blob: 913e323f12c8c8b95efab1a2140f88f9e19622cd [file] [log] [blame]
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +01001/**
2 * \file ecp.h
3 *
Rose Zadikb2e111a2018-04-20 10:13:48 +01004 * \brief This file provides an API for Elliptic Curves over GF(P) (ECP).
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +01005 *
Rose Zadikb2e111a2018-04-20 10:13:48 +01006 * The use of ECP in cryptography and TLS is defined in
7 * <em>Standards for Efficient Cryptography Group (SECG): SEC1
8 * Elliptic Curve Cryptography</em> and
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01009 * <em>RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites
10 * for Transport Layer Security (TLS)</em>.
Rose Zadika7a61552018-04-24 13:14:01 +010011 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +010012 * <em>RFC-2409: The Internet Key Exchange (IKE)</em> defines ECP
13 * group types.
Rose Zadika7a61552018-04-24 13:14:01 +010014 *
Darryl Greena40a1012018-01-05 15:33:17 +000015 */
Rose Zadikd3c9bfc2018-04-17 10:56:55 +010016
Darryl Greena40a1012018-01-05 15:33:17 +000017/*
Bence Szépkúti1e148272020-08-07 13:07:28 +020018 * Copyright The Mbed TLS Contributors
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +020019 * SPDX-License-Identifier: Apache-2.0
20 *
21 * Licensed under the Apache License, Version 2.0 (the "License"); you may
22 * not use this file except in compliance with the License.
23 * You may obtain a copy of the License at
24 *
25 * http://www.apache.org/licenses/LICENSE-2.0
26 *
27 * Unless required by applicable law or agreed to in writing, software
28 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
29 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
30 * See the License for the specific language governing permissions and
31 * limitations under the License.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010032 */
Rose Zadika7a61552018-04-24 13:14:01 +010033
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020034#ifndef MBEDTLS_ECP_H
35#define MBEDTLS_ECP_H
Mateusz Starzyk846f0212021-05-19 19:44:07 +020036#include "mbedtls/private_access.h"
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010037
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050038#if !defined(MBEDTLS_CONFIG_FILE)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010039#include "mbedtls/config.h"
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050040#else
41#include MBEDTLS_CONFIG_FILE
42#endif
43
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010044#include "mbedtls/bignum.h"
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010045
46/*
Manuel Pégourié-Gonnard7cfcea32012-11-05 10:06:12 +010047 * ECP error codes
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010048 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020049#define MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80 /**< Bad input parameters to function. */
50#define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00 /**< The buffer is too small to write to. */
Rose Zadikd3534052018-04-23 16:12:42 +010051#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< The requested feature is not available, for example, the requested curve is not supported. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020052#define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00 /**< The signature is not valid. */
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +020053#define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 /**< Memory allocation failed. */
Rose Zadikd3c9bfc2018-04-17 10:56:55 +010054#define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 /**< Generation of random value, such as ephemeral key, failed. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020055#define MBEDTLS_ERR_ECP_INVALID_KEY -0x4C80 /**< Invalid private or public key. */
Gilles Peskine5114d3e2018-03-30 07:12:15 +020056#define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH -0x4C00 /**< The buffer contains a valid signature followed by more data. */
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +020057#define MBEDTLS_ERR_ECP_IN_PROGRESS -0x4B00 /**< Operation in progress, call again with the same parameters to continue. */
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +010058
Gilles Peskine9b99a892018-09-14 18:32:19 +020059/* Flags indicating whether to include code that is specific to certain
60 * types of curves. These flags are for internal library use only. */
61#if defined(MBEDTLS_ECP_DP_SECP192R1_ENABLED) || \
62 defined(MBEDTLS_ECP_DP_SECP224R1_ENABLED) || \
63 defined(MBEDTLS_ECP_DP_SECP256R1_ENABLED) || \
64 defined(MBEDTLS_ECP_DP_SECP384R1_ENABLED) || \
65 defined(MBEDTLS_ECP_DP_SECP521R1_ENABLED) || \
Gilles Peskine9b99a892018-09-14 18:32:19 +020066 defined(MBEDTLS_ECP_DP_BP256R1_ENABLED) || \
67 defined(MBEDTLS_ECP_DP_BP384R1_ENABLED) || \
Gilles Peskinea3de08d2020-07-22 01:23:37 +020068 defined(MBEDTLS_ECP_DP_BP512R1_ENABLED) || \
69 defined(MBEDTLS_ECP_DP_SECP192K1_ENABLED) || \
70 defined(MBEDTLS_ECP_DP_SECP224K1_ENABLED) || \
71 defined(MBEDTLS_ECP_DP_SECP256K1_ENABLED)
Gilles Peskine9b99a892018-09-14 18:32:19 +020072#define MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED
73#endif
74#if defined(MBEDTLS_ECP_DP_CURVE25519_ENABLED) || \
75 defined(MBEDTLS_ECP_DP_CURVE448_ENABLED)
76#define MBEDTLS_ECP_MONTGOMERY_ENABLED
77#endif
78
Paul Bakker407a0da2013-06-27 14:29:21 +020079#ifdef __cplusplus
80extern "C" {
81#endif
82
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010083/**
Rose Zadikd76ac582018-04-23 06:29:34 +010084 * Domain-parameter identifiers: curve, subgroup, and generator.
Manuel Pégourié-Gonnard70380392013-09-16 16:19:53 +020085 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +010086 * \note Only curves over prime fields are supported.
Manuel Pégourié-Gonnard70380392013-09-16 16:19:53 +020087 *
88 * \warning This library does not support validation of arbitrary domain
Rose Zadikf56cb342018-04-19 12:49:10 +010089 * parameters. Therefore, only standardized domain parameters from trusted
Manuel Pégourié-Gonnarde3a062b2015-05-11 18:46:47 +020090 * sources should be used. See mbedtls_ecp_group_load().
Manuel Pégourié-Gonnard70380392013-09-16 16:19:53 +020091 */
Gilles Peskine963a2072018-09-14 18:31:30 +020092/* Note: when adding a new curve:
93 * - Add it at the end of this enum, otherwise you'll break the ABI by
94 * changing the numerical value for existing curves.
Gilles Peskine6d9c8d72020-07-22 01:26:25 +020095 * - Increment MBEDTLS_ECP_DP_MAX below if needed.
Gilles Peskine963a2072018-09-14 18:31:30 +020096 * - Add the corresponding MBEDTLS_ECP_DP_xxx_ENABLED macro definition to
97 * config.h.
98 * - List the curve as a dependency of MBEDTLS_ECP_C and
99 * MBEDTLS_ECDSA_C if supported in check_config.h.
100 * - Add the curve to the appropriate curve type macro
101 * MBEDTLS_ECP_yyy_ENABLED above.
102 * - Add the necessary definitions to ecp_curves.c.
103 * - Add the curve to the ecp_supported_curves array in ecp.c.
104 * - Add the curve to applicable profiles in x509_crt.c if applicable.
105 */
Manuel Pégourié-Gonnard70380392013-09-16 16:19:53 +0200106typedef enum
107{
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100108 MBEDTLS_ECP_DP_NONE = 0, /*!< Curve not defined. */
Rose Zadikb2e111a2018-04-20 10:13:48 +0100109 MBEDTLS_ECP_DP_SECP192R1, /*!< Domain parameters for the 192-bit curve defined by FIPS 186-4 and SEC1. */
110 MBEDTLS_ECP_DP_SECP224R1, /*!< Domain parameters for the 224-bit curve defined by FIPS 186-4 and SEC1. */
111 MBEDTLS_ECP_DP_SECP256R1, /*!< Domain parameters for the 256-bit curve defined by FIPS 186-4 and SEC1. */
112 MBEDTLS_ECP_DP_SECP384R1, /*!< Domain parameters for the 384-bit curve defined by FIPS 186-4 and SEC1. */
113 MBEDTLS_ECP_DP_SECP521R1, /*!< Domain parameters for the 521-bit curve defined by FIPS 186-4 and SEC1. */
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100114 MBEDTLS_ECP_DP_BP256R1, /*!< Domain parameters for 256-bit Brainpool curve. */
115 MBEDTLS_ECP_DP_BP384R1, /*!< Domain parameters for 384-bit Brainpool curve. */
116 MBEDTLS_ECP_DP_BP512R1, /*!< Domain parameters for 512-bit Brainpool curve. */
Rose Zadikb2e111a2018-04-20 10:13:48 +0100117 MBEDTLS_ECP_DP_CURVE25519, /*!< Domain parameters for Curve25519. */
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100118 MBEDTLS_ECP_DP_SECP192K1, /*!< Domain parameters for 192-bit "Koblitz" curve. */
119 MBEDTLS_ECP_DP_SECP224K1, /*!< Domain parameters for 224-bit "Koblitz" curve. */
120 MBEDTLS_ECP_DP_SECP256K1, /*!< Domain parameters for 256-bit "Koblitz" curve. */
Jaeden Amerofe0669f2018-04-27 17:43:32 +0100121 MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for Curve448. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200122} mbedtls_ecp_group_id;
Manuel Pégourié-Gonnard70380392013-09-16 16:19:53 +0200123
124/**
Rose Zadikf56cb342018-04-19 12:49:10 +0100125 * The number of supported curves, plus one for #MBEDTLS_ECP_DP_NONE.
Manuel Pégourié-Gonnard66153662013-12-03 14:12:26 +0100126 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100127 * \note Montgomery curves are currently excluded.
Manuel Pégourié-Gonnardf24b4a72013-09-23 18:14:50 +0200128 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200129#define MBEDTLS_ECP_DP_MAX 12
Manuel Pégourié-Gonnardf24b4a72013-09-23 18:14:50 +0200130
Janos Follathdf9295b2019-02-26 12:36:52 +0000131/*
132 * Curve types
133 */
134typedef enum
135{
136 MBEDTLS_ECP_TYPE_NONE = 0,
137 MBEDTLS_ECP_TYPE_SHORT_WEIERSTRASS, /* y^2 = x^3 + a x + b */
138 MBEDTLS_ECP_TYPE_MONTGOMERY, /* y^2 = x^3 + a x^2 + x */
139} mbedtls_ecp_curve_type;
140
Manuel Pégourié-Gonnardf24b4a72013-09-23 18:14:50 +0200141/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100142 * Curve information, for use by other modules.
Manuel Pégourié-Gonnard568c9cf2013-09-16 17:30:04 +0200143 */
Dawid Drozd428cc522018-07-24 10:02:47 +0200144typedef struct mbedtls_ecp_curve_info
Manuel Pégourié-Gonnard568c9cf2013-09-16 17:30:04 +0200145{
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200146 mbedtls_ecp_group_id MBEDTLS_PRIVATE(grp_id); /*!< An internal identifier. */
147 uint16_t MBEDTLS_PRIVATE(tls_id); /*!< The TLS NamedCurve identifier. */
148 uint16_t MBEDTLS_PRIVATE(bit_size); /*!< The curve size in bits. */
149 const char *MBEDTLS_PRIVATE(name); /*!< A human-friendly name. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200150} mbedtls_ecp_curve_info;
Manuel Pégourié-Gonnard568c9cf2013-09-16 17:30:04 +0200151
152/**
Rose Zadikf56cb342018-04-19 12:49:10 +0100153 * \brief The ECP point structure, in Jacobian coordinates.
Manuel Pégourié-Gonnardae180d02012-11-02 18:14:40 +0100154 *
Manuel Pégourié-Gonnard1c2782c2012-11-19 20:16:28 +0100155 * \note All functions expect and return points satisfying
Rose Zadikf56cb342018-04-19 12:49:10 +0100156 * the following condition: <code>Z == 0</code> or
Rose Zadika7a61552018-04-24 13:14:01 +0100157 * <code>Z == 1</code>. Other values of \p Z are
Rose Zadikf56cb342018-04-19 12:49:10 +0100158 * used only by internal functions.
159 * The point is zero, or "at infinity", if <code>Z == 0</code>.
Rose Zadika7a61552018-04-24 13:14:01 +0100160 * Otherwise, \p X and \p Y are its standard (affine)
Rose Zadikf56cb342018-04-19 12:49:10 +0100161 * coordinates.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100162 */
Dawid Drozd428cc522018-07-24 10:02:47 +0200163typedef struct mbedtls_ecp_point
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100164{
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200165 mbedtls_mpi MBEDTLS_PRIVATE(X); /*!< The X coordinate of the ECP point. */
166 mbedtls_mpi MBEDTLS_PRIVATE(Y); /*!< The Y coordinate of the ECP point. */
167 mbedtls_mpi MBEDTLS_PRIVATE(Z); /*!< The Z coordinate of the ECP point. */
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100168}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200169mbedtls_ecp_point;
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100170
171#if !defined(MBEDTLS_ECP_ALT)
172/*
173 * default mbed TLS elliptic curve arithmetic implementation
174 *
175 * (in case MBEDTLS_ECP_ALT is defined then the developer has to provide an
176 * alternative implementation for the whole module and it will replace this
177 * one.)
178 */
179
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100180/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100181 * \brief The ECP group structure.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100182 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100183 * We consider two types of curve equations:
Rose Zadikb2e111a2018-04-20 10:13:48 +0100184 * <ul><li>Short Weierstrass: <code>y^2 = x^3 + A x + B mod P</code>
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100185 * (SEC1 + RFC-4492)</li>
Rose Zadikf56cb342018-04-19 12:49:10 +0100186 * <li>Montgomery: <code>y^2 = x^3 + A x^2 + x mod P</code> (Curve25519,
Rose Zadikb2e111a2018-04-20 10:13:48 +0100187 * Curve448)</li></ul>
Rose Zadikf56cb342018-04-19 12:49:10 +0100188 * In both cases, the generator (\p G) for a prime-order subgroup is fixed.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100189 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100190 * For Short Weierstrass, this subgroup is the whole curve, and its
Rose Zadikf56cb342018-04-19 12:49:10 +0100191 * cardinality is denoted by \p N. Our code requires that \p N is an
Rose Zadikb2e111a2018-04-20 10:13:48 +0100192 * odd prime as mbedtls_ecp_mul() requires an odd number, and
193 * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100194 *
Rose Zadikf56cb342018-04-19 12:49:10 +0100195 * For Montgomery curves, we do not store \p A, but <code>(A + 2) / 4</code>,
Rose Zadika7a61552018-04-24 13:14:01 +0100196 * which is the quantity used in the formulas. Additionally, \p nbits is
Rose Zadikf56cb342018-04-19 12:49:10 +0100197 * not the size of \p N but the required size for private keys.
Manuel Pégourié-Gonnard47123252012-11-10 14:44:24 +0100198 *
Rose Zadika7a61552018-04-24 13:14:01 +0100199 * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm.
200 * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the
201 * range of <code>0..2^(2*pbits)-1</code>, and transforms it in-place to an integer
202 * which is congruent mod \p P to the given MPI, and is close enough to \p pbits
203 * in size, so that it may be efficiently brought in the 0..P-1 range by a few
204 * additions or subtractions. Therefore, it is only an approximative modular
205 * reduction. It must return 0 on success and non-zero on failure.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100206 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500207 * \note Alternative implementations must keep the group IDs distinct. If
208 * two group structures have the same ID, then they must be
209 * identical.
210 *
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100211 */
Dawid Drozd428cc522018-07-24 10:02:47 +0200212typedef struct mbedtls_ecp_group
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100213{
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200214 mbedtls_ecp_group_id MBEDTLS_PRIVATE(id); /*!< An internal group identifier. */
215 mbedtls_mpi MBEDTLS_PRIVATE(P); /*!< The prime modulus of the base field. */
216 mbedtls_mpi MBEDTLS_PRIVATE(A); /*!< For Short Weierstrass: \p A in the equation. For
Rose Zadikb2e111a2018-04-20 10:13:48 +0100217 Montgomery curves: <code>(A + 2) / 4</code>. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200218 mbedtls_mpi MBEDTLS_PRIVATE(B); /*!< For Short Weierstrass: \p B in the equation.
Rose Zadikb2e111a2018-04-20 10:13:48 +0100219 For Montgomery curves: unused. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200220 mbedtls_ecp_point MBEDTLS_PRIVATE(G); /*!< The generator of the subgroup used. */
221 mbedtls_mpi MBEDTLS_PRIVATE(N); /*!< The order of \p G. */
222 size_t MBEDTLS_PRIVATE(pbits); /*!< The number of bits in \p P.*/
223 size_t MBEDTLS_PRIVATE(nbits); /*!< For Short Weierstrass: The number of bits in \p P.
Rose Zadika7a61552018-04-24 13:14:01 +0100224 For Montgomery curves: the number of bits in the
Rose Zadikd76ac582018-04-23 06:29:34 +0100225 private keys. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200226 unsigned int MBEDTLS_PRIVATE(h); /*!< \internal 1 if the constants are static. */
227 int (*MBEDTLS_PRIVATE(modp))(mbedtls_mpi *); /*!< The function for fast pseudo-reduction
Rose Zadikf56cb342018-04-19 12:49:10 +0100228 mod \p P (see above).*/
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200229 int (*MBEDTLS_PRIVATE(t_pre))(mbedtls_ecp_point *, void *); /*!< Unused. */
230 int (*MBEDTLS_PRIVATE(t_post))(mbedtls_ecp_point *, void *); /*!< Unused. */
231 void *MBEDTLS_PRIVATE(t_data); /*!< Unused. */
232 mbedtls_ecp_point *MBEDTLS_PRIVATE(T); /*!< Pre-computed points for ecp_mul_comb(). */
233 size_t MBEDTLS_PRIVATE(T_size); /*!< The number of pre-computed points. */
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100234}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200235mbedtls_ecp_group;
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100236
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500237/**
238 * \name SECTION: Module settings
239 *
240 * The configuration options you can set for this module are in this section.
241 * Either change them in config.h, or define them using the compiler command line.
242 * \{
243 */
244
245#if !defined(MBEDTLS_ECP_MAX_BITS)
246/**
247 * The maximum size of the groups, that is, of \c N and \c P.
248 */
249#define MBEDTLS_ECP_MAX_BITS 521 /**< The maximum size of groups, in bits. */
250#endif
251
252#define MBEDTLS_ECP_MAX_BYTES ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 )
253#define MBEDTLS_ECP_MAX_PT_LEN ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 )
254
255#if !defined(MBEDTLS_ECP_WINDOW_SIZE)
256/*
257 * Maximum "window" size used for point multiplication.
258 * Default: 6.
259 * Minimum value: 2. Maximum value: 7.
260 *
261 * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) )
262 * points used for point multiplication. This value is directly tied to EC
263 * peak memory usage, so decreasing it by one should roughly cut memory usage
264 * by two (if large curves are in use).
265 *
266 * Reduction in size may reduce speed, but larger curves are impacted first.
267 * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1):
268 * w-size: 6 5 4 3 2
269 * 521 145 141 135 120 97
270 * 384 214 209 198 177 146
271 * 256 320 320 303 262 226
272 * 224 475 475 453 398 342
273 * 192 640 640 633 587 476
274 */
275#define MBEDTLS_ECP_WINDOW_SIZE 6 /**< The maximum window size used. */
276#endif /* MBEDTLS_ECP_WINDOW_SIZE */
277
278#if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)
279/*
280 * Trade memory for speed on fixed-point multiplication.
281 *
282 * This speeds up repeated multiplication of the generator (that is, the
283 * multiplication in ECDSA signatures, and half of the multiplications in
284 * ECDSA verification and ECDHE) by a factor roughly 3 to 4.
285 *
286 * The cost is increasing EC peak memory usage by a factor roughly 2.
287 *
288 * Change this value to 0 to reduce peak memory usage.
289 */
290#define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up. */
291#endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */
292
293/* \} name SECTION: Module settings */
294
295#else /* MBEDTLS_ECP_ALT */
296#include "ecp_alt.h"
297#endif /* MBEDTLS_ECP_ALT */
298
Manuel Pégourié-Gonnard4b9c51e2017-04-20 15:50:26 +0200299#if defined(MBEDTLS_ECP_RESTARTABLE)
Manuel Pégourié-Gonnardb5a50e72017-04-20 16:06:13 +0200300
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200301/**
Manuel Pégourié-Gonnard3cade222017-04-20 09:31:00 +0200302 * \brief Internal restart context for multiplication
303 *
304 * \note Opaque struct
305 */
306typedef struct mbedtls_ecp_restart_mul mbedtls_ecp_restart_mul_ctx;
307
308/**
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +0200309 * \brief Internal restart context for ecp_muladd()
310 *
311 * \note Opaque struct
312 */
313typedef struct mbedtls_ecp_restart_muladd mbedtls_ecp_restart_muladd_ctx;
314
315/**
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200316 * \brief General context for resuming ECC operations
317 */
318typedef struct
319{
Manuel Pégourié-Gonnard646393b2017-04-20 10:03:45 +0200320 unsigned ops_done; /*!< current ops count */
Manuel Pégourié-Gonnard3a256122017-04-20 11:20:26 +0200321 unsigned depth; /*!< call depth (0 = top-level) */
Manuel Pégourié-Gonnard646393b2017-04-20 10:03:45 +0200322 mbedtls_ecp_restart_mul_ctx *rsm; /*!< ecp_mul_comb() sub-context */
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +0200323 mbedtls_ecp_restart_muladd_ctx *ma; /*!< ecp_muladd() sub-context */
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200324} mbedtls_ecp_restart_ctx;
Manuel Pégourié-Gonnardb5a50e72017-04-20 16:06:13 +0200325
Manuel Pégourié-Gonnardc7511482017-04-20 16:31:00 +0200326/*
327 * Operation counts for restartable functions
328 */
Manuel Pégourié-Gonnard5314f232017-04-21 12:36:59 +0200329#define MBEDTLS_ECP_OPS_CHK 3 /*!< basic ops count for ecp_check_pubkey() */
Manuel Pégourié-Gonnardc7511482017-04-20 16:31:00 +0200330#define MBEDTLS_ECP_OPS_DBL 8 /*!< basic ops count for ecp_double_jac() */
331#define MBEDTLS_ECP_OPS_ADD 11 /*!< basic ops count for see ecp_add_mixed() */
332#define MBEDTLS_ECP_OPS_INV 120 /*!< empirical equivalent for mpi_mod_inv() */
333
334/**
335 * \brief Internal; for restartable functions in other modules.
336 * Check and update basic ops budget.
337 *
338 * \param grp Group structure
339 * \param rs_ctx Restart context
340 * \param ops Number of basic ops to do
341 *
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200342 * \return \c 0 if doing \p ops basic ops is still allowed,
343 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS otherwise.
Manuel Pégourié-Gonnardc7511482017-04-20 16:31:00 +0200344 */
345int mbedtls_ecp_check_budget( const mbedtls_ecp_group *grp,
346 mbedtls_ecp_restart_ctx *rs_ctx,
347 unsigned ops );
348
349/* Utility macro for checking and updating ops budget */
Hanno Beckerabdf67e2018-10-26 13:28:32 +0100350#define MBEDTLS_ECP_BUDGET( ops ) \
351 MBEDTLS_MPI_CHK( mbedtls_ecp_check_budget( grp, rs_ctx, \
352 (unsigned) (ops) ) );
Manuel Pégourié-Gonnardc7511482017-04-20 16:31:00 +0200353
Manuel Pégourié-Gonnardb5a50e72017-04-20 16:06:13 +0200354#else /* MBEDTLS_ECP_RESTARTABLE */
355
Manuel Pégourié-Gonnardc7511482017-04-20 16:31:00 +0200356#define MBEDTLS_ECP_BUDGET( ops ) /* no-op; for compatibility */
357
Manuel Pégourié-Gonnardb5a50e72017-04-20 16:06:13 +0200358/* We want to declare restartable versions of existing functions anyway */
359typedef void mbedtls_ecp_restart_ctx;
360
Manuel Pégourié-Gonnard4b9c51e2017-04-20 15:50:26 +0200361#endif /* MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200362
Paul Bakker088c5c52014-04-25 11:11:10 +0200363/**
Jaeden Amero89453432018-04-24 17:15:38 +0100364 * \brief The ECP key-pair structure.
Ron Eldor05d0e512018-04-16 17:40:04 +0300365 *
Jaeden Amero89453432018-04-24 17:15:38 +0100366 * A generic key-pair that may be used for ECDSA and fixed ECDH, for example.
Ron Eldor05d0e512018-04-16 17:40:04 +0300367 *
Jaeden Amero89453432018-04-24 17:15:38 +0100368 * \note Members are deliberately in the same order as in the
369 * ::mbedtls_ecdsa_context structure.
Ron Eldor05d0e512018-04-16 17:40:04 +0300370 */
Dawid Drozd428cc522018-07-24 10:02:47 +0200371typedef struct mbedtls_ecp_keypair
Ron Eldor05d0e512018-04-16 17:40:04 +0300372{
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200373 mbedtls_ecp_group MBEDTLS_PRIVATE(grp); /*!< Elliptic curve and base point */
374 mbedtls_mpi MBEDTLS_PRIVATE(d); /*!< our secret value */
375 mbedtls_ecp_point MBEDTLS_PRIVATE(Q); /*!< our public value */
Ron Eldor05d0e512018-04-16 17:40:04 +0300376}
377mbedtls_ecp_keypair;
378
Manuel Pégourié-Gonnard37d218a2012-11-24 15:19:55 +0100379/*
Manuel Pégourié-Gonnard00794052013-02-09 19:00:07 +0100380 * Point formats, from RFC 4492's enum ECPointFormat
Manuel Pégourié-Gonnard37d218a2012-11-24 15:19:55 +0100381 */
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100382#define MBEDTLS_ECP_PF_UNCOMPRESSED 0 /**< Uncompressed point format. */
383#define MBEDTLS_ECP_PF_COMPRESSED 1 /**< Compressed point format. */
Manuel Pégourié-Gonnard37d218a2012-11-24 15:19:55 +0100384
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100385/*
Manuel Pégourié-Gonnard00794052013-02-09 19:00:07 +0100386 * Some other constants from RFC 4492
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100387 */
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100388#define MBEDTLS_ECP_TLS_NAMED_CURVE 3 /**< The named_curve of ECCurveType. */
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100389
Manuel Pégourié-Gonnard4b9c51e2017-04-20 15:50:26 +0200390#if defined(MBEDTLS_ECP_RESTARTABLE)
Manuel Pégourié-Gonnard054433c2017-03-22 11:18:33 +0100391/**
392 * \brief Set the maximum number of basic operations done in a row.
393 *
394 * If more operations are needed to complete a computation,
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200395 * #MBEDTLS_ERR_ECP_IN_PROGRESS will be returned by the
Manuel Pégourié-Gonnard8467e682017-04-20 09:47:06 +0200396 * function performing the computation. It is then the
397 * caller's responsibility to either call again with the same
Manuel Pégourié-Gonnard7037e222017-08-23 14:30:36 +0200398 * parameters until it returns 0 or an error code; or to free
Manuel Pégourié-Gonnard8467e682017-04-20 09:47:06 +0200399 * the restart context if the operation is to be aborted.
Manuel Pégourié-Gonnard054433c2017-03-22 11:18:33 +0100400 *
Manuel Pégourié-Gonnard7037e222017-08-23 14:30:36 +0200401 * It is strictly required that all input parameters and the
402 * restart context be the same on successive calls for the
403 * same operation, but output parameters need not be the
404 * same; they must not be used until the function finally
405 * returns 0.
406 *
Gilles Peskine1174db52020-02-26 19:52:06 +0100407 * This only applies to functions whose documentation
408 * mentions they may return #MBEDTLS_ERR_ECP_IN_PROGRESS (or
409 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS for functions in the
410 * SSL module). For functions that accept a "restart context"
411 * argument, passing NULL disables restart and makes the
412 * function equivalent to the function with the same name
Manuel Pégourié-Gonnard32df9112018-10-15 13:29:21 +0200413 * with \c _restartable removed. For functions in the ECDH
Gilles Peskine1174db52020-02-26 19:52:06 +0100414 * module, restart is disabled unless the function accepts
415 * an "ECDH context" argument and
416 * mbedtls_ecdh_enable_restart() was previously called on
417 * that context. For function in the SSL module, restart is
418 * only enabled for specific sides and key exchanges
419 * (currently only for clients and ECDHE-ECDSA).
Manuel Pégourié-Gonnard8f28add2017-04-19 10:20:49 +0200420 *
Manuel Pégourié-Gonnard054433c2017-03-22 11:18:33 +0100421 * \param max_ops Maximum number of basic operations done in a row.
422 * Default: 0 (unlimited).
423 * Lower (non-zero) values mean ECC functions will block for
424 * a lesser maximum amount of time.
425 *
Manuel Pégourié-Gonnarde6854492017-03-20 14:35:19 +0100426 * \note A "basic operation" is defined as a rough equivalent of a
427 * multiplication in GF(p) for the NIST P-256 curve.
428 * As an indication, with default settings, a scalar
429 * multiplication (full run of \c mbedtls_ecp_mul()) is:
430 * - about 3300 basic operations for P-256
431 * - about 9400 basic operations for P-384
Manuel Pégourié-Gonnard054433c2017-03-22 11:18:33 +0100432 *
Manuel Pégourié-Gonnarde58f65a2017-03-20 14:59:54 +0100433 * \note Very low values are not always respected: sometimes
Manuel Pégourié-Gonnard1c678e02017-03-20 13:39:39 +0100434 * functions need to block for a minimum number of
435 * operations, and will do so even if max_ops is set to a
436 * lower value. That minimum depends on the curve size, and
437 * can be made lower by decreasing the value of
Manuel Pégourié-Gonnard7037e222017-08-23 14:30:36 +0200438 * \c MBEDTLS_ECP_WINDOW_SIZE. As an indication, here is the
439 * lowest effective value for various curves and values of
440 * that parameter (w for short):
441 * w=6 w=5 w=4 w=3 w=2
442 * P-256 208 208 160 136 124
443 * P-384 682 416 320 272 248
444 * P-521 1364 832 640 544 496
Manuel Pégourié-Gonnarde58f65a2017-03-20 14:59:54 +0100445 *
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200446 * \note This setting is currently ignored by Curve25519.
Manuel Pégourié-Gonnard054433c2017-03-22 11:18:33 +0100447 */
448void mbedtls_ecp_set_max_ops( unsigned max_ops );
Manuel Pégourié-Gonnarda0c5bcc2017-04-21 11:33:57 +0200449
450/**
451 * \brief Check if restart is enabled (max_ops != 0)
452 *
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200453 * \return \c 0 if \c max_ops == 0 (restart disabled)
454 * \return \c 1 otherwise (restart enabled)
Manuel Pégourié-Gonnarda0c5bcc2017-04-21 11:33:57 +0200455 */
Manuel Pégourié-Gonnardb843b152018-10-16 10:41:31 +0200456int mbedtls_ecp_restart_is_enabled( void );
Manuel Pégourié-Gonnard4b9c51e2017-04-20 15:50:26 +0200457#endif /* MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnard054433c2017-03-22 11:18:33 +0100458
Janos Follathdf9295b2019-02-26 12:36:52 +0000459/*
460 * Get the type of a curve
461 */
462mbedtls_ecp_curve_type mbedtls_ecp_get_type( const mbedtls_ecp_group *grp );
463
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100464/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100465 * \brief This function retrieves the information defined in
Rose Zadikf56cb342018-04-19 12:49:10 +0100466 * mbedtls_ecp_curve_info() for all supported curves in order
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100467 * of preference.
Manuel Pégourié-Gonnardda179e42013-09-18 15:31:24 +0200468 *
Gilles Peskined2085f52019-02-11 18:43:55 +0100469 * \note This function returns information about all curves
470 * supported by the library. Some curves may not be
471 * supported for all algorithms. Call mbedtls_ecdh_can_do()
472 * or mbedtls_ecdsa_can_do() to check if a curve is
473 * supported for ECDH or ECDSA.
474 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100475 * \return A statically allocated array. The last entry is 0.
Manuel Pégourié-Gonnardda179e42013-09-18 15:31:24 +0200476 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200477const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void );
Manuel Pégourié-Gonnardda179e42013-09-18 15:31:24 +0200478
479/**
Rose Zadikf56cb342018-04-19 12:49:10 +0100480 * \brief This function retrieves the list of internal group
481 * identifiers of all supported curves in the order of
482 * preference.
Manuel Pégourié-Gonnardac719412014-02-04 14:48:50 +0100483 *
Gilles Peskined2085f52019-02-11 18:43:55 +0100484 * \note This function returns information about all curves
485 * supported by the library. Some curves may not be
486 * supported for all algorithms. Call mbedtls_ecdh_can_do()
487 * or mbedtls_ecdsa_can_do() to check if a curve is
488 * supported for ECDH or ECDSA.
489 *
Manuel Pégourié-Gonnardac719412014-02-04 14:48:50 +0100490 * \return A statically allocated array,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200491 * terminated with MBEDTLS_ECP_DP_NONE.
Manuel Pégourié-Gonnardac719412014-02-04 14:48:50 +0100492 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200493const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void );
Manuel Pégourié-Gonnardac719412014-02-04 14:48:50 +0100494
495/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100496 * \brief This function retrieves curve information from an internal
497 * group identifier.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200498 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100499 * \param grp_id An \c MBEDTLS_ECP_DP_XXX value.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200500 *
Rose Zadikf56cb342018-04-19 12:49:10 +0100501 * \return The associated curve information on success.
502 * \return NULL on failure.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200503 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200504const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id );
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200505
506/**
Rose Zadika7a61552018-04-24 13:14:01 +0100507 * \brief This function retrieves curve information from a TLS
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100508 * NamedCurve value.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200509 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100510 * \param tls_id An \c MBEDTLS_ECP_DP_XXX value.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200511 *
Rose Zadikf56cb342018-04-19 12:49:10 +0100512 * \return The associated curve information on success.
513 * \return NULL on failure.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200514 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200515const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id );
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200516
517/**
Rose Zadika7a61552018-04-24 13:14:01 +0100518 * \brief This function retrieves curve information from a
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100519 * human-readable name.
Manuel Pégourié-Gonnard0267e3d2013-11-30 15:10:14 +0100520 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100521 * \param name The human-readable name.
Manuel Pégourié-Gonnard0267e3d2013-11-30 15:10:14 +0100522 *
Rose Zadikf56cb342018-04-19 12:49:10 +0100523 * \return The associated curve information on success.
524 * \return NULL on failure.
Manuel Pégourié-Gonnard0267e3d2013-11-30 15:10:14 +0100525 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200526const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name );
Manuel Pégourié-Gonnard0267e3d2013-11-30 15:10:14 +0100527
528/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100529 * \brief This function initializes a point as zero.
530 *
531 * \param pt The point to initialize.
Manuel Pégourié-Gonnardae180d02012-11-02 18:14:40 +0100532 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200533void mbedtls_ecp_point_init( mbedtls_ecp_point *pt );
Manuel Pégourié-Gonnardae180d02012-11-02 18:14:40 +0100534
535/**
Rose Zadikf56cb342018-04-19 12:49:10 +0100536 * \brief This function initializes an ECP group context
Rose Zadika7a61552018-04-24 13:14:01 +0100537 * without loading any domain parameters.
Rose Zadikf56cb342018-04-19 12:49:10 +0100538 *
539 * \note After this function is called, domain parameters
540 * for various ECP groups can be loaded through the
Gilles Peskine13cf3ec2018-11-07 22:06:48 +0100541 * mbedtls_ecp_group_load() or mbedtls_ecp_tls_read_group()
Rose Zadikf56cb342018-04-19 12:49:10 +0100542 * functions.
Manuel Pégourié-Gonnardb505c272012-11-05 17:27:54 +0100543 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200544void mbedtls_ecp_group_init( mbedtls_ecp_group *grp );
Manuel Pégourié-Gonnardb505c272012-11-05 17:27:54 +0100545
546/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100547 * \brief This function initializes a key pair as an invalid one.
548 *
549 * \param key The key pair to initialize.
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200550 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200551void mbedtls_ecp_keypair_init( mbedtls_ecp_keypair *key );
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200552
553/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100554 * \brief This function frees the components of a point.
555 *
556 * \param pt The point to free.
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100557 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200558void mbedtls_ecp_point_free( mbedtls_ecp_point *pt );
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100559
560/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100561 * \brief This function frees the components of an ECP group.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500562 *
563 * \param grp The group to free. This may be \c NULL, in which
564 * case this function returns immediately. If it is not
565 * \c NULL, it must point to an initialized ECP group.
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100566 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200567void mbedtls_ecp_group_free( mbedtls_ecp_group *grp );
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100568
569/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100570 * \brief This function frees the components of a key pair.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500571 *
572 * \param key The key pair to free. This may be \c NULL, in which
573 * case this function returns immediately. If it is not
574 * \c NULL, it must point to an initialized ECP key pair.
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200575 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200576void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key );
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200577
Manuel Pégourié-Gonnard4b9c51e2017-04-20 15:50:26 +0200578#if defined(MBEDTLS_ECP_RESTARTABLE)
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200579/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500580 * \brief Initialize a restart context.
581 *
582 * \param ctx The restart context to initialize. This must
583 * not be \c NULL.
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200584 */
585void mbedtls_ecp_restart_init( mbedtls_ecp_restart_ctx *ctx );
586
587/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500588 * \brief Free the components of a restart context.
589 *
590 * \param ctx The restart context to free. This may be \c NULL, in which
591 * case this function returns immediately. If it is not
592 * \c NULL, it must point to an initialized restart context.
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200593 */
594void mbedtls_ecp_restart_free( mbedtls_ecp_restart_ctx *ctx );
Manuel Pégourié-Gonnard4b9c51e2017-04-20 15:50:26 +0200595#endif /* MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200596
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200597/**
Rose Zadika7a61552018-04-24 13:14:01 +0100598 * \brief This function copies the contents of point \p Q into
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100599 * point \p P.
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100600 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500601 * \param P The destination point. This must be initialized.
602 * \param Q The source point. This must be initialized.
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100603 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100604 * \return \c 0 on success.
Rose Zadikf56cb342018-04-19 12:49:10 +0100605 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500606 * \return Another negative error code for other kinds of failure.
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100607 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200608int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q );
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100609
610/**
Rose Zadika7a61552018-04-24 13:14:01 +0100611 * \brief This function copies the contents of group \p src into
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100612 * group \p dst.
Manuel Pégourié-Gonnarde09631b2013-08-12 15:44:31 +0200613 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500614 * \param dst The destination group. This must be initialized.
615 * \param src The source group. This must be initialized.
Manuel Pégourié-Gonnarde09631b2013-08-12 15:44:31 +0200616 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100617 * \return \c 0 on success.
Rose Zadikf56cb342018-04-19 12:49:10 +0100618 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500619 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnarde09631b2013-08-12 15:44:31 +0200620 */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500621int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst,
622 const mbedtls_ecp_group *src );
Manuel Pégourié-Gonnarde09631b2013-08-12 15:44:31 +0200623
624/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500625 * \brief This function sets a point to the point at infinity.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200626 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500627 * \param pt The point to set. This must be initialized.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200628 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100629 * \return \c 0 on success.
Rose Zadikf56cb342018-04-19 12:49:10 +0100630 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500631 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200632 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200633int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt );
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200634
635/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500636 * \brief This function checks if a point is the point at infinity.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200637 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500638 * \param pt The point to test. This must be initialized.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200639 *
Rose Zadikf56cb342018-04-19 12:49:10 +0100640 * \return \c 1 if the point is zero.
641 * \return \c 0 if the point is non-zero.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500642 * \return A negative error code on failure.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200643 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200644int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt );
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200645
646/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100647 * \brief This function compares two points.
Manuel Pégourié-Gonnard6029a852015-08-11 15:44:41 +0200648 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100649 * \note This assumes that the points are normalized. Otherwise,
Manuel Pégourié-Gonnard6029a852015-08-11 15:44:41 +0200650 * they may compare as "not equal" even if they are.
651 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500652 * \param P The first point to compare. This must be initialized.
653 * \param Q The second point to compare. This must be initialized.
Manuel Pégourié-Gonnard6029a852015-08-11 15:44:41 +0200654 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100655 * \return \c 0 if the points are equal.
656 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal.
Manuel Pégourié-Gonnard6029a852015-08-11 15:44:41 +0200657 */
658int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P,
659 const mbedtls_ecp_point *Q );
660
661/**
Rose Zadika7a61552018-04-24 13:14:01 +0100662 * \brief This function imports a non-zero point from two ASCII
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100663 * strings.
Manuel Pégourié-Gonnard847395a2012-11-05 13:13:44 +0100664 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500665 * \param P The destination point. This must be initialized.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100666 * \param radix The numeric base of the input.
667 * \param x The first affine coordinate, as a null-terminated string.
668 * \param y The second affine coordinate, as a null-terminated string.
Manuel Pégourié-Gonnard847395a2012-11-05 13:13:44 +0100669 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100670 * \return \c 0 on success.
671 * \return An \c MBEDTLS_ERR_MPI_XXX error code on failure.
Manuel Pégourié-Gonnard847395a2012-11-05 13:13:44 +0100672 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200673int mbedtls_ecp_point_read_string( mbedtls_ecp_point *P, int radix,
Manuel Pégourié-Gonnard847395a2012-11-05 13:13:44 +0100674 const char *x, const char *y );
675
676/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100677 * \brief This function exports a point into unsigned binary data.
Manuel Pégourié-Gonnarde19feb52012-11-24 14:10:14 +0100678 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100679 * \param grp The group to which the point should belong.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500680 * This must be initialized and have group parameters
681 * set, for example through mbedtls_ecp_group_load().
682 * \param P The point to export. This must be initialized.
683 * \param format The point format. This must be either
684 * #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
Janos Follath28eb06d2019-02-26 10:53:34 +0000685 * (For groups without these formats, this parameter is
686 * ignored. But it still has to be either of the above
687 * values.)
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500688 * \param olen The address at which to store the length of
689 * the output in Bytes. This must not be \c NULL.
690 * \param buf The output buffer. This must be a writable buffer
691 * of length \p buflen Bytes.
692 * \param buflen The length of the output buffer \p buf in Bytes.
Manuel Pégourié-Gonnarde19feb52012-11-24 14:10:14 +0100693 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100694 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500695 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer
696 * is too small to hold the point.
Janos Follath28eb06d2019-02-26 10:53:34 +0000697 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
698 * or the export for the given group is not implemented.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500699 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnarde19feb52012-11-24 14:10:14 +0100700 */
Janos Follath28eb06d2019-02-26 10:53:34 +0000701int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp,
702 const mbedtls_ecp_point *P,
703 int format, size_t *olen,
704 unsigned char *buf, size_t buflen );
Manuel Pégourié-Gonnarde19feb52012-11-24 14:10:14 +0100705
706/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100707 * \brief This function imports a point from unsigned binary data.
Manuel Pégourié-Gonnard5e402d82012-11-24 16:19:42 +0100708 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100709 * \note This function does not check that the point actually
Rose Zadika7a61552018-04-24 13:14:01 +0100710 * belongs to the given group, see mbedtls_ecp_check_pubkey()
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100711 * for that.
Manuel Pégourié-Gonnard5e402d82012-11-24 16:19:42 +0100712 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100713 * \param grp The group to which the point should belong.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500714 * This must be initialized and have group parameters
715 * set, for example through mbedtls_ecp_group_load().
716 * \param P The destination context to import the point to.
717 * This must be initialized.
718 * \param buf The input buffer. This must be a readable buffer
719 * of length \p ilen Bytes.
720 * \param ilen The length of the input buffer \p buf in Bytes.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100721 *
722 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500723 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
Rose Zadikf56cb342018-04-19 12:49:10 +0100724 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
Janos Follath28eb06d2019-02-26 10:53:34 +0000725 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the import for the
726 * given group is not implemented.
Manuel Pégourié-Gonnard5e402d82012-11-24 16:19:42 +0100727 */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500728int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp,
729 mbedtls_ecp_point *P,
730 const unsigned char *buf, size_t ilen );
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100731
Manuel Pégourié-Gonnard5e402d82012-11-24 16:19:42 +0100732/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100733 * \brief This function imports a point from a TLS ECPoint record.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200734 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500735 * \note On function return, \p *buf is updated to point immediately
Rose Zadikf56cb342018-04-19 12:49:10 +0100736 * after the ECPoint record.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200737 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500738 * \param grp The ECP group to use.
739 * This must be initialized and have group parameters
740 * set, for example through mbedtls_ecp_group_load().
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100741 * \param pt The destination point.
Rose Zadikf56cb342018-04-19 12:49:10 +0100742 * \param buf The address of the pointer to the start of the input buffer.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100743 * \param len The length of the buffer.
Manuel Pégourié-Gonnard150c4f62014-11-21 09:14:52 +0100744 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100745 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500746 * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization
747 * failure.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100748 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200749 */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500750int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp,
751 mbedtls_ecp_point *pt,
752 const unsigned char **buf, size_t len );
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200753
754/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500755 * \brief This function exports a point as a TLS ECPoint record
756 * defined in RFC 4492, Section 5.4.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200757 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500758 * \param grp The ECP group to use.
759 * This must be initialized and have group parameters
760 * set, for example through mbedtls_ecp_group_load().
761 * \param pt The point to be exported. This must be initialized.
762 * \param format The point format to use. This must be either
763 * #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
764 * \param olen The address at which to store the length in Bytes
765 * of the data written.
766 * \param buf The target buffer. This must be a writable buffer of
767 * length \p blen Bytes.
768 * \param blen The length of the target buffer \p buf in Bytes.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200769 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100770 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500771 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
772 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the target buffer
773 * is too small to hold the exported point.
774 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200775 */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500776int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp,
777 const mbedtls_ecp_point *pt,
778 int format, size_t *olen,
779 unsigned char *buf, size_t blen );
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200780
781/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500782 * \brief This function sets up an ECP group context
783 * from a standardized set of domain parameters.
Manuel Pégourié-Gonnarda5402fe2012-11-07 20:24:05 +0100784 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100785 * \note The index should be a value of the NamedCurve enum,
Rose Zadika7a61552018-04-24 13:14:01 +0100786 * as defined in <em>RFC-4492: Elliptic Curve Cryptography
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100787 * (ECC) Cipher Suites for Transport Layer Security (TLS)</em>,
788 * usually in the form of an \c MBEDTLS_ECP_DP_XXX macro.
Manuel Pégourié-Gonnarda5402fe2012-11-07 20:24:05 +0100789 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500790 * \param grp The group context to setup. This must be initialized.
Rose Zadikf56cb342018-04-19 12:49:10 +0100791 * \param id The identifier of the domain parameter set to load.
Manuel Pégourié-Gonnarda5402fe2012-11-07 20:24:05 +0100792 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500793 * \return \c 0 on success.
794 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p id doesn't
795 * correspond to a known group.
796 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnarda5402fe2012-11-07 20:24:05 +0100797 */
Hanno Becker61937d42017-04-26 15:01:23 +0100798int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id );
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100799
800/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500801 * \brief This function sets up an ECP group context from a TLS
802 * ECParameters record as defined in RFC 4492, Section 5.4.
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100803 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500804 * \note The read pointer \p buf is updated to point right after
805 * the ECParameters record on exit.
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100806 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500807 * \param grp The group context to setup. This must be initialized.
Rose Zadikf56cb342018-04-19 12:49:10 +0100808 * \param buf The address of the pointer to the start of the input buffer.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500809 * \param len The length of the input buffer \c *buf in Bytes.
Manuel Pégourié-Gonnard150c4f62014-11-21 09:14:52 +0100810 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100811 * \return \c 0 on success.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100812 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500813 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
814 * recognized.
815 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100816 */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500817int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp,
818 const unsigned char **buf, size_t len );
Manuel Pégourié-Gonnarda5402fe2012-11-07 20:24:05 +0100819
820/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500821 * \brief This function extracts an elliptic curve group ID from a
822 * TLS ECParameters record as defined in RFC 4492, Section 5.4.
Manuel Pégourié-Gonnardb3258872013-02-10 12:06:19 +0100823 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500824 * \note The read pointer \p buf is updated to point right after
825 * the ECParameters record on exit.
826 *
827 * \param grp The address at which to store the group id.
828 * This must not be \c NULL.
829 * \param buf The address of the pointer to the start of the input buffer.
830 * \param len The length of the input buffer \c *buf in Bytes.
Manuel Pégourié-Gonnardb3258872013-02-10 12:06:19 +0100831 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100832 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500833 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
834 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
835 * recognized.
836 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnardb3258872013-02-10 12:06:19 +0100837 */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500838int mbedtls_ecp_tls_read_group_id( mbedtls_ecp_group_id *grp,
839 const unsigned char **buf,
840 size_t len );
841/**
842 * \brief This function exports an elliptic curve as a TLS
843 * ECParameters record as defined in RFC 4492, Section 5.4.
844 *
845 * \param grp The ECP group to be exported.
846 * This must be initialized and have group parameters
847 * set, for example through mbedtls_ecp_group_load().
848 * \param olen The address at which to store the number of Bytes written.
849 * This must not be \c NULL.
850 * \param buf The buffer to write to. This must be a writable buffer
851 * of length \p blen Bytes.
852 * \param blen The length of the output buffer \p buf in Bytes.
853 *
854 * \return \c 0 on success.
855 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output
856 * buffer is too small to hold the exported group.
857 * \return Another negative error code on other kinds of failure.
858 */
859int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp,
860 size_t *olen,
861 unsigned char *buf, size_t blen );
Manuel Pégourié-Gonnardb3258872013-02-10 12:06:19 +0100862
863/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500864 * \brief This function performs a scalar multiplication of a point
865 * by an integer: \p R = \p m * \p P.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100866 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100867 * It is not thread-safe to use same group in multiple threads.
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +0200868 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100869 * \note To prevent timing attacks, this function
870 * executes the exact same sequence of base-field
871 * operations for any valid \p m. It avoids any if-branch or
872 * array index depending on the value of \p m.
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +0200873 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100874 * \note If \p f_rng is not NULL, it is used to randomize
875 * intermediate results to prevent potential timing attacks
876 * targeting these results. We recommend always providing
877 * a non-NULL \p f_rng. The overhead is negligible.
Manuel Pégourié-Gonnard71d56672020-06-04 10:20:12 +0200878 * Note: unless #MBEDTLS_ECP_NO_INTERNAL_RNG is defined, when
879 * \p f_rng is NULL, an internal RNG (seeded from the value
880 * of \p m) will be used instead.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100881 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500882 * \param grp The ECP group to use.
883 * This must be initialized and have group parameters
884 * set, for example through mbedtls_ecp_group_load().
885 * \param R The point in which to store the result of the calculation.
886 * This must be initialized.
887 * \param m The integer by which to multiply. This must be initialized.
888 * \param P The point to multiply. This must be initialized.
889 * \param f_rng The RNG function. This may be \c NULL if randomization
890 * of intermediate results isn't desired (discouraged).
891 * \param p_rng The RNG context to be passed to \p p_rng.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100892 *
893 * \return \c 0 on success.
Rose Zadikf56cb342018-04-19 12:49:10 +0100894 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
895 * key, or \p P is not a valid public key.
896 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500897 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200898 */
899int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
900 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
901 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
902
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200903/**
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200904 * \brief This function performs multiplication of a point by
905 * an integer: \p R = \p m * \p P in a restartable way.
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200906 *
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200907 * \see mbedtls_ecp_mul()
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200908 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200909 * \note This function does the same as \c mbedtls_ecp_mul(), but
910 * it can return early and restart according to the limit set
911 * with \c mbedtls_ecp_set_max_ops() to reduce blocking.
912 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500913 * \param grp The ECP group to use.
914 * This must be initialized and have group parameters
915 * set, for example through mbedtls_ecp_group_load().
916 * \param R The point in which to store the result of the calculation.
917 * This must be initialized.
918 * \param m The integer by which to multiply. This must be initialized.
919 * \param P The point to multiply. This must be initialized.
920 * \param f_rng The RNG function. This may be \c NULL if randomization
921 * of intermediate results isn't desired (discouraged).
922 * \param p_rng The RNG context to be passed to \p p_rng.
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +0200923 * \param rs_ctx The restart context (NULL disables restart).
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200924 *
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200925 * \return \c 0 on success.
926 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
927 * key, or \p P is not a valid public key.
928 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
929 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnard8467e682017-04-20 09:47:06 +0200930 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500931 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100932 */
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200933int mbedtls_ecp_mul_restartable( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200934 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200935 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
936 mbedtls_ecp_restart_ctx *rs_ctx );
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100937
Gilles Peskine9b99a892018-09-14 18:32:19 +0200938#if defined(MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED)
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100939/**
Rose Zadika7a61552018-04-24 13:14:01 +0100940 * \brief This function performs multiplication and addition of two
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100941 * points by integers: \p R = \p m * \p P + \p n * \p Q
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +0200942 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100943 * It is not thread-safe to use same group in multiple threads.
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +0200944 *
Rose Zadika7a61552018-04-24 13:14:01 +0100945 * \note In contrast to mbedtls_ecp_mul(), this function does not
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100946 * guarantee a constant execution flow and timing.
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +0200947 *
Gilles Peskine9b99a892018-09-14 18:32:19 +0200948 * \note This function is only defined for short Weierstrass curves.
949 * It may not be included in builds without any short
950 * Weierstrass curve.
951 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500952 * \param grp The ECP group to use.
953 * This must be initialized and have group parameters
954 * set, for example through mbedtls_ecp_group_load().
955 * \param R The point in which to store the result of the calculation.
956 * This must be initialized.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100957 * \param m The integer by which to multiply \p P.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500958 * This must be initialized.
959 * \param P The point to multiply by \p m. This must be initialized.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100960 * \param n The integer by which to multiply \p Q.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500961 * This must be initialized.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100962 * \param Q The point to be multiplied by \p n.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500963 * This must be initialized.
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +0200964 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100965 * \return \c 0 on success.
Rose Zadika7a61552018-04-24 13:14:01 +0100966 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
967 * valid private keys, or \p P or \p Q are not valid public
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100968 * keys.
Rose Zadikf56cb342018-04-19 12:49:10 +0100969 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
Gilles Peskine9b99a892018-09-14 18:32:19 +0200970 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p grp does not
971 * designate a short Weierstrass curve.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500972 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +0200973 */
974int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
975 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
976 const mbedtls_mpi *n, const mbedtls_ecp_point *Q );
977
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +0200978/**
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200979 * \brief This function performs multiplication and addition of two
980 * points by integers: \p R = \p m * \p P + \p n * \p Q in a
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200981 * restartable way.
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +0200982 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200983 * \see \c mbedtls_ecp_muladd()
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +0200984 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200985 * \note This function works the same as \c mbedtls_ecp_muladd(),
986 * but it can return early and restart according to the limit
987 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +0200988 *
Gilles Peskine9b99a892018-09-14 18:32:19 +0200989 * \note This function is only defined for short Weierstrass curves.
990 * It may not be included in builds without any short
991 * Weierstrass curve.
992 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500993 * \param grp The ECP group to use.
994 * This must be initialized and have group parameters
995 * set, for example through mbedtls_ecp_group_load().
996 * \param R The point in which to store the result of the calculation.
997 * This must be initialized.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200998 * \param m The integer by which to multiply \p P.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500999 * This must be initialized.
1000 * \param P The point to multiply by \p m. This must be initialized.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001001 * \param n The integer by which to multiply \p Q.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001002 * This must be initialized.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001003 * \param Q The point to be multiplied by \p n.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001004 * This must be initialized.
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +02001005 * \param rs_ctx The restart context (NULL disables restart).
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001006 *
1007 * \return \c 0 on success.
1008 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
1009 * valid private keys, or \p P or \p Q are not valid public
1010 * keys.
1011 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
Gilles Peskine9b99a892018-09-14 18:32:19 +02001012 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p grp does not
1013 * designate a short Weierstrass curve.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001014 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +02001015 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001016 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +02001017 */
1018int mbedtls_ecp_muladd_restartable(
1019 mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
1020 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
1021 const mbedtls_mpi *n, const mbedtls_ecp_point *Q,
1022 mbedtls_ecp_restart_ctx *rs_ctx );
Gilles Peskine9b99a892018-09-14 18:32:19 +02001023#endif /* MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED */
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +02001024
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +02001025/**
Rose Zadika7a61552018-04-24 13:14:01 +01001026 * \brief This function checks that a point is a valid public key
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001027 * on this curve.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001028 *
Rose Zadika7a61552018-04-24 13:14:01 +01001029 * It only checks that the point is non-zero, has
1030 * valid coordinates and lies on the curve. It does not verify
1031 * that it is indeed a multiple of \p G. This additional
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001032 * check is computationally more expensive, is not required
1033 * by standards, and should not be necessary if the group
Rose Zadika7a61552018-04-24 13:14:01 +01001034 * used has a small cofactor. In particular, it is useless for
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001035 * the NIST groups which all have a cofactor of 1.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001036 *
Rose Zadika7a61552018-04-24 13:14:01 +01001037 * \note This function uses bare components rather than an
1038 * ::mbedtls_ecp_keypair structure, to ease use with other
1039 * structures, such as ::mbedtls_ecdh_context or
Rose Zadikb2e111a2018-04-20 10:13:48 +01001040 * ::mbedtls_ecdsa_context.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001041 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001042 * \param grp The ECP group the point should belong to.
1043 * This must be initialized and have group parameters
1044 * set, for example through mbedtls_ecp_group_load().
1045 * \param pt The point to check. This must be initialized.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001046 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001047 * \return \c 0 if the point is a valid public key.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001048 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not
1049 * a valid public key for the given curve.
1050 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001051 */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001052int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp,
1053 const mbedtls_ecp_point *pt );
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001054
1055/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001056 * \brief This function checks that an \p mbedtls_mpi is a
1057 * valid private key for this curve.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001058 *
Rose Zadika7a61552018-04-24 13:14:01 +01001059 * \note This function uses bare components rather than an
1060 * ::mbedtls_ecp_keypair structure to ease use with other
1061 * structures, such as ::mbedtls_ecdh_context or
Rose Zadikb2e111a2018-04-20 10:13:48 +01001062 * ::mbedtls_ecdsa_context.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001063 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001064 * \param grp The ECP group the private key should belong to.
1065 * This must be initialized and have group parameters
1066 * set, for example through mbedtls_ecp_group_load().
1067 * \param d The integer to check. This must be initialized.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001068 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001069 * \return \c 0 if the point is a valid private key.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001070 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not a valid
1071 * private key for the given curve.
1072 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001073 */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001074int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp,
1075 const mbedtls_mpi *d );
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001076
1077/**
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001078 * \brief This function generates a private key.
Manuel Pégourié-Gonnarda7937f92017-04-20 15:37:46 +02001079 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001080 * \param grp The ECP group to generate a private key for.
1081 * This must be initialized and have group parameters
1082 * set, for example through mbedtls_ecp_group_load().
1083 * \param d The destination MPI (secret part). This must be initialized.
1084 * \param f_rng The RNG function. This must not be \c NULL.
1085 * \param p_rng The RNG parameter to be passed to \p f_rng. This may be
1086 * \c NULL if \p f_rng doesn't need a context argument.
Manuel Pégourié-Gonnarda7937f92017-04-20 15:37:46 +02001087 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001088 * \return \c 0 on success.
1089 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
1090 * on failure.
Manuel Pégourié-Gonnarda7937f92017-04-20 15:37:46 +02001091 */
1092int mbedtls_ecp_gen_privkey( const mbedtls_ecp_group *grp,
1093 mbedtls_mpi *d,
1094 int (*f_rng)(void *, unsigned char *, size_t),
1095 void *p_rng );
1096
1097/**
Rose Zadika7a61552018-04-24 13:14:01 +01001098 * \brief This function generates a keypair with a configurable base
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001099 * point.
Manuel Pégourié-Gonnardd9a3f472015-08-11 14:31:03 +02001100 *
Rose Zadika7a61552018-04-24 13:14:01 +01001101 * \note This function uses bare components rather than an
1102 * ::mbedtls_ecp_keypair structure to ease use with other
1103 * structures, such as ::mbedtls_ecdh_context or
Rose Zadikb2e111a2018-04-20 10:13:48 +01001104 * ::mbedtls_ecdsa_context.
Manuel Pégourié-Gonnardd9a3f472015-08-11 14:31:03 +02001105 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001106 * \param grp The ECP group to generate a key pair for.
1107 * This must be initialized and have group parameters
1108 * set, for example through mbedtls_ecp_group_load().
1109 * \param G The base point to use. This must be initialized
1110 * and belong to \p grp. It replaces the default base
1111 * point \c grp->G used by mbedtls_ecp_gen_keypair().
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001112 * \param d The destination MPI (secret part).
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001113 * This must be initialized.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001114 * \param Q The destination point (public part).
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001115 * This must be initialized.
1116 * \param f_rng The RNG function. This must not be \c NULL.
1117 * \param p_rng The RNG context to be passed to \p f_rng. This may
1118 * be \c NULL if \p f_rng doesn't need a context argument.
Manuel Pégourié-Gonnardd9a3f472015-08-11 14:31:03 +02001119 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001120 * \return \c 0 on success.
1121 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
1122 * on failure.
Manuel Pégourié-Gonnardd9a3f472015-08-11 14:31:03 +02001123 */
1124int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp,
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001125 const mbedtls_ecp_point *G,
1126 mbedtls_mpi *d, mbedtls_ecp_point *Q,
1127 int (*f_rng)(void *, unsigned char *, size_t),
1128 void *p_rng );
Manuel Pégourié-Gonnardd9a3f472015-08-11 14:31:03 +02001129
1130/**
Rose Zadikf56cb342018-04-19 12:49:10 +01001131 * \brief This function generates an ECP keypair.
Manuel Pégourié-Gonnard45a035a2013-01-26 14:42:45 +01001132 *
Rose Zadika7a61552018-04-24 13:14:01 +01001133 * \note This function uses bare components rather than an
1134 * ::mbedtls_ecp_keypair structure to ease use with other
1135 * structures, such as ::mbedtls_ecdh_context or
Rose Zadikb2e111a2018-04-20 10:13:48 +01001136 * ::mbedtls_ecdsa_context.
Manuel Pégourié-Gonnard45a035a2013-01-26 14:42:45 +01001137 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001138 * \param grp The ECP group to generate a key pair for.
1139 * This must be initialized and have group parameters
1140 * set, for example through mbedtls_ecp_group_load().
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001141 * \param d The destination MPI (secret part).
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001142 * This must be initialized.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001143 * \param Q The destination point (public part).
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001144 * This must be initialized.
1145 * \param f_rng The RNG function. This must not be \c NULL.
1146 * \param p_rng The RNG context to be passed to \p f_rng. This may
1147 * be \c NULL if \p f_rng doesn't need a context argument.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001148 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001149 * \return \c 0 on success.
1150 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
1151 * on failure.
Manuel Pégourié-Gonnard45a035a2013-01-26 14:42:45 +01001152 */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001153int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d,
1154 mbedtls_ecp_point *Q,
1155 int (*f_rng)(void *, unsigned char *, size_t),
1156 void *p_rng );
Manuel Pégourié-Gonnard45a035a2013-01-26 14:42:45 +01001157
1158/**
Rose Zadikf56cb342018-04-19 12:49:10 +01001159 * \brief This function generates an ECP key.
Manuel Pégourié-Gonnard104ee1d2013-11-30 14:13:16 +01001160 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001161 * \param grp_id The ECP group identifier.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001162 * \param key The destination key. This must be initialized.
1163 * \param f_rng The RNG function to use. This must not be \c NULL.
1164 * \param p_rng The RNG context to be passed to \p f_rng. This may
1165 * be \c NULL if \p f_rng doesn't need a context argument.
Manuel Pégourié-Gonnard104ee1d2013-11-30 14:13:16 +01001166 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001167 * \return \c 0 on success.
1168 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
1169 * on failure.
Manuel Pégourié-Gonnard104ee1d2013-11-30 14:13:16 +01001170 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001171int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001172 int (*f_rng)(void *, unsigned char *, size_t),
1173 void *p_rng );
Manuel Pégourié-Gonnard104ee1d2013-11-30 14:13:16 +01001174
Manuel Pégourié-Gonnard30668d62014-11-06 15:25:32 +01001175/**
Janos Follathb65853c2019-02-25 16:33:28 +00001176 * \brief This function reads an elliptic curve private key.
Janos Follath171a7ef2019-02-15 16:17:45 +00001177 *
1178 * \param grp_id The ECP group identifier.
1179 * \param key The destination key.
Tobias Nießen1e8ca122021-05-10 19:53:15 +02001180 * \param buf The buffer containing the binary representation of the
Janos Follath171a7ef2019-02-15 16:17:45 +00001181 * key. (Big endian integer for Weierstrass curves, byte
1182 * string for Montgomery curves.)
1183 * \param buflen The length of the buffer in bytes.
1184 *
1185 * \return \c 0 on success.
Janos Follathb65853c2019-02-25 16:33:28 +00001186 * \return #MBEDTLS_ERR_ECP_INVALID_KEY error if the key is
1187 * invalid.
1188 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
Janos Follath28eb06d2019-02-26 10:53:34 +00001189 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the operation for
1190 * the group is not implemented.
Janos Follathb65853c2019-02-25 16:33:28 +00001191 * \return Another negative error code on different kinds of failure.
Janos Follath171a7ef2019-02-15 16:17:45 +00001192 */
1193int mbedtls_ecp_read_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
1194 const unsigned char *buf, size_t buflen );
Steven Cooremande8593f2020-06-09 19:55:26 +02001195
1196/**
1197 * \brief This function exports an elliptic curve private key.
1198 *
Steven Cooremande8593f2020-06-09 19:55:26 +02001199 * \param key The private key.
Steven Cooremanc9b7f782020-06-11 17:00:36 +02001200 * \param buf The output buffer for containing the binary representation
1201 * of the key. (Big endian integer for Weierstrass curves, byte
Steven Cooremande8593f2020-06-09 19:55:26 +02001202 * string for Montgomery curves.)
1203 * \param buflen The total length of the buffer in bytes.
1204 *
1205 * \return \c 0 on success.
Steven Cooremanc9b7f782020-06-11 17:00:36 +02001206 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the \p key
1207 representation is larger than the available space in \p buf.
Steven Cooremande8593f2020-06-09 19:55:26 +02001208 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the operation for
1209 * the group is not implemented.
1210 * \return Another negative error code on different kinds of failure.
1211 */
Steven Cooreman0024df62020-07-13 10:59:40 +02001212int mbedtls_ecp_write_key( mbedtls_ecp_keypair *key,
Steven Cooremanc9b7f782020-06-11 17:00:36 +02001213 unsigned char *buf, size_t buflen );
Steven Cooremande8593f2020-06-09 19:55:26 +02001214
Janos Follath171a7ef2019-02-15 16:17:45 +00001215/**
Rose Zadika7a61552018-04-24 13:14:01 +01001216 * \brief This function checks that the keypair objects
Rose Zadikb2e111a2018-04-20 10:13:48 +01001217 * \p pub and \p prv have the same group and the
1218 * same public point, and that the private key in
1219 * \p prv is consistent with the public key.
Manuel Pégourié-Gonnard30668d62014-11-06 15:25:32 +01001220 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001221 * \param pub The keypair structure holding the public key. This
1222 * must be initialized. If it contains a private key, that
1223 * part is ignored.
Rose Zadikb2e111a2018-04-20 10:13:48 +01001224 * \param prv The keypair structure holding the full keypair.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001225 * This must be initialized.
Manuel Pégourié-Gonnard30668d62014-11-06 15:25:32 +01001226 *
Rose Zadika7a61552018-04-24 13:14:01 +01001227 * \return \c 0 on success, meaning that the keys are valid and match.
Rose Zadikb2e111a2018-04-20 10:13:48 +01001228 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match.
Rose Zadika7a61552018-04-24 13:14:01 +01001229 * \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
Rose Zadikb2e111a2018-04-20 10:13:48 +01001230 * error code on calculation failure.
Manuel Pégourié-Gonnard30668d62014-11-06 15:25:32 +01001231 */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001232int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub,
1233 const mbedtls_ecp_keypair *prv );
Manuel Pégourié-Gonnard30668d62014-11-06 15:25:32 +01001234
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001235#if defined(MBEDTLS_SELF_TEST)
Janos Follathb0697532016-08-18 12:38:46 +01001236
Manuel Pégourié-Gonnard104ee1d2013-11-30 14:13:16 +01001237/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001238 * \brief The ECP checkup routine.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +01001239 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001240 * \return \c 0 on success.
1241 * \return \c 1 on failure.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +01001242 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001243int mbedtls_ecp_self_test( int verbose );
Janos Follathb0697532016-08-18 12:38:46 +01001244
Janos Follath372697b2016-10-28 16:53:11 +01001245#endif /* MBEDTLS_SELF_TEST */
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +01001246
1247#ifdef __cplusplus
1248}
1249#endif
1250
Paul Bakker9af723c2014-05-01 13:03:14 +02001251#endif /* ecp.h */