Skip to content
Module 08

SSH certificates

Replace scattered authorized_keys files and host-key warnings with short-lived SSH certificates.

SSHIntermediate 35 min

OpenSSH has its own certificate format. Instead of copying public keys into every server’s authorized_keys, servers trust one SSH CA. Users and hosts get short-lived certificates signed by it.

Plain SSH keys trust individual keys, one at a time:

  • Every server keeps an authorized_keys list. When someone leaves, you must find and remove their key everywhere.
  • Every client keeps a known_hosts list. The first connection asks “Are you sure you want to continue connecting?” Almost everyone types yes without checking. That’s trust on first use, and it’s how a man-in-the-middle gets in.

SSH certificates replace both lists with two CA keys:

Laptopuser certificateSSH CAuser key + host keyServerhost certificatesignssignsLaptop trusts the host CA. Server trusts the user CA.
  • The user CA signs user keys. Servers trust it with one line: TrustedUserCAKeys.
  • The host CA signs server keys. Clients trust it with one line in known_hosts: @cert-authority.

An SSH certificate is not X.509. It’s a public key plus a few fields, signed by the CA key: a key ID, a serial, principals (allowed login names or host names), a validity window and a few options.

step ca init --ssh creates SSH CA keys at setup. Your CA already exists, so add them by hand.

Create the host CA key pair. Use your CA password when asked:

terminal
step crypto keypair $(step path)/certs/ssh_host_ca_key.pub $(step path)/secrets/ssh_host_ca_key
Expected output
Your public key has been saved in /home/ubuntu/.step/certs/ssh_host_ca_key.pub.
Your private key has been saved in /home/ubuntu/.step/secrets/ssh_host_ca_key.

Create the user CA key pair the same way:

terminal
step crypto keypair $(step path)/certs/ssh_user_ca_key.pub $(step path)/secrets/ssh_user_ca_key

Open $(step path)/config/ca.json. Add this block at the top level, next to "db". On a host install, replace /home/ubuntu with your home folder:

ca.json (excerpt)
"ssh": {
"hostKey": "/home/ubuntu/.step/secrets/ssh_host_ca_key",
"userKey": "/home/ubuntu/.step/secrets/ssh_user_ca_key"
},

Allow your admin provisioner to sign SSH certificates:

terminal
step ca provisioner update admin@example.com --ssh
Expected output
✔ CA Configuration: /home/ubuntu/.step/config/ca.json
Success! Your `step-ca` config has been updated. To pick up the new configuration SIGHUP (kill -1 <pid>) or restart the step-ca process.

Restart step-ca so it loads the new keys. Then ask it for its SSH CA keys:

terminal
step ssh config --roots
Expected output
ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBJNE72/yogyhdZedsQrzNzCiqbhZQgDNkq1EtcaGYiBWwlSSZv6ne8NioCzBYiP88M3Fo9NL5C9lkp5CAiuu0uU=

That’s the user CA public key. step ssh config --host --roots prints the host CA key.

On the server, sign its existing ECDSA host key. The certificate lists the names clients will use:

terminal
sudo step ssh certificate --host --sign \
--principal localhost --principal host.example.com \
host.example.com /etc/ssh/ssh_host_ecdsa_key.pub \
--ca-url https://localhost:9000 --root $(step path)/certs/root_ca.crt \
--provisioner admin@example.com

--sign means “sign this existing public key”, so no new key is made. --ca-url and --root matter because sudo runs as root, which has no step config of its own.

Expected output
✔ Provisioner: admin@example.com (JWK) [kid: Cd7tLLuIuLwt1q99PInSoACmv1IcO7db19AOY_3AS_E]
✔ CA: https://localhost:9000
✔ Certificate: /etc/ssh/ssh_host_ecdsa_key-cert.pub

Read it with OpenSSH’s own tool:

terminal
ssh-keygen -L -f /etc/ssh/ssh_host_ecdsa_key-cert.pub
Expected output
/etc/ssh/ssh_host_ecdsa_key-cert.pub:
Type: ecdsa-sha2-nistp256-cert-v01@openssh.com host certificate
Public key: ECDSA-CERT SHA256:vtR0vV1NmhQF2eZ7rbeUXhn9tr5JTux4uvANnGxTiic
Signing CA: ECDSA SHA256:V5d2k/Mh8hZQsv+5vCeQdlrG1/z5tYGmsVTczWGLKx0 (using ecdsa-sha2-nistp256)
Key ID: "host.example.com"
Serial: 14565824590151446183
Valid: from 2026-11-16T04:03:48 to 2026-12-16T04:04:48
Principals:
localhost
host.example.com
Critical Options: (none)
Extensions: (none)

Host certificates default to 30 days. Run the same command again before it expires. For hands-off renewal, step-ca’s SSHPOP provisioner lets a host renew with step ssh renew, using its current certificate as proof.

Save the user CA key where sshd can read it:

terminal
step ssh config --roots | sudo tee /etc/ssh/ssh_user_ca.pub

Create a config file for the lab. Keep it out of /etc/ssh/sshd_config.d/, because your normal SSH server reads every file there:

/etc/ssh/pki-lab-sshd.conf
TrustedUserCAKeys /etc/ssh/ssh_user_ca.pub
HostCertificate /etc/ssh/ssh_host_ecdsa_key-cert.pub
PidFile /run/sshd-pki-lab.pid
Include /etc/ssh/sshd_config
  • TrustedUserCAKeys accepts any user certificate signed by this CA.
  • HostCertificate makes sshd present its certificate to clients.
  • PidFile keeps the lab server’s process ID apart from your normal server’s.
  • Include pulls in everything else from your normal config. The lab lines come first because sshd keeps the first value it reads for most settings.

Only the lab server loads this file, so your normal SSH server never trusts the lab CA.

Test the config:

terminal
sudo sshd -t -f /etc/ssh/pki-lab-sshd.conf && echo "sshd config OK"
Expected output
sshd config OK

On a host install, you might see Missing privilege separation directory: /run/sshd instead. Create the folder with sudo mkdir -p /run/sshd, then test again. The lab VM creates it at boot.

Start a second sshd on port 2222 with the lab config:

terminal
sudo /usr/sbin/sshd -f /etc/ssh/pki-lab-sshd.conf -p 2222

Create a local account for Alice to log in to:

terminal
sudo useradd -m -s /bin/bash alice

Alice has no password and no authorized_keys. The certificate is the only way in.

On the client, ask for a certificate for Alice:

terminal
step ssh certificate alice@example.com ~/.ssh/id_ecdsa

Choose a password for the new private key, then enter the provisioner password.

Expected output
✔ Provisioner: admin@example.com (JWK) [kid: Cd7tLLuIuLwt1q99PInSoACmv1IcO7db19AOY_3AS_E]
✔ CA: https://localhost:9000
✔ Private Key: /home/ubuntu/.ssh/id_ecdsa
✔ Public Key: /home/ubuntu/.ssh/id_ecdsa.pub
✔ Certificate: /home/ubuntu/.ssh/id_ecdsa-cert.pub
✔ SSH Agent: yes

If no ssh-agent is running, the last line shows an error instead. That’s harmless. The files are on disk.

The private key is protected by the passphrase you chose. Keep it that way. The certificate is public, but the key is not.

terminal
ssh-keygen -L -f ~/.ssh/id_ecdsa-cert.pub
Expected output
/home/ubuntu/.ssh/id_ecdsa-cert.pub:
Type: ecdsa-sha2-nistp256-cert-v01@openssh.com user certificate
Public key: ECDSA-CERT SHA256:hWMpvdzMtmwsqcM3MRO3+USpMPctT98cvYQXyDKjRe4
Signing CA: ECDSA SHA256:EIcXDAfDg6cm9wkLx2vr70NIgDt53MsMW6uYOQfLgtw (using ecdsa-sha2-nistp256)
Key ID: "alice@example.com"
Serial: 9167219149753294453
Valid: from 2026-11-16T04:03:49 to 2026-11-16T20:04:49
Principals:
alice
alice@example.com
Critical Options: (none)
Extensions:
permit-X11-forwarding
permit-agent-forwarding
permit-port-forwarding
permit-pty
permit-user-rc

Three things to notice:

  • Principals are alice and alice@example.com. step derived them from the email. The server lets this certificate log in only as a listed principal.
  • Valid for 16 hours, the default for user certificates. Tomorrow, Alice gets a new one. Nobody cleans up old keys.
  • Signing CA is the user CA, not your X.509 intermediate. SSH and X.509 trust are separate.

Add one line to ~/.ssh/known_hosts. It says: “for these host names, trust any host certificate from this CA.”

terminal
echo "@cert-authority [localhost]:2222,*.example.com $(step ssh config --host --roots)" >> ~/.ssh/known_hosts

[localhost]:2222 is how OpenSSH writes a host on a non-standard port. *.example.com covers every server you’ll add later.

terminal
ssh -p 2222 alice@localhost whoami

ssh asks for your key’s passphrase. That unlocks the key on your laptop. It is not a server password.

Expected output
Enter passphrase for key '/home/ubuntu/.ssh/id_ecdsa':
alice

No account password. No “Are you sure you want to continue connecting?” Both sides proved themselves with certificates.

Add -v to see it happen:

terminal
ssh -v -p 2222 alice@localhost whoami
Expected output (excerpt)
debug1: Server host certificate: ecdsa-sha2-nistp256-cert-v01@openssh.com SHA256:vtR0vV1NmhQF2eZ7rbeUXhn9tr5JTux4uvANnGxTiic, serial 14565824590151446183 ID "host.example.com" CA ecdsa-sha2-nistp256 SHA256:V5d2k/Mh8hZQsv+5vCeQdlrG1/z5tYGmsVTczWGLKx0 valid from 2026-11-16T04:03:48 to 2026-12-16T04:04:48
debug1: Host '[localhost]:2222' is known and matches the ECDSA-CERT host certificate.
debug1: Found CA key in /home/ubuntu/.ssh/known_hosts:1
...
debug1: Offering public key: /home/ubuntu/.ssh/id_ecdsa ECDSA-CERT SHA256:hWMpvdzMtmwsqcM3MRO3+USpMPctT98cvYQXyDKjRe4
debug1: Server accepts key: /home/ubuntu/.ssh/id_ecdsa ECDSA-CERT SHA256:hWMpvdzMtmwsqcM3MRO3+USpMPctT98cvYQXyDKjRe4

The first two lines are the host check. The last two are the user check.

Create a second account:

terminal
sudo useradd -m bob

Try to log in as Bob with Alice’s certificate:

terminal
ssh -p 2222 bob@localhost whoami
Expected output
bob@localhost: Permission denied (publickey,password).

The signature is valid, but bob isn’t a principal in the certificate. Principals are how SSH certificates do authorization.

Connect by IP address with strict checking on:

terminal
ssh -p 2222 -o StrictHostKeyChecking=yes alice@127.0.0.1 whoami
Expected output
No ECDSA host key is known for [127.0.0.1]:2222 and you have requested strict checking.
Host key verification failed.

Your @cert-authority line covers [localhost]:2222 and *.example.com, and the host certificate lists localhost and host.example.com. Neither covers 127.0.0.1, so the client falls back to plain host keys. Without StrictHostKeyChecking, you’d get the old “Are you sure?” prompt. In a certificate setup, that prompt means something is wrong.

If the CA line did cover the address, OpenSSH would still refuse, with Certificate invalid: name is not a listed principal. Both the client’s pattern and the certificate’s principals must match.

Remove the @cert-authority line from ~/.ssh/known_hosts. Then connect with strict checking:

terminal
ssh -p 2222 -o StrictHostKeyChecking=yes alice@localhost whoami
Expected output
No ECDSA host key is known for [localhost]:2222 and you have requested strict checking.
Host key verification failed.

The host certificate only helps clients that trust the host CA. Put the line back to continue.

Stop the lab sshd, using its PID file:

terminal
sudo kill $(cat /run/sshd-pki-lab.pid)

Remove its config:

terminal
sudo rm /etc/ssh/pki-lab-sshd.conf

Check yourself

Tap a card to flip it. Nothing is scored or saved.

Progress is saved in this browser only.