diff --git a/docs/MAN_CISS_ISO_BOOT_CHAIN.md b/docs/MAN_CISS_ISO_BOOT_CHAIN.md index 31af2f2..469f0e3 100644 --- a/docs/MAN_CISS_ISO_BOOT_CHAIN.md +++ b/docs/MAN_CISS_ISO_BOOT_CHAIN.md @@ -12,19 +12,24 @@ include_toc: true # 2. CISS.debian.live.builder – Boot & Trust Chain (Technical Documentation) -**Status:** 2025-11-12
+**Status:** 2026-06-10
**Audience:** CICA CISO, CISS staff, technically proficient administrators
-**Summary:** The **CISS.debian.live.builder** Live-ISO establishes a two-stage verification chain around the live root: an early ISO-edge check (signature and FPR pin) *before* LUKS unlock, and a late root-FS attestation *after* unlock, reinforced by `dm-crypt (AES-XTS)` and `dm-integrity (HMAC-SHA-512)`. UEFI Secure Boot can use either the default Microsoft/Debian shim chain, or a CISS-signed UKI chain for systems that trust the CISS Secure Boot key material.
+**Summary:** The **CISS.debian.live.builder** Live-ISO establishes a two-stage verification chain around the live root: an +ISO-edge checksum-manifest check and a late attestation of the complete selected decrypted rootfs mapper. The late check verifies +both the signed SHA-512 manifest and the mapper bytes before boot continues. `dm-integrity` separately provides sector-integrity +protection and is not a substitute for origin-bound signature and checksum attestation. UEFI Secure Boot can use either the +default Microsoft/Debian shim chain, or a CISS-signed UKI chain for systems that trust the CISS Secure Boot key material.
# 3. Overview * **Trust anchor:** Pinned fingerprint (FPR) of the signing key embedded at build time in initramfs hooks. * **Integrity & authenticity verification:** - 1. **Early:** Verify `sha512sum.txt` at the ISO edge using `gpgv` and FPR pin. - 2. **Late:** Verify an attestation hash list inside the decrypted root FS using `gpgv` and FPR pin. + 1. **ISO edge:** Verify one supported checksum manifest using `gpgv`, FPR pinning, and the matching checksum tool. + 2. **Late rootfs attestation:** Verify the signed mapper manifest and the complete selected decrypted mapper + `/dev/mapper/crypt_liveiso` with `sha512sum -c`. -* **Storage-level AEAD (functional):** `dm-crypt` (AES-XTS-512) and `dm-integrity` (HMAC-SHA-512, 4 KiB). +* **Storage-level protection:** `dm-crypt` (AES-XTS-512) and, outside runner builds, `dm-integrity` (HMAC-SHA-512, 4 KiB). * **Remotely unlock:** CISS hardened and build dropbear, modern primitives only, no passwords, no agent/forwarding. # 3.1. Secure Boot Profiles @@ -52,11 +57,11 @@ private Secure Boot key names are detected in those paths before live-build chec | Component | Primitive / Parameter | Purpose | |--------------|-----------------------------------------------------------|--------------------------------------------------------| | LUKS2 | `aes-xts-plain64`, `--key-size 512`, `--sector-size 4096` | Confidentiality (2×256-bit XTS) | -| dm-integrity | `hmac-sha512` (keyed), journal | Adversary-resistant per-sector integrity, authenticity | +| dm-integrity | `hmac-sha512` (keyed), journal | Per-sector integrity inside the LUKS mapping; not origin attestation | | PBKDF | `argon2id`, `--iter-time 1000` ms | Key derivation, hardware-agnostic | | Signatures | Ed25519 or RSA-4096 (FPR pinned) | Public verifiability, non-repudiation | | Verification | `gpgv --no-default-keyring` | No agent dependency in initramfs | -| Hash lists | `sha512sum` format | Deterministic content verification | +| Hash lists | `sha512sum` format | Deterministic ISO-edge and decrypted-mapper verification | | Dropbear | Modern KEX/AEAD (per `localoptions.h`) | Minimal attack surface, remote unlock | # 5. Diagram: CISS Live ISO Boot Flow @@ -150,7 +155,8 @@ flowchart TD ``` -**Note:** Encrypt-then-MAC at the block layer (functionally AEAD-equivalent). Any manipulation ⇒ hard I/O error. +**Note:** `dm-integrity` detects sector corruption within its keyed mapping. The signed SHA-512 mapper manifest independently +binds the selected decrypted rootfs payload to the signing key. Neither property substitutes for the other. # 7. CISS Live ISO LUKS Build-Time Core Steps ```sh @@ -172,16 +178,24 @@ cryptsetup luksFormat \ "${LUKSFS}" ``` +After `filesystem.squashfs` is copied to `/dev/mapper/crypt_liveiso`, the binary hook hashes the complete decrypted mapper, +including the mapper padding after the SquashFS image. It writes +`binary/live/ciss_rootfs.crypt.decrypted.sha512sum.txt`, signs that manifest with the existing artifact-signing key, verifies the +signature and checksum locally, and only then closes the mapping and removes the plaintext `filesystem.squashfs`. + **Signing keys:** Ed25519 and RSA-4096; **FPR pinned at build time** in hooks. Signing keys are **additionally** signed by an offline GPG Root-CA (out-of-band trust chain). # 8. Early ISO-Edge Verification (CISS modified hook 0030-ciss-verify-checksums, live-bottom) -**Goal:** Before consuming any medium content, verify: +**Goal:** During live-boot, require one supported ISO-edge checksum manifest to be successfully verified: 1. **Detached signature of `sha512sum.txt`** using `gpgv` against the embedded public key. 2. **FPR pinning:** Parse `VALIDSIG` and require exact match with the build-time pinned FPR. 3. **Optional:** *Script self-IA* – hash the executed hook and compare against the signed list (drift/bitrot detector). +Verification is fail-closed. Boot panics if no supported manifest is present, no matching checksum tool is available, checksum +verification does not succeed, signature verification fails when requested, or verification ends in an unknown state. + **Core call (initramfs):** ```sh @@ -189,12 +203,16 @@ cryptsetup luksFormat \ # parse [GNUPG:] VALIDSIG ... ... ``` -# 9. Late Root-FS Attestation and dmsetup Health (CISS hook 0042_ciss_post_decrypt_attest, called by 9990-overlay.sh) +# 9. Late Root-FS Payload Attestation (CISS hook 0042_ciss_post_decrypt_attest, called by 9990-overlay.sh) -**Goal:** After LUKS unlock, validate the **decrypted** contents and the **actual** mapping topology. +**Goal:** After LUKS unlock and rootfs selection, verify the authenticity of the manifest and the content of the actual selected +decrypted rootfs payload. -* **Attestation files:** `/root/.ciss/attestation/.sha512sum.txt[.sig]` -* **Key source:** `/etc/ciss/keys/*.gpg` (accepted only if FPR == build-pin) +* **Exact attested boundary:** the complete `/dev/mapper/crypt_liveiso` block payload selected by `9990-overlay.sh` and mounted + read-only as SquashFS, including mapper padding after the SquashFS image. +* **Attestation files:** `/run/live/medium/live/ciss_rootfs.crypt.decrypted.sha512sum.txt[.sig]` +* **Key source:** `/etc/ciss/keys/.gpg` in the initramfs; the valid signature FPR must equal the build-time pin. +* **Manifest constraint:** exactly one checksum record is accepted, and it must target the selected mapper path. **Core calls (initramfs):** @@ -202,13 +220,20 @@ cryptsetup luksFormat \ # 1) Signature and FPR pin (no agent) /usr/bin/gpgv --no-default-keyring --keyring "$KEYFILE" --status-fd 1 --verify "$SIG" "$DATA" -# 2) Optional: Content hash verification -( cd "$ROOTMP" && /usr/bin/sha512sum -c --strict --quiet "$DATA" ) +# 2) Required selected-payload verification +( cd / && /usr/bin/sha512sum -c --strict --quiet "$DATA" ) ``` +The signed manifest alone is not sufficient: boot continues only after the selected decrypted mapper content matches it. +This boundary does not individually attest the mounted file tree, OverlayFS upper layer, runtime mutations, or secrets after +unlock. + # 10. Failure Policy (fail-closed, deterministic) -* **Abort** on: missing `VALIDSIG`, FPR mismatch, missing key / signature. +* **ISO-edge abort:** no supported manifest, no supported verification tool, failed checksum, failed requested signature, or + unknown verification state. +* **Rootfs-attestation abort:** missing or malformed manifest/signature/key, missing `VALIDSIG`, FPR mismatch, manifest target + mismatch, unreadable or non-block selected mapper, or mapper checksum mismatch. # 11. CISS hardened and built dropbear @@ -251,17 +276,19 @@ flowchart TD subgraph ISO Build Time A["Embed and pin GPG FPR (into ISO & RootFS as needed)"] e00@--> B["Generate ISO-edge sha512sum.txt and .sig"]; B e01@--> C["Build filesystem.squashfs and wrap it into ciss_rootfs.crypt"]; + C e01a@--> C2["Hash complete decrypted mapper and sign rootfs manifest"]; e00@{ animation: fast } e01@{ animation: fast } + e01a@{ animation: fast } end subgraph ISO Boot Time - C e02@--> D["0024 LUKS2, dm-integrity HMAC-SHA512"]; + C2 e02@--> D["0024 LUKS2, dm-integrity HMAC-SHA512"]; D e03@-->|SUCCESSFUL| E["ciss_rootfs.crypt opened"]; E e04@--> F["Mounting RootFS"]; F e05@--> G["0030 verification of authenticity and integrity via embedded and pinned GPG of ISO edge"]; G e06@-->|SUCCESSFUL| H["ISO edge verified"]; - H e07@--> I["0042 post-decrypt-attestation of RootFS"]; + H e07@--> I["0042 verifies signed manifest and selected decrypted mapper"]; I e08@-->|SUCCESSFUL| J["RootFS attestation successful"]; e02@{ animation: fast } e03@{ animation: fast } @@ -285,7 +312,9 @@ I -- FAIL --> X; # 14. Closing Remarks -This achieves a portable, self-contained trust chain without a Microsoft-db, providing strong protection against medium tampering, bitrot, and active attacks **both before and after decryption**. The dual-verification phases make the state transparent and deterministic. +The verification path is fail-closed and binds the selected decrypted rootfs mapper to the pinned signing key. `dm-integrity` +adds a separate sector-integrity property where enabled. The implemented attestation does not cover runtime OverlayFS changes, +post-unlock secrets, or an individually enumerated mounted file tree. --- **[no tracking | no logging | no advertising | no profiling | no bullshit](https://coresecret.eu/)**