Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
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 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 */
Generated on Tue Jul 12 2022 12:43:50 by
