X-Git-Url: https://www.bearssl.org/gitweb//home/git/?p=BearSSL;a=blobdiff_plain;f=inc%2Fbearssl_ec.h;h=50225300629b4c255aed05c60a69d64d1e32e407;hp=336c89c4f9e145b5e0587a0a4a8b6157e21701da;hb=bd3036844bd20b2b8d7bce7fee5ad010ce401915;hpb=6dd8c51ba7e8ca106ede7ff58b5c507042bbf6eb;ds=sidebyside diff --git a/inc/bearssl_ec.h b/inc/bearssl_ec.h index 336c89c..5022530 100644 --- a/inc/bearssl_ec.h +++ b/inc/bearssl_ec.h @@ -65,10 +65,20 @@ * 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. * + * - `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 @@ -213,6 +223,12 @@ /** \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. */ @@ -283,6 +299,18 @@ typedef struct { */ 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. * @@ -299,10 +327,9 @@ typedef struct { * 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. @@ -317,6 +344,22 @@ typedef struct { 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. @@ -333,6 +376,11 @@ typedef struct { * 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 @@ -346,7 +394,7 @@ typedef struct { * 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). @@ -370,14 +418,99 @@ typedef struct { extern const br_ec_impl br_ec_prime_i31; /** - * \brief EC implementation "i15" for P-256. + * \brief EC implementation "i15". + * + * This implementation internally uses generic code for modular integers, + * with a representation as sequences of 15-bit words. It supports secp256r1, + * secp384r1 and secp521r1 (aka NIST curves P-256, P-384 and P-521). + */ +extern const br_ec_impl br_ec_prime_i15; + +/** + * \brief EC implementation "m15" for P-256. + * + * This implementation uses specialised code for curve secp256r1 (also + * 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), 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), relying on multiplications of 31-bit values + * (MUL31). + */ +extern const br_ec_impl br_ec_p256_m31; + +/** + * \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 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_p256_i15; +extern const br_ec_impl br_ec_all_m15; /** * \brief Convert a signature from "raw" to "asn1". @@ -533,4 +666,70 @@ uint32_t br_ecdsa_i31_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); +/** + * \brief ECDSA signature generator, "i15" implementation, "asn1" format. + * + * \see br_ecdsa_sign() + * + * \param impl EC implementation to use. + * \param hf hash function used to process the data. + * \param hash_value signed data (hashed). + * \param sk EC private key. + * \param sig destination buffer. + * \return the signature length (in bytes), or 0 on error. + */ +size_t br_ecdsa_i15_sign_asn1(const br_ec_impl *impl, + const br_hash_class *hf, const void *hash_value, + const br_ec_private_key *sk, void *sig); + +/** + * \brief ECDSA signature generator, "i15" implementation, "raw" format. + * + * \see br_ecdsa_sign() + * + * \param impl EC implementation to use. + * \param hf hash function used to process the data. + * \param hash_value signed data (hashed). + * \param sk EC private key. + * \param sig destination buffer. + * \return the signature length (in bytes), or 0 on error. + */ +size_t br_ecdsa_i15_sign_raw(const br_ec_impl *impl, + const br_hash_class *hf, const void *hash_value, + const br_ec_private_key *sk, void *sig); + +/** + * \brief ECDSA signature verifier, "i15" implementation, "asn1" format. + * + * \see br_ecdsa_vrfy() + * + * \param impl EC implementation to use. + * \param hash signed data (hashed). + * \param hash_len hash value length (in bytes). + * \param pk EC public key. + * \param sig signature. + * \param sig_len signature length (in bytes). + * \return 1 on success, 0 on error. + */ +uint32_t br_ecdsa_i15_vrfy_asn1(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); + +/** + * \brief ECDSA signature verifier, "i15" implementation, "raw" format. + * + * \see br_ecdsa_vrfy() + * + * \param impl EC implementation to use. + * \param hash signed data (hashed). + * \param hash_len hash value length (in bytes). + * \param pk EC public key. + * \param sig signature. + * \param sig_len signature length (in bytes). + * \return 1 on success, 0 on error. + */ +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); + #endif