kryptos/rsa

RSA (Rivest-Shamir-Adleman) cryptography.

This module provides RSA key generation, signing, and encryption operations. RSA keys can be used for both digital signatures and encryption.

Key Generation

import kryptos/rsa

let assert Ok(#(private_key, public_key)) = rsa.generate_key_pair(2048)

Signing (RSA-PSS)

import kryptos/rsa
import kryptos/hash

let assert Ok(#(private_key, public_key)) = rsa.generate_key_pair(2048)
let message = <<"hello world":utf8>>
let padding = rsa.Pss(rsa.SaltLengthHashLen)
let signature = rsa.sign(private_key, message, hash.Sha256, padding)
let valid = rsa.verify(public_key, message, signature, hash.Sha256, padding)

Encryption (RSA-OAEP)

import kryptos/rsa
import kryptos/hash

let assert Ok(#(private_key, public_key)) = rsa.generate_key_pair(2048)
let plaintext = <<"secret":utf8>>
let padding = rsa.Oaep(hash: hash.Sha256, label: <<>>)
let assert Ok(ciphertext) = rsa.encrypt(public_key, plaintext, padding)
let assert Ok(decrypted) = rsa.decrypt(private_key, ciphertext, padding)

Types

EncryptPadding

</>

Padding scheme for RSA encryption.

pub type EncryptPadding {
  EncryptPkcs1v15
  Oaep(hash: hash.HashAlgorithm, label: BitArray)
}

Constructors

```
EncryptPkcs1v15
```
PKCS#1 v1.5 encryption padding.

Warning: Vulnerable to padding oracle attacks. Prefer OAEP for new applications.

JavaScript target: Decryption may fail on Node.js 20.x due to CVE-2023-46809 which disables PKCS#1 v1.5 decryption to prevent the Marvin timing attack. Use Node.js 22+ or OAEP padding instead.
```
Oaep(hash: hash.HashAlgorithm, label: BitArray)
```
RSA-OAEP (Optimal Asymmetric Encryption Padding).

The hash algorithm is used for both OAEP and MGF1. The label is optional associated data (usually empty).

PrivateKey

</>

An RSA private key.

pub type PrivateKey

PrivateKeyFormat

</>

Format for encoding/decoding RSA private keys.

pub type PrivateKeyFormat {
  Pkcs8
  Pkcs1
}

Constructors

```
Pkcs8
```
PKCS#8 format (PrivateKeyInfo) - works with all key types.
```
Pkcs1
```
PKCS#1 format (RSAPrivateKey) - RSA-specific.

PssSaltLength

</>

Salt length options for RSA-PSS signatures.

pub type PssSaltLength {
  SaltLengthHashLen
  SaltLengthMax
  SaltLengthExplicit(Int)
}

Constructors

```
SaltLengthHashLen
```
Salt length equals hash output length (recommended).
```
SaltLengthMax
```
Maximum salt length for the key and hash combination.
```
SaltLengthExplicit(Int)
```
Explicit salt length in bytes.

PublicKey

</>

An RSA public key.

pub type PublicKey

PublicKeyFormat

</>

Format for encoding/decoding RSA public keys.

pub type PublicKeyFormat {
  Spki
  RsaPublicKey
}

Constructors

```
Spki
```
SPKI format (SubjectPublicKeyInfo) - works with all key types.
```
RsaPublicKey
```
PKCS#1 format (RSAPublicKey) - RSA-specific.

SignPadding

</>

Padding scheme for RSA signatures.

pub type SignPadding {
  Pkcs1v15
  Pss(PssSaltLength)
}

Constructors

```
Pkcs1v15
```
PKCS#1 v1.5 signature padding.
```
Pss(PssSaltLength)
```
RSA-PSS (Probabilistic Signature Scheme) padding.

Values

decrypt

</>

pub fn decrypt(
  private_key: PrivateKey,
  ciphertext: BitArray,
  padding: EncryptPadding,
) -> Result(BitArray, Nil)

Decrypts data using RSA with the specified padding scheme.

Parameters

private_key: The RSA private key
ciphertext: The encrypted data
padding: The encryption padding scheme (must match encryption)

Returns

Ok(plaintext) on success, Error(Nil) on decryption failure.

encrypt

</>

pub fn encrypt(
  public_key: PublicKey,
  plaintext: BitArray,
  padding: EncryptPadding,
) -> Result(BitArray, Nil)

Encrypts data using RSA with the specified padding scheme.

Note: RSA encryption should only be used for small amounts of data (typically symmetric keys). For bulk encryption, use a symmetric cipher with a randomly generated key, then encrypt that key with RSA.

Parameters

public_key: The RSA public key
plaintext: The data to encrypt
padding: The encryption padding scheme (EncryptPkcs1v15 or Oaep)

Returns

Ok(ciphertext) on success, Error(Nil) if plaintext is too long.

from_der

</>

pub fn from_der(
  der: BitArray,
  format: PrivateKeyFormat,
) -> Result(#(PrivateKey, PublicKey), Nil)

Imports an RSA private key from DER-encoded data.

Parameters

der: DER-encoded key data
format: The key format (Pkcs8 or Pkcs1)

Returns

Ok(#(private_key, public_key)) on success, Error(Nil) on failure.

from_pem

</>

pub fn from_pem(
  pem: String,
  format: PrivateKeyFormat,
) -> Result(#(PrivateKey, PublicKey), Nil)

Imports an RSA private key from PEM-encoded data.

Parameters

pem: PEM-encoded key string
format: The key format (Pkcs8 or Pkcs1)

Returns

Ok(#(private_key, public_key)) on success, Error(Nil) on failure.

generate_key_pair

</>

pub fn generate_key_pair(
  bits: Int,
) -> Result(#(PrivateKey, PublicKey), Nil)

Generates an RSA key pair with the specified key size.

The key can be used for both signing and encryption operations.

Parameters

bits: The key size in bits (must be >= 1024)

Returns

Ok(#(private_key, public_key)) on success, Error(Nil) if bits < 1024.

Example

let assert Ok(#(private_key, public_key)) = rsa.generate_key_pair(2048)

min_key_size

</>

pub const min_key_size: Int

The minimum allowed RSA key size in bits.

public_key_from_der

</>

pub fn public_key_from_der(
  der: BitArray,
  format: PublicKeyFormat,
) -> Result(PublicKey, Nil)

Imports an RSA public key from DER-encoded data.

Parameters

der: DER-encoded key data
format: The key format (Spki or RsaPublicKey)

Returns

Ok(public_key) on success, Error(Nil) on failure.

public_key_from_pem

</>

pub fn public_key_from_pem(
  pem: String,
  format: PublicKeyFormat,
) -> Result(PublicKey, Nil)

Imports an RSA public key from PEM-encoded data.

Parameters

pem: PEM-encoded key string
format: The key format (Spki or RsaPublicKey)

Returns

Ok(public_key) on success, Error(Nil) on failure.

public_key_from_private_key

</>

pub fn public_key_from_private_key(key: PrivateKey) -> PublicKey

Derives the public key from an RSA private key.

Parameters

key: The private key

Returns

The corresponding public key.

public_key_to_der

</>

pub fn public_key_to_der(
  key: PublicKey,
  format: PublicKeyFormat,
) -> Result(BitArray, Nil)

Exports an RSA public key to DER format.

Parameters

key: The public key to export
format: The output format (Spki or RsaPublicKey)

Returns

Ok(der_data) on success, Error(Nil) on failure.

public_key_to_pem

</>

pub fn public_key_to_pem(
  key: PublicKey,
  format: PublicKeyFormat,
) -> Result(String, Nil)

Exports an RSA public key to PEM format.

Parameters

key: The public key to export
format: The output format (Spki or RsaPublicKey)

Returns

Ok(pem_string) on success, Error(Nil) on failure.

sign

</>

pub fn sign(
  private_key: PrivateKey,
  message: BitArray,
  hash: hash.HashAlgorithm,
  padding: SignPadding,
) -> BitArray

Signs a message using RSA with the specified hash algorithm and padding.

The message is hashed internally using the provided algorithm before signing.

Parameters

private_key: An RSA private key
message: The message to sign (any length)
hash: The hash algorithm to use
padding: The signature padding scheme (Pkcs1v15 or Pss)

Returns

The RSA signature.

to_der

</>

pub fn to_der(
  key: PrivateKey,
  format: PrivateKeyFormat,
) -> Result(BitArray, Nil)

Exports an RSA private key to DER format.

Parameters

key: The private key to export
format: The output format (Pkcs8 or Pkcs1)

Returns

Ok(der_data) on success, Error(Nil) on failure.

to_pem

</>

pub fn to_pem(
  key: PrivateKey,
  format: PrivateKeyFormat,
) -> Result(String, Nil)

Exports an RSA private key to PEM format.

Parameters

key: The private key to export
format: The output format (Pkcs8 or Pkcs1)

Returns

Ok(pem_string) on success, Error(Nil) on failure.

verify

</>

pub fn verify(
  public_key: PublicKey,
  message message: BitArray,
  signature signature: BitArray,
  hash hash: hash.HashAlgorithm,
  padding padding: SignPadding,
) -> Bool

Verifies an RSA signature against a message.

The message is hashed internally using the provided algorithm before verification. The same hash algorithm and padding used during signing must be used for verification.

Parameters

public_key: The RSA public key corresponding to the signing key
message: The original message that was signed
signature: The signature to verify
hash: The hash algorithm used during signing
padding: The signature padding scheme used during signing

Returns

True if the signature is valid, False otherwise.