134 lines
7.9 KiB
Markdown
134 lines
7.9 KiB
Markdown
# 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-<name>` 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/<name>/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 <helper> </dev/null"`,
|
|
with no settings of its own. `ssh` runs the command while it reads the config,
|
|
before it loads an identity. With `HIVE_SSH_CERT_ENSURE` the helper is silent and
|
|
its exit status says whether a usable certificate exists: it exits 0 at once
|
|
when the certificate has more than ten minutes left, asks the store nothing
|
|
for ten seconds after a refusal, and otherwise logs in and signs. Nothing in
|
|
the config depends on the answer; the point is the certificate it leaves
|
|
behind. Every `ssh` on the agent runs this, so a loop of them while the switch
|
|
is off costs one login per ten seconds.
|
|
|
|
## 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.
|
|
|
|
## 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).
|