SSL_SET_DEFAULT_STREAM_MODE(3SSL)

📦
version 4.0.3 · 6 versions
, in ubuntu stonking

💖 SSL_SET_DEFAULT_STREAM_MODE — okay bestie, let's talk about your QUIC default stream 💖

So this is from the 3SSL manual, and it's all about SSL_set_default_stream_mode, plus its three lil mode constants SSL_DEFAULT_STREAM_MODE_NONE, SSL_DEFAULT_STREAM_MODE_AUTO_BIDI, and SSL_DEFAULT_STREAM_MODE_AUTO_UNI — literally the whole squad 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 🦋

okay so. A QUIC connection SSL object can have a default stream attached to it, and that's just a QUIC stream that SSL_read(3) and SSL_write(3) calls get redirected to when you call them on the QUIC connection SSL object itself. Basically, default stream handling is the vibe that lets legacy applications use QUIC kinda like they'd use a plain old traditional TLS connection. iconic of OpenSSL honestly 👑

When it's not disabled, a default stream gets auto-created on an outgoing connection the moment you call SSL_read(3) or SSL_write(3). No extra work, she just shows up 💅

Now here's the thing: a QUIC stream has to be explicitly marked as client-initiated or server-initiated up front, no takebacks. And this broadly corresponds to whether the app protocol has the client transmitting first, or the server transmitting first. So:

  • if SSL_read(3) gets called first (before any call to SSL_write(3)) after the connection is established, OpenSSL will literally just 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 that gets created is bidirectional. But if you want a unidirectional stream, or if you wanna disable default stream functionality entirely, SSL_set_default_stream_mode() (more on her below) is the one that gets it done 🎀

And when a QUIC connection SSL object has no default stream currently associated with it — say, because default stream functionality was disabled — then calls to functions that need a stream on that QUIC connection SSL object (looking at you, SSL_read(3) and SSL_write(3)) will simply fail. no stream, no service, sorry bestie 😭

Real talk: it is recommended that new applications, and applications that rely on multiple streams, forego the default stream functionality altogether. It's intended for legacy applications. periodt.

SSL_set_default_stream_mode() is how you configure or disable default stream handling. But listen: 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 move is to call it immediately after SSL_new(3), before you initiate a connection. ✨

The argument mode may be one of these options:

  • 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. Heads up though: 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. To find out what type a stream actually is 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 behaves identically 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, bestie. 🌈
  • SSL_DEFAULT_STREAM_MODE_NONE — default stream creation is inhibited. full stop. And this is actually the recommended mode of operation 👑. With this one, 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 whole assignment.

Also: 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. obviously, but they said it, so I'm saying it 💀

And one more thing to keep on your radar: SSL_set_incoming_stream_policy(3) interacts significantly with the default stream functionality. iykyk 👀

⭐ RETURN VALUES ⭐

SSL_set_default_stream_mode() returns 1 on success and 0 on failure. simple as that.

SSL_set_default_stream_mode() fails if it is called after a default stream has already been established. (told you — timing is everything, bestie 😤)

These functions also fail if called on a QUIC stream SSL object or on a non-QUIC SSL object. Wrong object, wrong vibe. 🚫

🫶 SEE ALSO 🫶

🎀 HISTORY 🎀

These functions were added in OpenSSL 3.2. new-ish era, we love her ✨

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

and that's the whole page, bestie!! 💖✨🦋🌸🫶

signing off from version 4.0.3, dated 2026-09-29 — this was SSL_SET_DEFAULT_STREAM_MODE(3SSL), slay, no cap, go forth and manage your streams responsibly 💅👑

📦 where this page comes from