| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "SSL_SHUTDOWN 3SSL" |
| 58 |
.TH SSL_SHUTDOWN 3SSL 2026-04-07 3.6.2 OpenSSL |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
SSL_shutdown, SSL_shutdown_ex \- shut down a TLS/SSL or QUIC connection |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& #include <openssl/ssl.h> |
| 69 |
\& |
| 70 |
\& int SSL_shutdown(SSL *ssl); |
| 71 |
\& |
| 72 |
\& typedef struct ssl_shutdown_ex_args_st { |
| 73 |
\& uint64_t quic_error_code; |
| 74 |
\& const char *quic_reason; |
| 75 |
\& } SSL_SHUTDOWN_EX_ARGS; |
| 76 |
\& |
| 77 |
\& _\|_owur int SSL_shutdown_ex(SSL *ssl, uint64_t flags, |
| 78 |
\& const SSL_SHUTDOWN_EX_ARGS *args, |
| 79 |
\& size_t args_len); |
| 80 |
.Ve |
| 81 |
.SH DESCRIPTION |
| 82 |
.IX Header "DESCRIPTION" |
| 83 |
\&\fBSSL_shutdown()\fR shuts down an active connection represented by an SSL object. \fIssl\fR \fBMUST NOT\fR be NULL. |
| 84 |
.PP |
| 85 |
\&\fBSSL_shutdown_ex()\fR is an extended version of \fBSSL_shutdown()\fR. If non-NULL, \fIargs\fR |
| 86 |
must point to a \fBSSL_SHUTDOWN_EX_ARGS\fR structure and \fIargs_len\fR must be set to |
| 87 |
\&\f(CWsizeof(SSL_SHUTDOWN_EX_ARGS)\fR. The \fBSSL_SHUTDOWN_EX_ARGS\fR structure must be |
| 88 |
zero-initialized. If \fIargs\fR is NULL, the behaviour is the same as passing a |
| 89 |
zero-initialised \fBSSL_SHUTDOWN_EX_ARGS\fR structure. Currently, all extended |
| 90 |
arguments relate to usage with QUIC, therefore this call functions identically |
| 91 |
to \fBSSL_shutdown()\fR when not being used with QUIC. |
| 92 |
.PP |
| 93 |
While the general operation of \fBSSL_shutdown()\fR is common between protocols, the |
| 94 |
exact nature of how a shutdown is performed depends on the underlying protocol |
| 95 |
being used. See the section below pertaining to each protocol for more |
| 96 |
information. |
| 97 |
.PP |
| 98 |
In general, calling \fBSSL_shutdown()\fR in nonblocking mode will initiate the |
| 99 |
shutdown process and return 0 to indicate that the shutdown process has not yet |
| 100 |
completed. Once the shutdown process has completed, subsequent calls to |
| 101 |
\&\fBSSL_shutdown()\fR will return 1. See the RETURN VALUES section for more |
| 102 |
information. |
| 103 |
.PP |
| 104 |
\&\fBSSL_shutdown()\fR should not be called if a previous fatal error has occurred on a |
| 105 |
connection; i.e., if \fBSSL_get_error\fR\|(3) has returned \fBSSL_ERROR_SYSCALL\fR or |
| 106 |
\&\fBSSL_ERROR_SSL\fR. |
| 107 |
.SH "TLS AND DTLS-SPECIFIC CONSIDERATIONS" |
| 108 |
.IX Header "TLS AND DTLS-SPECIFIC CONSIDERATIONS" |
| 109 |
Shutdown for SSL/TLS and DTLS is implemented in terms of the SSL/TLS/DTLS |
| 110 |
close_notify alert message. The shutdown process for SSL/TLS and DTLS |
| 111 |
consists of two steps: |
| 112 |
.IP \(bu 4 |
| 113 |
A close_notify shutdown alert message is sent to the peer. |
| 114 |
.IP \(bu 4 |
| 115 |
A close_notify shutdown alert message is received from the peer. |
| 116 |
.PP |
| 117 |
These steps can occur in either order depending on whether the connection |
| 118 |
shutdown process was first initiated by the local application or by the peer. |
| 119 |
.SS "Locally-Initiated Shutdown" |
| 120 |
.IX Subsection "Locally-Initiated Shutdown" |
| 121 |
Calling \fBSSL_shutdown()\fR on an SSL/TLS or DTLS SSL object initiates the shutdown |
| 122 |
process and causes OpenSSL to try to send a close_notify shutdown alert to the |
| 123 |
peer. The shutdown process will then be considered completed once the peer |
| 124 |
responds in turn with a close_notify shutdown alert message. |
| 125 |
.PP |
| 126 |
Calling \fBSSL_shutdown()\fR only closes the write direction of the connection; the |
| 127 |
read direction is closed by the peer. Once \fBSSL_shutdown()\fR is called, |
| 128 |
\&\fBSSL_write\fR\|(3) can no longer be used, but \fBSSL_read\fR\|(3) may still be used |
| 129 |
until the peer decides to close the connection in turn. The peer might |
| 130 |
continue sending data for some period of time before handling the local |
| 131 |
application's shutdown indication. |
| 132 |
.PP |
| 133 |
\&\fBSSL_shutdown()\fR does not affect an underlying network connection such as a TCP |
| 134 |
connection, which remains open. |
| 135 |
.SS "Remotely-Initiated Shutdown" |
| 136 |
.IX Subsection "Remotely-Initiated Shutdown" |
| 137 |
If the peer was the first to initiate the shutdown process by sending a |
| 138 |
close_notify alert message, an application will be notified of this as an EOF |
| 139 |
condition when calling |
| 140 |
\&\fBSSL_read\fR\|(3) (i.e., \fBSSL_read\fR\|(3) will fail and \fBSSL_get_error\fR\|(3) will |
| 141 |
return \fBSSL_ERROR_ZERO_RETURN\fR), after all application data sent by the peer |
| 142 |
prior to initiating the shutdown has been read. An application should handle |
| 143 |
this condition by calling \fBSSL_shutdown()\fR to respond with a close_notify alert in |
| 144 |
turn, completing the shutdown process, though it may choose to write additional |
| 145 |
application data using \fBSSL_write\fR\|(3) before doing so. If an application does |
| 146 |
not call \fBSSL_shutdown()\fR in this case, a close_notify alert will not be sent and |
| 147 |
the behaviour will not be fully standards compliant. |
| 148 |
.SS "Shutdown Lifecycle" |
| 149 |
.IX Subsection "Shutdown Lifecycle" |
| 150 |
Regardless of whether a shutdown was initiated locally or by the peer, if the |
| 151 |
underlying BIO is blocking, a call to \fBSSL_shutdown()\fR will return firstly once a |
| 152 |
close_notify alert message is written to the peer (returning 0), and upon a |
| 153 |
second and subsequent call, once a corresponding message is received from the |
| 154 |
peer (returning 1 and completing the shutdown process). Calls to \fBSSL_shutdown()\fR |
| 155 |
with a blocking underlying BIO will also return if an error occurs. |
| 156 |
.PP |
| 157 |
If the underlying BIO is nonblocking and the shutdown process is not yet |
| 158 |
complete (for example, because a close_notify alert message has not yet been |
| 159 |
received from the peer, or because a close_notify alert message needs to be sent |
| 160 |
but would currently block), \fBSSL_shutdown()\fR returns 0 to indicate that the |
| 161 |
shutdown process is still ongoing; in this case, a call to \fBSSL_get_error\fR\|(3) |
| 162 |
will yield \fBSSL_ERROR_WANT_READ\fR or \fBSSL_ERROR_WANT_WRITE\fR. |
| 163 |
.PP |
| 164 |
An application can then detect completion of the shutdown process by calling |
| 165 |
\&\fBSSL_shutdown()\fR again repeatedly until it returns 1, indicating that the shutdown |
| 166 |
process is complete (with a close_notify alert having both been sent and |
| 167 |
received). |
| 168 |
.PP |
| 169 |
However, the preferred method of waiting for the shutdown to complete is to use |
| 170 |
\&\fBSSL_read\fR\|(3) until \fBSSL_get_error\fR\|(3) indicates EOF by returning |
| 171 |
\&\fBSSL_ERROR_ZERO_RETURN\fR. This ensures any data received immediately before the |
| 172 |
peer's close_notify alert is still provided to the application. It also ensures |
| 173 |
any final handshake-layer messages received are processed (for example, messages |
| 174 |
issuing new session tickets). |
| 175 |
.PP |
| 176 |
If this approach is not used, the second call to \fBSSL_shutdown()\fR (to complete the |
| 177 |
shutdown by confirming receipt of the peer's close_notify message) will fail if |
| 178 |
it is called when the application has not read all pending application data |
| 179 |
sent by the peer using \fBSSL_read\fR\|(3). |
| 180 |
.PP |
| 181 |
When calling \fBSSL_shutdown()\fR, the \fBSSL_SENT_SHUTDOWN\fR flag is set once an |
| 182 |
attempt is made to send a close_notify alert, regardless of whether the attempt |
| 183 |
was successful. The \fBSSL_RECEIVED_SHUTDOWN\fR flag is set once a close_notify |
| 184 |
alert is received, which may occur during any call which processes incoming data |
| 185 |
from the network, such as \fBSSL_read\fR\|(3) or \fBSSL_shutdown()\fR. These flags |
| 186 |
may be checked using \fBSSL_get_shutdown\fR\|(3). |
| 187 |
.SS "Fast Shutdown" |
| 188 |
.IX Subsection "Fast Shutdown" |
| 189 |
Alternatively, it is acceptable for an application to call \fBSSL_shutdown()\fR once |
| 190 |
(such that it returns 0) and then close the underlying connection without |
| 191 |
waiting for the peer's response. This allows for a more rapid shutdown process |
| 192 |
if the application does not wish to wait for the peer. |
| 193 |
.PP |
| 194 |
This alternative "fast shutdown" approach should only be done if it is known |
| 195 |
that the peer will not send more data, otherwise there is a risk of an |
| 196 |
application exposing itself to a truncation attack. The full \fBSSL_shutdown()\fR |
| 197 |
process, in which both parties send close_notify alerts and \fBSSL_shutdown()\fR |
| 198 |
returns 1, provides a cryptographically authenticated indication of the end of a |
| 199 |
connection. |
| 200 |
.PP |
| 201 |
This approach of a single \fBSSL_shutdown()\fR call without waiting is preferable to |
| 202 |
simply calling \fBSSL_free\fR\|(3) or \fBSSL_clear\fR\|(3) as calling \fBSSL_shutdown()\fR |
| 203 |
beforehand makes an SSL session eligible for subsequent reuse and notifies the |
| 204 |
peer of connection shutdown. |
| 205 |
.PP |
| 206 |
The fast shutdown approach can only be used if there is no intention to reuse |
| 207 |
the underlying connection (e.g. a TCP connection) for further communication; in |
| 208 |
this case, the full shutdown process must be performed to ensure |
| 209 |
synchronisation. |
| 210 |
.SS "Effects on Session Reuse" |
| 211 |
.IX Subsection "Effects on Session Reuse" |
| 212 |
Calling \fBSSL_shutdown()\fR sets the SSL_SENT_SHUTDOWN flag (see |
| 213 |
\&\fBSSL_set_shutdown\fR\|(3)), regardless of whether the transmission of the |
| 214 |
close_notify alert was successful or not. This makes the SSL session eligible |
| 215 |
for reuse; the SSL session is considered properly closed and can be reused for |
| 216 |
future connections. |
| 217 |
.SS "Quiet Shutdown" |
| 218 |
.IX Subsection "Quiet Shutdown" |
| 219 |
\&\fBSSL_shutdown()\fR can be modified to set the connection to the "shutdown" |
| 220 |
state without actually sending a close_notify alert message; see |
| 221 |
\&\fBSSL_CTX_set_quiet_shutdown\fR\|(3). When "quiet shutdown" is enabled, |
| 222 |
\&\fBSSL_shutdown()\fR will always succeed and return 1 immediately. |
| 223 |
.PP |
| 224 |
This is not standards-compliant behaviour. It should only be done when the |
| 225 |
application protocol in use enables the peer to ensure that all data has been |
| 226 |
received, such that it doesn't need to wait for a close_notify alert, otherwise |
| 227 |
application data may be truncated unexpectedly. |
| 228 |
.SS "Non-Compliant Peers" |
| 229 |
.IX Subsection "Non-Compliant Peers" |
| 230 |
There are SSL/TLS implementations that never send the required close_notify |
| 231 |
alert message but simply close the underlying transport (e.g. a TCP connection) |
| 232 |
instead. This will ordinarily result in an error being generated. |
| 233 |
.PP |
| 234 |
If compatibility with such peers is desired, the option |
| 235 |
\&\fBSSL_OP_IGNORE_UNEXPECTED_EOF\fR can be set. For more information, see |
| 236 |
\&\fBSSL_CTX_set_options\fR\|(3). |
| 237 |
.PP |
| 238 |
Note that use of this option means that the EOF condition for application data |
| 239 |
does not receive cryptographic protection, and therefore renders an application |
| 240 |
potentially vulnerable to truncation attacks. Thus, this option must only be |
| 241 |
used in conjunction with an application protocol which indicates unambiguously |
| 242 |
when all data has been received. |
| 243 |
.PP |
| 244 |
An alternative approach is to simply avoid calling \fBSSL_read\fR\|(3) if it is known |
| 245 |
that no more data is going to be sent. This requires an application protocol |
| 246 |
which indicates unambiguously when all data has been sent. |
| 247 |
.SS "Session Ticket Handling" |
| 248 |
.IX Subsection "Session Ticket Handling" |
| 249 |
If a client application only writes to an SSL/TLS or DTLS connection and never |
| 250 |
reads, OpenSSL may never process new SSL/TLS session tickets sent by the server. |
| 251 |
This is because OpenSSL ordinarily processes handshake messages received from a |
| 252 |
peer during calls to \fBSSL_read\fR\|(3) by the application. |
| 253 |
.PP |
| 254 |
Therefore, client applications which only write and do not read but which wish |
| 255 |
to benefit from session resumption are advised to perform a complete shutdown |
| 256 |
procedure by calling \fBSSL_shutdown()\fR until it returns 1, as described above. This |
| 257 |
will ensure there is an opportunity for SSL/TLS session ticket messages to be |
| 258 |
received and processed by OpenSSL. |
| 259 |
.SH "QUIC-SPECIFIC SHUTDOWN CONSIDERATIONS" |
| 260 |
.IX Header "QUIC-SPECIFIC SHUTDOWN CONSIDERATIONS" |
| 261 |
When used with a QUIC connection SSL object, \fBSSL_shutdown()\fR initiates a QUIC |
| 262 |
immediate close using QUIC \fBCONNECTION_CLOSE\fR frames. |
| 263 |
.PP |
| 264 |
\&\fBSSL_shutdown()\fR cannot be used on QUIC stream SSL objects. To conclude a stream |
| 265 |
normally, see \fBSSL_stream_conclude\fR\|(3); to perform a non-normal stream |
| 266 |
termination, see \fBSSL_stream_reset\fR\|(3). |
| 267 |
.PP |
| 268 |
\&\fBSSL_shutdown_ex()\fR may be used instead of \fBSSL_shutdown()\fR by an application to |
| 269 |
provide additional information to the peer on the reason why a connection is |
| 270 |
being shut down. The information which can be provided is as follows: |
| 271 |
.IP \fIquic_error_code\fR 4 |
| 272 |
.IX Item "quic_error_code" |
| 273 |
An optional 62\-bit application error code to be signalled to the peer. The value |
| 274 |
must be in the range [0, 2**62\-1], else the call to \fBSSL_shutdown_ex()\fR fails. If |
| 275 |
not provided, an error code of 0 is used by default. |
| 276 |
.IP \fIquic_reason\fR 4 |
| 277 |
.IX Item "quic_reason" |
| 278 |
An optional zero-terminated (UTF\-8) reason string to be signalled to the peer. |
| 279 |
The application is responsible for providing a valid UTF\-8 string and OpenSSL |
| 280 |
will not validate the string. If a reason is not provided, or \fBSSL_shutdown()\fR is |
| 281 |
used, a zero-length string is used as the reason. If provided, the reason string |
| 282 |
is copied and stored inside the QUIC connection SSL object and need not remain |
| 283 |
allocated after the call to \fBSSL_shutdown_ex()\fR returns. Reason strings are |
| 284 |
bounded by the path MTU and may be silently truncated if they are too long to |
| 285 |
fit in a QUIC packet. |
| 286 |
.Sp |
| 287 |
Reason strings are intended for human diagnostic purposes only, and should not |
| 288 |
be used for application signalling. |
| 289 |
.PP |
| 290 |
The arguments to \fBSSL_shutdown_ex()\fR are used only on the first call to |
| 291 |
\&\fBSSL_shutdown_ex()\fR (or \fBSSL_shutdown()\fR) for a given QUIC connection SSL object. |
| 292 |
These arguments are ignored on subsequent calls. |
| 293 |
.PP |
| 294 |
These functions do not affect an underlying network BIO or the resource it |
| 295 |
represents; for example, a UDP datagram provided to a QUIC connection as the |
| 296 |
network BIO will remain open. |
| 297 |
.PP |
| 298 |
Note that when using QUIC, an application must call \fBSSL_shutdown()\fR if it wants |
| 299 |
to ensure that all transmitted data was received by the peer. This is unlike a |
| 300 |
TLS/TCP connection, where reliable transmission of buffered data is the |
| 301 |
responsibility of the operating system. If an application calls \fBSSL_free()\fR on a |
| 302 |
QUIC connection SSL object or exits before completing the shutdown process using |
| 303 |
\&\fBSSL_shutdown()\fR, data which was written by the application using \fBSSL_write()\fR, but |
| 304 |
could not yet be transmitted, or which was sent but lost in the network, may not |
| 305 |
be received by the peer. |
| 306 |
.PP |
| 307 |
When using QUIC, calling \fBSSL_shutdown()\fR allows internal network event processing |
| 308 |
to be performed. It is important that this processing is performed regularly, |
| 309 |
whether during connection usage or during shutdown. If an application is not |
| 310 |
using thread assisted mode, an application conducting shutdown should either |
| 311 |
ensure that \fBSSL_shutdown()\fR is called regularly, or alternatively ensure that |
| 312 |
\&\fBSSL_handle_events()\fR is called regularly. See \fBopenssl\-quic\fR\|(7) and |
| 313 |
\&\fBSSL_handle_events\fR\|(3) for more information. |
| 314 |
.SS "Application Data Drainage Behaviour" |
| 315 |
.IX Subsection "Application Data Drainage Behaviour" |
| 316 |
When using QUIC, \fBSSL_shutdown()\fR or \fBSSL_shutdown_ex()\fR ordinarily waits until all |
| 317 |
data written to a stream by an application has been acknowledged by the peer. In |
| 318 |
other words, the shutdown process waits until all data written by the |
| 319 |
application has been sent to the peer, and until the receipt of all such data is |
| 320 |
acknowledged by the peer. Only once this process is completed is the shutdown |
| 321 |
considered complete. |
| 322 |
.PP |
| 323 |
An exception to this is streams which terminated in a non-normal fashion, for |
| 324 |
example due to a stream reset; only streams which are non-terminated at the time |
| 325 |
\&\fBSSL_shutdown()\fR is called, or which terminated in a normal fashion, have their |
| 326 |
pending send buffers flushed in this manner. |
| 327 |
.PP |
| 328 |
This behaviour of flushing streams during the shutdown process can be skipped by |
| 329 |
setting the \fBSSL_SHUTDOWN_FLAG_NO_STREAM_FLUSH\fR flag in a call to |
| 330 |
\&\fBSSL_shutdown_ex()\fR; in this case, data remaining in stream send buffers may not |
| 331 |
be transmitted to the peer. This flag may be used when a non-normal application |
| 332 |
condition has occurred and the delivery of data written to streams via |
| 333 |
\&\fBSSL_write\fR\|(3) is no longer relevant. |
| 334 |
.SS "Shutdown Mode" |
| 335 |
.IX Subsection "Shutdown Mode" |
| 336 |
Aspects of how QUIC handles connection closure must be taken into account by |
| 337 |
applications. Ordinarily, QUIC expects a connection to continue to be serviced |
| 338 |
for a substantial period of time after it is nominally closed. This is necessary |
| 339 |
to ensure that any connection closure notification sent to the peer was |
| 340 |
successfully received. However, a consequence of this is that a fully |
| 341 |
RFC-compliant QUIC connection closure process could take of the order of |
| 342 |
seconds. This may be unsuitable for some applications, such as short-lived |
| 343 |
processes which need to exit immediately after completing an application-layer |
| 344 |
transaction. |
| 345 |
.PP |
| 346 |
As such, there are two shutdown modes available to users of QUIC connection SSL |
| 347 |
objects: |
| 348 |
.IP "RFC compliant shutdown mode" 4 |
| 349 |
.IX Item "RFC compliant shutdown mode" |
| 350 |
This is the default behaviour. The shutdown process may take a period of time up |
| 351 |
to three times the current estimated RTT to the peer. It is possible for the |
| 352 |
closure process to complete much faster in some circumstances but this cannot be |
| 353 |
relied upon. |
| 354 |
.Sp |
| 355 |
In blocking mode, the function will return once the closure process is complete. |
| 356 |
In nonblocking mode, \fBSSL_shutdown_ex()\fR should be called until it returns 1, |
| 357 |
indicating the closure process is complete and the connection is now fully shut |
| 358 |
down. |
| 359 |
.IP "Rapid shutdown mode" 4 |
| 360 |
.IX Item "Rapid shutdown mode" |
| 361 |
In this mode, the peer is notified of connection closure on a best effort basis |
| 362 |
by sending a single QUIC packet. If that QUIC packet is lost, the peer will not |
| 363 |
know that the connection has terminated until the negotiated idle timeout (if |
| 364 |
any) expires. |
| 365 |
.Sp |
| 366 |
This will generally return 0 on success, indicating that the connection has not |
| 367 |
yet been fully shut down (unless it has already done so, in which case it will |
| 368 |
return 1). |
| 369 |
.PP |
| 370 |
If \fBSSL_SHUTDOWN_FLAG_RAPID\fR is specified in \fIflags\fR, a rapid shutdown is |
| 371 |
performed, otherwise an RFC-compliant shutdown is performed. |
| 372 |
.PP |
| 373 |
If an application calls \fBSSL_shutdown_ex()\fR with \fBSSL_SHUTDOWN_FLAG_RAPID\fR, an |
| 374 |
application can subsequently change its mind about performing a rapid shutdown |
| 375 |
by making a subsequent call to \fBSSL_shutdown_ex()\fR without the flag set. |
| 376 |
.SS "Peer-Initiated Shutdown" |
| 377 |
.IX Subsection "Peer-Initiated Shutdown" |
| 378 |
In some cases, an application may wish to wait for a shutdown initiated by the |
| 379 |
peer rather than triggered locally. To do this, call \fBSSL_shutdown_ex()\fR with |
| 380 |
\&\fISSL_SHUTDOWN_FLAG_WAIT_PEER\fR specified in \fIflags\fR. In blocking mode, this |
| 381 |
waits until the peer initiates a shutdown or the connection otherwise becomes |
| 382 |
terminated for another reason. In nonblocking mode it exits immediately with |
| 383 |
either success or failure depending on whether a shutdown has occurred. |
| 384 |
.PP |
| 385 |
If a locally initiated shutdown has already been triggered or the connection has |
| 386 |
started terminating for another reason, this flag has no effect. |
| 387 |
.PP |
| 388 |
\&\fBSSL_SHUTDOWN_FLAG_WAIT_PEER\fR implies \fBSSL_SHUTDOWN_FLAG_NO_STREAM_FLUSH\fR, as |
| 389 |
stream data cannot be flushed after a peer closes the connection. Stream data |
| 390 |
may still be sent to the peer in any time spent waiting before the peer closes |
| 391 |
the connection, though there is no guarantee of this. |
| 392 |
.SS "Nonblocking Mode" |
| 393 |
.IX Subsection "Nonblocking Mode" |
| 394 |
\&\fBSSL_shutdown()\fR and \fBSSL_shutdown_ex()\fR block if the connection is configured in |
| 395 |
blocking mode. This may be overridden by specifying |
| 396 |
\&\fBSSL_SHUTDOWN_FLAG_NO_BLOCK\fR in \fIflags\fR when calling \fBSSL_shutdown_ex()\fR, which |
| 397 |
causes the call to operate as though in nonblocking mode. |
| 398 |
.SH "RETURN VALUES" |
| 399 |
.IX Header "RETURN VALUES" |
| 400 |
For both \fBSSL_shutdown()\fR and \fBSSL_shutdown_ex()\fR the following return values can occur: |
| 401 |
.IP 0 4 |
| 402 |
The shutdown process is ongoing and has not yet completed. |
| 403 |
.Sp |
| 404 |
For TLS and DTLS, this means that a close_notify alert has been sent but the |
| 405 |
peer has not yet replied in turn with its own close_notify. |
| 406 |
.Sp |
| 407 |
For QUIC connection SSL objects, a CONNECTION_CLOSE frame may have been |
| 408 |
sent but the connection closure process has not yet completed. |
| 409 |
.Sp |
| 410 |
Unlike most other functions, returning 0 does not indicate an error. |
| 411 |
\&\fBSSL_get_error\fR\|(3) should not be called; it may misleadingly indicate an error |
| 412 |
even though no error occurred. |
| 413 |
.IP 1 4 |
| 414 |
.IX Item "1" |
| 415 |
The shutdown was successfully completed. |
| 416 |
.Sp |
| 417 |
For TLS and DTLS, this means that a close_notify alert was sent and the peer's |
| 418 |
close_notify alert was received. |
| 419 |
.Sp |
| 420 |
For QUIC connection SSL objects, this means that the connection closure process |
| 421 |
has completed. |
| 422 |
.IP <0 4 |
| 423 |
.IX Item "<0" |
| 424 |
The shutdown was not successful. |
| 425 |
Call \fBSSL_get_error\fR\|(3) with the return value \fBret\fR to find out the reason. |
| 426 |
It can occur if an action is needed to continue the operation for nonblocking |
| 427 |
BIOs. |
| 428 |
.Sp |
| 429 |
It can also occur when not all data was read using \fBSSL_read()\fR, or if called |
| 430 |
on a QUIC stream SSL object. |
| 431 |
.Sp |
| 432 |
This value is also returned when called on QUIC stream SSL objects. |
| 433 |
.SH "SEE ALSO" |
| 434 |
.IX Header "SEE ALSO" |
| 435 |
\&\fBSSL_get_error\fR\|(3), \fBSSL_connect\fR\|(3), |
| 436 |
\&\fBSSL_accept\fR\|(3), \fBSSL_set_shutdown\fR\|(3), |
| 437 |
\&\fBSSL_CTX_set_quiet_shutdown\fR\|(3), \fBSSL_CTX_set_options\fR\|(3) |
| 438 |
\&\fBSSL_clear\fR\|(3), \fBSSL_free\fR\|(3), |
| 439 |
\&\fBssl\fR\|(7), \fBbio\fR\|(7) |
| 440 |
.SH HISTORY |
| 441 |
.IX Header "HISTORY" |
| 442 |
The \fBSSL_shutdown_ex()\fR function was added in OpenSSL 3.2. |
| 443 |
.SH COPYRIGHT |
| 444 |
.IX Header "COPYRIGHT" |
| 445 |
Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. |
| 446 |
.PP |
| 447 |
Licensed under the Apache License 2.0 (the "License"). You may not use |
| 448 |
this file except in compliance with the License. You can obtain a copy |
| 449 |
in the file LICENSE in the source distribution or at |
| 450 |
<https://www.openssl.org/source/license.html>. |