Creating an SSH Key for Git, Explained for 5 Year Olds

When you’re only 5 years old, it can be confusing to use git and ssh, due to the many different concepts involved. This guide explains each step simple terms that any child will be able to understand.

SSH stands for Secure Shell. It’s a way of accessing another computer securely. For a git repo, it’s a more secure alternative to using a username and password to get access.

This guide will explain how to make an SSH key pair, and use it to access a git repo.

Step 0: Access the Command Line

The tools you need exist on most computers by default as command line tools.

• On Mac, open Terminal (command + space → terminal.app).
• On Windows, look for Git Bash. This should exist if you have git installed. If not, download and install Git before continuing.

Step 1: Create an SSH Key Pair

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

ssh-keygen is the program that’s going to generate an SSH key for us.

-b means bits and 4096 is the number of bits the key will use. That’s a lot of bits for lots of security! 2048 is the default and is already enough, so this key will be unbreakable by any modern computer.

-C means ‘comment’, and the email address is the value of this comment. This tells the computer we’re accessing who we are.

You don’t need to provide a location to store the key because you will be asked.

→ Run the above command

It will ask you where you want to save the key pair. Just press enter to accept the default location of ~/.ssh , which is a hidden folder (because it starts with .) in your user folder.

It will also ask you if you want to create a password. You can press enter to ignore this and not set a password. SSH is secure enough without one, but use one if you’re worried about people stealing your laptop or keys.

What did it create? If you look in ~/.ssh you’ll see two files:

• id_rsa is your ‘private key’, meaning it should never be shared with anyone.
• id_rsa.pub is your public key. This is what you’ll give to your git repo so that it can verify your identity when you try to access it.

You may not be able to see hidden files and folders as this is the default setting on most computers, but you can use the command line to look at this folder if you want to. Use cd ~/.ssh to change directory and then ls -a to list all the files in there.

Step 2: Get your public key

Run this command in the console to see the public key’s value. cat is a bash program that reads text files and prints their content to the terminal. You could also open the file in TextEdit/Notepad to see the key.

cat ~/.ssh/id_rsa.pub

Then copy the key to you clipboard. It should begin with “ssh-rsa” and end with your email address.

Step 3: Upload the Key to Your Git Repo

For Github repos: Go to github.com/settings/keys, and click ‘New SSH key’. It will ask you to give it a name. Paste the public key from step 2 in the ‘key’ box. Click ‘Add SSH key’.

Now GitHub knows your public key, and when it sees you trying to connect it will grant you access because you and only you have the matching private key!

Step 4: Git Clone or Set Remote

Find the SSH url of the repo by clicking ‘Code’. Copy the value it shows you. Make sure SSH is selected, see below:

Then run git clone with the value you copied, e.g.:

git clone git@github.com:example/example.git

If you already cloned your repo before now, you may need to change the remote to use SSH instead of HTTP:

git remote set-url git@github.com:example/example.git

Now just test it works:

git pull

When you run this, the git program automatically looks for the private key you made called id_rsa to authenticate. You don’t need to tell it where the key is, or enter any passwords, unless you set a password for this key.

THE END. If you get any errors, scroll down for tips.

Photo by Cookie the Pom on Unsplash

If you see ‘WARNING: UNPROTECTED PRIVATE KEY FILE!’

Don’t panic. This just means other users on your computer can access the private key. You may be the only user on your computer, so this may not seem relevant, but it if you were to let someone else connect to your computer remotely, they would have access to these files, so it’s safer to prevent others from reading them.

We’ll use chmod which means ‘change mode’. This is a program found on all Unix based computers that is used to change the permissions that ‘users’ have on the file.

Run:

chmod 400 ~/.ssh/id_rsa

The three numbers in represent the permissions of the user, group, and others, in that order, where each number means:

• 0 = no permissions (can’t even open it)
• 1 = execute (run a file as a program)
• 2 = write (make changes to)
• 4 = read
• 7 = all permissions

Therefore, the command above is going to make the private key readable only by the user (you), and not readable by anyone else. The SSH program asked you to do this to make it even more secure.

If you see ‘Failed to add the host to the list of known hosts’

This means the list of computer host names that your computer trusts (or ‘knows’) couldn’t be added to by the ssh program, due to it not having permission to do so. As above, we need to change the permissions on this list using chmod.

sudo chmod 644 ~/.ssh/known_hosts
sudo chmod 755 ~/.ssh

If you see ‘You’re using an RSA key with SHA-1, which is no longer allowed. Please use a newer client or a different key type’

Please see https://github.blog/2021-09-01-improving-git-protocol-security-github/ for more information.

—

Thanks for reading. If you run into any other issues when doing this feel free to leave a comment and I’ll add it to the guide.

For more programming tips, follow me on Twitter: @MattSimmons01

Reach out to us at datasparq.ai/contact or @DatasparqAI on Twitter for advice on solving a problem with AI and Data!