1LIBVAL(1)             User Contributed Perl Documentation            LIBVAL(1)
2
3
4

NAME

6       val_create_context(), val_create_context_with_conf(), val_free_con‐
7       text() - manage validator context
8
9       val_resolve_and_check(), val_free_result_chain() - query and validate
10       answers from a DNS name server
11
12       val_istrusted() - check if status value corresponds to that of a trust‐
13       worthy answer
14
15       val_isvalidated() - check if status value represents an answer that
16       cryptographically chains down from a configured trust anchor
17
18       val_does_not_exist() - check if status value represents one of the
19       non-existence types
20
21       p_val_status(), p_ac_status(), p_val_error() - display validation sta‐
22       tus, authentication chain status and error information
23
24       dnsval_conf_get(), resolv_conf_get(), root_hints_get() - get the
25       default location for the validator configuration files
26
27       dnsval_conf_set(), resolv_conf_set(), root_hints_set() - set the
28       default location for the validator configuration files
29

SYNOPSIS

31         #include <validator.h>
32
33         int val_create_context(const char *label, val_context_t **newcontext);
34
35         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
41         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
48         char *p_val_status(val_status_t valerrno);
49
50         char *p_ac_status(val_astatus_t auth_chain_status);
51
52         char *p_val_error(int err);
53
54         int val_istrusted(val_status_t val_status);
55
56         int val_isvalidated(val_status_t val_status);
57
58         int val_does_not_exist(val_status_t status);
59
60         void val_free_result_chain(struct val_result_chain *results);
61
62         void val_free_context(val_context_t *context);
63
64         char *resolv_conf_get(void);
65
66         int resolv_conf_set(const char *name);
67
68         char *root_hints_get(void);
69
70         int root_hints_set(const char *name);
71
72         char *dnsval_conf_get(void);
73
74         int dnsval_conf_set(const char *name);
75

DESCRIPTION

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
85       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
92       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
99       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
111       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
116       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
121       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
126       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
132       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
136       val_istrusted() identifies if a given validator status value is
137       trusted.  An answer may be locally trusted without being validated.
138
139       val_does_not_exist() identifies if a given validator status value cor‐
140       responds to one of the non-existence types.
141
142       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

DATA STRUCTURES

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
157           val_rc_answer
158               Authentication chain for a given RRset.
159
160           val_rc_next
161               Pointer to the next RRset in the set of answers returned for a
162               query.
163
164           val_rc_proofs
165               Pointer to authentication chains for any proof of non-existence
166               that were returned for the query.
167
168           val_rc_proof_count
169               Number of proof elements stored in val_rc_proofs. The number
170               cannot exceed MAX_PROOFS.
171
172           val_rc_status
173               Validation status for a given RRset.  This can be one of the
174               following:
175
176                   VAL_SUCCESS
177                       Answer received and validated successfully.
178
179                   VAL_LOCAL_ANSWER
180                       Answer was available from a local file.
181
182                   VAL_BARE_RRSIG
183                       No DNSSEC validation possible, query was
184                       for an RRSIG.
185
186                   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
192                   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
198                   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
205                   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
213                   VAL_DNS_CONFLICTING_ANSWERS
214                       Multiple conflicting answers received for a query.
215
216                   VAL_DNS_QUERY_ERROR
217                       Some error was encountered while sending the query.
218
219                   VAL_DNS_RESPONSE_ERROR
220                       No response returned or response with an error
221                       rcode value returned.
222
223                   VAL_DNS_WRONG_ANSWER
224                       Wrong answer received for a query.
225
226                   VAL_DNS_REFERRAL_ERROR
227                       Some error encountered while following referrals.
228
229                   VAL_DNS_MISSING_GLUE
230                       Glue was missing.
231
232                   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
238                   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
244                   VAL_NOTRUST
245                       All available components in the authentication
246                       chain verified properly, but there was no trust
247                       anchor available.
248
249                   VAL_IGNORE_VALIDATION
250                       Local policy was configured to ignore validation
251                       for the zone from which this data was received.
252
253                   VAL_TRUSTED_ZONE
254                       Local policy was configured to trust
255                       any data received from the given zone.
256
257                   VAL_UNTRUSTED_ZONE
258                       Local policy was configured to reject
259                       any data received from the given zone.
260
261                   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
266                   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
272               Status values in val_status_t returned by the validator can be
273               displayed in ASCII format using p_val_status().
274
275       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
283           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
289                   VAL_AC_UNSET
290                       The status was not set.
291
292                   VAL_AC_DATA_MISSING
293                       No data were returned for a query and the
294                       DNS did not indicate an error.
295
296                   VAL_AC_RRSIG_MISSING
297                       RRSIG data could not be retrieved for a
298                       resource record.
299
300                   VAL_AC_DNSKEY_MISSING
301                       The DNSKEY for an RRSIG covering a resource
302                       record could not be retrieved.
303
304                   VAL_AC_DS_MISSING
305                       The DS record covering a DNSKEY record was
306                       not available.
307
308                   VAL_AC_NOT_VERIFIED
309                       All RRSIGs covering the RRset could not
310                       be verified.
311
312                   VAL_AC_VERIFIED
313                       At least one RRSIG covering a resource
314                       record had a status of VAL_AC_RRSIG_VERIFIED.
315
316                   VAL_AC_TRUST_KEY
317                       A given DNSKEY or a DS record was locally
318                       defined to be a trust anchor.
319
320                   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
325                   VAL_AC_TRUSTED_ZONE
326                       Local policy defined a given zone as trusted, with
327                       no further validation being deemed necessary.
328
329                   VAL_AC_UNTRUSTED_ZONE
330                       Local policy defined a given zone as untrusted,
331                       with no further validation being deemed necessary.
332
333                   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
339                   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
344                   VAL_AC_NO_TRUST_ANCHOR
345                       There was no trust anchor configured for a given
346                       authentication chain.
347
348                   VAL_AC_DNS_CONFLICTING_ANSWERS
349                       Multiple conflicting answers received for a query.
350
351                   VAL_AC_DNS_QUERY_ERROR
352                       Some error was encountered while sending the query.
353
354                   VAL_AC_DNS_RESPONSE_ERROR
355                       No response returned or response with an error
356                       rcode value returned.
357
358                   VAL_AC_DNS_WRONG_ANSWER
359                       Wrong answer received for a query.
360
361                   VAL_AC_DNS_REFERRAL_ERROR
362                       Some error encountered while following referrals.
363
364                   VAL_AC_DNS_MISSING_GLUE
365                       Glue was missing.
366
367           val_ac_rrset
368               Pointer to an RRset of type struct val_rrset obtained from the
369               DNS response.
370
371           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
377       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
392           val_msg_header
393               Header of the DNS response in which the RRset was received.
394
395           val_msg_headerlen
396               Length of the header information in val_msg_header.
397
398           val_rrset_name_n
399               Owner name of the RRset represented in on-the-wire format.
400
401           val_rrset_class_h
402               Class of the RRset.
403
404           val_val_rrset_type_h
405               Type of the RRset.
406
407           val_rrset_ttl_h
408               TTL of the RRset.
409
410           val_rrset_ttl_x
411               The time when the TTL for this RRset is set to expire.
412
413           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
417           val_rrset_data
418               Response RDATA.
419
420           val_rrset_sig
421               Any associated RRSIGs for the RDATA returned in val_rrset_data.
422
423           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
432               rr_rdata_length_h
433                   Length of data stored in rr_rdata.
434
435               rr_rdata
436                   RDATA bytes.
437
438               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
443                       VAL_AC_RRSIG_VERIFIED
444                           The RRSIG verified successfully.
445
446                       VAL_AC_WCARD_VERIFIED
447                           A given RRSIG covering a resource record shows
448                           that the record was wildcard expanded.
449
450                       VAL_AC_RRSIG_VERIFIED_SKEW
451                           The RRSIG verified successfully after clock
452                           skew was taken into account.
453
454                       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
459                       VAL_AC_RRSIG_VERIFY_FAILED
460                           A given RRSIG covering an RRset was bogus.
461
462                       VAL_AC_DNSKEY_NOMATCH
463                           An RRSIG was created by a DNSKEY that did not
464                           exist in the apex keyset.
465
466                       VAL_AC_RRSIG_ALGORITHM_MISMATCH
467                           The keytag referenced in the RRSIG matched a
468                           DNSKEY but the algorithms were different.
469
470                       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
474                       VAL_AC_BAD_DELEGATION
475                           An RRSIG was created with a key that did not
476                           exist in the parent DS record set.
477
478                       VAL_AC_RRSIG_NOTYETACTIVE
479                           The RRSIG's inception time is in the future.
480
481                       VAL_AC_RRSIG_EXPIRED
482                           The RRSIG had expired.
483
484                       VAL_AC_INVALID_RRSIG
485                           The RRSIG could not be parsed.
486
487                       VAL_AC_ALGORITHM_NOT_SUPPORTED
488                           The RRSIG algorithm was not supported.
489
490                   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
495                       VAL_AC_SIGNING_KEY
496                           This DNSKEY was used to create an RRSIG for
497                           the resource record set.
498
499                       VAL_AC_VERIFIED_LINK
500                           This DNSKEY provided the link in the authentication
501                           chain from the trust anchor to the signed record.
502
503                       VAL_AC_UNKNOWN_DNSKEY_PROTOCOL
504                           The DNSKEY protocol number was unrecognized.
505
506                       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
511                       VAL_AC_INVALID_KEY
512                           The key used to verify the RRSIG was not a valid
513                           DNSKEY.
514
515                       VAL_AC_ALGORITHM_NOT_SUPPORTED
516                           The DNSKEY or DS algorithm was not supported.
517
518           rr_next
519               Points to the next resource record in the RRset.
520

RETURN VALUES

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
525       val_resolve_and_check()
526           VAL_NO_ERROR
527               No error was encountered.
528
529           VAL_GENERIC_ERROR
530               Generic error encountered.
531
532           VAL_NOT_IMPLEMENTED
533               Functionality not yet implemented.
534
535           VAL_BAD_ARGUMENT
536               Bad arguments passed as parameters.
537
538           VAL_INTERNAL_ERROR
539               Encountered some internal error.
540
541           VAL_NO_PERMISSION
542               No permission to perform operation.  Currently not implemented.
543
544           VAL_RESOURCE_UNAVAILABLE
545               Some resource (crypto possibly) was unavailable.  Currently not
546               implemented.
547
548       val_create_context() and val_create_context_with_conf()
549           VAL_NO_ERROR
550               No error was encountered.
551
552           VAL_RESOURCE_UNAVAILABLE
553               Could not allocate memory.
554
555           VAL_CONF_PARSE_ERROR
556               Error in parsing some configuration file.
557
558           VAL_CONF_NOT_FOUND
559               A configuration file was not available.
560
561           VAL_NO_POLICY
562               The policy identifier being referenced was invalid.
563

FILES

565       The validator library reads configuration information from two files,
566       /etc/resolv.conf and /etc/dnsval.conf.
567
568       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

AUTHORS

575       Suresh Krishnaswamy, Robert Story
576

SEE ALSO

578       libsres(3)
579
580       dnsval.conf(5)
581
582       http://dnssec-tools.sourceforge.net
583
584
585
586perl v5.8.6                       2007-09-11                         LIBVAL(1)
Impressum