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