te_t S, dane_query_t * R, const char * HOST, const char * PROTO, unsigned int PORT) S: The DANE state structure R: A structure to place the result HOST: The host name to resolve. PROTO: The protocol type (tcp, udp, etc.) PORT: The service port number (eg. 443). This function will query the DNS server for the TLSA (DANE) data for the given host. *Returns:* On success, ‘DANE_E_SUCCESS’ (0) is returned, otherwise a negative error value. dane_query_to_raw_tlsa ---------------------- -- Function: int dane_query_to_raw_tlsa (dane_query_t Q, unsigned int * DATA_ENTRIES, char *** DANE_DATA, int ** DANE_DATA_LEN, int * SECURE, int * BOGUS) Q: The query result structure DATA_ENTRIES: Pointer set to the number of entries in the query 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 ‘dane_query_deinit()’ is called. DANE_DATA_LEN: Pointer to contain the length n bytes of the dane_data items SECURE: Pointer set true if the result is validated securely, false if validation failed or the domain queried has no security info 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 ‘gnutls_malloc()’ to contain the data from the query result structure (individual ‘dane_data’ items simply point to the original data and are not allocated separately). The returned ‘dane_data’ are only valid during the lifetime of ‘q’ . *Returns:* On success, ‘DANE_E_SUCCESS’ (0) is returned, otherwise a negative error value. dane_raw_tlsa ------------- -- Function: int dane_raw_tlsa (dane_state_t S, dane_query_t * R, char *const * DANE_DATA, const int * DANE_DATA_LEN, int SECURE, int BOGUS) S: The DANE state structure R: A structure to place the result DANE_DATA: array of DNS rdata items, terminated with a NULL pointer; caller must guarantee that the referenced data remains valid until ‘dane_query_deinit()’ is called. DANE_DATA_LEN: the length n bytes of the dane_data items SECURE: true if the result is validated securely, false if validation failed or the domain queried has no security info 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 ‘dane_data’ must be valid during the lifetime of the query. *Returns:* On success, ‘DANE_E_SUCCESS’ (0) is returned, otherwise a negative error value. dane_state_deinit ----------------- -- Function: void dane_state_deinit (dane_state_t S) S: The structure to be deinitialized This function will deinitialize a DANE query structure. dane_state_init --------------- -- Function: int dane_state_init (dane_state_t * S, unsigned int FLAGS) S: The structure to be initialized FLAGS: flags from the ‘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. *Returns:* On success, ‘DANE_E_SUCCESS’ (0) is returned, otherwise a negative error value. dane_state_set_dlv_file ----------------------- -- Function: int dane_state_set_dlv_file (dane_state_t S, const char * FILE) S: The structure to be deinitialized FILE: The file holding the DLV keys. This function will set a file with trusted keys for DLV (DNSSEC Lookaside Validation). dane_strerror ------------- -- Function: const char * dane_strerror (int ERROR) 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 ‘NULL’ . Error codes are always a negative error code. *Returns:* A string explaining the DANE error message. dane_verification_status_print ------------------------------ -- Function: int dane_verification_status_print (unsigned int STATUS, gnutls_datum_t * OUT, unsigned int FLAGS) STATUS: The status flags to be printed OUT: Newly allocated datum with (0) terminated string. FLAGS: should be zero This function will pretty print the status of a verification process - eg. the one obtained by ‘dane_verify_crt()’ . The output ‘out’ needs to be deallocated using ‘gnutls_free()’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. dane_verify_crt --------------- -- Function: int dane_verify_crt (dane_state_t S, const gnutls_datum_t * CHAIN, unsigned CHAIN_SIZE, gnutls_certificate_type_t CHAIN_TYPE, const char * HOSTNAME, const char * PROTO, unsigned int PORT, unsigned int SFLAGS, unsigned int VFLAGS, unsigned int * VERIFY) S: A DANE state structure (may be NULL) CHAIN: A certificate chain CHAIN_SIZE: The size of the chain CHAIN_TYPE: The type of the certificate chain HOSTNAME: The hostname associated with the chain PROTO: The protocol of the service connecting (e.g. tcp) PORT: The port of the service connecting (e.g. 443) SFLAGS: Flags for the initialization of ‘s’ (if NULL) VFLAGS: Verification flags; an OR'ed list of ‘dane_verify_flags_t’ . VERIFY: An OR'ed list of ‘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 ‘DANE_VERIFY_NO_DANE_INFO’ is set. If a DNSSEC signature is not available for the DANE record then the verify flag ‘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 verification. Note that this function is designed to be run in addition to PKIX - certificate chain - verification. To be run independently the ‘DANE_VFLAG_ONLY_CHECK_EE_USAGE’ flag should be specified; then the function will check whether the key of the peer matches the key advertised in the DANE entry. *Returns:* a negative error code on error and ‘DANE_E_SUCCESS’ (0) when the DANE entries were successfully parsed, irrespective of whether they were verified (see ‘verify’ for that information). If no usable entries were encountered ‘DANE_E_REQUESTED_DATA_NOT_AVAILABLE’ will be returned. dane_verify_crt_raw ------------------- -- Function: int dane_verify_crt_raw (dane_state_t S, const gnutls_datum_t * CHAIN, unsigned CHAIN_SIZE, gnutls_certificate_type_t CHAIN_TYPE, dane_query_t R, unsigned int SFLAGS, unsigned int VFLAGS, unsigned int * VERIFY) S: A DANE state structure (may be NULL) CHAIN: A certificate chain CHAIN_SIZE: The size of the chain CHAIN_TYPE: The type of the certificate chain R: DANE data to check against SFLAGS: Flags for the initialization of ‘s’ (if NULL) VFLAGS: Verification flags; an OR'ed list of ‘dane_verify_flags_t’ . VERIFY: An OR'ed list of ‘dane_verify_status_t’ . This is the low-level function of ‘dane_verify_crt()’ . See the high level function for documentation. This function does not perform any resolving, it utilizes cached entries from ‘r’ . *Returns:* a negative error code on error and ‘DANE_E_SUCCESS’ (0) when the DANE entries were successfully parsed, irrespective of whether they were verified (see ‘verify’ for that information). If no usable entries were encountered ‘DANE_E_REQUESTED_DATA_NOT_AVAILABLE’ will be returned. dane_verify_session_crt ----------------------- -- Function: int dane_verify_session_crt (dane_state_t S, gnutls_session_t SESSION, const char * HOSTNAME, const char * PROTO, unsigned int PORT, unsigned int SFLAGS, unsigned int VFLAGS, unsigned int * VERIFY) S: A DANE state structure (may be NULL) SESSION: A gnutls session HOSTNAME: The hostname associated with the chain PROTO: The protocol of the service connecting (e.g. tcp) PORT: The port of the service connecting (e.g. 443) SFLAGS: Flags for the initialization of ‘s’ (if NULL) VFLAGS: Verification flags; an OR'ed list of ‘dane_verify_flags_t’ . VERIFY: An OR'ed list of ‘dane_verify_status_t’ . This function will verify session's certificate chain against the CA constrains and/or the certificate available via DANE. See ‘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 ‘gnutls_certificate_verify_peers3()’ . *Returns:* a negative error code on error and ‘DANE_E_SUCCESS’ (0) when the DANE entries were successfully parsed, irrespective of whether they were verified (see ‘verify’ for that information). If no usable entries were encountered ‘DANE_E_REQUESTED_DATA_NOT_AVAILABLE’ will be returned.