gnutls_handshake man page

gnutls_handshake — API function

Synopsis

#include <gnutls/gnutls.h>

int gnutls_handshake(gnutls_session_t session);

Arguments

gnutls_session_t session

is a gnutls_session_t type.

Description

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.

Returns

GNUTLS_E_SUCCESS on a successful handshake, otherwise a negative error code.

Reporting Bugs

Report bugs to <bugs@gnutls.org>.
Home page: http://www.gnutls.org

See Also

The full documentation for gnutls is maintained as a Texinfo manual. If the /usr/share/doc/gnutls/ directory does not contain the HTML form visit

http://www.gnutls.org/manual/

Info

3.6.3 gnutls