Using git with a private key authentication on windows with putty

We are going to see how to use a private/public key pair to connect to a remote system in SSH from windows. This authentication method is way more secure than a simple password, and it is possible once correctly set to completely deactivate the login/password identification (although it isn’t within the scope of this post). We will also see how to link msysgit in command line to the private key we’ll have generated.

Generating a key

We will need puttygen.exe, putty.exe, pageant.exe and plink.exe for this tutorial.
You can get them from http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html.
Note that the installer contains all those components in a single download.

Once installed on your system, launch puttygen.exe and click on “Generate”. You’ll then have to move your mouse until the progress bar is complete, in order to generate the randomness required to create the key.
Once it’s done, fill the “Key passphrase” field with the passphrase of your choosing, then click on “Save private key” and save it in a secure area on your computer in .ppk format.

Don’t forget your passphrase, it will be essential to use your private key!

Link your key to the remote system

The public key you have generated is shown in the top part of puttygen under the “Public key for pasting into OpenSSH authorized_keys file” label.

Connect to the server for which you are setting up the keys system, and in the home directory of your user create a .ssh directory (if it doesn’t already exist). In this directory, create a file named authorized_keys and paste your public OpenSSH key into it.
That’s it for the server side!

Connect in SSH

In order to check that everything is fine, we are now going to test the connection.
Launch putty.exe and type the server address in the “Host Name (or IP address)” field preceded by your user name and a @ (example: myuser@my.server.com).
Also check that “Connection type” is set to SSH and port to 22 (if the server uses the default port).
In the left menu, go to “Connection”, then “SSH” and click on “Auth”. You should see a “Private key file for authentication” field. Type the location of the .ppk file we have generated in it.

Then go back to the “Session” part of the left menu, type in the name you want for the connection in the “Saved Sessions” field, and click on “Save”.
You can now click on “Open” to connect to the server, which will ask you for the passphrase and validate the connection.

Automating the passphrase

We will now ask pageant.exe to handle the passphrase for us in order not to type it manually at each connection.
To do so, launch pageant.exe, click on “Add key”, and input the .ppk file location.

If you try and connect with putty, the server shouldn’t ask you for the passphrase anymore, and just connect you right away.

Note that pageant won’t remember they loaded keys next time you launch it. If you close it (for example when rebooting the computer), you will have to use “Add key” again.
To avoid this, we will create a shortcut that will fetch the .ppk for us.
Right-clik on pageant.exe and click “Copy”.
Go to the desktop, right-click anywhere and click “paste the shortcut”.
Right-click the shortcut and click “properties”. In the “Target” field, you will have the path to pageant.exe. We are going to add the path to the .ppk as a parameter to this executable by adding it after a space (example: "C:\Program Files\PuTTy\pageant.exe" C:\Users\Myself\Documents\my_private_key.ppk). If the path to the .ppk contains spaces, put it into quotes. If you want to load several private keys, separate them with spaces (example: "C:\Program Files\PuTTy\pageant.exe" C:\Users\Myself\Documents\my_private_key1.ppk C:\Users\Myself\Documents\my_private_key2.ppk).

You should also note that if you authorize the agent forwarding, you will be able to use this key loaded in peageant.exe from any server you connect to.
Imagine you have two servers (let’s call them A and B) which give you ssh access through your public key. You connect to server A thanks to your private key as explained above, and you can then connect to server B from server A thanks to your private key, although it didn’t leave your computer ! There lies all the agent forwarding magic : the key which is stored onto your own computer can be used to get recognized by any of the servers you wish to access to, even if the terminal you connect from never heard of it. It can be quite useful, for example, when you wan to ask server A to do a “git pull” from server B.

To activate this option in putty, go in the left menu, in “Connection”, “SSH”, “Auth” –i.e. the same place we loaded the .ppk key from– and check the “allow agent forwarding” box.

Don’t forget to save this setting by going back to “Session” to click on “Save”.

To check if the agent forwarding is properly set, you can use the command “ssh-add -l” in order to check the forwarded keys.

What about git ?

In order for git to take advantage of this system, we’re first going to add GIT_SSH to our environment vraiables.
To do so, click on the start menu and in the program launcher field type “SystemPropertiesAdvanced”.
This shortcut takes us directly to the system properties window.
In this window, click in the bottom on “Environment variables”. You will find the user variables in the top. We ware going to add our variable in those : click on “New…” and type GIT_SSH as a name and the location of the plink.exe file as a value.
We’ll also need to add this location to the PATH : in the system environement variables, select Path, click on “Change”, go to the end of the line and add the location of the directory in which putty.exe and plink.exe are (preceded with the ; separator). While you’re there, check that the Path also contains a reference to c:\path\to\git\bin, it can get useful ;)

We can now link a repository to our passphrase handler tool (pageant.exe) :
Click on the start menu and type “cmd” in the program launcher field to get a MSDOS window.
Type in : plink.exe user@git.repository.address
Et voila !
From now on, you can use all the git commands in a MSDOS command line to handle your repository wihtout having to type your passphrase each and everytime!

Other tools

The .ppk format being specific to PuTTy, some applications won’t recognize it as a valid key.
They will most likely ask you for a key in the OpenSSH format.
This is the case for example when using SmartGit, a quite interesting graphical user interface.
In order to generate the OpenSSH key, go back to puttygen.exe, click on “Load” to open your .ppk formated key (your will be asked for your passphrase), then click on the “Conversions” menu and “Export OpenSSH Key”.
Save the key next to your .ppk with the name you want, and when smartgit asks for your private key, point it to this file.

Even better: go in the home directory of your user (ex: C:\Users\Matt\), you should find there a hidden folder named .ssh.
Create a file there with id_rsa as a name and your private key in OpenSSH format as a content, and another one with the name id_rsa.pub and your public key in it.
This way, most of the applications integrating this kind of authentication will automatically be able to use those informations.
It is worth noting that this is the way our preferred IDE, namely PhpStorm, behaves. ;)

It is also this way that you should proceed if your system is based on an unix (ex: Linux, OSX…)

Resources

A few useful links on the topic:

2 thoughts on “Using git with a private key authentication on windows with putty

    • Thanks for pointing it out. It was a typo, and I’ve now fixed it. The filename is indeed supposed to be id_rsa (or id_dsa if you have a DSA key).

Leave a Reply

Your email address will not be published. Required fields are marked *

Top of page