fips205-slhdsa-verified/README.md

fips205-slhdsa-verified

Machine-checked verification campaign for the SLH-DSA (FIPS 205) verify path, extracted from a pure-Rust implementation into Lean 4 via Charon/Aeneas — the same pipeline, discipline, and honesty rules as the four ed25519 campaigns (dalek/anza/risc0/betrusted-ed25519-verified).

STATUS: eleven certificates over the extracted verify model (external review rounds 1–5 applied)

verification/check.sh is green (exit 0): the model compiles, the proofs compile, and the audit passes. The audit runs inside Lean (verification/Proofs/Audit.lean) and binds four things, each added because an external reviewer demonstrated the button going green without it:

• axiom cones — each certificate's cone is read from the kernel via collectAxioms and must equal its expected set EXACTLY, so an added axiom and a silently dropped oracle both fail (round 2 retired a text parser that could fail open on an empty or truncated report);
• coverage — EVERY declaration in the eight certificate modules, of every kind, and in Audit.lean itself, must stay inside the axiom boundary (rounds 4–5: an un-manifested theorem : False, then a def : False, then one inside the auditor, each passed a gate that checked only the listed certificates);
• statements and specifications — check.sh binds to the SHA-256 of a canonical block containing the policy constants, every certificate's fully-elaborated statement, and every reference fold's fully-elaborated body. Round 5 showed why the last part is essential: redefining a fold to be the extracted loop left every earlier fingerprint bit-identical while the certificate degenerated to "the loop equals the loop";
• bytes — Phase 0 sha256-pins the four model files and the compiler harness lean-guard, purges stale .oleans, and forbids stray .lean files, so the verdict depends on committed bytes rather than build-directory state.

What the button still does not bind is stated plainly in TRUSTED-BASE.md item 11 — check.sh itself, the toolchain env, and $AENEAS_HOME. verification/check-selftest.sh runs the reviewers' own exploits back against the gate; all are rejected.

What is actually established — eleven Lean theorems about the Aeneas-generated model of the monomorphic verify_mono compatibility verify path (an additive, #![allow(dead_code)] re-expression of the deployed generic verifier, using named hash oracles because Charon/Aeneas cannot translate the deployed Hashers function-pointer struct):

• Ten loop-fidelity theorems (chain 5, WOTS+ 8, XMSS 10, hypertree 12, FORS-inner/outer 17, and the input-prep helpers to_int/to_byte/checksum/ base_2b-outer, Alg 2/3/4). Each equates one generated Aeneas loop with an explicit hand-written recursive fold — a local control-flow correspondence, not an Algorithm-level mathematical specification.
• The apex, fips205.slh_verify_128s_accepts_iff — the extracted verify_mono::slh_verify_128s returns ok true iff the recomputed hypertree root byte-equals pk.pk_root. This is an acceptance characterization: there is no acceptance path other than root equality over the extracted recomputation. Its #print axioms cone is exactly [propext, Classical.choice, Quot.sound] + the five SHA-2 oracles.

What is NOT (yet) established — do not overclaim:

• The apex proof does not compose the ten loop theorems. It is a structural factorization of the extracted verifier around its final equality check; it references none of the ten (it would remain provable if one were deleted). The ten are independent local-fidelity lemmas, not links in the apex's proof chain.
• Not "every loop": base_2b's inner accumulation loop (helpers.base_2b_loop0_loop0) is threaded opaquely and has no certificate — and it determines the FORS indices / WOTS digits, so a defect there could change the recomputed root while all eleven theorems still hold.
• Not the deployed public verifier: the proved subject is the private verify_mono facade; the bridge to upstream's generic pk.verify() is the finite in-snapshot differential test, not a machine-checked refinement.
• Not closed-form FIPS 205 correctness: the folds are transliterations of the extracted loops (the hash primitives stay opaque); nothing here relates the recomputed root to a mathematical SLH-DSA specification.
• Read every loop certificate as "visible", not "correct". This follows from the previous point but is worth stating on its own, because the per- certificate descriptions below are easy to over-read. Each reference fold is built from the same extracted primitives the loop calls, so any defect in the extracted code is faithfully copied into the fold and the theorem still holds. What is machine-checked is the loop's scaffolding — trip count, index arithmetic, state threading, argument order, branch structure. Whether the address schedule, the Merkle sibling order, or the FORS leaf index match FIPS 205 is a human reading step, not a proved one. (Round-5 review makes this sharper: the certificates are individually meaningful only to the extent someone has read each fold against the standard — see TRUSTED-BASE item 12.)

This is a real intermediate verification layer, not an end-to-end formal verification of the deployed verifier. After de-plumbing rounds 1+2 the model carries no plumbing axioms on the verify path — its external surface is exactly the five SHA-2 oracles (plus off-path zeroize impls). The trust base and residual assumptions are stated in TRUSTED-BASE.md.

• fips205.chain_free_loop_eq (Algorithm 5, WOTS+ chaining): the extracted chain_free loop equals the explicit s-fold hash chain, with the hash address set to i, i+1, …, i+s−1 in turn. This rules out — machine-checked, for the monomorphic SHA2-128s verify_mono path — an off-by-one loop bound and wrong state threading. (It does not rule out a wrong ADRS field: the reference fold is built from the same extracted set_hash_address primitive the loop calls, so a wrong field would be faithfully copied into the fold and the theorem would still hold. What the certificate pins is what the extracted code does at each index, so a wrong field is visible in the certificate, not excluded by it — the mapping onto FIPS 205 Alg 5 is a human reading step, consistent with "the folds are transliterations of the extracted loops" above.) Its #print axioms cone is exactly [propext, Classical.choice, Quot.sound, verify_mono.oracle.f] — the three kernel axioms plus the one hash oracle it touches, and nothing else (no transpiler plumbing; the u32 range machinery was discharged with real definitions). check.sh Phase 3 (the in-Lean exact-cone audit) fails the build if any certificate's cone differs from its expected set — an extra axiom or a dropped oracle both break it.

• fips205.wots_loop1_eq (Algorithm 8, WOTS+ pk recomputation — the chain loop): the extracted wots_pk_from_sig_free_loop1 equals the fold that, at each index i in [0, LEN), sets the chain address to i and runs chain_free on sig[i] starting at digit msg[i] for W−1−msg[i] steps, writing tmp[i]. This is the layer above chain: it consumes chain_free and pins that the LEN chains run with the right start indices, step counts, and slots. Cone: kernel three + verify_mono.oracle.f.

• fips205.xmss_loop_eq (Algorithm 10, XMSS pk-from-sig — the authentication-path Merkle loop): the extracted xmss_pk_from_sig_free_loop equals the fold that, at step k, sets the tree height to k+1, tests bit k of the leaf index, and on an even bit halves the tree index and hashes H(node ∥ auth[k]), on an odd bit sets the tree index to (i−1)/2 and hashes H(auth[k] ∥ node). This makes the Merkle sibling ORDER (the even/odd rule), the tree-height/tree-index address schedule, and the auth-path indexing VISIBLE in the certificate — it does not establish them as correct. xmssFoldN calls the same extracted set_tree_height/get_tree_index/oracle.h that the loop body calls, so a swapped sibling order would be copied into the fold and the theorem would still hold. Read that as: the certificate pins what the extracted code does at each step; whether that matches FIPS 205 Algorithm 10 is a human reading step. Cone: kernel three + verify_mono.oracle.h (the first certificate where H enters; F does not — the loop runs above the WOTS+ computation).

• fips205.ht_loop_eq (Algorithm 12, hypertree verification — the layer walk): the extracted ht_verify_free_loop equals the fold that, at layer j, splits the tree index (idx_leaf = idx_tree mod 2^h' by mask+cast, then idx_tree >>= h'), sets the layer address to j and the tree address to the shifted index, and recomputes the node through xmss_pk_from_sig on the j-th XMSS signature. This makes the layer schedule of hypertree verification visible in the certificate (same transliteration caveat as above); the final node = pk_root comparison sits one bind above, in ht_verify_free, and belongs to the apex composition. Cone: kernel three + verify_mono.oracle.{f, h, t_l} — the full WOTS+/XMSS machinery referenced through the fold, and nothing else.

Foundations behind this (2026-07-22/23): the Aeneas-compat patch (additive monomorphic verify module through a named oracle boundary; charon + aeneas exit 0); the u32 range-loop de-plumbing (faithful Step defs vs pinned rustc, axiom-clean); the 8-site source de-plumbing (snapshot commit 6f6a9d6: try_from/is_err/unwrap on pre-masked values → plain casts, the WOTS+ checksum iter().take() + &u32 Sub → an index loop — each site a local rewrite whose equivalence is argued in the commit and checked, for SHA2-128s, by the differential test; the obsoleted transpiler axioms were deleted from the external files); fidelity pinned by that differential test in the snapshot (valid / corrupted / wrong-message), re-run green after every source patch.

• fips205.fors_inner_loop_eq + fips205.fors_outer_loop_eq (Algorithm 17, FORS pk-from-sig): a nested loop, split into two theorems. The inner one equates the auth-path Merkle fold for a single FORS tree (bit source indices[i] >> j, H in the even/odd sibling order) — cone kernel-3 + oracle.h. The outer one equates the K-tree fold: for each tree compute the leaf with F at index (i<<a)+indices[i], run the inner Merkle loop, write root[i] — cone kernel-3 + oracle.{f, h}. Split into two files under the memory discipline; the outer step lemma closes by peeling its 16-bind body with bind_congr (a bare rfl there whnf-times- out over the nested inner loop).

• input-prep (fips205.to_int_loop_eq, to_byte_loop_eq, wots_csum_loop_eq, base2b_outer_loop_eq — Algorithms 2/3/4 + the WOTS+ checksum): the byte→integer, integer→byte, checksum, and digit-decomposition loops that prepare the verifier's inputs. All four cones are exactly [propext, Classical.choice, Quot.sound] — pure kernel-3, no hash oracle (byte/bit arithmetic touches no hash). base_2b's inner while loop is threaded opaquely, as every layer treats its sub-loops. These proofs became possible after de-plumbing round 2 (snapshot bea1051) rewrote to_int's iter().take() and base_2b's iter_mut() as index loops, removing the last Take/IterMut iterator adapters; the obsoleted Take axiom was then deleted.

The apex (slh_verify_128s_accepts_iff, above) sits at the top of this layer: the extracted verify_mono::slh_verify_128s accepts iff the recomputed hypertree root byte-equals the pinned public-key root. What remains genuinely unproven is stated in "What is NOT (yet) established" above — most sharply the opaque base_2b inner loop (no certificate) and the bridge from this private verify_mono facade to the deployed generic verifier (a finite differential test, not a machine-checked refinement). Each certificate is audited to the same boundary.

Subject

• Upstream: integritychain/fips205 — pure-Rust FIPS 205 (final standard, 2024-08-13), zero unsafe, no_std, const-generic parameterization, modules mirroring the FIPS 205 algorithm structure.
• Pinned at upstream commit 30bac08580aa61f653e5436d1bbacb5ffac446c4 (2025-09-01), snapshotted with full history at saymrwulf/fips205-source. The verbatim-import base commit's only deviation from upstream is the removal of CI workflows (documented in that commit); the Aeneas-compat and de-plumbing patches then landed as transparent, individually-justified commits on top — never upstream. The current snapshot head is 797b4ef (the round-2 reproducibility commit — committed Cargo.lock + pinned rust-toolchain.toml — on top of de-plumbing round 2, bea1051); the model in this repo is extracted from it, and verification/extract.sh refuses any other commit. No affiliation with, and no changes proposed to, the upstream project.
• Parameter set: SLH-DSA-SHA2-128s first (the small-signature profile deployed in the firmware/code-signing lane). The architecture generalizes; each further parameter set is a separate claim (rigor invariant R2).

Scope

Verify path only, rooted at slh_verify_internal. The extraction root is verify_mono::slh_verify_128s, which is slh_verify_internal_free(M′, sig, pk) — it takes the already-assembled message digest input M′ as an argument. So the covered cone is:

slh_verify_internal(M′, …)         ← the extraction ROOT (M′ is an input)
  -> fors_pk_from_sig
  -> ht_verify -> xmss_pk_from_sig -> wots_pk_from_sig -> chain

Everything above this root, in slh_verify/verify (src/lib.rs), is OUT of scope and is stated as such in TRUSTED-BASE.md: M′ assembly, the pure-vs-prehash domain-separator byte (0u8 for verify, 1u8 for hash_verify — the entire cross-variant separation), the ctx.len() > 255 check, and signature/public-key deserialization. A reader must NOT read slh_verify -> slh_verify_internal as "the top of the verify path is covered" — it is not; the top-of-path input handling is trusted base. Key generation and signing are out of scope (trusted base), exactly as ed25519 signing was. The five verify-path hash oracles (h_msg, f, h, t_l, t_len — SHA-2 instantiations; prf/prf_msg are sign-side only and never enter the cone) are opaque external models with written justifications. They are the only things beyond Lean's three kernel axioms that any certificate cone contains: each cone is exactly the kernel three plus the specific oracles that certificate's computation reaches (e.g. chain reaches F, so oracle.f is inside its cone; the input-prep helpers reach no hash, so their cones are kernel-3 alone). That the cones contain nothing else — no transpiler plumbing, no hidden axiom — is what the audit enforces (honesty invariant H4); their semantics are the standing SHA-2 oracle boundary documented in TRUSTED-BASE.md.

Gate-0 record (2026-07-22)

Per TARGETS.md ("re-verify before use"), the subject was probed before this repository was created:

• Charon: clean (charon cargo --preset=aeneas, roots at the verify cone, sha2/sha3/zeroize/rand_core opaque, features slh_dsa_sha2_128s) — LLBC produced, exit 0.
• Aeneas: translated the entire const-generic verify cone to Lean definitions (wots.chain … slh.slh_verify_internal all generated), with exactly one obstruction class (3 unique errors): the crate::hashers::Hashers struct of plain function pointers cannot be translated.
• Phase 1 — DONE (2026-07-22): the Aeneas-compat patch landed in fips205-source (snapshot 2d89ee3): an additive monomorphic SHA2-128s verify module (src/verify_mono.rs) whose hash suite is reached through named free functions in verify_mono::oracle (marked opaque at the Charon boundary) — the sha512_*-shim pattern. Two further compat refinements: the message-digest input M' passes as a single &[u8] (nested &[&[u8]] is untranslatable), and one let-else became the is_err/unwrap idiom. verification/extract.sh now re-derives the model from the mono root; charon + aeneas both exit 0, and verification/check.sh compiles the result. At this compat-patch commit the only change to pre-existing code was two lines wiring the new module; the generic paths and all twelve parameter sets stayed untouched. That scoping does not extend to the later de-plumbing commits, and the difference matters: round 1 (6f6a9d6) touched only the private verify_mono.rs, but round 2 (bea1051) rewrote to_int and base_2b in src/helpers.rs, which the DEPLOYED generic verify path and the SIGNING path also call (slh.rs, wots.rs, fors.rs). So the snapshot's deployed verifier — the one the differential test compares against — is itself patched relative to upstream 30bac08. src/wots.rs was never modified by any patch commit (an earlier revision of this README wrongly named it). See the snapshot history at head 797b4ef and TRUSTED-BASE.md item 7.

What is claimed (the button is green)

Each certificate is a statement about the extracted functions (H3), compiled by verification/check.sh with the in-Lean exact-cone audit (H1): chain semantics, WOTS+ pk recomputation, XMSS path recomputation, hypertree acceptance, FORS pk recomputation, the input-prep helpers, and the apex — verify_mono::slh_verify_128s accepts iff the recomputed hypertree root equals the pinned public-key root. The precise scope and non-claims are in the STATUS section above.

The allowed axiom set, stated precisely: unlike the ed25519 field and scalar layers (whose cones are exactly [propext, Classical.choice, Quot.sound]), the hash oracles permeate every SLH-DSA layer — chain already calls F. Each certificate's cone is therefore the three kernel axioms plus exactly the named oracles its computation reaches (and nothing else). The transpiler-plumbing axioms that once sat in FunsExternal.lean were discharged (de-plumbing rounds 1+2) before any certificate shipped; the audit fails the button if anything outside a certificate's expected boundary — plumbing, an extra oracle, or a dropped one — appears in its cone.

Discipline

Every Lean compile in this repository runs under verification/lean-guard (memory-capped, machine-wide serialized). Extraction is reproducible: the full pin set (source commit, Charon/Aeneas commits + toolchain channel, Lean and OCaml versions) is in verification/PROVENANCE.json; verification/extract.sh refuses to run against a wrong-commit or dirty source tree, and re-running it reproduces the aeneas-generated model byte-identically (verified 2026-07-24). The axiom audit runs inside Lean (verification/Proofs/Audit.lean): exact per-certificate cone equality, fail-closed, adversarially exercised by verification/check-selftest.sh. What cannot be proven is named in TRUSTED-BASE.md, not hidden (H5).