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