166458Sdfr=pod 266458Sdfr 366458Sdfr=head1 NAME 466458Sdfr 566458SdfrSSL_do_handshake - perform a TLS/SSL handshake 666458Sdfr 766458Sdfr=head1 SYNOPSIS 866458Sdfr 966458Sdfr #include <openssl/ssl.h> 1066458Sdfr 1166458Sdfr int SSL_do_handshake(SSL *ssl); 1266458Sdfr 1366458Sdfr=head1 DESCRIPTION 1466458Sdfr 1566458SdfrSSL_do_handshake() will wait for a SSL/TLS handshake to take place. If the 1666458Sdfrconnection is in client mode, the handshake will be started. The handshake 1766458Sdfrroutines may have to be explicitly set in advance using either 1866458SdfrL<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or 1966458SdfrL<SSL_set_accept_state(3)|SSL_set_accept_state(3)>. 2066458Sdfr 2166458Sdfr=head1 NOTES 2266458Sdfr 2366458SdfrThe behaviour of SSL_do_handshake() depends on the underlying BIO. 2466458Sdfr 2566458SdfrIf the underlying BIO is B<blocking>, SSL_do_handshake() will only return 2666458Sdfronce the handshake has been finished or an error occurred. 2766458Sdfr 2866458SdfrIf the underlying BIO is B<non-blocking>, SSL_do_handshake() will also return 2966458Sdfrwhen the underlying BIO could not satisfy the needs of SSL_do_handshake() 3066458Sdfrto continue the handshake. In this case a call to SSL_get_error() with the 3166458Sdfrreturn value of SSL_do_handshake() will yield B<SSL_ERROR_WANT_READ> or 3266458SdfrB<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after 3366458Sdfrtaking appropriate action to satisfy the needs of SSL_do_handshake(). 3466458SdfrThe action depends on the underlying BIO. When using a non-blocking socket, 3583511Sdfrnothing is to be done, but select() can be used to check for the required 3696912Smarcelcondition. When using a buffering BIO, like a BIO pair, data must be written 3766458Sdfrinto or retrieved out of the BIO before being able to continue. 38143063Sjoerg 39143063Sjoerg=head1 RETURN VALUES 40143063Sjoerg 41143063SjoergThe following return values can occur: 4293264Sdillon 4388088Sjhb=over 4 44127253Smarcel 45127253Smarcel=item Z<>0 46143063Sjoerg 4766458SdfrThe TLS/SSL handshake was not successful but was shut down controlled and 4866458Sdfrby the specifications of the TLS/SSL protocol. Call SSL_get_error() with the 4966458Sdfrreturn value B<ret> to find out the reason. 5066458Sdfr 51127253Smarcel=item Z<>1 5266458Sdfr 5366458SdfrThe TLS/SSL handshake was successfully completed, a TLS/SSL connection has been 54124478Sdesestablished. 55132871Smarcel 56123419Speter=item E<lt>0 57114208Smarcel 58114208SmarcelThe TLS/SSL handshake was not successful because a fatal error occurred either 59114208Smarcelat the protocol level or a connection failure occurred. The shutdown was 60114208Smarcelnot clean. It can also occur of action is need to continue the operation 6183511Sdfrfor non-blocking BIOs. Call SSL_get_error() with the return value B<ret> 62114208Smarcelto find out the reason. 63114208Smarcel 64114208Smarcel=back 65114208Smarcel 66114208Smarcel=head1 SEE ALSO 6783511Sdfr 68114208SmarcelL<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_connect(3)|SSL_connect(3)>, 69114208SmarcelL<SSL_accept(3)|SSL_accept(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, 70114208SmarcelL<SSL_set_connect_state(3)|SSL_set_connect_state(3)> 7183511Sdfr 72114208Smarcel=cut 73114208Smarcel