Routers: named variables

[exim.git] / doc / doc-txt / experimental-spec.txt

diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt
index 3c348d0df6118784c46b3a3677f8ed5fe4eab0c8..f748f61460a27692e61ed51630e379ec5c2b156c 100644 (file)
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -428,16 +428,17 @@ need to uncomment them if an rpm (or you) installed them in the
 package controlled locations (/usr/include and /usr/lib).
 
 
 package controlled locations (/usr/include and /usr/lib).
 
 

-2. Use the following global settings to configure DMARC:
+2. Use the following global options to configure DMARC:

 
 

-Optional:
+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/.
 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/.

-                    If unset, "/etc/exim/opendmarc.tlds" (hardcoded)
-                    is used.
+                    See also util/renew-opendmarc-tlds.sh script.
+                   The default for the option is currently
+                   /etc/exim/opendmarc.tlds

 
 Optional:
 dmarc_history_file  Defines the location of a file to log results
 
 Optional:
 dmarc_history_file  Defines the location of a file to log results


@@ -448,11 +449,19 @@ dmarc_history_file  Defines the location of a file to log results
                     directory of this file is writable by the user
                     exim runs as.
 
                     directory of this file is writable by the user
                     exim runs as.
 

-dmarc_forensic_sender The email address to use when sending a
+dmarc_forensic_sender Alternate 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.
                     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
+
+                   If set, this is expanded and used for the
+                   From: header line; the address is extracted
+                   from it and used for the envelope from.
+                   If not set, the From: header is expanded from
+                   the dsn_from option, and <> is used for the
+                   envelope from.
+
+                    Default: unset.

 
 
 3. By default, the DMARC processing will run for any remote,
 
 
 3. By default, the DMARC processing will run for any remote,


@@ -525,6 +534,9 @@ 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.
 
 supports, including LDAP, Postgres, MySQL, etc, as long as the
 result is a list of colon-separated strings.
 

+Performing the check sets up information used by the
+${authresults } expansion item.
+

 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:
 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:


@@ -548,9 +560,8 @@ expansion variables are available:
     are "none", "reject" and "quarantine".  It is blank when there
     is any error, including no DMARC record.
 
     are "none", "reject" and "quarantine".  It is blank when there
     is any error, including no DMARC record.
 

-  o $dmarc_ar_header
-    This is the entire Authentication-Results header which you can
-    add using an add_header modifier.
+A now-redundant variable $dmarc_ar_header has now been withdrawn.
+Use the ${authresults } expansion instead.

 
 
 5. How to enable DMARC advanced operation:
 
 
 5. How to enable DMARC advanced operation:


@@ -590,7 +601,6 @@ b. Configure, somewhere before the DATA ACL, the control option to
   warn    dmarc_status   = accept : none : off
           !authenticated = *
           log_message    = DMARC DEBUG: $dmarc_status $dmarc_used_domain
   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 = *
 
   warn    dmarc_status   = !accept
           !authenticated = *


@@ -609,6 +619,8 @@ b. Configure, somewhere before the DATA ACL, the control option to
           !authenticated = *
           message        = Message from $dmarc_used_domain failed sender's DMARC policy, REJECT
 
           !authenticated = *
           message        = Message from $dmarc_used_domain failed sender's DMARC policy, REJECT
 

+  warn    add_header     = :at_start:${authresults {$primary_hostname}}
+

 
 
 DSN extra information
 
 
 DSN extra information


@@ -707,6 +719,8 @@ an external directory retaining the exim spool format.
 
 The spool files can then be processed by external processes and then
 requeued into exim spool directories for final delivery.
 
 The spool files can then be processed by external processes and then
 requeued into exim spool directories for final delivery.

+However, note carefully the warnings in the main documentation on
+qpool file formats.

 
 The motivation/inspiration for the transport is to allow external
 processes to access email queued by exim and have access to all the
 
 The motivation/inspiration for the transport is to allow external
 processes to access email queued by exim and have access to all the


@@ -723,7 +737,7 @@ the queuefile driver.
 The transport only takes one option:
 
 * directory - This is used to specify the directory messages should be
 The transport only takes one option:
 
 * directory - This is used to specify the directory messages should be

-copied to
+copied to.  Expanded.

 
 The generic transport options (body_only, current_directory, disable_logging,
 debug_print, delivery_date_add, envelope_to_add, event_action, group,
 
 The generic transport options (body_only, current_directory, disable_logging,
 debug_print, delivery_date_add, envelope_to_add, event_action, group,


@@ -791,7 +805,21 @@ standard header.
        Note that it would be wise to strip incoming messages of A-R headers
        that claim to be from our own <admd-identifier>.
 
        Note that it would be wise to strip incoming messages of A-R headers
        that claim to be from our own <admd-identifier>.
 

-There are two new variables: $arc_state and $arc_state_reason.
+There are four new variables:
+
+  $arc_state           One of pass, fail, none
+  $arc_state_reason    (if fail, why)
+  $arc_domains         colon-sep list of ARC chain domains, in chain order.
+                       problematic elements may have empty list elements
+  $arc_oldest_pass     lowest passing instance number of chain
+
+Example:
+  logwrite = oldest-p-ams: <${reduce {$lh_ARC-Authentication-Results:} \
+                               {} \
+                               {${if = {$arc_oldest_pass} \
+                                       {${extract {i}{${extract {1}{;}{$item}}}}} \
+                                       {$item} {$value}}} \
+                           }>

 
 Receive log lines for an ARC pass will be tagged "ARC".
 
 
 Receive log lines for an ARC pass will be tagged "ARC".
 


@@ -803,12 +831,18 @@ An option on the smtp transport, which constructs and prepends to the message
 an ARC set of headers.  The textually-first Authentication-Results: header
 is used as a basis (you must have added one on entry to the ADMD).
 Expanded as a whole; if unset, empty or forced-failure then no signing is done.
 an ARC set of headers.  The textually-first Authentication-Results: header
 is used as a basis (you must have added one on entry to the ADMD).
 Expanded as a whole; if unset, empty or forced-failure then no signing is done.

-If it is set, all three elements must be non-empty.
+If it is set, all of the first three elements must be non-empty.

 
 The fourth element is optional, and if present consists of a comma-separated list
 
 The fourth element is optional, and if present consists of a comma-separated list

-of options.  The only option implemented so far is
-  timestamps    Add a t= tag to the generated AMS and AS headers, with the
-                current time.
+of options.  The options implemented are
+
+  timestamps           Add a t= tag to the generated AMS and AS headers, with the
+                       current time.
+  expire[=<val>]       Add an x= tag to the generated AMS header, with an expiry time.
+                       If the value <val> is an plain number it is used unchanged.
+                       If it starts with a '+' then the following number is added
+                       to the current time, as an offset in seconds.
+                       If a value is not given it defaults to a one month offset.

 
 [As of writing, gmail insist that a t= tag on the AS is mandatory]
 
 
 [As of writing, gmail insist that a t= tag on the AS is mandatory]
 


@@ -816,12 +850,18 @@ Caveats:
  * There must be an Authentication-Results header, presumably added by an ACL
    while receiving the message, for the same ADMD, for arc_sign to succeed.
    This requires careful coordination between inbound and outbound logic.
  * There must be an Authentication-Results header, presumably added by an ACL
    while receiving the message, for the same ADMD, for arc_sign to succeed.
    This requires careful coordination between inbound and outbound logic.

+
+   Only one A-R header is taken account of.  This is a limitation versus
+   the ARC spec (which says that all A-R headers from within the ADMD must
+   be used).
+

  * If passing a message to another system, such as a mailing-list manager
    (MLM), between receipt and sending, be wary of manipulations to headers made
    by the MLM.
    + For instance, Mailman with REMOVE_DKIM_HEADERS==3 might improve
      deliverability in a pre-ARC world, but that option also renames the
      Authentication-Results header, which breaks signing.
  * If passing a message to another system, such as a mailing-list manager
    (MLM), between receipt and sending, be wary of manipulations to headers made
    by the MLM.
    + For instance, Mailman with REMOVE_DKIM_HEADERS==3 might improve
      deliverability in a pre-ARC world, but that option also renames the
      Authentication-Results header, which breaks signing.

+

  * Even if you use multiple DKIM keys for different domains, the ARC concept
    should try to stick to one ADMD, so pick a primary domain and use that for
    AR headers and outbound signing.
  * Even if you use multiple DKIM keys for different domains, the ARC concept
    should try to stick to one ADMD, so pick a primary domain and use that for
    AR headers and outbound signing.


@@ -832,6 +872,64 @@ used via the transport in question.
 
 
 
 
 
 

+
+TLS Session Resumption
+----------------------
+TLS Session Resumption for TLS 1.2 and TLS 1.3 connections can be used (defined
+in RFC 5077 for 1.2).  The support for this can be included by building with
+EXPERIMENTAL_TLS_RESUME defined.  This requires GnuTLS 3.6.3 or OpenSSL 1.1.1
+(or later).
+
+Session resumption (this is the "stateless" variant) involves the server sending
+a "session ticket" to the client on one connection, which can be stored by the
+client and used for a later session.  The ticket contains sufficient state for
+the server to reconstruct the TLS session, avoiding some expensive crypto
+calculation and one full packet roundtrip time.
+
+Operational cost/benefit:
+ The extra data being transmitted costs a minor amount, and the client has
+ extra costs in storing and retrieving the data.
+
+ In the Exim/Gnutls implementation the extra cost on an initial connection
+ which is TLS1.2 over a loopback path is about 6ms on 2017-laptop class hardware.
+ The saved cost on a subsequent connection is about 4ms; three or more
+ connections become a net win.  On longer network paths, two or more
+ connections will have an average lower startup time thanks to the one
+ saved packet roundtrip.  TLS1.3 will save the crypto cpu costs but not any
+ packet roundtrips.
+
+ Since a new hints DB is used, the hints DB maintenance should be updated
+ to additionally handle "tls".
+
+Security aspects:
+ The session ticket is encrypted, but is obviously an additional security
+ vulnarability surface.  An attacker able to decrypt it would have access
+ all connections using the resumed session.
+ The session ticket encryption key is not committed to storage by the server
+ and is rotated regularly (OpenSSL: 1hr, and one previous key is used for
+ overlap; GnuTLS 6hr but does not specify any overlap).
+ Tickets have limited lifetime (2hr, and new ones issued after 1hr under
+ OpenSSL.  GnuTLS 2hr, appears to not do overlap).
+
+ There is a question-mark over the security of the Diffie-Helman parameters
+ used for session negotiation. TBD.  q-value; cf bug 1895
+
+Observability:
+ New log_selector "tls_resumption", appends an asterisk to the tls_cipher "X="
+ element.
+
+ Variables $tls_{in,out}_resumption have bits 0-4 indicating respectively
+ support built, client requested ticket, client offered session,
+ server issued ticket, resume used.  A suitable decode list is provided
+ in the builtin macro _RESUME_DECODE for ${listextract {}{}}.
+
+Issues:
+ In a resumed session:
+  $tls_{in,out}_cipher will have values different to the original (under GnuTLS)
+  $tls_{in,out}_ocsp will be "not requested" or "no response", and
+   hosts_require_ocsp will fail
+
+

 --------------------------------------------------------------
 End of file
 --------------------------------------------------------------
 --------------------------------------------------------------
 End of file
 --------------------------------------------------------------