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
128 descriptor signals that it is ready. User callbacks are fired dur‐
129 ing 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
226 include:
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
270 numeric
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
289 license.
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
295 default 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
315 results, 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
320 appear in the results. When this context option is set, if the API
321 receives DNS replies but none are determined to be secure, the error
322 code at the top level of the response object is GETDNS_RESPSTA‐
323 TUS_NO_SECURE_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
328 dnssec_return_validation_chain extension. The extension's value (an
329 int) is set to GETDNS_EXTENSION_TRUE to cause a set of additional
330 DNSSEC-related records needed for validation to be returned in the
331 response object. This set comes as validation_chain (a list) at the top
332 level of the response object. This list includes all resource record
333 dicts for all the resource records (DS, DNSKEY and their RRSIGs) that
334 are needed to perform the validation from the root up. Thus, a reply
335 might look like:
336 { # This is the response object
338 "validation_chain":
339 [ { "name": <bindata for .>,
340 "type": GETDNS_RRTYPE_DNSKEY,
341 "rdata": { "flags": 256, . . . },
342 . . .
343 },
344 { "name": <bindata for .>,
345 "type": GETDNS_RRTYPE_DNSKEY,
346 "rdata": { "flags": 257, . . . },
347 . . .
348 },
349 { "name": <bindata for .>,
350 "type": GETDNS_RRTYPE_RRSIG,
351 "rdata": { "signers_name": <bindata for .>,
352 "type_covered": GETDNS_RRTYPE_DNSKEY,
353 . . .
354 },
355 },
356 { "name": <bindata for com.>,
357 "type": GETDNS_RRTYPE_DS,
358 . . .
359 },
360 { "name": <bindata for com.>,
361 "type": GETDNS_RRTYPE_RRSIG
362 "rdata": { "signers_name": <bindata for .>,
363 "type_covered": GETDNS_RRTYPE_DS,
364 . . .
365 },
366 . . .
367 },
368 { "name": <bindata for com.>,
369 "type": GETDNS_RRTYPE_DNSKEY
370 "rdata": { "flags": 256, . . . },
371 . . .
372 },
373 { "name": <bindata for com.>,
374 "type": GETDNS_RRTYPE_DNSKEY
375 "rdata": { "flags": 257, . . . },
376 . . .
377 },
378 { "name": <bindata for com.>,
379 "type": GETDNS_RRTYPE_RRSIG
380 "rdata": { "signers_name": <bindata for com.>,
381 "type_covered": GETDNS_RRTYPE_DNSKEY,
382 . . .
383 },
384 . . .
385 },
386 { "name": <bindata for example.com.>,
387 "type": GETDNS_RRTYPE_DS,
388 . . .
389 },
390 { "name": <bindata for example.com.>,
391 "type": GETDNS_RRTYPE_RRSIG
392 "rdata": { "signers_name": <bindata for com.>,
393 "type_covered": GETDNS_RRTYPE_DS,
394 . . .
395 },
396 . . .
397 },
398 { "name": <bindata for example.com.>,
399 "type": GETDNS_RRTYPE_DNSKEY
400 "rdata": { "flags": 257, ... },
401 . . .
402 },
403 . . .
404 ]
405 "replies_tree":
406 [
407 . . .
408 If a request is using a context in which stub resolution is set, and
411 that request also has any of the dnssec_return_status,
412 dnssec_return_only_secure, or dnssec_return_validation_chain extensions
413 specified, the API will not perform the request and will instead return
414 an error of GETDNS_RETURN_DNSSEC_WITH_STUB_DISALLOWED.
415
418 For lookups that need an OPT resource record in the Additional Data
419 section, use the add_opt_parameters extension. The extension's value (a
420 dict) contains the parameters; these are described in more detail in
421 RFC 2671. They are:
422 maximum_udp_payload_size (an int) between 512 and 65535; if not speci‐
425 fied, this defaults to those from the DNS context
426 extended_rcode (an int) between 0 and 255; if not specified, this
429 defaults to those from the DNS context
430 version (an int) between 0 and 255; if not specified, this defaults to
433 0
434 do_bit (an int) between 0 and 1; if not specified, this defaults to
437 those from the DNS context
438 options (a list) contains dicts for each option to be specified. Each
441 list time contains two names: option_code (an int) and option_data
442 (a bindata). The API marshalls the entire set of options into a
443 properly-formatted RDATA for the resource record.
444 It is very important to note that the OPT resource record specified in
447 the add_opt_parameters extension might not be the same the one that the
448 API sends in the query. For example, if the application also includes
449 any of the DNSSEC extensions, the API will make sure that the OPT
450 resource record sets the resource record appropriately, making the
451 needed changes to the settings from the add_opt_parameters extension.
452 The use of this extension can conflict with the values in the DNS con‐
455 text. For example, the default for an OS might be a maximum payload
456 size of 65535, but the extension might specify 1550. In such a case,
457 the API will honor the values stated in the extension, but will honor
458 the values from the DNS context if values are not given in the exten‐
459 sion.
460
463 The callback function contains a pointer to a response object. A
464 response object is always a dict. The response object always contains
465 at least three names: replies_full (a list) and replies_tree (a list),
466 and status (an int). replies_full is a list of DNS replies (each is
467 bindata) as they appear on the wire. replies_tree is a list of DNS
468 replies (each is a dict) with the various part of the reply parsed out.
469 status is a status code for the query.
470 Because the API might be extended in the future, a response object
473 might also contain names other than replies_full, replies_tree, and
474 status. Similarly, any of the dicts described here might be extended in
475 later versions of the API. Thus, an application using the API must not
476 assume that it knows all possible names in a dict.
477 The following lists the status codes for response objects. Note that,
480 if the status is that there are no responses for the query, the lists
481 in replies_full and replies_tree will have zero length.
482 GETDNS_RESPSTATUS_GOOD At least one response was returned
485 GETDNS_RESPSTATUS_NO_NAME Queries for the name yielded all negative
487 responses
488 GETDNS_RESPSTATUS_ALL_TIMEOUT All queries for the name timed out
490 GETDNS_RESPSTATUS_NO_SECURE_ANSWERS The context setting for getting
492 only secure responses was specified, and at least one DNS response
493 was received, but no DNS response was determined to be secure
494 through DNSSEC.
495 The top level of replies_tree can optionally have the following names:
498 canonical_name (a bindata), intermediate_aliases (a list),
499 answer_ipv4_address (a bindata), answer_ipv6_address (a bindata), and
500 answer_type (an int).
501 The value of canonical_name is the name that the API used for its
504 lookup. It is in FQDN presentation format. The values in the interme‐
505 diate_aliases list are domain names from any CNAME or unsynthesized
506 DNAME found when resolving the original query. The list might have zero
507 entries if there were no CNAMEs in the path. These may be useful, for
508 example, for name comparisons when following the rules in RFC 6125.
509 The value of answer_ipv4_address and answer_ipv6_address are the
510 addresses of the server from which the answer was received. The value
511 of answer_type is the type of name service that generated the response.
512 The values are:
513 GETDNS_NAMETYPE_DNS
515 Normal DNS (RFC 1035)
516 GETDNS_NAMETYPE_WINS
517 The WINS name service (some reference needed)
518 If the call was getdns_address or getdns_address_sync, the top level of
521 replies_tree has an additional name, just_address_answers (a list). The
522 value of just_address_answers is a list that contains all of the A and
523 AAAA records from the answer sections of any of the replies, in the
524 order they appear in the replies. Each item in the list is a dict with
525 at least two names: address_type (whose value is a bindata; it is cur‐
526 rently either "IPv4" or "IPv6") and address_data (whose value is a
527 bindata). Note that the dnssec_return_only_secure extension affects
528 what will appear in the just_address_answers list. If the DNS returns
529 other address types, those types will appear in this list as well.
530 The API can make service discovery through SRV records easier. If the
533 call was getdns_service or getdns_service_sync, the top level of
534 replies_tree has an additional name, srv_addresses (a list). The list
535 is ordered by priority and weight based on the weighting algorithm in
536 RFC 2782, lowest priority value first. Each element of the list is dict
537 has at least two names: port and domain_name. If the API was able to
538 determine the address of the target domain name (such as from its cache
539 or from the Additional section of responses), the dict for an element
540 will also contain address_type (whose value is a bindata; it is cur‐
541 rently either "IPv4" or "IPv6") and address_data (whose value is a
542 bindata). Note that the dnssec_return_only_secure extension affects
543 what will appear in the srv_addresses list.
544
547 The names in each entry in the the replies_tree list for DNS responses
548 include header (a dict), question (a dict), answer (a list), authority
549 (a list), and additional (a list), corresponding to the sections in the
550 DNS message format. The answer, authority, and additional lists each
551 contain zero or more dicts, with each dict in each list representing a
552 resource record.
553 The names in the header dict are all the fields from Section 4.1.1. of
556 RFC 1035. They are: id, qr, opcode, aa, tc, rd, ra, z, rcode, qdcount,
557 ancount, nscount, and arcount. All are ints.
558 The names in the question dict are the three fields from Section 4.1.2.
561 of RFC 1035: qname (a bindata), qtype (an int), and qclass (an int).
562 Resource records are a bit different than headers and question sections
565 in that the RDATA portion often has its own structure. The other names
566 in the resource record dicts are name (a bindata), type (an int), class
567 (an int), ttl (an int) and rdata (a dict); there is no name equivalent
568 to the RDLENGTH field.
569 The rdata dict has different names for each response type. There is a
572 complete list of the types defined in the API. For names that end in
573 "-obsolete" or "-unknown", the bindata is the entire RDATA field. For
574 example, the rdata for an A record has a name ipv4_address (a bindata);
575 the rdata for an SRV record has the names priority (an int), weight (an
576 int), port (an int), and target (a bindata).
577 Each rdata dict also has a rdata_raw field (a bindata). This is useful
580 for types not defined in this version of the API. It also might be of
581 value if a later version of the API allows for additional parsers.
582 Thus, doing a query for types not known by the API still will return a
583 result: an rdata with just a rdata_raw.
584 It is expected that later extensions to the API will give some DNS
587 types different names. It is also possible that later extensions will
588 change the names for some of the DNS types listed above.
589
592 A call to the async getdns functions typically returns before any net‐
593 work or file I/O occurs. After the API marshalls all the needed infor‐
594 mation, it calls the callback function that was passed by the applica‐
595 tion. The callback function might be called at any time, even before
596 the calling function has returned. The API guarantees that the callback
597 will be called exactly once unless the calling function returned an
598 error, in which case the callback function is never called.
599 The getdns calling function calls the callback with the parameters
601 defined as follows:
602 typedef void (*getdns_callback_t)(
604 getdns_context_t context,
605 uint16_t callback_type,
606 getdns_dict *response,
607 void *userarg,
608 getdns_transaction_t transaction_id)
609 context see getdns_context (3)
612 callback_type Supplies the reason for the callback.
615 GETDNS_CALLBACK_COMPLETE The response has the requested data in it
617 GETDNS_CALLBACK_CANCEL The calling program canceled the callback;
619 response is NULL
620 GETDNS_CALLBACK_TIMEOUT The requested action timed out; response is
622 NULL
623 GETDNS_CALLBACK_ERROR The requested action had an error; response is
625 NULL
626 response A response object with the response data. This is described in
629 the section titled "RESPONSE DATA" elsewhere in this manual page.
630 The response object is part of the API's memory space, and will be
631 freed by the API with the callback returns.
632 userarg Identical to the userarg passed to the calling function.
635 transaction_id The transaction identified assigned by the calling func‐
638 tion, used to associate a DNS response to a specific DNS request.
639 To cancel an outstanding callback, use the following function.
642 getdns_return_t
644 getdns_cancel_callback (getdns_context_t context, getdns_transac‐
645 tion_t transaction_id)
646 This causes the API to call the callback with a callback_type of
649 GETDNS_CALLBACK_CANCEL if the callback for this transaction_id has not
650 already been called. The callback code for cancellation should clean up
651 any memory related to the identified call, such as to deallocate the
652 memory for the userarg. getdns_cancel_callback() may return immedi‐
653 ately, even before the callback finishes its work and returns. Calling
654 getdns_cancel_callback() with a transaction_id of a callback that has
655 already been called or an unknown transaction_id returns
656 GETDNS_RETURN_UNKNOWN_TRANSACTION; otherwise, getdns_cancel_callback()
657 returns GETDNS_RETURN_GOOD.
658
662 TBD
663
666 TBD
667
670 getdns_address(3), getdns_bindata(3), getdns_context(3), getdns_con‐
671 vert(3), getdns_dict(3), getdns_general(3), getdns_hostname(3),
672 getdns_list(3), getdns_root_trust_anchor(3) getdns_service(3)
673 getdns_validate_dnssec(3)
674
677 Bug reports should be sent to the getdns-bugs@getdns.net
678
681 The getdns API was documented by Paul Hoffman. This implementation of
682 the getdns API was written by:
683 Craig Despeaux, Verisign Inc.
685 John Dickinson, Sinodun
686 Sara Dickinson, Sinodun
687 Neel Goyal, Verisign Inc.
688 Shumon Huque, Verisign Labs
689 Olaf Kolkman, NLnet Labs
690 Allison Mankin, Verisign Inc. - Verisign Labs.
691 Melinda Shore, No Mountain Software LLC
692 Willem Toorop, NLnet Labs
693 Gowri Visweswaran, Verisign Labs
694 Wouter Wijngaards, NLnet Labs
695 Glen Wiley, Verisign Inc.
696getdns 1.4.2 December 2015 libgetdns(3)