Watch
0
0
Fork
You've already forked hyperhive
0

add an ssh ca to bao, agent ssh certificates and a target module

This commit is contained in:
atlas 2026-11-16 16:24:37 +01:00 • committed by mara
commit 0afb111862
9 changed files with 1056 additions and 17 deletions

View file

@ -103,6 +103,7 @@ in
./packages.nix
./queue-identity.nix
./rea.nix
./ssh.nix
./user.nix
./screen.nix
./weston-vnc.nix

264
nix/agent-modules/ssh.nix Normal file
View file

@ -0,0 +1,264 @@
# 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 `<IdentityFile>-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";
};
};
};
}

View file

@ -225,6 +225,10 @@ in
inherit pkgs self nixosSystem;
inherit (pkgs) lib;
};
module-eval-agent-ssh-target = import ./module-eval/agent-ssh-target.nix {
inherit pkgs self nixosSystem;
inherit (pkgs) lib;
};
# Executes what the two `module-eval-agent-*-bao` suites above only
# evaluate: the rendered scripts of the forge-token, identity and
# proxy-credential fetch units, against a stub `bao`.

View file

@ -0,0 +1,23 @@
# What the swarm's SSH CA and its agent role fix, spelled once for the two
# files that must agree: ../swarm-bao.nix writes the role, and
# ../../agent-modules/ssh.nix signs through it and renews on a schedule
# derived from the certificate's lifetime.
#
# `mountPath` and `roleName` are also `swarm_secret_client::policy::SSH_MOUNT`
# and `SSH_ROLE`, which the shared agent policy names; the bao-grants module-eval
# suite reads that file and fails when the two disagree.
#
# Pure attrset, not a NixOS module.
{ }:
rec {
mountPath = "ssh-agents";
roleName = "swarm-agent";
# A certificate is valid this long, and the role refuses a longer request.
certTtlMinutes = 60;
certMaxTtlMinutes = 180;
# A third of the lifetime: a run that fails once still leaves the old
# certificate valid for the retry, and a few failed runs still do.
renewEveryMinutes = certTtlMinutes / 3;
}

View file

@ -195,10 +195,13 @@ let
# the services root. The next six set up the agent PKI mount: the mount, its
# root and the `swarm-*` role agent certificates are issued through. No
# `root` delete there: every agent's cert-auth role pins that root by value,
# so replacing it would lock every agent out. The last three configure the
# `oidc` auth method: its config, its `swarm-*` roles, and a read on the one
# client secret that config carries. No `sys/auth`: the auth mounts are
# created with the bootstrap token by `swarm-bao-granter-role`.
# so replacing it would lock every agent out. The four after those set up the
# agent SSH CA mount: the mount, its issuer list, the CA write and its
# `swarm-*` role. No read on the CA and no delete: the CA is generated once.
# The last three configure the `oidc` auth method: its config, its `swarm-*`
# roles, and a read on the one client secret that config carries. No
# `sys/auth`: the auth mounts are created with the bootstrap token by
# `swarm-bao-granter-role`.
#
# Piped as a shell-quoted argument like `controllerPolicyText`, so
# ../module-eval/bao-grants.nix can read it out of the unit script.
@ -271,6 +274,22 @@ let
capabilities = ["create", "update"]
}
path "sys/mounts/${sshAgentsMountPath}" {
capabilities = ["create", "update"]
}
path "${sshAgentsMountPath}/issuers" {
capabilities = ["list"]
}
path "${sshAgentsMountPath}/config/ca" {
capabilities = ["create", "update"]
}
path "${sshAgentsMountPath}/roles/swarm-*" {
capabilities = ["create", "update"]
}
path "auth/oidc/config" {
capabilities = ["create", "update"]
}
@ -1082,6 +1101,43 @@ let
# live agent's leaf once it is past half of it (`agent_renewal.rs`).
agentPkiLeafTtl = "168h";
# The SSH secrets engine mount whose CA signs the agents' user certificates,
# and the one role they sign through, spelled once for this file and
# ../agent-modules/ssh.nix in ./lib/ssh-agent-ca.nix.
sshAgent = import ./lib/ssh-agent-ca.nix { };
sshAgentsMountPath = sshAgent.mountPath;
sshAgentRoleName = sshAgent.roleName;
# What the role pins. `{{identity.entity.name}}` is the name of the entity the
# agent's cert login lands on, which swarm-controller sets to the agent's name
# (`swarm-controller/src/agent_entity.rs`); with `allowed_users_template` the
# engine checks every requested principal against it, and with
# `default_user_template` an unrequested one defaults to it, so a certificate
# names its holder's own agent and no other. `allowed_user_key_lengths` limits
# the keys it signs to ed25519, whatever the length. The only extension is
# `permit-pty`; `allow_host_certificates = false` keeps the CA from signing a
# host key. A certificate is valid for an hour and never longer than three, and
# `ssh-agent-ca.nix` derives the agent's renewal interval from the hour.
sshAgentRoleBody = builtins.toJSON {
key_type = "ca";
allow_user_certificates = true;
allow_host_certificates = false;
allowed_users = "{{identity.entity.name}}";
allowed_users_template = true;
default_user = "{{identity.entity.name}}";
default_user_template = true;
allow_user_key_ids = false;
allowed_user_key_lengths = {
"ssh-ed25519" = 0;
};
allowed_extensions = "permit-pty";
default_extensions = {
"permit-pty" = "";
};
ttl = "${toString sshAgent.certTtlMinutes}m";
max_ttl = "${toString sshAgent.certMaxTtlMinutes}m";
};
# Lifetime of a token from a cert login, on every cert-auth role this file
# writes except the batch ones. The store keeps a lease per token until it
# expires; a login per operation at the mount default (32 days) leaves one
@ -4181,6 +4237,40 @@ in
'') hiveLeafIssuers
);
# The SSH CA agents get their short-lived user certificates from: the
# mount, the CA key the engine generates inside itself, and the one role
# every agent signs through. The same idempotence as the agent PKI unit
# below, without its restart: nothing here changes what the listener trusts.
systemd.services.swarm-bao-agent-ssh-policy = granterPolicyUnit "set up the swarm SSH CA mount and the role agents sign their user certificates through" ''
mounts="$(bao secrets list -format=json)"
case "$mounts" in
*'"${sshAgentsMountPath}/"'*) ;;
*) bao secrets enable -path=${sshAgentsMountPath} ssh ;;
esac
# Generated once, ever: every target machine trusts this CA's public key
# by value, so a second `config/ca` write would replace the default
# issuer and lock every agent out of every target. There is no replace
# branch. The issuer list is the guard, and `{}` is the only answer that
# means "none".
if issuers="$(bao list -format=json ${lib.escapeShellArg "${sshAgentsMountPath}/issuers"})"; then
echo "the ${sshAgentsMountPath} mount already has a CA — leaving it alone"
elif [ "$issuers" = '{}' ]; then
echo "generating the swarm agent SSH CA into the ${sshAgentsMountPath} mount"
bao write -field=public_key ${lib.escapeShellArg "${sshAgentsMountPath}/config/ca"} \
generate_signing_key=true \
key_type=ssh-ed25519 >/dev/null
else
echo "could not list the ${sshAgentsMountPath} issuers — not generating a CA over one that may exist" >&2
exit 1
fi
# Upserted every run, so a change to the role applies on deploy.
printf '%s' ${lib.escapeShellArg sshAgentRoleBody} |
bao write ${lib.escapeShellArg "${sshAgentsMountPath}/roles/${sshAgentRoleName}"} -
'';
# The agent PKI mount: its root, its one role, the host's copy of the
# root's certificate, and the listener's trust in it.
#

View file

@ -6,6 +6,8 @@
# fetches it, and ../agent-modules/forge.nix's readers find it. The same fixtures
# cover ../agent-modules/egress-proxy.nix, the agent's proxy credential and the
# environment built from it.
# They also cover ../agent-modules/ssh.nix: the agent's SSH certificate unit and
# client config, on the same store address.
{
pkgs,
lib,
@ -32,12 +34,30 @@ let
# A forge and a store: the fetch exists and every reader points at it.
agentForgeBao = agentWith {
services.hyperhive.agent.bao.addr = baoAddr;
services.hyperhive.agent.ssh = {
enable = true;
hosts.testvm = {
hostName = "10.0.0.7";
user = "test";
hostKey = hostKeyA;
};
hosts.altvm = {
hostName = "vm2.t.local";
user = "ops";
port = 2222;
hostKey = hostKeyB;
};
};
services.hyperhive.agent.forge.url = forgeUrl;
# A second `EnvironmentFile=` on the harness, which the proxy file must join.
services.hyperhive.agent.backendEnvironmentFile = "/var/lib/t/backend.env";
services.hyperhive.agent.icon = pkgs.emptyFile;
};
# Outbound SSH on the same agent: two hosts, one on a non-default port.
hostKeyA = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOHfYeWemIBqSc5Ac51ecuhi0G9LTN+57DFRq6mFKKk0";
hostKeyB = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMY1xboa8d2ncPDhTSPKsq5WMyYfWwIqLcCOnkHLO3ad";
# A forge and no store: the absence arm, and what makes the cases above able
# to fail.
agentForgeNoBao = agentWith {
@ -45,6 +65,15 @@ let
services.hyperhive.agent.icon = pkgs.emptyFile;
};
# SSH asked for with no store: the certificate has nowhere to be signed.
agentSshNoBao = agentWith {
services.hyperhive.agent.ssh.enable = true;
services.hyperhive.agent.icon = pkgs.emptyFile;
};
sshUnit = machine: machine.systemd.services.hive-agent-ssh-cert;
sshCa = import ../host-modules/lib/ssh-agent-ca.nix { };
fetchUnit = machine: machine.systemd.services.hive-agent-forge-token;
proxyUnit = machine: machine.systemd.services.hive-agent-proxy-credential;
accountsUnit = machine: machine.systemd.services.hive-agent-forge-accounts;
@ -521,6 +550,88 @@ let
&& lib.hasInfix "NODE_USE_ENV_PROXY=1" s
&& lib.hasInfix "url=\"http://${name}:$secret@$proxy\"" s;
}
{
# ../agent-modules/ssh.nix. Presence arm first, then the agent that
# did not ask for SSH, which gets neither the unit nor a host block.
name = "an agent that enables ssh gets the certificate unit and its timer, and one that does not gets neither";
ok =
agentForgeBao.systemd.services ? hive-agent-ssh-cert
&& agentForgeBao.systemd.timers ? hive-agent-ssh-cert
&& !(agentForgeNoBao.systemd.services ? hive-agent-ssh-cert)
&& !(agentForgeNoBao.systemd.timers ? hive-agent-ssh-cert)
&& !(lib.hasInfix "Host testvm" agentForgeNoBao.environment.etc."ssh/ssh_config".text);
}
{
# The key and the certificate stay in the unit's own tmpfs directory,
# owner-only, and the unit asks for no principal: the role's default is
# the agent's own name, and a `valid_principals` here would be the one
# place the unit could name another.
name = "the ssh certificate unit keeps the key in a 0700 directory under /run as the agent user, asks for no principal, and renames the certificate in";
ok =
let
u = sshUnit agentForgeBao;
s = u.script;
in
u.serviceConfig.User == "a1"
&& u.serviceConfig.RuntimeDirectory == "hive-agent-ssh-cert"
&& u.serviceConfig.RuntimeDirectoryMode == "0700"
&& u.serviceConfig.UMask == "0377"
&& lib.hasInfix "key=/run/hive-agent-ssh-cert/key" s
&& lib.hasInfix "ssh-keygen -q -t ed25519" s
&& lib.hasInfix "bao write -field=signed_key ssh-agents/sign/swarm-agent" s
&& lib.hasInfix "mv -f \"$staged\" \"$cert\"" s
&& !(lib.hasInfix "valid_principals" s)
&& !(lib.hasInfix ".ssh" s)
&& lib.elem "hive-agent-bao-identity.service" u.after
&& u.environment.BAO_CLIENT_CERT == agentForgeBao.services.hyperhive.agent.bao.clientCertFile;
}
{
# The certificate lives an hour and the timer fires every third of
# that, so one missed run still leaves the old certificate valid.
name = "the ssh certificate is renewed at least twice within its lifetime";
ok =
let
every = lib.toInt (
lib.removeSuffix "min" agentForgeBao.systemd.timers.hive-agent-ssh-cert.timerConfig.OnUnitInactiveSec
);
in
every * 2 < sshCa.certTtlMinutes && every > 0;
}
{
# `ssh testvm` has to work with no other flag: the host block names the
# target, the user, the port, the one identity and its certificate, and
# refuses an unknown host key.
name = "each ssh host gets a Host block offering only the agent's certificate, and a pinned known_hosts line";
ok =
let
conf = agentForgeBao.environment.etc."ssh/ssh_config".text;
known = agentForgeBao.environment.etc."ssh/ssh_known_hosts".text;
block = lib.concatStringsSep "\n" [
"Host testvm"
" HostName 10.0.0.7"
" User test"
" Port 22"
" IdentityFile /run/hive-agent-ssh-cert/key"
" CertificateFile /run/hive-agent-ssh-cert/key-cert.pub"
" IdentitiesOnly yes"
" StrictHostKeyChecking yes"
];
in
lib.hasInfix block conf
&& lib.hasInfix "Host altvm\n HostName vm2.t.local\n User ops\n Port 2222\n" conf
&& lib.hasInfix "10.0.0.7 ${hostKeyA}" known
# A port other than 22 is spelled the way known_hosts keys it.
&& lib.hasInfix "[vm2.t.local]:2222 ${hostKeyB}" known
&& !(lib.hasInfix "\nvm2.t.local " "\n${known}");
}
{
name = "enabling ssh on an agent with no store address is refused, naming the option";
ok =
let
refuses = m: lib.any (a: !a.assertion && lib.hasInfix "agent.bao.addr" a.message) m.assertions;
in
refuses agentSshNoBao && !(refuses agentForgeBao);
}
];
in
runGroup "agent-forge-bao" cases

View file

@ -0,0 +1,120 @@
# `checks.module-eval-agent-ssh-target` — see ./lib.nix for the shared
# rationale (why this suite exists, naming convention, "evaluates
# not executes").
#
# ../target-modules/agent-ssh.nix, the module for a machine agents SSH into. It
# needs a fixture of its own: it is not a hive host or an agent, and the
# agent-side cases in ./agent-forge-bao.nix cannot evaluate it.
{
pkgs,
lib,
self,
nixosSystem,
}:
let
inherit
(import ./lib.nix {
inherit
pkgs
lib
self
nixosSystem
;
})
runGroup
;
caKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOHfYeWemIBqSc5Ac51ecuhi0G9LTN+57DFRq6mFKKk0";
machine =
extra:
(nixosSystem {
system = pkgs.stdenv.hostPlatform.system;
modules = [
self.nixosModules.agent-ssh-target
{
fileSystems."/" = {
device = "/dev/null";
fsType = "tmpfs";
};
boot.loader.grub.enable = false;
system.stateVersion = "25.11";
users.users.test.isNormalUser = true;
users.users.ops.isNormalUser = true;
}
extra
];
}).config;
trusting = machine {
services.hyperhive.agentSshTarget = {
enable = true;
# The command's output ends in a newline.
caPublicKey = "${caKey}\n";
principals.test = [
"atlas"
"maia"
];
};
};
# The module imported and left off.
untouched = machine { };
# Enabled with nobody listed.
nobody = machine {
services.hyperhive.agentSshTarget = {
enable = true;
caPublicKey = caKey;
};
};
principalsOf = m: user: m.environment.etc."ssh/authorized_principals.d/${user}".text;
cases = [
{
name = "an enabled target trusts the CA's public key and ties sshd to the per-user principals file";
ok =
trusting.services.openssh.enable
&& trusting.services.openssh.settings.TrustedUserCAKeys == "/etc/ssh/hyperhive-agent-ssh-ca.pub"
&& trusting.environment.etc."ssh/hyperhive-agent-ssh-ca.pub".text == "${caKey}\n"
&&
trusting.services.openssh.settings.AuthorizedPrincipalsFile
== "/etc/ssh/authorized_principals.d/%u";
}
{
# `ops` is a real account on the machine that no agent was listed for.
name = "only the listed agents are principals of the listed user, and an unlisted user has no principals file";
ok =
principalsOf trusting "test" == "atlas\nmaia"
&& !(trusting.environment.etc ? "ssh/authorized_principals.d/ops");
}
{
# No key is ever copied: the module writes none for any user.
name = "the target module writes no authorized key";
ok =
trusting.users.users.test.openssh.authorizedKeys.keys == [ ]
&& trusting.users.users.test.openssh.authorizedKeys.keyFiles == [ ];
}
{
# The absence arm, and the control that makes the cases above able to
# fail: the same module, imported and not enabled, changes nothing.
name = "an imported but disabled target trusts no CA";
ok =
!(untouched.services.openssh.settings ? TrustedUserCAKeys)
&& !(untouched.environment.etc ? "ssh/hyperhive-agent-ssh-ca.pub")
&& untouched.services.openssh.settings.AuthorizedPrincipalsFile == "none"
&& !untouched.services.openssh.enable;
}
{
name = "an enabled target that lists no agent is refused";
ok =
let
refuses =
m: lib.any (a: !a.assertion && lib.hasInfix "agentSshTarget.principals" a.message) m.assertions;
in
refuses nobody && !(refuses trusting);
}
];
in
runGroup "agent-ssh-target" cases

View file

@ -182,6 +182,7 @@ let
"swarm-bao-services-issuer-policy"
"swarm-bao-nats-tls-policy"
"swarm-bao-agent-pki"
"swarm-bao-agent-ssh-policy"
"swarm-bao-nats-auth-policy"
"swarm-bao-operator-viewer-policy"
"swarm-bao-hive-leaf-policy"
@ -1340,7 +1341,7 @@ let
{
# The granter's grants, whole. Pinned as the full list, because an added
# path or capability is exactly what a presence check misses.
name = "the granter's policy is exactly these twenty stanzas";
name = "the granter's policy is exactly these twenty-four stanzas";
ok =
let
cu = [
@ -1420,6 +1421,22 @@ let
path = "pki-agents/roles/swarm-*";
caps = cu;
}
{
path = "sys/mounts/ssh-agents";
caps = cu;
}
{
path = "ssh-agents/issuers";
caps = [ "list" ];
}
{
path = "ssh-agents/config/ca";
caps = cu;
}
{
path = "ssh-agents/roles/swarm-*";
caps = cu;
}
{
path = "auth/oidc/config";
caps = cu;
@ -2806,6 +2823,94 @@ let
&& !(lib.any (a: !a.assertion && names a) baoGrantHere.assertions);
}
{
# The SSH CA is the trust every target machine holds by value, so it is
# made once, only when the mount lists no issuer, and the granter can
# neither read it back nor delete it. The presence arms: the same unit
# does write the mount, the CA and the role.
name = "the agent SSH CA is generated once from an ed25519 key, only when the mount has no issuer, and nothing deletes it";
ok =
let
s = baoGrantHere.systemd.services.swarm-bao-agent-ssh-policy.script;
generate = "ssh-agents/config/ca";
in
lib.length (lib.splitString generate s) == 2
&& lib.hasInfix "generate_signing_key=true" s
&& lib.hasInfix "key_type=ssh-ed25519" s
&& lib.hasInfix "bao secrets enable -path=ssh-agents ssh" s
&& lib.hasInfix "elif [ \"$issuers\" = '{}' ]; then" s
&& !(lib.hasInfix "bao delete" s)
&&
(grantFor granterGrants "ssh-agents/config/ca").caps == [
"create"
"update"
]
&& grantFor granterGrants "ssh-agents/sign/swarm-agent" == null
&& grantFor granterGrants "ssh-agents/roles/other" == null;
}
{
# What keeps an agent from a certificate for another agent: the
# principal is the caller's entity name, requested or not, and the role
# signs nothing but ed25519 user keys with one extension. The role is
# a single JSON document, so each fragment below is one property of it.
name = "the agent SSH role names the caller's own entity as the only principal, signs ed25519 user keys for an hour, and one unit writes it";
ok =
let
s = baoGrantHere.systemd.services.swarm-bao-agent-ssh-policy.script;
roleWriters = lib.filter (u: matches "bao write '?ssh-agents/roles/" (u.script or "") != [ ]) (
lib.attrValues baoGrantHere.systemd.services
);
in
lib.all (t: lib.hasInfix t s) [
''"allowed_users":"{{identity.entity.name}}"''
''"allowed_users_template":true''
''"default_user":"{{identity.entity.name}}"''
''"default_user_template":true''
''"allow_user_certificates":true''
''"allow_host_certificates":false''
''"allow_user_key_ids":false''
''"allowed_user_key_lengths":{"ssh-ed25519":0}''
''"allowed_extensions":"permit-pty"''
''"key_type":"ca"''
''"ttl":"60m"''
''"max_ttl":"180m"''
"bao write ssh-agents/roles/swarm-agent -"
]
&& lib.length roleWriters == 1;
}
{
# The agents' `update` on the sign path comes from the shared agent
# policy (swarm-secret-client), not from a unit here. Of the policies
# these units write, only the granter's names the mount: the controller,
# which writes the shared one, holds nothing on it.
name = "of the policies the host writes, only the granter's has a grant on the agent SSH mount";
ok =
let
cg = grantsIn baoGrantHere.systemd.services.swarm-bao-controller-policy.script;
onMount = lib.filter (g: lib.hasPrefix "ssh-agents" g.path);
in
onMount cg == [ ]
# The control: the granter's grants do name the mount.
&& onMount granterGrants != [ ]
&& lib.all (u: onMount (grantsIn baoGrantHere.systemd.services.${u}.script) == [ ]) (
lib.filter (u: u != "swarm-bao-agent-ssh-policy") grantingUnitNames
);
}
{
# The shared agent policy (swarm-secret-client) names the mount and the
# role; the unit above and the agent module spell the same two strings
# from ../host-modules/lib/ssh-agent-ca.nix.
name = "the SSH mount and role the shared agent policy names are the ones the swarm writes";
ok =
let
ca = import ../host-modules/lib/ssh-agent-ca.nix { };
policy = builtins.readFile ../../swarm-secret-client/src/policy.rs;
in
lib.hasInfix ''pub const SSH_MOUNT: &str = "${ca.mountPath}";'' policy
&& lib.hasInfix ''pub const SSH_ROLE: &str = "${ca.roleName}";'' policy
&& lib.hasInfix "bao write ssh-agents/roles/${ca.roleName} -" baoGrantHere.systemd.services.swarm-bao-agent-ssh-policy.script;
}
# ── the UI's OIDC login ─────────────────────────────────────────────────
{
# What an `admins` login through the UI holds: the key tree, KV

View file

@ -0,0 +1,79 @@
# A machine agents may SSH into: it trusts the swarm's SSH CA and lists which
# agent may log in as which local user. Exported as
# `hyperhive.nixosModules.agent-ssh-target`, and meant for any NixOS machine,
# not only a hive host.
#
# sshd accepts a user certificate when the CA that signed it is in
# `TrustedUserCAKeys` and one of its principals is in that user's
# `AuthorizedPrincipalsFile`. The swarm's SSH role puts exactly one principal on
# 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.
#
# The agent's side is ../agent-modules/ssh.nix.
{
lib,
config,
...
}:
let
cfg = config.services.hyperhive.agentSshTarget;
in
{
options.services.hyperhive.agentSshTarget = {
enable = lib.mkEnableOption "logins by agents holding a certificate from the swarm's SSH CA";
caPublicKey = lib.mkOption {
type = lib.types.strMatching "ssh-ed25519 [A-Za-z0-9+/]+=*[[:space:]]*";
example = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…";
description = ''
The public key of the swarm's SSH CA: a public value, set here once. Read
it on the swarm's store host, as an operator with a token that may read
the mount:
```
bao read -field=public_key ssh-agents/config/ca
```
The same key is served without a token at `<store address>/v1/ssh-agents/public_key`.
A CA that is regenerated has a new key, and every target must then be
given it.
'';
};
principals = lib.mkOption {
type = lib.types.attrsOf (lib.types.listOf (lib.types.strMatching "[A-Za-z0-9_-]+"));
default = { };
example = {
test = [
"atlas"
"maia"
];
};
description = ''
For each local account, the names of the agents that may log in as it. The
account has to exist on this machine. An account that is not listed
accepts no certificate.
'';
};
};
config = lib.mkIf cfg.enable {
assertions = [
{
assertion = lib.any (agents: agents != [ ]) (lib.attrValues cfg.principals);
message = "services.hyperhive.agentSshTarget.principals lists no agent, so this machine would trust the CA and admit nobody";
}
];
services.openssh.enable = lib.mkDefault true;
services.openssh.settings.TrustedUserCAKeys = "/etc/ssh/hyperhive-agent-ssh-ca.pub";
environment.etc."ssh/hyperhive-agent-ssh-ca.pub".text = "${lib.trim cfg.caPublicKey}\n";
# NixOS writes `/etc/ssh/authorized_principals.d/<user>` for each of these
# and points `AuthorizedPrincipalsFile` at it.
users.users = lib.mapAttrs (_: agents: { openssh.authorizedPrincipals = agents; }) cfg.principals;
};
}