# Outbound SSH for this agent: a certificate for a key it generates itself, # signed by the swarm's SSH CA, and a client config for the hosts it may reach. # # Nothing is configured unless `services.hyperhive.agent.ssh.enable` is set. The # agent has no standing SSH credential: `${unitName}.service` generates an # ed25519 key in its own `/run` directory (tmpfs, never on disk), logs in to the # swarm secret store with the identity ./bao.nix keeps current, and has the # public half signed by the store's SSH engine # (`swarm_secret_client::policy::SSH_MOUNT`). The role it signs through issues a # user certificate with this agent's name as its only principal, valid for an # hour; a timer signs again well before that runs out. # # A target machine trusts the CA, not this key: ../target-modules/agent-ssh.nix. { pkgs, lib, config, ... }: let cfg = config.services.hyperhive.agent.ssh; baoCfg = config.services.hyperhive.agent.bao; # The unix user is named for the agent, so this is also the principal the # role puts on the certificate (the identity entity swarm-controller names # after the agent). agentName = config.services.hyperhive.agent.user.name; ca = import ../host-modules/lib/ssh-agent-ca.nix { }; # The server CA id ./bao.nix loads. serverCaCredential = "hive-agent-bao-server-ca"; unitName = "hive-agent-ssh-cert"; runtimeDir = unitName; keyFile = "/run/${runtimeDir}/key"; pubFile = "${keyFile}.pub"; # `ssh` reads `-cert.pub` by itself, but the config names it so # that the file a Host block uses is visible in the config. certFile = "${keyFile}-cert.pub"; stagingFile = "/run/${runtimeDir}/cert.new"; errFile = "/run/${runtimeDir}/bao.err"; signPath = "${ca.mountPath}/sign/${ca.roleName}"; storeRetry = import ../host-modules/lib/store-retry.nix { }; # `[host]:port` is how a known_hosts line names a host on a non-default port. knownHostName = h: if h.port == 22 then h.hostName else "[${h.hostName}]:${toString h.port}"; hostBlock = name: h: '' Host ${name} HostName ${h.hostName} User ${h.user} Port ${toString h.port} IdentityFile ${keyFile} CertificateFile ${certFile} IdentitiesOnly yes StrictHostKeyChecking yes ''; hostType = lib.types.submodule { options = { hostName = lib.mkOption { type = lib.types.strMatching "[A-Za-z0-9._:-]+"; example = "vm1.pc2.example.com"; description = '' Name or address the agent connects to. The host key below is pinned to exactly this spelling. ''; }; user = lib.mkOption { type = lib.types.strMatching "[A-Za-z0-9._-]+"; example = "test"; description = '' Account to log in as on the target. The target's {option}`principals` for that account must list this agent. ''; }; port = lib.mkOption { type = lib.types.port; default = 22; description = "TCP port of the target's sshd."; }; hostKey = lib.mkOption { type = lib.types.strMatching "(ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp(256|384|521)) [A-Za-z0-9+/]+=*( [A-Za-z0-9@._-]+)?"; example = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…"; description = '' The target's SSH host public key, one line as in {file}`/etc/ssh/ssh_host_ed25519_key.pub` on the target. It is pinned: the agent refuses a target that presents any other key, and there is no trust on first use. ''; }; }; }; in { options.services.hyperhive.agent.ssh = { enable = lib.mkEnableOption '' outbound SSH for this agent with short-lived certificates from the swarm secret store's SSH CA. Needs {option}`services.hyperhive.agent.bao.addr` ''; hosts = lib.mkOption { type = lib.types.attrsOf hostType; default = { }; example = lib.literalExpression '' { testvm = { hostName = "10.0.0.7"; user = "test"; hostKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…"; }; } ''; description = '' Hosts this agent may SSH to, by the name it types: `ssh testvm`. Each entry becomes a `Host` block in the system {file}`ssh_config` that offers this agent's certificate and nothing else, and a pinned line in the system {file}`ssh_known_hosts`. This does not open the network path: with the hive's egress set to reject, direct TCP out of the container is refused whatever is configured here. ''; }; }; config = lib.mkIf cfg.enable { assertions = [ { assertion = baoCfg.addr != null; message = "services.hyperhive.agent.ssh.enable needs services.hyperhive.agent.bao.addr: the certificate is signed by the swarm secret store, and this agent has no store address"; } { assertion = lib.all (n: builtins.match "[A-Za-z0-9._-]+" n != null) (lib.attrNames cfg.hosts); message = "services.hyperhive.agent.ssh.hosts names are written into ssh_config and may hold only letters, digits, `.`, `_` and `-`"; } ]; programs.ssh.extraConfig = lib.concatStrings (lib.mapAttrsToList hostBlock cfg.hosts); programs.ssh.knownHosts = lib.mapAttrs' ( name: h: lib.nameValuePair "hive-agent-ssh-${name}" { hostNames = [ (knownHostName h) ]; publicKey = h.hostKey; } ) cfg.hosts; systemd.services.${unitName} = { description = "sign this agent's SSH key with the swarm's SSH CA"; after = [ "network.target" # Ordering only: that unit reports a store this agent cannot reach as # itself, and should get to say so first. "hive-agent-bao-identity.service" ]; wantedBy = [ "multi-user.target" ]; path = [ pkgs.openbao pkgs.openssh pkgs.coreutils ]; # ../host-modules/lib/store-retry.nix. inherit (storeRetry) startLimitBurst startLimitIntervalSec; serviceConfig = storeRetry.serviceConfig // { Type = "oneshot"; # Not `RemainAfterExit`: the timer has to be able to start this unit # again. `RuntimeDirectoryPreserve` keeps the key between runs. RemainAfterExit = false; TimeoutStartSec = 30; User = agentName; Group = agentName; RuntimeDirectory = runtimeDir; RuntimeDirectoryMode = "0700"; RuntimeDirectoryPreserve = "yes"; UMask = "0377"; LoadCredential = [ serverCaCredential ]; }; environment = { BAO_ADDR = toString baoCfg.addr; BAO_CLIENT_CERT = baoCfg.clientCertFile; BAO_CLIENT_KEY = baoCfg.clientKeyFile; }; script = '' set -euo pipefail # No identity delivered: ./bao.nix's check reports that; saying it # twice adds nothing. for f in "$BAO_CLIENT_CERT" "$BAO_CLIENT_KEY"; do if [ ! -s "$f" ]; then echo "this agent has no store identity, so it cannot get an SSH certificate." >&2 exit 0 fi if [ ! -r "$f" ]; then echo "cannot read $f, so this agent cannot present its store identity." >&2 exit 1 fi done if [ -s "$CREDENTIALS_DIRECTORY/${serverCaCredential}" ]; then export BAO_CACERT="$CREDENTIALS_DIRECTORY/${serverCaCredential}" fi # `UMask=0377` makes every file this script creates `0400`, so each one # is removed before the command that creates it. key=${lib.escapeShellArg keyFile} pub=${lib.escapeShellArg pubFile} cert=${lib.escapeShellArg certFile} staged=${lib.escapeShellArg stagingFile} err=${lib.escapeShellArg errFile} trap 'rm -f "$err" "$staged"' EXIT # The key lives as long as /run does, which is as long as this # container: a restart is a new key. Only a pair with both halves is # kept. if [ ! -s "$key" ] || [ ! -s "$pub" ]; then rm -f "$key" "$pub" "$cert" ssh-keygen -q -t ed25519 -N "" -C ${lib.escapeShellArg "hive-agent-${agentName}"} -f "$key" chmod 0400 "$key" fi rm -f "$err" if ! BAO_TOKEN="$(bao login -method=cert -token-only 2>"$err")"; then echo "the swarm secret store at $BAO_ADDR refused or could not answer this agent's certificate login:" >&2 if [ -s "$err" ]; then cat "$err" >&2; fi exit 1 fi export BAO_TOKEN # No principal is requested: the role's default is this agent's own # name, and it refuses any other. rm -f "$err" "$staged" if ! bao write -field=signed_key ${lib.escapeShellArg signPath} public_key=@"$pub" >"$staged" 2>"$err"; then echo "the swarm secret store would not sign this agent's SSH key at ${signPath}:" >&2 if [ -s "$err" ]; then cat "$err" >&2; fi exit 1 fi # A reply that is not a certificate must not replace the one in use. if ! ssh-keygen -L -f "$staged" >/dev/null 2>&1; then echo "what the store returned at ${signPath} is not an SSH certificate; keeping the current one." >&2 exit 1 fi # One rename: ssh never reads a half-written certificate. mv -f "$staged" "$cert" echo "signed this agent's SSH key as ${agentName}, valid for ${toString ca.certTtlMinutes} minutes." ''; }; # Every third of the certificate's lifetime, so a store that is down for # a run or two does not outlast it. systemd.timers.${unitName} = { description = "sign this agent's SSH key again before its certificate expires"; wantedBy = [ "timers.target" ]; timerConfig = { OnUnitInactiveSec = "${toString ca.renewEveryMinutes}min"; RandomizedDelaySec = "1min"; }; }; }; }