SSL_SET_DEFAULT_STREAM_MODE(3ossl)

💅 SSL_SET_DEFAULT_STREAM_MODE — hey bestie, welcome to the 3ossl corner of the manual 🦋

okay so this whole page is about one little function and three little constants, and they're all about the ✨default stream✨ on a QUIC connection. it's giving "legacy app tries to pretend QUIC is just regular TLS" energy, and honestly? relatable. let's get into it 🎀

---

🌸 NAME 🌸

SSL_set_default_stream_mode, SSL_DEFAULT_STREAM_MODE_NONE, SSL_DEFAULT_STREAM_MODE_AUTO_BIDI, SSL_DEFAULT_STREAM_MODE_AUTO_UNI — the whole girl gang that manages 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 may have a default stream attached to it. and what even is a default stream? bestie it's literally just a QUIC stream that SSL_read(3) and SSL_write(3) calls get redirected to when you call them on a QUIC connection SSL object. that's it. that's the whole vibe. the point of default stream handling is letting legacy applications use QUIC kinda like they'd use a traditional TLS connection — no cap 👑

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). automatic. iconic. 🔥

here's the thing though — a QUIC stream has to be explicitly designated as client-initiated or server-initiated up front. like, no take-backs, decide now. this roughly corresponds to whether your application 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 wishes 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 instead, or if you wanna disable default stream functionality entirely, SSL_set_default_stream_mode() (discussed below, keep reading babe) is your girl 💜

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

and ngl, the recommendation here is: new applications, and applications that rely on multiple streams, should forego the default stream functionality altogether. it's intended for legacy applications. iykyk 🦋

so SSL_set_default_stream_mode() is what configures or disables default stream handling. it can only be called on a QUIC connection SSL object prior to any default stream being created. and if you're gonna use it, the rec is to call it immediately after calling SSL_new(3), before you initiate a connection. the mode argument can be one of these three:

🌈 the modes, ranked by vibe

• SSL_DEFAULT_STREAM_MODE_AUTO_BIDI — this is the default setting, the main character 👑 if SSL_write(3) is called prior to 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 prior to 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. and listen — that incoming stream may be either bidirectional or unidirectional, so this setting does not guarantee you a bidirectional stream when SSL_read(3) is called first. rude, i know. 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 prior to any call to SSL_read(3), a unidirectional client-initiated stream is created and bound as the default stream. everything else is identical to SSL_DEFAULT_STREAM_MODE_AUTO_BIDI. and the behaviour when SSL_read(3) is called prior to any call to SSL_write(3)? unchanged. same as before, bestie 🦋
• SSL_DEFAULT_STREAM_MODE_NONE — default stream creation is inhibited 🚫 and 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 must obtain streams using SSL_new_stream(3) or SSL_accept_stream(3) in order to communicate with the peer. that's the assignment 💅

also, quick note: 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. consistent. we love that for us.

oh and 🚨 SSL_set_incoming_stream_policy(3) interacts significantly with the default stream functionality. like, significantly significantly. keep that in mind.

🍓 RETURN VALUES 🍓

• SSL_set_default_stream_mode() returns 1 on success and 0 on failure ✨
• SSL_set_default_stream_mode() fails if it's called after a default stream has already been established 🙈 (should've called it earlier, babe)
• 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) — go read these next, bestie, they're all in the group chat 🫶

⭐ HISTORY ⭐

these functions were added in OpenSSL 3.2 🌱 (so if you're on something older... no they weren't, sorry bestie)

👑 COPYRIGHT 👑

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

---

okay that's the whole page, you ate that 💖 mwah. this was OpenSSL 3.5.6, dated 2026-04-07, and yes that's the SSL_SET_DEFAULT_STREAM_MODE(3ossl) manual — go slay your QUIC streams, queen 🌈👑💅