Skip to content

feat: the Ansible role makes missing broker SSH keys on the broker host, from a list of names #206

Open

Description

@groupsky

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-p521

For each name, when /etc/nodkey/credentials/ssh-NAME.cred does not exist:

  1. make the key in a private temporary directory (0700, on tmpfs, removed in an always block), with no passphrase (the broker refuses one; the credential protects it), comment nodkey-NAME;
  2. encrypt it with systemd-creds encrypt --with-key=… --name=ssh-NAME (a role variable, default as setup.md: host+tpm2 when systemd-creds has-tpm2 says yes, else host) to a temporary name, then rename it to ssh-NAME.cred (0600, root). The .cred file is the "done" marker, so it is written last and never half;
  3. write the public key to /etc/nodkey/ssh-NAME.pub (0644);
  4. keep a LoadCredentialEncrypted=ssh-NAME:/etc/nodkey/credentials/ssh-NAME.cred line in a drop-in of the unit for every listed name whose .cred exists (not only new ones), then systemctl daemon-reload;
  5. restart the broker through the handler, which nodkey_restart: false can 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 .pub and the drop-in line, and the broker starts and can sign with it; a second run changes nothing; an existing .cred is 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; --check makes nothing; the name deploy works next to the stock unit's ssh-deploy line (no duplicate); nodkey_restart: false makes no restart.
  • check-data refuses 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.

Part of #193 (same role); its own PR after #193.

Activity

  1. groupsky commented on Nov 18, 2026

    @groupsky
    ContributorAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions