SSL_SET_DEFAULT_STREAM_MODE(3ossl) OpenSSL SSL_SET_DEFAULT_STREAM_MODE(3ossl)
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
SYNOPSIS
#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);
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 SSL_read(3) and
SSL_write(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.
When not disabled, a default stream is automatically created on an
outgoing connection once SSL_read(3) or SSL_write(3) is called.
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 SSL_read(3) is called first
(before any call to SSL_write(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
SSL_write(3) is called before any call to SSL_read(3), OpenSSL assumes
the client wishes to transmit first, creates a client-initiated stream,
and binds this as the default stream.
By default, the default stream created is bidirectional. If a
unidirectional stream is desired, or if the application wishes to
disable default stream functionality, SSL_set_default_stream_mode(3)
(discussed below) can be used to accomplish this.
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, SSL_read(3) and SSL_write(3)) will
fail.
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.
SSL_set_default_stream_mode(3) 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 SSL_new(3), prior to
initiating a connection. The argument mode may be one of the following
options:
SSL_DEFAULT_STREAM_MODE_AUTO_BIDI
This is the default setting. If SSL_write(3) is called prior to any
call to SSL_read(3), a bidirectional client-initiated stream is
created and bound as the default stream. If SSL_read(3) is called
prior to any call to SSL_write(3), OpenSSL waits for an incoming
stream from the peer (causing SSL_read(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 SSL_read(3)
is called first. To determine the type of a stream after a call to
SSL_read(3), use SSL_get_stream_type(3).
SSL_DEFAULT_STREAM_MODE_AUTO_UNI
In this mode, if SSL_write(3) is called prior to any call to
SSL_read(3), a unidirectional client-initiated stream is created
and bound as the default stream. The behaviour is otherwise
identical to that of SSL_DEFAULT_STREAM_MODE_AUTO_BIDI. The
behaviour when SSL_read(3) is called prior to any call to
SSL_write(3) is unchanged.
SSL_DEFAULT_STREAM_MODE_NONE
Default stream creation is inhibited. This is the recommended mode
of operation. SSL_read(3) and SSL_write(3) calls cannot be made on
the QUIC connection SSL object directly. You must obtain streams
using SSL_new_stream(3) or SSL_accept_stream(3) in order to
communicate with the peer.
A default stream will not be automatically created on a QUIC connection
SSL object if the default stream mode is set to
SSL_DEFAULT_STREAM_MODE_NONE.
SSL_set_incoming_stream_policy(3) interacts significantly with the
default stream functionality.
RETURN VALUES
SSL_set_default_stream_mode(3) returns 1 on success and 0 on failure.
SSL_set_default_stream_mode(3) fails if it is called after a default
stream has already been established.
These functions fail if called on a QUIC stream SSL object or on a
non-QUIC SSL object.
SEE ALSO
SSL_new_stream(3), SSL_accept_stream(3), SSL_free(3),
SSL_set_incoming_stream_policy(3)
HISTORY
These functions were added in OpenSSL 3.2.
COPYRIGHT
Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
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>.
3.3.2 2024-09-04
SSL_SET_DEFAULT_STREAM_MODE(3ossl)
openssl 3.3.2 - Generated Tue Sep 24 18:33:31 CDT 2024