Setting up SSH keys on a linux server (so that you cannect to other hosts such as Github) is one of those tasks that many of us have to do infrequently. If you’re as forgetful as me, that means you have to work out how to do it all over again almost every time the need arises. Here’s a quick reminder.

Some key files

SSH keys – both incoming and outgoing are usually to be found in your home directory within a directory named .ssh. Here are some of the files you might see:

authorized_keys Contains external public keys. Used by your ssh server to grant access. In other words, keys here are used to confirm that an incoming connection is authorised.
config Configuration file. You can create shortcuts and manage the behaviour of ssh here.
id_rsa (or id_dsa or, id_ecdsa, id_ed25519, identity) A private key. This is the secret key you keep only on the current machine. It identifies you as who you are when you try and log in somewhere that has your public key.
id_rsa.pub (or id_dsa.pub, id_ecdsa.pub, id_ed25519.pub, identity.pub) This is your public key. When someone asks you for your key, it’s this you give them. It’s this we give to github and the like.

You may already be good to go.. take a look:


cd; # sends you to your home directory
ls -l ~/.ssh

If you you don’t find a set of matching public and private keys or if you get an error that says .ssh/ does not exist, don’t worry – read on!

Generating keys

If you don’t already have ssh keys – or if you’d like to generate shiny new ones, this is the section for you.

Remember that when you generate keys you are setting up access FROM your server TO somehere else. Let’s do it

cd;
ssh-keygen -t rsa -b 4096 -C "your@email.address"

Here is my output:

Generating public/private rsa key pair.
Enter file in which to save the key (/home/bob/.ssh/id_rsa): 
Created directory '/home/bob/.ssh'.
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /home/bob/.ssh/id_rsa.
Your public key has been saved in /home/bob/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:9yd0eX1MBeMpfXG7pga+O0wM0RhSEXpnyDsp3MH+vSs your@email.address
The key's randomart image is:
+---[RSA 2048]----+
|       ..=*   ooo|
|        =o.. o o=|
|       . *.o. +.o|
|      . +.*  . =o|
|       oS*+.. oo=|
|        ..+=o.o..|
|          ooo+.  |
|           Eoo.  |
|           o+o.  |
+----[SHA256]-----+

Now I should see my public and private keys on the filesystem:

$ ls -l .ssh/
total 8
-rw-------. 1 bob bob 1766 Jul 30 18:43 id_rsa
-rw-r--r--. 1 bob bob  402 Jul 30 18:43 id_rsa.pub

Adding keys to github

Once you have logged in to your github account, click on the avatar icon in the top right hand corner and choose Settings. Then select SSH and GPG Keys from the list on the left hand side. Then click on the New SSH key button.

Paste in the contents of the id_rsa.pub file.

Click on Add SSH Key and you should be done.

Let’s try it out

$ git clone git@github.com:popp5-bob/sample.git
Cloning into 'sample'...
Enter passphrase for key '/home/bob/.ssh/id_rsa': 
remote: Counting objects: 3, done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (3/3), done.
Checking connectivity... done.

Troubleshooting: permissions

In my experience, the most common cause of problems with ssh keys on Linux is incorrectly set file permissions. Your private key file must be readable only to you – not to any other groups and certainly not to the world. To simulate this problem I have made my id_rsa file world readable.

$ git clone git@github.com:popp5-bob/sample.git
Cloning into 'sample'...
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@         WARNING: UNPROTECTED PRIVATE KEY FILE!          @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Permissions 0666 for '/home/bob/.ssh/id_rsa' are too open.
It is required that your private key files are NOT accessible by others.
This private key will be ignored.
Load key "/home/bob/.ssh/id_rsa": bad permissions
Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights

The fix for this is easy. I just need to adjust my file permissions using the chmod command (0600 makes a file readable by the user only):

$ chmod 0600 .ssh/id_rsa

and now I can connect once again

$ git clone git@github.com:popp5-bob/sample.git
Cloning into 'sample'...
Enter passphrase for key '/home/bob/.ssh/id_rsa': 
remote: Counting objects: 3, done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (3/3), done.
Checking connectivity... done.

If you’re still having problems, you can get more information about what might be going wrong by connecting to github (or to any other host that authenticates you using your public key) via ssh – using the -v flag to enter debug mode. You won’t be able to connect to a shell at github.com – but the server will tell you if you authenticated.

$ ssh -v git@github.com
OpenSSH_7.2p2, OpenSSL 1.0.2j-fips  26 Sep 2016
debug1: Reading configuration data /etc/ssh/ssh_config
debug1: /etc/ssh/ssh_config line 58: Applying options for *
debug1: Connecting to github.com [192.30.253.112] port 22.
debug1: Connection established.
debug1: identity file /home/bob/.ssh/id_rsa type 1
# much deleted here!
Hi popp5-bob! You've successfully authenticated, but GitHub does not provide shell access.
# a bit more deleted here

If your authentication failed, the reason should be buried within all those debug lines!

“Key” by German via The Metropolitan Museum of Artis licensed under CC0 1.0