dockerfile/examples/openssl/openssl-3.2.1/share/man/man3/SSL_shutdown.3ossl

.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SSL_SHUTDOWN 3ossl"
.TH SSL_SHUTDOWN 3ossl "2024-01-30" "3.2.1" "OpenSSL"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SSL_shutdown, SSL_shutdown_ex \- shut down a TLS/SSL or QUIC connection
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/ssl.h>
\&
\& int SSL_shutdown(SSL *ssl);
\&
\& typedef struct ssl_shutdown_ex_args_st {
\&     uint64_t    quic_error_code;
\&     const char  *quic_reason;
\& } SSL_SHUTDOWN_EX_ARGS;
\&
\& _\|_owur int SSL_shutdown_ex(SSL *ssl, uint64_t flags,
\&                            const SSL_SHUTDOWN_EX_ARGS *args,
\&                            size_t args_len);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fISSL_shutdown()\fR shuts down an active connection represented by an \s-1SSL\s0 object.
.PP
\&\fISSL_shutdown_ex()\fR is an extended version of \fISSL_shutdown()\fR. If non-NULL, \fIargs\fR
must point to a \fB\s-1SSL_SHUTDOWN_EX_ARGS\s0\fR structure and \fIargs_len\fR must be set to
\&\f(CW\*(C`sizeof(SSL_SHUTDOWN_EX_ARGS)\*(C'\fR. The \fB\s-1SSL_SHUTDOWN_EX_ARGS\s0\fR structure must be
zero-initialized. If \fIargs\fR is \s-1NULL,\s0 the behaviour is the same as passing a
zero-initialised \fB\s-1SSL_SHUTDOWN_EX_ARGS\s0\fR structure. Currently, all extended
arguments relate to usage with \s-1QUIC,\s0 therefore this call functions identically
to \fISSL_shutdown()\fR when not being used with \s-1QUIC.\s0
.PP
While the general operation of \fISSL_shutdown()\fR is common between protocols, the
exact nature of how a shutdown is performed depends on the underlying protocol
being used. See the section below pertaining to each protocol for more
information.
.PP
In general, calling \fISSL_shutdown()\fR in nonblocking mode will initiate the
shutdown process and return 0 to indicate that the shutdown process has not yet
completed. Once the shutdown process has completed, subsequent calls to
\&\fISSL_shutdown()\fR will return 1. See the \s-1RETURN VALUES\s0 section for more
information.
.PP
\&\fISSL_shutdown()\fR should not be called if a previous fatal error has occurred on a
connection; i.e., if \fISSL_get_error\fR\|(3) has returned \fB\s-1SSL_ERROR_SYSCALL\s0\fR or
\&\fB\s-1SSL_ERROR_SSL\s0\fR.
.SH "TLS AND DTLS-SPECIFIC CONSIDERATIONS"
.IX Header "TLS AND DTLS-SPECIFIC CONSIDERATIONS"
Shutdown for \s-1SSL/TLS\s0 and \s-1DTLS\s0 is implemented in terms of the \s-1SSL/TLS/DTLS\s0
close_notify alert message. The shutdown process for \s-1SSL/TLS\s0 and \s-1DTLS\s0
consists of two steps:
.IP "\(bu" 4
A close_notify shutdown alert message is sent to the peer.
.IP "\(bu" 4
A close_notify shutdown alert message is received from the peer.
.PP
These steps can occur in either order depending on whether the connection
shutdown process was first initiated by the local application or by the peer.
.SS "Locally-Initiated Shutdown"
.IX Subsection "Locally-Initiated Shutdown"
Calling \fISSL_shutdown()\fR on a \s-1SSL/TLS\s0 or \s-1DTLS SSL\s0 object initiates the shutdown
process and causes OpenSSL to try to send a close_notify shutdown alert to the
peer. The shutdown process will then be considered completed once the peer
responds in turn with a close_notify shutdown alert message.
.PP
Calling \fISSL_shutdown()\fR only closes the write direction of the connection; the
read direction is closed by the peer. Once \fISSL_shutdown()\fR is called,
\&\fISSL_write\fR\|(3) can no longer be used, but \fISSL_read\fR\|(3) may still be used
until the peer decides to close the connection in turn. The peer might
continue sending data for some period of time before handling the local
application's shutdown indication.
.PP
\&\fISSL_shutdown()\fR does not affect an underlying network connection such as a \s-1TCP\s0
connection, which remains open.
.SS "Remotely-Initiated Shutdown"
.IX Subsection "Remotely-Initiated Shutdown"
If the peer was the first to initiate the shutdown process by sending a
close_notify alert message, an application will be notified of this as an \s-1EOF\s0
condition when calling
\&\fISSL_read\fR\|(3) (i.e., \fISSL_read\fR\|(3) will fail and \fISSL_get_error\fR\|(3) will
return \fB\s-1SSL_ERROR_ZERO_RETURN\s0\fR), after all application data sent by the peer
prior to initiating the shutdown has been read. An application should handle
this condition by calling \fISSL_shutdown()\fR to respond with a close_notify alert in
turn, completing the shutdown process, though it may choose to write additional
application data using \fISSL_write\fR\|(3) before doing so. If an application does
not call \fISSL_shutdown()\fR in this case, a close_notify alert will not be sent and
the behaviour will not be fully standards compliant.
.SS "Shutdown Lifecycle"
.IX Subsection "Shutdown Lifecycle"
Regardless of whether a shutdown was initiated locally or by the peer, if the
underlying \s-1BIO\s0 is blocking, a call to \fISSL_shutdown()\fR will return firstly once a
close_notify alert message is written to the peer (returning 0), and upon a
second and subsequent call, once a corresponding message is received from the
peer (returning 1 and completing the shutdown process). Calls to \fISSL_shutdown()\fR
with a blocking underlying \s-1BIO\s0 will also return if an error occurs.
.PP
If the underlying \s-1BIO\s0 is nonblocking and the shutdown process is not yet
complete (for example, because a close_notify alert message has not yet been
received from the peer, or because a close_notify alert message needs to be sent
but would currently block), \fISSL_shutdown()\fR returns 0 to indicate that the
shutdown process is still ongoing; in this case, a call to \fISSL_get_error\fR\|(3)
will yield \fB\s-1SSL_ERROR_WANT_READ\s0\fR or \fB\s-1SSL_ERROR_WANT_WRITE\s0\fR.
.PP
An application can then detect completion of the shutdown process by calling
\&\fISSL_shutdown()\fR again repeatedly until it returns 1, indicating that the shutdown
process is complete (with a close_notify alert having both been sent and
received).
.PP
However, the preferred method of waiting for the shutdown to complete is to use
\&\fISSL_read\fR\|(3) until \fISSL_get_error\fR\|(3) indicates \s-1EOF\s0 by returning
\&\fB\s-1SSL_ERROR_ZERO_RETURN\s0\fR. This ensures any data received immediately before the
peer's close_notify alert is still provided to the application. It also ensures
any final handshake-layer messages received are processed (for example, messages
issuing new session tickets).
.PP
If this approach is not used, the second call to \fISSL_shutdown()\fR (to complete the
shutdown by confirming receipt of the peer's close_notify message) will fail if
it is called when the application has not read all pending application data
sent by the peer using \fISSL_read\fR\|(3).
.PP
When calling \fISSL_shutdown()\fR, the \fB\s-1SSL_SENT_SHUTDOWN\s0\fR flag is set once an
attempt is made to send a close_notify alert, regardless of whether the attempt
was successful. The \fB\s-1SSL_RECEIVED_SHUTDOWN\s0\fR flag is set once a close_notify
alert is received, which may occur during any call which processes incoming data
from the network, such as \fISSL_read\fR\|(3) or \fISSL_shutdown()\fR. These flags
may be checked using \fISSL_get_shutdown\fR\|(3).
.SS "Fast Shutdown"
.IX Subsection "Fast Shutdown"
Alternatively, it is acceptable for an application to call \fISSL_shutdown()\fR once
(such that it returns 0) and then close the underlying connection without
waiting for the peer's response. This allows for a more rapid shutdown process
if the application does not wish to wait for the peer.
.PP
This alternative \*(L"fast shutdown\*(R" approach should only be done if it is known
that the peer will not send more data, otherwise there is a risk of an
application exposing itself to a truncation attack. The full \fISSL_shutdown()\fR
process, in which both parties send close_notify alerts and \fISSL_shutdown()\fR
returns 1, provides a cryptographically authenticated indication of the end of a
connection.
.PP
This approach of a single \fISSL_shutdown()\fR call without waiting is preferable to
simply calling \fISSL_free\fR\|(3) or \fISSL_clear\fR\|(3) as calling \fISSL_shutdown()\fR
beforehand makes an \s-1SSL\s0 session eligible for subsequent reuse and notifies the
peer of connection shutdown.
.PP
The fast shutdown approach can only be used if there is no intention to reuse
the underlying connection (e.g. a \s-1TCP\s0 connection) for further communication; in
this case, the full shutdown process must be performed to ensure
synchronisation.
.SS "Effects on Session Reuse"
.IX Subsection "Effects on Session Reuse"
Calling \fISSL_shutdown()\fR sets the \s-1SSL_SENT_SHUTDOWN\s0 flag (see
\&\fISSL_set_shutdown\fR\|(3)), regardless of whether the transmission of the
close_notify alert was successful or not. This makes the \s-1SSL\s0 session eligible
for reuse; the \s-1SSL\s0 session is considered properly closed and can be reused for
future connections.
.SS "Quiet Shutdown"
.IX Subsection "Quiet Shutdown"
\&\fISSL_shutdown()\fR can be modified to set the connection to the \*(L"shutdown\*(R"
state without actually sending a close_notify alert message; see
\&\fISSL_CTX_set_quiet_shutdown\fR\|(3). When \*(L"quiet shutdown\*(R" is enabled,
\&\fISSL_shutdown()\fR will always succeed and return 1 immediately.
.PP
This is not standards-compliant behaviour. It should only be done when the
application protocol in use enables the peer to ensure that all data has been
received, such that it doesn't need to wait for a close_notify alert, otherwise
application data may be truncated unexpectedly.
.SS "Non-Compliant Peers"
.IX Subsection "Non-Compliant Peers"
There are \s-1SSL/TLS\s0 implementations that never send the required close_notify
alert message but simply close the underlying transport (e.g. a \s-1TCP\s0 connection)
instead. This will ordinarily result in an error being generated.
.PP
If compatibility with such peers is desired, the option
\&\fB\s-1SSL_OP_IGNORE_UNEXPECTED_EOF\s0\fR can be set. For more information, see
\&\fISSL_CTX_set_options\fR\|(3).
.PP
Note that use of this option means that the \s-1EOF\s0 condition for application data
does not receive cryptographic protection, and therefore renders an application
potentially vulnerable to truncation attacks. Thus, this option must only be
used in conjunction with an application protocol which indicates unambiguously
when all data has been received.
.PP
An alternative approach is to simply avoid calling \fISSL_read\fR\|(3) if it is known
that no more data is going to be sent. This requires an application protocol
which indicates unambiguously when all data has been sent.
.SS "Session Ticket Handling"
.IX Subsection "Session Ticket Handling"
If a client application only writes to a \s-1SSL/TLS\s0 or \s-1DTLS\s0 connection and never
reads, OpenSSL may never process new \s-1SSL/TLS\s0 session tickets sent by the server.
This is because OpenSSL ordinarily processes handshake messages received from a
peer during calls to \fISSL_read\fR\|(3) by the application.
.PP
Therefore, client applications which only write and do not read but which wish
to benefit from session resumption are advised to perform a complete shutdown
procedure by calling \fISSL_shutdown()\fR until it returns 1, as described above. This
will ensure there is an opportunity for \s-1SSL/TLS\s0 session ticket messages to be
received and processed by OpenSSL.
.SH "QUIC-SPECIFIC SHUTDOWN CONSIDERATIONS"
.IX Header "QUIC-SPECIFIC SHUTDOWN CONSIDERATIONS"
When used with a \s-1QUIC\s0 connection \s-1SSL\s0 object, \fISSL_shutdown()\fR initiates a \s-1QUIC\s0
immediate close using \s-1QUIC \s0\fB\s-1CONNECTION_CLOSE\s0\fR frames.
.PP
\&\fISSL_shutdown()\fR cannot be used on \s-1QUIC\s0 stream \s-1SSL\s0 objects. To conclude a stream
normally, see \fISSL_stream_conclude\fR\|(3); to perform a non-normal stream
termination, see \fISSL_stream_reset\fR\|(3).
.PP
\&\fISSL_shutdown_ex()\fR may be used instead of \fISSL_shutdown()\fR by an application to
provide additional information to the peer on the reason why a connection is
being shut down. The information which can be provided is as follows:
.IP "\fIquic_error_code\fR" 4
.IX Item "quic_error_code"
An optional 62\-bit application error code to be signalled to the peer. The value
must be in the range [0, 2**62\-1], else the call to \fISSL_shutdown_ex()\fR fails. If
not provided, an error code of 0 is used by default.
.IP "\fIquic_reason\fR" 4
.IX Item "quic_reason"
An optional zero-terminated (\s-1UTF\-8\s0) reason string to be signalled to the peer.
The application is responsible for providing a valid \s-1UTF\-8\s0 string and OpenSSL
will not validate the string. If a reason is not provided, or \fISSL_shutdown()\fR is
used, a zero-length string is used as the reason. If provided, the reason string
is copied and stored inside the \s-1QUIC\s0 connection \s-1SSL\s0 object and need not remain
allocated after the call to \fISSL_shutdown_ex()\fR returns. Reason strings are
bounded by the path \s-1MTU\s0 and may be silently truncated if they are too long to
fit in a \s-1QUIC\s0 packet.
.Sp
Reason strings are intended for human diagnostic purposes only, and should not
be used for application signalling.
.PP
The arguments to \fISSL_shutdown_ex()\fR are used only on the first call to
\&\fISSL_shutdown_ex()\fR (or \fISSL_shutdown()\fR) for a given \s-1QUIC\s0 connection \s-1SSL\s0 object.
These arguments are ignored on subsequent calls.
.PP
These functions do not affect an underlying network \s-1BIO\s0 or the resource it
represents; for example, a \s-1UDP\s0 datagram provided to a \s-1QUIC\s0 connection as the
network \s-1BIO\s0 will remain open.
.PP
Note that when using \s-1QUIC,\s0 an application must call \fISSL_shutdown()\fR if it wants
to ensure that all transmitted data was received by the peer. This is unlike a
\&\s-1TLS/TCP\s0 connection, where reliable transmission of buffered data is the
responsibility of the operating system. If an application calls \fISSL_free()\fR on a
\&\s-1QUIC\s0 connection \s-1SSL\s0 object or exits before completing the shutdown process using
\&\fISSL_shutdown()\fR, data which was written by the application using \fISSL_write()\fR, but
could not yet be transmitted, or which was sent but lost in the network, may not
be received by the peer.
.PP
When using \s-1QUIC,\s0 calling \fISSL_shutdown()\fR allows internal network event processing
to be performed. It is important that this processing is performed regularly,
whether during connection usage or during shutdown. If an application is not
using thread assisted mode, an application conducting shutdown should either
ensure that \fISSL_shutdown()\fR is called regularly, or alternatively ensure that
\&\fISSL_handle_events()\fR is called regularly. See \fIopenssl\-quic\fR\|(7) and
\&\fISSL_handle_events\fR\|(3) for more information.
.SS "Application Data Drainage Behaviour"
.IX Subsection "Application Data Drainage Behaviour"
When using \s-1QUIC,\s0 \fISSL_shutdown()\fR or \fISSL_shutdown_ex()\fR ordinarily waits until all
data written to a stream by an application has been acknowledged by the peer. In
other words, the shutdown process waits until all data written by the
application has been sent to the peer, and until the receipt of all such data is
acknowledged by the peer. Only once this process is completed is the shutdown
considered complete.
.PP
An exception to this is streams which terminated in a non-normal fashion, for
example due to a stream reset; only streams which are non-terminated at the time
\&\fISSL_shutdown()\fR is called, or which terminated in a normal fashion, have their
pending send buffers flushed in this manner.
.PP
This behaviour of flushing streams during the shutdown process can be skipped by
setting the \fB\s-1SSL_SHUTDOWN_FLAG_NO_STREAM_FLUSH\s0\fR flag in a call to
\&\fISSL_shutdown_ex()\fR; in this case, data remaining in stream send buffers may not
be transmitted to the peer. This flag may be used when a non-normal application
condition has occurred and the delivery of data written to streams via
\&\fISSL_write\fR\|(3) is no longer relevant.
.SS "Shutdown Mode"
.IX Subsection "Shutdown Mode"
Aspects of how \s-1QUIC\s0 handles connection closure must be taken into account by
applications. Ordinarily, \s-1QUIC\s0 expects a connection to continue to be serviced
for a substantial period of time after it is nominally closed. This is necessary
to ensure that any connection closure notification sent to the peer was
successfully received. However, a consequence of this is that a fully
RFC-compliant \s-1QUIC\s0 connection closure process could take of the order of
seconds. This may be unsuitable for some applications, such as short-lived
processes which need to exit immediately after completing an application-layer
transaction.
.PP
As such, there are two shutdown modes available to users of \s-1QUIC\s0 connection \s-1SSL\s0
objects:
.IP "\s-1RFC\s0 compliant shutdown mode" 4
.IX Item "RFC compliant shutdown mode"
This is the default behaviour. The shutdown process may take a period of time up
to three times the current estimated \s-1RTT\s0 to the peer. It is possible for the
closure process to complete much faster in some circumstances but this cannot be
relied upon.
.Sp
In blocking mode, the function will return once the closure process is complete.
In nonblocking mode, \fISSL_shutdown_ex()\fR should be called until it returns 1,
indicating the closure process is complete and the connection is now fully shut
down.
.IP "Rapid shutdown mode" 4
.IX Item "Rapid shutdown mode"
In this mode, the peer is notified of connection closure on a best effort basis
by sending a single \s-1QUIC\s0 packet. If that \s-1QUIC\s0 packet is lost, the peer will not
know that the connection has terminated until the negotiated idle timeout (if
any) expires.
.Sp
This will generally return 0 on success, indicating that the connection has not
yet been fully shut down (unless it has already done so, in which case it will
return 1).
.PP
If \fB\s-1SSL_SHUTDOWN_FLAG_RAPID\s0\fR is specified in \fIflags\fR, a rapid shutdown is
performed, otherwise an RFC-compliant shutdown is performed.
.PP
If an application calls \fISSL_shutdown_ex()\fR with \fB\s-1SSL_SHUTDOWN_FLAG_RAPID\s0\fR, an
application can subsequently change its mind about performing a rapid shutdown
by making a subsequent call to \fISSL_shutdown_ex()\fR without the flag set.
.SS "Peer-Initiated Shutdown"
.IX Subsection "Peer-Initiated Shutdown"
In some cases, an application may wish to wait for a shutdown initiated by the
peer rather than triggered locally. To do this, call \fISSL_shutdown_ex()\fR with
\&\fI\s-1SSL_SHUTDOWN_FLAG_WAIT_PEER\s0\fR specified in \fIflags\fR. In blocking mode, this
waits until the peer initiates a shutdown or the connection otherwise becomes
terminated for another reason. In nonblocking mode it exits immediately with
either success or failure depending on whether a shutdown has occurred.
.PP
If a locally initiated shutdown has already been triggered or the connection has
started terminating for another reason, this flag has no effect.
.PP
\&\fB\s-1SSL_SHUTDOWN_FLAG_WAIT_PEER\s0\fR implies \fB\s-1SSL_SHUTDOWN_FLAG_NO_STREAM_FLUSH\s0\fR, as
stream data cannot be flushed after a peer closes the connection. Stream data
may still be sent to the peer in any time spent waiting before the peer closes
the connection, though there is no guarantee of this.
.SS "Nonblocking Mode"
.IX Subsection "Nonblocking Mode"
\&\fISSL_shutdown()\fR and \fISSL_shutdown_ex()\fR block if the connection is configured in
blocking mode. This may be overridden by specifying
\&\fB\s-1SSL_SHUTDOWN_FLAG_NO_BLOCK\s0\fR in \fIflags\fR when calling \fISSL_shutdown_ex()\fR, which
causes the call to operate as though in nonblocking mode.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
For both \fISSL_shutdown()\fR and \fISSL_shutdown_ex()\fR the following return values can occur:
.IP "0" 4
The shutdown process is ongoing and has not yet completed.
.Sp
For \s-1TLS\s0 and \s-1DTLS,\s0 this means that a close_notify alert has been sent but the
peer has not yet replied in turn with its own close_notify.
.Sp
For \s-1QUIC\s0 connection \s-1SSL\s0 objects, a \s-1CONNECTION_CLOSE\s0 frame may have been
sent but the connection closure process has not yet completed.
.Sp
Unlike most other functions, returning 0 does not indicate an error.
\&\fISSL_get_error\fR\|(3) should not be called; it may misleadingly indicate an error
even though no error occurred.
.IP "1" 4
.IX Item "1"
The shutdown was successfully completed.
.Sp
For \s-1TLS\s0 and \s-1DTLS,\s0 this means that a close_notify alert was sent and the peer's
close_notify alert was received.
.Sp
For \s-1QUIC\s0 connection \s-1SSL\s0 objects, this means that the connection closure process
has completed.
.IP "<0" 4
.IX Item "<0"
The shutdown was not successful.
Call \fISSL_get_error\fR\|(3) with the return value \fBret\fR to find out the reason.
It can occur if an action is needed to continue the operation for nonblocking
BIOs.
.Sp
It can also occur when not all data was read using \fISSL_read()\fR, or if called
on a \s-1QUIC\s0 stream \s-1SSL\s0 object.
.Sp
This value is also returned when called on \s-1QUIC\s0 stream \s-1SSL\s0 objects.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fISSL_get_error\fR\|(3), \fISSL_connect\fR\|(3),
\&\fISSL_accept\fR\|(3), \fISSL_set_shutdown\fR\|(3),
\&\fISSL_CTX_set_quiet_shutdown\fR\|(3), \fISSL_CTX_set_options\fR\|(3)
\&\fISSL_clear\fR\|(3), \fISSL_free\fR\|(3),
\&\fIssl\fR\|(7), \fIbio\fR\|(7)
.SH "HISTORY"
.IX Header "HISTORY"
The \fISSL_shutdown_ex()\fR function was added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.