]>
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 |
8e593f0a | 16 | close_notify shutdown alert to the peer. |
8e495e4a LJ |
17 | |
18 | =head1 NOTES | |
19 | ||
8e593f0a | 20 | SSL_shutdown() tries to send the close_notify shutdown alert to the peer. |
8e495e4a LJ |
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 | ||
8e593f0a KR |
25 | The shutdown procedure consists of two steps: sending of the close_notify |
26 | shutdown alert, and reception of the peer's close_notify shutdown alert. | |
27 | The order of those two steps depends on the application. | |
28 | ||
29 | It is acceptable for an application to only send its shutdown alert and | |
30 | then close the underlying connection without waiting for the peer's response. | |
31 | This way resources can be saved, as the process can already terminate or | |
32 | serve another connection. | |
33 | This should only be done when it is known that the other side will not send more | |
34 | data, otherwise there is a risk of a truncation attack. | |
b2ed4629 | 35 | |
8e593f0a KR |
36 | When a client only writes and never reads from the connection, and the server |
37 | has sent a session ticket to establish a session, the client might not be able | |
38 | to resume the session because it did not received and process the session ticket | |
39 | from the server. | |
40 | In case the application wants to be able to resume the session, it is recommended to | |
41 | do a complete shutdown procedure (bidirectional close_notify alerts). | |
42 | ||
43 | When the underlying connection shall be used for more communications, the | |
44 | complete shutdown procedure must be performed, so that the peers stay | |
45 | synchronized. | |
9e09eebf | 46 | |
2f6f913e KR |
47 | SSL_shutdown() only closes the write direction. |
48 | It is not possible to call SSL_write() after calling SSL_shutdown(). | |
49 | The read direction is closed by the peer. | |
50 | ||
51 | =head2 First to close the connection | |
9e09eebf | 52 | |
8e593f0a | 53 | When the application is the first party to send the close_notify |
4a64f3d6 | 54 | alert, SSL_shutdown() will only send the alert and then set the |
9e09eebf | 55 | SSL_SENT_SHUTDOWN flag (so that the session is considered good and will |
2f6f913e | 56 | be kept in the cache). |
8e593f0a KR |
57 | If successful, SSL_shutdown() will return 0. |
58 | ||
2f6f913e | 59 | If a unidirectional shutdown is enough (the underlying connection shall be |
8e593f0a | 60 | closed anyway), this first successful call to SSL_shutdown() is sufficient. |
2f6f913e KR |
61 | |
62 | In order to complete the bidirectional shutdown handshake, the peer needs | |
8e593f0a | 63 | to send back a close_notify alert. |
2f6f913e KR |
64 | The SSL_RECEIVED_SHUTDOWN flag will be set after receiving and processing |
65 | it. | |
2f6f913e | 66 | |
8e593f0a | 67 | The peer is still allowed to send data after receiving the close_notify |
2f6f913e | 68 | event. |
8e593f0a KR |
69 | When it is done sending data, it will send the close_notify alert. |
70 | SSL_read() should be called until all data is received. | |
2f6f913e KR |
71 | SSL_read() will indicate the end of the peer data by returning <= 0 |
72 | and SSL_get_error() returning SSL_ERROR_ZERO_RETURN. | |
2f6f913e KR |
73 | |
74 | =head2 Peer closes the connection | |
75 | ||
8e593f0a | 76 | If the peer already sent the close_notify alert B<and> it was |
d93eb21c | 77 | already processed implicitly inside another function |
9b86974e | 78 | (L<SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set. |
2f6f913e KR |
79 | SSL_read() will return <= 0 in that case, and SSL_get_error() will return |
80 | SSL_ERROR_ZERO_RETURN. | |
8e593f0a KR |
81 | SSL_shutdown() will send the close_notify alert, set the SSL_SENT_SHUTDOWN |
82 | flag. | |
83 | If successful, SSL_shutdown() will return 1. | |
84 | ||
d93eb21c | 85 | Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the |
9b86974e | 86 | SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call. |
9e09eebf | 87 | |
2f6f913e | 88 | =head1 NOTES |
9e09eebf | 89 | |
1bc74519 | 90 | The behaviour of SSL_shutdown() additionally depends on the underlying BIO. |
1e4e5492 | 91 | If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the |
9e09eebf | 92 | handshake step has been finished or an error occurred. |
cc99526d | 93 | |
1e4e5492 | 94 | If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return |
cc99526d RL |
95 | when the underlying BIO could not satisfy the needs of SSL_shutdown() |
96 | to continue the handshake. In this case a call to SSL_get_error() with the | |
1e4e5492 UM |
97 | return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or |
98 | B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after | |
cc99526d RL |
99 | taking appropriate action to satisfy the needs of SSL_shutdown(). |
100 | The action depends on the underlying BIO. When using a non-blocking socket, | |
101 | nothing is to be done, but select() can be used to check for the required | |
102 | condition. When using a buffering BIO, like a BIO pair, data must be written | |
103 | into or retrieved out of the BIO before being able to continue. | |
104 | ||
8e593f0a KR |
105 | After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again |
106 | to wait for the peer's close_notify alert. | |
107 | SSL_shutdown() will return 1 in that case. | |
108 | However, it is recommended to wait for it using SSL_read() instead. | |
109 | ||
cdd7c3ce | 110 | SSL_shutdown() can be modified to only set the connection to "shutdown" |
8e593f0a | 111 | state but not actually send the close_notify alert messages, |
9b86974e | 112 | see L<SSL_CTX_set_quiet_shutdown(3)>. |
cdd7c3ce LJ |
113 | When "quiet shutdown" is enabled, SSL_shutdown() will always succeed |
114 | and return 1. | |
115 | ||
cc99526d RL |
116 | =head1 RETURN VALUES |
117 | ||
118 | The following return values can occur: | |
119 | ||
120 | =over 4 | |
121 | ||
c8919dde | 122 | =item Z<>0 |
cc99526d | 123 | |
8e593f0a | 124 | The shutdown is not yet finished: the close_notify was sent but the peer |
2f6f913e | 125 | did not send it back yet. |
8e593f0a | 126 | Call SSL_read() to do a bidirectional shutdown. |
9b86974e | 127 | The output of L<SSL_get_error(3)> may be misleading, as an |
9e09eebf | 128 | erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred. |
cc99526d | 129 | |
c8919dde | 130 | =item Z<>1 |
5cc27077 | 131 | |
8e593f0a KR |
132 | The shutdown was successfully completed. The close_notify alert was sent |
133 | and the peer's close_notify alert was received. | |
5cc27077 | 134 | |
fe757304 | 135 | =item E<lt>0 |
cc99526d | 136 | |
2f6f913e KR |
137 | The shutdown was not successful. |
138 | Call L<SSL_get_error(3)> with the return value B<ret> to find out the reason. | |
139 | It can occur if an action is needed to continue the operation for non-blocking | |
140 | BIOs. | |
141 | ||
142 | It can also occur when not all data was read using SSL_read(). | |
cc99526d RL |
143 | |
144 | =back | |
145 | ||
146 | =head1 SEE ALSO | |
147 | ||
9b86974e RS |
148 | L<SSL_get_error(3)>, L<SSL_connect(3)>, |
149 | L<SSL_accept(3)>, L<SSL_set_shutdown(3)>, | |
150 | L<SSL_CTX_set_quiet_shutdown(3)>, | |
151 | L<SSL_clear(3)>, L<SSL_free(3)>, | |
b97fdb57 | 152 | L<ssl(7)>, L<bio(7)> |
cc99526d | 153 | |
e2f92610 RS |
154 | =head1 COPYRIGHT |
155 | ||
c4d3c19b | 156 | Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
157 | |
158 | Licensed under the OpenSSL license (the "License"). You may not use | |
159 | this file except in compliance with the License. You can obtain a copy | |
160 | in the file LICENSE in the source distribution or at | |
161 | L<https://www.openssl.org/source/license.html>. | |
162 | ||
163 | =cut |