msw/CISS.debian.live.builder
SHA256
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity
Files
securityaudit/a01-a02-boot-attestation
CISS.debian.live.builder/docs/MAN_CISS_ISO_BOOT_CHAIN.md
T

15 KiB
Raw Permalink 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: 9.14
Build: V9.14.022.2026.06.10

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

Status: 2026-06-10
Audience: CICA CISO, CISS staff, technically proficient administrators
Summary: The CISS.debian.live.builder Live-ISO establishes a two-stage verification chain around the live root: an ISO-edge checksum-manifest check and a late attestation of the complete selected decrypted rootfs mapper. The late check verifies both the signed SHA-512 manifest and the mapper bytes before boot continues. dm-integrity separately provides sector-integrity protection and is not a substitute for origin-bound signature and checksum attestation. UEFI Secure Boot can use either the default Microsoft/Debian shim chain, or a CISS-signed UKI chain for systems that trust the CISS Secure Boot key material.

3. Overview

  • Trust anchor: Pinned fingerprint (FPR) of the signing key embedded at build time in initramfs hooks.

  • Integrity & authenticity verification:

    1. ISO edge: Verify one supported checksum manifest using gpgv, FPR pinning, and the matching checksum tool.
    2. Late rootfs attestation: Verify the signed mapper manifest and the complete selected decrypted mapper /dev/mapper/crypt_liveiso with sha512sum -c.

  • Storage-level protection: dm-crypt (AES-XTS-512) and, outside runner builds, dm-integrity (HMAC-SHA-512, 4 KiB).

  • Remotely unlock: CISS hardened and build dropbear, modern primitives only, no passwords, no agent/forwarding.

3.1. Secure Boot Profiles

The builder supports two built-time Secure Boot profiles:

  • debian-shim (default): keeps the broadly portable live-build path. The ISO is built as iso-hybrid with BIOS and UEFI bootloaders, and UEFI Secure Boot loads the Microsoft-signed Debian shim before Debian-signed GRUB.
  • ciss-uki: intended for amd64 systems whose firmware trusts the CISS Secure Boot public key through db, or a custom PK/KEK/db model. A late binary hook builds and signs a UKI from the final binary/live/vmlinuz-* and binary/live/initrd.img-* artifacts, then installs it as EFI/BOOT/BOOTX64.EFI inside binary/boot/grub/efi.img and mirrors it into the ISO EFI tree when live-build created one.

The ciss-uki path is:

UEFI firmware -> EFI/BOOT/BOOTX64.EFI (CISS-signed UKI) -> Linux

The private EFI signing key remains outside binary/, chroot/ and config/includes.*; the binary hooks fail if the CISS private Secure Boot key names are detected in those paths before live-build checksum generation.

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 Per-sector integrity inside the LUKS mapping; not origin attestation
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 ISO-edge and decrypted-mapper verification
Dropbear Modern KEX/AEAD (per localoptions.h) Minimal attack surface, remote unlock

5. Diagram: CISS Live ISO 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@--> |debian-shim| 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"];
    0030 e06a@--> |ciss-uki| 0045["Secure Boot: load & verify \EFI\BOOT\BOOTX64.EFI (CISS UKI)"];
    0045 e06b@--> 0060;
    e03@{ animation: fast }
    e04@{ animation: fast }
    e05@{ animation: fast }
    e06a@{ animation: fast }
    e06b@{ 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

---
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: dm-integrity detects sector corruption within its keyed mapping. The signed SHA-512 mapper manifest independently binds the selected decrypted rootfs payload to the signing key. Neither property substitutes for the other.

7. CISS Live ISO LUKS Build-Time Core Steps

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

After filesystem.squashfs is copied to /dev/mapper/crypt_liveiso, the binary hook hashes the complete decrypted mapper, including the mapper padding after the SquashFS image. It writes binary/live/ciss_rootfs.crypt.decrypted.sha512sum.txt, signs that manifest with the existing artifact-signing key, verifies the signature and checksum locally, and only then closes the mapping and removes the plaintext filesystem.squashfs.

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: During live-boot, require one supported ISO-edge checksum manifest to be successfully verified:

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

Verification is fail-closed. Boot panics if no supported manifest is present, no matching checksum tool is available, checksum verification does not succeed, signature verification fails when requested, or verification ends in an unknown state.

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 Payload Attestation (CISS hook 0042_ciss_post_decrypt_attest, called by 9990-overlay.sh)

Goal: After LUKS unlock and rootfs selection, verify the authenticity of the manifest and the content of the actual selected decrypted rootfs payload.

  • Exact attested boundary: the complete /dev/mapper/crypt_liveiso block payload selected by 9990-overlay.sh and mounted read-only as SquashFS, including mapper padding after the SquashFS image.
  • Attestation files: /run/live/medium/live/ciss_rootfs.crypt.decrypted.sha512sum.txt[.sig]
  • Key source: /etc/ciss/keys/<FPR>.gpg in the initramfs; the valid signature FPR must equal the build-time pin.
  • Manifest constraint: exactly one checksum record is accepted, and it must target the selected mapper path.

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) Required selected-payload verification
( cd / && /usr/bin/sha512sum -c --strict --quiet "$DATA" )

The signed manifest alone is not sufficient: boot continues only after the selected decrypted mapper content matches it. This boundary does not individually attest the mounted file tree, OverlayFS upper layer, runtime mutations, or secrets after unlock.

10. Failure Policy (fail-closed, deterministic)

  • ISO-edge abort: no supported manifest, no supported verification tool, failed checksum, failed requested signature, or unknown verification state.
  • Rootfs-attestation abort: missing or malformed manifest/signature/key, missing VALIDSIG, FPR mismatch, manifest target mismatch, unreadable or non-block selected mapper, or mapper checksum mismatch.

11. CISS hardened and built dropbear

• 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 at ISO build time.

12. Integration Points & Paths

13. Diagram: CISS Live ISO Build, Boot, and Run Time 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"];
    C e01a@--> C2["Hash complete decrypted mapper and sign rootfs manifest"];
    e00@{ animation: fast }
    e01@{ animation: fast }
    e01a@{ animation: fast }
  end

  subgraph ISO Boot Time
    C2 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 verifies signed manifest and selected decrypted mapper"];
    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

The verification path is fail-closed and binds the selected decrypted rootfs mapper to the pinned signing key. dm-integrity adds a separate sector-integrity property where enabled. The implemented attestation does not cover runtime OverlayFS changes, post-unlock secrets, or an individually enumerated mounted file tree.

no tracking | no logging | no advertising | no profiling | no bullshit

Reference in New Issue View Git Blame Copy Permalink