]>
Commit | Line | Data |
---|---|---|
cc99526d RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
1e4e5492 | 5 | SSL_shutdown - shut down a TLS/SSL connection |
cc99526d RL |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | int SSL_shutdown(SSL *ssl); | |
12 | ||
13 | =head1 DESCRIPTION | |
14 | ||
1bc74519 | 15 | SSL_shutdown() shuts down an active TLS/SSL connection. It sends the |
8e495e4a LJ |
16 | "close notify" shutdown alert to the peer. |
17 | ||
18 | =head1 NOTES | |
19 | ||
20 | SSL_shutdown() tries to send the "close notify" shutdown alert to the peer. | |
21 | Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and | |
22 | a currently open session is considered closed and good and will be kept in the | |
23 | session cache for further reuse. | |
24 | ||
9e09eebf | 25 | The shutdown procedure consists of 2 steps: the sending of the "close notify" |
b2ed4629 LJ |
26 | shutdown alert and the reception of the peer's "close notify" shutdown |
27 | alert. According to the TLS standard, it is acceptable for an application | |
28 | to only send its shutdown alert and then close the underlying connection | |
29 | without waiting for the peer's response (this way resources can be saved, | |
30 | as the process can already terminate or serve another connection). | |
31 | When the underlying connection shall be used for more communications, the | |
32 | complete shutdown procedure (bidirectional "close notify" alerts) must be | |
33 | performed, so that the peers stay synchronized. | |
34 | ||
35 | SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step | |
36 | behaviour. | |
9e09eebf LJ |
37 | |
38 | =over 4 | |
39 | ||
40 | =item When the application is the first party to send the "close notify" | |
4a64f3d6 | 41 | alert, SSL_shutdown() will only send the alert and then set the |
9e09eebf | 42 | SSL_SENT_SHUTDOWN flag (so that the session is considered good and will |
b2ed4629 LJ |
43 | be kept in cache). SSL_shutdown() will then return with 0. If a unidirectional |
44 | shutdown is enough (the underlying connection shall be closed anyway), this | |
45 | first call to SSL_shutdown() is sufficient. In order to complete the | |
46 | bidirectional shutdown handshake, SSL_shutdown() must be called again. | |
9e09eebf LJ |
47 | The second call will make SSL_shutdown() wait for the peer's "close notify" |
48 | shutdown alert. On success, the second call to SSL_shutdown() will return | |
49 | with 1. | |
50 | ||
51 | =item If the peer already sent the "close notify" alert B<and> it was | |
d93eb21c | 52 | already processed implicitly inside another function |
9b86974e | 53 | (L<SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set. |
d93eb21c LJ |
54 | SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN |
55 | flag and will immediately return with 1. | |
56 | Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the | |
9b86974e | 57 | SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call. |
9e09eebf LJ |
58 | |
59 | =back | |
60 | ||
61 | It is therefore recommended, to check the return value of SSL_shutdown() | |
62 | and call SSL_shutdown() again, if the bidirectional shutdown is not yet | |
45f55f6a | 63 | complete (return value of the first call is 0). |
9e09eebf | 64 | |
1bc74519 | 65 | The behaviour of SSL_shutdown() additionally depends on the underlying BIO. |
cc99526d | 66 | |
1e4e5492 | 67 | If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the |
9e09eebf | 68 | handshake step has been finished or an error occurred. |
cc99526d | 69 | |
1e4e5492 | 70 | If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return |
cc99526d RL |
71 | when the underlying BIO could not satisfy the needs of SSL_shutdown() |
72 | to continue the handshake. In this case a call to SSL_get_error() with the | |
1e4e5492 UM |
73 | return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or |
74 | B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after | |
cc99526d RL |
75 | taking appropriate action to satisfy the needs of SSL_shutdown(). |
76 | The action depends on the underlying BIO. When using a non-blocking socket, | |
77 | nothing is to be done, but select() can be used to check for the required | |
78 | condition. When using a buffering BIO, like a BIO pair, data must be written | |
79 | into or retrieved out of the BIO before being able to continue. | |
80 | ||
cdd7c3ce LJ |
81 | SSL_shutdown() can be modified to only set the connection to "shutdown" |
82 | state but not actually send the "close notify" alert messages, | |
9b86974e | 83 | see L<SSL_CTX_set_quiet_shutdown(3)>. |
cdd7c3ce LJ |
84 | When "quiet shutdown" is enabled, SSL_shutdown() will always succeed |
85 | and return 1. | |
86 | ||
cc99526d RL |
87 | =head1 RETURN VALUES |
88 | ||
89 | The following return values can occur: | |
90 | ||
91 | =over 4 | |
92 | ||
c8919dde | 93 | =item Z<>0 |
cc99526d | 94 | |
b2ed4629 LJ |
95 | The shutdown is not yet finished. Call SSL_shutdown() for a second time, |
96 | if a bidirectional shutdown shall be performed. | |
9b86974e | 97 | The output of L<SSL_get_error(3)> may be misleading, as an |
9e09eebf | 98 | erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred. |
cc99526d | 99 | |
c8919dde | 100 | =item Z<>1 |
5cc27077 NA |
101 | |
102 | The shutdown was successfully completed. The "close notify" alert was sent | |
103 | and the peer's "close notify" alert was received. | |
104 | ||
fe757304 | 105 | =item E<lt>0 |
cc99526d | 106 | |
1e4e5492 | 107 | The shutdown was not successful because a fatal error occurred either |
9e09eebf | 108 | at the protocol level or a connection failure occurred. It can also occur if |
cc99526d | 109 | action is need to continue the operation for non-blocking BIOs. |
9b86974e | 110 | Call L<SSL_get_error(3)> with the return value B<ret> |
9e09eebf | 111 | to find out the reason. |
cc99526d RL |
112 | |
113 | =back | |
114 | ||
115 | =head1 SEE ALSO | |
116 | ||
9b86974e RS |
117 | L<SSL_get_error(3)>, L<SSL_connect(3)>, |
118 | L<SSL_accept(3)>, L<SSL_set_shutdown(3)>, | |
119 | L<SSL_CTX_set_quiet_shutdown(3)>, | |
120 | L<SSL_clear(3)>, L<SSL_free(3)>, | |
b97fdb57 | 121 | L<ssl(7)>, L<bio(7)> |
cc99526d | 122 | |
e2f92610 RS |
123 | =head1 COPYRIGHT |
124 | ||
125 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
126 | ||
127 | Licensed under the OpenSSL license (the "License"). You may not use | |
128 | this file except in compliance with the License. You can obtain a copy | |
129 | in the file LICENSE in the source distribution or at | |
130 | L<https://www.openssl.org/source/license.html>. | |
131 | ||
132 | =cut |