If you’re no longer using SSH certificates you’re doing SSH tainted (2019)

SSH is ubiquitous. It’s the de-facto solution for remote administration of *nix systems. But SSH has some pretty gnarly issues when it comes to usability, operability, and security.You’re probably familiar with these issues: SSH user experience is terrible. SSH user on-boarding is slow and manual. Connecting to new hosts produces confusing security warnings. You’re left…

If you’re no longer using SSH certificates you’re doing SSH tainted (2019)

SSH is ubiquitous. It’s the de-facto acknowledge for distant administration of *nix programs. But SSH has some somewhat gnarly points in phrases of usability, operability, and security.

You’re potentially accustomed to these points:

  • SSH user experience is unpleasant. SSH user on-boarding is tedious and manual. Connecting to unique hosts produces confusing security warnings. You’re left with abnormal unique credentials to purchase watch over with small steering on the correct intention to enact so.
  • Working SSH at scale is a catastrophe. Key approval & distribution is a silly rupture of time. Host names can’t be reused. Homegrown instruments scatter key area fabric true by intention of your fast that possess to be cleaned up later to off-board customers.
  • SSH encourages bad security practices. Rekeying is spicy, so it’s no longer accomplished. Customers are exposed to key area fabric and encouraged to reuse keys true by intention of devices. Keys are trusted completely, so mistakes are fail-open.

The genuine recordsdata is that here’s all easy to repair.

None of these points are indubitably inherent to SSH. They’re indubitably issues with SSH public key authentication. The acknowledge is to switch to certificate authentication.

SSH certificate authentication makes SSH more easy to command, more easy to feature, and more true.


At smallstep, certificates are roughly our jam. We compose open source arrangement that permits you to saunter your possess deepest certificate authority and manage X.509 (TLS/HTTPS) certificates.

SSH certificates possess been on our radar for some time. From our level of view they’re all mavens, no cons. But no one uses them. Why no longer? We’ve requested a entire bunch of participants who quiz. Here’s what we learned:

  • Folk enact command SSH certificates. Actually, somewhat grand everyone working at scale that knows what they’re doing does (Fb, Uber, Google, Netflix, Intercom, Lyft, etc), however…
  • Certificates and public key infrastructure (PKI) are spicy to grok. Folk don’t true now notice the benefits.
  • There’s a (small) tooling gap that exacerbates this recordsdata gap. It’s no longer spicy to own, however folks are cautious to enact so themselves with out a deeper understanding of PKI ideas.
  • Bigger than anything else, SSH certificates haven’t gotten the click they deserve. Most folks we requested hadn’t heard of them at all.

We’re ecstatic that SSH certificates are the correct methodology to enact SSH. They’re no longer that onerous to notice, and it’s neatly price the misfortune. SSH certificates deserve more press, and broader command.

why don’t more people know about ssh certificates?

Public key authentication

Most SSH deployments command public key authentication, which uses uneven (public key) cryptography with a public / deepest key pair generated for every user & host to authenticate.

The magic of uneven cryptography is the special correspondence between a public and deepest key. You would also label recordsdata alongside with your deepest key and anyone else can compare your signature with the corresponding public key. Fancy a hash, it’s computationally infeasible to forge a signature. Thus, when that you just would possibly compare a signature, and you understand who owns the deepest key, you understand who generated the signature.

Easy authentication might moreover be implemented by spicy anyone to label a mountainous random amount. If I open a socket to you and ship a random amount, and you respond with a sound signature over that quantity, I possess to be talking to you.

Here is an oversimplification, however it’s more or less how SSH public key authentication works. Certificates authentication works the identical methodology, however with a indubitably crucial twist that we’ll accumulate to in a moment.

To SSH to a bunch using public key authentication the host needs to know your public key. By default, your public key possess to be added to ~/.ssh/authorized_keys. Asserting this file for every user true by intention of a fast is operationally spicy and error inclined.

SSH Deployment Rube Goldberg Machine

SSH user onboarding with public key authentication in general begins with some baroque incantation of ssh-keygen, confidently pulled from a runbook, however more likely cribbed from stack overflow. Next you’ll be requested to post your public key for approval and distribution. This path of is infrequently manual and opaque. You would also honest be requested to email an administrator or open a JIRA designate. Then you definately wait. While you’re doing that, some heart-broken operator gets interrupted and instructed so that you just would possibly possibly perchance add your key to a manifest in some repo and trigger a deploy. As soon as that’s accomplished that you just would possibly SSH. Since key bindings are eternal, your SSH access will continue in perpetuity unless anyone reverses this path of.

Certificates authentication

Certificates authentication eliminates key approval and distribution. As an more than just a few of scattering public keys true by intention of static files, you bind a public key to a title with a certificate. A certificate is neutral a recordsdata structure that involves a public key, title, and ancillary recordsdata devour an expiration date and permissions. The data structure is signed by a certificate authority (CA).

$ ssh-keygen -L -f id_ecdsa-cert.pub
        Kind: ecdsa-sha2-nistp256-cert-v01@openssh.com user certificate
        Public key: ECDSA-CERT SHA256:O6M6oIjDm5gPm1/aTY619BgC3KSpS4c3aHVWxYh/uGQ
        Signing CA: ECDSA SHA256:EY2EXJGoPv2LA6yEbjH+sf9JjG9Rd45FH1Wt/6H1k7Y
        Key ID: "mike@example.com"
        Serial: 4309995459650363134
        True: from 2019-09-11T14: 50: 01 to 2019-09-11T18: 50: 01
        Necessary Options: (none)

To allow certificate authentication simply configure purchasers and hosts to compare certificates using your CA’s public key (i.e., belief certificates issued by your CA).

On every host, edit /etc/ssh/sshd_config, specifying the CA public key for verifying user certificates, the host’s deepest key, and the host’s certificate:

# Path to the CA public key for verifying user certificates
TrustedUserCAKeys /etc/ssh/ssh_user_key.pub

# Path to this host's deepest key and certificate
HostKey /etc/ssh/ssh_host_ecdsa_key
HostCertificate /etc/ssh/ssh_host_ecdsa_key-cert.pub

On every client, add a line to ~/.ssh/known_hosts specifying the CA public key for verifying host certificates:

@cert-authority *.example.com ecdsa-sha2-nistp256 AAAAE...=

That’s it. That’s actually all that you just possess got to enact to delivery up using certificate authentication. You would also even command it alongside public key authentication to compose transitioning more easy.

SSH Certificate Authentication - Example Architecture

Static keys in ~/.ssh/authorized_keys will now not be any longer wanted. As an more than just a few, traffic study one one other’s public keys on ask of, when connections are established, by exchanging certificates. As soon as certificates possess been exchanged the protocol proceeds because it would with public key authentication.

Certificates authentication improves usability

With public key authentication, while you SSH to host for the foremost time, you’ll be presented with a security warning devour this:

$ ssh ubuntu@ec2-54-161-77-102.compute-1.amazonaws.com
The authenticity of host 'ec2-54-161-77-102.compute-1.amazonaws.com (' can't be established.
ECDSA key fingerprint is SHA256:2ae53QcOB0W6HO+XtPmMXk7To/MvMuhFxTj8ZD7eSsE.
Are you certain you devour to ought to continue connecting (certain/no)?

You’ve potentially seen this outdated to. If you’re devour most folks, you’ve been trained to ignore it by neutral typing “certain”. That’s a order because here’s a sound security risk. It’s also a moderately horrendous user experience. I’d wager the overwhelming majority of SSH customers don’t indubitably notice this warning.

If you SSH to a bunch, the host authenticates you. Your SSH client also makes an strive to authenticate the host. To enact so your client needs to know the host’s public key. Host public keys are saved in a straightforward database in ~/.ssh/known_hosts. If your client can’t salvage the host’s public key on this database you accumulate this warning. It’s telling you that the host can’t be authenticated!

Browser certificate warning is equivalent to TOFU

What you’re supposed to enact is compare the important thing fingerprint out-of-band by asking an administrator or consulting a database or something. But no one does that. If you form “certain” the connection proceeds without authentication and the general public secret’s completely added to ~/.ssh/known_hosts. Here is the belief on first command (TOFU) anti-sample.

Since certificate authentication uses certificates to talk public key bindings, purchasers are always ready to authenticate, despite the very fact that it’s the foremost time connecting to a bunch. TOFU warnings fade away.

Certificates authentication also gives a convenient build to gate SSH with custom authentication: when the certificate is issued. This might presumably be leveraged to additional enhance SSH usability. In exclaim, it let’s you lengthen single label-on (SSO) to SSH. SSO for SSH is certificate authentication’s greatest celebration trick. We’ll return to this conception and gape the intention it additional enhances usability and security later. For now, let’s transfer on to operability.

Certificates authentication improves operability

Taking away key approval and distribution has instantaneous operational benefits. You’re now no longer losing ops cycles on mundane key management tasks, and you accumulate rid of any ongoing charges associated with monitoring and asserting homegrown equipment for adding, eliminating, synchronizing, and auditing static public key files true by intention of your fast.

The potential to order SSH user certificates by intention of a diversity of authentication mechanisms also facilitates operational automation. If a cron job or script needs SSH access it’s going to compose an ephemeral SSH certificate robotically, when it’s wanted, as a replace of being pre-provisioned with a long-lived, static deepest key.

SSH public key authentication introduces some abnormal operational constraints around host names that certificate authentication eliminates. As we’ve seen, when an SSH client connects to a bunch for the foremost time it displays a TOFU warning to the user. When the user sorts “certain” the host’s public secret’s added locally to ~/.ssh/known_hosts. This binding between the host title and a exclaim public secret’s eternal. If the host gifts a totally different public key later, the user gets a honest correct scarier host key verification failure error message that looks to be devour this:

$ ssh ubuntu@ec2-54-161-77-102.compute-1.amazonaws.com
Any individual might even honest be eavesdropping on you correct now (man-in-the-heart attack)!
It's a ways in general possible that a bunch key has neutral been modified.
The fingerprint for the ECDSA key sent by the distant host is
Please contact your arrangement administrator.
Add upright host key in ~/.ssh/known_hosts to build up rid of this message.
Offending ECDSA key in ~/.ssh/known_hosts: 11
ECDSA host key for ec2-54-161-77-102.compute-1.amazonaws.com has modified and you've got got requested strict checking.
Host key verification failed.

This makes it operationally spicy to reuse host names. If prod01.example.com has a hardware failure, and it’s modified with a brand unique host using the identical title, host key verification mess ups will ensue. This in general outcomes in a bunch engineers contacting secops to converse them they’re being hacked.

Ignoring host key verification mess ups has the accurate identical attack ground dwelling as no longer lustrous the important thing at all. Curiously, OpenSSH chooses to soft-fail with an without wretchedness bypassed urged when the important thing isn’t identified (TOFU), however spicy-fails with a grand scarier and more mighty to avoid error when there’s a mismatch.

In spite of all the pieces, certificates repair all of this since a present title-to-public-key binding is communicated when a connection is established. Changing the host’s public secret’s gentle, so long as the host also gets a brand unique certificate. You would also safely reuse host names and even saunter a pair of hosts with the identical title. You’ll never gape a bunch key verification failure all all over again. Beyond title reuse, we’ll soon gape that eliminating host key verification mess ups is regarded as some of the many strategies certificate authentication facilitates genuine security hygiene.

Certificates authentication improves security

While the SSH protocol itself is true, public key authentication encourages a bunch of bad security practices and makes genuine security hygiene spicy to total.

With public key authentication, keys are trusted completely. A compromised deepest key or illegitimate key binding might even honest fade uncared for or unreported for a long time. Key management oversight (e.g., forgetting to take an ex-employee’s public keys from hosts) outcomes in SSH failing open: unauthorized access without live.

Certificates, on the varied hand, expire. In an incident — a mistake, theft, misuse, or key exfiltration of any compose — compromised SSH credentials will expire robotically, without intervention, despite the very fact that the incident goes uncared for or unreported. SSH certificates are fail-true. Access expires naturally if no motion is taken to lengthen it. And when SSH customers and hosts register periodically alongside with your CA to resume their credentials, a total audit story is produced as a byproduct.

We’ve already seen how public key authentication trains customers to ignore excessive security warnings (TOFU) and triggers spurious security errors. Here is better than an operational nuisance. Confusion precipitated by host key verification failure discourages host rekeying (i.e., changing a bunch’s key pair). Host deepest keys aren’t very neatly protected, so periodic rekeying is genuine practice. Rekeying might even honest be required after a breach or after offboarding a user. But, to purchase away from disruption from ensuing host key verification mess ups, it’s repeatedly no longer accomplished. Certificates authentication makes rekeying hosts trivial.

Public key authentication also makes rekeying complicated for customers. Key approval and distribution is anxious ample that customers are reluctant to rekey, even while you’ve constructed instruments to compose it possible. Worse, frustrated customers copy deepest keys and reuse them true by intention of devices, repeatedly for decades. Key reuse is a excessive security sin. Personal keys are never alleged to be transferred true by intention of a community. But SSH public key authentication exposes customers straight to soft deepest keys, then fails to give them usable instruments for key management. It’s a recipe for misuse and abuse.

An SSH CA, coupled with a straightforward converse-line client for customers, can streamline key expertise and insulate customers from a form of needless detail. Certificates authentication can’t entirely accumulate rid of all security risks, however it does facilitate SSH workflows that are more intuitive, more easy to command, and more mighty to misuse.

A perfect SSH waft

SSH certificate authentication is the root of what I believe is the genuine SSH waft.

To SSH, customers first saunter a login converse of their terminal (e.g., step ssh login):

$ step ssh login
Your default web browser has been opened for you to login: https://accounts.google.com/...

A browser is opened and an SSO waft is initiated at your group’s identity provider:

User authenticates in browser via SSO

A web based-essentially based totally SSO waft makes it easy to leverage solid MFA (e.g., FIDO U2F) and any other evolved authentication capabilities your identity provider gives. Customers login with a familiar waft, and eliminating a user from your canonical identity provider ensures urged termination of SSH access.

As soon as the user completes SSO, a bearer token (e.g., an OIDC identity token) is returned to the login utility. The utility generates a brand unique key pair and requests a signed certificate from the CA, using the bearer token to authenticate and authorize the certificate query.

The CA returns a certificate with an expiry long ample for a work day (e.g., 16-20 hours). The login utility robotically provides the signed certificate and corresponding deepest key to the user’s ssh-agent.

Customers needn’t be mindful of any of this detail. All they want to know is that, in expose to command SSH, they ought to first saunter step ssh login. As soon as that’s accomplished they’ll command SSH devour customary:

$ ssh prod01.example.com
Welcome to Ubuntu 18.04.2 LTS (GNU/Linux 4.15.0-1036-gcp x86_64)

Remaining login: Wed Sep 11 04: 04: 51 2019 from

Fancy browser cookies, short-lived certificates issued by this waft are ephemeral credentials, lasting neutral long ample for one work day. Fancy logging into a web web site, logging into SSH creates a session. It’s a straightforward path of that possess to be finished, at most, as soon as per day. Here is infrequent ample that solid MFA might moreover be mature without worrying or desensitizing customers.

Unusual deepest keys and certificates are generated robotically at any time when the user logs in, and they never contact disk. Inserting straight into ssh-agent insulates customers from soft credentials. If a user desires to connect from a totally different tool it’s more easy for them to saunter step ssh login there than it’s to exfiltrate keys from ssh-agent and reuse them.

There are a form of possible diversifications of this waft. You would also regulate the certificate expiry, command PAM authentication at the CA as a replace of SSO, generate the deepest key on a beautiful card or TPM, make a selection no longer to command ssh-agent, or transfer MFA to the genuine SSH connection. For my fragment, I believe this combination gives the finest balance of security and usability. Certainly, relative to most existing SSH deployments it’s operationally easier, more true, and more usable.

Critics of SSH certificate authentication screech that it’s unique, no longer neatly supported, and the tooling doesn’t exist to command certificates in practice. The fact is, certificate authentication used to be added in OpenSSH 5.4 nearly a decade ago. It’s struggle tested and mature in production by extensive operations. And the tooling required to compose this ideal SSH waft is on hand today time.

There are a form of existing instruments for managing SSH certificates. Listed below are a pair of:

For our section, the most contemporary delivery of step & step-ca (v0.12.0) provides stylish SSH certificate strengthen. In other words:

  • step-ca is now an SSH CA (as well to being an X.509 CA)
  • step makes it easy for customers and hosts to build up certificates from step-ca

SSH workflows aren’t fully fleshed out yet, however these instruments already enact all the pieces you need for the genuine waft.

With the correct configuration of step-ca that you just would possibly command step to:

Accumulate a bunch certificate robotically at startup

To existing, let’s form a brand unique EC2 event with the aws CLI instrument. The attention-grabbing bits are tucked in some light configuration (using a user-recordsdata startup script) that gets a bunch certificate and permits certificate authentication for customers:

$ aws ec2 saunter-conditions --image-id ami-07d0cf3af28718ef8 
    --rely 1 --event-form t2.micro 
    --key-title mike-test 
    --security-crew-ids delivery-wizard-7 
    --user-recordsdata file://startup.sh

Yelp: you needs with a purpose to command our event identity doc strengthen here, however we’ve received a pair of kinks to determine. End tuned.

Accumulate a user certificate using SSO (OAuth OIDC)

Now we’ll command step ssh certificate locally (that you just would possibly brew install step) to generate a brand unique key pair, accumulate a certificate from the CA using SSO, and robotically add the certificate and deepest key to ssh-agent.

That sounds devour a lot, however it’s neutral one converse:

$ step ssh certificate mike@smallstep.com id_ecdsa
✔ Provisioner: Google (OIDC)
Your default web browser has been opened to maneuver to:


✔ CA: https://ca.within
✔ Personal Key: id_ecdsa
✔ Public Key: id_ecdsa.pub
✔ Certificates: id_ecdsa-cert.pub
✔ SSH Agent: certain

As soon as that’s accomplished we can SSH to the event we neutral created, using certificate authentication, with out a TOFU!

$ ssh mike@ec2-100-26-100-55.compute-1.amazonaws.com
Welcome to Ubuntu 18.04.2 LTS (GNU/Linux 4.15.0-1044-aws x86_64)

Remaining login: Thu Sep 12 02: 25: 43 2019 from

For more data test out our getting started recordsdata and SSH example repo. Invent definite you fade the --ssh flag to step ca init while you’re developing the CA (the getting started recordsdata doesn’t enact this).

There’s a ways more that can perchance moreover be accomplished to compose SSH certificate authentication even more awesome. We’re working on that. If you possess got any strategies, converse us!

Exhaust SSH certificates

SSH certificate authentication does a lot to enhance SSH. It eliminates spurious TOFU warnings and host key verification mess ups. It permits you to tumble complex key approval & distribution processes and lengthen SSO to SSH. It makes rekeying possible for hosts and more easy than key reuse for customers. It makes SSH keys ephemeral, making key management oversights fail-true.

You would also deploy an SSH CA and reconfigure hosts in a subject of minutes. It’s easy to transition — that you just would possibly continue supporting public key authentication at the identical time.

SSH certificate authentication is the correct methodology to enact SSH.

At smallstep, we’re taking a watch forward to bettering our SSH story. We’re constructing out infrastructure and streamlined workflows to compose SSH better for everyone. And purchase an watch on our weblog because we now possess a ways more to screech about SSH!


Read More



“Simplicity, patience, compassion.
These three are your greatest treasures.
Simple in actions and thoughts, you return to the source of being.
Patient with both friends and enemies,
you accord with the way things are.
Compassionate toward yourself,
you reconcile all beings in the world.”
― Lao Tzu, Tao Te ChingBio: About: