Cryptography

Encode, encrypt, hash and generate random data with the crypt library.

13 functionssUNC 100%Lynx 0.747

Every byte-data parameter in this library accepts a binary string or a Luau buffer, including base64 input, encryption data/key/IV and HMAC key/data. Results are strings, not buffers. Algorithm/mode selectors remain strings; lengths and compression levels remain numbers. All calls are synchronous.

Encoding and compression

base64encode

base64encode(data: string | buffer): string

base64encode converts binary data into a Base64 string.

Also available as base64_encode, base64.encode, crypt.base64encode, crypt.base64_encode and crypt.base64.encode.

Parameters

datastring | buffer
The binary data to process.

Returns

string

The Base64-encoded data.

base64decode

base64decode(data: string | buffer): string

base64decode converts a Base64 string into its original binary data.

Also available as base64_decode, base64.decode, crypt.base64decode, crypt.base64_decode and crypt.base64.decode.

Parameters

datastring | buffer
The Base64 text to decode, supplied as a string or buffer.

Returns

string

The decoded binary bytes.

lz4compress

lz4compress(data: string | buffer): string?

lz4compress compresses binary data into a raw LZ4 block.

Also available as lz4.compress, crypt.lz4.compress and crypt.lz4compress.

Parameters

datastring | buffer
The binary data to process.

Returns

string?

A raw LZ4 block, or nil if compression fails.

lz4decompress

lz4decompress(data: string | buffer, uncompressedSize: number): string?

lz4decompress restores the binary data stored in a raw LZ4 block.

Also available as lz4.decompress, crypt.lz4.decompress and crypt.lz4decompress.

Parameters

datastring | buffer
The raw LZ4 block to decompress.
uncompressedSizenumber
The maximum number of decompressed bytes to allocate.

Returns

string?

The decompressed bytes, or nil if the block cannot fit or decode.

zstdcompress

zstdcompress(data: string | buffer, compressionLevel: number?): string

zstdcompress compresses binary data into a Zstandard frame.

Also available as crypt.zstdcompress and crypt.zstd.compress.

Parameters

datastring | buffer
The binary data to process.
compressionLevelnumber??
Optional.The Zstandard compression level. Default 1.

Returns

string

A compressed Zstandard frame.

zstddecompress

zstddecompress(data: string | buffer): string

zstddecompress restores the binary data stored in Zstandard frames.

Also available as crypt.zstddecompress and crypt.zstd.decompress.

Parameters

datastring | buffer
The Zstandard frame or concatenated frames to decompress.

Returns

string

The combined decompressed frame contents.

Example

local original = buffer.fromstring("binary data\0with NUL")
local compressed = zstdcompress(original, 1)
assert(zstddecompress(compressed) == buffer.tostring(original))
local lz4 = assert(lz4compress(original))
assert(lz4decompress(lz4, buffer.len(original)) == buffer.tostring(original))

Encryption, hashing and random bytes

crypt.encrypt

crypt.encrypt(data: string | buffer, key: string | buffer, iv: (string | buffer)?, mode: string?): (string?, string?)

crypt.encrypt encrypts data with AES and returns the ciphertext and initialization vector as Base64 strings.

Also available as crypt.custom.encrypt.

Parameters

datastring | buffer
The raw bytes to encrypt.
keystring | buffer
The Base64-encoded AES key.
iv(string | buffer)??
Optional.A Base64 IV, or nil to generate 16 random IV bytes. Default nil.
modestring??
Optional.The AES mode name. Default "CBC".

Returns

(string?, string?)

Base64 ciphertext and Base64 IV, or nil, nil on encryption failure.

Example

local key = assert(crypt.generatekey())
local encrypted, iv = crypt.encrypt("hello", key, nil, "CBC")
assert(encrypted and iv)
assert(crypt.decrypt(encrypted, key, iv, "CBC") == "hello")

crypt.decrypt

crypt.decrypt(data: string | buffer, key: string | buffer, iv: string | buffer, mode: string): string?

crypt.decrypt decrypts Base64-encoded AES ciphertext and returns the original binary data.

Also available as crypt.custom.decrypt.

Parameters

datastring | buffer
The Base64-encoded ciphertext.
keystring | buffer
The Base64-encoded AES key used for encryption.
ivstring | buffer
The Base64-encoded initialization vector.
modestring
The AES mode name.

Returns

string?

The binary plaintext, or nil on decryption failure.

crypt.generatebytes

crypt.generatebytes(length: number?): string?

crypt.generatebytes produces random bytes and returns them as a Base64 string.

Parameters

lengthnumber??
Optional.The number of random bytes to generate. Default 16.

Returns

string?

Base64-encoded random bytes, or nil.

crypt.generatekey

crypt.generatekey(): string?

crypt.generatekey generates a random 32-byte AES key encoded as Base64.

Returns

string?

The Base64-encoded 32-byte key, or nil.

crypt.random

crypt.random(length: number): string?

crypt.random returns a string containing the requested number of random bytes.

Parameters

lengthnumber
The number of random bytes to generate.

Returns

string?

Raw random bytes, or nil for zero length. A random-provider failure raises an error.

crypt.hash

crypt.hash(data: string | buffer, algorithm: string?): string?

crypt.hash calculates a digest of the supplied data and returns it as lowercase hexadecimal.

Parameters

datastring | buffer
The binary data to process.
algorithmstring??
Optional.The digest algorithm name. Default "sha256".

Returns

string?

The lowercase hexadecimal digest, or nil if the selected digest is unavailable. Provider or allocation failures raise an error.

crypt.hmac

crypt.hmac(key: string | buffer, data: string | buffer, algorithm: string?): string?

crypt.hmac calculates a keyed message authentication code and returns it as Base64.

Parameters

keystring | buffer
The raw authentication key, not a Base64-encoded key.
datastring | buffer
The message bytes to authenticate.
algorithmstring??
Optional.The digest algorithm name. Default "sha256".

Returns

string?

The Base64-encoded HMAC, or nil for an empty key or an algorithm unavailable to the backend. Provider failures raise an error.