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.