Difference between revisions of "Using SSH Keys To Access HPG"

From UFRC
Jump to navigation Jump to search
 
(55 intermediate revisions by 4 users not shown)
Line 1: Line 1:
=DRAFT=
+
__NOTOC__ [[Category:Essentials]]
This is work in progress. Please provide feedback using the 'Discussion tab.
+
{{Note|'''Never share your private ssh keys''' even with Support staff. Your private ssh key works as your password and it must be kept in a non-shareable space with r/w permissions at the owner level (-rw------- or 600).|warn}}
==Introduction==
 
After a new account is created on HiPerGator (HPG) you as the account's owner can log in using your GatorLink credentials (gatorlink username and password). However, mis-typing the credentials several times will result in a security system block of the user's IP address. For convenience and speed, especially when copying files between HPG and a remote computer system - whether it's a local computer you are connecting from or an external system - using scp or rsync tools or SFTP applications it may be useful to set up a SSH key pair to use instead of GatorLink credentials.
 
  
SSH key pair means there are two keys - a private key is stored in the ~/.ssh/ directory on the system you are connecting from and acts as the identity file (the key part of the lock/key mechanism). Use a good passphrase to protect the private key in case it's accessed by someone else and use an SSH agent to store it, so you only have to type the passphrase in once when starting the computer or the terminal application. A public key gets copied to every system you want to connect to and can be described as a specification for the 'lock' part of the lock/key ssh mechanism to allow the receiving computer connections to your account from a system that uses the private key part of the pair as its identify file.
+
=Introduction=
 +
After a new account is created on HiPerGator (HPG) you, as the account's owner, can log in using your credentials (GatorLink username and password for UF users). Mis-typing the credentials several times will result in a security system block of the user's IP address and can be slow. For convenience and speed, it may be useful to set up a SSH key pair to use. If you're on windows you can accomplish this with Putty instead following the guide at [[Create SSH Keys Using Putty]].
  
The private key is not used automatically, although most systems are configured to use ~/.ssh/id_rsa by default. See how to configure your ssh setup to use the correct private key as the IdentityFile below.
+
SSH key pair means there are two keys:
 +
# A private key is stored in the <code>~/.ssh/</code> directory on the computer you are connecting from
 +
## The '''private''' key acts as the identity file (the key part of the lock/key mechanism).
 +
## Use a good passphrase to protect the private key in case it is accessed by someone else
 +
## Use an SSH agent to store it, so you only have to type the passphrase in once when starting the computer or the terminal application.
 +
# A '''public''' key gets copied to every system you want to connect to and can be described as a specification for the 'lock' part of the lock/key ssh mechanism to allow the receiving computer connections to your account from a system that uses the private key part of the pair as its identify file.
 +
 
 +
The private key is not used automatically, although most systems are configured to use ~/.ssh/id_rsa by default. See how to configure your ssh setup to use the correct private key as the IdentityFile below.  
  
 
=Create SSH Keys=
 
=Create SSH Keys=
==Linux==
+
''Note:'' You can also use a text editor (vi, vscode, etc) in a terminal or a console session in [[Open OnDemand]] to edit ~/.ssh/authorized_keys file. On MacOS these steps can be done using either the built-in MacOS terminal application or [https://iterm2.com/ iTerm2].
For a modern ED25519 cipher  
+
 
* Generate a key
+
'''The default cipher for ssh keys is RSA. However, this no longer recommended as it is less secure. We recommend users to use a ED25519 cipher when generating new keys in HiPerGator.'''
ssh-keygen -o -a 100 -t ed25519 -f ~/.ssh/id_ed25519 -C "Comment to make the key recognizable among many"
+
* Generate a key on Linux/Mac
 +
**<pre>ssh-keygen -o -a 100 -t ed25519 -f ~/.ssh/id_ed25519 -C "Comment to make the key recognizable among many"</pre>
 +
*Generate key from Windows Command Line
 +
**<pre>ssh-keygen -t ed25519 -C "Comment to make the key recognizable among many"</pre>
 +
 
 +
=SSH Keys Permissions=
 +
Learn more about Linux file permissions at (external resource): [https://www.redhat.com/sysadmin/linux-file-permissions-explained Linux File Permissions Explained].
 +
 
 +
SSH requires a certain permission configuration for files in the ~/.ssh path. SSH refuses connection to HPG if the permission of said files doesn't match the expected value, resulting in output such as:
  
* Add the following configuration at the top of the ~/.ssh/config file
 
 
<pre>
 
<pre>
Host *
+
@        WARNING: UNPROTECTED PRIVATE KEY FILE!          @
  AddKeysToAgent yes
+
Permissions (XXXX) for '/home/*******/.ssh/id_rsa' are too open.
  IdentityFile ~/.ssh/id_ed25519
+
It is required that your private key files are NOT accessible by others.
 +
This private key will be ignored.
 +
Load key "/home/******/.ssh/id_rsa": bad permissions
 +
"******@hpg.rc.ufl.edu": Permission denied (publickey).
 +
Your connection to the remote server has been terminated.
 
</pre>
 
</pre>
  
* Configure your account on HiPerGator to accept the key instead of the username/password. Substitute your real username for 'USER':
+
If you're having issues with SSH, try accessing HPG using [[Open OnDemand]]'s console and ensure that your files are set as follows:
ssh-copy-id ~/.ssh/id_ed25519 USER@hpg.rc.ufl.edu
+
<pre>
 
+
    [$USER@login12~]$ ls -la ~/.ssh
For an RSA key
+
    ...
* ssh-keygen -o -t rsa -b 4096 -f ~/.ssh/id_rsa
+
    -rw-r--r--  1 ... authorized_keys
ssh-add -K ~/.ssh/id_rsa
+
    -rw-------  1 ... id_ed25519
Edit ~/.ssh/config and add
+
    -rw-r--r-- 1 ... id_ed25519.pub
 +
    -rw------- 1 ... known_hosts
 +
</pre>
 +
If your permission configuration looks different, run the <code>chmod</code> command to adjust the permissions. I.e.:
 
<pre>
 
<pre>
Host *
+
    [$USER@login12~]$ chmod 644 authorized_keys
  AddKeysToAgent yes
 
  IdentityFile ~/.ssh/id_rsa
 
 
</pre>
 
</pre>
 +
Where:
  
* Configure your account on HiPerGator to accept the key instead of the username/password. Substitute your real username for 'USER':
+
644 = -rw-r--r--
ssh-copy-id ~/.ssh/id_rsa USER@hpg.rc.ufl.edu
 
  
The default cipher for ssh keys is RSA. However, key length less than 4096 should not be used for better security.
+
600 = -rw-------
  
==MacOS==
 
The procedure is mostly the same as on Linux when using either the built-in MacOS terminal application or [https://iterm2.com/ iTerm2].
 
  
For a modern ED25519 cipher
+
It is also recommended to check the permissions on the .ssh directory as well:
* Generate a key
+
<pre>
ssh-keygen -o -a 100 -t ed25519 -f ~/.ssh/id_ed25519 -C "Comment to make the key recognizable among many"
+
[$USER@login12 ~]$ chmod 650 /home/$USER/.ssh
 +
</pre>
 +
If your ~/.ssh directory is missing the "authorized_keys" file, you should create it and populated with the contents of your public (<code>$ cat ~/.ssh/id_ed25519.pub</code>) either by copy/paste or <code>$ cat ~/.ssh/id_ed25519.pub > authorized_keys</code>.
  
* Add the following configuration to ~/.ssh/config file
+
=SSH Configuration=
 +
* Add the following configuration at the top of the ~/.ssh/config file.
 
<pre>
 
<pre>
 
Host *
 
Host *
 
   AddKeysToAgent yes
 
   AddKeysToAgent yes
  UseKeychain yes
 
 
   IdentityFile ~/.ssh/id_ed25519
 
   IdentityFile ~/.ssh/id_ed25519
 
</pre>
 
</pre>
 +
* If you're on Mac, add new line with
 +
**<pre>UseKeychain yes</pre>
  
For an RSA key
+
* If you're on Mac/ Linux, add the following under the previous text in config, but replace your username in the <code>User</code> line. A convenient configuration for your ssh '''client''' on your local computer. In all commands below you can now use 'hpg' instead of USER@hpg.rc.ufl.edu. If you would like to use multiplexing, consider following the guide at [[SSH Multiplexing]]
* ssh-keygen -o -t rsa -b 4096 -f ~/.ssh/id_rsa
+
* Windows users only need to add port 2222 to the config they added at setup, but can paste it all if that was not done.  
ssh-add -K ~/.ssh/id_rsa
 
Edit ~/.ssh/config and add
 
 
<pre>
 
<pre>
Host *
+
Host hpg
  AddKeysToAgent yes
+
    User albertgator
  UseKeychain yes
+
    HostName hpg.rc.ufl.edu
  IdentityFile ~/.ssh/id_rsa
+
    Port 2222
 +
    ControlPath ~/.ssh/cm-%r@%l-%h:%p
 +
    ControlMaster auto
 
</pre>
 
</pre>
  
* Configure your account on HiPerGator to accept the key instead of the username/password. Substitute your real username for 'USER':
+
=Enable Key Access on HPG=
ssh-copy-id ~/.ssh/id_rsa USER@hpg.rc.ufl.edu
+
Configure your account on HiPerGator to accept the key instead of the username/password. If you are already logged in you can manually edit the ~/.ssh/authorized_keys file and add the new '''public''' ssh key.
 +
 
 +
*Alternatively on Mac or Linux, you can type the following command on your local computer, replacing your username for USER.
 +
**<pre>ssh-copy-id -i ~/.ssh/id_ed25519 USER@hpg.rc.ufl.edu</pre>
 +
*In order to enable key-based login to HPG on Windows, you will need to copy the public key content into your authorized_keys file on HPG. To do this you will need to SSH as explain in [[Getting Started#Interfaces|Intefaces]]. From the hpg terminal, type the following to edit your authorized_keys file. ''Note:'' You can also use a text editor in a terminal or a console session in [[Open OnDemand]] to edit ~/.ssh/authorized_keys file.
 +
**<pre>nano $HOME/.ssh/authorized_keys</pre>
 +
*There will likely already be entries for keys that were generated for your account automatically. Please select copy the data from your locally generated key file in .ssh folder.  Use the arrow keys to navigate to the bottom of the list in the authorized_keys file and paste the data using right click. After you have pasted the information in the file, press the <code>CTRL</code> and <code>o</code> keys at the same time followed by <code>Enter</code> to write out the file. Then press the <code>CTRL</code> and <code>x</code> keys at the same time to exit the editor.<br />
 +
 
 +
Congratulations your key is now authorized to login to your account on HPG.
  
 +
=SSH to HPG Using SSH Keys=
 +
To SSH into HPG using SSH keys use the following command: <code>ssh -p 2222 username@hpg.rc.ufl.edu</code>
  
==Windows==
+
;Note: '''Federated users must use the default port 22 with ssh key authentication. If you are a federated user do not specify the port in your command.
See the following document that describes how to [[Create SSH keys on Windows]].
 

Latest revision as of 15:46, 1 August 2024

Never share your private ssh keys even with Support staff. Your private ssh key works as your password and it must be kept in a non-shareable space with r/w permissions at the owner level (-rw------- or 600).

Introduction

After a new account is created on HiPerGator (HPG) you, as the account's owner, can log in using your credentials (GatorLink username and password for UF users). Mis-typing the credentials several times will result in a security system block of the user's IP address and can be slow. For convenience and speed, it may be useful to set up a SSH key pair to use. If you're on windows you can accomplish this with Putty instead following the guide at Create SSH Keys Using Putty.

SSH key pair means there are two keys:

  1. A private key is stored in the ~/.ssh/ directory on the computer you are connecting from
    1. The private key acts as the identity file (the key part of the lock/key mechanism).
    2. Use a good passphrase to protect the private key in case it is accessed by someone else
    3. Use an SSH agent to store it, so you only have to type the passphrase in once when starting the computer or the terminal application.
  2. A public key gets copied to every system you want to connect to and can be described as a specification for the 'lock' part of the lock/key ssh mechanism to allow the receiving computer connections to your account from a system that uses the private key part of the pair as its identify file.

The private key is not used automatically, although most systems are configured to use ~/.ssh/id_rsa by default. See how to configure your ssh setup to use the correct private key as the IdentityFile below.

Create SSH Keys

Note: You can also use a text editor (vi, vscode, etc) in a terminal or a console session in Open OnDemand to edit ~/.ssh/authorized_keys file. On MacOS these steps can be done using either the built-in MacOS terminal application or iTerm2.

The default cipher for ssh keys is RSA. However, this no longer recommended as it is less secure. We recommend users to use a ED25519 cipher when generating new keys in HiPerGator.

  • Generate a key on Linux/Mac
    • ssh-keygen -o -a 100 -t ed25519 -f ~/.ssh/id_ed25519 -C "Comment to make the key recognizable among many"
  • Generate key from Windows Command Line
    • ssh-keygen -t ed25519 -C "Comment to make the key recognizable among many"

SSH Keys Permissions

Learn more about Linux file permissions at (external resource): Linux File Permissions Explained.

SSH requires a certain permission configuration for files in the ~/.ssh path. SSH refuses connection to HPG if the permission of said files doesn't match the expected value, resulting in output such as:

@         WARNING: UNPROTECTED PRIVATE KEY FILE!          @
Permissions (XXXX) for '/home/*******/.ssh/id_rsa' are too open.
It is required that your private key files are NOT accessible by others.
This private key will be ignored.
Load key "/home/******/.ssh/id_rsa": bad permissions
"******@hpg.rc.ufl.edu": Permission denied (publickey).
Your connection to the remote server has been terminated.

If you're having issues with SSH, try accessing HPG using Open OnDemand's console and ensure that your files are set as follows:

    [$USER@login12~]$ ls -la ~/.ssh
    ...
    -rw-r--r--  1 ... authorized_keys
    -rw-------  1 ... id_ed25519
    -rw-r--r--  1 ... id_ed25519.pub
    -rw-------  1 ... known_hosts

If your permission configuration looks different, run the chmod command to adjust the permissions. I.e.:

    [$USER@login12~]$ chmod 644 authorized_keys

Where:

644 = -rw-r--r--

600 = -rw-------


It is also recommended to check the permissions on the .ssh directory as well:

[$USER@login12 ~]$ chmod 650 /home/$USER/.ssh

If your ~/.ssh directory is missing the "authorized_keys" file, you should create it and populated with the contents of your public ($ cat ~/.ssh/id_ed25519.pub) either by copy/paste or $ cat ~/.ssh/id_ed25519.pub > authorized_keys.

SSH Configuration

  • Add the following configuration at the top of the ~/.ssh/config file.
Host *
  AddKeysToAgent yes
  IdentityFile ~/.ssh/id_ed25519
  • If you're on Mac, add new line with
    • UseKeychain yes
  • If you're on Mac/ Linux, add the following under the previous text in config, but replace your username in the User line. A convenient configuration for your ssh client on your local computer. In all commands below you can now use 'hpg' instead of USER@hpg.rc.ufl.edu. If you would like to use multiplexing, consider following the guide at SSH Multiplexing
  • Windows users only need to add port 2222 to the config they added at setup, but can paste it all if that was not done.
Host hpg
    User albertgator
    HostName hpg.rc.ufl.edu
    Port 2222
    ControlPath ~/.ssh/cm-%r@%l-%h:%p
    ControlMaster auto

Enable Key Access on HPG

Configure your account on HiPerGator to accept the key instead of the username/password. If you are already logged in you can manually edit the ~/.ssh/authorized_keys file and add the new public ssh key.

  • Alternatively on Mac or Linux, you can type the following command on your local computer, replacing your username for USER.
    • ssh-copy-id -i ~/.ssh/id_ed25519 USER@hpg.rc.ufl.edu
  • In order to enable key-based login to HPG on Windows, you will need to copy the public key content into your authorized_keys file on HPG. To do this you will need to SSH as explain in Intefaces. From the hpg terminal, type the following to edit your authorized_keys file. Note: You can also use a text editor in a terminal or a console session in Open OnDemand to edit ~/.ssh/authorized_keys file.
    • nano $HOME/.ssh/authorized_keys
  • There will likely already be entries for keys that were generated for your account automatically. Please select copy the data from your locally generated key file in .ssh folder. Use the arrow keys to navigate to the bottom of the list in the authorized_keys file and paste the data using right click. After you have pasted the information in the file, press the CTRL and o keys at the same time followed by Enter to write out the file. Then press the CTRL and x keys at the same time to exit the editor.

Congratulations your key is now authorized to login to your account on HPG.

SSH to HPG Using SSH Keys

To SSH into HPG using SSH keys use the following command: ssh -p 2222 username@hpg.rc.ufl.edu

Note
Federated users must use the default port 22 with ssh key authentication. If you are a federated user do not specify the port in your command.