path: root/doc/dane-api.texi

@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