SSH certificates
Replace scattered authorized_keys files and host-key warnings with short-lived SSH certificates.
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.
The problem with plain SSH keys
Section titled “The problem with plain SSH keys”Plain SSH keys trust individual keys, one at a time:
- Every server keeps an
authorized_keyslist. When someone leaves, you must find and remove their key everywhere. - Every client keeps a
known_hostslist. The first connection asks “Are you sure you want to continue connecting?” Almost everyone typesyeswithout 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:
- 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.
1. Give your CA SSH keys
Section titled “1. Give your CA SSH keys”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:
step crypto keypair $(step path)/certs/ssh_host_ca_key.pub $(step path)/secrets/ssh_host_ca_keyYour 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:
step crypto keypair $(step path)/certs/ssh_user_ca_key.pub $(step path)/secrets/ssh_user_ca_keyOpen $(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:
"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:
step ca provisioner update admin@example.com --ssh✔ 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:
step ssh config --rootsecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBJNE72/yogyhdZedsQrzNzCiqbhZQgDNkq1EtcaGYiBWwlSSZv6ne8NioCzBYiP88M3Fo9NL5C9lkp5CAiuu0uU=That’s the user CA public key. step ssh config --host --roots prints the host CA key.
2. Give the server a host certificate
Section titled “2. Give the server a host certificate”On the server, sign its existing ECDSA host key. The certificate lists the names clients will use:
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.
✔ Provisioner: admin@example.com (JWK) [kid: Cd7tLLuIuLwt1q99PInSoACmv1IcO7db19AOY_3AS_E]✔ CA: https://localhost:9000✔ Certificate: /etc/ssh/ssh_host_ecdsa_key-cert.pubRead it with OpenSSH’s own tool:
ssh-keygen -L -f /etc/ssh/ssh_host_ecdsa_key-cert.pub/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.
3. Configure sshd to use both
Section titled “3. Configure sshd to use both”Save the user CA key where sshd can read it:
step ssh config --roots | sudo tee /etc/ssh/ssh_user_ca.pubCreate a config file for the lab. Keep it out of /etc/ssh/sshd_config.d/, because your normal SSH server reads every file there:
TrustedUserCAKeys /etc/ssh/ssh_user_ca.pubHostCertificate /etc/ssh/ssh_host_ecdsa_key-cert.pubPidFile /run/sshd-pki-lab.pidInclude /etc/ssh/sshd_configTrustedUserCAKeysaccepts any user certificate signed by this CA.HostCertificatemakes sshd present its certificate to clients.PidFilekeeps the lab server’s process ID apart from your normal server’s.Includepulls 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:
sudo sshd -t -f /etc/ssh/pki-lab-sshd.conf && echo "sshd config OK"sshd config OKOn 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:
sudo /usr/sbin/sshd -f /etc/ssh/pki-lab-sshd.conf -p 2222Create a local account for Alice to log in to:
sudo useradd -m -s /bin/bash aliceAlice has no password and no authorized_keys. The certificate is the only way in.
4. Get a user certificate
Section titled “4. Get a user certificate”On the client, ask for a certificate for Alice:
step ssh certificate alice@example.com ~/.ssh/id_ecdsaChoose a password for the new private key, then enter the provisioner password.
✔ 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: yesIf 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.
ssh-keygen -L -f ~/.ssh/id_ecdsa-cert.pub/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-rcThree things to notice:
- Principals are
aliceandalice@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.
5. Trust the host CA on the client
Section titled “5. Trust the host CA on the client”Add one line to ~/.ssh/known_hosts. It says: “for these host names, trust any host certificate from this CA.”
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.
6. Log in
Section titled “6. Log in”ssh -p 2222 alice@localhost whoamissh asks for your key’s passphrase. That unlocks the key on your laptop. It is not a server password.
Enter passphrase for key '/home/ubuntu/.ssh/id_ecdsa':aliceNo account password. No “Are you sure you want to continue connecting?” Both sides proved themselves with certificates.
Add -v to see it happen:
ssh -v -p 2222 alice@localhost whoamidebug1: 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:48debug1: 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+USpMPctT98cvYQXyDKjRe4debug1: Server accepts key: /home/ubuntu/.ssh/id_ecdsa ECDSA-CERT SHA256:hWMpvdzMtmwsqcM3MRO3+USpMPctT98cvYQXyDKjRe4The first two lines are the host check. The last two are the user check.
Break it
Section titled “Break it”Log in as someone else
Section titled “Log in as someone else”Create a second account:
sudo useradd -m bobTry to log in as Bob with Alice’s certificate:
ssh -p 2222 bob@localhost whoamibob@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 a name nobody vouched for
Section titled “Connect by a name nobody vouched for”Connect by IP address with strict checking on:
ssh -p 2222 -o StrictHostKeyChecking=yes alice@127.0.0.1 whoamiNo 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.
No host CA trust at all
Section titled “No host CA trust at all”Remove the @cert-authority line from ~/.ssh/known_hosts. Then connect with strict checking:
ssh -p 2222 -o StrictHostKeyChecking=yes alice@localhost whoamiNo 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.
Clean up
Section titled “Clean up”Stop the lab sshd, using its PID file:
sudo kill $(cat /run/sshd-pki-lab.pid)Remove its config:
sudo rm /etc/ssh/pki-lab-sshd.confGo deeper
Section titled “Go deeper”ssh-keygenmanual, CERTIFICATES sectionsshd_configmanual —TrustedUserCAKeys,HostCertificateandAuthorizedPrincipalsFile.- step-ca SSH documentation
- Run an SSH CA with step-ca
Check yourself
Tap a card to flip it. Nothing is scored or saved.
Progress is saved in this browser only.