table of contents
| DNS::LDNS(3) | User Contributed Perl Documentation | DNS::LDNS(3) |
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 if 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.
Most constructors will update the DNS::LDNS::last_status variable if they fail (return undef). Wrapper methods to ldns functions which would return 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 still in the beta stage of development. There no known bugs, although parts of the code has not yet been very well tested. Bugreports will be greatly appreciated.
SEE ALSO¶
AUTHOR¶
Erik Pihl Ostlyngen, <erik.ostlyngen@uninett.no>
COPYRIGHT AND LICENSE¶
Copyright (C) 2013 by UNINETT Norid AS
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.
| 2022-07-06 | perl v5.32.1 |