# `./fio-stl/155 rsa.h`

9 public symbols.

### Macros

#### `FIO_RSA_MAX_BITS`

```c
#define FIO_RSA_MAX_BITS 4096
```

Maximum RSA key size in bits

_Symbol type:_ `macro`

#### `FIO_RSA_MAX_BYTES`

```c
#define FIO_RSA_MAX_BYTES (FIO_RSA_MAX_BITS / 8)
```

Maximum RSA key size in bytes

_Symbol type:_ `macro`

#### `FIO_RSA_MAX_WORDS`

```c
#define FIO_RSA_MAX_WORDS (FIO_RSA_MAX_BYTES / 8)
```

Maximum RSA key size in 64-bit words

_Symbol type:_ `macro`

### Types

#### `fio_rsa_hash_e`

```c
typedef enum {
FIO_RSA_HASH_SHA256 = 0, /**< SHA-256 (32 bytes) */
FIO_RSA_HASH_SHA384 = 1, /**< SHA-384 (48 bytes) */
FIO_RSA_HASH_SHA512 = 2, /**< SHA-512 (64 bytes) */
} fio_rsa_hash_e
```

Hash algorithm identifiers for RSA verification

_Symbol type:_ `type`

#### `fio_rsa_pubkey_s`

```c
typedef struct {
const uint8_t *n; /**< Modulus (big-endian) */
size_t n_len; /**< Modulus length in bytes */
const uint8_t *e; /**< Public exponent (big-endian) */
size_t e_len; /**< Exponent length in bytes */
} fio_rsa_pubkey_s
```

RSA public key for signature verification.

The modulus (n) and exponent (e) are stored as big-endian byte arrays.
This matches the DER encoding used in X.509 certificates.

_Symbol type:_ `type`

#### `fio_rsa_privkey_s`

```c
typedef struct {
const uint8_t *n; /**< Modulus (big-endian) */
size_t n_len; /**< Modulus length in bytes (256, 384, or 512) */
const uint8_t *d; /**< Private exponent (big-endian) */
size_t d_len; /**< Private exponent length in bytes */
const uint8_t *e; /**< Public exponent (big-endian), optional, for blinding */
size_t e_len;
const uint8_t *p; /**< Prime p (big-endian), optional, for CRT */
size_t p_len;
const uint8_t *q; /**< Prime q (big-endian), optional, for CRT */
size_t q_len;
const uint8_t *dP; /**< d mod (p-1) (big-endian), optional, for CRT */
size_t dP_len;
const uint8_t *dQ; /**< d mod (q-1) (big-endian), optional, for CRT */
size_t dQ_len;
const uint8_t *qInv; /**< q^-1 mod p (big-endian), optional, for CRT */
size_t qInv_len;
} fio_rsa_privkey_s
```

RSA private key for signature generation.

The modulus (n) and private exponent (d) are stored as big-endian byte
arrays. This matches the DER encoding used in PKCS#8 private keys.

Optional CRT parameters (p, q, dP, dQ, qInv) and the public exponent (e)
may be provided. When CRT parameters are available, signing uses CRT with
message blinding for better side-channel resistance. When only n and d are
available, signing falls back to a non-CRT (still constant-time) path.

All optional fields are indicated by a non-zero length. Missing CRT
parameters may be derived from p, q, and d when p and q are present.

_Symbol type:_ `type`

### Functions

#### `fio_rsa_verify_pkcs1`

```c
int fio_rsa_verify_pkcs1(const uint8_t *sig, size_t sig_len, const uint8_t *msg_hash, size_t hash_len, fio_rsa_hash_e hash_alg, const fio_rsa_pubkey_s *key)
```

Verify an RSA PKCS#1 v1.5 signature.

This verifies signatures with DigestInfo encoding as used in:
- sha256WithRSAEncryption (OID 1.2.840.113549.1.1.11)
- sha384WithRSAEncryption (OID 1.2.840.113549.1.1.12)
- sha512WithRSAEncryption (OID 1.2.840.113549.1.1.13)

**Parameters:**
- `sig` - Signature bytes (same length as modulus)
- `sig_len` - Signature length in bytes
- `msg_hash` - Pre-computed hash of the message
- `hash_len` - Hash length (32, 48, or 64 bytes)
- `hash_alg` - Hash algorithm used (FIO_RSA_HASH_SHA256, etc.)
- `key` - RSA public key

**Returns:**
- 0 on success (valid signature), -1 on failure

_Symbol type:_ `function`

#### `fio_rsa_verify_pss`

```c
int fio_rsa_verify_pss(const uint8_t *sig, size_t sig_len, const uint8_t *msg_hash, size_t hash_len, fio_rsa_hash_e hash_alg, const fio_rsa_pubkey_s *key)
```

Verify an RSA-PSS signature (required for TLS 1.3).

RSA-PSS uses probabilistic padding and is the mandatory signature scheme
for TLS 1.3 CertificateVerify messages with RSA keys.

This implementation uses:
- MGF1 with the same hash function
- Salt length = hash length (as required by TLS 1.3)
- Trailer field = 0xBC

**Parameters:**
- `sig` - Signature bytes (same length as modulus)
- `sig_len` - Signature length in bytes
- `msg_hash` - Pre-computed hash of the message
- `hash_len` - Hash length (32, 48, or 64 bytes)
- `hash_alg` - Hash algorithm used
- `key` - RSA public key

**Returns:**
- 0 on success (valid signature), -1 on failure

_Symbol type:_ `function`

#### `fio_rsa_sign_pss`

```c
int fio_rsa_sign_pss(uint8_t *signature, size_t *sig_len, const uint8_t *msg_hash, size_t hash_len, fio_rsa_hash_e hash_alg, const fio_rsa_privkey_s *key)
```

Generate an RSA-PSS signature (RSASSA-PSS-SIGN per RFC 8017 Section 8.1.1).

This is required for TLS 1.3 server CertificateVerify messages when using
RSA certificates. PKCS#1 v1.5 signatures are NOT allowed for
CertificateVerify in TLS 1.3.

This implementation uses:
- MGF1 with the same hash function
- Salt length = hash length (as required by TLS 1.3)
- Trailer field = 0xBC

**Parameters:**
- `signature` - Output buffer for signature (must be key->n_len bytes)
- `sig_len` - Output: actual signature length (equals key->n_len)
- `msg_hash` - Pre-computed hash of the message to sign
- `hash_len` - Hash length (32, 48, or 64 bytes)
- `hash_alg` - Hash algorithm (FIO_RSA_HASH_SHA256, etc.)
- `key` - RSA private key

**Returns:**
- 0 on success, -1 on error

_Symbol type:_ `function`

-----------------------------------------------------