blob: cbd48414a343aa1fa2ff9367625d834eb14928c7 [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
Janos Follathc9c32f32018-08-13 15:52:45 +010039/*
40 * Use a backward compatible ECDH context.
41 *
42 * This flag is always enabled for now and future versions might add a
43 * configuration option that conditionally undefines this flag.
44 * The configuration option in question may have a different name.
45 *
46 * Features undefining this flag, must have a warning in their description in
47 * config.h stating that the feature breaks backward compatibility.
48 */
49#define MBEDTLS_ECDH_LEGACY_CONTEXT
50
Paul Bakker407a0da2013-06-27 14:29:21 +020051#ifdef __cplusplus
52extern "C" {
53#endif
54
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +010055/**
Rose Zadik68993282018-03-27 11:12:25 +010056 * Defines the source of the imported EC key.
Manuel Pégourié-Gonnardcdff3cf2013-12-12 09:55:52 +010057 */
58typedef enum
59{
Rose Zadik7375b0f2018-04-16 16:04:57 +010060 MBEDTLS_ECDH_OURS, /**< Our key. */
Rose Zadik68993282018-03-27 11:12:25 +010061 MBEDTLS_ECDH_THEIRS, /**< The key of the peer. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020062} mbedtls_ecdh_side;
Manuel Pégourié-Gonnardcdff3cf2013-12-12 09:55:52 +010063
Janos Follathc9c32f32018-08-13 15:52:45 +010064#if !defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
65/**
66 * Defines the ECDH implementation used.
67 *
68 * Later versions of the library may add new variants, therefore users should
69 * not make any assumptions about them.
70 */
71typedef enum
72{
73 MBEDTLS_ECDH_VARIANT_NONE = 0, /*!< Implementation not defined. */
74 MBEDTLS_ECDH_VARIANT_MBEDTLS_2_0,/*!< The default Mbed TLS implementation */
75} mbedtls_ecdh_variant;
76
77/**
78 * The context used by the default ECDH implementation.
79 *
80 * Later versions might change the structure of this context, therefore users
81 * should not make any assumptions about the structure of
82 * mbedtls_ecdh_context_mbed.
83 */
84typedef struct mbedtls_ecdh_context_mbed
85{
86 mbedtls_ecp_group grp; /*!< The elliptic curve used. */
87 mbedtls_mpi d; /*!< The private key. */
88 mbedtls_ecp_point Q; /*!< The public key. */
89 mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */
90 mbedtls_mpi z; /*!< The shared secret. */
91#if defined(MBEDTLS_ECP_RESTARTABLE)
92 mbedtls_ecp_restart_ctx rs; /*!< The restart context for EC computations. */
93#endif
94} mbedtls_ecdh_context_mbed;
95#endif
96
Manuel Pégourié-Gonnardcdff3cf2013-12-12 09:55:52 +010097/**
Manuel Pégourié-Gonnardeaf55be2017-08-23 14:40:21 +020098 *
99 * \warning Performing multiple operations concurrently on the same
100 * ECDSA context is not supported; objects of this type
101 * should not be shared between multiple threads.
Rose Zadikde2d6222018-01-25 21:57:43 +0000102 * \brief The ECDH context structure.
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100103 */
Dawid Drozd428cc522018-07-24 10:02:47 +0200104typedef struct mbedtls_ecdh_context
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100105{
Janos Follathc9c32f32018-08-13 15:52:45 +0100106#if defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
Rose Zadikde2d6222018-01-25 21:57:43 +0000107 mbedtls_ecp_group grp; /*!< The elliptic curve used. */
108 mbedtls_mpi d; /*!< The private key. */
109 mbedtls_ecp_point Q; /*!< The public key. */
110 mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */
111 mbedtls_mpi z; /*!< The shared secret. */
112 int point_format; /*!< The format of point export in TLS messages. */
113 mbedtls_ecp_point Vi; /*!< The blinding value. */
114 mbedtls_ecp_point Vf; /*!< The unblinding value. */
115 mbedtls_mpi _d; /*!< The previous \p d. */
Manuel Pégourié-Gonnard66ba48a2017-04-27 11:38:26 +0200116#if defined(MBEDTLS_ECP_RESTARTABLE)
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200117 int restart_enabled; /*!< The flag for restartable mode. */
118 mbedtls_ecp_restart_ctx rs; /*!< The restart context for EC computations. */
Janos Follathc9c32f32018-08-13 15:52:45 +0100119#endif /* MBEDTLS_ECP_RESTARTABLE */
120#else
121 uint8_t point_format; /*!< The format of point export in TLS messages
122 as defined in RFC 4492. */
123 mbedtls_ecp_group_id grp_id;/*!< The elliptic curve used. */
124 mbedtls_ecdh_variant var; /*!< The ECDH implementation/structure used. */
125 union
126 {
127 mbedtls_ecdh_context_mbed mbed_ecdh;
128 } ctx; /*!< Implementation-specific context. The
129 context in use is specified by the \c var
130 field. */
131#if defined(MBEDTLS_ECP_RESTARTABLE)
132 uint8_t restart_enabled; /*!< The flag for restartable mode. Functions of
133 an alternative implementation not supporting
134 restartable mode must return
135 MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED error
136 if this flag is set. */
137#endif /* MBEDTLS_ECP_RESTARTABLE */
138#endif /* MBEDTLS_ECDH_LEGACY_CONTEXT */
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100139}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200140mbedtls_ecdh_context;
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100141
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +0100142/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000143 * \brief This function generates an ECDH keypair on an elliptic
144 * curve.
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +0100145 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000146 * This function performs the first of two core computations
147 * implemented during the ECDH key exchange. The second core
148 * computation is performed by mbedtls_ecdh_compute_shared().
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +0100149 *
Rose Zadik68993282018-03-27 11:12:25 +0100150 * \see ecp.h
151 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000152 * \param grp The ECP group.
153 * \param d The destination MPI (private key).
154 * \param Q The destination point (public key).
155 * \param f_rng The RNG function.
Rose Zadik68993282018-03-27 11:12:25 +0100156 * \param p_rng The RNG context.
Rose Zadikde2d6222018-01-25 21:57:43 +0000157 *
Rose Zadik68993282018-03-27 11:12:25 +0100158 * \return \c 0 on success.
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +0200159 * \return Another \c MBEDTLS_ERR_ECP_XXX or
160 * \c MBEDTLS_MPI_XXX error code on failure.
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +0100161 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200162int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +0100163 int (*f_rng)(void *, unsigned char *, size_t),
164 void *p_rng );
165
166/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000167 * \brief This function computes the shared secret.
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +0100168 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000169 * This function performs the second of two core computations
170 * implemented during the ECDH key exchange. The first core
171 * computation is performed by mbedtls_ecdh_gen_public().
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +0100172 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000173 * \see ecp.h
174 *
175 * \note If \p f_rng is not NULL, it is used to implement
Rose Zadik7375b0f2018-04-16 16:04:57 +0100176 * countermeasures against side-channel attacks.
177 * For more information, see mbedtls_ecp_mul().
Rose Zadik68993282018-03-27 11:12:25 +0100178 *
179 * \param grp The ECP group.
180 * \param z The destination MPI (shared secret).
181 * \param Q The public key from another party.
182 * \param d Our secret exponent (private key).
183 * \param f_rng The RNG function.
184 * \param p_rng The RNG context.
185 *
186 * \return \c 0 on success.
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +0200187 * \return Another \c MBEDTLS_ERR_ECP_XXX or
188 * \c MBEDTLS_MPI_XXX error code on failure.
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +0100189 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200190int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
191 const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
Manuel Pégourié-Gonnarde09d2f82013-09-02 14:29:09 +0200192 int (*f_rng)(void *, unsigned char *, size_t),
193 void *p_rng );
Manuel Pégourié-Gonnard0bad5c22013-01-26 15:30:46 +0100194
195/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000196 * \brief This function initializes an ECDH context.
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100197 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000198 * \param ctx The ECDH context to initialize.
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100199 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200200void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100201
202/**
Janos Follathf61e4862018-10-30 11:53:25 +0000203 * \brief This function sets up the ECDH context with the information
204 * given.
205 *
206 * This function should be called after mbedtls_ecdh_init() but
207 * before mbedtls_ecdh_make_params(). There is no need to call
208 * this function before mbedtls_ecdh_read_params().
209 *
210 * This is the first function used by a TLS server for ECDHE
211 * ciphersuites.
212 *
213 * \param ctx The ECDH context to set up.
214 * \param grp_id The group id of the group to set up the context for.
215 *
216 * \return \c 0 on success.
217 */
218int mbedtls_ecdh_setup( mbedtls_ecdh_context *ctx, mbedtls_ecp_group_id grp_id );
219
220/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000221 * \brief This function frees a context.
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100222 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000223 * \param ctx The context to free.
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100224 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200225void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
Manuel Pégourié-Gonnard63533e42013-02-10 14:21:04 +0100226
227/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000228 * \brief This function generates a public key and a TLS
229 * ServerKeyExchange payload.
Manuel Pégourié-Gonnard13724762013-02-10 15:01:54 +0100230 *
Janos Follathf61e4862018-10-30 11:53:25 +0000231 * This is the second function used by a TLS server for ECDHE
232 * ciphersuites. (It is called after mbedtls_ecdh_setup().)
Manuel Pégourié-Gonnard13724762013-02-10 15:01:54 +0100233 *
Rose Zadik68993282018-03-27 11:12:25 +0100234 * \note This function assumes that the ECP group (grp) of the
235 * \p ctx context has already been properly set,
236 * for example, using mbedtls_ecp_group_load().
Manuel Pégourié-Gonnard13724762013-02-10 15:01:54 +0100237 *
Rose Zadik68993282018-03-27 11:12:25 +0100238 * \see ecp.h
239 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000240 * \param ctx The ECDH context.
241 * \param olen The number of characters written.
242 * \param buf The destination buffer.
243 * \param blen The length of the destination buffer.
244 * \param f_rng The RNG function.
Rose Zadik68993282018-03-27 11:12:25 +0100245 * \param p_rng The RNG context.
Manuel Pégourié-Gonnard13724762013-02-10 15:01:54 +0100246 *
Rose Zadik68993282018-03-27 11:12:25 +0100247 * \return \c 0 on success.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200248 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnardc90d3b02017-04-27 10:48:29 +0200249 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +0200250 * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
Manuel Pégourié-Gonnard13724762013-02-10 15:01:54 +0100251 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200252int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
Manuel Pégourié-Gonnard854fbd72013-02-11 20:28:55 +0100253 unsigned char *buf, size_t blen,
254 int (*f_rng)(void *, unsigned char *, size_t),
255 void *p_rng );
256
257/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000258 * \brief This function parses and processes a TLS ServerKeyExhange
259 * payload.
Manuel Pégourié-Gonnard854fbd72013-02-11 20:28:55 +0100260 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000261 * This is the first function used by a TLS client for ECDHE
262 * ciphersuites.
Manuel Pégourié-Gonnard854fbd72013-02-11 20:28:55 +0100263 *
Rose Zadik68993282018-03-27 11:12:25 +0100264 * \see ecp.h
265 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000266 * \param ctx The ECDH context.
267 * \param buf The pointer to the start of the input buffer.
268 * \param end The address for one Byte past the end of the buffer.
269 *
Rose Zadik68993282018-03-27 11:12:25 +0100270 * \return \c 0 on success.
271 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
Rose Zadikde2d6222018-01-25 21:57:43 +0000272 *
Manuel Pégourié-Gonnard854fbd72013-02-11 20:28:55 +0100273 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200274int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
Manuel Pégourié-Gonnard854fbd72013-02-11 20:28:55 +0100275 const unsigned char **buf, const unsigned char *end );
Manuel Pégourié-Gonnard13724762013-02-10 15:01:54 +0100276
277/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000278 * \brief This function sets up an ECDH context from an EC key.
Manuel Pégourié-Gonnardcdff3cf2013-12-12 09:55:52 +0100279 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000280 * It is used by clients and servers in place of the
281 * ServerKeyEchange for static ECDH, and imports ECDH
282 * parameters from the EC key information of a certificate.
Manuel Pégourié-Gonnardcdff3cf2013-12-12 09:55:52 +0100283 *
Rose Zadik68993282018-03-27 11:12:25 +0100284 * \see ecp.h
285 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000286 * \param ctx The ECDH context to set up.
287 * \param key The EC key to use.
Rose Zadik68993282018-03-27 11:12:25 +0100288 * \param side Defines the source of the key: 1: Our key, or
289 * 0: The key of the peer.
Rose Zadikde2d6222018-01-25 21:57:43 +0000290 *
Rose Zadik68993282018-03-27 11:12:25 +0100291 * \return \c 0 on success.
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +0200292 * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
Rose Zadikde2d6222018-01-25 21:57:43 +0000293 *
Manuel Pégourié-Gonnardcdff3cf2013-12-12 09:55:52 +0100294 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200295int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
296 mbedtls_ecdh_side side );
Manuel Pégourié-Gonnardcdff3cf2013-12-12 09:55:52 +0100297
298/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000299 * \brief This function generates a public key and a TLS
300 * ClientKeyExchange payload.
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100301 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000302 * This is the second function used by a TLS client for ECDH(E)
303 * ciphersuites.
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100304 *
Rose Zadik68993282018-03-27 11:12:25 +0100305 * \see ecp.h
306 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000307 * \param ctx The ECDH context.
308 * \param olen The number of Bytes written.
309 * \param buf The destination buffer.
310 * \param blen The size of the destination buffer.
311 * \param f_rng The RNG function.
Rose Zadik68993282018-03-27 11:12:25 +0100312 * \param p_rng The RNG context.
Rose Zadikde2d6222018-01-25 21:57:43 +0000313 *
Rose Zadik68993282018-03-27 11:12:25 +0100314 * \return \c 0 on success.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200315 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnardc90d3b02017-04-27 10:48:29 +0200316 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +0200317 * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100318 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200319int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100320 unsigned char *buf, size_t blen,
321 int (*f_rng)(void *, unsigned char *, size_t),
322 void *p_rng );
323
324/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000325 * \brief This function parses and processes a TLS ClientKeyExchange
326 * payload.
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100327 *
Janos Follathf61e4862018-10-30 11:53:25 +0000328 * This is the third function used by a TLS server for ECDH(E)
329 * ciphersuites. (It is called after mbedtls_ecdh_setup() and
330 * mbedtls_ecdh_make_params().)
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100331 *
Rose Zadik68993282018-03-27 11:12:25 +0100332 * \see ecp.h
333 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000334 * \param ctx The ECDH context.
335 * \param buf The start of the input buffer.
336 * \param blen The length of the input buffer.
337 *
Rose Zadik68993282018-03-27 11:12:25 +0100338 * \return \c 0 on success.
339 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100340 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200341int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
Manuel Pégourié-Gonnard5cceb412013-02-11 21:51:45 +0100342 const unsigned char *buf, size_t blen );
343
344/**
Rose Zadikde2d6222018-01-25 21:57:43 +0000345 * \brief This function derives and exports the shared secret.
Manuel Pégourié-Gonnard424fda52013-02-11 22:05:42 +0100346 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000347 * This is the last function used by both TLS client
348 * and servers.
Manuel Pégourié-Gonnard424fda52013-02-11 22:05:42 +0100349 *
Rose Zadik68993282018-03-27 11:12:25 +0100350 * \note If \p f_rng is not NULL, it is used to implement
Rose Zadik7375b0f2018-04-16 16:04:57 +0100351 * countermeasures against side-channel attacks.
352 * For more information, see mbedtls_ecp_mul().
Rose Zadik68993282018-03-27 11:12:25 +0100353 *
354 * \see ecp.h
355 *
Rose Zadikde2d6222018-01-25 21:57:43 +0000356 * \param ctx The ECDH context.
357 * \param olen The number of Bytes written.
358 * \param buf The destination buffer.
359 * \param blen The length of the destination buffer.
360 * \param f_rng The RNG function.
Rose Zadik68993282018-03-27 11:12:25 +0100361 * \param p_rng The RNG context.
Rose Zadikde2d6222018-01-25 21:57:43 +0000362 *
Rose Zadik68993282018-03-27 11:12:25 +0100363 * \return \c 0 on success.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200364 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnardc90d3b02017-04-27 10:48:29 +0200365 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +0200366 * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
Manuel Pégourié-Gonnard424fda52013-02-11 22:05:42 +0100367 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200368int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
Manuel Pégourié-Gonnarde09d2f82013-09-02 14:29:09 +0200369 unsigned char *buf, size_t blen,
370 int (*f_rng)(void *, unsigned char *, size_t),
371 void *p_rng );
Manuel Pégourié-Gonnard424fda52013-02-11 22:05:42 +0100372
Manuel Pégourié-Gonnard23e41622017-05-18 12:35:37 +0200373#if defined(MBEDTLS_ECP_RESTARTABLE)
374/**
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200375 * \brief This function enables restartable EC computations for this
376 * context. (Default: disabled.)
Manuel Pégourié-Gonnard23e41622017-05-18 12:35:37 +0200377 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200378 * \see \c mbedtls_ecp_set_max_ops()
Manuel Pégourié-Gonnard23e41622017-05-18 12:35:37 +0200379 *
380 * \note It is not possible to safely disable restartable
381 * computations once enabled, except by free-ing the context,
382 * which cancels possible in-progress operations.
383 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200384 * \param ctx The ECDH context.
Manuel Pégourié-Gonnard23e41622017-05-18 12:35:37 +0200385 */
386void mbedtls_ecdh_enable_restart( mbedtls_ecdh_context *ctx );
387#endif /* MBEDTLS_ECP_RESTARTABLE */
388
Manuel Pégourié-Gonnard6545ca72013-01-26 16:05:22 +0100389#ifdef __cplusplus
390}
391#endif
392
Paul Bakker9af723c2014-05-01 13:03:14 +0200393#endif /* ecdh.h */