1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosSSL_do_handshake - perform a TLS/SSL handshake 6*4724848cSchristos 7*4724848cSchristos=head1 SYNOPSIS 8*4724848cSchristos 9*4724848cSchristos #include <openssl/ssl.h> 10*4724848cSchristos 11*4724848cSchristos int SSL_do_handshake(SSL *ssl); 12*4724848cSchristos 13*4724848cSchristos=head1 DESCRIPTION 14*4724848cSchristos 15*4724848cSchristosSSL_do_handshake() will wait for a SSL/TLS handshake to take place. If the 16*4724848cSchristosconnection is in client mode, the handshake will be started. The handshake 17*4724848cSchristosroutines may have to be explicitly set in advance using either 18*4724848cSchristosL<SSL_set_connect_state(3)> or 19*4724848cSchristosL<SSL_set_accept_state(3)>. 20*4724848cSchristos 21*4724848cSchristos=head1 NOTES 22*4724848cSchristos 23*4724848cSchristosThe behaviour of SSL_do_handshake() depends on the underlying BIO. 24*4724848cSchristos 25*4724848cSchristosIf the underlying BIO is B<blocking>, SSL_do_handshake() will only return 26*4724848cSchristosonce the handshake has been finished or an error occurred. 27*4724848cSchristos 28*4724848cSchristosIf the underlying BIO is B<nonblocking>, SSL_do_handshake() will also return 29*4724848cSchristoswhen the underlying BIO could not satisfy the needs of SSL_do_handshake() 30*4724848cSchristosto continue the handshake. In this case a call to SSL_get_error() with the 31*4724848cSchristosreturn value of SSL_do_handshake() will yield B<SSL_ERROR_WANT_READ> or 32*4724848cSchristosB<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after 33*4724848cSchristostaking appropriate action to satisfy the needs of SSL_do_handshake(). 34*4724848cSchristosThe action depends on the underlying BIO. When using a nonblocking socket, 35*4724848cSchristosnothing is to be done, but select() can be used to check for the required 36*4724848cSchristoscondition. When using a buffering BIO, like a BIO pair, data must be written 37*4724848cSchristosinto or retrieved out of the BIO before being able to continue. 38*4724848cSchristos 39*4724848cSchristos=head1 RETURN VALUES 40*4724848cSchristos 41*4724848cSchristosThe following return values can occur: 42*4724848cSchristos 43*4724848cSchristos=over 4 44*4724848cSchristos 45*4724848cSchristos=item Z<>0 46*4724848cSchristos 47*4724848cSchristosThe TLS/SSL handshake was not successful but was shut down controlled and 48*4724848cSchristosby the specifications of the TLS/SSL protocol. Call SSL_get_error() with the 49*4724848cSchristosreturn value B<ret> to find out the reason. 50*4724848cSchristos 51*4724848cSchristos=item Z<>1 52*4724848cSchristos 53*4724848cSchristosThe TLS/SSL handshake was successfully completed, a TLS/SSL connection has been 54*4724848cSchristosestablished. 55*4724848cSchristos 56*4724848cSchristos=item E<lt>0 57*4724848cSchristos 58*4724848cSchristosThe TLS/SSL handshake was not successful because a fatal error occurred either 59*4724848cSchristosat the protocol level or a connection failure occurred. The shutdown was 60*4724848cSchristosnot clean. It can also occur if action is needed to continue the operation 61*4724848cSchristosfor nonblocking BIOs. Call SSL_get_error() with the return value B<ret> 62*4724848cSchristosto find out the reason. 63*4724848cSchristos 64*4724848cSchristos=back 65*4724848cSchristos 66*4724848cSchristos=head1 SEE ALSO 67*4724848cSchristos 68*4724848cSchristosL<SSL_get_error(3)>, L<SSL_connect(3)>, 69*4724848cSchristosL<SSL_accept(3)>, L<ssl(7)>, L<bio(7)>, 70*4724848cSchristosL<SSL_set_connect_state(3)> 71*4724848cSchristos 72*4724848cSchristos=head1 COPYRIGHT 73*4724848cSchristos 74*4724848cSchristosCopyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved. 75*4724848cSchristos 76*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 77*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 78*4724848cSchristosin the file LICENSE in the source distribution or at 79*4724848cSchristosL<https://www.openssl.org/source/license.html>. 80*4724848cSchristos 81*4724848cSchristos=cut 82