Provided by: libval-dev_2.0-1.1ubuntu1_amd64 
NAME
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
SYNOPSIS
#include <validator.h>
int val_create_context(const char *label, val_context_t **newcontext);
int val_context_setqflags(val_context_t *context,
unsigned char action,
unsigned int flags);
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);
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);
DESCRIPTION
The val_resolve_and_check() function queries a set of name servers for the <domain_name, 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 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
causes the validator to disable validation for this query.
VAL_QUERY_IGNORE_SKEW
causes the validator to disable checking signature inception and expiration times on RRSIGs.
VAL_QUERY_AC_DETAIL
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
enables asynchronous query resolution for that lookup.
VAL_QUERY_NO_DLV
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 will also attempt multiple EDNS0 sizes, ending with a query
that has EDNS0 disabled (i.e. no CD bit set). This option causes libval to disable EDNS0 fallback
for the query.
VAL_QUERY_RECURSE
forces libval to recursively answer the query by iteratively 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
forces libval to only look at its cache while trying to resolve a name.
VAL_QUERY_SKIP_CACHE
forces libval to ignore cached data while trying to resolve a name.
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)). 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 fallback to /etc/resolv.conf as a last resort.
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
causes the validator to set the given flag as one of the default query flags.
VAL_CTX_FLAG_RESET
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 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;
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 an 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:
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.
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 for an indeterminate number of components in the authentication chain.
VAL_DNS_ERROR
Some error was encountered during DNS processing.
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.
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.
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
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.
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 validatate the DNSKEY could not be
parsed
=back
rr_next
Points to the next resource record in the RRset.
LOGGING
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 : errror 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
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.
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.
FILES
The validator library reads configuration information from two files, resolv.conf and dnsval.conf.
See dnsval.conf(5) for a description of syntax for these files.
COPYRIGHT
Copyright 2004-2013 SPARTA, Inc. All rights reserved. See the COPYING file included with the dnssec-
tools package for details.
AUTHORS
Suresh Krishnaswamy, Robert Story
SEE ALSO
libsres(3)
dnsval.conf(5)
http://www.dnssec-tools.org