1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosSSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server 6*4724848cSchristos 7*4724848cSchristos=head1 SYNOPSIS 8*4724848cSchristos 9*4724848cSchristos #include <openssl/ssl.h> 10*4724848cSchristos 11*4724848cSchristos int SSL_connect(SSL *ssl); 12*4724848cSchristos 13*4724848cSchristos=head1 DESCRIPTION 14*4724848cSchristos 15*4724848cSchristosSSL_connect() initiates the TLS/SSL handshake with a server. The communication 16*4724848cSchristoschannel must already have been set and assigned to the B<ssl> by setting an 17*4724848cSchristosunderlying B<BIO>. 18*4724848cSchristos 19*4724848cSchristos=head1 NOTES 20*4724848cSchristos 21*4724848cSchristosThe behaviour of SSL_connect() depends on the underlying BIO. 22*4724848cSchristos 23*4724848cSchristosIf the underlying BIO is B<blocking>, SSL_connect() will only return once the 24*4724848cSchristoshandshake has been finished or an error occurred. 25*4724848cSchristos 26*4724848cSchristosIf the underlying BIO is B<nonblocking>, SSL_connect() will also return 27*4724848cSchristoswhen the underlying BIO could not satisfy the needs of SSL_connect() 28*4724848cSchristosto continue the handshake, indicating the problem by the return value -1. 29*4724848cSchristosIn this case a call to SSL_get_error() with the 30*4724848cSchristosreturn value of SSL_connect() will yield B<SSL_ERROR_WANT_READ> or 31*4724848cSchristosB<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after 32*4724848cSchristostaking appropriate action to satisfy the needs of SSL_connect(). 33*4724848cSchristosThe action depends on the underlying BIO. When using a nonblocking socket, 34*4724848cSchristosnothing is to be done, but select() can be used to check for the required 35*4724848cSchristoscondition. When using a buffering BIO, like a BIO pair, data must be written 36*4724848cSchristosinto or retrieved out of the BIO before being able to continue. 37*4724848cSchristos 38*4724848cSchristosMany systems implement Nagle's algorithm by default which means that it will 39*4724848cSchristosbuffer outgoing TCP data if a TCP packet has already been sent for which no 40*4724848cSchristoscorresponding ACK has been received yet from the peer. This can have performance 41*4724848cSchristosimpacts after a successful TLSv1.3 handshake or a successful TLSv1.2 (or below) 42*4724848cSchristosresumption handshake, because the last peer to communicate in the handshake is 43*4724848cSchristosthe client. If the client is also the first to send application data (as is 44*4724848cSchristostypical for many protocols) then this data could be buffered until an ACK has 45*4724848cSchristosbeen received for the final handshake message. 46*4724848cSchristos 47*4724848cSchristosThe B<TCP_NODELAY> socket option is often available to disable Nagle's 48*4724848cSchristosalgorithm. If an application opts to disable Nagle's algorithm consideration 49*4724848cSchristosshould be given to turning it back on again later if appropriate. The helper 50*4724848cSchristosfunction BIO_set_tcp_ndelay() can be used to turn on or off the B<TCP_NODELAY> 51*4724848cSchristosoption. 52*4724848cSchristos 53*4724848cSchristos=head1 RETURN VALUES 54*4724848cSchristos 55*4724848cSchristosThe following return values can occur: 56*4724848cSchristos 57*4724848cSchristos=over 4 58*4724848cSchristos 59*4724848cSchristos=item Z<>0 60*4724848cSchristos 61*4724848cSchristosThe TLS/SSL handshake was not successful but was shut down controlled and 62*4724848cSchristosby the specifications of the TLS/SSL protocol. Call SSL_get_error() with the 63*4724848cSchristosreturn value B<ret> to find out the reason. 64*4724848cSchristos 65*4724848cSchristos=item Z<>1 66*4724848cSchristos 67*4724848cSchristosThe TLS/SSL handshake was successfully completed, a TLS/SSL connection has been 68*4724848cSchristosestablished. 69*4724848cSchristos 70*4724848cSchristos=item E<lt>0 71*4724848cSchristos 72*4724848cSchristosThe TLS/SSL handshake was not successful, because a fatal error occurred either 73*4724848cSchristosat the protocol level or a connection failure occurred. The shutdown was 74*4724848cSchristosnot clean. It can also occur if action is needed to continue the operation 75*4724848cSchristosfor nonblocking BIOs. Call SSL_get_error() with the return value B<ret> 76*4724848cSchristosto find out the reason. 77*4724848cSchristos 78*4724848cSchristos=back 79*4724848cSchristos 80*4724848cSchristos=head1 SEE ALSO 81*4724848cSchristos 82*4724848cSchristosL<SSL_get_error(3)>, L<SSL_accept(3)>, 83*4724848cSchristosL<SSL_shutdown(3)>, L<ssl(7)>, L<bio(7)>, 84*4724848cSchristosL<SSL_set_connect_state(3)>, 85*4724848cSchristosL<SSL_do_handshake(3)>, 86*4724848cSchristosL<SSL_CTX_new(3)> 87*4724848cSchristos 88*4724848cSchristos=head1 COPYRIGHT 89*4724848cSchristos 90*4724848cSchristosCopyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. 91*4724848cSchristos 92*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 93*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 94*4724848cSchristosin the file LICENSE in the source distribution or at 95*4724848cSchristosL<https://www.openssl.org/source/license.html>. 96*4724848cSchristos 97*4724848cSchristos=cut 98