1libval(3) Programmer's Manual libval(3)
2
6 val_create_context() val_free_context() - manage validator context
7 val_resolve_and_check(), val_free_result_chain() - query and validate
9 answers from a DNS name server
10 val_istrusted() - check if status value corresponds to that of a trust‐
12 worthy answer
13 val_isvalidated() - check if status value represents an answer that
15 cryptographically chains down from a configured trust anchor
16 val_does_not_exist() - check if status value represents one of the
18 non-existence types
19 p_val_status(), p_ac_status(), p_val_error() - display validation sta‐
21 tus, authentication chain status and error information
22 val_log_add_optarg - control log message verbosity and output location
24
26 #include <validator.h>
27 int val_create_context(const char *label, val_context_t **newcontext);
29 int val_resolve_and_check(val_context_t *context,
31 const char *domain_name,
32 int class,
33 int type,
34 unsigned int flags,
35 struct val_result_chain **results);
36 char *p_val_status(val_status_t valerrno);
38 char *p_ac_status(val_astatus_t auth_chain_status);
40 char *p_val_error(int err);
42 int val_istrusted(val_status_t val_status);
44 int val_isvalidated(val_status_t val_status);
46 int val_does_not_exist(val_status_t status);
48 val_log_t *val_log_add_optarg(const char *args, int use_stderr);
50 void val_free_result_chain(struct val_result_chain *results);
52 void val_free_context(val_context_t *context);
54
56 The val_resolve_and_check() function queries a set of name servers for
57 the <domain_name, type, class> tuple and to verifies and validates the
58 response. Verification involves checking the RRSIGs, and validation is
59 verification of an authentication chain from a configured trust anchor.
60 The flags parameter can be used to control the results of validation.
62 The following values, which may be ORed together, are currently defined
63 for this field:
64 VAL_QUERY_DONT_VALIDATE
66 causes the validator to disable validation for this query.
67 VAL_QUERY_AC_DETAIL
69 causes the validator to copy the authentication chain details into
70 the val_rc_answer member within the returned val_result_chain
71 structure.
72 VAL_QUERY_ASYNC
74 enables asynchronous query resolution for that lookup.
75 VAL_QUERY_NO_DLV
77 causes the validator to disable DLV processing for this query.
78 This is only available if the libval(3) library has been compiled
79 with DLV support.
80 VAL_QUERY_NO_EDNS0_FALLBACK In querying various name servers, libsres
82 will also attempt multiple EDNS0 sizes, ending with a query that has
83 EDNS0 disabled (i.e. no CD bit set). This option causes libval to dis‐
84 able EDNS0 fallback for the query.
85 VAL_QUERY_RECURSE forces libval to recursively answer the query by
86 iteratively querying various name servers in the delegation hierarchy,
87 instead of requesting this information from any caching name server
88 that may be configured in dnsval.conf
89 VAL_QUERY_REFRESH_QCACHE forces libval to fetch lookup information from
90 other name servers instead of looking for this data in its local cache.
91 The first parameter to val_resolve_and_check() is the validator con‐
93 text. Applications can create a new validator context using the
94 val_create_context() function. This function parses the resolver and
95 validator configuration files and creates the handle newcontext to this
96 parsed information. Information stored as part of validator context
97 includes the validation policy and resolver policy.
98 Validator and resolver policies are read from the /etc/dnsval.conf and
100 /etc/resolv.conf files by default. /etc/root.hints provides bootstrap‐
101 ping information for the validator when it functions as a full resolver
102 (see dnsval.conf(3)). These defaults may be different if any other
103 value was specified at library configure time. If the default resolver
104 configuration file is not found at the specified location, libval will
105 also try to fallback to /etc/resolv.conf as a last resort.
106 Answers returned by val_resolve_and_check() are made available in the
108 *results linked list. Each answer corresponds to a distinct RRset;
109 multiple RRs within the RRset are part of the same answer. Multiple
110 answers are possible when type is ns_t_any or ns_t_rrsig.
111 Individual elements in *results point to val_authentication_chain
113 linked lists. The authentication chain elements in val_authentica‐
114 tion_chain contain the actual RRsets returned by the name server in
115 response to the query.
116 Validation result values returned in val_result_chain and authentica‐
118 tion chain status values returned in each element of the val_authenti‐
119 cation_chain linked list can be can be converted into ASCII format
120 using the p_val_status() and p_ac_status() functions respectively.
121 While some applications such as DNSSEC troubleshooting utilities and
123 packet inspection tools may look at individual authentication chain
124 elements to identify the actual reasons for validation error, most
125 applications will only be interested in a single error code for deter‐
126 mining the authenticity of data.
127 val_isvalidated() identifies if a given validation result status value
129 corresponds to an answer that was cryptographically verified and vali‐
130 dated using a locally configured trust anchor.
131 val_istrusted() identifies if a given validator status value is
133 trusted. An answer may be locally trusted without being validated.
134 val_does_not_exist() identifies if a given validator status value cor‐
136 responds to one of the non-existence types.
137 The libval library internally allocates memory for *results and this
139 must be freed by the invoking application using the free_result_chain()
140 interface.
141
143 struct val_result_chain
144 struct val_result_chain
145 {
146 val_status_t val_rc_status;
147 char *val_rc_alias;
148 struct val_rrset_rec *val_rc_rrset;
149 struct val_authentication_chain *val_rc_answer;
150 int val_rc_proof_count;
151 struct val_authentication_chain *val_rc_proofs[MAX_PROOFS];
152 struct val_result_chain *val_rc_next;
153 };
154 val_rc_answer
156 Authentication chain for a given RRset.
157 val_rc_next
159 Pointer to the next RRset in the set of answers returned for a
160 query.
161 val_rc_proofs
163 Pointer to authentication chains for any proof of non-existence
164 that were returned for the query.
165 val_rc_proof_count
167 Number of proof elements stored in val_rc_proofs. The number
168 cannot exceed MAX_PROOFS.
169 val_rc_alias
171 For an val_result_chain element that points to a name alias,
172 this field contains the target value.
173 val_rc_rrset
175 For an val_result_chain element that contains a valid (not
176 NULL) val_rc_answer field, the val_rc_rrset field points to the
177 top-most val_rrset_rec element in the val_rc_answer authentica‐
178 tion chain.
179 val_rc_status
181 Validation status for a given RRset. This can be one of the
182 following:
183 VAL_SUCCESS
185 Answer received and validated successfully.
186 VAL_NONEXISTENT_NAME
188 No name was present and a valid proof of non-
189 existence confirming the missing name (NSEC or
190 NSEC3 span) was returned. The components of
191 the proof were also individually validated.
192 VAL_NONEXISTENT_TYPE
194 No type exists for the name and a valid proof
195 of non-existence confirming the missing name
196 was returned. The components of the proof
197 were also individually validated.
198 VAL_NONEXISTENT_NAME_NOCHAIN
200 No name was present and a valid proof of non-
201 existence confirming the missing name was
202 returned. The components of the proof were also
203 identified to be trustworthy, but they were
204 not individually validated.
205 VAL_NONEXISTENT_TYPE_NOCHAIN
207 No type exists for the name and a valid proof
208 of non-existence confirming the missing name
209 (NSEC or NSEC3 span) was returned. The
210 components of the proof were also identified
211 to be trustworthy, but they were not
212 individually validated.
213 VAL_PINSECURE
215 The record or some ancestor of the record in
216 the authentication chain towards the trust
217 anchor was known to be provably insecure.
218 VAL_PINSECURE_UNTRUSTED
220 The record or some ancestor of the record in the
221 authentication chain towards the trust anchor was
222 known to be provably insecure. But the provably
223 insecure condition was configured as untrustworthy.
224 VAL_BARE_RRSIG
226 No DNSSEC validation possible, query was
227 for an RRSIG.
228 VAL_IGNORE_VALIDATION
230 Local policy was configured to ignore validation
231 for the zone from which this data was received.
232 VAL_UNTRUSTED_ZONE
234 Local policy was configured to reject
235 any data received from the given zone.
236 VAL_OOB_ANSWER
238 Answer was obtained using some Out of Band
239 method, such as a local configuration file.
240 VAL_BOGUS
242 Response could not be validated due to signature
243 verification failures or the inability to verify
244 proofs for an indeterminate number of components
245 in the authentication chain.
246 VAL_DNS_ERROR
248 Some error was encountered during DNS processing.
249 VAL_NOTRUST
251 All available components in the authentication
252 chain verified properly, but there was no trust
253 anchor available.
254 Status values in val_status_t returned by the validator can be
256 displayed in ASCII format using p_val_status().
257 struct val_authentication_chain
259 struct val_authentication_chain
260 {
261 val_astatus_t val_ac_status;
262 struct val_rrset_rec *val_ac_rrset;
263 struct val_authentication_chain *val_ac_trust;
264 };
265 val_ac_status
267 Validation state of the authentication chain element. This
268 field will contain the status code for the given component in
269 the authentication chain. This field may contain one of the
270 following values:
271 VAL_AC_UNSET
273 The status could not be determined.
274 VAL_AC_IGNORE_VALIDATION
276 Validation for the given resource record was ignored,
277 either because of some local policy directive or
278 because of some protocol-specific behavior.
279 VAL_AC_UNTRUSTED_ZONE
281 Local policy defined a given zone as untrusted,
282 with no further validation being deemed necessary.
283 VAL_AC_PINSECURE
285 The authentication chain from a trust anchor to a
286 given zone could not be constructed due to the
287 provable absence of a DS record for this zone in
288 the parent.
289 VAL_AC_BARE_RRSIG
291 The response was for a query of type RRSIG. RRSIGs
292 contain the cryptographic signatures for other DNS
293 data and cannot themselves be validated.
294 VAL_AC_NO_LINK
296 There was no trust anchor configured for a given
297 authentication chain or the chain didn't link up.
298 VAL_AC_TRUST
300 At least one of the signatures covering the given
301 DNSKEY RRset was directly verified using a key that was
302 configured as a DNSSEC trust anchor.
303 VAL_AC_RRSIG_MISSING
305 RRSIG data could not be retrieved for a
306 resource record.
307 VAL_AC_DNSKEY_MISSING
309 The DNSKEY for an RRSIG covering a resource
310 record could not be retrieved.
311 VAL_AC_DS_MISSING
313 The DS record covering a DNSKEY record was
314 not available.
315 VAL_AC_DATA_MISSING
317 No data were returned for a query and the
318 DNS did not indicate an error.
319 VAL_AC_DNS_ERROR
321 Some error was encountered during DNS processing.
322 VAL_AC_NOT_VERIFIED
324 All RRSIGs covering the RRset could not
325 be verified.
326 VAL_AC_VERIFIED
328 At least one RRSIG covering a resource
329 record had a status of VAL_AC_RRSIG_VERIFIED.
330 val_ac_rrset
332 Pointer to an RRset of type struct val_rrset_rec obtained from
333 the DNS response.
334 val_ac_trust
336 Pointer to an authentication chain element that either contains
337 a DNSKEY RRset that can be used to verify RRSIGs over the cur‐
338 rent record, or contains a DS RRset that can be used to build
339 the chain-of-trust towards a trust anchor.
340 struct val_rrset_rec
342 struct val_rrset_rec
343 {
344 int val_rrset_rcode;
345 char *val_rrset_name;
346 int val_rrset_class;
347 int val_rrset_type;
348 long val_rrset_ttl;
349 int val_rrset_section;
350 struct sockaddr *val_rrset_server;
351 struct val_rr_rec *val_rrset_data;
352 struct val_rr_rec *val_rrset_sig;
353 };
354 val_rrset_rcode
356 The rcode on the response header for this rrset.
357 val_rrset_name
359 Owner name of the RRset.
360 val_rrset_class
362 Class of the RRset.
363 val_val_rrset_type
365 Type of the RRset.
366 val_rrset_ttl
368 TTL of the RRset.
369 val_rrset_section
371 Section in which the RRset was received. This value may be
372 VAL_FROM_ANSWER, VAL_FROM_AUTHORITY, or VAL_FROM_ADDITIONAL.
373 val_rrset_server
375 The name server that returned this reponse.
376 val_rrset_data
378 Response RDATA.
379 val_rrset_sig
381 Any associated RRSIGs for the RDATA returned in val_rrset_data.
382 struct val_rr_rec
384 struct val_rr_rec
385 {
386 size_t rr_rdata_length;
387 unsigned char *rr_rdata;
388 struct val_rr_rec *rr_next;
389 val_astatus_t rr_status;
390 };
391 rr_rdata_length_h
393 Length of data stored in rr_rdata.
394 rr_rdata
396 RDATA bytes.
397 rr_status
399 For each signature val_rr_rec member within the authentica‐
400 tion chain val_ac_rrset, the validation status stored in
401 the variable rr_status can return one of the following val‐
402 ues:
403 VAL_AC_RRSIG_VERIFIED
405 The RRSIG verified successfully.
406 VAL_AC_WCARD_VERIFIED
408 A given RRSIG covering a resource record shows
409 that the record was wildcard expanded.
410 VAL_AC_RRSIG_VERIFIED_SKEW
412 The RRSIG verified successfully after clock
413 skew was taken into account.
414 VAL_AC_WCARD_VERIFIED_SKEW
416 A given RRSIG covering a resource record shows that
417 the record was wildcard expanded, but it was verified
418 only after clock skew was taken into account.
419 VAL_AC_WRONG_LABEL_COUNT
421 The number of labels on the signature was greater
422 than the count given in the RRSIG RDATA.
423 VAL_AC_INVALID_RRSIG
425 The RRSIG could not be parsed.
426 VAL_AC_RRSIG_NOTYETACTIVE
428 The RRSIG's inception time is in the future.
429 VAL_AC_RRSIG_EXPIRED
431 The RRSIG had expired.
432 VAL_AC_ALGORITHM_NOT_SUPPORTED
434 The RRSIG algorithm was not supported.
435 VAL_AC_RRSIG_VERIFY_FAILED
437 A given RRSIG covering an RRset was bogus.
438 VAL_AC_RRSIG_ALGORITHM_MISMATCH
440 The keytag referenced in the RRSIG matched a
441 DNSKEY but the algorithms were different.
442 VAL_AC_DNSKEY_NOMATCH
444 An RRSIG was created by a DNSKEY that did not
445 exist in the apex keyset.
446 For each val_rr_rec member of type DNSKEY (or DS, where
448 relevant) within the authentication chain val_ac_rrset, the
449 validation status is stored in the variable rr_status and
450 can return one of the following values:
451 VAL_AC_TRUST_POINT
453 The given DNSKEY or a DS record was configured
454 as a DNSSEC trust anchor.
455 VAL_AC_SIGNING_KEY
457 This DNSKEY was used to create an RRSIG for
458 the resource record set.
459 VAL_AC_VERIFIED_LINK
461 This DNSKEY provided the link in the authentication
462 chain from the trust anchor to the signed record.
463 VAL_AC_UNKNOWN_ALGORITHM_LINK
465 This DNSKEY provided the link in the authentication
466 chain from the trust anchor to the signed record,
467 but the DNSKEY algorithm was unknown.
468 VAL_AC_UNKNOWN_DNSKEY_PROTOCOL
470 The DNSKEY protocol number was unrecognized.
471 VAL_AC_ALGORITHM_NOT_SUPPORTED
473 The DNSKEY or DS algorithm was not supported.
474 VAL_AC_DS_NOMATCH
476 An RRSIG was created with a key that did not
477 exist in the parent DS record set.
478 VAL_AC_INVALID_KEY
480 The key used to verify the RRSIG was not a valid
481 DNSKEY.
482 VAL_AC_INVALID_DS
484 The DS used to validatate the DNSKEY could not be
485 parsed
486 =back
487 rr_next
489 Points to the next resource record in the RRset.
490
492 libval provides the val_log_add_optarg() function for controlling the
493 verbosity and location of log message output.
494 The val_log_add_optarg() function takes two arguments: the first argu‐
496 ment args is a character string value that specifies the location and
497 verbosity, the second argument, use_stderr, if set to a value greater
498 than 0 allows libval to send log messages to stderr.
499 The character string that specifies log target location and verbosity
501 has a specific format:
502 <debug-level>:<dest-type>[:<dest-options>]
504 where
506 <debug-level> is 1-7, for increasing levels of verbosity
507 <dest-type> is one of file, net, syslog, stderr, stdout
508 <dest-options> depends on <dest-type>
509 file:<file-name> (opened in append mode)
510 net[:<host-name>:<host-port>] (127.0.0.1:1053)
511 syslog[:facility] (0-23 (default 1 USER))
512 The log levels can be roughly translated into different types of log
514 messages as follows (the messages returned for each level in this list
515 subsumes the messages returned for the level above it):
516 3 : Error : errror encountered
518 4 : Warning : recovering from error
519 5 : Notice : gives final validation results for a query
520 and details on policy files and labels used
521 6 : Info : gives details on authentication chains
522 7 : Debug : gives debug level information
523
525 Return values for various functions are given below. These values can
526 be displayed in ASCII format using the p_val_error() function.
527 VAL_NO_ERROR
529 No error was encountered.
530 VAL_NOT_IMPLEMENTED
532 Functionality not yet implemented.
533 VAL_RESOURCE_UNAVAILABLE
535 Some resource (crypto possibly) was unavailable. Currently not
536 implemented.
537 VAL_BAD_ARGUMENT
539 Bad arguments passed as parameters.
540 VAL_INTERNAL_ERROR
542 Encountered some internal error.
543 VAL_NO_PERMISSION
545 No permission to perform operation. Currently not implemented.
546 VAL_CONF_PARSE_ERROR
548 Error in parsing some configuration file.
549 VAL_CONF_NOT_FOUND
551 A configuration file was not available.
552 VAL_NO_POLICY
554 The policy identifier being referenced was invalid.
555
557 The validator library reads configuration information from two files,
558 resolv.conf and dnsval.conf.
559 See dnsval.conf(5) for a description of syntax for these files.
561
563 Copyright 2004-2011 SPARTA, Inc. All rights reserved. See the COPYING
564 file included with the dnssec-tools package for details.
565
567 Suresh Krishnaswamy, Robert Story
568
570 libsres(3)
571 dnsval.conf(5)
573 http://dnssec-tools.sourceforge.net
575perl v5.8.9 2011-06-28 libval(3)