CISS.debian.live.builder/docs/MAN_CISS_ISO_BOOT_CHAIN.md

---
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.544.2025.12.05<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:** CISS hardened and build dropbear, modern primitives only, no passwords, no agent/forwarding.

# 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                         | 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                     |
| Dropbear     | Modern KEX/AEAD (per `localoptions.h`)                    | Minimal attack surface, remote unlock                  |

# 5. Diagram: CISS Live ISO Boot Flow
```mermaid
flowchart TD
  subgraph Trusted HW Manufacturer
    0000["System Power On"] e00@--> 0010["CPU reset 0xFFFFFFF0, POST"];
    0010 e01@--> 0020["UEFI DXE Phase enumerates devices"];
    0020 e02@--> 0030["Secure Boot (if enabled): db, dbx, KEK, PK loaded from NVRAM"];
    e00@{ animation: fast }
    e01@{ animation: fast }
    e02@{ animation: fast }
  end

  subgraph Trusted Secure Boot
    0030 e03@--> |SUCCESSFUL| 0040["Secure Boot: load & verify \\EFI\\BOOT\\BOOTX64.EFI (shim)"];
    0040 e04@--> |SUCCESSFUL| 0050["shim: load & verify \\EFI\\BOOT\\GRUBX64.EFI"];
    0050 e05@--> 0060["GRUB: load vmlinuz + initrd.img, set cmdline"];
    e03@{ animation: fast }
    e04@{ animation: fast }
    e05@{ animation: fast }

  end

  subgraph Trusted Live ISO
    0060 e06@--> 0070["Transfer Control to Kernel Entry Point"];
    0070 e07@--> 0080["Decompress Kernel"];
    0080 e08@--> 0090["/init Phase"];
    0090 e09@--> 0100["Starting CISS.hardened dropbear"];
    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"];
    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"];
    9010 e21@--> 9020["Starting Target Units"];
    0100    -.-> 0145;
    e06@{ animation: fast }
    e07@{ animation: fast }
    e08@{ animation: fast }
    e09@{ animation: fast }
    e10@{ animation: fast }
    e11@{ animation: fast }
    e12@{ animation: fast }
    e13@{ animation: fast }
    e14@{ animation: fast }
    e15@{ animation: fast }
    e16@{ animation: fast }
    e17@{ animation: fast }
    e18@{ animation: fast }
    e19@{ animation: fast }
    e20@{ animation: fast }
    e21@{ animation: fast }
  end

  subgraph Finale State
      9020 e24@--> 9030{{"CISS.debian.live.builder Waiting for Login"}};
      X{{"CISS.debian.live.builder Boot process halted"}};
      e24@{ animation: fast }
  end

0030 -- FAIL --> X;
0040 -- FAIL --> X;
0124 -- FAIL --> X;
0130 -- FAIL --> X;
0142 -- FAIL --> X;
```

# 6. Diagram: CISS Live ISO LUKS and dm-integrity layering
```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"];

```

**Note:** Encrypt-then-MAC at the block layer (functionally AEAD-equivalent). Any manipulation ⇒ hard I/O error.

# 7. CISS Live ISO LUKS Build-Time Core Steps
```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-ciss-verify-checksums, 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 0042_ciss_post_decrypt_attest, called by 9990-overlay.sh)

**Goal:** After LUKS unlock, validate the **decrypted** contents and the **actual** mapping topology.

* **Attestation files:** `/root/.ciss/attestation/<FPR>.sha512sum.txt[.sig]`
* **Key source:** `/etc/ciss/keys/*.gpg` (accepted only if FPR == build-pin)

**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" )
```

# 10. Failure Policy (fail-closed, deterministic)

* **Abort** on: missing `VALIDSIG`, FPR mismatch, missing key / signature.

# 11. CISS hardened and built dropbear

```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 44137 (per CISS convention)
```

*Concrete selection compiled via [localoptions.h](../upgrades/dropbear/localoptions.h) at ISO build time.*

# 12. Integration Points & Paths

* **Hooks (build view):** 
  * [0022-ciss-overlay-tmpfs](../config/includes.chroot/usr/lib/live/boot/0022-ciss-overlay-tmpfs),
  * [0024-ciss-crypt-squash](../config/includes.chroot/usr/lib/live/boot/0024-ciss-crypt-squash),
  * [0026-ciss-early-sysctl](../config/includes.chroot/usr/lib/live/boot/0026-ciss-early-sysctl),
  * [0030-ciss-verify-checksums](../config/includes.chroot/usr/lib/live/boot/0030-ciss-verify-checksums),
  * [0042_ciss_post_decrypt_attest](../config/includes.chroot/usr/lib/live/boot/0042_ciss_post_decrypt_attest),
  * [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`
* **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: CISS Live ISO Build, Boot and Run Time Trust Chain & Verification Paths
```mermaid
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"];
    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"];
    I e08@-->|SUCCESSFUL| J["RootFS attestation successful"];
    e02@{ animation: fast }
    e03@{ animation: fast }
    e04@{ animation: fast }
    e05@{ animation: fast }
    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

D -- FAIL --> X;
G -- FAIL --> X;
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.

---
**[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 -->