Set up ssh-agent

Checking out or updating the PHENIX sources will establish many ssh-connections to several servers hosting the source repositories. While not necessary for a successful installation, having an ssh-agent running on the machine used to access the repositories will save much error-prone password-typing. The idea is to provide the remote server with the public half of a cryptographic key pair, which enables it to encrypt a randomly generated challenge and send it to the ssh-agent. If the agent has acquired the corresponding private key it can respond with the decrypted challenge, thereby proving to the remote server that it has access to the decrypted private key. The ssh-agent has authenticated with the server without any user intervention.

Creating a cryptographic key pair

The first step is to generate a complementary pair of cryptographic keys. This step can be skipped if a key pair already exists—it is perfectly safe to use the same key pair to authenticate with any number of remote systems. One of the keys is public and the other is private. The public component of the key pair can be freely distributed without compromising security; indeed, any system one wishes to authenticate with will need access to the public key. The private component must be kept secret. In addition, the private key can be encrypted using a passphrase without which it cannot be used. It is possible to generate a key pair without a passphrase, but then anybody who gains access to the key also acquires access to all systems the key unlocks.

In the example below, an RSA key pair is generated in the default location, /home/user/.ssh/id_rsa and /home/user/.ssh/id_rsa.pub. The passphrase should be complex—when using ssh-agent one will not need to type it very often.

$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/home/user/.ssh/id_rsa): [PRESS RETURN]
Enter passphrase (empty for no passphrase): [ENTER A COMPLEX PASSPHRASE AND PRESS RETURN]
Enter same passphrase again: [REPEAT COMPLEX PASSPHRASE AND PRESS RETURN]
Your identification has been saved in /home/user/.ssh/id_rsa.
Your public key has been saved in /home/user/.ssh/id_rsa.pub.
The key fingerprint is:
ba:f2:7a:78:aa:b0:33:1d:53:de:63:01:62:15:d6:c9 user@host

Then, start the ssh-agent, and add the decrypted private key of the newly generated key pair to the ssh-agent's cache.

$ eval `ssh-agent`
$ ssh-add
Enter passphrase for /home/user/.ssh/id_rsa: [ENTER COMPLEX PASSPHRASE AND PRESS RETURN]
Identity added: /home/user/.ssh/id_rsa (/home/user/.ssh/id_rsa)

New ssh-processes will now act as clients to the ssh-agent, and attempt to use the keys it holds to authenticate with the remote system.

Distribute the public key to the remote system

The remote system needs access to the public component of the key pair to generate the authenticating challenge for the ssh-agent. This means that the public component of the key pair has to be present in ~/.ssh/authorized_keys on the remote system.

$ cat ~/.ssh/id_rsa.pub | ssh user@remote.host "cat - >> ~/.ssh/authorized_keys"

This will append the public key of the recently created key pair to ~/.ssh/authorized_keys on the remote system. It is now possible to access remote.host without typing a password on the command line.

Distribute the public key to sourceforge.net

The servers at sourceforge.net can be made aware of the public key, too. To do so, access the account from the web interface and navigate to SSH Settings, and choose Edit SSH Keys for Shell/CVS. The public key can now be pasted into the text box. Note that it may take several minutes for the change to take effect.

Using keychain

An ssh-agent started from command line only affects ssh-connections started from the same shell, and separate ssh-agents would be required for each new login shell. The private key would have to be decrypted from every login shell separately. Furthermore, ssh-agents are not necessarily terminated when the login shell exits, potentially cluttering the system with orphaned ssh-agents. keychain is a shell script that was written to avoid this situation: it probes the system for any running ssh-agents, and attempts to use a running agent instead of starting a new daemon. If no ssh-agents are running, keychain starts a new process and uses ssh-add to add the specified private keys.

At CCI and SLAC keychain is installed at ~hattne/gentoo/usr/bin/keychain. At NERSC it is at /global/project/projectdirs/lcls/gentoo/usr/bin/keychain. It is recommended to run keychain from the shell configuration files for interactive, login shells. To do so, bash users can add the following lines to their ~/.bash_profile:

 test -x /path/to/keychain && \
   eval `/path/to/keychain --agents ssh --eval id_rsa --inherit any-once --stop others`

csh would modify ~/.login instead.

Using agent forwarding

It is not necessary to start ssh-agents on every system logged in to. If an ssh-agent is running on the host used to access a remote system, a connection to the agent can be forwarded using the ssh’s -A option. Any ssh-processes on the remote system will now query the ssh-agent on the host logged in from. keychain will recognize that agent-forwarding is in effect and will not start a new agent on the remote system.

External links

• OpenBSD manual pages: ssh-agent
• OpenBSD manual pages: ssh-keygen
• OpenBSD manual pages: ssh-add
• SSH keys - sourceforge
• Keychain—Funtoo