Docs: clarify DKIM verification
[exim.git] / doc / doc-docbook / spec.xfpt
index e5873f3496fe5318ee2ae741f3e50cfa3b5a395e..173d69222845a1f24b748e89f57c404b739cc70f 100644 (file)
@@ -30740,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
-reject message  = \
+deny message  = \
          rejected because $sender_host_address is blacklisted \
          at $dnslist_domain\n$dnslist_text
        dnslists = \
@@ -30758,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
-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 : \
@@ -30969,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
-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.
-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
@@ -39035,7 +39037,7 @@ tag value.  Note that Exim does not check the value.
 This option sets the canonicalization method used when signing a message.
 The DKIM RFC currently supports two methods: "simple" and "relaxed".
 The option defaults to "relaxed" when unset. Note: the current implementation
-only supports using the same canonicalization method for both headers and body.
+only supports signing with the same canonicalization method for both headers and body.
 
 .option dkim_strict smtp string&!! unset
 This  option  defines  how  Exim  behaves  when  signing a message that
@@ -39069,22 +39071,28 @@ name will be appended.
 .section "Verifying DKIM signatures in incoming mail" "SECDKIMVFY"
 .cindex "DKIM" "verification"
 
-Verification of DKIM signatures in SMTP incoming email is implemented via the
-&%acl_smtp_dkim%& ACL. By default, this ACL is called once for each
+.new
+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.
+.cindex authentication "expansion item"
+Performing verification sets up information used by the
+&$authresults$& expansion item.
+.wen
+
+.new The results of that verification are then made available to the
+&%acl_smtp_dkim%& ACL, &new(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.
 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).
 
-To evaluate the signature in the ACL a large number of expansion variables
+To evaluate the &new(verification result) 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.
 
-.cindex authentication "expansion item"
-Performing verification sets up information used by the
-&$authresults$& expansion item.
-
 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