1139823Simp=pod 221830Sjoerg 321830Sjoerg=head1 NAME 47055Sdg 57055SdgSSL_do_handshake - perform a TLS/SSL handshake 67055Sdg 77055Sdg=head1 SYNOPSIS 87055Sdg 97055Sdg #include <openssl/ssl.h> 107055Sdg 117055Sdg int SSL_do_handshake(SSL *ssl); 127055Sdg 137055Sdg=head1 DESCRIPTION 147055Sdg 157055SdgSSL_do_handshake() will wait for a SSL/TLS handshake to take place. If the 167055Sdgconnection is in client mode, the handshake will be started. The handshake 177055Sdgroutines may have to be explicitly set in advance using either 187055SdgL<SSL_set_connect_state(3)> or 197055SdgL<SSL_set_accept_state(3)>. 207055Sdg 217055Sdg=head1 NOTES 227055Sdg 237055SdgThe behaviour of SSL_do_handshake() depends on the underlying BIO. 247055Sdg 257055SdgIf the underlying BIO is B<blocking>, SSL_do_handshake() will only return 267055Sdgonce the handshake has been finished or an error occurred. 277055Sdg 287055SdgIf the underlying BIO is B<nonblocking>, SSL_do_handshake() will also return 297055Sdgwhen the underlying BIO could not satisfy the needs of SSL_do_handshake() 307055Sdgto continue the handshake. In this case a call to SSL_get_error() with the 317055Sdgreturn value of SSL_do_handshake() will yield B<SSL_ERROR_WANT_READ> or 327055SdgB<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after 337055Sdgtaking appropriate action to satisfy the needs of SSL_do_handshake(). 347055SdgThe action depends on the underlying BIO. When using a nonblocking socket, 357061Sdgnothing is to be done, but select() can be used to check for the required 3650477Spetercondition. When using a buffering BIO, like a BIO pair, data must be written 377055Sdginto or retrieved out of the BIO before being able to continue. 387055Sdg 3932356Seivind=head1 RETURN VALUES 4032350Seivind 4154263SshinThe following return values can occur: 4231742Seivind 43105577Srwatson=over 4 4431742Seivind 457055Sdg=item Z<>0 467055Sdg 4793375SmdoddThe TLS/SSL handshake was not successful but was shut down controlled and 4893375Smdoddby the specifications of the TLS/SSL protocol. Call SSL_get_error() with the 497055Sdgreturn value B<ret> to find out the reason. 5093375Smdodd 517055Sdg=item Z<>1 5293375Smdodd 537055SdgThe TLS/SSL handshake was successfully completed, a TLS/SSL connection has been 547055Sdgestablished. 55112271Smdodd 567055Sdg=item E<lt>0 577055Sdg 58112271SmdoddThe TLS/SSL handshake was not successful because a fatal error occurred either 5993375Smdoddat the protocol level or a connection failure occurred. The shutdown was 6093375Smdoddnot clean. It can also occur if action is needed to continue the operation 6193375Smdoddfor nonblocking BIOs. Call SSL_get_error() with the return value B<ret> 6293373Smdoddto find out the reason. 637055Sdg 6454263Sshin=back 657055Sdg 667055Sdg=head1 SEE ALSO 6732350Seivind 687055SdgL<SSL_get_error(3)>, L<SSL_connect(3)>, 6954263SshinL<SSL_accept(3)>, L<ssl(7)>, L<bio(7)>, 7054263SshinL<SSL_set_connect_state(3)> 7154263Sshin 727055Sdg=head1 COPYRIGHT 7311819Sjulian 7421830SjoergCopyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved. 7511819Sjulian 7611819SjulianLicensed under the Apache License 2.0 (the "License"). You may not use 7711819Sjulianthis file except in compliance with the License. You can obtain a copy 787055Sdgin the file LICENSE in the source distribution or at 797055SdgL<https://www.openssl.org/source/license.html>. 807055Sdg 817055Sdg=cut 8221830Sjoerg