Skip to content

docs: close the README with an overview instead of a stage section #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DavidCozens merged 1 commit into from
Jul 30, 2026
Merged

docs: close the README with an overview instead of a stage section #48

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 12 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,24 +10,26 @@ 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.

<!-- STAGE-COST:START (generated by scripts/gen-cost-table.py — do not edit by hand) -->

**Cost above baseline: Flash +13,780 B, RAM +37,748 B.**

<!-- STAGE-COST:END -->

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

Expand Down
Loading