SSHSSH A secure way to type commands on a server from your own computer, as if you were sitting at it. More about SSH → keys are a pair of matching files that let you log in to a server without a password, by proving you hold a secret that never leaves your computer. This guide is for anyone who has been told to “add your SSH key” and wants to understand what that actually means before doing it.
An SSH key is a pair of files: a private key that stays on your computer and a public key that you put on the server. When you connect, your computer uses the private key to sign a piece of data unique to that connection, and the server checks the signature with the public key it already has. No password crosses the network, and nothing useful can be guessed or reused. You create the pair with ssh-keygen and copy only the .pub file to servers.
What an SSH key pair is
SSH (Secure Shell) is the encrypted connection you use to run commands on a remote server. It can check who you are in two common ways: a password, or a key pair.
A key pair is made with public key cryptography. Two keys are generated together and are mathematically linked:
- The private key is the secret half. It lives on your own computer, usually at
~/.ssh/id_ed25519, and should never be emailed, uploaded or pasted anywhere. - The public key is the shareable half, at
~/.ssh/id_ed25519.pub. You can give it to as many servers and services as you like. Anyone who has it can check your signatures, but nobody can work out the private key from it.
A useful picture is a padlock and its key. You hand out copies of the open padlock (the public key) to every server. Only you hold the key that fits it (the private key).
A public key is a single line of text that looks like this:
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleOnlyNotARealKey0000000000000000 exampleco-laptop
It has three parts: the key type (ssh-ed25519), the key itself, and a comment at the end that is only there to help you tell keys apart.
How SSH keys work when you log in
Here is what happens, in order, when you run ssh exampleco@203.0.113.10 with a key:
- Your computer and the server set up an encrypted connection first. During this step the server proves its own identity with its host key, which is why you see a fingerprint prompt the first time you connect.
- Your computer tells the server which public key it would like to use.
- The server looks for that public key in the user’s
~/.ssh/authorized_keysfile. If it is not there, the server refuses it and may fall back to asking for a password. - If it is listed, your computer uses the private key to sign data that is unique to this connection and sends the signature.
- The server checks the signature with the public key. Only the matching private key could have produced it, so you are let in.
Because the signed data is different every session, a recorded login cannot be replayed later. And because your private key is never sent, a fake or compromised server cannot steal it the way it could steal a typed password.
There are two kinds of key in every SSH connection. Host keys identify the server to you and are remembered in your ~/.ssh/known_hosts file. User keys identify you to the server and are listed in its ~/.ssh/authorized_keys file. This guide is about user keys.
Where SSH keys live
| File | Where | What it does |
|---|---|---|
~/.ssh/id_ed25519 | Your computer | Your private key. Keep it secret. |
~/.ssh/id_ed25519.pub | Your computer | Your public key. Safe to share. |
~/.ssh/authorized_keys | The server, in the user’s home folder | The list of public keys allowed to log in as that user, one per line. |
~/.ssh/known_hosts | Your computer | Fingerprints of servers you have already trusted. |
/etc/ssh/ssh_host_*_key | The server | The server’s own host keys. |
On Windows, ~ means your user folder, so the files are in C:\Users\exampleco\.ssh\. The same OpenSSH tools are built into Windows 10 and 11.
SSH is strict about permissions. On the server, the ~/.ssh folder should be 700 (only the owner can enter it) and authorized_keys should be 600 (only the owner can read or write it). If they are more open than that, the server ignores the keys and asks for a password instead.
Key types: which one to use
When you run ssh-keygen, the -t option chooses the type of key.
| Type | Command | When to use it |
|---|---|---|
| Ed25519 | ssh-keygen -t ed25519 | The default choice today. Short, fast and secure. |
| RSA | ssh-keygen -t rsa -b 4096 | Only for older systems that do not accept Ed25519. |
| ECDSA | ssh-keygen -t ecdsa | Works, but has no advantage over Ed25519 for most people. |
| Ed25519-SK | ssh-keygen -t ed25519-sk | Stores the secret on a hardware security key, which you touch to log in. |
| DSA | none | Obsolete. Current OpenSSH no longer supports it. |
If you are not sure, use Ed25519. The step-by-step process of creating one and copying it to a server is in How to set up SSH keys.
Passphrases and ssh-agent
A passphrase encrypts the private key file on your disk. Without one, anyone who copies the file (from a stolen laptop or a careless backup) can log in to every server that trusts it. With one, the file is useless to them on its own.
Typing a passphrase on every connection would be tiresome, so SSH includes ssh-agent, a small background program that holds your unlocked key in memory for the session. You unlock it once:
ssh-add ~/.ssh/id_ed25519
On macOS you can store the passphrase in the system keychain with ssh-add --apple-use-keychain ~/.ssh/id_ed25519. On Windows, the OpenSSH Authentication Agent service does the same job, and Git Bash users can start an agent from its shell.
You can add or change a passphrase on an existing key at any time:
ssh-keygen -p -f ~/.ssh/id_ed25519
Checking which key is which
A fingerprint is a short summary of a key that is easy to compare by eye. To see yours:
ssh-keygen -l -f ~/.ssh/id_ed25519.pub
The output looks like 256 SHA256:Xb3... exampleco-laptop (ED25519). Services that store your key, such as a Git host or your cloud provider’s control panelControl panel A website you log into to manage your hosting with buttons and forms, instead of typing commands. cPanel and Plesk are the common ones. More about Control panel →, usually show the same SHA256: fingerprint, so you can confirm they hold the right key.
If you have lost the .pub file but still have the private key, you can rebuild the public half:
ssh-keygen -y -f ~/.ssh/id_ed25519
Common problems
| Symptom | Cause | Fix |
|---|---|---|
| Server still asks for a password | Public key not in authorized_keys, or permissions too open | Check the file contains your .pub line and run chmod 700 ~/.ssh and chmod 600 ~/.ssh/authorized_keys on the server. |
Permission denied (publickey) | Password login is off and the server does not recognise your key | Make sure you are using the right user name and key. Run ssh -v to see which keys are offered. |
UNPROTECTED PRIVATE KEY FILE! | Your private key can be read by other users on your computer | Run chmod 600 ~/.ssh/id_ed25519. |
| Key rejected by an old server | The server does not understand Ed25519 | Create an RSA key with ssh-keygen -t rsa -b 4096 for that server. |
Good habits with SSH keys
- Use one key per computer, so you can revoke a lost laptop without affecting the others.
- Always set a passphrase, and let ssh-agent remember it.
- Never share or upload the private key. Only the
.pubfile goes anywhere. - Put a clear comment on each key (
-C "exampleco-laptop") so you know whose line is whose inauthorized_keys. - When a device is lost or someone leaves, delete their line from
authorized_keyson every server.
Official documentation
- ssh-keygen manual (OpenBSD)
- sshd manual, including the authorized_keys format (OpenBSD)
- RFC 4252: The SSH Authentication Protocol
Related
- How to set up SSH keys: create a key, copy it to a server and switch password login off.
- How to connect to a server with SSH: your first connection and what the host key prompt means.
- Git Bash for Windows: use ssh, ssh-keygen and ssh-agent on a Windows PC.
- How HTTPS works: the same public key idea, used to secure websites.
Something out of date? Software changes. If a step no longer works, tell us and we will check it and update the page.



