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

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

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.