xref: /openssl/doc/man3/SSL_connect.pod (revision 5d632274)
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