.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "SSL_SET_DEFAULT_STREAM_MODE 3ssl" .TH SSL_SET_DEFAULT_STREAM_MODE 3ssl 2024-04-28 3.3.0 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH 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 .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& #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); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" A QUIC connection SSL object may have a default stream attached to it. A default stream is a QUIC stream to which calls to \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) made on a QUIC connection SSL object are redirected. Default stream handling allows legacy applications to use QUIC similarly to a traditional TLS connection. .PP When not disabled, a default stream is automatically created on an outgoing connection once \fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called. .PP A QUIC stream must be explicitly designated as client-initiated or server-initiated up front. This broadly corresponds to whether an application protocol involves the client transmitting first, or the server transmitting first. As such, if \fBSSL_read\fR\|(3) is called first (before any call to \&\fBSSL_write\fR\|(3)) after establishing a connection, OpenSSL will wait for the server to open the first server-initiated stream, and then bind this as the default stream. Conversely, if \fBSSL_write\fR\|(3) is called before any call to \&\fBSSL_read\fR\|(3), OpenSSL assumes the client wishes to transmit first, creates a client-initiated stream, and binds this as the default stream. .PP By default, the default stream created is bidirectional. If a unidirectional stream is desired, or if the application wishes to disable default stream functionality, \fBSSL_set_default_stream_mode()\fR (discussed below) can be used to accomplish this. .PP When a QUIC connection SSL object has no default stream currently associated with it, for example because default stream functionality was disabled, calls to functions which require a stream on the QUIC connection SSL object (for example, \&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3)) will fail. .PP It is recommended that new applications and applications which rely on multiple streams forego use of the default stream functionality, which is intended for legacy applications. .PP \&\fBSSL_set_default_stream_mode()\fR can be used to configure or disable default stream handling. It can only be called on a QUIC connection SSL object prior to any default stream being created. If used, it is recommended to call it immediately after calling \fBSSL_new\fR\|(3), prior to initiating a connection. The argument \&\fImode\fR may be one of the following options: .IP SSL_DEFAULT_STREAM_MODE_AUTO_BIDI 4 .IX Item "SSL_DEFAULT_STREAM_MODE_AUTO_BIDI" This is the default setting. If \fBSSL_write\fR\|(3) is called prior to any call to \&\fBSSL_read\fR\|(3), a bidirectional client-initiated stream is created and bound as the default stream. If \fBSSL_read\fR\|(3) is called prior to any call to \&\fBSSL_write\fR\|(3), OpenSSL waits for an incoming stream from the peer (causing \&\fBSSL_read\fR\|(3) to 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; thus, this setting does not guarantee the presence of a bidirectional stream when \fBSSL_read\fR\|(3) is called first. To determine the type of a stream after a call to \fBSSL_read\fR\|(3), use \&\fBSSL_get_stream_type\fR\|(3). .IP SSL_DEFAULT_STREAM_MODE_AUTO_UNI 4 .IX Item "SSL_DEFAULT_STREAM_MODE_AUTO_UNI" In this mode, if \fBSSL_write\fR\|(3) is called prior to any call to \fBSSL_read\fR\|(3), a unidirectional client-initiated stream is created and bound as the default stream. The behaviour is otherwise identical to that of \&\fBSSL_DEFAULT_STREAM_MODE_AUTO_BIDI\fR. The behaviour when \fBSSL_read\fR\|(3) is called prior to any call to \fBSSL_write\fR\|(3) is unchanged. .IP SSL_DEFAULT_STREAM_MODE_NONE 4 .IX Item "SSL_DEFAULT_STREAM_MODE_NONE" Default stream creation is inhibited. This is the recommended mode of operation. \&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) calls cannot be made on the QUIC connection SSL object directly. You must obtain streams using \fBSSL_new_stream\fR\|(3) or \&\fBSSL_accept_stream\fR\|(3) in order to communicate with the peer. .PP A default stream will not be automatically created on a QUIC connection SSL object if the default stream mode is set to \fBSSL_DEFAULT_STREAM_MODE_NONE\fR. .PP \&\fBSSL_set_incoming_stream_policy\fR\|(3) interacts significantly with the default stream functionality. .SH "RETURN VALUES" .IX Header "RETURN VALUES" \&\fBSSL_set_default_stream_mode()\fR returns 1 on success and 0 on failure. .PP \&\fBSSL_set_default_stream_mode()\fR fails if it is called after a default stream has already been established. .PP These functions fail if called on a QUIC stream SSL object or on a non-QUIC SSL object. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBSSL_new_stream\fR\|(3), \fBSSL_accept_stream\fR\|(3), \fBSSL_free\fR\|(3), \&\fBSSL_set_incoming_stream_policy\fR\|(3) .SH HISTORY .IX Header "HISTORY" These functions were added in OpenSSL 3.2. .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP 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 .