Crypto Library

Cryptographic primitives and encryption

Overview

The crypto table provides comprehensive cryptographic functions for sandboxed applications, including symmetric encryption, hashing, key derivation, asymmetric cryptography, and post-quantum algorithms.

Key Management

Function	Description
`crypto.generateKey()`	Generate random 32-byte key (binary)
`crypto.generateKeyString()`	Generate random key as base64 string
`crypto.deriveKey(password)`	Derive key from password using Argon2id (recommended)

Symmetric Encryption (AEAD)

All encryption functions use authenticated encryption (AEAD). Encrypted output format:

[Nonce][Tag][Ciphertext]

AES-256-GCM (Default - Hardware Accelerated)

Function	Description
`crypto.encrypt(key, plaintext, [len])`	Encrypt, returns table with :raw(), :base64(), :hex()
`crypto.decrypt(key, encrypted)`	Decrypt, returns plaintext
`crypto.encryptString(key, plaintext)`	Encrypt, returns base64 string
`crypto.decryptString(key, base64)`	Decrypt from base64
`crypto.AES.*`	Same functions via AES subtable

AES-128-GCM

Function	Description
`crypto.AES128.encrypt(key, plaintext, [len])`	Encrypt with 16-byte key
`crypto.AES128.decrypt(key, encrypted)`	Decrypt
`crypto.AES128.encryptString(key, plaintext)`	Encrypt to base64
`crypto.AES128.decryptString(key, base64)`	Decrypt from base64

ChaCha20-Poly1305 (Fast Software)

Function	Description
`crypto.encryptChaCha(key, plaintext, [len])`	Encrypt with ChaCha20
`crypto.decryptChaCha(key, encrypted)`	Decrypt
`crypto.encryptChaChaString(key, plaintext)`	Encrypt to base64
`crypto.decryptChaChaString(key, base64)`	Decrypt from base64
`crypto.ChaCha20.*`	Same functions via ChaCha20 subtable

XChaCha20-Poly1305 (Extended Nonce)

Function	Description
`crypto.encryptXChaCha(key, plaintext, [len])`	Encrypt with 192-bit nonce
`crypto.decryptXChaCha(key, encrypted)`	Decrypt
`crypto.encryptXChaChaString(key, plaintext)`	Encrypt to base64
`crypto.decryptXChaChaString(key, base64)`	Decrypt from base64
`crypto.XChaCha20.*`	Same functions via XChaCha20 subtable

Serpent-256-GCM (Conservative)

Function	Description
`crypto.encryptSerpent(key, plaintext, [len])`	Encrypt with Serpent
`crypto.decryptSerpent(key, encrypted)`	Decrypt
`crypto.encryptSerpentString(key, plaintext)`	Encrypt to base64
`crypto.decryptSerpentString(key, base64)`	Decrypt from base64
`crypto.Serpent.*`	Same functions via Serpent subtable

Twofish-256-GCM

Function	Description
`crypto.encryptTwofish(key, plaintext, [len])`	Encrypt with Twofish
`crypto.decryptTwofish(key, encrypted)`	Decrypt
`crypto.encryptTwofishString(key, plaintext)`	Encrypt to base64
`crypto.decryptTwofishString(key, base64)`	Decrypt from base64
`crypto.Twofish.*`	Same functions via Twofish subtable

Salsa20-Poly1305

Function	Description
`crypto.encryptSalsa(key, plaintext, [len])`	Encrypt with Salsa20
`crypto.decryptSalsa(key, encrypted)`	Decrypt
`crypto.encryptSalsaString(key, plaintext)`	Encrypt to base64
`crypto.decryptSalsaString(key, base64)`	Decrypt from base64
`crypto.Salsa20.*`	Same functions via Salsa20 subtable

Hashing

Function	Description
`crypto.hash(data)`	SHA-256 hash (default)
`crypto.hash.SHA512(data)`	SHA-512 hash
`crypto.hash.SHA1(data)`	SHA-1 hash (legacy)
`crypto.hash.MD5(data)`	MD5 hash (legacy)
`crypto.hash.CRC32(data)`	CRC32 checksum
`crypto.hash.SHA3(data)` / `crypto.hash.SHA3_256(data)`	SHA3-256 hash
`crypto.hash.SHA3_512(data)`	SHA3-512 hash
`crypto.hash.BLAKE2b(data)` / `crypto.hash.BLAKE2b_256(data)`	BLAKE2b-256 hash
`crypto.hash.BLAKE2b_512(data)`	BLAKE2b-512 hash

Key Derivation

PBKDF2

Function	Description
`crypto.PBKDF2.deriveKey(password, salt, [iterations], [keylen])`	Derive key from password
`crypto.PBKDF2.deriveKeyString(password, salt, [iterations])`	Derive key as base64
`crypto.PBKDF2.generateSalt([length])`	Generate random salt

Argon2 (Recommended for Passwords)

Function	Description
`crypto.Argon2.deriveKey(password, salt, [options])`	Derive key with Argon2id
`crypto.Argon2.generateSalt([length])`	Generate random salt

HKDF (Key Expansion)

Function	Description
`crypto.HKDF.deriveKey(ikm, salt, info, length)`	Derive key using HKDF

Elliptic Curve Cryptography

X25519 (Key Exchange)

Function	Description
`crypto.X25519.keypair()`	Generate keypair, returns {public, private}
`crypto.X25519.publicKey(private_key)`	Derive public key from private
`crypto.X25519.sharedSecret(my_private, their_public)`	Compute shared secret

Ed25519 (Digital Signatures)

Function	Description
`crypto.Ed25519.keypair()`	Generate keypair, returns {public, private}
`crypto.Ed25519.sign(private_key, message)`	Sign message
`crypto.Ed25519.verify(public_key, message, signature)`	Verify signature

P-256 / secp256r1 (NIST Curve)

Function	Description
`crypto.P256.ecdhKeypair()`	Generate ECDH keypair
`crypto.P256.ecdhPublicKey(private_key)`	Derive ECDH public key
`crypto.P256.ecdhSharedSecret(my_private, their_public)`	Compute shared secret
`crypto.P256.ecdsaKeypair()`	Generate ECDSA keypair
`crypto.P256.ecdsaSign(private_key, message_hash)`	Sign with ECDSA
`crypto.P256.ecdsaVerify(public_key, message_hash, signature)`	Verify ECDSA signature

RSA

Function	Description
`crypto.RSA.generateKeypair([bits])`	Generate RSA keypair
`crypto.RSA.encrypt(public_key, plaintext)`	Encrypt with public key
`crypto.RSA.decrypt(private_key, ciphertext)`	Decrypt with private key
`crypto.RSA.sign(private_key, message)`	Sign with PKCS#1 v1.5
`crypto.RSA.verify(public_key, message, signature)`	Verify PKCS#1 v1.5
`crypto.RSA.signPSS(private_key, message)`	Sign with PSS padding
`crypto.RSA.verifyPSS(public_key, message, signature)`	Verify PSS signature

Post-Quantum Cryptography (CRYSTALS)

Kyber (Key Encapsulation)

Function	Security Level	Description
`crypto.Kyber.keypair()` / `crypto.Kyber.keypair768()`	Level 3 (Recommended)	Generate keypair
`crypto.Kyber.encapsulate()` / `crypto.Kyber.encapsulate768()`	Level 3	Encapsulate shared secret
`crypto.Kyber.decapsulate()` / `crypto.Kyber.decapsulate768()`	Level 3	Decapsulate shared secret
`crypto.Kyber.keypair512()`	Level 1	Generate Kyber-512 keypair
`crypto.Kyber.encapsulate512(public_key)`	Level 1	Encapsulate with Kyber-512
`crypto.Kyber.decapsulate512(private_key, ciphertext)`	Level 1	Decapsulate with Kyber-512
`crypto.Kyber.keypair1024()`	Level 5	Generate Kyber-1024 keypair
`crypto.Kyber.encapsulate1024(public_key)`	Level 5	Encapsulate with Kyber-1024
`crypto.Kyber.decapsulate1024(private_key, ciphertext)`	Level 5	Decapsulate with Kyber-1024

Dilithium (Digital Signatures)

Function	Security Level	Description
`crypto.Dilithium.keypair()` / `crypto.Dilithium.keypair3()`	Level 3 (Recommended)	Generate keypair
`crypto.Dilithium.sign()` / `crypto.Dilithium.sign3()`	Level 3	Sign message
`crypto.Dilithium.verify()` / `crypto.Dilithium.verify3()`	Level 3	Verify signature
`crypto.Dilithium.keypair2()`	Level 2	Generate Dilithium2 keypair
`crypto.Dilithium.sign2(private_key, message)`	Level 2	Sign with Dilithium2
`crypto.Dilithium.verify2(public_key, message, signature)`	Level 2	Verify Dilithium2
`crypto.Dilithium.keypair5()`	Level 5	Generate Dilithium5 keypair
`crypto.Dilithium.sign5(private_key, message)`	Level 5	Sign with Dilithium5
`crypto.Dilithium.verify5(public_key, message, signature)`	Level 5	Verify Dilithium5

CSPRNG (Cryptographically Secure Random)

Function	Description
`crypto.CSPRNG.randomBytes(length)`	Generate random bytes
`crypto.CSPRNG.newKey()`	Generate random 32-byte key
`crypto.CSPRNG.new()`	Create new CSPRNG instance

Usage Examples

-- Symmetric encryption with AES
local key = crypto.generateKey()
local encrypted = crypto.encrypt(key, "Hello, World!")
local decrypted = crypto.decrypt(key, encrypted)

-- String-based API
local key64 = crypto.generateKeyString()
local encrypted64 = crypto.encryptString(key64, "Secret message")
local decrypted = crypto.decryptString(key64, encrypted64)

-- Password-based encryption
local key = crypto.deriveKey("mypassword")  -- Uses Argon2id
local encrypted = crypto.encrypt(key, data)

-- Digital signatures with Ed25519
local keys = crypto.Ed25519.keypair()
local signature = crypto.Ed25519.sign(keys.private, "message")
local valid = crypto.Ed25519.verify(keys.public, "message", signature)

-- Key exchange with X25519
local alice = crypto.X25519.keypair()
local bob = crypto.X25519.keypair()
local shared_alice = crypto.X25519.sharedSecret(alice.private, bob.public)
local shared_bob = crypto.X25519.sharedSecret(bob.private, alice.public)
-- shared_alice == shared_bob

-- Post-quantum key exchange with Kyber
local keys = crypto.Kyber.keypair()
local ct, shared1 = crypto.Kyber.encapsulate(keys.public)
local shared2 = crypto.Kyber.decapsulate(keys.private, ct)
-- shared1 == shared2

-- Post-quantum signatures with Dilithium
local keys = crypto.Dilithium.keypair()
local sig = crypto.Dilithium.sign(keys.private, "message")
local valid = crypto.Dilithium.verify(keys.public, "message", sig)