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 #include "ecp.h"
00038 
00039 #ifdef __cplusplus
00040 extern "C" {
00041 #endif
00042 
00043 /**
00044  * Defines the source of the imported EC key.
00045  */
00046 typedef enum
00047 {
00048     MBEDTLS_ECDH_OURS,   /**< Our key. */
00049     MBEDTLS_ECDH_THEIRS, /**< The key of the peer. */
00050 } mbedtls_ecdh_side;
00051 
00052 /**
00053  * \brief           The ECDH context structure.
00054  */
00055 typedef struct mbedtls_ecdh_context
00056 {
00057     mbedtls_ecp_group grp ;   /*!< The elliptic curve used. */
00058     mbedtls_mpi d ;           /*!< The private key. */
00059     mbedtls_ecp_point Q ;     /*!< The public key. */
00060     mbedtls_ecp_point Qp ;    /*!< The value of the public key of the peer. */
00061     mbedtls_mpi z ;           /*!< The shared secret. */
00062     int point_format ;        /*!< The format of point export in TLS messages. */
00063     mbedtls_ecp_point Vi ;    /*!< The blinding value. */
00064     mbedtls_ecp_point Vf ;    /*!< The unblinding value. */
00065     mbedtls_mpi _d ;          /*!< The previous \p d. */
00066 }
00067 mbedtls_ecdh_context;
00068 
00069 /**
00070  * \brief           This function generates an ECDH keypair on an elliptic
00071  *                  curve.
00072  *
00073  *                  This function performs the first of two core computations
00074  *                  implemented during the ECDH key exchange. The second core
00075  *                  computation is performed by mbedtls_ecdh_compute_shared().
00076  *
00077  * \see             ecp.h
00078  *
00079  * \param grp       The ECP group.
00080  * \param d         The destination MPI (private key).
00081  * \param Q         The destination point (public key).
00082  * \param f_rng     The RNG function.
00083  * \param p_rng     The RNG context.
00084  *
00085  * \return          \c 0 on success.
00086  * \return          An \c MBEDTLS_ERR_ECP_XXX or
00087  *                  \c MBEDTLS_MPI_XXX error code on failure.
00088  *
00089  */
00090 int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
00091                      int (*f_rng)(void *, unsigned char *, size_t),
00092                      void *p_rng );
00093 
00094 /**
00095  * \brief           This function computes the shared secret.
00096  *
00097  *                  This function performs the second of two core computations
00098  *                  implemented during the ECDH key exchange. The first core
00099  *                  computation is performed by mbedtls_ecdh_gen_public().
00100  *
00101  * \see             ecp.h
00102  *
00103  * \note            If \p f_rng is not NULL, it is used to implement
00104  *                  countermeasures against side-channel attacks.
00105  *                  For more information, see mbedtls_ecp_mul().
00106  *
00107  * \param grp       The ECP group.
00108  * \param z         The destination MPI (shared secret).
00109  * \param Q         The public key from another party.
00110  * \param d         Our secret exponent (private key).
00111  * \param f_rng     The RNG function.
00112  * \param p_rng     The RNG context.
00113  *
00114  * \return          \c 0 on success.
00115  * \return          An \c MBEDTLS_ERR_ECP_XXX or
00116  *                  \c MBEDTLS_MPI_XXX error code on failure.
00117  */
00118 int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
00119                          const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
00120                          int (*f_rng)(void *, unsigned char *, size_t),
00121                          void *p_rng );
00122 
00123 /**
00124  * \brief           This function initializes an ECDH context.
00125  *
00126  * \param ctx       The ECDH context to initialize.
00127  */
00128 void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
00129 
00130 /**
00131  * \brief           This function frees a context.
00132  *
00133  * \param ctx       The context to free.
00134  */
00135 void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
00136 
00137 /**
00138  * \brief           This function generates a public key and a TLS
00139  *                  ServerKeyExchange payload.
00140  *
00141  *                  This is the first function used by a TLS server for ECDHE
00142  *                  ciphersuites.
00143  *
00144  * \note            This function assumes that the ECP group (grp) of the
00145  *                  \p ctx context has already been properly set,
00146  *                  for example, using mbedtls_ecp_group_load().
00147  *
00148  * \see             ecp.h
00149  *
00150  * \param ctx       The ECDH context.
00151  * \param olen      The number of characters written.
00152  * \param buf       The destination buffer.
00153  * \param blen      The length of the destination buffer.
00154  * \param f_rng     The RNG function.
00155  * \param p_rng     The RNG context.
00156  *
00157  * \return          \c 0 on success.
00158  * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
00159  */
00160 int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
00161                       unsigned char *buf, size_t blen,
00162                       int (*f_rng)(void *, unsigned char *, size_t),
00163                       void *p_rng );
00164 
00165 /**
00166  * \brief           This function parses and processes a TLS ServerKeyExhange
00167  *                  payload.
00168  *
00169  *                  This is the first function used by a TLS client for ECDHE
00170  *                  ciphersuites.
00171  *
00172  * \see             ecp.h
00173  *
00174  * \param ctx       The ECDH context.
00175  * \param buf       The pointer to the start of the input buffer.
00176  * \param end       The address for one Byte past the end of the buffer.
00177  *
00178  * \return          \c 0 on success.
00179  * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
00180  *
00181  */
00182 int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
00183                       const unsigned char **buf, const unsigned char *end );
00184 
00185 /**
00186  * \brief           This function sets up an ECDH context from an EC key.
00187  *
00188  *                  It is used by clients and servers in place of the
00189  *                  ServerKeyEchange for static ECDH, and imports ECDH
00190  *                  parameters from the EC key information of a certificate.
00191  *
00192  * \see             ecp.h
00193  *
00194  * \param ctx       The ECDH context to set up.
00195  * \param key       The EC key to use.
00196  * \param side      Defines the source of the key: 1: Our key, or
00197  *                  0: The key of the peer.
00198  *
00199  * \return          \c 0 on success.
00200  * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
00201  *
00202  */
00203 int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
00204                      mbedtls_ecdh_side side );
00205 
00206 /**
00207  * \brief           This function generates a public key and a TLS
00208  *                  ClientKeyExchange payload.
00209  *
00210  *                  This is the second function used by a TLS client for ECDH(E)
00211  *                  ciphersuites.
00212  *
00213  * \see             ecp.h
00214  *
00215  * \param ctx       The ECDH context.
00216  * \param olen      The number of Bytes written.
00217  * \param buf       The destination buffer.
00218  * \param blen      The size of the destination buffer.
00219  * \param f_rng     The RNG function.
00220  * \param p_rng     The RNG context.
00221  *
00222  * \return          \c 0 on success.
00223  * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
00224  */
00225 int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
00226                       unsigned char *buf, size_t blen,
00227                       int (*f_rng)(void *, unsigned char *, size_t),
00228                       void *p_rng );
00229 
00230 /**
00231  * \brief       This function parses and processes a TLS ClientKeyExchange
00232  *              payload.
00233  *
00234  *              This is the second function used by a TLS server for ECDH(E)
00235  *              ciphersuites.
00236  *
00237  * \see         ecp.h
00238  *
00239  * \param ctx   The ECDH context.
00240  * \param buf   The start of the input buffer.
00241  * \param blen  The length of the input buffer.
00242  *
00243  * \return      \c 0 on success.
00244  * \return      An \c MBEDTLS_ERR_ECP_XXX error code on failure.
00245  */
00246 int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
00247                       const unsigned char *buf, size_t blen );
00248 
00249 /**
00250  * \brief           This function derives and exports the shared secret.
00251  *
00252  *                  This is the last function used by both TLS client
00253  *                  and servers.
00254  *
00255  * \note            If \p f_rng is not NULL, it is used to implement
00256  *                  countermeasures against side-channel attacks.
00257  *                  For more information, see mbedtls_ecp_mul().
00258  *
00259  * \see             ecp.h
00260  *
00261  * \param ctx       The ECDH context.
00262  * \param olen      The number of Bytes written.
00263  * \param buf       The destination buffer.
00264  * \param blen      The length of the destination buffer.
00265  * \param f_rng     The RNG function.
00266  * \param p_rng     The RNG context.
00267  *
00268  * \return          \c 0 on success.
00269  * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
00270  */
00271 int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
00272                       unsigned char *buf, size_t blen,
00273                       int (*f_rng)(void *, unsigned char *, size_t),
00274                       void *p_rng );
00275 
00276 #ifdef __cplusplus
00277 }
00278 #endif
00279 
00280 #endif /* ecdh.h */