Doc: Update dns_trust_aa documentation

1 files changed, 30 insertions, 21 deletions

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 2d2a1097a..96f967a7a 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9071,7 +9071,7 @@ ${env{USER}{$value} fail }
 This forces an expansion failure (see section &<<SECTforexpfai>>&);
 {<&'string1'&>} must be present for &"fail"& to be recognized.
 
-If {<&'string2'&>} is omitted an empty string is substituted on 
+If {<&'string2'&>} is omitted an empty string is substituted on
 search failure.
 If {<&'string1'&>} is omitted the search result is substituted on
 search success.
@@ -11764,7 +11764,7 @@ It will be empty if &(DNSSEC)& was not requested,
 and &"yes"& if it was.
 .new
 Results that are labelled as authoritive answer that match
-the $%dns_trust_aa%$ configuration variable count also
+the &%dns_trust_aa%& configuration variable count also
 as authenticated data.
 .wen
 
@@ -13616,7 +13616,7 @@ See also the &'Policy controls'& section above.
 .row &%dns_ipv4_lookup%&             "only v4 lookup for these domains"
 .row &%dns_retrans%&                 "parameter for resolver"
 .row &%dns_retry%&                   "parameter for resolver"
-.row &%dns_trust_aa%&                "nameservers trusted as authentic"
+.row &%dns_trust_aa%&                "DNS zones trusted as authentic"
 .row &%dns_use_edns0%&               "parameter for resolver"
 .row &%hold_domains%&                "hold delivery for these domains"
 .row &%local_interfaces%&            "for routing checks"
@@ -14323,23 +14323,32 @@ See &%dns_retrans%& above.
 
 
 .new
-.option dns_trust_aa main domain list&!! unset
+.option dns_trust_aa main "domain list&!!" unset
 .cindex "DNS" "resolver options"
 .cindex "DNS" "DNSSEC"
-If this option is set then lookup results marked with an AA bit
-(Authoratative Answer) are trusted when they come from one
-of the listed domains, as if they were marked as having been
-DNSSEC-verified.
-
-Use this option only if you talk directly to the resolver
-for your local domains, and list only it.
-It is needed when the resolver does not return an AD bit
-for its local domains.
-The first SOA or NS record appearing in the results is compared
-against the option value.
+If this option is set then lookup results marked with the AA bit
+(Authoritative Answer) are trusted the same way as if they were
+DNSSEC-verified. The authority section's name of the answer must
+match with this expanded domain list.
+
+Use this option only if you talk directly to a resolver that is
+authoritive for some zones and does not set the AD (Authentic Data)
+bit in the answer. Some DNS servers may have an configuration option to
+mark the answers from their own zones as verified (they set the AD bit).
+Others do not have this option. It is considered as poor practice using
+a resolver that is an authoritive server for some zones.
+
+Use this option only if you really have to (e.g. if you want
+to use DANE for remote delivery to a server that is listed in the DNS
+zones that your resolver is authoritive for).
+
+If the DNS answer packet has the AA bit set and contains resource record
+in the answer section, the name of first NS record appearing in the
+authority section is compared against the list. If the answer packet is
+authoritive but the answer section is empty, the name of the first SOA
+record in the authoritive section is used instead.
 .wen
 
-
 .cindex "DNS" "resolver options"
 .option dns_use_edns0 main integer -1
 .cindex "DNS" "resolver options"
@@ -15452,7 +15461,7 @@ not count as protocol errors (see &%smtp_max_synprot_errors%&).
 This option can be used to enable the Per-Recipient Data Response extension
 to SMTP, defined by Eric Hall.
 If the option is set, PRDR is advertised by Exim when operating as a server.
-If the client requests PRDR, and more than one recipient, for a message 
+If the client requests PRDR, and more than one recipient, for a message
 an additional ACL is called for each recipient after the message content
 is recieved.  See section &<<SECTPRDRACL>>&.
 
@@ -30797,7 +30806,7 @@ is used.
 If you use a remote host,
 you need to make Exim's spool directory available to it,
 as the scanner is passed a file path, not file contents.
-For information about available commands and their options you may use 
+For information about available commands and their options you may use
 .code
 $ socat UNIX:/var/run/avast/scan.sock STDIO:
     FLAGS
@@ -31108,7 +31117,7 @@ score and a report for the message.
 .new
 Support is also provided for Rspamd.
 
-For more information about installation and configuration of SpamAssassin or 
+For more information about installation and configuration of SpamAssassin or
 Rspamd refer to their respective websites at
 &url(http://spamassassin.apache.org) and &url(http://www.rspamd.com)
 .wen
@@ -31122,7 +31131,7 @@ documentation to see how you can tweak it. The default installation should work
 nicely, however.
 
 .oindex "&%spamd_address%&"
-By default, SpamAssassin listens on 127.0.0.1, TCP port 783 and if you 
+By default, SpamAssassin listens on 127.0.0.1, TCP port 783 and if you
 intend to use an instance running on the local host you do not need to set
 &%spamd_address%&. If you intend to use another host or port for SpamAssassin,
 you must set the &%spamd_address%& option in the global part of the Exim
@@ -35909,7 +35918,7 @@ exim -bp
 The &*-C*& option is used to specify an alternate &_exim.conf_& which might
 contain alternate exim configuration the queue management might be using.
 
-to obtain a queue listing, and then greps the output to select messages 
+to obtain a queue listing, and then greps the output to select messages
 that match given criteria. The following selection options are available:
 
 .vlist