Accessing your account through SSH keys

In order to access an HCS group account to read email and begin setting up webpages, you will first need to set up an SSH key and add it to your account through the Helios account management system. You will then be able to connect via a terminal application into our servers.

What are SSH keys?

SSH keys are a way to identify trusted computers, without involving passwords. SSH keys always come in pairs, one private and the other public. The private key is known only to you and it should be safely guarded. By contrast, the public key can be shared freely with any SSH server to which you would like to connect to. The steps below will walk you through generating an SSH key and adding the public key to your HCS account.

The process is different depending on whether you use Mac or Windows. Incidentally, if you're on a Linux computer, the Mac directions will work fine for you as well. Just substitute Gnome Terminal or Konsole (or other equivalent) for Terminal.app and the relevant keyboard shortcuts for copying & pasting.

Using a Mac/Linux

Open Terminal (on a Mac, in Applications > Utilities) and type:

ssh-keygen -t rsa

It will begin generating a pair of RSA keys for you. This process might take a minute or two. At the next prompt,

Generating public/private rsa key pair.
Enter file in which to save the key (/Users/jharvard/.ssh/id_rsa):

simply hit return to save the key in the default location. Important: If you choose not to save it to the default location, you will need to add your key to an SSH agent later to make your computer recognize it.

Enter passphrase (empty for no passphrase):

You will then be prompted for a passphrase. You don't have to specify one, but it's recommended that you do. Everytime you connect to HCS however, you will need to remember this passphrase, so choose something memorable but difficult for others to guess. Basically, you are setting a password for your own keys so that other people are unable to use them even if they steal your SSH key files. Whatever you choose, you will have to enter it twice, and then you will be informed that your keys have been saved.

After you have generated the key, you now need to grant access to this key on your HCS account. First, you need to copy the key's contents to your clipboard. To display the key you just created, type

cat ~/.ssh/id_rsa.pub

and then copy all the output that results. To do that, highlight it in the Terminal and press ⌘(Command)-C. You should be highlighting all the text that looks like this:

ssh-rsa AAAAB3NzaC1kc3MAAACBAPn9BVNNZry4SEdR9Kwf2yAV/jxtMlPjTXLFRgw/LCnT
2OOWsdreSJQ/+s2q1TxL3Dj5ZwCxyS9Al7+s5QxY1JDJW1tKBlDglo+6tPML7RsVyCLwCOzb
EWmgzcq/95PzpEaZyJCUW2IGcQkDRtTNx7D+V24aM+28NtjCOCR2GroKTHAAAAFQDDJMwUmB
YNuwdwBzvyN+MAiRlVlwAAAIB3eiqyWOODw6gXmOkKfL/e7PgihyPJFHZKnOQcQktHK41L4U
QYCwfEPemuVvhDl7ECHPzlx5LxnBdLgvsNzODBUXzi+UXAIjg0t06pLfvlKi7RZ+9pVBD4z7
BGEVUDjlnYaI2eivbLt30M3Fc8USFnMjDvNkMRrhoSlwcCtglYUwAAAIEA6qykkPCK4qo+DG
XarB+nALSb0Xqx/ND3ZlUJmFu4SDJbryN+ss5qXM6cepxCAn/QIXGOW+giTR1GOQf6oIhiux
iUjy60X7RfyBrpPkq1++LQVEmjTi7qutFqJayIc25O/CyJRoObuT+Zu/a4kik3CaapaVh6TC
UruSQwVzKI6iM= jharvard@jharvardmac.local

Now, you need to login into the Helios account management system, and upload the key that you just made. On your group's page, select the user that you want to associate the SSH key with, paste in your SSH key from the Clipboard into the SSH Key field, and hit the Submit button.

With this, you should now be able to run the command ssh group-name@hcs.harvard.edu straight from your own system. If you made a passphrase when creating your keys, you'll be prompted for it to decode the private key, and with any luck, you just let yourself into HCS directly! Check out the next tutorial to find out what you can do with your account now that you have access to it. If something went wrong, check the last bit of this page for troubleshooting tips.

Adding your SSH Keys to an SSH Agent

If you have an passphrase on your private SSH key, you will be prompted to enter the passphrase every time you use it to connect to a remote host.

To avoid having to repeatedly do this, you can run an SSH agent. This small utility stores your private key after you have entered the passphrase for the first time. It will be available for the duration of your terminal session, allowing you to connect in the future without re-entering the passphrase.

Another reason why you might want to use an SSH Agent is if you're storing your key in a different location than the default (~/.ssh/id_rsa). You will need to add your private key to the SSH Agent to make your client recognize the key that you generated.

On Mac

To store the passphrase for your default key in the Keychain open a Terminal and run:

ssh-add -K

If you did not save the key in the default location, you will need to append the path to your key to the end of the command above:

ssh-add -K /path/to/your/private/key

You will have to enter your passphrase (if one is set). Afterwards, your identity file is added to the agent, allowing you to use your key to sign in without having re-enter the passphrase again.

On Linux

To start the SSH Agent, type the following into your local terminal session:

eval $(ssh-agent)

This will start the agent program and place it into the background. Now, you need to add your private key to the agent, so that it can manage your key:

ssh-add

If you did not save the key in the default location, you will need to append the path to your key to the end of the command above:

ssh-add -K /path/to/your/key

You will have to enter your passphrase (if one is set). Afterwards, your identity file is added to the agent, allowing you to use your key to sign in without having re-enter the passphrase again. Note: Your SSH Agent will only last for the current Terminal session, so if you close your Terminal and open a new one, you will have to redo the steps above. You might want to consider automated tools such as keychain.

On Windows

The process here is a bit longer than with a Mac, but hang in there. We've tried to make this guide as simple and straightforward as possible. First, make sure you have PuTTY and PuTTYgen from here (we recommend using their Windows installer to install everything you need). Now, load up PuTTYgen. Select SSH-2 RSA and set the key length to 2048, as shown below:

Then click "Generate" to create a SSH key pair. Now for the fun part: move your mouse around to create random data for the key generator. Seriously. Whip it around however you like.

Once that is finished, you need to add a comment to your key and choose a passphrase, as shown below. The comment should be something that can identify the computer you're currently using to create this key.

Select "Save public key", and save the file as "key.txt" wherever you'd like. Remember the location so that you can access it in the future. Then select "Save private key", and save the file in the same directory that you saved your public key. The private key should be named "key.ppk".

Now, select your entire public key, right click, and select Copy.

Now you need to login into the Helios account management system, and upload the key that you just made. On your group's page, select the user that you want to associate the SSH key with, paste in your SSH key from the Clipboard into the SSH Key field, and hit the Submit button.

When the screen refreshes you should see your key in the list. If you see it, then congrats, you're all set. You can view more details about the SSH key you've uploaded if you click the Show button.

Now we need to tell PuTTY to connect to HCS with the SSH key. Open up PuTTY and type hcs.harvard.edu in the Host Name box.

Select Data under Connection in the navigation menu, and enter your HCS account name in the "Auto-login username" box.

Now select Auth, under SSH, under Connection in the navigation menu, and click Browse.

Navigate to the folder where you saved your SSH keys, and select the private key file, key.ppk.

Now select Session at the top of the navigation menu, and save this session configuration by choosing a name and putting it in the box below "Saved Sessions", and clicking Save. We used "HCS" in the image below.

Now you're all set! Select Open to start a connection. If this is your first time connecting, you may see a message like the following:

Just select Yes, and you should be at your account prompt. In the future, to connect to your account, just open PuTTY and double-click on HCS (or whatever you saved this connection as), or select HCS and then click Load and then Open.

That's it! You should be in; if not, something went wrong. See the final section for some tips.
Now that you have SSH access to your account, check out the next tutorial to find out what you can do with it.

So what now?

Troubleshooting

OK, what if it didn't work. The mostly likely reason is that our web application mangled its job and didn't add your key correctly, or you pasted it wrong, say without the last ten characters or something. In that case, you will have to roll up your sleeves and fix the mess. Get back into Helios, check your key details by clicking the Show button, and compare it with the public key you generated.

If you think you did everything right, your SSH key list looks fine, and you're followed all the settings above to a T, you could try asking us at acctserv@hcs what to do. We'll give you our best shot.

Why did I go through all this again?

SSH keys are a convenient and secure way of accessing your account, as compared to password-based authentication. Although the initial setup might take some effort, the benefits that come with it are worth it, we promise. Plus, it will make uploading files to your account so much easier through a graphical client, which will be the focus of the SFTP tutorial.