Provided by: libval-dev_2.0-1.1ubuntu1_amd64 
NAME
dnsval.conf, resolv.conf, root.hints - Configuration policy for the DNSSEC validator library libval(3).
val_add_valpolicy - Dynamically add a new policy to the validator context val_remove_valpolicy - Remove a
dynamically added policy from the validator context
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
Applications can use local policy to influence the validation outcome. Examples of local policy elements
include trust anchors for different zones and untrusted algorithms for cryptographic keys and hashes.
Local policy may vary for different applications and operating scenarios.
The val_add_valpolicy() function can be used to dynamically add a new policy for a given context (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.
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.
resolv.conf
The nameserver and search options are supported in the resolv.conf file.
This nameserver option is used to specify the IP address of the name server to which queries must be
sent by default. For example,
nameserver 10.0.0.1
This search option is used to specify the search path for issuing queries. For example,
search test.dnssec-tools.org dnssec-tools.org
The forward option is used to redirect 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
If the resolv.conf file contains no name servers, the validator tries to recursively answer the query
using information present in root.hints.
root.hints
The root.hints file contains bootstrapping information for the resolver while it attempts to
recursively answer queries. The contents of this file may be generated by the following command:
dig @e.root-servers.net . ns > root.hints
dnsval.conf
The dnsval.conf file contains the validator policy. It consists of a sequence of the following
"policy-fragments":
<label> <keyword> <additional-data>;
Policies are identified by simple text strings called labels, which must be unique within the
configuration system. For example, "browser" could be used as the label that defines the validator
policy for all web-browsers in a system. A label value of ":" identifies the default policy, the
policy that is used when a NULL context is specified as the ctx parameter for interfaces listed in
libval(3), val_getaddrinfo(3), and val_gethostbyname(3). 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 the keyword specified.
If multiple policy fragments are defined for the same label and keyword combination then the first
definition in the file is used.
The following keywords are defined for dnsval.conf:
trust-anchor
For the "trust-anchor" attribute additional-data is a sequence of ordered pairs, each consisting
of the zone name and the RDATA portion for the trust anchor with an optional prefix. Trust
anchors may be either DNSKEY or DS records, the prefix in the RDATA is use to indicate what type
of record it is. DNSKEY is assumed if no prefix is specified.
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 the "zone-security-expectation" attribute additional-data is a sequence of <domain
name,value> tuples representing the security expectation for names in that domain, where value
can be one of the following:
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 makes it possible to define
various islands of trust for DNSSEC-enabled zones and to ignore or validate data from selected
zones. The default zone security expectation for a domain is "validate". In the following
example, for DNSSEC validator contexts created with a DNSSEC validator policy label of "browser",
the DNSSEC validation is only performed for names under the example.com domain; names under the
somebogus.org domain are always considered to be untrusted and DNSSEC validation for all other
domain names is ignored.
browser zone-security-expectation
example.com validate
somebogusname.org untrusted
. ignore
;
provably-insecure-status
For the "provably-insecure-status" attribute additional-data is a sequence of <domain
name,value> tuples representing the validity of the provably insecure condition, where value is
one of the following:
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 following
example, 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 this condition is
treated as invalid.
: provably-insecure-status
. trusted
net untrusted
;
clock-skew
For the "clock-skew" attribute 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
has the effect of turning off inception and expiration time checks on signatures from that
domain. The default clock skew is 0. In the following example, 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
;
nsec3-max-iter [only if LIBVAL_NSEC3 is enabled]
Specifies the maximum number of iterations allowable while computing the NSEC3 hash for a zone.
A value of -1 does not place a maximum limit on the number of iterations. This is also the
default setting for a zone.
dlv-trust-points [only if LIBVAL_DLV is enabled]
Specifies the DLV tree for the target zone. In the following example, libval will use the DLV
registry defined at dlv.isc.org. for all queries under the root that do not 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.
;
In order for DLV to be used in the above example, there must also 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
;
Apart from zone-specific configuration options, it is also possible to configure global options for
the validation in dnsval.conf. Global options can be specified using the construct below.
global-options
keyowrd1 value1
keyword2 value2
...
;
There can only be one global-options construct defined for dnsval.conf. If multiple constructs are
defined, only the first is used.
The following keywords are defined for global-options in dnsval.conf
trust-local-answers
This option has been deprecated. 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.
edns0-size
In 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 allows the administrator of the dnsval.conf to 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 additional details on this option.
app-policy
This option allows the administrator of the dnsval.conf file to control whether libval will
automatically look for a validation policy with a label equal to the application name in
dnsval.conf. See the section below on overriding dnsval.conf policies for additional details on
this option.
closest-ta-only
The default validation behavior is to look for any authentication chain that validates
successfully. Thus 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.
rec-fallback
This option is used to control 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 options
is set to yes; it can be turned off by setting this option to no.
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 specfied at the time of running
configure. If this file is absent, libval looks at /etc/resolv.conf file for resolver options.
This allows users with 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.
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.
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 Precendence
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.
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