SSH Certificate Authority

Issue short-lived user and host certificates with an Ed25519-based SSH CA.

Overview

The SSH Certificate Authority (SSH CA) issues short-lived user certificates for operator SSH public keys and host certificates for target SSH servers. The current CLI implementation supports CA initialization, automatic/manual user certificate issuance, host certificate signing, managed trust registration in the operator's known_hosts, and status inspection.

plaintext

CA (Ed25519)
  ├─ User certificates (24 hours) → Operator SSH authentication
  └─ Host certificates (90 days)  → Target SSH server authentication

Setup

Initialize the CA

bash

nefia ssh-ca init

An Ed25519 key pair is generated:

Private key: OS keyring (nefia-ssh-ca)
Public key: <state-dir>/ssh_ca.pub

The configuration file is automatically updated with ssh_ca.enabled: true and ssh_ca.auto_sign: true.

Issue a User Certificate

Sign the operator's SSH public key with the CA:

bash

nefia ssh-ca sign-user

Flag	Description	Default
`--duration`	Certificate validity period	`24h`
`--principals`	SSH usernames (comma-separated)	Current OS user

The certificate is saved to <identity_file>-cert.pub.

Issue a Host Certificate

Reads the target host's public key and issues a host certificate:

bash

nefia ssh-ca sign-host --host my-pc

Configure the Target

Configure the target's SSH server to trust the CA public key:

bash

# Add to /etc/ssh/sshd_config
TrustedUserCAKeys /path/to/trusted_user_ca_keys.pub
HostKey /etc/ssh/ssh_host_ed25519_key
HostCertificate /etc/ssh/ssh_host_ed25519_key-cert.pub

On the operator side, add a managed @cert-authority entry to known_hosts:

bash

nefia ssh-ca trust-known-hosts

bash

sudo systemctl restart sshd

Status Check

bash

nefia ssh-ca status

Displays the CA fingerprint, enabled/mode state, certificate validity settings, and the current user certificate status.

Configuration

yaml

ssh_ca:
  enabled: true
  auto_sign: true               # Automatically issue/renew user certificates on connection
  cert_duration: "24h"          # User certificate validity period
  host_cert_duration: "2160h"   # Host certificate validity period (90 days)
  allowed_user_principals:      # Required when enabled — allowlist of principals for user certificates
    - deploy
    - ops
  allow_privileged_principals: false  # Allow privileged principals like "root" (default: false)

Security Features

Short-lived certificates: Automatically expire after 24 hours by default
Clock skew tolerance: 5-minute clock skew allowance at signing time
Agent forwarding disabled: no-agent-forwarding is set by default on user certificates
OS keyring storage: CA private key is securely stored in the OS keyring
Public key format: PublicKeyAuthorizedFormat() outputs an OpenSSH-compatible TrustedUserCAKeys format
Principal allowlist: Only principals listed in allowed_user_principals can appear in user certificates. Duplicates are rejected at config load time.
Privileged principal protection: Privileged principals (e.g., root) are blocked by default. Set allow_privileged_principals: true to permit them.

Key Storage

Data	Storage Location
CA private key	OS keyring (service: `nefia-ssh-ca`, account: `ca-private-key`)
CA public key	`<state-dir>/ssh_ca.pub`
User certificate	`<identity_file>-cert.pub`

MCP Tools

AI agents can manage SSH CAs programmatically via MCP:

Tool	Description
`nefia.sshca.init`	Initialize the SSH CA with Ed25519 key pair stored in OS keyring.
`nefia.sshca.sign_user`	Issue a short-lived user certificate with principal restrictions and validity period. Requires mandatory approval — the approval workflow must be enabled, and a human must approve each signing request.
`nefia.sshca.sign_host`	Issue a host certificate for a target's SSH server.
`nefia.sshca.status`	Check SSH CA initialization status and certificate details.
`nefia.sshca.trust`	Register the CA public key in the operator's `known_hosts` file.
`nefia.sshca.server_snippet`	Generate the SSH server configuration snippet (`TrustedUserCAKeys`, `HostCertificate`) for a host.