Rotate and upgrade your SSH keys

SSH is an invaluable tool for us developers and sysadmins, and it continues to be perhaps the most secure way to access and operate remote machines, despite being introduced almost 30 years ago.

The time came for me to rotate my client keys again and this time I decided write down why and how to do so. I hope it helps someone else.

Why rotate SSH keys? #

When establishing a connection to a server through SSH, your computer authenticates itself to the host through public-key cryptography using a key pair. Like most other types of credentials, it is good security hygiene to regurlarly review and rotate your key pairs to maintain a strong security posture.

Maybe you, like many others, have been moving the same SSH keys from one device to another for a decade to avoid the hassle of configuring everything again. Or maybe you experienced a catastrophic failure and restored a backup of your old computer to a new one. Meaning the keys could still be lying around on old laptops, company devices, or unencrypted disks.

Importantly, SSH keys are meant to be per-host, ie. a separate pair of keys for each device you use. So when you get a new computer you should generate a new key pair and configure access to each server or service you use. But in my experience, most developers do not realize this (including myself for a long time). And if they are aware, many still choose to not follow the practice because of the perceived hassle.

Maybe you’ve only ever had one key pair on the same device for many years, but it was generated back when the recommended key size was a lot smaller. These days the default size for new RSA keys is 3072 bits, while the recommended size is 4096 bits. So if your key is, say 1024 bits or fewer, then it’s also time for an upgrade.

Why switch to a different type of key? #

While we usually just refer to them as “SSH keys”, that is just a generic term for different types of key pairs based on various cryptographic algorithms. One doesn’t need understand or even know about the cryptography or mathematics behind these algorithms, we can instead rely on the recommendations from industry professionals.

Let’s look at the main types available in our local SSH client¹:

• DSA ( ssh-dsa ) 🛑
  DSA is considered insecure and should not be used². It was deprecated by the OpenSSH project in 2015 and was removed from the latest FIPS standard³.

• RSA ( ssh-rsa ) ⚠️
  Based on prime numbers and has been the most commonly used algorithm for decades. It is still going strong and is considered to be secure, but you do have to check the length of the key. If it is less than a 1024 bits, it should be considered insecure. On the other hand, if your key is 3072 or more bits (many are 4096 bits) then you’re all good!⁴.

• ECDSA ( ecdsa-sha2-nistp256 and others) 👎
  An elliptic curve implementation of DSA that has been standardized and used widely for many years. This and other algorithms coming out of NIST are subject to speculation. Many believe they are safe, while others believe that they are “backdoored” by the NSA⁵. For practical purposes, it doesn’t really matter whether that is true or not, because these implementations are vulnerable to some of the same issues as DSA anyway. Furthermore, they also rely on securely generating random numbers, which is always difficult and can lead to real problem as we saw with the PlayStation 3 hack⁶. So there are multple reasons to avoid this category if you can.

• Ed25519 ( ssh-ed25519 ) ✅
  Based on Edwards elliptic curves and comes from the modern EdDSA family of signature schemes.⁷ Despite the confusingly similar names, it is unrelated the above ECDSA family. Ed25519 is widely regarded as the recommended public-key signature algorithm today. It is faster, safer to use, and more secure than alternative algorithms.⁸ The keys and signature are significantly smaller than those of RSA and it is designed to be more resilient to side channel attacks than ECDSA⁹. And it does not rely on random numbers as input, meaning less problems for implementers and users.

Since many of us use git over SSH for our daily work, it is worth noting that GitHub dropped support for DSA keys and RSA keys used with a dated signature algorithm (SHA-1) in late 2021. And since March 2022 only ECDSA, Ed25519, and RSA (with SHA-2 signatures) are supported.¹⁰

Which type to choose? #

To sum up the previous section, you could create a fresh set of RSA keys and be reasonably secure, as long as is 4096 bits or more and uses SHA-2. One could even argue that it is overkill for our daily development work.

But security is a moving target and modern elliptic curve cryptography offers quite a few advantages that you might as well take advantage of when generating new keys. So for the rest of this post I will walk you through how to generate a new key pair based on Ed25519 and how to use it to connect to GitHub.

Which type are your current keys? #

Check the folder #

Navigate to the default SSH folder and list out all the files:

$ cd ~/.ssh
$ ls -l
config        # Your SSH configuration file
id_rsa        # Your SSH private key (RSA)
id_rsa.pub    # Your SSH public key (RSA)
known_hosts   # List of servers you 'trust'

The default filename for new key pairs is id_, followed by the key type. For example: id_rsa.pub, id_ecdsa.pub, or id_ed25519.pub - meaning RSA, ECDSA, and Ed25519 type keys respectively.

Ask the agent #

As shown above, it is common to look in the ~/.ssh folder on your computer to find your keys, but there might be SSH keys in use that are located elsewhere.

So let’s ask the ssh-agent which keys it knows about, using the list option:

ssh-add -l

The command prints a list of keys and their details in the following format:

$ ssh-add -l
# Length  Fingerprint                   Comment         Type
  4096    SHA256:R4DFsSQ23wSpKDcAfE...  user@hostname   (RSA)

Which tells us that the key in this example is a 4096-bit RSA key.

(This is assuming that the agent is running and working correctly. If it is not working for you, take a look at this article: Generating a new SSH key and adding it to the ssh-agent | GitHub Docs).

Archive the old keys #

You can have as many key pairs on your computer as you want and it is even prudent to use different key pairs for different contexts. But as time passes it is easy to forget which keys were made when and for what purpose.

So I recommend that you archive all your current ones, generate a new key pair, and then later generate purpose-specific ones as the need arises.

Back up #

We don’t want to simply delete the old keys right away, because we could get accidentally locked out. By renaming and moving the keys first, we can gradually migrate away without the risk of losing access.

You can back up the entire folder using the archive option of the copy utility:

cp --archive ~/.ssh ~/ssh_backup

The result is a full copy of the folder, hopefully with permissions and everything intact in case you need later.

Rename #

If you already have an existing id_ed25519 key pair, rename the files to something else to avoid confusion and conflicts, for example:

# Rename existing keys to have the prefix "old_"
mv id_ed25519 old_id_ed25519
mv id_ed25519.pub old_id_ed25519.pub

Inform the agent #

As mentioned earlier, the SSH agents keeps track of the keys in use on your computer. But unless configured to do so, it does not automatically react to changes you make to the key files.

So once you have archived and renamed your existing key(s), you need to remove them from the SSH agent.

You can do so using the -D or -d options in ssh-add:

# Remove all known keys pairs
ssh-add -D

# Remove a single known key pair
ssh-add -d ~/.ssh/id_rsa

Generate a new key pair #

Unless you know what you are doing, you should not generate key pairs without a passphrase. So first, generate a very strong passphrase in your password manager of choice and copy it.

Then, generate a new SSH key pair:

ssh-keygen -t ed25519 -a 100 -C "laptop"

Explanation of the options:

• -t: sets the key type to Ed25519 instead of RSA, as discussed above.
• -a: set the number of Key Derivation Function rounds to perform. In short: The higher the number is, the slower the verification of the passphrase is, meaning bruteforce attempts get slowed down. But it also means that verification of your passphrase is slower in general use, so it is a tradeoff of performance vs security. The default value is 16.
• -C: adds a comment to the key to make it easier to identify later. The comment is stored as a string at the end of the public key and in encrypted form inside the private key. It can be changed later, so don’t worry too much about it, just don’t put anything sensitive here. The default value is user@hostname.
  

  A note on comments:
  Many guides suggest that you use your email address, and some even seem to imply that it’s mandatory. It’s really not and there’s no good reason to do so. Though if you are working with other people and connect to machines that store multiple public keys, it’s a good idea to use some sort of identifier like your initials or username so it is easier to tell the keys apart.

When you run the command, you have to choose where to put the file (default is fine) and enter a passphrase for the key (paste the one you generated earlier):

$ ssh-keygen -t ed25519 -a 100 -C "laptop"
Generating public/private ed25519 key pair.
Enter file in which to save the key (~/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in ~/.ssh/id_ed25519
Your public key has been saved in ~/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:9f32ks02FW2FwOPiDf3F02Rd2VkAksogx2Cb1auIHKUSv8 laptop

Update your config #

Make sure to update your SSH configuration to use the new identity. To update it, you can open the ~/.ssh/config file in your editor of choice.

Here is an example of how to set a configuration for GitHub:

Host github.com  
  User git
  PubkeyAuthentication yes
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

Inform the agent, again #

The SSH agent needs to be told about new keys manually, we can do so using ssh-add:

ssh-add id_ed25519

You might need the --apple-use-keychain option if you are on MacOS.

Then, use the list option to verify that the new key is listed and the old ones are no longer there:

$ ssh-add -l
SHA256:9f32ks02FW2FwOPiDf3F02Rd2VkAksogx2Cb1auIHKUSv8 laptop

Test the new key #

To test the new key, you can use a service that offers SSH access like GitHub.

1. Follow the steps in their guide, to associate your key with your account: Adding a new SSH key to your GitHub account - GitHub Docs

2. Connect to GitHub to test that the key is working:

ssh -T [email protected]

Authenticity and fingerprints #

When connecting, you may see a notice about the authenticity of the server. Make sure that the fingerprint you are seeing in the response, matches one of the SSH key fingerprints GitHub has published publicly: GitHub’s SSH key fingerprints - GitHub Docs

So for example:

$ ssh -T [email protected]
The authenticity of host 'github.com (140.82.121.4)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes

At the time of writing, the fingerprint in the SSH response (SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU) matches the one GitHub has published for Ed25519 on their site. So I can reasonably conclude that I am in fact connecting to the real GitHub and not an imposter. I accept the connection by typing yes.

If everything has gone as planned, you should see this response:

$ ssh -T [email protected]
Hi vanjacosic! You've successfully authenticated, but GitHub does not provide shell access.

Congrats, you have successfuly rotated and upgraded your SSH keys to keep up with the latest standard in security and performance!