More tls_sni support: outbound, logging.

[exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 32e24ca8086811f1669b75f8f3c2436f835433f5..ea4e040e15d6f8d2b09dbb53e7fdedd003e653fa 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -11899,8 +11899,8 @@ If the variable appears in &%tls_certificate%& then this option and
 a different certificate to be presented (and optionally a different key to be
 used) to the client, based upon the value of the SNI extension.
 
 a different certificate to be presented (and optionally a different key to be
 used) to the client, based upon the value of the SNI extension.
 

-The value will be retained for the lifetime of the message, and not changed
-during outbound SMTP.
+The value will be retained for the lifetime of the message.  During outbound
+SMTP deliveries, it reflects the value of the tls_sni option on the transport.

 
 This is currently only available when using OpenSSL, built with support for
 SNI.
 
 This is currently only available when using OpenSSL, built with support for
 SNI.


@@ -15627,6 +15627,12 @@ receiving incoming messages as a server. If you want to supply certificates for
 use when sending messages as a client, you must set the &%tls_certificate%&
 option in the relevant &(smtp)& transport.
 
 use when sending messages as a client, you must set the &%tls_certificate%&
 option in the relevant &(smtp)& transport.
 

+.new
+If the option contains &$tls_sni$& and Exim is built against OpenSSL, then
+if the OpenSSL build supports TLS extensions and the TLS client sends the
+Server Name Indication extension, then this option and &%tls_privatekey%&
+will be re-expanded.
+.wen

 
 .option tls_crl main string&!! unset
 .cindex "TLS" "server certificate revocation list"
 
 .option tls_crl main string&!! unset
 .cindex "TLS" "server certificate revocation list"


@@ -15659,6 +15665,11 @@ the expansion is forced to fail, or the result is an empty string, the private
 key is assumed to be in the same file as the server's certificates. See chapter
 &<<CHAPTLS>>& for further details.
 
 key is assumed to be in the same file as the server's certificates. See chapter
 &<<CHAPTLS>>& for further details.
 

+.new
+See &%tls_certificate%& discussion of &$tls_sni$& for when this option may be
+re-expanded.
+.wen
+

 
 .option tls_remember_esmtp main boolean false
 .cindex "TLS" "esmtp state; remembering"
 
 .option tls_remember_esmtp main boolean false
 .cindex "TLS" "esmtp state; remembering"


@@ -22371,6 +22382,20 @@ ciphers is a preference order.
 
 
 
 
 
 

+.new
+.option tls_sni smtp string&!! unset
+.cindex "TLS" "Server Name Indication"
+.vindex "&$tls_sni$&"
+If this option is set then it sets the $tls_sni variable and causes any
+TLS session to pass this value as the Server Name Indication extension to
+the remote side, which can be used by the remote side to select an appropriate
+certificate and private key for the session.
+
+OpenSSL only, also requiring a build of OpenSSL that supports TLS extensions.
+.wen
+
+
+

 .option tls_tempfail_tryclear smtp boolean true
 .cindex "4&'xx'& responses" "to STARTTLS"
 When the server host is not in &%hosts_require_tls%&, and there is a problem in
 .option tls_tempfail_tryclear smtp boolean true
 .cindex "4&'xx'& responses" "to STARTTLS"
 When the server host is not in &%hosts_require_tls%&, and there is a problem in


@@ -33155,6 +33180,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_certificate_verified   `&  certificate verification status
 &`*tls_cipher                 `&  TLS cipher suite on <= and => lines
 &` tls_peerdn                 `&  TLS peer DN on <= and => lines

+&` tls_sni                    `&  TLS SNI on <= lines

 &` unknown_in_list            `&  DNS lookup failed in list match
 
 &` all                        `&  all of the above
 &` unknown_in_list            `&  DNS lookup failed in list match
 
 &` all                        `&  all of the above


@@ -33450,6 +33476,12 @@ 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
 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 SNI"
+.cindex "TLS" "logging SNI"
+&%tls_sni%&: When a message is received over an encrypted connection, and
+the remote host provided the Server Name Indication extension, the SNI is
+added to the log line, preceded by SNI=.
+.next

 .cindex "log" "DNS failure in list"
 &%unknown_in_list%&: This setting causes a log entry to be written when the
 result of a list match is failure because a DNS lookup failed.
 .cindex "log" "DNS failure in list"
 &%unknown_in_list%&: This setting causes a log entry to be written when the
 result of a list match is failure because a DNS lookup failed.