Blog Entry

How to use ssh-agent on Windows with TortoiseSVN

TortoiseSVN uses Plink, the command line member of the PuTTY suite, to perform SSH connections. This means that TortoiseSVN has the entire featureset of PuTTY (and thus SSH) available at it's disposal. Some of these features require a good deal of setup work, but can pay off in the long run.

The feature of primary interest is that of ssh-agent functionality under Windows, where we set up a public/private key pair, authenticate with the server once, then use the ssh-agent to manage our password and session from then on. This gives all of the benefits of security associated with SSH, while not requiring the user's password for every operation.

NOTE: This can be done even more elegantly under OS X. I'll write that up eventually as well.

Software

To do this, we need 3 pieces of software on our machine:

Installer for all utilities found here.

PuTTY is used to create the session and store it in the registry. PuTTYGen is used to take the private key of the pair we create on the Unix machine and convert it to the PuTTY format. Pageant is used to store that key when we actually want ssh-agent functionality.

In addition to this, you'll obviously need a Unix machine to connect to and have a valid account on it.

Key Generation

Since this whole operation depends on having a public/private key pair, our first order of business is to go about generating one.

PuTTYGen can generate keys, but they are incompatible with the ones used by OpenSSH on the Unix box. So we go to the command line of the Unix box. The following will generate a key pair:

ssh-keygen -b <bits> -t <type> -C <comment> -f <filename>

Type:

ssh-keygen -t rsa -C "Subversion login key" -f svnkey

and you will be prompted for a password. The result will be 2 files, svnkey and svnkey.pub (the private and public keys, respectively). These go on opposite ends of the connection we want to make. The server has the public key, and you have the private key. The mentality is that only you should have your private key, so the server should trust that. Still, we have a password to be doubly sure.

The public key needs to go in a specific file, called authorized_keys, so enter:

cat svnkey.pub >> ~/.ssh/authorized_keys

to append it to that file. You may need to create this file and directory in your home directory first.

Finally, with that in place, copy the private key to the machine you want to connect with.

PuTTY Configuration

PuTTY uses a different key format than OpenSSH, so we first need to convert our OpenSSH private key to a PuTTY private key. We use PuTTYGen to accomplish this task.

Open PuTTYGen and click Load and select the key you downloaded from the server. You will be prompted for the passphrase you chose. PuTTYGen will acknowledge that it loaded the key and instruct you to save it out. Click the Save private key button and pick a filename.

The next step is to make all of this storable in PuTTY, so it can be made available to TortoiseSVN or any other PuTTY-compliant application. So we do the following:

  1. Under Session, enter the hostname of the Unix machine, and choose the SSH protocol
  2. Under Connection > Data, enter your login name for the Unix machine in Auto-login username
  3. Under Connection > SSH > Auth, select the filename of the private key that you saved out of PuTTYGen
  4. Back under Session, enter the hostname again in the box under Saved Sessions and click Save

This is now added into the registry and all PuTTY applications are aware of it.

Pageant and TortoiseSVN Usage

The last step is to run Pageant and then use TortoiseSVN. Double clicking the Pageant icon will cause a smaller version of it to appear in the status area of the task bar. It doesn't do anything until you load a key. So, right click, choose Add key and select the private key you generated with PuTTYGen. It will prompt you for the password.

Congratulations, once entered, you have properly configured and started ssh-agent.

Now, to put it to use. The way that TortoiseSVN communicates with Plink revolves around the name for the session you chose. You put that in place of the server name in the repository URL.

So, where before you might have done:

svn co svn+ssh://cs.ubc.ca/path/to/repos/trunk

You now use the name of the session you created. Since the session name matches, the hostname actually do the same thing:

svn co svn+ssh://cs.ubc.ca/path/to/repos/trunk

TortoiseSVN should pause for a second then start checking out. And, that's that. Untill you close Pageant, or remove your key from it, you can operate over the SSH connection without needing to enter your password everytime.

Posted on August 21, 2005
Tags: , , ,