Lines Matching +full:in +full:- +full:application

1 .\" -*- mode: troff; coding: utf-8 -*-
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
35 .\" entries marked with X<> in POD.  Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
58 .TH SSL_SHUTDOWN 3ossl 2025-09-30 3.5.4 OpenSSL
60 .\" way too many mistakes in technical documents.
64 SSL_shutdown, SSL_shutdown_ex \- shut down a TLS/SSL or QUIC connection
85 \&\fBSSL_shutdown_ex()\fR is an extended version of \fBSSL_shutdown()\fR. If non-NULL, \fIargs\fR
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
98 In general, calling \fBSSL_shutdown()\fR in nonblocking mode will initiate the
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
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"
124 responds in turn with a close_notify shutdown alert message.
129 until the peer decides to close the connection in turn. The peer might
131 application's shutdown indication.
135 .SS "Remotely-Initiated Shutdown"
136 .IX Subsection "Remotely-Initiated Shutdown"
138 close_notify alert message, an application will be notified of this as an EOF
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
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
161 shutdown process is still ongoing; in this case, a call to \fBSSL_get_error\fR\|(3)
164 An application can then detect completion of the shutdown process by calling
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
178 it is called when the application has not read all pending application data
189 Alternatively, it is acceptable for an application to call \fBSSL_shutdown()\fR once
192 if the application does not wish to wait for the peer.
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
207 the underlying connection (e.g. a TCP connection) for further communication; in
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
227 application data may be truncated unexpectedly.
228 .SS "Non-Compliant Peers"
229 .IX Subsection "Non-Compliant Peers"
232 instead. This will ordinarily result in an error being generated.
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
241 used in conjunction with an application protocol which indicates unambiguously
245 that no more data is going to be sent. This requires an application protocol
249 If a client application only writes to an SSL/TLS or DTLS connection and never
252 peer during calls to \fBSSL_read\fR\|(3) by the application.
259 .SH "QUIC-SPECIFIC SHUTDOWN CONSIDERATIONS"
260 .IX Header "QUIC-SPECIFIC SHUTDOWN CONSIDERATIONS"
265 normally, see \fBSSL_stream_conclude\fR\|(3); to perform a non-normal stream
268 \&\fBSSL_shutdown_ex()\fR may be used instead of \fBSSL_shutdown()\fR by an application to
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
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
281 used, a zero-length string is used as the reason. If provided, the reason string
285 fit in a QUIC packet.
288 be used for application signalling.
298 Note that when using QUIC, an application must call \fBSSL_shutdown()\fR if it wants
301 responsibility of the operating system. If an application calls \fBSSL_free()\fR on a
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
309 whether during connection usage or during shutdown. If an application is not
310 using thread assisted mode, an application conducting shutdown should either
312 \&\fBSSL_handle_events()\fR is called regularly. See \fBopenssl\-quic\fR\|(7) and
314 .SS "Application Data Drainage Behaviour"
315 .IX Subsection "Application Data Drainage Behaviour"
317 data written to a stream by an application has been acknowledged by the peer. In
319 application has been sent to the peer, and until the receipt of all such data is
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.
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
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
352 closure process to complete much faster in some circumstances but this cannot be
367 yet been fully shut down (unless it has already done so, in which case it will
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.
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
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
380 \&\fISSL_SHUTDOWN_FLAG_WAIT_PEER\fR specified in \fIflags\fR. In blocking mode, this
382 terminated for another reason. In nonblocking mode it exits immediately with
390 may still be sent to the peer in any time spent waiting before the peer closes
394 \&\fBSSL_shutdown()\fR and \fBSSL_shutdown_ex()\fR block if the connection is configured in
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.
405 peer has not yet replied in turn with its own close_notify.
442 The \fBSSL_shutdown_ex()\fR function was added in OpenSSL 3.2.
445 Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
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