SSH Keys

SSH Keys

SSH key pairs allow users to connect to remote accounts without having to use the password of the remote account. This is useful if you'd like to not have to enter the password to an account you own and access frequently, or if you need to connect to a shared account where you are not its owner and do not know its password. You create a pair of files known as "keys", one private and one public, to facilitate this process. The private key stays on the machine you will connect from which is usually the machine where it is created (for example, your laptop). The other key, the public key, is put into the remote account by the owner of that account (which may be you) or by the server administrator. Think of this process as leaving a real key (the public key) in a remote door. The door will only open if you have the associated private key as you approach. This is why you must keep the private key to yourself, otherwise people who have a copy of it can pass through all the doors in which you left your public key.

On UNIX and Mac OS X

Generating SSH Keys

You can generate keys with the 'ssh-keygen' command:

$ ssh-keygen -t ed25519
Generating public/private ed25519 key pair.
Enter file in which to save the key ($HOME/.ssh/id_ed25519):     
Enter passphrase (empty for no passphrase):  
Enter same passphrase again:  
Your identification has been saved in $HOME/.ssh/id_ed25519.
Your public key has been saved in $HOME/.ssh/

If you already have a keypair with the standard names, you may choose to create additional keypairs with different names. For security reasons you should not use empty passphrases.

Uploading the public key

Once you have generated the key pair, you will need to transfer the public key, e.g. ~/.ssh/, to the remote site. You can transfer the public key in any number of ways, such as by emailing it to the owner of the remote account or an administrator, or FTP, SCP, or SFTP if you have access. The public key file is actually just a text file.

Installing the public key

Once the key has been transfered to the remote machine, its contents will need to be appended to ~/.ssh/authorized_keys within the remote account. If you are not the owner of the remote account you will need to have the owner perform this step. Otherwise, on the remote computer:

$ cat >> ~/.ssh/authorized_keys

On Windows

The most popular Windows SSH client today is Putty which is available from Download the complete Windows installer rather than just the putty.exe file. You may choose to follow the thorough Putty documentation directly on how to create an SSH keypair on Windows. Otherwise see the more brief step-by-step instructions below.

Generating SSH Keys

  1. Start the puttygen.exe program included with the Putty installer.
  2. In the Parameters section choose SSH2 RSA as the key type and press Generate. You will need to move your mouse about in the small window area in order to generate randomness that the process requires.
  3. You may choose to enter a key comment which can be used by you to identify the key (useful when you use several SSH keys).
  4. Type in a passphrase and confirm it. The passphrase is used to protect your key and you will be asked for it when you connect via SSH using public key authentication.
  5. Click Save private key to save your private key. A common name is id_rsa.
  6. Click Save public key to save your public key.  A common name is

Uploading and Installing the public key

See the UNIX instructions for these steps above as they are identical.

Using the SSH Key

SSH config file

You can explicitly tell your ssh program to use your ssh key and not your password with `ssh -o preferredauthentications=publickey ...`. Since you may not want to type that every time, you can configure an ssh host alias. Create and/or append to the file ~/.ssh/config on your local computer and enter the following:

Host somename
User theuser
PreferredAuthentications publickey

Then you can invoke `ssh somename` and it will pass in all of the above options.

SSH Agent

If you do not want to have to type your key's passphrase every time, you can load the key into your SSH agent once. The ssh-agent is usually automatically started on Linux, and you can load the key into your agent by typing `ssh-add`. If your key is in a non-standard location, you can manually specify it with `ssh-add /path/to/the/ssh/key`. On macOS, your agent uses your keychain, so pass in `-K` to ssh-add, e.g. `ssh-add -K` or `ssh-add -K /path/to/the/ssh/key`.