Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 450 insertions, 0 deletions

diff --git a/upstream/archlinux/man3/SSL_shutdown.3ssl b/upstream/archlinux/man3/SSL_shutdown.3ssl
new file mode 100644
index 00000000..4e247457
--- /dev/null
+++ b/upstream/archlinux/man3/SSL_shutdown.3ssl
@@ -0,0 +1,450 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" 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
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    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 >0, 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
+.\" ========================================================================
+.\"
+.IX Title "SSL_SHUTDOWN 3ssl"
+.TH SSL_SHUTDOWN 3ssl 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"
+\&\fBSSL_shutdown()\fR shuts down an active connection represented by an SSL object.
+.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 a 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's 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'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 \fBSSL_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 \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's 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'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 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 a 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"
+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 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.
+.Sp
+For TLS and DTLS, this means that a close_notify alert was sent and the peer's
+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, 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_options\fR\|(3)
+\&\fBSSL_clear\fR\|(3), \fBSSL_free\fR\|(3),
+\&\fBssl\fR\|(7), \fBbio\fR\|(7)
+.SH HISTORY
+.IX Header "HISTORY"
+The \fBSSL_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 "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+<https://www.openssl.org/source/license.html>.