.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "libval 3" .TH libval 3 "2013-01-02" "perl v5.18.1" "Programmer's Manual" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" val_create_context() val_free_context() \- manage validator context .PP val_context_setqflags() \- manage validator context flags .PP val_resolve_and_check(), val_free_result_chain() \- query and validate answers from a DNS name server .PP val_istrusted() \- check if status value corresponds to that of a trustworthy answer .PP val_isvalidated() \- check if status value represents an answer that cryptographically chains down from a configured trust anchor .PP val_does_not_exist() \- check if status value represents one of the non\-existence types .PP p_val_status(), p_ac_status(), p_val_error() \- display validation status, authentication chain status and error information .PP val_log_add_optarg \- control log message verbosity and output location .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& 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); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fI\fIval_resolve_and_check()\fI\fR function queries a set of name servers for the \fI 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. .PP The \fIflags\fR parameter can be used to control the results of validation. The following values, which may be ORed together, are currently defined for this field: .IP "\fB\s-1VAL_QUERY_DONT_VALIDATE\s0\fR" 4 .IX Item "VAL_QUERY_DONT_VALIDATE" causes the validator to disable validation for this query. .IP "\fB\s-1VAL_QUERY_IGNORE_SKEW\s0\fR" 4 .IX Item "VAL_QUERY_IGNORE_SKEW" causes the validator to disable checking signature inception and expiration times on RRSIGs. .IP "\fB\s-1VAL_QUERY_AC_DETAIL\s0\fR" 4 .IX Item "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. .IP "\fB\s-1VAL_QUERY_ASYNC\s0\fR" 4 .IX Item "VAL_QUERY_ASYNC" enables asynchronous query resolution for that lookup. .IP "\fB\s-1VAL_QUERY_NO_DLV\s0\fR" 4 .IX Item "VAL_QUERY_NO_DLV" causes the validator to disable \s-1DLV\s0 processing for this query. This is only available if the \fI\fIlibval\fI\|(3)\fR library has been compiled with \s-1DLV\s0 support. .IP "\fB\s-1VAL_QUERY_NO_EDNS0_FALLBACK\s0\fR" 4 .IX Item "VAL_QUERY_NO_EDNS0_FALLBACK" In querying various name servers, libsres will also attempt multiple \s-1EDNS0\s0 sizes, ending with a query that has \s-1EDNS0\s0 disabled (i.e. no \s-1CD\s0 bit set). This option causes libval to disable \s-1EDNS0\s0 fallback for the query. .IP "\fB\s-1VAL_QUERY_RECURSE\s0\fR" 4 .IX Item "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 \fBdnsval.conf\fR .IP "\fB\s-1VAL_QUERY_SKIP_RESOLVER\s0\fR" 4 .IX Item "VAL_QUERY_SKIP_RESOLVER" forces libval to only look at its cache while trying to resolve a name. .IP "\fB\s-1VAL_QUERY_SKIP_CACHE\s0\fR" 4 .IX Item "VAL_QUERY_SKIP_CACHE" forces libval to ignore cached data while trying to resolve a name. .PP The first parameter to \fI\fIval_resolve_and_check()\fI\fR is the validator context. Applications can create a new validator context using the \&\fI\fIval_create_context()\fI\fR function. This function parses the resolver and validator configuration files and creates the handle \fInewcontext\fR to this parsed information. Information stored as part of validator context includes the validation policy and resolver policy. .PP Validator and resolver policies are read from the \fB/etc/dnsval.conf\fR and \&\fB/etc/resolv.conf\fR files by default. \fB/etc/root.hints\fR provides bootstrapping information for the validator when it functions as a full resolver (see \fI\fIdnsval.conf\fI\|(3)\fR). 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. .PP Default query flags can be set and unset for a given context using \&\fI\fIval_context_setqflags()\fI\fR. This allows an application to alter the \&\s-1DNSSEC\s0 validator processing, while still having most of the more granular default configuration specified in its configuration file. The \fIaction\fR parameter can be set to one of the following. .IP "\fB\s-1VAL_CTX_FLAG_SET\s0\fR" 4 .IX Item "VAL_CTX_FLAG_SET" causes the validator to set the given flag as one of the default query flags. .IP "\fB\s-1VAL_CTX_FLAG_RESET\s0\fR" 4 .IX Item "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. .PP Answers returned by \fI\fIval_resolve_and_check()\fI\fR are made available in the \&\fI*results\fR 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 \&\fItype\fR is \fIns_t_any\fR or \fIns_t_rrsig\fR. .PP Individual elements in \fI*results\fR point to \fIval_authentication_chain\fR linked lists. The authentication chain elements in \fIval_authentication_chain\fR contain the actual RRsets returned by the name server in response to the query. .PP Validation result values returned in \fIval_result_chain\fR and authentication chain status values returned in each element of the \&\fIval_authentication_chain\fR linked list can be can be converted into \s-1ASCII\s0 format using the \fI\fIp_val_status()\fI\fR and \fI\fIp_ac_status()\fI\fR functions respectively. .PP While some applications such as \s-1DNSSEC\s0 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. .PP \&\fI\fIval_isvalidated()\fI\fR identifies if a given validation result status value corresponds to an answer that was cryptographically verified and validated using a locally configured trust anchor. .PP \&\fI\fIval_istrusted()\fI\fR identifies if a given validator status value is trusted. An answer may be locally trusted without being validated. .PP \&\fI\fIval_does_not_exist()\fI\fR identifies if a given validator status value corresponds to one of the non-existence types. .PP The \fIlibval\fR library internally allocates memory for \fI*results\fR and this must be freed by the invoking application using the \fI\fIfree_result_chain()\fI\fR interface. .SH "DATA STRUCTURES" .IX Header "DATA STRUCTURES" .IP "\fIstruct val_result_chain\fR" 4 .IX Item "struct val_result_chain" .Vb 10 \& 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; \& }; .Ve .RS 4 .IP "\fIval_rc_answer\fR" 4 .IX Item "val_rc_answer" Authentication chain for a given RRset. .IP "\fIval_rc_next\fR" 4 .IX Item "val_rc_next" Pointer to the next RRset in the set of answers returned for a query. .IP "\fIval_rc_proofs\fR" 4 .IX Item "val_rc_proofs" Pointer to authentication chains for any proof of non-existence that were returned for the query. .IP "\fIval_rc_proof_count\fR" 4 .IX Item "val_rc_proof_count" Number of proof elements stored in \fIval_rc_proofs\fR. The number cannot exceed \&\fB\s-1MAX_PROOFS\s0\fR. .IP "\fIval_rc_alias\fR" 4 .IX Item "val_rc_alias" For an val_result_chain element that points to a name alias, this field contains the target value. .IP "\fIval_rc_rrset\fR" 4 .IX Item "val_rc_rrset" For an val_result_chain element that contains a valid (not \s-1NULL\s0) 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. .IP "\fIval_rc_status\fR" 4 .IX Item "val_rc_status" Validation status for a given RRset. This can be one of the following: .RS 4 .IP "\s-1VAL_SUCCESS\s0" 4 .IX Item "VAL_SUCCESS" Answer received and validated successfully. .IP "\s-1VAL_NONEXISTENT_NAME\s0" 4 .IX Item "VAL_NONEXISTENT_NAME" No name was present and a valid proof of non\- existence confirming the missing name (\s-1NSEC\s0 or \&\s-1NSEC3\s0 span) was returned. The components of the proof were also individually validated. .IP "\s-1VAL_NONEXISTENT_TYPE\s0" 4 .IX Item "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. .IP "\s-1VAL_NONEXISTENT_NAME_NOCHAIN\s0" 4 .IX Item "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. .IP "\s-1VAL_NONEXISTENT_TYPE_NOCHAIN\s0" 4 .IX Item "VAL_NONEXISTENT_TYPE_NOCHAIN" No type exists for the name and a valid proof of non-existence confirming the missing name (\s-1NSEC\s0 or \s-1NSEC3\s0 span) was returned. The components of the proof were also identified to be trustworthy, but they were not individually validated. .IP "\s-1VAL_PINSECURE\s0" 4 .IX Item "VAL_PINSECURE" The record or some ancestor of the record in the authentication chain towards the trust anchor was known to be provably insecure. .IP "\s-1VAL_PINSECURE_UNTRUSTED\s0" 4 .IX Item "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. .IP "\s-1VAL_BARE_RRSIG\s0" 4 .IX Item "VAL_BARE_RRSIG" No \s-1DNSSEC\s0 validation possible, query was for an \s-1RRSIG.\s0 .IP "\s-1VAL_IGNORE_VALIDATION\s0" 4 .IX Item "VAL_IGNORE_VALIDATION" Local policy was configured to ignore validation for the zone from which this data was received. .IP "\s-1VAL_UNTRUSTED_ZONE\s0" 4 .IX Item "VAL_UNTRUSTED_ZONE" Local policy was configured to reject any data received from the given zone. .IP "\s-1VAL_OOB_ANSWER\s0" 4 .IX Item "VAL_OOB_ANSWER" Answer was obtained using some Out of Band method, such as a local configuration file. .IP "\s-1VAL_BOGUS\s0" 4 .IX Item "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. .IP "\s-1VAL_DNS_ERROR \s0" 4 .IX Item "VAL_DNS_ERROR " Some error was encountered during \s-1DNS\s0 processing. .IP "\s-1VAL_NOTRUST\s0" 4 .IX Item "VAL_NOTRUST" All available components in the authentication chain verified properly, but there was no trust anchor available. .RE .RS 4 .Sp Status values in \fIval_status_t\fR returned by the validator can be displayed in \s-1ASCII\s0 format using \fI\fIp_val_status()\fI\fR. .RE .RE .RS 4 .RE .IP "\fIstruct val_authentication_chain\fR" 4 .IX Item "struct val_authentication_chain" .Vb 6 \& struct val_authentication_chain \& { \& val_astatus_t val_ac_status; \& struct val_rrset_rec *val_ac_rrset; \& struct val_authentication_chain *val_ac_trust; \& }; .Ve .RS 4 .IP "\fIval_ac_status\fR" 4 .IX Item "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: .RS 4 .IP "\s-1VAL_AC_UNSET\s0" 4 .IX Item "VAL_AC_UNSET" The status could not be determined. .IP "\s-1VAL_AC_IGNORE_VALIDATION\s0" 4 .IX Item "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. .IP "\s-1VAL_AC_UNTRUSTED_ZONE\s0" 4 .IX Item "VAL_AC_UNTRUSTED_ZONE" Local policy defined a given zone as untrusted, with no further validation being deemed necessary. .IP "\s-1VAL_AC_PINSECURE\s0" 4 .IX Item "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 \s-1DS\s0 record for this zone in the parent. .IP "\s-1VAL_AC_BARE_RRSIG\s0" 4 .IX Item "VAL_AC_BARE_RRSIG" The response was for a query of type \s-1RRSIG. \s0 RRSIGs contain the cryptographic signatures for other \s-1DNS\s0 data and cannot themselves be validated. .IP "\s-1VAL_AC_NO_LINK\s0" 4 .IX Item "VAL_AC_NO_LINK" There was no trust anchor configured for a given authentication chain or the chain didn't link up. .IP "\s-1VAL_AC_TRUST\s0" 4 .IX Item "VAL_AC_TRUST" At least one of the signatures covering the given \&\s-1DNSKEY\s0 RRset was directly verified using a key that was configured as a \s-1DNSSEC\s0 trust anchor. .IP "\s-1VAL_AC_RRSIG_MISSING\s0" 4 .IX Item "VAL_AC_RRSIG_MISSING" \&\s-1RRSIG\s0 data could not be retrieved for a resource record. .IP "\s-1VAL_AC_DNSKEY_MISSING\s0" 4 .IX Item "VAL_AC_DNSKEY_MISSING" The \s-1DNSKEY\s0 for an \s-1RRSIG\s0 covering a resource record could not be retrieved. .IP "\s-1VAL_AC_DS_MISSING\s0" 4 .IX Item "VAL_AC_DS_MISSING" The \s-1DS\s0 record covering a \s-1DNSKEY\s0 record was not available. .IP "\s-1VAL_AC_DATA_MISSING\s0" 4 .IX Item "VAL_AC_DATA_MISSING" No data were returned for a query and the \&\s-1DNS\s0 did not indicate an error. .IP "\s-1VAL_AC_DNS_ERROR\s0" 4 .IX Item "VAL_AC_DNS_ERROR" Some error was encountered during \s-1DNS\s0 processing. .IP "\s-1VAL_AC_NOT_VERIFIED\s0" 4 .IX Item "VAL_AC_NOT_VERIFIED" All RRSIGs covering the RRset could not be verified. .IP "\s-1VAL_AC_VERIFIED\s0" 4 .IX Item "VAL_AC_VERIFIED" At least one \s-1RRSIG\s0 covering a resource record had a status of \s-1VAL_AC_RRSIG_VERIFIED.\s0 .RE .RS 4 .RE .IP "\fIval_ac_rrset\fR" 4 .IX Item "val_ac_rrset" Pointer to an RRset of type \fIstruct val_rrset_rec\fR obtained from the \s-1DNS\s0 response. .IP "\fIval_ac_trust\fR" 4 .IX Item "val_ac_trust" Pointer to an authentication chain element that either contains a \s-1DNSKEY\s0 RRset that can be used to verify RRSIGs over the current record, or contains a \s-1DS\s0 RRset that can be used to build the chain-of-trust towards a trust anchor. .RE .RS 4 .RE .IP "\fIstruct val_rrset_rec\fR" 4 .IX Item "struct val_rrset_rec" .Vb 12 \& 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; \& }; .Ve .RS 4 .IP "\fIval_rrset_rcode\fR" 4 .IX Item "val_rrset_rcode" The rcode on the response header for this rrset. .IP "\fIval_rrset_name\fR" 4 .IX Item "val_rrset_name" Owner name of the RRset. .IP "\fIval_rrset_class\fR" 4 .IX Item "val_rrset_class" Class of the RRset. .IP "\fIval_val_rrset_type\fR" 4 .IX Item "val_val_rrset_type" Type of the RRset. .IP "\fIval_rrset_ttl\fR" 4 .IX Item "val_rrset_ttl" \&\s-1TTL\s0 of the RRset. .IP "\fIval_rrset_section\fR" 4 .IX Item "val_rrset_section" Section in which the RRset was received. This value may be \fB\s-1VAL_FROM_ANSWER\s0\fR, \&\fB\s-1VAL_FROM_AUTHORITY\s0\fR, or \fB\s-1VAL_FROM_ADDITIONAL\s0\fR. .IP "\fIval_rrset_server\fR" 4 .IX Item "val_rrset_server" The name server that returned this reponse. .IP "\fIval_rrset_data\fR" 4 .IX Item "val_rrset_data" Response \s-1RDATA.\s0 .IP "\fIval_rrset_sig\fR" 4 .IX Item "val_rrset_sig" Any associated RRSIGs for the \s-1RDATA\s0 returned in \fIval_rrset_data\fR. .RE .RS 4 .RE .IP "\fIstruct val_rr_rec\fR" 4 .IX Item "struct val_rr_rec" .Vb 7 \& struct val_rr_rec \& { \& size_t rr_rdata_length; \& unsigned char *rr_rdata; \& struct val_rr_rec *rr_next; \& val_astatus_t rr_status; \& }; .Ve .RS 4 .IP "\fIrr_rdata_length_h\fR" 4 .IX Item "rr_rdata_length_h" Length of data stored in \fIrr_rdata\fR. .IP "\fIrr_rdata\fR" 4 .IX Item "rr_rdata" \&\s-1RDATA\s0 bytes. .IP "\fIrr_status\fR" 4 .IX Item "rr_status" For each signature \fIval_rr_rec\fR member within the authentication chain \&\fIval_ac_rrset\fR, the validation status stored in the variable \&\fIrr_status\fR can return one of the following values: .Sp .Vb 2 \& 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\*(Aqs 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. .Ve .Sp For each \fIval_rr_rec\fR member of type \s-1DNSKEY \s0(or \s-1DS,\s0 where relevant) within the authentication chain \fIval_ac_rrset\fR, the validation status is stored in the variable \fIrr_status\fR and can return one of the following values: .Sp .Vb 3 \& 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 .Ve .IP "\fIrr_next\fR" 4 .IX Item "rr_next" Points to the next resource record in the RRset. .RE .RS 4 .RE .SH "LOGGING" .IX Header "LOGGING" libval provides the \fIval_log_add_optarg()\fR function for controlling the verbosity and location of log message output. .PP The \fIval_log_add_optarg()\fR 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. .PP The character string that specifies log target location and verbosity has a specific format: .PP .Vb 1 \& :[:] .Ve .PP where is 1\-7, for increasing levels of verbosity is one of file, net, syslog, stderr, stdout depends on file: (opened in append mode) net[::] (127.0.0.1:1053) syslog[:facility] (0\-23 (default 1 \s-1USER\s0)) .PP 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): .PP .Vb 6 \& 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 .Ve .SH "RETURN VALUES" .IX Header "RETURN VALUES" Return values for various functions are given below. These values can be displayed in \s-1ASCII\s0 format using the \fI\fIp_val_error()\fI\fR function. .IP "\s-1VAL_NO_ERROR\s0" 4 .IX Item "VAL_NO_ERROR" No error was encountered. .IP "\s-1VAL_NOT_IMPLEMENTED\s0" 4 .IX Item "VAL_NOT_IMPLEMENTED" Functionality not yet implemented. .IP "\s-1VAL_RESOURCE_UNAVAILABLE\s0" 4 .IX Item "VAL_RESOURCE_UNAVAILABLE" Some resource (crypto possibly) was unavailable. Currently not implemented. .IP "\s-1VAL_BAD_ARGUMENT\s0" 4 .IX Item "VAL_BAD_ARGUMENT" Bad arguments passed as parameters. .IP "\s-1VAL_INTERNAL_ERROR\s0" 4 .IX Item "VAL_INTERNAL_ERROR" Encountered some internal error. .IP "\s-1VAL_NO_PERMISSION\s0" 4 .IX Item "VAL_NO_PERMISSION" No permission to perform operation. Currently not implemented. .IP "\s-1VAL_CONF_PARSE_ERROR\s0" 4 .IX Item "VAL_CONF_PARSE_ERROR" Error in parsing some configuration file. .IP "\s-1VAL_CONF_NOT_FOUND\s0" 4 .IX Item "VAL_CONF_NOT_FOUND" A configuration file was not available. .IP "\s-1VAL_NO_POLICY\s0" 4 .IX Item "VAL_NO_POLICY" The policy identifier being referenced was invalid. .SH "FILES" .IX Header "FILES" The validator library reads configuration information from two files, \&\fBresolv.conf\fR and \fBdnsval.conf\fR. .PP See \fB\f(BIdnsval.conf\fB\|(5)\fR for a description of syntax for these files. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2004\-2013 \s-1SPARTA,\s0 Inc. All rights reserved. See the \s-1COPYING\s0 file included with the dnssec-tools package for details. .SH "AUTHORS" .IX Header "AUTHORS" Suresh Krishnaswamy, Robert Story .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fI\fIlibsres\fI\|(3)\fR .PP \&\fB\f(BIdnsval.conf\fB\|(5)\fR .PP http://www.dnssec\-tools.org