Skip to content
BENIBIX Learn

SSH Agent and Passphrases

Level 2 · Keys and shortcuts

Why a private key should have a passphrase. How ssh-agent keeps it open for the day, so you type the passphrase once, not every time.

Course contentsLesson 4 of 9

After this lesson you can

  • Set a passphrase on a private key
  • Load a key into ssh-agent
  • Say what a passphrase protects against

10 mincovers 2 glossary entries

Worth reading first: SSH Keys and ssh-keygen

How to lock your key and still log in fast

An SSH key passphrase is a password that locks the private key file itself. If someone copies the file, it is no use to them without the passphrase. ssh-agent is a small program that holds the open key in memory. You type the passphrase once, with ssh-add. The agent then signs each login for you until you log out.

ssh-keygen asks for a passphrase when it makes the key. Leaving it empty is allowed, and many people do. But then the file alone is enough to log in to every server that trusts it.

A laptop can be stolen, and a backup can leak. A passphrase turns either of those into a much smaller problem. A long phrase of four or five plain words is easy to remember and hard to guess.

Typing that phrase forty times a day would be painful. That is the agent's job. ssh-add asks for the passphrase once and hands the open key to the agent. ssh, scp and rsync all ask the agent to sign for them.

The open key lives only in memory, never on disk. When you log out or restart, it is gone, and the next ssh-add asks again. ssh-add -l lists the keys the agent holds right now.

On most desktops the agent starts for you when you log in. macOS can also keep the passphrase in its keychain, so even the first ssh-add happens by itself.

You can add a passphrase to a key you already have. ssh-keygen -p asks for a new passphrase and locks the file with it. The key itself stays the same, so the servers that trust it do not need to change.

console
$ ssh-add ~/.ssh/id_ed25519
Enter passphrase for /home/lucy/.ssh/id_ed25519:
Identity added: /home/lucy/.ssh/id_ed25519 (lucy@laptop)
$ ssh-add -l
256 SHA256:Xq3v... lucy@laptop (ED25519)
Type the passphrase once. The agent now holds the open key and lists it.
The passphrase locks the file. The agent saves you from typing it again and again.

Worked example

Lucy's laptop is stolen

Lucy's laptop is taken from a cafe. Her private key had a 5-word passphrase, and the laptop was off.

The thief has the key file but cannot use it. That evening, Lucy still deletes its line on her 3 servers. Then she makes a new pair on her new laptop.

The words for this lesson2

Check yourself

What does ssh-agent do?

Finished this lesson?

Marking it complete also marks its 2 glossary entries learned, which updates your roadmap and your saved page. 0 are already marked.