From 7e0b9f35f12949db41d0d3c142f54c87ee330162 Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Sat, 26 Sep 2026 12:20:10 -0500 Subject: [PATCH 1/4] feat(installer): opt-in network credentials pull for PXE installs Extend the installer wrapper (bluefin-sysinstall) with two inst.* kernel cmdline parameters, mirroring inst.ddi_url in style and failure semantics, so PXE/netboot clients can receive per-host first-boot systemd credentials without any per-host installer media: - inst.creds_url= fetches a tar archive of systemd-creds encrypted *.cred files via curl, after the shared systemd-networkd-wait-online bring-up. - inst.creds_sha256= is mandatory when inst.creds_url is set; the archive is verified before the target disk is touched (fail closed). Nothing unverified is used. The download is capped at 16 MiB (curl --max-filesize, re-checked with stat once the checksum has passed). The archive must be an uncompressed ustar/pax/gnu tar: the wrapper checks the ustar magic at offset 257 and hands the file to tar on stdin, where GNU tar refuses compressed input instead of transparently decompressing a .tar.zst into an unbounded listing. It must be flat: at most 64 top-level regular files named .cred with matching [A-Za-z0-9][A-Za-z0-9._@~-]* (~ is systemd's own systemd.unit-dropin.~ namespace), each name at most 250 bytes (vfat and systemd filename limits), each file at most 1 MiB, and no name may repeat, even ignoring case, because the ESP is vfat. The `tar -tv` listing is validated column by column before anything is extracted (regular-file type only: no directories, symlinks, hardlinks, devices or FIFOs; numeric size within the cap; date/time columns where tar puts them; strict name pattern, which also rejects the backslash sequences tar's escape quoting produces for control characters such as a smuggled newline), then cross-checked against the plain `tar -t` listing. Only the validated names are extracted, with --no-same-owner --no-same-permissions, pinned to 0644 and re-checked as regular files. Any violation rejects the whole archive with a wrapper-level message. Verification, validation and unpacking into tmpfs all run before systemd-sysinstall, alongside the DDI fetch, so a bad download aborts with the target untouched. After systemd-sysinstall has created the target, the existing post-install ESP pass (previously stage_fallback_bootloader, now finalize_target_esp) copies each validated name -- never a glob over the extraction directory -- to /loader/credentials/ on the same single vfat mount used to stage the UEFI fallback loader, so systemd-stub hands them to the installed OS on first boot. The credentials go first, so the best-effort loader copy cannot abort the function with the mandatory step undone. The ESP is now identified by its GPT partition type (c12a7328-f81f-11d2-ba4b-00a0c93ec93b) on the target disk rather than by the first vfat filesystem. When inst.creds_url is set and the ESP cannot be found or mounted, the install fails rather than leaving the host to boot unconfigured. Without inst.creds_url the flow is behaviourally unchanged apart from that ESP lookup by GPT type, which the offline path shares. Add tar to installer-stack.bst (nothing in the stack shipped one) and tar, dd, rm, chmod and sync to the build-time tool check. Assisted-by: Claude Fable 5.1 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- elements/installer/installer-stack.bst | 3 + elements/oci/bluefin-server-installer.bst | 248 ++++++++++++++++++---- 2 files changed, 210 insertions(+), 41 deletions(-) diff --git a/elements/installer/installer-stack.bst b/elements/installer/installer-stack.bst index 7aa27e1c..f897e163 100644 --- a/elements/installer/installer-stack.bst +++ b/elements/installer/installer-stack.bst @@ -38,6 +38,9 @@ depends: # zstd-compressed DDI over the LAN, per inst.ddi_url in the wrapper). - freedesktop-sdk.bst:components/curl.bst - freedesktop-sdk.bst:components/zstd.bst + # tar unpacks the inst.creds_url first-boot credentials archive; nothing else + # in this stack (uutils, util-linux, systemd) ships a tar. + - freedesktop-sdk.bst:components/tar.bst # Kernel (installer boots from this; vmlinuz used as the UKI --linux= arg) - flatcar/flatcar-kernel.bst diff --git a/elements/oci/bluefin-server-installer.bst b/elements/oci/bluefin-server-installer.bst index eabbd31f..de495fa2 100644 --- a/elements/oci/bluefin-server-installer.bst +++ b/elements/oci/bluefin-server-installer.bst @@ -74,7 +74,7 @@ config: # here rather than discovered at install time (exit 127 after download). for tool in udevadm lsblk systemd-repart bootctl systemd-sysinstall systemctl \ grep curl zstd modprobe mount umount sha256sum readlink ls cp mkdir sleep \ - mountpoint stat df tail; do + mountpoint stat df tail tar dd rm chmod sync; do if ! [ -x "/layer/usr/bin/${tool}" ] && ! [ -x "/layer/usr/sbin/${tool}" ]; then echo "ERROR: Critical tool '${tool}' is missing from the staged rootfs at /layer!" >&2 exit 1 @@ -231,46 +231,56 @@ config: # Parse the kernel command line for PXE/netboot parameters. The inst.* # namespace follows the Anaconda convention PXE operators already guess. - # Without inst.ddi_url the embedded installer-media path is unchanged. + # Without inst.ddi_url / inst.creds_url the embedded installer-media path + # is unchanged. CMDLINE="$(< /proc/cmdline)" DDI_URL="" DDI_SHA256="" + CREDS_URL="" + CREDS_SHA256="" TARGET_DISK_OVERRIDE="" for arg in ${CMDLINE}; do case "${arg}" in inst.ddi_url=*) DDI_URL="${arg#inst.ddi_url=}" ;; inst.ddi_sha256=*) DDI_SHA256="${arg#inst.ddi_sha256=}" ;; + inst.creds_url=*) CREDS_URL="${arg#inst.creds_url=}" ;; + inst.creds_sha256=*) CREDS_SHA256="${arg#inst.creds_sha256=}" ;; inst.target_disk=*) TARGET_DISK_OVERRIDE="${arg#inst.target_disk=}" ;; esac done - # Opt-in network DDI pull (PXE/netboot). Absence of inst.ddi_url leaves - # the embedded installer-media path byte-for-byte unchanged (offline-first - # preserved). Any fetch/verification failure aborts here, before the target - # disk is touched. - if [ -n "${DDI_URL}" ]; then - # Verification is mandatory for network installs: fail closed when no - # checksum is supplied, so no unsigned/unchecked install can proceed. - if [ -z "${DDI_SHA256}" ]; then - echo "ERROR: inst.ddi_url is set but inst.ddi_sha256 is missing; verification is mandatory for network installs." >&2 - exit 1 - fi + # Opt-in network pulls (PXE/netboot): the OS DDI (inst.ddi_url) and a tar + # archive of first-boot systemd credentials (inst.creds_url). Absence of + # both leaves the embedded installer-media path behaviourally unchanged + # (offline-first preserved; the one shared change is that the ESP is + # located by GPT partition type in finalize_target_esp). Verification is mandatory for network + # installs: fail closed when a checksum is not supplied, so no + # unsigned/unchecked install can proceed, and any fetch/verification + # failure aborts here, before the target disk is touched. + if [ -n "${DDI_URL}" ] && [ -z "${DDI_SHA256}" ]; then + echo "ERROR: inst.ddi_url is set but inst.ddi_sha256 is missing; verification is mandatory for network installs." >&2 + exit 1 + fi + if [ -n "${CREDS_URL}" ] && [ -z "${CREDS_SHA256}" ]; then + echo "ERROR: inst.creds_url is set but inst.creds_sha256 is missing; verification is mandatory for network installs." >&2 + exit 1 + fi + if [ -n "${DDI_URL}" ] || [ -n "${CREDS_URL}" ]; then # Stage under /dev/shm, not /run: systemd PID 1 mounts /run as tmpfs # capped at 20% of RAM, which cannot hold the decompressed DDI on an # 8 GiB machine, while /dev/shm is a tmpfs at the kernel default of # 50% of RAM. PID 1 mounts it as an API filesystem before any unit # runs; refuse to stage on devtmpfs should that ever not be the case. mountpoint -q /dev/shm || { - echo "ERROR: /dev/shm is not a mounted tmpfs; cannot stage the network DDI." >&2 + echo "ERROR: /dev/shm is not a mounted tmpfs; cannot stage network downloads." >&2 exit 1 } mkdir -p /dev/shm/installer - echo "==> Fetching DDI from ${DDI_URL}..." # The binary lives in /usr/lib/systemd, not on PATH: a `command -v` # guard silently skipped the wait and curl raced the DHCP lease. It is # called from here, not via systemd-networkd-wait-online.service, so - # the wait stays conditional on inst.ddi_url (offline USB installs - # must not wait) and a failure aborts the install. + # the wait stays conditional on inst.ddi_url / inst.creds_url (offline + # USB installs must not wait) and a failure aborts the install. # --any: the installer's 80-dhcp.network matches every en*/eth* # interface, and without --any an unplugged NIC (no-carrier, setup # state "configuring") would hold the wait until the timeout. @@ -282,6 +292,10 @@ config: echo "ERROR: systemd-networkd-wait-online failed: no interface got an IPv4 address within 90 s (or wait-online itself failed, see above)." >&2 exit 1 } + fi + + if [ -n "${DDI_URL}" ]; then + echo "==> Fetching DDI from ${DDI_URL}..." curl --fail --silent --show-error --location --retry 3 \ --output /dev/shm/installer/bluefin-server-ddi.raw.zst "${DDI_URL}" printf '%s %s\n' "${DDI_SHA256}" /dev/shm/installer/bluefin-server-ddi.raw.zst \ @@ -374,6 +388,131 @@ config: fi fi + # Opt-in first-boot credentials pull. The archive is fetched, verified and + # unpacked into tmpfs now, before any disk change; the files reach the + # target ESP only after systemd-sysinstall has created it (see + # finalize_target_esp below), where systemd-stub hands /loader/credentials/ + # to the installed OS on first boot. + CREDS_DIR="" + CREDS_NAMES=() + if [ -n "${CREDS_URL}" ]; then + echo "==> Fetching first-boot credentials from ${CREDS_URL}..." + # A handful of encrypted credentials is a few KiB; 16 MiB bounds what + # the URL can make the installer pull into tmpfs. curl >= 8.4 aborts + # a transfer of unknown length once it crosses --max-filesize (exit + # 63); the stat re-check below keeps the bound independent of the + # curl version. + curl --fail --silent --show-error --location --retry 3 \ + --max-filesize 16777216 \ + --output /dev/shm/installer/credentials.tar "${CREDS_URL}" + printf '%s %s\n' "${CREDS_SHA256}" /dev/shm/installer/credentials.tar \ + | sha256sum --check --status || { + echo "ERROR: downloaded credentials SHA256 verification failed." >&2 + exit 1 + } + CREDS_TAR_BYTES="$(stat -c %s /dev/shm/installer/credentials.tar)" + if [ "${CREDS_TAR_BYTES}" -gt 16777216 ]; then + echo "ERROR: credentials archive is ${CREDS_TAR_BYTES} bytes, above the 16 MiB limit; refusing the archive." >&2 + exit 1 + fi + # Only an uncompressed, flat archive of at most 64 top-level regular + # files named .cred, each at most 1 MiB, is accepted + # (systemd-creds encrypted; on this image systemd-stub stages ESP + # credentials under /run/credentials/@encrypted, so plaintext files + # are rejected by the consuming services). GNU tar transparently + # decompresses a compressed file named on -f, which would let a + # 16 MiB download expand into gigabytes of listing; require the + # ustar magic at offset 257 (ustar, pax and gnu formats all carry + # it) and hand the archive to tar on stdin, where it refuses + # compressed input instead of decompressing it. The verbose listing + # is then validated column by column before anything is extracted: + # the type must be a regular file (no directories, symlinks, + # hardlinks, devices or FIFOs), the size must be numeric and within + # the cap, the date and time columns must be where tar puts them, + # and the name must match [A-Za-z0-9][A-Za-z0-9._@~-]*.cred (~ is + # systemd's own drop-in namespace, systemd.unit-dropin.~) + # -- no path separators, spaces, leading dashes or dots -- and be at + # most 250 bytes so it fits vfat and systemd's filename limits. tar's + # escape quoting turns a newline or any other control character + # inside a member name into a backslash sequence, which that pattern + # rejects. Names that repeat, or differ only by case (the ESP is + # vfat, where a.cred and A.cred are the same file), reject the + # archive too. Anything else rejects the whole archive, so nothing + # unexpected can reach the ESP. + if [ "$(dd if=/dev/shm/installer/credentials.tar bs=1 skip=257 count=5 2>/dev/null)" != "ustar" ]; then + echo "ERROR: downloaded credentials file is not an uncompressed ustar/pax tar archive; refusing the archive." >&2 + exit 1 + fi + CREDS_LIST="$(LC_ALL=C tar --quoting-style=escape -tvf - < /dev/shm/installer/credentials.tar)" || { + echo "ERROR: downloaded credentials file is not a readable tar archive." >&2 + exit 1 + } + CREDS_PLAIN_LIST="$(LC_ALL=C tar --quoting-style=escape -tf - < /dev/shm/installer/credentials.tar)" || { + echo "ERROR: downloaded credentials file is not a readable tar archive." >&2 + exit 1 + } + [ -n "${CREDS_LIST}" ] || { + echo "ERROR: downloaded credentials archive contains no files." >&2 + exit 1 + } + CREDS_MODE_RE='^-[-rwxsStT]{9}$' + CREDS_NAME_RE='^[A-Za-z0-9][A-Za-z0-9._@~-]*\.cred$' + CREDS_DATE_RE='^[0-9]{4}-[0-9]{2}-[0-9]{2}$' + CREDS_TIME_RE='^[0-9]{2}:[0-9]{2}$' + CREDS_COUNT=0 + declare -A CREDS_SEEN=() + while read -r mode _ size date time name; do + CREDS_COUNT=$(( CREDS_COUNT + 1 )) + if [ "${CREDS_COUNT}" -gt 64 ]; then + echo "ERROR: credentials archive has more than 64 members; refusing the archive." >&2 + exit 1 + fi + if ! [[ "${mode}" =~ ${CREDS_MODE_RE} ]] || ! [[ "${size}" =~ ^[0-9]+$ ]] \ + || ! [[ "${date}" =~ ${CREDS_DATE_RE} ]] || ! [[ "${time}" =~ ${CREDS_TIME_RE} ]] \ + || ! [[ "${name}" =~ ${CREDS_NAME_RE} ]]; then + echo "ERROR: credentials archive member '${name}' is not a top-level regular *.cred file; refusing the archive." >&2 + exit 1 + fi + if [ "${#name}" -gt 250 ]; then + echo "ERROR: credentials archive member '${name}' has a ${#name}-byte name, above the 250-byte limit; refusing the archive." >&2 + exit 1 + fi + if [ "${size}" -gt 1048576 ]; then + echo "ERROR: credentials archive member '${name}' is ${size} bytes, above the 1 MiB limit; refusing the archive." >&2 + exit 1 + fi + if [ -n "${CREDS_SEEN[${name,,}]+set}" ]; then + echo "ERROR: credentials archive member '${name}' repeats '${CREDS_SEEN[${name,,}]}' (names are case-insensitive on the ESP); refusing the archive." >&2 + exit 1 + fi + CREDS_SEEN[${name,,}]="${name}" + CREDS_NAMES+=("${name}") + done <<< "${CREDS_LIST}" + # The plain listing must name exactly the members the verbose one was + # parsed into; a disagreement means the columns were not where the + # parser assumed and nothing is trusted. + if [ "$(printf '%s\n' "${CREDS_NAMES[@]}")" != "${CREDS_PLAIN_LIST}" ]; then + echo "ERROR: credentials archive listing is inconsistent; refusing the archive." >&2 + exit 1 + fi + CREDS_DIR=/dev/shm/installer/credentials + mkdir -p "${CREDS_DIR}" + # Extract only the validated names, as this user with the umask, then + # pin our own copies to 0644 and re-check that each is a regular file. + tar --no-same-owner --no-same-permissions -C "${CREDS_DIR}" \ + -xf - -- "${CREDS_NAMES[@]}" < /dev/shm/installer/credentials.tar + rm -f /dev/shm/installer/credentials.tar + for name in "${CREDS_NAMES[@]}"; do + if [ -L "${CREDS_DIR}/${name}" ] || ! [ -f "${CREDS_DIR}/${name}" ]; then + echo "ERROR: credentials archive member '${name}' did not extract as a regular file; refusing the archive." >&2 + exit 1 + fi + chmod 0644 -- "${CREDS_DIR}/${name}" + done + echo "==> Verified first-boot credentials:" + ls -l "${CREDS_DIR}" + fi + INSTALLER_PART="" # Hard preflight: the embedded installer-media path needs the # bluefin-installer-data partition. Under PXE (inst.ddi_url=) there is no @@ -429,7 +568,12 @@ config: TARGET_DISK="${TARGET_DISK_OVERRIDE}" fi - stage_fallback_bootloader() { + # Post-install pass over the target ESP, mounted once: stage the UEFI + # removable-media fallback loader (best-effort) and, when inst.creds_url + # was given, place the verified credentials under /loader/credentials/ + # (mandatory: a host that cannot receive its credentials must not be left + # to boot unconfigured, so a missing or unmountable ESP fails the install). + finalize_target_esp() { udevadm settle --timeout=10 || true local target="${TARGET_DISK:-}" if [ -z "${target}" ]; then @@ -440,35 +584,57 @@ config: fi fi + local esp_dev="" if [ -n "${target}" ]; then - local esp_dev="" - while read -r dev fstype; do - if [ "${fstype}" = "vfat" ]; then + # Identify the ESP by its GPT partition type (never by device path or + # filesystem alone, which any vfat data partition would also match). + while read -r dev parttype; do + if [ "${parttype,,}" = "c12a7328-f81f-11d2-ba4b-00a0c93ec93b" ]; then esp_dev="${dev}" break fi - done < <(lsblk -p -n -l -o NAME,FSTYPE "${target}") - - if [ -n "${esp_dev}" ] && [ -b "${esp_dev}" ]; then - echo "==> Staging UEFI removable media fallback /EFI/BOOT/BOOTX64.EFI on ${esp_dev}..." - mkdir -p /mnt/esp - if mount -t vfat "${esp_dev}" /mnt/esp; then - mkdir -p /mnt/esp/EFI/BOOT - for candidate in \ - /mnt/esp/EFI/systemd/systemd-bootx64.efi \ - /mnt/esp/flatcar/bluefin-server.efi \ - /mnt/esp/EFI/Linux/bluefin-server.efi \ - /usr/lib/bluefin-server/bluefin-server.efi; do - if [ -f "${candidate}" ]; then - cp -a "${candidate}" /mnt/esp/EFI/BOOT/BOOTX64.EFI - echo "==> Successfully staged ${candidate} -> ${esp_dev}:/EFI/BOOT/BOOTX64.EFI" - break - fi + done < <(lsblk -p -n -l -o NAME,PARTTYPE "${target}") + fi + + local esp_mounted=0 + if [ -n "${esp_dev}" ] && [ -b "${esp_dev}" ]; then + echo "==> Staging UEFI removable media fallback /EFI/BOOT/BOOTX64.EFI on ${esp_dev}..." + mkdir -p /mnt/esp + if mount -t vfat "${esp_dev}" /mnt/esp; then + esp_mounted=1 + if [ -n "${CREDS_DIR}" ]; then + # The mandatory step first, so the best-effort loader copy below + # cannot abort this function before the credentials are on disk. + # Plain cp (no mode/owner preservation) — vfat has neither — of + # each validated name; never a glob over the extraction dir. + echo "==> Placing first-boot credentials in ${esp_dev}:/loader/credentials/..." + mkdir -p /mnt/esp/loader/credentials + for name in "${CREDS_NAMES[@]}"; do + cp -- "${CREDS_DIR}/${name}" /mnt/esp/loader/credentials/ done - umount /mnt/esp || true + ls -l /mnt/esp/loader/credentials + sync fi + mkdir -p /mnt/esp/EFI/BOOT + for candidate in \ + /mnt/esp/EFI/systemd/systemd-bootx64.efi \ + /mnt/esp/flatcar/bluefin-server.efi \ + /mnt/esp/EFI/Linux/bluefin-server.efi \ + /usr/lib/bluefin-server/bluefin-server.efi; do + if [ -f "${candidate}" ]; then + cp -a "${candidate}" /mnt/esp/EFI/BOOT/BOOTX64.EFI + echo "==> Successfully staged ${candidate} -> ${esp_dev}:/EFI/BOOT/BOOTX64.EFI" + break + fi + done + umount /mnt/esp || true fi fi + + if [ -n "${CREDS_DIR}" ] && [ "${esp_mounted}" -ne 1 ]; then + echo "ERROR: inst.creds_url was given but the target ESP could not be found or mounted; credentials were not installed." >&2 + exit 1 + fi } # Check for unattended in kernel command line @@ -485,7 +651,7 @@ config: --reboot=no \ --mute-console=yes \ "${TARGET_DISK}" < /dev/null - stage_fallback_bootloader + finalize_target_esp else echo "ERROR: No suitable target disk found for unattended installation!" >&2 exit 1 @@ -512,7 +678,7 @@ config: --copy-keymap=yes \ --copy-timezone=yes \ "${EXTRA_ARGS[@]}" - stage_fallback_bootloader + finalize_target_esp echo "==> Installation complete! Rebooting..." systemctl reboot fi From 0bb3a3b804e2b1ef4453336ed4377e45575ae38d Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Sat, 26 Sep 2026 12:20:10 -0500 Subject: [PATCH 2/4] docs(installer): document inst.creds_url / inst.creds_sha256 for PXE installs Extend the "PXE network installs" section of ddi-installer.md with the two credentials parameters next to the inst.ddi_* pair: the flat *.cred tar format and how to build it, the fetch-before-disk-change and fail-closed guarantees, how the wrapper locates and mounts the target ESP, and an iPXE stanza that adds a per-host creds archive. Add a Common Rationalizations row mirroring the DDI one and widen the index.md scope line. Assisted-by: Claude Fable 5.1 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/skills/ddi-installer.md | 46 +++++++++++++++++++++++++++++------- docs/skills/index.md | 4 ++-- 2 files changed, 40 insertions(+), 10 deletions(-) diff --git a/docs/skills/ddi-installer.md b/docs/skills/ddi-installer.md index a8823dba..2de7d8ad 100644 --- a/docs/skills/ddi-installer.md +++ b/docs/skills/ddi-installer.md @@ -182,6 +182,12 @@ over the LAN with `inst.*` kernel parameters: embedded installer partition. - `inst.ddi_sha256=` — **mandatory** when `inst.ddi_url` is set; verify the downloaded DDI before touching the target disk (fail closed if absent). +- `inst.creds_url=` — download a tar archive of first-boot systemd + credentials and place them in the installed system's ESP at + `/loader/credentials/`, where `systemd-stub` hands them to the target OS on + first boot (consumers: [tpm2-credential-sealing.md](tpm2-credential-sealing.md)). +- `inst.creds_sha256=` — **mandatory** when `inst.creds_url` is set; verify + the downloaded archive before touching the target disk (fail closed if absent). - `inst.target_disk=/dev/...` — explicit target disk, overriding first-writable-disk auto-detection. @@ -195,18 +201,41 @@ decompresses it with `zstd`, and feeds it into the **native** points at the downloaded image — no custom installer logic. The override is written with plain Bash line handling: the live initrd contains only what `installer-stack.bst` and its transitive runtime deps install (Bash, uutils -coreutils, util-linux, kmod, systemd, `grep`, `curl`, `zstd`, cryptsetup, -xfsprogs, dosfstools). `sed`, `awk` and `tar` are **not** present. Every -external command the wrapper calls is pinned by the Step 1a tool check in -`bluefin-server-installer.bst`, which fails the build when one is missing. +coreutils, util-linux, kmod, systemd, `grep`, `curl`, `zstd`, `tar` (declared +for the credentials archive), cryptsetup, xfsprogs, dosfstools). `sed` and +`awk` are **not** present. Every external command the wrapper calls is pinned +by the Step 1a tool check in `bluefin-server-installer.bst`, which fails the +build when one is missing. + +The credentials archive is flat: top-level regular files named `.cred` +only, plain or `systemd-creds encrypt`ed, no directories or links. Any other +member rejects the whole archive. Build it with explicit member names so no +`./` entry is recorded: + +```bash +tar -cf .tar -C /path/to/creds firstboot.hostname.cred tmpfiles.extra.cred +sha256sum .tar +``` -Example iPXE stanza (the PXE server mirrors the three assets, verified against -the signed `SHA256SUMS`): +Ordering and guarantees: both downloads are fetched and verified together, +before any disk change, so a bad DDI or credentials download aborts the install +with the target untouched. The credentials are unpacked into +`/dev/shm/installer/credentials/` at that point and copied onto the ESP only after `systemd-sysinstall` has created it; +the wrapper locates the ESP by GPT partition type +(`c12a7328-f81f-11d2-ba4b-00a0c93ec93b`) on the target disk, mounts it once +(the same mount stages the UEFI fallback loader), writes +`/loader/credentials/*.cred`, syncs, and unmounts. If the ESP cannot be found +or mounted while `inst.creds_url` is set, the install fails rather than leaving +the host to boot unconfigured. Without `inst.creds_url`, no credentials are +written. + +Example iPXE stanza (the PXE server mirrors the three release assets, verified +against the signed `SHA256SUMS`, plus one per-host credentials archive): ```ipxe #!ipxe set base http://pxe-server:8080/data -kernel ${base}/bluefin-server-pxe-vmlinuz- systemd.unit=system-install.target console=tty0 console=ttyS0,115200 rw unattended inst.ddi_url=${base}/bluefin-server-ddi-.raw.zst inst.ddi_sha256= +kernel ${base}/bluefin-server-pxe-vmlinuz- systemd.unit=system-install.target console=tty0 console=ttyS0,115200 rw unattended inst.ddi_url=${base}/bluefin-server-ddi-.raw.zst inst.ddi_sha256= inst.creds_url=${base}/creds/${mac}.tar inst.creds_sha256= initrd ${base}/bluefin-server-pxe-initrd-.cpio.gz boot ``` @@ -248,8 +277,9 @@ unaffected. | "Use knuckle instead." | knuckle is deprecated in favor of native `systemd-sysinstall` (systemd 261+). | | "Hardcode `root=/dev/vda2` for QEMU." | Bare metal has different device names. Always use PARTUUID. | | "Pull the DDI from the network at install time." | Network pull is opt-in via `inst.ddi_url`; verification is mandatory and failures abort before any disk change, while the embedded installer media stays the default. | -| "The live initrd has sed/awk/tar like any Linux box." | It does not. The initrd holds only `installer-stack.bst` plus transitive runtime deps (Bash, uutils coreutils, util-linux, kmod, systemd, `grep`, `curl`, `zstd`); `sed`, `awk` and `tar` are absent and fail with `command not found` (exit 127) after the download. Use Bash builtins, or declare the tool in `installer-stack.bst` and add it to the Step 1a build-time tool check. | +| "The live initrd has sed/awk like any Linux box." | It does not. The initrd holds only `installer-stack.bst` plus transitive runtime deps (Bash, uutils coreutils, util-linux, kmod, systemd, `grep`, `curl`, `zstd`, `tar`); `sed` and `awk` are absent and fail with `command not found` (exit 127) after the download. Use Bash builtins, or declare the tool in `installer-stack.bst` and add it to the Step 1a build-time tool check. | | "`/run` can hold the downloaded DDI." | No. systemd mounts `/run` with `size=20%`; the network DDI stages in `/dev/shm/installer/` (kernel tmpfs default, 50% of RAM) and the wrapper checks tmpfs free space and `MemAvailable` before decompressing. See "Memory requirements". | +| "Per-host configuration needs a custom installer step." | `inst.creds_url` is opt-in and only delivers verified `*.cred` files to the ESP `/loader/credentials/`; the installed OS consumes them through stock systemd credential consumers, so no installer logic is added. | | "Put the DDI in the initrd cpio." | The DDI is ≈1.6 GiB raw (2 GiB+ once sparse space is written out). The initrd cpio step must run before the DDI is placed in `/layer`. | | "Store the DDI in the ESP (FAT32)." | FAT32 has a 4 GiB per-file limit. Use a separate XFS partition. | | "Add an 8 GiB minimum size floor to the DDI." | The rootfs is immutable. It never grows in-place. Content + overhead is enough. | diff --git a/docs/skills/index.md b/docs/skills/index.md index 2c43ad27..927221dd 100644 --- a/docs/skills/index.md +++ b/docs/skills/index.md @@ -4,7 +4,7 @@ description: Lazy-load manifest for Bluefin Server skills. Load this file after metadata: type: index status: stable - last_updated: "2026-09-08" + last_updated: "2026-09-25" --- # docs/skills — Index @@ -27,7 +27,7 @@ This is the lazy-load routing table for agent skills. Keep this file in memory w | [`bump-fsdk-version.md`](bump-fsdk-version.md) | Pinning or retagging the FSDK junction | Update the pinned FSDK release and derived tags. | | [`ci-tooling.md`](ci-tooling.md) | GitHub Actions, workflow SHA pinning, CI conventions | CI conventions and release pipeline rules. | | [`ddi-installer-build.md`](ddi-installer-build.md) | Building the installer or DDI on the cluster | Cluster build pipeline and local installer/DDI build. | -| [`ddi-installer.md`](ddi-installer.md) | Installer boot flow, `systemd-sysinstall`, `systemd-repart`, PXE network DDI pull | High-level DDI install architecture and local smoke test. | +| [`ddi-installer.md`](ddi-installer.md) | Installer boot flow, `systemd-sysinstall`, `systemd-repart`, PXE network DDI / credentials pull | High-level DDI install architecture and local smoke test. | | [`factory-integration.md`](factory-integration.md) | Lab integration, boot-test workflow, factory role | How Bluefin Server is consumed by the CI lab. | | [`flatcar-parity-matrix.md`](flatcar-parity-matrix.md) | Flatcar version audit, component parity, substitution order | Version parity matrix and gap audit against Flatcar 4593.2.5. | | [`gap-analysis-distros.md`](gap-analysis-distros.md) | Comparing Bluefin Server to other server OSes | Source-verified comparison to Ubuntu, Talos, Flatcar, FCOS. | From 44adaa55dc7cb23bda0cef50da56a8aa23b5a7bc Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Sat, 26 Sep 2026 12:20:10 -0500 Subject: [PATCH 3/4] test(installer): contract and executed coverage for the credentials pull test_installer_contract.py gains a contract for the inst.creds_* wiring: parameter parsing, mandatory-checksum wording, the fetch -> verify -> size cap -> ustar magic -> listing -> unpack -> systemd-sysinstall ordering, tar only ever reading the archive from stdin, the 16 MiB / 64 member / 250-byte name / 1 MiB caps, the mode and name patterns, the case-insensitive duplicate check, the plain-vs-verbose listing cross-check, the post-extraction regular-file re-check and 0644 pin, ESP lookup by GPT partition type on a single vfat mount with per-name copies (no glob) written before the best-effort loader, the fail-closed message, and tar.bst in the installer stack plus tar in the build-time tool check. The sed/awk test drops tar from its forbidden list now that tar is declared. test_installer_creds_pull_behavior.py runs the fetch/verify/validate/unpack block of the wrapper (shared installer_wrapper fixture) under bash against real tar archives with a stand-in curl: a flat archive lands in tmpfs at 0644 regardless of archive modes/owners and the download is removed; 64 members with a 1 MiB member is accepted at the boundary; a systemd.unit-dropin.~.cred member is accepted; a 250-byte name passes and a 251-byte one is rejected; a checksum mismatch, non-.cred names, directories, ./ prefixes, symlinks, hardlinks, character and block devices, FIFOs, names with spaces, newlines, colons, leading dashes or dots, an owner field with a space (column shift), a member over 1 MiB, 65 members, a repeated name, two names differing only by case, an archive over 16 MiB, a zstd-compressed tar (rejected at the magic check; and GNU tar on stdin is shown to refuse it even without the check) and non-tar payloads each abort without creating the credentials directory. The module docstring states what is not executed: the curl-side --max-filesize (the stand-in curl ignores it; the stat re-check is executed) and finalize_target_esp (string assertions only). Tests skip unless GNU tar is present, since the wrapper parses GNU tar's -tv layout. Assisted-by: Claude Fable 5.1 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- tests/unit/test_installer_contract.py | 104 ++++- .../test_installer_creds_pull_behavior.py | 368 ++++++++++++++++++ 2 files changed, 462 insertions(+), 10 deletions(-) create mode 100644 tests/unit/test_installer_creds_pull_behavior.py diff --git a/tests/unit/test_installer_contract.py b/tests/unit/test_installer_contract.py index 605f41d7..7a0973db 100644 --- a/tests/unit/test_installer_contract.py +++ b/tests/unit/test_installer_contract.py @@ -145,14 +145,15 @@ def test_installer_hard_preflight_aborts_on_missing_installer_data_part() -> Non assert "lsblk -p -o NAME,TYPE,PARTLABEL,PKNAME,SIZE,FSTYPE" in installer_element -def test_installer_wrapper_does_not_call_sed_awk_or_tar(installer_wrapper: str) -> None: +def test_installer_wrapper_does_not_call_sed_or_awk(installer_wrapper: str) -> None: # The released 26.08.0 PXE initrd failed with "sed: command not found" # (exit 127) right after a successful download: the live initrd ships - # uutils coreutils, grep, curl, zstd and systemd, but no sed, awk or tar, - # so no command position may name any of them. Only a '#' at the start of - # a line or after whitespace opens a comment; '#' inside a string does not. + # uutils coreutils, grep, curl, zstd, tar (declared for the credentials + # archive) and systemd, but no sed or awk, so no command position may + # name either. Only a '#' at the start of a line or after whitespace + # opens a comment; '#' inside a string does not. code_lines = [re.sub(r"(^|\s)#.*$", "", line) for line in installer_wrapper.splitlines()] - invoked = re.compile(r"(?:^|[\s|;&(`$])(sed|awk|tar)(?=[\s;|&)>]|$)") + invoked = re.compile(r"(?:^|[\s|;&(`$])(sed|awk)(?=[\s;|&)>]|$)") offenders = [line for line in code_lines if invoked.search(line)] assert offenders == [], offenders @@ -168,7 +169,7 @@ def test_installer_build_pins_every_external_command_the_wrapper_calls() -> None for tool in ( "grep", "curl", "zstd", "modprobe", "mount", "umount", "sha256sum", "readlink", "lsblk", "udevadm", "systemd-sysinstall", "systemctl", - "mountpoint", "stat", "df", "tail", + "mountpoint", "stat", "df", "tail", "tar", "dd", "rm", "chmod", "sync", ): assert tool in pinned, f"{tool} is called by bluefin-sysinstall but not pinned at build time" @@ -414,17 +415,100 @@ def test_installer_network_ddi_waits_for_networkd_by_absolute_path(installer_wra assert "--ipv4" in args assert any(arg.startswith("--timeout=") for arg in args) - # The wait must sit inside the inst.ddi_url block (an unconditional wait - # would stall every offline USB install) and before the download. - ddi_block = wrapper.index('if [ -n "${DDI_URL}" ]; then') + # The wait must sit inside the network-pull block (an unconditional wait + # would stall every offline USB install) and before the downloads. + net_block = wrapper.index('if [ -n "${DDI_URL}" ] || [ -n "${CREDS_URL}" ]; then') fetch = wrapper.index('--output /dev/shm/installer/bluefin-server-ddi.raw.zst "${DDI_URL}"') - assert ddi_block < call.start() < fetch + assert net_block < call.start() < fetch assert "ERROR: systemd-networkd-wait-online failed" in wrapper # The build fails if the FSDK ever moves the binary out from under the path. assert "if ! [ -x /layer/usr/lib/systemd/systemd-networkd-wait-online ]; then" in installer_element +def test_installer_network_credentials_pull_contract() -> None: + installer_element = INSTALLER_ELEMENT.read_text(encoding="utf-8") + installer_stack = INSTALLER_STACK.read_text(encoding="utf-8") + + # Both parameters are parsed next to the inst.ddi_* pair and the checksum is + # mandatory, mirroring the DDI pull's fail-closed wording. + assert 'inst.creds_url=*) CREDS_URL="${arg#inst.creds_url=}" ;;' in installer_element + assert 'inst.creds_sha256=*) CREDS_SHA256="${arg#inst.creds_sha256=}" ;;' in installer_element + assert ( + "ERROR: inst.creds_url is set but inst.creds_sha256 is missing; " + "verification is mandatory for network installs." + ) in installer_element + assert "ERROR: downloaded credentials SHA256 verification failed." in installer_element + + # Fetch + verify + unpack into tmpfs happen before systemd-sysinstall runs, so + # a bad archive aborts with the target disk untouched. + fetch = installer_element.index('--output /dev/shm/installer/credentials.tar "${CREDS_URL}"') + verify = installer_element.index("ERROR: downloaded credentials SHA256 verification failed.") + size_cap = installer_element.index('CREDS_TAR_BYTES="$(stat -c %s /dev/shm/installer/credentials.tar)"') + magic = installer_element.index( + 'if [ "$(dd if=/dev/shm/installer/credentials.tar bs=1 skip=257 count=5 2>/dev/null)" != "ustar" ]; then' + ) + listing = installer_element.index("tar --quoting-style=escape -tvf - < /dev/shm/installer/credentials.tar") + unpack = installer_element.index( + 'tar --no-same-owner --no-same-permissions -C "${CREDS_DIR}" \\\n' + ' -xf - -- "${CREDS_NAMES[@]}" < /dev/shm/installer/credentials.tar' + ) + sysinstall = installer_element.index("/usr/bin/systemd-sysinstall \\") + assert fetch < verify < size_cap < magic < listing < unpack < sysinstall + # tar never sees the archive as a named file, so it cannot transparently + # decompress a compressed download into an unbounded listing. + assert "-tvf /dev/shm/installer/credentials.tar" not in installer_element + assert "-tf /dev/shm/installer/credentials.tar" not in installer_element + assert "-xf /dev/shm/installer/credentials.tar" not in installer_element + + # Nothing unverified is used: the download is capped at 16 MiB (curl and a + # stat re-check after the checksum), the verbose listing is validated column + # by column (regular file, numeric size <= 1 MiB, date/time columns, strict + # name pattern, <= 64 members) and cross-checked against the plain listing, + # then only the validated names are extracted, pinned to 0644 and re-checked + # as regular files. + assert "--max-filesize 16777216" in installer_element + assert 'if [ "${CREDS_TAR_BYTES}" -gt 16777216 ]; then' in installer_element + assert "CREDS_MODE_RE='^-[-rwxsStT]{9}$'" in installer_element + assert "CREDS_NAME_RE='^[A-Za-z0-9][A-Za-z0-9._@~-]*\\.cred$'" in installer_element + assert 'if [ "${CREDS_COUNT}" -gt 64 ]; then' in installer_element + assert 'if [ "${#name}" -gt 250 ]; then' in installer_element + assert 'if [ "${size}" -gt 1048576 ]; then' in installer_element + assert 'if [ -n "${CREDS_SEEN[${name,,}]+set}" ]; then' in installer_element + assert ( + 'if [ "$(printf \'%s\\n\' "${CREDS_NAMES[@]}")" != "${CREDS_PLAIN_LIST}" ]; then' + in installer_element + ) + assert 'if [ -L "${CREDS_DIR}/${name}" ] || ! [ -f "${CREDS_DIR}/${name}" ]; then' in installer_element + assert 'chmod 0644 -- "${CREDS_DIR}/${name}"' in installer_element + + # The ESP is located by GPT partition type on the target disk, mounted once + # (shared with the fallback-loader staging), only the validated names are + # copied (never a glob over the extraction dir), and the pull fails closed + # when the ESP cannot be mounted. + assert 'lsblk -p -n -l -o NAME,PARTTYPE "${target}"' in installer_element + assert '"${parttype,,}" = "c12a7328-f81f-11d2-ba4b-00a0c93ec93b"' in installer_element + assert 'cp -- "${CREDS_DIR}/${name}" /mnt/esp/loader/credentials/' in installer_element + assert "${CREDS_DIR}\"/*.cred" not in installer_element + assert installer_element.count("mount -t vfat") == 1 + assert ( + "ERROR: inst.creds_url was given but the target ESP could not be found or mounted; " + "credentials were not installed." + ) in installer_element + + # The credentials are written before the best-effort fallback-loader copy, + # so a loader hiccup cannot abort the function with the mandatory step undone. + creds_copy = installer_element.index('cp -- "${CREDS_DIR}/${name}" /mnt/esp/loader/credentials/') + loader_copy = installer_element.index('cp -a "${candidate}" /mnt/esp/EFI/BOOT/BOOTX64.EFI') + assert creds_copy < loader_copy + + # tar is the only new tool; it is declared in the stack and checked at build + # time next to the wrapper's other external commands. + assert "freedesktop-sdk.bst:components/tar.bst" in installer_stack + tools = re.search(r"for tool in ((?:[^;\n]|\\\n)+); do", installer_element) + assert tools and "tar" in tools.group(1).split() + + def test_interactive_installer_uses_local_virtual_console() -> None: installer_element = INSTALLER_ELEMENT.read_text(encoding="utf-8") diff --git a/tests/unit/test_installer_creds_pull_behavior.py b/tests/unit/test_installer_creds_pull_behavior.py new file mode 100644 index 00000000..d1e766a2 --- /dev/null +++ b/tests/unit/test_installer_creds_pull_behavior.py @@ -0,0 +1,368 @@ +"""Executed coverage for the bluefin-sysinstall inst.creds_url archive handling. + +The wrapper is carved out of the installer element's heredoc and run under bash +with a stand-in curl, so the fetch/verify/validate/unpack block is exercised +against real tar archives without a network or a BuildStream build. + +Not executed here: the stand-in curl copies the "URL" path and ignores +--max-filesize, so the curl-side 16 MiB cap is only pinned as a string by +test_installer_contract.py (the stat re-check after the checksum *is* +executed), and finalize_target_esp (ESP lookup by GPT type, mount, copy, +fail-closed) needs a block device and is covered by string assertions only. +""" + +from __future__ import annotations + +import hashlib +import io +import os +import shutil +import subprocess +import tarfile +from pathlib import Path + +import pytest + +REPO_ROOT = Path(__file__).resolve().parents[2] +INSTALLER_ELEMENT = REPO_ROOT / "elements" / "oci" / "bluefin-server-installer.bst" + +def _gnu_tar_available() -> bool: + if shutil.which("bash") is None or shutil.which("tar") is None: + return False + version = subprocess.run(["tar", "--version"], capture_output=True, text=True) + return "GNU tar" in version.stdout + + +pytestmark = pytest.mark.skipif( + not _gnu_tar_available(), + reason="bash and GNU tar (the initrd's tar, whose -tv listing format the wrapper parses) are required", +) + + +def _creds_block(script: str) -> str: + lines = script.splitlines() + anchor = next(i for i, line in enumerate(lines) if "Fetching first-boot credentials" in line) + start = next(i for i in range(anchor, -1, -1) if lines[i] == 'if [ -n "${CREDS_URL}" ]; then') + end = next(i for i in range(anchor, len(lines)) if lines[i] == "fi") + return "\n".join(lines[start : end + 1]) + "\n" + + +def _write_tar(path: Path, members: dict[str, bytes | None], *, symlink: str | None = None) -> str: + with tarfile.open(path, "w") as tar: + for name, payload in members.items(): + if payload is None: + info = tarfile.TarInfo(name) + info.type = tarfile.DIRTYPE + tar.addfile(info) + else: + info = tarfile.TarInfo(name) + info.size = len(payload) + tar.addfile(info, fileobj=io.BytesIO(payload)) + if symlink: + info = tarfile.TarInfo(symlink) + info.type = tarfile.SYMTYPE + info.linkname = "/etc/passwd" + tar.addfile(info) + return hashlib.sha256(path.read_bytes()).hexdigest() + + + +def _write_tar_members(path: Path, members: list[tuple[tarfile.TarInfo, bytes | None]]) -> str: + with tarfile.open(path, "w") as tar: + for info, payload in members: + if payload is None: + tar.addfile(info) + else: + info.size = len(payload) + tar.addfile(info, fileobj=io.BytesIO(payload)) + return hashlib.sha256(path.read_bytes()).hexdigest() + + +def _regular(name: str, payload: bytes = b"x", **attrs: object) -> tuple[tarfile.TarInfo, bytes]: + info = tarfile.TarInfo(name) + for key, value in attrs.items(): + setattr(info, key, value) + return info, payload + + +def _special(name: str, tar_type: bytes, **attrs: object) -> tuple[tarfile.TarInfo, None]: + info = tarfile.TarInfo(name) + info.type = tar_type + for key, value in attrs.items(): + setattr(info, key, value) + return info, None + + +def _run_creds_block(tmp_path: Path, archive: Path, sha256: str, wrapper: str) -> tuple[subprocess.CompletedProcess[str], Path]: + run_dir = tmp_path / "run-installer" + run_dir.mkdir() + fake_bin = tmp_path / "bin" + fake_bin.mkdir() + (fake_bin / "curl").write_text( + "#!/bin/bash\n" + "out=''\n" + 'while [ $# -gt 1 ]; do [ "$1" = --output ] && out="$2"; shift; done\n' + 'cp -- "$1" "$out"\n', + encoding="utf-8", + ) + os.chmod(fake_bin / "curl", 0o755) + + block = _creds_block(wrapper).replace("/dev/shm/installer", str(run_dir)) + script = ( + "set -euo pipefail\n" + f'CREDS_URL="{archive}"\nCREDS_SHA256="{sha256}"\nCREDS_DIR=""\nCREDS_NAMES=()\n' + f"{block}" + 'echo "CREDS_DIR=${CREDS_DIR}"\n' + 'printf \'CREDS_NAME=%s\\n\' "${CREDS_NAMES[@]}"\n' + ) + env = {**os.environ, "PATH": f"{fake_bin}:{os.environ['PATH']}"} + return ( + subprocess.run(["bash", "-c", script], capture_output=True, text=True, env=env), + run_dir, + ) + + +def test_wrapper_script_parses_under_bash(installer_wrapper: str) -> None: + result = subprocess.run(["bash", "-n", "-c", installer_wrapper], capture_output=True, text=True) + assert result.returncode == 0, result.stderr + + +@pytest.mark.skipif(shutil.which("shellcheck") is None, reason="shellcheck not installed") +def test_wrapper_script_is_shellcheck_clean_at_warning_level(installer_wrapper: str) -> None: + result = subprocess.run( + ["shellcheck", "--shell=bash", "-S", "warning", "-"], + input=installer_wrapper, + capture_output=True, + text=True, + ) + assert result.returncode == 0, result.stdout + + +def test_flat_cred_archive_is_verified_and_unpacked_into_tmpfs(tmp_path: Path, installer_wrapper: str) -> None: + archive = tmp_path / "creds.tar" + sha256 = _write_tar_members( + archive, + [ + _regular("firstboot.hostname.cred", b"node-01\n", mode=0o600, uname="root", gname="root"), + _regular("tmpfiles.extra.cred", b"d /var/home/core 0700 core core -\n", mode=0o4777, uid=1000), + ], + ) + + result, run_dir = _run_creds_block(tmp_path, archive, sha256, installer_wrapper) + + assert result.returncode == 0, result.stderr + assert f"CREDS_DIR={run_dir}/credentials" in result.stdout + assert result.stdout.count("CREDS_NAME=") == 2 + assert "CREDS_NAME=firstboot.hostname.cred" in result.stdout + assert "CREDS_NAME=tmpfiles.extra.cred" in result.stdout + extracted = sorted((run_dir / "credentials").iterdir()) + assert [p.name for p in extracted] == ["firstboot.hostname.cred", "tmpfiles.extra.cred"] + # Archive modes (0600, setuid 4777) and ownership are not honoured: our own + # copies are pinned to 0644. + assert [oct(p.stat().st_mode & 0o7777) for p in extracted] == ["0o644", "0o644"] + assert (run_dir / "credentials" / "firstboot.hostname.cred").read_bytes() == b"node-01\n" + assert not (run_dir / "credentials.tar").exists() + + +def test_caps_are_inclusive_at_64_members_and_1_mib_each(tmp_path: Path, installer_wrapper: str) -> None: + archive = tmp_path / "creds.tar" + members = [_regular(f"cred-{index:02d}.cred") for index in range(63)] + members.append(_regular("big.cred", b"\0" * 1048576)) + sha256 = _write_tar_members(archive, members) + + result, run_dir = _run_creds_block(tmp_path, archive, sha256, installer_wrapper) + + assert result.returncode == 0, result.stderr + assert result.stdout.count("CREDS_NAME=") == 64 + assert len(list((run_dir / "credentials").iterdir())) == 64 + + +def test_checksum_mismatch_fails_closed_before_unpacking(tmp_path: Path, installer_wrapper: str) -> None: + archive = tmp_path / "creds.tar" + _write_tar(archive, {"firstboot.hostname.cred": b"node-01\n"}) + + result, run_dir = _run_creds_block(tmp_path, archive, "0" * 64, installer_wrapper) + + assert result.returncode == 1 + assert "downloaded credentials SHA256 verification failed" in result.stderr + assert not (run_dir / "credentials").exists() + + +@pytest.mark.parametrize( + ("members", "symlink", "rejected"), + [ + ({"firstboot.hostname.cred": b"x", "README.txt": b"y"}, None, "README.txt"), + ({"sub/": None, "sub/nested.cred": b"x"}, None, "sub/"), + ({"./": None, "./firstboot.hostname.cred": b"x"}, None, "./"), + ({"firstboot.hostname.cred": b"x"}, "link.cred", "link.cred"), + ({".cred": b"x"}, None, ".cred"), + ], +) +def test_non_flat_or_non_cred_members_reject_the_whole_archive( + tmp_path: Path, installer_wrapper: str, members: dict[str, bytes | None], symlink: str | None, rejected: str +) -> None: + archive = tmp_path / "creds.tar" + sha256 = _write_tar(archive, members, symlink=symlink) + + result, run_dir = _run_creds_block(tmp_path, archive, sha256, installer_wrapper) + + assert result.returncode == 1 + assert f"credentials archive member '{rejected}" in result.stderr + assert "refusing the archive" in result.stderr + assert not (run_dir / "credentials").exists() + + +def test_garbage_or_empty_download_is_rejected(tmp_path: Path, installer_wrapper: str) -> None: + # Neither carries the ustar magic at offset 257, so both stop at the + # format check before tar is even asked to read them. + for payload in (b"", b"not a tar archive\n", b"\0" * 512 + b"garbage" * 100): + blob = tmp_path / "creds.tar" + blob.write_bytes(payload) + sha256 = hashlib.sha256(payload).hexdigest() + + result, run_dir = _run_creds_block(tmp_path, blob, sha256, installer_wrapper) + + assert result.returncode == 1 + assert "not an uncompressed ustar/pax tar archive" in result.stderr + assert not (run_dir / "credentials").exists() + shutil.rmtree(run_dir) + shutil.rmtree(tmp_path / "bin") + + +@pytest.mark.skipif(shutil.which("zstd") is None, reason="zstd not installed") +def test_compressed_archive_is_rejected_without_being_decompressed(tmp_path: Path, installer_wrapper: str) -> None: + # GNU tar would transparently decompress a .tar.zst named on -f, letting a + # 16 MiB download expand into an unbounded listing held in bash variables. + # The wrapper checks the ustar magic and feeds tar on stdin, where it + # refuses compressed input; a valid archive that is merely compressed must + # be rejected before any member is listed. + plain = tmp_path / "plain.tar" + _write_tar(plain, {"firstboot.hostname.cred": b"node-01\n"}) + compressed = tmp_path / "creds.tar" + subprocess.run(["zstd", "-q", "-f", str(plain), "-o", str(compressed)], check=True) + sha256 = hashlib.sha256(compressed.read_bytes()).hexdigest() + + result, run_dir = _run_creds_block(tmp_path, compressed, sha256, installer_wrapper) + + assert result.returncode == 1, result.stdout + assert "not an uncompressed ustar/pax tar archive" in result.stderr + assert "CREDS_NAME=" not in result.stdout + assert not (run_dir / "credentials").exists() + + # Belt and braces: even with the magic check bypassed, tar on stdin refuses + # to decompress (GNU tar only auto-detects compression for a named file). + listing = subprocess.run( + ["bash", "-c", f"LC_ALL=C tar -tvf - < {compressed}"], capture_output=True, text=True + ) + assert listing.returncode != 0 + assert "compressed" in listing.stderr + + +def test_tilde_names_from_systemd_dropin_namespace_are_accepted(tmp_path: Path, installer_wrapper: str) -> None: + # systemd.unit-dropin.~ is systemd's own credential namespace + # (systemd.system-credentials(7)); ~ is a legal vfat long-filename byte. + archive = tmp_path / "creds.tar" + name = "systemd.unit-dropin.multi-user.target~booty.cred" + sha256 = _write_tar(archive, {name: b"[Unit]\n", "firstboot.hostname.cred": b"node-01\n"}) + + result, run_dir = _run_creds_block(tmp_path, archive, sha256, installer_wrapper) + + assert result.returncode == 0, result.stderr + assert f"CREDS_NAME={name}" in result.stdout + assert (run_dir / "credentials" / name).read_bytes() == b"[Unit]\n" + + +def test_member_name_length_is_capped_at_250_bytes(tmp_path: Path, installer_wrapper: str) -> None: + # A 250-byte name passes; 251 is rejected by the wrapper, with its own + # message, before tar (ENAMETOOLONG at 256) or vfat (255) would fail it. + ok_name = "n" * (250 - len(".cred")) + ".cred" + long_name = "n" * (251 - len(".cred")) + ".cred" + assert len(ok_name) == 250 and len(long_name) == 251 + + archive = tmp_path / "ok.tar" + sha256 = _write_tar(archive, {ok_name: b"x"}) + (tmp_path / "ok").mkdir() + ok, _ = _run_creds_block(tmp_path / "ok", archive, sha256, installer_wrapper) + assert ok.returncode == 0, ok.stderr + assert f"CREDS_NAME={ok_name}" in ok.stdout + + archive = tmp_path / "long.tar" + sha256 = _write_tar(archive, {long_name: b"x"}) + (tmp_path / "long").mkdir() + rejected, run_dir = _run_creds_block(tmp_path / "long", archive, sha256, installer_wrapper) + assert rejected.returncode == 1, rejected.stdout + assert f"member '{long_name}' has a 251-byte name, above the 250-byte limit" in rejected.stderr + assert not (run_dir / "credentials").exists() + + +@pytest.mark.parametrize( + ("names", "rejected"), + [ + pytest.param(["a.cred", "a.cred"], "member 'a.cred' repeats 'a.cred'", id="duplicate"), + pytest.param(["Host.cred", "host.cred"], "member 'host.cred' repeats 'Host.cred'", id="case-collision-on-vfat"), + ], +) +def test_repeated_or_case_colliding_names_reject_the_whole_archive( + tmp_path: Path, installer_wrapper: str, names: list[str], rejected: str +) -> None: + # tar -x with a repeated name fails half-way through with tar's own error; + # two names that differ only by case both extract in tmpfs and then + # silently overwrite each other on the vfat ESP. Both are refused up front. + archive = tmp_path / "creds.tar" + sha256 = _write_tar_members(archive, [_regular(name, name.encode()) for name in names]) + + result, run_dir = _run_creds_block(tmp_path, archive, sha256, installer_wrapper) + + assert result.returncode == 1, result.stdout + assert rejected in result.stderr + assert "refusing the archive" in result.stderr + assert not (run_dir / "credentials").exists() + + +@pytest.mark.parametrize( + ("members", "rejected"), + [ + pytest.param( + [_regular("firstboot.hostname.cred"), _special("copy.cred", tarfile.LNKTYPE, linkname="firstboot.hostname.cred")], + "member 'copy.cred", + id="hardlink", + ), + pytest.param([_special("tty.cred", tarfile.CHRTYPE, devmajor=5, devminor=0)], "member 'tty.cred", id="char-device"), + pytest.param([_special("sda.cred", tarfile.BLKTYPE, devmajor=8, devminor=0)], "member 'sda.cred", id="block-device"), + pytest.param([_special("pipe.cred", tarfile.FIFOTYPE)], "member 'pipe.cred", id="fifo"), + pytest.param([_regular("host name.cred")], "member 'host name.cred", id="space-in-name"), + pytest.param([_regular("host\nname.cred")], "member 'host\\nname.cred", id="newline-in-name"), + pytest.param([_regular("-rf.cred")], "member '-rf.cred", id="leading-dash"), + pytest.param([_regular("..cred")], "member '..cred", id="leading-dot"), + pytest.param([_regular("host:name.cred")], "member 'host:name.cred", id="colon-in-name"), + pytest.param([_regular("ok.cred", uname="a b", gname="c")], "is not a top-level regular *.cred file", id="space-in-owner-shifts-columns"), + pytest.param([_regular("big.cred", b"\0" * (1048576 + 1))], "member 'big.cred' is 1048577 bytes, above the 1 MiB limit", id="member-over-1-mib"), + pytest.param([_regular(f"cred-{index:02d}.cred") for index in range(65)], "more than 64 members", id="65-members"), + ], +) +def test_unsafe_members_reject_the_whole_archive( + tmp_path: Path, installer_wrapper: str, members: list[tuple[tarfile.TarInfo, bytes | None]], rejected: str +) -> None: + archive = tmp_path / "creds.tar" + sha256 = _write_tar_members(archive, members) + + result, run_dir = _run_creds_block(tmp_path, archive, sha256, installer_wrapper) + + assert result.returncode == 1, result.stdout + assert rejected in result.stderr + assert "refusing the archive" in result.stderr + assert not (run_dir / "credentials").exists() + + +def test_archive_over_16_mib_is_rejected_after_the_checksum(tmp_path: Path, installer_wrapper: str) -> None: + archive = tmp_path / "creds.tar" + sha256 = _write_tar_members( + archive, [_regular(f"pad-{index:02d}.cred", b"\0" * 1048576) for index in range(17)] + ) + assert archive.stat().st_size > 16777216 + + result, run_dir = _run_creds_block(tmp_path, archive, sha256, installer_wrapper) + + assert result.returncode == 1, result.stdout + assert "above the 16 MiB limit; refusing the archive" in result.stderr + assert not (run_dir / "credentials").exists() From 9ef3068d8fe343e4b36d751f792dee1af21163b5 Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Sat, 26 Sep 2026 12:20:22 -0500 Subject: [PATCH 4/4] docs(installer): credentials archive must be encrypted, capped and validated Verified in QEMU on the installed image: systemd-stub stages ESP credentials under /run/credentials/@encrypted, so plaintext *.cred files are rejected by the consuming services with status=243/CREDENTIALS. Null-key encrypted files apply. Document the requirement and show the encrypt commands. State the archive contract the wrapper enforces: an uncompressed ustar/pax/gnu tar (compressed archives are rejected, not transparently decompressed), at most 64 top-level regular files named .cred with matching [A-Za-z0-9][A-Za-z0-9._@~-]* (~ for systemd's drop-in credential namespace), names at most 250 bytes and unique ignoring case (vfat ESP), each at most 1 MiB, 16 MiB in total; the listing is validated column by column and cross-checked before extraction, only validated names are extracted (--no-same-owner --no-same-permissions), pinned to 0644 and re-checked as regular files. Add the trust model: the sha256 comes from the same unauthenticated PXE cmdline as the URL, so it protects against a bad file server, not against whoever controls DHCP/TFTP. Note that inst.creds_url accepts any curl scheme and that the credentials are written to the ESP before the best-effort fallback loader. Assisted-by: Claude Fable 5.1 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/skills/ddi-installer.md | 59 +++++++++++++++++++++++++----------- 1 file changed, 42 insertions(+), 17 deletions(-) diff --git a/docs/skills/ddi-installer.md b/docs/skills/ddi-installer.md index 2de7d8ad..c4d5fdcd 100644 --- a/docs/skills/ddi-installer.md +++ b/docs/skills/ddi-installer.md @@ -182,12 +182,14 @@ over the LAN with `inst.*` kernel parameters: embedded installer partition. - `inst.ddi_sha256=` — **mandatory** when `inst.ddi_url` is set; verify the downloaded DDI before touching the target disk (fail closed if absent). -- `inst.creds_url=` — download a tar archive of first-boot systemd - credentials and place them in the installed system's ESP at +- `inst.creds_url=` — download a tar archive of first-boot systemd + credentials (any `curl` scheme; the iPXE example uses plain `http://`) and + place them in the installed system's ESP at `/loader/credentials/`, where `systemd-stub` hands them to the target OS on first boot (consumers: [tpm2-credential-sealing.md](tpm2-credential-sealing.md)). -- `inst.creds_sha256=` — **mandatory** when `inst.creds_url` is set; verify - the downloaded archive before touching the target disk (fail closed if absent). +- `inst.creds_sha256=` — **mandatory** when `inst.creds_url` is set; + verify the downloaded archive before touching the target disk (fail closed + if absent). - `inst.target_disk=/dev/...` — explicit target disk, overriding first-writable-disk auto-detection. @@ -207,27 +209,50 @@ for the credentials archive), cryptsetup, xfsprogs, dosfstools). `sed` and by the Step 1a tool check in `bluefin-server-installer.bst`, which fails the build when one is missing. -The credentials archive is flat: top-level regular files named `.cred` -only, plain or `systemd-creds encrypt`ed, no directories or links. Any other -member rejects the whole archive. Build it with explicit member names so no -`./` entry is recorded: +The credentials archive is an **uncompressed** ustar/pax/gnu tar (the wrapper +checks the `ustar` magic and feeds tar on stdin, so a `.tar.zst`/`.tar.xz` is +rejected rather than transparently decompressed) and flat: at most 64 +top-level regular files named `.cred`, where `` matches +`[A-Za-z0-9][A-Za-z0-9._@~-]*` (`~` is systemd's own drop-in namespace, +`systemd.unit-dropin.~`), each filename at most 250 bytes, each +file at most 1 MiB, the whole archive at most 16 MiB. Names must be unique +even ignoring case — the ESP is vfat, where `a.cred` and `A.cred` are the same +file. The wrapper validates the `tar -tv` listing column by column before +extracting anything (no directories, symlinks, hardlinks, devices or FIFOs; no +path separators, spaces, control characters or leading dashes/dots in names), +cross-checks it against `tar -t`, extracts only the validated names with +`--no-same-owner --no-same-permissions`, pins its copies to `0644` and +re-checks each is a regular file; any violation rejects the whole archive with +the target disk untouched. Trust model: `inst.creds_sha256` arrives on the same +unauthenticated PXE command line as the URL, so the checksum protects against a +compromised or misconfigured file server, not against whoever controls +DHCP/TFTP — they control both. The archive hardening is defence against +operator error and a bad mirror, not a boundary against a hostile netboot +server; secrets belong in TPM2/host-key-sealed credentials. +Each file must be `systemd-creds encrypt`ed with `--name=` matching the +filename — `systemd-stub` stages ESP credentials under +`/run/credentials/@encrypted`, so plaintext files fail with +`status=243/CREDENTIALS`. The null key suffices for non-secret data +(`firstboot.hostname`, `tmpfiles.extra`); use host/TPM2 keys for secrets: ```bash -tar -cf .tar -C /path/to/creds firstboot.hostname.cred tmpfiles.extra.cred +systemd-creds --with-key=null encrypt --name=firstboot.hostname hostname.txt firstboot.hostname.cred +systemd-creds --with-key=null encrypt --name=tmpfiles.extra tmpfiles.conf tmpfiles.extra.cred +tar -cf .tar firstboot.hostname.cred tmpfiles.extra.cred sha256sum .tar ``` Ordering and guarantees: both downloads are fetched and verified together, before any disk change, so a bad DDI or credentials download aborts the install with the target untouched. The credentials are unpacked into -`/dev/shm/installer/credentials/` at that point and copied onto the ESP only after `systemd-sysinstall` has created it; -the wrapper locates the ESP by GPT partition type -(`c12a7328-f81f-11d2-ba4b-00a0c93ec93b`) on the target disk, mounts it once -(the same mount stages the UEFI fallback loader), writes -`/loader/credentials/*.cred`, syncs, and unmounts. If the ESP cannot be found -or mounted while `inst.creds_url` is set, the install fails rather than leaving -the host to boot unconfigured. Without `inst.creds_url`, no credentials are -written. +`/dev/shm/installer/credentials/` at that point and copied onto the ESP only +after `systemd-sysinstall` has created it; the wrapper locates the ESP by GPT +partition type (`c12a7328-f81f-11d2-ba4b-00a0c93ec93b`) on the target disk, +mounts it once, writes `/loader/credentials/*.cred` first, syncs, then stages +the best-effort UEFI fallback loader on the same mount and unmounts. If the ESP +cannot be found or mounted while `inst.creds_url` is set, the install fails +rather than leaving the host to boot unconfigured. Without `inst.creds_url`, no +credentials are written. Example iPXE stanza (the PXE server mirrors the three release assets, verified against the signed `SHA256SUMS`, plus one per-host credentials archive):