resolv.5: Document the trust-ad option

Signed-off-by Florian Weimer <[email protected]>

---
 man5/resolv.conf.5 | 31 ++++++++++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)

man5/resolv.conf.5 +28 -3

index 7013c8a28..6f3de7faf 100644
@@ -35,9 +35,10 @@ The resolver configuration file contains information that is read
 by the resolver routines the first time they are invoked by a process.
 The file is designed to be human readable and contains a list of
 keywords with values that provide various types of resolver information.
-The configuration file is considered a trusted source of DNS information
-(e.g., DNSSEC AD-bit information will be returned unmodified from this
-source).
+The configuration file is considered a trusted source of DNS information;
+see the
+.B trust-ad
+option below for details.
 .PP
 If this file does not exist, only the name server on the local machine
 will be queried, and the search list contains the local domain name

@@ -317,6 +318,30 @@ Sets
 in
 .IR _res.options .
 This option disables automatic reloading of a changed configuration file.
+.TP
+.BR trust\-ad " (since glibc 2.31)"
+.\" 446997ff1433d33452b81dfa9e626b8dccf101a4
+Sets
+.BR RES_TRUSTAD
+in
+.IR _res.options .
+This option controls the AD bit behavior of the stub resolver.  If a
+validating resolver sets the AD bit in a response, it indicates that
+the data in the response was verified according to the DNSSEC
+protocol.  In order to rely on the AD bit, the local system has to
+trust both the DNSSEC-validating resolver and the network path to it,
+which is why an explicit opt-in is required.  If the
+.B trust\-ad
+option is active, the stub resolver sets the AD bit in outgoing DNS
+queries (to enable AD bit support), and preserves the AD bit in
+responses.  Without this option, the AD bit is not set in queries, and
+it is always removed from responses before they are returned to the
+application.  This means that applications can trust the AD bit in
+responses if the
+.B trust\-ad
+option has been set correctly.  In glibc version 2.30 and earlier, the
+AD is not set automatically in queries, and passed through unchanged
+to applications in responses.
 .RE
 .PP
 The \fIsearch\fP keyword of a system's \fIresolv.conf\fP file can be