SSL_connect.pod revision 76866
168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 568651SkrisSSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server 668651Skris 768651Skris=head1 SYNOPSIS 868651Skris 968651Skris #include <openssl/ssl.h> 1068651Skris 1168651Skris int SSL_connect(SSL *ssl); 1268651Skris 1368651Skris=head1 DESCRIPTION 1468651Skris 1568651SkrisSSL_connect() initiates the TLS/SSL handshake with a server. The communication 1668651Skrischannel must already have been set and assigned to the B<ssl> by setting an 1768651Skrisunderlying B<BIO>. 1868651Skris 1968651Skris=head1 NOTES 2068651Skris 2168651SkrisThe behaviour of SSL_connect() depends on the underlying BIO. 2268651Skris 2368651SkrisIf the underlying BIO is B<blocking>, SSL_connect() will only return once the 2468651Skrishandshake has been finished or an error occurred. 2568651Skris 2668651SkrisIf the underlying BIO is B<non-blocking>, SSL_connect() will also return 2768651Skriswhen the underlying BIO could not satisfy the needs of SSL_connect() 2868651Skristo continue the handshake. In this case a call to SSL_get_error() with the 2968651Skrisreturn value of SSL_connect() will yield B<SSL_ERROR_WANT_READ> or 3068651SkrisB<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after 3168651Skristaking appropriate action to satisfy the needs of SSL_connect(). 3268651SkrisThe action depends on the underlying BIO. When using a non-blocking socket, 3368651Skrisnothing is to be done, but select() can be used to check for the required 3468651Skriscondition. When using a buffering BIO, like a BIO pair, data must be written 3568651Skrisinto or retrieved out of the BIO before being able to continue. 3668651Skris 3776866SkrisWhen using a generic method (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>), it 3876866Skrisis necessary to call L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> 3976866Skrisbefore calling SSL_connect() to explicitly switch the B<ssl> to client 4076866Skrismode. 4176866Skris 4268651Skris=head1 RETURN VALUES 4368651Skris 4468651SkrisThe following return values can occur: 4568651Skris 4668651Skris=over 4 4768651Skris 4868651Skris=item 1 4968651Skris 5068651SkrisThe TLS/SSL handshake was successfully completed, a TLS/SSL connection has been 5168651Skrisestablished. 5268651Skris 5368651Skris=item 0 5468651Skris 5568651SkrisThe TLS/SSL handshake was not successful but was shut down controlled and 5668651Skrisby the specifications of the TLS/SSL protocol. Call SSL_get_error() with the 5768651Skrisreturn value B<ret> to find out the reason. 5868651Skris 5972613Skris=item E<lt>0 6068651Skris 6168651SkrisThe TLS/SSL handshake was not successful, because a fatal error occurred either 6268651Skrisat the protocol level or a connection failure occurred. The shutdown was 6368651Skrisnot clean. It can also occur of action is need to continue the operation 6468651Skrisfor non-blocking BIOs. Call SSL_get_error() with the return value B<ret> 6568651Skristo find out the reason. 6668651Skris 6768651Skris=back 6868651Skris 6968651Skris=head1 SEE ALSO 7068651Skris 7168651SkrisL<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_accept(3)|SSL_accept(3)>, 7276866SkrisL<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, 7376866SkrisL<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, 7476866SkrisL<SSL_CTX_new(3)|SSL_CTX_new(3)> 7568651Skris 7668651Skris=cut 77