Are SSH keys protected with a passphrase or a password?

An SSH private key is protected by an optional passphrase, not a password. Learn what it does and how to add, change, remove or remember it.

6–10 minutes
Hands typing on a laptop keyboard

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 passwordKey passphrase
What it protectsYour user account on the serverThe private key file on your computer
Where it is checkedOn the serverOnly on your computer
Sent over the networkYes (inside the encrypted SSH connection)Never
RequiredYes, if password login is allowedNo, it is optional
Who sets itThe server administrator or you, with passwdYou, with ssh-keygen
If you forget itAn administrator can reset itIt 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 sshd can 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.

  1. Open a terminal (PowerShell on Windows).
  2. Run ssh-keygen -p and point it at your private key:
ssh-keygen -p -f ~/.ssh/id_ed25519
  1. If the key already has a passphrase, type the old one when asked.
  2. 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

SymptomCauseFix
Asked for the passphrase on every connectionThe key is not loaded into ssh-agent, or no agent is runningRun ssh-add for the key, and on macOS add UseKeychain yes to ~/.ssh/config
user@host's password: instead of a passphrase promptThe server did not accept your key, so it fell back to password loginCheck 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 keyThe passphrase typed does not matchCheck the keyboard layout and Caps Lock; if it is truly lost, make a new key
Load key: bad permissions or UNPROTECTED PRIVATE KEY FILEThe private key file is readable by other usersOn Linux and macOS run chmod 600 ~/.ssh/id_ed25519
A script hangs waiting for inputThe key it uses has a passphrase and nobody is there to type itUse a separate key without a passphrase, restricted on the server, for that job
Could not open a connection to your authentication agentssh-add was run without an agent in this terminalRun eval "$(ssh-agent -s)" first on Linux, or start the ssh-agent service on Windows

Official documentation

Get the next guide

One email when there is something worth reading: new guides, errors going around, and hosting changes that affect your site.

No tracking pixels, and one click to leave.

Something out of date? Software changes. If a step no longer works, tell us and we will check it and update the page.