]>
Commit | Line | Data |
---|---|---|
02b7ec88 LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_do_handshake - perform a TLS/SSL handshake | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | int SSL_do_handshake(SSL *ssl); | |
12 | ||
13 | =head1 DESCRIPTION | |
14 | ||
15 | SSL_do_handshake() will wait for a SSL/TLS handshake to take place. If the | |
16 | connection is in client mode, the handshake will be started. The handshake | |
17 | routines may have to be explicitly set in advance using either | |
9b86974e RS |
18 | L<SSL_set_connect_state(3)> or |
19 | L<SSL_set_accept_state(3)>. | |
02b7ec88 LJ |
20 | |
21 | =head1 NOTES | |
22 | ||
23 | The behaviour of SSL_do_handshake() depends on the underlying BIO. | |
24 | ||
25 | If the underlying BIO is B<blocking>, SSL_do_handshake() will only return | |
63eab8a6 | 26 | once the handshake has been finished or an error occurred. |
02b7ec88 LJ |
27 | |
28 | If the underlying BIO is B<non-blocking>, SSL_do_handshake() will also return | |
29 | when the underlying BIO could not satisfy the needs of SSL_do_handshake() | |
30 | to continue the handshake. In this case a call to SSL_get_error() with the | |
31 | return value of SSL_do_handshake() will yield B<SSL_ERROR_WANT_READ> or | |
32 | B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after | |
33 | taking appropriate action to satisfy the needs of SSL_do_handshake(). | |
34 | The action depends on the underlying BIO. When using a non-blocking socket, | |
35 | nothing is to be done, but select() can be used to check for the required | |
36 | condition. When using a buffering BIO, like a BIO pair, data must be written | |
37 | into or retrieved out of the BIO before being able to continue. | |
38 | ||
39 | =head1 RETURN VALUES | |
40 | ||
41 | The following return values can occur: | |
42 | ||
43 | =over 4 | |
44 | ||
c8919dde | 45 | =item Z<>0 |
02b7ec88 LJ |
46 | |
47 | The TLS/SSL handshake was not successful but was shut down controlled and | |
48 | by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the | |
49 | return value B<ret> to find out the reason. | |
50 | ||
c8919dde | 51 | =item Z<>1 |
5cc27077 NA |
52 | |
53 | The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been | |
54 | established. | |
55 | ||
02b7ec88 LJ |
56 | =item E<lt>0 |
57 | ||
58 | The TLS/SSL handshake was not successful because a fatal error occurred either | |
59 | at the protocol level or a connection failure occurred. The shutdown was | |
004f5708 | 60 | not clean. It can also occur if action is needed to continue the operation |
02b7ec88 LJ |
61 | for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> |
62 | to find out the reason. | |
63 | ||
64 | =back | |
65 | ||
66 | =head1 SEE ALSO | |
67 | ||
9b86974e | 68 | L<SSL_get_error(3)>, L<SSL_connect(3)>, |
b97fdb57 | 69 | L<SSL_accept(3)>, L<ssl(7)>, L<bio(7)>, |
9b86974e | 70 | L<SSL_set_connect_state(3)> |
02b7ec88 | 71 | |
e2f92610 RS |
72 | =head1 COPYRIGHT |
73 | ||
004f5708 | 74 | Copyright 2002-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
75 | |
76 | Licensed under the OpenSSL license (the "License"). You may not use | |
77 | this file except in compliance with the License. You can obtain a copy | |
78 | in the file LICENSE in the source distribution or at | |
79 | L<https://www.openssl.org/source/license.html>. | |
80 | ||
81 | =cut |