Cryptography & Hashing

Built-in cryptographic primitives for encoding, hashing, HMAC authentication, and symmetric AES-256 encryption.

---

Base64

local encoded = base64.encode(data: string, url_safe?: boolean) --> string
local decoded = base64.decode(data: string)                     --> string

• url_safe: Replaces standard +/ characters with URL-safe -_.
• base64.decode automatically ignores whitespace and newlines.

---

MD5 Hashing

md5.sum(data)      --> raw 16 bytes string
md5.sumhexa(data)  --> 32-character lowercase hex string
md5.binary(data)   --> alias of sum
md5.hex(data)      --> alias of sumhexa
md5.tohex(bytes)   --> converts raw bytes string to hex string

---

SHA-1

sha1(data)                   --> 40-character hex string (callable table)
sha1.hex(data)               --> 40-character hex string
sha1.binary(data)            --> raw 20 bytes string
sha1.hmac(key, message)      --> hex string
sha1.hmac_binary(key, msg)   --> raw 20 bytes HMAC digest

---

SHA-256

sha256.hex(data)             --> 64-character hex string
sha256.binary(data)          --> raw 32 bytes string
sha256.hmac(key, message)    --> hex string
sha256.hmac_binary(key, msg) --> raw 32 bytes HMAC digest

---

AES-256 Encryption (aes)

Native AES-256 encryption with PKCS#7 padding.

-- Electronic Codebook (ECB) Mode (Requires 32-byte key)
local cipher = aes.encrypt(key: string, plaintext: string) --> string | nil
local plain  = aes.decrypt(key: string, ciphertext: string) --> string | nil

-- Cipher Block Chaining (CBC) Mode (Requires 32-byte key & 16-byte IV)
local cipher = aes.encrypt(key: string, plaintext: string, iv: string) --> string | nil
local plain  = aes.decrypt(key: string, ciphertext: string, iv: string) --> string | nil

Key & IV Requirements

• The key must be exactly 32 raw bytes (e.g. generated via sha256.binary(passphrase)).
• The IV for CBC mode must be exactly 16 raw bytes.
• Any mismatch or corrupt padding returns nil rather than returning corrupt data.

Encrypting & Decrypting Data

local secret_key = sha256.binary("my_secure_script_password")
local config_data = json.stringify({ user = "alice", premium = true })

-- Encrypt
local encrypted_blob = aes.encrypt(secret_key, config_data)

-- Decrypt
local decrypted_json = aes.decrypt(secret_key, encrypted_blob)
if decrypted_json then
    local restored_data = json.parse(decrypted_json)
    print("Decrypted User: " .. restored_data.user)
end