OpenSSL: discard expired resumption session in client
[exim.git] / doc / doc-txt / experimental-spec.txt
index 84fd54716c7397b70006e8f00a2bcfaeb6f2bdcb..f304cf455127cef1e58afd1510e3fdc6182d0243 100644 (file)
@@ -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,41 +873,6 @@ 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".
-
-
-
-
 Early pipelining support
 ------------------------
 Ref: https://datatracker.ietf.org/doc/draft-harris-early-pipe/
@@ -984,6 +951,63 @@ Transport configurations should be checked for this.  An example avoidance:
 
 
 
+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.  Tickets have limited lifetime.
+
+ 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}_certificate_verified will be set, and verify = certificate
+    will be true, when verify failed but tls_try_verify_hosts allowed the
+    connection (under OpenSSL)
+  $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
 --------------------------------------------------------------