TLS: library version build-time checks for resumption support

[users/jgh/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 9b472c080dbe506cb47844f5e47f0ca7915a73f1..feecb3375ca478404d95e2541e897cbab5574882 100644 (file)
--- 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
@@ -949,6 +951,51 @@ 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.
+
+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 bit 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 {}{}}.
+
+
 --------------------------------------------------------------
 End of file
 --------------------------------------------------------------