SSH keys are a convenient and secure way to access Linux servers, but the private key stored on your computer still needs protection.
If your private key has no passphrase, anyone who obtains a copy of it may be able to use it to access every server where the matching public key is authorised. Adding a passphrase protects the private key on disk, while ssh-agent means you do not need to enter that passphrase every time you connect to a server.
In this guide, we'll look at how both work and how to set them up without making SSH inconvenient to use.
An SSH key pair normally consists of two files:
~/.ssh/id_ed25519
~/.ssh/id_ed25519.pub
The .pub file is your public key. This is the part you install on servers or add to services such as ServerAuth.
The file without .pub is your private key. It stays on your computer and must not be shared.
If the private key is not protected by a passphrase, somebody who copies it may be able to use it immediately. A passphrase encrypts the private key so that it must first be unlocked before it can be used.
The passphrase is entirely local. It is not sent to the server and does not need to match your server password.
For a new SSH key, Ed25519 is a good default:
ssh-keygen -t ed25519 -C "you@example.com"
You will first be asked where to save the key:
Enter file in which to save the key (/home/user/.ssh/id_ed25519):
Press Enter to accept the default, or provide another filename if you use separate keys for different purposes.
You will then be asked for a passphrase:
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Enter a strong passphrase rather than leaving it empty.
The resulting private key should normally only be readable by your user:
chmod 600 ~/.ssh/id_ed25519
Your public key can then be installed on the servers you need to access.
You do not need to generate a new key simply because your existing key does not have a passphrase.
Run:
ssh-keygen -p -f ~/.ssh/id_ed25519
If the key currently has no passphrase, press Enter when asked for the old one. You can then enter and confirm a new passphrase.
This does not change your public key.
If the key is already installed on several servers, it will continue to work on all of them. You are only changing how the private key is protected on your computer.
The same command can be used later to change an existing passphrase.
Protecting a private key with a passphrase is useful, but without an SSH agent it can quickly become irritating.
Connect to a server:
ssh deploy@example.com
and SSH asks:
Enter passphrase for key '/home/user/.ssh/id_ed25519':
Connect to another server and you may be asked again.
Use Git over SSH and you may be asked again.
This is the problem ssh-agent solves.
ssh-agent?ssh-agent is part of OpenSSH and runs on your own computer.
It can keep an unlocked SSH key available for your current session, allowing SSH to use it without asking for the passphrase every time.
The process is roughly:
Private key on disk
|
| Enter passphrase
v
ssh-agent
|
v
SSH
|
v
Server
Your private key does not get copied to the server, and the server never receives your passphrase.
You unlock the key locally, then the agent can use it when SSH needs to authenticate.
ssh-agent is already runningBefore starting an agent yourself, check whether your system already provides one:
echo "$SSH_AUTH_SOCK"
You can also run:
ssh-add -l
If an agent is running but does not currently contain any keys, you may see:
The agent has no identities.
If no agent is available, you may see:
Could not open a connection to your authentication agent.
Many desktop environments already start an SSH agent when you log in, so you should check before creating another one.
ssh-agent manuallyIf you do not already have an agent running:
eval "$(ssh-agent -s)"
You should see something similar to:
Agent pid 12345
Now add your private key:
ssh-add ~/.ssh/id_ed25519
Enter your passphrase when prompted.
Once added, check the keys available to the agent:
ssh-add -l
You can now connect normally:
ssh deploy@example.com
and the agent will provide the unlocked key without asking for its passphrase again.
ssh-agentTo remove a particular key:
ssh-add -d ~/.ssh/id_ed25519
To remove every key currently held by the agent:
ssh-add -D
Removing a key from the agent does not delete the key from your computer. It simply means the passphrase will need to be entered again before the key can be used.
You can also load a key for a limited period:
ssh-add -t 4h ~/.ssh/id_ed25519
In this example, the key remains available for four hours before being removed automatically.
This can be useful for keys that provide access to production servers.
OpenSSH can automatically add a key to your running agent when it is first used.
Edit:
~/.ssh/config
and add:
Host *
AddKeysToAgent yes
You can also configure this for individual servers:
Host production
HostName production.example.com
User deploy
IdentityFile ~/.ssh/production_ed25519
AddKeysToAgent yes
You can then connect using:
ssh production
The first time the key is required, SSH can ask for its passphrase and add it to the agent.
macOS includes OpenSSH and integrates SSH keys with the macOS Keychain.
A useful ~/.ssh/config setup is:
Host *
AddKeysToAgent yes
UseKeychain yes
UseKeychain allows macOS to store the SSH key passphrase in Keychain, so you do not need to enter it manually whenever you start a new session.
If you share the same SSH configuration between macOS and other operating systems, you can use:
IgnoreUnknown UseKeychain
Host *
AddKeysToAgent yes
UseKeychain yes
Other OpenSSH implementations can then ignore the macOS-specific option.
It is common to have several SSH keys, particularly if you manage servers for different companies or clients.
For example:
~/.ssh/id_ed25519
~/.ssh/client_acme
~/.ssh/work_servers
Rather than relying on SSH to work out which key to use, configure them explicitly in ~/.ssh/config:
Host acme-production
HostName 203.0.113.20
User deploy
IdentityFile ~/.ssh/client_acme
IdentitiesOnly yes
Host work-server
HostName server.example.com
User deploy
IdentityFile ~/.ssh/work_servers
IdentitiesOnly yes
You can then connect with:
ssh acme-production
IdentitiesOnly yes is particularly useful when your agent contains several keys because it tells SSH to use the configured identity rather than offering every available key to the server.
If you ever need to see which key SSH is trying to use, run:
ssh -v acme-production
The verbose output will show which identities are being offered and which one the server accepts.
Each person who needs server access should have their own SSH key pair.
Avoid creating one key and distributing the private key to the entire team.
With a shared private key, removing one person's access means replacing the credential for everybody. It also becomes difficult to know who has copies of the key or which devices it has ended up on.
Individual keys are much easier to manage:
Rick's laptop -> Rick's SSH key
Alice's laptop -> Alice's SSH key
Sam's desktop -> Sam's SSH key
If Alice leaves the team, only Alice's public key needs to be removed.
The same principle can be taken further by using a separate key for each device. If a laptop is lost, that device's key can be revoked without affecting the user's other computers.
ServerAuth only needs the public part of your SSH key.
Your private key:
~/.ssh/id_ed25519
remains on your computer.
The public key:
~/.ssh/id_ed25519.pub
is the part that you add to ServerAuth.
ServerAuth can then manage which server users your public key is authorised to access
ServerAuth provides a whole host of management tools, from controlling who can access your server, to managing your website deployments. And with an ever-growing suite of tools you'll always be one step ahead!
Start for free
