# Crypto `crypto/` collects hashing, keyed HMAC, secure randomness, hex and base64 encoding, and ChaCha20-Poly1305 authenticated encryption. It is a namespaced stdlib family, compiled into every runtime and called with prefix syntax (`[crypto/sha256 $data]`). Strings double as byte containers here: hash and encode functions consume the string's bytes, and decoders return raw bytes turned back into a string — use the `bytes/*` verbs from Strings for binary lengths and slices. ## Functions ### Hashing | Function | Purpose | |---|---| | `crypto/sha256 $data` | SHA-256 digest as a 64-character lowercase hex string | | `crypto/sha512 $data` | SHA-512 digest as a 128-character lowercase hex string | | `crypto/blake3 $data` | BLAKE3 digest as a 64-character lowercase hex string | | `crypto/md5 $data` | MD5 digest as a 32-character lowercase hex string; cryptographically broken, use only for non-security checksums | | `crypto/hash $data :algo` | Dispatch by algorithm: `:sha256`, `:sha512`, `:blake3`, or `:md5`; `%Err` on an unknown name | | `crypto/hmac :algo $key $data` | Keyed HMAC (`:sha256` or `:sha512`) as a lowercase hex string | ### Random | Function | Purpose | |---|---| | `crypto/rand $n` | `$n` (1–4096) bytes from the OS CSPRNG, as a vector of numbers | | `crypto/rand-hex $n` | The same random bytes as a lowercase hex string of `2 * n` characters | ### Encoding | Function | Purpose | |---|---| | `crypto/b64-encode $data` | Encode a string to standard base64 (with padding) | | `crypto/b64-decode $s` | Decode base64 to raw bytes (as a string); `%Err` on invalid input | | `crypto/hex-encode $data` | Encode bytes to lowercase hex (`2 * len` characters) | | `crypto/hex-decode $hex` | Decode hex to raw bytes (as a string); must be even length, at most 8192 characters | ### Authenticated encryption | Function | Purpose | |---|---| | `crypto/encrypt :chacha20-poly1305 $key-hex $nonce-hex $plaintext ?$aad` | AEAD encrypt; returns `%Encrypted{ :ciphertext hex :tag hex }` | | `crypto/decrypt :chacha20-poly1305 $key-hex $nonce-hex $ciphertext-hex $tag-hex ?$aad` | AEAD decrypt; returns the plaintext string, or `%Err` when authentication fails | Notes: - All digests and encoded values are lowercase hex or standard padded base64; decoders accept those forms and return raw byte strings, so a decoded blob can be passed straight back to `crypto/encrypt` or written with `fs/write`. - `crypto/hmac` takes the algorithm first: `[crypto/hmac :sha256 $key $data]`. - For the AEAD calls the key is a 32-byte key expressed as 64 hex characters (generate with `[crypto/rand-hex 32]`), the nonce is 12 bytes as 24 hex characters, and the tag is 16 bytes as 32 hex characters. The optional AAD is covered by the tag but not encrypted and must match at decrypt time. - MD5 is retained for compatibility and checksums only — do not use it for signatures, integrity, or password storage. ## Examples ### Hashes and HMAC

set payload "hello"
echo [crypto/sha256 $payload]
echo [crypto/sha512 $payload]
echo [crypto/blake3 $payload]
echo [crypto/md5 $payload]

echo [crypto/hash $payload :sha256]      # same as crypto/sha256
echo [crypto/hmac :sha256 "secret-key" $payload]

### Hex and base64 encoding

set b64 [crypto/b64-encode "hello"]      # aGVsbG8=
echo [crypto/b64-decode $b64]            # hello

echo [crypto/hex-encode "hello"]         # 68656c6c6f
echo [crypto/hex-decode "68656c6c6f"]    # hello

### Random tokens

def session [crypto/rand-hex 32]         # 64-character hex session id
def noise   [crypto/rand 16]             # @{ 0-255 ... } byte vector
echo $session(len) $noise(len)

### Authenticated encryption

def key   [crypto/rand-hex 32]           # 32-byte key as 64 hex chars
def nonce [crypto/rand-hex 12]           # 12-byte nonce as 24 hex chars

def sealed [crypto/encrypt :chacha20-poly1305 $key $nonce "secret message"]
set plain [crypto/decrypt :chacha20-poly1305 $key $nonce
           $sealed~ciphertext $sealed~tag]
echo $plain                              # secret message

## See Also - Strings — `bytes/*` verbs for binary-safe lengths and slices - Compress — gzip, tar, and tarball helpers for encoded blobs - Filesystem — reading and writing binary files to hash or seal - Data Formats — serialising values that are then signed or hashed