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