SSL_NEW_STREAM(3SSL)

📦
version 4.0.3 · 6 versions
, in ubuntu stonking

💖 SSL_NEW_STREAM 💖 — like, the OpenSSL 3SSL manual, but make it make sense

okay so bestie, welcome to the SSL_new_stream(3SSL) page 💅 this one's all about spinning up a brand-new locally-initiated QUIC stream, and honestly? it's giving main character energy. stay with me, it's not even hard.

✨ 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);

like, that's the whole vibe. three little flags and one function. slay. 🎀

✨ DESCRIPTION ✨

so SSL_new_stream() — when you hand it a QUIC connection SSL object — creates a shiny new locally-initiated bidirectional or unidirectional QUIC stream and gives you back the freshly-made QUIC stream SSL object. new stream, who dis. 🌸

if you pass the SSL_STREAM_FLAG_UNI flag, congrats, it's a unidirectional stream 💫 otherwise? bidirectional, no cap.

wanna know the stream ID of the new baby stream? go grab it with SSL_get_stream_id(3).

lowkey important: it is the caller's responsibility to free the QUIC stream SSL object using SSL_free(3). and 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 has to be freed first. connection outlives stream, always. don't be the one who frees it backwards 😭

once a stream exists thanks to SSL_new_stream(), you just use it the normal way with SSL_read(3) and SSL_write(3). that's it, that's the tea.

oh and heads up: this function can only create stream objects for locally-initiated streams. if a peer opens a stream at you and you wanna accept it, that's SSL_accept_stream(3). different function, different vibe.

also also — calling SSL_new_stream() when there's no default stream already present inhibits the future creation of a default stream. yes, really. check openssl-quic(7) for the details, iykyk. 🧚

now the flow control bit, because QUIC said "actually no":

creating new streams is subject to flow control by the QUIC protocol. so if it's currently impossible to create a new locally-initiated stream of the type you asked for, a call to SSL_new_stream() will either:

  • block (if the connection is configured in blocking mode) until a new stream can be created, or
  • otherwise just return NULL. 💀

this function operates in blocking mode if the QUIC connection SSL object is configured in blocking mode (peep SSL_set_blocking_mode(3)). you can also use it in nonblocking mode on a connection that's configured in blocking mode — just pass the flag SSL_STREAM_FLAG_NO_BLOCK. flexible, iconic. 👑

and then there's SSL_STREAM_FLAG_ADVANCE, which is the "manifest it anyway" flag ✨ it may be used to create a QUIC stream SSL object even if a new QUIC stream cannot yet be opened because of flow control. the caller can start using the new stream and fill its write buffer by calling SSL_write(3). however — and this is the part where we all need to breathe — 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.

bestie, listen: 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. so like... hope for the best, but don't build your whole personality on it 🙈

✨ RETURN VALUES ✨

SSL_new_stream() returns a new stream object, or NULL on error.

it fails if you call it on a QUIC stream SSL object or on a non-QUIC SSL object. (wrong object, wrong function, know the difference fr fr.)

SSL_new_stream() 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. when that happens, that NULL return comes with an error on the error stack (grab it via ERR_get_error()), and it'll contain a reason code of SSL_R_STREAM_COUNT_LIMITED. 💅

good news though — when you hit this error, the operation may be retried. and the recommended glow-up before you retry is:

  1. clear the error stack via a call to ERR_clear_error(), and
  2. activate the TLS state machine via a call to SSL_handle_events() to process any potential updates from the server allowing additional streams to be created.

do those two and try again. periodt. 🔥

✨ SEE ALSO ✨

✨ HISTORY ✨

SSL_new_stream() was added in OpenSSL 3.2. so it's not ancient, it's just ✨established✨.

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>.

okay that's the whole page bestie, you ate it 🫶 this was SSL_NEW_STREAM(3SSL) from OpenSSL 4.0.3, dated 2026-09-29 — go make some streams, ily, bye! 💜🎀🦋

📦 where this page comes from