1 /**
2 * \file ecp.h
3 *
4 * \brief This file provides an API for Elliptic Curves over GF(P) (ECP).
5 *
6 * 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
9 * <em>RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites
10 * for Transport Layer Security (TLS)</em>.
11 *
12 * <em>RFC-2409: The Internet Key Exchange (IKE)</em> defines ECP
13 * group types.
14 *
15 */
16
17 /*
18 * Copyright The Mbed TLS Contributors
19 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
20 */
21
22 #ifndef MBEDTLS_ECP_H
23 #define MBEDTLS_ECP_H
24 #include "mbedtls/private_access.h"
25
26 #include "mbedtls/build_info.h"
27 #include "mbedtls/platform_util.h"
28
29 #include "mbedtls/bignum.h"
30
31 /*
32 * ECP error codes
33 */
34 /** 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
52
53 /* 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) || \
60 defined(MBEDTLS_ECP_DP_BP256R1_ENABLED) || \
61 defined(MBEDTLS_ECP_DP_BP384R1_ENABLED) || \
62 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)
66 #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
73 #ifdef __cplusplus
74 extern "C" {
75 #endif
76
77 /**
78 * Domain-parameter identifiers: curve, subgroup, and generator.
79 *
80 * \note Only curves over prime fields are supported.
81 *
82 * \warning This library does not support validation of arbitrary domain
83 * parameters. Therefore, only standardized domain parameters from trusted
84 * sources should be used. See mbedtls_ecp_group_load().
85 */
86 /* 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.
89 * - Increment MBEDTLS_ECP_DP_MAX below if needed.
90 * - Update the calculation of MBEDTLS_ECP_MAX_BITS below.
91 * - Add the corresponding MBEDTLS_ECP_DP_xxx_ENABLED macro definition to
92 * mbedtls_config.h.
93 * - 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.
99 * - Add the curve to applicable profiles in x509_crt.c.
100 * - Add the curve to applicable presets in ssl_tls.c.
101 */
102 typedef enum {
103 MBEDTLS_ECP_DP_NONE = 0, /*!< Curve not defined. */
104 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. */
109 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. */
112 MBEDTLS_ECP_DP_CURVE25519, /*!< Domain parameters for Curve25519. */
113 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. */
116 MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for Curve448. */
117 } mbedtls_ecp_group_id;
118
119 /**
120 * The number of supported curves, plus one for #MBEDTLS_ECP_DP_NONE.
121 */
122 #define MBEDTLS_ECP_DP_MAX 14
123
124 /*
125 * Curve types
126 */
127 typedef enum {
128 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
133 /**
134 * Curve information, for use by other modules.
135 *
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.
139 */
140 typedef struct mbedtls_ecp_curve_info {
141 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. */
145 } mbedtls_ecp_curve_info;
146
147 /**
148 * \brief The ECP point structure, in Jacobian coordinates.
149 *
150 * \note All functions expect and return points satisfying
151 * the following condition: <code>Z == 0</code> or
152 * <code>Z == 1</code>. Other values of \p Z are
153 * used only by internal functions.
154 * The point is zero, or "at infinity", if <code>Z == 0</code>.
155 * Otherwise, \p X and \p Y are its standard (affine)
156 * coordinates.
157 */
158 typedef struct mbedtls_ecp_point {
159 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. */
162 }
163 mbedtls_ecp_point;
164
165 #if !defined(MBEDTLS_ECP_ALT)
166 /*
167 * default Mbed TLS elliptic curve arithmetic implementation
168 *
169 * (in case MBEDTLS_ECP_ALT is defined then the developer has to provide an
170 * alternative implementation for the whole module and it will replace this
171 * one.)
172 */
173
174 /**
175 * \brief The ECP group structure.
176 *
177 * We consider two types of curve equations:
178 * <ul><li>Short Weierstrass: <code>y^2 = x^3 + A x + B mod P</code>
179 * (SEC1 + RFC-4492)</li>
180 * <li>Montgomery: <code>y^2 = x^3 + A x^2 + x mod P</code> (Curve25519,
181 * Curve448)</li></ul>
182 * In both cases, the generator (\p G) for a prime-order subgroup is fixed.
183 *
184 * For Short Weierstrass, this subgroup is the whole curve, and its
185 * cardinality is denoted by \p N. Our code requires that \p N is an
186 * odd prime as mbedtls_ecp_mul() requires an odd number, and
187 * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes.
188 *
189 * The default implementation only initializes \p A without setting it to the
190 * authentic value for curves with <code>A = -3</code>(SECP256R1, etc), in which
191 * case you need to load \p A by yourself when using domain parameters directly,
192 * for example:
193 * \code
194 * mbedtls_mpi_init(&A);
195 * mbedtls_ecp_group_init(&grp);
196 * CHECK_RETURN(mbedtls_ecp_group_load(&grp, grp_id));
197 * if (mbedtls_ecp_group_a_is_minus_3(&grp)) {
198 * CHECK_RETURN(mbedtls_mpi_sub_int(&A, &grp.P, 3));
199 * } else {
200 * CHECK_RETURN(mbedtls_mpi_copy(&A, &grp.A));
201 * }
202 *
203 * do_something_with_a(&A);
204 *
205 * cleanup:
206 * mbedtls_mpi_free(&A);
207 * mbedtls_ecp_group_free(&grp);
208 * \endcode
209 *
210 * For Montgomery curves, we do not store \p A, but <code>(A + 2) / 4</code>,
211 * which is the quantity used in the formulas. Additionally, \p nbits is
212 * not the size of \p N but the required size for private keys.
213 *
214 * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm.
215 * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the
216 * range of <code>0..2^(2*pbits)-1</code>, and transforms it in-place to an integer
217 * which is congruent mod \p P to the given MPI, and is close enough to \p pbits
218 * in size, so that it may be efficiently brought in the 0..P-1 range by a few
219 * additions or subtractions. Therefore, it is only an approximative modular
220 * reduction. It must return 0 on success and non-zero on failure.
221 *
222 * \note Alternative implementations of the ECP module must obey the
223 * following constraints.
224 * * Group IDs must be distinct: if two group structures have
225 * the same ID, then they must be identical.
226 * * The fields \c id, \c P, \c A, \c B, \c G, \c N,
227 * \c pbits and \c nbits must have the same type and semantics
228 * as in the built-in implementation.
229 * They must be available for reading, but direct modification
230 * of these fields does not need to be supported.
231 * They do not need to be at the same offset in the structure.
232 */
233 typedef struct mbedtls_ecp_group {
234 mbedtls_ecp_group_id id; /*!< An internal group identifier. */
235 mbedtls_mpi P; /*!< The prime modulus of the base field. */
236 mbedtls_mpi A; /*!< For Short Weierstrass: \p A in the equation. Note that
237 \p A is not set to the authentic value in some cases.
238 Refer to detailed description of ::mbedtls_ecp_group if
239 using domain parameters in the structure.
240 For Montgomery curves: <code>(A + 2) / 4</code>. */
241 mbedtls_mpi B; /*!< For Short Weierstrass: \p B in the equation.
242 For Montgomery curves: unused. */
243 mbedtls_ecp_point G; /*!< The generator of the subgroup used. */
244 mbedtls_mpi N; /*!< The order of \p G. */
245 size_t pbits; /*!< The number of bits in \p P.*/
246 size_t nbits; /*!< For Short Weierstrass: The number of bits in \p P.
247 For Montgomery curves: the number of bits in the
248 private keys. */
249 /* End of public fields */
250
251 unsigned int MBEDTLS_PRIVATE(h); /*!< \internal 1 if the constants are static. */
252 int(*MBEDTLS_PRIVATE(modp))(mbedtls_mpi *); /*!< The function for fast pseudo-reduction
253 mod \p P (see above).*/
254 int(*MBEDTLS_PRIVATE(t_pre))(mbedtls_ecp_point *, void *); /*!< Unused. */
255 int(*MBEDTLS_PRIVATE(t_post))(mbedtls_ecp_point *, void *); /*!< Unused. */
256 void *MBEDTLS_PRIVATE(t_data); /*!< Unused. */
257 mbedtls_ecp_point *MBEDTLS_PRIVATE(T); /*!< Pre-computed points for ecp_mul_comb(). */
258 size_t MBEDTLS_PRIVATE(T_size); /*!< The number of dynamic allocated pre-computed points. */
259 }
260 mbedtls_ecp_group;
261
262 /**
263 * \name SECTION: Module settings
264 *
265 * The configuration options you can set for this module are in this section.
266 * Either change them in mbedtls_config.h, or define them using the compiler command line.
267 * \{
268 */
269
270 #if !defined(MBEDTLS_ECP_WINDOW_SIZE)
271 /*
272 * Maximum "window" size used for point multiplication.
273 * Default: a point where higher memory usage yields diminishing performance
274 * returns.
275 * Minimum value: 2. Maximum value: 7.
276 *
277 * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) )
278 * points used for point multiplication. This value is directly tied to EC
279 * peak memory usage, so decreasing it by one should roughly cut memory usage
280 * by two (if large curves are in use).
281 *
282 * Reduction in size may reduce speed, but larger curves are impacted first.
283 * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1):
284 * w-size: 6 5 4 3 2
285 * 521 145 141 135 120 97
286 * 384 214 209 198 177 146
287 * 256 320 320 303 262 226
288 * 224 475 475 453 398 342
289 * 192 640 640 633 587 476
290 */
291 #define MBEDTLS_ECP_WINDOW_SIZE 4 /**< The maximum window size used. */
292 #endif /* MBEDTLS_ECP_WINDOW_SIZE */
293
294 #if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM)
295 /*
296 * Trade code size for speed on fixed-point multiplication.
297 *
298 * This speeds up repeated multiplication of the generator (that is, the
299 * multiplication in ECDSA signatures, and half of the multiplications in
300 * ECDSA verification and ECDHE) by a factor roughly 3 to 4.
301 *
302 * For each n-bit Short Weierstrass curve that is enabled, this adds 4n bytes
303 * of code size if n < 384 and 8n otherwise.
304 *
305 * Change this value to 0 to reduce code size.
306 */
307 #define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up. */
308 #endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */
309
310 /** \} name SECTION: Module settings */
311
312 #else /* MBEDTLS_ECP_ALT */
313 #include "ecp_alt.h"
314 #endif /* MBEDTLS_ECP_ALT */
315
316 /**
317 * The maximum size of the groups, that is, of \c N and \c P.
318 */
319 #if !defined(MBEDTLS_ECP_LIGHT)
320 /* Dummy definition to help code that has optional ECP support and
321 * defines an MBEDTLS_ECP_MAX_BYTES-sized array unconditionally. */
322 #define MBEDTLS_ECP_MAX_BITS 1
323 /* Note: the curves must be listed in DECREASING size! */
324 #elif defined(MBEDTLS_ECP_DP_SECP521R1_ENABLED)
325 #define MBEDTLS_ECP_MAX_BITS 521
326 #elif defined(MBEDTLS_ECP_DP_BP512R1_ENABLED)
327 #define MBEDTLS_ECP_MAX_BITS 512
328 #elif defined(MBEDTLS_ECP_DP_CURVE448_ENABLED)
329 #define MBEDTLS_ECP_MAX_BITS 448
330 #elif defined(MBEDTLS_ECP_DP_BP384R1_ENABLED)
331 #define MBEDTLS_ECP_MAX_BITS 384
332 #elif defined(MBEDTLS_ECP_DP_SECP384R1_ENABLED)
333 #define MBEDTLS_ECP_MAX_BITS 384
334 #elif defined(MBEDTLS_ECP_DP_BP256R1_ENABLED)
335 #define MBEDTLS_ECP_MAX_BITS 256
336 #elif defined(MBEDTLS_ECP_DP_SECP256K1_ENABLED)
337 #define MBEDTLS_ECP_MAX_BITS 256
338 #elif defined(MBEDTLS_ECP_DP_SECP256R1_ENABLED)
339 #define MBEDTLS_ECP_MAX_BITS 256
340 #elif defined(MBEDTLS_ECP_DP_CURVE25519_ENABLED)
341 #define MBEDTLS_ECP_MAX_BITS 255
342 #elif defined(MBEDTLS_ECP_DP_SECP224K1_ENABLED)
343 #define MBEDTLS_ECP_MAX_BITS 225 // n is slightly above 2^224
344 #elif defined(MBEDTLS_ECP_DP_SECP224R1_ENABLED)
345 #define MBEDTLS_ECP_MAX_BITS 224
346 #elif defined(MBEDTLS_ECP_DP_SECP192K1_ENABLED)
347 #define MBEDTLS_ECP_MAX_BITS 192
348 #elif defined(MBEDTLS_ECP_DP_SECP192R1_ENABLED)
349 #define MBEDTLS_ECP_MAX_BITS 192
350 #else /* !MBEDTLS_ECP_LIGHT */
351 #error "Missing definition of MBEDTLS_ECP_MAX_BITS"
352 #endif /* !MBEDTLS_ECP_LIGHT */
353
354 #define MBEDTLS_ECP_MAX_BYTES ((MBEDTLS_ECP_MAX_BITS + 7) / 8)
355 #define MBEDTLS_ECP_MAX_PT_LEN (2 * MBEDTLS_ECP_MAX_BYTES + 1)
356
357 #if defined(MBEDTLS_ECP_RESTARTABLE)
358
359 /**
360 * \brief Internal restart context for multiplication
361 *
362 * \note Opaque struct
363 */
364 typedef struct mbedtls_ecp_restart_mul mbedtls_ecp_restart_mul_ctx;
365
366 /**
367 * \brief Internal restart context for ecp_muladd()
368 *
369 * \note Opaque struct
370 */
371 typedef struct mbedtls_ecp_restart_muladd mbedtls_ecp_restart_muladd_ctx;
372
373 /**
374 * \brief General context for resuming ECC operations
375 */
376 typedef struct {
377 unsigned MBEDTLS_PRIVATE(ops_done); /*!< current ops count */
378 unsigned MBEDTLS_PRIVATE(depth); /*!< call depth (0 = top-level) */
379 mbedtls_ecp_restart_mul_ctx *MBEDTLS_PRIVATE(rsm); /*!< ecp_mul_comb() sub-context */
380 mbedtls_ecp_restart_muladd_ctx *MBEDTLS_PRIVATE(ma); /*!< ecp_muladd() sub-context */
381 } mbedtls_ecp_restart_ctx;
382
383 /*
384 * Operation counts for restartable functions
385 */
386 #define MBEDTLS_ECP_OPS_CHK 3 /*!< basic ops count for ecp_check_pubkey() */
387 #define MBEDTLS_ECP_OPS_DBL 8 /*!< basic ops count for ecp_double_jac() */
388 #define MBEDTLS_ECP_OPS_ADD 11 /*!< basic ops count for see ecp_add_mixed() */
389 #define MBEDTLS_ECP_OPS_INV 120 /*!< empirical equivalent for mpi_mod_inv() */
390
391 /**
392 * \brief Internal; for restartable functions in other modules.
393 * Check and update basic ops budget.
394 *
395 * \param grp Group structure
396 * \param rs_ctx Restart context
397 * \param ops Number of basic ops to do
398 *
399 * \return \c 0 if doing \p ops basic ops is still allowed,
400 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS otherwise.
401 */
402 int mbedtls_ecp_check_budget(const mbedtls_ecp_group *grp,
403 mbedtls_ecp_restart_ctx *rs_ctx,
404 unsigned ops);
405
406 /* Utility macro for checking and updating ops budget */
407 #define MBEDTLS_ECP_BUDGET(ops) \
408 MBEDTLS_MPI_CHK(mbedtls_ecp_check_budget(grp, rs_ctx, \
409 (unsigned) (ops)));
410
411 #else /* MBEDTLS_ECP_RESTARTABLE */
412
413 #define MBEDTLS_ECP_BUDGET(ops) /* no-op; for compatibility */
414
415 /* We want to declare restartable versions of existing functions anyway */
416 typedef void mbedtls_ecp_restart_ctx;
417
418 #endif /* MBEDTLS_ECP_RESTARTABLE */
419
420 /**
421 * \brief The ECP key-pair structure.
422 *
423 * A generic key-pair that may be used for ECDSA and fixed ECDH, for example.
424 *
425 * \note Members are deliberately in the same order as in the
426 * ::mbedtls_ecdsa_context structure.
427 */
428 typedef struct mbedtls_ecp_keypair {
429 mbedtls_ecp_group MBEDTLS_PRIVATE(grp); /*!< Elliptic curve and base point */
430 mbedtls_mpi MBEDTLS_PRIVATE(d); /*!< our secret value */
431 mbedtls_ecp_point MBEDTLS_PRIVATE(Q); /*!< our public value */
432 }
433 mbedtls_ecp_keypair;
434
435 /**
436 * The uncompressed point format for Short Weierstrass curves
437 * (MBEDTLS_ECP_DP_SECP_XXX and MBEDTLS_ECP_DP_BP_XXX).
438 */
439 #define MBEDTLS_ECP_PF_UNCOMPRESSED 0
440 /**
441 * The compressed point format for Short Weierstrass curves
442 * (MBEDTLS_ECP_DP_SECP_XXX and MBEDTLS_ECP_DP_BP_XXX).
443 *
444 * \warning While this format is supported for all concerned curves for
445 * writing, when it comes to parsing, it is not supported for all
446 * curves. Specifically, parsing compressed points on
447 * MBEDTLS_ECP_DP_SECP224R1 and MBEDTLS_ECP_DP_SECP224K1 is not
448 * supported.
449 */
450 #define MBEDTLS_ECP_PF_COMPRESSED 1
451
452 /*
453 * Some other constants from RFC 4492
454 */
455 #define MBEDTLS_ECP_TLS_NAMED_CURVE 3 /**< The named_curve of ECCurveType. */
456
457 #if defined(MBEDTLS_ECP_RESTARTABLE)
458 /**
459 * \brief Set the maximum number of basic operations done in a row.
460 *
461 * If more operations are needed to complete a computation,
462 * #MBEDTLS_ERR_ECP_IN_PROGRESS will be returned by the
463 * function performing the computation. It is then the
464 * caller's responsibility to either call again with the same
465 * parameters until it returns 0 or an error code; or to free
466 * the restart context if the operation is to be aborted.
467 *
468 * It is strictly required that all input parameters and the
469 * restart context be the same on successive calls for the
470 * same operation, but output parameters need not be the
471 * same; they must not be used until the function finally
472 * returns 0.
473 *
474 * This only applies to functions whose documentation
475 * mentions they may return #MBEDTLS_ERR_ECP_IN_PROGRESS (or
476 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS for functions in the
477 * SSL module). For functions that accept a "restart context"
478 * argument, passing NULL disables restart and makes the
479 * function equivalent to the function with the same name
480 * with \c _restartable removed. For functions in the ECDH
481 * module, restart is disabled unless the function accepts
482 * an "ECDH context" argument and
483 * mbedtls_ecdh_enable_restart() was previously called on
484 * that context. For function in the SSL module, restart is
485 * only enabled for specific sides and key exchanges
486 * (currently only for clients and ECDHE-ECDSA).
487 *
488 * \warning Using the PSA interruptible interfaces with keys in local
489 * storage and no accelerator driver will also call this
490 * function to set the values specified via those interfaces,
491 * overwriting values previously set. Care should be taken if
492 * mixing these two interfaces.
493 *
494 * \param max_ops Maximum number of basic operations done in a row.
495 * Default: 0 (unlimited).
496 * Lower (non-zero) values mean ECC functions will block for
497 * a lesser maximum amount of time.
498 *
499 * \note A "basic operation" is defined as a rough equivalent of a
500 * multiplication in GF(p) for the NIST P-256 curve.
501 * As an indication, with default settings, a scalar
502 * multiplication (full run of \c mbedtls_ecp_mul()) is:
503 * - about 3300 basic operations for P-256
504 * - about 9400 basic operations for P-384
505 *
506 * \note Very low values are not always respected: sometimes
507 * functions need to block for a minimum number of
508 * operations, and will do so even if max_ops is set to a
509 * lower value. That minimum depends on the curve size, and
510 * can be made lower by decreasing the value of
511 * \c MBEDTLS_ECP_WINDOW_SIZE. As an indication, here is the
512 * lowest effective value for various curves and values of
513 * that parameter (w for short):
514 * w=6 w=5 w=4 w=3 w=2
515 * P-256 208 208 160 136 124
516 * P-384 682 416 320 272 248
517 * P-521 1364 832 640 544 496
518 *
519 * \note This setting is currently ignored by Curve25519.
520 */
521 void mbedtls_ecp_set_max_ops(unsigned max_ops);
522
523 /**
524 * \brief Check if restart is enabled (max_ops != 0)
525 *
526 * \return \c 0 if \c max_ops == 0 (restart disabled)
527 * \return \c 1 otherwise (restart enabled)
528 */
529 int mbedtls_ecp_restart_is_enabled(void);
530 #endif /* MBEDTLS_ECP_RESTARTABLE */
531
532 /*
533 * Get the type of a curve
534 */
535 mbedtls_ecp_curve_type mbedtls_ecp_get_type(const mbedtls_ecp_group *grp);
536
537 /**
538 * \brief This function retrieves the information defined in
539 * mbedtls_ecp_curve_info() for all supported curves.
540 *
541 * \note This function returns information about all curves
542 * supported by the library. Some curves may not be
543 * supported for all algorithms. Call mbedtls_ecdh_can_do()
544 * or mbedtls_ecdsa_can_do() to check if a curve is
545 * supported for ECDH or ECDSA.
546 *
547 * \return A statically allocated array. The last entry is 0.
548 */
549 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list(void);
550
551 /**
552 * \brief This function retrieves the list of internal group
553 * identifiers of all supported curves in the order of
554 * preference.
555 *
556 * \note This function returns information about all curves
557 * supported by the library. Some curves may not be
558 * supported for all algorithms. Call mbedtls_ecdh_can_do()
559 * or mbedtls_ecdsa_can_do() to check if a curve is
560 * supported for ECDH or ECDSA.
561 *
562 * \return A statically allocated array,
563 * terminated with MBEDTLS_ECP_DP_NONE.
564 */
565 const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list(void);
566
567 /**
568 * \brief This function retrieves curve information from an internal
569 * group identifier.
570 *
571 * \param grp_id An \c MBEDTLS_ECP_DP_XXX value.
572 *
573 * \return The associated curve information on success.
574 * \return NULL on failure.
575 */
576 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id(mbedtls_ecp_group_id grp_id);
577
578 /**
579 * \brief This function retrieves curve information from a TLS
580 * NamedCurve value.
581 *
582 * \param tls_id An \c MBEDTLS_ECP_DP_XXX value.
583 *
584 * \return The associated curve information on success.
585 * \return NULL on failure.
586 */
587 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id(uint16_t tls_id);
588
589 /**
590 * \brief This function retrieves curve information from a
591 * human-readable name.
592 *
593 * \param name The human-readable name.
594 *
595 * \return The associated curve information on success.
596 * \return NULL on failure.
597 */
598 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name(const char *name);
599
600 /**
601 * \brief This function initializes a point as zero.
602 *
603 * \param pt The point to initialize.
604 */
605 void mbedtls_ecp_point_init(mbedtls_ecp_point *pt);
606
607 /**
608 * \brief This function initializes an ECP group context
609 * without loading any domain parameters.
610 *
611 * \note After this function is called, domain parameters
612 * for various ECP groups can be loaded through the
613 * mbedtls_ecp_group_load() or mbedtls_ecp_tls_read_group()
614 * functions.
615 */
616 void mbedtls_ecp_group_init(mbedtls_ecp_group *grp);
617
618 /**
619 * \brief This function initializes a key pair as an invalid one.
620 *
621 * \param key The key pair to initialize.
622 */
623 void mbedtls_ecp_keypair_init(mbedtls_ecp_keypair *key);
624
625 /**
626 * \brief This function frees the components of a point.
627 *
628 * \param pt The point to free.
629 */
630 void mbedtls_ecp_point_free(mbedtls_ecp_point *pt);
631
632 /**
633 * \brief This function frees the components of an ECP group.
634 *
635 * \param grp The group to free. This may be \c NULL, in which
636 * case this function returns immediately. If it is not
637 * \c NULL, it must point to an initialized ECP group.
638 */
639 void mbedtls_ecp_group_free(mbedtls_ecp_group *grp);
640
641 /**
642 * \brief This function frees the components of a key pair.
643 *
644 * \param key The key pair to free. This may be \c NULL, in which
645 * case this function returns immediately. If it is not
646 * \c NULL, it must point to an initialized ECP key pair.
647 */
648 void mbedtls_ecp_keypair_free(mbedtls_ecp_keypair *key);
649
650 #if defined(MBEDTLS_ECP_RESTARTABLE)
651 /**
652 * \brief Initialize a restart context.
653 *
654 * \param ctx The restart context to initialize. This must
655 * not be \c NULL.
656 */
657 void mbedtls_ecp_restart_init(mbedtls_ecp_restart_ctx *ctx);
658
659 /**
660 * \brief Free the components of a restart context.
661 *
662 * \param ctx The restart context to free. This may be \c NULL, in which
663 * case this function returns immediately. If it is not
664 * \c NULL, it must point to an initialized restart context.
665 */
666 void mbedtls_ecp_restart_free(mbedtls_ecp_restart_ctx *ctx);
667 #endif /* MBEDTLS_ECP_RESTARTABLE */
668
669 /**
670 * \brief This function copies the contents of point \p Q into
671 * point \p P.
672 *
673 * \param P The destination point. This must be initialized.
674 * \param Q The source point. This must be initialized.
675 *
676 * \return \c 0 on success.
677 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
678 * \return Another negative error code for other kinds of failure.
679 */
680 int mbedtls_ecp_copy(mbedtls_ecp_point *P, const mbedtls_ecp_point *Q);
681
682 /**
683 * \brief This function copies the contents of group \p src into
684 * group \p dst.
685 *
686 * \param dst The destination group. This must be initialized.
687 * \param src The source group. This must be initialized.
688 *
689 * \return \c 0 on success.
690 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
691 * \return Another negative error code on other kinds of failure.
692 */
693 int mbedtls_ecp_group_copy(mbedtls_ecp_group *dst,
694 const mbedtls_ecp_group *src);
695
696 /**
697 * \brief This function sets a point to the point at infinity.
698 *
699 * \param pt The point to set. This must be initialized.
700 *
701 * \return \c 0 on success.
702 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
703 * \return Another negative error code on other kinds of failure.
704 */
705 int mbedtls_ecp_set_zero(mbedtls_ecp_point *pt);
706
707 /**
708 * \brief This function checks if a point is the point at infinity.
709 *
710 * \param pt The point to test. This must be initialized.
711 *
712 * \return \c 1 if the point is zero.
713 * \return \c 0 if the point is non-zero.
714 * \return A negative error code on failure.
715 */
716 int mbedtls_ecp_is_zero(mbedtls_ecp_point *pt);
717
718 /**
719 * \brief This function compares two points.
720 *
721 * \note This assumes that the points are normalized. Otherwise,
722 * they may compare as "not equal" even if they are.
723 *
724 * \param P The first point to compare. This must be initialized.
725 * \param Q The second point to compare. This must be initialized.
726 *
727 * \return \c 0 if the points are equal.
728 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal.
729 */
730 int mbedtls_ecp_point_cmp(const mbedtls_ecp_point *P,
731 const mbedtls_ecp_point *Q);
732
733 /**
734 * \brief This function imports a non-zero point from two ASCII
735 * strings.
736 *
737 * \param P The destination point. This must be initialized.
738 * \param radix The numeric base of the input.
739 * \param x The first affine coordinate, as a null-terminated string.
740 * \param y The second affine coordinate, as a null-terminated string.
741 *
742 * \return \c 0 on success.
743 * \return An \c MBEDTLS_ERR_MPI_XXX error code on failure.
744 */
745 int mbedtls_ecp_point_read_string(mbedtls_ecp_point *P, int radix,
746 const char *x, const char *y);
747
748 /**
749 * \brief This function exports a point into unsigned binary data.
750 *
751 * \param grp The group to which the point should belong.
752 * This must be initialized and have group parameters
753 * set, for example through mbedtls_ecp_group_load().
754 * \param P The point to export. This must be initialized.
755 * \param format The point format. This must be either
756 * #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
757 * (For groups without these formats, this parameter is
758 * ignored. But it still has to be either of the above
759 * values.)
760 * \param olen The address at which to store the length of
761 * the output in Bytes. This must not be \c NULL.
762 * \param buf The output buffer. This must be a writable buffer
763 * of length \p buflen Bytes.
764 * \param buflen The length of the output buffer \p buf in Bytes.
765 *
766 * \return \c 0 on success.
767 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer
768 * is too small to hold the point.
769 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
770 * or the export for the given group is not implemented.
771 * \return Another negative error code on other kinds of failure.
772 */
773 int mbedtls_ecp_point_write_binary(const mbedtls_ecp_group *grp,
774 const mbedtls_ecp_point *P,
775 int format, size_t *olen,
776 unsigned char *buf, size_t buflen);
777
778 /**
779 * \brief This function imports a point from unsigned binary data.
780 *
781 * \note This function does not check that the point actually
782 * belongs to the given group, see mbedtls_ecp_check_pubkey()
783 * for that.
784 *
785 * \note For compressed points, see #MBEDTLS_ECP_PF_COMPRESSED for
786 * limitations.
787 *
788 * \param grp The group to which the point should belong.
789 * This must be initialized and have group parameters
790 * set, for example through mbedtls_ecp_group_load().
791 * \param P The destination context to import the point to.
792 * This must be initialized.
793 * \param buf The input buffer. This must be a readable buffer
794 * of length \p ilen Bytes.
795 * \param ilen The length of the input buffer \p buf in Bytes.
796 *
797 * \return \c 0 on success.
798 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
799 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
800 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the import for the
801 * given group is not implemented.
802 */
803 int mbedtls_ecp_point_read_binary(const mbedtls_ecp_group *grp,
804 mbedtls_ecp_point *P,
805 const unsigned char *buf, size_t ilen);
806
807 /**
808 * \brief This function imports a point from a TLS ECPoint record.
809 *
810 * \note On function return, \p *buf is updated to point immediately
811 * after the ECPoint record.
812 *
813 * \param grp The ECP group to use.
814 * This must be initialized and have group parameters
815 * set, for example through mbedtls_ecp_group_load().
816 * \param pt The destination point.
817 * \param buf The address of the pointer to the start of the input buffer.
818 * \param len The length of the buffer.
819 *
820 * \return \c 0 on success.
821 * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization
822 * failure.
823 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
824 */
825 int mbedtls_ecp_tls_read_point(const mbedtls_ecp_group *grp,
826 mbedtls_ecp_point *pt,
827 const unsigned char **buf, size_t len);
828
829 /**
830 * \brief This function exports a point as a TLS ECPoint record
831 * defined in RFC 4492, Section 5.4.
832 *
833 * \param grp The ECP group to use.
834 * This must be initialized and have group parameters
835 * set, for example through mbedtls_ecp_group_load().
836 * \param pt The point to be exported. This must be initialized.
837 * \param format The point format to use. This must be either
838 * #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
839 * \param olen The address at which to store the length in Bytes
840 * of the data written.
841 * \param buf The target buffer. This must be a writable buffer of
842 * length \p blen Bytes.
843 * \param blen The length of the target buffer \p buf in Bytes.
844 *
845 * \return \c 0 on success.
846 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
847 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the target buffer
848 * is too small to hold the exported point.
849 * \return Another negative error code on other kinds of failure.
850 */
851 int mbedtls_ecp_tls_write_point(const mbedtls_ecp_group *grp,
852 const mbedtls_ecp_point *pt,
853 int format, size_t *olen,
854 unsigned char *buf, size_t blen);
855
856 /**
857 * \brief This function sets up an ECP group context
858 * from a standardized set of domain parameters.
859 *
860 * \note The index should be a value of the NamedCurve enum,
861 * as defined in <em>RFC-4492: Elliptic Curve Cryptography
862 * (ECC) Cipher Suites for Transport Layer Security (TLS)</em>,
863 * usually in the form of an \c MBEDTLS_ECP_DP_XXX macro.
864 *
865 * \param grp The group context to setup. This must be initialized.
866 * \param id The identifier of the domain parameter set to load.
867 *
868 * \return \c 0 on success.
869 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p id doesn't
870 * correspond to a known group.
871 * \return Another negative error code on other kinds of failure.
872 */
873 int mbedtls_ecp_group_load(mbedtls_ecp_group *grp, mbedtls_ecp_group_id id);
874
875 /**
876 * \brief This function sets up an ECP group context from a TLS
877 * ECParameters record as defined in RFC 4492, Section 5.4.
878 *
879 * \note The read pointer \p buf is updated to point right after
880 * the ECParameters record on exit.
881 *
882 * \param grp The group context to setup. This must be initialized.
883 * \param buf The address of the pointer to the start of the input buffer.
884 * \param len The length of the input buffer \c *buf in Bytes.
885 *
886 * \return \c 0 on success.
887 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
888 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
889 * recognized.
890 * \return Another negative error code on other kinds of failure.
891 */
892 int mbedtls_ecp_tls_read_group(mbedtls_ecp_group *grp,
893 const unsigned char **buf, size_t len);
894
895 /**
896 * \brief This function extracts an elliptic curve group ID from a
897 * TLS ECParameters record as defined in RFC 4492, Section 5.4.
898 *
899 * \note The read pointer \p buf is updated to point right after
900 * the ECParameters record on exit.
901 *
902 * \param grp The address at which to store the group id.
903 * This must not be \c NULL.
904 * \param buf The address of the pointer to the start of the input buffer.
905 * \param len The length of the input buffer \c *buf in Bytes.
906 *
907 * \return \c 0 on success.
908 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
909 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not
910 * recognized.
911 * \return Another negative error code on other kinds of failure.
912 */
913 int mbedtls_ecp_tls_read_group_id(mbedtls_ecp_group_id *grp,
914 const unsigned char **buf,
915 size_t len);
916 /**
917 * \brief This function exports an elliptic curve as a TLS
918 * ECParameters record as defined in RFC 4492, Section 5.4.
919 *
920 * \param grp The ECP group to be exported.
921 * This must be initialized and have group parameters
922 * set, for example through mbedtls_ecp_group_load().
923 * \param olen The address at which to store the number of Bytes written.
924 * This must not be \c NULL.
925 * \param buf The buffer to write to. This must be a writable buffer
926 * of length \p blen Bytes.
927 * \param blen The length of the output buffer \p buf in Bytes.
928 *
929 * \return \c 0 on success.
930 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output
931 * buffer is too small to hold the exported group.
932 * \return Another negative error code on other kinds of failure.
933 */
934 int mbedtls_ecp_tls_write_group(const mbedtls_ecp_group *grp,
935 size_t *olen,
936 unsigned char *buf, size_t blen);
937
938 /**
939 * \brief This function performs a scalar multiplication of a point
940 * by an integer: \p R = \p m * \p P.
941 *
942 * It is not thread-safe to use same group in multiple threads.
943 *
944 * \note To prevent timing attacks, this function
945 * executes the exact same sequence of base-field
946 * operations for any valid \p m. It avoids any if-branch or
947 * array index depending on the value of \p m. It also uses
948 * \p f_rng to randomize some intermediate results.
949 *
950 * \param grp The ECP group to use.
951 * This must be initialized and have group parameters
952 * set, for example through mbedtls_ecp_group_load().
953 * \param R The point in which to store the result of the calculation.
954 * This must be initialized.
955 * \param m The integer by which to multiply. This must be initialized.
956 * \param P The point to multiply. This must be initialized.
957 * \param f_rng The RNG function. This must not be \c NULL.
958 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c
959 * NULL if \p f_rng doesn't need a context.
960 *
961 * \return \c 0 on success.
962 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
963 * key, or \p P is not a valid public key.
964 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
965 * \return Another negative error code on other kinds of failure.
966 */
967 int mbedtls_ecp_mul(mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
968 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
969 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
970
971 /**
972 * \brief This function performs multiplication of a point by
973 * an integer: \p R = \p m * \p P in a restartable way.
974 *
975 * \see mbedtls_ecp_mul()
976 *
977 * \note This function does the same as \c mbedtls_ecp_mul(), but
978 * it can return early and restart according to the limit set
979 * with \c mbedtls_ecp_set_max_ops() to reduce blocking.
980 *
981 * \param grp The ECP group to use.
982 * This must be initialized and have group parameters
983 * set, for example through mbedtls_ecp_group_load().
984 * \param R The point in which to store the result of the calculation.
985 * This must be initialized.
986 * \param m The integer by which to multiply. This must be initialized.
987 * \param P The point to multiply. This must be initialized.
988 * \param f_rng The RNG function. This must not be \c NULL.
989 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c
990 * NULL if \p f_rng doesn't need a context.
991 * \param rs_ctx The restart context (NULL disables restart).
992 *
993 * \return \c 0 on success.
994 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
995 * key, or \p P is not a valid public key.
996 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
997 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
998 * operations was reached: see \c mbedtls_ecp_set_max_ops().
999 * \return Another negative error code on other kinds of failure.
1000 */
1001 int mbedtls_ecp_mul_restartable(mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
1002 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
1003 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
1004 mbedtls_ecp_restart_ctx *rs_ctx);
1005
1006 #if defined(MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED)
1007 /**
1008 * \brief This function checks if domain parameter A of the curve is
1009 * \c -3.
1010 *
1011 * \note This function is only defined for short Weierstrass curves.
1012 * It may not be included in builds without any short
1013 * Weierstrass curve.
1014 *
1015 * \param grp The ECP group to use.
1016 * This must be initialized and have group parameters
1017 * set, for example through mbedtls_ecp_group_load().
1018 *
1019 * \return \c 1 if <code>A = -3</code>.
1020 * \return \c 0 Otherwise.
1021 */
mbedtls_ecp_group_a_is_minus_3(const mbedtls_ecp_group * grp)1022 static inline int mbedtls_ecp_group_a_is_minus_3(const mbedtls_ecp_group *grp)
1023 {
1024 return grp->A.MBEDTLS_PRIVATE(p) == NULL;
1025 }
1026
1027 /**
1028 * \brief This function performs multiplication and addition of two
1029 * points by integers: \p R = \p m * \p P + \p n * \p Q
1030 *
1031 * It is not thread-safe to use same group in multiple threads.
1032 *
1033 * \note In contrast to mbedtls_ecp_mul(), this function does not
1034 * guarantee a constant execution flow and timing.
1035 *
1036 * \note This function is only defined for short Weierstrass curves.
1037 * It may not be included in builds without any short
1038 * Weierstrass curve.
1039 *
1040 * \param grp The ECP group to use.
1041 * This must be initialized and have group parameters
1042 * set, for example through mbedtls_ecp_group_load().
1043 * \param R The point in which to store the result of the calculation.
1044 * This must be initialized.
1045 * \param m The integer by which to multiply \p P.
1046 * This must be initialized.
1047 * \param P The point to multiply by \p m. This must be initialized.
1048 * \param n The integer by which to multiply \p Q.
1049 * This must be initialized.
1050 * \param Q The point to be multiplied by \p n.
1051 * This must be initialized.
1052 *
1053 * \return \c 0 on success.
1054 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
1055 * valid private keys, or \p P or \p Q are not valid public
1056 * keys.
1057 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
1058 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p grp does not
1059 * designate a short Weierstrass curve.
1060 * \return Another negative error code on other kinds of failure.
1061 */
1062 int mbedtls_ecp_muladd(mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
1063 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
1064 const mbedtls_mpi *n, const mbedtls_ecp_point *Q);
1065
1066 /**
1067 * \brief This function performs multiplication and addition of two
1068 * points by integers: \p R = \p m * \p P + \p n * \p Q in a
1069 * restartable way.
1070 *
1071 * \see \c mbedtls_ecp_muladd()
1072 *
1073 * \note This function works the same as \c mbedtls_ecp_muladd(),
1074 * but it can return early and restart according to the limit
1075 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
1076 *
1077 * \note This function is only defined for short Weierstrass curves.
1078 * It may not be included in builds without any short
1079 * Weierstrass curve.
1080 *
1081 * \param grp The ECP group to use.
1082 * This must be initialized and have group parameters
1083 * set, for example through mbedtls_ecp_group_load().
1084 * \param R The point in which to store the result of the calculation.
1085 * This must be initialized.
1086 * \param m The integer by which to multiply \p P.
1087 * This must be initialized.
1088 * \param P The point to multiply by \p m. This must be initialized.
1089 * \param n The integer by which to multiply \p Q.
1090 * This must be initialized.
1091 * \param Q The point to be multiplied by \p n.
1092 * This must be initialized.
1093 * \param rs_ctx The restart context (NULL disables restart).
1094 *
1095 * \return \c 0 on success.
1096 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
1097 * valid private keys, or \p P or \p Q are not valid public
1098 * keys.
1099 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
1100 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if \p grp does not
1101 * designate a short Weierstrass curve.
1102 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
1103 * operations was reached: see \c mbedtls_ecp_set_max_ops().
1104 * \return Another negative error code on other kinds of failure.
1105 */
1106 int mbedtls_ecp_muladd_restartable(
1107 mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
1108 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
1109 const mbedtls_mpi *n, const mbedtls_ecp_point *Q,
1110 mbedtls_ecp_restart_ctx *rs_ctx);
1111 #endif /* MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED */
1112
1113 /**
1114 * \brief This function checks that a point is a valid public key
1115 * on this curve.
1116 *
1117 * It only checks that the point is non-zero, has
1118 * valid coordinates and lies on the curve. It does not verify
1119 * that it is indeed a multiple of \c G. This additional
1120 * check is computationally more expensive, is not required
1121 * by standards, and should not be necessary if the group
1122 * used has a small cofactor. In particular, it is useless for
1123 * the NIST groups which all have a cofactor of 1.
1124 *
1125 * \note This function uses bare components rather than an
1126 * ::mbedtls_ecp_keypair structure, to ease use with other
1127 * structures, such as ::mbedtls_ecdh_context or
1128 * ::mbedtls_ecdsa_context.
1129 *
1130 * \param grp The ECP group the point should belong to.
1131 * This must be initialized and have group parameters
1132 * set, for example through mbedtls_ecp_group_load().
1133 * \param pt The point to check. This must be initialized.
1134 *
1135 * \return \c 0 if the point is a valid public key.
1136 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not
1137 * a valid public key for the given curve.
1138 * \return Another negative error code on other kinds of failure.
1139 */
1140 int mbedtls_ecp_check_pubkey(const mbedtls_ecp_group *grp,
1141 const mbedtls_ecp_point *pt);
1142
1143 /**
1144 * \brief This function checks that an \c mbedtls_mpi is a
1145 * valid private key for this curve.
1146 *
1147 * \note This function uses bare components rather than an
1148 * ::mbedtls_ecp_keypair structure to ease use with other
1149 * structures, such as ::mbedtls_ecdh_context or
1150 * ::mbedtls_ecdsa_context.
1151 *
1152 * \param grp The ECP group the private key should belong to.
1153 * This must be initialized and have group parameters
1154 * set, for example through mbedtls_ecp_group_load().
1155 * \param d The integer to check. This must be initialized.
1156 *
1157 * \return \c 0 if the point is a valid private key.
1158 * \return #MBEDTLS_ERR_ECP_INVALID_KEY if the point is not a valid
1159 * private key for the given curve.
1160 * \return Another negative error code on other kinds of failure.
1161 */
1162 int mbedtls_ecp_check_privkey(const mbedtls_ecp_group *grp,
1163 const mbedtls_mpi *d);
1164
1165 /**
1166 * \brief This function generates a private key.
1167 *
1168 * \param grp The ECP group to generate a private key for.
1169 * This must be initialized and have group parameters
1170 * set, for example through mbedtls_ecp_group_load().
1171 * \param d The destination MPI (secret part). This must be initialized.
1172 * \param f_rng The RNG function. This must not be \c NULL.
1173 * \param p_rng The RNG parameter to be passed to \p f_rng. This may be
1174 * \c NULL if \p f_rng doesn't need a context argument.
1175 *
1176 * \return \c 0 on success.
1177 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
1178 * on failure.
1179 */
1180 int mbedtls_ecp_gen_privkey(const mbedtls_ecp_group *grp,
1181 mbedtls_mpi *d,
1182 int (*f_rng)(void *, unsigned char *, size_t),
1183 void *p_rng);
1184
1185 /**
1186 * \brief This function generates a keypair with a configurable base
1187 * point.
1188 *
1189 * \note This function uses bare components rather than an
1190 * ::mbedtls_ecp_keypair structure to ease use with other
1191 * structures, such as ::mbedtls_ecdh_context or
1192 * ::mbedtls_ecdsa_context.
1193 *
1194 * \param grp The ECP group to generate a key pair for.
1195 * This must be initialized and have group parameters
1196 * set, for example through mbedtls_ecp_group_load().
1197 * \param G The base point to use. This must be initialized
1198 * and belong to \p grp. It replaces the default base
1199 * point \c grp->G used by mbedtls_ecp_gen_keypair().
1200 * \param d The destination MPI (secret part).
1201 * This must be initialized.
1202 * \param Q The destination point (public part).
1203 * This must be initialized.
1204 * \param f_rng The RNG function. This must not be \c NULL.
1205 * \param p_rng The RNG context to be passed to \p f_rng. This may
1206 * be \c NULL if \p f_rng doesn't need a context argument.
1207 *
1208 * \return \c 0 on success.
1209 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
1210 * on failure.
1211 */
1212 int mbedtls_ecp_gen_keypair_base(mbedtls_ecp_group *grp,
1213 const mbedtls_ecp_point *G,
1214 mbedtls_mpi *d, mbedtls_ecp_point *Q,
1215 int (*f_rng)(void *, unsigned char *, size_t),
1216 void *p_rng);
1217
1218 /**
1219 * \brief This function generates an ECP keypair.
1220 *
1221 * \note This function uses bare components rather than an
1222 * ::mbedtls_ecp_keypair structure to ease use with other
1223 * structures, such as ::mbedtls_ecdh_context or
1224 * ::mbedtls_ecdsa_context.
1225 *
1226 * \param grp The ECP group to generate a key pair for.
1227 * This must be initialized and have group parameters
1228 * set, for example through mbedtls_ecp_group_load().
1229 * \param d The destination MPI (secret part).
1230 * This must be initialized.
1231 * \param Q The destination point (public part).
1232 * This must be initialized.
1233 * \param f_rng The RNG function. This must not be \c NULL.
1234 * \param p_rng The RNG context to be passed to \p f_rng. This may
1235 * be \c NULL if \p f_rng doesn't need a context argument.
1236 *
1237 * \return \c 0 on success.
1238 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
1239 * on failure.
1240 */
1241 int mbedtls_ecp_gen_keypair(mbedtls_ecp_group *grp, mbedtls_mpi *d,
1242 mbedtls_ecp_point *Q,
1243 int (*f_rng)(void *, unsigned char *, size_t),
1244 void *p_rng);
1245
1246 /**
1247 * \brief This function generates an ECP key.
1248 *
1249 * \param grp_id The ECP group identifier.
1250 * \param key The destination key. This must be initialized.
1251 * \param f_rng The RNG function to use. This must not be \c NULL.
1252 * \param p_rng The RNG context to be passed to \p f_rng. This may
1253 * be \c NULL if \p f_rng doesn't need a context argument.
1254 *
1255 * \return \c 0 on success.
1256 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code
1257 * on failure.
1258 */
1259 int mbedtls_ecp_gen_key(mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
1260 int (*f_rng)(void *, unsigned char *, size_t),
1261 void *p_rng);
1262
1263 /** \brief Set the public key in a key pair object.
1264 *
1265 * \note This function does not check that the point actually
1266 * belongs to the given group. Call mbedtls_ecp_check_pubkey()
1267 * on \p Q before calling this function to check that.
1268 *
1269 * \note This function does not check that the public key matches
1270 * the private key that is already in \p key, if any.
1271 * To check the consistency of the resulting key pair object,
1272 * call mbedtls_ecp_check_pub_priv() after setting both
1273 * the public key and the private key.
1274 *
1275 * \param grp_id The ECP group identifier.
1276 * \param key The key pair object. It must be initialized.
1277 * If its group has already been set, it must match \p grp_id.
1278 * If its group has not been set, it will be set to \p grp_id.
1279 * If the public key has already been set, it is overwritten.
1280 * \param Q The public key to copy. This must be a point on the
1281 * curve indicated by \p grp_id.
1282 *
1283 * \return \c 0 on success.
1284 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if \p key does not
1285 * match \p grp_id.
1286 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the operation for
1287 * the group is not implemented.
1288 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
1289 * \return Another negative error code on other kinds of failure.
1290 */
1291 int mbedtls_ecp_set_public_key(mbedtls_ecp_group_id grp_id,
1292 mbedtls_ecp_keypair *key,
1293 const mbedtls_ecp_point *Q);
1294
1295 /**
1296 * \brief This function reads an elliptic curve private key.
1297 *
1298 * \note This function does not set the public key in the
1299 * key pair object. Without a public key, the key pair object
1300 * cannot be used with operations that require the public key.
1301 * Call mbedtls_ecp_keypair_calc_public() to set the public
1302 * key from the private key. Alternatively, you can call
1303 * mbedtls_ecp_set_public_key() to set the public key part,
1304 * and then optionally mbedtls_ecp_check_pub_priv() to check
1305 * that the private and public parts are consistent.
1306 *
1307 * \note If a public key has already been set in the key pair
1308 * object, this function does not check that it is consistent
1309 * with the private key. Call mbedtls_ecp_check_pub_priv()
1310 * after setting both the public key and the private key
1311 * to make that check.
1312 *
1313 * \param grp_id The ECP group identifier.
1314 * \param key The destination key.
1315 * \param buf The buffer containing the binary representation of the
1316 * key. (Big endian integer for Weierstrass curves, byte
1317 * string for Montgomery curves.)
1318 * \param buflen The length of the buffer in bytes.
1319 *
1320 * \return \c 0 on success.
1321 * \return #MBEDTLS_ERR_ECP_INVALID_KEY error if the key is
1322 * invalid.
1323 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
1324 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the operation for
1325 * the group is not implemented.
1326 * \return Another negative error code on different kinds of failure.
1327 */
1328 int mbedtls_ecp_read_key(mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
1329 const unsigned char *buf, size_t buflen);
1330
1331 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
1332 /**
1333 * \brief This function exports an elliptic curve private key.
1334 *
1335 * \deprecated Note that although this function accepts an output
1336 * buffer that is smaller or larger than the key, most key
1337 * import interfaces require the output to have exactly
1338 * key's nominal length. It is generally simplest to
1339 * pass the key's nominal length as \c buflen, after
1340 * checking that the output buffer is large enough.
1341 * See the description of the \p buflen parameter for
1342 * how to calculate the nominal length.
1343 * To avoid this difficulty, use mbedtls_ecp_write_key_ext()
1344 * instead.
1345 * mbedtls_ecp_write_key() is deprecated and will be
1346 * removed in a future version of the library.
1347 *
1348 * \note If the private key was not set in \p key,
1349 * the output is unspecified. Future versions
1350 * may return an error in that case.
1351 *
1352 * \param key The private key.
1353 * \param buf The output buffer for containing the binary representation
1354 * of the key.
1355 * For Weierstrass curves, this is the big-endian
1356 * representation, padded with null bytes at the beginning
1357 * to reach \p buflen bytes.
1358 * For Montgomery curves, this is the standard byte string
1359 * representation (which is little-endian), padded with
1360 * null bytes at the end to reach \p buflen bytes.
1361 * \param buflen The total length of the buffer in bytes.
1362 * The length of the output is
1363 * (`grp->nbits` + 7) / 8 bytes
1364 * where `grp->nbits` is the private key size in bits.
1365 * For Weierstrass keys, if the output buffer is smaller,
1366 * leading zeros are trimmed to fit if possible. For
1367 * Montgomery keys, the output buffer must always be large
1368 * enough for the nominal length.
1369 *
1370 * \return \c 0 on success.
1371 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL or
1372 * #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if the \p key
1373 * representation is larger than the available space in \p buf.
1374 * \return Another negative error code on different kinds of failure.
1375 */
1376 int MBEDTLS_DEPRECATED mbedtls_ecp_write_key(mbedtls_ecp_keypair *key,
1377 unsigned char *buf, size_t buflen);
1378 #endif /* MBEDTLS_DEPRECATED_REMOVED */
1379
1380 /**
1381 * \brief This function exports an elliptic curve private key.
1382 *
1383 * \param key The private key.
1384 * \param olen On success, the length of the private key.
1385 * This is always (`grp->nbits` + 7) / 8 bytes
1386 * where `grp->nbits` is the private key size in bits.
1387 * \param buf The output buffer for containing the binary representation
1388 * of the key.
1389 * \param buflen The total length of the buffer in bytes.
1390 * #MBEDTLS_ECP_MAX_BYTES is always sufficient.
1391 *
1392 * \return \c 0 on success.
1393 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the \p key
1394 * representation is larger than the available space in \p buf.
1395 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if no private key is
1396 * set in \p key.
1397 * \return Another negative error code on different kinds of failure.
1398 */
1399 int mbedtls_ecp_write_key_ext(const mbedtls_ecp_keypair *key,
1400 size_t *olen, unsigned char *buf, size_t buflen);
1401
1402 /**
1403 * \brief This function exports an elliptic curve public key.
1404 *
1405 * \note If the public key was not set in \p key,
1406 * the output is unspecified. Future versions
1407 * may return an error in that case.
1408 *
1409 * \param key The public key.
1410 * \param format The point format. This must be either
1411 * #MBEDTLS_ECP_PF_COMPRESSED or #MBEDTLS_ECP_PF_UNCOMPRESSED.
1412 * (For groups without these formats, this parameter is
1413 * ignored. But it still has to be either of the above
1414 * values.)
1415 * \param olen The address at which to store the length of
1416 * the output in Bytes. This must not be \c NULL.
1417 * \param buf The output buffer. This must be a writable buffer
1418 * of length \p buflen Bytes.
1419 * \param buflen The length of the output buffer \p buf in Bytes.
1420 *
1421 * \return \c 0 on success.
1422 * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer
1423 * is too small to hold the point.
1424 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format
1425 * or the export for the given group is not implemented.
1426 * \return Another negative error code on other kinds of failure.
1427 */
1428 int mbedtls_ecp_write_public_key(const mbedtls_ecp_keypair *key,
1429 int format, size_t *olen,
1430 unsigned char *buf, size_t buflen);
1431
1432 /**
1433 * \brief This function checks that the keypair objects
1434 * \p pub and \p prv have the same group and the
1435 * same public point, and that the private key in
1436 * \p prv is consistent with the public key.
1437 *
1438 * \param pub The keypair structure holding the public key. This
1439 * must be initialized. If it contains a private key, that
1440 * part is ignored.
1441 * \param prv The keypair structure holding the full keypair.
1442 * This must be initialized.
1443 * \param f_rng The RNG function. This must not be \c NULL.
1444 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c
1445 * NULL if \p f_rng doesn't need a context.
1446 *
1447 * \return \c 0 on success, meaning that the keys are valid and match.
1448 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match.
1449 * \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
1450 * error code on calculation failure.
1451 */
1452 int mbedtls_ecp_check_pub_priv(
1453 const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv,
1454 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
1455
1456 /** \brief Calculate the public key from a private key in a key pair.
1457 *
1458 * \param key A keypair structure. It must have a private key set.
1459 * If the public key is set, it will be overwritten.
1460 * \param f_rng The RNG function. This must not be \c NULL.
1461 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c
1462 * NULL if \p f_rng doesn't need a context.
1463 *
1464 * \return \c 0 on success. The key pair object can be used for
1465 * operations that require the public key.
1466 * \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX
1467 * error code on calculation failure.
1468 */
1469 int mbedtls_ecp_keypair_calc_public(
1470 mbedtls_ecp_keypair *key,
1471 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
1472
1473 /** \brief Query the group that a key pair belongs to.
1474 *
1475 * \param key The key pair to query.
1476 *
1477 * \return The group ID for the group registered in the key pair
1478 * object.
1479 * This is \c MBEDTLS_ECP_DP_NONE if no group has been set
1480 * in the key pair object.
1481 */
1482 mbedtls_ecp_group_id mbedtls_ecp_keypair_get_group_id(
1483 const mbedtls_ecp_keypair *key);
1484
1485 /**
1486 * \brief This function exports generic key-pair parameters.
1487 *
1488 * Each of the output parameters can be a null pointer
1489 * if you do not need that parameter.
1490 *
1491 * \note If the private key or the public key was not set in \p key,
1492 * the corresponding output is unspecified. Future versions
1493 * may return an error in that case.
1494 *
1495 * \param key The key pair to export from.
1496 * \param grp Slot for exported ECP group.
1497 * It must either be null or point to an initialized ECP group.
1498 * \param d Slot for the exported secret value.
1499 * It must either be null or point to an initialized mpi.
1500 * \param Q Slot for the exported public value.
1501 * It must either be null or point to an initialized ECP point.
1502 *
1503 * \return \c 0 on success,
1504 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.
1505 * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if key id doesn't
1506 * correspond to a known group.
1507 * \return Another negative error code on other kinds of failure.
1508 */
1509 int mbedtls_ecp_export(const mbedtls_ecp_keypair *key, mbedtls_ecp_group *grp,
1510 mbedtls_mpi *d, mbedtls_ecp_point *Q);
1511
1512 #if defined(MBEDTLS_SELF_TEST)
1513
1514 /**
1515 * \brief The ECP checkup routine.
1516 *
1517 * \return \c 0 on success.
1518 * \return \c 1 on failure.
1519 */
1520 int mbedtls_ecp_self_test(int verbose);
1521
1522 #endif /* MBEDTLS_SELF_TEST */
1523
1524 #ifdef __cplusplus
1525 }
1526 #endif
1527
1528 #endif /* ecp.h */
1529
