]> git.zerfleddert.de Git - proxmark3-svn/blob - common/mbedtls/ecp.h
fix 'hf iclass sim':
[proxmark3-svn] / common / mbedtls / ecp.h
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. */
85 MBEDTLS_ECP_DP_SECP128R1, /*!< Domain parameters for the 128-bit curve used for NXP originality check. */
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 */
Impressum, Datenschutz