BearSSL

Data Structures | Macros | Typedefs | Functions | Variables
bearssl_ec.h File Reference
Include dependency graph for bearssl_ec.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures
struct | br_ec_public_key
| Structure for an EC public key. More...
struct | br_ec_private_key
| Structure for an EC private key. More...
struct | br_ec_impl
| Type for an EC implementation. More...

## Macros
#define | BR_EC_sect163k1 1
| Identifier for named curve sect163k1. More...
#define | BR_EC_sect163r1 2
| Identifier for named curve sect163r1. More...
#define | BR_EC_sect163r2 3
| Identifier for named curve sect163r2. More...
#define | BR_EC_sect193r1 4
| Identifier for named curve sect193r1. More...
#define | BR_EC_sect193r2 5
| Identifier for named curve sect193r2. More...
#define | BR_EC_sect233k1 6
| Identifier for named curve sect233k1. More...
#define | BR_EC_sect233r1 7
| Identifier for named curve sect233r1. More...
#define | BR_EC_sect239k1 8
| Identifier for named curve sect239k1. More...
#define | BR_EC_sect283k1 9
| Identifier for named curve sect283k1. More...
#define | BR_EC_sect283r1 10
| Identifier for named curve sect283r1. More...
#define | BR_EC_sect409k1 11
| Identifier for named curve sect409k1. More...
#define | BR_EC_sect409r1 12
| Identifier for named curve sect409r1. More...
#define | BR_EC_sect571k1 13
| Identifier for named curve sect571k1. More...
#define | BR_EC_sect571r1 14
| Identifier for named curve sect571r1. More...
#define | BR_EC_secp160k1 15
| Identifier for named curve secp160k1. More...
#define | BR_EC_secp160r1 16
| Identifier for named curve secp160r1. More...
#define | BR_EC_secp160r2 17
| Identifier for named curve secp160r2. More...
#define | BR_EC_secp192k1 18
| Identifier for named curve secp192k1. More...
#define | BR_EC_secp192r1 19
| Identifier for named curve secp192r1. More...
#define | BR_EC_secp224k1 20
| Identifier for named curve secp224k1. More...
#define | BR_EC_secp224r1 21
| Identifier for named curve secp224r1. More...
#define | BR_EC_secp256k1 22
| Identifier for named curve secp256k1. More...
#define | BR_EC_secp256r1 23
| Identifier for named curve secp256r1. More...
#define | BR_EC_secp384r1 24
| Identifier for named curve secp384r1. More...
#define | BR_EC_secp521r1 25
| Identifier for named curve secp521r1. More...
#define | BR_EC_brainpoolP256r1 26
| Identifier for named curve brainpoolP256r1. More...
#define | BR_EC_brainpoolP384r1 27
| Identifier for named curve brainpoolP384r1. More...
#define | BR_EC_brainpoolP512r1 28
| Identifier for named curve brainpoolP512r1. More...
#define | BR_EC_curve25519 29
| Identifier for named curve Curve25519. More...
#define | BR_EC_curve448 30
| Identifier for named curve Curve448. More...
#define | BR_EC_KBUF_PRIV_MAX_SIZE 72
| Maximum size for EC private key element buffer. More...
#define | BR_EC_KBUF_PUB_MAX_SIZE 145
| Maximum size for EC public key element buffer. More...

## Typedefs
typedef size_t(* | br_ecdsa_sign) (const br_ec_impl *impl, const br_hash_class *hf, const void *hash_value, const br_ec_private_key *sk, void *sig)
| Type for an ECDSA signer function. More...
typedef uint32_t(* | br_ecdsa_vrfy) (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)
| Type for an ECDSA signature verification function. More...

## Functions
const br_ec_impl * | br_ec_get_default (void)
| Get the "default" EC implementation for the current system. More...
size_t | br_ecdsa_raw_to_asn1 (void *sig, size_t sig_len)
| Convert a signature from "raw" to "asn1". More...
size_t | br_ecdsa_asn1_to_raw (void *sig, size_t sig_len)
| Convert a signature from "asn1" to "raw". More...
size_t | br_ecdsa_i31_sign_asn1 (const br_ec_impl *impl, const br_hash_class *hf, const void *hash_value, const br_ec_private_key *sk, void *sig)
| ECDSA signature generator, "i31" implementation, "asn1" format. More...
size_t | br_ecdsa_i31_sign_raw (const br_ec_impl *impl, const br_hash_class *hf, const void *hash_value, const br_ec_private_key *sk, void *sig)
| ECDSA signature generator, "i31" implementation, "raw" format. More...
uint32_t | br_ecdsa_i31_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)
| ECDSA signature verifier, "i31" implementation, "asn1" format. More...
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)
| ECDSA signature verifier, "i31" implementation, "raw" format. More...
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)
| ECDSA signature generator, "i15" implementation, "asn1" format. More...
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)
| ECDSA signature generator, "i15" implementation, "raw" format. More...
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)
| ECDSA signature verifier, "i15" implementation, "asn1" format. More...
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)
| ECDSA signature verifier, "i15" implementation, "raw" format. More...
br_ecdsa_sign | br_ecdsa_sign_asn1_get_default (void)
| Get "default" ECDSA implementation (signer, asn1 format). More...
br_ecdsa_sign | br_ecdsa_sign_raw_get_default (void)
| Get "default" ECDSA implementation (signer, raw format). More...
br_ecdsa_vrfy | br_ecdsa_vrfy_asn1_get_default (void)
| Get "default" ECDSA implementation (verifier, asn1 format). More...
br_ecdsa_vrfy | br_ecdsa_vrfy_raw_get_default (void)
| Get "default" ECDSA implementation (verifier, raw format). More...
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)
| Generate a new EC private key. More...
size_t | br_ec_compute_pub (const br_ec_impl *impl, br_ec_public_key *pk, void *kbuf, const br_ec_private_key *sk)
| Compute EC public key from EC private key. More...

## Variables
const br_ec_impl | br_ec_prime_i31
| EC implementation "i31". More...
const br_ec_impl | br_ec_prime_i15
| EC implementation "i15". More...
const br_ec_impl | br_ec_p256_m15
| EC implementation "m15" for P-256. More...
const br_ec_impl | br_ec_p256_m31
| EC implementation "m31" for P-256. More...
const br_ec_impl | br_ec_c25519_i15
| EC implementation "i15" (generic code) for Curve25519. More...
const br_ec_impl | br_ec_c25519_i31
| EC implementation "i31" (generic code) for Curve25519. More...
const br_ec_impl | br_ec_c25519_m15
| EC implementation "m15" (specialised code) for Curve25519. More...
const br_ec_impl | br_ec_c25519_m31
| EC implementation "m31" (specialised code) for Curve25519. More...
const br_ec_impl | br_ec_all_m15
| Aggregate EC implementation "m15". More...
const br_ec_impl | br_ec_all_m31
| Aggregate EC implementation "m31". More...

## Detailed Description

# Elliptic Curves

This file documents the EC implementations provided with BearSSL, and ECDSA.

## Elliptic Curve API

Only "named curves" are supported. Each EC implementation supports one or several named curves, identified by symbolic identifiers. These identifiers are small integers, that correspond to the values registered by the IANA.

Since all currently defined elliptic curve identifiers are in the 0..31 range, it is convenient to encode support of some curves in a 32-bit word, such that bit x corresponds to curve of identifier x.

An EC implementation is incarnated by a `br_ec_impl` instance, that offers the following fields:

- `supported_curves`

  A 32-bit word that documents the identifiers of the curves supported by this implementation.

- `generator()`

  Callback method that returns a pointer to the conventional generator point for that curve.

- `order()`

  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 the two products.

All curve points are represented in uncompressed format. The `mul()` and `muladd()` methods take care to validate that the provided points are really part of the relevant curve subgroup.

For all point multiplication functions, the following holds:

- Functions validate that the provided points are valid members of the relevant curve subgroup. An error is reported if that is not the case.
- Processing is constant-time, even if the point operands are not valid. This holds for both the source and resulting points, and the multipliers (integers). Only the byte length of the provided multiplier arrays (not their actual value length in bits) may leak through timing-based side channels.
- The multipliers (integers) MUST be lower than the subgroup order. If this property is not met, then the result is indeterminate, but an error value is not ncessearily returned.

## ECDSA

ECDSA signatures have two standard formats, called "raw" and "asn1". Internally, such a signature is a pair of modular integers `(r,s)`. The "raw" format is the concatenation of the unsigned big-endian encodings of these two integers, possibly left-padded with zeros so that they have the same encoded length. The "asn1" format is the DER encoding of an ASN.1 structure that contains the two integer values:

    ECDSASignature ::= SEQUENCE {
        r   INTEGER,
        s   INTEGER
    }

In general, in all of X.509 and SSL/TLS, the "asn1" format is used. BearSSL offers ECDSA implementations for both formats; conversion functions between the two formats are also provided. Conversion of a "raw" format signature into "asn1" may enlarge a signature by no more than 9 bytes for all supported curves; conversely, conversion of an "asn1" signature to "raw" may expand the signature but the "raw" length will never be more than twice the length of the "asn1" length (and usually it will be shorter).

Note that for a given signature, the "raw" format is not fully deterministic, in that it does not enforce a minimal common length.

## Macro Definition Documentation

## ◆ BR_EC_brainpoolP256r1

#define BR_EC_brainpoolP256r1 26

Identifier for named curve brainpoolP256r1.

## ◆ BR_EC_brainpoolP384r1

#define BR_EC_brainpoolP384r1 27

Identifier for named curve brainpoolP384r1.

## ◆ BR_EC_brainpoolP512r1

#define BR_EC_brainpoolP512r1 28

Identifier for named curve brainpoolP512r1.

## ◆ BR_EC_curve25519

#define BR_EC_curve25519 29

Identifier for named curve Curve25519.

## ◆ BR_EC_curve448

#define BR_EC_curve448 30

Identifier for named curve Curve448.

## ◆ BR_EC_KBUF_PRIV_MAX_SIZE

#define BR_EC_KBUF_PRIV_MAX_SIZE 72

Maximum size for EC private key element buffer.

This is the largest number of bytes that `br_ec_keygen()` may need or ever return.

## ◆ BR_EC_KBUF_PUB_MAX_SIZE

#define BR_EC_KBUF_PUB_MAX_SIZE 145

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.

## ◆ BR_EC_secp160k1

#define BR_EC_secp160k1 15

Identifier for named curve secp160k1.

## ◆ BR_EC_secp160r1

#define BR_EC_secp160r1 16

Identifier for named curve secp160r1.

## ◆ BR_EC_secp160r2

#define BR_EC_secp160r2 17

Identifier for named curve secp160r2.

## ◆ BR_EC_secp192k1

#define BR_EC_secp192k1 18

Identifier for named curve secp192k1.

## ◆ BR_EC_secp192r1

#define BR_EC_secp192r1 19

Identifier for named curve secp192r1.

## ◆ BR_EC_secp224k1

#define BR_EC_secp224k1 20

Identifier for named curve secp224k1.

## ◆ BR_EC_secp224r1

#define BR_EC_secp224r1 21

Identifier for named curve secp224r1.

## ◆ BR_EC_secp256k1

#define BR_EC_secp256k1 22

Identifier for named curve secp256k1.

## ◆ BR_EC_secp256r1

#define BR_EC_secp256r1 23

Identifier for named curve secp256r1.

## ◆ BR_EC_secp384r1

#define BR_EC_secp384r1 24

Identifier for named curve secp384r1.

## ◆ BR_EC_secp521r1

#define BR_EC_secp521r1 25

Identifier for named curve secp521r1.

## ◆ BR_EC_sect163k1

#define BR_EC_sect163k1 1

Identifier for named curve sect163k1.

## ◆ BR_EC_sect163r1

#define BR_EC_sect163r1 2

Identifier for named curve sect163r1.

## ◆ BR_EC_sect163r2

#define BR_EC_sect163r2 3

Identifier for named curve sect163r2.

## ◆ BR_EC_sect193r1

#define BR_EC_sect193r1 4

Identifier for named curve sect193r1.

## ◆ BR_EC_sect193r2

#define BR_EC_sect193r2 5

Identifier for named curve sect193r2.

## ◆ BR_EC_sect233k1

#define BR_EC_sect233k1 6

Identifier for named curve sect233k1.

## ◆ BR_EC_sect233r1

#define BR_EC_sect233r1 7

Identifier for named curve sect233r1.

## ◆ BR_EC_sect239k1

#define BR_EC_sect239k1 8

Identifier for named curve sect239k1.

## ◆ BR_EC_sect283k1

#define BR_EC_sect283k1 9

Identifier for named curve sect283k1.

## ◆ BR_EC_sect283r1

#define BR_EC_sect283r1 10

Identifier for named curve sect283r1.

## ◆ BR_EC_sect409k1

#define BR_EC_sect409k1 11

Identifier for named curve sect409k1.

## ◆ BR_EC_sect409r1

#define BR_EC_sect409r1 12

Identifier for named curve sect409r1.

## ◆ BR_EC_sect571k1

#define BR_EC_sect571k1 13

Identifier for named curve sect571k1.

## ◆ BR_EC_sect571r1

#define BR_EC_sect571r1 14

Identifier for named curve sect571r1.

## Typedef Documentation

## ◆ br_ecdsa_sign

typedef size_t(* br_ecdsa_sign) (const br_ec_impl *impl, const br_hash_class *hf, const void *hash_value, const br_ec_private_key *sk, void *sig)

Type for an ECDSA signer function.

A pointer to the EC implementation is provided. The hash value is assumed to have the length inferred from the designated hash function class.

Signature is written in the buffer pointed to by `sig`, and the length (in bytes) is returned. On error, nothing is written in the buffer, and 0 is returned. This function returns 0 if the specified curve is not supported by the provided EC implementation.

The signature format is either "raw" or "asn1", depending on the implementation; maximum length is predictable from the implemented curve:

curve | raw | asn1
--- | --- | ---
NIST P-256 | 64 | 72
NIST P-384 | 96 | 104
NIST P-521 | 132 | 139

Parameters

  impl | EC implementation to use.
  hf | hash function used to process the data.
  hash_value | signed data (hashed).
  sk | EC private key.
  sig | destination buffer.

Returns
  the signature length (in bytes), or 0 on error.

## ◆ br_ecdsa_vrfy

typedef uint32_t(* br_ecdsa_vrfy) (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)

Type for an ECDSA signature verification function.

A pointer to the EC implementation is provided. The hashed value, computed over the purportedly signed data, is also provided with its length.

The signature format is either "raw" or "asn1", depending on the implementation.

Returned value is 1 on success (valid signature), 0 on error. This function returns 0 if the specified curve is not supported by the provided EC implementation.

Parameters

  impl | EC implementation to use.
  hash | signed data (hashed).
  hash_len | hash value length (in bytes).
  pk | EC public key.
  sig | signature.
  sig_len | signature length (in bytes).

Returns
  1 on success, 0 on error.

## Function Documentation

## ◆ br_ec_compute_pub()

size_t br_ec_compute_pub | ( | const br_ec_impl * | impl,
|  | br_ec_public_key * | pk,
|  | void * | kbuf,
|  | const br_ec_private_key * | sk
| ) |  |

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.

Parameters

  impl | the elliptic curve implementation.
  pk | the public key structure to fill (or `NULL`).
  kbuf | the public key point buffer (or `NULL`).
  sk | the source private key.

Returns
  the public key point length (in bytes), or zero.

## ◆ br_ec_get_default()

const br_ec_impl * br_ec_get_default | ( | void |  | ) |

Get the "default" EC implementation for the current system.

This returns a pointer to the preferred implementation on the current system.

Returns
  the default EC implementation.

## ◆ br_ec_keygen()

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
| ) |  |

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`.

Parameters

  rng_ctx | source PRNG context (already initialized).
  impl | the elliptic curve implementation.
  sk | the private key structure to fill, or `NULL`.
  kbuf | the key element buffer, or `NULL`.
  curve | the curve identifier.

Returns
  the key data length (in bytes), or zero.

## ◆ br_ecdsa_asn1_to_raw()

size_t br_ecdsa_asn1_to_raw | ( | void * | sig,
|  | size_t | sig_len
| ) |  |

Convert a signature from "asn1" to "raw".

Conversion is done "in place" and the new length is returned. Conversion may enlarge the signature, but the new signature length will be less than twice the source length at most. On error, 0 is returned (error conditions include an invalid ASN.1 structure or an oversized integer).

Parameters

  sig | signature to convert.
  sig_len | signature length (in bytes).

Returns
  the new signature length, or 0 on error.

## ◆ br_ecdsa_i15_sign_asn1()

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
| ) |  |

ECDSA signature generator, "i15" implementation, "asn1" format.

See also
  br_ecdsa_sign()

Parameters

  impl | EC implementation to use.
  hf | hash function used to process the data.
  hash_value | signed data (hashed).
  sk | EC private key.
  sig | destination buffer.

Returns
  the signature length (in bytes), or 0 on error.

## ◆ br_ecdsa_i15_sign_raw()

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
| ) |  |

ECDSA signature generator, "i15" implementation, "raw" format.

See also
  br_ecdsa_sign()

Parameters

  impl | EC implementation to use.
  hf | hash function used to process the data.
  hash_value | signed data (hashed).
  sk | EC private key.
  sig | destination buffer.

Returns
  the signature length (in bytes), or 0 on error.

## ◆ br_ecdsa_i15_vrfy_asn1()

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
| ) |  |

ECDSA signature verifier, "i15" implementation, "asn1" format.

See also
  br_ecdsa_vrfy()

Parameters

  impl | EC implementation to use.
  hash | signed data (hashed).
  hash_len | hash value length (in bytes).
  pk | EC public key.
  sig | signature.
  sig_len | signature length (in bytes).

Returns
  1 on success, 0 on error.

## ◆ br_ecdsa_i15_vrfy_raw()

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
| ) |  |

ECDSA signature verifier, "i15" implementation, "raw" format.

See also
  br_ecdsa_vrfy()

Parameters

  impl | EC implementation to use.
  hash | signed data (hashed).
  hash_len | hash value length (in bytes).
  pk | EC public key.
  sig | signature.
  sig_len | signature length (in bytes).

Returns
  1 on success, 0 on error.

## ◆ br_ecdsa_i31_sign_asn1()

size_t br_ecdsa_i31_sign_asn1 | ( | const br_ec_impl * | impl,
|  | const br_hash_class * | hf,
|  | const void * | hash_value,
|  | const br_ec_private_key * | sk,
|  | void * | sig
| ) |  |

ECDSA signature generator, "i31" implementation, "asn1" format.

See also
  br_ecdsa_sign()

Parameters

  impl | EC implementation to use.
  hf | hash function used to process the data.
  hash_value | signed data (hashed).
  sk | EC private key.
  sig | destination buffer.

Returns
  the signature length (in bytes), or 0 on error.

## ◆ br_ecdsa_i31_sign_raw()

size_t br_ecdsa_i31_sign_raw | ( | const br_ec_impl * | impl,
|  | const br_hash_class * | hf,
|  | const void * | hash_value,
|  | const br_ec_private_key * | sk,
|  | void * | sig
| ) |  |

ECDSA signature generator, "i31" implementation, "raw" format.

See also
  br_ecdsa_sign()

Parameters

  impl | EC implementation to use.
  hf | hash function used to process the data.
  hash_value | signed data (hashed).
  sk | EC private key.
  sig | destination buffer.

Returns
  the signature length (in bytes), or 0 on error.

## ◆ br_ecdsa_i31_vrfy_asn1()

uint32_t br_ecdsa_i31_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
| ) |  |

ECDSA signature verifier, "i31" implementation, "asn1" format.

See also
  br_ecdsa_vrfy()

Parameters

  impl | EC implementation to use.
  hash | signed data (hashed).
  hash_len | hash value length (in bytes).
  pk | EC public key.
  sig | signature.
  sig_len | signature length (in bytes).

Returns
  1 on success, 0 on error.

## ◆ br_ecdsa_i31_vrfy_raw()

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
| ) |  |

ECDSA signature verifier, "i31" implementation, "raw" format.

See also
  br_ecdsa_vrfy()

Parameters

  impl | EC implementation to use.
  hash | signed data (hashed).
  hash_len | hash value length (in bytes).
  pk | EC public key.
  sig | signature.
  sig_len | signature length (in bytes).

Returns
  1 on success, 0 on error.

## ◆ br_ecdsa_raw_to_asn1()

size_t br_ecdsa_raw_to_asn1 | ( | void * | sig,
|  | size_t | sig_len
| ) |  |

Convert a signature from "raw" to "asn1".

Conversion is done "in place" and the new length is returned. Conversion may enlarge the signature, but by no more than 9 bytes at most. On error, 0 is returned (error conditions include an odd raw signature length, or an oversized integer).

Parameters

  sig | signature to convert.
  sig_len | signature length (in bytes).

Returns
  the new signature length, or 0 on error.

## ◆ br_ecdsa_sign_asn1_get_default()

br_ecdsa_sign br_ecdsa_sign_asn1_get_default | ( | void |  | ) |

Get "default" ECDSA implementation (signer, asn1 format).

This returns the preferred implementation of ECDSA signature generation ("asn1" output format) on the current system.

Returns
  the default implementation.

## ◆ br_ecdsa_sign_raw_get_default()

br_ecdsa_sign br_ecdsa_sign_raw_get_default | ( | void |  | ) |

Get "default" ECDSA implementation (signer, raw format).

This returns the preferred implementation of ECDSA signature generation ("raw" output format) on the current system.

Returns
  the default implementation.

## ◆ br_ecdsa_vrfy_asn1_get_default()

br_ecdsa_vrfy br_ecdsa_vrfy_asn1_get_default | ( | void |  | ) |

Get "default" ECDSA implementation (verifier, asn1 format).

This returns the preferred implementation of ECDSA signature verification ("asn1" output format) on the current system.

Returns
  the default implementation.

## ◆ br_ecdsa_vrfy_raw_get_default()

br_ecdsa_vrfy br_ecdsa_vrfy_raw_get_default | ( | void |  | ) |

Get "default" ECDSA implementation (verifier, raw format).

This returns the preferred implementation of ECDSA signature verification ("raw" output format) on the current system.

Returns
  the default implementation.

## Variable Documentation

## ◆ br_ec_all_m15

const br_ec_impl br_ec_all_m15
| extern

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)

## ◆ br_ec_all_m31

const br_ec_impl br_ec_all_m31
| extern

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)

## ◆ br_ec_c25519_i15

const br_ec_impl br_ec_c25519_i15
| extern

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).

## ◆ br_ec_c25519_i31

const br_ec_impl br_ec_c25519_i31
| extern

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).

## ◆ br_ec_c25519_m15

const br_ec_impl br_ec_c25519_m15
| extern

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).

## ◆ br_ec_c25519_m31

const br_ec_impl br_ec_c25519_m31
| extern

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).

## ◆ br_ec_p256_m15

const br_ec_impl br_ec_p256_m15
| extern

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).

## ◆ br_ec_p256_m31

const br_ec_impl br_ec_p256_m31
| extern

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).

## ◆ br_ec_prime_i15

const br_ec_impl br_ec_prime_i15
| extern

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).

## ◆ br_ec_prime_i31

const br_ec_impl br_ec_prime_i31
| extern

EC implementation "i31".

This implementation internally uses generic code for modular integers, with a representation as sequences of 31-bit words. It supports secp256r1, secp384r1 and secp521r1 (aka NIST curves P-256, P-384 and P-521).