_ 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 /*
  32  * Elliptic Curves
  33  * ---------------
  34  *
  35  * ECDSA signatures have two standard formats, called "raw" and "asn1".
  36  * Internally, such a signature is a pair of modular integers (r,s).
  37  * The "raw" format is the concatenation of the unsigned big-endian
  38  * encodings of these two integers, possibly left-padded with zeros so
  39  * that they have the same encoded length. The "asn1" format is the
  40  * DER encoding of an ASN.1 structure that contains the two integer
  41  * values:
  42  *
  43  *   ECDSASignature ::= SEQUENCE {
  44  *       r   INTEGER,
  45  *       s   INTEGER
  46  *   }
  47  *
  48  * Low-level implementations defined here work on the "raw" format.
  49  * Conversion functions are provided.
  50  *
  51  * Note that for a given signature, the "raw" format is not fully
  52  * deterministic, in that it does not enforce a minimal common length.
  53  * The functions below MUST ensure, when producing signatures, that
  54  * the signature length never exceeds 2*qlen, where qlen is the length,
  55  * in bytes, of the minimal unsigned big-endian encoding of the curve
  56  * subgroup order.
  57  *
  58  * Conversion of a "raw" format signature into "asn1" may enlarge a
  59  * signature by no more than 9 bytes for all supported curves.
  60  */
  61
  62 /*
  63  * Standard curve ID. These ID are equal to the assigned numerical
  64  * identifiers assigned to these curves for TLS:
  65  *    http://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8
  66  */
  67 #define BR_EC_sect163k1           1
  68 #define BR_EC_sect163r1           2
  69 #define BR_EC_sect163r2           3
  70 #define BR_EC_sect193r1           4
  71 #define BR_EC_sect193r2           5
  72 #define BR_EC_sect233k1           6
  73 #define BR_EC_sect233r1           7
  74 #define BR_EC_sect239k1           8
  75 #define BR_EC_sect283k1           9
  76 #define BR_EC_sect283r1          10
  77 #define BR_EC_sect409k1          11
  78 #define BR_EC_sect409r1          12
  79 #define BR_EC_sect571k1          13
  80 #define BR_EC_sect571r1          14
  81 #define BR_EC_secp160k1          15
  82 #define BR_EC_secp160r1          16
  83 #define BR_EC_secp160r2          17
  84 #define BR_EC_secp192k1          18
  85 #define BR_EC_secp192r1          19
  86 #define BR_EC_secp224k1          20
  87 #define BR_EC_secp224r1          21
  88 #define BR_EC_secp256k1          22
  89 #define BR_EC_secp256r1          23
  90 #define BR_EC_secp384r1          24
  91 #define BR_EC_secp521r1          25
  92 #define BR_EC_brainpoolP256r1    26
  93 #define BR_EC_brainpoolP384r1    27
  94 #define BR_EC_brainpoolP512r1    28
  95
  96 /*
  97  * Structure for an EC public key.
  98  */
  99 typedef struct {
 100         int curve;
 101         unsigned char *q;
 102         size_t qlen;
 103 } br_ec_public_key;
 104
 105 /*
 106  * Structure for an EC private key.
 107  */
 108 typedef struct {
 109         int curve;
 110         unsigned char *x;
 111         size_t xlen;
 112 } br_ec_private_key;
 113
 114 /*
 115  * Type for an EC implementation.
 116  *
 117  *  supported_curves
 118  *     Bit mask for supported curves: if curve 'id' is supported, then
 119  *     bit '1 << id' is set.
 120  *
 121  *  generator
 122  *     Get a pointer to the conventional generator for a given curve.
 123  *
 124  *  order
 125  *     Get a pointer to the curve order (minimal unsigned big-endian
 126  *     encoding).
 127  *
 128  *  mul
 129  *     Compute x*G. Provided point G (encoded size Glen) must be valid and
 130  *     distinct from the point at infinity. 'x' must be non-zero and less
 131  *     than the curve order. On error, 0 is returned; an invalid G (or
 132  *     point at infinity) is always detected, as well as a case of x = 0.
 133  *     However, if x is a non-zero multiple of the curve order, then it is
 134  *     not guaranteed that an error is reported.
 135  *
 136  *  muladd
 137  *     compute x*A+y*B, result being written over A. Points and multipliers
 138  *     must fulfill the same conditions as for mul().
 139  */
 140 typedef struct {
 141         uint32_t supported_curves;
 142         const unsigned char *(*generator)(int curve, size_t *len);
 143         const unsigned char *(*order)(int curve, size_t *len);
 144         uint32_t (*mul)(unsigned char *G, size_t Glen,
 145                 const unsigned char *x, size_t xlen, int curve);
 146         uint32_t (*muladd)(unsigned char *A, const unsigned char *B, size_t len,
 147                 const unsigned char *x, size_t xlen,
 148                 const unsigned char *y, size_t ylen, int curve);
 149 } br_ec_impl;
 150
 151 /*
 152  * The 'i31' implementation for elliptic curves. It supports secp256r1,
 153  * secp384r1 and secp521r1 (aka NIST curves P-256, P-384 and P-521).
 154  */
 155 extern const br_ec_impl br_ec_prime_i31;
 156
 157 /*
 158  * Convert a signature from "raw" to "asn1". Conversion is done "in
 159  * place" and the new length is returned. Conversion may enlarge the
 160  * signature, but by no more than 9 bytes at most. On error, 0 is
 161  * returned (error conditions include an odd raw signature length, or an
 162  * oversized integer).
 163  */
 164 size_t br_ecdsa_raw_to_asn1(void *sig, size_t sig_len);
 165
 166 /*
 167  * Convert a signature from "asn1" to "raw". Conversion is done "in
 168  * place" and the new length is returned. Conversion in that direction
 169  * always reduced signature length. On error, 0 is returned (error
 170  * conditions include an invalid signature format or an oversized
 171  * integer).
 172  */
 173 size_t br_ecdsa_asn1_to_raw(void *sig, size_t sig_len);
 174
 175 /*
 176  * Type for an ECDSA signer function. A pointer to the EC implementation
 177  * is provided. The hash value is assumed to have the length inferred
 178  * from the designated hash function class.
 179  *
 180  * Signature is written in the buffer pointed to by 'sig', and the length
 181  * (in bytes) is returned. On error, nothing is written in the buffer,
 182  * and 0 is returned.
 183  *
 184  * The signature format is either "raw" or "asn1", depending on the
 185  * implementation; maximum length is predictable from the implemented
 186  * curve:
 187  *
 188  *   curve        raw   asn1
 189  *   NIST P-256    64     72
 190  *   NIST P-384    96    104
 191  *   NIST P-521   132    139
 192  */
 193 typedef size_t (*br_ecdsa_sign)(const br_ec_impl *impl,
 194         const br_hash_class *hf, const void *hash_value,
 195         const br_ec_private_key *sk, void *sig);
 196
 197 /*
 198  * Verify ECDSA signature. Returned value is 1 on success, 0 on error.
 199  */
 200 typedef uint32_t (*br_ecdsa_vrfy)(const br_ec_impl *impl,
 201         const void *hash, size_t hash_len,
 202         const br_ec_public_key *pk, const void *sig, size_t sig_len);
 203
 204 /*
 205  * ECDSA implementation using the "i31" integers.
 206  */
 207 size_t br_ecdsa_i31_sign_asn1(const br_ec_impl *impl,
 208         const br_hash_class *hf, const void *hash_value,
 209         const br_ec_private_key *sk, void *sig);
 210 size_t br_ecdsa_i31_sign_raw(const br_ec_impl *impl,
 211         const br_hash_class *hf, const void *hash_value,
 212         const br_ec_private_key *sk, void *sig);
 213 uint32_t br_ecdsa_i31_vrfy_asn1(const br_ec_impl *impl,
 214         const void *hash, size_t hash_len,
 215         const br_ec_public_key *pk, const void *sig, size_t sig_len);
 216 uint32_t br_ecdsa_i31_vrfy_raw(const br_ec_impl *impl,
 217         const void *hash, size_t hash_len,
 218         const br_ec_public_key *pk, const void *sig, size_t sig_len);
 219
 220 #endif