SSH allows you to log in using passwords, but you can also log in with a faster and more secure method, public key authentication. While this sounds daunting, it’s actually remarkably easy to use.

Overview

The steps you need to get started are:

  1. Create a key pair. One key is public, the other private.
  2. Copy the public key to computers you log into regularly.
  3. (optional) Load the private key into a helper program, called ssh-agent.
  4. Connect. You may need to troubleshoot.

Step 1 only has to be done once. Step 2 only needs to be done once per machine (but see also below).

The instructions below are mainly aimed at users of UNIX-like operating systems (e.g. Linux, MacOS) . We have some brief notes for users of other systems.

There are some further notes for interested readers.

Step-by-step

Below are the details of each step, with some explanation of what’s going on:

Create a key pair

laptop% ssh-keygen -t ed25519 -C "me@laptop"
Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in id_ed25519.
Your public key has been saved id_ed25519.pub.

You may need to copy the key pair to the right place:

laptop% mkdir ~/.ssh
laptop% chmod 0700 ~/.ssh
laptop% chmod 0600 id_ed25519
laptop% mv id_ed25519 ~/.ssh/id_ed25519
laptop% mv id_ed25519.pub ~/.ssh/id_ed25519.pub

What’s going on:

  • The -t argument sets the type of SSH key to be generated. ed25519 is the recommended one these days.

  • The -C argument to ssh-keygen allows you to specify a comment in the key. This will be visible in the public key file. You can put anything you like in the comment, the example shows one way to do it. The comment can help when you need to distinguish between keys.

  • It is vital to encrypt the private key. This is what the “passphrase” is used for, to encrypt and later decrypt the key. This prevents people from copying and using it, pretending to be you.

  • By default ssh looks in a specific directory (.ssh, in your home directory) for your keys and its configuration file. It’s important to get the file and directory permissions right. ssh will refuse to work if you have the permissions set too liberally.

Copy the public key to computers you log into regularly

laptop% cat ~/.ssh/id_ed25519.pub | ssh fred@remote.host.net "cat >> .ssh/authorized_keys"
Enter password for fred@remote.host.net:

What’s going on:

  • This command copies the contents of the ~/.ssh/id_ed25519.pub file and appends it to .ssh/authorized_keys on remote.host.net.
  • Another way to achieve the same thing is: 
    laptop% ssh-copy-id -i ~/.ssh/id_ed25519.pub fred@remote.host.net
    Enter password for fred@remote.host.net:

For ATNF machines, most people will only need to do this once (on ‘venice’) because your home directory is shared across machines; once you have set up your public key to one machine, you will have it installed on all of them. Some users have a separate home directory at some of our sites; those people will need to update each of those other locations.

Load the private key into a helper program, called ssh-agent

This is optional, but will make life more pleasant.

laptop% eval `ssh-agent`               # not needed on MacOS
laptop% ssh-add
Enter passphrase for ~/.ssh/id_ed25519:
laptop%

What’s going on:

  • Essentially, ssh-agent does your password-typing for you.
    Once you ssh-add your private keys to the agent, it is able to respond to authentication requests on your behalf, using your keys.

  • Sure, when loading the key you need to type your passphrase, but this is just proving to ssh-agent that the key is yours. You won’t have to type your passphrase again, until you stop running the agent.

Note for MacOS users: the default setup runs a program called keychain that acts as an SSH agent. You don’t need to start it manually.

Connect

laptop% ssh fred@remote.host.net
Welcome to remote.host.net!
remote$

If you want to see what’s really going on, use the -v option to ssh.

Troubleshooting

Use ssh -v

Use ssh -v to connect. This gives a lot of detail about what’s going on in the background, which may help resolve the problem. Always include output from this command when requesting help.

How do I check ssh-agent is running?

The simplest option is to ask it to list any keys it has loaded. If it is not running, you will see an error message similar to what is shown below.

$ ssh-add -l
Could not open a connection to your authentication agent.

The other check is to look for environment variables the agent sets. You should see something like this:

$ env|grep SSH_
SSH_AGENT_PID=123456
SSH_AUTH_SOCK=/tmps/sh-zx7ciKsZmLE3/agent.123456

I started the agent, but ssh keeps asking me for a password

This usually indicates that SSH is unable to use your key for login. Try again with ssh -v and check for output lines saying:

Authentications that can continue

(publickey should be one of the options listed), and

Offering public key

Both of these lines should appear in the output.

Next, make sure that ssh-agent -l shows your key is loaded.

Now check that at the remote end you have:

  • ~/.ssh directory has correct permission (drwx------)
  • ~/.ssh/authorized_keys file exists and has correct permissions (-rw-------)
  • ~/.ssh/authorized_keys contains the right public key.
    You can keep more than one key in this file. The comment field will help you distinguish between the keys in the file; that is why it is important to use it correctly when you create the key pair.
  • Your home directory (~) does not have group write turned on (ideally, no access for anyone but you, i.e. drwx------)

Now run ssh -v again and watch what happens when it comes to the publickey step.

Note: The server may be configured to require both the key and a password. Ask the administrators of the server about this.

I started the agent, but ssh keeps asking me for a passphrase

Note that here we mean the passphrase for the SSH key, not the password for the computer account.

There are two cases to consider here.

  1. ssh will usually try to use your keys, if it finds any in the ~/.ssh directory. However if ssh can’t decrypt your private key (by talking to an ssh-agent), it has no alternative but to ask you for the passphrase. ssh uses environment variables to find out which process is the ssh-agent. It then tries to talk to that process. Sometimes, the environment variables don’t get set up correctly. There are two main kinds of problem:
    1. If you started ssh-agent from a window on your X11 desktop, you need to start the ssh command in the same window as the ssh-agent. None of the other windows on your desktop will know about changes in the environment variables of the window where you started ssh-agent.

    2. If you started ssh-agent before you started your X desktop session, then all your windows should “know” about the ssh-agent, because they are children of the shell in which you started the agent. Check that ssh-agent has updated your environment variables:

      laptop% env | grep SSH_A
      SSH_AUTH_SOCK=/tmp/ssh-HQHtfI6952/agent.6952
      SSH_AGENT_PID=6955
      laptop%

      Getting this right may take some fiddling with your login scripts.

  2. It’s easy to misunderstand how the ssh-agent works. Once you’ve logged into a remote computer, and then want to connect on to a second machine, ssh on the computer you’ve just logged on to won’t know about the ssh-agent running on your laptop.

    You can work around this if you make your connection like this:

    laptop% ssh -A me2@remote.example.net
    Welcome to remote.example.net!
    remote$ ssh me2@second.example.net
    Welcome to second.example.net!
    second$

    The -A argument turns on agent forwarding. This means that when you type ssh on the remote machine, the program will ask the ssh-agent on your laptop for an authentication key.

    A couple of final notes:

    • The account on the second machine must also have a copy of your public key in its .ssh/authorized_keys file.
    • Use agent forwarding with caution. Never use it as ‘root’.

I need to change the passphrase on my key (or add one)

Assuming your private key is in ~/.ssh/id_ed25519 , run this command

$ ssh-keygen -p -f ~/.ssh/id_ed25519
Enter old passphrase:
Enter new passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved with the new passphrase
$

I need to prevent a key being used

There are a couple of options. The easy one is to delete the private key. Job done … as long as that is the only copy.

If you suspect someone else has a copy of the private key, you will need to log in to each of the machines where you use the key, and delete it or comment it out from your ~/.ssh/authorized_keys file on those machines. You should probably seek help from the administrators of those machines.

Non-UNIX operating systems

Windows

There is a package called PuTTY that provides SSH functions. It provides a terminal via the program putty.exe and an SSH agent with pagent.exe.

Windows 10 and later has support for a the usual set of command-line ssh programs including ssh-keygen; these can be called from the traditional cmd.exe or from PowerShell. Another good option is Windows Subsystem for Linux.

Microsoft have a guide to setting up ssh-agent and loading your key. The main steps are shown below – run these in PowerShell.

# By default, the ssh-agent service is disabled. Configure it to start automatically.
# Run the following command as an administrator.
PS> Get-Service ssh-agent | Set-Service -StartupType Automatic

# Start the service. It should auto-start after reboots, etc.
PS> Start-Service ssh-agent

These commands can be run as a normal user (in PowerShell).

# The following command should return a status of Running.
PS> Get-Service ssh-agent

# Load your key files into ssh-agent.
PS> ssh-add $env:USERPROFILE\.ssh\id_ecdsa

After you add the key to the ssh-agent service on your client, the ssh-agent service automatically retrieves the local private key and passes it to your SSH client.

Android

We recommend ‘ConnectBot’ or ‘Termius’. Both are available for free, but watch out for default settings that select a ‘paid subscription’ mode.

iOS

The only suitable free option we have found so far is ‘Termius’.

Further Notes

  • A key is basically a long number. SSH represents keys using files, each file containing one key. The format used for the private and public keys is different.
  • You can use any name for the key files (by adding the -f argument to ssh-keygen). For example: 
    laptop% ssh-keygen -t ed25519 -C "me@laptop" -f ~/.ssh/webmaster
    Generating public/private ed25519 key pair.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in ~.ssh/webmaster.
    Your public key has been saved ~.ssh/webmaster.pub.
    It’s a good idea to use different keys for different roles. You will need to keep each key in a differently-named file. For example if you do any computer administration (for example, administering a web server), you might generate a key just to be used in that capacity.
  • If you want to embed a timestamp into the comment field of the key, try this:
    laptop% ssh-keygen -t ed25519 -C "me@laptop `date +%Y-%m-%dT%H:%M:%S%z`" -f ~/.ssh/mykey
    This will generate a comment like ‘me@laptop 2025-05-03T12:34:56+1000’ .

  • If you don’t encrypt the private key, anyone who can make a copy of your private key file can use all the accounts where you have deposited your public key. This means they can impersonate you; it’s the same as giving them your password. Think – what could happen if your laptop was lost or stolen?

    If you do encrypt the private key, someone may copy the file, but it’s useless to them unless they can guess the passphrase you used to encrypt it. SSH encryption is strong enough that guessing could take many years. So make sure to encrypt your private keys.

  • What constitutes a good passphrase?

    • Ideally it should be a long string of randomly-chosen characters. But that’s too hard to remember for most people.

    • The next best option is a phrase you can remember but with some letters replaced by numbers.
      Preferably a nonsense phrase, for example: jo9us+Jone9s h3rds_L2mbs .

    • If you’re stuck for inspiration, an old password will do, temporarily. But you should update it when inspiration strikes, see Troubleshooting, above.
    • A long passphrase can be annoying to type. However if you use an ssh-agent program (see above) you should only need to type it once in a while, a couple of times per day perhaps.