]>
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 | ||
38 | =head1 RETURN VALUES | |
39 | ||
40 | The following return values can occur: | |
41 | ||
42 | =over 4 | |
43 | ||
c8919dde | 44 | =item Z<>0 |
cc99526d | 45 | |
1e4e5492 UM |
46 | The TLS/SSL handshake was not successful but was shut down controlled and |
47 | by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the | |
cc99526d RL |
48 | return value B<ret> to find out the reason. |
49 | ||
c8919dde | 50 | =item Z<>1 |
5cc27077 NA |
51 | |
52 | The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been | |
53 | established. | |
54 | ||
53fe8d5b | 55 | =item E<lt>0 |
cc99526d | 56 | |
1e4e5492 UM |
57 | The TLS/SSL handshake was not successful, because a fatal error occurred either |
58 | at the protocol level or a connection failure occurred. The shutdown was | |
59 | not clean. It can also occur of action is need to continue the operation | |
cc99526d RL |
60 | for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> |
61 | to find out the reason. | |
62 | ||
63 | =back | |
64 | ||
65 | =head1 SEE ALSO | |
66 | ||
9b86974e | 67 | L<SSL_get_error(3)>, L<SSL_accept(3)>, |
b97fdb57 | 68 | L<SSL_shutdown(3)>, L<ssl(7)>, L<bio(7)>, |
9b86974e RS |
69 | L<SSL_set_connect_state(3)>, |
70 | L<SSL_do_handshake(3)>, | |
71 | L<SSL_CTX_new(3)> | |
cc99526d | 72 | |
e2f92610 RS |
73 | =head1 COPYRIGHT |
74 | ||
75 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
76 | ||
77 | Licensed under the OpenSSL license (the "License"). You may not use | |
78 | this file except in compliance with the License. You can obtain a copy | |
79 | in the file LICENSE in the source distribution or at | |
80 | L<https://www.openssl.org/source/license.html>. | |
81 | ||
82 | =cut |