SSL_NEW_STREAM(3ossl) OpenSSL SSL_NEW_STREAM(3ossl)
NAME
SSL_new_stream, SSL_STREAM_FLAG_UNI, SSL_STREAM_FLAG_NO_BLOCK,
SSL_STREAM_FLAG_ADVANCE - create a new locally-initiated QUIC stream
SYNOPSIS
#include <openssl/ssl.h>
#define SSL_STREAM_FLAG_UNI (1U << 0)
#define SSL_STREAM_FLAG_NO_BLOCK (1U << 1)
#define SSL_STREAM_FLAG_ADVANCE (1U << 2)
SSL *SSL_new_stream(SSL *ssl, uint64_t flags);
DESCRIPTION
The SSL_new_stream(3) function, when passed a QUIC connection SSL
object, creates a new locally-initiated bidirectional or unidirectional
QUIC stream and returns the newly created QUIC stream SSL object.
If the SSL_STREAM_FLAG_UNI flag is passed, a unidirectional stream is
created; else a bidirectional stream is created.
To retrieve the stream ID of the newly created stream, use
SSL_get_stream_id(3).
It is the caller's responsibility to free the QUIC stream SSL object
using SSL_free(3). The lifetime of the QUIC connection SSL object must
exceed that of the QUIC stream SSL object; in other words, the QUIC
stream SSL object must be freed first.
Once a stream has been created using SSL_new_stream(3), it may be used
in the normal way using SSL_read(3) and SSL_write(3).
This function can only be used to create stream objects for locally-
initiated streams. To accept incoming streams initiated by a peer, use
SSL_accept_stream(3).
Calling SSL_new_stream(3) if there is no default stream already present
inhibits the future creation of a default stream. See openssl-quic(7).
The creation of new streams is subject to flow control by the QUIC
protocol. If it is currently not possible to create a new locally
initiated stream of the specified type, a call to SSL_new_stream(3) will
either block (if the connection is configured in blocking mode) until a
new stream can be created, or otherwise return NULL.
This function operates in blocking mode if the QUIC connection SSL
object is configured in blocking mode (see SSL_set_blocking_mode(3)).
It may also be used in nonblocking mode on a connection configured in
blocking mode by passing the flag SSL_STREAM_FLAG_NO_BLOCK.
The flag SSL_STREAM_FLAG_ADVANCE may be used to create a QUIC stream
SSL object even if a new QUIC stream cannot yet be opened due to flow
control. The caller may begin to use the new stream and fill the write
buffer of the stream by calling SSL_write(3). However, no actual stream
data (or QUIC frames regarding the stream) will be sent until QUIC flow
control allows it. Any queued data will be sent as soon as a peer
permits it. There is no guarantee the stream will be eventually
created; for example, the connection could fail, or a peer might simply
decide never to increase the number of allowed streams for the
remainder of the connection lifetime.
RETURN VALUES
SSL_new_stream(3) returns a new stream object, or NULL on error.
This function fails if called on a QUIC stream SSL object or on a non-
QUIC SSL object.
SSL_new_stream(3) may also fail if the underlying connection has reached
the maximum stream count, based on the max_streams_bidi or
max_streams_uni transport parameter values negotiated with the peer.
In this event the NULL return will be accompanied by an error on the
error stack (obtainable via ERR_get_error()), which will contain a
reason code of SSL_R_STREAM_COUNT_LIMITED. When this error is
encountered, the operation may be retried. It is recommended that,
prior to retry, the error stack be cleared via a call to
ERR_clear_error(), and that the TLS state machine be activated via a
call to SSL_handle_events() to process any potential updates from the
server allowing additional streams to be created.
SEE ALSO
SSL_accept_stream(3), SSL_free(3)
HISTORY
SSL_new_stream(3) was added in OpenSSL 3.2.
COPYRIGHT
Copyright 2002-2025 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.5.0 2025-04-10 SSL_NEW_STREAM(3ossl)
openssl 3.5.0 - Generated Tue Apr 29 18:25:28 CDT 2025