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