529 lines
25 KiB
Plaintext
529 lines
25 KiB
Plaintext
.\" 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>.
|