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