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_resolve_and_check(val_context_t *context,
char *domain_name,
int class,
int type,
const u_int32_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);
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 flags parameter can be used to control the results of validation. Three 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_AC_DETAIL causes the validator to leave the authentication chain details in val_rc_answer and val_rc_proofs empty (NULL). 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)).
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.
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_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
{
val_astatus_t val_ac_status;
struct val_rrset_rec *val_ac_rrset;
struct val_authentication_chain *val_ac_trust;
};
VAL_AC_UNSET
The status was not set.
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.
struct val_rrset_rec
{
int val_rrset_rcode;
char *val_rrset_name;
u_int16_t val_rrset_class;
u_int16_t val_rrset_type;
u_int32_t val_rrset_ttl;
u_int8_t val_rrset_section;
struct sockaddr *val_rrset_server;
struct val_rr_rec *val_rrset_data;
struct val_rr_rec *val_rrset_sig;
};
struct val_rr_rec
{
size_t rr_rdata_length;
u_char *rr_rdata;
struct val_rr_rec *rr_next;
val_astatus_t rr_status;
};
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
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
See dnsval.conf(5) for a description of syntax for these files.
dnsval.conf(5)
http://dnssec-tools.sourceforge.net