BearSSL

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

Go to the source code of this file.

## Data Structures
struct | br_rsa_public_key
| RSA public key. More...
struct | br_rsa_private_key
| RSA private key. More...

## Macros
#define | BR_HASH_OID_SHA1 ((const unsigned char *)"\x05\x2B\x0E\x03\x02\x1A")
| Encoded OID for SHA-1 (in RSA PKCS#1 signatures). More...
#define | BR_HASH_OID_SHA224 ((const unsigned char *)"\x09\x60\x86\x48\x01\x65\x03\x04\x02\x04")
| Encoded OID for SHA-224 (in RSA PKCS#1 signatures). More...
#define | BR_HASH_OID_SHA256 ((const unsigned char *)"\x09\x60\x86\x48\x01\x65\x03\x04\x02\x01")
| Encoded OID for SHA-256 (in RSA PKCS#1 signatures). More...
#define | BR_HASH_OID_SHA384 ((const unsigned char *)"\x09\x60\x86\x48\x01\x65\x03\x04\x02\x02")
| Encoded OID for SHA-384 (in RSA PKCS#1 signatures). More...
#define | BR_HASH_OID_SHA512 ((const unsigned char *)"\x09\x60\x86\x48\x01\x65\x03\x04\x02\x03")
| Encoded OID for SHA-512 (in RSA PKCS#1 signatures). More...
#define | BR_RSA_KBUF_PRIV_SIZE(size) (5 * (((size) + 15) >> 4))
| Get buffer size to hold RSA private key elements. More...
#define | BR_RSA_KBUF_PUB_SIZE(size) (4 + (((size) + 7) >> 3))
| Get buffer size to hold RSA public key elements. More...

## Typedefs
typedef uint32_t(* | br_rsa_public) (unsigned char *x, size_t xlen, const br_rsa_public_key *pk)
| Type for a RSA public key engine. More...
typedef uint32_t(* | br_rsa_pkcs1_vrfy) (const unsigned char *x, size_t xlen, const unsigned char *hash_oid, size_t hash_len, const br_rsa_public_key *pk, unsigned char *hash_out)
| Type for a RSA signature verification engine (PKCS#1 v1.5). More...
typedef size_t(* | br_rsa_oaep_encrypt) (const br_prng_class **rnd, const br_hash_class *dig, const void *label, size_t label_len, const br_rsa_public_key *pk, void *dst, size_t dst_max_len, const void *src, size_t src_len)
| Type for a RSA encryption engine (OAEP). More...
typedef uint32_t(* | br_rsa_private) (unsigned char *x, const br_rsa_private_key *sk)
| Type for a RSA private key engine. More...
typedef uint32_t(* | br_rsa_pkcs1_sign) (const unsigned char *hash_oid, const unsigned char *hash, size_t hash_len, const br_rsa_private_key *sk, unsigned char *x)
| Type for a RSA signature generation engine (PKCS#1 v1.5). More...
typedef uint32_t(* | br_rsa_oaep_decrypt) (const br_hash_class *dig, const void *label, size_t label_len, const br_rsa_private_key *sk, void *data, size_t *len)
| Type for a RSA decryption engine (OAEP). More...
typedef uint32_t(* | br_rsa_keygen) (const br_prng_class **rng_ctx, br_rsa_private_key *sk, void *kbuf_priv, br_rsa_public_key *pk, void *kbuf_pub, unsigned size, uint32_t pubexp)
| Type for RSA key pair generator implementation. More...
typedef size_t(* | br_rsa_compute_modulus) (void *n, const br_rsa_private_key *sk)
| Type for a modulus computing function. More...
typedef uint32_t(* | br_rsa_compute_pubexp) (const br_rsa_private_key *sk)
| Type for a public exponent computing function. More...
typedef size_t(* | br_rsa_compute_privexp) (void *d, const br_rsa_private_key *sk, uint32_t pubexp)
| Type for a private exponent computing function. More...

## Functions
uint32_t | br_rsa_i32_public (unsigned char *x, size_t xlen, const br_rsa_public_key *pk)
| RSA public key engine "i32". More...
uint32_t | br_rsa_i32_pkcs1_vrfy (const unsigned char *x, size_t xlen, const unsigned char *hash_oid, size_t hash_len, const br_rsa_public_key *pk, unsigned char *hash_out)
| RSA signature verification engine "i32". More...
uint32_t | br_rsa_i32_private (unsigned char *x, const br_rsa_private_key *sk)
| RSA private key engine "i32". More...
uint32_t | br_rsa_i32_pkcs1_sign (const unsigned char *hash_oid, const unsigned char *hash, size_t hash_len, const br_rsa_private_key *sk, unsigned char *x)
| RSA signature generation engine "i32". More...
uint32_t | br_rsa_i31_public (unsigned char *x, size_t xlen, const br_rsa_public_key *pk)
| RSA public key engine "i31". More...
uint32_t | br_rsa_i31_pkcs1_vrfy (const unsigned char *x, size_t xlen, const unsigned char *hash_oid, size_t hash_len, const br_rsa_public_key *pk, unsigned char *hash_out)
| RSA signature verification engine "i31". More...
uint32_t | br_rsa_i31_private (unsigned char *x, const br_rsa_private_key *sk)
| RSA private key engine "i31". More...
uint32_t | br_rsa_i31_pkcs1_sign (const unsigned char *hash_oid, const unsigned char *hash, size_t hash_len, const br_rsa_private_key *sk, unsigned char *x)
| RSA signature generation engine "i31". More...
uint32_t | br_rsa_i62_public (unsigned char *x, size_t xlen, const br_rsa_public_key *pk)
| RSA public key engine "i62". More...
uint32_t | br_rsa_i62_pkcs1_vrfy (const unsigned char *x, size_t xlen, const unsigned char *hash_oid, size_t hash_len, const br_rsa_public_key *pk, unsigned char *hash_out)
| RSA signature verification engine "i62". More...
uint32_t | br_rsa_i62_private (unsigned char *x, const br_rsa_private_key *sk)
| RSA private key engine "i62". More...
uint32_t | br_rsa_i62_pkcs1_sign (const unsigned char *hash_oid, const unsigned char *hash, size_t hash_len, const br_rsa_private_key *sk, unsigned char *x)
| RSA signature generation engine "i62". More...
br_rsa_public | br_rsa_i62_public_get (void)
| Get the RSA "i62" implementation (public key operations), if available. More...
br_rsa_pkcs1_vrfy | br_rsa_i62_pkcs1_vrfy_get (void)
| Get the RSA "i62" implementation (PKCS#1 signature verification), if available. More...
br_rsa_private | br_rsa_i62_private_get (void)
| Get the RSA "i62" implementation (private key operations), if available. More...
br_rsa_pkcs1_sign | br_rsa_i62_pkcs1_sign_get (void)
| Get the RSA "i62" implementation (PKCS#1 signature generation), if available. More...
br_rsa_oaep_encrypt | br_rsa_i62_oaep_encrypt_get (void)
| Get the RSA "i62" implementation (OAEP encryption), if available. More...
br_rsa_oaep_decrypt | br_rsa_i62_oaep_decrypt_get (void)
| Get the RSA "i62" implementation (OAEP decryption), if available. More...
uint32_t | br_rsa_i15_public (unsigned char *x, size_t xlen, const br_rsa_public_key *pk)
| RSA public key engine "i15". More...
uint32_t | br_rsa_i15_pkcs1_vrfy (const unsigned char *x, size_t xlen, const unsigned char *hash_oid, size_t hash_len, const br_rsa_public_key *pk, unsigned char *hash_out)
| RSA signature verification engine "i15". More...
uint32_t | br_rsa_i15_private (unsigned char *x, const br_rsa_private_key *sk)
| RSA private key engine "i15". More...
uint32_t | br_rsa_i15_pkcs1_sign (const unsigned char *hash_oid, const unsigned char *hash, size_t hash_len, const br_rsa_private_key *sk, unsigned char *x)
| RSA signature generation engine "i15". More...
br_rsa_public | br_rsa_public_get_default (void)
| Get "default" RSA implementation (public-key operations). More...
br_rsa_private | br_rsa_private_get_default (void)
| Get "default" RSA implementation (private-key operations). More...
br_rsa_pkcs1_vrfy | br_rsa_pkcs1_vrfy_get_default (void)
| Get "default" RSA implementation (PKCS#1 signature verification). More...
br_rsa_pkcs1_sign | br_rsa_pkcs1_sign_get_default (void)
| Get "default" RSA implementation (PKCS#1 signature generation). More...
br_rsa_oaep_encrypt | br_rsa_oaep_encrypt_get_default (void)
| Get "default" RSA implementation (OAEP encryption). More...
br_rsa_oaep_decrypt | br_rsa_oaep_decrypt_get_default (void)
| Get "default" RSA implementation (OAEP decryption). More...
uint32_t | br_rsa_ssl_decrypt (br_rsa_private core, const br_rsa_private_key *sk, unsigned char *data, size_t len)
| RSA decryption helper, for SSL/TLS. More...
size_t | br_rsa_i15_oaep_encrypt (const br_prng_class **rnd, const br_hash_class *dig, const void *label, size_t label_len, const br_rsa_public_key *pk, void *dst, size_t dst_max_len, const void *src, size_t src_len)
| RSA encryption (OAEP) with the "i15" engine. More...
uint32_t | br_rsa_i15_oaep_decrypt (const br_hash_class *dig, const void *label, size_t label_len, const br_rsa_private_key *sk, void *data, size_t *len)
| RSA decryption (OAEP) with the "i15" engine. More...
size_t | br_rsa_i31_oaep_encrypt (const br_prng_class **rnd, const br_hash_class *dig, const void *label, size_t label_len, const br_rsa_public_key *pk, void *dst, size_t dst_max_len, const void *src, size_t src_len)
| RSA encryption (OAEP) with the "i31" engine. More...
uint32_t | br_rsa_i31_oaep_decrypt (const br_hash_class *dig, const void *label, size_t label_len, const br_rsa_private_key *sk, void *data, size_t *len)
| RSA decryption (OAEP) with the "i31" engine. More...
size_t | br_rsa_i32_oaep_encrypt (const br_prng_class **rnd, const br_hash_class *dig, const void *label, size_t label_len, const br_rsa_public_key *pk, void *dst, size_t dst_max_len, const void *src, size_t src_len)
| RSA encryption (OAEP) with the "i32" engine. More...
uint32_t | br_rsa_i32_oaep_decrypt (const br_hash_class *dig, const void *label, size_t label_len, const br_rsa_private_key *sk, void *data, size_t *len)
| RSA decryption (OAEP) with the "i32" engine. More...
size_t | br_rsa_i62_oaep_encrypt (const br_prng_class **rnd, const br_hash_class *dig, const void *label, size_t label_len, const br_rsa_public_key *pk, void *dst, size_t dst_max_len, const void *src, size_t src_len)
| RSA encryption (OAEP) with the "i62" engine. More...
uint32_t | br_rsa_i62_oaep_decrypt (const br_hash_class *dig, const void *label, size_t label_len, const br_rsa_private_key *sk, void *data, size_t *len)
| RSA decryption (OAEP) with the "i62" engine. More...
uint32_t | br_rsa_i15_keygen (const br_prng_class **rng_ctx, br_rsa_private_key *sk, void *kbuf_priv, br_rsa_public_key *pk, void *kbuf_pub, unsigned size, uint32_t pubexp)
| RSA key pair generation with the "i15" engine. More...
uint32_t | br_rsa_i31_keygen (const br_prng_class **rng_ctx, br_rsa_private_key *sk, void *kbuf_priv, br_rsa_public_key *pk, void *kbuf_pub, unsigned size, uint32_t pubexp)
| RSA key pair generation with the "i31" engine. More...
uint32_t | br_rsa_i62_keygen (const br_prng_class **rng_ctx, br_rsa_private_key *sk, void *kbuf_priv, br_rsa_public_key *pk, void *kbuf_pub, unsigned size, uint32_t pubexp)
| RSA key pair generation with the "i62" engine. More...
br_rsa_keygen | br_rsa_i62_keygen_get (void)
| Get the RSA "i62" implementation (key pair generation), if available. More...
br_rsa_keygen | br_rsa_keygen_get_default (void)
| Get "default" RSA implementation (key pair generation). More...
size_t | br_rsa_i15_compute_modulus (void *n, const br_rsa_private_key *sk)
| Recompute RSA modulus ("i15" engine). More...
size_t | br_rsa_i31_compute_modulus (void *n, const br_rsa_private_key *sk)
| Recompute RSA modulus ("i31" engine). More...
br_rsa_compute_modulus | br_rsa_compute_modulus_get_default (void)
| Get "default" RSA implementation (recompute modulus). More...
uint32_t | br_rsa_i15_compute_pubexp (const br_rsa_private_key *sk)
| Recompute RSA public exponent ("i15" engine). More...
uint32_t | br_rsa_i31_compute_pubexp (const br_rsa_private_key *sk)
| Recompute RSA public exponent ("i31" engine). More...
br_rsa_compute_pubexp | br_rsa_compute_pubexp_get_default (void)
| Get "default" RSA implementation (recompute public exponent). More...
size_t | br_rsa_i15_compute_privexp (void *d, const br_rsa_private_key *sk, uint32_t pubexp)
| Recompute RSA private exponent ("i15" engine). More...
size_t | br_rsa_i31_compute_privexp (void *d, const br_rsa_private_key *sk, uint32_t pubexp)
| Recompute RSA private exponent ("i31" engine). More...
br_rsa_compute_privexp | br_rsa_compute_privexp_get_default (void)
| Get "default" RSA implementation (recompute private exponent). More...

## Detailed Description

# RSA

This file documents the RSA implementations provided with BearSSL. Note that the SSL engine accesses these implementations through a configurable API, so it is possible to, for instance, run a SSL server which uses a RSA engine which is not based on this code.

## Key Elements

RSA public and private keys consist in lists of big integers. All such integers are represented with big-endian unsigned notation: first byte is the most significant, and the value is positive (so there is no dedicated "sign bit"). Public and private key structures thus contain, for each such integer, a pointer to the first value byte (`unsigned char *`), and a length (`size_t`) which is the number of relevant bytes. As a general rule, minimal-length encoding is not enforced: values may have extra leading bytes of value 0.

RSA public keys consist in two integers:

- the modulus (`n`);
- the public exponent (`e`).

RSA private keys, as defined in PKCS#1, contain eight integers:

- the modulus (`n`);
- the public exponent (`e`);
- the private exponent (`d`);
- the first prime factor (`p`);
- the second prime factor (`q`);
- the first reduced exponent (`dp`, which is `d` modulo `p-1`);
- the second reduced exponent (`dq`, which is `d` modulo `q-1`);
- the CRT coefficient (`iq`, the inverse of `q` modulo `p`).

However, the implementations defined in BearSSL use only five of these integers: `p`, `q`, `dp`, `dq` and `iq`.

## Security Features and Limitations

The implementations contained in BearSSL have the following limitations and features:

- They are constant-time. This means that the execution time and memory access pattern may depend on the lengths of the private key components, but not on their value, nor on the value of the operand. Note that this property is not achieved through random masking, but "true" constant-time code.
- They support only private keys with two prime factors. RSA private keys with three or more prime factors are nominally supported, but rarely used; they may offer faster operations, at the expense of more code and potentially a reduction in security if there are "too many" prime factors.
- The public exponent may have arbitrary length. Of course, it is a good idea to keep public exponents small, so that public key operations are fast; but, contrary to some widely deployed implementations, BearSSL has no problem with public exponents longer than 32 bits.
- The two prime factors of the modulus need not have the same length (but severely imbalanced factor lengths might reduce security). Similarly, there is no requirement that the first factor (`p`) be greater than the second factor (`q`).
- Prime factors and modulus must be smaller than a compile-time limit. This is made necessary by the use of fixed-size stack buffers, and the limit has been adjusted to keep stack usage under 2 kB for the RSA operations. Currently, the maximum modulus size is 4096 bits, and the maximum prime factor size is 2080 bits.
- The RSA functions themselves do not enforce lower size limits, except that which is absolutely necessary for the operation to mathematically make sense (e.g. a PKCS#1 v1.5 signature with SHA-1 requires a modulus of at least 361 bits). It is up to users of this code to enforce size limitations when appropriate (e.g. the X.509 validation engine, by default, rejects RSA keys of less than 1017 bits).
- Within the size constraints expressed above, arbitrary bit lengths are supported. There is no requirement that prime factors or modulus have a size multiple of 8 or 16.
- When verifying PKCS#1 v1.5 signatures, both variants of the hash function identifying header (with and without the ASN.1 NULL) are supported. When producing such signatures, the variant with the ASN.1 NULL is used.

## Implementations

Three RSA implementations are included:

- The i32 implementation internally represents big integers as arrays of 32-bit integers. It is perfunctory and portable, but not very efficient.
- The i31 implementation uses 32-bit integers, each containing 31 bits worth of integer data. The i31 implementation is somewhat faster than the i32 implementation (the reduced integer size makes carry propagation easier) for a similar code footprint, but uses very slightly larger stack buffers (about 4% bigger).
- The i62 implementation is similar to the i31 implementation, except that it internally leverages the 64x64->128 multiplication opcode. This implementation is available only on architectures where such an opcode exists. It is much faster than i31.
- The i15 implementation uses 16-bit integers, each containing 15 bits worth of integer data. Multiplication results fit on 32 bits, so this won't use the "widening" multiplication routine on ARM Cortex M0/M0+, for much better performance and constant-time execution.

## Macro Definition Documentation

## ◆ BR_HASH_OID_SHA1

#define BR_HASH_OID_SHA1 ((const unsigned char *)"\x05\x2B\x0E\x03\x02\x1A")

Encoded OID for SHA-1 (in RSA PKCS#1 signatures).

## ◆ BR_HASH_OID_SHA224

#define BR_HASH_OID_SHA224 ((const unsigned char *)"\x09\x60\x86\x48\x01\x65\x03\x04\x02\x04")

Encoded OID for SHA-224 (in RSA PKCS#1 signatures).

## ◆ BR_HASH_OID_SHA256

#define BR_HASH_OID_SHA256 ((const unsigned char *)"\x09\x60\x86\x48\x01\x65\x03\x04\x02\x01")

Encoded OID for SHA-256 (in RSA PKCS#1 signatures).

## ◆ BR_HASH_OID_SHA384

#define BR_HASH_OID_SHA384 ((const unsigned char *)"\x09\x60\x86\x48\x01\x65\x03\x04\x02\x02")

Encoded OID for SHA-384 (in RSA PKCS#1 signatures).

## ◆ BR_HASH_OID_SHA512

#define BR_HASH_OID_SHA512 ((const unsigned char *)"\x09\x60\x86\x48\x01\x65\x03\x04\x02\x03")

Encoded OID for SHA-512 (in RSA PKCS#1 signatures).

## ◆ BR_RSA_KBUF_PRIV_SIZE

#define BR_RSA_KBUF_PRIV_SIZE | ( |  | size | ) | (5 * (((size) + 15) >> 4))

Get buffer size to hold RSA private key elements.

This macro returns the length (in bytes) of the buffer needed to receive the elements of a RSA private key, as generated by one of the `br_rsa_*_keygen()` functions. If the provided size is a constant expression, then the whole macro evaluates to a constant expression.

Parameters

  size | target key size (modulus size, in bits)

Returns
  the length of the private key buffer, in bytes.

## ◆ BR_RSA_KBUF_PUB_SIZE

#define BR_RSA_KBUF_PUB_SIZE | ( |  | size | ) | (4 + (((size) + 7) >> 3))

Get buffer size to hold RSA public key elements.

This macro returns the length (in bytes) of the buffer needed to receive the elements of a RSA public key, as generated by one of the `br_rsa_*_keygen()` functions. If the provided size is a constant expression, then the whole macro evaluates to a constant expression.

Parameters

  size | target key size (modulus size, in bits)

Returns
  the length of the public key buffer, in bytes.

## Typedef Documentation

## ◆ br_rsa_compute_modulus

typedef size_t(* br_rsa_compute_modulus) (void *n, const br_rsa_private_key *sk)

Type for a modulus computing function.

Such a function computes the public modulus from the private key. The encoded modulus (unsigned big-endian) is written on `n`, and the size (in bytes) is returned. If `n` is `NULL`, then the size is returned but the modulus itself is not computed.

If the key size exceeds an internal limit, 0 is returned.

Parameters

  n | destination buffer (or `NULL`).
  sk | RSA private key.

Returns
  the modulus length (in bytes), or 0.

## ◆ br_rsa_compute_privexp

typedef size_t(* br_rsa_compute_privexp) (void *d, const br_rsa_private_key *sk, uint32_t pubexp)

Type for a private exponent computing function.

An RSA private key (`br_rsa_private_key`) contains two reduced private exponents, which are sufficient to perform private key operations. However, standard encoding formats for RSA private keys require also a copy of the complete private exponent (non-reduced), which this function recomputes.

This function suceeds if all the following conditions hold:

- Both private factors `p` and `q` are equal to 3 modulo 4.
- The provided public exponent `pubexp` is correct, and, in particular, is odd, relatively prime to `p-1` and `q-1`, and greater than 1.
- No internal storage limit is exceeded.

For all private keys produced by the key generator functions (`br_rsa_keygen` type), this function succeeds. Note that the API restricts the public exponent to a maximum size of 32 bits.

The encoded private exponent is written in `d` (unsigned big-endian convention), and the length (in bytes) is returned. If `d` is `NULL`, then the exponent is not written anywhere, but the length is still returned. On error, 0 is returned.

Not all error conditions are detected when `d` is `NULL`; therefore, the returned value shall be checked also when actually producing the value.

Parameters

  d | destination buffer (or `NULL`).
  sk | RSA private key.
  pubexp | the public exponent.

Returns
  the private exponent length (in bytes), or 0.

## ◆ br_rsa_compute_pubexp

typedef uint32_t(* br_rsa_compute_pubexp) (const br_rsa_private_key *sk)

Type for a public exponent computing function.

Such a function recomputes the public exponent from the private key. 0 is returned if any of the following occurs:

- Either `p` or `q` is not equal to 3 modulo 4.
- The public exponent does not fit on 32 bits.
- An internal limit is exceeded.
- The private key is invalid in some way.

For all private keys produced by the key generator functions (`br_rsa_keygen` type), this function succeeds and returns the true public exponent. The public exponent is always an odd integer greater than 1.

Returns
  the public exponent, or 0.

## ◆ br_rsa_keygen

typedef uint32_t(* br_rsa_keygen) (const br_prng_class **rng_ctx, br_rsa_private_key *sk, void *kbuf_priv, br_rsa_public_key *pk, void *kbuf_pub, unsigned size, uint32_t pubexp)

Type for RSA key pair generator implementation.

This function generates a new RSA key pair whose modulus has bit length `size` bits. The private key elements are written in the `kbuf_priv` buffer, and pointer values and length fields to these elements are populated in the provided private key structure `sk`. Similarly, the public key elements are written in `kbuf_pub`, with pointers and lengths set in `pk`.

If `pk` is `NULL`, then `kbuf_pub` may be `NULL`, and only the private key is set.

If `pubexp` is not zero, then its value will be used as public exponent. Valid RSA public exponent values are odd integers greater than 1. If `pubexp` is zero, then the public exponent will have value 3.

The provided PRNG (`rng_ctx`) must have already been initialized and seeded.

Returned value is 1 on success, 0 on error. An error is reported if the requested range is outside of the supported key sizes, or if an invalid non-zero public exponent value is provided. Supported range starts at 512 bits, and up to an implementation-defined maximum (by default 4096 bits). Note that key sizes up to 768 bits have been broken in practice, and sizes lower than 2048 bits are usually considered to be weak and should not be used.

Parameters

  rng_ctx | source PRNG context (already initialized)
  sk | RSA private key structure (destination)
  kbuf_priv | buffer for private key elements
  pk | RSA public key structure (destination), or `NULL`
  kbuf_pub | buffer for public key elements, or `NULL`
  size | target RSA modulus size (in bits)
  pubexp | public exponent to use, or zero

Returns
  1 on success, 0 on error (invalid parameters)

## ◆ br_rsa_oaep_decrypt

typedef uint32_t(* br_rsa_oaep_decrypt) (const br_hash_class *dig, const void *label, size_t label_len, const br_rsa_private_key *sk, void *data, size_t *len)

Type for a RSA decryption engine (OAEP).

Parameters are:

- A hash function, used internally with the mask generation function (MGF1).
- A label. The `label` pointer may be `NULL` if `label_len` is zero (an empty label, which is the default in PKCS#1 v2.2).
- The private key.
- The source and destination buffer. The buffer initially contains the encrypted message; the buffer contents are altered, and the decrypted message is written at the start of that buffer (decrypted message is always shorter than the encrypted message).

If decryption fails in any way, then `*len` is unmodified, and the function returns 0. Otherwise, `*len` is set to the decrypted message length, and 1 is returned. The implementation is responsible for checking that the input message length matches the key modulus length, and that the padding is correct.

Implementations MUST use constant-time check of the validity of the OAEP padding, at least until the leading byte and hash value have been checked. Whether overall decryption worked, and the length of the decrypted message, may leak.

Parameters

  dig | hash function to use with MGF1.
  label | label value (may be `NULL` if `label_len` is zero).
  label_len | label length, in bytes.
  sk | RSA private key.
  data | input/output buffer.
  len | encrypted/decrypted message length.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_oaep_encrypt

typedef size_t(* br_rsa_oaep_encrypt) (const br_prng_class **rnd, const br_hash_class *dig, const void *label, size_t label_len, const br_rsa_public_key *pk, void *dst, size_t dst_max_len, const void *src, size_t src_len)

Type for a RSA encryption engine (OAEP).

Parameters are:

- A source of random bytes. The source must be already initialized.
- A hash function, used internally with the mask generation function (MGF1).
- A label. The `label` pointer may be `NULL` if `label_len` is zero (an empty label, which is the default in PKCS#1 v2.2).
- The public key.
- The destination buffer. Its maximum length (in bytes) is provided; if that length is lower than the public key length, then an error is reported.
- The source message.

The encrypted message output has exactly the same length as the modulus (mathematical length, in bytes, not counting extra leading zeros in the modulus representation in the public key).

The source message (`src`, length `src_len`) may overlap with the destination buffer (`dst`, length `dst_max_len`).

This function returns the actual encrypted message length, in bytes; on error, zero is returned. An error is reported if the output buffer is not large enough, or the public is invalid, or the public key modulus exceeds the maximum supported RSA size.

Parameters

  rnd | source of random bytes.
  dig | hash function to use with MGF1.
  label | label value (may be `NULL` if `label_len` is zero).
  label_len | label length, in bytes.
  pk | RSA public key.
  dst | destination buffer.
  dst_max_len | destination buffer length (maximum encrypted data size).
  src | message to encrypt.
  src_len | source message length (in bytes).

Returns
  encrypted message length (in bytes), or 0 on error.

## ◆ br_rsa_pkcs1_sign

typedef uint32_t(* br_rsa_pkcs1_sign) (const unsigned char *hash_oid, const unsigned char *hash, size_t hash_len, const br_rsa_private_key *sk, unsigned char *x)

Type for a RSA signature generation engine (PKCS#1 v1.5).

Parameters are:

- The encoded OID for the hash function. The provided array must begin with a single byte that contains the length of the OID value (in bytes), followed by exactly that many bytes. This parameter may also be `NULL`, in which case the raw hash value should be used with the PKCS#1 v1.5 "type 1" padding (as used in SSL/TLS up to TLS-1.1, with a 36-byte hash value).
- The hash value computes over the data to sign (its length is expressed in bytes).
- The RSA private key.
- The output buffer, that receives the signature.

Returned value is 1 on success, 0 on error. Error conditions include a too small modulus for the provided hash OID and value, or some invalid key parameters. The signature length is exactly `(sk->n_bitlen+7)/8` bytes.

This function is expected to be constant-time with regards to the private key bytes (lengths of the modulus and the individual factors may leak, though) and to the hashed data.

Parameters

  hash_oid | encoded hash algorithm OID (or `NULL`).
  hash | hash value.
  hash_len | hash value length (in bytes).
  sk | RSA private key.
  x | output buffer for the signature value.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_pkcs1_vrfy

typedef uint32_t(* br_rsa_pkcs1_vrfy) (const unsigned char *x, size_t xlen, const unsigned char *hash_oid, size_t hash_len, const br_rsa_public_key *pk, unsigned char *hash_out)

Type for a RSA signature verification engine (PKCS#1 v1.5).

Parameters are:

- The signature itself. The provided array is NOT modified.
- The encoded OID for the hash function. The provided array must begin with a single byte that contains the length of the OID value (in bytes), followed by exactly that many bytes. This parameter may also be `NULL`, in which case the raw hash value should be used with the PKCS#1 v1.5 "type 1" padding (as used in SSL/TLS up to TLS-1.1, with a 36-byte hash value).
- The hash output length, in bytes.
- The public key.
- An output buffer for the hash value. The caller must still compare it with the hash of the data over which the signature is computed.

Constraints:

- Hash length MUST be no more than 64 bytes.
- OID value length MUST be no more than 32 bytes (i.e. `hash_oid[0]` must have a value in the 0..32 range, inclusive).

This function verifies that the signature length (`xlen`) matches the modulus length (this function returns 0 on mismatch). If the modulus size exceeds the maximum supported RSA size, then the function also returns 0.

Returned value is 1 on success, 0 on error.

Implementations of this type need not be constant-time.

Parameters

  x | signature buffer.
  xlen | signature length (in bytes).
  hash_oid | encoded hash algorithm OID (or `NULL`).
  hash_len | expected hash value length (in bytes).
  pk | RSA public key.
  hash_out | output buffer for the hash value.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_private

typedef uint32_t(* br_rsa_private) (unsigned char *x, const br_rsa_private_key *sk)

Type for a RSA private key engine.

The `x[]` buffer is modified in place, and its length is inferred from the modulus length (`x[]` is assumed to have a length of `(sk->n_bitlen+7)/8` bytes).

Returned value is 1 on success, 0 on error.

Parameters

  x | operand to exponentiate.
  sk | RSA private key.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_public

typedef uint32_t(* br_rsa_public) (unsigned char *x, size_t xlen, const br_rsa_public_key *pk)

Type for a RSA public key engine.

The public key engine performs the modular exponentiation of the provided value with the public exponent. The value is modified in place.

The value length (`xlen`) is verified to have exactly the same length as the modulus (actual modulus length, without extra leading zeros in the modulus representation in memory). If the length does not match, then this function returns 0 and `x[]` is unmodified.

It `xlen` is correct, then `x[]` is modified. Returned value is 1 on success, 0 on error. Error conditions include an oversized `x[]` (the array has the same length as the modulus, but the numerical value is not lower than the modulus) and an invalid modulus (e.g. an even integer). If an error is reported, then the new contents of `x[]` are unspecified.

Parameters

  x | operand to exponentiate.
  xlen | length of the operand (in bytes).
  pk | RSA public key.

Returns
  1 on success, 0 on error.

## Function Documentation

## ◆ br_rsa_compute_modulus_get_default()

br_rsa_compute_modulus br_rsa_compute_modulus_get_default | ( | void |  | ) |

Get "default" RSA implementation (recompute modulus).

This returns the preferred implementation of RSA (recompute modulus) on the current system.

Returns
  the default implementation.

## ◆ br_rsa_compute_privexp_get_default()

br_rsa_compute_privexp br_rsa_compute_privexp_get_default | ( | void |  | ) |

Get "default" RSA implementation (recompute private exponent).

This returns the preferred implementation of RSA (recompute private exponent) on the current system.

Returns
  the default implementation.

## ◆ br_rsa_compute_pubexp_get_default()

br_rsa_compute_pubexp br_rsa_compute_pubexp_get_default | ( | void |  | ) |

Get "default" RSA implementation (recompute public exponent).

This returns the preferred implementation of RSA (recompute public exponent) on the current system.

Returns
  the default implementation.

## ◆ br_rsa_i15_compute_modulus()

size_t br_rsa_i15_compute_modulus | ( | void * | n,
|  | const br_rsa_private_key * | sk
| ) |  |

Recompute RSA modulus ("i15" engine).

See also
  br_rsa_compute_modulus

Parameters

  n | destination buffer (or `NULL`).
  sk | RSA private key.

Returns
  the modulus length (in bytes), or 0.

## ◆ br_rsa_i15_compute_privexp()

size_t br_rsa_i15_compute_privexp | ( | void * | d,
|  | const br_rsa_private_key * | sk,
|  | uint32_t | pubexp
| ) |  |

Recompute RSA private exponent ("i15" engine).

See also
  br_rsa_compute_privexp

Parameters

  d | destination buffer (or `NULL`).
  sk | RSA private key.
  pubexp | the public exponent.

Returns
  the private exponent length (in bytes), or 0.

## ◆ br_rsa_i15_compute_pubexp()

uint32_t br_rsa_i15_compute_pubexp | ( | const br_rsa_private_key * | sk | ) |

Recompute RSA public exponent ("i15" engine).

See also
  br_rsa_compute_pubexp

Returns
  the public exponent, or 0.

## ◆ br_rsa_i15_keygen()

uint32_t br_rsa_i15_keygen | ( | const br_prng_class ** | rng_ctx,
|  | br_rsa_private_key * | sk,
|  | void * | kbuf_priv,
|  | br_rsa_public_key * | pk,
|  | void * | kbuf_pub,
|  | unsigned | size,
|  | uint32_t | pubexp
| ) |  |

RSA key pair generation with the "i15" engine.

See also
  br_rsa_keygen

Parameters

  rng_ctx | source PRNG context (already initialized)
  sk | RSA private key structure (destination)
  kbuf_priv | buffer for private key elements
  pk | RSA public key structure (destination), or `NULL`
  kbuf_pub | buffer for public key elements, or `NULL`
  size | target RSA modulus size (in bits)
  pubexp | public exponent to use, or zero

Returns
  1 on success, 0 on error (invalid parameters)

## ◆ br_rsa_i15_oaep_decrypt()

uint32_t br_rsa_i15_oaep_decrypt | ( | const br_hash_class * | dig,
|  | const void * | label,
|  | size_t | label_len,
|  | const br_rsa_private_key * | sk,
|  | void * | data,
|  | size_t * | len
| ) |  |

RSA decryption (OAEP) with the "i15" engine.

See also
  br_rsa_oaep_decrypt

Parameters

  dig | hash function to use with MGF1.
  label | label value (may be `NULL` if `label_len` is zero).
  label_len | label length, in bytes.
  sk | RSA private key.
  data | input/output buffer.
  len | encrypted/decrypted message length.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i15_oaep_encrypt()

size_t br_rsa_i15_oaep_encrypt | ( | const br_prng_class ** | rnd,
|  | const br_hash_class * | dig,
|  | const void * | label,
|  | size_t | label_len,
|  | const br_rsa_public_key * | pk,
|  | void * | dst,
|  | size_t | dst_max_len,
|  | const void * | src,
|  | size_t | src_len
| ) |  |

RSA encryption (OAEP) with the "i15" engine.

See also
  br_rsa_oaep_encrypt

Parameters

  rnd | source of random bytes.
  dig | hash function to use with MGF1.
  label | label value (may be `NULL` if `label_len` is zero).
  label_len | label length, in bytes.
  pk | RSA public key.
  dst | destination buffer.
  dst_max_len | destination buffer length (maximum encrypted data size).
  src | message to encrypt.
  src_len | source message length (in bytes).

Returns
  encrypted message length (in bytes), or 0 on error.

## ◆ br_rsa_i15_pkcs1_sign()

uint32_t br_rsa_i15_pkcs1_sign | ( | const unsigned char * | hash_oid,
|  | const unsigned char * | hash,
|  | size_t | hash_len,
|  | const br_rsa_private_key * | sk,
|  | unsigned char * | x
| ) |  |

RSA signature generation engine "i15".

See also
  br_rsa_pkcs1_sign

Parameters

  hash_oid | encoded hash algorithm OID (or `NULL`).
  hash | hash value.
  hash_len | hash value length (in bytes).
  sk | RSA private key.
  x | output buffer for the hash value.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i15_pkcs1_vrfy()

uint32_t br_rsa_i15_pkcs1_vrfy | ( | const unsigned char * | x,
|  | size_t | xlen,
|  | const unsigned char * | hash_oid,
|  | size_t | hash_len,
|  | const br_rsa_public_key * | pk,
|  | unsigned char * | hash_out
| ) |  |

RSA signature verification engine "i15".

See also
  br_rsa_pkcs1_vrfy

Parameters

  x | signature buffer.
  xlen | signature length (in bytes).
  hash_oid | encoded hash algorithm OID (or `NULL`).
  hash_len | expected hash value length (in bytes).
  pk | RSA public key.
  hash_out | output buffer for the hash value.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i15_private()

uint32_t br_rsa_i15_private | ( | unsigned char * | x,
|  | const br_rsa_private_key * | sk
| ) |  |

RSA private key engine "i15".

See also
  br_rsa_private

Parameters

  x | operand to exponentiate.
  sk | RSA private key.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i15_public()

uint32_t br_rsa_i15_public | ( | unsigned char * | x,
|  | size_t | xlen,
|  | const br_rsa_public_key * | pk
| ) |  |

RSA public key engine "i15".

See also
  br_rsa_public

Parameters

  x | operand to exponentiate.
  xlen | length of the operand (in bytes).
  pk | RSA public key.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i31_compute_modulus()

size_t br_rsa_i31_compute_modulus | ( | void * | n,
|  | const br_rsa_private_key * | sk
| ) |  |

Recompute RSA modulus ("i31" engine).

See also
  br_rsa_compute_modulus

Parameters

  n | destination buffer (or `NULL`).
  sk | RSA private key.

Returns
  the modulus length (in bytes), or 0.

## ◆ br_rsa_i31_compute_privexp()

size_t br_rsa_i31_compute_privexp | ( | void * | d,
|  | const br_rsa_private_key * | sk,
|  | uint32_t | pubexp
| ) |  |

Recompute RSA private exponent ("i31" engine).

See also
  br_rsa_compute_privexp

Parameters

  d | destination buffer (or `NULL`).
  sk | RSA private key.
  pubexp | the public exponent.

Returns
  the private exponent length (in bytes), or 0.

## ◆ br_rsa_i31_compute_pubexp()

uint32_t br_rsa_i31_compute_pubexp | ( | const br_rsa_private_key * | sk | ) |

Recompute RSA public exponent ("i31" engine).

See also
  br_rsa_compute_pubexp

Returns
  the public exponent, or 0.

## ◆ br_rsa_i31_keygen()

uint32_t br_rsa_i31_keygen | ( | const br_prng_class ** | rng_ctx,
|  | br_rsa_private_key * | sk,
|  | void * | kbuf_priv,
|  | br_rsa_public_key * | pk,
|  | void * | kbuf_pub,
|  | unsigned | size,
|  | uint32_t | pubexp
| ) |  |

RSA key pair generation with the "i31" engine.

See also
  br_rsa_keygen

Parameters

  rng_ctx | source PRNG context (already initialized)
  sk | RSA private key structure (destination)
  kbuf_priv | buffer for private key elements
  pk | RSA public key structure (destination), or `NULL`
  kbuf_pub | buffer for public key elements, or `NULL`
  size | target RSA modulus size (in bits)
  pubexp | public exponent to use, or zero

Returns
  1 on success, 0 on error (invalid parameters)

## ◆ br_rsa_i31_oaep_decrypt()

uint32_t br_rsa_i31_oaep_decrypt | ( | const br_hash_class * | dig,
|  | const void * | label,
|  | size_t | label_len,
|  | const br_rsa_private_key * | sk,
|  | void * | data,
|  | size_t * | len
| ) |  |

RSA decryption (OAEP) with the "i31" engine.

See also
  br_rsa_oaep_decrypt

Parameters

  dig | hash function to use with MGF1.
  label | label value (may be `NULL` if `label_len` is zero).
  label_len | label length, in bytes.
  sk | RSA private key.
  data | input/output buffer.
  len | encrypted/decrypted message length.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i31_oaep_encrypt()

size_t br_rsa_i31_oaep_encrypt | ( | const br_prng_class ** | rnd,
|  | const br_hash_class * | dig,
|  | const void * | label,
|  | size_t | label_len,
|  | const br_rsa_public_key * | pk,
|  | void * | dst,
|  | size_t | dst_max_len,
|  | const void * | src,
|  | size_t | src_len
| ) |  |

RSA encryption (OAEP) with the "i31" engine.

See also
  br_rsa_oaep_encrypt

Parameters

  rnd | source of random bytes.
  dig | hash function to use with MGF1.
  label | label value (may be `NULL` if `label_len` is zero).
  label_len | label length, in bytes.
  pk | RSA public key.
  dst | destination buffer.
  dst_max_len | destination buffer length (maximum encrypted data size).
  src | message to encrypt.
  src_len | source message length (in bytes).

Returns
  encrypted message length (in bytes), or 0 on error.

## ◆ br_rsa_i31_pkcs1_sign()

uint32_t br_rsa_i31_pkcs1_sign | ( | const unsigned char * | hash_oid,
|  | const unsigned char * | hash,
|  | size_t | hash_len,
|  | const br_rsa_private_key * | sk,
|  | unsigned char * | x
| ) |  |

RSA signature generation engine "i31".

See also
  br_rsa_pkcs1_sign

Parameters

  hash_oid | encoded hash algorithm OID (or `NULL`).
  hash | hash value.
  hash_len | hash value length (in bytes).
  sk | RSA private key.
  x | output buffer for the hash value.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i31_pkcs1_vrfy()

uint32_t br_rsa_i31_pkcs1_vrfy | ( | const unsigned char * | x,
|  | size_t | xlen,
|  | const unsigned char * | hash_oid,
|  | size_t | hash_len,
|  | const br_rsa_public_key * | pk,
|  | unsigned char * | hash_out
| ) |  |

RSA signature verification engine "i31".

See also
  br_rsa_pkcs1_vrfy

Parameters

  x | signature buffer.
  xlen | signature length (in bytes).
  hash_oid | encoded hash algorithm OID (or `NULL`).
  hash_len | expected hash value length (in bytes).
  pk | RSA public key.
  hash_out | output buffer for the hash value.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i31_private()

uint32_t br_rsa_i31_private | ( | unsigned char * | x,
|  | const br_rsa_private_key * | sk
| ) |  |

RSA private key engine "i31".

See also
  br_rsa_private

Parameters

  x | operand to exponentiate.
  sk | RSA private key.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i31_public()

uint32_t br_rsa_i31_public | ( | unsigned char * | x,
|  | size_t | xlen,
|  | const br_rsa_public_key * | pk
| ) |  |

RSA public key engine "i31".

See also
  br_rsa_public

Parameters

  x | operand to exponentiate.
  xlen | length of the operand (in bytes).
  pk | RSA public key.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i32_oaep_decrypt()

uint32_t br_rsa_i32_oaep_decrypt | ( | const br_hash_class * | dig,
|  | const void * | label,
|  | size_t | label_len,
|  | const br_rsa_private_key * | sk,
|  | void * | data,
|  | size_t * | len
| ) |  |

RSA decryption (OAEP) with the "i32" engine.

See also
  br_rsa_oaep_decrypt

Parameters

  dig | hash function to use with MGF1.
  label | label value (may be `NULL` if `label_len` is zero).
  label_len | label length, in bytes.
  sk | RSA private key.
  data | input/output buffer.
  len | encrypted/decrypted message length.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i32_oaep_encrypt()

size_t br_rsa_i32_oaep_encrypt | ( | const br_prng_class ** | rnd,
|  | const br_hash_class * | dig,
|  | const void * | label,
|  | size_t | label_len,
|  | const br_rsa_public_key * | pk,
|  | void * | dst,
|  | size_t | dst_max_len,
|  | const void * | src,
|  | size_t | src_len
| ) |  |

RSA encryption (OAEP) with the "i32" engine.

See also
  br_rsa_oaep_encrypt

Parameters

  rnd | source of random bytes.
  dig | hash function to use with MGF1.
  label | label value (may be `NULL` if `label_len` is zero).
  label_len | label length, in bytes.
  pk | RSA public key.
  dst | destination buffer.
  dst_max_len | destination buffer length (maximum encrypted data size).
  src | message to encrypt.
  src_len | source message length (in bytes).

Returns
  encrypted message length (in bytes), or 0 on error.

## ◆ br_rsa_i32_pkcs1_sign()

uint32_t br_rsa_i32_pkcs1_sign | ( | const unsigned char * | hash_oid,
|  | const unsigned char * | hash,
|  | size_t | hash_len,
|  | const br_rsa_private_key * | sk,
|  | unsigned char * | x
| ) |  |

RSA signature generation engine "i32".

See also
  br_rsa_pkcs1_sign

Parameters

  hash_oid | encoded hash algorithm OID (or `NULL`).
  hash | hash value.
  hash_len | hash value length (in bytes).
  sk | RSA private key.
  x | output buffer for the hash value.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i32_pkcs1_vrfy()

uint32_t br_rsa_i32_pkcs1_vrfy | ( | const unsigned char * | x,
|  | size_t | xlen,
|  | const unsigned char * | hash_oid,
|  | size_t | hash_len,
|  | const br_rsa_public_key * | pk,
|  | unsigned char * | hash_out
| ) |  |

RSA signature verification engine "i32".

See also
  br_rsa_pkcs1_vrfy

Parameters

  x | signature buffer.
  xlen | signature length (in bytes).
  hash_oid | encoded hash algorithm OID (or `NULL`).
  hash_len | expected hash value length (in bytes).
  pk | RSA public key.
  hash_out | output buffer for the hash value.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i32_private()

uint32_t br_rsa_i32_private | ( | unsigned char * | x,
|  | const br_rsa_private_key * | sk
| ) |  |

RSA private key engine "i32".

See also
  br_rsa_private

Parameters

  x | operand to exponentiate.
  sk | RSA private key.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i32_public()

uint32_t br_rsa_i32_public | ( | unsigned char * | x,
|  | size_t | xlen,
|  | const br_rsa_public_key * | pk
| ) |  |

RSA public key engine "i32".

See also
  br_rsa_public

Parameters

  x | operand to exponentiate.
  xlen | length of the operand (in bytes).
  pk | RSA public key.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i62_keygen()

uint32_t br_rsa_i62_keygen | ( | const br_prng_class ** | rng_ctx,
|  | br_rsa_private_key * | sk,
|  | void * | kbuf_priv,
|  | br_rsa_public_key * | pk,
|  | void * | kbuf_pub,
|  | unsigned | size,
|  | uint32_t | pubexp
| ) |  |

RSA key pair generation with the "i62" engine.

This function is defined only on architecture that offer a 64x64->128 opcode. Use `br_rsa_i62_keygen_get()` to dynamically obtain a pointer to that function.

See also
  br_rsa_keygen

Parameters

  rng_ctx | source PRNG context (already initialized)
  sk | RSA private key structure (destination)
  kbuf_priv | buffer for private key elements
  pk | RSA public key structure (destination), or `NULL`
  kbuf_pub | buffer for public key elements, or `NULL`
  size | target RSA modulus size (in bits)
  pubexp | public exponent to use, or zero

Returns
  1 on success, 0 on error (invalid parameters)

## ◆ br_rsa_i62_keygen_get()

br_rsa_keygen br_rsa_i62_keygen_get | ( | void |  | ) |

Get the RSA "i62" implementation (key pair generation), if available.

Returns
  the implementation, or 0.

## ◆ br_rsa_i62_oaep_decrypt()

uint32_t br_rsa_i62_oaep_decrypt | ( | const br_hash_class * | dig,
|  | const void * | label,
|  | size_t | label_len,
|  | const br_rsa_private_key * | sk,
|  | void * | data,
|  | size_t * | len
| ) |  |

RSA decryption (OAEP) with the "i62" engine.

This function is defined only on architecture that offer a 64x64->128 opcode. Use `br_rsa_i62_oaep_decrypt_get()` to dynamically obtain a pointer to that function.

See also
  br_rsa_oaep_decrypt

Parameters

  dig | hash function to use with MGF1.
  label | label value (may be `NULL` if `label_len` is zero).
  label_len | label length, in bytes.
  sk | RSA private key.
  data | input/output buffer.
  len | encrypted/decrypted message length.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i62_oaep_decrypt_get()

br_rsa_oaep_decrypt br_rsa_i62_oaep_decrypt_get | ( | void |  | ) |

Get the RSA "i62" implementation (OAEP decryption), if available.

Returns
  the implementation, or 0.

## ◆ br_rsa_i62_oaep_encrypt()

size_t br_rsa_i62_oaep_encrypt | ( | const br_prng_class ** | rnd,
|  | const br_hash_class * | dig,
|  | const void * | label,
|  | size_t | label_len,
|  | const br_rsa_public_key * | pk,
|  | void * | dst,
|  | size_t | dst_max_len,
|  | const void * | src,
|  | size_t | src_len
| ) |  |

RSA encryption (OAEP) with the "i62" engine.

This function is defined only on architecture that offer a 64x64->128 opcode. Use `br_rsa_i62_oaep_encrypt_get()` to dynamically obtain a pointer to that function.

See also
  br_rsa_oaep_encrypt

Parameters

  rnd | source of random bytes.
  dig | hash function to use with MGF1.
  label | label value (may be `NULL` if `label_len` is zero).
  label_len | label length, in bytes.
  pk | RSA public key.
  dst | destination buffer.
  dst_max_len | destination buffer length (maximum encrypted data size).
  src | message to encrypt.
  src_len | source message length (in bytes).

Returns
  encrypted message length (in bytes), or 0 on error.

## ◆ br_rsa_i62_oaep_encrypt_get()

br_rsa_oaep_encrypt br_rsa_i62_oaep_encrypt_get | ( | void |  | ) |

Get the RSA "i62" implementation (OAEP encryption), if available.

Returns
  the implementation, or 0.

## ◆ br_rsa_i62_pkcs1_sign()

uint32_t br_rsa_i62_pkcs1_sign | ( | const unsigned char * | hash_oid,
|  | const unsigned char * | hash,
|  | size_t | hash_len,
|  | const br_rsa_private_key * | sk,
|  | unsigned char * | x
| ) |  |

RSA signature generation engine "i62".

This function is defined only on architecture that offer a 64x64->128 opcode. Use `br_rsa_i62_pkcs1_sign_get()` to dynamically obtain a pointer to that function.

See also
  br_rsa_pkcs1_sign

Parameters

  hash_oid | encoded hash algorithm OID (or `NULL`).
  hash | hash value.
  hash_len | hash value length (in bytes).
  sk | RSA private key.
  x | output buffer for the hash value.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i62_pkcs1_sign_get()

br_rsa_pkcs1_sign br_rsa_i62_pkcs1_sign_get | ( | void |  | ) |

Get the RSA "i62" implementation (PKCS#1 signature generation), if available.

Returns
  the implementation, or 0.

## ◆ br_rsa_i62_pkcs1_vrfy()

uint32_t br_rsa_i62_pkcs1_vrfy | ( | const unsigned char * | x,
|  | size_t | xlen,
|  | const unsigned char * | hash_oid,
|  | size_t | hash_len,
|  | const br_rsa_public_key * | pk,
|  | unsigned char * | hash_out
| ) |  |

RSA signature verification engine "i62".

This function is defined only on architecture that offer a 64x64->128 opcode. Use `br_rsa_i62_pkcs1_vrfy_get()` to dynamically obtain a pointer to that function.

See also
  br_rsa_pkcs1_vrfy

Parameters

  x | signature buffer.
  xlen | signature length (in bytes).
  hash_oid | encoded hash algorithm OID (or `NULL`).
  hash_len | expected hash value length (in bytes).
  pk | RSA public key.
  hash_out | output buffer for the hash value.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i62_pkcs1_vrfy_get()

br_rsa_pkcs1_vrfy br_rsa_i62_pkcs1_vrfy_get | ( | void |  | ) |

Get the RSA "i62" implementation (PKCS#1 signature verification), if available.

Returns
  the implementation, or 0.

## ◆ br_rsa_i62_private()

uint32_t br_rsa_i62_private | ( | unsigned char * | x,
|  | const br_rsa_private_key * | sk
| ) |  |

RSA private key engine "i62".

This function is defined only on architecture that offer a 64x64->128 opcode. Use `br_rsa_i62_private_get()` to dynamically obtain a pointer to that function.

See also
  br_rsa_private

Parameters

  x | operand to exponentiate.
  sk | RSA private key.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i62_private_get()

br_rsa_private br_rsa_i62_private_get | ( | void |  | ) |

Get the RSA "i62" implementation (private key operations), if available.

Returns
  the implementation, or 0.

## ◆ br_rsa_i62_public()

uint32_t br_rsa_i62_public | ( | unsigned char * | x,
|  | size_t | xlen,
|  | const br_rsa_public_key * | pk
| ) |  |

RSA public key engine "i62".

This function is defined only on architecture that offer a 64x64->128 opcode. Use `br_rsa_i62_public_get()` to dynamically obtain a pointer to that function.

See also
  br_rsa_public

Parameters

  x | operand to exponentiate.
  xlen | length of the operand (in bytes).
  pk | RSA public key.

Returns
  1 on success, 0 on error.

## ◆ br_rsa_i62_public_get()

br_rsa_public br_rsa_i62_public_get | ( | void |  | ) |

Get the RSA "i62" implementation (public key operations), if available.

Returns
  the implementation, or 0.

## ◆ br_rsa_keygen_get_default()

br_rsa_keygen br_rsa_keygen_get_default | ( | void |  | ) |

Get "default" RSA implementation (key pair generation).

This returns the preferred implementation of RSA (key pair generation) on the current system.

Returns
  the default implementation.

## ◆ br_rsa_oaep_decrypt_get_default()

br_rsa_oaep_decrypt br_rsa_oaep_decrypt_get_default | ( | void |  | ) |

Get "default" RSA implementation (OAEP decryption).

This returns the preferred implementation of RSA (OAEP decryption) on the current system.

Returns
  the default implementation.

## ◆ br_rsa_oaep_encrypt_get_default()

br_rsa_oaep_encrypt br_rsa_oaep_encrypt_get_default | ( | void |  | ) |

Get "default" RSA implementation (OAEP encryption).

This returns the preferred implementation of RSA (OAEP encryption) on the current system.

Returns
  the default implementation.

## ◆ br_rsa_pkcs1_sign_get_default()

br_rsa_pkcs1_sign br_rsa_pkcs1_sign_get_default | ( | void |  | ) |

Get "default" RSA implementation (PKCS#1 signature generation).

This returns the preferred implementation of RSA (signature generation) on the current system.

Returns
  the default implementation.

## ◆ br_rsa_pkcs1_vrfy_get_default()

br_rsa_pkcs1_vrfy br_rsa_pkcs1_vrfy_get_default | ( | void |  | ) |

Get "default" RSA implementation (PKCS#1 signature verification).

This returns the preferred implementation of RSA (signature verification) on the current system.

Returns
  the default implementation.

## ◆ br_rsa_private_get_default()

br_rsa_private br_rsa_private_get_default | ( | void |  | ) |

Get "default" RSA implementation (private-key operations).

This returns the preferred implementation of RSA (private-key operations) on the current system.

Returns
  the default implementation.

## ◆ br_rsa_public_get_default()

br_rsa_public br_rsa_public_get_default | ( | void |  | ) |

Get "default" RSA implementation (public-key operations).

This returns the preferred implementation of RSA (public-key operations) on the current system.

Returns
  the default implementation.

## ◆ br_rsa_ssl_decrypt()

uint32_t br_rsa_ssl_decrypt | ( | br_rsa_private | core,
|  | const br_rsa_private_key * | sk,
|  | unsigned char * | data,
|  | size_t | len
| ) |  |

RSA decryption helper, for SSL/TLS.

This function performs the RSA decryption for a RSA-based key exchange in a SSL/TLS server. The provided RSA engine is used. The `data` parameter points to the value to decrypt, of length `len` bytes. On success, the 48-byte pre-master secret is copied into `data`, starting at the first byte of that buffer; on error, the contents of `data` become indeterminate.

This function first checks that the provided value length (`len`) is not lower than 59 bytes, and matches the RSA modulus length; if neither of this property is met, then this function returns 0 and the buffer is unmodified.

Otherwise, decryption and then padding verification are performed, both in constant-time. A decryption error, or a bad padding, or an incorrect decrypted value length are reported with a returned value of 0; on success, 1 is returned. The caller (SSL server engine) is supposed to proceed with a random pre-master secret in case of error.

Parameters

  core | RSA private key engine.
  sk | RSA private key.
  data | input/output buffer.
  len | length (in bytes) of the data to decrypt.

Returns
  1 on success, 0 on error.