Generates a fresh 32-byte secretbox key.
This key is suitable for use with seal and open. Treat it as a shared secret and store or transmit it securely.
local key = secretbox.keygen()
@eryx/crypto/secretbox Module
JSON
High-level symmetric authenticated encryption.
This module provides a simple "secretbox"-style API built on ChaCha20-Poly1305. It is intended as the user-facing way to encrypt a message with a shared secret key without manually managing nonces or separate authentication tags.
The serialized ciphertext format is:
algorithm || nonce || ciphertext || tag
The current algorithm marker is:
"$c$"for ChaCha20-Poly1305
local secretbox = require("@eryx/crypto/secretbox")
local ciphertext, key = secretbox.seal(buffer.fromstring("hello"))
local opened = secretbox.open(ciphertext, key)
assert(buffer.tostring(opened) == "hello")
Summary
Functions
API Reference
Functions
secretbox.keygen
secretbox.keygen() → buffer
Returns
buffer
32 random bytes.
secretbox.seal
Encrypts and authenticates a message.
If key is omitted, a fresh random key is generated and returned as
the second result. The first result is a self-contained ciphertext
buffer containing the algorithm tag, nonce, ciphertext, and Poly1305
tag.
local ciphertext, key = secretbox.seal(buffer.fromstring("top secret"))
secretbox.seal(message: buffer, key: buffer?) → (buffer, buffer)
Parameters
message: buffer
The plaintext message to encrypt.
key: buffer?
Optional 32-byte symmetric key. If omitted, one is generated.
Returns
buffer
Serialized ciphertext in algorithm || nonce || ciphertext || tag form.
buffer
The key used for encryption.
secretbox.open
Decrypts and verifies a serialized secretbox ciphertext.
Raises an error if the algorithm tag is unsupported, the ciphertext is truncated, or authentication fails.
local message = secretbox.open(ciphertext, key)
secretbox.open(ciphertext: buffer, key: buffer) → buffer
Parameters
ciphertext: buffer
A buffer previously returned by seal.
key: buffer
The 32-byte secret key used to encrypt it.
Returns
buffer
Decrypted plaintext.