Using SSH Keys

SSH keys allow you to connect securely to departmental machines, GitLab, and potentially other systems, without needing to enter your password every time.

The following is intended as a "getting started" guide covering the most common scenarios - other options are available and can be found online.

Linux/macOS/WSL Terminal

If you are using a standard Linux/Unix-like terminal with OpenSSH Client installed (which is usually the case), you can set up SSH keys as follows.

To create a new SSH key pair:

Run ssh-keygen -C "john.doe@maths.ox.ac.uk (Oxford Maths desktop)" - replacing the last part with a comment that uniquely identifies the key. (This may be shared with other people when you upload your public key to a server.)
At the prompt "Enter file in which to save the key", press Enter to accept the default value.
At the prompt "Enter passphrase", enter a suitably secure password to encrypt your key with. Press Enter, then enter it again, and press Enter again.

To upload your public key to the departmental systems:

Run ssh-copy-id USERNAME@gate.maths.ox.ac.uk - replacing USERNAME with your Maths username.
If prompted to confirm the host key fingerprint, check it here. If it is valid, type yes and press Enter.
Enter your Maths account password when prompted and press Enter.

Add the following to your ~/.bash_profile file to automatically start/stop the SSH agent:

if [[ -n $PS1 && -z $SSH_AUTH_SOCK ]]; then
    eval "$(ssh-agent -s)" && ssh-add
    trap 'eval "$(ssh-agent -k)"' EXIT
fi
if [[ -n $SSH_AUTH_SOCK ]] && ! ssh-add -l &>/dev/null; then
    ssh-add
fi

Then close and re-open your terminal to load it. You should be prompted for the password/passphrase used to secure your key - type it and press Enter. (If you don't want to unlock it for a session, you can just press Enter.)

To use your SSH key:

Run ssh -A USERNAME@gate.maths.ox.ac.uk - replacing USERNAME with your Maths username.
You should now be connected to gate, without being prompted for your Maths password.
From gate, you should be able to connect to other Maths servers - e.g. ssh cyclops.
Type exit and press enter to disconnect.

It is technically possible to share the SSH agent across multiple Terminal windows, e.g. with Keychain or custom Bash code, but that is beyond the scope of this guide.

Ubuntu Desktop (GUI)

If you are connecting from a departmental desktop, a laptop installed by us, or a Linux RAP server, this will probably be the easiest way to set up your SSH key. It may also work on some other Linux GUI distributions.

To create a new SSH key pair:

Click Menu > Accessories > Passwords and Keys (or run seahorse from a terminal).
Click the "+" button (top-left corner) then "Secure Shell key".
In the Description field, enter something to uniquely identify the key e.g. john.doe@maths.ox.ac.uk (Oxford Maths desktop). (This may be shared with other people when you upload your public key to a server.)
For Encryption Type, select "ED25519".
Click "Generate".
When prompted, enter a suitably secure password to encrypt your key with, then click "OK".
When prompted, enter the same password again, then click "OK".

To upload your public key to the departmental systems:

Right-click the key, then click "Configure Key for Secure Shell".
Enter the server address gate.maths.ox.ac.uk and your Maths username.
Click "Set Up".
Enter your Maths account password when prompted and click "OK".

To use it:

Open a new Terminal window.
Run ssh -A USERNAME@gate.maths.ox.ac.uk - replacing USERNAME with your Maths username.
You should be prompted to enter the password used to secure your key - enter it and click "Unlock". (You will only need to do this once per session - it will remain unlocked until you log out of the local machine.)
You should now be connected to gate, without being prompted for your Maths password.
From gate, you should be able to connect to other Maths servers - e.g. ssh cyclops.
Type exit and press enter to disconnect.

Technical notes:

The private key is stored in ~/.ssh/id_<type> (e.g. ~/.ssh/id_rsa), encrypted with the password you entered.
If you tick "Automatically unlock this key whenever I'm logged in", the password is saved in your "Login" keyring, which is encrypted using your Maths/laptop account password and unlocked automatically when you log into a desktop/laptop (but not a RAP server due to technical limitations).
The public key is stored in ~/.ssh/id_<type>.pub.
When you upload your public key to a remote system, it is added to ~/.ssh/authorized_keys on that system. The Description you entered is included as a comment to identify the key.
Because Maths home directories are shared over the network, you only need to add your public key to a single machine to log into any of them.
The -A flag enables SSH agent forwarding, which allows the key to be used on the remote system too. This is particularly useful for gate, where you will want to connect to other internal systems, but it should be avoided when connecting to untrusted third-party systems.

Windows PowerShell

If you are using a departmental Windows laptop, you can set up SSH keys as follows.

Using your Administrator account, open PowerShell and run the following to enable SSH agent (you only need to do this once):

Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent
exit

Then using your standard User account, open PowerShell and create a new SSH key pair:

Run ssh-keygen -C "john.doe@maths.ox.ac.uk (Oxford Maths desktop)" - replacing the last part with a comment that uniquely identifies the key. (This may be shared with other people when you upload your public key to a server.)
At the prompt "Enter file in which to save the key", press Enter to accept the default value.
At the prompt "Enter passphrase", enter a suitably secure password to encrypt your key with. Press Enter, then enter it again, and press Enter again.
Run ssh-add to import your private key into the SSH agent. Enter your passphrase when prompted and press Enter. (You will only need to do this once - Windows will store it encrypted with your Windows password.)

To upload your public key to the departmental systems:

Run type $env:USERPROFILE\.ssh\id_*.pub | ssh USERNAME@gate.maths.ox.ac.uk 'cat >> .ssh/authorized_keys' - replacing USERNAME with your Maths username.
If prompted to confirm the host key fingerprint, check it here. If it is valid, type yes and press Enter.
Enter your Maths account password when prompted and press Enter.

To use your SSH key:

Run ssh -A USERNAME@gate.maths.ox.ac.uk - replacing USERNAME with your Maths username.
You should now be connected to gate, without being prompted for your Maths password.
From gate, you should be able to connect to other Maths servers - e.g. ssh cyclops.
Type exit and press enter to disconnect.

Security Considerations

An SSH key is made up of two parts - a private key and a public key. As the name implies, you must keep the private key to yourself, the same as you would a password. The public key can be shared freely - this is what you upload to the target servers so they can identify you.

Your private key should be encrypted with a passphrase to keep it secure - especially on shared systems such as the departmental computers.

You can have multiple SSH keys (e.g. one for the Maths computers, another for your laptop), or you can copy the same key to multiple machines. Either is fine, as long as they are stored and transferred securely.

If a private key is ever compromised, remove it from ~/.ssh/authorized_keys on all systems (or contact IT Support for assistance doing so). You may also need to report it as a potential data breach if your account contains any personal data or saved passwords.