Changes

Page history
Update Documentation.md authored by Lion Rexhepi's avatar Lion Rexhepi
Show whitespace changes
Inline Side-by-side
Documentation.md
View page @ 1be0c89d
...@@ -66,6 +66,8 @@ If you own a [YubiKey](https://en.wikipedia.org/wiki/YubiKey) hardware token, yo ...@@ -66,6 +66,8 @@ If you own a [YubiKey](https://en.wikipedia.org/wiki/YubiKey) hardware token, yo
### 2.2 SSH access, keys and things ### 2.2 SSH access, keys and things
To
Quick summary, if you just need a reminder: Quick summary, if you just need a reminder:
| Command | Description | | Command | Description |
...@@ -80,9 +82,42 @@ Quick summary, if you just need a reminder: ...@@ -80,9 +82,42 @@ Quick summary, if you just need a reminder:
Please keep reading if you require more details. Please keep reading if you require more details.
An SSH key pair always consists of a private key (as in **private - don't share, don't give away**) and a public key. As with physical keys, one does not want to share private keys or leave their copies in other locations/computers. Instead, we recommend to create a new SSH key pair on each frequently-used host. Let's outline a **3-step procedure** to get you "keyed-in". An SSH key pair always consists of a private key (as in **private - don't share, don't give away**) and a public key. As with physical keys, one does not want to share private keys or leave their copies in other locations/computers. Instead, we recommend to create a new SSH key pair on each frequently-used host. As for Ramses, you will need to log into our dedicated [Ramses key upload website](https://ramses-umc.itcc.uni-koeln.de/web-sshkey/login) to set up SSH authentication. Once you log in, you have two options on how to proceed: Using our `web-sshkey` helper interface to generate a key pair and downloading the private key or uploading the public part of a key pair you generated yourself. Unless you frequently use SSH and are confident using `ssh-keygen` from the command line, we recommend the former.
**IMPORTANT NOTE**: Both generation and upload are only accessible within the UKLAN, either be on premise or use Cisco VPN. The website is not accessible from the Internet!
#### 2.2.1 Using the `web-sshkey-gen` interface
To make setting up a key pair on Ramses easier for first-time users, we provide a web interface that allows you to generate password-protected [elliptic-curve](https://blog.cloudflare.com/a-relatively-easy-to-understand-primer-on-elliptic-curve-cryptography/) based SSH key pairs **locally and entirely on your machine** using the [Web Cryptography APIs](https://en.wikipedia.org/wiki/Web_Cryptography_API) available in all modern web browsers.
##### 2.2.1.1 Generating a key pair
To generate a key using `web-sshkey-gen`, all you need to do is enter the desired passphrase, confirm it, and enter a comment which acts like a "name" making it easier to identify the generated key. Note that while the form enforces some degree of complexity for your passphrase, such as a minimum length, choosing one that is actually secure is your responsibility; You may want to use passphrase generator such as [this one](https://www.tu-braunschweig.de/it-sicherheit/pwsec/pwgen) to make it easier to generate a unique passphrase.
Once you have confirmed that you have stored the passphrase securely, you can hit "Generate". After a few seconds, you will be presented with the private half of the generated key pair. Download the file containing the key and confirm that the download was successful. After you have done so, all that is left to do is to click the "Upload Public Key" button – the public half of the generated key pair will be uploaded to Ramses and added to your account automatically, with no further action required from your side.
##### 2.2.1.2 Using the generated private key
After you have finished generating a key pair, you will need to perform some additional steps on your machine to be able to access Ramses. These steps differ depending on the operating system and SSH client you use. Generally, we recommend you use OpenSSH, as it comes preinstalled on Windows, MacOS and all major Linux distributions, having established itself as the _de facto_ standard. However, since GUI tools like PuTTY are still quite popular, there are also instructions below on how to import the generated keys there.
##### 2.2.1.3 Using your key with OpenSSH (recommended)
Since `web-sshkey-gen` produces private keys in OpenSSH's own `v2` format by default, no conversion between formats is necessary. First, copy the file containing the private key, usually called `id_ed25519_ramses` or similar, into the directory `~/.ssh` or `%USERPROFILE\.ssh`, creating the directory if it is not already present. Afterwards, you need to modify the file's permissions so that you are the only user allowed to access the file, or OpenSSH will refuse to load your key.
On MacOS/Linux, you can do this from the command line by running `chmod 600 <path-to-key-file>`. On Windows, the process is a bit more intricate:
1. Right-Click the file in Explorer, select **Properties**, then **Security**, then **Advanced**.
2. Click on **Disable inheritance**. When asked, choose to remove all inherited permissions from the file. Click **Apply**.
3. Back in the **Security** tab, click on **Edit**, then **Add**. Enter your device name, followed by your user name (e.g. `LAPTOP-12345\jdoe`) and confirm your changes.
#### 2.2.1 Step 1: Generate authentication keys: `ssh-keygen` ##### 2.2.1.4 Using your key with PuTTY/WinSCP
As **PuTTY** uses a different file format to store private keys, you will need to convert your private key first. To do this, open PuTTYgen, which is installed automatically alongside PuTTY, click on the button next to "Load an existing private key file", and select the private key file you downloaded from `web-sshkey-gen`. Enter your key's passphrase to decrypt it, then click on "Save" to export the key in PuTTYs `.ppk` format.
_**Note:** Unlike OpenSSH, PuTTY does not place any restrictions on file permissions. However, it is still good practice to read-protect your private key file(s) as described in the section above._
Now, you can start PuTTY and specify the private key under **Connection > SSH > Auth > Credentials > Select private key file**. After you are finished configuring the session, you can save the connection to avoid having to repeat this process every time you want to connect to Ramses.
**WinSCP** is primarily used alongside PuTTY to transfer files and thus uses the same `.ppk` format as PuTTY does. To configure your connection to use the private key, first change the connection type from `SFTP` to `SCP`. Then, under **SSH > Authentication > Private Key File**, select the private key `.ppk` file. If you only want to use WinSCP without PuTTY, you can also change the file mask from "PuTTY private key files" to "All private key files" and WinSCP will offer to do the conversion to `.ppk` for you.
#### 2.2.2 Manually Generating a SSH keypair
##### 2.2.2.1 Generate authentication keys: `ssh-keygen`
``` ```
ssh-keygen -t ed25519 -C "<YOUR NAME>" ssh-keygen -t ed25519 -C "<YOUR NAME>"
``` ```
...@@ -119,12 +154,10 @@ You will now find the key pair in the hidden `.ssh` directory of your home as fi ...@@ -119,12 +154,10 @@ You will now find the key pair in the hidden `.ssh` directory of your home as fi
##### (on Windows: you can also use [PuTTY](PuTTY-key-generator) ) ##### (on Windows: you can also use [PuTTY](PuTTY-key-generator) )
#### 2.2.2 Step 2: Transfer the public key to Ramses ##### 2.2.2.2 Transfer the public key to Ramses
The newly generated SSH public key needs to be transferred to your Ramses home directory. The newly generated SSH public key needs to be transferred to your Ramses home directory.
To this end, we have set up a dedicated [Ramses key upload website](https://ramses-umc.itcc.uni-koeln.de/web-sshkey/login). To this end, we have set up a dedicated [Ramses key upload website](https://ramses-umc.itcc.uni-koeln.de/web-sshkey/login).
**IMPORTANT NOTE**: The website is only accessible within the UKLAN, either be on premise or use Cisco VPN. It is not accessible from the Internet!
Log in with your uniKIM credentials (username and password) and upload your public key. It will then be installed in your `~/.ssh/authorized_keys` file on Ramses and enable SSH authentication without a password request when used with your matching private key on the local host. Log in with your uniKIM credentials (username and password) and upload your public key. It will then be installed in your `~/.ssh/authorized_keys` file on Ramses and enable SSH authentication without a password request when used with your matching private key on the local host.
In case key upload to the website is not possible, you can send it to us (hpc-mgr@uni-koeln.de) as an email attachment or by copy-paste of the public key file contents: In case key upload to the website is not possible, you can send it to us (hpc-mgr@uni-koeln.de) as an email attachment or by copy-paste of the public key file contents:
...@@ -132,17 +165,24 @@ In case key upload to the website is not possible, you can send it to us (hpc-mg ...@@ -132,17 +165,24 @@ In case key upload to the website is not possible, you can send it to us (hpc-mg
`cat ~/.ssh/id_ed25519.pub` `cat ~/.ssh/id_ed25519.pub`
#### 2.2.3 Step 3 (optional): Wanna pass on the passphrase? - Call your agent! #### 2.2.3 (optional): Wanna pass on the passphrase? - Call your agent!
`ssh-agent` is a program which can automatically do your authentication when logging in to a remote machine via SSH. Thus, to avoid providing the passphrase during multiple subsequent sessions, you can load the private key into memory using the SSH agent. `ssh-agent` is a program which can automatically do your authentication when logging in to a remote machine via SSH. Thus, to avoid providing the passphrase during multiple subsequent sessions, you can load the private key into memory using the SSH agent.
First, check if your agent is at home by typing First, check if your agent is at home by typing
``` ```
ssh-add -l # with `-l` as in "list" ssh-add -l # with `-l` as in "list"
``` ```
This will list all identities currently represented by the agent. Think of "identity" as an SSH key that you want to add to the SSH authentication agent. If you see the message `"Could not open a connection to your authentication agent"`, you need to activate the agent first: This will list all identities currently represented by the agent. Think of "identity" as an SSH key that you want to add to the SSH authentication agent. If you see the message `"Could not open a connection to your authentication agent"`, you need to activate the agent first. On Linux and MacOS, this is fairly simple:
``` ```
eval "$(ssh-agent -s)" eval "$(ssh-agent -s)"
``` ```
On Windows, you sadly need **Administrator Privileges** to be able to activate the `ssh-agent` service, which is done in PowerShell:
```ps
Set-Service ssh-agent -StartupType Automatic # Configure ssh-agent to start automatically on boot
Start-Service ssh-agent
```
When the agent is active, you may see a listing of identities, and you're good to go if your Ramses key is part of it. However, if you see a message like `"This agent has no identities"`, your key still needs to be added: When the agent is active, you may see a listing of identities, and you're good to go if your Ramses key is part of it. However, if you see a message like `"This agent has no identities"`, your key still needs to be added:
``` ```
ssh-add ~/.ssh/id_ed25519 # supply your private-key, may also be ~/.ssh/id_rsa ssh-add ~/.ssh/id_ed25519 # supply your private-key, may also be ~/.ssh/id_rsa
... ...
......