SSH Keys #

SSH keys are used in a number of CIS systems and, if used properly, can provide an extra layer of security.

We strongly recommend using SSH keys for git operations on Gitlab.

SSH keys use public key cryptography/authentication to securely login to resources without using a shared password. In the steps below, you'll create an SSH keypair - a public key (which can be openly shared and is loaded onto any server you wish to login to) and a private key (which should be stored securely and never shared).

Recommendations #

We recommend using the OpenSSH tools (including ssh-keygen) wherever possible. These ship with virtually all Linux distributions, MacOS and all recent versions of Windows.

We also recommend using WSL2 in Windows, where possible. It provides the best command-line experience and most up to date tooling. Lab machines are currently unable to run WSL2 due to technical constraints, but they are configured to dual-boot with Linux. Most of the commands here will work in a normal Windows command prompt (or PowerShell prompt) but you may need to make some adjustment to file paths (e.g. ~/ssh/id_ed25519 will be at %USER%\.ssh\id_ed25519 on Windows).

We strongly recommend using only the ed25519 algorithm (an ECDSA variant). It is the most secure SSH key type widely available, and is very well supported in the majority of systems. If you are using an client or server without ed25519 support, you should consider upgrading where possible.

Generating a key #

To generate an SSH key, run: ssh-keygen -t ed25519

You should enter a strong passphrase to protect the private key. If the passphrase and private key file (id_ed25519, by default) are exposed then your account should be considered compromised.

After generating a keypair, you can add the key to your computer's SSH agent - this will prevent you from having to enter the key each time you run an SSH (or git) command. To do so, run ssh-add ~/.ssh/id_ed25519.

If you're using Windows (without WSL), you'll need to enable the OpenSSH Authentication Agent service in services.msc to use the agent; you may need an administrator to enable this service for you if you're using a department-issued computer.

Configuring OpenSSH client #

To use your key, you should edit or create ~/.ssh/config to add the line:

IdentityFile ~/.ssh/id_ed25519

This will instruct the SSH client to attempt to use the id_ed25519 key whenever you connect to an SSH server.

Configuring Gitlab #

You should copy the contents of your id_ed25519.pub file (the public key from your keypair - note the .pub suffix) and paste them into your account SSH keys page.

Keychain agent management #

In some setups (particularly non-graphical Linux and WSL2 machines), SSH agent key management can result in multiple prompts for the key passphrase and can cause problems for reattached tmux and screen sessions. If you are working in such an environment, you should consider using the keychain tool to manage the SSH agent environment and socket.

Note: this isn't normally required if you're using MacOS, a graphical (e.g. Gnome) Linux environment or plain Windows (without WSL2).

Adding your key to the server #

If you would like to use your SSH key to authenticate to cafe, you should run (locally): ssh-copy-id aab12345@cafe.cis.strath.ac.uk (replacing aab12345 with your DS username).

This will copy your public key to your ~/.ssh/authorized_keys file, which controls which keys are allowed to login to a given user account. You can add multiple keys to the authorized_keys file as necessary. It's generally recommended to generate a new key on each client device rather than copy private keys from device to device; this reduces the chance of a key becoming exposed if it is copied insecurely and allows you to revoke access for a specific key (device) by simply removing it from the authorized_keys file or revoking it on the Gitlab web interface.

Note that authentication by SSH key will not give you access to any Kerberos-controlled resources (as PAM doesn't prompt you to enter your account password when using an SSH key). This mean that network shares and SSHing onwards to other machines will generally require you to enter your account password. You can, however, run kinit to start a Kerberos session once you connect to SSH using your key.