man gnutls_handshake (3): 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 does the handshake of the TLS/SSL protocol, and initializes the TLS connection.

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

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

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

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

RETURNS

GNUTLS_E_SUCCESS on success, otherwise a negative error code.

REPORTING BUGS

Report bugs to <[email protected]>.
Home page: http://www.gnutls.org

COPYRIGHT