Reference/Libraries/crypt
Library

crypt

table

Hashing, base64 and hex encoding, symmetric and authenticated encryption, key derivation, asymmetric signatures, and secure RNG.

Functions

29

#crypt.hash(data: string | buffer, algorithm: string sha1|sha256|sha384|sha512|md5) → string

since 1.8.3-free

Computes a cryptographic hash and returns the hex digest.

Parameters

datastring | buffer
algorithmstring sha1|sha256|sha384|sha512|md5

Returns

string

Lowercase hex digest.

Errors

  • LuaError invalid algorithm -- Unknown hash algorithm; expected sha1|sha256|sha384|sha512|md5.

#crypt.hash_to_buffer(data: string | buffer, algorithm: string sha1|sha256|sha384|sha512|md5) → buffer

since 1.8.3-free

Computes a cryptographic hash and returns the raw bytes as a buffer.

Aliaseshashtobuffer

Parameters

datastring | buffer
algorithmstring sha1|sha256|sha384|sha512|md5

Errors

  • LuaError invalid algorithm -- Unknown hash algorithm; expected sha1|sha256|sha384|sha512|md5.

#crypt.hmac(data: string | buffer, key: string | buffer, algorithm: string sha1|sha256|sha384|sha512|md5) → string

since 1.8.3-free

Computes an HMAC and returns the hex digest.

Parameters

datastring | buffer
keystring | buffer
algorithmstring sha1|sha256|sha384|sha512|md5

Returns

string

Lowercase hex digest.

Errors

  • LuaError invalid algorithm -- Unknown hash algorithm; expected sha1|sha256|sha384|sha512|md5.

#crypt.hmac_to_buffer(data: string | buffer, key: string | buffer, algorithm: string sha1|sha256|sha384|sha512|md5) → buffer

since 1.8.3-free

Computes an HMAC and returns the raw bytes as a buffer.

Aliaseshmactobuffer

Parameters

datastring | buffer
keystring | buffer
algorithmstring sha1|sha256|sha384|sha512|md5

Errors

  • LuaError invalid algorithm -- Unknown hash algorithm; expected sha1|sha256|sha384|sha512|md5.

#crypt.base64encode(data: string | buffer) → string

since 1.8.3-free

Base64-encodes a string or buffer. Returns the standard (RFC 4648) encoded string with padding.

Aliasesbase64_encode

Parameters

datastring | buffer

#crypt.base64decode(s: string) → buffer

since 1.8.3-free

Base64-decodes a string into a buffer. Tolerates whitespace and padding.

Aliasesbase64_decode

Parameters

sstring

Errors

  • LuaError invalid input -- Input is not valid base64.

#crypt.hexencode(data: string | buffer) → string

since 1.8.3-free

Hex-encodes a string or buffer into a lowercase hex string.

Aliaseshex_encode

Parameters

datastring | buffer

#crypt.hexdecode(s: string) → buffer

since 1.8.3-free

Hex-decodes a string into a buffer. Accepts upper/lowercase; rejects odd-length or non-hex input.

Aliaseshex_decode

Parameters

sstring

Errors

  • LuaError invalid input -- Input is not valid hex (odd length or non-hex character).

#crypt.random(n: number) → buffer

since 1.8.3-free

Returns N cryptographically random bytes from the OS RNG (BCryptGenRandom).

Parameters

nnumber

Byte count.

Errors

  • LuaError rng failure -- OS random number generator failed.

#crypt.generatekey() → string

since 1.8.3-free

Returns a fresh base64-encoded 32-byte (AES-256) key.

Aliasesgenerate_key

Errors

  • LuaError rng failure -- OS random number generator failed.

#crypt.generatebytes(n: number) → buffer

since 1.8.3-free

Convenience: same as crypt.random(n) returning a buffer of N random bytes.

Aliasesgenerate_bytes

Parameters

nnumber

Byte count.

#crypt.encrypt_aes_cbc(plaintext: string | buffer, key: string | buffer, iv: string | buffer) → buffer

since 1.8.3-free

AES-CBC encrypt. Key must be 16/24/32 bytes (AES-128/192/256); IV must be 16 bytes. PKCS#7 padding.

Parameters

plaintextstring | buffer
keystring | buffer
ivstring | buffer

Returns

buffer

Ciphertext.

Errors

  • LuaError invalid key size -- key must be 16, 24, or 32 bytes.
  • LuaError invalid iv size -- iv must be 16 bytes.

#crypt.decrypt_aes_cbc(ciphertext: string | buffer, key: string | buffer, iv: string | buffer) → buffer

since 1.8.3-free

AES-CBC decrypt. Mirrors encrypt_aes_cbc; throws on bad padding or wrong key/iv.

Parameters

ciphertextstring | buffer
keystring | buffer
ivstring | buffer

Returns

buffer

Plaintext.

Errors

  • LuaError invalid key size -- key must be 16, 24, or 32 bytes.
  • LuaError invalid iv size -- iv must be 16 bytes.
  • LuaError bad padding -- Decryption failed; likely wrong key/iv or corrupted ciphertext.

#crypt.encrypt_aes_gcm(plaintext: string | buffer, key: string | buffer, iv: string | buffer, aad: string | buffer | nil) → buffer, buffer ciphertext, tag (16 bytes)

since 1.8.3-free

AES-GCM encrypt with authentication. Key=16/24/32 bytes; IV typically 12 bytes; AAD optional.

Parameters

plaintextstring | buffer
keystring | buffer
ivstring | buffer
aadstring | buffer | nil

Errors

  • LuaError invalid key size -- key must be 16, 24, or 32 bytes.
  • LuaError invalid iv size -- iv must be 1..16 bytes (typically 12).

#crypt.decrypt_aes_gcm(ciphertext: string | buffer, key: string | buffer, iv: string | buffer, tag: string | buffer 16-byte auth tag returned by encrypt., aad: string | buffer | nil) → buffer

since 1.8.3-free

AES-GCM decrypt + verify. Returns plaintext or throws on tag mismatch.

Parameters

ciphertextstring | buffer
keystring | buffer
ivstring | buffer
tagstring | buffer 16-byte auth tag returned by encrypt.
aadstring | buffer | nil

Returns

buffer

Plaintext.

Errors

  • LuaError invalid key size -- key must be 16, 24, or 32 bytes.
  • LuaError invalid iv size -- iv must be 1..16 bytes.
  • LuaError invalid tag size -- tag must be 16 bytes.
  • LuaError auth failed -- GCM authentication tag did not verify.

#crypt.encrypt(plaintext: string | buffer, base64Key: string) → string, string base64 ciphertext, base64 iv.

since 1.8.3-free

Convenience: AES-CBC encrypt with a base64-encoded key, returning base64 ciphertext + base64 IV. Generates a fresh 16-byte IV per call. Compatible with Daily's crypt.encrypt shape.

Parameters

plaintextstring | buffer
base64Keystring

A 16/24/32-byte key encoded as base64.

Errors

  • LuaError invalid input -- key was not valid base64.
  • LuaError rng failure -- OS random number generator failed.
  • LuaError invalid key size -- key must be 16, 24, or 32 bytes.

#crypt.decrypt(base64Ciphertext: string, base64Key: string, base64Iv: string) → buffer

since 1.8.3-free

Convenience: AES-CBC decrypt of base64 ciphertext + base64 iv with a base64 key.

Parameters

base64Ciphertextstring
base64Keystring
base64Ivstring

Returns

buffer

Plaintext.

Errors

  • LuaError invalid input -- ciphertext, key, or iv was not valid base64.
  • LuaError bad padding -- Decryption failed; likely wrong key/iv or corrupted ciphertext.

#crypt.blake3(data: string | buffer, outlen: number?) → string

since 1.8.3-free

BLAKE3 hash. Returns lowercase hex digest of outlen bytes (default 32).

Parameters

datastring | buffer
outlennumber?

Output length in bytes (default 32, must be >= 1).

Errors

  • LuaError invalid outlen -- outlen must be >= 1.

#crypt.blake3_to_buffer(data: string | buffer, outlen: number?) → buffer

since 1.8.3-free

BLAKE3 hash to buffer. Raw digest of outlen bytes (default 32).

Parameters

datastring | buffer
outlennumber?

Output length in bytes (default 32).

Errors

  • LuaError invalid outlen -- outlen must be >= 1.

#crypt.blake3_keyed(data: string | buffer, key: string | buffer 32-byte key., outlen: number?) → string

since 1.8.3-free

BLAKE3 keyed hash with a 32-byte key. Returns lowercase hex digest of outlen bytes (default 32).

Parameters

datastring | buffer
keystring | buffer 32-byte key.
outlennumber?

Default 32.

Errors

  • LuaError invalid key size -- key must be 32 bytes.
  • LuaError invalid outlen -- outlen must be >= 1.

#crypt.blake2b(data: string | buffer, key: string | buffer | nil, outlen: number?) → string

since 1.8.3-free

BLAKE2b hash via libsodium. Returns lowercase hex digest of outlen bytes (default 32, max 64).

Parameters

datastring | buffer
keystring | buffer | nil

Optional key (0-64 bytes) for keyed-hash mode.

outlennumber?

Default 32; must be 16..64.

Errors

  • LuaError libsodium init -- libsodium initialization failed.
  • LuaError invalid outlen -- outlen must be 16..64.
  • LuaError invalid key size -- key longer than the libsodium maximum.

#crypt.chacha20(data: string | buffer, key: string | buffer 32-byte key., nonce: string | buffer 12-byte nonce., counter: number?) → buffer

since 1.8.3-free

ChaCha20 stream-cipher encrypt (IETF variant). Decryption is the same call.

Parameters

datastring | buffer
keystring | buffer 32-byte key.
noncestring | buffer 12-byte nonce.
counternumber?

Initial block counter (default 0).

Errors

  • LuaError libsodium init -- libsodium initialization failed.
  • LuaError invalid key size -- key must be 32 bytes.
  • LuaError invalid nonce size -- nonce must be 12 bytes.

#crypt.chacha20poly1305_encrypt(plaintext: string | buffer, key: string | buffer 32-byte key., nonce: string | buffer 12-byte nonce., aad: string | buffer | nil) → buffer

since 1.8.3-free

ChaCha20-Poly1305 AEAD encrypt (IETF). Returns ciphertext with the 16-byte Poly1305 tag appended.

Parameters

plaintextstring | buffer
keystring | buffer 32-byte key.
noncestring | buffer 12-byte nonce.
aadstring | buffer | nil

Optional additional authenticated data.

Returns

buffer

ciphertext (plaintext.size() + 16 bytes).

Errors

  • LuaError libsodium init -- libsodium initialization failed.
  • LuaError invalid key size -- key must be 32 bytes.
  • LuaError invalid nonce size -- nonce must be 12 bytes.

#crypt.chacha20poly1305_decrypt(ciphertext: string | buffer ciphertext with the 16-byte Poly1305 tag appended., key: string | buffer 32-byte key., nonce: string | buffer 12-byte nonce., aad: string | buffer | nil) → buffer

since 1.8.3-free

ChaCha20-Poly1305 AEAD decrypt + verify (IETF). Errors on auth tag mismatch.

Parameters

ciphertextstring | buffer ciphertext with the 16-byte Poly1305 tag appended.
keystring | buffer 32-byte key.
noncestring | buffer 12-byte nonce.
aadstring | buffer | nil

Optional additional authenticated data.

Returns

buffer

plaintext.

Errors

  • LuaError libsodium init -- libsodium initialization failed.
  • LuaError invalid key size -- key must be 32 bytes.
  • LuaError invalid nonce size -- nonce must be 12 bytes.
  • LuaError short ciphertext -- ciphertext is shorter than the 16-byte tag.
  • LuaError auth failed -- Poly1305 authentication tag did not verify.

#crypt.ed25519_keypair() → buffer, buffer public_key (32 bytes), secret_key (64 bytes).

since 1.8.3-free

Generates an Ed25519 keypair via libsodium's RNG.

Errors

  • LuaError libsodium init -- libsodium initialization failed.

#crypt.ed25519_sign(message: string | buffer, secret_key: string | buffer 64-byte Ed25519 secret key.) → buffer

since 1.8.3-free

Ed25519 detached sign. Returns the 64-byte signature.

Parameters

messagestring | buffer
secret_keystring | buffer 64-byte Ed25519 secret key.

Returns

buffer

signature.

Errors

  • LuaError libsodium init -- libsodium initialization failed.
  • LuaError invalid secret key -- secret_key must be 64 bytes.

#crypt.ed25519_verify(message: string | buffer, signature: string | buffer 64-byte signature., public_key: string | buffer 32-byte Ed25519 public key.) → boolean

since 1.8.3-free

Ed25519 detached verify. Returns true on valid signature.

Parameters

messagestring | buffer
signaturestring | buffer 64-byte signature.
public_keystring | buffer 32-byte Ed25519 public key.

Errors

  • LuaError libsodium init -- libsodium initialization failed.
  • LuaError invalid signature -- signature must be 64 bytes.
  • LuaError invalid public key -- public_key must be 32 bytes.

#crypt.x25519_keypair() → buffer, buffer public_key (32 bytes), secret_key (32 bytes).

since 1.8.3-free

Generates an X25519 keypair via libsodium's RNG.

Errors

  • LuaError libsodium init -- libsodium initialization failed.

#crypt.x25519_shared_secret(secret_key: string | buffer 32-byte own private scalar., peer_public: string | buffer 32-byte peer's public key.) → buffer 32-byte

since 1.8.3-free

X25519 shared secret via scalar multiplication. The output should be passed through a KDF (BLAKE2b / BLAKE3 / HKDF) before use as a symmetric key.

Parameters

secret_keystring | buffer 32-byte own private scalar.
peer_publicstring | buffer 32-byte peer's public key.

Returns

buffer 32-byte

shared secret.

Errors

  • LuaError libsodium init -- libsodium initialization failed.
  • LuaError invalid secret key -- secret_key must be 32 bytes.
  • LuaError invalid peer public -- peer_public must be 32 bytes.
  • LuaError scalarmult failed -- scalar multiplication failed (peer_public is the all-zero point?).