diskless-workstation/docs/tpm-enrolment-design.md

TPM identity enrolment + the fleet identity lifecycle — design note

Status: DESIGN (consolidated 2026-06-28). Supersedes the scattered decisions in docs/TODO.md #11 (which it folds in) and closes the bootstrap gap left open by docs/fleet-management-design.md. The bench stand-in (serving/dot1x-bench/enrol/tpm-provision.sh) already proves the cryptography end-to-end minus the human-approval queue; the only unbuilt piece is the enrolment broker.

How a diskless host acquires — and keeps — its one cryptographic identity: a signing key at TPM handle 0x81010001 and a cert at NV index 0x01800001. Invariant #1 forbids baking any per-host state into the image, so this identity must be minted at enrolment, at runtime, from the TPM. That single identity is then reused for everything: 802.1X EAP-TLS, the NVMe hostnqn (derived from the cert serial), and mTLS to the fleet-manager. This note is the authoritative design for how it is born, used, renewed, and revoked.

The gap this closes

fleet-management-design.md authenticates every host by mTLS keyed on the TPM cert — but never says how the cert gets onto the host. That is a chicken-and-egg: mTLS needs a cert; the cert needs enrolment; enrolment is the one thing that cannot itself be mTLS-authenticated (an empty-NV host has no client identity yet). Enrolment is therefore the sole unauthenticated bootstrap in the whole system, and the management plane's entire trust model rests on it. Treating the enrolment broker as the fleet-manager's one unauthenticated endpoint — rather than a separate box — is what makes the two designs one coherent identity story.

Design philosophy (forced by the architecture invariants)

1. One identity, minted once, reused everywhere. Key 0x81010001 + cert NV 0x01800001 = 802.1X identity = NVMe hostnqn (…:host-<cert-serial>) = mTLS client identity. There is no second secret. (Invariant #1.)
2. The private key never leaves the TPM. Generated in the TPM; only a CSR and the issued cert ever cross the wire — both are public. This is why the pre-auth, pre-MACsec enrolment link being plaintext is acceptable.
3. Humans authorise; machines sign. step-ca can sign but has no notion of "should I." The authorisation decision is a human OOB act (fingerprint cross-check). No auto-sign of unauthenticated CSRs, ever.
4. Enrolment is the birth of the inventory record. The fleet-manager keys every host by cert-serial / hostnqn; that key does not exist until enrolment. So approval is simultaneously INSERT host and the moment a human binds physical identity → cryptographic identity (asset tag / switch port / location → cert serial). Every downstream signal hangs off this record.
5. Integrity of the pre-auth path comes from Secure Boot, not the network. The UKI fetch and the enrolment exchange both happen pre-auth on an untrusted, unencrypted L2. The boot is trustworthy because the UKI is Secure-Boot-signed (#8), not because the wire is. Enrolment design and Secure Boot are two halves of the same "the pre-auth path is hostile" assumption.

The identity lifecycle (the load-bearing state machine)

Triggered by the state of NV 0x01800001 and the cert within it. The three events are deliberately split — conflating them is a security regression:

  EMPTY NV                  → ENROL    human OOB approval; broker→step-ca sign; write NV.
                                       Births the fleet-manager inventory record.
  VALID KEY + cert near/at  → RENEW    automatic, NO human. The host already holds a
  expiry                               CA-trusted key; re-sign the same key, rewrite NV.
  AUTH FAILS, cert present   → ALERT    retry + raise an alert. NEVER auto-re-enrol —
                                       that would mask a revocation and churn keys on a
                                       transient RADIUS/CA outage.
  Re-enrol after first time  → ADMIN    explicit admin action (clear/flag the host); not
                                       reachable from any automatic path.

• Renew is safe to automate precisely because the host proves possession of an already-trusted key — no human needed, no new trust established.
• Auth-failure must not re-enrol. A revoked host that re-enrolled itself would defeat revocation. Failures alert; they never mint new identity.

Components

1. TPM key + NV cert (exists — tpm-provision.sh)

Key generated in the TPM, persisted at 0x81010001; CSR built with it via the openssl tpm2 provider (key never leaves the TPM); issued cert written DER to NV 0x01800001. At boot, dot1x-macsec-up.sh reads the cert from NV, wpa_supplicant signs EAP-TLS with the handle key, and the hostnqn is derived from the cert serial. All of this is built and bench-proven; enrolment just replaces the manual sign step with a brokered, human-gated one.

2. The enrolment broker (the only new component)

A small service that turns "step-ca can sign" into "step-ca signs only what a human approved." Stateless-leaning; pending state is short-lived and server-side.

API (HTTPS; image trusts the serving CA):

Route	Auth	Action
POST /enrol/request	none (bootstrap)	accept CSR + self-reported device context; create a time-boxed PENDING record; return enrol-id + the fingerprint to display
GET /enrol/status/{enrol-id}	none (bootstrap)	host polls → PENDING | APPROVED+cert | DENIED | EXPIRED
GET /enrol/pending	mTLS, admin	the approval queue (one entry per pending CSR, with context + fingerprint)
POST /enrol/approve/{enrol-id}	mTLS, admin	bind physical context → record; hand CSR to step-ca; store the issued cert
POST /enrol/deny/{enrol-id}	mTLS, admin	reject + audit

The request/status routes are the sole unauthenticated surface; pending/ approve/deny are admin-only mTLS — i.e. they are already the fleet-manager's authenticated plane. This is why the broker is the fleet-manager's bootstrap endpoint, not a separate trust domain.

Device context (what an un-enrolled host can self-report, for the admin to recognise what they are approving): NIC MAC, DMI system UUID/serial, TPM EK public-key hash, and switch port via LLDP if available. Context is advisory — the fingerprint is the cryptographic anchor.

3. OOB fingerprint approval (the human gate) — v1 assurance

v1 ships fingerprint-only (TPM attestation is the documented upgrade, § "Stronger assurance"). The flow:

• fingerprint = BIP39-encode( SHA-256( CSR_SubjectPublicKeyInfo_DER || server_nonce )[:N bits] ) — both broker and host compute it identically from the CSR public key and a server-chosen per-enrol-id nonce.
• The host shows it on the Plymouth splash (states only — invariant #1 — never per-host secrets; the fingerprint is public). The admin reads it off the physical device's screen and matches it to that device's entry in GET /enrol/pending.
• What it proves: the queue entry the admin approves carries the same key as the device physically in front of them. What it does not prove: that the key actually resides in a TPM (that's attestation, below).

Hardening, all required for v1:

• Word-list encoding, not short hex. Hex is grindable; ~6 BIP39 words (~66 bits) reads short but resists collision-grinding.
• Server nonce per enrol-id so an attacker cannot pre-grind a key whose fingerprint collides with a target device's (the nonce is unknown until after submission, and is per-request).
• Rate-limit + time-boxed pending (expire unapproved requests) to bound queue flooding.
• Show device context beside the fingerprint so the admin approves a specific MAC/serial, not just a matching string.

4. step-ca (exists — serving/dot1x-bench/step-ca/)

The fleet CA. The broker calls it on approval (token-gated step ca sign, exactly as tpm-provision.sh does today). Same root that is baked as radius-ca.pem and pinned for mTLS — one trust anchor across 802.1X, NVMe, and management.

5. Relationship to the fleet-manager and host-api

• Broker ⊂ fleet-manager. /enrol/request + /enrol/status are the fleet-manager's only unauthenticated routes; /enrol/pending|approve|deny are its admin mTLS plane. Approval writes the inventory record the manager keys everything else on. Build the broker standalone first (fastest path to the state machine), but design it to fold into the mgmt service with no rewrite — same Go style, same step-ca anchor, same data model.
• host-api is not in the enrolment path (it is loopback/post-boot; the host has no cert during enrolment). The tie is downstream: the fleet-manager agent (the push sibling of fleet-hostapi) authenticates with the enrolled cert over mTLS, and inherits host-api's hardened posture (DynamicUser, fapolicyd-trusted, reproducible static build). One identity, three stages: enrol mints it → host-api/agent uses it → renew refreshes it.

End-to-end enrolment flow

  empty-NV host (provisioning UKI)        broker (= fleet-mgr bootstrap)     admin        step-ca
  ───────────────────────────────         ─────────────────────────────     ─────        ───────
  1. key in TPM @0x81010001
  2. build CSR (key never leaves)
  3. POST /enrol/request (CSR+context) ─▶  create PENDING, pick nonce,
                                           compute fingerprint
     ◀── enrol-id + fingerprint ─────────
  4. show fingerprint on Plymouth
                                           GET /enrol/pending ◀──────────── 5. read queue (mTLS)
                                                                            6. cross-check fp on
                                                                               the device screen
                                           POST /enrol/approve/{id} ◀────── 7. approve + bind
                                                                               physical→crypto
                                           bind context → INSERT host,
                                           sign CSR ──────────────────────────────────▶ issue cert
                                           store cert ◀───────────────────────────────
  8. GET /enrol/status/{id} (poll) ───▶
     ◀── APPROVED + cert ────────────────
  9. write cert DER → NV 0x01800001
  10. reboot into production UKI → 802.1X EAP-TLS → mTLS mgmt

Where it runs: a provisioning UKI/mode

Enrolment must not live in the production initramfs. The boot hook ordering is load-bearing (invariant #2: NV-cert → supplicant → Authorized+macsec0 → DHCP → hostnqn); parking that sequence on a multi-minute human-approval wait is unacceptable. Enrolment runs in a separate provisioning UKI / mode — the same vehicle as #10 (Secure Boot key enrolment) — entered deliberately (empty-NV detect, or an explicit provisioning boot), never as a branch inside the normal hot path. The production UKI only ever reads an already-present cert; it never enrols.

Pre-auth network placement

The firmware cannot do 802.1X, so the UKI fetch (DHCP/DNS/TFTP/HTTP to the serving host) is always pre-auth — the secure model therefore already requires a pre-auth permit-set (low-impact 802.1X / pre-auth dACL / boot→secure dynamic VLAN; RADIUS returns the secure VLAN on Access-Accept). Enrolment is just one more entry in that set: expose /enrol/ on the existing serving nginx, reverse-proxied to the broker. No new network mechanism. Pre-auth traffic has no MACsec (plaintext L2) — fine here, because CSR/cert are public and the fingerprint supplies authenticity, and because boot integrity comes from the SB-signed UKI.

Bench caveat: hostapd wired is strictly port-based (no pre-auth per-flow ACL): before EAP success it passes nothing, so the rig cannot reproduce "boot + enrol pre-auth on the same port." Model the pre-auth state with a separate provisioning bridge/VLAN on the bench; validate the in-place low-impact pre-auth permit on the 820's real switch.

Security posture / threat model

• Sole unauthenticated surface = /enrol/request|status. Scope the pre-auth permit to only these routes + the serving host; everything else is mTLS.
• No auto-sign. Every cert traces to a human OOB approval; the broker never signs on its own.
• Fingerprint binds queue↔device (v1). It does not prove TPM residency or prevent a determined insider — it raises the bar to "be physically at the device and have an admin approve it."
• Rate-limit + time-box + audit every request/approve/deny to the collector (the binding event is forensically important).
• Revocation is real only because auth-failure never auto-re-enrols (see lifecycle). Pair with step-ca CRL/short-lived certs + the renew path.

Stronger assurance (documented upgrade, not v1)

Fingerprint proves "this physical device"; it does not prove "the key is in a TPM." The residency proof is step-ca's ACME device-attest-01 provisioner (TPM EK/AK attestation): switch enrolment from step ca sign to an ACME exchange with a TPM attestation provisioner on the same CA, anchored to the TPM vendors' EK roots. Together — fingerprint = a human authorised the device, attestation = the key is genuinely TPM-resident — this is the strong SSP R-01 story. Deferred from v1 to keep the first build tractable; the broker's approve step is the natural insertion point (verify the attestation statement before signing). The CA bootstrap already carries a commented acme-attest provisioner block (serving/dot1x-bench/step-ca/bootstrap.sh).

Inventory record born at enrolment

Host (by cert-serial / hostnqn)            ← created at /enrol/approve
  ├─ identity:  cert serial, hostnqn, MAC, TPM EK hash, starship-name
  ├─ binding:   asset tag, switch port, location   ← the human OOB act records this
  ├─ enrolled:  approver, timestamp, fingerprint, attestation? (later)
  └─ (then fleet-manager fills) version / health / usage / desired-state

This is the join key the rest of fleet-management-design.md assumes already exists. Enrolment is where it comes into being.

Phasing

1. Built / proven: TPM key→CSR→sign→NV (manual, tpm-provision.sh); tpm-selftest.sh capability check; step-ca + EAP-TLS bench.
2. v1 (next build): the broker state machine (request/status/pending/approve/ deny) + BIP39 fingerprint + Plymouth display + the /enrol/ nginx permit + the provisioning-mode trigger. Fingerprint-only assurance.
3. Folds into fleet-manager: the admin routes become the mgmt service's authenticated plane; approval writes the shared inventory record.
4. Attestation upgrade: ACME device-attest-01 at the approve step.

Open questions for build time

• openssl TPM2 provider in the provisioning image — tpm2-tss ≠ the provider; tpm-selftest.sh flags whether tpm2-openssl must be added (also affects the wpa_supplicant key-ref form: provider handle: vs tpm2-pkcs11 URI).
• Pending store: in-memory (simplest, lost on broker restart) vs a tiny persistent store. Time-boxed pending makes in-memory acceptable for v1.
• Provisioning UKI vehicle — shared with #10 but not yet built; sequencing.
• Fingerprint length — exact bit count / word count (entropy vs readability).
• Open/test path identity (rd.dot1x=0): MAC/fleet-name is a weak stand-in; gate real enrolment to the secure path, or accept lab-only there.