Handling SSH keys on macOS can be confusing as heck, and it doesn’t need to be. I’ve seen it done a million overcomplicated ways, and I’m part of the guilt-ridden many. So let me try to start over here, one more time, from the top, and offer the simplest and safest solution I can.
When they’re set up simply and safely like this, and you don’t have to worry about them, you can really unlock their potential. Git becomes a breeze to use, for sure, but you can also use all kinds of remote resources in all kinds of useful ways. I’ll go more into detail on what’s going on and why I made the choices I did at the end of this post. And next time, we’ll cover more complex setups that build on this.
From Zero to Keyed
Creating an SSH key is a straightforward three-step process.
① Generate a random passphrase.
You won’t ever need to type it again, and you won’t be managing it yourself, so go ahead and use 1Password’s password generator and generate a random password.
20 characters long using letters, numbers, and symbols is awesome and recommended. Copy it to your clipboard.
② Generate an SSH key.
ssh-keygen
When asked for a passphrase, paste your passphrase in (both times).
③ Add the passphrase for the SSH key to the macOS Keychain.
ssh-add --apple-use-keychain
Now you have an SSH key in “.ssh” in your home directory. You have the public key (ending in “.pub”) that you should upload to other systems you want to access. You also have the private key (no suffix), which should stay on your system. Note, though, it’s protected by that passphrase that you will never need to remember or type!
Testing
Now, there are actually a few leftovers in your current session at this point. To really test things out, you should either log out and back in, or reboot. Someday, you’ll need to reboot for an update; this will test that path.
Once you do that, if you try to use the “ssh” command, you’ll get prompted for that passphrase. This is resolvable a number of ways, but the easiest is to stick one line in a file called “config” in “.ssh” in your home directory:
UseKeychain yes
This tells macOS’s version of OpenSSH that, when it either needs a passphrase or gets a passphrase, it should involve Keychain, where that very random passphrase we created earlier is now. macOS gets it, decrypts your SSH key, and uses it.
And that is all you need to do in order to simply and safely manage a basic SSH key setup on macOS.
So let’s talk a bit about the details.
The SSH Agent
There’s been a bit player in this whole dance that I’ve been explicitly avoiding talking about: the SSH agent.
A lot of configurations explaining how to use macOS’ Keychain support involve the agent (usually with “AddKeysToAgent yes” in the “config” file). I’ve found it to not only be not necessary, but actually a complicating factor in my more complex setups.
The agent is a program that holds decrypted keys in memory. It’s from the (now ancient) days of Unix when we used to type our passphrases to unlock our keys every time we signed in. The agent would then keep our keys for us as long as it was still running.
macOS does run an agent, too. But since the Keychain always has the passphrase available, “ssh” is perfectly capable of decrypting a key on its own, on the fly, without any further input. This eliminates the need for the agent day-to-day.
We did actually use the agent briefly for a side effect above, using “ssh-add” with an extra flag to save the key into the Keychain. That also put the decrypted key temporarily into the agent, which is why I asked you to log out or reboot.
Losing a Passphrase
If you’ve been thinking curiously and deeply about this process, you may also have a question about the passphrase: what happens if we lose it?
The answer is simple: we shrug, throw away the key, and make a new one.
For nearly all uses of SSH keys I have day-to-day, I have a path into the system I am trying to access that does not require the key. The key is a way to easily access specific services, not my final authentication.
In the rare case that it is, then I should save both my private key file and my passphrase. Even if I didn’t copy the passphrase out of my clipboard, it can be retrieved from Keychain Access—just search for “SSH” items.
Multiple Computers
Have a number of computers that you want to use Git from? Cool! Generate keys on all of them.
I used to copy the same key around to all my systems. This sounded convenient, but in practice, it meant that I was handling private key material a lot more than I needed to.
Keys are cheap, it turns out. Make lots of them, and pick and choose which ones have access to which services.
Specific keys for specific services actually leads me into my next topic…
Okay, but I really want to do more…
In this post, we created one basic SSH key, most likely called “id_ed25519”. It’s a single identity for a single machine. But the reason a lot of people start falling down the SSH rabbit hole is because they start to realize they have more complex needs.
For example: Azure DevOps bizarrely still requires RSA public keys. (If that’s all you need, consult “man ssh-keygen”; the “-t rsa” flag might help you out.) But also, very commonly, because people have distinct work and personal GitHub accounts, and distinct SSH keys for each.
I’ll talk about my approach for this in the next post: SSH keys on macOS, part 2: building a key system.