mirror of
https://github.com/saymrwulf/verifying-crypto-with-lean.git
synced 2026-09-03 19:53:45 +00:00
mrwulf
1f11b8aa4d
The operator caught what no check had ever tested: nobody had LOOKED at
the rendered pages. A ten-inspector visual audit of all 129 pages (every
page opened as an image) found 40 defects, including didactic
correctness bugs invisible to the text layer:
BAD, fixed:
- ch03 printed WRONG Lean operators: \lean{P /\ Q} lost its backslash
('P / Q') and \lean{P \/ Q} lost the operator entirely ('P Q') —
TeX ate them inside the non-verbatim macro. Now the unicode ∧/∨ the
book uses everywhere else.
- ch12: the doubling display overflowed its box border, slicing the
math; stacked on two lines.
- toolkit Card 6: the headroom-audit display was clipped by the page
edge; now an align* stack.
UGLY, fixed:
- title page: the 'pyramid motif' at 5% white opacity on near-black
rendered as smudge artifacts, plus a clipped ∀ glyph in the corner
— redrawn with solid mixed colors (no transparency), glyph removed;
the footer's mid-word paragraph gap was a \vspace landing inside
horizontal mode; fixed with \par
- ch06: both clock diagrams' wrap-around arrows ran counterclockwise,
retracing over earlier arcs — target position expressed as 12 (one
revolution) so the arc continues clockwise, landing on 0 (mod 12)
and 1 (mod 11) correctly
- ch04: two_mul'' printed as two_mul" (quote ligature)
- one-line orphaned box fragments and stranded solution headings
throughout: bigidea/tryit/pitfall/aha/checkpoint are now unbreakable
(none exceeds half a page), worked boxes announce '(continued)' after
a break, \solhead keeps four lines with \Needspace
- --all/--receipt flags printed as one merged dash: \ddash macro
- inline code no longer hyphen-breaks at underscores (codeguards)
- ch09's 2^{...} smudge, glossary margin overflow, ch08 orphaned
listing line, ch13 command-line layout, three >10pt overfulls
THE STRUCTURAL LESSON, encoded: the two worst clipping bugs had been
announced as 80pt/73pt overfull warnings in every build log and ignored.
check-book.sh now FAILS on any overfull box past 10pt — the machine was
telling us; now it is allowed to stop us.
132 pages; publication-history and README counts synced; every fixed
page re-rendered and verified by eye. Button: ALL GREEN (96 checks).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
168 lines
9.3 KiB
Markdown
168 lines
9.3 KiB
Markdown
# Verifying Cryptography with Lean 4
|
||
|
||
**A hands-on curriculum for undergraduates with zero formal-verification
|
||
background** — from `1 + 1 = 2` to reading (and extending) real,
|
||
machine-checked proofs that production elliptic-curve code is correct.
|
||
|
||
This is the educational companion to a family of verification projects in
|
||
which complete Ed25519 proof pyramids (from
|
||
[curve25519-dalek](https://github.com/dalek-cryptography/curve25519-dalek)
|
||
and three production forks — field, group law, scalars, and the signature
|
||
verifier itself) and the Pasta curves' field layer were machine-checked in
|
||
Lean 4 against models extracted from the actual Rust sources:
|
||
|
||
| Companion project | What is verified there |
|
||
|---|---|
|
||
| [dalek-ed25519-verified](https://github.com/saymrwulf/dalek-ed25519-verified) | the complete pyramid, upstream dalek: field 𝔽ₚ + Edwards group law + scalar arithmetic mod ℓ + the four-tier signature apex (accept ⇔ decompress(R) = [k](−A)+[s]B, hash opaque) |
|
||
| [anza-ed25519-verified](https://github.com/saymrwulf/anza-ed25519-verified) | the complete pyramid, Solana's fork, its own extraction |
|
||
| [risc0-ed25519-verified](https://github.com/saymrwulf/risc0-ed25519-verified) | the complete pyramid, RISC Zero's fork |
|
||
| [betrusted-ed25519-verified](https://github.com/saymrwulf/betrusted-ed25519-verified) | the complete pyramid, Betrusted's fork |
|
||
| [pasta-pallas-verified](https://github.com/saymrwulf/pasta-pallas-verified) | Pallas modulus primality (Lucas/Pratt), Montgomery foundations |
|
||
| [formal-verification-control](https://github.com/saymrwulf/formal-verification-control) | the method: invariants, terrain map, failure map, tooling |
|
||
|
||
## The book
|
||
|
||
**[`main.pdf`](main.pdf)** — fourteen chapters + interlude + three
|
||
appendices, full color, built with LaTeX/TikZ from the sources in this
|
||
repo (`./build.sh`, tectonic, no root needed). **Second edition,
|
||
published August 8, 2026** (132 pages; the full publication history is
|
||
printed in the book's front matter). No prior Lean or formal
|
||
methods assumed; high-school algebra and a little programming suffice.
|
||
|
||
1. **Why Verify?** — the carry bug testing cannot find
|
||
2. **Meet Lean** — programs, types, inductive data
|
||
3. **Propositions as Types** — Curry–Howard: proofs *are* programs
|
||
4. **Tactics** — proving as a dialogue with the goal state
|
||
5. **Numbers and Automation** — `omega`, `ring`, `norm_num`, `decide`, and the `simp` discipline
|
||
6. **Modular Arithmetic** — clock worlds, fields, why 2²⁵⁵ − 19
|
||
7. **Primality Certificates** — convincing a paranoid kernel a 77-digit number is prime
|
||
8. **From Rust to Lean** — the Charon/Aeneas extraction pipeline
|
||
9. **The Denotation Bridge** — the commuting square at the heart of it all
|
||
— ***Interlude*** — a complete verification, entirely by hand, then re-enacted in Lean line by line
|
||
10. **Verifying a Field** — the full campaign, told honestly (including the crash)
|
||
11. **Honesty and Axioms** — `#print axioms`, hollow certificates, trusted bases
|
||
12. **The Pyramid** — group law, scalars, signatures, and where you come in
|
||
13. **The Second Summit** — a hash-based pyramid for the quantum era: SLH-DSA (FIPS 205), Winternitz chains and the checksum see-saw, the virtual hypertree, the eleven certificates and their cone-growth table, and leaf 18 live
|
||
14. **The Attestation Protocol** — what it takes to make "it is proven" checkable by a stranger; closes with *Go and touch the real thing*: a guided reading of the estate's **live transparency log** (ltl.zkdefi.org — 19 leaves, the four ed25519 pyramids at 44 certificates, the log's own Merkle proofs as leaf 17, and the first post-quantum leaf, SLH-DSA, as leaf 18), including the fifteen-minute verify-it-yourself exercise
|
||
|
||
Appendices: **A** — the pen-and-paper toolkit (recipe cards with drills);
|
||
**B** — guided walkthroughs of every exercise-file hole; **C** — a tour of
|
||
the real repositories. Plus a glossary and a fourteen-week course plan.
|
||
|
||
The didactic machinery, deliberately heavy:
|
||
|
||
- **Pen-and-paper worked examples in every chapter** — computations with
|
||
the *real* constants (2²⁵⁵−19, radix 2⁵¹, the fold constant 19, the
|
||
actual 254-squaring inversion chain, the true Pratt tree
|
||
p−1 = 2²·3·65147·Q), because the real numbers carry the real arguments.
|
||
Highlights: inverting 19 modulo the 77-digit prime in five lines of
|
||
Euclid; a fully hand-checked primality certificate for 97; the ×19 fold
|
||
derived at the real weights; the 16p subtraction constant audited to the
|
||
bit (8 fails by 151); the complete Bernstein–Lange completeness chain.
|
||
- **Solutions immediately after every exercise set** — each one leads with
|
||
the *pathway* (how a person finds the answer) before the answer itself.
|
||
- Boxed **Big idea / Try it / Pitfall / Aha / Checkpoint** elements, TikZ
|
||
figures throughout.
|
||
|
||
Everything the book claims about the companion projects reflects their
|
||
actual, auditable state — including open frontiers.
|
||
|
||
## The exercises (they run!)
|
||
|
||
`exercises/ChNN.lean` are working files with `sorry` holes;
|
||
`solutions/ChNN.lean` are complete. **Every solution file compiles with
|
||
zero errors** against the pinned toolchain (Lean `v4.30.0-rc2`, Mathlib
|
||
`5450b53e`); solutions to proof exercises contain no `sorry`.
|
||
|
||
Setup (one-time, ~5 min + Mathlib cache download):
|
||
|
||
```bash
|
||
# 1. install elan (Lean version manager) if you haven't:
|
||
curl https://elan.lean-lang.org/elan-init.sh -sSf | sh
|
||
# 2. fetch the Mathlib build cache (do NOT build Mathlib yourself):
|
||
cd verifying-crypto-with-lean
|
||
lake exe cache get
|
||
# 3. open the folder in VS Code with the "Lean 4" extension, or:
|
||
lake build Solutions # compiles all solution files as a check
|
||
```
|
||
|
||
Chapters 2–4 need no Mathlib at all — you can start them with any Lean 4
|
||
install while the cache downloads.
|
||
|
||
## The button
|
||
|
||
Like every repository in this estate, the book has one command that earns
|
||
its claims — and it is the only source of the words "ALL GREEN" here:
|
||
|
||
```bash
|
||
./check-book.sh
|
||
```
|
||
|
||
It rebuilds the PDF from the committed sources and then verifies ~90
|
||
countable claims printed in the book against reality measured at run
|
||
time: chapter and week-plan counts, exercise↔solution pairing per chapter,
|
||
every chapter ending on its checkpoint, the recomputed SLH-DSA arithmetic
|
||
(digest split, signature size, the 3,824-call worst case), the
|
||
transparency log's 19 leaves and per-leaf certificate counts, leaf 18's
|
||
axiom cones, the first dual-signed head at size 14, the extracted
|
||
SLH-DSA-SHA2-128s parameter card, and chapter 7's 71-digit Q — digit for
|
||
digit against `P25519.lean`. Numbers are parsed out of the prose and
|
||
compared to measurements, so editing either side alone turns the button
|
||
red. Cross-repo checks need the sibling estate repos checked out next to
|
||
this one (`BOOK_LOCAL_ONLY=1` skips them, loudly, and never prints ALL
|
||
GREEN). `./check-book.sh --selftest` mutates copies of the sources seven
|
||
ways and proves each mutation is caught by its own check.
|
||
|
||
## Building the book
|
||
|
||
The repo's own recipe (tectonic, user-space, no root — installs itself on
|
||
first run):
|
||
|
||
```bash
|
||
./build.sh
|
||
```
|
||
|
||
Or any TeX Live ≥ 2023 with `tikz`, `tcolorbox`, `listings`, `lmodern`:
|
||
|
||
```bash
|
||
pdflatex main.tex && pdflatex main.tex # twice for the TOC
|
||
```
|
||
|
||
## Honesty ledger
|
||
|
||
In the spirit of Chapter 11:
|
||
|
||
- All `solutions/*.lean` were compiled (and their `#eval` outputs checked
|
||
against their comments) at authoring time with the pinned versions above.
|
||
- Exercise templates compile with `sorry` warnings only.
|
||
- The book's claims about the companion projects (what is proven, what is
|
||
frontier) mirror those repos' own READMEs and TRUSTED-BASE ledgers at the
|
||
time of writing; the repos, not this book, are the source of truth.
|
||
Re-audited 2026-07-06 after the signature apex reached its final
|
||
four-tier form (coherence pass 4): chapter 12's status diagram, apex
|
||
section, and audit-drill solution, chapter 11's boundary example,
|
||
chapter 8's extraction notes, the repo tour, and this table were
|
||
brought up to the proven state.
|
||
- Didactic revision (2026-07-06, same day): the book now states and keeps
|
||
a "ratchet rule" (chapter 1) — every load-bearing idea worked at napkin
|
||
scale AND at real scale with the full 77-digit constants printed,
|
||
nothing elided. Chapter 12 gained the missing rungs: the addition law
|
||
run by hand on a mod-13 curve and then on the real base point (with a
|
||
machine-supplied quotient witness audited by casting out nines and
|
||
elevens), the scalar cycle felt on the napkin curve, decompression run
|
||
twice (mod-13 sign-bit walk, then the real compressed base point:
|
||
byte-31 sign bit, and the full-size hand verification 5·y_B − 4 = 4·p,
|
||
every digit printed), plus a new paper exercise (12.4). Every printed
|
||
constant was machine-verified before typesetting.
|
||
- The PDF in the repo is built from the committed sources by `./build.sh`
|
||
and recommitted alongside source changes; rebuild it yourself if you
|
||
don't trust binaries (good instinct), and you should get the same
|
||
fourteen-chapter book.
|
||
- The three named solution certificates were kernel-audited
|
||
(coherence pass 2, 2026-07-03): `Ch09.add_spec` depends on
|
||
`[propext, Classical.choice, Quot.sound]`; `Ch09.mulVal_spec` and
|
||
`Ch12.addFixed_spec` on `[propext, Quot.sound]` only. The Interlude's
|
||
"compiled and axiom-audited" phrase shipped one pass before its audit
|
||
had actually been run — caught by the verification projects' own
|
||
coherence process and made true; recorded here in the spirit of
|
||
Chapter 11.
|