Skip to content

feat(installer): opt-in network credentials pull (inst.creds_url / inst.creds_sha256) for PXE installs - #253

Merged
jeefy merged 4 commits into
projectbluefin:mainfrom
jeefy:feat/installer-creds-url
Sep 26, 2026
Merged

jeefy merged 4 commits into
projectbluefin:mainfrom
jeefy:feat/installer-creds-url

Conversation

@jeefy

@jeefy jeefy commented Sep 26, 2026 •

Copy link
Copy Markdown
Collaborator

Branch: feat/installer-creds-url.

Stacked on #252 (wait-online) ← #251 (/dev/shm staging) ← #250 (sed rewrite) — only the last four commits (feat, docs, test, docs) are new here; the credentials pull shares the same staging directory and network wait, so the diff shrinks to those four as the fixes merge.

Motivation

#229 made PXE installs self-contained by letting the installer pull the DDI over the LAN (inst.ddi_url / inst.ddi_sha256). Its feature request (#14 §4) left per-host configuration out of scope, naming the natural follow-up: installer-fetched systemd credentials. A PXE fleet still needs a hostname, an operator SSH key and usually a first-boot callback per machine, and the only delivery path today is an operator hand-mounting the ESP after the install. This PR closes that gap with the same shape as the DDI pull: two opt-in kernel parameters, mandatory verification, no new installer logic — the files are handed to the stock systemd credential consumers already documented in docs/skills/tpm2-credential-sealing.md (firstboot.*, tmpfiles.extra, network.*, passwd.*).

Found while integrating with the jeefy/booty PXE server, which serves GET /creds/<mac>.tar per host.

Behaviour

Parameter Meaning
inst.creds_url=<url> Download a flat, uncompressed tar archive of systemd-creds encrypted *.cred files (any curl scheme; the example uses plain http://) and place them in the installed system's ESP at /loader/credentials/.
inst.creds_sha256=<hex> Mandatory when inst.creds_url is set. Verified before anything is unpacked or written.

iPXE example (${mac} expanded by iPXE):

systemd.unit=system-install.target console=tty0 console=ttyS0,115200 rw unattended inst.ddi_url=${base}/bluefin-server-ddi-<ver>.raw.zst inst.ddi_sha256=<sha256> inst.creds_url=${base}/creds/${mac}.tar inst.creds_sha256=<sha256>

Archive contract: an uncompressed ustar/pax/gnu tar (the wrapper checks the ustar magic at offset 257 and feeds tar on stdin, where GNU tar refuses compressed input instead of transparently decompressing a .tar.zst into an unbounded listing) of at most 64 top-level regular files named <name>.cred, <name> matching [A-Za-z0-9][A-Za-z0-9._@~-]* (~ is systemd's own systemd.unit-dropin.<unit>~<name> credential namespace), each name at most 250 bytes, each file at most 1 MiB, the archive at most 16 MiB, and no name repeated even ignoring case (the ESP is vfat, where a.cred and A.cred are the same file). Any other member (directory, ./ prefix, symlink, hardlink, device, FIFO, path, space/control character/leading dash or dot in the name, non-.cred name, over-long or duplicate name) rejects the whole archive with a wrapper-level message before anything is extracted. Build with tar -cf <mac>.tar -C <dir> a.cred b.cred.

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 security boundary against a hostile netboot server; secrets belong in TPM2/host-key-sealed credentials.

Guarantees

  • Absent → behaviourally unchanged. Without inst.creds_url the wrapper behaves as before; the one shared change is that the ESP is now located by GPT partition type instead of "first vfat on the target" (design note 1). The commit message and in-script comment now say the same (round 1 said "byte-for-byte", which was wrong).
  • Fail closed on missing checksum, same wording as the DDI check.
  • Nothing touches the disk before both downloads verify, and nothing unverified is used. The archive is fetched right after the DDI (one shared systemd-networkd-wait-online), capped at 16 MiB (curl --max-filesize — curl ≥ 8.4 aborts a transfer of unknown length once it crosses the cap; re-checked with stat after the checksum so the bound does not depend on the curl version), sha256sum --checked, checked for the ustar magic, and only then listed — via stdin, so tar cannot auto-decompress. The tar -tv listing is validated column by column before extraction — type must be a regular file (no directories, symlinks, hardlinks, devices, FIFOs), size numeric and ≤ 1 MiB, date/time columns where GNU tar puts them (LC_ALL=C), name matching the strict pattern (which also rejects the backslash sequences --quoting-style=escape emits for a smuggled newline or other control character) and ≤ 250 bytes, no duplicate or case-colliding names, ≤ 64 members — and cross-checked against the plain tar -t listing so a column shift (e.g. an owner name with a space) is caught. Only the validated names are extracted (--no-same-owner --no-same-permissions), pinned to 0644, and re-checked as regular non-symlink files. Everything lands in /dev/shm/installer/credentials/ (tmpfs) before systemd-sysinstall runs. A bad download aborts with the target untouched.
  • Placement happens after systemd-sysinstall in the existing post-install ESP pass (stage_fallback_bootloader → finalize_target_esp): one mount -t vfat of the ESP identified by type GUID c12a7328-f81f-11d2-ba4b-00a0c93ec93b on the target disk, mkdir -p loader/credentials, cp -- "$CREDS_DIR/$name" for each validated name (never a glob over the extraction directory), sync — first, then the best-effort fallback-loader copy on the same mount, so a loader hiccup cannot abort the function with the mandatory step undone — then umount.
  • Fail closed after install too. If inst.creds_url was given and the ESP cannot be found or mounted, the wrapper exits 1 (→ FailureAction=poweroff) instead of letting an unconfigured, unreachable host reboot.
  • Credentials must be systemd-creds encrypted. systemd-stub stages ESP credentials under /run/credentials/@encrypted, so plaintext *.cred files are rejected by the consuming services (status=243/CREDENTIALS); null-key encrypted files (systemd-creds --with-key=null encrypt --name=<name> - <name>.cred) apply. The docs say so and show the commands.
  • One new tool: GNU tar (components/tar.bst, present at the pinned freedesktop-sdk-26.08.0; runtime deps glibc, symlinks, utf-locale) in installer-stack.bst, also added to the build-time tool check together with dd, rm, chmod, sync (all confirmed in the released initrd). curl, sha256sum, stat, mount, lsblk, udevadm were already there (confirmed against the released 26.08.0 initrd's file list: uutils coreutils 0.11.0, GNU grep, curl, zstd, util-linux; no sed/awk/tar).

Verification

  • tests/unit/test_installer_contract.py::test_installer_network_credentials_pull_contract — parameter parsing, mandatory-checksum wording, fetch → verify → size cap → ustar magic → listing → unpack → systemd-sysinstall ordering, tar only ever reading the archive from stdin, the 16 MiB / 64 / 250-byte / 1 MiB caps, mode and name patterns, case-insensitive duplicate check, listing cross-check, 0644 pin and regular-file re-check, ESP lookup by type GUID on a single vfat mount with per-name copies (no glob) written before the loader, fail-closed message, tar.bst in the stack and tar in the build-time tool check.
  • tests/unit/test_installer_creds_pull_behavior.py (new, 29 tests) — runs the wrapper (shared installer_wrapper fixture) under bash: bash -n, shellcheck -S warning when installed, and the fetch/verify/validate/unpack block against real tar archives with a stand-in curl. Accepted: a flat archive lands in tmpfs at 0644 regardless of archive modes/owners and the download is removed; 64 members incl. a 1 MiB member (boundary); a systemd.unit-dropin.multi-user.target~booty.cred member; a 250-byte name. Rejected without creating the credentials directory: checksum mismatch, non-.cred names, directories, ./ prefixes, symlinks, hardlinks, char/block devices, FIFOs, names with spaces / newlines / colons / leading dash / leading dot, an owner field with a space (column shift), a 1 MiB + 1 B member, 65 members, a 251-byte name, a repeated name, two names differing only by case, a 17 MiB archive, a zstd-compressed tar (rejected at the magic check; GNU tar on stdin is also shown to refuse it), empty and non-tar payloads. Not executed here: the curl-side --max-filesize (the stand-in curl ignores it; the stat re-check is executed) and finalize_target_esp (string assertions only) — stated in the module docstring. Tests skip unless GNU tar is present.
  • python3 -m pytest tests/unit -q — 383 passed, 1 xfailed (pre-existing).
  • bash -n + shellcheck -S warning on the extracted wrapper — clean.
  • python3 .github/scripts/docs-checks.py + the check-* scripts — pass.
  • End to end in QEMU (OVMF, q35/KVM, 8 GiB, 20 GiB virtio disk, single NIC) with the combined wrapper of this stack and GNU tar dropped into the released installer-v26.08.0 initrd, booted via iPXE from a Booty instance serving all four inst.* parameters: archive fetched and verified before any disk change, a 7-file *.cred archive accepted, systemd-sysinstall runs, finalize_target_esp stages the fallback loader and writes /loader/credentials/*.cred on /dev/vda1; on first boot the target logs Received untrusted credentials: firstboot.hostname, firstboot.locale, firstboot.timezone, tmpfiles.extra, …, tmpfiles.extra is applied and SSH as the provisioned operator works.
  • Not booted: the archive-hardening pass (size caps, column-by-column listing validation, cross-check, --no-same-permissions/0644 pin, per-name copy) and the --any on wait-online were added after that QEMU run from review; the happy path is behaviourally identical for a well-formed archive (the executed unit tests exercise the exact block that ships), but the current wrapper has not been re-booted. The archive-rejection paths, the ESP-not-found/unmountable failure and the wait-online timeout are unit-tested only.
  • Not run: just validate / just build-installer (no local BuildStream); the tested initrd was hand-assembled from the released one.

Two target-side observations from that run, both outside this PR: (a) null-key credentials are honoured by ImportCredential= consumers (tmpfiles, sysusers, …) but refused by PID 1 and generators (system.hostname, systemd.extra-unit.*: Operation not supported), so anything beyond those consumers needs host/TPM2-key encryption; (b) bluefin-firstboot-credentials.service fails on the released image with Failed at step EXEC spawning systemd-firstboot, so firstboot.* are no-ops there — fixed separately in fix/firstboot-credentials-binary (#254).

Design notes / questions

  1. ESP lookup by partition type. The fallback-loader pass previously took the first vfat partition on the target disk. I switched it to the ESP type GUID so the credentials cannot land on an unrelated vfat data partition on an install-alongside layout. Same partition in every layout the installer produces today; flagging it because it touches the non-PXE path.
  2. Mount reuse vs. separate pass. I reused the single existing post-install mount rather than mounting twice, so the fallback loader and the credentials share one function. Happy to split it if you prefer the bootloader staging to stay strictly best-effort and isolated.
  3. sha256sum vs. importctl. I mirrored the DDI path (curl + sha256sum --check). If you would rather move both network pulls to importctl pull-raw --verify=checksum with a SHA256SUMS, I can do that in a follow-up covering both.
  4. Encrypted-only enforcement. The wrapper checks archive shape, not contents. Should it additionally check for the systemd-creds header and refuse plaintext up front?
  5. Caps. 64 members / 1 MiB each / 16 MiB total are generous for encrypted credentials (a few KiB each) but arbitrary; happy to tune.
  6. tar as the only new dep. GNU tar was the smallest thing that reads the archive; a cpio or a DDI-wrapped credentials volume felt heavier for a handful of small files.

Review round 2

Applied from the line-by-line review:

  • Name regex allows ~ (systemd.unit-dropin.<unit>~<name>.cred is systemd's own namespace), with a positive test.
  • Name length capped at 250 bytes (tar ENAMETOOLONG at 256 and vfat's 255 previously produced tar's error mid-extraction, or a cp failure after the install); 250 accepted / 251 rejected tests.
  • Duplicate and case-colliding names rejected pre-extraction (a repeated name made tar -x die half-way with tar's message; A.cred+a.cred silently overwrote each other on the vfat ESP); tests for both.
  • Compressed archives rejected: ustar magic check at offset 257 plus tar reading from stdin (GNU tar auto-decompresses only a named file, so a .tar.zst could expand a 16 MiB download into gigabytes of listing held in bash variables); this also bounds the listing to ≤ 32768 entries. Test with a real zstd-compressed tar, and a check that stdin tar refuses it even without the magic check.
  • Wording: "byte-for-byte unchanged" → "behaviourally unchanged apart from the ESP lookup by GPT type" in the commit body and in-script comment; --max-filesize comment updated for curl ≥ 8.4; inst.creds_url=<url> (not <https-url>).
  • Test honesty: module docstring and this body state that the curl cap and finalize_target_esp are not executed by unit tests; tests skip unless GNU tar.
  • Ordering: credentials are copied to the ESP before the best-effort loader cp -a, so the mandatory step cannot be aborted by the optional one.
  • Docs contract paragraph: ~, 250-byte limit, duplicates/case, compression rejection, trust-model sentence; ddi-installer.md is now 330 lines (docs-checks WARN, non-fatal — a split is a follow-up).
  • Skipped: --numeric-owner on the listing (the owner-field class is already caught by the size regex and the -t cross-check, both tested); head -n 65 on the listing (unnecessary once compression is rejected — the on-disk 16 MiB cap bounds an uncompressed listing); set -f around the for arg in ${CMDLINE} loop (pre-existing, shared with inst.ddi_url); printing only the URL host (same as the DDI path); -gt 0 on member size (systemd rejects empty creds itself).
  • Round-1 CI build (run 36259019391) passed; the new build is running.

@jeefy
jeefy force-pushed the feat/installer-creds-url branch 2 times, most recently from fd7bc14 to 7b7af16 Compare September 26, 2026 19:36
jeefy added a commit that referenced this pull request Sep 26, 2026
…254)

## Problem

On the installed image `bluefin-firstboot-credentials.service` fails on every boot that carries a `firstboot.*` credential:

```text
bluefin-firstboot-credentials.service: Failed at step EXEC spawning systemd-firstboot: No such file or directory
```

so `firstboot.locale`, `firstboot.locale-messages`, `firstboot.keymap`, `firstboot.timezone` and `firstboot.hostname` are silent no-ops — including the ones `systemd-sysinstall` itself propagates from the installer environment (locale/keymap/timezone, see the "Propagates installer environment settings" bullet in `ddi-installer.md`). Observed in QEMU on the installed `installer-v26.08.0` image with credentials staged on the ESP (`Received untrusted credentials: firstboot.hostname, firstboot.locale, firstboot.timezone, …` followed by the EXEC failure). Found while integrating with the [jeefy/booty](https://github.com/jeefy/booty) PXE server, which delivers `firstboot.hostname` per host.

## Root cause

The unit runs `ExecStart=systemd-firstboot --force --welcome=no`, written when the OS payload was FSDK's systemd. #132 cut the payload over to Flatcar's `/usr` (`flatcar-usr.bst`), and **Flatcar builds systemd without `systemd-firstboot`**: `flatcar-container.tar.gz` for 4593.2.5 contains neither `/usr/bin/systemd-firstboot` nor `systemd-firstboot.service` (verified by listing the archive; the `ln -sf /dev/null …/systemd-firstboot.service` mask in `bluefin-server-ddi.bst` is therefore a no-op too, harmless). `installer-stack.bst` still has FSDK's systemd with `systemd-firstboot`, which is why the *installer* side works and the *target* side does not.

## Fix

Replace the binary with `/usr/libexec/bluefin-firstboot-credentials`, a bash + coreutils helper (both shipped by Flatcar), staged by `os-creds-prov.bst`. It reads the five credentials from `$CREDENTIALS_DIRECTORY`, validates them at least as strictly as systemd's validators (`hostname_is_valid`-style: labels `[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?`, no leading/trailing hyphen, ≤ 64 chars total; timezone must match `[A-Za-z0-9_+-]+(/…)*` **and** exist under `/usr/share/zoneinfo`; locale/keymap restricted to safe characters and < 128 bytes like `locale_is_valid()`/`keymap_is_valid()`; everything ASCII-only under `export LC_ALL=C`, since PID 1 exports the `LANG` this helper itself writes and `[[:alnum:]]` would otherwise widen with it; a NUL byte in a credential is rejected rather than silently dropped by `$(<file)`), and writes the same files `systemd-firstboot` would, in the same format — plus `/etc/hostname`. On `firstboot.hostname`: systemd ≤ v259 (Flatcar 4593.2.5 ships 257.9) has no such credential; systemd v260 added it as a *static* hostname honoured only when none is set yet, whereas this helper applies it unconditionally and additionally sets the live kernel hostname (systemd's own transient hostname credential remains `system.hostname`, consumed by PID 1):

| credential | file |
|---|---|
| `firstboot.locale` / `firstboot.locale-messages` | `/etc/locale.conf` (`LANG=` / `LC_MESSAGES=`) |
| `firstboot.keymap` | `/etc/vconsole.conf` (`KEYMAP=`) |
| `firstboot.timezone` | `/etc/localtime -> ../usr/share/zoneinfo/<tz>` |
| `firstboot.hostname` | `/etc/hostname` + live kernel hostname (`/proc/sys/kernel/hostname`) so the first DHCP request carries it — new relative to `main` (the old `ExecStartPost` set the kernel hostname but never persisted `/etc/hostname`); semantics differ from systemd v260's (always applied, not only when no static hostname exists) |

Any invalid value fails the run **before** anything is written (unit fails visibly, stamp file not created; control characters in the rejected value are `%q`-quoted in the log). The helper `sync`s before exiting so the `ExecStartPost` stamp cannot outlive the files on power loss. The unit's ordering, conditions, `ImportCredential=` lines and the `/etc/.bluefin-firstboot-credentials` stamp are unchanged; the old `ExecStartPost` hostname one-liner folds into the helper. Shebang is `/usr/bin/bash` so EXEC does not depend on the tmpfiles-created `/bin` symlink. `--root=DIR` exists for tests only.

Known, deliberate differences from `systemd-firstboot` (stated in the helper's header): trailing newlines in a credential are stripped rather than rejected; `LC_MESSAGES=` is written even when it equals `LANG=`; locales/keymaps are shape-checked, not checked against what is installed (Flatcar ships the full zoneinfo, so the timezone existence check is real).

### Why not ship the binary

Pulling FSDK's `systemd-firstboot` into the Flatcar `/usr` was the other option and was rejected: it links `libsystemd-shared-<ver>.so` from a different systemd build, so it would drag a second libsystemd-shared into the image and reintroduce exactly the FSDK/Flatcar userspace split #132 removed. The helper is ~100 lines with no dependencies beyond what the payload already has, and follows the precedent of #246's `files/os/libexec/bluefin-root-cred-sync`.

## Verification

- `tests/unit/test_credentials_provisioning.py` — unit no longer names `systemd-firstboot`, `ExecStart` points at the helper and precedes the stamp; element stages `files/os/libexec` and installs the helper 0755.
- `tests/unit/test_firstboot_credentials_behavior.py` (new, 26 tests) — executes the helper against a scratch `--root`: all five credentials produce the exact files above; a subset writes only its files; `--force`-style overwrite of existing `/etc/hostname` and `/etc/localtime`; interior hyphens/digits in labels accepted; twelve invalid inputs (`bad host`, `-leading`, `trailing-`, `foo-.bar`, `foo..bar`, `hôte`, `host\r`, 65-char hostname, `../../etc/passwd` and unknown timezone, shell metacharacters in locale, `..` in keymap) exit 1 with a named error and write **nothing**; a non-ASCII **keymap/locale** (`[[:alnum:]]` regexes) is rejected with `LC_ALL=C.UTF-8`/`LANG=C.UTF-8` in the environment — this test **fails when `export LC_ALL=C` is removed from the helper** (verified by mutation; the round-1 hostname variant did not, because `[A-Za-z0-9]` does not widen under `C.UTF-8`); 127-byte keymap accepted / 128 rejected; locale-only and messages-only `locale.conf`; invalid `locale-messages`; a NUL byte; the CR case logs `$'host\r'`; empty credential treated as absent; missing and nonexistent `CREDENTIALS_DIRECTORY` are errors; `bash -n`; `shellcheck -S warning` (skipped visibly, not silently passed, when shellcheck is absent — CI's `unit-tests.yml` does not install it).
- `python3 -m pytest tests/unit -q` — 371 passed, 1 xfailed (pre-existing). `test_files_payload_reachability` confirms the new `files/os/libexec/` path is staged.
- `python3 .github/scripts/docs-checks.py` + the `check-*` scripts — pass.
- Not run: `just validate` / `just build-ddi` (no local BuildStream) and a rebuilt-image boot. The helper has only been exercised by the executed unit tests against a scratch `--root`; a first boot with `firstboot.*` credentials on a rebuilt DDI is the remaining proof and I am happy to run it against a CI artefact.

Docs: `ddi-installer.md` describes what the unit actually runs and writes (same files as `systemd-firstboot` plus the hostname handling, with the ≤ v259 / v260 distinction); `tpm2-credential-sealing.md` drops `systemd-firstboot` as a consumer of `passwd.hashed-password.root`.

No relation to the installer PR stack (#250, #251, #252, #253); no textual or compose overlap with #246 (`bluefin-root-cred-sync` is installed from a separate element).
jeefy and others added 4 commits September 26, 2026 16:20
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=<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=<hex> 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 <name>.cred with <name> matching [A-Za-z0-9][A-Za-z0-9._@~-]*
(~ is systemd's own systemd.unit-dropin.<unit>~<name> 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>
…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>
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.<unit>~<name>.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>
…lidated

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 <name>.cred with
<name> 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>
@jeefy
jeefy force-pushed the feat/installer-creds-url branch from 7b7af16 to 9ef3068 Compare September 26, 2026 21:20
@jeefy
jeefy merged commit 452503a into projectbluefin:main Sep 26, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant