1 /** 2 * \file ecdh.h 3 * 4 * \brief Elliptic curve Diffie-Hellman 5 * 6 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved 7 * SPDX-License-Identifier: Apache-2.0 8 * 9 * Licensed under the Apache License, Version 2.0 (the "License"); you may 10 * not use this file except in compliance with the License. 11 * You may obtain a copy of the License at 12 * 13 * http://www.apache.org/licenses/LICENSE-2.0 14 * 15 * Unless required by applicable law or agreed to in writing, software 16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 18 * See the License for the specific language governing permissions and 19 * limitations under the License. 20 * 21 * This file is part of mbed TLS (https://tls.mbed.org) 22 */ 23 #ifndef MBEDTLS_ECDH_H 24 #define MBEDTLS_ECDH_H 25 26 #include "ecp.h" 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /** 33 * When importing from an EC key, select if it is our key or the peer's key 34 */ 35 typedef enum 36 { 37 MBEDTLS_ECDH_OURS, 38 MBEDTLS_ECDH_THEIRS, 39 } mbedtls_ecdh_side; 40 41 /** 42 * \brief ECDH context structure 43 */ 44 typedef struct 45 { 46 mbedtls_ecp_group grp; /*!< elliptic curve used */ 47 mbedtls_mpi d; /*!< our secret value (private key) */ 48 mbedtls_ecp_point Q; /*!< our public value (public key) */ 49 mbedtls_ecp_point Qp; /*!< peer's public value (public key) */ 50 mbedtls_mpi z; /*!< shared secret */ 51 int point_format; /*!< format for point export in TLS messages */ 52 mbedtls_ecp_point Vi; /*!< blinding value (for later) */ 53 mbedtls_ecp_point Vf; /*!< un-blinding value (for later) */ 54 mbedtls_mpi _d; /*!< previous d (for later) */ 55 } 56 mbedtls_ecdh_context; 57 58 /** 59 * \brief Generate a public key. 60 * Raw function that only does the core computation. 61 * 62 * \param grp ECP group 63 * \param d Destination MPI (secret exponent, aka private key) 64 * \param Q Destination point (public key) 65 * \param f_rng RNG function 66 * \param p_rng RNG parameter 67 * 68 * \return 0 if successful, 69 * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code 70 */ 71 int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q, 72 int (*f_rng)(void *, unsigned char *, size_t), 73 void *p_rng ); 74 75 /** 76 * \brief Compute shared secret 77 * Raw function that only does the core computation. 78 * 79 * \param grp ECP group 80 * \param z Destination MPI (shared secret) 81 * \param Q Public key from other party 82 * \param d Our secret exponent (private key) 83 * \param f_rng RNG function (see notes) 84 * \param p_rng RNG parameter 85 * 86 * \return 0 if successful, 87 * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code 88 * 89 * \note If f_rng is not NULL, it is used to implement 90 * countermeasures against potential elaborate timing 91 * attacks, see \c mbedtls_ecp_mul() for details. 92 */ 93 int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z, 94 const mbedtls_ecp_point *Q, const mbedtls_mpi *d, 95 int (*f_rng)(void *, unsigned char *, size_t), 96 void *p_rng ); 97 98 /** 99 * \brief Initialize context 100 * 101 * \param ctx Context to initialize 102 */ 103 void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx ); 104 105 /** 106 * \brief Free context 107 * 108 * \param ctx Context to free 109 */ 110 void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx ); 111 112 /** 113 * \brief Generate a public key and a TLS ServerKeyExchange payload. 114 * (First function used by a TLS server for ECDHE.) 115 * 116 * \param ctx ECDH context 117 * \param olen number of chars written 118 * \param buf destination buffer 119 * \param blen length of buffer 120 * \param f_rng RNG function 121 * \param p_rng RNG parameter 122 * 123 * \note This function assumes that ctx->grp has already been 124 * properly set (for example using mbedtls_ecp_group_load). 125 * 126 * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code 127 */ 128 int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen, 129 unsigned char *buf, size_t blen, 130 int (*f_rng)(void *, unsigned char *, size_t), 131 void *p_rng ); 132 133 /** 134 * \brief Parse and procress a TLS ServerKeyExhange payload. 135 * (First function used by a TLS client for ECDHE.) 136 * 137 * \param ctx ECDH context 138 * \param buf pointer to start of input buffer 139 * \param end one past end of buffer 140 * 141 * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code 142 */ 143 int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx, 144 const unsigned char **buf, const unsigned char *end ); 145 146 /** 147 * \brief Setup an ECDH context from an EC key. 148 * (Used by clients and servers in place of the 149 * ServerKeyEchange for static ECDH: import ECDH parameters 150 * from a certificate's EC key information.) 151 * 152 * \param ctx ECDH constext to set 153 * \param key EC key to use 154 * \param side Is it our key (1) or the peer's key (0) ? 155 * 156 * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code 157 */ 158 int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key, 159 mbedtls_ecdh_side side ); 160 161 /** 162 * \brief Generate a public key and a TLS ClientKeyExchange payload. 163 * (Second function used by a TLS client for ECDH(E).) 164 * 165 * \param ctx ECDH context 166 * \param olen number of bytes actually written 167 * \param buf destination buffer 168 * \param blen size of destination buffer 169 * \param f_rng RNG function 170 * \param p_rng RNG parameter 171 * 172 * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code 173 */ 174 int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen, 175 unsigned char *buf, size_t blen, 176 int (*f_rng)(void *, unsigned char *, size_t), 177 void *p_rng ); 178 179 /** 180 * \brief Parse and process a TLS ClientKeyExchange payload. 181 * (Second function used by a TLS server for ECDH(E).) 182 * 183 * \param ctx ECDH context 184 * \param buf start of input buffer 185 * \param blen length of input buffer 186 * 187 * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code 188 */ 189 int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx, 190 const unsigned char *buf, size_t blen ); 191 192 /** 193 * \brief Derive and export the shared secret. 194 * (Last function used by both TLS client en servers.) 195 * 196 * \param ctx ECDH context 197 * \param olen number of bytes written 198 * \param buf destination buffer 199 * \param blen buffer length 200 * \param f_rng RNG function, see notes for \c mbedtls_ecdh_compute_shared() 201 * \param p_rng RNG parameter 202 * 203 * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code 204 */ 205 int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen, 206 unsigned char *buf, size_t blen, 207 int (*f_rng)(void *, unsigned char *, size_t), 208 void *p_rng ); 209 210 #ifdef __cplusplus 211 } 212 #endif 213 214 #endif /* ecdh.h */ 215