msw/CISS.debian.live.builder
SHA256
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity
Files
a8454eeadf4bc0238f772b4e3b1fb843242099ec8ecb417911d9e19b0f2d830d
CISS.debian.live.builder/docs/MAN_CISS_ISO_BOOT_CHAIN.md
T
msw a8454eeadf
🛡️ Retrieve DNSSEC status of coresecret.dev. / 🛡️ Retrieve DNSSEC status of coresecret.dev. (push) Has been cancelled
Details
🛡️ Shell Script Linting / 🛡️ Shell Script Linting (push) Has been cancelled
Details
💙 Generating a PUBLIC Live ISO. / 💙 Generating a PUBLIC Live ISO. (push) Has been cancelled
Details
🔐 Generating a Private Live ISO TRIXIE. / 🔐 Generating a Private Live ISO TRIXIE. (push) Has been cancelled
Details
V9.14.028.2026.06.18 
Signed-off-by: Marc S. Weidner <msw@coresecret.dev>
2026-06-18 10:49:41 +01:00

26 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: 9.14
Build: V9.14.028.2026.06.18

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

Status: 2026-06-18
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: after the CISS LUKS/dm-integrity container has been opened, and the live medium context has been exposed, 0030-ciss-verify-checksums verifies the mounted live-medium checksum manifest, detached signature, and signer fingerprint; 0024-ciss-crypt-squash preserves the rootfs attestation artifacts from the real ISO medium into a stable initramfs runtime cache; later, 0042_ciss_post_decrypt_attest verifies the signed rootfs attestation manifest, and the exact final SquashFS payload bytes copied into the decrypted LUKS mapper. 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 and authenticity verification:

    1. Mounted live medium: After 0024-ciss-crypt-squash has opened the encrypted container and exposed /run/live/medium, verify sha512sum.txt using gpgv, FPR pinning, and checksum execution.
    2. Decrypted rootfs payload: Preserve the external rootfs attestation manifest and detached signature before live-boot may replace or unmount the medium view, verify the cached manifest using gpgv and FPR pinning, then verify the exact SquashFS payload bytes from the decrypted mapper with sha512sum -c.

  • Storage-level confidentiality and keyed sector integrity: 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.

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 Keyed per-sector integrity for the opened mapping; not origin authenticity
PBKDF argon2id, --iter-time 1000 ms, --pbkdf-memory 262144, --pbkdf-parallel 1 Bounded key derivation cost for initramfs unlock
Signatures Ed25519 or RSA-4096 (FPR pinned) Public verifiability, non-repudiation
Verification gpgv --keyring <pinned-keyring> Explicit keyring selection and 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

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: Mount ISO medium and locate /live/ciss_rootfs.crypt"];
    0124 e13@--> CACHE["0024-ciss: Preserve rootfs attestation artifacts in /run/ciss-rootfs-attestation"];
    CACHE e13b@--> LUKSOPEN["0024-ciss: LUKS open (dm-crypt & integrity)"];
    LUKSOPEN e13c@--> |SUCCESSFUL| LUKS["Decrypted mapper exposed; livefs_root=/run/live/medium set"];
    LUKS e14@--> 0126["Executing 0026-ciss: Hardening early sysctls"];
    0126 e15@--> 0130["Executing 0030-ciss: Mounted live-medium checksum and signature verification"];
    0130 e16@--> |SUCCESSFUL| ROOT["9990-overlay: Mount SquashFS / OverlayFS"];
    ROOT e17@--> 0142["Executing 0042-ciss: Attestation of RootFS SquashFS payload"];
    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 }
    e13b@{ animation: fast }
    e13c@{ 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;
CACHE -- FAIL --> X;
LUKSOPEN -- FAIL --> X;
0130 -- FAIL --> X;
0142 -- FAIL --> X;

6. Diagram: CISS Live ISO LUKS and dm-integrity layering

ISO medium
└── /live/ciss_rootfs.crypt
    └── LUKS2 / dm-crypt / dm-integrity
        └── /dev/mapper/crypt_liveiso
            └── SquashFS rootfs [SHA-512 over exact SquashFS byte stream]
                └── OverlayFS / running root filesystem

Rootfs attestation evidence follows a separate side path:

ISO medium
├── /live/filesystem.squashfs.sha512sum.txt
└── /live/filesystem.squashfs.sha512sum.txt.sig
    └── copied by 0024-ciss-crypt-squash to:
        ├── /run/ciss-rootfs-attestation/filesystem.squashfs.sha512sum.txt
        └── /run/ciss-rootfs-attestation/filesystem.squashfs.sha512sum.txt.sig

The /run/ciss-rootfs-attestation/ cache is only a stable initramfs runtime location. It is not a trust anchor. 0042_ciss_post_decrypt_attest still requires the cached manifest to verify against the detached signature, the pinned GPG fingerprint, and the actual decrypted mapper bytes.

---
config:
      theme: forest
---
flowchart TD
0{{"Plain device: CD-ROM / USB"}} --> 1["ISO medium (ISO9660 + ESP)"];
1 --> 2["/live/ciss_rootfs.crypt"];
2 --> 3["LUKS2 / dm-crypt / dm-integrity"];
3 --> 4["/dev/mapper/crypt_liveiso"];
4 --> 5["SquashFS rootfs byte stream"];
5 --> 6["OverlayFS / running root filesystem"];

Note: dm-integrity provides keyed sector integrity for the opened LUKS mapping. It is not treated as origin authenticity; origin authenticity is provided by the signed checksum and rootfs attestation manifests plus pinned signer fingerprints.

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 \
  --pbkdf-memory 262144 \
  --pbkdf-parallel 1 \
  --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).

7.1. Rootfs Attestation Artifacts Created at Build Time

config/hooks/live/zzzz_ciss_crypt_squash.hook.binary runs in the live-build binary phase after binary/live/filesystem.squashfs exists and before the final ISO image is emitted.

The hook expects:

Artifact Build-time path Purpose
Final plaintext SquashFS ${VAR_HANDLER_BUILD_DIR}/binary/live/filesystem.squashfs Source byte stream that will be attested and copied into the encrypted mapper.
Signing key passphrase file ${VAR_SIGNING_KEY_PASSFILE} Unlocks the configured signing key without exposing the passphrase on the command line.
Verification keyring ${VAR_VERIFY_KEYRING} Build-time self-check for the detached signature before the ISO is accepted.

The hook creates:

Artifact Build-time path ISO path
Encrypted live root container ${VAR_HANDLER_BUILD_DIR}/binary/live/ciss_rootfs.crypt /live/ciss_rootfs.crypt
Rootfs attestation manifest ${VAR_HANDLER_BUILD_DIR}/binary/live/filesystem.squashfs.sha512sum.txt /live/filesystem.squashfs.sha512sum.txt
Rootfs attestation detached signature ${VAR_HANDLER_BUILD_DIR}/binary/live/filesystem.squashfs.sha512sum.txt.sig /live/filesystem.squashfs.sha512sum.txt.sig

The manifest format is intentionally small and deterministic:

# CISS.debian.live.builder Master <version>
# Attestation file for filesystem.squashfs Version 1.0.0
# Boundary : Final filesystem.squashfs byte stream copied into /dev/mapper/crypt_liveiso
# Bytes    : Final filesystem.squashfs <exact-byte-count>
<sha512-of-final-filesystem.squashfs>  filesystem.squashfs

The signed boundary is the final SquashFS byte stream before LUKS wrapping. The hook writes that byte stream into /dev/mapper/crypt_liveiso, closes the mapper, shreds the transient LUKS key file, removes binary/live/filesystem.squashfs, and keeps only /live/ciss_rootfs.crypt plus the manifest/signature pair in the final ISO payload tree.

8. Mounted Live-Medium Checksum Verification (CISS modified hook 0030-ciss-verify-checksums, live-bottom)

Goal: After 0024-ciss-crypt-squash has opened the encrypted container and exposed the live medium context, but before the final live root is accepted, 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 --keyring "$KEYFILE" --status-fd 1 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 unlocked, and the live root has been mounted by 9990-overlay.sh, validate the decrypted rootfs payload selected at build time and the actual mapping topology.

  • Attested boundary: the final binary/live/filesystem.squashfs byte stream, immediately before it is copied into /dev/mapper/crypt_liveiso by zzzz_ciss_crypt_squash.hook.binary.
  • Runtime verification boundary: the first byte count declared by # Bytes : Final filesystem.squashfs <bytes> in the signed manifest, read from the decrypted mapper. Any LUKS allocation slack after the SquashFS payload is intentionally excluded.
  • ISO attestation files: /run/live/medium/live/filesystem.squashfs.sha512sum.txt[.sig] while the original ISO medium is mounted by 0024-ciss-crypt-squash.
  • Runtime attestation cache: /run/ciss-rootfs-attestation/filesystem.squashfs.sha512sum.txt[.sig], copied by 0024-ciss-crypt-squash before live-boot may replace or unmount the medium view during toram handling.
  • Key source: /etc/ciss/keys/*.gpg (accepted only if FPR == build-pin)

9.1. Runtime Artifact Custody and Expectations

Step Actor Requires Copies / writes Later consumer
1 0024-ciss-crypt-squash Mounted ISO medium at /run/live/medium; /run/live/medium/live/ciss_rootfs.crypt; /run/live/medium/live/filesystem.squashfs.sha512sum.txt; /run/live/medium/live/filesystem.squashfs.sha512sum.txt.sig Copies the manifest to /run/ciss-rootfs-attestation/filesystem.squashfs.sha512sum.txt and the detached signature to /run/ciss-rootfs-attestation/filesystem.squashfs.sha512sum.txt.sig; sets the cache directory to 0755 before copy, cached files to 0444, and best-effort final directory mode to 0555 0042_ciss_post_decrypt_attest
2 0024-ciss-crypt-squash /run/live/medium/live/ciss_rootfs.crypt; unlock passphrase from console or Dropbear path Opens the encrypted container as /dev/mapper/crypt_liveiso; writes /run/ciss-rootdev with mapper, medium, and attestation-cache paths 9990-overlay.sh
3 9990-main.sh /conf/param.conf with PLAIN_ROOT=1 and livefs_root=/run/live/medium; optional toram boot parameter May copy live media to RAM and may leave /run/live/medium busy, replaced, or otherwise unsuitable as the only attestation source 9990-overlay.sh and 0042_ciss_post_decrypt_attest
4 9990-overlay.sh /run/ciss-rootdev; /dev/mapper/crypt_liveiso Sources /run/ciss-rootdev, overrides the image directory to /dev/mapper/crypt_liveiso, mounts the decrypted SquashFS read-only, and invokes /usr/lib/live/boot/0042_ciss_post_decrypt_attest 0042_ciss_post_decrypt_attest
5 0042_ciss_post_decrypt_attest /etc/ciss/keys/<pinned-FPR>.gpg; /run/ciss-rootfs-attestation/filesystem.squashfs.sha512sum.txt; /run/ciss-rootfs-attestation/filesystem.squashfs.sha512sum.txt.sig; /dev/mapper/crypt_liveiso Creates transient /run/ciss-rootfs-attestation.sha512sum for sha512sum -c; does not create trusted evidence Boot continues only after signature, FPR, and exact payload bytes all verify

0042_ciss_post_decrypt_attest resolves artifacts in this order:

  1. The explicit manifest/signature paths exported through /run/ciss-rootdev.
  2. The default runtime cache under /run/ciss-rootfs-attestation/.
  3. Compatibility fallback mountpoints: ${CDLB_MNT_MEDIUM}, /run/live/medium, /lib/live/mount/medium, and /cdrom.

The fallback mountpoints are diagnostic and compatibility paths. The intended normal path for current CISS ISOs is the runtime cache copied by 0024-ciss-crypt-squash.

Core calls (initramfs):

# 1) Signature and FPR pin (no agent)
DATA="/run/ciss-rootfs-attestation/filesystem.squashfs.sha512sum.txt"
SIG="${DATA}.sig"
KEYFILE="/etc/ciss/keys/<pinned-FPR>.gpg"
/usr/bin/gpgv --keyring "${KEYFILE}" --status-fd 1 "${SIG}" "${DATA}"

# 2) Mandatory content hash verification
dd if="${CDLB_MAPPER_DEV}" ... | /usr/bin/sha512sum -c /run/ciss-rootfs-attestation.sha512sum

10. Failure Policy (fail-closed, deterministic)

  • Abort on: missing checksum manifest, unsupported checksum manifest/tool state, failed checksum, empty checksum manifest, missing rootfs attestation artifacts on the real ISO medium during 0024, failed preservation of the runtime attestation cache, missing cached rootfs manifest/signature during 0042, missing VALIDSIG, FPR mismatch, missing key/signature, malformed rootfs attestation manifest, or rootfs payload hash mismatch.
  • A signed rootfs manifest alone is not sufficient. Boot continues only after the manifest signature/FPR, and the decrypted SquashFS payload bytes both verify successfully.
  • dm-integrity protects the opened LUKS mapping against sector corruption or tampering under the LUKS key, but it is not treated as origin authenticity. Origin authenticity is provided by the signed rootfs attestation manifest and pinned signer fingerprint.

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

  • Hooks (build view):
  • Hooks (initramfs boot 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,
    • /usr/lib/live/boot/9990-main.sh,
    • /usr/lib/live/boot/9990-overlay.sh
  • Key files:
    • Mounted live medium (for 0030): embedded public key blob (project-specific FPR)
    • Root FS (for 0042): /etc/ciss/keys/<FPR>.gpg
  • Rootfs attestation artifacts:
    • ISO payload paths: /live/filesystem.squashfs.sha512sum.txt, /live/filesystem.squashfs.sha512sum.txt.sig
    • Runtime cache paths: /run/ciss-rootfs-attestation/filesystem.squashfs.sha512sum.txt, /run/ciss-rootfs-attestation/filesystem.squashfs.sha512sum.txt.sig
    • Transient checksum file for exact mapper-byte verification: /run/ciss-rootfs-attestation.sha512sum
  • Runtime handoff state: /run/ciss-rootdev
  • Mounts (typical): /run/live/medium, /run/live/rootfs, /run/live/overlay

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 mounted-medium sha512sum.txt and .sig"];
    B e01@--> C["Build filesystem.squashfs"];
    C e01b@--> C2["Generate rootfs attestation manifest and detached signature in binary/live"];
    C2 e01c@--> C3["Copy filesystem.squashfs into ciss_rootfs.crypt and remove plaintext filesystem.squashfs"];
    e00@{ animation: fast }
    e01@{ animation: fast }
    e01b@{ animation: fast }
    e01c@{ animation: fast }
  end

  subgraph ISO Boot Time
    C3 e02@--> D["0024 mounts real ISO medium and expects ciss_rootfs.crypt plus rootfs attestation files under /live"];
    D e02b@--> DCACHE["0024 copies rootfs attestation files to /run/ciss-rootfs-attestation"];
    DCACHE e03@--> E["0024 opens ciss_rootfs.crypt with LUKS2/dm-integrity and exposes /dev/mapper/crypt_liveiso"];
    E e04@--> F["0030 verifies mounted live-medium manifest, signature, FPR, and checksums"];
    F e05@-->|SUCCESSFUL| G["Mounted live medium verified"];
    G e06@--> H["9990-overlay mounts SquashFS / OverlayFS"];
    H e07@--> I["0042 verifies cached rootfs attestation manifest and FPR"];
    I e08@--> J["0042 verifies exact SquashFS bytes from /dev/mapper/crypt_liveiso"];
    J e09@-->|SUCCESSFUL| K["RootFS SquashFS payload attestation successful"];
    e02@{ animation: fast }
    e02b@{ animation: fast }
    e03@{ animation: fast }
    e04@{ animation: fast }
    e05@{ animation: fast }
    e06@{ animation: fast }
    e07@{ animation: fast }
    e08@{ animation: fast }
    e09@{ animation: fast }
  end

  subgraph ISO Run Time
    K e10@--> L{{"CISS.debian.live.builder ISO running"}};
    X{{"CISS.debian.live.builder Boot process halted"}};
    e10@{ animation: fast }
  end

D -- FAIL --> X;
DCACHE -- FAIL --> X;
E -- FAIL --> X;
F -- FAIL --> X;
I -- FAIL --> X;
J -- FAIL --> X;

14. Closing Remarks

This achieves a portable, self-contained trust chain without a Microsoft-db, providing strong protection at the mounted-medium and decrypted-rootfs-payload boundaries. The dual-verification phases make the state transparent and deterministic without treating dm-integrity, LUKS, or private infrastructure as substitutes for origin authenticity.

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

Reference in New Issue View Git Blame Copy Permalink