Set up SSH key authentication

An SSH key is a pair of files: a private key that stays on your computer and a public key that goes on the server. Logging in with a key is faster than typing a password, and far harder for attackers to guess.

Before you begin

• A working SSH login to your server with your sudo user, as described in the sudo user guide.
• An SSH client on your computer. macOS, Linux and recent Windows versions include ssh-keygen, which this guide uses.
• About ten minutes, and a plan to choose a passphrase you will remember.

Step 1: Check for an existing key

If you already have an Ed25519 key, you can reuse it. Look in your .ssh folder on your computer. On Windows PowerShell, use ls $HOME\.ssh instead:

ls -al ~/.ssh

If you see id_ed25519 and id_ed25519.pub, skip to Step 4. If the folder does not exist, that is fine; the next step creates it.

Step 2: Generate a new key pair

The ssh-keygen command creates the keys. The -t ed25519 flag chooses the modern Ed25519 algorithm, and -C adds a label so you can recognize the key later:

ssh-keygen -t ed25519 -C "alex@laptop"

When prompted for a file location, press Enter to accept the default. When prompted for a passphrase, type one. A passphrase encrypts the private key on your disk, so a stolen file is not enough to log in. The output looks like this:

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/alex/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Your identification has been saved in /home/alex/.ssh/id_ed25519
Your public key has been saved in /home/alex/.ssh/id_ed25519.pub

Step 3: Install the public key on the server

The ssh-copy-id tool appends your public key to the server's list of allowed keys. Run it from your computer, replacing the address and username with yours:

ssh-copy-id -i ~/.ssh/id_ed25519.pub alex@203.0.113.10

Enter your password one last time. If ssh-copy-id is not available on your computer, copy the key manually. This command sends the public key over SSH and appends it to authorized_keys, creating the folder and file if needed:

cat ~/.ssh/id_ed25519.pub | ssh alex@203.0.113.10 "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

Step 4: Test the key login

Open a new terminal and connect normally:

ssh alex@203.0.113.10

If the key is set up correctly, you log in without a password prompt, or you are asked only for your key passphrase. Keep your existing session open until this works.

Step 5: Check file permissions on the server

SSH refuses keys when the folder or file is readable by other users. Check the permissions on the server:

ls -ld ~/.ssh
ls -l ~/.ssh/authorized_keys

drwx------ 2 alex alex 4096 Oct 31 09:14 /home/alex/.ssh
-rw------- 1 alex alex  101 Oct 31 09:14 /home/alex/.ssh/authorized_keys

If the permissions differ, fix them with chmod 700 ~/.ssh and chmod 600 ~/.ssh/authorized_keys. The chmod command changes who may read or write a file.

Troubleshooting

• Still asked for a password. Check the permissions in Step 5 first. For more detail, run ssh -v alex@203.0.113.10 and read the lines that mention the key.
• "Too many authentication failures." Your SSH agent is offering several keys. Force the right one with ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 alex@203.0.113.10.
• The key was added to the wrong account. Remove the line from the authorized_keys file of that account with nano, then repeat Step 3 for the correct user.
• Lost the private key or passphrase. A key cannot be recovered. Generate a new pair, install the new public key while you can still log in with another method, and remove the old line from authorized_keys.

Next steps

With key login working, you can now turn off password logins and direct root access. The SSH hardening guide walks you through that safely.