The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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.