Callouts: record succeeding random local-part tests. Bug 177

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index b1cc46862743cda0f8fc56ebf931a7655d6b5ad2..44022291c8c368f422290a2f793c7059a5fa2f82 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9434,11 +9434,14 @@ letters appear. For example:
         &*$h_*&<&'header&~name'&>&*:*&" &&&
        "&*$bheader_*&<&'header&~name'&>&*:*&&~or&~&&&
         &*$bh_*&<&'header&~name'&>&*:*&" &&&
+       "&*$lheader_*&<&'header&~name'&>&*:*&&~or&~&&&
+        &*$lh_*&<&'header&~name'&>&*:*&"
        "&*$rheader_*&<&'header&~name'&>&*:*&&~or&~&&&
         &*$rh_*&<&'header&~name'&>&*:*&"
 .cindex "expansion" "header insertion"
 .vindex "&$header_$&"
 .vindex "&$bheader_$&"
+.vindex "&$lheader_$&"
 .vindex "&$rheader_$&"
 .cindex "header lines" "in expansion strings"
 .cindex "header lines" "character sets"
@@ -9451,7 +9454,7 @@ The newline that terminates a header line is not included in the expansion, but
 internal newlines (caused by splitting the header line over several physical
 lines) may be present.
 
-The difference between &%rheader%&, &%bheader%&, and &%header%& is in the way
+The difference between the four pairs of expansions is in the way
 the data in the header line is interpreted.
 
 .ilist
@@ -9459,6 +9462,15 @@ the data in the header line is interpreted.
 &%rheader%& gives the original &"raw"& content of the header line, with no
 processing at all, and without the removal of leading and trailing white space.
 
+.next
+.cindex "list" "of header lines"
+&%lheader%& gives a colon-separated list, one element per header when there
+are multiple headers with a given name.
+Any embedded colon characters within an element are doubled, so normal Exim
+list-processing facilities can be used.
+The terminating newline of each element is removed; in other respects
+the content is &"raw"&.
+
 .next
 .cindex "base64 encoding" "in header lines"
 &%bheader%& removes leading and trailing white space, and then decodes base64
@@ -15082,7 +15094,7 @@ server. This reduces security slightly, but improves interworking with older
 implementations of TLS.
 
 
-option gnutls_allow_auto_pkcs11 main boolean unset
+.option gnutls_allow_auto_pkcs11 main boolean unset
 This option will let GnuTLS (2.12.0 or later) autoload PKCS11 modules with
 the p11-kit configuration files in &_/etc/pkcs11/modules/_&.
 
@@ -17369,7 +17381,7 @@ The ordering of the two lists must match.
 .cindex SSMTP
 .cindex SMTPS
 This option specifies a list of incoming SSMTP (aka SMTPS) ports that should
-operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately
+operate the SSMTP (SMTPS) protocol, where a TLS session is immediately
 set up without waiting for the client to issue a STARTTLS command. For
 further details, see section &<<SECTsupobssmt>>&.
 
@@ -31148,6 +31160,15 @@ connection, HELO, or MAIL).
 The main use of these variables is expected to be to distinguish between
 rejections of MAIL and rejections of RCPT in callouts.
 
+.new
+The above variables may also be set after a &*successful*&
+address verification to:
+
+.ilist
+&%random%&: A random local-part callout succeeded
+.endlist
+.wen
+
 
 
 
@@ -39037,7 +39058,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
@@ -39071,22 +39092,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