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

NAME

6       Net::DNS::SEC::Validator - interface to libval(3) and related
7       constants, structures and functions
8

SYNOPSIS

10         use Net::DNS::SEC::Validator;
11         use Net::DNS::Packet;
12         use Net::hostent;
13         use Net::addrinfo;
14         use Socket qw(:all);
15
16         sub callback {
17
18         }
19
20         my $validator = new Net::DNS::SEC::Validator(policy => ":");
21         $validator.map_ns("dnssec-tools.org", "127.0.0.1");
22         my (@r) = $validator->getaddrinfo("good-A.test.dnssec-tools.org");
23         my $r = $validator->res_query("dnssec-tools.org", "IN", "MX");
24         my $h = $validator->gethostbyname("good-AAAA.test.dnssec-tools.org",
25                                           AF_INET6);
26
27         $validator->async_submit("badsign-a.test.dnssec-tools.org",
28               "IN", "A", 0, \&callback, undef);
29         do {
30           my $ref = $val->async_gather($readfds, $timeout);
31           my $ret = $ref->[0];
32           my $readfds = $ref->[1];
33           my $timeout = $ref->[2];
34
35           if (! @$readfds) {
36               last;
37           }
38
39           my @readyarr = IO::Select->new(@$readfds)->can_read($timeout);
40           $ret = $validator->async_check(\@readyarr);
41
42         } while(1);
43

DESCRIPTION

45       The Validator module provides provides access to the libval(3)
46       validating DNS resolver library.  The library functions are accessed
47       through an object-oriented interface.  The interface is designed to
48       hide some of the complexity of validating resolvers.  Application-
49       interface behavior can be customized through configuration files
50       provided by libval, and extensive error codes are returned.
51
52       Since Validator is a gateway to libval, documentation for libval will
53       provide further details on how the Validator interfaces and parameters
54       may be used.
55
56       Details of DNSSEC and associated resolver behavior may be found in the
57       core DNSSEC RFCs (4033-4035).
58

INTERFACE

60       This module suppors both synchronous and ansynchronous lookups. A
61       description of the API follows.
62
63   Validator Constructor
64       This constructor builds a new validator object, which is used to make
65       the various resolver calls.  When the validator object is created, a
66       policy object is created.  The policy object provides a number of
67       settings that will control various aspects of the DNS resolution.
68
69       To create a validator object use the Net::DNS::SEC::Validator-new()>
70       method.  This method takes a number of optional parameters, which will
71       be described below.
72
73       A policy object may be named with the policy parameter, which
74       associates a label with a particular policy.  This allows that policy
75       to be referenced at a later time.  If the label isn't specified, then
76       it will be given the the default label from the libval dnsval.conf
77       file.
78
79       The parameters to the constructor are passed as a hash, with both key
80       and value given in the call.  Besides the policy label, there are two
81       sets of constructor parameters.  These are separated based on how they
82       are stored and used in libval.
83
84       Context Options
85
86       This group of parameters are stored in a val_context_opt structure in
87       libval.  This structure is defined in
88       dnssec/validator/include/validator/validator.h.  The context options
89       below are the hash-key values used in the constructor call.
90
91       dnsval_conf
92           Configuration policy for the libval library.
93
94           This file contains the validator policy.  The default value is
95           /usr/local/etc/dnssec-tools/dnsval.conf, but this may have been
96           changed when libval was built and installed.
97
98           val_context_opt field:  vc_val_conf
99
100       nslist
101           This is a list of name servers that should be used in resolving
102           names.  This must be a white-space delimited list of IP or IPv6
103           addresses.
104
105           val_context_opt field:  vc_nslist
106
107       polflags
108           This is a set of bitmapped policy flags.  The valid flags are
109           defined in dnssec/validator/include/validator/validator.h.  The
110           default value is CTX_DYN_POL_RES_OVR.
111
112           val_context_opt field:  vc_polflags
113
114       qflags
115           This is the set of default query flags.  The valid flags are
116           defined in dnssec/validator/include/validator/validator.h.  The
117           default value is 0.
118
119           val_context_opt field:  vc_qflags
120
121       resolv_conf
122           This file contains nameserver and search options for the libval
123           library.  The default value is
124           /usr/local/etc/dnssec-tools/resolv.conf, but this may have been
125           changed when libval was built and installed.
126
127           val_context_opt field:  vc_res_conf
128
129       root_hints
130           This file contains bootstrapping information for the name resolver.
131           The default value is /usr/local/etc/dnssec-tools/root.hints, but
132           this may have been changed when libval was built and installed.
133
134           val_context_opt field:  vc_root_conf
135
136       valpol
137           This supplies a customized piece of validator configuration to the
138           default validator configuration as an extension or an override.
139           This is null by default.
140
141           val_context_opt field:  vc_valpol
142
143       Global Options
144
145       This group of parameters are stored in a val_global_opt structure,
146       which is itself stored in a the gopt field of the val_context_opt
147       structure.  This structure is defined in
148       dnssec/validator/include/validator/validator.h.  The global options
149       below are the hash-key values used in the constructor call.
150
151       For all but the log_target field, a value of -1 indicates an "ignore"
152       condition.  This means that the validator will not include dynamically
153       supplied global options with a value of -1 when creating its context.
154       This allows an application to override a subset of global options while
155       using the global options supplied in the dnsval.conf file by default.
156
157       Even though libval uses the global options in a separate structure from
158       the context options, they are all specified in the same hash when
159       passed as parameters to the Validator constructor.
160
161       app_policy
162           This field is equivalent to the env-policy option in a dnsval.conf
163           file.  The following are the legal values and their env-policy
164           equivalences:
165
166               VAL_POL_GOPT_DISABLE       "disable"
167               VAL_POL_GOPT_ENABLE        "enable"
168               VAL_POL_GOPT_OVERRIDE      "override"
169
170           The default value is -1.
171
172           val_global_opt field:  gopt.app_policy
173
174       closest_ta_only
175           This field is equivalent to the closest-ta-only option in a
176           dnsval.conf file.  Setting this to 1 is equivalent to setting
177           closest-ta-only to "yes"; setting it to 0 is equivalent to "no".
178           The default value is -1.
179
180           val_global_opt field:  gopt.closest_ta_only
181
182       edns0_size
183           This field is equivalent to the edns0-size option in a dnsval.conf
184           file.  The default value is -1.
185
186           val_global_opt field:  gopt.edns0_size
187
188       env_policy
189           This field is equivalent to the env-policy option in a dnsval.conf
190           file.  The following are the legal values and their env-policy
191           equivalences:
192
193               VAL_POL_GOPT_DISABLE       "disable"
194               VAL_POL_GOPT_ENABLE        "enable"
195               VAL_POL_GOPT_OVERRIDE      "override"
196
197           The default value is -1.
198
199           val_global_opt field:  gopt.env_policy
200
201       local_is_trusted
202           This field is equivalent to the trust-oob-answers option in a
203           dnsval.conf file.  Setting this to 1 is equivalent to setting
204           trust-oob-answers to "yes"; setting it to 0 is equivalent to "no".
205           The default value is -1.
206
207           val_global_opt field:  gopt.local_is_trusted
208
209       log_target
210           This field allows the caller to specify additional log targets to
211           those given in the dnsval.conf file.  No additional logs are listed
212           by default.
213
214           val_global_opt field:  gopt.log_target
215
216       rec_fallback
217           This field is equivalent to the rec-fallback option in a
218           dnsval.conf file.  Setting this to 1 is equivalent to setting rec-
219           fallback to "yes"; setting it to 0 is equivalent to "no".  The
220           default value is -1.
221
222           val_global_opt field:  gopt.rec_fallback
223
224       max_refresh
225           This field is equivalent to the max-refresh option in a dnsval.conf
226           file.
227
228           val_global_opt field:  gopt.max_refresh
229
230       proto
231           This field is equivalent to the proto option in a dnsval.conf file.
232           Setting this value to 1 is equivalent to setting proto to "ipv4";
233           setting this value to 2 is equivalent to setting proto to "ipv6".
234           The default is 0, which is equivalent to setting proto to "any".
235
236           val_global_opt field:  gopt.proto
237
238       timeout
239           This field is equivalent to the timeout option in a dnsval.conf
240           file.
241
242           val_global_opt field:  gopt.timeout
243
244       retry
245           This field is equivalent to the retry option in a dnsval.conf file.
246
247           val_global_opt field:  gopt.retry
248
249       Validator Result Fields
250
251       Operation status and results are found in the following validator
252       fields:
253
254         $validator->{error}        => the latest method error code
255         $validator->{errorStr}     => the latest method error string
256         $validator->{valStatus}    => the val_status of last call (if single)
257         $validator->{valStatusStr} => the val_status string of last call
258
259       Values for these fields are described in the next section.
260
261   $validator->getaddrinfo(<name>[,<service>[,<hints>]])
262       where:
263
264           <name> => is the node name or numeric address being queried
265           <service> => is the name or number representing the service
266           (note: <name> or <service> may be undef, but not both)
267           <hint> => a Net::addrinfo object specifying flags, family, etc.
268
269       returns:
270
271           An array of Net::addrinfo objects (augmented with a 'val_status'
272           field). On error, returns an empty array. in scalar context
273           returns first Net::addrinfo object, or undef on error.
274
275   $validator->gethostbyname(<name>[,<family>])
276       where:
277
278           <name> => is the node name or numeric address being queried
279           <family> => the address family of returned entry (default: AF_INET)
280
281       returns:
282
283           A Net::hostent object. Validator valStatus/valStatusStr fields
284           will be updated. On error, undef is returned and validator object
285           error/errorStr fields are updated.
286
287   $validator->res_query(<name>[,<class>[,<type>]])
288       where:
289
290           <name>      => is the node name or numeric address being queried
291           <class>     => is the DNS class of the record being queried (default: IN)
292           <type>      => is the DNS record type being queried (default A)
293
294       returns:
295
296           A packed DNS query result is returned on success. This object is
297           suitable to be passed to the Net::DNS::Packet(\$result)
298           interface for parsing. Validator valStatus/valStatusStr fields
299           will be updated. On error, undef is returned and validator
300           object error/errorStr fields are updated.
301
302   $validator->policy([<label>])
303       where:
304
305           <label>     => the policy label to use (old context is destroyed)
306           (default: ":" dnsval.conf default policy)
307
308       returns:
309
310           the policy label currently (after change) being used.
311
312   $validator->istrusted([<val_status>])
313       where:
314
315           <val_status> => numeric validator status code
316           (default: $validator->{valStatus})
317
318       returns:
319
320           A boolean positive value if <val_status> is a trusted result.
321
322   $validator->valStatusStr([<val_status>])
323       where:
324
325           <val_status> => numeric validator status code
326           (default: $validator->{valStatus})
327
328       returns:
329
330           A string representation of the given <val_status>.
331
332   $validator->map_ns(<zone>, <ipaddr>, <recursive>)
333       where:
334
335           <zone> => string value for zone
336           <ipaddr> => The IP address to which all queries associated with the
337                       above 'zone' should be directed.
338           <recursive> => if set to 1, this name server is considered to
339           recursive (queries are sent with the RD bit set). The default value
340           is to consder the name server to be authoritative.
341
342       returns:
343
344           0 if the association between the zone and the IP address could be
345           made successfully; some other value if the association could not be
346           created.
347

VALIDATOR DATA FIELDS

349       The validator's error and errorStr fields are set with values
350       corresponding to those from the standard herror() and hstrerror()
351       functions.  These values are defined in netdb.h.  These values are:
352
353         error      errorStr
354           0        Resolver Error 0 (no error)
355           1        Unknown host
356           2        Host name lookup failure
357           3        Unknown server error
358           4        No address associated with name
359
360       The values for the validator's valStatus field are defined in
361       .../dnssec-tools/validator/include/validator/val_errors.h.  The values
362       for the valStatusStr fields are the text representation of the status
363       values' constants.  The different possible values for valStatus are
364       listed below, and further details are provided in libval(3):
365
366           VAL_BARE_RRSIG
367           VAL_INDETERMINATE
368           VAL_BOGUS
369           VAL_DNS_ERROR
370           VAL_IGNORE_VALIDATION
371           VAL_NONEXISTENT_NAME
372           VAL_NONEXISTENT_NAME_NOCHAIN
373           VAL_NONEXISTENT_TYPE
374           VAL_NONEXISTENT_TYPE_NOCHAIN
375           VAL_NOTRUST
376           VAL_OOB_ANSWER
377           VAL_PINSECURE
378           VAL_PINSECURE_UNTRUSTED
379           VAL_SUCCESS
380           VAL_TRUSTED_ANSWER
381           VAL_UNTRUSTED_ANSWER
382           VAL_UNTRUSTED_ZONE
383           VAL_VALIDATED_ANSWER
384
385       The istrusted() and isvalidated() functions can be used to test if a
386       particular valStatus value corresponds to a trusted or a validated
387       status condition. Status values that are neither trusted nor validated
388       are un-trustworthy and must be treated as such by the application.
389

EXAMPLES

391         use Net::DNS::SEC::Validator;
392         use Net::DNS::Packet;
393         use Net::hostent;
394         use Net::addrinfo;
395         use Socket qw(:all);
396
397         # construct object
398         my $validator = new Net::DNS::SEC::Validator(policy => ":");
399
400         # change validation policy
401         $validator->policy("validate_tools:");
402
403         # fetch array of Net::addrinfo objects
404         my (@r) = $validator->getaddrinfo("good-A.test.dnssec-tools.org");
405         foreach $a (@r) {
406            print $a->stringify, " is trusted\n"
407               if $validator->istrusted($a->val_status));
408         }
409
410         # query an MX record
411         my $r = $validator->res_query("dnssec-tools.org", "IN", "MX");
412         my ($pkt, $err) = new Net::DNS::Packet(\$r);
413         print ($validator->istrusted ?
414               "result is trusted\n" :
415               "result is NOT trusted\n");
416
417         my $h = $validator->gethostbyname("good-A.test.dnssec-tools.org");
418         if ( @{$h->addr_list}) {
419         my $i;
420            for $addr ( @{$h->addr_list} ) {
421               printf "\taddr #%d is [%s]\n", $i++, inet_ntoa($addr);
422            }
423         }
424
425         # get details of validation
426         my $a = $validator->resolve_and_check("good-a.test.dnssec-tools.org", "IN", "A", 0);
427         foreach my $h (@$a) {
428          print "Status: " .  ${$h}{status} . "\n";
429          print ($validator->istrusted(${$h}{status}) ?
430                  "result is trusted\n" :
431                  "result is NOT trusted\n");
432
433          $acs = ${$h}{answer};
434          foreach my $ac ($acs) {
435               print "AC status: " . ${$ac}{status} . "\n";
436               $acr = ${$ac}{rrset};
437               $acd = ${$acr}{data};
438               foreach $d (@$acd) {
439                   print "Data RR status: " . ${$d}{rrstatus} . "\n";
440                   ${$d}{rrdata}->print;
441               }
442               $acs = ${$acr}{sigs};
443               foreach $d (@$acs) {
444                   print "Sig RR status: " . ${$d}{rrstatus} . "\n";
445                   ${$d}{rrdata}->print;
446               }
447          }
448       }
449

SEE ALSO

451       libval(3), dnsval.conf(3), resolv.conf(3), root.hints(3)
452
454       Copyright (c) 2006 G. S. Marzot. All rights reserved.  This program is
455       free software; you can redistribute it and/or modify it under the same
456       terms as Perl itself.
457
458       Copyright (c) 2006-2013 SPARTA, Inc.  All Rights Reserved.  This
459       program is free software; you can redistribute it and/or modify it
460       under the same terms as Perl itself.
461

AUTHOR

463        G. S. Marzot (marz@users.sourceforge.net)
464
465
466
467perl v5.36.0                      2022-07-21                      Validator(3)
Impressum