Encrypts data with AES-CBC (PKCS#7 padding).
The same (key, IV) pair must never be reused. Generate a random IV per message and transmit it alongside the ciphertext.
@eryx/crypto/aes Module
JSON
AES (Advanced Encryption Standard) symmetric encryption.
Supports 128-, 192-, and 256-bit keys (determined by key length). Three operation modes are provided:
- CBC – Cipher Block Chaining with PKCS#7 padding. Requires an IV; do not reuse (key, IV) pairs.
- CTR – Counter mode. Turns AES into a stream cipher; no padding. The IV is the initial counter block (16 bytes).
- GCM – Galois/Counter Mode. Authenticated encryption (AEAD). Returns ciphertext and a 16-byte authentication tag separately.
- CCM – Counter with CBC-MAC. Another AEAD mode; nonce must be 7–13 bytes.
local aes = require("@eryx/crypto/aes")
local key = buffer.fromstring("0123456789abcdef") -- 16-byte AES-128
local iv = buffer.fromstring("0000000000000000")
local plain = buffer.fromstring("Hello, AES!")
local ct = aes.cbc_encrypt(key, iv, plain)
local pt = aes.cbc_decrypt(key, iv, ct)
assert(buffer.tostring(pt) == "Hello, AES!")
Summary
Functions
API Reference
Functions
aes.encryptCBC
aes.encryptCBC(key: buffer, iv: buffer, data: buffer) → buffer
Parameters
key: buffer
AES key - 16, 24, or 32 bytes (128/192/256-bit).
iv: buffer
Initialisation vector - 16 bytes.
data: buffer
Plaintext to encrypt.
Returns
buffer
Ciphertext (length rounded up to a 16-byte block boundary).
aes.decryptCBC
Decrypts AES-CBC ciphertext (strips PKCS#7 padding).
aes.decryptCBC(key: buffer, iv: buffer, data: buffer) → buffer
Parameters
key: buffer
AES key - 16, 24, or 32 bytes.
iv: buffer
Initialisation vector - 16 bytes.
data: buffer
Ciphertext to decrypt.
Returns
buffer
Plaintext.
aes.encryptCTR
Encrypts data with AES-CTR (stream cipher; no padding).
CTR mode is length-preserving. The iv parameter is the 16-byte
counter block (typically a random nonce). A (key, IV) pair must
never be reused.
aes.encryptCTR(key: buffer, iv: buffer, data: buffer) → buffer
Parameters
key: buffer
AES key - 16, 24, or 32 bytes.
iv: buffer
Counter/nonce block - 16 bytes.
data: buffer
Plaintext to encrypt.
Returns
buffer
Ciphertext (same length as input).
aes.decryptCTR
Decrypts AES-CTR ciphertext.
CTR decryption is identical to encryption; this function is provided for API symmetry.
aes.decryptCTR(key: buffer, iv: buffer, data: buffer) → buffer
Parameters
key: buffer
AES key - 16, 24, or 32 bytes.
iv: buffer
Counter/nonce block - 16 bytes.
data: buffer
Ciphertext to decrypt.
Returns
buffer
Plaintext (same length as input).
aes.encryptGCM
Encrypts data with AES-GCM, returning the ciphertext and
authentication tag separately.
GCM provides authenticated encryption: the tag covers both the
ciphertext and any additional authenticated data (aad). A
(key, nonce) pair must never be reused; 12-byte random nonces are
standard.
local ct, tag = aes.gcm_encrypt(key, nonce, plain, aad)
local pt = aes.gcm_decrypt(key, nonce, ct, tag, aad)
aes.encryptGCM(key: buffer, nonce: buffer, data: buffer, aad: buffer?) → (buffer, buffer)
Parameters
key: buffer
AES key - 16, 24, or 32 bytes.
nonce: buffer
Nonce - 12 bytes recommended.
data: buffer
Plaintext to encrypt.
aad: buffer?
Additional authenticated data (not encrypted, but covered by tag).
Returns
buffer
Ciphertext.
buffer
16-byte authentication tag.
aes.decryptGCM
Decrypts AES-GCM ciphertext and verifies the authentication tag.
Raises an error if the tag does not match (i.e. the data has been tampered with or the wrong key/nonce/aad was supplied).
aes.decryptGCM(key: buffer, nonce: buffer, ct: buffer, tag: buffer, aad: buffer?) → buffer
Parameters
key: buffer
AES key - 16, 24, or 32 bytes.
nonce: buffer
Nonce - must match the value used during encryption.
ct: buffer
Ciphertext.
tag: buffer
16-byte authentication tag.
aad: buffer?
Additional authenticated data (must match encryption).
Returns
buffer
Plaintext.
aes.encryptCCM
Encrypts data with AES-CCM, returning the ciphertext and
authentication tag separately.
CCM is an AEAD mode similar to GCM but based on CBC-MAC. The nonce must be 7–13 bytes; shorter nonces allow larger messages.
aes.encryptCCM(key: buffer, nonce: buffer, data: buffer, aad: buffer?) → (buffer, buffer)
Parameters
key: buffer
AES key - 16, 24, or 32 bytes.
nonce: buffer
Nonce - 7 to 13 bytes.
data: buffer
Plaintext to encrypt.
aad: buffer?
Additional authenticated data.
Returns
buffer
Ciphertext.
buffer
Authentication tag.
aes.decryptCCM
Decrypts AES-CCM ciphertext and verifies the authentication tag.
Raises an error if the tag does not match.
aes.decryptCCM(key: buffer, nonce: buffer, ct: buffer, tag: buffer, aad: buffer?) → buffer
Parameters
key: buffer
AES key - 16, 24, or 32 bytes.
nonce: buffer
Nonce - must match the value used during encryption.
ct: buffer
Ciphertext.
tag: buffer
Authentication tag.
aad: buffer?
Additional authenticated data (must match encryption).
Returns
buffer
Plaintext.
aes.encryptECB
Encrypts data with AES-ECB (PKCS#7 padding).
aes.encryptECB(key: buffer, data: buffer) → buffer
Parameters
key: buffer
AES key - 16, 24, or 32 bytes.
data: buffer
Plaintext to encrypt.
Returns
buffer
Ciphertext (length rounded up to a 16-byte block boundary).
aes.decryptECB
Decrypts AES-ECB ciphertext (strips PKCS#7 padding).
aes.decryptECB(key: buffer, data: buffer) → buffer
Parameters
key: buffer
AES key - 16, 24, or 32 bytes.
data: buffer
Ciphertext to decrypt.
Returns
buffer
Plaintext.