age

Generates a fresh X25519 key pair and returns a table with private_hex and public_hex fields. Both keys are hex-encoded 32-byte values.

use plugin age::{generate_key}

let keypair = generate_key()
print("private: {keypair["private_hex"]}")
print("public:  {keypair["public_hex"]}")

Encrypts plaintext using AES-256-GCM with a key derived from passphrase via PBKDF2 (100,000 iterations). Returns a base64-encoded blob containing the random salt, nonce, ciphertext, and authentication tag. A fresh salt and nonce are generated on every call, so encrypting the same text twice yields different blobs.

use plugin age::{encrypt_symmetric, decrypt_symmetric}

let secret = "api-key: abc123"
let blob = encrypt_symmetric(secret, "my-strong-passphrase")
print(blob)

let recovered = decrypt_symmetric(blob, "my-strong-passphrase")
print(recovered)

Because each call randomizes the salt, two encryptions of the same plaintext differ:

use plugin age::{encrypt_symmetric}

let a = encrypt_symmetric("same text", "pass")
let b = encrypt_symmetric("same text", "pass")
print("blobs differ: {a != b}")

Decrypts a base64 blob produced by encrypt_symmetric. The passphrase must match exactly; a wrong passphrase fails the GCM authentication check and raises an error rather than returning garbage.

use plugin age::{decrypt_symmetric}

let plaintext = decrypt_symmetric(stored_blob, "my-strong-passphrase")
print(plaintext)

Derives a 32-byte key from passphrase and the hex-encoded salt_hex using PBKDF2-HMAC-SHA256 with 100,000 iterations. Pair it with generate_salt to produce the salt, and store the salt alongside the ciphertext so you can re-derive the same key later.

use plugin age::{generate_salt, derive_key}

let salt = generate_salt(16)
let key = derive_key("my-passphrase", salt)
print("derived key from salt {salt}")

The same passphrase and salt always produce the same key — that determinism is what lets you reconstruct the key on the next run:

use plugin age::{derive_key}

let salt = "0102030405060708090a0b0c0d0e0f10"
let k1 = derive_key("pass", salt)
let k2 = derive_key("pass", salt)
print("stable derivation: {k1 == k2}")

Generates len cryptographically random bytes (default 16) and returns them hex-encoded. Use this salt when calling derive_key or for your own key derivation.

use plugin age::{generate_salt}

let salt16 = generate_salt()
let salt32 = generate_salt(32)
print(salt16)

Encrypts plaintext with AES-256-GCM using a raw 32-byte key supplied as exactly 64 hex characters. Returns a base64-encoded blob of nonce + ciphertext + tag. Use this when you manage keys directly (e.g., a key from random_bytes or one you persist yourself). Supplying a key that is not 32 bytes raises an error.

use plugin age::{random_bytes, encrypt, decrypt}

let key_hex = random_bytes(32)
let blob = encrypt("secret message", key_hex)
let plain = decrypt(blob, key_hex)
print(plain)

The key length is enforced — a short key is rejected before any encryption happens:

use plugin age::{encrypt}

let key64 = "0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20"
let blob = encrypt("payload", key64)
print(blob)

Decrypts a base64 blob produced by encrypt using the same 64-char hex key. Wrong keys fail authentication and raise an error.

use plugin age::{decrypt}

let message = decrypt(ciphertext_blob, key_hex_64_chars)
print(message)

Wraps a base64 string in -----BEGIN AGE ENCRYPTED DATA----- / -----END AGE ENCRYPTED DATA----- PEM-style headers, breaking lines at 76 characters. Useful for embedding ciphertext in text files, emails, or logs.

use plugin age::{encrypt_symmetric, armor, dearmor, decrypt_symmetric}

let blob = encrypt_symmetric("hello", "pass")
let pem = armor(blob)
print(pem)

let raw = dearmor(pem)
let plain = decrypt_symmetric(raw, "pass")
print(plain)

Strips PEM-style headers and whitespace from an armored string, returning the raw base64 payload. It is the exact inverse of armor, so dearmor(armor(x)) returns x.

use plugin age::{armor, dearmor}

let raw = dearmor(armor("dGVzdA=="))
print(raw)

Hashes data using "sha256" (default) or "sha512" and returns the hex-encoded digest. The algorithm name is case-insensitive and accepts both "sha256" and "sha-256" spellings; an unsupported name raises an error.

use plugin age::{hash}

let digest = hash("hello world")
print(digest)

let digest512 = hash("hello world", "sha512")
print(digest512)

Hashing is deterministic, which makes it handy for checksums and integrity checks:

use plugin age::{hash}

let expected = hash("config-v1")
let actual = hash("config-v1")
print("integrity ok: {expected == actual}")

Generates len cryptographically random bytes from the OS RNG and returns them hex-encoded (so the string is len * 2 characters). Useful for nonces, tokens, session IDs, or raw 32-byte keys. Unlike generate_salt, the length argument is required.

use plugin age::{random_bytes}

let token = random_bytes(32)
print(token)

let nonce = random_bytes(12)
print("nonce: {nonce}")