---
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.408.2025.11.13<br>

# 2. CISS.debian.live.builder – Boot & Trust Chain (Technical Documentation)

**Status:** 2025-11-12
**Audience:** CICA CISO, CISS staff, technically proficient administrators
**Summary:** The CISS.debian 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)`.

# 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
participant FW as UEFI/BIOS
participant GRUB as GRUB
participant K as Kernel
participant I as initramfs + live-boot
participant D as Dropbear (optional)
participant C30 as CISS 0030 (early verify)
participant C22 as CISS 0024 (unlock)
participant LUKS as LUKS2 + dm-integrity
participant RS as RootFS (SquashFS/Overlay)
participant C42 as CISS 0042 (late attestation)

FW->>GRUB: Load kernel + initramfs
GRUB->>K: Boot kernel
K->>I: Pivot to initramfs (live-boot phases)
I->>D: (optional) Start Dropbear (remote unlock)

I->>C30: Run 0030: Verify ISO edge (gpgv, FPR pin)
alt 0030 OK
C30-->>I: Verified
else 0030 FAIL
C30-x I: Abort boot
end

I->>C24: Run 0024: LUKS open (dm-crypt + integrity), mount SquashFS
C24->>LUKS: Unlock (Argon2id PBKDF → XTS + HMAC)

I->>RS: Assemble overlay, switch_root
I->>C42: Run 0042: Verify root FS (gpgv, FPR pin) + dmsetup health
alt 0042 OK
C42-->>I: Verified
else 0045 FAIL
C42-x I: Abort boot
end
```

# 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 -->
