add an ssh ca to bao, agent ssh certificates and a target module
This commit is contained in:
parent
ac01ef1bdb
commit
0afb111862
2 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).
|
||||
Loading…
Reference in a new issue