# 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. ## The switch and the signing policy The operator's switch is the `ssh` field of the agent's record in `agent-permissions` (`swarm_wire::agent_permissions`), set with `PUT /api/agents/{name}/permissions` from the swarm UI's **ssh** row. Absent is off. A `PUT` or `DELETE` that leaves the field out keeps it. Signing is a separate policy, `hive-agent-ssh` (`policy::SSH_POLICY`, `render_ssh_signer`): `update` on `ssh-agents/sign/swarm-agent` and nothing else. The shared agent policy `hive-agent` holds no SSH stanza. `swarm-controller` writes `hive-agent-ssh` at every identity mint and every pass of `agent_ssh.rs`, and attaches it to the agent's cert-auth role `hive-agent-` as a second `token_policies` entry only while the switch is on. - **Rewrite.** A change of the field wakes `agent_ssh`'s pass at once, and the pass also runs every five minutes. It reads each role's policies and rewrites only `token_policies` (a partial write: the role's certificate, names and lifetimes stay) when they differ from the shared policy plus, if on, `hive-agent-ssh`. The identity mint (`agent_identity.rs`) keeps whatever the role has, so a certificate renewal doesn't switch it off. The pass doesn't create a missing role. - **When it takes effect.** A token carries the policies of the role it logged in under and keeps them until it expires, at most the role's `token_ttl` of one hour. Switching **on** reaches the agent at its next login, which its certificate unit makes on every run (every 20 minutes), so within about 25 minutes of the pass. Switching **off** stops every new login at once; an agent already holding a token that carries the policy can still sign until that token expires, at most an hour. Neither touches a certificate already signed: it stays valid until it expires, at most three hours. - **The CA key.** `GET /api/ssh/ca` returns `{ "public_key": "ssh-ed25519 …" }`, read from `ssh-agents/config/ca` with the controller's own identity. The controller holds `read` on that path and nothing else on the mount: it can't sign. It answers 404 while the store holds no CA. ## The agent's unit `nix/agent-modules/ssh.nix` is on in every agent that has a store address (`services.hyperhive.agent.bao.addr`), with no option. It 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; - the unit's script is also the **helper** `ssh` runs: one text, two entries. Each run logs in afresh 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. A `403` from the signing call is the switch being off: the unit prints one line and exits 0, and the next tick asks again. Any other failure fails the unit, which retries. One run at a time (`flock` on the directory), the unit's or an `ssh`'s; - the unit copies the store's CA out of its credentials into `server-ca.pem` beside the key, so that an `ssh` run, which has no credentials directory, can reach the store; - 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 system `/etc/ssh/ssh_config` has one `Host *` block: `IdentityFile` and `CertificateFile` from `/run`, `IdentitiesOnly yes`, `StrictHostKeyChecking accept-new`, and `UserKnownHostsFile /agents//state/ssh_known_hosts`. The host binds the state directory in, so the pins survive a restart; the container root doesn't. The agent trusts the first key a host shows and refuses a changed one; - the same config starts with `Match exec "HIVE_SSH_CERT_ENSURE=1 `, which becomes `users.users..openssh.authorizedPrincipals`. NixOS then writes `/etc/ssh/authorized_principals.d/` and sets `AuthorizedPrincipalsFile` to it. ## Named connections The operator's named connections are the `ssh_connections` list of the same record (`swarm_wire::ssh_connection::SshConnection`: `name`, `user`, `host`, `port`). They have their own routes in `swarm-controller/src/ssh_connections.rs`, and a write changes only that field; a `PUT` or `DELETE` on `/permissions` keeps them: ```text GET /api/agents//ssh-connections PUT /api/agents//ssh-connections/ {"user":"root","host":"muede-pc2","port":2222} DELETE /api/agents//ssh-connections/ ``` `SshConnection::checked` is the one validation, run by the controller before it stores a connection and by the agent before it renders one: - **Name:** lower-case letters, digits and hyphens, up to 63, not starting with a hyphen. A name is unique per agent, and an agent has at most 32. - **User:** letters, digits, `_`, `.` and `-`, up to 32, not starting with `-` or `.`. - **Host:** a DNS name (one label is fine) or an IPv4 address. The swarm refuses IPv6 addresses, `localhost`, and loopback, link-local, multicast and reserved addresses. - **Port:** 1 to 65535, except 80 and 443. The hive sends those two ports to its own proxy, so no direct connection there can exist. The swarm doesn't check the hive's own bridge subnet, because each hive sets its own and an agent can move between hives. Each hive drops an address of its own subnet when it resolves a host (see [Egress](#egress)). `hive-agent`'s `ssh_connections.rs` renders the list each time the harness reads the record (every ten seconds) into `/run/hive-agent-ssh-connections/config`: one `Host` block each with `HostName`, `User` and `Port`, and an empty file while `ssh` is off. The block carries no identity lines: ssh takes the identity from the `Host *` block below the `Include` in `ssh.nix`, which gives the swarm CA certificate to every connection. The file belongs to the agent user, because ssh refuses an included file that another user owns. A controller older than the field drops the list when it next writes the record through `PUT /permissions`. ## Egress The hive's forward chain accepts a named connection of an agent that has `ssh` on, whatever `egress.forward` is (`log` or `reject`). Each hive does this for the agents it has: 1. `hive-c0re`'s `workers::egress_connections` reads the permissions the hive last read from the swarm and, for each agent with `ssh` on, resolves the `host` of each connection with the host's resolver. An IPv4 literal passes through. It asks the hosts of a pass together, each for at most five seconds, so a hung resolver delays the file by that long and no more. It keeps an answer for ten minutes and keeps the last answer when a lookup fails or times out (one warning, until the name resolves again). It drops loopback, link-local, multicast and IPv6 answers, and any address inside the hive's bridge subnet (`HIVE_NETWORK_SUBNET`) with one warning per host, because a flow to the bridge never reaches the forward chain. It writes ` ` lines to `egress.connectionsFile`, beside squid's users file. 2. `hive-priv egress-pin` maps each agent to the MAC of its port and fills the `agent_allow` set of the `inet hive_egress` table, in the same transaction as `direct_mac`. `hive-egress-connections.path` runs a pass when the file changes. 3. The forward chain accepts `ether saddr . ip daddr . tcp dport @agent_allow` right after the `direct_mac` rule, so a matching flow is neither counted nor logged. The allowance is for TCP and IPv4 only: the agent bridge has no IPv6 addressing. An agent whose port has no binding yet has no allowance until it gets one. See [the network page](../networking/network.md). ## Revocation Unticking the switch stops signing as described above. Destroying an agent disables its identity entity and deletes its cert-auth role (`agent_cutoff.rs`), after which its tokens stop working at once. A target's principals list is the immediate control per machine. A certificate already signed stays valid for at most `max_ttl` (180 minutes).