_ Git - BearSSL/blob - 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 ncessearily 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