1libgetdns(3) getdns libgetdns(3)
3
7 libgetdns -- an implementation of a modern asynchronous DNS API by and
8 for application developers
9
12 DNS Resolver library (libgetdns, -lgetdns)
13
16 libgetdns
17 This man page describes the getdns library, the general concepts behind
19 the API and some of the common elements of the public interface to the
20 library. Each of the public entry points and more complex data types
21 are captured in separate man pages.
22
25 getdns is modern asynchronous DNS API intended to be useful to applica‐
26 tion developers and operating system distributors as a way of making
27 all types of DNS information easily available in many types of pro‐
28 grams. The major features of this new API are:
29 Full support for event-driven programming
31 Supports DNSSEC in multiple ways
32 Mirroring of the resolution in getaddrinfo()
33 Easily supports all RRtypes, even those yet to be defined
34 Each of the entry points is offered with both asynchronous and synchro‐
37 nous signatures. The asynchronous functions rely on event handling and
38 callback via libevent. Functions are thread safe.
39 A context structure maintains DNS query and response data and is used
42 to maintain state during calls to the public entry points.
43 The project page for this implementation is at
46 http://getdnsapi.net
48 The specification is maintained at
51 http://getdnsapi.net/spec
53 The git repository for this implementation is at
56 http://github.com/getdnsapi/getdns
58
61 The API uses a few data structures to pass data into and return data
62 from the public entry points.
63 list an ordered list, the members of the list can be any of the four
66 data types.
67 dict a name-value pair. The name is a string literal, and the value
69 can be any of the four data types. The order of the name-value
70 pairs in a dict is not important.
71 int an integer compatible with uint32_t.
73 bindata
75 a struct used to hold binary data defined as { size_t size;
76 uint8_t *binary_stuff; }.
77
80 The getdns specification emphasizes the asynchronous nature of the API
81 and allows implementations to define their own approach. This page doc‐
82 uments this implementation's decisions and facilities provided to the
83 developer.
84 This implementation provides asynchronous support via the following
87 mechanisms:
88 File Descriptor Polling
90 Event Loop Integrations:
91 libevent
92 libuv
93 libev
94 Custom Event Loop Integrations
95 All functions and types discussed in this page are declared in
98 getdns_extra.h
99 Build-in Event loop
102 The library has an built in event loop that can be used if none of the
103 extensions for external event loops are used. The library will execute
104 requests and dispatch callbacks with a call to getdns_context_run().
105 If an event loop extension is used, this will run the extension's
106 eventloop.
107 void getdns_context_run(getdns_context *context)
110 Run the context's event loop until nothing more to do.
112 uint32_t getdns_context_get_num_pending_requests(getdns_context* con‐
115 text, struct timeval* next_timeout)
116 Get the number of outstanding asynchronous requests for a given con‐
118 text as well as the the amount of time until the next timeout. The
119 next_timeout struct can be NULL. If supplied and the number of out‐
120 standing requests is > 0, then the timeout represents the relative
121 time until the next timeout.
122 getdns_return_t getdns_context_process_async(getdns_context* context)
125 Inform the context to process its outstanding requests. Users
127 should call this when either a timeout has occurred or the file de‐
128 scriptor signals that it is ready. User callbacks are fired during
129 this call.
130 Included Event Loop Integrations
133 A number of applications achieve asynchronous behavior by leveraging
134 event loop abstraction libraries. If the build system discovers a sup‐
135 ported event loop, the event loop extension is built in addition to the
136 getdns library. Extensions are built as an additional shared library.
137 The following event loop libraries are supported:
138 libevent1 and libevent2
140 The libevent extension allows a context to attach to a event_base. The
143 event loop is then run like any other application using libevent via
144 event_base_dispatch or event_base_loop and expect getdns callbacks to
145 fire.
146 Note that if both libevent1 and libevent2 reside on system, the exten‐
149 sion uses libevent2.
150 Extension library: libgetdns_ext_event.[shared_lib_ext]
152 Extension header: getdns/getdns_ext_libevent.h
153 libuv
155 The libuv extension allows a context to attach to a uv_loop_s. The
158 event loop can then be run like any other application using libuv via
159 uv_run and expect getdns callbacks to fire.
160 Extension library: libgetdns_ext_uv.[shared_lib_ext]
162 Extension header: getdns_ext_libuv.h
163 libev
165 The libev extension allows a context to attach to a ev_loop. The event
168 loop can then be run like any other application using libev via ev_run
169 and expect getdns callbacks to fire.
170 Extension library: libgetdns_ext_ev.[shared_lib_ext]
172 Extension header: getdns_ext_libev.h
173 getdns_context event loop extension functions
176 The following are functions used by the extension entry point to attach
177 to a particular context.
178 The application sets an event loop extension on a context. The exten‐
181 sion_data is optional data that is passed into the extension methods.
182 If an event loop is already set on a context then it is cleaned up.
183 All outstanding requests are also canceled.
184 getdns_return_t getdns_extension_set_eventloop(struct
187 getdns_context* context, getdns_eventloop_extension* extension,
188 void* extension_data);
189 The application gets the extension data associated with a context.
192 void* getdns_context_get_extension_data(struct getdns_context*
195 context);
196 When no more work must be done the application detaches an event loop
199 from a context
200 getdns_return_t getdns_extension_detach_eventloop(struct
203 getdns_context* context);
204
208 There are four synchronous functions parallel to the four getdns async
209 functions, except that there is no callback parameter. When an applica‐
210 tion calls one of these synchronous functions, the API gathers all the
211 required information and then returns the result. The value returned is
212 exactly the same as the response returned in the callback if you had
213 used the async version of the function.
214 When you are done with the data in the response, call
217 getdns_free_sync_request_memory so that the API can free the memory
218 from its internal pool.
219
222 Applications may populate an extension dictionary when making a call to
223 the public entry points. To use an extension add it to the extension
224 dictionary prior to making the call to the public entry point and set
225 the value depending on the behavior you expect. These extensions in‐
226 clude:
227 "dnssec_return_status" (int)
230 Set to GETDNS_EXTENSION_TRUE to include the DNSSEC status for each
232 DNS record in the replies_tree
233 "dnssec_return_only_secure" (int)
236 Set to GETDNS_EXTENSION_TRUE to cause only records that the API can
238 validate as secure with DNSSEC to be returned in the replies_tree
239 and replies_full lists
240 "dnssec_return_validation_chain" (int)
243 Set to GETDNS_EXTENSION_TRUE to cause the set of additional DNSSEC-
245 related records needed for validation to be returned in the response
246 object as the list named additional_dnssec at the top level of the
247 response object
248 "return_both_v4_and_v6" (int)
251 Set to GETDNS_EXTENSION_TRUE to cause the results of both A and AAAA
253 records for the queried name to be included in the response object.
254 "add_opt_parameters" (dict)
257 TBD (complicated)
259 "add_warning_for_bad_dns"
262 Set to GETDNS_EXTENSION_TRUE to cause each reply in the replies_tree
264 to contain an additional name whose data type is a list, bad_dns
265 which contains zero or more ints that indicate the types of bad DNS
266 found in the reply.
267 GETDNS_BAD_DNS_CNAME_IN_TARGET: query type does not allow a CNAME
268 pointed to a CNAME
269 GETDNS_BAD_DNS_ALL_NUMERIC_LABEL: one or more labels is all nu‐
270 meric
271 GETDNS_BAD_DNS_CNAME_RETURNED_FOR_OTHER_TYPE: query type for
272 other than CNAME returned a CNAME
273 "specify_class" (int)
276 Set to the DNS class number (other than Internet (IN) class desired
278 in query.
279 "return_call_reporting" (int)
282 Set to GETDNS_EXTENSION_TRUE to add the name call_reporting (list)
284 to the top level of the response object that includes a dict for
285 each call made to the API. TBD: more detail
286 This implementation of the getdns API is licensed under the BSD li‐
289 cense.
290
293 If an application wants the API to do DNSSEC validation for a request,
294 it must set one or more DNSSEC-related extensions. Note that the de‐
295 fault is for none of these extensions to be set and the API will not
296 perform DNSSEC. Note that getting DNSSEC results can take longer in a
297 few circumstances.
298 To return the DNSSEC status for each DNS record in the replies_tree
301 list, use the dnssec_return_status extension. The extension's value (an
302 int) is set to GETDNS_EXTENSION_TRUE to cause the returned status to
303 have the name dnssec_status (an int) added to the other names in the
304 record's dict ("header", "question", and so on). The values for that
305 name are GETDNS_DNSSEC_SECURE, GETDNS_DNSSEC_BOGUS, GETDNS_DNSSEC_INDE‐
306 TERMINATE, and GETDNS_DNSSEC_INSECURE. Thus, a reply might look like:
307 { # This is the first reply
309 "dnssec_status": GETDNS_DNSSEC_INDETERMINATE,
310 "header": { "id": 23456, "qr": 1, "opcode": 0, ... },
311 . . .
312 If instead of returning the status, you want to only see secure re‐
315 sults, use the dnssec_return_only_secure extension. The extension's
316 value (an int) is set to GETDNS_EXTENSION_TRUE to cause only records
317 that the API can validate as secure with DNSSEC to be returned in the
318 replies_tree and replies_full lists. No additional names are added to
319 the dict of the record; the change is that some records might not ap‐
320 pear in the results. When this context option is set, if the API re‐
321 ceives DNS replies but none are determined to be secure, the error code
322 at the top level of the response object is GETDNS_RESPSTATUS_NO_SE‐
323 CURE_ANSWERS.
324 Applications that want to do their own validation will want to have the
327 DNSSEC-related records for a particular response. Use the dnssec_re‐
328 turn_validation_chain extension. The extension's value (an int) is set
329 to GETDNS_EXTENSION_TRUE to cause a set of additional DNSSEC-related
330 records needed for validation to be returned in the response object.
331 This set comes as validation_chain (a list) at the top level of the re‐
332 sponse object. This list includes all resource record dicts for all the
333 resource records (DS, DNSKEY and their RRSIGs) that are needed to per‐
334 form the validation from the root up. Thus, a reply might look like:
335 { # This is the response object
337 "validation_chain":
338 [ { "name": <bindata for .>,
339 "type": GETDNS_RRTYPE_DNSKEY,
340 "rdata": { "flags": 256, . . . },
341 . . .
342 },
343 { "name": <bindata for .>,
344 "type": GETDNS_RRTYPE_DNSKEY,
345 "rdata": { "flags": 257, . . . },
346 . . .
347 },
348 { "name": <bindata for .>,
349 "type": GETDNS_RRTYPE_RRSIG,
350 "rdata": { "signers_name": <bindata for .>,
351 "type_covered": GETDNS_RRTYPE_DNSKEY,
352 . . .
353 },
354 },
355 { "name": <bindata for com.>,
356 "type": GETDNS_RRTYPE_DS,
357 . . .
358 },
359 { "name": <bindata for com.>,
360 "type": GETDNS_RRTYPE_RRSIG
361 "rdata": { "signers_name": <bindata for .>,
362 "type_covered": GETDNS_RRTYPE_DS,
363 . . .
364 },
365 . . .
366 },
367 { "name": <bindata for com.>,
368 "type": GETDNS_RRTYPE_DNSKEY
369 "rdata": { "flags": 256, . . . },
370 . . .
371 },
372 { "name": <bindata for com.>,
373 "type": GETDNS_RRTYPE_DNSKEY
374 "rdata": { "flags": 257, . . . },
375 . . .
376 },
377 { "name": <bindata for com.>,
378 "type": GETDNS_RRTYPE_RRSIG
379 "rdata": { "signers_name": <bindata for com.>,
380 "type_covered": GETDNS_RRTYPE_DNSKEY,
381 . . .
382 },
383 . . .
384 },
385 { "name": <bindata for example.com.>,
386 "type": GETDNS_RRTYPE_DS,
387 . . .
388 },
389 { "name": <bindata for example.com.>,
390 "type": GETDNS_RRTYPE_RRSIG
391 "rdata": { "signers_name": <bindata for com.>,
392 "type_covered": GETDNS_RRTYPE_DS,
393 . . .
394 },
395 . . .
396 },
397 { "name": <bindata for example.com.>,
398 "type": GETDNS_RRTYPE_DNSKEY
399 "rdata": { "flags": 257, ... },
400 . . .
401 },
402 . . .
403 ]
404 "replies_tree":
405 [
406 . . .
407 If a request is using a context in which stub resolution is set, and
410 that request also has any of the dnssec_return_status, dnssec_re‐
411 turn_only_secure, or dnssec_return_validation_chain extensions speci‐
412 fied, the API will not perform the request and will instead return an
413 error of GETDNS_RETURN_DNSSEC_WITH_STUB_DISALLOWED.
414
417 For lookups that need an OPT resource record in the Additional Data
418 section, use the add_opt_parameters extension. The extension's value (a
419 dict) contains the parameters; these are described in more detail in
420 RFC 2671. They are:
421 maximum_udp_payload_size (an int) between 512 and 65535; if not speci‐
424 fied, this defaults to those from the DNS context
425 extended_rcode (an int) between 0 and 255; if not specified, this de‐
428 faults to those from the DNS context
429 version (an int) between 0 and 255; if not specified, this defaults to
432 0
433 do_bit (an int) between 0 and 1; if not specified, this defaults to
436 those from the DNS context
437 options (a list) contains dicts for each option to be specified. Each
440 list time contains two names: option_code (an int) and option_data
441 (a bindata). The API marshalls the entire set of options into a
442 properly-formatted RDATA for the resource record.
443 It is very important to note that the OPT resource record specified in
446 the add_opt_parameters extension might not be the same the one that the
447 API sends in the query. For example, if the application also includes
448 any of the DNSSEC extensions, the API will make sure that the OPT re‐
449 source record sets the resource record appropriately, making the needed
450 changes to the settings from the add_opt_parameters extension.
451 The use of this extension can conflict with the values in the DNS con‐
454 text. For example, the default for an OS might be a maximum payload
455 size of 65535, but the extension might specify 1550. In such a case,
456 the API will honor the values stated in the extension, but will honor
457 the values from the DNS context if values are not given in the exten‐
458 sion.
459
462 The callback function contains a pointer to a response object. A re‐
463 sponse object is always a dict. The response object always contains at
464 least three names: replies_full (a list) and replies_tree (a list), and
465 status (an int). replies_full is a list of DNS replies (each is
466 bindata) as they appear on the wire. replies_tree is a list of DNS
467 replies (each is a dict) with the various part of the reply parsed out.
468 status is a status code for the query.
469 Because the API might be extended in the future, a response object
472 might also contain names other than replies_full, replies_tree, and
473 status. Similarly, any of the dicts described here might be extended in
474 later versions of the API. Thus, an application using the API must not
475 assume that it knows all possible names in a dict.
476 The following lists the status codes for response objects. Note that,
479 if the status is that there are no responses for the query, the lists
480 in replies_full and replies_tree will have zero length.
481 GETDNS_RESPSTATUS_GOOD At least one response was returned
484 GETDNS_RESPSTATUS_NO_NAME Queries for the name yielded all negative re‐
486 sponses
487 GETDNS_RESPSTATUS_ALL_TIMEOUT All queries for the name timed out
489 GETDNS_RESPSTATUS_NO_SECURE_ANSWERS The context setting for getting
491 only secure responses was specified, and at least one DNS response
492 was received, but no DNS response was determined to be secure
493 through DNSSEC.
494 The top level of replies_tree can optionally have the following names:
497 canonical_name (a bindata), intermediate_aliases (a list), an‐
498 swer_ipv4_address (a bindata), answer_ipv6_address (a bindata), and an‐
499 swer_type (an int).
500 The value of canonical_name is the name that the API used for its
503 lookup. It is in FQDN presentation format. The values in the interme‐
504 diate_aliases list are domain names from any CNAME or unsynthesized
505 DNAME found when resolving the original query. The list might have zero
506 entries if there were no CNAMEs in the path. These may be useful, for
507 example, for name comparisons when following the rules in RFC 6125.
508 The value of answer_ipv4_address and answer_ipv6_address are the ad‐
509 dresses of the server from which the answer was received. The value of
510 answer_type is the type of name service that generated the response.
511 The values are:
512 GETDNS_NAMETYPE_DNS
514 Normal DNS (RFC 1035)
515 GETDNS_NAMETYPE_WINS
516 The WINS name service (some reference needed)
517 If the call was getdns_address or getdns_address_sync, the top level of
520 replies_tree has an additional name, just_address_answers (a list). The
521 value of just_address_answers is a list that contains all of the A and
522 AAAA records from the answer sections of any of the replies, in the or‐
523 der they appear in the replies. Each item in the list is a dict with at
524 least two names: address_type (whose value is a bindata; it is cur‐
525 rently either "IPv4" or "IPv6") and address_data (whose value is a
526 bindata). Note that the dnssec_return_only_secure extension affects
527 what will appear in the just_address_answers list. If the DNS returns
528 other address types, those types will appear in this list as well.
529 The API can make service discovery through SRV records easier. If the
532 call was getdns_service or getdns_service_sync, the top level of
533 replies_tree has an additional name, srv_addresses (a list). The list
534 is ordered by priority and weight based on the weighting algorithm in
535 RFC 2782, lowest priority value first. Each element of the list is dict
536 has at least two names: port and domain_name. If the API was able to
537 determine the address of the target domain name (such as from its cache
538 or from the Additional section of responses), the dict for an element
539 will also contain address_type (whose value is a bindata; it is cur‐
540 rently either "IPv4" or "IPv6") and address_data (whose value is a
541 bindata). Note that the dnssec_return_only_secure extension affects
542 what will appear in the srv_addresses list.
543
546 The names in each entry in the the replies_tree list for DNS responses
547 include header (a dict), question (a dict), answer (a list), authority
548 (a list), and additional (a list), corresponding to the sections in the
549 DNS message format. The answer, authority, and additional lists each
550 contain zero or more dicts, with each dict in each list representing a
551 resource record.
552 The names in the header dict are all the fields from Section 4.1.1. of
555 RFC 1035. They are: id, qr, opcode, aa, tc, rd, ra, z, rcode, qdcount,
556 ancount, nscount, and arcount. All are ints.
557 The names in the question dict are the three fields from Section 4.1.2.
560 of RFC 1035: qname (a bindata), qtype (an int), and qclass (an int).
561 Resource records are a bit different than headers and question sections
564 in that the RDATA portion often has its own structure. The other names
565 in the resource record dicts are name (a bindata), type (an int), class
566 (an int), ttl (an int) and rdata (a dict); there is no name equivalent
567 to the RDLENGTH field.
568 The rdata dict has different names for each response type. There is a
571 complete list of the types defined in the API. For names that end in
572 "-obsolete" or "-unknown", the bindata is the entire RDATA field. For
573 example, the rdata for an A record has a name ipv4_address (a bindata);
574 the rdata for an SRV record has the names priority (an int), weight (an
575 int), port (an int), and target (a bindata).
576 Each rdata dict also has a rdata_raw field (a bindata). This is useful
579 for types not defined in this version of the API. It also might be of
580 value if a later version of the API allows for additional parsers.
581 Thus, doing a query for types not known by the API still will return a
582 result: an rdata with just a rdata_raw.
583 It is expected that later extensions to the API will give some DNS
586 types different names. It is also possible that later extensions will
587 change the names for some of the DNS types listed above.
588
591 A call to the async getdns functions typically returns before any net‐
592 work or file I/O occurs. After the API marshalls all the needed infor‐
593 mation, it calls the callback function that was passed by the applica‐
594 tion. The callback function might be called at any time, even before
595 the calling function has returned. The API guarantees that the callback
596 will be called exactly once unless the calling function returned an er‐
597 ror, in which case the callback function is never called.
598 The getdns calling function calls the callback with the parameters de‐
600 fined as follows:
601 typedef void (*getdns_callback_t)(
603 getdns_context_t context,
604 uint16_t callback_type,
605 getdns_dict *response,
606 void *userarg,
607 getdns_transaction_t transaction_id)
608 context see getdns_context (3)
611 callback_type Supplies the reason for the callback.
614 GETDNS_CALLBACK_COMPLETE The response has the requested data in it
616 GETDNS_CALLBACK_CANCEL The calling program canceled the callback;
618 response is NULL
619 GETDNS_CALLBACK_TIMEOUT The requested action timed out; response is
621 NULL
622 GETDNS_CALLBACK_ERROR The requested action had an error; response is
624 NULL
625 response A response object with the response data. This is described in
628 the section titled "RESPONSE DATA" elsewhere in this manual page.
629 The response object is part of the API's memory space, and will be
630 freed by the API with the callback returns.
631 userarg Identical to the userarg passed to the calling function.
634 transaction_id The transaction identified assigned by the calling func‐
637 tion, used to associate a DNS response to a specific DNS request.
638 To cancel an outstanding callback, use the following function.
641 getdns_return_t
643 getdns_cancel_callback (getdns_context_t context, getdns_transac‐
644 tion_t transaction_id)
645 This causes the API to call the callback with a callback_type of
648 GETDNS_CALLBACK_CANCEL if the callback for this transaction_id has not
649 already been called. The callback code for cancellation should clean up
650 any memory related to the identified call, such as to deallocate the
651 memory for the userarg. getdns_cancel_callback() may return immedi‐
652 ately, even before the callback finishes its work and returns. Calling
653 getdns_cancel_callback() with a transaction_id of a callback that has
654 already been called or an unknown transaction_id returns GETDNS_RE‐
655 TURN_UNKNOWN_TRANSACTION; otherwise, getdns_cancel_callback() returns
656 GETDNS_RETURN_GOOD.
657
661 TBD
662
665 TBD
666
669 getdns_address(3), getdns_bindata(3), getdns_context(3), getdns_con‐
670 vert(3), getdns_dict(3), getdns_general(3), getdns_hostname(3),
671 getdns_list(3), getdns_root_trust_anchor(3) getdns_service(3)
672 getdns_validate_dnssec(3)
673
676 Bug reports should be sent to the getdns-bugs@getdns.net
677
680 The getdns API was documented by Paul Hoffman. This implementation of
681 the getdns API was written by:
682 Craig Despeaux, Verisign Inc.
684 John Dickinson, Sinodun
685 Sara Dickinson, Sinodun
686 Neel Goyal, Verisign Inc.
687 Shumon Huque, Verisign Labs
688 Olaf Kolkman, NLnet Labs
689 Allison Mankin, Verisign Inc. - Verisign Labs.
690 Melinda Shore, No Mountain Software LLC
691 Willem Toorop, NLnet Labs
692 Gowri Visweswaran, Verisign Labs
693 Wouter Wijngaards, NLnet Labs
694 Glen Wiley, Verisign Inc.
695getdns 1.7.3 December 2015 libgetdns(3)