Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/docs/4-implementation/swarm/ssh-ca.md

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).