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