Marc S. Weidner
b19c0380e6
All checks were successful
🛡️ Shell Script Linting / 🛡️ Shell Script Linting (push) Successful in 1m18s
Signed-off-by: Marc S. Weidner <msw@coresecret.dev>
247 lines
9.6 KiB
Markdown
247 lines
9.6 KiB
Markdown
---
|
||
gitea: none
|
||
include_toc: true
|
||
---
|
||
|
||
# 1. CISS.debian.live.builder
|
||
|
||
**Centurion Intelligence Consulting Agency Information Security Standard**<br>
|
||
*Debian Live Build Generator for hardened live environment and CISS Debian Installer*<br>
|
||
**Master Version**: 8.13<br>
|
||
**Build**: V8.13.432.2025.11.18<br>
|
||
|
||
# 2. CISS.debian.live.builder – Boot & Trust Chain (Technical Documentation)
|
||
|
||
**Status:** 2025-11-12<br>
|
||
**Audience:** CICA CISO, CISS staff, technically proficient administrators<br>
|
||
**Summary:** The CISS.debian.live.builder Live-ISO establishes a two-stage verification chain without Microsoft-db: 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)`.<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.
|
||
* **Storage-level AEAD (functional):** `dm-crypt` (AES-XTS-512) and `dm-integrity` (HMAC-SHA-512, 4 KiB).
|
||
* **Remotely unlock:** Hardened Dropbear (modern primitives only), no passwords, no agent/forwarding.
|
||
|
||
# 4. Primitives & Parameters (concise)
|
||
|
||
| 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 | Key derivation, hardware-agnostic |
|
||
| Signatures | Ed25519, 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. End-to-End Boot Flow
|
||
```mermaid
|
||
sequenceDiagram
|
||
autonumber
|
||
|
||
box lightgrey Trusted Manufacturer
|
||
participant 0000 as Power On
|
||
participant 0010 as POST
|
||
participant 0020 as UEFI Initialisation
|
||
end
|
||
|
||
box lightblue Trusted Secure Boot
|
||
participant 0030 as Secure Boot Initialisation
|
||
participant 0040 as bootx64.efi
|
||
participant 0050 as grubx64.efi
|
||
end
|
||
|
||
box lightgreen Trusted CISS.debian.live.builder
|
||
participant 0060 as initrd.img
|
||
participant 0070 as Kernel Entry Point
|
||
participant 0080 as Kernel Decompress
|
||
participant 0090 as /init
|
||
participant 0100 as Dropbear Remote Unlock
|
||
participant 0110 as live-boot mounts ISO FS
|
||
participant 0122 as 0022-ciss
|
||
participant 0124 as 0024-ciss
|
||
participant LUKS as LUKS2 & dm-integrity
|
||
participant ROOT as RootFS (SquashFS/Overlay)
|
||
participant 0126 as 0026-ciss
|
||
participant 0130 as 0030-ciss
|
||
participant 0142 as 0042-ciss
|
||
participant 9000 as switch_root
|
||
participant 9010 as /sbin/init
|
||
participant 9020 as Target Units
|
||
participant 9030 as Login
|
||
end
|
||
|
||
0000->>0010: CPU reset 0xFFFFFFF0, POST
|
||
0010->>0020: UEFI DXE Phase enumerates devices
|
||
0020->>0030: Secure Boot (if enabled): db, dbx, KEK, PK loaded from NVRAM
|
||
0030->>0040: Loading \EFI\BOOT\BOOTX64.EFI
|
||
0040->>0050: Loading \EFI\BOOT\GRUBX64.EFI
|
||
0050->>0060: Loading initrd.img
|
||
0060->>0070: Transfer Control to Kernel Entry Point
|
||
0070->>0080: Decompress Kernel
|
||
0080->>0090: /init Phase
|
||
0090->>0100: Starting CISS.hardened dropbear
|
||
0100->>9000: Living CISS.hardened dropbear
|
||
0100->>0110: Executing live-boot, mounting ISO FS
|
||
0110->>0122: Executing 0022-ciss: Hardening tmpfs for OverlayFS upper/work
|
||
0122->>0124: Executing 0024-ciss: LUKS open (dm-crypt & integrity)
|
||
0124->>LUKS: Unlocking [Argon2id PBKDF → XTS + HMAC-SHA512]
|
||
LUKS->>ROOT: Assemble RootFS OverlayFS
|
||
ROOT->>0126: Executing 0026-ciss: Hardening early sysctls
|
||
|
||
0126->>0130: Executing 0030-ciss: Verify ISO edge (gpgv, FPR pin)
|
||
alt 0130 SUCCESSFUL
|
||
0130->>0060: Verified authenticity and integrity of ISO edge
|
||
else 0130 FAIL
|
||
0130-x 0060: CISS boot process stopped
|
||
end
|
||
|
||
0130->>0142: Executing 0042-ciss: RootFS attestation, dmsetup health checking
|
||
alt 0142 SUCCESSFUL
|
||
0142->>0060: Verified confidentiality, authenticity and integrity of opened LUKS2 RootFS
|
||
else 0142 FAIL
|
||
0142-x 0060: CISS boot process stopped
|
||
end
|
||
|
||
0142->>9000: Switching root
|
||
9000->>9010: Starting /sbin/init -> systemd
|
||
9010->>9020: Starting Target Units
|
||
9020->>9030: Waiting for Login
|
||
```
|
||
|
||
# 6. LUKS/dm-integrity Layering
|
||
```mermaid
|
||
flowchart TD
|
||
|
||
|
||
A["Plain device (/live/rootfs.crypt)"] --> B["dm-integrity (HMAC-SHA-512, 4 KiB)"];
|
||
B --> C["dm-crypt (AES-XTS-512)"];
|
||
C --> D["/dev/mapper/crypt_liveiso"];
|
||
D --> E["SquashFS mount /run/live/rootfs"];
|
||
```
|
||
|
||
**Note:** Encrypt-then-MAC at the block layer (functionally AEAD-equivalent). Any manipulation ⇒ hard I/O error.
|
||
|
||
# 7. Build-Time Core Step (LUKS)
|
||
```sh
|
||
cryptsetup luksFormat \
|
||
--batch-mode \
|
||
--cipher aes-xts-plain64 \
|
||
--integrity hmac-sha512 \
|
||
--iter-time 1000 \
|
||
--key-file "/proc/$$/fd/${KEYFD}" \
|
||
--key-size 512 \
|
||
--label crypt_liveiso \
|
||
--luks2-keyslots-size 16777216 \
|
||
--luks2-metadata-size 4194304 \
|
||
--pbkdf argon2id \
|
||
--sector-size 4096 \
|
||
--type luks2 \
|
||
--use-random \
|
||
--verbose \
|
||
"${LUKSFS}"
|
||
```
|
||
|
||
**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, live-bottom)
|
||
|
||
**Goal:** Before consuming any medium content, 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.
|
||
3. **Optional:** *Script self-IA* – hash the executed hook and compare against the signed list (drift/bitrot detector).
|
||
|
||
**Core call (initramfs):**
|
||
|
||
```sh
|
||
/usr/bin/gpgv --no-default-keyring --keyring "$KEYFILE" --status-fd 1 --verify sha512sum.txt.sig sha512sum.txt
|
||
# parse [GNUPG:] VALIDSIG ... <FPR> ...
|
||
```
|
||
|
||
# 9. Late Root-FS Attestation and dmsetup Health (CISS hook 0045, live-bottom)
|
||
|
||
**Goal:** After LUKS unlock, validate the **decrypted** contents and the **actual** mapping topology.
|
||
|
||
* **Attestation files:** `/.ciss/attest/rootfs.sha512[.sig]`
|
||
* **Key source:** `/etc/ciss/keys/*.gpg` (accepted only if FPR == build-pin)
|
||
* **Health check:** `dmsetup table --showkeys` → top `crypt` (AES-XTS), child `integrity` (HMAC-SHA-512, 4096 B)
|
||
|
||
**Core calls (initramfs):**
|
||
|
||
```sh
|
||
# 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" )
|
||
|
||
# 3) dmsetup health
|
||
dmsetup table --showkeys /dev/mapper/crypt_liveiso
|
||
dmsetup table --showkeys CHILD # expect integrity hmac sha512 4096
|
||
```
|
||
|
||
# 10. Failure Policy (fail-closed, deterministic)
|
||
|
||
* **Abort** on: missing `VALIDSIG`, FPR mismatch, missing key/signature, or a deviating `dmsetup` topology.
|
||
|
||
# 11. Dropbear (Hardened Remotely Unlock)
|
||
|
||
```text
|
||
• Public-key auth only, no passwords
|
||
• Modern KEX/AEAD (e.g., curve25519, sntrup761x25519-sha512, mlkem768x25519-sha256; AES-GCM)
|
||
• No agent/X11/TCP forwarding, no SFTP
|
||
• Strict timeouts/keep-alives, restricted cipher/KEX set
|
||
• Port 42137 (per CISS convention)
|
||
```
|
||
|
||
*Concrete selection compiled via your `localoptions.h` at ISO build time.*
|
||
|
||
# 12. Integration Points & Paths
|
||
|
||
* **Hooks (build 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`,
|
||
* **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`
|
||
* **Key files:**
|
||
* ISO edge (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`
|
||
|
||
# 13. Diagram: Trust Chain & Verification Paths
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
|
||
|
||
A["Build time: pin EXP_FPR + embed ISO key"] --> B["ISO artifacts: sha512sum.txt + .sig"];
|
||
B --> C["Boot early (0030): gpgv verify + FPR pin"];
|
||
C -->|OK| D["LUKS open (0024)"];
|
||
D --> E["Mount RootFS"];
|
||
E --> F["Boot late (0042): gpgv verify + FPR pin (root key)"];
|
||
F --> G["dmsetup health: crypt(XTS) over integrity(HMAC-SHA-512)"];
|
||
C -- FAIL --> X["Abort"];
|
||
F -- FAIL --> X;
|
||
G -- FAIL --> X;
|
||
```
|
||
|
||
# 14. Closing Remark
|
||
|
||
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 plus `dmsetup` health make the state transparent and deterministic.
|
||
|
||
---
|
||
**[no tracking | no logging | no advertising | no profiling | no bullshit](https://coresecret.eu/)**
|
||
<!-- vim: set number et ts=2 sw=2 sts=2 ai tw=128 ft=markdown -->
|