diff options
Diffstat (limited to 'doc/gnutls-api.texi')
| -rw-r--r-- | doc/gnutls-api.texi | 8438 |
1 files changed, 8438 insertions, 0 deletions
diff --git a/doc/gnutls-api.texi b/doc/gnutls-api.texi new file mode 100644 index 0000000..b641407 --- /dev/null +++ b/doc/gnutls-api.texi @@ -0,0 +1,8438 @@ + +@subheading gnutls_alert_get +@anchor{gnutls_alert_get} +@deftypefun {gnutls_alert_description_t} {gnutls_alert_get} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function will return the last alert number received. This +function should be called when @code{GNUTLS_E_WARNING_ALERT_RECEIVED} or +@code{GNUTLS_E_FATAL_ALERT_RECEIVED} errors are returned by a gnutls +function. The peer may send alerts if he encounters an error. +If no alert has been received the returned value is undefined. + +@strong{Returns:} the last alert received, a +@code{gnutls_alert_description_t} value. +@end deftypefun + +@subheading gnutls_alert_get_name +@anchor{gnutls_alert_get_name} +@deftypefun {const char *} {gnutls_alert_get_name} (gnutls_alert_description_t @var{alert}) +@var{alert}: is an alert number. + +This function will return a string that describes the given alert +number, or @code{NULL} . See @code{gnutls_alert_get()} . + +@strong{Returns:} string corresponding to @code{gnutls_alert_description_t} value. +@end deftypefun + +@subheading gnutls_alert_get_strname +@anchor{gnutls_alert_get_strname} +@deftypefun {const char *} {gnutls_alert_get_strname} (gnutls_alert_description_t @var{alert}) +@var{alert}: is an alert number. + +This function will return a string of the name of the alert. + +@strong{Returns:} string corresponding to @code{gnutls_alert_description_t} value. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_alert_send +@anchor{gnutls_alert_send} +@deftypefun {int} {gnutls_alert_send} (gnutls_session_t @var{session}, gnutls_alert_level_t @var{level}, gnutls_alert_description_t @var{desc}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{level}: is the level of the alert + +@var{desc}: is the alert description + +This function will send an alert to the peer in order to inform +him of something important (eg. his Certificate could not be verified). +If the alert level is Fatal then the peer is expected to close the +connection, otherwise he may ignore the alert and continue. + +The error code of the underlying record send function will be +returned, so you may also receive @code{GNUTLS_E_INTERRUPTED} or +@code{GNUTLS_E_AGAIN} as well. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_alert_send_appropriate +@anchor{gnutls_alert_send_appropriate} +@deftypefun {int} {gnutls_alert_send_appropriate} (gnutls_session_t @var{session}, int @var{err}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{err}: is an error code returned by another GnuTLS function + +Sends an alert to the peer depending on the error code returned by +a gnutls function. This function will call @code{gnutls_error_to_alert()} +to determine the appropriate alert to send. + +This function may also return @code{GNUTLS_E_AGAIN} , or +@code{GNUTLS_E_INTERRUPTED} . + +This function historically was always sending an alert to the +peer, even if @code{err} was inappropriate to respond with an alert +(e.g., @code{GNUTLS_E_SUCCESS} ). Since 3.6.6 this function returns +success without transmitting any data on error codes that +should not result to an alert. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_alert_set_read_function +@anchor{gnutls_alert_set_read_function} +@deftypefun {void} {gnutls_alert_set_read_function} (gnutls_session_t @var{session}, gnutls_alert_read_func @var{func}) +@var{session}: is @code{gnutls_session_t} type + +@var{func}: is the function to be called + +This function will set a callback to be called when an alert +message is being sent. + +@strong{Since:} 3.7.0 +@end deftypefun + +@subheading gnutls_alpn_get_selected_protocol +@anchor{gnutls_alpn_get_selected_protocol} +@deftypefun {int} {gnutls_alpn_get_selected_protocol} (gnutls_session_t @var{session}, gnutls_datum_t * @var{protocol}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{protocol}: will hold the protocol name + +This function allows you to get the negotiated protocol name. The +returned protocol should be treated as opaque, constant value and +only valid during the session life. + +The selected protocol is the first supported by the list sent +by the client. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +Since 3.2.0 +@end deftypefun + +@subheading gnutls_alpn_set_protocols +@anchor{gnutls_alpn_set_protocols} +@deftypefun {int} {gnutls_alpn_set_protocols} (gnutls_session_t @var{session}, const gnutls_datum_t * @var{protocols}, unsigned @var{protocols_size}, unsigned int @var{flags}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{protocols}: is the protocol names to add. + +@var{protocols_size}: the number of protocols to add. + +@var{flags}: zero or a sequence of @code{gnutls_alpn_flags_t} + +This function is to be used by both clients and servers, to declare +the supported ALPN protocols, which are used during negotiation with peer. + +See @code{gnutls_alpn_flags_t} description for the documentation of available +flags. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +Since 3.2.0 +@end deftypefun + +@subheading gnutls_anon_allocate_client_credentials +@anchor{gnutls_anon_allocate_client_credentials} +@deftypefun {int} {gnutls_anon_allocate_client_credentials} (gnutls_anon_client_credentials_t * @var{sc}) +@var{sc}: is a pointer to a @code{gnutls_anon_client_credentials_t} type. + +Allocate a gnutls_anon_client_credentials_t structure. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. +@end deftypefun + +@subheading gnutls_anon_allocate_server_credentials +@anchor{gnutls_anon_allocate_server_credentials} +@deftypefun {int} {gnutls_anon_allocate_server_credentials} (gnutls_anon_server_credentials_t * @var{sc}) +@var{sc}: is a pointer to a @code{gnutls_anon_server_credentials_t} type. + +Allocate a gnutls_anon_server_credentials_t structure. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. +@end deftypefun + +@subheading gnutls_anon_free_client_credentials +@anchor{gnutls_anon_free_client_credentials} +@deftypefun {void} {gnutls_anon_free_client_credentials} (gnutls_anon_client_credentials_t @var{sc}) +@var{sc}: is a @code{gnutls_anon_client_credentials_t} type. + +Free a gnutls_anon_client_credentials_t structure. +@end deftypefun + +@subheading gnutls_anon_free_server_credentials +@anchor{gnutls_anon_free_server_credentials} +@deftypefun {void} {gnutls_anon_free_server_credentials} (gnutls_anon_server_credentials_t @var{sc}) +@var{sc}: is a @code{gnutls_anon_server_credentials_t} type. + +Free a gnutls_anon_server_credentials_t structure. +@end deftypefun + +@subheading gnutls_anon_set_params_function +@anchor{gnutls_anon_set_params_function} +@deftypefun {void} {gnutls_anon_set_params_function} (gnutls_anon_server_credentials_t @var{res}, gnutls_params_function * @var{func}) +@var{res}: is a gnutls_anon_server_credentials_t type + +@var{func}: is the function to be called + +This function will set a callback in order for the server to get +the Diffie-Hellman or RSA parameters for anonymous authentication. +The callback should return @code{GNUTLS_E_SUCCESS} (0) on success. + +@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 +or later. Since 3.6.0, DH parameters are negotiated +following RFC7919. +@end deftypefun + +@subheading gnutls_anon_set_server_dh_params +@anchor{gnutls_anon_set_server_dh_params} +@deftypefun {void} {gnutls_anon_set_server_dh_params} (gnutls_anon_server_credentials_t @var{res}, gnutls_dh_params_t @var{dh_params}) +@var{res}: is a gnutls_anon_server_credentials_t type + +@var{dh_params}: The Diffie-Hellman parameters. + +This function will set the Diffie-Hellman parameters for an +anonymous server to use. These parameters will be used in +Anonymous Diffie-Hellman cipher suites. + +@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 +or later. Since 3.6.0, DH parameters are negotiated +following RFC7919. +@end deftypefun + +@subheading gnutls_anon_set_server_known_dh_params +@anchor{gnutls_anon_set_server_known_dh_params} +@deftypefun {int} {gnutls_anon_set_server_known_dh_params} (gnutls_anon_server_credentials_t @var{res}, gnutls_sec_param_t @var{sec_param}) +@var{res}: is a gnutls_anon_server_credentials_t type + +@var{sec_param}: is an option of the @code{gnutls_sec_param_t} enumeration + +This function will set the Diffie-Hellman parameters for an +anonymous server to use. These parameters will be used in +Anonymous Diffie-Hellman cipher suites and will be selected from +the FFDHE set of RFC7919 according to the security level provided. + +@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 +or later. Since 3.6.0, DH parameters are negotiated +following RFC7919. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.5.6 +@end deftypefun + +@subheading gnutls_anon_set_server_params_function +@anchor{gnutls_anon_set_server_params_function} +@deftypefun {void} {gnutls_anon_set_server_params_function} (gnutls_anon_server_credentials_t @var{res}, gnutls_params_function * @var{func}) +@var{res}: is a gnutls_certificate_credentials_t type + +@var{func}: is the function to be called + +This function will set a callback in order for the server to get +the Diffie-Hellman parameters for anonymous authentication. The +callback should return @code{GNUTLS_E_SUCCESS} (0) on success. + +@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 +or later. Since 3.6.0, DH parameters are negotiated +following RFC7919. +@end deftypefun + +@subheading gnutls_anti_replay_deinit +@anchor{gnutls_anti_replay_deinit} +@deftypefun {void} {gnutls_anti_replay_deinit} (gnutls_anti_replay_t @var{anti_replay}) +@var{anti_replay}: is a @code{gnutls_anti_replay} type + +This function will deinitialize all resources occupied by the given +anti-replay context. + +@strong{Since:} 3.6.5 +@end deftypefun + +@subheading gnutls_anti_replay_enable +@anchor{gnutls_anti_replay_enable} +@deftypefun {void} {gnutls_anti_replay_enable} (gnutls_session_t @var{session}, gnutls_anti_replay_t @var{anti_replay}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{anti_replay}: is a @code{gnutls_anti_replay_t} type. + +Request that the server should use anti-replay mechanism. + +@strong{Since:} 3.6.5 +@end deftypefun + +@subheading gnutls_anti_replay_init +@anchor{gnutls_anti_replay_init} +@deftypefun {int} {gnutls_anti_replay_init} (gnutls_anti_replay_t * @var{anti_replay}) +@var{anti_replay}: is a pointer to @code{gnutls_anti_replay_t} type + +This function will allocate and initialize the @code{anti_replay} context +to be usable for detect replay attacks. The context can then be +attached to a @code{gnutls_session_t} with +@code{gnutls_anti_replay_enable()} . + +@strong{Returns:} Zero or a negative error code on error. + +@strong{Since:} 3.6.5 +@end deftypefun + +@subheading gnutls_anti_replay_set_add_function +@anchor{gnutls_anti_replay_set_add_function} +@deftypefun {void} {gnutls_anti_replay_set_add_function} (gnutls_anti_replay_t @var{anti_replay}, gnutls_db_add_func @var{add_func}) +@var{anti_replay}: is a @code{gnutls_anti_replay_t} type. + +@var{add_func}: is the function. + +Sets the function that will be used to store an entry if it is not +already present in the resumed sessions database. This function returns 0 +if the entry is successfully stored, and a negative error code +otherwise. In particular, if the entry is found in the database, +it returns @code{GNUTLS_E_DB_ENTRY_EXISTS} . + +The arguments to the @code{add_func} are: +- @code{ptr} : the pointer set with @code{gnutls_anti_replay_set_ptr()} +- @code{exp_time} : the expiration time of the entry +- @code{key} : a pointer to the key +- @code{data} : a pointer to data to store + +The data set by this function can be examined using +@code{gnutls_db_check_entry_expire_time()} and @code{gnutls_db_check_entry_time()} . + +@strong{Since:} 3.6.5 +@end deftypefun + +@subheading gnutls_anti_replay_set_ptr +@anchor{gnutls_anti_replay_set_ptr} +@deftypefun {void} {gnutls_anti_replay_set_ptr} (gnutls_anti_replay_t @var{anti_replay}, void * @var{ptr}) +@var{anti_replay}: is a @code{gnutls_anti_replay_t} type. + +@var{ptr}: is the pointer + +Sets the pointer that will be provided to db add function +as the first argument. +@end deftypefun + +@subheading gnutls_anti_replay_set_window +@anchor{gnutls_anti_replay_set_window} +@deftypefun {void} {gnutls_anti_replay_set_window} (gnutls_anti_replay_t @var{anti_replay}, unsigned int @var{window}) +@var{anti_replay}: is a @code{gnutls_anti_replay_t} type. + +@var{window}: is the time window recording ClientHello, in milliseconds + +Sets the time window used for ClientHello recording. In order to +protect against replay attacks, the server records ClientHello +messages within this time period from the last update, and +considers it a replay when a ClientHello outside of the period; if +a ClientHello arrives within this period, the server checks the +database and detects duplicates. + +For the details of the algorithm, see RFC 8446, section 8.2. + +@strong{Since:} 3.6.5 +@end deftypefun + +@subheading gnutls_auth_client_get_type +@anchor{gnutls_auth_client_get_type} +@deftypefun {gnutls_credentials_type_t} {gnutls_auth_client_get_type} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Returns the type of credentials that were used for client authentication. +The returned information is to be used to distinguish the function used +to access authentication data. + +Note that on resumed sessions, this function returns the schema +used in the original session authentication. + +@strong{Returns:} The type of credentials for the client authentication +schema, a @code{gnutls_credentials_type_t} type. +@end deftypefun + +@subheading gnutls_auth_get_type +@anchor{gnutls_auth_get_type} +@deftypefun {gnutls_credentials_type_t} {gnutls_auth_get_type} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Returns type of credentials for the current authentication schema. +The returned information is to be used to distinguish the function used +to access authentication data. + +Eg. for CERTIFICATE ciphersuites (key exchange algorithms: +@code{GNUTLS_KX_RSA} , @code{GNUTLS_KX_DHE_RSA} ), the same function are to be +used to access the authentication data. + +Note that on resumed sessions, this function returns the schema +used in the original session authentication. + +@strong{Returns:} The type of credentials for the current authentication +schema, a @code{gnutls_credentials_type_t} type. +@end deftypefun + +@subheading gnutls_auth_server_get_type +@anchor{gnutls_auth_server_get_type} +@deftypefun {gnutls_credentials_type_t} {gnutls_auth_server_get_type} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Returns the type of credentials that were used for server authentication. +The returned information is to be used to distinguish the function used +to access authentication data. + +Note that on resumed sessions, this function returns the schema +used in the original session authentication. + +@strong{Returns:} The type of credentials for the server authentication +schema, a @code{gnutls_credentials_type_t} type. +@end deftypefun + +@subheading gnutls_base64_decode2 +@anchor{gnutls_base64_decode2} +@deftypefun {int} {gnutls_base64_decode2} (const gnutls_datum_t * @var{base64}, gnutls_datum_t * @var{result}) +@var{base64}: contains the encoded data + +@var{result}: the location of decoded data + +This function will decode the given base64 encoded data. The decoded data +will be allocated, and stored into result. + +You should use @code{gnutls_free()} to free the returned data. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_base64_encode2 +@anchor{gnutls_base64_encode2} +@deftypefun {int} {gnutls_base64_encode2} (const gnutls_datum_t * @var{data}, gnutls_datum_t * @var{result}) +@var{data}: contains the raw data + +@var{result}: will hold the newly allocated encoded data + +This function will convert the given data to printable data, using +the base64 encoding. This function will allocate the required +memory to hold the encoded data. + +You should use @code{gnutls_free()} to free the returned data. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_buffer_append_data +@anchor{gnutls_buffer_append_data} +@deftypefun {int} {gnutls_buffer_append_data} (gnutls_buffer_t @var{dest}, const void * @var{data}, size_t @var{data_size}) +@var{dest}: the buffer to append to + +@var{data}: the data + +@var{data_size}: the size of @code{data} + +Appends the provided @code{data} to the destination buffer. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_bye +@anchor{gnutls_bye} +@deftypefun {int} {gnutls_bye} (gnutls_session_t @var{session}, gnutls_close_request_t @var{how}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{how}: is an integer + +Terminates the current TLS/SSL connection. The connection should +have been initiated using @code{gnutls_handshake()} . @code{how} should be one +of @code{GNUTLS_SHUT_RDWR} , @code{GNUTLS_SHUT_WR} . + +In case of @code{GNUTLS_SHUT_RDWR} the TLS session gets +terminated and further receives and sends will be disallowed. If +the return value is zero you may continue using the underlying +transport layer. @code{GNUTLS_SHUT_RDWR} sends an alert containing a close +request and waits for the peer to reply with the same message. + +In case of @code{GNUTLS_SHUT_WR} the TLS session gets terminated +and further sends will be disallowed. In order to reuse the +connection you should wait for an EOF from the peer. +@code{GNUTLS_SHUT_WR} sends an alert containing a close request. + +Note that not all implementations will properly terminate a TLS +connection. Some of them, usually for performance reasons, will +terminate only the underlying transport layer, and thus not +distinguishing between a malicious party prematurely terminating +the connection and normal termination. + +This function may also return @code{GNUTLS_E_AGAIN} or +@code{GNUTLS_E_INTERRUPTED} ; cf. @code{gnutls_record_get_direction()} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code, see +function documentation for entire semantics. +@end deftypefun + +@subheading gnutls_certificate_activation_time_peers +@anchor{gnutls_certificate_activation_time_peers} +@deftypefun {time_t} {gnutls_certificate_activation_time_peers} (gnutls_session_t @var{session}) +@var{session}: is a gnutls session + +This function will return the peer's certificate activation time. + +@strong{Returns:} (time_t)-1 on error. + +@strong{Deprecated:} @code{gnutls_certificate_verify_peers2()} now verifies activation times. +@end deftypefun + +@subheading gnutls_certificate_allocate_credentials +@anchor{gnutls_certificate_allocate_credentials} +@deftypefun {int} {gnutls_certificate_allocate_credentials} (gnutls_certificate_credentials_t * @var{res}) +@var{res}: is a pointer to a @code{gnutls_certificate_credentials_t} type. + +Allocate a gnutls_certificate_credentials_t structure. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. +@end deftypefun + +@subheading gnutls_certificate_client_get_request_status +@anchor{gnutls_certificate_client_get_request_status} +@deftypefun {unsigned} {gnutls_certificate_client_get_request_status} (gnutls_session_t @var{session}) +@var{session}: is a gnutls session + +Get whether client certificate was requested on the last +handshake or not. + +@strong{Returns:} 0 if the peer (server) did not request client +authentication or 1 otherwise. +@end deftypefun + +@subheading gnutls_certificate_expiration_time_peers +@anchor{gnutls_certificate_expiration_time_peers} +@deftypefun {time_t} {gnutls_certificate_expiration_time_peers} (gnutls_session_t @var{session}) +@var{session}: is a gnutls session + +This function will return the peer's certificate expiration time. + +@strong{Returns:} (time_t)-1 on error. + +@strong{Deprecated:} @code{gnutls_certificate_verify_peers2()} now verifies expiration times. +@end deftypefun + +@subheading gnutls_certificate_free_ca_names +@anchor{gnutls_certificate_free_ca_names} +@deftypefun {void} {gnutls_certificate_free_ca_names} (gnutls_certificate_credentials_t @var{sc}) +@var{sc}: is a @code{gnutls_certificate_credentials_t} type. + +This function will delete all the CA name in the given +credentials. Clients may call this to save some memory since in +client side the CA names are not used. Servers might want to use +this function if a large list of trusted CAs is present and +sending the names of it would just consume bandwidth without providing +information to client. + +CA names are used by servers to advertise the CAs they support to +clients. +@end deftypefun + +@subheading gnutls_certificate_free_cas +@anchor{gnutls_certificate_free_cas} +@deftypefun {void} {gnutls_certificate_free_cas} (gnutls_certificate_credentials_t @var{sc}) +@var{sc}: is a @code{gnutls_certificate_credentials_t} type. + +This function was operational on very early versions of gnutls. +Due to internal refactorings and the fact that this was hardly ever +used, it is currently a no-op. +@end deftypefun + +@subheading gnutls_certificate_free_credentials +@anchor{gnutls_certificate_free_credentials} +@deftypefun {void} {gnutls_certificate_free_credentials} (gnutls_certificate_credentials_t @var{sc}) +@var{sc}: is a @code{gnutls_certificate_credentials_t} type. + +Free a gnutls_certificate_credentials_t structure. + +This function does not free any temporary parameters associated +with this structure (ie RSA and DH parameters are not freed by this +function). +@end deftypefun + +@subheading gnutls_certificate_free_crls +@anchor{gnutls_certificate_free_crls} +@deftypefun {void} {gnutls_certificate_free_crls} (gnutls_certificate_credentials_t @var{sc}) +@var{sc}: is a @code{gnutls_certificate_credentials_t} type. + +This function will delete all the CRLs associated +with the given credentials. +@end deftypefun + +@subheading gnutls_certificate_free_keys +@anchor{gnutls_certificate_free_keys} +@deftypefun {void} {gnutls_certificate_free_keys} (gnutls_certificate_credentials_t @var{sc}) +@var{sc}: is a @code{gnutls_certificate_credentials_t} type. + +This function will delete all the keys and the certificates associated +with the given credentials. This function must not be called when a +TLS negotiation that uses the credentials is in progress. +@end deftypefun + +@subheading gnutls_certificate_get_crt_raw +@anchor{gnutls_certificate_get_crt_raw} +@deftypefun {int} {gnutls_certificate_get_crt_raw} (gnutls_certificate_credentials_t @var{sc}, unsigned @var{idx1}, unsigned @var{idx2}, gnutls_datum_t * @var{cert}) +@var{sc}: is a @code{gnutls_certificate_credentials_t} type. + +@var{idx1}: the index of the certificate chain if multiple are present + +@var{idx2}: the index of the certificate in the chain. Zero gives the server's certificate. + +@var{cert}: Will hold the DER encoded certificate. + +This function will return the DER encoded certificate of the +server or any other certificate on its certificate chain (based on @code{idx2} ). +The returned data should be treated as constant and only accessible during the lifetime +of @code{sc} . The @code{idx1} matches the value @code{gnutls_certificate_set_x509_key()} and friends +functions. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. In case the indexes are out of bounds @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +is returned. + +@strong{Since:} 3.2.5 +@end deftypefun + +@subheading gnutls_certificate_get_issuer +@anchor{gnutls_certificate_get_issuer} +@deftypefun {int} {gnutls_certificate_get_issuer} (gnutls_certificate_credentials_t @var{sc}, gnutls_x509_crt_t @var{cert}, gnutls_x509_crt_t * @var{issuer}, unsigned int @var{flags}) +@var{sc}: is a @code{gnutls_certificate_credentials_t} type. + +@var{cert}: is the certificate to find issuer for + +@var{issuer}: Will hold the issuer if any. Should be treated as constant. + +@var{flags}: Use zero or @code{GNUTLS_TL_GET_COPY} + +This function will return the issuer of a given certificate. +If the flag @code{GNUTLS_TL_GET_COPY} is specified a copy of the issuer +will be returned which must be freed using @code{gnutls_x509_crt_deinit()} . +In that case the provided @code{issuer} must not be initialized. + +As with @code{gnutls_x509_trust_list_get_issuer()} this function requires +the @code{GNUTLS_TL_GET_COPY} flag in order to operate with PKCS@code{11} trust +lists in a thread-safe way. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_certificate_get_ocsp_expiration +@anchor{gnutls_certificate_get_ocsp_expiration} +@deftypefun {time_t} {gnutls_certificate_get_ocsp_expiration} (gnutls_certificate_credentials_t @var{sc}, unsigned @var{idx}, int @var{oidx}, unsigned @var{flags}) +@var{sc}: is a credentials structure. + +@var{idx}: is a certificate chain index as returned by @code{gnutls_certificate_set_key()} and friends + +@var{oidx}: is an OCSP response index + +@var{flags}: should be zero + +This function returns the validity of the loaded OCSP responses, +to provide information on when to reload/refresh them. + +Note that the credentials structure should be read-only when in +use, thus when reloading, either the credentials structure must not +be in use by any sessions, or a new credentials structure should be +allocated for new sessions. + +When @code{oidx} is (-1) then the minimum refresh time for all responses +is returned. Otherwise the index specifies the response corresponding +to the @code{odix} certificate in the certificate chain. + +@strong{Returns:} On success, the expiration time of the OCSP response. Otherwise +(time_t)(-1) on error, or (time_t)-2 on out of bounds. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_certificate_get_ours +@anchor{gnutls_certificate_get_ours} +@deftypefun {const gnutls_datum_t *} {gnutls_certificate_get_ours} (gnutls_session_t @var{session}) +@var{session}: is a gnutls session + +Gets the certificate as sent to the peer in the last handshake. +The certificate is in raw (DER) format. No certificate +list is being returned. Only the first certificate. + +This function returns the certificate that was sent in the current +handshake. In subsequent resumed sessions this function will return +@code{NULL} . That differs from @code{gnutls_certificate_get_peers()} which always +returns the peer's certificate used in the original session. + +@strong{Returns:} a pointer to a @code{gnutls_datum_t} containing our +certificate, or @code{NULL} in case of an error or if no certificate +was used. +@end deftypefun + +@subheading gnutls_certificate_get_peers +@anchor{gnutls_certificate_get_peers} +@deftypefun {const gnutls_datum_t *} {gnutls_certificate_get_peers} (gnutls_session_t @var{session}, unsigned int * @var{list_size}) +@var{session}: is a gnutls session + +@var{list_size}: is the length of the certificate list (may be @code{NULL} ) + +Get the peer's raw certificate (chain) as sent by the peer. These +certificates are in raw format (DER encoded for X.509). In case of +a X.509 then a certificate list may be present. The list +is provided as sent by the server; the server must send as first +certificate in the list its own certificate, following the +issuer's certificate, then the issuer's issuer etc. However, there +are servers which violate this principle and thus on certain +occasions this may be an unsorted list. + +In resumed sessions, this function will return the peer's certificate +list as used in the first/original session. + +@strong{Returns:} a pointer to a @code{gnutls_datum_t} containing the peer's +certificates, or @code{NULL} in case of an error or if no certificate +was used. +@end deftypefun + +@subheading gnutls_certificate_get_peers_subkey_id +@anchor{gnutls_certificate_get_peers_subkey_id} +@deftypefun {int} {gnutls_certificate_get_peers_subkey_id} (gnutls_session_t @var{session}, gnutls_datum_t * @var{id}) +@var{session}: is a gnutls session + +@var{id}: will contain the ID + +This function is no-op. + +@strong{Returns:} @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} . + +@strong{Since:} 3.1.3 +@end deftypefun + +@subheading gnutls_certificate_get_verify_flags +@anchor{gnutls_certificate_get_verify_flags} +@deftypefun {unsigned int} {gnutls_certificate_get_verify_flags} (gnutls_certificate_credentials_t @var{res}) +@var{res}: is a gnutls_certificate_credentials_t type + +Returns the verification flags set with +@code{gnutls_certificate_set_verify_flags()} . + +@strong{Returns:} The certificate verification flags used by @code{res} . + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_certificate_get_x509_crt +@anchor{gnutls_certificate_get_x509_crt} +@deftypefun {int} {gnutls_certificate_get_x509_crt} (gnutls_certificate_credentials_t @var{res}, unsigned @var{index}, gnutls_x509_crt_t ** @var{crt_list}, unsigned * @var{crt_list_size}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{index}: The index of the certificate list to obtain. + +@var{crt_list}: Where to store the certificate list. + +@var{crt_list_size}: Will hold the number of certificates. + +Obtains a X.509 certificate list that has been stored in @code{res} with one of +@code{gnutls_certificate_set_x509_key()} , @code{gnutls_certificate_set_key()} , +@code{gnutls_certificate_set_x509_key_file()} , +@code{gnutls_certificate_set_x509_key_file2()} , +@code{gnutls_certificate_set_x509_key_mem()} , or +@code{gnutls_certificate_set_x509_key_mem2()} . Each certificate in the returned +certificate list must be deallocated with @code{gnutls_x509_crt_deinit()} , and the +list itself must be freed with @code{gnutls_free()} . + +The @code{index} matches the return value of @code{gnutls_certificate_set_x509_key()} and friends +functions, when the @code{GNUTLS_CERTIFICATE_API_V2} flag is set. + +If there is no certificate with the given index, +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. If the certificate +with the given index is not a X.509 certificate, @code{GNUTLS_E_INVALID_REQUEST} +is returned. The returned certificates must be deinitialized after +use, and the @code{crt_list} pointer must be freed using @code{gnutls_free()} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success, or a negative error code. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_certificate_get_x509_key +@anchor{gnutls_certificate_get_x509_key} +@deftypefun {int} {gnutls_certificate_get_x509_key} (gnutls_certificate_credentials_t @var{res}, unsigned @var{index}, gnutls_x509_privkey_t * @var{key}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{index}: The index of the key to obtain. + +@var{key}: Location to store the key. + +Obtains a X.509 private key that has been stored in @code{res} with one of +@code{gnutls_certificate_set_x509_key()} , @code{gnutls_certificate_set_key()} , +@code{gnutls_certificate_set_x509_key_file()} , +@code{gnutls_certificate_set_x509_key_file2()} , +@code{gnutls_certificate_set_x509_key_mem()} , or +@code{gnutls_certificate_set_x509_key_mem2()} . The returned key must be deallocated +with @code{gnutls_x509_privkey_deinit()} when no longer needed. + +The @code{index} matches the return value of @code{gnutls_certificate_set_x509_key()} and friends +functions, when the @code{GNUTLS_CERTIFICATE_API_V2} flag is set. + +If there is no key with the given index, +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. If the key with the +given index is not a X.509 key, @code{GNUTLS_E_INVALID_REQUEST} is returned. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success, or a negative error code. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_certificate_send_x509_rdn_sequence +@anchor{gnutls_certificate_send_x509_rdn_sequence} +@deftypefun {void} {gnutls_certificate_send_x509_rdn_sequence} (gnutls_session_t @var{session}, int @var{status}) +@var{session}: a @code{gnutls_session_t} type. + +@var{status}: is 0 or 1 + +If status is non zero, this function will order gnutls not to send +the rdnSequence in the certificate request message. That is the +server will not advertise its trusted CAs to the peer. If status +is zero then the default behaviour will take effect, which is to +advertise the server's trusted CAs. + +This function has no effect in clients, and in authentication +methods other than certificate with X.509 certificates. +@end deftypefun + +@subheading gnutls_certificate_server_set_request +@anchor{gnutls_certificate_server_set_request} +@deftypefun {void} {gnutls_certificate_server_set_request} (gnutls_session_t @var{session}, gnutls_certificate_request_t @var{req}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{req}: is one of GNUTLS_CERT_REQUEST, GNUTLS_CERT_REQUIRE, GNUTLS_CERT_IGNORE + +This function specifies if we (in case of a server) are going to +send a certificate request message to the client. If @code{req} is +GNUTLS_CERT_REQUIRE then the server will return the @code{GNUTLS_E_NO_CERTIFICATE_FOUND} +error if the peer does not provide a certificate. If you do not call this +function then the client will not be asked to send a certificate. Invoking +the function with @code{req} GNUTLS_CERT_IGNORE has the same effect. +@end deftypefun + +@subheading gnutls_certificate_set_dh_params +@anchor{gnutls_certificate_set_dh_params} +@deftypefun {void} {gnutls_certificate_set_dh_params} (gnutls_certificate_credentials_t @var{res}, gnutls_dh_params_t @var{dh_params}) +@var{res}: is a gnutls_certificate_credentials_t type + +@var{dh_params}: the Diffie-Hellman parameters. + +This function will set the Diffie-Hellman parameters for a +certificate server to use. These parameters will be used in +Ephemeral Diffie-Hellman cipher suites. Note that only a pointer +to the parameters are stored in the certificate handle, so you +must not deallocate the parameters before the certificate is deallocated. + +@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 +or later. Since 3.6.0, DH parameters are negotiated +following RFC7919. +@end deftypefun + +@subheading gnutls_certificate_set_flags +@anchor{gnutls_certificate_set_flags} +@deftypefun {void} {gnutls_certificate_set_flags} (gnutls_certificate_credentials_t @var{res}, unsigned int @var{flags}) +@var{res}: is a gnutls_certificate_credentials_t type + +@var{flags}: are the flags of @code{gnutls_certificate_flags} type + +This function will set flags to tweak the operation of +the credentials structure. See the @code{gnutls_certificate_flags} enumerations +for more information on the available flags. + +@strong{Since:} 3.4.7 +@end deftypefun + +@subheading gnutls_certificate_set_known_dh_params +@anchor{gnutls_certificate_set_known_dh_params} +@deftypefun {int} {gnutls_certificate_set_known_dh_params} (gnutls_certificate_credentials_t @var{res}, gnutls_sec_param_t @var{sec_param}) +@var{res}: is a gnutls_certificate_credentials_t type + +@var{sec_param}: is an option of the @code{gnutls_sec_param_t} enumeration + +This function will set the Diffie-Hellman parameters for a +certificate server to use. These parameters will be used in +Ephemeral Diffie-Hellman cipher suites and will be selected from +the FFDHE set of RFC7919 according to the security level provided. + +@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 +or later. Since 3.6.0, DH parameters are negotiated +following RFC7919. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.5.6 +@end deftypefun + +@subheading gnutls_certificate_set_ocsp_status_request_file +@anchor{gnutls_certificate_set_ocsp_status_request_file} +@deftypefun {int} {gnutls_certificate_set_ocsp_status_request_file} (gnutls_certificate_credentials_t @var{sc}, const char * @var{response_file}, unsigned @var{idx}) +@var{sc}: is a credentials structure. + +@var{response_file}: a filename of the OCSP response + +@var{idx}: is a certificate index as returned by @code{gnutls_certificate_set_key()} and friends + +This function loads the provided OCSP response. It will be +sent to the client if requests an OCSP certificate status for +the certificate chain specified by @code{idx} . + +@strong{Note:} the ability to set multiple OCSP responses per credential +structure via the index @code{idx} was added in version 3.5.6. To keep +backwards compatibility, it requires using @code{gnutls_certificate_set_flags()} +with the @code{GNUTLS_CERTIFICATE_API_V2} flag to make the set certificate +functions return an index usable by this function. + +This function can be called multiple times since GnuTLS 3.6.3 +when multiple responses which apply to the chain are available. +If the response provided does not match any certificates present +in the chain, the code @code{GNUTLS_E_OCSP_MISMATCH_WITH_CERTS} is returned. +To revert to the previous behavior set the flag @code{GNUTLS_CERTIFICATE_SKIP_OCSP_RESPONSE_CHECK} +in the certificate credentials structure. In that case, only the +end-certificate's OCSP response can be set. +If the response is already expired at the time of loading the code +@code{GNUTLS_E_EXPIRED} is returned. + +To revert to the previous behavior of this function which does not return +any errors, set the flag @code{GNUTLS_CERTIFICATE_SKIP_OCSP_RESPONSE_CHECK} + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +@strong{Since:} 3.1.3 +@end deftypefun + +@subheading gnutls_certificate_set_ocsp_status_request_file2 +@anchor{gnutls_certificate_set_ocsp_status_request_file2} +@deftypefun {int} {gnutls_certificate_set_ocsp_status_request_file2} (gnutls_certificate_credentials_t @var{sc}, const char * @var{response_file}, unsigned @var{idx}, gnutls_x509_crt_fmt_t @var{fmt}) +@var{sc}: is a credentials structure. + +@var{response_file}: a filename of the OCSP response + +@var{idx}: is a certificate index as returned by @code{gnutls_certificate_set_key()} and friends + +@var{fmt}: is PEM or DER + +This function loads the OCSP responses to be sent to the +peer for the certificate chain specified by @code{idx} . When @code{fmt} is +set to PEM, multiple responses can be loaded. + +This function must be called after setting any certificates, and +cannot be used for certificates that are provided via a callback -- +that is when @code{gnutls_certificate_set_retrieve_function()} is used. In +that case consider using @code{gnutls_certificate_set_retrieve_function3()} . + +This function can be called multiple times when multiple responses +applicable to the certificate chain are available. +If the response provided does not match any certificates present +in the chain, the code @code{GNUTLS_E_OCSP_MISMATCH_WITH_CERTS} is returned. +If the response is already expired at the time of loading the code +@code{GNUTLS_E_EXPIRED} is returned. + +@strong{Returns:} On success, the number of loaded responses is returned, +otherwise a negative error code. + +@strong{Since:} 3.1.3 +@end deftypefun + +@subheading gnutls_certificate_set_ocsp_status_request_function +@anchor{gnutls_certificate_set_ocsp_status_request_function} +@deftypefun {void} {gnutls_certificate_set_ocsp_status_request_function} (gnutls_certificate_credentials_t @var{sc}, gnutls_status_request_ocsp_func @var{ocsp_func}, void * @var{ptr}) +@var{sc}: is a @code{gnutls_certificate_credentials_t} type. + +@var{ocsp_func}: function pointer to OCSP status request callback. + +@var{ptr}: opaque pointer passed to callback function + +This function is to be used by server to register a callback to +handle OCSP status requests from the client. The callback will be +invoked if the client supplied a status-request OCSP extension. +The callback function prototype is: + +typedef int (*gnutls_status_request_ocsp_func) +(gnutls_session_t session, void *ptr, gnutls_datum_t *ocsp_response); + +The callback will be invoked if the client requests an OCSP certificate +status. The callback may return @code{GNUTLS_E_NO_CERTIFICATE_STATUS} , if +there is no recent OCSP response. If the callback returns @code{GNUTLS_E_SUCCESS} , +it is expected to have the @code{ocsp_response} field set with a valid (DER-encoded) +OCSP response. The response must be a value allocated using @code{gnutls_malloc()} , +and will be deinitialized by the caller. + +It is possible to set a specific callback for each provided certificate +using @code{gnutls_certificate_set_ocsp_status_request_function2()} . + +@strong{Since:} 3.1.3 +@end deftypefun + +@subheading gnutls_certificate_set_ocsp_status_request_function2 +@anchor{gnutls_certificate_set_ocsp_status_request_function2} +@deftypefun {int} {gnutls_certificate_set_ocsp_status_request_function2} (gnutls_certificate_credentials_t @var{sc}, unsigned @var{idx}, gnutls_status_request_ocsp_func @var{ocsp_func}, void * @var{ptr}) +@var{sc}: is a @code{gnutls_certificate_credentials_t} type. + +@var{idx}: is a certificate index as returned by @code{gnutls_certificate_set_key()} and friends + +@var{ocsp_func}: function pointer to OCSP status request callback. + +@var{ptr}: opaque pointer passed to callback function + +This function is to be used by server to register a callback to +provide OCSP status requests that correspond to the indexed certificate chain +from the client. The callback will be invoked if the client supplied a +status-request OCSP extension. + +The callback function prototype is: + +typedef int (*gnutls_status_request_ocsp_func) +(gnutls_session_t session, void *ptr, gnutls_datum_t *ocsp_response); + +The callback will be invoked if the client requests an OCSP certificate +status. The callback may return @code{GNUTLS_E_NO_CERTIFICATE_STATUS} , if +there is no recent OCSP response. If the callback returns @code{GNUTLS_E_SUCCESS} , +it is expected to have the @code{ocsp_response} field set with a valid (DER-encoded) +OCSP response. The response must be a value allocated using @code{gnutls_malloc()} , +and will be deinitialized by the caller. + +@strong{Note:} the ability to set multiple OCSP responses per credential +structure via the index @code{idx} was added in version 3.5.6. To keep +backwards compatibility, it requires using @code{gnutls_certificate_set_flags()} +with the @code{GNUTLS_CERTIFICATE_API_V2} flag to make the set certificate +functions return an index usable by this function. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +@strong{Since:} 3.5.5 +@end deftypefun + +@subheading gnutls_certificate_set_ocsp_status_request_mem +@anchor{gnutls_certificate_set_ocsp_status_request_mem} +@deftypefun {int} {gnutls_certificate_set_ocsp_status_request_mem} (gnutls_certificate_credentials_t @var{sc}, const gnutls_datum_t * @var{resp_data}, unsigned @var{idx}, gnutls_x509_crt_fmt_t @var{fmt}) +@var{sc}: is a credentials structure. + +@var{resp_data}: a memory buffer holding an OCSP response + +@var{idx}: is a certificate index as returned by @code{gnutls_certificate_set_key()} and friends + +@var{fmt}: is PEM or DER + +This function sets the OCSP responses to be sent to the +peer for the certificate chain specified by @code{idx} . When @code{fmt} is set +to PEM, multiple responses can be loaded. + +@strong{Note:} the ability to set multiple OCSP responses per credential +structure via the index @code{idx} was added in version 3.5.6. To keep +backwards compatibility, it requires using @code{gnutls_certificate_set_flags()} +with the @code{GNUTLS_CERTIFICATE_API_V2} flag to make the set certificate +functions return an index usable by this function. + +This function must be called after setting any certificates, and +cannot be used for certificates that are provided via a callback -- +that is when @code{gnutls_certificate_set_retrieve_function()} is used. + +This function can be called multiple times when multiple responses which +apply to the certificate chain are available. +If the response provided does not match any certificates present +in the chain, the code @code{GNUTLS_E_OCSP_MISMATCH_WITH_CERTS} is returned. +If the response is already expired at the time of loading the code +@code{GNUTLS_E_EXPIRED} is returned. + +@strong{Returns:} On success, the number of loaded responses is returned, +otherwise a negative error code. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_certificate_set_params_function +@anchor{gnutls_certificate_set_params_function} +@deftypefun {void} {gnutls_certificate_set_params_function} (gnutls_certificate_credentials_t @var{res}, gnutls_params_function * @var{func}) +@var{res}: is a gnutls_certificate_credentials_t type + +@var{func}: is the function to be called + +This function will set a callback in order for the server to get +the Diffie-Hellman or RSA parameters for certificate +authentication. The callback should return @code{GNUTLS_E_SUCCESS} (0) on success. + +@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 +or later. Since 3.6.0, DH parameters are negotiated +following RFC7919. +@end deftypefun + +@subheading gnutls_certificate_set_pin_function +@anchor{gnutls_certificate_set_pin_function} +@deftypefun {void} {gnutls_certificate_set_pin_function} (gnutls_certificate_credentials_t @var{cred}, gnutls_pin_callback_t @var{fn}, void * @var{userdata}) +@var{cred}: is a @code{gnutls_certificate_credentials_t} type. + +@var{fn}: A PIN callback + +@var{userdata}: Data to be passed in the callback + +This function will set a callback function to be used when +required to access a protected object. This function overrides any other +global PIN functions. + +Note that this function must be called right after initialization +to have effect. + +@strong{Since:} 3.1.0 +@end deftypefun + +@subheading gnutls_certificate_set_rawpk_key_file +@anchor{gnutls_certificate_set_rawpk_key_file} +@deftypefun {int} {gnutls_certificate_set_rawpk_key_file} (gnutls_certificate_credentials_t @var{cred}, const char* @var{rawpkfile}, const char* @var{privkeyfile}, gnutls_x509_crt_fmt_t @var{format}, const char * @var{pass}, unsigned int @var{key_usage}, const char ** @var{names}, unsigned int @var{names_length}, unsigned int @var{privkey_flags}, unsigned int @var{pkcs11_flags}) +@var{cred}: is a @code{gnutls_certificate_credentials_t} type. + +@var{rawpkfile}: contains a raw public key in +PKIX.SubjectPublicKeyInfo format. + +@var{privkeyfile}: contains a file path to a private key. + +@var{format}: encoding of the keys. DER or PEM. + +@var{pass}: an optional password to unlock the private key privkeyfile. + +@var{key_usage}: an ORed sequence of @code{GNUTLS_KEY_} * flags. + +@var{names}: is an array of DNS names belonging to the public-key (NULL if none). + +@var{names_length}: holds the length of the names list. + +@var{privkey_flags}: an ORed sequence of @code{gnutls_pkcs_encrypt_flags_t} . +These apply to the private key pkey. + +@var{pkcs11_flags}: one of gnutls_pkcs11_obj_flags. These apply to URLs. + +This function sets a public/private keypair read from file in the +@code{gnutls_certificate_credentials_t} type to be used for authentication +and/or encryption. @code{spki} and @code{privkey} should match otherwise set +signatures cannot be validated. In case of no match this function +returns @code{GNUTLS_E_CERTIFICATE_KEY_MISMATCH} . This function should +be called once for the client because there is currently no mechanism +to determine which raw public-key to select for the peer when there +are multiple present. Multiple raw public keys for the server can be +distinghuished by setting the @code{names} . + +Note here that @code{spki} is a raw public-key as defined +in RFC7250. It means that there is no surrounding certificate that +holds the public key and that there is therefore no direct mechanism +to prove the authenticity of this key. The keypair can be used during +a TLS handshake but its authenticity should be established via a +different mechanism (e.g. TOFU or known fingerprint). + +The supported formats are basic unencrypted key, PKCS8, PKCS12, +and the openssl format and will be autodetected. + +If the raw public-key and the private key are given in PEM encoding +then the strings that hold their values must be null terminated. + +Key usage (as defined by X.509 extension (2.5.29.15)) can be explicitly +set because there is no certificate structure around the key to define +this value. See for more info @code{gnutls_x509_crt_get_key_usage()} . + +Note that, this function by default returns zero on success and a +negative value on error. Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} +is set using @code{gnutls_certificate_set_flags()} it returns an index +(greater or equal to zero). That index can be used in other functions +to refer to the added key-pair. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, in case the +key pair does not match @code{GNUTLS_E_CERTIFICATE_KEY_MISMATCH} is returned, +in other erroneous cases a different negative error code is returned. + +@strong{Since:} 3.6.6 +@end deftypefun + +@subheading gnutls_certificate_set_rawpk_key_mem +@anchor{gnutls_certificate_set_rawpk_key_mem} +@deftypefun {int} {gnutls_certificate_set_rawpk_key_mem} (gnutls_certificate_credentials_t @var{cred}, const gnutls_datum_t* @var{spki}, const gnutls_datum_t* @var{pkey}, gnutls_x509_crt_fmt_t @var{format}, const char* @var{pass}, unsigned int @var{key_usage}, const char ** @var{names}, unsigned int @var{names_length}, unsigned int @var{flags}) +@var{cred}: is a @code{gnutls_certificate_credentials_t} type. + +@var{spki}: contains a raw public key in +PKIX.SubjectPublicKeyInfo format. + +@var{pkey}: contains a raw private key. + +@var{format}: encoding of the keys. DER or PEM. + +@var{pass}: an optional password to unlock the private key pkey. + +@var{key_usage}: An ORed sequence of @code{GNUTLS_KEY_} * flags. + +@var{names}: is an array of DNS names belonging to the public-key (NULL if none). + +@var{names_length}: holds the length of the names list. + +@var{flags}: an ORed sequence of @code{gnutls_pkcs_encrypt_flags_t} . +These apply to the private key pkey. + +This function sets a public/private keypair in the +@code{gnutls_certificate_credentials_t} type to be used for authentication +and/or encryption. @code{spki} and @code{privkey} should match otherwise set +signatures cannot be validated. In case of no match this function +returns @code{GNUTLS_E_CERTIFICATE_KEY_MISMATCH} . This function should +be called once for the client because there is currently no mechanism +to determine which raw public-key to select for the peer when there +are multiple present. Multiple raw public keys for the server can be +distinghuished by setting the @code{names} . + +Note here that @code{spki} is a raw public-key as defined +in RFC7250. It means that there is no surrounding certificate that +holds the public key and that there is therefore no direct mechanism +to prove the authenticity of this key. The keypair can be used during +a TLS handshake but its authenticity should be established via a +different mechanism (e.g. TOFU or known fingerprint). + +The supported formats are basic unencrypted key, PKCS8, PKCS12, +and the openssl format and will be autodetected. + +If the raw public-key and the private key are given in PEM encoding +then the strings that hold their values must be null terminated. + +Key usage (as defined by X.509 extension (2.5.29.15)) can be explicitly +set because there is no certificate structure around the key to define +this value. See for more info @code{gnutls_x509_crt_get_key_usage()} . + +Note that, this function by default returns zero on success and a +negative value on error. Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} +is set using @code{gnutls_certificate_set_flags()} it returns an index +(greater or equal to zero). That index can be used in other functions +to refer to the added key-pair. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, in case the +key pair does not match @code{GNUTLS_E_CERTIFICATE_KEY_MISMATCH} is returned, +in other erroneous cases a different negative error code is returned. + +@strong{Since:} 3.6.6 +@end deftypefun + +@subheading gnutls_certificate_set_retrieve_function +@anchor{gnutls_certificate_set_retrieve_function} +@deftypefun {void} {gnutls_certificate_set_retrieve_function} (gnutls_certificate_credentials_t @var{cred}, gnutls_certificate_retrieve_function * @var{func}) +@var{cred}: is a @code{gnutls_certificate_credentials_t} type. + +@var{func}: is the callback function + +This function sets a callback to be called in order to retrieve the +certificate to be used in the handshake. The callback will take control +only if a certificate is requested by the peer. You are advised +to use @code{gnutls_certificate_set_retrieve_function2()} because it +is much more efficient in the processing it requires from gnutls. + +The callback's function prototype is: +int (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int nreqs, +const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length, gnutls_retr2_st* st); + + @code{req_ca_dn} is only used in X.509 certificates. +Contains a list with the CA names that the server considers trusted. +This is a hint and typically the client should send a certificate that is signed +by one of these CAs. These names, when available, are DER encoded. To get a more +meaningful value use the function @code{gnutls_x509_rdn_get()} . + + @code{pk_algos} contains a list with server's acceptable public key algorithms. +The certificate returned should support the server's given algorithms. + + @code{st} should contain the certificates and private keys. + +If the callback function is provided then gnutls will call it, in the +handshake, after the certificate request message has been received. + +In server side pk_algos and req_ca_dn are NULL. + +The callback function should set the certificate list to be sent, +and return 0 on success. If no certificate was selected then the +number of certificates should be set to zero. The value (-1) +indicates error and the handshake will be terminated. If both certificates +are set in the credentials and a callback is available, the callback +takes predence. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_certificate_set_verify_flags +@anchor{gnutls_certificate_set_verify_flags} +@deftypefun {void} {gnutls_certificate_set_verify_flags} (gnutls_certificate_credentials_t @var{res}, unsigned int @var{flags}) +@var{res}: is a gnutls_certificate_credentials_t type + +@var{flags}: are the flags + +This function will set the flags to be used for verification +of certificates and override any defaults. The provided flags must be an OR of the +@code{gnutls_certificate_verify_flags} enumerations. +@end deftypefun + +@subheading gnutls_certificate_set_verify_function +@anchor{gnutls_certificate_set_verify_function} +@deftypefun {void} {gnutls_certificate_set_verify_function} (gnutls_certificate_credentials_t @var{cred}, gnutls_certificate_verify_function * @var{func}) +@var{cred}: is a @code{gnutls_certificate_credentials_t} type. + +@var{func}: is the callback function + +This function sets a callback to be called when peer's certificate +has been received in order to verify it on receipt rather than +doing after the handshake is completed. + +The callback's function prototype is: +int (*callback)(gnutls_session_t); + +If the callback function is provided then gnutls will call it, in the +handshake, just after the certificate message has been received. +To verify or obtain the certificate the @code{gnutls_certificate_verify_peers2()} , +@code{gnutls_certificate_type_get()} , @code{gnutls_certificate_get_peers()} functions +can be used. + +The callback function should return 0 for the handshake to continue +or non-zero to terminate. + +@strong{Since:} 2.10.0 +@end deftypefun + +@subheading gnutls_certificate_set_verify_limits +@anchor{gnutls_certificate_set_verify_limits} +@deftypefun {void} {gnutls_certificate_set_verify_limits} (gnutls_certificate_credentials_t @var{res}, unsigned int @var{max_bits}, unsigned int @var{max_depth}) +@var{res}: is a gnutls_certificate_credentials type + +@var{max_bits}: is the number of bits of an acceptable certificate (default 8200) + +@var{max_depth}: is maximum depth of the verification of a certificate chain (default 5) + +This function will set some upper limits for the default +verification function, @code{gnutls_certificate_verify_peers2()} , to avoid +denial of service attacks. You can set them to zero to disable +limits. +@end deftypefun + +@subheading gnutls_certificate_set_x509_crl +@anchor{gnutls_certificate_set_x509_crl} +@deftypefun {int} {gnutls_certificate_set_x509_crl} (gnutls_certificate_credentials_t @var{res}, gnutls_x509_crl_t * @var{crl_list}, int @var{crl_list_size}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{crl_list}: is a list of trusted CRLs. They should have been verified before. + +@var{crl_list_size}: holds the size of the crl_list + +This function adds the trusted CRLs in order to verify client or +server certificates. In case of a client this is not required to +be called if the certificates are not verified using +@code{gnutls_certificate_verify_peers2()} . This function may be called +multiple times. + +@strong{Returns:} number of CRLs processed, or a negative error code on error. + +@strong{Since:} 2.4.0 +@end deftypefun + +@subheading gnutls_certificate_set_x509_crl_file +@anchor{gnutls_certificate_set_x509_crl_file} +@deftypefun {int} {gnutls_certificate_set_x509_crl_file} (gnutls_certificate_credentials_t @var{res}, const char * @var{crlfile}, gnutls_x509_crt_fmt_t @var{type}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{crlfile}: is a file containing the list of verified CRLs (DER or PEM list) + +@var{type}: is PEM or DER + +This function adds the trusted CRLs in order to verify client or server +certificates. In case of a client this is not required +to be called if the certificates are not verified using +@code{gnutls_certificate_verify_peers2()} . +This function may be called multiple times. + +@strong{Returns:} number of CRLs processed or a negative error code on error. +@end deftypefun + +@subheading gnutls_certificate_set_x509_crl_mem +@anchor{gnutls_certificate_set_x509_crl_mem} +@deftypefun {int} {gnutls_certificate_set_x509_crl_mem} (gnutls_certificate_credentials_t @var{res}, const gnutls_datum_t * @var{CRL}, gnutls_x509_crt_fmt_t @var{type}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{CRL}: is a list of trusted CRLs. They should have been verified before. + +@var{type}: is DER or PEM + +This function adds the trusted CRLs in order to verify client or +server certificates. In case of a client this is not required to +be called if the certificates are not verified using +@code{gnutls_certificate_verify_peers2()} . This function may be called +multiple times. + +@strong{Returns:} number of CRLs processed, or a negative error code on error. +@end deftypefun + +@subheading gnutls_certificate_set_x509_key +@anchor{gnutls_certificate_set_x509_key} +@deftypefun {int} {gnutls_certificate_set_x509_key} (gnutls_certificate_credentials_t @var{res}, gnutls_x509_crt_t * @var{cert_list}, int @var{cert_list_size}, gnutls_x509_privkey_t @var{key}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{cert_list}: contains a certificate list (path) for the specified private key + +@var{cert_list_size}: holds the size of the certificate list + +@var{key}: is a @code{gnutls_x509_privkey_t} key + +This function sets a certificate/private key pair in the +gnutls_certificate_credentials_t type. This function may be +called more than once, in case multiple keys/certificates exist for +the server. For clients that wants to send more than their own end +entity certificate (e.g., also an intermediate CA cert) then put +the certificate chain in @code{cert_list} . + +Note that the certificates and keys provided, can be safely deinitialized +after this function is called. + +If that function fails to load the @code{res} type is at an undefined state, it must +not be reused to load other keys or certificates. + +Note that, this function by default returns zero on success and a negative value on error. +Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} is set using @code{gnutls_certificate_set_flags()} +it returns an index (greater or equal to zero). That index can be used to other functions to refer to the added key-pair. + +@strong{Returns:} On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). + +@strong{Since:} 2.4.0 +@end deftypefun + +@subheading gnutls_certificate_set_x509_key_file +@anchor{gnutls_certificate_set_x509_key_file} +@deftypefun {int} {gnutls_certificate_set_x509_key_file} (gnutls_certificate_credentials_t @var{res}, const char * @var{certfile}, const char * @var{keyfile}, gnutls_x509_crt_fmt_t @var{type}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{certfile}: is a file that containing the certificate list (path) for +the specified private key, in PKCS7 format, or a list of certificates + +@var{keyfile}: is a file that contains the private key + +@var{type}: is PEM or DER + +This function sets a certificate/private key pair in the +gnutls_certificate_credentials_t type. This function may be +called more than once, in case multiple keys/certificates exist for +the server. For clients that need to send more than its own end +entity certificate, e.g., also an intermediate CA cert, then the + @code{certfile} must contain the ordered certificate chain. + +Note that the names in the certificate provided will be considered +when selecting the appropriate certificate to use (in case of multiple +certificate/key pairs). + +This function can also accept URLs at @code{keyfile} and @code{certfile} . In that case it +will use the private key and certificate indicated by the URLs. Note +that the supported URLs are the ones indicated by @code{gnutls_url_is_supported()} . + +In case the @code{certfile} is provided as a PKCS @code{11} URL, then the certificate, and its +present issuers in the token are imported (i.e., forming the required trust chain). + +If that function fails to load the @code{res} structure is at an undefined state, it must +not be reused to load other keys or certificates. + +Note that, this function by default returns zero on success and a negative value on error. +Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} is set using @code{gnutls_certificate_set_flags()} +it returns an index (greater or equal to zero). That index can be used to other functions to refer to the added key-pair. + +@strong{Returns:} On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). + +@strong{Since:} 3.1.11 +@end deftypefun + +@subheading gnutls_certificate_set_x509_key_file2 +@anchor{gnutls_certificate_set_x509_key_file2} +@deftypefun {int} {gnutls_certificate_set_x509_key_file2} (gnutls_certificate_credentials_t @var{res}, const char * @var{certfile}, const char * @var{keyfile}, gnutls_x509_crt_fmt_t @var{type}, const char * @var{pass}, unsigned int @var{flags}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{certfile}: is a file that containing the certificate list (path) for +the specified private key, in PKCS7 format, or a list of certificates + +@var{keyfile}: is a file that contains the private key + +@var{type}: is PEM or DER + +@var{pass}: is the password of the key + +@var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t + +This function sets a certificate/private key pair in the +gnutls_certificate_credentials_t type. This function may be +called more than once, in case multiple keys/certificates exist for +the server. For clients that need to send more than its own end +entity certificate, e.g., also an intermediate CA cert, then the + @code{certfile} must contain the ordered certificate chain. + +Note that the names in the certificate provided will be considered +when selecting the appropriate certificate to use (in case of multiple +certificate/key pairs). + +This function can also accept URLs at @code{keyfile} and @code{certfile} . In that case it +will use the private key and certificate indicated by the URLs. Note +that the supported URLs are the ones indicated by @code{gnutls_url_is_supported()} . +Before GnuTLS 3.4.0 when a URL was specified, the @code{pass} part was ignored and a +PIN callback had to be registered, this is no longer the case in current releases. + +In case the @code{certfile} is provided as a PKCS @code{11} URL, then the certificate, and its +present issuers in the token are imported (i.e., forming the required trust chain). + +If that function fails to load the @code{res} structure is at an undefined state, it must +not be reused to load other keys or certificates. + +Note that, this function by default returns zero on success and a negative value on error. +Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} is set using @code{gnutls_certificate_set_flags()} +it returns an index (greater or equal to zero). That index can be used to other functions to refer to the added key-pair. + +@strong{Returns:} On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). +@end deftypefun + +@subheading gnutls_certificate_set_x509_key_mem +@anchor{gnutls_certificate_set_x509_key_mem} +@deftypefun {int} {gnutls_certificate_set_x509_key_mem} (gnutls_certificate_credentials_t @var{res}, const gnutls_datum_t * @var{cert}, const gnutls_datum_t * @var{key}, gnutls_x509_crt_fmt_t @var{type}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{cert}: contains a certificate list (path) for the specified private key + +@var{key}: is the private key, or @code{NULL} + +@var{type}: is PEM or DER + +This function sets a certificate/private key pair in the +gnutls_certificate_credentials_t type. This function may be called +more than once, in case multiple keys/certificates exist for the +server. + +Note that the keyUsage (2.5.29.15) PKIX extension in X.509 certificates +is supported. This means that certificates intended for signing cannot +be used for ciphersuites that require encryption. + +If the certificate and the private key are given in PEM encoding +then the strings that hold their values must be null terminated. + +The @code{key} may be @code{NULL} if you are using a sign callback, see +@code{gnutls_sign_callback_set()} . + +Note that, this function by default returns zero on success and a negative value on error. +Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} is set using @code{gnutls_certificate_set_flags()} +it returns an index (greater or equal to zero). That index can be used to other functions to refer to the added key-pair. + +@strong{Returns:} On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). +@end deftypefun + +@subheading gnutls_certificate_set_x509_key_mem2 +@anchor{gnutls_certificate_set_x509_key_mem2} +@deftypefun {int} {gnutls_certificate_set_x509_key_mem2} (gnutls_certificate_credentials_t @var{res}, const gnutls_datum_t * @var{cert}, const gnutls_datum_t * @var{key}, gnutls_x509_crt_fmt_t @var{type}, const char * @var{pass}, unsigned int @var{flags}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{cert}: contains a certificate list (path) for the specified private key + +@var{key}: is the private key, or @code{NULL} + +@var{type}: is PEM or DER + +@var{pass}: is the key's password + +@var{flags}: an ORed sequence of gnutls_pkcs_encrypt_flags_t + +This function sets a certificate/private key pair in the +gnutls_certificate_credentials_t type. This function may be called +more than once, in case multiple keys/certificates exist for the +server. + +Note that the keyUsage (2.5.29.15) PKIX extension in X.509 certificates +is supported. This means that certificates intended for signing cannot +be used for ciphersuites that require encryption. + +If the certificate and the private key are given in PEM encoding +then the strings that hold their values must be null terminated. + +The @code{key} may be @code{NULL} if you are using a sign callback, see +@code{gnutls_sign_callback_set()} . + +Note that, this function by default returns zero on success and a negative value on error. +Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} is set using @code{gnutls_certificate_set_flags()} +it returns an index (greater or equal to zero). That index can be used to other functions to refer to the added key-pair. + +@strong{Returns:} On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). +@end deftypefun + +@subheading gnutls_certificate_set_x509_simple_pkcs12_file +@anchor{gnutls_certificate_set_x509_simple_pkcs12_file} +@deftypefun {int} {gnutls_certificate_set_x509_simple_pkcs12_file} (gnutls_certificate_credentials_t @var{res}, const char * @var{pkcs12file}, gnutls_x509_crt_fmt_t @var{type}, const char * @var{password}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{pkcs12file}: filename of file containing PKCS@code{12} blob. + +@var{type}: is PEM or DER of the @code{pkcs12file} . + +@var{password}: optional password used to decrypt PKCS@code{12} file, bags and keys. + +This function sets a certificate/private key pair and/or a CRL in +the gnutls_certificate_credentials_t type. This function may +be called more than once (in case multiple keys/certificates exist +for the server). + +PKCS@code{12} files with a MAC, encrypted bags and PKCS @code{8} +private keys are supported. However, +only password based security, and the same password for all +operations, are supported. + +PKCS@code{12} file may contain many keys and/or certificates, and this +function will try to auto-detect based on the key ID the certificate +and key pair to use. If the PKCS@code{12} file contain the issuer of +the selected certificate, it will be appended to the certificate +to form a chain. + +If more than one private keys are stored in the PKCS@code{12} file, +then only one key will be read (and it is undefined which one). + +It is believed that the limitations of this function is acceptable +for most usage, and that any more flexibility would introduce +complexity that would make it harder to use this functionality at +all. + +Note that, this function by default returns zero on success and a negative value on error. +Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} is set using @code{gnutls_certificate_set_flags()} +it returns an index (greater or equal to zero). That index can be used to other functions to refer to the added key-pair. + +@strong{Returns:} On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). +@end deftypefun + +@subheading gnutls_certificate_set_x509_simple_pkcs12_mem +@anchor{gnutls_certificate_set_x509_simple_pkcs12_mem} +@deftypefun {int} {gnutls_certificate_set_x509_simple_pkcs12_mem} (gnutls_certificate_credentials_t @var{res}, const gnutls_datum_t * @var{p12blob}, gnutls_x509_crt_fmt_t @var{type}, const char * @var{password}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{p12blob}: the PKCS@code{12} blob. + +@var{type}: is PEM or DER of the @code{pkcs12file} . + +@var{password}: optional password used to decrypt PKCS@code{12} file, bags and keys. + +This function sets a certificate/private key pair and/or a CRL in +the gnutls_certificate_credentials_t type. This function may +be called more than once (in case multiple keys/certificates exist +for the server). + +Encrypted PKCS@code{12} bags and PKCS@code{8} private keys are supported. However, +only password based security, and the same password for all +operations, are supported. + +PKCS@code{12} file may contain many keys and/or certificates, and this +function will try to auto-detect based on the key ID the certificate +and key pair to use. If the PKCS@code{12} file contain the issuer of +the selected certificate, it will be appended to the certificate +to form a chain. + +If more than one private keys are stored in the PKCS@code{12} file, +then only one key will be read (and it is undefined which one). + +It is believed that the limitations of this function is acceptable +for most usage, and that any more flexibility would introduce +complexity that would make it harder to use this functionality at +all. + +Note that, this function by default returns zero on success and a negative value on error. +Since 3.5.6, when the flag @code{GNUTLS_CERTIFICATE_API_V2} is set using @code{gnutls_certificate_set_flags()} +it returns an index (greater or equal to zero). That index can be used to other functions to refer to the added key-pair. + +@strong{Returns:} On success this functions returns zero, and otherwise a negative value on error (see above for modifying that behavior). + +@strong{Since:} 2.8.0 +@end deftypefun + +@subheading gnutls_certificate_set_x509_system_trust +@anchor{gnutls_certificate_set_x509_system_trust} +@deftypefun {int} {gnutls_certificate_set_x509_system_trust} (gnutls_certificate_credentials_t @var{cred}) +@var{cred}: is a @code{gnutls_certificate_credentials_t} type. + +This function adds the system's default trusted CAs in order to +verify client or server certificates. + +In the case the system is currently unsupported @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} +is returned. + +@strong{Returns:} the number of certificates processed or a negative error code +on error. + +@strong{Since:} 3.0.20 +@end deftypefun + +@subheading gnutls_certificate_set_x509_trust +@anchor{gnutls_certificate_set_x509_trust} +@deftypefun {int} {gnutls_certificate_set_x509_trust} (gnutls_certificate_credentials_t @var{res}, gnutls_x509_crt_t * @var{ca_list}, int @var{ca_list_size}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{ca_list}: is a list of trusted CAs + +@var{ca_list_size}: holds the size of the CA list + +This function adds the trusted CAs in order to verify client +or server certificates. In case of a client this is not required +to be called if the certificates are not verified using +@code{gnutls_certificate_verify_peers2()} . +This function may be called multiple times. + +In case of a server the CAs set here will be sent to the client if +a certificate request is sent. This can be disabled using +@code{gnutls_certificate_send_x509_rdn_sequence()} . + +@strong{Returns:} the number of certificates processed or a negative error code +on error. + +@strong{Since:} 2.4.0 +@end deftypefun + +@subheading gnutls_certificate_set_x509_trust_dir +@anchor{gnutls_certificate_set_x509_trust_dir} +@deftypefun {int} {gnutls_certificate_set_x509_trust_dir} (gnutls_certificate_credentials_t @var{cred}, const char * @var{ca_dir}, gnutls_x509_crt_fmt_t @var{type}) +@var{cred}: is a @code{gnutls_certificate_credentials_t} type. + +@var{ca_dir}: is a directory containing the list of trusted CAs (DER or PEM list) + +@var{type}: is PEM or DER + +This function adds the trusted CAs present in the directory in order to +verify client or server certificates. This function is identical +to @code{gnutls_certificate_set_x509_trust_file()} but loads all certificates +in a directory. + +@strong{Returns:} the number of certificates processed + +@strong{Since:} 3.3.6 +@end deftypefun + +@subheading gnutls_certificate_set_x509_trust_file +@anchor{gnutls_certificate_set_x509_trust_file} +@deftypefun {int} {gnutls_certificate_set_x509_trust_file} (gnutls_certificate_credentials_t @var{cred}, const char * @var{cafile}, gnutls_x509_crt_fmt_t @var{type}) +@var{cred}: is a @code{gnutls_certificate_credentials_t} type. + +@var{cafile}: is a file containing the list of trusted CAs (DER or PEM list) + +@var{type}: is PEM or DER + +This function adds the trusted CAs in order to verify client or +server certificates. In case of a client this is not required to +be called if the certificates are not verified using +@code{gnutls_certificate_verify_peers2()} . This function may be called +multiple times. + +In case of a server the names of the CAs set here will be sent to +the client if a certificate request is sent. This can be disabled +using @code{gnutls_certificate_send_x509_rdn_sequence()} . + +This function can also accept URLs. In that case it +will import all certificates that are marked as trusted. Note +that the supported URLs are the ones indicated by @code{gnutls_url_is_supported()} . + +@strong{Returns:} the number of certificates processed +@end deftypefun + +@subheading gnutls_certificate_set_x509_trust_mem +@anchor{gnutls_certificate_set_x509_trust_mem} +@deftypefun {int} {gnutls_certificate_set_x509_trust_mem} (gnutls_certificate_credentials_t @var{res}, const gnutls_datum_t * @var{ca}, gnutls_x509_crt_fmt_t @var{type}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type. + +@var{ca}: is a list of trusted CAs or a DER certificate + +@var{type}: is DER or PEM + +This function adds the trusted CAs in order to verify client or +server certificates. In case of a client this is not required to be +called if the certificates are not verified using +@code{gnutls_certificate_verify_peers2()} . This function may be called +multiple times. + +In case of a server the CAs set here will be sent to the client if +a certificate request is sent. This can be disabled using +@code{gnutls_certificate_send_x509_rdn_sequence()} . + +@strong{Returns:} the number of certificates processed or a negative error code +on error. +@end deftypefun + +@subheading gnutls_certificate_type_get +@anchor{gnutls_certificate_type_get} +@deftypefun {gnutls_certificate_type_t} {gnutls_certificate_type_get} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function returns the type of the certificate that is negotiated +for this side to send to the peer. The certificate type is by default +X.509, unless an alternative certificate type is enabled by +@code{gnutls_init()} and negotiated during the session. + +Resumed sessions will return the certificate type that was negotiated +and used in the original session. + +As of version 3.6.4 it is recommended to use +@code{gnutls_certificate_type_get2()} which is more fine-grained. + +@strong{Returns:} the currently used @code{gnutls_certificate_type_t} certificate +type as negotiated for 'our' side of the connection. +@end deftypefun + +@subheading gnutls_certificate_type_get2 +@anchor{gnutls_certificate_type_get2} +@deftypefun {gnutls_certificate_type_t} {gnutls_certificate_type_get2} (gnutls_session_t @var{session}, gnutls_ctype_target_t @var{target}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{target}: is a @code{gnutls_ctype_target_t} type. + +This function returns the type of the certificate that a side +is negotiated to use. The certificate type is by default X.509, +unless an alternative certificate type is enabled by @code{gnutls_init()} and +negotiated during the session. + +The @code{target} parameter specifies whether to request the negotiated +certificate type for the client (@code{GNUTLS_CTYPE_CLIENT} ), +or for the server (@code{GNUTLS_CTYPE_SERVER} ). Additionally, in P2P mode +connection set up where you don't know in advance who will be client +and who will be server you can use the flag (@code{GNUTLS_CTYPE_OURS} ) and +(@code{GNUTLS_CTYPE_PEERS} ) to retrieve the corresponding certificate types. + +Resumed sessions will return the certificate type that was negotiated +and used in the original session. That is, this function can be used +to reliably determine the type of the certificate returned by +@code{gnutls_certificate_get_peers()} . + +@strong{Returns:} the currently used @code{gnutls_certificate_type_t} certificate +type for the client or the server. + +@strong{Since:} 3.6.4 +@end deftypefun + +@subheading gnutls_certificate_type_get_id +@anchor{gnutls_certificate_type_get_id} +@deftypefun {gnutls_certificate_type_t} {gnutls_certificate_type_get_id} (const char * @var{name}) +@var{name}: is a certificate type name + +The names are compared in a case insensitive way. + +@strong{Returns:} a @code{gnutls_certificate_type_t} for the specified in a +string certificate type, or @code{GNUTLS_CRT_UNKNOWN} on error. +@end deftypefun + +@subheading gnutls_certificate_type_get_name +@anchor{gnutls_certificate_type_get_name} +@deftypefun {const char *} {gnutls_certificate_type_get_name} (gnutls_certificate_type_t @var{type}) +@var{type}: is a certificate type + +Convert a @code{gnutls_certificate_type_t} type to a string. + +@strong{Returns:} a string that contains the name of the specified +certificate type, or @code{NULL} in case of unknown types. +@end deftypefun + +@subheading gnutls_certificate_type_list +@anchor{gnutls_certificate_type_list} +@deftypefun {const gnutls_certificate_type_t *} {gnutls_certificate_type_list} ( @var{void}) + +Get a list of certificate types. + +@strong{Returns:} a (0)-terminated list of @code{gnutls_certificate_type_t} +integers indicating the available certificate types. +@end deftypefun + +@subheading gnutls_certificate_verification_status_print +@anchor{gnutls_certificate_verification_status_print} +@deftypefun {int} {gnutls_certificate_verification_status_print} (unsigned int @var{status}, gnutls_certificate_type_t @var{type}, gnutls_datum_t * @var{out}, unsigned int @var{flags}) +@var{status}: The status flags to be printed + +@var{type}: The certificate type + +@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{gnutls_certificate_verify_peers3()} . + +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. + +@strong{Since:} 3.1.4 +@end deftypefun + +@subheading gnutls_certificate_verify_peers +@anchor{gnutls_certificate_verify_peers} +@deftypefun {int} {gnutls_certificate_verify_peers} (gnutls_session_t @var{session}, gnutls_typed_vdata_st * @var{data}, unsigned int @var{elements}, unsigned int * @var{status}) +@var{session}: is a gnutls session + +@var{data}: an array of typed data + +@var{elements}: the number of data elements + +@var{status}: is the output of the verification + +This function will verify the peer's certificate and store the +the status in the @code{status} variable as a bitwise OR of gnutls_certificate_status_t +values or zero if the certificate is trusted. Note that value in @code{status} is set only when the return value of this function is success (i.e, failure +to trust a certificate does not imply a negative return value). +The default verification flags used by this function can be overridden +using @code{gnutls_certificate_set_verify_flags()} . See the documentation +of @code{gnutls_certificate_verify_peers2()} for details in the verification process. + +This function will take into account the stapled OCSP responses sent by the server, +as well as the following X.509 certificate extensions: Name Constraints, +Key Usage, and Basic Constraints (pathlen). + +The acceptable @code{data} types are @code{GNUTLS_DT_DNS_HOSTNAME} , @code{GNUTLS_DT_RFC822NAME} and @code{GNUTLS_DT_KEY_PURPOSE_OID} . +The former two accept as data a null-terminated hostname or email address, and the latter a null-terminated +object identifier (e.g., @code{GNUTLS_KP_TLS_WWW_SERVER} ). + +If a DNS hostname is provided then this function will compare +the hostname in the certificate against the given. If names do not match the +@code{GNUTLS_CERT_UNEXPECTED_OWNER} status flag will be set. +If a key purpose OID is provided and the end-certificate contains the extended key +usage PKIX extension, it will be required to be have the provided key purpose +or be marked for any purpose, otherwise verification status will have the +@code{GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE} flag set. + +To avoid denial of service attacks some +default upper limits regarding the certificate key size and chain +size are set. To override them use @code{gnutls_certificate_set_verify_limits()} . + +Note that when using raw public-keys verification will not work because there is +no corresponding certificate body belonging to the raw key that can be verified. In that +case this function will return @code{GNUTLS_E_INVALID_REQUEST} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) when the validation is performed, or a negative error code otherwise. +A successful error code means that the @code{status} parameter must be checked to obtain the validation status. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_certificate_verify_peers2 +@anchor{gnutls_certificate_verify_peers2} +@deftypefun {int} {gnutls_certificate_verify_peers2} (gnutls_session_t @var{session}, unsigned int * @var{status}) +@var{session}: is a gnutls session + +@var{status}: is the output of the verification + +This function will verify the peer's certificate and store +the status in the @code{status} variable as a bitwise OR of gnutls_certificate_status_t +values or zero if the certificate is trusted. Note that value in @code{status} is set only when the return value of this function is success (i.e, failure +to trust a certificate does not imply a negative return value). +The default verification flags used by this function can be overridden +using @code{gnutls_certificate_set_verify_flags()} . + +This function will take into account the stapled OCSP responses sent by the server, +as well as the following X.509 certificate extensions: Name Constraints, +Key Usage, and Basic Constraints (pathlen). + +Note that you must also check the peer's name in order to check if +the verified certificate belongs to the actual peer, see @code{gnutls_x509_crt_check_hostname()} , +or use @code{gnutls_certificate_verify_peers3()} . + +To avoid denial of service attacks some +default upper limits regarding the certificate key size and chain +size are set. To override them use @code{gnutls_certificate_set_verify_limits()} . + +Note that when using raw public-keys verification will not work because there is +no corresponding certificate body belonging to the raw key that can be verified. In that +case this function will return @code{GNUTLS_E_INVALID_REQUEST} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) when the validation is performed, or a negative error code otherwise. +A successful error code means that the @code{status} parameter must be checked to obtain the validation status. +@end deftypefun + +@subheading gnutls_certificate_verify_peers3 +@anchor{gnutls_certificate_verify_peers3} +@deftypefun {int} {gnutls_certificate_verify_peers3} (gnutls_session_t @var{session}, const char * @var{hostname}, unsigned int * @var{status}) +@var{session}: is a gnutls session + +@var{hostname}: is the expected name of the peer; may be @code{NULL} + +@var{status}: is the output of the verification + +This function will verify the peer's certificate and store the +the status in the @code{status} variable as a bitwise OR of gnutls_certificate_status_t +values or zero if the certificate is trusted. Note that value in @code{status} is set only when the return value of this function is success (i.e, failure +to trust a certificate does not imply a negative return value). +The default verification flags used by this function can be overridden +using @code{gnutls_certificate_set_verify_flags()} . See the documentation +of @code{gnutls_certificate_verify_peers2()} for details in the verification process. + +This function will take into account the stapled OCSP responses sent by the server, +as well as the following X.509 certificate extensions: Name Constraints, +Key Usage, and Basic Constraints (pathlen). + +If the @code{hostname} provided is non-NULL then this function will compare +the hostname in the certificate against it. The comparison will follow +the RFC6125 recommendations. If names do not match the +@code{GNUTLS_CERT_UNEXPECTED_OWNER} status flag will be set. + +In order to verify the purpose of the end-certificate (by checking the extended +key usage), use @code{gnutls_certificate_verify_peers()} . + +To avoid denial of service attacks some +default upper limits regarding the certificate key size and chain +size are set. To override them use @code{gnutls_certificate_set_verify_limits()} . + +Note that when using raw public-keys verification will not work because there is +no corresponding certificate body belonging to the raw key that can be verified. In that +case this function will return @code{GNUTLS_E_INVALID_REQUEST} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) when the validation is performed, or a negative error code otherwise. +A successful error code means that the @code{status} parameter must be checked to obtain the validation status. + +@strong{Since:} 3.1.4 +@end deftypefun + +@subheading gnutls_check_version +@anchor{gnutls_check_version} +@deftypefun {const char *} {gnutls_check_version} (const char * @var{req_version}) +@var{req_version}: version string to compare with, or @code{NULL} . + +Check the GnuTLS Library version against the provided string. +See @code{GNUTLS_VERSION} for a suitable @code{req_version} string. + +See also @code{gnutls_check_version_numeric()} , which provides this +functionality as a macro. + +@strong{Returns:} Check that the version of the library is at +minimum the one given as a string in @code{req_version} and return the +actual version string of the library; return @code{NULL} if the +condition is not met. If @code{NULL} is passed to this function no +check is done and only the version string is returned. +@end deftypefun + +@subheading gnutls_cipher_get +@anchor{gnutls_cipher_get} +@deftypefun {gnutls_cipher_algorithm_t} {gnutls_cipher_get} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Get the currently used cipher. + +@strong{Returns:} the currently used cipher, a @code{gnutls_cipher_algorithm_t} +type. +@end deftypefun + +@subheading gnutls_cipher_get_id +@anchor{gnutls_cipher_get_id} +@deftypefun {gnutls_cipher_algorithm_t} {gnutls_cipher_get_id} (const char * @var{name}) +@var{name}: is a cipher algorithm name + +The names are compared in a case insensitive way. + +@strong{Returns:} return a @code{gnutls_cipher_algorithm_t} value corresponding to +the specified cipher, or @code{GNUTLS_CIPHER_UNKNOWN} on error. +@end deftypefun + +@subheading gnutls_cipher_get_key_size +@anchor{gnutls_cipher_get_key_size} +@deftypefun {size_t} {gnutls_cipher_get_key_size} (gnutls_cipher_algorithm_t @var{algorithm}) +@var{algorithm}: is an encryption algorithm + +This function returns the key size of the provided algorithm. + +@strong{Returns:} length (in bytes) of the given cipher's key size, or 0 if +the given cipher is invalid. +@end deftypefun + +@subheading gnutls_cipher_get_name +@anchor{gnutls_cipher_get_name} +@deftypefun {const char *} {gnutls_cipher_get_name} (gnutls_cipher_algorithm_t @var{algorithm}) +@var{algorithm}: is an encryption algorithm + +Convert a @code{gnutls_cipher_algorithm_t} type to a string. + +@strong{Returns:} a pointer to a string that contains the name of the +specified cipher, or @code{NULL} . +@end deftypefun + +@subheading gnutls_cipher_list +@anchor{gnutls_cipher_list} +@deftypefun {const gnutls_cipher_algorithm_t *} {gnutls_cipher_list} ( @var{void}) + +Get a list of supported cipher algorithms. Note that not +necessarily all ciphers are supported as TLS cipher suites. For +example, DES is not supported as a cipher suite, but is supported +for other purposes (e.g., PKCS@code{8} or similar). + +This function is not thread safe. + +@strong{Returns:} a (0)-terminated list of @code{gnutls_cipher_algorithm_t} +integers indicating the available ciphers. +@end deftypefun + +@subheading gnutls_cipher_suite_get_name +@anchor{gnutls_cipher_suite_get_name} +@deftypefun {const char *} {gnutls_cipher_suite_get_name} (gnutls_kx_algorithm_t @var{kx_algorithm}, gnutls_cipher_algorithm_t @var{cipher_algorithm}, gnutls_mac_algorithm_t @var{mac_algorithm}) +@var{kx_algorithm}: is a Key exchange algorithm + +@var{cipher_algorithm}: is a cipher algorithm + +@var{mac_algorithm}: is a MAC algorithm + +This function returns the ciphersuite name under TLS1.2 or earlier +versions when provided with individual algorithms. The full cipher suite +name must be prepended by TLS or SSL depending of the protocol in use. + +To get a description of the current ciphersuite across versions, it +is recommended to use @code{gnutls_session_get_desc()} . + +@strong{Returns:} a string that contains the name of a TLS cipher suite, +specified by the given algorithms, or @code{NULL} . +@end deftypefun + +@subheading gnutls_cipher_suite_info +@anchor{gnutls_cipher_suite_info} +@deftypefun {const char *} {gnutls_cipher_suite_info} (size_t @var{idx}, unsigned char * @var{cs_id}, gnutls_kx_algorithm_t * @var{kx}, gnutls_cipher_algorithm_t * @var{cipher}, gnutls_mac_algorithm_t * @var{mac}, gnutls_protocol_t * @var{min_version}) +@var{idx}: index of cipher suite to get information about, starts on 0. + +@var{cs_id}: output buffer with room for 2 bytes, indicating cipher suite value + +@var{kx}: output variable indicating key exchange algorithm, or @code{NULL} . + +@var{cipher}: output variable indicating cipher, or @code{NULL} . + +@var{mac}: output variable indicating MAC algorithm, or @code{NULL} . + +@var{min_version}: output variable indicating TLS protocol version, or @code{NULL} . + +Get information about supported cipher suites. Use the function +iteratively to get information about all supported cipher suites. +Call with idx=0 to get information about first cipher suite, then +idx=1 and so on until the function returns NULL. + +@strong{Returns:} the name of @code{idx} cipher suite, and set the information +about the cipher suite in the output variables. If @code{idx} is out of +bounds, @code{NULL} is returned. +@end deftypefun + +@subheading gnutls_ciphersuite_get +@anchor{gnutls_ciphersuite_get} +@deftypefun {const char *} {gnutls_ciphersuite_get} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Get the canonical name of negotiated TLS ciphersuite. The names +returned by this function match the IANA registry, with one +exception: + +TLS_DHE_DSS_RC4_128_SHA @{ 0x00, 0x66 @} + +which is reserved for compatibility. + +To get a detailed description of the current ciphersuite, it is +recommended to use @code{gnutls_session_get_desc()} . + +@strong{Returns:} a string that contains the canonical name of a TLS ciphersuite, +or @code{NULL} if the handshake is not completed. + +@strong{Since:} 3.7.4 +@end deftypefun + +@subheading gnutls_compress_certificate_get_selected_method +@anchor{gnutls_compress_certificate_get_selected_method} +@deftypefun {gnutls_compression_method_t} {gnutls_compress_certificate_get_selected_method} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function returns the certificate compression method that has been +selected to compress the certificate before sending it to the peer. +The selection is done based on the local list of supported compression +methods and the peer's requested compression methods. + +@strong{Returns:} selected certificate compression method. + +Since 3.7.4 +@end deftypefun + +@subheading gnutls_compress_certificate_set_methods +@anchor{gnutls_compress_certificate_set_methods} +@deftypefun {int} {gnutls_compress_certificate_set_methods} (gnutls_session_t @var{session}, const gnutls_compression_method_t * @var{methods}, size_t @var{methods_len}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{methods}: is a list of supported compression methods. + +@var{methods_len}: number of compression methods in @code{methods} + +This function sets the supported compression methods for certificate compression +for the given session. The list of supported compression methods will be used +for a) requesting the compression of peer's certificate and b) selecting the +method to compress the local certificate before sending it to the peer. +The order of compression methods inside the list does matter as the method +that appears earlier in the list will be preffered before the later ones. +Note that even if you set the list of supported compression methods, the +compression might not be used if the peer does not support any of your chosen +compression methods. + +The list of supported compression methods must meet the following criteria: +Argument @code{methods} must be an array of valid compression methods of type +@code{gnutls_compression_method_t} . Argument @code{methods_len} must contain the number of +compression methods stored in the @code{methods} array and must be within range <1, 127>. +The length constraints are defined by @code{MIN_COMPRESS_CERTIFICATE_METHODS} +and @code{MAX_COMPRESS_CERTIFICATE_METHODS} macros located in the header file +compress_certificate.h. + +If either @code{methods} or @code{methods_len} is equal to 0, current list of supported +compression methods will be unset. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +Since 3.7.4 +@end deftypefun + +@subheading gnutls_credentials_clear +@anchor{gnutls_credentials_clear} +@deftypefun {void} {gnutls_credentials_clear} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Clears all the credentials previously set in this session. +@end deftypefun + +@subheading gnutls_credentials_get +@anchor{gnutls_credentials_get} +@deftypefun {int} {gnutls_credentials_get} (gnutls_session_t @var{session}, gnutls_credentials_type_t @var{type}, void ** @var{cred}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{type}: is the type of the credentials to return + +@var{cred}: will contain the credentials. + +Returns the previously provided credentials structures. + +For @code{GNUTLS_CRD_ANON} , @code{cred} will be +@code{gnutls_anon_client_credentials_t} in case of a client. In case of +a server it should be @code{gnutls_anon_server_credentials_t} . + +For @code{GNUTLS_CRD_SRP} , @code{cred} will be @code{gnutls_srp_client_credentials_t} +in case of a client, and @code{gnutls_srp_server_credentials_t} , in case +of a server. + +For @code{GNUTLS_CRD_CERTIFICATE} , @code{cred} will be +@code{gnutls_certificate_credentials_t} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +@strong{Since:} 3.3.3 +@end deftypefun + +@subheading gnutls_credentials_set +@anchor{gnutls_credentials_set} +@deftypefun {int} {gnutls_credentials_set} (gnutls_session_t @var{session}, gnutls_credentials_type_t @var{type}, void * @var{cred}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{type}: is the type of the credentials + +@var{cred}: the credentials to set + +Sets the needed credentials for the specified type. E.g. username, +password - or public and private keys etc. The @code{cred} parameter is +a structure that depends on the specified type and on the current +session (client or server). + +In order to minimize memory usage, and share credentials between +several threads gnutls keeps a pointer to cred, and not the whole +cred structure. Thus you will have to keep the structure allocated +until you call @code{gnutls_deinit()} . + +For @code{GNUTLS_CRD_ANON} , @code{cred} should be +@code{gnutls_anon_client_credentials_t} in case of a client. In case of +a server it should be @code{gnutls_anon_server_credentials_t} . + +For @code{GNUTLS_CRD_SRP} , @code{cred} should be @code{gnutls_srp_client_credentials_t} +in case of a client, and @code{gnutls_srp_server_credentials_t} , in case +of a server. + +For @code{GNUTLS_CRD_CERTIFICATE} , @code{cred} should be +@code{gnutls_certificate_credentials_t} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_db_check_entry +@anchor{gnutls_db_check_entry} +@deftypefun {int} {gnutls_db_check_entry} (gnutls_session_t @var{session}, gnutls_datum_t @var{session_entry}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{session_entry}: is the session data (not key) + +This function has no effect. + +@strong{Returns:} Returns @code{GNUTLS_E_EXPIRED} , if the database entry has +expired or 0 otherwise. + +@strong{Deprecated:} This function is deprecated. +@end deftypefun + +@subheading gnutls_db_check_entry_expire_time +@anchor{gnutls_db_check_entry_expire_time} +@deftypefun {time_t} {gnutls_db_check_entry_expire_time} (gnutls_datum_t * @var{entry}) +@var{entry}: is a pointer to a @code{gnutls_datum_t} type. + +This function returns the time that this entry will expire. +It can be used for database entry expiration. + +@strong{Returns:} The time this entry will expire, or zero on error. + +@strong{Since:} 3.6.5 +@end deftypefun + +@subheading gnutls_db_check_entry_time +@anchor{gnutls_db_check_entry_time} +@deftypefun {time_t} {gnutls_db_check_entry_time} (gnutls_datum_t * @var{entry}) +@var{entry}: is a pointer to a @code{gnutls_datum_t} type. + +This function returns the time that this entry was active. +It can be used for database entry expiration. + +@strong{Returns:} The time this entry was created, or zero on error. +@end deftypefun + +@subheading gnutls_db_get_default_cache_expiration +@anchor{gnutls_db_get_default_cache_expiration} +@deftypefun {unsigned} {gnutls_db_get_default_cache_expiration} ( @var{void}) + +Returns the expiration time (in seconds) of stored sessions for resumption. +@end deftypefun + +@subheading gnutls_db_get_ptr +@anchor{gnutls_db_get_ptr} +@deftypefun {void *} {gnutls_db_get_ptr} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Get db function pointer. + +@strong{Returns:} the pointer that will be sent to db store, retrieve and +delete functions, as the first argument. +@end deftypefun + +@subheading gnutls_db_remove_session +@anchor{gnutls_db_remove_session} +@deftypefun {void} {gnutls_db_remove_session} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function will remove the current session data from the +session database. This will prevent future handshakes reusing +these session data. This function should be called if a session +was terminated abnormally, and before @code{gnutls_deinit()} is called. + +Normally @code{gnutls_deinit()} will remove abnormally terminated +sessions. +@end deftypefun + +@subheading gnutls_db_set_cache_expiration +@anchor{gnutls_db_set_cache_expiration} +@deftypefun {void} {gnutls_db_set_cache_expiration} (gnutls_session_t @var{session}, int @var{seconds}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{seconds}: is the number of seconds. + +Set the expiration time for resumed sessions. The default is 21600 +(6 hours) at the time of writing. + +The maximum value that can be set using this function is 604800 +(7 days). +@end deftypefun + +@subheading gnutls_db_set_ptr +@anchor{gnutls_db_set_ptr} +@deftypefun {void} {gnutls_db_set_ptr} (gnutls_session_t @var{session}, void * @var{ptr}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{ptr}: is the pointer + +Sets the pointer that will be provided to db store, retrieve and +delete functions, as the first argument. +@end deftypefun + +@subheading gnutls_db_set_remove_function +@anchor{gnutls_db_set_remove_function} +@deftypefun {void} {gnutls_db_set_remove_function} (gnutls_session_t @var{session}, gnutls_db_remove_func @var{rem_func}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{rem_func}: is the function. + +Sets the function that will be used to remove data from the +resumed sessions database. This function must return 0 on success. + +The first argument to @code{rem_func} will be null unless +@code{gnutls_db_set_ptr()} has been called. +@end deftypefun + +@subheading gnutls_db_set_retrieve_function +@anchor{gnutls_db_set_retrieve_function} +@deftypefun {void} {gnutls_db_set_retrieve_function} (gnutls_session_t @var{session}, gnutls_db_retr_func @var{retr_func}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{retr_func}: is the function. + +Sets the function that will be used to retrieve data from the +resumed sessions database. This function must return a +gnutls_datum_t containing the data on success, or a gnutls_datum_t +containing null and 0 on failure. + +The datum's data must be allocated using the function +@code{gnutls_malloc()} . + +The first argument to @code{retr_func} will be null unless +@code{gnutls_db_set_ptr()} has been called. +@end deftypefun + +@subheading gnutls_db_set_store_function +@anchor{gnutls_db_set_store_function} +@deftypefun {void} {gnutls_db_set_store_function} (gnutls_session_t @var{session}, gnutls_db_store_func @var{store_func}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{store_func}: is the function + +Sets the function that will be used to store data in the resumed +sessions database. This function must return 0 on success. + +The first argument to @code{store_func} will be null unless +@code{gnutls_db_set_ptr()} has been called. +@end deftypefun + +@subheading gnutls_deinit +@anchor{gnutls_deinit} +@deftypefun {void} {gnutls_deinit} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function clears all buffers associated with the @code{session} . +This function will also remove session data from the session +database if the session was terminated abnormally. +@end deftypefun + +@subheading gnutls_dh_get_group +@anchor{gnutls_dh_get_group} +@deftypefun {int} {gnutls_dh_get_group} (gnutls_session_t @var{session}, gnutls_datum_t * @var{raw_gen}, gnutls_datum_t * @var{raw_prime}) +@var{session}: is a gnutls session + +@var{raw_gen}: will hold the generator. + +@var{raw_prime}: will hold the prime. + +This function will return the group parameters used in the last +Diffie-Hellman key exchange with the peer. These are the prime and +the generator used. This function should be used for both +anonymous and ephemeral Diffie-Hellman. The output parameters must +be freed with @code{gnutls_free()} . + +Note, that the prime and generator are exported as non-negative +integers and may include a leading zero byte. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_dh_get_peers_public_bits +@anchor{gnutls_dh_get_peers_public_bits} +@deftypefun {int} {gnutls_dh_get_peers_public_bits} (gnutls_session_t @var{session}) +@var{session}: is a gnutls session + +Get the Diffie-Hellman public key bit size. Can be used for both +anonymous and ephemeral Diffie-Hellman. + +@strong{Returns:} The public key bit size used in the last Diffie-Hellman +key exchange with the peer, or a negative error code in case of error. +@end deftypefun + +@subheading gnutls_dh_get_prime_bits +@anchor{gnutls_dh_get_prime_bits} +@deftypefun {int} {gnutls_dh_get_prime_bits} (gnutls_session_t @var{session}) +@var{session}: is a gnutls session + +This function will return the bits of the prime used in the last +Diffie-Hellman key exchange with the peer. Should be used for both +anonymous and ephemeral Diffie-Hellman. Note that some ciphers, +like RSA and DSA without DHE, do not use a Diffie-Hellman key +exchange, and then this function will return 0. + +@strong{Returns:} The Diffie-Hellman bit strength is returned, or 0 if no +Diffie-Hellman key exchange was done, or a negative error code on +failure. +@end deftypefun + +@subheading gnutls_dh_get_pubkey +@anchor{gnutls_dh_get_pubkey} +@deftypefun {int} {gnutls_dh_get_pubkey} (gnutls_session_t @var{session}, gnutls_datum_t * @var{raw_key}) +@var{session}: is a gnutls session + +@var{raw_key}: will hold the public key. + +This function will return the peer's public key used in the last +Diffie-Hellman key exchange. This function should be used for both +anonymous and ephemeral Diffie-Hellman. The output parameters must +be freed with @code{gnutls_free()} . + +Note, that public key is exported as non-negative +integer and may include a leading zero byte. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_dh_get_secret_bits +@anchor{gnutls_dh_get_secret_bits} +@deftypefun {int} {gnutls_dh_get_secret_bits} (gnutls_session_t @var{session}) +@var{session}: is a gnutls session + +This function will return the bits used in the last Diffie-Hellman +key exchange with the peer. Should be used for both anonymous and +ephemeral Diffie-Hellman. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_dh_params_cpy +@anchor{gnutls_dh_params_cpy} +@deftypefun {int} {gnutls_dh_params_cpy} (gnutls_dh_params_t @var{dst}, gnutls_dh_params_t @var{src}) +@var{dst}: Is the destination parameters, which should be initialized. + +@var{src}: Is the source parameters + +This function will copy the DH parameters structure from source +to destination. The destination should be already initialized. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_dh_params_deinit +@anchor{gnutls_dh_params_deinit} +@deftypefun {void} {gnutls_dh_params_deinit} (gnutls_dh_params_t @var{dh_params}) +@var{dh_params}: The parameters + +This function will deinitialize the DH parameters type. +@end deftypefun + +@subheading gnutls_dh_params_export2_pkcs3 +@anchor{gnutls_dh_params_export2_pkcs3} +@deftypefun {int} {gnutls_dh_params_export2_pkcs3} (gnutls_dh_params_t @var{params}, gnutls_x509_crt_fmt_t @var{format}, gnutls_datum_t * @var{out}) +@var{params}: Holds the DH parameters + +@var{format}: the format of output params. One of PEM or DER. + +@var{out}: will contain a PKCS3 DHParams structure PEM or DER encoded + +This function will export the given dh parameters to a PKCS3 +DHParams structure. This is the format generated by "openssl dhparam" tool. +The data in @code{out} will be allocated using @code{gnutls_malloc()} . + +If the structure is PEM encoded, it will have a header +of "BEGIN DH PARAMETERS". + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +@strong{Since:} 3.1.3 +@end deftypefun + +@subheading gnutls_dh_params_export_pkcs3 +@anchor{gnutls_dh_params_export_pkcs3} +@deftypefun {int} {gnutls_dh_params_export_pkcs3} (gnutls_dh_params_t @var{params}, gnutls_x509_crt_fmt_t @var{format}, unsigned char * @var{params_data}, size_t * @var{params_data_size}) +@var{params}: Holds the DH parameters + +@var{format}: the format of output params. One of PEM or DER. + +@var{params_data}: will contain a PKCS3 DHParams structure PEM or DER encoded + +@var{params_data_size}: holds the size of params_data (and will be replaced by the actual size of parameters) + +This function will export the given dh parameters to a PKCS3 +DHParams structure. This is the format generated by "openssl dhparam" tool. +If the buffer provided is not long enough to hold the output, then +GNUTLS_E_SHORT_MEMORY_BUFFER will be returned. + +If the structure is PEM encoded, it will have a header +of "BEGIN DH PARAMETERS". + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_dh_params_export_raw +@anchor{gnutls_dh_params_export_raw} +@deftypefun {int} {gnutls_dh_params_export_raw} (gnutls_dh_params_t @var{params}, gnutls_datum_t * @var{prime}, gnutls_datum_t * @var{generator}, unsigned int * @var{bits}) +@var{params}: Holds the DH parameters + +@var{prime}: will hold the new prime + +@var{generator}: will hold the new generator + +@var{bits}: if non null will hold the secret key's number of bits + +This function will export the pair of prime and generator for use +in the Diffie-Hellman key exchange. The new parameters will be +allocated using @code{gnutls_malloc()} and will be stored in the +appropriate datum. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_dh_params_generate2 +@anchor{gnutls_dh_params_generate2} +@deftypefun {int} {gnutls_dh_params_generate2} (gnutls_dh_params_t @var{dparams}, unsigned int @var{bits}) +@var{dparams}: The parameters + +@var{bits}: is the prime's number of bits + +This function will generate a new pair of prime and generator for use in +the Diffie-Hellman key exchange. This may take long time. + +It is recommended not to set the number of bits directly, but +use @code{gnutls_sec_param_to_pk_bits()} instead. +Also note that the DH parameters are only useful to servers. +Since clients use the parameters sent by the server, it's of +no use to call this in client side. + +The parameters generated are of the DSA form. It also is possible +to generate provable parameters (following the Shawe-Taylor +algorithm), using @code{gnutls_x509_privkey_generate2()} with DSA option +and the @code{GNUTLS_PRIVKEY_FLAG_PROVABLE} flag set. These can the +be imported with @code{gnutls_dh_params_import_dsa()} . + +It is no longer recommended for applications to generate parameters. +See the "Parameter generation" section in the manual. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_dh_params_import_dsa +@anchor{gnutls_dh_params_import_dsa} +@deftypefun {int} {gnutls_dh_params_import_dsa} (gnutls_dh_params_t @var{dh_params}, gnutls_x509_privkey_t @var{key}) +@var{dh_params}: The parameters + +@var{key}: holds a DSA private key + +This function will import the prime and generator of the DSA key for use +in the Diffie-Hellman key exchange. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_dh_params_import_pkcs3 +@anchor{gnutls_dh_params_import_pkcs3} +@deftypefun {int} {gnutls_dh_params_import_pkcs3} (gnutls_dh_params_t @var{params}, const gnutls_datum_t * @var{pkcs3_params}, gnutls_x509_crt_fmt_t @var{format}) +@var{params}: The parameters + +@var{pkcs3_params}: should contain a PKCS3 DHParams structure PEM or DER encoded + +@var{format}: the format of params. PEM or DER. + +This function will extract the DHParams found in a PKCS3 formatted +structure. This is the format generated by "openssl dhparam" tool. + +If the structure is PEM encoded, it should have a header +of "BEGIN DH PARAMETERS". + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_dh_params_import_raw +@anchor{gnutls_dh_params_import_raw} +@deftypefun {int} {gnutls_dh_params_import_raw} (gnutls_dh_params_t @var{dh_params}, const gnutls_datum_t * @var{prime}, const gnutls_datum_t * @var{generator}) +@var{dh_params}: The parameters + +@var{prime}: holds the new prime + +@var{generator}: holds the new generator + +This function will replace the pair of prime and generator for use +in the Diffie-Hellman key exchange. The new parameters should be +stored in the appropriate gnutls_datum. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_dh_params_import_raw2 +@anchor{gnutls_dh_params_import_raw2} +@deftypefun {int} {gnutls_dh_params_import_raw2} (gnutls_dh_params_t @var{dh_params}, const gnutls_datum_t * @var{prime}, const gnutls_datum_t * @var{generator}, unsigned @var{key_bits}) +@var{dh_params}: The parameters + +@var{prime}: holds the new prime + +@var{generator}: holds the new generator + +@var{key_bits}: the private key bits (set to zero when unknown) + +This function will replace the pair of prime and generator for use +in the Diffie-Hellman key exchange. The new parameters should be +stored in the appropriate gnutls_datum. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_dh_params_import_raw3 +@anchor{gnutls_dh_params_import_raw3} +@deftypefun {int} {gnutls_dh_params_import_raw3} (gnutls_dh_params_t @var{dh_params}, const gnutls_datum_t * @var{prime}, const gnutls_datum_t * @var{q}, const gnutls_datum_t * @var{generator}) +@var{dh_params}: The parameters + +@var{prime}: holds the new prime + +@var{q}: holds the subgroup if available, otherwise NULL + +@var{generator}: holds the new generator + +This function will replace the pair of prime and generator for use +in the Diffie-Hellman key exchange. The new parameters should be +stored in the appropriate gnutls_datum. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_dh_params_init +@anchor{gnutls_dh_params_init} +@deftypefun {int} {gnutls_dh_params_init} (gnutls_dh_params_t * @var{dh_params}) +@var{dh_params}: The parameters + +This function will initialize the DH parameters type. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_dh_set_prime_bits +@anchor{gnutls_dh_set_prime_bits} +@deftypefun {void} {gnutls_dh_set_prime_bits} (gnutls_session_t @var{session}, unsigned int @var{bits}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{bits}: is the number of bits + +This function sets the number of bits, for use in a Diffie-Hellman +key exchange. This is used both in DH ephemeral and DH anonymous +cipher suites. This will set the minimum size of the prime that +will be used for the handshake. + +In the client side it sets the minimum accepted number of bits. If +a server sends a prime with less bits than that +@code{GNUTLS_E_DH_PRIME_UNACCEPTABLE} will be returned by the handshake. + +Note that this function will warn via the audit log for value that +are believed to be weak. + +The function has no effect in server side. + +Note that since 3.1.7 this function is deprecated. The minimum +number of bits is set by the priority string level. +Also this function must be called after @code{gnutls_priority_set_direct()} +or the set value may be overridden by the selected priority options. +@end deftypefun + +@subheading gnutls_digest_get_id +@anchor{gnutls_digest_get_id} +@deftypefun {gnutls_digest_algorithm_t} {gnutls_digest_get_id} (const char * @var{name}) +@var{name}: is a digest algorithm name + +Convert a string to a @code{gnutls_digest_algorithm_t} value. The names are +compared in a case insensitive way. + +@strong{Returns:} a @code{gnutls_digest_algorithm_t} id of the specified MAC +algorithm string, or @code{GNUTLS_DIG_UNKNOWN} on failure. +@end deftypefun + +@subheading gnutls_digest_get_name +@anchor{gnutls_digest_get_name} +@deftypefun {const char *} {gnutls_digest_get_name} (gnutls_digest_algorithm_t @var{algorithm}) +@var{algorithm}: is a digest algorithm + +Convert a @code{gnutls_digest_algorithm_t} value to a string. + +@strong{Returns:} a string that contains the name of the specified digest +algorithm, or @code{NULL} . +@end deftypefun + +@subheading gnutls_digest_get_oid +@anchor{gnutls_digest_get_oid} +@deftypefun {const char *} {gnutls_digest_get_oid} (gnutls_digest_algorithm_t @var{algorithm}) +@var{algorithm}: is a digest algorithm + +Convert a @code{gnutls_digest_algorithm_t} value to its object identifier. + +@strong{Returns:} a string that contains the object identifier of the specified digest +algorithm, or @code{NULL} . + +@strong{Since:} 3.4.3 +@end deftypefun + +@subheading gnutls_digest_list +@anchor{gnutls_digest_list} +@deftypefun {const gnutls_digest_algorithm_t *} {gnutls_digest_list} ( @var{void}) + +Get a list of hash (digest) algorithms supported by GnuTLS. + +This function is not thread safe. + +@strong{Returns:} Return a (0)-terminated list of @code{gnutls_digest_algorithm_t} +integers indicating the available digests. +@end deftypefun + +@subheading gnutls_digest_set_secure +@anchor{gnutls_digest_set_secure} +@deftypefun {int} {gnutls_digest_set_secure} (gnutls_digest_algorithm_t @var{dig}, unsigned int @var{secure}) +@var{dig}: is a digest algorithm + +@var{secure}: whether to mark the digest algorithm secure + +Modify the previous system wide setting that marked @code{dig} as secure +or insecure. This only has effect when the algorithm is enabled +through the allowlisting mode in the configuration file, or when +the setting is modified with a prior call to this function. + +@strong{Since:} 3.7.3 +@end deftypefun + +@subheading gnutls_early_cipher_get +@anchor{gnutls_early_cipher_get} +@deftypefun {gnutls_cipher_algorithm_t} {gnutls_early_cipher_get} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Get the cipher algorithm used for encrypting early data. + +@strong{Returns:} the cipher used for early data, a +@code{gnutls_cipher_algorithm_t} type. + +@strong{Since:} 3.7.2 +@end deftypefun + +@subheading gnutls_early_prf_hash_get +@anchor{gnutls_early_prf_hash_get} +@deftypefun {gnutls_digest_algorithm_t} {gnutls_early_prf_hash_get} (const gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Get the hash algorithm used as a PRF to derive keys for encrypting +early data in TLS 1.3. + +@strong{Returns:} the hash algorithm used for early data, a +@code{gnutls_digest_algorithm_t} value. + +@strong{Since:} 3.7.2 +@end deftypefun + +@subheading gnutls_ecc_curve_get +@anchor{gnutls_ecc_curve_get} +@deftypefun {gnutls_ecc_curve_t} {gnutls_ecc_curve_get} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Returns the currently used elliptic curve for key exchange. Only valid +when using an elliptic curve ciphersuite. + +@strong{Returns:} the currently used curve, a @code{gnutls_ecc_curve_t} +type. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_ecc_curve_get_id +@anchor{gnutls_ecc_curve_get_id} +@deftypefun {gnutls_ecc_curve_t} {gnutls_ecc_curve_get_id} (const char * @var{name}) +@var{name}: is a curve name + +The names are compared in a case insensitive way. + +@strong{Returns:} return a @code{gnutls_ecc_curve_t} value corresponding to +the specified curve, or @code{GNUTLS_ECC_CURVE_INVALID} on error. + +@strong{Since:} 3.4.3 +@end deftypefun + +@subheading gnutls_ecc_curve_get_name +@anchor{gnutls_ecc_curve_get_name} +@deftypefun {const char *} {gnutls_ecc_curve_get_name} (gnutls_ecc_curve_t @var{curve}) +@var{curve}: is an ECC curve + +Convert a @code{gnutls_ecc_curve_t} value to a string. + +@strong{Returns:} a string that contains the name of the specified +curve or @code{NULL} . + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_ecc_curve_get_oid +@anchor{gnutls_ecc_curve_get_oid} +@deftypefun {const char *} {gnutls_ecc_curve_get_oid} (gnutls_ecc_curve_t @var{curve}) +@var{curve}: is an ECC curve + +Convert a @code{gnutls_ecc_curve_t} value to its object identifier. + +@strong{Returns:} a string that contains the OID of the specified +curve or @code{NULL} . + +@strong{Since:} 3.4.3 +@end deftypefun + +@subheading gnutls_ecc_curve_get_pk +@anchor{gnutls_ecc_curve_get_pk} +@deftypefun {gnutls_pk_algorithm_t} {gnutls_ecc_curve_get_pk} (gnutls_ecc_curve_t @var{curve}) +@var{curve}: is an ECC curve + + +@strong{Returns:} the public key algorithm associated with the named curve or @code{GNUTLS_PK_UNKNOWN} . + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_ecc_curve_get_size +@anchor{gnutls_ecc_curve_get_size} +@deftypefun {int} {gnutls_ecc_curve_get_size} (gnutls_ecc_curve_t @var{curve}) +@var{curve}: is an ECC curve + + +@strong{Returns:} the size in bytes of the curve or 0 on failure. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_ecc_curve_list +@anchor{gnutls_ecc_curve_list} +@deftypefun {const gnutls_ecc_curve_t *} {gnutls_ecc_curve_list} ( @var{void}) + +Get the list of supported elliptic curves. + +This function is not thread safe. + +@strong{Returns:} Return a (0)-terminated list of @code{gnutls_ecc_curve_t} +integers indicating the available curves. +@end deftypefun + +@subheading gnutls_ecc_curve_set_enabled +@anchor{gnutls_ecc_curve_set_enabled} +@deftypefun {int} {gnutls_ecc_curve_set_enabled} (gnutls_ecc_curve_t @var{curve}, unsigned int @var{enabled}) +@var{curve}: is an ECC curve + +@var{enabled}: whether to enable the curve + +Modify the previous system wide setting that marked @code{curve} as +enabled or disabled. Calling this fuction is allowed +only if allowlisting mode is set in the configuration file, +and only if the system-wide TLS priority string +has not been initialized yet. +The intended usage is to provide applications with a way +to expressly deviate from the distribution or site defaults +inherited from the configuration file. +The modification is composable with further modifications +performed through the priority string mechanism. + +This function is not thread-safe and is intended to be called +in the main thread at the beginning of the process execution. + +@strong{Returns:} 0 on success or negative error code otherwise. + +@strong{Since:} 3.7.3 +@end deftypefun + +@subheading gnutls_error_is_fatal +@anchor{gnutls_error_is_fatal} +@deftypefun {int} {gnutls_error_is_fatal} (int @var{error}) +@var{error}: is a GnuTLS error code, a negative error code + +If a GnuTLS function returns a negative error code you may feed that +value to this function to see if the error condition is fatal to +a TLS session (i.e., must be terminated). + +Note that you may also want to check the error code manually, since some +non-fatal errors to the protocol (such as a warning alert or +a rehandshake request) may be fatal for your program. + +This function is only useful if you are dealing with errors from +functions that relate to a TLS session (e.g., record layer or handshake +layer handling functions). + +@strong{Returns:} Non-zero value on fatal errors or zero on non-fatal. +@end deftypefun + +@subheading gnutls_error_to_alert +@anchor{gnutls_error_to_alert} +@deftypefun {int} {gnutls_error_to_alert} (int @var{err}, int * @var{level}) +@var{err}: is a negative integer + +@var{level}: the alert level will be stored there + +Get an alert depending on the error code returned by a gnutls +function. All alerts sent by this function should be considered +fatal. The only exception is when @code{err} is @code{GNUTLS_E_REHANDSHAKE} , +where a warning alert should be sent to the peer indicating that no +renegotiation will be performed. + +If there is no mapping to a valid alert the alert to indicate +internal error (@code{GNUTLS_A_INTERNAL_ERROR} ) is returned. + +@strong{Returns:} the alert code to use for a particular error code. +@end deftypefun + +@subheading gnutls_est_record_overhead_size +@anchor{gnutls_est_record_overhead_size} +@deftypefun {size_t} {gnutls_est_record_overhead_size} (gnutls_protocol_t @var{version}, gnutls_cipher_algorithm_t @var{cipher}, gnutls_mac_algorithm_t @var{mac}, gnutls_compression_method_t @var{comp}, unsigned int @var{flags}) +@var{version}: is a @code{gnutls_protocol_t} value + +@var{cipher}: is a @code{gnutls_cipher_algorithm_t} value + +@var{mac}: is a @code{gnutls_mac_algorithm_t} value + +@var{comp}: is a @code{gnutls_compression_method_t} value (ignored) + +@var{flags}: must be zero + +This function will return the set size in bytes of the overhead +due to TLS (or DTLS) per record. + +Note that this function may provide inaccurate values when TLS +extensions that modify the record format are negotiated. In these +cases a more accurate value can be obtained using @code{gnutls_record_overhead_size()} +after a completed handshake. + +@strong{Since:} 3.2.2 +@end deftypefun + +@subheading gnutls_ext_get_current_msg +@anchor{gnutls_ext_get_current_msg} +@deftypefun {unsigned} {gnutls_ext_get_current_msg} (gnutls_session_t @var{session}) +@var{session}: a @code{gnutls_session_t} opaque pointer + +This function allows an extension handler to obtain the message +this extension is being called from. The returned value is a single +entry of the @code{gnutls_ext_flags_t} enumeration. That is, if an +extension was registered with the @code{GNUTLS_EXT_FLAG_HRR} and +@code{GNUTLS_EXT_FLAG_EE} flags, the value when called during parsing of the +encrypted extensions message will be @code{GNUTLS_EXT_FLAG_EE} . + +If not called under an extension handler, its value is undefined. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_ext_get_data +@anchor{gnutls_ext_get_data} +@deftypefun {int} {gnutls_ext_get_data} (gnutls_session_t @var{session}, unsigned @var{tls_id}, gnutls_ext_priv_data_t * @var{data}) +@var{session}: a @code{gnutls_session_t} opaque pointer + +@var{tls_id}: the numeric id of the extension + +@var{data}: a pointer to the private data to retrieve + +This function retrieves any data previously stored with @code{gnutls_ext_set_data()} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_ext_get_name +@anchor{gnutls_ext_get_name} +@deftypefun {const char *} {gnutls_ext_get_name} (unsigned int @var{ext}) +@var{ext}: is a TLS extension numeric ID + +Convert a TLS extension numeric ID to a printable string. + +@strong{Returns:} a pointer to a string that contains the name of the +specified cipher, or @code{NULL} . +@end deftypefun + +@subheading gnutls_ext_get_name2 +@anchor{gnutls_ext_get_name2} +@deftypefun {const char *} {gnutls_ext_get_name2} (gnutls_session_t @var{session}, unsigned int @var{tls_id}, gnutls_ext_parse_type_t @var{parse_point}) +@var{session}: a @code{gnutls_session_t} opaque pointer + +@var{tls_id}: is a TLS extension numeric ID + +@var{parse_point}: the parse type of the extension + +Convert a TLS extension numeric ID to a printable string. + +@strong{Returns:} a pointer to a string that contains the name of the +specified cipher, or @code{NULL} . +@end deftypefun + +@subheading gnutls_ext_raw_parse +@anchor{gnutls_ext_raw_parse} +@deftypefun {int} {gnutls_ext_raw_parse} (void * @var{ctx}, gnutls_ext_raw_process_func @var{cb}, const gnutls_datum_t * @var{data}, unsigned int @var{flags}) +@var{ctx}: a pointer to pass to callback function + +@var{cb}: callback function to process each extension found + +@var{data}: TLS extension data + +@var{flags}: should be zero or @code{GNUTLS_EXT_RAW_FLAG_TLS_CLIENT_HELLO} or @code{GNUTLS_EXT_RAW_FLAG_DTLS_CLIENT_HELLO} + +This function iterates through the TLS extensions as passed in + @code{data} , passing the individual extension data to callback. The + @code{data} must conform to Extension extensions<0..2^16-1> format. + +If flags is @code{GNUTLS_EXT_RAW_TLS_FLAG_CLIENT_HELLO} then this function +will parse the extension data from the position, as if the packet in + @code{data} is a client hello (without record or handshake headers) - +as provided by @code{gnutls_handshake_set_hook_function()} . + +The return value of the callback will be propagated. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. On unknown +flags it returns @code{GNUTLS_E_INVALID_REQUEST} . + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_ext_register +@anchor{gnutls_ext_register} +@deftypefun {int} {gnutls_ext_register} (const char * @var{name}, int @var{id}, gnutls_ext_parse_type_t @var{parse_point}, gnutls_ext_recv_func @var{recv_func}, gnutls_ext_send_func @var{send_func}, gnutls_ext_deinit_data_func @var{deinit_func}, gnutls_ext_pack_func @var{pack_func}, gnutls_ext_unpack_func @var{unpack_func}) +@var{name}: the name of the extension to register + +@var{id}: the numeric TLS id of the extension + +@var{parse_point}: the parse type of the extension (see gnutls_ext_parse_type_t) + +@var{recv_func}: a function to receive the data + +@var{send_func}: a function to send the data + +@var{deinit_func}: a function deinitialize any private data + +@var{pack_func}: a function which serializes the extension's private data (used on session packing for resumption) + +@var{unpack_func}: a function which will deserialize the extension's private data + +This function will register a new extension type. The extension will remain +registered until @code{gnutls_global_deinit()} is called. If the extension type +is already registered then @code{GNUTLS_E_ALREADY_REGISTERED} will be returned. + +Each registered extension can store temporary data into the gnutls_session_t +structure using @code{gnutls_ext_set_data()} , and they can be retrieved using +@code{gnutls_ext_get_data()} . + +Any extensions registered with this function are valid for the client +and TLS1.2 server hello (or encrypted extensions for TLS1.3). + +This function is not thread safe. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_ext_set_data +@anchor{gnutls_ext_set_data} +@deftypefun {void} {gnutls_ext_set_data} (gnutls_session_t @var{session}, unsigned @var{tls_id}, gnutls_ext_priv_data_t @var{data}) +@var{session}: a @code{gnutls_session_t} opaque pointer + +@var{tls_id}: the numeric id of the extension + +@var{data}: the private data to set + +This function allows an extension handler to store data in the current session +and retrieve them later on. The set data will be deallocated using +the gnutls_ext_deinit_data_func. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_fingerprint +@anchor{gnutls_fingerprint} +@deftypefun {int} {gnutls_fingerprint} (gnutls_digest_algorithm_t @var{algo}, const gnutls_datum_t * @var{data}, void * @var{result}, size_t * @var{result_size}) +@var{algo}: is a digest algorithm + +@var{data}: is the data + +@var{result}: is the place where the result will be copied (may be null). + +@var{result_size}: should hold the size of the result. The actual size +of the returned result will also be copied there. + +This function will calculate a fingerprint (actually a hash), of +the given data. The result is not printable data. You should +convert it to hex, or to something else printable. + +This is the usual way to calculate a fingerprint of an X.509 DER +encoded certificate. Note however that the fingerprint of an +OpenPGP certificate is not just a hash and cannot be calculated with this +function. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_fips140_context_deinit +@anchor{gnutls_fips140_context_deinit} +@deftypefun {void} {gnutls_fips140_context_deinit} (gnutls_fips140_context_t @var{context}) +@var{context}: a @code{gnutls_fips140_context_t} + +Uninitialize and release the FIPS context @code{context} . + +@strong{Since:} 3.7.3 +@end deftypefun + +@subheading gnutls_fips140_context_init +@anchor{gnutls_fips140_context_init} +@deftypefun {int} {gnutls_fips140_context_init} (gnutls_fips140_context_t * @var{context}) +@var{context}: location to store @code{gnutls_fips140_context_t} + +Create and initialize the FIPS context object. + +@strong{Returns:} 0 upon success, a negative error code otherwise + +@strong{Since:} 3.7.3 +@end deftypefun + +@subheading gnutls_fips140_get_operation_state +@anchor{gnutls_fips140_get_operation_state} +@deftypefun {gnutls_fips140_operation_state_t} {gnutls_fips140_get_operation_state} (gnutls_fips140_context_t @var{context}) +@var{context}: a @code{gnutls_fips140_context_t} + +Get the previous operation state of @code{context} in terms of FIPS. + +@strong{Returns:} a @code{gnutls_fips140_operation_state_t} + +@strong{Since:} 3.7.3 +@end deftypefun + +@subheading gnutls_fips140_mode_enabled +@anchor{gnutls_fips140_mode_enabled} +@deftypefun {unsigned} {gnutls_fips140_mode_enabled} ( @var{void}) + +Checks whether this library is in FIPS140 mode. The returned +value corresponds to the library mode as set with +@code{gnutls_fips140_set_mode()} . + +If @code{gnutls_fips140_set_mode()} was called with @code{GNUTLS_FIPS140_SET_MODE_THREAD} +then this function will return the current thread's FIPS140 mode, otherwise +the global value is returned. + +@strong{Returns:} return non-zero if true or zero if false. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_fips140_pop_context +@anchor{gnutls_fips140_pop_context} +@deftypefun {int} {gnutls_fips140_pop_context} ( @var{void}) + +Dissociate the FIPS context currently +active on the current thread, reverting to the previously active +context. If a cryptographic operation is ongoing in the current +thread, e.g., @code{gnutls_aead_cipher_init()} is called but +@code{gnutls_aead_cipher_deinit()} is not yet called, it returns an error +@code{GNUTLS_E_INVALID_REQUEST} . + +This function is no-op if FIPS140 is not compiled in nor enabled +at run-time. + +@strong{Returns:} 0 upon success, a negative error code otherwise + +@strong{Since:} 3.7.3 +@end deftypefun + +@subheading gnutls_fips140_push_context +@anchor{gnutls_fips140_push_context} +@deftypefun {int} {gnutls_fips140_push_context} (gnutls_fips140_context_t @var{context}) +@var{context}: a @code{gnutls_fips140_context_t} + +Associate the FIPS @code{context} to the current thread, diverting the +currently active context. If a cryptographic operation is ongoing +in the current thread, e.g., @code{gnutls_aead_cipher_init()} is called +but @code{gnutls_aead_cipher_deinit()} is not yet called, it returns an +error @code{GNUTLS_E_INVALID_REQUEST} . + +The operation state of @code{context} will be reset to +@code{GNUTLS_FIPS140_OP_INITIAL} . + +This function is no-op if FIPS140 is not compiled in nor enabled +at run-time. + +@strong{Returns:} 0 upon success, a negative error code otherwise + +@strong{Since:} 3.7.3 +@end deftypefun + +@subheading gnutls_fips140_run_self_tests +@anchor{gnutls_fips140_run_self_tests} +@deftypefun {int} {gnutls_fips140_run_self_tests} ( @var{void}) + +Manually perform the second round of the FIPS140 self-tests, +including: + +- Known answer tests (KAT) for the selected set of symmetric +cipher, MAC, public key, KDF, and DRBG +- Library integrity checks + +Upon failure with FIPS140 mode enabled, it makes the library +unusable. This function is not thread-safe. + +@strong{Returns:} 0 upon success, a negative error code otherwise + +@strong{Since:} 3.7.7 +@end deftypefun + +@subheading gnutls_fips140_set_mode +@anchor{gnutls_fips140_set_mode} +@deftypefun {void} {gnutls_fips140_set_mode} (gnutls_fips_mode_t @var{mode}, unsigned @var{flags}) +@var{mode}: the FIPS140-2 mode to switch to + +@var{flags}: should be zero or @code{GNUTLS_FIPS140_SET_MODE_THREAD} + +That function is not thread-safe when changing the mode with no flags +(globally), and should be called prior to creating any threads. Its +behavior with no flags after threads are created is undefined. + +When the flag @code{GNUTLS_FIPS140_SET_MODE_THREAD} is specified +then this call will change the FIPS140-2 mode for this particular +thread and not for the whole process. That way an application +can utilize this function to set and reset mode for specific +operations. + +This function never fails but will be a no-op if used when +the library is not in FIPS140-2 mode. When asked to switch to unknown +values for @code{mode} or to @code{GNUTLS_FIPS140_SELFTESTS} mode, the library +switches to @code{GNUTLS_FIPS140_STRICT} mode. + +@strong{Since:} 3.6.2 +@end deftypefun + +@subheading gnutls_get_library_config +@anchor{gnutls_get_library_config} +@deftypefun {const gnutls_library_config_st *} {gnutls_get_library_config} ( @var{void}) + +Returns the library configuration as key value pairs. +Currently defined keys are: + +- fips-module-name: the name of the FIPS140 module + +- fips-module-version: the version of the FIPS140 module + +- libgnutls-soname: the SONAME of the library itself + +- libnettle-soname: the library SONAME of linked libnettle + +- libhogweed-soname: the library SONAME of linked libhogweed + +- libgmp-soname: the library SONAME of linked libgmp + +- hardware-features: enabled hardware support features + +- tls-features: enabled TLS protocol features + +@strong{Returns:} a NUL-terminated @code{gnutls_library_config_st} array + +@strong{Since:} 3.7.3 +@end deftypefun + +@subheading gnutls_get_system_config_file +@anchor{gnutls_get_system_config_file} +@deftypefun {const char *} {gnutls_get_system_config_file} ( @var{void}) + +Returns the filename of the system wide configuration +file to be loaded by the library. + +@strong{Returns:} a constant pointer to the config file path + +@strong{Since:} 3.6.9 +@end deftypefun + +@subheading gnutls_global_deinit +@anchor{gnutls_global_deinit} +@deftypefun {void} {gnutls_global_deinit} ( @var{void}) + +This function deinitializes the global data, that were initialized +using @code{gnutls_global_init()} . + +Since GnuTLS 3.3.0 this function is no longer necessary to be explicitly +called. GnuTLS will automatically deinitialize on library destructor. See +@code{gnutls_global_init()} for disabling the implicit initialization/deinitialization. +@end deftypefun + +@subheading gnutls_global_init +@anchor{gnutls_global_init} +@deftypefun {int} {gnutls_global_init} ( @var{void}) + +Since GnuTLS 3.3.0 this function is no longer necessary to be explicitly +called. To disable the implicit call (in a library constructor) of this +function set the environment variable @code{GNUTLS_NO_IMPLICIT_INIT} to 1. + +This function performs any required precalculations, detects +the supported CPU capabilities and initializes the underlying +cryptographic backend. In order to free any resources +taken by this call you should @code{gnutls_global_deinit()} +when gnutls usage is no longer needed. + +This function increments a global counter, so that +@code{gnutls_global_deinit()} only releases resources when it has been +called as many times as @code{gnutls_global_init()} . This is useful when +GnuTLS is used by more than one library in an application. This +function can be called many times, but will only do something the +first time. It is thread safe since GnuTLS 3.3.0. + +A subsequent call of this function if the initial has failed will +return the same error code. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_global_set_audit_log_function +@anchor{gnutls_global_set_audit_log_function} +@deftypefun {void} {gnutls_global_set_audit_log_function} (gnutls_audit_log_func @var{log_func}) +@var{log_func}: it is the audit log function + +This is the function to set the audit logging function. This +is a function to report important issues, such as possible +attacks in the protocol. This is different from @code{gnutls_global_set_log_function()} +because it will report also session-specific events. The session +parameter will be null if there is no corresponding TLS session. + + @code{gnutls_audit_log_func} is of the form, +void (*gnutls_audit_log_func)( gnutls_session_t, const char*); + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_global_set_log_function +@anchor{gnutls_global_set_log_function} +@deftypefun {void} {gnutls_global_set_log_function} (gnutls_log_func @var{log_func}) +@var{log_func}: it's a log function + +This is the function where you set the logging function gnutls is +going to use. This function only accepts a character array. +Normally you may not use this function since it is only used for +debugging purposes. + + @code{gnutls_log_func} is of the form, +void (*gnutls_log_func)( int level, const char*); +@end deftypefun + +@subheading gnutls_global_set_log_level +@anchor{gnutls_global_set_log_level} +@deftypefun {void} {gnutls_global_set_log_level} (int @var{level}) +@var{level}: it's an integer from 0 to 99. + +This is the function that allows you to set the log level. The +level is an integer between 0 and 9. Higher values mean more +verbosity. The default value is 0. Larger values should only be +used with care, since they may reveal sensitive information. + +Use a log level over 10 to enable all debugging options. +@end deftypefun + +@subheading gnutls_global_set_mutex +@anchor{gnutls_global_set_mutex} +@deftypefun {void} {gnutls_global_set_mutex} (mutex_init_func @var{init}, mutex_deinit_func @var{deinit}, mutex_lock_func @var{lock}, mutex_unlock_func @var{unlock}) +@var{init}: mutex initialization function + +@var{deinit}: mutex deinitialization function + +@var{lock}: mutex locking function + +@var{unlock}: mutex unlocking function + +With this function you are allowed to override the default mutex +locks used in some parts of gnutls and dependent libraries. This function +should be used if you have complete control of your program and libraries. +Do not call this function from a library, or preferably from any application +unless really needed to. GnuTLS will use the appropriate locks for the running +system. + +This function must be called prior to any other GnuTLS function; otherwise +the behavior is undefined. + +@strong{Deprecated:} This function is discouraged on GnuTLS 3.7.3 or later. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_global_set_time_function +@anchor{gnutls_global_set_time_function} +@deftypefun {void} {gnutls_global_set_time_function} (gnutls_time_func @var{time_func}) +@var{time_func}: it's the system time function, a @code{gnutls_time_func()} callback. + +This is the function where you can override the default system time +function. The application provided function should behave the same +as the standard function. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_gost_paramset_get_name +@anchor{gnutls_gost_paramset_get_name} +@deftypefun {const char *} {gnutls_gost_paramset_get_name} (gnutls_gost_paramset_t @var{param}) +@var{param}: is a GOST 28147 param set + +Convert a @code{gnutls_gost_paramset_t} value to a string. + +@strong{Returns:} a string that contains the name of the specified GOST param set, +or @code{NULL} . + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_gost_paramset_get_oid +@anchor{gnutls_gost_paramset_get_oid} +@deftypefun {const char *} {gnutls_gost_paramset_get_oid} (gnutls_gost_paramset_t @var{param}) +@var{param}: is a GOST 28147 param set + +Convert a @code{gnutls_gost_paramset_t} value to its object identifier. + +@strong{Returns:} a string that contains the object identifier of the specified GOST +param set, or @code{NULL} . + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_group_get +@anchor{gnutls_group_get} +@deftypefun {gnutls_group_t} {gnutls_group_get} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Returns the currently used group for key exchange. Only valid +when using an elliptic curve or DH ciphersuite. + +@strong{Returns:} the currently used group, a @code{gnutls_group_t} +type. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_group_get_id +@anchor{gnutls_group_get_id} +@deftypefun {gnutls_group_t} {gnutls_group_get_id} (const char * @var{name}) +@var{name}: is a group name + +The names are compared in a case insensitive way. + +@strong{Returns:} return a @code{gnutls_group_t} value corresponding to +the specified group, or @code{GNUTLS_GROUP_INVALID} on error. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_group_get_name +@anchor{gnutls_group_get_name} +@deftypefun {const char *} {gnutls_group_get_name} (gnutls_group_t @var{group}) +@var{group}: is an element from @code{gnutls_group_t} + +Convert a @code{gnutls_group_t} value to a string. + +@strong{Returns:} a string that contains the name of the specified +group or @code{NULL} . + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_group_list +@anchor{gnutls_group_list} +@deftypefun {const gnutls_group_t *} {gnutls_group_list} ( @var{void}) + +Get the list of supported elliptic curves. + +This function is not thread safe. + +@strong{Returns:} Return a (0)-terminated list of @code{gnutls_group_t} +integers indicating the available groups. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_handshake +@anchor{gnutls_handshake} +@deftypefun {int} {gnutls_handshake} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function performs the handshake of the TLS/SSL protocol, and +initializes the TLS session parameters. + +The non-fatal errors expected by this function are: +@code{GNUTLS_E_INTERRUPTED} , @code{GNUTLS_E_AGAIN} , +@code{GNUTLS_E_WARNING_ALERT_RECEIVED} . When this function is called +for re-handshake under TLS 1.2 or earlier, the non-fatal error code +@code{GNUTLS_E_GOT_APPLICATION_DATA} may also be returned. + +The former two interrupt the handshake procedure due to the transport +layer being interrupted, and the latter because of a "warning" alert that +was sent by the peer (it is always a good idea to check any +received alerts). On these non-fatal errors call this function again, +until it returns 0; cf. @code{gnutls_record_get_direction()} and +@code{gnutls_error_is_fatal()} . In DTLS sessions the non-fatal error +@code{GNUTLS_E_LARGE_PACKET} is also possible, and indicates that +the MTU should be adjusted. + +When this function is called by a server after a rehandshake request +under TLS 1.2 or earlier the @code{GNUTLS_E_GOT_APPLICATION_DATA} error code indicates +that some data were pending prior to peer initiating the handshake. +Under TLS 1.3 this function when called after a successful handshake, is a no-op +and always succeeds in server side; in client side this function is +equivalent to @code{gnutls_session_key_update()} with @code{GNUTLS_KU_PEER} flag. + +This function handles both full and abbreviated TLS handshakes (resumption). +For abbreviated handshakes, in client side, the @code{gnutls_session_set_data()} +should be called prior to this function to set parameters from a previous session. +In server side, resumption is handled by either setting a DB back-end, or setting +up keys for session tickets. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on a successful handshake, otherwise a negative error code. +@end deftypefun + +@subheading gnutls_handshake_description_get_name +@anchor{gnutls_handshake_description_get_name} +@deftypefun {const char *} {gnutls_handshake_description_get_name} (gnutls_handshake_description_t @var{type}) +@var{type}: is a handshake message description + +Convert a @code{gnutls_handshake_description_t} value to a string. + +@strong{Returns:} a string that contains the name of the specified handshake +message or @code{NULL} . +@end deftypefun + +@subheading gnutls_handshake_get_last_in +@anchor{gnutls_handshake_get_last_in} +@deftypefun {gnutls_handshake_description_t} {gnutls_handshake_get_last_in} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function is only useful to check where the last performed +handshake failed. If the previous handshake succeed or was not +performed at all then no meaningful value will be returned. + +Check @code{gnutls_handshake_description_t} in gnutls.h for the +available handshake descriptions. + +@strong{Returns:} the last handshake message type received, a +@code{gnutls_handshake_description_t} . +@end deftypefun + +@subheading gnutls_handshake_get_last_out +@anchor{gnutls_handshake_get_last_out} +@deftypefun {gnutls_handshake_description_t} {gnutls_handshake_get_last_out} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function is only useful to check where the last performed +handshake failed. If the previous handshake succeed or was not +performed at all then no meaningful value will be returned. + +Check @code{gnutls_handshake_description_t} in gnutls.h for the +available handshake descriptions. + +@strong{Returns:} the last handshake message type sent, a +@code{gnutls_handshake_description_t} . +@end deftypefun + +@subheading gnutls_handshake_set_hook_function +@anchor{gnutls_handshake_set_hook_function} +@deftypefun {void} {gnutls_handshake_set_hook_function} (gnutls_session_t @var{session}, unsigned int @var{htype}, int @var{when}, gnutls_handshake_hook_func @var{func}) +@var{session}: is a @code{gnutls_session_t} type + +@var{htype}: the @code{gnutls_handshake_description_t} of the message to hook at + +@var{when}: @code{GNUTLS_HOOK_} * depending on when the hook function should be called + +@var{func}: is the function to be called + +This function will set a callback to be called after or before the specified +handshake message has been received or generated. This is a +generalization of @code{gnutls_handshake_set_post_client_hello_function()} . + +To call the hook function prior to the message being generated or processed +use @code{GNUTLS_HOOK_PRE} as @code{when} parameter, @code{GNUTLS_HOOK_POST} to call +after, and @code{GNUTLS_HOOK_BOTH} for both cases. + +This callback must return 0 on success or a gnutls error code to +terminate the handshake. + +To hook at all handshake messages use an @code{htype} of @code{GNUTLS_HANDSHAKE_ANY} . + +@strong{Warning:} You should not use this function to terminate the +handshake based on client input unless you know what you are +doing. Before the handshake is finished there is no way to know if +there is a man-in-the-middle attack being performed. +@end deftypefun + +@subheading gnutls_handshake_set_max_packet_length +@anchor{gnutls_handshake_set_max_packet_length} +@deftypefun {void} {gnutls_handshake_set_max_packet_length} (gnutls_session_t @var{session}, size_t @var{max}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{max}: is the maximum number. + +This function will set the maximum size of all handshake messages. +Handshakes over this size are rejected with +@code{GNUTLS_E_HANDSHAKE_TOO_LARGE} error code. The default value is +128kb which is typically large enough. Set this to 0 if you do not +want to set an upper limit. + +The reason for restricting the handshake message sizes are to +limit Denial of Service attacks. + +Note that the maximum handshake size was increased to 128kb +from 48kb in GnuTLS 3.5.5. +@end deftypefun + +@subheading gnutls_handshake_set_post_client_hello_function +@anchor{gnutls_handshake_set_post_client_hello_function} +@deftypefun {void} {gnutls_handshake_set_post_client_hello_function} (gnutls_session_t @var{session}, gnutls_handshake_simple_hook_func @var{func}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{func}: is the function to be called + +This function will set a callback to be called after the client +hello has been received (callback valid in server side only). This +allows the server to adjust settings based on received extensions. + +Those settings could be ciphersuites, requesting certificate, or +anything else except for version negotiation (this is done before +the hello message is parsed). + +This callback must return 0 on success or a gnutls error code to +terminate the handshake. + +Since GnuTLS 3.3.5 the callback is +allowed to return @code{GNUTLS_E_AGAIN} or @code{GNUTLS_E_INTERRUPTED} to +put the handshake on hold. In that case @code{gnutls_handshake()} +will return @code{GNUTLS_E_INTERRUPTED} and can be resumed when needed. + +@strong{Warning:} You should not use this function to terminate the +handshake based on client input unless you know what you are +doing. Before the handshake is finished there is no way to know if +there is a man-in-the-middle attack being performed. +@end deftypefun + +@subheading gnutls_handshake_set_private_extensions +@anchor{gnutls_handshake_set_private_extensions} +@deftypefun {void} {gnutls_handshake_set_private_extensions} (gnutls_session_t @var{session}, int @var{allow}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{allow}: is an integer (0 or 1) + +This function will enable or disable the use of private cipher +suites (the ones that start with 0xFF). By default or if @code{allow} is 0 then these cipher suites will not be advertised nor used. + +Currently GnuTLS does not include such cipher-suites or +compression algorithms. + +Enabling the private ciphersuites when talking to other than +gnutls servers and clients may cause interoperability problems. +@end deftypefun + +@subheading gnutls_handshake_set_random +@anchor{gnutls_handshake_set_random} +@deftypefun {int} {gnutls_handshake_set_random} (gnutls_session_t @var{session}, const gnutls_datum_t * @var{random}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{random}: a random value of 32-bytes + +This function will explicitly set the server or client hello +random value in the subsequent TLS handshake. The random value +should be a 32-byte value. + +Note that this function should not normally be used as gnutls +will select automatically a random value for the handshake. + +This function should not be used when resuming a session. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. + +Since 3.1.9 +@end deftypefun + +@subheading gnutls_handshake_set_read_function +@anchor{gnutls_handshake_set_read_function} +@deftypefun {void} {gnutls_handshake_set_read_function} (gnutls_session_t @var{session}, gnutls_handshake_read_func @var{func}) +@var{session}: is @code{gnutls_session_t} type + +@var{func}: is the function to be called + +This function will set a callback to be called when a handshake +message is being sent. + +@strong{Since:} 3.7.0 +@end deftypefun + +@subheading gnutls_handshake_set_secret_function +@anchor{gnutls_handshake_set_secret_function} +@deftypefun {void} {gnutls_handshake_set_secret_function} (gnutls_session_t @var{session}, gnutls_handshake_secret_func @var{func}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{func}: the secret func + +This function will set a callback to be called when a new traffic +secret is installed. + +@strong{Since:} 3.7.0 +@end deftypefun + +@subheading gnutls_handshake_set_timeout +@anchor{gnutls_handshake_set_timeout} +@deftypefun {void} {gnutls_handshake_set_timeout} (gnutls_session_t @var{session}, unsigned int @var{ms}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{ms}: is a timeout value in milliseconds + +This function sets the timeout for the TLS handshake process +to the provided value. Use an @code{ms} value of zero to disable +timeout, or @code{GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT} for a reasonable +default value. For the DTLS protocol, the more detailed +@code{gnutls_dtls_set_timeouts()} is provided. + +This function requires to set a pull timeout callback. See +@code{gnutls_transport_set_pull_timeout_function()} . + +@strong{Since:} 3.1.0 +@end deftypefun + +@subheading gnutls_handshake_write +@anchor{gnutls_handshake_write} +@deftypefun {int} {gnutls_handshake_write} (gnutls_session_t @var{session}, gnutls_record_encryption_level_t @var{level}, const void * @var{data}, size_t @var{data_size}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{level}: the current encryption level for reading a handshake message + +@var{data}: the (const) handshake data to be processed + +@var{data_size}: the size of data + +This function processes a handshake message in the encryption level +specified with @code{level} . Prior to calling this function, a handshake +read callback must be set on @code{session} . Use +@code{gnutls_handshake_set_read_function()} to do this. + +@strong{Since:} 3.7.0 +@end deftypefun + +@subheading gnutls_heartbeat_allowed +@anchor{gnutls_heartbeat_allowed} +@deftypefun {unsigned} {gnutls_heartbeat_allowed} (gnutls_session_t @var{session}, unsigned int @var{type}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{type}: one of @code{GNUTLS_HB_LOCAL_ALLOWED_TO_SEND} and @code{GNUTLS_HB_PEER_ALLOWED_TO_SEND} + +This function will check whether heartbeats are allowed +to be sent or received in this session. + +@strong{Returns:} Non zero if heartbeats are allowed. + +@strong{Since:} 3.1.2 +@end deftypefun + +@subheading gnutls_heartbeat_enable +@anchor{gnutls_heartbeat_enable} +@deftypefun {void} {gnutls_heartbeat_enable} (gnutls_session_t @var{session}, unsigned int @var{type}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{type}: one of the GNUTLS_HB_* flags + +If this function is called with the @code{GNUTLS_HB_PEER_ALLOWED_TO_SEND} + @code{type} , GnuTLS will allow heartbeat messages to be received. Moreover it also +request the peer to accept heartbeat messages. This function +must be called prior to TLS handshake. + +If the @code{type} used is @code{GNUTLS_HB_LOCAL_ALLOWED_TO_SEND} , then the peer +will be asked to accept heartbeat messages but not send ones. + +The function @code{gnutls_heartbeat_allowed()} can be used to test Whether +locally generated heartbeat messages can be accepted by the peer. + +@strong{Since:} 3.1.2 +@end deftypefun + +@subheading gnutls_heartbeat_get_timeout +@anchor{gnutls_heartbeat_get_timeout} +@deftypefun {unsigned int} {gnutls_heartbeat_get_timeout} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function will return the milliseconds remaining +for a retransmission of the previously sent ping +message. This function is useful when ping is used in +non-blocking mode, to estimate when to call @code{gnutls_heartbeat_ping()} +if no packets have been received. + +@strong{Returns:} the remaining time in milliseconds. + +@strong{Since:} 3.1.2 +@end deftypefun + +@subheading gnutls_heartbeat_ping +@anchor{gnutls_heartbeat_ping} +@deftypefun {int} {gnutls_heartbeat_ping} (gnutls_session_t @var{session}, size_t @var{data_size}, unsigned int @var{max_tries}, unsigned int @var{flags}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{data_size}: is the length of the ping payload. + +@var{max_tries}: if flags is @code{GNUTLS_HEARTBEAT_WAIT} then this sets the number of retransmissions. Use zero for indefinite (until timeout). + +@var{flags}: if @code{GNUTLS_HEARTBEAT_WAIT} then wait for pong or timeout instead of returning immediately. + +This function sends a ping to the peer. If the @code{flags} is set +to @code{GNUTLS_HEARTBEAT_WAIT} then it waits for a reply from the peer. + +Note that it is highly recommended to use this function with the +flag @code{GNUTLS_HEARTBEAT_WAIT} , or you need to handle retransmissions +and timeouts manually. + +The total TLS data transmitted as part of the ping message are given by +the following formula: MAX(16, @code{data_size} )+@code{gnutls_record_overhead_size()} +3. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +@strong{Since:} 3.1.2 +@end deftypefun + +@subheading gnutls_heartbeat_pong +@anchor{gnutls_heartbeat_pong} +@deftypefun {int} {gnutls_heartbeat_pong} (gnutls_session_t @var{session}, unsigned int @var{flags}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{flags}: should be zero + +This function replies to a ping by sending a pong to the peer. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +@strong{Since:} 3.1.2 +@end deftypefun + +@subheading gnutls_heartbeat_set_timeouts +@anchor{gnutls_heartbeat_set_timeouts} +@deftypefun {void} {gnutls_heartbeat_set_timeouts} (gnutls_session_t @var{session}, unsigned int @var{retrans_timeout}, unsigned int @var{total_timeout}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{retrans_timeout}: The time at which a retransmission will occur in milliseconds + +@var{total_timeout}: The time at which the connection will be aborted, in milliseconds. + +This function will override the timeouts for the DTLS heartbeat +protocol. The retransmission timeout is the time after which a +message from the peer is not received, the previous request will +be retransmitted. The total timeout is the time after which the +handshake will be aborted with @code{GNUTLS_E_TIMEDOUT} . + +@strong{Since:} 3.1.2 +@end deftypefun + +@subheading gnutls_hex2bin +@anchor{gnutls_hex2bin} +@deftypefun {int} {gnutls_hex2bin} (const char * @var{hex_data}, size_t @var{hex_size}, void * @var{bin_data}, size_t * @var{bin_size}) +@var{hex_data}: string with data in hex format + +@var{hex_size}: size of hex data + +@var{bin_data}: output array with binary data + +@var{bin_size}: when calling should hold maximum size of @code{bin_data} , +on return will hold actual length of @code{bin_data} . + +Convert a buffer with hex data to binary data. This function +unlike @code{gnutls_hex_decode()} can parse hex data with separators +between numbers. That is, it ignores any non-hex characters. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +@strong{Since:} 2.4.0 +@end deftypefun + +@subheading gnutls_hex_decode +@anchor{gnutls_hex_decode} +@deftypefun {int} {gnutls_hex_decode} (const gnutls_datum_t * @var{hex_data}, void * @var{result}, size_t * @var{result_size}) +@var{hex_data}: contain the encoded data + +@var{result}: the place where decoded data will be copied + +@var{result_size}: holds the size of the result + +This function will decode the given encoded data, using the hex +encoding used by PSK password files. + +Initially @code{result_size} must hold the maximum size available in + @code{result} , and on return it will contain the number of bytes written. + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the buffer given is not +long enough, @code{GNUTLS_E_PARSING_ERROR} on invalid hex data, or 0 on success. +@end deftypefun + +@subheading gnutls_hex_decode2 +@anchor{gnutls_hex_decode2} +@deftypefun {int} {gnutls_hex_decode2} (const gnutls_datum_t * @var{hex_data}, gnutls_datum_t * @var{result}) +@var{hex_data}: contain the encoded data + +@var{result}: the result in an allocated string + +This function will decode the given encoded data, using the hex +encoding used by PSK password files. + +@strong{Returns:} @code{GNUTLS_E_PARSING_ERROR} on invalid hex data, or 0 on success. +@end deftypefun + +@subheading gnutls_hex_encode +@anchor{gnutls_hex_encode} +@deftypefun {int} {gnutls_hex_encode} (const gnutls_datum_t * @var{data}, char * @var{result}, size_t * @var{result_size}) +@var{data}: contain the raw data + +@var{result}: the place where hex data will be copied + +@var{result_size}: holds the size of the result + +This function will convert the given data to printable data, using +the hex encoding, as used in the PSK password files. + +Note that the size of the result includes the null terminator. + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the buffer given is not +long enough, or 0 on success. +@end deftypefun + +@subheading gnutls_hex_encode2 +@anchor{gnutls_hex_encode2} +@deftypefun {int} {gnutls_hex_encode2} (const gnutls_datum_t * @var{data}, gnutls_datum_t * @var{result}) +@var{data}: contain the raw data + +@var{result}: the result in an allocated string + +This function will convert the given data to printable data, using +the hex encoding, as used in the PSK password files. + +Note that the size of the result does NOT include the null terminator. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. +@end deftypefun + +@subheading gnutls_idna_map +@anchor{gnutls_idna_map} +@deftypefun {int} {gnutls_idna_map} (const char * @var{input}, unsigned @var{ilen}, gnutls_datum_t * @var{out}, unsigned @var{flags}) +@var{input}: contain the UTF-8 formatted domain name + +@var{ilen}: the length of the provided string + +@var{out}: the result in an null-terminated allocated string + +@var{flags}: should be zero + +This function will convert the provided UTF-8 domain name, to +its IDNA mapping in an allocated variable. Note that depending on the flags the used gnutls +library was compiled with, the output of this function may vary (i.e., +may be IDNA2008, or IDNA2003). + +To force IDNA2008 specify the flag @code{GNUTLS_IDNA_FORCE_2008} . In +the case GnuTLS is not compiled with the necessary dependencies, +@code{GNUTLS_E_UNIMPLEMENTED_FEATURE} will be returned to indicate that +gnutls is unable to perform the requested conversion. + +Note also, that this function will return an empty string if an +empty string is provided as input. + +@strong{Returns:} @code{GNUTLS_E_INVALID_UTF8_STRING} on invalid UTF-8 data, or 0 on success. + +@strong{Since:} 3.5.8 +@end deftypefun + +@subheading gnutls_idna_reverse_map +@anchor{gnutls_idna_reverse_map} +@deftypefun {int} {gnutls_idna_reverse_map} (const char * @var{input}, unsigned @var{ilen}, gnutls_datum_t * @var{out}, unsigned @var{flags}) +@var{input}: contain the ACE (IDNA) formatted domain name + +@var{ilen}: the length of the provided string + +@var{out}: the result in an null-terminated allocated UTF-8 string + +@var{flags}: should be zero + +This function will convert an ACE (ASCII-encoded) domain name to a UTF-8 domain name. + +If GnuTLS is compiled without IDNA support, then this function +will return @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} . + +Note also, that this function will return an empty string if an +empty string is provided as input. + +@strong{Returns:} A negative error code on error, or 0 on success. + +@strong{Since:} 3.5.8 +@end deftypefun + +@subheading gnutls_init +@anchor{gnutls_init} +@deftypefun {int} {gnutls_init} (gnutls_session_t * @var{session}, unsigned int @var{flags}) +@var{session}: is a pointer to a @code{gnutls_session_t} type. + +@var{flags}: indicate if this session is to be used for server or client. + +This function initializes the provided session. Every +session must be initialized before use, and must be deinitialized +after used by calling @code{gnutls_deinit()} . + + @code{flags} can be any combination of flags from @code{gnutls_init_flags_t} . + +Note that since version 3.1.2 this function enables some common +TLS extensions such as session tickets and OCSP certificate status +request in client side by default. To prevent that use the @code{GNUTLS_NO_EXTENSIONS} +flag. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. +@end deftypefun + +@subheading gnutls_key_generate +@anchor{gnutls_key_generate} +@deftypefun {int} {gnutls_key_generate} (gnutls_datum_t * @var{key}, unsigned int @var{key_size}) +@var{key}: is a pointer to a @code{gnutls_datum_t} which will contain a newly +created key + +@var{key_size}: the number of bytes of the key + +Generates a random key of @code{key_size} bytes. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an +error code. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_kx_get +@anchor{gnutls_kx_get} +@deftypefun {gnutls_kx_algorithm_t} {gnutls_kx_get} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Get the currently used key exchange algorithm. + +This function will return @code{GNUTLS_KX_ECDHE_RSA} , or @code{GNUTLS_KX_DHE_RSA} +under TLS 1.3, to indicate an elliptic curve DH key exchange or +a finite field one. The precise group used is available +by calling @code{gnutls_group_get()} instead. + +@strong{Returns:} the key exchange algorithm used in the last handshake, a +@code{gnutls_kx_algorithm_t} value. +@end deftypefun + +@subheading gnutls_kx_get_id +@anchor{gnutls_kx_get_id} +@deftypefun {gnutls_kx_algorithm_t} {gnutls_kx_get_id} (const char * @var{name}) +@var{name}: is a KX name + +Convert a string to a @code{gnutls_kx_algorithm_t} value. The names are +compared in a case insensitive way. + +@strong{Returns:} an id of the specified KX algorithm, or @code{GNUTLS_KX_UNKNOWN} +on error. +@end deftypefun + +@subheading gnutls_kx_get_name +@anchor{gnutls_kx_get_name} +@deftypefun {const char *} {gnutls_kx_get_name} (gnutls_kx_algorithm_t @var{algorithm}) +@var{algorithm}: is a key exchange algorithm + +Convert a @code{gnutls_kx_algorithm_t} value to a string. + +@strong{Returns:} a pointer to a string that contains the name of the +specified key exchange algorithm, or @code{NULL} . +@end deftypefun + +@subheading gnutls_kx_list +@anchor{gnutls_kx_list} +@deftypefun {const gnutls_kx_algorithm_t *} {gnutls_kx_list} ( @var{void}) + +Get a list of supported key exchange algorithms. + +This function is not thread safe. + +@strong{Returns:} a (0)-terminated list of @code{gnutls_kx_algorithm_t} integers +indicating the available key exchange algorithms. +@end deftypefun + +@subheading gnutls_load_file +@anchor{gnutls_load_file} +@deftypefun {int} {gnutls_load_file} (const char * @var{filename}, gnutls_datum_t * @var{data}) +@var{filename}: the name of the file to load + +@var{data}: Where the file will be stored + +This function will load a file into a datum. The data are +zero terminated but the terminating null is not included in length. +The returned data are allocated using @code{gnutls_malloc()} . + +Note that this function is not designed for reading sensitive materials, +such as private keys, on practical applications. When the reading fails +in the middle, the partially loaded content might remain on memory. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. + +Since 3.1.0 +@end deftypefun + +@subheading gnutls_mac_get +@anchor{gnutls_mac_get} +@deftypefun {gnutls_mac_algorithm_t} {gnutls_mac_get} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Get the currently used MAC algorithm. + +@strong{Returns:} the currently used mac algorithm, a +@code{gnutls_mac_algorithm_t} value. +@end deftypefun + +@subheading gnutls_mac_get_id +@anchor{gnutls_mac_get_id} +@deftypefun {gnutls_mac_algorithm_t} {gnutls_mac_get_id} (const char * @var{name}) +@var{name}: is a MAC algorithm name + +Convert a string to a @code{gnutls_mac_algorithm_t} value. The names are +compared in a case insensitive way. + +@strong{Returns:} a @code{gnutls_mac_algorithm_t} id of the specified MAC +algorithm string, or @code{GNUTLS_MAC_UNKNOWN} on failure. +@end deftypefun + +@subheading gnutls_mac_get_key_size +@anchor{gnutls_mac_get_key_size} +@deftypefun {size_t} {gnutls_mac_get_key_size} (gnutls_mac_algorithm_t @var{algorithm}) +@var{algorithm}: is an encryption algorithm + +Returns the size of the MAC key used in TLS. + +@strong{Returns:} length (in bytes) of the given MAC key size, or 0 if the +given MAC algorithm is invalid. +@end deftypefun + +@subheading gnutls_mac_get_name +@anchor{gnutls_mac_get_name} +@deftypefun {const char *} {gnutls_mac_get_name} (gnutls_mac_algorithm_t @var{algorithm}) +@var{algorithm}: is a MAC algorithm + +Convert a @code{gnutls_mac_algorithm_t} value to a string. + +@strong{Returns:} a string that contains the name of the specified MAC +algorithm, or @code{NULL} . +@end deftypefun + +@subheading gnutls_mac_list +@anchor{gnutls_mac_list} +@deftypefun {const gnutls_mac_algorithm_t *} {gnutls_mac_list} ( @var{void}) + +Get a list of hash algorithms for use as MACs. Note that not +necessarily all MACs are supported in TLS cipher suites. +This function is not thread safe. + +@strong{Returns:} Return a (0)-terminated list of @code{gnutls_mac_algorithm_t} +integers indicating the available MACs. +@end deftypefun + +@subheading gnutls_memcmp +@anchor{gnutls_memcmp} +@deftypefun {int} {gnutls_memcmp} (const void * @var{s1}, const void * @var{s2}, size_t @var{n}) +@var{s1}: the first address to compare + +@var{s2}: the second address to compare + +@var{n}: the size of memory to compare + +This function will operate similarly to @code{memcmp()} , but will operate +on time that depends only on the size of the string. That is will +not return early if the strings don't match on the first byte. + +@strong{Returns:} non zero on difference and zero if the buffers are identical. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_memset +@anchor{gnutls_memset} +@deftypefun {void} {gnutls_memset} (void * @var{data}, int @var{c}, size_t @var{size}) +@var{data}: the memory to set + +@var{c}: the constant byte to fill the memory with + +@var{size}: the size of memory + +This function will operate similarly to @code{memset()} , but will +not be optimized out by the compiler. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_ocsp_status_request_enable_client +@anchor{gnutls_ocsp_status_request_enable_client} +@deftypefun {int} {gnutls_ocsp_status_request_enable_client} (gnutls_session_t @var{session}, gnutls_datum_t * @var{responder_id}, size_t @var{responder_id_size}, gnutls_datum_t * @var{extensions}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{responder_id}: ignored, must be @code{NULL} + +@var{responder_id_size}: ignored, must be zero + +@var{extensions}: ignored, must be @code{NULL} + +This function is to be used by clients to request OCSP response +from the server, using the "status_request" TLS extension. Only +OCSP status type is supported. + +Previous versions of GnuTLS supported setting @code{responder_id} and + @code{extensions} fields, but due to the difficult semantics of the +parameter usage, and other issues, this support was removed +since 3.6.0 and these parameters must be set to @code{NULL} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +@strong{Since:} 3.1.3 +@end deftypefun + +@subheading gnutls_ocsp_status_request_get +@anchor{gnutls_ocsp_status_request_get} +@deftypefun {int} {gnutls_ocsp_status_request_get} (gnutls_session_t @var{session}, gnutls_datum_t * @var{response}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{response}: a @code{gnutls_datum_t} with DER encoded OCSP response + +This function returns the OCSP status response received +from the TLS server. The @code{response} should be treated as +constant. If no OCSP response is available then +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} is returned. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +@strong{Since:} 3.1.3 +@end deftypefun + +@subheading gnutls_ocsp_status_request_get2 +@anchor{gnutls_ocsp_status_request_get2} +@deftypefun {int} {gnutls_ocsp_status_request_get2} (gnutls_session_t @var{session}, unsigned @var{idx}, gnutls_datum_t * @var{response}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{idx}: the index of peer's certificate + +@var{response}: a @code{gnutls_datum_t} with DER encoded OCSP response + +This function returns the OCSP status response received +from the TLS server for the certificate index provided. +The index corresponds to certificates as returned by +gnutls_certificate_get_peers. When index is zero this +function operates identically to @code{gnutls_ocsp_status_request_get()} . + +The returned @code{response} should be treated as +constant. If no OCSP response is available for the +given index then @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} +is returned. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_ocsp_status_request_is_checked +@anchor{gnutls_ocsp_status_request_is_checked} +@deftypefun {unsigned} {gnutls_ocsp_status_request_is_checked} (gnutls_session_t @var{session}, unsigned int @var{flags}) +@var{session}: is a gnutls session + +@var{flags}: should be zero or @code{GNUTLS_OCSP_SR_IS_AVAIL} + +When flags are zero this function returns non-zero if a valid OCSP status +response was included in the TLS handshake. That is, an OCSP status response +which is not too old, superseded or marks the certificate as revoked. +It returns zero otherwise. + +When the flag @code{GNUTLS_OCSP_SR_IS_AVAIL} is specified, the function +returns non-zero if an OCSP status response was included in the handshake +even if it was invalid. Otherwise, if no OCSP status response was included, +it returns zero. The @code{GNUTLS_OCSP_SR_IS_AVAIL} flag was introduced in GnuTLS 3.4.0. + +This is a helper function when needing to decide whether to perform an +explicit OCSP validity check on the peer's certificate. Should be called after +any of gnutls_certificate_verify_peers*() are called. + +This function is always usable on client side, but on server side only +under TLS 1.3, which is the first version of TLS that allows cliend-side OCSP +responses. + +@strong{Returns:} Non-zero if the response was valid, or a zero if it wasn't sent, +or sent and was invalid. + +@strong{Since:} 3.1.4 +@end deftypefun + +@subheading gnutls_oid_to_digest +@anchor{gnutls_oid_to_digest} +@deftypefun {gnutls_digest_algorithm_t} {gnutls_oid_to_digest} (const char * @var{oid}) +@var{oid}: is an object identifier + +Converts a textual object identifier to a @code{gnutls_digest_algorithm_t} value. + +@strong{Returns:} a @code{gnutls_digest_algorithm_t} id of the specified digest +algorithm, or @code{GNUTLS_DIG_UNKNOWN} on failure. + +@strong{Since:} 3.4.3 +@end deftypefun + +@subheading gnutls_oid_to_ecc_curve +@anchor{gnutls_oid_to_ecc_curve} +@deftypefun {gnutls_ecc_curve_t} {gnutls_oid_to_ecc_curve} (const char * @var{oid}) +@var{oid}: is a curve's OID + + +@strong{Returns:} return a @code{gnutls_ecc_curve_t} value corresponding to +the specified OID, or @code{GNUTLS_ECC_CURVE_INVALID} on error. + +@strong{Since:} 3.4.3 +@end deftypefun + +@subheading gnutls_oid_to_gost_paramset +@anchor{gnutls_oid_to_gost_paramset} +@deftypefun {gnutls_gost_paramset_t} {gnutls_oid_to_gost_paramset} (const char * @var{oid}) +@var{oid}: is an object identifier + +Converts a textual object identifier to a @code{gnutls_gost_paramset_t} value. + +@strong{Returns:} a @code{gnutls_gost_paramset_get_oid} of the specified GOST 28147 +param st, or @code{GNUTLS_GOST_PARAMSET_UNKNOWN} on failure. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_oid_to_mac +@anchor{gnutls_oid_to_mac} +@deftypefun {gnutls_mac_algorithm_t} {gnutls_oid_to_mac} (const char * @var{oid}) +@var{oid}: is an object identifier + +Converts a textual object identifier typically from PKCS@code{5} values to a @code{gnutls_mac_algorithm_t} value. + +@strong{Returns:} a @code{gnutls_mac_algorithm_t} id of the specified digest +algorithm, or @code{GNUTLS_MAC_UNKNOWN} on failure. + +@strong{Since:} 3.5.4 +@end deftypefun + +@subheading gnutls_oid_to_pk +@anchor{gnutls_oid_to_pk} +@deftypefun {gnutls_pk_algorithm_t} {gnutls_oid_to_pk} (const char * @var{oid}) +@var{oid}: is an object identifier + +Converts a textual object identifier to a @code{gnutls_pk_algorithm_t} value. + +@strong{Returns:} a @code{gnutls_pk_algorithm_t} id of the specified digest +algorithm, or @code{GNUTLS_PK_UNKNOWN} on failure. + +@strong{Since:} 3.4.3 +@end deftypefun + +@subheading gnutls_oid_to_sign +@anchor{gnutls_oid_to_sign} +@deftypefun {gnutls_sign_algorithm_t} {gnutls_oid_to_sign} (const char * @var{oid}) +@var{oid}: is an object identifier + +Converts a textual object identifier to a @code{gnutls_sign_algorithm_t} value. + +@strong{Returns:} a @code{gnutls_sign_algorithm_t} id of the specified digest +algorithm, or @code{GNUTLS_SIGN_UNKNOWN} on failure. + +@strong{Since:} 3.4.3 +@end deftypefun + +@subheading gnutls_openpgp_send_cert +@anchor{gnutls_openpgp_send_cert} +@deftypefun {void} {gnutls_openpgp_send_cert} (gnutls_session_t @var{session}, gnutls_openpgp_crt_status_t @var{status}) +@var{session}: is a gnutls session + +@var{status}: is ignored + +This function is no-op. + +@strong{Returns:} @code{GNUTLS_E_UNIMPLEMENTED_FEATURE} . +@end deftypefun + +@subheading gnutls_packet_deinit +@anchor{gnutls_packet_deinit} +@deftypefun {void} {gnutls_packet_deinit} (gnutls_packet_t @var{packet}) +@var{packet}: is a pointer to a @code{gnutls_packet_st} structure. + +This function will deinitialize all data associated with +the received packet. + +@strong{Since:} 3.3.5 +@end deftypefun + +@subheading gnutls_packet_get +@anchor{gnutls_packet_get} +@deftypefun {void} {gnutls_packet_get} (gnutls_packet_t @var{packet}, gnutls_datum_t * @var{data}, unsigned char * @var{sequence}) +@var{packet}: is a @code{gnutls_packet_t} type. + +@var{data}: will contain the data present in the @code{packet} structure (may be @code{NULL} ) + +@var{sequence}: the 8-bytes of the packet sequence number (may be @code{NULL} ) + +This function returns the data and sequence number associated with +the received packet. + +@strong{Since:} 3.3.5 +@end deftypefun + +@subheading gnutls_pem_base64_decode +@anchor{gnutls_pem_base64_decode} +@deftypefun {int} {gnutls_pem_base64_decode} (const char * @var{header}, const gnutls_datum_t * @var{b64_data}, unsigned char * @var{result}, size_t * @var{result_size}) +@var{header}: A null terminated string with the PEM header (eg. CERTIFICATE) + +@var{b64_data}: contain the encoded data + +@var{result}: the place where decoded data will be copied + +@var{result_size}: holds the size of the result + +This function will decode the given encoded data. If the header +given is non @code{NULL} this function will search for "-----BEGIN header" +and decode only this part. Otherwise it will decode the first PEM +packet found. + +@strong{Returns:} On success @code{GNUTLS_E_SUCCESS} (0) is returned, +@code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned if the buffer given is +not long enough, or 0 on success. +@end deftypefun + +@subheading gnutls_pem_base64_decode2 +@anchor{gnutls_pem_base64_decode2} +@deftypefun {int} {gnutls_pem_base64_decode2} (const char * @var{header}, const gnutls_datum_t * @var{b64_data}, gnutls_datum_t * @var{result}) +@var{header}: The PEM header (eg. CERTIFICATE) + +@var{b64_data}: contains the encoded data + +@var{result}: the location of decoded data + +This function will decode the given encoded data. The decoded data +will be allocated, and stored into result. If the header given is +non null this function will search for "-----BEGIN header" and +decode only this part. Otherwise it will decode the first PEM +packet found. + +You should use @code{gnutls_free()} to free the returned data. + +Note, that prior to GnuTLS 3.4.0 this function was available +under the name @code{gnutls_pem_base64_decode_alloc()} . There is +compatibility macro pointing to this function. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_pem_base64_encode +@anchor{gnutls_pem_base64_encode} +@deftypefun {int} {gnutls_pem_base64_encode} (const char * @var{msg}, const gnutls_datum_t * @var{data}, char * @var{result}, size_t * @var{result_size}) +@var{msg}: is a message to be put in the header (may be @code{NULL} ) + +@var{data}: contain the raw data + +@var{result}: the place where base64 data will be copied + +@var{result_size}: holds the size of the result + +This function will convert the given data to printable data, using +the base64 encoding. This is the encoding used in PEM messages. + +The output string will be null terminated, although the output size will +not include the terminating null. + +@strong{Returns:} On success @code{GNUTLS_E_SUCCESS} (0) is returned, +@code{GNUTLS_E_SHORT_MEMORY_BUFFER} is returned if the buffer given is +not long enough, or 0 on success. +@end deftypefun + +@subheading gnutls_pem_base64_encode2 +@anchor{gnutls_pem_base64_encode2} +@deftypefun {int} {gnutls_pem_base64_encode2} (const char * @var{header}, const gnutls_datum_t * @var{data}, gnutls_datum_t * @var{result}) +@var{header}: is a message to be put in the encoded header (may be @code{NULL} ) + +@var{data}: contains the raw data + +@var{result}: will hold the newly allocated encoded data + +This function will convert the given data to printable data, using +the base64 encoding. This is the encoding used in PEM messages. +This function will allocate the required memory to hold the encoded +data. + +You should use @code{gnutls_free()} to free the returned data. + +Note, that prior to GnuTLS 3.4.0 this function was available +under the name @code{gnutls_pem_base64_encode_alloc()} . There is +compatibility macro pointing to this function. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_perror +@anchor{gnutls_perror} +@deftypefun {void} {gnutls_perror} (int @var{error}) +@var{error}: is a GnuTLS error code, a negative error code + +This function is like @code{perror()} . The only difference is that it +accepts an error number returned by a gnutls function. +@end deftypefun + +@subheading gnutls_pk_algorithm_get_name +@anchor{gnutls_pk_algorithm_get_name} +@deftypefun {const char *} {gnutls_pk_algorithm_get_name} (gnutls_pk_algorithm_t @var{algorithm}) +@var{algorithm}: is a pk algorithm + +Convert a @code{gnutls_pk_algorithm_t} value to a string. + +@strong{Returns:} a string that contains the name of the specified public +key algorithm, or @code{NULL} . +@end deftypefun + +@subheading gnutls_pk_bits_to_sec_param +@anchor{gnutls_pk_bits_to_sec_param} +@deftypefun {gnutls_sec_param_t} {gnutls_pk_bits_to_sec_param} (gnutls_pk_algorithm_t @var{algo}, unsigned int @var{bits}) +@var{algo}: is a public key algorithm + +@var{bits}: is the number of bits + +This is the inverse of @code{gnutls_sec_param_to_pk_bits()} . Given an algorithm +and the number of bits, it will return the security parameter. This is +a rough indication. + +@strong{Returns:} The security parameter. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pk_get_id +@anchor{gnutls_pk_get_id} +@deftypefun {gnutls_pk_algorithm_t} {gnutls_pk_get_id} (const char * @var{name}) +@var{name}: is a string containing a public key algorithm name. + +Convert a string to a @code{gnutls_pk_algorithm_t} value. The names are +compared in a case insensitive way. For example, +gnutls_pk_get_id("RSA") will return @code{GNUTLS_PK_RSA} . + +@strong{Returns:} a @code{gnutls_pk_algorithm_t} id of the specified public key +algorithm string, or @code{GNUTLS_PK_UNKNOWN} on failures. + +@strong{Since:} 2.6.0 +@end deftypefun + +@subheading gnutls_pk_get_name +@anchor{gnutls_pk_get_name} +@deftypefun {const char *} {gnutls_pk_get_name} (gnutls_pk_algorithm_t @var{algorithm}) +@var{algorithm}: is a public key algorithm + +Convert a @code{gnutls_pk_algorithm_t} value to a string. + +@strong{Returns:} a pointer to a string that contains the name of the +specified public key algorithm, or @code{NULL} . + +@strong{Since:} 2.6.0 +@end deftypefun + +@subheading gnutls_pk_get_oid +@anchor{gnutls_pk_get_oid} +@deftypefun {const char *} {gnutls_pk_get_oid} (gnutls_pk_algorithm_t @var{algorithm}) +@var{algorithm}: is a public key algorithm + +Convert a @code{gnutls_pk_algorithm_t} value to its object identifier string. + +@strong{Returns:} a pointer to a string that contains the object identifier of the +specified public key algorithm, or @code{NULL} . + +@strong{Since:} 3.4.3 +@end deftypefun + +@subheading gnutls_pk_list +@anchor{gnutls_pk_list} +@deftypefun {const gnutls_pk_algorithm_t *} {gnutls_pk_list} ( @var{void}) + +Get a list of supported public key algorithms. + +This function is not thread safe. + +@strong{Returns:} a (0)-terminated list of @code{gnutls_pk_algorithm_t} integers +indicating the available ciphers. + +@strong{Since:} 2.6.0 +@end deftypefun + +@subheading gnutls_pk_to_sign +@anchor{gnutls_pk_to_sign} +@deftypefun {gnutls_sign_algorithm_t} {gnutls_pk_to_sign} (gnutls_pk_algorithm_t @var{pk}, gnutls_digest_algorithm_t @var{hash}) +@var{pk}: is a public key algorithm + +@var{hash}: a hash algorithm + +This function maps public key and hash algorithms combinations +to signature algorithms. + +@strong{Returns:} return a @code{gnutls_sign_algorithm_t} value, or @code{GNUTLS_SIGN_UNKNOWN} on error. +@end deftypefun + +@subheading gnutls_prf +@anchor{gnutls_prf} +@deftypefun {int} {gnutls_prf} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, int @var{server_random_first}, size_t @var{extra_size}, const char * @var{extra}, size_t @var{outsize}, char * @var{out}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{label_size}: length of the @code{label} variable. + +@var{label}: label used in PRF computation, typically a short string. + +@var{server_random_first}: non-zero if server random field should be first in seed + +@var{extra_size}: length of the @code{extra} variable. + +@var{extra}: optional extra data to seed the PRF with. + +@var{outsize}: size of pre-allocated output buffer to hold the output. + +@var{out}: pre-allocated buffer to hold the generated data. + +Applies the TLS Pseudo-Random-Function (PRF) on the master secret +and the provided data, seeded with the client and server random fields. +For the key expansion specified in RFC5705 see @code{gnutls_prf_rfc5705()} . + +The @code{label} variable usually contains a string denoting the purpose +for the generated data. The @code{server_random_first} indicates whether +the client random field or the server random field should be first +in the seed. Non-zero indicates that the server random field is first, +0 that the client random field is first. + +The @code{extra} variable can be used to add more data to the seed, after +the random variables. It can be used to make sure the +generated output is strongly connected to some additional data +(e.g., a string used in user authentication). + +The output is placed in @code{out} , which must be pre-allocated. + +@strong{Note:} This function produces identical output with @code{gnutls_prf_rfc5705()} +when @code{server_random_first} is set to 0 and @code{extra} is @code{NULL} . Under TLS1.3 +this function will only operate when these conditions are true, or otherwise +return @code{GNUTLS_E_INVALID_REQUEST} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. +@end deftypefun + +@subheading gnutls_prf_early +@anchor{gnutls_prf_early} +@deftypefun {int} {gnutls_prf_early} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, size_t @var{context_size}, const char * @var{context}, size_t @var{outsize}, char * @var{out}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{label_size}: length of the @code{label} variable. + +@var{label}: label used in PRF computation, typically a short string. + +@var{context_size}: length of the @code{extra} variable. + +@var{context}: optional extra data to seed the PRF with. + +@var{outsize}: size of pre-allocated output buffer to hold the output. + +@var{out}: pre-allocated buffer to hold the generated data. + +This function is similar to @code{gnutls_prf_rfc5705()} , but only works in +TLS 1.3 or later to export early keying material. + +Note that the keying material is only available after the +ClientHello message is processed and before the application traffic +keys are established. Therefore this function shall be called in a +handshake hook function for @code{GNUTLS_HANDSHAKE_CLIENT_HELLO} . + +The @code{label} variable usually contains a string denoting the purpose +for the generated data. + +The @code{context} variable can be used to add more data to the seed, after +the random variables. It can be used to make sure the +generated output is strongly connected to some additional data +(e.g., a string used in user authentication). + +The output is placed in @code{out} , which must be pre-allocated. + +Note that, to provide the RFC5705 context, the @code{context} variable +must be non-null. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. + +@strong{Since:} 3.6.8 +@end deftypefun + +@subheading gnutls_prf_hash_get +@anchor{gnutls_prf_hash_get} +@deftypefun {gnutls_digest_algorithm_t} {gnutls_prf_hash_get} (const gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Get the currently used hash algorithm. In TLS 1.3, the hash +algorithm is used for both the key derivation function and +handshake message authentication code. In TLS 1.2, it matches the +hash algorithm used for PRF. + +@strong{Returns:} the currently used hash algorithm, a +@code{gnutls_digest_algorithm_t} value. + +@strong{Since:} 3.6.13 +@end deftypefun + +@subheading gnutls_prf_raw +@anchor{gnutls_prf_raw} +@deftypefun {int} {gnutls_prf_raw} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, size_t @var{seed_size}, const char * @var{seed}, size_t @var{outsize}, char * @var{out}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{label_size}: length of the @code{label} variable. + +@var{label}: label used in PRF computation, typically a short string. + +@var{seed_size}: length of the @code{seed} variable. + +@var{seed}: optional extra data to seed the PRF with. + +@var{outsize}: size of pre-allocated output buffer to hold the output. + +@var{out}: pre-allocated buffer to hold the generated data. + +Apply the TLS Pseudo-Random-Function (PRF) on the master secret +and the provided data. + +The @code{label} variable usually contains a string denoting the purpose +for the generated data. The @code{seed} usually contains data such as the +client and server random, perhaps together with some additional +data that is added to guarantee uniqueness of the output for a +particular purpose. + +Because the output is not guaranteed to be unique for a particular +session unless @code{seed} includes the client random and server random +fields (the PRF would output the same data on another connection +resumed from the first one), it is not recommended to use this +function directly. The @code{gnutls_prf()} function seeds the PRF with the +client and server random fields directly, and is recommended if you +want to generate pseudo random data unique for each session. + +@strong{Note:} This function will only operate under TLS versions prior to 1.3. +In TLS1.3 the use of PRF is replaced with HKDF and the generic +exporters like @code{gnutls_prf_rfc5705()} should be used instead. Under +TLS1.3 this function returns @code{GNUTLS_E_INVALID_REQUEST} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. +@end deftypefun + +@subheading gnutls_prf_rfc5705 +@anchor{gnutls_prf_rfc5705} +@deftypefun {int} {gnutls_prf_rfc5705} (gnutls_session_t @var{session}, size_t @var{label_size}, const char * @var{label}, size_t @var{context_size}, const char * @var{context}, size_t @var{outsize}, char * @var{out}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{label_size}: length of the @code{label} variable. + +@var{label}: label used in PRF computation, typically a short string. + +@var{context_size}: length of the @code{extra} variable. + +@var{context}: optional extra data to seed the PRF with. + +@var{outsize}: size of pre-allocated output buffer to hold the output. + +@var{out}: pre-allocated buffer to hold the generated data. + +Exports keying material from TLS/DTLS session to an application, as +specified in RFC5705. + +In the TLS versions prior to 1.3, it applies the TLS +Pseudo-Random-Function (PRF) on the master secret and the provided +data, seeded with the client and server random fields. + +In TLS 1.3, it applies HKDF on the exporter master secret derived +from the master secret. + +The @code{label} variable usually contains a string denoting the purpose +for the generated data. + +The @code{context} variable can be used to add more data to the seed, after +the random variables. It can be used to make sure the +generated output is strongly connected to some additional data +(e.g., a string used in user authentication). + +The output is placed in @code{out} , which must be pre-allocated. + +Note that, to provide the RFC5705 context, the @code{context} variable +must be non-null. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. + +@strong{Since:} 3.4.4 +@end deftypefun + +@subheading gnutls_priority_certificate_type_list +@anchor{gnutls_priority_certificate_type_list} +@deftypefun {int} {gnutls_priority_certificate_type_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) +@var{pcache}: is a @code{gnutls_priority_t} type. + +@var{list}: will point to an integer list + +Get a list of available certificate types in the priority +structure. + +As of version 3.6.4 this function is an alias for +gnutls_priority_certificate_type_list2 with the target parameter +set to: +- GNUTLS_CTYPE_SERVER, if the @code{SERVER_PRECEDENCE} option is set +- GNUTLS_CTYPE_CLIENT, otherwise. + +@strong{Returns:} the number of certificate types, or an error code. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_priority_certificate_type_list2 +@anchor{gnutls_priority_certificate_type_list2} +@deftypefun {int} {gnutls_priority_certificate_type_list2} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}, gnutls_ctype_target_t @var{target}) +@var{pcache}: is a @code{gnutls_priority_t} type. + +@var{list}: will point to an integer list. + +@var{target}: is a @code{gnutls_ctype_target_t} type. Valid arguments are +GNUTLS_CTYPE_CLIENT and GNUTLS_CTYPE_SERVER + +Get a list of available certificate types for the given target +in the priority structure. + +@strong{Returns:} the number of certificate types, or an error code. + +@strong{Since:} 3.6.4 +@end deftypefun + +@subheading gnutls_priority_cipher_list +@anchor{gnutls_priority_cipher_list} +@deftypefun {int} {gnutls_priority_cipher_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) +@var{pcache}: is a @code{gnutls_priority_t} type. + +@var{list}: will point to an integer list + +Get a list of available ciphers in the priority +structure. + +@strong{Returns:} the number of items, or an error code. + +@strong{Since:} 3.2.3 +@end deftypefun + +@subheading gnutls_priority_deinit +@anchor{gnutls_priority_deinit} +@deftypefun {void} {gnutls_priority_deinit} (gnutls_priority_t @var{priority_cache}) +@var{priority_cache}: is a @code{gnutls_priority_t} type. + +Deinitializes the priority cache. +@end deftypefun + +@subheading gnutls_priority_ecc_curve_list +@anchor{gnutls_priority_ecc_curve_list} +@deftypefun {int} {gnutls_priority_ecc_curve_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) +@var{pcache}: is a @code{gnutls_priority_t} type. + +@var{list}: will point to an integer list + +Get a list of available elliptic curves in the priority +structure. + +@strong{Deprecated:} This function has been replaced by +@code{gnutls_priority_group_list()} since 3.6.0. + +@strong{Returns:} the number of items, or an error code. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_priority_get_cipher_suite_index +@anchor{gnutls_priority_get_cipher_suite_index} +@deftypefun {int} {gnutls_priority_get_cipher_suite_index} (gnutls_priority_t @var{pcache}, unsigned int @var{idx}, unsigned int * @var{sidx}) +@var{pcache}: is a @code{gnutls_priority_t} type. + +@var{idx}: is an index number. + +@var{sidx}: internal index of cipher suite to get information about. + +Provides the internal ciphersuite index to be used with +@code{gnutls_cipher_suite_info()} . The index @code{idx} provided is an +index kept at the priorities structure. It might be that a valid +priorities index does not correspond to a ciphersuite and in +that case @code{GNUTLS_E_UNKNOWN_CIPHER_SUITE} will be returned. +Once the last available index is crossed then +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned. + +@strong{Returns:} On success it returns @code{GNUTLS_E_SUCCESS} (0), or a negative error value otherwise. + +@strong{Since:} 3.0.9 +@end deftypefun + +@subheading gnutls_priority_group_list +@anchor{gnutls_priority_group_list} +@deftypefun {int} {gnutls_priority_group_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) +@var{pcache}: is a @code{gnutls_priority_t} type. + +@var{list}: will point to an integer list + +Get a list of available groups in the priority +structure. + +@strong{Returns:} the number of items, or an error code. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_priority_init +@anchor{gnutls_priority_init} +@deftypefun {int} {gnutls_priority_init} (gnutls_priority_t * @var{priority_cache}, const char * @var{priorities}, const char ** @var{err_pos}) +@var{priority_cache}: is a @code{gnutls_priority_t} type. + +@var{priorities}: is a string describing priorities (may be @code{NULL} ) + +@var{err_pos}: In case of an error this will have the position in the string the error occurred + +For applications that do not modify their crypto settings per release, consider +using @code{gnutls_priority_init2()} with @code{GNUTLS_PRIORITY_INIT_DEF_APPEND} flag +instead. We suggest to use centralized crypto settings handled by the GnuTLS +library, and applications modifying the default settings to their needs. + +This function is identical to @code{gnutls_priority_init2()} with zero +flags. + +A @code{NULL} @code{priorities} string indicates the default priorities to be +used (this is available since GnuTLS 3.3.0). + +@strong{Returns:} On syntax error @code{GNUTLS_E_INVALID_REQUEST} is returned, +@code{GNUTLS_E_SUCCESS} on success, or an error code. +@end deftypefun + +@subheading gnutls_priority_init2 +@anchor{gnutls_priority_init2} +@deftypefun {int} {gnutls_priority_init2} (gnutls_priority_t * @var{priority_cache}, const char * @var{priorities}, const char ** @var{err_pos}, unsigned @var{flags}) +@var{priority_cache}: is a @code{gnutls_priority_t} type. + +@var{priorities}: is a string describing priorities (may be @code{NULL} ) + +@var{err_pos}: In case of an error this will have the position in the string the error occurred + +@var{flags}: zero or @code{GNUTLS_PRIORITY_INIT_DEF_APPEND} + +Sets priorities for the ciphers, key exchange methods, and macs. +The @code{priority_cache} should be deinitialized +using @code{gnutls_priority_deinit()} . + +The @code{priorities} option allows you to specify a colon +separated list of the cipher priorities to enable. +Some keywords are defined to provide quick access +to common preferences. + +When @code{flags} is set to @code{GNUTLS_PRIORITY_INIT_DEF_APPEND} then the @code{priorities} specified will be appended to the default options. + +Unless there is a special need, use the "NORMAL" keyword to +apply a reasonable security level, or "NORMAL:%COMPAT" for compatibility. + +"PERFORMANCE" means all the "secure" ciphersuites are enabled, +limited to 128 bit ciphers and sorted by terms of speed +performance. + +"LEGACY" the NORMAL settings for GnuTLS 3.2.x or earlier. There is +no verification profile set, and the allowed DH primes are considered +weak today. + +"NORMAL" means all "secure" ciphersuites. The 256-bit ciphers are +included as a fallback only. The ciphers are sorted by security +margin. + +"PFS" means all "secure" ciphersuites that support perfect forward secrecy. +The 256-bit ciphers are included as a fallback only. +The ciphers are sorted by security margin. + +"SECURE128" means all "secure" ciphersuites of security level 128-bit +or more. + +"SECURE192" means all "secure" ciphersuites of security level 192-bit +or more. + +"SUITEB128" means all the NSA SuiteB ciphersuites with security level +of 128. + +"SUITEB192" means all the NSA SuiteB ciphersuites with security level +of 192. + +"NONE" means nothing is enabled. This disables everything, including protocols. + +"@@KEYWORD1,KEYWORD2,..." The system administrator imposed settings. +The provided keyword(s) will be expanded from a configuration-time +provided file - default is: /etc/gnutls/config. +Any attributes that follow it, will be appended to the expanded +string. If multiple keywords are provided, separated by commas, +then the first keyword that exists in the configuration file +will be used. At least one of the keywords must exist, or this +function will return an error. Typical usage would be to specify +an application specified keyword first, followed by "SYSTEM" as +a default fallback. e.g., " @code{LIBVIRT} ,SYSTEM:!-VERS-SSL3.0" will +first try to find a config file entry matching "LIBVIRT", but if +that does not exist will use the entry for "SYSTEM". If "SYSTEM" +does not exist either, an error will be returned. In all cases, +the SSL3.0 protocol will be disabled. The system priority file +entries should be formatted as "KEYWORD=VALUE", e.g., +"SYSTEM=NORMAL:+ARCFOUR-128". + +Special keywords are "!", "-" and "+". +"!" or "-" appended with an algorithm will remove this algorithm. +"+" appended with an algorithm will add this algorithm. + +Check the GnuTLS manual section "Priority strings" for detailed +information. + +@strong{Examples:} +"NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL" + +"NORMAL:+ARCFOUR-128" means normal ciphers plus ARCFOUR-128. + +"SECURE128:-VERS-SSL3.0" means that only secure ciphers are +and enabled, SSL3.0 is disabled. + +"NONE:+VERS-TLS-ALL:+AES-128-CBC:+RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1", + +"NONE:+VERS-TLS-ALL:+AES-128-CBC:+ECDHE-RSA:+SHA1:+COMP-NULL:+SIGN-RSA-SHA1:+CURVE-SECP256R1", + +"SECURE256:+SECURE128", + +Note that "NORMAL:%COMPAT" is the most compatible mode. + +A @code{NULL} @code{priorities} string indicates the default priorities to be +used (this is available since GnuTLS 3.3.0). + +@strong{Returns:} On syntax error @code{GNUTLS_E_INVALID_REQUEST} is returned, +@code{GNUTLS_E_SUCCESS} on success, or an error code. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_priority_kx_list +@anchor{gnutls_priority_kx_list} +@deftypefun {int} {gnutls_priority_kx_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) +@var{pcache}: is a @code{gnutls_priority_t} type. + +@var{list}: will point to an integer list + +Get a list of available key exchange methods in the priority +structure. + +@strong{Returns:} the number of items, or an error code. + +@strong{Since:} 3.2.3 +@end deftypefun + +@subheading gnutls_priority_mac_list +@anchor{gnutls_priority_mac_list} +@deftypefun {int} {gnutls_priority_mac_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) +@var{pcache}: is a @code{gnutls_priority_t} type. + +@var{list}: will point to an integer list + +Get a list of available MAC algorithms in the priority +structure. + +@strong{Returns:} the number of items, or an error code. + +@strong{Since:} 3.2.3 +@end deftypefun + +@subheading gnutls_priority_protocol_list +@anchor{gnutls_priority_protocol_list} +@deftypefun {int} {gnutls_priority_protocol_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) +@var{pcache}: is a @code{gnutls_priority_t} type. + +@var{list}: will point to an integer list + +Get a list of available TLS version numbers in the priority +structure. + +@strong{Returns:} the number of protocols, or an error code. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_priority_set +@anchor{gnutls_priority_set} +@deftypefun {int} {gnutls_priority_set} (gnutls_session_t @var{session}, gnutls_priority_t @var{priority}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{priority}: is a @code{gnutls_priority_t} type. + +Sets the priorities to use on the ciphers, key exchange methods, +and macs. Note that this function is expected to be called once +per session; when called multiple times (e.g., before a re-handshake, +the caller should make sure that any new settings are not incompatible +with the original session). + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code on error. +@end deftypefun + +@subheading gnutls_priority_set_direct +@anchor{gnutls_priority_set_direct} +@deftypefun {int} {gnutls_priority_set_direct} (gnutls_session_t @var{session}, const char * @var{priorities}, const char ** @var{err_pos}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{priorities}: is a string describing priorities + +@var{err_pos}: In case of an error this will have the position in the string the error occurred + +Sets the priorities to use on the ciphers, key exchange methods, +and macs. This function avoids keeping a +priority cache and is used to directly set string priorities to a +TLS session. For documentation check the @code{gnutls_priority_init()} . + +To use a reasonable default, consider using @code{gnutls_set_default_priority()} , +or @code{gnutls_set_default_priority_append()} instead of this function. + +@strong{Returns:} On syntax error @code{GNUTLS_E_INVALID_REQUEST} is returned, +@code{GNUTLS_E_SUCCESS} on success, or an error code. +@end deftypefun + +@subheading gnutls_priority_sign_list +@anchor{gnutls_priority_sign_list} +@deftypefun {int} {gnutls_priority_sign_list} (gnutls_priority_t @var{pcache}, const unsigned int ** @var{list}) +@var{pcache}: is a @code{gnutls_priority_t} type. + +@var{list}: will point to an integer list + +Get a list of available signature algorithms in the priority +structure. + +@strong{Returns:} the number of algorithms, or an error code. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_priority_string_list +@anchor{gnutls_priority_string_list} +@deftypefun {const char *} {gnutls_priority_string_list} (unsigned @var{iter}, unsigned int @var{flags}) +@var{iter}: an integer counter starting from zero + +@var{flags}: one of @code{GNUTLS_PRIORITY_LIST_INIT_KEYWORDS} , @code{GNUTLS_PRIORITY_LIST_SPECIAL} + +Can be used to iterate all available priority strings. +Due to internal implementation details, there are cases where this +function can return the empty string. In that case that string should be ignored. +When no strings are available it returns @code{NULL} . + +@strong{Returns:} a priority string + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_protocol_get_id +@anchor{gnutls_protocol_get_id} +@deftypefun {gnutls_protocol_t} {gnutls_protocol_get_id} (const char * @var{name}) +@var{name}: is a protocol name + +The names are compared in a case insensitive way. + +@strong{Returns:} an id of the specified protocol, or +@code{GNUTLS_VERSION_UNKNOWN} on error. +@end deftypefun + +@subheading gnutls_protocol_get_name +@anchor{gnutls_protocol_get_name} +@deftypefun {const char *} {gnutls_protocol_get_name} (gnutls_protocol_t @var{version}) +@var{version}: is a (gnutls) version number + +Convert a @code{gnutls_protocol_t} value to a string. + +@strong{Returns:} a string that contains the name of the specified TLS +version (e.g., "TLS1.0"), or @code{NULL} . +@end deftypefun + +@subheading gnutls_protocol_get_version +@anchor{gnutls_protocol_get_version} +@deftypefun {gnutls_protocol_t} {gnutls_protocol_get_version} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Get TLS version, a @code{gnutls_protocol_t} value. + +@strong{Returns:} The version of the currently used protocol. +@end deftypefun + +@subheading gnutls_protocol_list +@anchor{gnutls_protocol_list} +@deftypefun {const gnutls_protocol_t *} {gnutls_protocol_list} ( @var{void}) + +Get a list of supported protocols, e.g. SSL 3.0, TLS 1.0 etc. + +This function is not thread safe. + +@strong{Returns:} a (0)-terminated list of @code{gnutls_protocol_t} integers +indicating the available protocols. +@end deftypefun + +@subheading gnutls_protocol_set_enabled +@anchor{gnutls_protocol_set_enabled} +@deftypefun {int} {gnutls_protocol_set_enabled} (gnutls_protocol_t @var{version}, unsigned int @var{enabled}) +@var{version}: is a (gnutls) version number + +@var{enabled}: whether to enable the protocol + +Control the previous system-wide setting that marked @code{version} as +enabled or disabled. Calling this fuction is allowed +only if allowlisting mode is set in the configuration file, +and only if the system-wide TLS priority string +has not been initialized yet. +The intended usage is to provide applications with a way +to expressly deviate from the distribution or site defaults +inherited from the configuration file. +The modification is composable with further modifications +performed through the priority string mechanism. + +This function is not thread-safe and is intended to be called +in the main thread at the beginning of the process execution. + +@strong{Returns:} 0 on success or negative error code otherwise. + +@strong{Since:} 3.7.3 +@end deftypefun + +@subheading gnutls_psk_allocate_client_credentials +@anchor{gnutls_psk_allocate_client_credentials} +@deftypefun {int} {gnutls_psk_allocate_client_credentials} (gnutls_psk_client_credentials_t * @var{sc}) +@var{sc}: is a pointer to a @code{gnutls_psk_server_credentials_t} type. + +Allocate a gnutls_psk_client_credentials_t structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_psk_allocate_server_credentials +@anchor{gnutls_psk_allocate_server_credentials} +@deftypefun {int} {gnutls_psk_allocate_server_credentials} (gnutls_psk_server_credentials_t * @var{sc}) +@var{sc}: is a pointer to a @code{gnutls_psk_server_credentials_t} type. + +Allocate a gnutls_psk_server_credentials_t structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_psk_client_get_hint +@anchor{gnutls_psk_client_get_hint} +@deftypefun {const char *} {gnutls_psk_client_get_hint} (gnutls_session_t @var{session}) +@var{session}: is a gnutls session + +The PSK identity hint may give the client help in deciding which +username to use. This should only be called in case of PSK +authentication and in case of a client. + +@strong{Note:} there is no hint in TLS 1.3, so this function will return @code{NULL} +if TLS 1.3 has been negotiated. + +@strong{Returns:} the identity hint of the peer, or @code{NULL} in case of an error or if TLS 1.3 is being used. + +@strong{Since:} 2.4.0 +@end deftypefun + +@subheading gnutls_psk_free_client_credentials +@anchor{gnutls_psk_free_client_credentials} +@deftypefun {void} {gnutls_psk_free_client_credentials} (gnutls_psk_client_credentials_t @var{sc}) +@var{sc}: is a @code{gnutls_psk_client_credentials_t} type. + +Free a gnutls_psk_client_credentials_t structure. +@end deftypefun + +@subheading gnutls_psk_free_server_credentials +@anchor{gnutls_psk_free_server_credentials} +@deftypefun {void} {gnutls_psk_free_server_credentials} (gnutls_psk_server_credentials_t @var{sc}) +@var{sc}: is a @code{gnutls_psk_server_credentials_t} type. + +Free a gnutls_psk_server_credentials_t structure. +@end deftypefun + +@subheading gnutls_psk_server_get_username +@anchor{gnutls_psk_server_get_username} +@deftypefun {const char *} {gnutls_psk_server_get_username} (gnutls_session_t @var{session}) +@var{session}: is a gnutls session + +This should only be called in case of PSK authentication and in +case of a server. + +The returned pointer should be considered constant (do not free) and valid +for the lifetime of the session. + +This function will return @code{NULL} if the username has embedded NULL bytes. +In that case, @code{gnutls_psk_server_get_username2()} should be used to retrieve the username. + +@strong{Returns:} the username of the peer, or @code{NULL} in case of an error, +or if the username has embedded NULLs. +@end deftypefun + +@subheading gnutls_psk_server_get_username2 +@anchor{gnutls_psk_server_get_username2} +@deftypefun {int} {gnutls_psk_server_get_username2} (gnutls_session_t @var{session}, gnutls_datum_t * @var{username}) +@var{session}: is a gnutls session + +@var{username}: a datum that will be filled in by this function + +Return a pointer to the username of the peer in the supplied datum. Does not +need to be null-terminated. + +This should only be called in case of PSK authentication and in +case of a server. + +The returned pointer should be considered constant (do not free) and valid +for the lifetime of the session. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} , or a negative value in case of an error. +@end deftypefun + +@subheading gnutls_psk_set_client_credentials +@anchor{gnutls_psk_set_client_credentials} +@deftypefun {int} {gnutls_psk_set_client_credentials} (gnutls_psk_client_credentials_t @var{res}, const char * @var{username}, const gnutls_datum_t * @var{key}, gnutls_psk_key_flags @var{flags}) +@var{res}: is a @code{gnutls_psk_client_credentials_t} type. + +@var{username}: is the user's zero-terminated userid + +@var{key}: is the user's key + +@var{flags}: indicate the format of the key, either +@code{GNUTLS_PSK_KEY_RAW} or @code{GNUTLS_PSK_KEY_HEX} . + +This function sets the username and password, in a +gnutls_psk_client_credentials_t type. Those will be used in +PSK authentication. @code{username} should be an ASCII string or UTF-8 +string. In case of a UTF-8 string it is recommended to be following +the PRECIS framework for usernames (rfc8265). The key can be either +in raw byte format or in Hex format (without the 0x prefix). + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_psk_set_client_credentials2 +@anchor{gnutls_psk_set_client_credentials2} +@deftypefun {int} {gnutls_psk_set_client_credentials2} (gnutls_psk_client_credentials_t @var{res}, const gnutls_datum_t * @var{username}, const gnutls_datum_t * @var{key}, gnutls_psk_key_flags @var{flags}) +@var{res}: is a @code{gnutls_psk_client_credentials_t} type. + +@var{username}: is the userid + +@var{key}: is the user's key + +@var{flags}: indicate the format of the key, either +@code{GNUTLS_PSK_KEY_RAW} or @code{GNUTLS_PSK_KEY_HEX} . + +This function is identical to @code{gnutls_psk_set_client_credentials()} , +except that it allows a non-null-terminated username to be introduced. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_psk_set_client_credentials_function +@anchor{gnutls_psk_set_client_credentials_function} +@deftypefun {void} {gnutls_psk_set_client_credentials_function} (gnutls_psk_client_credentials_t @var{cred}, gnutls_psk_client_credentials_function * @var{func}) +@var{cred}: is a @code{gnutls_psk_server_credentials_t} type. + +@var{func}: is the callback function + +This function can be used to set a callback to retrieve the username and +password for client PSK authentication. +The callback's function form is: +int (*callback)(gnutls_session_t, char** username, +gnutls_datum_t* key); + +The @code{username} and @code{key} ->data must be allocated using @code{gnutls_malloc()} . +The @code{username} should be an ASCII string or UTF-8 +string. In case of a UTF-8 string it is recommended to be following +the PRECIS framework for usernames (rfc8265). + +The callback function will be called once per handshake. + +The callback function should return 0 on success. +-1 indicates an error. +@end deftypefun + +@subheading gnutls_psk_set_client_credentials_function2 +@anchor{gnutls_psk_set_client_credentials_function2} +@deftypefun {void} {gnutls_psk_set_client_credentials_function2} (gnutls_psk_client_credentials_t @var{cred}, gnutls_psk_client_credentials_function2 * @var{func}) +@var{cred}: is a @code{gnutls_psk_server_credentials_t} type. + +@var{func}: is the callback function + +This function can be used to set a callback to retrieve the username and +password for client PSK authentication. +The callback's function form is: +int (*callback)(gnutls_session_t, gnutls_datum_t* username, +gnutls_datum_t* key); + +This callback function has the same semantics as that of @code{gnutls_psk_set_client_credentials_function()} , +but it allows non-string usernames to be used. + +The @code{username} and @code{key} ->data must be allocated using @code{gnutls_malloc()} . +The @code{username} should be an ASCII string or UTF-8 +string. In case of a UTF-8 string it is recommended to be following +the PRECIS framework for usernames (rfc8265). + +The callback function will be called once per handshake. + +The callback function should return 0 on success. +-1 indicates an error. +@end deftypefun + +@subheading gnutls_psk_set_params_function +@anchor{gnutls_psk_set_params_function} +@deftypefun {void} {gnutls_psk_set_params_function} (gnutls_psk_server_credentials_t @var{res}, gnutls_params_function * @var{func}) +@var{res}: is a gnutls_psk_server_credentials_t type + +@var{func}: is the function to be called + +This function will set a callback in order for the server to get +the Diffie-Hellman or RSA parameters for PSK authentication. The +callback should return @code{GNUTLS_E_SUCCESS} (0) on success. + +@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 +or later. Since 3.6.0, DH parameters are negotiated +following RFC7919. +@end deftypefun + +@subheading gnutls_psk_set_server_credentials_file +@anchor{gnutls_psk_set_server_credentials_file} +@deftypefun {int} {gnutls_psk_set_server_credentials_file} (gnutls_psk_server_credentials_t @var{res}, const char * @var{password_file}) +@var{res}: is a @code{gnutls_psk_server_credentials_t} type. + +@var{password_file}: is the PSK password file (passwd.psk) + +This function sets the password file, in a +@code{gnutls_psk_server_credentials_t} type. This password file +holds usernames and keys and will be used for PSK authentication. + +Each entry in the file consists of a username, followed by a colon +(':') and a hex-encoded key. If the username contains a colon or +any other special character, it can be hex-encoded preceded by a +'#'. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_psk_set_server_credentials_function +@anchor{gnutls_psk_set_server_credentials_function} +@deftypefun {void} {gnutls_psk_set_server_credentials_function} (gnutls_psk_server_credentials_t @var{cred}, gnutls_psk_server_credentials_function * @var{func}) +@var{cred}: is a @code{gnutls_psk_server_credentials_t} type. + +@var{func}: is the callback function + +This function can be used to set a callback to retrieve the user's PSK credentials. +The callback's function form is: +int (*callback)(gnutls_session_t, const char* username, +gnutls_datum_t* key); + + @code{username} contains the actual username. +The @code{key} must be filled in using the @code{gnutls_malloc()} . + +In case the callback returned a negative number then gnutls will +assume that the username does not exist. + +The callback function will only be called once per handshake. The +callback function should return 0 on success, while -1 indicates +an error. +@end deftypefun + +@subheading gnutls_psk_set_server_credentials_function2 +@anchor{gnutls_psk_set_server_credentials_function2} +@deftypefun {void} {gnutls_psk_set_server_credentials_function2} (gnutls_psk_server_credentials_t @var{cred}, gnutls_psk_server_credentials_function2 @var{func}) +@var{cred}: is a @code{gnutls_psk_server_credentials_t} type. + +@var{func}: is the callback function + +This function can be used to set a callback to retrieve the user's PSK credentials. +The callback's function form is: +int (*callback)(gnutls_session_t, const gnutls_datum_t* username, +gnutls_datum_t* key); + +This callback function has the same semantics as that of @code{gnutls_psk_set_server_credentials_function()} , +but it allows non-string usernames to be used. + + @code{username} contains the actual username. +The @code{key} must be filled in using the @code{gnutls_malloc()} . + +In case the callback returned a negative number then gnutls will +assume that the username does not exist. + +The callback function will only be called once per handshake. The +callback function should return 0 on success, while -1 indicates +an error. +@end deftypefun + +@subheading gnutls_psk_set_server_credentials_hint +@anchor{gnutls_psk_set_server_credentials_hint} +@deftypefun {int} {gnutls_psk_set_server_credentials_hint} (gnutls_psk_server_credentials_t @var{res}, const char * @var{hint}) +@var{res}: is a @code{gnutls_psk_server_credentials_t} type. + +@var{hint}: is the PSK identity hint string + +This function sets the identity hint, in a +@code{gnutls_psk_server_credentials_t} type. This hint is sent to +the client to help it chose a good PSK credential (i.e., username +and password). + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. + +@strong{Since:} 2.4.0 +@end deftypefun + +@subheading gnutls_psk_set_server_dh_params +@anchor{gnutls_psk_set_server_dh_params} +@deftypefun {void} {gnutls_psk_set_server_dh_params} (gnutls_psk_server_credentials_t @var{res}, gnutls_dh_params_t @var{dh_params}) +@var{res}: is a gnutls_psk_server_credentials_t type + +@var{dh_params}: is a structure that holds Diffie-Hellman parameters. + +This function will set the Diffie-Hellman parameters for an +anonymous server to use. These parameters will be used in +Diffie-Hellman exchange with PSK cipher suites. + +@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 +or later. Since 3.6.0, DH parameters are negotiated +following RFC7919. +@end deftypefun + +@subheading gnutls_psk_set_server_known_dh_params +@anchor{gnutls_psk_set_server_known_dh_params} +@deftypefun {int} {gnutls_psk_set_server_known_dh_params} (gnutls_psk_server_credentials_t @var{res}, gnutls_sec_param_t @var{sec_param}) +@var{res}: is a gnutls_psk_server_credentials_t type + +@var{sec_param}: is an option of the @code{gnutls_sec_param_t} enumeration + +This function will set the Diffie-Hellman parameters for a +PSK server to use. These parameters will be used in +Ephemeral Diffie-Hellman cipher suites and will be selected from +the FFDHE set of RFC7919 according to the security level provided. + +@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 +or later. Since 3.6.0, DH parameters are negotiated +following RFC7919. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.5.6 +@end deftypefun + +@subheading gnutls_psk_set_server_params_function +@anchor{gnutls_psk_set_server_params_function} +@deftypefun {void} {gnutls_psk_set_server_params_function} (gnutls_psk_server_credentials_t @var{res}, gnutls_params_function * @var{func}) +@var{res}: is a @code{gnutls_certificate_credentials_t} type + +@var{func}: is the function to be called + +This function will set a callback in order for the server to get +the Diffie-Hellman parameters for PSK authentication. The callback +should return @code{GNUTLS_E_SUCCESS} (0) on success. + +@strong{Deprecated:} This function is unnecessary and discouraged on GnuTLS 3.6.0 +or later. Since 3.6.0, DH parameters are negotiated +following RFC7919. +@end deftypefun + +@subheading gnutls_random_art +@anchor{gnutls_random_art} +@deftypefun {int} {gnutls_random_art} (gnutls_random_art_t @var{type}, const char * @var{key_type}, unsigned int @var{key_size}, void * @var{fpr}, size_t @var{fpr_size}, gnutls_datum_t * @var{art}) +@var{type}: The type of the random art (for now only @code{GNUTLS_RANDOM_ART_OPENSSH} is supported) + +@var{key_type}: The type of the key (RSA, DSA etc.) + +@var{key_size}: The size of the key in bits + +@var{fpr}: The fingerprint of the key + +@var{fpr_size}: The size of the fingerprint + +@var{art}: The returned random art + +This function will convert a given fingerprint to an "artistic" +image. The returned image is allocated using @code{gnutls_malloc()} , is +null-terminated but art->size will not account the terminating null. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_range_split +@anchor{gnutls_range_split} +@deftypefun {int} {gnutls_range_split} (gnutls_session_t @var{session}, const gnutls_range_st * @var{orig}, gnutls_range_st * @var{next}, gnutls_range_st * @var{remainder}) +@var{session}: is a @code{gnutls_session_t} type + +@var{orig}: is the original range provided by the user + +@var{next}: is the returned range that can be conveyed in a TLS record + +@var{remainder}: is the returned remaining range + +This function should be used when it is required to hide the length +of very long data that cannot be directly provided to @code{gnutls_record_send_range()} . +In that case this function should be called with the desired length +hiding range in @code{orig} . The returned @code{next} value should then be used in +the next call to @code{gnutls_record_send_range()} with the partial data. +That process should be repeated until @code{remainder} is (0,0). + +@strong{Returns:} 0 in case splitting succeeds, non zero in case of error. +Note that @code{orig} is not changed, while the values of @code{next} and @code{remainder} are modified to store the resulting values. +@end deftypefun + +@subheading gnutls_reauth +@anchor{gnutls_reauth} +@deftypefun {int} {gnutls_reauth} (gnutls_session_t @var{session}, unsigned int @var{flags}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{flags}: must be zero + +This function performs the post-handshake authentication +for TLS 1.3. The post-handshake authentication is initiated by the server +by calling this function. Clients respond when @code{GNUTLS_E_REAUTH_REQUEST} +has been seen while receiving data. + +The non-fatal errors expected by this function are: +@code{GNUTLS_E_INTERRUPTED} , @code{GNUTLS_E_AGAIN} , as well as +@code{GNUTLS_E_GOT_APPLICATION_DATA} when called on server side. + +The former two interrupt the authentication procedure due to the transport +layer being interrupted, and the latter because there were pending data prior +to peer initiating the re-authentication. The server should read/process that +data as unauthenticated and retry calling @code{gnutls_reauth()} . + +When this function is called under TLS1.2 or earlier or the peer didn't +advertise post-handshake auth, it always fails with +@code{GNUTLS_E_INVALID_REQUEST} . The verification of the received peers certificate +is delegated to the session or credentials verification callbacks. A +server can check whether post handshake authentication is supported +by the client by checking the session flags with @code{gnutls_session_get_flags()} . + +Prior to calling this function in server side, the function +@code{gnutls_certificate_server_set_request()} must be called setting expectations +for the received certificate (request or require). If none are set +this function will return with @code{GNUTLS_E_INVALID_REQUEST} . + +Note that post handshake authentication is available irrespective +of the initial negotiation type (PSK or certificate). In all cases +however, certificate credentials must be set to the session prior +to calling this function. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on a successful authentication, otherwise a negative error code. +@end deftypefun + +@subheading gnutls_record_can_use_length_hiding +@anchor{gnutls_record_can_use_length_hiding} +@deftypefun {unsigned} {gnutls_record_can_use_length_hiding} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +If the session supports length-hiding padding, you can +invoke @code{gnutls_record_send_range()} to send a message whose +length is hidden in the given range. If the session does not +support length hiding padding, you can use the standard +@code{gnutls_record_send()} function, or @code{gnutls_record_send_range()} +making sure that the range is the same as the length of the +message you are trying to send. + +@strong{Returns:} true (1) if the current session supports length-hiding +padding, false (0) if the current session does not. +@end deftypefun + +@subheading gnutls_record_check_corked +@anchor{gnutls_record_check_corked} +@deftypefun {size_t} {gnutls_record_check_corked} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function checks if there pending corked +data in the gnutls buffers --see @code{gnutls_record_cork()} . + +@strong{Returns:} Returns the size of the corked data or zero. + +@strong{Since:} 3.2.8 +@end deftypefun + +@subheading gnutls_record_check_pending +@anchor{gnutls_record_check_pending} +@deftypefun {size_t} {gnutls_record_check_pending} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function checks if there are unread data +in the gnutls buffers. If the return value is +non-zero the next call to @code{gnutls_record_recv()} +is guaranteed not to block. + +@strong{Returns:} Returns the size of the data or zero. +@end deftypefun + +@subheading gnutls_record_cork +@anchor{gnutls_record_cork} +@deftypefun {void} {gnutls_record_cork} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +If called, @code{gnutls_record_send()} will no longer send any records. +Any sent records will be cached until @code{gnutls_record_uncork()} is called. + +This function is safe to use with DTLS after GnuTLS 3.3.0. + +@strong{Since:} 3.1.9 +@end deftypefun + +@subheading gnutls_record_disable_padding +@anchor{gnutls_record_disable_padding} +@deftypefun {void} {gnutls_record_disable_padding} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Used to disabled padding in TLS 1.0 and above. Normally you do not +need to use this function, but there are buggy clients that +complain if a server pads the encrypted data. This of course will +disable protection against statistical attacks on the data. + +This function is defunct since 3.1.7. Random padding is disabled +by default unless requested using @code{gnutls_record_send_range()} . +@end deftypefun + +@subheading gnutls_record_discard_queued +@anchor{gnutls_record_discard_queued} +@deftypefun {size_t} {gnutls_record_discard_queued} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function discards all queued to be sent packets in a DTLS session. +These are the packets queued after an interrupted @code{gnutls_record_send()} . + +This function can only be used with transports where @code{send()} is +an all-or-nothing operation (e.g., UDP). When partial writes are allowed +this function will cause session errors. + +@strong{Returns:} The number of bytes discarded. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_record_get_direction +@anchor{gnutls_record_get_direction} +@deftypefun {int} {gnutls_record_get_direction} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function is useful to determine whether a GnuTLS function was interrupted +while sending or receiving, so that @code{select()} or @code{poll()} may be called appropriately. + +It provides information about the internals of the record +protocol and is only useful if a prior gnutls function call, +e.g. @code{gnutls_handshake()} , was interrupted and returned +@code{GNUTLS_E_INTERRUPTED} or @code{GNUTLS_E_AGAIN} . After such an interrupt +applications may call @code{select()} or @code{poll()} before restoring the +interrupted GnuTLS function. + +This function's output is unreliable if you are using the same + @code{session} in different threads for sending and receiving. + +@strong{Returns:} 0 if interrupted while trying to read data, or 1 while trying to write data. +@end deftypefun + +@subheading gnutls_record_get_max_early_data_size +@anchor{gnutls_record_get_max_early_data_size} +@deftypefun {size_t} {gnutls_record_get_max_early_data_size} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function returns the maximum early data size in this connection. +This property can only be set to servers. The client may be +provided with the maximum allowed size through the "early_data" +extension of the NewSessionTicket handshake message. + +@strong{Returns:} The maximum early data size in this connection. + +@strong{Since:} 3.6.5 +@end deftypefun + +@subheading gnutls_record_get_max_size +@anchor{gnutls_record_get_max_size} +@deftypefun {size_t} {gnutls_record_get_max_size} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Get the record size. The maximum record size is negotiated by the +client after the first handshake message. + +@strong{Returns:} The maximum record packet size in this connection. +@end deftypefun + +@subheading gnutls_record_get_state +@anchor{gnutls_record_get_state} +@deftypefun {int} {gnutls_record_get_state} (gnutls_session_t @var{session}, unsigned @var{read}, gnutls_datum_t * @var{mac_key}, gnutls_datum_t * @var{IV}, gnutls_datum_t * @var{cipher_key}, unsigned char [8] @var{seq_number}) +@var{session}: is a @code{gnutls_session_t} type + +@var{read}: if non-zero the read parameters are returned, otherwise the write + +@var{mac_key}: the key used for MAC (if a MAC is used) + +@var{IV}: the initialization vector or nonce used + +@var{cipher_key}: the cipher key + +@var{seq_number}: A 64-bit sequence number + +This function will return the parameters of the current record state. +These are only useful to be provided to an external off-loading device +or subsystem. The returned values should be considered constant +and valid for the lifetime of the session. + +In that case, to sync the state back you must call @code{gnutls_record_set_state()} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. + +Since 3.4.0 +@end deftypefun + +@subheading gnutls_record_overhead_size +@anchor{gnutls_record_overhead_size} +@deftypefun {size_t} {gnutls_record_overhead_size} (gnutls_session_t @var{session}) +@var{session}: is @code{gnutls_session_t} + +This function will return the size in bytes of the overhead +due to TLS (or DTLS) per record. On certain occasions +(e.g., CBC ciphers) the returned value is the maximum +possible overhead. + +@strong{Since:} 3.2.2 +@end deftypefun + +@subheading gnutls_record_recv +@anchor{gnutls_record_recv} +@deftypefun {ssize_t} {gnutls_record_recv} (gnutls_session_t @var{session}, void * @var{data}, size_t @var{data_size}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{data}: the buffer that the data will be read into + +@var{data_size}: the number of requested bytes + +This function has the similar semantics with @code{recv()} . The only +difference is that it accepts a GnuTLS session, and uses different +error codes. +In the special case that the peer requests a renegotiation, the +caller will receive an error code of @code{GNUTLS_E_REHANDSHAKE} . In case +of a client, this message may be simply ignored, replied with an alert +@code{GNUTLS_A_NO_RENEGOTIATION} , or replied with a new handshake, +depending on the client's will. A server receiving this error code +can only initiate a new handshake or terminate the session. + +If @code{EINTR} is returned by the internal pull function (the default +is @code{recv()} ) then @code{GNUTLS_E_INTERRUPTED} will be returned. If +@code{GNUTLS_E_INTERRUPTED} or @code{GNUTLS_E_AGAIN} is returned, you must +call this function again to get the data. See also +@code{gnutls_record_get_direction()} . + +@strong{Returns:} The number of bytes received and zero on EOF (for stream +connections). A negative error code is returned in case of an error. +The number of bytes received might be less than the requested @code{data_size} . +@end deftypefun + +@subheading gnutls_record_recv_early_data +@anchor{gnutls_record_recv_early_data} +@deftypefun {ssize_t} {gnutls_record_recv_early_data} (gnutls_session_t @var{session}, void * @var{data}, size_t @var{data_size}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{data}: the buffer that the data will be read into + +@var{data_size}: the number of requested bytes + +This function can be used by a server to retrieve data sent early +in the handshake processes when resuming a session. This is used +to implement a zero-roundtrip (0-RTT) mode. It has the same +semantics as @code{gnutls_record_recv()} . + +This function can be called either in a handshake hook, or after +the handshake is complete. + +@strong{Returns:} The number of bytes received and zero when early data +reading is complete. A negative error code is returned in case of +an error. If no early data is received during the handshake, this +function returns @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} . The +number of bytes received might be less than the requested + @code{data_size} . + +@strong{Since:} 3.6.5 +@end deftypefun + +@subheading gnutls_record_recv_packet +@anchor{gnutls_record_recv_packet} +@deftypefun {ssize_t} {gnutls_record_recv_packet} (gnutls_session_t @var{session}, gnutls_packet_t * @var{packet}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{packet}: the structure that will hold the packet data + +This is a lower-level function than @code{gnutls_record_recv()} and allows +to directly receive the whole decrypted packet. That avoids a +memory copy, and is intended to be used by applications seeking high +performance. + +The received packet is accessed using @code{gnutls_packet_get()} and +must be deinitialized using @code{gnutls_packet_deinit()} . The returned +packet will be @code{NULL} if the return value is zero (EOF). + +@strong{Returns:} The number of bytes received and zero on EOF (for stream +connections). A negative error code is returned in case of an error. + +@strong{Since:} 3.3.5 +@end deftypefun + +@subheading gnutls_record_recv_seq +@anchor{gnutls_record_recv_seq} +@deftypefun {ssize_t} {gnutls_record_recv_seq} (gnutls_session_t @var{session}, void * @var{data}, size_t @var{data_size}, unsigned char * @var{seq}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{data}: the buffer that the data will be read into + +@var{data_size}: the number of requested bytes + +@var{seq}: is the packet's 64-bit sequence number. Should have space for 8 bytes. + +This function is the same as @code{gnutls_record_recv()} , except that +it returns in addition to data, the sequence number of the data. +This is useful in DTLS where record packets might be received +out-of-order. The returned 8-byte sequence number is an +integer in big-endian format and should be +treated as a unique message identification. + +@strong{Returns:} The number of bytes received and zero on EOF. A negative +error code is returned in case of an error. The number of bytes +received might be less than @code{data_size} . + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_record_send +@anchor{gnutls_record_send} +@deftypefun {ssize_t} {gnutls_record_send} (gnutls_session_t @var{session}, const void * @var{data}, size_t @var{data_size}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{data}: contains the data to send + +@var{data_size}: is the length of the data + +This function has the similar semantics with @code{send()} . The only +difference is that it accepts a GnuTLS session, and uses different +error codes. +Note that if the send buffer is full, @code{send()} will block this +function. See the @code{send()} documentation for more information. + +You can replace the default push function which is @code{send()} , by using +@code{gnutls_transport_set_push_function()} . + +If the EINTR is returned by the internal push function +then @code{GNUTLS_E_INTERRUPTED} will be returned. If +@code{GNUTLS_E_INTERRUPTED} or @code{GNUTLS_E_AGAIN} is returned, you must +call this function again with the exact same parameters, or provide a +@code{NULL} pointer for @code{data} and 0 for @code{data_size} , in order to write the +same data as before. If you wish to discard the previous data instead +of retrying, you must call @code{gnutls_record_discard_queued()} before +calling this function with different parameters. Note that the latter +works only on special transports (e.g., UDP). +cf. @code{gnutls_record_get_direction()} . + +Note that in DTLS this function will return the @code{GNUTLS_E_LARGE_PACKET} +error code if the send data exceed the data MTU value - as returned +by @code{gnutls_dtls_get_data_mtu()} . The errno value EMSGSIZE +also maps to @code{GNUTLS_E_LARGE_PACKET} . +Note that since 3.2.13 this function can be called under cork in DTLS +mode, and will refuse to send data over the MTU size by returning +@code{GNUTLS_E_LARGE_PACKET} . + +@strong{Returns:} The number of bytes sent, or a negative error code. The +number of bytes sent might be less than @code{data_size} . The maximum +number of bytes this function can send in a single call depends +on the negotiated maximum record size. +@end deftypefun + +@subheading gnutls_record_send2 +@anchor{gnutls_record_send2} +@deftypefun {ssize_t} {gnutls_record_send2} (gnutls_session_t @var{session}, const void * @var{data}, size_t @var{data_size}, size_t @var{pad}, unsigned @var{flags}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{data}: contains the data to send + +@var{data_size}: is the length of the data + +@var{pad}: padding to be added to the record + +@var{flags}: must be zero + +This function is identical to @code{gnutls_record_send()} except that it +takes an extra argument to specify padding to be added the record. +To determine the maximum size of padding, use +@code{gnutls_record_get_max_size()} and @code{gnutls_record_overhead_size()} . + +Note that in order for GnuTLS to provide constant time processing +of padding and data in TLS1.3, the flag @code{GNUTLS_SAFE_PADDING_CHECK} +must be used in @code{gnutls_init()} . + +@strong{Returns:} The number of bytes sent, or a negative error code. The +number of bytes sent might be less than @code{data_size} . The maximum +number of bytes this function can send in a single call depends +on the negotiated maximum record size. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_record_send_early_data +@anchor{gnutls_record_send_early_data} +@deftypefun {ssize_t} {gnutls_record_send_early_data} (gnutls_session_t @var{session}, const void * @var{data}, size_t @var{data_size}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{data}: contains the data to send + +@var{data_size}: is the length of the data + +This function can be used by a client to send data early in the +handshake processes when resuming a session. This is used to +implement a zero-roundtrip (0-RTT) mode. It has the same semantics +as @code{gnutls_record_send()} . + +There may be a limit to the amount of data sent as early data. Use +@code{gnutls_record_get_max_early_data_size()} to check the limit. If the +limit exceeds, this function returns +@code{GNUTLS_E_RECORD_LIMIT_REACHED} . + +@strong{Returns:} The number of bytes sent, or a negative error code. The +number of bytes sent might be less than @code{data_size} . The maximum +number of bytes this function can send in a single call depends +on the negotiated maximum record size. + +@strong{Since:} 3.6.5 +@end deftypefun + +@subheading gnutls_record_send_file +@anchor{gnutls_record_send_file} +@deftypefun {ssize_t} {gnutls_record_send_file} (gnutls_session_t @var{session}, int @var{fd}, off_t * @var{offset}, size_t @var{count}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{fd}: file descriptor from which to read data. + +@var{offset}: Is relative to file offset, denotes the starting location for +reading. after function returns, it point to position following +last read byte. + +@var{count}: is the length of the data in bytes to be read from file and send. + +This function sends data from @code{fd} . If KTLS (kernel TLS) is enabled, it will +use the @code{sendfile()} system call to avoid overhead of copying data between user +space and the kernel. Otherwise, this functionality is merely emulated by +calling @code{read()} and @code{gnutls_record_send()} . If this implementation is +suboptimal, check whether KTLS is enabled using +@code{gnutls_transport_is_ktls_enabled()} . + +If @code{offset} is NULL then file offset is incremented by number of bytes send, +otherwise file offset remains unchanged. + +@strong{Returns:} The number of bytes sent, or a negative error code. +@end deftypefun + +@subheading gnutls_record_send_range +@anchor{gnutls_record_send_range} +@deftypefun {ssize_t} {gnutls_record_send_range} (gnutls_session_t @var{session}, const void * @var{data}, size_t @var{data_size}, const gnutls_range_st * @var{range}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{data}: contains the data to send. + +@var{data_size}: is the length of the data. + +@var{range}: is the range of lengths in which the real data length must be hidden. + +This function operates like @code{gnutls_record_send()} but, while +@code{gnutls_record_send()} adds minimal padding to each TLS record, +this function uses the TLS extra-padding feature to conceal the real +data size within the range of lengths provided. +Some TLS sessions do not support extra padding (e.g. stream ciphers in standard +TLS or SSL3 sessions). To know whether the current session supports extra +padding, and hence length hiding, use the @code{gnutls_record_can_use_length_hiding()} +function. + +@strong{Note:} This function currently is limited to blocking sockets. + +@strong{Returns:} The number of bytes sent (that is data_size in a successful invocation), +or a negative error code. +@end deftypefun + +@subheading gnutls_record_set_max_early_data_size +@anchor{gnutls_record_set_max_early_data_size} +@deftypefun {int} {gnutls_record_set_max_early_data_size} (gnutls_session_t @var{session}, size_t @var{size}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{size}: is the new size + +This function sets the maximum early data size in this connection. +This property can only be set to servers. The client may be +provided with the maximum allowed size through the "early_data" +extension of the NewSessionTicket handshake message. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +@strong{Since:} 3.6.4 +@end deftypefun + +@subheading gnutls_record_set_max_recv_size +@anchor{gnutls_record_set_max_recv_size} +@deftypefun {ssize_t} {gnutls_record_set_max_recv_size} (gnutls_session_t @var{session}, size_t @var{size}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{size}: is the new size + +This function sets the maximum amount of plaintext received in a +record in this connection. + +The limit is also negotiated through a TLS extension called 'record +size limit'. Note that while the 'record size limit' extension is +preferred, not all TLS implementations use or even understand the +extension. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +@strong{Since:} 3.6.8 +@end deftypefun + +@subheading gnutls_record_set_max_size +@anchor{gnutls_record_set_max_size} +@deftypefun {ssize_t} {gnutls_record_set_max_size} (gnutls_session_t @var{session}, size_t @var{size}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{size}: is the new size + +This function sets the maximum amount of plaintext sent and +received in a record in this connection. + +Prior to 3.6.4, this function was implemented using a TLS extension +called 'max fragment length', which limits the acceptable values to +512(=2^9), 1024(=2^10), 2048(=2^11) and 4096(=2^12). + +Since 3.6.4, the limit is also negotiated through a new TLS +extension called 'record size limit', which doesn't have the +limitation, as long as the value ranges between 512 and 16384. +Note that while the 'record size limit' extension is preferred, not +all TLS implementations use or even understand the extension. + +@strong{Deprecated:} if the client can assume that the 'record size limit' +extension is supported by the server, we recommend using +@code{gnutls_record_set_max_recv_size()} instead. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_record_set_state +@anchor{gnutls_record_set_state} +@deftypefun {int} {gnutls_record_set_state} (gnutls_session_t @var{session}, unsigned @var{read}, const unsigned char [8] @var{seq_number}) +@var{session}: is a @code{gnutls_session_t} type + +@var{read}: if non-zero the read parameters are returned, otherwise the write + +@var{seq_number}: A 64-bit sequence number + +This function will set the sequence number in the current record state. +This function is useful if sending and receiving are offloaded from +gnutls. That is, if @code{gnutls_record_get_state()} was used. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. + +Since 3.4.0 +@end deftypefun + +@subheading gnutls_record_set_timeout +@anchor{gnutls_record_set_timeout} +@deftypefun {void} {gnutls_record_set_timeout} (gnutls_session_t @var{session}, unsigned int @var{ms}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{ms}: is a timeout value in milliseconds + +This function sets the receive timeout for the record layer +to the provided value. Use an @code{ms} value of zero to disable +timeout (the default), or @code{GNUTLS_INDEFINITE_TIMEOUT} , to +set an indefinite timeout. + +This function requires to set a pull timeout callback. See +@code{gnutls_transport_set_pull_timeout_function()} . + +@strong{Since:} 3.1.7 +@end deftypefun + +@subheading gnutls_record_uncork +@anchor{gnutls_record_uncork} +@deftypefun {int} {gnutls_record_uncork} (gnutls_session_t @var{session}, unsigned int @var{flags}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{flags}: Could be zero or @code{GNUTLS_RECORD_WAIT} + +This resets the effect of @code{gnutls_record_cork()} , and flushes any pending +data. If the @code{GNUTLS_RECORD_WAIT} flag is specified then this +function will block until the data is sent or a fatal error +occurs (i.e., the function will retry on @code{GNUTLS_E_AGAIN} and +@code{GNUTLS_E_INTERRUPTED} ). + +If the flag @code{GNUTLS_RECORD_WAIT} is not specified and the function +is interrupted then the @code{GNUTLS_E_AGAIN} or @code{GNUTLS_E_INTERRUPTED} +errors will be returned. To obtain the data left in the corked +buffer use @code{gnutls_record_check_corked()} . + +@strong{Returns:} On success the number of transmitted data is returned, or +otherwise a negative error code. + +@strong{Since:} 3.1.9 +@end deftypefun + +@subheading gnutls_rehandshake +@anchor{gnutls_rehandshake} +@deftypefun {int} {gnutls_rehandshake} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function can only be called in server side, and +instructs a TLS 1.2 or earlier client to renegotiate +parameters (perform a handshake), by sending a +hello request message. + +If this function succeeds, the calling application +should call @code{gnutls_record_recv()} until @code{GNUTLS_E_REHANDSHAKE} +is returned to clear any pending data. If the @code{GNUTLS_E_REHANDSHAKE} +error code is not seen, then the handshake request was +not followed by the peer (the TLS protocol does not require +the client to do, and such compliance should be handled +by the application protocol). + +Once the @code{GNUTLS_E_REHANDSHAKE} error code is seen, the +calling application should proceed to calling +@code{gnutls_handshake()} to negotiate the new +parameters. + +If the client does not wish to renegotiate parameters he +may reply with an alert message, and in that case the return code seen +by subsequent @code{gnutls_record_recv()} will be +@code{GNUTLS_E_WARNING_ALERT_RECEIVED} with the specific alert being +@code{GNUTLS_A_NO_RENEGOTIATION} . A client may also choose to ignore +this request. + +Under TLS 1.3 this function is equivalent to @code{gnutls_session_key_update()} +with the @code{GNUTLS_KU_PEER} flag. In that case subsequent calls to +@code{gnutls_record_recv()} will not return @code{GNUTLS_E_REHANDSHAKE} , and +calls to @code{gnutls_handshake()} in server side are a no-op. + +This function always fails with @code{GNUTLS_E_INVALID_REQUEST} when +called in client side. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. +@end deftypefun + +@subheading gnutls_safe_renegotiation_status +@anchor{gnutls_safe_renegotiation_status} +@deftypefun {unsigned} {gnutls_safe_renegotiation_status} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Can be used to check whether safe renegotiation is being used +in the current session. + +@strong{Returns:} 0 when safe renegotiation is not used and non (0) when +safe renegotiation is used. + +@strong{Since:} 2.10.0 +@end deftypefun + +@subheading gnutls_sec_param_get_name +@anchor{gnutls_sec_param_get_name} +@deftypefun {const char *} {gnutls_sec_param_get_name} (gnutls_sec_param_t @var{param}) +@var{param}: is a security parameter + +Convert a @code{gnutls_sec_param_t} value to a string. + +@strong{Returns:} a pointer to a string that contains the name of the +specified security level, or @code{NULL} . + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_sec_param_to_pk_bits +@anchor{gnutls_sec_param_to_pk_bits} +@deftypefun {unsigned int} {gnutls_sec_param_to_pk_bits} (gnutls_pk_algorithm_t @var{algo}, gnutls_sec_param_t @var{param}) +@var{algo}: is a public key algorithm + +@var{param}: is a security parameter + +When generating private and public key pairs a difficult question +is which size of "bits" the modulus will be in RSA and the group size +in DSA. The easy answer is 1024, which is also wrong. This function +will convert a human understandable security parameter to an +appropriate size for the specific algorithm. + +@strong{Returns:} The number of bits, or (0). + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_sec_param_to_symmetric_bits +@anchor{gnutls_sec_param_to_symmetric_bits} +@deftypefun {unsigned int} {gnutls_sec_param_to_symmetric_bits} (gnutls_sec_param_t @var{param}) +@var{param}: is a security parameter + +This function will return the number of bits that correspond to +symmetric cipher strength for the given security parameter. + +@strong{Returns:} The number of bits, or (0). + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_server_name_get +@anchor{gnutls_server_name_get} +@deftypefun {int} {gnutls_server_name_get} (gnutls_session_t @var{session}, void * @var{data}, size_t * @var{data_length}, unsigned int * @var{type}, unsigned int @var{indx}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{data}: will hold the data + +@var{data_length}: will hold the data length. Must hold the maximum size of data. + +@var{type}: will hold the server name indicator type + +@var{indx}: is the index of the server_name + +This function will allow you to get the name indication (if any), a +client has sent. The name indication may be any of the enumeration +gnutls_server_name_type_t. + +If @code{type} is GNUTLS_NAME_DNS, then this function is to be used by +servers that support virtual hosting, and the data will be a null +terminated IDNA ACE string (prior to GnuTLS 3.4.0 it was a UTF-8 string). + +If @code{data} has not enough size to hold the server name +GNUTLS_E_SHORT_MEMORY_BUFFER is returned, and @code{data_length} will +hold the required size. + + @code{indx} is used to retrieve more than one server names (if sent by +the client). The first server name has an index of 0, the second 1 +and so on. If no name with the given index exists +GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE is returned. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, on UTF-8 +decoding error @code{GNUTLS_E_IDNA_ERROR} is returned, otherwise a negative +error code is returned. +@end deftypefun + +@subheading gnutls_server_name_set +@anchor{gnutls_server_name_set} +@deftypefun {int} {gnutls_server_name_set} (gnutls_session_t @var{session}, gnutls_server_name_type_t @var{type}, const void * @var{name}, size_t @var{name_length}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{type}: specifies the indicator type + +@var{name}: is a string that contains the server name. + +@var{name_length}: holds the length of name excluding the terminating null byte + +This function is to be used by clients that want to inform (via a +TLS extension mechanism) the server of the name they connected to. +This should be used by clients that connect to servers that do +virtual hosting. + +The value of @code{name} depends on the @code{type} type. In case of +@code{GNUTLS_NAME_DNS} , a UTF-8 null-terminated domain name string, +without the trailing dot, is expected. + +IPv4 or IPv6 addresses are not permitted to be set by this function. +If the function is called with a name of @code{name_length} zero it will clear +all server names set. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. +@end deftypefun + +@subheading gnutls_session_channel_binding +@anchor{gnutls_session_channel_binding} +@deftypefun {int} {gnutls_session_channel_binding} (gnutls_session_t @var{session}, gnutls_channel_binding_t @var{cbtype}, gnutls_datum_t * @var{cb}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{cbtype}: an @code{gnutls_channel_binding_t} enumeration type + +@var{cb}: output buffer array with data + +Extract given channel binding data of the @code{cbtype} (e.g., +@code{GNUTLS_CB_TLS_UNIQUE} ) type. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, +@code{GNUTLS_E_UNIMPLEMENTED_FEATURE} if the @code{cbtype} is unsupported, +@code{GNUTLS_E_CHANNEL_BINDING_NOT_AVAILABLE} if the data is not +currently available, or an error code. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_session_enable_compatibility_mode +@anchor{gnutls_session_enable_compatibility_mode} +@deftypefun {void} {gnutls_session_enable_compatibility_mode} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function can be used to disable certain (security) features in +TLS in order to maintain maximum compatibility with buggy +clients. Because several trade-offs with security are enabled, +if required they will be reported through the audit subsystem. + +Normally only servers that require maximum compatibility with +everything out there, need to call this function. + +Note that this function must be called after any call to gnutls_priority +functions. + +@strong{Since:} 2.1.4 +@end deftypefun + +@subheading gnutls_session_etm_status +@anchor{gnutls_session_etm_status} +@deftypefun {unsigned} {gnutls_session_etm_status} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Get the status of the encrypt-then-mac extension negotiation. +This is in accordance to rfc7366 + +@strong{Returns:} Non-zero if the negotiation was successful or zero otherwise. +@end deftypefun + +@subheading gnutls_session_ext_master_secret_status +@anchor{gnutls_session_ext_master_secret_status} +@deftypefun {unsigned} {gnutls_session_ext_master_secret_status} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Get the status of the extended master secret extension negotiation. +This is in accordance to RFC7627. That information is also +available to the more generic @code{gnutls_session_get_flags()} . + +@strong{Returns:} Non-zero if the negotiation was successful or zero otherwise. +@end deftypefun + +@subheading gnutls_session_ext_register +@anchor{gnutls_session_ext_register} +@deftypefun {int} {gnutls_session_ext_register} (gnutls_session_t @var{session}, const char * @var{name}, int @var{id}, gnutls_ext_parse_type_t @var{parse_point}, gnutls_ext_recv_func @var{recv_func}, gnutls_ext_send_func @var{send_func}, gnutls_ext_deinit_data_func @var{deinit_func}, gnutls_ext_pack_func @var{pack_func}, gnutls_ext_unpack_func @var{unpack_func}, unsigned @var{flags}) +@var{session}: the session for which this extension will be set + +@var{name}: the name of the extension to register + +@var{id}: the numeric id of the extension + +@var{parse_point}: the parse type of the extension (see gnutls_ext_parse_type_t) + +@var{recv_func}: a function to receive the data + +@var{send_func}: a function to send the data + +@var{deinit_func}: a function deinitialize any private data + +@var{pack_func}: a function which serializes the extension's private data (used on session packing for resumption) + +@var{unpack_func}: a function which will deserialize the extension's private data + +@var{flags}: must be zero or flags from @code{gnutls_ext_flags_t} + +This function will register a new extension type. The extension will be +only usable within the registered session. If the extension type +is already registered then @code{GNUTLS_E_ALREADY_REGISTERED} will be returned, +unless the flag @code{GNUTLS_EXT_FLAG_OVERRIDE_INTERNAL} is specified. The latter +flag when specified can be used to override certain extensions introduced +after 3.6.0. It is expected to be used by applications which handle +custom extensions that are not currently supported in GnuTLS, but direct +support for them may be added in the future. + +Each registered extension can store temporary data into the gnutls_session_t +structure using @code{gnutls_ext_set_data()} , and they can be retrieved using +@code{gnutls_ext_get_data()} . + +The validity of the extension registered can be given by the appropriate flags +of @code{gnutls_ext_flags_t} . If no validity is given, then the registered extension +will be valid for client and TLS1.2 server hello (or encrypted extensions for TLS1.3). + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +@strong{Since:} 3.5.5 +@end deftypefun + +@subheading gnutls_session_force_valid +@anchor{gnutls_session_force_valid} +@deftypefun {void} {gnutls_session_force_valid} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Clears the invalid flag in a session. That means +that sessions were corrupt or invalid data were received +can be re-used. Use only when debugging or experimenting +with the TLS protocol. Should not be used in typical +applications. +@end deftypefun + +@subheading gnutls_session_get_data +@anchor{gnutls_session_get_data} +@deftypefun {int} {gnutls_session_get_data} (gnutls_session_t @var{session}, void * @var{session_data}, size_t * @var{session_data_size}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{session_data}: is a pointer to space to hold the session. + +@var{session_data_size}: is the session_data's size, or it will be set by the function. + +Returns all session parameters needed to be stored to support resumption, +in a pre-allocated buffer. + +See @code{gnutls_session_get_data2()} for more information. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_session_get_data2 +@anchor{gnutls_session_get_data2} +@deftypefun {int} {gnutls_session_get_data2} (gnutls_session_t @var{session}, gnutls_datum_t * @var{data}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{data}: is a pointer to a datum that will hold the session. + +Returns necessary parameters to support resumption. The client +should call this function and store the returned session data. A session +can be resumed later by calling @code{gnutls_session_set_data()} with the returned +data. Note that under TLS 1.3, it is recommended for clients to use +session parameters only once, to prevent passive-observers from correlating +the different connections. + +The returned @code{data} are allocated and must be released using @code{gnutls_free()} . + +This function will fail if called prior to handshake completion. In +case of false start TLS, the handshake completes only after data have +been successfully received from the peer. + +Under TLS1.3 session resumption is possible only after a session ticket +is received by the client. To ensure that such a ticket has been received use +@code{gnutls_session_get_flags()} and check for flag @code{GNUTLS_SFLAGS_SESSION_TICKET} ; +if this flag is not set, this function will wait for a new ticket within +an estimated roundtrip, and if not received will return dummy data which +cannot lead to resumption. + +To get notified when new tickets are received by the server +use @code{gnutls_handshake_set_hook_function()} to wait for @code{GNUTLS_HANDSHAKE_NEW_SESSION_TICKET} +messages. Each call of @code{gnutls_session_get_data2()} after a ticket is +received, will return session resumption data corresponding to the last +received ticket. + +Note that this function under TLS1.3 requires a callback to be set with +@code{gnutls_transport_set_pull_timeout_function()} for successful operation. There +was a bug before 3.6.10 which could make this function fail if that callback +was not set. On later versions if not set, the function will return a successful +error code, but will return dummy data that cannot lead to a resumption. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_session_get_desc +@anchor{gnutls_session_get_desc} +@deftypefun {char *} {gnutls_session_get_desc} (gnutls_session_t @var{session}) +@var{session}: is a gnutls session + +This function returns a string describing the current session. +The string is null terminated and allocated using @code{gnutls_malloc()} . + +If initial negotiation is not complete when this function is called, +@code{NULL} will be returned. + +@strong{Returns:} a description of the protocols and algorithms in the current session. + +@strong{Since:} 3.1.10 +@end deftypefun + +@subheading gnutls_session_get_flags +@anchor{gnutls_session_get_flags} +@deftypefun {unsigned} {gnutls_session_get_flags} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +This function will return a series (ORed) of flags, applicable +for the current session. + +This replaces individual informational functions such as +@code{gnutls_safe_renegotiation_status()} , @code{gnutls_session_ext_master_secret_status()} , +etc. + +@strong{Returns:} An ORed sequence of flags (see @code{gnutls_session_flags_t} ) + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_session_get_id +@anchor{gnutls_session_get_id} +@deftypefun {int} {gnutls_session_get_id} (gnutls_session_t @var{session}, void * @var{session_id}, size_t * @var{session_id_size}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{session_id}: is a pointer to space to hold the session id. + +@var{session_id_size}: initially should contain the maximum @code{session_id} size and will be updated. + +Returns the TLS session identifier. The session ID is selected by the +server, and in older versions of TLS was a unique identifier shared +between client and server which was persistent across resumption. +In the latest version of TLS (1.3) or TLS with session tickets, the +notion of session identifiers is undefined and cannot be relied for uniquely +identifying sessions across client and server. + +In client side this function returns the identifier returned by the +server, and cannot be assumed to have any relation to session resumption. +In server side this function is guaranteed to return a persistent +identifier of the session since GnuTLS 3.6.4, which may not necessarily +map into the TLS session ID value. Prior to that version the value +could only be considered a persistent identifier, under TLS1.2 or earlier +and when no session tickets were in use. + +The session identifier value returned is always less than +@code{GNUTLS_MAX_SESSION_ID_SIZE} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_session_get_id2 +@anchor{gnutls_session_get_id2} +@deftypefun {int} {gnutls_session_get_id2} (gnutls_session_t @var{session}, gnutls_datum_t * @var{session_id}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{session_id}: will point to the session ID. + +Returns the TLS session identifier. The session ID is selected by the +server, and in older versions of TLS was a unique identifier shared +between client and server which was persistent across resumption. +In the latest version of TLS (1.3) or TLS 1.2 with session tickets, the +notion of session identifiers is undefined and cannot be relied for uniquely +identifying sessions across client and server. + +In client side this function returns the identifier returned by the +server, and cannot be assumed to have any relation to session resumption. +In server side this function is guaranteed to return a persistent +identifier of the session since GnuTLS 3.6.4, which may not necessarily +map into the TLS session ID value. Prior to that version the value +could only be considered a persistent identifier, under TLS1.2 or earlier +and when no session tickets were in use. + +The session identifier value returned is always less than +@code{GNUTLS_MAX_SESSION_ID_SIZE} and should be treated as constant. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. + +@strong{Since:} 3.1.4 +@end deftypefun + +@subheading gnutls_session_get_keylog_function +@anchor{gnutls_session_get_keylog_function} +@deftypefun {gnutls_keylog_func} {gnutls_session_get_keylog_function} (const gnutls_session_t @var{session}) +@var{session}: is @code{gnutls_session_t} type + +This function will return the callback function set using +@code{gnutls_session_set_keylog_function()} . + +@strong{Returns:} The function set or @code{NULL} otherwise. + +@strong{Since:} 3.6.13 +@end deftypefun + +@subheading gnutls_session_get_master_secret +@anchor{gnutls_session_get_master_secret} +@deftypefun {void} {gnutls_session_get_master_secret} (gnutls_session_t @var{session}, gnutls_datum_t * @var{secret}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{secret}: the session's master secret + +This function returns pointers to the master secret +used in the TLS session. The pointers are not to be modified or deallocated. + +This function is only applicable under TLS 1.2 or earlier versions. + +@strong{Since:} 3.5.0 +@end deftypefun + +@subheading gnutls_session_get_ptr +@anchor{gnutls_session_get_ptr} +@deftypefun {void *} {gnutls_session_get_ptr} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Get user pointer for session. Useful in callbacks. This is the +pointer set with @code{gnutls_session_set_ptr()} . + +@strong{Returns:} the user given pointer from the session structure, or +@code{NULL} if it was never set. +@end deftypefun + +@subheading gnutls_session_get_random +@anchor{gnutls_session_get_random} +@deftypefun {void} {gnutls_session_get_random} (gnutls_session_t @var{session}, gnutls_datum_t * @var{client}, gnutls_datum_t * @var{server}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{client}: the client part of the random + +@var{server}: the server part of the random + +This function returns pointers to the client and server +random fields used in the TLS handshake. The pointers are +not to be modified or deallocated. + +If a client random value has not yet been established, the output +will be garbage. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_session_get_verify_cert_status +@anchor{gnutls_session_get_verify_cert_status} +@deftypefun {unsigned int} {gnutls_session_get_verify_cert_status} (gnutls_session_t @var{session}) +@var{session}: is a gnutls session + +This function returns the status of the verification when initiated +via auto-verification, i.e., by @code{gnutls_session_set_verify_cert2()} or +@code{gnutls_session_set_verify_cert()} . If no certificate verification +was occurred then the return value would be set to ((unsigned int)-1). + +The certificate verification status is the same as in @code{gnutls_certificate_verify_peers()} . + +@strong{Returns:} the certificate verification status. + +@strong{Since:} 3.4.6 +@end deftypefun + +@subheading gnutls_session_is_resumed +@anchor{gnutls_session_is_resumed} +@deftypefun {int} {gnutls_session_is_resumed} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Checks whether session is resumed or not. This is functional +for both server and client side. + +@strong{Returns:} non zero if this session is resumed, or a zero if this is +a new session. +@end deftypefun + +@subheading gnutls_session_key_update +@anchor{gnutls_session_key_update} +@deftypefun {int} {gnutls_session_key_update} (gnutls_session_t @var{session}, unsigned @var{flags}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{flags}: zero of @code{GNUTLS_KU_PEER} + +This function will update/refresh the session keys when the +TLS protocol is 1.3 or better. The peer is notified of the +update by sending a message, so this function should be +treated similarly to @code{gnutls_record_send()} --i.e., it may +return @code{GNUTLS_E_AGAIN} or @code{GNUTLS_E_INTERRUPTED} . + +When this flag @code{GNUTLS_KU_PEER} is specified, this function +in addition to updating the local keys, will ask the peer to +refresh its keys too. + +If the negotiated version is not TLS 1.3 or better this +function will return @code{GNUTLS_E_INVALID_REQUEST} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_session_resumption_requested +@anchor{gnutls_session_resumption_requested} +@deftypefun {int} {gnutls_session_resumption_requested} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Check whether the client has asked for session resumption. +This function is valid only on server side. + +@strong{Returns:} non zero if session resumption was asked, or a zero if not. +@end deftypefun + +@subheading gnutls_session_set_data +@anchor{gnutls_session_set_data} +@deftypefun {int} {gnutls_session_set_data} (gnutls_session_t @var{session}, const void * @var{session_data}, size_t @var{session_data_size}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{session_data}: is a pointer to space to hold the session. + +@var{session_data_size}: is the session's size + +Sets all session parameters, in order to resume a previously +established session. The session data given must be the one +returned by @code{gnutls_session_get_data()} . This function should be +called before @code{gnutls_handshake()} . + +Keep in mind that session resuming is advisory. The server may +choose not to resume the session, thus a full handshake will be +performed. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_session_set_id +@anchor{gnutls_session_set_id} +@deftypefun {int} {gnutls_session_set_id} (gnutls_session_t @var{session}, const gnutls_datum_t * @var{sid}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{sid}: the session identifier + +This function sets the session ID to be used in a client hello. +This is a function intended for exceptional uses. Do not use this +function unless you are implementing a custom protocol. + +To set session resumption parameters use @code{gnutls_session_set_data()} instead. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. + +@strong{Since:} 3.2.1 +@end deftypefun + +@subheading gnutls_session_set_keylog_function +@anchor{gnutls_session_set_keylog_function} +@deftypefun {void} {gnutls_session_set_keylog_function} (gnutls_session_t @var{session}, gnutls_keylog_func @var{func}) +@var{session}: is @code{gnutls_session_t} type + +@var{func}: is the function to be called + +This function will set a callback to be called when a new secret is +derived and installed during handshake. + +@strong{Since:} 3.6.13 +@end deftypefun + +@subheading gnutls_session_set_premaster +@anchor{gnutls_session_set_premaster} +@deftypefun {int} {gnutls_session_set_premaster} (gnutls_session_t @var{session}, unsigned int @var{entity}, gnutls_protocol_t @var{version}, gnutls_kx_algorithm_t @var{kx}, gnutls_cipher_algorithm_t @var{cipher}, gnutls_mac_algorithm_t @var{mac}, gnutls_compression_method_t @var{comp}, const gnutls_datum_t * @var{master}, const gnutls_datum_t * @var{session_id}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{entity}: GNUTLS_SERVER or GNUTLS_CLIENT + +@var{version}: the TLS protocol version + +@var{kx}: the key exchange method + +@var{cipher}: the cipher + +@var{mac}: the MAC algorithm + +@var{comp}: the compression method (ignored) + +@var{master}: the master key to use + +@var{session_id}: the session identifier + +This function sets the premaster secret in a session. This is +a function intended for exceptional uses. Do not use this +function unless you are implementing a legacy protocol. +Use @code{gnutls_session_set_data()} instead. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. +@end deftypefun + +@subheading gnutls_session_set_ptr +@anchor{gnutls_session_set_ptr} +@deftypefun {void} {gnutls_session_set_ptr} (gnutls_session_t @var{session}, void * @var{ptr}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{ptr}: is the user pointer + +This function will set (associate) the user given pointer @code{ptr} to +the session structure. This pointer can be accessed with +@code{gnutls_session_get_ptr()} . +@end deftypefun + +@subheading gnutls_session_set_verify_cert +@anchor{gnutls_session_set_verify_cert} +@deftypefun {void} {gnutls_session_set_verify_cert} (gnutls_session_t @var{session}, const char * @var{hostname}, unsigned @var{flags}) +@var{session}: is a gnutls session + +@var{hostname}: is the expected name of the peer; may be @code{NULL} + +@var{flags}: flags for certificate verification -- @code{gnutls_certificate_verify_flags} + +This function instructs GnuTLS to verify the peer's certificate +using the provided hostname. If the verification fails the handshake +will also fail with @code{GNUTLS_E_CERTIFICATE_VERIFICATION_ERROR} . In that +case the verification result can be obtained using @code{gnutls_session_get_verify_cert_status()} . + +The @code{hostname} pointer provided must remain valid for the lifetime +of the session. More precisely it should be available during any subsequent +handshakes. If no hostname is provided, no hostname verification +will be performed. For a more advanced verification function check +@code{gnutls_session_set_verify_cert2()} . + +If @code{flags} is provided which contain a profile, this function should be +called after any session priority setting functions. + +The @code{gnutls_session_set_verify_cert()} function is intended to be used by TLS +clients to verify the server's certificate. + +@strong{Since:} 3.4.6 +@end deftypefun + +@subheading gnutls_session_set_verify_cert2 +@anchor{gnutls_session_set_verify_cert2} +@deftypefun {void} {gnutls_session_set_verify_cert2} (gnutls_session_t @var{session}, gnutls_typed_vdata_st * @var{data}, unsigned @var{elements}, unsigned @var{flags}) +@var{session}: is a gnutls session + +@var{data}: an array of typed data + +@var{elements}: the number of data elements + +@var{flags}: flags for certificate verification -- @code{gnutls_certificate_verify_flags} + +This function instructs GnuTLS to verify the peer's certificate +using the provided typed data information. If the verification fails the handshake +will also fail with @code{GNUTLS_E_CERTIFICATE_VERIFICATION_ERROR} . In that +case the verification result can be obtained using @code{gnutls_session_get_verify_cert_status()} . + +The acceptable typed data are the same as in @code{gnutls_certificate_verify_peers()} , +and once set must remain valid for the lifetime of the session. More precisely +they should be available during any subsequent handshakes. + +If @code{flags} is provided which contain a profile, this function should be +called after any session priority setting functions. + +@strong{Since:} 3.4.6 +@end deftypefun + +@subheading gnutls_session_set_verify_function +@anchor{gnutls_session_set_verify_function} +@deftypefun {void} {gnutls_session_set_verify_function} (gnutls_session_t @var{session}, gnutls_certificate_verify_function * @var{func}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{func}: is the callback function + +This function sets a callback to be called when peer's certificate +has been received in order to verify it on receipt rather than +doing after the handshake is completed. This overrides any callback +set using @code{gnutls_certificate_set_verify_function()} . + +The callback's function prototype is: +int (*callback)(gnutls_session_t); + +If the callback function is provided then gnutls will call it, in the +handshake, just after the certificate message has been received. +To verify or obtain the certificate the @code{gnutls_certificate_verify_peers2()} , +@code{gnutls_certificate_type_get()} , @code{gnutls_certificate_get_peers()} functions +can be used. + +The callback function should return 0 for the handshake to continue +or non-zero to terminate. + +@strong{Since:} 3.4.6 +@end deftypefun + +@subheading gnutls_session_supplemental_register +@anchor{gnutls_session_supplemental_register} +@deftypefun {int} {gnutls_session_supplemental_register} (gnutls_session_t @var{session}, const char * @var{name}, gnutls_supplemental_data_format_type_t @var{type}, gnutls_supp_recv_func @var{recv_func}, gnutls_supp_send_func @var{send_func}, unsigned @var{flags}) +@var{session}: the session for which this will be registered + +@var{name}: the name of the supplemental data to register + +@var{type}: the type of the supplemental data format + +@var{recv_func}: the function to receive the data + +@var{send_func}: the function to send the data + +@var{flags}: must be zero + +This function will register a new supplemental data type (rfc4680). +The registered supplemental functions will be used for that specific +session. The provided @code{type} must be an unassigned type in +@code{gnutls_supplemental_data_format_type_t} . + +If the type is already registered or handled by GnuTLS internally +@code{GNUTLS_E_ALREADY_REGISTERED} will be returned. + +As supplemental data are not defined under TLS 1.3, this function will +disable TLS 1.3 support for the given session. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +@strong{Since:} 3.5.5 +@end deftypefun + +@subheading gnutls_session_ticket_enable_client +@anchor{gnutls_session_ticket_enable_client} +@deftypefun {int} {gnutls_session_ticket_enable_client} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Request that the client should attempt session resumption using +SessionTicket. This call is typically unnecessary as session +tickets are enabled by default. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an +error code. + +@strong{Since:} 2.10.0 +@end deftypefun + +@subheading gnutls_session_ticket_enable_server +@anchor{gnutls_session_ticket_enable_server} +@deftypefun {int} {gnutls_session_ticket_enable_server} (gnutls_session_t @var{session}, const gnutls_datum_t * @var{key}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{key}: key to encrypt session parameters. + +Request that the server should attempt session resumption using +session tickets, i.e., by delegating storage to the client. + @code{key} must be initialized using @code{gnutls_session_ticket_key_generate()} . +To avoid leaking that key, use @code{gnutls_memset()} prior to +releasing it. + +The default ticket expiration time can be overridden using +@code{gnutls_db_set_cache_expiration()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an +error code. + +@strong{Since:} 2.10.0 +@end deftypefun + +@subheading gnutls_session_ticket_key_generate +@anchor{gnutls_session_ticket_key_generate} +@deftypefun {int} {gnutls_session_ticket_key_generate} (gnutls_datum_t * @var{key}) +@var{key}: is a pointer to a @code{gnutls_datum_t} which will contain a newly +created key. + +Generate a random key to encrypt security parameters within +SessionTicket. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an +error code. + +@strong{Since:} 2.10.0 +@end deftypefun + +@subheading gnutls_session_ticket_send +@anchor{gnutls_session_ticket_send} +@deftypefun {int} {gnutls_session_ticket_send} (gnutls_session_t @var{session}, unsigned @var{nr}, unsigned @var{flags}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{nr}: the number of tickets to send + +@var{flags}: must be zero + +Sends a fresh session ticket to the peer. This is relevant only +in server side under TLS1.3. This function may also return @code{GNUTLS_E_AGAIN} +or @code{GNUTLS_E_INTERRUPTED} and in that case it must be called again. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or a negative error code. +@end deftypefun + +@subheading gnutls_set_default_priority +@anchor{gnutls_set_default_priority} +@deftypefun {int} {gnutls_set_default_priority} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Sets the default priority on the ciphers, key exchange methods, +and macs. This is the recommended method of +setting the defaults, in order to promote consistency between applications +using GnuTLS, and to allow GnuTLS using applications to update settings +in par with the library. For client applications which require +maximum compatibility consider calling @code{gnutls_session_enable_compatibility_mode()} +after this function. + +For an application to specify additional options to priority string +consider using @code{gnutls_set_default_priority_append()} . + +To allow a user to override the defaults (e.g., when a user interface +or configuration file is available), the functions +@code{gnutls_priority_set_direct()} or @code{gnutls_priority_set()} can +be used. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. + +@strong{Since:} 2.1.4 +@end deftypefun + +@subheading gnutls_set_default_priority_append +@anchor{gnutls_set_default_priority_append} +@deftypefun {int} {gnutls_set_default_priority_append} (gnutls_session_t @var{session}, const char * @var{add_prio}, const char ** @var{err_pos}, unsigned @var{flags}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{add_prio}: is a string describing priorities to be appended to default + +@var{err_pos}: In case of an error this will have the position in the string the error occurred + +@var{flags}: must be zero + +Sets the default priority on the ciphers, key exchange methods, +and macs with the additional options in @code{add_prio} . This is the recommended method of +setting the defaults when only few additional options are to be added. This promotes +consistency between applications using GnuTLS, and allows GnuTLS using applications +to update settings in par with the library. + +The @code{add_prio} string should start as a normal priority string, e.g., +'-VERS-TLS-ALL:+VERS-TLS1.3:%COMPAT' or '%FORCE_ETM'. That is, it must not start +with ':'. + +To allow a user to override the defaults (e.g., when a user interface +or configuration file is available), the functions +@code{gnutls_priority_set_direct()} or @code{gnutls_priority_set()} can +be used. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, or an error code. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_sign_algorithm_get +@anchor{gnutls_sign_algorithm_get} +@deftypefun {int} {gnutls_sign_algorithm_get} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Returns the signature algorithm that is (or will be) used in this +session by the server to sign data. This function should be +used only with TLS 1.2 or later. + +@strong{Returns:} The sign algorithm or @code{GNUTLS_SIGN_UNKNOWN} . + +@strong{Since:} 3.1.1 +@end deftypefun + +@subheading gnutls_sign_algorithm_get_client +@anchor{gnutls_sign_algorithm_get_client} +@deftypefun {int} {gnutls_sign_algorithm_get_client} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Returns the signature algorithm that is (or will be) used in this +session by the client to sign data. This function should be +used only with TLS 1.2 or later. + +@strong{Returns:} The sign algorithm or @code{GNUTLS_SIGN_UNKNOWN} . + +@strong{Since:} 3.1.11 +@end deftypefun + +@subheading gnutls_sign_algorithm_get_requested +@anchor{gnutls_sign_algorithm_get_requested} +@deftypefun {int} {gnutls_sign_algorithm_get_requested} (gnutls_session_t @var{session}, size_t @var{indx}, gnutls_sign_algorithm_t * @var{algo}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{indx}: is an index of the signature algorithm to return + +@var{algo}: the returned certificate type will be stored there + +Returns the signature algorithm specified by index that was +requested by the peer. If the specified index has no data available +this function returns @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} . If +the negotiated TLS version does not support signature algorithms +then @code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} will be returned even +for the first index. The first index is 0. + +This function is useful in the certificate callback functions +to assist in selecting the correct certificate. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise +an error code is returned. + +@strong{Since:} 2.10.0 +@end deftypefun + +@subheading gnutls_sign_get_hash_algorithm +@anchor{gnutls_sign_get_hash_algorithm} +@deftypefun {gnutls_digest_algorithm_t} {gnutls_sign_get_hash_algorithm} (gnutls_sign_algorithm_t @var{sign}) +@var{sign}: is a signature algorithm + +This function returns the digest algorithm corresponding to +the given signature algorithms. + +@strong{Since:} 3.1.1 + +@strong{Returns:} return a @code{gnutls_digest_algorithm_t} value, or @code{GNUTLS_DIG_UNKNOWN} on error. +@end deftypefun + +@subheading gnutls_sign_get_id +@anchor{gnutls_sign_get_id} +@deftypefun {gnutls_sign_algorithm_t} {gnutls_sign_get_id} (const char * @var{name}) +@var{name}: is a sign algorithm name + +The names are compared in a case insensitive way. + +@strong{Returns:} return a @code{gnutls_sign_algorithm_t} value corresponding to +the specified algorithm, or @code{GNUTLS_SIGN_UNKNOWN} on error. +@end deftypefun + +@subheading gnutls_sign_get_name +@anchor{gnutls_sign_get_name} +@deftypefun {const char *} {gnutls_sign_get_name} (gnutls_sign_algorithm_t @var{algorithm}) +@var{algorithm}: is a sign algorithm + +Convert a @code{gnutls_sign_algorithm_t} value to a string. + +@strong{Returns:} a string that contains the name of the specified sign +algorithm, or @code{NULL} . +@end deftypefun + +@subheading gnutls_sign_get_oid +@anchor{gnutls_sign_get_oid} +@deftypefun {const char *} {gnutls_sign_get_oid} (gnutls_sign_algorithm_t @var{sign}) +@var{sign}: is a sign algorithm + +Convert a @code{gnutls_sign_algorithm_t} value to its object identifier. + +@strong{Returns:} a string that contains the object identifier of the specified sign +algorithm, or @code{NULL} . + +@strong{Since:} 3.4.3 +@end deftypefun + +@subheading gnutls_sign_get_pk_algorithm +@anchor{gnutls_sign_get_pk_algorithm} +@deftypefun {gnutls_pk_algorithm_t} {gnutls_sign_get_pk_algorithm} (gnutls_sign_algorithm_t @var{sign}) +@var{sign}: is a signature algorithm + +This function returns the public key algorithm corresponding to +the given signature algorithms. Note that there may be multiple +public key algorithms supporting a particular signature type; +when dealing with such algorithms use instead @code{gnutls_sign_supports_pk_algorithm()} . + +@strong{Since:} 3.1.1 + +@strong{Returns:} return a @code{gnutls_pk_algorithm_t} value, or @code{GNUTLS_PK_UNKNOWN} on error. +@end deftypefun + +@subheading gnutls_sign_is_secure +@anchor{gnutls_sign_is_secure} +@deftypefun {unsigned} {gnutls_sign_is_secure} (gnutls_sign_algorithm_t @var{algorithm}) +@var{algorithm}: is a sign algorithm + + +@strong{Returns:} Non-zero if the provided signature algorithm is considered to be secure. +@end deftypefun + +@subheading gnutls_sign_is_secure2 +@anchor{gnutls_sign_is_secure2} +@deftypefun {unsigned} {gnutls_sign_is_secure2} (gnutls_sign_algorithm_t @var{algorithm}, unsigned int @var{flags}) +@var{algorithm}: is a sign algorithm + +@var{flags}: zero or @code{GNUTLS_SIGN_FLAG_SECURE_FOR_CERTS} + + +@strong{Returns:} Non-zero if the provided signature algorithm is considered to be secure. +@end deftypefun + +@subheading gnutls_sign_list +@anchor{gnutls_sign_list} +@deftypefun {const gnutls_sign_algorithm_t *} {gnutls_sign_list} ( @var{void}) + +Get a list of supported public key signature algorithms. +This function is not thread safe. + +@strong{Returns:} a (0)-terminated list of @code{gnutls_sign_algorithm_t} +integers indicating the available ciphers. +@end deftypefun + +@subheading gnutls_sign_set_secure +@anchor{gnutls_sign_set_secure} +@deftypefun {int} {gnutls_sign_set_secure} (gnutls_sign_algorithm_t @var{sign}, unsigned int @var{secure}) +@var{sign}: the sign algorithm + +@var{secure}: whether to mark the sign algorithm secure + +Modify the previous system wide setting that marked @code{sign} as secure +or insecure. Calling this function is allowed +only if allowlisting mode is set in the configuration file, +and only if the system-wide TLS priority string +has not been initialized yet. +The intended usage is to provide applications with a way +to expressly deviate from the distribution or site defaults +inherited from the configuration file. +The modification is composable with further modifications +performed through the priority string mechanism. + +This function is not thread-safe and is intended to be called +in the main thread at the beginning of the process execution. + +Even when @code{secure} is true, @code{sign} is not marked as secure for the +use in certificates. Use @code{gnutls_sign_set_secure_for_certs()} to +mark it secure as well for certificates. + +@strong{Returns:} 0 on success or negative error code otherwise. + +@strong{Since:} 3.7.3 +@end deftypefun + +@subheading gnutls_sign_set_secure_for_certs +@anchor{gnutls_sign_set_secure_for_certs} +@deftypefun {int} {gnutls_sign_set_secure_for_certs} (gnutls_sign_algorithm_t @var{sign}, unsigned int @var{secure}) +@var{sign}: the sign algorithm + +@var{secure}: whether to mark the sign algorithm secure for certificates + +Modify the previous system wide setting that marked @code{sign} as secure +or insecure for the use in certificates. Calling this fuction is allowed +only if allowlisting mode is set in the configuration file, +and only if the system-wide TLS priority string +has not been initialized yet. +The intended usage is to provide applications with a way +to expressly deviate from the distribution or site defaults +inherited from the configuration file. +The modification is composable with further modifications +performed through the priority string mechanism. + +This function is not thread-safe and is intended to be called +in the main thread at the beginning of the process execution. +When @code{secure} is true, @code{sign} is marked as secure for any use unlike +@code{gnutls_sign_set_secure()} . Otherwise, it is marked as insecure only +for the use in certificates. Use @code{gnutls_sign_set_secure()} to mark +it insecure for any uses. + +@strong{Returns:} 0 on success or negative error code otherwise. + +@strong{Since:} 3.7.3 +@end deftypefun + +@subheading gnutls_sign_supports_pk_algorithm +@anchor{gnutls_sign_supports_pk_algorithm} +@deftypefun {unsigned} {gnutls_sign_supports_pk_algorithm} (gnutls_sign_algorithm_t @var{sign}, gnutls_pk_algorithm_t @var{pk}) +@var{sign}: is a signature algorithm + +@var{pk}: is a public key algorithm + +This function returns non-zero if the public key algorithm corresponds to +the given signature algorithm. That is, if that signature can be generated +from the given private key algorithm. + +@strong{Since:} 3.6.0 + +@strong{Returns:} return non-zero when the provided algorithms are compatible. +@end deftypefun + +@subheading gnutls_srp_allocate_client_credentials +@anchor{gnutls_srp_allocate_client_credentials} +@deftypefun {int} {gnutls_srp_allocate_client_credentials} (gnutls_srp_client_credentials_t * @var{sc}) +@var{sc}: is a pointer to a @code{gnutls_srp_server_credentials_t} type. + +Allocate a gnutls_srp_client_credentials_t structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an +error code. +@end deftypefun + +@subheading gnutls_srp_allocate_server_credentials +@anchor{gnutls_srp_allocate_server_credentials} +@deftypefun {int} {gnutls_srp_allocate_server_credentials} (gnutls_srp_server_credentials_t * @var{sc}) +@var{sc}: is a pointer to a @code{gnutls_srp_server_credentials_t} type. + +Allocate a gnutls_srp_server_credentials_t structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an +error code. +@end deftypefun + +@subheading gnutls_srp_base64_decode +@anchor{gnutls_srp_base64_decode} +@deftypefun {int} {gnutls_srp_base64_decode} (const gnutls_datum_t * @var{b64_data}, char * @var{result}, size_t * @var{result_size}) +@var{b64_data}: contain the encoded data + +@var{result}: the place where decoded data will be copied + +@var{result_size}: holds the size of the result + +This function will decode the given encoded data, using the base64 +encoding found in libsrp. + +Note that @code{b64_data} should be null terminated. + +Warning! This base64 encoding is not the "standard" encoding, so +do not use it for non-SRP purposes. + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the buffer given is not +long enough, or 0 on success. +@end deftypefun + +@subheading gnutls_srp_base64_decode2 +@anchor{gnutls_srp_base64_decode2} +@deftypefun {int} {gnutls_srp_base64_decode2} (const gnutls_datum_t * @var{b64_data}, gnutls_datum_t * @var{result}) +@var{b64_data}: contains the encoded data + +@var{result}: the place where decoded data lie + +This function will decode the given encoded data. The decoded data +will be allocated, and stored into result. It will decode using +the base64 algorithm as used in libsrp. + +You should use @code{gnutls_free()} to free the returned data. + +Warning! This base64 encoding is not the "standard" encoding, so +do not use it for non-SRP purposes. + +@strong{Returns:} 0 on success, or an error code. +@end deftypefun + +@subheading gnutls_srp_base64_encode +@anchor{gnutls_srp_base64_encode} +@deftypefun {int} {gnutls_srp_base64_encode} (const gnutls_datum_t * @var{data}, char * @var{result}, size_t * @var{result_size}) +@var{data}: contain the raw data + +@var{result}: the place where base64 data will be copied + +@var{result_size}: holds the size of the result + +This function will convert the given data to printable data, using +the base64 encoding, as used in the libsrp. This is the encoding +used in SRP password files. If the provided buffer is not long +enough GNUTLS_E_SHORT_MEMORY_BUFFER is returned. + +Warning! This base64 encoding is not the "standard" encoding, so +do not use it for non-SRP purposes. + +@strong{Returns:} @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the buffer given is not +long enough, or 0 on success. +@end deftypefun + +@subheading gnutls_srp_base64_encode2 +@anchor{gnutls_srp_base64_encode2} +@deftypefun {int} {gnutls_srp_base64_encode2} (const gnutls_datum_t * @var{data}, gnutls_datum_t * @var{result}) +@var{data}: contains the raw data + +@var{result}: will hold the newly allocated encoded data + +This function will convert the given data to printable data, using +the base64 encoding. This is the encoding used in SRP password +files. This function will allocate the required memory to hold +the encoded data. + +You should use @code{gnutls_free()} to free the returned data. + +Warning! This base64 encoding is not the "standard" encoding, so +do not use it for non-SRP purposes. + +@strong{Returns:} 0 on success, or an error code. +@end deftypefun + +@subheading gnutls_srp_free_client_credentials +@anchor{gnutls_srp_free_client_credentials} +@deftypefun {void} {gnutls_srp_free_client_credentials} (gnutls_srp_client_credentials_t @var{sc}) +@var{sc}: is a @code{gnutls_srp_client_credentials_t} type. + +Free a gnutls_srp_client_credentials_t structure. +@end deftypefun + +@subheading gnutls_srp_free_server_credentials +@anchor{gnutls_srp_free_server_credentials} +@deftypefun {void} {gnutls_srp_free_server_credentials} (gnutls_srp_server_credentials_t @var{sc}) +@var{sc}: is a @code{gnutls_srp_server_credentials_t} type. + +Free a gnutls_srp_server_credentials_t structure. +@end deftypefun + +@subheading gnutls_srp_server_get_username +@anchor{gnutls_srp_server_get_username} +@deftypefun {const char *} {gnutls_srp_server_get_username} (gnutls_session_t @var{session}) +@var{session}: is a gnutls session + +This function will return the username of the peer. This should +only be called in case of SRP authentication and in case of a +server. Returns NULL in case of an error. + +@strong{Returns:} SRP username of the peer, or NULL in case of error. +@end deftypefun + +@subheading gnutls_srp_set_client_credentials +@anchor{gnutls_srp_set_client_credentials} +@deftypefun {int} {gnutls_srp_set_client_credentials} (gnutls_srp_client_credentials_t @var{res}, const char * @var{username}, const char * @var{password}) +@var{res}: is a @code{gnutls_srp_client_credentials_t} type. + +@var{username}: is the user's userid + +@var{password}: is the user's password + +This function sets the username and password, in a +@code{gnutls_srp_client_credentials_t} type. Those will be used in +SRP authentication. @code{username} should be an ASCII string or UTF-8 +string. In case of a UTF-8 string it is recommended to be following +the PRECIS framework for usernames (rfc8265). The password can +be in ASCII format, or normalized using @code{gnutls_utf8_password_normalize()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an +error code. +@end deftypefun + +@subheading gnutls_srp_set_client_credentials_function +@anchor{gnutls_srp_set_client_credentials_function} +@deftypefun {void} {gnutls_srp_set_client_credentials_function} (gnutls_srp_client_credentials_t @var{cred}, gnutls_srp_client_credentials_function * @var{func}) +@var{cred}: is a @code{gnutls_srp_server_credentials_t} type. + +@var{func}: is the callback function + +This function can be used to set a callback to retrieve the +username and password for client SRP authentication. The +callback's function form is: + +int (*callback)(gnutls_session_t, char** username, char**password); + +The @code{username} and @code{password} must be allocated using +@code{gnutls_malloc()} . + +The @code{username} should be an ASCII string or UTF-8 +string. In case of a UTF-8 string it is recommended to be following +the PRECIS framework for usernames (rfc8265). The password can +be in ASCII format, or normalized using @code{gnutls_utf8_password_normalize()} . + +The callback function will be called once per handshake before the +initial hello message is sent. + +The callback should not return a negative error code the second +time called, since the handshake procedure will be aborted. + +The callback function should return 0 on success. +-1 indicates an error. +@end deftypefun + +@subheading gnutls_srp_set_prime_bits +@anchor{gnutls_srp_set_prime_bits} +@deftypefun {void} {gnutls_srp_set_prime_bits} (gnutls_session_t @var{session}, unsigned int @var{bits}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{bits}: is the number of bits + +This function sets the minimum accepted number of bits, for use in +an SRP key exchange. If zero, the default 2048 bits will be used. + +In the client side it sets the minimum accepted number of bits. If +a server sends a prime with less bits than that +@code{GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER} will be returned by the +handshake. + +This function has no effect in server side. + +@strong{Since:} 2.6.0 +@end deftypefun + +@subheading gnutls_srp_set_server_credentials_file +@anchor{gnutls_srp_set_server_credentials_file} +@deftypefun {int} {gnutls_srp_set_server_credentials_file} (gnutls_srp_server_credentials_t @var{res}, const char * @var{password_file}, const char * @var{password_conf_file}) +@var{res}: is a @code{gnutls_srp_server_credentials_t} type. + +@var{password_file}: is the SRP password file (tpasswd) + +@var{password_conf_file}: is the SRP password conf file (tpasswd.conf) + +This function sets the password files, in a +@code{gnutls_srp_server_credentials_t} type. Those password files +hold usernames and verifiers and will be used for SRP +authentication. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an +error code. +@end deftypefun + +@subheading gnutls_srp_set_server_credentials_function +@anchor{gnutls_srp_set_server_credentials_function} +@deftypefun {void} {gnutls_srp_set_server_credentials_function} (gnutls_srp_server_credentials_t @var{cred}, gnutls_srp_server_credentials_function * @var{func}) +@var{cred}: is a @code{gnutls_srp_server_credentials_t} type. + +@var{func}: is the callback function + +This function can be used to set a callback to retrieve the user's +SRP credentials. The callback's function form is: + +int (*callback)(gnutls_session_t, const char* username, +gnutls_datum_t *salt, gnutls_datum_t *verifier, gnutls_datum_t *generator, +gnutls_datum_t *prime); + + @code{username} contains the actual username. +The @code{salt} , @code{verifier} , @code{generator} and @code{prime} must be filled +in using the @code{gnutls_malloc()} . For convenience @code{prime} and @code{generator} may also be one of the static parameters defined in gnutls.h. + +Initially, the data field is NULL in every @code{gnutls_datum_t} +structure that the callback has to fill in. When the +callback is done GnuTLS deallocates all of those buffers +which are non-NULL, regardless of the return value. + +In order to prevent attackers from guessing valid usernames, +if a user does not exist, g and n values should be filled in +using a random user's parameters. In that case the callback must +return the special value (1). +See @code{gnutls_srp_set_server_fake_salt_seed} too. +If this is not required for your application, return a negative +number from the callback to abort the handshake. + +The callback function will only be called once per handshake. +The callback function should return 0 on success, while +-1 indicates an error. +@end deftypefun + +@subheading gnutls_srp_set_server_fake_salt_seed +@anchor{gnutls_srp_set_server_fake_salt_seed} +@deftypefun {void} {gnutls_srp_set_server_fake_salt_seed} (gnutls_srp_server_credentials_t @var{cred}, const gnutls_datum_t * @var{seed}, unsigned int @var{salt_length}) +@var{cred}: is a @code{gnutls_srp_server_credentials_t} type + +@var{seed}: is the seed data, only needs to be valid until the function +returns; size of the seed must be greater than zero + +@var{salt_length}: is the length of the generated fake salts + +This function sets the seed that is used to generate salts for +invalid (non-existent) usernames. + +In order to prevent attackers from guessing valid usernames, +when a user does not exist gnutls generates a salt and a verifier +and proceeds with the protocol as usual. +The authentication will ultimately fail, but the client cannot tell +whether the username is valid (exists) or invalid. + +If an attacker learns the seed, given a salt (which is part of the +handshake) which was generated when the seed was in use, it can tell +whether or not the authentication failed because of an unknown username. +This seed cannot be used to reveal application data or passwords. + + @code{salt_length} should represent the salt length your application uses. +Generating fake salts longer than 20 bytes is not supported. + +By default the seed is a random value, different each time a +@code{gnutls_srp_server_credentials_t} is allocated and fake salts are +16 bytes long. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_srp_verifier +@anchor{gnutls_srp_verifier} +@deftypefun {int} {gnutls_srp_verifier} (const char * @var{username}, const char * @var{password}, const gnutls_datum_t * @var{salt}, const gnutls_datum_t * @var{generator}, const gnutls_datum_t * @var{prime}, gnutls_datum_t * @var{res}) +@var{username}: is the user's name + +@var{password}: is the user's password + +@var{salt}: should be some randomly generated bytes + +@var{generator}: is the generator of the group + +@var{prime}: is the group's prime + +@var{res}: where the verifier will be stored. + +This function will create an SRP verifier, as specified in +RFC2945. The @code{prime} and @code{generator} should be one of the static +parameters defined in gnutls/gnutls.h or may be generated. + +The verifier will be allocated with @code{gnutls_malloc} () and will be stored in + @code{res} using binary format. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, or an +error code. +@end deftypefun + +@subheading gnutls_srtp_get_keys +@anchor{gnutls_srtp_get_keys} +@deftypefun {int} {gnutls_srtp_get_keys} (gnutls_session_t @var{session}, void * @var{key_material}, unsigned int @var{key_material_size}, gnutls_datum_t * @var{client_key}, gnutls_datum_t * @var{client_salt}, gnutls_datum_t * @var{server_key}, gnutls_datum_t * @var{server_salt}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{key_material}: Space to hold the generated key material + +@var{key_material_size}: The maximum size of the key material + +@var{client_key}: The master client write key, pointing inside the key material + +@var{client_salt}: The master client write salt, pointing inside the key material + +@var{server_key}: The master server write key, pointing inside the key material + +@var{server_salt}: The master server write salt, pointing inside the key material + +This is a helper function to generate the keying material for SRTP. +It requires the space of the key material to be pre-allocated (should be at least +2x the maximum key size and salt size). The @code{client_key} , @code{client_salt} , @code{server_key} and @code{server_salt} are convenience datums that point inside the key material. They may +be @code{NULL} . + +@strong{Returns:} On success the size of the key material is returned, +otherwise, @code{GNUTLS_E_SHORT_MEMORY_BUFFER} if the buffer given is not +sufficient, or a negative error code. + +Since 3.1.4 +@end deftypefun + +@subheading gnutls_srtp_get_mki +@anchor{gnutls_srtp_get_mki} +@deftypefun {int} {gnutls_srtp_get_mki} (gnutls_session_t @var{session}, gnutls_datum_t * @var{mki}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{mki}: will hold the MKI + +This function exports the negotiated Master Key Identifier, +received by the peer if any. The returned value in @code{mki} should be +treated as constant and valid only during the session's lifetime. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +Since 3.1.4 +@end deftypefun + +@subheading gnutls_srtp_get_profile_id +@anchor{gnutls_srtp_get_profile_id} +@deftypefun {int} {gnutls_srtp_get_profile_id} (const char * @var{name}, gnutls_srtp_profile_t * @var{profile}) +@var{name}: The name of the profile to look up + +@var{profile}: Will hold the profile id + +This function allows you to look up a profile based on a string. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +Since 3.1.4 +@end deftypefun + +@subheading gnutls_srtp_get_profile_name +@anchor{gnutls_srtp_get_profile_name} +@deftypefun {const char *} {gnutls_srtp_get_profile_name} (gnutls_srtp_profile_t @var{profile}) +@var{profile}: The profile to look up a string for + +This function allows you to get the corresponding name for a +SRTP protection profile. + +@strong{Returns:} On success, the name of a SRTP profile as a string, +otherwise NULL. + +Since 3.1.4 +@end deftypefun + +@subheading gnutls_srtp_get_selected_profile +@anchor{gnutls_srtp_get_selected_profile} +@deftypefun {int} {gnutls_srtp_get_selected_profile} (gnutls_session_t @var{session}, gnutls_srtp_profile_t * @var{profile}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{profile}: will hold the profile + +This function allows you to get the negotiated SRTP profile. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +Since 3.1.4 +@end deftypefun + +@subheading gnutls_srtp_set_mki +@anchor{gnutls_srtp_set_mki} +@deftypefun {int} {gnutls_srtp_set_mki} (gnutls_session_t @var{session}, const gnutls_datum_t * @var{mki}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{mki}: holds the MKI + +This function sets the Master Key Identifier, to be +used by this session (if any). + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +Since 3.1.4 +@end deftypefun + +@subheading gnutls_srtp_set_profile +@anchor{gnutls_srtp_set_profile} +@deftypefun {int} {gnutls_srtp_set_profile} (gnutls_session_t @var{session}, gnutls_srtp_profile_t @var{profile}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{profile}: is the profile id to add. + +This function is to be used by both clients and servers, to declare +what SRTP profiles they support, to negotiate with the peer. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +otherwise a negative error code is returned. + +Since 3.1.4 +@end deftypefun + +@subheading gnutls_srtp_set_profile_direct +@anchor{gnutls_srtp_set_profile_direct} +@deftypefun {int} {gnutls_srtp_set_profile_direct} (gnutls_session_t @var{session}, const char * @var{profiles}, const char ** @var{err_pos}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{profiles}: is a string that contains the supported SRTP profiles, +separated by colons. + +@var{err_pos}: In case of an error this will have the position in the string the error occurred, may be NULL. + +This function is to be used by both clients and servers, to declare +what SRTP profiles they support, to negotiate with the peer. + +@strong{Returns:} On syntax error @code{GNUTLS_E_INVALID_REQUEST} is returned, +@code{GNUTLS_E_SUCCESS} on success, or an error code. + +Since 3.1.4 +@end deftypefun + +@subheading gnutls_store_commitment +@anchor{gnutls_store_commitment} +@deftypefun {int} {gnutls_store_commitment} (const char * @var{db_name}, gnutls_tdb_t @var{tdb}, const char * @var{host}, const char * @var{service}, gnutls_digest_algorithm_t @var{hash_algo}, const gnutls_datum_t * @var{hash}, time_t @var{expiration}, unsigned int @var{flags}) +@var{db_name}: A file specifying the stored keys (use NULL for the default) + +@var{tdb}: A storage structure or NULL to use the default + +@var{host}: The peer's name + +@var{service}: non-NULL if this key is specific to a service (e.g. http) + +@var{hash_algo}: The hash algorithm type + +@var{hash}: The raw hash + +@var{expiration}: The expiration time (use 0 to disable expiration) + +@var{flags}: should be 0 or @code{GNUTLS_SCOMMIT_FLAG_ALLOW_BROKEN} . + +This function will store the provided hash commitment to +the list of stored public keys. The key with the given +hash will be considered valid until the provided expiration time. + +The @code{tdb} variable if non-null specifies a custom backend for +the storage of entries. If it is NULL then the +default file backend will be used. + +Note that this function is not thread safe with the default backend. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_store_pubkey +@anchor{gnutls_store_pubkey} +@deftypefun {int} {gnutls_store_pubkey} (const char * @var{db_name}, gnutls_tdb_t @var{tdb}, const char * @var{host}, const char * @var{service}, gnutls_certificate_type_t @var{cert_type}, const gnutls_datum_t * @var{cert}, time_t @var{expiration}, unsigned int @var{flags}) +@var{db_name}: A file specifying the stored keys (use NULL for the default) + +@var{tdb}: A storage structure or NULL to use the default + +@var{host}: The peer's name + +@var{service}: non-NULL if this key is specific to a service (e.g. http) + +@var{cert_type}: The type of the certificate + +@var{cert}: The data of the certificate + +@var{expiration}: The expiration time (use 0 to disable expiration) + +@var{flags}: should be 0. + +This function will store a raw public-key or a public-key provided via +a raw (DER-encoded) certificate to the list of stored public keys. The key +will be considered valid until the provided expiration time. + +The @code{tdb} variable if non-null specifies a custom backend for +the storage of entries. If it is NULL then the +default file backend will be used. + +Unless an alternative @code{tdb} is provided, the storage format is a textual format +consisting of a line for each host with fields separated by '|'. The contents of +the fields are a format-identifier which is set to 'g0', the hostname that the +rest of the data applies to, the numeric port or host name, the expiration +time in seconds since the epoch (0 for no expiration), and a base64 +encoding of the raw (DER) public key information (SPKI) of the peer. + +As of GnuTLS 3.6.6 this function also accepts raw public keys. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.0.13 +@end deftypefun + +@subheading gnutls_strerror +@anchor{gnutls_strerror} +@deftypefun {const char *} {gnutls_strerror} (int @var{error}) +@var{error}: is a GnuTLS 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 GnuTLS error message. +@end deftypefun + +@subheading gnutls_strerror_name +@anchor{gnutls_strerror_name} +@deftypefun {const char *} {gnutls_strerror_name} (int @var{error}) +@var{error}: is an error returned by a gnutls function. + +Return the GnuTLS error code define as a string. For example, +gnutls_strerror_name (GNUTLS_E_DH_PRIME_UNACCEPTABLE) will return +the string "GNUTLS_E_DH_PRIME_UNACCEPTABLE". + +@strong{Returns:} A string corresponding to the symbol name of the error +code. + +@strong{Since:} 2.6.0 +@end deftypefun + +@subheading gnutls_supplemental_get_name +@anchor{gnutls_supplemental_get_name} +@deftypefun {const char *} {gnutls_supplemental_get_name} (gnutls_supplemental_data_format_type_t @var{type}) +@var{type}: is a supplemental data format type + +Convert a @code{gnutls_supplemental_data_format_type_t} value to a +string. + +@strong{Returns:} a string that contains the name of the specified +supplemental data format type, or @code{NULL} for unknown types. +@end deftypefun + +@subheading gnutls_supplemental_recv +@anchor{gnutls_supplemental_recv} +@deftypefun {void} {gnutls_supplemental_recv} (gnutls_session_t @var{session}, unsigned @var{do_recv_supplemental}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{do_recv_supplemental}: non-zero in order to expect supplemental data + +This function is to be called by an extension handler to +instruct gnutls to attempt to receive supplemental data +during the handshake process. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_supplemental_register +@anchor{gnutls_supplemental_register} +@deftypefun {int} {gnutls_supplemental_register} (const char * @var{name}, gnutls_supplemental_data_format_type_t @var{type}, gnutls_supp_recv_func @var{recv_func}, gnutls_supp_send_func @var{send_func}) +@var{name}: the name of the supplemental data to register + +@var{type}: the type of the supplemental data format + +@var{recv_func}: the function to receive the data + +@var{send_func}: the function to send the data + +This function will register a new supplemental data type (rfc4680). +The registered data will remain until @code{gnutls_global_deinit()} +is called. The provided @code{type} must be an unassigned type in +@code{gnutls_supplemental_data_format_type_t} . If the type is already +registered or handled by GnuTLS internally @code{GNUTLS_E_ALREADY_REGISTERED} +will be returned. + +This function is not thread safe. As supplemental data are not defined under +TLS 1.3, this function will disable TLS 1.3 support globally. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} on success, otherwise a negative error code. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_supplemental_send +@anchor{gnutls_supplemental_send} +@deftypefun {void} {gnutls_supplemental_send} (gnutls_session_t @var{session}, unsigned @var{do_send_supplemental}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{do_send_supplemental}: non-zero in order to send supplemental data + +This function is to be called by an extension handler to +instruct gnutls to send supplemental data during the handshake process. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_system_recv_timeout +@anchor{gnutls_system_recv_timeout} +@deftypefun {int} {gnutls_system_recv_timeout} (gnutls_transport_ptr_t @var{ptr}, unsigned int @var{ms}) +@var{ptr}: A file descriptor (wrapped in a gnutls_transport_ptr_t pointer) + +@var{ms}: The number of milliseconds to wait. + +Wait for data to be received from the provided socket ( @code{ptr} ) within a +timeout period in milliseconds, using @code{select()} on the provided @code{ptr} . + +This function is provided as a helper for constructing custom +callbacks for @code{gnutls_transport_set_pull_timeout_function()} , +which can be used if you rely on socket file descriptors. + +Returns -1 on error, 0 on timeout, positive value if data are available for reading. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_tdb_deinit +@anchor{gnutls_tdb_deinit} +@deftypefun {void} {gnutls_tdb_deinit} (gnutls_tdb_t @var{tdb}) +@var{tdb}: The structure to be deinitialized + +This function will deinitialize a public key trust storage structure. +@end deftypefun + +@subheading gnutls_tdb_init +@anchor{gnutls_tdb_init} +@deftypefun {int} {gnutls_tdb_init} (gnutls_tdb_t * @var{tdb}) +@var{tdb}: A pointer to the type to be initialized + +This function will initialize a public key trust storage structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_tdb_set_store_commitment_func +@anchor{gnutls_tdb_set_store_commitment_func} +@deftypefun {void} {gnutls_tdb_set_store_commitment_func} (gnutls_tdb_t @var{tdb}, gnutls_tdb_store_commitment_func @var{cstore}) +@var{tdb}: The trust storage + +@var{cstore}: The commitment storage function + +This function will associate a commitment (hash) storage function with the +trust storage structure. The function is of the following form. + +int gnutls_tdb_store_commitment_func(const char* db_name, const char* host, +const char* service, time_t expiration, +gnutls_digest_algorithm_t, const gnutls_datum_t* hash); + +The @code{db_name} should be used to pass any private data to this function. +@end deftypefun + +@subheading gnutls_tdb_set_store_func +@anchor{gnutls_tdb_set_store_func} +@deftypefun {void} {gnutls_tdb_set_store_func} (gnutls_tdb_t @var{tdb}, gnutls_tdb_store_func @var{store}) +@var{tdb}: The trust storage + +@var{store}: The storage function + +This function will associate a storage function with the +trust storage structure. The function is of the following form. + +int gnutls_tdb_store_func(const char* db_name, const char* host, +const char* service, time_t expiration, +const gnutls_datum_t* pubkey); + +The @code{db_name} should be used to pass any private data to this function. +@end deftypefun + +@subheading gnutls_tdb_set_verify_func +@anchor{gnutls_tdb_set_verify_func} +@deftypefun {void} {gnutls_tdb_set_verify_func} (gnutls_tdb_t @var{tdb}, gnutls_tdb_verify_func @var{verify}) +@var{tdb}: The trust storage + +@var{verify}: The verification function + +This function will associate a retrieval function with the +trust storage structure. The function is of the following form. + +int gnutls_tdb_verify_func(const char* db_name, const char* host, +const char* service, const gnutls_datum_t* pubkey); + +The verify function should return zero on a match, @code{GNUTLS_E_CERTIFICATE_KEY_MISMATCH} +if there is a mismatch and any other negative error code otherwise. + +The @code{db_name} should be used to pass any private data to this function. +@end deftypefun + +@subheading gnutls_transport_get_int +@anchor{gnutls_transport_get_int} +@deftypefun {int} {gnutls_transport_get_int} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Used to get the first argument of the transport function (like +PUSH and PULL). This must have been set using +@code{gnutls_transport_set_int()} . + +@strong{Returns:} The first argument of the transport function. + +@strong{Since:} 3.1.9 +@end deftypefun + +@subheading gnutls_transport_get_int2 +@anchor{gnutls_transport_get_int2} +@deftypefun {void} {gnutls_transport_get_int2} (gnutls_session_t @var{session}, int * @var{recv_int}, int * @var{send_int}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{recv_int}: will hold the value for the pull function + +@var{send_int}: will hold the value for the push function + +Used to get the arguments of the transport functions (like PUSH +and PULL). These should have been set using +@code{gnutls_transport_set_int2()} . + +@strong{Since:} 3.1.9 +@end deftypefun + +@subheading gnutls_transport_get_ptr +@anchor{gnutls_transport_get_ptr} +@deftypefun {gnutls_transport_ptr_t} {gnutls_transport_get_ptr} (gnutls_session_t @var{session}) +@var{session}: is a @code{gnutls_session_t} type. + +Used to get the first argument of the transport function (like +PUSH and PULL). This must have been set using +@code{gnutls_transport_set_ptr()} . + +@strong{Returns:} The first argument of the transport function. +@end deftypefun + +@subheading gnutls_transport_get_ptr2 +@anchor{gnutls_transport_get_ptr2} +@deftypefun {void} {gnutls_transport_get_ptr2} (gnutls_session_t @var{session}, gnutls_transport_ptr_t * @var{recv_ptr}, gnutls_transport_ptr_t * @var{send_ptr}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{recv_ptr}: will hold the value for the pull function + +@var{send_ptr}: will hold the value for the push function + +Used to get the arguments of the transport functions (like PUSH +and PULL). These should have been set using +@code{gnutls_transport_set_ptr2()} . +@end deftypefun + +@subheading gnutls_transport_set_errno +@anchor{gnutls_transport_set_errno} +@deftypefun {void} {gnutls_transport_set_errno} (gnutls_session_t @var{session}, int @var{err}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{err}: error value to store in session-specific errno variable. + +Store @code{err} in the session-specific errno variable. Useful values +for @code{err} are EINTR, EAGAIN and EMSGSIZE, other values are treated will be +treated as real errors in the push/pull function. + +This function is useful in replacement push and pull functions set by +@code{gnutls_transport_set_push_function()} and +@code{gnutls_transport_set_pull_function()} under Windows, where the +replacements may not have access to the same @code{errno} variable that is used by GnuTLS (e.g., the application is linked to +msvcr71.dll and gnutls is linked to msvcrt.dll). + +This function is unreliable if you are using the same + @code{session} in different threads for sending and receiving. +@end deftypefun + +@subheading gnutls_transport_set_errno_function +@anchor{gnutls_transport_set_errno_function} +@deftypefun {void} {gnutls_transport_set_errno_function} (gnutls_session_t @var{session}, gnutls_errno_func @var{errno_func}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{errno_func}: a callback function similar to @code{write()} + +This is the function where you set a function to retrieve errno +after a failed push or pull operation. + + @code{errno_func} is of the form, +int (*gnutls_errno_func)(gnutls_transport_ptr_t); +and should return the errno. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_transport_set_int +@anchor{gnutls_transport_set_int} +@deftypefun {void} {gnutls_transport_set_int} (gnutls_session_t @var{session}, int @var{fd}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{fd}: is the socket descriptor for the connection. + +This function sets the first argument of the transport function, such +as @code{send()} and @code{recv()} for the default callbacks using the +system's socket API. + +This function is equivalent to calling @code{gnutls_transport_set_ptr()} +with the descriptor, but requires no casts. + +@strong{Since:} 3.1.9 +@end deftypefun + +@subheading gnutls_transport_set_int2 +@anchor{gnutls_transport_set_int2} +@deftypefun {void} {gnutls_transport_set_int2} (gnutls_session_t @var{session}, int @var{recv_fd}, int @var{send_fd}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{recv_fd}: is socket descriptor for the pull function + +@var{send_fd}: is socket descriptor for the push function + +This function sets the first argument of the transport functions, +such as @code{send()} and @code{recv()} for the default callbacks using the +system's socket API. With this function you can set two different +descriptors for receiving and sending. + +This function is equivalent to calling @code{gnutls_transport_set_ptr2()} +with the descriptors, but requires no casts. + +@strong{Since:} 3.1.9 +@end deftypefun + +@subheading gnutls_transport_set_ptr +@anchor{gnutls_transport_set_ptr} +@deftypefun {void} {gnutls_transport_set_ptr} (gnutls_session_t @var{session}, gnutls_transport_ptr_t @var{ptr}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{ptr}: is the value. + +Used to set the first argument of the transport function (for push +and pull callbacks). In berkeley style sockets this function will set the +connection descriptor. +@end deftypefun + +@subheading gnutls_transport_set_ptr2 +@anchor{gnutls_transport_set_ptr2} +@deftypefun {void} {gnutls_transport_set_ptr2} (gnutls_session_t @var{session}, gnutls_transport_ptr_t @var{recv_ptr}, gnutls_transport_ptr_t @var{send_ptr}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{recv_ptr}: is the value for the pull function + +@var{send_ptr}: is the value for the push function + +Used to set the first argument of the transport function (for push +and pull callbacks). In berkeley style sockets this function will set the +connection descriptor. With this function you can use two different +pointers for receiving and sending. +@end deftypefun + +@subheading gnutls_transport_set_pull_function +@anchor{gnutls_transport_set_pull_function} +@deftypefun {void} {gnutls_transport_set_pull_function} (gnutls_session_t @var{session}, gnutls_pull_func @var{pull_func}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{pull_func}: a callback function similar to @code{read()} + +This is the function where you set a function for gnutls to receive +data. Normally, if you use berkeley style sockets, do not need to +use this function since the default recv(2) will probably be ok. +The callback should return 0 on connection termination, a positive +number indicating the number of bytes received, and -1 on error. + + @code{gnutls_pull_func} is of the form, +ssize_t (*gnutls_pull_func)(gnutls_transport_ptr_t, void*, size_t); +@end deftypefun + +@subheading gnutls_transport_set_pull_timeout_function +@anchor{gnutls_transport_set_pull_timeout_function} +@deftypefun {void} {gnutls_transport_set_pull_timeout_function} (gnutls_session_t @var{session}, gnutls_pull_timeout_func @var{func}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{func}: a callback function + +This is the function where you set a function for gnutls to know +whether data are ready to be received. It should wait for data a +given time frame in milliseconds. The callback should return 0 on +timeout, a positive number if data can be received, and -1 on error. +You'll need to override this function if @code{select()} is not suitable +for the provided transport calls. + +As with @code{select()} , if the timeout value is zero the callback should return +zero if no data are immediately available. The special value +@code{GNUTLS_INDEFINITE_TIMEOUT} indicates that the callback should wait indefinitely +for data. + + @code{gnutls_pull_timeout_func} is of the form, +int (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, unsigned int ms); + +This callback is necessary when @code{gnutls_handshake_set_timeout()} or +@code{gnutls_record_set_timeout()} are set, under TLS1.3 and for enforcing the DTLS +mode timeouts when in blocking mode. + +For compatibility with future GnuTLS versions this callback must be set when +a custom pull function is registered. The callback will not be used when the +session is in TLS mode with non-blocking sockets. That is, when @code{GNUTLS_NONBLOCK} +is specified for a TLS session in @code{gnutls_init()} . + +The helper function @code{gnutls_system_recv_timeout()} is provided to +simplify writing callbacks. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_transport_set_push_function +@anchor{gnutls_transport_set_push_function} +@deftypefun {void} {gnutls_transport_set_push_function} (gnutls_session_t @var{session}, gnutls_push_func @var{push_func}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{push_func}: a callback function similar to @code{write()} + +This is the function where you set a push function for gnutls to +use in order to send data. If you are going to use berkeley style +sockets, you do not need to use this function since the default +send(2) will probably be ok. Otherwise you should specify this +function for gnutls to be able to send data. +The callback should return a positive number indicating the +bytes sent, and -1 on error. + + @code{push_func} is of the form, +ssize_t (*gnutls_push_func)(gnutls_transport_ptr_t, const void*, size_t); +@end deftypefun + +@subheading gnutls_transport_set_vec_push_function +@anchor{gnutls_transport_set_vec_push_function} +@deftypefun {void} {gnutls_transport_set_vec_push_function} (gnutls_session_t @var{session}, gnutls_vec_push_func @var{vec_func}) +@var{session}: is a @code{gnutls_session_t} type. + +@var{vec_func}: a callback function similar to @code{writev()} + +Using this function you can override the default writev(2) +function for gnutls to send data. Setting this callback +instead of @code{gnutls_transport_set_push_function()} is recommended +since it introduces less overhead in the TLS handshake process. + + @code{vec_func} is of the form, +ssize_t (*gnutls_vec_push_func) (gnutls_transport_ptr_t, const giovec_t * iov, int iovcnt); + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_url_is_supported +@anchor{gnutls_url_is_supported} +@deftypefun {unsigned} {gnutls_url_is_supported} (const char * @var{url}) +@var{url}: A URI to be tested + +Check whether the provided @code{url} is supported. Depending on the system libraries +GnuTLS may support pkcs11, tpmkey or other URLs. + +@strong{Returns:} return non-zero if the given URL is supported, and zero if +it is not known. + +@strong{Since:} 3.1.0 +@end deftypefun + +@subheading gnutls_utf8_password_normalize +@anchor{gnutls_utf8_password_normalize} +@deftypefun {int} {gnutls_utf8_password_normalize} (const unsigned char * @var{password}, unsigned @var{plen}, gnutls_datum_t * @var{out}, unsigned @var{flags}) +@var{password}: contain the UTF-8 formatted password + +@var{plen}: the length of the provided password + +@var{out}: the result in an null-terminated allocated string + +@var{flags}: should be zero + +This function will convert the provided UTF-8 password according +to the normalization rules in RFC7613. + +If the flag @code{GNUTLS_UTF8_IGNORE_ERRS} is specified, any UTF-8 encoding +errors will be ignored, and in that case the output will be a copy of the input. + +@strong{Returns:} @code{GNUTLS_E_INVALID_UTF8_STRING} on invalid UTF-8 data, or 0 on success. + +@strong{Since:} 3.5.7 +@end deftypefun + +@subheading gnutls_verify_stored_pubkey +@anchor{gnutls_verify_stored_pubkey} +@deftypefun {int} {gnutls_verify_stored_pubkey} (const char * @var{db_name}, gnutls_tdb_t @var{tdb}, const char * @var{host}, const char * @var{service}, gnutls_certificate_type_t @var{cert_type}, const gnutls_datum_t * @var{cert}, unsigned int @var{flags}) +@var{db_name}: A file specifying the stored keys (use NULL for the default) + +@var{tdb}: A storage structure or NULL to use the default + +@var{host}: The peer's name + +@var{service}: non-NULL if this key is specific to a service (e.g. http) + +@var{cert_type}: The type of the certificate + +@var{cert}: The raw (der) data of the certificate + +@var{flags}: should be 0. + +This function will try to verify a raw public-key or a public-key provided via +a raw (DER-encoded) certificate using a list of stored public keys. +The @code{service} field if non-NULL should be a port number. + +The @code{db_name} variable if non-null specifies a custom backend for +the retrieval of entries. If it is NULL then the +default file backend will be used. In POSIX-like systems the +file backend uses the $HOME/.gnutls/known_hosts file. + +Note that if the custom storage backend is provided the +retrieval function should return @code{GNUTLS_E_CERTIFICATE_KEY_MISMATCH} +if the host/service pair is found but key doesn't match, +@code{GNUTLS_E_NO_CERTIFICATE_FOUND} if no such host/service with +the given key is found, and 0 if it was found. The storage +function should return 0 on success. + +As of GnuTLS 3.6.6 this function also verifies raw public keys. + +@strong{Returns:} If no associated public key is found +then @code{GNUTLS_E_NO_CERTIFICATE_FOUND} will be returned. If a key +is found but does not match @code{GNUTLS_E_CERTIFICATE_KEY_MISMATCH} +is returned. On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +or a negative error value on other errors. + +@strong{Since:} 3.0.13 +@end deftypefun + |