NAME

DNS::LDNS - Perl extension for the ldns library

SYNOPSIS

use DNS::LDNS ':all'

DESCRIPTION

DNS::LDNS is a perl OO-wrapper for the ldns library. A complete list of object methods is found in the perldoc for each of the individual classes. You may also read the documentation of the ldns library (http://www.nlnetlabs.nl/projects/ldns).

Brief examples of usage

use DNS::LDNS ':all';

my $z = new DNS::LDNS::Zone(filename => '/path/to/myzone');
print DNS::LDNS::last_error;
my $rr = new DNS::LDNS::RR('mylabel 3600 IN A 168.10.10.10');
print $z->soa->to_string;
my $rrlist = $z->rrs->push($rr);
print $z->to_string;

my $kl = new DNS::LDNS::KeyList;
$kl->push(new DNS::LDNS::Key(filename => 'key');
$kl->key(0)->set_pubkey_owner(
    new DNS::LDNS::RData(LDNS_RDF_TYPE_DNAME, 'myzone.org'));
my $signedz = $z->sign($kl);
print $signedz->to_string;

my $r = new DNS::LDNS::Resolver(filename => '/my/resolv.conf');
my $p = $r->send(
  new DNS::LDNS::RData(LDNS_RDF_TYPE_DNAME, 'www.google.com'), 
  LDNS_RR_TYPE_A, LDNS_RR_CLASS_IN, LDNS_RD);
print $p->answer->to_string;
print $p->authority->to_string;

Classes

A description of the classes included and how they map to the ldns library structures:

DNS::LDNS: Base class with static functions and constants
DNS::LDNS::Zone: Represents a parsed zonefile (maps to the ldns_zone struct)
DNS::LDNS::RRList: Represents a list of RRs. This class is also used to represent an RRSet all the dnames and types are equal, (maps to the the ldns_rr_list struct)
DNS::LDNS::RR: Represents a resource record (RR), (maps to the ldns_rr struct)
DNS::LDNS::RData: Represents an rdata field or a dname in an RR (maps to the ldns_rdf struct)
DNS::LDNS::Resolver: Represents a DNS resolver (maps to the ldns_resolver struct)
DNS::LDNS::Packet: Represents a DNS package (maps to the ldns_pkt struct)
DNS::LDNS::Key: Represents a DNSSec private key (maps to the ldns_key struct)
DNS::LDNS::KeyList: Represents a linked list of keys (maps to the ldns_key_list struct)
DNS::LDNS::DNSSecZone: Represents a zone with dnssec data (maps to the ldns_dnssec_zone struct)
DNS::LDNS::RBTree: Represents a tree of DNSSecName nodes (maps to the ldns_rbtree struct)
DNS::LDNS::RBNode: Represents a node in the RBTree (maps to the ldns_rbnode struct)
DNS::LDNS::DNSSecName: Represents a dname in a DNSSecZone and holds a DNSSecRRSets list for this dname, possibly with signatures (maps to the ldns_dnssec_name struct)
DNS::LDNS::DNSSecRRSets: Represents a linked list of DNSSec RR sets, possibly with signatures (maps to the ldns_dnssec_rrsets struct)
DNS::LDNS::DNSSecRRs: Represents a linked list of RRs (maps to the ldns_dnssec_rrs struct)
DNS::LDNS::DNSSecDataChain: Represents a chain of RR, DNSKEY, and DS data used for building a dnssec trust tree (maps to the ldns_dnssec_data_chain struct)
DNS::LDNS::DNSSecTrustTree: Represents a tree of chained trust relationships from a signed RR to a set of trust anchors (maps to the ldns_dnssec_trust_tree struct).
DNS::LDNS::GC: Garbage collector. Handles ownership dependencies and freeing data used by the other classes. Used internally only.

One thing to note is that some of the classes have a seemingly overlapping functionality. The Zone and RRList are used to represent a generic zone. It may contain dnssec data but treats it like any other dns data and does not have any knowledge of its structure. The DNSSec* and RB* classes are building blocks for representing a signed zone in a more structured way.

Static functions

str = rr_type2str(type)
str = rr_class2str(class)
type = rr_type_by_name(str)
class = rr_class_by_name(str)
str = pkt_opcode2str(opcode)
str = pkt_rcode2str(rcode)
error = errorstr_by_id(status)
str = DNS::LDNS::last_error
status = DNS::LDNS::last_status
rr = dnssec_create_nsec(from, to, type)
rr = dnssec_create_nsec3(from, to, algorithm, flags, iterations, salt)
rr = create_nsec(current, next, rrs)
rr = create_nsec3(cur_owner, cur_zone, algorithm, flags, 
                  iterations, salt, empty_nonterminals)
algo = signing_algorithm_by_name(name)
bool = key_algorithm_supported(algorithm)
rr = read_anchor_file(filename)

Object references and cloning

Since some of the objects are found as sub objects within other objects, it is important to know how the wrapper classes handle object references, dependencies and cloning. The general rule is that accessor methods just return a reference to the object while methods inserting data inserts inserts a clone of the object. Most classes have a clone method which can be used if a cloned object is what you really want.

Examples

DNS::LDNS::Zone::rrs returns a reference to the DNS::LDNS::RRList within the zone, so if you make changes to the RRList you also changes the Zone object.

DNS::LDNS::RRList::push(rr) clones the rr, then pushes the cloned rr to the list. Changing the rr afterwards will not change the list.

An exception is the Key class which does not have a clone mechanism. In this case we allow a free Key to be added to only one KeyList. Adding it to multiple lists will provoke an error.

The wrapper keeps track of allocated data structures and references. Whenever data is no longer referred to by a perl object, it will be freed.

ERROR HANDLING

The purpose for writing this wrapper class has been to be able to process zone file data with good time performance. Data checking and error handling is a bit sparse. Calling a method with wrong argument types will some times kill the application with an intelligible error message, in other cases it may provoke a segmentation fault. Using out-of-range data values, e.g. in array indexes, may also cause unexpected results.

Most constructors and all methods returning a status will update the static DNS::LDNS::last_status variable. Most methods do not return a status and will not reset this variable even though they succeeds.

EXPORT

None by default.

Exportable constants

Status

LDNS_STATUS_ADDRESS_ERR
LDNS_STATUS_CERT_BAD_ALGORITHM
LDNS_STATUS_CRYPTO_ALGO_NOT_IMPL
LDNS_STATUS_CRYPTO_BOGUS
LDNS_STATUS_CRYPTO_EXPIRATION_BEFORE_INCEPTION
LDNS_STATUS_CRYPTO_NO_DNSKEY
LDNS_STATUS_CRYPTO_NO_DS
LDNS_STATUS_CRYPTO_NO_MATCHING_KEYTAG_DNSKEY
LDNS_STATUS_CRYPTO_NO_RRSIG
LDNS_STATUS_CRYPTO_NO_TRUSTED_DNSKEY
LDNS_STATUS_CRYPTO_NO_TRUSTED_DS
LDNS_STATUS_CRYPTO_SIG_EXPIRED
LDNS_STATUS_CRYPTO_SIG_NOT_INCEPTED
LDNS_STATUS_CRYPTO_TSIG_BOGUS
LDNS_STATUS_CRYPTO_TSIG_ERR
LDNS_STATUS_CRYPTO_TYPE_COVERED_ERR
LDNS_STATUS_CRYPTO_UNKNOWN_ALGO
LDNS_STATUS_CRYPTO_VALIDATED
LDNS_STATUS_DDD_OVERFLOW
LDNS_STATUS_DNSSEC_EXISTENCE_DENIED
LDNS_STATUS_DNSSEC_NSEC3_ORIGINAL_NOT_FOUND
LDNS_STATUS_DNSSEC_NSEC_RR_NOT_COVERED
LDNS_STATUS_DNSSEC_NSEC_WILDCARD_NOT_COVERED
LDNS_STATUS_DOMAINNAME_OVERFLOW
LDNS_STATUS_DOMAINNAME_UNDERFLOW
LDNS_STATUS_EMPTY_LABEL
LDNS_STATUS_ENGINE_KEY_NOT_LOADED
LDNS_STATUS_ERR
LDNS_STATUS_FILE_ERR
LDNS_STATUS_INTERNAL_ERR
LDNS_STATUS_INVALID_B32_EXT
LDNS_STATUS_INVALID_B64
LDNS_STATUS_INVALID_HEX
LDNS_STATUS_INVALID_INT
LDNS_STATUS_INVALID_IP4
LDNS_STATUS_INVALID_IP6
LDNS_STATUS_INVALID_POINTER
LDNS_STATUS_INVALID_STR
LDNS_STATUS_INVALID_TIME
LDNS_STATUS_LABEL_OVERFLOW
LDNS_STATUS_MEM_ERR
LDNS_STATUS_MISSING_RDATA_FIELDS_KEY
LDNS_STATUS_MISSING_RDATA_FIELDS_RRSIG
LDNS_STATUS_NETWORK_ERR
LDNS_STATUS_NOT_IMPL
LDNS_STATUS_NO_DATA
LDNS_STATUS_NSEC3_ERR
LDNS_STATUS_NULL
LDNS_STATUS_OK
LDNS_STATUS_PACKET_OVERFLOW
LDNS_STATUS_RES_NO_NS
LDNS_STATUS_RES_QUERY
LDNS_STATUS_SOCKET_ERROR
LDNS_STATUS_SSL_ERR
LDNS_STATUS_SYNTAX_ALG_ERR
LDNS_STATUS_SYNTAX_BAD_ESCAPE
LDNS_STATUS_SYNTAX_CLASS_ERR
LDNS_STATUS_SYNTAX_DNAME_ERR
LDNS_STATUS_SYNTAX_EMPTY
LDNS_STATUS_SYNTAX_ERR
LDNS_STATUS_SYNTAX_INCLUDE
LDNS_STATUS_SYNTAX_INCLUDE_ERR_NOTIMPL
LDNS_STATUS_SYNTAX_INTEGER_OVERFLOW
LDNS_STATUS_SYNTAX_ITERATIONS_OVERFLOW
LDNS_STATUS_SYNTAX_KEYWORD_ERR
LDNS_STATUS_SYNTAX_MISSING_VALUE_ERR
LDNS_STATUS_SYNTAX_ORIGIN
LDNS_STATUS_SYNTAX_RDATA_ERR
LDNS_STATUS_SYNTAX_TTL
LDNS_STATUS_SYNTAX_TTL_ERR
LDNS_STATUS_SYNTAX_TYPE_ERR
LDNS_STATUS_SYNTAX_VERSION_ERR
LDNS_STATUS_UNKNOWN_INET
LDNS_STATUS_WIRE_INCOMPLETE_ADDITIONAL
LDNS_STATUS_WIRE_INCOMPLETE_ANSWER
LDNS_STATUS_WIRE_INCOMPLETE_AUTHORITY
LDNS_STATUS_WIRE_INCOMPLETE_HEADER
LDNS_STATUS_WIRE_INCOMPLETE_QUESTION

Resolver flags and constants

LDNS_RESOLV_ANCHOR
LDNS_RESOLV_DEFDOMAIN
LDNS_RESOLV_INET
LDNS_RESOLV_INET6
LDNS_RESOLV_INETANY
LDNS_RESOLV_KEYWORD
LDNS_RESOLV_KEYWORDS
LDNS_RESOLV_NAMESERVER
LDNS_RESOLV_OPTIONS
LDNS_RESOLV_RTT_INF
LDNS_RESOLV_RTT_MIN
LDNS_RESOLV_SEARCH
LDNS_RESOLV_SORTLIST

Resolver query flags

LDNS_AA
LDNS_AD
LDNS_CD
LDNS_QR
LDNS_RA
LDNS_RD
LDNS_TC

Resolver rcodes

LDNS_RCODE_FORMERR
LDNS_RCODE_NOERROR
LDNS_RCODE_NOTAUTH
LDNS_RCODE_NOTIMPL
LDNS_RCODE_NOTZONE
LDNS_RCODE_NXDOMAIN
LDNS_RCODE_NXRRSET
LDNS_RCODE_REFUSED
LDNS_RCODE_SERVFAIL
LDNS_RCODE_YXDOMAIN
LDNS_RCODE_YXRRSET

Packet types

LDNS_PACKET_ANSWER
LDNS_PACKET_NODATA
LDNS_PACKET_NXDOMAIN
LDNS_PACKET_QUESTION
LDNS_PACKET_REFERRAL
LDNS_PACKET_UNKNOWN

Packet opcodes

LDNS_PACKET_IQUERY
LDNS_PACKET_NOTIFY
LDNS_PACKET_QUERY
LDNS_PACKET_STATUS
LDNS_PACKET_UPDATE

Packet sections

LDNS_SECTION_ADDITIONAL
LDNS_SECTION_ANSWER
LDNS_SECTION_ANY
LDNS_SECTION_ANY_NOQUESTION
LDNS_SECTION_AUTHORITY
LDNS_SECTION_QUESTION

DNSSec constants

LDNS_DEFAULT_EXP_TIME
LDNS_MAX_KEYLEN
LDNS_DNSSEC_KEYPROTO

DNSSec sign policies

LDNS_SIGNATURE_LEAVE_ADD_NEW
LDNS_SIGNATURE_LEAVE_NO_ADD
LDNS_SIGNATURE_REMOVE_ADD_NEW
LDNS_SIGNATURE_REMOVE_NO_ADD
LDNS_NSEC3_MAX_ITERATIONS

Key flags

LDNS_KEY_REVOKE_KEY
LDNS_KEY_SEP_KEY
LDNS_KEY_ZONE_KEY

Key algorithms

LDNS_DH
LDNS_DSA
LDNS_DSA_NSEC3
LDNS_ECC
LDNS_RSAMD5
LDNS_RSASHA1
LDNS_RSASHA1_NSEC3
LDNS_RSASHA256
LDNS_RSASHA512
LDNS_ECC_GOST
LDNS_PRIVATEDNS
LDNS_PRIVATEOID

Signing algorithms

LDNS_SIGN_DSA
LDNS_SIGN_DSA_NSEC3
LDNS_SIGN_ECC_GOST
LDNS_SIGN_HMACSHA1
LDNS_SIGN_HMACSHA256
LDNS_SIGN_RSAMD5
LDNS_SIGN_RSASHA1
LDNS_SIGN_RSASHA1_NSEC3
LDNS_SIGN_RSASHA256
LDNS_SIGN_RSASHA512

Hashing algorithm

LDNS_SHA1
LDNS_SHA256
LDNS_HASH_GOST

Rdata constants

LDNS_MAX_RDFLEN
LDNS_NSEC3_VARS_OPTOUT_MASK

LDNS_RDF_SIZE_16BYTES
LDNS_RDF_SIZE_6BYTES
LDNS_RDF_SIZE_BYTE
LDNS_RDF_SIZE_DOUBLEWORD
LDNS_RDF_SIZE_WORD

Rdata types

LDNS_RDF_TYPE_A
LDNS_RDF_TYPE_AAAA
LDNS_RDF_TYPE_ALG
LDNS_RDF_TYPE_APL
LDNS_RDF_TYPE_ATMA
LDNS_RDF_TYPE_B32_EXT
LDNS_RDF_TYPE_B64
LDNS_RDF_TYPE_CERT_ALG
LDNS_RDF_TYPE_CLASS
LDNS_RDF_TYPE_DNAME
LDNS_RDF_TYPE_HEX
LDNS_RDF_TYPE_INT16
LDNS_RDF_TYPE_INT16_DATA
LDNS_RDF_TYPE_INT32
LDNS_RDF_TYPE_INT8
LDNS_RDF_TYPE_IPSECKEY
LDNS_RDF_TYPE_LOC
LDNS_RDF_TYPE_NONE
LDNS_RDF_TYPE_NSAP
LDNS_RDF_TYPE_NSEC
LDNS_RDF_TYPE_NSEC3_NEXT_OWNER
LDNS_RDF_TYPE_NSEC3_SALT
LDNS_RDF_TYPE_PERIOD
LDNS_RDF_TYPE_SERVICE
LDNS_RDF_TYPE_STR
LDNS_RDF_TYPE_TIME
LDNS_RDF_TYPE_HIP
LDNS_RDF_TYPE_TSIGTIME
LDNS_RDF_TYPE_TYPE
LDNS_RDF_TYPE_UNKNOWN
LDNS_RDF_TYPE_WKS

Algorithms used in CERT RRs.

LDNS_CERT_ACPKIX
LDNS_CERT_IACPKIX
LDNS_CERT_IPGP
LDNS_CERT_IPKIX
LDNS_CERT_ISPKI
LDNS_CERT_OID
LDNS_CERT_PGP
LDNS_CERT_PKIX
LDNS_CERT_SPKI
LDNS_CERT_URI

RR compress flag

LDNS_RR_COMPRESS
LDNS_RR_NO_COMPRESS

RR classes

LDNS_RR_CLASS_ANY
LDNS_RR_CLASS_CH
LDNS_RR_CLASS_COUNT
LDNS_RR_CLASS_FIRST
LDNS_RR_CLASS_HS
LDNS_RR_CLASS_IN
LDNS_RR_CLASS_LAST
LDNS_RR_CLASS_NONE

RR types

LDNS_RR_TYPE_A
LDNS_RR_TYPE_A6
LDNS_RR_TYPE_AAAA
LDNS_RR_TYPE_AFSDB
LDNS_RR_TYPE_ANY
LDNS_RR_TYPE_APL
LDNS_RR_TYPE_ATMA
LDNS_RR_TYPE_AXFR
LDNS_RR_TYPE_CERT
LDNS_RR_TYPE_CNAME
LDNS_RR_TYPE_COUNT
LDNS_RR_TYPE_DHCID
LDNS_RR_TYPE_DLV
LDNS_RR_TYPE_DNAME
LDNS_RR_TYPE_DNSKEY
LDNS_RR_TYPE_DS
LDNS_RR_TYPE_EID
LDNS_RR_TYPE_FIRST
LDNS_RR_TYPE_GID
LDNS_RR_TYPE_GPOS
LDNS_RR_TYPE_HINFO
LDNS_RR_TYPE_IPSECKEY
LDNS_RR_TYPE_ISDN
LDNS_RR_TYPE_IXFR
LDNS_RR_TYPE_KEY
LDNS_RR_TYPE_KX
LDNS_RR_TYPE_LAST
LDNS_RR_TYPE_LOC
LDNS_RR_TYPE_MAILA
LDNS_RR_TYPE_MAILB
LDNS_RR_TYPE_MB
LDNS_RR_TYPE_MD
LDNS_RR_TYPE_MF
LDNS_RR_TYPE_MG
LDNS_RR_TYPE_MINFO
LDNS_RR_TYPE_MR
LDNS_RR_TYPE_MX
LDNS_RR_TYPE_NAPTR
LDNS_RR_TYPE_NIMLOC
LDNS_RR_TYPE_NS
LDNS_RR_TYPE_NSAP
LDNS_RR_TYPE_NSAP_PTR
LDNS_RR_TYPE_NSEC
LDNS_RR_TYPE_NSEC3
LDNS_RR_TYPE_NSEC3PARAM
LDNS_RR_TYPE_NSEC3PARAMS
LDNS_RR_TYPE_NULL
LDNS_RR_TYPE_NXT
LDNS_RR_TYPE_OPT
LDNS_RR_TYPE_PTR
LDNS_RR_TYPE_PX
LDNS_RR_TYPE_RP
LDNS_RR_TYPE_RRSIG
LDNS_RR_TYPE_RT
LDNS_RR_TYPE_SIG
LDNS_RR_TYPE_SINK
LDNS_RR_TYPE_SOA
LDNS_RR_TYPE_SPF
LDNS_RR_TYPE_SRV
LDNS_RR_TYPE_SSHFP
LDNS_RR_TYPE_TALINK
LDNS_RR_TYPE_TSIG
LDNS_RR_TYPE_TXT
LDNS_RR_TYPE_UID
LDNS_RR_TYPE_UINFO
LDNS_RR_TYPE_UNSPEC
LDNS_RR_TYPE_WKS
LDNS_RR_TYPE_X25

Various defaults and other constants

LDNS_DEFAULT_TTL
LDNS_PORT
LDNS_IP4ADDRLEN
LDNS_IP6ADDRLEN
LDNS_MAX_DOMAINLEN
LDNS_MAX_LABELLEN
LDNS_MAX_PACKETLEN
LDNS_MAX_POINTERS
LDNS_RR_OVERHEAD
LDNS_RDATA_FIELD_DESCRIPTORS_COMMON

BUGS

This package is currently in a very early stage of development. There are probably some bugs. You may also expect that method names and behaviour could still change without much considerations to backward compatibility.

AUTHOR

Erik Pihl Ostlyngen, <erik.ostlyngen@uninett.no>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.

To install DNS::LDNS, copy and paste the appropriate command in to your terminal.

cpanm

cpanm DNS::LDNS

CPAN shell

perl -MCPAN -e shell
install DNS::LDNS

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)