Part of Lock.Boot. The preferred stage2 layering in the chain (stage0 → stage1 → stage2) — replaceable, like any lockboot stage, with your own. It is a payload-agnostic loader, not a container runtime: it takes any container image, seals it into a measured, TPM-bound, integrity-checked form, and boots it. "Run this Docker container under Lock.Boot."
By the time this runs, the layers below have admitted and verified it (sha256/ed25519, PCR 14). Trust and verification are not this layer's concern — it consumes an already-trusted payload.
A small, low-churn loader binary (bootstrap, static-musl, PID 1) with a container image
appended to it as a self-extracting zip. The workload never touches the loader — you swap the
appended image freely without recompiling the (audited, reproducible) loader. stage1 measures the
whole loader+image into PCR 14, so the image identity is attested for free. Deployment is just
packaging: docker export → mkfs.erofs → veritysetup → zip → append to the loader ELF.
Each v* release publishes a multi-arch (linux/amd64 + linux/arm64) erofs-builder image
with that release's loaders for both arches baked in, so there is no separate loader download. Pin
it by the digest in the release notes, and verify its provenance first:
IMG=ghcr.io/lockboot/stage2-erofs-builder@sha256:<digest from the release notes>
gh attestation verify "oci://$IMG" --repo lockboot/stage2
docker export "$(docker create --rm myimage)" \
| docker run --rm -i "$IMG" --arch aarch64 - - > stage2 # or --arch x86_64--arch picks the target arch of the loader, independent of the host's: an amd64 host can pack an
aarch64 stage2 and vice versa, with identical output.
Build the loader and the packaging image once:
make build-x86_64 docker-build-erofs
# build-x86_64 -> target/x86_64-unknown-linux-musl/release/bootstrap (the loader ELF)
# docker-build-erofs -> lockboot:erofs-builder (a one-shot CLI; mkruntime.sh is its entrypoint)The image is the tool. Mount just the loader ELF, pipe any container rootfs in on stdin, and the
bootable stage2 comes out on stdout — no repo bind-mount, no host filesystem tools:
docker export "$(docker create --rm myimage)" \
| docker run --rm -i \
-v "$PWD/target/x86_64-unknown-linux-musl/release/bootstrap:/bootstrap:ro" \
lockboot:erofs-builder --bootstrap /bootstrap - - > stage2The rootfs argument (- above) can instead be a .tar, a directory, or a single binary (installed
as /init); the output (-) can be a path. docker run --rm lockboot:erofs-builder --help lists
the env knobs (DATA_SIZE_MB, ROOTFS_UUID, VERITY_SALT, SOURCE_DATE_EPOCH), all reproducible
by default. Serve the resulting stage2 as your payload; stage0/stage1 admit it by sha256/ed25519.
- Read its own payload from
/proc/self/exe(a memfd) — the appended zip carriesrootfs.erofs(+ its dm-verity hash tree), a deterministic emptydata-base.img, andverity.json. - Bind the config: hash the verbatim stdin JSON into PCR 15, then rewind fd 0 so the workload reads the exact same bytes.
- Derive keys from the TPM, bound to the boot-chain PCRs (see below).
- Runtime (p2) — flush the erofs to the partition only if it doesn't already verify, then dm-verity-mount it read-only.
- Root — assemble an overlay: the verity'd erofs as the immutable lower, a tmpfs
upper. The merged
/is therefore pure verity'd erofs at every boot — runtime writes hit RAM and can never persist to shadow the measured code. - Data (p3) — bring up
/data: dm-cryptaes-xts-plain64(AES-256-XTS), grown online to fill the disk. Confidential; the TPM-derived key binds it to the boot chain. - Attest — copy stage1's attestation and drop stage2's alongside it in an ephemeral
/run/lockboot/. switch_rootonto the overlay andexec /init— the image's own entrypoint, handed the verbatim config on stdin. Transparent: stage2 imposes no config schema of its own.
| Layer | Mechanism | Guarantee |
|---|---|---|
| Code / rootfs | erofs + dm-verity, measured into PCR 14, under an ephemeral overlay | Immutable, integrity-verified, re-attestable each boot — no persistent code modification |
| Config | verbatim stdin JSON → hashed → PCR 15 | Disk key bound to config; any change ⇒ fresh disk (fail-closed) |
| Data | /data: dm-crypt aes-xts-plain64 (AES-256-XTS) |
Confidential (confidentiality-only): at-rest tamper garbles rather than being cryptographically detected — media integrity is left to the storage layer (EBS et al.) |
| Keys | TPM-derived under a PolicyPCR session over a curated PCR set |
No LUKS/header; drift in bound PCRs (code/config/firmware) ⇒ superblock decrypts to garbage ⇒ re-initialized (fail-closed) |
See PCR-BINDING.md for the bound PCR set, the {5,10} exclusions, and the IMA
analysis.
Everything builds inside the shared lockboot:build image (no host toolchain); the runtime image is
forged in the build-time-only lockboot:erofs-builder — none of those tools ship to the instance.
Reproducible: the loader ELF and the payload zip are each byte-deterministic.
make lock # generate Cargo.lock (first time)
make check test # cargo check + test the workspace
make ci # fmt + clippy + test (the CI gate)
make pack-x86_64 # pack the bundled example -> build/x86_64/pack/stage2
make test-pivot-x86_64 # boot a packed stage2 under the QEMU/swtpm harnessunzip -l build/<arch>/pack/stage2 inspects a packed payload.
bootstrap— the loader: read the appended payload, bring up persistence, pivot onto the overlay root,exec /init.payload— the minimal appended-zip reader (self-extracting; reads/proc/self/exe).blockdev— raw device-mapper ioctls (nolibdevmapper): dm-verity, dm-crypt (XTS), byte-stable GPT grow/discovery, ext4 online grow.tpm-derive— deterministic PCR-bound key derivation (pure-Rust TPM2).
Apache-2.0 OR MIT, at your option.