From 36082a2fe36ecd800d784ae44c14f1f18c66a7e9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 28 Apr 2024 09:33:12 +0200 Subject: Adding upstream version 3.7.9. Signed-off-by: Daniel Baumann --- doc/dane-api.texi | 341 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 341 insertions(+) create mode 100644 doc/dane-api.texi (limited to 'doc/dane-api.texi') diff --git a/doc/dane-api.texi b/doc/dane-api.texi new file mode 100644 index 0000000..5511734 --- /dev/null +++ b/doc/dane-api.texi @@ -0,0 +1,341 @@ + +@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 + -- cgit v1.2.3