SSH background channels
=======================

SSH's internal port forwarding mechanism makes it possible to protect many
TCP-based services. Sometimes this port forwarding is the only purpose of an
SSH connection. In this case it is a good idea to establish the secure SSH
channel in the background. 

I use such a background channel for the mailer "pine". Pine is able to
manipulate remote mailboxes via the IMAP protocol. The client (user)
authenticates by sending a cleartext password. When using an SSH channel the
whole IMAP communication is now transparently encrypted, thus avoiding
cleartext passwords. 

IMAP is only an example. Other protocols can benefit from background channels
as well, e.g. POP.

In the current SSH implementation it is necessary to specify a remote command
which is to be executed on the server. Its sole purpose is to keep the secure
channel open. Therefore it should merely generate a minimal load. The channel
can be closed by killing this command.

The script "secure_imap" (written for SSH 1.2.13) sets up a aforementioned
background channel for pine. It works as follows:

- The script itself must be started as child of an ssh-agent.
  I run it in a new xterm and use the following tcsh alias to do so:

     alias mail 'xterm -e ssh-agent secure_imap &'

- At first some shell variables are initialized:
    
	 ID_FILE      --- SSH identity file to login on the server
     IMAP_SERVER  --- name of host where the IMAP server is running
	 IMAP_PORT    --- port the IMAP server listens on
	 MAILER       --- the mailer command to be executed

  These settings must be adapted to a specific environment.

- A private RSA key is added to ssh-agent. This key is used to login on 
  the host where the remote IMAP server is running. If the key is stored
  in a password-protected file you are asked for this password.

- In a next step the script tries to find a free local TCP port which SSH 
  can forward. Under certain conditions even a fixed port should completely
  suffice, e.g. when you use your computer alone and start your background 
  channels just after booting the machine or if the SSH channel is established 
  by "root" as a regular service for all users.

- Now the background channel is created by starting SSH in the background
  (option -f) with local port forwarding enabled (option -L). The option -f 
  requests SSH to go to the background after the authentication is done and 
  the TCP forwarding is established.

  In SSH version 1.2.13 the option -f implies the option -n, thus closing 
  standard input. Therefore it's necessary to run a remote command not 
  terminating on EOF.

  As remote command the little C program "ssh_pause" is executed. It contains
  just one statement: a call of the function pause(). This means, the command
  will sleep until waked up by a signal. Then it will silently terminate and
  the channel will be closed.

  Because ssh_pause takes no account of its command line arguments we can use 
  them to distinguish between different incarnations of the program. This 
  makes it easy to kill the right process when a channel is no longer needed. 
  
  ssh_pause can be used for different purposes and from many clients. 
  Therefore the command line contains a protocol identifier (imap), the 
  hostname of the client and the process id of the current secure_imap script:

    ssh_pause imap `hostname` $$

  If this should be not enough you are free to find better distinguishing
  features.

- Afterwards pine's config file $HOME/.pinerc is modified to tell the 
  mailer on which local port it can talk to the IMAP server. This step is 
  not necessary when using fixed ports.

  Note: The documentation of Pine 3.91 doesn't discuss the possibility to 
        specify the IMAP port. It's a (in my opinion undocumented) feature
		of the underlying c-client library. You can specify the port number
		after the host name, separated by a colon, e.g:

           inbox-path={localhost:1456}

  Before the config file is modified a backup copy ($HOME/.pinerc.backup) is 
  made, just in case. 
  
  Recommendation: Make a backup of your $HOME/.pinerc before running secure_imap
                  for the first time. In case something goes wrong you don't
				  lose your private settings.

- Now the mailer pine is started. The SSH authentication is accomplished 
  by ssh-agent. Nevertheless you have to authenticate with the IMAP
  server by typing your normal password.

- After pine has finished, the channel is closed. This is done by killing
  the corresponding ssh_pause process. As discussed above it's easy to find 
  the right one because of the unique command line arguments. Killing is done 
  by a script "kill_proc" which selects the ssh_pause process by analyzing 
  the output of "ps".



Holger Trapp (hot@informatik.tu-chemnitz.de)
21 March 1996
