Generating SSH Keys

This guide explains how to create an SSH key pair on your computer. You can then deploy the public key to the SSH gateway, Eureka2, AISurrey, Surrey GitLab, GitHub or other services.

For the purpose of this guide we assume that you are either on-campus or connecting via the VPN - Global Protect when testing access to University systems.

Before you start

An SSH key pair consists of:

• a private key, for example id_ed25519_eureka2;

• a public key, for example id_ed25519_eureka2.pub.

The public key is the file you copy to remote systems or upload to GitLab/GitHub. The private key stays on your computer.

Warning

Never share, upload or email your private key. Only share the file ending in .pub.

Which key should I create?

We recommend creating separate keys for separate purposes. This makes it easier to replace or revoke one key without disrupting every system you use.

Examples:

• id_ed25519_gateway for the SSH gateway;

• id_ed25519_eureka2 for Eureka2;

• id_ed25519_aisurrey for AISurrey;

• id_ed25519_surrey_gitlab for Surrey GitLab;

• id_ed25519_github for GitHub;

• id_ed25519_gitlab_com for GitLab.com.

If you are only starting out, create the key you need now. You can always create additional keys later.

Generating a key

Linux / macOSWindows

Open a terminal and run ssh-keygen. Replace the filename and comment with something meaningful for your account and purpose.

For example, for Eureka2:

ssh-keygen -t ed25519 -C "ab1234 Eureka2" -f ~/.ssh/id_ed25519_eureka2

For Surrey GitLab:

ssh-keygen -t ed25519 -C "ab1234 Surrey GitLab" -f ~/.ssh/id_ed25519_surrey_gitlab

Choosing a passphrase

When ssh-keygen asks for a passphrase, we recommend setting one.

A passphrase protects your private key if the key file is copied, stolen or accidentally exposed. Without a passphrase, anyone who obtains the private key file may be able to use it immediately. With a passphrase, they need both:

• something they have: the private key file

• something they know: the passphrase

This is not the same as full multi-factor authentication, but it adds an important extra layer of protection.

Note

You do not normally need to type the passphrase every time you connect. SSH agents can keep an unlocked key available during your login session, and some operating systems can store the passphrase securely for convenience.

Adding the key to your SSH agent

An SSH agent can remember your unlocked key during your login session.

Linux / macOSWindows

Start the SSH agent if needed and add the key you created:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519_eureka2

On macOS, you may prefer:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519_eureka2

If your macOS version does not support --apple-use-keychain, use ssh-add without that option.

Checking the key files

On Linux/macOS, run:

ls -la ~/.ssh/

You should see a private key and a public key. For example:

-rw-------  1 ab1234 staff  411 Jul  7 10:00 id_ed25519_eureka2
-rw-r--r--  1 ab1234 staff   99 Jul  7 10:00 id_ed25519_eureka2.pub

On Windows PowerShell, run:

dir C:\Users\YourUsername\.ssh

The file ending in .pub is the public key. The file without .pub is the private key and must be kept secret.

Optional SSH client configuration

You can create ~/.ssh/config to give systems short names and to tell SSH which key to use.

On Linux/macOS:

nano ~/.ssh/config

On Windows PowerShell:

notepad $env:USERPROFILE\.ssh\config

Example entries:

Host gateway
    HostName access.eps.surrey.ac.uk
    User ab1234
    IdentityFile ~/.ssh/id_ed25519_gateway
    IdentitiesOnly yes

Host eureka2
    HostName eureka2.surrey.ac.uk
    User ab1234
    IdentityFile ~/.ssh/id_ed25519_eureka2
    IdentitiesOnly yes

Host aisurrey
    HostName aisurrey-submit01.surrey.ac.uk
    User ab1234
    IdentityFile ~/.ssh/id_ed25519_aisurrey
    IdentitiesOnly yes

Host surrey-gitlab
    HostName gitlab.surrey.ac.uk
    User git
    IdentityFile ~/.ssh/id_ed25519_surrey_gitlab
    IdentitiesOnly yes

Replace ab1234 and the key filenames with your own details.

We do not recommend enabling ForwardAgent yes by default. SSH agent forwarding is useful for some advanced workflows, but it should be enabled only when you understand why you need it.

macOS: storing SSH key passphrases in Keychain

On macOS, you can ask SSH to store your SSH key passphrase in the macOS Keychain. This reduces the inconvenience of using passphrase-protected keys, because you do not normally need to type the passphrase every time.

Add these lines to the relevant Host entry in ~/.ssh/config:

AddKeysToAgent yes
UseKeychain yes

For example:

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_github
    IdentitiesOnly yes
    AddKeysToAgent yes
    UseKeychain yes

Then add the key to the SSH agent and store the passphrase in Keychain:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519_github

If you are using an older version of macOS, you may see older instructions using ssh-add -K instead.

UseKeychain is specific to Apple’s OpenSSH. Do not add it to shared SSH configuration files that also need to work on Linux systems.

PuTTY and WinSCP on Windows

PuTTY and some versions of WinSCP use .ppk key files. If you use those tools, open PuTTYgen, load your private key, and save a converted .ppk file.

Users who connect with PowerShell, Windows Terminal, Git Bash, VS Code or WSL usually do not need a .ppk file.

Next steps

After creating a key, you need to deploy the public key to the systems you want to access. See Deploying SSH Keys.

If you use Git over SSH with more than one Git service, for example Surrey GitLab and GitHub, also see Using SSH Keys with Git Services.