From 16718bb968308a7c296f4ea862bd6eed14b3376b Mon Sep 17 00:00:00 2001 From: David Cozens Date: Wed, 29 Jul 2026 12:52:17 +0100 Subject: [PATCH] docs: close the README with an overview instead of a stage section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every commit so far rewrote "## This stage —" to describe the one capability it added. At the tip that section is the wrong shape: a reader arriving at the head of the branch wants to know what the device ends up doing and what the whole thing cost, not what the last commit changed about it. It becomes "## Where it ends up" — the record the device actually sends, with its four SD elements, mutual TLS and AES-256-GCM store; the generated total; and an instruction to read the history forward from the Baseline commit rather than to treat the tip as the product. That instruction is the point of the repository: the diff is what a reader applies to their own build, so the sequence is the deliverable and the tip is only where it happens to stop. The STAGE-COST block stays where it was, so the headline figure is still written by scripts/gen-cost-table.py from measurements/aes-gcm.csv. The minimum useful cost is pointed at rather than quoted — it is already a row in the table below, and a figure written into prose here would go stale silently the first time anything moved. No stage row, no CSV, and run-report.md is untouched: nothing here reaches the binary, so there is no measurement to take. --- README.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 6338de3..a276206 100644 --- a/README.md +++ b/README.md @@ -10,15 +10,12 @@ It builds on a baseline that simulates the sort of device you might be adding th measures itself: see [docs/baseline.md](docs/baseline.md) for what the baseline is, how the figures are made, and how to run it. -## This stage — AES-GCM at rest +## Where it ends up -Spooled records are encrypted with AES-256-GCM rather than only sealed. Anyone who takes the -volume — a pulled card, a recovered device, a backup — learns nothing from what is on it. - -The record header is authenticated alongside the encrypted body, so the tamper-evidence of the -previous stage is kept rather than traded away. The key is the same one the seal used: its name -says what it protects, not which algorithm protects it, so strengthening the policy needs nothing -new provisioned. +The device logs one RFC 5424 record carrying four SD elements — sequence and uptime, time quality, +origin, and a private element naming the protection its own log pipeline is under. The record goes +to the collector over mutual TLS and is spooled to a local store encrypted with AES-256-GCM, so +records survive a failed send and a disk that leaves the device gives nothing away. @@ -26,8 +23,13 @@ new provisioned. -The full report for this stage — what the device did, every figure, and the self-check — is -committed as [`run-report.md`](run-report.md), and rewritten by every stage. +Most devices want less than that. The table below prices every stage, and the cheapest row that +does anything useful — a valid, timestamped record on the wire — is a fraction of it. + +**Read it as a sequence.** Start at the Baseline commit and step forward: `git show` on any stage +gives you the diff to apply to your own build, the reasoning behind it, and the measured cost of +applying it — each stage's run is committed alongside it as [`run-report.md`](run-report.md). Stop +where your device's threat model does. ## Every stage