fix example line-length, add comment (openssl_options)

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 016f3f075f57c9bd7cf724d7eadfd50e784211e9..582eb60727aa18bf1a8da90a47cccfd635763460 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -11888,6 +11888,25 @@ the value of the Distinguished Name of the certificate is made available in the
 value is retained during message delivery, except during outbound SMTP
 deliveries.
 
+.new
+.vitem &$tls_sni$&
+.vindex "&$tls_sni$&"
+.cindex "TLS" "Server Name Indication"
+When a TLS session is being established, if the client sends the Server
+Name Indication extension, the value will be placed in this variable.
+If the variable appears in &%tls_certificate%& then this option and
+&%tls_privatekey%& will be re-expanded early in the TLS session, to permit
+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.  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.
+.wen
+
 .vitem &$tod_bsdinbox$&
 .vindex "&$tod_bsdinbox$&"
 The time of day and the date, in the format required for BSD-style mailbox
@@ -14362,61 +14381,63 @@ some now infamous attacks.
 
 An example:
 .code
-openssl_options = -all +microsoft_big_sslv3_buffer +dont_insert_empty_fragments
+# Make both old MS and old Eudora happy:
+openssl_options = -all +microsoft_big_sslv3_buffer \
+                       +dont_insert_empty_fragments
 .endd
 
 Possible options may include:
 .ilist
 &`all`&
-.ilist
+.next
 &`allow_unsafe_legacy_renegotiation`&
-.ilist
+.next
 &`cipher_server_preference`&
-.ilist
+.next
 &`dont_insert_empty_fragments`&
-.ilist
+.next
 &`ephemeral_rsa`&
-.ilist
+.next
 &`legacy_server_connect`&
-.ilist
+.next
 &`microsoft_big_sslv3_buffer`&
-.ilist
+.next
 &`microsoft_sess_id_bug`&
-.ilist
+.next
 &`msie_sslv2_rsa_padding`&
-.ilist
+.next
 &`netscape_challenge_bug`&
-.ilist
+.next
 &`netscape_reuse_cipher_change_bug`&
-.ilist
+.next
 &`no_compression`&
-.ilist
+.next
 &`no_session_resumption_on_renegotiation`&
-.ilist
+.next
 &`no_sslv2`&
-.ilist
+.next
 &`no_sslv3`&
-.ilist
+.next
 &`no_ticket`&
-.ilist
+.next
 &`no_tlsv1`&
-.ilist
+.next
 &`no_tlsv1_1`&
-.ilist
+.next
 &`no_tlsv1_2`&
-.ilist
+.next
 &`single_dh_use`&
-.ilist
+.next
 &`single_ecdh_use`&
-.ilist
+.next
 &`ssleay_080_client_dh_bug`&
-.ilist
+.next
 &`sslref2_reuse_cert_type_bug`&
-.ilist
+.next
 &`tls_block_padding_bug`&
-.ilist
+.next
 &`tls_d5_bug`&
-.ilist
+.next
 &`tls_rollback_bug`&
 .endlist
 
@@ -15609,6 +15630,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.
 
+.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"
@@ -15641,6 +15668,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.
 
+.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"
@@ -22353,6 +22385,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
@@ -33137,6 +33183,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_sni                    `&  TLS SNI on <= lines
 &` unknown_in_list            `&  DNS lookup failed in list match
 
 &` all                        `&  all of the above
@@ -33432,6 +33479,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
+.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.