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

V9.14.024.2026.06.11
🛡️ Shell Script Linting / 🛡️ Shell Script Linting (push) Has been cancelled
Details

Browse Source 
Signed-off-by: Marc S. Weidner <msw@coresecret.dev>
This commit is contained in:
Marc S. Weidner
2026-06-11 20:39:50 +01:00
parent 5cc2110ecb
commit 666111df0e
2 changed files with 71 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/MAN_CISS_ISO_BOOT_CHAIN.md
+67 -52
View File
@@ -14,17 +14,17 @@ include_toc: true
**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 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.<br>
**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.<br>
# 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 <bytes>` 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/<FPR>.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/)**