From b8444b382f1b4fa31bf975295ade3a29d616ed9e Mon Sep 17 00:00:00 2001
From: Jeremy Harris <jgh146exb@wizmail.org>
Date: Sat, 24 Mar 2018 18:38:15 +0000
Subject: [PATCH] Docs: more on ${authresults }

---
 doc/doc-docbook/spec.xfpt         | 27 +++++++++++++++++++++++++++
 doc/doc-txt/experimental-spec.txt |  6 +++++-
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index c29ab47ba..67ade7b04 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9154,6 +9154,7 @@ If the ACL returns defer the result is a forced-fail.  Otherwise the expansion f
 .vitem "&*${authresults{*&<&'authserv-id'&>&*}}*&"
 .cindex authentication "results header"
 .cindex headers "authentication-results:"
+.cindex authentication "expansion item"
 This item returns a string suitable for insertion as an
 &'Authentication-Results"'&
 header line.
@@ -9172,6 +9173,7 @@ Example use (as an ACL modifier):
 .code
       add_header = :at_start:${authresults {$primary_hostname}}
 .endd
+This is safe even if no authentication reselts are available.
 .wen
 
 
@@ -11936,6 +11938,13 @@ 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$&.
 
+.new
+.cindex authentication "expansion item"
+Performing these checks sets up information used by the
+&$authresults$& expansion item.
+.wen
+
+
 .vitem &$host_lookup_failed$&
 .vindex "&$host_lookup_failed$&"
 See &$host_lookup_deferred$&.
@@ -26105,6 +26114,12 @@ 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.
 
+.new
+.cindex authentication "expansion item"
+Successful authentication sets up information used by the
+&$authresults$& expansion item.
+.wen
+
 
 
 
@@ -39001,6 +39016,12 @@ 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.
 
+.new
+.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
 &%dkim_verify_signers%&, and a global expansion variable
@@ -39261,6 +39282,12 @@ There is no Exim involvement on the trasmission of messages; publishing certain
 DNS records is all that is required.
 
 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.
+.wen
+
 
 .cindex SPF "ACL condition"
 .cindex ACL "spf condition"
diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt
index 2ed6e3582..4abb29697 100644
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -523,6 +523,9 @@ Of course, you can also use any other lookup method that Exim
 supports, including LDAP, Postgres, MySQL, etc, as long as the
 result is a list of colon-separated strings.
 
+Performing the check sets up information used by the
+${authresults } expansion item.
+
 Several expansion variables are set before the DATA ACL is
 processed, and you can use them in this ACL.  The following
 expansion variables are available:
@@ -587,7 +590,6 @@ b. Configure, somewhere before the DATA ACL, the control option to
   warn    dmarc_status   = accept : none : off
           !authenticated = *
           log_message    = DMARC DEBUG: $dmarc_status $dmarc_used_domain
-          add_header     = $dmarc_ar_header
 
   warn    dmarc_status   = !accept
           !authenticated = *
@@ -606,6 +608,8 @@ b. Configure, somewhere before the DATA ACL, the control option to
           !authenticated = *
           message        = Message from $dmarc_used_domain failed sender's DMARC policy, REJECT
 
+  warn    add_header     = :at_start:${authresults {$primary_hostname}}
+
 
 
 DSN extra information
-- 
2.25.1