# HG changeset patch
# User meillo@marmaro.de
# Date 1279876700 -7200
# Node ID 9814e75de61c93d48fbe603e40ee04a38b2bdf80
# Parent  8cddc65765bdb0a2841b89f793ba6c0d17b6f311
updated docs to STARTTLS wrappers

diff -r 8cddc65765bd -r 9814e75de61c docs/simple-relay-setup
--- a/docs/simple-relay-setup	Fri Jul 23 10:57:53 2010 +0200
+++ b/docs/simple-relay-setup	Fri Jul 23 11:18:20 2010 +0200
@@ -38,8 +38,12 @@
 
     # where to relay to; the address and port of the smart host
     mail_host = "mail.gmx.net:25"
-    # use the wrapper to enable encryption
-    #wrapper = "openssl s_client -quiet -connect mail.gmx.net:465 2>/dev/null"
+    # use a wrapper to enable encryption
+    # for STARTTLS on port 25:
+    #instant_helo=true
+    #wrapper="/usr/bin/openssl s_client -quiet -starttls smtp -connect mail.gmx.net:25 2>/dev/null"
+    # for SMTP over SSL on port 465:
+    #wrapper = "/usr/bin/openssl s_client -quiet -connect mail.gmx.net:465 2>/dev/null"
     
     do_correct_helo = true
     
diff -r 8cddc65765bd -r 9814e75de61c examples/openssl.route
--- a/examples/openssl.route	Fri Jul 23 10:57:53 2010 +0200
+++ b/examples/openssl.route	Fri Jul 23 11:18:20 2010 +0200
@@ -6,9 +6,15 @@
 
 # encryption is done by communicating through openssl
 
-wrapper="/usr/bin/openssl s_client -quiet -connect mail.gmx.net:465 2>/dev/null"
-# you may want to tell openssl where the certificates are stored
-#wrapper="/usr/bin/openssl s_client -quiet -CApath /etc/ssl -connect mail.gmx.net:465 2>/dev/null"
+# Today usually STARTTLS (RFC-3207) is used:
+# don't forget the instant_helo, otherwise it won't work, because the wrapper eats the 220 greeting
+instant_helo=true
+wrapper="/usr/bin/openssl s_client -quiet -starttls smtp -connect mail.gmx.net:25 2>/dev/null"
+
+# The old way is SMTP over SSL; the IETF had marked it obsolete:
+# don't use instant_helo here
+#wrapper="/usr/bin/openssl s_client -quiet -connect mail.gmx.net:465 2>/dev/null"
+
 
 # which addresses are allowed through this route?
 allowed_return_paths = "*@gmx.de;*@gmx.net"
diff -r 8cddc65765bd -r 9814e75de61c man/masqmail.route.5
--- a/man/masqmail.route.5	Fri Jul 23 10:57:53 2010 +0200
+++ b/man/masqmail.route.5	Fri Jul 23 11:18:20 2010 +0200
@@ -80,7 +80,7 @@
 after opening the connection.
 Instead it says EHLO right away (ESMTP is assumed).
 Use this option with wrappers that eat the 220 greeting of the SMTP server.
-Common examples are STARTTLS wrappers, like `openssl -starttls smtp ...'.
+Common examples are STARTTLS wrappers, like `openssl s_client -starttls smtp ...'.
 
 If this option is set and a 220 greeting is received though,
 everything should still work.
@@ -188,8 +188,9 @@
 the local parts (the keys) are separated from the addresses (the values) by colons (`:').
 
 Example:
-
+.nf
 map_h_from_addresses = "john: John Smith <jsmith@mail.academic.edu>; charlie: Charlie Miller <cmiller@mx.commercial.com>"
+.fi
 
 You can use patterns, eg. * as keys.
 
@@ -214,8 +215,9 @@
 The most important difference is that RFC 821 addresses have no full name.
 
 Example:
-
+.nf
 map_return_path_addresses = "john: <jsmith@mail.academic.edu>; charlie: <cmiller@mx.commercial.com>"
+.fi
 
 You can use patterns, eg. * as keys.
 
@@ -275,17 +277,24 @@
 \fIcommand\fR will be called and all traffic will be piped to its stdin and from its stdout.
 Purpose is to tunnel ip traffic, eg. for ssl.
 
-Example for ssl tunneling:
+Example for SMTP over SSL tunneling:
+.nf
+wrapper="/usr/bin/openssl s_client \-quiet \-connect mail.gmx.net:465 2>/dev/null"
+.fi
 
-wrapper="/usr/bin/openssl s_client \-quiet \-connect mail.gmx.net:465 2>/dev/null"
+SMTP over SSL is supported since masqmail-0.1.8.
+It is marked obsolete by the IETF but is still in use.
 
-Note: The above line works with masqmail,
-but listening on Port 465 for SSL-encrypted connections is deprecated.
-The modern way is STARTTLS (RFC-3207).
-This could be covered by the following command.
-Unfortunately, masqmail doesn't support that yet (as of 0.2.25).
 
+Example for encryption with STARTTLS (RFC-3207):
+.nf
+# don't forget the instant_helo, otherwise it won't work
+instant_helo=true
 wrapper="/usr/bin/openssl s_client \-quiet \-starttls smtp \-connect mail.gmx.net:25 2>/dev/null"
+.fi
+
+This is supported since masqmail-0.2.28.
+STARTTLS supersedes SMTP over SSL.
 
 Note for openssl:
 Ensure that stderr is redirected.