.. _ssh-key-intro:

SSH Keys
========


Introduction
------------

Using **SSH** (secure shell) cryptographic keys instead of passwords for authentication offers several advantages:

* **Enhanced Security**:
    Cryptographic keys provide a more secure authentication method. Unlike passwords, which can be guessed or brute-forced, cryptographic keys are nearly impossible to crack.

* **Convenience**:
    Once set up, SSH keys simplify the login process. When used with SSH agents or keychain tools that cache your passphrase, you can enjoy password-less logins after the initial use.

* **Gitlab Access**:
    Some source code repositories, e.g., certain GitLab instances, do not allow password authentication for cloning repositories or pushing changes. SSH keys offer a more convenient and secure alternative to short-lived tokens.


What can I use SSH Keys for?
----------------------------

Once configured, your SSH keys can provide secure access to:

- **HPC Clusters**: Such as the CoSTAR cluster as well as other compute systems (if you have been granted access)
- **SSH Gateway**:  Central access point for multiple systems, in case you cannot used the GlobalProtect VPN
- **GitLab & GitHub**: Version control for your code and research projects



How does SSH work?
------------------

The generated SSH keys consist of two elements, both of which are files stored on computers:

* **Public key**:
    This key is distributed to the systems you wish to log in to. It is considered safe to share, as it cannot be used to gain unauthorised access.
* **Private key**:
    This key remains securely on the system from which you connect. If stolen, it is compromised, and both the private and public keys must be replaced. To prevent unauthorised use, the private key should always be protected by a passphrase.

When you attempt to authenticate, the private key on your system is used to sign a challenge, which the remote system verifies against the corresponding public key, granting access if they match.
Learn more about the underlying technology `here <https://en.wikipedia.org/wiki/Public-key_cryptography>`__.


Setup Guide: Your Next Steps
----------------------------

Setting up SSH keys two-step process. Follow the guides below to get started:

.. grid:: 1 2 2 2
   :gutter: 3
   :margin: 3

   .. grid-item-card:: :octicon:`key` Step 1: Generate your Keys
      :link: generate_keys
      :link-type: doc

      Learn how to create a secure Public and Private key pair on your local Linux, Mac, or Windows computer.

   .. grid-item-card:: :octicon:`server` Step 2: Deploy your Keys
      :link: deploy_keys
      :link-type: doc

      Learn how to safely copy your Public key to the CoSTAR cluster so the system recognizes you automatically.


.. toctree::
   :hidden:

   generate_keys
   deploy_keys