diff --git a/.gitea/workflows/gitea-main-ci.yaml b/.gitea/workflows/gitea-main-ci.yaml
index ab576f4..7349621 100644
--- a/.gitea/workflows/gitea-main-ci.yaml
+++ b/.gitea/workflows/gitea-main-ci.yaml
@@ -8,19 +8,24 @@
# shell-local post-processors extract artifacts, build the UKI (ukify), and
# build+push the OCI release image.
#
-# Signed when the SB_KEY/SB_CERT secrets are set; otherwise an UNSIGNED (lab)
-# build where build-oci.sh emits its loud unsigned-UKI warning. Signing runs
-# shell-local on the runner (not in the build VM); the key is staged to
-# RUNNER_TEMP and shredded after. See docs/secure-boot-keys.md.
+# This is the PRODUCTION build profile and it FAILS CLOSED (POA&M P-03): a
+# "Production build gate" step aborts the run unless SB_KEY, SB_CERT and FLEET_CA
+# are set — there is no unsigned fallback and no placeholder fleet CA. STIG
+# hardening is mandatory (enforced by the Packer template's variable validation).
+# Signing runs shell-local on the runner (not in the build VM); the key is staged
+# to RUNNER_TEMP and shredded after. See docs/secure-boot-keys.md.
#
# Required Gitea repo secrets:
# REGISTRY_USERNAME - registry user for `oci_image` (oci_push=true)
# REGISTRY_TOKEN - registry password/token
# SSH_AUTHORIZED_KEY - public key for the sudo admin user; empty => no admin
# user + root left unlocked (lab). Set it to lock root.
-# SB_KEY, SB_CERT - Secure Boot signing: the `db` PRIVATE key (PEM) + its
-# cert (PEM). Empty => unsigned lab build. PK/KEK are NOT
-# here (offline/HSM). Generate per docs/secure-boot-keys.md.
+# SB_KEY, SB_CERT - REQUIRED. Secure Boot signing: the `db` PRIVATE key (PEM)
+# + its cert (PEM). PK/KEK are NOT here (offline/HSM).
+# Generate per docs/secure-boot-keys.md. Missing => build fails.
+# FLEET_CA - REQUIRED. Real fleet step-ca root PEM baked to
+# radius-ca.pem (RADIUS EAP-TLS + fleet-agent verify).
+# Missing => build fails.
#
# Runner: needs KVM (qemu accelerator=kvm) and the build-host tooling installed
# below (libguestfs, erofs-utils, cryptsetup, jq, ukify, buildah).
@@ -147,6 +152,36 @@ jobs:
echo "image_version=${version}" >> "$GITHUB_OUTPUT"
echo "Building image_version=${version}"
+ -
+ name: Production build gate (fail closed on missing security material)
+ # POA&M P-03 / F-01 (poam-hardening): the pipeline is the production build
+ # profile, so it FAILS CLOSED. There is no unsigned fallback and no
+ # placeholder fleet CA — the three security-critical secrets MUST be set:
+ # SB_KEY / SB_CERT Secure Boot `db` signing material (signed UKI)
+ # FLEET_CA real fleet step-ca root baked to radius-ca.pem
+ # (RADIUS EAP-TLS trust anchor + fleet-agent verify)
+ # enable_stig is enforced true by the Packer template itself (variable
+ # validation); it is asserted here too so a misconfigured ENABLE_STIG env
+ # fails before the ~17-min VM build rather than during it.
+ env:
+ SB_KEY: ${{ secrets.SB_KEY }}
+ SB_CERT: ${{ secrets.SB_CERT }}
+ FLEET_CA: ${{ secrets.FLEET_CA }}
+ run: |
+ miss=0
+ for v in SB_KEY SB_CERT FLEET_CA; do
+ if [ -z "${!v}" ]; then
+ echo "::error::required secret ${v} is empty — production builds are signed with a real fleet CA (no fallback). Set it in the Gitea repo secrets."
+ miss=1
+ fi
+ done
+ if [ "${ENABLE_STIG}" != "true" ]; then
+ echo "::error::ENABLE_STIG must be 'true' — production builds are hardening-mandatory (POA&M P-03)."
+ miss=1
+ fi
+ [ "$miss" = 0 ] || exit 1
+ echo "Production gate passed: SB_KEY, SB_CERT, FLEET_CA present; STIG enabled."
+
-
name: Install build-host tooling
# Tools the shell-local post-processors run on the RUNNER (not the VM):
@@ -197,7 +232,7 @@ jobs:
go-version: '1.26.4'
-
- name: Build host Go binaries out-of-VM (fleet-enrol, fleet-hostapi, fleet-agent)
+ name: Build host Go binaries out-of-VM (fleet-enrol, fleet-hostapi, fleet-agent, fleet-ssh-hostcert)
# Built HERE on the runner, NOT inside the Packer VM, so the Rocky build
# image never carries the Go toolchain or the go-tpm dep tree. Packer
# file-provisions the resulting static binaries into the rootfs. Runs
@@ -223,7 +258,11 @@ jobs:
&& CGO_ENABLED=0 GOTOOLCHAIN=local \
go build -trimpath -buildvcs=false -ldflags '-s -w -buildid=' -o bin/fleet-agent . \
&& CGO_ENABLED=0 go vet ./... && CGO_ENABLED=0 go test ./... )
- file files/enrol/bin/fleet-enrol files/hostapi/bin/fleet-hostapi files/agent/bin/fleet-agent
+ ( cd files/ssh-hostcert \
+ && CGO_ENABLED=0 GOTOOLCHAIN=local \
+ go build -trimpath -buildvcs=false -ldflags '-s -w -buildid=' -o bin/fleet-ssh-hostcert . \
+ && CGO_ENABLED=0 go vet ./... && CGO_ENABLED=0 go test ./... )
+ file files/enrol/bin/fleet-enrol files/hostapi/bin/fleet-hostapi files/agent/bin/fleet-agent files/ssh-hostcert/bin/fleet-ssh-hostcert
-
name: TPM ceremony + agent mTLS tests (go-tpm software simulator)
@@ -265,9 +304,8 @@ jobs:
# signing post-processor runs shell-local on THIS runner (not in the build
# VM), so write the secrets to runner-temp files and pass their paths. The
# `db` PRIVATE key is the only signing key here; PK/KEK stay offline (see
- # docs/secure-boot-keys.md). If SB_KEY is unset, this no-ops and the build
- # falls back to an UNSIGNED lab UKI (the loud warning stays).
- if: ${{ secrets.SB_KEY != '' }}
+ # docs/secure-boot-keys.md). Presence is guaranteed by the Production build
+ # gate above (fail-closed) — there is no unsigned fallback.
env:
SB_KEY: ${{ secrets.SB_KEY }} # db private key (PEM) — secret
SB_CERT: ${{ secrets.SB_CERT }} # db cert (PEM) — public, kept as a secret for convenience
@@ -284,10 +322,9 @@ jobs:
name: Materialize fleet CA (radius-ca.pem trust anchor)
# The real fleet step-ca root is baked to /etc/dot1x/radius-ca.pem (RADIUS
# EAP-TLS + fleet-agent server-verify). Written to a runner-temp FILE and
- # passed as a build-host PATH (var.fleet_ca). If FLEET_CA is unset this
- # no-ops and the build falls back to the committed PLACEHOLDER (auth cannot
- # succeed — lab only). Never commit real internal CA material (CLAUDE.md).
- if: ${{ secrets.FLEET_CA != '' }}
+ # passed as a build-host PATH (var.fleet_ca). Presence is guaranteed by the
+ # Production build gate above (fail-closed) — the committed placeholder is
+ # NOT a usable fallback here. Never commit real internal CA material (CLAUDE.md).
env:
FLEET_CA: ${{ secrets.FLEET_CA }} # fleet step-ca root PEM (root, or root+intermediate)
run: |
@@ -318,9 +355,10 @@ jobs:
-
name: packer build (UKI + OCI release image)
- # Signed when SB_KEY/SB_CERT secrets are set (paths exported above);
- # UNSIGNED lab build (loud warning) when they're empty. sb_key/sb_cert are
- # PATHS, never values — see the materialize step and docs/secure-boot-keys.md.
+ # Always a SIGNED build: SB_KEY/SB_CERT/FLEET_CA presence is enforced by the
+ # Production build gate, and enable_stig=true is enforced by the template's
+ # variable validation. sb_key/sb_cert are PATHS, never values — see the
+ # materialize step and docs/secure-boot-keys.md.
run: |
packer build -color=false -on-error=abort \
-var image_version="${{ steps.vars.outputs.image_version }}" \
@@ -330,9 +368,9 @@ jobs:
-var disable_dot1x=${{ env.DISABLE_DOT1X }} \
-var nvmet_traddr="${{ env.NVMET_TRADDR }}" \
-var ssh_authorized_key="${{ secrets.SSH_AUTHORIZED_KEY }}" \
- -var sb_key="${SB_KEY_FILE:-}" \
- -var sb_cert="${SB_CERT_FILE:-}" \
- -var fleet_ca="${FLEET_CA_FILE:-files/etc/dot1x/radius-ca.pem}" \
+ -var sb_key="${SB_KEY_FILE}" \
+ -var sb_cert="${SB_CERT_FILE}" \
+ -var fleet_ca="${FLEET_CA_FILE}" \
-var kiosk_url="${{ env.KIOSK_URL }}" \
-var boot_splash=${{ env.BOOT_SPLASH }} \
-var enable_stig=${{ env.ENABLE_STIG }} \
diff --git a/.gitea/workflows/ipxe-image.yaml b/.gitea/workflows/ipxe-image.yaml
index fc12dcd..43c4a20 100644
--- a/.gitea/workflows/ipxe-image.yaml
+++ b/.gitea/workflows/ipxe-image.yaml
@@ -22,9 +22,10 @@
#
# Runs only when the iPXE inputs change (path filter) or on demand.
#
-# Required Gitea repo secrets: PACKAGE_USER, PACKAGE_TOKEN (registry creds).
-# Optional: SB_KEY, SB_CERT (db PRIVATE key + cert, PEM). Unset => UNSIGNED lab
-# image (loud warning; Secure-Boot-enforcing hosts will reject it). PK/KEK
+# Required Gitea repo secrets: PACKAGE_USER, PACKAGE_TOKEN (registry creds),
+# SB_KEY, SB_CERT (db PRIVATE key + cert, PEM). SB_KEY/SB_CERT are REQUIRED —
+# a "Production build gate" fails the run if either is unset (no unsigned
+# fallback; POA&M P-03). Enforcing hosts reject an unsigned snponly.efi. PK/KEK
# never come near CI — only `db` signs (docs/secure-boot-keys.md).
#
@@ -104,12 +105,31 @@ jobs:
echo "push_latest=$push_latest" >> "$GITHUB_OUTPUT"
echo "Using snponly.efi=$SNP tag=$VER (ipxe pkg $RAW, latest=$push_latest)"
+ -
+ name: Production build gate (fail closed on missing signing material)
+ # POA&M P-03 (poam-hardening): the signed iPXE bootloader is a production
+ # Secure-Boot artifact — an unsigned snponly.efi is rejected by enforcing
+ # hosts and defeats the chain of trust. SB_KEY/SB_CERT MUST be set; there
+ # is no unsigned fallback. (FLEET_CA is N/A — iPXE carries no fleet CA.)
+ env:
+ SB_KEY: ${{ secrets.SB_KEY }}
+ SB_CERT: ${{ secrets.SB_CERT }}
+ run: |
+ miss=0
+ for v in SB_KEY SB_CERT; do
+ if [ -z "${!v}" ]; then
+ echo "::error::required secret ${v} is empty — the fleet-ipxe bootloader must be signed (no unsigned fallback). Set it in the Gitea repo secrets."
+ miss=1
+ fi
+ done
+ [ "$miss" = 0 ] || exit 1
+ echo "Production gate passed: SB_KEY, SB_CERT present."
+
-
name: Materialize Secure Boot signing material
# Same db key that signs the UKI; written to a runner-temp file and passed
- # to build-ipxe-oci.sh as a path. If SB_KEY is unset this no-ops and the
- # build produces an UNSIGNED (lab) image with its loud warning.
- if: ${{ secrets.SB_KEY != '' }}
+ # to build-ipxe-oci.sh as a path. Presence is guaranteed by the Production
+ # build gate above (fail-closed) — there is no unsigned fallback.
env:
SB_KEY: ${{ secrets.SB_KEY }}
SB_CERT: ${{ secrets.SB_CERT }}
@@ -140,8 +160,8 @@ jobs:
"${{ steps.src.outputs.snponly }}" \
"${IPXE_IMAGE}" \
"$VER" \
- "${SB_KEY_FILE:-}" \
- "${SB_CERT_FILE:-}" \
+ "${SB_KEY_FILE}" \
+ "${SB_CERT_FILE}" \
true
# main / release tags also move :latest; dev branches never clobber it.
if [ "${{ steps.src.outputs.push_latest }}" = "true" ]; then
diff --git a/.gitignore b/.gitignore
index dccc3ad..e384609 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,3 +20,4 @@ keys
files/enrol/bin/
files/hostapi/bin/
files/agent/bin/
+files/ssh-hostcert/bin/
diff --git a/diskless.pkr.hcl b/diskless.pkr.hcl
index eb35a47..9dca771 100644
--- a/diskless.pkr.hcl
+++ b/diskless.pkr.hcl
@@ -136,6 +136,12 @@ variable "enable_agent" {
default = true
}
+variable "enable_ssh_hostcert" {
+ type = bool
+ description = "Build-time feature flag for the SSH host-certificate client (fleet-ssh-hostcert: at boot, gets this host's per-boot SSH host key signed by the fleet SSH CA via the enrol-broker host plane over TPM-identity mTLS, so admins trust every host via one `@cert-authority` line instead of per-boot TOFU; closes F-02/P-17, docs/ssh-host-certificate-design.md). true (default) installs /usr/local/bin/fleet-ssh-hostcert + ssh-hostcert.service/.timer; false skips it (sshd still boots with its per-boot key). Config is fleet-generic in files/ssh-hostcert/ssh-hostcert.env; set the broker DNS name there per environment."
+ default = true
+}
+
variable "boot_splash" {
type = bool
description = "true (default): bake 'rhgb quiet' into the UKI cmdline so Plymouth shows a graphical boot splash (covers the network-auth + NVMe/TCP + verity phase). false: bake 'plymouth.enable=0' for a fully verbose console boot — use while debugging the boot chain. Plymouth itself is always in the image; this only flips the cmdline. (The cmdline is immutable once signed, so this is a build-time choice.)"
@@ -144,14 +150,12 @@ variable "boot_splash" {
variable "enable_stig" {
type = bool
- description = "true (default): apply DISA STIG hardening (OpenSCAP + SSG) with a diskless/UKI/kiosk tailoring (files/stig/diskless-tailoring.xml), bake STIG kernel params into the UKI cmdline, and emit a deviations report. false: skip hardening entirely — escape hatch if a build regresses the boot/secure-path bench. FIPS is OFF and audit offload is LOCAL-only regardless (see docs/stig-deviations.md)."
- default = true
-}
-
-variable "debug_shell" {
- type = bool
- description = "DEBUG/LAB ONLY. true: enable systemd's debug-shell.service — a passwordless root /bin/sh on tty2 (Ctrl+Alt+F2) that bypasses login/PAM entirely. (Placed on tty2, with the login getty there masked, because constrained consoles often expose only tty1-6; tty1 stays the kiosk.) Use to get into a hardened image when login is broken (locked root + key-only accounts). This is a deliberate security hole; NEVER ship it. Default false."
+ description = "MUST be true (enforced). Applies DISA STIG hardening (OpenSCAP + SSG) with a diskless/UKI/kiosk tailoring (files/stig/diskless-tailoring.xml), bakes STIG kernel params into the UKI cmdline, and emits a deviations report. FIPS is OFF and audit offload is LOCAL-only regardless (see docs/stig-deviations.md). The former enable_stig=false escape hatch is removed for production hardening (POA&M P-03) — a build with enable_stig=false now fails validation. To debug a hardening regression, revert this validation on a throwaway branch, never on a release build."
default = true
+ validation {
+ condition = var.enable_stig
+ error_message = "STIG hardening is mandatory: enable_stig must be true. Production builds are hardening-mandatory (POA&M P-03); there is no unhardened build path, so do not set enable_stig=false on a release build."
+ }
}
variable "audit_host" {
@@ -294,6 +298,19 @@ build {
destination = "/tmp/fleet-agent"
}
+ # SSH host-certificate client: the systemd unit + timer AND the baked
+ # fleet-generic config (ssh-hostcert.env) ride this module upload to
+ # /tmp/ssh-hostcert (installed in the 2b-ssh-hostcert step, after /tmp/etc-stage
+ # is cleaned — same reason as the agent). Static binary staged separately below.
+ provisioner "file" {
+ source = "files/ssh-hostcert"
+ destination = "/tmp/"
+ }
+ provisioner "file" {
+ source = "files/ssh-hostcert/bin/fleet-ssh-hostcert"
+ destination = "/tmp/fleet-ssh-hostcert"
+ }
+
# Custom 'fleet' Plymouth theme (scripted security-handshake splash). Staged to
# /tmp/plymouth, installed + set default in the package step before dracut runs.
provisioner "file" {
@@ -694,6 +711,37 @@ build {
]
}
+ # --- 2b-ssh-hostcert. SSH host-certificate client (Go, TPM-authenticated) --
+ # Installs the OUT-OF-VM-built /usr/local/bin/fleet-ssh-hostcert (staged to
+ # /tmp/fleet-ssh-hostcert) + its systemd unit + renewal timer + baked,
+ # fleet-generic config. At boot it gets this host's PER-BOOT SSH host key signed
+ # by the fleet SSH CA via the enrol-broker host plane (TPM-identity mTLS), so
+ # admins trust every host via one `@cert-authority` line instead of TOFU on a key
+ # that changes each boot (closes F-02 / POA&M P-17; docs/ssh-host-certificate-design.md).
+ # NOTHING host-specific is baked (invariant #1) — the broker DNS name in
+ # ssh-hostcert.env is fleet-generic; the host identity comes from the TPM at
+ # runtime (same 0x81000100 key / 0x01800100 cert as 802.1X + the agent). We
+ # enable the TIMER (not the service) so it fires at boot + renews. Gated on
+ # enable_ssh_hostcert. The binary is fapolicyd-trusted in 2c-STIG-postfix
+ # (non-RPM exec, like hostapi/agent/kiosk-session).
+ provisioner "shell" {
+ environment_vars = [
+ "ENABLE_SSH_HOSTCERT=${var.enable_ssh_hostcert}",
+ ]
+ inline = [
+ "set -euxo pipefail",
+ "if [ \"$ENABLE_SSH_HOSTCERT\" != \"true\" ]; then echo 'enable_ssh_hostcert=false -> skipping fleet-ssh-hostcert install.'; exit 0; fi",
+ "install -D -m0755 /tmp/fleet-ssh-hostcert /usr/local/bin/fleet-ssh-hostcert",
+ "install -D -m0644 /tmp/ssh-hostcert/ssh-hostcert.service /etc/systemd/system/ssh-hostcert.service",
+ "install -D -m0644 /tmp/ssh-hostcert/ssh-hostcert.timer /etc/systemd/system/ssh-hostcert.timer",
+ "install -D -m0644 /tmp/ssh-hostcert/ssh-hostcert.env /etc/ssh-hostcert/ssh-hostcert.env",
+ "restorecon -R /usr/local/bin/fleet-ssh-hostcert /etc/systemd/system/ssh-hostcert.service /etc/systemd/system/ssh-hostcert.timer /etc/ssh-hostcert 2>/dev/null || true",
+ "systemctl enable ssh-hostcert.timer",
+ "rm -rf /tmp/ssh-hostcert /tmp/fleet-ssh-hostcert",
+ "echo '==> fleet-ssh-hostcert enabled (SSH host cert from the fleet SSH CA; timer at boot + renew)'",
+ ]
+ }
+
# --- 2c. Admin access: sudo-enabled key user + locked root --------------
# Fleet-generic (same user + key on every host => NOT per-host state). The
# key comes from var.ssh_authorized_key (CI secret). If no key is supplied we
@@ -727,7 +775,7 @@ build {
# unaffected.
# Banner: show the fleet (starship) login notice pre-auth. The banner file
# itself is written by the '2e. Fleet login banner' step below (after STIG,
- # so it overrides the DoD banner). Set here too so it works with enable_stig=false.
+ # so it overrides the DoD banner). Set here too as a pre-STIG baseline.
"printf 'PermitRootLogin no\\nPasswordAuthentication no\\nKbdInteractiveAuthentication no\\nBanner /etc/issue.net\\n' > /etc/ssh/sshd_config.d/50-fleet-hardening.conf",
"chmod 0644 /etc/ssh/sshd_config.d/50-fleet-hardening.conf",
"restorecon /etc/ssh/sshd_config.d/50-fleet-hardening.conf",
@@ -742,34 +790,13 @@ build {
]
}
- # --- 2c-debug. Break-glass root shell (DEBUG/LAB ONLY) -------------------
- # debug_shell=true enables systemd's debug-shell.service: a passwordless root
- # /bin/sh on tty9 (Ctrl+Alt+F9) that does NOT go through login/PAM — so you can
- # get into a hardened image even when root is locked, the accounts are key-only,
- # and login/sshd are broken. This is a deliberate security hole for diagnosing
- # boot/login regressions; never ship it. The symlink into sysinit.target.wants
- # guarantees it starts early regardless of the unit's [Install] section.
- provisioner "shell" {
- environment_vars = ["DEBUG_SHELL=${var.debug_shell}"]
- inline = [
- "set -e",
- "if [ \"$DEBUG_SHELL\" != \"true\" ]; then echo 'debug_shell=false -> no debug shell baked.'; exit 0; fi",
- "echo '############################################################'",
- "echo '## WARNING: debug_shell=true — PASSWORDLESS ROOT on tty2. ##'",
- "echo '## DEBUG/LAB IMAGE ONLY. Do NOT deploy to production. ##'",
- "echo '############################################################'",
- "systemctl enable debug-shell.service 2>/dev/null || true",
- "mkdir -p /etc/systemd/system/sysinit.target.wants",
- "ln -sf /usr/lib/systemd/system/debug-shell.service /etc/systemd/system/sysinit.target.wants/debug-shell.service",
- # Default debug-shell is tty9 (outside the getty range) — but constrained
- # consoles (noVNC/SPICE) often only expose tty1-6. Move it to tty2, which
- # IS reachable, and mask the login getty there so they don't fight over the
- # VT. Result: Ctrl+Alt+F2 = passwordless root shell. (tty1 stays the kiosk.)
- "mkdir -p /etc/systemd/system/debug-shell.service.d",
- "printf '[Service]\\nTTYPath=/dev/tty2\\n' > /etc/systemd/system/debug-shell.service.d/tty.conf",
- "systemctl mask getty@tty2.service autovt@tty2.service 2>/dev/null || true",
- ]
- }
+ # --- 2c-debug REMOVED (POA&M P-02 / R-02) -------------------------------
+ # The break-glass systemd debug-shell.service (passwordless root on a tty,
+ # bypassing login/PAM) is no longer part of any build. It was an undocumented
+ # privileged access path flagged High-risk in the A&A (irap-poam.md P-02,
+ # ssp.md R-02). There is intentionally NO debug_shell variable and NO provisioner
+ # that enables debug-shell.service. To diagnose a boot/login regression, use a
+ # throwaway branch/serial console — never reintroduce a shipped root shell.
# --- 2c-STIG. DISA STIG hardening (OpenSCAP + SSG), diskless/UKI/kiosk tailored
# Runs after admin (so it hardens the full system incl. the admin/sshd config)
@@ -789,7 +816,10 @@ build {
]
inline = [
"set -e",
- "if [ \"$ENABLE_STIG\" != \"true\" ]; then echo 'enable_stig=false -> skipping STIG hardening.'; mkdir -p /root; echo 'STIG hardening disabled for this build (enable_stig=false).' > /root/stig-report.html; : > /root/stig-arf.xml; exit 0; fi",
+ # enable_stig is enforced true by variable validation (POA&M P-03). This is
+ # a fail-closed backstop: if STIG were ever somehow disabled we abort the
+ # build rather than silently ship an unhardened image masquerading as one.
+ "if [ \"$ENABLE_STIG\" != \"true\" ]; then echo 'FATAL: ENABLE_STIG != true — production builds are hardening-mandatory (no unhardened path).' >&2; exit 1; fi",
"echo '==> Installing OpenSCAP + SCAP Security Guide'",
"dnf install -y openscap-scanner scap-security-guide",
# Pick the datastream that MATCHES THIS DISTRO. The RHEL9 datastream's CPE
@@ -855,8 +885,8 @@ build {
# sysadm_u) so SSH login isn't gated by the ssh_sysadm_login bool.
# ⚠ BENCH-VERIFY: admin SSH login succeeds AND `sudo` works AND every
# privileged op the admin needs runs under the sysadm_t transition. If
- # this locks the admin out, enable_stig=false is the escape hatch and
- # this rule reverts to a justified deviation. ⚠ REPRODUCIBILITY: confirm
+ # this locks the admin out, revert this rule to a justified deviation in
+ # the tailoring (NOT by disabling STIG — that path is gone). ⚠ REPRODUCIBILITY: confirm
# the verity hash is stable across two builds — semanage rebuilds the
# SELinux policy store and may write nondeterministic content; if it
# drifts, normalize in 2d.
@@ -876,8 +906,8 @@ build {
# GUARD: a scan with 0 evaluated rules (everything notapplicable/notselected)
# means the datastream/CPE didn't match this host — NO hardening happened and
# the report would be falsely 'clean'. Fail the build rather than ship an
- # unhardened image masquerading as STIG-compliant. (enable_stig=false is the
- # intentional way to skip hardening.)
+ # unhardened image masquerading as STIG-compliant. (There is no skip-hardening
+ # path — enable_stig is enforced true, POA&M P-03.)
"evaluated=$(grep -oE '(pass|fixed|fail)' /root/stig-arf.xml | wc -l)",
"[ \"$evaluated\" -gt 0 ] || { echo 'ERROR: STIG scan evaluated 0 rules (all notapplicable/notselected) — SSG datastream/CPE mismatch for this distro. Hardening did NOT run; aborting.' >&2; exit 1; }",
"echo \"==> STIG scan evaluated $evaluated rules (pass/fixed/fail)\"",
@@ -960,7 +990,8 @@ build {
]
inline = [
"set -e",
- "if [ \"$ENABLE_STIG\" != \"true\" ]; then echo '2c-STIG-postfix: enable_stig=false -> nothing to undo.'; exit 0; fi",
+ # enable_stig is enforced true (POA&M P-03); fail closed if it ever isn't.
+ "if [ \"$ENABLE_STIG\" != \"true\" ]; then echo 'FATAL: 2c-STIG-postfix reached with ENABLE_STIG != true.' >&2; exit 1; fi",
# Exempt each appliance account from password aging/inactivity/expiry and
# clear any faillock tally (these accounts have NO password to age).
"for u in \"$ADMIN_USER\" kiosk; do",
@@ -1001,9 +1032,9 @@ build {
# provide). Can drop lower after measuring `fapolicyd-cli --dump | wc -l` on
# the bench; see docs/TODO.md.
" if [ -f /etc/fapolicyd/fapolicyd.conf ]; then sed -ri 's/^[[:space:]]*#?[[:space:]]*db_max_size[[:space:]]*=.*/db_max_size = 50/' /etc/fapolicyd/fapolicyd.conf; grep -q '^db_max_size' /etc/fapolicyd/fapolicyd.conf || printf 'db_max_size = 50\\n' >> /etc/fapolicyd/fapolicyd.conf; echo '==> fapolicyd: db_max_size set to 50 MiB (was EL9 default ~100)'; fi",
- " for f in /usr/local/bin/kiosk-session /usr/local/bin/fleet-sb-enroll /usr/local/bin/fleet-hostapi /usr/local/bin/fleet-agent /usr/sbin/fleet-enrol; do { [ -f \"$f\" ] && fapolicyd-cli --file add \"$f\"; } || true; done",
+ " for f in /usr/local/bin/kiosk-session /usr/local/bin/fleet-sb-enroll /usr/local/bin/fleet-hostapi /usr/local/bin/fleet-agent /usr/local/bin/fleet-ssh-hostcert /usr/sbin/fleet-enrol; do { [ -f \"$f\" ] && fapolicyd-cli --file add \"$f\"; } || true; done",
" fapolicyd-cli --update 2>/dev/null || true",
- " echo '==> fapolicyd: trusted custom binaries (kiosk-session, fleet-sb-enroll, fleet-hostapi, fleet-agent) + rebuilt trust db'",
+ " echo '==> fapolicyd: trusted custom binaries (kiosk-session, fleet-sb-enroll, fleet-hostapi, fleet-agent, fleet-ssh-hostcert) + rebuilt trust db'",
# watch_fs: the diskless root is OVERLAYFS (systemd.volatile=overlay), but the
# shipped watch_fs lacks 'overlay', so fapolicyd marks NO overlay mount and
# therefore intercepts NO exec on / — the exec guard for the writable overlay
@@ -1017,7 +1048,8 @@ build {
# for the WHOLE root at runtime for the first time: boot + kiosk render + admin
# SSH + sudo + TPM enrolment must ALL still work (nothing legit is untrusted),
# a novel /tmp binary must now be BLOCKED (EPERM), and watch for new AVCs.
- # enable_stig=false is the escape hatch if it regresses the boot/secure path.
+ # If it regresses the boot/secure path, waive the offending rule in the
+ # tailoring (a justified deviation) — not by disabling STIG (that path is gone).
" if [ -f /etc/fapolicyd/fapolicyd.conf ]; then",
" grep -Eq '^watch_fs.*overlay' /etc/fapolicyd/fapolicyd.conf || sed -ri '/^watch_fs *=/ s/$/,overlay/' /etc/fapolicyd/fapolicyd.conf",
" grep -Eq '^watch_fs.*overlay' /etc/fapolicyd/fapolicyd.conf || { echo 'ERROR: failed to add overlay to fapolicyd watch_fs' >&2; exit 1; }",
diff --git a/files/ssh-hostcert/README.md b/files/ssh-hostcert/README.md
new file mode 100644
index 0000000..2a9d11e
--- /dev/null
+++ b/files/ssh-hostcert/README.md
@@ -0,0 +1,82 @@
+# fleet-ssh-hostcert — SSH host certificate client
+
+At boot, gets this host's **per-boot SSH host key** signed by the **fleet SSH CA**
+(step-ca) so administrators trust every fleet host via a single `@cert-authority`
+line in `known_hosts` — instead of trust-on-first-use (TOFU) on a key that changes
+every boot. Closes **F-02 / POA&M P-17**. Full design: `docs/ssh-host-certificate-design.md`.
+
+## Why
+
+The diskless root is a RAM overlay, so `sshd-keygen@` regenerates the SSH host
+keys **every boot** (see `scripts/extract-artifacts.sh`). Clients can therefore
+never pin a host key — every admin SSH connection is TOFU, and a LAN MITM is
+undetectable client-side. A CA-signed **host certificate** removes TOFU fleet-wide:
+the key can stay ephemeral; trust comes from the CA, not the key.
+
+## How (Design A — per-boot key + boot-time cert)
+
+1. Load the **TPM identity** (persistent handle `0x81000100` + leaf cert in NV
+ `0x01800100`) and build an **mTLS client cert** from it — the same identity used
+ for 802.1X, the NVMe hostnqn and agent mTLS. The private key never leaves the TPM.
+2. Read the fresh `/etc/ssh/ssh_host_ecdsa_key.pub`.
+3. `POST` it to the **enrol-broker host plane** (`/ssh/hostcert`) over mTLS. The
+ broker verifies the client cert to the fleet CA (⇒ an enrolled host) and has
+ step-ca sign an SSH **host** cert — the broker, not the host, holds the CA
+ provisioner credential, so step-ca stays behind the single front door.
+4. Write `/etc/ssh/ssh_host_ecdsa_key-cert.pub` + a `HostCertificate` sshd drop-in
+ (`60-hostcert.conf`), then `systemctl reload sshd`.
+
+**Fail-open:** any failure (no network, broker/CA down, host not yet enrolled)
+exits non-zero **without touching sshd** — the host keeps serving its bare per-boot
+key (today's behaviour). It never installs a missing/broken `HostCertificate` that
+would stop sshd from starting. `ssh-hostcert.timer` retries (boot + hourly); a
+signed cert lands once the broker is reachable.
+
+## Identity model / invariants
+
+- **No per-host state in the image** (invariant #1): the broker DNS name in
+ `ssh-hostcert.env` is fleet-generic; the host identity comes from the TPM at
+ runtime. Principals default to the runtime hostname (never baked).
+- **Reuses the one TPM identity** ("one identity, N stages") as the mTLS client
+ auth to the broker — the SSH host key itself is a separate ephemeral key, so this
+ does not add cross-protocol signing exposure to the identity key (cf. F-06).
+
+## Config
+
+Fleet-generic knobs in `ssh-hostcert.env` (installed to `/etc/ssh-hostcert/`):
+`SSH_HOSTCERT_BROKER_URL` (the enrol-broker host-plane endpoint),
+`SSH_HOSTCERT_CACERT`, `SSH_HOSTCERT_HANDLE`/`_NVINDEX`, `SSH_HOSTCERT_PRINCIPALS`.
+All are also `-flags` for `fleet-ssh-hostcert`.
+
+## Build / test
+
+Pure Go (go-tpm, `CGO_ENABLED=0`), one static reproducible binary like
+`fleet-enrol`/`fleet-agent`; deps pinned by `go.sum`. Built **out of the VM** by
+CI and file-provisioned into the rootfs (Packer `2b-ssh-hostcert`, gated on
+`enable_ssh_hostcert`).
+
+```
+cd files/ssh-hostcert
+CGO_ENABLED=0 go test ./...
+CGO_ENABLED=0 GOTOOLCHAIN=local go build -trimpath -buildvcs=false -ldflags '-s -w -buildid=' -o bin/fleet-ssh-hostcert .
+```
+
+## Serving side (once per environment)
+
+`serving/dot1x-bench/step-ca/ssh-ca-bootstrap.sh` enables step-ca's SSH CA, allows
+the `enrol` provisioner to issue SSH host certs, issues the broker host-plane
+server cert, and prints the admin `@cert-authority` line. The broker host plane is
+enabled by `BROKER_HOST_ADDR` (wired in the dot1x-bench compose). Several steps are
+**BENCH-VERIFY** against your step / step-ca version — notably the SSH host
+principal **authorisation policy**. See `serving/enrol-broker/` (host.go, sshsigner.go).
+
+## Bench checklist (BENCH-VERIFY)
+
+- Broker host plane: `step ssh certificate --host --sign …` (sshsigner.go) succeeds
+ against the CA's SSH host CA; the exact flags are the tunable part of the contract.
+- Host principal policy: requested principals are authorised (tighten the broker to
+ validate `principals` against the peer cert).
+- SELinux: the (root) service writing `/etc/ssh/*` and running `systemctl reload
+ sshd` under confinement — may need a small local TE module (à la the chrony
+ read module). Watch for AVCs.
+- Client: `ssh ` shows no host-key warning once `@cert-authority` is set.
diff --git a/files/ssh-hostcert/go.mod b/files/ssh-hostcert/go.mod
new file mode 100644
index 0000000..c99b41c
--- /dev/null
+++ b/files/ssh-hostcert/go.mod
@@ -0,0 +1,14 @@
+// fleet-ssh-hostcert — boot-time SSH host-certificate client (post-switch-root).
+// Gets the host's per-boot ephemeral SSH host key signed by the fleet SSH CA via
+// the enrol-broker host plane, authenticating with the TPM identity over mTLS —
+// so admins trust every host via one `@cert-authority` line instead of per-boot
+// TOFU (closes F-02 / POA&M P-17). Pure Go (go-tpm, no CGO), one static
+// reproducible binary like fleet-enrol/fleet-agent; deps pinned by go.sum.
+// See docs/ssh-host-certificate-design.md and files/ssh-hostcert/README.md.
+module fleet-ssh-hostcert
+
+go 1.26
+
+require github.com/google/go-tpm v0.9.8
+
+require golang.org/x/sys v0.8.0 // indirect
diff --git a/files/ssh-hostcert/go.sum b/files/ssh-hostcert/go.sum
new file mode 100644
index 0000000..5416cec
--- /dev/null
+++ b/files/ssh-hostcert/go.sum
@@ -0,0 +1,6 @@
+github.com/google/go-tpm v0.9.8 h1:slArAR9Ft+1ybZu0lBwpSmpwhRXaa85hWtMinMyRAWo=
+github.com/google/go-tpm v0.9.8/go.mod h1:h9jEsEECg7gtLis0upRBQU+GhYVH6jMjrFxI8u6bVUY=
+github.com/google/go-tpm-tools v0.3.13-0.20230620182252-4639ecce2aba h1:qJEJcuLzH5KDR0gKc0zcktin6KSAwL7+jWKBYceddTc=
+github.com/google/go-tpm-tools v0.3.13-0.20230620182252-4639ecce2aba/go.mod h1:EFYHy8/1y2KfgTAsx7Luu7NGhoxtuVHnNo8jE7FikKc=
+golang.org/x/sys v0.8.0 h1:EBmGv8NaZBZTWvrbjNoL6HVt+IVy3QDQpJs7VRIw3tU=
+golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
diff --git a/files/ssh-hostcert/http.go b/files/ssh-hostcert/http.go
new file mode 100644
index 0000000..7767637
--- /dev/null
+++ b/files/ssh-hostcert/http.go
@@ -0,0 +1,28 @@
+package main
+
+import (
+ "fmt"
+ "net/http"
+ "net/url"
+ "time"
+)
+
+// brokerClient builds an HTTPS client that presents the host's TPM-backed mTLS
+// identity to the enrol-broker's host plane and verifies the broker's server cert
+// against the fleet CA. serverName for hostname verification is taken from the
+// broker URL's host.
+func brokerClient(id *tpmIdentity, brokerURL, caFile string) (*http.Client, error) {
+ u, err := url.Parse(brokerURL)
+ if err != nil {
+ return nil, fmt.Errorf("parse broker URL %q: %w", brokerURL, err)
+ }
+ if u.Scheme != "https" {
+ return nil, fmt.Errorf("broker URL must be https (mTLS), got %q", u.Scheme)
+ }
+ tlsCfg, err := mtlsClientConfig(id, caFile, u.Hostname())
+ if err != nil {
+ return nil, err
+ }
+ tr := &http.Transport{TLSClientConfig: tlsCfg}
+ return &http.Client{Timeout: 30 * time.Second, Transport: tr}, nil
+}
diff --git a/files/ssh-hostcert/identity.go b/files/ssh-hostcert/identity.go
new file mode 100644
index 0000000..c9fe1ed
--- /dev/null
+++ b/files/ssh-hostcert/identity.go
@@ -0,0 +1,93 @@
+// identity.go — the host's mTLS identity, reused from the TPM (same key/cert as
+// 802.1X, the NVMe hostnqn and the agent). The private key never leaves the TPM:
+// we present the enrolment cert (DER read from NV 0x01800100) as the leaf and
+// hand crypto/tls a crypto.Signer backed by the persistent key at 0x81000100
+// (tpmkey.LoadSigner). The enrol-broker's host plane verifies this chain to the
+// fleet CA (RequireAndVerifyClientCert) — proving "an enrolled fleet host" — and
+// only then signs the SSH host cert. Mirrors files/agent/identity.go.
+package main
+
+import (
+ "crypto/tls"
+ "crypto/x509"
+ "fmt"
+ "os"
+
+ "fleet-ssh-hostcert/tpmkey"
+
+ "github.com/google/go-tpm/tpm2"
+ "github.com/google/go-tpm/tpm2/transport"
+)
+
+// tpmIdentity holds the open TPM transport plus the loaded mTLS identity so the
+// caller can close the device when done.
+type tpmIdentity struct {
+ dev *os.File
+ cert tls.Certificate
+}
+
+func (id *tpmIdentity) Close() error {
+ if id != nil && id.dev != nil {
+ return id.dev.Close()
+ }
+ return nil
+}
+
+// loadTPMIdentity opens the TPM, loads the signing key at handle, reads the cert
+// from NV index, and assembles a tls.Certificate whose PrivateKey is the TPM
+// signer. A missing key/cert means the host isn't enrolled yet — surfaced with a
+// clear error so the caller can fail-open (retry later, leave sshd untouched).
+func loadTPMIdentity(tpmPath string, handle, nvIndex tpm2.TPMHandle) (*tpmIdentity, error) {
+ // transport.FromReadWriter over the /dev/tpmrm0 *os.File avoids the linuxtpm
+ // transport and its extra deps — the same lean approach fleet-enrol/agent use.
+ f, err := os.OpenFile(tpmPath, os.O_RDWR, 0)
+ if err != nil {
+ return nil, fmt.Errorf("open TPM %s: %w", tpmPath, err)
+ }
+ tpm := transport.FromReadWriter(f)
+
+ signer, err := tpmkey.LoadSigner(tpm, handle)
+ if err != nil {
+ f.Close()
+ return nil, fmt.Errorf("load signing key at %#x: %w (host enrolled?)", uint32(handle), err)
+ }
+ der, err := tpmkey.ReadNVCert(tpm, nvIndex)
+ if err != nil {
+ f.Close()
+ return nil, fmt.Errorf("read identity cert from NV %#x: %w (host enrolled?)", uint32(nvIndex), err)
+ }
+ leaf, err := x509.ParseCertificate(der)
+ if err != nil {
+ f.Close()
+ return nil, fmt.Errorf("parse identity cert: %w", err)
+ }
+
+ return &tpmIdentity{
+ dev: f,
+ cert: tls.Certificate{
+ Certificate: [][]byte{der},
+ PrivateKey: signer, // crypto.Signer — TLS signs the handshake in the TPM
+ Leaf: leaf,
+ },
+ }, nil
+}
+
+// mtlsClientConfig builds the mTLS config: our TPM-backed client cert + the fleet
+// CA as the root that verifies the broker's server cert. serverName is the
+// broker's DNS name (SNI + hostname verification).
+func mtlsClientConfig(id *tpmIdentity, caFile, serverName string) (*tls.Config, error) {
+ pemBytes, err := os.ReadFile(caFile)
+ if err != nil {
+ return nil, fmt.Errorf("read fleet CA %s: %w", caFile, err)
+ }
+ pool := x509.NewCertPool()
+ if !pool.AppendCertsFromPEM(pemBytes) {
+ return nil, fmt.Errorf("no certificates parsed from fleet CA %s", caFile)
+ }
+ return &tls.Config{
+ MinVersion: tls.VersionTLS12,
+ Certificates: []tls.Certificate{id.cert},
+ RootCAs: pool,
+ ServerName: serverName,
+ }, nil
+}
diff --git a/files/ssh-hostcert/main.go b/files/ssh-hostcert/main.go
new file mode 100644
index 0000000..6c946e5
--- /dev/null
+++ b/files/ssh-hostcert/main.go
@@ -0,0 +1,207 @@
+// Command fleet-ssh-hostcert obtains a fleet-CA-signed SSH *host* certificate for
+// this host's per-boot SSH host key and installs it, so administrators trust the
+// host via a single `@cert-authority` line instead of trust-on-first-use on a key
+// that changes every boot (the ephemeral RAM overlay regenerates host keys each
+// boot — see scripts/extract-artifacts.sh). Closes F-02 / POA&M P-17.
+//
+// Flow (Design A, broker-mediated — docs/ssh-host-certificate-design.md):
+// 1. load the host's mTLS identity from the TPM (persistent key 0x81000100 +
+// leaf cert in NV 0x01800100) — the same identity used for 802.1X, the NVMe
+// hostnqn and agent mTLS. The private key never leaves the TPM.
+// 2. read the freshly generated public host key (/etc/ssh/ssh_host_ecdsa_key.pub).
+// 3. POST it to the enrol-broker's host plane over mTLS. The broker verifies the
+// client cert to the fleet CA (proving an enrolled host) and has step-ca sign
+// an SSH host certificate — the broker, not the host, holds the CA provisioner
+// credential, keeping step-ca behind the single front door.
+// 4. write the returned cert + a HostCertificate sshd drop-in, then reload sshd.
+//
+// FAIL-OPEN: any failure (no network, broker/CA down, host not enrolled) exits
+// non-zero WITHOUT touching sshd — the host keeps serving its bare per-boot key
+// (today's behaviour). It never installs a missing/broken HostCertificate that
+// would stop sshd from starting. A systemd timer retries. Fleet-generic: no
+// per-host data in the image (invariant #1).
+package main
+
+import (
+ "bytes"
+ "encoding/json"
+ "flag"
+ "fmt"
+ "io"
+ "log"
+ "net/http"
+ "os"
+ "os/exec"
+ "strconv"
+ "strings"
+
+ "github.com/google/go-tpm/tpm2"
+)
+
+func main() {
+ log.SetFlags(0)
+ log.SetPrefix("fleet-ssh-hostcert: ")
+
+ var (
+ tpmPath = flag.String("tpm", envOr("SSH_HOSTCERT_TPM", "/dev/tpmrm0"), "TPM resource-manager device")
+ handleStr = flag.String("handle", envOr("SSH_HOSTCERT_HANDLE", "0x81000100"), "persistent handle of the TPM identity key")
+ nvindexStr = flag.String("nvindex", envOr("SSH_HOSTCERT_NVINDEX", "0x01800100"), "NV index of the identity cert (DER)")
+ brokerURL = flag.String("broker-url", envOr("SSH_HOSTCERT_BROKER_URL", "https://boot.fleet.lab:9444/ssh/hostcert"), "enrol-broker host-plane SSH host-cert endpoint (mTLS)")
+ caFile = flag.String("cacert", envOr("SSH_HOSTCERT_CACERT", "/etc/dot1x/radius-ca.pem"), "fleet CA bundle (verifies the broker's server cert)")
+ hostKey = flag.String("hostkey", envOr("SSH_HOSTCERT_HOSTKEY", "/etc/ssh/ssh_host_ecdsa_key.pub"), "SSH host public key to certify")
+ outCert = flag.String("out", envOr("SSH_HOSTCERT_OUT", "/etc/ssh/ssh_host_ecdsa_key-cert.pub"), "path to write the host certificate")
+ dropIn = flag.String("dropin", envOr("SSH_HOSTCERT_DROPIN", "/etc/ssh/sshd_config.d/60-hostcert.conf"), "sshd drop-in that references the host certificate")
+ principals = flag.String("principals", envOr("SSH_HOSTCERT_PRINCIPALS", ""), "comma-separated cert principals (default: hostname)")
+ reload = flag.Bool("reload", envOr("SSH_HOSTCERT_RELOAD", "true") == "true", "reload sshd after installing the certificate")
+ )
+ flag.Parse()
+
+ handle, err := parseHandle(*handleStr)
+ if err != nil {
+ log.Fatalf("bad -handle: %v", err)
+ }
+ nvindex, err := parseHandle(*nvindexStr)
+ if err != nil {
+ log.Fatalf("bad -nvindex: %v", err)
+ }
+
+ // --- mTLS identity from the TPM ------------------------------------------
+ id, err := loadTPMIdentity(*tpmPath, handle, nvindex)
+ if err != nil {
+ log.Fatalf("TPM identity: %v", err)
+ }
+ defer id.Close()
+
+ // --- request inputs -------------------------------------------------------
+ pubLine, err := readHostPubLine(*hostKey)
+ if err != nil {
+ log.Fatalf("read host key %s: %v", *hostKey, err)
+ }
+ princ := splitPrincipals(*principals)
+ if len(princ) == 0 {
+ princ = defaultPrincipals()
+ }
+ keyID := ""
+ if id.cert.Leaf != nil {
+ keyID = id.cert.Leaf.Subject.CommonName
+ }
+ if keyID == "" {
+ keyID = princ[0]
+ }
+
+ // --- ask the broker to sign (over mTLS) ----------------------------------
+ client, err := brokerClient(id, *brokerURL, *caFile)
+ if err != nil {
+ log.Fatalf("broker client: %v", err)
+ }
+ certLine, err := requestHostCert(client, *brokerURL, pubLine, princ, keyID)
+ if err != nil {
+ log.Fatalf("request SSH host cert: %v", err)
+ }
+
+ // --- install (only now do we touch sshd's config surface) -----------------
+ if err := writeFileAtomic(*outCert, []byte(strings.TrimRight(certLine, "\n")+"\n"), 0o644); err != nil {
+ log.Fatalf("write cert %s: %v", *outCert, err)
+ }
+ dropContent := fmt.Sprintf("# Managed by fleet-ssh-hostcert. Host cert signed by the fleet SSH CA.\nHostCertificate %s\n", *outCert)
+ if err := writeFileAtomic(*dropIn, []byte(dropContent), 0o644); err != nil {
+ log.Fatalf("write drop-in %s: %v", *dropIn, err)
+ }
+ log.Printf("installed SSH host certificate for principals %v (keyID %q)", princ, keyID)
+
+ if *reload {
+ if out, err := exec.Command("systemctl", "reload", "sshd.service").CombinedOutput(); err != nil {
+ // Non-fatal: the cert is on disk and takes effect on the next sshd (re)start.
+ log.Printf("warning: sshd reload failed (%v): %s", err, strings.TrimSpace(string(out)))
+ }
+ }
+}
+
+type hostCertRequest struct {
+ PublicKey string `json:"publicKey"`
+ Principals []string `json:"principals"`
+ KeyID string `json:"keyID"`
+}
+
+type hostCertResponse struct {
+ Cert string `json:"cert"`
+ Error string `json:"error,omitempty"`
+}
+
+// requestHostCert POSTs the host public key to the broker's mTLS host plane and
+// returns the signed SSH host-certificate line (`ecdsa-sha2-…-cert-v01@… AAAA…`).
+func requestHostCert(client *http.Client, url, pubLine string, principals []string, keyID string) (string, error) {
+ body, err := json.Marshal(hostCertRequest{PublicKey: pubLine, Principals: principals, KeyID: keyID})
+ if err != nil {
+ return "", err
+ }
+ resp, err := client.Post(url, "application/json", bytes.NewReader(body))
+ if err != nil {
+ return "", err
+ }
+ defer resp.Body.Close()
+ raw, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+ if resp.StatusCode/100 != 2 {
+ return "", fmt.Errorf("broker %s: %s", resp.Status, strings.TrimSpace(string(raw)))
+ }
+ var out hostCertResponse
+ if err := json.Unmarshal(raw, &out); err != nil || out.Cert == "" {
+ return "", fmt.Errorf("unexpected broker response: %s", strings.TrimSpace(string(raw)))
+ }
+ return out.Cert, nil
+}
+
+// readHostPubLine returns the trimmed single-line OpenSSH public key (type +
+// base64 + optional comment) that the broker signs.
+func readHostPubLine(path string) (string, error) {
+ b, err := os.ReadFile(path)
+ if err != nil {
+ return "", err
+ }
+ line := strings.TrimSpace(string(b))
+ if len(strings.Fields(line)) < 2 {
+ return "", fmt.Errorf("malformed public key (want at least 2 fields)")
+ }
+ return line, nil
+}
+
+func splitPrincipals(s string) []string {
+ var out []string
+ for p := range strings.SplitSeq(s, ",") {
+ if p = strings.TrimSpace(p); p != "" {
+ out = append(out, p)
+ }
+ }
+ return out
+}
+
+func defaultPrincipals() []string {
+ h, err := os.Hostname()
+ if err != nil || h == "" {
+ return []string{"localhost"}
+ }
+ return []string{h}
+}
+
+func envOr(k, def string) string {
+ if v := os.Getenv(k); v != "" {
+ return v
+ }
+ return def
+}
+
+func parseHandle(s string) (tpm2.TPMHandle, error) {
+ v, err := strconv.ParseUint(strings.TrimPrefix(strings.ToLower(s), "0x"), 16, 32)
+ if err != nil {
+ return 0, err
+ }
+ return tpm2.TPMHandle(v), nil
+}
+
+func writeFileAtomic(path string, data []byte, mode os.FileMode) error {
+ tmp := path + ".tmp"
+ if err := os.WriteFile(tmp, data, mode); err != nil {
+ return err
+ }
+ return os.Rename(tmp, path)
+}
diff --git a/files/ssh-hostcert/main_test.go b/files/ssh-hostcert/main_test.go
new file mode 100644
index 0000000..3e467a5
--- /dev/null
+++ b/files/ssh-hostcert/main_test.go
@@ -0,0 +1,91 @@
+package main
+
+import (
+ "encoding/json"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+)
+
+func TestReadHostPubLine(t *testing.T) {
+ dir := t.TempDir()
+ p := dir + "/k.pub"
+ if err := writeFileAtomic(p, []byte("ecdsa-sha2-nistp256 AAAAB3Nz root@fleet\n"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ line, err := readHostPubLine(p)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if line != "ecdsa-sha2-nistp256 AAAAB3Nz root@fleet" {
+ t.Errorf("got %q", line)
+ }
+ if err := writeFileAtomic(p, []byte("garbage\n"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := readHostPubLine(p); err == nil {
+ t.Error("expected error on malformed key")
+ }
+}
+
+func TestSplitPrincipals(t *testing.T) {
+ got := splitPrincipals(" a, b ,,c ")
+ if len(got) != 3 || got[0] != "a" || got[1] != "b" || got[2] != "c" {
+ t.Errorf("got %v", got)
+ }
+ if len(splitPrincipals("")) != 0 {
+ t.Error("empty string should yield no principals")
+ }
+}
+
+func TestParseHandle(t *testing.T) {
+ h, err := parseHandle("0x81000100")
+ if err != nil || uint32(h) != 0x81000100 {
+ t.Fatalf("h=%#x err=%v", uint32(h), err)
+ }
+ if _, err := parseHandle("nothex"); err == nil {
+ t.Error("expected error")
+ }
+}
+
+func TestRequestHostCert(t *testing.T) {
+ const certLine = "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAcert host.fleet.lab"
+ var gotReq hostCertRequest
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ defer r.Body.Close()
+ raw, _ := io.ReadAll(r.Body)
+ _ = json.Unmarshal(raw, &gotReq)
+ writeJSON(w, http.StatusOK, hostCertResponse{Cert: certLine})
+ }))
+ defer srv.Close()
+
+ got, err := requestHostCert(srv.Client(), srv.URL, "ecdsa-sha2-nistp256 AAAA host", []string{"host", "host.fleet.lab"}, "host.fleet.lab")
+ if err != nil {
+ t.Fatalf("requestHostCert: %v", err)
+ }
+ if got != certLine {
+ t.Errorf("cert = %q", got)
+ }
+ if gotReq.PublicKey != "ecdsa-sha2-nistp256 AAAA host" || gotReq.KeyID != "host.fleet.lab" || len(gotReq.Principals) != 2 {
+ t.Errorf("broker received unexpected request: %+v", gotReq)
+ }
+}
+
+func TestRequestHostCertErrorBody(t *testing.T) {
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ writeJSON(w, http.StatusForbidden, hostCertResponse{Error: "not enrolled"})
+ }))
+ defer srv.Close()
+ if _, err := requestHostCert(srv.Client(), srv.URL, "ecdsa-sha2-nistp256 AAAA host", []string{"host"}, "host"); err == nil || !strings.Contains(err.Error(), "not enrolled") {
+ t.Errorf("want error carrying broker message, got %v", err)
+ }
+}
+
+// writeJSON mirrors the broker's small JSON helper for the test server.
+func writeJSON(w http.ResponseWriter, code int, v any) {
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(code)
+ _ = json.NewEncoder(w).Encode(v)
+}
diff --git a/files/ssh-hostcert/ssh-hostcert.env b/files/ssh-hostcert/ssh-hostcert.env
new file mode 100644
index 0000000..c93b546
--- /dev/null
+++ b/files/ssh-hostcert/ssh-hostcert.env
@@ -0,0 +1,33 @@
+# fleet-ssh-hostcert configuration — fleet-generic (no per-host data; invariant #1).
+# The host's SSH host key is signed by the fleet SSH CA (via the enrol-broker) so
+# admins trust every host with one `@cert-authority` line instead of per-boot TOFU
+# (F-02/P-17). Replace the DNS names per environment; the serving dnsmasq resolves
+# them. docs/ssh-host-certificate-design.md.
+
+# The enrol-broker's HOST PLANE endpoint (mTLS). The host authenticates with its
+# TPM identity; the broker (not the host) holds the step-ca provisioner credential
+# and signs the SSH host cert, keeping step-ca behind the single front door.
+SSH_HOSTCERT_BROKER_URL=https://boot.fleet.lab:9444/ssh/hostcert
+
+# Fleet CA bundle: verifies the broker's server cert. Same anchor as the RADIUS /
+# agent CA — reuse the one placeholder, replace per environment.
+SSH_HOSTCERT_CACERT=/etc/dot1x/radius-ca.pem
+
+# TPM identity (same key/cert as 802.1X, the NVMe hostnqn and agent mTLS) — used
+# as the mTLS CLIENT cert proving this is an enrolled host.
+SSH_HOSTCERT_HANDLE=0x81000100
+SSH_HOSTCERT_NVINDEX=0x01800100
+
+# The per-boot host key to certify and where its certificate is installed.
+SSH_HOSTCERT_HOSTKEY=/etc/ssh/ssh_host_ecdsa_key.pub
+SSH_HOSTCERT_OUT=/etc/ssh/ssh_host_ecdsa_key-cert.pub
+SSH_HOSTCERT_DROPIN=/etc/ssh/sshd_config.d/60-hostcert.conf
+
+# Cert principals. Empty => the binary uses the host's hostname (derived at
+# runtime, never baked). Set a comma list to add e.g. a per-env FQDN or wildcard
+# that admins connect by (must be covered by their `@cert-authority` line and
+# authorised by the broker's principal policy).
+SSH_HOSTCERT_PRINCIPALS=
+
+# Reload sshd after installing/renewing the cert so it takes effect immediately.
+SSH_HOSTCERT_RELOAD=true
diff --git a/files/ssh-hostcert/ssh-hostcert.service b/files/ssh-hostcert/ssh-hostcert.service
new file mode 100644
index 0000000..f1bfa31
--- /dev/null
+++ b/files/ssh-hostcert/ssh-hostcert.service
@@ -0,0 +1,51 @@
+[Unit]
+Description=Fleet SSH host-certificate acquisition (TPM-authenticated, fleet SSH CA)
+Documentation=https://git.bitasylum.org/audiobuzz/diskless-workstation/docs/ssh-host-certificate-design.md
+# Needs the network up (dials step-ca) and sshd's per-boot host key to exist.
+# sshd-keygen generates the host key before sshd starts, so ordering After sshd
+# guarantees the key is present; sshd itself serves the bare key until we install
+# the cert and reload it. All soft ordering (After, not Requires) — this unit is
+# FAIL-OPEN: if the CA is unreachable or the host isn't enrolled yet, it exits
+# non-zero WITHOUT touching sshd, and the timer retries.
+After=network-online.target sshd.service
+Wants=network-online.target
+# Don't run in the throwaway build VM (no TPM, no enrolment, no network CA).
+ConditionPathExists=/dev/tpmrm0
+
+[Service]
+Type=oneshot
+EnvironmentFile=/etc/ssh-hostcert/ssh-hostcert.env
+ExecStart=/usr/local/bin/fleet-ssh-hostcert
+
+# Runs as root — unlike the DynamicUser agent — because it writes root-owned
+# files under /etc/ssh and reloads sshd. Kept tightly sandboxed otherwise. The
+# TPM private key never leaves the chip; root only drives signing through it.
+User=root
+# STIG-friendly sandbox. /etc/ssh must be writable (the cert + drop-in); the rest
+# of the filesystem is read-only.
+ProtectSystem=strict
+ReadWritePaths=/etc/ssh
+ProtectHome=yes
+PrivateTmp=yes
+DeviceAllow=/dev/tpmrm0 rw
+NoNewPrivileges=yes
+ProtectKernelTunables=yes
+ProtectKernelModules=yes
+ProtectKernelLogs=yes
+ProtectControlGroups=yes
+ProtectClock=yes
+ProtectHostname=yes
+RestrictNamespaces=yes
+RestrictRealtime=yes
+RestrictSUIDSGID=yes
+LockPersonality=yes
+MemoryDenyWriteExecute=yes
+SystemCallArchitectures=native
+SystemCallFilter=@system-service
+SystemCallFilter=~@privileged @resources
+# INET egress to step-ca; AF_UNIX for the journal + talking to systemd (reload
+# sshd); AF_NETLINK for Go's interface/source-address selection.
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK
+UMask=0022
+
+# Triggered by ssh-hostcert.timer (boot + periodic renewal), not enabled directly.
diff --git a/files/ssh-hostcert/ssh-hostcert.timer b/files/ssh-hostcert/ssh-hostcert.timer
new file mode 100644
index 0000000..f9590b8
--- /dev/null
+++ b/files/ssh-hostcert/ssh-hostcert.timer
@@ -0,0 +1,17 @@
+[Unit]
+Description=Renew the fleet SSH host certificate
+Documentation=https://git.bitasylum.org/audiobuzz/diskless-workstation/docs/ssh-host-certificate-design.md
+
+[Timer]
+# Fire shortly after boot (once the network + enrolment are likely ready) to
+# acquire the first cert for this boot's ephemeral host key, then renew well
+# inside the cert's validity window. The service is idempotent + fail-open, so a
+# missed/failed run just retries next cycle (sshd keeps serving the bare key
+# meanwhile). Cadence is bench-tunable (host-cert validity is a step-ca policy).
+OnBootSec=60s
+OnUnitActiveSec=1h
+Persistent=false
+AccuracySec=15s
+
+[Install]
+WantedBy=timers.target
diff --git a/files/ssh-hostcert/tpmkey/tpmkey.go b/files/ssh-hostcert/tpmkey/tpmkey.go
new file mode 100644
index 0000000..53bf7e8
--- /dev/null
+++ b/files/ssh-hostcert/tpmkey/tpmkey.go
@@ -0,0 +1,304 @@
+// Package tpmkey — TPM 2.0 operations via go-tpm (pure Go, no CGO, no tpm2-tools
+// / no openssl tpm2 provider). Provides: ensure a persistent ECDSA signing key
+// at a non-reserved owner handle (default 0x81000100 — NOT the EK slot
+// 0x81010001, see EnsureKey), a crypto.Signer backed by it (for CSR signing),
+// and NV cert read-presence + write at 0x01800100. Talks to any transport.TPM,
+// so the same
+// code runs against /dev/tpmrm0 (production) and the software simulator (tests).
+//
+// Exported so the ceremony can be tested against the go-tpm simulator from a
+// SEPARATE module (simtest/), keeping this module's vendored deps lean (go-tpm
+// only) — the simulator (CGO + the MS TPM reference C) never enters the image build.
+//
+// NOTE: this is a COPY of files/enrol/tpmkey (via files/agent/tpmkey) — kept
+// byte-identical apart from the added read-only LoadSigner — so every reused-
+// identity client (agent, ssh-hostcert) has the exact same, bench-verified TPM
+// signing path without importing across the load-bearing fleet-enrol module.
+// ssh-hostcert only READS the key (LoadSigner) + NV cert (ReadNVCert); it never
+// creates/evicts. A future refactor could promote tpmkey to a shared module.
+package tpmkey
+
+import (
+ "crypto"
+ "crypto/ecdsa"
+ "encoding/asn1"
+ "fmt"
+ "io"
+ "math/big"
+
+ "github.com/google/go-tpm/tpm2"
+ "github.com/google/go-tpm/tpm2/transport"
+)
+
+// eccSigningTemplate: a NON-restricted ECC P-256 ECDSA-SHA256 signing key.
+// Non-restricted so it can sign an externally-computed digest (the CSR TBS) with
+// a NULL validation ticket; Symmetric/KDF are explicitly NULL (sign-only key).
+func eccSigningTemplate() tpm2.TPMTPublic {
+ return tpm2.TPMTPublic{
+ Type: tpm2.TPMAlgECC,
+ NameAlg: tpm2.TPMAlgSHA256,
+ ObjectAttributes: tpm2.TPMAObject{
+ FixedTPM: true,
+ FixedParent: true,
+ SensitiveDataOrigin: true,
+ UserWithAuth: true,
+ SignEncrypt: true,
+ NoDA: true,
+ },
+ Parameters: tpm2.NewTPMUPublicParms(tpm2.TPMAlgECC, &tpm2.TPMSECCParms{
+ Symmetric: tpm2.TPMTSymDefObject{Algorithm: tpm2.TPMAlgNull},
+ Scheme: tpm2.TPMTECCScheme{
+ Scheme: tpm2.TPMAlgECDSA,
+ Details: tpm2.NewTPMUAsymScheme(tpm2.TPMAlgECDSA, &tpm2.TPMSSigSchemeECDSA{
+ HashAlg: tpm2.TPMAlgSHA256,
+ }),
+ },
+ CurveID: tpm2.TPMECCNistP256,
+ KDF: tpm2.TPMTKDFScheme{Scheme: tpm2.TPMAlgNull},
+ }),
+ }
+}
+
+// Signer implements crypto.Signer using a persistent TPM key.
+type Signer struct {
+ tpm transport.TPM
+ handle tpm2.TPMHandle
+ name tpm2.TPM2BName
+ pub *ecdsa.PublicKey
+}
+
+func (s *Signer) Public() crypto.PublicKey { return s.pub }
+
+func (s *Signer) Sign(_ io.Reader, digest []byte, _ crypto.SignerOpts) ([]byte, error) {
+ rsp, err := tpm2.Sign{
+ KeyHandle: tpm2.NamedHandle{Handle: s.handle, Name: s.name},
+ Digest: tpm2.TPM2BDigest{Buffer: digest},
+ InScheme: tpm2.TPMTSigScheme{
+ Scheme: tpm2.TPMAlgECDSA,
+ Details: tpm2.NewTPMUSigScheme(tpm2.TPMAlgECDSA, &tpm2.TPMSSchemeHash{
+ HashAlg: tpm2.TPMAlgSHA256,
+ }),
+ },
+ Validation: tpm2.TPMTTKHashCheck{Tag: tpm2.TPMSTHashCheck},
+ }.Execute(s.tpm)
+ if err != nil {
+ return nil, fmt.Errorf("tpm sign: %w", err)
+ }
+ ecc, err := rsp.Signature.Signature.ECDSA()
+ if err != nil {
+ return nil, fmt.Errorf("tpm sign: not ECDSA: %w", err)
+ }
+ r := new(big.Int).SetBytes(ecc.SignatureR.Buffer)
+ sInt := new(big.Int).SetBytes(ecc.SignatureS.Buffer)
+ // x509 expects an ASN.1 DER ECDSA-Sig-Value{ r, s }.
+ return asn1.Marshal(struct{ R, S *big.Int }{r, sInt})
+}
+
+func signerFromPub(tpm transport.TPM, handle tpm2.TPMHandle, name tpm2.TPM2BName, pub2b tpm2.TPM2BPublic) (*Signer, error) {
+ pub, err := pub2b.Contents()
+ if err != nil {
+ return nil, err
+ }
+ det, err := pub.Parameters.ECCDetail()
+ if err != nil {
+ return nil, fmt.Errorf("key at handle is not ECC: %w", err)
+ }
+ uniq, err := pub.Unique.ECC()
+ if err != nil {
+ return nil, err
+ }
+ pk, err := tpm2.ECDSAPub(det, uniq)
+ if err != nil {
+ return nil, err
+ }
+ return &Signer{tpm: tpm, handle: handle, name: name, pub: pk}, nil
+}
+
+// isProtectedObject reports whether a persistent object is a restricted
+// decryption key — i.e. an Endorsement Key or Storage Root Key. We must NEVER
+// evict one of those (it would destroy the TPM's endorsement/storage identity,
+// including the EK the future EK/AK attestation path depends on). Fail-safe: if
+// the public area can't be parsed, treat it as protected.
+func isProtectedObject(pub2b tpm2.TPM2BPublic) bool {
+ pub, err := pub2b.Contents()
+ if err != nil {
+ return true
+ }
+ a := pub.ObjectAttributes
+ return a.Restricted && a.Decrypt
+}
+
+// ensureKey returns a signer for the persistent key at handle, creating +
+// persisting a fresh ECDSA key there if none exists. Returns created=true when
+// a new key was generated. handle MUST be a non-reserved owner handle (the fleet
+// default is 0x81000100) — NOT the EK (0x81010001/2) or SRK (0x81000001/2) slots.
+//
+// If the handle already holds an object that is NOT our ECC signing key (e.g. an
+// RSA signing key left by an older tpm2-tools/openssl provisioning path — go-tpm
+// reports "key at handle is not ECC"), it is treated as STALE and evicted, then a
+// fresh ECC key is created. Safe on the enrol path: this only runs on an empty-NV
+// host, so no issued cert references the old key. Only a valid ECC key is reused.
+// A restricted-decrypt object (EK/SRK) is NEVER evicted — it errors instead, which
+// only happens if handle was misconfigured to a reserved slot.
+func EnsureKey(tpm transport.TPM, handle tpm2.TPMHandle) (signer *Signer, created bool, err error) {
+ if rp, e := (tpm2.ReadPublic{ObjectHandle: handle}).Execute(tpm); e == nil {
+ // Guard FIRST: never touch a restricted-decrypt object (EK/SRK). An ECC
+ // EK/SRK would otherwise parse as a usable ECC key below and be "reused".
+ if isProtectedObject(rp.OutPublic) {
+ return nil, false, fmt.Errorf("refusing to evict a restricted-decrypt object (EK/SRK?) at handle %#x — configure a non-reserved owner handle (e.g. 0x81000100)", uint32(handle))
+ }
+ if s, e2 := signerFromPub(tpm, handle, rp.Name, rp.OutPublic); e2 == nil {
+ return s, false, nil // our ECC signing key is already there — reuse it
+ }
+ // Stale/wrong-type signing key occupying the handle — evict so we recreate.
+ if _, e2 := (tpm2.EvictControl{
+ Auth: tpm2.TPMRHOwner,
+ ObjectHandle: &tpm2.NamedHandle{Handle: handle, Name: rp.Name},
+ PersistentHandle: handle,
+ }).Execute(tpm); e2 != nil {
+ return nil, false, fmt.Errorf("evict stale (non-ECC) key at handle: %w", e2)
+ }
+ }
+
+ cp, err := tpm2.CreatePrimary{
+ PrimaryHandle: tpm2.TPMRHOwner,
+ InPublic: tpm2.New2B(eccSigningTemplate()),
+ }.Execute(tpm)
+ if err != nil {
+ return nil, false, fmt.Errorf("createprimary: %w", err)
+ }
+ // Persist at the well-known handle, then flush the transient object.
+ _, err = tpm2.EvictControl{
+ Auth: tpm2.TPMRHOwner,
+ ObjectHandle: &tpm2.NamedHandle{Handle: cp.ObjectHandle, Name: cp.Name},
+ PersistentHandle: handle,
+ }.Execute(tpm)
+ _, _ = (tpm2.FlushContext{FlushHandle: cp.ObjectHandle}).Execute(tpm)
+ if err != nil {
+ return nil, false, fmt.Errorf("evictcontrol: %w", err)
+ }
+ rp, err := (tpm2.ReadPublic{ObjectHandle: handle}).Execute(tpm)
+ if err != nil {
+ return nil, false, fmt.Errorf("readpublic after persist: %w", err)
+ }
+ s, err := signerFromPub(tpm, handle, rp.Name, rp.OutPublic)
+ return s, true, err
+}
+
+// LoadSigner returns a crypto.Signer for the persistent key ALREADY at handle,
+// WITHOUT creating one. This is the reused-identity path (normal boot / the on-host
+// agent): the fleet signing key was created at enrolment, so here we only sign the
+// TLS handshake with it — the private key never leaves the TPM. Errors (never
+// creates/evicts) if the handle is empty, holds a non-ECC object, or holds a
+// restricted-decrypt EK/SRK. Contrast EnsureKey, which is the enrol-time create path.
+func LoadSigner(tpm transport.TPM, handle tpm2.TPMHandle) (*Signer, error) {
+ rp, err := (tpm2.ReadPublic{ObjectHandle: handle}).Execute(tpm)
+ if err != nil {
+ return nil, fmt.Errorf("no persistent key at handle %#x: %w", uint32(handle), err)
+ }
+ if isProtectedObject(rp.OutPublic) {
+ return nil, fmt.Errorf("object at handle %#x is a restricted-decrypt key (EK/SRK?), not the fleet signing key", uint32(handle))
+ }
+ return signerFromPub(tpm, handle, rp.Name, rp.OutPublic)
+}
+
+// nvPresent reports whether a defined NV index exists. NOTE: "defined" does NOT
+// mean "holds our fleet cert" — leftover/foreign NV (e.g. an earlier
+// tpm-provision run, or another OS) also reports present. Prefer ReadNVCert +
+// content validation for the enrol decision; this stays for cheap existence checks.
+func NVPresent(tpm transport.TPM, index tpm2.TPMHandle) bool {
+ _, err := (tpm2.NVReadPublic{NVIndex: index}).Execute(tpm)
+ return err == nil
+}
+
+// ReadNVCert reads the full contents of NV index (chunked under the NV buffer
+// limit). Returns an error if the index is undefined or unreadable — callers
+// treat that as "no cert" (enrol). The bytes are the caller's to parse/validate;
+// this does not assume they are a certificate.
+func ReadNVCert(tpm transport.TPM, index tpm2.TPMHandle) ([]byte, error) {
+ rp, err := (tpm2.NVReadPublic{NVIndex: index}).Execute(tpm)
+ if err != nil {
+ return nil, fmt.Errorf("nv readpublic: %w", err)
+ }
+ pub, err := rp.NVPublic.Contents()
+ if err != nil {
+ return nil, err
+ }
+ size := int(pub.DataSize)
+ out := make([]byte, 0, size)
+ const chunk = 512 // conservatively under TPM_MAX_NV_BUFFER_SIZE
+ for off := 0; off < size; off += chunk {
+ end := min(off+chunk, size)
+ r, err := (tpm2.NVRead{
+ AuthHandle: tpm2.AuthHandle{Handle: index, Name: rp.NVName, Auth: tpm2.PasswordAuth(nil)},
+ NVIndex: tpm2.NamedHandle{Handle: index, Name: rp.NVName},
+ Size: uint16(end - off),
+ Offset: uint16(off),
+ }).Execute(tpm)
+ if err != nil {
+ return nil, fmt.Errorf("nv read @%d: %w", off, err)
+ }
+ out = append(out, r.Data.Buffer...)
+ }
+ return out, nil
+}
+
+// nvWriteCert (re)defines the NV index sized to der and writes it under owner
+// auth. Chunks the write to stay within the TPM's NV buffer limit.
+func WriteNVCert(tpm transport.TPM, index tpm2.TPMHandle, der []byte) error {
+ // Undefine a stale index first (re-enrolment / resized cert).
+ if rp, err := (tpm2.NVReadPublic{NVIndex: index}).Execute(tpm); err == nil {
+ // A PLATFORM-created index at our handle is OEM firmware NV (bench-seen on
+ // a Dell 820: 0x01800001 was platformcreate|policydelete|writelocked). We
+ // cannot undefine it with owner auth, and TPM2_Clear/BIOS won't remove it —
+ // so fail LOUDLY with guidance rather than a confusing "nv undefine" error.
+ // The remedy is a different, free owner index via rd.dot1x.nvindex.
+ if pub, e := rp.NVPublic.Contents(); e == nil && pub.Attributes.PlatformCreate {
+ return fmt.Errorf("NV index %#x is a platform-created (firmware-owned) index — cannot be written by enrolment; pick a free owner index via rd.dot1x.nvindex / -nvindex", uint32(index))
+ }
+ if _, err := (tpm2.NVUndefineSpace{
+ AuthHandle: tpm2.TPMRHOwner,
+ NVIndex: tpm2.NamedHandle{Handle: index, Name: rp.NVName},
+ }).Execute(tpm); err != nil {
+ return fmt.Errorf("nv undefine: %w", err)
+ }
+ }
+
+ def := tpm2.NVDefineSpace{
+ AuthHandle: tpm2.TPMRHOwner,
+ PublicInfo: tpm2.New2B(tpm2.TPMSNVPublic{
+ NVIndex: index,
+ NameAlg: tpm2.TPMAlgSHA256,
+ Attributes: tpm2.TPMANV{
+ OwnerWrite: true,
+ OwnerRead: true,
+ AuthWrite: true,
+ AuthRead: true,
+ NT: tpm2.TPMNTOrdinary,
+ NoDA: true,
+ },
+ DataSize: uint16(len(der)),
+ }),
+ }
+ if _, err := def.Execute(tpm); err != nil {
+ return fmt.Errorf("nv define: %w", err)
+ }
+ rp, err := (tpm2.NVReadPublic{NVIndex: index}).Execute(tpm)
+ if err != nil {
+ return fmt.Errorf("nv readpublic: %w", err)
+ }
+
+ const chunk = 512 // conservatively under TPM_MAX_NV_BUFFER_SIZE
+ for off := 0; off < len(der); off += chunk {
+ end := min(off+chunk, len(der))
+ if _, err := (tpm2.NVWrite{
+ AuthHandle: tpm2.AuthHandle{Handle: index, Name: rp.NVName, Auth: tpm2.PasswordAuth(nil)},
+ NVIndex: tpm2.NamedHandle{Handle: index, Name: rp.NVName},
+ Data: tpm2.TPM2BMaxNVBuffer{Buffer: der[off:end]},
+ Offset: uint16(off),
+ }).Execute(tpm); err != nil {
+ return fmt.Errorf("nv write @%d: %w", off, err)
+ }
+ }
+ return nil
+}
diff --git a/scripts/extract-artifacts.sh b/scripts/extract-artifacts.sh
index c95753b..1095428 100755
--- a/scripts/extract-artifacts.sh
+++ b/scripts/extract-artifacts.sh
@@ -134,9 +134,12 @@ rm -rf "$WORK/root/boot/"* "$WORK/rootfs.tar" # diskless hosts don't need /boo
# sshd rejects them ("Permissions 640 ... too open") and refuses to start.
# RHEL's sshd-keygen@.service regenerates them with correct perms before sshd
# starts, into the writable volatile overlay. NOTE: with the ephemeral overlay
-# they regenerate EVERY boot, so the host key changes each reboot (SSH clients
-# will warn) — for a stable identity, persist them or derive from the TPM
-# (future; ties to the hostnqn/identity model).
+# they regenerate EVERY boot, so the raw host key changes each reboot. This no
+# longer causes client TOFU warnings: fleet-ssh-hostcert (files/ssh-hostcert,
+# enabled via 2b-ssh-hostcert) gets the per-boot key signed by the fleet SSH CA
+# at boot, so admins trust every host via one `@cert-authority` line instead of
+# pinning a per-boot key (F-02 / POA&M P-17; docs/ssh-host-certificate-design.md).
+# A STABLE TPM-resident host key (Design B) remains a deferred follow-on.
rm -f "$WORK/root/etc/ssh/"ssh_host_*
# Fail loudly if labels didn't make it — shipping an unlabeled enforcing image
diff --git a/serving/dot1x-bench/docker-compose.yml b/serving/dot1x-bench/docker-compose.yml
index 35710ed..fc18e02 100644
--- a/serving/dot1x-bench/docker-compose.yml
+++ b/serving/dot1x-bench/docker-compose.yml
@@ -82,5 +82,15 @@ services:
BROKER_ADMIN_CERT: "/pki/broker/server.crt"
BROKER_ADMIN_KEY: "/pki/broker/server.key"
BROKER_ADMIN_CLIENT_CA: "/pki/broker/admin-ca.crt"
+ # HOST plane (SSH host-cert issuance, F-02/P-17). mTLS on the boot LAN:
+ # FLEET-signed server cert + the fleet CA (root+intermediate) as the client
+ # CA that verifies each host's TPM identity. Certs issued by
+ # step-ca/ssh-ca-bootstrap.sh (run it once after bootstrap.sh). 0.0.0.0 so
+ # booted hosts can reach it — firewall to the boot LAN.
+ BROKER_HOST_ADDR: "0.0.0.0:9444"
+ BROKER_HOST_CERT: "/pki/broker/host-server.crt"
+ BROKER_HOST_KEY: "/pki/broker/host-server.key"
+ BROKER_HOST_CLIENT_CA: "/pki/broker/fleet-client-ca.crt"
+ STEP_SSH_CERT_NOT_AFTER: "720h"
volumes:
- ./pki:/pki:ro
diff --git a/serving/dot1x-bench/step-ca/ssh-ca-bootstrap.sh b/serving/dot1x-bench/step-ca/ssh-ca-bootstrap.sh
new file mode 100755
index 0000000..e7e1c04
--- /dev/null
+++ b/serving/dot1x-bench/step-ca/ssh-ca-bootstrap.sh
@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# ssh-ca-bootstrap.sh — enable the fleet SSH host CA so booted hosts can get their
+# per-boot SSH HOST key signed VIA THE ENROL-BROKER (files/ssh-hostcert →
+# fleet-ssh-hostcert → broker host plane → step-ca), killing per-boot TOFU
+# (F-02 / POA&M P-17). Run ONCE after bootstrap.sh, from serving/dot1x-bench/.
+# Pairs with docs/ssh-host-certificate-design.md.
+#
+# 1. enable step-ca's SSH CA (generate host+user CA keys; add the ssh block)
+# 2. enable SSH host-cert issuance on the existing 'enrol' JWK provisioner
+# (the broker already authenticates to step-ca with it)
+# 3. issue the broker HOST-PLANE server cert (fleet-signed; the booted host
+# verifies it against radius-ca.pem) + a root+intermediate client-CA bundle
+# (verifies the host's TPM identity cert)
+# 4. export the SSH HOST CA public key (-> the admin @cert-authority line)
+#
+# The signing path is BROKER-mediated: step-ca stays behind the single front door;
+# hosts never reach it directly. `step` runs INSIDE the CA container. Flags vary
+# across step / step-ca versions — this is a BENCH-VERIFY scaffold. Reads .env.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+[ -f .env ] && . ./.env
+CA_DNS=${CA_DNS:-ca.fleet.lab}
+CA_PORT=${CA_PORT:-8443}
+CA_CONNECT=${CA_CONNECT:-localhost}
+CA_URL="https://${CA_CONNECT}:${CA_PORT}"
+PKI=pki
+PROVISIONER=${PROVISIONER:-enrol}
+# The DNS name booted hosts dial for the broker host plane (must be in the server
+# cert SAN and resolve via the fleet dnsmasq). Reuses boot.fleet.lab by default.
+HOST_PLANE_CN=${HOST_PLANE_CN:-boot.fleet.lab}
+
+PW="$PKI/stepca/password"
+[ -e "$PW" ] || { [ -e "$PKI/stepca/secrets/password" ] && PW="$PKI/stepca/secrets/password"; }
+[ -r "$PW" ] || { echo "ERROR: CA password $PW missing — run bootstrap.sh first." >&2; exit 1; }
+CONTAINER_PW="/home/step/${PW#"$PKI/stepca/"}"
+
+step() { docker compose exec -T step-ca step "$@"; }
+incca() { docker compose exec -T step-ca "$@"; }
+
+CA_JSON="$PKI/stepca/config/ca.json"
+[ -f "$CA_JSON" ] || { echo "ERROR: $CA_JSON not found — is step-ca up?" >&2; exit 1; }
+
+restart_ca() {
+ docker compose restart step-ca >/dev/null
+ for _ in $(seq 1 50); do curl -fsS -k "$CA_URL/health" >/dev/null 2>&1 && break; sleep 0.2; done
+}
+
+# --- 1. SSH CA keys + ca.json ssh block -------------------------------------
+# step-ca signs SSH certs with dedicated SSH CA keys (separate from the X.509
+# root). `step ca init --ssh` creates them at init; to add them to an already-
+# initialised CA we generate two EC keypairs and reference them in ca.json.ssh.
+# BENCH-VERIFY: key format/password expectations vary by version.
+echo "==> generating SSH host/user CA keys (if absent)"
+for kind in host user; do
+ if ! incca test -f "/home/step/secrets/ssh_${kind}_ca_key"; then
+ incca step crypto keypair \
+ "/home/step/secrets/ssh_${kind}_ca_key.pub" \
+ "/home/step/secrets/ssh_${kind}_ca_key" \
+ --kty EC --curve P-256 --no-password --insecure --force
+ fi
+done
+
+echo "==> patching ca.json ssh block (idempotent)"
+if python3 - "$CA_JSON" <<'PY'
+import json,sys
+p=sys.argv[1]
+c=json.load(open(p))
+want={"hostKey":"/home/step/secrets/ssh_host_ca_key",
+ "userKey":"/home/step/secrets/ssh_user_ca_key"}
+if c.get("ssh")==want: sys.exit(1) # already set — no restart needed
+c["ssh"]=want
+json.dump(c,open(p,"w"),indent=2)
+PY
+then
+ echo " ssh block added; restarting step-ca"; restart_ca
+else
+ echo " ssh block already present"
+fi
+
+# --- 2. enable SSH host certs on the 'enrol' provisioner ---------------------
+# The broker authenticates to step-ca with this JWK provisioner (signer.go). It
+# must be allowed to issue SSH HOST certs. BENCH-VERIFY the exact subcommand/flag
+# on your step version (some use `provisioner update --ssh`).
+echo "==> enabling SSH on provisioner '${PROVISIONER}' (BENCH-VERIFY the flag)"
+incca step ca provisioner update "${PROVISIONER}" --ssh 2>/dev/null \
+ && restart_ca \
+ || echo " NOTE: could not auto-enable SSH on '${PROVISIONER}' — enable it by hand (step ca provisioner update ${PROVISIONER} --ssh) and restart step-ca."
+
+# --- 3. broker host-plane server cert + fleet client-CA bundle --------------
+# The host plane is mTLS: its SERVER cert must be FLEET-signed (the booted host
+# verifies it against radius-ca.pem), and its CLIENT CA must verify the host's
+# TPM identity leaf (root + intermediate).
+echo "==> issuing broker host-plane server cert (CN ${HOST_PLANE_CN})"
+incca mkdir -p /export/broker
+step ca certificate "${HOST_PLANE_CN}" \
+ /export/broker/host-server.crt /export/broker/host-server.key \
+ --ca-url "$CA_URL" --root /export/root_ca.crt \
+ --provisioner "${PROVISIONER}" --provisioner-password-file "$CONTAINER_PW" \
+ --not-after 2160h --force
+echo "==> building fleet client-CA bundle (root + intermediate) -> $PKI/broker/fleet-client-ca.crt"
+mkdir -p "$PKI/broker"
+cat "$PKI/root_ca.crt" > "$PKI/broker/fleet-client-ca.crt"
+[ -f "$PKI/intermediate_ca.crt" ] && cat "$PKI/intermediate_ca.crt" >> "$PKI/broker/fleet-client-ca.crt"
+
+# --- 4. export the SSH host CA public key (admin trust anchor) ---------------
+echo "==> exporting SSH host CA public key -> $PKI/ssh_host_ca.pub"
+incca cp /home/step/secrets/ssh_host_ca_key.pub /export/ssh_host_ca.pub
+echo
+echo "Admin rollout — add ONE line to each admin's ~/.ssh/known_hosts (or a system"
+echo "known_hosts), so every fleet host is trusted via the CA instead of TOFU:"
+echo
+echo " @cert-authority *.${CA_DNS#ca.} $(cat "$PKI/ssh_host_ca.pub" 2>/dev/null || echo '')"
+echo
+echo "Then enable the broker host plane (dot1x-bench compose already wires"
+echo "BROKER_HOST_ADDR + the certs issued above) and rebuild the secure-path image."
+echo "On a booted+enrolled host, ssh-hostcert.timer POSTs its host key to the broker"
+echo "and installs /etc/ssh/ssh_host_ecdsa_key-cert.pub."
diff --git a/serving/enrol-broker/README.md b/serving/enrol-broker/README.md
index 48afe58..5b5cb0f 100644
--- a/serving/enrol-broker/README.md
+++ b/serving/enrol-broker/README.md
@@ -10,7 +10,7 @@ Authoritative design: [`../../docs/tpm-enrolment-design.md`](../../docs/tpm-enro
This is **v1** (fingerprint-only OOB assurance; inline empty-NV vehicle on the host
side). TPM attestation and the host-side dracut branch are the next phases.
-## Two listeners, by design
+## Three listeners, by design
```
PUBLIC (plain HTTP, behind the serving nginx /enrol/) UNAUTHENTICATED
@@ -23,10 +23,28 @@ ADMIN (mTLS, management network / loopback ONLY) admin client cert
GET /pending JSON queue
POST /approve/{id} OOB-approve -> step ca sign -> store cert
POST /deny/{id} reject
+
+HOST (mTLS, boot LAN) FLEET host client cert
+ POST /ssh/hostcert {publicKey, principals, keyID} -> {cert}
+ GET /healthz
```
The public side is deliberately tiny and stdlib-only — it is the only thing
-reachable by un-enrolled devices. The admin side never touches the boot LAN.
+reachable by un-enrolled devices. The admin side never touches the boot LAN. The
+**host plane** (F-02/P-17) is the automatic, self-authenticating counterpart of
+enrolment: an already-enrolled host proves itself with its **TPM identity** as the
+mTLS client cert (verified to the fleet CA) and the broker has step-ca sign an SSH
+**host** certificate — no human approval, no CA secret on the host. This keeps
+step-ca behind the single front door for SSH host certs too. The host plane is
+**disabled unless `BROKER_HOST_ADDR` is set**. Enable the SSH CA on step-ca +
+issue its certs with `serving/dot1x-bench/step-ca/ssh-ca-bootstrap.sh`; the client
+is `files/ssh-hostcert` (docs/ssh-host-certificate-design.md).
+
+> **Client CA differs by plane:** the ADMIN plane uses a *dedicated admin CA*
+> (`admin-pki.sh`) — deliberately **not** the fleet root. The HOST plane uses the
+> **fleet CA** (`BROKER_HOST_CLIENT_CA` = root+intermediate), because host clients
+> present fleet-signed TPM identities. Its *server* cert must also be fleet-signed
+> so the booted host verifies it against `radius-ca.pem`.
## How identity is gated
@@ -84,6 +102,11 @@ authenticate to the admin plane and approve enrolments (privilege escalation).
| `HOSTNQN_BASE` | `nqn.2026-06.org.example.fleet:host-` | hostnqn = base + cert-serial |
| `BROKER_ADMIN_CERT` / `_KEY` / `_CLIENT_CA` | — | admin mTLS (required unless insecure) |
| `BROKER_ADMIN_INSECURE` | `false` | **dev only**: plaintext admin, no client-cert auth |
+| `BROKER_HOST_ADDR` | — (disabled) | SSH host-cert plane listener; unset ⇒ off |
+| `BROKER_HOST_CERT` / `_KEY` | — | host-plane server cert/key (**fleet-signed**) |
+| `BROKER_HOST_CLIENT_CA` | `STEP_CA_ROOT` | verifies host TPM identities (**fleet** root+intermediate) |
+| `BROKER_HOST_INSECURE` | `false` | **dev only**: plaintext host plane, no client-cert auth |
+| `STEP_SSH_CERT_NOT_AFTER` | `720h` | issued SSH host-cert validity |
Swap `wordlist.txt` for the 2048-word BIP39 list (11 bits/word) for more entropy
per word; it just needs to be a power-of-two number of lines.
diff --git a/serving/enrol-broker/host.go b/serving/enrol-broker/host.go
new file mode 100644
index 0000000..6d3c0ae
--- /dev/null
+++ b/serving/enrol-broker/host.go
@@ -0,0 +1,135 @@
+// host.go — the mTLS HOST plane: enrolled hosts get their per-boot SSH host key
+// signed by the fleet SSH CA.
+//
+// This is the THIRD listener, distinct from the two in main.go:
+//
+// HOST (mTLS, boot-LAN reachable) -- fleet-CA host client cert:
+// POST /ssh/hostcert {publicKey, principals, keyID} -> {cert}
+//
+// It is the automatic, self-authenticating counterpart of enrolment: a host
+// proves it is enrolled by presenting its TPM identity as the mTLS client cert
+// (verified to the fleet CA), and the broker has step-ca sign an SSH HOST cert —
+// no human approval, no CA secret on the host. Admins then trust every fleet host
+// via one `@cert-authority` line instead of per-boot TOFU (F-02 / POA&M P-17).
+// Keep step-ca itself off the boot LAN; the broker is the single front door.
+package main
+
+import (
+ "crypto/tls"
+ "crypto/x509"
+ "encoding/json"
+ "log"
+ "net/http"
+ "os"
+ "time"
+)
+
+type sshHostCertRequest struct {
+ PublicKey string `json:"publicKey"`
+ Principals []string `json:"principals"`
+ KeyID string `json:"keyID"`
+}
+
+type sshHostCertResponse struct {
+ Cert string `json:"cert,omitempty"`
+ Error string `json:"error,omitempty"`
+}
+
+func (b *broker) serveHost() {
+ if b.cfg.hostAddr == "" {
+ log.Printf("host plane disabled (set BROKER_HOST_ADDR + BROKER_HOST_CERT/KEY to enable SSH host-cert issuance)")
+ return
+ }
+
+ mux := http.NewServeMux()
+ mux.HandleFunc("POST /ssh/hostcert", b.handleSSHHostCert)
+ mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(http.StatusOK) })
+
+ srv := &http.Server{
+ Addr: b.cfg.hostAddr,
+ Handler: mux,
+ ReadHeaderTimeout: 5 * time.Second,
+ ReadTimeout: 10 * time.Second,
+ WriteTimeout: 40 * time.Second, // signing blocks on step-ca
+ IdleTimeout: 30 * time.Second,
+ MaxHeaderBytes: 16 << 10,
+ }
+
+ if b.cfg.hostInsecure {
+ log.Printf("WARNING: BROKER_HOST_INSECURE=true — SSH host plane is PLAINTEXT with NO client-cert auth. DEV ONLY.")
+ log.Fatalf("host listener: %v", srv.ListenAndServe())
+ return
+ }
+ if b.cfg.hostCert == "" || b.cfg.hostKey == "" {
+ log.Fatalf("host mTLS requires BROKER_HOST_CERT and BROKER_HOST_KEY (or BROKER_HOST_INSECURE=true for dev)")
+ }
+ clientCAPath := b.cfg.hostClientCA
+ if clientCAPath == "" {
+ clientCAPath = b.cfg.caRoot // default: the fleet root that signs host identities
+ }
+ cert, err := tls.LoadX509KeyPair(b.cfg.hostCert, b.cfg.hostKey)
+ if err != nil {
+ log.Fatalf("host server cert: %v", err)
+ }
+ caPEM, err := os.ReadFile(clientCAPath)
+ if err != nil {
+ log.Fatalf("host client CA: %v", err)
+ }
+ pool := x509.NewCertPool()
+ if !pool.AppendCertsFromPEM(caPEM) {
+ log.Fatalf("host client CA %s contains no certificates", clientCAPath)
+ }
+ srv.TLSConfig = &tls.Config{
+ Certificates: []tls.Certificate{cert},
+ ClientAuth: tls.RequireAndVerifyClientCert, // must be an enrolled fleet host
+ ClientCAs: pool,
+ MinVersion: tls.VersionTLS12,
+ }
+ log.Printf("host plane up: %s (mTLS, fleet-CA host client certs) ssh-signer=%s", b.cfg.hostAddr, b.sshSigner.Kind())
+ log.Fatalf("host listener: %v", srv.ListenAndServeTLS("", ""))
+}
+
+func (b *broker) handleSSHHostCert(w http.ResponseWriter, r *http.Request) {
+ // RequireAndVerifyClientCert already guaranteed the peer chains to the fleet
+ // CA; the presented identity is who we're issuing for.
+ peerCN := hostPeerCN(r)
+
+ r.Body = http.MaxBytesReader(w, r.Body, 16<<10)
+ var req sshHostCertRequest
+ if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+ writeSSHErr(w, http.StatusBadRequest, "invalid JSON body")
+ return
+ }
+ if req.KeyID == "" {
+ req.KeyID = peerCN
+ }
+ if len(req.Principals) == 0 {
+ writeSSHErr(w, http.StatusBadRequest, "no principals requested")
+ return
+ }
+
+ ctx, cancel := ctxWithTimeout(35 * time.Second)
+ defer cancel()
+ certLine, err := b.sshSigner.SignHost(ctx, req.PublicKey, req.KeyID, req.Principals)
+ if err != nil {
+ log.Printf("audit ssh-hostcert-FAILED cn=%q principals=%v err=%v", peerCN, req.Principals, err)
+ writeSSHErr(w, http.StatusBadGateway, "signing failed: "+err.Error())
+ return
+ }
+ log.Printf("audit SSH-HOSTCERT cn=%q keyid=%q principals=%v", peerCN, req.KeyID, req.Principals)
+ writeJSON(w, http.StatusOK, sshHostCertResponse{Cert: certLine})
+}
+
+func hostPeerCN(r *http.Request) string {
+ if r.TLS != nil && len(r.TLS.PeerCertificates) > 0 {
+ if cn := r.TLS.PeerCertificates[0].Subject.CommonName; cn != "" {
+ return cn
+ }
+ return "unknown-host"
+ }
+ return "dev-insecure"
+}
+
+func writeSSHErr(w http.ResponseWriter, code int, msg string) {
+ writeJSON(w, code, sshHostCertResponse{Error: msg})
+}
diff --git a/serving/enrol-broker/host_test.go b/serving/enrol-broker/host_test.go
new file mode 100644
index 0000000..92c2164
--- /dev/null
+++ b/serving/enrol-broker/host_test.go
@@ -0,0 +1,72 @@
+package main
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+)
+
+func newTestBroker() *broker {
+ return &broker{cfg: loadConfig(), sshSigner: mockSSHSigner{}}
+}
+
+func TestHandleSSHHostCert_OK(t *testing.T) {
+ b := newTestBroker()
+ body, _ := json.Marshal(sshHostCertRequest{
+ PublicKey: "ecdsa-sha2-nistp256 AAAAB3Nz root@fleet",
+ Principals: []string{"host01", "host01.fleet.lab"},
+ KeyID: "host01.fleet.lab",
+ })
+ req := httptest.NewRequest(http.MethodPost, "/ssh/hostcert", strings.NewReader(string(body)))
+ rec := httptest.NewRecorder()
+
+ b.handleSSHHostCert(rec, req)
+
+ if rec.Code != http.StatusOK {
+ t.Fatalf("status = %d, body=%s", rec.Code, rec.Body.String())
+ }
+ var resp sshHostCertResponse
+ if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+ t.Fatal(err)
+ }
+ if !strings.HasPrefix(resp.Cert, "ecdsa-sha2-nistp256-cert-v01@openssh.com ") {
+ t.Errorf("cert line = %q", resp.Cert)
+ }
+ if !strings.Contains(resp.Cert, "host01.fleet.lab") {
+ t.Errorf("cert should carry keyID/principals: %q", resp.Cert)
+ }
+}
+
+func TestHandleSSHHostCert_NoPrincipals(t *testing.T) {
+ b := newTestBroker()
+ body, _ := json.Marshal(sshHostCertRequest{PublicKey: "ecdsa-sha2-nistp256 AAAA x", KeyID: "h"})
+ req := httptest.NewRequest(http.MethodPost, "/ssh/hostcert", strings.NewReader(string(body)))
+ rec := httptest.NewRecorder()
+
+ b.handleSSHHostCert(rec, req)
+
+ if rec.Code != http.StatusBadRequest {
+ t.Fatalf("want 400 for missing principals, got %d", rec.Code)
+ }
+}
+
+func TestHandleSSHHostCert_BadJSON(t *testing.T) {
+ b := newTestBroker()
+ req := httptest.NewRequest(http.MethodPost, "/ssh/hostcert", strings.NewReader("{not json"))
+ rec := httptest.NewRecorder()
+
+ b.handleSSHHostCert(rec, req)
+
+ if rec.Code != http.StatusBadRequest {
+ t.Fatalf("want 400 for bad JSON, got %d", rec.Code)
+ }
+}
+
+func TestMockSSHSignerRejectsEmptyKey(t *testing.T) {
+ if _, err := (mockSSHSigner{}).SignHost(context.Background(), "", "h", []string{"h"}); err == nil {
+ t.Error("expected error on malformed public key")
+ }
+}
diff --git a/serving/enrol-broker/main.go b/serving/enrol-broker/main.go
index 0d7f215..fe7d572 100644
--- a/serving/enrol-broker/main.go
+++ b/serving/enrol-broker/main.go
@@ -63,6 +63,13 @@ type config struct {
adminKey string
adminClientCA string
adminInsecure bool
+ // host plane (SSH host-cert issuance) mTLS
+ hostAddr string
+ hostCert string
+ hostKey string
+ hostClientCA string
+ hostInsecure bool
+ sshNotAfter string
}
func loadConfig() config {
@@ -87,14 +94,21 @@ func loadConfig() config {
adminKey: env("BROKER_ADMIN_KEY", ""),
adminClientCA: env("BROKER_ADMIN_CLIENT_CA", ""),
adminInsecure: envBool("BROKER_ADMIN_INSECURE", false),
+ hostAddr: env("BROKER_HOST_ADDR", ""), // empty => host plane disabled
+ hostCert: env("BROKER_HOST_CERT", ""),
+ hostKey: env("BROKER_HOST_KEY", ""),
+ hostClientCA: env("BROKER_HOST_CLIENT_CA", ""), // default: caRoot (fleet root)
+ hostInsecure: envBool("BROKER_HOST_INSECURE", false),
+ sshNotAfter: env("STEP_SSH_CERT_NOT_AFTER", "720h"),
}
}
type broker struct {
- cfg config
- store *Store
- signer Signer
- rl *rateLimiter
+ cfg config
+ store *Store
+ signer Signer
+ sshSigner SSHSigner
+ rl *rateLimiter
}
func main() {
@@ -123,7 +137,20 @@ func main() {
log.Fatalf("unknown BROKER_SIGNER %q (want step|mock)", cfg.signerKind)
}
- b := &broker{cfg: cfg, store: store, signer: signer, rl: newRateLimiter(cfg.ratePerMin)}
+ // SSH host-cert signer (host plane) — same step|mock selection as the X.509
+ // enrolment signer, so a mock broker exercises both without a running step-ca.
+ var sshSigner SSHSigner
+ switch cfg.signerKind {
+ case "step":
+ sshSigner = &stepSSHSigner{
+ bin: cfg.stepBin, caURL: cfg.caURL, root: cfg.caRoot,
+ provisioner: cfg.provisioner, passwordFile: cfg.passwordFile, notAfter: cfg.sshNotAfter,
+ }
+ case "mock":
+ sshSigner = mockSSHSigner{}
+ }
+
+ b := &broker{cfg: cfg, store: store, signer: signer, sshSigner: sshSigner, rl: newRateLimiter(cfg.ratePerMin)}
// background reaper: expire timed-out requests + evict old decided ones.
go func() {
@@ -138,11 +165,12 @@ func main() {
}()
var wg sync.WaitGroup
- wg.Add(2)
+ wg.Add(3)
go func() { defer wg.Done(); b.servePublic() }()
go func() { defer wg.Done(); b.serveAdmin() }()
- log.Printf("enrol-broker up: public=%s admin=%s signer=%s words=%d ttl=%s",
- cfg.publicAddr, cfg.adminAddr, signer.Kind(), len(words), cfg.ttl)
+ go func() { defer wg.Done(); b.serveHost() }() // SSH host-cert plane (no-op if BROKER_HOST_ADDR unset)
+ log.Printf("enrol-broker up: public=%s admin=%s host=%s signer=%s words=%d ttl=%s",
+ cfg.publicAddr, cfg.adminAddr, cfg.hostAddr, signer.Kind(), len(words), cfg.ttl)
wg.Wait()
}
diff --git a/serving/enrol-broker/sshsigner.go b/serving/enrol-broker/sshsigner.go
new file mode 100644
index 0000000..47b5d23
--- /dev/null
+++ b/serving/enrol-broker/sshsigner.go
@@ -0,0 +1,130 @@
+// sshsigner.go — issuing SSH HOST certificates for already-enrolled hosts.
+//
+// This is the SSH counterpart of signer.go. Unlike enrolment (unauthenticated,
+// human-approved), an SSH host cert is issued AUTOMATICALLY to a host that
+// authenticates on the host plane with its fleet-CA mTLS identity (host.go) —
+// the cert IS the authorisation. The broker holds the step-ca provisioner
+// credential and drives `step ssh certificate`, so step-ca stays behind the
+// single front door and the host never holds a CA secret. Closes F-02 / P-17.
+//
+// BENCH-VERIFY: the exact `step ssh certificate` sign flags vary across step
+// versions (and the CA must have its SSH host CA enabled — see
+// serving/dot1x-bench/step-ca/ssh-ca-bootstrap.sh). Confirm against your
+// `step version`. The mock path returns a synthetic (non-cryptographic) cert line
+// so the host-plane HTTP flow is testable without a running step-ca.
+package main
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "strings"
+)
+
+// SSHSigner signs an OpenSSH host public key, returning the certificate as a
+// single authorized-keys/HostCertificate line.
+type SSHSigner interface {
+ SignHost(ctx context.Context, pubKeyLine, keyID string, principals []string) (certLine string, err error)
+ Kind() string
+}
+
+// --- production: step-ca SSH host CA via the `step` CLI ---------------------
+
+type stepSSHSigner struct {
+ bin string
+ caURL string
+ root string
+ provisioner string
+ passwordFile string
+ notAfter string
+}
+
+func (s *stepSSHSigner) Kind() string { return "step" }
+
+func (s *stepSSHSigner) SignHost(ctx context.Context, pubKeyLine, keyID string, principals []string) (string, error) {
+ if strings.TrimSpace(pubKeyLine) == "" {
+ return "", fmt.Errorf("empty public key")
+ }
+ if keyID == "" {
+ return "", fmt.Errorf("empty key id")
+ }
+ if len(principals) == 0 {
+ return "", fmt.Errorf("no principals requested")
+ }
+ dir, err := os.MkdirTemp("", "sshhost-*")
+ if err != nil {
+ return "", err
+ }
+ defer os.RemoveAll(dir)
+
+ // `step ssh certificate --sign ` writes -cert.pub next to
+ // the input; give the input a .pub name so the derived cert path is stable.
+ pubPath := filepath.Join(dir, "hostkey.pub")
+ certPath := filepath.Join(dir, "hostkey-cert.pub")
+ if err := os.WriteFile(pubPath, []byte(strings.TrimRight(pubKeyLine, "\n")+"\n"), 0o600); err != nil {
+ return "", err
+ }
+
+ args := []string{
+ "ssh", "certificate",
+ "--host", // HOST certificate (not a user cert)
+ "--sign", // sign the EXISTING public key (don't generate one)
+ "--no-password", "--insecure", // non-interactive; key file is already on disk
+ "--provisioner", s.provisioner,
+ "--provisioner-password-file", s.passwordFile,
+ "--ca-url", s.caURL,
+ "--root", s.root,
+ }
+ for _, p := range principals {
+ args = append(args, "--principal", p)
+ }
+ if s.notAfter != "" {
+ args = append(args, "--not-after", s.notAfter)
+ }
+ args = append(args, keyID, pubPath)
+
+ if _, err := runStep(ctx, s.bin, args...); err != nil {
+ return "", fmt.Errorf("step ssh certificate: %w", err)
+ }
+ cert, err := os.ReadFile(certPath)
+ if err != nil {
+ return "", fmt.Errorf("read signed cert: %w", err)
+ }
+ return strings.TrimSpace(string(cert)), nil
+}
+
+// runStep executes `step ...`, returning stdout (stderr folded into the error).
+// We never log argv (it can carry a token) or the password-file contents.
+func runStep(ctx context.Context, bin string, args ...string) (string, error) {
+ cmd := exec.CommandContext(ctx, bin, args...)
+ out, err := cmd.Output()
+ if err != nil {
+ var ee *exec.ExitError
+ if errors.As(err, &ee) {
+ return "", fmt.Errorf("%w: %s", err, strings.TrimSpace(string(ee.Stderr)))
+ }
+ return "", err
+ }
+ return string(out), nil
+}
+
+// --- dev only: synthetic cert line -----------------------------------------
+
+// mockSSHSigner returns a deterministic, NON-cryptographic cert line so the
+// host-plane HTTP path is testable without a running step-ca. LAB/TEST ONLY.
+type mockSSHSigner struct{}
+
+func (mockSSHSigner) Kind() string { return "mock" }
+
+func (mockSSHSigner) SignHost(_ context.Context, pubKeyLine, keyID string, principals []string) (string, error) {
+ fields := strings.Fields(pubKeyLine)
+ if len(fields) < 2 {
+ return "", fmt.Errorf("malformed public key")
+ }
+ // Not a real certificate — just an identifiable placeholder blob.
+ return fmt.Sprintf("ecdsa-sha2-nistp256-cert-v01@openssh.com MOCK-%s-%s %s",
+ keyID, strings.Join(principals, ","), fields[len(fields)-1]), nil
+}
diff --git a/serving/enrol-broker/store.go b/serving/enrol-broker/store.go
index dba53f2..c24b3ee 100644
--- a/serving/enrol-broker/store.go
+++ b/serving/enrol-broker/store.go
@@ -287,9 +287,9 @@ func fingerprint(pubDER, nonce []byte, words []string, n int) (string, error) {
stream := digestStream(pubDER, nonce, (n*bpw+7)/8)
out := make([]string, 0, n)
bitpos := 0
- for i := 0; i < n; i++ {
+ for range n {
idx := 0
- for k := 0; k < bpw; k++ {
+ for range bpw {
byteIdx := bitpos / 8
bit := 7 - uint(bitpos%8)
b := (stream[byteIdx] >> bit) & 1