School of Education Knowledgebase

Version Control with TortoiseSVN, PuTTY, and Public-Key Authentication

Subversion is a version-control system for managing collaborative work, and secure shell (SSH) grants remote access to network resources. On Microsoft Windows, the TortoiseSVN Subversion client and the PuTTY SSH client combine to encrypt communication with the server where collaborative work is stored. The combination also permits one to use the same credentials to logon to the Subversion server as one uses to log on to a Windows computer in a School of Education office.

The focus of this article is on using a public-key pair or SSH keys, instead of the traditional username and password credentials, to logon to a Subversion server. Two benefits of SSH keys are that a password is never transferred on the network and SSH keys can be used repeatedly without prompting the user for a password. The latter is a major benefit for Subversion users, because Subversion can frequently request credentials during a session. SSH keys can eliminate password prompts.

Assumptions

• A 64-bit version of Microsoft Windows is installed on the Surversion client computer.
• A Subversion server is named "example-svn.ad.education.wisc.edu". Replace with the name of a real Subversion server when ready.
• A user account named "jdoe" exists on the Subversion server. Replace with an actual user account name when ready.

Install the PuTTY and TortoiseSVN Applications

1. Download application installers. If given the choice, choose 64-bit applications.
1. PuTTY: http://www.putty.org
1. Choose the "Windows installer": putty-X.XX-installer.exe
2. The full install includes important applications like "Pageant", "Plink", and "PuTTYgen".
2. TortoiseSVN: http://tortoisesvn.net/downloads.html
2. Double-click on the PuTTY installer icon to run it.
1. Accept the defaults.
2. PuTTY files are stored in the "C:\Program Files (x86)\PuTTY" folder by default.
3. To run applications from a command prompt, add the location of these applications to the PATH environment variable.
1. Choose "Start > Control Panel".
2. Open the "System" icon, click on the "Advanced system settings" link, and click "Environment Variables...".
3. Double-click the "Path" variable in the "System variables" list.
4. Add ";C:\Program Files (x86)\PuTTY" to the end of the "Variable value".
5. Click the "OK" button to save the settings.

3. Double-click on the TortoiseSVN installer to run it.
1. Accept the license agreement and defaults.
2. TortoiseSVN files are stored in the "C:\Program Files\TortoiseSVN" folder by default.

Configure TortoiseSVN to use SSH

1. Open "Settings" by choosing "Start > All Programs > TortoiseSVN > Settings" or by right-clicking on any file icon and choosing "TortoiseSVN > Settings" from the pop-up menu.
2. Select "Network" from the left sidebar of the "Settings" window.
3. Click the "Browse..." button beside the "SSH client" field.
4. Navigate to the "C:\Program Files\TortoiseSVN\bin" folder and choose "TortoisePlink.exe".
5. Click "Apply" to save the setting and click "OK" to close the "Settings" window.

Make a SSH Key Pair

1. Choose "Start > All Programs > PuTTY > PuTTYgen".
2. Check the "Parameters" area to verify "SSH-2 RSA" is the "Type of key to generate" and "2048" is the "Number of bits in a generated key".
3. Click the "Generate" button. Be sure to move the mouse to make randomness.
4. Type your username in the "Key comment" field.
5. Consider typing a password in the "Key passphrase" field. If a password is given, it will be requested once per session to access the SSH keys. Otherwise, the key pair will automatically authenticate and grant access to the server.
6. Copy all the text from "ssh-rsa" to your username in the field labeled "Public key for pasting into OpenSSH authorized_keys file".
7. Run the "NotePad" application, add a blank line to the top of the file, paste the public key into the file, and save it as a text file, e.g., "example-svn-public.txt".
8. Click the "Save private key" button, and save it as a PuTTY Private Key file, e.g., "example-svn-private.ppk".
9. Choose "File > Exit" to close the "PuTTY Key Generator" window.

Upload the Public Key to the Subversion Server

1. Open a command prompt by choosing "Start > All Applications > Accessories > Command Prompt".
2. Issue this "pscp" command to upload the public key to the Subversion server. The following command saves the "example-svn-public.txt" file into the ".ssh" directory of the "jdoe" user.

pscp %HomePath%\Documents\example-svn-public.txt jdoe@example-svn.ad.education.wisc.edu:.ssh
(Type the user account password when prompted.)
      

3. Issue this "plink" command to add the public key to the "authorized_keys" file on the Subversion server. This command appends the content of the "example-svn-public.txt" file to the "authorized_keys" file, the file where SSH looks for public keys.

plink jdoe@example-svn.ad.education.wisc.edu "cat ~/.ssh/example-svn-public.txt >> ~/.ssh/authorized_keys"
(Type the user account password when prompted.)
      

Make a PuTTY Session for the SSH Key

1. Choose "Start > All Programs > PuTTY > PuTTY" to open the "PuTTY Configuration" window.
2. Type your user name and the host name in the field labeled "Host Name (or IP address)". Use the following format that resembles an email address with the user name separated from the host name by an "@" character.

jdoe@example-svn.ad.education.wisc.edu
      

3. Type a descriptive name in the "Saved Session" field, for example, the host name...

example-svn
      

4. Click the "Save" button.
5. Select "Connection > SSH > Auth" from the left sidebar.
6. Click the "Browse..." button beside the "Private key file for authentication" field.
7. Navigate to your "Documents" folder and pick the "example-svn-private.ppk" file.
8. Select "Session" from the left sidebar, pick your session from the list under "Saved Sessions", and click the "Save" button.

Run Pageant to Activate the SSH Key

1. Choose "Start > All Programs > PuTTY > Pageant". When Pageant is running, an icon of a monitor with a black hat appears in the system tray of the task bar.
2. Double-click on the icon to open the "Pageant Key List" window.
3. Click the "Add Key" button and pick the "example-svn-private.ppk" file.
4. Click the "Close" button. The SSH key is active in memory and ready to work. One can now issue TortoiseSVN commands without being prompted repeatedly for credentials.
5. IMPORTANT! The SSH key will remain active until either the Pageant application is stopped or the computer is restarted or shutdown. Steps 1-4 must be repeated each time the computer is started in order to activate the SSH key.

Check Out a Repository

1. Choose a location for the working copy, for example your "Documents" folder.
2. Open the chosen folder, right-click on the background, and choose "SVN Checkout...".
3. Type the following into the field labeled "URL of repository"...

    
svn+ssh://jdoe@example-svn.ad.education.wisc.edu

-- An alternative is to use the HTTPS protocol if it is active on the server. --

https://example-svn.ad.education.wisc.edu
      

4. Append "\example-svn" to the line in the "Checkout directory" field. This will be the local location of the "working copy" of the repository.
5. Click the "OK" button to start the file transfer. (If asked to accept the public key of the Subversion server, click the "Yes" button. )

For More Information

• Public-Key Cryptography (Wikipedia)
• PuTTY Documentation
• Subversion Documentation (Red-Bean)
• TortoiseSVN Documentation