facil.io
API Reference

#./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