=pod

=head1 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

=head1 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;


=head1 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 I<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: I<keyword>, I<zone> and I<value> arguments are
identical to I<keyword>, I<zone> and I<additional-data> defined below for
B<dnsval.conf>.  I<ttl> specifies the duration in seconds for which the
policy is kept in effect.  A I<tt> value of B<-1> adds to policy to the context
indefinitely.  A handle to the newly added policy is returned in I<*pol>.
This structure is opaque to the applications; applications must not modify the
contents of the memory returned in I<*pol>.

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

The validator library reads configuration information from three separate
files, B<resolv.conf>, B<root.hints>, and B<dnsval.conf>.

=over 4

=item resolv.conf

The I<nameserver> and I<search> options are supported in the B<resolv.conf> file.

This I<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

A number of additional fields can be specified to qualify the name
server. For example, in the following line:

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

I<example.tsigkey> refers to the TSIG key name;
I<hmac-md5.sig-alg.reg.int> refers to the TSIG algorithm, I<300> is the
TSIG fudge factor. and the key is specified as a base64 encoded value.
The value I<8053> refers to the port number.

The values for the TSIG algorithm and the fudge factor in the above
example are the defaults. They may be omitted as follows:

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

The TSIG portion may also be left out entirely, in which case the
representation is as follows:

    nameserver [10.0.0.1]:8053


This I<search> option is used to specify the search path for issuing queries.
For example,

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

The I<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 B<resolv.conf> file contains no name servers, the validator
tries to recursively answer the query using information present
in B<root.hints>.

=item root.hints

The B<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

=item dnsval.conf

The B<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 I<ctx>
parameter for interfaces listed in I<libval(3)>,
I<val_getaddrinfo(3)>, and I<val_gethostbyname(3)>.  The default policy must be 
unique within the configuration system.

I<keyword> specifies the policy component within the
policy fragment.  The format of I<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 B<dnsval.conf>:

=over 4

=item 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==
    ;

=item zone-security-expectation

For the "zone-security-expectation" attribute additional-data
is a sequence of E<lt>domain name,valueE<gt> tuples representing 
the security expectation for names in that domain, where value 
can be one of the following:

=over 4

=item ignore

Ignore DNSSEC validation for names under this domain. 

=item validate

Perform DNSSEC validation of answers received for names under this domain.

=item untrusted

Reject all answers received for names under this domain.

=back

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
    ;


=item 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:

=over 4

=item trusted

Treat the provably insecure condition as valid.

=item untrusted

Treat the provably insecure condition as invalid.

=back

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
    ;

=item 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
    ;

=item 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.

=item 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 B<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
    ;

=back

Apart from zone-specific configuration options, it is also possible to
configure global options for the validation in B<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 B<dnsval.conf>.
If multiple constructs are defined, only the first is used.

The following keywords are defined for global-options in B<dnsval.conf>

=over 4

=item trust-local-answers

This option has been deprecated. Use trust-oob-answers instead.

=item trust-oob-answers

If the value against this option is B<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 B<libval(3)>) 
is greater than one.

=item 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.

=item 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.

=item 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 B<dnsval.conf>. See the section below on 
overriding dnsval.conf policies for additional details on this option.

=item 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 B<yes> then the validation algorithm terminates at
the closest matching TA.

=item 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 B<yes>; it can be turned
off by setting this option to B<no>.

=item max-refresh 

This option 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. Whe 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 the VAL_QUERY_SKIP_CACHE flag set
less than a minute apart will only result in one query seen on the wire. 

=item proto

This option is used to control the network protocol that libval uses to
send queries out to various name servers. If the value is set to
B<ipv6>, libval uses only IPv6; if it is set to B<ipv4> libval uses only
IPv4. The default is B<any>, which causes libval to send over any of the
available protocols for the given name server.

=item timeout

This option overrides the default resolver timeout value with the value
provided.

=item retry

This option overrides the default resolver retry value with the value
provided.

=item 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 B<libval(3)>).

=back

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
    ;


=back


=head1 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.

=head1 OVERRIDING dnsval.conf POLICIES

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

=over 4

=item 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.

=item 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.

=item 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.

=item 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

=over 4

=item 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)).

=item 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.

=item 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.

=back


=back

=head1 FILES

resolv.conf

root.hints

dnsval.conf	

=head1 COPYRIGHT

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

=head1 SEE ALSO

B<libval(3)>

http://www.dnssec-tools.org
http://www.dnssec-tools.org

=cut	
