p_ac_status(3) - Linux man page

Name

val_create_context(), val_create_context_with_conf(), val_free_context() - manage validator context

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

dnsval_conf_get(), resolv_conf_get(), root_hints_get() - get the default location for the validator configuration files

dnsval_conf_set(), resolv_conf_set(), root_hints_set() - set the default location for the validator configuration files

Synopsis

#include <validator.h>

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

int val_create_context_with_conf(char *label,
                       char *dnsval_conf,
                       char *resolv_conf,
                       char *root_conf,
                       val_context_t ** newcontext);

int val_resolve_and_check(val_context_t *context,
                       u_char *domain_name_n,
                       const u_int16_t class,
                       const u_int16_t type,
                       const u_int8_t  flags,
                       struct val_result_chain  **results);

char *p_val_status(val_status_t valerrno);

char *p_ac_status(val_astatus_t auth_chain_status);

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

void val_free_result_chain(struct val_result_chain *results);

void val_free_context(val_context_t *context);

char *resolv_conf_get(void);

int resolv_conf_set(const char *name);

char *root_hints_get(void);

int root_hints_set(const char *name);

char *dnsval_conf_get(void);

int dnsval_conf_set(const char *name);

Description

The val_resolve_and_check() function queries a set of name servers for the <domain_name_n, type, class> tuple and to verifies and validates the response. Verification involves checking the RRSIGs, and validation is verification of an authentication chain from a configured trust anchor. The domain_name_n parameter is the queried name in DNS wire format. The conversion from host format to DNS wire format can be done using the ns_name_pton() function exported by the libsres(3) library.

The flags parameter can be used to control the results of validation. Two values, which may be ORed together, are currently defined for this field. VAL_QUERY_DONT_VALIDATE causes the validator to disable validation for this query. VAL_QUERY_NO_DLV causes the validator to disable DLV processing for this query. The second flag is only available if the libval(3) library has been compiled with DLV support.

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 handle newcontext to this parsed information. Information stored as part of validator context includes the validation policy 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)). The default locations of each of these files may be changed using the interfaces dnsval_conf_set(), resolv_conf_set(), and root_hints_set(), respectively. The corresponding "get" interfaces (namely dnsval_conf_get(), resolv_conf_get(), and root_hints_get()) can be used to return the current location from where these configuration files are read. The configuration file locations may also be specified on a per-context basis using the val_create_context_with_conf() function.

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 and 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_val_status() and p_ac_status() functions respectively.

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.

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.

Data Structures

struct val_result_chain

struct val_result_chain
{
    val_status_t                     val_rc_status;
    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_status

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

VAL_SUCCESS
    Answer received and validated successfully.

VAL_LOCAL_ANSWER
    Answer was available from a local file.

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

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_DNS_CONFLICTING_ANSWERS
    Multiple conflicting answers received for a query.

VAL_DNS_QUERY_ERROR
    Some error was encountered while sending the query.

VAL_DNS_RESPONSE_ERROR
    No response returned or response with an error
    rcode value returned.

VAL_DNS_WRONG_ANSWER
    Wrong answer received for a query.

VAL_DNS_REFERRAL_ERROR
    Some error encountered while following referrals.

VAL_DNS_MISSING_GLUE
    Glue was missing.

VAL_BOGUS_PROVABLE
    Response could not be validated due to signature
    verification failures or the inability to verify
    proofs for exactly one component in the
    authentication chain below the trust anchor.

VAL_BOGUS
    Response could not be validated due to signature
    verification failures or the inability to verify
    proofs for an indeterminate number of components
    in the authentication chain.

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

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

VAL_TRUSTED_ZONE
    Local policy was configured to trust
    any data received from the given zone.

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

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

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

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                *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 was not set.

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

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_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_TRUST_KEY
    A given DNSKEY or a DS record was locally
    defined to be a trust anchor.

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_TRUSTED_ZONE
    Local policy defined a given zone as trusted, with
    no further validation being deemed necessary.

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

VAL_AC_PROVABLY_UNSECURE
    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_TRUST_ANCHOR
    There was no trust anchor configured for a given
    authentication chain.

VAL_AC_DNS_CONFLICTING_ANSWERS
    Multiple conflicting answers received for a query.

VAL_AC_DNS_QUERY_ERROR
    Some error was encountered while sending the query.

VAL_AC_DNS_RESPONSE_ERROR
    No response returned or response with an error
    rcode value returned.

VAL_AC_DNS_WRONG_ANSWER
    Wrong answer received for a query.

VAL_AC_DNS_REFERRAL_ERROR
    Some error encountered while following referrals.

VAL_AC_DNS_MISSING_GLUE
    Glue was missing.

val_ac_rrset

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

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

struct val_rrset
{
    u_int8_t      *val_msg_header;
    u_int16_t      val_msg_headerlen;
    u_int8_t      *val_rrset_name_n;
    u_int16_t      val_rrset_class_h;
    u_int16_t      val_rrset_type_h;
    u_int32_t      val_rrset_ttl_h;
    u_int32_t      val_rrset_ttl_x;
    u_int8_t       val_rrset_section;
    struct rr_rec *val_rrset_data;
    struct rr_rec *val_rrset_sig;
};

val_msg_header

Header of the DNS response in which the RRset was received.

val_msg_headerlen

Length of the header information in val_msg_header.

val_rrset_name_n

Owner name of the RRset represented in on-the-wire format.

val_rrset_class_h

Class of the RRset.

val_val_rrset_type_h

Type of the RRset.

val_rrset_ttl_h

TTL of the RRset.

val_rrset_ttl_x

The time when the TTL for this RRset is set to expire.

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_data

Response RDATA .

val_rrset_sig

Any associated RRSIGs for the RDATA returned in val_rrset_data.

struct rr_rec

struct rr_rec
{
    u_int16_t        rr_rdata_length_h;
    u_int8_t        *rr_rdata;
    val_astatus_t    rr_status;
    struct rr_rec   *rr_next;
};

rr_rdata_length_h

Length of data stored in rr_rdata.

rr_rdata

RDATA bytes.

rr_status

For each signature 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_RRSIG_VERIFY_FAILED
    A given RRSIG covering an RRset was bogus.

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

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

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

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

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

VAL_AC_RRSIG_EXPIRED
    The RRSIG had expired.

VAL_AC_INVALID_RRSIG
    The RRSIG could not be parsed.

VAL_AC_ALGORITHM_NOT_SUPPORTED
    The RRSIG algorithm was not supported.

For each 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_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_DNSKEY_PROTOCOL
    The DNSKEY protocol number was unrecognized.

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_INVALID_KEY
    The key used to verify the RRSIG was not a valid
    DNSKEY.

VAL_AC_ALGORITHM_NOT_SUPPORTED
    The DNSKEY or DS algorithm was not supported.

rr_next

Points to the next resource record in the RRset.

Return Values

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

val_resolve_and_check(): VAL_NO_ERROR; No error was encountered.; VAL_GENERIC_ERROR; Generic error encountered.; VAL_NOT_IMPLEMENTED; Functionality not yet implemented.; VAL_BAD_ARGUMENT; Bad arguments passed as parameters.; VAL_INTERNAL_ERROR; Encountered some internal error.; VAL_NO_PERMISSION; No permission to perform operation. Currently not implemented.; VAL_RESOURCE_UNAVAILABLE; Some resource (crypto possibly) was unavailable. Currently not implemented.
val_create_context() and val_create_context_with_conf(): VAL_NO_ERROR; No error was encountered.; VAL_RESOURCE_UNAVAILABLE; Could not allocate memory.; 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.

Files

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

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

Copyright

Authors

Suresh Krishnaswamy, Robert Story