diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/SSL_shutdown.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/SSL_shutdown.3 | 582 |
1 files changed, 368 insertions, 214 deletions
diff --git a/secure/lib/libcrypto/man/man3/SSL_shutdown.3 b/secure/lib/libcrypto/man/man3/SSL_shutdown.3 index d8510ce551b4..57eb6d24608d 100644 --- a/secure/lib/libcrypto/man/man3/SSL_shutdown.3 +++ b/secure/lib/libcrypto/man/man3/SSL_shutdown.3 @@ -1,4 +1,5 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== @@ -15,29 +16,12 @@ .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' +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .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\} @@ -69,231 +53,401 @@ .\} .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 +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l .\" ======================================================================== .\" -.IX Title "SSL_SHUTDOWN 3" -.TH SSL_SHUTDOWN 3 "2022-07-05" "1.1.1q" "OpenSSL" +.IX Title "SSL_SHUTDOWN 3ossl" +.TH SSL_SHUTDOWN 3ossl 2026-04-07 3.5.6 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 \- shut down a TLS/SSL connection -.SH "SYNOPSIS" +.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" +.SH DESCRIPTION .IX Header "DESCRIPTION" -\&\fBSSL_shutdown()\fR shuts down an active \s-1TLS/SSL\s0 connection. It sends the -close_notify shutdown alert to the peer. -.SH "NOTES" -.IX Header "NOTES" -\&\fBSSL_shutdown()\fR tries to send the close_notify shutdown alert to the peer. -Whether the operation succeeds or not, the \s-1SSL_SENT_SHUTDOWN\s0 flag is set and -a currently open session is considered closed and good and will be kept in the -session cache for further reuse. -.PP -Note that \fBSSL_shutdown()\fR must not be called if a previous fatal error has -occurred on a connection i.e. if \fBSSL_get_error()\fR has returned \s-1SSL_ERROR_SYSCALL\s0 -or \s-1SSL_ERROR_SSL.\s0 -.PP -The shutdown procedure consists of two steps: sending of the close_notify -shutdown alert, and reception of the peer's close_notify shutdown alert. -The order of those two steps depends on the application. -.PP -It is acceptable for an application to only send its shutdown alert and -then close the underlying connection without waiting for the peer's response. -This way resources can be saved, as the process can already terminate or -serve another connection. -This should only be done when it is known that the other side will not send more -data, otherwise there is a risk of a truncation attack. -.PP -When a client only writes and never reads from the connection, and the server -has sent a session ticket to establish a session, the client might not be able -to resume the session because it did not received and process the session ticket -from the server. -In case the application wants to be able to resume the session, it is recommended to -do a complete shutdown procedure (bidirectional close_notify alerts). -.PP -When the underlying connection shall be used for more communications, the -complete shutdown procedure must be performed, so that the peers stay -synchronized. -.PP -\&\fBSSL_shutdown()\fR only closes the write direction. -It is not possible to call \fBSSL_write()\fR after calling \fBSSL_shutdown()\fR. -The read direction is closed by the peer. -.SS "First to close the connection" -.IX Subsection "First to close the connection" -When the application is the first party to send the close_notify -alert, \fBSSL_shutdown()\fR will only send the alert and then set the -\&\s-1SSL_SENT_SHUTDOWN\s0 flag (so that the session is considered good and will -be kept in the cache). -If successful, \fBSSL_shutdown()\fR will return 0. -.PP -If a unidirectional shutdown is enough (the underlying connection shall be -closed anyway), this first successful call to \fBSSL_shutdown()\fR is sufficient. -.PP -In order to complete the bidirectional shutdown handshake, the peer needs -to send back a close_notify alert. -The \s-1SSL_RECEIVED_SHUTDOWN\s0 flag will be set after receiving and processing -it. -.PP -The peer is still allowed to send data after receiving the close_notify -event. -When it is done sending data, it will send the close_notify alert. -\&\fBSSL_read()\fR should be called until all data is received. -\&\fBSSL_read()\fR will indicate the end of the peer data by returning <= 0 -and \fBSSL_get_error()\fR returning \s-1SSL_ERROR_ZERO_RETURN.\s0 -.SS "Peer closes the connection" -.IX Subsection "Peer closes the connection" -If the peer already sent the close_notify alert \fBand\fR it was -already processed implicitly inside another function -(\fBSSL_read\fR\|(3)), the \s-1SSL_RECEIVED_SHUTDOWN\s0 flag is set. -\&\fBSSL_read()\fR will return <= 0 in that case, and \fBSSL_get_error()\fR will return -\&\s-1SSL_ERROR_ZERO_RETURN.\s0 -\&\fBSSL_shutdown()\fR will send the close_notify alert, set the \s-1SSL_SENT_SHUTDOWN\s0 -flag. -If successful, \fBSSL_shutdown()\fR will return 1. -.PP -Whether \s-1SSL_RECEIVED_SHUTDOWN\s0 is already set can be checked using the -\&\fBSSL_get_shutdown()\fR (see also \fBSSL_set_shutdown\fR\|(3) call. -.SH "NOTES" -.IX Header "NOTES" -The behaviour of \fBSSL_shutdown()\fR additionally depends on the underlying \s-1BIO.\s0 -If the underlying \s-1BIO\s0 is \fBblocking\fR, \fBSSL_shutdown()\fR will only return once the -handshake step has been finished or an error occurred. -.PP -If the underlying \s-1BIO\s0 is \fBnonblocking\fR, \fBSSL_shutdown()\fR will also return -when the underlying \s-1BIO\s0 could not satisfy the needs of \fBSSL_shutdown()\fR -to continue the handshake. In this case a call to \fBSSL_get_error()\fR with the -return value of \fBSSL_shutdown()\fR will yield \fB\s-1SSL_ERROR_WANT_READ\s0\fR or -\&\fB\s-1SSL_ERROR_WANT_WRITE\s0\fR. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of \fBSSL_shutdown()\fR. -The action depends on the underlying \s-1BIO.\s0 When using a nonblocking socket, -nothing is to be done, but \fBselect()\fR can be used to check for the required -condition. When using a buffering \s-1BIO,\s0 like a \s-1BIO\s0 pair, data must be written -into or retrieved out of the \s-1BIO\s0 before being able to continue. -.PP -After \fBSSL_shutdown()\fR returned 0, it is possible to call \fBSSL_shutdown()\fR again -to wait for the peer's close_notify alert. -\&\fBSSL_shutdown()\fR will return 1 in that case. -However, it is recommended to wait for it using \fBSSL_read()\fR instead. -.PP -\&\fBSSL_shutdown()\fR can be modified to only set the connection to \*(L"shutdown\*(R" -state but not actually send the close_notify alert messages, -see \fBSSL_CTX_set_quiet_shutdown\fR\|(3). -When \*(L"quiet shutdown\*(R" is enabled, \fBSSL_shutdown()\fR will always succeed -and return 1. -Note that this is not standard compliant behaviour. -It should only be done when the peer has a way to make sure all -data has been received and doesn't wait for the close_notify alert -message, otherwise an unexpected \s-1EOF\s0 will be reported. -.PP -There are implementations that do not send the required close_notify alert. -If there is a need to communicate with such an implementation, and it's clear -that all data has been received, do not wait for the peer's close_notify alert. -Waiting for the close_notify alert when the peer just closes the connection will -result in an error being generated. +\&\fBSSL_shutdown()\fR shuts down an active connection represented by an SSL object. \fIssl\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBSSL_shutdown_ex()\fR is an extended version of \fBSSL_shutdown()\fR. If non\-NULL, \fIargs\fR +must point to a \fBSSL_SHUTDOWN_EX_ARGS\fR structure and \fIargs_len\fR must be set to +\&\f(CWsizeof(SSL_SHUTDOWN_EX_ARGS)\fR. The \fBSSL_SHUTDOWN_EX_ARGS\fR structure must be +zero\-initialized. If \fIargs\fR is NULL, the behaviour is the same as passing a +zero\-initialised \fBSSL_SHUTDOWN_EX_ARGS\fR structure. Currently, all extended +arguments relate to usage with QUIC, therefore this call functions identically +to \fBSSL_shutdown()\fR when not being used with QUIC. +.PP +While the general operation of \fBSSL_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 \fBSSL_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 +\&\fBSSL_shutdown()\fR will return 1. See the RETURN VALUES section for more +information. +.PP +\&\fBSSL_shutdown()\fR should not be called if a previous fatal error has occurred on a +connection; i.e., if \fBSSL_get_error\fR\|(3) has returned \fBSSL_ERROR_SYSCALL\fR or +\&\fBSSL_ERROR_SSL\fR. +.SH "TLS AND DTLS\-SPECIFIC CONSIDERATIONS" +.IX Header "TLS AND DTLS-SPECIFIC CONSIDERATIONS" +Shutdown for SSL/TLS and DTLS is implemented in terms of the SSL/TLS/DTLS +close_notify alert message. The shutdown process for SSL/TLS and DTLS +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 \fBSSL_shutdown()\fR on an SSL/TLS or DTLS SSL 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 \fBSSL_shutdown()\fR only closes the write direction of the connection; the +read direction is closed by the peer. Once \fBSSL_shutdown()\fR is called, +\&\fBSSL_write\fR\|(3) can no longer be used, but \fBSSL_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\*(Aqs shutdown indication. +.PP +\&\fBSSL_shutdown()\fR does not affect an underlying network connection such as a TCP +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 EOF +condition when calling +\&\fBSSL_read\fR\|(3) (i.e., \fBSSL_read\fR\|(3) will fail and \fBSSL_get_error\fR\|(3) will +return \fBSSL_ERROR_ZERO_RETURN\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 \fBSSL_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 \fBSSL_write\fR\|(3) before doing so. If an application does +not call \fBSSL_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 BIO is blocking, a call to \fBSSL_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 \fBSSL_shutdown()\fR +with a blocking underlying BIO will also return if an error occurs. +.PP +If the underlying BIO 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), \fBSSL_shutdown()\fR returns 0 to indicate that the +shutdown process is still ongoing; in this case, a call to \fBSSL_get_error\fR\|(3) +will yield \fBSSL_ERROR_WANT_READ\fR or \fBSSL_ERROR_WANT_WRITE\fR. +.PP +An application can then detect completion of the shutdown process by calling +\&\fBSSL_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 +\&\fBSSL_read\fR\|(3) until \fBSSL_get_error\fR\|(3) indicates EOF by returning +\&\fBSSL_ERROR_ZERO_RETURN\fR. This ensures any data received immediately before the +peer\*(Aqs 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 \fBSSL_shutdown()\fR (to complete the +shutdown by confirming receipt of the peer\*(Aqs close_notify message) will fail if +it is called when the application has not read all pending application data +sent by the peer using \fBSSL_read\fR\|(3). +.PP +When calling \fBSSL_shutdown()\fR, the \fBSSL_SENT_SHUTDOWN\fR flag is set once an +attempt is made to send a close_notify alert, regardless of whether the attempt +was successful. The \fBSSL_RECEIVED_SHUTDOWN\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 \fBSSL_read\fR\|(3) or \fBSSL_shutdown()\fR. These flags +may be checked using \fBSSL_get_shutdown\fR\|(3). +.SS "Fast Shutdown" +.IX Subsection "Fast Shutdown" +Alternatively, it is acceptable for an application to call \fBSSL_shutdown()\fR once +(such that it returns 0) and then close the underlying connection without +waiting for the peer\*(Aqs response. This allows for a more rapid shutdown process +if the application does not wish to wait for the peer. +.PP +This alternative "fast shutdown" 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 \fBSSL_shutdown()\fR +process, in which both parties send close_notify alerts and \fBSSL_shutdown()\fR +returns 1, provides a cryptographically authenticated indication of the end of a +connection. +.PP +This approach of a single \fBSSL_shutdown()\fR call without waiting is preferable to +simply calling \fBSSL_free\fR\|(3) or \fBSSL_clear\fR\|(3) as calling \fBSSL_shutdown()\fR +beforehand makes an SSL 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 TCP 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 \fBSSL_shutdown()\fR sets the SSL_SENT_SHUTDOWN flag (see +\&\fBSSL_set_shutdown\fR\|(3)), regardless of whether the transmission of the +close_notify alert was successful or not. This makes the SSL session eligible +for reuse; the SSL session is considered properly closed and can be reused for +future connections. +.SS "Quiet Shutdown" +.IX Subsection "Quiet Shutdown" +\&\fBSSL_shutdown()\fR can be modified to set the connection to the "shutdown" +state without actually sending a close_notify alert message; see +\&\fBSSL_CTX_set_quiet_shutdown\fR\|(3). When "quiet shutdown" is enabled, +\&\fBSSL_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\*(Aqt 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 SSL/TLS implementations that never send the required close_notify +alert message but simply close the underlying transport (e.g. a TCP connection) +instead. This will ordinarily result in an error being generated. +.PP +If compatibility with such peers is desired, the option +\&\fBSSL_OP_IGNORE_UNEXPECTED_EOF\fR can be set. For more information, see +\&\fBSSL_CTX_set_options\fR\|(3). +.PP +Note that use of this option means that the EOF 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 \fBSSL_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 an SSL/TLS or DTLS connection and never +reads, OpenSSL may never process new SSL/TLS session tickets sent by the server. +This is because OpenSSL ordinarily processes handshake messages received from a +peer during calls to \fBSSL_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 \fBSSL_shutdown()\fR until it returns 1, as described above. This +will ensure there is an opportunity for SSL/TLS 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 QUIC connection SSL object, \fBSSL_shutdown()\fR initiates a QUIC +immediate close using QUIC \fBCONNECTION_CLOSE\fR frames. +.PP +\&\fBSSL_shutdown()\fR cannot be used on QUIC stream SSL objects. To conclude a stream +normally, see \fBSSL_stream_conclude\fR\|(3); to perform a non\-normal stream +termination, see \fBSSL_stream_reset\fR\|(3). +.PP +\&\fBSSL_shutdown_ex()\fR may be used instead of \fBSSL_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 \fBSSL_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 (UTF\-8) reason string to be signalled to the peer. +The application is responsible for providing a valid UTF\-8 string and OpenSSL +will not validate the string. If a reason is not provided, or \fBSSL_shutdown()\fR is +used, a zero\-length string is used as the reason. If provided, the reason string +is copied and stored inside the QUIC connection SSL object and need not remain +allocated after the call to \fBSSL_shutdown_ex()\fR returns. Reason strings are +bounded by the path MTU and may be silently truncated if they are too long to +fit in a QUIC packet. +.Sp +Reason strings are intended for human diagnostic purposes only, and should not +be used for application signalling. +.PP +The arguments to \fBSSL_shutdown_ex()\fR are used only on the first call to +\&\fBSSL_shutdown_ex()\fR (or \fBSSL_shutdown()\fR) for a given QUIC connection SSL object. +These arguments are ignored on subsequent calls. +.PP +These functions do not affect an underlying network BIO or the resource it +represents; for example, a UDP datagram provided to a QUIC connection as the +network BIO will remain open. +.PP +Note that when using QUIC, an application must call \fBSSL_shutdown()\fR if it wants +to ensure that all transmitted data was received by the peer. This is unlike a +TLS/TCP connection, where reliable transmission of buffered data is the +responsibility of the operating system. If an application calls \fBSSL_free()\fR on a +QUIC connection SSL object or exits before completing the shutdown process using +\&\fBSSL_shutdown()\fR, data which was written by the application using \fBSSL_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 QUIC, calling \fBSSL_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 \fBSSL_shutdown()\fR is called regularly, or alternatively ensure that +\&\fBSSL_handle_events()\fR is called regularly. See \fBopenssl\-quic\fR\|(7) and +\&\fBSSL_handle_events\fR\|(3) for more information. +.SS "Application Data Drainage Behaviour" +.IX Subsection "Application Data Drainage Behaviour" +When using QUIC, \fBSSL_shutdown()\fR or \fBSSL_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 +\&\fBSSL_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 \fBSSL_SHUTDOWN_FLAG_NO_STREAM_FLUSH\fR flag in a call to +\&\fBSSL_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 +\&\fBSSL_write\fR\|(3) is no longer relevant. +.SS "Shutdown Mode" +.IX Subsection "Shutdown Mode" +Aspects of how QUIC handles connection closure must be taken into account by +applications. Ordinarily, QUIC 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 QUIC 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 QUIC connection SSL +objects: +.IP "RFC 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 RTT 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, \fBSSL_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 QUIC packet. If that QUIC 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 \fBSSL_SHUTDOWN_FLAG_RAPID\fR is specified in \fIflags\fR, a rapid shutdown is +performed, otherwise an RFC\-compliant shutdown is performed. +.PP +If an application calls \fBSSL_shutdown_ex()\fR with \fBSSL_SHUTDOWN_FLAG_RAPID\fR, an +application can subsequently change its mind about performing a rapid shutdown +by making a subsequent call to \fBSSL_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 \fBSSL_shutdown_ex()\fR with +\&\fISSL_SHUTDOWN_FLAG_WAIT_PEER\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 +\&\fBSSL_SHUTDOWN_FLAG_WAIT_PEER\fR implies \fBSSL_SHUTDOWN_FLAG_NO_STREAM_FLUSH\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" +\&\fBSSL_shutdown()\fR and \fBSSL_shutdown_ex()\fR block if the connection is configured in +blocking mode. This may be overridden by specifying +\&\fBSSL_SHUTDOWN_FLAG_NO_BLOCK\fR in \fIflags\fR when calling \fBSSL_shutdown_ex()\fR, which +causes the call to operate as though in nonblocking mode. .SH "RETURN VALUES" .IX Header "RETURN VALUES" -The following return values can occur: -.IP "0" 4 -The shutdown is not yet finished: the close_notify was sent but the peer -did not send it back yet. -Call \fBSSL_read()\fR to do a bidirectional shutdown. +For both \fBSSL_shutdown()\fR and \fBSSL_shutdown_ex()\fR the following return values can occur: +.IP 0 4 +The shutdown process is ongoing and has not yet completed. +.Sp +For TLS and DTLS, 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 QUIC connection SSL objects, a CONNECTION_CLOSE frame may have been +sent but the connection closure process has not yet completed. .Sp -Unlike most other function, returning 0 does not indicate an error. -\&\fBSSL_get_error\fR\|(3) should not get called, it may misleadingly -indicate an error even though no error occurred. -.IP "1" 4 +Unlike most other functions, returning 0 does not indicate an error. +\&\fBSSL_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. The close_notify alert was sent -and the peer's close_notify alert was received. -.IP "<0" 4 +The shutdown was successfully completed. +.Sp +For TLS and DTLS, this means that a close_notify alert was sent and the peer\*(Aqs +close_notify alert was received. +.Sp +For QUIC connection SSL objects, this means that the connection closure process +has completed. +.IP <0 4 .IX Item "<0" The shutdown was not successful. Call \fBSSL_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 \fBSSL_read()\fR. +It can also occur when not all data was read using \fBSSL_read()\fR, or if called +on a QUIC stream SSL object. +.Sp +This value is also returned when called on QUIC stream SSL objects. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBSSL_get_error\fR\|(3), \fBSSL_connect\fR\|(3), \&\fBSSL_accept\fR\|(3), \fBSSL_set_shutdown\fR\|(3), -\&\fBSSL_CTX_set_quiet_shutdown\fR\|(3), +\&\fBSSL_CTX_set_quiet_shutdown\fR\|(3), \fBSSL_CTX_set_options\fR\|(3) \&\fBSSL_clear\fR\|(3), \fBSSL_free\fR\|(3), \&\fBssl\fR\|(7), \fBbio\fR\|(7) -.SH "COPYRIGHT" +.SH HISTORY +.IX Header "HISTORY" +The \fBSSL_shutdown_ex()\fR function was added in OpenSSL 3.2. +.SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2000\-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the "License"). 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 +in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>. |