Commit | Line | Data |
---|---|---|
700d8687 OM |
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 (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved | |
19 | * SPDX-License-Identifier: GPL-2.0 | |
20 | * | |
21 | * This program is free software; you can redistribute it and/or modify | |
22 | * it under the terms of the GNU General Public License as published by | |
23 | * the Free Software Foundation; either version 2 of the License, or | |
24 | * (at your option) any later version. | |
25 | * | |
26 | * This program is distributed in the hope that it will be useful, | |
27 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
28 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
29 | * GNU General Public License for more details. | |
30 | * | |
31 | * You should have received a copy of the GNU General Public License along | |
32 | * with this program; if not, write to the Free Software Foundation, Inc., | |
33 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. | |
34 | * | |
35 | * This file is part of Mbed TLS (https://tls.mbed.org) | |
36 | */ | |
37 | ||
38 | #ifndef MBEDTLS_ECP_H | |
39 | #define MBEDTLS_ECP_H | |
40 | ||
41 | #include "bignum.h" | |
42 | ||
43 | /* | |
44 | * ECP error codes | |
45 | */ | |
46 | #define MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80 /**< Bad input parameters to function. */ | |
47 | #define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00 /**< The buffer is too small to write to. */ | |
48 | #define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< The requested feature is not available, for example, the requested curve is not supported. */ | |
49 | #define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00 /**< The signature is not valid. */ | |
50 | #define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 /**< Memory allocation failed. */ | |
51 | #define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 /**< Generation of random value, such as ephemeral key, failed. */ | |
52 | #define MBEDTLS_ERR_ECP_INVALID_KEY -0x4C80 /**< Invalid private or public key. */ | |
53 | #define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH -0x4C00 /**< The buffer contains a valid signature followed by more data. */ | |
54 | #define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80 /**< The ECP hardware accelerator failed. */ | |
55 | ||
56 | #ifdef __cplusplus | |
57 | extern "C" { | |
58 | #endif | |
59 | ||
60 | /** | |
61 | * Domain-parameter identifiers: curve, subgroup, and generator. | |
62 | * | |
63 | * \note Only curves over prime fields are supported. | |
64 | * | |
65 | * \warning This library does not support validation of arbitrary domain | |
66 | * parameters. Therefore, only standardized domain parameters from trusted | |
67 | * sources should be used. See mbedtls_ecp_group_load(). | |
68 | */ | |
69 | typedef enum | |
70 | { | |
71 | MBEDTLS_ECP_DP_NONE = 0, /*!< Curve not defined. */ | |
72 | MBEDTLS_ECP_DP_SECP192R1, /*!< Domain parameters for the 192-bit curve defined by FIPS 186-4 and SEC1. */ | |
73 | MBEDTLS_ECP_DP_SECP224R1, /*!< Domain parameters for the 224-bit curve defined by FIPS 186-4 and SEC1. */ | |
74 | MBEDTLS_ECP_DP_SECP256R1, /*!< Domain parameters for the 256-bit curve defined by FIPS 186-4 and SEC1. */ | |
75 | MBEDTLS_ECP_DP_SECP384R1, /*!< Domain parameters for the 384-bit curve defined by FIPS 186-4 and SEC1. */ | |
76 | MBEDTLS_ECP_DP_SECP521R1, /*!< Domain parameters for the 521-bit curve defined by FIPS 186-4 and SEC1. */ | |
77 | MBEDTLS_ECP_DP_BP256R1, /*!< Domain parameters for 256-bit Brainpool curve. */ | |
78 | MBEDTLS_ECP_DP_BP384R1, /*!< Domain parameters for 384-bit Brainpool curve. */ | |
79 | MBEDTLS_ECP_DP_BP512R1, /*!< Domain parameters for 512-bit Brainpool curve. */ | |
80 | MBEDTLS_ECP_DP_CURVE25519, /*!< Domain parameters for Curve25519. */ | |
81 | MBEDTLS_ECP_DP_SECP192K1, /*!< Domain parameters for 192-bit "Koblitz" curve. */ | |
82 | MBEDTLS_ECP_DP_SECP224K1, /*!< Domain parameters for 224-bit "Koblitz" curve. */ | |
83 | MBEDTLS_ECP_DP_SECP256K1, /*!< Domain parameters for 256-bit "Koblitz" curve. */ | |
84 | MBEDTLS_ECP_DP_CURVE448, /*!< Domain parameters for Curve448. */ | |
3a5ffba7 | 85 | MBEDTLS_ECP_DP_SECP128R1, /*!< Domain parameters for the 128-bit curve used for NXP originality check. */ |
700d8687 OM |
86 | } mbedtls_ecp_group_id; |
87 | ||
88 | /** | |
89 | * The number of supported curves, plus one for #MBEDTLS_ECP_DP_NONE. | |
90 | * | |
91 | * \note Montgomery curves are currently excluded. | |
92 | */ | |
93 | #define MBEDTLS_ECP_DP_MAX 12 | |
94 | ||
95 | /** | |
96 | * Curve information, for use by other modules. | |
97 | */ | |
98 | typedef struct mbedtls_ecp_curve_info | |
99 | { | |
100 | mbedtls_ecp_group_id grp_id; /*!< An internal identifier. */ | |
101 | uint16_t tls_id; /*!< The TLS NamedCurve identifier. */ | |
102 | uint16_t bit_size; /*!< The curve size in bits. */ | |
103 | const char *name; /*!< A human-friendly name. */ | |
104 | } mbedtls_ecp_curve_info; | |
105 | ||
106 | /** | |
107 | * \brief The ECP point structure, in Jacobian coordinates. | |
108 | * | |
109 | * \note All functions expect and return points satisfying | |
110 | * the following condition: <code>Z == 0</code> or | |
111 | * <code>Z == 1</code>. Other values of \p Z are | |
112 | * used only by internal functions. | |
113 | * The point is zero, or "at infinity", if <code>Z == 0</code>. | |
114 | * Otherwise, \p X and \p Y are its standard (affine) | |
115 | * coordinates. | |
116 | */ | |
117 | typedef struct mbedtls_ecp_point | |
118 | { | |
119 | mbedtls_mpi X; /*!< The X coordinate of the ECP point. */ | |
120 | mbedtls_mpi Y; /*!< The Y coordinate of the ECP point. */ | |
121 | mbedtls_mpi Z; /*!< The Z coordinate of the ECP point. */ | |
122 | } | |
123 | mbedtls_ecp_point; | |
124 | ||
125 | #if !defined(MBEDTLS_ECP_ALT) | |
126 | /* | |
127 | * default mbed TLS elliptic curve arithmetic implementation | |
128 | * | |
129 | * (in case MBEDTLS_ECP_ALT is defined then the developer has to provide an | |
130 | * alternative implementation for the whole module and it will replace this | |
131 | * one.) | |
132 | */ | |
133 | ||
134 | /** | |
135 | * \brief The ECP group structure. | |
136 | * | |
137 | * We consider two types of curve equations: | |
138 | * <ul><li>Short Weierstrass: <code>y^2 = x^3 + A x + B mod P</code> | |
139 | * (SEC1 + RFC-4492)</li> | |
140 | * <li>Montgomery: <code>y^2 = x^3 + A x^2 + x mod P</code> (Curve25519, | |
141 | * Curve448)</li></ul> | |
142 | * In both cases, the generator (\p G) for a prime-order subgroup is fixed. | |
143 | * | |
144 | * For Short Weierstrass, this subgroup is the whole curve, and its | |
145 | * cardinality is denoted by \p N. Our code requires that \p N is an | |
146 | * odd prime as mbedtls_ecp_mul() requires an odd number, and | |
147 | * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes. | |
148 | * | |
149 | * For Montgomery curves, we do not store \p A, but <code>(A + 2) / 4</code>, | |
150 | * which is the quantity used in the formulas. Additionally, \p nbits is | |
151 | * not the size of \p N but the required size for private keys. | |
152 | * | |
153 | * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm. | |
154 | * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the | |
155 | * range of <code>0..2^(2*pbits)-1</code>, and transforms it in-place to an integer | |
156 | * which is congruent mod \p P to the given MPI, and is close enough to \p pbits | |
157 | * in size, so that it may be efficiently brought in the 0..P-1 range by a few | |
158 | * additions or subtractions. Therefore, it is only an approximative modular | |
159 | * reduction. It must return 0 on success and non-zero on failure. | |
160 | * | |
161 | */ | |
162 | typedef struct mbedtls_ecp_group | |
163 | { | |
164 | mbedtls_ecp_group_id id; /*!< An internal group identifier. */ | |
165 | mbedtls_mpi P; /*!< The prime modulus of the base field. */ | |
166 | mbedtls_mpi A; /*!< For Short Weierstrass: \p A in the equation. For | |
167 | Montgomery curves: <code>(A + 2) / 4</code>. */ | |
168 | mbedtls_mpi B; /*!< For Short Weierstrass: \p B in the equation. | |
169 | For Montgomery curves: unused. */ | |
170 | mbedtls_ecp_point G; /*!< The generator of the subgroup used. */ | |
171 | mbedtls_mpi N; /*!< The order of \p G. */ | |
172 | size_t pbits; /*!< The number of bits in \p P.*/ | |
173 | size_t nbits; /*!< For Short Weierstrass: The number of bits in \p P. | |
174 | For Montgomery curves: the number of bits in the | |
175 | private keys. */ | |
176 | unsigned int h; /*!< \internal 1 if the constants are static. */ | |
177 | int (*modp)(mbedtls_mpi *); /*!< The function for fast pseudo-reduction | |
178 | mod \p P (see above).*/ | |
179 | int (*t_pre)(mbedtls_ecp_point *, void *); /*!< Unused. */ | |
180 | int (*t_post)(mbedtls_ecp_point *, void *); /*!< Unused. */ | |
181 | void *t_data; /*!< Unused. */ | |
182 | mbedtls_ecp_point *T; /*!< Pre-computed points for ecp_mul_comb(). */ | |
183 | size_t T_size; /*!< The number of pre-computed points. */ | |
184 | } | |
185 | mbedtls_ecp_group; | |
186 | ||
187 | /** | |
188 | * \name SECTION: Module settings | |
189 | * | |
190 | * The configuration options you can set for this module are in this section. | |
191 | * Either change them in config.h, or define them using the compiler command line. | |
192 | * \{ | |
193 | */ | |
194 | ||
195 | #if !defined(MBEDTLS_ECP_MAX_BITS) | |
196 | /** | |
197 | * The maximum size of the groups, that is, of \c N and \c P. | |
198 | */ | |
199 | #define MBEDTLS_ECP_MAX_BITS 521 /**< The maximum size of groups, in bits. */ | |
200 | #endif | |
201 | ||
202 | #define MBEDTLS_ECP_MAX_BYTES ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 ) | |
203 | #define MBEDTLS_ECP_MAX_PT_LEN ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 ) | |
204 | ||
205 | #if !defined(MBEDTLS_ECP_WINDOW_SIZE) | |
206 | /* | |
207 | * Maximum "window" size used for point multiplication. | |
208 | * Default: 6. | |
209 | * Minimum value: 2. Maximum value: 7. | |
210 | * | |
211 | * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) ) | |
212 | * points used for point multiplication. This value is directly tied to EC | |
213 | * peak memory usage, so decreasing it by one should roughly cut memory usage | |
214 | * by two (if large curves are in use). | |
215 | * | |
216 | * Reduction in size may reduce speed, but larger curves are impacted first. | |
217 | * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1): | |
218 | * w-size: 6 5 4 3 2 | |
219 | * 521 145 141 135 120 97 | |
220 | * 384 214 209 198 177 146 | |
221 | * 256 320 320 303 262 226 | |
222 | * 224 475 475 453 398 342 | |
223 | * 192 640 640 633 587 476 | |
224 | */ | |
225 | #define MBEDTLS_ECP_WINDOW_SIZE 6 /**< The maximum window size used. */ | |
226 | #endif /* MBEDTLS_ECP_WINDOW_SIZE */ | |
227 | ||
228 | #if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM) | |
229 | /* | |
230 | * Trade memory for speed on fixed-point multiplication. | |
231 | * | |
232 | * This speeds up repeated multiplication of the generator (that is, the | |
233 | * multiplication in ECDSA signatures, and half of the multiplications in | |
234 | * ECDSA verification and ECDHE) by a factor roughly 3 to 4. | |
235 | * | |
236 | * The cost is increasing EC peak memory usage by a factor roughly 2. | |
237 | * | |
238 | * Change this value to 0 to reduce peak memory usage. | |
239 | */ | |
240 | #define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up. */ | |
241 | #endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */ | |
242 | ||
243 | /* \} name SECTION: Module settings */ | |
244 | ||
245 | #else /* MBEDTLS_ECP_ALT */ | |
246 | #include "ecp_alt.h" | |
247 | #endif /* MBEDTLS_ECP_ALT */ | |
248 | ||
249 | /** | |
250 | * \brief The ECP key-pair structure. | |
251 | * | |
252 | * A generic key-pair that may be used for ECDSA and fixed ECDH, for example. | |
253 | * | |
254 | * \note Members are deliberately in the same order as in the | |
255 | * ::mbedtls_ecdsa_context structure. | |
256 | */ | |
257 | typedef struct mbedtls_ecp_keypair | |
258 | { | |
259 | mbedtls_ecp_group grp; /*!< Elliptic curve and base point */ | |
260 | mbedtls_mpi d; /*!< our secret value */ | |
261 | mbedtls_ecp_point Q; /*!< our public value */ | |
262 | } | |
263 | mbedtls_ecp_keypair; | |
264 | ||
265 | /* | |
266 | * Point formats, from RFC 4492's enum ECPointFormat | |
267 | */ | |
268 | #define MBEDTLS_ECP_PF_UNCOMPRESSED 0 /**< Uncompressed point format. */ | |
269 | #define MBEDTLS_ECP_PF_COMPRESSED 1 /**< Compressed point format. */ | |
270 | ||
271 | /* | |
272 | * Some other constants from RFC 4492 | |
273 | */ | |
274 | #define MBEDTLS_ECP_TLS_NAMED_CURVE 3 /**< The named_curve of ECCurveType. */ | |
275 | ||
276 | /** | |
277 | * \brief This function retrieves the information defined in | |
278 | * mbedtls_ecp_curve_info() for all supported curves in order | |
279 | * of preference. | |
280 | * | |
281 | * \return A statically allocated array. The last entry is 0. | |
282 | */ | |
283 | const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void ); | |
284 | ||
285 | /** | |
286 | * \brief This function retrieves the list of internal group | |
287 | * identifiers of all supported curves in the order of | |
288 | * preference. | |
289 | * | |
290 | * \return A statically allocated array, | |
291 | * terminated with MBEDTLS_ECP_DP_NONE. | |
292 | */ | |
293 | const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void ); | |
294 | ||
295 | /** | |
296 | * \brief This function retrieves curve information from an internal | |
297 | * group identifier. | |
298 | * | |
299 | * \param grp_id An \c MBEDTLS_ECP_DP_XXX value. | |
300 | * | |
301 | * \return The associated curve information on success. | |
302 | * \return NULL on failure. | |
303 | */ | |
304 | const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id ); | |
305 | ||
306 | /** | |
307 | * \brief This function retrieves curve information from a TLS | |
308 | * NamedCurve value. | |
309 | * | |
310 | * \param tls_id An \c MBEDTLS_ECP_DP_XXX value. | |
311 | * | |
312 | * \return The associated curve information on success. | |
313 | * \return NULL on failure. | |
314 | */ | |
315 | const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id ); | |
316 | ||
317 | /** | |
318 | * \brief This function retrieves curve information from a | |
319 | * human-readable name. | |
320 | * | |
321 | * \param name The human-readable name. | |
322 | * | |
323 | * \return The associated curve information on success. | |
324 | * \return NULL on failure. | |
325 | */ | |
326 | const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name ); | |
327 | ||
328 | /** | |
329 | * \brief This function initializes a point as zero. | |
330 | * | |
331 | * \param pt The point to initialize. | |
332 | */ | |
333 | void mbedtls_ecp_point_init( mbedtls_ecp_point *pt ); | |
334 | ||
335 | /** | |
336 | * \brief This function initializes an ECP group context | |
337 | * without loading any domain parameters. | |
338 | * | |
339 | * \note After this function is called, domain parameters | |
340 | * for various ECP groups can be loaded through the | |
341 | * mbedtls_ecp_load() or mbedtls_ecp_tls_read_group() | |
342 | * functions. | |
343 | */ | |
344 | void mbedtls_ecp_group_init( mbedtls_ecp_group *grp ); | |
345 | ||
346 | /** | |
347 | * \brief This function initializes a key pair as an invalid one. | |
348 | * | |
349 | * \param key The key pair to initialize. | |
350 | */ | |
351 | void mbedtls_ecp_keypair_init( mbedtls_ecp_keypair *key ); | |
352 | ||
353 | /** | |
354 | * \brief This function frees the components of a point. | |
355 | * | |
356 | * \param pt The point to free. | |
357 | */ | |
358 | void mbedtls_ecp_point_free( mbedtls_ecp_point *pt ); | |
359 | ||
360 | /** | |
361 | * \brief This function frees the components of an ECP group. | |
362 | * \param grp The group to free. | |
363 | */ | |
364 | void mbedtls_ecp_group_free( mbedtls_ecp_group *grp ); | |
365 | ||
366 | /** | |
367 | * \brief This function frees the components of a key pair. | |
368 | * \param key The key pair to free. | |
369 | */ | |
370 | void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key ); | |
371 | ||
372 | /** | |
373 | * \brief This function copies the contents of point \p Q into | |
374 | * point \p P. | |
375 | * | |
376 | * \param P The destination point. | |
377 | * \param Q The source point. | |
378 | * | |
379 | * \return \c 0 on success. | |
380 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. | |
381 | */ | |
382 | int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q ); | |
383 | ||
384 | /** | |
385 | * \brief This function copies the contents of group \p src into | |
386 | * group \p dst. | |
387 | * | |
388 | * \param dst The destination group. | |
389 | * \param src The source group. | |
390 | * | |
391 | * \return \c 0 on success. | |
392 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. | |
393 | */ | |
394 | int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src ); | |
395 | ||
396 | /** | |
397 | * \brief This function sets a point to zero. | |
398 | * | |
399 | * \param pt The point to set. | |
400 | * | |
401 | * \return \c 0 on success. | |
402 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. | |
403 | */ | |
404 | int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt ); | |
405 | ||
406 | /** | |
407 | * \brief This function checks if a point is zero. | |
408 | * | |
409 | * \param pt The point to test. | |
410 | * | |
411 | * \return \c 1 if the point is zero. | |
412 | * \return \c 0 if the point is non-zero. | |
413 | */ | |
414 | int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt ); | |
415 | ||
416 | /** | |
417 | * \brief This function compares two points. | |
418 | * | |
419 | * \note This assumes that the points are normalized. Otherwise, | |
420 | * they may compare as "not equal" even if they are. | |
421 | * | |
422 | * \param P The first point to compare. | |
423 | * \param Q The second point to compare. | |
424 | * | |
425 | * \return \c 0 if the points are equal. | |
426 | * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal. | |
427 | */ | |
428 | int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P, | |
429 | const mbedtls_ecp_point *Q ); | |
430 | ||
431 | /** | |
432 | * \brief This function imports a non-zero point from two ASCII | |
433 | * strings. | |
434 | * | |
435 | * \param P The destination point. | |
436 | * \param radix The numeric base of the input. | |
437 | * \param x The first affine coordinate, as a null-terminated string. | |
438 | * \param y The second affine coordinate, as a null-terminated string. | |
439 | * | |
440 | * \return \c 0 on success. | |
441 | * \return An \c MBEDTLS_ERR_MPI_XXX error code on failure. | |
442 | */ | |
443 | int mbedtls_ecp_point_read_string( mbedtls_ecp_point *P, int radix, | |
444 | const char *x, const char *y ); | |
445 | ||
446 | /** | |
447 | * \brief This function exports a point into unsigned binary data. | |
448 | * | |
449 | * \param grp The group to which the point should belong. | |
450 | * \param P The point to export. | |
451 | * \param format The point format. Should be an \c MBEDTLS_ECP_PF_XXX macro. | |
452 | * \param olen The length of the output. | |
453 | * \param buf The output buffer. | |
454 | * \param buflen The length of the output buffer. | |
455 | * | |
456 | * \return \c 0 on success. | |
457 | * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA | |
458 | * or #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure. | |
459 | */ | |
460 | int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *P, | |
461 | int format, size_t *olen, | |
462 | unsigned char *buf, size_t buflen ); | |
463 | ||
464 | /** | |
465 | * \brief This function imports a point from unsigned binary data. | |
466 | * | |
467 | * \note This function does not check that the point actually | |
468 | * belongs to the given group, see mbedtls_ecp_check_pubkey() | |
469 | * for that. | |
470 | * | |
471 | * \param grp The group to which the point should belong. | |
472 | * \param P The point to import. | |
473 | * \param buf The input buffer. | |
474 | * \param ilen The length of the input. | |
475 | * | |
476 | * \return \c 0 on success. | |
477 | * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid. | |
478 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. | |
479 | * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format | |
480 | * is not implemented. | |
481 | * | |
482 | */ | |
483 | int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_point *P, | |
484 | const unsigned char *buf, size_t ilen ); | |
485 | ||
486 | /** | |
487 | * \brief This function imports a point from a TLS ECPoint record. | |
488 | * | |
489 | * \note On function return, \p buf is updated to point to immediately | |
490 | * after the ECPoint record. | |
491 | * | |
492 | * \param grp The ECP group used. | |
493 | * \param pt The destination point. | |
494 | * \param buf The address of the pointer to the start of the input buffer. | |
495 | * \param len The length of the buffer. | |
496 | * | |
497 | * \return \c 0 on success. | |
498 | * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure. | |
499 | * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid. | |
500 | */ | |
501 | int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point *pt, | |
502 | const unsigned char **buf, size_t len ); | |
503 | ||
504 | /** | |
505 | * \brief This function exports a point as a TLS ECPoint record. | |
506 | * | |
507 | * \param grp The ECP group used. | |
508 | * \param pt The point format to export to. The point format is an | |
509 | * \c MBEDTLS_ECP_PF_XXX constant. | |
510 | * \param format The export format. | |
511 | * \param olen The length of the data written. | |
512 | * \param buf The buffer to write to. | |
513 | * \param blen The length of the buffer. | |
514 | * | |
515 | * \return \c 0 on success. | |
516 | * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA or | |
517 | * #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure. | |
518 | */ | |
519 | int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt, | |
520 | int format, size_t *olen, | |
521 | unsigned char *buf, size_t blen ); | |
522 | ||
523 | /** | |
524 | * \brief This function sets a group using standardized domain parameters. | |
525 | * | |
526 | * \note The index should be a value of the NamedCurve enum, | |
527 | * as defined in <em>RFC-4492: Elliptic Curve Cryptography | |
528 | * (ECC) Cipher Suites for Transport Layer Security (TLS)</em>, | |
529 | * usually in the form of an \c MBEDTLS_ECP_DP_XXX macro. | |
530 | * | |
531 | * \param grp The destination group. | |
532 | * \param id The identifier of the domain parameter set to load. | |
533 | * | |
534 | * \return \c 0 on success, | |
535 | * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure. | |
536 | * \return #MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups. | |
537 | ||
538 | */ | |
539 | int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id ); | |
540 | ||
541 | /** | |
542 | * \brief This function sets a group from a TLS ECParameters record. | |
543 | * | |
544 | * \note \p buf is updated to point right after the ECParameters record | |
545 | * on exit. | |
546 | * | |
547 | * \param grp The destination group. | |
548 | * \param buf The address of the pointer to the start of the input buffer. | |
549 | * \param len The length of the buffer. | |
550 | * | |
551 | * \return \c 0 on success. | |
552 | * \return An \c MBEDTLS_ERR_MPI_XXX error code on initialization failure. | |
553 | * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid. | |
554 | */ | |
555 | int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp, const unsigned char **buf, size_t len ); | |
556 | ||
557 | /** | |
558 | * \brief This function writes the TLS ECParameters record for a group. | |
559 | * | |
560 | * \param grp The ECP group used. | |
561 | * \param olen The number of Bytes written. | |
562 | * \param buf The buffer to write to. | |
563 | * \param blen The length of the buffer. | |
564 | * | |
565 | * \return \c 0 on success. | |
566 | * \return #MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL on failure. | |
567 | */ | |
568 | int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen, | |
569 | unsigned char *buf, size_t blen ); | |
570 | ||
571 | /** | |
572 | * \brief This function performs multiplication of a point by | |
573 | * an integer: \p R = \p m * \p P. | |
574 | * | |
575 | * It is not thread-safe to use same group in multiple threads. | |
576 | * | |
577 | * \note To prevent timing attacks, this function | |
578 | * executes the exact same sequence of base-field | |
579 | * operations for any valid \p m. It avoids any if-branch or | |
580 | * array index depending on the value of \p m. | |
581 | * | |
582 | * \note If \p f_rng is not NULL, it is used to randomize | |
583 | * intermediate results to prevent potential timing attacks | |
584 | * targeting these results. We recommend always providing | |
585 | * a non-NULL \p f_rng. The overhead is negligible. | |
586 | * | |
587 | * \param grp The ECP group. | |
588 | * \param R The destination point. | |
589 | * \param m The integer by which to multiply. | |
590 | * \param P The point to multiply. | |
591 | * \param f_rng The RNG function. | |
592 | * \param p_rng The RNG context. | |
593 | * | |
594 | * \return \c 0 on success. | |
595 | * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private | |
596 | * key, or \p P is not a valid public key. | |
597 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. | |
598 | */ | |
599 | int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, | |
600 | const mbedtls_mpi *m, const mbedtls_ecp_point *P, | |
601 | int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); | |
602 | ||
603 | /** | |
604 | * \brief This function performs multiplication and addition of two | |
605 | * points by integers: \p R = \p m * \p P + \p n * \p Q | |
606 | * | |
607 | * It is not thread-safe to use same group in multiple threads. | |
608 | * | |
609 | * \note In contrast to mbedtls_ecp_mul(), this function does not | |
610 | * guarantee a constant execution flow and timing. | |
611 | * | |
612 | * \param grp The ECP group. | |
613 | * \param R The destination point. | |
614 | * \param m The integer by which to multiply \p P. | |
615 | * \param P The point to multiply by \p m. | |
616 | * \param n The integer by which to multiply \p Q. | |
617 | * \param Q The point to be multiplied by \p n. | |
618 | * | |
619 | * \return \c 0 on success. | |
620 | * \return #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not | |
621 | * valid private keys, or \p P or \p Q are not valid public | |
622 | * keys. | |
623 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure. | |
624 | */ | |
625 | int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, | |
626 | const mbedtls_mpi *m, const mbedtls_ecp_point *P, | |
627 | const mbedtls_mpi *n, const mbedtls_ecp_point *Q ); | |
628 | ||
629 | /** | |
630 | * \brief This function checks that a point is a valid public key | |
631 | * on this curve. | |
632 | * | |
633 | * It only checks that the point is non-zero, has | |
634 | * valid coordinates and lies on the curve. It does not verify | |
635 | * that it is indeed a multiple of \p G. This additional | |
636 | * check is computationally more expensive, is not required | |
637 | * by standards, and should not be necessary if the group | |
638 | * used has a small cofactor. In particular, it is useless for | |
639 | * the NIST groups which all have a cofactor of 1. | |
640 | * | |
641 | * \note This function uses bare components rather than an | |
642 | * ::mbedtls_ecp_keypair structure, to ease use with other | |
643 | * structures, such as ::mbedtls_ecdh_context or | |
644 | * ::mbedtls_ecdsa_context. | |
645 | * | |
646 | * \param grp The curve the point should lie on. | |
647 | * \param pt The point to check. | |
648 | * | |
649 | * \return \c 0 if the point is a valid public key. | |
650 | * \return #MBEDTLS_ERR_ECP_INVALID_KEY on failure. | |
651 | */ | |
652 | int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt ); | |
653 | ||
654 | /** | |
655 | * \brief This function checks that an \p mbedtls_mpi is a valid private | |
656 | * key for this curve. | |
657 | * | |
658 | * \note This function uses bare components rather than an | |
659 | * ::mbedtls_ecp_keypair structure to ease use with other | |
660 | * structures, such as ::mbedtls_ecdh_context or | |
661 | * ::mbedtls_ecdsa_context. | |
662 | * | |
663 | * \param grp The group used. | |
664 | * \param d The integer to check. | |
665 | * | |
666 | * \return \c 0 if the point is a valid private key. | |
667 | * \return #MBEDTLS_ERR_ECP_INVALID_KEY on failure. | |
668 | */ | |
669 | int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d ); | |
670 | ||
671 | /** | |
672 | * \brief This function generates a keypair with a configurable base | |
673 | * point. | |
674 | * | |
675 | * \note This function uses bare components rather than an | |
676 | * ::mbedtls_ecp_keypair structure to ease use with other | |
677 | * structures, such as ::mbedtls_ecdh_context or | |
678 | * ::mbedtls_ecdsa_context. | |
679 | * | |
680 | * \param grp The ECP group. | |
681 | * \param G The chosen base point. | |
682 | * \param d The destination MPI (secret part). | |
683 | * \param Q The destination point (public part). | |
684 | * \param f_rng The RNG function. | |
685 | * \param p_rng The RNG context. | |
686 | * | |
687 | * \return \c 0 on success. | |
688 | * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code | |
689 | * on failure. | |
690 | */ | |
691 | int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp, | |
692 | const mbedtls_ecp_point *G, | |
693 | mbedtls_mpi *d, mbedtls_ecp_point *Q, | |
694 | int (*f_rng)(void *, unsigned char *, size_t), | |
695 | void *p_rng ); | |
696 | ||
697 | /** | |
698 | * \brief This function generates an ECP keypair. | |
699 | * | |
700 | * \note This function uses bare components rather than an | |
701 | * ::mbedtls_ecp_keypair structure to ease use with other | |
702 | * structures, such as ::mbedtls_ecdh_context or | |
703 | * ::mbedtls_ecdsa_context. | |
704 | * | |
705 | * \param grp The ECP group. | |
706 | * \param d The destination MPI (secret part). | |
707 | * \param Q The destination point (public part). | |
708 | * \param f_rng The RNG function. | |
709 | * \param p_rng The RNG context. | |
710 | * | |
711 | * \return \c 0 on success. | |
712 | * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code | |
713 | * on failure. | |
714 | */ | |
715 | int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q, | |
716 | int (*f_rng)(void *, unsigned char *, size_t), | |
717 | void *p_rng ); | |
718 | ||
719 | /** | |
720 | * \brief This function generates an ECP key. | |
721 | * | |
722 | * \param grp_id The ECP group identifier. | |
723 | * \param key The destination key. | |
724 | * \param f_rng The RNG function. | |
725 | * \param p_rng The RNG context. | |
726 | * | |
727 | * \return \c 0 on success. | |
728 | * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX error code | |
729 | * on failure. | |
730 | */ | |
731 | int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key, | |
732 | int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); | |
733 | ||
734 | /** | |
735 | * \brief This function checks that the keypair objects | |
736 | * \p pub and \p prv have the same group and the | |
737 | * same public point, and that the private key in | |
738 | * \p prv is consistent with the public key. | |
739 | * | |
740 | * \param pub The keypair structure holding the public key. | |
741 | * If it contains a private key, that part is ignored. | |
742 | * \param prv The keypair structure holding the full keypair. | |
743 | * | |
744 | * \return \c 0 on success, meaning that the keys are valid and match. | |
745 | * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match. | |
746 | * \return An \c MBEDTLS_ERR_ECP_XXX or an \c MBEDTLS_ERR_MPI_XXX | |
747 | * error code on calculation failure. | |
748 | */ | |
749 | int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv ); | |
750 | ||
751 | #if defined(MBEDTLS_SELF_TEST) | |
752 | ||
753 | /** | |
754 | * \brief The ECP checkup routine. | |
755 | * | |
756 | * \return \c 0 on success. | |
757 | * \return \c 1 on failure. | |
758 | */ | |
759 | int mbedtls_ecp_self_test( int verbose ); | |
760 | ||
761 | #endif /* MBEDTLS_SELF_TEST */ | |
762 | ||
763 | #ifdef __cplusplus | |
764 | } | |
765 | #endif | |
766 | ||
767 | #endif /* ecp.h */ |