Use macOS Keychain to store your SSH passphrase

For anyone who deals with a remote server (let it be your own self-hosted server or GitHub), you probably have come across SSH. Basically, this is a way for you to connect to a remote server securely in a shell. For many of us who started their path to a software engineer from learning to use GitHub, we might have referred to the tutorial there:

Connecting to GitHub with SSH - GitHub Docs

You can connect to GitHub using the Secure Shell Protocol (SSH), which provides a secure channel over an unsecured network.

GitHub Docs

When running the command to generate a pair of ssh keys, you might encounter the prompt to let you enter a passphrase:

❯ ssh-keygen -t rsa -b 4096 -C "test" -f ~/.ssh/id_test
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):

For those of you who have entered something here, you will soon find out that, every time you try to use that pair of keys (e.g. authenticating with GitHub), you will be prompted to enter your passphrase. This soon can be cumbersome if you are a heavy user.

When I was watching a video on YouTube recently, I found out that 1Password, a password manager, had the feature that let you authenticate with your biometrics (e.g. Touch ID if you are on a Mac) in scenarios where you should have entered the passphrase.

As a heavy user of Bitwarden (actually just moved to Vaultwarden and love it! I will talk about it in later posts), I jumped into searching if this feature existed for Bitwarden too.

From this thread, it has been a long-time feature request but unfortunately has not been implemented yet.

Some community members introduced some brilliant workarounds. Two honourable mentions here:

However, if you just don't feel like using third-party tools, are there still other options?

The answer is yes! In this post, we will be talking about how to use macOS Keychain to make your life easier in this case.

Step 1. Generate SSH keys like normal

❯ ssh-keygen -t rsa -b 4096 -C "test" -f ~/.ssh/id_test

For your reference, what those parameters mean is:

-t type
Specifies the type of key to create. The possible values are ''rsa1'' for protocol version 1 and ''rsa'' or ''dsa'' for protocol version 2.

-b bits
Specifies the number of bits in the key to create. For RSA keys, the minimum size is 768 bits and the default is 2048 bits. Generally, 2048 bits is considered sufficient. DSA keys must be exactly 1024 bits as specified by FIPS 186-2.

-C comment
Provides a new comment.

-f filename
Specifies the filename of the key file.

Please note that, the -C won't change the behaviour of your keys so feel free to write anything you want to remind yourself of.

Of course, when prompted for a passphrase, enter one.

Step 2. Add your SSH public key to the host

This is also like usual. If you are trying to SSH into a remote machine, just log in using username and password first, and add the content of your public key (the one with .pub suffix) to the file:

> vi ~/.ssh/authorized_keys

Remember: one public key content per line.

For GitHub, that's even easier. Just some clicking and copy-paste. Please refer to their doc about this part.

Step 3. Add your passphrase to Keychain

> ssh-add --apple-use-keychain ~/.ssh/[your-private-key]

You will be prompted to enter the passphrase again. And after this, you have successfully added your passphrase to Keychain!

Step 4. Let your SSH agent know

Lastly, let's edit ~/.ssh/config.

Host * # or enter your host IP or domain name
    IgnoreUnknown UseKeychain # this tells ssh agents on other platforms not throw error on this UseKeychain
    UseKeychain yes
    AddKeysToAgent yes
    IdentityFile ~/.ssh/[your-private-key] # path to your private key

And that's it! From now on, every time you ssh you will not be asked for a passphrase (as Keychain is already unlocked when you log in to your Mac) and you still enjoy the safety of keys being protected by a passphrase.

Enjoy!