dnsval.conf






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


    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.










                             ‐2‐


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

    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

    example.tsigkey refers to the TSIG key name;
    hmac−md5.sig−alg.reg.int refers to 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.

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










                             ‐3‐


        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









                             ‐4‐


        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









                             ‐5‐


            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.













                             ‐6‐


            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









                             ‐7‐


        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.

    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.

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











                             ‐8‐


    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
            ;

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









                             ‐9‐


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









                            ‐10‐


    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.

resolv.conf

     root.hints

     dnsval.conf

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

libval(3)

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