msw/CISS.debian.live.builder
SHA256
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity
Files
bb854daa004861843a1c8431926fbe05ffb0329cf0ed72a63996f7aa208d3fca
CISS.debian.live.builder/docs/MAN_CISS_ISO_BOOT_CHAIN.md
Marc S. Weidner bb854daa00
All checks were successful
🛡️ Shell Script Linting / 🛡️ Shell Script Linting (push) Successful in 59s
Details
V8.13.432.2025.11.18 
Signed-off-by: Marc S. Weidner <msw@coresecret.dev>
2025-11-18 16:29:38 +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

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["Loading \EFI\BOOT\BOOTX64.EFI"];
    0040 e04@--> 0050["Loading \EFI\BOOT\GRUBX64.EFI"];
    0050 e05@--> 0060["Loading initrd.img"];
    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    -.-> 9000["Living 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@--> |SUCCESSFUL| 9000["Switching root"];
    9000 e19@--> 9010["Starting /sbin/init -> systemd"];
    9010 e20@--> 9020["Starting Target Units"];
    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 }
  end

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

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

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
    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{{"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