DANE: fix TA-mode verify under GnuTLS. Bug 2311

[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 ac3f1cc23f6218c1b7530a663fe3ad5fa1ca0993..0ad7f0de9a01f502fa49ff41072ed4c37e3a81ff 100644 (file)
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -447,11 +447,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.
 
-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.
-                    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,
@@ -709,6 +717,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.
+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
@@ -801,6 +811,14 @@ There are three new variables: $arc_state, $arc_state_reason, $arc_domains:
                        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".
 
 
@@ -811,7 +829,7 @@ 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.
-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
 of options.  The options implemented are
@@ -830,12 +848,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.
+
+   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.
+
  * 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.
@@ -846,6 +870,40 @@ used via the transport in question.
 
 
 
+
+REQUIRETLS support
+------------------
+Ref: https://tools.ietf.org/html/draft-ietf-uta-smtp-require-tls-03
+
+If compiled with EXPERIMENTAL_REQUIRETLS support is included for this
+feature, where a REQUIRETLS option is added to the MAIL command.
+The client may not retry in clear if the MAIL+REQUIRETLS fails (or was never
+offered), and the server accepts an obligation that any onward transmission
+by SMTP of the messages accepted will also use REQUIRETLS - or generate a
+fail DSN.
+
+The Exim implementation includes
+- a main-part option tls_advertise_requiretls; host list, default "*"
+- an observability variable $requiretls returning yes/no
+- an ACL "control = requiretls" modifier for setting the requirement
+- Log lines and Received: headers capitalise the S in the protocol
+  element: "P=esmtpS"
+
+Differences from spec:
+- we support upgrading the requirement for REQUIRETLS, including adding
+  it from cold, within an MTA.  The spec only define the sourcing MUA
+  as being able to source the requirement, and makes no mention of upgrade.
+- No support is coded for the RequireTLS header (which can be used
+  to annul DANE and/or STS policiy). [this can _almost_ be done in
+  transport option expansions, but not quite: it requires tha DANE-present
+  but STARTTLS-failing targets fallback to cleartext, which current DANE
+  coding specifically blocks]
+
+Note that REQUIRETLS is only advertised once a TLS connection is achieved
+(in contrast to STARTTLS).  If you want to check the advertising, do something
+like "swaks -s 127.0.0.1 -tls -q HELO".
+
+
 --------------------------------------------------------------
 End of file
 --------------------------------------------------------------