flesh out ssh key generation docs

This commit is contained in:
Jason Levine 2014-10-06 22:25:35 -04:00
parent 72a7b45bdb
commit 0154efe5e1
1 changed files with 53 additions and 16 deletions

View File

@ -1,29 +1,66 @@
[http://tilde.club](tilde.club) uses `ssh` public-key authentication.
[tilde.club](http://tilde.club) uses `ssh` public-key authentication.
If you want access to [tilde.club](http://tilde.club), create a new key pair with an encrypted key and send the **public** key to the admins.
If you want access to [tilde.club](http://tilde.club), you'll need to create a new SSH key pair and then send the **public** key to the admins; they will then associate it with your account and let you know when things are ready for you to log in.
##Mac
## Mac
1. Open **Terminal** (in /Applications/Utilities).
### Generating your key pair
1. Open **Terminal** (in `/Applications/Utilities/`).
1. In the **Terminal** window, paste the following:
<pre>
mkdir -p ~/.ssh # Create your .ssh directory
ssh-keygen -f ~/.ssh/tilde.club # Create your keys
mkdir -m 700 -p ~/.ssh # Create your .ssh directory
ssh-keygen -t rsa -b 2048 -f ~/.ssh/tilde.club # Create your keys
</pre>
1. The `ssh-keygen` program will generate two new keys (private and public), and prompt you for a password. Please set a good password (at least 9 characters, and not just letters or numbers). Make a note of it somewhere safe.
1. `open ~/.ssh # Open your .ssh directory`
1. Email ford@ (our friendly host) and attach `tilde.club.pub` to the email (it should be visible in the Finder. **Do not** attach `tilde.club` -- that is your *private* key, which you should never share.
1. The `ssh-keygen` program will generate two new keys (private and public), and prompt you for a password. Please set a good password (at least 9 characters, and not just letters or numbers), and make a note of it somewhere safe.
1. Now, in **Terminal**, type: `open ~/.ssh` to open a Finder window showing your `.ssh` directory.
1. Take the `tilde.club.pub` file and attach it to an email to ford@ (our friendly host). **Do not attach the file `tilde.club`** -- that is your *private* key, which you should never ever **ever** share with anyone.
##Linux
### Using your key pair
If you're on Linux you can use the same commands to generate a `tilde.club` keypair, but attaching `tilde.club.pub` is left as an exercise for the reader.
1. Open **Terminal**.
1. type `ssh -i ~/.ssh/tilde.club username@tilde.club` (substituting in your own username)
##Windows
Note that it's possible to save an SSH configuration so that you don't have to type this whole long thing every time; [here's a good primer](http://nerderati.com/2011/03/17/simplify-your-life-with-an-ssh-config-file/) on how to do that.
We need instructions for using `PuTTYgen` to create a key in OpenSSH compatible format.
## Linux
##Why?
### Generating your key pair
`ssh` keys are more secure than classic UNIX passwords. Someone who takes over the server (`sshd` program) can capture the UNIX passwords of everyone who uses them to login -- [this has happened](http://www.apache.org/info/20010519-hack.html).
If you're on Linux you can use the same commands as on the Mac to generate a `tilde.club` key pair, but attaching `tilde.club.pub` is left as an exercise for the reader.
Additionally, if you use an `ssh` agent, you can login without entering a password every time. On OS X the Apple Keychain provides this functionality. On Linux it's `ssh-agent` and possibly [keychain](http://www.funtoo.org/Keychain). On Windows `pageant` provides this capability for [PuTTY](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html).
### Using your key pair
At a command prompt, type `ssh -i ~/.ssh/tilde.club username@tilde.club` (substituting your own username).
Note that it's possible to save an SSH configuration so that you don't have to type this whole long thing every time; [here's a good primer](http://nerderati.com/2011/03/17/simplify-your-life-with-an-ssh-config-file/) on how to do that.
## Windows
### Generating your key pair
The easiest method to generate a key pair on Windows is to use [PuTTY](http://www.chiark.greenend.org.uk/~sgtatham/putty/), a freely-available SSH client which comes with its own key generator.
1. Download PuTTY [here](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html). (Specifically, get the Windows Installer version; if you want to download the binaries individually, you want to make sure you get the PuTTYgen binary which is what generates key pairs.)
1. Run **PuTTYgen**.
1. From the main window, click the **Generate** button; you'll be asked to move the mouse around to generate randomness, which you should do until PuTTYgen tells you that it's generating the key.
1. Once the key pair is generated, click the **Save public key** button, choose a directory you want to save it into, and in the "File name" field, type `tilde.club.pub`. Save the key.
1. Halfway down the main window, type a good password into the "Key passphrase" field (at least 9 characters, and not just letters or numbers), and repeat it in the "Confirm passphrase" field.
1. Click the **Save private key** button, choose the same directory as you did above, type `tilde.club` into the "File name" field, and save the private key.
1. Finally, email the `tilde.club.pub` file to ford@ (our friendly host). **Do not attach the file `tilde.club`** -- that is your *private* key, which you should never ever **ever** share with anyone.
### Using your key pair
1. Run **PuTTY**.
1. In the first window that comes up, you should be in the main "Session" category (in the left-hand column). On the right, in the "Host Name" field, type `tilde.club`.
1. In the left-hand column, find the **SSH** entry underneath the **Connection** section and then click on the small plus sign next to it to open it up; then find the **Auth** entry beneath it and click on it.
1. On the right, the last field should be "Private key file for authentication"; click the **Browse** button and find the `tilde.club` file you saved above. Select it and click the **Open** button.
1. Finally, click the **Open** button at the bottom of the main PuTTY window to open your connection. You'll be asked for your username ("login as:"); type it in and hit Enter. You'll then be asked for your key passphrase; type it in and hit enter, and you're in.
Note that you can save these settings from that first page of the main PuTTY window, so you don't have to do this every time.
## Why go through all this?
One of the weakest links in online account security is your password. If someone were to take over the tilde server (specifically the SSH server, `sshd`), they would be able to capture the passwords of everyone who uses a password to log in. (This isn't theoretical -- [it has actually happened](http://www.apache.org/info/20010519-hack.html).) If users use their SSH keys to log in instead, hackers can't do this anymore; a user's private key never leaves their own computer and can't be captured on the server.
Additionally, if you use an `ssh` agent, you can login without entering a password every time. On OS X the Apple Keychain provides this functionality. On Linux it's `ssh-agent` and possibly [keychain](http://www.funtoo.org/Keychain). On Windows `pageant` provides this capability for [PuTTY](http://www.chiark.greenend.org.uk/~sgtatham/putty/).