plucky (3) libgetdns.3.gz

Provided by: libgetdns-dev_1.6.0-3.2_amd64 bug

NAME

       libgetdns -- an implementation of a modern asynchronous DNS API by and for application developers

LIBRARY

       DNS Resolver library (libgetdns, -lgetdns)

SYNOPSIS

       libgetdns

       This  man  page  describes the getdns library, the general concepts behind the API and some of the common
       elements of the public interface to the library.  Each of the public entry points and more  complex  data
       types are captured in separate man pages.

DESCRIPTION

       getdns  is  modern  asynchronous  DNS  API  intended to be useful to application developers and operating
       system distributors as a way of making all types of DNS information easily available  in  many  types  of
       programs. The major features of this new API are:

              Full support for event-driven programming
              Supports DNSSEC in multiple ways
              Mirroring of the resolution in getaddrinfo()
              Easily supports all RRtypes, even those yet to be defined

       Each  of the entry points is offered with both asynchronous and synchronous signatures.  The asynchronous
       functions rely on event handling and callback via libevent.  Functions are thread safe.

       A context structure maintains DNS query and response data and is used to maintain state during  calls  to
       the public entry points.

       The project page for this implementation is at

              http://getdnsapi.net

       The specification is maintained at

              http://getdnsapi.net/spec

       The git repository for this implementation is at

              http://github.com/getdnsapi/getdns

DATA STRUCTURES

       The API uses a few data structures to pass data into and return data from the public entry points.

       list   an ordered list, the members of the list can be any of the four data types.

       dict   a  name-value pair. The name is a string literal, and the value can be any of the four data types.
              The order of the name-value pairs in a dict is not important.

       int    an integer compatible with uint32_t.

       bindata
              a struct used to hold binary data defined as { size_t size; uint8_t *binary_stuff; }.

ASYNCHRONOUS USE

       The getdns specification emphasizes the asynchronous nature of the  API  and  allows  implementations  to
       define their own approach. This page documents this implementation's decisions and facilities provided to
       the developer.

       This implementation provides asynchronous support via the following mechanisms:

          File Descriptor Polling
          Event Loop Integrations:
             libevent
             libuv
             libev
          Custom Event Loop Integrations

       All functions and types discussed in this page are declared in getdns_extra.h

   Build-in Event loop
       The library has an built in event loop that can be used if none of  the  extensions  for  external  event
       loops   are   used.   The   library  will  execute  requests  and  dispatch  callbacks  with  a  call  to
       getdns_context_run().  If an event loop extension is used, this will run the extension's eventloop.

       void getdns_context_run(getdns_context *context)

          Run the context's event loop until nothing more to do.

       uint32_t getdns_context_get_num_pending_requests(getdns_context* context, struct timeval* next_timeout)

          Get the number of outstanding asynchronous requests for a given context as well as the the  amount  of
          time  until  the  next  timeout.   The next_timeout struct can be NULL.  If supplied and the number of
          outstanding requests is > 0, then the timeout represents the relative time until the next timeout.

       getdns_return_t getdns_context_process_async(getdns_context* context)

          Inform the context to process its outstanding requests.  Users should call this when either a  timeout
          has  occurred  or  the file descriptor signals that it is ready.  User callbacks are fired during this
          call.

   Included Event Loop Integrations
       A number of applications achieve asynchronous behavior by leveraging event loop abstraction libraries. If
       the  build  system discovers a supported event loop, the event loop extension is built in addition to the
       getdns library. Extensions are built as an additional shared library. The following event loop  libraries
       are supported:

       libevent1 and libevent2

       The  libevent  extension  allows a context to attach to a event_base. The event loop is then run like any
       other application using libevent via event_base_dispatch or event_base_loop and expect  getdns  callbacks
       to fire.

       Note that if both libevent1 and libevent2 reside on system, the extension uses libevent2.

          Extension library: libgetdns_ext_event.[shared_lib_ext]
          Extension header: getdns/getdns_ext_libevent.h

       libuv

       The  libuv  extension  allows a context to attach to a uv_loop_s. The event loop can then be run like any
       other application using libuv via uv_run and expect getdns callbacks to fire.

          Extension library: libgetdns_ext_uv.[shared_lib_ext]
          Extension header: getdns_ext_libuv.h

       libev

       The libev extension allows a context to attach to a ev_loop. The event loop can  then  be  run  like  any
       other application using libev via ev_run and expect getdns callbacks to fire.

          Extension library: libgetdns_ext_ev.[shared_lib_ext]
          Extension header: getdns_ext_libev.h

   getdns_context event loop extension functions
       The following are functions used by the extension entry point to attach to a particular context.

       The  application  sets an event loop extension on a context.  The extension_data is optional data that is
       passed into the extension methods.  If an event loop is already set on a context then it is  cleaned  up.
       All outstanding requests are also canceled.

              getdns_return_t        getdns_extension_set_eventloop(struct        getdns_context*       context,
              getdns_eventloop_extension* extension, void* extension_data);

       The application gets the extension data associated with a context.

              void* getdns_context_get_extension_data(struct getdns_context* context);

       When no more work must be done the application detaches an event loop from a context

              getdns_return_t getdns_extension_detach_eventloop(struct getdns_context* context);

SYNCHRONOUS USE

       There are four synchronous functions parallel to the four getdns async functions, except that there is no
       callback parameter. When an application calls one of these synchronous functions, the API gathers all the
       required information and then returns the result. The value returned is exactly the same as the  response
       returned in the callback if you had used the async version of the function.

       When you are done with the data in the response, call getdns_free_sync_request_memory so that the API can
       free the memory from its internal pool.

EXTENSIONS

       Applications may populate an extension dictionary when making a call to the public entry points.  To  use
       an  extension  add  it to the extension dictionary prior to making the call to the public entry point and
       set the value depending on the behavior you expect.  These extensions include:

       "dnssec_return_status" (int)

          Set to GETDNS_EXTENSION_TRUE to include the DNSSEC status for each DNS record in the replies_tree

       "dnssec_return_only_secure" (int)

          Set to GETDNS_EXTENSION_TRUE to cause only records that the API can validate as secure with DNSSEC  to
          be returned in the replies_tree and replies_full lists

       "dnssec_return_validation_chain" (int)

          Set  to  GETDNS_EXTENSION_TRUE  to  cause  the  set  of  additional  DNSSEC-related records needed for
          validation to be returned in the response object as the list named additional_dnssec at the top  level
          of the response object

       "return_both_v4_and_v6" (int)

          Set  to  GETDNS_EXTENSION_TRUE to cause the results of both A and AAAA records for the queried name to
          be included in the response object.

       "add_opt_parameters" (dict)

          TBD (complicated)

       "add_warning_for_bad_dns"

          Set to GETDNS_EXTENSION_TRUE to cause each reply in the replies_tree to  contain  an  additional  name
          whose data type is a list, bad_dns which contains zero or more ints that indicate the types of bad DNS
          found in the reply.
             GETDNS_BAD_DNS_CNAME_IN_TARGET: query type does not allow a CNAME pointed to a CNAME
             GETDNS_BAD_DNS_ALL_NUMERIC_LABEL: one or more labels is all numeric
             GETDNS_BAD_DNS_CNAME_RETURNED_FOR_OTHER_TYPE: query type for other than CNAME returned a CNAME

       "specify_class" (int)

          Set to the DNS class number (other than Internet (IN) class desired in query.

       "return_call_reporting" (int)

          Set to GETDNS_EXTENSION_TRUE to add the name call_reporting (list) to the top level  of  the  response
          object that includes a dict for each call made to the API.  TBD: more detail

       This implementation of the getdns API is licensed under the BSD license.

DNSSEC

       If  an  application  wants the API to do DNSSEC validation for a request, it must set one or more DNSSEC-
       related extensions. Note that the default is for none of these extensions to be set and the API will  not
       perform DNSSEC. Note that getting DNSSEC results can take longer in a few circumstances.

       To  return  the  DNSSEC status for each DNS record in the replies_tree list, use the dnssec_return_status
       extension. The extension's value (an int) is set to GETDNS_EXTENSION_TRUE to cause the returned status to
       have the name dnssec_status (an int) added to the other names in the record's dict ("header", "question",
       and   so   on).   The   values   for   that   name   are    GETDNS_DNSSEC_SECURE,    GETDNS_DNSSEC_BOGUS,
       GETDNS_DNSSEC_INDETERMINATE, and GETDNS_DNSSEC_INSECURE.  Thus, a reply might look like:

       {     # This is the first reply
             "dnssec_status": GETDNS_DNSSEC_INDETERMINATE,
             "header": { "id": 23456, "qr": 1, "opcode": 0, ... },
             . . .

       If   instead   of   returning   the   status,   you   want   to   only   see   secure  results,  use  the
       dnssec_return_only_secure extension. The extension's value (an int) is set  to  GETDNS_EXTENSION_TRUE  to
       cause only records that the API can validate as secure with DNSSEC to be returned in the replies_tree and
       replies_full lists.  No additional names are added to the dict of the record; the  change  is  that  some
       records might not appear in the results. When this context option is set, if the API receives DNS replies
       but none are determined to be secure, the error  code  at  the  top  level  of  the  response  object  is
       GETDNS_RESPSTATUS_NO_SECURE_ANSWERS.

       Applications  that  want  to  do  their own validation will want to have the DNSSEC-related records for a
       particular response. Use the dnssec_return_validation_chain extension. The extension's value (an int)  is
       set to GETDNS_EXTENSION_TRUE to cause a set of additional DNSSEC-related records needed for validation to
       be returned in the response object. This set comes as validation_chain (a list) at the top level  of  the
       response  object.  This  list includes all resource record dicts for all the resource records (DS, DNSKEY
       and their RRSIGs) that are needed to perform the validation from the root up. Thus, a  reply  might  look
       like:

       {     # This is the response object
           "validation_chain":
           [ { "name": <bindata for .>,
           "type": GETDNS_RRTYPE_DNSKEY,
           "rdata": { "flags": 256, . . . },
             . . .
           },
           { "name": <bindata for .>,
             "type": GETDNS_RRTYPE_DNSKEY,
             "rdata": { "flags": 257, . . . },
             . . .
           },
           { "name": <bindata for .>,
             "type": GETDNS_RRTYPE_RRSIG,
             "rdata": { "signers_name": <bindata for .>,
                        "type_covered": GETDNS_RRTYPE_DNSKEY,
                        . . .
                      },
           },
           { "name": <bindata for com.>,
             "type": GETDNS_RRTYPE_DS,
             . . .
           },
           { "name": <bindata for com.>,
             "type": GETDNS_RRTYPE_RRSIG
             "rdata": { "signers_name": <bindata for .>,
                        "type_covered": GETDNS_RRTYPE_DS,
                        . . .
                      },
             . . .
           },
           { "name": <bindata for com.>,
             "type": GETDNS_RRTYPE_DNSKEY
             "rdata": { "flags": 256, . . . },
             . . .
           },
           { "name": <bindata for com.>,
             "type": GETDNS_RRTYPE_DNSKEY
             "rdata": { "flags": 257, . . . },
             . . .
           },
           { "name": <bindata for com.>,
             "type": GETDNS_RRTYPE_RRSIG
             "rdata": { "signers_name": <bindata for com.>,
                        "type_covered": GETDNS_RRTYPE_DNSKEY,
                        . . .
                      },
             . . .
           },
           { "name": <bindata for example.com.>,
             "type": GETDNS_RRTYPE_DS,
             . . .
           },
           { "name": <bindata for example.com.>,
             "type": GETDNS_RRTYPE_RRSIG
             "rdata": { "signers_name": <bindata for com.>,
                        "type_covered": GETDNS_RRTYPE_DS,
                        . . .
                      },
             . . .
           },
           { "name": <bindata for example.com.>,
             "type": GETDNS_RRTYPE_DNSKEY
             "rdata": { "flags": 257, ... },
             . . .
           },
           . . .
         ]
         "replies_tree":
         [
         . . .

       If  a  request  is  using a context in which stub resolution is set, and that request also has any of the
       dnssec_return_status, dnssec_return_only_secure, or dnssec_return_validation_chain extensions  specified,
       the    API    will    not    perform    the    request    and   will   instead   return   an   error   of
       GETDNS_RETURN_DNSSEC_WITH_STUB_DISALLOWED.

OPT RESOURCE RECORDS

       For lookups that need an OPT resource record in the Additional Data section, use  the  add_opt_parameters
       extension.  The extension's value (a dict) contains the parameters; these are described in more detail in
       RFC 2671. They are:

       maximum_udp_payload_size (an int) between 512 and 65535; if not specified, this defaults  to  those  from
          the DNS context

       extended_rcode (an int) between 0 and 255; if not specified, this defaults to those from the DNS context

       version (an int) between 0 and 255; if not specified, this defaults to 0

       do_bit (an int) between 0 and 1; if not specified, this defaults to those from the DNS context

       options  (a  list)  contains  dicts  for  each option to be specified. Each list time contains two names:
          option_code (an int) and option_data (a bindata). The API marshalls the entire set of options  into  a
          properly-formatted RDATA for the resource record.

       It  is  very important to note that the OPT resource record specified in the add_opt_parameters extension
       might not be the same the one that the API sends in the query.  For  example,  if  the  application  also
       includes  any  of  the  DNSSEC  extensions,  the API will make sure that the OPT resource record sets the
       resource record appropriately, making the needed changes to  the  settings  from  the  add_opt_parameters
       extension.

       The  use  of this extension can conflict with the values in the DNS context. For example, the default for
       an OS might be a maximum payload size of 65535, but the extension might specify 1550. In such a case, the
       API  will  honor  the  values  stated in the extension, but will honor the values from the DNS context if
       values are not given in the extension.

RESPONSE DATA

       The callback function contains a pointer to a response object. A response object is always  a  dict.  The
       response  object  always  contains at least three names: replies_full (a list) and replies_tree (a list),
       and status (an int).  replies_full is a list of DNS replies (each is bindata) as they appear on the wire.
       replies_tree  is  a  list  of DNS replies (each is a dict) with the various part of the reply parsed out.
       status is a status code for the query.

       Because the API might be extended in the future, a response object might also contain  names  other  than
       replies_full,  replies_tree,  and status. Similarly, any of the dicts described here might be extended in
       later versions of the API.  Thus, an application using the API must not assume that it knows all possible
       names in a dict.

       The  following lists the status codes for response objects. Note that, if the status is that there are no
       responses for the query, the lists in replies_full and replies_tree will have zero length.

       GETDNS_RESPSTATUS_GOOD At least one response was returned

       GETDNS_RESPSTATUS_NO_NAME Queries for the name yielded all negative responses

       GETDNS_RESPSTATUS_ALL_TIMEOUT All queries for the name timed out

       GETDNS_RESPSTATUS_NO_SECURE_ANSWERS The context setting for getting only secure responses was  specified,
          and  at  least  one DNS response was received, but no DNS response was determined to be secure through
          DNSSEC.

       The top level of replies_tree can optionally  have  the  following  names:  canonical_name  (a  bindata),
       intermediate_aliases  (a  list),  answer_ipv4_address  (a  bindata), answer_ipv6_address (a bindata), and
       answer_type (an int).

       The value of canonical_name is the name that the API used for its lookup.  It  is  in  FQDN  presentation
       format.   The  values  in  the intermediate_aliases list are domain names from any CNAME or unsynthesized
       DNAME found when resolving the original query. The list might have zero entries if there were  no  CNAMEs
       in the path. These may be useful, for example, for name comparisons when following the rules in RFC 6125.
       The value of answer_ipv4_address and answer_ipv6_address are the addresses of the server from  which  the
       answer  was  received.  The value of answer_type is the type of name service that generated the response.
       The values are:

              GETDNS_NAMETYPE_DNS
              Normal DNS (RFC 1035)
              GETDNS_NAMETYPE_WINS
              The WINS name service (some reference needed)

       If the call was getdns_address or getdns_address_sync, the top level of replies_tree  has  an  additional
       name, just_address_answers (a list). The value of just_address_answers is a list that contains all of the
       A and AAAA records from the answer sections of any of the replies,  in  the  order  they  appear  in  the
       replies. Each item in the list is a dict with at least two names: address_type (whose value is a bindata;
       it is currently either "IPv4" or "IPv6") and address_data (whose value  is  a  bindata).  Note  that  the
       dnssec_return_only_secure extension affects what will appear in the just_address_answers list. If the DNS
       returns other address types, those types will appear in this list as well.

       The API can make service discovery through  SRV  records  easier.  If  the  call  was  getdns_service  or
       getdns_service_sync,  the  top  level of replies_tree has an additional name, srv_addresses (a list). The
       list is ordered by priority and weight based on the weighting algorithm  in  RFC  2782,  lowest  priority
       value  first.  Each  element of the list is dict has at least two names: port and domain_name. If the API
       was able to determine the address of the target  domain  name  (such  as  from  its  cache  or  from  the
       Additional  section of responses), the dict for an element will also contain address_type (whose value is
       a bindata; it is currently either "IPv4" or "IPv6") and address_data (whose value  is  a  bindata).  Note
       that the dnssec_return_only_secure extension affects what will appear in the srv_addresses list.

STRUCTURE OF DNS REPLIES_TREE

       The  names in each entry in the the replies_tree list for DNS responses include header (a dict), question
       (a dict), answer (a list), authority (a list), and additional (a list), corresponding to the sections  in
       the  DNS  message  format.   The answer, authority, and additional lists each contain zero or more dicts,
       with each dict in each list representing a resource record.

       The names in the header dict are all the fields from Section 4.1.1.  of  RFC  1035.  They  are:  id,  qr,
       opcode, aa, tc, rd, ra, z, rcode, qdcount, ancount, nscount, and arcount. All are ints.

       The  names  in the question dict are the three fields from Section 4.1.2. of RFC 1035: qname (a bindata),
       qtype (an int), and qclass (an int).

       Resource records are a bit different than headers and question sections in that the RDATA  portion  often
       has  its own structure. The other names in the resource record dicts are name (a bindata), type (an int),
       class (an int), ttl (an int) and rdata (a dict); there is no name equivalent to the RDLENGTH field.

       The rdata dict has different names for each response type. There is a complete list of the types  defined
       in  the  API. For names that end in "-obsolete" or "-unknown", the bindata is the entire RDATA field. For
       example, the rdata for an A record has a name ipv4_address (a bindata); the rdata for an SRV  record  has
       the names priority (an int), weight (an int), port (an int), and target (a bindata).

       Each  rdata  dict  also  has  a rdata_raw field (a bindata). This is useful for types not defined in this
       version of the API. It also might be of value if a  later  version  of  the  API  allows  for  additional
       parsers.  Thus,  doing  a  query for types not known by the API still will return a result: an rdata with
       just a rdata_raw.

       It is expected that later extensions to the API will give some DNS types  different  names.  It  is  also
       possible that later extensions will change the names for some of the DNS types listed above.

CALLBACK FUNCTIONS

       A  call  to the async getdns functions typically returns before any network or file I/O occurs. After the
       API marshalls all the needed information,  it  calls  the  callback  function  that  was  passed  by  the
       application.  The  callback  function  might  be called at any time, even before the calling function has
       returned. The API guarantees that the callback will be called exactly once unless  the  calling  function
       returned an error, in which case the callback function is never called.

       The getdns calling function calls the callback with the parameters defined as follows:

       typedef void (*getdns_callback_t)(
          getdns_context_t context,
          uint16_t callback_type,
          getdns_dict *response,
          void *userarg,
          getdns_transaction_t transaction_id)

       context see getdns_context (3)

       callback_type Supplies the reason for the callback.

          GETDNS_CALLBACK_COMPLETE The response has the requested data in it

          GETDNS_CALLBACK_CANCEL The calling program canceled the callback; response is NULL

          GETDNS_CALLBACK_TIMEOUT The requested action timed out; response is NULL

          GETDNS_CALLBACK_ERROR The requested action had an error; response is NULL

       response  A  response  object  with  the response data. This is described in the section titled "RESPONSE
          DATA" elsewhere in this manual page. The response object is part of the API's memory space,  and  will
          be freed by the API with the callback returns.

       userarg Identical to the userarg passed to the calling function.

       transaction_id  The  transaction  identified  assigned  by  the calling function, used to associate a DNS
          response to a specific DNS request.

       To cancel an outstanding callback, use the following function.

          getdns_return_t
          getdns_cancel_callback (getdns_context_t context, getdns_transaction_t transaction_id)

       This causes the API to call the callback with a callback_type of GETDNS_CALLBACK_CANCEL if  the  callback
       for  this  transaction_id has not already been called. The callback code for cancellation should clean up
       any memory related  to  the  identified  call,  such  as  to  deallocate  the  memory  for  the  userarg.
       getdns_cancel_callback()  may return immediately, even before the callback finishes its work and returns.
       Calling getdns_cancel_callback() with a transaction_id of a callback that has already been called  or  an
       unknown  transaction_id  returns  GETDNS_RETURN_UNKNOWN_TRANSACTION;  otherwise, getdns_cancel_callback()
       returns GETDNS_RETURN_GOOD.

FILES

EXAMPLES

       TBD

DIAGNOSTICS

       TBD

SEE ALSO

       getdns_address(3),    getdns_bindata(3),    getdns_context(3),     getdns_convert(3),     getdns_dict(3),
       getdns_general(3),   getdns_hostname(3),  getdns_list(3),  getdns_root_trust_anchor(3)  getdns_service(3)
       getdns_validate_dnssec(3)

REPORTING PROBLEMS

       Bug reports should be sent to the getdns-bugs@getdns.net

AUTHORS

       The getdns API was documented by Paul Hoffman.  This implementation of the getdns API was written by:

          Craig Despeaux, Verisign Inc.
          John Dickinson, Sinodun
          Sara Dickinson, Sinodun
          Neel Goyal, Verisign Inc.
          Shumon Huque, Verisign Labs
          Olaf Kolkman, NLnet Labs
          Allison Mankin, Verisign Inc. - Verisign Labs.
          Melinda Shore, No Mountain Software LLC
          Willem Toorop, NLnet Labs
          Gowri Visweswaran, Verisign Labs
          Wouter Wijngaards, NLnet Labs
          Glen Wiley, Verisign Inc.