.. _ssh-key-setup: 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 :ref:`GlobalProtect VPN`. .. tab-set:: .. tab-item:: Linux / macOS 1. **Open a Terminal** Open your favourite terminal application. 2. **Generate the SSH Key** Type the following command to generate an Ed25519 key: .. code-block:: bash 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. 3. **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: .. code-block:: bash eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519_costar 4. **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--``. .. code-block:: bash 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. 5. **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. .. code-block:: bash 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): .. code-block:: text 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. .. tab-item:: Windows 1. **Open PowerShell or Command Prompt** Open PowerShell or Command Prompt. 2. **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. 3. **Generate the SSH Key** Use the following command to generate an Ed25519 key: .. code-block:: batch 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. 4. **Add the SSH Key to the local SSH Agent** Start the SSH agent and add your new key, for example: .. code-block:: batch 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. 5. **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. 6. **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. .. code-block:: batch 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. 7. **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. .. code-block:: batch notepad $env:USERPROFILE\.ssh\config If applicable, add the following configuration: .. code-block:: text 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 :ref:`ssh-key-deploy` page to learn how to deploy the keys to authenticate against the SSH gateway, the CoSTAR cluster, or GitLab and GitHub.