SSH2 Keypair
============

This page provides instructions on how to generate a SSH2 Keypair.

Linux
-----

In a running terminal window::

    $ ssh-keygen

Your private key should be located in *~/.ssh/id_rsa* or *~/.ssh/id_dsa*
Your public key should be located in *~/.ssh/id_rsa.pub* or *~/.ssh/id_dsa.pub*

Mac OS X
--------

In a running terminal window::

    $ ssh-keygen

Your private key should be located in *~/.ssh/id_rsa* or *~/.ssh/id_dsa*
Your public key should be located in *~/.ssh/id_rsa.pub* or *~/.ssh/id_dsa.pub*

Windows
-------

Natively Windows does not provide a tool to generate such a pair.

However you can use external tools, such as PuTTYgen which can be found `here <http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html>`_.

Using PuTTYgen
^^^^^^^^^^^^^^

Generating your key pair
""""""""""""""""""""""""

Before generating a key pair using PuTTYgen, you need to select which type of key you need.

    - Select **SSH2 RSA**

Press the *Generate* button and PuTTYgen will begin the process of actually generating the key.

The Key passphrase and Confirm passphrase boxes allow you to choose a passphrase for your key. The passphrase will be used to encrypt the key on disk, so you will not be able to use the key without first entering the passphrase.

If you leave the passphrase fields blank, the key will be saved unencrypted. **You should not do this without a good reason**, if you do, your private key file on disk will be all an attacker needs to gain access to any machine configured to accept that key.

Once you have generated a key, set a comment field and set a passphrase, you are ready to save your private key to disk.

Saving your private key to disk
"""""""""""""""""""""""""""""""

Press the **Save private key** button. PuTTYgen will put up a dialog box asking you where to save the file. Select a directory, type in a file name, and press **Save**.

Saving your public key to disk
""""""""""""""""""""""""""""""

To save your public key in the SSH-2 standard format, press the **Save public key** button in PuTTYgen. PuTTYgen will put up a dialog box asking you where to save the file. Select a directory, type in a file name, and press **Save**.

Converting Keys from PuTTY to OpenSSH format
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you generate your key pair on Windows before following this guide, it is likely that the private key is saved in \*.ppk format. If this is the case, you will need to convert it to OpenSSH format.

Converting in Windows
"""""""""""""""""""""

After opening PuTTYgen, go to :menuselection:`Conversions --> Import Key`, locate and select your private key in \*.ppk format.

Now that the key is loaded, go to :menuselection:`Conversions --> Export OpenSSH key`, and choose a name and destination (if you only use one key, we recommend naming it "id_rsa")

Converting in Linux (Ubuntu)
""""""""""""""""""""""""""""

First you will need to install the following package, which provides tools for conversion:

.. code-block::bash

    $ sudo apt-get install putty-tools

Assuming your private_key.ppk is located in your home's root (~/private_key.ppk) and we want to save it as id_rsa in .ssh directory:

.. code-block::bash

    $ puttygen ~/private_key.ppk -O private-openssh -o ~/.ssh/id_rsa

Make sure the permissions are ok for the private key file:

.. code-block::bash

    $ chmod 600 ~/.ssh/id_rsa

Converting in Mac OS X
""""""""""""""""""""""

Installing PuTTY in Mac OS X, makes use of external tools, thus we recommend either converting in Linux or Windows as aforementioned.