1 files changed, 173 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man3/SSL_set_default_stream_mode.3 b/secure/lib/libcrypto/man/man3/SSL_set_default_stream_mode.3
new file mode 100644
index 000000000000..c38364baf6c7
--- /dev/null
+++ b/secure/lib/libcrypto/man/man3/SSL_set_default_stream_mode.3
@@ -0,0 +1,173 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
+.\"
+.\" 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_SET_DEFAULT_STREAM_MODE 3ossl"
+.TH SSL_SET_DEFAULT_STREAM_MODE 3ossl 2025-07-01 3.5.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_set_default_stream_mode,
+SSL_DEFAULT_STREAM_MODE_NONE, SSL_DEFAULT_STREAM_MODE_AUTO_BIDI,
+SSL_DEFAULT_STREAM_MODE_AUTO_UNI \- manage the default stream for a QUIC
+connection
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\& #include <openssl/ssl.h>
+\&
+\& #define SSL_DEFAULT_STREAM_MODE_NONE
+\& #define SSL_DEFAULT_STREAM_MODE_AUTO_BIDI
+\& #define SSL_DEFAULT_STREAM_MODE_AUTO_UNI
+\&
+\& int SSL_set_default_stream_mode(SSL *conn, uint32_t mode);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+A QUIC connection SSL object may have a default stream attached to it. A default
+stream is a QUIC stream to which calls to \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3)
+made on a QUIC connection SSL object are redirected. Default stream handling
+allows legacy applications to use QUIC similarly to a traditional TLS
+connection.
+.PP
+When not disabled, a default stream is automatically created on an outgoing
+connection once \fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called.
+.PP
+A QUIC stream must be explicitly designated as client-initiated or
+server-initiated up front. This broadly corresponds to whether an application
+protocol involves the client transmitting first, or the server transmitting
+first. As such, if \fBSSL_read\fR\|(3) is called first (before any call to
+\&\fBSSL_write\fR\|(3))  after establishing a connection, OpenSSL will wait for the
+server to open the first server-initiated stream, and then bind this as the
+default stream. Conversely, if \fBSSL_write\fR\|(3) is called before any call to
+\&\fBSSL_read\fR\|(3), OpenSSL assumes the client wishes to transmit first, creates a
+client-initiated stream, and binds this as the default stream.
+.PP
+By default, the default stream created is bidirectional. If a unidirectional
+stream is desired, or if the application wishes to disable default stream
+functionality, \fBSSL_set_default_stream_mode()\fR (discussed below) can be used to
+accomplish this.
+.PP
+When a QUIC connection SSL object has no default stream currently associated
+with it, for example because default stream functionality was disabled, calls to
+functions which require a stream on the QUIC connection SSL object (for example,
+\&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3)) will fail.
+.PP
+It is recommended that new applications and applications which rely on multiple
+streams forego use of the default stream functionality, which is intended for
+legacy applications.
+.PP
+\&\fBSSL_set_default_stream_mode()\fR can be used to configure or disable default stream
+handling. It can only be called on a QUIC connection SSL object prior to any
+default stream being created. If used, it is recommended to call it immediately
+after calling \fBSSL_new\fR\|(3), prior to initiating a connection. The argument
+\&\fImode\fR may be one of the following options:
+.IP SSL_DEFAULT_STREAM_MODE_AUTO_BIDI 4
+.IX Item "SSL_DEFAULT_STREAM_MODE_AUTO_BIDI"
+This is the default setting. If \fBSSL_write\fR\|(3) is called prior to any call to
+\&\fBSSL_read\fR\|(3), a bidirectional client-initiated stream is created and bound as
+the default stream. If \fBSSL_read\fR\|(3) is called prior to any call to
+\&\fBSSL_write\fR\|(3), OpenSSL waits for an incoming stream from the peer (causing
+\&\fBSSL_read\fR\|(3) to block if the connection is in blocking mode), and then binds
+that stream as the default stream. Note that this incoming stream may be either
+bidirectional or unidirectional; thus, this setting does not guarantee the
+presence of a bidirectional stream when \fBSSL_read\fR\|(3) is called first. To
+determine the type of a stream after a call to \fBSSL_read\fR\|(3), use
+\&\fBSSL_get_stream_type\fR\|(3).
+.IP SSL_DEFAULT_STREAM_MODE_AUTO_UNI 4
+.IX Item "SSL_DEFAULT_STREAM_MODE_AUTO_UNI"
+In this mode, if \fBSSL_write\fR\|(3) is called prior to any call to \fBSSL_read\fR\|(3),
+a unidirectional client-initiated stream is created and bound as the default
+stream. The behaviour is otherwise identical to that of
+\&\fBSSL_DEFAULT_STREAM_MODE_AUTO_BIDI\fR. The behaviour when \fBSSL_read\fR\|(3) is
+called prior to any call to \fBSSL_write\fR\|(3) is unchanged.
+.IP SSL_DEFAULT_STREAM_MODE_NONE 4
+.IX Item "SSL_DEFAULT_STREAM_MODE_NONE"
+Default stream creation is inhibited. This is the recommended mode of operation.
+\&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) calls cannot be made on the QUIC connection
+SSL object directly. You must obtain streams using \fBSSL_new_stream\fR\|(3) or
+\&\fBSSL_accept_stream\fR\|(3) in order to communicate with the peer.
+.PP
+A default stream will not be automatically created on a QUIC connection SSL
+object if the default stream mode is set to \fBSSL_DEFAULT_STREAM_MODE_NONE\fR.
+.PP
+\&\fBSSL_set_incoming_stream_policy\fR\|(3) interacts significantly with the default
+stream functionality.
+.SH "RETURN VALUES"
+.IX Header "RETURN VALUES"
+\&\fBSSL_set_default_stream_mode()\fR returns 1 on success and 0 on failure.
+.PP
+\&\fBSSL_set_default_stream_mode()\fR fails if it is called after a default stream has
+already been established.
+.PP
+These functions fail if called on a QUIC stream SSL object or on a non-QUIC SSL
+object.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBSSL_new_stream\fR\|(3), \fBSSL_accept_stream\fR\|(3), \fBSSL_free\fR\|(3),
+\&\fBSSL_set_incoming_stream_policy\fR\|(3)
+.SH HISTORY
+.IX Header "HISTORY"
+These functions were added in OpenSSL 3.2.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 2002\-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>.