ssh-agent and ssh-add

You probably use ssh on a regular basis. It’s easy and powerful. But once in a while you might be confronted to ssh utility tools like ssh-agent and ssh-add. What are these, and what are they used for?

But first, some background: ssh keys…

SSH keys

When you connect to a remote device (usually a server) with ssh or scp, you can (and often do) authenticate yourself using a password. You can also authenticate using SSH keys. Here is how it works:

First, on your device, your create a pair of keys: a private key and the corresponding public key. You upload the public key to the remote device.

When you need to authenticate on the remote device:

1. the remote device generates a random string and encrypts it using your public key (a challenge) ;

According to the principle of public key cryptography, this challenge can only be decrypted using the corresponding private key.

2. the remote device sends the encrypted string (the challenge) to your computer;
3. your computer uses the private key to decrypt the challenge and recover the original random string;
4. your computer sends the string back to the remote device.

As you are (normally) the only owner of the private key, you are the only one able to correctly decrypt the challenge and recover the original random string. Hence this allows to verify your identity.

Using SSH keys has multiple advantages:

1. SSH keys are randomly generated, so you cannot create a ‘guessable’ key like ‘12345’;
2. SSH keys are long, hence difficult to brute force;
3. the private key is never sent to the remote device, hence it cannot be stolen even if the remote device is compromised or cannot be trusted.

SSH keys have one caveat: they are stored on your computer. So if another user or a malware can read your SSH key, he (it) will be able to authenticate on your remote devices (servers). Hence SSH keys must be protected. One way to do so is to define a passphrase when you create the keys.

This way, each time you use ssh or scp, you will have to provide the passphrase to unlock your private key. This provides a nice layer of security, but can be pretty annoying if you have to type this passphrase too often. This is where ssh-agent comes into play…

ssh-agent and ssh-add

ssh-agent is a small utility that keeps the cleartext version of your private SSH keys in memory. Hence each time you use ssh or scp, they actually forward the challenge to the ssh-agent running in the background. This means you only have to provide the passphrase once, when the key is loaded.

On most Linux systems, ssh-agent is automatically started when you login, and stopped when you terminate (logout from) the local session.

If you must manually start ssh-agent: the ssh-agent command outputs environment variable settings that must be used later by ssh and scp. Hence ssh-agent is usually started with something like:

eval `ssh-agent`

By default, ssh-agent automatically loads SSH keys stored in the .ssh directory under the user’s home directory. You can also load additional keys with

ssh-add path/to/key

You can also load a key stored in an environment variable. This is a pattern that you can see in a Continuous Delivery (CD) pipeline for example:

ssh-add <(echo "$SSH_PRIVATE_KEY")

This blog post is licensed under CC BY-SA 4.0