SSL_SET_DEFAULT_STREAM_MODE(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 SSL_SET_DEFAULT_STREAM_MODE(3ossl) — like, the whole manual but make it make sense

okay so bestie, this is the 3ossl manual page for SSL_set_default_stream_mode and its little mode-constant friends ✨ It's all about managing the default stream for a QUIC connection, and honestly? Once you get it, you get it.

🎀 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

So. A QUIC connection SSL object can have a default stream attached to it. A default stream is literally just a QUIC stream that all your SSL_read(3) and SSL_write(3) calls get redirected to when you make them on a QUIC connection SSL object. It's giving ✨legacy compatibility✨ — default stream handling is what lets old-school apps use QUIC in a way that feels like a traditional TLS connection. Cute, right?

When it's not disabled, a default stream gets automatically created on an outgoing connection the moment you call SSL_read(3) or SSL_write(3). Like, it just shows up. Iconic.

Now here's the thing — a QUIC stream has to be explicitly designated as client-initiated or server-initiated up front. No take-backs. This basically comes down to whether your app protocol has the client transmitting first, or the server transmitting first. So:

  • 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 that as the default stream. 🫶
  • Conversely, if SSL_write(3) is called before any call to SSL_read(3), OpenSSL assumes the client wants to transmit first, creates a client-initiated stream, and binds that as the default stream.

By default, the default stream created is bidirectional. If you want a unidirectional stream, or if you want to disable default stream functionality entirely, you use SSL_set_default_stream_mode() — which we're getting to, don't worry. 💅

⚠️ Heads up: when a QUIC connection SSL object has no default stream currently associated with it — say, because default stream functionality was disabled — then any calls to functions that require a stream on that QUIC connection SSL object (like SSL_read(3) and SSL_write(3)) will fail. Not a vibe. 😭

fr fr, it is recommended that new applications and applications that rely on multiple streams just... forego the default stream functionality altogether. It's intended for legacy applications. New apps, y'all are better than this. 👑

🦋 SSL_set_default_stream_mode()

SSL_set_default_stream_mode() configures or disables default stream handling. Important caveat though: it can only be called on a QUIC connection SSL object prior to any default stream being created. If you're gonna use it, the recommendation is to call it immediately after SSL_new(3), before you even initiate a connection. Timing matters, bestie. ⏰

The argument mode may be one of these:

  • SSL_DEFAULT_STREAM_MODE_AUTO_BIDI — This is the default setting, the OTP. If SSL_write(3) is called before 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 before any call to SSL_write(3), OpenSSL waits for an incoming stream from the peer — which means SSL_read(3) will 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, so this setting does not guarantee you get a bidirectional stream when SSL_read(3) is called first. To figure out 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 before any call to SSL_read(3), a unidirectional client-initiated stream is created and bound as the default stream. Otherwise the behaviour is identical to SSL_DEFAULT_STREAM_MODE_AUTO_BIDI. The behaviour when SSL_read(3) is called before any call to SSL_write(3) is unchanged. Same energy, different stream type. 💫
  • SSL_DEFAULT_STREAM_MODE_NONE — Default stream creation is inhibited. This is the recommended mode of operation, periodt. SSL_read(3) and SSL_write(3) calls cannot be made on the QUIC connection SSL object directly. You have to obtain streams using SSL_new_stream(3) or SSL_accept_stream(3) in order to communicate with the peer. Do it properly. 🎀

And just to say it one more time for the people in the back: 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. 🚫

Also — SSL_set_incoming_stream_policy(3) interacts significantly with the default stream functionality. Just so you know. iykyk 🌈

🔥 RETURN VALUES

  • SSL_set_default_stream_mode() returns 1 on success and 0 on failure.
  • SSL_set_default_stream_mode() fails if it is called after a default stream has already been established. (Told you — timing.) 😤
  • 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. Newer than your fave's debut single, ngl.

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

k that's the whole page bestie, go configure your streams responsibly 💖✨🦋

Signing off from the 3.5.0 edition, dated 2026-09-25 — mwah 💅🎀

📦 where this page comes from