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:
- Where are SSH keys stored on a Mac? What’s an RSA key?
- What is an SSH config and how can I set one up?
- What is a known_hosts file and what is an id_rsa file?
- 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
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. (🔒)
known_hostsfile 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 firstname.lastname@example.org would use a private key from the file
my-awesome-key for authentication when opening a secure shell to
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 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.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:
❗️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.
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:
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
HostNameline 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
Hostis a pattern matcher that is used to differentiate between these sets of configurations. Keep it the same as the
HostNameso it matches hosts in connections correctly without additional specification. If you want to use the
personal_keyas 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.
Userfor most git based systems will just be
git. It will be different based on what you’re connecting to. E.g.
ec2-userif you’re connecting to an Amazon AWS EC2 instance at
IdentityFileasks for the location of the identity key we made. Type in the respective paths here.
UserKnownHostsFilespecifies an exact location to store all hosts you connect to when you’re using that profile. Provide the respective paths here.
IdentitiesOnlyspecifies 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.
Portspecifies what port number to use when connecting through SSH.
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
chmod 644 personal_key
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
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.
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:
git pull, or
git pushto 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:
To delete all keys from just the agent, use:
⚠️ Note that your keys are on an agent, so a passphrase isn’t required. Make sure no one else has access to your computer!
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
Now paste it in the appropriate account, where SSH keys can be added. For github, you can get there through your personal settings:
email@example.com:some_cool_project is what you want to use when cloning this project with the command:
git clone firstname.lastname@example.org:some_cool_project.
Now, instead of
email@example.com, if you used a different
Host in the config file, you'd replace those parts of the clone command. For example, say you used
personal.github.com for the
Host you'd write:
git clone firstname.lastname@example.org: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!
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/