Provided by: libval-dev_2.0-1.1ubuntu1_amd64 bug


       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


           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;


       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.

           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,


           This search option is used to specify the search path for issuing queries.  For


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


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

           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

           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:

               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  \
                257 3 5 AQO8XS4y9r77X 9SHBmrx MoJf1Pf9\
                           AT9Mr/L5BBGtO9/e9f/zl4FFgM2l B6M2 XEm6mp6 mit4tzp\
                           B/sAEQw1McYz6bJdKkTiqtuWTCfDmgQhI6 /Ha0 Ef GPNSqn\
                           Y 99FmbSeWNIRaa4fgSCVFhvbrYq1nXkNVy QPeEVHk oDNCA\
                           lr qOA3lw==

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

                   Ignore DNSSEC validation for names under this domain.

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

                   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 domain; names under the
      domain are always considered to be untrusted and DNSSEC validation
               for all other domain names is ignored.

                   browser zone-security-expectation
                       . ignore

               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:

                   Treat the provably insecure condition as valid.

                   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

               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 domain.

                   mta clock-skew

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

               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
              DS  19297  5  2  \

           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.

                   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

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

               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.

               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.

               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.

               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.

               The default validation behavior is to look for any authentication chain that
               validates successfully. Thus if there are trust anchors for and
      the validator will return success if the authentication chain can
               be anchored to the trust anchor, even if the trust anchor for
      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.

               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:

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


       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.


       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.






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