1libval(3) Programmer's Manual libval(3)
2
6 val_create_context() val_free_context() - manage validator context
7 val_context_setqflags() - manage validator context flags
9 val_resolve_and_check(), val_free_result_chain() - query and validate
11 answers from a DNS name server
12 val_istrusted() - check if status value corresponds to that of a
14 trustworthy answer
15 val_isvalidated() - check if status value represents an answer that
17 cryptographically chains down from a configured trust anchor
18 val_does_not_exist() - check if status value represents one of the
20 non-existence types
21 p_val_status(), p_ac_status(), p_val_error() - display validation
23 status, authentication chain status and error information
24 val_log_add_optarg - control log message verbosity and output location
26
28 #include <validator.h>
29 int val_create_context(const char *label, val_context_t **newcontext);
31 int val_create_context_ex(char *label,
33 val_context_opt_t *opt,
34 val_context_t ** newcontext);
35 int val_context_setqflags(val_context_t *context,
37 unsigned char action,
38 unsigned int flags);
39 int val_context_store_ns_for_zone(val_context_t *context,
41 char * zone,
42 char *resp_server,
43 int recursive)
44 int val_resolve_and_check(val_context_t *context,
46 const char *domain_name,
47 int class,
48 int type,
49 unsigned int flags,
50 struct val_result_chain **results);
51 char *p_val_status(val_status_t valerrno);
53 char *p_ac_status(val_astatus_t auth_chain_status);
55 char *p_val_error(int err);
57 int val_istrusted(val_status_t val_status);
59 int val_isvalidated(val_status_t val_status);
61 int val_does_not_exist(val_status_t status);
63 val_log_t *val_log_add_optarg(const char *args, int use_stderr);
65 void val_free_result_chain(struct val_result_chain *results);
67 void val_free_context(val_context_t *context);
69
71 The val_resolve_and_check() function queries a set of name servers for
72 the <domain_name, type, class> tuple and verifies and validates the
73 response. Verification involves checking the RRSIGs, and validation is
74 verification of an authentication chain from a configured trust anchor.
75 The flags parameter can be used to control the results of validation.
77 The following values, which may be ORed together, are currently defined
78 for this field:
79 VAL_QUERY_DONT_VALIDATE
81 This flag causes the validator to disable validation for this
82 query.
83 VAL_QUERY_IGNORE_SKEW
85 This flag causes the validator to disable checking signature
86 inception and expiration times on RRSIGs.
87 VAL_QUERY_AC_DETAIL
89 This flag causes the validator to copy the authentication chain
90 details into the val_rc_answer member within the returned
91 val_result_chain structure.
92 VAL_QUERY_ASYNC
94 This flag enables asynchronous query resolution for that lookup.
95 VAL_QUERY_NO_DLV
97 This flag causes the validator to disable DLV processing for this
98 query. This is only available if the libval(3) library has been
99 compiled with DLV support.
100 VAL_QUERY_NO_EDNS0_FALLBACK
102 In querying various name servers, libsres(3) will also attempt
103 multiple EDNS0 sizes, ending with a query that has EDNS0 disabled
104 (i.e. no CD bit set). This flag causes libval to disable EDNS0
105 fallback for the query.
106 VAL_QUERY_ITERATE
108 This flag forces libval to iteratively lookup the query by querying
109 various name servers in the delegation hierarchy, instead of
110 requesting this information from any caching name server that may
111 be configured in dnsval.conf.
112 VAL_QUERY_SKIP_RESOLVER
114 This flag forces libval to only look at its cache while trying to
115 resolve a name.
116 VAL_QUERY_SKIP_CACHE
118 There are two levels of caching that happen within libval: at the
119 assertion level and at the answer level. This flag forces libval to
120 ignore data in both caches while trying to resolve a name.
121 VAL_QUERY_SKIP_ANS_CACHE
123 There are two levels of caching that happen within libval: at the
124 assertion level and at the answer level. This flag forces libval to
125 ignore data in the answer cache while trying to resolve a name. If
126 an assertion already exists for the given name,class and type that
127 assertion is re-used till it expires. Once it expires the name is
128 looked up via a query even if an newer record (fetched by another
129 assertion in the same or different context) is available in its
130 answer cache.
131 The first parameter to val_resolve_and_check() is the validator
133 context. Applications can create a new validator context using the
134 val_create_context() function. This function parses the resolver and
135 validator configuration files and creates the newcontext handle for
136 this parsed information. Information stored as part of the validator
137 context includes the validation policy the and resolver policy.
138 Validator and resolver policies are read from the /etc/dnsval.conf and
140 /etc/resolv.conf files by default. /etc/root.hints provides
141 bootstrapping information for the validator when it functions as a full
142 resolver (see dnsval.conf(3)). These defaults may be different if any
143 other value was specified at library configure time. If the default
144 resolver configuration file is not found at the specified location,
145 libval will also try to fall back to /etc/resolv.conf as a last resort.
146 Applications may also create a validator context with a custom policy
148 using the val_create_context_ex() function.
149 The opt argument in val_create_context_ex() points to the following
151 structure:
152 typedef struct val_context_opt {
154 unsigned int vc_qflags;
155 unsigned int vc_polflags;
156 char *vc_valpol;
157 char *vc_nslist;
158 char *vc_val_conf;
159 char *vc_res_conf;
160 char *vc_root_conf;
161 val_global_opt_t *gopt,
162 } val_context_opt_t;
163 vc_qflags specify the default query flags for queries associated with
165 the context. This field is identical to the flags argument in the
166 val_resolve_and_check() function.
167 The vc_val_conf, vc_res_conf, and vc_root_conf fields can be used to
169 specify alternative configuration files in place of the default files
170 used for the validator, resolver, and root hints configuration
171 information.
172 The vc_valpol field can be used to supply a custom validator
174 configuration "snippet" to the validator. The validator parses this
175 information and applies it to the default validator configuration
176 either as an extension or as an override, as specified by the
177 vc_polflags field. The vc_nslist field, similarly, can be used to
178 supply a custom list of recursive name servers to send queries to, in
179 addition (or in place of) the list of name servers specified in the
180 resolv.conf file. The list of name servers in vc_res_conf must be
181 specified as a white-space delimited list of IP or IPv6 addresses.
182 A custom mapping between a zone and a name server may be created using
184 the val_context_store_ns_for_zone() function.
185 vc_polflags can be configured with the following values:
187 CTX_DYN_POL_VAL_OVR
189 When this flag is set only the validator configuration specified in
190 the vc_valpol field is used for the validator configuration.
191 Options specified in the dnsval.conf file are ignored.
192 CTX_DYN_POL_RES_OVR
194 When this flag is set only the name servers specified in the
195 vc_nslist field is used for the resolver configuration. Options
196 specified in the resolv.conf file are ignored.
197 CTX_DYN_POL_GLO_OVR
199 When this flag is set only the global options set in gopt field are
200 used. Global options specified in the dnsval.conf file are
201 ignored.
202 CTX_DYN_POL_RES_NRD
204 When this flag is set outgoing queries have the Recursion Desired
205 (RD) bit set to 0. This is useful if queries need to be sent to an
206 authoritative-only name server.
207 The gopt field points to the following structure:
209 typedef struct val_global_opt {
211 int local_is_trusted;
212 long edns0_size;
213 int env_policy;
214 int app_policy;
215 char *log_target;
216 int closest_ta_only;
217 int rec_fallback;
218 long max_refresh;
219 int proto;
220 } val_global_opt_t;
221 Setting a value of 1 for local_is_trusted is equivalent to specifying
223 the trust-oob-answers option in the dnsval.conf file to yes.
224 Similarly, setting the closest_ta_only and rec_fallback members to 1 is
225 equivalent to setting the closest-ta-only and rec-fallback options to
226 yes in the dnsval.conf file. A value of 0 is equivalent to the no
227 setting for these option.
228 Setting the edns0_size member to a particular value has the same effect
230 setting the edns0-size option in the dnsval.conf file.
231 Setting the max_refresh member to a particular value has the same
233 effect setting the max-refresh option in the dnsval.conf file.
234 Setting the proto member to a particular value has the same effect
236 setting the proto option in the dnsval.conf file.
237 env_policy and app_policy can be set to one of VAL_POL_GOPT_DISABLE,
239 VAL_POL_GOPT_ENABLE, or VAL_POL_GOPT_OVERRIDE. These values correspond
240 directly to the disable, enable and override options for the env-policy
241 and app-policy settings in the dnsval.conf file.
242 Values of -1 for the above fields are treated as "ignore" conditions in
244 that the validator will not include dynamically supplied global options
245 with a value of -1 when creating its context. This allows an
246 application to overriding a subset of global options while using the
247 global options supplied in the dnsval.conf file by default.
248 The log_target field enables the application to supply log targets in
250 addition to the ones configured in the configuration file.
251 See dnsval.conf(3) for more details on specifying validator policy.
253 Default query flags can be set and unset for a given context using
255 val_context_setqflags(). This allows an application to alter the
256 DNSSEC validator processing, while still having most of the more
257 granular default configuration specified in its configuration file.
258 The action parameter can be set to one of the following.
259 VAL_CTX_FLAG_SET
261 This option causes the validator to set the given flag as one of
262 the default query flags.
263 VAL_CTX_FLAG_RESET
265 This option causes the validator to reset the given flag if it was
266 set as one of the default query flags for the context.
267 Answers returned by val_resolve_and_check() are made available in the
269 *results linked list. Each answer corresponds to a distinct RRset;
270 multiple RRs within the RRset are part of the same answer. Multiple
271 answers are possible when type is ns_t_any or ns_t_rrsig.
272 Individual elements in *results point to val_authentication_chain
274 linked lists. The authentication chain elements in
275 val_authentication_chain contain the actual RRsets returned by the name
276 server in response to the query.
277 Validation result values returned in val_result_chain can be can be
279 converted into ASCII format using the p_val_status(). Authentication
280 chain status values returned in each element of the
281 val_authentication_chain linked list can be can be converted into ASCII
282 format using the p_ac_status() functions.
283 While some applications such as DNSSEC troubleshooting utilities and
285 packet inspection tools may look at individual authentication chain
286 elements to identify the actual reasons for validation error, most
287 applications will only be interested in a single error code for
288 determining the authenticity of data.
289 val_isvalidated() identifies if a given validation result status value
291 corresponds to an answer that was cryptographically verified and
292 validated using a locally configured trust anchor.
293 val_istrusted() identifies if a given validator status value is
295 trusted. An answer may be locally trusted without being validated.
296 val_does_not_exist() identifies if a given validator status value
298 corresponds to one of the non-existence types.
299 The libval library internally allocates memory for *results and this
301 must be freed by the invoking application using the free_result_chain()
302 interface.
303
305 struct val_result_chain
306 struct val_result_chain
307 {
308 val_status_t val_rc_status;
309 char *val_rc_alias;
310 struct val_rrset_rec *val_rc_rrset;
311 struct val_authentication_chain *val_rc_answer;
312 int val_rc_proof_count;
313 struct val_authentication_chain *val_rc_proofs[MAX_PROOFS];
314 struct val_result_chain *val_rc_next;
315 };
316 val_rc_answer
318 Authentication chain for a given RRset.
319 val_rc_next
321 Pointer to the next RRset in the set of answers returned for a
322 query.
323 val_rc_proofs
325 Pointer to authentication chains for any proof of non-existence
326 that were returned for the query.
327 val_rc_proof_count
329 Number of proof elements stored in val_rc_proofs. The number
330 cannot exceed MAX_PROOFS.
331 val_rc_alias
333 For an val_result_chain element that points to a name alias,
334 this field contains the target value.
335 val_rc_rrset
337 For a val_result_chain element that contains a valid (not NULL)
338 val_rc_answer field, the val_rc_rrset field points to the top-
339 most val_rrset_rec element in the val_rc_answer authentication
340 chain.
341 val_rc_status
343 Validation status for a given RRset. This can be one of the
344 following:
345 VAL_SUCCESS
347 Answer received and validated successfully.
348 VAL_NONEXISTENT_NAME
350 No name was present and a valid proof of non-existence
351 confirming the missing name (NSEC or NSEC3 span) was
352 returned. The components of the proof were also
353 individually validated.
354 VAL_NONEXISTENT_TYPE
356 No type exists for the name and a valid proof of non-
357 existence confirming the missing name was returned. The
358 components of the proof were also individually validated.
359 VAL_NONEXISTENT_NAME_NOCHAIN
361 No name was present and a valid proof of non-existence
362 confirming the missing name was returned. The components
363 of the proof were also identified to be trustworthy, but
364 they were not individually validated.
365 VAL_NONEXISTENT_TYPE_NOCHAIN
367 No type exists for the name and a valid proof of non-
368 existence confirming the missing name (NSEC or NSEC3 span)
369 was returned. The components of the proof were also
370 identified to be trustworthy, but they were not
371 individually validated.
372 VAL_PINSECURE
374 The record or some ancestor of the record in the
375 authentication chain towards the trust anchor was known to
376 be provably insecure.
377 VAL_PINSECURE_UNTRUSTED
379 The record or some ancestor of the record in the
380 authentication chain towards the trust anchor was known to
381 be provably insecure. But the provably insecure condition
382 was configured as untrustworthy.
383 VAL_BARE_RRSIG
385 No DNSSEC validation possible, query was for an RRSIG.
386 VAL_IGNORE_VALIDATION
388 Local policy was configured to ignore validation for the
389 zone from which this data was received.
390 VAL_UNTRUSTED_ZONE
392 Local policy was configured to reject any data received
393 from the given zone.
394 VAL_OOB_ANSWER
396 Answer was obtained using some Out Of Band method, such as
397 a local configuration file.
398 VAL_BOGUS
400 Response could not be validated due to signature
401 verification failures or the inability to verify proofs in
402 the authentication chain.
403 VAL_DNS_ERROR
405 Some error was encountered during DNS processing.
406 VAL_INDETERMINATE
408 Response could not be validated due to missing DNSSEC meta-
409 data.
410 VAL_NOTRUST
412 All available components in the authentication chain
413 verified properly, but there was no trust anchor available.
414 Status values in val_status_t returned by the validator can be
416 displayed in ASCII format using p_val_status().
417 struct val_authentication_chain
419 struct val_authentication_chain
420 {
421 val_astatus_t val_ac_status;
422 struct val_rrset_rec *val_ac_rrset;
423 struct val_authentication_chain *val_ac_trust;
424 };
425 val_ac_status
427 Validation state of the authentication chain element. This
428 field will contain the status code for the given component in
429 the authentication chain. This field may contain one of the
430 following values:
431 VAL_AC_UNSET
433 The status could not be determined.
434 VAL_AC_IGNORE_VALIDATION
436 Validation for the given resource record was ignored,
437 either because of some local policy directive or because of
438 some protocol-specific behavior.
439 VAL_AC_UNTRUSTED_ZONE
441 Local policy defined a given zone as untrusted, with no
442 further validation being deemed necessary.
443 VAL_AC_PINSECURE
445 The authentication chain from a trust anchor to a given
446 zone could not be constructed due to the provable absence
447 of a DS record for this zone in the parent.
448 VAL_AC_BARE_RRSIG
450 The response was for a query of type RRSIG. RRSIGs contain
451 the cryptographic signatures for other DNS data and cannot
452 themselves be validated.
453 VAL_AC_NO_LINK
455 There was no trust anchor configured for a given
456 authentication chain or the chain didn't link up.
457 VAL_AC_TRUST
459 At least one of the signatures covering the given DNSKEY
460 RRset was directly verified using a key that was configured
461 as a DNSSEC trust anchor.
462 VAL_AC_RRSIG_MISSING
464 RRSIG data could not be retrieved for a resource record.
465 VAL_AC_DNSKEY_MISSING
467 The DNSKEY for an RRSIG covering a resource record could
468 not be retrieved.
469 VAL_AC_DS_MISSING
471 The DS record covering a DNSKEY record was not available.
472 VAL_AC_DATA_MISSING
474 No data were returned for a query and the DNS did not
475 indicate an error.
476 VAL_AC_DNS_ERROR
478 Some error was encountered during DNS processing.
479 VAL_AC_NOT_VERIFIED
481 All RRSIGs covering the RRset could not be verified.
482 VAL_AC_VERIFIED
484 At least one RRSIG covering a resource record had a status
485 of VAL_AC_RRSIG_VERIFIED.
486 val_ac_rrset
488 Pointer to an RRset of type struct val_rrset_rec obtained from
489 the DNS response.
490 val_ac_trust
492 Pointer to an authentication chain element that either contains
493 a DNSKEY RRset that can be used to verify RRSIGs over the
494 current record, or contains a DS RRset that can be used to
495 build the chain-of-trust towards a trust anchor.
496 struct val_rrset_rec
498 struct val_rrset_rec
499 {
500 int val_rrset_rcode;
501 char *val_rrset_name;
502 int val_rrset_class;
503 int val_rrset_type;
504 long val_rrset_ttl;
505 int val_rrset_section;
506 struct sockaddr *val_rrset_server;
507 struct val_rr_rec *val_rrset_data;
508 struct val_rr_rec *val_rrset_sig;
509 };
510 val_rrset_rcode
512 The rcode on the response header for this rrset.
513 val_rrset_name
515 Owner name of the RRset.
516 val_rrset_class
518 Class of the RRset.
519 val_val_rrset_type
521 Type of the RRset.
522 val_rrset_ttl
524 TTL of the RRset.
525 val_rrset_section
527 Section in which the RRset was received. This value may be
528 VAL_FROM_ANSWER, VAL_FROM_AUTHORITY, or VAL_FROM_ADDITIONAL.
529 val_rrset_server
531 The name server that returned this reponse.
532 val_rrset_data
534 Response RDATA.
535 val_rrset_sig
537 Any associated RRSIGs for the RDATA returned in val_rrset_data.
538 struct val_rr_rec
540 struct val_rr_rec
541 {
542 size_t rr_rdata_length;
543 unsigned char *rr_rdata;
544 struct val_rr_rec *rr_next;
545 val_astatus_t rr_status;
546 };
547 rr_rdata_length_h
549 Length of data stored in rr_rdata.
550 rr_rdata
552 RDATA bytes.
553 rr_status
555 For each signature val_rr_rec member within the authentication
556 chain val_ac_rrset, the validation status stored in the
557 variable rr_status can return one of the following values:
558 VAL_AC_RRSIG_VERIFIED
560 The RRSIG verified successfully.
561 VAL_AC_WCARD_VERIFIED
563 A given RRSIG covering a resource record shows
564 that the record was wildcard expanded.
565 VAL_AC_RRSIG_VERIFIED_SKEW
567 The RRSIG verified successfully after clock
568 skew was taken into account.
569 VAL_AC_WCARD_VERIFIED_SKEW
571 A given RRSIG covering a resource record shows that
572 the record was wildcard expanded, but it was verified
573 only after clock skew was taken into account.
574 VAL_AC_WRONG_LABEL_COUNT
576 The number of labels on the signature was greater
577 than the count given in the RRSIG RDATA.
578 VAL_AC_INVALID_RRSIG
580 The RRSIG could not be parsed.
581 VAL_AC_RRSIG_NOTYETACTIVE
583 The RRSIG's inception time is in the future.
584 VAL_AC_RRSIG_EXPIRED
586 The RRSIG had expired.
587 VAL_AC_ALGORITHM_NOT_SUPPORTED
589 The RRSIG algorithm was not supported.
590 VAL_AC_RRSIG_VERIFY_FAILED
592 A given RRSIG covering an RRset was bogus.
593 VAL_AC_RRSIG_ALGORITHM_MISMATCH
595 The keytag referenced in the RRSIG matched a
596 DNSKEY but the algorithms were different.
597 VAL_AC_DNSKEY_NOMATCH
599 An RRSIG was created by a DNSKEY that did not
600 exist in the apex keyset.
601 For each val_rr_rec member of type DNSKEY (or DS, where
603 relevant) within the authentication chain val_ac_rrset, the
604 validation status is stored in the variable rr_status and can
605 return one of the following values:
606 VAL_AC_TRUST_POINT
608 The given DNSKEY or a DS record was configured
609 as a DNSSEC trust anchor.
610 VAL_AC_SIGNING_KEY
612 This DNSKEY was used to create an RRSIG for
613 the resource record set.
614 VAL_AC_VERIFIED_LINK
616 This DNSKEY provided the link in the authentication
617 chain from the trust anchor to the signed record.
618 VAL_AC_UNKNOWN_ALGORITHM_LINK
620 This DNSKEY provided the link in the authentication
621 chain from the trust anchor to the signed record,
622 but the DNSKEY algorithm was unknown.
623 VAL_AC_UNKNOWN_DNSKEY_PROTOCOL
625 The DNSKEY protocol number was unrecognized.
626 VAL_AC_ALGORITHM_NOT_SUPPORTED
628 The DNSKEY or DS algorithm was not supported.
629 VAL_AC_DS_NOMATCH
631 An RRSIG was created with a key that did not
632 exist in the parent DS record set.
633 VAL_AC_INVALID_KEY
635 The key used to verify the RRSIG was not a valid DNSKEY.
636 VAL_AC_INVALID_DS
638 The DS used to validate the DNSKEY could not be parsed.
639 rr_next
641 Points to the next resource record in the RRset.
642
644 libval provides the val_log_add_optarg() function for controlling the
645 verbosity and location of log message output.
646 The val_log_add_optarg() function takes two arguments: the first
648 argument args is a character-string value that specifies the location
649 and verbosity. The second argument, use_stderr, if set to a value
650 greater than 0 allows libval to send log messages to stderr.
651 The character string that specifies log target location and verbosity
653 has a specific format:
654 <debug-level>:<dest-type>[:<dest-options>]
656 where
658 <debug-level> is 1-7, for increasing levels of verbosity
659 <dest-type> is one of file, net, syslog, stderr, stdout
660 <dest-options> depends on <dest-type>
661 file:<file-name> (opened in append mode)
662 net[:<host-name>:<host-port>] (127.0.0.1:1053)
663 syslog[:facility] (0-23 (default 1 USER))
664 The log levels can be roughly translated into different types of log
666 messages as follows (the messages returned for each level in this list
667 subsumes the messages returned for the level above it):
668 3 : Error : error encountered
670 4 : Warning : recovering from error
671 5 : Notice : gives final validation results for a query
672 and details on policy files and labels used
673 6 : Info : gives details on authentication chains
674 7 : Debug : gives debug level information
675
677 Return values for various functions are given below. These values can
678 be displayed in ASCII format using the p_val_error() function.
679 VAL_NO_ERROR
681 No error was encountered.
682 VAL_NOT_IMPLEMENTED
684 Functionality not yet implemented.
685 VAL_RESOURCE_UNAVAILABLE
687 Some resource (crypto possibly) was unavailable. Currently not
688 implemented.
689 VAL_BAD_ARGUMENT
691 Bad arguments passed as parameters.
692 VAL_INTERNAL_ERROR
694 Encountered some internal error.
695 VAL_NO_PERMISSION
697 No permission to perform operation. Currently not implemented.
698 VAL_CONF_PARSE_ERROR
700 Error in parsing some configuration file.
701 VAL_CONF_NOT_FOUND
703 A configuration file was not available.
704 VAL_NO_POLICY
706 The policy identifier being referenced was invalid.
707
709 The validator library reads configuration information from two files,
710 resolv.conf and dnsval.conf.
711 See dnsval.conf(5) for a description of the syntax for these files.
713
715 Copyright 2004-2013 SPARTA, Inc. All rights reserved. See the COPYING
716 file included with the dnssec-tools package for details.
717
719 Suresh Krishnaswamy, Robert Story
720
722 libsres(3)
723 dnsval.conf(5)
725 http://www.dnssec-tools.org
727perl v5.26.2 2018-08-08 libval(3)