To the inexperienced, learning to configure SSH key authentication is one of those things that might seem like more trouble than it’s worth. Unless you’re a battle hardened sysadmin, talk of public and private keys can be daunting and the price of a slight misunderstanding could be a compromised server or stolen data. However, once properly prepared, it allows you to log in using a special password that can not be guessed and is nigh on impossible to steal.

Fortunately, configuring SSH key authentication only takes a few minutes to set up even for the uninitiated, and the concepts behind the magic are relatively easy to understand.

For this article, I’ll expect that you can already connect to a Linux server via SSH with a password, have little or no problem navigating to directories and running simple commands via Linux terminal, and are familiar with the concepts of user accounts and home directories.  This should work with little variation on most Linux distros.

The basics

There’s really only a few steps:

• create a public and private key pair on each machine you want access to or from
• copy the public key from the client machine to the authorized_keys file on the SSH server
• profit?

For this post, I’ll refer to the Linux server that you want to SSH into as The Server and the connecting workstation – Linux, Windows or macOS – as The Client.

If you’re connecting from a Windows machine, there are a few more steps and programs involved. I’ll go over them as well.

The keys

So, the first step to configure SSH key authentication is creating your public and private keys. What exactly are keys, you ask? Well, they’re essentially huge, complex passwords, created and used in pairs.  One of the pair (the public key) you give out to The Server and the other (the private key) you keep secret on The Client, the machine you’re connecting from. Basically (and waaaay oversimply), when you add the public and private keys to each other, you should get a specific answer. If the answer is correct, then you’re in. If not, you’re not.

To be extra clear, you only need to worry about moving the public key of The Client to The Server’s authorized_keys file and not the other way round.

SSH Keys on The Linux Server

On a Linux machine, SSH keys are stored as text files that reside in the home directory of the user you’re logged in as.

If you’re using the root user (you really shouldn’t be, according to best practices), it would likely be

/root/.ssh

If you’re using another account, it would likely be

/home/username/.ssh

Along with the keys, you’ll find a few other text files that are created when keys are generated:

• id_rsa – The user’s private key
• id_rsa.pub – The user’s public key
• authorized_keys – A list of public keys from machines that are allowed to connect to the current machine
• known_hosts – a list of machines that have successfully connected at least once to the current machine

This .ssh directory is created in the current user’s home directory if there isn’t one already. You copy The Client’s public key to the authorized_keys file of The Server and that’s that.

Creating the keys

On a Linux or macOS system, it’s easy enough to generate keys via the terminal using the built-in ssh-keygen command.  On Windows, third party software is required.

Linux/macOS/OS X:

Open a terminal window and type the following:

ssh-keygen -t rsa

and press enter.  It will ask where the keys should be saved.  Press enter again to accept the default of the current users home directory.

The next step asks for a passphrase for the private key, which I recommend you set; even a simple one.

The next step, after repeating your passphrase if you wanted one, is the computer creating a new 2048 bit RSA key pair in the home directory of the user you’re logged in as.

Now your keys are done but need to be transferred to The Server.

In the terminal, type

ssh-copy-id user@hostname.example.com

where user is the user name on The Server, and @hostname.example.com is the address of The Server.  It will ask for your password on the remote machine, then move the id_rsa.pub of whoever you’re logged in as to the remote server.

Now you should be able to

ssh user@hostname.example.com

and be in without a password.  You can skip to The SSHD.

Windows:

To configure SSH key authentication on Windows, which doesn’t have a key generating command like Linux and macOS, you’ll need a couple of tools.  You probably already use PuTTY to SSH into a Linux server, so you might as well download and use some of the other PuTTY tools you’ve always skipped over: PuTTYgen and Pageant.

PuTTYgen takes the place of ssh-keygen and gives you a nice Windowsy GUI to mouse your way to a new ssh key. Pageant works in tandem with PuTTY and automates the whole key management and handshake for you.

Download PuTTYgen and Pageant from the download page. Put all three in the same directory – I just dump them into a “putty” folder in my documents.  Fire up PuTTYgen and you’ll see a pretty stark interface (but that’s a good thing):

Leave everything at their defaults and click the “Generate” button. PuTTYgen will ask you to move the mouse around, using this random cursor positioning information to generate your key pair.  After it finishes, you’ll have a bunch characters at the top of the window that make up your public key as well as a fingerprint and comment:

Don’t expect your numbers to be the same as mine; they will all be different and I’ve also obscured some details to deter the scoundrels.  I KNOW YOU’RE OUT THERE!

Put a passphrase in the “Key Passphrase” and “Confirm Passphrase” boxes (or not – but seriously, I recommend it). Go ahead and save the public and private key to the directory of your choice and fire up Pageant.  It works from your system tray, so right-click the icon of a computer wearing a hat and choose “Add Key”.  Navigate to the private key, the ppk file that you saved a moment ago, and choose it.   If it asks, put in the passphrase you chose during creation.

Now you can right-click Pageant in the system tray and click “New Session”.  If you put the programs in the same directory like I mentioned, it will launch PuTTY.  Magic.

Copy the public key from the top of the PuTTYgen window to your clipboard, and head over to The Server.

Where the key goes

You’ll need to SSH into The Server and paste the PuTTYgen public key into The Server’s authorized_keys file.

If The Server’s keys haven’t been generated already, set up keys using the same method detailed in the Linux instructions above.  After the key pair is done, use your favorite text editor to edit

/home/username/.ssh/authorized_keys

and paste your public key to the first blank line in the file.  Save the file and you are done setting up the keys.

The SSHD

CAREFUL NOW

The next steps will disable the ability to log in to SSH with a password. If you haven’t set up key authentication correctly, you could find yourself locked out of your server if you’re connecting via SSH.

JUST IN CASE

Make sure you have another way to access your machine, like a console (for a virtual machine) or physical access to the keyboard, before you begin the next step.

Finally, the last steps, configuring the SSH server on The Server to reject passwords. With your choice of text editor, edit

/etc/ssh/sshd_config

and look for:

#PasswordAuthentication yes

Delete the hash sign, change yes to no, and save the file. Restart sshd and you’re done.  Your current SSH session will continue, but the next time you try to connect, there will not be a prompt for password.

So what now?

You should now have a working key pair with the public key on The Server and the private key on The Client.  Your SSH server should reject password attempts, with the only way to gain access being the key in the file on your local machine.

To test and see if you’ve configured SSH key authentication correctly, simply connect to The Server using the SSH client of your choice.

In Windows, right click the Pageant icon in your system tray, choose “New Session”, and it should bring up PuTTY.  Start your session and Pageant should do the authenticating/key handshaking.

In Linux/macOS, just do a

ssh user@hostname.example.com

and you should just glide right on in. You’ll get a password prompt if you put a passphrase on your private key.