diff --git a/README.md b/README.md
index 674bf92..c57caff 100644
--- a/README.md
+++ b/README.md
@@ -44,10 +44,10 @@ changes and made publicly available for download. The latest generic ISO is avai
Beyond a conventional live system, **CISS.debian.live.builder** assembles a **fully encrypted, integrity-protected live medium**
in a single, deterministic build step: a LUKS2 container backed by `dm-integrity` hosting the SquashFS root filesystem, combined
-with a hardened initramfs chain including a dedicated Dropbear build pipeline for remote LUKS unlock. The resulting ISO ships
-with a hardened kernel configuration, strict sysctl and network tuning, pre-configured SSH hardening and fail2ban, and a
-customised `verify-checksums` path providing fail-closed ISO-edge verification and runtime attestation of the exact final
-SquashFS payload bytes selected for the encrypted live root. All components are aligned with the `CISS.debian.installer`
+with a hardened initramfs chain including a dedicated Dropbear build pipeline for remote LUKS unlock. The resulting ISO ships
+with a hardened kernel configuration, strict sysctl and network tuning, pre-configured SSH hardening and fail2ban, and a
+customised `verify-checksums` path providing fail-closed mounted-medium verification plus runtime attestation of the exact
+final SquashFS payload bytes selected for the encrypted live root. All components are aligned with the `CISS.debian.installer`
baseline, ensuring a unified cryptographic and security posture from first boot to an installed system. For an overview of the
entire build process, see:
**[MAN_CISS_ISO_BOOT_CHAIN.md](docs/MAN_CISS_ISO_BOOT_CHAIN.md)**
diff --git a/docs/MAN_CISS_ISO_BOOT_CHAIN.md b/docs/MAN_CISS_ISO_BOOT_CHAIN.md
index ba25a9c..e27d678 100644
--- a/docs/MAN_CISS_ISO_BOOT_CHAIN.md
+++ b/docs/MAN_CISS_ISO_BOOT_CHAIN.md
@@ -14,17 +14,17 @@ include_toc: true
**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 that verifies the exact final SquashFS payload bytes copied into the decrypted LUKS mapper, 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: after the CISS LUKS/dm-integrity container has been opened, and the live medium context has been exposed, `0030-ciss-verify-checksums` verifies the mounted live-medium checksum manifest, detached signature, and signer fingerprint; later, `0042_ciss_post_decrypt_attest` verifies the signed rootfs attestation manifest, and the exact final SquashFS payload bytes copied into the decrypted LUKS mapper. 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:**
+* **Integrity and authenticity verification:**
- 1. **Early:** Verify `sha512sum.txt` at the ISO edge using `gpgv` and FPR pin.
- 2. **Late:** Verify the external rootfs attestation manifest using `gpgv` and FPR pin, then verify the exact SquashFS payload bytes from the decrypted mapper with `sha512sum -c`.
+ 1. **Mounted live medium:** After `0024-ciss-crypt-squash` has opened the encrypted container and exposed `/run/live/medium`, verify `sha512sum.txt` using `gpgv`, FPR pinning, and checksum execution.
+ 2. **Decrypted rootfs payload:** Verify the external rootfs attestation manifest using `gpgv` and FPR pinning, then verify the exact SquashFS payload bytes from the decrypted mapper with `sha512sum -c`.
-* **Storage-level AEAD (functional):** `dm-crypt` (AES-XTS-512) and `dm-integrity` (HMAC-SHA-512, 4 KiB).
+* **Storage-level confidentiality and keyed sector integrity:** `dm-crypt` (AES-XTS-512) and `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
@@ -49,15 +49,15 @@ private Secure Boot key names are detected in those paths before live-build chec
# 4. Primitives & Parameters
-| 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 |
-| PBKDF | `argon2id`, `--iter-time 1000` ms, `--pbkdf-memory 262144`, `--pbkdf-parallel 1` | Bounded key derivation cost for initramfs unlock |
-| 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 |
-| Dropbear | Modern KEX/AEAD (per `localoptions.h`) | Minimal attack surface, remote unlock |
+| 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 | Keyed per-sector integrity for the opened mapping; not origin authenticity |
+| PBKDF | `argon2id`, `--iter-time 1000` ms, `--pbkdf-memory 262144`, `--pbkdf-parallel 1` | Bounded key derivation cost for initramfs unlock |
+| 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 |
+| Dropbear | Modern KEX/AEAD (per `localoptions.h`) | Minimal attack surface, remote unlock |
# 5. Diagram: CISS Live ISO Boot Flow
```mermaid
@@ -93,11 +93,11 @@ flowchart TD
0100 e10@--> 0110["Executing live-boot, mounting ISO FS"];
0110 e11@--> 0122["Executing 0022-ciss: Hardening tmpfs for OverlayFS upper/work"];
0122 e12@--> 0124["Executing 0024-ciss: LUKS open (dm-crypt & integrity)"];
- 0124 e13@--> |SUCCESSFUL| LUKS["Unlocking LUKS2 Argon2id PBKDF → XTS + HMAC-SHA512"];
- LUKS e14@--> ROOT["Assemble RootFS OverlayFS"];
- ROOT e15@--> 0126["Executing 0026-ciss: Hardening early sysctls"];
- 0126 e16@--> 0130["Executing 0030-ciss: Verification of authenticity and integrity via embedded and pinned GPG of ISO edge"];
- 0130 e17@--> |SUCCESSFUL| 0142["Executing 0042-ciss: Attestation of RootFS SquashFS payload"];
+ 0124 e13@--> |SUCCESSFUL| LUKS["Decrypted mapper exposed; livefs_root=/run/live/medium set"];
+ LUKS e14@--> 0126["Executing 0026-ciss: Hardening early sysctls"];
+ 0126 e15@--> 0130["Executing 0030-ciss: Mounted live-medium checksum and signature verification"];
+ 0130 e16@--> |SUCCESSFUL| ROOT["9990-overlay: Mount SquashFS / OverlayFS"];
+ ROOT e17@--> 0142["Executing 0042-ciss: Attestation of RootFS SquashFS payload"];
0142 e18@--> 0145["init-bottom: stop CISS.hardened dropbear, tear down initramfs net"];
0145 e19@--> 9050["Switching root (run-init / pivot_root)"];
9050 e20@--> 9010["Starting /sbin/init -> systemd"];
@@ -135,22 +135,32 @@ flowchart TD
```
# 6. Diagram: CISS Live ISO LUKS and dm-integrity layering
+
+```text
+ISO medium
+└── /live/ciss_rootfs.crypt
+ └── LUKS2 / dm-crypt / dm-integrity
+ └── /dev/mapper/crypt_liveiso
+ └── SquashFS rootfs [SHA-512 over exact SquashFS byte stream]
+ └── OverlayFS / running root filesystem
+```
+
```mermaid
---
config:
theme: forest
---
flowchart TD
-0{{"Plain device: CD-ROM / USB"}} --> 1["ISO image (ISO9660 + ESP)"];
-1 --> 2["Mount ISO9660 FS → /run/live/medium"];
-2 --> 3["Container file /run/live/medium/live/ciss_rootfs.crypt"];
-3 --> 4["dm-integrity layer (HMAC-SHA-512, 4 KiB)"];
-4 --> 5["dm-crypt LUKS2 (AES-XTS-512) → /dev/mapper/crypt_liveiso"];
-5 --> 6["Mount SquashFS from /dev/mapper/crypt_liveiso → /run/live/rootfs"];
+0{{"Plain device: CD-ROM / USB"}} --> 1["ISO medium (ISO9660 + ESP)"];
+1 --> 2["/live/ciss_rootfs.crypt"];
+2 --> 3["LUKS2 / dm-crypt / dm-integrity"];
+3 --> 4["/dev/mapper/crypt_liveiso"];
+4 --> 5["SquashFS rootfs byte stream"];
+5 --> 6["OverlayFS / running root filesystem"];
```
-**Note:** Encrypt-then-MAC at the block layer (functionally AEAD-equivalent). Any manipulation ⇒ hard I/O error.
+**Note:** `dm-integrity` provides keyed sector integrity for the opened LUKS mapping. It is not treated as origin authenticity; origin authenticity is provided by the signed checksum and rootfs attestation manifests plus pinned signer fingerprints.
# 7. CISS Live ISO LUKS Build-Time Core Steps
```sh
@@ -176,9 +186,9 @@ cryptsetup luksFormat \
**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)
+# 8. Mounted Live-Medium Checksum Verification (CISS modified hook 0030-ciss-verify-checksums, live-bottom)
-**Goal:** Before consuming any medium content, verify:
+**Goal:** After `0024-ciss-crypt-squash` has opened the encrypted container and exposed the live medium context, but before the final live root is accepted, verify:
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.
@@ -196,8 +206,8 @@ cryptsetup luksFormat \
**Goal:** After LUKS unlocked, validate the **decrypted** rootfs payload selected at build time and the **actual** mapping topology.
* **Attested boundary:** the final `binary/live/filesystem.squashfs` byte stream, immediately before it is copied into `/dev/mapper/crypt_liveiso` by `zzzz_ciss_crypt_squash.hook.binary`.
-* **Runtime verification boundary:** the first `rootfs-size-bytes` bytes read from the decrypted mapper. Any LUKS allocation slack after the SquashFS payload is intentionally excluded.
-* **Attestation files:** `/run/live/medium/live/ciss_rootfs.sha512sum.txt[.sig]`
+* **Runtime verification boundary:** the first byte count declared by `# Bytes : Final filesystem.squashfs ` in the signed manifest, read from the decrypted mapper. Any LUKS allocation slack after the SquashFS payload is intentionally excluded.
+* **Attestation files:** `/run/live/medium/live/filesystem.squashfs.sha512sum.txt[.sig]`
* **Key source:** `/etc/ciss/keys/*.gpg` (accepted only if FPR == build-pin)
**Core calls (initramfs):**
@@ -239,14 +249,16 @@ dd if="${CDLB_MAPPER_DEV}" ... | /usr/bin/sha512sum -c /run/ciss-rootfs-attestat
* [9990-main.sh](../config/includes.chroot/usr/lib/live/boot/9990-main.sh),
* [9990-networking.sh](../config/includes.chroot/usr/lib/live/boot/9990-networking.sh),
* [9990-overlay.sh](../config/includes.chroot/usr/lib/live/boot/9990-overlay.sh).
-* **Hooks (boot view):**
- * `/scripts/live-premount/0022-ciss-overlay-tmpfs`,
- * `/scripts/live-premount/0024-ciss-crypt-squash`,
- * `/scripts/live-premount/0026-ciss-early-sysctl`,
- * `/scripts/live-bottom/0030-ciss-verify-checksums`,
- * `/scripts/live-bottom/0042-ciss-post-decrypt-attest`
+* **Hooks (initramfs boot view):**
+ * `/usr/lib/live/boot/0022-ciss-overlay-tmpfs`,
+ * `/usr/lib/live/boot/0024-ciss-crypt-squash`,
+ * `/usr/lib/live/boot/0026-ciss-early-sysctl`,
+ * `/usr/lib/live/boot/0030-ciss-verify-checksums`,
+ * `/usr/lib/live/boot/0042_ciss_post_decrypt_attest`,
+ * `/usr/lib/live/boot/9990-main.sh`,
+ * `/usr/lib/live/boot/9990-overlay.sh`
* **Key files:**
- * ISO edge (for 0030): embedded public key blob (project-specific FPR)
+ * Mounted live medium (for 0030): embedded public key blob (project-specific FPR)
* Root FS (for 0042): `/etc/ciss/keys/.gpg`
* **Mounts (typical):** `/run/live/rootfs`, `/run/live/overlay`
@@ -255,20 +267,21 @@ dd if="${CDLB_MAPPER_DEV}" ... | /usr/bin/sha512sum -c /run/ciss-rootfs-attestat
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"];
+ A["Embed and pin GPG FPR (into ISO & RootFS as needed)"] e00@--> B["Generate mounted-medium sha512sum.txt and .sig"];
B e01@--> C["Build filesystem.squashfs and wrap it into ciss_rootfs.crypt"];
e00@{ animation: fast }
e01@{ animation: fast }
end
subgraph ISO Boot Time
- C 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 SquashFS payload"];
- I e08@-->|SUCCESSFUL| J["RootFS SquashFS payload attestation successful"];
+ C e02@--> D["0024 opens ciss_rootfs.crypt with LUKS2 and dm-integrity"];
+ D e03@-->|SUCCESSFUL| E["Decrypted mapper exposed and livefs_root=/run/live/medium set"];
+ E e04@--> F["0030 verifies mounted live-medium manifest, signature, FPR, and checksums"];
+ F e05@-->|SUCCESSFUL| G["Mounted live medium verified"];
+ G e06@--> H["9990-overlay mounts SquashFS / OverlayFS"];
+ H e07@--> I["0042 verifies signed rootfs attestation manifest and FPR"];
+ I e08@--> J["0042 verifies exact SquashFS bytes from /dev/mapper/crypt_liveiso"];
+ J e09@-->|SUCCESSFUL| K["RootFS SquashFS payload attestation successful"];
e02@{ animation: fast }
e03@{ animation: fast }
e04@{ animation: fast }
@@ -276,22 +289,24 @@ flowchart TD
e06@{ animation: fast }
e07@{ animation: fast }
e08@{ animation: fast }
- end
-
- subgraph ISO Run Time
- J e09@--> K{{"CISS.debian.live.builder ISO running"}};
- X{{"CISS.debian.live.builder Boot process halted"}};
e09@{ animation: fast }
end
+ subgraph ISO Run Time
+ K e10@--> L{{"CISS.debian.live.builder ISO running"}};
+ X{{"CISS.debian.live.builder Boot process halted"}};
+ e10@{ animation: fast }
+ end
+
D -- FAIL --> X;
-G -- FAIL --> X;
+F -- FAIL --> X;
I -- FAIL --> X;
+J -- 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.
+This achieves a portable, self-contained trust chain without a Microsoft-db, providing strong protection at the mounted-medium and decrypted-rootfs-payload boundaries. The dual-verification phases make the state transparent and deterministic without treating `dm-integrity`, LUKS, or private infrastructure as substitutes for origin authenticity.
---
**[no tracking | no logging | no advertising | no profiling | no bullshit](https://coresecret.eu/)**