msw/CISS.debian.live.builder
SHA256
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity
Files
653f702169e2fff2eb7361556db6dbeba197cef844c03008cf3520f1cd7bb6ab
CISS.debian.live.builder/docs/MAN_CISS_ISO_BOOT_CHAIN.md
Marc S. Weidner 653f702169
All checks were successful
🛡️ Shell Script Linting / 🛡️ Shell Script Linting (push) Successful in 1m5s
Details
V8.13.432.2025.11.18 
Signed-off-by: Marc S. Weidner <msw@coresecret.dev>
2025-11-18 15:54:48 +00:00

10 KiB
Raw Blame History

Table of Contents

1. CISS.debian.live.builder

Centurion Intelligence Consulting Agency Information Security Standard
Debian Live Build Generator for hardened live environment and CISS Debian Installer
Master Version: 8.13
Build: V8.13.432.2025.11.18

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.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).

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

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

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)

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):

/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):

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

• 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

flowchart TD
  subgraph ISO Build Time
    direction TD
      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
    direction TD
      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
    direction TD
      J e09@--> K{{"CISS.debian.live.builder ISO running"}};
      X{{"Boot process halted"}};
      e09@{ animation: fast }
  end

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

Reference in New Issue View Git Blame Copy Permalink