diff --git a/docs/2-handbook/external-accounts/ssh.md b/docs/2-handbook/external-accounts/ssh.md index 89927bb69..4d200af8e 100644 --- a/docs/2-handbook/external-accounts/ssh.md +++ b/docs/2-handbook/external-accounts/ssh.md @@ -5,11 +5,17 @@ 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: +Agent-side, 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. +The permission to get a certificate is in the policy every agent shares, so +every agent with a store identity can already get a certificate for its own +name, whether or not you switch SSH on for it. That's harmless: no machine +trusts a name it doesn't list. Switching SSH on only sets up the key, the +renewal and the client config. + ## 1. Switch it on for an agent In the agent's config: @@ -82,9 +88,15 @@ module writes no `authorized_keys`. - **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-` 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. +- **One agent from every machine:** remove its name from every machine's + `principals`. That's the revocation. No swarm-wide switch + stops signing for an agent that a hive still declares: if you delete + its cert-auth role `hive-agent-` in the store, `swarm-controller` + writes it back within five minutes. Signing stops only once no hive declares + the agent any more (you destroyed it); the controller then stops renewing + its store identity, and the identity lapses with its 7-day certificate. +- **A certificate already issued** stays valid until it expires, at most three + hours, whatever you remove. Removing a principal blocks new logins at once. - **The CA itself:** if the CA key changes, every machine needs the new public key. Nothing replaces the CA by itself. diff --git a/docs/4-implementation/swarm/ssh-ca.md b/docs/4-implementation/swarm/ssh-ca.md index a90fb434c..ab760bcca 100644 --- a/docs/4-implementation/swarm/ssh-ca.md +++ b/docs/4-implementation/swarm/ssh-ca.md @@ -81,3 +81,14 @@ NixOS then writes `/etc/ssh/authorized_principals.d/` and sets 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. + +## Revocation + +Every agent shares the role, which holds nothing per agent, so there is no +per-agent signing switch. `swarm-controller`'s renewal pass (`agent_renewal.rs`) re-mints +the store identity, and writes the cert-auth role `hive-agent-` back, for +every agent a hive still declares, so deleting the role doesn't stick. Nothing +in the controller deletes the role when you destroy an agent; the renewal pass +skips a destroyed agent and its identity lapses with its 7-day +certificate. A target's `principals` list is the immediate control. A +certificate already signed stays valid for at most `max_ttl` (180 minutes). diff --git a/nix/target-modules/agent-ssh.nix b/nix/target-modules/agent-ssh.nix index 649366e71..53e534866 100644 --- a/nix/target-modules/agent-ssh.nix +++ b/nix/target-modules/agent-ssh.nix @@ -9,8 +9,9 @@ # a certificate, the agent's name, so listing an agent here is what lets it in. # No `authorized_keys` entry is written or needed. Removing a name from # `principals` ends that agent's logins at the next attempt, whatever -# certificate it holds; the swarm stops signing for an agent whose store -# identity is gone, and the certificates it has lapse within three hours. +# certificate it holds. The swarm has no switch that stops signing for an +# agent that is still declared; a certificate already signed expires within +# three hours. # # The agent's side is ../agent-modules/ssh.nix. {