Encryption & Signing

Cryptographic operations including encryption, HMAC, JWT, and key derivation. Adapted for workflows.

Loading

local crypto = require("crypto")

Random Generation

Random Bytes

local bytes, err = crypto.random.bytes(32)
Parameter Type Description
length integer Number of bytes (1 to 1,048,576)

Returns: string, error

Random String

local str, err = crypto.random.string(32)
local str, err = crypto.random.string(32, "0123456789abcdef")
Parameter Type Description
length integer String length (1 to 1,048,576)
charset string? Characters to use (default: alphanumeric)

Returns: string, error

Random UUID

local id, err = crypto.random.uuid()

Returns: string, error

HMAC

HMAC-SHA256

local hex, err = crypto.hmac.sha256(key, data)
Parameter Type Description
key string HMAC key
data string Data to authenticate

Returns: string, error

HMAC-SHA512

local hex, err = crypto.hmac.sha512(key, data)
Parameter Type Description
key string HMAC key
data string Data to authenticate

Returns: string, error

Encryption

AES-GCM {id="encrypt-aes-gcm"}

local encrypted, err = crypto.encrypt.aes(data, key)
local encrypted, err = crypto.encrypt.aes(data, key, aad)
Parameter Type Description
data string Plaintext to encrypt
key string 16, 24, or 32 bytes (AES-128/192/256)
aad string? Additional authenticated data

Returns: string, error (nonce prepended)

ChaCha20-Poly1305 {id="encrypt-chacha20"}

local encrypted, err = crypto.encrypt.chacha20(data, key)
local encrypted, err = crypto.encrypt.chacha20(data, key, aad)
Parameter Type Description
data string Plaintext to encrypt
key string Must be 32 bytes
aad string? Additional authenticated data

Returns: string, error

Decryption

AES-GCM {id="decrypt-aes-gcm"}

local plaintext, err = crypto.decrypt.aes(encrypted, key)
local plaintext, err = crypto.decrypt.aes(encrypted, key, aad)
Parameter Type Description
data string Encrypted data from encrypt.aes
key string Same key used for encryption
aad string? Must match AAD used in encryption

Returns: string, error

ChaCha20-Poly1305 {id="decrypt-chacha20"}

local plaintext, err = crypto.decrypt.chacha20(encrypted, key)
local plaintext, err = crypto.decrypt.chacha20(encrypted, key, aad)
Parameter Type Description
data string Encrypted data from encrypt.chacha20
key string Same key used for encryption
aad string? Must match AAD used in encryption

Returns: string, error

JWT

Encode

local token, err = crypto.jwt.encode(payload, secret)
local token, err = crypto.jwt.encode(payload, secret, "HS256")
local token, err = crypto.jwt.encode(payload, private_key_pem, "RS256")
Parameter Type Description
payload table JWT claims (_header for custom header)
key string Secret (HMAC) or PEM private key (RSA)
alg string? HS256, HS384, HS512, RS256 (default: HS256)

Returns: string, error

Verify

local claims, err = crypto.jwt.verify(token, secret)
local claims, err = crypto.jwt.verify(token, secret, "HS256", false)
local claims, err = crypto.jwt.verify(token, public_key_pem, "RS256")
Parameter Type Description
token string JWT token to verify
key string Secret (HMAC) or PEM public key (RSA)
alg string? Expected algorithm (default: HS256)
require_exp boolean? Validate expiration (default: true)

Returns: table, error

Key Derivation

PBKDF2

local key, err = crypto.pbkdf2(password, salt, iterations, key_length)
local key, err = crypto.pbkdf2(password, salt, iterations, key_length, "sha512")
Parameter Type Description
password string Password/passphrase
salt string Salt value
iterations integer Iteration count (max 10,000,000)
key_length integer Desired key length in bytes
hash string? sha256 or sha512 (default: sha256)

Returns: string, error

Utility

Constant-Time Compare

local equal = crypto.constant_time_compare(a, b)
Parameter Type Description
a string First string
b string Second string

Returns: boolean

Errors

Condition Kind Retryable
Invalid length errors.INVALID no
Empty key errors.INVALID no
Invalid key size errors.INVALID no
Decryption failed errors.INTERNAL no
Token expired errors.INTERNAL no

See Error Handling for working with errors.