Getting started with SSH

The following sections should provide enough information to start using the secure shell program, ssh, between UNIX computers. (Ssh can also be used between UNIX computers and Macintosh and Windows computers but this document will focus on UNIX. See below for more Mac and PC information.)

Ssh (Secure Shell) is a program to log into another computer over a network, to execute commands in a remote machine, and to move files from one machine to another. It is intended as a replacement for rlogin, rsh, rcp and telnet. The key is that ssh provides strong authentication ("Are you who you say you are?") and secure communications (conversations which cannot be deciphered by hackers) over unsecure networks.

It also provides neat services like handling xauth commands for you and providing a single-login facility (where you only have to give your password once in order to login to multiple domains of computers) via the ssh-agent and ssh-add commands.

There are actually two different versions of the SSH protocol (SSH-1 and SSH-2) and strictly speaking, they are not compatible. For a discussion of the two implementations, see http://www.snailbook.com/faq/ssh-1-vs-2.auto.html. We are using SSH-2, with fallback support for SSH-1 clients.

Contents

Why use ssh? What is it good for?

The traditional Berkeley UNIX 'r' - commmands (rsh, rlogin, rcp) are vulnerable to different kinds of attacks. Somebody who has superuser access to machines on the network, or physical access to the wire, can log all the network traffic to and from your system, including your userid and password.

They can use that information to pretend to be you; therefore they can gain unauthorized access to any password-protected computer you use (locally or remotely). Even if they don't pretend to be you, they can record all of your keystrokes as you work from machine A over the network to machine B.

A primary benefit to ssh is that it encrypts your keystrokes so no one can see them as they pass over the network.

The X Window System also has a number of severe vulnerabilities. With ssh, you can easily create secure remote X sessions. Ssh conveniently handles setting your DISPLAY variable and running xauth for you.

Ssh protects against these kinds of attacks:

In other words, ssh never trusts the network; somebody hostile who has taken over the network can only force ssh to disconnect, but cannot decrypt or play back the traffic, or hijack the connection.

About public key cryptography

Cryptography is the science of protecting information by making it unreadable to those without a key of some kind. To communicate back and forth between two points, both sides need to know the key. If you don't trust a computer network, how can you securely send your key from point A to point B so that you can then use the key to encrypt your data and transmit it privately in the future?

Things get more complicated when you realize that network packets are pretty faceless critters. Just because one comes bearing a key, how do you know it was sent by the computer it claims to be from? This makes it useful to do some checking on the computer's identity as well as verifying that the key works.

Public key cryptography uses a public key to encrypt data and a private key to decrypt it. The name public key comes from the fact that you can make the encryption key public without compromising the secrecy of the data or the decryption key.

What this means is that it is safe to send your public key in electronic mail or by other means. For anyone to actually gain access they need the corresponding private key to identify themselves.

Overview of using ssh for the first time

NOTE: One does not have to follow all of the steps below to use ssh. You can get the primary benefit (encryption of your connection) without generating a key pair or modifying any of the files in your .ssh directory. Just use "ssh other-computer"

These other, more involved, steps are helpful for people who are going to use ssh between domains of computers and/or more sophisticated tools, like ssh-agent.

When I say "end" below, I mean the computer at one end of a two-computer connection you wish to make or are making. In general, I assume that the ends will be in different security domains, so you'll want a different password to get into each end. The ~ (tilde) sign indicates your home directory.

Is ssh available on both ends?

The first thing to do is to make sure both computers have ssh installed. You can check your end by running ssh -V. (That is a uppercase -V. The lowercase -v option means "connect but emit verbose status messages.")

If you get a "ssh: Command not found" error message, then either ssh is not installed on your computer or it is not in your search path.

You can check the other end with the telnet program. The ssh daemon listens for incoming connections on port 22. If you telnet to that port on a host, (telnet hostname 22), it will say "connection refused" if ssh is NOT installed. In that case, immediately ask your system administrator to quickly install the latest version of ssh so their computers will be more secure! She or he can get a copy from the ssh home page http://www.ssh.com.

If ssh is available, you will see 

Trying 220.220.220.220...
Connected to hostname.
Escape character is '^]'.
SSH-1.99-2.4.0 SSH Secure Shell (non-commercial)
You can then type "quit" to close the connection.

Creating your authentication key

The next step is to use ssh-keygen to create a pair of authentication keys (one public, one private) for yourself. These will be stored in your .ssh2 directory as ~/.ssh2/id_dsa_1024_a (the private key) and ~/.ssh2/id_dsa_1024_a.pub (the public key). The naming convention used is
id = identification
dsa = public key encryption method
1024 = key length (in bits)
a = key a (subsequent keys will be b, c, d, etc by default).

If someone has access to the private key, they can use it to pretend to be you. Because we work in a very cooperative environment, by default most users can read many of the files in our home directories. Even if they couldn't, a hacker could break into your machine by some method other than password sniffing, and then take your private key and pretend to be you to get onto other machines. The private and public keys are stored on disk in files because they are too long (over two hundred characters) to memorize or type by hand.

Knowing this, the authors of ssh made ssh able to encrypt your private key before storing it to or reading it from your home directory. To do this, ssh will ask you for a password when you need to read that ~/.ssh2/id_dsa_1024_a file. Actually, ssh allows you to use more than one (pass) word -- you can specify a short phrase that, taken together, acts as a password.

Always, always, type in a good pass-phrase when prompted for one. It can be multiple words (i.e. spaces are just fine within the phrase), so you could choose a sentence that you can remember. Changing some of the words by misspelling them or by changing some of the letters into digits is highly recommended to increase the strength of your pass phrase.

Here is a sample session, your input is in bold. Note that the pass-phrase is not echoed back as you type it. It is shown here only as an example. DO NOT USE THE SAMPLE PASS-PHRASE SHOWN BELOW AS YOUR OWN PASS-PHRASE! 

  myworkstation% ssh-keygen -c myuserid-ssh2@home
  Generating 1024-bit dsa key pair
     4 .oOOo.oOo.oO
  Key generated.
  myuserid-ssh2@home
  Passphrase : red 3agle, midnight
  Again      : red 3agle, midnight
  Private key saved to /home/myuserid/.ssh2/id_dsa_1024_a
  Public key saved to /home/myuserid/.ssh2/id_dsa_1024_a.pub
  myworkstation%
Okay, now you have a pair of keys on one computer, which we'll call computerA. You need to copy the public key to the remote computer(s) so you can start having a secure two way conversation.

If you have accounts on computers in multiple organizations, you should create separate keys on each of them. I have separate keys for

This allows me to limit access between computers in these organizations, e.g. not allowing the university account to access my ISP account or the machines in the office. This enhances the overall security in the case any of authentication keys are compromised for some reason in one place.

People are going to have more and more passwords in the coming years. Passwords, pass-phrases, PIN numbers, etc. The only thing you can do (without carrying around a password-protected Personal Digital Assistant) is write them down on a small scrap of paper and put it in your wallet. This does not have to be as risky as it sounds.

  1. People are careful about what they do with their wallets!
  2. The list of passwords is more secure if you don't describe what they are used for (they're just a list of words).
  3. And you can make passwords even more useless to thieves if you simply mix up their contents a bit. Use a simple convention to make your passwords hard to read, by, for example, moving the first two letters of any password or PIN to the end of word).

The -c (comment) option to ssh-keygen allows you to give a more meaningful name to your pair of keys. By default, ssh-keygen will name your keys youruserid@machineonwhichyourunssh-keygen (e.g. user@eta). It may help you remember which key is which if you use -C myuserid@domainname (e.g. myuserid@pha).

You specify which identity you will be using to authenticate to other computers with the ~./ssh2/identification file. Add the following line to your identification file: 

IdKey id_dsa_1024_a   # You can rename this private key to something
		      # more meaningful.  Just be sure to change the
	              # corresponding file name in ./ssh2
If your identity varies from machine to machine, this file file will be machine-specific.

Unlike ssh1, ssh2 does not support changing the passphrase on an existing key.

Authorizing access

To allow access to a system for a given identity specify the public key in your ~/.ssh2/authorization file on that system. All keys listed in that file are allowed access via ssh (if they have the right pass-phrase).

Start by copying the public key for your default identity into the ~/.ssh2/authorization file. 

myworkstation% cd ~/.ssh2 
myworkstation% vi authorization
Add the following line to the file ~/.ssh2/authorization: 
Key id_dsa_1024_a.pub # Note that you can change the name of this
                      # to something more meaningful, like pha-ssh2-key.pub.
                      # Just be sure to change the corresponding file name
		      # in ./ssh2.
If you want to use ssh only within one organization, say within your department, then you will have only one key in authorization. If you want to use ssh to go between two sets of computers, say your department and your university account, you would have multiple keys in the file.

A second file is specific to the local machine, ~/.ssh2/identification. This file specifies what private key you want to use when authenticating to other computers. So the next step is to add the following line to ~/.ssh2/identification: 

IdKey id_dsa_1024_a   # Again, you can rename this private key to something
		      # more meaningful.  Same rule as above applies.
Keep in mind that the ~/.ssh2/identification file will vary from identity to identity (ie your isp key, work key, home key).

Use a text editor (e.g. pico, vi, gnuemacs) to add more keys (that you've generated on other computers using ssh-keygen) to the file. If you use cut and paste to copy the key make sure each key entry is a single line in the file. The keys to add are always the public keys (from key.pub files).

You should now copy the ~/.ssh2/authorization file to other systems (in other organizations) to allow access from the local system.

One way to copy the file is to use the scp command. You can also send it in electronic mail, via the ftp command or even by putting it on a floppy disk and hand carrying it to the other computer.

Directory and file permissions

Make sure that the ~/.ssh2 directory and the files in it are not world-writable. They can all be world-readable, (except for the id_1024_dsa_a file, which is the private key). Ssh will not connect to machines where some of the ssh control files are world-writable. These are the most important ones to protect: The permissions should allow writing only by you (the owner). This example shows the most relaxed permissions you could use. 
  myworkstation% cd
  myworkstation% ls -ld authorization identification id_dsa_1024_a id_dsa_1024_a.pub
  -rw-r--r--   1 you     you         26 Mar 26 11:29 authorization
  -rw-r--r--   1 you     you         11 Mar 26 11:33 identification
  -rw-------   1 you     you        825 Mar 26 11:12 id_dsa_1024_a
  -rw-r--r--   1 you     you        686 Mar 26 11:12 id_dsa_1024_a.pub
You can set these permissions with these commands: 
  myworkstation% cd
  myworkstation% chmod go-w .ssh2/identification
  myworkstation% chmod a+rx .ssh2
  myworkstation% chmod a+r .ssh/authorization
Remember to do this on all the systems you want to have access to.

Logging into remote systems

To establish a secure, interactive connection to a remote system you would simply use either the ssh or the slogin commands instead of the insecure rsh, rlogin or the telnet commands. slogin is a symbolic link to ssh, so it's shorter/easier to use the ssh command. Slogin is still available only for the convenience of people who are used to it.

The only required parameter is the name of the remote system. (The pass-phrase shown below is not actually echoed back to you when you type it.) 

  myworkstation% ssh othercomputer
  Passphrase for key "/home/you/.ssh2/id_dsa_1024_a" with comment "you-ssh2@pha":red 3eagle, midnight
  Authentication successful.
  [more output from the remote machine]
  othercomputer%
Now all of your keystrokes will be transmitted in encrypted form. If you start any X Windows programs, the X data sent back and forth will be encrypted too.

If your account name on the remote system differs from the one on the local system (the system you are connecting from) you can use the -l switch or ssh user@host to specify the remote account name. (That is a lowercase L character, not the number one.) 

  myworkstation% ssh -l othername othercomputer
  Passphrase for key "/home/you/.ssh2/id_dsa_1024_a" with comment "you-ssh2@pha":red 3eagle, midnight
  Authentication successful.
  [more output from the remote machine]
  othercomputer%
or... 
  myworkstation% ssh othername@othercomputer
  Passphrase for key "/home/you/.ssh2/id_dsa_1024_a" with comment "you-ssh2@pha":red 3eagle, midnight
  Authentication successful.
  [more output from the remote machine]
  othercomputer%
You can change the default remote account name by creating an entry for the host in the ssh configuration file ~/.ssh2/ssh_config. Then you won't need to use the -l option to specify the remote account name every time you connect to that host.

Troubleshooting ssh connections

If you have problems making a connection and you're not sure why, you can use ssh -v to get verbose output on what is being done by the local ssh program and the remote sshd server daemon. (That is a lowercase -v. The uppercase -V option means "print version number and exit.")

Running commands on remote systems

The ssh command can also be used to run commands on remote systems without logging in. The output of the command is displayed and control returns to the local system. Here is an example which will display all the users logged in on the remote system. 
  myworkstation% ssh myworkstation who
  christos ttyp8    Oct 17 20:42  (milou)
  myworkstation%
If you are using the X Window System you can use this capability to start a terminal window to start an interactive session on the remote system. 
  myworkstation% ssh -n myworkstation xterm &
  [1] 15866
  myworkstation%
Use the -n to avoid the remote system from trying to read from the terminal starting the xterm and put the process in the background. A new window from the remote system should appear shortly on your display.

Copying files between systems

You can securely copy files from the local system to a remote system or vice versa, or even between two remote systems using the scp command. Starting with SSH-2, sftp is also available to transfer files securely. If you use ftp, you have to send your password over the network unencrypted. If you use rcp, you have to have insecure .rhosts or /etc/hosts.equiv files in place beforehand. You can scp or sftp files around and it will encrypt your pass-phrase if it is required. If you are comfortable with using ftp, sftp should be very familiar - commands are based on ftp.

Sftp and scp serve slightly different purposes. If you have one file that you want to transfer quickly, scp can be more useful. If you want to copy multiple files interactively, sftp is better.

When using scp, to specify a file on a remote system, simply prefix it with the name of the remote host followed by a colon, as in this example, which copies a file from your home directory on computerB to the current directory on computerA: 

  computerA% scp -p computerB:aliases .
  computerA%
The -p option is not required. It indicates that the modification and access times as well as modes of the original file should be preserved on the copy. This is usually desirable.

You can copy several files in a single command if the destination is a directory. You can also copy files between two other machines. This example makes use of both of those features: 

  computerA% scp -p computerB:.login computerB:boofoo hn.stsci.edu:.
  computerA%
Relative filenames resolve differently on the local system than on the remote system. On the local system the current directory is assumed (as usual with all commands). On the remote system the command runs in the home directory! Thus relative filenames will be relative to the home directory of the remote account.

More examples of scp usage can be found at the Ssh quick command reference.

NOTE: When you specify remote machines in both the source and the destination the connection to copy the files is made directly between those hosts. The files are not copied through the local system. Sometimes this makes a difference in a firewalled or otherwise restricted environment.

To transfer multiple files, an interactive session is often useful. sftp supports copying files in much the same wayas traditional ftp, but it encrypts all traffic. Don't be confused by the similarities, however - an sftp client cannot connect to an ftp server, nor can SSH-2 servers accept ftp connections (w/o setting up special forwarding configurations). Despite these fundamental underlying differences, the two share an extremely similar command syntax. Use sftp as you would ftp: 

computerA% sftp computerB
sftp> pwd
/home/you
sftp> get file
file                     |         62 kB |  62.5 kB/s | TOC: 00:00:01 | 100%
Type help at the sftp prompt to list all the commands it supports. Unlike ftp, sftp does not distinguish between ASCII and binary transfers; it only supports binary. Therefore ASCII files transferred from Windows machines will not display end-of-line characters properly.

Changing default settings

The defaults for the ssh-related commands can be altered for each account in a configuration file ~/.ssh2/config (there is also a system-wide file, usually /etc/ssh_config). Each entry starts with a Host keyword. You can use wildcards to match all the appropriate systems: Usual keywords include (defaults in parenthesis):
Compression yes/no (no)
Controls whether compression is used on the connection.
EscapeChar character (~)
Escape sequences are used to send special signals to ssh, such as to list forwarded connections, suspend, or terminate. You can change the defaul ~ with this keyword.
KeepAlive yes/no (yes)
Controls whether TCP keepalive messages are used. When enabled it is possible to detect network outages and automatically close your connections (which is good). However, if you are connected over a dialup link that automatically dials when there is traffic, you will want to turn this off to avoid unnecessarily bringing up the line.
User account (local account)
Specify the remote account name. Add this to avoid having to use the -l option when issuing commands.
Here is an example ~/.ssh2/config file. 
  Host *nasa.gov
    User you
    Compression no

  Host *jhu.edu
    EscapeChar ^

  Host *
    Compression yes
    EscapeChar !
    KeepAlive no
Options are accumulated over entries, but a more specific entry will override a less specific one. E.g. in the above compression will not be used for hosts that match *nasa.gov but will be used for hosts that match *jhu.edu (and all other hosts since the * entry matches all hosts).

For a complete list of options please refer to the manual pages of both ssh and sshd.

Keeping authentication keys in memory

If you frequently open connections or copy files to remote systems you can avoid having to repeatedly type in pass-phrases by keeping some or all of your authentication keys in memory. This mode of authentication is called using "RSA keys". (If you don't do RSA, you are using either password or /etc/hosts.equiv-style authentication.) A key benefit of using ssh-agent is that you no longer need to use .rhosts or .shosts or /etc/hosts.equiv or /etc/shosts.equiv files to login or copy files without typing your passphrase. Even if a user can break into your account, as long as you used a passphrase to encrypt your private key file, they cannot do RSA authentication as you.

A program called ssh-agent will provide decrypted authentication keys to other machines when you connect to them with the ssh or slogin or scp commands. You will need to type the pass-phrase only once -- when you load an identity into ssh-agent with the ssh-add program (see the next section below).

There is a trick to this, and that is that ssh-agent will do this automatic key transmission only for programs that were started by a shell that was started by ssh-agent. UNIX programs inherit configuration information from the programs that start them ("parent" processes give their configuration to their "children" processes). For security reasons, ssh-agent checks to ensure that the program trying to use it is a child of itself.

When you start ssh-agent you need to provide it a command to spawn. This is usually either your shell (e.g. /bin/csh) or a command to start a windowing environment (e.g. startx to start an X Windows session). When you exit the command, all of the keys will be removed from memory.

Computer Center-maintained Solaris 2.6 (and later) computers start ssh-agent automatically for you at the right place in the CDE startup process for all of your shells to be children of ssh-agent. Therefore, you only need to use ssh-add when using the console of these workstations. You're welcome! (Of course, if you login remotely, you'll need to use something like ssh-agent /bin/csh by hand.)

Here are two examples, one for any UNIX environment and one for an X Windows environment. 

  myworkstation% ssh-agent $SHELL
  myworkstation%

  myworkstation% xterm -exec ssh-agent /bin/csh &
  myworkstation%
You will now need to add keys into memory with ssh-add to have them available for ssh, slogin or scp commands. Those commands have to be run by a child of the shell in the first example and from the xterm in the second example. If you would like add keys to your current shell or xterm, you can do so by issuing the following command 
  myworkstation% eval `ssh-agent`
  Agent pid 880
  myworkstation% ssh-add

See the systems administration tips page for pointers to configuring X Windows sessions to use ssh-agent for all xterm sessions.

Because of the complexity of X Windows implementations and the lack of time for testing, the Computer Center cannot assist people in using this feature to enable ssh-agent support for an entire OpenWindows or CDE session if the above information is not sufficient.

Managing keys in memory

This section describes an advanced ssh feature.

Before your connections can be authenticated without prompts for a pass-phrase you have to use ssh-add to add the necessary keys to memory. To add the default key on the current system to memory no options are needed. To add keys for other domains, you need to have the private key files for those domains in the local .ssh2 directory.

The pass-phrase is prompted for to decrypt the key. It is not echoed back as you type it. 

  myworkstation% ssh-add
  Adding identity: /home/you/.ssh2/id_dsa_1024_a.pub
  Need passphrase for /home/you/.ssh2/id_dsa_1024_a (you-ssh2@pha).
  Enter passphrase: red 3agle, midnight
  myworkstation&
You can specify the file that contains the key if you have multiple identities. You must use the private key file (the one that does not have the .pub extension, normally ~/.ssh2/id_dsa_1024_a on that particular domain). (When creating your .ssh2/authorization file, you need to specify all of the public key components for your multiple domains to the same file, one per line. Therefore this part of setting up ssh-agent can be confusing because you are supposed to have multiple files, one for each domain, with the private key information in them.) this is different For example 
  myworkstation% ssh-add ~/.ssh2/goddard
  Adding identity: /home/you/.ssh2/goddard.pub
  Need passphrase for /home/you/.ssh2/goddard (you-ssh2@goddard).
  Enter passphrase: red 3agle, midnight
  myworkstation&

To list all keys currently in memory use the -l option. 

  myworkstation% ssh-add -l
  Listing identities.
  The authorization agent has 2 keys:
  id_dsa_1024_a: you-ssh2@pha
  goddard: you-ssh2@goddard
  myworkstation%
The -d option will delete the specified key from memory. There is no ssh-delete command. 
  myworkstation% ssh-add -d ~/.ssh2/goddard
You can delete all keys from memory at once with the -D option. 
  myworkstation% ssh-add -D
This is useful if you have added keys into memory on remote systems and don't want to reconnect just to delete the keys.

Ssh and X Windows

Ssh makes it very easy to run X Windows programs on computerB and display them on computerA.

If you use ssh to go from computerA to computerB (and don't turn off the X forwarding feature, which is enabled by default), ssh will set the DISPLAY variable on computerB to display back on computerA. Ssh will also exchange xauth magic cookies from computerA to computerB automatically. So you do not have to set the DISPLAY variable by hand or run xauth by hand! (Xauth is a more secure implementation of the xhost program that may be more familiar to you.)

Why is the protocol version (SSH-1 or SSH-2) important?

SSH-1 and SSH-2 should live peacefully in our environment, but there are some important things to know about interoperability between the two. The two protocols are NOT compatible and if you try to connect with an SSH-1 client to an SSH-2 server (or vice versa), it will fail. That said, on Computer Center maintained machine, we have configured our SSH-2 to fallback to SSH-1 if an incompatible client attempts to connect. You may find problems when trying to ssh from our domain to other domains if the remote administrators have not configured support for both protocols. This is particularly true of sftp - since this is a new subsystem of SSH-2, sftp will not work at all with an SSH-1 client or server. If you have difficulties copying files FROM a Computer Center client to a remote SSH server, trying using scp1 or /usr/site/ssh1/bin/scp at the commandline - the remote server may be running SSH-1.

Macintosh and PC ssh information

See the related web pages for recommended Macintosh and PC ssh-capable programs. Additional, unexplored programs are included in the next section.

Sources of more information

See the on-line manual pages for ssh, scp, ssh-keygen, ssh-agent, ssh-add. For example, man ssh. These programs for Windows 95/98/NT have not been explored but are provided simply for your further exploration.