Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 226 insertions, 0 deletions

diff --git a/upstream/archlinux/man7/ossl-guide-quic-introduction.7ssl b/upstream/archlinux/man7/ossl-guide-quic-introduction.7ssl
new file mode 100644
index 00000000..b1df87a5
--- /dev/null
+++ b/upstream/archlinux/man7/ossl-guide-quic-introduction.7ssl
@@ -0,0 +1,226 @@
+.\" -*- 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 "OSSL-GUIDE-QUIC-INTRODUCTION 7ssl"
+.TH OSSL-GUIDE-QUIC-INTRODUCTION 7ssl 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
+ossl\-guide\-quic\-introduction
+\&\- OpenSSL Guide: An introduction to QUIC in OpenSSL
+.SH INTRODUCTION
+.IX Header "INTRODUCTION"
+This page will provide an introduction to some basic QUIC concepts and
+background and how it is used within OpenSSL. It assumes that you have a basic
+understanding of UDP/IP and sockets. It also assumes that you are familiar with
+some OpenSSL and TLS fundamentals (see \fBossl\-guide\-libraries\-introduction\fR\|(7)
+and \fBossl\-guide\-tls\-introduction\fR\|(7)).
+.SH "WHAT IS QUIC?"
+.IX Header "WHAT IS QUIC?"
+QUIC is a general purpose protocol for enabling applications to securely
+communicate over a network. It is defined in RFC9000 (see
+<https://datatracker.ietf.org/doc/rfc9000/>). QUIC integrates parts of the
+TLS protocol for connection establishment but independently protects packets.
+It provides similar security guarantees to TLS such as confidentiality,
+integrity and authentication (see \fBossl\-guide\-tls\-introduction\fR\|(7)).
+.PP
+QUIC delivers a number of advantages:
+.IP "Multiple streams" 4
+.IX Item "Multiple streams"
+It supports multiple streams of communication (see "QUIC STREAMS" below),
+allowing application protocols built on QUIC to create arbitrarily many
+bytestreams for communication between a client and server. This allows an
+application protocol to avoid problems where one packet of data is held up
+waiting on another packet being delivered (commonly referred to as
+"head-of-line blocking"). It also enables an application to open additional
+logical streams without requiring a round-trip exchange of packets between the
+client and server as is required when opening an additional TLS/TCP
+connection.
+.IP HTTP/3 4
+.IX Item "HTTP/3"
+Since QUIC is the basis of HTTP/3, support for QUIC also enables applications
+to use HTTP/3 using a suitable third-party library.
+.IP "Fast connection initiation" 4
+.IX Item "Fast connection initiation"
+Future versions of OpenSSL will offer support for 0\-RTT connection initiation,
+allowing a connection to be initiated to a server and application data to be
+transmitted without any waiting time. This is similar to TLS 1.3's 0\-RTT
+functionality but also avoids the round trip needed to open a TCP socket; thus,
+it is similar to a combination of TLS 1.3 0\-RTT and TCP Fast Open.
+.IP "Connection migration" 4
+.IX Item "Connection migration"
+Future versions of OpenSSL will offer support for connection migration, allowing
+connections to seamlessly survive IP address changes.
+.IP "Datagram based use cases" 4
+.IX Item "Datagram based use cases"
+Future versions of OpenSSL will offer support for the QUIC datagram extension,
+allowing support for both TLS and DTLS-style use cases on a single connection.
+.IP "Implemented as application library" 4
+.IX Item "Implemented as application library"
+Because most QUIC implementations, including OpenSSL's implementation, are
+implemented as an application library rather than by an operating system, an
+application can gain the benefit of QUIC without needing to wait for an OS
+update to be deployed. Future evolutions and enhancements to the QUIC protocol
+can be delivered as quickly as an application can be updated without dependency
+on an OS update cadence.
+.IP "Multiplexing over a single UDP socket" 4
+.IX Item "Multiplexing over a single UDP socket"
+Because QUIC is UDP-based, it is possible to multiplex a QUIC connection on the
+same UDP socket as some other UDP-based protocols, such as RTP.
+.SH "QUIC TIME BASED EVENTS"
+.IX Header "QUIC TIME BASED EVENTS"
+A key difference between the TLS implementation and the QUIC implementation in
+OpenSSL is how time is handled. The QUIC protocol requires various actions to be
+performed on a regular basis regardless of whether application data is being
+transmitted or received.
+.PP
+OpenSSL introduces a new function \fBSSL_handle_events\fR\|(3) that will
+automatically process any outstanding time based events that must be handled.
+Alternatively calling any I/O function such as \fBSSL_read_ex\fR\|(3) or
+\&\fBSSL_write_ex\fR\|(3) will also process these events. There is also
+\&\fBSSL_get_event_timeout\fR\|(3) which tells an application the amount of time that
+remains until \fBSSL_handle_events\fR\|(3) (or any I/O function) must be called.
+.PP
+Fortunately a blocking application that does not leave the QUIC connection idle,
+and is regularly calling I/O functions does not typically need to worry about
+this. However if you are developing a nonblocking application or one that may
+leave the QUIC connection idle for a period of time then you will need to
+arrange to call these functions.
+.PP
+OpenSSL provides an optional "thread assisted mode" that will automatically
+create a background thread and will regularly call \fBSSL_handle_events\fR\|(3) in a
+thread safe manner. This provides a simple way for an application to satisfy the
+QUIC requirements for time based events without having to implement special
+logic to accomplish it.
+.SH "QUIC AND TLS"
+.IX Header "QUIC AND TLS"
+QUIC reuses parts of the TLS protocol in its implementation. Specifically the
+TLS handshake also exists in QUIC. The TLS handshake messages are wrapped up in
+QUIC protocol messages in order to send them to the peer. Once the TLS handshake
+is complete all application data is sent entirely using QUIC protocol messages
+without using TLS \- although some TLS handshake messages may still be sent in
+some circumstances.
+.PP
+This relationship between QUIC and TLS means that many of the API functions in
+OpenSSL that apply to TLS connections also apply to QUIC connections and
+applications can use them in exactly the same way. Some functions do not apply
+to QUIC at all, and others have altered semantics. You should refer to the
+documentation pages for each function for information on how it applies to QUIC.
+Typically if QUIC is not mentioned in the manual pages then the functions apply
+to both TLS and QUIC.
+.SH "QUIC STREAMS"
+.IX Header "QUIC STREAMS"
+QUIC introduces the concept of "streams". A stream provides a reliable
+mechanism for sending and receiving application data between the endpoints. The
+bytes transmitted are guaranteed to be received in the same order they were sent
+without any loss of data or reordering of the bytes. A TLS application
+effectively has one bi-directional stream available to it per TLS connection. A
+QUIC application can have multiple uni-directional or bi-directional streams
+available to it for each connection.
+.PP
+In OpenSSL an \fBSSL\fR object is used to represent both connections and streams.
+A QUIC application creates an initial \fBSSL\fR object to represent the connection
+(known as the connection \fBSSL\fR object). Once the connection is complete
+additional \fBSSL\fR objects can be created to represent streams (known as stream
+\&\fBSSL\fR objects). Unless configured otherwise, a "default" stream is also
+associated with the connection \fBSSL\fR object so you can still write data and
+read data to/from it. Some OpenSSL API functions can only be used with
+connection \fBSSL\fR objects, and some can only be used with stream \fBSSL\fR objects.
+Check the documentation for each function to confirm what type of \fBSSL\fR object
+can be used in any particular context. A connection \fBSSL\fR object that has a
+default stream attached to it can be used in contexts that require a connection
+\&\fBSSL\fR object or in contexts that require a stream \fBSSL\fR object.
+.SH "SOCKETS AND BLOCKING"
+.IX Header "SOCKETS AND BLOCKING"
+TLS assumes "stream" type semantics for its underlying transport layer protocol
+(usually achieved by using TCP). However QUIC assumes "datagram" type semantics
+by using UDP. An OpenSSL application using QUIC is responsible for creating a
+BIO to represent the underlying transport layer. This BIO must support datagrams
+and is typically \fBBIO_s_datagram\fR\|(3), but other \fBBIO\fR choices are available.
+See \fBbio\fR\|(7) for an introduction to OpenSSL's \fBBIO\fR concept.
+.PP
+A significant difference between OpenSSL TLS applications and OpenSSL QUIC
+applications is the way that blocking is implemented. In TLS if your application
+expects blocking behaviour then you configure the underlying socket for
+blocking. Conversely if your application wants nonblocking behaviour then the
+underlying socket is configured to be nonblocking.
+.PP
+With an OpenSSL QUIC application the underlying socket must always be configured
+to be nonblocking. Howevever the \fBSSL\fR object will, by default, still operate
+in blocking mode. So, from an application's perspective, calls to functions such
+as \fBSSL_read_ex\fR\|(3), \fBSSL_write_ex\fR\|(3) and other I/O functions will still
+block. OpenSSL itself provides that blocking capability for QUIC instead of the
+socket. If nonblocking behaviour is desired then the application must call
+\&\fBSSL_set_blocking_mode\fR\|(3).
+.SH "FURTHER READING"
+.IX Header "FURTHER READING"
+See \fBossl\-guide\-quic\-client\-block\fR\|(7) to see an example of applying these
+concepts in order to write a simple blocking QUIC client.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7),
+\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7),
+\&\fBossl\-guide\-tls\-client\-block\fR\|(7), \fBossl\-guide\-quic\-client\-block\fR\|(7), \fBbio\fR\|(7)
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 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>.