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