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
README.md
+2 -2
View File
@@ -46,8 +46,8 @@ Beyond a conventional live system, **CISS.debian.live.builder** assembles a **fu
in a single, deterministic build step: a LUKS2 container backed by `dm-integrity` hosting the SquashFS root filesystem, combined 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 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 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 customised `verify-checksums` path providing fail-closed mounted-medium verification plus runtime attestation of the exact
SquashFS payload bytes selected for the encrypted live root. All components are aligned with the `CISS.debian.installer` 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 baseline, ensuring a unified cryptographic and security posture from first boot to an installed system. For an overview of the
entire build process, see: entire build process, see:
**[MAN_CISS_ISO_BOOT_CHAIN.md](docs/MAN_CISS_ISO_BOOT_CHAIN.md)** **[MAN_CISS_ISO_BOOT_CHAIN.md](docs/MAN_CISS_ISO_BOOT_CHAIN.md)**
docs/MAN_CISS_ISO_BOOT_CHAIN.md
+67 -52
View File
@@ -14,17 +14,17 @@ include_toc: true
**Status:** 2026-06-10<br> **Status:** 2026-06-10<br>
**Audience:** CICA CISO, CISS staff, technically proficient administrators<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 # 3. Overview
* **Trust anchor:** Pinned fingerprint (FPR) of the signing key embedded at build time in initramfs hooks. * **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. 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. **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`. 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. * **Remotely unlock:** CISS hardened and build dropbear, modern primitives only, no passwords, no agent/forwarding.
# 3.1. Secure Boot Profiles # 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 # 4. Primitives & Parameters
| Component | Primitive / Parameter | Purpose | | Component | Primitive / Parameter | Purpose |
|--------------|----------------------------------------------------------------------------------|--------------------------------------------------------| |--------------|----------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| LUKS2 | `aes-xts-plain64`, `--key-size 512`, `--sector-size 4096` | Confidentiality (2×256-bit XTS) | | 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 | 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 | | 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 | | Signatures | Ed25519 or RSA-4096 (FPR pinned) | Public verifiability, non-repudiation |
| Verification | `gpgv --no-default-keyring` | No agent dependency in initramfs | | Verification | `gpgv --no-default-keyring` | No agent dependency in initramfs |
| Hash lists | `sha512sum` format | Deterministic content verification | | Hash lists | `sha512sum` format | Deterministic content verification |
| Dropbear | Modern KEX/AEAD (per `localoptions.h`) | Minimal attack surface, remote unlock | | Dropbear | Modern KEX/AEAD (per `localoptions.h`) | Minimal attack surface, remote unlock |
# 5. Diagram: CISS Live ISO Boot Flow # 5. Diagram: CISS Live ISO Boot Flow
```mermaid ```mermaid
@@ -93,11 +93,11 @@ flowchart TD
0100 e10@--> 0110["Executing live-boot, mounting ISO FS"]; 0100 e10@--> 0110["Executing live-boot, mounting ISO FS"];
0110 e11@--> 0122["Executing 0022-ciss: Hardening tmpfs for OverlayFS upper/work"]; 0110 e11@--> 0122["Executing 0022-ciss: Hardening tmpfs for OverlayFS upper/work"];
0122 e12@--> 0124["Executing 0024-ciss: LUKS open (dm-crypt & integrity)"]; 0122 e12@--> 0124["Executing 0024-ciss: LUKS open (dm-crypt & integrity)"];
0124 e13@--> |SUCCESSFUL| LUKS["Unlocking LUKS2 Argon2id PBKDF → XTS + HMAC-SHA512"]; 0124 e13@--> |SUCCESSFUL| LUKS["Decrypted mapper exposed; livefs_root=/run/live/medium set"];
LUKS e14@--> ROOT["Assemble RootFS OverlayFS"]; LUKS e14@--> 0126["Executing 0026-ciss: Hardening early sysctls"];
ROOT e15@--> 0126["Executing 0026-ciss: Hardening early sysctls"]; 0126 e15@--> 0130["Executing 0030-ciss: Mounted live-medium checksum and signature verification"];
0126 e16@--> 0130["Executing 0030-ciss: Verification of authenticity and integrity via embedded and pinned GPG of ISO edge"]; 0130 e16@--> |SUCCESSFUL| ROOT["9990-overlay: Mount SquashFS / OverlayFS"];
0130 e17@--> |SUCCESSFUL| 0142["Executing 0042-ciss: Attestation of RootFS SquashFS payload"]; ROOT e17@--> 0142["Executing 0042-ciss: Attestation of RootFS SquashFS payload"];
0142 e18@--> 0145["init-bottom: stop CISS.hardened dropbear, tear down initramfs net"]; 0142 e18@--> 0145["init-bottom: stop CISS.hardened dropbear, tear down initramfs net"];
0145 e19@--> 9050["Switching root (run-init / pivot_root)"]; 0145 e19@--> 9050["Switching root (run-init / pivot_root)"];
9050 e20@--> 9010["Starting /sbin/init -> systemd"]; 9050 e20@--> 9010["Starting /sbin/init -> systemd"];
@@ -135,22 +135,32 @@ flowchart TD
``` ```
# 6. Diagram: CISS Live ISO LUKS and dm-integrity layering # 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 ```mermaid
--- ---
config: config:
theme: forest theme: forest
--- ---
flowchart TD flowchart TD
0{{"Plain device: CD-ROM / USB"}} --> 1["ISO image (ISO9660 + ESP)"]; 0{{"Plain device: CD-ROM / USB"}} --> 1["ISO medium (ISO9660 + ESP)"];
1 --> 2["Mount ISO9660 FS → /run/live/medium"]; 1 --> 2["/live/ciss_rootfs.crypt"];
2 --> 3["Container file /run/live/medium/live/ciss_rootfs.crypt"]; 2 --> 3["LUKS2 / dm-crypt / dm-integrity"];
3 --> 4["dm-integrity layer (HMAC-SHA-512, 4 KiB)"]; 3 --> 4["/dev/mapper/crypt_liveiso"];
4 --> 5["dm-crypt LUKS2 (AES-XTS-512) → /dev/mapper/crypt_liveiso"]; 4 --> 5["SquashFS rootfs byte stream"];
5 --> 6["Mount SquashFS from /dev/mapper/crypt_liveiso → /run/live/rootfs"]; 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 # 7. CISS Live ISO LUKS Build-Time Core Steps
```sh ```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). **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. 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. 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. **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`. * **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. * **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/ciss_rootfs.sha512sum.txt[.sig]` * **Attestation files:** `/run/live/medium/live/filesystem.squashfs.sha512sum.txt[.sig]`
* **Key source:** `/etc/ciss/keys/*.gpg` (accepted only if FPR == build-pin) * **Key source:** `/etc/ciss/keys/*.gpg` (accepted only if FPR == build-pin)
**Core calls (initramfs):** **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-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-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). * [9990-overlay.sh](../config/includes.chroot/usr/lib/live/boot/9990-overlay.sh).
* **Hooks (boot view):** * **Hooks (initramfs boot view):**
* `/scripts/live-premount/0022-ciss-overlay-tmpfs`, * `/usr/lib/live/boot/0022-ciss-overlay-tmpfs`,
* `/scripts/live-premount/0024-ciss-crypt-squash`, * `/usr/lib/live/boot/0024-ciss-crypt-squash`,
* `/scripts/live-premount/0026-ciss-early-sysctl`, * `/usr/lib/live/boot/0026-ciss-early-sysctl`,
* `/scripts/live-bottom/0030-ciss-verify-checksums`, * `/usr/lib/live/boot/0030-ciss-verify-checksums`,
* `/scripts/live-bottom/0042-ciss-post-decrypt-attest` * `/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:** * **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` * Root FS (for 0042): `/etc/ciss/keys/<FPR>.gpg`
* **Mounts (typical):** `/run/live/rootfs`, `/run/live/overlay` * **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 flowchart TD
subgraph ISO Build Time 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"]; B e01@--> C["Build filesystem.squashfs and wrap it into ciss_rootfs.crypt"];
e00@{ animation: fast } e00@{ animation: fast }
e01@{ animation: fast } e01@{ animation: fast }
end end
subgraph ISO Boot Time subgraph ISO Boot Time
C e02@--> D["0024 LUKS2, dm-integrity HMAC-SHA512"]; C e02@--> D["0024 opens ciss_rootfs.crypt with LUKS2 and dm-integrity"];
D e03@-->|SUCCESSFUL| E["ciss_rootfs.crypt opened"]; D e03@-->|SUCCESSFUL| E["Decrypted mapper exposed and livefs_root=/run/live/medium set"];
E e04@--> F["Mounting RootFS"]; E e04@--> F["0030 verifies mounted live-medium manifest, signature, FPR, and checksums"];
F e05@--> G["0030 verification of authenticity and integrity via embedded and pinned GPG of ISO edge"]; F e05@-->|SUCCESSFUL| G["Mounted live medium verified"];
G e06@-->|SUCCESSFUL| H["ISO edge verified"]; G e06@--> H["9990-overlay mounts SquashFS / OverlayFS"];
H e07@--> I["0042 post-decrypt-attestation of RootFS SquashFS payload"]; H e07@--> I["0042 verifies signed rootfs attestation manifest and FPR"];
I e08@-->|SUCCESSFUL| J["RootFS SquashFS payload attestation successful"]; 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 } e02@{ animation: fast }
e03@{ animation: fast } e03@{ animation: fast }
e04@{ animation: fast } e04@{ animation: fast }
@@ -276,22 +289,24 @@ flowchart TD
e06@{ animation: fast } e06@{ animation: fast }
e07@{ animation: fast } e07@{ animation: fast }
e08@{ 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 } e09@{ animation: fast }
end 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; D -- FAIL --> X;
G -- FAIL --> X; F -- FAIL --> X;
I -- FAIL --> X; I -- FAIL --> X;
J -- FAIL --> X;
``` ```
# 14. Closing Remarks # 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/)** **[no tracking | no logging | no advertising | no profiling | no bullshit](https://coresecret.eu/)**