generate SSH keys & use agent as a group

Author: tkphd

_episodes/12-cluster.md

@@ -86,46 +86,233 @@ something like `ssh userName@hostname`, where the argument is just like an
 email address: the "@" symbol is used to separate the personal ID from the
 address of the shared resource.
 
-> ## Setup Revisited
+When logging in to a laptop, tablet, or other personal device, a username,
+password, or pattern are normally required to prevent unauthorized access. In
+these situations, the likelihood of somebody else intercepting your password is
+low, since logging your keystrokes requires a malicious exploit or physical
+access. For systems like {{ site.remote.host }} running an SSH server, anybody
+on the network can log in, or try to. Since usernames are often public or easy
+to guess, your password is often the weakest link in the security chain. Many
+clusters therefore forbid password-based login, requiring instead that you
+generate and configure a public-private key pair with a much stronger password.
+Even if your cluster does not require it, the next section will guide you
+through the use of SSH keys and an SSH agent to both strengthen your security
+*and* make it more convenient to log in to remote systems.
+
+### Better Security With SSH Keys
+
+The [Lesson Setup]({{ page.root }}/setup) provides instructions for
+installing a [shell application][setup-shell] with [SSH][setup-ssh].
+If you have not done so already, please open that shell application with a
+Unix-like command line interface to your system.
+
+SSH keys are an alternative method for authentication to obtain access to
+remote computing systems. They can also be used for authentication when
+transferring files or for accessing version control systems. In this section
+you will create a pair of SSH keys:
+
+* a private key which you keep on your own computer, and
+* a public key which is placed on any remote system you will access.
+
+> ## Private keys are your secure digital passport
 >
-> The [Lesson Setup]({{ page.root }}/setup) provides instructions for
-> installing a [shell application][setup-shell] with [SSH][setup-ssh],
-> generating your [public-private key pair][setup-keys], and
-> installing the [SSH agent][setup-agent].
+> A private key that is visible to anyone but you should be considered
+> compromised, and must be destroyed. This includes having improper permissions
+> on the directory it (or a copy) is stored in, traversing any network that is
+> not secure (encrypted), attachment on unencrypted email, and even displaying
+> the key on your terminal window.
 >
-> If you have not completed Setup already, please do the following;
-> skip any steps you have already completed:
->
-> 1. Open your terminal application.
-> 2. Generate a public-private key pair using the 255-bit EdDSA
->    algorithm and 100 rounds of hashing:
->    ```
->    {{ site.local.prompt }} ssh-keygen -t ed25519 -a 100
->    # accept default location; enter a strong password
->    ```
->    {: .language-bash}
-> 3. Check the SSH Agent by attempting to list the keys it knows about:
->    ```
->    {{ site.local.prompt }} ssh-add -l
->    ```
->    {: .language-bash}
->    1. *Iff* this returns an error because the agent cannot be
->    found, launch the SSH Agent as a background process:
->       ```
->       {{ site.local.prompt }} eval $(ssh-agent)
->       ```
->       {: .language-bash}
-> 4. Register your private key (assuming it resides at `~/.ssh/id_ed25519`)
->    with the agent:
->    ```
->    {{ site.local.prompt }} ssh-add -t 8h ~/.ssh/id_ed25519
->    ```
->    {: .language-bash}
+> Protect this key as if it unlocks your front door. In many ways, it does.
+{: .caution}
+
+#### SSH Keys on Linux, Mac, MobaXterm, and Windows Subsystem for Linux
+
+Once you have opened a terminal, check for existing SSH keys and filenames
+since existing SSH keys are overwritten.
+
+```
+{{ site.local.prompt }} ls ~/.ssh/
+```
+{: .language-bash}
+
+If `~/.ssh/id_ed25519` already exists, you will need to specify
+choose a different name for the new key-pair.
+
+Generate a new public-private key pair using the following command, which will
+produce a stronger key than the `ssh-keygen` default by invoking these flags:
+
+* `-a` (default is 16): number of rounds of passphrase derivation; increase to
+  slow down brute force attacks.
+* `-t` (default is [rsa][wiki-rsa]): specify the "type" or cryptographic
+  algorithm. `ed25519` specifies [EdDSA][wiki-dsa] with a 256-bit key;
+  it is faster than RSA with a comparable strength.
+* `-f` (default is /home/user/.ssh/id_algorithm): filename to store your
+  private key. The public key will be identical, with a `.pub` extension added.
+
+```
+{{ site.local.prompt }} ssh-keygen -a 100 -f ~/.ssh/id_ed25519 -t ed25519
+```
+{: .language-bash}
+
+When prompted, enter a strong password that you will remember. There are two
+common approaches to this:
+
+1. Create a memorable passphrase with some punctuation and number-for-letter
+   substitutions, 32 characters or longer. Street addresses work well; just be
+   careful of social engineering or public records attacks.
+2. Use a password manager and its built-in password generator with all
+   character classes, 25 characters or longer. KeePass and BitWarden are two
+   good options.
+
+Note that the terminal will not appear to change while you type the password:
+this is deliberate, for your security. You will be prompted to type it again,
+so don't worry too much about typos.
+
+Take a look in `~/.ssh` (use `ls ~/.ssh`). You should see two new files:
+
+* your private key (`~/.ssh/id_ed25519`): *do not share with anyone!*
+* the shareable public key (`~/.ssh/id_ed25519.pub`): if a system administrator
+  asks for a key, this is the one to send. It is also safe to upload to
+  websites such as GitHub: it is meant to be seen.
+
+> ## No Empty Passwords
 >
-> You can now use your strong SSH key to log in to remote machines and, for the
-> next 8 hours, you will not have to type your password to do so: the SSH Agent
-> handles it for you.
-{: .callout}
+> Nothing is *less* secure than a private key with no password. If you skipped
+> password entry by accident, go back and generate a new key pair *with* a
+> strong password.
+{: .error}
+
+##### Use RSA for Older Systems
+
+If key generation failed because ed25519 is not available, try using the older
+(but still strong and trustworthy) [RSA][wiki-rsa] cryptosystem. Again, first
+check for an existing key:
+
+```
+{{ site.local.prompt }} ls ~/.ssh/
+```
+{: .language-bash}
+
+If `~/.ssh/id_rsa` already exists, you will need to specify choose a different
+name for the new key-pair. Generate it as above, with the following extra flags:
+
+* `-b` sets the number of bits in the key. The default is 2048.
+  EdDSA uses a fixed key length, so this flag would have no effect.
+* `-o` (no default): use the OpenSSH key format,
+  rather than PEM.
+
+```
+{{ site.local.prompt }} ssh-keygen -a 100 -b 4096 -f ~/.ssh/id_rsa -o -t rsa
+```
+{: .language-bash}
+
+When prompted, enter a strong password that you will remember. There are two
+common approaches to this:
+
+1. Create a memorable passphrase with some punctuation and number-for-letter
+   substitutions, 32 characters or longer. Street addresses work well; just be
+   careful of social engineering or public records attacks.
+2. Use a password manager and its built-in password generator with all
+   character classes, 25 characters or longer. KeePass and BitWarden are two
+   good options.
+
+Take a look in `~/.ssh` (use `ls ~/.ssh`). You should see two new files:
+
+* your private key (`~/.ssh/id_ed25519`): *do not share with anyone!*
+* the shareable public key (`~/.ssh/id_ed25519.pub`): if a system administrator
+  asks for a key, this is the one to send. It is also safe to upload to
+  websites such as GitHub: it is meant to be seen.
+
+#### SSH Keys on PuTTY
+
+If you are using PuTTY on Windows, download and use `puttygen` to generate the
+key pair. See the [PuTTY documentation][putty-gen] for details.
+
+* Select `EdDSA` as the key type.
+* Select `255` as the key size or strength.
+* Click on the "Generate" button.
+* You do not need to enter a comment.
+* When prompted, enter a strong password that you will remember. There are two
+  common approaches to this:
+
+1. Create a memorable passphrase with some punctuation and number-for-letter
+   substitutions, 32 characters or longer. Street addresses work well; just be
+   careful of social engineering or public records attacks.
+2. Use a password manager and its built-in password generator with all
+   character classes, 25 characters or longer. KeePass and BitWarden are two
+   good options.
+
+* Save the keys in a folder no other users of the system can read.
+
+Take a look in the folder you specified. You should see two new files:
+
+* your private key (`id_ed25519`): *do not share with anyone!*
+* the shareable public key (`id_ed25519.pub`): if a system administrator
+  asks for a key, this is the one to send. It is also safe to upload to
+  websites such as GitHub: it is meant to be seen.
+
+## SSH Agent for Easier Key Handling
+
+An SSH key is only as strong as the password used to unlock it, but on the
+other hand, typing out a complex password every time you connect to a machine
+is tedious and gets old very fast. This is where the [SSH Agent][ssh-agent]
+comes in.
+
+Using an SSH Agent, you can type your password for the private key once, then
+have the Agent remember for some number of hours or until you log off. Unless
+some nefarious actor has physical access to your machine, this keeps the
+password safe, and removes the tedium of entering the password multiple times.
+
+Just remember your password, because once it expires in the Agent, you have to
+type it in again.
+
+### SSH Agents on Linux, macOS, and Windows
+
+Open your terminal application and check if an agent is running:
+
+```
+{{ site.local.prompt }} ssh-add -l
+```
+{: .language-bash}
+
+* If you get an error like this one,
+
+  ```
+  Error connecting to agent: No such file or directory
+  ```
+  {: .error}
+
+  ... then you need to launch the agent *as a background process*.
+
+  ```
+  {{ site.local.prompt }} eval $(ssh-agent)
+  ```
+  {: .language-bash}
+
+* Otherwise, your agent is already running: don't mess with it.
+
+Add your key to the agent, with session expiration after 8 hours:
+
+```
+{{ site.local.prompt }} ssh-add -t 8h ~/.ssh/id_ed25519
+```
+{: .language-bash}
+```
+Enter passphrase for .ssh/id_ed25519: 
+Identity added: .ssh/id_ed25519
+Lifetime set to 86400 seconds
+```
+{: .output}
+
+For the duration (8 hours), whenever you use that key, the SSH Agent will
+provide the key on your behalf without you having to type a single keystroke.
+
+### SSH Agent on PuTTY
+
+If you are using PuTTY on Windows, download and use `pageant` as the SSH agent.
+See the [PuTTY documentation][putty-agent].
+
+### Log in
 
 Go ahead and open your terminal or graphical SSH client, then log in to the
 cluster using your username and the remote computer you can reach from the
@@ -144,13 +331,13 @@ Normal output will resume once you press `Enter`.
 You may have noticed that the prompt changed when you logged into the remote
 system using the terminal (if you logged in using PuTTY this will not apply
 because it does not offer a local terminal). This change is important because
-it can help you distinguish on which system the commands you type will be run when you
-pass them into the terminal. This change is also a small complication that we
-will need to navigate throughout the workshop. Exactly what is reported before
-the `$` in the terminal when it is connected to the local system and the remote
-system will typically be different for every user. We still need to indicate
-which system we are entering commands on though so we will adopt the following
-convention:
+it can help you distinguish on which system the commands you type will be run
+when you pass them into the terminal. This change is also a small complication
+that we will need to navigate throughout the workshop. Exactly what is reported
+before the `$` in the terminal when it is connected to the local system and the
+remote system will typically be different for every user. We still need to
+indicate which system we are entering commands on though so we will adopt the
+following convention:
 
 - `{{ site.local.prompt }}` when the command is to be entered on a terminal
   connected to your local computer
@@ -476,7 +663,9 @@ scheduler, and use it to start running our scripts and programs!
 {% include links.md %}
 
 [fshs]: https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard
-[setup-shell]: {{ page.root }}/setup#where-to-type-commands-how-to-open-a-new-shell
-[setup-ssh]: {{ page.root }}/setup#ssh-for-secure-connections
-[setup-keys]: {{ page.root }}/setup#public-private-key-pair-for-ssh
-[setup-agent]: {{ page.root }}/setup#ssh-agent-for-easier-key-handling
+[putty-gen]: https://tartarus.org/~simon/putty-prerel-snapshots/htmldoc/Chapter8.html#pubkey-puttygen
+[putty-agent]: https://tartarus.org/~simon/putty-prerel-snapshots/htmldoc/Chapter9.html#pageant
+[ssh-agent]: https://www.ssh.com/academy/ssh/agent
+[ssh-flags]: https://stribika.github.io/2015/01/04/secure-secure-shell.html
+[wiki-rsa]: https://en.wikipedia.org/wiki/RSA_(cryptosystem)
+[wiki-dsa]: https://en.wikipedia.org/wiki/EdDSA