[PATCH] resolv.5: Document the trust-ad option

[PATCH] resolv.5: Document the trust-ad option

[Florian Weimer]

Signed-off-by: Florian Weimer <fweimer@redhat.com>

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

diff --git a/man5/resolv.conf.5 b/man5/resolv.conf.5
index 7013c8a28..6f3de7faf 100644
--- a/man5/resolv.conf.5
+++ b/man5/resolv.conf.5
@@ -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

-- 
Red Hat GmbH, https://de.redhat.com/ , Registered seat: Grasbrunn,
Commercial register: Amtsgericht Muenchen, HRB 153243,
Managing Directors: Charles Cachera, Brian Klemm, Laurie Krebs, Michael O'Neill

Re: [PATCH] resolv.5: Document the trust-ad option

[Michael Kerrisk (man-pages)]

On 10/12/20 1:22 PM, Florian Weimer wrote:
> Signed-off-by: Florian Weimer <fweimer@redhat.com>

Thanks, Florian. Patch applied.

Cheers

Michael

> ---
>  man5/resolv.conf.5 | 31 ++++++++++++++++++++++++++++---
>  1 file changed, 28 insertions(+), 3 deletions(-)
> 
> diff --git a/man5/resolv.conf.5 b/man5/resolv.conf.5
> index 7013c8a28..6f3de7faf 100644
> --- a/man5/resolv.conf.5
> +++ b/man5/resolv.conf.5
> @@ -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
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/