gnutls_handshake_description_get_name ()

const char *
gnutls_handshake_description_get_name (gnutls_handshake_description_t type);

Convert a gnutls_handshake_description_t value to a string.

gnutls_pk_algorithm_get_name ()

const char *
gnutls_pk_algorithm_get_name (gnutls_pk_algorithm_t algorithm);

Convert a gnutls_pk_algorithm_t value to a string.

GNUTLS_CURVE_TO_BITS()

#define             GNUTLS_CURVE_TO_BITS(curve)

GNUTLS_BITS_TO_CURVE()

#define GNUTLS_BITS_TO_CURVE(bits) (((unsigned int)(bits)) & 0x7FFFFFFF)

GNUTLS_BITS_ARE_CURVE()

#define GNUTLS_BITS_ARE_CURVE(bits) (((unsigned int)(bits)) & 0x80000000)

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 after successful initialization and use must be deinitialized 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_DEFAULT_EXTENSIONS flag.

Note that it is never mandatory to use gnutls_deinit() after this function fails. Since gnutls 3.8.0, it is safe to unconditionally use gnutls_deinit() even after failure regardless of whether the memory was initialized prior to gnutls_init(); however, clients wanting to be portable to older versions of the library should either skip deinitialization on failure, or pre-initialize the memory passed in to gnutls_init() to all zeroes via memset() or similar.

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_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_handshake ()

int
gnutls_handshake (gnutls_session_t session);

This function performs the handshake of the TLS/SSL protocol, and initializes the TLS session parameters.

The non-fatal errors expected by this function are: GNUTLS_E_INTERRUPTED, GNUTLS_E_AGAIN, GNUTLS_E_WARNING_ALERT_RECEIVED. When this function is called for re-handshake under TLS 1.2 or earlier, the non-fatal error code GNUTLS_E_GOT_APPLICATION_DATA may also be returned.

The former two interrupt the handshake procedure due to the transport layer being interrupted, and the latter because of a "warning" alert that was sent by the peer (it is always a good idea to check any received alerts). On these non-fatal errors call this function again, until it returns 0; cf. 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.

When this function is called by a server after a rehandshake request under TLS 1.2 or earlier the GNUTLS_E_GOT_APPLICATION_DATA error code indicates that some data were pending prior to peer initiating the handshake. Under TLS 1.3 this function when called after a successful handshake, is a no-op and always succeeds in server side; in client side this function is equivalent to gnutls_session_key_update() with GNUTLS_KU_PEER flag.

This function handles both full and abbreviated TLS handshakes (resumption). For abbreviated handshakes, in client side, the gnutls_session_set_data() should be called prior to this function to set parameters from a previous session. In server side, resumption is handled by either setting a DB back-end, or setting up keys for session tickets.

gnutls_reauth ()

int
gnutls_reauth (gnutls_session_t session,
               unsigned int flags);

This function performs the post-handshake authentication for TLS 1.3. The post-handshake authentication is initiated by the server by calling this function. Clients respond when GNUTLS_E_REAUTH_REQUEST has been seen while receiving data.

The non-fatal errors expected by this function are: GNUTLS_E_INTERRUPTED, GNUTLS_E_AGAIN, as well as GNUTLS_E_GOT_APPLICATION_DATA when called on server side.

The former two interrupt the authentication procedure due to the transport layer being interrupted, and the latter because there were pending data prior to peer initiating the re-authentication. The server should read/process that data as unauthenticated and retry calling gnutls_reauth().

When this function is called under TLS1.2 or earlier or the peer didn't advertise post-handshake auth, it always fails with GNUTLS_E_INVALID_REQUEST. The verification of the received peers certificate is delegated to the session or credentials verification callbacks. A server can check whether post handshake authentication is supported by the client by checking the session flags with gnutls_session_get_flags().

Prior to calling this function in server side, the function gnutls_certificate_server_set_request() must be called setting expectations for the received certificate (request or require). If none are set this function will return with GNUTLS_E_INVALID_REQUEST.

Note that post handshake authentication is available irrespective of the initial negotiation type (PSK or certificate). In all cases however, certificate credentials must be set to the session prior to calling this function.

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

int
gnutls_rehandshake (gnutls_session_t session);

This function can only be called in server side, and instructs a TLS 1.2 or earlier client to renegotiate parameters (perform a handshake), by sending a hello request message.

If this function succeeds, the calling application should call gnutls_record_recv() until GNUTLS_E_REHANDSHAKE is returned to clear any pending data. If the GNUTLS_E_REHANDSHAKE error code is not seen, then the handshake request was not followed by the peer (the TLS protocol does not require the client to do, and such compliance should be handled by the application protocol).

Once the GNUTLS_E_REHANDSHAKE error code is seen, the calling application should proceed to calling gnutls_handshake() to negotiate the new parameters.

If the client does not wish to renegotiate parameters he may reply with an alert message, and in that case the return code seen by subsequent gnutls_record_recv() will be GNUTLS_E_WARNING_ALERT_RECEIVED with the specific alert being GNUTLS_A_NO_RENEGOTIATION. A client may also choose to ignore this request.

Under TLS 1.3 this function is equivalent to gnutls_session_key_update() with the GNUTLS_KU_PEER flag. In that case subsequent calls to gnutls_record_recv() will not return GNUTLS_E_REHANDSHAKE, and calls to gnutls_handshake() in server side are a no-op.

This function always fails with GNUTLS_E_INVALID_REQUEST when called in client side.

gnutls_session_key_update ()

int
gnutls_session_key_update (gnutls_session_t session,
                           unsigned  flags);

This function will update/refresh the session keys when the TLS protocol is 1.3 or better. The peer is notified of the update by sending a message, so this function should be treated similarly to gnutls_record_send() --i.e., it may return GNUTLS_E_AGAIN or GNUTLS_E_INTERRUPTED.

When this flag GNUTLS_KU_PEER is specified, this function in addition to updating the local keys, will ask the peer to refresh its keys too.

If the negotiated version is not TLS 1.3 or better this function will return GNUTLS_E_INVALID_REQUEST.

Since: 3.6.3

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

This function historically was always sending an alert to the peer, even if err was inappropriate to respond with an alert (e.g., GNUTLS_E_SUCCESS). Since 3.6.6 this function returns success without transmitting any data on error codes that should not result to an alert.

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

gnutls_sec_param_t
gnutls_pk_bits_to_sec_param (gnutls_pk_algorithm_t algo,
                             unsigned int bits);

This is the inverse of gnutls_sec_param_to_pk_bits(). Given an algorithm and the number of bits, it will return the security parameter. This is a rough indication.

Since: 2.12.0

gnutls_sec_param_get_name ()

const char *
gnutls_sec_param_get_name (gnutls_sec_param_t param);

Convert a gnutls_sec_param_t value to a string.

Since: 2.12.0

gnutls_sec_param_to_pk_bits ()

unsigned int
gnutls_sec_param_to_pk_bits (gnutls_pk_algorithm_t algo,
                             gnutls_sec_param_t param);

When generating private and public key pairs a difficult question is which size of "bits" the modulus will be in RSA and the group size in DSA. The easy answer is 1024, which is also wrong. This function will convert a human understandable security parameter to an appropriate size for the specific algorithm.

Since: 2.12.0

gnutls_sec_param_to_symmetric_bits ()

unsigned int
gnutls_sec_param_to_symmetric_bits ();

This function will return the number of bits that correspond to symmetric cipher strength for the given security parameter.

Since: 3.3.0

gnutls_group_get ()

gnutls_group_t
gnutls_group_get (gnutls_session_t session);

Returns the currently used group for key exchange. Only valid when using an elliptic curve or DH ciphersuite.

Since: 3.6.0

gnutls_cipher_get ()

gnutls_cipher_algorithm_t
gnutls_cipher_get (gnutls_session_t session);

Get the currently used cipher.

gnutls_early_cipher_get ()

gnutls_cipher_algorithm_t
gnutls_early_cipher_get (gnutls_session_t session);

Get the cipher algorithm used for encrypting early data.

Since: 3.7.2

gnutls_kx_get ()

gnutls_kx_algorithm_t
gnutls_kx_get (gnutls_session_t session);

Get the currently used key exchange algorithm.

This function will return GNUTLS_KX_ECDHE_RSA, or GNUTLS_KX_DHE_RSA under TLS 1.3, to indicate an elliptic curve DH key exchange or a finite field one. The precise group used is available by calling gnutls_group_get() instead.

gnutls_mac_get ()

gnutls_mac_algorithm_t
gnutls_mac_get (gnutls_session_t session);

Get the currently used MAC algorithm.

gnutls_prf_hash_get ()

gnutls_digest_algorithm_t
gnutls_prf_hash_get (const gnutls_session_t session);

Get the currently used hash algorithm. In TLS 1.3, the hash algorithm is used for both the key derivation function and handshake message authentication code. In TLS 1.2, it matches the hash algorithm used for PRF.

Since: 3.6.13

gnutls_early_prf_hash_get ()

gnutls_digest_algorithm_t
gnutls_early_prf_hash_get (const gnutls_session_t session);

Get the hash algorithm used as a PRF to derive keys for encrypting early data in TLS 1.3.

Since: 3.7.2

gnutls_certificate_type_get ()

gnutls_certificate_type_t
gnutls_certificate_type_get (gnutls_session_t session);

This function returns the type of the certificate that is negotiated for this side to send to the peer. The certificate type is by default X.509, unless an alternative certificate type is enabled by gnutls_init() and negotiated during the session.

Resumed sessions will return the certificate type that was negotiated and used in the original session.

As of version 3.6.4 it is recommended to use gnutls_certificate_type_get2() which is more fine-grained.

gnutls_certificate_type_get2 ()

gnutls_certificate_type_t
gnutls_certificate_type_get2 (gnutls_session_t session,
                              gnutls_ctype_target_t target);

This function returns the type of the certificate that a side is negotiated to use. The certificate type is by default X.509, unless an alternative certificate type is enabled by gnutls_init() and negotiated during the session.

The target parameter specifies whether to request the negotiated certificate type for the client (GNUTLS_CTYPE_CLIENT), or for the server (GNUTLS_CTYPE_SERVER). Additionally, in P2P mode connection set up where you don't know in advance who will be client and who will be server you can use the flag (GNUTLS_CTYPE_OURS) and (GNUTLS_CTYPE_PEERS) to retrieve the corresponding certificate types.

Resumed sessions will return the certificate type that was negotiated and used in the original session. That is, this function can be used to reliably determine the type of the certificate returned by gnutls_certificate_get_peers().

Since: 3.6.4

gnutls_sign_algorithm_get ()

int
gnutls_sign_algorithm_get (gnutls_session_t session);

Returns the signature algorithm that is (or will be) used in this session by the server to sign data. This function should be used only with TLS 1.2 or later.

Since: 3.1.1

gnutls_sign_algorithm_get_client ()

int
gnutls_sign_algorithm_get_client (gnutls_session_t session);

Returns the signature algorithm that is (or will be) used in this session by the client to sign data. This function should be used only with TLS 1.2 or later.

Since: 3.1.11

gnutls_sign_algorithm_get_requested ()

int
gnutls_sign_algorithm_get_requested (gnutls_session_t session,
                                     size_t indx,
                                     gnutls_sign_algorithm_t *algo);

Returns the signature algorithm specified by index that was requested by the peer. If the specified index has no data available this function returns GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE. If the negotiated TLS version does not support signature algorithms then GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned even for the first index. The first index is 0.

This function is useful in the certificate callback functions to assist in selecting the correct certificate.

Since: 2.10.0

gnutls_cipher_get_name ()

const char *
gnutls_cipher_get_name ();

Convert a gnutls_cipher_algorithm_t type to a string.

gnutls_oid_to_digest ()

gnutls_digest_algorithm_t
gnutls_oid_to_digest ();

Converts a textual object identifier to a gnutls_digest_algorithm_t value.

Since: 3.4.3

gnutls_ecc_curve_set_enabled ()

int
gnutls_ecc_curve_set_enabled (gnutls_ecc_curve_t curve,
                              unsigned int enabled);

Modify the previous system wide setting that marked curve as enabled or disabled. Calling this function is allowed only if allowlisting mode is set in the configuration file, and only if the system-wide TLS priority string has not been initialized yet. The intended usage is to provide applications with a way to expressly deviate from the distribution or site defaults inherited from the configuration file. The modification is composable with further modifications performed through the priority string mechanism.

This function is not thread-safe and is intended to be called in the main thread at the beginning of the process execution.

Since: 3.7.3

gnutls_sign_set_secure ()

int
gnutls_sign_set_secure (gnutls_sign_algorithm_t sign,
                        unsigned int secure);

Modify the previous system wide setting that marked sign as secure or insecure. Calling this function is allowed only if allowlisting mode is set in the configuration file, and only if the system-wide TLS priority string has not been initialized yet. The intended usage is to provide applications with a way to expressly deviate from the distribution or site defaults inherited from the configuration file. The modification is composable with further modifications performed through the priority string mechanism.

This function is not thread-safe and is intended to be called in the main thread at the beginning of the process execution.

Even when secure is true, sign is not marked as secure for the use in certificates. Use gnutls_sign_set_secure_for_certs() to mark it secure as well for certificates.

Since: 3.7.3

gnutls_sign_set_secure_for_certs ()

int
gnutls_sign_set_secure_for_certs (gnutls_sign_algorithm_t sign,
                                  unsigned int secure);

Modify the previous system wide setting that marked sign as secure or insecure for the use in certificates. Calling this function is allowed only if allowlisting mode is set in the configuration file, and only if the system-wide TLS priority string has not been initialized yet. The intended usage is to provide applications with a way to expressly deviate from the distribution or site defaults inherited from the configuration file. The modification is composable with further modifications performed through the priority string mechanism.

This function is not thread-safe and is intended to be called in the main thread at the beginning of the process execution.

When secure is true, sign is marked as secure for any use unlike gnutls_sign_set_secure(). Otherwise, it is marked as insecure only for the use in certificates. Use gnutls_sign_set_secure() to mark it insecure for any uses.

Since: 3.7.3

gnutls_digest_set_secure ()

int
gnutls_digest_set_secure (gnutls_digest_algorithm_t dig,
                          unsigned int secure);

Modify the previous system wide setting that marked dig as secure or insecure. This only has effect when the algorithm is enabled through the allowlisting mode in the configuration file, or when the setting is modified with a prior call to this function.

Since: 3.7.3

gnutls_protocol_set_enabled ()

int
gnutls_protocol_set_enabled (gnutls_protocol_t version,
                             unsigned int enabled);

Control the previous system-wide setting that marked version as enabled or disabled. Calling this function is allowed only if allowlisting mode is set in the configuration file, and only if the system-wide TLS priority string has not been initialized yet. The intended usage is to provide applications with a way to expressly deviate from the distribution or site defaults inherited from the configuration file. The modification is composable with further modifications performed through the priority string mechanism.

This function is not thread-safe and is intended to be called in the main thread at the beginning of the process execution.

Since: 3.7.3

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

void
gnutls_perror (int error);

This function is like perror(). The only difference is that it accepts an error number returned by a gnutls function.

gnutls_strerror ()

const char *
gnutls_strerror ();

This function is similar to strerror. The difference is that it accepts an error number returned by a gnutls function; In case of an unknown error a descriptive string is sent instead of NULL.

Error codes are always a negative error code.

gnutls_handshake_set_random ()

int
gnutls_handshake_set_random (gnutls_session_t session,
                             const gnutls_datum_t *random);

This function will explicitly set the server or client hello random value in the subsequent TLS handshake. The random value should be a 32-byte value.

Note that this function should not normally be used as gnutls will select automatically a random value for the handshake.

This function should not be used when resuming a session.

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_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_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_record_set_timeout ()

void
gnutls_record_set_timeout (gnutls_session_t session,
                           unsigned int ms);

This function sets the receive timeout for the record layer to the provided value. Use an ms value of zero to disable timeout (the default), or GNUTLS_INDEFINITE_TIMEOUT, to set an indefinite timeout.

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

Since: 3.1.7

gnutls_record_disable_padding ()

void
gnutls_record_disable_padding (gnutls_session_t session);

Used to disabled padding in TLS 1.0 and above. Normally you do not need to use this function, but there are buggy clients that complain if a server pads the encrypted data. This of course will disable protection against statistical attacks on the data.

This function is defunct since 3.1.7. Random padding is disabled by default unless requested using gnutls_record_send_range().

gnutls_record_cork ()

void
gnutls_record_cork (gnutls_session_t session);

If called, gnutls_record_send() will no longer send any records. Any sent records will be cached until gnutls_record_uncork() is called.

This function is safe to use with DTLS after GnuTLS 3.3.0.

Since: 3.1.9

gnutls_record_uncork ()

int
gnutls_record_uncork (gnutls_session_t session,
                      unsigned int flags);

This resets the effect of gnutls_record_cork(), and flushes any pending data. If the GNUTLS_RECORD_WAIT flag is specified then this function will block until the data is sent or a fatal error occurs (i.e., the function will retry on GNUTLS_E_AGAIN and GNUTLS_E_INTERRUPTED).

If the flag GNUTLS_RECORD_WAIT is not specified and the function is interrupted then the GNUTLS_E_AGAIN or GNUTLS_E_INTERRUPTED errors will be returned. To obtain the data left in the corked buffer use gnutls_record_check_corked().

Since: 3.1.9

gnutls_record_discard_queued ()

size_t
gnutls_record_discard_queued (gnutls_session_t session);

This function discards all queued to be sent packets in a DTLS session. These are the packets queued after an interrupted gnutls_record_send().

This function can only be used with transports where send() is an all-or-nothing operation (e.g., UDP). When partial writes are allowed this function will cause session errors.

Since: 3.4.0

gnutls_record_get_state ()

int
gnutls_record_get_state (gnutls_session_t session,
                         unsigned  read,
                         gnutls_datum_t *mac_key,
                         gnutls_datum_t *IV,
                         gnutls_datum_t *cipher_key,
                         unsigned char seq_number[8]);

This function will return the parameters of the current record state. These are only useful to be provided to an external off-loading device or subsystem. The returned values should be considered constant and valid for the lifetime of the session.

In that case, to sync the state back you must call gnutls_record_set_state().

gnutls_record_set_state ()

int
gnutls_record_set_state (gnutls_session_t session,
                         unsigned  read,
                         const unsigned char seq_number[8]);

This function will set the sequence number in the current record state. This function is useful if sending and receiving are offloaded from gnutls. That is, if gnutls_record_get_state() was used.

gnutls_range_split ()

int
gnutls_range_split (gnutls_session_t session,
                    const gnutls_range_st *orig,
                    gnutls_range_st *small_range,
                    gnutls_range_st *rem_range);

This function should be used when it is required to hide the length of very long data that cannot be directly provided to gnutls_record_send_range(). In that case this function should be called with the desired length hiding range in orig . The returned next value should then be used in the next call to gnutls_record_send_range() with the partial data. That process should be repeated until remainder is (0,0).

gnutls_record_send ()

ssize_t
gnutls_record_send (gnutls_session_t session,
                    const void *data,
                    size_t data_size);

This function has the similar semantics with send(). The only difference is that it accepts a GnuTLS session, and uses different error codes. Note that if the send buffer is full, send() will block this function. See the send() documentation for more information.

You can replace the default push function which is send(), by using gnutls_transport_set_push_function().

If the EINTR is returned by the internal push function then GNUTLS_E_INTERRUPTED will be returned. If GNUTLS_E_INTERRUPTED or GNUTLS_E_AGAIN is returned, you must call this function again with the exact same parameters, or provide a NULL pointer for data and 0 for data_size , in order to write the same data as before. If you wish to discard the previous data instead of retrying, you must call gnutls_record_discard_queued() before calling this function with different parameters. Note that the latter works only on special transports (e.g., UDP). cf. gnutls_record_get_direction().

Note that in DTLS this function will return the GNUTLS_E_LARGE_PACKET error code if the send data exceed the data MTU value - as returned by gnutls_dtls_get_data_mtu(). The errno value EMSGSIZE also maps to GNUTLS_E_LARGE_PACKET. Note that since 3.2.13 this function can be called under cork in DTLS mode, and will refuse to send data over the MTU size by returning GNUTLS_E_LARGE_PACKET.

gnutls_record_send2 ()

ssize_t
gnutls_record_send2 (gnutls_session_t session,
                     const void *data,
                     size_t data_size,
                     size_t pad,
                     unsigned  flags);

This function is identical to gnutls_record_send() except that it takes an extra argument to specify padding to be added the record. To determine the maximum size of padding, use gnutls_record_get_max_size() and gnutls_record_overhead_size().

Note that in order for GnuTLS to provide constant time processing of padding and data in TLS1.3, the flag GNUTLS_SAFE_PADDING_CHECK must be used in gnutls_init().

Since: 3.6.3

gnutls_record_send_range ()

ssize_t
gnutls_record_send_range (gnutls_session_t session,
                          const void *data,
                          size_t data_size,
                          const gnutls_range_st *range);

This function operates like gnutls_record_send() but, while gnutls_record_send() adds minimal padding to each TLS record, this function uses the TLS extra-padding feature to conceal the real data size within the range of lengths provided. Some TLS sessions do not support extra padding (e.g. stream ciphers in standard TLS or SSL3 sessions). To know whether the current session supports extra padding, and hence length hiding, use the gnutls_record_can_use_length_hiding() function.

Note: This function currently is limited to blocking sockets.

gnutls_record_send_file ()

ssize_t
gnutls_record_send_file (gnutls_session_t session,
                         int fd,
                         off_t *offset,
                         size_t count);

This function sends data from fd . If KTLS (kernel TLS) is enabled, it will use the sendfile() system call to avoid overhead of copying data between user space and the kernel. Otherwise, this functionality is merely emulated by calling read() and gnutls_record_send(). If this implementation is suboptimal, check whether KTLS is enabled using gnutls_transport_is_ktls_enabled().

If offset is NULL then file offset is incremented by number of bytes send, otherwise file offset remains unchanged.

gnutls_record_recv ()

ssize_t
gnutls_record_recv (gnutls_session_t session,
                    void *data,
                    size_t data_size);

This function has the similar semantics with recv(). The only difference is that it accepts a GnuTLS session, and uses different error codes. In the special case that the peer requests a renegotiation, the caller will receive an error code of GNUTLS_E_REHANDSHAKE. In case of a client, this message may be simply ignored, replied with an alert GNUTLS_A_NO_RENEGOTIATION, or replied with a new handshake, depending on the client's will. A server receiving this error code can only initiate a new handshake or terminate the session.

If EINTR is returned by the internal pull function (the default is recv()) then GNUTLS_E_INTERRUPTED will be returned. If GNUTLS_E_INTERRUPTED or GNUTLS_E_AGAIN is returned, you must call this function again to get the data. See also gnutls_record_get_direction().

gnutls_record_recv_packet ()

ssize_t
gnutls_record_recv_packet (gnutls_session_t session,
                           gnutls_packet_t *packet);

This is a lower-level function than gnutls_record_recv() and allows to directly receive the whole decrypted packet. That avoids a memory copy, and is intended to be used by applications seeking high performance.

The received packet is accessed using gnutls_packet_get() and must be deinitialized using gnutls_packet_deinit(). The returned packet will be NULL if the return value is zero (EOF).

Since: 3.3.5

gnutls_packet_get ()

void
gnutls_packet_get (gnutls_packet_t packet,
                   gnutls_datum_t *data,
                   unsigned char *sequence);

This function returns the data and sequence number associated with the received packet.

Since: 3.3.5

gnutls_packet_deinit ()

void
gnutls_packet_deinit (gnutls_packet_t packet);

This function will deinitialize all data associated with the received packet.

Since: 3.3.5

gnutls_record_recv_seq ()

ssize_t
gnutls_record_recv_seq (gnutls_session_t session,
                        void *data,
                        size_t data_size,
                        unsigned char *seq);

This function is the same as gnutls_record_recv(), except that it returns in addition to data, the sequence number of the data. This is useful in DTLS where record packets might be received out-of-order. The returned 8-byte sequence number is an integer in big-endian format and should be treated as a unique message identification.

Since: 3.0

gnutls_record_overhead_size ()

size_t
gnutls_record_overhead_size (gnutls_session_t session);

This function will return the size in bytes of the overhead due to TLS (or DTLS) per record. On certain occasions (e.g., CBC ciphers) the returned value is the maximum possible overhead.

Since: 3.2.2

gnutls_est_record_overhead_size ()

size_t
gnutls_est_record_overhead_size (gnutls_protocol_t version,
                                 gnutls_cipher_algorithm_t cipher,
                                 gnutls_mac_algorithm_t mac,
                                 gnutls_compression_method_t comp);

This function will return the set size in bytes of the overhead due to TLS (or DTLS) per record.

Note that this function may provide inaccurate values when TLS extensions that modify the record format are negotiated. In these cases a more accurate value can be obtained using gnutls_record_overhead_size() after a completed handshake.

Since: 3.2.2

gnutls_record_set_max_empty_records()

#define gnutls_record_set_max_empty_records(session, x)

gnutls_record_can_use_length_hiding ()

unsigned
gnutls_record_can_use_length_hiding (gnutls_session_t session);

If the session supports length-hiding padding, you can invoke gnutls_record_send_range() to send a message whose length is hidden in the given range. If the session does not support length hiding padding, you can use the standard gnutls_record_send() function, or gnutls_record_send_range() making sure that the range is the same as the length of the message you are trying to send.

gnutls_record_get_direction ()

int
gnutls_record_get_direction (gnutls_session_t session);

This function is useful to determine whether a GnuTLS function was interrupted while sending or receiving, so that select() or poll() may be called appropriately.

It provides information about the internals of the record protocol and is only useful if a prior gnutls function call, e.g. gnutls_handshake(), was interrupted and returned GNUTLS_E_INTERRUPTED or GNUTLS_E_AGAIN. After such an interrupt applications may call select() or poll() before restoring the interrupted GnuTLS function.

This function's output is unreliable if you are using the same session in different threads for sending and receiving.

gnutls_record_get_max_size ()

size_t
gnutls_record_get_max_size (gnutls_session_t session);

Get the record size. The maximum record size is negotiated by the client after the first handshake message.

gnutls_record_set_max_size ()

ssize_t
gnutls_record_set_max_size (gnutls_session_t session,
                            size_t size);

This function sets the maximum amount of plaintext sent and received in a record in this connection.

Prior to 3.6.4, this function was implemented using a TLS extension called 'max fragment length', which limits the acceptable values to 512(=2^9), 1024(=2^10), 2048(=2^11) and 4096(=2^12).

Since 3.6.4, the limit is also negotiated through a new TLS extension called 'record size limit', which doesn't have the limitation, as long as the value ranges between 512 and 16384. Note that while the 'record size limit' extension is preferred, not all TLS implementations use or even understand the extension.

gnutls_record_set_max_recv_size ()

ssize_t
gnutls_record_set_max_recv_size (gnutls_session_t session,
                                 size_t size);

This function sets the maximum amount of plaintext received in a record in this connection.

The limit is also negotiated through a TLS extension called 'record size limit'. Note that while the 'record size limit' extension is preferred, not all TLS implementations use or even understand the extension.

Since: 3.6.8

gnutls_record_check_pending ()

size_t
gnutls_record_check_pending (gnutls_session_t session);

This function checks if there are unread data in the gnutls buffers. If the return value is non-zero the next call to gnutls_record_recv() is guaranteed not to block.

gnutls_record_check_corked ()

size_t
gnutls_record_check_corked (gnutls_session_t session);

This function checks if there pending corked data in the gnutls buffers --see gnutls_record_cork().

Since: 3.2.8

gnutls_record_get_max_early_data_size ()

size_t
gnutls_record_get_max_early_data_size (gnutls_session_t session);

This function returns the maximum early data size in this connection. This property can only be set to servers. The client may be provided with the maximum allowed size through the "early_data" extension of the NewSessionTicket handshake message.

Since: 3.6.5

gnutls_record_set_max_early_data_size ()

int
gnutls_record_set_max_early_data_size (gnutls_session_t session,
                                       size_t size);

This function sets the maximum early data size in this connection. This property can only be set to servers. The client may be provided with the maximum allowed size through the "early_data" extension of the NewSessionTicket handshake message.

Since: 3.6.4

gnutls_record_send_early_data ()

ssize_t
gnutls_record_send_early_data (gnutls_session_t session,
                               const void *data,
                               size_t length);

This function can be used by a client to send data early in the handshake processes when resuming a session. This is used to implement a zero-roundtrip (0-RTT) mode. It has the same semantics as gnutls_record_send().

There may be a limit to the amount of data sent as early data. Use gnutls_record_get_max_early_data_size() to check the limit. If the limit exceeds, this function returns GNUTLS_E_RECORD_LIMIT_REACHED.

Since: 3.6.5

gnutls_record_recv_early_data ()

ssize_t
gnutls_record_recv_early_data (gnutls_session_t session,
                               void *data,
                               size_t data_size);

This function can be used by a server to retrieve data sent early in the handshake processes when resuming a session. This is used to implement a zero-roundtrip (0-RTT) mode. It has the same semantics as gnutls_record_recv().

This function can be called either in a handshake hook, or after the handshake is complete.

Since: 3.6.5

gnutls_session_force_valid ()

void
gnutls_session_force_valid (gnutls_session_t session);

Clears the invalid flag in a session. That means that sessions were corrupt or invalid data were received can be re-used. Use only when debugging or experimenting with the TLS protocol. Should not be used in typical applications.

gnutls_prf ()

int
gnutls_prf (gnutls_session_t session,
            size_t label_size,
            const char *label,
            int server_random_first,
            size_t extra_size,
            const char *extra,
            size_t outsize,
            char *out);

Applies the TLS Pseudo-Random-Function (PRF) on the master secret and the provided data, seeded with the client and server random fields. For the key expansion specified in RFC5705 see gnutls_prf_rfc5705().

The label variable usually contains a string denoting the purpose for the generated data. The server_random_first indicates whether the client random field or the server random field should be first in the seed. Non-zero indicates that the server random field is first, 0 that the client random field is first.

The extra variable can be used to add more data to the seed, after the random variables. It can be used to make sure the generated output is strongly connected to some additional data (e.g., a string used in user authentication).

The output is placed in out , which must be pre-allocated.

Note: This function produces identical output with gnutls_prf_rfc5705() when server_random_first is set to 0 and extra is NULL. Under TLS1.3 this function will only operate when these conditions are true, or otherwise return GNUTLS_E_INVALID_REQUEST.