Merging upstream version 4.23.0.

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

1 files changed, 435 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man7/ossl-guide-tls-client-non-block.7ssl b/upstream/debian-unstable/man7/ossl-guide-tls-client-non-block.7ssl
new file mode 100644
index 00000000..507feb6d
--- /dev/null
+++ b/upstream/debian-unstable/man7/ossl-guide-tls-client-non-block.7ssl
@@ -0,0 +1,435 @@
+.\" -*- 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-TLS-CLIENT-NON-BLOCK 7SSL"
+.TH OSSL-GUIDE-TLS-CLIENT-NON-BLOCK 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\-tls\-client\-non\-block
+\&\- OpenSSL Guide: Writing a simple nonblocking TLS client
+.SH "SIMPLE NONBLOCKING TLS CLIENT EXAMPLE"
+.IX Header "SIMPLE NONBLOCKING TLS CLIENT EXAMPLE"
+This page will build on the example developed on the
+\&\fBossl\-guide\-tls\-client\-block\fR\|(7) page which demonstrates how to write a simple
+blocking TLS client. On this page we will amend that demo code so that it
+supports a nonblocking socket.
+.PP
+The complete source code for this example nonblocking TLS client is available
+in the \fBdemos/guide\fR directory of the OpenSSL source distribution in the file
+\&\fBtls\-client\-non\-block.c\fR. It is also available online at
+<https://github.com/openssl/openssl/blob/master/demos/guide/tls\-client\-non\-block.c>.
+.PP
+As we saw in the previous example a blocking socket is one which waits (blocks)
+until data is available to read if you attempt to read from it when there is no
+data yet. Similarly it waits when writing if the socket is currently unable to
+write at the moment. This can simplify the development of code because you do
+not have to worry about what to do in these cases. The execution of the code
+will simply stop until it is able to continue. However in many cases you do not
+want this behaviour. Rather than stopping and waiting your application may need
+to go and do other tasks whilst the socket is unable to read/write, for example
+updating a GUI or performing operations on some other socket.
+.PP
+With a nonblocking socket attempting to read or write to a socket that is
+currently unable to read or write will return immediately with a non-fatal
+error. Although OpenSSL does the reading/writing to the socket this nonblocking
+behaviour is propagated up to the application so that OpenSSL I/O functions such
+as \fBSSL_read_ex\fR\|(3) or \fBSSL_write_ex\fR\|(3) will not block.
+.PP
+Since this page is building on the example developed on the
+\&\fBossl\-guide\-tls\-client\-block\fR\|(7) page we assume that you are familiar with it
+and we only explain how this example differs.
+.SS "Setting the socket to be nonblocking"
+.IX Subsection "Setting the socket to be nonblocking"
+The first step in writing an application that supports nonblocking is to set
+the socket into nonblocking mode. A socket will be default be blocking. The
+exact details on how to do this can differ from one platform to another.
+Fortunately OpenSSL offers a portable function that will do this for you:
+.PP
+.Vb 5
+\&    /* Set to nonblocking mode */
+\&    if (!BIO_socket_nbio(sock, 1)) {
+\&        sock = \-1;
+\&        continue;
+\&    }
+.Ve
+.PP
+You do not have to use OpenSSL's function for this. You can of course directly
+call whatever functions that your Operating System provides for this purpose on
+your platform.
+.SS "Performing work while waiting for the socket"
+.IX Subsection "Performing work while waiting for the socket"
+In a nonblocking application you will need work to perform in the event that
+we want to read or write to the socket, but we are currently unable to. In fact
+this is the whole point of using a nonblocking socket, i.e. to give the
+application the opportunity to do something else. Whatever it is that the
+application has to do, it must also be prepared to come back and retry the
+operation that it previously attempted periodically to see if it can now
+complete. Ideally it would only do this in the event that the state of the
+underlying socket has actually changed (e.g. become readable where it wasn't
+before), but this does not have to be the case. It can retry at any time.
+.PP
+Note that it is important that you retry exactly the same operation that you
+tried last time. You cannot start something new. For example if you were
+attempting to write the text "Hello World" and the operation failed because the
+socket is currently unable to write, then you cannot then attempt to write
+some other text when you retry the operation.
+.PP
+In this demo application we will create a helper function which simulates doing
+other work. In fact, for the sake of simplicity, it will do nothing except wait
+for the state of the socket to change.
+.PP
+We call our function \f(CWwait_for_activity()\fR because all it does is wait until
+the underlying socket has become readable or writeable when it wasn't before.
+.PP
+.Vb 4
+\&    static void wait_for_activity(SSL *ssl, int write)
+\&    {
+\&        fd_set fds;
+\&        int width, sock;
+\&
+\&        /* Get hold of the underlying file descriptor for the socket */
+\&        sock = SSL_get_fd(ssl);
+\&
+\&        FD_ZERO(&fds);
+\&        FD_SET(sock, &fds);
+\&        width = sock + 1;
+\&
+\&        /*
+\&         * Wait until the socket is writeable or readable. We use select here
+\&         * for the sake of simplicity and portability, but you could equally use
+\&         * poll/epoll or similar functions
+\&         *
+\&         * NOTE: For the purposes of this demonstration code this effectively
+\&         * makes this demo block until it has something more useful to do. In a
+\&         * real application you probably want to go and do other work here (e.g.
+\&         * update a GUI, or service other connections).
+\&         *
+\&         * Let\*(Aqs say for example that you want to update the progress counter on
+\&         * a GUI every 100ms. One way to do that would be to add a 100ms timeout
+\&         * in the last parameter to "select" below. Then, when select returns,
+\&         * you check if it did so because of activity on the file descriptors or
+\&         * because of the timeout. If it is due to the timeout then update the
+\&         * GUI and then restart the "select".
+\&         */
+\&        if (write)
+\&            select(width, NULL, &fds, NULL, NULL);
+\&        else
+\&            select(width, &fds, NULL, NULL, NULL);
+\&    }
+.Ve
+.PP
+In this example we are using the \f(CW\*(C`select\*(C'\fR function because it is very simple
+to use and is available on most Operating Systems. However you could use any
+other similar function to do the same thing. \f(CW\*(C`select\*(C'\fR waits for the state of
+the underlying socket(s) to become readable/writeable before returning. It also
+supports a "timeout" (as do most other similar functions) so in your own
+applications you can make use of this to periodically wake up and perform work
+while waiting for the socket state to change. But we don't use that timeout
+capability in this example for the sake of simplicity.
+.SS "Handling errors from OpenSSL I/O functions"
+.IX Subsection "Handling errors from OpenSSL I/O functions"
+An application that uses a nonblocking socket will need to be prepared to
+handle errors returned from OpenSSL I/O functions such as \fBSSL_read_ex\fR\|(3) or
+\&\fBSSL_write_ex\fR\|(3). Errors may be fatal (for example because the underlying
+connection has failed), or non-fatal (for example because we are trying to read
+from the underlying socket but the data has not yet arrived from the peer).
+.PP
+\&\fBSSL_read_ex\fR\|(3) and \fBSSL_write_ex\fR\|(3) will return 0 to indicate an error and
+\&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) will return 0 or a negative value to indicate
+an error. \fBSSL_shutdown\fR\|(3) will return a negative value to incidate an error.
+.PP
+In the event of an error an application should call \fBSSL_get_error\fR\|(3) to find
+out what type of error has occurred. If the error is non-fatal and can be
+retried then \fBSSL_get_error\fR\|(3) will return \fBSSL_ERROR_WANT_READ\fR or
+\&\fBSSL_ERROR_WANT_WRITE\fR depending on whether OpenSSL wanted to read to or write
+from the socket but was unable to. Note that a call to \fBSSL_read_ex\fR\|(3) or
+\&\fBSSL_read\fR\|(3) can still generate \fBSSL_ERROR_WANT_WRITE\fR because OpenSSL
+may need to write protocol messages (such as to update cryptographic keys) even
+if the application is only trying to read data. Similarly calls to
+\&\fBSSL_write_ex\fR\|(3) or \fBSSL_write\fR\|(3) might generate \fBSSL_ERROR_WANT_READ\fR.
+.PP
+Another type of non-fatal error that may occur is \fBSSL_ERROR_ZERO_RETURN\fR. This
+indicates an EOF (End-Of-File) which can occur if you attempt to read data from
+an \fBSSL\fR object but the peer has indicated that it will not send any more data
+on it. In this case you may still want to write data to the connection but you
+will not receive any more data.
+.PP
+Fatal errors that may occur are \fBSSL_ERROR_SYSCALL\fR and \fBSSL_ERROR_SSL\fR. These
+indicate that the underlying connection has failed. You should not attempt to
+shut it down with \fBSSL_shutdown\fR\|(3). \fBSSL_ERROR_SYSCALL\fR indicates that
+OpenSSL attempted to make a syscall that failed. You can consult \fBerrno\fR for
+further details. \fBSSL_ERROR_SSL\fR indicates that some OpenSSL error occurred. You
+can consult the OpenSSL error stack for further details (for example by calling
+\&\fBERR_print_errors\fR\|(3) to print out details of errors that have occurred).
+.PP
+In our demo application we will write a function to handle these errors from
+OpenSSL I/O functions:
+.PP
+.Vb 7
+\&    static int handle_io_failure(SSL *ssl, int res)
+\&    {
+\&        switch (SSL_get_error(ssl, res)) {
+\&        case SSL_ERROR_WANT_READ:
+\&            /* Temporary failure. Wait until we can read and try again */
+\&            wait_for_activity(ssl, 0);
+\&            return 1;
+\&
+\&        case SSL_ERROR_WANT_WRITE:
+\&            /* Temporary failure. Wait until we can write and try again */
+\&            wait_for_activity(ssl, 1);
+\&            return 1;
+\&
+\&        case SSL_ERROR_ZERO_RETURN:
+\&            /* EOF */
+\&            return 0;
+\&
+\&        case SSL_ERROR_SYSCALL:
+\&            return \-1;
+\&
+\&        case SSL_ERROR_SSL:
+\&            /*
+\&            * If the failure is due to a verification error we can get more
+\&            * information about it from SSL_get_verify_result().
+\&            */
+\&            if (SSL_get_verify_result(ssl) != X509_V_OK)
+\&                printf("Verify error: %s\en",
+\&                    X509_verify_cert_error_string(SSL_get_verify_result(ssl)));
+\&            return \-1;
+\&
+\&        default:
+\&            return \-1;
+\&        }
+\&    }
+.Ve
+.PP
+This function takes as arguments the \fBSSL\fR object that represents the
+connection, as well as the return code from the I/O function that failed. In
+the event of a non-fatal failure, it waits until a retry of the I/O operation
+might succeed (by using the \f(CWwait_for_activity()\fR function that we developed
+in the previous section). It returns 1 in the event of a non-fatal error
+(except EOF), 0 in the event of EOF, or \-1 if a fatal error occurred.
+.SS "Creating the SSL_CTX and SSL objects"
+.IX Subsection "Creating the SSL_CTX and SSL objects"
+In order to connect to a server we must create \fBSSL_CTX\fR and \fBSSL\fR objects for
+this. The steps do this are the same as for a blocking client and are explained
+on the \fBossl\-guide\-tls\-client\-block\fR\|(7) page. We won't repeat that information
+here.
+.SS "Performing the handshake"
+.IX Subsection "Performing the handshake"
+As in the demo for a blocking TLS client we use the \fBSSL_connect\fR\|(3) function
+to perform the TLS handshake with the server. Since we are using a nonblocking
+socket it is very likely that calls to this function will fail with a non-fatal
+error while we are waiting for the server to respond to our handshake messages.
+In such a case we must retry the same \fBSSL_connect\fR\|(3) call at a later time.
+In this demo we this in a loop:
+.PP
+.Vb 7
+\&    /* Do the handshake with the server */
+\&    while ((ret = SSL_connect(ssl)) != 1) {
+\&        if (handle_io_failure(ssl, ret) == 1)
+\&            continue; /* Retry */
+\&        printf("Failed to connect to server\en");
+\&        goto end; /* Cannot retry: error */
+\&    }
+.Ve
+.PP
+We continually call \fBSSL_connect\fR\|(3) until it gives us a success response.
+Otherwise we use the \f(CWhandle_io_failure()\fR function that we created earlier to
+work out what we should do next. Note that we do not expect an EOF to occur at
+this stage, so such a response is treated in the same way as a fatal error.
+.SS "Sending and receiving data"
+.IX Subsection "Sending and receiving data"
+As with the blocking TLS client demo we use the \fBSSL_write_ex\fR\|(3) function to
+send data to the server. As with \fBSSL_connect\fR\|(3) above, because we are using
+a nonblocking socket, this call could fail with a non-fatal error. In that case
+we should retry exactly the same \fBSSL_write_ex\fR\|(3) call again. Note that the
+parameters must be \fIexactly\fR the same, i.e. the same pointer to the buffer to
+write with the same length. You must not attempt to send different data on a
+retry. An optional mode does exist (\fBSSL_MODE_ACCEPT_MOVING_WRITE_BUFFER\fR)
+which will configure OpenSSL to allow the buffer being written to change from
+one retry to the next. However, in this case, you must still retry exactly the
+same data \- even though the buffer that contains that data may change location.
+See \fBSSL_CTX_set_mode\fR\|(3) for further details. As in the TLS client
+blocking tutorial (\fBossl\-guide\-tls\-client\-block\fR\|(7)) we write the request
+in three chunks.
+.PP
+.Vb 10
+\&    /* Write an HTTP GET request to the peer */
+\&    while (!SSL_write_ex(ssl, request_start, strlen(request_start), &written)) {
+\&        if (handle_io_failure(ssl, 0) == 1)
+\&            continue; /* Retry */
+\&        printf("Failed to write start of HTTP request\en");
+\&        goto end; /* Cannot retry: error */
+\&    }
+\&    while (!SSL_write_ex(ssl, hostname, strlen(hostname), &written)) {
+\&        if (handle_io_failure(ssl, 0) == 1)
+\&            continue; /* Retry */
+\&        printf("Failed to write hostname in HTTP request\en");
+\&        goto end; /* Cannot retry: error */
+\&    }
+\&    while (!SSL_write_ex(ssl, request_end, strlen(request_end), &written)) {
+\&        if (handle_io_failure(ssl, 0) == 1)
+\&            continue; /* Retry */
+\&        printf("Failed to write end of HTTP request\en");
+\&        goto end; /* Cannot retry: error */
+\&    }
+.Ve
+.PP
+On a write we do not expect to see an EOF response so we treat that case in the
+same way as a fatal error.
+.PP
+Reading a response back from the server is similar:
+.PP
+.Vb 10
+\&    do {
+\&        /*
+\&         * Get up to sizeof(buf) bytes of the response. We keep reading until
+\&         * the server closes the connection.
+\&         */
+\&        while (!eof && !SSL_read_ex(ssl, buf, sizeof(buf), &readbytes)) {
+\&            switch (handle_io_failure(ssl, 0)) {
+\&            case 1:
+\&                continue; /* Retry */
+\&            case 0:
+\&                eof = 1;
+\&                continue;
+\&            case \-1:
+\&            default:
+\&                printf("Failed reading remaining data\en");
+\&                goto end; /* Cannot retry: error */
+\&            }
+\&        }
+\&        /*
+\&         * 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.
+\&         */
+\&        if (!eof)
+\&            fwrite(buf, 1, readbytes, stdout);
+\&    } while (!eof);
+\&    /* In case the response didn\*(Aqt finish with a newline we add one now */
+\&    printf("\en");
+.Ve
+.PP
+The main difference this time is that it is valid for us to receive an EOF
+response when trying to read data from the server. This will occur when the
+server closes down the connection after sending all the data in its response.
+.PP
+In this demo we just print out all the data we've received back in the response
+from the server. We continue going around the loop until we either encounter a
+fatal error, or we receive an EOF (indicating a graceful finish).
+.SS "Shutting down the connection"
+.IX Subsection "Shutting down the connection"
+As in the TLS blocking example we must shutdown the connection when we are
+finished with it.
+.PP
+If our application was initiating the shutdown then we would expect to see
+\&\fBSSL_shutdown\fR\|(3) give a return value of 0, and then we would continue to call
+it until we received a return value of 1 (meaning we have successfully completed
+the shutdown). In this particular example we don't expect \fBSSL_shutdown()\fR to
+return 0 because we have already received EOF from the server indicating that it
+has shutdown already. So we just keep calling it until \fBSSL_shutdown()\fR returns 1.
+Since we are using a nonblocking socket we might expect to have to retry this
+operation several times. If \fBSSL_shutdown\fR\|(3) returns a negative result then we
+must call \fBSSL_get_error\fR\|(3) to work out what to do next. We use our
+\&\fBhandle_io_failure()\fR function that we developed earlier for this:
+.PP
+.Vb 10
+\&    /*
+\&     * The peer already shutdown gracefully (we know this because of the
+\&     * SSL_ERROR_ZERO_RETURN (i.e. EOF) above). We should do the same back.
+\&     */
+\&    while ((ret = SSL_shutdown(ssl)) != 1) {
+\&        if (ret < 0 && handle_io_failure(ssl, ret) == 1)
+\&            continue; /* Retry */
+\&        /*
+\&         * ret == 0 is unexpected here because that means "we\*(Aqve sent a
+\&         * close_notify and we\*(Aqre waiting for one back". But we already know
+\&         * we got one from the peer because of the SSL_ERROR_ZERO_RETURN
+\&         * (i.e. EOF) above.
+\&         */
+\&        printf("Error shutting down\en");
+\&        goto end; /* Cannot retry: error */
+\&    }
+.Ve
+.SS "Final clean up"
+.IX Subsection "Final clean up"
+As with the blocking TLS client example, once our connection is finished with we
+must free it. The steps to do this for this example are the same as for the
+blocking example, so we won't repeat it here.
+.SH "FURTHER READING"
+.IX Header "FURTHER READING"
+See \fBossl\-guide\-tls\-client\-block\fR\|(7) to read a tutorial on how to write a
+blocking TLS client. See \fBossl\-guide\-quic\-client\-block\fR\|(7) to see how to do the
+same thing for a 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)
+.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>.