getdns

Overview of getdns

• GitHub: https://github.com/getdnsapi/getdns

getdns is an implementation of a modern asynchronous DNS API; the specification was originally edited by Paul Hoffman. It is intended to make all types of DNS information easily available to application developers and non-DNS experts.

Why you might want getdns

Traditional access to DNS data from applications has several limitations:

• APIs require applications to have considerable sophistication about DNS data and data types

• Some kinds of data about the response (notably, the resource record set time to live) is not exposed via any API, so applications need to process raw protocol responses to get such data

• APIs are often blocking, meaning asynchronous access is not possible without some work

• Sophisticated uses of the DNS (things like IDNA and DNSSEC validation) require considerable application work, possibly by application developers with little experience with the vagaries of DNS.

getdns also provides an experimental DNS Privacy enabled client called 'stubby' - see below for more details.

Motivation for providing the API

The developers are of the opinion that DNSSEC offers a unique global infrastructure for establishing and enhancing cryptographic trust relations. With the development of this API we intend to offer application developers a modern and flexible interface that enables end-to-end trust in the DNS architecture, and which will inspire application developers to implement innovative security solutions in their applications.

API Documentation

Note that this implementation offers additional functionality to supplement that in the official getdns API. Some additions are convenient utility functions but other functionality is experimental prior to be being recommended for inclusion in the official API. The Doxygen documentation provides the details of the full API for this implementation.

License

This implementation is licensed under the New BSD License (BSD-new).

Obtaining and getting started with getdns

The project home page at getdnsapi.net provides documentation, binary downloads, and news regarding the getdns API implementation. This README file captures the goals and direction of the project and the current state of the implementation.

If you are just getting started with the library take a look at the section below that describes building and handling external dependencies for the library.

Examples

Once it is built you should take a look at spec/example to see how the library is used.

Download

Download the sources from our github repo or from getdnsapi.net and verify the download using the checksums (SHA1 or MD5) or using gpg to verify the signature. Our keys are available from the openpgp keyserver

• willem@nlnetlabs.nl, key id E5F8F8212F77A498

Releases

Release numbering follows the Semantic Versioning approach. The code is currently under active development.

The following requirements were met as conditions for the present release:

• code compiles cleanly on at least the primary target platforms: OSX, Linux (RHEL/CentOS, Ubuntu), FreeBSD
• examples must compile and run cleanly
• there must be clear documentation of supported and unsupported elements of the API

External Dependencies

If you are installing from packages, you have to install the library and also the library-devel (or -dev) for your package management system to get the the necessary compile time files.

External dependencies are linked outside the getdns API build tree (we rely on CMake to find them). We would like to keep the dependency tree short, see Minimising Dependancies for more details.

Required for all builds:

• libssl and libcrypto from the OpenSSL Project version 1.0.2 or later. Using OpenSSL 1.1 is recommended due to TSL 1.3 support.

Required for all builds that include recursive functionality:

• libunbound from NLnet Labs version 1.5.9 or later. (Note: linking to libunbound is not yet supported on Windows, see Windows 10)

Required for all builds that include IDN functionality:

• libidn2 from the FSF version 2.0.0 and higher.

Required to build the documentation:

• Doxygen is used to generate documentation; while this is not technically necessary for the build it makes things a lot more pleasant.

For example, to build on Ubuntu 18.04 or later, you would need the following packages for a full build:

# apt install build-essential libunbound-dev libidn2-dev libssl-dev cmake

Building

If you are building from git, you need to do the following before building:

# git submodule update --init

From release 1.6.0 getdns uses CMake (previous versions used autoconf/libtool). To build from this release and later use:

# cmake .
# make

If you are unfamiliar with CMake, see our CMake Quick Start for how to use CMake options to customise the getdns build.

As well as building the getdns library two other tools are installed by default:

• getdns_query: a command line test script wrapper for getdns. This can be used to quickly check the functionality of the library, see (#using-getdnsquery)
• getdns_server_mon: test DNS server function and capabilities

Additionally Stubby a DNS Privacy enabled client can also be built and installed by using the BUILD_STUBBY option when running cmake, see Stubby.

Minimizing dependencies

• getdns can be configured for stub resolution mode only with the ENABLE_STUB_ONLY option to cmake. This removes the dependency on libunbound.
• Currently getdns only offers two helper functions to deal with IDN: getdns_convert_ulabel_to_alabel and getdns_convert_alabel_to_ulabel. If you do not need these functions, getdns can be configured to compile without them by setting theUSE_LIBIDN2 option to cmake to OFF.
• When ENABLE_STUB_ONLY is ON, and USE_LIBIDN2 is OFF, getdns has only one dependency left, which is OpenSSL.

Extensions and Event loop dependencies

The implementation works with a variety of event loops, each built as a separate shared library. See this Doxygen page and [this man page](https://getdnsapi.net/documentation/manpages/#ASYNCHRONOUS USE) for more details.

• libevent. Note: the examples require this. libevent 2.x is required.
• libuv
• libev

Using getdns_query

Example test queries using getdns_query (pointed at Google Public DNS) and requesting the call_reporting extension which provides information on the transport and query time:

getdns_query -s example.com A @8.8.8.8 +return_call_reporting (UDP) getdns_query -s example.com A @8.8.8.8 -T +return_call_reporting (TCP) getdns_query -s example.com A @8.8.8.8 -L +return_call_reporting (TLS without authentication) getdns_query -s getdnsapi.net A +dnssec_return_status +return_call_reporting (DNSSEC)

Stubby

• Stubby is an implementation of a DNS Privacy enabled stub resolver that encrypts DNS queries using TLS. It is currently suitable for advanced/technical users - all feedback is welcome!
• Details on how to use Stubby can be found in the Stubby Reference Guide.
• Also see dnsprivacy.org for more information on DNS Privacy.

Experimental support for GnuTLS

A project to allow user selection of either OpenSSL or GnuTLS is currently a work in progress. At present a user may select to use GnuTLS for the majority of the supported functionality, however, OpenSSL is still required for some cryptographic functions.

Regression Tests

A suite of regression tests are included with the library, if you make changes or just want to sanity check things on your system take a look at src/test. You will need to install libcheck. The check library is also available from many of the package repositories for the more popular operating systems. Note: The tests currently do not run on Windows because of a dependancy on bash.

DNSSEC dependencies

For the library to be DNSSEC capable, it needs to know the root trust anchor. The library will try to load the root trust anchor from /etc/unbound/getdns-root.key by default. This file is expected to have one or more DS or DNSKEY resource records in presentation (i.e. zone file) format. Note that this is different than the format of BIND.keys.

Zero configuration DNSSEC

When the root trust anchor is not installed in the default location and a DNSSEC query is done, getdns will try to use the trust anchors published here: http://data.iana.org/root-anchors/root-anchors.xml . It will validate these anchors with the ICANN Certificate Authority certificate following the procedure described in [RFC7958]. The root-anchors.xml and root-anchors.p7s S/MIME signature will be cached in the $HOME/.getdns directory on Unixes, and the %appdata%\getdns directory on Windows.

When using trust-anchors from the root-anchors.xml file, getdns will track the keys in the root DNSKEY rrset and store a copy in $HOME/.getdns/root.key on Unixes, and %appdata%\getdns\root.key on Windows. Only when the KSK DNSKEY's change, a new version of root-anchors.xml is tried to be retrieved from data.iana.org.

A installed trust-anchor from the default location (/etc/unbound/getdns-root.key) that