Getting started with SSH

The following sections hope to provide enough information to setup a user new to ssh with the appropriate files necessary for accessing remote hosts in a secure manner.

Contents

• Intro to public key cryptography
• Creating your authentication key
  • Changing your pass-phrase
• Authorizing access
  • Directory and file permissions
• Logging into remote systems
• Keeping authentication keys in memory
  • Running X on a local display
  • Running X with an xdm session
• Managing keys in memory
• Running commands on remote systems
• Copying files between systems
• Changing default settings
• Sources of more information

Intro to public key cryptography

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 (i.e. the contents of the ~/.ssh/identity.pub file) in electronic mail or by other means e.g. to have a system administrator of a remote site install that key into your ~/.ssh/authorized_keys file. For anyone to actually gain access they need the corresponding private key (i.e. the decrypted contents of ~/.ssh/identity) to identify themselves.

To further protect your private key you should enter a passphrase to encrypt the key when it is stored in the filesystem. This will prevent people from using it even if the gain access to your files.

Creating your authentication key

The very first step is to use ssh-keygen to create an authentication key for yourself. In most cases the defaults for this command are what you want.

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.

  csociety% ssh-keygen
  Initializing random number generator...
  Generating p:  .++ (distance 6)
  Generating q:  ........++ (distance 110)
  Computing the keys...
  Testing the keys...
  Key generation complete.
  Enter file in which to save the key ($HOME/.ssh/identity): 
  [RETURN]
  Enter passphrase (empty for no passphrase): $av3 Th3 Tr33$
  Enter same passphrase again: $sav3 Th3 Tr33$
  Your identification has been saved in /home/sigos/.ssh/identity.
  Your public key is:
  1024 37 [lots of numbers] sigos@csociety.purdue.edu
  Your public key has been saved in /home/sigos/.ssh/identity.pub

If you have multiple accounts you might want to create a separate key on each of them. You may want to have have separate keys for

• your office environment
• your private systems
• your Internet service provider (ISP) systems
• your university account(s)

This allows you to limit access between these organizations, e.g. not allowing the university account to access your 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.

Changing your pass-phrase

You can change the pass-phrase at any time by using the -p option of ssh-keygen.

  csociety% ssh-keygen -p
  Enter file in which the key is ($HOME/.ssh/identity): 
  [RETURN]
  Enter old passphrase: $sav3 Th3 Tr33$
  Key has comment 'sigos@csociety.purdue.edu'
  Enter new passphrase (empty for no passphrase): 
  Y0ur Pa$$phra$e H3r3
  Enter same passphrase again:
  Y0ur Pa$$phra$e H3r3
  Your identification has been saved with the new passphrase.

The pass-phrases are not echoed as you type them.

Authorizing access

To allow access to a system for a given identity place the public key in your ~/.ssh/authorized_keys file on that system. All keys listed in that file are allowed access.

Usually you will want to authorize access to the local system using the local key (especially in an environment where multiple systems share the same home directory e.g. using NFS). Thus a good start is to copy the public key for your default identity into the ~/.ssh/authorized_keys file.

  csociety% cd ~/.ssh
  csociety% cp identity.pub authorized_keys

You could now copy the ~/.ssh/authorized_keys file to other systems to allow access from the local system. One way to copy the file is to use the ftp command.

Use a text editor to add more keys 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 files with the .pub extension).

NOTE: To gain access to restricted systems you might need to send your public key in electronic mail to the administrator of the system. Just include the contents of the ~/.ssh/identity.pub file in the message.

Directory and file permissions

If access to the remote system is still denied you should check the permissions of the following files on it:

• the home directory itself
• the ~/.ssh directory
• the ~/.ssh/authorized_keys file

The permissions should allow writing only by you (the owner). This example shows the most relaxed permissions you could use.

  etla% cd
  etla% ls -ld . .ssh .ssh/authorized_keys
  drwxr-xr-x  36 sigos  sigos  4096 Jul 25 02:24 .
  drwxr-xr-x   2 sigos  sigos   512 Apr 10 02:30 .ssh
  -rw-r--r--   1 sigos  sigos  1674 Apr 10 02:29 .ssh/authorized_keys

To make the remote system allow access you must change the permissions to disallow writing by others than the owner.

  etla% cd
  etla% chmod go-w . .ssh .ssh/authorized_keys

Remember to do this on all the systems you want to have access to.

Logging into remote systems

To establish an interactive connection to a remote system you would use either the slogin or the ssh command. The only parameter is the name of the remote system. The pass-phrase is not echoed back to you when you type it.

  csociety% slogin etla
  Enter passphrase for RSA key 'sigos@csociety.purdue.edu': 
  Y0ur Pa$$phra$e H3r3
  Last login: Wed Oct 16 20:37:00 1996 from idefix
  [more output from the remote machine]
  etla%

You can avoid the pass-phrase prompts by keeping the authentication keys in memory. You only need to type the pass-phrase when you add a key into memory.

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 to specify the remote account name.

  csociety% slogin -l oboyle gestalt.isca.uiowa.edu
  Last login: Sun Oct 13 14:55:17 1996 from csociety.ecn.purdue.edu
  [more output from the remote machine]
  gestalt%

You can change the default remote account name by creating a configuration file entry for the host.

Keeping authentication keys in memory

If you frequently open connections to remote systems you can run your session under the ssh-agent. The agent will provide decrypted authentication keys to all the commands when new connections are created.

When you start ssh-agent you need to provide it a command to spawn. This is usually either your shell or a command to start a windowing environment. When you exit the command all keys will be removed from memory.

  csociety% ssh-agent $SHELL
  csociety%

You will now need to add keys into memory to have them available for other commands.

Running X on a local display

If you have workstation where you start the X window system after logging in you can have the whole windowing environment benefit from the keys in memory. The X window system is normally started with startx and the initial clients are in your ~/.xinitrc file.

  csociety% ssh-agent startx &

If your workstation has virtual consoles it is good to put the X window system in the background so the current virtual console can still be used for more commands if necessary. It won't hurt to background the command even without virtual consoles.

NOTE: Your system might have a non-standard way of starting the X window system. Replace startx with the appropriate command if necessary. Please ask your system administrator for the exact command to use.

Running X with an xdm session

If you use an X-terminal or your workstation is running xdm you need to arrange for the clients to run under ssh-agent. The easiest way (which is conveniently compatible with the method used without xdm) is to put all initial clients into the ~/.xinitrc file which in turn is called from the ~/.xsession file.

An example ~/.xsession file is below. It runs ssh-agent only if you have a ~/.ssh directory.

  #!/bin/sh
  if [ -d $HOME/.ssh ]
  then EXEC="exec ssh-agent"
  else EXEC="exec"
  fi
  if [ -x $HOME/.xinitrc ]
  then $EXEC $HOME/.xinitrc
  else $EXEC xterm -geometry 80x24+0-60 -ls
  fi

Make sure the files are executable. The following command will change the permissions suitably.

  csociety% chmod u+x ~/.xinitrc ~/.xsession

What you have now done is made ssh-agent your initial process in your X session. After you use ssh-add to give your identity to the agent, we can seamlessly ssh over to all hosts who know who we are, should our destination be 'ssh-friendly' X11 forwarding is automagically set up for you.

NOTE: If you are using an X-terminal keep in mind that your session is most likely not secure. Usually anything you type can be captured on the local area network you are connected to.

Managing keys in memory

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. The pass-phrase is prompted for to decrypt the key. It is not echoed back as you type it.

  csociety% ssh-add
  Need passphrase for /home/sigos/.ssh/identity (sigos@csociety.purdue.edu).
  Enter passphrase: Y0ur Pa$$phra$e H3r3
  Identity added: /home/sigos/.ssh/identity (sigos@csociety.purdue.edu)

## Get my passphrase for ssh'ing around.


You can specify the file that contains the key if you have other
identities than the default.  You must use the private key
file (the one that does not have the .pub
extension).

The -d option will have the key deleted from memory.
There is no ssh-delete command.

  csociety% ssh-add -d ~/.ssh/isp


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

  csociety% ssh-add -l
  1024 37 [lots of numbers] sigos@csociety.purdue.edu
  1024 35 [lots of numbers] sigos@etla.ecn.purdue.edu


You can delete all keys from memory at once with the -D
option.

  csociety% 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.



    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.

  csociety% ssh gestalt.isca.uiowa.edu who
  oboyle 	ttyp8    Oct 17 20:42  (csociety.ecn.purdue.edu)
  csociety%


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.

  csociety% ssh -n etla xterm &
  [1] 15866
  csociety%


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 copy files from the local system to a remote system or
vice versa, or even between two remote systems using the
scp command.  To
specify a file on a remote system simply prefix it with the name
of the remote host followed by a colon.

If you leave off the filename of the copy or specify a directory
only the name of the source file will be used.  An easy way of
retrieving a copy of a remote file into the current directory
while keeping the name of the source file is to use a single dot
as the destination.

  csociety% scp -p etla:aliases .
  csociety%


The -p option is not required.  It indicates that the
modification and access times as well as modes of the source 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.

  csociety% scp -p etla:.login etla:.logout gestalt.isca.uiowa.edu:.
  csociety%


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.

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.



    Changing default settings

The defaults for the ssh-related commands can be altered for each
account in a configuration file ~/.ssh/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:


? matches any single character
* matches any sequence zero or more characters


Usual keywords include (defaults in parenthesis):


Compression yes/no (no)
Controls whether compression is used on the connection.
CompressionLevel 1-9 (6)
Level of compression: 1 is fastest, 9 is slowest (achieves best
    compression).  Compression is good for slow links (saves
    bandwidth) and fast machines.
FallBackToRsh yes/no (yes)
If a secure connection to the remote system cannot be established
    the commands can try unsecure connections (a warning will be
    displayed if this happens).  On highly secure systems this could
    be disabled in the system-wide configuration.
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 ~/.ssh/config file.

  Host *purdue.edu
    User sigos
    Compression no

  Host *uiowa.edu
    FallBackToRsh no

  Host *
    Compression yes
    CompressionLevel 9
    FallBackToRsh yes
    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 *purdue.edu but will be used
for hosts that match *uiowa.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.



    Sources of more information


Some people like to create functions (these happen to be in ksh) to manage
ssh.  For example, if one was behind a firewall that didn't allow servers
to connect on privileged ports, you could use the -P option
to tell ssh to not connect back to a priviledged port on the local side.



For more tricks for using ssh behind a firewall, drop me a note.


  ssh () {
    /usr/bin/ssh "$@"
  }

  sterm () {
    ssh -f "$1" "exec /usr/X11/bin/xterm -T '$1' -n '$1'"
  }





The SSH Home Page
    has information on the protocol and distribution of ssh.
The SSH
    FAQ anwers common questions on obtaining, installing and tuning
    ssh.
Data Fellows offers
    commercial implementations of ssh.
SSH Communications Security
    has information about the development of ssh.