89 lines
4 KiB
Markdown
89 lines
4 KiB
Markdown
# 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. While you allow it, the agent
|
|
gets a certificate from the swarm's SSH certificate authority (CA) that lasts
|
|
an hour. The machine trusts the CA, so it needs no list of keys.
|
|
|
|
Two things have to be true before an agent gets in:
|
|
|
|
1. **You switch SSH on for that agent**, in the swarm UI.
|
|
2. **The machine trusts the CA** and lists the agent.
|
|
|
|
Every agent already has an SSH client, a key it makes in memory, and a
|
|
certificate unit. The switch alone decides whether the swarm signs.
|
|
|
|
## 1. Switch it on for an agent
|
|
|
|
Open the agent's card in the swarm UI and find the **ssh** row. Select it and
|
|
tick **allow the agent to get SSH certificates**. The default is off. The
|
|
agent has a certificate within about 25 minutes of the change. Untick the box
|
|
to stop new certificates. The row also shows the three forms of the target
|
|
setup below, already filled in with the swarm's CA key and the agent's name.
|
|
|
|
The agent then runs `ssh user@host`, with no other setup. It offers its
|
|
certificate and nothing else.
|
|
|
|
**Host keys use trust on first use.** The agent accepts the key a machine
|
|
shows on the first connection, keeps it in its state directory (so it survives
|
|
restarts), and refuses a changed key afterwards. A swapped machine on the first
|
|
contact would go unnoticed. The row's explainer says so.
|
|
|
|
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
|
|
|
|
Open **on the target** in the same row. It shows the swarm's CA public key, a
|
|
public value, and the agent's name, in three forms. Replace `<user>` with the
|
|
account the agent logs in as. The target never contacts the swarm.
|
|
|
|
- **NixOS:** the CA key in `services.openssh.settings.TrustedUserCAKeys` and
|
|
`users.users.<user>.openssh.authorizedPrincipals = [ "<agent>" ];`. The same
|
|
as one module: import `hyperhive.nixosModules.agent-ssh-target` and set
|
|
`services.hyperhive.agentSshTarget` (`enable`, `caPublicKey`,
|
|
`principals.<user>`).
|
|
- **home-manager:** `home.file.".ssh/authorized_keys".text` holding one
|
|
`cert-authority` line.
|
|
- **plain ssh:** one line in the account's `~/.ssh/authorized_keys`:
|
|
|
|
```
|
|
cert-authority,principals="<agent>" ssh-ed25519 AAAA…
|
|
```
|
|
|
|
This works on any machine without a change to its sshd config.
|
|
|
|
To read the CA key outside the UI, run this on the swarm's store host:
|
|
|
|
```bash
|
|
bao read -field=public_key ssh-agents/config/ca
|
|
```
|
|
|
|
## 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 principal (the `authorizedPrincipals`
|
|
entry, or the `cert-authority` line) and deploy the machine. The next login
|
|
attempt fails.
|
|
- **One agent from every machine:** untick the switch. The swarm stops signing
|
|
for it within five minutes; an agent already signed in can still sign
|
|
for up to an hour. Destroying the agent cuts its store identity off within
|
|
minutes. Either way a certificate already signed stays valid until it
|
|
expires, at most three hours, so removing the principal on a machine is what
|
|
cuts it off there at once.
|
|
- **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).
|