Guard LDAP TLS usage against Solaris LDAP variant.
[users/heiko/exim.git] / doc / doc-txt / experimental-spec.txt
index 5dd6832b1f6382cc71aa32f4f0736e99d5a161e8..d58f3961b46040270babf67781ff6aca758161e9 100644 (file)
@@ -2,14 +2,42 @@ From time to time, experimental features may be added to Exim.
 While a feature  is experimental, there  will be a  build-time
 option whose name starts  "EXPERIMENTAL_" that must be  set in
 order to include the  feature. This file contains  information
-about experimenatal  features, all  of which  are unstable and
-liable to incompatibile change.
+about experimental  features, all  of which  are unstable and
+liable to incompatible change.
+
+
+PRDR support
+--------------------------------------------------------------
+
+Per-Recipient Data Reponse is an SMTP extension proposed by Eric Hall
+in a (now-expired) IETF draft from 2007.  It's not hit mainstream
+use, but has apparently been implemented in the META1 MTA.
+
+There is mention at http://mail.aegee.org/intern/sendmail.html
+of a patch to sendmail "to make it PRDR capable".
+
+ ref: http://www.eric-a-hall.com/specs/draft-hall-prdr-00.txt
+
+If Exim is built with EXPERIMENTAL_PRDR there is a new config
+boolean "prdr_enable" which controls whether PRDR is advertised
+as part of an EHLO response, a new "acl_data_smtp_prdr" ACL
+(called for each recipient, after data arrives but before the
+data ACL), and a new smtp transport option "hosts_try_prdr".
+
+PRDR may be used to support per-user content filtering.  Without it
+one must defer any recipient after the first that has a different
+content-filter configuration.  With PRDR, the RCPT-time check
+for this can be disabled when the MAIL-time $smtp_command included
+"PRDR".  Any required difference in behaviour of the main DATA-time
+ACL should however depend on the PRDR-time ACL having run, as Exim
+will avoid doing so in some situations (eg.  single-recipient mails).
+
 
 
 OCSP Stapling support
 --------------------------------------------------------------
 
-X509 PKI certificates expire and can be revoked; to handle this, the
+X.509 PKI certificates expire and can be revoked; to handle this, the
 clients need some way to determine if a particular certificate, from a
 particular Certificate Authority (CA), is still valid.  There are three
 main ways to do so.
@@ -41,7 +69,7 @@ starts retrying to fetch an OCSP proof some time before its current
 proof expires.  The downside is that it requires server support.
 
 If Exim is built with EXPERIMENTAL_OCSP and it was built with OpenSSL,
-then it gains one new option: "tls_ocsp_file".
+then it gains a new global option: "tls_ocsp_file".
 
 The file specified therein is expected to be in DER format, and contain
 an OCSP proof.  Exim will serve it as part of the TLS handshake.  This
@@ -58,10 +86,15 @@ next connection.
 Exim will check for a valid next update timestamp in the OCSP proof;
 if not present, or if the proof has expired, it will be ignored.
 
+Also, given EXPERIMENTAL_OCSP and OpenSSL, the smtp transport gains
+a "hosts_require_ocsp" option; a host-list for which an OCSP Stapling
+is requested and required for the connection to proceed.  The host(s)
+should also be in "hosts_require_tls", and "tls_verify_certificates"
+configured for the transport.
+
 At this point in time, we're gathering feedback on use, to determine if
 it's worth adding complexity to the Exim daemon to periodically re-fetch
-OCSP files and somehow handling multiple files.  There is no client support
-for OCSP in Exim, this is feature expected to be used by mail clients.
+OCSP files and somehow handling multiple files.
 
 
 
@@ -380,7 +413,7 @@ their default locations.
 
 You can now run SPF checks in incoming SMTP by using the "spf"
 ACL condition  in either  the MAIL,  RCPT or  DATA ACLs.  When
-using it in the RCPT ACL, you can make the checks dependend on
+using it in the RCPT ACL, you can make the checks dependent on
 the RCPT  address (or  domain), so  you can  check SPF records
 only  for   certain  target   domains.  This   gives  you  the
 possibility  to opt-out  certain customers  that do  not want
@@ -491,7 +524,7 @@ reject message.
 When the spf_guess condition has run, it sets up the same expansion
 variables as when spf condition is run, described above.
 
-Additionally, since Best-guess is not standarized, you may redefine
+Additionally, since Best-guess is not standardized, you may redefine
 what "Best-guess" means to you by redefining spf_guess variable in
 global config.  For example, the following:
 
@@ -546,7 +579,7 @@ In the DATA ACL you can use the new condition
 
 After that "$dcc_header" contains the X-DCC-Header.
 
-Returnvalues are:
+Return values are:
   fail    for overall "R", "G" from dccifd
   defer   for overall "T" from dccifd
   accept  for overall "A", "S" from dccifd
@@ -570,10 +603,232 @@ through to eg. SpamAssassin.
 If you want to pass even more headers in the middle of the
 DATA stage you can set
   $acl_m_dcc_add_header
-to tell the DCC routines add more information; eg, you might set
+to tell the DCC routines to add more information; eg, you might set
 this to some results from ClamAV.  Be careful.  Header syntax is
 not checked and is added "as is".
 
+In case you've troubles with sites sending the same queue items from several
+hosts and fail to get through greylisting you can use
+$acl_m_dcc_override_client_ip
+
+Setting $acl_m_dcc_override_client_ip to an IP address overrides the default
+of $sender_host_address. eg. use the following ACL in DATA stage:
+
+  warn    set acl_m_dcc_override_client_ip = \
+    ${lookup{$sender_helo_name}nwildlsearch{/etc/mail/multipleip_sites}{$value}{}}
+          condition = ${if def:acl_m_dcc_override_client_ip}
+          log_message = dbg: acl_m_dcc_override_client_ip set to \
+                        $acl_m_dcc_override_client_ip
+
+Then set something like
+# cat /etc/mail/multipleip_sites
+mout-xforward.gmx.net           82.165.159.12
+mout.gmx.net                    212.227.15.16
+
+Use a reasonable IP. eg. one the sending cluster acutally uses.
+
+DMARC Support
+--------------------------------------------------------------
+
+DMARC combines feedback from SPF, DKIM, and header From: in order
+to attempt to provide better indicators of the authenticity of an
+email.  This document does not explain the fundamentals, you
+should read and understand how it works by visiting the website at
+http://www.dmarc.org/.
+
+DMARC support is added via the libopendmarc library.  Visit:
+
+  http://sourceforge.net/projects/opendmarc/
+
+to obtain a copy, or find it in your favorite rpm package
+repository.  If building from source, this description assumes
+that headers will be in /usr/local/include, and that the libraries
+are in /usr/local/lib.
+
+1. To compile Exim with DMARC support, you must first enable SPF.
+Please read the above section on enabling the EXPERIMENTAL_SPF
+feature.  You must also have DKIM support, so you cannot set the
+DISABLE_DKIM feature.  Once both of those conditions have been met
+you can enable DMARC in Local/Makefile:
+
+EXPERIMENTAL_DMARC=yes
+LDFLAGS += -lopendmarc
+# CFLAGS += -I/usr/local/include
+# LDFLAGS += -L/usr/local/lib
+
+The first line sets the feature to include the correct code, and
+the second line says to link the libopendmarc libraries into the
+exim binary.  The commented out lines should be uncommented if you
+built opendmarc from source and installed in the default location.
+Adjust the paths if you installed them elsewhere, but you do not
+need to uncomment them if an rpm (or you) installed them in the
+package controlled locations (/usr/include and /usr/lib).
+
+
+2. Use the following global settings to configure DMARC:
+
+Required:
+dmarc_tld_file      Defines the location of a text file of valid
+                    top level domains the opendmarc library uses
+                    during domain parsing. Maintained by Mozilla,
+                    the most current version can be downloaded
+                    from a link at http://publicsuffix.org/list/.
+
+Optional:
+dmarc_history_file  Defines the location of a file to log results
+                    of dmarc verification on inbound emails. The
+                    contents are importable by the opendmarc tools
+                    which will manage the data, send out DMARC
+                    reports, and expire the data. Make sure the
+                    directory of this file is writable by the user
+                    exim runs as.
+
+dmarc_forensic_sender The email address to use when sending a
+                    forensic report detailing alignment failures
+                    if a sender domain's dmarc record specifies it
+                    and you have configured Exim to send them.
+                    Default: do-not-reply@$default_hostname
+
+
+3. By default, the DMARC processing will run for any remote,
+non-authenticated user.  It makes sense to only verify DMARC
+status of messages coming from remote, untrusted sources.  You can
+use standard conditions such as hosts, senders, etc, to decide that
+DMARC verification should *not* be performed for them and disable
+DMARC with a control setting:
+
+  control = dmarc_verify_disable
+
+A DMARC record can also specify a "forensic address", which gives
+exim an email address to submit reports about failed alignment.
+Exim does not do this by default because in certain conditions it
+results in unintended information leakage (what lists a user might
+be subscribed to, etc).  You must configure exim to submit forensic
+reports to the owner of the domain.  If the DMARC record contains a
+forensic address and you specify the control statement below, then
+exim will send these forensic emails.  It's also advised that you
+configure a dmarc_forensic_sender because the default sender address
+construction might be inadequate.
+
+  control = dmarc_forensic_enable
+
+(AGAIN: You can choose not to send these forensic reports by simply
+not putting the dmarc_forensic_enable control line at any point in
+your exim config.  If you don't tell it to send them, it will not
+send them.)
+
+There are no options to either control.  Both must appear before
+the DATA acl.
+
+
+4. You can now run DMARC checks in incoming SMTP by using the
+"dmarc_status" ACL condition in the DATA ACL.  You are required to
+call the spf condition first in the ACLs, then the "dmarc_status"
+condition.  Putting this condition in the ACLs is required in order
+for a DMARC check to actually occur.  All of the variables are set
+up before the DATA ACL, but there is no actual DMARC check that
+occurs until a "dmarc_status" condition is encountered in the ACLs.
+
+The dmarc_status condition takes a list of strings on its
+right-hand side.  These strings describe recommended action based
+on the DMARC check.  To understand what the policy recommendations
+mean, refer to the DMARC website above.  Valid strings are:
+
+  o accept      The DMARC check passed and the library recommends
+                accepting the email.
+  o reject      The DMARC check failed and the library recommends
+                rejecting the email.
+  o quarantine  The DMARC check failed and the library recommends
+                keeping it for further inspection.
+  o norecord    No policy section in the DMARC record for this
+                sender domain.
+  o nofrom      Unable to determine the domain of the sender.
+  o none        There is no DMARC record for this sender domain.
+  o error       Library error or dns error.
+
+You can prefix each string with an exclamation mark to invert its
+meaning, for example "!accept" will match all results but
+"accept".  The string list is evaluated left-to-right in a
+short-circuit fashion.  When a string matches the outcome of the
+DMARC check, the condition succeeds.  If none of the listed
+strings matches the outcome of the DMARC check, the condition
+fails.
+
+Of course, you can also use any other lookup method that Exim
+supports, including LDAP, Postgres, MySQL, etc, as long as the
+result is a list of colon-separated strings;
+
+Several expansion variables are set before the DATA ACL is
+processed, and you can use them in this ACL.  The following
+expansion variables are available:
+
+  o $dmarc_status
+    This is a one word status indicating what the DMARC library
+    thinks of the email.
+
+  o $dmarc_status_text
+    This is a slightly longer, human readable status.
+
+  o $dmarc_used_domain
+    This is the domain which DMARC used to look up the DMARC
+    policy record.
+
+  o $dmarc_ar_header
+    This is the entire Authentication-Results header which you can
+    add using an add_header modifier.
+
+
+5. How to enable DMARC advanced operation:
+By default, Exim's DMARC configuration is intended to be
+non-intrusive and conservative.  To facilitate this, Exim will not
+create any type of logging files without explicit configuration by
+you, the admin.  Nor will Exim send out any emails/reports about
+DMARC issues without explicit configuration by you, the admin (other
+than typical bounce messages that may come about due to ACL
+processing or failure delivery issues).
+
+In order to log statistics suitable to be imported by the opendmarc
+tools, you need to:
+a. Configure the global setting dmarc_history_file.
+b. Configure cron jobs to call the appropriate opendmarc history
+   import scripts and truncating the dmarc_history_file.
+
+In order to send forensic reports, you need to:
+a. Configure the global setting dmarc_forensic_sender.
+b. Configure, somewhere before the DATA ACL, the control option to
+   enable sending DMARC forensic reports.
+
+
+6. Example usage:
+(RCPT ACL)
+  warn    domains        = +local_domains
+          hosts          = +local_hosts
+          control        = dmarc_verify_disable
+
+  warn    !domains       = +screwed_up_dmarc_records
+          control        = dmarc_enable_forensic
+
+(DATA ACL)
+  warn    dmarc_status   = accept : none : off
+          !authenticated = *
+          log_message    = DMARC DEBUG: $dmarc_status $dmarc_used_domain
+          add_header     = $dmarc_ar_header
+
+  warn    dmarc_status   = !accept
+          !authenticated = *
+          log_message    = DMARC DEBUG: '$dmarc_status' for $dmarc_used_domain
+
+  warn    dmarc_status   = quarantine
+          !authenticated = *
+          set $acl_m_quarantine = 1
+          # Do something in a transport with this flag variable
+
+  deny    dmarc_status   = reject
+          !authenticated = *
+          message        = Message from $domain_used_domain failed sender's DMARC policy, REJECT
+
+
+
 
 --------------------------------------------------------------
 End of file