# 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](../../2-handbook/external-accounts/ssh.md). ## 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](bao.md). Each run: 1. enables the `ssh-agents` mount (type `ssh`) when it isn't there; 2. generates the CA key inside the mount, once, with `config/ca generate_signing_key=true key_type=ssh-ed25519`. It does that only when `ssh-agents/issuers` lists none. Nothing replaces or deletes the CA, and the granter holds no read on it; 3. 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` (directory `0700`, files `0400`, `UMask=0377`), generated when absent; the certificate is `key-cert.pub` beside it; - each run logs in to the store with the cert identity `hive-agent-bao-identity` keeps, signs `key.pub` through 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_config` has one `Host ` block per entry (`HostName`, `User`, `Port`, `IdentityFile`, `CertificateFile`, `IdentitiesOnly yes`, `StrictHostKeyChecking yes`), and `/etc/ssh/ssh_known_hosts` one pinned line per `hostKey` (`[host]:port` for 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.`, which becomes `users.users..openssh.authorizedPrincipals`. NixOS then writes `/etc/ssh/authorized_principals.d/` 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. ## Revocation Every agent shares the role, which holds nothing per agent, so there is no per-agent signing switch. `swarm-controller`'s renewal pass (`agent_renewal.rs`) re-mints the store identity, and writes the cert-auth role `hive-agent-` back, for every agent a hive still declares, so deleting the role doesn't stick. Nothing in the controller deletes the role when you destroy an agent; the renewal pass skips a destroyed agent and its identity lapses with its 7-day certificate. A target's `principals` list is the immediate control. A certificate already signed stays valid for at most `max_ttl` (180 minutes).