stunnel-tls/sme7/pop3-tls.README

********************
*** INTRODUCTION ***
********************

STLS is the standard (RFC 2595) way of doing POP3 encrypted with
SSL/TLS.  Although it does not provide end-to-end encryption of email
messages, it can be useful to protect POP passwords, and to protect POP messages across the "last mile" of mail delivery.

qmail-pop3d doesn't have native support for STLS.  Many people run
qmail for it's extremely good security record, and are reluctant to
have the security of their mail system depend on the many thousands of
lines of code in openssl.  One way to avoid this is to run a proxy
which can handle the encryption and the STLS command itself, and
then have it hand off to the standard qmail-pop3d.  Even better is if
the proxy can run in an environment secured by chroot(), setuid(), and
setgid().

That's the approach that this document describes, with stunnel acting
as the proxy.  Basic POP3/STLS proxy support is already included
in stunnel, and that support has been extended to do a plaintext proxy
of the POP3 session if STLS isn't used.  stunnel runs chrooted in
its own directory, as a special user and group.  This means that even
a grievous security error in stunnel or openssl wouldn't allow
significant access to your system, or even allow interfering with
mail.


********************
*** INSTRUCTIONS ***
********************

WARNING: These are not for the faint-hearted.  They are confusing and
may not work for you.  This is still experimental; if you get stuck,
email me at <sgifford@suspectclass.com>.

1. Download stunnel-3.22.  Apply the patch "stunnel3.22-sg2.patch",
   available from:

       http://www.suspectclass.com/~sgifford/stunnel-tlsproxy/stunnel3.22-sg2.patch 

   Compile and install it somewhere.  This patch improves the proxy
   support, adds options to tell stunnel to communicate via an already
   opened file descriptor, adds chroot() support, and improves
   setuid/setgid support; see:

       http://www.suspectclass.com/~sgifford/qmail-smtp-tls-proxy/stunnel3.22-sg2.README

   for a full description of the patch.

2. Compile and install "makesock.c".  

3. Create your service directory for pop3-tls

4. Set up a log directory for pop3-tls.

5. Create a user called "stunnel" with a primary group of "stunnel".

6. Create a directory in your service directory called "ssl".

   6a. Copy in your certificate as "stunnel.pem"

   6b. Copy in your SSL configuration as openssl.cnf

   6c. Create a seed file with "dd if=/dev/random of=seed count=10k"
       or something.

   6d/1. Some copies of OpenSSL will require you to create a fake
         'usr/share/ssl' directory, to placate openssl in chroot.
         Something like:

             mkdir -p usr/share/ssl

         .  If your ssl expects to find its configuration elsewhere,
         make that directory instead.

   6d/2. If your copy of OpenSSL requires it, make a symlink to
         openssl.cnf from the fake config dir.  Something like:
 
             ln -s ../../../openssl.cnf usr/share/ssl/

         should do the trick, if your openssl expects its config file in
         /usr/share/ssl normally.

   6e. Set group-ownership of the ssl directory to "stunnel" (leaving
       user-ownership at "root") and permissions to "owner read-write,
       group read, other none" on everything in the ssl directory:

           chgrp -R stunnel ssl
           chmod -R u=rwX,g=rX,o= ssl

7. Install the run file "pop3-tls-run" as "run" in your service
   directory.  Make sure it's executable.  If you've installed the
   modified stunnel somewhere other than /usr/local/sbin, add that to
   the PATH near the top.

8. Run the "run" file in the service directory, and find and fix any
   errors.

9. Active the service, perhaps by symlinking it into /service.


*******************
*** EXPLANATION ***
*******************

Here's what the run script does.  It expects everything it runs to be
in your PATH.

First, it gathers up some information from control files and from the
system user and group database, and gets some hardcoded configuration
information.

softlimit limits the memory usage for each process to 5 MB.

tcpserver listens on the POP3 port.  We continue running as root from
here (so we can do chroot() and set[ug]id() later, and also run
checkpassword), and when we get a connection we run...

...makesock.  This is a small C program that creates a socket with
socketpair(), and provides one end of that socket on file descriptor 3
to the first program it's asked to run, and the other end on standard
input and output to the second program it's asked to run.  The first
and second programs are separated by the command line option
"-makesock_connect_to".

The first program, the STLS proxy, is stunnel.  Debugging is turned
on, since this is still experimental.  "-/ ssl" (an option added by my
patch) asks it to chroot to the "ssl" directory.  "-s $SSLUID" asks it
to change to the stunnel user.  "-g $SSLGID" asks it to change to the
stunnel group.  "-i" (an option added by my patch) asks it to switch
users immediately, instead of after binding to the local port for
listening (which we don't ask stunnel to do, since tcpserver has done
it for us).  "-R seed" tells it to get the seed for the random number
generator from the file "seed".  "-p stunnel.pem" tells it to use the
certificate in "stunnel.pem".  "-n" pop3-" tells it to act as a POP3
proxy, and to act as a plaintext proxy if TLS isn't negotiated.  "-f"
asks it to stay in the foreground and write its errors to stderr,
perfect for running under supervise!  "-F 3" (an option added by my
patch) asks it to connect to file descriptor 3 (set up by makesock) as
the plaintext end of the proxy.

The second program is the POP3 server.  As in a normal qmail POP3
setup, qmail-popup runs checkpasswords runs qmail-pop3d.

*************
*** NOTES ***
*************

It is also possible to run this proxy as a simple TCP proxy, as long
as you don't care about what IP addresses your POP3 users are really
coming from.


************
*** BUGS ***
************

  * STLS is only supported if no other commands besides CAPA are sent
    before it.

  * makesock.c is a single-purpose ugly hack.  It should take more
    command-line options, to make it a flexible tool.

1	********************
2	* INTRODUCTION *
3	********************
4
5	STLS is the standard (RFC 2595) way of doing POP3 encrypted with
6	SSL/TLS. Although it does not provide end-to-end encryption of email
7	messages, it can be useful to protect POP passwords, and to protect POP messages across the "last mile" of mail delivery.
8
9	qmail-pop3d doesn't have native support for STLS. Many people run
10	qmail for it's extremely good security record, and are reluctant to
11	have the security of their mail system depend on the many thousands of
12	lines of code in openssl. One way to avoid this is to run a proxy
13	which can handle the encryption and the STLS command itself, and
14	then have it hand off to the standard qmail-pop3d. Even better is if
15	the proxy can run in an environment secured by chroot(), setuid(), and
16	setgid().
17
18	That's the approach that this document describes, with stunnel acting
19	as the proxy. Basic POP3/STLS proxy support is already included
20	in stunnel, and that support has been extended to do a plaintext proxy
21	of the POP3 session if STLS isn't used. stunnel runs chrooted in
22	its own directory, as a special user and group. This means that even
23	a grievous security error in stunnel or openssl wouldn't allow
24	significant access to your system, or even allow interfering with
25	mail.
26
27
28	********************
29	* INSTRUCTIONS *
30	********************
31
32	WARNING: These are not for the faint-hearted. They are confusing and
33	may not work for you. This is still experimental; if you get stuck,
34	email me at <sgifford@suspectclass.com>.
35
36	1. Download stunnel-3.22. Apply the patch "stunnel3.22-sg2.patch",
37	available from:
38
39	http://www.suspectclass.com/~sgifford/stunnel-tlsproxy/stunnel3.22-sg2.patch
40
41	Compile and install it somewhere. This patch improves the proxy
42	support, adds options to tell stunnel to communicate via an already
43	opened file descriptor, adds chroot() support, and improves
44	setuid/setgid support; see:
45
46	http://www.suspectclass.com/~sgifford/qmail-smtp-tls-proxy/stunnel3.22-sg2.README
47
48	for a full description of the patch.
49
50	2. Compile and install "makesock.c".
51
52	3. Create your service directory for pop3-tls
53
54	4. Set up a log directory for pop3-tls.
55
56	5. Create a user called "stunnel" with a primary group of "stunnel".
57
58	6. Create a directory in your service directory called "ssl".
59
60	6a. Copy in your certificate as "stunnel.pem"
61
62	6b. Copy in your SSL configuration as openssl.cnf
63
64	6c. Create a seed file with "dd if=/dev/random of=seed count=10k"
65	or something.
66
67	6d/1. Some copies of OpenSSL will require you to create a fake
68	'usr/share/ssl' directory, to placate openssl in chroot.
69	Something like:
70
71	mkdir -p usr/share/ssl
72
73	. If your ssl expects to find its configuration elsewhere,
74	make that directory instead.
75
76	6d/2. If your copy of OpenSSL requires it, make a symlink to
77	openssl.cnf from the fake config dir. Something like:
78
79	ln -s ../../../openssl.cnf usr/share/ssl/
80
81	should do the trick, if your openssl expects its config file in
82	/usr/share/ssl normally.
83
84	6e. Set group-ownership of the ssl directory to "stunnel" (leaving
85	user-ownership at "root") and permissions to "owner read-write,
86	group read, other none" on everything in the ssl directory:
87
88	chgrp -R stunnel ssl
89	chmod -R u=rwX,g=rX,o= ssl
90
91	7. Install the run file "pop3-tls-run" as "run" in your service
92	directory. Make sure it's executable. If you've installed the
93	modified stunnel somewhere other than /usr/local/sbin, add that to
94	the PATH near the top.
95
96	8. Run the "run" file in the service directory, and find and fix any
97	errors.
98
99	9. Active the service, perhaps by symlinking it into /service.
100
101
102
103	*******************
104	* EXPLANATION *
105	*******************
106
107	Here's what the run script does. It expects everything it runs to be
108	in your PATH.
109
110	First, it gathers up some information from control files and from the
111	system user and group database, and gets some hardcoded configuration
112	information.
113
114	softlimit limits the memory usage for each process to 5 MB.
115
116	tcpserver listens on the POP3 port. We continue running as root from
117	here (so we can do chroot() and set[ug]id() later, and also run
118	checkpassword), and when we get a connection we run...
119
120	...makesock. This is a small C program that creates a socket with
121	socketpair(), and provides one end of that socket on file descriptor 3
122	to the first program it's asked to run, and the other end on standard
123	input and output to the second program it's asked to run. The first
124	and second programs are separated by the command line option
125	"-makesock_connect_to".
126
127	The first program, the STLS proxy, is stunnel. Debugging is turned
128	on, since this is still experimental. "-/ ssl" (an option added by my
129	patch) asks it to chroot to the "ssl" directory. "-s $SSLUID" asks it
130	to change to the stunnel user. "-g $SSLGID" asks it to change to the
131	stunnel group. "-i" (an option added by my patch) asks it to switch
132	users immediately, instead of after binding to the local port for
133	listening (which we don't ask stunnel to do, since tcpserver has done
134	it for us). "-R seed" tells it to get the seed for the random number
135	generator from the file "seed". "-p stunnel.pem" tells it to use the
136	certificate in "stunnel.pem". "-n" pop3-" tells it to act as a POP3
137	proxy, and to act as a plaintext proxy if TLS isn't negotiated. "-f"
138	asks it to stay in the foreground and write its errors to stderr,
139	perfect for running under supervise! "-F 3" (an option added by my
140	patch) asks it to connect to file descriptor 3 (set up by makesock) as
141	the plaintext end of the proxy.
142
143	The second program is the POP3 server. As in a normal qmail POP3
144	setup, qmail-popup runs checkpasswords runs qmail-pop3d.
145
146	*************
147	* NOTES *
148	*************
149
150	It is also possible to run this proxy as a simple TCP proxy, as long
151	as you don't care about what IP addresses your POP3 users are really
152	coming from.
153
154
155	************
156	* BUGS *
157	************
158
159	* STLS is only supported if no other commands besides CAPA are sent
160	before it.
161
162	* makesock.c is a single-purpose ugly hack. It should take more
163	command-line options, to make it a flexible tool.
164