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 = DNS::LDNS::Zone->new(filename => '/path/to/myzone');
print DNS::LDNS::last_error;
my $rr = DNS::LDNS::RR->new('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 = DNS::LDNS::KeyList->new;
$kl->push(DNS::LDNS::Key->new(filename => 'key');
$kl->key(0)->set_pubkey_owner(
DNS::LDNS::RData->new(LDNS_RDF_TYPE_DNAME, 'myzone.org'));
my $signedz = $z->sign($kl);
print $signedz->to_string;
my $r = DNS::LDNS::Resolver->new(filename => '/my/resolv.conf');
my $p = $r->send(
DNS::LDNS::RData->new(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.
BUGS
There no known bugs, although parts of the code has not yet been very well tested. Bugreports will be greatly appreciated.
SEE ALSO
http://www.nlnetlabs.nl/projects/ldns
AUTHOR
Erik Pihl Ostlyngen, <erik.ostlyngen@norid.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.