@eryx/crypto/chacha20 Module

JSON

ChaCha20 stream cipher and ChaCha20-Poly1305 AEAD.

ChaCha20 is a fast, secure stream cipher designed by Daniel J. Bernstein. It is widely used in TLS 1.3 and WireGuard as an alternative to AES when hardware AES acceleration is unavailable.

Key: 32 bytes. Nonce: 12 bytes. Counter starts at 0.

local chacha20 = require("@eryx/crypto/chacha20")

local key   = buffer.create(32)  -- 32 zero bytes (use a real key!)
local nonce = buffer.create(12)  -- 12 zero bytes

-- Authenticated encryption
local ct, tag = chacha20.poly1305_encrypt(key, nonce, buffer.fromstring("secret"))
local pt = chacha20.poly1305_decrypt(key, nonce, ct, tag)

Summary

Functions

chacha20.encrypt(key: buffer, nonce: buffer, data: buffer) → buffer
chacha20.decrypt(key: buffer, nonce: buffer, data: buffer) → buffer
chacha20.encryptPoly1305(key: buffer, nonce: buffer, data: buffer, aad: buffer?) → (buffer, buffer)
chacha20.decryptPoly1305(key: buffer, nonce: buffer, ct: buffer, tag: buffer, aad: buffer?) → buffer

API Reference

Functions

chacha20.encrypt

Encrypts data with ChaCha20 (unauthenticated stream cipher).

The output is the same length as the input. A given (key, nonce) pair must never be reused; generate a fresh random nonce per message.

For authenticated encryption, use poly1305_encrypt instead.

chacha20.encrypt(key: buffer, nonce: buffer, data: buffer) → buffer

Parameters

key: buffer

32-byte ChaCha20 key.

nonce: buffer

12-byte nonce.

data: buffer

Plaintext to encrypt.

Returns

buffer

Ciphertext (same length as input).

chacha20.decrypt

Decrypts ChaCha20 ciphertext (unauthenticated).

ChaCha20 decryption is identical to encryption; this function is provided for API symmetry.

chacha20.decrypt(key: buffer, nonce: buffer, data: buffer) → buffer

Parameters

key: buffer

32-byte ChaCha20 key.

nonce: buffer

12-byte nonce.

data: buffer

Ciphertext to decrypt.

Returns

buffer

Plaintext (same length as input).

chacha20.encryptPoly1305

Encrypts data with ChaCha20-Poly1305 (authenticated encryption).

Returns the ciphertext and a 16-byte Poly1305 authentication tag separately. The tag covers the ciphertext and any additional authenticated data (aad).

This is the recommended variant when you need both confidentiality and integrity.

local ct, tag = chacha20.poly1305_encrypt(key, nonce, plain, aad)
local pt = chacha20.poly1305_decrypt(key, nonce, ct, tag, aad)
chacha20.encryptPoly1305(key: buffer, nonce: buffer, data: buffer, aad: buffer?) → (buffer, buffer)

Parameters

key: buffer

32-byte ChaCha20 key.

nonce: buffer

12-byte nonce.

data: buffer

Plaintext to encrypt.

aad: buffer?

Additional authenticated data (not encrypted).

Returns

buffer

Ciphertext.

buffer

16-byte Poly1305 authentication tag.

chacha20.decryptPoly1305

Decrypts ChaCha20-Poly1305 ciphertext and verifies the tag.

Raises an error if the authentication tag does not match (data has been tampered with, or wrong key/nonce/aad was used).

chacha20.decryptPoly1305(key: buffer, nonce: buffer, ct: buffer, tag: buffer, aad: buffer?) → buffer

Parameters

key: buffer

32-byte ChaCha20 key.

nonce: buffer

12-byte nonce - must match the value used during encryption.

ct: buffer

Ciphertext.

tag: buffer

16-byte Poly1305 authentication tag.

aad: buffer?

Additional authenticated data (must match encryption).

Returns

buffer

Plaintext.