Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/docs/4-implementation/swarm/ssh-ca.md

6.9 KiB

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.

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. 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.

The switch and the signing policy

The operator's switch is the ssh field of the agent's record in agent-permissions (swarm_wire::agent_permissions), set with PUT /api/agents/{name}/permissions from the swarm UI's ssh row. Absent is off. A PUT or DELETE that leaves the field out keeps it.

Signing is a separate policy, hive-agent-ssh (policy::SSH_POLICY, render_ssh_signer): update on ssh-agents/sign/swarm-agent and nothing else. The shared agent policy hive-agent holds no SSH stanza. swarm-controller writes hive-agent-ssh at every identity mint and every pass of agent_ssh.rs, and attaches it to the agent's cert-auth role hive-agent-<name> as a second token_policies entry only while the switch is on.

  • Rewrite. A change of the field wakes agent_ssh's pass at once, and the pass also runs every five minutes. It reads each role's policies and rewrites only token_policies (a partial write: the role's certificate, names and lifetimes stay) when they differ from the shared policy plus, if on, hive-agent-ssh. The identity mint (agent_identity.rs) keeps whatever the role has, so a certificate renewal doesn't switch it off. The pass doesn't create a missing role.
  • When it takes effect. A token carries the policies of the role it logged in under and keeps them until it expires, at most the role's token_ttl of one hour. Switching on reaches the agent at its next login, which its certificate unit makes on every run (every 20 minutes), so within about 25 minutes of the pass. Switching off stops every new login at once; an agent already holding a token that carries the policy can still sign until that token expires, at most an hour. Neither touches a certificate already signed: it stays valid until it expires, at most three hours.
  • The CA key. GET /api/ssh/ca returns { "public_key": "ssh-ed25519 …" }, read from ssh-agents/config/ca with the controller's own identity. The controller holds read on that path and nothing else on the mount: it can't sign. It answers 404 while the store holds no CA.

The agent's unit

nix/agent-modules/ssh.nix is on in every agent that has a store address (services.hyperhive.agent.bao.addr), with no option. It 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. A 403 from the signing call is the switch being off: the unit prints one line and exits 0, and the next tick asks again. Any other failure fails the unit, which retries;
  • 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 system /etc/ssh/ssh_config has one Host * block: IdentityFile and CertificateFile from /run, IdentitiesOnly yes, StrictHostKeyChecking accept-new, and UserKnownHostsFile /agents/<name>/state/ssh_known_hosts. The host binds the state directory in, so the pins survive a restart; the container root doesn't. The agent trusts the first key a host shows and refuses a changed one.

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.

Revocation

Unticking the switch stops signing as described above. Destroying an agent disables its identity entity and deletes its cert-auth role (agent_cutoff.rs), after which its tokens stop working at once. A target's principals list is the immediate control per machine. A certificate already signed stays valid for at most max_ttl (180 minutes).