1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_do_handshake - perform a TLS/SSL handshake
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  int SSL_do_handshake(SSL *ssl);
   12: 
   13: =head1 DESCRIPTION
   14: 
   15: SSL_do_handshake() will wait for a SSL/TLS handshake to take place. If the
   16: connection is in client mode, the handshake will be started. The handshake
   17: routines may have to be explicitly set in advance using either
   18: L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or
   19: L<SSL_set_accept_state(3)|SSL_set_accept_state(3)>.
   20: 
   21: =head1 NOTES
   22: 
   23: The behaviour of SSL_do_handshake() depends on the underlying BIO.
   24: 
   25: If the underlying BIO is B<blocking>, SSL_do_handshake() will only return
   26: once the handshake has been finished or an error occurred, except for SGC
   27: (Server Gated Cryptography). For SGC, SSL_do_handshake() may return with -1,
   28: but SSL_get_error() will yield B<SSL_ERROR_WANT_READ/WRITE> and
   29: SSL_do_handshake() should be called again.
   30: 
   31: If the underlying BIO is B<non-blocking>, SSL_do_handshake() will also return
   32: when the underlying BIO could not satisfy the needs of SSL_do_handshake()
   33: to continue the handshake. In this case a call to SSL_get_error() with the
   34: return value of SSL_do_handshake() will yield B<SSL_ERROR_WANT_READ> or
   35: B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
   36: taking appropriate action to satisfy the needs of SSL_do_handshake().
   37: The action depends on the underlying BIO. When using a non-blocking socket,
   38: nothing is to be done, but select() can be used to check for the required
   39: condition. When using a buffering BIO, like a BIO pair, data must be written
   40: into or retrieved out of the BIO before being able to continue.
   41: 
   42: =head1 RETURN VALUES
   43: 
   44: The following return values can occur:
   45: 
   46: =over 4
   47: 
   48: =item 1
   49: 
   50: The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been
   51: established.
   52: 
   53: =item 0
   54: 
   55: The TLS/SSL handshake was not successful but was shut down controlled and
   56: by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the
   57: return value B<ret> to find out the reason.
   58: 
   59: =item E<lt>0
   60: 
   61: The TLS/SSL handshake was not successful because a fatal error occurred either
   62: at the protocol level or a connection failure occurred. The shutdown was
   63: not clean. It can also occur of action is need to continue the operation
   64: for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
   65: to find out the reason.
   66: 
   67: =back
   68: 
   69: =head1 SEE ALSO
   70: 
   71: L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>,
   72: L<SSL_accept(3)|SSL_accept(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
   73: L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>
   74: 
   75: =cut