ecdh.h

00001 /**
00002  * \file ecdh.h
00003  *
00004  * \brief This file contains ECDH definitions and functions.
00005  *
00006  * The Elliptic Curve Diffie-Hellman (ECDH) protocol is an anonymous
00007  * key agreement protocol allowing two parties to establish a shared
00008  * secret over an insecure channel. Each party must have an
00009  * elliptic-curve public–private key pair.
00010  *
00011  * For more information, see <em>NIST SP 800-56A Rev. 2: Recommendation for
00012  * Pair-Wise Key Establishment Schemes Using Discrete Logarithm
00013  * Cryptography</em>.
00014  */
00015 /*
00016  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
00017  *  SPDX-License-Identifier: Apache-2.0
00018  *
00019  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00020  *  not use this file except in compliance with the License.
00021  *  You may obtain a copy of the License at
00022  *
00023  *  http://www.apache.org/licenses/LICENSE-2.0
00024  *
00025  *  Unless required by applicable law or agreed to in writing, software
00026  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00027  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00028  *  See the License for the specific language governing permissions and
00029  *  limitations under the License.
00030  *
00031  *  This file is part of Mbed TLS (https://tls.mbed.org)
00032  */
00033 
00034 #ifndef MBEDTLS_ECDH_H
00035 #define MBEDTLS_ECDH_H
00036 
00037 #if !defined(MBEDTLS_CONFIG_FILE)
00038 #include "mbedtls/config.h"
00039 #else
00040 #include MBEDTLS_CONFIG_FILE
00041 #endif
00042 
00043 #include "mbedtls/ecp.h"
00044 
00045 #if defined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED)
00046 #undef MBEDTLS_ECDH_LEGACY_CONTEXT
00047 #include "everest/everest.h"
00048 #endif
00049 
00050 #ifdef __cplusplus
00051 extern "C" {
00052 #endif
00053 
00054 /**
00055  * Defines the source of the imported EC key.
00056  */
00057 typedef enum
00058 {
00059     MBEDTLS_ECDH_OURS,   /**< Our key. */
00060     MBEDTLS_ECDH_THEIRS, /**< The key of the peer. */
00061 } mbedtls_ecdh_side;
00062 
00063 #if !defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
00064 /**
00065  * Defines the ECDH implementation used.
00066  *
00067  * Later versions of the library may add new variants, therefore users should
00068  * not make any assumptions about them.
00069  */
00070 typedef enum
00071 {
00072     MBEDTLS_ECDH_VARIANT_NONE  = 0,   /*!< Implementation not defined. */
00073     MBEDTLS_ECDH_VARIANT_MBEDTLS_2_0 ,/*!< The default Mbed TLS implementation */
00074 #if defined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED)
00075     MBEDTLS_ECDH_VARIANT_EVEREST      /*!< Everest implementation */
00076 #endif
00077 } mbedtls_ecdh_variant;
00078 
00079 /**
00080  * The context used by the default ECDH implementation.
00081  *
00082  * Later versions might change the structure of this context, therefore users
00083  * should not make any assumptions about the structure of
00084  * mbedtls_ecdh_context_mbed.
00085  */
00086 typedef struct mbedtls_ecdh_context_mbed
00087 {
00088     mbedtls_ecp_group grp ;   /*!< The elliptic curve used. */
00089     mbedtls_mpi d ;           /*!< The private key. */
00090     mbedtls_ecp_point Q ;     /*!< The public key. */
00091     mbedtls_ecp_point Qp ;    /*!< The value of the public key of the peer. */
00092     mbedtls_mpi z ;           /*!< The shared secret. */
00093 #if defined(MBEDTLS_ECP_RESTARTABLE)
00094     mbedtls_ecp_restart_ctx rs ; /*!< The restart context for EC computations. */
00095 #endif
00096 } mbedtls_ecdh_context_mbed;
00097 #endif
00098 
00099 /**
00100  *
00101  * \warning         Performing multiple operations concurrently on the same
00102  *                  ECDSA context is not supported; objects of this type
00103  *                  should not be shared between multiple threads.
00104  * \brief           The ECDH context structure.
00105  */
00106 typedef struct mbedtls_ecdh_context
00107 {
00108 #if defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
00109     mbedtls_ecp_group grp ;   /*!< The elliptic curve used. */
00110     mbedtls_mpi d ;           /*!< The private key. */
00111     mbedtls_ecp_point Q ;     /*!< The public key. */
00112     mbedtls_ecp_point Qp ;    /*!< The value of the public key of the peer. */
00113     mbedtls_mpi z ;           /*!< The shared secret. */
00114     int point_format ;        /*!< The format of point export in TLS messages. */
00115     mbedtls_ecp_point Vi ;    /*!< The blinding value. */
00116     mbedtls_ecp_point Vf ;    /*!< The unblinding value. */
00117     mbedtls_mpi _d ;          /*!< The previous \p d. */
00118 #if defined(MBEDTLS_ECP_RESTARTABLE)
00119     int restart_enabled ;        /*!< The flag for restartable mode. */
00120     mbedtls_ecp_restart_ctx rs ; /*!< The restart context for EC computations. */
00121 #endif /* MBEDTLS_ECP_RESTARTABLE */
00122 #else
00123     uint8_t point_format ;       /*!< The format of point export in TLS messages
00124                                   as defined in RFC 4492. */
00125     mbedtls_ecp_group_id grp_id ;/*!< The elliptic curve used. */
00126     mbedtls_ecdh_variant var ;   /*!< The ECDH implementation/structure used. */
00127     union
00128     {
00129         mbedtls_ecdh_context_mbed   mbed_ecdh;
00130 #if defined(MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED)
00131         mbedtls_ecdh_context_everest everest_ecdh;
00132 #endif
00133     } ctx ;                      /*!< Implementation-specific context. The
00134                                   context in use is specified by the \c var
00135                                   field. */
00136 #if defined(MBEDTLS_ECP_RESTARTABLE)
00137     uint8_t restart_enabled ;    /*!< The flag for restartable mode. Functions of
00138                                   an alternative implementation not supporting
00139                                   restartable mode must return
00140                                   MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED error
00141                                   if this flag is set. */
00142 #endif /* MBEDTLS_ECP_RESTARTABLE */
00143 #endif /* MBEDTLS_ECDH_LEGACY_CONTEXT */
00144 }
00145 mbedtls_ecdh_context;
00146 
00147 /**
00148  * \brief          Check whether a given group can be used for ECDH.
00149  *
00150  * \param gid      The ECP group ID to check.
00151  *
00152  * \return         \c 1 if the group can be used, \c 0 otherwise
00153  */
00154 int mbedtls_ecdh_can_do( mbedtls_ecp_group_id gid );
00155 
00156 /**
00157  * \brief           This function generates an ECDH keypair on an elliptic
00158  *                  curve.
00159  *
00160  *                  This function performs the first of two core computations
00161  *                  implemented during the ECDH key exchange. The second core
00162  *                  computation is performed by mbedtls_ecdh_compute_shared().
00163  *
00164  * \see             ecp.h
00165  *
00166  * \param grp       The ECP group to use. This must be initialized and have
00167  *                  domain parameters loaded, for example through
00168  *                  mbedtls_ecp_load() or mbedtls_ecp_tls_read_group().
00169  * \param d         The destination MPI (private key).
00170  *                  This must be initialized.
00171  * \param Q         The destination point (public key).
00172  *                  This must be initialized.
00173  * \param f_rng     The RNG function to use. This must not be \c NULL.
00174  * \param p_rng     The RNG context to be passed to \p f_rng. This may be
00175  *                  \c NULL in case \p f_rng doesn't need a context argument.
00176  *
00177  * \return          \c 0 on success.
00178  * \return          Another \c MBEDTLS_ERR_ECP_XXX or
00179  *                  \c MBEDTLS_MPI_XXX error code on failure.
00180  */
00181 int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
00182                      int (*f_rng)(void *, unsigned char *, size_t),
00183                      void *p_rng );
00184 
00185 /**
00186  * \brief           This function computes the shared secret.
00187  *
00188  *                  This function performs the second of two core computations
00189  *                  implemented during the ECDH key exchange. The first core
00190  *                  computation is performed by mbedtls_ecdh_gen_public().
00191  *
00192  * \see             ecp.h
00193  *
00194  * \note            If \p f_rng is not NULL, it is used to implement
00195  *                  countermeasures against side-channel attacks.
00196  *                  For more information, see mbedtls_ecp_mul().
00197  *
00198  * \param grp       The ECP group to use. This must be initialized and have
00199  *                  domain parameters loaded, for example through
00200  *                  mbedtls_ecp_load() or mbedtls_ecp_tls_read_group().
00201  * \param z         The destination MPI (shared secret).
00202  *                  This must be initialized.
00203  * \param Q         The public key from another party.
00204  *                  This must be initialized.
00205  * \param d         Our secret exponent (private key).
00206  *                  This must be initialized.
00207  * \param f_rng     The RNG function. This may be \c NULL if randomization
00208  *                  of intermediate results during the ECP computations is
00209  *                  not needed (discouraged). See the documentation of
00210  *                  mbedtls_ecp_mul() for more.
00211  * \param p_rng     The RNG context to be passed to \p f_rng. This may be
00212  *                  \c NULL if \p f_rng is \c NULL or doesn't need a
00213  *                  context argument.
00214  *
00215  * \return          \c 0 on success.
00216  * \return          Another \c MBEDTLS_ERR_ECP_XXX or
00217  *                  \c MBEDTLS_MPI_XXX error code on failure.
00218  */
00219 int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
00220                          const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
00221                          int (*f_rng)(void *, unsigned char *, size_t),
00222                          void *p_rng );
00223 
00224 /**
00225  * \brief           This function initializes an ECDH context.
00226  *
00227  * \param ctx       The ECDH context to initialize. This must not be \c NULL.
00228  */
00229 void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
00230 
00231 /**
00232  * \brief           This function sets up the ECDH context with the information
00233  *                  given.
00234  *
00235  *                  This function should be called after mbedtls_ecdh_init() but
00236  *                  before mbedtls_ecdh_make_params(). There is no need to call
00237  *                  this function before mbedtls_ecdh_read_params().
00238  *
00239  *                  This is the first function used by a TLS server for ECDHE
00240  *                  ciphersuites.
00241  *
00242  * \param ctx       The ECDH context to set up. This must be initialized.
00243  * \param grp_id    The group id of the group to set up the context for.
00244  *
00245  * \return          \c 0 on success.
00246  */
00247 int mbedtls_ecdh_setup( mbedtls_ecdh_context *ctx,
00248                         mbedtls_ecp_group_id grp_id );
00249 
00250 /**
00251  * \brief           This function frees a context.
00252  *
00253  * \param ctx       The context to free. This may be \c NULL, in which
00254  *                  case this function does nothing. If it is not \c NULL,
00255  *                  it must point to an initialized ECDH context.
00256  */
00257 void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
00258 
00259 /**
00260  * \brief           This function generates an EC key pair and exports its
00261  *                  in the format used in a TLS ServerKeyExchange handshake
00262  *                  message.
00263  *
00264  *                  This is the second function used by a TLS server for ECDHE
00265  *                  ciphersuites. (It is called after mbedtls_ecdh_setup().)
00266  *
00267  * \see             ecp.h
00268  *
00269  * \param ctx       The ECDH context to use. This must be initialized
00270  *                  and bound to a group, for example via mbedtls_ecdh_setup().
00271  * \param olen      The address at which to store the number of Bytes written.
00272  * \param buf       The destination buffer. This must be a writable buffer of
00273  *                  length \p blen Bytes.
00274  * \param blen      The length of the destination buffer \p buf in Bytes.
00275  * \param f_rng     The RNG function to use. This must not be \c NULL.
00276  * \param p_rng     The RNG context to be passed to \p f_rng. This may be
00277  *                  \c NULL in case \p f_rng doesn't need a context argument.
00278  *
00279  * \return          \c 0 on success.
00280  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
00281  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
00282  * \return          Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
00283  */
00284 int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
00285                       unsigned char *buf, size_t blen,
00286                       int (*f_rng)(void *, unsigned char *, size_t),
00287                       void *p_rng );
00288 
00289 /**
00290  * \brief           This function parses the ECDHE parameters in a
00291  *                  TLS ServerKeyExchange handshake message.
00292  *
00293  * \note            In a TLS handshake, this is the how the client
00294  *                  sets up its ECDHE context from the server's public
00295  *                  ECDHE key material.
00296  *
00297  * \see             ecp.h
00298  *
00299  * \param ctx       The ECDHE context to use. This must be initialized.
00300  * \param buf       On input, \c *buf must be the start of the input buffer.
00301  *                  On output, \c *buf is updated to point to the end of the
00302  *                  data that has been read. On success, this is the first byte
00303  *                  past the end of the ServerKeyExchange parameters.
00304  *                  On error, this is the point at which an error has been
00305  *                  detected, which is usually not useful except to debug
00306  *                  failures.
00307  * \param end       The end of the input buffer.
00308  *
00309  * \return          \c 0 on success.
00310  * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
00311  *
00312  */
00313 int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
00314                               const unsigned char **buf,
00315                               const unsigned char *end );
00316 
00317 /**
00318  * \brief           This function sets up an ECDH context from an EC key.
00319  *
00320  *                  It is used by clients and servers in place of the
00321  *                  ServerKeyEchange for static ECDH, and imports ECDH
00322  *                  parameters from the EC key information of a certificate.
00323  *
00324  * \see             ecp.h
00325  *
00326  * \param ctx       The ECDH context to set up. This must be initialized.
00327  * \param key       The EC key to use. This must be initialized.
00328  * \param side      Defines the source of the key. Possible values are:
00329  *                  - #MBEDTLS_ECDH_OURS: The key is ours.
00330  *                  - #MBEDTLS_ECDH_THEIRS: The key is that of the peer.
00331  *
00332  * \return          \c 0 on success.
00333  * \return          Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
00334  *
00335  */
00336 int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx,
00337                              const mbedtls_ecp_keypair *key,
00338                              mbedtls_ecdh_side side );
00339 
00340 /**
00341  * \brief           This function generates a public key and exports it
00342  *                  as a TLS ClientKeyExchange payload.
00343  *
00344  *                  This is the second function used by a TLS client for ECDH(E)
00345  *                  ciphersuites.
00346  *
00347  * \see             ecp.h
00348  *
00349  * \param ctx       The ECDH context to use. This must be initialized
00350  *                  and bound to a group, the latter usually by
00351  *                  mbedtls_ecdh_read_params().
00352  * \param olen      The address at which to store the number of Bytes written.
00353  *                  This must not be \c NULL.
00354  * \param buf       The destination buffer. This must be a writable buffer
00355  *                  of length \p blen Bytes.
00356  * \param blen      The size of the destination buffer \p buf in Bytes.
00357  * \param f_rng     The RNG function to use. This must not be \c NULL.
00358  * \param p_rng     The RNG context to be passed to \p f_rng. This may be
00359  *                  \c NULL in case \p f_rng doesn't need a context argument.
00360  *
00361  * \return          \c 0 on success.
00362  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
00363  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
00364  * \return          Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
00365  */
00366 int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
00367                       unsigned char *buf, size_t blen,
00368                       int (*f_rng)(void *, unsigned char *, size_t),
00369                       void *p_rng );
00370 
00371 /**
00372  * \brief       This function parses and processes the ECDHE payload of a
00373  *              TLS ClientKeyExchange message.
00374  *
00375  *              This is the third function used by a TLS server for ECDH(E)
00376  *              ciphersuites. (It is called after mbedtls_ecdh_setup() and
00377  *              mbedtls_ecdh_make_params().)
00378  *
00379  * \see         ecp.h
00380  *
00381  * \param ctx   The ECDH context to use. This must be initialized
00382  *              and bound to a group, for example via mbedtls_ecdh_setup().
00383  * \param buf   The pointer to the ClientKeyExchange payload. This must
00384  *              be a readable buffer of length \p blen Bytes.
00385  * \param blen  The length of the input buffer \p buf in Bytes.
00386  *
00387  * \return      \c 0 on success.
00388  * \return      An \c MBEDTLS_ERR_ECP_XXX error code on failure.
00389  */
00390 int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
00391                               const unsigned char *buf, size_t blen );
00392 
00393 /**
00394  * \brief           This function derives and exports the shared secret.
00395  *
00396  *                  This is the last function used by both TLS client
00397  *                  and servers.
00398  *
00399  * \note            If \p f_rng is not NULL, it is used to implement
00400  *                  countermeasures against side-channel attacks.
00401  *                  For more information, see mbedtls_ecp_mul().
00402  *
00403  * \see             ecp.h
00404 
00405  * \param ctx       The ECDH context to use. This must be initialized
00406  *                  and have its own private key generated and the peer's
00407  *                  public key imported.
00408  * \param olen      The address at which to store the total number of
00409  *                  Bytes written on success. This must not be \c NULL.
00410  * \param buf       The buffer to write the generated shared key to. This
00411  *                  must be a writable buffer of size \p blen Bytes.
00412  * \param blen      The length of the destination buffer \p buf in Bytes.
00413  * \param f_rng     The RNG function, for blinding purposes. This may
00414  *                  b \c NULL if blinding isn't needed.
00415  * \param p_rng     The RNG context. This may be \c NULL if \p f_rng
00416  *                  doesn't need a context argument.
00417  *
00418  * \return          \c 0 on success.
00419  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
00420  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
00421  * \return          Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
00422  */
00423 int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
00424                       unsigned char *buf, size_t blen,
00425                       int (*f_rng)(void *, unsigned char *, size_t),
00426                       void *p_rng );
00427 
00428 #if defined(MBEDTLS_ECP_RESTARTABLE)
00429 /**
00430  * \brief           This function enables restartable EC computations for this
00431  *                  context.  (Default: disabled.)
00432  *
00433  * \see             \c mbedtls_ecp_set_max_ops()
00434  *
00435  * \note            It is not possible to safely disable restartable
00436  *                  computations once enabled, except by free-ing the context,
00437  *                  which cancels possible in-progress operations.
00438  *
00439  * \param ctx       The ECDH context to use. This must be initialized.
00440  */
00441 void mbedtls_ecdh_enable_restart( mbedtls_ecdh_context *ctx );
00442 #endif /* MBEDTLS_ECP_RESTARTABLE */
00443 
00444 #ifdef __cplusplus
00445 }
00446 #endif
00447 
00448 #endif /* ecdh.h */