X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/a1d4300b12abf65bb714f88f60f5719f66e66410..c19ab167ac:/doc/doc-txt/experimental-spec.txt

diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt
index 49935fb40..2f1e5c591 100644
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -428,7 +428,7 @@ 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:
+2. Use the following global options to configure DMARC:
 
 Required:
 dmarc_tld_file      Defines the location of a text file of valid
@@ -437,6 +437,8 @@ dmarc_tld_file      Defines the location of a text file of valid
                     the most current version can be downloaded
                     from a link at http://publicsuffix.org/list/.
                     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
@@ -871,37 +873,82 @@ used via the transport in question.
 
 
 
-REQUIRETLS support
-------------------
-Ref: https://tools.ietf.org/html/draft-ietf-uta-smtp-require-tls-03
+Early pipelining support
+------------------------
+Ref: https://datatracker.ietf.org/doc/draft-harris-early-pipe/
 
-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.
+If compiled with EXPERIMENTAL_PIPE_CONNECT support is included for this feature.
+The server advertises the feature in its EHLO response, currently using the name
+"X_PIPE_CONNECT" (this will change, some time in the future).
+A client may cache this information, along with the rest of the EHLO response,
+and use it for later connections.  Those later ones can send esmtp commands before
+a banner is received.
 
-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"
+Up to 1.5 roundtrip times can be taken out of cleartext connections, 2.5 on
+STARTTLS connections.
+
+In combination with the traditional PIPELINING feature the following example
+sequences are possible (among others):
+
+(client)                (server)
+
+EHLO,MAIL,RCPT,DATA ->
+                     <- banner,EHLO-resp,MAIL-ack,RCPT-ack,DATA-goahead
+message-data        ->
+------
+
+EHLO,MAIL,RCPT,BDAT              ->
+                                  <- banner,EHLO-resp,MAIL-ack,RCPT-ack
+message-data                     ->
+------
+
+EHLO,STARTTLS                     ->
+                                   <- banner,EHLO-resp,TLS-goahead
+TLS1.2-client-hello               ->
+                                   <- TLS-server-hello,cert,hello-done
+client-Kex,change-cipher,finished ->
+                                   <- change-cipher,finished
+EHLO,MAIL,RCPT,DATA               ->
+                                   <- EHLO-resp,MAIL-ack,RCPT-ack,DATA-goahead
+
+------
+(tls-on-connect)
+TLS1.2-client-hello               ->
+                                   <- TLS-server-hello,cert,hello-done
+client-Kex,change-cipher,finished ->
+                                   <- change-cipher,finshed
+                                   <- banner
+EHLO,MAIL,RCPT,DATA               ->
+                                   <- EHLO-resp,MAIL-ack,RCPT-ack,DATA-goahead
+
+Where the initial client packet is SMTP, it can combine with the TCP Fast Open
+feature and be sent in the TCP SYN.
+
+
+A main-section option "pipelining_connect_advertise_hosts" (default: *)
+and an smtp transport option "hosts_pipe_connect" (default: unset)
+control the feature.
+
+If the "pipelining" log_selector is enabled, the "L" field in server <=
+log lines has a period appended if the feature was advertised but not used;
+or has an asterisk appended if the feature was used.  In client => lines
+the "L" field has an asterisk appended if the feature was used.
+
+The "retry_data_expire" option controls cache invalidation.
+Entries are also rewritten (or cleared) if the adverised features
+change.
+
+
+NOTE: since the EHLO command must be constructed before the connection is
+made it cannot depend on the interface IP address that will be used.
+Transport configurations should be checked for this.  An example avoidance:
+
+ helo_data =	${if def:sending_ip_address \
+		   {${lookup dnsdb{>! ptr=$sending_ip_address} \
+			{${sg{$value} {^([^!]*).*\$} {\$1}}} fail}} \
+		   {$primary_hostname}}
 
-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".
 
 
 --------------------------------------------------------------