SSL_NEW_STREAM(3ossl)

💖 SSL_NEW_STREAM 💖

okay bestie, so this is a page from the OpenSSL manual — SSL_NEW_STREAM(3ossl) — and it's all about making a brand new QUIC stream that you start. no cap, it's giving "let me open a little doorway of my own" energy. 🦋

---

✨ 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 🌸

so the whole vibe of SSL_new_stream() is: you hand it a QUIC connection SSL object, and it makes you a fresh, locally-initiated QUIC stream — either bidirectional or unidirectional — and then it hands you back the shiny new QUIC stream SSL object. icon behavior, truly. ✨

if you pass the SSL_STREAM_FLAG_UNI flag, you get a unidirectional stream; otherwise you get a bidirectional one. pick your fighter. 🫶

wanna know the stream ID of the lil baby stream you just made? that's SSL_get_stream_id(3), go get it. 🔥

⚠️ heads up: 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 has to exceed that of the QUIC stream SSL object — meaning the QUIC stream SSL object must be freed first. the connection is the parent, the stream is the child, and the child does NOT outlive the parent. periodt. 💀

once a stream has been created with SSL_new_stream(), you can just use it the normal way with SSL_read(3) and SSL_write(3). nothing weird, nothing extra. 😌

also: this function can only be used to create stream objects for locally-initiated streams. if you're trying to accept incoming streams that the peer started, that's a whole different function — use SSL_accept_stream(3) instead. don't mix them up bestie, that's not the move. 🙈

and here's a sneaky lil detail: calling SSL_new_stream() when there's no default stream already present inhibits the future creation of a default stream. see openssl-quic(7) for the lore. 🧚

now, the creation of new streams is subject to flow control by the QUIC protocol — yeah, the protocol is the one holding the clipboard. so if it's currently not possible to create a new locally-initiated stream of the type you asked for, then 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 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)). and it may also be used in nonblocking mode on a connection that's configured in blocking mode — you just do that by passing the SSL_STREAM_FLAG_NO_BLOCK flag. sneaky but valid. 💅

then there's SSL_STREAM_FLAG_ADVANCE, which lets you 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 up the write buffer of the stream by calling SSL_write(3). BUT — and this is a big but — 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. 🌈

💀 and listen: there is no guarantee the stream will be eventually created. like, 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. no promises, no refunds, main character energy with zero accountability fr fr.

---

👑 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 vibe. 🙅

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. in that 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 you hit this error, the operation may be retried. and the recommendation is: prior to retry, clear the error stack via a call to ERR_clear_error(), and 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. basically: wipe the slate, poke the state machine, try again. slay. ✨

---

💜 SEE ALSO 💜

• SSL_accept_stream(3)
• SSL_free(3)

---

⭐ HISTORY ⭐

SSL_new_stream() was added in OpenSSL 3.2. she's new-ish and she's thriving. 🎀

---

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

---

and that's the whole page bestie 💖 this was 3.5.9, dated 2026-09-29, and it lives at SSL_NEW_STREAM(3ossl) — go forth and stream responsibly, mwah 🫶🌸