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