Adding upstream version 4.23.0.upstream/4.23.0

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

1 files changed, 453 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man7/ossl-guide-quic-multi-stream.7ssl b/upstream/debian-unstable/man7/ossl-guide-quic-multi-stream.7ssl
new file mode 100644
index 00000000..e3169803
--- /dev/null
+++ b/upstream/debian-unstable/man7/ossl-guide-quic-multi-stream.7ssl
@@ -0,0 +1,453 @@
+.\" -*- 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-MULTI-STREAM 7SSL"
+.TH OSSL-GUIDE-QUIC-MULTI-STREAM 7SSL 2024-04-04 3.2.2-dev 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\-multi\-stream
+\&\- OpenSSL Guide: Writing a simple multi\-stream QUIC client
+.SH INTRODUCTION
+.IX Header "INTRODUCTION"
+This page will introduce some important concepts required to write a simple
+QUIC multi-stream application. It assumes a basic understanding of QUIC and how
+it is used in OpenSSL. See \fBossl\-guide\-quic\-introduction\fR\|(7) and
+\&\fBossl\-guide\-quic\-client\-block\fR\|(7).
+.SH "QUIC STREAMS"
+.IX Header "QUIC STREAMS"
+In a QUIC multi-stream application we separate out the concepts of a QUIC
+"connection" and a QUIC "stream". A connection object represents the overarching
+details of the connection between a client and a server including all its
+negotiated and configured parameters. We use the \fBSSL\fR object for that in an
+OpenSSL application (known as the connection \fBSSL\fR object). It is created by an
+application calling \fBSSL_new\fR\|(3).
+.PP
+Separately a connection can have zero or more streams associated with it
+(although a connection with zero streams is probably not very useful, so
+normally you would have at least one). A stream is used to send and receive
+data between the two peers. Each stream is also represented by an \fBSSL\fR
+object. A stream is logically independent of all the other streams associated
+with the same connection. Data sent on a stream is guaranteed to be delivered
+in the order that it was sent within that stream. The same is not true across
+streams, e.g. if an application sends data on stream 1 first and then sends some
+more data on stream 2 second, then the remote peer may receive the data sent on
+stream 2 before it receives the data sent on stream 1.
+.PP
+Once the connection \fBSSL\fR object has completed its handshake (i.e.
+\&\fBSSL_connect\fR\|(3) has returned 1), stream \fBSSL\fR objects are created by the
+application calling \fBSSL_new_stream\fR\|(3) or \fBSSL_accept_stream\fR\|(3) (see
+"CREATING NEW STREAMS" below).
+.PP
+The same threading rules apply to \fBSSL\fR objects as for most OpenSSL objects
+(see \fBossl\-guide\-libraries\-introduction\fR\|(7)). In particular most OpenSSL
+functions are thread safe, but the \fBSSL\fR object is not. This means that you can
+use an \fBSSL\fR object representing one stream at the same time as another thread
+is using a different \fBSSL\fR object for a different stream on the same
+connection. But you cannot use the same \fBSSL\fR object on two different threads
+at the same time (without additional application level locking).
+.SH "THE DEFAULT STREAM"
+.IX Header "THE DEFAULT STREAM"
+A connection \fBSSL\fR object may also (optionally) be associated with a stream.
+This stream is known as the default stream. The default stream is automatically
+created and associated with the \fBSSL\fR object when the application calls
+\&\fBSSL_read_ex\fR\|(3), \fBSSL_read\fR\|(3), \fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) and
+passes the connection \fBSSL\fR object as a parameter.
+.PP
+If a client application calls \fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) first then
+(by default) the default stream will be a client-initiated bi-directional
+stream. If a client application calls \fBSSL_read_ex\fR\|(3) or \fBSSL_read\fR\|(3)
+first then the first stream initiated by the server will be used as the default
+stream (whether it is bi-directional or uni-directional).
+.PP
+This behaviour can be controlled via the default stream mode. See
+\&\fBSSL_set_default_stream_mode\fR\|(3) for further details.
+.PP
+It is recommended that new multi-stream applications should not use a default
+stream at all and instead should use a separate stream \fBSSL\fR object for each
+stream that is used. This requires calling \fBSSL_set_default_stream_mode\fR\|(3)
+and setting the mode to \fBSSL_DEFAULT_STREAM_MODE_NONE\fR.
+.SH "CREATING NEW STREAMS"
+.IX Header "CREATING NEW STREAMS"
+An endpoint can create a new stream by calling \fBSSL_new_stream\fR\|(3). This
+creates a locally initiated stream. In order to do so you must pass the QUIC
+connection \fBSSL\fR object as a parameter. You can also specify whether you want a
+bi-directional or a uni-directional stream.
+.PP
+The function returns a new QUIC stream \fBSSL\fR object for sending and receiving
+data on that stream.
+.PP
+The peer may also initiate streams. An application can use the function
+\&\fBSSL_get_accept_stream_queue_len\fR\|(3) to determine the number of streams that
+the peer has initiated that are waiting for the application to handle. An
+application can call \fBSSL_accept_stream\fR\|(3) to create a new \fBSSL\fR object for
+a remotely initiated stream. If the peer has not initiated any then this call
+will block until one is available if the connection object is in blocking mode
+(see \fBSSL_set_blocking_mode\fR\|(3)).
+.PP
+When using a default stream OpenSSL will prevent new streams from being
+accepted. To override this behaviour you must call
+\&\fBSSL_set_incoming_stream_policy\fR\|(3) to set the policy to
+\&\fBSSL_INCOMING_STREAM_POLICY_ACCEPT\fR. See the man page for further details. This
+is not relevant if the default stream has been disabled as described in
+"THE DEFAULT STREAM" above.
+.PP
+Any stream may be bi-directional or uni-directional. If it is uni-directional
+then the initiator can write to it but not read from it, and vice-versa for the
+peer. You can determine what type of stream an \fBSSL\fR object represents by
+calling \fBSSL_get_stream_type\fR\|(3). See the man page for further details.
+.SH "USING A STREAM TO SEND AND RECEIVE DATA"
+.IX Header "USING A STREAM TO SEND AND RECEIVE DATA"
+Once you have a stream \fBSSL\fR object (which includes the connection \fBSSL\fR
+object if a default stream is in use) then you can send and receive data over it
+using the \fBSSL_write_ex\fR\|(3), \fBSSL_write\fR\|(3), \fBSSL_read_ex\fR\|(3) or
+\&\fBSSL_read\fR\|(3) functions. See the man pages for further details.
+.PP
+In the event of one of these functions not returning a success code then
+you should call \fBSSL_get_error\fR\|(3) to find out further details about the error.
+In blocking mode this will either be a fatal error (e.g. \fBSSL_ERROR_SYSCALL\fR
+or \fBSSL_ERROR_SSL\fR), or it will be \fBSSL_ERROR_ZERO_RETURN\fR which can occur
+when attempting to read data from a stream and the peer has indicated that the
+stream is concluded (i.e. "FIN" has been signalled on the stream). This means
+that the peer will send no more data on that stream. Note that the
+interpretation of \fBSSL_ERROR_ZERO_RETURN\fR is slightly different for a QUIC
+application compared to a TLS application. In TLS it occurs when the connection
+has been shutdown by the peer. In QUIC this only tells you that the current
+stream has been concluded by the peer. It tells you nothing about the underlying
+connection. If the peer has concluded the stream then no more data will be
+received on it, however an application can still send data to the peer until
+the send side of the stream has also been concluded. This can happen by the
+application calling \fBSSL_stream_conclude\fR\|(3). It is an error to attempt to
+send more data on a stream after \fBSSL_stream_conclude\fR\|(3) has been called.
+.PP
+It is also possible to abandon a stream abnormally by calling
+\&\fBSSL_stream_reset\fR\|(3).
+.PP
+Once a stream object is no longer needed it should be freed via a call to
+\&\fBSSL_free\fR\|(3). An application should not call \fBSSL_shutdown\fR\|(3) on it since
+this is only meaningful for connection level \fBSSL\fR objects. Freeing the stream
+will automatically signal STOP_SENDING to the peer.
+.SH "STREAMS AND CONNECTIONS"
+.IX Header "STREAMS AND CONNECTIONS"
+Given a stream object it is possible to get the \fBSSL\fR object corresponding to
+the connection via a call to \fBSSL_get0_connection\fR\|(3). Multi-threaded
+restrictions apply so care should be taken when using the returned connection
+object. Specifically, if you are handling each of your stream objects in a
+different thread and call \fBSSL_get0_connection\fR\|(3) from within that thread then
+you must be careful to not to call any function that uses the connection object
+at the same time as one of the other threads is also using that connection
+object (with the exception of \fBSSL_accept_stream\fR\|(3) and
+\&\fBSSL_get_accept_stream_queue_len\fR\|(3) which are thread-safe).
+.PP
+A stream object does not inherit all its settings and values from its parent
+\&\fBSSL\fR connection object. Therefore certain function calls that are relevant to
+the connection as a whole will not work on a stream. For example the function
+\&\fBSSL_get_certificate\fR\|(3) can be used to obtain a handle on the peer certificate
+when called with a connection \fBSSL\fR object. When called with a stream \fBSSL\fR
+object it will return NULL.
+.SH "SIMPLE MULTI-STREAM QUIC CLIENT EXAMPLE"
+.IX Header "SIMPLE MULTI-STREAM QUIC CLIENT EXAMPLE"
+This section will present various source code samples demonstrating how to write
+a simple multi-stream QUIC client application which connects to a server, send
+some HTTP/1.0 requests to it, and read back the responses. Note that HTTP/1.0
+over QUIC is non-standard and will not be supported by real world servers. This
+is for demonstration purposes only.
+.PP
+We will build on the example code for the simple blocking QUIC client that is
+covered on the \fBossl\-guide\-quic\-client\-block\fR\|(7) page and we assume that you
+are familiar with it. We will only describe the differences between the simple
+blocking QUIC client and the multi-stream QUIC client. Although the example code
+uses blocking \fBSSL\fR objects, you can equally use nonblocking \fBSSL\fR objects.
+See \fBossl\-guide\-quic\-client\-non\-block\fR\|(7) for more information about writing a
+nonblocking QUIC client.
+.PP
+The complete source code for this example multi-stream QUIC client is available
+in the \f(CW\*(C`demos/guide\*(C'\fR directory of the OpenSSL source distribution in the file
+\&\f(CW\*(C`quic\-multi\-stream.c\*(C'\fR. It is also available online at
+<https://github.com/openssl/openssl/blob/master/demos/guide/quic\-multi\-stream.c>.
+.SS "Disabling the default stream"
+.IX Subsection "Disabling the default stream"
+As discussed above in "THE DEFAULT STREAM" we will follow the recommendation
+to disable the default stream for our multi-stream client. To do this we call
+the \fBSSL_set_default_stream_mode\fR\|(3) function and pass in our connection \fBSSL\fR
+object and the value \fBSSL_DEFAULT_STREAM_MODE_NONE\fR.
+.PP
+.Vb 8
+\&    /*
+\&     * We will use multiple streams so we will disable the default stream mode.
+\&     * This is not a requirement for using multiple streams but is recommended.
+\&     */
+\&    if (!SSL_set_default_stream_mode(ssl, SSL_DEFAULT_STREAM_MODE_NONE)) {
+\&        printf("Failed to disable the default stream mode\en");
+\&        goto end;
+\&    }
+.Ve
+.SS "Creating the request streams"
+.IX Subsection "Creating the request streams"
+For the purposes of this example we will create two different streams to send
+two different HTTP requests to the server. For the purposes of demonstration the
+first of these will be a bi-directional stream and the second one will be a
+uni-directional one:
+.PP
+.Vb 10
+\&    /*
+\&     * We create two new client initiated streams. The first will be
+\&     * bi\-directional, and the second will be uni\-directional.
+\&     */
+\&    stream1 = SSL_new_stream(ssl, 0);
+\&    stream2 = SSL_new_stream(ssl, SSL_STREAM_FLAG_UNI);
+\&    if (stream1 == NULL || stream2 == NULL) {
+\&        printf("Failed to create streams\en");
+\&        goto end;
+\&    }
+.Ve
+.SS "Writing data to the streams"
+.IX Subsection "Writing data to the streams"
+Once the streams are successfully created we can start writing data to them. In
+this example we will be sending a different HTTP request on each stream. To
+avoid repeating too much code we write a simple helper function to send an HTTP
+request to a stream:
+.PP
+.Vb 5
+\&    int write_a_request(SSL *stream, const char *request_start,
+\&                        const char *hostname)
+\&    {
+\&        const char *request_end = "\er\en\er\en";
+\&        size_t written;
+\&
+\&        if (!SSL_write_ex(stream, request_start, strlen(request_start), &written))
+\&            return 0;
+\&        if (!SSL_write_ex(stream, hostname, strlen(hostname), &written))
+\&            return 0;
+\&        if (!SSL_write_ex(stream, request_end, strlen(request_end), &written))
+\&            return 0;
+\&
+\&        return 1;
+\&    }
+.Ve
+.PP
+We assume the strings \fBrequest1_start\fR and \fBrequest2_start\fR hold the
+appropriate HTTP requests. We can then call our helper function above to send
+the requests on the two streams. For the sake of simplicity this example does
+this sequentially, writing to \fBstream1\fR first and, when this is successful,
+writing to \fBstream2\fR second. Remember that our client is blocking so these
+calls will only return once they have been successfully completed. A real
+application would not need to do these writes sequentially or in any particular
+order. For example we could start two threads (one for each stream) and write
+the requests to each stream simultaneously.
+.PP
+.Vb 5
+\&    /* Write an HTTP GET request on each of our streams to the peer */
+\&    if (!write_a_request(stream1, request1_start, hostname)) {
+\&        printf("Failed to write HTTP request on stream 1\en");
+\&        goto end;
+\&    }
+\&
+\&    if (!write_a_request(stream2, request2_start, hostname)) {
+\&        printf("Failed to write HTTP request on stream 2\en");
+\&        goto end;
+\&    }
+.Ve
+.SS "Reading data from a stream"
+.IX Subsection "Reading data from a stream"
+In this example \fBstream1\fR is a bi-directional stream so, once we have sent the
+request on it, we can attempt to read the response from the server back. Here
+we just repeatedly call \fBSSL_read_ex\fR\|(3) until that function fails (indicating
+either that there has been a problem, or that the peer has signalled the stream
+as concluded).
+.PP
+.Vb 10
+\&    printf("Stream 1 data:\en");
+\&    /*
+\&     * Get up to sizeof(buf) bytes of the response from stream 1 (which is a
+\&     * bidirectional stream). We keep reading until the server closes the
+\&     * connection.
+\&     */
+\&    while (SSL_read_ex(stream1, buf, sizeof(buf), &readbytes)) {
+\&        /*
+\&        * OpenSSL does not guarantee that the returned data is a string or
+\&        * that it is NUL terminated so we use fwrite() to write the exact
+\&        * number of bytes that we read. The data could be non\-printable or
+\&        * have NUL characters in the middle of it. For this simple example
+\&        * we\*(Aqre going to print it to stdout anyway.
+\&        */
+\&        fwrite(buf, 1, readbytes, stdout);
+\&    }
+\&    /* In case the response didn\*(Aqt finish with a newline we add one now */
+\&    printf("\en");
+.Ve
+.PP
+In a blocking application like this one calls to \fBSSL_read_ex\fR\|(3) will either
+succeed immediately returning data that is already available, or they will block
+waiting for more data to become available and return it when it is, or they will
+fail with a 0 response code.
+.PP
+Once we exit the while loop above we know that the last call to
+\&\fBSSL_read_ex\fR\|(3) gave a 0 response code so we call the \fBSSL_get_error\fR\|(3)
+function to find out more details. Since this is a blocking application this
+will either return \fBSSL_ERROR_SYSCALL\fR or \fBSSL_ERROR_SSL\fR indicating a
+fundamental problem, or it will return \fBSSL_ERROR_ZERO_RETURN\fR indicating that
+the stream is concluded and there will be no more data available to read from
+it. Care must be taken to distinguish between an error at the stream level (i.e.
+a stream reset) and an error at the connection level (i.e. a connection closed).
+The \fBSSL_get_stream_read_state\fR\|(3) function can be used to distinguish between
+these different cases.
+.PP
+.Vb 12
+\&    /*
+\&     * Check whether we finished the while loop above normally or as the
+\&     * result of an error. The 0 argument to SSL_get_error() is the return
+\&     * code we received from the SSL_read_ex() call. It must be 0 in order
+\&     * to get here. Normal completion is indicated by SSL_ERROR_ZERO_RETURN. In
+\&     * QUIC terms this means that the peer has sent FIN on the stream to
+\&     * indicate that no further data will be sent.
+\&     */
+\&    switch (SSL_get_error(stream1, 0)) {
+\&    case SSL_ERROR_ZERO_RETURN:
+\&        /* Normal completion of the stream */
+\&        break;
+\&
+\&    case SSL_ERROR_SSL:
+\&        /*
+\&         * Some stream fatal error occurred. This could be because of a stream
+\&         * reset \- or some failure occurred on the underlying connection.
+\&         */
+\&        switch (SSL_get_stream_read_state(stream1)) {
+\&        case SSL_STREAM_STATE_RESET_REMOTE:
+\&            printf("Stream reset occurred\en");
+\&            /* The stream has been reset but the connection is still healthy. */
+\&            break;
+\&
+\&        case SSL_STREAM_STATE_CONN_CLOSED:
+\&            printf("Connection closed\en");
+\&            /* Connection is already closed. Skip SSL_shutdown() */
+\&            goto end;
+\&
+\&        default:
+\&            printf("Unknown stream failure\en");
+\&            break;
+\&        }
+\&        break;
+\&
+\&    default:
+\&        /* Some other unexpected error occurred */
+\&        printf ("Failed reading remaining data\en");
+\&        break;
+\&    }
+.Ve
+.SS "Accepting an incoming stream"
+.IX Subsection "Accepting an incoming stream"
+Our \fBstream2\fR object that we created above was a uni-directional stream so it
+cannot be used to receive data from the server. In this hypothetical example
+we assume that the server initiates a new stream to send us back the data that
+we requested. To do that we call \fBSSL_accept_stream\fR\|(3). Since this is a
+blocking application this will wait indefinitely until the new stream has
+arrived and is available for us to accept. In the event of an error it will
+return \fBNULL\fR.
+.PP
+.Vb 10
+\&    /*
+\&     * In our hypothetical HTTP/1.0 over QUIC protocol that we are using we
+\&     * assume that the server will respond with a server initiated stream
+\&     * containing the data requested in our uni\-directional stream. This doesn\*(Aqt
+\&     * really make sense to do in a real protocol, but its just for
+\&     * demonstration purposes.
+\&     *
+\&     * We\*(Aqre using blocking mode so this will block until a stream becomes
+\&     * available. We could override this behaviour if we wanted to by setting
+\&     * the SSL_ACCEPT_STREAM_NO_BLOCK flag in the second argument below.
+\&     */
+\&    stream3 = SSL_accept_stream(ssl, 0);
+\&    if (stream3 == NULL) {
+\&        printf("Failed to accept a new stream\en");
+\&        goto end;
+\&    }
+.Ve
+.PP
+We can now read data from the stream in the same way that we did for \fBstream1\fR
+above. We won't repeat that here.
+.SS "Cleaning up the streams"
+.IX Subsection "Cleaning up the streams"
+Once we have finished using our streams we can simply free them by calling
+\&\fBSSL_free\fR\|(3). Optionally we could call \fBSSL_stream_conclude\fR\|(3) on them if
+we want to indicate to the peer that we won't be sending them any more data, but
+we don't do that in this example because we assume that the HTTP application
+protocol supplies sufficient information for the peer to know when we have
+finished sending request data.
+.PP
+We should not call \fBSSL_shutdown\fR\|(3) or \fBSSL_shutdown_ex\fR\|(3) on the stream
+objects since those calls should not be used for streams.
+.PP
+.Vb 3
+\&    SSL_free(stream1);
+\&    SSL_free(stream2);
+\&    SSL_free(stream3);
+.Ve
+.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\-quic\-introduction\fR\|(7),
+\&\fBossl\-guide\-quic\-client\-block\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>.