Added support for getrandom()/getentropy(), and a fix for the RDRAND bug on AMD CPU...

[BearSSL] / inc / bearssl_ec.h

diff --git a/inc/bearssl_ec.h b/inc/bearssl_ec.h
index 69ad29e..f954309 100644 (file)
--- a/inc/bearssl_ec.h
+++ b/inc/bearssl_ec.h
@@ -28,6 +28,12 @@
 #include <stddef.h>
 #include <stdint.h>
 
 #include <stddef.h>
 #include <stdint.h>
 

+#include "bearssl_rand.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+

 /** \file bearssl_ec.h
  *
  * # Elliptic Curves
 /** \file bearssl_ec.h
  *
  * # Elliptic Curves


@@ -65,10 +71,20 @@
  *      Callback method that returns a pointer to the subgroup order for
  *      that curve. That value uses unsigned big-endian encoding.
  *
  *      Callback method that returns a pointer to the subgroup order for
  *      that curve. That value uses unsigned big-endian encoding.
  *

+ *   - `xoff()`
+ *
+ *      Callback method that returns the offset and length of the X
+ *      coordinate in an encoded point.
+ *

  *   - `mul()`
  *
  *      Multiply a curve point with an integer.
  *
  *   - `mul()`
  *
  *      Multiply a curve point with an integer.
  *

+ *   - `mulgen()`
+ *
+ *      Multiply the curve generator with an integer. This may be faster
+ *      than the generic `mul()`.
+ *

  *   - `muladd()`
  *
  *      Multiply two curve points by two integers, and return the sum of
  *   - `muladd()`
  *
  *      Multiply two curve points by two integers, and return the sum of


@@ -213,6 +229,12 @@
 /** \brief Identifier for named curve brainpoolP512r1. */
 #define BR_EC_brainpoolP512r1    28
 
 /** \brief Identifier for named curve brainpoolP512r1. */
 #define BR_EC_brainpoolP512r1    28
 

+/** \brief Identifier for named curve Curve25519. */
+#define BR_EC_curve25519         29
+
+/** \brief Identifier for named curve Curve448. */
+#define BR_EC_curve448           30
+

 /**
  * \brief Structure for an EC public key.
  */
 /**
  * \brief Structure for an EC public key.
  */


@@ -283,6 +305,18 @@ typedef struct {
         */
        const unsigned char *(*order)(int curve, size_t *len);
 
         */
        const unsigned char *(*order)(int curve, size_t *len);
 

+       /**
+        * \brief Get the offset and length for the X coordinate.
+        *
+        * This function returns the offset and length (in bytes) of
+        * the X coordinate in an encoded non-zero point.
+        *
+        * \param curve   curve identifier.
+        * \param len     receiver for the X coordinate length (in bytes).
+        * \return  the offset for the X coordinate (in bytes).
+        */
+       size_t (*xoff)(int curve, size_t *len);
+

        /**
         * \brief Multiply a curve point by an integer.
         *
        /**
         * \brief Multiply a curve point by an integer.
         *


@@ -299,10 +333,9 @@ typedef struct {
         *     not the case, then this function returns an error (0).
         *
         *   - The multiplier integer MUST be non-zero and less than the
         *     not the case, then this function returns an error (0).
         *
         *   - The multiplier integer MUST be non-zero and less than the

-        *     curve subgroup order. If the integer is zero, then an
-        *     error is reported, but if the integer is not lower than
-        *     the subgroup order, then the result is indeterminate and an
-        *     error code is not guaranteed.
+        *     curve subgroup order. If this property does not hold, then
+        *     the result is indeterminate and an error code is not
+        *     guaranteed.

         *
         * Returned value is 1 on success, 0 on error. On error, the
         * contents of `G` are indeterminate.
         *
         * Returned value is 1 on success, 0 on error. On error, the
         * contents of `G` are indeterminate.


@@ -317,6 +350,22 @@ typedef struct {
        uint32_t (*mul)(unsigned char *G, size_t Glen,
                const unsigned char *x, size_t xlen, int curve);
 
        uint32_t (*mul)(unsigned char *G, size_t Glen,
                const unsigned char *x, size_t xlen, int curve);
 

+       /**
+        * \brief Multiply the generator by an integer.
+        *
+        * The multiplier MUST be non-zero and less than the curve
+        * subgroup order. Results are indeterminate if this property
+        * does not hold.
+        *
+        * \param R       output buffer for the point.
+        * \param x       multiplier (unsigned big-endian).
+        * \param xlen    multiplier length (in bytes).
+        * \param curve   curve identifier.
+        * \return  encoded result point length (in bytes).
+        */
+       size_t (*mulgen)(unsigned char *R,
+               const unsigned char *x, size_t xlen, int curve);
+

        /**
         * \brief Multiply two points by two integers and add the
         * results.
        /**
         * \brief Multiply two points by two integers and add the
         * results.


@@ -333,6 +382,11 @@ typedef struct {
         *     infinity" either). If this is not the case, then this
         *     function returns an error (0).
         *
         *     infinity" either). If this is not the case, then this
         *     function returns an error (0).
         *

+        *   - If the `B` pointer is `NULL`, then the conventional
+        *     subgroup generator is used. With some implementations,
+        *     this may be faster than providing a pointer to the
+        *     generator.
+        *

         *   - The multiplier integers (`x` and `y`) MUST be non-zero
         *     and less than the curve subgroup order. If either integer
         *     is zero, then an error is reported, but if one of them is
         *   - The multiplier integers (`x` and `y`) MUST be non-zero
         *     and less than the curve subgroup order. If either integer
         *     is zero, then an error is reported, but if one of them is


@@ -346,7 +400,7 @@ typedef struct {
         * contents of `A` are indeterminate.
         *
         * \param A       first point to multiply.
         * contents of `A` are indeterminate.
         *
         * \param A       first point to multiply.

-        * \param B       second point to multiply.
+        * \param B       second point to multiply (`NULL` for the generator).

         * \param len     common length of the encoded points (in bytes).
         * \param x       multiplier for `A` (unsigned big-endian).
         * \param xlen    length of multiplier for `A` (in bytes).
         * \param len     common length of the encoded points (in bytes).
         * \param x       multiplier for `A` (unsigned big-endian).
         * \param xlen    length of multiplier for `A` (in bytes).


@@ -379,14 +433,195 @@ extern const br_ec_impl br_ec_prime_i31;
 extern const br_ec_impl br_ec_prime_i15;
 
 /**
 extern const br_ec_impl br_ec_prime_i15;
 
 /**

- * \brief EC implementation "i15" for P-256.
+ * \brief EC implementation "m15" for P-256.

  *
  * This implementation uses specialised code for curve secp256r1 (also
  *
  * This implementation uses specialised code for curve secp256r1 (also

- * known as NIST P-256), with Karatsuba decomposition, and fast modular
- * reduction thanks to the field modulus special format. Only 32-bit
- * multiplications are used (with 32-bit results, not 64-bit).
+ * known as NIST P-256), with optional Karatsuba decomposition, and fast
+ * modular reduction thanks to the field modulus special format. Only
+ * 32-bit multiplications are used (with 32-bit results, not 64-bit).
+ */
+extern const br_ec_impl br_ec_p256_m15;
+
+/**
+ * \brief EC implementation "m31" for P-256.
+ *
+ * This implementation uses specialised code for curve secp256r1 (also
+ * known as NIST P-256), relying on multiplications of 31-bit values
+ * (MUL31).
+ */
+extern const br_ec_impl br_ec_p256_m31;
+
+/**
+ * \brief EC implementation "m62" (specialised code) for P-256.
+ *
+ * This implementation uses custom code relying on multiplication of
+ * integers up to 64 bits, with a 128-bit result. This implementation is
+ * defined only on platforms that offer the 64x64->128 multiplication
+ * support; use `br_ec_p256_m62_get()` to dynamically obtain a pointer
+ * to that implementation.
+ */
+extern const br_ec_impl br_ec_p256_m62;
+
+/**
+ * \brief Get the "m62" implementation of P-256, if available.
+ *
+ * \return  the implementation, or 0.
+ */
+const br_ec_impl *br_ec_p256_m62_get(void);
+
+/**
+ * \brief EC implementation "m64" (specialised code) for P-256.
+ *
+ * This implementation uses custom code relying on multiplication of
+ * integers up to 64 bits, with a 128-bit result. This implementation is
+ * defined only on platforms that offer the 64x64->128 multiplication
+ * support; use `br_ec_p256_m64_get()` to dynamically obtain a pointer
+ * to that implementation.
+ */
+extern const br_ec_impl br_ec_p256_m64;
+
+/**
+ * \brief Get the "m64" implementation of P-256, if available.
+ *
+ * \return  the implementation, or 0.
+ */
+const br_ec_impl *br_ec_p256_m64_get(void);
+
+/**
+ * \brief EC implementation "i15" (generic code) for Curve25519.
+ *
+ * This implementation uses the generic code for modular integers (with
+ * 15-bit words) to support Curve25519. Due to the specificities of the
+ * curve definition, the following applies:
+ *
+ *   - `muladd()` is not implemented (the function returns 0 systematically).
+ *   - `order()` returns 2^255-1, since the point multiplication algorithm
+ *     accepts any 32-bit integer as input (it clears the top bit and low
+ *     three bits systematically).
+ */
+extern const br_ec_impl br_ec_c25519_i15;
+
+/**
+ * \brief EC implementation "i31" (generic code) for Curve25519.
+ *
+ * This implementation uses the generic code for modular integers (with
+ * 31-bit words) to support Curve25519. Due to the specificities of the
+ * curve definition, the following applies:
+ *
+ *   - `muladd()` is not implemented (the function returns 0 systematically).
+ *   - `order()` returns 2^255-1, since the point multiplication algorithm
+ *     accepts any 32-bit integer as input (it clears the top bit and low
+ *     three bits systematically).
+ */
+extern const br_ec_impl br_ec_c25519_i31;
+
+/**
+ * \brief EC implementation "m15" (specialised code) for Curve25519.
+ *
+ * This implementation uses custom code relying on multiplication of
+ * integers up to 15 bits. Due to the specificities of the curve
+ * definition, the following applies:
+ *
+ *   - `muladd()` is not implemented (the function returns 0 systematically).
+ *   - `order()` returns 2^255-1, since the point multiplication algorithm
+ *     accepts any 32-bit integer as input (it clears the top bit and low
+ *     three bits systematically).
+ */
+extern const br_ec_impl br_ec_c25519_m15;
+
+/**
+ * \brief EC implementation "m31" (specialised code) for Curve25519.
+ *
+ * This implementation uses custom code relying on multiplication of
+ * integers up to 31 bits. Due to the specificities of the curve
+ * definition, the following applies:
+ *
+ *   - `muladd()` is not implemented (the function returns 0 systematically).
+ *   - `order()` returns 2^255-1, since the point multiplication algorithm
+ *     accepts any 32-bit integer as input (it clears the top bit and low
+ *     three bits systematically).
+ */
+extern const br_ec_impl br_ec_c25519_m31;
+
+/**
+ * \brief EC implementation "m62" (specialised code) for Curve25519.
+ *
+ * This implementation uses custom code relying on multiplication of
+ * integers up to 62 bits, with a 124-bit result. This implementation is
+ * defined only on platforms that offer the 64x64->128 multiplication
+ * support; use `br_ec_c25519_m62_get()` to dynamically obtain a pointer
+ * to that implementation. Due to the specificities of the curve
+ * definition, the following applies:
+ *
+ *   - `muladd()` is not implemented (the function returns 0 systematically).
+ *   - `order()` returns 2^255-1, since the point multiplication algorithm
+ *     accepts any 32-bit integer as input (it clears the top bit and low
+ *     three bits systematically).

  */
  */

-extern const br_ec_impl br_ec_p256_i15;
+extern const br_ec_impl br_ec_c25519_m62;
+
+/**
+ * \brief Get the "m62" implementation of Curve25519, if available.
+ *
+ * \return  the implementation, or 0.
+ */
+const br_ec_impl *br_ec_c25519_m62_get(void);
+
+/**
+ * \brief EC implementation "m64" (specialised code) for Curve25519.
+ *
+ * This implementation uses custom code relying on multiplication of
+ * integers up to 64 bits, with a 128-bit result. This implementation is
+ * defined only on platforms that offer the 64x64->128 multiplication
+ * support; use `br_ec_c25519_m64_get()` to dynamically obtain a pointer
+ * to that implementation. Due to the specificities of the curve
+ * definition, the following applies:
+ *
+ *   - `muladd()` is not implemented (the function returns 0 systematically).
+ *   - `order()` returns 2^255-1, since the point multiplication algorithm
+ *     accepts any 32-bit integer as input (it clears the top bit and low
+ *     three bits systematically).
+ */
+extern const br_ec_impl br_ec_c25519_m64;
+
+/**
+ * \brief Get the "m64" implementation of Curve25519, if available.
+ *
+ * \return  the implementation, or 0.
+ */
+const br_ec_impl *br_ec_c25519_m64_get(void);
+
+/**
+ * \brief Aggregate EC implementation "m15".
+ *
+ * This implementation is a wrapper for:
+ *
+ *   - `br_ec_c25519_m15` for Curve25519
+ *   - `br_ec_p256_m15` for NIST P-256
+ *   - `br_ec_prime_i15` for other curves (NIST P-384 and NIST-P512)
+ */
+extern const br_ec_impl br_ec_all_m15;
+
+/**
+ * \brief Aggregate EC implementation "m31".
+ *
+ * This implementation is a wrapper for:
+ *
+ *   - `br_ec_c25519_m31` for Curve25519
+ *   - `br_ec_p256_m31` for NIST P-256
+ *   - `br_ec_prime_i31` for other curves (NIST P-384 and NIST-P512)
+ */
+extern const br_ec_impl br_ec_all_m31;
+
+/**
+ * \brief Get the "default" EC implementation for the current system.
+ *
+ * This returns a pointer to the preferred implementation on the
+ * current system.
+ *
+ * \return  the default EC implementation.
+ */
+const br_ec_impl *br_ec_get_default(void);

 
 /**
  * \brief Convert a signature from "raw" to "asn1".
 
 /**
  * \brief Convert a signature from "raw" to "asn1".


@@ -608,4 +843,125 @@ uint32_t br_ecdsa_i15_vrfy_raw(const br_ec_impl *impl,
        const void *hash, size_t hash_len,
        const br_ec_public_key *pk, const void *sig, size_t sig_len);
 
        const void *hash, size_t hash_len,
        const br_ec_public_key *pk, const void *sig, size_t sig_len);
 

+/**
+ * \brief Get "default" ECDSA implementation (signer, asn1 format).
+ *
+ * This returns the preferred implementation of ECDSA signature generation
+ * ("asn1" output format) on the current system.
+ *
+ * \return  the default implementation.
+ */
+br_ecdsa_sign br_ecdsa_sign_asn1_get_default(void);
+
+/**
+ * \brief Get "default" ECDSA implementation (signer, raw format).
+ *
+ * This returns the preferred implementation of ECDSA signature generation
+ * ("raw" output format) on the current system.
+ *
+ * \return  the default implementation.
+ */
+br_ecdsa_sign br_ecdsa_sign_raw_get_default(void);
+
+/**
+ * \brief Get "default" ECDSA implementation (verifier, asn1 format).
+ *
+ * This returns the preferred implementation of ECDSA signature verification
+ * ("asn1" output format) on the current system.
+ *
+ * \return  the default implementation.
+ */
+br_ecdsa_vrfy br_ecdsa_vrfy_asn1_get_default(void);
+
+/**
+ * \brief Get "default" ECDSA implementation (verifier, raw format).
+ *
+ * This returns the preferred implementation of ECDSA signature verification
+ * ("raw" output format) on the current system.
+ *
+ * \return  the default implementation.
+ */
+br_ecdsa_vrfy br_ecdsa_vrfy_raw_get_default(void);
+
+/**
+ * \brief Maximum size for EC private key element buffer.
+ *
+ * This is the largest number of bytes that `br_ec_keygen()` may need or
+ * ever return.
+ */
+#define BR_EC_KBUF_PRIV_MAX_SIZE   72
+
+/**
+ * \brief Maximum size for EC public key element buffer.
+ *
+ * This is the largest number of bytes that `br_ec_compute_public()` may
+ * need or ever return.
+ */
+#define BR_EC_KBUF_PUB_MAX_SIZE    145
+
+/**
+ * \brief Generate a new EC private key.
+ *
+ * If the specified `curve` is not supported by the elliptic curve
+ * implementation (`impl`), then this function returns zero.
+ *
+ * The `sk` structure fields are set to the new private key data. In
+ * particular, `sk.x` is made to point to the provided key buffer (`kbuf`),
+ * in which the actual private key data is written. That buffer is assumed
+ * to be large enough. The `BR_EC_KBUF_PRIV_MAX_SIZE` defines the maximum
+ * size for all supported curves.
+ *
+ * The number of bytes used in `kbuf` is returned. If `kbuf` is `NULL`, then
+ * the private key is not actually generated, and `sk` may also be `NULL`;
+ * the minimum length for `kbuf` is still computed and returned.
+ *
+ * If `sk` is `NULL` but `kbuf` is not `NULL`, then the private key is
+ * still generated and stored in `kbuf`.
+ *
+ * \param rng_ctx   source PRNG context (already initialized).
+ * \param impl      the elliptic curve implementation.
+ * \param sk        the private key structure to fill, or `NULL`.
+ * \param kbuf      the key element buffer, or `NULL`.
+ * \param curve     the curve identifier.
+ * \return  the key data length (in bytes), or zero.
+ */
+size_t br_ec_keygen(const br_prng_class **rng_ctx,
+       const br_ec_impl *impl, br_ec_private_key *sk,
+       void *kbuf, int curve);
+
+/**
+ * \brief Compute EC public key from EC private key.
+ *
+ * This function uses the provided elliptic curve implementation (`impl`)
+ * to compute the public key corresponding to the private key held in `sk`.
+ * The public key point is written into `kbuf`, which is then linked from
+ * the `*pk` structure. The size of the public key point, i.e. the number
+ * of bytes used in `kbuf`, is returned.
+ *
+ * If `kbuf` is `NULL`, then the public key point is NOT computed, and
+ * the public key structure `*pk` is unmodified (`pk` may be `NULL` in
+ * that case). The size of the public key point is still returned.
+ *
+ * If `pk` is `NULL` but `kbuf` is not `NULL`, then the public key
+ * point is computed and stored in `kbuf`, and its size is returned.
+ *
+ * If the curve used by the private key is not supported by the curve
+ * implementation, then this function returns zero.
+ *
+ * The private key MUST be valid. An off-range private key value is not
+ * necessarily detected, and leads to unpredictable results.
+ *
+ * \param impl   the elliptic curve implementation.
+ * \param pk     the public key structure to fill (or `NULL`).
+ * \param kbuf   the public key point buffer (or `NULL`).
+ * \param sk     the source private key.
+ * \return  the public key point length (in bytes), or zero.
+ */
+size_t br_ec_compute_pub(const br_ec_impl *impl, br_ec_public_key *pk,
+       void *kbuf, const br_ec_private_key *sk);
+
+#ifdef __cplusplus
+}
+#endif
+

 #endif
 #endif