SSH keys

From CELS IT Wiki
Revision as of 21:22, 29 May 2007 by Stace (talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Contents

Using SSH keys in MCS

This page outlines the steps required to get your SSH keys in place to use MCS computing resources via SSH. We have tried to cover as many situations as is reasonable, but obviously, problems can occur. We have to handle a lot of these key installations in the regular operations of things, and more when there's a large influx of people. So we ask that you read over this information and, where appropriate, follow the steps outlined to get operational. If you do encounter problems, you can always ask us for help at systems@mcs.anl.gov.

Note: If you are using a registered host (the hostname ends with .mcs.anl.gov) on an MCS network, or are using the VPN, you do not *need* to use keys to access MCS workstation resources. You can ssh to fuzzy.mcs.anl.gov using your unix/e-mail password.


SSH is the main method that MCS supports for people to use to connect to MCS unix machines remotely.

When connecting to an MCS unix machine, you will need to provide information that demonstrates you are who you say you are. This is traditionally done by providing your username and your password. However, this is not quite secure enough, and so MCS is requiring that other methods be used. SSH supports several different methods, one of which is the use of "keys".

Without going into the details of the protocol,

this document will describe what you need to do to get your SSH program to use keys. This will involve generating and installing keys. Once these are in place, you can also use "agents" to reduce

the number of times you need to type a password. 

First: Preparing your MCS environment

All of the MCS environment steps require that you be able to login to an MCS workstation.  If you're onsite or using the VPN, you can use fuzzy.mcs.anl.gov and continue on to the steps below.  If not, or if fuzzy doesn't work for you, please visit <a href="https://www-accounts.mcs.anl.gov/account.php">https://www-accounts.mcs.anl.gov/account.php</a> and upload your public key or email it to <a href="mailto:systems@mcs.anl.gov">systems@mcs.anl.gov</a>.  (Note: If you e-mailed your key, please wait until you receive an e-mail confirming we have the key loaded into our system before you call.)  After you do that, call the Help Desk at (630) 252-6813 Monday - Friday, 9:00AM - 11:00AM or 1:00PM - 4:00PM to verify your identity and have that key moved to your authorized_keys file.  During the verification process you will need to read part of the public key to the help desk staff. Please have it available before contacting the help desk. 

Most likely, your MCS environment is already configured properly. Just in case, however, here are things you should check on your MCS home directory.

Your home directory on MCS cannot be writeable by anyone other than you.  On an MCS UNIX system, be sure this is the case with the following command:

chmod og-w ~

You also need a .ssh and .ssh/authorized keys directory.  To ensure this is in place:

mkdir ~/.ssh
touch ~/.ssh/authorized_keys
chmod -R 700 ~/.ssh

If you get an error on the mkdir command saying the directory already exists, that's okay.

Second: Prepare your client environment

You will need to install SSH keys on the machine that you use to login to MCS. This may be your laptop, your machine at home, a desktop at some other site, or any other computer not in the MCS UNIX space.

Follow the instructions below based on the kind of system you're using.


<a name="Other">Linux, MacOS X, Cygwin, and other UNIX variants</a>

STEP ONE: Generate keys.

The "ssh-keygen" command is used to create keys. There are many options for it. We recommend that you run it this way:

ssh-keygen -t rsa

This will create and store keys in your ~/.ssh directory. It will overwrite any existing keys as well. The default keytype in MCS is RSA for SSH 2. To generate this key (id_rsa), simply type "ssh-keygen -t rsa" and follow the prompts. WE REQUIRE THE USE OF A PASSPHRASE. There are a very limited number of circumstances where a key without a passphrase is acceptable. If you are in doubt, ask us. Just remember this: with a copy of your private key, if it has no passphrase, a person can ssh as you to any host to which you've allowed access without knowing a password or passphrase.  Needless to say, This Is Bad.

We recommend SSH2 (and in most cases require it), but if you need

to generate an SSH 1 key, the command is "ssh-keygen -t rsa1" which will create .ssh/identity.

Some machines may put these files in a different spot.  If

this is the case, make a note of where it puts them and what it

names them.

The id_rsa (and, if

they exist, id_dsa or identity) file is your private key.  Keep it secret, keep it safe.

STEP TWO: Put public key on MCS host.

Each of the commands above will generate an associated .pub file.

That's your public key. In order for you to tell a host that you want to authorize that private key to identify you, you need to give that host your public key. This is done via ~/.ssh/authorized_keys.

If your keys are on an MCS machine, then to add your MCS identities to your authorized keys file, it's as

simple as:

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

To add the SSH1 identity:

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

If the keys are on a different host, to add the public keys to an MCS host:

cat ~/.ssh/id_rsa.pub | ssh username@fuzzy.mcs.anl.gov 'cat - >> ~/.ssh/authorized_keys'

You will need to be onsite using a registered host or using the VPN for the above command to work.  If you are not, please visit <a href="https://www-accounts.mcs.anl.gov/account.php">https://www-accounts.mcs.anl.gov/account.php</a> and upload your public key and call the Help Desk at (630) 252-6813 to have that key moved to your authorized_keys file.  Don't send us e-mail asking to do it.  We need in-person of over-the-phone verification of identity before we do anything like that.

In all cases above, you need to create the authorized_keys file

if it doesn't yet exist.

At this point, if you ssh to the machine on which you added the

public key to the authorized_keys file, instead of being asked for a password, you'll see something like this:

% ssh joeblow@terra.mcs.anl.gov
Enter passphrase for key '/homes/stace/.ssh/id_rsa':

What I type at that prompt is not my password. It's the passphrase I used when I created that key. That passphrase is not stored anywhere. You're no longer using your password. However, we can still reduce the number of times you need to type the passphrase.

If your private key is named something other than the default,

the format for the ssh is:

% ssh -i /path/to/private/key joeblow@terra.mcs.anl.gov

STEP THREE (Optional): Agents

If you run an ssh-agent, it will remember the passphrase for your

key while it's running.

If you login to an MCS linux workstation locally through

X-Windows, an agent is launched automatically. If not, you can launch one by running:

eval `ssh-agent`

To add your keys to the agent:

ssh-add

If your keys have a non-standard name or path, you'll need to specify the full path after the ssh-add command.

You will be asked for the passphrase for your .ssh/id_rsa (and .ssh/identity, if applicable).

Now you can ssh to other machines that have your public key and

never have a password.

MacOS users can use GUI tools such as the following to manage keys and agents:

<a name="Windows">Windows</a>

If you use cygwin for SSH, see the unix instructions above. I recommend skimming the above section for background an insight on what the keys are for if you haven't already read it.

SecureCRT

If you use SecureCRT, the version of SecureCRT on the <a href="http://www.mcs.anl.gov/windows/software.html">windows

software page</a> supports keys. Simply generate your key by clicking "Tools", then "Generate Public Key". Follow the prompts (I currently recommend an RSA key, despite what the text above the selection box says). Choose a good passphrase, WE REQUIRE THE USE OF A PASSPHRASE. 1024 is an adequate key length. Make note of where it's installing the key. It's probably something like:

C:\Documents and Settings\USERNAME\Application Data\VanDyke\Identity

If you upgraded from an old version, it might be:

C:\Documents and Settings\USERNAME\Application Data\Van Dyke Technologies\Identity

Say "Yes" to the global public key question.

Now, the tricky part. SecureCRT stores your public key in a funky

format. To get it into the format OpenSSH recognizes:

  1. If you are on-site or using the VPN, log on to fuzzy.mcs.anl.gov using SSH2 and password authentication.  If not, please email the "Identity.pub" file you created to <a href="mailto:systems@mcs.anl.gov">systems@mcs.anl.gov</a> as per the instructions at the top of the page.  Then proceed to Step 6.
  2. If it does not already exist, you'll need to create your .ssh

    directory in your MCS unix home directory on the remote machine.  Type "mkdir ~/.ssh" followed by "chmod 700 ~/.ssh".

  3. On the local machine, use Notepad.exe to open the Identity.pub

    file that was created with the Key Generation wizard.

  4. With the Identity.pub file opened in the Notepad application,

    open the Edit menu and choose Select All. Once everything is selected, open the Edit menu again and select Copy.

  5. On the remote machine, complete the following steps:
    • % cat > ~/.ssh/windows-machine-name.ident (where "windows-machine-name" is the name of your machine)
    • Click on the SecureCRT paste button to paste the contents

      of the Clipboard (which should now contain the contents of your Identity.pub file).

    • Issue a CTRL+D to close the Identity.pub file.
    • Convert the key to one that OpenSSH will recognize using

      the following command:
      % ssh-keygen -i -f ~/.ssh/windows-machine-name.ident >> ~/.ssh/authorized_keys

  6. Make SecureCRT use the key.
    • Click "File" then "connect", and for each existing entry, in the list (or for new ones you add) click the "Properties" button (it looks like a hand holding a card).
    • In the Authentication section under "Connection",

      change "Primary" to be "PublicKey". Choose "Properties" and make sure it's using your global file.

    • Click "Options", "Global Options", and under

      SSH2 heading, check both boxes in the "Agent" section.

Now, the first SecureCRT session you open will ask the passphrase for the key you generated, and any subsequent ones will not (as long as SecureCRT is running.)

NOTE: If you converted a previously SSH1 session to use SSH2, check your port forwarding configuration.  It may have been messed up.  The checkbox for local IP address restrictions should be unchecked.  If it's not, uncheck it.

Putty

If you would like to use PuTTY as your ssh client, the first thing you should do is download the latest client. We have found that various older versions give funky problems when trying to use version2 keys. It only takes 10 seconds - no fancy installer, no rebooting.

Close any current PuTTY connections, move the current PuTTY executable (putty.exe) to the recycle bin, and download a new putty.exe from <a href="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">here</a>. Your current preferences and saved connections will not go away. When you open the new PuTTY, all those things will still be there.

While you are grabbing the latest client, also grab <a href="http://the.earth.li/%7Esgtatham/putty/latest/x86/puttygen.exe">PuTTYgen (puttygen.exe)</a>, which is the tool you will use to generate a new ssh key pair.

You can use PuTTYgen to load and convert an existing key you may have generated with OpenSSH to PuTTY's key format. See:

<a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Chapter8.html#8.2.12"> "Dealing with private keys in other formats"</a>. We will not cover that here. It is easier to simply generate a new key pair.

After downloading PuTTYgen, double-click on the PuTTYgen icon. At the very bottom of the dialog box, there is a section called "Parameters". Under "Type of key to generate:", click the radio button for "SSH2 RSA". Note the PuTTY default of "SSH1 (RSA)" will

  • not* work with most MCS systems, so you must do this step!

You may leave the "Number of bits in a generated key:" at the default value of 1024.

Now under "Actions" in the middle, click on the "Generate" button. Follow the directions of moving the mouse around in the blank section to generate randomness. It will then say "Please wait while a key is generated." This doesn't take long at all.

Part 1 - the public key goes in your MCS ~/.ssh/authorized_keys file:

Now you will see at the top your "Public key for pasting into OpenSSH authorized_keys file:". If you like, at this point you can change the "Key comment:" to add something like -<name of="" machine="" where="" generated="">. Now highlight that whole block of characters, including the first line of ssh-rsa, and Copy it to the clipboard in Windows

using CTRL-C. Don't shut the dialog box - there is more to do later.</name>

You can get this onto MCS Unix systems in two ways: go to <a href="https://www-accounts.mcs.anl.gov/account.php">the personal account management page</a>, log in, and paste the public key block into the SSH Public Key section and click on the "Update SSH Public Key" button. Follow the directions to call the HelpDesk at 630-252-6813 to get the key activated. Or, if you can come in through the VPN, do that, ssh to fuzzy using your plain Unix password, and then follow the directions under "First: Preparing your MCS environment" at the top of this page.  You can also email the key to systems@mcs.anl.gov, then call to verify your identity.

Next, open ~/.ssh/authorized_keys in your favorite editor, and

paste the public key block into the file (making sure it is all actually one single line of text, no returns). Exit the editor, saving the authorized_keys file.

You can also click on the "Save public key" button to save this text-block as a file locally on your Windows box, but this is just to have it around for later in case you want to file-transfer it somewhere later, or email it, etc.


Part 2 - saving the private key on your Windows machine:

You will definitely need to save the private key on your Windows box. To do this, first enter a "Key passphase" in the box provided, and re-type it to confirm in the "Confirm passphrase" box just below that. You will need to remember this passphrase! Make sure you choose a strong one. Then click on the "Save private key" button. You can name it whatever you want. It will be saved with a ".ppk" extension. Do not change this.

You are now done generating your key-pair, and may close the PuTTYgen dialog box.

Part 3 - setting up PuTTY to use keys and opening an SSH session

If you have used PuTTY before, double-click on the PuTTY icon to open the application. You can click on one of your previously saved sessions and hit the "load" button. But don't hit "Open" yet.

If you have not used PuTTY before, enter a hostname under "Hostname (or IP address)", like terra.mcs.anl.gov. Make sure the radio button for SSH is clicked, and the port says 22.

On the "Category" tree on the left-hand side of the dialog box, click on "Auth" under Connection->SSH->Auth. This should be "Options Controlling SSH Authentication". The only box that needs to be checked is "Attempt keyboard interactive auth (SSH2)". Under "Private key file for authentication:", click the "Browse..." button off to the right, and locate the .ppk file you saved earlier. Click "Open" and it will return you to the SSH Auth dialog box with the private key file location entered properly in the box.

Go back and click on "Session" at the top of the "Category" tree on the left side. You may want to name and save this session, so it will use keys from now on. Enter a short name under "Saved Sessions:" like terra. Then click the "Save" button.

You are now ready to click the "Open" button at the bottom to launch your SSH session using keys.

You will get a window that says:
login as: [Enter your Unix username]

Then it will say: Authenticating with public key "<name of the rsa key you created>"
Passphrase for key "<name of the rsa key you created>":

Enter the passphrase you used while saving your private key to this Windows box.

You're in!

For more information on using PuTTY, see <a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Contents.html">the PuTTY docs</a>, especially <a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Chapter8.html#8">Chapter 8</a> on SSH public keys.

Using SSH keys in MCS

       <p>This page outlines the steps required to get your SSH keys in place to use MCS computing resources via SSH.

We have tried to cover as many situations as is reasonable, but obviously, problems can occur. We have to handle a lot of these key installations in the regular operations of things, and more when there's a large influx of people. So we ask that you read over this information and, where appropriate, follow the steps outlined to get operational.

If you do encounter problems, you can always ask us for help at systems@mcs.anl.gov.

Note: If you are using a registered host (the hostname ends with .mcs.anl.gov) on an MCS network, or are using the VPN, you do not *need* to use keys to access MCS workstation resources. You can ssh to fuzzy.mcs.anl.gov using your unix/e-mail password.


SSH is the main method that MCS supports for people to use to connect to MCS unix machines remotely.

When connecting to an MCS unix machine, you will need to provide information that demonstrates you are who you say you are. This is traditionally done by providing your username and your password. However, this is not quite secure enough, and so MCS is requiring that other methods be used. SSH supports several different methods, one of which is the use of "keys".

Without going into the details of the protocol,

this document will describe what you need to do to get your SSH program to use keys. This will involve generating and installing keys. Once these are in place, you can also use "agents" to reduce

the number of times you need to type a password. 

First: Preparing your MCS environment

All of the MCS environment steps require that you be able to login to an MCS workstation.  If you're onsite or using the VPN, you can use fuzzy.mcs.anl.gov and continue on to the steps below.  If not, or if fuzzy doesn't work for you, please visit <a href="https://www-accounts.mcs.anl.gov/account.php">https://www-accounts.mcs.anl.gov/account.php</a> and upload your public key or email it to <a href="mailto:systems@mcs.anl.gov">systems@mcs.anl.gov</a>.  (Note: If you e-mailed your key, please wait until you receive an e-mail confirming we have the key loaded into our system before you call.)  After you do that, call the Help Desk at (630) 252-6813 Monday - Friday, 9:00AM - 11:00AM or 1:00PM - 4:00PM to verify your identity and have that key moved to your authorized_keys file.  During the verification process you will need to read part of the public key to the help desk staff. Please have it available before contacting the help desk. 

Most likely, your MCS environment is already configured properly. Just in case, however, here are things you should check on your MCS home directory.

Your home directory on MCS cannot be writeable by anyone other than you.  On an MCS UNIX system, be sure this is the case with the following command:

chmod og-w ~

You also need a .ssh and .ssh/authorized keys directory.  To ensure this is in place:

mkdir ~/.ssh
touch ~/.ssh/authorized_keys
chmod -R 700 ~/.ssh

If you get an error on the mkdir command saying the directory already exists, that's okay.

Second: Prepare your client environment

You will need to install SSH keys on the machine that you use to login to MCS. This may be your laptop, your machine at home, a desktop at some other site, or any other computer not in the MCS UNIX space.

Follow the instructions below based on the kind of system you're using.


<a name="Other">Linux, MacOS X, Cygwin, and other UNIX variants</a>

STEP ONE: Generate keys.

The "ssh-keygen" command is used to create keys. There are many options for it. We recommend that you run it this way:

ssh-keygen -t rsa

This will create and store keys in your ~/.ssh directory. It will overwrite any existing keys as well. The default keytype in MCS is RSA for SSH 2. To generate this key (id_rsa), simply type "ssh-keygen -t rsa" and follow the prompts. WE REQUIRE THE USE OF A PASSPHRASE. There are a very limited number of circumstances where a key without a passphrase is acceptable. If you are in doubt, ask us. Just remember this: with a copy of your private key, if it has no passphrase, a person can ssh as you to any host to which you've allowed access without knowing a password or passphrase.  Needless to say, This Is Bad.

We recommend SSH2 (and in most cases require it), but if you need

to generate an SSH 1 key, the command is "ssh-keygen -t rsa1" which will create .ssh/identity.

Some machines may put these files in a different spot.  If

this is the case, make a note of where it puts them and what it

names them.

The id_rsa (and, if

they exist, id_dsa or identity) file is your private key.  Keep it secret, keep it safe.

STEP TWO: Put public key on MCS host.

Each of the commands above will generate an associated .pub file.

That's your public key. In order for you to tell a host that you want to authorize that private key to identify you, you need to give that host your public key. This is done via ~/.ssh/authorized_keys.

If your keys are on an MCS machine, then to add your MCS identities to your authorized keys file, it's as

simple as:

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

To add the SSH1 identity:

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

If the keys are on a different host, to add the public keys to an MCS host:

cat ~/.ssh/id_rsa.pub | ssh username@fuzzy.mcs.anl.gov 'cat - >> ~/.ssh/authorized_keys'

You will need to be onsite using a registered host or using the VPN for the above command to work.  If you are not, please visit <a href="https://www-accounts.mcs.anl.gov/account.php">https://www-accounts.mcs.anl.gov/account.php</a> and upload your public key and call the Help Desk at (630) 252-6813 to have that key moved to your authorized_keys file.  Don't send us e-mail asking to do it.  We need in-person of over-the-phone verification of identity before we do anything like that.

In all cases above, you need to create the authorized_keys file

if it doesn't yet exist.

At this point, if you ssh to the machine on which you added the

public key to the authorized_keys file, instead of being asked for a password, you'll see something like this:

% ssh joeblow@terra.mcs.anl.gov
Enter passphrase for key '/homes/stace/.ssh/id_rsa':

What I type at that prompt is not my password. It's the passphrase I used when I created that key. That passphrase is not stored anywhere. You're no longer using your password. However, we can still reduce the number of times you need to type the passphrase.

If your private key is named something other than the default,

the format for the ssh is:

% ssh -i /path/to/private/key joeblow@terra.mcs.anl.gov

STEP THREE (Optional): Agents

If you run an ssh-agent, it will remember the passphrase for your

key while it's running.

If you login to an MCS linux workstation locally through

X-Windows, an agent is launched automatically. If not, you can launch one by running:

eval `ssh-agent`

To add your keys to the agent:

ssh-add

If your keys have a non-standard name or path, you'll need to specify the full path after the ssh-add command.

You will be asked for the passphrase for your .ssh/id_rsa (and .ssh/identity, if applicable).

Now you can ssh to other machines that have your public key and

never have a password.

MacOS users can use GUI tools such as the following to manage keys and agents:

<a name="Windows">Windows</a>

If you use cygwin for SSH, see the unix instructions above. I recommend skimming the above section for background an insight on what the keys are for if you haven't already read it.

SecureCRT

If you use SecureCRT, the version of SecureCRT on the <a href="http://www.mcs.anl.gov/windows/software.html">windows

software page</a> supports keys. Simply generate your key by clicking "Tools", then "Generate Public Key". Follow the prompts (I currently recommend an RSA key, despite what the text above the selection box says). Choose a good passphrase, WE REQUIRE THE USE OF A PASSPHRASE. 1024 is an adequate key length. Make note of where it's installing the key. It's probably something like:

C:\Documents and Settings\USERNAME\Application Data\VanDyke\Identity

If you upgraded from an old version, it might be:

C:\Documents and Settings\USERNAME\Application Data\Van Dyke Technologies\Identity

Say "Yes" to the global public key question.

Now, the tricky part. SecureCRT stores your public key in a funky

format. To get it into the format OpenSSH recognizes:

  1. If you are on-site or using the VPN, log on to fuzzy.mcs.anl.gov using SSH2 and password authentication.  If not, please email the "Identity.pub" file you created to <a href="mailto:systems@mcs.anl.gov">systems@mcs.anl.gov</a> as per the instructions at the top of the page.  Then proceed to Step 6.
  2. If it does not already exist, you'll need to create your .ssh

    directory in your MCS unix home directory on the remote machine.  Type "mkdir ~/.ssh" followed by "chmod 700 ~/.ssh".

  3. On the local machine, use Notepad.exe to open the Identity.pub

    file that was created with the Key Generation wizard.

  4. With the Identity.pub file opened in the Notepad application,

    open the Edit menu and choose Select All. Once everything is selected, open the Edit menu again and select Copy.

  5. On the remote machine, complete the following steps:
    • % cat > ~/.ssh/windows-machine-name.ident (where "windows-machine-name" is the name of your machine)
    • Click on the SecureCRT paste button to paste the contents

      of the Clipboard (which should now contain the contents of your Identity.pub file).

    • Issue a CTRL+D to close the Identity.pub file.
    • Convert the key to one that OpenSSH will recognize using

      the following command:
      % ssh-keygen -i -f ~/.ssh/windows-machine-name.ident >> ~/.ssh/authorized_keys

  6. Make SecureCRT use the key.
    • Click "File" then "connect", and for each existing entry, in the list (or for new ones you add) click the "Properties" button (it looks like a hand holding a card).
    • In the Authentication section under "Connection",

      change "Primary" to be "PublicKey". Choose "Properties" and make sure it's using your global file.

    • Click "Options", "Global Options", and under

      SSH2 heading, check both boxes in the "Agent" section.

Now, the first SecureCRT session you open will ask the passphrase for the key you generated, and any subsequent ones will not (as long as SecureCRT is running.)

NOTE: If you converted a previously SSH1 session to use SSH2, check your port forwarding configuration.  It may have been messed up.  The checkbox for local IP address restrictions should be unchecked.  If it's not, uncheck it.

Putty

If you would like to use PuTTY as your ssh client, the first thing you should do is download the latest client. We have found that various older versions give funky problems when trying to use version2 keys. It only takes 10 seconds - no fancy installer, no rebooting.

Close any current PuTTY connections, move the current PuTTY executable (putty.exe) to the recycle bin, and download a new putty.exe from <a href="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">here</a>. Your current preferences and saved connections will not go away. When you open the new PuTTY, all those things will still be there.

While you are grabbing the latest client, also grab <a href="http://the.earth.li/%7Esgtatham/putty/latest/x86/puttygen.exe">PuTTYgen (puttygen.exe)</a>, which is the tool you will use to generate a new ssh key pair.

You can use PuTTYgen to load and convert an existing key you may have generated with OpenSSH to PuTTY's key format. See:

<a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Chapter8.html#8.2.12"> "Dealing with private keys in other formats"</a>. We will not cover that here. It is easier to simply generate a new key pair.

After downloading PuTTYgen, double-click on the PuTTYgen icon. At the very bottom of the dialog box, there is a section called "Parameters". Under "Type of key to generate:", click the radio button for "SSH2 RSA". Note the PuTTY default of "SSH1 (RSA)" will

  • not* work with most MCS systems, so you must do this step!

You may leave the "Number of bits in a generated key:" at the default value of 1024.

Now under "Actions" in the middle, click on the "Generate" button. Follow the directions of moving the mouse around in the blank section to generate randomness. It will then say "Please wait while a key is generated." This doesn't take long at all.

Part 1 - the public key goes in your MCS ~/.ssh/authorized_keys file:

Now you will see at the top your "Public key for pasting into OpenSSH authorized_keys file:". If you like, at this point you can change the "Key comment:" to add something like -<name of="" machine="" where="" generated="">. Now highlight that whole block of characters, including the first line of ssh-rsa, and Copy it to the clipboard in Windows

using CTRL-C. Don't shut the dialog box - there is more to do later.</name>

You can get this onto MCS Unix systems in two ways: go to <a href="https://www-accounts.mcs.anl.gov/account.php">the personal account management page</a>, log in, and paste the public key block into the SSH Public Key section and click on the "Update SSH Public Key" button. Follow the directions to call the HelpDesk at 630-252-6813 to get the key activated. Or, if you can come in through the VPN, do that, ssh to fuzzy using your plain Unix password, and then follow the directions under "First: Preparing your MCS environment" at the top of this page.  You can also email the key to systems@mcs.anl.gov, then call to verify your identity.

Next, open ~/.ssh/authorized_keys in your favorite editor, and

paste the public key block into the file (making sure it is all actually one single line of text, no returns). Exit the editor, saving the authorized_keys file.

You can also click on the "Save public key" button to save this text-block as a file locally on your Windows box, but this is just to have it around for later in case you want to file-transfer it somewhere later, or email it, etc.


Part 2 - saving the private key on your Windows machine:

You will definitely need to save the private key on your Windows box. To do this, first enter a "Key passphase" in the box provided, and re-type it to confirm in the "Confirm passphrase" box just below that. You will need to remember this passphrase! Make sure you choose a strong one. Then click on the "Save private key" button. You can name it whatever you want. It will be saved with a ".ppk" extension. Do not change this.

You are now done generating your key-pair, and may close the PuTTYgen dialog box.

Part 3 - setting up PuTTY to use keys and opening an SSH session

If you have used PuTTY before, double-click on the PuTTY icon to open the application. You can click on one of your previously saved sessions and hit the "load" button. But don't hit "Open" yet.

If you have not used PuTTY before, enter a hostname under "Hostname (or IP address)", like terra.mcs.anl.gov. Make sure the radio button for SSH is clicked, and the port says 22.

On the "Category" tree on the left-hand side of the dialog box, click on "Auth" under Connection->SSH->Auth. This should be "Options Controlling SSH Authentication". The only box that needs to be checked is "Attempt keyboard interactive auth (SSH2)". Under "Private key file for authentication:", click the "Browse..." button off to the right, and locate the .ppk file you saved earlier. Click "Open" and it will return you to the SSH Auth dialog box with the private key file location entered properly in the box.

Go back and click on "Session" at the top of the "Category" tree on the left side. You may want to name and save this session, so it will use keys from now on. Enter a short name under "Saved Sessions:" like terra. Then click the "Save" button.

You are now ready to click the "Open" button at the bottom to launch your SSH session using keys.

You will get a window that says:
login as: [Enter your Unix username]

Then it will say: Authenticating with public key "<name of the rsa key you created>"
Passphrase for key "<name of the rsa key you created>":

Enter the passphrase you used while saving your private key to this Windows box.

You're in!

For more information on using PuTTY, see <a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Contents.html">the PuTTY docs</a>, especially <a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Chapter8.html#8">Chapter 8</a> on SSH public keys.

Using SSH keys in MCS

This page outlines the steps required to get your SSH keys in place to use MCS computing resources via SSH. We have tried to cover as many situations as is reasonable, but obviously, problems can occur. We have to handle a lot of these key installations in the regular operations of things, and more when there's a large influx of people. So we ask that you read over this information and, where appropriate, follow the steps outlined to get operational. If you do encounter problems, you can always ask us for help at systems@mcs.anl.gov.

Note: If you are using a registered host (the hostname ends with .mcs.anl.gov) on an MCS network, or are using the VPN, you do not *need* to use keys to access MCS workstation resources. You can ssh to fuzzy.mcs.anl.gov using your unix/e-mail password.


SSH is the main method that MCS supports for people to use to connect to MCS unix machines remotely.

When connecting to an MCS unix machine, you will need to provide information that demonstrates you are who you say you are. This is traditionally done by providing your username and your password. However, this is not quite secure enough, and so MCS is requiring that other methods be used. SSH supports several different methods, one of which is the use of "keys".

Without going into the details of the protocol,

this document will describe what you need to do to get your SSH program to use keys. This will involve generating and installing keys. Once these are in place, you can also use "agents" to reduce

the number of times you need to type a password. 

First: Preparing your MCS environment

All of the MCS environment steps require that you be able to login to an MCS workstation.  If you're onsite or using the VPN, you can use fuzzy.mcs.anl.gov and continue on to the steps below.  If not, or if fuzzy doesn't work for you, please visit <a href="https://www-accounts.mcs.anl.gov/account.php">https://www-accounts.mcs.anl.gov/account.php</a> and upload your public key or email it to <a href="mailto:systems@mcs.anl.gov">systems@mcs.anl.gov</a>.  (Note: If you e-mailed your key, please wait until you receive an e-mail confirming we have the key loaded into our system before you call.)  After you do that, call the Help Desk at (630) 252-6813 Monday - Friday, 9:00AM - 11:00AM or 1:00PM - 4:00PM to verify your identity and have that key moved to your authorized_keys file.  During the verification process you will need to read part of the public key to the help desk staff. Please have it available before contacting the help desk. 

Most likely, your MCS environment is already configured properly. Just in case, however, here are things you should check on your MCS home directory.

Your home directory on MCS cannot be writeable by anyone other than you.  On an MCS UNIX system, be sure this is the case with the following command:

chmod og-w ~

You also need a .ssh and .ssh/authorized keys directory.  To ensure this is in place:

mkdir ~/.ssh
touch ~/.ssh/authorized_keys
chmod -R 700 ~/.ssh

If you get an error on the mkdir command saying the directory already exists, that's okay.

Second: Prepare your client environment

You will need to install SSH keys on the machine that you use to login to MCS. This may be your laptop, your machine at home, a desktop at some other site, or any other computer not in the MCS UNIX space.

Follow the instructions below based on the kind of system you're using.


<a name="Other">Linux, MacOS X, Cygwin, and other UNIX variants</a>

STEP ONE: Generate keys.

The "ssh-keygen" command is used to create keys. There are many options for it. We recommend that you run it this way:

ssh-keygen -t rsa

This will create and store keys in your ~/.ssh directory. It will overwrite any existing keys as well. The default keytype in MCS is RSA for SSH 2. To generate this key (id_rsa), simply type "ssh-keygen -t rsa" and follow the prompts. WE REQUIRE THE USE OF A PASSPHRASE. There are a very limited number of circumstances where a key without a passphrase is acceptable. If you are in doubt, ask us. Just remember this: with a copy of your private key, if it has no passphrase, a person can ssh as you to any host to which you've allowed access without knowing a password or passphrase.  Needless to say, This Is Bad.

We recommend SSH2 (and in most cases require it), but if you need

to generate an SSH 1 key, the command is "ssh-keygen -t rsa1" which will create .ssh/identity.

Some machines may put these files in a different spot.  If

this is the case, make a note of where it puts them and what it

names them.

The id_rsa (and, if

they exist, id_dsa or identity) file is your private key.  Keep it secret, keep it safe.

STEP TWO: Put public key on MCS host.

Each of the commands above will generate an associated .pub file.

That's your public key. In order for you to tell a host that you want to authorize that private key to identify you, you need to give that host your public key. This is done via ~/.ssh/authorized_keys.

If your keys are on an MCS machine, then to add your MCS identities to your authorized keys file, it's as

simple as:

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

To add the SSH1 identity:

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

If the keys are on a different host, to add the public keys to an MCS host:

cat ~/.ssh/id_rsa.pub | ssh username@fuzzy.mcs.anl.gov 'cat - >> ~/.ssh/authorized_keys'

You will need to be onsite using a registered host or using the VPN for the above command to work.  If you are not, please visit <a href="https://www-accounts.mcs.anl.gov/account.php">https://www-accounts.mcs.anl.gov/account.php</a> and upload your public key and call the Help Desk at (630) 252-6813 to have that key moved to your authorized_keys file.  Don't send us e-mail asking to do it.  We need in-person of over-the-phone verification of identity before we do anything like that.

In all cases above, you need to create the authorized_keys file

if it doesn't yet exist.

At this point, if you ssh to the machine on which you added the

public key to the authorized_keys file, instead of being asked for a password, you'll see something like this:

% ssh joeblow@terra.mcs.anl.gov
Enter passphrase for key '/homes/stace/.ssh/id_rsa':

What I type at that prompt is not my password. It's the passphrase I used when I created that key. That passphrase is not stored anywhere. You're no longer using your password. However, we can still reduce the number of times you need to type the passphrase.

If your private key is named something other than the default,

the format for the ssh is:

% ssh -i /path/to/private/key joeblow@terra.mcs.anl.gov

STEP THREE (Optional): Agents

If you run an ssh-agent, it will remember the passphrase for your

key while it's running.

If you login to an MCS linux workstation locally through

X-Windows, an agent is launched automatically. If not, you can launch one by running:

eval `ssh-agent`

To add your keys to the agent:

ssh-add

If your keys have a non-standard name or path, you'll need to specify the full path after the ssh-add command.

You will be asked for the passphrase for your .ssh/id_rsa (and .ssh/identity, if applicable).

Now you can ssh to other machines that have your public key and

never have a password.

MacOS users can use GUI tools such as the following to manage keys and agents:

<a name="Windows">Windows</a>

If you use cygwin for SSH, see the unix instructions above. I recommend skimming the above section for background an insight on what the keys are for if you haven't already read it.

SecureCRT

If you use SecureCRT, the version of SecureCRT on the <a href="http://www.mcs.anl.gov/windows/software.html">windows

software page</a> supports keys. Simply generate your key by clicking "Tools", then "Generate Public Key". Follow the prompts (I currently recommend an RSA key, despite what the text above the selection box says). Choose a good passphrase, WE REQUIRE THE USE OF A PASSPHRASE. 1024 is an adequate key length. Make note of where it's installing the key. It's probably something like:

C:\Documents and Settings\USERNAME\Application Data\VanDyke\Identity

If you upgraded from an old version, it might be:

C:\Documents and Settings\USERNAME\Application Data\Van Dyke Technologies\Identity

Say "Yes" to the global public key question.

Now, the tricky part. SecureCRT stores your public key in a funky

format. To get it into the format OpenSSH recognizes:

  1. If you are on-site or using the VPN, log on to fuzzy.mcs.anl.gov using SSH2 and password authentication.  If not, please email the "Identity.pub" file you created to <a href="mailto:systems@mcs.anl.gov">systems@mcs.anl.gov</a> as per the instructions at the top of the page.  Then proceed to Step 6.
  2. If it does not already exist, you'll need to create your .ssh

    directory in your MCS unix home directory on the remote machine.  Type "mkdir ~/.ssh" followed by "chmod 700 ~/.ssh".

  3. On the local machine, use Notepad.exe to open the Identity.pub

    file that was created with the Key Generation wizard.

  4. With the Identity.pub file opened in the Notepad application,

    open the Edit menu and choose Select All. Once everything is selected, open the Edit menu again and select Copy.

  5. On the remote machine, complete the following steps:
    • % cat > ~/.ssh/windows-machine-name.ident (where "windows-machine-name" is the name of your machine)
    • Click on the SecureCRT paste button to paste the contents

      of the Clipboard (which should now contain the contents of your Identity.pub file).

    • Issue a CTRL+D to close the Identity.pub file.
    • Convert the key to one that OpenSSH will recognize using

      the following command:
      % ssh-keygen -i -f ~/.ssh/windows-machine-name.ident >> ~/.ssh/authorized_keys

  6. Make SecureCRT use the key.
    • Click "File" then "connect", and for each existing entry, in the list (or for new ones you add) click the "Properties" button (it looks like a hand holding a card).
    • In the Authentication section under "Connection",

      change "Primary" to be "PublicKey". Choose "Properties" and make sure it's using your global file.

    • Click "Options", "Global Options", and under

      SSH2 heading, check both boxes in the "Agent" section.

Now, the first SecureCRT session you open will ask the passphrase for the key you generated, and any subsequent ones will not (as long as SecureCRT is running.)

NOTE: If you converted a previously SSH1 session to use SSH2, check your port forwarding configuration.  It may have been messed up.  The checkbox for local IP address restrictions should be unchecked.  If it's not, uncheck it.

Putty

If you would like to use PuTTY as your ssh client, the first thing you should do is download the latest client. We have found that various older versions give funky problems when trying to use version2 keys. It only takes 10 seconds - no fancy installer, no rebooting.

Close any current PuTTY connections, move the current PuTTY executable (putty.exe) to the recycle bin, and download a new putty.exe from <a href="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">here</a>. Your current preferences and saved connections will not go away. When you open the new PuTTY, all those things will still be there.

While you are grabbing the latest client, also grab <a href="http://the.earth.li/%7Esgtatham/putty/latest/x86/puttygen.exe">PuTTYgen (puttygen.exe)</a>, which is the tool you will use to generate a new ssh key pair.

You can use PuTTYgen to load and convert an existing key you may have generated with OpenSSH to PuTTY's key format. See:

<a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Chapter8.html#8.2.12"> "Dealing with private keys in other formats"</a>. We will not cover that here. It is easier to simply generate a new key pair.

After downloading PuTTYgen, double-click on the PuTTYgen icon. At the very bottom of the dialog box, there is a section called "Parameters". Under "Type of key to generate:", click the radio button for "SSH2 RSA". Note the PuTTY default of "SSH1 (RSA)" will

  • not* work with most MCS systems, so you must do this step!

You may leave the "Number of bits in a generated key:" at the default value of 1024.

Now under "Actions" in the middle, click on the "Generate" button. Follow the directions of moving the mouse around in the blank section to generate randomness. It will then say "Please wait while a key is generated." This doesn't take long at all.

Part 1 - the public key goes in your MCS ~/.ssh/authorized_keys file:

Now you will see at the top your "Public key for pasting into OpenSSH authorized_keys file:". If you like, at this point you can change the "Key comment:" to add something like -<name of="" machine="" where="" generated="">. Now highlight that whole block of characters, including the first line of ssh-rsa, and Copy it to the clipboard in Windows

using CTRL-C. Don't shut the dialog box - there is more to do later.</name>

You can get this onto MCS Unix systems in two ways: go to <a href="https://www-accounts.mcs.anl.gov/account.php">the personal account management page</a>, log in, and paste the public key block into the SSH Public Key section and click on the "Update SSH Public Key" button. Follow the directions to call the HelpDesk at 630-252-6813 to get the key activated. Or, if you can come in through the VPN, do that, ssh to fuzzy using your plain Unix password, and then follow the directions under "First: Preparing your MCS environment" at the top of this page.  You can also email the key to systems@mcs.anl.gov, then call to verify your identity.

Next, open ~/.ssh/authorized_keys in your favorite editor, and

paste the public key block into the file (making sure it is all actually one single line of text, no returns). Exit the editor, saving the authorized_keys file.

You can also click on the "Save public key" button to save this text-block as a file locally on your Windows box, but this is just to have it around for later in case you want to file-transfer it somewhere later, or email it, etc.


Part 2 - saving the private key on your Windows machine:

You will definitely need to save the private key on your Windows box. To do this, first enter a "Key passphase" in the box provided, and re-type it to confirm in the "Confirm passphrase" box just below that. You will need to remember this passphrase! Make sure you choose a strong one. Then click on the "Save private key" button. You can name it whatever you want. It will be saved with a ".ppk" extension. Do not change this.

You are now done generating your key-pair, and may close the PuTTYgen dialog box.

Part 3 - setting up PuTTY to use keys and opening an SSH session

If you have used PuTTY before, double-click on the PuTTY icon to open the application. You can click on one of your previously saved sessions and hit the "load" button. But don't hit "Open" yet.

If you have not used PuTTY before, enter a hostname under "Hostname (or IP address)", like terra.mcs.anl.gov. Make sure the radio button for SSH is clicked, and the port says 22.

On the "Category" tree on the left-hand side of the dialog box, click on "Auth" under Connection->SSH->Auth. This should be "Options Controlling SSH Authentication". The only box that needs to be checked is "Attempt keyboard interactive auth (SSH2)". Under "Private key file for authentication:", click the "Browse..." button off to the right, and locate the .ppk file you saved earlier. Click "Open" and it will return you to the SSH Auth dialog box with the private key file location entered properly in the box.

Go back and click on "Session" at the top of the "Category" tree on the left side. You may want to name and save this session, so it will use keys from now on. Enter a short name under "Saved Sessions:" like terra. Then click the "Save" button.

You are now ready to click the "Open" button at the bottom to launch your SSH session using keys.

You will get a window that says:
login as: [Enter your Unix username]

Then it will say: Authenticating with public key "<name of the rsa key you created>"
Passphrase for key "<name of the rsa key you created>":

Enter the passphrase you used while saving your private key to this Windows box.

You're in!

For more information on using PuTTY, see <a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Contents.html">the PuTTY docs</a>, especially <a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Chapter8.html#8">Chapter 8</a> on SSH public keys.

Using SSH keys in MCS

This page outlines the steps required to get your SSH keys in place to use MCS computing resources via SSH. We have tried to cover as many situations as is reasonable, but obviously, problems can occur. We have to handle a lot of these key installations in the regular operations of things, and more when there's a large influx of people. So we ask that you read over this information and, where appropriate, follow the steps outlined to get operational. If you do encounter problems, you can always ask us for help at systems@mcs.anl.gov.

Note: If you are using a registered host (the hostname ends with .mcs.anl.gov) on an MCS network, or are using the VPN, you do not *need* to use keys to access MCS workstation resources. You can ssh to fuzzy.mcs.anl.gov using your unix/e-mail password.


SSH is the main method that MCS supports for people to use to connect to MCS unix machines remotely.

When connecting to an MCS unix machine, you will need to provide information that demonstrates you are who you say you are. This is traditionally done by providing your username and your password. However, this is not quite secure enough, and so MCS is requiring that other methods be used. SSH supports several different methods, one of which is the use of "keys".

Without going into the details of the protocol,

this document will describe what you need to do to get your SSH program to use keys. This will involve generating and installing keys. Once these are in place, you can also use "agents" to reduce

the number of times you need to type a password. 

First: Preparing your MCS environment

All of the MCS environment steps require that you be able to login to an MCS workstation.  If you're onsite or using the VPN, you can use fuzzy.mcs.anl.gov and continue on to the steps below.  If not, or if fuzzy doesn't work for you, please visit <a href="https://www-accounts.mcs.anl.gov/account.php">https://www-accounts.mcs.anl.gov/account.php</a> and upload your public key or email it to <a href="mailto:systems@mcs.anl.gov">systems@mcs.anl.gov</a>.  (Note: If you e-mailed your key, please wait until you receive an e-mail confirming we have the key loaded into our system before you call.)  After you do that, call the Help Desk at (630) 252-6813 Monday - Friday, 9:00AM - 11:00AM or 1:00PM - 4:00PM to verify your identity and have that key moved to your authorized_keys file.  During the verification process you will need to read part of the public key to the help desk staff. Please have it available before contacting the help desk. 

Most likely, your MCS environment is already configured properly. Just in case, however, here are things you should check on your MCS home directory.

Your home directory on MCS cannot be writeable by anyone other than you.  On an MCS UNIX system, be sure this is the case with the following command:

chmod og-w ~

You also need a .ssh and .ssh/authorized keys directory.  To ensure this is in place:

mkdir ~/.ssh
touch ~/.ssh/authorized_keys
chmod -R 700 ~/.ssh

If you get an error on the mkdir command saying the directory already exists, that's okay.

Second: Prepare your client environment

You will need to install SSH keys on the machine that you use to login to MCS. This may be your laptop, your machine at home, a desktop at some other site, or any other computer not in the MCS UNIX space.

Follow the instructions below based on the kind of system you're using.


<a name="Other">Linux, MacOS X, Cygwin, and other UNIX variants</a>

STEP ONE: Generate keys.

The "ssh-keygen" command is used to create keys. There are many options for it. We recommend that you run it this way:

ssh-keygen -t rsa

This will create and store keys in your ~/.ssh directory. It will overwrite any existing keys as well. The default keytype in MCS is RSA for SSH 2. To generate this key (id_rsa), simply type "ssh-keygen -t rsa" and follow the prompts. WE REQUIRE THE USE OF A PASSPHRASE. There are a very limited number of circumstances where a key without a passphrase is acceptable. If you are in doubt, ask us. Just remember this: with a copy of your private key, if it has no passphrase, a person can ssh as you to any host to which you've allowed access without knowing a password or passphrase.  Needless to say, This Is Bad.

We recommend SSH2 (and in most cases require it), but if you need

to generate an SSH 1 key, the command is "ssh-keygen -t rsa1" which will create .ssh/identity.

Some machines may put these files in a different spot.  If

this is the case, make a note of where it puts them and what it

names them.

The id_rsa (and, if

they exist, id_dsa or identity) file is your private key.  Keep it secret, keep it safe.

STEP TWO: Put public key on MCS host.

Each of the commands above will generate an associated .pub file.

That's your public key. In order for you to tell a host that you want to authorize that private key to identify you, you need to give that host your public key. This is done via ~/.ssh/authorized_keys.

If your keys are on an MCS machine, then to add your MCS identities to your authorized keys file, it's as

simple as:

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

To add the SSH1 identity:

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

If the keys are on a different host, to add the public keys to an MCS host:

cat ~/.ssh/id_rsa.pub | ssh username@fuzzy.mcs.anl.gov 'cat - >> ~/.ssh/authorized_keys'

You will need to be onsite using a registered host or using the VPN for the above command to work.  If you are not, please visit <a href="https://www-accounts.mcs.anl.gov/account.php">https://www-accounts.mcs.anl.gov/account.php</a> and upload your public key and call the Help Desk at (630) 252-6813 to have that key moved to your authorized_keys file.  Don't send us e-mail asking to do it.  We need in-person of over-the-phone verification of identity before we do anything like that.

In all cases above, you need to create the authorized_keys file

if it doesn't yet exist.

At this point, if you ssh to the machine on which you added the

public key to the authorized_keys file, instead of being asked for a password, you'll see something like this:

% ssh joeblow@terra.mcs.anl.gov
Enter passphrase for key '/homes/stace/.ssh/id_rsa':

What I type at that prompt is not my password. It's the passphrase I used when I created that key. That passphrase is not stored anywhere. You're no longer using your password. However, we can still reduce the number of times you need to type the passphrase.

If your private key is named something other than the default,

the format for the ssh is:

% ssh -i /path/to/private/key joeblow@terra.mcs.anl.gov

STEP THREE (Optional): Agents

If you run an ssh-agent, it will remember the passphrase for your

key while it's running.

If you login to an MCS linux workstation locally through

X-Windows, an agent is launched automatically. If not, you can launch one by running:

eval `ssh-agent`

To add your keys to the agent:

ssh-add

If your keys have a non-standard name or path, you'll need to specify the full path after the ssh-add command.

You will be asked for the passphrase for your .ssh/id_rsa (and .ssh/identity, if applicable).

Now you can ssh to other machines that have your public key and

never have a password.

MacOS users can use GUI tools such as the following to manage keys and agents:

<a name="Windows">Windows</a>

If you use cygwin for SSH, see the unix instructions above. I recommend skimming the above section for background an insight on what the keys are for if you haven't already read it.

SecureCRT

If you use SecureCRT, the version of SecureCRT on the <a href="http://www.mcs.anl.gov/windows/software.html">windows

software page</a> supports keys. Simply generate your key by clicking "Tools", then "Generate Public Key". Follow the prompts (I currently recommend an RSA key, despite what the text above the selection box says). Choose a good passphrase, WE REQUIRE THE USE OF A PASSPHRASE. 1024 is an adequate key length. Make note of where it's installing the key. It's probably something like:

C:\Documents and Settings\USERNAME\Application Data\VanDyke\Identity

If you upgraded from an old version, it might be:

C:\Documents and Settings\USERNAME\Application Data\Van Dyke Technologies\Identity

Say "Yes" to the global public key question.

Now, the tricky part. SecureCRT stores your public key in a funky

format. To get it into the format OpenSSH recognizes:

  1. If you are on-site or using the VPN, log on to fuzzy.mcs.anl.gov using SSH2 and password authentication.  If not, please email the "Identity.pub" file you created to <a href="mailto:systems@mcs.anl.gov">systems@mcs.anl.gov</a> as per the instructions at the top of the page.  Then proceed to Step 6.
  2. If it does not already exist, you'll need to create your .ssh

    directory in your MCS unix home directory on the remote machine.  Type "mkdir ~/.ssh" followed by "chmod 700 ~/.ssh".

  3. On the local machine, use Notepad.exe to open the Identity.pub

    file that was created with the Key Generation wizard.

  4. With the Identity.pub file opened in the Notepad application,

    open the Edit menu and choose Select All. Once everything is selected, open the Edit menu again and select Copy.

  5. On the remote machine, complete the following steps:
    • % cat > ~/.ssh/windows-machine-name.ident (where "windows-machine-name" is the name of your machine)
    • Click on the SecureCRT paste button to paste the contents

      of the Clipboard (which should now contain the contents of your Identity.pub file).

    • Issue a CTRL+D to close the Identity.pub file.
    • Convert the key to one that OpenSSH will recognize using

      the following command:
      % ssh-keygen -i -f ~/.ssh/windows-machine-name.ident >> ~/.ssh/authorized_keys

  6. Make SecureCRT use the key.
    • Click "File" then "connect", and for each existing entry, in the list (or for new ones you add) click the "Properties" button (it looks like a hand holding a card).
    • In the Authentication section under "Connection",

      change "Primary" to be "PublicKey". Choose "Properties" and make sure it's using your global file.

    • Click "Options", "Global Options", and under

      SSH2 heading, check both boxes in the "Agent" section.

Now, the first SecureCRT session you open will ask the passphrase for the key you generated, and any subsequent ones will not (as long as SecureCRT is running.)

NOTE: If you converted a previously SSH1 session to use SSH2, check your port forwarding configuration.  It may have been messed up.  The checkbox for local IP address restrictions should be unchecked.  If it's not, uncheck it.

Putty

If you would like to use PuTTY as your ssh client, the first thing you should do is download the latest client. We have found that various older versions give funky problems when trying to use version2 keys. It only takes 10 seconds - no fancy installer, no rebooting.

Close any current PuTTY connections, move the current PuTTY executable (putty.exe) to the recycle bin, and download a new putty.exe from <a href="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">here</a>. Your current preferences and saved connections will not go away. When you open the new PuTTY, all those things will still be there.

While you are grabbing the latest client, also grab <a href="http://the.earth.li/%7Esgtatham/putty/latest/x86/puttygen.exe">PuTTYgen (puttygen.exe)</a>, which is the tool you will use to generate a new ssh key pair.

You can use PuTTYgen to load and convert an existing key you may have generated with OpenSSH to PuTTY's key format. See:

<a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Chapter8.html#8.2.12"> "Dealing with private keys in other formats"</a>. We will not cover that here. It is easier to simply generate a new key pair.

After downloading PuTTYgen, double-click on the PuTTYgen icon. At the very bottom of the dialog box, there is a section called "Parameters". Under "Type of key to generate:", click the radio button for "SSH2 RSA". Note the PuTTY default of "SSH1 (RSA)" will

  • not* work with most MCS systems, so you must do this step!

You may leave the "Number of bits in a generated key:" at the default value of 1024.

Now under "Actions" in the middle, click on the "Generate" button. Follow the directions of moving the mouse around in the blank section to generate randomness. It will then say "Please wait while a key is generated." This doesn't take long at all.

Part 1 - the public key goes in your MCS ~/.ssh/authorized_keys file:

Now you will see at the top your "Public key for pasting into OpenSSH authorized_keys file:". If you like, at this point you can change the "Key comment:" to add something like -<name of="" machine="" where="" generated="">. Now highlight that whole block of characters, including the first line of ssh-rsa, and Copy it to the clipboard in Windows

using CTRL-C. Don't shut the dialog box - there is more to do later.</name>

You can get this onto MCS Unix systems in two ways: go to <a href="https://www-accounts.mcs.anl.gov/account.php">the personal account management page</a>, log in, and paste the public key block into the SSH Public Key section and click on the "Update SSH Public Key" button. Follow the directions to call the HelpDesk at 630-252-6813 to get the key activated. Or, if you can come in through the VPN, do that, ssh to fuzzy using your plain Unix password, and then follow the directions under "First: Preparing your MCS environment" at the top of this page.  You can also email the key to systems@mcs.anl.gov, then call to verify your identity.

Next, open ~/.ssh/authorized_keys in your favorite editor, and

paste the public key block into the file (making sure it is all actually one single line of text, no returns). Exit the editor, saving the authorized_keys file.

You can also click on the "Save public key" button to save this text-block as a file locally on your Windows box, but this is just to have it around for later in case you want to file-transfer it somewhere later, or email it, etc.


Part 2 - saving the private key on your Windows machine:

You will definitely need to save the private key on your Windows box. To do this, first enter a "Key passphase" in the box provided, and re-type it to confirm in the "Confirm passphrase" box just below that. You will need to remember this passphrase! Make sure you choose a strong one. Then click on the "Save private key" button. You can name it whatever you want. It will be saved with a ".ppk" extension. Do not change this.

You are now done generating your key-pair, and may close the PuTTYgen dialog box.

Part 3 - setting up PuTTY to use keys and opening an SSH session

If you have used PuTTY before, double-click on the PuTTY icon to open the application. You can click on one of your previously saved sessions and hit the "load" button. But don't hit "Open" yet.

If you have not used PuTTY before, enter a hostname under "Hostname (or IP address)", like terra.mcs.anl.gov. Make sure the radio button for SSH is clicked, and the port says 22.

On the "Category" tree on the left-hand side of the dialog box, click on "Auth" under Connection->SSH->Auth. This should be "Options Controlling SSH Authentication". The only box that needs to be checked is "Attempt keyboard interactive auth (SSH2)". Under "Private key file for authentication:", click the "Browse..." button off to the right, and locate the .ppk file you saved earlier. Click "Open" and it will return you to the SSH Auth dialog box with the private key file location entered properly in the box.

Go back and click on "Session" at the top of the "Category" tree on the left side. You may want to name and save this session, so it will use keys from now on. Enter a short name under "Saved Sessions:" like terra. Then click the "Save" button.

You are now ready to click the "Open" button at the bottom to launch your SSH session using keys.

You will get a window that says:
login as: [Enter your Unix username]

Then it will say: Authenticating with public key "<name of the rsa key you created>"
Passphrase for key "<name of the rsa key you created>":

Enter the passphrase you used while saving your private key to this Windows box.

You're in!

For more information on using PuTTY, see <a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Contents.html">the PuTTY docs</a>, especially <a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Chapter8.html#8">Chapter 8</a> on SSH public keys.

Using SSH keys in MCS

This page outlines the steps required to get your SSH keys in place to use MCS computing resources via SSH. We have tried to cover as many situations as is reasonable, but obviously, problems can occur. We have to handle a lot of these key installations in the regular operations of things, and more when there's a large influx of people. So we ask that you read over this information and, where appropriate, follow the steps outlined to get operational. If you do encounter problems, you can always ask us for help at systems@mcs.anl.gov.

Note: If you are using a registered host (the hostname ends with .mcs.anl.gov) on an MCS network, or are using the VPN, you do not *need* to use keys to access MCS workstation resources. You can ssh to fuzzy.mcs.anl.gov using your unix/e-mail password.


SSH is the main method that MCS supports for people to use to connect to MCS unix machines remotely.

When connecting to an MCS unix machine, you will need to provide information that demonstrates you are who you say you are. This is traditionally done by providing your username and your password. However, this is not quite secure enough, and so MCS is requiring that other methods be used. SSH supports several different methods, one of which is the use of "keys".

Without going into the details of the protocol,

this document will describe what you need to do to get your SSH program to use keys. This will involve generating and installing keys. Once these are in place, you can also use "agents" to reduce

the number of times you need to type a password. 

First: Preparing your MCS environment

All of the MCS environment steps require that you be able to login to an MCS workstation.  If you're onsite or using the VPN, you can use fuzzy.mcs.anl.gov and continue on to the steps below.  If not, or if fuzzy doesn't work for you, please visit <a href="https://www-accounts.mcs.anl.gov/account.php">https://www-accounts.mcs.anl.gov/account.php</a> and upload your public key or email it to <a href="mailto:systems@mcs.anl.gov">systems@mcs.anl.gov</a>.  (Note: If you e-mailed your key, please wait until you receive an e-mail confirming we have the key loaded into our system before you call.)  After you do that, call the Help Desk at (630) 252-6813 Monday - Friday, 9:00AM - 11:00AM or 1:00PM - 4:00PM to verify your identity and have that key moved to your authorized_keys file.  During the verification process you will need to read part of the public key to the help desk staff. Please have it available before contacting the help desk. 

Most likely, your MCS environment is already configured properly. Just in case, however, here are things you should check on your MCS home directory.

Your home directory on MCS cannot be writeable by anyone other than you.  On an MCS UNIX system, be sure this is the case with the following command:

chmod og-w ~

You also need a .ssh and .ssh/authorized keys directory.  To ensure this is in place:

mkdir ~/.ssh
touch ~/.ssh/authorized_keys
chmod -R 700 ~/.ssh

If you get an error on the mkdir command saying the directory already exists, that's okay.

Second: Prepare your client environment

You will need to install SSH keys on the machine that you use to login to MCS. This may be your laptop, your machine at home, a desktop at some other site, or any other computer not in the MCS UNIX space.

Follow the instructions below based on the kind of system you're using.


<a name="Other">Linux, MacOS X, Cygwin, and other UNIX variants</a>

STEP ONE: Generate keys.

The "ssh-keygen" command is used to create keys. There are many options for it. We recommend that you run it this way:

ssh-keygen -t rsa

This will create and store keys in your ~/.ssh directory. It will overwrite any existing keys as well. The default keytype in MCS is RSA for SSH 2. To generate this key (id_rsa), simply type "ssh-keygen -t rsa" and follow the prompts. WE REQUIRE THE USE OF A PASSPHRASE. There are a very limited number of circumstances where a key without a passphrase is acceptable. If you are in doubt, ask us. Just remember this: with a copy of your private key, if it has no passphrase, a person can ssh as you to any host to which you've allowed access without knowing a password or passphrase.  Needless to say, This Is Bad.

We recommend SSH2 (and in most cases require it), but if you need

to generate an SSH 1 key, the command is "ssh-keygen -t rsa1" which will create .ssh/identity.

Some machines may put these files in a different spot.  If

this is the case, make a note of where it puts them and what it

names them.

The id_rsa (and, if

they exist, id_dsa or identity) file is your private key.  Keep it secret, keep it safe.

STEP TWO: Put public key on MCS host.

Each of the commands above will generate an associated .pub file.

That's your public key. In order for you to tell a host that you want to authorize that private key to identify you, you need to give that host your public key. This is done via ~/.ssh/authorized_keys.

If your keys are on an MCS machine, then to add your MCS identities to your authorized keys file, it's as

simple as:

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

To add the SSH1 identity:

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

If the keys are on a different host, to add the public keys to an MCS host:

cat ~/.ssh/id_rsa.pub | ssh username@fuzzy.mcs.anl.gov 'cat - >> ~/.ssh/authorized_keys'

You will need to be onsite using a registered host or using the VPN for the above command to work.  If you are not, please visit <a href="https://www-accounts.mcs.anl.gov/account.php">https://www-accounts.mcs.anl.gov/account.php</a> and upload your public key and call the Help Desk at (630) 252-6813 to have that key moved to your authorized_keys file.  Don't send us e-mail asking to do it.  We need in-person of over-the-phone verification of identity before we do anything like that.

In all cases above, you need to create the authorized_keys file

if it doesn't yet exist.

At this point, if you ssh to the machine on which you added the

public key to the authorized_keys file, instead of being asked for a password, you'll see something like this:

% ssh joeblow@terra.mcs.anl.gov
Enter passphrase for key '/homes/stace/.ssh/id_rsa':

What I type at that prompt is not my password. It's the passphrase I used when I created that key. That passphrase is not stored anywhere. You're no longer using your password. However, we can still reduce the number of times you need to type the passphrase.

If your private key is named something other than the default,

the format for the ssh is:

% ssh -i /path/to/private/key joeblow@terra.mcs.anl.gov

STEP THREE (Optional): Agents

If you run an ssh-agent, it will remember the passphrase for your

key while it's running.

If you login to an MCS linux workstation locally through

X-Windows, an agent is launched automatically. If not, you can launch one by running:

eval `ssh-agent`

To add your keys to the agent:

ssh-add

If your keys have a non-standard name or path, you'll need to specify the full path after the ssh-add command.

You will be asked for the passphrase for your .ssh/id_rsa (and .ssh/identity, if applicable).

Now you can ssh to other machines that have your public key and

never have a password.

MacOS users can use GUI tools such as the following to manage keys and agents:

<a name="Windows">Windows</a>

If you use cygwin for SSH, see the unix instructions above. I recommend skimming the above section for background an insight on what the keys are for if you haven't already read it.

SecureCRT

If you use SecureCRT, the version of SecureCRT on the <a href="http://www.mcs.anl.gov/windows/software.html">windows

software page</a> supports keys. Simply generate your key by clicking "Tools", then "Generate Public Key". Follow the prompts (I currently recommend an RSA key, despite what the text above the selection box says). Choose a good passphrase, WE REQUIRE THE USE OF A PASSPHRASE. 1024 is an adequate key length. Make note of where it's installing the key. It's probably something like:

C:\Documents and Settings\USERNAME\Application Data\VanDyke\Identity

If you upgraded from an old version, it might be:

C:\Documents and Settings\USERNAME\Application Data\Van Dyke Technologies\Identity

Say "Yes" to the global public key question.

Now, the tricky part. SecureCRT stores your public key in a funky

format. To get it into the format OpenSSH recognizes:

  1. If you are on-site or using the VPN, log on to fuzzy.mcs.anl.gov using SSH2 and password authentication.  If not, please email the "Identity.pub" file you created to <a href="mailto:systems@mcs.anl.gov">systems@mcs.anl.gov</a> as per the instructions at the top of the page.  Then proceed to Step 6.
  2. If it does not already exist, you'll need to create your .ssh

    directory in your MCS unix home directory on the remote machine.  Type "mkdir ~/.ssh" followed by "chmod 700 ~/.ssh".

  3. On the local machine, use Notepad.exe to open the Identity.pub

    file that was created with the Key Generation wizard.

  4. With the Identity.pub file opened in the Notepad application,

    open the Edit menu and choose Select All. Once everything is selected, open the Edit menu again and select Copy.

  5. On the remote machine, complete the following steps:
    • % cat > ~/.ssh/windows-machine-name.ident (where "windows-machine-name" is the name of your machine)
    • Click on the SecureCRT paste button to paste the contents

      of the Clipboard (which should now contain the contents of your Identity.pub file).

    • Issue a CTRL+D to close the Identity.pub file.
    • Convert the key to one that OpenSSH will recognize using

      the following command:
      % ssh-keygen -i -f ~/.ssh/windows-machine-name.ident >> ~/.ssh/authorized_keys

  6. Make SecureCRT use the key.
    • Click "File" then "connect", and for each existing entry, in the list (or for new ones you add) click the "Properties" button (it looks like a hand holding a card).
    • In the Authentication section under "Connection",

      change "Primary" to be "PublicKey". Choose "Properties" and make sure it's using your global file.

    • Click "Options", "Global Options", and under

      SSH2 heading, check both boxes in the "Agent" section.

Now, the first SecureCRT session you open will ask the passphrase for the key you generated, and any subsequent ones will not (as long as SecureCRT is running.)

NOTE: If you converted a previously SSH1 session to use SSH2, check your port forwarding configuration.  It may have been messed up.  The checkbox for local IP address restrictions should be unchecked.  If it's not, uncheck it.

Putty

If you would like to use PuTTY as your ssh client, the first thing you should do is download the latest client. We have found that various older versions give funky problems when trying to use version2 keys. It only takes 10 seconds - no fancy installer, no rebooting.

Close any current PuTTY connections, move the current PuTTY executable (putty.exe) to the recycle bin, and download a new putty.exe from <a href="http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html">here</a>. Your current preferences and saved connections will not go away. When you open the new PuTTY, all those things will still be there.

While you are grabbing the latest client, also grab <a href="http://the.earth.li/%7Esgtatham/putty/latest/x86/puttygen.exe">PuTTYgen (puttygen.exe)</a>, which is the tool you will use to generate a new ssh key pair.

You can use PuTTYgen to load and convert an existing key you may have generated with OpenSSH to PuTTY's key format. See:

<a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Chapter8.html#8.2.12"> "Dealing with private keys in other formats"</a>. We will not cover that here. It is easier to simply generate a new key pair.

After downloading PuTTYgen, double-click on the PuTTYgen icon. At the very bottom of the dialog box, there is a section called "Parameters". Under "Type of key to generate:", click the radio button for "SSH2 RSA". Note the PuTTY default of "SSH1 (RSA)" will

  • not* work with most MCS systems, so you must do this step!

You may leave the "Number of bits in a generated key:" at the default value of 1024.

Now under "Actions" in the middle, click on the "Generate" button. Follow the directions of moving the mouse around in the blank section to generate randomness. It will then say "Please wait while a key is generated." This doesn't take long at all.

Part 1 - the public key goes in your MCS ~/.ssh/authorized_keys file:

Now you will see at the top your "Public key for pasting into OpenSSH authorized_keys file:". If you like, at this point you can change the "Key comment:" to add something like -<name of="" machine="" where="" generated="">. Now highlight that whole block of characters, including the first line of ssh-rsa, and Copy it to the clipboard in Windows

using CTRL-C. Don't shut the dialog box - there is more to do later.</name>

You can get this onto MCS Unix systems in two ways: go to <a href="https://www-accounts.mcs.anl.gov/account.php">the personal account management page</a>, log in, and paste the public key block into the SSH Public Key section and click on the "Update SSH Public Key" button. Follow the directions to call the HelpDesk at 630-252-6813 to get the key activated. Or, if you can come in through the VPN, do that, ssh to fuzzy using your plain Unix password, and then follow the directions under "First: Preparing your MCS environment" at the top of this page.  You can also email the key to systems@mcs.anl.gov, then call to verify your identity.

Next, open ~/.ssh/authorized_keys in your favorite editor, and

paste the public key block into the file (making sure it is all actually one single line of text, no returns). Exit the editor, saving the authorized_keys file.

You can also click on the "Save public key" button to save this text-block as a file locally on your Windows box, but this is just to have it around for later in case you want to file-transfer it somewhere later, or email it, etc.


Part 2 - saving the private key on your Windows machine:

You will definitely need to save the private key on your Windows box. To do this, first enter a "Key passphase" in the box provided, and re-type it to confirm in the "Confirm passphrase" box just below that. You will need to remember this passphrase! Make sure you choose a strong one. Then click on the "Save private key" button. You can name it whatever you want. It will be saved with a ".ppk" extension. Do not change this.

You are now done generating your key-pair, and may close the PuTTYgen dialog box.

Part 3 - setting up PuTTY to use keys and opening an SSH session

If you have used PuTTY before, double-click on the PuTTY icon to open the application. You can click on one of your previously saved sessions and hit the "load" button. But don't hit "Open" yet.

If you have not used PuTTY before, enter a hostname under "Hostname (or IP address)", like terra.mcs.anl.gov. Make sure the radio button for SSH is clicked, and the port says 22.

On the "Category" tree on the left-hand side of the dialog box, click on "Auth" under Connection->SSH->Auth. This should be "Options Controlling SSH Authentication". The only box that needs to be checked is "Attempt keyboard interactive auth (SSH2)". Under "Private key file for authentication:", click the "Browse..." button off to the right, and locate the .ppk file you saved earlier. Click "Open" and it will return you to the SSH Auth dialog box with the private key file location entered properly in the box.

Go back and click on "Session" at the top of the "Category" tree on the left side. You may want to name and save this session, so it will use keys from now on. Enter a short name under "Saved Sessions:" like terra. Then click the "Save" button.

You are now ready to click the "Open" button at the bottom to launch your SSH session using keys.

You will get a window that says:
login as: [Enter your Unix username]

Then it will say: Authenticating with public key "<name of the rsa key you created>"
Passphrase for key "<name of the rsa key you created>":

Enter the passphrase you used while saving your private key to this Windows box.

You're in!

For more information on using PuTTY, see <a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Contents.html">the PuTTY docs</a>, especially <a href="http://the.earth.li/%7Esgtatham/putty/0.54/htmldoc/Chapter8.html#8">Chapter 8</a> on SSH public keys.