NAME    [Toc]    [Back]

       SSL_do_handshake - Perform a TLS/SSL handshake

SYNOPSIS    [Toc]    [Back]

       #include <openssl/ssl.h>

       int SSL_do_handshake(
               SSL *ssl );

DESCRIPTION    [Toc]    [Back]

       The  SSL_do_handshake()  function will wait for an SSL/TLS
       handshake to take place. If the connection  is  in  client
       mode, the handshake will start. The handshake routines may
       have to be explicitly set  in  advance  using  either  the
       SSL_set_connect_state()  or  SSL_set_accept_state()  functions.

NOTES    [Toc]    [Back]

       The behavior of SSL_do_handshake() depends on the underlying
  BIO.  If the underlying BIO is blocking, SSL_do_handshake()will
 only return once the handshake has  been  finished
  or  an error occurred, except for SGC (Server Gated
       Cryptography). For SGC, SSL_do_handshake()  may  return  a
       -1,       but       SSL_get_error()       will       yield
       SSL_ERROR_WANT_READ/WRITE and SSL_do_handshake() should be
       called  again.  If  the  underlying  BIO  is non-blocking,
       SSL_do_handshake() will also return  when  the  underlying
       BIO  could  not satisfy the needs of SSL_do_handshake() to
       continue  the  handshake.  In  this  case,   a   call   to
       SSL_get_error()  with  the  return  value  of SSL_do_handshake()
     will     yield     SSL_ERROR_WANT_READ      or
       SSL_ERROR_WANT_WRITE. The calling process then must repeat
       the call after taking appropriate action  to  satisfy  the
       needs  of  SSL_do_handshake().  The  action depends on the
       underlying BIO. When using a non-blocking socket,  nothing
       is  done,  but  select()  can  be  used  to  check for the
       required condition. When using a buffering BIO, such as  a
       BIO  pair,  data  must be written into or retrieved out of
       the  BIO before continuing.

RETURN VALUES    [Toc]    [Back]

       The TLS/SSL handshake was successfully  completed,  and  a
       TLS/SSL  connection  has  been  established.   The TLS/SSL
       handshake was not successful but was shut down  controlled
       and  by  the specifications of the TLS/SSL protocol.  Call
       SSL_get_error() with the return value  ret  to  learn  the
       reason.   The TLS/SSL handshake was not successful because
       a fatal error occurred either at the protocol level  or  a
       connection  failure  occurred. The shutdown was not clean.
       It can also occur if action  is  needed  to  continue  the
       operation for non-blocking BIOs. Call SSL_get_error() with
       the return value ret to learn the reason.

SEE ALSO    [Toc]    [Back]

       SSL_get_error(3), SSL_connect(3),  SSL_accept(3),  ssl(3),
       SSL_set_connect_state(3), bio(3)



                                              SSL_do_handshake(3)