msw
666111df0e
🛡️ Shell Script Linting / 🛡️ Shell Script Linting (push) Has been cancelled
Signed-off-by: Marc S. Weidner <msw@coresecret.dev>
314 lines
15 KiB
Markdown
314 lines
15 KiB
Markdown
---
|
||
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**: 9.14<br>
|
||
**Build**: V9.14.024.2026.06.11<br>
|
||
|
||
# 2. CISS.debian.live.builder – Boot & Trust Chain (Technical Documentation)
|
||
|
||
**Status:** 2026-06-10<br>
|
||
**Audience:** CICA CISO, CISS staff, technically proficient administrators<br>
|
||
**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; 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.<br>
|
||
|
||
# 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:** Verify the external rootfs attestation 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:
|
||
|
||
```text
|
||
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 --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. Diagram: CISS Live ISO Boot Flow
|
||
```mermaid
|
||
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["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 }
|
||
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
|
||
|
||
```text
|
||
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
|
||
```
|
||
|
||
```mermaid
|
||
---
|
||
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
|
||
```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 \
|
||
--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).
|
||
|
||
# 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):**
|
||
|
||
```sh
|
||
/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, 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.
|
||
* **Attestation files:** `/run/live/medium/live/filesystem.squashfs.sha512sum.txt[.sig]`
|
||
* **Key source:** `/etc/ciss/keys/*.gpg` (accepted only if FPR == build-pin)
|
||
|
||
**Core calls (initramfs):**
|
||
|
||
```sh
|
||
# 1) Signature and FPR pin (no agent)
|
||
/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 `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
|
||
|
||
```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 44137 (per CISS convention)
|
||
```
|
||
|
||
*Concrete selection compiled via [localoptions.h](../upgrades/dropbear/localoptions.h) at ISO build time.*
|
||
|
||
# 12. Integration Points & Paths
|
||
|
||
* **Hooks (build view):**
|
||
* [0022-ciss-overlay-tmpfs](../config/includes.chroot/usr/lib/live/boot/0022-ciss-overlay-tmpfs),
|
||
* [0024-ciss-crypt-squash](../config/includes.chroot/usr/lib/live/boot/0024-ciss-crypt-squash),
|
||
* [0026-ciss-early-sysctl](../config/includes.chroot/usr/lib/live/boot/0026-ciss-early-sysctl),
|
||
* [0030-ciss-verify-checksums](../config/includes.chroot/usr/lib/live/boot/0030-ciss-verify-checksums),
|
||
* [0042_ciss_post_decrypt_attest](../config/includes.chroot/usr/lib/live/boot/0042_ciss_post_decrypt_attest),
|
||
* [9990-main.sh](../config/includes.chroot/usr/lib/live/boot/9990-main.sh),
|
||
* [9990-networking.sh](../config/includes.chroot/usr/lib/live/boot/9990-networking.sh),
|
||
* [9990-overlay.sh](../config/includes.chroot/usr/lib/live/boot/9990-overlay.sh).
|
||
* **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`
|
||
* **Mounts (typical):** `/run/live/rootfs`, `/run/live/overlay`
|
||
|
||
# 13. Diagram: CISS Live ISO Build, Boot, and Run Time Trust Chain & Verification Paths
|
||
```mermaid
|
||
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 and wrap it into ciss_rootfs.crypt"];
|
||
e00@{ animation: fast }
|
||
e01@{ animation: fast }
|
||
end
|
||
|
||
subgraph ISO Boot Time
|
||
C e02@--> D["0024 opens ciss_rootfs.crypt with LUKS2 and dm-integrity"];
|
||
D e03@-->|SUCCESSFUL| E["Decrypted mapper exposed and livefs_root=/run/live/medium set"];
|
||
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 signed 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 }
|
||
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;
|
||
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](https://coresecret.eu/)**
|
||
<!-- vim: set number et ts=2 sw=2 sts=2 ai tw=128 ft=markdown -->
|