diff --git a/README.md b/README.md index 28a4d6ab..623a786f 100644 --- a/README.md +++ b/README.md @@ -5,23 +5,35 @@ getdns * GitHub: -getdns is an implementation of a modern asynchronous DNS API specification -originally edited by Paul Hoffman. It is intended to make all types of DNS -information easily available to application developers and non-DNS experts. -The project home page at [getdnsapi.net](https://getdnsapi.net) provides -documentation, binary downloads and news regarding the getdns API -implementation. This implementation is licensed under the New BSD License -(BSD-new). +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. -This file captures the goals and direction of the project and the current state -of the implementation. +## Why you might want getdns -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. Once it is built you should take a look at src/examples to see how -the library is used. +Traditional access to DNS data from applications has several limitations: -## Download +* 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. + +## 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. + +## 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](https://getdnsapi.net) provides documentation, binary downloads, and news regarding the getdns API implementation. This 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. Once it is built you should take a look at src/examples to see how the library is used. + +# Download Download the sources from our [github repo](https://github.com/getdnsapi/getdns) or from [getdnsapi.net](https://getdnsapi.net) and verify the download using @@ -29,89 +41,28 @@ the checksums (SHA1 or MD5) or using gpg to verify the signature. Our keys are available from the [pgp keyservers](https://keyserver.pgp.com) * willem@nlnetlabs.nl, key id E5F8F8212F77A498 -* gwiley@verisign.com, key id 9DC3D572A6B73532 -## Mailing lists +# Releases -We have a [getdns users list](https://getdnsapi.net/mailman/listinfo/spec) for this implementation. - -The [getdns-api mailing list](https://getdnsapi.net/mailman/listinfo/spec) -is a good place to engage in discussions regarding the design of the API. - -## 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 way that enables end-to-end trust in the DNS architecture -and will inspire application developers towards innovative security solutions -in their applications. - -## Goals - -The goals of this implementation of the getdns API are: - -* Provide an open source implementation, in C, of the formally described getdns API by getdns API team at -* Initial support for FreeBSD, OSX, Linux (CentOS/RHEL, Ubuntu) via functional "configure" script -* Initial support for Windows 8.1 -* Initial support to include the Android platform -* Include examples and tests as part of the build -* Document code using doxygen -* Leverage github as much as possible for project coordination -* Coding style/standards follow the BSD coding style - -Non-goals (things we will not be doing at least initially) include: -* implementation of the traditional DNS related routines (gethostbyname, etc.) - -## Official and Additional API - -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 'Modules' page in the doxygen documentation provides a guide to both the -official API and the additional functionality. - -## Language Bindings - -In parallel, the team is actively developing bindings for various languages. -For more information, visit the -[wiki](https://github.com/getdnsapi/getdns/wiki/Language-Bindings). - - -Releases -======== Release numbering follows the [Semantic Versioning](http://semver.org/) 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, RHEL/CentOS Linux, FreeBSD -* examples must compile and run clean -* clearly document supported/unsupported elements of the API +* examples must compile and run cleanly +* there must be clear documentation of supported and unsupported elements of the API +# Building and External Dependencies -Tickets/Bug Reports -=================== -Tickets and bug reports should be reported via the [GitHub issues list](https://github.com/getdnsapi/getdns/issues). - -Additionally, we have a mailing list at users@getdns.net. - - -Building/External Dependencies -============================== - -External dependencies are linked outside the getdns API build tree (we rely on configure to find them). We would like to keep the dependency tree short. -Please refer to section for building on Windows for separate dependency and build instructions. +External dependencies are linked outside the getdns API build tree (we rely on configure to find them). We would like to keep the dependency tree short. Please refer to section for building on Windows for separate dependency and build instructions for that platform. * [libunbound from NLnet Labs](https://unbound.net/) version 1.4.16 or later. -* [libidn from the FSF](https://www.gnu.org/software/libidn/) version 1. +* [libidn from the FSF](https://www.gnu.org/software/libidn/) version 1. (Note that the libidn version means the conversions between A-labels and U-labels may permit conversion of formally invalid labels under IDNA2008.) * [libssl and libcrypto from the OpenSSL Project](https://www.openssl.org/) version 0.9.7 or later. (Note: version 1.0.1 or later is required for TLS support, version 1.0.2 or later is required for TLS hostname authentication) -* Doxygen is used to generate documentation, while this is not technically necessary for the build it makes things a lot more pleasant. +* Doxygen is used to generate documentation; while this is not technically necessary for the build it makes things a lot more pleasant. -You have to install the library and also the library-devel (or -dev) for your -package management system to install the compile time files. If you checked -out our git you need to copy the libtool helper scripts and rebuild configure -with: +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. If you checked out from git you need to copy the libtool helper scripts and rebuild configure thus: # libtoolize -ci (use glibtoolize for OS X, libtool is installed as glibtool to avoid name conflict on OS X) # autoreconf -fi @@ -126,9 +77,9 @@ If you want to use the getdns_query command line wrapper script for testing or t # make getdns_query -## Minimal dependencies +## Minimizing dependencies -* getdns can be configured for stub resolution mode only with the `--enable-stub-only` option to configure. This removed the dependency on `libunbound`. +* getdns can be configured for stub resolution mode only with the `--enable-stub-only` option to configure. 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 with the `--without-libidn` option to configure. * When both `--enable-stub-only` and `--without-libidn` options are used, getdns has only one dependency left, which is OpenSSL. @@ -140,18 +91,15 @@ The implementation works with a variety of event loops, each built as a separate * [libuv](https://github.com/joyent/libuv) * [libev](http://software.schmorp.de/pkg/libev.html) -NOTE: The current Windows implementation does not support the above. - ## 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](https://libcheck.github.io/check/). The check library is also available from -many of the package repositories for the more popular operating systems. +to install [libcheck](https://libcheck.github.io/check/). The check library is also available from many of the package repositories for the more popular operating systems. -NOTE: The current Windows implementation does not support the above. +The regression tests do not work with --enable-stub-only. -## DNSSEC +## 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 @@ -167,7 +115,49 @@ execute the following steps as root: # mkdir -p /etc/unbound # unbound-anchor -a /etc/unbound/getdns-root.key -# Unsupported Features +Support +======= + +# Mailing lists + +We have a [getdns users list](https://getdnsapi.net/mailman/listinfo/users) for this implementation. + +The [getdns-api mailing list](https://getdnsapi.net/mailman/listinfo/spec) is a good place to engage in discussions regarding the design of the API. + +# Tickets/Bug Reports + +Tickets and bug reports should be reported via the [GitHub issues list](https://github.com/getdnsapi/getdns/issues). + +Features of this release +======================== + +# Goals + +The goals of this implementation of the getdns API are: + +* Provide an open source implementation, in C, of the formally described getdns API by getdns API team at +* Support FreeBSD, OSX, Linux (CentOS/RHEL, Ubuntu) via functional "configure" script +* Support Windows 8.1 +* Include examples and tests as part of the build +* Document code using doxygen +* Leverage github as much as possible for project coordination +* Follow the BSD coding style/standards + +Non-goals (things we will not be doing at least initially) include: + +* implementation of the traditional DNS related routines (gethostbyname, etc.) + +# Official and Additional API + +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 'Modules' page in the doxygen documentation provides a guide to both the official API and the additional functionality. + +# Language Bindings + +In parallel, the team is actively developing bindings for various languages. +For more information, visit the +[wiki](https://github.com/getdnsapi/getdns/wiki/Language-Bindings). + +# Unsupported getDNS Features The following API calls are documented in getDNS but *not supported* by the implementation at this time: @@ -175,7 +165,7 @@ The following API calls are documented in getDNS but *not supported* by the impl * Detecting changes to resolv.conf and hosts * MDNS, NIS and NetBIOS namespaces (only DNS and LOCALFILES are supported) -## Non-uniform implementation +## Minor omissions The following minor implementation omissions are noted: @@ -189,12 +179,7 @@ Stub mode does not support: # Known Issues -There are a few known issues which we have summarized below - the most recent -and helpful list is being maintained in the git issues list in the repository. -Other known issues are being managed in the git repository issue list. - -* When doing a synchronous lookup with a context that has outstanding asynchronous lookups, the callbacks for the asynchronous lookups might get called as a side effect of the synchronous lookup. - +* None # Supported Platforms @@ -203,9 +188,9 @@ The primary platforms targeted are Linux and FreeBSD, other platform are support * RHEL/CentOS 6.4 * OSX 10.8 * Ubuntu 14.04 -* Microsoft Windows 8.1 (initial support for DNSSEC but no TLS provided for version 0.5.1) +* Microsoft Windows 8.1 -We intend to add Android and other platforms to the releases as we have time to port it. +We intend to add Android and other platforms to future releases as we have time to port it. ## Platform Specific Build Reports @@ -220,9 +205,9 @@ If you are using FreeBSD 10 getdns can be intalled via 'pkg install getdns'. ### CentOS/RHEL 6.5 -We rely on the most excellent package manager fpm to build the linux packages which +We rely on the most excellent package manager fpm to build the linux packages, which means that the packaging platform requires ruby 2.1.0. There are other ways to -build the packages, this is simplythe one we chose to use. +build the packages; this is simply the one we chose to use. # cat /etc/redhat-release CentOS release 6.5 (Final) @@ -258,7 +243,7 @@ build the packages, this is simplythe one we chose to use. create dmg A self-compiled version of OpenSSL or the version installed via Homebrew is required. - Note: If using a self-compiled version manual configuration of certificates into /usr/local/etc/openssl/certs is required for TLS authentication to work. + Note: If using a self-compiled version, manual configuration of certificates into /usr/local/etc/openssl/certs is required for TLS authentication to work. #### Homebrew @@ -270,12 +255,9 @@ Note that in order to compile the examples, the `--with-libevent` switch is requ As of the 0.2.0 release, when installing via Homebrew, the trust anchor is expected to be located at `$(brew --prefix)/etc/getdns-root.key`. Additionally, the OpenSSL library installed by Homebrew is linked against. Note that the Homebrew OpenSSL installation clones the Keychain certificates to the default OpenSSL location so TLS certificate authentication should work out of the box. - ### Microsoft Windows 8.1 -This section has some Windows specific build instructions. - -Build tested using the following: +The build has been tested using the following: 32 bit only Mingw: [Mingw(3.21.0) and Msys 1.0](http://www.mingw.org/) on Windows 8.1 32 bit build on a 64 bit Mingw [Download latest from: http://mingw-w64.org/doku.php/download/mingw-builds and http://msys2.github.io/]. IMPORTANT: Install tested ONLY on the "x86_64" for 64-bit installer of msys2. @@ -315,6 +297,7 @@ To configure: Contributors ============ +* Claus Assman * Theogene Bucuti * Andrew Cathrow, Verisign Labs * Neil Cook @@ -322,26 +305,35 @@ Contributors * Craig Despeaux, Verisign, Inc. * John Dickinson, Sinodun * Sara Dickinson, Sinodun +* Robert Edmonds * Angelique Finan, Verisign, Inc. +* Simson Garfinkel * Daniel Kahn Gillmor * Neel Goyal, Verisign, Inc. * Bryan Graham, Verisign, Inc. +* Robert Groenenberg * Paul Hoffman * Scott Hollenbeck, Verising, Inc. * Shumon Huque, Verisign Labs +* Jelte Janssen +* Guillem Jover * Shane Kerr * Anthony Kirby * Olaf Kolkman, NLnet Labs * Sanjay Mahurpawar, Verisign, Inc. * Allison Mankin, Verisign, Inc. - Verisign Labs. * Sai Mogali, Verisign, Inc. +* Linus Nordberg * Benno Overeinder, NLnet Labs * Joel Purra +* Tom Pusateri * Prithvi Ranganath, Verisign, Inc. * Rushi Shah, Verisign, Inc. * Vinay Soni, Verisign, Inc. * Melinda Shore, No Mountain Software LLC * Bob Steagall, Verisign, Inc. +* Andrew Sullivan +* Ondřej Surý * Willem Toorop, NLnet Labs * Gowri Visweswaran, Verisign Labs * Wouter Wijngaards, NLnet Labs diff --git a/project-doc/release-procedure.txt b/project-doc/release-procedure.txt index 6ffe4749..6438a4cf 100644 --- a/project-doc/release-procedure.txt +++ b/project-doc/release-procedure.txt @@ -8,8 +8,8 @@ update this document and share it with us. is cut nothing should be committed to the release branch (make a new release) - create a release branch - in git repository named for the release, e.g. "v0.1.2" - we do this because folks may want to continue to work in the master branch + in git repository named for the release, e.g. "release/v1.0.0-b3" + we do this because folks may want to continue to work in the develop branch and be free to commit changes without injuring the release process. Since building and testing binaries for a release takes a few days we don't want to force changes to queue up. @@ -25,84 +25,47 @@ update this document and share it with us. use a working directory with lots of cruft - crap will find its way into the release and embarass you: - # git clone -b v0.1.2 https://github.com/getdnsapi/getdns.git getdns-0.1.2 + # git clone -b v1.0.0-b3 https://github.com/getdnsapi/getdns.git getdns-1.0.0-b3 - update files to reflect release number/date ./README.md ./ChangeLog - ./configure.ac (AC_INIT) - ./src/Makefile.in (-version-info, follow libtool guidelines) + ./configure.ac + - Watch for and change values: + - AC_INIT + - RELEASE_CANDIDATE + - GETDNS_NUMERIC_VERSION + - API_VERSION and API_NUMERUC_VERSION + - read section "Library version" and + update GETDNS_LIBVERSION carefully! - # make clean - # autoreconf + # autoreconf -fi commit these changes to the release branch # git commit -a -m "release number and date updates" # git push -- prepare to build binaries for each target platform - you need to remove libs and headers that might be lingering from previous builds - to avoid accidentally including the wrong headers or linking the wrong libs +- Do the unit tests on as many different systems as you can. They must all + be able to fulfill all requirements. So they have libidn, libev, libuv, libevent, + latest libunbound, latest openssl (at least 1.0.2) lastest clang compiler + (for static analysis), latest valigrind. Then run: - - create clean local repo + # ${GETDNS_SRCDIR}/src/test/tpkg/run-all.sh -- build source distribution tar + and evaluate the results. + +- build and sign source distribution tarball: + # rm -fr * + # git reset --hard + # git submodule update --init + # autoreconf -fi + # libtoolize -ci # ./configure - # make dist - # openssl sha1 getdns-0.1.2.tar.gz > getdns-0.1.2.tar.gz.sha1 - # openssl md5 getdns-0.1.2.tar.gz > getdns-0.1.2.tar.gz.md5 - # gpg --armor --detach-sig --default-key gwiley@verisign.com getdns-0.1.2.tar.gz + # make pub - test the resulting tar by building it and running the regression tests - -- build CentOS binary - # tar -xzvf getdns-0.1.2.tar.gz - # cd getdns-0.1.2 - # ./configure --with-libevent --prefix=$HOME/build - # make - # make install - # cd ~/build - - fix the libdir path in the *.la files to point to /usr/local/lib - - fix the dependency_libs entry in the *.la files to point to /usr/local/lib - # fpm -x "*.la" -a native -s dir --rpm-sign -t rpm -n getdns -v 0.1.2 -d "unbound" -d "ldns" -d "libevent" -d "libidn" --prefix /usr/local --vendor "Verisign Inc., NLnet Labs" --license "BSD New" --url "http://www.getdnsapi.net" --description "Modern asynchronous API to the DNS" . - - make sure your signing key is in the keyring on the build machine - - contents of ~/.rpmmacros - %_signature gpg - %_gpg_path /root/.gnupg - %_gpg_name A6B73532 - %_gpgbin /usr/bin/gpg - - - name the rpm and checksum files something like this: - getdns-0.1.3-1.CentOS_6_5.x86_64.rpm - getdns-0.1.3-1.CentOS_6_5.x86_64.rpm.sha1 - getdns-0.1.3-1.CentOS_6_5.x86_64.rpm.md5 - - check the signature - - install - - test - -- build OSX binary disk image - - - build code (no additional libraries, note that regression tests will not build) - if you are building a simple binary tar then something like this works - # ./configure --prefix=/Users/gwiley/getdnsox/export - # make - # make install - # tar -C /Users/gwiley/getdnsosx/export -cvf getdns-0.1.2.tar * - - - build code (with libevent) - # ./configure --with-libevent2 - - - run regression tests and verify that alls well - - if you have do do anything even mildly interesting to get the build or install to - work then we either have to add it to the README.md or, preferably, fix it - and update the branch - - Be careful about tool sets loaded on your build hosts. You may have 'solved' - problems while you are working that mask issues with the build for more typical - users - this is why we want to build on hosts that are representative of - our users. + on as many different systems as you can. - install on each target platform - make sure and use a user that was NOT used for the build, this will uncover @@ -114,55 +77,34 @@ update this document and share it with us. - merge branch changes back into master - once all binaries are built and tested clean, create source tar ball - and the actual package for each platform you may need to run this as root to permit the chown # make clean - # make dist - generates getdns-0.1.2.tar.gz + # make pub + generates getdns-1.0.0-b3.tar.gz + checksums + signatures -- sign each binary/source tar using one or more developers keys - - make sure that the keys you use to sign the release are also up to date - on the getdnsapi.net site +- upload source tarball and checsums and signatures to the getdnsapi.net site -- generate checksums for each binary/source tar + # scp getdns-1.0.0-b3.tar.gz* getdnsapi.net:/usr/local/www/apache24/data/dist -- upload source and binaries to the getdnsapi.net site +- Create and push signed tags to github -- create a release in the github repository - - from the main repo choose 'releases' - - choose 'Draft a new release' - - use tag v0.x.y to match the branch being released - - for a release name use v0.x.y - - for description cut/paste the ChangeLog entry - - check the 'pre-release' checkbox (unless this is a production release) + # git -s v1.0.0-b3 + # git push --tags - update getdnsapi.net web site - - push binaries to getdnsapi.net + - create a getdns-1.0.0-b3.tar.gz.changelog and + getdns-1.0.0-b3.tar.gz.html in /usr/local/www/apache24/data/dist - - news entry for the release - /usr/local/www/apache24/data/news.html - - download links and checksums - /usr/local/www/apache24/data/frontpage.html + with the content of ChangeLog + and the release announcement respectively. + - Edit /usr/local/www/apache24/build_site.py. + Change latest entry and create a new news_item entry. - rebuild website - # ./build.sh + # cd /usr/local/www/apache24 + # ./build_site.py - announce message to - getdns mailing list - stub-resolvers mailing list - Verisign internal via the matrix - -- update the + users@getdnsapi.net, spec@getdnsapi.net and maintainers@nlnetlabs.nl -List of Build Targets ---------------------- -The naming conventions for each of these build products are specific to the -platform they target. The result is that the naming seems a little inconsistent, -however I felt that it is best to follow naming standards for the platform rather -than try to impose a project specific standard across platforms. - -- source tar: getdns-0.1.2.tar.gz -- OSX binary package: getdns-0.1.2-OSX_10_8.dmg -- RHEL/CentOS: getdns-0.1.0-1.CentOS_6_5.x86_64.rpm -- Debian/Ubuntu: diff --git a/src/getdns/getdns_extra.h.in b/src/getdns/getdns_extra.h.in index d48d13b6..9c973a5e 100644 --- a/src/getdns/getdns_extra.h.in +++ b/src/getdns/getdns_extra.h.in @@ -399,11 +399,11 @@ const char *getdns_get_errorstr_by_id(uint16_t err); /* dict util */ /* set a string as bindata */ -getdns_return_t getdns_dict_util_set_string(struct getdns_dict * dict, +getdns_return_t getdns_dict_util_set_string(getdns_dict * dict, char *name, const char *value); /* get a string from a dict. the result must be freed if valid */ -getdns_return_t getdns_dict_util_get_string(struct getdns_dict * dict, +getdns_return_t getdns_dict_util_get_string(getdns_dict * dict, char *name, char **result); /** diff --git a/src/util-internal.c b/src/util-internal.c index 0bcf9d23..dfca9603 100644 --- a/src/util-internal.c +++ b/src/util-internal.c @@ -54,7 +54,7 @@ getdns_return_t -getdns_dict_util_get_string(struct getdns_dict * dict, char *name, char **result) +getdns_dict_util_get_string(getdns_dict * dict, char *name, char **result) { struct getdns_bindata *bindata = NULL; if (!result) {