Make it easier to get SMTP authentication and TLS/SSL support working

by adding some example configuration directives to the default
configuration file. A little bit of work is required to uncomment the
directives and define how usernames and passwords are checked, but
there is now a framework to start from.

3 files changed, 173 insertions, 15 deletions

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 7a15e116f..896287082 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -1,4 +1,4 @@
-. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.5 2006/05/31 19:34:57 fanf2 Exp $
+. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.6 2006/06/07 17:42:27 fanf2 Exp $
 .
 . /////////////////////////////////////////////////////////////////////////////
 . This is the primary source of the Exim Manual. It is an xfpt document that is
@@ -4958,7 +4958,7 @@ mentioned at all in the default configuration.
 
 
 
-.section "Main configuration settings"
+.section "Main configuration settings" "SECTdefconfmain"
 The main (global) configuration option settings must always come first in the
 file. The first thing you'll see in the file, after some initial comments, is
 the line
@@ -5034,6 +5034,36 @@ content-scanning extension. The first specifies the interface to the virus
 scanner, and the second specifies the interface to SpamAssassin. Further
 details are given in chapter &<<CHAPexiscan>>&.
 
+Three more commented-out option settings follow:
+.code
+# tls_advertise_hosts = *
+# tls_certificate = /etc/ssl/exim.crt
+# tls_privatekey = /etc/ssl/exim.pem
+.endd
+These are example settings that can be used when Exim is compiled with
+support for TLS (aka SSL) as described in &<<SECTinctlsssl>>&. The
+first one specifies the list of clients that are allowed to use TLS
+when connecting to this server; in this case the wildcard means all
+clients. The other options specify where Exim should find its TLS
+certificate and private key, which together prove the server's
+identity to any clients that connect. More details are given in
+&<<CHAPTLS>>&.
+
+Another two commented-out option settings follow:
+.code
+# daemon_smtp_ports = 25 : 465 : 587
+# tls_on_connect_ports = 465
+.endd
+These options provide better support for roaming users who wish to use
+this server for message submission. They are not much use unless you
+have turned on TLS (as described in the previous paragraph) and
+authentication (about which more in &<<SECTdefconfauth>>&). The usual
+SMTP port 25 is often blocked on end-user networks, so RFC 4409
+specifies that message submission should use port 587 instead. However
+some software (notably Microsoft Outlook) cannot be configured to use
+port 587 correctly, so these settings also enable the non-standard
+&"smtps"& port 465.
+
 Two more commented-out options settings follow:
 .code
 # qualify_domain =
@@ -5275,9 +5305,9 @@ accept  authenticated = *
 This statement accepts the address if the client host has authenticated itself.
 Submission mode is again specified, on the grounds that such messages are most
 likely to come from MUAs. The default configuration does not define any
-authenticators, which means that no client can in fact authenticate. You will
-need to add authenticator definitions if you want to make use of this ACL
-statement.
+authenticators, though it does include some nearly complete commented-out
+examples described in &<<SECTdefconfauth>>&. This means that no client can in
+fact authenticate until you complete the authenticator definitions.
 .code
 # deny    message     = rejected because $sender_host_address \
 #                       is in a black list at $dnslist_domain\n\
@@ -5624,14 +5654,52 @@ rewriting rules in the default configuration file.
 
 
 
-.section "Authenticators configuration"
+.section "Authenticators configuration" "SECTdefconfauth"
 .cindex "AUTH" "configuration"
 The authenticators section of the configuration, introduced by
 .code
 begin authenticators
 .endd
-defines mechanisms for the use of the SMTP AUTH command. No authenticators
-are specified in the default configuration file.
+defines mechanisms for the use of the SMTP AUTH command. The default
+configuration file contains two commented-out example authenticators
+which support plaintext username/password authentication using the
+standard PLAIN mechanism and the traditional but non-standard LOGIN
+mechanism, with Exim acting as the server. PLAIN and LOGIN are enough
+to support most MUA software.
+
+The example PLAIN authenticator looks like this:
+.code
+#PLAIN:
+#  driver                     = plaintext
+#  server_set_id              = $auth2
+#  server_prompts             = :
+#  server_condition           = Authentication is not yet configured
+#  server_advertise_condition = ${if def:tls_cipher }
+.endd
+And the example LOGIN authenticator looks like this:
+.code
+#LOGIN:
+#  driver                     = plaintext
+#  server_set_id              = $auth1
+#  server_prompts             = <| Username: | Password:
+#  server_condition           = Authentication is not yet configured
+#  server_advertise_condition = ${if def:tls_cipher }
+.endd
+
+The &%server_set_id%& option makes Exim remember the authenticated username
+in &$authenticated_id$&, which can be used later in ACLs or routers. The
+&%server_prompts%& option configures the &(plaintext)& authenticator so
+that it implements the details of the specific authentication mechanism,
+i.e. PLAIN or LOGIN. The &%server_advertise_condition%& setting controls
+when Exim offers authentication to clients; in the examples, this is only
+when TLS or SSL has been started, so to enable the authenticators you also
+need to add support for TLS as described in &<<SECTdefconfmain>>&.
+
+The &%server_condition%& setting defines how to verify that the username and
+password are correct. In the examples it just produces an error message.
+To make the authenticators work, you can use a string expansion
+expression like one of the examples in &<<CHAPplaintext>>&.
+
 .ecindex IIDconfiwal
 
 
@@ -23680,10 +23748,21 @@ connection is closed. In these special cases, the QUIT ACL does not run.
 
 .section "Finding an ACL to use"
 .cindex "&ACL;" "finding which to use"
-The value of an &%acl_smtp_%&&'xxx'& option is expanded before use, so you can
-use different ACLs in different circumstances. The resulting string does not
-have to be the name of an ACL in the configuration file; there are other
-possibilities. Having expanded the string, Exim searches for an ACL as follows:
+The value of an &%acl_smtp_%&&'xxx'& option is expanded before use, so
+you can use different ACLs in different circumstances. For example,
+.code
+acl_smtp_rcpt = ${if ={25}{$interface_port} \
+                     {acl_check_rcpt} {acl_check_rcpt_submit} }
+.endd
+In the default configuration file there are some example settings for
+providing an RFC 4409 message submission service on port 587 and a
+non-standard &"smtps"& service on port 465. You can use a string
+expansion like this to choose an ACL for MUAs on these ports which is
+more appropriate for this purpose than the default ACL on port 25.
+
+The expanded string does not have to be the name of an ACL in the
+configuration file; there are other possibilities. Having expanded the
+string, Exim searches for an ACL as follows:
 
 .ilist
 If the string begins with a slash, Exim uses it as a file name, and reads its
diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog
index 6013ceb86..b86bd4ba5 100644
--- a/doc/doc-txt/ChangeLog
+++ b/doc/doc-txt/ChangeLog
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-txt/ChangeLog,v 1.355 2006/06/07 15:06:25 fanf2 Exp $
+$Cambridge: exim/doc/doc-txt/ChangeLog,v 1.356 2006/06/07 17:42:27 fanf2 Exp $
 
 Change log file for Exim from version 4.21
 -------------------------------------------
@@ -29,6 +29,12 @@ TF/03 Note in the spec that $authenticated_id is not set for local
 TF/04 The ratelimit per_rcpt option now works correctly in acl_not_smtp.
       Thanks to Dean Brooks <dean@iglou.com> for the patch.
 
+TF/05 Make it easier to get SMTP authentication and TLS/SSL support working
+      by adding some example configuration directives to the default
+      configuration file. A little bit of work is required to uncomment the
+      directives and define how usernames and passwords are checked, but
+      there is now a framework to start from.
+
 
 Exim version 4.62
 -----------------
diff --git a/src/src/configure.default b/src/src/configure.default
index e581288c6..cfc5a4985 100644
--- a/src/src/configure.default
+++ b/src/src/configure.default
@@ -1,4 +1,4 @@
-# $Cambridge: exim/src/src/configure.default,v 1.7 2006/02/20 16:31:49 ph10 Exp $
+# $Cambridge: exim/src/src/configure.default,v 1.8 2006/06/07 17:42:27 fanf2 Exp $
 
 ######################################################################
 #                  Runtime configuration file for Exim               #
@@ -130,6 +130,40 @@ acl_smtp_data = acl_check_data
 # spamd_address = 127.0.0.1 783
 
 
+# If Exim is compiled with support for TLS, you may want to enable the
+# following options so that Exim allows clients to make encrypted
+# connections. In the authenticators section below, there are template
+# configurations for plaintext username/password authentication. This kind
+# of authentication is only safe when used within a TLS connection, so the
+# authenticators will only work if the following TLS settings are turned on
+# as well.
+
+# Allow any client to use TLS.
+
+# tls_advertise_hosts = *
+
+# Specify the location of the Exim server's TLS certificate and private key.
+# The private key must not be encrypted (password protected). You can put
+# the certificate and private key in the same file, in which case you only
+# need the first setting, or in separate files, in which case you need both
+# options.
+
+# tls_certificate = /etc/ssl/exim.crt
+# tls_privatekey = /etc/ssl/exim.pem
+
+# In order to support roaming users who wish to send email from anywhere,
+# you may want to make Exim listen on other ports as well as port 25, in
+# case these users need to send email from a network that blocks port 25.
+# The standard port for this purpose is port 587, the "message submission"
+# port. See RFC 4409 for details. Microsoft MUAs cannot be configured to
+# talk the message submission protocol correctly, so if you need to support
+# them you should also allow TLS-on-connect on the traditional but
+# non-standard port 465.
+
+# daemon_smtp_ports = 25 : 465 : 587
+# tls_on_connect_ports = 465
+
+
 # Specify the domain you want to be added to all unqualified addresses
 # here. An unqualified address is one that does not contain an "@" character
 # followed by a domain. For example, "caesar@rome.example" is a fully qualified
@@ -662,10 +696,49 @@ begin rewrite
 #                   AUTHENTICATION CONFIGURATION                     #
 ######################################################################
 
-# There are no authenticator specifications in this default configuration file.
+# The following authenticators support plaintext username/password
+# authentication using the standard PLAIN mechanism and the traditional
+# but non-standard LOGIN mechanism, with Exim acting as the server.
+# PLAIN and LOGIN are enough to support most MUA software.
+#
+# These authenticators are not complete: you need to change the
+# server_condition settings to specify how passwords are verified.
+# They are set up to offer authentication to the client only if the
+# connection is encrypted with TLS, so you also need to add support
+# for TLS. See the global configuration options section at the start
+# of this file for more about TLS.
+#
+# The default RCPT ACL checks for successful authentication, and will accept
+# messages from authenticated users from anywhere on the Internet.
 
 begin authenticators
 
+# PLAIN authentication has no server prompts. The client sends its
+# credentials in one lump, containing an authorization ID (which we do not
+# use), an authentication ID, and a password. The latter two appear as
+# $auth2 and $auth3 in the configuration and should be checked against a
+# valid username and password. In a real configuration you would typically
+# use $auth2 as a lookup key, and compare $auth3 against the result of the
+# lookup, perhaps using the crypteq{}{} condition.
+
+#PLAIN:
+#  driver                     = plaintext
+#  server_set_id              = $auth2
+#  server_prompts             = :
+#  server_condition           = Authentication is not yet configured
+#  server_advertise_condition = ${if def:tls_cipher }
+
+# LOGIN authentication has traditional prompts and responses. There is no
+# authorization ID in this mechanism, so unlike PLAIN the username and
+# password are $auth1 and $auth2. Apart from that you can use the same
+# server_condition setting for both authenticators.
+
+#LOGIN:
+#  driver                     = plaintext
+#  server_set_id              = $auth1
+#  server_prompts             = <| Username: | Password:
+#  server_condition           = Authentication is not yet configured
+#  server_advertise_condition = ${if def:tls_cipher }
 
 
 ######################################################################