Hacl_P384.h (8494B)
1 /* MIT License 2 * 3 * Copyright (c) 2016-2022 INRIA, CMU and Microsoft Corporation 4 * Copyright (c) 2022-2023 HACL* Contributors 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to deal 8 * in the Software without restriction, including without limitation the rights 9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 10 * copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in all 14 * copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 22 * SOFTWARE. 23 */ 24 25 #ifndef __Hacl_P384_H 26 #define __Hacl_P384_H 27 28 #if defined(__cplusplus) 29 extern "C" { 30 #endif 31 32 #include <string.h> 33 #include "krml/internal/types.h" 34 #include "krml/lowstar_endianness.h" 35 36 #include "lib_intrinsics.h" 37 38 /******************************************************************************* 39 40 Verified C library for ECDSA and ECDH functions over the P-384 NIST curve. 41 42 This module implements signing and verification, key validation, conversions 43 between various point representations, and ECDH key agreement. 44 45 *******************************************************************************/ 46 47 /*****************/ 48 /* ECDSA signing */ 49 /*****************/ 50 51 /** 52 Create an ECDSA signature WITHOUT hashing first. 53 54 This function is intended to receive a hash of the input. 55 For convenience, we recommend using one of the hash-and-sign combined functions above. 56 57 The argument `msg` MUST be at least 32 bytes (i.e. `msg_len >= 32`). 58 59 NOTE: The equivalent functions in OpenSSL and Fiat-Crypto both accept inputs 60 smaller than 32 bytes. These libraries left-pad the input with enough zeroes to 61 reach the minimum 32 byte size. Clients who need behavior identical to OpenSSL 62 need to perform the left-padding themselves. 63 64 The function returns `true` for successful creation of an ECDSA signature and `false` otherwise. 65 66 The outparam `signature` (R || S) points to 64 bytes of valid memory, i.e., uint8_t[64]. 67 The argument `msg` points to `msg_len` bytes of valid memory, i.e., uint8_t[msg_len]. 68 The arguments `private_key` and `nonce` point to 32 bytes of valid memory, i.e., uint8_t[32]. 69 70 The function also checks whether `private_key` and `nonce` are valid values: 71 • 0 < `private_key` < the order of the curve 72 • 0 < `nonce` < the order of the curve 73 */ 74 bool 75 Hacl_P384_ecdsa_sign_p384_without_hash( 76 uint8_t *signature, 77 uint32_t msg_len, 78 uint8_t *msg, 79 uint8_t *private_key, 80 uint8_t *nonce); 81 82 /**********************/ 83 /* ECDSA verification */ 84 /**********************/ 85 86 /** 87 Verify an ECDSA signature WITHOUT hashing first. 88 89 This function is intended to receive a hash of the input. 90 For convenience, we recommend using one of the hash-and-verify combined functions above. 91 92 The argument `msg` MUST be at least 32 bytes (i.e. `msg_len >= 32`). 93 94 The function returns `true` if the signature is valid and `false` otherwise. 95 96 The argument `msg` points to `msg_len` bytes of valid memory, i.e., uint8_t[msg_len]. 97 The argument `public_key` (x || y) points to 64 bytes of valid memory, i.e., uint8_t[64]. 98 The arguments `signature_r` and `signature_s` point to 32 bytes of valid memory, i.e., uint8_t[32]. 99 100 The function also checks whether `public_key` is valid 101 */ 102 bool 103 Hacl_P384_ecdsa_verif_without_hash( 104 uint32_t msg_len, 105 uint8_t *msg, 106 uint8_t *public_key, 107 uint8_t *signature_r, 108 uint8_t *signature_s); 109 110 /******************/ 111 /* Key validation */ 112 /******************/ 113 114 /** 115 Public key validation. 116 117 The function returns `true` if a public key is valid and `false` otherwise. 118 119 The argument `public_key` points to 64 bytes of valid memory, i.e., uint8_t[64]. 120 121 The public key (x || y) is valid (with respect to SP 800-56A): 122 • the public key is not the “point at infinity”, represented as O. 123 • the affine x and y coordinates of the point represented by the public key are 124 in the range [0, p – 1] where p is the prime defining the finite field. 125 • y^2 = x^3 + ax + b where a and b are the coefficients of the curve equation. 126 The last extract is taken from: https://neilmadden.blog/2017/05/17/so-how-do-you-validate-nist-ecdh-public-keys/ 127 */ 128 bool Hacl_P384_validate_public_key(uint8_t *public_key); 129 130 /** 131 Private key validation. 132 133 The function returns `true` if a private key is valid and `false` otherwise. 134 135 The argument `private_key` points to 32 bytes of valid memory, i.e., uint8_t[32]. 136 137 The private key is valid: 138 • 0 < `private_key` < the order of the curve 139 */ 140 bool Hacl_P384_validate_private_key(uint8_t *private_key); 141 142 /******************************************************************************* 143 Parsing and Serializing public keys. 144 145 A public key is a point (x, y) on the P-384 NIST curve. 146 147 The point can be represented in the following three ways. 148 • raw = [ x || y ], 64 bytes 149 • uncompressed = [ 0x04 || x || y ], 65 bytes 150 • compressed = [ (0x02 for even `y` and 0x03 for odd `y`) || x ], 33 bytes 151 152 *******************************************************************************/ 153 154 /** 155 Convert a public key from uncompressed to its raw form. 156 157 The function returns `true` for successful conversion of a public key and `false` otherwise. 158 159 The outparam `pk_raw` points to 64 bytes of valid memory, i.e., uint8_t[64]. 160 The argument `pk` points to 65 bytes of valid memory, i.e., uint8_t[65]. 161 162 The function DOESN'T check whether (x, y) is a valid point. 163 */ 164 bool Hacl_P384_uncompressed_to_raw(uint8_t *pk, uint8_t *pk_raw); 165 166 /** 167 Convert a public key from compressed to its raw form. 168 169 The function returns `true` for successful conversion of a public key and `false` otherwise. 170 171 The outparam `pk_raw` points to 64 bytes of valid memory, i.e., uint8_t[64]. 172 The argument `pk` points to 33 bytes of valid memory, i.e., uint8_t[33]. 173 174 The function also checks whether (x, y) is a valid point. 175 */ 176 bool Hacl_P384_compressed_to_raw(uint8_t *pk, uint8_t *pk_raw); 177 178 /** 179 Convert a public key from raw to its uncompressed form. 180 181 The outparam `pk` points to 65 bytes of valid memory, i.e., uint8_t[65]. 182 The argument `pk_raw` points to 64 bytes of valid memory, i.e., uint8_t[64]. 183 184 The function DOESN'T check whether (x, y) is a valid point. 185 */ 186 void Hacl_P384_raw_to_uncompressed(uint8_t *pk_raw, uint8_t *pk); 187 188 /** 189 Convert a public key from raw to its compressed form. 190 191 The outparam `pk` points to 33 bytes of valid memory, i.e., uint8_t[33]. 192 The argument `pk_raw` points to 64 bytes of valid memory, i.e., uint8_t[64]. 193 194 The function DOESN'T check whether (x, y) is a valid point. 195 */ 196 void Hacl_P384_raw_to_compressed(uint8_t *pk_raw, uint8_t *pk); 197 198 /******************/ 199 /* ECDH agreement */ 200 /******************/ 201 202 /** 203 Compute the public key from the private key. 204 205 The function returns `true` if a private key is valid and `false` otherwise. 206 207 The outparam `public_key` points to 64 bytes of valid memory, i.e., uint8_t[64]. 208 The argument `private_key` points to 32 bytes of valid memory, i.e., uint8_t[32]. 209 210 The private key is valid: 211 • 0 < `private_key` < the order of the curve. 212 */ 213 bool Hacl_P384_dh_initiator(uint8_t *public_key, uint8_t *private_key); 214 215 /** 216 Execute the diffie-hellmann key exchange. 217 218 The function returns `true` for successful creation of an ECDH shared secret and 219 `false` otherwise. 220 221 The outparam `shared_secret` points to 64 bytes of valid memory, i.e., uint8_t[64]. 222 The argument `their_pubkey` points to 64 bytes of valid memory, i.e., uint8_t[64]. 223 The argument `private_key` points to 32 bytes of valid memory, i.e., uint8_t[32]. 224 225 The function also checks whether `private_key` and `their_pubkey` are valid. 226 */ 227 bool 228 Hacl_P384_dh_responder(uint8_t *shared_secret, uint8_t *their_pubkey, uint8_t *private_key); 229 230 #if defined(__cplusplus) 231 } 232 #endif 233 234 #define __Hacl_P384_H_DEFINED 235 #endif