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)
int	getdns_pretty_snprint_dict (char *str, size_t size, const getdns_dict *dict)
char *	getdns_pretty_print_list (const getdns_list *some_list)
int	getdns_pretty_snprint_list (char *str, size_t size, const getdns_list *list)
char *	getdns_print_json_dict (const getdns_dict *some_dict, int pretty)
int	getdns_snprint_json_dict (char *str, size_t size, const getdns_dict *dict, int pretty)
char *	getdns_print_json_list (const getdns_list *some_list, int pretty)
int	getdns_snprint_json_list (char *str, size_t size, const getdns_list *list, int pretty)
getdns_return_t	getdns_rr_dict2wire (const getdns_dict *rr_dict, uint8_t **wire, size_t *wire_sz)
getdns_return_t	getdns_rr_dict2wire_buf (const getdns_dict *rr_dict, uint8_t *wire, size_t *wire_sz)
getdns_return_t	getdns_rr_dict2wire_scan (const getdns_dict *rr_dict, uint8_t **wire, int *wire_sz)
getdns_return_t	getdns_wire2rr_dict (const uint8_t *wire, size_t wire_sz, getdns_dict **rr_dict)
getdns_return_t	getdns_wire2rr_dict_buf (const uint8_t *wire, size_t *wire_sz, getdns_dict **rr_dict)
getdns_return_t	getdns_wire2rr_dict_scan (const uint8_t **wire, size_t *wire_sz, getdns_dict **rr_dict)
getdns_return_t	getdns_rr_dict2str (const getdns_dict *rr_dict, char **str)
getdns_return_t	getdns_rr_dict2str_buf (const getdns_dict *rr_dict, char *str, size_t *str_len)
getdns_return_t	getdns_rr_dict2str_scan (const getdns_dict *rr_dict, char **str, int *str_len)
getdns_return_t	getdns_str2rr_dict (const char *str, getdns_dict **rr_dict, const char *origin, uint32_t default_ttl)
getdns_return_t	getdns_fp2rr_list (FILE *in, getdns_list **rr_list, const char *origin, uint32_t default_ttl)
getdns_return_t	getdns_msg_dict2wire (const getdns_dict *msg_dict, uint8_t **wire, size_t *wire_sz)
getdns_return_t	getdns_msg_dict2wire_buf (const getdns_dict *msg_dict, uint8_t *wire, size_t *wire_sz)
getdns_return_t	getdns_msg_dict2wire_scan (const getdns_dict *msg_dict, uint8_t **wire, int *wire_sz)
getdns_return_t	getdns_wire2msg_dict (const uint8_t *wire, size_t wire_sz, getdns_dict **msg_dict)
getdns_return_t	getdns_wire2msg_dict_buf (const uint8_t *wire, size_t *wire_sz, getdns_dict **msg_dict)
getdns_return_t	getdns_wire2msg_dict_scan (const uint8_t **wire, size_t *wire_sz, getdns_dict **msg_dict)
getdns_return_t	getdns_msg_dict2str (const getdns_dict *msg_dict, char **str)
getdns_return_t	getdns_msg_dict2str_buf (const getdns_dict *msg_dict, char *str, size_t *str_len)
getdns_return_t	getdns_msg_dict2str_scan (const getdns_dict *msg_dict, char **str, int *str_len)

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.

int getdns_pretty_snprint_dict	(	char *	str,
		size_t	size,
		const getdns_dict *	dict
	)

Pretty print the getdns_dict in a given buffer snprintf style.

Parameters

str	pointer to the buffer to print to
size	size of the given buffer. No more than size bytes (including the terminating null byte) will be written to str.
dict	getdns_dict to print

Returns

The number of characters written excluding the terminating null byte or the number of characters which would have been written if enough space had been available.

char* getdns_pretty_print_list

(

const getdns_list *

some_list

)

creates a string that describes the list in a human readable form.

Parameters

some_list

list to pretty print

Returns

character array (caller must free this) containing pretty string

int getdns_pretty_snprint_list	(	char *	str,
		size_t	size,
		const getdns_list *	list
	)

Pretty print the getdns_list in a given buffer snprintf style.

Parameters

str	pointer to the buffer to print to
size	size of the given buffer. No more than size bytes (including the terminating null byte) will be written to str.
list	getdns_list to print

Returns

The number of characters written excluding the terminating null byte or the number of characters which would have been written if enough space had been available.

char* getdns_print_json_dict	(	const getdns_dict *	some_dict,
		int	pretty
	)

creates a string containing a json representation of some_dict. bindatas are converted to strings when possible, including bindatas for addresses, dnames and other printable data. All other bindatas are converted to lists of byte values.

Parameters

some_dict	dict to represent as json data
pretty	when non-zero returns formatted json

Returns

character array (caller must free this) containing pretty string

int getdns_snprint_json_dict	(	char *	str,
		size_t	size,
		const getdns_dict *	dict,
		int	pretty
	)

Prints a json representation of dict in a given buffer snprintf style. bindatas are converted to strings when possible, including bindatas for addresses, dnames and other printable data. All other bindatas are converted to lists of byte values.

Parameters

str	pointer to the buffer to print to
size	size of the given buffer. No more than size bytes (including the terminating null byte) will be written to str.
dict	dict to represent as json data
pretty	when non-zero returns formatted json

Returns

The number of characters written excluding the terminating null byte or the number of characters which would have been written if enough space had been available.

char* getdns_print_json_list	(	const getdns_list *	some_list,
		int	pretty
	)

creates a string containing a json representation of some_list. bindatas are converted to strings when possible, including bindatas for addresses, dnames and other printable data. All other bindatas are converted to lists of byte values.

Parameters

some_list	list to represent as json data
pretty	when non-zero returns formatted json

Returns

character array (caller must free this) containing pretty string

int getdns_snprint_json_list	(	char *	str,
		size_t	size,
		const getdns_list *	list,
		int	pretty
	)

Prints a json representation of list in a given buffer snprintf style. bindatas are converted to strings when possible, including bindatas for addresses, dnames and other printable data. All other bindatas are converted to lists of byte values.

Parameters

str	pointer to the buffer to print to
size	size of the given buffer. No more than size bytes (including the terminating null byte) will be written to str.
list	list to represent as json data
pretty	when non-zero returns formatted json

Returns

The number of characters written excluding the terminating null byte or the number of characters which would have been written if enough space had been available.

getdns_return_t getdns_rr_dict2wire	(	const getdns_dict *	rr_dict,
		uint8_t **	wire,
		size_t *	wire_sz
	)

Convert rr_dict to wireformat representation of the resource record.

Parameters

rr_dict	The getdns dict representation of the resource record
wire	A newly allocated buffer which will contain the wireformat.
wire_sz	The size of the allocated buffer and the wireformat.

Returns

GETDNS_RETURN_GOOD on success or an error code on failure.

getdns_return_t getdns_rr_dict2wire_buf	(	const getdns_dict *	rr_dict,
		uint8_t *	wire,
		size_t *	wire_sz
	)

Convert rr_dict to wireformat representation of the resource record.

Parameters

rr_dict	The getdns dict representation of the resource record
wire	The buffer in which the wireformat will be written
wire_sz	On input the size of the wire buffer, On output the amount of wireformat needed for the wireformat representation of the resource record; even if it did not fit.

Returns

GETDNS_RETURN_GOOD on success or an error code on failure. GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too small. wire_sz will be set to the needed buffer space then.

getdns_return_t getdns_rr_dict2wire_scan	(	const getdns_dict *	rr_dict,
		uint8_t **	wire,
		int *	wire_sz
	)

Convert rr_dict to wireformat representation of the resource record.

Parameters

rr_dict	The getdns dict representation of the resource record
wire	A pointer to the buffer pointer in which the wireformat will be written. On output the buffer pointer will have moved along the buffer and point right after the just written RR.
wire_sz	On input the size of the wire buffer, On output the amount of wireformat needed for the wireformat will have been substracted from wire_sz.

Returns

GETDNS_RETURN_GOOD on success or an error code on failure. GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too small. The function will pretend that it had written beyond the end of the buffer, and wire will point past the buffer and wire_sz will contain a negative value.

getdns_return_t getdns_wire2rr_dict	(	const uint8_t *	wire,
		size_t	wire_sz,
		getdns_dict **	rr_dict
	)

Convert wireformat resource record in a getdns rr_dict representation.

Parameters

wire	Buffer containing the wireformat rr
wire_sz	Size of the wire buffer
rr_dict	The returned rr_dict

Returns

GETDNS_RETURN_GOOD on success or an error code on failure.

getdns_return_t getdns_wire2rr_dict_buf	(	const uint8_t *	wire,
		size_t *	wire_sz,
		getdns_dict **	rr_dict
	)

Convert wireformat resource record in a getdns rr_dict representation.

Parameters

wire	Buffer containing the wireformat rr
wire_sz	On input the size of the wire buffer On output the length of the wireformat rr.
rr_dict	The returned rr_dict

Returns

GETDNS_RETURN_GOOD on success or an error code on failure.

getdns_return_t getdns_wire2rr_dict_scan	(	const uint8_t **	wire,
		size_t *	wire_sz,
		getdns_dict **	rr_dict
	)

Convert wireformat resource record in a getdns rr_dict representation.

Parameters

wire	A pointer to the pointer of the wireformat buffer. On return this pointer is moved to after first read in resource record.
wire_sz	On input the size of the wire buffer On output the size is decreased with the length of the wireformat resource record.
rr_dict	The returned rr_dict

Returns

GETDNS_RETURN_GOOD on success or an error code on failure.

getdns_return_t getdns_rr_dict2str	(	const getdns_dict *	rr_dict,
		char **	str
	)

Convert rr_dict to the string representation of the resource record.

Parameters

rr_dict	The getdns dict representation of the resource record
str	A newly allocated string representation of the rr

Returns

GETDNS_RETURN_GOOD on success or an error code on failure.

getdns_return_t getdns_rr_dict2str_buf	(	const getdns_dict *	rr_dict,
		char *	str,
		size_t *	str_len
	)

Convert rr_dict to the string representation of the resource record.

Parameters

rr_dict	The getdns dict representation of the resource record
str	The buffer in which the string will be written
str_len	On input the size of the text buffer, On output the amount of characters needed to write the string representation of the rr. Even if it does not fit.

Returns

GETDNS_RETURN_GOOD on success or an error code on failure. GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too small. str_len will be set to the needed buffer space then.

getdns_return_t getdns_rr_dict2str_scan	(	const getdns_dict *	rr_dict,
		char **	str,
		int *	str_len
	)

Convert rr_dict to the string representation of the resource record.

Parameters

rr_dict	The getdns dict representation of the resource record
str	A pointer to the buffer pointer in which the string will be written. On output the buffer pointer will have moved along the buffer and point right after the just written RR.
str_len	On input the size of the str buffer, On output the number of characters needed for the string will have been substracted from strlen.

Returns

GETDNS_RETURN_GOOD on success or an error code on failure. GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too small. The function will pretend that it had written beyond the end of the buffer, and str will point past the buffer and str_len will contain a negative value.

getdns_return_t getdns_str2rr_dict	(	const char *	str,
		getdns_dict **	rr_dict,
		const char *	origin,
		uint32_t	default_ttl
	)

Convert the string representation of the resource record to rr_dict format.

Parameters

str	String representation of the resource record.
rr_dict	The result getdns dict representation of the resource record
origin	Default suffix for not fully qualified domain names
default_ttl	Default ttl

Returns

GETDNS_RETURN_GOOD on success or an error code on failure.

getdns_return_t getdns_fp2rr_list	(	FILE *	in,
		getdns_list **	rr_list,
		const char *	origin,
		uint32_t	default_ttl
	)

Read the zonefile and convert to a list of rr_dict's.

Parameters

in	An opened FILE pointer on the zone file.
rr_list	The result list of rr_dicts representing the zone file.
origin	Default suffix for not fully qualified domain names
default_ttl	Default ttl

Returns

GETDNS_RETURN_GOOD on success or an error code on failure.

getdns_return_t getdns_msg_dict2wire	(	const getdns_dict *	msg_dict,
		uint8_t **	wire,
		size_t *	wire_sz
	)

Convert DNS message dict to wireformat representation.

Parameters

msg_dict	The getdns dict representation of a DNS message
wire	A newly allocated buffer which will contain the wireformat.
wire_sz	The size of the allocated buffer and the wireformat.

Returns

GETDNS_RETURN_GOOD on success or an error code on failure.

getdns_return_t getdns_msg_dict2wire_buf	(	const getdns_dict *	msg_dict,
		uint8_t *	wire,
		size_t *	wire_sz
	)

Convert DNS message dict to wireformat representation.

Parameters

msg_dict	The getdns dict representation of a DNS message
wire	The buffer in which the wireformat will be written
wire_sz	On input the size of the wire buffer, On output the amount of wireformat needed for the wireformat representation of the DNS message; even if it did not fit.

Returns

GETDNS_RETURN_GOOD on success or an error code on failure. GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too small. wire_sz will be set to the needed buffer space then.

getdns_return_t getdns_msg_dict2wire_scan	(	const getdns_dict *	msg_dict,
		uint8_t **	wire,
		int *	wire_sz
	)

Convert DNS message dict to wireformat representation.

Parameters

msg_dict	The getdns dict representation of the DNS message
wire	A pointer to the buffer pointer in which the wireformat will be written. On output the buffer pointer will have moved along the buffer and point right after the just written RR.
wire_sz	On input the size of the wire buffer, On output the amount of wireformat needed for the wireformat will have been substracted from wire_sz.

Returns

GETDNS_RETURN_GOOD on success or an error code on failure. GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too small. The function will pretend that it had written beyond the end of the buffer, and wire will point past the buffer and wire_sz will contain a negative value.

getdns_return_t getdns_wire2msg_dict	(	const uint8_t *	wire,
		size_t	wire_sz,
		getdns_dict **	msg_dict
	)

Convert wireformat DNS message in a getdns msg_dict representation.

Parameters

wire	Buffer containing the wireformat rr
wire_sz	Size of the wire buffer
msg_dict	The returned DNS message

Returns

GETDNS_RETURN_GOOD on success or an error code on failure.

getdns_return_t getdns_wire2msg_dict_buf	(	const uint8_t *	wire,
		size_t *	wire_sz,
		getdns_dict **	msg_dict
	)

Convert wireformat DNS message in a getdns msg_dict representation.

Parameters

wire	Buffer containing the wireformat rr
wire_sz	On input the size of the wire buffer On output the length of the wireformat rr.
msg_dict	The returned DNS message

Returns

GETDNS_RETURN_GOOD on success or an error code on failure.

getdns_return_t getdns_wire2msg_dict_scan	(	const uint8_t **	wire,
		size_t *	wire_sz,
		getdns_dict **	msg_dict
	)

Convert wireformat DNS message in a getdns msg_dic representation.

Parameters

wire	A pointer to the pointer of the wireformat buffer. On return this pointer is moved to after first read in resource record.
wire_sz	On input the size of the wire buffer On output the size is decreased with the length of the wireformat DNS message.
msg_dict	The returned DNS message

Returns

GETDNS_RETURN_GOOD on success or an error code on failure.

getdns_return_t getdns_msg_dict2str	(	const getdns_dict *	msg_dict,
		char **	str
	)

Convert msg_dict to the string representation of the DNS message.

Parameters

msg_dict	The getdns dict representation of the DNS message
str	A newly allocated string representation of the rr

Returns

GETDNS_RETURN_GOOD on success or an error code on failure.

getdns_return_t getdns_msg_dict2str_buf	(	const getdns_dict *	msg_dict,
		char *	str,
		size_t *	str_len
	)

Convert msg_dict to the string representation of the DNS message.

Parameters

msg_dict	The getdns dict representation of the resource record
str	The buffer in which the string will be written
str_len	On input the size of the text buffer, On output the amount of characters needed to write the string representation of the rr. Even if it does not fit.

Returns

GETDNS_RETURN_GOOD on success or an error code on failure. GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too small. str_len will be set to the needed buffer space then.

getdns_return_t getdns_msg_dict2str_scan	(	const getdns_dict *	msg_dict,
		char **	str,
		int *	str_len
	)

Convert msg_dict to the string representation of the resource record.

Parameters

msg_dict	The getdns dict representation of the resource record
str	A pointer to the buffer pointer in which the string will be written. On output the buffer pointer will have moved along the buffer and point right after the just written RR.
str_len	On input the size of the str buffer, On output the number of characters needed for the string will have been substracted from strlen.

Returns

GETDNS_RETURN_GOOD on success or an error code on failure. GETDNS_RETURN_NEED_MORE_SPACE will be returned when the buffer was too small. The function will pretend that it had written beyond the end of the buffer, and str will point past the buffer and str_len will contain a negative value.