ecdh.h

00001 /**
00002  * \file ecdh.h
00003  *
00004  * \brief The Elliptic Curve Diffie-Hellman (ECDH) protocol APIs.
00005  *
00006  * ECDH is an anonymous key agreement protocol allowing two parties to
00007  * establish a shared secret over an insecure channel. Each party must have an
00008  * elliptic-curve public–private key pair.
00009  *
00010  * For more information, see <em>NIST SP 800-56A Rev. 2: Recommendation for
00011  * Pair-Wise Key Establishment Schemes Using Discrete Logarithm
00012  * Cryptography</em>.
00013  */
00014 /*
00015  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
00016  *  SPDX-License-Identifier: Apache-2.0
00017  *
00018  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00019  *  not use this file except in compliance with the License.
00020  *  You may obtain a copy of the License at
00021  *
00022  *  http://www.apache.org/licenses/LICENSE-2.0
00023  *
00024  *  Unless required by applicable law or agreed to in writing, software
00025  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00026  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00027  *  See the License for the specific language governing permissions and
00028  *  limitations under the License.
00029  *
00030  *  This file is part of Mbed TLS (https://tls.mbed.org)
00031  */
00032 
00033 #ifndef MBEDTLS_ECDH_H
00034 #define MBEDTLS_ECDH_H
00035 
00036 #include "ecp.h"
00037 
00038 #ifdef __cplusplus
00039 extern "C" {
00040 #endif
00041 
00042 /**
00043  * Defines the source of the imported EC key:
00044  * <ul><li>Our key.</li>
00045  * <li>The key of the peer.</li></ul>
00046  */
00047 typedef enum
00048 {
00049     MBEDTLS_ECDH_OURS,
00050     MBEDTLS_ECDH_THEIRS,
00051 } mbedtls_ecdh_side;
00052 
00053 /**
00054  * \brief           The ECDH context structure.
00055  */
00056 typedef struct
00057 {
00058     mbedtls_ecp_group grp ;   /*!< The elliptic curve used. */
00059     mbedtls_mpi d ;           /*!< The private key. */
00060     mbedtls_ecp_point Q ;     /*!< The public key. */
00061     mbedtls_ecp_point Qp ;    /*!< The value of the public key of the peer. */
00062     mbedtls_mpi z ;           /*!< The shared secret. */
00063     int point_format ;        /*!< The format of point export in TLS messages. */
00064     mbedtls_ecp_point Vi ;    /*!< The blinding value. */
00065     mbedtls_ecp_point Vf ;    /*!< The unblinding value. */
00066     mbedtls_mpi _d ;          /*!< The previous \p d. */
00067 }
00068 mbedtls_ecdh_context;
00069 
00070 /**
00071  * \brief           This function generates an ECDH keypair on an elliptic
00072  *                  curve.
00073  *
00074  *                  This function performs the first of two core computations
00075  *                  implemented during the ECDH key exchange. The second core
00076  *                  computation is performed by mbedtls_ecdh_compute_shared().
00077  *
00078  * \param grp       The ECP group.
00079  * \param d         The destination MPI (private key).
00080  * \param Q         The destination point (public key).
00081  * \param f_rng     The RNG function.
00082  * \param p_rng     The RNG parameter.
00083  *
00084  * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
00085  *                  \c MBEDTLS_MPI_XXX error code on failure.
00086  *
00087  * \see             ecp.h
00088  */
00089 int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
00090                      int (*f_rng)(void *, unsigned char *, size_t),
00091                      void *p_rng );
00092 
00093 /**
00094  * \brief           This function computes the shared secret.
00095  *
00096  *                  This function performs the second of two core computations
00097  *                  implemented during the ECDH key exchange. The first core
00098  *                  computation is performed by mbedtls_ecdh_gen_public().
00099  *
00100  * \param grp       The ECP group.
00101  * \param z         The destination MPI (shared secret).
00102  * \param Q         The public key from another party.
00103  * \param d         Our secret exponent (private key).
00104  * \param f_rng     The RNG function.
00105  * \param p_rng     The RNG parameter.
00106  *
00107  * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
00108  *                  \c MBEDTLS_MPI_XXX error code on failure.
00109  *
00110  * \see             ecp.h
00111  *
00112  * \note            If \p f_rng is not NULL, it is used to implement
00113  *                  countermeasures against potential elaborate timing
00114  *                  attacks. For more information, see mbedtls_ecp_mul().
00115  */
00116 int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
00117                          const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
00118                          int (*f_rng)(void *, unsigned char *, size_t),
00119                          void *p_rng );
00120 
00121 /**
00122  * \brief           This function initializes an ECDH context.
00123  *
00124  * \param ctx       The ECDH context to initialize.
00125  */
00126 void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
00127 
00128 /**
00129  * \brief           This function frees a context.
00130  *
00131  * \param ctx       The context to free.
00132  */
00133 void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
00134 
00135 /**
00136  * \brief           This function generates a public key and a TLS
00137  *                  ServerKeyExchange payload.
00138  *
00139  *                  This is the first function used by a TLS server for ECDHE
00140  *                  ciphersuites.
00141  *
00142  * \param ctx       The ECDH context.
00143  * \param olen      The number of characters written.
00144  * \param buf       The destination buffer.
00145  * \param blen      The length of the destination buffer.
00146  * \param f_rng     The RNG function.
00147  * \param p_rng     The RNG parameter.
00148  *
00149  * \note            This function assumes that the ECP group (grp) of the
00150  *                  \p ctx context has already been properly set,
00151  *                  for example, using mbedtls_ecp_group_load().
00152  *
00153  * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
00154  *                  on failure.
00155  *
00156  * \see             ecp.h
00157  */
00158 int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
00159                       unsigned char *buf, size_t blen,
00160                       int (*f_rng)(void *, unsigned char *, size_t),
00161                       void *p_rng );
00162 
00163 /**
00164  * \brief           This function parses and processes a TLS ServerKeyExhange
00165  *                  payload.
00166  *
00167  *                  This is the first function used by a TLS client for ECDHE
00168  *                  ciphersuites.
00169  *
00170  * \param ctx       The ECDH context.
00171  * \param buf       The pointer to the start of the input buffer.
00172  * \param end       The address for one Byte past the end of the buffer.
00173  *
00174  * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
00175  *                  on failure.
00176  *
00177  * \see             ecp.h
00178  */
00179 int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
00180                       const unsigned char **buf, const unsigned char *end );
00181 
00182 /**
00183  * \brief           This function sets up an ECDH context from an EC key.
00184  *
00185  *                  It is used by clients and servers in place of the
00186  *                  ServerKeyEchange for static ECDH, and imports ECDH
00187  *                  parameters from the EC key information of a certificate.
00188  *
00189  * \param ctx       The ECDH context to set up.
00190  * \param key       The EC key to use.
00191  * \param side      Defines the source of the key:
00192  *                  <ul><li>1: Our key.</li>
00193                     <li>0: The key of the peer.</li></ul>
00194  *
00195  * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
00196  *                  on failure.
00197  *
00198  * \see             ecp.h
00199  */
00200 int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
00201                      mbedtls_ecdh_side side );
00202 
00203 /**
00204  * \brief           This function generates a public key and a TLS
00205  *                  ClientKeyExchange payload.
00206  *
00207  *                  This is the second function used by a TLS client for ECDH(E)
00208  *                  ciphersuites.
00209  *
00210  * \param ctx       The ECDH context.
00211  * \param olen      The number of Bytes written.
00212  * \param buf       The destination buffer.
00213  * \param blen      The size of the destination buffer.
00214  * \param f_rng     The RNG function.
00215  * \param p_rng     The RNG parameter.
00216  *
00217  * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
00218  *                  on failure.
00219  *
00220  * \see             ecp.h
00221  */
00222 int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
00223                       unsigned char *buf, size_t blen,
00224                       int (*f_rng)(void *, unsigned char *, size_t),
00225                       void *p_rng );
00226 
00227 /**
00228  * \brief       This function parses and processes a TLS ClientKeyExchange
00229  *              payload.
00230  *
00231  *              This is the second function used by a TLS server for ECDH(E)
00232  *              ciphersuites.
00233  *
00234  * \param ctx   The ECDH context.
00235  * \param buf   The start of the input buffer.
00236  * \param blen  The length of the input buffer.
00237  *
00238  * \return      \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
00239  *              on failure.
00240  *
00241  * \see         ecp.h
00242  */
00243 int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
00244                       const unsigned char *buf, size_t blen );
00245 
00246 /**
00247  * \brief           This function derives and exports the shared secret.
00248  *
00249  *                  This is the last function used by both TLS client
00250  *                  and servers.
00251  *
00252  * \param ctx       The ECDH context.
00253  * \param olen      The number of Bytes written.
00254  * \param buf       The destination buffer.
00255  * \param blen      The length of the destination buffer.
00256  * \param f_rng     The RNG function.
00257  * \param p_rng     The RNG parameter.
00258  *
00259  * \return          \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
00260  *                  on failure.
00261  *
00262  * \see             ecp.h
00263  *
00264  * \note            If \p f_rng is not NULL, it is used to implement
00265  *                  countermeasures against potential elaborate timing
00266  *                  attacks. For more information, see mbedtls_ecp_mul().
00267  */
00268 int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
00269                       unsigned char *buf, size_t blen,
00270                       int (*f_rng)(void *, unsigned char *, size_t),
00271                       void *p_rng );
00272 
00273 #ifdef __cplusplus
00274 }
00275 #endif
00276 
00277 #endif /* ecdh.h */