83 lines
4.6 KiB
Markdown
83 lines
4.6 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.
|
|
|
|
## 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 <name>` 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.<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.
|