Cryptography
Encode, encrypt, hash and generate random data with the crypt library.
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): stringbase64encode 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
stringThe Base64-encoded data.
base64decode
base64decode(data: string | buffer): stringbase64decode 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
stringThe 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?): stringzstdcompress 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
stringA compressed Zstandard frame.
zstddecompress
zstddecompress(data: string | buffer): stringzstddecompress 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
stringThe combined decompressed frame contents.
Example
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
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.
Written for Lynx 0.747
Something unclear? Tell us on Discord