Secure Mail Transfer via SSL Guide
----------------------------------

What is this guide?

	This guide details two methods for using SSL to securely
	transfer all of your email. XFMail does not have builtin
	support for SSL connections, but it is easy to use standard
	UNIX tools to support SSL connections. The first method
	describes using the STUNNEL utility and the second part
	mentions how you can do the same using SSH tunneling.


	Secure Mail Transfer via SSL using STUNNEL
	------------------------------------------


What's this all about?
	This document briefly describes how you can secure the transfer of mail
	between Xfmail and an email server via SSL.  I recently needed to do this
	in order to connect XFMail to a IMAP server that was only accessible via 
	SSL. I found that this was actually a quite simple process, and the same
	principles can be applied to other protocols as well, such as SMTP,
	POP-3, HTTP, and others that by default transfer everything in clear 
	text across the Internet.  


Who wrote this?
	Wim Kerkhoff <wim@merilus.com>, October 31, 2000

	I wrote this up, as I'm sure that many others will want to do the same 
	thing.  I spent several hours trying to get this to go, and then 
	stumbled on this easy solution.  If it doesn't work for you, your 
	first bet is to read the Stunnel FAQ at www.stunnel.org/faq/.

	Additions and typo fixes from Duncan Haldane <f.d.m.haldane@mciworld.com> 
	were added on December 3, 2000.


What do I need?
	You will need the Stunnel tool.  You can get this at 
	http://www.stunnel.org/download/.  This depends on openssl, so if you 
	want to build stunnel from source, you will need to build openssl from
	source as well.  I use Debian; it was simple as apt-get install stunnel.  
	This will download and install stunnel and all its dependencies.  stunnel
	and openssl are also part of some other newer Linux distributions, such as 
	Red Hat 7.0; for older distributions (and Red Hat < 7.0), you can find an 
	assortment of stunnel and openssl RPM packages at http://www.rpmfind.org.   
	(You may need to create a PID directory like /var/run/stunnel/ after 
	installing the RPM, if it does not get created:
             
	stunnel -V 

	will tell you the precise name you should use.)


What do I do?
	As root, invoke stunnel in client ("-c") mode: 

	stunnel -c -d <insecure port> -r <remote host>:<secure port>

	So for IMAP, you are trying to set up a tunnel between port 143 on your 
	local system with port 993 on the remote host.  Your command would look 
	like: 

	stunnel -c -d 143 -r mail.yourdomain.com:993

	These ports have friendly service names, listed in /etc/services: 143 = "imap"
 	or "imap2", 992 = "imaps" or "simap" (check what names are used by your system). 
  	If it is listed, you can use the friendly service name, e.g. "-d imap" and 
  	"-r mail.yourdomain.com:imaps".
  
  	For POP-3, the insecure port is  110 ("pop3")  instead of 143, and the secure 
  	port is 995 ("pop3s" or "spop3")  instead of 993.   

  	For SMTP (outgoing mail) , the insecure port is 25 ("smtp") and the secure
  	port is 465 ("smtps" or "ssmtp").

  	You may find that when you try to connect to the port 143 or 110 on your local 
  	system, the connection gets intercepted by local imapd or ipop3d daemons, which
  	get started by the inetd daemon.  If this is so, you must either use a different
  	unused port (e.g. "9999") as the insecure port on your local system, or comment
  	out the  imapd or ipop3d entries in /etc/inetd.conf, which are not needed if 
  	your local system does not need to be a imap or pop3 server. (Shut down and 
  	restart inet services to activate changes to /etc/inetd.conf).

	
	You'll probably want to add the command that creates the stunnel into 
  	/etc/rc.boot/somescript or something so that the tunnel will be automatically 
  	created  when the system is booted, so you don't have to do it manually (you will 
  	need to specify the remote host" mail.yourdomain.com" by its IP number, or create 
  	an entry for it in /etc/hosts, if you don't have nameserver service available 
  	when the tunnel is created.)

	Now, the final task is to start Xfmail, open the configuration menu, and create a
  	new IMAP or POP account. Instead of setting the Xfmail "Receive" configuration 
  	"Host:" entry to "mail.yourdomain.com", use  "localhost" (or "127.0.0.1").
  	If the default (insecure) imap or pop3 port is in use by a local server, change 
  	the default port in the Xfmail "Receive" configuration to the one you specified 
  	in the "-d ..." option to stunnel. 

	That's all!

	You don't need to run stunnel as root, but that's they only way you'll have
	access to the default insecure ports, which are under 1024.  Using the 
	default ports makes configuration in your various clients easier, because 
	you won't have to change their default port.


What else can you do with stunnel?
	From a quick look at the FAQ (www.stunnel.org/faq/), it seems like you can:
	- setup PPP over the SSL tunnel (create a VPN)
	- use certificates, so that you can be sure that whoever is making a 
	  connection is who they say they are
	- run in different modes: inetd/daemon/tcp wrappers
	- encrypt existing services 
	- secure traffic between two systems, when you do not control any part of 
	  the network between, or even have root on the two systems.  You could 
	  run SMTP AND POP over SSL, without having to bug your network 
	  administrator.


	Secure Mail Transfer via SSL using SSH tunneling
	------------------------------------------------

	This section contributed by: Andy Harrison <ah42@httpsite.com>


   Advantage: no server modification
Disadvantage: you have to be able to login to the server

I use a small script to start xfmail right from my home directory:

~/xfmail.sh
#!/bin/sh
start ()
{
        /usr/X11R6/bin/xfmail &
}
stop ()
{
        printf "\ndon't kill xfmail this way...\n\n"
        printf "if it's really important, kill it yourself...\n\n\n"
        ps -x -o command,pid,user | grep ^xfmail | grep -v grep
        printf "\n"
}

starttunnel()
{
        ~/smtptunnel.ssh
        ~/imaptunnel.ssh
        ~/poptunnel.ssh
}

case "$1" in
        start)
                starttunnel
                start
                ;;
        stop)
                stop
                ;;
        stoptunnel)
                SSHPID=`ps ax | grep 'ssh.*sleep' | awk '{print $1}'`
                kill $SSHPID
                ;;
        restart)
                stoptunnel
                starttunnel
                ;;
        *)
                echo ""
                echo "Usage: `basename $0` { start | stop | restart | stoptunnel }"
                echo ""
                exit 64
                ;;
esac


The scripts that it calls are as follows:
~/imaptunnel.ssh
ssh -P -f -L 60143:localhost:143 my.imaphost sleep 32400
~/poptunnel.ssh
ssh -P -f -L 1234:localhost:110 username@office.mail.server sleep 32400
~/smtptunnel.ssh
ssh -P -f -L 60025:localhost:25 my.smtphost sleep 32400

They specify which local port to forward to the remote server.  60143 forwards
to port 143 on my.imaphost.  The gotcha is that localhost refers to localhost
on the remote server, NOT localhost on your local client machine.

I use the sleep 32400 on purpose so that it will die after about 9 hours.  If
it dies while you're actually running xmfail, xfmail usually unhappily dies
right along with it.

In xfmail, I have two receive accounts, one imap pointing to 127.0.0.1 port
60143, and one pop pointing to 127.0.0.1 port 1234.  I also use two smtp
servers and have configured xfmail to deliver mail with my personal domain via
my personal mail server.  My office mail goes through the regular in-house
server.

Setting up access without a password is of course ill-advised and my office
mail server disallows this altogether.  Setting it up isn't difficult though. 
On your local client machine while logged in as your regular user id that you'll
be checking mail from, issue the command:

ssh-keygen -t rsa

This will generate ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub.  scp the id_rsa.pub
file to the server in your ~/.ssh directory there, creating the directory first
if it doesn't already exist.  Put the contents of the public key file in the
file ~/.ssh/authorized_keys2, again, creating it if it doesn't exist already.

This is all the setup that is required.  From your home directory on your
client machine, issue:

./xfmail.sh start

This will start the tunnels, prompting you for passwords if needed, and then
start xfmail.


