1DNS::LDNS(3) User Contributed Perl Documentation DNS::LDNS(3)
2
6 DNS::LDNS - Perl extension for the ldns library
7
9 use DNS::LDNS ':all'
10
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 Brief examples of usage
18 use DNS::LDNS ':all';
19 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 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 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 Classes
42 A description of the classes included and how they map to the ldns
43 library structures:
44 DNS::LDNS Base class with static functions and constants
46 DNS::LDNS::Zone Represents a parsed zonefile (maps to the ldns_zone
48 struct)
49 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 DNS::LDNS::RR Represents a resource record (RR), (maps to the
55 ldns_rr struct)
56 DNS::LDNS::RData Represents an rdata field or a dname in an RR (maps
58 to the ldns_rdf struct)
59 DNS::LDNS::Resolver Represents a DNS resolver (maps to the
61 ldns_resolver struct)
62 DNS::LDNS::Packet Represents a DNS package (maps to the ldns_pkt
64 struct)
65 DNS::LDNS::Key Represents a DNSSec private key (maps to the
67 ldns_key struct)
68 DNS::LDNS::KeyList Represents a linked list of keys (maps to the
70 ldns_key_list struct)
71 DNS::LDNS::DNSSecZone
73 Represents a zone with dnssec data (maps to the
74 ldns_dnssec_zone struct)
75 DNS::LDNS::RBTree Represents a tree of DNSSecName nodes (maps to the
77 ldns_rbtree struct)
78 DNS::LDNS::RBNode Represents a node in the RBTree (maps to the
80 ldns_rbnode struct)
81 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 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 DNS::LDNS::DNSSecRRs
93 Represents a linked list of RRs (maps to the
94 ldns_dnssec_rrs struct)
95 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 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 DNS::LDNS::GC Garbage collector. Handles ownership dependencies
107 and freeing data used by the other classes. Used
108 internally only.
109 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 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 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 Examples
146 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 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 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 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 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 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 EXPORT
174 None by default.
175 Exportable constants
177 Status
178 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 Resolver flags and constants
259 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 Resolver query flags
275 LDNS_AA
277 LDNS_AD
278 LDNS_CD
279 LDNS_QR
280 LDNS_RA
281 LDNS_RD
282 LDNS_TC
283 Resolver rcodes
285 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 Packet types
299 LDNS_PACKET_ANSWER
301 LDNS_PACKET_NODATA
302 LDNS_PACKET_NXDOMAIN
303 LDNS_PACKET_QUESTION
304 LDNS_PACKET_REFERRAL
305 LDNS_PACKET_UNKNOWN
306 Packet opcodes
308 LDNS_PACKET_IQUERY
310 LDNS_PACKET_NOTIFY
311 LDNS_PACKET_QUERY
312 LDNS_PACKET_STATUS
313 LDNS_PACKET_UPDATE
314 Packet sections
316 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 DNSSec constants
325 LDNS_DEFAULT_EXP_TIME
327 LDNS_MAX_KEYLEN
328 LDNS_DNSSEC_KEYPROTO
329 DNSSec sign policies
331 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 Key flags
339 LDNS_KEY_REVOKE_KEY
341 LDNS_KEY_SEP_KEY
342 LDNS_KEY_ZONE_KEY
343 Key algorithms
345 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 Signing algorithms
360 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 Hashing algorithm
373 LDNS_SHA1
375 LDNS_SHA256
376 LDNS_HASH_GOST
377 Rdata constants
379 LDNS_MAX_RDFLEN
381 LDNS_NSEC3_VARS_OPTOUT_MASK
382 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 Rdata types
390 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 Algorithms used in CERT RRs.
424 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 RR compress flag
437 LDNS_RR_COMPRESS
439 LDNS_RR_NO_COMPRESS
440 RR classes
442 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 RR types
453 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 Various defaults and other constants
524 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
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
542 http://www.nlnetlabs.nl/projects/ldns
543
545 Erik Pihl Ostlyngen, <erik.ostlyngen@uninett.no>
546
548 Copyright (C) 2013 by UNINETT Norid AS
549 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.
553perl v5.32.0 2020-07-28 DNS::LDNS(3)