extlibs/tinydtls/ecc/ecc.h

   1 /* Copyright 2014, Kenneth MacKay. Licensed under the BSD 2-clause license. */
   2
   3 #ifndef _MICRO_ECC_H_
   4 #define _MICRO_ECC_H_
   5
   6 #include <stdint.h>
   7
   8 /* Platform selection options.
   9 If uECC_PLATFORM is not defined, the code will try to guess it based on compiler macros.
  10 Possible values for uECC_PLATFORM are defined below: */
  11 #define uECC_arch_other 0
  12 #define uECC_x86        1
  13 #define uECC_x86_64     2
  14 #define uECC_arm        3
  15 #define uECC_arm_thumb  4
  16 #define uECC_avr        5
  17
  18 /* If desired, you can define uECC_WORD_SIZE as appropriate for your platform (1, 4, or 8 bytes).
  19 If uECC_WORD_SIZE is not explicitly defined then it will be automatically set based on your platform. */
  20
  21 /* Inline assembly options.
  22 uECC_asm_none  - Use standard C99 only.
  23 uECC_asm_small - Use GCC inline assembly for the target platform (if available), optimized for minimum size.
  24 uECC_asm_fast  - Use GCC inline assembly optimized for maximum speed. */
  25 #define uECC_asm_none  0
  26 #define uECC_asm_small 1
  27 #define uECC_asm_fast  2
  28 #ifndef uECC_ASM
  29     #define uECC_ASM uECC_asm_none//uECC_asm_fast
  30 #endif
  31
  32 /* Curve selection options. */
  33 #define uECC_secp160r1 1
  34 #define uECC_secp192r1 2
  35 #define uECC_secp256r1 3
  36 #define uECC_secp256k1 4
  37 #ifndef uECC_CURVE
  38     #define uECC_CURVE uECC_secp256r1
  39 #endif
  40
  41 /* uECC_SQUARE_FUNC - If enabled (defined as nonzero), this will cause a specific function to be used for (scalar) squaring
  42     instead of the generic multiplication function. This will make things faster by about 8% but increases the code size. */
  43 #define uECC_SQUARE_FUNC 1
  44
  45 #define uECC_CONCAT1(a, b) a##b
  46 #define uECC_CONCAT(a, b) uECC_CONCAT1(a, b)
  47
  48 #define uECC_size_1 20 /* secp160r1 */
  49 #define uECC_size_2 24 /* secp192r1 */
  50 #define uECC_size_3 32 /* secp256r1 */
  51 #define uECC_size_4 32 /* secp256k1 */
  52
  53 #define uECC_BYTES uECC_CONCAT(uECC_size_, uECC_CURVE)
  54
  55 #ifdef __cplusplus
  56 extern "C"
  57 {
  58 #endif
  59
  60 /* uECC_RNG_Function type
  61 The RNG function should fill p_size random bytes into p_dest. It should return 1 if
  62 p_dest was filled with random data, or 0 if the random data could not be generated.
  63 The filled-in values should be either truly random, or from a cryptographically-secure PRNG.
  64
  65 A correctly functioning RNG function must be set (using uECC_set_rng()) before calling
  66 uECC_make_key() or uECC_sign().
  67
  68 A correct RNG function is set by default when building for Windows, Linux, or OS X.
  69 If you are building on another POSIX-compliant system that supports /dev/random or /dev/urandom,
  70 you can define uECC_POSIX to use the predefined RNG. For embedded platforms there is no predefined
  71 RNG function; you must provide your own.
  72 */
  73 typedef int (*uECC_RNG_Function)(uint8_t *p_dest, unsigned p_size);
  74
  75 /* uECC_set_rng() function.
  76 Set the function that will be used to generate random bytes. The RNG function should
  77 return 1 if the random data was generated, or 0 if the random data could not be generated.
  78
  79 On platforms where there is no predefined RNG function (eg embedded platforms), this must
  80 be called before uECC_make_key() or uECC_sign() are used.
  81
  82 Inputs:
  83     p_rng  - The function that will be used to generate random bytes.
  84 */
  85 void uECC_set_rng(uECC_RNG_Function p_rng);
  86
  87 //////////////////////////////////////////
  88 // DTLS_CRYPTO_HAL
  89 /**
  90 * Call this function to create a unique public-private key pair in secure hardware
  91 *
  92 * @param[out] p_publicKey  The public key that is associated with the private key that was just created.
  93 * @param[out] p_privateKeyHandle  A handle that is used to point to the private key stored in hardware.
  94 * @return 1 upon success, 0 if an error occurred.
  95 */
  96 typedef int (*uECC_make_key_Function)(uint8_t p_publicKey[uECC_BYTES*2], uint8_t p_privateKeyHandle[uECC_BYTES]);
  97
  98 /**
  99 * Set the callback function that will be used to generate a public-private key pair.
 100 * This function will replace uECC_make_key.
 101 *
 102 * @param[in] p_make_key_cb  The function that will be used to generate a public-private key pair.
 103 */
 104 void uECC_set_make_key_cb(uECC_make_key_Function p_make_key_cb);
 105
 106 /**
 107 * Call this function to sign a hash using a hardware protected private key.
 108 *
 109 * @param[in] p_privateKeyHandle  A handle that is used to point to the private key stored in hardware.
 110 * @param[in] p_hash  The hash to sign.
 111 * @param[out] p_signature  The signature that is produced in hardware by the private key..
 112 * @return 1 upon success, 0 if an error occurred.
 113 */
 114 typedef int (*uECC_sign_Function)(uint8_t p_privateKeyHandle[uECC_BYTES], const uint8_t p_hash[uECC_BYTES], uint8_t p_signature[uECC_BYTES*2]);
 115
 116 /**
 117 * Set the callback function that will be used to sign.
 118 * This function will replace uECC_sign.
 119 *
 120 * @param[in] p_sign_cb  The function that will be used to sign.
 121 */
 122 void uECC_set_sign_cb(uECC_sign_Function p_sign_cb);
 123
 124 /**
 125 * Call this function to verify a signature using the public key and hash that was signed.
 126 *
 127 * @param[in] p_publicKey  The public key that is associated with the private key that produced the signature.
 128 * @param[in] p_hash  The hash that was signed.
 129 * @param[in] p_signature  The signature that was produced the private key that is associated with p_public_key
 130 * @return 1 upon success, 0 if an error occurred.
 131 */
 132 typedef int (*uECC_verify_Function)(const uint8_t p_publicKey[uECC_BYTES*2], const uint8_t p_hash[uECC_BYTES], const uint8_t p_signature[uECC_BYTES*2]);
 133
 134 /**
 135 * Set the callback function that will be used to verify.
 136 * This function will replace uECC_verify.
 137 *
 138 * @param[in] p_verify_cb  The function that will be used to verify.
 139 */
 140 void uECC_set_verify_cb(uECC_verify_Function p_verify_cb);
 141
 142 /**
 143 * Call this function to produce an ECDH shared key using the public key of the other node.
 144 * A hardware protected private key will be used for the point multiply
 145 *
 146 * @param[in] p_publicKey  The public key from the other node used for communication.
 147 * @param[in] p_privateKeyHandle  A handle that is used to point to the private key stored in hardware.
 148 * @param[out] p_secret  The pre-master key that is produced by the point multiply with p_public_key and our private key
 149 * @return 1 upon success, 0 if an error occurred.
 150 */
 151 typedef int (*uECC_shared_secret_Function)(const uint8_t p_publicKey[uECC_BYTES*2], const uint8_t p_privateKeyHandle[uECC_BYTES], uint8_t p_secret[uECC_BYTES]);
 152
 153 /**
 154 * Set the callback function that will be used to produce a shared secret.
 155 * This function will replace uECC_shared_secret.
 156 *
 157 * @param[in] p_make_key_cb  The function that will be used to generate the shared secret.
 158 */
 159 void uECC_set_shared_secret_cb(uECC_shared_secret_Function p_shared_secret_cb);
 160
 161 /**
 162 * Call this function to produce a shared key using the public key of the other node.
 163 * An ephemeral private key will be created in secure hardware that will be used for the point multiply
 164 *
 165 * @param[in] p_public_key  The public key from the other node used for communication.
 166 * @param[out] p_public_key_out  The ephemeral public key that will be used in the point multiply.
 167 * @param[out] p_secret  The pre-master key that is produced by the point multiply with p_public_key and our private key
 168 * @return 1 upon success, 0 if an error occurred.
 169 */
 170 typedef int (*uECC_ecdhe_Function)(const uint8_t p_public_key_in[uECC_BYTES*2],
 171                                    uint8_t p_public_key_out[uECC_BYTES*2],
 172                                    uint8_t p_secret[uECC_BYTES]);
 173
 174 /**
 175 * Set the callback function that will be used to produce a ECDHE shared secret.
 176 *
 177 * @param[in] p_ecdhe_cb  The function that will be used to generate the ECDHE shared secret.
 178 */
 179 void uECC_set_ecdhe_cb(uECC_ecdhe_Function p_ecdhe_cb);
 180
 181 /**
 182 * Call this function to return the public key for an existing private key.
 183 *
 184 * @param[out] p_key_handle  A handle that is used to point to the private key stored in hardware.
 185 *    The public key that is associated with this private key will be returned
 186 * @param[out] p_public_key  The public key that is associated with the private key that was just created.
 187 * @return 1 upon success, 0 if an error occurred.
 188 */
 189 typedef int (*uECC_get_pubkey_Function)(const uint8_t p_key_handle[uECC_BYTES],
 190                                         uint8_t p_public_key[uECC_BYTES*2]);
 191
 192 /**
 193 * Set the callback function that will be used to return the public key for an existing private key.
 194 *
 195 * @param[in] p_get_pubkey_cb  The function that will be used to return the public key for an existing private key.
 196 */
 197 void uECC_set_get_pubkey_cb(uECC_get_pubkey_Function p_get_pubkey_cb);
 198
 199
 200 /**
 201 * Call this function to produce a shared key using the public key of the other node.
 202 * An ephemeral private key will be created that will be used for the point multiply
 203 *
 204 * @param[in] p_public_key  The public key from the other node used for communication.
 205 * @param[out] p_public_key_out  The ephemeral public key that will be used in the point multiply.
 206 * @param[out] p_secret  The pre-master key that is produced by the point multiply with p_public_key and our private key
 207 * @return 1 upon success, 0 if an error occurred.
 208 */
 209 int uECC_ecdhe(const uint8_t p_public_key_in[uECC_BYTES*2],
 210                uint8_t p_public_key_out[uECC_BYTES*2],
 211                uint8_t p_secret[uECC_BYTES]);
 212
 213 /**
 214 * Call this function to return the public key for an existing private key.
 215 *
 216 * @param[out] p_key_handle  A handle that is used to point to the private key stored in hardware.
 217 *    The public key that is associated with this private key will be returned
 218 * @param[out] p_public_key  The public key that is associated with the private key that was just created.
 219 * @return 1 upon success, 0 if an error occurred.
 220 */
 221 int uECC_get_pubkey(const uint8_t p_key_handle[uECC_BYTES],
 222                     uint8_t p_public_key[uECC_BYTES*2]);
 223
 224 //////////////////////////////////////////
 225
 226
 227 /* uECC_make_key() function.
 228 Create a public/private key pair.
 229
 230 Outputs:
 231     p_publicKey  - Will be filled in with the public key.
 232     p_privateKey - Will be filled in with the private key.
 233
 234 Returns 1 if the key pair was generated successfully, 0 if an error occurred.
 235 */
 236 int uECC_make_key(uint8_t p_publicKey[uECC_BYTES*2], uint8_t p_privateKey[uECC_BYTES]);
 237
 238 /* uECC_shared_secret() function.
 239 Compute a shared secret given your secret key and someone else's public key.
 240 Note: It is recommended that you hash the result of uECC_shared_secret() before using it for symmetric encryption or HMAC.
 241
 242 Inputs:
 243     p_publicKey  - The public key of the remote party.
 244     p_privateKey - Your private key.
 245
 246 Outputs:
 247     p_secret - Will be filled in with the shared secret value.
 248
 249 Returns 1 if the shared secret was generated successfully, 0 if an error occurred.
 250 */
 251 int uECC_shared_secret(const uint8_t p_publicKey[uECC_BYTES*2], const uint8_t p_privateKey[uECC_BYTES], uint8_t p_secret[uECC_BYTES]);
 252
 253 /* uECC_compress() function.
 254 Compress a public key.
 255
 256 Inputs:
 257     p_publicKey - The public key to compress.
 258
 259 Outputs:
 260     p_compressed - Will be filled in with the compressed public key.
 261 */
 262 void uECC_compress(const uint8_t p_publicKey[uECC_BYTES*2], uint8_t p_compressed[uECC_BYTES+1]);
 263
 264 /* uECC_decompress() function.
 265 Decompress a compressed public key.
 266
 267 Inputs:
 268     p_compressed - The compressed public key.
 269
 270 Outputs:
 271     p_publicKey - Will be filled in with the decompressed public key.
 272 */
 273 void uECC_decompress(const uint8_t p_compressed[uECC_BYTES+1], uint8_t p_publicKey[uECC_BYTES*2]);
 274
 275 /* uECC_sign() function.
 276 Generate an ECDSA signature for a given hash value.
 277
 278 Usage: Compute a hash of the data you wish to sign (SHA-2 is recommended) and pass it in to
 279 this function along with your private key.
 280
 281 Inputs:
 282     p_privateKey - Your private key.
 283     p_hash       - The message hash to sign.
 284
 285 Outputs:
 286     p_signature  - Will be filled in with the signature value.
 287
 288 Returns 1 if the signature generated successfully, 0 if an error occurred.
 289 */
 290 int uECC_sign(const uint8_t p_privateKey[uECC_BYTES], const uint8_t p_hash[uECC_BYTES], uint8_t p_signature[uECC_BYTES*2]);
 291
 292 /* uECC_verify() function.
 293 Verify an ECDSA signature.
 294
 295 Usage: Compute the hash of the signed data using the same hash as the signer and
 296 pass it to this function along with the signer's public key and the signature values (r and s).
 297
 298 Inputs:
 299     p_publicKey - The signer's public key
 300     p_hash      - The hash of the signed data.
 301     p_signature - The signature value.
 302
 303 Returns 1 if the signature is valid, 0 if it is invalid.
 304 */
 305 int uECC_verify(const uint8_t p_publicKey[uECC_BYTES*2], const uint8_t p_hash[uECC_BYTES], const uint8_t p_signature[uECC_BYTES*2]);
 306
 307 #ifdef __cplusplus
 308 } /* end of extern "C" */
 309 #endif
 310
 311 #endif /* _MICRO_ECC_H_ */