Setting up an SSH key

Introduction

In this tutorial you will learn how to work with an SSH key. This will include generating an SSH key pair, copying the public key to a remote device and deleting an SSH key pair.

SSH key explained

Secure Shell (SSH) is a network protocol that is used for encrypted communication between two devices. To establish an SSH connection, you can either use a password or an SSH key for authentication. A single SSH key pair has two components, a private key and a public key. Each key consists of a long string of characters.

• The public key uses a specific algorithm to encrypt messages.
• The private key uses a specific algorithm to decrypt messages.

Only a private key can decrypt messages that have been encrypted with a public key and both keys have to be part of the same key pair. The public key is saved on all remote devices you want to connect to via the key. This means that anyone in possession of your private key can also decrypt all messages from that device. For this reason, the private key should always be kept secret and never be shared. One of the advantages of this authentication method is that it is more secure than passwords.

SSH keys allow to automatically authenticate connections. There are mainly 4 steps:

1. The public key of the client has to be on the server.
2. The server uses the public key to encrypt a random message that is then sent to the client.
3. The client uses the private key to decrypt the message.
4. If the message has been decrypted correctly, the connection is authenticated.

Prerequisites

• Basic knowledge about the Hetzner Cloud
• CLI tool

Example terminology

• Username: holu
• IPv4: <10.0.0.1>

Please replace holu with your username and <10.0.0.1> with your own IP address in all example commands.

Step 1 - Generating an SSH key

To create an SSH key on your local device, please open your CLI. Generally, it is enough to run ssh-keygen without any other specifications. This will create an RSA key by default.

ssh-keygen

It is also possible to provide additional information about key type and key size.

Options:

• -t specifies the key type
• -b specifies the key size

Type:

• rsa
• ed25519
• dsa
• ecdsa

Depending on the type, different algorithms are used. DSA and ECDSA both include a parameter (k) that can be problematic in terms of security. If the same parameter is used twice, attackers can use this information to recover the private key. Mathematically, Ed25519 is probably one of the strongest keys. If your device does not support this key, you can also generate an RSA key.

1. Ed25519 key

   Ed25519 is considered to be very secure. It is supported by OpenSSH 6.5 (2014) and all versions that followed. If your device does support this key, we recommend using it. The key size is fixed and cannot be changed.

   $ ssh-keygen -t ed25519

2. RSA key

   Compared to other keys, RSA can be considered to be relatively old. It is not quite as secure as an Ed25519 key. RSA has a default key size of 3072 bits and should never be under 1024 bits. To increase security, you can set the key size to be 4096 bits.

   $ ssh-keygen -t rsa -b 4096

3. ECDSA key

   ECDSA is supported by OpenSSH 5.7 (2011) and all versions that followed. You can set the key size to be 256, 384 or 521 bits. The default setting is 256 bits.

4. DSA key

   DSA is considered to be relatively insecure. Support ended with OpenSSH 7.0 (2017). The key size is fixed as 1024 bits and cannot be changed.

Once you run the command to generate an SSH key, you should get an output that looks like this:

Generating public/private <type> key pair.
Enter file in which to save the key (/<your_home>/.ssh/id_<type>):

The default location to save the key is /<your_home>/.ssh/id_<type>. You can press ENTER to confirm the default setting or specify another location. If possible, you should keep the default. This way, the SSH client will be able to find the key automatically when authenticating. If you already have an SSH key of the same type, you might get something like this:

/home/your_home/.ssh/id_<type> already exists.
Overwrite (y/n)?

If you enter y, the existing SSH key will be overwritten and you will no longer be able to use it.

Once the location is set, you should be asked to set a passphrase.

Enter passphrase (empty for no passphrase):
Enter same passphrase again:

A passphrase increases security even further. If you set a passphrase, you will be asked to enter it every time you use your key. If you press ENTER without entering a passphrase, your SSH key will not have a passphrase. Output:

Your identification has been saved in /<your_home>/.ssh/id_<type>
Your public key has been saved in /<your_home>/.ssh/id_<type>.pub

The SSH key has now been generated and has been saved in the location you set earlier.

Step 2 - Opening the SSH key

When you generate an SSH key, an SSH directory with several files is created too. Important files include:

• id_<type>
• id_<type>.pub
• authorized_keys

The id_<type> file is for the private key. This file should never be shared with anyone else.

The id_<type>.pub file is for the public key. This is the part you have to share with remote devices you want to connect to via an SSH key. On those remote devices, the public key will be saved in the authorized_keys file.

The authorized_keys file is for public keys of all devices that are allowed to connect to the device via an SSH key. The format of this file is one key per line. It is not possible to connect to a remote device via an SSH key, unless the public key is in this file.

Use the following command to open the SSH directory:

cd ~/.ssh

You can use ls to list all files within the directory. You can open the files with cat followed by the filename. You can use the following command to open your public key:

cat id_<type>.pub

Please replace <type> with the actual name of your file.

Step 3 - Connecting to the server

Three important SSH key files have already been explained in step 2. But there is one other file that should also be mentioned.

• known_hosts

This file is needed when you connect to another device. Every remote device has a unique fingerprint that is saved in this file. If you connect to your server for the first time, you should be aware of a few things. Connect via SSH:

$ ssh holu@<10.0.0.1>

Please replace holu with your own username and <10.0.0.1> with your own IP address.

The first time you connect to your server, there will be a warning about host authenticity. You can enter yes. The fingerprint shown in the warning will be saved locally in the known_hosts file and it will automatically be recognized in the future when you try to connect to this IP address. You can think of this fingerprint as a unique identifier of the server. Usually, this fingerprint should never change. However, if you delete your cloud server, for example, this fingerprint will no longer be valid. The fingerprint does not get removed from the known_hosts file automatically. If you try to connect to this IP address after the fingerprint has changed, the remote device will send the new fingerprint to your system but it will no longer match the one in your known_hosts file. Your system will identify the old fingerprint in your known_hosts file as invalid and you will see a warning like this:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that a host key has just been changed.
The fingerprint for the ECDSA key sent by the remote host is
SHA256:XEBOdibbPpSSWWZZ+0VO6ayoCjFghKys0FfVE6EDWZz.
Please contact your system administrator.
Add correct host key in /home/user/.ssh/known_hosts to get rid of this message.
Offending ECDSA key in /home/user/.ssh/known_hosts:7
  remove with:
  ssh-keygen -f "/home/user/.ssh/known_hosts" -R "<10.0.0.1>"
ECDSA host key for <10.0.0.1> has changed and you have requested strict checking.
Host key verification failed.

If there is no warning, you can continue with step 4.

If you do get a warning but you have not made any drastic changes on your remote system, you should take this warning seriously and find out more about the reason for this warning.

If you do get a warning and you know the reason for it (e.g. deleted the cloud server), you can remove the old fingerprint from the known_hosts file. There are two ways to do that:

• One way to remove the old fingerprint from the known_hosts file is to use the command given in the warning:

  ssh-keygen -f "/home/user/.ssh/known_hosts" -R "<10.0.0.1>"

  Output:

  # Host <10.0.0.1> found: line 7
  /home/user/.ssh/known_hosts updated.
  Original contents retained as /home/user/.ssh/known_hosts.old
  user@<hostname>:/mnt/c/Users/user$

  This method does not only remove the fingerprint from the file but also saves this fingerprint in known_hosts.old in case you need it again.

  If you do not need a copy of the original known_hosts file, you can delete the known_hosts.old file and all its contents with rm -v known_hosts.old or you can use the second way to remove the fingerprint from the known_hosts file manually. Once the invalid fingerprint has been removed from the file, you can user ssh holu@<10.0.0.1> to connect to your server again. This time, there should only be a warning about host authenticity. You can enter yes to save the new fingerprint in the known_hosts file.

• Another way to remove the fingerprint from the known_hosts file is doing it manually. If you have more than one fingerprint in your file, you can refer to the warning. The line Offending ECDSA key in /home/user/.ssh/known_hosts:7 states in which line the fingerprint is saved. In this example it is line 7. Alternatively, you can also use to following command to display the whole fingerprint:

  ssh-keygen -H -F <10.0.0.1>

  Please replace <10.0.0.1> with your own IP address.

  In the output, you can see the full fingerprint to the IP address. It also shows its line in the known_hosts file. You can now use nano to open and edit the known_hosts file.

  $ nano ~/.ssh/known_hosts

  Next, you can remove the old fingerprint to the IP address. Once you are done, you can use CTRL+X to save the file, Y to confirm and ENTER to close the file.

  Now that the invalid fingerprint has been removed, you can enter ssh holu@<10.0.0.1> to try to connect to your server. This time, there should only be a warning about host authenticity. You can enter yes to save the new fingerprint in the known_hosts file.

Step 4 - Adding an SSH key to a server

Once you know how to generate an SSH key and how to connect to the remote device, you can add the public key to your remote device. Please note that you will have to authenticate. This means that you will have to know your password or, if you are using another SSH key, that the corresponding public key must have already been added to the user.

There are several ways to add an SSH key to a remote device. Probably the easiest way to do this is using the ssh-copy-id command. If you cannot use this command, you can use one of the following options instead.

With options 1 and 2 the public key is automatically copied from your local device (client) and automatically pasted to the authorized_keys file on your remote device (server).

With option 3 the public key is manually copied from your local device (client) and manually pasted to the authorized_keys file on your remote device (server).

With option 4 the whole SSH directory of one user (user 1) on your remote device (server) is copied to another user (user 2) on your remote device (server). For this option, you must have already added your public key to user 1, for example with one of the other three options.

It is enough to choose one of the four options above and to skip the other ones.

Option 1

This option is probably the easiest of them all. If you only have one single SSH key, you can simply run the command below. Please note that you will be asked to enter the password of the user you are trying to connect to.

$ ssh-copy-id holu@<10.0.0.1>

Please replace holu with your own username and <10.0.0.1> with your own IP address. The public key will automatically be copied from your local device and automatically be added to the authorized_keys file on the remote device (IP address).

If you have more than one SSH key on your local device, you should also add the file name of the key you would like to add to the remote user.

$ ssh-copy-id -i ~/.ssh/id_<type>.pub holu@<10.0.0.1>

Please replace holu with your own username and <10.0.0.1> with your own IP address. Also, <type> needs to be replaced with the actual type of your SSH key in order to match the file name the local machine is supposed to copy the public SSH key from. In case you are not sure about the correct name of the file, you can use ls ~/.ssh to list all files that are saved in the SSH directory. One of those files should be named like this id_<type>.pub. After you run the ssh-copy-id command, the public key will automatically be copied from your local device and automatically be pasted to the authorized_keys file on your remote device.

The SSH key has now been saved and will be used automatically the next time you connect to your server.

Option 2

If you cannot use ssh-copy-id, you can also use the command below as an alternative. Please note that you will be asked to enter the password of the user you are trying to connect to.

$ cat ~/.ssh/id_<type>.pub | ssh holu@<10.0.0.1> "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

Please replace holu with your own username and <10.0.0.1> with your own IP address. Also, <type> needs to be replaced with the actual type of your SSH key in order to match the file name the local machine is supposed to copy the public SSH key from. In case you are not sure about the correct name of the file, you can use ls ~/.ssh to list all files that are saved in the SSH directory. One of those files should be named like this id_<type>.pub. The >> part in the command above ensures that the original file will not be overwritten. Instead, the new key will be added in the next free line. After you run the command, the public key will automatically be copied from your local device and automatically be pasted to the authorized_keys file on your remote device.

The SSH key has now been saved and will be used automatically the next time you connect to your server.

Option 3

In order to add an SSH key on a remote device, you need to copy the public key from the local device first. To do so, open the file the public key is saved in. If you are not sure about the file name, you can use ls ~/.ssh to list all files that are within the SSH directory. Use cat followed by the filename to open the file:

$ cat ~/.ssh/id_<type>.pub

Copy the whole output, starting with the key type ssh-<type>.

$ ssh-<type> AAA...fjdkl== holu@example

Next, connect to the remote device to add the key. Open a second CLI window and use the command below.

$ ssh holu@<10.0.0.1>

Now that you are connected, check if there is an SSH directory.

$ ls -l ~/.ssh/

If there is an SSH directory, it will list all its contents. If this user does not have an SSH directory, your output should be something like ls: cannot access '/home/new/.ssh/': No such file or directory. In this case, you will have to add an SSH directory.

• Creating an SSH directory

  $ mkdir -p ~/.ssh

  Now change the permissions:

  $ chmod 700 ~/.ssh

  Next you can create the authorized_keys file within this directory. Use cd ~/.ssh to open the SSH directory and run the following command:

  $ touch authorized_keys

  Now change the permissions:

  $ chmod 600 ~/.ssh/authorized_keys

Once you have an authorized_keys file, you can add the public key. Use nano to open the authorized_keys file:

$ nano ~/.ssh/authorized_keys

Next, add the public key from your local device. You can go back to your first CLI window to copy it (cat ~/.ssh/id_<type>.pub). The format of the authorized_keys file is one key per line. This means that you have to remove any paragraphs from your public key until it is a one-liner. You can add more public keys in the lines below - again, one key per line. Once you are done, you can use CTRL+X to save the file, Y to confirm and ENTER to close the file.

The SSH key has now been saved and will be used automatically the next time you connect to your server.

Option 4

The approaches shown above simply add a new SSH key to the authorized_keys file of the remote user. If you have been using another user (u1) for a while now and there is already a lot of data in the .ssh directory that you would like to keep, you can also copy the whole .ssh directory from your other user (u1) to your new user (u2). Open an CLI and connect to your remote device as the old user (u1).

$ ssh user@<10.0.0.1>

Please replace user with your own username (u1) and <10.0.0.1> with your own IP address. Next, use the following command to add the SSH directory to your new user (u2):

# rsync --archive --chown=holu:holu ~/.ssh /home/holu

Please replace holu with your own username (u2). This command automatically modifies the file owner. Please ensure that ~/.ssh does not end with a trailing slash ~/.ssh/ or otherwise this command will not work properly.

Step 5 - Testing the SSH key

Now that the public SSH key has been added to the user's authorized_keys file, you can test authenticating with it. Use CTRL+D on your second CLI window to close the connection to your remote device. Then reconnect to it:

$ ssh holu@<10.0.0.1>

Please replace holu with your own username and <10.0.0.1> with your own IP address. If this is the first time you connect to your server, please be aware of the remarks in step 3.

If your SSH key has a passphrase, you will be asked to enter it now. You should now be connected to your server.

Step 6 - Adding, changing or deleting the SSH key passphrase

You can add, change and delete the passphrase to your private SSH key on your local device. Please note that you have to know your current passphrase. You will no longer be able to use your SSH key if you forgot your passphrase. If you did forget your passphrase, you might want to consider deleting your SSH key as described in the next step and creating a new one with ssh-keygen. If you remember your passphrase, you can use the following command to make changes to it:

$ ssh-keygen -p

Output:

Enter file in which the key is (/root/.ssh/id_rsa):

Enter the file path of your SSH key. If you saved your key in the default location, you can copy the path in the output /root/.ssh/id_<type> and replace rsa with your key type.

If your SSH key already has a passphrase, you will be asked to enter it now. Next, enter a new passphrase and repeat it to confirm. If you want to remove the passphrase, you can simply skip this step by pressing ENTER.

Step 7 - Deleting the SSH key

If you stop using a certain SSH key, you might want to consider to not only delete the corresponding files on your local device but also the public keys from the authorized_keys files on remote devices.

• You can do this manually. Connect to the user that has your public key in the authorized_keys file. Then, open the file:

  $ nano ~/.ssh/authorized_keys

  Remove your public key but do not delete any other keys. After you save the file, you will no longer be able to connect to the server via this SSH key. So please make sure that your new key or password authentication is working. Once you are done, you can use CTRL+X to save the file, Y to confirm and ENTER to close the file.

Use rm to remove the files to your key pair from your local device:

rm id_<type>
rm id_<type>.pub

Conclusion

In the previous steps you learned how to generate an SSH key, add an SSH key to a server, add, change or delete the SSH key passphrase, and delete the SSH key.

License: MIT