add an ssh ca to bao, agent ssh certificates and a target module
This commit is contained in:
parent
ac01ef1bdb
commit
0afb111862
1 changed files with 1056 additions and 17 deletions
83
docs/4-implementation/swarm/ssh-ca.md
Normal file
83
docs/4-implementation/swarm/ssh-ca.md
Normal file
|
|
@ -0,0 +1,83 @@
|
|||
# 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.
|
||||
Loading…
Reference in a new issue