blob: b3406142fee62e97078aa043cacd74ddd69778ce [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
Dave Rodgman16799db2023-11-02 19:47:20 +000019 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010020 */
Rose Zadika7a61552018-04-24 13:14:01 +010021
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020022#ifndef MBEDTLS_ECP_H
23#define MBEDTLS_ECP_H
Mateusz Starzyk846f0212021-05-19 19:44:07 +020024#include "mbedtls/private_access.h"
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010025
Bence Szépkútic662b362021-05-27 11:25:03 +020026#include "mbedtls/build_info.h"
Gilles Peskinec0f7a862024-02-19 16:50:39 +010027#include "mbedtls/platform_util.h"
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050028
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010029#include "mbedtls/bignum.h"
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010030
31/*
Manuel Pégourié-Gonnard7cfcea32012-11-05 10:06:12 +010032 * ECP error codes
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010033 */
Gilles Peskined2971572021-07-26 18:48:10 +020034/** Bad input parameters to function. */
35#define MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80
36/** The buffer is too small to write to. */
37#define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00
38/** The requested feature is not available, for example, the requested curve is not supported. */
39#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80
40/** The signature is not valid. */
41#define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00
42/** Memory allocation failed. */
43#define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80
44/** Generation of random value, such as ephemeral key, failed. */
45#define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00
46/** Invalid private or public key. */
47#define MBEDTLS_ERR_ECP_INVALID_KEY -0x4C80
48/** The buffer contains a valid signature followed by more data. */
49#define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH -0x4C00
50/** Operation in progress, call again with the same parameters to continue. */
51#define MBEDTLS_ERR_ECP_IN_PROGRESS -0x4B00
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +010052
Gilles Peskine9b99a892018-09-14 18:32:19 +020053/* Flags indicating whether to include code that is specific to certain
54 * types of curves. These flags are for internal library use only. */
55#if defined(MBEDTLS_ECP_DP_SECP192R1_ENABLED) || \
56 defined(MBEDTLS_ECP_DP_SECP224R1_ENABLED) || \
57 defined(MBEDTLS_ECP_DP_SECP256R1_ENABLED) || \
58 defined(MBEDTLS_ECP_DP_SECP384R1_ENABLED) || \
59 defined(MBEDTLS_ECP_DP_SECP521R1_ENABLED) || \
Gilles Peskine9b99a892018-09-14 18:32:19 +020060 defined(MBEDTLS_ECP_DP_BP256R1_ENABLED) || \
61 defined(MBEDTLS_ECP_DP_BP384R1_ENABLED) || \
Gilles Peskinea3de08d2020-07-22 01:23:37 +020062 defined(MBEDTLS_ECP_DP_BP512R1_ENABLED) || \
63 defined(MBEDTLS_ECP_DP_SECP192K1_ENABLED) || \
64 defined(MBEDTLS_ECP_DP_SECP224K1_ENABLED) || \
65 defined(MBEDTLS_ECP_DP_SECP256K1_ENABLED)
Gilles Peskine9b99a892018-09-14 18:32:19 +020066#define MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED
67#endif
68#if defined(MBEDTLS_ECP_DP_CURVE25519_ENABLED) || \
69 defined(MBEDTLS_ECP_DP_CURVE448_ENABLED)
70#define MBEDTLS_ECP_MONTGOMERY_ENABLED
71#endif
72
Paul Bakker407a0da2013-06-27 14:29:21 +020073#ifdef __cplusplus
74extern "C" {
75#endif
76
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +010077/**
Rose Zadikd76ac582018-04-23 06:29:34 +010078 * Domain-parameter identifiers: curve, subgroup, and generator.
Manuel Pégourié-Gonnard70380392013-09-16 16:19:53 +020079 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +010080 * \note Only curves over prime fields are supported.
Manuel Pégourié-Gonnard70380392013-09-16 16:19:53 +020081 *
82 * \warning This library does not support validation of arbitrary domain
Rose Zadikf56cb342018-04-19 12:49:10 +010083 * parameters. Therefore, only standardized domain parameters from trusted
Manuel Pégourié-Gonnarde3a062b2015-05-11 18:46:47 +020084 * sources should be used. See mbedtls_ecp_group_load().
Manuel Pégourié-Gonnard70380392013-09-16 16:19:53 +020085 */
Gilles Peskine963a2072018-09-14 18:31:30 +020086/* Note: when adding a new curve:
87 * - Add it at the end of this enum, otherwise you'll break the ABI by
88 * changing the numerical value for existing curves.
Gilles Peskine6d9c8d72020-07-22 01:26:25 +020089 * - Increment MBEDTLS_ECP_DP_MAX below if needed.
Gilles Peskine6e1387a2021-06-07 20:24:51 +020090 * - Update the calculation of MBEDTLS_ECP_MAX_BITS below.
Gilles Peskine963a2072018-09-14 18:31:30 +020091 * - Add the corresponding MBEDTLS_ECP_DP_xxx_ENABLED macro definition to
Bence Szépkútibb0cfeb2021-05-28 09:42:25 +020092 * mbedtls_config.h.
Gilles Peskine963a2072018-09-14 18:31:30 +020093 * - List the curve as a dependency of MBEDTLS_ECP_C and
94 * MBEDTLS_ECDSA_C if supported in check_config.h.
95 * - Add the curve to the appropriate curve type macro
96 * MBEDTLS_ECP_yyy_ENABLED above.
97 * - Add the necessary definitions to ecp_curves.c.
98 * - Add the curve to the ecp_supported_curves array in ecp.c.
Gilles Peskine601d3432021-06-07 20:27:01 +020099 * - Add the curve to applicable profiles in x509_crt.c.
100 * - Add the curve to applicable presets in ssl_tls.c.
Gilles Peskine963a2072018-09-14 18:31:30 +0200101 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100102typedef enum {
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100103 MBEDTLS_ECP_DP_NONE = 0, /*!< Curve not defined. */
Rose Zadikb2e111a2018-04-20 10:13:48 +0100104 MBEDTLS_ECP_DP_SECP192R1, /*!< Domain parameters for the 192-bit curve defined by FIPS 186-4 and SEC1. */
105 MBEDTLS_ECP_DP_SECP224R1, /*!< Domain parameters for the 224-bit curve defined by FIPS 186-4 and SEC1. */
106 MBEDTLS_ECP_DP_SECP256R1, /*!< Domain parameters for the 256-bit curve defined by FIPS 186-4 and SEC1. */
107 MBEDTLS_ECP_DP_SECP384R1, /*!< Domain parameters for the 384-bit curve defined by FIPS 186-4 and SEC1. */
108 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 +0100109 MBEDTLS_ECP_DP_BP256R1, /*!< Domain parameters for 256-bit Brainpool curve. */
110 MBEDTLS_ECP_DP_BP384R1, /*!< Domain parameters for 384-bit Brainpool curve. */
111 MBEDTLS_ECP_DP_BP512R1, /*!< Domain parameters for 512-bit Brainpool curve. */
Rose Zadikb2e111a2018-04-20 10:13:48 +0100112 MBEDTLS_ECP_DP_CURVE25519, /*!< Domain parameters for Curve25519. */
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100113 MBEDTLS_ECP_DP_SECP192K1, /*!< Domain parameters for 192-bit "Koblitz" curve. */
114 MBEDTLS_ECP_DP_SECP224K1, /*!< Domain parameters for 224-bit "Koblitz" curve. */
115 MBEDTLS_ECP_DP_SECP256K1, /*!< Domain parameters for 256-bit "Koblitz" curve. */
Jaeden Amerofe0669f2018-04-27 17:43:32 +0100116 MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for Curve448. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200117} mbedtls_ecp_group_id;
Manuel Pégourié-Gonnard70380392013-09-16 16:19:53 +0200118
119/**
Rose Zadikf56cb342018-04-19 12:49:10 +0100120 * The number of supported curves, plus one for #MBEDTLS_ECP_DP_NONE.
Manuel Pégourié-Gonnardf24b4a72013-09-23 18:14:50 +0200121 */
Brett Warren36b70b22021-10-19 23:39:07 +0100122#define MBEDTLS_ECP_DP_MAX 14
Manuel Pégourié-Gonnardf24b4a72013-09-23 18:14:50 +0200123
Janos Follathdf9295b2019-02-26 12:36:52 +0000124/*
125 * Curve types
126 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100127typedef enum {
Janos Follathdf9295b2019-02-26 12:36:52 +0000128 MBEDTLS_ECP_TYPE_NONE = 0,
129 MBEDTLS_ECP_TYPE_SHORT_WEIERSTRASS, /* y^2 = x^3 + a x + b */
130 MBEDTLS_ECP_TYPE_MONTGOMERY, /* y^2 = x^3 + a x^2 + x */
131} mbedtls_ecp_curve_type;
132
Manuel Pégourié-Gonnardf24b4a72013-09-23 18:14:50 +0200133/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100134 * Curve information, for use by other modules.
Gilles Peskinea73b5772021-07-19 14:36:03 +0200135 *
136 * The fields of this structure are part of the public API and can be
137 * accessed directly by applications. Future versions of the library may
138 * add extra fields or reorder existing fields.
Manuel Pégourié-Gonnard568c9cf2013-09-16 17:30:04 +0200139 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100140typedef struct mbedtls_ecp_curve_info {
Gilles Peskinea73b5772021-07-19 14:36:03 +0200141 mbedtls_ecp_group_id grp_id; /*!< An internal identifier. */
142 uint16_t tls_id; /*!< The TLS NamedCurve identifier. */
143 uint16_t bit_size; /*!< The curve size in bits. */
144 const char *name; /*!< A human-friendly name. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200145} mbedtls_ecp_curve_info;
Manuel Pégourié-Gonnard568c9cf2013-09-16 17:30:04 +0200146
147/**
Rose Zadikf56cb342018-04-19 12:49:10 +0100148 * \brief The ECP point structure, in Jacobian coordinates.
Manuel Pégourié-Gonnardae180d02012-11-02 18:14:40 +0100149 *
Manuel Pégourié-Gonnard1c2782c2012-11-19 20:16:28 +0100150 * \note All functions expect and return points satisfying
Rose Zadikf56cb342018-04-19 12:49:10 +0100151 * the following condition: <code>Z == 0</code> or
Rose Zadika7a61552018-04-24 13:14:01 +0100152 * <code>Z == 1</code>. Other values of \p Z are
Rose Zadikf56cb342018-04-19 12:49:10 +0100153 * used only by internal functions.
154 * The point is zero, or "at infinity", if <code>Z == 0</code>.
Rose Zadika7a61552018-04-24 13:14:01 +0100155 * Otherwise, \p X and \p Y are its standard (affine)
Rose Zadikf56cb342018-04-19 12:49:10 +0100156 * coordinates.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100157 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100158typedef struct mbedtls_ecp_point {
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200159 mbedtls_mpi MBEDTLS_PRIVATE(X); /*!< The X coordinate of the ECP point. */
160 mbedtls_mpi MBEDTLS_PRIVATE(Y); /*!< The Y coordinate of the ECP point. */
161 mbedtls_mpi MBEDTLS_PRIVATE(Z); /*!< The Z coordinate of the ECP point. */
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100162}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200163mbedtls_ecp_point;
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100164
Waleed Elmelegycca4dbe2024-09-25 17:49:14 +0100165#define MBEDTLS_ECP_POINT_INIT { MBEDTLS_MPI_INIT, MBEDTLS_MPI_INIT, MBEDTLS_MPI_INIT }
166
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100167/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100168 * \brief The ECP group structure.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100169 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100170 * We consider two types of curve equations:
Rose Zadikb2e111a2018-04-20 10:13:48 +0100171 * <ul><li>Short Weierstrass: <code>y^2 = x^3 + A x + B mod P</code>
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100172 * (SEC1 + RFC-4492)</li>
Rose Zadikf56cb342018-04-19 12:49:10 +0100173 * <li>Montgomery: <code>y^2 = x^3 + A x^2 + x mod P</code> (Curve25519,
Rose Zadikb2e111a2018-04-20 10:13:48 +0100174 * Curve448)</li></ul>
Rose Zadikf56cb342018-04-19 12:49:10 +0100175 * In both cases, the generator (\p G) for a prime-order subgroup is fixed.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100176 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100177 * For Short Weierstrass, this subgroup is the whole curve, and its
Rose Zadikf56cb342018-04-19 12:49:10 +0100178 * cardinality is denoted by \p N. Our code requires that \p N is an
Rose Zadikb2e111a2018-04-20 10:13:48 +0100179 * odd prime as mbedtls_ecp_mul() requires an odd number, and
180 * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes.
Chien Wongaa9a1582023-08-09 12:33:40 +0800181 *
Chien Wong153ae462023-01-31 23:27:03 +0800182 * The default implementation only initializes \p A without setting it to the
183 * authentic value for curves with <code>A = -3</code>(SECP256R1, etc), in which
Chien Wongaa9a1582023-08-09 12:33:40 +0800184 * case you need to load \p A by yourself when using domain parameters directly,
185 * for example:
Chien Wong153ae462023-01-31 23:27:03 +0800186 * \code
Chien Wongaa9a1582023-08-09 12:33:40 +0800187 * mbedtls_mpi_init(&A);
Chien Wong153ae462023-01-31 23:27:03 +0800188 * mbedtls_ecp_group_init(&grp);
189 * CHECK_RETURN(mbedtls_ecp_group_load(&grp, grp_id));
190 * if (mbedtls_ecp_group_a_is_minus_3(&grp)) {
Chien Wongaa9a1582023-08-09 12:33:40 +0800191 * CHECK_RETURN(mbedtls_mpi_sub_int(&A, &grp.P, 3));
192 * } else {
193 * CHECK_RETURN(mbedtls_mpi_copy(&A, &grp.A));
Chien Wong153ae462023-01-31 23:27:03 +0800194 * }
195 *
Chien Wongaa9a1582023-08-09 12:33:40 +0800196 * do_something_with_a(&A);
Chien Wong153ae462023-01-31 23:27:03 +0800197 *
198 * cleanup:
Chien Wongaa9a1582023-08-09 12:33:40 +0800199 * mbedtls_mpi_free(&A);
Chien Wong153ae462023-01-31 23:27:03 +0800200 * mbedtls_ecp_group_free(&grp);
201 * \endcode
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100202 *
Rose Zadikf56cb342018-04-19 12:49:10 +0100203 * For Montgomery curves, we do not store \p A, but <code>(A + 2) / 4</code>,
Rose Zadika7a61552018-04-24 13:14:01 +0100204 * which is the quantity used in the formulas. Additionally, \p nbits is
Rose Zadikf56cb342018-04-19 12:49:10 +0100205 * not the size of \p N but the required size for private keys.
Manuel Pégourié-Gonnard47123252012-11-10 14:44:24 +0100206 *
Rose Zadika7a61552018-04-24 13:14:01 +0100207 * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm.
208 * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the
209 * range of <code>0..2^(2*pbits)-1</code>, and transforms it in-place to an integer
210 * which is congruent mod \p P to the given MPI, and is close enough to \p pbits
211 * in size, so that it may be efficiently brought in the 0..P-1 range by a few
Wenxing Houb4d03cc2024-06-19 11:04:13 +0800212 * additions or subtractions. Therefore, it is only an approximate modular
Rose Zadika7a61552018-04-24 13:14:01 +0100213 * reduction. It must return 0 on success and non-zero on failure.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100214 *
Gilles Peskinebf69ea52021-05-27 23:53:07 +0200215 * \note Alternative implementations of the ECP module must obey the
216 * following constraints.
217 * * Group IDs must be distinct: if two group structures have
218 * the same ID, then they must be identical.
219 * * The fields \c id, \c P, \c A, \c B, \c G, \c N,
220 * \c pbits and \c nbits must have the same type and semantics
221 * as in the built-in implementation.
222 * They must be available for reading, but direct modification
223 * of these fields does not need to be supported.
224 * They do not need to be at the same offset in the structure.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100225 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100226typedef struct mbedtls_ecp_group {
Gilles Peskinebf69ea52021-05-27 23:53:07 +0200227 mbedtls_ecp_group_id id; /*!< An internal group identifier. */
228 mbedtls_mpi P; /*!< The prime modulus of the base field. */
Chien Wong153ae462023-01-31 23:27:03 +0800229 mbedtls_mpi A; /*!< For Short Weierstrass: \p A in the equation. Note that
230 \p A is not set to the authentic value in some cases.
Chien Wongaa9a1582023-08-09 12:33:40 +0800231 Refer to detailed description of ::mbedtls_ecp_group if
232 using domain parameters in the structure.
233 For Montgomery curves: <code>(A + 2) / 4</code>. */
Gilles Peskinebf69ea52021-05-27 23:53:07 +0200234 mbedtls_mpi B; /*!< For Short Weierstrass: \p B in the equation.
Rose Zadikb2e111a2018-04-20 10:13:48 +0100235 For Montgomery curves: unused. */
Gilles Peskinebf69ea52021-05-27 23:53:07 +0200236 mbedtls_ecp_point G; /*!< The generator of the subgroup used. */
237 mbedtls_mpi N; /*!< The order of \p G. */
238 size_t pbits; /*!< The number of bits in \p P.*/
239 size_t nbits; /*!< For Short Weierstrass: The number of bits in \p P.
Rose Zadika7a61552018-04-24 13:14:01 +0100240 For Montgomery curves: the number of bits in the
Rose Zadikd76ac582018-04-23 06:29:34 +0100241 private keys. */
Gilles Peskinebf69ea52021-05-27 23:53:07 +0200242 /* End of public fields */
243
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200244 unsigned int MBEDTLS_PRIVATE(h); /*!< \internal 1 if the constants are static. */
Gilles Peskine449bd832023-01-11 14:50:10 +0100245 int(*MBEDTLS_PRIVATE(modp))(mbedtls_mpi *); /*!< The function for fast pseudo-reduction
246 mod \p P (see above).*/
247 int(*MBEDTLS_PRIVATE(t_pre))(mbedtls_ecp_point *, void *); /*!< Unused. */
248 int(*MBEDTLS_PRIVATE(t_post))(mbedtls_ecp_point *, void *); /*!< Unused. */
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200249 void *MBEDTLS_PRIVATE(t_data); /*!< Unused. */
250 mbedtls_ecp_point *MBEDTLS_PRIVATE(T); /*!< Pre-computed points for ecp_mul_comb(). */
Mateusz Starzyk854a25c2021-06-07 09:49:01 +0200251 size_t MBEDTLS_PRIVATE(T_size); /*!< The number of dynamic allocated pre-computed points. */
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100252}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200253mbedtls_ecp_group;
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100254
Waleed Elmelegycca4dbe2024-09-25 17:49:14 +0100255#define MBEDTLS_ECP_GROUP_INIT { MBEDTLS_ECP_DP_NONE, MBEDTLS_MPI_INIT, MBEDTLS_MPI_INIT, \
256 MBEDTLS_MPI_INIT, MBEDTLS_ECP_POINT_INIT, MBEDTLS_MPI_INIT, \
257 0, 0, 0, NULL, NULL, NULL, NULL, NULL, 0 }
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500258/**
259 * \name SECTION: Module settings
260 *
261 * The configuration options you can set for this module are in this section.
Bence Szépkútibb0cfeb2021-05-28 09:42:25 +0200262 * Either change them in mbedtls_config.h, or define them using the compiler command line.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500263 * \{
264 */
265
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500266#if !defined(MBEDTLS_ECP_WINDOW_SIZE)
267/*
268 * Maximum "window" size used for point multiplication.
Tom Cosgrove1e211442022-05-26 11:51:00 +0100269 * Default: a point where higher memory usage yields diminishing performance
Gilles Peskine5752e592021-06-02 13:27:03 +0200270 * returns.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500271 * Minimum value: 2. Maximum value: 7.
272 *
273 * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) )
274 * points used for point multiplication. This value is directly tied to EC
275 * peak memory usage, so decreasing it by one should roughly cut memory usage
276 * by two (if large curves are in use).
277 *
278 * Reduction in size may reduce speed, but larger curves are impacted first.
279 * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1):
280 * w-size: 6 5 4 3 2
281 * 521 145 141 135 120 97
282 * 384 214 209 198 177 146
283 * 256 320 320 303 262 226
284 * 224 475 475 453 398 342
285 * 192 640 640 633 587 476
286 */
Gilles Peskine5752e592021-06-02 13:27:03 +0200287#define MBEDTLS_ECP_WINDOW_SIZE 4 /**< The maximum window size used. */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500288#endif /* MBEDTLS_ECP_WINDOW_SIZE */
289
290#if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)
291/*
kXuan782c2b92021-06-02 16:53:42 +0800292 * Trade code size for speed on fixed-point multiplication.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500293 *
294 * This speeds up repeated multiplication of the generator (that is, the
295 * multiplication in ECDSA signatures, and half of the multiplications in
296 * ECDSA verification and ECDHE) by a factor roughly 3 to 4.
297 *
kXuan782c2b92021-06-02 16:53:42 +0800298 * For each n-bit Short Weierstrass curve that is enabled, this adds 4n bytes
299 * of code size if n < 384 and 8n otherwise.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500300 *
kXuan782c2b92021-06-02 16:53:42 +0800301 * Change this value to 0 to reduce code size.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500302 */
303#define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up. */
304#endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */
305
Andrzej Kurekcead70d2022-01-24 10:48:10 -0500306/** \} name SECTION: Module settings */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500307
Gilles Peskined0b16302021-05-28 00:17:26 +0200308/**
309 * The maximum size of the groups, that is, of \c N and \c P.
310 */
Valerio Settifd122f42023-04-05 18:15:32 +0200311#if !defined(MBEDTLS_ECP_LIGHT)
Gilles Peskined0b16302021-05-28 00:17:26 +0200312/* Dummy definition to help code that has optional ECP support and
313 * defines an MBEDTLS_ECP_MAX_BYTES-sized array unconditionally. */
314#define MBEDTLS_ECP_MAX_BITS 1
315/* Note: the curves must be listed in DECREASING size! */
316#elif defined(MBEDTLS_ECP_DP_SECP521R1_ENABLED)
317#define MBEDTLS_ECP_MAX_BITS 521
318#elif defined(MBEDTLS_ECP_DP_BP512R1_ENABLED)
319#define MBEDTLS_ECP_MAX_BITS 512
320#elif defined(MBEDTLS_ECP_DP_CURVE448_ENABLED)
321#define MBEDTLS_ECP_MAX_BITS 448
322#elif defined(MBEDTLS_ECP_DP_BP384R1_ENABLED)
323#define MBEDTLS_ECP_MAX_BITS 384
324#elif defined(MBEDTLS_ECP_DP_SECP384R1_ENABLED)
325#define MBEDTLS_ECP_MAX_BITS 384
326#elif defined(MBEDTLS_ECP_DP_BP256R1_ENABLED)
327#define MBEDTLS_ECP_MAX_BITS 256
328#elif defined(MBEDTLS_ECP_DP_SECP256K1_ENABLED)
329#define MBEDTLS_ECP_MAX_BITS 256
330#elif defined(MBEDTLS_ECP_DP_SECP256R1_ENABLED)
331#define MBEDTLS_ECP_MAX_BITS 256
332#elif defined(MBEDTLS_ECP_DP_CURVE25519_ENABLED)
333#define MBEDTLS_ECP_MAX_BITS 255
334#elif defined(MBEDTLS_ECP_DP_SECP224K1_ENABLED)
335#define MBEDTLS_ECP_MAX_BITS 225 // n is slightly above 2^224
336#elif defined(MBEDTLS_ECP_DP_SECP224R1_ENABLED)
337#define MBEDTLS_ECP_MAX_BITS 224
338#elif defined(MBEDTLS_ECP_DP_SECP192K1_ENABLED)
339#define MBEDTLS_ECP_MAX_BITS 192
340#elif defined(MBEDTLS_ECP_DP_SECP192R1_ENABLED)
341#define MBEDTLS_ECP_MAX_BITS 192
Valerio Settifd122f42023-04-05 18:15:32 +0200342#else /* !MBEDTLS_ECP_LIGHT */
Gilles Peskined0b16302021-05-28 00:17:26 +0200343#error "Missing definition of MBEDTLS_ECP_MAX_BITS"
Valerio Settifd122f42023-04-05 18:15:32 +0200344#endif /* !MBEDTLS_ECP_LIGHT */
Gilles Peskined0b16302021-05-28 00:17:26 +0200345
Gilles Peskine449bd832023-01-11 14:50:10 +0100346#define MBEDTLS_ECP_MAX_BYTES ((MBEDTLS_ECP_MAX_BITS + 7) / 8)
347#define MBEDTLS_ECP_MAX_PT_LEN (2 * MBEDTLS_ECP_MAX_BYTES + 1)
Gilles Peskine9ef1ea72021-05-28 00:16:18 +0200348
Manuel Pégourié-Gonnard4b9c51e2017-04-20 15:50:26 +0200349#if defined(MBEDTLS_ECP_RESTARTABLE)
Manuel Pégourié-Gonnardb5a50e72017-04-20 16:06:13 +0200350
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200351/**
Manuel Pégourié-Gonnard3cade222017-04-20 09:31:00 +0200352 * \brief Internal restart context for multiplication
353 *
354 * \note Opaque struct
355 */
356typedef struct mbedtls_ecp_restart_mul mbedtls_ecp_restart_mul_ctx;
357
358/**
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +0200359 * \brief Internal restart context for ecp_muladd()
360 *
361 * \note Opaque struct
362 */
363typedef struct mbedtls_ecp_restart_muladd mbedtls_ecp_restart_muladd_ctx;
364
365/**
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200366 * \brief General context for resuming ECC operations
367 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100368typedef struct {
Mateusz Starzyk363eb292021-05-19 17:32:44 +0200369 unsigned MBEDTLS_PRIVATE(ops_done); /*!< current ops count */
370 unsigned MBEDTLS_PRIVATE(depth); /*!< call depth (0 = top-level) */
371 mbedtls_ecp_restart_mul_ctx *MBEDTLS_PRIVATE(rsm); /*!< ecp_mul_comb() sub-context */
372 mbedtls_ecp_restart_muladd_ctx *MBEDTLS_PRIVATE(ma); /*!< ecp_muladd() sub-context */
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200373} mbedtls_ecp_restart_ctx;
Manuel Pégourié-Gonnardb5a50e72017-04-20 16:06:13 +0200374
Manuel Pégourié-Gonnardc7511482017-04-20 16:31:00 +0200375/*
376 * Operation counts for restartable functions
377 */
Manuel Pégourié-Gonnard5314f232017-04-21 12:36:59 +0200378#define MBEDTLS_ECP_OPS_CHK 3 /*!< basic ops count for ecp_check_pubkey() */
Manuel Pégourié-Gonnardc7511482017-04-20 16:31:00 +0200379#define MBEDTLS_ECP_OPS_DBL 8 /*!< basic ops count for ecp_double_jac() */
380#define MBEDTLS_ECP_OPS_ADD 11 /*!< basic ops count for see ecp_add_mixed() */
381#define MBEDTLS_ECP_OPS_INV 120 /*!< empirical equivalent for mpi_mod_inv() */
382
383/**
384 * \brief Internal; for restartable functions in other modules.
385 * Check and update basic ops budget.
386 *
387 * \param grp Group structure
388 * \param rs_ctx Restart context
389 * \param ops Number of basic ops to do
390 *
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200391 * \return \c 0 if doing \p ops basic ops is still allowed,
392 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS otherwise.
Manuel Pégourié-Gonnardc7511482017-04-20 16:31:00 +0200393 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100394int mbedtls_ecp_check_budget(const mbedtls_ecp_group *grp,
395 mbedtls_ecp_restart_ctx *rs_ctx,
396 unsigned ops);
Manuel Pégourié-Gonnardc7511482017-04-20 16:31:00 +0200397
398/* Utility macro for checking and updating ops budget */
Gilles Peskine449bd832023-01-11 14:50:10 +0100399#define MBEDTLS_ECP_BUDGET(ops) \
400 MBEDTLS_MPI_CHK(mbedtls_ecp_check_budget(grp, rs_ctx, \
401 (unsigned) (ops)));
Manuel Pégourié-Gonnardc7511482017-04-20 16:31:00 +0200402
Manuel Pégourié-Gonnardb5a50e72017-04-20 16:06:13 +0200403#else /* MBEDTLS_ECP_RESTARTABLE */
404
Gilles Peskine449bd832023-01-11 14:50:10 +0100405#define MBEDTLS_ECP_BUDGET(ops) /* no-op; for compatibility */
Manuel Pégourié-Gonnardc7511482017-04-20 16:31:00 +0200406
Manuel Pégourié-Gonnardb5a50e72017-04-20 16:06:13 +0200407/* We want to declare restartable versions of existing functions anyway */
408typedef void mbedtls_ecp_restart_ctx;
409
Manuel Pégourié-Gonnard4b9c51e2017-04-20 15:50:26 +0200410#endif /* MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200411
Paul Bakker088c5c52014-04-25 11:11:10 +0200412/**
Jaeden Amero89453432018-04-24 17:15:38 +0100413 * \brief The ECP key-pair structure.
Ron Eldor05d0e512018-04-16 17:40:04 +0300414 *
Jaeden Amero89453432018-04-24 17:15:38 +0100415 * A generic key-pair that may be used for ECDSA and fixed ECDH, for example.
Ron Eldor05d0e512018-04-16 17:40:04 +0300416 *
Jaeden Amero89453432018-04-24 17:15:38 +0100417 * \note Members are deliberately in the same order as in the
418 * ::mbedtls_ecdsa_context structure.
Ron Eldor05d0e512018-04-16 17:40:04 +0300419 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100420typedef struct mbedtls_ecp_keypair {
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200421 mbedtls_ecp_group MBEDTLS_PRIVATE(grp); /*!< Elliptic curve and base point */
422 mbedtls_mpi MBEDTLS_PRIVATE(d); /*!< our secret value */
423 mbedtls_ecp_point MBEDTLS_PRIVATE(Q); /*!< our public value */
Ron Eldor05d0e512018-04-16 17:40:04 +0300424}
425mbedtls_ecp_keypair;
426
Waleed Elmelegycca4dbe2024-09-25 17:49:14 +0100427#define MBEDTLS_ECP_KEYPAIR_INIT { MBEDTLS_ECP_GROUP_INIT, MBEDTLS_MPI_INIT, \
428 MBEDTLS_ECP_POINT_INIT }
429
Valerio Setti78f79d32023-02-07 08:33:26 +0100430/**
431 * The uncompressed point format for Short Weierstrass curves
432 * (MBEDTLS_ECP_DP_SECP_XXX and MBEDTLS_ECP_DP_BP_XXX).
Manuel Pégourié-Gonnard37d218a2012-11-24 15:19:55 +0100433 */
Valerio Setti78f79d32023-02-07 08:33:26 +0100434#define MBEDTLS_ECP_PF_UNCOMPRESSED 0
435/**
436 * The compressed point format for Short Weierstrass curves
437 * (MBEDTLS_ECP_DP_SECP_XXX and MBEDTLS_ECP_DP_BP_XXX).
438 *
439 * \warning While this format is supported for all concerned curves for
440 * writing, when it comes to parsing, it is not supported for all
441 * curves. Specifically, parsing compressed points on
442 * MBEDTLS_ECP_DP_SECP224R1 and MBEDTLS_ECP_DP_SECP224K1 is not
443 * supported.
444 */
445#define MBEDTLS_ECP_PF_COMPRESSED 1
Manuel Pégourié-Gonnard37d218a2012-11-24 15:19:55 +0100446
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100447/*
Manuel Pégourié-Gonnard00794052013-02-09 19:00:07 +0100448 * Some other constants from RFC 4492
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100449 */
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100450#define MBEDTLS_ECP_TLS_NAMED_CURVE 3 /**< The named_curve of ECCurveType. */
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100451
Manuel Pégourié-Gonnard4b9c51e2017-04-20 15:50:26 +0200452#if defined(MBEDTLS_ECP_RESTARTABLE)
Manuel Pégourié-Gonnard054433c2017-03-22 11:18:33 +0100453/**
454 * \brief Set the maximum number of basic operations done in a row.
455 *
456 * If more operations are needed to complete a computation,
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200457 * #MBEDTLS_ERR_ECP_IN_PROGRESS will be returned by the
Manuel Pégourié-Gonnard8467e682017-04-20 09:47:06 +0200458 * function performing the computation. It is then the
459 * caller's responsibility to either call again with the same
Manuel Pégourié-Gonnard7037e222017-08-23 14:30:36 +0200460 * parameters until it returns 0 or an error code; or to free
Manuel Pégourié-Gonnard8467e682017-04-20 09:47:06 +0200461 * the restart context if the operation is to be aborted.
Manuel Pégourié-Gonnard054433c2017-03-22 11:18:33 +0100462 *
Manuel Pégourié-Gonnard7037e222017-08-23 14:30:36 +0200463 * It is strictly required that all input parameters and the
464 * restart context be the same on successive calls for the
465 * same operation, but output parameters need not be the
466 * same; they must not be used until the function finally
467 * returns 0.
468 *
Gilles Peskine1174db52020-02-26 19:52:06 +0100469 * This only applies to functions whose documentation
470 * mentions they may return #MBEDTLS_ERR_ECP_IN_PROGRESS (or
471 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS for functions in the
472 * SSL module). For functions that accept a "restart context"
473 * argument, passing NULL disables restart and makes the
474 * function equivalent to the function with the same name
Manuel Pégourié-Gonnard32df9112018-10-15 13:29:21 +0200475 * with \c _restartable removed. For functions in the ECDH
Gilles Peskine1174db52020-02-26 19:52:06 +0100476 * module, restart is disabled unless the function accepts
477 * an "ECDH context" argument and
478 * mbedtls_ecdh_enable_restart() was previously called on
479 * that context. For function in the SSL module, restart is
480 * only enabled for specific sides and key exchanges
481 * (currently only for clients and ECDHE-ECDSA).
Manuel Pégourié-Gonnard8f28add2017-04-19 10:20:49 +0200482 *
Paul Elliott56865332023-02-15 22:57:44 +0000483 * \warning Using the PSA interruptible interfaces with keys in local
484 * storage and no accelerator driver will also call this
485 * function to set the values specified via those interfaces,
486 * overwriting values previously set. Care should be taken if
487 * mixing these two interfaces.
488 *
Manuel Pégourié-Gonnard054433c2017-03-22 11:18:33 +0100489 * \param max_ops Maximum number of basic operations done in a row.
490 * Default: 0 (unlimited).
491 * Lower (non-zero) values mean ECC functions will block for
492 * a lesser maximum amount of time.
493 *
Manuel Pégourié-Gonnarde6854492017-03-20 14:35:19 +0100494 * \note A "basic operation" is defined as a rough equivalent of a
495 * multiplication in GF(p) for the NIST P-256 curve.
496 * As an indication, with default settings, a scalar
497 * multiplication (full run of \c mbedtls_ecp_mul()) is:
498 * - about 3300 basic operations for P-256
499 * - about 9400 basic operations for P-384
Manuel Pégourié-Gonnard054433c2017-03-22 11:18:33 +0100500 *
Manuel Pégourié-Gonnarde58f65a2017-03-20 14:59:54 +0100501 * \note Very low values are not always respected: sometimes
Manuel Pégourié-Gonnard1c678e02017-03-20 13:39:39 +0100502 * functions need to block for a minimum number of
503 * operations, and will do so even if max_ops is set to a
504 * lower value. That minimum depends on the curve size, and
505 * can be made lower by decreasing the value of
Manuel Pégourié-Gonnard7037e222017-08-23 14:30:36 +0200506 * \c MBEDTLS_ECP_WINDOW_SIZE. As an indication, here is the
507 * lowest effective value for various curves and values of
508 * that parameter (w for short):
509 * w=6 w=5 w=4 w=3 w=2
510 * P-256 208 208 160 136 124
511 * P-384 682 416 320 272 248
512 * P-521 1364 832 640 544 496
Manuel Pégourié-Gonnarde58f65a2017-03-20 14:59:54 +0100513 *
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200514 * \note This setting is currently ignored by Curve25519.
Manuel Pégourié-Gonnard054433c2017-03-22 11:18:33 +0100515 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100516void mbedtls_ecp_set_max_ops(unsigned max_ops);
Manuel Pégourié-Gonnarda0c5bcc2017-04-21 11:33:57 +0200517
518/**
519 * \brief Check if restart is enabled (max_ops != 0)
520 *
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200521 * \return \c 0 if \c max_ops == 0 (restart disabled)
522 * \return \c 1 otherwise (restart enabled)
Manuel Pégourié-Gonnarda0c5bcc2017-04-21 11:33:57 +0200523 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100524int mbedtls_ecp_restart_is_enabled(void);
Manuel Pégourié-Gonnard4b9c51e2017-04-20 15:50:26 +0200525#endif /* MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnard054433c2017-03-22 11:18:33 +0100526
Janos Follathdf9295b2019-02-26 12:36:52 +0000527/*
528 * Get the type of a curve
529 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100530mbedtls_ecp_curve_type mbedtls_ecp_get_type(const mbedtls_ecp_group *grp);
Janos Follathdf9295b2019-02-26 12:36:52 +0000531
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100532/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100533 * \brief This function retrieves the information defined in
Gilles Peskine377c91e2021-06-02 14:37:57 +0200534 * mbedtls_ecp_curve_info() for all supported curves.
Manuel Pégourié-Gonnardda179e42013-09-18 15:31:24 +0200535 *
Gilles Peskined2085f52019-02-11 18:43:55 +0100536 * \note This function returns information about all curves
537 * supported by the library. Some curves may not be
538 * supported for all algorithms. Call mbedtls_ecdh_can_do()
539 * or mbedtls_ecdsa_can_do() to check if a curve is
540 * supported for ECDH or ECDSA.
541 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100542 * \return A statically allocated array. The last entry is 0.
Manuel Pégourié-Gonnardda179e42013-09-18 15:31:24 +0200543 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100544const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list(void);
Manuel Pégourié-Gonnardda179e42013-09-18 15:31:24 +0200545
546/**
Rose Zadikf56cb342018-04-19 12:49:10 +0100547 * \brief This function retrieves the list of internal group
548 * identifiers of all supported curves in the order of
549 * preference.
Manuel Pégourié-Gonnardac719412014-02-04 14:48:50 +0100550 *
Gilles Peskined2085f52019-02-11 18:43:55 +0100551 * \note This function returns information about all curves
552 * supported by the library. Some curves may not be
553 * supported for all algorithms. Call mbedtls_ecdh_can_do()
554 * or mbedtls_ecdsa_can_do() to check if a curve is
555 * supported for ECDH or ECDSA.
556 *
Manuel Pégourié-Gonnardac719412014-02-04 14:48:50 +0100557 * \return A statically allocated array,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200558 * terminated with MBEDTLS_ECP_DP_NONE.
Manuel Pégourié-Gonnardac719412014-02-04 14:48:50 +0100559 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100560const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list(void);
Manuel Pégourié-Gonnardac719412014-02-04 14:48:50 +0100561
562/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100563 * \brief This function retrieves curve information from an internal
564 * group identifier.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200565 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100566 * \param grp_id An \c MBEDTLS_ECP_DP_XXX value.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200567 *
Rose Zadikf56cb342018-04-19 12:49:10 +0100568 * \return The associated curve information on success.
569 * \return NULL on failure.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200570 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100571const 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 +0200572
573/**
Rose Zadika7a61552018-04-24 13:14:01 +0100574 * \brief This function retrieves curve information from a TLS
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100575 * NamedCurve value.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200576 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100577 * \param tls_id An \c MBEDTLS_ECP_DP_XXX value.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200578 *
Rose Zadikf56cb342018-04-19 12:49:10 +0100579 * \return The associated curve information on success.
580 * \return NULL on failure.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200581 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100582const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id(uint16_t tls_id);
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200583
584/**
Rose Zadika7a61552018-04-24 13:14:01 +0100585 * \brief This function retrieves curve information from a
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100586 * human-readable name.
Manuel Pégourié-Gonnard0267e3d2013-11-30 15:10:14 +0100587 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100588 * \param name The human-readable name.
Manuel Pégourié-Gonnard0267e3d2013-11-30 15:10:14 +0100589 *
Rose Zadikf56cb342018-04-19 12:49:10 +0100590 * \return The associated curve information on success.
591 * \return NULL on failure.
Manuel Pégourié-Gonnard0267e3d2013-11-30 15:10:14 +0100592 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100593const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name(const char *name);
Manuel Pégourié-Gonnard0267e3d2013-11-30 15:10:14 +0100594
595/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100596 * \brief This function initializes a point as zero.
597 *
598 * \param pt The point to initialize.
Manuel Pégourié-Gonnardae180d02012-11-02 18:14:40 +0100599 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100600void mbedtls_ecp_point_init(mbedtls_ecp_point *pt);
Manuel Pégourié-Gonnardae180d02012-11-02 18:14:40 +0100601
602/**
Rose Zadikf56cb342018-04-19 12:49:10 +0100603 * \brief This function initializes an ECP group context
Rose Zadika7a61552018-04-24 13:14:01 +0100604 * without loading any domain parameters.
Rose Zadikf56cb342018-04-19 12:49:10 +0100605 *
606 * \note After this function is called, domain parameters
607 * for various ECP groups can be loaded through the
Gilles Peskine13cf3ec2018-11-07 22:06:48 +0100608 * mbedtls_ecp_group_load() or mbedtls_ecp_tls_read_group()
Rose Zadikf56cb342018-04-19 12:49:10 +0100609 * functions.
Manuel Pégourié-Gonnardb505c272012-11-05 17:27:54 +0100610 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100611void mbedtls_ecp_group_init(mbedtls_ecp_group *grp);
Manuel Pégourié-Gonnardb505c272012-11-05 17:27:54 +0100612
613/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100614 * \brief This function initializes a key pair as an invalid one.
615 *
616 * \param key The key pair to initialize.
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200617 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100618void mbedtls_ecp_keypair_init(mbedtls_ecp_keypair *key);
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200619
620/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100621 * \brief This function frees the components of a point.
622 *
623 * \param pt The point to free.
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100624 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100625void mbedtls_ecp_point_free(mbedtls_ecp_point *pt);
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100626
627/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100628 * \brief This function frees the components of an ECP group.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500629 *
630 * \param grp The group to free. This may be \c NULL, in which
631 * case this function returns immediately. If it is not
632 * \c NULL, it must point to an initialized ECP group.
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100633 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100634void mbedtls_ecp_group_free(mbedtls_ecp_group *grp);
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100635
636/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100637 * \brief This function frees the components of a key pair.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500638 *
639 * \param key The key pair to free. This may be \c NULL, in which
640 * case this function returns immediately. If it is not
641 * \c NULL, it must point to an initialized ECP key pair.
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200642 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100643void mbedtls_ecp_keypair_free(mbedtls_ecp_keypair *key);
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200644
Manuel Pégourié-Gonnard4b9c51e2017-04-20 15:50:26 +0200645#if defined(MBEDTLS_ECP_RESTARTABLE)
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200646/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500647 * \brief Initialize a restart context.
648 *
649 * \param ctx The restart context to initialize. This must
650 * not be \c NULL.
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200651 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100652void mbedtls_ecp_restart_init(mbedtls_ecp_restart_ctx *ctx);
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200653
654/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500655 * \brief Free the components of a restart context.
656 *
657 * \param ctx The restart context to free. This may be \c NULL, in which
658 * case this function returns immediately. If it is not
659 * \c NULL, it must point to an initialized restart context.
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200660 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100661void mbedtls_ecp_restart_free(mbedtls_ecp_restart_ctx *ctx);
Manuel Pégourié-Gonnard4b9c51e2017-04-20 15:50:26 +0200662#endif /* MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200663
Manuel Pégourié-Gonnardb8c6e0e2013-07-01 13:40:52 +0200664/**
Rose Zadika7a61552018-04-24 13:14:01 +0100665 * \brief This function copies the contents of point \p Q into
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100666 * point \p P.
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100667 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500668 * \param P The destination point. This must be initialized.
669 * \param Q The source point. This must be initialized.
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100670 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100671 * \return \c 0 on success.
Rose Zadikf56cb342018-04-19 12:49:10 +0100672 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500673 * \return Another negative error code for other kinds of failure.
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100674 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100675int mbedtls_ecp_copy(mbedtls_ecp_point *P, const mbedtls_ecp_point *Q);
Manuel Pégourié-Gonnard883f3132012-11-02 09:40:25 +0100676
677/**
Rose Zadika7a61552018-04-24 13:14:01 +0100678 * \brief This function copies the contents of group \p src into
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100679 * group \p dst.
Manuel Pégourié-Gonnarde09631b2013-08-12 15:44:31 +0200680 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500681 * \param dst The destination group. This must be initialized.
682 * \param src The source group. This must be initialized.
Manuel Pégourié-Gonnarde09631b2013-08-12 15:44:31 +0200683 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100684 * \return \c 0 on success.
Rose Zadikf56cb342018-04-19 12:49:10 +0100685 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500686 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnarde09631b2013-08-12 15:44:31 +0200687 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100688int mbedtls_ecp_group_copy(mbedtls_ecp_group *dst,
689 const mbedtls_ecp_group *src);
Manuel Pégourié-Gonnarde09631b2013-08-12 15:44:31 +0200690
691/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500692 * \brief This function sets a point to the point at infinity.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200693 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500694 * \param pt The point to set. This must be initialized.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200695 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100696 * \return \c 0 on success.
Rose Zadikf56cb342018-04-19 12:49:10 +0100697 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500698 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200699 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100700int mbedtls_ecp_set_zero(mbedtls_ecp_point *pt);
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200701
702/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500703 * \brief This function checks if a point is the point at infinity.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200704 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500705 * \param pt The point to test. This must be initialized.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200706 *
Rose Zadikf56cb342018-04-19 12:49:10 +0100707 * \return \c 1 if the point is zero.
708 * \return \c 0 if the point is non-zero.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500709 * \return A negative error code on failure.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200710 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100711int mbedtls_ecp_is_zero(mbedtls_ecp_point *pt);
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200712
713/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100714 * \brief This function compares two points.
Manuel Pégourié-Gonnard6029a852015-08-11 15:44:41 +0200715 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100716 * \note This assumes that the points are normalized. Otherwise,
Manuel Pégourié-Gonnard6029a852015-08-11 15:44:41 +0200717 * they may compare as "not equal" even if they are.
718 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500719 * \param P The first point to compare. This must be initialized.
720 * \param Q The second point to compare. This must be initialized.
Manuel Pégourié-Gonnard6029a852015-08-11 15:44:41 +0200721 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100722 * \return \c 0 if the points are equal.
723 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal.
Manuel Pégourié-Gonnard6029a852015-08-11 15:44:41 +0200724 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100725int mbedtls_ecp_point_cmp(const mbedtls_ecp_point *P,
726 const mbedtls_ecp_point *Q);
Manuel Pégourié-Gonnard6029a852015-08-11 15:44:41 +0200727
728/**
Rose Zadika7a61552018-04-24 13:14:01 +0100729 * \brief This function imports a non-zero point from two ASCII
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100730 * strings.
Manuel Pégourié-Gonnard847395a2012-11-05 13:13:44 +0100731 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500732 * \param P The destination point. This must be initialized.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100733 * \param radix The numeric base of the input.
734 * \param x The first affine coordinate, as a null-terminated string.
735 * \param y The second affine coordinate, as a null-terminated string.
Manuel Pégourié-Gonnard847395a2012-11-05 13:13:44 +0100736 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100737 * \return \c 0 on success.
738 * \return An \c MBEDTLS_ERR_MPI_XXX error code on failure.
Manuel Pégourié-Gonnard847395a2012-11-05 13:13:44 +0100739 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100740int mbedtls_ecp_point_read_string(mbedtls_ecp_point *P, int radix,
741 const char *x, const char *y);
Manuel Pégourié-Gonnard847395a2012-11-05 13:13:44 +0100742
743/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100744 * \brief This function exports a point into unsigned binary data.
Manuel Pégourié-Gonnarde19feb52012-11-24 14:10:14 +0100745 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100746 * \param grp The group to which the point should belong.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500747 * This must be initialized and have group parameters
748 * set, for example through mbedtls_ecp_group_load().
749 * \param P The point to export. This must be initialized.
750 * \param format The point format. This must be either
751 * #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
Janos Follath28eb06d2019-02-26 10:53:34 +0000752 * (For groups without these formats, this parameter is
753 * ignored. But it still has to be either of the above
754 * values.)
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500755 * \param olen The address at which to store the length of
756 * the output in Bytes. This must not be \c NULL.
757 * \param buf The output buffer. This must be a writable buffer
758 * of length \p buflen Bytes.
759 * \param buflen The length of the output buffer \p buf in Bytes.
Manuel Pégourié-Gonnarde19feb52012-11-24 14:10:14 +0100760 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100761 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500762 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer
763 * is too small to hold the point.
Janos Follath28eb06d2019-02-26 10:53:34 +0000764 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
765 * or the export for the given group is not implemented.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500766 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnarde19feb52012-11-24 14:10:14 +0100767 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100768int mbedtls_ecp_point_write_binary(const mbedtls_ecp_group *grp,
769 const mbedtls_ecp_point *P,
770 int format, size_t *olen,
771 unsigned char *buf, size_t buflen);
Manuel Pégourié-Gonnarde19feb52012-11-24 14:10:14 +0100772
773/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100774 * \brief This function imports a point from unsigned binary data.
Manuel Pégourié-Gonnard5e402d82012-11-24 16:19:42 +0100775 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100776 * \note This function does not check that the point actually
Rose Zadika7a61552018-04-24 13:14:01 +0100777 * belongs to the given group, see mbedtls_ecp_check_pubkey()
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100778 * for that.
Manuel Pégourié-Gonnard5e402d82012-11-24 16:19:42 +0100779 *
Valerio Setti78f79d32023-02-07 08:33:26 +0100780 * \note For compressed points, see #MBEDTLS_ECP_PF_COMPRESSED for
781 * limitations.
782 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100783 * \param grp The group to which the point should belong.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500784 * This must be initialized and have group parameters
785 * set, for example through mbedtls_ecp_group_load().
786 * \param P The destination context to import the point to.
787 * This must be initialized.
788 * \param buf The input buffer. This must be a readable buffer
789 * of length \p ilen Bytes.
790 * \param ilen The length of the input buffer \p buf in Bytes.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100791 *
792 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500793 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
Rose Zadikf56cb342018-04-19 12:49:10 +0100794 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
Janos Follath28eb06d2019-02-26 10:53:34 +0000795 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the import for the
796 * given group is not implemented.
Manuel Pégourié-Gonnard5e402d82012-11-24 16:19:42 +0100797 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100798int mbedtls_ecp_point_read_binary(const mbedtls_ecp_group *grp,
799 mbedtls_ecp_point *P,
800 const unsigned char *buf, size_t ilen);
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100801
Manuel Pégourié-Gonnard5e402d82012-11-24 16:19:42 +0100802/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100803 * \brief This function imports a point from a TLS ECPoint record.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200804 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500805 * \note On function return, \p *buf is updated to point immediately
Rose Zadikf56cb342018-04-19 12:49:10 +0100806 * after the ECPoint record.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200807 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500808 * \param grp The ECP group to use.
809 * This must be initialized and have group parameters
810 * set, for example through mbedtls_ecp_group_load().
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100811 * \param pt The destination point.
Rose Zadikf56cb342018-04-19 12:49:10 +0100812 * \param buf The address of the pointer to the start of the input buffer.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100813 * \param len The length of the buffer.
Manuel Pégourié-Gonnard150c4f62014-11-21 09:14:52 +0100814 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100815 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500816 * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization
817 * failure.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100818 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200819 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100820int mbedtls_ecp_tls_read_point(const mbedtls_ecp_group *grp,
821 mbedtls_ecp_point *pt,
822 const unsigned char **buf, size_t len);
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200823
824/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500825 * \brief This function exports a point as a TLS ECPoint record
826 * defined in RFC 4492, Section 5.4.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200827 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500828 * \param grp The ECP group to use.
829 * This must be initialized and have group parameters
830 * set, for example through mbedtls_ecp_group_load().
831 * \param pt The point to be exported. This must be initialized.
832 * \param format The point format to use. This must be either
833 * #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
834 * \param olen The address at which to store the length in Bytes
835 * of the data written.
836 * \param buf The target buffer. This must be a writable buffer of
837 * length \p blen Bytes.
838 * \param blen The length of the target buffer \p buf in Bytes.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200839 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100840 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500841 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
842 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the target buffer
843 * is too small to hold the exported point.
844 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200845 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100846int mbedtls_ecp_tls_write_point(const mbedtls_ecp_group *grp,
847 const mbedtls_ecp_point *pt,
848 int format, size_t *olen,
849 unsigned char *buf, size_t blen);
Manuel Pégourié-Gonnardcae6f3e2013-10-23 20:19:57 +0200850
851/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500852 * \brief This function sets up an ECP group context
853 * from a standardized set of domain parameters.
Manuel Pégourié-Gonnarda5402fe2012-11-07 20:24:05 +0100854 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100855 * \note The index should be a value of the NamedCurve enum,
Rose Zadika7a61552018-04-24 13:14:01 +0100856 * as defined in <em>RFC-4492: Elliptic Curve Cryptography
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100857 * (ECC) Cipher Suites for Transport Layer Security (TLS)</em>,
858 * usually in the form of an \c MBEDTLS_ECP_DP_XXX macro.
Manuel Pégourié-Gonnarda5402fe2012-11-07 20:24:05 +0100859 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500860 * \param grp The group context to setup. This must be initialized.
Rose Zadikf56cb342018-04-19 12:49:10 +0100861 * \param id The identifier of the domain parameter set to load.
Manuel Pégourié-Gonnarda5402fe2012-11-07 20:24:05 +0100862 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500863 * \return \c 0 on success.
864 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p id doesn't
865 * correspond to a known group.
866 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnarda5402fe2012-11-07 20:24:05 +0100867 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100868int mbedtls_ecp_group_load(mbedtls_ecp_group *grp, mbedtls_ecp_group_id id);
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100869
870/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500871 * \brief This function sets up an ECP group context from a TLS
872 * ECParameters record as defined in RFC 4492, Section 5.4.
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100873 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500874 * \note The read pointer \p buf is updated to point right after
875 * the ECParameters record on exit.
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100876 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500877 * \param grp The group context to setup. This must be initialized.
Rose Zadikf56cb342018-04-19 12:49:10 +0100878 * \param buf The address of the pointer to the start of the input buffer.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500879 * \param len The length of the input buffer \c *buf in Bytes.
Manuel Pégourié-Gonnard150c4f62014-11-21 09:14:52 +0100880 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100881 * \return \c 0 on success.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100882 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500883 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
884 * recognized.
885 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnard1a967282013-02-09 17:03:58 +0100886 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100887int mbedtls_ecp_tls_read_group(mbedtls_ecp_group *grp,
888 const unsigned char **buf, size_t len);
Manuel Pégourié-Gonnarda5402fe2012-11-07 20:24:05 +0100889
890/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500891 * \brief This function extracts an elliptic curve group ID from a
892 * TLS ECParameters record as defined in RFC 4492, Section 5.4.
Manuel Pégourié-Gonnardb3258872013-02-10 12:06:19 +0100893 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500894 * \note The read pointer \p buf is updated to point right after
895 * the ECParameters record on exit.
896 *
897 * \param grp The address at which to store the group id.
898 * This must not be \c NULL.
899 * \param buf The address of the pointer to the start of the input buffer.
900 * \param len The length of the input buffer \c *buf in Bytes.
Manuel Pégourié-Gonnardb3258872013-02-10 12:06:19 +0100901 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100902 * \return \c 0 on success.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500903 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
904 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
905 * recognized.
906 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnardb3258872013-02-10 12:06:19 +0100907 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100908int mbedtls_ecp_tls_read_group_id(mbedtls_ecp_group_id *grp,
909 const unsigned char **buf,
910 size_t len);
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500911/**
912 * \brief This function exports an elliptic curve as a TLS
913 * ECParameters record as defined in RFC 4492, Section 5.4.
914 *
915 * \param grp The ECP group to be exported.
916 * This must be initialized and have group parameters
917 * set, for example through mbedtls_ecp_group_load().
918 * \param olen The address at which to store the number of Bytes written.
919 * This must not be \c NULL.
920 * \param buf The buffer to write to. This must be a writable buffer
921 * of length \p blen Bytes.
922 * \param blen The length of the output buffer \p buf in Bytes.
923 *
924 * \return \c 0 on success.
925 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output
926 * buffer is too small to hold the exported group.
927 * \return Another negative error code on other kinds of failure.
928 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100929int mbedtls_ecp_tls_write_group(const mbedtls_ecp_group *grp,
930 size_t *olen,
931 unsigned char *buf, size_t blen);
Manuel Pégourié-Gonnardb3258872013-02-10 12:06:19 +0100932
933/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500934 * \brief This function performs a scalar multiplication of a point
935 * by an integer: \p R = \p m * \p P.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100936 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100937 * It is not thread-safe to use same group in multiple threads.
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +0200938 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100939 * \note To prevent timing attacks, this function
940 * executes the exact same sequence of base-field
941 * operations for any valid \p m. It avoids any if-branch or
Jan Bruckner9ff6f8c2022-08-22 16:05:58 +0200942 * array index depending on the value of \p m. It also uses
Manuel Pégourié-Gonnardaa3ed6f2021-06-15 11:29:26 +0200943 * \p f_rng to randomize some intermediate results.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100944 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500945 * \param grp The ECP group to use.
946 * This must be initialized and have group parameters
947 * set, for example through mbedtls_ecp_group_load().
948 * \param R The point in which to store the result of the calculation.
949 * This must be initialized.
950 * \param m The integer by which to multiply. This must be initialized.
951 * \param P The point to multiply. This must be initialized.
Manuel Pégourié-Gonnardaa3ed6f2021-06-15 11:29:26 +0200952 * \param f_rng The RNG function. This must not be \c NULL.
953 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c
954 * NULL if \p f_rng doesn't need a context.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +0100955 *
956 * \return \c 0 on success.
Rose Zadikf56cb342018-04-19 12:49:10 +0100957 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
958 * key, or \p P is not a valid public key.
959 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500960 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200961 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100962int mbedtls_ecp_mul(mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
963 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
964 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200965
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200966/**
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200967 * \brief This function performs multiplication of a point by
968 * an integer: \p R = \p m * \p P in a restartable way.
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200969 *
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200970 * \see mbedtls_ecp_mul()
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200971 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200972 * \note This function does the same as \c mbedtls_ecp_mul(), but
973 * it can return early and restart according to the limit set
974 * with \c mbedtls_ecp_set_max_ops() to reduce blocking.
975 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500976 * \param grp The ECP group to use.
977 * This must be initialized and have group parameters
978 * set, for example through mbedtls_ecp_group_load().
979 * \param R The point in which to store the result of the calculation.
980 * This must be initialized.
981 * \param m The integer by which to multiply. This must be initialized.
982 * \param P The point to multiply. This must be initialized.
Manuel Pégourié-Gonnardaa3ed6f2021-06-15 11:29:26 +0200983 * \param f_rng The RNG function. This must not be \c NULL.
984 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c
985 * NULL if \p f_rng doesn't need a context.
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +0200986 * \param rs_ctx The restart context (NULL disables restart).
Manuel Pégourié-Gonnardb739a712017-04-19 10:11:56 +0200987 *
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200988 * \return \c 0 on success.
989 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
990 * key, or \p P is not a valid public key.
991 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
992 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnard8467e682017-04-20 09:47:06 +0200993 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500994 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +0100995 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100996int mbedtls_ecp_mul_restartable(mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
997 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
998 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
999 mbedtls_ecp_restart_ctx *rs_ctx);
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +01001000
Gilles Peskine9b99a892018-09-14 18:32:19 +02001001#if defined(MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED)
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +01001002/**
Chien Wong153ae462023-01-31 23:27:03 +08001003 * \brief This function checks if domain parameter A of the curve is
1004 * \c -3.
1005 *
1006 * \note This function is only defined for short Weierstrass curves.
1007 * It may not be included in builds without any short
1008 * Weierstrass curve.
1009 *
1010 * \param grp The ECP group to use.
1011 * This must be initialized and have group parameters
1012 * set, for example through mbedtls_ecp_group_load().
1013 *
1014 * \return \c 1 if <code>A = -3</code>.
1015 * \return \c 0 Otherwise.
1016 */
1017static inline int mbedtls_ecp_group_a_is_minus_3(const mbedtls_ecp_group *grp)
1018{
1019 return grp->A.MBEDTLS_PRIVATE(p) == NULL;
1020}
1021
1022/**
Rose Zadika7a61552018-04-24 13:14:01 +01001023 * \brief This function performs multiplication and addition of two
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001024 * points by integers: \p R = \p m * \p P + \p n * \p Q
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +02001025 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001026 * It is not thread-safe to use same group in multiple threads.
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +02001027 *
Rose Zadika7a61552018-04-24 13:14:01 +01001028 * \note In contrast to mbedtls_ecp_mul(), this function does not
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001029 * guarantee a constant execution flow and timing.
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +02001030 *
Gilles Peskine9b99a892018-09-14 18:32:19 +02001031 * \note This function is only defined for short Weierstrass curves.
1032 * It may not be included in builds without any short
1033 * Weierstrass curve.
1034 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001035 * \param grp The ECP group to use.
1036 * This must be initialized and have group parameters
1037 * set, for example through mbedtls_ecp_group_load().
1038 * \param R The point in which to store the result of the calculation.
1039 * This must be initialized.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001040 * \param m The integer by which to multiply \p P.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001041 * This must be initialized.
1042 * \param P The point to multiply by \p m. This must be initialized.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001043 * \param n The integer by which to multiply \p Q.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001044 * This must be initialized.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001045 * \param Q The point to be multiplied by \p n.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001046 * This must be initialized.
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +02001047 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001048 * \return \c 0 on success.
Rose Zadika7a61552018-04-24 13:14:01 +01001049 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
1050 * valid private keys, or \p P or \p Q are not valid public
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001051 * keys.
Rose Zadikf56cb342018-04-19 12:49:10 +01001052 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
Gilles Peskine9b99a892018-09-14 18:32:19 +02001053 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p grp does not
1054 * designate a short Weierstrass curve.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001055 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +02001056 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001057int mbedtls_ecp_muladd(mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
1058 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
1059 const mbedtls_mpi *n, const mbedtls_ecp_point *Q);
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +02001060
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +02001061/**
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001062 * \brief This function performs multiplication and addition of two
1063 * points by integers: \p R = \p m * \p P + \p n * \p Q in a
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +02001064 * restartable way.
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +02001065 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001066 * \see \c mbedtls_ecp_muladd()
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +02001067 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001068 * \note This function works the same as \c mbedtls_ecp_muladd(),
1069 * but it can return early and restart according to the limit
1070 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +02001071 *
Gilles Peskine9b99a892018-09-14 18:32:19 +02001072 * \note This function is only defined for short Weierstrass curves.
1073 * It may not be included in builds without any short
1074 * Weierstrass curve.
1075 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001076 * \param grp The ECP group to use.
1077 * This must be initialized and have group parameters
1078 * set, for example through mbedtls_ecp_group_load().
1079 * \param R The point in which to store the result of the calculation.
1080 * This must be initialized.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001081 * \param m The integer by which to multiply \p P.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001082 * This must be initialized.
1083 * \param P The point to multiply by \p m. This must be initialized.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001084 * \param n The integer by which to multiply \p Q.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001085 * This must be initialized.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001086 * \param Q The point to be multiplied by \p n.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001087 * This must be initialized.
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +02001088 * \param rs_ctx The restart context (NULL disables restart).
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001089 *
1090 * \return \c 0 on success.
1091 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
1092 * valid private keys, or \p P or \p Q are not valid public
1093 * keys.
1094 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
Gilles Peskine9b99a892018-09-14 18:32:19 +02001095 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p grp does not
1096 * designate a short Weierstrass curve.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001097 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +02001098 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001099 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +02001100 */
1101int mbedtls_ecp_muladd_restartable(
Gilles Peskine449bd832023-01-11 14:50:10 +01001102 mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
1103 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
1104 const mbedtls_mpi *n, const mbedtls_ecp_point *Q,
1105 mbedtls_ecp_restart_ctx *rs_ctx);
Gilles Peskine9b99a892018-09-14 18:32:19 +02001106#endif /* MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED */
Manuel Pégourié-Gonnard54dd6522017-04-20 13:36:18 +02001107
Manuel Pégourié-Gonnard56cc88a2015-05-11 18:40:45 +02001108/**
Rose Zadika7a61552018-04-24 13:14:01 +01001109 * \brief This function checks that a point is a valid public key
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001110 * on this curve.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001111 *
Rose Zadika7a61552018-04-24 13:14:01 +01001112 * It only checks that the point is non-zero, has
1113 * valid coordinates and lies on the curve. It does not verify
Andrzej Kurek3bedb5b2022-02-17 14:39:00 -05001114 * that it is indeed a multiple of \c G. This additional
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001115 * check is computationally more expensive, is not required
1116 * by standards, and should not be necessary if the group
Rose Zadika7a61552018-04-24 13:14:01 +01001117 * used has a small cofactor. In particular, it is useless for
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001118 * the NIST groups which all have a cofactor of 1.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001119 *
Rose Zadika7a61552018-04-24 13:14:01 +01001120 * \note This function uses bare components rather than an
1121 * ::mbedtls_ecp_keypair structure, to ease use with other
1122 * structures, such as ::mbedtls_ecdh_context or
Rose Zadikb2e111a2018-04-20 10:13:48 +01001123 * ::mbedtls_ecdsa_context.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001124 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001125 * \param grp The ECP group the point should belong to.
1126 * This must be initialized and have group parameters
1127 * set, for example through mbedtls_ecp_group_load().
1128 * \param pt The point to check. This must be initialized.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001129 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001130 * \return \c 0 if the point is a valid public key.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001131 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not
1132 * a valid public key for the given curve.
1133 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001134 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001135int mbedtls_ecp_check_pubkey(const mbedtls_ecp_group *grp,
1136 const mbedtls_ecp_point *pt);
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001137
1138/**
Andrzej Kurek3bedb5b2022-02-17 14:39:00 -05001139 * \brief This function checks that an \c mbedtls_mpi is a
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001140 * valid private key for this curve.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001141 *
Rose Zadika7a61552018-04-24 13:14:01 +01001142 * \note This function uses bare components rather than an
1143 * ::mbedtls_ecp_keypair structure to ease use with other
1144 * structures, such as ::mbedtls_ecdh_context or
Rose Zadikb2e111a2018-04-20 10:13:48 +01001145 * ::mbedtls_ecdsa_context.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001146 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001147 * \param grp The ECP group the private key should belong to.
1148 * This must be initialized and have group parameters
1149 * set, for example through mbedtls_ecp_group_load().
1150 * \param d The integer to check. This must be initialized.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001151 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001152 * \return \c 0 if the point is a valid private key.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001153 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not a valid
1154 * private key for the given curve.
1155 * \return Another negative error code on other kinds of failure.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001156 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001157int mbedtls_ecp_check_privkey(const mbedtls_ecp_group *grp,
1158 const mbedtls_mpi *d);
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001159
1160/**
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001161 * \brief This function generates a private key.
Manuel Pégourié-Gonnarda7937f92017-04-20 15:37:46 +02001162 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001163 * \param grp The ECP group to generate a private key for.
1164 * This must be initialized and have group parameters
1165 * set, for example through mbedtls_ecp_group_load().
1166 * \param d The destination MPI (secret part). This must be initialized.
1167 * \param f_rng The RNG function. This must not be \c NULL.
1168 * \param p_rng The RNG parameter to be passed to \p f_rng. This may be
1169 * \c NULL if \p f_rng doesn't need a context argument.
Manuel Pégourié-Gonnarda7937f92017-04-20 15:37:46 +02001170 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +02001171 * \return \c 0 on success.
1172 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
1173 * on failure.
Manuel Pégourié-Gonnarda7937f92017-04-20 15:37:46 +02001174 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001175int mbedtls_ecp_gen_privkey(const mbedtls_ecp_group *grp,
1176 mbedtls_mpi *d,
1177 int (*f_rng)(void *, unsigned char *, size_t),
1178 void *p_rng);
Manuel Pégourié-Gonnarda7937f92017-04-20 15:37:46 +02001179
1180/**
Rose Zadika7a61552018-04-24 13:14:01 +01001181 * \brief This function generates a keypair with a configurable base
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001182 * point.
Manuel Pégourié-Gonnardd9a3f472015-08-11 14:31:03 +02001183 *
Rose Zadika7a61552018-04-24 13:14:01 +01001184 * \note This function uses bare components rather than an
1185 * ::mbedtls_ecp_keypair structure to ease use with other
1186 * structures, such as ::mbedtls_ecdh_context or
Rose Zadikb2e111a2018-04-20 10:13:48 +01001187 * ::mbedtls_ecdsa_context.
Manuel Pégourié-Gonnardd9a3f472015-08-11 14:31:03 +02001188 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001189 * \param grp The ECP group to generate a key pair for.
1190 * This must be initialized and have group parameters
1191 * set, for example through mbedtls_ecp_group_load().
1192 * \param G The base point to use. This must be initialized
1193 * and belong to \p grp. It replaces the default base
1194 * point \c grp->G used by mbedtls_ecp_gen_keypair().
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001195 * \param d The destination MPI (secret part).
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001196 * This must be initialized.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001197 * \param Q The destination point (public part).
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001198 * This must be initialized.
1199 * \param f_rng The RNG function. This must not be \c NULL.
1200 * \param p_rng The RNG context to be passed to \p f_rng. This may
1201 * be \c NULL if \p f_rng doesn't need a context argument.
Manuel Pégourié-Gonnardd9a3f472015-08-11 14:31:03 +02001202 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001203 * \return \c 0 on success.
1204 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
1205 * on failure.
Manuel Pégourié-Gonnardd9a3f472015-08-11 14:31:03 +02001206 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001207int mbedtls_ecp_gen_keypair_base(mbedtls_ecp_group *grp,
1208 const mbedtls_ecp_point *G,
1209 mbedtls_mpi *d, mbedtls_ecp_point *Q,
1210 int (*f_rng)(void *, unsigned char *, size_t),
1211 void *p_rng);
Manuel Pégourié-Gonnardd9a3f472015-08-11 14:31:03 +02001212
1213/**
Rose Zadikf56cb342018-04-19 12:49:10 +01001214 * \brief This function generates an ECP keypair.
Manuel Pégourié-Gonnard45a035a2013-01-26 14:42:45 +01001215 *
Rose Zadika7a61552018-04-24 13:14:01 +01001216 * \note This function uses bare components rather than an
1217 * ::mbedtls_ecp_keypair structure to ease use with other
1218 * structures, such as ::mbedtls_ecdh_context or
Rose Zadikb2e111a2018-04-20 10:13:48 +01001219 * ::mbedtls_ecdsa_context.
Manuel Pégourié-Gonnard45a035a2013-01-26 14:42:45 +01001220 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001221 * \param grp The ECP group to generate a key pair for.
1222 * This must be initialized and have group parameters
1223 * set, for example through mbedtls_ecp_group_load().
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001224 * \param d The destination MPI (secret part).
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001225 * This must be initialized.
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001226 * \param Q The destination point (public part).
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001227 * This must be initialized.
1228 * \param f_rng The RNG function. This must not be \c NULL.
1229 * \param p_rng The RNG context to be passed to \p f_rng. This may
1230 * be \c NULL if \p f_rng doesn't need a context argument.
Manuel Pégourié-Gonnardc8dc2952013-07-01 14:06:13 +02001231 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001232 * \return \c 0 on success.
1233 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
1234 * on failure.
Manuel Pégourié-Gonnard45a035a2013-01-26 14:42:45 +01001235 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001236int mbedtls_ecp_gen_keypair(mbedtls_ecp_group *grp, mbedtls_mpi *d,
1237 mbedtls_ecp_point *Q,
1238 int (*f_rng)(void *, unsigned char *, size_t),
1239 void *p_rng);
Manuel Pégourié-Gonnard45a035a2013-01-26 14:42:45 +01001240
1241/**
Rose Zadikf56cb342018-04-19 12:49:10 +01001242 * \brief This function generates an ECP key.
Manuel Pégourié-Gonnard104ee1d2013-11-30 14:13:16 +01001243 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001244 * \param grp_id The ECP group identifier.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001245 * \param key The destination key. This must be initialized.
1246 * \param f_rng The RNG function to use. This must not be \c NULL.
1247 * \param p_rng The RNG context to be passed to \p f_rng. This may
1248 * be \c NULL if \p f_rng doesn't need a context argument.
Manuel Pégourié-Gonnard104ee1d2013-11-30 14:13:16 +01001249 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001250 * \return \c 0 on success.
1251 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
1252 * on failure.
Manuel Pégourié-Gonnard104ee1d2013-11-30 14:13:16 +01001253 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001254int mbedtls_ecp_gen_key(mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
1255 int (*f_rng)(void *, unsigned char *, size_t),
1256 void *p_rng);
Manuel Pégourié-Gonnard104ee1d2013-11-30 14:13:16 +01001257
Gilles Peskine28240322023-06-21 19:52:11 +02001258/** \brief Set the public key in a key pair object.
1259 *
1260 * \note This function does not check that the point actually
1261 * belongs to the given group. Call mbedtls_ecp_check_pubkey()
1262 * on \p Q before calling this function to check that.
1263 *
1264 * \note This function does not check that the public key matches
1265 * the private key that is already in \p key, if any.
1266 * To check the consistency of the resulting key pair object,
1267 * call mbedtls_ecp_check_pub_priv() after setting both
1268 * the public key and the private key.
1269 *
1270 * \param grp_id The ECP group identifier.
1271 * \param key The key pair object. It must be initialized.
1272 * If its group has already been set, it must match \p grp_id.
1273 * If its group has not been set, it will be set to \p grp_id.
1274 * If the public key has already been set, it is overwritten.
1275 * \param Q The public key to copy. This must be a point on the
1276 * curve indicated by \p grp_id.
1277 *
1278 * \return \c 0 on success.
1279 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if \p key does not
1280 * match \p grp_id.
1281 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the operation for
1282 * the group is not implemented.
1283 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
1284 * \return Another negative error code on other kinds of failure.
1285 */
1286int mbedtls_ecp_set_public_key(mbedtls_ecp_group_id grp_id,
1287 mbedtls_ecp_keypair *key,
1288 const mbedtls_ecp_point *Q);
1289
Manuel Pégourié-Gonnard30668d62014-11-06 15:25:32 +01001290/**
Janos Follathb65853c2019-02-25 16:33:28 +00001291 * \brief This function reads an elliptic curve private key.
Janos Follath171a7ef2019-02-15 16:17:45 +00001292 *
Gilles Peskine091a85a2023-06-21 19:51:28 +02001293 * \note This function does not set the public key in the
1294 * key pair object. Without a public key, the key pair object
1295 * cannot be used with operations that require the public key.
Gilles Peskinead5e4372023-12-22 21:59:46 +01001296 * Call mbedtls_ecp_keypair_calc_public() to set the public
1297 * key from the private key. Alternatively, you can call
1298 * mbedtls_ecp_set_public_key() to set the public key part,
1299 * and then optionally mbedtls_ecp_check_pub_priv() to check
1300 * that the private and public parts are consistent.
Gilles Peskine091a85a2023-06-21 19:51:28 +02001301 *
1302 * \note If a public key has already been set in the key pair
1303 * object, this function does not check that it is consistent
1304 * with the private key. Call mbedtls_ecp_check_pub_priv()
1305 * after setting both the public key and the private key
1306 * to make that check.
1307 *
Janos Follath171a7ef2019-02-15 16:17:45 +00001308 * \param grp_id The ECP group identifier.
1309 * \param key The destination key.
Tobias Nießen1e8ca122021-05-10 19:53:15 +02001310 * \param buf The buffer containing the binary representation of the
Janos Follath171a7ef2019-02-15 16:17:45 +00001311 * key. (Big endian integer for Weierstrass curves, byte
1312 * string for Montgomery curves.)
1313 * \param buflen The length of the buffer in bytes.
1314 *
1315 * \return \c 0 on success.
Janos Follathb65853c2019-02-25 16:33:28 +00001316 * \return #MBEDTLS_ERR_ECP_INVALID_KEY error if the key is
1317 * invalid.
1318 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
Janos Follath28eb06d2019-02-26 10:53:34 +00001319 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the operation for
1320 * the group is not implemented.
Janos Follathb65853c2019-02-25 16:33:28 +00001321 * \return Another negative error code on different kinds of failure.
Janos Follath171a7ef2019-02-15 16:17:45 +00001322 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001323int mbedtls_ecp_read_key(mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
1324 const unsigned char *buf, size_t buflen);
Steven Cooremande8593f2020-06-09 19:55:26 +02001325
Gilles Peskinec0f7a862024-02-19 16:50:39 +01001326#if !defined(MBEDTLS_DEPRECATED_REMOVED)
Steven Cooremande8593f2020-06-09 19:55:26 +02001327/**
1328 * \brief This function exports an elliptic curve private key.
1329 *
Gilles Peskinec0f7a862024-02-19 16:50:39 +01001330 * \deprecated Note that although this function accepts an output
Gilles Peskine1c7ff7e2024-02-19 13:49:45 +01001331 * buffer that is smaller or larger than the key, most key
1332 * import interfaces require the output to have exactly
Gilles Peskinea395bdd2024-02-19 13:30:31 +01001333 * key's nominal length. It is generally simplest to
1334 * pass the key's nominal length as \c buflen, after
1335 * checking that the output buffer is large enough.
1336 * See the description of the \p buflen parameter for
1337 * how to calculate the nominal length.
Gilles Peskineacdc52e2024-02-19 16:42:54 +01001338 * To avoid this difficulty, use mbedtls_ecp_write_key_ext()
1339 * instead.
Gilles Peskinec0f7a862024-02-19 16:50:39 +01001340 * mbedtls_ecp_write_key() is deprecated and will be
1341 * removed in a future version of the library.
Gilles Peskinea395bdd2024-02-19 13:30:31 +01001342 *
Gilles Peskine7511d4a2024-02-19 13:56:39 +01001343 * \note If the private key was not set in \p key,
1344 * the output is unspecified. Future versions
1345 * may return an error in that case.
1346 *
Steven Cooremande8593f2020-06-09 19:55:26 +02001347 * \param key The private key.
Steven Cooremanc9b7f782020-06-11 17:00:36 +02001348 * \param buf The output buffer for containing the binary representation
Gilles Peskinea395bdd2024-02-19 13:30:31 +01001349 * of the key.
1350 * For Weierstrass curves, this is the big-endian
1351 * representation, padded with null bytes at the beginning
1352 * to reach \p buflen bytes.
1353 * For Montgomery curves, this is the standard byte string
1354 * representation (which is little-endian), padded with
1355 * null bytes at the end to reach \p buflen bytes.
Steven Cooremande8593f2020-06-09 19:55:26 +02001356 * \param buflen The total length of the buffer in bytes.
Gilles Peskine1c7ff7e2024-02-19 13:49:45 +01001357 * The length of the output is
Gilles Peskinea395bdd2024-02-19 13:30:31 +01001358 * (`grp->nbits` + 7) / 8 bytes
1359 * where `grp->nbits` is the private key size in bits.
Gilles Peskine1c7ff7e2024-02-19 13:49:45 +01001360 * For Weierstrass keys, if the output buffer is smaller,
1361 * leading zeros are trimmed to fit if possible. For
1362 * Montgomery keys, the output buffer must always be large
1363 * enough for the nominal length.
Steven Cooremande8593f2020-06-09 19:55:26 +02001364 *
1365 * \return \c 0 on success.
Gilles Peskine1c7ff7e2024-02-19 13:49:45 +01001366 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL or
1367 * #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if the \p key
1368 * representation is larger than the available space in \p buf.
Steven Cooremande8593f2020-06-09 19:55:26 +02001369 * \return Another negative error code on different kinds of failure.
1370 */
Gilles Peskinec0f7a862024-02-19 16:50:39 +01001371int MBEDTLS_DEPRECATED mbedtls_ecp_write_key(mbedtls_ecp_keypair *key,
1372 unsigned char *buf, size_t buflen);
1373#endif /* MBEDTLS_DEPRECATED_REMOVED */
Steven Cooremande8593f2020-06-09 19:55:26 +02001374
Janos Follath171a7ef2019-02-15 16:17:45 +00001375/**
Gilles Peskinee3fb4cc2024-02-19 16:27:35 +01001376 * \brief This function exports an elliptic curve private key.
1377 *
1378 * \param key The private key.
1379 * \param olen On success, the length of the private key.
1380 * This is always (`grp->nbits` + 7) / 8 bytes
1381 * where `grp->nbits` is the private key size in bits.
1382 * \param buf The output buffer for containing the binary representation
1383 * of the key.
1384 * \param buflen The total length of the buffer in bytes.
1385 * #MBEDTLS_ECP_MAX_BYTES is always sufficient.
1386 *
1387 * \return \c 0 on success.
1388 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the \p key
1389 * representation is larger than the available space in \p buf.
Gilles Peskine04ae4792024-02-26 09:15:08 +01001390 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if no private key is
1391 * set in \p key.
Gilles Peskinee3fb4cc2024-02-19 16:27:35 +01001392 * \return Another negative error code on different kinds of failure.
1393 */
Gilles Peskineb395e742024-02-28 14:18:28 +01001394int mbedtls_ecp_write_key_ext(const mbedtls_ecp_keypair *key,
Gilles Peskinee3fb4cc2024-02-19 16:27:35 +01001395 size_t *olen, unsigned char *buf, size_t buflen);
1396
1397/**
Gilles Peskine62e33bc2023-06-22 22:27:32 +02001398 * \brief This function exports an elliptic curve public key.
1399 *
Gilles Peskine7511d4a2024-02-19 13:56:39 +01001400 * \note If the public key was not set in \p key,
1401 * the output is unspecified. Future versions
1402 * may return an error in that case.
1403 *
Gilles Peskine62e33bc2023-06-22 22:27:32 +02001404 * \param key The public key.
1405 * \param format The point format. This must be either
1406 * #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
1407 * (For groups without these formats, this parameter is
1408 * ignored. But it still has to be either of the above
1409 * values.)
1410 * \param olen The address at which to store the length of
1411 * the output in Bytes. This must not be \c NULL.
1412 * \param buf The output buffer. This must be a writable buffer
1413 * of length \p buflen Bytes.
1414 * \param buflen The length of the output buffer \p buf in Bytes.
1415 *
1416 * \return \c 0 on success.
1417 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer
1418 * is too small to hold the point.
1419 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
1420 * or the export for the given group is not implemented.
1421 * \return Another negative error code on other kinds of failure.
1422 */
Gilles Peskine39b7bba2024-01-02 17:56:54 +01001423int mbedtls_ecp_write_public_key(const mbedtls_ecp_keypair *key,
Gilles Peskine62e33bc2023-06-22 22:27:32 +02001424 int format, size_t *olen,
1425 unsigned char *buf, size_t buflen);
1426
1427/**
Rose Zadika7a61552018-04-24 13:14:01 +01001428 * \brief This function checks that the keypair objects
Rose Zadikb2e111a2018-04-20 10:13:48 +01001429 * \p pub and \p prv have the same group and the
1430 * same public point, and that the private key in
1431 * \p prv is consistent with the public key.
Manuel Pégourié-Gonnard30668d62014-11-06 15:25:32 +01001432 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001433 * \param pub The keypair structure holding the public key. This
1434 * must be initialized. If it contains a private key, that
1435 * part is ignored.
Rose Zadikb2e111a2018-04-20 10:13:48 +01001436 * \param prv The keypair structure holding the full keypair.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -05001437 * This must be initialized.
Manuel Pégourié-Gonnardf8c24bf2021-06-15 11:29:26 +02001438 * \param f_rng The RNG function. This must not be \c NULL.
1439 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c
1440 * NULL if \p f_rng doesn't need a context.
Manuel Pégourié-Gonnard30668d62014-11-06 15:25:32 +01001441 *
Rose Zadika7a61552018-04-24 13:14:01 +01001442 * \return \c 0 on success, meaning that the keys are valid and match.
Rose Zadikb2e111a2018-04-20 10:13:48 +01001443 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match.
Rose Zadika7a61552018-04-24 13:14:01 +01001444 * \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
Rose Zadikb2e111a2018-04-20 10:13:48 +01001445 * error code on calculation failure.
Manuel Pégourié-Gonnard30668d62014-11-06 15:25:32 +01001446 */
Manuel Pégourié-Gonnardf8c24bf2021-06-15 11:29:26 +02001447int mbedtls_ecp_check_pub_priv(
Gilles Peskine449bd832023-01-11 14:50:10 +01001448 const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv,
1449 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
Manuel Pégourié-Gonnard30668d62014-11-06 15:25:32 +01001450
Gilles Peskine7ea72022023-06-21 20:39:08 +02001451/** \brief Calculate the public key from a private key in a key pair.
1452 *
1453 * \param key A keypair structure. It must have a private key set.
1454 * If the public key is set, it will be overwritten.
1455 * \param f_rng The RNG function. This must not be \c NULL.
1456 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c
1457 * NULL if \p f_rng doesn't need a context.
1458 *
1459 * \return \c 0 on success. The key pair object can be used for
1460 * operations that require the public key.
1461 * \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
1462 * error code on calculation failure.
1463 */
1464int mbedtls_ecp_keypair_calc_public(
1465 mbedtls_ecp_keypair *key,
1466 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
1467
Gilles Peskinee6886102023-06-21 18:22:06 +02001468/** \brief Query the group that a key pair belongs to.
1469 *
1470 * \param key The key pair to query.
1471 *
1472 * \return The group ID for the group registered in the key pair
1473 * object.
1474 * This is \c MBEDTLS_ECP_DP_NONE if no group has been set
1475 * in the key pair object.
1476 */
1477mbedtls_ecp_group_id mbedtls_ecp_keypair_get_group_id(
1478 const mbedtls_ecp_keypair *key);
1479
Przemek Stekiel711d0f52022-03-18 13:52:26 +01001480/**
1481 * \brief This function exports generic key-pair parameters.
1482 *
Gilles Peskineba5b5d62023-06-21 18:24:04 +02001483 * Each of the output parameters can be a null pointer
1484 * if you do not need that parameter.
1485 *
Gilles Peskine7511d4a2024-02-19 13:56:39 +01001486 * \note If the private key or the public key was not set in \p key,
1487 * the corresponding output is unspecified. Future versions
1488 * may return an error in that case.
1489 *
Przemek Stekiela677b5f2022-03-21 07:25:45 +01001490 * \param key The key pair to export from.
Przemek Stekiel711d0f52022-03-18 13:52:26 +01001491 * \param grp Slot for exported ECP group.
Gilles Peskineba5b5d62023-06-21 18:24:04 +02001492 * It must either be null or point to an initialized ECP group.
Przemek Stekiel711d0f52022-03-18 13:52:26 +01001493 * \param d Slot for the exported secret value.
Gilles Peskineba5b5d62023-06-21 18:24:04 +02001494 * It must either be null or point to an initialized mpi.
Przemek Stekiel711d0f52022-03-18 13:52:26 +01001495 * \param Q Slot for the exported public value.
Gilles Peskineba5b5d62023-06-21 18:24:04 +02001496 * It must either be null or point to an initialized ECP point.
Przemek Stekiel711d0f52022-03-18 13:52:26 +01001497 *
1498 * \return \c 0 on success,
1499 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
1500 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if key id doesn't
1501 * correspond to a known group.
1502 * \return Another negative error code on other kinds of failure.
1503 */
1504int mbedtls_ecp_export(const mbedtls_ecp_keypair *key, mbedtls_ecp_group *grp,
1505 mbedtls_mpi *d, mbedtls_ecp_point *Q);
1506
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001507#if defined(MBEDTLS_SELF_TEST)
Janos Follathb0697532016-08-18 12:38:46 +01001508
Manuel Pégourié-Gonnard104ee1d2013-11-30 14:13:16 +01001509/**
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001510 * \brief The ECP checkup routine.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +01001511 *
Rose Zadikd3c9bfc2018-04-17 10:56:55 +01001512 * \return \c 0 on success.
1513 * \return \c 1 on failure.
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +01001514 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001515int mbedtls_ecp_self_test(int verbose);
Janos Follathb0697532016-08-18 12:38:46 +01001516
Janos Follath372697b2016-10-28 16:53:11 +01001517#endif /* MBEDTLS_SELF_TEST */
Manuel Pégourié-Gonnard39d2adb2012-10-31 09:26:55 +01001518
1519#ifdef __cplusplus
1520}
1521#endif
1522
Paul Bakker9af723c2014-05-01 13:03:14 +02001523#endif /* ecp.h */