Fix ${domain:} for a bare local-part input. Bug 2375

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 32d57d027ec1a7c2d2d42a6c5a0e807b69508bab..63db8ef707902698dd85819f785ca7639e290690 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -14347,7 +14347,9 @@ listed in more than one group.
 See also the &'Policy controls'& section above.
 
 .table2
 See also the &'Policy controls'& section above.
 
 .table2

-.row &%dkim_verify_signers%&         "DKIM domain for which DKIM ACL is run"
+.row &%dkim_verify_hashes%&          "DKIM hash methods accepted for signatures"
+.row &%dkim_verify_keytypes%&        "DKIM key types accepted for signatures"
+.row &%dkim_verify_signers%&         "DKIM domains for which DKIM ACL is run"

 .row &%host_lookup%&                 "host name looked up for these hosts"
 .row &%host_lookup_order%&           "order of DNS and local name lookups"
 .row &%recipient_unqualified_hosts%& "may send unqualified recipients"
 .row &%host_lookup%&                 "host name looked up for these hosts"
 .row &%host_lookup_order%&           "order of DNS and local name lookups"
 .row &%recipient_unqualified_hosts%& "may send unqualified recipients"


@@ -15092,6 +15094,27 @@ etc. are ignored. If IP literals are enabled, the &(ipliteral)& router declines
 to handle IPv6 literal addresses.
 
 
 to handle IPv6 literal addresses.
 
 

+.new
+.option dkim_verify_hashes main "string list" "sha256 : sha512 : sha1"
+.cindex DKIM "selecting signature algorithms"
+This option gives a list of hash types which are acceptable in signatures,
+and an order of processing.
+Signatures with algorithms not in the list will be ignored.
+
+Note that the presence of sha1 violates RFC 8301.
+Signatures using the rsa-sha1 are however (as of writing) still common.
+The default inclusion of sha1 may be dropped in a future release.
+
+.option dkim_verify_keytypes main "string list" "ed25519 : rsa"
+This option gives a list of key types which are acceptable in signatures,
+and an order of processing.
+Signatures with algorithms not in the list will be ignored.
+
+.option dkim_verify_minimal main boolean false
+If set to true, verification of signatures will terminate after the
+first success.
+.wen
+

 .option dkim_verify_signers main "domain list&!!" $dkim_signers
 .cindex DKIM "controlling calls to the ACL"
 This option gives a list of DKIM domains for which the DKIM ACL is run.
 .option dkim_verify_signers main "domain list&!!" $dkim_signers
 .cindex DKIM "controlling calls to the ACL"
 This option gives a list of DKIM domains for which the DKIM ACL is run.


@@ -18884,11 +18907,24 @@ latter kind.
 
 This option controls whether the local part is used to form the key for retry
 hints for addresses that suffer temporary errors while being handled by this
 
 This option controls whether the local part is used to form the key for retry
 hints for addresses that suffer temporary errors while being handled by this

-router. The default value is true for any router that has &%check_local_user%&
+.new
+router. The default value is true for any router that has any of
+&%check_local_user%&, 
+&%local_parts%&,
+&%condition%&,
+&%local_part_prefix%&,
+&%local_part_suffix%&,
+&%senders%& or
+&%require_files%&
+.wen

 set, and false otherwise. Note that this option does not apply to hints keys
 for transport delays; they are controlled by a generic transport option of the
 same name.
 
 set, and false otherwise. Note that this option does not apply to hints keys
 for transport delays; they are controlled by a generic transport option of the
 same name.
 

+Failing to set this option when it is needed
+(because a remote router handles only some of the local-parts for a domain)
+can result in incorrect error messages being generated.
+

 The setting of &%retry_use_local_part%& applies only to the router on which it
 appears. If the router generates child addresses, they are routed
 independently; this setting does not become attached to them.
 The setting of &%retry_use_local_part%& applies only to the router on which it
 appears. If the router generates child addresses, they are routed
 independently; this setting does not become attached to them.


@@ -22823,6 +22859,15 @@ sometimes add other information onto the ends of message filenames.
 
 Section &<<SECID136>>& contains further information.
 
 
 Section &<<SECID136>>& contains further information.
 

+.new
+This option should not be used when other message-handling software
+may duplicate messages by making hardlinks to the files.  When that is done Exim
+will count the message size once for each filename, in contrast with the actual
+disk usage.  When the option is not set, calculating total usage requires
+a system-call per file to get the size; the number of links is then available also
+as is used to adjust the effective size.
+.wen
+

 
 .option quota_warn_message appendfile string&!! "see below"
 See below for the use of this option. If it is not set when
 
 .option quota_warn_message appendfile string&!! "see below"
 See below for the use of this option. If it is not set when


@@ -39900,15 +39945,28 @@ RFC 6376 lists these tags as RECOMMENDED.
 
 Verification of DKIM signatures in SMTP incoming email is done for all
 messages for which an ACL control &%dkim_disable_verify%& has not been set.
 
 Verification of DKIM signatures in SMTP incoming email is done for all
 messages for which an ACL control &%dkim_disable_verify%& has not been set.

+.new
+.cindex DKIM "selecting signature algorithms"
+Individual classes of signature algorithm can be ignored by changing
+the main options &%dkim_verify_hashes%& or &%dkim_verify_keytypes%&.
+The &%dkim_verify_minimal%& option can be set to cease verification
+processing for a message once the first passing signature is found.
+.wen
+

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

-The results of that verification are then made available to the
+.new
+For most purposes the default option settings suffice and the remainder
+of this section can be ignored.
+.wen
+
+The results of verification are made available to the

 &%acl_smtp_dkim%& ACL, which can examine and modify them.
 &%acl_smtp_dkim%& ACL, which can examine and modify them.

-By default, this ACL is called once for each
-syntactically(!) correct signature in the incoming message.

 A missing ACL definition defaults to accept.
 A missing ACL definition defaults to accept.

+By default, the ACL is called once for each
+syntactically(!) correct signature in the incoming message.

 If any ACL call does not accept, the message is not accepted.
 If a cutthrough delivery was in progress for the message, that is
 summarily dropped (having wasted the transmission effort).
 If any ACL call does not accept, the message is not accepted.
 If a cutthrough delivery was in progress for the message, that is
 summarily dropped (having wasted the transmission effort).


@@ -39919,11 +39977,11 @@ containing the signature status and its details are set up during the
 runtime of the ACL.
 
 Calling the ACL only for existing signatures is not sufficient to build
 runtime of the ACL.
 
 Calling the ACL only for existing signatures is not sufficient to build

-more advanced policies. For that reason, the global option
-&%dkim_verify_signers%&, and a global expansion variable
+more advanced policies. For that reason, the main option
+&%dkim_verify_signers%&, and an expansion variable

 &%$dkim_signers%& exist.
 
 &%$dkim_signers%& exist.
 

-The global option &%dkim_verify_signers%& can be set to a colon-separated
+The main option &%dkim_verify_signers%& can be set to a colon-separated

 list of DKIM domains or identities for which the ACL &%acl_smtp_dkim%& is
 called. It is expanded when the message has been received. At this point,
 the expansion variable &%$dkim_signers%& already contains a colon-separated
 list of DKIM domains or identities for which the ACL &%acl_smtp_dkim%& is
 called. It is expanded when the message has been received. At this point,
 the expansion variable &%$dkim_signers%& already contains a colon-separated


@@ -39961,7 +40019,7 @@ If multiple signatures match a domain (or identity), the ACL is called once
 for each matching signature.
 
 
 for each matching signature.
 
 

-Inside the &%acl_smtp_dkim%&, the following expansion variables are
+Inside the DKIM ACL, the following expansion variables are

 available (from most to least important):
 
 
 available (from most to least important):
 
 


@@ -40055,8 +40113,12 @@ DKIM signatures identified as having been signed with historic
 algorithms (currently, rsa-sha1) have permanently failed evaluation
 .endd
 
 algorithms (currently, rsa-sha1) have permanently failed evaluation
 .endd
 

-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 either have a DKIM ACL which checks this variable
+and overwrites the &$dkim_verify_status$& variable as discussed above,
+.new
+or have set the main option &%dkim_verify_hashes%& to exclude
+processing of such signatures.
+.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'.


@@ -40323,7 +40385,11 @@ would relax host matching rules to a broader network range.
 .cindex SPF "lookup expansion"
 .cindex lookup spf
 A lookup expansion is also available. It takes an email
 .cindex SPF "lookup expansion"
 .cindex lookup spf
 A lookup expansion is also available. It takes an email

-address as the key and an IP address as the database:
+address as the key and an IP address
+.new
+(v4 or v6)
+.wen
+as the database:

 
 .code
   ${lookup {username@domain} spf {ip.ip.ip.ip}}
 
 .code
   ${lookup {username@domain} spf {ip.ip.ip.ip}}


@@ -40331,7 +40397,6 @@ address as the key and an IP address as the database:
 
 The lookup will return the same result strings as can appear in
 &$spf_result$& (pass,fail,softfail,neutral,none,err_perm,err_temp).
 
 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.