Repository navigation
Description
Why
A broker SSH key must be made on the broker host, never on an agent machine (docs/setup.md section 6, THREAT-MODEL.md section 5 item 8). Today that is a hand job as root on the broker: ssh-keygen, systemd-creds encrypt, a LoadCredentialEncrypted= line in the unit, and a restart. On a host run by the Ansible role of #193 and its data-only playbook broker-host.yml, everything else is data that a pull tool applies after the owner approves it. The SSH keys are the one part left by hand, because #193 says the role "never writes credential values".
A key that the role makes on the host is not a credential value from outside: the private key is born on the host, is encrypted there at once, and never leaves it. So the role can do this without breaking #193's rule.
What
In the broker side of the role (#193), a data key, for example:
nodkey_ssh_keys:
- name: deploy
type: ed25519 # ed25519 (default), ecdsa-p256, ecdsa-p384 or ecdsa-p521For each name, when /etc/nodkey/credentials/ssh-NAME.cred does not exist:
- make the key in a private temporary directory (0700, on tmpfs, removed in an
alwaysblock), with no passphrase (the broker refuses one; the credential protects it), commentnodkey-NAME; - encrypt it with
systemd-creds encrypt --with-key=… --name=ssh-NAME(a role variable, default as setup.md:host+tpm2whensystemd-creds has-tpm2says yes, elsehost) to a temporary name, then rename it tossh-NAME.cred(0600, root). The.credfile is the "done" marker, so it is written last and never half; - write the public key to
/etc/nodkey/ssh-NAME.pub(0644); - keep a
LoadCredentialEncrypted=ssh-NAME:/etc/nodkey/credentials/ssh-NAME.credline in a drop-in of the unit for every listed name whose.credexists (not only new ones), thensystemctl daemon-reload; - restart the broker through the handler, which
nodkey_restart: falsecan turn off (a restart ends all grants).
Steps 1–3 run in one task with no_log: true: the private key never goes into an Ansible variable, fact, register or log. In --check mode the role makes nothing and reports what it would make. To use a key, broker.toml needs [key.NAME] with file = "${CREDENTIALS_DIRECTORY}/ssh-NAME" (the owner adds it; the role does not write broker.toml).
The role never replaces or removes an existing key: a key that exists is left as it is (rotation stays a hand job, setup.md). A name that leaves the list is not deleted; the role warns. The role prints each new public key and its fingerprint, so a pull tool's report can show it. The data check (check-data) accepts only names that match ^[a-z0-9][a-z0-9-]{0,31}$ and the types above.
Done when
- The broker side of the role makes each missing key as above; DESIGN.md, THREAT-MODEL.md (approved host data can now make keys and restart the broker) and setup.md section 6 describe it (by hand stays documented as the way without the role).
- Tests in the systemd container of feat: Ansible role that installs nodkey (broker or agent side) from a checked release #193: a new name makes the
.cred, the.puband the drop-in line, and the broker starts and can sign with it; a second run changes nothing; an existing.credis never replaced; a removed name keeps its files and gives a warning; no private key file is left anywhere after a run (also after a failed run); a run that stops before the rename leaves no.cred, and the next run makes the key;--checkmakes nothing; the namedeployworks next to the stock unit'sssh-deployline (no duplicate);nodkey_restart: falsemakes no restart. -
check-datarefuses a bad name and an unknown type. - The security reviewer agent ran on the change, and its findings are fixed or answered in the PR.
Activity
groupsky commentedon Nov 18, 2026
Not started in this run. The role of #193 is merged (#213), so this can build on it now. It is left for a later job: its container test must start a broker and sign with the new key, and that is more work than this run had budget for.