Docs: rewrite description of 'leaky' ratelimit. Bug 1298

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 6353e29fb8f4edb1ddf4ee7df08367992fa6c1a8..b1cc46862743cda0f8fc56ebf931a7655d6b5ad2 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -45,7 +45,7 @@
 . Update the Copyright year (only) when changing content.
 . /////////////////////////////////////////////////////////////////////////////
 
 . Update the Copyright year (only) when changing content.
 . /////////////////////////////////////////////////////////////////////////////
 

-.set previousversion "4.90"
+.set previousversion "4.91"

 .include ./local_params
 
 .set ACL "access control lists (ACLs)"
 .include ./local_params
 
 .set ACL "access control lists (ACLs)"


@@ -448,12 +448,9 @@ available in other formats (HTML, PostScript, PDF, and Texinfo). Section
 .section "FTP and web sites" "SECID2"
 .cindex "web site"
 .cindex "FTP site"
 .section "FTP and web sites" "SECID2"
 .cindex "web site"
 .cindex "FTP site"

-The primary site for Exim source distributions is currently the University of
-Cambridge's FTP site, whose contents are described in &'Where to find the Exim
-distribution'& below. In addition, there is a web site and an FTP site at
-&%exim.org%&. These are now also hosted at the University of Cambridge. The
-&%exim.org%& site was previously hosted for a number of years by Energis
-Squared, formerly Planet Online Ltd, whose support I gratefully acknowledge.
+The primary site for Exim source distributions is the &%exim.org%& FTP site,
+available over HTTPS, HTTP and FTP.  These services, and the &%exim.org%&
+website, are hosted at the University of Cambridge.

 
 .cindex "wiki"
 .cindex "FAQ"
 
 .cindex "wiki"
 .cindex "FAQ"


@@ -462,12 +459,14 @@ differently formatted versions of the documentation. A recent addition to the
 online information is the Exim wiki (&url(http://wiki.exim.org)),
 which contains what used to be a separate FAQ, as well as various other
 examples, tips, and know-how that have been contributed by Exim users.
 online information is the Exim wiki (&url(http://wiki.exim.org)),
 which contains what used to be a separate FAQ, as well as various other
 examples, tips, and know-how that have been contributed by Exim users.

+The wiki site should always redirect to the correct place, which is currently
+provided by GitHub, and is open to editing by anyone with a GitHub account.

 
 .cindex Bugzilla
 An Exim Bugzilla exists at &url(https://bugs.exim.org). You can use
 this to report bugs, and also to add items to the wish list. Please search
 first to check that you are not duplicating a previous entry.
 
 .cindex Bugzilla
 An Exim Bugzilla exists at &url(https://bugs.exim.org). You can use
 this to report bugs, and also to add items to the wish list. Please search
 first to check that you are not duplicating a previous entry.

-
+Please do not ask for configuration help in the bug-tracker.

 
 
 .section "Mailing lists" "SECID3"
 
 
 .section "Mailing lists" "SECID3"


@@ -505,26 +504,41 @@ message to the &'exim-dev'& mailing list and have it discussed.
 
 .section "Where to find the Exim distribution" "SECTavail"
 .cindex "FTP site"
 
 .section "Where to find the Exim distribution" "SECTavail"
 .cindex "FTP site"

+.cindex "HTTPS download site"

 .cindex "distribution" "ftp site"
 .cindex "distribution" "ftp site"

-The master ftp site for the Exim distribution is
+.cindex "distribution" "https site"
+The master distribution site for the Exim distribution is

 .display
 .display

-&*ftp://ftp.exim.org/pub/exim*&
+&*https://downloads.exim.org/*&

 .endd
 .endd

-The file references that follow are relative to the &_exim_& directories at
-these sites. There are now quite a number of independent mirror sites around
+The service is available over HTTPS, HTTP and FTP.
+We encourage people to migrate to HTTPS.
+
+The content served at &'https://downloads.exim.org/'& is identical to the
+content served at &'https://ftp.exim.org/pub/exim'& and
+&'ftp://ftp.exim.org/pub/exim'&.
+
+If accessing via a hostname containing &'ftp'&, then the file references that
+follow are relative to the &_exim_& directories at these sites.
+If accessing via the hostname &'downloads'& then the subdirectories described
+here are top-level directories.
+
+There are now quite a number of independent mirror sites around

 the world. Those that I know about are listed in the file called &_Mirrors_&.
 
 the world. Those that I know about are listed in the file called &_Mirrors_&.
 

-Within the &_exim_& directory there are subdirectories called &_exim3_& (for
+Within the top exim directory there are subdirectories called &_exim3_& (for

 previous Exim 3 distributions), &_exim4_& (for the latest Exim 4
 distributions), and &_Testing_& for testing versions. In the &_exim4_&
 subdirectory, the current release can always be found in files called
 .display
 previous Exim 3 distributions), &_exim4_& (for the latest Exim 4
 distributions), and &_Testing_& for testing versions. In the &_exim4_&
 subdirectory, the current release can always be found in files called
 .display

+&_exim-n.nn.tar.xz_&

 &_exim-n.nn.tar.gz_&
 &_exim-n.nn.tar.bz2_&
 .endd
 &_exim-n.nn.tar.gz_&
 &_exim-n.nn.tar.bz2_&
 .endd

-where &'n.nn'& is the highest such version number in the directory. The two
+where &'n.nn'& is the highest such version number in the directory. The three

 files contain identical data; the only difference is the type of compression.
 files contain identical data; the only difference is the type of compression.

-The &_.bz2_& file is usually a lot smaller than the &_.gz_& file.
+The &_.xz_& file is usually the smallest, while the &_.gz_& file is the
+most portable to old systems.

 
 .cindex "distribution" "signing details"
 .cindex "distribution" "public key"
 
 .cindex "distribution" "signing details"
 .cindex "distribution" "public key"


@@ -538,17 +552,14 @@ PGP key, a version of which can be found in the release directory in the file
 &_nigel-pubkey.asc_&.  All keys used will be available in public keyserver pools,
 such as &'pool.sks-keyservers.net'&.
 
 &_nigel-pubkey.asc_&.  All keys used will be available in public keyserver pools,
 such as &'pool.sks-keyservers.net'&.
 

-At time of last update, releases were being made by Phil Pennock and signed with
-key &'0x403043153903637F'&, although that key is expected to be replaced in 2013.
-A trust path from Nigel's key to Phil's can be observed at
-&url(https://www.security.spodhuis.org/exim-trustpath).
-
-Releases have also been authorized to be performed by Todd Lyons who signs with
-key &'0xC4F4F94804D29EBA'&. A direct trust path exists between previous RE Phil
-Pennock and Todd Lyons through a common associate.
+At time of last update, releases were being made by Jeremy Harris and signed
+with key &'0xBCE58C8CE41F32DF'&.  Other recent keys used for signing are those
+of Heiko Schlittermann, &'0x26101B62F69376CE'&,
+and of Phil Pennock, &'0x4D1E900E14C1CC04'&.

 
 The signatures for the tar bundles are in:
 .display
 
 The signatures for the tar bundles are in:
 .display

+&_exim-n.nn.tar.xz.asc_&

 &_exim-n.nn.tar.gz.asc_&
 &_exim-n.nn.tar.bz2.asc_&
 .endd
 &_exim-n.nn.tar.gz.asc_&
 &_exim-n.nn.tar.bz2.asc_&
 .endd


@@ -567,7 +578,7 @@ inside the &_exim4_& directory of the FTP site:
 &_exim-texinfo-n.nn.tar.gz_&
 .endd
 These tar files contain only the &_doc_& directory, not the complete
 &_exim-texinfo-n.nn.tar.gz_&
 .endd
 These tar files contain only the &_doc_& directory, not the complete

-distribution, and are also available in &_.bz2_& as well as &_.gz_& forms.
+distribution, and are also available in &_.bz2_& and &_.xz_& forms.

 
 
 .section "Limitations" "SECID6"
 
 
 .section "Limitations" "SECID6"


@@ -3162,10 +3173,8 @@ If invoked by an admin user, then &%macro%&, &%macro_list%& and &%macros%&
 are available, similarly to the drivers.  Because macros are sometimes used
 for storing passwords, this option is restricted.
 The output format is one item per line.
 are available, similarly to the drivers.  Because macros are sometimes used
 for storing passwords, this option is restricted.
 The output format is one item per line.

-.new

 For the "-bP macro <name>" form, if no such macro is found
 the exit status will be nonzero.
 For the "-bP macro <name>" form, if no such macro is found
 the exit status will be nonzero.

-.wen

 
 .vitem &%-bp%&
 .oindex "&%-bp%&"
 
 .vitem &%-bp%&
 .oindex "&%-bp%&"


@@ -3838,7 +3847,7 @@ alternate queue is used, named by the following argument.
 .vitem &%-MCK%&
 .oindex "&%-MCK%&"
 This option is not intended for use by external callers. It is used internally
 .vitem &%-MCK%&
 .oindex "&%-MCK%&"
 This option is not intended for use by external callers. It is used internally

-by Exim in conjunction with the &%-MC%& option. It signifies that an
+by Exim in conjunction with the &%-MC%& option. It signifies that a

 remote host supports the ESMTP &_CHUNKING_& extension.
 
 .vitem &%-MCP%&
 remote host supports the ESMTP &_CHUNKING_& extension.
 
 .vitem &%-MCP%&


@@ -7839,18 +7848,16 @@ ${lookup redis{set keyname ${quote_redis:objvalue plus}}}
 ${lookup redis{get keyname}}
 .endd
 
 ${lookup redis{get keyname}}
 .endd
 

-.new

 As of release 4.91, "lightweight" support for Redis Cluster is available.
 Requires &%redis_servers%& list to contain all the servers in the cluster, all
 of which must be reachable from the running exim instance. If the cluster has
 master/slave replication, the list must contain all the master and slave
 servers.
 
 As of release 4.91, "lightweight" support for Redis Cluster is available.
 Requires &%redis_servers%& list to contain all the servers in the cluster, all
 of which must be reachable from the running exim instance. If the cluster has
 master/slave replication, the list must contain all the master and slave
 servers.
 

-When the Redis Cluster returns a "MOVED" response to a query, exim does not
+When the Redis Cluster returns a "MOVED" response to a query, Exim does not

 immediately follow the redirection but treats the response as a DEFER, moving on
 to the next server in the &%redis_servers%& list until the correct server is
 reached.
 immediately follow the redirection but treats the response as a DEFER, moving on
 to the next server in the &%redis_servers%& list until the correct server is
 reached.

-.wen

 
 .ecindex IIDfidalo1
 .ecindex IIDfidalo2
 
 .ecindex IIDfidalo1
 .ecindex IIDfidalo2


@@ -9150,7 +9157,6 @@ the expansion result is an empty string.
 If the ACL returns defer the result is a forced-fail.  Otherwise the expansion fails.
 
 
 If the ACL returns defer the result is a forced-fail.  Otherwise the expansion fails.
 
 

-.new

 .vitem "&*${authresults{*&<&'authserv-id'&>&*}}*&"
 .cindex authentication "results header"
 .cindex headers "authentication-results:"
 .vitem "&*${authresults{*&<&'authserv-id'&>&*}}*&"
 .cindex authentication "results header"
 .cindex headers "authentication-results:"


@@ -9159,8 +9165,8 @@ This item returns a string suitable for insertion as an
 &'Authentication-Results"'&
 header line.
 The given <&'authserv-id'&> is included in the result; typically this
 &'Authentication-Results"'&
 header line.
 The given <&'authserv-id'&> is included in the result; typically this

-will ba a domain name identifying the system performing the authentications.
-Methods that may be present in the result include:
+will be a domain name identifying the system performing the authentications.
+Methods that might be present in the result include:

 .code
 none
 iprev
 .code
 none
 iprev


@@ -9173,8 +9179,7 @@ Example use (as an ACL modifier):
 .code
       add_header = :at_start:${authresults {$primary_hostname}}
 .endd
 .code
       add_header = :at_start:${authresults {$primary_hostname}}
 .endd

-This is safe even if no authentication reselts are available.
-.wen
+This is safe even if no authentication results are available.

 
 
 .vitem "&*${certextract{*&<&'field'&>&*}{*&<&'certificate'&>&*}&&&
 
 
 .vitem "&*${certextract{*&<&'field'&>&*}{*&<&'certificate'&>&*}&&&


@@ -10690,10 +10695,8 @@ with 256 being the default.
 
 The &%sha3%& expansion item is only supported if Exim has been
 compiled with GnuTLS 3.5.0 or later,
 
 The &%sha3%& expansion item is only supported if Exim has been
 compiled with GnuTLS 3.5.0 or later,

-.new

 or OpenSSL 1.1.1 or later.
 The macro "_CRYPTO_HASH_SHA3" will be defined if it is supported.
 or OpenSSL 1.1.1 or later.
 The macro "_CRYPTO_HASH_SHA3" will be defined if it is supported.

-.wen

 
 
 .vitem &*${stat:*&<&'string'&>&*}*&
 
 
 .vitem &*${stat:*&<&'string'&>&*}*&


@@ -11600,10 +11603,8 @@ When a message is submitted locally (that is, not over a TCP connection)
 the value of &$authenticated_id$& is normally the login name of the calling
 process. However, a trusted user can override this by means of the &%-oMai%&
 command line option.
 the value of &$authenticated_id$& is normally the login name of the calling
 process. However, a trusted user can override this by means of the &%-oMai%&
 command line option.

-.new

 This second case also sets up inforamtion used by the
 &$authresults$& expansion item.
 This second case also sets up inforamtion used by the
 &$authresults$& expansion item.

-.wen

 
 .vitem &$authenticated_fail_id$&
 .cindex "authentication" "fail" "id"
 
 .vitem &$authenticated_fail_id$&
 .cindex "authentication" "fail" "id"


@@ -11943,11 +11944,9 @@ lookup succeeds, but there is a lookup problem such as a timeout when checking
 the result, the name is not accepted, and &$host_lookup_deferred$& is set to
 &"1"&. See also &$sender_host_name$&.
 
 the result, the name is not accepted, and &$host_lookup_deferred$& is set to
 &"1"&. See also &$sender_host_name$&.
 

-.new

 .cindex authentication "expansion item"
 Performing these checks sets up information used by the
 &$authresults$& expansion item.
 .cindex authentication "expansion item"
 Performing these checks sets up information used by the
 &$authresults$& expansion item.

-.wen

 
 
 .vitem &$host_lookup_failed$&
 
 
 .vitem &$host_lookup_failed$&


@@ -12901,7 +12900,6 @@ A number of variables whose names start with &$spam$& are available when Exim
 is compiled with the content-scanning extension. For details, see section
 &<<SECTscanspamass>>&.
 
 is compiled with the content-scanning extension. For details, see section
 &<<SECTscanspamass>>&.
 

-.new

 .vitem &$spf_header_comment$& &&&
        &$spf_received$& &&&
        &$spf_result$& &&&
 .vitem &$spf_header_comment$& &&&
        &$spf_received$& &&&
        &$spf_result$& &&&


@@ -12909,7 +12907,6 @@ is compiled with the content-scanning extension. For details, see section
        &$spf_smtp_comment$&
 These variables are only available if Exim is built with SPF support.
 For details see section &<<SECSPF>>&.
        &$spf_smtp_comment$&
 These variables are only available if Exim is built with SPF support.
 For details see section &<<SECSPF>>&.

-.wen

 
 .vitem &$spool_directory$&
 .vindex "&$spool_directory$&"
 
 .vitem &$spool_directory$&
 .vindex "&$spool_directory$&"


@@ -12972,7 +12969,8 @@ It is only useful as the argument of a
 &%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
 or a &%def%& condition.
 
 &%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
 or a &%def%& condition.
 

-&*Note*&: Under current versions of OpenSSL, when a list of more than one
+&*Note*&: Under versions of OpenSSL preceding 1.1.1,
+when a list of more than one

 file is used for &%tls_certificate%&, this variable is not reliable.
 
 .vitem &$tls_in_peercert$&
 file is used for &%tls_certificate%&, this variable is not reliable.
 
 .vitem &$tls_in_peercert$&


@@ -16906,11 +16904,9 @@ See section &<<SECTscanspamass>>& for more details.
 
 
 
 
 
 

-.new

 .option spf_guess main string "v=spf1 a/24 mx/24 ptr ?all"
 This option is available when Exim is compiled with SPF support.
 See section &<<SECSPF>>& for more details.
 .option spf_guess main string "v=spf1 a/24 mx/24 ptr ?all"
 This option is available when Exim is compiled with SPF support.
 See section &<<SECSPF>>& for more details.

-.wen

 
 
 
 
 
 


@@ -16966,10 +16962,10 @@ tests of Exim without using the standard spool.
 
 .option spool_wireformat main boolean false
 .cindex "spool directory" "file formats"
 
 .option spool_wireformat main boolean false
 .cindex "spool directory" "file formats"

-If this option is set, Exim may for some messages use an alternate format
+If this option is set, Exim may for some messages use an alternative format

 for data-files in the spool which matches the wire format.
 Doing this permits more efficient message reception and transmission.
 for data-files in the spool which matches the wire format.
 Doing this permits more efficient message reception and transmission.

-Currently it is only done for messages received using the EMSTP CHUNKING
+Currently it is only done for messages received using the ESMTP CHUNKING

 option.
 
 The following variables will not have useful values:
 option.
 
 The following variables will not have useful values:


@@ -16982,7 +16978,7 @@ $body_zerocount
 Users of the local_scan() API (see &<<CHAPlocalscan>>&),
 and any external programs which are passed a reference to a message data file
 (except via the &"regex"&, &"malware"& or &"spam"&) ACL conditions)
 Users of the local_scan() API (see &<<CHAPlocalscan>>&),
 and any external programs which are passed a reference to a message data file
 (except via the &"regex"&, &"malware"& or &"spam"&) ACL conditions)

-will need to be aware of the potential different format.
+will need to be aware of the different formats potentially available.

 
 Using any of the ACL conditions noted will negate the reception benefit
 (as a Unix-mbox-format file is constructed for them).
 
 Using any of the ACL conditions noted will negate the reception benefit
 (as a Unix-mbox-format file is constructed for them).


@@ -17212,7 +17208,8 @@ option in the relevant &(smtp)& transport.
 &*Note*&: If you use filenames based on IP addresses, change the list
 separator in the usual way to avoid confusion under IPv6.
 
 &*Note*&: If you use filenames based on IP addresses, change the list
 separator in the usual way to avoid confusion under IPv6.
 

-&*Note*&: Under current versions of OpenSSL, when a list of more than one
+&*Note*&: Under versions of OpenSSL preceding 1.1.1,
+when a list of more than one

 file is used, the &$tls_in_ourcert$& variable is unreliable.
 
 &*Note*&: OCSP stapling is not usable under OpenSSL
 file is used, the &$tls_in_ourcert$& variable is unreliable.
 
 &*Note*&: OCSP stapling is not usable under OpenSSL


@@ -17232,13 +17229,11 @@ generated for every connection.
 This option specifies a certificate revocation list. The expanded value must
 be the name of a file that contains CRLs in PEM format.
 
 This option specifies a certificate revocation list. The expanded value must
 be the name of a file that contains CRLs in PEM format.
 

-.new

 Under OpenSSL the option can specify a directory with CRL files.
 
 &*Note:*& Under OpenSSL the option must, if given, supply a CRL
 for each signing element of the certificate chain (i.e. all but the leaf).
 For the file variant this can be multiple PEM blocks in the one file.
 Under OpenSSL the option can specify a directory with CRL files.
 
 &*Note:*& Under OpenSSL the option must, if given, supply a CRL
 for each signing element of the certificate chain (i.e. all but the leaf).
 For the file variant this can be multiple PEM blocks in the one file.

-.wen

 
 See &<<SECTtlssni>>& for discussion of when this option might be re-expanded.
 
 
 See &<<SECTtlssni>>& for discussion of when this option might be re-expanded.
 


@@ -17365,11 +17360,9 @@ Certificate Authority.
 
 Usable for GnuTLS 3.4.4 or 3.3.17 or OpenSSL 1.1.0 (or later).
 
 
 Usable for GnuTLS 3.4.4 or 3.3.17 or OpenSSL 1.1.0 (or later).
 

-.new

 For GnuTLS 3.5.6 or later the expanded value of this option can be a list
 of files, to match a list given for the &%tls_certificate%& option.
 The ordering of the two lists must match.
 For GnuTLS 3.5.6 or later the expanded value of this option can be a list
 of files, to match a list given for the &%tls_certificate%& option.
 The ordering of the two lists must match.

-.wen

 
 
 .option tls_on_connect_ports main "string list" unset
 
 
 .option tls_on_connect_ports main "string list" unset


@@ -18832,9 +18825,7 @@ records.
 MX records of equal priority are sorted by Exim into a random order. Exim then
 looks for address records for the host names obtained from MX or SRV records.
 When a host has more than one IP address, they are sorted into a random order,
 MX records of equal priority are sorted by Exim into a random order. Exim then
 looks for address records for the host names obtained from MX or SRV records.
 When a host has more than one IP address, they are sorted into a random order,

-.new

 except that IPv6 addresses are sorted before IPv4 addresses. If all the
 except that IPv6 addresses are sorted before IPv4 addresses. If all the

-.wen

 IP addresses found are discarded by a setting of the &%ignore_target_hosts%&
 generic option, the router declines.
 
 IP addresses found are discarded by a setting of the &%ignore_target_hosts%&
 generic option, the router declines.
 


@@ -18967,7 +18958,6 @@ However, it will result in any message with mistyped domains
 also being queued.
 
 
 also being queued.
 
 

-.new

 .option ipv4_only "string&!!" unset
 .cindex IPv6 disabling
 .cindex DNS "IPv6 disabling"
 .option ipv4_only "string&!!" unset
 .cindex IPv6 disabling
 .cindex DNS "IPv6 disabling"


@@ -18983,7 +18973,6 @@ The string is expanded, and if the result is anything but a forced failure,
 or an empty string, or one of the strings “0” or “no” or “false”
 (checked without regard to the case of the letters),
 A records are sorted before AAAA records (inverting the default).
 or an empty string, or one of the strings “0” or “no” or “false”
 (checked without regard to the case of the letters),
 A records are sorted before AAAA records (inverting the default).

-.wen

 
 .option mx_domains dnslookup "domain list&!!" unset
 .cindex "MX record" "required to exist"
 
 .option mx_domains dnslookup "domain list&!!" unset
 .cindex "MX record" "required to exist"


@@ -19610,12 +19599,10 @@ also look in &_/etc/hosts_& or other sources of information.
 &%bydns%&: look up address records for the hosts directly in the DNS; fail if
 no address records are found. If there is a temporary DNS error (such as a
 timeout), delivery is deferred.
 &%bydns%&: look up address records for the hosts directly in the DNS; fail if
 no address records are found. If there is a temporary DNS error (such as a
 timeout), delivery is deferred.

-.new

 .next
 &%ipv4_only%&: in direct DNS lookups, look up only A records.
 .next
 &%ipv4_prefer%&: in direct DNS lookups, sort A records before AAAA records.
 .next
 &%ipv4_only%&: in direct DNS lookups, look up only A records.
 .next
 &%ipv4_prefer%&: in direct DNS lookups, sort A records before AAAA records.

-.wen

 .endlist
 
 For example:
 .endlist
 
 For example:


@@ -23941,7 +23928,6 @@ For testing purposes, this value can be overridden by the &%-oB%& command line
 option.
 
 
 option.
 
 

-.new

 .option dane_require_tls_ciphers smtp string&!! unset
 .cindex "TLS" "requiring specific ciphers for DANE"
 .cindex "cipher" "requiring specific"
 .option dane_require_tls_ciphers smtp string&!! unset
 .cindex "TLS" "requiring specific ciphers for DANE"
 .cindex "cipher" "requiring specific"


@@ -23956,7 +23942,6 @@ TLS cipherlist configuration stronger will increase security, rather than
 counter-intuitively decreasing it.
 If the option expands to be empty or is forced to fail, then it will
 be treated as unset and &%tls_require_ciphers%& will be used instead.
 counter-intuitively decreasing it.
 If the option expands to be empty or is forced to fail, then it will
 be treated as unset and &%tls_require_ciphers%& will be used instead.

-.wen

 
 
 .option data_timeout smtp time 5m
 
 
 .option data_timeout smtp time 5m


@@ -24280,7 +24265,6 @@ Exim will request a Certificate Status on a
 TLS session for any host that matches this list.
 &%tls_verify_certificates%& should also be set for the transport.
 
 TLS session for any host that matches this list.
 &%tls_verify_certificates%& should also be set for the transport.
 

-.new

 .option hosts_require_dane smtp "host list&!!" unset
 .cindex DANE "transport options"
 .cindex DANE "requiring for certain servers"
 .option hosts_require_dane smtp "host list&!!" unset
 .cindex DANE "transport options"
 .cindex DANE "requiring for certain servers"


@@ -24289,7 +24273,6 @@ TLSA record is present for any host matching the list,
 and that a DANE-verified TLS connection is made.
 There will be no fallback to in-clear communication.
 See section &<<SECDANE>>&.
 and that a DANE-verified TLS connection is made.
 There will be no fallback to in-clear communication.
 See section &<<SECDANE>>&.

-.wen

 
 .option hosts_require_ocsp smtp "host list&!!" unset
 .cindex "TLS" "requiring for certain servers"
 
 .option hosts_require_ocsp smtp "host list&!!" unset
 .cindex "TLS" "requiring for certain servers"


@@ -24320,7 +24303,6 @@ This option provides a list of servers to which, provided they announce
 CHUNKING support, Exim will attempt to use BDAT commands rather than DATA.
 BDAT will not be used in conjunction with a transport filter.
 
 CHUNKING support, Exim will attempt to use BDAT commands rather than DATA.
 BDAT will not be used in conjunction with a transport filter.
 

-.new

 .option hosts_try_dane smtp "host list&!!" unset
 .cindex DANE "transport options"
 .cindex DANE "attempting for certain servers"
 .option hosts_try_dane smtp "host list&!!" unset
 .cindex DANE "transport options"
 .cindex DANE "attempting for certain servers"


@@ -24330,7 +24312,6 @@ If found and verified by DNSSEC,
 a DANE-verified TLS connection is made to that host;
 there will be no fallback to in-clear communication.
 See section &<<SECDANE>>&.
 a DANE-verified TLS connection is made to that host;
 there will be no fallback to in-clear communication.
 See section &<<SECDANE>>&.

-.wen

 
 .option hosts_try_fastopen smtp "host list&!!" unset
 .cindex "fast open, TCP" "enabling, in client"
 
 .option hosts_try_fastopen smtp "host list&!!" unset
 .cindex "fast open, TCP" "enabling, in client"


@@ -26137,11 +26118,9 @@ public name) of the authenticator driver that successfully authenticated the
 client from which the message was received. This variable is empty if there was
 no successful authentication.
 
 client from which the message was received. This variable is empty if there was
 no successful authentication.
 

-.new

 .cindex authentication "expansion item"
 Successful authentication sets up information used by the
 &$authresults$& expansion item.
 .cindex authentication "expansion item"
 Successful authentication sets up information used by the
 &$authresults$& expansion item.

-.wen

 
 
 
 
 
 


@@ -26235,8 +26214,8 @@ deliver the message unauthenticated.
 
 Note that the hostlist test for whether to do authentication can be
 confused if name-IP lookups change between the time the peer is decided
 
 Note that the hostlist test for whether to do authentication can be
 confused if name-IP lookups change between the time the peer is decided

-on and the transport running.  For example, with a manualroute
-router given a host name, and DNS "round-robin" use by that name: if
+upon and the time that the transport runs.  For example, with a manualroute
+router given a host name, and with DNS "round-robin" used by that name: if

 the local resolver cache times out between the router and the transport
 running, the transport may get an IP for the name for its authentication
 check which does not match the connection peer IP.
 the local resolver cache times out between the router and the transport
 running, the transport may get an IP for the name for its authentication
 check which does not match the connection peer IP.


@@ -27229,7 +27208,7 @@ The history of port numbers for TLS in SMTP is a little messy and has been
 contentious.  As of RFC 8314, the common practice of using the historically
 allocated port 465 for "email submission but with TLS immediately upon connect
 instead of using STARTTLS" is officially blessed by the IETF, and recommended
 contentious.  As of RFC 8314, the common practice of using the historically
 allocated port 465 for "email submission but with TLS immediately upon connect
 instead of using STARTTLS" is officially blessed by the IETF, and recommended

-in preference to STARTTLS.
+by them in preference to STARTTLS.

 
 The name originally assigned to the port was &"ssmtp"& or &"smtps"&, but as
 clarity emerged over the dual roles of SMTP, for MX delivery and Email
 
 The name originally assigned to the port was &"ssmtp"& or &"smtps"&, but as
 clarity emerged over the dual roles of SMTP, for MX delivery and Email


@@ -27240,8 +27219,8 @@ standardized, but many clients kept using it, even as the TCP port number was
 reassigned for other use.
 Thus you may encounter guidance claiming that you shouldn't enable use of
 this port.
 reassigned for other use.
 Thus you may encounter guidance claiming that you shouldn't enable use of
 this port.

-In practice, a number of mail-clients have only supported submissions, not
-submission with STARTTLS upgrade.
+In practice, a number of mail-clients have only ever supported submissions,
+not submission with STARTTLS upgrade.

 Ideally, offer both submission (587) and submissions (465) service.
 
 Exim supports TLS-on-connect by means of the &%tls_on_connect_ports%&
 Ideally, offer both submission (587) and submissions (465) service.
 
 Exim supports TLS-on-connect by means of the &%tls_on_connect_ports%&


@@ -28094,7 +28073,6 @@ Open-source PKI book, available online at
 
 
 
 
 
 

-.new

 .section DANE "SECDANE"
 .cindex DANE
 DNS-based Authentication of Named Entities, as applied to SMTP over TLS, provides assurance to a client that
 .section DANE "SECDANE"
 .cindex DANE
 DNS-based Authentication of Named Entities, as applied to SMTP over TLS, provides assurance to a client that


@@ -28139,6 +28117,9 @@ the entire certificate chain from CA to server-certificate.  If a public CA is u
 DANE-TA is commonly used for several services and/or servers, each having a TLSA query-domain CNAME record,
 all of which point to a single TLSA record.
 
 DANE-TA is commonly used for several services and/or servers, each having a TLSA query-domain CNAME record,
 all of which point to a single TLSA record.
 

+Another approach which should be seriously considered is to use DANE with a certificate
+from a public CA, because of another technology, "MTA-STS", described below.
+

 The TLSA record should have a Selector field of SPKI(1) and a Matching Type field of SHA2-512(2).
 
 At the time of writing, &url(https://www.huque.com/bin/gen_tlsa)
 The TLSA record should have a Selector field of SPKI(1) and a Matching Type field of SHA2-512(2).
 
 At the time of writing, &url(https://www.huque.com/bin/gen_tlsa)


@@ -28225,7 +28206,28 @@ The &$event_data$& will be one of the Result Types defined in
 Section 4.3 of that document.
 
 Under GnuTLS, DANE is only supported from version 3.0.0 onwards.
 Section 4.3 of that document.
 
 Under GnuTLS, DANE is only supported from version 3.0.0 onwards.

-.wen
+
+DANE is specified in published RFCs and decouples certificate authority trust
+selection from a "race to the bottom" of "you must trust everything for mail
+to get through".  There is an alternative technology called MTA-STS, which
+instead publishes MX trust anchor information on an HTTPS website.  At the
+time this text was last updated, MTA-STS was still a draft, not yet an RFC.
+Exim has no support for MTA-STS as a client, but Exim mail server operators
+can choose to publish information describing their TLS configuration using
+MTA-STS to let those clients who do use that protocol derive trust
+information.
+
+The MTA-STS design requires a certificate from a public Certificate Authority
+which is recognized by clients sending to you.  That selection is outside your
+control.
+
+The most interoperable course of action is probably to use
+&url(https://letsencrypt.org/,Let's Encrypt), with automated certificate
+renewal; to publish the anchor information in DNSSEC-secured DNS via TLSA
+records for DANE clients (such as Exim and Postfix) and to publish anchor
+information for MTA-STS as well.  This is what is done for the &'exim.org'&
+domain itself (with caveats around occasionally broken MTA-STS because of
+incompatible specification changes prior to reaching RFC status).

 
 
 
 
 
 


@@ -29439,7 +29441,7 @@ and cannot depend on content of received headers.
 Note also that headers cannot be
 modified by any of the post-data ACLs (DATA, MIME and DKIM).
 Headers may be modified by routers (subject to the above) and transports.
 Note also that headers cannot be
 modified by any of the post-data ACLs (DATA, MIME and DKIM).
 Headers may be modified by routers (subject to the above) and transports.

-The Received-By: header is generated as soon as the body reception starts,
+The &'Received-By:'& header is generated as soon as the body reception starts,

 rather than the traditional time after the full message is received;
 this will affect the timestamp.
 
 rather than the traditional time after the full message is received;
 this will affect the timestamp.
 


@@ -30738,7 +30740,7 @@ restrictions, to get the TXT record. As a byproduct of this, there is also
 a check that the IP being tested is indeed on the first list. The first
 domain is the one that is put in &$dnslist_domain$&. For example:
 .code
 a check that the IP being tested is indeed on the first list. The first
 domain is the one that is put in &$dnslist_domain$&. For example:
 .code

-reject message  = \
+deny message  = \

          rejected because $sender_host_address is blacklisted \
          at $dnslist_domain\n$dnslist_text
        dnslists = \
          rejected because $sender_host_address is blacklisted \
          at $dnslist_domain\n$dnslist_text
        dnslists = \


@@ -30756,7 +30758,7 @@ If you are interested in more than one merged list, the same list must be
 given several times, but because the results of the DNS lookups are cached,
 the DNS calls themselves are not repeated. For example:
 .code
 given several times, but because the results of the DNS lookups are cached,
 the DNS calls themselves are not repeated. For example:
 .code

-reject dnslists = \
+deny dnslists = \

          http.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.2 : \
          socks.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.3 : \
          misc.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.4 : \
          http.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.2 : \
          socks.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.3 : \
          misc.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.4 : \


@@ -30967,13 +30969,15 @@ rest of the ACL.
 
 The &%leaky%& (default) option means that the client's recorded rate is not
 updated if it is above the limit. The effect of this is that Exim measures the
 
 The &%leaky%& (default) option means that the client's recorded rate is not
 updated if it is above the limit. The effect of this is that Exim measures the

-client's average rate of successfully sent email, which cannot be greater than
-the maximum allowed. If the client is over the limit it may suffer some
-counter-measures (as specified in the ACL), but it will still be able to send
-email at the configured maximum rate, whatever the rate of its attempts. This
+client's average rate of successfully sent email,
+.new
+up to the given limit.
+This is appropriate if the countermeasure when the condition is true
+consists of refusing the message, and

 is generally the better choice if you have clients that retry automatically.
 is generally the better choice if you have clients that retry automatically.

-For example, it does not prevent a sender with an over-aggressive retry rate
-from getting any email through.
+If the action when true is anything more complex then this option is
+likely not what is wanted.
+.wen

 
 The &%strict%& option means that the client's recorded rate is always
 updated. The effect of this is that Exim measures the client's average rate
 
 The &%strict%& option means that the client's recorded rate is always
 updated. The effect of this is that Exim measures the client's average rate


@@ -31858,9 +31862,7 @@ If the value of &%av_scanner%& starts with a dollar character, it is expanded
 before use.
 The usual list-parsing of the content (see &<<SECTlistconstruct>>&) applies.
 The following scanner types are supported in this release,
 before use.
 The usual list-parsing of the content (see &<<SECTlistconstruct>>&) applies.
 The following scanner types are supported in this release,

-.new

 though individual ones can be included or not at build time:
 though individual ones can be included or not at build time:

-.wen

 
 .vlist
 .vitem &%avast%&
 
 .vlist
 .vitem &%avast%&


@@ -31874,11 +31876,20 @@ which can be either a full path to a UNIX socket,
 or host and port specifiers separated by white space.
 The host may be a name or an IP address; the port is either a
 single number or a pair of numbers with a dash between.
 or host and port specifiers separated by white space.
 The host may be a name or an IP address; the port is either a
 single number or a pair of numbers with a dash between.

-Any further options are given, on separate lines,
-to the daemon as options before the main scan command.
+A list of options may follow. These options are interpreted on the
+Exim's side of the malware scanner, or are given on separate lines to
+the daemon as options before the main scan command.
+
+.cindex &`pass_unscanned`& "avast"
+If &`pass_unscanned`&
+is set, any files the Avast scanner can't scan (e.g.
+decompression bombs, or invalid archives) are considered clean. Use with
+care.
+

 For example:
 .code
 av_scanner = avast:/var/run/avast/scan.sock:FLAGS -fullfiles:SENSITIVITY -pup
 For example:
 .code
 av_scanner = avast:/var/run/avast/scan.sock:FLAGS -fullfiles:SENSITIVITY -pup

+av_scanner = avast:/var/run/avast/scan.sock:pass_unscanned:FLAGS -fullfiles:SENSITIVITY -pup

 av_scanner = avast:192.168.2.22 5036
 .endd
 If you omit the argument, the default path
 av_scanner = avast:192.168.2.22 5036
 .endd
 If you omit the argument, the default path


@@ -31895,13 +31906,9 @@ $ socat UNIX:/var/run/avast/scan.sock STDIO:
     PACK
 .endd
 
     PACK
 .endd
 

-A paniclog entry is logged and the message is deferred (except the
-malware condition uses "defer_ok") if the scanner returns a tmpfail
-(e.g. on license issues, or permission problems). If the scanner can't
-scan a file for internal reasons (e.g. decompression bomb), this is
-treated as an infection and malware_name is set to the error message.
-We do this err on the safe side.
-
+If the scanner returns a temporary failure (e.g. license issues, or
+permission problems), the message is deferred and a paniclog entry is
+written.  The usual &`defer_ok`& option is available.

 
 .vitem &%aveserver%&
 .cindex "virus scanners" "Kaspersky"
 
 .vitem &%aveserver%&
 .cindex "virus scanners" "Kaspersky"


@@ -31952,7 +31959,7 @@ av_scanner = clamd:192.0.2.3 1234 : 192.0.2.4 1234
 If the value of av_scanner points to a UNIX socket file or contains the
 &`local`&
 option, then the ClamAV interface will pass a filename containing the data
 If the value of av_scanner points to a UNIX socket file or contains the
 &`local`&
 option, then the ClamAV interface will pass a filename containing the data

-to be scanned, which will should normally result in less I/O happening and be
+to be scanned, which should normally result in less I/O happening and be

 more efficient.  Normally in the TCP case, the data is streamed to ClamAV as
 Exim does not assume that there is a common filesystem with the remote host.
 
 more efficient.  Normally in the TCP case, the data is streamed to ClamAV as
 Exim does not assume that there is a common filesystem with the remote host.
 


@@ -32034,7 +32041,7 @@ For example:
 .code
 av_scanner = f-protd:localhost 10200-10204
 .endd
 .code
 av_scanner = f-protd:localhost 10200-10204
 .endd

-If you omit the argument, the default values show above are used.
+If you omit the argument, the default values shown above are used.

 
 .vitem &%f-prot6d%&
 .cindex "virus scanners" "f-prot6d"
 
 .vitem &%f-prot6d%&
 .cindex "virus scanners" "f-prot6d"


@@ -32731,10 +32738,15 @@ code. The incident is logged on the main and reject logs.
 .section "Building Exim to use a local scan function" "SECID207"
 .cindex "&[local_scan()]& function" "building Exim to use"
 To make use of the local scan function feature, you must tell Exim where your
 .section "Building Exim to use a local scan function" "SECID207"
 .cindex "&[local_scan()]& function" "building Exim to use"
 To make use of the local scan function feature, you must tell Exim where your

-function is before building Exim, by setting LOCAL_SCAN_SOURCE in your
+function is before building Exim, by setting
+.new
+both HAVE_LOCAL_SCAN and
+.wen
+LOCAL_SCAN_SOURCE in your

 &_Local/Makefile_&. A recommended place to put it is in the &_Local_&
 directory, so you might set
 .code
 &_Local/Makefile_&. A recommended place to put it is in the &_Local_&
 directory, so you might set
 .code

+HAVE_LOCAL_SCAN=yes

 LOCAL_SCAN_SOURCE=Local/local_scan.c
 .endd
 for example. The function must be called &[local_scan()]&. It is called by
 LOCAL_SCAN_SOURCE=Local/local_scan.c
 .endd
 for example. The function must be called &[local_scan()]&. It is called by


@@ -36446,11 +36458,9 @@ A delivery set up by a router configured with
 failed. The delivery was discarded.
 .endlist olist
 .next
 failed. The delivery was discarded.
 .endlist olist
 .next

-.new

 .cindex DKIM "log line"
 &'DKIM: d='&&~&~Verbose results of a DKIM verification attempt, if enabled for
 logging and the message has a DKIM signature header.
 .cindex DKIM "log line"
 &'DKIM: d='&&~&~Verbose results of a DKIM verification attempt, if enabled for
 logging and the message has a DKIM signature header.

-.wen

 .endlist ilist
 
 
 .endlist ilist
 
 


@@ -36496,6 +36506,7 @@ selection marked by asterisks:
 &` queue_time_overall         `&  time on queue for whole message
 &` pid                        `&  Exim process id
 &` proxy                      `&  proxy address on <= and => lines
 &` queue_time_overall         `&  time on queue for whole message
 &` pid                        `&  Exim process id
 &` proxy                      `&  proxy address on <= and => lines

+&` receive_time               `&  time taken to receive message

 &` received_recipients        `&  recipients on <= lines
 &` received_sender            `&  sender on <= lines
 &`*rejected_header            `&  header contents on reject log
 &` received_recipients        `&  recipients on <= lines
 &` received_sender            `&  sender on <= lines
 &`*rejected_header            `&  header contents on reject log


@@ -36586,7 +36597,6 @@ precision, eg. &`DT=0.304s`&.
 &%delivery_size%&: For each delivery, the size of message delivered is added to
 the &"=>"& line, tagged with S=.
 .next
 &%delivery_size%&: For each delivery, the size of message delivered is added to
 the &"=>"& line, tagged with S=.
 .next

-.new

 .cindex log "DKIM verification"
 .cindex DKIM "verification logging"
 &%dkim%&: For message acceptance log lines, when an DKIM signature in the header
 .cindex log "DKIM verification"
 .cindex DKIM "verification logging"
 &%dkim%&: For message acceptance log lines, when an DKIM signature in the header


@@ -36595,7 +36605,6 @@ verifies successfully a tag of DKIM is added, with one of the verified domains.
 .cindex log "DKIM verification"
 .cindex DKIM "verification logging"
 &%dkim_verbose%&: A log entry is written for each attempted DKIM verification.
 .cindex log "DKIM verification"
 .cindex DKIM "verification logging"
 &%dkim_verbose%&: A log entry is written for each attempted DKIM verification.

-.wen

 .next
 .cindex "log" "dnslist defer"
 .cindex "DNS list" "logging defer"
 .next
 .cindex "log" "dnslist defer"
 .cindex "DNS list" "logging defer"


@@ -36717,14 +36726,12 @@ precision, eg. &`QT=1.578s`&.
 the local host is logged as QT=<&'time'&> on &"Completed"& lines, for
 example, &`QT=3m45s`&. The clock starts when Exim starts to receive the
 message, so it includes reception time as well as the total delivery time.
 the local host is logged as QT=<&'time'&> on &"Completed"& lines, for
 example, &`QT=3m45s`&. The clock starts when Exim starts to receive the
 message, so it includes reception time as well as the total delivery time.

-.new

 .next
 .cindex "log" "receive duration"
 &%receive_time%&: For each message, the amount of real time it has taken to
 perform the reception is logged as RT=<&'time'&>, for example, &`RT=1s`&.
 If millisecond logging is enabled, short times will be shown with greater
 precision, eg. &`RT=0.204s`&.
 .next
 .cindex "log" "receive duration"
 &%receive_time%&: For each message, the amount of real time it has taken to
 perform the reception is logged as RT=<&'time'&>, for example, &`RT=1s`&.
 If millisecond logging is enabled, short times will be shown with greater
 precision, eg. &`RT=0.204s`&.

-.wen

 .next
 .cindex "log" "recipients"
 &%received_recipients%&: The recipients of a message are listed in the main log
 .next
 .cindex "log" "recipients"
 &%received_recipients%&: The recipients of a message are listed in the main log


@@ -36882,10 +36889,8 @@ unchanged, or whether they should be rendered as escape sequences.
 &%tls_certificate_verified%&: An extra item is added to <= and => log lines
 when TLS is in use. The item is &`CV=yes`& if the peer's certificate was
 verified
 &%tls_certificate_verified%&: An extra item is added to <= and => log lines
 when TLS is in use. The item is &`CV=yes`& if the peer's certificate was
 verified

-.new

 using a CA trust anchor,
 &`CA=dane`& if using a DNS trust anchor,
 using a CA trust anchor,
 &`CA=dane`& if using a DNS trust anchor,

-.wen

 and &`CV=no`& if not.
 .next
 .cindex "log" "TLS cipher"
 and &`CV=no`& if not.
 .next
 .cindex "log" "TLS cipher"


@@ -38858,11 +38863,9 @@ linked to a domain which that entity controls.  It permits reputation to
 be tracked on a per-domain basis, rather than merely upon source IP address.
 DKIM is documented in RFC 6376.
 
 be tracked on a per-domain basis, rather than merely upon source IP address.
 DKIM is documented in RFC 6376.
 

-.new

 As DKIM relies on the message being unchanged in transit, messages handled
 by a mailing-list (which traditionally adds to the message) will not match
 any original DKIM signature.
 As DKIM relies on the message being unchanged in transit, messages handled
 by a mailing-list (which traditionally adds to the message) will not match
 any original DKIM signature.

-.wen

 
 DKIM support is compiled into Exim by default if TLS support is present.
 It can be disabled by setting DISABLE_DKIM=yes in &_Local/Makefile_&.
 
 DKIM support is compiled into Exim by default if TLS support is present.
 It can be disabled by setting DISABLE_DKIM=yes in &_Local/Makefile_&.


@@ -38883,7 +38886,6 @@ In typical Exim style, the verification implementation does not include any
 default "policy". Instead it enables you to build your own policy using
 Exim's standard controls.
 
 default "policy". Instead it enables you to build your own policy using
 Exim's standard controls.
 

-.new

 Please note that verification of DKIM signatures in incoming mail is turned
 on by default for logging (in the <= line) purposes.
 
 Please note that verification of DKIM signatures in incoming mail is turned
 on by default for logging (in the <= line) purposes.
 


@@ -38897,7 +38899,6 @@ signature status. Here is an example (with line-breaks added for clarity):
     c=relaxed/relaxed a=rsa-sha1
     i=@facebookmail.com t=1252484542 [verification succeeded]
 .endd
     c=relaxed/relaxed a=rsa-sha1
     i=@facebookmail.com t=1252484542 [verification succeeded]
 .endd

-.wen

 
 You might want to turn off DKIM verification processing entirely for internal
 or relay mail sources. To do that, set the &%dkim_disable_verify%& ACL
 
 You might want to turn off DKIM verification processing entirely for internal
 or relay mail sources. To do that, set the &%dkim_disable_verify%& ACL


@@ -38909,7 +38910,6 @@ senders).
 .section "Signing outgoing messages" "SECDKIMSIGN"
 .cindex "DKIM" "signing"
 
 .section "Signing outgoing messages" "SECDKIMSIGN"
 .cindex "DKIM" "signing"
 

-.new

 For signing to be usable you must have published a DKIM record in DNS.
 Note that RFC 8301 says:
 .code
 For signing to be usable you must have published a DKIM record in DNS.
 Note that RFC 8301 says:
 .code


@@ -38924,7 +38924,6 @@ in the DNS record is different between RSA and EC keys;
 for the former it is the base64 of the ASN.1 for the RSA public key
 (equivalent to the private-key .pem with the header/trailer stripped)
 but for EC keys it is the base64 of the pure key; no ASN.1 wrapping.
 for the former it is the base64 of the ASN.1 for the RSA public key
 (equivalent to the private-key .pem with the header/trailer stripped)
 but for EC keys it is the base64 of the pure key; no ASN.1 wrapping.

-.wen

 
 Signing is enabled by setting private options on the SMTP transport.
 These options take (expandable) strings as arguments.
 
 Signing is enabled by setting private options on the SMTP transport.
 These options take (expandable) strings as arguments.


@@ -38953,11 +38952,9 @@ You can use the &%$dkim_domain%& and
 The result can either
 .ilist
 be a valid RSA private key in ASCII armor (.pem file), including line breaks
 The result can either
 .ilist
 be a valid RSA private key in ASCII armor (.pem file), including line breaks

-.new

 .next
 with GnuTLS 3.6.0 or OpenSSL 1.1.1 or later,
 be a valid Ed25519 private key (same format as above)
 .next
 with GnuTLS 3.6.0 or OpenSSL 1.1.1 or later,
 be a valid Ed25519 private key (same format as above)

-.wen

 .next
 start with a slash, in which case it is treated as a file that contains
 the private key
 .next
 start with a slash, in which case it is treated as a file that contains
 the private key


@@ -38967,7 +38964,6 @@ be signed. This case will not result in an error, even if &%dkim_strict%&
 is set.
 .endlist
 
 is set.
 .endlist
 

-.new

 To generate keys under OpenSSL:
 .code
 openssl genrsa -out dkim_rsa.private 2048
 To generate keys under OpenSSL:
 .code
 openssl genrsa -out dkim_rsa.private 2048


@@ -39009,18 +39005,26 @@ To produce the required public key value for a DNS record:
 openssl pkey -outform DER -pubout -in dkim_ed25519.private | tail -c +13 | base64
 certtool --load_privkey=dkim_ed25519.private --pubkey_info --outder | tail -c +13 | base64
 .endd
 openssl pkey -outform DER -pubout -in dkim_ed25519.private | tail -c +13 | base64
 certtool --load_privkey=dkim_ed25519.private --pubkey_info --outder | tail -c +13 | base64
 .endd

-.wen
+
+Note that the format
+of Ed25519 keys in DNS has not yet been decided; this release supports
+both of the leading candidates at this time, a future release will
+probably drop support for whichever proposal loses.

 
 .option dkim_hash smtp string&!! sha256
 
 .option dkim_hash smtp string&!! sha256

-Can be set alternatively to &"sha1"& to use an alternate hash
-method.
+Can be set to any one of the supported hash methods, which are:
+.ilist
+&`sha1`& &-- should not be used, is old and insecure
+.next
+&`sha256`& &-- the default
+.next
+&`sha512`& &-- possibly more secure but less well supported
+.endlist

 
 

-.new

 Note that RFC 8301 says:
 .code
 rsa-sha1 MUST NOT be used for signing or verifying.
 .endd
 Note that RFC 8301 says:
 .code
 rsa-sha1 MUST NOT be used for signing or verifying.
 .endd

-.wen

 
 .option dkim_identity smtp string&!! unset
 If set after expansion, the value is used to set an "i=" tag in
 
 .option dkim_identity smtp string&!! unset
 If set after expansion, the value is used to set an "i=" tag in


@@ -39079,11 +39083,9 @@ To evaluate the signature in the ACL a large number of expansion variables
 containing the signature status and its details are set up during the
 runtime of the ACL.
 
 containing the signature status and its details are set up during the
 runtime of the ACL.
 

-.new

 .cindex authentication "expansion item"
 Performing verification sets up information used by the
 &$authresults$& expansion item.
 .cindex authentication "expansion item"
 Performing verification sets up information used by the
 &$authresults$& expansion item.

-.wen

 
 Calling the ACL only for existing signatures is not sufficient to build
 more advanced policies. For that reason, the global option
 
 Calling the ACL only for existing signatures is not sufficient to build
 more advanced policies. For that reason, the global option


@@ -39150,13 +39152,13 @@ This variable can be overwritten using an ACL 'set' modifier.
 This might, for instance, be done to enforce a policy restriction on
 hash-method or key-size:
 .code
 This might, for instance, be done to enforce a policy restriction on
 hash-method or key-size:
 .code

-  warn condition =     ${if eq {$dkim_verify_status}{pass}}
-       condition =     ${if eq {$len_3:$dkim_algo}{rsa}}
-       condition =     ${if or {eq {$dkim_algo}{rsa-sha1}} \
-                               {< {$dkim_key_length}{1024}} }
-       logwrite =      NOTE: forcing dkim verify fail (was pass)
-       set dkim_verify_status = fail
-       set dkim_verify_reason = hash too weak or key too short
+  warn condition       = ${if eq {$dkim_verify_status}{pass}}
+       condition       = ${if eq {${length_3:$dkim_algo}}{rsa}}
+       condition       = ${if or {{eq {$dkim_algo}{rsa-sha1}} \
+                                  {< {$dkim_key_length}{1024}}}}
+       logwrite        = NOTE: forcing DKIM verify fail (was pass)
+       set dkim_verify_status = fail
+       set dkim_verify_reason = hash too weak or key too short

 .endd
 
 After all the DKIM ACL runs have completed, the value becomes a
 .endd
 
 After all the DKIM ACL runs have completed, the value becomes a


@@ -39199,14 +39201,11 @@ The key record selector string.
 
 .vitem &%$dkim_algo%&
 The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'.
 
 .vitem &%$dkim_algo%&
 The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'.

-.new

 If running under GnuTLS 3.6.0 or OpenSSL 1.1.1 or later,
 may also be 'ed25519-sha256'.
 The "_CRYPTO_SIGN_ED25519" macro will be defined if support is present
 for EC keys.
 If running under GnuTLS 3.6.0 or OpenSSL 1.1.1 or later,
 may also be 'ed25519-sha256'.
 The "_CRYPTO_SIGN_ED25519" macro will be defined if support is present
 for EC keys.

-.wen

 
 

-.new

 Note that RFC 8301 says:
 .code
 rsa-sha1 MUST NOT be used for signing or verifying.
 Note that RFC 8301 says:
 .code
 rsa-sha1 MUST NOT be used for signing or verifying.


@@ -39217,7 +39216,6 @@ algorithms (currently, rsa-sha1) have permanently failed evaluation
 
 To enforce this you must have a DKIM ACL which checks this variable
 and overwrites the &$dkim_verify_status$& variable as discussed above.
 
 To enforce this you must have a DKIM ACL which checks this variable
 and overwrites the &$dkim_verify_status$& variable as discussed above.

-.wen

 
 .vitem &%$dkim_canon_body%&
 The body canonicalization method. One of 'relaxed' or 'simple'.
 
 .vitem &%$dkim_canon_body%&
 The body canonicalization method. One of 'relaxed' or 'simple'.


@@ -39246,9 +39244,7 @@ UNIX timestamp reflecting the date and time when the signer wants the
 signature to be treated as "expired". When this was not specified by the
 signer, "9999999999999" is returned. This makes it possible to do useful
 integer size comparisons against this value.
 signature to be treated as "expired". When this was not specified by the
 signer, "9999999999999" is returned. This makes it possible to do useful
 integer size comparisons against this value.

-.new

 Note that Exim does not check this value.
 Note that Exim does not check this value.

-.wen

 
 .vitem &%$dkim_headernames%&
 A colon-separated list of names of headers included in the signature.
 
 .vitem &%$dkim_headernames%&
 A colon-separated list of names of headers included in the signature.


@@ -39273,7 +39269,6 @@ Notes from the key record (tag n=).
 .vitem &%$dkim_key_length%&
 Number of bits in the key.
 
 .vitem &%$dkim_key_length%&
 Number of bits in the key.
 

-.new

 Note that RFC 8301 says:
 .code
 Verifiers MUST NOT consider signatures using RSA keys of
 Note that RFC 8301 says:
 .code
 Verifiers MUST NOT consider signatures using RSA keys of


@@ -39283,7 +39278,6 @@ less than 1024 bits as valid signatures.
 To enforce this you must have a DKIM ACL which checks this variable
 and overwrites the &$dkim_verify_status$& variable as discussed above.
 As EC keys are much smaller, the check should only do this for RSA keys.
 To enforce this you must have a DKIM ACL which checks this variable
 and overwrites the &$dkim_verify_status$& variable as discussed above.
 As EC keys are much smaller, the check should only do this for RSA keys.

-.wen

 
 .endlist
 
 
 .endlist
 


@@ -39327,7 +39321,6 @@ for more information of what they mean.
 
 
 
 
 
 

-.new

 .section "SPF (Sender Policy Framework)" SECSPF
 .cindex SPF verification
 
 .section "SPF (Sender Policy Framework)" SECSPF
 .cindex SPF verification
 


@@ -39341,15 +39334,13 @@ This includes retransmissions done by traditional forwarders.
 SPF verification support is built into Exim if SUPPORT_SPF=yes is set in
 &_Local/Makefile_&.  The support uses the &_libspf2_& library
 &url(http://www.libspf2.org/).
 SPF verification support is built into Exim if SUPPORT_SPF=yes is set in
 &_Local/Makefile_&.  The support uses the &_libspf2_& library
 &url(http://www.libspf2.org/).

-There is no Exim involvement on the trasmission of messages; publishing certain
-DNS records is all that is required.
+There is no Exim involvement in the transmission of messages;
+publishing certain DNS records is all that is required.

 
 For verification, an ACL condition and an expansion lookup are provided.
 
 For verification, an ACL condition and an expansion lookup are provided.

-.new

 .cindex authentication "expansion item"
 Performing verification sets up information used by the
 &$authresults$& expansion item.
 .cindex authentication "expansion item"
 Performing verification sets up information used by the
 &$authresults$& expansion item.

-.wen

 
 
 .cindex SPF "ACL condition"
 
 
 .cindex SPF "ACL condition"


@@ -39491,13 +39482,11 @@ address as the key and an IP address as the database:
   ${lookup {username@domain} spf {ip.ip.ip.ip}}
 .endd
 
   ${lookup {username@domain} spf {ip.ip.ip.ip}}
 .endd
 

-The lookup will return the same result strings as they can appear in
+The lookup will return the same result strings as can appear in

 &$spf_result$& (pass,fail,softfail,neutral,none,err_perm,err_temp).
 Currently, only IPv4 addresses are supported.
 
 
 &$spf_result$& (pass,fail,softfail,neutral,none,err_perm,err_temp).
 Currently, only IPv4 addresses are supported.
 
 

-. wen-for SPF section
-.wen

 
 
 . ////////////////////////////////////////////////////////////////////////////
 
 
 . ////////////////////////////////////////////////////////////////////////////


@@ -39713,9 +39702,7 @@ ${utf8_localpart_from_alabel:str}
 
 .cindex utf8 "address downconversion"
 .cindex i18n "utf8 address downconversion"
 
 .cindex utf8 "address downconversion"
 .cindex i18n "utf8 address downconversion"

-.new

 The RCPT ACL
 The RCPT ACL

-.wen

 may use the following modifier:
 .display
 control = utf8_downconvert
 may use the following modifier:
 .display
 control = utf8_downconvert