1LIBVAL(1) User Contributed Perl Documentation LIBVAL(1)
2
6 val_create_context(), val_create_context_with_conf(), val_free_con‐
7 text() - manage validator context
8 val_resolve_and_check(), val_free_result_chain() - query and validate
10 answers from a DNS name server
11 val_istrusted() - check if status value corresponds to that of a trust‐
13 worthy answer
14 val_isvalidated() - check if status value represents an answer that
16 cryptographically chains down from a configured trust anchor
17 val_does_not_exist() - check if status value represents one of the
19 non-existence types
20 p_val_status(), p_ac_status(), p_val_error() - display validation sta‐
22 tus, authentication chain status and error information
23 dnsval_conf_get(), resolv_conf_get(), root_hints_get() - get the
25 default location for the validator configuration files
26 dnsval_conf_set(), resolv_conf_set(), root_hints_set() - set the
28 default location for the validator configuration files
29
31 #include <validator.h>
32 int val_create_context(const char *label, val_context_t **newcontext);
34 int val_create_context_with_conf(char *label,
36 char *dnsval_conf,
37 char *resolv_conf,
38 char *root_conf,
39 val_context_t ** newcontext);
40 int val_resolve_and_check(val_context_t *context,
42 u_char *domain_name_n,
43 const u_int16_t class,
44 const u_int16_t type,
45 const u_int8_t flags,
46 struct val_result_chain **results);
47 char *p_val_status(val_status_t valerrno);
49 char *p_ac_status(val_astatus_t auth_chain_status);
51 char *p_val_error(int err);
53 int val_istrusted(val_status_t val_status);
55 int val_isvalidated(val_status_t val_status);
57 int val_does_not_exist(val_status_t status);
59 void val_free_result_chain(struct val_result_chain *results);
61 void val_free_context(val_context_t *context);
63 char *resolv_conf_get(void);
65 int resolv_conf_set(const char *name);
67 char *root_hints_get(void);
69 int root_hints_set(const char *name);
71 char *dnsval_conf_get(void);
73 int dnsval_conf_set(const char *name);
75
77 The val_resolve_and_check() function queries a set of name servers for
78 the <domain_name_n, type, class> tuple and to verifies and validates
79 the response. Verification involves checking the RRSIGs, and valida‐
80 tion is verification of an authentication chain from a configured trust
81 anchor. The domain_name_n parameter is the queried name in DNS wire
82 format. The conversion from host format to DNS wire format can be done
83 using the ns_name_pton() function exported by the libsres(3) library.
84 The flags parameter can be used to control the results of validation.
86 Two values, which may be ORed together, are currently defined for this
87 field. VAL_QUERY_DONT_VALIDATE causes the validator to disable valida‐
88 tion for this query. VAL_QUERY_NO_DLV causes the validator to disable
89 DLV processing for this query. The second flag is only available if
90 the libval(3) library has been compiled with DLV support.
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)). The default locations of each of these files may
103 be changed using the interfaces dnsval_conf_set(), resolv_conf_set(),
104 and root_hints_set(), respectively. The corresponding "get" interfaces
105 (namely dnsval_conf_get(), resolv_conf_get(), and root_hints_get()) can
106 be used to return the current location from where these configuration
107 files are read. The configuration file locations may also be specified
108 on a per-context basis using the val_create_context_with_conf() func‐
109 tion.
110 Answers returned by val_resolve_and_check() are made available in the
112 *results linked list. Each answer corresponds to a distinct RRset;
113 multiple RRs within the RRset are part of the same answer. Multiple
114 answers are possible when type is ns_t_any or ns_t_rrsig.
115 Individual elements in *results point to val_authentication_chain
117 linked lists. The authentication chain elements in val_authentica‐
118 tion_chain contain the actual RRsets returned by the name server in
119 response to the query.
120 Validation result values returned in val_result_chain and authentica‐
122 tion chain status values returned in each element of the val_authenti‐
123 cation_chain linked list can be can be converted into ASCII format
124 using the p_val_status() and p_ac_status() functions respectively.
125 While some applications such as DNSSEC troubleshooting utilities and
127 packet inspection tools may look at individual authentication chain
128 elements to identify the actual reasons for validation error, most
129 applications will only be interested in a single error code for deter‐
130 mining the authenticity of data.
131 val_isvalidated() identifies if a given validation result status value
133 corresponds to an answer that was cryptographically verified and vali‐
134 dated using a locally configured trust anchor.
135 val_istrusted() identifies if a given validator status value is
137 trusted. An answer may be locally trusted without being validated.
138 val_does_not_exist() identifies if a given validator status value cor‐
140 responds to one of the non-existence types.
141 The libval library internally allocates memory for *results and this
143 must be freed by the invoking application using the free_result_chain()
144 interface.
145
147 struct val_result_chain
148 struct val_result_chain
149 {
150 val_status_t val_rc_status;
151 struct val_authentication_chain *val_rc_answer;
152 int val_rc_proof_count;
153 struct val_authentication_chain *val_rc_proofs[MAX_PROOFS];
154 struct val_result_chain *val_rc_next;
155 };
156 val_rc_answer
158 Authentication chain for a given RRset.
159 val_rc_next
161 Pointer to the next RRset in the set of answers returned for a
162 query.
163 val_rc_proofs
165 Pointer to authentication chains for any proof of non-existence
166 that were returned for the query.
167 val_rc_proof_count
169 Number of proof elements stored in val_rc_proofs. The number
170 cannot exceed MAX_PROOFS.
171 val_rc_status
173 Validation status for a given RRset. This can be one of the
174 following:
175 VAL_SUCCESS
177 Answer received and validated successfully.
178 VAL_LOCAL_ANSWER
180 Answer was available from a local file.
181 VAL_BARE_RRSIG
183 No DNSSEC validation possible, query was
184 for an RRSIG.
185 VAL_NONEXISTENT_NAME
187 No name was present and a valid proof of non-
188 existence confirming the missing name (NSEC or
189 NSEC3 span) was returned. The components of
190 the proof were also individually validated.
191 VAL_NONEXISTENT_TYPE
193 No type exists for the name and a valid proof
194 of non-existence confirming the missing name
195 was returned. The components of the proof
196 were also individually validated.
197 VAL_NONEXISTENT_NAME_NOCHAIN
199 No name was present and a valid proof of non-
200 existence confirming the missing name was
201 returned. The components of the proof were also
202 identified to be trustworthy, but they were
203 not individually validated.
204 VAL_NONEXISTENT_TYPE_NOCHAIN
206 No type exists for the name and a valid proof
207 of non-existence confirming the missing name
208 (NSEC or NSEC3 span) was returned. The
209 components of the proof were also identified
210 to be trustworthy, but they were not
211 individually validated.
212 VAL_DNS_CONFLICTING_ANSWERS
214 Multiple conflicting answers received for a query.
215 VAL_DNS_QUERY_ERROR
217 Some error was encountered while sending the query.
218 VAL_DNS_RESPONSE_ERROR
220 No response returned or response with an error
221 rcode value returned.
222 VAL_DNS_WRONG_ANSWER
224 Wrong answer received for a query.
225 VAL_DNS_REFERRAL_ERROR
227 Some error encountered while following referrals.
228 VAL_DNS_MISSING_GLUE
230 Glue was missing.
231 VAL_BOGUS_PROVABLE
233 Response could not be validated due to signature
234 verification failures or the inability to verify
235 proofs for exactly one component in the
236 authentication chain below the trust anchor.
237 VAL_BOGUS
239 Response could not be validated due to signature
240 verification failures or the inability to verify
241 proofs for an indeterminate number of components
242 in the authentication chain.
243 VAL_NOTRUST
245 All available components in the authentication
246 chain verified properly, but there was no trust
247 anchor available.
248 VAL_IGNORE_VALIDATION
250 Local policy was configured to ignore validation
251 for the zone from which this data was received.
252 VAL_TRUSTED_ZONE
254 Local policy was configured to trust
255 any data received from the given zone.
256 VAL_UNTRUSTED_ZONE
258 Local policy was configured to reject
259 any data received from the given zone.
260 VAL_PROVABLY_UNSECURE
262 The record or some ancestor of the record in
263 the authentication chain towards the trust
264 anchor was known to be provably unsecure.
265 VAL_BAD_PROVABLY_UNSECURE
267 The record or some ancestor of the record in the
268 authentication chain towards the trust anchor was
269 known to be provably unsecure. But the provably
270 unsecure condition was configured as untrustworthy.
271 Status values in val_status_t returned by the validator can be
273 displayed in ASCII format using p_val_status().
274 struct val_authentication_chain
276 struct val_authentication_chain
277 {
278 val_astatus_t val_ac_status;
279 struct val_rrset *val_ac_rrset;
280 struct val_authentication_chain *val_ac_trust;
281 };
282 val_ac_status
284 Validation state of the authentication chain element. This
285 field will contain the status code for the given component in
286 the authentication chain. This field may contain one of the
287 following values:
288 VAL_AC_UNSET
290 The status was not set.
291 VAL_AC_DATA_MISSING
293 No data were returned for a query and the
294 DNS did not indicate an error.
295 VAL_AC_RRSIG_MISSING
297 RRSIG data could not be retrieved for a
298 resource record.
299 VAL_AC_DNSKEY_MISSING
301 The DNSKEY for an RRSIG covering a resource
302 record could not be retrieved.
303 VAL_AC_DS_MISSING
305 The DS record covering a DNSKEY record was
306 not available.
307 VAL_AC_NOT_VERIFIED
309 All RRSIGs covering the RRset could not
310 be verified.
311 VAL_AC_VERIFIED
313 At least one RRSIG covering a resource
314 record had a status of VAL_AC_RRSIG_VERIFIED.
315 VAL_AC_TRUST_KEY
317 A given DNSKEY or a DS record was locally
318 defined to be a trust anchor.
319 VAL_AC_IGNORE_VALIDATION
321 Validation for the given resource record was ignored,
322 either because of some local policy directive or
323 because of some protocol-specific behavior.
324 VAL_AC_TRUSTED_ZONE
326 Local policy defined a given zone as trusted, with
327 no further validation being deemed necessary.
328 VAL_AC_UNTRUSTED_ZONE
330 Local policy defined a given zone as untrusted,
331 with no further validation being deemed necessary.
332 VAL_AC_PROVABLY_UNSECURE
334 The authentication chain from a trust anchor to a
335 given zone could not be constructed due to the
336 provable absence of a DS record for this zone in
337 the parent.
338 VAL_AC_BARE_RRSIG
340 The response was for a query of type RRSIG. RRSIGs
341 contain the cryptographic signatures for other DNS
342 data and cannot themselves be validated.
343 VAL_AC_NO_TRUST_ANCHOR
345 There was no trust anchor configured for a given
346 authentication chain.
347 VAL_AC_DNS_CONFLICTING_ANSWERS
349 Multiple conflicting answers received for a query.
350 VAL_AC_DNS_QUERY_ERROR
352 Some error was encountered while sending the query.
353 VAL_AC_DNS_RESPONSE_ERROR
355 No response returned or response with an error
356 rcode value returned.
357 VAL_AC_DNS_WRONG_ANSWER
359 Wrong answer received for a query.
360 VAL_AC_DNS_REFERRAL_ERROR
362 Some error encountered while following referrals.
363 VAL_AC_DNS_MISSING_GLUE
365 Glue was missing.
366 val_ac_rrset
368 Pointer to an RRset of type struct val_rrset obtained from the
369 DNS response.
370 val_ac_trust
372 Pointer to an authentication chain element that either contains
373 a DNSKEY RRset that can be used to verify RRSIGs over the cur‐
374 rent record, or contains a DS RRset that can be used to build
375 the chain-of-trust towards a trust anchor.
376 struct val_rrset
378 struct val_rrset
379 {
380 u_int8_t *val_msg_header;
381 u_int16_t val_msg_headerlen;
382 u_int8_t *val_rrset_name_n;
383 u_int16_t val_rrset_class_h;
384 u_int16_t val_rrset_type_h;
385 u_int32_t val_rrset_ttl_h;
386 u_int32_t val_rrset_ttl_x;
387 u_int8_t val_rrset_section;
388 struct rr_rec *val_rrset_data;
389 struct rr_rec *val_rrset_sig;
390 };
391 val_msg_header
393 Header of the DNS response in which the RRset was received.
394 val_msg_headerlen
396 Length of the header information in val_msg_header.
397 val_rrset_name_n
399 Owner name of the RRset represented in on-the-wire format.
400 val_rrset_class_h
402 Class of the RRset.
403 val_val_rrset_type_h
405 Type of the RRset.
406 val_rrset_ttl_h
408 TTL of the RRset.
409 val_rrset_ttl_x
411 The time when the TTL for this RRset is set to expire.
412 val_rrset_section
414 Section in which the RRset was received. This value may be
415 VAL_FROM_ANSWER, VAL_FROM_AUTHORITY, or VAL_FROM_ADDITIONAL.
416 val_rrset_data
418 Response RDATA.
419 val_rrset_sig
421 Any associated RRSIGs for the RDATA returned in val_rrset_data.
422 struct rr_rec
424 struct rr_rec
425 {
426 u_int16_t rr_rdata_length_h;
427 u_int8_t *rr_rdata;
428 val_astatus_t rr_status;
429 struct rr_rec *rr_next;
430 };
431 rr_rdata_length_h
433 Length of data stored in rr_rdata.
434 rr_rdata
436 RDATA bytes.
437 rr_status
439 For each signature rr_rec member within the authentication
440 chain val_ac_rrset, the validation status stored in the
441 variable rr_status can return one of the following values:
442 VAL_AC_RRSIG_VERIFIED
444 The RRSIG verified successfully.
445 VAL_AC_WCARD_VERIFIED
447 A given RRSIG covering a resource record shows
448 that the record was wildcard expanded.
449 VAL_AC_RRSIG_VERIFIED_SKEW
451 The RRSIG verified successfully after clock
452 skew was taken into account.
453 VAL_AC_WCARD_VERIFIED_SKEW
455 A given RRSIG covering a resource record shows that
456 the record was wildcard expanded, but it was verified
457 only after clock skew was taken into account.
458 VAL_AC_RRSIG_VERIFY_FAILED
460 A given RRSIG covering an RRset was bogus.
461 VAL_AC_DNSKEY_NOMATCH
463 An RRSIG was created by a DNSKEY that did not
464 exist in the apex keyset.
465 VAL_AC_RRSIG_ALGORITHM_MISMATCH
467 The keytag referenced in the RRSIG matched a
468 DNSKEY but the algorithms were different.
469 VAL_AC_WRONG_LABEL_COUNT
471 The number of labels on the signature was greater
472 than the count given in the RRSIG RDATA.
473 VAL_AC_BAD_DELEGATION
475 An RRSIG was created with a key that did not
476 exist in the parent DS record set.
477 VAL_AC_RRSIG_NOTYETACTIVE
479 The RRSIG's inception time is in the future.
480 VAL_AC_RRSIG_EXPIRED
482 The RRSIG had expired.
483 VAL_AC_INVALID_RRSIG
485 The RRSIG could not be parsed.
486 VAL_AC_ALGORITHM_NOT_SUPPORTED
488 The RRSIG algorithm was not supported.
489 For each rr_rec member of type DNSKEY (or DS, where rele‐
491 vant) within the authentication chain val_ac_rrset, the
492 validation status is stored in the variable rr_status and
493 can return one of the following values:
494 VAL_AC_SIGNING_KEY
496 This DNSKEY was used to create an RRSIG for
497 the resource record set.
498 VAL_AC_VERIFIED_LINK
500 This DNSKEY provided the link in the authentication
501 chain from the trust anchor to the signed record.
502 VAL_AC_UNKNOWN_DNSKEY_PROTOCOL
504 The DNSKEY protocol number was unrecognized.
505 VAL_AC_UNKNOWN_ALGORITHM_LINK
507 This DNSKEY provided the link in the authentication
508 chain from the trust anchor to the signed record,
509 but the DNSKEY algorithm was unknown.
510 VAL_AC_INVALID_KEY
512 The key used to verify the RRSIG was not a valid
513 DNSKEY.
514 VAL_AC_ALGORITHM_NOT_SUPPORTED
516 The DNSKEY or DS algorithm was not supported.
517 rr_next
519 Points to the next resource record in the RRset.
520
522 Return values for various functions are given below. These values can
523 be displayed in ASCII format using the p_val_error() function.
524 val_resolve_and_check()
526 VAL_NO_ERROR
527 No error was encountered.
528 VAL_GENERIC_ERROR
530 Generic error encountered.
531 VAL_NOT_IMPLEMENTED
533 Functionality not yet implemented.
534 VAL_BAD_ARGUMENT
536 Bad arguments passed as parameters.
537 VAL_INTERNAL_ERROR
539 Encountered some internal error.
540 VAL_NO_PERMISSION
542 No permission to perform operation. Currently not implemented.
543 VAL_RESOURCE_UNAVAILABLE
545 Some resource (crypto possibly) was unavailable. Currently not
546 implemented.
547 val_create_context() and val_create_context_with_conf()
549 VAL_NO_ERROR
550 No error was encountered.
551 VAL_RESOURCE_UNAVAILABLE
553 Could not allocate memory.
554 VAL_CONF_PARSE_ERROR
556 Error in parsing some configuration file.
557 VAL_CONF_NOT_FOUND
559 A configuration file was not available.
560 VAL_NO_POLICY
562 The policy identifier being referenced was invalid.
563
565 The validator library reads configuration information from two files,
566 /etc/resolv.conf and /etc/dnsval.conf.
567 See dnsval.conf(5) for a description of syntax for these files.
569
571 Copyright 2004-2007 SPARTA, Inc. All rights reserved. See the COPYING
572 file included with the dnssec-tools package for details.
573
575 Suresh Krishnaswamy, Robert Story
576
578 libsres(3)
579 dnsval.conf(5)
581 http://dnssec-tools.sourceforge.net
583perl v5.8.6 2007-09-11 LIBVAL(1)