GNUTLS_CLIENT

#define GNUTLS_CLIENT (1<<1)

GNUTLS_DATAGRAM

#define GNUTLS_DATAGRAM (1<<2)

GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT

#define GNUTLS_DEFAULT_HANDSHAKE_TIMEOUT ((unsigned int)-1)

GNUTLS_HB_LOCAL_ALLOWED_TO_SEND

#define GNUTLS_HB_LOCAL_ALLOWED_TO_SEND (1<<2)

GNUTLS_HB_PEER_ALLOWED_TO_SEND

#define GNUTLS_HB_PEER_ALLOWED_TO_SEND (1)

GNUTLS_HB_PEER_NOT_ALLOWED_TO_SEND

#define GNUTLS_HB_PEER_NOT_ALLOWED_TO_SEND (1<<1)

GNUTLS_NONBLOCK

#define GNUTLS_NONBLOCK (1<<3)

GNUTLS_NO_EXTENSIONS

#define GNUTLS_NO_EXTENSIONS (1<<4)

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

This structure is complex enough to manipulate directly thus this helper function is provided in order to allocate it.

gnutls_anon_allocate_server_credentials ()

int
gnutls_anon_allocate_server_credentials
                               (gnutls_anon_server_credentials_t *sc);

This structure is complex enough to manipulate directly thus this helper function is provided in order to allocate it.

gnutls_anon_free_client_credentials ()

void
gnutls_anon_free_client_credentials (gnutls_anon_client_credentials_t sc);

This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) it.

gnutls_anon_free_server_credentials ()

void
gnutls_anon_free_server_credentials (gnutls_anon_server_credentials_t sc);

This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) it.

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

This structure is complex enough to manipulate directly thus this helper function is provided in order to allocate it.

gnutls_certificate_client_get_request_status ()

int
gnutls_certificate_client_get_request_status
                               (gnutls_session_t session);

Get whether client certificate is requested 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);

This structure is complex enough to manipulate directly thus this helper function is provided in order to free (deallocate) it.

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. As with gnutls_x509_trust_list_get_issuer() this function requires the GNUTLS_TL_GET_COPY flag in order to operate with PKCS 11 trust lists. In that case the issuer must be freed using gnutls_x509_crt_deinit().

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 first certificate in the list is the peer's certificate, following the issuer's certificate, then the issuer's issuer etc.

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

This function sets the filename of an OCSP response, that will be sent to the client if requests an OCSP certificate status. This is a convenience function which is inefficient on busy servers since the file is opened on every access. Use gnutls_certificate_set_ocsp_status_request_function() to fine-tune file accesses.

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, the server will provide the client with the ocsp_response.

The response must be a value allocated using gnutls_malloc(), and will be deinitialized when needed.

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. 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. Normally we should send a certificate that is signed by one of these CAs. These names 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.

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 structure. 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 structure is at an undefined state, it must not be reused to load other keys or certificates.

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 structure. 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 import 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 are imported (i.e., 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.

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

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

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

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_type_get_id ()

gnutls_certificate_type_t
gnutls_certificate_type_get_id (const char *name);

The names are compared in a case insensitive way.

gnutls_certificate_type_get_name ()

const char *
gnutls_certificate_type_get_name (gnutls_certificate_type_t type);

Convert a gnutls_certificate_type_t type to a string.

gnutls_certificate_type_list ()

const gnutls_certificate_type_t *
gnutls_certificate_type_list (void);

Get a list of certificate types.

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 the given. The comparison will be accurate for ascii names; non-ascii names are compared byte-by-byte. 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 (const char *req_version);

Check GnuTLS Library version.

See GNUTLS_VERSION for a suitable req_version string.

gnutls_cipher_get ()

gnutls_cipher_algorithm_t
gnutls_cipher_get (gnutls_session_t session);

Get currently used cipher.

gnutls_cipher_get_id ()

gnutls_cipher_algorithm_t
gnutls_cipher_get_id (const char *name);

The names are compared in a case insensitive way.

gnutls_cipher_get_key_size ()

size_t
gnutls_cipher_get_key_size (gnutls_cipher_algorithm_t algorithm);

Get key size for cipher.

gnutls_cipher_get_name ()

const char *
gnutls_cipher_get_name (gnutls_cipher_algorithm_t algorithm);

Convert a gnutls_cipher_algorithm_t type to a string.

gnutls_cipher_list ()

const gnutls_cipher_algorithm_t *
gnutls_cipher_list (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#8 or similar).

This function is not thread safe.

gnutls_cipher_suite_get_name ()

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

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

gnutls_cipher_suite_info ()

const char *
gnutls_cipher_suite_info (size_t idx,
                          unsigned char *cs_id,
                          gnutls_kx_algorithm_t *kx,
                          gnutls_cipher_algorithm_t *cipher,
                          gnutls_mac_algorithm_t *mac,
                          gnutls_protocol_t *min_version);

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.

gnutls_compression_get ()

gnutls_compression_method_t
gnutls_compression_get (gnutls_session_t session);

Get currently used compression algorithm.

gnutls_compression_get_id ()

gnutls_compression_method_t
gnutls_compression_get_id (const char *name);

The names are compared in a case insensitive way.

gnutls_compression_get_name ()

const char *
gnutls_compression_get_name (gnutls_compression_method_t algorithm);

Convert a gnutls_compression_method_t value to a string.

gnutls_compression_list ()

const gnutls_compression_method_t *
gnutls_compression_list (void);

Get a list of compression methods.

gnutls_credentials_clear ()

void
gnutls_credentials_clear (gnutls_session_t session);

Clears all the credentials previously set in this session.

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

gnutls_dh_params_deinit ()

void
gnutls_dh_params_deinit (gnutls_dh_params_t dh_params);

This function will deinitialize the DH parameters structure.

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. The new parameters will be allocated using gnutls_malloc() and will be stored in the appropriate datum. This function is normally slow.

Do not set the number of bits directly, use gnutls_sec_param_to_pk_bits() to get bits for GNUTLS_PK_DSA. 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.

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

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_ecc_curve_get ()

gnutls_ecc_curve_t
gnutls_ecc_curve_get (gnutls_session_t session);

Returns the currently used elliptic curve. Only valid when using an elliptic curve ciphersuite.

Since: 3.0

gnutls_ecc_curve_get_name ()

const char *
gnutls_ecc_curve_get_name (gnutls_ecc_curve_t curve);

Convert a gnutls_ecc_curve_t value to a string.

Since: 3.0

gnutls_ecc_curve_get_size ()

int
gnutls_ecc_curve_get_size (gnutls_ecc_curve_t curve);

Returns the size in bytes of the curve.

Since: 3.0

gnutls_ecc_curve_list ()

const gnutls_ecc_curve_t *
gnutls_ecc_curve_list (void);

Get the list of supported elliptic curves.

This function is not thread safe.

gnutls_errno_func ()

int
(*gnutls_errno_func) (gnutls_transport_ptr_t Param1);

gnutls_error_is_fatal ()

int
gnutls_error_is_fatal (int error);

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_error_to_alert ()

int
gnutls_error_to_alert (int err,
                       int *level);

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

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

gnutls_global_init ()

int
gnutls_global_init (void);

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.

Since GnuTLS 3.3.0 this function is only required in systems that do not support library constructors and static linking. This function also became thread safe.

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

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.

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_post_client_hello_func ()

int
(*gnutls_handshake_post_client_hello_func)
                               (gnutls_session_t Param1);

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

gnutls_handshake_set_post_client_hello_function ()

void
gnutls_handshake_set_post_client_hello_function
                               (gnutls_session_t session,
                                gnutls_handshake_post_client_hello_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.