interesting
/
getdns
mirror of https://github.com/getdnsapi/getdns.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'develop' into release/v1.1.0a1

This commit is contained in:
Willem Toorop 2016-07-13 15:55:17 +02:00
parent 31f1375b8e a55c8ab377
commit 504cb8a783
16 changed files with 519 additions and 375 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
README.md
View File

@ -1,17 +1,28 @@
getdns API getdns
========== ======
# Overview of getdns
* Date: 2016-03-24
* GitHub: <https://github.com/getdnsapi/getdns> * GitHub: <https://github.com/getdnsapi/getdns>
getdns is an implementation of a modern asynchronous DNS API specification 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 originally edited by Paul Hoffman. It is intended to make all types of DNS
information easily available to application developers and non-DNS experts. information easily available to application developers and non-DNS experts.
The project home page at [getdnsapi.net](https://getdnsapi.net) provides The project home page at [getdnsapi.net](https://getdnsapi.net) provides
documentation, binary downloads and new regarding the getdns API documentation, binary downloads and news regarding the getdns API
implementation. This implementation is licensed under the New BSD License implementation. This implementation is licensed under the New BSD License
(BSD-new). (BSD-new).
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) Download the sources from our [github repo](https://github.com/getdnsapi/getdns)
or from [getdnsapi.net](https://getdnsapi.net) and verify the download using or from [getdnsapi.net](https://getdnsapi.net) and verify the download using
the checksums (SHA1 or MD5) or using gpg to verify the signature. Our keys are the checksums (SHA1 or MD5) or using gpg to verify the signature. Our keys are
@ -20,18 +31,23 @@ available from the [pgp keyservers](https://keyserver.pgp.com)
* willem@nlnetlabs.nl, key id E5F8F8212F77A498 * willem@nlnetlabs.nl, key id E5F8F8212F77A498
* gwiley@verisign.com, key id 9DC3D572A6B73532 * gwiley@verisign.com, key id 9DC3D572A6B73532
We have a [users list](https://getdnsapi.net/mailman/listinfo/spec) for this implementation. ## Mailing lists
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) 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. is a good place to engage in discussions regarding the design of the API.
If you are just getting started with the library take a look at the section ## Motivation for providing the API
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.
This file captures the goals and direction of the project and the current state The developers are of the opinion that DNSSEC offers a unique global
of the implementation. 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: The goals of this implementation of the getdns API are:
@ -47,22 +63,20 @@ The goals of this implementation of the getdns API are:
Non-goals (things we will not be doing at least initially) include: Non-goals (things we will not be doing at least initially) include:
* implementation of the traditional DNS related routines (gethostbyname, etc.) * 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 ## Language Bindings
In parallel, the team is actively developing bindings for various languages. In parallel, the team is actively developing bindings for various languages.
For more information, visit the For more information, visit the
[wiki](https://github.com/getdnsapi/getdns/wiki/Language-Bindings). [wiki](https://github.com/getdnsapi/getdns/wiki/Language-Bindings).
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.
Releases Releases
======== ========
@ -102,6 +116,16 @@ with:
# libtoolize -ci (use glibtoolize for OS X, libtool is installed as glibtool to avoid name conflict on OS X) # libtoolize -ci (use glibtoolize for OS X, libtool is installed as glibtool to avoid name conflict on OS X)
# autoreconf -fi # autoreconf -fi
If you want to make use of the configuration files that utilise a JSON-like format, you must do
# git submodule update --init
before building.
If you want to use the getdns_query command line wrapper script for testing or to enable getdns as a daemon then you must build it using
# make getdns_query
## Minimal dependencies ## Minimal 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 removed the dependency on `libunbound`.
@ -151,6 +175,18 @@ The following API calls are documented in getDNS but *not supported* by the impl
* Detecting changes to resolv.conf and hosts * Detecting changes to resolv.conf and hosts
* MDNS, NIS and NetBIOS namespaces (only DNS and LOCALFILES are supported) * MDNS, NIS and NetBIOS namespaces (only DNS and LOCALFILES are supported)
## Non-uniform implementation
The following minor implementation omissions are noted:
Recursive mode does not support:
* TLS as a transport
* Non-zero connection idle timeouts or query pipelining
Stub mode does not support:
* Non zero idle timeouts for synchronous calls
* Limit on number of outstanding queries
# Known Issues # Known Issues
There are a few known issues which we have summarized below - the most recent There are a few known issues which we have summarized below - the most recent
@ -277,7 +313,6 @@ To configure:
./getdns_query.exe -s gmadkat.com A -l L @185.49.141.37 +return_call_reporting (TLS without authentication) ./getdns_query.exe -s gmadkat.com A -l L @185.49.141.37 +return_call_reporting (TLS without authentication)
./getdns_query.exe -s www.huque.com A +dnssec_return_status +return_call_reporting (DNSSEC) ./getdns_query.exe -s www.huque.com A +dnssec_return_status +return_call_reporting (DNSSEC)
Contributors Contributors
============ ============
* Theogene Bucuti * Theogene Bucuti
@ -313,6 +348,7 @@ Contributors
* Glen Wiley, Verisign, Inc. * Glen Wiley, Verisign, Inc.
* Paul Wouters * Paul Wouters
Acknowledgements Acknowledgements
================ ================
The development team explicitly acknowledges Paul Hoffman for his initiative and efforts to develop a consensus based DNS API. We would like to thank the participants of the [mailing list](https://getdnsapi.net/mailman/listinfo/spec) for their contributions. The development team explicitly acknowledges Paul Hoffman for his initiative and efforts to develop a consensus based DNS API. We would like to thank the participants of the [mailing list](https://getdnsapi.net/mailman/listinfo/spec) for their contributions.

19
src/Doxyfile.in
View File

@ -50,7 +50,7 @@ DOXYFILE_ENCODING = UTF-8
# identify the project. Note that if you do not use Doxywizard you need # identify the project. Note that if you do not use Doxywizard you need
# to put quotes around the project name if it contains spaces. # to put quotes around the project name if it contains spaces.
PROJECT_NAME = "getdns API" PROJECT_NAME = "getdns"
# The PROJECT_NUMBER tag can be used to enter a project or revision number. # The PROJECT_NUMBER tag can be used to enter a project or revision number.
# This could be handy for archiving the generated documentation or # This could be handy for archiving the generated documentation or
@ -62,7 +62,7 @@ PROJECT_NUMBER = @PACKAGE_VERSION@
# for a project that appears at the top of each page and should give viewer # for a project that appears at the top of each page and should give viewer
# a quick idea about the purpose of the project. Keep the description short. # a quick idea about the purpose of the project. Keep the description short.
PROJECT_BRIEF = "A modern asynchronous API for fetching DNS data" PROJECT_BRIEF = "An implementation of the getdns API - a modern asynchronous API for fetching DNS data"
# With the PROJECT_LOGO tag one can specify an logo or icon that is # With the PROJECT_LOGO tag one can specify an logo or icon that is
# included in the documentation. The maximum height of the logo should not # included in the documentation. The maximum height of the logo should not
@ -692,12 +692,15 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories # directories like "/usr/src/myproject". Separate the files or directories
# with spaces. # with spaces.
INPUT = @srcdir@ \ INPUT = @srcdir@/getdns/ \
getdns/ \ getdns/getdns.h \
@srcdir@/getdns/ \ getdns/getdns_extra.h \
@srcdir@/example/ \
@srcdir@/test/ \
@srcdir@/../README.md @srcdir@/../README.md
# @srcdir@/../spec/example/ \
# getdns/ \
# @srcdir@ \
# @srcdir@/test/ \
# This tag can be used to specify the character encoding of the source files # This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@ -820,7 +823,7 @@ FILTER_SOURCE_PATTERNS =
# This can be useful if you have a project on for instance GitHub and want reuse # This can be useful if you have a project on for instance GitHub and want reuse
# the introduction page also for the doxygen output. # the introduction page also for the doxygen output.
USE_MDFILE_AS_MAINPAGE = ../README.md USE_MDFILE_AS_MAINPAGE = @srcdir@/../README.md
#--------------------------------------------------------------------------- #---------------------------------------------------------------------------
# configuration options related to source browsing # configuration options related to source browsing

16
src/general.c
View File

@ -665,7 +665,7 @@ getdns_return_t
getdns_general(getdns_context *context, getdns_general(getdns_context *context,
const char *name, uint16_t request_type, getdns_dict *extensions, const char *name, uint16_t request_type, getdns_dict *extensions,
void *userarg, getdns_transaction_t * transaction_id, void *userarg, getdns_transaction_t * transaction_id,
getdns_callback_t callback) getdns_callback_t callbackfn)
{ {
getdns_return_t r; getdns_return_t r;
getdns_network_req *netreq = NULL; getdns_network_req *netreq = NULL;
@ -673,7 +673,7 @@ getdns_general(getdns_context *context,
if (!context) return GETDNS_RETURN_INVALID_PARAMETER; if (!context) return GETDNS_RETURN_INVALID_PARAMETER;
r = _getdns_general_loop(context, context->extension, r = _getdns_general_loop(context, context->extension,
name, request_type, extensions, name, request_type, extensions,
userarg, &netreq, callback, NULL); userarg, &netreq, callbackfn, NULL);
if (netreq && transaction_id) if (netreq && transaction_id)
*transaction_id = netreq->owner->trans_id; *transaction_id = netreq->owner->trans_id;
return r; return r;
@ -686,12 +686,12 @@ getdns_general(getdns_context *context,
getdns_return_t getdns_return_t
getdns_address(getdns_context *context, getdns_address(getdns_context *context,
const char *name, getdns_dict *extensions, void *userarg, const char *name, getdns_dict *extensions, void *userarg,
getdns_transaction_t *transaction_id, getdns_callback_t callback) getdns_transaction_t *transaction_id, getdns_callback_t callbackfn)
{ {
if (!context) return GETDNS_RETURN_INVALID_PARAMETER; if (!context) return GETDNS_RETURN_INVALID_PARAMETER;
return _getdns_address_loop(context, context->extension, return _getdns_address_loop(context, context->extension,
name, extensions, userarg, name, extensions, userarg,
transaction_id, callback); transaction_id, callbackfn);
} /* getdns_address */ } /* getdns_address */
/* /*
@ -701,11 +701,11 @@ getdns_address(getdns_context *context,
getdns_return_t getdns_return_t
getdns_hostname(getdns_context *context, getdns_hostname(getdns_context *context,
getdns_dict *address, getdns_dict *extensions, void *userarg, getdns_dict *address, getdns_dict *extensions, void *userarg,
getdns_transaction_t *transaction_id, getdns_callback_t callback) getdns_transaction_t *transaction_id, getdns_callback_t callbackfn)
{ {
if (!context) return GETDNS_RETURN_INVALID_PARAMETER; if (!context) return GETDNS_RETURN_INVALID_PARAMETER;
return _getdns_hostname_loop(context, context->extension, return _getdns_hostname_loop(context, context->extension,
address, extensions, userarg, transaction_id, callback); address, extensions, userarg, transaction_id, callbackfn);
} /* getdns_hostname */ } /* getdns_hostname */
/* /*
@ -715,11 +715,11 @@ getdns_hostname(getdns_context *context,
getdns_return_t getdns_return_t
getdns_service(getdns_context *context, getdns_service(getdns_context *context,
const char *name, getdns_dict *extensions, void *userarg, const char *name, getdns_dict *extensions, void *userarg,
getdns_transaction_t *transaction_id, getdns_callback_t callback) getdns_transaction_t *transaction_id, getdns_callback_t callbackfn)
{ {
if (!context) return GETDNS_RETURN_INVALID_PARAMETER; if (!context) return GETDNS_RETURN_INVALID_PARAMETER;
return _getdns_service_loop(context, context->extension, return _getdns_service_loop(context, context->extension,
name, extensions, userarg, transaction_id, callback); name, extensions, userarg, transaction_id, callbackfn);
} /* getdns_service */ } /* getdns_service */
/* getdns_general.c */ /* getdns_general.c */

151
src/getdns/getdns.h.in
View File

@ -47,8 +47,17 @@ extern "C" {
#define GETDNS_COMPILATION_COMMENT "@GETDNS_COMPILATION_COMMENT@" #define GETDNS_COMPILATION_COMMENT "@GETDNS_COMPILATION_COMMENT@"
/** \defgroup getdnsAPI Official getdns API
* @{
*/
/** \defgroup valuesandtexts Values and texts
* @{
*/
/** /**
* \defgroup returntypes Return values * \defgroup returntypestext Return values and texts
* @{ * @{
*/ */
typedef enum getdns_return_t { typedef enum getdns_return_t {
@ -68,13 +77,8 @@ typedef enum getdns_return_t {
GETDNS_RETURN_INVALID_PARAMETER = 311, GETDNS_RETURN_INVALID_PARAMETER = 311,
GETDNS_RETURN_NOT_IMPLEMENTED = 312 GETDNS_RETURN_NOT_IMPLEMENTED = 312
} getdns_return_t; } getdns_return_t;
/** @}
*/
/**
* \defgroup returntypestext Return values texts
* @{
*/
#define GETDNS_RETURN_GOOD_TEXT "Good" #define GETDNS_RETURN_GOOD_TEXT "Good"
#define GETDNS_RETURN_GENERIC_ERROR_TEXT "Generic error" #define GETDNS_RETURN_GENERIC_ERROR_TEXT "Generic error"
#define GETDNS_RETURN_BAD_DOMAIN_NAME_TEXT "Badly-formed domain name in first argument" #define GETDNS_RETURN_BAD_DOMAIN_NAME_TEXT "Badly-formed domain name in first argument"
@ -113,7 +117,7 @@ typedef enum getdns_return_t {
/** /**
* \defgroup namespacetypes Namespace types * \defgroup namespacetypestext Namespace types and texts
* @{ * @{
*/ */
typedef enum getdns_namespace_t { typedef enum getdns_namespace_t {
@ -123,13 +127,8 @@ typedef enum getdns_namespace_t {
GETDNS_NAMESPACE_MDNS = 503, GETDNS_NAMESPACE_MDNS = 503,
GETDNS_NAMESPACE_NIS = 504 GETDNS_NAMESPACE_NIS = 504
} getdns_namespace_t; } getdns_namespace_t;
/** @}
*/
/**
* \defgroup namespacetypestext Namespace types texts
* @{
*/
#define GETDNS_NAMESPACE_DNS_TEXT "See getdns_context_set_namespaces()" #define GETDNS_NAMESPACE_DNS_TEXT "See getdns_context_set_namespaces()"
#define GETDNS_NAMESPACE_LOCALNAMES_TEXT "See getdns_context_set_namespaces()" #define GETDNS_NAMESPACE_LOCALNAMES_TEXT "See getdns_context_set_namespaces()"
#define GETDNS_NAMESPACE_NETBIOS_TEXT "See getdns_context_set_namespaces()" #define GETDNS_NAMESPACE_NETBIOS_TEXT "See getdns_context_set_namespaces()"
@ -140,20 +139,15 @@ typedef enum getdns_namespace_t {
/** /**
* \defgroup resolutiontypes Resolution types * \defgroup resolutiontypestext Resolution types and texts
* @{ * @{
*/ */
typedef enum getdns_resolution_t { typedef enum getdns_resolution_t {
GETDNS_RESOLUTION_STUB = 520, GETDNS_RESOLUTION_STUB = 520,
GETDNS_RESOLUTION_RECURSING = 521 GETDNS_RESOLUTION_RECURSING = 521
} getdns_resolution_t; } getdns_resolution_t;
/** @}
*/
/**
* \defgroup resolutiontypestext Resolution types texts
* @{
*/
#define GETDNS_RESOLUTION_STUB_TEXT "See getdns_context_set_resolution_type()" #define GETDNS_RESOLUTION_STUB_TEXT "See getdns_context_set_resolution_type()"
#define GETDNS_RESOLUTION_RECURSING_TEXT "See getdns_context_set_resolution_type()" #define GETDNS_RESOLUTION_RECURSING_TEXT "See getdns_context_set_resolution_type()"
/** @} /** @}
@ -161,20 +155,15 @@ typedef enum getdns_resolution_t {
/** /**
* \defgroup redirectpolicytype Redirect policies * \defgroup redirectpoliciestext Redirect policies and texts
* @{ * @{
*/ */
typedef enum getdns_redirects_t { typedef enum getdns_redirects_t {
GETDNS_REDIRECTS_FOLLOW = 530, GETDNS_REDIRECTS_FOLLOW = 530,
GETDNS_REDIRECTS_DO_NOT_FOLLOW = 531 GETDNS_REDIRECTS_DO_NOT_FOLLOW = 531
} getdns_redirects_t; } getdns_redirects_t;
/** @}
*/
/**
* \defgroup redirectpoliciestext Redirect policies texts
* @{
*/
#define GETDNS_REDIRECTS_FOLLOW_TEXT "See getdns_context_set_follow_redirects()" #define GETDNS_REDIRECTS_FOLLOW_TEXT "See getdns_context_set_follow_redirects()"
#define GETDNS_REDIRECTS_DO_NOT_FOLLOW_TEXT "See getdns_context_set_follow_redirects()" #define GETDNS_REDIRECTS_DO_NOT_FOLLOW_TEXT "See getdns_context_set_follow_redirects()"
/** @} /** @}
@ -182,7 +171,7 @@ typedef enum getdns_redirects_t {
/** /**
* \defgroup transporttypes Transport arrangements * \defgroup transporttypestext Transport arrangements and texts
* @{ * @{
*/ */
typedef enum getdns_transport_t { typedef enum getdns_transport_t {
@ -191,13 +180,7 @@ typedef enum getdns_transport_t {
GETDNS_TRANSPORT_TCP_ONLY = 542, GETDNS_TRANSPORT_TCP_ONLY = 542,
GETDNS_TRANSPORT_TCP_ONLY_KEEP_CONNECTIONS_OPEN = 543 GETDNS_TRANSPORT_TCP_ONLY_KEEP_CONNECTIONS_OPEN = 543
} getdns_transport_t; } getdns_transport_t;
/** @}
*/
/**
* \defgroup transporttypestext Transport arrangements texts
* @{
*/
#define GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP_TEXT "See getdns_context_set_dns_transport()" #define GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP_TEXT "See getdns_context_set_dns_transport()"
#define GETDNS_TRANSPORT_UDP_ONLY_TEXT "See getdns_context_set_dns_transport()" #define GETDNS_TRANSPORT_UDP_ONLY_TEXT "See getdns_context_set_dns_transport()"
#define GETDNS_TRANSPORT_TCP_ONLY_TEXT "See getdns_context_set_dns_transport()" #define GETDNS_TRANSPORT_TCP_ONLY_TEXT "See getdns_context_set_dns_transport()"
@ -207,7 +190,7 @@ typedef enum getdns_transport_t {
/** /**
* \defgroup transportlisttypes Transport list values * \defgroup transportlisttypestext Transport list values and tests
* @{ * @{
*/ */
/* Base transports for use in transport list */ /* Base transports for use in transport list */
@ -216,13 +199,8 @@ typedef enum getdns_transport_list_t {
GETDNS_TRANSPORT_TCP = 1201, GETDNS_TRANSPORT_TCP = 1201,
GETDNS_TRANSPORT_TLS = 1202, GETDNS_TRANSPORT_TLS = 1202,
} getdns_transport_list_t; } getdns_transport_list_t;
/** @}
*/
/**
* \defgroup transportlisttypestext Transport list values texts
* @{
*/
#define GETDNS_TRANSPORT_UDP_TEXT "See getdns_context_set_dns_transport_list()" #define GETDNS_TRANSPORT_UDP_TEXT "See getdns_context_set_dns_transport_list()"
#define GETDNS_TRANSPORT_TCP_TEXT "See getdns_context_set_dns_transport_list()" #define GETDNS_TRANSPORT_TCP_TEXT "See getdns_context_set_dns_transport_list()"
#define GETDNS_TRANSPORT_TLS_TEXT "See getdns_context_set_dns_transport_list()" #define GETDNS_TRANSPORT_TLS_TEXT "See getdns_context_set_dns_transport_list()"
@ -231,7 +209,7 @@ typedef enum getdns_transport_list_t {
/** /**
* \defgroup suffixappendtypes Suffix appending values * \defgroup suffixappendtypestext Suffix appending values and texts
* @{ * @{
*/ */
typedef enum getdns_append_name_t { typedef enum getdns_append_name_t {
@ -240,13 +218,8 @@ typedef enum getdns_append_name_t {
GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE = 552, GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE = 552,
GETDNS_APPEND_NAME_NEVER = 553 GETDNS_APPEND_NAME_NEVER = 553
} getdns_append_name_t; } getdns_append_name_t;
/** @}
*/
/**
* \defgroup suffixappendtypestext Suffix appending values texts
* @{
*/
#define GETDNS_APPEND_NAME_ALWAYS_TEXT "See getdns_context_set_append_name()" #define GETDNS_APPEND_NAME_ALWAYS_TEXT "See getdns_context_set_append_name()"
#define GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE_TEXT "See getdns_context_set_append_name()" #define GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE_TEXT "See getdns_context_set_append_name()"
#define GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE_TEXT "See getdns_context_set_append_name()" #define GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE_TEXT "See getdns_context_set_append_name()"
@ -256,7 +229,7 @@ typedef enum getdns_append_name_t {
/** /**
* \defgroup contextcodetypes Context code values * \defgroup contextcodetypestext Context code values and texts
* @{ * @{
*/ */
/* Context codes */ /* Context codes */
@ -280,13 +253,8 @@ typedef enum getdns_context_code_t {
GETDNS_CONTEXT_CODE_TIMEOUT = 616, GETDNS_CONTEXT_CODE_TIMEOUT = 616,
GETDNS_CONTEXT_CODE_IDLE_TIMEOUT = 617 GETDNS_CONTEXT_CODE_IDLE_TIMEOUT = 617
} getdns_context_code_t; } getdns_context_code_t;
/** @}
*/
/**
* \defgroup contextcodetypestext Context code values texts
* @{
*/
#define GETDNS_CONTEXT_CODE_NAMESPACES_TEXT "Change related to getdns_context_set_namespaces" #define GETDNS_CONTEXT_CODE_NAMESPACES_TEXT "Change related to getdns_context_set_namespaces"
#define GETDNS_CONTEXT_CODE_RESOLUTION_TYPE_TEXT "Change related to getdns_context_set_resolution_type" #define GETDNS_CONTEXT_CODE_RESOLUTION_TYPE_TEXT "Change related to getdns_context_set_resolution_type"
#define GETDNS_CONTEXT_CODE_FOLLOW_REDIRECTS_TEXT "Change related to getdns_context_set_follow_redirects" #define GETDNS_CONTEXT_CODE_FOLLOW_REDIRECTS_TEXT "Change related to getdns_context_set_follow_redirects"
@ -310,7 +278,7 @@ typedef enum getdns_context_code_t {
/** /**
* \defgroup callbacktype Callback types * \defgroup callbacktype Callback types and texts
* @{ * @{
*/ */
typedef enum getdns_callback_type_t { typedef enum getdns_callback_type_t {
@ -319,13 +287,7 @@ typedef enum getdns_callback_type_t {
GETDNS_CALLBACK_TIMEOUT = 702, GETDNS_CALLBACK_TIMEOUT = 702,
GETDNS_CALLBACK_ERROR = 703 GETDNS_CALLBACK_ERROR = 703
} getdns_callback_type_t; } getdns_callback_type_t;
/** @}
*/
/**
* \defgroup callbacktypetext Callback types texts
* @{
*/
#define GETDNS_CALLBACK_COMPLETE_TEXT "The response has the requested data in it" #define GETDNS_CALLBACK_COMPLETE_TEXT "The response has the requested data in it"
#define GETDNS_CALLBACK_CANCEL_TEXT "The calling program cancelled the callback; response is NULL" #define GETDNS_CALLBACK_CANCEL_TEXT "The calling program cancelled the callback; response is NULL"
#define GETDNS_CALLBACK_TIMEOUT_TEXT "The requested action timed out; response is filled in with empty structures" #define GETDNS_CALLBACK_TIMEOUT_TEXT "The requested action timed out; response is filled in with empty structures"
@ -347,7 +309,7 @@ typedef enum getdns_callback_type_t {
/** /**
* \defgroup respstatus Status Codes for responses and text * \defgroup respstatus Status Codes for responses and texts
* @{ * @{
*/ */
#define GETDNS_RESPSTATUS_GOOD 900 #define GETDNS_RESPSTATUS_GOOD 900
@ -364,7 +326,7 @@ typedef enum getdns_callback_type_t {
*/ */
/** /**
* \defgroup extvals Values associated with extensions * \defgroup extvals Values associated with extensions and texts
* @{ * @{
*/ */
#define GETDNS_EXTENSION_TRUE 1000 #define GETDNS_EXTENSION_TRUE 1000
@ -375,7 +337,7 @@ typedef enum getdns_callback_type_t {
*/ */
/** /**
* \defgroup dnserrors Values associated with DNS errors found by the API and text * \defgroup dnserrors Values associated with DNS errors found by the API and texts
* @{ * @{
*/ */
#define GETDNS_BAD_DNS_CNAME_IN_TARGET 1100 #define GETDNS_BAD_DNS_CNAME_IN_TARGET 1100
@ -556,7 +518,13 @@ typedef struct getdns_dict getdns_dict;
* Indexes are 0 based. * Indexes are 0 based.
*/ */
typedef struct getdns_list getdns_list; typedef struct getdns_list getdns_list;
/** @}
*/
/** \defgroup functions Functions
* @{
*/
/* Specify the order of the following groups manually here so they appear in /* Specify the order of the following groups manually here so they appear in
a better order in doxygen */ a better order in doxygen */
@ -569,15 +537,16 @@ typedef struct getdns_list getdns_list;
* \defgroup getdns_dict_get_functions getdns_dict_get functions * \defgroup getdns_dict_get_functions getdns_dict_get functions
* \defgroup context_create getdns_context creation/destruction functions * \defgroup context_create getdns_context creation/destruction functions
* \defgroup context_set getdns_context_set functions * \defgroup context_set getdns_context_set functions
* \defgroup callbacks getdns_callback functions * \defgroup callbackfns getdns_callback functions
* \defgroup eventloops getdns event loop extension functions
* \defgroup funcs Asynchronous API functions * \defgroup funcs Asynchronous API functions
* \defgroup syncfuns Synchronous API functions that do not use callbacks * \defgroup syncfuncs Synchronous API functions that do not use callbacks
* \defgroup utils Utility functions * \defgroup utils Utility functions
*/ */
/** /**
* \ingroup getdns_list_get_functions getdns_list_get functions * \addtogroup getdns_list_get_functions getdns_list_get functions
* @{ * @{
*/ */
@ -656,7 +625,7 @@ getdns_return_t getdns_list_get_int(const getdns_list *list, size_t index,
/** /**
* \ingroup getdns_dict_get_functions getdns_dict_get functions * \addtogroup getdns_dict_get_functions getdns_dict_get functions
* @{ * @{
*/ */
@ -730,7 +699,7 @@ getdns_return_t getdns_dict_get_int(const getdns_dict *dict,
/** /**
* \ingroup list_create getdns_list creation/destruction functions * \addtogroup list_create getdns_list creation/destruction functions
* @{ * @{
*/ */
@ -766,7 +735,7 @@ void getdns_list_destroy(getdns_list *list);
/** /**
* \ingroup getdns_list_set getdns_list_set functions * \addtogroup getdns_list_set getdns_list_set functions
* @{ * @{
*/ */
@ -816,7 +785,7 @@ getdns_return_t getdns_list_set_int(getdns_list *list, size_t index,
/** /**
* \ingroup dict_create getdns_dict creation/destruction functions * \addtogroup dict_create getdns_dict creation/destruction functions
* @{ * @{
*/ */
@ -849,7 +818,7 @@ void getdns_dict_destroy(getdns_dict *dict);
/** /**
* \ingroup getdns_dict_set getdns_dict_set functions * \addtogroup getdns_dict_set getdns_dict_set functions
* @{ * @{
*/ */
@ -889,6 +858,7 @@ getdns_return_t getdns_dict_set_int(getdns_dict *dict, const char *name,
/** /**
* \addtogroup utils
* remove the value associated with the specified name * remove the value associated with the specified name
* @param dict dictionary from which to fetch the integer * @param dict dictionary from which to fetch the integer
* @param name a name/key value to look up in the dictionary * @param name a name/key value to look up in the dictionary
@ -899,21 +869,16 @@ getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name);
/** /**
* \ingroup callbacks getdns_callback functions * \addtogroup callbackfns getdns_callback functions
* @{
*/ */
/* Callback arguments */ /* Callback arguments */
typedef void (*getdns_callback_t) (getdns_context *context, typedef void (*getdns_callback_t) (getdns_context *context,
getdns_callback_type_t callback_type, getdns_callback_type_t callback_type,
getdns_dict * response, getdns_dict * response,
void *userarg, getdns_transaction_t transaction_id); void *userarg, getdns_transaction_t transaction_id);
/** @}
*/
/** /**
* \ingroup funcs Asynchronous API functions * \addtogroup funcs Asynchronous API functions
* @{ * @{
*/ */
@ -940,7 +905,6 @@ getdns_general(getdns_context *context,
* retrieve address assigned to a DNS name * retrieve address assigned to a DNS name
* @param context pointer to a previously created context to be used for this call * @param context pointer to a previously created context to be used for this call
* @param name the ASCII based domain name to lookup * @param name the ASCII based domain name to lookup
* @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS
* @param extensions dict data structures, NULL to use no extensions * @param extensions dict data structures, NULL to use no extensions
* @param userarg void* returned to the callback untouched * @param userarg void* returned to the callback untouched
* @param[out] transaction_id id used to identify the callback, NULL is ignored * @param[out] transaction_id id used to identify the callback, NULL is ignored
@ -958,7 +922,6 @@ getdns_address(getdns_context *context,
* retrieve hostname assigned to an IP address * retrieve hostname assigned to an IP address
* @param context pointer to a previously created context to be used for this call * @param context pointer to a previously created context to be used for this call
* @param address the address to look up * @param address the address to look up
* @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS
* @param extensions dict data structures, NULL to use no extensions * @param extensions dict data structures, NULL to use no extensions
* @param userarg void* returned to the callback untouched * @param userarg void* returned to the callback untouched
* @param[out] transaction_id id used to identify the callback, NULL is ignored * @param[out] transaction_id id used to identify the callback, NULL is ignored
@ -976,7 +939,6 @@ getdns_hostname(getdns_context *context,
* retrieve a service assigned to a DNS name * retrieve a service assigned to a DNS name
* @param context pointer to a previously created context to be used for this call * @param context pointer to a previously created context to be used for this call
* @param name the ASCII based domain name to lookup * @param name the ASCII based domain name to lookup
* @param request_type RR type for the query, e.g. GETDNS_RR_TYPE_NS
* @param extensions dict data structures, NULL to use no extensions * @param extensions dict data structures, NULL to use no extensions
* @param userarg void* returned to the callback untouched * @param userarg void* returned to the callback untouched
* @param[out] transaction_id id used to identify the callback, NULL is ignored * @param[out] transaction_id id used to identify the callback, NULL is ignored
@ -994,7 +956,7 @@ getdns_service(getdns_context *context,
/** /**
* \ingroup context_create getdns_context creation/destruction functions * \addtogroup context_create getdns_context creation/destruction functions
* @{ * @{
*/ */
@ -1058,7 +1020,7 @@ void getdns_context_destroy(getdns_context *context);
/** /**
* \ingroup callbacks getdns_callback functions * \addtogroup callbackfns getdns_callback functions
* @{ * @{
*/ */
getdns_return_t getdns_return_t
@ -1069,12 +1031,13 @@ getdns_cancel_callback(getdns_context *context,
/** /**
* \ingroup syncfuns Synchronous API functions that do not use callbacks * \addtogroup syncfuncs Synchronous API functions that do not use callbacks
* These functions do not use callbacks, when the application calls one of these * @{
*/
/** These functions do not use callbacks, when the application calls one of these
* functions the library retrieves all of the data before returning. Return * functions the library retrieves all of the data before returning. Return
* values are exactly the same as if you had used a callback with the * values are exactly the same as if you had used a callback with the
* asynchronous functions. * asynchronous functions.
* @{
*/ */
/** /**
@ -1139,7 +1102,7 @@ getdns_service_sync(getdns_context *context,
*/ */
/** /**
* \ingroup utils Utility functions * \addtogroup utils Utility functions
* @{ * @{
*/ */
@ -1181,7 +1144,7 @@ char *getdns_display_ip_address(const getdns_bindata
/** /**
* \ingroup context_set getdns_context_set functions * \addtogroup context_set getdns_context_set functions
* @{ * @{
*/ */
getdns_return_t getdns_return_t
@ -1279,6 +1242,12 @@ getdns_context_set_extended_memory_functions(getdns_context *context,
getdns_dict* getdns_dict*
getdns_context_get_api_information(getdns_context* context); getdns_context_get_api_information(getdns_context* context);
/** @}
*/
/** @}
*/
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif

4
src/getdns/getdns_ext_libev.h
View File

@ -44,6 +44,10 @@ extern "C" {
#include <getdns/getdns_extra.h> #include <getdns/getdns_extra.h>
struct ev_loop; struct ev_loop;
/**
* \ingroup eventloops
*/
/* For libevent, which we are using for these examples */ /* For libevent, which we are using for these examples */
getdns_return_t getdns_return_t
getdns_extension_set_libev_loop(struct getdns_context *context, getdns_extension_set_libev_loop(struct getdns_context *context,

3
src/getdns/getdns_ext_libevent.h
View File

@ -44,6 +44,9 @@ extern "C" {
#include <getdns/getdns_extra.h> #include <getdns/getdns_extra.h>
struct event_base; struct event_base;
/**
* \ingroup eventloops
*/
/* For libevent, which we are using for these examples */ /* For libevent, which we are using for these examples */
getdns_return_t getdns_return_t
getdns_extension_set_libevent_base(struct getdns_context *context, getdns_extension_set_libevent_base(struct getdns_context *context,

3
src/getdns/getdns_ext_libuv.h
View File

@ -44,6 +44,9 @@ extern "C" {
#include <getdns/getdns_extra.h> #include <getdns/getdns_extra.h>
struct uv_loop_s; struct uv_loop_s;
/**
* \ingroup eventloops
*/
/* For libevent, which we are using for these examples */ /* For libevent, which we are using for these examples */
getdns_return_t getdns_return_t
getdns_extension_set_libuv_loop(struct getdns_context *context, getdns_extension_set_libuv_loop(struct getdns_context *context,

549
src/getdns/getdns_extra.h.in
View File

@ -1,3 +1,10 @@
/**
* \file
* \brief Public interface to getdns that is ADDITIONAL to the official getdns API, include
* in your application to use additional functionality offered by
* this implementation.
*/
/* /*
* Copyright (c) 2013, NLNet Labs, Verisign, Inc. * Copyright (c) 2013, NLNet Labs, Verisign, Inc.
* All rights reserved. * All rights reserved.
@ -37,34 +44,111 @@
extern "C" { extern "C" {
#endif #endif
/* Enable the return_dnssec_status extension on every request. /** \defgroup UnofficialgetdnsAPI Additional API for getdns implementation
value is either GETDNS_EXTENSION_TRUE or GETDNS_EXTENSION_FALSE * @{
returns GETDNS_RETURN_GOOD on success or GETDNS_RETURN_INVALID_PARAMETER */
if context or value is invalid */
getdns_return_t getdns_context_set_return_dnssec_status(
getdns_context *context, int enabled);
/* dict util */ /** \defgroup Uvaluesandtexts Additional values and texts
/* set a string as bindata */ * @{
getdns_return_t getdns_dict_util_set_string(struct 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, * \defgroup Ureturnvaluesandtext Additional return values and texts
char *name, char **result); * @{
*/
#define GETDNS_RETURN_NEED_MORE_SPACE ((getdns_return_t) 399 )
#define GETDNS_RETURN_NEED_MORE_SPACE_TEXT "The buffer was too small"
/** @}
*/
/* tells underlying unbound to use background threads or fork */
getdns_return_t getdns_context_set_use_threads(getdns_context* context,
int use_threads);
/* Async support */ /**
uint32_t getdns_context_get_num_pending_requests(getdns_context* context, * \defgroup Ucontextcodes Additional context codes and texts
struct timeval* next_timeout); * @{
*/
#define GETDNS_CONTEXT_CODE_TLS_AUTHENTICATION 618
#define GETDNS_CONTEXT_CODE_TLS_AUTHENTICATION_TEXT "Change related to getdns_context_set_tls_authentication"
#define GETDNS_CONTEXT_CODE_EDNS_CLIENT_SUBNET_PRIVATE 619
#define GETDNS_CONTEXT_CODE_EDNS_CLIENT_SUBNET_PRIVATE_TEXT "Change related to getdns_context_set_edns_client_subnet_private"
#define GETDNS_CONTEXT_CODE_TLS_QUERY_PADDING_BLOCKSIZE 620
#define GETDNS_CONTEXT_CODE_TLS_QUERY_PADDING_BLOCKSIZE_TEXT "Change related to getdns_context_set_tls_query_padding_blocksize"
#define GETDNS_CONTEXT_CODE_PUBKEY_PINSET 621
#define GETDNS_CONTEXT_CODE_PUBKEY_PINSET_TEXT "Change related to getdns_context_set_pubkey_pinset"
/** @}
*/
/* process async reqs */
getdns_return_t getdns_context_process_async(getdns_context* context);
/***************** functions for eventloop extensions ******************/ /**
* \defgroup versions Additional version values
* @{
*/
#define GETDNS_VERSION "@GETDNS_VERSION@"
#define GETDNS_NUMERIC_VERSION @GETDNS_NUMERIC_VERSION@
#define GETDNS_API_VERSION "@API_VERSION@"
#define GETDNS_API_NUMERIC_VERSION @API_NUMERIC_VERSION@
/** @}
*/
/* an alias for REQUIRED */
#define GETDNS_AUTHENTICATION_HOSTNAME GETDNS_AUTHENTICATION_REQUIRED
/**
* \defgroup authvaulesandtext Additional authentication values and texts
* @{
*/
/* Authentication options used when doing TLS */
typedef enum getdns_tls_authentication_t {
GETDNS_AUTHENTICATION_NONE = 1300,
GETDNS_AUTHENTICATION_REQUIRED = 1301
} getdns_tls_authentication_t;
#define GETDNS_AUTHENTICATION_NONE_TEXT "See getdns_context_set_tls_authentication()"
#define GETDNS_AUTHENTICATION_REQUIRED_TEXT "See getdns_context_set_tls_authentication()"
/** @}
*/
/**
* \defgroup appendname Additional append name values and texts
* @{
*/
#define GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST ((getdns_append_name_t) 554 )
#define GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST_TEXT "See getdns_context_set_append_name()"
/** @}
*/
/**
* \defgroup Uvaluesandtextsdepricated Additional transport values and texts (will be deprecated)
* @{
*/
/** WARNING! Do not use the constants below. They will be removed from future
* releases. Please use the getdns_context_set_dns_transport_list with the
* GETDNS_TRANSPORT_UDP, GETDNS_TRANSPORT_TCP and GETDNS_TRANSPORT_TLS
* constants instead.
*/
#define GETDNS_TRANSPORT_TLS_ONLY_KEEP_CONNECTIONS_OPEN 544
#define GETDNS_TRANSPORT_TLS_ONLY_KEEP_CONNECTIONS_OPEN_TEXT "See getdns_context_set_dns_transport()"
#define GETDNS_TRANSPORT_TLS_FIRST_AND_FALL_BACK_TO_TCP_KEEP_CONNECTIONS_OPEN 545
#define GETDNS_TRANSPORT_TLS_FIRST_AND_FALL_BACK_TO_TCP_KEEP_CONNECTIONS_OPEN_TEXT "See getdns_context_set_dns_transport()"
/** @}
*/
/** @}
*/
/**
* \defgroup Ufunctions Additional functions
* @{
*/
/**
* \defgroup Ueventloops Additional event loop extension functions
* @{
*/
typedef void (*getdns_eventloop_callback)(void *userarg); typedef void (*getdns_eventloop_callback)(void *userarg);
@ -131,7 +215,66 @@ getdns_context_detach_eventloop(getdns_context *context);
/* Run the context's event loop until nothing more to do */ /* Run the context's event loop until nothing more to do */
void void
getdns_context_run(getdns_context *context); getdns_context_run(getdns_context *context);
/** @}
*/
/**
* \defgroup contextfunction Additional getdns_context async functions
* @{
*/
/* process async reqs */
getdns_return_t getdns_context_process_async(getdns_context* context);
/** @}
*/
/**
* \defgroup Ucontextset Additional getdns_context_set functions
* @{
*/
/**
* Register a callback function for context changes.
* @param context The context to monitor for changes
* @param userarg A user defined argument that will be passed to the callback
* function.
* @param value The callback function that will be called when a context
* value is changed. The arguments to the callback function
* are the context for which the value changes, a code
* referencing the changed value and the userarg parameter
* supplied during callback registration.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_context_set_update_callback(getdns_context *context, void *userarg,
void (*value) (getdns_context *, getdns_context_code_t, void *));
/* Enable the return_dnssec_status extension on every request.
value is either GETDNS_EXTENSION_TRUE or GETDNS_EXTENSION_FALSE
returns GETDNS_RETURN_GOOD on success or GETDNS_RETURN_INVALID_PARAMETER
if context or value is invalid */
getdns_return_t getdns_context_set_return_dnssec_status(
getdns_context *context, int enabled);
/* tells underlying unbound to use background threads or fork */
getdns_return_t getdns_context_set_use_threads(getdns_context* context,
int use_threads);
getdns_return_t
getdns_context_set_tls_authentication(
getdns_context *context, getdns_tls_authentication_t value);
getdns_return_t
getdns_context_set_edns_client_subnet_private(getdns_context *context, uint8_t value);
getdns_return_t
getdns_context_set_tls_query_padding_blocksize(getdns_context *context, uint16_t value);
/** @}
*/
/**
* \defgroup Ucontextget Additional getdns_context_get functions
* @{
*/
/** begin getters **/ /** begin getters **/
getdns_return_t getdns_return_t
getdns_context_get_resolution_type(getdns_context *context, getdns_context_get_resolution_type(getdns_context *context,
@ -201,16 +344,154 @@ getdns_context_get_edns_version(getdns_context *context, uint8_t* value);
getdns_return_t getdns_return_t
getdns_context_get_edns_do_bit(getdns_context *context, uint8_t* value); getdns_context_get_edns_do_bit(getdns_context *context, uint8_t* value);
getdns_return_t
getdns_context_set_edns_client_subnet_private(getdns_context *context, uint8_t value);
getdns_return_t getdns_return_t
getdns_context_get_edns_client_subnet_private(getdns_context *context, uint8_t* value); getdns_context_get_edns_client_subnet_private(getdns_context *context, uint8_t* value);
getdns_return_t
getdns_context_set_tls_query_padding_blocksize(getdns_context *context, uint16_t value);
getdns_return_t getdns_return_t
getdns_context_get_tls_query_padding_blocksize(getdns_context *context, uint16_t* value); getdns_context_get_tls_query_padding_blocksize(getdns_context *context, uint16_t* value);
getdns_return_t
getdns_context_get_tls_authentication(getdns_context *context,
getdns_tls_authentication_t* value);
/**
* Get the currently registered callback function and user defined argument
* for context changes.
* Combined with getdns_context_set_update_callback this can be used to
* "chain" context update callbacks and in this way create a subscription
* service catering multiple interested parties.
* @param context The context to monitor for changes
* @return userarg A user defined argument to be passed to the callback
* function.
* @return value The callback function to be called on context value
* changes.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_context_get_update_callback(getdns_context *context, void **userarg,
void (**value) (getdns_context *, getdns_context_code_t, void *));
/* Async support */
uint32_t getdns_context_get_num_pending_requests(getdns_context* context,
struct timeval* next_timeout);
/** @}
*/
/**
* \defgroup Uutilityfunctions Additional utility functions
* @{
*/
const char *getdns_get_version(void);
uint32_t getdns_get_version_number(void);
const char *getdns_get_api_version(void);
uint32_t getdns_get_api_version_number(void);
/**
* Returns a text describing the getdns error code, or NULL when the error
* code is unkown.
* @param err The error code for which to return the describing text
* @return The describing text for the error code. The string is in library
* space and the caller must *not* free this.
*/
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,
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,
char *name, char **result);
/**
* Validate replies or resource records.
*
* @param to_validate A list of RR-dicts with companion RRSIG-RR-dicts
* which will be validated. Or a list of reply-dicts
* that will be validated. The "replies_tree" list
* of a response dict can be used directly here.
* @param support_records A list of DS's RR-dicts and DNSKEY RR-dicts with
* companion RRSIG-RR-dicts that lead up from one of
* the trust_anchors to the RR-dicts or replies to
* validate. The "validation_chain" list of a response
* dict (with the dnssec_return_validation_chain
* extension) can be used directly here.
* @param trust_anchors The list of trusted DNSKEYs or DS'es RR-dicts.
* The result of the getdns_root_trust_anchor() or the
* getdns_context_get_dnssec_trust_anchors() function
* can be used directly here.
* @param validation_time The point in time in seconds since 1 January 1970
* 00:00:00 UTC, ignoring leap seconds, wrapping using
* "Serial number arithmetic", as defined in RFC1982.
* @param skew The numer of seconds of skew that is allowed in
* either direction when checking an RRSIG's
* Expiration and Inception fields
* @return The dnssec status of validated records or replies,
* GETDNS_DNSSEC_SECURE, GETDNS_DNSSEC_INSECURE,
* GETDNS_DNSSEC_INDETERMINATE or GETDNS_DNSSEC_BOGUS, or an error
* return code.
*/
getdns_return_t
getdns_validate_dnssec2(getdns_list *to_validate,
getdns_list *support_records,
getdns_list *trust_anchors,
time_t validation_time, uint32_t skew);
/**
* Public Key Pinning functionality:
*
* a public key pinset is a list of dicts. each dict should have a
* "digest" and a "value".
*
* "digest": a string indicating the type of digest. at the moment, we
* only support a "digest" of "sha256".
*
* "value": a binary representation of the digest provided.
*
* given a such a pinset, we should be able to validate a chain
* properly according to section 2.6 of RFC 7469.
*/
/**
* convert an HPKP-style pin description to an appropriate getdns data
* structure. An example string is: (with the quotes, without any
* leading or trailing whitespace):
*
* pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g="
*
* It is the caller's responsibility to call getdns_dict_destroy() on
* the dict returned when it is no longer needed.
*
* @param context a context to use to create the dict, or NULL to create
* it generically
* @param str the pinning string to parse
* @return a dict created from ctx, or NULL if the string did not match.
*/
getdns_dict* getdns_pubkey_pin_create_from_string(
getdns_context* context,
const char* str);
/**
* Test whether a given pinset is reasonable, including:
*
* is it well-formed?
* are there at least two pins?
* are the digests used sane?
*
* @param pinset the set of public key pins to check for sanity. This
* should be a list of dicts.
* @return errorlist if not NULL, a list of human-readable strings is
* appended to errorlist.
* @return GETDNS_RETURN_GOOD if the pinset passes the sanity check.
*/
getdns_return_t getdns_pubkey_pinset_sanity_check(
const getdns_list* pinset,
getdns_list* errorlist);
/** /**
* Pretty print the getdns_dict in a given buffer snprintf style. * Pretty print the getdns_dict in a given buffer snprintf style.
@ -306,169 +587,6 @@ int
getdns_snprint_json_list( getdns_snprint_json_list(
char *str, size_t size, const getdns_list *list, int pretty); char *str, size_t size, const getdns_list *list, int pretty);
/**
* Register a callback function for context changes.
* @param context The context to monitor for changes
* @param userarg A user defined argument that will be passed to the callback
* function.
* @param value The callback function that will be called when a context
* value is changed. The arguments to the callback function
* are the context for which the value changes, a code
* referencing the changed value and the userarg parameter
* supplied during callback registration.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_context_set_update_callback(getdns_context *context, void *userarg,
void (*value) (getdns_context *, getdns_context_code_t, void *));
/**
* Get the currently registered callback function and user defined argument
* for context changes.
* Combined with getdns_context_set_update_callback this can be used to
* "chain" context update callbacks and in this way create a subscription
* service catering multiple interested parties.
* @param context The context to monitor for changes
* @return userarg A user defined argument to be passed to the callback
* function.
* @return value The callback function to be called on context value
* changes.
* @return GETDNS_RETURN_GOOD on success or an error code on failure.
*/
getdns_return_t
getdns_context_get_update_callback(getdns_context *context, void **userarg,
void (**value) (getdns_context *, getdns_context_code_t, void *));
/**
* Returns a text describing the getdns error code, or NULL when the error
* code is unkown.
* @param err The error code for which to return the describing text
* @return The describing text for the error code. The string is in library
* space and the caller must *not* free this.
*/
const char *getdns_get_errorstr_by_id(uint16_t err);
/**
* Public Key Pinning functionality:
*
* a public key pinset is a list of dicts. each dict should have a
* "digest" and a "value".
*
* "digest": a string indicating the type of digest. at the moment, we
* only support a "digest" of "sha256".
*
* "value": a binary representation of the digest provided.
*
* given a such a pinset, we should be able to validate a chain
* properly according to section 2.6 of RFC 7469.
*/
/**
* convert an HPKP-style pin description to an appropriate getdns data
* structure. An example string is: (with the quotes, without any
* leading or trailing whitespace):
*
* pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g="
*
* It is the caller's responsibility to call getdns_dict_destroy() on
* the dict returned when it is no longer needed.
*
* @param context a context to use to create the dict, or NULL to create
* it generically
* @param str the pinning string to parse
* @return a dict created from ctx, or NULL if the string did not match.
*/
getdns_dict* getdns_pubkey_pin_create_from_string(
getdns_context* context,
const char* str);
/**
* Test whether a given pinset is reasonable, including:
*
* is it well-formed?
* are there at least two pins?
* are the digests used sane?
*
* @param pinset the set of public key pins to check for sanity. This
* should be a list of dicts.
* @return errorlist if not NULL, a list of human-readable strings is
* appended to errorlist.
* @return GETDNS_RETURN_GOOD if the pinset passes the sanity check.
*/
getdns_return_t getdns_pubkey_pinset_sanity_check(
const getdns_list* pinset,
getdns_list* errorlist);
/* WARNING! Function getdns_strerror is not in the API specification and
* is likely to be removed from future versions of our implementation, to be
* replaced by getdns_get_errorstr_by_id or something similar.
* Please use getdns_get_errorstr_by_id instead of getdns_strerror.
*/
getdns_return_t getdns_strerror(getdns_return_t err, char *buf, size_t buflen);
#define GETDNS_VERSION "@GETDNS_VERSION@"
#define GETDNS_NUMERIC_VERSION @GETDNS_NUMERIC_VERSION@
#define GETDNS_API_VERSION "@API_VERSION@"
#define GETDNS_API_NUMERIC_VERSION @API_NUMERIC_VERSION@
const char *getdns_get_version(void);
uint32_t getdns_get_version_number(void);
const char *getdns_get_api_version(void);
uint32_t getdns_get_api_version_number(void);
/* Authentication options used when doing TLS */
typedef enum getdns_tls_authentication_t {
GETDNS_AUTHENTICATION_NONE = 1300,
GETDNS_AUTHENTICATION_REQUIRED = 1301
} getdns_tls_authentication_t;
/* an alias for REQUIRED */
#define GETDNS_AUTHENTICATION_HOSTNAME GETDNS_AUTHENTICATION_REQUIRED
/**
* \defgroup authtext Authentication texts
* @{
*/
#define GETDNS_AUTHENTICATION_NONE_TEXT "See getdns_context_set_tls_authentication()"
#define GETDNS_AUTHENTICATION_REQUIRED_TEXT "See getdns_context_set_tls_authentication()"
/** @}
*/
#define GETDNS_CONTEXT_CODE_TLS_AUTHENTICATION 618
#define GETDNS_CONTEXT_CODE_TLS_AUTHENTICATION_TEXT "Change related to getdns_context_set_tls_authentication"
#define GETDNS_CONTEXT_CODE_EDNS_CLIENT_SUBNET_PRIVATE 619
#define GETDNS_CONTEXT_CODE_EDNS_CLIENT_SUBNET_PRIVATE_TEXT "Change related to getdns_context_set_edns_client_subnet_private"
#define GETDNS_CONTEXT_CODE_TLS_QUERY_PADDING_BLOCKSIZE 620
#define GETDNS_CONTEXT_CODE_TLS_QUERY_PADDING_BLOCKSIZE_TEXT "Change related to getdns_context_set_tls_query_padding_blocksize"
#define GETDNS_CONTEXT_CODE_PUBKEY_PINSET 621
#define GETDNS_CONTEXT_CODE_PUBKEY_PINSET_TEXT "Change related to getdns_context_set_pubkey_pinset"
getdns_return_t
getdns_context_set_tls_authentication(
getdns_context *context, getdns_tls_authentication_t value);
getdns_return_t
getdns_context_get_tls_authentication(getdns_context *context,
getdns_tls_authentication_t* value);
/* WARNING! Do not use the constants below. They will be removed from future
* releases. Please use the getdns_context_set_dns_transport_list with the
* GETDNS_TRANSPORT_UDP, GETDNS_TRANSPORT_TCP and GETDNS_TRANSPORT_TLS
* constants instead.
*/
#define GETDNS_TRANSPORT_TLS_ONLY_KEEP_CONNECTIONS_OPEN 544
#define GETDNS_TRANSPORT_TLS_ONLY_KEEP_CONNECTIONS_OPEN_TEXT "See getdns_context_set_dns_transport()"
#define GETDNS_TRANSPORT_TLS_FIRST_AND_FALL_BACK_TO_TCP_KEEP_CONNECTIONS_OPEN 545
#define GETDNS_TRANSPORT_TLS_FIRST_AND_FALL_BACK_TO_TCP_KEEP_CONNECTIONS_OPEN_TEXT "See getdns_context_set_dns_transport()"
#define GETDNS_RETURN_NEED_MORE_SPACE ((getdns_return_t) 399 )
#define GETDNS_RETURN_NEED_MORE_SPACE_TEXT "The buffer was too small"
/** /**
* Convert rr_dict to wireformat representation of the resource record. * Convert rr_dict to wireformat representation of the resource record.
@ -630,7 +748,7 @@ getdns_str2rr_dict(
/** /**
* Read the zonefile and convert to a list of rr_dict's. * Read the zonefile and convert to a list of rr_dict's.
* *
* @param fp An opened FILE pointer on the zone file. * @param FILE An opened FILE pointer on the zone file.
* @return rr_list The result list of rr_dicts representing the zone file. * @return rr_list The result list of rr_dicts representing the zone file.
* @param origin Default suffix for not fully qualified domain names * @param origin Default suffix for not fully qualified domain names
* @param default_ttl Default ttl * @param default_ttl Default ttl
@ -782,45 +900,26 @@ getdns_msg_dict2str_buf(
getdns_return_t getdns_return_t
getdns_msg_dict2str_scan( getdns_msg_dict2str_scan(
const getdns_dict *msg_dict, char **str, int *str_len); const getdns_dict *msg_dict, char **str, int *str_len);
/** @}
*/
/** /**
* Validate replies or resource records. * \defgroup Uutilityfunctionsdeprecated Additional utility functions (will be deprecated)
* * @{
* @param to_validate A list of RR-dicts with companion RRSIG-RR-dicts */
* which will be validated. Or a list of reply-dicts /* WARNING! Function getdns_strerror is not in the API specification and
* that will be validated. The "replies_tree" list * is likely to be removed from future versions of our implementation, to be
* of a response dict can be used directly here. * replaced by getdns_get_errorstr_by_id or something similar.
* @param support_records A list of DS's RR-dicts and DNSKEY RR-dicts with * Please use getdns_get_errorstr_by_id instead of getdns_strerror.
* companion RRSIG-RR-dicts that lead up from one of */
* the trust_anchors to the RR-dicts or replies to getdns_return_t getdns_strerror(getdns_return_t err, char *buf, size_t buflen);
* validate. The "validation_chain" list of a response /** @}
* dict (with the dnssec_return_validation_chain */
* extension) can be used directly here. /** @}
* @param trust_anchors The list of trusted DNSKEYs or DS'es RR-dicts. */
* The result of the getdns_root_trust_anchor() or the /** @}
* getdns_context_get_dnssec_trust_anchors() function
* can be used directly here.
* @param validation_time The point in time in seconds since 1 January 1970
* 00:00:00 UTC, ignoring leap seconds, wrapping using
* "Serial number arithmetic", as defined in RFC1982.
* @param skew The numer of seconds of skew that is allowed in
* either direction when checking an RRSIG's
* Expiration and Inception fields
* @return The dnssec status of validated records or replies,
* GETDNS_DNSSEC_SECURE, GETDNS_DNSSEC_INSECURE,
* GETDNS_DNSSEC_INDETERMINATE or GETDNS_DNSSEC_BOGUS, or an error
* return code.
*/ */
getdns_return_t
getdns_validate_dnssec2(getdns_list *to_validate,
getdns_list *support_records,
getdns_list *trust_anchors,
time_t validation_time, uint32_t skew);
#define GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST ((getdns_append_name_t) 554 )
#define GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST_TEXT "See getdns_context_set_append_name()"
getdns_return_t getdns_str2dict(const char *str, getdns_dict **dict); getdns_return_t getdns_str2dict(const char *str, getdns_dict **dict);
getdns_return_t getdns_str2list(const char *str, getdns_list **list); getdns_return_t getdns_str2list(const char *str, getdns_list **list);

25
src/test/check_getdns_context_set_dns_transport.h
View File

@ -226,7 +226,7 @@
GETDNS_RETURN_GOOD, "Return code from getdns_context_set_edns_maximum_udp_payload_size()"); GETDNS_RETURN_GOOD, "Return code from getdns_context_set_edns_maximum_udp_payload_size()");
ASSERT_RC(getdns_context_set_timeout(context, 2000), ASSERT_RC(getdns_context_set_timeout(context, 2000),
GETDNS_RETURN_GOOD, "Return code from getdns_context_set_edns_maximum_udp_payload_size()"); GETDNS_RETURN_GOOD, "Return code from getdns_context_set_edns_maximum_udp_payload_size()");
ASSERT_RC(getdns_general_sync(context, "getdnsapi.net", 48, extensions, &response), ASSERT_RC(getdns_general_sync(context, "large.getdnsapi.net", GETDNS_RRTYPE_TXT, extensions, &response),
GETDNS_RETURN_GOOD, "Return code from getdns_general_sync()"); GETDNS_RETURN_GOOD, "Return code from getdns_general_sync()");
ASSERT_RC(getdns_dict_get_int(response, "status", &status), ASSERT_RC(getdns_dict_get_int(response, "status", &status),
@ -250,6 +250,19 @@
struct getdns_context *context = NULL; struct getdns_context *context = NULL;
struct getdns_dict *response = NULL; struct getdns_dict *response = NULL;
struct getdns_dict *extensions = getdns_dict_create(); struct getdns_dict *extensions = getdns_dict_create();
/*
* Not all servers in the path to large.getdnsapi.net seem to support
* TCP consistently. Many (root) servers are anycasted which decreases
* reliability of TCP availability (as we've seen in practice).
* To mitigate we provide our own root server for which we are sure that
* it supports TCP. The .net authoritative server are still out of our
* control tough. But because they are managed by a single party I
* suspect them to be a bit more reliable.
*/
struct getdns_list *root_servers = getdns_list_create();
struct getdns_bindata nlnetlabs_root = { 4, (void *)"\xB9\x31\x8D\x25" };
uint32_t status; uint32_t status;
uint32_t type; uint32_t type;
uint32_t tc; uint32_t tc;
@ -264,11 +277,15 @@
/* Re-do over TCP */ /* Re-do over TCP */
ASSERT_RC(getdns_dict_set_int(extensions,"return_call_reporting", GETDNS_EXTENSION_TRUE), ASSERT_RC(getdns_dict_set_int(extensions,"return_call_reporting", GETDNS_EXTENSION_TRUE),
GETDNS_RETURN_GOOD, "Return code from getdns_dict_set_int()"); GETDNS_RETURN_GOOD, "Return code from getdns_dict_set_int()");
ASSERT_RC(getdns_list_set_bindata(root_servers,0,&nlnetlabs_root),
GETDNS_RETURN_GOOD, "Return code from getdns_list_set_bindata()");
ASSERT_RC(getdns_context_set_dns_root_servers(context, root_servers),
GETDNS_RETURN_GOOD, "Return code from getdns_context_set_dns_root_servers()");
ASSERT_RC(getdns_context_set_dns_transport(context, GETDNS_TRANSPORT_TCP_ONLY), ASSERT_RC(getdns_context_set_dns_transport(context, GETDNS_TRANSPORT_TCP_ONLY),
GETDNS_RETURN_GOOD, "Return code from getdns_context_set_dns_transport()"); GETDNS_RETURN_GOOD, "Return code from getdns_context_set_dns_transport()");
ASSERT_RC(getdns_context_set_edns_maximum_udp_payload_size(context, 512), ASSERT_RC(getdns_context_set_edns_maximum_udp_payload_size(context, 512),
GETDNS_RETURN_GOOD, "Return code from getdns_context_set_edns_maximum_udp_payload_size()"); GETDNS_RETURN_GOOD, "Return code from getdns_context_set_edns_maximum_udp_payload_size()");
ASSERT_RC(getdns_general_sync(context, "getdnsapi.net", 48, extensions, &response), ASSERT_RC(getdns_general_sync(context, "large.getdnsapi.net", GETDNS_RRTYPE_TXT, extensions, &response),
GETDNS_RETURN_GOOD, "Return code from getdns_general_sync()"); GETDNS_RETURN_GOOD, "Return code from getdns_general_sync()");
ASSERT_RC(getdns_dict_get_int(response, "status", &status), ASSERT_RC(getdns_dict_get_int(response, "status", &status),
@ -283,6 +300,8 @@
} }
CONTEXT_DESTROY; CONTEXT_DESTROY;
getdns_dict_destroy(extensions);
getdns_list_destroy(root_servers);
} }
END_TEST END_TEST
@ -311,7 +330,7 @@
GETDNS_RETURN_GOOD, "Return code from getdns_context_set_dns_transport()"); GETDNS_RETURN_GOOD, "Return code from getdns_context_set_dns_transport()");
ASSERT_RC(getdns_context_set_edns_maximum_udp_payload_size(context, 512), ASSERT_RC(getdns_context_set_edns_maximum_udp_payload_size(context, 512),
GETDNS_RETURN_GOOD, "Return code from getdns_context_set_edns_maximum_udp_payload_size()"); GETDNS_RETURN_GOOD, "Return code from getdns_context_set_edns_maximum_udp_payload_size()");
ASSERT_RC(getdns_general_sync(context, "getdnsapi.net", 48, extensions, &response), ASSERT_RC(getdns_general_sync(context, "large.getdnsapi.net", GETDNS_RRTYPE_TXT, extensions, &response),
GETDNS_RETURN_GOOD, "Return code from getdns_general_sync()"); GETDNS_RETURN_GOOD, "Return code from getdns_general_sync()");
ASSERT_RC(getdns_dict_get_int(response, "status", &status), ASSERT_RC(getdns_dict_get_int(response, "status", &status),

2
src/test/check_getdns_eventloop.h
View File

@ -1,6 +1,6 @@
/** /**
* \file * \file
* \brief Public interfaces to getdns, include in your application to use getdns API. * \brief Testing interfaces to getdns
* *
* This source was taken from the original pseudo-implementation by * This source was taken from the original pseudo-implementation by
* Paul Hoffman. * Paul Hoffman.

2
src/test/check_getdns_libev.c
View File

@ -1,6 +1,6 @@
/** /**
* \file * \file
* \brief Public interfaces to getdns, include in your application to use getdns API. * \brief Testing interfaces to getdns
* *
* This source was taken from the original pseudo-implementation by * This source was taken from the original pseudo-implementation by
* Paul Hoffman. * Paul Hoffman.

2
src/test/check_getdns_libevent.c
View File

@ -1,6 +1,6 @@
/** /**
* \file * \file
* \brief Public interfaces to getdns, include in your application to use getdns API. * \brief Testing interfaces to getdns
* *
* This source was taken from the original pseudo-implementation by * This source was taken from the original pseudo-implementation by
* Paul Hoffman. * Paul Hoffman.

2
src/test/check_getdns_libuv.c
View File

@ -1,6 +1,6 @@
/** /**
* \file * \file
* \brief Public interfaces to getdns, include in your application to use getdns API. * \brief Testing interfaces to getdns
* *
* This source was taken from the original pseudo-implementation by * This source was taken from the original pseudo-implementation by
* Paul Hoffman. * Paul Hoffman.

2
src/test/check_getdns_selectloop.c
View File

@ -1,6 +1,6 @@
/** /**
* \file * \file
* \brief Public interfaces to getdns, include in your application to use getdns API. * \brief Testing interfaces to getdns
* *
* This source was taken from the original pseudo-implementation by * This source was taken from the original pseudo-implementation by
* Paul Hoffman. * Paul Hoffman.

8
src/test/getdns_query.c
View File

@ -1521,6 +1521,14 @@ error:
getdns_dict_destroy(response); getdns_dict_destroy(response);
} }
/**
* \brief A wrapper script for command line testing of getdns
* getdns_query -h provides details of the available options (the syntax is
* similar to that of drill)
* Note that for getdns the -z options enables getdns as a daemon which
* allows getdns to be used as the local stub (or recursive) resolver
*/
int int
main(int argc, char **argv) main(int argc, char **argv)
{ {

2
src/util-internal.h
View File

@ -68,7 +68,7 @@ getdns_return_t getdns_apply_network_result(getdns_network_req* netreq,
* description but the list_set functions seem to be designed to modify an existing * description but the list_set functions seem to be designed to modify an existing
* item in the list. The newly added item has no data type. * item in the list. The newly added item has no data type.
* @param list list containing the item to which child_list is to be added * @param list list containing the item to which child_list is to be added
* @param *index assigned to the index of the newly added item on success * @param *child_dict dict to append to the list
* @return GETDNS_RETURN_GOOD on success * @return GETDNS_RETURN_GOOD on success
* @return GETDNS_RETURN_GENERAL_ERROR if out of memory * @return GETDNS_RETURN_GENERAL_ERROR if out of memory
*/ */