SSH keys

A key lets you sign in to an SSH server without sending a password. By the end of this lesson you can make a key, install it on a server, use it from SecureShell Go, and take it away again when a device is lost.

Why use a key

In the last lesson you signed in with a password. That works, but a password can be guessed, reused on other sites, or watched as you type it. Servers on the internet receive password guesses all day long.

A key pair is two matching files:

Half	Where it lives	Who may see it
Private key	Only on your device, for example ~/.ssh/id_ed25519	Nobody. Treat it like a password.
Public key	On every server you want to sign in to, in ~/.ssh/authorized_keys	Anyone. Sharing it gives no access.

When you connect, the server sends a fresh random challenge. Your device signs it with the private key, and the server checks the signature with the public key it already has. The private key never leaves your device, and each signature is good for one sign-in only, so there is nothing for an eavesdropper to reuse.

 Your device                                   Server
 ┌──────────────────┐                          ┌──────────────────────────┐
 │ private key      │   1. "sign this: 7f3a…"  │ ~/.ssh/authorized_keys   │
 │ (never sent)     │ ◄─────────────────────── │   ssh-ed25519 AAAA… maya │
 │                  │   2. signature           │                          │
 │                  │ ───────────────────────► │ 3. checks it with the    │
 └──────────────────┘                          │    public key: welcome   │
                                               └──────────────────────────┘

Kinds of key

Type	Use it when	Command
ed25519	Almost always. Short, fast, and supported by every current SSH server.	ssh-keygen -t ed25519
RSA	A very old server or device does not accept ed25519. Use at least 3072 bits.	ssh-keygen -t rsa -b 4096
ECDSA	Some organisations require it. Otherwise prefer ed25519.	ssh-keygen -t ecdsa

An ed25519 public key is one short line of about 90 characters; a 4096-bit RSA public key is over 700.

Make a key

On Linux, macOS or Windows (in PowerShell), run ssh-keygen. -C adds a comment, a label stored at the end of the public key, so you can tell later which device a key belongs to.

$ ssh-keygen -t ed25519 -C "maya@laptop"
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/maya/.ssh/id_ed25519):
Enter passphrase for "/home/maya/.ssh/id_ed25519" (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/maya/.ssh/id_ed25519
Your public key has been saved in /home/maya/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:L8BPGUEDc7xoANerKu6RDnDAVO8vcb82Tldt2QFHxVU maya@laptop
…

Press Enter at the first question to accept the usual file name. Two files appear:

$ ls -l ~/.ssh/id_ed25519*
-rw------- 1 maya maya 399 Nov  9 17:44 /home/maya/.ssh/id_ed25519
-rw-r--r-- 1 maya maya  93 Nov  9 17:44 /home/maya/.ssh/id_ed25519.pub

The private key (no ending) is readable by you alone. The .pub file is the public key, a single line:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI… maya@laptop

The passphrase

A passphrase encrypts the private key file. If someone copies the file from a stolen laptop or a backup, they still cannot use it without the passphrase. Pick a few words you can remember. An empty passphrase is only reasonable for a key that does one narrow job and never leaves one machine; WinBridge's dedicated VM key is an example.

A wrong passphrase is refused before the key is ever used:

Load key "/home/maya/.ssh/id_ed25519": incorrect passphrase supplied to decrypt private key

Put the public key on the server

The easiest way, from Linux or macOS, while you can still sign in with a password:

$ ssh-copy-id maya@192.168.1.20
/usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/home/maya/.ssh/id_ed25519.pub"
…
maya@192.168.1.20's password:

Number of key(s) added: 1

Now try logging into the machine, with: "ssh 'maya@192.168.1.20'"
and check to make sure that only the key(s) you wanted were added.

ssh-copy-id appends your public line to ~/.ssh/authorized_keys on the server and sets the right permissions. Now ssh maya@192.168.1.20 asks for your key's passphrase (if it has one) instead of the account password.

By hand

If ssh-copy-id is not available, sign in to the server and add the line yourself:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys      # paste the one public line, save
chmod 600 ~/.ssh/authorized_keys

The permissions matter. The SSH server ignores your authorized_keys if other users could change it, because then anyone could add their own key to your account:

$ ls -ld ~/.ssh ~/.ssh/authorized_keys
drwx------ 2 maya maya 4096 Nov  9 17:46 /home/maya/.ssh
-rw------- 1 maya maya   93 Nov  9 17:46 /home/maya/.ssh/authorized_keys

700 on the folder and 600 on the file mean "only the owner". When a key that should work is refused, check these first.

Windows servers

For an ordinary account, the file is C:\Users\<name>\.ssh\authorized_keys, as on Linux. For an account in the Administrators group, Windows OpenSSH reads C:\ProgramData\ssh\administrators_authorized_keys instead.

One line per key

Each line of authorized_keys is one key that may sign in:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI… maya@laptop
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI… secureshellgo@192.168.1.20

Give every device its own key, with a comment that names the device. Then you can remove one device without touching the others.

Agents: type the passphrase once

An SSH agent is a small program that holds your unlocked keys in memory, so you type the passphrase once per session rather than at every connection. Most Linux desktops and macOS start one for you. To add a key and list what it holds:

$ ssh-add ~/.ssh/id_ed25519
Enter passphrase for /home/maya/.ssh/id_ed25519:
Identity added: /home/maya/.ssh/id_ed25519 (maya@laptop)

$ ssh-add -l
256 SHA256:L8BPGUEDc7xoANerKu6RDnDAVO8vcb82Tldt2QFHxVU maya@laptop (ED25519)

ssh-add -t 3600 ~/.ssh/id_ed25519 keeps the key for one hour only, and ssh-add -D forgets all keys at once.

Agent forwarding

ssh -A, and Forward SSH agent in SecureShell Go, let a server use your agent while you are connected. Anyone with root on that server can then sign in elsewhere as you. Only forward your agent to servers you trust completely.

Save the details in ~/.ssh/config

Instead of typing the address, user and key every time, give the server a short name in ~/.ssh/config on your device:

Host desktop
    HostName 192.168.1.20
    User maya
    IdentityFile ~/.ssh/id_ed25519

Now ssh desktop, scp notes.txt desktop: and sftp desktop all work. CrossShell writes entries like this for each paired machine, which is why ssh <name> works after pairing.

Take a key away

When a phone is lost, a laptop is sold or a colleague leaves, remove their key from every server it was on:

1. Sign in to the server from another device.

2. Find the line by its comment:

   grep -n "maya@old-phone" ~/.ssh/authorized_keys

3. Delete that line with a text editor, such as nano ~/.ssh/authorized_keys, and save.

4. The lost device's key now opens nothing on this server. Repeat on every server that had it.

Changing the account password does not lock out a key. Only removing the line does.

Host keys and user keys

Both are key pairs, and both appear in files under .ssh, so people often mix them up:

	Host key	User key
Proves	Which server you reached	Which person or device is signing in
Private half lives	On the server, in /etc/ssh/	On your device, in ~/.ssh/
Public half is saved	In your ~/.ssh/known_hosts	In the server's ~/.ssh/authorized_keys
Made by	The server's installer	You, with ssh-keygen or an app

Do it in the apps

SecureShell Go can make a key and install it for you. In the host's form, select Private key, tap Generate new key, save the host, then tap Install public key on server… and enter the account password once. The app adds the public line to authorized_keys, with a comment such as secureshellgo@192.168.1.20, and sets the permissions. You can also Import key file for a key made with ssh-keygen, or, on a computer, sign in through your OS SSH agent. See Use SSH keys.

CrossShell swaps keys during pairing. The other machine's key goes into your authorized_keys with a crossshell: marker, so unpairing removes exactly that line. See Use SSH and the terminal.

WinBridge asks you to make a separate key, used only for its Windows VM, rather than reusing your everyday key. See Build Flutter apps on a Windows VM.

Stay safe

• Never share the private key. Not in a chat, an email, a ticket or a Git repository. Only the .pub line goes anywhere.
• Use a passphrase on any key that lives on a laptop or phone.
• One key per device, named in its comment, so one lost device costs you one line.
• Move key files over a cable or a transfer you control, not by email.
• Review authorized_keys now and then and remove lines you do not recognise.

Check yourself

QuizSSH keys

Question 1 of 6

Which half of your key pair goes on the server?

Score: 0

What you learned

• The private key stays on your device; the public key goes in the server's authorized_keys.
• Use ed25519 unless an old system needs RSA, and protect the private key with a passphrase.
• ssh-copy-id installs a key; by hand, ~/.ssh must be 700 and authorized_keys 600.
• An agent holds unlocked keys so you type the passphrase once.
• To revoke a key, delete its line from authorized_keys; a password change does not.

Next steps

• SSH tunnels
• Use SSH keys in SecureShell Go
• Auth basics: the same ideas for APIs