An SSHSSH A secure way to type commands on a server from your own computer, as if you were sitting at it. More about SSH → private key is protected with a passphrase, not a password, and the passphrase is optional. This guide is for anyone who has seen “Enter passphrase for key” and wondered what it is, whether they need one, and how to add, change or remove it.
SSH keys are protected with a passphrase: a secret you choose when you run ssh-keygen, used to encrypt the private key file on your own computer. It never goes to the server, and it is different from your server account’s password. You can add, change or remove it at any time with **ssh-keygen -p -f ~/.ssh/id_ed25519, and use ssh-agent** so you only type it once per session.
If you are new to key pairs, start with what SSH keys are and how they work. The short version: the private key stays on your computer, the public key goes on the server.
Passphrase and password: two different secrets
The words sound alike, but they protect different things in different places.
| Account password | Key passphrase | |
|---|---|---|
| What it protects | Your user account on the server | The private key file on your computer |
| Where it is checked | On the server | Only on your computer |
| Sent over the network | Yes (inside the encrypted SSH connection) | Never |
| Required | Yes, if password login is allowed | No, it is optional |
| Who sets it | The server administrator or you, with passwd | You, with ssh-keygen |
| If you forget it | An administrator can reset it | It cannot be recovered |
The prompt you see tells you which one SSH wants:
Enter passphrase for key '/home/exampleco/.ssh/id_ed25519':means SSH found your key and needs the passphrase to unlock it locally.exampleco@203.0.113.10's password:means key login did not work (or you have no key) and the server is asking for your account password instead.
Getting the second prompt when you expected to use a key is a sign that the server did not accept your key. The table under Common problems below covers the usual reasons.
What the passphrase actually does
When you set a passphrase, ssh-keygen turns it into an encryption key using a deliberately slow function (bcrypt, in the current OpenSSH key format) and uses that to encrypt the private key before saving it. The file on disk is then useless without the passphrase.
That matters in one situation: someone gets a copy of your private key file. A stolen laptop, a backup drive left in a drawer, a synced folder that was shared by mistake. Without a passphrase, whoever has the file can log in to every server that trusts the key. With a good passphrase, they hold an encrypted blob that they must try to crack, one slow guess at a time.
What a passphrase does not do:
- It does not make the login itself any stronger. The server only checks a signature made with the private key, and it has no way to know whether the key had a passphrase.
- It cannot be enforced by the server. If an organisation requires passphrases, that is a policy, not something
sshdcan check. - It does not help once the key is unlocked in a running ssh-agent on a computer an attacker controls.
Because the slow function only slows down guessing, a short passphrase such as a single word gives little protection. A few random words, such as copper lantern fifteen orbit, is long enough and still easy to type.
Should you use one?
For a key on a laptop or desktop that you log in from by hand, yes. With ssh-agent you will type it once after you log in to your computer, not every time you connect.
An empty passphrase is a reasonable choice for a key used by an unattended job, such as a backup script or a deployment tool that has no one to type it. In that case, limit what the key can do instead: give it its own account on the server, and restrict it in authorized_keys (the from= and command= options) so a stolen copy is worth less.
How to check whether a key has a passphrase
Ask ssh-keygen to print the public half from the private key:
ssh-keygen -y -f ~/.ssh/id_ed25519
- If it asks
Enter passphrase:, the key is encrypted. - If it prints a line starting
ssh-ed25519 AAAA...straight away, the key has no passphrase.
On Windows, run the same command in PowerShell with the Windows path:
ssh-keygen -y -f $env:USERPROFILE\.ssh\id_ed25519
You can also tell from older RSA keys in the PEM format: an encrypted one has a Proc-Type: 4,ENCRYPTED line near the top. Keys in the current OpenSSH format (the first line is -----BEGIN OPENSSH PRIVATE KEY-----) do not show this, so use the command above. If you are not sure where your key files are, see where SSH keys are stored.
How to add, change or remove a passphrase
You do not need to make a new key to change its passphrase. The key pair stays the same, so nothing has to change on your servers.
- Open a terminal (PowerShell on Windows).
- Run
ssh-keygen -pand point it at your private key:
ssh-keygen -p -f ~/.ssh/id_ed25519
- If the key already has a passphrase, type the old one when asked.
- Type the new passphrase twice. To remove the passphrase, press Enter twice without typing anything.
Success looks like this:
Your identification has been saved with the new passphrase.
To add a passphrase to a key that has none, use exactly the same command: you will not be asked for an old one.
Make a copy of the private key before changing it, for example cp ~/.ssh/id_ed25519 ~/.ssh/id_ed25519.bak, and delete the copy once you have tested a login. If you forget the passphrase, there is no reset: you will have to create a new key pair and put the new public key on every server.
If you lost the passphrase for good, follow how to set up SSH keys to make a new pair, add the new public key to your servers, then remove the old one as described in how to delete SSH keys.
Type the passphrase once with ssh-agent
ssh-agent is a small background program that holds your unlocked key in memory, so SSH can use it without asking again. You add the key once, type the passphrase once, and every connection after that is silent until you log out or restart.
Linux
Most desktop Linux sessions start an agent for you. If ssh-add -l says it cannot connect to an agent, start one in the current terminal:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
To have the key unlocked only for a while, give a lifetime, for example one hour:
ssh-add -t 1h ~/.ssh/id_ed25519
macOS
macOS can keep the passphrase in your Keychain so it is unlocked when you log in to your Mac. Add the key once:
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
Then add these lines to ~/.ssh/config so SSH loads it automatically:
Host *
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_ed25519
Windows
The OpenSSH agent on Windows is a service that is switched off by default. In PowerShell run as Administrator:
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
Then, in a normal PowerShell window:
ssh-add $env:USERPROFILE\.ssh\id_ed25519
The Windows agent keeps the key across restarts, so you are asked for the passphrase once. The full Windows setup is in how to create an SSH key on Windows.
To see which keys the agent is holding on any system, run ssh-add -l. To forget them all, run ssh-add -D.
Common problems
| Symptom | Cause | Fix |
|---|---|---|
| Asked for the passphrase on every connection | The key is not loaded into ssh-agent, or no agent is running | Run ssh-add for the key, and on macOS add UseKeychain yes to ~/.ssh/config |
user@host's password: instead of a passphrase prompt | The server did not accept your key, so it fell back to password login | Check the public key is in ~/.ssh/authorized_keys on the server and run ssh -v to see which keys were offered |
incorrect passphrase supplied to decrypt private key | The passphrase typed does not match | Check the keyboard layout and Caps Lock; if it is truly lost, make a new key |
Load key: bad permissions or UNPROTECTED PRIVATE KEY FILE | The private key file is readable by other users | On Linux and macOS run chmod 600 ~/.ssh/id_ed25519 |
| A script hangs waiting for input | The key it uses has a passphrase and nobody is there to type it | Use a separate key without a passphrase, restricted on the server, for that job |
Could not open a connection to your authentication agent | ssh-add was run without an agent in this terminal | Run eval "$(ssh-agent -s)" first on Linux, or start the ssh-agent service on Windows |
Official documentation
Related
- What are SSH keys? explains the key pair and how a login is checked.
- How to set up SSH keys walks through making a key and turning off password login.
- Where are SSH keys stored? shows where to find the private key file you are protecting.
- How to delete SSH keys covers replacing a key whose passphrase you have lost.
Something out of date? Software changes. If a step no longer works, tell us and we will check it and update the page.



