More tls_sni support: outbound, logging.

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 8afccbf1d2266d989919bca2b06f52e7252873b8..ea4e040e15d6f8d2b09dbb53e7fdedd003e653fa 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -6223,13 +6223,26 @@ using Berkeley DB versions 3 or 4, it opens existing databases for reading with
 the DB_UNKNOWN option. This enables it to handle any of the types of database
 that the library supports, and can be useful for accessing DBM files created by
 other applications. (For earlier DB versions, DB_HASH is always used.)
 the DB_UNKNOWN option. This enables it to handle any of the types of database
 that the library supports, and can be useful for accessing DBM files created by
 other applications. (For earlier DB versions, DB_HASH is always used.)

+.new
+.next
+.cindex "lookup" "dbmjz"
+.cindex "lookup" "dbm &-- embedded NULs"
+.cindex "sasldb2"
+.cindex "dbmjz lookup type"
+&(dbmjz)&: This is the same as &(dbm)&, except that the lookup key is
+interpreted as an Exim list; the elements of the list are joined together with
+ASCII NUL characters to form the lookup key.  An example usage would be to
+authenticate incoming SMTP calls using the passwords from Cyrus SASL's
+&_/etc/sasldb2_& file with the &(gsasl)& authenticator or Exim's own
+&(cram_md5)& authenticator.
+.wen

 .next
 .cindex "lookup" "dbmnz"
 .cindex "lookup" "dbm &-- terminating zero"
 .cindex "binary zero" "in lookup key"
 .cindex "Courier"
 .cindex "&_/etc/userdbshadow.dat_&"
 .next
 .cindex "lookup" "dbmnz"
 .cindex "lookup" "dbm &-- terminating zero"
 .cindex "binary zero" "in lookup key"
 .cindex "Courier"
 .cindex "&_/etc/userdbshadow.dat_&"

-.cindex "dmbnz lookup type"
+.cindex "dbmnz lookup type"

 &(dbmnz)&: This is the same as &(dbm)&, except that a terminating binary zero
 is not included in the key that is passed to the DBM library. You may need this
 if you want to look up data in files that are created by or shared with some
 &(dbmnz)&: This is the same as &(dbm)&, except that a terminating binary zero
 is not included in the key that is passed to the DBM library. You may need this
 if you want to look up data in files that are created by or shared with some


@@ -8523,6 +8536,13 @@ start of a portion of the string that is interpreted and replaced as described
 below in section &<<SECTexpansionitems>>& onwards. Backslash is used as an
 escape character, as described in the following section.
 
 below in section &<<SECTexpansionitems>>& onwards. Backslash is used as an
 escape character, as described in the following section.
 

+Whether a string is expanded depends upon the context.  Usually this is solely
+dependent upon the option for which a value is sought; in this documentation,
+options for which string expansion is performed are marked with &dagger; after
+the data type.  ACL rules always expand strings.  A couple of expansion
+conditions do not expand some of the brace-delimited branches, for security
+reasons.
+

 
 
 .section "Literal text in expanded strings" "SECTlittext"
 
 
 .section "Literal text in expanded strings" "SECTlittext"


@@ -9904,6 +9924,10 @@ lower case), signifying multiplication by 1024 or 1024*1024, respectively.
 As a special case, the numerical value of an empty string is taken as
 zero.
 
 As a special case, the numerical value of an empty string is taken as
 zero.
 

+In all cases, a relative comparator OP is testing if <&'string1'&> OP
+<&'string2'&>; the above example is checking if &$message_size$& is larger than
+10M, not if 10M is larger than &$message_size$&.
+

 
 .vitem &*bool&~{*&<&'string'&>&*}*&
 .cindex "expansion" "boolean parsing"
 
 .vitem &*bool&~{*&<&'string'&>&*}*&
 .cindex "expansion" "boolean parsing"


@@ -11824,6 +11848,16 @@ command in a filter file. Its use is explained in the description of that
 command, which can be found in the separate document entitled &'Exim's
 interfaces to mail filtering'&.
 
 command, which can be found in the separate document entitled &'Exim's
 interfaces to mail filtering'&.
 

+.new
+.vitem &$tls_bits$&
+.vindex "&$tls_bits$&"
+Contains an approximation of the TLS cipher's bit-strength; the meaning of
+this depends upon the TLS implementation used.
+If TLS has not been negotiated, the value will be 0.
+The value of this is automatically fed into the Cyrus SASL authenticator
+when acting as a server, to specify the "external SSF" (a SASL term).
+.wen
+

 .vitem &$tls_certificate_verified$&
 .vindex "&$tls_certificate_verified$&"
 This variable is set to &"1"& if a TLS certificate was verified when the
 .vitem &$tls_certificate_verified$&
 .vindex "&$tls_certificate_verified$&"
 This variable is set to &"1"& if a TLS certificate was verified when the


@@ -11854,6 +11888,24 @@ 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


@@ -14299,16 +14351,12 @@ harm. This option overrides the &%pipe_as_creator%& option of the &(pipe)&
 transport driver.
 
 
 transport driver.
 
 

-.option openssl_options main "string list" +dont_insert_empty_fragments
+.option openssl_options main "string list" unset

 .cindex "OpenSSL "compatibility options"
 This option allows an administrator to adjust the SSL options applied
 by OpenSSL to connections.  It is given as a space-separated list of items,
 .cindex "OpenSSL "compatibility options"
 This option allows an administrator to adjust the SSL options applied
 by OpenSSL to connections.  It is given as a space-separated list of items,

-each one to be +added or -subtracted from the current value.  The default
-value is one option which happens to have been set historically.  You can
-remove all options with:
-.code
-openssl_options = -all
-.endd
+each one to be +added or -subtracted from the current value.
+

 This option is only available if Exim is built against OpenSSL.  The values
 available for this option vary according to the age of your OpenSSL install.
 The &"all"& value controls a subset of flags which are available, typically
 This option is only available if Exim is built against OpenSSL.  The values
 available for this option vary according to the age of your OpenSSL install.
 The &"all"& value controls a subset of flags which are available, typically


@@ -14320,14 +14368,76 @@ names lose the leading &"SSL_OP_"& and are lower-cased.
 Note that adjusting the options can have severe impact upon the security of
 SSL as used by Exim.  It is possible to disable safety checks and shoot
 yourself in the foot in various unpleasant ways.  This option should not be
 Note that adjusting the options can have severe impact upon the security of
 SSL as used by Exim.  It is possible to disable safety checks and shoot
 yourself in the foot in various unpleasant ways.  This option should not be

-adjusted lightly.  An unrecognised item will be detected at by invoking Exim
-with the &%-bV%& flag.
+adjusted lightly.  An unrecognised item will be detected at startup, by
+invoking Exim with the &%-bV%& flag.
+
+.new
+Historical note: prior to release 4.78, Exim defaulted this value to
+"+dont_insert_empty_fragments", which may still be needed for compatibility
+with some clients, but which lowers security by increasing exposure to
+some now infamous attacks.
+.wen

 
 An example:
 .code
 
 An example:
 .code

-openssl_options = -all +microsoft_big_sslv3_buffer
+openssl_options = -all +microsoft_big_sslv3_buffer +dont_insert_empty_fragments

 .endd
 
 .endd
 

+Possible options may include:
+.ilist
+&`all`&
+.ilist
+&`allow_unsafe_legacy_renegotiation`&
+.ilist
+&`cipher_server_preference`&
+.ilist
+&`dont_insert_empty_fragments`&
+.ilist
+&`ephemeral_rsa`&
+.ilist
+&`legacy_server_connect`&
+.ilist
+&`microsoft_big_sslv3_buffer`&
+.ilist
+&`microsoft_sess_id_bug`&
+.ilist
+&`msie_sslv2_rsa_padding`&
+.ilist
+&`netscape_challenge_bug`&
+.ilist
+&`netscape_reuse_cipher_change_bug`&
+.ilist
+&`no_compression`&
+.ilist
+&`no_session_resumption_on_renegotiation`&
+.ilist
+&`no_sslv2`&
+.ilist
+&`no_sslv3`&
+.ilist
+&`no_ticket`&
+.ilist
+&`no_tlsv1`&
+.ilist
+&`no_tlsv1_1`&
+.ilist
+&`no_tlsv1_2`&
+.ilist
+&`single_dh_use`&
+.ilist
+&`single_ecdh_use`&
+.ilist
+&`ssleay_080_client_dh_bug`&
+.ilist
+&`sslref2_reuse_cert_type_bug`&
+.ilist
+&`tls_block_padding_bug`&
+.ilist
+&`tls_d5_bug`&
+.ilist
+&`tls_rollback_bug`&
+.endlist
+

 
 .option oracle_servers main "string list" unset
 .cindex "Oracle" "server list"
 
 .option oracle_servers main "string list" unset
 .cindex "Oracle" "server list"


@@ -15517,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"


@@ -15549,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"


@@ -22261,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


@@ -24169,6 +24304,20 @@ lookup_cram:
 Note that this expansion explicitly forces failure if the lookup fails
 because &$auth1$& contains an unknown user name.
 
 Note that this expansion explicitly forces failure if the lookup fails
 because &$auth1$& contains an unknown user name.
 

+.new
+As another example, if you wish to re-use a Cyrus SASL sasldb2 file without
+using the relevant libraries, you need to know the realm to specify in the
+lookup and then ask for the &"userPassword"& attribute for that user in that
+realm, with:
+.code
+cyrusless_crammd5:
+  driver = cram_md5
+  public_name = CRAM-MD5
+  server_secret = ${lookup{$auth1:mail.example.org:userPassword}\
+                  dbmjz{/etc/sasldb2}}
+  server_set_id = $auth1
+.endd
+.wen

 
 .section "Using cram_md5 as a client" "SECID177"
 .cindex "options" "&(cram_md5)& authenticator (client)"
 
 .section "Using cram_md5 as a client" "SECID177"
 .cindex "options" "&(cram_md5)& authenticator (client)"


@@ -24283,8 +24432,10 @@ sasl:
   server_set_id = $auth1
 .endd
 
   server_set_id = $auth1
 .endd
 

-.option server_realm cyrus_sasl string unset
+.new
+.option server_realm cyrus_sasl string&!! unset

 This specifies the SASL realm that the server claims to be in.
 This specifies the SASL realm that the server claims to be in.

+.wen

 
 
 .option server_service cyrus_sasl string &`smtp`&
 
 
 .option server_service cyrus_sasl string &`smtp`&


@@ -24498,6 +24649,20 @@ An &'anonymous token'& is something passed along as an unauthenticated
 identifier; this is analogous to FTP anonymous authentication passing an
 email address, or software-identifier@, as the "password".
 
 identifier; this is analogous to FTP anonymous authentication passing an
 email address, or software-identifier@, as the "password".
 

+
+An example showing the password having the realm specified in the callback
+and demonstrating a Cyrus SASL to GSASL migration approach is:
+.code
+gsasl_cyrusless_crammd5:
+  driver = gsasl
+  public_name = CRAM-MD5
+  server_realm = imap.example.org
+  server_password = ${lookup{$auth1:$auth3:userPassword}\
+                    dbmjz{/etc/sasldb2}{$value}fail}
+  server_set_id = ${quote:$auth1}
+  server_condition = yes
+.endd
+

 .wen
 
 . ////////////////////////////////////////////////////////////////////////////
 .wen
 
 . ////////////////////////////////////////////////////////////////////////////


@@ -24546,7 +24711,8 @@ role suffix.  For instance, &"joe/admin@EXAMPLE.ORG"&.
 .next
 .vindex "&$auth2$&"
 &$auth2$&: the &'authorization id'&, sent within SASL encapsulation after
 .next
 .vindex "&$auth2$&"
 &$auth2$&: the &'authorization id'&, sent within SASL encapsulation after

-authentication.
+authentication.  If that was empty, this will also be set to the
+GSS Display Name.

 .endlist
 
 .wen
 .endlist
 
 .wen


@@ -33014,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


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