1 /** 2 * \file ecdh.h 3 * 4 * \brief This file contains ECDH definitions and functions. 5 * 6 * The Elliptic Curve Diffie-Hellman (ECDH) protocol is an anonymous 7 * key agreement protocol allowing two parties to establish a shared 8 * secret over an insecure channel. Each party must have an 9 * elliptic-curve public–private key pair. 10 * 11 * For more information, see <em>NIST SP 800-56A Rev. 2: Recommendation for 12 * Pair-Wise Key Establishment Schemes Using Discrete Logarithm 13 * Cryptography</em>. 14 */ 15 /* 16 * Copyright The Mbed TLS Contributors 17 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 18 */ 19 20 #ifndef MBEDTLS_ECDH_H 21 #define MBEDTLS_ECDH_H 22 23 #if !defined(MBEDTLS_CONFIG_FILE) 24 #include "mbedtls/config.h" 25 #else 26 #include MBEDTLS_CONFIG_FILE 27 #endif 28 29 #include "mbedtls/ecp.h" 30 31 #if defined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED) 32 #undef MBEDTLS_ECDH_LEGACY_CONTEXT 33 #include "everest/everest.h" 34 #endif 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /** 41 * Defines the source of the imported EC key. 42 */ 43 typedef enum { 44 MBEDTLS_ECDH_OURS, /**< Our key. */ 45 MBEDTLS_ECDH_THEIRS, /**< The key of the peer. */ 46 } mbedtls_ecdh_side; 47 48 #if !defined(MBEDTLS_ECDH_LEGACY_CONTEXT) 49 /** 50 * Defines the ECDH implementation used. 51 * 52 * Later versions of the library may add new variants, therefore users should 53 * not make any assumptions about them. 54 */ 55 typedef enum { 56 MBEDTLS_ECDH_VARIANT_NONE = 0, /*!< Implementation not defined. */ 57 MBEDTLS_ECDH_VARIANT_MBEDTLS_2_0,/*!< The default Mbed TLS implementation */ 58 #if defined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED) 59 MBEDTLS_ECDH_VARIANT_EVEREST /*!< Everest implementation */ 60 #endif 61 } mbedtls_ecdh_variant; 62 63 /** 64 * The context used by the default ECDH implementation. 65 * 66 * Later versions might change the structure of this context, therefore users 67 * should not make any assumptions about the structure of 68 * mbedtls_ecdh_context_mbed. 69 */ 70 typedef struct mbedtls_ecdh_context_mbed { 71 mbedtls_ecp_group grp; /*!< The elliptic curve used. */ 72 mbedtls_mpi d; /*!< The private key. */ 73 mbedtls_ecp_point Q; /*!< The public key. */ 74 mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */ 75 mbedtls_mpi z; /*!< The shared secret. */ 76 #if defined(MBEDTLS_ECP_RESTARTABLE) 77 mbedtls_ecp_restart_ctx rs; /*!< The restart context for EC computations. */ 78 #endif 79 } mbedtls_ecdh_context_mbed; 80 #endif 81 82 /** 83 * 84 * \warning Performing multiple operations concurrently on the same 85 * ECDSA context is not supported; objects of this type 86 * should not be shared between multiple threads. 87 * \brief The ECDH context structure. 88 */ 89 typedef struct mbedtls_ecdh_context { 90 #if defined(MBEDTLS_ECDH_LEGACY_CONTEXT) 91 mbedtls_ecp_group grp; /*!< The elliptic curve used. */ 92 mbedtls_mpi d; /*!< The private key. */ 93 mbedtls_ecp_point Q; /*!< The public key. */ 94 mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */ 95 mbedtls_mpi z; /*!< The shared secret. */ 96 int point_format; /*!< The format of point export in TLS messages. */ 97 mbedtls_ecp_point Vi; /*!< The blinding value. */ 98 mbedtls_ecp_point Vf; /*!< The unblinding value. */ 99 mbedtls_mpi _d; /*!< The previous \p d. */ 100 #if defined(MBEDTLS_ECP_RESTARTABLE) 101 int restart_enabled; /*!< The flag for restartable mode. */ 102 mbedtls_ecp_restart_ctx rs; /*!< The restart context for EC computations. */ 103 #endif /* MBEDTLS_ECP_RESTARTABLE */ 104 #else 105 uint8_t point_format; /*!< The format of point export in TLS messages 106 as defined in RFC 4492. */ 107 mbedtls_ecp_group_id grp_id;/*!< The elliptic curve used. */ 108 mbedtls_ecdh_variant var; /*!< The ECDH implementation/structure used. */ 109 union { 110 mbedtls_ecdh_context_mbed mbed_ecdh; 111 #if defined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED) 112 mbedtls_ecdh_context_everest everest_ecdh; 113 #endif 114 } ctx; /*!< Implementation-specific context. The 115 context in use is specified by the \c var 116 field. */ 117 #if defined(MBEDTLS_ECP_RESTARTABLE) 118 uint8_t restart_enabled; /*!< The flag for restartable mode. Functions of 119 an alternative implementation not supporting 120 restartable mode must return 121 MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED error 122 if this flag is set. */ 123 #endif /* MBEDTLS_ECP_RESTARTABLE */ 124 #endif /* MBEDTLS_ECDH_LEGACY_CONTEXT */ 125 } 126 mbedtls_ecdh_context; 127 128 /** 129 * \brief Check whether a given group can be used for ECDH. 130 * 131 * \param gid The ECP group ID to check. 132 * 133 * \return \c 1 if the group can be used, \c 0 otherwise 134 */ 135 int mbedtls_ecdh_can_do(mbedtls_ecp_group_id gid); 136 137 /** 138 * \brief This function generates an ECDH keypair on an elliptic 139 * curve. 140 * 141 * This function performs the first of two core computations 142 * implemented during the ECDH key exchange. The second core 143 * computation is performed by mbedtls_ecdh_compute_shared(). 144 * 145 * \see ecp.h 146 * 147 * \param grp The ECP group to use. This must be initialized and have 148 * domain parameters loaded, for example through 149 * mbedtls_ecp_load() or mbedtls_ecp_tls_read_group(). 150 * \param d The destination MPI (private key). 151 * This must be initialized. 152 * \param Q The destination point (public key). 153 * This must be initialized. 154 * \param f_rng The RNG function to use. This must not be \c NULL. 155 * \param p_rng The RNG context to be passed to \p f_rng. This may be 156 * \c NULL in case \p f_rng doesn't need a context argument. 157 * 158 * \return \c 0 on success. 159 * \return Another \c MBEDTLS_ERR_ECP_XXX or 160 * \c MBEDTLS_MPI_XXX error code on failure. 161 */ 162 int mbedtls_ecdh_gen_public(mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q, 163 int (*f_rng)(void *, unsigned char *, size_t), 164 void *p_rng); 165 166 /** 167 * \brief This function computes the shared secret. 168 * 169 * This function performs the second of two core computations 170 * implemented during the ECDH key exchange. The first core 171 * computation is performed by mbedtls_ecdh_gen_public(). 172 * 173 * \see ecp.h 174 * 175 * \note If \p f_rng is not NULL, it is used to implement 176 * countermeasures against side-channel attacks. 177 * For more information, see mbedtls_ecp_mul(). 178 * 179 * \param grp The ECP group to use. This must be initialized and have 180 * domain parameters loaded, for example through 181 * mbedtls_ecp_load() or mbedtls_ecp_tls_read_group(). 182 * \param z The destination MPI (shared secret). 183 * This must be initialized. 184 * \param Q The public key from another party. 185 * This must be initialized. 186 * \param d Our secret exponent (private key). 187 * This must be initialized. 188 * \param f_rng The RNG function. This may be \c NULL if randomization 189 * of intermediate results during the ECP computations is 190 * not needed (discouraged). See the documentation of 191 * mbedtls_ecp_mul() for more. 192 * \param p_rng The RNG context to be passed to \p f_rng. This may be 193 * \c NULL if \p f_rng is \c NULL or doesn't need a 194 * context argument. 195 * 196 * \return \c 0 on success. 197 * \return Another \c MBEDTLS_ERR_ECP_XXX or 198 * \c MBEDTLS_MPI_XXX error code on failure. 199 */ 200 int mbedtls_ecdh_compute_shared(mbedtls_ecp_group *grp, mbedtls_mpi *z, 201 const mbedtls_ecp_point *Q, const mbedtls_mpi *d, 202 int (*f_rng)(void *, unsigned char *, size_t), 203 void *p_rng); 204 205 /** 206 * \brief This function initializes an ECDH context. 207 * 208 * \param ctx The ECDH context to initialize. This must not be \c NULL. 209 */ 210 void mbedtls_ecdh_init(mbedtls_ecdh_context *ctx); 211 212 /** 213 * \brief This function sets up the ECDH context with the information 214 * given. 215 * 216 * This function should be called after mbedtls_ecdh_init() but 217 * before mbedtls_ecdh_make_params(). There is no need to call 218 * this function before mbedtls_ecdh_read_params(). 219 * 220 * This is the first function used by a TLS server for ECDHE 221 * ciphersuites. 222 * 223 * \param ctx The ECDH context to set up. This must be initialized. 224 * \param grp_id The group id of the group to set up the context for. 225 * 226 * \return \c 0 on success. 227 */ 228 int mbedtls_ecdh_setup(mbedtls_ecdh_context *ctx, 229 mbedtls_ecp_group_id grp_id); 230 231 /** 232 * \brief This function frees a context. 233 * 234 * \param ctx The context to free. This may be \c NULL, in which 235 * case this function does nothing. If it is not \c NULL, 236 * it must point to an initialized ECDH context. 237 */ 238 void mbedtls_ecdh_free(mbedtls_ecdh_context *ctx); 239 240 /** 241 * \brief This function generates an EC key pair and exports its 242 * in the format used in a TLS ServerKeyExchange handshake 243 * message. 244 * 245 * This is the second function used by a TLS server for ECDHE 246 * ciphersuites. (It is called after mbedtls_ecdh_setup().) 247 * 248 * \see ecp.h 249 * 250 * \param ctx The ECDH context to use. This must be initialized 251 * and bound to a group, for example via mbedtls_ecdh_setup(). 252 * \param olen The address at which to store the number of Bytes written. 253 * \param buf The destination buffer. This must be a writable buffer of 254 * length \p blen Bytes. 255 * \param blen The length of the destination buffer \p buf in Bytes. 256 * \param f_rng The RNG function to use. This must not be \c NULL. 257 * \param p_rng The RNG context to be passed to \p f_rng. This may be 258 * \c NULL in case \p f_rng doesn't need a context argument. 259 * 260 * \return \c 0 on success. 261 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of 262 * operations was reached: see \c mbedtls_ecp_set_max_ops(). 263 * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure. 264 */ 265 int mbedtls_ecdh_make_params(mbedtls_ecdh_context *ctx, size_t *olen, 266 unsigned char *buf, size_t blen, 267 int (*f_rng)(void *, unsigned char *, size_t), 268 void *p_rng); 269 270 /** 271 * \brief This function parses the ECDHE parameters in a 272 * TLS ServerKeyExchange handshake message. 273 * 274 * \note In a TLS handshake, this is the how the client 275 * sets up its ECDHE context from the server's public 276 * ECDHE key material. 277 * 278 * \see ecp.h 279 * 280 * \param ctx The ECDHE context to use. This must be initialized. 281 * \param buf On input, \c *buf must be the start of the input buffer. 282 * On output, \c *buf is updated to point to the end of the 283 * data that has been read. On success, this is the first byte 284 * past the end of the ServerKeyExchange parameters. 285 * On error, this is the point at which an error has been 286 * detected, which is usually not useful except to debug 287 * failures. 288 * \param end The end of the input buffer. 289 * 290 * \return \c 0 on success. 291 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure. 292 * 293 */ 294 int mbedtls_ecdh_read_params(mbedtls_ecdh_context *ctx, 295 const unsigned char **buf, 296 const unsigned char *end); 297 298 /** 299 * \brief This function sets up an ECDH context from an EC key. 300 * 301 * It is used by clients and servers in place of the 302 * ServerKeyEchange for static ECDH, and imports ECDH 303 * parameters from the EC key information of a certificate. 304 * 305 * \see ecp.h 306 * 307 * \param ctx The ECDH context to set up. This must be initialized. 308 * \param key The EC key to use. This must be initialized. 309 * \param side Defines the source of the key. Possible values are: 310 * - #MBEDTLS_ECDH_OURS: The key is ours. 311 * - #MBEDTLS_ECDH_THEIRS: The key is that of the peer. 312 * 313 * \return \c 0 on success. 314 * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure. 315 * 316 */ 317 int mbedtls_ecdh_get_params(mbedtls_ecdh_context *ctx, 318 const mbedtls_ecp_keypair *key, 319 mbedtls_ecdh_side side); 320 321 /** 322 * \brief This function generates a public key and exports it 323 * as a TLS ClientKeyExchange payload. 324 * 325 * This is the second function used by a TLS client for ECDH(E) 326 * ciphersuites. 327 * 328 * \see ecp.h 329 * 330 * \param ctx The ECDH context to use. This must be initialized 331 * and bound to a group, the latter usually by 332 * mbedtls_ecdh_read_params(). 333 * \param olen The address at which to store the number of Bytes written. 334 * This must not be \c NULL. 335 * \param buf The destination buffer. This must be a writable buffer 336 * of length \p blen Bytes. 337 * \param blen The size of the destination buffer \p buf in Bytes. 338 * \param f_rng The RNG function to use. This must not be \c NULL. 339 * \param p_rng The RNG context to be passed to \p f_rng. This may be 340 * \c NULL in case \p f_rng doesn't need a context argument. 341 * 342 * \return \c 0 on success. 343 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of 344 * operations was reached: see \c mbedtls_ecp_set_max_ops(). 345 * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure. 346 */ 347 int mbedtls_ecdh_make_public(mbedtls_ecdh_context *ctx, size_t *olen, 348 unsigned char *buf, size_t blen, 349 int (*f_rng)(void *, unsigned char *, size_t), 350 void *p_rng); 351 352 /** 353 * \brief This function parses and processes the ECDHE payload of a 354 * TLS ClientKeyExchange message. 355 * 356 * This is the third function used by a TLS server for ECDH(E) 357 * ciphersuites. (It is called after mbedtls_ecdh_setup() and 358 * mbedtls_ecdh_make_params().) 359 * 360 * \see ecp.h 361 * 362 * \param ctx The ECDH context to use. This must be initialized 363 * and bound to a group, for example via mbedtls_ecdh_setup(). 364 * \param buf The pointer to the ClientKeyExchange payload. This must 365 * be a readable buffer of length \p blen Bytes. 366 * \param blen The length of the input buffer \p buf in Bytes. 367 * 368 * \return \c 0 on success. 369 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure. 370 */ 371 int mbedtls_ecdh_read_public(mbedtls_ecdh_context *ctx, 372 const unsigned char *buf, size_t blen); 373 374 /** 375 * \brief This function derives and exports the shared secret. 376 * 377 * This is the last function used by both TLS client 378 * and servers. 379 * 380 * \note If \p f_rng is not NULL, it is used to implement 381 * countermeasures against side-channel attacks. 382 * For more information, see mbedtls_ecp_mul(). 383 * 384 * \see ecp.h 385 386 * \param ctx The ECDH context to use. This must be initialized 387 * and have its own private key generated and the peer's 388 * public key imported. 389 * \param olen The address at which to store the total number of 390 * Bytes written on success. This must not be \c NULL. 391 * \param buf The buffer to write the generated shared key to. This 392 * must be a writable buffer of size \p blen Bytes. 393 * \param blen The length of the destination buffer \p buf in Bytes. 394 * \param f_rng The RNG function, for blinding purposes. This may 395 * b \c NULL if blinding isn't needed. 396 * \param p_rng The RNG context. This may be \c NULL if \p f_rng 397 * doesn't need a context argument. 398 * 399 * \return \c 0 on success. 400 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of 401 * operations was reached: see \c mbedtls_ecp_set_max_ops(). 402 * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure. 403 */ 404 int mbedtls_ecdh_calc_secret(mbedtls_ecdh_context *ctx, size_t *olen, 405 unsigned char *buf, size_t blen, 406 int (*f_rng)(void *, unsigned char *, size_t), 407 void *p_rng); 408 409 #if defined(MBEDTLS_ECP_RESTARTABLE) 410 /** 411 * \brief This function enables restartable EC computations for this 412 * context. (Default: disabled.) 413 * 414 * \see \c mbedtls_ecp_set_max_ops() 415 * 416 * \note It is not possible to safely disable restartable 417 * computations once enabled, except by free-ing the context, 418 * which cancels possible in-progress operations. 419 * 420 * \param ctx The ECDH context to use. This must be initialized. 421 */ 422 void mbedtls_ecdh_enable_restart(mbedtls_ecdh_context *ctx); 423 #endif /* MBEDTLS_ECP_RESTARTABLE */ 424 425 #ifdef __cplusplus 426 } 427 #endif 428 429 #endif /* ecdh.h */ 430