How to Configure Public-Key SSH Login to SWARPAnet

Public-key authentication is a moderately easy-to-use authentication mechanism which SSH provides as an alternative to logging in by typing your password. We are trying to encourage SWARPAnet users to authenticate via public-key as much as possible. The primary reason for this is security --- it's not impossible for crackers to break into your account if you use public-key authentication, but as of right now (August 2005), more accounts are being hacked by guessing or sniffing passwords than are being hacked by stealing and decrypting keys.

However, a nice side benefit is that SSH's public-key authentication provides a lot more flexibility than password authentication does. Eventually, we may provide some pointers here for some of the cool things you can do with public-key auth, but, for now, feel free to ask us.

Public-key authentication is based on public-key cryptography. In extremely vague (and not entirely accurate) detail, it works as follows: you have two related keys, one public and one private. The server (login.swarpa.net) has your public key. The public key is used to define a question which (cryptographically speaking) can only be answered by someone who has the private key (i.e. you). When you try to login, the SSH server asks this cryptographic question, and your SSH client uses your private key to answer it. (All of this is done for you behind the scenes, so you will not have to type any really long hexidecimal numbers in order to login.) If your client's answer makes sense to the server, then the cookies have won. Also, you get to login.

In order to make this happen, you will need to do several things:

Create a public/private keypair
Tell login.swarpa.net to use your public key to identify you, so that you can login
Tell your SSH client to use your private key when connecting to login.swarpa.net

Once you have done those things, the login process itself is not very different from what you are used to doing. It is worth noting that you will only be able to login using your key from a computer on which your private key has been installed. If this means that you login using your key when you're at home, but using a password when you're at work or somewhere else, that's okay --- it's still preferable to always logging in using your password.

Creating a public/private keypair

Note: these instructions are for generating keys from a command line on a Unix machine, including Mac OS X. If you regularly login from a machine running Windows, MacOS 9 or earlier, or some other non-Unix OS, let us know, and we'll try to find directions for how to configure your SSH client to use public-key authentication.

Use the ssh-keygen utility to create a keypair. The syntax is:

  % ssh-keygen -t rsa

You will be prompted for a filename in which to store the key. Unless you are going to have multiple keys, the default is probably fine. At any rate, it is preferable to keep your key in the directory ~/.ssh/ so that you can find it again.

You will then be prompted for a passphrase. This should be a strong password (at least eight characters which are seemingly random and which include letters, numbers, and punctuation), or a much longer (at least 20 characters or so) English-like phrase which is hard to guess, and which contains at least some numbers and punctuation. It should not be the same as your login password for SWARPAnet.

The passphrase is used for encrypting your private key on disk. This is important because, if you do not encrypt your key, then anyone who breaks into your computer can also break into your SWARPAnet account. If SWARPAnet is cracked because of your unencrypted key, restoring the system will waste a lot of time which we could be using to do other neat things for SWARPAnet or to relax and enjoy ourselves, and we will be upset with you. Do not enter a blank passphrase.

Once you are done, you should have two new files. The one whose name ends in .pub is your public key, and the other is your private key. For the rest of this document, we will assume that they are named:

  /Users/username/.ssh/id_rsa
  /Users/username/.ssh/id_rsa.pub

which is the default for an OS X machine.

Configuring `login.swarpa.net` to allow you to authenticate with your key

In this step, you will tell login.swarpa.net that it can use your public key to try to authenticate people who want to login to your account.

If you are creating an SSH keypair for a new SWARPAnet account, you may not have access to your account yet. In that case, we will do this step. Send your public key only (the id_rsa.pub file) to us as an e-mail attachment, and we will configure your key file.

If you already have an account and are switching over to using public-key authentication, you can do the server configuration yourself:

Copy your public key over to login.swarpa.net:
```
  % scp ~/.ssh/id_rsa.pub swarpauser@login.swarpa.net:
        
```
(where swarpauser is your username on SWARPAnet). Remember that you will need to enter your old SWARPAnet password --- the passphrase is for your new key, which SWARPAnet doesn't know about yet.
Add your public key to your authorized_keys file. The file ~/.ssh/authorized_keys is what SSH on the server uses to determine what keys are allowed to login to your account. To configure it, connect to login.swarpa.net. (You will need to use your password for this connection, since the public key has not yet been configured.) Then do:
```
  % ls -l ~/.ssh/authorized_keys
      
```
to find out whether you already have this file (if you have a webpage at keyfitz.org, you probably do, even if you didn't set one up yourself). If you don't have the file, create it from your public key:
```
  % mv -i ~/id_rsa.pub ~/.ssh/authorized_keys
      
```
If you do have the file, add your public key to it:
```
  % cat ~/id_rsa.pub >> ~/.ssh/authorized_keys
      
```

Now SSH on SWARPAnet knows to let you login to your account if you can prove that you have your private key.

Configuring your SSH client to use your key

Now, setup your home computer so that it uses your private key when trying to login to SWARPAnet. Edit the file ~/.ssh/config:

  % pico ~/.ssh/config

(You're welcome to use an editor other than pico if you know one, of course.) Add something like the following to the bottom of the file:

  Host swarpa
    HostName login.swarpa.net
    User swarpauser
    IdentityFile /Users/username/.ssh/id_rsa

Any of those lines are negotiable. Host is what you want to type as the hostname when you login, so it should be any short name you can remember which corresponds to your SWARPAnet account. HostName can be login.keyfitz.org if you want. User is your username on SWARPAnet. IdentityFile is the file containing the private key you created earlier.

Logging in

You should now be able to login to SWARPAnet by typing:

  % ssh swarpa

(or whatever you used as the Host field of your configuration entry above). Instead of asking for a password, it should prompt for your passphrase:

  % ssh swarpa
  Enter passphrase for key '/Users/username/.ssh/id_rsa':

Enter your passphrase. You should now be logged into SWARPAnet.

Return to main documentation page

Page maintained by <webmaster at swarpa dot net>
Last updated on 2005-06-23 (Thu) at 23:28 EDT