NAME

       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  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 <bugs@gnutls.org>.
       Home page: http://www.gnutls.org

COPYRIGHT

       Copyright © 2001-2021 Free Software Foundation, Inc., and others.
       Copying and distribution of this file, with or without modification, are permitted in  any
       medium without royalty provided the copyright notice and this notice are preserved.

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/