blob: f6e67020438ecb3f049a643318b1b62ec5aa9b20 [file] [log] [blame]
Manuel Pégourié-Gonnard0bad5c22013-01-26 15:30:46 +01001/**
2 * \file ecdh.h
3 *
Rose Zadik68993282018-03-27 11:12:25 +01004 * \brief This file contains ECDH definitions and functions.
Manuel Pégourié-Gonnard0bad5c22013-01-26 15:30:46 +01005 *
Darryl Green11999bb2018-03-13 15:22:58 +00006 * The Elliptic Curve Diffie-Hellman (ECDH) protocol is an anonymous
Rose Zadik68993282018-03-27 11:12:25 +01007 * key agreement protocol allowing two parties to establish a shared
8 * secret over an insecure channel. Each party must have an
Rose Zadikde2d6222018-01-25 21:57:43 +00009 * elliptic-curve public–private key pair.
10 *
11 * For more information, see <em>NIST SP 800-56A Rev. 2: Recommendation for
12 * Pair-Wise Key Establishment Schemes Using Discrete Logarithm
13 * Cryptography</em>.
Darryl Greena40a1012018-01-05 15:33:17 +000014 */
15/*
Rose Zadikde2d6222018-01-25 21:57:43 +000016 * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +020017 * SPDX-License-Identifier: Apache-2.0
18 *
19 * Licensed under the Apache License, Version 2.0 (the "License"); you may
20 * not use this file except in compliance with the License.
21 * You may obtain a copy of the License at
22 *
23 * http://www.apache.org/licenses/LICENSE-2.0
24 *
25 * Unless required by applicable law or agreed to in writing, software
26 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
27 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
28 * See the License for the specific language governing permissions and
29 * limitations under the License.
Manuel Pégourié-Gonnard0bad5c22013-01-26 15:30:46 +010030 *
Rose Zadikde2d6222018-01-25 21:57:43 +000031 * This file is part of Mbed TLS (https://tls.mbed.org)
Manuel Pégourié-Gonnard0bad5c22013-01-26 15:30:46 +010032 */
Rose Zadikde2d6222018-01-25 21:57:43 +000033
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020034#ifndef MBEDTLS_ECDH_H
35#define MBEDTLS_ECDH_H
Manuel Pégourié-Gonnard0bad5c22013-01-26 15:30:46 +010036
Manuel Pégourié-Gonnardbdc96762013-10-03 11:50:39 +020037#include "ecp.h"
Manuel Pégourié-Gonnard0bad5c22013-01-26 15:30:46 +010038
Paul Bakker407a0da2013-06-27 14:29:21 +020039#ifdef __cplusplus
40extern "C" {
41#endif
42
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +010043/**
Rose Zadik68993282018-03-27 11:12:25 +010044 * Defines the source of the imported EC key.
Manuel Pégourié-Gonnardcdff3cf2013-12-12 09:55:52 +010045 */
46typedef enum
47{
Rose Zadik7375b0f2018-04-16 16:04:57 +010048 MBEDTLS_ECDH_OURS, /**< Our key. */
Rose Zadik68993282018-03-27 11:12:25 +010049 MBEDTLS_ECDH_THEIRS, /**< The key of the peer. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020050} mbedtls_ecdh_side;
Manuel Pégourié-Gonnardcdff3cf2013-12-12 09:55:52 +010051
52/**
Manuel Pégourié-Gonnardeaf55be2017-08-23 14:40:21 +020053 *
54 * \warning Performing multiple operations concurrently on the same
55 * ECDSA context is not supported; objects of this type
56 * should not be shared between multiple threads.
Rose Zadikde2d6222018-01-25 21:57:43 +000057 * \brief The ECDH context structure.
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +010058 */
59typedef struct
60{
Rose Zadikde2d6222018-01-25 21:57:43 +000061 mbedtls_ecp_group grp; /*!< The elliptic curve used. */
62 mbedtls_mpi d; /*!< The private key. */
63 mbedtls_ecp_point Q; /*!< The public key. */
64 mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */
65 mbedtls_mpi z; /*!< The shared secret. */
66 int point_format; /*!< The format of point export in TLS messages. */
67 mbedtls_ecp_point Vi; /*!< The blinding value. */
68 mbedtls_ecp_point Vf; /*!< The unblinding value. */
69 mbedtls_mpi _d; /*!< The previous \p d. */
Manuel Pégourié-Gonnard66ba48a2017-04-27 11:38:26 +020070#if defined(MBEDTLS_ECP_RESTARTABLE)
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +020071 int restart_enabled; /*!< The flag for restartable mode. */
72 mbedtls_ecp_restart_ctx rs; /*!< The restart context for EC computations. */
Manuel Pégourié-Gonnard66ba48a2017-04-27 11:38:26 +020073#endif
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +010074}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020075mbedtls_ecdh_context;
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +010076
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +010077/**
Rose Zadikde2d6222018-01-25 21:57:43 +000078 * \brief This function generates an ECDH keypair on an elliptic
79 * curve.
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +010080 *
Rose Zadikde2d6222018-01-25 21:57:43 +000081 * This function performs the first of two core computations
82 * implemented during the ECDH key exchange. The second core
83 * computation is performed by mbedtls_ecdh_compute_shared().
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +010084 *
Rose Zadik68993282018-03-27 11:12:25 +010085 * \see ecp.h
86 *
Rose Zadikde2d6222018-01-25 21:57:43 +000087 * \param grp The ECP group.
88 * \param d The destination MPI (private key).
89 * \param Q The destination point (public key).
90 * \param f_rng The RNG function.
Rose Zadik68993282018-03-27 11:12:25 +010091 * \param p_rng The RNG context.
Rose Zadikde2d6222018-01-25 21:57:43 +000092 *
Rose Zadik68993282018-03-27 11:12:25 +010093 * \return \c 0 on success.
94 * \return An \c MBEDTLS_ERR_ECP_XXX or
Rose Zadikde2d6222018-01-25 21:57:43 +000095 * \c MBEDTLS_MPI_XXX error code on failure.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +020096 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnardc90d3b02017-04-27 10:48:29 +020097 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +010098 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020099int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +0100100 int (*f_rng)(void *, unsigned char *, size_t),
101 void *p_rng );
102
103/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000104 * \brief This function computes the shared secret.
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +0100105 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000106 * This function performs the second of two core computations
107 * implemented during the ECDH key exchange. The first core
108 * computation is performed by mbedtls_ecdh_gen_public().
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +0100109 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000110 * \see ecp.h
111 *
112 * \note If \p f_rng is not NULL, it is used to implement
Rose Zadik7375b0f2018-04-16 16:04:57 +0100113 * countermeasures against side-channel attacks.
114 * For more information, see mbedtls_ecp_mul().
Rose Zadik68993282018-03-27 11:12:25 +0100115 *
116 * \param grp The ECP group.
117 * \param z The destination MPI (shared secret).
118 * \param Q The public key from another party.
119 * \param d Our secret exponent (private key).
120 * \param f_rng The RNG function.
121 * \param p_rng The RNG context.
122 *
123 * \return \c 0 on success.
124 * \return An \c MBEDTLS_ERR_ECP_XXX or
125 * \c MBEDTLS_MPI_XXX error code on failure.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200126 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnardc90d3b02017-04-27 10:48:29 +0200127 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +0100128 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200129int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
130 const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
Manuel Pégourié-Gonnarde09d2f82013-09-02 14:29:09 +0200131 int (*f_rng)(void *, unsigned char *, size_t),
132 void *p_rng );
Manuel Pégourié-Gonnard0bad5c22013-01-26 15:30:46 +0100133
134/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000135 * \brief This function initializes an ECDH context.
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100136 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000137 * \param ctx The ECDH context to initialize.
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100138 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200139void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100140
141/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000142 * \brief This function frees a context.
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100143 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000144 * \param ctx The context to free.
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100145 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200146void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100147
148/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000149 * \brief This function generates a public key and a TLS
150 * ServerKeyExchange payload.
Manuel Pégourié-Gonnard13724762013-02-10 15:01:54 +0100151 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000152 * This is the first function used by a TLS server for ECDHE
153 * ciphersuites.
Manuel Pégourié-Gonnard13724762013-02-10 15:01:54 +0100154 *
Rose Zadik68993282018-03-27 11:12:25 +0100155 * \note This function assumes that the ECP group (grp) of the
156 * \p ctx context has already been properly set,
157 * for example, using mbedtls_ecp_group_load().
Manuel Pégourié-Gonnard13724762013-02-10 15:01:54 +0100158 *
Rose Zadik68993282018-03-27 11:12:25 +0100159 * \see ecp.h
160 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000161 * \param ctx The ECDH context.
162 * \param olen The number of characters written.
163 * \param buf The destination buffer.
164 * \param blen The length of the destination buffer.
165 * \param f_rng The RNG function.
Rose Zadik68993282018-03-27 11:12:25 +0100166 * \param p_rng The RNG context.
Manuel Pégourié-Gonnard13724762013-02-10 15:01:54 +0100167 *
Rose Zadik68993282018-03-27 11:12:25 +0100168 * \return \c 0 on success.
169 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200170 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnardc90d3b02017-04-27 10:48:29 +0200171 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Manuel Pégourié-Gonnard13724762013-02-10 15:01:54 +0100172 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200173int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
Manuel Pégourié-Gonnard854fbd72013-02-11 20:28:55 +0100174 unsigned char *buf, size_t blen,
175 int (*f_rng)(void *, unsigned char *, size_t),
176 void *p_rng );
177
178/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000179 * \brief This function parses and processes a TLS ServerKeyExhange
180 * payload.
Manuel Pégourié-Gonnard854fbd72013-02-11 20:28:55 +0100181 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000182 * This is the first function used by a TLS client for ECDHE
183 * ciphersuites.
Manuel Pégourié-Gonnard854fbd72013-02-11 20:28:55 +0100184 *
Rose Zadik68993282018-03-27 11:12:25 +0100185 * \see ecp.h
186 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000187 * \param ctx The ECDH context.
188 * \param buf The pointer to the start of the input buffer.
189 * \param end The address for one Byte past the end of the buffer.
190 *
Rose Zadik68993282018-03-27 11:12:25 +0100191 * \return \c 0 on success.
192 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
Rose Zadikde2d6222018-01-25 21:57:43 +0000193 *
Manuel Pégourié-Gonnard854fbd72013-02-11 20:28:55 +0100194 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200195int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
Manuel Pégourié-Gonnard854fbd72013-02-11 20:28:55 +0100196 const unsigned char **buf, const unsigned char *end );
Manuel Pégourié-Gonnard13724762013-02-10 15:01:54 +0100197
198/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000199 * \brief This function sets up an ECDH context from an EC key.
Manuel Pégourié-Gonnardcdff3cf2013-12-12 09:55:52 +0100200 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000201 * It is used by clients and servers in place of the
202 * ServerKeyEchange for static ECDH, and imports ECDH
203 * parameters from the EC key information of a certificate.
Manuel Pégourié-Gonnardcdff3cf2013-12-12 09:55:52 +0100204 *
Rose Zadik68993282018-03-27 11:12:25 +0100205 * \see ecp.h
206 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000207 * \param ctx The ECDH context to set up.
208 * \param key The EC key to use.
Rose Zadik68993282018-03-27 11:12:25 +0100209 * \param side Defines the source of the key: 1: Our key, or
210 * 0: The key of the peer.
Rose Zadikde2d6222018-01-25 21:57:43 +0000211 *
Rose Zadik68993282018-03-27 11:12:25 +0100212 * \return \c 0 on success.
213 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200214 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
215 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Rose Zadikde2d6222018-01-25 21:57:43 +0000216 *
Manuel Pégourié-Gonnardcdff3cf2013-12-12 09:55:52 +0100217 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200218int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
219 mbedtls_ecdh_side side );
Manuel Pégourié-Gonnardcdff3cf2013-12-12 09:55:52 +0100220
221/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000222 * \brief This function generates a public key and a TLS
223 * ClientKeyExchange payload.
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100224 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000225 * This is the second function used by a TLS client for ECDH(E)
226 * ciphersuites.
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100227 *
Rose Zadik68993282018-03-27 11:12:25 +0100228 * \see ecp.h
229 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000230 * \param ctx The ECDH context.
231 * \param olen The number of Bytes written.
232 * \param buf The destination buffer.
233 * \param blen The size of the destination buffer.
234 * \param f_rng The RNG function.
Rose Zadik68993282018-03-27 11:12:25 +0100235 * \param p_rng The RNG context.
Rose Zadikde2d6222018-01-25 21:57:43 +0000236 *
Rose Zadik68993282018-03-27 11:12:25 +0100237 * \return \c 0 on success.
238 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200239 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnardc90d3b02017-04-27 10:48:29 +0200240 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100241 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200242int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100243 unsigned char *buf, size_t blen,
244 int (*f_rng)(void *, unsigned char *, size_t),
245 void *p_rng );
246
247/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000248 * \brief This function parses and processes a TLS ClientKeyExchange
249 * payload.
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100250 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000251 * This is the second function used by a TLS server for ECDH(E)
252 * ciphersuites.
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100253 *
Rose Zadik68993282018-03-27 11:12:25 +0100254 * \see ecp.h
255 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000256 * \param ctx The ECDH context.
257 * \param buf The start of the input buffer.
258 * \param blen The length of the input buffer.
259 *
Rose Zadik68993282018-03-27 11:12:25 +0100260 * \return \c 0 on success.
261 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100262 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200263int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100264 const unsigned char *buf, size_t blen );
265
266/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000267 * \brief This function derives and exports the shared secret.
Manuel Pégourié-Gonnard424fda52013-02-11 22:05:42 +0100268 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000269 * This is the last function used by both TLS client
270 * and servers.
Manuel Pégourié-Gonnard424fda52013-02-11 22:05:42 +0100271 *
Rose Zadik68993282018-03-27 11:12:25 +0100272 * \note If \p f_rng is not NULL, it is used to implement
Rose Zadik7375b0f2018-04-16 16:04:57 +0100273 * countermeasures against side-channel attacks.
274 * For more information, see mbedtls_ecp_mul().
Rose Zadik68993282018-03-27 11:12:25 +0100275 *
276 * \see ecp.h
277 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000278 * \param ctx The ECDH context.
279 * \param olen The number of Bytes written.
280 * \param buf The destination buffer.
281 * \param blen The length of the destination buffer.
282 * \param f_rng The RNG function.
Rose Zadik68993282018-03-27 11:12:25 +0100283 * \param p_rng The RNG context.
Rose Zadikde2d6222018-01-25 21:57:43 +0000284 *
Rose Zadik68993282018-03-27 11:12:25 +0100285 * \return \c 0 on success.
286 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200287 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnardc90d3b02017-04-27 10:48:29 +0200288 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Manuel Pégourié-Gonnard424fda52013-02-11 22:05:42 +0100289 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200290int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
Manuel Pégourié-Gonnarde09d2f82013-09-02 14:29:09 +0200291 unsigned char *buf, size_t blen,
292 int (*f_rng)(void *, unsigned char *, size_t),
293 void *p_rng );
Manuel Pégourié-Gonnard424fda52013-02-11 22:05:42 +0100294
Manuel Pégourié-Gonnard23e41622017-05-18 12:35:37 +0200295#if defined(MBEDTLS_ECP_RESTARTABLE)
296/**
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200297 * \brief This function enables restartable EC computations for this
298 * context. (Default: disabled.)
Manuel Pégourié-Gonnard23e41622017-05-18 12:35:37 +0200299 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200300 * \see \c mbedtls_ecp_set_max_ops()
Manuel Pégourié-Gonnard23e41622017-05-18 12:35:37 +0200301 *
302 * \note It is not possible to safely disable restartable
303 * computations once enabled, except by free-ing the context,
304 * which cancels possible in-progress operations.
305 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200306 * \param ctx The ECDH context.
Manuel Pégourié-Gonnard23e41622017-05-18 12:35:37 +0200307 */
308void mbedtls_ecdh_enable_restart( mbedtls_ecdh_context *ctx );
309#endif /* MBEDTLS_ECP_RESTARTABLE */
310
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +0100311#ifdef __cplusplus
312}
313#endif
314
Paul Bakker9af723c2014-05-01 13:03:14 +0200315#endif /* ecdh.h */