1Validator(3) User Contributed Perl Documentation Validator(3)
2
6 Net::DNS::SEC::Validator - interface to libval(3) and related
7 constants, structures and functions
8
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 sub callback {
17 }
19 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 $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 if (! @$readfds) {
36 last;
37 }
38 my @readyarr = IO::Select->new(@$readfds)->can_read($timeout);
40 $ret = $validator->async_check(\@readyarr);
41 } while(1);
43
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 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 Details of DNSSEC and associated resolver behavior may be found in the
57 core DNSSEC RFCs (4033-4035).
58
60 This module suppors both synchronous and ansynchronous lookups. A
61 description of the API follows.
62 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 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 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 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 Context Options
85 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 dnsval_conf
92 Configuration policy for the libval library.
93 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 val_context_opt field: vc_val_conf
99 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 val_context_opt field: vc_nslist
106 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 val_context_opt field: vc_polflags
113 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 val_context_opt field: vc_qflags
120 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 val_context_opt field: vc_res_conf
128 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 val_context_opt field: vc_root_conf
135 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 val_context_opt field: vc_valpol
142 Global Options
144 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 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 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 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 VAL_POL_GOPT_DISABLE "disable"
167 VAL_POL_GOPT_ENABLE "enable"
168 VAL_POL_GOPT_OVERRIDE "override"
169 The default value is -1.
171 val_global_opt field: gopt.app_policy
173 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 val_global_opt field: gopt.closest_ta_only
181 edns0_size
183 This field is equivalent to the edns0-size option in a dnsval.conf
184 file. The default value is -1.
185 val_global_opt field: gopt.edns0_size
187 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 VAL_POL_GOPT_DISABLE "disable"
194 VAL_POL_GOPT_ENABLE "enable"
195 VAL_POL_GOPT_OVERRIDE "override"
196 The default value is -1.
198 val_global_opt field: gopt.env_policy
200 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 val_global_opt field: gopt.local_is_trusted
208 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 val_global_opt field: gopt.log_target
215 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 val_global_opt field: gopt.rec_fallback
223 max_refresh
225 This field is equivalent to the max-refresh option in a dnsval.conf
226 file.
227 val_global_opt field: gopt.max_refresh
229 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 val_global_opt field: gopt.proto
237 timeout
239 This field is equivalent to the timeout option in a dnsval.conf
240 file.
241 val_global_opt field: gopt.timeout
243 retry
245 This field is equivalent to the retry option in a dnsval.conf file.
246 val_global_opt field: gopt.retry
248 Validator Result Fields
250 Operation status and results are found in the following validator
252 fields:
253 $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 Values for these fields are described in the next section.
260 $validator->getaddrinfo(<name>[,<service>[,<hints>]])
262 where:
263 <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 returns:
270 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 $validator->gethostbyname(<name>[,<family>])
276 where:
277 <name> => is the node name or numeric address being queried
279 <family> => the address family of returned entry (default: AF_INET)
280 returns:
282 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 $validator->res_query(<name>[,<class>[,<type>]])
288 where:
289 <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 returns:
295 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 $validator->policy([<label>])
303 where:
304 <label> => the policy label to use (old context is destroyed)
306 (default: ":" dnsval.conf default policy)
307 returns:
309 the policy label currently (after change) being used.
311 $validator->istrusted([<val_status>])
313 where:
314 <val_status> => numeric validator status code
316 (default: $validator->{valStatus})
317 returns:
319 A boolean positive value if <val_status> is a trusted result.
321 $validator->valStatusStr([<val_status>])
323 where:
324 <val_status> => numeric validator status code
326 (default: $validator->{valStatus})
327 returns:
329 A string representation of the given <val_status>.
331 $validator->map_ns(<zone>, <ipaddr>, <recursive>)
333 where:
334 <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 returns:
343 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
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 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 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 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 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
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 # construct object
398 my $validator = new Net::DNS::SEC::Validator(policy => ":");
399 # change validation policy
401 $validator->policy("validate_tools:");
402 # 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 # 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 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 # 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 $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
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 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
463 G. S. Marzot (marz@users.sourceforge.net)
464perl v5.38.0 2023-07-19 Validator(3)