4.6 KiB
The SSH CA for agents
Agents SSH out with certificates signed by an OpenBao SSH secrets engine mount. The operator view, how to enable it and how to trust it on a machine, is SSH access to a machine.
The mount and its role
swarm-bao-agent-ssh-policy.service runs on the store's host under the
granter's identity, like the agent PKI unit in
the store page. Each run:
- enables the
ssh-agentsmount (typessh) when it isn't there; - generates the CA key inside the mount, once, with
config/ca generate_signing_key=true key_type=ssh-ed25519. It does that only whenssh-agents/issuerslists none. Nothing replaces or deletes the CA, and the granter holds no read on it; - writes the role
ssh-agents/roles/swarm-agent.
The mount and role names come from nix/host-modules/lib/ssh-agent-ca.nix and
are SSH_MOUNT and SSH_ROLE in swarm-secret-client/src/policy.rs; the
bao-grants module-eval suite fails when they differ.
The role signs for every agent:
| field | value |
|---|---|
key_type |
ca |
allow_user_certificates / allow_host_certificates |
true / false |
allowed_users, default_user |
{{identity.entity.name}}, with allowed_users_template and default_user_template on |
allowed_user_key_lengths |
{"ssh-ed25519": 0}: ed25519 keys only |
allowed_extensions, default_extensions |
permit-pty |
allow_user_key_ids |
false |
ttl, max_ttl |
60 minutes, 180 minutes |
The entity name is the agent's name: swarm-controller names the entity of
each agent's cert login after the agent
(swarm-controller/src/agent_entity.rs). A request for any other principal,
a glob, host certificates, other key types or another extension is a refusal
from the store.
What an agent may call
The shared agent policy hive-agent (render_shared_agent) holds one more
stanza: update on ssh-agents/sign/swarm-agent, and nothing on the rest of
the mount. swarm-controller writes the policy at every start and at every
agent mint, so a deploy that adds the stanza reaches existing agents when the
controller restarts. A token already issued picks the change up on its next
request, because bao reads policies per request.
The agent's unit
With services.hyperhive.agent.ssh.enable, nix/agent-modules/ssh.nix adds
hive-agent-ssh-cert.service and its timer, as the agent user:
- the key is
/run/hive-agent-ssh-cert/key(directory0700, files0400,UMask=0377), generated when absent; the certificate iskey-cert.pubbeside it; - each run logs in to the store with the cert identity
hive-agent-bao-identitykeeps, signskey.pubthrough the role, checks the answer parses as a certificate and renames it into place; - the timer fires 20 minutes after each run, a third of the 60-minute lifetime, from the same file as the role's TTL;
- the generated
/etc/ssh/ssh_confighas oneHost <name>block per entry (HostName,User,Port,IdentityFile,CertificateFile,IdentitiesOnly yes,StrictHostKeyChecking yes), and/etc/ssh/ssh_known_hostsone pinned line perhostKey([host]:portfor a port other than 22).
The target module
nixosModules.agent-ssh-target (nix/target-modules/agent-ssh.nix) sets
services.hyperhive.agentSshTarget: caPublicKey, written to
/etc/ssh/hyperhive-agent-ssh-ca.pub and named by TrustedUserCAKeys, and
principals.<user>, which becomes users.users.<user>.openssh.authorizedPrincipals.
NixOS then writes /etc/ssh/authorized_principals.d/<user> and sets
AuthorizedPrincipalsFile to it.
Not covered
Egress. The default egress.forward = "log" lets a direct connection from an
agent to a machine's SSH port through, and reject blocks it; there is no
per-agent allowance for it yet.