common/mbedtls/ecdh.h

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