--- track: runtime-v2 iteration: "8" status: in-progress readiness: ready --- # runtime-v2 8 — AEAD ciphers: authenticated encryption for cookies, data at rest, and TLS > Created 2026-09-06 from the porch-vs-fiber scope-gap analysis > ([exploration](../../plan/exploration/fiber/01-porch-vs-fiber-scope-gap.md)) as > a runtime-v2 iteration — a hand-rolled cipher builtin with a `types.ml` row is > exactly the track's builtin-sized-seam shape (the iteration 42 precedent). (It > is not a language-track iteration; the language number 43 was already spent on > the wmux foundation.) > > **Brainstormed to `ready` 2026-09-08.** A second consumer appeared after the > first draft — runtime-v2 [9](09-in-process-tls.md)'s TLS phase A — and it > reshaped the forks: TLS 1.3 **mandates AES-128-GCM** (RFC 8446), so the > original ChaCha-only lean is out, and TLS constructs its own per-record nonce, > so the primitive takes a **caller-supplied** nonce. ## Why this exists The runtime has digests only — SHA-1, SHA-256, HMAC-SHA256, base64 ([iteration 34](../language-runtime-database/34-crypto-builtins.md)) — and, from the porch track, `random_bytes` ([porch 2](../porch/02-randomness-and-cookies.md)). Those let a program *authenticate* and *sign* a value, and *mint* a random one. None of them let it *encrypt* — turn a plaintext into a ciphertext only the key-holder can read. That absence is a named porch limit: [porch 2](../porch/02-randomness-and-cookies.md) scopes out **encrypted cookies** explicitly — "Fiber's `encryptcookie` needs a symmetric cipher, and the runtime has digests only. Signed-and-readable is honest and sufficient for a session id; encrypting a payload is a separate ask with a separate primitive behind it." This is that separate primitive. Signed-and-readable (what porch has) is correct for a session id — the client may see it, it just may not forge it. Encryption is for the case where the *payload itself* must be hidden from the client: an encrypted cookie carrying app state, or a database field encrypted at rest. ## Decisions locked (brainstorm 2026-09-08) 1. **Two AEAD ciphers: AES-GCM (128 and 256) and ChaCha20-Poly1305.** TLS 1.3 mandates AES-128-GCM, so it is in whatever happens; ChaCha20-Poly1305 (RFC 8439) rides along because it is a valid TLS 1.3 suite, is far easier to get constant-time, is preferred where no AES hardware exists, and is the clean default for cookies and data-at-rest. TLS negotiates whichever the server picks; application code defaults to ChaCha. 2. **AES is made constant-time by hardware, with a software fallback.** AES-NI on x86-64 (``) and the ARMv8 crypto extension give constant-time AES and GHASH (CLMUL/PMULL) with zero external dependency — these are compiler intrinsics, not a library. A bitsliced constant-time software AES + a constant-time GHASH covers CPUs without the extension. ChaCha20-Poly1305 is naturally constant-time in portable C and needs no hardware path. 3. **The primitive takes a caller-supplied nonce.** Shape: `_seal(key, nonce, aad, plaintext) -> Bytes` (ciphertext‖tag) and `_open(key, nonce, aad, ciphertext) -> ?Bytes` (`nil` on any authentication failure). Caller-supplied because TLS builds its own per-record nonce (static IV XOR sequence number); the random-nonce convenience for cookies is a **wrapper** on top (phase D), not the primitive. Named per cipher (matching the existing `sha1`/`sha256`/`hmac_sha256` style), AES variant inferred from key length (16 → AES-128, 32 → AES-256). New builtin ids start at 111 (after `net.connect` = 110); confirm against `wob.h` at implementation. 4. **Raw key with a length check.** A raw key (16 or 32 bytes, from `random_bytes`, carried as base64 in config — the `encryptcookie.GenerateKey` shape), length-validated. A passphrase-plus-KDF is a separate ask. 5. **Hand-rolled, no vendored library** — consistent with rv2 9's decision and the SHA-256 precedent. AEAD, never a bare cipher: unauthenticated encryption is a footgun that will not ship. ## Phases Easy cipher first, so a working AEAD exists before the hard constant-time AES work; TLS's ChaCha suite and the cookie consumer unblock at phase A. | Phase | Delivers | | --- | --- | | A — ChaCha20-Poly1305 | ✅ **LANDED 2026-09-08** — `chacha20poly1305_seal`/`open` (ids 111/112, bare-name crypto family). Hand-rolled ChaCha20 + poly1305-donna-32 + the RFC 8439 §2.8 AEAD, caller-supplied 12-byte nonce, 32-byte key, constant-time tag compare, `open` returns nil on auth failure. Matches the RFC 8439 §2.8.2 vector byte-for-byte; gated in `test/test_crypto.c` (§2.5.2 Poly1305 + §2.8.2 seal/open/tamper), ASan/UBSan clean | | B — AES-GCM via hardware | ✅ **LANDED 2026-09-08** (x86-64) — `aes_gcm_seal`/`open` (ids 113/114), AES-128/256 (by key length) on AES-NI + PCLMULQDQ, constant-time by hardware, CPUID-gated with target-attributed functions so the binary stays portable (no-AES-NI traps until phase C). Matches NIST SP 800-38D cases 4 & 16 byte-for-byte; KAT-gated in `test_crypto.c`, ASan/UBSan clean. **ARMv8 crypto-ext path deferred** (untestable on the x86-64 dev host) — folds into phase C | | C — AES-GCM portability | ✅ **software fallback LANDED 2026-09-08** — portable constant-time AES (S-box via the GF(2⁸)-inverse power ladder, no tables) + bit-by-bit constant-time GHASH; same `aes_gcm_seal`/`open`, dispatched to AES-NI when present else this path. Matches NIST cases 4 & 16 byte-for-byte (test forces the software path via `wo_aes_force_software`), ASan/UBSan clean. AES-GCM is now available on any CPU (the phase-B no-AES-NI trap is retired). **ARMv8 crypto-ext hardware path still deferred** (untestable on the x86-64 dev host) — a follow-up when an ARM host exists | | D — the cookie wrapper | an `encryptcookie`-equivalent on porch [2](../porch/02-randomness-and-cookies.md)'s cookie machinery: random nonce (from `random_bytes`) prepended to the ciphertext, default ChaCha | | E — the gate | RFC 8439 + NIST GCM known-answer vectors, ASan/UBSan on both paths, and a reference cross-check (`openssl enc`/a scripted peer) | ## Consumers - **runtime-v2 [9](09-in-process-tls.md), TLS phase A** — the record-layer AEAD; needs AES-GCM (mandatory) and gets ChaCha too. This is why AES-GCM is in scope. - **porch encrypted cookies** — the original consumer (phase D), the `encryptcookie`-equivalent porch [2](../porch/02-randomness-and-cookies.md) scoped out. - **database field-at-rest** — a plausible third, unbuilt until a workload asks. ## Dependencies - **porch [2](../porch/02-randomness-and-cookies.md)** — `random_bytes`, for the cookie wrapper's random nonce (phase D only). The AEAD primitives themselves are self-contained. - **AES-NI / ARMv8 crypto** — compiler intrinsics, not an external dependency. ## Out of scope - **Asymmetric crypto** (RSA, ECDH, signatures). A different, much larger surface — owned by rv2 [9](09-in-process-tls.md)'s TLS phases C/D, not here. - **Key rotation, a KMS, envelope encryption.** Operational key management is its own story if a consumer appears. - **A passphrase KDF** (fork 4) — raw keys only; a KDF is a separate ask. - **Nonce-misuse-resistant modes** (AES-GCM-SIV). The caller-supplied-nonce contract stands; misuse resistance is a later slice if a consumer needs it. - **Compression before encryption** (the CRIME/BREACH interaction). A caller concern to document, not a primitive. > The earlier draft listed "TLS — proxy-terminated by doctrine" here. That > doctrine was **retired** by rv2 [9](09-in-process-tls.md); TLS is now a > first-class consumer of this cipher, which is what pulled AES-GCM into scope. ## Risk and test strategy Encryption code is get-it-exactly-right code, and the risk is timing side channels and a reused nonce: - **Constant-time is mandatory** for every key/plaintext-dependent operation — hardware AES/GHASH by construction, and the bitsliced fallback and ChaCha/ Poly1305 verified table-free and branch-free. The Poly1305/GHASH tag compare is constant-time (`ct_eq`-style). - **Known-answer vectors gate every cipher**: RFC 8439 for ChaCha20-Poly1305, the NIST GCM test vectors for AES-GCM, on both the hardware and software paths; plus a reference cross-check and an ASan/UBSan leg. - **The reused-nonce hazard is documented loudly.** A key+nonce pair must never repeat; the cookie wrapper (phase D) draws a fresh random nonce per seal, and TLS owns its own per-record nonce discipline — the primitive trusts the caller and says so. ## Info Two named consumers now — TLS (rv2 9 phase A, the reason AES-GCM is in) and porch encrypted cookies — with database-field-at-rest a plausible third. Pure compute, no actors, not exposed to the lang-41 hang. It is the **first rung of the TLS ladder**, so it gates rv2 9: nothing above TLS phase A can be built until this lands. Implementation order is A (ChaCha, unblocks the most for the least risk) → B (hardware AES-GCM) → C (software AES fallback) → D (cookie wrapper) → E (gate).