Generating SSH Keys¶

This guide will help you set up SSH cryptographic keys for connecting to the SSH gateway, the CoSTAR cluster, and developer platforms such as GitHub or GitLab.

For the purpose of this guide we assume that you are connected to the University of Surrey’s network either directly or via the GlobalProtect VPN.

Linux / macOS

Open a Terminal

Open your favourite terminal application.
Generate the SSH Key

Type the following command to generate an Ed25519 key:
```
ssh-keygen -t ed25519 -C "Enter a meaningful comment here"
```
Follow the prompts to save the key. It is recommended to use the default directory (~/.ssh/) and to choose a filename for the key that indicates its purpose, e.g., id_ed25519_costar, id_ed25519_gateway, or id_ed25519_gitlab.

Note

While SSH keys can be used without a passphrase for convenience, a passphrase should be set for enhanced security.
Add the SSH Key to the local SSH Agent

Enter the following commands to ensure that the SSH agent is running and to add the newly created key, for example:
```
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519_costar
```

Verify File Permissions

The ssh-keygen command should create the default directory if it does not already exist and also set the access permissions on your system correctly, i.e. private files should carry -rw------- and public files can be set to -rw-r--r--.

ls -la ~/.ssh/
...
-rw-------@ 1 ab1234  staff   697 24 Apr 22:59 config
-rw-------@ 1 ab1234  staff   411  4 Mar 12:48 id_ed25519_costar_VPN
-rw-r--r--@ 1 ab1234  staff    99  4 Mar 12:48 id_ed25519_costar_VPN.pub
-rw-------@ 1 ab1234  staff   411 27 Sep  2024 id_ed25519_gateway
-rw-r--r--@ 1 ab1234  staff    96 27 Sep  2024 id_ed25519_gateway.pub
-rw-------@ 1 ab1234  staff   399 12 Feb  2024 id_ed25519_gitlab
-rw-r--r--@ 1 ab1234  staff    95 12 Feb  2024 id_ed25519_gitlab.pub
-rw-------@ 1 ab1234  staff  5583  8 Jul 14:53 known_hosts

See this guide if your permissions do not match and need to be adjusted.

Optional: Configure SSH for Convenience

Use your favourite text editor to create or edit the SSH user config file on your local machine to simplify connections.

nano ~/.ssh/config

Add the following configuration (and change it to reflect your setup, e.g. replace ab1234 with your username and the IdentityFile for your key pair):

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

Host costar
    HostName costar-login01.surrey.ac.uk
    User ab1234
    ForwardAgent yes
    IdentityFile ~/.ssh/id_ed25519_costar

Host gitlab.com
    HostName gitlab.com
    User git
    ForwardAgent yes
    IdentityFile ~/.ssh/id_ed25519_gitlab

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

Save and exit the editor.

Windows

Open PowerShell or Command Prompt

Open PowerShell or Command Prompt.
Install OpenSSH (if not already installed)

Ensure OpenSSH is installed. On Windows 10 and above, the OpenSSH client is installed by default. If it is not, you can install it through the Optional Features setting.
Generate the SSH Key

Use the following command to generate an Ed25519 key:
```
ssh-keygen -t ed25519 -C "Enter a meaningful comment here"
```
Follow the prompts to save the key. It is recommended to use the default file location (C:\Users\YourUsername\.ssh\id_ed25519) and to choose a filename for the key that indicates its purpose, e.g., id_ed25519_costar, id_ed25519_gateway, or id_ed25519_gitlab, etc.

Note

While SSH keys can be used without a passphrase for convenience, it is recommended to set a passphrase for additional security.
Add the SSH Key to the local SSH Agent

Start the SSH agent and add your new key, for example:
```
Start-Service ssh-agent
ssh-add C:\Users\YourUsername\.ssh\id_ed25519_costar
```
Note

Throughout this guide please replace YourUsername with your Windows username, adjust the key names to the names you have chosen, and replace ab1234 with your university username.
Convert SSH Keys for PuTTY / WinSCP (if applicable)

If you are using PuTTY or WinSCP, you will need to convert your SSH key to the .ppk format using PuTTYgen, which is part of the PuTTY suite.
1. Open PuTTYgen: Launch PuTTYgen from the Start menu.
2. Load your private key: Click “Load” and navigate to C:\Users\YourUsername\.ssh\id_ed25519_costar (you may need to change the file type filter to “All Files”).
3. Save the key in `.ppk` format: Once the key is loaded, click “Save private key” and save it as a .ppk file, such as id_ed25519_costar.ppk.
You can now use this .ppk file with PuTTY or WinSCP for logging into the server.
Verify File Permissions

Verify that your private key file has the correct permissions set. In Windows, permissions are handled differently than in Linux, so it is sufficient to ensure that only your user account has access to the .ssh directory and its contents.
```
icacls C:\Users\YourUsername\.ssh\id_ed25519_costar
```
This should return a result that indicates only your user account has access to the keys on your system.

See this guide if your permissions do not match and need to be adjusted.

Optional: Configure SSH for Convenience

You can create or edit the SSH config file on your local machine to simplify connections. Create a file named config in the .ssh directory and change the following to reflect your setup, e.g. replace ab123 with your username, YourUsername with your Windows username, and the IdentityFile for your key pair.

notepad $env:USERPROFILE\.ssh\config

If applicable, add the following configuration:

Host gateway
    HostName access.eps.surrey.ac.uk
    User ab1234
    IdentityFile C:\Users\YourUsername\.ssh\id_ed25519_gateway

Host costar
    HostName costar-login01.surrey.ac.uk
    User ab1234
    IdentityFile C:\Users\YourUsername\.ssh\id_ed25519_costar

Host gitlab.com
    HostName gitlab.com
    User git
    Preferredauthentications publickey
    IdentityFile C:\Users\YourUsername\.ssh\id_ed25519_gitlab

Host github.com
    HostName github.com
    User git
    Preferredauthentications publickey
    IdentityFile C:\Users\YourUsername\.ssh\id_ed25519_github

Save and close the editor.

See the Deploying SSH Keys page to learn how to deploy the keys to authenticate against the SSH gateway, the CoSTAR cluster, or GitLab and GitHub.