SSL_NEW_STREAM(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 SSL_NEW_STREAM(3ossl) — the OpenSSL glow-up

okay so bestie, this is the SSL_NEW_STREAM(3ossl) page from the OpenSSL manual, and it's literally about making brand-new locally-initiated QUIC streams. yes. we're doing QUIC today. sit down, hydrate, let's go 🫶

✨ 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 it. that's the whole vibe. three flags and one function 🔥

🦋 DESCRIPTION 🦋

So SSL_new_stream() — when you pass it a QUIC connection SSL object — creates a new locally-initiated bidirectional or unidirectional QUIC stream, and hands you back the shiny new QUIC stream SSL object. main character energy, honestly 👑

  • The uni/bidi situation — if you pass the SSL_STREAM_FLAG_UNI flag, you get a unidirectional stream. no flag? you get a bidirectional stream. simple as that 💅
  • want the stream ID? use SSL_get_stream_id(3) to retrieve the stream ID of the newly created stream. iykyk ✨
⚠️ ok important one: it's the caller's job 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. no cap, don't get this backwards or it's giving undefined behavior 😭

Once a stream has been created with SSL_new_stream(), you can use it in the normal way with SSL_read(3) and SSL_write(3). business as usual, bestie 🎀

heads up though: this function can only be used to create stream objects for locally-initiated streams. to accept incoming streams that a peer initiated, you want SSL_accept_stream(3) instead. different tool, different job 🧚

Also — calling SSL_new_stream() when there's no default stream already present inhibits the future creation of a default stream. fr fr. see openssl-quic(7) for the whole story 🌈

🌀 flow control vibes

The creation of new streams is subject to flow control by the QUIC protocol. so if it's currently not possible to create a new locally-initiated stream of the specified type, 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 💀

🔀 blocking / nonblocking tea

This function operates in blocking mode if the QUIC connection SSL object is configured in blocking mode (see SSL_set_blocking_mode(3)). It can also be used in nonblocking mode on a connection that's configured in blocking mode — just pass the SSL_STREAM_FLAG_NO_BLOCK flag. obsessed with the flexibility honestly 💖

🚀 the SSL_STREAM_FLAG_ADVANCE flag

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. like, manifesting a stream before the universe allows it ✨

What happens then:

  • 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
😭 and 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 know the risks 💀

👑 RETURN VALUES 👑

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

This function fails if you call it on a QUIC stream SSL object, or on a non-QUIC SSL object. wrong object, wrong function, we've all been there 🙈

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 this error is encountered, the operation may be retried. The recommended glow-up ritual before retry is:

  1. clear the error stack via a call to ERR_clear_error()
  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

that's the whole retry routine. slay, go again 💜

💫 SEE ALSO 💫

⭐ HISTORY ⭐

SSL_new_stream() was added in OpenSSL 3.2. a relatively recent icon, honestly 🌟

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, go forth and create streams responsibly 🦋💖

brought to you by OpenSSL 3.5.0, dated 2026-09-25 — stay iconic, bestie 🌈✨

📦 where this page comes from