Validator(3)          User Contributed Perl Documentation         Validator(3)


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

SYNOPSIS
         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, \&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(\@readyarr);

         } while(1);

DESCRIPTION
       The Validator module provides provides access to the libval(3)
       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 libval, and extensive error codes are returned.

       Since Validator is a gateway to libval, documentation for libval will
       provide further details on how the Validator interfaces and parameters
       may be used.

       Details of DNSSEC and associated resolver behavior may be found in the
       core DNSSEC RFCs (4033-4035).

INTERFACE
       This module suppors both synchronous and ansynchronous lookups. A
       description of the API follows.

   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
       policy object is created.  The policy object provides a number of
       settings that will control various aspects of the DNS resolution.

       To create a validator object use the Net::DNS::SEC::Validator-new()>
       method.  This method takes a number of optional parameters, which will
       be described below.

       A policy object may be named with the policy 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 libval dnsval.conf
       file.

       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 libval.

       Context Options

       This group of parameters are stored in a val_context_opt structure in
       libval.  This structure is defined in
       dnssec/validator/include/validator/validator.h.  The context options
       below are the hash-key values used in the constructor call.

       dnsval_conf
           Configuration policy for the libval library.

           This file contains the validator policy.  The default value is
           /usr/local/etc/dnssec-tools/dnsval.conf, but this may have been
           changed when libval was built and installed.

           val_context_opt field:  vc_val_conf

       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.

           val_context_opt field:  vc_nslist

       polflags
           This is a set of bitmapped policy flags.  The valid flags are
           defined in dnssec/validator/include/validator/validator.h.  The
           default value is CTX_DYN_POL_RES_OVR.

           val_context_opt field:  vc_polflags

       qflags
           This is the set of default query flags.  The valid flags are
           defined in dnssec/validator/include/validator/validator.h.  The
           default value is 0.

           val_context_opt field:  vc_qflags

       resolv_conf
           This file contains nameserver and search options for the libval
           library.  The default value is
           /usr/local/etc/dnssec-tools/resolv.conf, but this may have been
           changed when libval was built and installed.

           val_context_opt field:  vc_res_conf

       root_hints
           This file contains bootstrapping information for the name resolver.
           The default value is /usr/local/etc/dnssec-tools/root.hints, but
           this may have been changed when libval was built and installed.

           val_context_opt field:  vc_root_conf

       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.

           val_context_opt field:  vc_valpol

       Global Options

       This group of parameters are stored in a val_global_opt structure,
       which is itself stored in a the gopt field of the val_context_opt
       structure.  This structure is defined in
       dnssec/validator/include/validator/validator.h.  The global options
       below are the hash-key values used in the constructor call.

       For all but the log_target 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 dnsval.conf file by default.

       Even though libval 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 Validator constructor.

       app_policy
           This field is equivalent to the env-policy option in a dnsval.conf
           file.  The following are the legal values and their env-policy
           equivalences:

               VAL_POL_GOPT_DISABLE       "disable"
               VAL_POL_GOPT_ENABLE        "enable"
               VAL_POL_GOPT_OVERRIDE      "override"

           The default value is -1.

           val_global_opt field:  gopt.app_policy

       closest_ta_only
           This field is equivalent to the closest-ta-only option in a
           dnsval.conf file.  Setting this to 1 is equivalent to setting
           closest-ta-only to "yes"; setting it to 0 is equivalent to "no".
           The default value is -1.

           val_global_opt field:  gopt.closest_ta_only

       edns0_size
           This field is equivalent to the edns0-size option in a dnsval.conf
           file.  The default value is -1.

           val_global_opt field:  gopt.edns0_size

       env_policy
           This field is equivalent to the env-policy option in a dnsval.conf
           file.  The following are the legal values and their env-policy
           equivalences:

               VAL_POL_GOPT_DISABLE       "disable"
               VAL_POL_GOPT_ENABLE        "enable"
               VAL_POL_GOPT_OVERRIDE      "override"

           The default value is -1.

           val_global_opt field:  gopt.env_policy

       local_is_trusted
           This field is equivalent to the trust-oob-answers option in a
           dnsval.conf file.  Setting this to 1 is equivalent to setting
           trust-oob-answers to "yes"; setting it to 0 is equivalent to "no".
           The default value is -1.

           val_global_opt field:  gopt.local_is_trusted

       log_target
           This field allows the caller to specify additional log targets to
           those given in the dnsval.conf file.  No additional logs are listed
           by default.

           val_global_opt field:  gopt.log_target

       rec_fallback
           This field is equivalent to the rec-fallback option in a
           dnsval.conf file.  Setting this to 1 is equivalent to setting rec-
           fallback to "yes"; setting it to 0 is equivalent to "no".  The
           default value is -1.

           val_global_opt field:  gopt.rec_fallback

       max_refresh
           This field is equivalent to the max-refresh option in a dnsval.conf
           file.

           val_global_opt field:  gopt.max_refresh

       proto
           This field is equivalent to the proto option in a dnsval.conf file.
           Setting this value to 1 is equivalent to setting proto to "ipv4";
           setting this value to 2 is equivalent to setting proto to "ipv6".
           The default is 0, which is equivalent to setting proto to "any".

           val_global_opt field:  gopt.proto

       timeout
           This field is equivalent to the timeout option in a dnsval.conf
           file.

           val_global_opt field:  gopt.timeout

       retry
           This field is equivalent to the retry option in a dnsval.conf file.

           val_global_opt field:  gopt.retry

       Validator Result Fields

       Operation status and results are found in the following validator
       fields:

         $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

       Values for these fields are described in the next section.

   $validator->getaddrinfo(<name>[,<service>[,<hints>]])
       where:

           <name> => is the node name or numeric address being queried
           <service> => is the name or number representing the service
           (note: <name> or <service> may be undef, but not both)
           <hint> => a Net::addrinfo object specifying flags, family, etc.

       returns:

           An array of Net::addrinfo objects (augmented with a 'val_status'
           field). On error, returns an empty array. in scalar context
           returns first Net::addrinfo object, or undef on error.

   $validator->gethostbyname(<name>[,<family>])
       where:

           <name> => is the node name or numeric address being queried
           <family> => the address family of returned entry (default: AF_INET)

       returns:

           A Net::hostent object. Validator valStatus/valStatusStr fields
           will be updated. On error, undef is returned and validator object
           error/errorStr fields are updated.

   $validator->res_query(<name>[,<class>[,<type>]])
       where:

           <name>      => is the node name or numeric address being queried
           <class>     => is the DNS class of the record being queried (default: IN)
           <type>      => is the DNS record type being queried (default A)

       returns:

           A packed DNS query result is returned on success. This object is
           suitable to be passed to the Net::DNS::Packet(\$result)
           interface for parsing. Validator valStatus/valStatusStr fields
           will be updated. On error, undef is returned and validator
           object error/errorStr fields are updated.

   $validator->policy([<label>])
       where:

           <label>     => the policy label to use (old context is destroyed)
           (default: ":" dnsval.conf default policy)

       returns:

           the policy label currently (after change) being used.

   $validator->istrusted([<val_status>])
       where:

           <val_status> => numeric validator status code
           (default: $validator->{valStatus})

       returns:

           A boolean positive value if <val_status> is a trusted result.

   $validator->valStatusStr([<val_status>])
       where:

           <val_status> => numeric validator status code
           (default: $validator->{valStatus})

       returns:

           A string representation of the given <val_status>.

   $validator->map_ns(<zone>, <ipaddr>, <recursive>)
       where:

           <zone> => string value for zone
           <ipaddr> => The IP address to which all queries associated with the
                       above 'zone' should be directed.
           <recursive> => if set to 1, this name server is considered to
           recursive (queries are sent with the RD bit set). The default value
           is to consder the name server to be authoritative.

       returns:

           0 if the association between the zone and the IP address could be
           made successfully; some other value if the association could not be
           created.

VALIDATOR DATA FIELDS
       The validator's error and errorStr fields are set with values
       corresponding to those from the standard herror() and hstrerror()
       functions.  These values are defined in netdb.h.  These values are:

         error      errorStr
           0        Resolver Error 0 (no error)
           1        Unknown host
           2        Host name lookup failure
           3        Unknown server error
           4        No address associated with name

       The values for the validator's valStatus field are defined in
       .../dnssec-tools/validator/include/validator/val_errors.h.  The values
       for the valStatusStr fields are the text representation of the status
       values' constants.  The different possible values for valStatus are
       listed below, and further details are provided in libval(3):

           VAL_BARE_RRSIG
           VAL_INDETERMINATE
           VAL_BOGUS
           VAL_DNS_ERROR
           VAL_IGNORE_VALIDATION
           VAL_NONEXISTENT_NAME
           VAL_NONEXISTENT_NAME_NOCHAIN
           VAL_NONEXISTENT_TYPE
           VAL_NONEXISTENT_TYPE_NOCHAIN
           VAL_NOTRUST
           VAL_OOB_ANSWER
           VAL_PINSECURE
           VAL_PINSECURE_UNTRUSTED
           VAL_SUCCESS
           VAL_TRUSTED_ANSWER
           VAL_UNTRUSTED_ANSWER
           VAL_UNTRUSTED_ZONE
           VAL_VALIDATED_ANSWER

       The istrusted() and isvalidated() functions can be used to test if a
       particular valStatus value corresponds to a trusted or a validated
       status condition. Status values that are neither trusted nor validated
       are un-trustworthy and must be treated as such by the application.

EXAMPLES
         use Net::DNS::SEC::Validator;
         use Net::DNS::Packet;
         use Net::hostent;
         use Net::addrinfo;
         use Socket qw(:all);

         # construct object
         my $validator = new Net::DNS::SEC::Validator(policy => ":");

         # change validation policy
         $validator->policy("validate_tools:");

         # fetch array of Net::addrinfo objects
         my (@r) = $validator->getaddrinfo("good-A.test.dnssec-tools.org");
         foreach $a (@r) {
            print $a->stringify, " is trusted\n"
               if $validator->istrusted($a->val_status));
         }

         # query an MX record
         my $r = $validator->res_query("dnssec-tools.org", "IN", "MX");
         my ($pkt, $err) = new Net::DNS::Packet(\$r);
         print ($validator->istrusted ?
               "result is trusted\n" :
               "result is NOT trusted\n");

         my $h = $validator->gethostbyname("good-A.test.dnssec-tools.org");
         if ( @{$h->addr_list}) {
         my $i;
            for $addr ( @{$h->addr_list} ) {
               printf "\taddr #%d is [%s]\n", $i++, inet_ntoa($addr);
            }
         }

         # get details of validation
         my $a = $validator->resolve_and_check("good-a.test.dnssec-tools.org", "IN", "A", 0);
         foreach my $h (@$a) {
          print "Status: " .  ${$h}{status} . "\n";
          print ($validator->istrusted(${$h}{status}) ?
                  "result is trusted\n" :
                  "result is NOT trusted\n");

          $acs = ${$h}{answer};
          foreach my $ac ($acs) {
               print "AC status: " . ${$ac}{status} . "\n";
               $acr = ${$ac}{rrset};
               $acd = ${$acr}{data};
               foreach $d (@$acd) {
                   print "Data RR status: " . ${$d}{rrstatus} . "\n";
                   ${$d}{rrdata}->print;
               }
               $acs = ${$acr}{sigs};
               foreach $d (@$acs) {
                   print "Sig RR status: " . ${$d}{rrstatus} . "\n";
                   ${$d}{rrdata}->print;
               }
          }
       }

SEE ALSO
       libval(3), dnsval.conf(3), resolv.conf(3), root.hints(3)

COPYRIGHT
       Copyright (c) 2006 G. S. Marzot. All rights reserved.  This program is
       free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

       Copyright (c) 2006-2013 SPARTA, Inc.  All Rights Reserved.  This
       program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

AUTHOR
        G. S. Marzot (marz@users.sourceforge.net)

perl v5.38.0                      2023-07-29                      Validator(3)