Keychain/en

This document describes how to use SSH shared keys along with the keychain program. It assumes basic knowledge of public key cryptography.

The problem at hand
So you have all of these lovely Gentoo machines running sshd, but it's a little inconvenient for you to keep typing in all of those login passwords, right? Or maybe you have a script or cron-job that needs a convenient way to use an ssh connection. Either way, there is a solution to this problem, and it begins with public key authentication.

How does public key authentication work?
Assume that a client wants to connect to the ssh daemon on a server. The client first generates a key pair and gives the public key to the server. Afterwards, whenever the client attempts to connect, the server sends a challenge that is encrypted with that public key. Only the holder of the corresponding private key (the client) is able to decrypt it, so the correct response leads to successful authentication.

Generating your key pair
The first step is to create a key pair. To do this, use the ssh-keygen command:

Just accept the default values, and make sure to enter a strong passphrase.

You should now have a private key in and a public key in. We are ready to copy the public key over to the remote host.

Preparing the server
We will be copying the file over to the server that runs sshd. We will also be adding it to the file that belongs the connecting user on that server. Here's an example of how to do that if you already have ssh access to the server.

The output from that last line should show the contents of the file. Make sure the output looks correct.

Testing the setup
Theoretically, if all went well, and the sshd daemon on the server allows it (as this can be configured), ssh access without entering a password should now be possible on the server. The private key on the client will still need to be decrypted with the passphrase used previously, but this should not be confused with the password of the user account on the server.

It should have asked for a passphrase for, and then grant access via ssh as the user  on the server. If not, login as, and verify that the contents of  has each entry (which is a public key) on a single line. It is also a good idea to check the sshd configuration to make sure that it allows to use public key authorization when available.

At this point, you're probably thinking, "What's the point, I just replaced one password with another?!" Relax, the next section will show you exactly how we can use this to save your precious time.

Typical key management with ssh-agent
The next step is to decrypt the private key(s) once, and gain the ability to ssh freely, without any passwords. That is exactly what the program ssh-agent is for.

ssh-agent is usually started at the beginning of the X session, or from a shell startup script like. It works by creating a unix-socket, and registering the appropriate environment variables so that all subsequent applications can take advantage of its services by connecting to that socket. Clearly, it only makes sense to start it in the parent process of an X session to use the set of decrypted private keys in all subsequent X applications.

When running ssh-agent</tt>, it should output the PID of the running ssh-agent, and also set a few environment variables, namely  and. It should also automatically add to it's collection and ask the user for the corresponding passphrase. If other private keys exist which need to be added to the running ssh-agent, use the ssh-add</tt> command:

Now for the magic. With the decrypted private key ready, ssh into a (public key configured) server without entering any passwords:

It would be nice to know how to shut down ssh-agent in case you need to, right?

If you want even more convenience from ssh-agent, proceed to the next section on using keychain. Be sure to kill the running ssh-agent as in the example above if you decide to do so.

Squeezing the last drop of convenience out of ssh-agent
Keychain will allow to reuse an ssh-agent between logins, and optionally prompt for passphrases each time the user logs in. Let's emerge it first:

Assuming that was successful, keychain</tt> can now be used. Add the following to the file to enable it:

Let's test it. First make sure we killed the ssh-agent from the previous section, then start up a new shell, usually by just logging in, or spawning a new terminal. It should prompt you for the password for each key you specified on the command line. All shells opened after that point should reuse the ssh-agent, allowing you to make passwordless ssh connections over and over.

Using keychain with KDE
If you are a KDE user, instead of using, you can let KDE manage ssh-agent for you. In order to do so, you will have to edit, which is read during KDE's startup, and , which is executed during KDE's shutdown. Here is how you could edit those files:

Now, all you have to do is launch a term of your choice, like Konsole, and load the keys you would like to use. For example:

The keys will be remembered until the end of the KDE session (or until the ssh-agent process is killed manually).

Security considerations
Of course, the use of ssh-agent may add a bit of insecurity to your system. If another user were to use your shell while you were in the bathroom, he could login to all of your servers without passwords. As a result, it is a risk to the servers you are connecting to, and you should be sure to consult the local security policy. If you do use it, be sure to take the appropriate measures to ensure the security of your sessions.

Troubleshooting
Most of this should work pretty well, but if you encounter problems, you'll certainly want to know a few useful things.


 * If you are unable to connect without ssh-agent, consider using ssh with the arguments  to find out what's happening. Sometimes the server is not configured to use public key authentication, sometimes it is configured to ask for local passwords anyway! If that is the case, you may want to also use the   option with ssh</tt>, or change the server.
 * If you are having problems with ssh-agent or keychain, it may be that you are not using a shell that understands the commands they use. Consult the man pages for ssh-agent and keychain for details on working with other shells.

External resources

 * Official project page
 * IBM developerWorks article series introducing the concepts behind Keychain