How SSHKing works

People and servers prove who they are with short-lived SSH certificates instead of copied keys. This guide covers what the certificates are, how to set up servers and laptops, and what to do when keys rotate or someone leaves.

Two kinds of certificate

Every environment has two certificate authorities (CAs). They appear as the two key tags on the environment page.

What happens when you connect

1. Your laptop shows its certificateIt was signed by the environment's User CA for your username.
2. The server checks the signatureThe User CA must be trusted on that server, and your key must not be revoked.
3. The server checks the accountYour username must be allowed for the account you asked for, for example deploy.
4. Your laptop checks the serverAt the same time, the server shows its host certificate and your laptop checks it against the Server CA.

Set up a server

Who: an admin of the environment or department.

Before you start

• Root access, OpenSSH 8.2 or newer (Ubuntu 20.04+, Debian 11+, RHEL/Rocky/Alma 9+, Fedora, Amazon Linux 2023) and outbound HTTPS to https://sshking.app.
• Accounts: either turn on Create accounts on servers for the environment, or create the accounts yourself (for example deploy) before people log in. See Server accounts below.
• Keep your current way in, such as authorized_keys or a console, until a certificate login works. Enrolling doesn't remove it.

Steps

1. Add the serverOpen the environment, choose Add server, and enter its name, the host names people type after ssh, and optionally a department.
2. Copy the enrol commandIt works once and expires after 24 hours. Create a new one on the server page if needed.
3. Run it as root on the serverPick the server's system. The first line installs what the tool needs; the rest is the enrol command from step 2.

   Ubuntu / DebianRHEL / Rocky / Alma / Fedora / Amazon LinuxOther Linux

   # as root (sudo -i)
   apt-get update && apt-get install -y curl openssh-server sudo
   curl -fsSL https://sshking.app/sshking-server -o /usr/local/bin/sshking-server \
     && chmod 755 /usr/local/bin/sshking-server \
     && sshking-server enroll https://sshking.app sshenr_…

   Copy

   Ubuntu 20.04 or newer, Debian 11 or newer. Needs outbound HTTPS to https://sshking.app.

4. Give people accessUse Members on the server, its department, the environment or the organisation.

What enrolling installs

Check it worked

sshd -T | grep -Ei 'trustedusercakeys|authorizedprincipals|hostcertificate'
cat /etc/ssh/sshca_principals/deploy   # who may log in as deploy
systemctl list-timers 'sshking*'
sudo sshking-server sync               # refresh now instead of waiting

The server turns green in the app once it has checked in.

Server accounts

People log in to Unix accounts on the server. Which accounts each person may use is set under Members (Server accounts). Leaving it empty means their own username.

Quick renewal

Short certificates are safer: a stolen laptop's certificate stops working within hours. With quick renewal people don't notice them expiring, because ssh gets a fresh one by itself.

1. Run sshking-user login onceIt adds a rule to ~/.ssh/config that runs sshking-user auto <host> before each connection.
2. ssh renews when neededFor servers you can reach through SSHKing, a certificate with less than 10 minutes left is replaced silently. Other hosts, such as GitHub, are left alone.
3. Every so often, confirm it's youWhen the confirmation interval has passed, the terminal shows a code and opens the browser. Approve it (signed in with your email) and the connection carries on.

sshking-user status               # certificates and whether automatic renewal is on
sshking-user setup-ssh            # add the ~/.ssh/config rule (sshking-user login does this)
sshking-user setup-ssh --remove   # take it out again

Set up your laptop

Who: everyone who logs in. Works on macOS and Linux. On Windows, use WSL with Ubuntu.

Once

1. Accept your invitationOpen the email and sign in with the same address.
2. Install the helper

   macOSUbuntu / DebianRHEL / Fedora / Amazon LinuxOther Linux / WSL

   sudo apt-get update && sudo apt-get install -y curl openssh-client
   sudo curl -fsSL https://sshking.app/sshking-user -o /usr/local/bin/sshking-user
   sudo chmod 755 /usr/local/bin/sshking-user
   

   Copy

   Ubuntu 20.04 or newer, Debian 11 or newer.

3. Sign in from the terminal

   sshking-user login

   Copy

   It shows a code. Approve the same code in your browser.

sshking-user login registers your key (it creates ~/.ssh/id_ed25519 if you don't have one), writes your certificate, adds the Server CA to ~/.ssh/sshca_known_hosts, points ~/.ssh/config at it, and loads the key into ssh-agent if one is running.

Every day

Rotating CA keys

Rotation replaces a CA's signing key. Admins find these actions on the key tags of the environment page.

Rotate key (staged, the normal choice)

1. A new key is publishedIt shows as Not signing yet. Servers trust it within 5 minutes; laptops learn it on their next sshking-user login.
2. It starts signing after the stage period24 hours by default. The old key shows as Still trusted.
3. The old key retiresOnce every certificate it signed has expired, it stops being trusted.

Nobody needs to do anything.

Rotate immediately

The same, without the waiting period. People's current certificates keep working. For the Server CA, ask everyone to run sshking-user login once so their laptop learns the new key before servers renew their host certificates (within a day).

Key compromised

Replaces the key and revokes the old one at once. Everything it signed stops working. Revoke on a key tag does the same for that key.

Automatic rotation

Set Rotate keys every (days) in the environment settings, and staged rotations happen by themselves.

Revoking keys and access

Good to know

• A server that can't reach the service keeps its last access list until it reconnects. Short certificate lifetimes limit how long that matters.
• Laptops stop trusting a compromised Server CA key only after they run sshking-user login.
• Revoking a certificate revokes its whole key, not just that one certificate.
• Servers count towards your plan; people, organisations and environments don't.