PuTTY is a free SSH client available for Windows. It has facilities for saving session parameters for future reference and supports most of the features of the ubiquitous OpenSSH command-line client for Unix-like operating systems, but with a graphical user interface for session configuration. Below are basic instructions for configuring PuTTY to access the Research SSH servers.
- You must use PuTTY version 0.68 or newer; older releases of PuTTY do not support Elliptic Curve Cryptography, as required by the SSH server. Visit the PuTTY Homepage to access the free download.
- PuTTYgen is a companion program used to generate and manipulate keys, and is included with the complete package installer from the PuTTY Homepage. It will be useful for importing your SSH key(s) into the PuTTY native PPK format.
- See the instructions on the main SSH How To page regarding registering and receiving your keys.
- Run PuTTYgen and, using the "Import Key" menu item (see image), open the id_ecdsa file you were sent by email.
- You will be prompted for the passphrase your key was assigned, and which was provided in a separate email.
- Click Save private key and save the PPK file to a secure location of your choice; keep track of where you put it, as you will need to provide the path when you configure the PuTTY client to connect to the SSH servers (see below).
Changing the passphrase
When you use PuTTYgen to import your Private Key you will be given the opportunity to change the passphrase; please choose a responsibly complex passphrase with which to secure the key.
- Having saved your Private Key, run the main PuTTY client, and configure your session as follows:
- On the Session panel, set the Hostname to ssh.partners.org as illustrated.
- On the Connection > Data panel, set the Auto-login username to your Partners username.
- On the Connection > SSH > Auth panel, set Private key file for authentication to the path at which you saved the PPK file in the steps above (or you may browse the filesystem by clicking the button).
- Lastly you will need to list the hosts inside the Partners network to which you will most commonly be connecting.
- On the Connection > SSH > Tunnels panel, choose a local port not in use for each host:port tunnel you wish to establish.
- The localhost port to which you will connect will go in the Source port field.
- The Destination field is where you provide the Partners internal host you will connect to, in hostname:port format.
- Click the Add button for each Partners host you wish to be part of your saved configuration.
- Return to the Session panel to save these connection parameters for future use.
- Type a name of your choice for your saved session in the field under Saved Sessions and click the Save button to the right.
- When you are ready to proceed, you may click the Open button at the bottom of the dialog and provide your credentials to connect to the SSH server.
- First you will be prompted for the passphrase used to secure your Private Key
- Next you will be prompted for your Partners password.
- Your connection window will open to a non-interactive SSH session. Leave the window open (you may minimize it to get it out of the way, but don't close the window until you are ready to end your session).
- Open a new PuTTY dialogue to configure a new secure shell connection to each host you specified in the Tunnels section, above.
- In the Session panel, choose localhost for the Host Name field and the tunneled port (e.g. 2022) for Port.
- If you have a username other than your Partners ID on the remote host, you may specify it in the Connection > Datapanel, as described above.
- You may save each "localhost" session under a different Saved Session name for future ease of access.
Tips & Warnings
You need not be distracted by the plethora of configuration options offered by the PuTTY client; other than the options specifically addressed here, these settings may generally be left at their default values.
- Did you note the "Public Key for pasting into OpenSSH authorized_keys file" section of the PuTTYgen dialogue? That should be fairly self-explanatory, and will allow you to use the same SSH Key you enter in the Auth panel for your tunneled connections (and most often as a single authentication factor).
- The PuTTY package also installs an authentication agent called Pageant, which can cache your decrypted Private Key file for you, so you don't need to type the passphrase over and over for multiple connections. This works similarly to the ssh-agent(1) utility on Unix-like systems. See the Pageant Documentation for details.
In the Tunnels example above, there is a Windows host added with port 3389 open. Assuming that host has been configured to allow connection via Remote Desktop Protocol (RDP), I may now connect to it using Windows' built-in Remote Desktop client and connecting to localhost:23389 (tunneled port based on the example).