Fixed spurious warning about old-style prototype.
[BearSSL] / inc / bearssl_ec.h
1 /*
2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files (the
6 * "Software"), to deal in the Software without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Software, and to
9 * permit persons to whom the Software is furnished to do so, subject to
10 * the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 */
24
25 #ifndef BR_BEARSSL_EC_H__
26 #define BR_BEARSSL_EC_H__
27
28 #include <stddef.h>
29 #include <stdint.h>
30
31 #include "bearssl_rand.h"
32
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36
37 /** \file bearssl_ec.h
38 *
39 * # Elliptic Curves
40 *
41 * This file documents the EC implementations provided with BearSSL, and
42 * ECDSA.
43 *
44 * ## Elliptic Curve API
45 *
46 * Only "named curves" are supported. Each EC implementation supports
47 * one or several named curves, identified by symbolic identifiers.
48 * These identifiers are small integers, that correspond to the values
49 * registered by the
50 * [IANA](http://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8).
51 *
52 * Since all currently defined elliptic curve identifiers are in the 0..31
53 * range, it is convenient to encode support of some curves in a 32-bit
54 * word, such that bit x corresponds to curve of identifier x.
55 *
56 * An EC implementation is incarnated by a `br_ec_impl` instance, that
57 * offers the following fields:
58 *
59 * - `supported_curves`
60 *
61 * A 32-bit word that documents the identifiers of the curves supported
62 * by this implementation.
63 *
64 * - `generator()`
65 *
66 * Callback method that returns a pointer to the conventional generator
67 * point for that curve.
68 *
69 * - `order()`
70 *
71 * Callback method that returns a pointer to the subgroup order for
72 * that curve. That value uses unsigned big-endian encoding.
73 *
74 * - `xoff()`
75 *
76 * Callback method that returns the offset and length of the X
77 * coordinate in an encoded point.
78 *
79 * - `mul()`
80 *
81 * Multiply a curve point with an integer.
82 *
83 * - `mulgen()`
84 *
85 * Multiply the curve generator with an integer. This may be faster
86 * than the generic `mul()`.
87 *
88 * - `muladd()`
89 *
90 * Multiply two curve points by two integers, and return the sum of
91 * the two products.
92 *
93 * All curve points are represented in uncompressed format. The `mul()`
94 * and `muladd()` methods take care to validate that the provided points
95 * are really part of the relevant curve subgroup.
96 *
97 * For all point multiplication functions, the following holds:
98 *
99 * - Functions validate that the provided points are valid members
100 * of the relevant curve subgroup. An error is reported if that is
101 * not the case.
102 *
103 * - Processing is constant-time, even if the point operands are not
104 * valid. This holds for both the source and resulting points, and
105 * the multipliers (integers). Only the byte length of the provided
106 * multiplier arrays (not their actual value length in bits) may
107 * leak through timing-based side channels.
108 *
109 * - The multipliers (integers) MUST be lower than the subgroup order.
110 * If this property is not met, then the result is indeterminate,
111 * but an error value is not necessarily returned.
112 *
113 *
114 * ## ECDSA
115 *
116 * ECDSA signatures have two standard formats, called "raw" and "asn1".
117 * Internally, such a signature is a pair of modular integers `(r,s)`.
118 * The "raw" format is the concatenation of the unsigned big-endian
119 * encodings of these two integers, possibly left-padded with zeros so
120 * that they have the same encoded length. The "asn1" format is the
121 * DER encoding of an ASN.1 structure that contains the two integer
122 * values:
123 *
124 * ECDSASignature ::= SEQUENCE {
125 * r INTEGER,
126 * s INTEGER
127 * }
128 *
129 * In general, in all of X.509 and SSL/TLS, the "asn1" format is used.
130 * BearSSL offers ECDSA implementations for both formats; conversion
131 * functions between the two formats are also provided. Conversion of a
132 * "raw" format signature into "asn1" may enlarge a signature by no more
133 * than 9 bytes for all supported curves; conversely, conversion of an
134 * "asn1" signature to "raw" may expand the signature but the "raw"
135 * length will never be more than twice the length of the "asn1" length
136 * (and usually it will be shorter).
137 *
138 * Note that for a given signature, the "raw" format is not fully
139 * deterministic, in that it does not enforce a minimal common length.
140 */
141
142 /*
143 * Standard curve ID. These ID are equal to the assigned numerical
144 * identifiers assigned to these curves for TLS:
145 * http://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8
146 */
147
148 /** \brief Identifier for named curve sect163k1. */
149 #define BR_EC_sect163k1 1
150
151 /** \brief Identifier for named curve sect163r1. */
152 #define BR_EC_sect163r1 2
153
154 /** \brief Identifier for named curve sect163r2. */
155 #define BR_EC_sect163r2 3
156
157 /** \brief Identifier for named curve sect193r1. */
158 #define BR_EC_sect193r1 4
159
160 /** \brief Identifier for named curve sect193r2. */
161 #define BR_EC_sect193r2 5
162
163 /** \brief Identifier for named curve sect233k1. */
164 #define BR_EC_sect233k1 6
165
166 /** \brief Identifier for named curve sect233r1. */
167 #define BR_EC_sect233r1 7
168
169 /** \brief Identifier for named curve sect239k1. */
170 #define BR_EC_sect239k1 8
171
172 /** \brief Identifier for named curve sect283k1. */
173 #define BR_EC_sect283k1 9
174
175 /** \brief Identifier for named curve sect283r1. */
176 #define BR_EC_sect283r1 10
177
178 /** \brief Identifier for named curve sect409k1. */
179 #define BR_EC_sect409k1 11
180
181 /** \brief Identifier for named curve sect409r1. */
182 #define BR_EC_sect409r1 12
183
184 /** \brief Identifier for named curve sect571k1. */
185 #define BR_EC_sect571k1 13
186
187 /** \brief Identifier for named curve sect571r1. */
188 #define BR_EC_sect571r1 14
189
190 /** \brief Identifier for named curve secp160k1. */
191 #define BR_EC_secp160k1 15
192
193 /** \brief Identifier for named curve secp160r1. */
194 #define BR_EC_secp160r1 16
195
196 /** \brief Identifier for named curve secp160r2. */
197 #define BR_EC_secp160r2 17
198
199 /** \brief Identifier for named curve secp192k1. */
200 #define BR_EC_secp192k1 18
201
202 /** \brief Identifier for named curve secp192r1. */
203 #define BR_EC_secp192r1 19
204
205 /** \brief Identifier for named curve secp224k1. */
206 #define BR_EC_secp224k1 20
207
208 /** \brief Identifier for named curve secp224r1. */
209 #define BR_EC_secp224r1 21
210
211 /** \brief Identifier for named curve secp256k1. */
212 #define BR_EC_secp256k1 22
213
214 /** \brief Identifier for named curve secp256r1. */
215 #define BR_EC_secp256r1 23
216
217 /** \brief Identifier for named curve secp384r1. */
218 #define BR_EC_secp384r1 24
219
220 /** \brief Identifier for named curve secp521r1. */
221 #define BR_EC_secp521r1 25
222
223 /** \brief Identifier for named curve brainpoolP256r1. */
224 #define BR_EC_brainpoolP256r1 26
225
226 /** \brief Identifier for named curve brainpoolP384r1. */
227 #define BR_EC_brainpoolP384r1 27
228
229 /** \brief Identifier for named curve brainpoolP512r1. */
230 #define BR_EC_brainpoolP512r1 28
231
232 /** \brief Identifier for named curve Curve25519. */
233 #define BR_EC_curve25519 29
234
235 /** \brief Identifier for named curve Curve448. */
236 #define BR_EC_curve448 30
237
238 /**
239 * \brief Structure for an EC public key.
240 */
241 typedef struct {
242 /** \brief Identifier for the curve used by this key. */
243 int curve;
244 /** \brief Public curve point (uncompressed format). */
245 unsigned char *q;
246 /** \brief Length of public curve point (in bytes). */
247 size_t qlen;
248 } br_ec_public_key;
249
250 /**
251 * \brief Structure for an EC private key.
252 *
253 * The private key is an integer modulo the curve subgroup order. The
254 * encoding below tolerates extra leading zeros. In general, it is
255 * recommended that the private key has the same length as the curve
256 * subgroup order.
257 */
258 typedef struct {
259 /** \brief Identifier for the curve used by this key. */
260 int curve;
261 /** \brief Private key (integer, unsigned big-endian encoding). */
262 unsigned char *x;
263 /** \brief Private key length (in bytes). */
264 size_t xlen;
265 } br_ec_private_key;
266
267 /**
268 * \brief Type for an EC implementation.
269 */
270 typedef struct {
271 /**
272 * \brief Supported curves.
273 *
274 * This word is a bitfield: bit `x` is set if the curve of ID `x`
275 * is supported. E.g. an implementation supporting both NIST P-256
276 * (secp256r1, ID 23) and NIST P-384 (secp384r1, ID 24) will have
277 * value `0x01800000` in this field.
278 */
279 uint32_t supported_curves;
280
281 /**
282 * \brief Get the conventional generator.
283 *
284 * This function returns the conventional generator (encoded
285 * curve point) for the specified curve. This function MUST NOT
286 * be called if the curve is not supported.
287 *
288 * \param curve curve identifier.
289 * \param len receiver for the encoded generator length (in bytes).
290 * \return the encoded generator.
291 */
292 const unsigned char *(*generator)(int curve, size_t *len);
293
294 /**
295 * \brief Get the subgroup order.
296 *
297 * This function returns the order of the subgroup generated by
298 * the conventional generator, for the specified curve. Unsigned
299 * big-endian encoding is used. This function MUST NOT be called
300 * if the curve is not supported.
301 *
302 * \param curve curve identifier.
303 * \param len receiver for the encoded order length (in bytes).
304 * \return the encoded order.
305 */
306 const unsigned char *(*order)(int curve, size_t *len);
307
308 /**
309 * \brief Get the offset and length for the X coordinate.
310 *
311 * This function returns the offset and length (in bytes) of
312 * the X coordinate in an encoded non-zero point.
313 *
314 * \param curve curve identifier.
315 * \param len receiver for the X coordinate length (in bytes).
316 * \return the offset for the X coordinate (in bytes).
317 */
318 size_t (*xoff)(int curve, size_t *len);
319
320 /**
321 * \brief Multiply a curve point by an integer.
322 *
323 * The source point is provided in array `G` (of size `Glen` bytes);
324 * the multiplication result is written over it. The multiplier
325 * `x` (of size `xlen` bytes) uses unsigned big-endian encoding.
326 *
327 * Rules:
328 *
329 * - The specified curve MUST be supported.
330 *
331 * - The source point must be a valid point on the relevant curve
332 * subgroup (and not the "point at infinity" either). If this is
333 * not the case, then this function returns an error (0).
334 *
335 * - The multiplier integer MUST be non-zero and less than the
336 * curve subgroup order. If this property does not hold, then
337 * the result is indeterminate and an error code is not
338 * guaranteed.
339 *
340 * Returned value is 1 on success, 0 on error. On error, the
341 * contents of `G` are indeterminate.
342 *
343 * \param G point to multiply.
344 * \param Glen length of the encoded point (in bytes).
345 * \param x multiplier (unsigned big-endian).
346 * \param xlen multiplier length (in bytes).
347 * \param curve curve identifier.
348 * \return 1 on success, 0 on error.
349 */
350 uint32_t (*mul)(unsigned char *G, size_t Glen,
351 const unsigned char *x, size_t xlen, int curve);
352
353 /**
354 * \brief Multiply the generator by an integer.
355 *
356 * The multiplier MUST be non-zero and less than the curve
357 * subgroup order. Results are indeterminate if this property
358 * does not hold.
359 *
360 * \param R output buffer for the point.
361 * \param x multiplier (unsigned big-endian).
362 * \param xlen multiplier length (in bytes).
363 * \param curve curve identifier.
364 * \return encoded result point length (in bytes).
365 */
366 size_t (*mulgen)(unsigned char *R,
367 const unsigned char *x, size_t xlen, int curve);
368
369 /**
370 * \brief Multiply two points by two integers and add the
371 * results.
372 *
373 * The point `x*A + y*B` is computed and written back in the `A`
374 * array.
375 *
376 * Rules:
377 *
378 * - The specified curve MUST be supported.
379 *
380 * - The source points (`A` and `B`) must be valid points on
381 * the relevant curve subgroup (and not the "point at
382 * infinity" either). If this is not the case, then this
383 * function returns an error (0).
384 *
385 * - If the `B` pointer is `NULL`, then the conventional
386 * subgroup generator is used. With some implementations,
387 * this may be faster than providing a pointer to the
388 * generator.
389 *
390 * - The multiplier integers (`x` and `y`) MUST be non-zero
391 * and less than the curve subgroup order. If either integer
392 * is zero, then an error is reported, but if one of them is
393 * not lower than the subgroup order, then the result is
394 * indeterminate and an error code is not guaranteed.
395 *
396 * - If the final result is the point at infinity, then an
397 * error is returned.
398 *
399 * Returned value is 1 on success, 0 on error. On error, the
400 * contents of `A` are indeterminate.
401 *
402 * \param A first point to multiply.
403 * \param B second point to multiply (`NULL` for the generator).
404 * \param len common length of the encoded points (in bytes).
405 * \param x multiplier for `A` (unsigned big-endian).
406 * \param xlen length of multiplier for `A` (in bytes).
407 * \param y multiplier for `A` (unsigned big-endian).
408 * \param ylen length of multiplier for `A` (in bytes).
409 * \param curve curve identifier.
410 * \return 1 on success, 0 on error.
411 */
412 uint32_t (*muladd)(unsigned char *A, const unsigned char *B, size_t len,
413 const unsigned char *x, size_t xlen,
414 const unsigned char *y, size_t ylen, int curve);
415 } br_ec_impl;
416
417 /**
418 * \brief EC implementation "i31".
419 *
420 * This implementation internally uses generic code for modular integers,
421 * with a representation as sequences of 31-bit words. It supports secp256r1,
422 * secp384r1 and secp521r1 (aka NIST curves P-256, P-384 and P-521).
423 */
424 extern const br_ec_impl br_ec_prime_i31;
425
426 /**
427 * \brief EC implementation "i15".
428 *
429 * This implementation internally uses generic code for modular integers,
430 * with a representation as sequences of 15-bit words. It supports secp256r1,
431 * secp384r1 and secp521r1 (aka NIST curves P-256, P-384 and P-521).
432 */
433 extern const br_ec_impl br_ec_prime_i15;
434
435 /**
436 * \brief EC implementation "m15" for P-256.
437 *
438 * This implementation uses specialised code for curve secp256r1 (also
439 * known as NIST P-256), with optional Karatsuba decomposition, and fast
440 * modular reduction thanks to the field modulus special format. Only
441 * 32-bit multiplications are used (with 32-bit results, not 64-bit).
442 */
443 extern const br_ec_impl br_ec_p256_m15;
444
445 /**
446 * \brief EC implementation "m31" for P-256.
447 *
448 * This implementation uses specialised code for curve secp256r1 (also
449 * known as NIST P-256), relying on multiplications of 31-bit values
450 * (MUL31).
451 */
452 extern const br_ec_impl br_ec_p256_m31;
453
454 /**
455 * \brief EC implementation "m62" (specialised code) for P-256.
456 *
457 * This implementation uses custom code relying on multiplication of
458 * integers up to 64 bits, with a 128-bit result. This implementation is
459 * defined only on platforms that offer the 64x64->128 multiplication
460 * support; use `br_ec_p256_m62_get()` to dynamically obtain a pointer
461 * to that implementation.
462 */
463 extern const br_ec_impl br_ec_p256_m62;
464
465 /**
466 * \brief Get the "m62" implementation of P-256, if available.
467 *
468 * \return the implementation, or 0.
469 */
470 const br_ec_impl *br_ec_p256_m62_get(void);
471
472 /**
473 * \brief EC implementation "m64" (specialised code) for P-256.
474 *
475 * This implementation uses custom code relying on multiplication of
476 * integers up to 64 bits, with a 128-bit result. This implementation is
477 * defined only on platforms that offer the 64x64->128 multiplication
478 * support; use `br_ec_p256_m64_get()` to dynamically obtain a pointer
479 * to that implementation.
480 */
481 extern const br_ec_impl br_ec_p256_m64;
482
483 /**
484 * \brief Get the "m64" implementation of P-256, if available.
485 *
486 * \return the implementation, or 0.
487 */
488 const br_ec_impl *br_ec_p256_m64_get(void);
489
490 /**
491 * \brief EC implementation "i15" (generic code) for Curve25519.
492 *
493 * This implementation uses the generic code for modular integers (with
494 * 15-bit words) to support Curve25519. Due to the specificities of the
495 * curve definition, the following applies:
496 *
497 * - `muladd()` is not implemented (the function returns 0 systematically).
498 * - `order()` returns 2^255-1, since the point multiplication algorithm
499 * accepts any 32-bit integer as input (it clears the top bit and low
500 * three bits systematically).
501 */
502 extern const br_ec_impl br_ec_c25519_i15;
503
504 /**
505 * \brief EC implementation "i31" (generic code) for Curve25519.
506 *
507 * This implementation uses the generic code for modular integers (with
508 * 31-bit words) to support Curve25519. Due to the specificities of the
509 * curve definition, the following applies:
510 *
511 * - `muladd()` is not implemented (the function returns 0 systematically).
512 * - `order()` returns 2^255-1, since the point multiplication algorithm
513 * accepts any 32-bit integer as input (it clears the top bit and low
514 * three bits systematically).
515 */
516 extern const br_ec_impl br_ec_c25519_i31;
517
518 /**
519 * \brief EC implementation "m15" (specialised code) for Curve25519.
520 *
521 * This implementation uses custom code relying on multiplication of
522 * integers up to 15 bits. Due to the specificities of the curve
523 * definition, the following applies:
524 *
525 * - `muladd()` is not implemented (the function returns 0 systematically).
526 * - `order()` returns 2^255-1, since the point multiplication algorithm
527 * accepts any 32-bit integer as input (it clears the top bit and low
528 * three bits systematically).
529 */
530 extern const br_ec_impl br_ec_c25519_m15;
531
532 /**
533 * \brief EC implementation "m31" (specialised code) for Curve25519.
534 *
535 * This implementation uses custom code relying on multiplication of
536 * integers up to 31 bits. Due to the specificities of the curve
537 * definition, the following applies:
538 *
539 * - `muladd()` is not implemented (the function returns 0 systematically).
540 * - `order()` returns 2^255-1, since the point multiplication algorithm
541 * accepts any 32-bit integer as input (it clears the top bit and low
542 * three bits systematically).
543 */
544 extern const br_ec_impl br_ec_c25519_m31;
545
546 /**
547 * \brief EC implementation "m62" (specialised code) for Curve25519.
548 *
549 * This implementation uses custom code relying on multiplication of
550 * integers up to 62 bits, with a 124-bit result. This implementation is
551 * defined only on platforms that offer the 64x64->128 multiplication
552 * support; use `br_ec_c25519_m62_get()` to dynamically obtain a pointer
553 * to that implementation. Due to the specificities of the curve
554 * definition, the following applies:
555 *
556 * - `muladd()` is not implemented (the function returns 0 systematically).
557 * - `order()` returns 2^255-1, since the point multiplication algorithm
558 * accepts any 32-bit integer as input (it clears the top bit and low
559 * three bits systematically).
560 */
561 extern const br_ec_impl br_ec_c25519_m62;
562
563 /**
564 * \brief Get the "m62" implementation of Curve25519, if available.
565 *
566 * \return the implementation, or 0.
567 */
568 const br_ec_impl *br_ec_c25519_m62_get(void);
569
570 /**
571 * \brief EC implementation "m64" (specialised code) for Curve25519.
572 *
573 * This implementation uses custom code relying on multiplication of
574 * integers up to 64 bits, with a 128-bit result. This implementation is
575 * defined only on platforms that offer the 64x64->128 multiplication
576 * support; use `br_ec_c25519_m64_get()` to dynamically obtain a pointer
577 * to that implementation. Due to the specificities of the curve
578 * definition, the following applies:
579 *
580 * - `muladd()` is not implemented (the function returns 0 systematically).
581 * - `order()` returns 2^255-1, since the point multiplication algorithm
582 * accepts any 32-bit integer as input (it clears the top bit and low
583 * three bits systematically).
584 */
585 extern const br_ec_impl br_ec_c25519_m64;
586
587 /**
588 * \brief Get the "m64" implementation of Curve25519, if available.
589 *
590 * \return the implementation, or 0.
591 */
592 const br_ec_impl *br_ec_c25519_m64_get(void);
593
594 /**
595 * \brief Aggregate EC implementation "m15".
596 *
597 * This implementation is a wrapper for:
598 *
599 * - `br_ec_c25519_m15` for Curve25519
600 * - `br_ec_p256_m15` for NIST P-256
601 * - `br_ec_prime_i15` for other curves (NIST P-384 and NIST-P512)
602 */
603 extern const br_ec_impl br_ec_all_m15;
604
605 /**
606 * \brief Aggregate EC implementation "m31".
607 *
608 * This implementation is a wrapper for:
609 *
610 * - `br_ec_c25519_m31` for Curve25519
611 * - `br_ec_p256_m31` for NIST P-256
612 * - `br_ec_prime_i31` for other curves (NIST P-384 and NIST-P512)
613 */
614 extern const br_ec_impl br_ec_all_m31;
615
616 /**
617 * \brief Get the "default" EC implementation for the current system.
618 *
619 * This returns a pointer to the preferred implementation on the
620 * current system.
621 *
622 * \return the default EC implementation.
623 */
624 const br_ec_impl *br_ec_get_default(void);
625
626 /**
627 * \brief Convert a signature from "raw" to "asn1".
628 *
629 * Conversion is done "in place" and the new length is returned.
630 * Conversion may enlarge the signature, but by no more than 9 bytes at
631 * most. On error, 0 is returned (error conditions include an odd raw
632 * signature length, or an oversized integer).
633 *
634 * \param sig signature to convert.
635 * \param sig_len signature length (in bytes).
636 * \return the new signature length, or 0 on error.
637 */
638 size_t br_ecdsa_raw_to_asn1(void *sig, size_t sig_len);
639
640 /**
641 * \brief Convert a signature from "asn1" to "raw".
642 *
643 * Conversion is done "in place" and the new length is returned.
644 * Conversion may enlarge the signature, but the new signature length
645 * will be less than twice the source length at most. On error, 0 is
646 * returned (error conditions include an invalid ASN.1 structure or an
647 * oversized integer).
648 *
649 * \param sig signature to convert.
650 * \param sig_len signature length (in bytes).
651 * \return the new signature length, or 0 on error.
652 */
653 size_t br_ecdsa_asn1_to_raw(void *sig, size_t sig_len);
654
655 /**
656 * \brief Type for an ECDSA signer function.
657 *
658 * A pointer to the EC implementation is provided. The hash value is
659 * assumed to have the length inferred from the designated hash function
660 * class.
661 *
662 * Signature is written in the buffer pointed to by `sig`, and the length
663 * (in bytes) is returned. On error, nothing is written in the buffer,
664 * and 0 is returned. This function returns 0 if the specified curve is
665 * not supported by the provided EC implementation.
666 *
667 * The signature format is either "raw" or "asn1", depending on the
668 * implementation; maximum length is predictable from the implemented
669 * curve:
670 *
671 * | curve | raw | asn1 |
672 * | :--------- | --: | ---: |
673 * | NIST P-256 | 64 | 72 |
674 * | NIST P-384 | 96 | 104 |
675 * | NIST P-521 | 132 | 139 |
676 *
677 * \param impl EC implementation to use.
678 * \param hf hash function used to process the data.
679 * \param hash_value signed data (hashed).
680 * \param sk EC private key.
681 * \param sig destination buffer.
682 * \return the signature length (in bytes), or 0 on error.
683 */
684 typedef size_t (*br_ecdsa_sign)(const br_ec_impl *impl,
685 const br_hash_class *hf, const void *hash_value,
686 const br_ec_private_key *sk, void *sig);
687
688 /**
689 * \brief Type for an ECDSA signature verification function.
690 *
691 * A pointer to the EC implementation is provided. The hashed value,
692 * computed over the purportedly signed data, is also provided with
693 * its length.
694 *
695 * The signature format is either "raw" or "asn1", depending on the
696 * implementation.
697 *
698 * Returned value is 1 on success (valid signature), 0 on error. This
699 * function returns 0 if the specified curve is not supported by the
700 * provided EC implementation.
701 *
702 * \param impl EC implementation to use.
703 * \param hash signed data (hashed).
704 * \param hash_len hash value length (in bytes).
705 * \param pk EC public key.
706 * \param sig signature.
707 * \param sig_len signature length (in bytes).
708 * \return 1 on success, 0 on error.
709 */
710 typedef uint32_t (*br_ecdsa_vrfy)(const br_ec_impl *impl,
711 const void *hash, size_t hash_len,
712 const br_ec_public_key *pk, const void *sig, size_t sig_len);
713
714 /**
715 * \brief ECDSA signature generator, "i31" implementation, "asn1" format.
716 *
717 * \see br_ecdsa_sign()
718 *
719 * \param impl EC implementation to use.
720 * \param hf hash function used to process the data.
721 * \param hash_value signed data (hashed).
722 * \param sk EC private key.
723 * \param sig destination buffer.
724 * \return the signature length (in bytes), or 0 on error.
725 */
726 size_t br_ecdsa_i31_sign_asn1(const br_ec_impl *impl,
727 const br_hash_class *hf, const void *hash_value,
728 const br_ec_private_key *sk, void *sig);
729
730 /**
731 * \brief ECDSA signature generator, "i31" implementation, "raw" format.
732 *
733 * \see br_ecdsa_sign()
734 *
735 * \param impl EC implementation to use.
736 * \param hf hash function used to process the data.
737 * \param hash_value signed data (hashed).
738 * \param sk EC private key.
739 * \param sig destination buffer.
740 * \return the signature length (in bytes), or 0 on error.
741 */
742 size_t br_ecdsa_i31_sign_raw(const br_ec_impl *impl,
743 const br_hash_class *hf, const void *hash_value,
744 const br_ec_private_key *sk, void *sig);
745
746 /**
747 * \brief ECDSA signature verifier, "i31" implementation, "asn1" format.
748 *
749 * \see br_ecdsa_vrfy()
750 *
751 * \param impl EC implementation to use.
752 * \param hash signed data (hashed).
753 * \param hash_len hash value length (in bytes).
754 * \param pk EC public key.
755 * \param sig signature.
756 * \param sig_len signature length (in bytes).
757 * \return 1 on success, 0 on error.
758 */
759 uint32_t br_ecdsa_i31_vrfy_asn1(const br_ec_impl *impl,
760 const void *hash, size_t hash_len,
761 const br_ec_public_key *pk, const void *sig, size_t sig_len);
762
763 /**
764 * \brief ECDSA signature verifier, "i31" implementation, "raw" format.
765 *
766 * \see br_ecdsa_vrfy()
767 *
768 * \param impl EC implementation to use.
769 * \param hash signed data (hashed).
770 * \param hash_len hash value length (in bytes).
771 * \param pk EC public key.
772 * \param sig signature.
773 * \param sig_len signature length (in bytes).
774 * \return 1 on success, 0 on error.
775 */
776 uint32_t br_ecdsa_i31_vrfy_raw(const br_ec_impl *impl,
777 const void *hash, size_t hash_len,
778 const br_ec_public_key *pk, const void *sig, size_t sig_len);
779
780 /**
781 * \brief ECDSA signature generator, "i15" implementation, "asn1" format.
782 *
783 * \see br_ecdsa_sign()
784 *
785 * \param impl EC implementation to use.
786 * \param hf hash function used to process the data.
787 * \param hash_value signed data (hashed).
788 * \param sk EC private key.
789 * \param sig destination buffer.
790 * \return the signature length (in bytes), or 0 on error.
791 */
792 size_t br_ecdsa_i15_sign_asn1(const br_ec_impl *impl,
793 const br_hash_class *hf, const void *hash_value,
794 const br_ec_private_key *sk, void *sig);
795
796 /**
797 * \brief ECDSA signature generator, "i15" implementation, "raw" format.
798 *
799 * \see br_ecdsa_sign()
800 *
801 * \param impl EC implementation to use.
802 * \param hf hash function used to process the data.
803 * \param hash_value signed data (hashed).
804 * \param sk EC private key.
805 * \param sig destination buffer.
806 * \return the signature length (in bytes), or 0 on error.
807 */
808 size_t br_ecdsa_i15_sign_raw(const br_ec_impl *impl,
809 const br_hash_class *hf, const void *hash_value,
810 const br_ec_private_key *sk, void *sig);
811
812 /**
813 * \brief ECDSA signature verifier, "i15" implementation, "asn1" format.
814 *
815 * \see br_ecdsa_vrfy()
816 *
817 * \param impl EC implementation to use.
818 * \param hash signed data (hashed).
819 * \param hash_len hash value length (in bytes).
820 * \param pk EC public key.
821 * \param sig signature.
822 * \param sig_len signature length (in bytes).
823 * \return 1 on success, 0 on error.
824 */
825 uint32_t br_ecdsa_i15_vrfy_asn1(const br_ec_impl *impl,
826 const void *hash, size_t hash_len,
827 const br_ec_public_key *pk, const void *sig, size_t sig_len);
828
829 /**
830 * \brief ECDSA signature verifier, "i15" implementation, "raw" format.
831 *
832 * \see br_ecdsa_vrfy()
833 *
834 * \param impl EC implementation to use.
835 * \param hash signed data (hashed).
836 * \param hash_len hash value length (in bytes).
837 * \param pk EC public key.
838 * \param sig signature.
839 * \param sig_len signature length (in bytes).
840 * \return 1 on success, 0 on error.
841 */
842 uint32_t br_ecdsa_i15_vrfy_raw(const br_ec_impl *impl,
843 const void *hash, size_t hash_len,
844 const br_ec_public_key *pk, const void *sig, size_t sig_len);
845
846 /**
847 * \brief Get "default" ECDSA implementation (signer, asn1 format).
848 *
849 * This returns the preferred implementation of ECDSA signature generation
850 * ("asn1" output format) on the current system.
851 *
852 * \return the default implementation.
853 */
854 br_ecdsa_sign br_ecdsa_sign_asn1_get_default(void);
855
856 /**
857 * \brief Get "default" ECDSA implementation (signer, raw format).
858 *
859 * This returns the preferred implementation of ECDSA signature generation
860 * ("raw" output format) on the current system.
861 *
862 * \return the default implementation.
863 */
864 br_ecdsa_sign br_ecdsa_sign_raw_get_default(void);
865
866 /**
867 * \brief Get "default" ECDSA implementation (verifier, asn1 format).
868 *
869 * This returns the preferred implementation of ECDSA signature verification
870 * ("asn1" output format) on the current system.
871 *
872 * \return the default implementation.
873 */
874 br_ecdsa_vrfy br_ecdsa_vrfy_asn1_get_default(void);
875
876 /**
877 * \brief Get "default" ECDSA implementation (verifier, raw format).
878 *
879 * This returns the preferred implementation of ECDSA signature verification
880 * ("raw" output format) on the current system.
881 *
882 * \return the default implementation.
883 */
884 br_ecdsa_vrfy br_ecdsa_vrfy_raw_get_default(void);
885
886 /**
887 * \brief Maximum size for EC private key element buffer.
888 *
889 * This is the largest number of bytes that `br_ec_keygen()` may need or
890 * ever return.
891 */
892 #define BR_EC_KBUF_PRIV_MAX_SIZE 72
893
894 /**
895 * \brief Maximum size for EC public key element buffer.
896 *
897 * This is the largest number of bytes that `br_ec_compute_public()` may
898 * need or ever return.
899 */
900 #define BR_EC_KBUF_PUB_MAX_SIZE 145
901
902 /**
903 * \brief Generate a new EC private key.
904 *
905 * If the specified `curve` is not supported by the elliptic curve
906 * implementation (`impl`), then this function returns zero.
907 *
908 * The `sk` structure fields are set to the new private key data. In
909 * particular, `sk.x` is made to point to the provided key buffer (`kbuf`),
910 * in which the actual private key data is written. That buffer is assumed
911 * to be large enough. The `BR_EC_KBUF_PRIV_MAX_SIZE` defines the maximum
912 * size for all supported curves.
913 *
914 * The number of bytes used in `kbuf` is returned. If `kbuf` is `NULL`, then
915 * the private key is not actually generated, and `sk` may also be `NULL`;
916 * the minimum length for `kbuf` is still computed and returned.
917 *
918 * If `sk` is `NULL` but `kbuf` is not `NULL`, then the private key is
919 * still generated and stored in `kbuf`.
920 *
921 * \param rng_ctx source PRNG context (already initialized).
922 * \param impl the elliptic curve implementation.
923 * \param sk the private key structure to fill, or `NULL`.
924 * \param kbuf the key element buffer, or `NULL`.
925 * \param curve the curve identifier.
926 * \return the key data length (in bytes), or zero.
927 */
928 size_t br_ec_keygen(const br_prng_class **rng_ctx,
929 const br_ec_impl *impl, br_ec_private_key *sk,
930 void *kbuf, int curve);
931
932 /**
933 * \brief Compute EC public key from EC private key.
934 *
935 * This function uses the provided elliptic curve implementation (`impl`)
936 * to compute the public key corresponding to the private key held in `sk`.
937 * The public key point is written into `kbuf`, which is then linked from
938 * the `*pk` structure. The size of the public key point, i.e. the number
939 * of bytes used in `kbuf`, is returned.
940 *
941 * If `kbuf` is `NULL`, then the public key point is NOT computed, and
942 * the public key structure `*pk` is unmodified (`pk` may be `NULL` in
943 * that case). The size of the public key point is still returned.
944 *
945 * If `pk` is `NULL` but `kbuf` is not `NULL`, then the public key
946 * point is computed and stored in `kbuf`, and its size is returned.
947 *
948 * If the curve used by the private key is not supported by the curve
949 * implementation, then this function returns zero.
950 *
951 * The private key MUST be valid. An off-range private key value is not
952 * necessarily detected, and leads to unpredictable results.
953 *
954 * \param impl the elliptic curve implementation.
955 * \param pk the public key structure to fill (or `NULL`).
956 * \param kbuf the public key point buffer (or `NULL`).
957 * \param sk the source private key.
958 * \return the public key point length (in bytes), or zero.
959 */
960 size_t br_ec_compute_pub(const br_ec_impl *impl, br_ec_public_key *pk,
961 void *kbuf, const br_ec_private_key *sk);
962
963 #ifdef __cplusplus
964 }
965 #endif
966
967 #endif