add an ssh ca to bao, agent ssh certificates and a target module
This commit is contained in:
parent
ac01ef1bdb
commit
0afb111862
5 changed files with 1056 additions and 17 deletions
|
|
@ -14,3 +14,5 @@ homeserver are in [`swarm/`](../swarm/README.md).
|
|||
`hive-forge -f <label>`.
|
||||
- **[Matrix](matrix.md)** — an account on another homeserver, beside the
|
||||
agent's own.
|
||||
- **[SSH](ssh.md)** — let an agent SSH into a machine with short-lived
|
||||
certificates from the swarm's SSH CA, and make that machine trust them.
|
||||
|
|
|
|||
92
docs/2-handbook/external-accounts/ssh.md
Normal file
92
docs/2-handbook/external-accounts/ssh.md
Normal file
|
|
@ -0,0 +1,92 @@
|
|||
# SSH access to a machine
|
||||
|
||||
Let an agent SSH into a machine you name, such as a test VM, without copying a
|
||||
key onto it. The agent holds no standing SSH key. It asks the swarm's secret
|
||||
store for a certificate that lasts an hour, and the machine trusts the swarm's
|
||||
SSH certificate authority (CA) instead of a list of keys.
|
||||
|
||||
Nothing changes until you do both of these:
|
||||
|
||||
1. Switch SSH on for the agent and name the machines it may reach.
|
||||
2. Make each machine trust the CA and list the agents allowed in.
|
||||
|
||||
## 1. Switch it on for an agent
|
||||
|
||||
In the agent's config:
|
||||
|
||||
```nix
|
||||
services.hyperhive.agent.ssh = {
|
||||
enable = true;
|
||||
hosts.testvm = {
|
||||
hostName = "10.0.0.7";
|
||||
user = "test";
|
||||
port = 22; # the default
|
||||
hostKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
`hostKey` is the machine's own host public key, the one line in
|
||||
`/etc/ssh/ssh_host_ed25519_key.pub` on it. The agent pins it: it refuses a
|
||||
machine that presents any other key, and never trusts a key on first sight.
|
||||
|
||||
The agent then runs `ssh testvm` with no other flag. The agent's SSH client
|
||||
offers its certificate and nothing else. The option needs the agent to have a
|
||||
store identity, the same as for its other store credentials.
|
||||
|
||||
This doesn't open the network. If you set the hive's `egress.forward` to
|
||||
`reject`, the hive refuses the agent's direct connection to the machine's port
|
||||
until a separate allowance exists; the default `log` lets it through. See
|
||||
[the network page](../../4-implementation/networking/network.md).
|
||||
|
||||
## 2. Make a machine trust the CA
|
||||
|
||||
On the swarm's store host, read the CA's public key:
|
||||
|
||||
```bash
|
||||
bao read -field=public_key ssh-agents/config/ca
|
||||
```
|
||||
|
||||
The store also serves the same key without a token at
|
||||
`<store address>/v1/ssh-agents/public_key`. The key is public and you set it
|
||||
once. Then import the module on the machine, which can be any NixOS machine,
|
||||
and not only a hive host:
|
||||
|
||||
```nix
|
||||
{
|
||||
imports = [ hyperhive.nixosModules.agent-ssh-target ];
|
||||
|
||||
services.hyperhive.agentSshTarget = {
|
||||
enable = true;
|
||||
caPublicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…";
|
||||
principals.test = [ "atlas" "maia" ];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
`principals.<user>` lists the agents that may log in as that local account. The
|
||||
account has to exist. An account with no entry accepts no certificate. The
|
||||
module writes no `authorized_keys`.
|
||||
|
||||
## What an agent can and can't do
|
||||
|
||||
- It can only get a certificate for **its own name**. The store signs for the
|
||||
name its identity carries, so atlas can't obtain one that says maia.
|
||||
- The certificate lasts an hour, and the agent signs a new one every 20
|
||||
minutes. The key lives in the agent's `/run` (memory) and never reaches disk.
|
||||
A new container start makes a new key.
|
||||
- It signs ed25519 user keys only, and the certificate allows a terminal
|
||||
(`permit-pty`) and nothing else.
|
||||
|
||||
## Revoking access
|
||||
|
||||
- **One agent from one machine:** remove its name from that user's
|
||||
`principals` and deploy the machine. The next login attempt fails.
|
||||
- **One agent from every machine:** delete its cert-auth role
|
||||
`hive-agent-<name>` in the store. It can no longer log in to the store, so
|
||||
nothing signs for it, and its last certificate lapses within three hours.
|
||||
- **The CA itself:** if the CA key changes, every machine needs the
|
||||
new public key. Nothing replaces the CA by itself.
|
||||
|
||||
For the bao paths, field names and units, see
|
||||
[the SSH CA implementation page](../../4-implementation/swarm/ssh-ca.md).
|
||||
|
|
@ -38,6 +38,7 @@ the rest of the cell says how.
|
|||
| `swarm/agents/<agent>/claude-credentials` | `swarm-claude-login`, when you log the agent in from its card; one version per login | the agent, while it waits for a login | ❌ log in again | ✅ every 30 seconds while waiting |
|
||||
| `swarm/hives/<hive>/forge/token` | `swarm-controller`, every 5 minutes | `swarm-controller` and the hive | ✅ when missing or no longer matching the forge | ✅ read on every forge call |
|
||||
| `swarm/agents/<agent>/proxy-credential` | `swarm-controller`: 32 random bytes, at start and every 5 minutes for every agent that holds a store identity | the hive (`hive-c0re`) and the agent, which fetches it | ❌ never replaced: written only while the path holds nothing | ✅ `hive-c0re` re-reads it every 30 seconds |
|
||||
| `ssh-agents/sign/swarm-agent` (a signing call, nothing is stored) | the store's SSH CA mount (`ssh-agents`), when the agent's `hive-agent-ssh-cert` unit asks it to sign the public key the unit generated in its own `/run`; the CA key is generated inside the store by `swarm-bao-agent-ssh-policy` | the agent, which keeps the key and the signed certificate in `/run` only; a target machine trusts the CA's public key by value | ✅ the certificate lasts 60 minutes; the CA is never replaced, and a target that holds a different CA key refuses every certificate | ✅ the agent signs again every 20 minutes |
|
||||
| `swarm/hives/<hive>/squid-selfcheck` | `swarm-controller`, in the same pass as the agents' credentials | the hive: `hive-c0re` and `squid-selfcheck-credential` (root) | ❌ never replaced: written only while the path holds nothing | ✅ `hive-c0re` every 30 seconds, the root unit every 10 minutes |
|
||||
| `swarm/hives/<hive>/oidc/client` | authelia, first boot, straight into the store | the hive | ❌ minted once, straight into the store; minted again only when the store holds none | ✅ re-read when authelia refuses it |
|
||||
| `swarm/services/<clientId>/oidc/client` | authelia | that service | must be stated | must be stated |
|
||||
|
|
|
|||
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.
|
||||
|
|
@ -100,6 +100,10 @@ Accounts outside the swarm that an agent can hold. Start at
|
|||
the PAT injected?** → [`2-handbook/external-accounts/github.md`](2-handbook/external-accounts/github.md).
|
||||
- **How to give an agent GitLab accounts (`glab` + `git push`, more than one
|
||||
instance)?** → [`2-handbook/external-accounts/gitlab.md`](2-handbook/external-accounts/gitlab.md).
|
||||
- **How to let an agent SSH into a machine (short-lived certificates, a target
|
||||
module)?** → [`2-handbook/external-accounts/ssh.md`](2-handbook/external-accounts/ssh.md);
|
||||
the bao role and units in
|
||||
[`4-implementation/swarm/ssh-ca.md`](4-implementation/swarm/ssh-ca.md).
|
||||
|
||||
## 3. Options reference
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue