gnutls_alert_get ()

gnutls_alert_description_t
gnutls_alert_get (gnutls_session_t session);

This function will return the last alert number received. This function should be called when GNUTLS_E_WARNING_ALERT_RECEIVED or 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.

gnutls_alert_get_name ()

const char *
gnutls_alert_get_name (gnutls_alert_description_t alert);

This function will return a string that describes the given alert number, or NULL. See gnutls_alert_get().

gnutls_alert_get_strname ()

const char *
gnutls_alert_get_strname (gnutls_alert_description_t alert);

This function will return a string of the name of the alert.

Since: 3.0

gnutls_alert_send ()

int
gnutls_alert_send (gnutls_session_t session,
                   gnutls_alert_level_t level,
                   gnutls_alert_description_t desc);

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 GNUTLS_E_INTERRUPTED or GNUTLS_E_AGAIN as well.

gnutls_alert_send_appropriate ()

int
gnutls_alert_send_appropriate (gnutls_session_t session,
                               int err);

Sends an alert to the peer depending on the error code returned by a gnutls function. This function will call gnutls_error_to_alert() to determine the appropriate alert to send.

This function may also return GNUTLS_E_AGAIN, or GNUTLS_E_INTERRUPTED.

If the return value is GNUTLS_E_INVALID_REQUEST, then no alert has been sent to the peer.

gnutls_alloc_function ()

void *
(*gnutls_alloc_function) (size_t Param1);

gnutls_anon_allocate_client_credentials ()

int
gnutls_anon_allocate_client_credentials
                               (gnutls_anon_client_credentials_t *sc);

Allocate a gnutls_anon_client_credentials_t structure.

gnutls_anon_allocate_server_credentials ()

int
gnutls_anon_allocate_server_credentials
                               (gnutls_anon_server_credentials_t *sc);

Allocate a gnutls_anon_server_credentials_t structure.

gnutls_anon_free_client_credentials ()

void
gnutls_anon_free_client_credentials (gnutls_anon_client_credentials_t sc);

Free a gnutls_anon_client_credentials_t structure.

gnutls_anon_free_server_credentials ()

void
gnutls_anon_free_server_credentials (gnutls_anon_server_credentials_t sc);

Free a gnutls_anon_server_credentials_t structure.

gnutls_anon_set_params_function ()

void
gnutls_anon_set_params_function (gnutls_anon_server_credentials_t res,
                                 gnutls_params_function *func);

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 GNUTLS_E_SUCCESS (0) on success.

gnutls_anon_set_server_dh_params ()

void
gnutls_anon_set_server_dh_params (gnutls_anon_server_credentials_t res,
                                  gnutls_dh_params_t dh_params);

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.

gnutls_anon_set_server_params_function ()

void
gnutls_anon_set_server_params_function
                               (gnutls_anon_server_credentials_t res,
                                gnutls_params_function *func);

This function will set a callback in order for the server to get the Diffie-Hellman parameters for anonymous authentication. The callback should return GNUTLS_E_SUCCESS (0) on success.

gnutls_audit_log_func ()

void
(*gnutls_audit_log_func) (gnutls_session_t Param1,
                          const char *Param2);

gnutls_bye ()

int
gnutls_bye (gnutls_session_t session,
            gnutls_close_request_t how);

Terminates the current TLS/SSL connection. The connection should have been initiated using gnutls_handshake(). how should be one of GNUTLS_SHUT_RDWR, GNUTLS_SHUT_WR.

In case of 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. GNUTLS_SHUT_RDWR sends an alert containing a close request and waits for the peer to reply with the same message.

In case of 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. 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 GNUTLS_E_AGAIN or GNUTLS_E_INTERRUPTED; cf. gnutls_record_get_direction().

gnutls_calloc_function ()

void *
(*gnutls_calloc_function) (size_t Param1,
                           size_t Param2);

gnutls_certificate_activation_time_peers ()

time_t
gnutls_certificate_activation_time_peers
                               (gnutls_session_t session);

This function will return the peer's certificate activation time. This is the creation time for openpgp keys.

gnutls_certificate_allocate_credentials ()

int
gnutls_certificate_allocate_credentials
                               (gnutls_certificate_credentials_t *res);

Allocate a gnutls_certificate_credentials_t structure.

gnutls_certificate_client_get_request_status ()

int
gnutls_certificate_client_get_request_status
                               (gnutls_session_t session);

Get whether client certificate was requested on the last handshake or not.

gnutls_certificate_expiration_time_peers ()

time_t
gnutls_certificate_expiration_time_peers
                               (gnutls_session_t session);

This function will return the peer's certificate expiration time.

gnutls_certificate_free_ca_names ()

void
gnutls_certificate_free_ca_names (gnutls_certificate_credentials_t sc);

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.

gnutls_certificate_free_cas ()

void
gnutls_certificate_free_cas (gnutls_certificate_credentials_t sc);

This function will delete all the CAs associated with the given credentials. Servers that do not use gnutls_certificate_verify_peers2() may call this to save some memory.

gnutls_certificate_free_credentials ()

void
gnutls_certificate_free_credentials (gnutls_certificate_credentials_t sc);

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).

gnutls_certificate_free_crls ()

void
gnutls_certificate_free_crls (gnutls_certificate_credentials_t sc);

This function will delete all the CRLs associated with the given credentials.

gnutls_certificate_free_keys ()

void
gnutls_certificate_free_keys (gnutls_certificate_credentials_t sc);

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.

gnutls_certificate_get_issuer ()

int
gnutls_certificate_get_issuer (gnutls_certificate_credentials_t sc,
                               gnutls_x509_crt_t cert,
                               gnutls_x509_crt_t *issuer,
                               unsigned int flags);

This function will return the issuer of a given certificate. If the flag GNUTLS_TL_GET_COPY is specified a copy of the issuer will be returned which must be freed using gnutls_x509_crt_deinit(). In that case the provided issuer must not be initialized.

As with gnutls_x509_trust_list_get_issuer() this function requires the GNUTLS_TL_GET_COPY flag in order to operate with PKCS11 trust lists in a thread-safe way.

Since: 3.0

gnutls_certificate_get_ours ()

const gnutls_datum_t *
gnutls_certificate_get_ours (gnutls_session_t 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.

gnutls_certificate_get_peers ()

const gnutls_datum_t *
gnutls_certificate_get_peers (gnutls_session_t session,
                              unsigned int *list_size);

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 case of OpenPGP keys a single key will be returned in raw format.

gnutls_certificate_get_peers_subkey_id ()

int
gnutls_certificate_get_peers_subkey_id
                               (gnutls_session_t session,
                                gnutls_datum_t *id);

Get the peer's subkey ID when OpenPGP certificates are used. The returned id should be treated as constant.

Since: 3.1.3

gnutls_certificate_send_x509_rdn_sequence ()

void
gnutls_certificate_send_x509_rdn_sequence
                               (gnutls_session_t session,
                                int status);

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.

gnutls_certificate_server_set_request ()

void
gnutls_certificate_server_set_request (gnutls_session_t session,
                                       gnutls_certificate_request_t req);

This function specifies if we (in case of a server) are going to send a certificate request message to the client. If req is GNUTLS_CERT_REQUIRE then the server will return an 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.

gnutls_certificate_set_dh_params ()

void
gnutls_certificate_set_dh_params (gnutls_certificate_credentials_t res,
                                  gnutls_dh_params_t dh_params);

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.

gnutls_certificate_set_ocsp_status_request_file ()

int
gnutls_certificate_set_ocsp_status_request_file
                               (gnutls_certificate_credentials_t res,
                                const char *response_file,
                                unsigned  idx);

This function sets the filename of an OCSP response, that will be sent to the client if requests an OCSP certificate status for the certificate chain specified by idx .

This is a convenience function which may be inefficient on busy servers since the file is opened on every access. Use gnutls_certificate_set_ocsp_status_request_function2() to fine-tune file accesses.

Note: the ability to set multiple OCSP responses per credential structure via idx was added in version 3.5.6 with the GNUTLS_CERTIFICATE_API_V2 flag.

Since: 3.1.3

gnutls_certificate_set_ocsp_status_request_function ()

void
gnutls_certificate_set_ocsp_status_request_function
                               (gnutls_certificate_credentials_t res,
                                gnutls_status_request_ocsp_func ocsp_func,
                                void *ptr);

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 GNUTLS_E_NO_CERTIFICATE_STATUS, if there is no recent OCSP response. If the callback returns GNUTLS_E_SUCCESS, it is expected to have the ocsp_response field set with a valid (DER-encoded) OCSP response. The response must be a value allocated using gnutls_malloc(), and will be deinitialized by the caller.

It is possible to set a specific callback for each provided certificate using gnutls_certificate_set_ocsp_status_request_function2().

Since: 3.1.3

gnutls_certificate_set_params_function ()

void
gnutls_certificate_set_params_function
                               (gnutls_certificate_credentials_t res,
                                gnutls_params_function *func);

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 GNUTLS_E_SUCCESS (0) on success.

gnutls_certificate_set_pin_function ()

void
gnutls_certificate_set_pin_function (gnutls_certificate_credentials_t Param1,
                                     gnutls_pin_callback_t fn,
                                     void *userdata);

gnutls_certificate_set_retrieve_function ()

void
gnutls_certificate_set_retrieve_function
                               (gnutls_certificate_credentials_t cred,
                                gnutls_certificate_retrieve_function *func);

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 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);

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 gnutls_x509_rdn_get().

pk_algos contains a list with server's acceptable signature algorithms. The certificate returned should support the server's given algorithms.

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.

Since: 3.0

gnutls_certificate_set_verify_flags ()

void
gnutls_certificate_set_verify_flags (gnutls_certificate_credentials_t res,
                                     unsigned int 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 gnutls_certificate_verify_flags enumerations.

gnutls_certificate_set_verify_function ()

void
gnutls_certificate_set_verify_function
                               (gnutls_certificate_credentials_t cred,
                                gnutls_certificate_verify_function *func);

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 gnutls_certificate_verify_peers2(), gnutls_certificate_type_get(), gnutls_certificate_get_peers() functions can be used.

The callback function should return 0 for the handshake to continue or non-zero to terminate.

Since: 2.10.0

gnutls_certificate_set_verify_limits ()

void
gnutls_certificate_set_verify_limits (gnutls_certificate_credentials_t res,
                                      unsigned int max_bits,
                                      unsigned int max_depth);

This function will set some upper limits for the default verification function, gnutls_certificate_verify_peers2(), to avoid denial of service attacks. You can set them to zero to disable limits.

gnutls_certificate_set_x509_crl ()

int
gnutls_certificate_set_x509_crl (gnutls_certificate_credentials_t res,
                                 gnutls_x509_crl_t *crl_list,
                                 int crl_list_size);

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 gnutls_certificate_verify_peers2(). This function may be called multiple times.

Since: 2.4.0

gnutls_certificate_set_x509_crl_file ()

int
gnutls_certificate_set_x509_crl_file (gnutls_certificate_credentials_t res,
                                      const char *crlfile,
                                      gnutls_x509_crt_fmt_t type);

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 gnutls_certificate_verify_peers2(). This function may be called multiple times.

gnutls_certificate_set_x509_crl_mem ()

int
gnutls_certificate_set_x509_crl_mem (gnutls_certificate_credentials_t res,
                                     const gnutls_datum_t *CRL,
                                     gnutls_x509_crt_fmt_t type);

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 gnutls_certificate_verify_peers2(). This function may be called multiple times.

gnutls_certificate_set_x509_key ()

int
gnutls_certificate_set_x509_key (gnutls_certificate_credentials_t res,
                                 gnutls_x509_crt_t *cert_list,
                                 int cert_list_size,
                                 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 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 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 GNUTLS_CERTIFICATE_API_V2 is set using 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.

Since: 2.4.0

gnutls_certificate_set_x509_key_file ()

int
gnutls_certificate_set_x509_key_file (gnutls_certificate_credentials_t res,
                                      const char *certfile,
                                      const char *keyfile,
                                      gnutls_x509_crt_fmt_t type);

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 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 keyfile and 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 gnutls_url_is_supported().

In case the certfile is provided as a PKCS 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 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 GNUTLS_CERTIFICATE_API_V2 is set using 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.

Since: 3.1.11

gnutls_certificate_set_x509_key_mem ()

int
gnutls_certificate_set_x509_key_mem (gnutls_certificate_credentials_t res,
                                     const gnutls_datum_t *cert,
                                     const gnutls_datum_t *key,
                                     gnutls_x509_crt_fmt_t type);

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 key may be NULL if you are using a sign callback, see 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 GNUTLS_CERTIFICATE_API_V2 is set using 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.

gnutls_certificate_set_x509_simple_pkcs12_file ()

int
gnutls_certificate_set_x509_simple_pkcs12_file
                               (gnutls_certificate_credentials_t res,
                                const char *pkcs12file,
                                gnutls_x509_crt_fmt_t type,
                                const char *password);

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).

PKCS12 files with a MAC, encrypted bags and PKCS #8 private keys are supported. However, only password based security, and the same password for all operations, are supported.

PKCS12 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 PKCS12 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 PKCS12 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 GNUTLS_CERTIFICATE_API_V2 is set using 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.

gnutls_certificate_set_x509_simple_pkcs12_mem ()

int
gnutls_certificate_set_x509_simple_pkcs12_mem
                               (gnutls_certificate_credentials_t res,
                                const gnutls_datum_t *p12blob,
                                gnutls_x509_crt_fmt_t type,
                                const char *password);

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 PKCS12 bags and PKCS#8 private keys are supported. However, only password based security, and the same password for all operations, are supported.

PKCS12 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 PKCS12 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 PKCS12 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 GNUTLS_CERTIFICATE_API_V2 is set using 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.

Since: 2.8.0

gnutls_certificate_set_x509_system_trust ()

int
gnutls_certificate_set_x509_system_trust
                               (gnutls_certificate_credentials_t cred);

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 GNUTLS_E_UNIMPLEMENTED_FEATURE is returned.

Since: 3.0.20

gnutls_certificate_set_x509_trust ()

int
gnutls_certificate_set_x509_trust (gnutls_certificate_credentials_t res,
                                   gnutls_x509_crt_t *ca_list,
                                   int ca_list_size);

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 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 gnutls_certificate_send_x509_rdn_sequence().

Since: 2.4.0

gnutls_certificate_set_x509_trust_file ()

int
gnutls_certificate_set_x509_trust_file
                               (gnutls_certificate_credentials_t cred,
                                const char *cafile,
                                gnutls_x509_crt_fmt_t type);

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 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 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 gnutls_url_is_supported().

gnutls_certificate_set_x509_trust_mem ()

int
gnutls_certificate_set_x509_trust_mem (gnutls_certificate_credentials_t res,
                                       const gnutls_datum_t *ca,
                                       gnutls_x509_crt_fmt_t type);

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 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 gnutls_certificate_send_x509_rdn_sequence().

gnutls_certificate_type_get ()

gnutls_certificate_type_t
gnutls_certificate_type_get (gnutls_session_t session);

The certificate type is by default X.509, unless it is negotiated as a TLS extension.

gnutls_certificate_verification_status_print ()

int
gnutls_certificate_verification_status_print
                               (unsigned int status,
                                gnutls_certificate_type_t type,
                                gnutls_datum_t *out,
                                unsigned int flags);

This function will pretty print the status of a verification process -- eg. the one obtained by gnutls_certificate_verify_peers3().

The output out needs to be deallocated using gnutls_free().

Since: 3.1.4

gnutls_certificate_verify_peers2 ()

int
gnutls_certificate_verify_peers2 (gnutls_session_t session,
                                  unsigned int *status);

This function will verify the peer's certificate and store the status in the status variable as a bitwise or'd gnutls_certificate_status_t values or zero if the certificate is trusted. Note that value in 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 gnutls_certificate_set_verify_flags().

This function will take into account the OCSP Certificate Status TLS extension, as well as the following X.509 certificate extensions: Name Constraints, Key Usage, and Basic Constraints (pathlen).

To avoid denial of service attacks some default upper limits regarding the certificate key size and chain size are set. To override them use gnutls_certificate_set_verify_limits().

Note that you must also check the peer's name in order to check if the verified certificate belongs to the actual peer, see gnutls_x509_crt_check_hostname(), or use gnutls_certificate_verify_peers3().

gnutls_certificate_verify_peers3 ()

int
gnutls_certificate_verify_peers3 (gnutls_session_t session,
                                  const char *hostname,
                                  unsigned int *status);

This function will verify the peer's certificate and store the status in the status variable as a bitwise or'd gnutls_certificate_status_t values or zero if the certificate is trusted. Note that value in 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 gnutls_certificate_set_verify_flags(). See the documentation of gnutls_certificate_verify_peers2() for details in the verification process.

If the 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 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 gnutls_certificate_verify_peers().

Since: 3.1.4

gnutls_check_version ()

const char *
gnutls_check_version ();

Check the GnuTLS Library version against the provided string. See GNUTLS_VERSION for a suitable req_version string.

See also gnutls_check_version_numeric(), which provides this functionality as a macro.

gnutls_cipher_get ()

gnutls_cipher_algorithm_t
gnutls_cipher_get (gnutls_session_t session);

Get currently used cipher.

gnutls_cipher_get_name ()

const char *
gnutls_cipher_get_name ();

Convert a gnutls_cipher_algorithm_t type to a string.

gnutls_cipher_suite_get_name ()

const char *
gnutls_cipher_suite_get_name (gnutls_kx_algorithm_t kx_algorithm,
                              gnutls_cipher_algorithm_t cipher_algorithm);

Note that the full cipher suite name must be prepended by TLS or SSL depending of the protocol in use.

gnutls_compression_get ()

gnutls_compression_method_t
gnutls_compression_get (gnutls_session_t session);

Get currently used compression algorithm.

gnutls_credentials_set ()

int
gnutls_credentials_set (gnutls_session_t session,
                        gnutls_credentials_type_t type,
                        void *cred);

Sets the needed credentials for the specified type. E.g. username, password - or public and private keys etc. The 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 gnutls_deinit().

For GNUTLS_CRD_ANON, cred should be gnutls_anon_client_credentials_t in case of a client. In case of a server it should be gnutls_anon_server_credentials_t.

For GNUTLS_CRD_SRP, cred should be gnutls_srp_client_credentials_t in case of a client, and gnutls_srp_server_credentials_t, in case of a server.

For GNUTLS_CRD_CERTIFICATE, cred should be gnutls_certificate_credentials_t.

gnutls_db_check_entry ()

int
gnutls_db_check_entry (gnutls_session_t session,
                       gnutls_datum_t session_entry);

This function has no effect.

gnutls_db_get_ptr ()

void *
gnutls_db_get_ptr (gnutls_session_t session);

Get db function pointer.

gnutls_db_remove_func ()

int
(*gnutls_db_remove_func) (void *Param1,
                          gnutls_datum_t key);

gnutls_db_remove_session ()

void
gnutls_db_remove_session (gnutls_session_t session);

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 gnutls_deinit() is called.

Normally gnutls_deinit() will remove abnormally terminated sessions.

gnutls_db_retr_func ()

gnutls_datum_t
(*gnutls_db_retr_func) (void *Param1,
                        gnutls_datum_t key);

gnutls_db_set_cache_expiration ()

void
gnutls_db_set_cache_expiration (gnutls_session_t session,
                                int seconds);

Set the expiration time for resumed sessions. The default is 3600 (one hour) at the time of this writing.

gnutls_db_set_ptr ()

void
gnutls_db_set_ptr (gnutls_session_t session,
                   void *ptr);

Sets the pointer that will be provided to db store, retrieve and delete functions, as the first argument.

gnutls_db_set_remove_function ()

void
gnutls_db_set_remove_function (gnutls_session_t session,
                               gnutls_db_remove_func rem_func);

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 rem_func will be null unless gnutls_db_set_ptr() has been called.

gnutls_db_set_retrieve_function ()

void
gnutls_db_set_retrieve_function (gnutls_session_t session,
                                 gnutls_db_retr_func retr_func);

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 gnutls_malloc().

The first argument to retr_func will be null unless gnutls_db_set_ptr() has been called.

gnutls_db_set_store_function ()

void
gnutls_db_set_store_function (gnutls_session_t session,
                              gnutls_db_store_func store_func);

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 store_func will be null unless gnutls_db_set_ptr() has been called.

gnutls_db_store_func ()

int
(*gnutls_db_store_func) (void *Param1,
                         gnutls_datum_t key,
                         gnutls_datum_t data);

gnutls_deinit ()

void
gnutls_deinit (gnutls_session_t session);

This function clears all buffers associated with the session . This function will also remove session data from the session database if the session was terminated abnormally.

gnutls_dh_get_group ()

int
gnutls_dh_get_group (gnutls_session_t session,
                     gnutls_datum_t *raw_gen,
                     gnutls_datum_t *raw_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 gnutls_free().

Note, that the prime and generator are exported as non-negative integers and may include a leading zero byte.

gnutls_dh_get_peers_public_bits ()

int
gnutls_dh_get_peers_public_bits (gnutls_session_t session);

Get the Diffie-Hellman public key bit size. Can be used for both anonymous and ephemeral Diffie-Hellman.

gnutls_dh_get_prime_bits ()

int
gnutls_dh_get_prime_bits (gnutls_session_t 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.

gnutls_dh_get_pubkey ()

int
gnutls_dh_get_pubkey (gnutls_session_t session,
                      gnutls_datum_t *raw_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 gnutls_free().

Note, that public key is exported as non-negative integer and may include a leading zero byte.

gnutls_dh_get_secret_bits ()

int
gnutls_dh_get_secret_bits (gnutls_session_t 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.

gnutls_dh_params_cpy ()

int
gnutls_dh_params_cpy (gnutls_dh_params_t dst,
                      gnutls_dh_params_t src);

This function will copy the DH parameters structure from source to destination. The destination should be already initialized.

gnutls_dh_params_deinit ()

void
gnutls_dh_params_deinit (gnutls_dh_params_t dh_params);

This function will deinitialize the DH parameters type.

gnutls_dh_params_export2_pkcs3 ()

int
gnutls_dh_params_export2_pkcs3 (gnutls_dh_params_t params,
                                gnutls_x509_crt_fmt_t format,
                                gnutls_datum_t *out);

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 out will be allocated using gnutls_malloc().

If the structure is PEM encoded, it will have a header of "BEGIN DH PARAMETERS".

Since: 3.1.3

gnutls_dh_params_export_pkcs3 ()

int
gnutls_dh_params_export_pkcs3 (gnutls_dh_params_t params,
                               gnutls_x509_crt_fmt_t format,
                               unsigned char *params_data,
                               size_t *params_data_size);

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".

gnutls_dh_params_export_raw ()

int
gnutls_dh_params_export_raw (gnutls_dh_params_t params,
                             gnutls_datum_t *prime,
                             gnutls_datum_t *generator,
                             unsigned int *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 gnutls_malloc() and will be stored in the appropriate datum.

gnutls_dh_params_generate2 ()

int
gnutls_dh_params_generate2 (gnutls_dh_params_t params,
                            unsigned int 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 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 gnutls_x509_privkey_generate2() with DSA option and the GNUTLS_PRIVKEY_FLAG_PROVABLE flag set. These can the be imported with gnutls_dh_params_import_dsa().

It is no longer recommended for applications to generate parameters. See the "Parameter generation" section in the manual.

gnutls_dh_params_import_pkcs3 ()

int
gnutls_dh_params_import_pkcs3 (gnutls_dh_params_t params,
                               const gnutls_datum_t *pkcs3_params,
                               gnutls_x509_crt_fmt_t format);

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".

gnutls_dh_params_import_raw ()

int
gnutls_dh_params_import_raw (gnutls_dh_params_t dh_params,
                             const gnutls_datum_t *prime,
                             const gnutls_datum_t *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.

gnutls_dh_params_init ()

int
gnutls_dh_params_init (gnutls_dh_params_t *dh_params);

This function will initialize the DH parameters type.

gnutls_dh_set_prime_bits ()

void
gnutls_dh_set_prime_bits (gnutls_session_t session,
                          unsigned int 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 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 gnutls_priority_set_direct() or the set value may be overridden by the selected priority options.

gnutls_errno_func ()

int
(*gnutls_errno_func) (gnutls_transport_ptr_t Param1);

gnutls_error_is_fatal ()

int
gnutls_error_is_fatal ();

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).

gnutls_fingerprint ()

int
gnutls_fingerprint (gnutls_digest_algorithm_t algo,
                    const gnutls_datum_t *data,
                    void *result,
                    size_t *result_size);

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.

gnutls_free_function ()

void
(*gnutls_free_function) (void *Param1);

gnutls_global_deinit ()

void
gnutls_global_deinit (void);

This function deinitializes the global data, that were initialized using 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 gnutls_global_init() for disabling the implicit initialization/deinitialization.

gnutls_global_init ()

int
gnutls_global_init (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 GNUTLS_NO_EXPLICIT_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 gnutls_global_deinit() when gnutls usage is no longer needed.

This function increments a global counter, so that gnutls_global_deinit() only releases resources when it has been called as many times as 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.

A subsequent call of this function if the initial has failed will return the same error code.

gnutls_global_set_audit_log_function ()

void
gnutls_global_set_audit_log_function (gnutls_audit_log_func log_func);

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 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.

gnutls_audit_log_func is of the form, void (*gnutls_audit_log_func)( gnutls_session_t, const char*);

Since: 3.0

gnutls_global_set_log_function ()

void
gnutls_global_set_log_function (gnutls_log_func log_func);

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.

gnutls_log_func is of the form, void (*gnutls_log_func)( int level, const char*);

gnutls_global_set_log_level ()

void
gnutls_global_set_log_level (int level);

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.

gnutls_global_set_mem_functions ()

void
gnutls_global_set_mem_functions (gnutls_alloc_function alloc_func,
                                 gnutls_alloc_function secure_alloc_func,
                                 gnutls_is_secure_function is_secure_func,
                                 gnutls_realloc_function realloc_func,
                                 gnutls_free_function free_func);

gnutls_global_set_mutex ()

void
gnutls_global_set_mutex (mutex_init_func init,
                         mutex_deinit_func deinit,
                         mutex_lock_func lock,
                         mutex_unlock_func unlock);

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.

Note that since the move to implicit initialization of GnuTLS on library load, calling this function will deinitialize the library, and re-initialize it after the new locking functions are set.

This function must be called prior to any other gnutls function.

Since: 2.12.0

gnutls_global_set_time_function ()

void
gnutls_global_set_time_function (gnutls_time_func time_func);

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.

Since: 2.12.0

gnutls_handshake ()

int
gnutls_handshake (gnutls_session_t session);

This function does the handshake of the TLS/SSL protocol, and initializes the TLS connection.

This function will fail if any problem is encountered, and will return a negative error code. In case of a client, if the client has asked to resume a session, but the server couldn't, then a full handshake will be performed.

The non-fatal errors expected by this function are: GNUTLS_E_INTERRUPTED, GNUTLS_E_AGAIN, GNUTLS_E_WARNING_ALERT_RECEIVED, and GNUTLS_E_GOT_APPLICATION_DATA, the latter only in a case of rehandshake.

The former two interrupt the handshake procedure due to the lower layer being interrupted, and the latter because of an alert that may be sent by a server (it is always a good idea to check any received alerts). On these errors call this function again, until it returns 0; cf. gnutls_record_get_direction() and gnutls_error_is_fatal(). In DTLS sessions the non-fatal error GNUTLS_E_LARGE_PACKET is also possible, and indicates that the MTU should be adjusted.

If this function is called by a server after a rehandshake request then GNUTLS_E_GOT_APPLICATION_DATA or GNUTLS_E_WARNING_ALERT_RECEIVED may be returned. Note that these are non fatal errors, only in the specific case of a rehandshake. Their meaning is that the client rejected the rehandshake request or in the case of GNUTLS_E_GOT_APPLICATION_DATA it could also mean that some data were pending. A client may receive that error code if it initiates the handshake and the server doesn't agreed.

gnutls_handshake_get_last_in ()

gnutls_handshake_description_t
gnutls_handshake_get_last_in (gnutls_session_t session);

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 gnutls_handshake_description_t in gnutls.h for the available handshake descriptions.

gnutls_handshake_get_last_out ()

gnutls_handshake_description_t
gnutls_handshake_get_last_out (gnutls_session_t session);

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 gnutls_handshake_description_t in gnutls.h for the available handshake descriptions.

gnutls_handshake_set_max_packet_length ()

void
gnutls_handshake_set_max_packet_length
                               (gnutls_session_t session,
                                size_t max);

This function will set the maximum size of all handshake messages. Handshakes over this size are rejected with 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.

gnutls_handshake_set_post_client_hello_function ()

void
gnutls_handshake_set_post_client_hello_function
                               (gnutls_session_t session,
                                gnutls_handshake_simple_hook_func func);

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 GNUTLS_E_AGAIN or GNUTLS_E_INTERRUPTED to put the handshake on hold. In that case gnutls_handshake() will return GNUTLS_E_INTERRUPTED and can be resumed when needed.

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.

gnutls_handshake_set_timeout ()

void
gnutls_handshake_set_timeout (gnutls_session_t session,
                              unsigned int ms);

This function sets the timeout for the TLS handshake process to the provided value. Use an ms value of zero to disable timeout, or GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT for a reasonable default value. For the DTLS protocol, the more detailed gnutls_dtls_set_timeouts() is provided.

This function requires to set a pull timeout callback. See gnutls_transport_set_pull_timeout_function().

Since: 3.1.0

gnutls_heartbeat_allowed ()

int
gnutls_heartbeat_allowed (gnutls_session_t session,
                          unsigned int type);

This function will check whether heartbeats are allowed to be sent or received in this session.

Since: 3.1.2

gnutls_heartbeat_enable ()

void
gnutls_heartbeat_enable (gnutls_session_t session,
                         unsigned int type);

If this function is called with the GNUTLS_HB_PEER_ALLOWED_TO_SEND type , GnuTLS will allow heartbeat messages to be received. Moreover it also request the peer to accept heartbeat messages.

If the type used is GNUTLS_HB_LOCAL_ALLOWED_TO_SEND, then the peer will be asked to accept heartbeat messages but not send ones.

The function gnutls_heartbeat_allowed() can be used to test Whether locally generated heartbeat messages can be accepted by the peer.

Since: 3.1.2

gnutls_heartbeat_get_timeout ()

unsigned int
gnutls_heartbeat_get_timeout (gnutls_session_t session);

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 gnutls_heartbeat_ping() if no packets have been received.

Since: 3.1.2

gnutls_heartbeat_ping ()

int
gnutls_heartbeat_ping (gnutls_session_t session,
                       size_t data_size,
                       unsigned int max_tries,
                       unsigned int flags);

This function sends a ping to the peer. If the flags is set to 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 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, data_size )+gnutls_record_overhead_size()+3.

Since: 3.1.2

gnutls_heartbeat_pong ()

int
gnutls_heartbeat_pong (gnutls_session_t session,
                       unsigned int flags);

This function replies to a ping by sending a pong to the peer.

Since: 3.1.2

gnutls_heartbeat_set_timeouts ()

void
gnutls_heartbeat_set_timeouts (gnutls_session_t session,
                               unsigned int retrans_timeout,
                               unsigned int total_timeout);

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 GNUTLS_E_TIMEDOUT.

Since: 3.1.2

gnutls_hex2bin ()

int
gnutls_hex2bin (const char *hex_data,
                size_t hex_size,
                void *bin_data,
                size_t *bin_size);

Convert a buffer with hex data to binary data. This function unlike gnutls_hex_decode() can parse hex data with separators between numbers. That is, it ignores any non-hex characters.

Since: 2.4.0

gnutls_hex_decode ()

int
gnutls_hex_decode (const gnutls_datum_t *hex_data,
                   void *result,
                   size_t *result_size);

This function will decode the given encoded data, using the hex encoding used by PSK password files.

Initially result_size must hold the maximum size available in result , and on return it will contain the number of bytes written.

gnutls_hex_encode ()

int
gnutls_hex_encode (const gnutls_datum_t *data,
                   char *result,
                   size_t *result_size);

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.

gnutls_init ()

int
gnutls_init (gnutls_session_t *session,
             unsigned int flags);

This function initializes the provided session. Every session must be initialized before use, and must be deinitialized after used by calling gnutls_deinit().

flags can be any combination of flags from 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 GNUTLS_NO_EXTENSIONS flag.

gnutls_is_secure_function ()

int
(*gnutls_is_secure_function) (const void *Param1);

gnutls_key_generate ()

int
gnutls_key_generate (gnutls_datum_t *key,
                     unsigned int key_size);

Generates a random key of key_size bytes.

Since: 3.0

gnutls_kx_get ()

gnutls_kx_algorithm_t
gnutls_kx_get (gnutls_session_t session);

Get currently used key exchange algorithm.

gnutls_load_file ()

int
gnutls_load_file (const char *filename,
                  gnutls_datum_t *data);

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 gnutls_malloc().

gnutls_log_func ()

void
(*gnutls_log_func) (int Param1,
                    const char *Param2);

gnutls_mac_get ()

gnutls_mac_algorithm_t
gnutls_mac_get (gnutls_session_t session);

Get currently used MAC algorithm.

gnutls_ocsp_status_request_enable_client ()

int
gnutls_ocsp_status_request_enable_client
                               (gnutls_session_t session,
                                gnutls_datum_t *responder_id,
                                size_t responder_id_size,
                                gnutls_datum_t *request_extensions);

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.

The responder_id array, its containing elements as well as the data of extensions , must be allocated using gnutls_malloc(). They will be deinitialized on session cleanup.

Due to the difficult semantics of the responder_id and extensions parameters, it is recommended to only call this function with these parameters set to NULL.

Since: 3.1.3

gnutls_ocsp_status_request_get ()

int
gnutls_ocsp_status_request_get (gnutls_session_t session,
                                gnutls_datum_t *response);

This function returns the OCSP status response received from the TLS server. The response should be treated as constant. If no OCSP response is available then GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE is returned.

Since: 3.1.3

gnutls_ocsp_status_request_is_checked ()

int
gnutls_ocsp_status_request_is_checked (gnutls_session_t session,
                                       unsigned int flags);

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 or superseded. It returns zero otherwise.

When the flag 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 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.

Since: 3.1.4

gnutls_openpgp_send_cert ()

void
gnutls_openpgp_send_cert (gnutls_session_t session,
                          gnutls_openpgp_crt_status_t status);

This function will order gnutls to send the key fingerprint instead of the key in the initial handshake procedure. This should be used with care and only when there is indication or knowledge that the server can obtain the client's key.

gnutls_pem_base64_decode ()

int
gnutls_pem_base64_decode (const char *header,
                          const gnutls_datum_t *b64_data,
                          unsigned char *result,
                          size_t *result_size);