More tls_sni support: outbound, logging.
[exim.git] / doc / doc-docbook / spec.xfpt
index d18b09dfed03d25b4d0d9851245f4298e1f82ea3..ea4e040e15d6f8d2b09dbb53e7fdedd003e653fa 100644 (file)
@@ -46,7 +46,7 @@
 . /////////////////////////////////////////////////////////////////////////////
 
 .set previousversion "4.75"
-.set version "4.76"
+.set version "4.77"
 
 .set ACL "access control lists (ACLs)"
 .set I   "    "
 <author><firstname>Exim</firstname><surname>Maintainers</surname></author>
 <authorinitials>EM</authorinitials>
 <revhistory><revision>
-  <revnumber>4.76</revnumber>
-  <date>06 May 2011</date>
+  <revnumber>4.77</revnumber>
+  <date>10 Oct 2011</date>
   <authorinitials>EM</authorinitials>
 </revision></revhistory>
 <copyright><year>2011</year><holder>University of Cambridge</holder></copyright>
@@ -1868,6 +1868,14 @@ SUPPORT_TLS=yes
 TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto
 TLS_INCLUDE=-I/usr/local/openssl/include/
 .endd
+.new
+.cindex "pkg-config" "OpenSSL"
+If you have &'pkg-config'& available, then instead you can just use:
+.code
+SUPPORT_TLS=yes
+USE_OPENSSL_PC=openssl
+.endd
+.wen
 .cindex "USE_GNUTLS"
 If GnuTLS is installed, you should set
 .code
@@ -1883,6 +1891,16 @@ USE_GNUTLS=yes
 TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt
 TLS_INCLUDE=-I/usr/gnu/include
 .endd
+.new
+.cindex "pkg-config" "GnuTLS"
+If you have &'pkg-config'& available, then instead you can just use:
+.code
+SUPPORT_TLS=yes
+USE_GNUTLS=yes
+USE_GNUTLS_PC=gnutls
+.endd
+.wen
+
 You do not need to set TLS_INCLUDE if the relevant directory is already
 specified in INCLUDE. Details of how to configure Exim to make use of TLS are
 given in chapter &<<CHAPTLS>>&.
@@ -2110,6 +2128,28 @@ files or libraries are required. When a lookup type is not included in the
 binary, attempts to configure Exim to use it cause run time configuration
 errors.
 
+.new
+.cindex "pkg-config" "lookups"
+.cindex "pkg-config" "authenticators"
+Many systems now use a tool called &'pkg-config'& to encapsulate information
+about how to compile against a library; Exim has some initial support for
+being able to use pkg-config for lookups and authenticators.  For any given
+makefile variable which starts &`LOOKUP_`& or &`AUTH_`&, you can add a new
+variable with the &`_PC`& suffix in the name and assign as the value the
+name of the package to be queried.  The results of querying via the
+&'pkg-config'& command will be added to the appropriate Makefile variables
+with &`+=`& directives, so your version of &'make'& will need to support that
+syntax.  For instance:
+.code
+LOOKUP_SQLITE=yes
+LOOKUP_SQLITE_PC=sqlite3
+AUTH_GSASL=yes
+AUTH_GSASL_PC=libgsasl
+AUTH_HEIMDAL_GSSAPI=yes
+AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi
+.endd
+.wen
+
 .cindex "Perl" "including support for"
 Exim can be linked with an embedded Perl interpreter, allowing Perl
 subroutines to be called during string expansion. To enable this facility,
@@ -6183,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.)
+.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_&"
-.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
@@ -7779,7 +7832,7 @@ pattern must be an appropriate query for the lookup type, as described in
 chapter &<<CHAPfdlookup>>&. For example:
 .code
 hold_domains = mysql;select domain from holdlist \
-  where domain = '$domain';
+  where domain = '${quote_mysql:$domain}';
 .endd
 In most cases, the data that is looked up is not used (so for an SQL query, for
 example, it doesn't matter what field you select). Exim is interested only in
@@ -8483,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.
 
+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"
@@ -9864,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.
 
+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"
@@ -9871,7 +9935,10 @@ zero.
 This condition turns a string holding a true or false representation into
 a boolean state.  It parses &"true"&, &"false"&, &"yes"& and &"no"&
 (case-insensitively); also positive integer numbers map to true if non-zero,
-false if zero.  Leading and trailing whitespace is ignored.
+false if zero.
+An empty string is treated as false.
+Leading and trailing whitespace is ignored;
+thus a string consisting only of whitespace is false.
 All other string values will result in expansion failure.
 
 When combined with ACL variables, this expansion condition will let you
@@ -10079,6 +10146,25 @@ string is lexically greater than the second string. For &%gt%& the comparison
 includes the case of letters, whereas for &%gti%& the comparison is
 case-independent.
 
+.new
+.vitem &*inlist&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&&
+       &*inlisti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
+.cindex "string" "comparison"
+.cindex "list" "iterative conditions"
+Both strings are expanded; the second string is treated as a list of simple
+strings; if the first string is a member of the second, then the condition
+is true.
+
+These are simpler to use versions of the more powerful &*forany*& condition.
+Examples, and the &*forany*& equivalents:
+.code
+${if inlist{needle}{foo:needle:bar}}
+  ${if forany{foo:needle:bar}{eq{$item}{needle}}}
+${if inlisti{Needle}{fOo:NeeDLE:bAr}}
+  ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}}
+.endd
+.wen
+
 .vitem &*isip&~{*&<&'string'&>&*}*&  &&&
        &*isip4&~{*&<&'string'&>&*}*& &&&
        &*isip6&~{*&<&'string'&>&*}*&
@@ -10189,10 +10275,12 @@ See &*match_local_part*&.
 
 .vitem &*match_ip&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
 .cindex "&%match_ip%& expansion condition"
+.new
 This condition matches an IP address to a list of IP address patterns. It must
 be followed by two argument strings. The first (after expansion) must be an IP
-address or an empty string. The second (after expansion) is a restricted host
+address or an empty string. The second (not expanded) is a restricted host
 list that can match only an IP address, not a host name. For example:
+.wen
 .code
 ${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}}
 .endd
@@ -10238,6 +10326,11 @@ just as easy to use the fact that a lookup is itself a condition, and write:
 .endd
 .endlist ilist
 
+.new
+Note that <&'string2'&> is not itself subject to string expansion, unless
+Exim was built with the EXPAND_LISTMATCH_RHS option.
+.wen
+
 Consult section &<<SECThoslispatip>>& for further details of these patterns.
 
 .vitem &*match_local_part&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
@@ -10265,6 +10358,11 @@ item can be used, as in all address lists, to cause subsequent items to
 have their local parts matched casefully. Domains are always matched
 caselessly.
 
+.new
+Note that <&'string2'&> is not itself subject to string expansion, unless
+Exim was built with the EXPAND_LISTMATCH_RHS option.
+.wen
+
 &*Note*&: Host lists are &'not'& supported in this way. This is because
 hosts have two identities: a name and an IP address, and it is not clear
 how to specify cleanly how such a test would work. However, IP addresses can be
@@ -10632,7 +10730,7 @@ number of lines in the message's body. See also &$message_linecount$&.
 .cindex "binary zero" "in message body"
 .vindex "&$body_zerocount$&"
 When a message is being received or delivered, this variable contains the
-number of binary zero bytes in the message's body.
+number of binary zero bytes (ASCII NULs) in the message's body.
 
 .vitem &$bounce_recipient$&
 .vindex "&$bounce_recipient$&"
@@ -11750,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'&.
 
+.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
@@ -11780,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.
 
+.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
@@ -13042,7 +13168,7 @@ section &<<SECTcallvercache>>& for details of the caching.
 This option defines the &"random"& local part that can be used as part of
 callout verification. The default value is
 .code
-$primary_host_name-$tod_epoch-testing
+$primary_hostname-$tod_epoch-testing
 .endd
 See section &<<CALLaddparcall>>& for details of how this value is used.
 
@@ -14225,16 +14351,12 @@ harm. This option overrides the &%pipe_as_creator%& option of the &(pipe)&
 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,
-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
@@ -14246,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
-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
-openssl_options = -all +microsoft_big_sslv3_buffer
+openssl_options = -all +microsoft_big_sslv3_buffer +dont_insert_empty_fragments
 .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"
@@ -15443,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.
 
+.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"
@@ -15475,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.
 
+.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"
@@ -22187,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
@@ -23362,15 +23571,29 @@ included by setting
 .code
 AUTH_CRAM_MD5=yes
 AUTH_CYRUS_SASL=yes
+.new
+AUTH_DOVECOT=yes
+AUTH_GSASL=yes
+AUTH_HEIMDAL_GSSAPI=yes
+.wen
 AUTH_PLAINTEXT=yes
 AUTH_SPA=yes
 .endd
 in &_Local/Makefile_&, respectively. The first of these supports the CRAM-MD5
 authentication mechanism (RFC 2195), and the second provides an interface to
-the Cyrus SASL authentication library. The third can be configured to support
+the Cyrus SASL authentication library.
+.new
+The third is an interface to Dovecot's authentication system, delegating the
+work via a socket interface.
+The fourth provides an interface to the GNU SASL authentication library, which
+provides mechanisms but typically not data sources.
+The fifth provides direct access to Heimdal GSSAPI, geared for Kerberos, but
+supporting setting a server keytab.
+The sixth can be configured to support
 the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism, which is
-not formally documented, but used by several MUAs. The fourth authenticator
+not formally documented, but used by several MUAs. The seventh authenticator
 supports Microsoft's &'Secure Password Authentication'& mechanism.
+.wen
 
 The authenticators are configured using the same syntax as other drivers (see
 section &<<SECTfordricon>>&). If no authenticators are required, no
@@ -23402,6 +23625,30 @@ The remainder of this chapter covers the generic options for the
 authenticators, followed by general discussion of the way authentication works
 in Exim.
 
+.new
+&*Beware:*& the meaning of &$auth1$&, &$auth2$&, ... varies on a per-driver and
+per-mechanism basis.  Please read carefully to determine which variables hold
+account labels such as usercodes and which hold passwords or other
+authenticating data.
+
+Note that some mechanisms support two different identifiers for accounts: the
+&'authentication id'& and the &'authorization id'&.  The contractions &'authn'&
+and &'authz'& are commonly encountered.  The American spelling is standard here.
+Conceptually, authentication data such as passwords are tied to the identifier
+used to authenticate; servers may have rules to permit one user to act as a
+second user, so that after login the session is treated as though that second
+user had logged in.  That second user is the &'authorization id'&.  A robust
+configuration might confirm that the &'authz'& field is empty or matches the
+&'authn'& field.  Often this is just ignored.  The &'authn'& can be considered
+as verified data, the &'authz'& as an unverified request which the server might
+choose to honour.
+
+A &'realm'& is a text string, typically a domain name, presented by a server
+to a client to help it select an account and credentials to use.  In some
+mechanisms, the client and server provably agree on the realm, but clients
+typically can not treat the realm as secure data to be blindly trusted.
+.wen
+
 
 
 .section "Generic options for authenticators" "SECID168"
@@ -23448,6 +23695,11 @@ This option must be set for a &%plaintext%& server authenticator, where it
 is used directly to control authentication. See section &<<SECTplainserver>>&
 for details.
 
+.new
+For the &(gsasl)& authenticator, this option is required for various
+mechanisms; see chapter &<<CHAPgsasl>>& for details.
+.wen
+
 For the other authenticators, &%server_condition%& can be used as an additional
 authentication or authorization mechanism that is applied after the other
 authenticator conditions succeed. If it is set, it is expanded when the
@@ -24052,6 +24304,20 @@ lookup_cram:
 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)"
@@ -24125,10 +24391,17 @@ be set in &_exim.conf_& in your SASL directory. If you are using GSSAPI for
 Kerberos, note that because of limitations in the GSSAPI interface,
 changing the server keytab might need to be communicated down to the Kerberos
 layer independently. The mechanism for doing so is dependent upon the Kerberos
-implementation. For example, for Heimdal, the environment variable KRB5_KTNAME
+implementation.
+.new
+For example, for older releases of Heimdal, the environment variable KRB5_KTNAME
 may be set to point to an alternative keytab file. Exim will pass this
 variable through from its own inherited environment when started as root or the
 Exim user. The keytab file needs to be readable by the Exim user.
+With newer releases of Heimdal, a setuid Exim may cause Heimdal to discard the
+environment variable.  In practice, for those releases, the Cyrus authenticator
+is not a suitable interface for GSSAPI (Kerberos) support.  Instead, consider
+the &(heimdal_gssapi)& authenticator, described in chapter &<<CHAPheimdalgss>>&
+.wen
 
 
 .section "Using cyrus_sasl as a server" "SECID178"
@@ -24159,8 +24432,10 @@ sasl:
   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.
+.wen
 
 
 .option server_service cyrus_sasl string &`smtp`&
@@ -24231,6 +24506,217 @@ who authenticated is placed in &$auth1$&.
 .ecindex IIDdcotauth2
 
 
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+.new
+.chapter "The gsasl authenticator" "CHAPgsasl"
+.scindex IIDgsaslauth1 "&(gsasl)& authenticator"
+.scindex IIDgsaslauth2 "authenticators" "&(gsasl)&"
+.cindex "authentication" "GNU SASL"
+.cindex "authentication" "SASL"
+.cindex "authentication" "EXTERNAL"
+.cindex "authentication" "ANONYMOUS"
+.cindex "authentication" "PLAIN"
+.cindex "authentication" "LOGIN"
+.cindex "authentication" "DIGEST-MD5"
+.cindex "authentication" "CRAM-MD5"
+.cindex "authentication" "SCRAM-SHA-1"
+The &(gsasl)& authenticator provides server integration for the GNU SASL
+library and the mechanisms it provides.  This is new as of the 4.78 release
+and there are a few areas where the library does not let Exim smoothly
+scale to handle future authentication mechanisms, so no guarantee can be
+made that any particular new authentication mechanism will be supported
+without code changes in Exim.
+
+
+.option server_channelbinding gsasl bool false
+Some authentication mechanisms are able to use external context at both ends
+of the session to bind the authentication to that context, and fail the
+authentication process if that context differs.  Specifically, some TLS
+ciphersuites can provide identifying information about the cryptographic
+context.
+
+This means that certificate identity and verification becomes a non-issue,
+as a man-in-the-middle attack will cause the correct client and server to
+see different identifiers and authentication will fail.
+
+This is currently only supported when using the GnuTLS library.  This is
+only usable by mechanisms which support "channel binding"; at time of
+writing, that's the SCRAM family.
+
+This defaults off to ensure smooth upgrade across Exim releases, in case
+this option causes some clients to start failing.  Some future release
+of Exim may switch the default to be true.
+
+
+.option server_hostname gsasl string&!! "see below"
+This option selects the hostname that is used when communicating with the
+library. The default value is &`$primary_hostname`&.
+Some mechanisms will use this data.
+
+
+.option server_mech gsasl string "see below"
+This option selects the authentication mechanism this driver should use. The
+default is the value of the generic &%public_name%& option. This option allows
+you to use a different underlying mechanism from the advertised name. For
+example:
+.code
+sasl:
+  driver = gsasl
+  public_name = X-ANYTHING
+  server_mech = CRAM-MD5
+  server_set_id = $auth1
+.endd
+
+
+.option server_password gsasl string&!! unset
+Various mechanisms need access to the cleartext password on the server, so
+that proof-of-possession can be demonstrated on the wire, without sending
+the password itself.
+
+The data available for lookup varies per mechanism.
+In all cases, &$auth1$& is set to the &'authentication id'&.
+The &$auth2$& variable will always be the &'authorization id'& (&'authz'&)
+if available, else the empty string.
+The &$auth3$& variable will always be the &'realm'& if available,
+else the empty string.
+
+A forced failure will cause authentication to defer.
+
+If using this option, it may make sense to set the &%server_condition%&
+option to be simply "true".
+
+
+.option server_realm gsasl string&!! unset
+This specifies the SASL realm that the server claims to be in.
+Some mechanisms will use this data.
+
+
+.option server_scram_iter gsasl string&!! unset
+This option provides data for the SCRAM family of mechanisms.
+&$auth1$& is not available at evaluation time.
+(This may change, as we receive feedback on use)
+
+
+.option server_scram_salt gsasl string&!! unset
+This option provides data for the SCRAM family of mechanisms.
+&$auth1$& is not available at evaluation time.
+(This may change, as we receive feedback on use)
+
+
+.option server_service gsasl string &`smtp`&
+This is the SASL service that the server claims to implement.
+Some mechanisms will use this data.
+
+
+.section "&(gsasl)& auth variables" "SECTgsaslauthvar"
+.vindex "&$auth1$&, &$auth2$&, etc"
+These may be set when evaluating specific options, as detailed above.
+They will also be set when evaluating &%server_condition%&.
+
+Unless otherwise stated below, the &(gsasl)& integration will use the following
+meanings for these variables:
+
+.ilist
+.vindex "&$auth1$&"
+&$auth1$&: the &'authentication id'&
+.next
+.vindex "&$auth2$&"
+&$auth2$&: the &'authorization id'&
+.next
+.vindex "&$auth3$&"
+&$auth3$&: the &'realm'&
+.endlist
+
+On a per-mechanism basis:
+
+.ilist
+.cindex "authentication" "EXTERNAL"
+EXTERNAL: only &$auth1$& is set, to the possibly empty &'authorization id'&;
+the &%server_condition%& option must be present.
+.next
+.cindex "authentication" "ANONYMOUS"
+ANONYMOUS: only &$auth1$& is set, to the possibly empty &'anonymous token'&;
+the &%server_condition%& option must be present.
+.next
+.cindex "authentication" "GSSAPI"
+GSSAPI: &$auth1$& will be set to the &'GSSAPI Display Name'&;
+&$auth2$& will be set to the &'authorization id'&,
+the &%server_condition%& option must be present.
+.endlist
+
+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".
+
+
+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
+
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
+.new
+.chapter "The heimdal_gssapi authenticator" "CHAPheimdalgss"
+.scindex IIDheimdalgssauth1 "&(heimdal_gssapi)& authenticator"
+.scindex IIDheimdalgssauth2 "authenticators" "&(heimdal_gssapi)&"
+.cindex "authentication" "GSSAPI"
+.cindex "authentication" "Kerberos"
+The &(heimdal_gssapi)& authenticator provides server integration for the
+Heimdal GSSAPI/Kerberos library, permitting Exim to set a keytab pathname
+reliably.
+
+.option server_hostname heimdal_gssapi string&!! "see below"
+This option selects the hostname that is used, with &%server_service%&,
+for constructing the GSS server name, as a &'GSS_C_NT_HOSTBASED_SERVICE'&
+identifier.  The default value is &`$primary_hostname`&.
+
+.option server_keytab heimdal_gssapi string&!! unset
+If set, then Heimdal will not use the system default keytab (typically
+&_/etc/krb5.keytab_&) but instead the pathname given in this option.
+The value should be a pathname, with no &"file:"& prefix.
+
+.option server_service heimdal_gssapi string&!! "smtp"
+This option specifies the service identifier used, in conjunction with
+&%server_hostname%&, for building the identifer for finding credentials
+from the keytab.
+
+
+.section "&(heimdal_gssapi)& auth variables" "SECTheimdalgssauthvar"
+Beware that these variables will typically include a realm, thus will appear
+to be roughly like an email address already.  The &'authzid'& in &$auth2$& is
+not verified, so a malicious client can set it to anything.
+
+The &$auth1$& field should be safely trustable as a value from the Key
+Distribution Center.  Note that these are not quite email addresses.
+Each identifier is for a role, and so the left-hand-side may include a
+role suffix.  For instance, &"joe/admin@EXAMPLE.ORG"&.
+
+.vindex "&$auth1$&, &$auth2$&, etc"
+.ilist
+.vindex "&$auth1$&"
+&$auth1$&: the &'authentication id'&, set to the GSS Display Name.
+.next
+.vindex "&$auth2$&"
+&$auth2$&: the &'authorization id'&, sent within SASL encapsulation after
+authentication.  If that was empty, this will also be set to the
+GSS Display Name.
+.endlist
+
+.wen
+
 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////
 
@@ -24595,8 +25081,14 @@ DHE_DSS). The default list contains RSA, DHE_DSS, DHE_RSA.
 For &%gnutls_require_mac%&, the recognized names are SHA (synonym SHA1), and
 MD5. The default list contains SHA, MD5.
 
-For &%gnutls_require_protocols%&, the recognized names are TLS1 and SSL3.
-The default list contains TLS1, SSL3.
+.new
+For &%gnutls_require_protocols%&, the recognized names are TLS1.2, TLS1.1,
+TLS1.0, (TLS1) and SSL3.
+The default list contains TLS1.2, TLS1.1, TLS1.0, SSL3.
+TLS1 is an alias for TLS1.0, for backwards compatibility.
+For sufficiently old versions of the GnuTLS library, TLS1.2 or TLS1.1 might
+not be supported and will not be recognised by Exim.
+.wen
 
 In a server, the order of items in these lists is unimportant. The server
 advertises the availability of all the relevant cipher suites. However, in a
@@ -27739,7 +28231,7 @@ check for a &"random"& local part at the same domain. The local part is not
 really random &-- it is defined by the expansion of the option
 &%callout_random_local_part%&, which defaults to
 .code
-$primary_host_name-$tod_epoch-testing
+$primary_hostname-$tod_epoch-testing
 .endd
 The idea here is to try to determine whether the remote host accepts all local
 parts without checking. If it does, there is no point in doing callouts for
@@ -32688,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_sni                    `&  TLS SNI on <= lines
 &` unknown_in_list            `&  DNS lookup failed in list match
 
 &` all                        `&  all of the above
@@ -32983,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
+.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.
@@ -34999,7 +35498,7 @@ integer size comparisons against this value.
 A colon-separated list of names of headers included in the signature.
 .vitem &%$dkim_key_testing%&
 "1" if the key record has the "testing" flag set, "0" if not.
-.vitem &%$dkim_key_nosubdomaining%&
+.vitem &%$nosubdomains%&
 "1" if the key record forbids subdomaining, "0" otherwise.
 .vitem &%$dkim_key_srvtype%&
 Service type (tag s=) from the key record. Defaults to "*" if not specified