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  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: https://www.gnutls.org

COPYRIGHT

       Copyright © 2001-2023 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

       https://www.gnutls.org/manual/