TLS: Session resumption, under the EXPERIMENTAL_TLS_RESUME build option.

[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 2f1e5c59194a897481784465d4ac9a0184350478..a2861c4a968b94f07d7e7f4ff1ad0b246b6279a1 100644 (file)
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -951,6 +951,50 @@ Transport configurations should be checked for this.  An example avoidance:
 
 
 
+TLS Session Resumption
+----------------------
+TLS Session Resumption for TLS 1.2 and TLS1.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.
+
+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
 --------------------------------------------------------------