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.
 
 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
 .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
 
 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`&
 .endd
 
 Possible options may include:
 .ilist
 &`all`&

-.ilist
+.next

 &`allow_unsafe_legacy_renegotiation`&
 &`allow_unsafe_legacy_renegotiation`&

-.ilist
+.next

 &`cipher_server_preference`&
 &`cipher_server_preference`&

-.ilist
+.next

 &`dont_insert_empty_fragments`&
 &`dont_insert_empty_fragments`&

-.ilist
+.next

 &`ephemeral_rsa`&
 &`ephemeral_rsa`&

-.ilist
+.next

 &`legacy_server_connect`&
 &`legacy_server_connect`&

-.ilist
+.next

 &`microsoft_big_sslv3_buffer`&
 &`microsoft_big_sslv3_buffer`&

-.ilist
+.next

 &`microsoft_sess_id_bug`&
 &`microsoft_sess_id_bug`&

-.ilist
+.next

 &`msie_sslv2_rsa_padding`&
 &`msie_sslv2_rsa_padding`&

-.ilist
+.next

 &`netscape_challenge_bug`&
 &`netscape_challenge_bug`&

-.ilist
+.next

 &`netscape_reuse_cipher_change_bug`&
 &`netscape_reuse_cipher_change_bug`&

-.ilist
+.next

 &`no_compression`&
 &`no_compression`&

-.ilist
+.next

 &`no_session_resumption_on_renegotiation`&
 &`no_session_resumption_on_renegotiation`&

-.ilist
+.next

 &`no_sslv2`&
 &`no_sslv2`&

-.ilist
+.next

 &`no_sslv3`&
 &`no_sslv3`&

-.ilist
+.next

 &`no_ticket`&
 &`no_ticket`&

-.ilist
+.next

 &`no_tlsv1`&
 &`no_tlsv1`&

-.ilist
+.next

 &`no_tlsv1_1`&
 &`no_tlsv1_1`&

-.ilist
+.next

 &`no_tlsv1_2`&
 &`no_tlsv1_2`&

-.ilist
+.next

 &`single_dh_use`&
 &`single_dh_use`&

-.ilist
+.next

 &`single_ecdh_use`&
 &`single_ecdh_use`&

-.ilist
+.next

 &`ssleay_080_client_dh_bug`&
 &`ssleay_080_client_dh_bug`&

-.ilist
+.next

 &`sslref2_reuse_cert_type_bug`&
 &`sslref2_reuse_cert_type_bug`&

-.ilist
+.next

 &`tls_block_padding_bug`&
 &`tls_block_padding_bug`&

-.ilist
+.next

 &`tls_d5_bug`&
 &`tls_d5_bug`&

-.ilist
+.next

 &`tls_rollback_bug`&
 .endlist
 
 &`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.
 
 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"


@@ -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.
 
 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"


@@ -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
 .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_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


@@ -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
 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.