@subheading dane_cert_type_name

@anchor{dane_cert_type_name}

@deftypefun {const char *} {dane_cert_type_name} (dane_cert_type_t @var{type})

@var{type}: is a DANE match type

Convert a @code{dane_cert_type_t}  value to a string.

@strong{Returns:} a string that contains the name of the specified

type, or @code{NULL} .

@end deftypefun

@subheading dane_cert_usage_name

@anchor{dane_cert_usage_name}

@deftypefun {const char *} {dane_cert_usage_name} (dane_cert_usage_t @var{usage})

@var{usage}: is a DANE certificate usage

Convert a @code{dane_cert_usage_t}  value to a string.

@strong{Returns:} a string that contains the name of the specified

type, or @code{NULL} .

@end deftypefun

@subheading dane_match_type_name

@anchor{dane_match_type_name}

@deftypefun {const char *} {dane_match_type_name} (dane_match_type_t @var{type})

@var{type}: is a DANE match type

Convert a @code{dane_match_type_t}  value to a string.

@strong{Returns:} a string that contains the name of the specified

type, or @code{NULL} .

@end deftypefun

@subheading dane_query_data

@anchor{dane_query_data}

@deftypefun {int} {dane_query_data} (dane_query_t @var{q}, unsigned int @var{idx}, unsigned int * @var{usage}, unsigned int * @var{type}, unsigned int * @var{match}, gnutls_datum_t * @var{data})

@var{q}: The query result structure

@var{idx}: The index of the query response.

@var{usage}: The certificate usage (see @code{dane_cert_usage_t} )

@var{type}: The certificate type (see @code{dane_cert_type_t} )

@var{match}: The DANE matching type (see @code{dane_match_type_t} )

@var{data}: The DANE data.

This function will provide the DANE data from the query

response.

@strong{Returns:} On success, @code{DANE_E_SUCCESS}  (0) is returned, otherwise a

negative error value.

@end deftypefun

@subheading dane_query_deinit

@anchor{dane_query_deinit}

@deftypefun {void} {dane_query_deinit} (dane_query_t @var{q})

@var{q}: The structure to be deinitialized

This function will deinitialize a DANE query result structure.

@end deftypefun

@subheading dane_query_entries

@anchor{dane_query_entries}

@deftypefun {unsigned int} {dane_query_entries} (dane_query_t @var{q})

@var{q}: The query result structure

This function will return the number of entries in a query.

@strong{Returns:} The number of entries.

@end deftypefun

@subheading dane_query_status

@anchor{dane_query_status}

@deftypefun {dane_query_status_t} {dane_query_status} (dane_query_t @var{q})

@var{q}: The query result structure

This function will return the status of the query response.

See @code{dane_query_status_t}  for the possible types.

@strong{Returns:} The status type.

@end deftypefun

@subheading dane_query_tlsa

@anchor{dane_query_tlsa}

@deftypefun {int} {dane_query_tlsa} (dane_state_t @var{s}, dane_query_t * @var{r}, const char * @var{host}, const char * @var{proto}, unsigned int @var{port})

@var{s}: The DANE state structure

@var{r}: A structure to place the result

@var{host}: The host name to resolve.

@var{proto}: The protocol type (tcp, udp, etc.)

@var{port}: The service port number (eg. 443).

This function will query the DNS server for the TLSA (DANE)

data for the given host.

@strong{Returns:} On success, @code{DANE_E_SUCCESS}  (0) is returned, otherwise a

negative error value.

@end deftypefun

@subheading dane_query_to_raw_tlsa

@anchor{dane_query_to_raw_tlsa}

@deftypefun {int} {dane_query_to_raw_tlsa} (dane_query_t @var{q}, unsigned int * @var{data_entries}, char *** @var{dane_data}, int ** @var{dane_data_len}, int * @var{secure}, int * @var{bogus})

@var{q}: The query result structure

@var{data_entries}: Pointer set to the number of entries in the query

@var{dane_data}: Pointer to contain an array of DNS rdata items, terminated with a NULL pointer;

caller must guarantee that the referenced data remains

valid until @code{dane_query_deinit()}  is called.

@var{dane_data_len}: Pointer to contain the length n bytes of the dane_data items

@var{secure}: Pointer set true if the result is validated securely, false if

validation failed or the domain queried has no security info

@var{bogus}: Pointer set true if the result was not secure due to a security failure

This function will provide the DANE data from the query

response.

The pointers dane_data and dane_data_len are allocated with @code{gnutls_malloc()} 

to contain the data from the query result structure (individual

 @code{dane_data} items simply point to the original data and are not allocated separately).

The returned  @code{dane_data} are only valid during the lifetime of  @code{q} .

@strong{Returns:} On success, @code{DANE_E_SUCCESS}  (0) is returned, otherwise a

negative error value.

@end deftypefun

@subheading dane_raw_tlsa

@anchor{dane_raw_tlsa}

@deftypefun {int} {dane_raw_tlsa} (dane_state_t @var{s}, dane_query_t * @var{r}, char *const * @var{dane_data}, const int * @var{dane_data_len}, int @var{secure}, int @var{bogus})

@var{s}: The DANE state structure

@var{r}: A structure to place the result

@var{dane_data}: array of DNS rdata items, terminated with a NULL pointer;

caller must guarantee that the referenced data remains

valid until @code{dane_query_deinit()}  is called.

@var{dane_data_len}: the length n bytes of the dane_data items

@var{secure}: true if the result is validated securely, false if

validation failed or the domain queried has no security info

@var{bogus}: if the result was not secure (secure = 0) due to a security failure,

and the result is due to a security failure, bogus is true.

This function will fill in the TLSA (DANE) structure from

the given raw DNS record data. The  @code{dane_data} must be valid

during the lifetime of the query.

@strong{Returns:} On success, @code{DANE_E_SUCCESS}  (0) is returned, otherwise a

negative error value.

@end deftypefun

@subheading dane_state_deinit

@anchor{dane_state_deinit}

@deftypefun {void} {dane_state_deinit} (dane_state_t @var{s})

@var{s}: The structure to be deinitialized

This function will deinitialize a DANE query structure.

@end deftypefun

@subheading dane_state_init

@anchor{dane_state_init}

@deftypefun {int} {dane_state_init} (dane_state_t * @var{s}, unsigned int @var{flags})

@var{s}: The structure to be initialized

@var{flags}: flags from the @code{dane_state_flags}  enumeration

This function will initialize the backend resolver. It is

intended to be used in scenarios where multiple resolvings

occur, to optimize against multiple re-initializations.

@strong{Returns:} On success, @code{DANE_E_SUCCESS}  (0) is returned, otherwise a

negative error value.

@end deftypefun

@subheading dane_state_set_dlv_file

@anchor{dane_state_set_dlv_file}

@deftypefun {int} {dane_state_set_dlv_file} (dane_state_t @var{s}, const char * @var{file})

@var{s}: The structure to be deinitialized

@var{file}: The file holding the DLV keys.

This function will set a file with trusted keys

for DLV (DNSSEC Lookaside Validation).

@end deftypefun

@subheading dane_strerror

@anchor{dane_strerror}

@deftypefun {const char *} {dane_strerror} (int @var{error})

@var{error}: is a DANE error code, a negative error code

This function is similar to strerror.  The difference is that it

accepts an error number returned by a gnutls function; In case of

an unknown error a descriptive string is sent instead of @code{NULL} .

Error codes are always a negative error code.

@strong{Returns:} A string explaining the DANE error message.

@end deftypefun

@subheading dane_verification_status_print

@anchor{dane_verification_status_print}

@deftypefun {int} {dane_verification_status_print} (unsigned int @var{status}, gnutls_datum_t * @var{out}, unsigned int @var{flags})

@var{status}: The status flags to be printed

@var{out}: Newly allocated datum with (0) terminated string.

@var{flags}: should be zero

This function will pretty print the status of a verification

process -- eg. the one obtained by @code{dane_verify_crt()} .

The output  @code{out} needs to be deallocated using @code{gnutls_free()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise a

negative error value.

@end deftypefun

@subheading dane_verify_crt

@anchor{dane_verify_crt}

@deftypefun {int} {dane_verify_crt} (dane_state_t @var{s}, const gnutls_datum_t * @var{chain}, unsigned @var{chain_size}, gnutls_certificate_type_t @var{chain_type}, const char * @var{hostname}, const char * @var{proto}, unsigned int @var{port}, unsigned int @var{sflags}, unsigned int @var{vflags}, unsigned int * @var{verify})

@var{s}: A DANE state structure (may be NULL)

@var{chain}: A certificate chain

@var{chain_size}: The size of the chain

@var{chain_type}: The type of the certificate chain

@var{hostname}: The hostname associated with the chain

@var{proto}: The protocol of the service connecting (e.g. tcp)

@var{port}: The port of the service connecting (e.g. 443)

@var{sflags}: Flags for the initialization of  @code{s} (if NULL)

@var{vflags}: Verification flags; an OR'ed list of @code{dane_verify_flags_t} .

@var{verify}: An OR'ed list of @code{dane_verify_status_t} .

This function will verify the given certificate chain against the

CA constrains and/or the certificate available via DANE.

If no information via DANE can be obtained the flag @code{DANE_VERIFY_NO_DANE_INFO} 

is set. If a DNSSEC signature is not available for the DANE

record then the verify flag @code{DANE_VERIFY_NO_DNSSEC_DATA}  is set.

Due to the many possible options of DANE, there is no single threat

model countered. When notifying the user about DANE verification results

it may be better to mention: DANE verification did not reject the certificate,

rather than mentioning a successful DANE verication.

Note that this function is designed to be run in addition to

PKIX - certificate chain - verification. To be run independently

the @code{DANE_VFLAG_ONLY_CHECK_EE_USAGE}  flag should be specified;

then the function will check whether the key of the peer matches the

key advertized in the DANE entry.

@strong{Returns:} a negative error code on error and @code{DANE_E_SUCCESS}  (0)

when the DANE entries were successfully parsed, irrespective of

whether they were verified (see  @code{verify} for that information). If

no usable entries were encountered @code{DANE_E_REQUESTED_DATA_NOT_AVAILABLE} 

will be returned.

@end deftypefun

@subheading dane_verify_crt_raw

@anchor{dane_verify_crt_raw}

@deftypefun {int} {dane_verify_crt_raw} (dane_state_t @var{s}, const gnutls_datum_t * @var{chain}, unsigned @var{chain_size}, gnutls_certificate_type_t @var{chain_type}, dane_query_t @var{r}, unsigned int @var{sflags}, unsigned int @var{vflags}, unsigned int * @var{verify})

@var{s}: A DANE state structure (may be NULL)

@var{chain}: A certificate chain

@var{chain_size}: The size of the chain

@var{chain_type}: The type of the certificate chain

@var{r}: DANE data to check against

@var{sflags}: Flags for the initialization of  @code{s} (if NULL)

@var{vflags}: Verification flags; an OR'ed list of @code{dane_verify_flags_t} .

@var{verify}: An OR'ed list of @code{dane_verify_status_t} .

This is the low-level function of @code{dane_verify_crt()} . See the

high level function for documentation.

This function does not perform any resolving, it utilizes

cached entries from  @code{r} .

@strong{Returns:} a negative error code on error and @code{DANE_E_SUCCESS}  (0)

when the DANE entries were successfully parsed, irrespective of

whether they were verified (see  @code{verify} for that information). If

no usable entries were encountered @code{DANE_E_REQUESTED_DATA_NOT_AVAILABLE} 

will be returned.

@end deftypefun

@subheading dane_verify_session_crt

@anchor{dane_verify_session_crt}

@deftypefun {int} {dane_verify_session_crt} (dane_state_t @var{s}, gnutls_session_t @var{session}, const char * @var{hostname}, const char * @var{proto}, unsigned int @var{port}, unsigned int @var{sflags}, unsigned int @var{vflags}, unsigned int * @var{verify})

@var{s}: A DANE state structure (may be NULL)

@var{session}: A gnutls session

@var{hostname}: The hostname associated with the chain

@var{proto}: The protocol of the service connecting (e.g. tcp)

@var{port}: The port of the service connecting (e.g. 443)

@var{sflags}: Flags for the initialization of  @code{s} (if NULL)

@var{vflags}: Verification flags; an OR'ed list of @code{dane_verify_flags_t} .

@var{verify}: An OR'ed list of @code{dane_verify_status_t} .

This function will verify session's certificate chain against the

CA constrains and/or the certificate available via DANE.

See @code{dane_verify_crt()}  for more information.

This will not verify the chain for validity; unless the DANE

verification is restricted to end certificates, this must be

be performed separately using @code{gnutls_certificate_verify_peers3()} .

@strong{Returns:} a negative error code on error and @code{DANE_E_SUCCESS}  (0)

when the DANE entries were successfully parsed, irrespective of

whether they were verified (see  @code{verify} for that information). If

no usable entries were encountered @code{DANE_E_REQUESTED_DATA_NOT_AVAILABLE} 

will be returned.

@end deftypefun