SSH

Template:oldfaq Here you'll find all you need to know about Secure Shell (SSH) and its usage as required in Peyton Hall

Introduction

What is SSH?

SSH is a secure networking protocol that uses public key encryption to make sure that all data, including authentication data, is encrypted from end to end. It is similar to 'telnet' in only the fact that it lets you connect to remote computers. However, with 'telnet', 'ftp' and other insecure protocols, your user name and password are sent in cleartext to the remote side - they can be sniffed out anywhere along the network and your password recovered from the traffic. SSH uses encryption to make sure that your password is kept safe - and in fact, can be set so that your password is not even used.

A decent introduction to SSH public key authentication is available at http://sial.org/howto/openssh/publickey-auth/

Why should I use SSH?

SSH is required for all logins for security issues (described above). In a switched ethernet environment like ours, cleartext passwords aren't too much of a problem, since there's very few places where one could put a "sniffer" (which captures the network traffic) to read your password. However, in some cable modem setups and even DSL, other people can read the traffic that comes from your computer. If they're looking, and you telnet in at that moment, they've now got your user name and password and can login as you. What's more is that they may be able to exploit deficiencies in the Unix OS from that point to gain root access, and destroy data for not only you but anyone else in the department. This is not a Good Thing.

Because of that, we require that all incoming connections use SSH. We also require that all connections (except those to "Minos") use no password at all, instead using SSH public key authentication (see *IMPORTANT SSH Login Policies*). By restricting logins this way, we are able to allow logins to any machine in the building, from any machine in the world.

SSH versions

All machines in Peyton Hall run a version of OpenSSH. This was chosen over the version available from SSH Communications Security because it's free, usually gets updated more frequently, and comes with Fedora, and even MacOS X. There are a handful of other SSH programs available (see below) for other operating systems and environments. However, most have a few things in common:

• The ability to use passwords over an encrypted link for authentication
• Use of public key encryption for authentication
• Tool for generating/converting keys
• Ability to tunnel other ports through the SSH connection

Where to get SSH

• OpenSSH: http://www.openssh.org
• PuTTY: http://www.chiark.greenend.org.uk/~sgtatham/putty/

Setting up a SSH environment

I have written a script called 'ssh-setup' to get you started with SSH. This will walk you through setting up a key, getting it used for authentication, and show you how to use it daily. You can run this script by entering "ssh-setup" at the command line on any of the linux machines in the department. This script will NOT explain all the details of usage, just a basic overview to get you up and running quickly; however, you will need to do a little more research to learn the details of usage. Because SSH is a complex program and protocol, there is no way to just hand you all the information you will need, so after running the script and getting some of the basics, read on for more information.

Keys

Before you can use SSH to the fullest extent - and in fact, before you can use it in Peyton Hall to login to another machine, you must create a keypair. There are a few different kinds of keys, which we'll go over here now.

Key types

DSA

The first type of key we'll go over is the DSA key (in fact, if you only want to create one key, this is the one). DSA keys use the SSH version 2 (SSHv2) protocol, which is more popular and more secure than the older SSHv1 system. To create a DSA key, run the command:

ssh-keygen -t dsa

This will generate output that looks like this (don't worry, we'll go over the parts in a moment):

Generating public/private dsa key pair.
Enter file in which to save the key (/u/user/.ssh/id_dsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /u/user/.ssh/id_dsa.
Your public key has been saved in /u/user/.ssh/id_dsa.pub.
The key fingerprint is:
e0:48:7e:47:5c:5e:6a:ad:71:f1:eb:47:b1:ab:ae:6d user@machine.Princeton.EDU

Now, the questions asked above and what they mean:

• Enter file in which to save the key

  If you want the key to go to a specific filename, type it here. The usual default (which maps to ~/.ssh/id_dsa) is perfectly fine for most uses, and in fact unless you have a reason for renaming the key you should leave it this way.

• Enter passphrase (empty for no passphrase)
  Enter same passphrase again

  This is where you should enter your passphrase. To understand what this means, please see the article Passphrase. DO NOT SIMPLY PRESS ENTER!

The remainder of the output tells you the filename for the key, the public portion of the key, and the key's fingerprint - a small hash of the key itself which is slightly less unique, but easier to compare than the entire key length.

Congratulations, you have a DSA SSHv2 keypair! The remainder of this article will assume you're using a DSA key, and that its name is id_dsa (with corresponding id_dsa.pub file for the public part of the key).

RSA

RSA keys are similar to DSA keys, and will let you login with the SSHv2 protocol as well. The procedure is the same as for DSA keys, but simply changing the type specified to ssh-keygen:

ssh-keygen -t rsa

Again, unless you know you explicitly need a RSA key, there's probably little reason to make one.

RSA1

RSA1 keys are a different beast entirely. These are only used with the older version 1 of the SSH protocol (SSHv1), which is no longer developed and has been proven less secure than SSHv2. If for some reason you know you need to connect to some place that does not support SSHv2, then you'll need to generate one of these keys. Again, as with DSA keys, the procedure is the same, just the key type to pass to ssh-keygen differs:

ssh-keygen -t rsa1

Converting keys

If you have a key from a remote location which uses a different SSH program, or you want to send a copy of your key to someplace that doesn't use OpenSSH-compliant programs, you may need to convert your key to make it work. Due to the number of possible programs, it's difficult to explain all the choices for converting keys, however one example is converting a key to work with the ssh.com program.

ssh-keygen -e (input file) > (output file)

Where:

• -e: tells ssh-keygen to export a key in SECSH format
• (input file): The key file you wish to convert; may be the public or the private key
• (output file): The file to store the converted key

Conversely, you can use the '-i' option to ssh-keygen to convert from SECSH format to OpenSSH.

NOTE:

In some cases, your private key file (if that's what you're converting) may need to be unencrypted first. See below for more details.

Installing your keys

A few words on the public key file

The public portion of a keypair (with extension .pub) is meant to be handed out to wherever you wish to connect. This part is used to encrypt some bit of information on the remote machine (the one you're connecting to), which is then sent to the local client. If the local client can then use your private key - either by first asking for your passphrase to decrypt it, or by use of the ssh-agent (see below) - to decrypt the information sent, then the remote server knows that the person who is initiating the connection must have the corresponding private key, and therefore is who they claim to be. If you look at the public key, it will appear similar to this:

ssh-dss AAAAB3NzaC1kc3MA.....b40HgUC4= huston@xanadu

The beginning part tells SSH what kind of key this is. The middle is the key itself, and can also be prefixed with other things if you want specific actions taken with this key (see the man page for sshd(8) section "AUTHORIZED_KEYS FILE FORMAT"). The last part is a comment, which can be anything you like; the default with keys generated by OpenSSH's ssh-keygen will be your username and the host on which you created the key. This is useful when you have a lot of keys, and aren't sure which is which, as you can look at the comment to help you determine which key does what.

NOTE:

SSH public keys are single-lined! The entire key must be written on one line for the SSH daemon to read it, with no line breaks anywhere. When you view the key in some programs, it may appear to take up 8 lines or so, but that is simply word-wrapping in your text editor. You must make sure when copying your key to the authorized_keys file that it is all contained on a single line, or SSH will fail without any error on your end to explain the problem.

The authorized_keys file

To actually use your keys, the software must know that the key you've created is 'authorized' to login as you. In order for that to happen, the public part of the key must be listed in the file ~/.ssh/authorized_keys. The simple way to do this, and make sure that line breaks are not inserted in a key erroneously, is to do the following:

cd ~/.ssh ; cat id_dsa.pub >> authorized_keys

You can add other public keys that you want to be able to access your account to these files also. Once that's done, any holder of the private key that goes with those public keys will be able to login to the account as you. A benefit of NFS mounted home directories is that you can now login from one machine to another without using your password, just using your SSH keys, since the authorized_keys file would now exist on every machine. You'll still have a passphrase to use for each login, instead of your password, until you follow the instructions for setting up ssh-agent (see below)

NOTE:

Older versions of SSH would have two separate files, like authorized_keys2 and known_hosts2. This was to separate the keys used for version 1 and version 2 of the SSH protocols. Since the older versions would choke on a version 2 key in a version 1 file, this was done to keep everything somewhat together yet separate where necessary. Newer versions of SSH will read both files. You can therefore keep all your keys in just one file, ~/.ssh/authorized_keys, instead of splitting the version two keys into a separate ~/.ssh/authorized_keys2. If you happen across an older system which requires both files used, you will have to do this - but the versions running in the building here can read both types of keys in a single file.

It is VERY IMPORTANT that your authorized_keys file is non-group and non-other writable, ie a 'ls -l' should look like this:

-rw-------    1 huston   huston        676 Aug 31  2001 .ssh/authorized_keys

(They can have the group and other read bit set, but not write). Do this with the command 'chmod 600 ~/.ssh/authorized_keys*'. This is because SSH will silently ignore your keys on the server side if it sees 'loose permissions' on the file, meaning that people other than you could write to it. I say it will silently ignore them, because the server gives no indication to the user that there was any problem, just seems to ignore the keys (it will, however, output a message to the system logs).

Installing keys to (or from) remote hosts

The procedure for installing a key to or from a remote host is the same as above. Simply copy the public part of the key from the host you wish to connect from, and install it on the host you wish to connect to. So if you're using coma in Peyton, and wish to login to the host "overthere", something like this should work:

cat ~/.ssh/id_dsa.pub | ssh overthere 'cat >> ~/.ssh/authorized_keys ; chmod 600 ~/.ssh/authorized_keys'

The 'chmod' command is to make sure that the authorized_keys file on the remote side is not set with 'loose permissions' which will cause the login to fail.

NOTE:

A trick I like to use is to always keep a connection open when I'm messing with SSH files. In the above situation, I would have in another window run 'ssh overthere' and had a shell running while I did the command. In this way, after I make the change, if something doesn't work I can still fix the problem through the shell I had opened previously. If, however, you make a mistake and cannot login to fix it, you may require the assistance of a system administrator to fix your files for you - and if it's 2am, it may take a little while before one wakes up to help :>

Conversely, if you wish to install a key such that you can login from "overthere" to any Peyton machine, you'll want to take the public key from the keypair you generated on "overthere", and add it to your ~/.ssh/authorized_keys file in your home directory here. The procedure is the same; just make sure to append to the file, not overwrite what you may have had there previously.

Last but not least, remember that not everyone runs the same version of SSH - there are a few out there, between versions from Unix vendors such as Sun, a commercial version from ssh.com, and the open source version we run from OpenSSH. Because of this, some of these instructions may be different for other locations. They may use a different type of key (see above for converting a key to work here or elsewhere), or a different method of storing the key for authentication. Check with the systems admin for the remote site if you're having problems, since they should know what is necessary to get SSH working with your key (and they'll appreciate that you're being secure and not using a password all the time).

Changing your key's passphrase

To change your ssh private key's passphrase, use the command:

ssh-keygen -p

ssh-keygen will then prompt you for the location of the private key (the default is usually ok), your current passphrase to unlock the key, and then for a new passphrase twice to lock the key.

Please remember, a good passphrase is similar to a good password. Don't make it the same as your username, real name, repeating characters, your password, or anything else that obvious. You *can* make it long, have spacing, capitalization, and punctuation so it might even be useful to make it a sentence or a group of non-related words. See Passphrase for more information on selecting good passphrases.

SSH in Windows

To use SSH under Windows, the easiest solution is to install and run PuTTY. Please see the article Setting up Putty in Windows for more information.

Using SSH

Actually using SSH is very simple to do. Aside from the comments below, as always be sure to read the man pages for more information.

Basic usage

ssh (hostname)

That's it! If your local username matches the remote username, that's all there is. If not (example, local username is "user", but remote username is "me"), then run ssh like this:

ssh me@(hostname)

That tells the SSH software to login as user 'me' on the specified host.

scp/sftp

scp and sftp are available with the SSH2 protocol to copy files to other machines. Here's a basic usage summary:

scp source destination

Either 'source' or 'destination' can be a local file, or a remote file in the form of '[user@]host:file'. For example, to copy the file 'testfile' to your home directory on coma:

scp testfile coma:.

If instead you wish to copy ~/testfile from coma to the current directory, use:

scp coma:testfile .

sftp works in a similar way, but gives a FTP-like interface:

sftp coma

This will give a secure FTP interface to your home directory on coma. SFTP requires that both machines run the same version of SSH; you can override this behavior with the '-1' flag, which will force sftp to use the older version 1 protocol (you must have SSHv1 keys created and installed for this to work):

sftp -1 coma

ssh-agent

The ssh-agent process allows you to authenticate your private keys to the local machine, so that you can use them without typing a passphrase every time. Since you should have a long and obnoxious passphrase, this is important to save your typing - especially if you're doing something like a CVS update which would require a lot of consecutive logins.

Starting a ssh-agent

There's two ways to start a ssh-agent process; either by calling a command as a child to the agent, or installing it in the current environment. For example:

ssh-agent <command>

Running an agent this way will make the command specified on the commandline a child of the agent, so the command will inherit the agent's environment. This is important because any other children of these processes will be able to access the agent to authenticate keys. The other method of calling:

eval `ssh-agent`

This will install the agent in the current environment. Note that this does not propagate the agent's environment to other terminal windows, for example, but only works in the current terminal. As of this writing (2007/05) most of the machines in the building will either automatically start an agent when you login via X on the console, or you have some lines in your shell startup files which will start an agent when you login (or both). This way the agent has the entire X11 session as a child, and all programs can use ssh without requiring that you type a password when your keys are authenticated.

Adding keys to a running agent

Now that your agent is running, you'll need to add your keys to it to make them work. Simply using the 'ssh-add' command will do this:

$ ssh-add
Need passphrase for /u/user/.ssh/id_dsa
Enter passphrase for /u/user/.ssh/id_dsa
Identity added: /u/user/.ssh/id_dsa (dsa w/o comment)

If you have multiple keys with standard names (id_dsa, id_rsa, identity) they'll all be added by ssh-add. If they have nonstandard names, you can simply name them on the command line of ssh-add and all the keys you name will be tried. ssh-add will ask for your passphrase, and add the first key; if you have multiple keys, it will then try the same passphrase on all the others and add them if successful; otherwise it will ask again for the passphrase for the next key.

Now, when you attempt to login to another machine, you will not be prompted for a password, passphrase, or anything else. It should simply exchange information between the running ssh-agent, and your keys, and let you login with no hassle:

machine:~$ ssh coma
Last login: Tue Feb 19 15:08:26 2002 from machine
coma:~$ 

Forwarding your ssh-agent

When you login to a remote machine, you've used the ssh-agent on your local machine to authenticate with your keys. However, if you have a lot of keys authenticated, it's handy to forward your agent through the connection as well. This way, you can 'hop' from one machine to another, taking your credentials with you as you go and not having to run another agent on the far end and authenticate it again.

All the machines in Peyton have agent forwarding setup by default, but if you're connecting from a laptop or home computer you may wish to turn it on. You can do so one of two ways:

1. Add the -A flag to ssh, ie ssh -A username@hostname
2. Edit (or create) the file ~/.ssh/config, and include these lines:

Host *
ForwardAgent yes

The first method might be handy for a one-off session, while the second will turn on agent forwarding for all connections.

ssh-agent for Windows

This is included in the article Setting up Putty in Windows

ssh-agent for Mac OS X

While Mac OS X does contain OpenSSH, there is no easy way to hook the ssh-agent process to your session by default. However, there is a program you can install which will do this, called SSHKeychain. You can get SSHKeychain from the website http://www.sshkeychain.org. Download and install the program (copy to your /Applications folder, for example). Double click the program to execute it. When you first run SSHKeychain, load its preferences and make the following changes:

• Under "Display", select "Status Bar" so only the icon in the status bar is visible
• Under "Environment", check the box for "Manage (and modify) global environment variables. The default settings should be OK.

Now close the preferences window and logout, then login again. This will start the ssh-agent process, and all the programs under your current login will be able to access it.

NOTE:

You will still need to either copy your keys from your Peyton account, or create new keys. You can use SSHKeychain to create new keys, or you can use the instructions above since OpenSSH will operate in the same way.

OS X SSH 'gotcha's

There's a couple things to note when using SSH on a Mac:

1. SSHKeychain will only work properly if the account is an administrative account

   By default, the first user setup on a Mac is forced to be an admin, so this most likely won't be an issue for most users. If you want to be sure you're an admin user, go to Apple Menu -> System Preferences -> Accounts and make sure "Allow user to administer this computer" is checked (it might be grayed out, but that's OK).

2. All forwarding is turned off by default

   Apple ships the SSH software on OS X so that all forwarding is turned off. In the Peyton Hall machines, when you ssh from one box to another, your ssh-agent keys and your X11 forwarding information carries through, so you can display things on the local machine from the remote one, and you can login again from the remote machine to another. In order to make the SSH software on the Mac behave like that installed in Peyton, you'll need to either create a file called ~/.ssh/config (if you want to enable it just on your account) or edit the file /etc/ssh_config (if you want to enable it on all the accounts on your Mac you will need to become root first, if you've enabled the root account, or use 'sudo' to exec your favorite editor on the file).

Host *
   ForwardAgent yes
   ForwardX11 yes
   ForwardX11Trusted yes

Tips & Tricks

• SSH Tips and Tricks

Errors & Warnings

• No SSH available?
• "Host Identification Changed" error message
• Failed Connections
• BadAtom Error

Advanced topics

• More information on SSH
• Advanced: Tunneling connections through SSH
• *IMPORTANT SSH Login Policies*

FAQ

---

Remember that once you setup keys, and have your ssh-agent running happily when you login, that you will need to use 'ssh-add' to add your keys to the running agent or else you will be asked for the passphrase every time! You only need to do this once per agent, so if you think they might be there use 'ssh-add -l' to list the keys. If you want to delete keys from the running agent, for example at the end of the work day, use 'ssh-add -D' to remove them.