Help:SSH Keys

SSH supports Public Key Infrastructure (PKI) based authentication using public-private key pairs. Typical algorithms include RSA and ed25519.

Properly configured ssh keys allow your account on one machine to authenticate to your account on another machine without needing an additional password.

Creating SSH Key Pairs

In order to use SSH keys for authentication, you must generate a pair of keys. One of these is called the "public" key, which is in this application can be thought of as the lock cylinder in a mechanical lock, which gets placed on the destination host. This key is not confidential. The second key is called the "private" key, which can be thought of as the key that fits the aforementioned lock cylinder. This key must NEVER be shared with others.

OpenSSH (Linux, UNIX, BSD, macOS, Windows 10)

OpenSSH, derived from OpenBSD, is the most widely used SSH distribution for both server and client and is the default SSH implementation in all major UNIX and UNIX-like operating systems including Linux, macOS, and the BSDs where the client is typically installed by default. Starting from version 1803, OpenSSH is also included with Windows 10. The client includes a command called ssh-keygen, which can be used to generate SSH key pairs from available entropy. The default key algorithm is RSA, but this can be overridden with the option -t <algorithm> (see the man page with man ssh-keygen for details). Please note: DSA is no longer considered a secure key algorithm and should not be used.

Generating an RSA Key Pair

An RSA key pair can be generated by simply running ssh-keygen in the terminal and following the prompts. It is highly recommended to provide a strong passphrase to encrypt the private key.

Example

user@host:~$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/home/user/.ssh/id_rsa):
Created directory '/home/user/.ssh'.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:

Your identification has been saved in /home/user/.ssh/id_rsa.
Your public key has been saved in /home/user/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:cG90W7KMyH4I8ZHN6ygQsrVK4x3VNNa4IqZBJqTm2I0 user@host
The key's randomart image is:
+---[RSA 3072]----+
|..      +o       |
|o o    +.=.      |
|.=. o + =.+ o .  |
|+..*o+.*.= = =   |
|..E+=...S = +    |
| o.+ o o =       |
|  o . . + o      |
|       . .       |
|                 |
+----[SHA256]-----+

Authenticating with Key Pairs

To use SSH keys for authentication, the destination host must be told which public keys to accept. This is typically done by appending the public key to the file ~/.ssh/authorized_keys on the destination host.

Adding an Authorized Key with ssh-copy-id

If you already have access to a remote system via SSH, then ssh-copy-id, included with the OpenSSH client, can be used. By default, it will add all public keys (~/.ssh/*.pub) that aren't already authorized on the remote host; this can be overridden with the option -i <public key file>. Read the man page with man ssh-copy-id for more details.

Example

user@host:~$ ssh-copy-id user@remote-host
/usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/home/user/.ssh/id_rsa.pub"
/usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed
/usr/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you are prompted now it is to install the new keys
user@remote-host's password:

Number of key(s) added:        1

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