CryptographyService

Getting it

local CryptographyService = Engine:GetService("CryptographyService")

Overview

CryptographyService implements modern, well-reviewed algorithms in Luau, on the server only:

• A CSPRNG for unpredictable ids, tokens and keys.
• Hashing: SHA-256/224/384/512, SHA3-224/256/384/512, SHAKE128/256, BLAKE2s/b and SHA-1.
• MACs: HMAC with any of those hashes, and keyed BLAKE2.
• Encryption: XChaCha20-Poly1305 envelopes that carry the key version, so you can rotate keys without breaking old data; plus raw ChaCha20-Poly1305 and ChaCha20.
• Key derivation: HKDF, PBKDF2, scrypt and Argon2 (i, d and id), with async versions that run off the main thread.
• Signed tokens with expiry, and HOTP/TOTP one-time codes compatible with authenticator apps.

Every function accepts strings or buffers. Byte results are buffers; use :Encode() or the Hex/String variants for text.

local Crypto = Engine:GetService("CryptographyService")

-- Encrypt something before storing it
local key = Crypto:CreateKey("Messages", SECRET_FROM_CONFIGURATION)
local stored = Crypto:EncryptString("meet at the north gate", "Messages")
local text, reason = Crypto:DecryptString(stored, "Messages")

-- A signed, expiring invite code
local token = Crypto:CreateToken({ PartyId = partyId }, "Messages", { ExpiresIn = 600 })
local claims, problem = Crypto:VerifyToken(token, "Messages")

For player passwords, use PasswordSystem, which builds on this service.

Random

The shared generator reseeds itself after ReseedAfterBytes bytes or ReseedAfterSeconds seconds. A Generator has Bytes, Fill, Int, Float, Bool, Pick, Shuffle, Hex, Base64, Base64Url and String.

Hashing

Algorithms (CryptographyService.HashAlgorithms): SHA256, SHA224, SHA384, SHA512, SHA3-224, SHA3-256, SHA3-384, SHA3-512, BLAKE2s, BLAKE2b, SHA1.

Message authentication

Algorithms (CryptographyService.MacAlgorithms): HMAC- plus any hash name above, and keyed BLAKE2s / BLAKE2b.

Keys

A Key holds 32 bytes of secret material and can have several versions. Rotating a key adds a new version for new encryptions while old versions keep decrypting older data.

Key material is 32 raw bytes, 64 hex characters, or Base64 of 32 bytes. A passphrase is not a key; derive one.

A Key object has Name, Version, VersionCount, Id, Size, IsDestroyed, :Rotate(material?), :Export(version?), :ExportString(encoding?, version?), :Fingerprint(version?), :HasVersion(version), :Derive(purpose, version?) (a sub-key for one purpose) and :Destroy().

Encryption

Encrypt / Decrypt

CryptographyService:Encrypt(plaintext, key, associatedData?): buffer
CryptographyService:Decrypt(envelope, key, associatedData?): (buffer?, DecryptReason?)

Encrypts with XChaCha20-Poly1305 using the key's current version. The envelope stores the format, the key version, a key fingerprint and a random nonce, so decryption picks the right key version automatically. associatedData is authenticated but not encrypted: decryption fails unless the same value is given, which binds ciphertext to its context (for example the player's UserId).

Decryption returns nil plus a reason instead of raising: "NotAnEnvelope", "UnknownFormat", "UnknownKeyVersion", "WrongKey" or "Tampered".

EncryptString / DecryptString

CryptographyService:EncryptString(text, key, associatedData?, encoding?): string
CryptographyService:DecryptString(encoded, key, associatedData?, encoding?): (string?, DecryptReason?)

The same, producing text (Base64 by default) that fits in a DataStore or attribute.

InspectEnvelope

CryptographyService:InspectEnvelope(envelope, encoding?): { Format, KeyVersion, KeyFingerprint, PlaintextSize }?

Reads an envelope's header without decrypting. Useful to find data that still uses an old key version.

CryptographyService.EnvelopeOverhead is the number of bytes an envelope adds to the plaintext.

Low-level

Key derivation

Passwords longer than MaxKdfInputLength and parameters needing more than MaxKdfMemoryMb are rejected.

Tokens

CreateToken / VerifyToken

CryptographyService:CreateToken(data, key, { ExpiresIn?, NotBefore?, Subject?, Id?, Now? }?): string
CryptographyService:VerifyToken(token, key): (Claims?, Reason?)

A compact, signed string carrying data (any storable value). It is signed, not encrypted: anyone can read the data, but nobody without the key can change it. Use it for invite codes, signed links between places, or anything that must prove it came from your server.

Claims: { Data, IssuedAt, ExpiresAt?, NotBefore?, Subject?, Id?, KeyVersion }. Failure reasons: "Malformed", "UnknownVersion", "UnknownKeyVersion", "BadSignature", "Expired", "NotYetValid", "BadPayload". Expiry checks allow TokenLeewaySeconds of clock skew.

One-time codes

Codes compatible with Google Authenticator, Authy and similar apps.

Options: { Digits?, Step?, Algorithm?, Window?, Time?, Issuer? }.

Utilities

Configuration

Types

export type Bytes = buffer | string
export type Key
export type KeyRef = Key | string
export type Generator
export type Hasher
export type HashAlgorithm
export type MacAlgorithm
export type Encoding = "Hex" | "Base64" | "Base64Url" | "Base32" | "Binary"
export type KeyDerivation = "Argon2id" | "Argon2i" | "Argon2d" | "Scrypt" | "PBKDF2"
export type DecryptReason
export type TokenClaims
export type TokenOptions
export type TokenReason
export type OtpOptions
export type EnvelopeInfo