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/)**