[PATCH] qregex-starttls-2way-auth-20060423-mm

1 files changed, 103 insertions, 0 deletions

diff --git a/README.starttls b/README.starttls
new file mode 100644
index 0000000..0286632
--- /dev/null
+++ b/README.starttls
@@ -0,0 +1,103 @@
+Frederik Vermeulen <qmail-tls akrul inoa.net> 20060104
+http://inoa.net/qmail-tls/
+
+This patch implements RFC 3207 (was RFC 2487) in qmail. 
+This means you can get SSL or TLS encrypted and 
+authenticated SMTP between the MTAs and from MUA to MTA. 
+The code is considered experimental (but has worked for
+many since its first release on 1999-03-21).
+
+Usage: - install OpenSSL-0.9.8 http://www.openssl.org/
+         (any 0.9.6 to 0.9.8 version is presumed to work)
+       - apply patch to netqmail-1.05 http://qmail.org/netqmail
+         (should work on qmail-1.03 too).  The patches to 
+         qmail-remote.c and qmail-smtpd.c can be applied separately.
+       - provide a server certificate in /var/qmail/control/servercert.pem.
+         "make cert" makes a self-signed certificate.
+         "make cert-req" makes a certificate request.
+         Note: you can add the CA certificate and intermediate
+         certs to the end of servercert.pem.
+       - replace qmail-smtpd and/or qmail-remote binary
+       - verify operation (header information should show
+         something like
+         "Received [..] with (DHE-RSA-AES256-SHA encrypted) SMTP;")
+         If you don't have a server to test with, you can test
+         by sending mail to tag-ping@tbs-internet.com,
+         which will bounce your mail.
+
+Optional: - when DEBUG is defined, some extra TLS info will be logged
+          - qmail-remote will authenticate with the certificate in
+            /var/qmail/control/clientcert.pem. By preference this is
+            the same as servercert.pem, where nsCertType should be 
+            == server,client or be a generic certificate (no usage specified). 
+          - when a 512 bit RSA key is provided in /var/qmail/control/rsa512.pem,
+            this key will be used instead of (slow) on-the-fly generation by
+            qmail-smtpd. Idem for 512 and 1024 DH params in control/dh512.pem
+            and control/dh1024.pem. `make tmprsadh` does this.
+            Periodical replacement can be done by crontab:
+            01 01 * * * /var/qmail/bin/update_tmprsadh > /dev/null 2>&1
+          - server authentication:
+            qmail-remote requires authentication from servers for which
+            /var/qmail/control/tlshosts/host.dom.ain.pem exists.
+            The .pem file contains the validating CA certificates
+            (or self-signed server certificate).  CommonName has to match.
+            WARNING: this option may cause mail to be delayed, bounced,
+            doublebounced, and lost.
+            If /var/qmail/control/tlshosts/exhaustivelist is present,
+            the lists of hosts in /var/qmail/control/tlshosts is
+            an exhaustive list of hosts TLS is tried on.
+            If /var/qmail/control/notlshosts/host.dom.ain is present,
+            no TLS is tried on this host.
+          - client authentication:
+            when relay rules would reject an incoming mail, 
+            qmail-smtpd can allow the mail based on a presented cert.
+            Certs are verified against a CA list in 
+            /var/qmail/control/clientca.pem (eg. http://www.modssl.org/
+            source/cvs/exp/mod_ssl/pkg.mod_ssl/pkg.sslcfg/ca-bundle.crt)
+            and the cert email-address has to match a line in
+            /var/qmail/control/tlsclients. This email-address is logged
+            in the headers. CRLs can be provided through 
+            /var/qmail/control/clientcrl.pem.
+          - cipher selection:
+            qmail-remote: 
+              openssl cipher string (`man ciphers`) read from 
+              /var/qmail/control/tlsclientciphers
+            qmail-smtpd: 
+              openssl cipher string read from TLSCIPHERS environment variable
+              (can vary based on client IP address e.g.)
+              or if that is not available /var/qmail/control/tlsserverciphers
+          - smtps (deprecated SMTP over TLS via port 465):
+            qmail-remote: when connecting to port 465 
+            qmail-smtpd: when SMTPS environment variable is not empty
+
+Caveats: - do a `make clean` after patching
+         - binaries dynamically linked with current openssl versions need
+           recompilation when the shared openssl libs are upgraded.
+         - this patch could conflict with other patches (notably those
+           replacing \n with \r\n, which is a bad idea on encrypted links).
+         - some broken servers have a problem with TLSv1 compatibility.
+           Uncomment the line where we set the SSL_OP_NO_TLSv1 option.
+         - needs working /dev/urandom (or EGD for openssl versions >0.9.7)
+           for seeding random number generator.
+         - packagers should make sure that installing without a valid 
+           servercert is impossible
+         - when applied in combination with AUTH patch, AUTH patch
+           should be applied first and first part of this patch
+           will fail. This error can be ignored. Packagers should
+           cut the first 12 lines of this patch to make a happy
+           patch
+         - `make tmprsadh` is recommended (or should I say required), 
+           otherwise DH generation can be unpredictably slow
+         - some need "-I/usr/kerberos/include" to be added in conf-cc
+
+Copyright: GPL
+           Links with OpenSSL
+           Inspiration and code from examples in SSLeay (E. Young
+           <eay@cryptsoft.com> and T. Hudson <tjh@cryptsoft.com>),
+           stunnel (M. Trojnara <mtrojnar@ddc.daewoo.com.pl>),
+           Postfix/TLS (L. Jaenicke <Lutz.Jaenicke@aet.tu-cottbus.de>),
+           modssl (R. Engelschall <rse@engelschall.com>),
+           openssl examples of E. Rescorla <ekr@rtfm.com>.
+
+Bug reports: mailto:<qmail-tls akrul inoa.net>
+