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