ZipKit
Glossary

SSH key

SSH key is a public and private key pair that proves who you are to a server over SSH, so you can log in or push to Git without sending a password. SSH stands for Secure Shell. You create it with ssh-keygen from OpenSSH, keep the private half secret and copy the public half to the server. OpenSSH 9.5 (2023-10-04) changed ssh-keygen to generate Ed25519 keys by default.

How it works

The server stores your public key, one key per line, in ~/.ssh/authorized_keys. When you connect, the client says which key pair it wants to use and proves it holds the private key, which never leaves your machine. A line in authorized_keys has the fields options (optional), key type, base64 key and comment.

ssh-keygen writes two files. For Ed25519 they are ~/.ssh/id_ed25519 (private) and ~/.ssh/id_ed25519.pub (public); RSA uses id_rsa and id_rsa.pub. The private file must be readable only by you. Key types and sizes:

  • ed25519: the default, with a fixed 256-bit key. The -b flag is ignored.
  • rsa: minimum 1024 bits, default 3072 bits. When ssh-keygen signs certificates with an RSA CA key, it uses rsa-sha2-512 by default.
  • ecdsa: -b must be 256, 384 or 521; any other value fails.

The public key line is just base64 of a small binary blob: a length-prefixed type name followed by the key. For Ed25519 the blob is the string ssh-ed25519 and the 32-byte public key, so it is 51 bytes in total. The fingerprint that ssh-keygen prints is the SHA-256 hash of that blob, base64 encoded without padding. SHA256 is the default fingerprint algorithm, and -E md5 selects the legacy MD5 form.

$ ssh-keygen -q -N "" -C "demo@example" -f ./demo
$ ls -l demo demo.pub
-rw------- 1 root root 399 Oct  5 09:23 demo
-rw-r--r-- 1 root root  94 Oct  5 09:23 demo.pub
$ cat demo.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBYvs8KbrZEGk7bPXeJ1I+UnGroF2PWG+yBFWiYJQ64R demo@example
$ ssh-keygen -l -f demo.pub
256 SHA256:YuNsmbLdQ0Q6/qiLVt0L7tnPs/XqUKhO5Ewc6LtCTIY demo@example (ED25519)

Decoding the base64 field shows a 51-byte blob: a 4-byte length (11), the bytes ssh-ed25519, a 4-byte length (32) and 32 key bytes. Hashing that blob with SHA-256 gave YuNsmbLdQ0Q6/qiLVt0L7tnPs/XqUKhO5Ewc6LtCTIY, identical to the fingerprint above. This key is a throwaway, created only for this example.

Should I use Ed25519 or RSA for an SSH key?

Use Ed25519 unless a system you connect to cannot accept it. It is the ssh-keygen default, has a fixed 256-bit size and produced a 94-byte public key file here, while a default 3072-bit RSA public key file was 561 bytes. Choose RSA only for older servers, and keep it at 3072 bits or more; the ssh-keygen manual calls 3072 bits generally sufficient.

Common pitfalls

  • Sharing the wrong file: the file without .pub is the private key, and it must never be pasted into a server, a chat or a Git repository. Add only the .pub line to authorized_keys.
  • Permissions too open: with mode 0644 the client refuses the key: WARNING: UNPROTECTED PRIVATE KEY FILE!, Permissions 0644 for 'bad' are too open, This private key will be ignored. Fix it with chmod 600.
  • No passphrase: -N "" creates a key anyone who copies the file can use. Set a passphrase, or add one later with ssh-keygen -p.
  • Old ssh-rsa rejected: OpenSSH 8.8 (2021-09-26) disabled RSA signatures that use SHA-1. Existing RSA keys still work, because the client uses SHA-2 signatures where it can; only very old servers fail.
  • Broken authorized_keys line: each key must stay on one line. A key that wrapped across two lines is no longer a valid line.
  • Mixing up fingerprints: the SHA256 form and the older MD5 form of the same key look different. Compare like with like.

Related terms

  • TLS — also relies on public key cryptography, but for HTTPS connections rather than SSH logins.
  • HTTPS — the other transport Git can use, with different credentials than an SSH key.
  • Git — uses SSH keys to authenticate pushes and pulls.
  • Base64 — the encoding of the key field in a public key line.
  • SHA-256 — the hash behind the default key fingerprint.

See also

  • Term: Base64 — the encoding of the key field in a public key line