mirror of https://github.com/getdnsapi/getdns.git
Merge branch 'develop' into release/v1.1.0a1
This commit is contained in:
Willem Toorop
commit
504cb8a783
80
README.md
80
README.md
|
|
@ -1,17 +1,28 @@
|
|||
getdns API
|
||||
==========
|
||||
getdns
|
||||
======
|
||||
|
||||
# Overview of getdns
|
||||
|
||||
* Date: 2016-03-24
|
||||
* GitHub: <https://github.com/getdnsapi/getdns>
|
||||
|
||||
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 new regarding the getdns API
|
||||
documentation, binary downloads and news regarding the getdns API
|
||||
implementation. This implementation is licensed under the New BSD License
|
||||
(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)
|
||||
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
|
||||
|
|
@ -20,18 +31,23 @@ available from the [pgp keyservers](https://keyserver.pgp.com)
|
|||
* willem@nlnetlabs.nl, key id E5F8F8212F77A498
|
||||
* 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)
|
||||
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
|
||||
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.
|
||||
## Motivation for providing the API
|
||||
|
||||
This file captures the goals and direction of the project and the current state
|
||||
of the implementation.
|
||||
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:
|
||||
|
||||
|
|
@ -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:
|
||||
* 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).
|
||||
|
||||
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
|
||||
========
|
||||
|
|
@ -102,6 +116,16 @@ with:
|
|||
# libtoolize -ci (use glibtoolize for OS X, libtool is installed as glibtool to avoid name conflict on OS X)
|
||||
# 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
|
||||
|
||||
* 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
|
||||
* 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
|
||||
|
||||
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 www.huque.com A +dnssec_return_status +return_call_reporting (DNSSEC)
|
||||
|
||||
|
||||
Contributors
|
||||
============
|
||||
* Theogene Bucuti
|
||||
|
|
@ -313,6 +348,7 @@ Contributors
|
|||
* Glen Wiley, Verisign, Inc.
|
||||
* Paul Wouters
|
||||
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@ DOXYFILE_ENCODING = UTF-8
|
|||
# identify the project. Note that if you do not use Doxywizard you need
|
||||
# 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.
|
||||
# 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
|
||||
# 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
|
||||
# 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
|
||||
# with spaces.
|
||||
|
||||
INPUT = @srcdir@ \
|
||||
getdns/ \
|
||||
@srcdir@/getdns/ \
|
||||
@srcdir@/example/ \
|
||||
@srcdir@/test/ \
|
||||
INPUT = @srcdir@/getdns/ \
|
||||
getdns/getdns.h \
|
||||
getdns/getdns_extra.h \
|
||||
@srcdir@/../README.md
|
||||
# @srcdir@/../spec/example/ \
|
||||
# getdns/ \
|
||||
# @srcdir@ \
|
||||
# @srcdir@/test/ \
|
||||
|
||||
|
||||
# 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
|
||||
|
|
@ -820,7 +823,7 @@ FILTER_SOURCE_PATTERNS =
|
|||
# This can be useful if you have a project on for instance GitHub and want reuse
|
||||
# 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
|
||||
|
|
|
|||
|
|
@ -665,7 +665,7 @@ getdns_return_t
|
|||
getdns_general(getdns_context *context,
|
||||
const char *name, uint16_t request_type, getdns_dict *extensions,
|
||||
void *userarg, getdns_transaction_t * transaction_id,
|
||||
getdns_callback_t callback)
|
||||
getdns_callback_t callbackfn)
|
||||
{
|
||||
getdns_return_t r;
|
||||
getdns_network_req *netreq = NULL;
|
||||
|
|
@ -673,7 +673,7 @@ getdns_general(getdns_context *context,
|
|||
if (!context) return GETDNS_RETURN_INVALID_PARAMETER;
|
||||
r = _getdns_general_loop(context, context->extension,
|
||||
name, request_type, extensions,
|
||||
userarg, &netreq, callback, NULL);
|
||||
userarg, &netreq, callbackfn, NULL);
|
||||
if (netreq && transaction_id)
|
||||
*transaction_id = netreq->owner->trans_id;
|
||||
return r;
|
||||
|
|
@ -686,12 +686,12 @@ getdns_general(getdns_context *context,
|
|||
getdns_return_t
|
||||
getdns_address(getdns_context *context,
|
||||
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;
|
||||
return _getdns_address_loop(context, context->extension,
|
||||
name, extensions, userarg,
|
||||
transaction_id, callback);
|
||||
transaction_id, callbackfn);
|
||||
} /* getdns_address */
|
||||
|
||||
/*
|
||||
|
|
@ -701,11 +701,11 @@ getdns_address(getdns_context *context,
|
|||
getdns_return_t
|
||||
getdns_hostname(getdns_context *context,
|
||||
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;
|
||||
return _getdns_hostname_loop(context, context->extension,
|
||||
address, extensions, userarg, transaction_id, callback);
|
||||
address, extensions, userarg, transaction_id, callbackfn);
|
||||
} /* getdns_hostname */
|
||||
|
||||
/*
|
||||
|
|
@ -715,11 +715,11 @@ getdns_hostname(getdns_context *context,
|
|||
getdns_return_t
|
||||
getdns_service(getdns_context *context,
|
||||
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;
|
||||
return _getdns_service_loop(context, context->extension,
|
||||
name, extensions, userarg, transaction_id, callback);
|
||||
name, extensions, userarg, transaction_id, callbackfn);
|
||||
} /* getdns_service */
|
||||
|
||||
/* getdns_general.c */
|
||||
|
|
|
|||
|
|
@ -47,8 +47,17 @@ extern "C" {
|
|||
|
||||
#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 {
|
||||
|
|
@ -68,13 +77,8 @@ typedef enum getdns_return_t {
|
|||
GETDNS_RETURN_INVALID_PARAMETER = 311,
|
||||
GETDNS_RETURN_NOT_IMPLEMENTED = 312
|
||||
} getdns_return_t;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup returntypestext Return values texts
|
||||
* @{
|
||||
*/
|
||||
|
||||
#define GETDNS_RETURN_GOOD_TEXT "Good"
|
||||
#define GETDNS_RETURN_GENERIC_ERROR_TEXT "Generic error"
|
||||
#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 {
|
||||
|
|
@ -123,13 +127,8 @@ typedef enum getdns_namespace_t {
|
|||
GETDNS_NAMESPACE_MDNS = 503,
|
||||
GETDNS_NAMESPACE_NIS = 504
|
||||
} getdns_namespace_t;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup namespacetypestext Namespace types texts
|
||||
* @{
|
||||
*/
|
||||
|
||||
#define GETDNS_NAMESPACE_DNS_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()"
|
||||
|
|
@ -140,20 +139,15 @@ typedef enum getdns_namespace_t {
|
|||
|
||||
|
||||
/**
|
||||
* \defgroup resolutiontypes Resolution types
|
||||
* \defgroup resolutiontypestext Resolution types and texts
|
||||
* @{
|
||||
*/
|
||||
typedef enum getdns_resolution_t {
|
||||
GETDNS_RESOLUTION_STUB = 520,
|
||||
GETDNS_RESOLUTION_RECURSING = 521
|
||||
} getdns_resolution_t;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup resolutiontypestext Resolution types texts
|
||||
* @{
|
||||
*/
|
||||
|
||||
#define GETDNS_RESOLUTION_STUB_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 {
|
||||
GETDNS_REDIRECTS_FOLLOW = 530,
|
||||
GETDNS_REDIRECTS_DO_NOT_FOLLOW = 531
|
||||
} getdns_redirects_t;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* \defgroup redirectpoliciestext Redirect policies texts
|
||||
* @{
|
||||
*/
|
||||
|
||||
#define GETDNS_REDIRECTS_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 {
|
||||
|
|
@ -191,13 +180,7 @@ typedef enum getdns_transport_t {
|
|||
GETDNS_TRANSPORT_TCP_ONLY = 542,
|
||||
GETDNS_TRANSPORT_TCP_ONLY_KEEP_CONNECTIONS_OPEN = 543
|
||||
} 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_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 */
|
||||
|
|
@ -216,13 +199,8 @@ typedef enum getdns_transport_list_t {
|
|||
GETDNS_TRANSPORT_TCP = 1201,
|
||||
GETDNS_TRANSPORT_TLS = 1202,
|
||||
} 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_TCP_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 {
|
||||
|
|
@ -240,13 +218,8 @@ typedef enum getdns_append_name_t {
|
|||
GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE = 552,
|
||||
GETDNS_APPEND_NAME_NEVER = 553
|
||||
} 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_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()"
|
||||
|
|
@ -256,7 +229,7 @@ typedef enum getdns_append_name_t {
|
|||
|
||||
|
||||
/**
|
||||
* \defgroup contextcodetypes Context code values
|
||||
* \defgroup contextcodetypestext Context code values and texts
|
||||
* @{
|
||||
*/
|
||||
/* Context codes */
|
||||
|
|
@ -280,13 +253,8 @@ typedef enum getdns_context_code_t {
|
|||
GETDNS_CONTEXT_CODE_TIMEOUT = 616,
|
||||
GETDNS_CONTEXT_CODE_IDLE_TIMEOUT = 617
|
||||
} 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_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"
|
||||
|
|
@ -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 {
|
||||
|
|
@ -319,13 +287,7 @@ typedef enum getdns_callback_type_t {
|
|||
GETDNS_CALLBACK_TIMEOUT = 702,
|
||||
GETDNS_CALLBACK_ERROR = 703
|
||||
} 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_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"
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -556,7 +518,13 @@ typedef struct getdns_dict getdns_dict;
|
|||
* Indexes are 0 based.
|
||||
*/
|
||||
typedef struct getdns_list getdns_list;
|
||||
/** @}
|
||||
*/
|
||||
|
||||
|
||||
/** \defgroup functions Functions
|
||||
* @{
|
||||
*/
|
||||
/* Specify the order of the following groups manually here so they appear in
|
||||
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 context_create getdns_context creation/destruction 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 syncfuns Synchronous API functions that do not use callbacks
|
||||
* \defgroup syncfuncs Synchronous API functions that do not use callbacks
|
||||
* \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
|
||||
* @param dict dictionary from which to fetch the integer
|
||||
* @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 */
|
||||
typedef void (*getdns_callback_t) (getdns_context *context,
|
||||
getdns_callback_type_t callback_type,
|
||||
getdns_dict * response,
|
||||
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
|
||||
* @param context pointer to a previously created context to be used for this call
|
||||
* @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 userarg void* returned to the callback untouched
|
||||
* @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
|
||||
* @param context pointer to a previously created context to be used for this call
|
||||
* @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 userarg void* returned to the callback untouched
|
||||
* @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
|
||||
* @param context pointer to a previously created context to be used for this call
|
||||
* @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 userarg void* returned to the callback untouched
|
||||
* @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
|
||||
|
|
@ -1069,12 +1031,13 @@ getdns_cancel_callback(getdns_context *context,
|
|||
|
||||
|
||||
/**
|
||||
* \ingroup syncfuns Synchronous API functions that do not use callbacks
|
||||
* These functions do not use callbacks, when the application calls one of these
|
||||
* \addtogroup syncfuncs Synchronous API functions that do not use callbacks
|
||||
* @{
|
||||
*/
|
||||
/** These functions do not use callbacks, when the application calls one of these
|
||||
* 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
|
||||
* 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
|
||||
|
|
@ -1279,6 +1242,12 @@ getdns_context_set_extended_memory_functions(getdns_context *context,
|
|||
getdns_dict*
|
||||
getdns_context_get_api_information(getdns_context* context);
|
||||
|
||||
/** @}
|
||||
*/
|
||||
|
||||
/** @}
|
||||
*/
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
|
|
|||
|
|
@ -44,6 +44,10 @@ extern "C" {
|
|||
#include <getdns/getdns_extra.h>
|
||||
struct ev_loop;
|
||||
|
||||
|
||||
/**
|
||||
* \ingroup eventloops
|
||||
*/
|
||||
/* For libevent, which we are using for these examples */
|
||||
getdns_return_t
|
||||
getdns_extension_set_libev_loop(struct getdns_context *context,
|
||||
|
|
|
|||
|
|
@ -44,6 +44,9 @@ extern "C" {
|
|||
#include <getdns/getdns_extra.h>
|
||||
struct event_base;
|
||||
|
||||
/**
|
||||
* \ingroup eventloops
|
||||
*/
|
||||
/* For libevent, which we are using for these examples */
|
||||
getdns_return_t
|
||||
getdns_extension_set_libevent_base(struct getdns_context *context,
|
||||
|
|
|
|||
|
|
@ -44,6 +44,9 @@ extern "C" {
|
|||
#include <getdns/getdns_extra.h>
|
||||
struct uv_loop_s;
|
||||
|
||||
/**
|
||||
* \ingroup eventloops
|
||||
*/
|
||||
/* For libevent, which we are using for these examples */
|
||||
getdns_return_t
|
||||
getdns_extension_set_libuv_loop(struct getdns_context *context,
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
* All rights reserved.
|
||||
|
|
@ -37,34 +44,111 @@
|
|||
extern "C" {
|
||||
#endif
|
||||
|
||||
/* 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);
|
||||
/** \defgroup UnofficialgetdnsAPI Additional API for getdns implementation
|
||||
* @{
|
||||
*/
|
||||
|
||||
/* dict util */
|
||||
/* set a string as bindata */
|
||||
getdns_return_t getdns_dict_util_set_string(struct getdns_dict * dict,
|
||||
char *name, const char *value);
|
||||
/** \defgroup Uvaluesandtexts Additional values and texts
|
||||
* @{
|
||||
*/
|
||||
|
||||
/* 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);
|
||||
/**
|
||||
* \defgroup Ureturnvaluesandtext Additional return values and texts
|
||||
* @{
|
||||
*/
|
||||
#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,
|
||||
struct timeval* next_timeout);
|
||||
/**
|
||||
* \defgroup Ucontextcodes Additional context codes and texts
|
||||
* @{
|
||||
*/
|
||||
#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);
|
||||
|
||||
|
|
@ -131,7 +215,66 @@ getdns_context_detach_eventloop(getdns_context *context);
|
|||
/* Run the context's event loop until nothing more to do */
|
||||
void
|
||||
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 **/
|
||||
getdns_return_t
|
||||
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_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_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_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.
|
||||
|
|
@ -306,169 +587,6 @@ int
|
|||
getdns_snprint_json_list(
|
||||
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.
|
||||
|
|
@ -630,7 +748,7 @@ getdns_str2rr_dict(
|
|||
/**
|
||||
* 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.
|
||||
* @param origin Default suffix for not fully qualified domain names
|
||||
* @param default_ttl Default ttl
|
||||
|
|
@ -782,45 +900,26 @@ getdns_msg_dict2str_buf(
|
|||
getdns_return_t
|
||||
getdns_msg_dict2str_scan(
|
||||
const getdns_dict *msg_dict, char **str, int *str_len);
|
||||
/** @}
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* 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.
|
||||
* \defgroup Uutilityfunctionsdeprecated Additional utility functions (will be deprecated)
|
||||
* @{
|
||||
*/
|
||||
/* 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);
|
||||
/** @}
|
||||
*/
|
||||
/** @}
|
||||
*/
|
||||
/** @}
|
||||
*/
|
||||
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_str2list(const char *str, getdns_list **list);
|
||||
|
|
|
|||
|
|
@ -226,7 +226,7 @@
|
|||
GETDNS_RETURN_GOOD, "Return code from getdns_context_set_edns_maximum_udp_payload_size()");
|
||||
ASSERT_RC(getdns_context_set_timeout(context, 2000),
|
||||
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()");
|
||||
|
||||
ASSERT_RC(getdns_dict_get_int(response, "status", &status),
|
||||
|
|
@ -250,6 +250,19 @@
|
|||
struct getdns_context *context = NULL;
|
||||
struct getdns_dict *response = NULL;
|
||||
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 type;
|
||||
uint32_t tc;
|
||||
|
|
@ -264,11 +277,15 @@
|
|||
/* Re-do over TCP */
|
||||
ASSERT_RC(getdns_dict_set_int(extensions,"return_call_reporting", GETDNS_EXTENSION_TRUE),
|
||||
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),
|
||||
GETDNS_RETURN_GOOD, "Return code from getdns_context_set_dns_transport()");
|
||||
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()");
|
||||
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()");
|
||||
|
||||
ASSERT_RC(getdns_dict_get_int(response, "status", &status),
|
||||
|
|
@ -283,6 +300,8 @@
|
|||
}
|
||||
|
||||
CONTEXT_DESTROY;
|
||||
getdns_dict_destroy(extensions);
|
||||
getdns_list_destroy(root_servers);
|
||||
|
||||
}
|
||||
END_TEST
|
||||
|
|
@ -311,7 +330,7 @@
|
|||
GETDNS_RETURN_GOOD, "Return code from getdns_context_set_dns_transport()");
|
||||
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()");
|
||||
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()");
|
||||
|
||||
ASSERT_RC(getdns_dict_get_int(response, "status", &status),
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/**
|
||||
* \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
|
||||
* Paul Hoffman.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/**
|
||||
* \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
|
||||
* Paul Hoffman.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/**
|
||||
* \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
|
||||
* Paul Hoffman.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/**
|
||||
* \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
|
||||
* Paul Hoffman.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/**
|
||||
* \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
|
||||
* Paul Hoffman.
|
||||
|
|
|
|||
|
|
@ -1521,6 +1521,14 @@ error:
|
|||
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
|
||||
main(int argc, char **argv)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -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
|
||||
* 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 *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_GENERAL_ERROR if out of memory
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue