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

5 SSL_shutdown, SSL_shutdown_ex - shut down a TLS/SSL or QUIC connection
26 SSL_shutdown_ex() is an extended version of SSL_shutdown(). If non-NULL, I<args>
29 zero-initialized. If I<args> is NULL, the behaviour is the same as passing a
30 zero-initialised B<SSL_SHUTDOWN_EX_ARGS> structure. Currently, all extended
39 In general, calling SSL_shutdown() in nonblocking mode will initiate the
49 =head1 TLS AND DTLS-SPECIFIC CONSIDERATIONS
51 Shutdown for SSL/TLS and DTLS is implemented in terms of the SSL/TLS/DTLS
67 These steps can occur in either order depending on whether the connection
68 shutdown process was first initiated by the local application or by the peer.
70 =head2 Locally-Initiated Shutdown
75 responds in turn with a close_notify shutdown alert message.
80 until the peer decides to close the connection in turn. The peer might
82 application's shutdown indication.
87 =head2 Remotely-Initiated Shutdown
90 close_notify alert message, an application will be notified of this as an EOF
93 return B<SSL_ERROR_ZERO_RETURN>), after all application data sent by the peer
94 prior to initiating the shutdown has been read. An application should handle
95 this condition by calling SSL_shutdown() to respond with a close_notify alert in
97 application data using L<SSL_write(3)> before doing so. If an application does
98 not call SSL_shutdown() in this case, a close_notify alert will not be sent and
114 shutdown process is still ongoing; in this case, a call to L<SSL_get_error(3)>
117 An application can then detect completion of the shutdown process by calling
125 peer's close_notify alert is still provided to the application. It also ensures
126 any final handshake-layer messages received are processed (for example, messages
131 it is called when the application has not read all pending application data
143 Alternatively, it is acceptable for an application to call SSL_shutdown() once
146 if the application does not wish to wait for the peer.
150 application exposing itself to a truncation attack. The full SSL_shutdown()
151 process, in which both parties send close_notify alerts and SSL_shutdown()
161 the underlying connection (e.g. a TCP connection) for further communication; in
180 This is not standards-compliant behaviour. It should only be done when the
181 application protocol in use enables the peer to ensure that all data has been
183 application data may be truncated unexpectedly.
185 =head2 Non-Compliant Peers
189 instead. This will ordinarily result in an error being generated.
195 Note that use of this option means that the EOF condition for application data
196 does not receive cryptographic protection, and therefore renders an application
198 used in conjunction with an application protocol which indicates unambiguously
202 that no more data is going to be sent. This requires an application protocol
207 If a client application only writes to an SSL/TLS or DTLS connection and never
210 peer during calls to L<SSL_read(3)> by the application.
218 =head1 QUIC-SPECIFIC SHUTDOWN CONSIDERATIONS
224 normally, see L<SSL_stream_conclude(3)>; to perform a non-normal stream
227 SSL_shutdown_ex() may be used instead of SSL_shutdown() by an application to
235 An optional 62-bit application error code to be signalled to the peer. The value
236 must be in the range [0, 2**62-1], else the call to SSL_shutdown_ex() fails. If
241 An optional zero-terminated (UTF-8) reason string to be signalled to the peer.
242 The application is responsible for providing a valid UTF-8 string and OpenSSL
244 used, a zero-length string is used as the reason. If provided, the reason string
248 fit in a QUIC packet.
251 be used for application signalling.
263 Note that when using QUIC, an application must call SSL_shutdown() if it wants
266 responsibility of the operating system. If an application calls SSL_free() on a
268 SSL_shutdown(), data which was written by the application using SSL_write(), but
269 could not yet be transmitted, or which was sent but lost in the network, may not
274 whether during connection usage or during shutdown. If an application is not
275 using thread assisted mode, an application conducting shutdown should either
277 SSL_handle_events() is called regularly. See L<openssl-quic(7)> and
280 =head2 Application Data Drainage Behaviour
283 data written to a stream by an application has been acknowledged by the peer. In
285 application has been sent to the peer, and until the receipt of all such data is
289 An exception to this is streams which terminated in a non-normal fashion, for
290 example due to a stream reset; only streams which are non-terminated at the time
291 SSL_shutdown() is called, or which terminated in a normal fashion, have their
292 pending send buffers flushed in this manner.
295 setting the B<SSL_SHUTDOWN_FLAG_NO_STREAM_FLUSH> flag in a call to
296 SSL_shutdown_ex(); in this case, data remaining in stream send buffers may not
297 be transmitted to the peer. This flag may be used when a non-normal application
308 RFC-compliant QUIC connection closure process could take of the order of
309 seconds. This may be unsuitable for some applications, such as short-lived
310 processes which need to exit immediately after completing an application-layer
322 closure process to complete much faster in some circumstances but this cannot be
325 In blocking mode, the function will return once the closure process is complete.
326 In nonblocking mode, SSL_shutdown_ex() should be called until it returns 1,
332 In this mode, the peer is notified of connection closure on a best effort basis
338 yet been fully shut down (unless it has already done so, in which case it will
343 If B<SSL_SHUTDOWN_FLAG_RAPID> is specified in I<flags>, a rapid shutdown is
344 performed, otherwise an RFC-compliant shutdown is performed.
346 If an application calls SSL_shutdown_ex() with B<SSL_SHUTDOWN_FLAG_RAPID>, an
347 application can subsequently change its mind about performing a rapid shutdown
350 =head2 Peer-Initiated Shutdown
352 In some cases, an application may wish to wait for a shutdown initiated by the
354 I<SSL_SHUTDOWN_FLAG_WAIT_PEER> specified in I<flags>. In blocking mode, this
356 terminated for another reason. In nonblocking mode it exits immediately with
364 may still be sent to the peer in any time spent waiting before the peer closes
369 SSL_shutdown() and SSL_shutdown_ex() block if the connection is configured in
371 B<SSL_SHUTDOWN_FLAG_NO_BLOCK> in I<flags> when calling SSL_shutdown_ex(), which
372 causes the call to operate as though in nonblocking mode.
385 peer has not yet replied in turn with its own close_notify.
428 The SSL_shutdown_ex() function was added in OpenSSL 3.2.
432 Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
435 this file except in compliance with the License.  You can obtain a copy
436 in the file LICENSE in the source distribution or at