Cryptography

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

7 functionssUNC 100%Lynx 0.0.0

The crypt library works on strings, and binary data is fine: Luau strings hold arbitrary bytes. Keys, IVs and ciphertext are base64-encoded, so they're safe to store with writefile or send over HTTP.

Encoding

crypt.base64encode

since 1.0.0
crypt.base64encode(data: string): string

Encodes data as base64.

Also available as base64_encode and crypt.base64.encode.

Parameters

datastring
Any string, including binary data.

Returns

string

The base64 encoding.

Example

local encoded = crypt.base64encode("Lynx")
print(encoded) --> THlueA==
print(crypt.base64decode(encoded)) --> Lynx

crypt.base64decode

since 1.0.0
crypt.base64decode(data: string): string

Decodes a base64 string. Errors on invalid input.

Also available as base64_decode and crypt.base64.decode.

Parameters

datastring
A base64 string.

Returns

string

The decoded bytes.

Example

local bytes = crypt.base64decode("iVBORw0KGgo=")
print(#bytes) --> 8, the PNG file signature

Encryption

crypt.encrypt

since 1.0.0
crypt.encrypt(data: string, key: string, iv: string?, mode: string?): (string, string)

Encrypts data with AES-256. Returns the base64-encoded ciphertext and the IV that was used, which is random unless you pass one.

Parameters

datastring
The plaintext.
keystring
A base64-encoded 32-byte key, such as one from crypt.generatekey().
ivstring?
Optional.A base64-encoded 16-byte IV. Generated for you when omitted.
modestring?
Optional."CBC", "CTR", "CFB", "OFB", "ECB" or "GCM". Default "CBC".

Returns

(string, string)

The ciphertext and the IV, both base64.

Example

local key = crypt.generatekey()
local ciphertext, iv = crypt.encrypt("meet at the fountain", key)
print(crypt.decrypt(ciphertext, key, iv, "CBC")) --> meet at the fountain

crypt.decrypt

since 1.0.0
crypt.decrypt(data: string, key: string, iv: string, mode: string): string

Decrypts base64 ciphertext produced by crypt.encrypt. The key, IV and mode must match the ones used to encrypt. Unlike crypt.encrypt, the mode has no default here.

Parameters

datastring
The base64 ciphertext.
keystring
The base64 key used to encrypt.
ivstring
The base64 IV returned by crypt.encrypt.
modestring
The mode used to encrypt, such as "CBC".

Returns

string

The plaintext.

Example

local HttpService = game:GetService("HttpService")
local key = readfile("my-tool/key.txt")
local saved = HttpService:JSONDecode(readfile("my-tool/secret.json"))
local secret = crypt.decrypt(saved.data, key, saved.iv, "CBC")

Hashing

crypt.hash

since 1.0.0
crypt.hash(data: string, algorithm: string?): string

Returns the hash of data as a lowercase hex string.

Parameters

datastring
The data to hash.
algorithmstring?
Optional."md5", "sha1", "sha224", "sha256", "sha384", "sha512", "sha3-224", "sha3-256", "sha3-384" or "sha3-512". Default "sha256".

Returns

string

The hex digest.

Example

print(crypt.hash("", "sha256"))
--> e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Random data

crypt.generatekey

since 1.0.0
crypt.generatekey(): string

Returns a random 256-bit key, base64-encoded, from a cryptographically secure source.

Returns

string

A base64 key for crypt.encrypt.

Example

local key = crypt.generatekey()
print(#crypt.base64decode(key)) --> 32

crypt.generatebytes

since 1.0.0
crypt.generatebytes(size: number?): string

Returns size cryptographically secure random bytes, base64-encoded.

Parameters

sizenumber?
Optional.How many bytes to generate, up to 1024. Default 16.

Returns

string

The bytes, base64-encoded.

Example

local nonce = crypt.generatebytes(12)
print(#crypt.base64decode(nonce)) --> 12

Written for Lynx 0.0.0

Something unclear? Tell us on Discord