val_istrusted






val_create_context() val_free_context() − manage validator
context

     val_context_setqflags() − manage validator context
flags

     val_resolve_and_check(), val_free_result_chain() −
query and validate answers from a DNS name server

     val_istrusted() − check if status value corresponds to
that of a trustworthy answer

     val_isvalidated() − check if status value represents an
answer that cryptographically chains down from a configured
trust anchor

     val_does_not_exist() − check if status value represents
one of the non−existence types

     p_val_status(), p_ac_status(), p_val_error() − display
validation status, authentication chain status and error
information

     val_log_add_optarg − control log message verbosity and
output location


  #include <validator.h>

  int val_create_context(const char *label, val_context_t **newcontext);

  int val_create_context_ex(char *label,
                            val_context_opt_t *opt,
                            val_context_t ** newcontext);

  int val_context_setqflags(val_context_t *context,
                            unsigned char action,
                            unsigned int flags);

  int val_context_store_ns_for_zone(val_context_t *context,
                                    char * zone,
                                    char *resp_server,
                                    int recursive)

  int val_resolve_and_check(val_context_t *context,
                         const char *domain_name,
                         int class,
                         int type,
                         unsigned int  flags,
                         struct val_result_chain  **results);

  char *p_val_status(val_status_t valerrno);

  char *p_ac_status(val_astatus_t auth_chain_status);









                             ‐2‐



  char *p_val_error(int err);

  int val_istrusted(val_status_t val_status);

  int val_isvalidated(val_status_t val_status);

  int val_does_not_exist(val_status_t status);

  val_log_t *val_log_add_optarg(const char *args, int use_stderr);

  void val_free_result_chain(struct val_result_chain *results);

  void val_free_context(val_context_t *context);

The val_resolve_and_check() function queries a set of name
servers for the <domain_name, type, class> tuple and
verifies and validates the response.  Verification involves
checking the RRSIGs, and validation is verification of an
authentication chain from a configured trust anchor.

     The flags parameter can be used to control the results
of validation.  The following values, which may be ORed
together, are currently defined for this field:

VAL_QUERY_DONT_VALIDATE
    This flag causes the validator to disable validation for
    this query.

VAL_QUERY_IGNORE_SKEW
    This flag causes the validator to disable checking
    signature inception and expiration times on RRSIGs.

VAL_QUERY_AC_DETAIL
    This flag causes the validator to copy the
    authentication chain details into the val_rc_answer
    member within the returned val_result_chain structure.

VAL_QUERY_ASYNC
    This flag enables asynchronous query resolution for that
    lookup.

VAL_QUERY_NO_DLV
    This flag causes the validator to disable DLV processing
    for this query.  This is only available if the libval(3)
    library has been compiled with DLV support.

VAL_QUERY_NO_EDNS0_FALLBACK
    In querying various name servers, libsres(3) will also
    attempt multiple EDNS0 sizes, ending with a query that
    has EDNS0 disabled (i.e. no CD bit set).  This flag
    causes libval to disable EDNS0 fallback for the query.











                             ‐3‐


VAL_QUERY_ITERATE
    This flag forces libval to iteratively lookup the query
    by querying various name servers in the delegation
    hierarchy, instead of requesting this information from
    any caching name server that may be configured in
    dnsval.conf.

VAL_QUERY_SKIP_RESOLVER
    This flag forces libval to only look at its cache while
    trying to resolve a name.

VAL_QUERY_SKIP_CACHE
    There are two levels of caching that happen within
    libval: at the assertion level and at the answer level.
    This flag forces libval to ignore data in both caches
    while trying to resolve a name.

VAL_QUERY_SKIP_ANS_CACHE
    There are two levels of caching that happen within
    libval: at the assertion level and at the answer level.
    This flag forces libval to ignore data in the answer
    cache while trying to resolve a name.  If an assertion
    already exists for the given name,class and type that
    assertion is re‐used till it expires. Once it expires
    the name is looked up via a query even if an newer
    record (fetched by another assertion in the same or
    different context) is available in its answer cache.

     The first parameter to val_resolve_and_check() is the
validator context.  Applications can create a new validator
context using the val_create_context() function.  This
function parses the resolver and validator configuration
files and creates the newcontext handle for this parsed
information.  Information stored as part of the validator
context includes the validation policy the and resolver
policy.

     Validator and resolver policies are read from the
/etc/dnsval.conf and /etc/resolv.conf files by default.
/etc/root.hints provides bootstrapping information for the
validator when it functions as a full resolver (see
dnsval.conf(3)). These defaults may be different if any
other value was specified at library configure time.  If the
default resolver configuration file is not found at the
specified location, libval will also try to fall back to
/etc/resolv.conf as a last resort.

     Applications may also create a validator context with a
custom policy using the val_create_context_ex() function.

     The opt argument in val_create_context_ex() points to
the following structure:











                             ‐4‐


         typedef struct val_context_opt {
        unsigned int vc_qflags;
        unsigned int vc_polflags;
        char *vc_valpol;
        char *vc_nslist;
        char *vc_val_conf;
        char *vc_res_conf;
        char *vc_root_conf;
        val_global_opt_t *gopt,
    } val_context_opt_t;

     vc_qflags specify the default query flags for queries
associated with the context. This field is identical to the
flags argument in the val_resolve_and_check() function.

     The vc_val_conf, vc_res_conf, and vc_root_conf fields
can be used to specify alternative configuration files in
place of the default files used for the validator, resolver,
and root hints configuration information.

     The vc_valpol field can be used to supply a custom
validator configuration "snippet" to the validator. The
validator parses this information and applies it to the
default validator configuration either as an extension or as
an override, as specified by the vc_polflags field. The
vc_nslist field, similarly, can be used to supply a custom
list of recursive name servers to send queries to, in
addition (or in place of) the list of name servers specified
in the resolv.conf file.  The list of name servers in
vc_res_conf must be specified as a white‐space delimited
list of IP or IPv6 addresses.

     A custom mapping between a zone and a name server may
be created using the val_context_store_ns_for_zone()
function.

     vc_polflags can be configured with the following
values:

CTX_DYN_POL_VAL_OVR
    When this flag is set only the validator configuration
    specified in the vc_valpol field is used for the
    validator configuration.  Options specified in the
    dnsval.conf file are ignored.

CTX_DYN_POL_RES_OVR
    When this flag is set only the name servers specified in
    the vc_nslist field is used for the resolver
    configuration.  Options specified in the resolv.conf
    file are ignored.

CTX_DYN_POL_GLO_OVR
    When this flag is set only the global options set in
    gopt field are used.  Global options specified in the









                             ‐5‐


    dnsval.conf file are ignored.

CTX_DYN_POL_RES_NRD
    When this flag is set outgoing queries have the
    Recursion Desired (RD) bit set to 0.  This is useful if
    queries need to be sent to an authoritative‐only name
    server.

     The gopt field points to the following structure:

         typedef struct val_global_opt {
        int local_is_trusted;
        long edns0_size;
        int env_policy;
        int app_policy;
        char *log_target;
        int closest_ta_only;
        int rec_fallback;
        long max_refresh;
        int proto;
    } val_global_opt_t;

     Setting a value of 1 for local_is_trusted is equivalent
to specifying the trust‐oob‐answers option in the
dnsval.conf file to yes.  Similarly, setting the
closest_ta_only and rec_fallback members to 1 is equivalent
to setting the closest‐ta‐only and rec‐fallback options to
yes in the dnsval.conf file.  A value of 0 is equivalent to
the no setting for these option.

     Setting the edns0_size member to a particular value has
the same effect setting the edns0−size option in the
dnsval.conf file.

     Setting the max_refresh member to a particular value
has the same effect setting the max‐refresh option in the
dnsval.conf file.

     Setting the proto member to a particular value has the
same effect setting the proto option in the dnsval.conf
file.

     env_policy and app_policy can be set to one of
VAL_POL_GOPT_DISABLE, VAL_POL_GOPT_ENABLE, or
VAL_POL_GOPT_OVERRIDE.  These values correspond directly to
the disable, enable and override options for the env‐policy
and app‐policy settings in the dnsval.conf file.

     Values of −1 for the above fields are treated as
"ignore" conditions in that the validator will not include
dynamically supplied global options with a value of −1 when
creating its context.  This allows an application to
overriding a subset of global options while using the global
options supplied in the dnsval.conf file by default.









                             ‐6‐


     The log_target field enables the application to supply
log targets in addition to the ones configured in the
configuration file.

     See dnsval.conf(3) for more details on specifying
validator policy.

     Default query flags can be set and unset for a given
context using val_context_setqflags().  This allows an
application to alter the DNSSEC validator processing, while
still having most of the more granular default configuration
specified in its configuration file.  The action parameter
can be set to one of the following.

VAL_CTX_FLAG_SET
    This option causes the validator to set the given flag
    as one of the default query flags.

VAL_CTX_FLAG_RESET
    This option causes the validator to reset the given flag
    if it was set as one of the default query flags for the
    context.

     Answers returned by val_resolve_and_check() are made
available in the *results linked list.  Each answer
corresponds to a distinct RRset; multiple RRs within the
RRset are part of the same answer.  Multiple answers are
possible when type is ns_t_any or ns_t_rrsig.

     Individual elements in *results point to
val_authentication_chain linked lists.  The authentication
chain elements in val_authentication_chain contain the
actual RRsets returned by the name server in response to the
query.

     Validation result values returned in val_result_chain
can be can be converted into ASCII format using the
p_val_status().  Authentication chain status values returned
in each element of the val_authentication_chain linked list
can be can be converted into ASCII format using the
p_ac_status() functions.

     While some applications such as DNSSEC troubleshooting
utilities and packet inspection tools may look at individual
authentication chain elements to identify the actual reasons
for validation error, most applications will only be
interested in a single error code for determining the
authenticity of data.

     val_isvalidated() identifies if a given validation
result status value corresponds to an answer that was
cryptographically verified and validated using a locally
configured trust anchor.










                             ‐7‐


     val_istrusted() identifies if a given validator status
value is trusted.  An answer may be locally trusted without
being validated.

     val_does_not_exist() identifies if a given validator
status value corresponds to one of the non‐existence types.

     The libval library internally allocates memory for
*results and this must be freed by the invoking application
using the free_result_chain() interface.



struct val_result_chain
      struct val_result_chain
      {
          val_status_t                     val_rc_status;
          char                            *val_rc_alias;
          struct val_rrset_rec            *val_rc_rrset;
          struct val_authentication_chain *val_rc_answer;
          int                              val_rc_proof_count;
          struct val_authentication_chain *val_rc_proofs[MAX_PROOFS];
          struct val_result_chain         *val_rc_next;
      };

    val_rc_answer
        Authentication chain for a given RRset.

    val_rc_next
        Pointer to the next RRset in the set of answers
        returned for a query.

    val_rc_proofs
        Pointer to authentication chains for any proof of
        non‐existence that were returned for the query.

    val_rc_proof_count
        Number of proof elements stored in val_rc_proofs.
        The number cannot exceed MAX_PROOFS.

    val_rc_alias
        For an val_result_chain element that points to a
        name alias, this field contains the target value.

    val_rc_rrset
        For a val_result_chain element that contains a valid
        (not NULL) val_rc_answer field, the val_rc_rrset
        field points to the top‐most val_rrset_rec element
        in the val_rc_answer authentication chain.

    val_rc_status
        Validation status for a given RRset.  This can be
        one of the following:










                             ‐8‐


        VAL_SUCCESS
            Answer received and validated successfully.

        VAL_NONEXISTENT_NAME
            No name was present and a valid proof of non‐
            existence confirming the missing name (NSEC or
            NSEC3 span) was returned.  The components of the
            proof were also individually validated.

        VAL_NONEXISTENT_TYPE
            No type exists for the name and a valid proof of
            non‐existence confirming the missing name was
            returned.  The components of the proof were also
            individually validated.

        VAL_NONEXISTENT_NAME_NOCHAIN
            No name was present and a valid proof of non‐
            existence confirming the missing name was
            returned.  The components of the proof were also
            identified to be trustworthy, but they were not
            individually validated.

        VAL_NONEXISTENT_TYPE_NOCHAIN
            No type exists for the name and a valid proof of
            non‐existence confirming the missing name (NSEC
            or NSEC3 span) was returned.  The components of
            the proof were also identified to be
            trustworthy, but they were not individually
            validated.

        VAL_PINSECURE
            The record or some ancestor of the record in the
            authentication chain towards the trust anchor
            was known to be provably insecure.

        VAL_PINSECURE_UNTRUSTED
            The record or some ancestor of the record in the
            authentication chain towards the trust anchor
            was known to be provably insecure. But the
            provably insecure condition was configured as
            untrustworthy.

        VAL_BARE_RRSIG
            No DNSSEC validation possible, query was for an
            RRSIG.

        VAL_IGNORE_VALIDATION
            Local policy was configured to ignore validation
            for the zone from which this data was received.

        VAL_UNTRUSTED_ZONE
            Local policy was configured to reject any data
            received from the given zone.










                             ‐9‐


        VAL_OOB_ANSWER
            Answer was obtained using some Out Of Band
            method, such as a local configuration file.

        VAL_BOGUS
            Response could not be validated due to signature
            verification failures or the inability to verify
            proofs in the authentication chain.

        VAL_DNS_ERROR
            Some error was encountered during DNS
            processing.

        VAL_INDETERMINATE
            Response could not be validated due to missing
            DNSSEC meta‐data.

        VAL_NOTRUST
            All available components in the authentication
            chain verified properly, but there was no trust
            anchor available.

            Status values in val_status_t returned by the
            validator can be displayed in ASCII format using
            p_val_status().

struct val_authentication_chain
      struct val_authentication_chain
      {
          val_astatus_t                    val_ac_status;
          struct val_rrset_rec                *val_ac_rrset;
          struct val_authentication_chain *val_ac_trust;
      };

    val_ac_status
        Validation state of the authentication chain
        element.  This field will contain the status code
        for the given component in the authentication chain.
        This field may contain one of the following values:

        VAL_AC_UNSET
            The status could not be determined.

        VAL_AC_IGNORE_VALIDATION
            Validation for the given resource record was
            ignored, either because of some local policy
            directive or because of some protocol‐specific
            behavior.

        VAL_AC_UNTRUSTED_ZONE
            Local policy defined a given zone as untrusted,
            with no further validation being deemed
            necessary.










                            ‐10‐


        VAL_AC_PINSECURE
            The authentication chain from a trust anchor to
            a given zone could not be constructed due to the
            provable absence of a DS record for this zone in
            the parent.

        VAL_AC_BARE_RRSIG
            The response was for a query of type RRSIG.
            RRSIGs contain the cryptographic signatures for
            other DNS data and cannot themselves be
            validated.

        VAL_AC_NO_LINK
            There was no trust anchor configured for a given
            authentication chain or the chain didn’t link
            up.

        VAL_AC_TRUST
            At least one of the signatures covering the
            given DNSKEY RRset was directly verified using a
            key that was configured as a DNSSEC trust
            anchor.

        VAL_AC_RRSIG_MISSING
            RRSIG data could not be retrieved for a resource
            record.

        VAL_AC_DNSKEY_MISSING
            The DNSKEY for an RRSIG covering a resource
            record could not be retrieved.

        VAL_AC_DS_MISSING
            The DS record covering a DNSKEY record was not
            available.

        VAL_AC_DATA_MISSING
            No data were returned for a query and the DNS
            did not indicate an error.

        VAL_AC_DNS_ERROR
            Some error was encountered during DNS
            processing.

        VAL_AC_NOT_VERIFIED
            All RRSIGs covering the RRset could not be
            verified.

        VAL_AC_VERIFIED
            At least one RRSIG covering a resource record
            had a status of VAL_AC_RRSIG_VERIFIED.

    val_ac_rrset
        Pointer to an RRset of type struct val_rrset_rec
        obtained from the DNS response.









                            ‐11‐


    val_ac_trust
        Pointer to an authentication chain element that
        either contains a DNSKEY RRset that can be used to
        verify RRSIGs over the current record, or contains a
        DS RRset that can be used to build the chain‐of‐
        trust towards a trust anchor.

struct val_rrset_rec
      struct val_rrset_rec
      {
          int    val_rrset_rcode;
          char   *val_rrset_name;
          int    val_rrset_class;
          int    val_rrset_type;
          long   val_rrset_ttl;
          int    val_rrset_section;
          struct sockaddr *val_rrset_server;
          struct val_rr_rec *val_rrset_data;
          struct val_rr_rec *val_rrset_sig;
      };

    val_rrset_rcode
        The rcode on the response header for this rrset.

    val_rrset_name
        Owner name of the RRset.

    val_rrset_class
        Class of the RRset.

    val_val_rrset_type
        Type of the RRset.

    val_rrset_ttl
        TTL of the RRset.

    val_rrset_section
        Section in which the RRset was received.  This value
        may be VAL_FROM_ANSWER, VAL_FROM_AUTHORITY, or
        VAL_FROM_ADDITIONAL.

    val_rrset_server
        The name server that returned this reponse.

    val_rrset_data
        Response RDATA.

    val_rrset_sig
        Any associated RRSIGs for the RDATA returned in
        val_rrset_data.

struct val_rr_rec











                            ‐12‐


      struct val_rr_rec
      {
          size_t            rr_rdata_length;
          unsigned char     *rr_rdata;
          struct val_rr_rec *rr_next;
          val_astatus_t     rr_status;
      };

    rr_rdata_length_h
        Length of data stored in rr_rdata.

    rr_rdata
        RDATA bytes.

    rr_status
        For each signature val_rr_rec member within the
        authentication chain val_ac_rrset, the validation
        status stored in the variable rr_status can return
        one of the following values:

            VAL_AC_RRSIG_VERIFIED
                The RRSIG verified successfully.

            VAL_AC_WCARD_VERIFIED
                A given RRSIG covering a resource record shows
                that the record was wildcard expanded.

            VAL_AC_RRSIG_VERIFIED_SKEW
                The RRSIG verified successfully after clock
                skew was taken into account.

            VAL_AC_WCARD_VERIFIED_SKEW
                A given RRSIG covering a resource record shows that
                the record was wildcard expanded, but it was verified
                only after clock skew was taken into account.

            VAL_AC_WRONG_LABEL_COUNT
                The number of labels on the signature was greater
                than the count given in the RRSIG RDATA.

            VAL_AC_INVALID_RRSIG
                The RRSIG could not be parsed.

            VAL_AC_RRSIG_NOTYETACTIVE
                The RRSIG's inception time is in the future.

            VAL_AC_RRSIG_EXPIRED
                The RRSIG had expired.

            VAL_AC_ALGORITHM_NOT_SUPPORTED
                The RRSIG algorithm was not supported.

            VAL_AC_RRSIG_VERIFY_FAILED
                A given RRSIG covering an RRset was bogus.









                            ‐13‐



            VAL_AC_RRSIG_ALGORITHM_MISMATCH
                The keytag referenced in the RRSIG matched a
                DNSKEY but the algorithms were different.

            VAL_AC_DNSKEY_NOMATCH
                An RRSIG was created by a DNSKEY that did not
                exist in the apex keyset.

        For each val_rr_rec member of type DNSKEY (or DS,
        where relevant) within the authentication chain
        val_ac_rrset, the validation status is stored in the
        variable rr_status and can return one of the
        following values:

            VAL_AC_TRUST_POINT
                The given DNSKEY or a DS record was configured
                as a DNSSEC trust anchor.

            VAL_AC_SIGNING_KEY
                This DNSKEY was used to create an RRSIG for
                the resource record set.

            VAL_AC_VERIFIED_LINK
                This DNSKEY provided the link in the authentication
                chain from the trust anchor to the signed record.

            VAL_AC_UNKNOWN_ALGORITHM_LINK
                This DNSKEY provided the link in the authentication
                chain from the trust anchor to the signed record,
                but the DNSKEY algorithm was unknown.

            VAL_AC_UNKNOWN_DNSKEY_PROTOCOL
                The DNSKEY protocol number was unrecognized.

            VAL_AC_ALGORITHM_NOT_SUPPORTED
                The DNSKEY or DS algorithm was not supported.

            VAL_AC_DS_NOMATCH
                An RRSIG was created with a key that did not
                exist in the parent DS record set.

            VAL_AC_INVALID_KEY
                The key used to verify the RRSIG was not a valid DNSKEY.

            VAL_AC_INVALID_DS
                The DS used to validate the DNSKEY could not be parsed.

rr_next
    Points to the next resource record in the RRset.













                            ‐14‐


libval provides the val_log_add_optarg() function for
controlling the verbosity and location of log message
output.

     The val_log_add_optarg() function takes two arguments:
the first argument args is a character‐string value that
specifies the location and verbosity.  The second argument,
use_stderr, if set to a value greater than 0 allows libval
to send log messages to stderr.

     The character string that specifies log target location
and verbosity has a specific format:

         <debug−level>:<dest−type>[:<dest−options>]

     where
    <debug−level> is 1−7, for increasing levels of verbosity
    <dest−type> is one of file, net, syslog, stderr, stdout
    <dest−options> depends on <dest−type>
        file:<file−name>   (opened in append mode)
        net[:<host−name>:<host−port>] (127.0.0.1:1053)
        syslog[:facility] (0−23 (default 1 USER))

     The log levels can be roughly translated into different
types of log messages as follows (the messages returned for
each level in this list subsumes the messages returned for
the level above it):

         3 : Error   : error encountered
    4 : Warning : recovering from error
    5 : Notice  : gives final validation results for a query
                  and details on policy files and labels used
    6 : Info    : gives details on authentication chains
    7 : Debug   : gives debug level information

Return values for various functions are given below. These
values can be displayed in ASCII format using the
p_val_error() function.

VAL_NO_ERROR
    No error was encountered.

VAL_NOT_IMPLEMENTED
    Functionality not yet implemented.

VAL_RESOURCE_UNAVAILABLE
    Some resource (crypto possibly) was unavailable.
    Currently not implemented.

VAL_BAD_ARGUMENT
    Bad arguments passed as parameters.

VAL_INTERNAL_ERROR
    Encountered some internal error.









                            ‐15‐


VAL_NO_PERMISSION
    No permission to perform operation.  Currently not
    implemented.

VAL_CONF_PARSE_ERROR
    Error in parsing some configuration file.

VAL_CONF_NOT_FOUND
    A configuration file was not available.

VAL_NO_POLICY
    The policy identifier being referenced was invalid.

The validator library reads configuration information from
two files, resolv.conf and dnsval.conf.

     See dnsval.conf(5) for a description of the syntax for
these files.

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

Suresh Krishnaswamy, Robert Story

libsres(3)

     dnsval.conf(5)

     http://www.dnssec−tools.org