.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Validator 3" .TH Validator 3 2023-07-29 "perl v5.38.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Net::DNS::SEC::Validator \- interface to libval(3) and related constants, structures and functions .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 5 \& use Net::DNS::SEC::Validator; \& use Net::DNS::Packet; \& use Net::hostent; \& use Net::addrinfo; \& use Socket qw(:all); \& \& sub callback { \& \& } \& \& my $validator = new Net::DNS::SEC::Validator(policy => ":"); \& $validator.map_ns("dnssec\-tools.org", "127.0.0.1"); \& my (@r) = $validator\->getaddrinfo("good\-A.test.dnssec\-tools.org"); \& my $r = $validator\->res_query("dnssec\-tools.org", "IN", "MX"); \& my $h = $validator\->gethostbyname("good\-AAAA.test.dnssec\-tools.org", \& AF_INET6); \& \& $validator\->async_submit("badsign\-a.test.dnssec\-tools.org", \& "IN", "A", 0, \e&callback, undef); \& do { \& my $ref = $val\->async_gather($readfds, $timeout); \& my $ret = $ref\->[0]; \& my $readfds = $ref\->[1]; \& my $timeout = $ref\->[2]; \& \& if (! @$readfds) { \& last; \& } \& \& my @readyarr = IO::Select\->new(@$readfds)\->can_read($timeout); \& $ret = $validator\->async_check(\e@readyarr); \& \& } while(1); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" The \fBValidator\fR module provides provides access to the \fBlibval\|(3)\fR validating DNS resolver library. The library functions are accessed through an object-oriented interface. The interface is designed to hide some of the complexity of validating resolvers. Application-interface behavior can be customized through configuration files provided by \fBlibval\fR, and extensive error codes are returned. .PP Since \fBValidator\fR is a gateway to \fBlibval\fR, documentation for \fBlibval\fR will provide further details on how the \fBValidator\fR interfaces and parameters may be used. .PP Details of DNSSEC and associated resolver behavior may be found in the core DNSSEC RFCs (4033\-4035). .SH INTERFACE .IX Header "INTERFACE" This module suppors both synchronous and ansynchronous lookups. A description of the API follows. .SS "\fBValidator\fP Constructor" .IX Subsection "Validator Constructor" This constructor builds a new validator object, which is used to make the various resolver calls. When the validator object is created, a \fIpolicy\fR object is created. The \fIpolicy\fR object provides a number of settings that will control various aspects of the DNS resolution. .PP To create a validator object use the \fINet::DNS::SEC::Validator\-\fR\fBnew()\fR> method. This method takes a number of optional parameters, which will be described below. .PP A policy object may be named with the \fIpolicy\fR parameter, which associates a label with a particular policy. This allows that policy to be referenced at a later time. If the label isn't specified, then it will be given the the default label from the \fBlibval\fR \fBdnsval.conf\fR file. .PP The parameters to the constructor are passed as a hash, with both key and value given in the call. Besides the policy label, there are two sets of constructor parameters. These are separated based on how they are stored and used in \fBlibval\fR. .PP \fIContext Options\fR .IX Subsection "Context Options" .PP This group of parameters are stored in a \fIval_context_opt\fR structure in \&\fBlibval\fR. This structure is defined in \&\fBdnssec/validator/include/validator/validator.h\fR. The context options below are the hash-key values used in the constructor call. .IP \fIdnsval_conf\fR 4 .IX Item "dnsval_conf" Configuration policy for the \fBlibval\fR library. .Sp This file contains the validator policy. The default value is \&\fB/usr/local/etc/dnssec\-tools/dnsval.conf\fR, but this may have been changed when \fBlibval\fR was built and installed. .Sp \&\fIval_context_opt\fR field: \fIvc_val_conf\fR .IP \fInslist\fR 4 .IX Item "nslist" This is a list of name servers that should be used in resolving names. This must be a white-space delimited list of IP or IPv6 addresses. .Sp \&\fIval_context_opt\fR field: \fIvc_nslist\fR .IP \fIpolflags\fR 4 .IX Item "polflags" This is a set of bitmapped policy flags. The valid flags are defined in \&\fBdnssec/validator/include/validator/validator.h\fR. The default value is \&\fBCTX_DYN_POL_RES_OVR\fR. .Sp \&\fIval_context_opt\fR field: \fIvc_polflags\fR .IP \fIqflags\fR 4 .IX Item "qflags" This is the set of default query flags. The valid flags are defined in \&\fBdnssec/validator/include/validator/validator.h\fR. The default value is 0. .Sp \&\fIval_context_opt\fR field: \fIvc_qflags\fR .IP \fIresolv_conf\fR 4 .IX Item "resolv_conf" This file contains nameserver and search options for the \fBlibval\fR library. The default value is \fB/usr/local/etc/dnssec\-tools/resolv.conf\fR, but this may have been changed when \fBlibval\fR was built and installed. .Sp \&\fIval_context_opt\fR field: \fIvc_res_conf\fR .IP \fIroot_hints\fR 4 .IX Item "root_hints" This file contains bootstrapping information for the name resolver. The default value is \fB/usr/local/etc/dnssec\-tools/root.hints\fR, but this may have been changed when \fBlibval\fR was built and installed. .Sp \&\fIval_context_opt\fR field: \fIvc_root_conf\fR .IP \fIvalpol\fR 4 .IX Item "valpol" This supplies a customized piece of validator configuration to the default validator configuration as an extension or an override. This is null by default. .Sp \&\fIval_context_opt\fR field: \fIvc_valpol\fR .PP \fIGlobal Options\fR .IX Subsection "Global Options" .PP This group of parameters are stored in a \fIval_global_opt\fR structure, which is itself stored in a the \fIgopt\fR field of the \fIval_context_opt\fR structure. This structure is defined in \fBdnssec/validator/include/validator/validator.h\fR. The global options below are the hash-key values used in the constructor call. .PP For all but the \fIlog_target\fR field, a value of \-1 indicates an "ignore" condition. This means that the validator will not include dynamically supplied global options with a value of \-1 when creating its context. This allows an application to override a subset of global options while using the global options supplied in the \fBdnsval.conf\fR file by default. .PP Even though \fBlibval\fR uses the global options in a separate structure from the context options, they are all specified in the same hash when passed as parameters to the \fBValidator\fR constructor. .IP \fIapp_policy\fR 4 .IX Item "app_policy" This field is equivalent to the \fIenv-policy\fR option in a \fBdnsval.conf\fR file. The following are the legal values and their \fIenv-policy\fR equivalences: .Sp .Vb 3 \& VAL_POL_GOPT_DISABLE "disable" \& VAL_POL_GOPT_ENABLE "enable" \& VAL_POL_GOPT_OVERRIDE "override" .Ve .Sp The default value is \-1. .Sp \&\fIval_global_opt\fR field: \fIgopt.app_policy\fR .IP \fIclosest_ta_only\fR 4 .IX Item "closest_ta_only" This field is equivalent to the \fIclosest-ta-only\fR option in a \fBdnsval.conf\fR file. Setting this to 1 is equivalent to setting \fIclosest-ta-only\fR to "yes"; setting it to 0 is equivalent to "no". The default value is \-1. .Sp \&\fIval_global_opt\fR field: \fIgopt.closest_ta_only\fR .IP \fIedns0_size\fR 4 .IX Item "edns0_size" This field is equivalent to the \fIedns0\-size\fR option in a \fBdnsval.conf\fR file. The default value is \-1. .Sp \&\fIval_global_opt\fR field: \fIgopt.edns0_size\fR .IP \fIenv_policy\fR 4 .IX Item "env_policy" This field is equivalent to the \fIenv-policy\fR option in a \fBdnsval.conf\fR file. The following are the legal values and their \fIenv-policy\fR equivalences: .Sp .Vb 3 \& VAL_POL_GOPT_DISABLE "disable" \& VAL_POL_GOPT_ENABLE "enable" \& VAL_POL_GOPT_OVERRIDE "override" .Ve .Sp The default value is \-1. .Sp \&\fIval_global_opt\fR field: \fIgopt.env_policy\fR .IP \fIlocal_is_trusted\fR 4 .IX Item "local_is_trusted" This field is equivalent to the \fItrust-oob-answers\fR option in a \&\fBdnsval.conf\fR file. Setting this to 1 is equivalent to setting \&\fItrust-oob-answers\fR to "yes"; setting it to 0 is equivalent to "no". The default value is \-1. .Sp \&\fIval_global_opt\fR field: \fIgopt.local_is_trusted\fR .IP \fIlog_target\fR 4 .IX Item "log_target" This field allows the caller to specify additional log targets to those given in the \fBdnsval.conf\fR file. No additional logs are listed by default. .Sp \&\fIval_global_opt\fR field: \fIgopt.log_target\fR .IP \fIrec_fallback\fR 4 .IX Item "rec_fallback" This field is equivalent to the \fIrec-fallback\fR option in a \fBdnsval.conf\fR file. Setting this to 1 is equivalent to setting \fIrec-fallback\fR to "yes"; setting it to 0 is equivalent to "no". The default value is \-1. .Sp \&\fIval_global_opt\fR field: \fIgopt.rec_fallback\fR .IP \fImax_refresh\fR 4 .IX Item "max_refresh" This field is equivalent to the \fImax-refresh\fR option in a \fBdnsval.conf\fR file. .Sp \&\fIval_global_opt\fR field: \fIgopt.max_refresh\fR .IP \fIproto\fR 4 .IX Item "proto" This field is equivalent to the \fIproto\fR option in a \fBdnsval.conf\fR file. Setting this value to 1 is equivalent to setting \fIproto\fR to "ipv4"; setting this value to 2 is equivalent to setting \fIproto\fR to "ipv6". The default is 0, which is equivalent to setting \fIproto\fR to "any". .Sp \&\fIval_global_opt\fR field: \fIgopt.proto\fR .IP \fItimeout\fR 4 .IX Item "timeout" This field is equivalent to the \fItimeout\fR option in a \fBdnsval.conf\fR file. .Sp \&\fIval_global_opt\fR field: \fIgopt.timeout\fR .IP \fIretry\fR 4 .IX Item "retry" This field is equivalent to the \fIretry\fR option in a \fBdnsval.conf\fR file. .Sp \&\fIval_global_opt\fR field: \fIgopt.retry\fR .PP \fIValidator Result Fields\fR .IX Subsection "Validator Result Fields" .PP Operation status and results are found in the following validator fields: .PP .Vb 4 \& $validator\->{error} => the latest method error code \& $validator\->{errorStr} => the latest method error string \& $validator\->{valStatus} => the val_status of last call (if single) \& $validator\->{valStatusStr} => the val_status string of last call .Ve .PP Values for these fields are described in the next section. .ie n .SS $validator\->getaddrinfo([,[,]]) .el .SS \f(CW$validator\fP\->getaddrinfo([,[,]]) .IX Subsection "$validator->getaddrinfo([,[,]])" \fIwhere:\fR .IX Subsection "where:" .PP .Vb 4 \& => is the node name or numeric address being queried \& => is the name or number representing the service \& (note: or may be undef, but not both) \& => a Net::addrinfo object specifying flags, family, etc. .Ve .PP \fIreturns:\fR .IX Subsection "returns:" .PP .Vb 3 \& An array of Net::addrinfo objects (augmented with a \*(Aqval_status\*(Aq \& field). On error, returns an empty array. in scalar context \& returns first Net::addrinfo object, or undef on error. .Ve .ie n .SS $validator\->gethostbyname([,]) .el .SS \f(CW$validator\fP\->gethostbyname([,]) .IX Subsection "$validator->gethostbyname([,])" \fIwhere:\fR .IX Subsection "where:" .PP .Vb 2 \& => is the node name or numeric address being queried \& => the address family of returned entry (default: AF_INET) .Ve .PP \fIreturns:\fR .IX Subsection "returns:" .PP .Vb 3 \& A Net::hostent object. Validator valStatus/valStatusStr fields \& will be updated. On error, undef is returned and validator object \& error/errorStr fields are updated. .Ve .ie n .SS $validator\->res_query([,[,]]) .el .SS \f(CW$validator\fP\->res_query([,[,]]) .IX Subsection "$validator->res_query([,[,]])" \fIwhere:\fR .IX Subsection "where:" .PP .Vb 3 \& => is the node name or numeric address being queried \& => is the DNS class of the record being queried (default: IN) \& => is the DNS record type being queried (default A) .Ve .PP \fIreturns:\fR .IX Subsection "returns:" .PP .Vb 5 \& A packed DNS query result is returned on success. This object is \& suitable to be passed to the Net::DNS::Packet(\e$result) \& interface for parsing. Validator valStatus/valStatusStr fields \& will be updated. On error, undef is returned and validator \& object error/errorStr fields are updated. .Ve .ie n .SS $validator\->policy([