| @@ -0,0 +1,45 @@ |
| 1 | +# ADR 0067: Signature verification in std |
| 2 | + |
| 3 | +**Status:** Proposed (2026-10-28); needs engineering review (#44). Security-sensitive: it puts a signature scheme in the standard library, which [ADR 0050](0050-scram-primitives.md) left to packages. |
| 4 | + |
| 5 | +## Context |
| 6 | + |
| 7 | +ADR 0050 gave `std/crypto` the hashes SCRAM needs, and stopped there: "a real [cryptography library] (signatures, AEAD) wants a reviewed binding, the way `argon2` is a package over a native dependency." |
| 8 | + |
| 9 | +toki2 now needs one signature scheme. Its sessions become short (minutes) and are renewed by a device key: the browser holds an Ed25519 key pair, non-extractable, in IndexedDB, and proves it holds it by signing a timestamp (`POST /refresh`). The server must verify an Ed25519 signature. Its tests must also make one, to play the browser. |
| 10 | + |
| 11 | +The package route is blocked today: |
| 12 | +- **No `Bytes` in C bindings.** A binding can take a `String`, not `Bytes` (`docs/runtime-abi.md`, "Known limitations": `tl_bytes_ptr`, `tl_bytes_len` and `tl_bytes_from` are planned). A public key, a signature and a binary message are bytes. |
| 13 | +- **No source to vendor.** `argon2` vendors the reference C implementation of its RFC. No Ed25519 source is at hand to vendor the same way, and whatever was vendored (libsodium, or ref10 from SUPERCOP) would be a second Ed25519 next to the one the runtime already links. |
| 14 | + |
| 15 | +The runtime already links one: `ring` 0.17, rustls's provider ([ADR 0038](0038-tls-client.md)), which `std/crypto` already uses for its hashes. `ring::signature` has Ed25519, verification and signing. |
| 16 | + |
| 17 | +## Decision |
| 18 | + |
| 19 | +`std/crypto` gets Ed25519 (RFC 8032), over `ring`, through the same runtime path as the hashes: |
| 20 | + |
| 21 | +```louise |
| 22 | +pub fn ed25519_verify :: public_key: Bytes message: Bytes signature: Bytes -> Bool |
| 23 | +pub fn ed25519_public_key :: seed: Bytes -> Bytes |
| 24 | +pub fn ed25519_sign :: seed: Bytes message: Bytes -> Bytes |
| 25 | +``` |
| 26 | + |
| 27 | +- **Verification is the point.** `ed25519_verify` is `UnparsedPublicKey::new(&ED25519, public_key).verify(message, signature)`. A key that is not 32 bytes or a signature that is not 64 is no signature, so the answer is `False`, not a panic: they come from the network. `ring` also refuses a non-canonical `S` (at least the group order), so a valid signature can't be altered into a second one. |
| 28 | +- **Signing is for tests and tools.** `ed25519_public_key` and `ed25519_sign` take RFC 8032's 32-byte private key, the seed (`Ed25519KeyPair::from_seed_unchecked`). A server verifies; its clients keep their seeds. The docs say so. A seed of another length is a programming error, so it panics, with the same message on both back ends. |
| 29 | +- **This amends ADR 0050** for Ed25519 only. Other signature schemes, AEAD and key exchange still belong in a package, once bindings take `Bytes`. |
| 30 | +- **The five places.** The kernels are in `runtime/louise_rt_prims` (`crypto.rs`), which both back ends call, so the interpreter and native code can't disagree. Then the externs in `louise_rt/src/crypto.rs`, with the `not_built!` fallback for a runtime built without the `crypto` feature, the prototypes in `louise_rt.h`, the interpreter's `externs.rs`, and the table in `louise_core/src/externs.rs`. All three are `pure().unwinds()`: they compute only, and they may panic (the seed, or a runtime without `crypto`). |
| 31 | +- **Not `blocking`.** A verification takes tens of microseconds, a signature less, and the cost doesn't depend on the caller. `sha256` and `hmac_sha256` are not `blocking` either; `pbkdf2_hmac_sha256` is, because its iteration count is the caller's. |
| 32 | + |
| 33 | +## Consequences |
| 34 | + |
| 35 | +- No new dependency: `ring` is already linked, and `--gc-sections` keeps Ed25519 out of programs that don't use it ([ADR 0042](0042-smaller-release-binaries.md)). |
| 36 | +- It works in the interpreter, so `louise test` covers code that verifies signatures, without the native backend. |
| 37 | +- `tests/run/crypto.lse` checks RFC 8032 §7.1's tests 1 to 3 on both back ends: the public key derived, the signature reproduced, verification, a flipped bit in the signature, key or message, and wrong lengths. `tests/run/crypto_seed_panic.lse` checks the seed's panic. |
| 38 | +- `std/crypto` stays a set of primitives, not a library: no key types, no encodings. Callers handle raw bytes. |
| 39 | +- If a C package later offers Ed25519 over `Bytes`, std keeps this one: it is small, and the interpreter can't run C. |
| 40 | + |
| 41 | +## Alternatives considered |
| 42 | + |
| 43 | +- **A C package** (libsodium, or ref10): blocked, as above, and a second implementation next to `ring`'s. |
| 44 | +- **Ed25519 in pure Louise:** field arithmetic over big integers would be slow and not constant-time. It would be a new, unreviewed implementation of a signature scheme, the thing ADR 0050 meant to avoid. |
| 45 | +- **Verification only, signing in the tests' own code:** the tests need valid signatures. Hard-coded ones would tie every test to fixed timestamps, so signing is offered, documented as for tests and tools. |