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