dnsval.conf(3)

NAME 💖

okay bestie, welcome to the dnsval.conf(3) page — part 1, more parts are coming. This is all about the configuration policy for the DNSSEC validator library libval(3), and the files in the mix are dnsval.conf, resolv.conf, and root.hints. Also, val_add_valpolicy dynamically adds a new policy to the validator context, while val_remove_valpolicy removes a dynamically added policy from the validator context. no cap. 🫶

SYNOPSIS ✨

           int val_add_valpolicy(val_context_t *context,
                           void *policy_definition,
                           val_policy_entry_t **pol);

           int val_remove_valpolicy(val_context_t *context,
                           val_policy_entry_t *pol);

           typedef struct {
               char *keyword;
               char *zone;
               char *value;
               long ttl;
           } libval_policy_definition_t;

DESCRIPTION 🌈

So apps can use local policy to influence the validation outcome, and that's iconic. Examples of local policy elements? Trust anchors for different zones, plus untrusted algorithms for cryptographic keys and hashes. Local policy may vary for different applications and operating scenarios. personalized policy, we love to see it. 💅

You can use val_add_valpolicy() to dynamically add a new policy for a given context (and no, the policies are not added persistently to the system configuration). The policy_definition field contains an implementation-specific definition of the validator policy to be added. For the libval library, this is represented by the libval_policy_definition_t structure, which contains four fields: keyword, zone and value arguments are identical to keyword, zone and additional-data defined below for dnsval.conf. ttl specifies the duration in seconds for which the policy is kept in effect. A tt value of -1 adds to policy to the context indefinitely. A handle to the newly added policy is returned in *pol.

This structure is opaque to the applications; applications must not modify the contents of the memory returned in *pol. 🚫 no touchy.

Applications may also revoke the effects of a newly added policy, pol, before the expiry of its timeout interval using the val_remove_valpolicy() policy.

The validator library reads configuration information from three separate files, resolv.conf, root.hints, and dnsval.conf. three files, three vibes 🎀

resolv.conf 🌸

So in resolv.conf, you've got the nameserver and search options supported.

The nameserver option is how you specify the IP address of the name server that queries must be sent to by default. For example,

nameserver 10.0.0.1

You can also add a bunch of additional fields to qualify the name server. Like, check this line:

nameserver [10.0.0.1][example.tsigkey:hmac-md5.sig-alg.reg.int:300:0jnu3SdsMvzzlmTDPYRceA==]:8053

Here example.tsigkey is the TSIG key name; hmac-md5.sig-alg.reg.int is the TSIG algorithm, 300 is the TSIG fudge factor. and the key is specified as a base64 encoded value. The value 8053 refers to the port number. iykyk, that bracket situation is iconic ✨

In that example, the TSIG algorithm and fudge factor values are the defaults. So you can omit them like this:

nameserver [10.0.0.1][example.tsigkey:::0jnu3SdsMvzzlmTDPYRceA==]:8053

You can also leave the TSIG portion out entirely, and then it looks like this:

nameserver [10.0.0.1]:8053

The search option is what you use to specify the search path for issuing queries. For example,

search test.dnssec-tools.org dnssec-tools.org

The forward option redirects queries for names that match a given zone name to the provided name server. For example,

forward 76.216.12.217 test.dnssec-tools.org

And if resolv.conf has no name servers at all, the validator tries to recursively answer the query using info present in root.hints. recursive mode activated 🌀

root.hints 🦋

root.hints holds bootstrapping information for the resolver while it attempts to recursively answer queries. You can generate the contents with this command:

dig @e.root-servers.net . ns > root.hints

literally just dig and redirect, bestie 💚

dnsval.conf 💅

dnsval.conf is where the validator policy lives. It's a sequence of these "policy-fragments":

<label> <keyword> <additional-data>;

Policies get identified by simple text strings called labels, and those labels must be unique within the configuration system. For example, "browser" could be the label that defines the validator policy for all web-browsers in a system. A label value of ":" identifies the default policy — the policy used when a NULL context is specified as the ctx parameter for interfaces listed in libval(3), val_getaddrinfo(3), and val_gethostbyname(3). And the default policy must be unique within the configuration system.

keyword specifies the policy component within the policy fragment. The format of additional-data depends on which keyword you specified.

If multiple policy fragments are defined for the same label and keyword combo, the first definition in the file is the one that wins. first one wins, no cap 🏆

These are the keywords defined for dnsval.conf:

trust-anchor 🔐

For the "trust-anchor" attribute, additional-data is a sequence of ordered pairs. Each pair has the zone name and the RDATA portion for the trust anchor, with an optional prefix. Trust anchors can be DNSKEY or DS records, and the prefix in the RDATA is use to indicate what type of record it is. If no prefix is specified, DNSKEY is assumed.

An example is given below.

                   browser trust-anchor
                       .   DS  19036  8  2  \
                           49AAC11D7B6F6446702E54A1607371607A1A41855200FD2CE\
                           1CDDE32F24E8FB5
                       example.com   257 3 5 AQO8XS4y9r77X 9SHBmrx MoJf1Pf9\
                           AT9Mr/L5BBGtO9/e9f/zl4FFgM2l B6M2 XEm6mp6 mit4tzp\
                           B/sAEQw1McYz6bJdKkTiqtuWTCfDmgQhI6 /Ha0 Ef GPNSqn\
                           Y 99FmbSeWNIRaa4fgSCVFhvbrYq1nXkNVy QPeEVHk oDNCA\
                           lr qOA3lw==
                   ;

zone-security-expectation 🛡️

For "zone-security-expectation", additional-data is a sequence of <domain name,value> tuples. They represent the security expectation for names in that domain, and value can be one of these:

• ignore — Ignore DNSSEC validation for names under this domain.
• validate — Perform DNSSEC validation of answers received for names under this domain.
• untrusted — Reject all answers received for names under this domain.

This zone-security-expectation DNSSEC validator policy construct lets you define various islands of trust for DNSSEC-enabled zones and ignore or validate data from selected zones. The default zone security expectation for a domain is "validate". In the example below, for DNSSEC validator contexts created with a DNSSEC validator policy label of "browser", DNSSEC validation only happens for names under the example.com domain; names under the somebogus.org domain are always considered untrusted, and DNSSEC validation for all other domain names is ignored.

                   browser zone-security-expectation
                       example.com  validate
                       somebogusname.org untrusted
                       . ignore
                   ;

islands of trust? we love a secure archipelago 🏝️

provably-insecure-status 🔍

For "provably-insecure-status", additional-data is a sequence of <domain name,value> tuples. They represent the validity of the provably insecure condition, and value is one of these:

• trusted — Treat the provably insecure condition as valid.
• untrusted — Treat the provably insecure condition as invalid.

The default value for the provably insecure status for a domain is "trusted". In the example below, for DNSSEC validator contexts created with the default label, the provably insecure condition is treated as valid for all domains except the net domain, where it's treated as invalid.

                   : provably-insecure-status
                       . trusted
                       net untrusted
                   ;

clock-skew ⏰

For "clock-skew", additional-data is a sequence of the domain name and the number of seconds of clock-skew acceptable for signatures on names in that domain. A clock skew value of -1 turns off inception and expiration time checks on signatures from that domain. The default clock skew is 0. In the example below, for DNSSEC validator contexts created with the "mta" label, signature inception and expiration checks are disabled for all names under the example.com domain.

                   mta clock-skew
                       example.com -1
                   ;

-1 here is giving "time is fake" energy, but it literally turns off inception and expiration checks for that domain. 🕰️

nsec3-max-iter [only if LIBVAL_NSEC3 is enabled] 🌀

This one specifies the maximum number of iterations allowable while computing the NSEC3 hash for a zone. A value of -1 means no maximum limit on the number of iterations. And that's also the default setting for a zone.

dlv-trust-points [only if LIBVAL_DLV is enabled] 🌳

This specifies the DLV tree for the target zone. In the example below, libval will use the DLV registry defined at dlv.isc.org. for all queries under the root that don't give us a trustworthy answer using the normal DNSSEC mechanism, and have a zone-security-expectation of validate.

                   dlv dlv-trust-points
                       .   dlv.isc.org.
                   ;

For DLV to be used in the above example, there also has to be a trust-anchor policy defined for the dlv registry, with the zone-security-expectation policy for registry set to validate.

                   dlv trust-anchor
                       dlv.isc.org DS  19297  5  2  \
                                   A11D16F6733983E159EDF8053B2FB57B479D81A309A5\
                                   0EAA79A81AF48A47C617
                   ;

Besides zone-specific configuration options, you can also configure global options for the validation in dnsval.conf. Global options can be specified using this construct:

               global-options
                   keyowrd1 value1
                   keyword2 value2
                   ...
               ;

global options, global slay 🌍✨

okay so real talk first: there can only be one global-options construct defined for dnsval.conf. Like, one. If multiple constructs are defined, only the first is used. The rest are just sitting there, decorative, ignored. 💅

The following keywords are defined for global-options in dnsval.conf:

• trust-local-answers — this one's deprecated bestie 😭 use trust-oob-answers instead.
• trust-oob-answers — if the value against this option is yes, then for all answers returned using some out-of-band mechanism (e.g. a file store such as /etc/hosts), the value returned from the val_istrusted() function (see libval(3)) is greater than one. yes bestie, greater than one ✨
• edns0-size — when querying various name servers, libsres will also attempt multiple EDNS0 sizes, ending with a query that has EDNS0 disabled (i.e. no CD bit set). The following EDNS0 sizes are tried by default: 4096, 1492, 512. The edns0-size policy knob can be used to change the largest EDNS0 size that is attempted. 🎀
• env-policy — this option lets the administrator of the dnsval.conf control whether libval uses user-specified values in environmental variables while determining libval policy and log targets. See the section below on overriding dnsval.conf policies for the extra deets on this one. 👀
• app-policy — this one lets the administrator of the dnsval.conf file control whether libval will automatically look for a validation policy with a label equal to the application name in dnsval.conf. Again, see the section below on overriding dnsval.conf policies for the details. 🦋
• closest-ta-only — the default validation behavior is to look for any authentication chain that validates successfully. So like, if there are trust anchors for example.com and test.example.com, the validator will return success if the authentication chain can be anchored to the example.com trust anchor, even if the trust anchor for test.example.com does not match. In cases where this is not desirable, the closest-ta-only option can be used. If this option is set to yes then the validation algorithm terminates at the closest matching TA. no cap, that's the whole vibe check ⭐
• rec-fallback — controls whether libval will attempt to fall back to a recursive lookup of the name if the response from the caching name server returned an error. By default this option is set to yes; it can be turned off by setting this option to no.
• max-refresh — this one is used in conjunction with the VAL_QUERY_SKIP_CACHE query flag. When queries have this flag enabled they would normally skip cached entries. However, max-refresh can throttle how often queries are actually sent on the wire. When this option is set to a positive value a new query is only sent out if the cached value was stored more than (the value specified by) max-refresh seconds ago. If max-refresh is 0, then the cache is always skipped. If the value is -1 the cache is never skipped. The default value for max-refresh is 60 seconds. That means that two queries sent with the VAL_QUERY_SKIP_CACHE flag set less than a minute apart will only result in one query seen on the wire. throttling queen behavior fr fr 👑
• proto — controls the network protocol that libval uses to send queries out to various name servers. If the value is set to ipv6, libval uses only IPv6; if it is set to ipv4 libval uses only IPv4. The default is any, which causes libval to send over any of the available protocols for the given name server. 🌈
• timeout — this option overrides the default resolver timeout value with the value provided.
• retry — this option overrides the default resolver retry value with the value provided.
• log — this option controls the level of logging and the log target for libval. The value expected against this option is the same as that specified for val_add_log_optarg (see libval(3)).

An example global-options construct is given below:

global-options
    trust-oob-answers yes
    edns0-size 4096
    env-policy enable
    app-policy enable
    log 5:stderr
;

---

💖 OVERRIDING resolv.conf POLICIES 💖

libval first looks at resolver options present in the resolv.conf file specified at the time of running configure. If this file is absent, libval looks at /etc/resolv.conf file for resolver options.

This allows users a simple way of overriding resolver policies. The system-specific resolv.conf can remain unchanged, while any additional policies that may have to be specified for libval can be used in the configure-supplied resolv.conf file. so clean, so tidy ✨

---

🌸 OVERRIDING dnsval.conf POLICIES 🌸

libval provides three ways for tailoring dnsval.conf policies for a given environment.

📁 Multiple include files

libval allows additional dnsval.conf files to be included with a given dnsval.conf file. The option is specified as follows:

include /path/to/override/file/dnsval.conf

The files are read in breadth-first. The policies are evaluated in a manner that gives the last-defined policy more precedence over earlier ones. Therefore, an administrator may supply a dnsval.conf with default policies including another file from the user's home directory. The included file may be used for overriding policies specified in the base dnsval.conf file. last one wins, that's just the rules bestie 🫶

🏷️ Application-name policies

If the app-policy global option is not disabled, libval automatically looks for a policy in dnsval.conf with a label value constructed from the name of the application. For example, dnsval.conf may be defined with validator policies for the foo label. The foo application, when run, will use the policy defined against the foo label during its validation operation.

🌱 Policies through environment

If the env-policy global option is not disabled, libval looks at the VAL_CONTEXT_LABEL and VAL_LOG_TARGET environmental variables in order to determine the validator policy label and log target.

🥇 Validator Label Precedence

There are effectively four different types of polic-labels that can be applied by libval: application-name policies, policies through VAL_CONTEXT_LABEL, and labels specified by the application (either NULL or non-NULL). The precedence of applying these labels is defined with the following rules:

1. If env-policy is "override", use the label specified in the VAL_CONTEXT_LABEL env variable (if defined).
2. If env-policy is "enable" and the policy specified by the application is NULL, use the label specified in the VAL_CONTEXT_LABEL env variable (if defined).
3. if app-policy is "override", use the label generated from the application name. If this policy label does not exist in the configuration system, use the default policy.
4. if app-policy is "enable" and the policy specified by the application is NULL, use the label generated from the application name.
5. If policy specified by the application is not NULL, use this label.
6. Use default policy

The following use-cases can therefore be defined:

🔒 locked-down system with single policy

An administrator that wants to (and is able to) lock down a system to a particular validator policy, must set the env-policy and app-policy global options to disable. This also requires that administrators are able to lock down the system to specific applications and that these applications are not written in a way that would allow them to specify non-NULL policy labels during context creation. (see val_create_context in libval(3)).

🔐 locked-down system with app-specific policies

An administrator that wants to (and is able to) lock down a system to a particular dnsval.conf file, but wishes to use different policies for different applications must set the app-policy to override and the env-policy to disable. The administrator must also define policies for various application names in dnval.conf; for applications that don't have a policy with a label corresponding to its name, the default policy is used.

The administrator may set the app-policy to enable if non-NULL policies specified by the application during validator context creation is deemed acceptable.

🎛️ User controlled

An administrator can set env-policy to override to give the user complete control over which policy label is used during validation. The validation policy is read through the VAL_CONTEXT_LABEL environment variable.

If VAL_CONTEXT_LABEL is specified globally for the system, the administrator may instead choose the env-policy global option to be enable instead of override. In this case, the label given in VAL_CONTEXT_LABEL is used only when the policy specified by the application is non-NULL.

The label in VAL_CONTEXT_LABEL is used only if it is defined. If this value is NULL, libval will read other policy labels as guided by the precedence rules listed above. iykyk 💅

---

🍓 FILES 🍓

• resolv.conf
• root.hints
• dnsval.conf

---

📜 COPYRIGHT 📜

Copyright 2004-2013 SPARTA, Inc. All rights reserved. See the COPYING file included with the dnssec-tools package for details.

---

👀 SEE ALSO 👀

• libval(3)
• http://www.dnssec-tools.org http://www.dnssec-tools.org

---

and that's the whole page bestie 🎀 this one's from perl v5.26.2, dated 2018-08-08, and it's dnsval.conf(3) — ate and left no crumbs 💖✨