1DNS::LDNS(3)          User Contributed Perl Documentation         DNS::LDNS(3)
2
3
4

NAME

6       DNS::LDNS - Perl extension for the ldns library
7

SYNOPSIS

9         use DNS::LDNS ':all'
10

DESCRIPTION

12       DNS::LDNS is a perl OO-wrapper for the ldns library. A complete list of
13       object methods is found in the perldoc for each of the individual
14       classes. You may also read the documentation of the ldns library
15       (http://www.nlnetlabs.nl/projects/ldns).
16
17   Brief examples of usage
18         use DNS::LDNS ':all';
19
20         my $z = new DNS::LDNS::Zone(filename => '/path/to/myzone');
21         print DNS::LDNS::last_error;
22         my $rr = new DNS::LDNS::RR('mylabel 3600 IN A 168.10.10.10');
23         print $z->soa->to_string;
24         my $rrlist = $z->rrs->push($rr);
25         print $z->to_string;
26
27         my $kl = new DNS::LDNS::KeyList;
28         $kl->push(new DNS::LDNS::Key(filename => 'key');
29         $kl->key(0)->set_pubkey_owner(
30             new DNS::LDNS::RData(LDNS_RDF_TYPE_DNAME, 'myzone.org'));
31         my $signedz = $z->sign($kl);
32         print $signedz->to_string;
33
34         my $r = new DNS::LDNS::Resolver(filename => '/my/resolv.conf');
35         my $p = $r->send(
36           new DNS::LDNS::RData(LDNS_RDF_TYPE_DNAME, 'www.google.com'),
37           LDNS_RR_TYPE_A, LDNS_RR_CLASS_IN, LDNS_RD);
38         print $p->answer->to_string;
39         print $p->authority->to_string;
40
41   Classes
42       A description of the classes included and how they map to the ldns
43       library structures:
44
45       DNS::LDNS           Base class with static functions and constants
46
47       DNS::LDNS::Zone     Represents a parsed zonefile (maps to the ldns_zone
48                           struct)
49
50       DNS::LDNS::RRList   Represents a list of RRs. This class is also used
51                           to represent an RRSet if all the dnames and types
52                           are equal, (maps to the the ldns_rr_list struct)
53
54       DNS::LDNS::RR       Represents a resource record (RR), (maps to the
55                           ldns_rr struct)
56
57       DNS::LDNS::RData    Represents an rdata field or a dname in an RR (maps
58                           to the ldns_rdf struct)
59
60       DNS::LDNS::Resolver Represents a DNS resolver (maps to the
61                           ldns_resolver struct)
62
63       DNS::LDNS::Packet   Represents a DNS package (maps to the ldns_pkt
64                           struct)
65
66       DNS::LDNS::Key      Represents a DNSSec private key (maps to the
67                           ldns_key struct)
68
69       DNS::LDNS::KeyList  Represents a linked list of keys (maps to the
70                           ldns_key_list struct)
71
72       DNS::LDNS::DNSSecZone
73                           Represents a zone with dnssec data (maps to the
74                           ldns_dnssec_zone struct)
75
76       DNS::LDNS::RBTree   Represents a tree of DNSSecName nodes (maps to the
77                           ldns_rbtree struct)
78
79       DNS::LDNS::RBNode   Represents a node in the RBTree (maps to the
80                           ldns_rbnode struct)
81
82       DNS::LDNS::DNSSecName
83                           Represents a dname in a DNSSecZone and holds a
84                           DNSSecRRSets list for this  dname, possibly with
85                           signatures (maps to the ldns_dnssec_name struct)
86
87       DNS::LDNS::DNSSecRRSets
88                           Represents a linked list of DNSSec RR sets,
89                           possibly with signatures (maps  to the
90                           ldns_dnssec_rrsets struct)
91
92       DNS::LDNS::DNSSecRRs
93                           Represents a linked list of RRs (maps to the
94                           ldns_dnssec_rrs struct)
95
96       DNS::LDNS::DNSSecDataChain
97                           Represents a chain of RR, DNSKEY, and DS data used
98                           for building a dnssec  trust tree (maps to the
99                           ldns_dnssec_data_chain struct)
100
101       DNS::LDNS::DNSSecTrustTree
102                           Represents a tree of chained trust relationships
103                           from a signed RR to a set  of trust anchors (maps
104                           to the ldns_dnssec_trust_tree struct).
105
106       DNS::LDNS::GC       Garbage collector. Handles ownership dependencies
107                           and freeing data used by  the other classes. Used
108                           internally only.
109
110       One thing to note is that some of the classes have a seemingly
111       overlapping  functionality. The Zone and RRList are used to represent a
112       generic zone. It  may contain dnssec data but treats it like any other
113       dns data and does not  have any knowledge of its structure. The DNSSec*
114       and RB* classes are  building blocks for representing a signed zone in
115       a more structured way.
116
117   Static functions
118         str = rr_type2str(type)
119         str = rr_class2str(class)
120         type = rr_type_by_name(str)
121         class = rr_class_by_name(str)
122         str = pkt_opcode2str(opcode)
123         str = pkt_rcode2str(rcode)
124         error = errorstr_by_id(status)
125         str = DNS::LDNS::last_error
126         status = DNS::LDNS::last_status
127         rr = dnssec_create_nsec(from, to, type)
128         rr = dnssec_create_nsec3(from, to, algorithm, flags, iterations, salt)
129         rr = create_nsec(current, next, rrs)
130         rr = create_nsec3(cur_owner, cur_zone, algorithm, flags,
131                           iterations, salt, empty_nonterminals)
132         algo = signing_algorithm_by_name(name)
133         bool = key_algorithm_supported(algorithm)
134         rr = read_anchor_file(filename)
135
136   Object references and cloning
137       Since some of the objects are found as sub objects within other
138       objects, it  is important to know how the wrapper classes handle object
139       references,  dependencies and cloning. The general rule is that
140       accessor methods just  return a reference to the object while methods
141       inserting data inserts inserts  a clone of the object. Most classes
142       have a clone method which can be used if  a cloned object is what you
143       really want.
144
145       Examples
146
147       DNS::LDNS::Zone::rrs returns a reference to the DNS::LDNS::RRList
148       within  the zone, so if you make changes to the RRList you also changes
149       the Zone  object.
150
151       DNS::LDNS::RRList::push(rr) clones the rr, then pushes the cloned rr to
152       the  list. Changing the rr afterwards will not change the list.
153
154       An exception is the Key class which does not have a clone mechanism. In
155       this  case we allow a free Key to be added to only one KeyList. Adding
156       it to  multiple lists will provoke an error.
157
158       The wrapper keeps track of allocated data structures and references.
159       Whenever data is no longer referred to by a perl object, it will be
160       freed.
161
162   ERROR HANDLING
163       The purpose for writing this wrapper class has been to be able to
164       process zone file data with good time performance. Data checking and
165       error handling is a bit sparse.
166
167       Most constructors will update the DNS::LDNS::last_status variable if
168       they fail (return undef). Wrapper methods to ldns functions which would
169       return a status will update the static DNS::LDNS::last_status variable.
170       Most methods do not return a status and will not reset this variable
171       even though they succeeds.
172
173   EXPORT
174       None by default.
175
176   Exportable constants
177       Status
178
179         LDNS_STATUS_ADDRESS_ERR
180         LDNS_STATUS_CERT_BAD_ALGORITHM
181         LDNS_STATUS_CRYPTO_ALGO_NOT_IMPL
182         LDNS_STATUS_CRYPTO_BOGUS
183         LDNS_STATUS_CRYPTO_EXPIRATION_BEFORE_INCEPTION
184         LDNS_STATUS_CRYPTO_NO_DNSKEY
185         LDNS_STATUS_CRYPTO_NO_DS
186         LDNS_STATUS_CRYPTO_NO_MATCHING_KEYTAG_DNSKEY
187         LDNS_STATUS_CRYPTO_NO_RRSIG
188         LDNS_STATUS_CRYPTO_NO_TRUSTED_DNSKEY
189         LDNS_STATUS_CRYPTO_NO_TRUSTED_DS
190         LDNS_STATUS_CRYPTO_SIG_EXPIRED
191         LDNS_STATUS_CRYPTO_SIG_NOT_INCEPTED
192         LDNS_STATUS_CRYPTO_TSIG_BOGUS
193         LDNS_STATUS_CRYPTO_TSIG_ERR
194         LDNS_STATUS_CRYPTO_TYPE_COVERED_ERR
195         LDNS_STATUS_CRYPTO_UNKNOWN_ALGO
196         LDNS_STATUS_CRYPTO_VALIDATED
197         LDNS_STATUS_DDD_OVERFLOW
198         LDNS_STATUS_DNSSEC_EXISTENCE_DENIED
199         LDNS_STATUS_DNSSEC_NSEC3_ORIGINAL_NOT_FOUND
200         LDNS_STATUS_DNSSEC_NSEC_RR_NOT_COVERED
201         LDNS_STATUS_DNSSEC_NSEC_WILDCARD_NOT_COVERED
202         LDNS_STATUS_DOMAINNAME_OVERFLOW
203         LDNS_STATUS_DOMAINNAME_UNDERFLOW
204         LDNS_STATUS_EMPTY_LABEL
205         LDNS_STATUS_ENGINE_KEY_NOT_LOADED
206         LDNS_STATUS_ERR
207         LDNS_STATUS_FILE_ERR
208         LDNS_STATUS_INTERNAL_ERR
209         LDNS_STATUS_INVALID_B32_EXT
210         LDNS_STATUS_INVALID_B64
211         LDNS_STATUS_INVALID_HEX
212         LDNS_STATUS_INVALID_INT
213         LDNS_STATUS_INVALID_IP4
214         LDNS_STATUS_INVALID_IP6
215         LDNS_STATUS_INVALID_POINTER
216         LDNS_STATUS_INVALID_STR
217         LDNS_STATUS_INVALID_TIME
218         LDNS_STATUS_LABEL_OVERFLOW
219         LDNS_STATUS_MEM_ERR
220         LDNS_STATUS_MISSING_RDATA_FIELDS_KEY
221         LDNS_STATUS_MISSING_RDATA_FIELDS_RRSIG
222         LDNS_STATUS_NETWORK_ERR
223         LDNS_STATUS_NOT_IMPL
224         LDNS_STATUS_NO_DATA
225         LDNS_STATUS_NSEC3_ERR
226         LDNS_STATUS_NULL
227         LDNS_STATUS_OK
228         LDNS_STATUS_PACKET_OVERFLOW
229         LDNS_STATUS_RES_NO_NS
230         LDNS_STATUS_RES_QUERY
231         LDNS_STATUS_SOCKET_ERROR
232         LDNS_STATUS_SSL_ERR
233         LDNS_STATUS_SYNTAX_ALG_ERR
234         LDNS_STATUS_SYNTAX_BAD_ESCAPE
235         LDNS_STATUS_SYNTAX_CLASS_ERR
236         LDNS_STATUS_SYNTAX_DNAME_ERR
237         LDNS_STATUS_SYNTAX_EMPTY
238         LDNS_STATUS_SYNTAX_ERR
239         LDNS_STATUS_SYNTAX_INCLUDE
240         LDNS_STATUS_SYNTAX_INCLUDE_ERR_NOTIMPL
241         LDNS_STATUS_SYNTAX_INTEGER_OVERFLOW
242         LDNS_STATUS_SYNTAX_ITERATIONS_OVERFLOW
243         LDNS_STATUS_SYNTAX_KEYWORD_ERR
244         LDNS_STATUS_SYNTAX_MISSING_VALUE_ERR
245         LDNS_STATUS_SYNTAX_ORIGIN
246         LDNS_STATUS_SYNTAX_RDATA_ERR
247         LDNS_STATUS_SYNTAX_TTL
248         LDNS_STATUS_SYNTAX_TTL_ERR
249         LDNS_STATUS_SYNTAX_TYPE_ERR
250         LDNS_STATUS_SYNTAX_VERSION_ERR
251         LDNS_STATUS_UNKNOWN_INET
252         LDNS_STATUS_WIRE_INCOMPLETE_ADDITIONAL
253         LDNS_STATUS_WIRE_INCOMPLETE_ANSWER
254         LDNS_STATUS_WIRE_INCOMPLETE_AUTHORITY
255         LDNS_STATUS_WIRE_INCOMPLETE_HEADER
256         LDNS_STATUS_WIRE_INCOMPLETE_QUESTION
257
258       Resolver flags and constants
259
260         LDNS_RESOLV_ANCHOR
261         LDNS_RESOLV_DEFDOMAIN
262         LDNS_RESOLV_INET
263         LDNS_RESOLV_INET6
264         LDNS_RESOLV_INETANY
265         LDNS_RESOLV_KEYWORD
266         LDNS_RESOLV_KEYWORDS
267         LDNS_RESOLV_NAMESERVER
268         LDNS_RESOLV_OPTIONS
269         LDNS_RESOLV_RTT_INF
270         LDNS_RESOLV_RTT_MIN
271         LDNS_RESOLV_SEARCH
272         LDNS_RESOLV_SORTLIST
273
274       Resolver query flags
275
276         LDNS_AA
277         LDNS_AD
278         LDNS_CD
279         LDNS_QR
280         LDNS_RA
281         LDNS_RD
282         LDNS_TC
283
284       Resolver rcodes
285
286         LDNS_RCODE_FORMERR
287         LDNS_RCODE_NOERROR
288         LDNS_RCODE_NOTAUTH
289         LDNS_RCODE_NOTIMPL
290         LDNS_RCODE_NOTZONE
291         LDNS_RCODE_NXDOMAIN
292         LDNS_RCODE_NXRRSET
293         LDNS_RCODE_REFUSED
294         LDNS_RCODE_SERVFAIL
295         LDNS_RCODE_YXDOMAIN
296         LDNS_RCODE_YXRRSET
297
298       Packet types
299
300         LDNS_PACKET_ANSWER
301         LDNS_PACKET_NODATA
302         LDNS_PACKET_NXDOMAIN
303         LDNS_PACKET_QUESTION
304         LDNS_PACKET_REFERRAL
305         LDNS_PACKET_UNKNOWN
306
307       Packet opcodes
308
309         LDNS_PACKET_IQUERY
310         LDNS_PACKET_NOTIFY
311         LDNS_PACKET_QUERY
312         LDNS_PACKET_STATUS
313         LDNS_PACKET_UPDATE
314
315       Packet sections
316
317         LDNS_SECTION_ADDITIONAL
318         LDNS_SECTION_ANSWER
319         LDNS_SECTION_ANY
320         LDNS_SECTION_ANY_NOQUESTION
321         LDNS_SECTION_AUTHORITY
322         LDNS_SECTION_QUESTION
323
324       DNSSec constants
325
326         LDNS_DEFAULT_EXP_TIME
327         LDNS_MAX_KEYLEN
328         LDNS_DNSSEC_KEYPROTO
329
330       DNSSec sign policies
331
332         LDNS_SIGNATURE_LEAVE_ADD_NEW
333         LDNS_SIGNATURE_LEAVE_NO_ADD
334         LDNS_SIGNATURE_REMOVE_ADD_NEW
335         LDNS_SIGNATURE_REMOVE_NO_ADD
336         LDNS_NSEC3_MAX_ITERATIONS
337
338       Key flags
339
340         LDNS_KEY_REVOKE_KEY
341         LDNS_KEY_SEP_KEY
342         LDNS_KEY_ZONE_KEY
343
344       Key algorithms
345
346         LDNS_DH
347         LDNS_DSA
348         LDNS_DSA_NSEC3
349         LDNS_ECC
350         LDNS_RSAMD5
351         LDNS_RSASHA1
352         LDNS_RSASHA1_NSEC3
353         LDNS_RSASHA256
354         LDNS_RSASHA512
355         LDNS_ECC_GOST
356         LDNS_PRIVATEDNS
357         LDNS_PRIVATEOID
358
359       Signing algorithms
360
361         LDNS_SIGN_DSA
362         LDNS_SIGN_DSA_NSEC3
363         LDNS_SIGN_ECC_GOST
364         LDNS_SIGN_HMACSHA1
365         LDNS_SIGN_HMACSHA256
366         LDNS_SIGN_RSAMD5
367         LDNS_SIGN_RSASHA1
368         LDNS_SIGN_RSASHA1_NSEC3
369         LDNS_SIGN_RSASHA256
370         LDNS_SIGN_RSASHA512
371
372       Hashing algorithm
373
374         LDNS_SHA1
375         LDNS_SHA256
376         LDNS_HASH_GOST
377
378       Rdata constants
379
380         LDNS_MAX_RDFLEN
381         LDNS_NSEC3_VARS_OPTOUT_MASK
382
383         LDNS_RDF_SIZE_16BYTES
384         LDNS_RDF_SIZE_6BYTES
385         LDNS_RDF_SIZE_BYTE
386         LDNS_RDF_SIZE_DOUBLEWORD
387         LDNS_RDF_SIZE_WORD
388
389       Rdata types
390
391         LDNS_RDF_TYPE_A
392         LDNS_RDF_TYPE_AAAA
393         LDNS_RDF_TYPE_ALG
394         LDNS_RDF_TYPE_APL
395         LDNS_RDF_TYPE_ATMA
396         LDNS_RDF_TYPE_B32_EXT
397         LDNS_RDF_TYPE_B64
398         LDNS_RDF_TYPE_CERT_ALG
399         LDNS_RDF_TYPE_CLASS
400         LDNS_RDF_TYPE_DNAME
401         LDNS_RDF_TYPE_HEX
402         LDNS_RDF_TYPE_INT16
403         LDNS_RDF_TYPE_INT16_DATA
404         LDNS_RDF_TYPE_INT32
405         LDNS_RDF_TYPE_INT8
406         LDNS_RDF_TYPE_IPSECKEY
407         LDNS_RDF_TYPE_LOC
408         LDNS_RDF_TYPE_NONE
409         LDNS_RDF_TYPE_NSAP
410         LDNS_RDF_TYPE_NSEC
411         LDNS_RDF_TYPE_NSEC3_NEXT_OWNER
412         LDNS_RDF_TYPE_NSEC3_SALT
413         LDNS_RDF_TYPE_PERIOD
414         LDNS_RDF_TYPE_SERVICE
415         LDNS_RDF_TYPE_STR
416         LDNS_RDF_TYPE_TIME
417         LDNS_RDF_TYPE_HIP
418         LDNS_RDF_TYPE_TSIGTIME
419         LDNS_RDF_TYPE_TYPE
420         LDNS_RDF_TYPE_UNKNOWN
421         LDNS_RDF_TYPE_WKS
422
423       Algorithms used in CERT RRs.
424
425         LDNS_CERT_ACPKIX
426         LDNS_CERT_IACPKIX
427         LDNS_CERT_IPGP
428         LDNS_CERT_IPKIX
429         LDNS_CERT_ISPKI
430         LDNS_CERT_OID
431         LDNS_CERT_PGP
432         LDNS_CERT_PKIX
433         LDNS_CERT_SPKI
434         LDNS_CERT_URI
435
436       RR compress flag
437
438         LDNS_RR_COMPRESS
439         LDNS_RR_NO_COMPRESS
440
441       RR classes
442
443         LDNS_RR_CLASS_ANY
444         LDNS_RR_CLASS_CH
445         LDNS_RR_CLASS_COUNT
446         LDNS_RR_CLASS_FIRST
447         LDNS_RR_CLASS_HS
448         LDNS_RR_CLASS_IN
449         LDNS_RR_CLASS_LAST
450         LDNS_RR_CLASS_NONE
451
452       RR types
453
454         LDNS_RR_TYPE_A
455         LDNS_RR_TYPE_A6
456         LDNS_RR_TYPE_AAAA
457         LDNS_RR_TYPE_AFSDB
458         LDNS_RR_TYPE_ANY
459         LDNS_RR_TYPE_APL
460         LDNS_RR_TYPE_ATMA
461         LDNS_RR_TYPE_AXFR
462         LDNS_RR_TYPE_CERT
463         LDNS_RR_TYPE_CNAME
464         LDNS_RR_TYPE_COUNT
465         LDNS_RR_TYPE_DHCID
466         LDNS_RR_TYPE_DLV
467         LDNS_RR_TYPE_DNAME
468         LDNS_RR_TYPE_DNSKEY
469         LDNS_RR_TYPE_DS
470         LDNS_RR_TYPE_EID
471         LDNS_RR_TYPE_FIRST
472         LDNS_RR_TYPE_GID
473         LDNS_RR_TYPE_GPOS
474         LDNS_RR_TYPE_HINFO
475         LDNS_RR_TYPE_IPSECKEY
476         LDNS_RR_TYPE_ISDN
477         LDNS_RR_TYPE_IXFR
478         LDNS_RR_TYPE_KEY
479         LDNS_RR_TYPE_KX
480         LDNS_RR_TYPE_LAST
481         LDNS_RR_TYPE_LOC
482         LDNS_RR_TYPE_MAILA
483         LDNS_RR_TYPE_MAILB
484         LDNS_RR_TYPE_MB
485         LDNS_RR_TYPE_MD
486         LDNS_RR_TYPE_MF
487         LDNS_RR_TYPE_MG
488         LDNS_RR_TYPE_MINFO
489         LDNS_RR_TYPE_MR
490         LDNS_RR_TYPE_MX
491         LDNS_RR_TYPE_NAPTR
492         LDNS_RR_TYPE_NIMLOC
493         LDNS_RR_TYPE_NS
494         LDNS_RR_TYPE_NSAP
495         LDNS_RR_TYPE_NSAP_PTR
496         LDNS_RR_TYPE_NSEC
497         LDNS_RR_TYPE_NSEC3
498         LDNS_RR_TYPE_NSEC3PARAM
499         LDNS_RR_TYPE_NSEC3PARAMS
500         LDNS_RR_TYPE_NULL
501         LDNS_RR_TYPE_NXT
502         LDNS_RR_TYPE_OPT
503         LDNS_RR_TYPE_PTR
504         LDNS_RR_TYPE_PX
505         LDNS_RR_TYPE_RP
506         LDNS_RR_TYPE_RRSIG
507         LDNS_RR_TYPE_RT
508         LDNS_RR_TYPE_SIG
509         LDNS_RR_TYPE_SINK
510         LDNS_RR_TYPE_SOA
511         LDNS_RR_TYPE_SPF
512         LDNS_RR_TYPE_SRV
513         LDNS_RR_TYPE_SSHFP
514         LDNS_RR_TYPE_TALINK
515         LDNS_RR_TYPE_TSIG
516         LDNS_RR_TYPE_TXT
517         LDNS_RR_TYPE_UID
518         LDNS_RR_TYPE_UINFO
519         LDNS_RR_TYPE_UNSPEC
520         LDNS_RR_TYPE_WKS
521         LDNS_RR_TYPE_X25
522
523       Various defaults and other constants
524
525         LDNS_DEFAULT_TTL
526         LDNS_PORT
527         LDNS_IP4ADDRLEN
528         LDNS_IP6ADDRLEN
529         LDNS_MAX_DOMAINLEN
530         LDNS_MAX_LABELLEN
531         LDNS_MAX_PACKETLEN
532         LDNS_MAX_POINTERS
533         LDNS_RR_OVERHEAD
534         LDNS_RDATA_FIELD_DESCRIPTORS_COMMON
535

BUGS

537       This package is still in the beta stage of development. There no known
538       bugs, although parts of the code has not yet been very well tested.
539       Bugreports will be greatly appreciated.
540

SEE ALSO

542       http://www.nlnetlabs.nl/projects/ldns
543

AUTHOR

545       Erik Pihl Ostlyngen, <erik.ostlyngen@uninett.no>
546
548       Copyright (C) 2013 by UNINETT Norid AS
549
550       This library is free software; you can redistribute it and/or modify it
551       under the same terms as Perl itself, either Perl version 5.14.2 or, at
552       your option, any later version of Perl 5 you may have available.
553
554
555
556perl v5.32.0                      2020-07-28                      DNS::LDNS(3)
Impressum