How to setup multiple SSH keys for multiple git accounts (MacOS + Windows)

When I first ran into this problem of managing multiple git accounts, I had done a ton of research online. There were a lot of helpful sources of information, but they all had something missing. I had to patch together information from a variety of places. I’m bringing all my learning together here, to pass the baton I was given.😅

Before we get started, let me outline a few of the questions I will be answering in this article. I’ll be addressing:

1. Where are SSH keys stored on a Mac? What’s an RSA key?
2. What is an SSH config and how can I set one up?
3. What is a known_hosts file and what is an id_rsa file?
4. How can I manage all my SSH keys? What are SSH keys anyway?

If you’re wondering what SSH is, we won’t be covering the answer to that here, but you are welcome to take a look at the official page from the organization behind SSH. This page is quite helpful and concise.

MacOS ships with the OpenSSH implementation of SSH. You’ll notice this particular statement from the site:

The OpenSSH client program is called ssh. The SSH client generally uses information in the .ssh directory in the user’s home directory. It also reads /etc/ssh/ssh_config, which contains its system-wide configuration.

For the purposes of this article, we won’t worry about the system-wide configuration in this article. In most Unix / Linux systems, the local configuration is found in the user’s home directory under .ssh.

📚 Soaking up some knowledge

To explain what these are, we need to talk about keys first. There are a few types:

• Authorized keys and Identity keys are user keys. Authorized keys are public keys, similar to a lock. (🔒) Identity keys, are private keys, similar to a key that opens that lock. (🔑)
• Host keys are for host authentication, i.e. the entity you are trying to connect to. They are public keys. (🔒)
• The known_hosts file is where OpenSSH stores or remembers hosts that it has connected to previously. It only remembers host keys.
• Session keys encrypt the data in a connection. They change every session and use the host key to generate or use a mutual shared key.

We’ll get into how the key exchange works in a later article.

We’re primarily concerned with Identity keys and Host keys. Your identity keys when generated with no options look like id_<algorithm it was made with> by default and are usually in this .ssh folder. RSA is the most common algorithm in use, and the most widely supported, so you’ll see keys that look like id_rsa. RSA also happens to be the default algorithm. (Click here if you want to know more about the other algorithms)

However, it is possible to specify any file name, and any location when creating a private key. You can also provide a custom path pointing to a key somewhere else, with the -i option to the SSH client. For example, ssh -i /home/me/somepath/my-awesome-key ec2-user@awshost.amazon.com would use a private key from the file my-awesome-key for authentication when opening a secure shell to awshost.amazon.com as ec2-user.

💻 Setup

It’s time to generate a key! To do this, we’ll need to use the ssh-keygen command to make a key with a certain algorithm. Here’s what we’re going to run:

ssh-keygen -t rsa -f personal_key -b 2048

-t specifies the algorithm that makes the key. -f specifies a custom name for the key, and an alternate location if it’s in the form of a path. -b specifies how many bits long the key will be. By default, ssh-keygen will use the RSA algorithm with 2048 bit length. So, all we really need to do is specify a custom name!

⚠️ Make sure an existing id_rsa and id_rsa keypair don’t exist already. If they do, keygen will ask if you want to overwrite. This will permanently delete that old key you might have used elsewhere! Back it up, make a key with a different name, or if you’re sure, overwrite it.

This will generate two files: personal_key and personal_key.pub. The first is your private key (🔑), the second is your public key (🔒).

It’s time to make two hosts files for each of your profiles. You don’t have to make two, but it’s nice to keep the profiles completely separate. Run the following commands to generate the two files:

touch known_hosts
touch known_hosts_work

❗️NOTE: if you have a known_hosts file here already, there’s no need to make another one. If you want to rename it, you can do that — just make sure you use that name for the following steps.

🛠 Connect the dots with a config file

Finally, let’s bring it all together in a config file. There’s two of them, one for local, and one for global. As mentioned before, we’re focussing on the local. Use the following command to make a config file:

touch config

The config file is organized by hosts. Each host definition has a set of connection options:

• Comments can be made with # at the start of a line. These are for your eyes.
• The URL on the HostName line is the exact base URL at which your repository resides. This is your destination. For example, if you have a personal account on github, with personal projects, the URL will be github.com. In my case, I have my work version-control host URL, and my personal account at github.com.
• Host is a pattern matcher that is used to differentiate between these sets of configurations. Keep it the same as the HostName so it matches hosts in connections correctly without additional specification. If you want to use the personal_key as a fallback for every other URL, use an asterix * as the Host. The Host * configuration set is usually at the bottom of the config file, so it tests very configuration set until it gets to this one, if none of the previous Host patterns match.
• User for most git based systems will just be git. It will be different based on what you’re connecting to. E.g. ec2-user if you’re connecting to an Amazon AWS EC2 instance at ec2-user@some_server.amazonaws.com.
• IdentityFile asks for the location of the identity key we made. Type in the respective paths here.
• UserKnownHostsFile specifies an exact location to store all hosts you connect to when you’re using that profile. Provide the respective paths here.
• IdentitiesOnly specifies that only these keys provided must be used to connect to a host, even if another service, like the ssh-agent, offers a key for use.
• Port specifies what port number to use when connecting through SSH.

♻️ Cleanup

Let’s do some cleanup before we move on to the final step. We need to make the keys only readable by you, that way no one else can modify or tamper with your private keys.

As you can see in the picture above, there's 2 ways to set permissions. Either one of the following commands in your terminal work.

chmod go-wx, u=rw personal_key

or

chmod 600 personal_key

With letters

go-wx removes write and execute permissions from the group and others. u=rw sets the user (you) to only have read and write permissions.
+ adds permissions that follow. — removes permissions that follow. = sets the permissions to exactly what follows.

You can separate as many sets of these as you want, with commas ,.

With numbers

644 sets (4+2) read and write for you, and (4) read permission for everyone else. This should be done on the public keys only.
600 sets (4+2) read and write permissions for you, and no permissions for everyone else. This should be done on all the secret keys.

Either method you use, make sure all the public keys show rw for you and r for everyone else, while the secret keys show rw for you and nothing for everyone else.

✅ Ready all the systems

Almost there!

The last step is to add the keys to an ssh-agent so you don’t have to enter the passphrase and specify the key to use every time you ssh to a host. The agent essentially acts like your personal assistant; a butler of sorts. Take this quote from github.com:

When you git clone, git fetch, git pull, or git push to a remote repository using SSH URLs, you'll be prompted for a password and must provide your SSH key passphrase.

Why type the passphrase everytime, when the ssh-agent can do it for you?

Let’s add both our keys to the agent using the following command:

ssh-add -K personal_key
ssh-add -K work_key

To list the keys you just added:

ssh-add -l

To delete all keys from just the agent, use:

ssh-add -D

⚠️ Note that your keys are on an agent, so a passphrase isn’t required. Make sure no one else has access to your computer!

🔗 Test your connection

Now it’s time to add your keys to your accounts. Use the following to copy your respective key:

pbcopy < personal_key.pub
cat personal_key.pub | pbcopy # alternative command!

⚠️ Notice how the .pub key is used. This is the public (🔒) identity key that you want to provide to your git service. Don’t use your private (🔑) key! (the other file without the .pub extension)

Now paste it in the appropriate account, where SSH keys can be added. For github, you can get there through your personal settings:

Say you want to clone your repo locally. This is what the URL would look like:

Github says git@github.com:some_cool_project is what you want to use when cloning this project with the command: git clone git@github.com:some_cool_project.
Now, instead of git@github.com, if you used a different User and Host in the config file, you'd replace those parts of the clone command. For example, say you used another_user for User and personal.github.com for the Host you'd write:

git clone another_user@personal.github.com:some_cool_project

⚠️ Your git user name and email must be configured locally for every project, or you'll end up making commits on work and personal accounts with the global user name and email you've set for git!

💡 I'll do a deep-dive into the git config in a later article. Stay tuned!

You're all done! No need to manually specify the key you want to use, every-time you connect with SSH. The config and agent will automatically determine what key to use based on the host you're connecting to.

I hope that this article helped you today. If you feel like it'll help others, or if you have a correction or suggestion, I would love to hear from you. If you want to replicate this article for other operating systems, I would love to hear from you as well. Cheers!

Troubleshooting links

https://medium.com/r/?url=https%3A%2F%2Fhelp.github.com%2Fen%2Farticles%2Ferror-ssh-add-illegal-option----k

Further exploration

https://medium.com/r/?url=http%3A%2F%2Fwww.snailbook.com%2Ffaq%2Fabout-agent.auto.html
Understand ssh-agent and ssh-add - http://blog.joncairns.com/2013/12/understanding-ssh-agent-and-ssh-add/
SSH Key types (read about the better ed25519 key algorithm that is now in use)- https://chealion.ca/2016/06/20/ssh-key-types-and-cryptography-the-short-notes/