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