@eryx/crypto/hazmat/rsa Module

JSON

RSA asymmetric cryptography.

Provides key generation, PEM/DER conversion, PKCS#1 v1.5 and OAEP encryption/decryption, and both PKCS#1 v1.5 and PSS signing/verification.

Keys are represented as PEM strings (the standard -----BEGIN RSA PRIVATE KEY----- / -----BEGIN PUBLIC KEY----- format). Use privateToDer / publicToDer to convert to raw DER bytes, or @eryx/crypto/pem to wrap/unwrap arbitrary DER blobs.

local rsa = require("@eryx/crypto/hazmat/rsa")

-- Generate a 2048-bit key pair
local priv = rsa.generateKey(2048)
local pub  = rsa.getPublicPem(priv)

-- Encrypt / decrypt with OAEP
local ct = rsa.encryptOaep(pub,  buffer.fromstring("hello"))
local pt = rsa.decryptOaep(priv, ct)
assert(buffer.tostring(pt) == "hello")

-- Sign / verify
local sig = rsa.signPkcs1(priv, buffer.fromstring("message"))
assert(rsa.verifyPkcs1(pub, buffer.fromstring("message"), sig))

Summary

Functions

rsa.generateKey(bits: number?) → string
rsa.getPublicPem(private_pem: string) → string
rsa.encryptPkcs1(public_pem: string, data: buffer) → buffer
rsa.decryptPkcs1(private_pem: string, data: buffer) → buffer
rsa.encryptOaep(public_pem: string, data: buffer, hash: string?) → buffer
rsa.decryptOaep(private_pem: string, data: buffer, hash: string?) → buffer
rsa.signPkcs1(private_pem: string, data: buffer, hash: string?) → buffer
rsa.verifyPkcs1(public_pem: string, data: buffer, signature: buffer, hash: string?) → boolean
rsa.signPss(private_pem: string, data: buffer, hash: string?) → buffer
rsa.verifyPss(public_pem: string, data: buffer, signature: buffer, hash: string?) → boolean
rsa.privateToDer(private_pem: string) → buffer
rsa.publicToDer(public_pem: string) → buffer
rsa.privateFromDer(der: buffer) → string
rsa.publicFromDer(der: buffer) → string
rsa.getKeyBits(pem: string) → number

API Reference

Functions

rsa.generateKey

Generates a new RSA private key and returns it as a PEM string.

The key includes all parameters needed for both encryption and signing. Extract the corresponding public key with getPublicPem.

local priv = rsa.generateKey(2048)
local pub  = rsa.getPublicPem(priv)
rsa.generateKey(bits: number?) → string

Parameters

bits: number?

Key size in bits. Defaults to 2048. Common values: 2048, 3072, 4096.

Returns

string

PEM-encoded RSA private key.

rsa.getPublicPem

Derives the public key from a PEM-encoded RSA private key.

rsa.getPublicPem(private_pem: string) → string

Parameters

private_pem: string

PEM-encoded RSA private key.

Returns

string

PEM-encoded RSA public key.

rsa.encryptPkcs1

Encrypts data using RSA-PKCS#1 v1.5.

PKCS#1 v1.5 encryption is widely supported but has known weaknesses (ROBOT attack, Bleichenbacher oracle). Prefer encryptOaep for new designs.

Maximum plaintext size: key_bytes - 11.

rsa.encryptPkcs1(public_pem: string, data: buffer) → buffer

Parameters

public_pem: string

PEM-encoded RSA public key.

data: buffer

Plaintext to encrypt.

Returns

buffer

Ciphertext (same length as the key modulus).

rsa.decryptPkcs1

Decrypts RSA-PKCS#1 v1.5 ciphertext.

rsa.decryptPkcs1(private_pem: string, data: buffer) → buffer

Parameters

private_pem: string

PEM-encoded RSA private key.

data: buffer

Ciphertext to decrypt.

Returns

buffer

Plaintext.

rsa.encryptOaep

Encrypts data using RSA-OAEP.

OAEP (Optimal Asymmetric Encryption Padding) is the modern, secure RSA encryption scheme. Use "sha256" (the default) or "sha1" for the OAEP hash parameter.

Maximum plaintext size: key_bytes - 2 * hash_bytes - 2. For a 2048-bit key with SHA-256: 256 - 2×32 - 2 = 190 bytes.

rsa.encryptOaep(public_pem: string, data: buffer, hash: string?) → buffer

Parameters

public_pem: string

PEM-encoded RSA public key.

data: buffer

Plaintext to encrypt.

hash: string?

Hash for the OAEP mask - "sha256" (default) or "sha1".

Returns

buffer

Ciphertext.

rsa.decryptOaep

Decrypts RSA-OAEP ciphertext.

rsa.decryptOaep(private_pem: string, data: buffer, hash: string?) → buffer

Parameters

private_pem: string

PEM-encoded RSA private key.

data: buffer

Ciphertext to decrypt.

hash: string?

Hash for the OAEP mask - must match what was used for encryption.

Returns

buffer

Plaintext.

rsa.signPkcs1

Signs data using RSA-PKCS#1 v1.5.

The data is hashed internally before signing. Supported hash values: "sha256" (default), "sha1", "sha384", "sha512".

local sig = rsa.signPkcs1(priv, buffer.fromstring("message"))
assert(rsa.verifyPkcs1(pub, buffer.fromstring("message"), sig))
rsa.signPkcs1(private_pem: string, data: buffer, hash: string?) → buffer

Parameters

private_pem: string

PEM-encoded RSA private key.

data: buffer

Message to sign.

hash: string?

Hash algorithm - "sha256" (default), "sha1", "sha384", "sha512".

Returns

buffer

Signature (same length as the key modulus).

rsa.verifyPkcs1

Verifies an RSA-PKCS#1 v1.5 signature.

Returns true if the signature is valid for the given data and public key, false otherwise.

rsa.verifyPkcs1(public_pem: string, data: buffer, signature: buffer, hash: string?) → boolean

Parameters

public_pem: string

PEM-encoded RSA public key.

data: buffer

The original message.

signature: buffer

Signature to verify.

hash: string?

Hash algorithm - must match what was used for signing.

Returns

boolean

true if the signature is valid.

rsa.signPss

Signs data using RSA-PSS (Probabilistic Signature Scheme).

PSS is the modern, preferred RSA signature scheme. Unlike PKCS#1 v1.5, it uses randomized padding and has a formal security proof.

The data is hashed internally before signing. Supported hash values: "sha256" (default), "sha1", "sha384", "sha512".

local sig = rsa.signPss(priv, buffer.fromstring("message"))
assert(rsa.verifyPss(pub, buffer.fromstring("message"), sig))
rsa.signPss(private_pem: string, data: buffer, hash: string?) → buffer

Parameters

private_pem: string

PEM-encoded RSA private key.

data: buffer

Message to sign.

hash: string?

Hash algorithm - "sha256" (default), "sha1", "sha384", "sha512".

Returns

buffer

Signature (same length as the key modulus).

rsa.verifyPss

Verifies an RSA-PSS signature.

Returns true if the signature is valid for the given data and public key, false otherwise.

rsa.verifyPss(public_pem: string, data: buffer, signature: buffer, hash: string?) → boolean

Parameters

public_pem: string

PEM-encoded RSA public key.

data: buffer

The original message.

signature: buffer

Signature to verify.

hash: string?

Hash algorithm - must match what was used for signing.

Returns

boolean

true if the signature is valid.

rsa.privateToDer

Encodes a PEM private key as raw DER bytes.

DER (Distinguished Encoding Rules) is the binary ASN.1 representation that PEM wraps in base64. Use this when a library or protocol requires the raw binary form.

local der = rsa.privateToDer(priv)
local priv2 = rsa.privateFromDer(der)  -- round-trip
rsa.privateToDer(private_pem: string) → buffer

Parameters

private_pem: string

PEM-encoded RSA private key.

Returns

buffer

Raw DER-encoded private key.

rsa.publicToDer

Encodes a PEM public key as raw DER bytes.

rsa.publicToDer(public_pem: string) → buffer

Parameters

public_pem: string

PEM-encoded RSA public key.

Returns

buffer

Raw DER-encoded public key (SubjectPublicKeyInfo format).

rsa.privateFromDer

Parses a DER-encoded RSA private key and returns it as a PEM string.

rsa.privateFromDer(der: buffer) → string

Parameters

der: buffer

Raw DER-encoded RSA private key.

Returns

string

PEM-encoded RSA private key.

rsa.publicFromDer

Parses a DER-encoded RSA public key and returns it as a PEM string.

rsa.publicFromDer(der: buffer) → string

Parameters

der: buffer

Raw DER-encoded RSA public key (SubjectPublicKeyInfo format).

Returns

string

PEM-encoded RSA public key.

rsa.getKeyBits

Returns the key size in bits for a PEM-encoded private or public key.

Useful for validating that a key meets a minimum size requirement before use.

local priv = rsa.generateKey(2048)
assert(rsa.getKeyBits(priv) == 2048)
assert(rsa.getKeyBits(rsa.getPublicPem(priv)) == 2048)
rsa.getKeyBits(pem: string) → number

Parameters

pem: string

PEM-encoded RSA private or public key.

Returns

number

Key size in bits (e.g. 2048, 3072, 4096).