SSH keys are a public/private key pair that allows a login to an ssh deamon (sshd) without using a password. SSH keys are generated using the ssh-keygen program on Linux/Unix/MacOS/Cygwin, or with PuTTYgen on Windows.

Note: Loading your SSH pblic key into the RCF/ACF LDAP server, as described in these pages, will only allow you to login to the RCF and ACF gateway machines. You will no longer automatically get your Kerberos and AFS tokens. It is recommended that you run the kinit program on the gateway machine using the wrappers akinit on the ATLAS gateways or rkinit on the RHIC gateways (these commands are wrappers for kinit -5 -4 -l 7d (the third argunment is a lower case L)). Running one of these commands will obtain your Kerberos and AFS tokens for your session. You can then proceed to login to an internal machine at the facility. An alternative would be to copy your public key to the authorized_keys file in the .ssh directory in your NFS home directory in the facility. Adding your public key to the file will allow you to login to the internal machines, but you will not have your Kerberos or AFS credentials.

Note: SSH keys are checked within the sshd program itself, and so will take precedence over the other authentication methods.

When fully implemented, CryptoCard authentication will automatically obtain Kerberos and AFS tokens and tickets.

Generating Keys

Warning: Do not generate your key pair on a multiuser machine. The keys should be created on your personal desktop or laptop. In addition, do not store your private key file on a multiuser machine. You private key file should only reside on your personal machine(s).

Step by step instructions for Linux/Unix/MacOS/Cygwin
Step by step instructions for Windows/PuTTY
Step by step instructions for Windows/ssh.com — the method also works for F-Secure (thanks to Thomas Ullrich, Jim Thomas and Jerome Lauret)

To generate an SSH key pair under Unix/Linux/Macintosh use the ssh-keygen program as:

ssh-keygen -t rsa

This command will generate an RSA key of default length (1024 bits). You will be prompted to enter a file name for the keys (the default is id_rsa in your .ssh directory). Finally, you will be prompted for a pass phrase for your key, which will be used to unlock your private key file (failing to enter a pass phrase for you key will, of course, defeat all security related to the key pair). Two files will be created. The first is the private key with the name you entered above and the second is the public key with .pub appended to the name.

Windows

Similarly, the PuTTYgen program is used to generate a public/private key pair under Windows (the PuTTY programs are available from Simon Tatham). The application looks like the figure below and will generate a 1024 bit RSA key by default. Once you have generated the keys using the Generate button and entered a pass phrase, select the Save public key and Save private key buttons to write the keys to disk. The fingerprint of the public key just generated is shown in the Key fingerprint: line.

Using SSH Keys

To use your ssh key to login to another remote machine, you must copy the public key file to the remote machine. For use at the RCF/ACF, you can use the SSH key file upload form to upload your public key file (the one with the .pub extension) to the facility. Your public key will be stored in LDAP and will be availble on all of the gateway machines. When you login to one of the gateway machines using ssh after uploading your key, you will be prompted to enter the passphrase for your private key (the passphrase and private key will remain on your local machine and never get transmitted over the network). After successfully entering your passphrase, you will be logged into the gateway. On a Windows machine using PuTTY, you need to tell PuTTY to use the key. Going to the Auth section of the PuTTY configuration (see Figure below), enter the name of the file containing your key in the Private key file for authentication: box (you can browse to it using the adjacent Browse... button). While you are on this page, you might want to check the Allow agent forwarding checkbox.

To avoid typing your passphrase each time you login, see the section below on the SSH agent. Note: If you use the SSH agent with PuTTY, you do not have to enter the private key file name on the Auth page of the PuTTY configuration, all is handled by the agent.

Multiple Machines

If you own multiple machines (e.g, a desktop and a laptop), then you can generate a public/private key pair on one machine, upload the public key to the LDAP server, and copy the private key to your other machines. Note: If you want to move keys between a Windows machine running PuTTY and a Linux machine, then you will have to convert the format of the key since PuTTY uses a different format from OpenSSH. Consult these instructions. If you use Cygwin, the key files should be compatible since OpenSSH is the version of ssh implemented in Cygwin .

The SSH Agent

Each time you login to a remote host using ssh keys, you will be prompted to supply the pass phrase used to lock your private key. There is an ssh agent that will hold your private key for you, respond to the ssh transaction and supply the key as needed. You start the ssh agent with the command:

ssh-agent [command [args ...]]

Where command is an optional aplication to run that will have access to the agent. Most modern versions of Linux have the agent being started when your X-windows session starts, so the agent will be available to all applications under X.

You add keys to the agent with the ssh-add command. Typing:

ssh-add -l

where the argument is a lower case L, will tell you if the agent is running and which keys are loaded into it. If the ssh-add -l command displays:

Could not open a connection to your authentication agent.

then the agent is not running. If the response is:

The agent has no identities.

then no keys are loaded into the agent. To load a key into the agent use:

ssh-add [file ...]

If no file is given, then an attempt is made to load the default files, otherwise the named private key file will be loaded. You will be prompted for the pass phrase for the private key file.

Windows - PuTTY

To use the ssh agent under Windows, you just have to start Pageant from the PuTTY menu. Starting the agent will put an icon of a computer terminal with a hat on it in the system tray. To load a key into the agent, right click on the Pageant icon and click on "Add Key". A file dialog will come up and you should open the private key file you want to load. You will be prompted for the key's passphrase.

If you want the agent to start automatically and load your private key when you start windows, then simply add the .ppk file to your "Startup" folder in your "Start" memu (this assumes that you intalled the PuTTY programs using the Windows installer method so that the association between the .ppk extension and the Pageant program was made) as:

C:\Documents and Settings\<user>\id_rsa.ppk

where <user> is replaced by your username and the .ppk file should be the name of your private key file. You, of course, will browse to the file during the process of adding the file to the Startup folder. If you want to add more than one key at startup, then put something like the following in your "Startup" folder.

C:\Program Files\PuTTY\pageant.exe <keyfile> <keyfile>

Where <keyfile> is replaced with the path to the keyfiles you want to load. If you do this, then when you start up your machine a dialog box asking for the passphrase for the private keyfile(s) you put in the Startup folder will popup. After entering the passphrase, the Pageant icon should appear in the system tray and it should contain your private key(s).

Windows - Cygwin

The ssh-agent works under Linux/Unix because parent processes spawn child processes that inherit the environment of the parent. The concept of a child process inheriting an environment does not exist under Windows, so when the ssh-agent creates a random socket to connect to under Windows, other processes do not know which socket to communicate with. To get around this problem in Windows, one can force the ssh-agent to use a particularly named socket and have the name of the socket available to all processes. Do this by picking a socket name, such as /tmp/ssh-socket and putting the name in the environment variable the various programs will use. So (assuming you are using the standard install of Cygwin), add the following line to your .bashrc file in your Cygwin home directory:

export SSH_AUTH_SOCK=/tmp/ssh-socket

Now every shell you start will have the above environment variable. Now start the ssh-agent forcing it to use this socket as:

ssh-agent -a $SSH_AUTH_SOCK

Since all shells have the SSH_AUTH_SOCK environment variable, they should now all see the agent. You can now proceed to add your private key to the ssh-agent with the ssh-add command. Once the ssh-agent has your key, you can login to the gateway machines without typing the passphrase to your key again.

File Transfer

To transfer files from a Linux machine, the standard scp and sftp programs will use the SSH keypair for authentication and they will use the agent if it is running.

Windows

On Windows machines using PuTTY, the PSFTP and PSCP programs will use your SSH keypair for authentication, but you will have to modify the command line used to invoke them to tell them where the private key file is located (see the PuTTY manual). If you are using the agent (Pageant), then both PSFTP and PSCP will transparently use the key(s) held by the agent.

If you use the WinSCP program under Windows, then you can have it use your SSH key by adding the path to your private key to the Private key file box on the Session page (you can browse by using the button on the right side of the box). When you connect, a dialog box will appear asking for your pass phrase. WinSCP recognizes the PuTTY agent, so if it is running, the pass phrase dialog box will not come up.