Preliminaries

Perhaps you’re tired of trying to remember long passwords every time you log in and out of the many Stacks you’ve anchored here at Stack Harbor. In this tutorial we’ll help you set up SSH key authentication to connect to your Stacks securely from your local machine without having to look up your root password every time you want to connect to one of your servers.

Brief Overview of SSH

Secure Shell, known by many as SSH, is a protocol to initiate text-based shell sessions on a remote host securely over a network. In other words, we can use SSH to execute terminal commands on our remote server without having to have physical access to the server itself.

There are three main ways to connect to a remote host using SSH, each offering a different level of security. If you’ve followed our “Getting Started with Your Stack” tutorial, you’ve been exposed to the most basic level of SSH authentication which uses passwords. In this tutorial, we’ll show you how to access your server more securely using public and private keys.

What are public and private keys?

SSH uses public-key cryptography to authenticate users and allow them to execute shell commands remotely. SSH key pairs consist of a public key and a private key which are used to encrypt and decrypt messages sent between two agents (let’s call them ‘client’ and ‘server’). The client is free to give out their public key to as many people as they wish to communicate with, but it is imperative that they keep their private key secure.

When a client attempts to connect to a server using SSH, they initiate a connection. The server checks a file local to the server named ‘authorized_keys’ for a public key associated to the IP address of the client. If the client’s public key exists on the server, it creates a challenge message and encrypts it using the public key. The crux of this process is that the message encrypted by the public key can only be decrypted by the correct private key. The server then sends this message back and waits for a response. The client proceeds by decrypting the message (if it can) and alerting the server that it correctly decrypted the message. How this occurs depends on the protocol of SSH used, but the essential idea is that if the server can verify that the client has successfully decrypted the message, an SSH connection is created and command is passed on to the user.

Generating Your Key Pair

Let’s begin by generating an SSH key pair on our local machine. If you see the shell prompt 'root@tutorial-ubuntu:~#' then you should be running the commands on your local machine, or the machine with which you want to access your server over SSH.

Run the ssh-keygen command.

root@tutorial-ubuntu:~# ssh-keygen 
Generating public/private rsa key pair. 
Enter file in which to save the key (/root/.ssh/id_rsa): 
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /root/.ssh/id_rsa. 
Your public key has been saved in /root/.ssh/id_rsa.pub. 
The key fingerprint is: 
25:12:d3:fe:1d:7f:61:ad:e4:f1:46:82:d2:cc:2c:72 root@tutorial-ubuntu 
The key's randomart image is: 
+--[ RSA 2048]----+ 
|      o.         | 
|       o.        | 
|      ... .= .  .| 
|       .ooE B +oo| 
|        S+ + =.*.| 
|          . . + +| 
|               o | 
|                 | 
|                 | 
+-----------------+ 

You’ll be prompted to enter the location where you wish to store your SSH keys. By default this is in your home directory under a hidden folder named ‘.ssh’. Unless you have a specific plan in mind for SSH key organization, the default location is recommended.

If you had previously used ssh-keygen, you might be prompted with this error.

/home/username/.ssh/id_rsa already exists. 
Overwrite (y/n)?

If you choose yes, then you will not be able to authenticate to any system with which you used the old key to authenticate.

After this, you’ll be prompted to enter a passphrase. This is an extra measure of security to further secure your private key. If you choose to enter a passphrase now, whenever you connect to a server using your private key, you’ll also be asked to enter the password associated with that private key. The motivation for this is the fact that your private key is stored in plaintext on your local machine. Without a passphrase, anyone that gains access to your computer or private key can connect to any machine you’ve connected to without any authentication. A passphrase only allows you to use your private key after providing the system with a passphrase.

Once you’ve provided ssh-keygen with a passphrase (or nothing), you’ll be able to find your public and private key in the folder you specified earlier, or in our example, /root/.ssh/. If you execute the command ls /root/.ssh/ you should see three files shown below.

root@user-unbuntu:~# ls /root/.ssh/
authorized_keys id_rsa id_rsa.pub

id_rsa contains your private key, id_rsa.pub your public key, and authorized_keys contains the public keys of other computers you might wish to allow access to your local machine over SSH. We will explain this further later. For now, we want to be able to share our public key with the machines we want to connect to.

cat ~/.ssh/id_rsa.pub

Your shell should output a long key beginning with “ssh-rsa” and ending with your user followed by the hostname of your local machine. This is your public key. Copy this to the clipboard and we’ll proceed to add this public key to our servers.

Now that you have your public key copied to your clipboard, you are free to share it with any host that you want to authenticate with using SSH. Specifically, you can now use it to securely log into your remote servers. If you want to add your SSH key from our Cloud Management Platform, view your Stack’s details and click on the ‘access’ tab. You will see an option to set SSH keys. Enter the public key you copied to your clipboard here and proceed. Your machine will be rebooted, after which you will be able to login using SSH keys.

If you choose to set your SSH keys manually on every server you wish to connect to, you’ll first have to gain access to the server. You can do this using basic SSH to access your remote server’s shell. Once you’ve logged in (see “Getting Started with Your Stack“) execute the following command:

ls ~/.ssh/

If you’re faced with the message “No such file or directory” then simply execute mkdir ~/.ssh and proceed. Otherwise when you execute “ls” in the .ssh directory, it will be empty or contain the same three files authorized_keys, id_rsa, and id_rsa.pub. We want to add the public key of our local machine to the list of keys that are allowed to access our remote host, which are stored in .ssh/authorized_keys. If your public key from the earlier steps is not still on your clipboard, you should copy it now and proceed.

Run the commandecho "PUBLIC_KEY" >> ~/.ssh/authorized_keys , appropriately replacing PUBLIC_KEY with the public key that you copied to your clipboard. This will append your public key to the authorized_keys file and allow you to connect to your remote server from your local machine using the public/private key pair you provided.

Final Words

Congratulations! You’re all set to securely login to your Stack using public-key authentication. You can be confident that unless someone is looking over your shoulder, the communication between your local machine and your remote Stack is secure. For more information on server administration and other related tasks, check out our Community Section. From all of us at Stack Harbor, ahoy!