gnutls_handshake(3)

1gnutls_handshake(3)                 gnutls                 gnutls_handshake(3)
2
3
4

NAME

6       gnutls_handshake - API function
7

SYNOPSIS

9       #include <gnutls/gnutls.h>
10
11       int gnutls_handshake(gnutls_session_t session);
12

ARGUMENTS

14       gnutls_session_t session
15                   is a gnutls_session_t type.
16

DESCRIPTION

18       This  function performs the handshake of the TLS/SSL protocol, and ini‐
19       tializes the TLS session parameters.
20
21       The non-fatal errors expected by  this  function  are:  GNUTLS_E_INTER‐
22       RUPTED,   GNUTLS_E_AGAIN,  GNUTLS_E_WARNING_ALERT_RECEIVED.  When  this
23       function is called for re-handshake  under  TLS  1.2  or  earlier,  the
24       non-fatal   error   code   GNUTLS_E_GOT_APPLICATION_DATA  may  also  be
25       returned.
26
27       The former two interrupt the handshake procedure due to  the  transport
28       layer  being  interrupted,  and the latter because of a "warning" alert
29       that was sent by the peer (it is  always  a  good  idea  to  check  any
30       received  alerts).  On these non-fatal errors call this function again,
31       until   it   returns   0;   cf.    gnutls_record_get_direction()    and
32       gnutls_error_is_fatal().   In   DTLS   sessions   the  non-fatal  error
33       GNUTLS_E_LARGE_PACKET is also possible,  and  indicates  that  the  MTU
34       should be adjusted.
35
36       When  this  function  is called by a server after a rehandshake request
37       under TLS 1.2 or earlier the GNUTLS_E_GOT_APPLICATION_DATA  error  code
38       indicates  that  some  data  were  pending prior to peer initiating the
39       handshake.  Under TLS 1.3 this function when called after a  successful
40       handshake,  is  a  no-op  and always succeeds in server side; in client
41       side this function is equivalent  to  gnutls_session_key_update()  with
42       GNUTLS_KU_PEER flag.
43
44       This function handles both full and abbreviated TLS handshakes (resump‐
45       tion).  For abbreviated handshakes, in  client  side,  the  gnutls_ses‐
46       sion_set_data()  should be called prior to this function to set parame‐
47       ters from a previous session.  In server side, resumption is handled by
48       either setting a DB back-end, or setting up keys for session tickets.
49

RETURNS

51       GNUTLS_E_SUCCESS  on a successful handshake, otherwise a negative error
52       code.
53

REPORTING BUGS

55       Report bugs to <bugs@gnutls.org>.
56       Home page: https://www.gnutls.org
57
58

COPYRIGHT

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