msw/CISS.debian.live.builder
SHA256
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

V9.14.022.2026.06.10: Document rootfs attestation boundary

Browse Source
This commit is contained in:
André H. Zimnol
2026-06-10 23:13:49 +02:00
parent eeecefc966
commit 6aeb9037ea
1 changed files with 48 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/MAN_CISS_ISO_BOOT_CHAIN.md
+48 -19
View File
@@ -12,19 +12,24 @@ include_toc: true
# 2. CISS.debian.live.builder – Boot & Trust Chain (Technical Documentation)
**Status:** 2025-11-12<br>
**Status:** 2026-06-10<br>
**Audience:** CICA CISO, CISS staff, technically proficient administrators<br>
**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.<br>
**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.<br>
# 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 ... <FPR> ...
```
# 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/<FPR>.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/<FPR>.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/)**