X-Git-Url: https://git.exim.org/users/heiko/exim.git/blobdiff_plain/7adc9ca07a9a870f92a14d16740abfecde0bdfa4..4a90d4879978fe062e0539da0942c3f9176f5b9b:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 748f81cc0..6dcb69d47 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -6858,6 +6858,29 @@ The final resulting element can be a simple JSON type or a JSON object or array; for the latter two a string-representation of the JSON is returned. For elements of type string, the returned value is de-quoted. + + +.new +.next +.cindex LMDB +.cindex lookup lmdb +.cindex database lmdb +&(lmdb)&: The given file is an LMDB database. +LMDB is a memory-mapped key-value store, +with API modeled loosely on that of BerkeleyDB. +See &url(https://symas.com/products/lightning-memory-mapped-database/) +for the feature set and operation modes. + +Exim provides read-only access via the LMDB C library. +The library can be obtained from &url(https://github.com/LMDB/lmdb) +or your operating system package repository. +To enable LMDB support in Exim set LOOKUP_LMDB=yes in &_Local/Makefile_&. + +You will need to separately create the LMDB database file, +possibly using the &"mdb_load"& utility. +.wen + + .next .cindex "linear search" .cindex "lookup" "lsearch" @@ -13766,6 +13789,17 @@ the value of the Distinguished Name of the certificate is made available in the If certificate verification fails it may refer to a failing chain element which is not the leaf. + +.new +.vitem &$tls_in_resumption$& &&& + &$tls_out_resumption$& +.vindex &$tls_in_resumption$& +.vindex &$tls_out_resumption$& +.cindex TLS resumption +Observability for TLS session resumption. See &<>& for details. +.wen + + .vitem &$tls_in_sni$& .vindex "&$tls_in_sni$&" .vindex "&$tls_sni$&" @@ -18274,6 +18308,14 @@ preference order of the available ciphers. Details are given in sections &<>& and &<>&. +.new +.option tls_resumption_hosts main "host list&!!" unset +.cindex TLS resumption +This option controls which connections to offer the TLS resumption feature. +See &<>& for details. +.wen + + .option tls_try_verify_hosts main "host list&!!" unset .cindex "TLS" "client certificate verification" .cindex "certificate" "verification of client" @@ -25594,6 +25636,14 @@ is used in different ways by OpenSSL and GnuTLS (see sections ciphers is a preference order. +.new +.option tls_resumption_hosts smtp "host list&!!" unset +.cindex TLS resumption +This option controls which connections to use the TLS resumption feature. +See &<>& for details. +.wen + + .option tls_sni smtp string&!! unset .cindex "TLS" "Server Name Indication" @@ -29424,6 +29474,100 @@ Open-source PKI book, available online at .ecindex IIDencsmtp2 +.new +.section "TLS Resumption" "SECTresumption" +.cindex TLS 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 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 (on TLS1.2) one full packet roundtrip time. + +.ilist +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. + +.cindex "hints database" tls + Since a new hints DB is used on the TLS client, + the hints DB maintenance should be updated to additionally handle "tls". + +.next +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 (OpenSSL: 1hr, and one previous key is used for + overlap; GnuTLS 6hr but does not specify any overlap). + Tickets have limited lifetime (2hr, and new ones issued after 1hr under + OpenSSL. GnuTLS 2hr, appears to not do overlap). + + There is a question-mark over the security of the Diffie-Helman parameters + used for session negotiation. + +.next +Observability: + + The &%log_selector%& "tls_resumption" appends an asterisk to the tls_cipher "X=" + element. + + The variables &$tls_in_resumption$& and &$tls_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 in &%listextract%& expansions. + +.next +Control: + +The &%tls_resumption_hosts%& main option specifies a hostlist for which +exim, operating as a server, will offer resumption to clients. +Current best practice is to not offer the feature to MUA connection. +Commonly this can be done like this: +.code +tls_resumption_hosts = ${if inlist {$received_port}{587:465} {:}{*}} +.endd +If the peer host matches the list after expansion then resumption +is offered and/or accepted. + +The &%tls_resumption_hosts% smtp transport option performs the +equivalent function for operation as a client. +If the peer host matches the list after expansion then resumption +is attempted (if a stored session is available) or the information +stored (if supplied by the peer). + + +.next +Issues: + + In a resumed session: +.ilist + The variables &$tls_{in,out}_cipher$& will have values different + to the original (under GnuTLS). +.next + The variables &$tls_{in,out}_ocsp$& will be "not requested" or "no response", + and the &%hosts_require_ocsp%& smtp trasnport option will fail. +. XXX need to do something with that hosts_require_ocsp +.endlist + +.endlist +.wen + .section DANE "SECDANE" .cindex DANE @@ -38043,6 +38187,7 @@ selection marked by asterisks: &`*tls_certificate_verified `& certificate verification status &`*tls_cipher `& TLS cipher suite on <= and => lines &` tls_peerdn `& TLS peer DN on <= and => lines +&` tls_resumption `& append * to cipher field &` tls_sni `& TLS SNI on <= lines &` unknown_in_list `& DNS lookup failed in list match @@ -38444,6 +38589,14 @@ connection, the cipher suite used is added to the log line, preceded by X=. connection, and a certificate is supplied by the remote host, the peer DN is added to the log line, preceded by DN=. .next +.cindex "log" "TLS resumption" +.cindex "TLS" "logging session resumption" +.new +&%tls_resumption%&: When a message is sent or received over an encrypted +connection and the TLS session resumed one used on a previous TCP connection, +an asterisk is appended to the X= cipher field in the log line. +.wen +.next .cindex "log" "TLS SNI" .cindex "TLS" "logging SNI" &%tls_sni%&: When a message is received over an encrypted connection, and @@ -38989,6 +39142,10 @@ for remote hosts .next &'ratelimit'&: the data for implementing the ratelimit ACL condition .next +.new +&'tls'&: TLS session resumption data +.wen +.next &'misc'&: other hints data .endlist