Additional utility functions

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)
const char *	getdns_get_errorstr_by_id (uint16_t err)
getdns_return_t	getdns_dict_util_set_string (getdns_dict *dict, char *name, const char *value)
getdns_return_t	getdns_dict_util_get_string (getdns_dict *dict, char *name, char **result)
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)
getdns_dict *	getdns_pubkey_pin_create_from_string (getdns_context *context, const char *str)
getdns_return_t	getdns_pubkey_pinset_sanity_check (const getdns_list *pinset, getdns_list *errorlist)
getdns_return_t	getdns_context_config (getdns_context *context, const getdns_dict *config_dict)

Detailed Description

Function Documentation

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

)

const char* getdns_get_errorstr_by_id

(

uint16_t

err

)

Returns a text describing the getdns error code, or NULL when the error code is unkown.

Parameters

err	The error code for which to return the describing text

Returns

The describing text for the error code. The string is in library space and the caller must not free this.

getdns_return_t getdns_dict_util_set_string	(	getdns_dict *	dict,
		char *	name,
		const char *	value
	)

getdns_return_t getdns_dict_util_get_string	(	getdns_dict *	dict,
		char *	name,
		char **	result
	)

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
	)

Validate replies or resource records.

Parameters

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.
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.
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.
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.
skew	The numer of seconds of skew that is allowed in either direction when checking an RRSIG's Expiration and Inception fields

Returns

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_dict* getdns_pubkey_pin_create_from_string	(	getdns_context *	context,
		const char *	str
	)

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.

Parameters

context	a context to use to create the dict, or NULL to create it generically
str	the pinning string to parse

Returns

a dict created from ctx, or NULL if the string did not match.

getdns_return_t getdns_pubkey_pinset_sanity_check	(	const getdns_list *	pinset,
		getdns_list *	errorlist
	)

Test whether a given pinset is reasonable, including:

is it well-formed? are there at least two pins? are the digests used sane?

Parameters

pinset	the set of public key pins to check for sanity. This should be a list of dicts.
errorlist	if not NULL, a list of human-readable strings is appended to errorlist.

Returns

GETDNS_RETURN_GOOD if the pinset passes the sanity check.

getdns_return_t getdns_context_config	(	getdns_context *	context,
		const getdns_dict *	config_dict
	)

Configure a context with settings given in a getdns_dict.

Parameters

context

The context to be configured.

config_dict

The getdns_dict containing the settings. The settings have the same name as returned by the getdns_context_get_api_information() function, or as used in the names of the getdns_context_get_*() and getdns_context_set_*() functions. The dict returned by getdns_context_get_api_information() can be used as the config_dict directly, but context settings do not have to be below a "all_context" key. It is possible to set default values for extensions that could otherwise only be given on a per query basis. For example: { dnssec_return_status: GETDNS_EXTENSION_TRUE } is equivalent to using the getdns_context_set_return_dnssec_status() function with that value, but default values for the other extensions can be set by this method now too. For example { return_call_reporting: GETDNS_EXTENSION_TRUE} Trust anchor files and root hints content can also be given by file, for example: { dns_root_servers : "named.root" , dnssec_trust_anchors: "/etc/unbound/getdns-root.key" }

Returns

GETDNS_RETURN_GOOD on success or an error code on failure. Beware that context might be partially configured on error. For retry strategies it is advised to recreate a new config.