SSH keys

First principles

An SSH key pair is two files that mathematically match. The public file is safe to hand out: it is a lock. The private file is the key to that lock. Anyone who holds the private file can prove they are you to any host that has accepted the public file.

That is the whole model. Encryption of the session is a separate layer. The pair is identity. Treat the private file the way you treat a password that never expires and cannot be rotated without visiting every host.

The two files

Default names, on macOS and Linux, live under your home directory:

~/.ssh/id_ed25519      private  — mode 600, never copied
~/.ssh/id_ed25519.pub  public   — the lock, this one travels

On Windows OpenSSH the same names sit at %USERPROFILE%\.ssh\id_ed25519 and .pub. The .pub file is one line. The private file is a block of text. If a chat, a ticket, or a git diff ever contains that block, the key is burned.

Generate an ed25519 key

Same command on macOS Terminal, a Linux shell, and Windows PowerShell or Command Prompt with OpenSSH installed (Windows 10 and 11 include it):

ssh-keygen -t ed25519 -C "you@org"

It asks for a path. The default is fine if you do not already have a key. It asks for a passphrase. Set one. The passphrase encrypts the private file at rest on your disk. An unlocked agent holds it for the session; the file on disk stays wrapped.

If ssh-keygen says the file already exists and asks to overwrite, stop. Overwriting a private key does not update the public half already sitting in authorized_keys on your servers. Those hosts will still expect the old lock. Answer n unless you intend to replace the pair everywhere in the same change.

Need a second key for a second role? Do not overwrite. Name it:

ssh-keygen -t ed25519 -C "you@org-admin" -f ~/.ssh/id_ed25519_admin

House rules

• Never paste a private key into chat, email, a ticket, or a pastebin.
• Never commit ~/.ssh/id_ed25519 or any file that begins with BEGIN OPENSSH PRIVATE KEY.
• If the private file leaked, generate a new pair, install the new public file, and remove the old line from every authorized_keys you control. Then treat the old key as hostile.
• A key without a passphrase is a password sitting in a file. Put a passphrase on it.