1 /** 2 * \file ecdh.h 3 * 4 * \brief The Elliptic Curve Diffie-Hellman (ECDH) protocol APIs. 5 * 6 * ECDH is an anonymous key agreement protocol allowing two parties to 7 * establish a shared secret over an insecure channel. Each party must have an 8 * elliptic-curve public–private key pair. 9 * 10 * For more information, see <em>NIST SP 800-56A Rev. 2: Recommendation for 11 * Pair-Wise Key Establishment Schemes Using Discrete Logarithm 12 * Cryptography</em>. 13 */ 14 /* 15 * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved 16 * SPDX-License-Identifier: GPL-2.0 17 * 18 * This program is free software; you can redistribute it and/or modify 19 * it under the terms of the GNU General Public License as published by 20 * the Free Software Foundation; either version 2 of the License, or 21 * (at your option) any later version. 22 * 23 * This program is distributed in the hope that it will be useful, 24 * but WITHOUT ANY WARRANTY; without even the implied warranty of 25 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 26 * GNU General Public License for more details. 27 * 28 * You should have received a copy of the GNU General Public License along 29 * with this program; if not, write to the Free Software Foundation, Inc., 30 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 31 * 32 * This file is part of Mbed TLS (https://tls.mbed.org) 33 */ 34 35 #ifndef MBEDTLS_ECDH_H 36 #define MBEDTLS_ECDH_H 37 38 #if !defined(MBEDTLS_CONFIG_FILE) 39 #include "config.h" 40 #else 41 #include MBEDTLS_CONFIG_FILE 42 #endif 43 44 #include "ecp.h" 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * Defines the source of the imported EC key: 52 * <ul><li>Our key.</li> 53 * <li>The key of the peer.</li></ul> 54 */ 55 typedef enum 56 { 57 MBEDTLS_ECDH_OURS, 58 MBEDTLS_ECDH_THEIRS, 59 } mbedtls_ecdh_side; 60 61 /** 62 * \brief The ECDH context structure. 63 */ 64 typedef struct 65 { 66 mbedtls_ecp_group grp; /*!< The elliptic curve used. */ 67 mbedtls_mpi d; /*!< The private key. */ 68 mbedtls_ecp_point Q; /*!< The public key. */ 69 mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */ 70 mbedtls_mpi z; /*!< The shared secret. */ 71 int point_format; /*!< The format of point export in TLS messages. */ 72 mbedtls_ecp_point Vi; /*!< The blinding value. */ 73 mbedtls_ecp_point Vf; /*!< The unblinding value. */ 74 mbedtls_mpi _d; /*!< The previous \p d. */ 75 } 76 mbedtls_ecdh_context; 77 78 /** 79 * \brief This function generates an ECDH keypair on an elliptic 80 * curve. 81 * 82 * This function performs the first of two core computations 83 * implemented during the ECDH key exchange. The second core 84 * computation is performed by mbedtls_ecdh_compute_shared(). 85 * 86 * \param grp The ECP group. 87 * \param d The destination MPI (private key). 88 * \param Q The destination point (public key). 89 * \param f_rng The RNG function. 90 * \param p_rng The RNG parameter. 91 * 92 * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or 93 * \c MBEDTLS_MPI_XXX error code on failure. 94 * 95 * \see ecp.h 96 */ 97 int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q, 98 int (*f_rng)(void *, unsigned char *, size_t), 99 void *p_rng ); 100 101 /** 102 * \brief This function computes the shared secret. 103 * 104 * This function performs the second of two core computations 105 * implemented during the ECDH key exchange. The first core 106 * computation is performed by mbedtls_ecdh_gen_public(). 107 * 108 * \param grp The ECP group. 109 * \param z The destination MPI (shared secret). 110 * \param Q The public key from another party. 111 * \param d Our secret exponent (private key). 112 * \param f_rng The RNG function. 113 * \param p_rng The RNG parameter. 114 * 115 * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or 116 * \c MBEDTLS_MPI_XXX error code on failure. 117 * 118 * \see ecp.h 119 * 120 * \note If \p f_rng is not NULL, it is used to implement 121 * countermeasures against potential elaborate timing 122 * attacks. For more information, see mbedtls_ecp_mul(). 123 */ 124 int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z, 125 const mbedtls_ecp_point *Q, const mbedtls_mpi *d, 126 int (*f_rng)(void *, unsigned char *, size_t), 127 void *p_rng ); 128 129 /** 130 * \brief This function initializes an ECDH context. 131 * 132 * \param ctx The ECDH context to initialize. 133 */ 134 void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx ); 135 136 /** 137 * \brief This function frees a context. 138 * 139 * \param ctx The context to free. 140 */ 141 void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx ); 142 143 /** 144 * \brief This function generates a public key and a TLS 145 * ServerKeyExchange payload. 146 * 147 * This is the first function used by a TLS server for ECDHE 148 * ciphersuites. 149 * 150 * \param ctx The ECDH context. 151 * \param olen The number of characters written. 152 * \param buf The destination buffer. 153 * \param blen The length of the destination buffer. 154 * \param f_rng The RNG function. 155 * \param p_rng The RNG parameter. 156 * 157 * \note This function assumes that the ECP group (grp) of the 158 * \p ctx context has already been properly set, 159 * for example, using mbedtls_ecp_group_load(). 160 * 161 * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code 162 * on failure. 163 * 164 * \see ecp.h 165 */ 166 int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen, 167 unsigned char *buf, size_t blen, 168 int (*f_rng)(void *, unsigned char *, size_t), 169 void *p_rng ); 170 171 /** 172 * \brief This function parses and processes a TLS ServerKeyExhange 173 * payload. 174 * 175 * This is the first function used by a TLS client for ECDHE 176 * ciphersuites. 177 * 178 * \param ctx The ECDH context. 179 * \param buf The pointer to the start of the input buffer. 180 * \param end The address for one Byte past the end of the buffer. 181 * 182 * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code 183 * on failure. 184 * 185 * \see ecp.h 186 */ 187 int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx, 188 const unsigned char **buf, const unsigned char *end ); 189 190 /** 191 * \brief This function sets up an ECDH context from an EC key. 192 * 193 * It is used by clients and servers in place of the 194 * ServerKeyEchange for static ECDH, and imports ECDH 195 * parameters from the EC key information of a certificate. 196 * 197 * \param ctx The ECDH context to set up. 198 * \param key The EC key to use. 199 * \param side Defines the source of the key: 200 * <ul><li>1: Our key.</li> 201 <li>0: The key of the peer.</li></ul> 202 * 203 * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code 204 * on failure. 205 * 206 * \see ecp.h 207 */ 208 int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key, 209 mbedtls_ecdh_side side ); 210 211 /** 212 * \brief This function generates a public key and a TLS 213 * ClientKeyExchange payload. 214 * 215 * This is the second function used by a TLS client for ECDH(E) 216 * ciphersuites. 217 * 218 * \param ctx The ECDH context. 219 * \param olen The number of Bytes written. 220 * \param buf The destination buffer. 221 * \param blen The size of the destination buffer. 222 * \param f_rng The RNG function. 223 * \param p_rng The RNG parameter. 224 * 225 * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code 226 * on failure. 227 * 228 * \see ecp.h 229 */ 230 int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen, 231 unsigned char *buf, size_t blen, 232 int (*f_rng)(void *, unsigned char *, size_t), 233 void *p_rng ); 234 235 /** 236 * \brief This function parses and processes a TLS ClientKeyExchange 237 * payload. 238 * 239 * This is the second function used by a TLS server for ECDH(E) 240 * ciphersuites. 241 * 242 * \param ctx The ECDH context. 243 * \param buf The start of the input buffer. 244 * \param blen The length of the input buffer. 245 * 246 * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code 247 * on failure. 248 * 249 * \see ecp.h 250 */ 251 int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx, 252 const unsigned char *buf, size_t blen ); 253 254 /** 255 * \brief This function derives and exports the shared secret. 256 * 257 * This is the last function used by both TLS client 258 * and servers. 259 * 260 * \param ctx The ECDH context. 261 * \param olen The number of Bytes written. 262 * \param buf The destination buffer. 263 * \param blen The length of the destination buffer. 264 * \param f_rng The RNG function. 265 * \param p_rng The RNG parameter. 266 * 267 * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code 268 * on failure. 269 * 270 * \see ecp.h 271 * 272 * \note If \p f_rng is not NULL, it is used to implement 273 * countermeasures against potential elaborate timing 274 * attacks. For more information, see mbedtls_ecp_mul(). 275 */ 276 int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen, 277 unsigned char *buf, size_t blen, 278 int (*f_rng)(void *, unsigned char *, size_t), 279 void *p_rng ); 280 281 #ifdef __cplusplus 282 } 283 #endif 284 285 #endif /* ecdh.h */ 286