/[smeserver]/rpms/stunnel-tls/sme8/pop3-tls.README
ViewVC logotype

Annotation of /rpms/stunnel-tls/sme8/pop3-tls.README

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph


Revision 1.1 - (hide annotations) (download)
Tue Jun 12 21:18:31 2007 UTC (17 years, 4 months ago) by slords
Branch: MAIN
CVS Tags: stunnel-tls-3_22-4_el5_sme, HEAD
Import on branch sme8 of package stunnel-tls-3.22-4.el5.sme.src.rpm

1 slords 1.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    

admin@koozali.org
ViewVC Help
Powered by ViewVC 1.2.1 RSS 2.0 feed