How to use the SSH agent for Linux

Introduction

JLab uses SSH to prevent third parties from snooping on the network traffic generated by interactive login sessions between hosts on our network. This provides strong security, but comes at the cost of always having to type a passphrase whenever you log into another machine. Fortunately, SSH provides a solution to this problem in the form of the SSH agent. The agent manages your credentials for you, so that you only need to type your SSH passphrase once during each login session. After you authenticate to the agent, SSH clients can contact the agent when they need to access your private key and you avoid having to retype your passphrase to unlock it again. You need to start the agent each time you log in, so these instructions will not only show how to use the agent, but also how to run it automatically when you log into your desktop.

Please note: The instructions in this document are intended to be used by users sitting at a JLab computer accessing other JLab computers or systems elsewhere on the Internet. The SSH agent relys on key-based authentication to work, and JLab policy does not allow key-based authentication on SSH sessions coming into the network from the Internet. Therefore, it is not possible to log into JLab systems from the Internet without supplying a password.

Generating and Distributing Your Keypair

Before you can use the agent, you will need to generate a pair of linked private and public keys that SSH will use to prove your identity when you log in to another system. The Computer Center provides a script to automate this process. Follow the directions in the JLab SSH2 Upgrade FAQ for Unix, specifically the question entitled "How do I upgrade my existing public/private keys to work with the new client?" to create a new set of keys. This will also add the public key you just created to your ~/.ssh/authorized_keys2 file to tell the SSH server that users possessing the corresponding private key are authorized to log in to your account. If you just need to log into CUE systems, this is all you need to do. If you want to log into non-CUE systems (either here at JLab or at another institution), you'll also need to copy your ~/.ssh directory containing your new authorized_keys2 file to the remote host. You can use scp, the secure remote copy command, to do this and type your password on the remote host when requested. In this example, the user issuing the command is "jackh", and you'll see this reflected in the output.

% scp -rp $HOME/.ssh remote-host:
jackh's password: <Type your password here>

Note the colon (:) at the end of the remote host's name. This tells scp that the last argument is a hostname and not a filename in the local filesystem.

Now try to log in to the remote system. Again, the user in this example is "jackh".

% ssh remote-host
Passphrase for key "/home/jackh/.ssh2/id_dsa_1024_a" with comment 
"1024-bit dsa, jackh@jlab.org, Fri Apr 26 2002 12:57:48 -0400": <Type your passphrase here>
Authentication successful.
[login proceeds normally]

Notice how the client prints the name of the key you're using to log in with. If you don't see the key name, you're not using one. If the key is unavailable or the client isn't configured properly for key login, the default is always password login, so be sure you're using a key before proceeding.

Preparing Your X Window Environment

The next stage is to prepare your X Window environment to be able to run the SSH agent. The agent needs to run as the parent process for your graphical session, so you'll need a way to make it run fairly early in the startup sequence. The easiest way to do this is to use RedHat's switchdesk utility.

RedHat Linux comes with a variety of different graphical desktop systems from which to choose. Most users use the default system, GNOME, though others like KDE and even Twm are popular. Before proceeding, make sure you know which desktop you are currently using. If you have trouble figuring this out, feel free to contact the helpdesk for assistance. From here on out, these instructions will assume you are using GNOME, though the same steps will apply to the other desktops as well.

In order to start the SSH agent automatically when you login, you'll need to edit your ~/.Xclients-default file. If this file does not already exist, you'll need to run /usr/bin/switchdesk to create it. Switchdesk will ask you which desktop environment you wish to use, so you should select your current choice. Click "OK" and the application will create a ~/.Xclients-default for you.

Now that the file exists, edit it with your favorite text editor. It should look something like this:

# Created by Red Hat Desktop Switcher
exec gnome-session

You need to edit the last line in this file to read

exec ssh-agent gnome-session

This will invoke the SSH agent, which in turn invokes the standard gnome-session. If you're using another desktop environment, you'll still see an "exec" statement as the last line, so just insert "ssh-agent" immediately after the exec and before the other arguments, like so:

exec ssh-agent startkde

Starting with your new desktop environment

Now you must log out of your desktop and make sure your account is configured to use your ~/.Xclients-default file. When you log out, you should see the system's graphical login screen. Before you type your user id, select the "Session" menu at the top of the login dialog. You'll see a list of several desktop sessions you can log into. You should make sure to select "Default" so that the session you chose earlier with switchdesk will be the active one. Then log in normally. The system will ask if the "Default" session should be made your default choice in the future, too. Select "Yes" so that your ~/.Xclients-default file is consulted each time you log in. When your session starts, you should see your normal desktop environment. If not, you probably selected the wrong session type in switchdesk. Simply run it again and pick another selection, then log out and back in again.

Now verify that the agent has started:

% ps -auxww | grep -i agent
jackh    6888  0.0  0.2  2784 1080 ?        S    10:08   0:00 ssh-agent gnome-session

Using the SSH Agent

Now that the SSH agent is running, the final step is to tell it your passphrase so that it can authenticate you later when you try to log in to other systems. In any terminal window, you can use the ssh-add command to add your identity to the agent's cache. Just run the command with no arguments and type your key's passphrase when requested.

% ssh-add
Adding identity: /home/jackh/.ssh2/id_dsa_1024_a.pub
Need passphrase for /home/jackh/.ssh2/id_dsa_1024_a (1024-bit dsa, jackh@jlab.org, Fri Apr 26 2002 12:57:48 -0400).
Enter passphrase: <Type your passphrase here>

Now try to log in to another JLab CUE host, or a remote host to which you have copied your ~/.ssh directory in the previous stage. You should find that you are logged in without asking for a passphrase.

To go a step further, it may be convenient to add ssh-add to the list of programs that start automatically when you log in to your graphical session. In this case, ssh-add will use an X Window interface to ask for your passphrase and you can avoid having to remember to run the command by hand. To add this for the GNOME desktop, open the footprint menu at the bottom left of the screen and select "Start Here" to run the GNOME configuration tool. When the window appears, double-click the "Preferences" icon, then the "Session" icon, then the "Session Properties & Startup Programs" icon. This will bring up a new dialog with two tabs. Select the "Startup Programs" tab and click "Add" to create a new entry. Type /apps/bin/ssh-add in the "Startup Command" field, then set the "Priority" setting to 25 and click "OK" to add the new command to the list. Now click "OK" again to exit the session properties dialog. Log out and log back in to your desktop and the system should prompt you to enter your SSH passphrase.

This document is maintained by {helpdesk@jlab.org}