1=pod
2
3=head1 NAME
4
5SSL_set_default_stream_mode,
6SSL_DEFAULT_STREAM_MODE_NONE, SSL_DEFAULT_STREAM_MODE_AUTO_BIDI,
7SSL_DEFAULT_STREAM_MODE_AUTO_UNI - manage the default stream for a QUIC
8connection
9
10=head1 SYNOPSIS
11
12 #include <openssl/ssl.h>
13
14 #define SSL_DEFAULT_STREAM_MODE_NONE
15 #define SSL_DEFAULT_STREAM_MODE_AUTO_BIDI
16 #define SSL_DEFAULT_STREAM_MODE_AUTO_UNI
17
18 int SSL_set_default_stream_mode(SSL *conn, uint32_t mode);
19
20=head1 DESCRIPTION
21
22A QUIC connection SSL object may have a default stream attached to it. A default
23stream is a QUIC stream to which calls to L<SSL_read(3)> and L<SSL_write(3)>
24made on a QUIC connection SSL object are redirected. Default stream handling
25allows legacy applications to use QUIC similarly to a traditional TLS
26connection.
27
28When not disabled, a default stream is automatically created on an outgoing
29connection once L<SSL_read(3)> or L<SSL_write(3)> is called.
30
31A QUIC stream must be explicitly designated as client-initiated or
32server-initiated up front. This broadly corresponds to whether an application
33protocol involves the client transmitting first, or the server transmitting
34first. As such, if L<SSL_read(3)> is called first (before any call to
35L<SSL_write(3)>)  after establishing a connection, OpenSSL will wait for the
36server to open the first server-initiated stream, and then bind this as the
37default stream. Conversely, if L<SSL_write(3)> is called before any call to
38L<SSL_read(3)>, OpenSSL assumes the client wishes to transmit first, creates a
39client-initiated stream, and binds this as the default stream.
40
41By default, the default stream created is bidirectional. If a unidirectional
42stream is desired, or if the application wishes to disable default stream
43functionality, SSL_set_default_stream_mode() (discussed below) can be used to
44accomplish this.
45
46When a QUIC connection SSL object has no default stream currently associated
47with it, for example because default stream functionality was disabled, calls to
48functions which require a stream on the QUIC connection SSL object (for example,
49L<SSL_read(3)> and L<SSL_write(3)>) will fail.
50
51It is recommended that new applications and applications which rely on multiple
52streams forego use of the default stream functionality, which is intended for
53legacy applications.
54
55SSL_set_default_stream_mode() can be used to configure or disable default stream
56handling. It can only be called on a QUIC connection SSL object prior to any
57default stream being created. If used, it is recommended to call it immediately
58after calling L<SSL_new(3)>, prior to initiating a connection. The argument
59I<mode> may be one of the following options:
60
61=over 4
62
63=item SSL_DEFAULT_STREAM_MODE_AUTO_BIDI
64
65This is the default setting. If L<SSL_write(3)> is called prior to any call to
66L<SSL_read(3)>, a bidirectional client-initiated stream is created and bound as
67the default stream. If L<SSL_read(3)> is called prior to any call to
68L<SSL_write(3)>, OpenSSL waits for an incoming stream from the peer (causing
69L<SSL_read(3)> to block if the connection is in blocking mode), and then binds
70that stream as the default stream. Note that this incoming stream may be either
71bidirectional or unidirectional; thus, this setting does not guarantee the
72presence of a bidirectional stream when L<SSL_read(3)> is called first. To
73determine the type of a stream after a call to L<SSL_read(3)>, use
74L<SSL_get_stream_type(3)>.
75
76=item SSL_DEFAULT_STREAM_MODE_AUTO_UNI
77
78In this mode, if L<SSL_write(3)> is called prior to any call to L<SSL_read(3)>,
79a unidirectional client-initiated stream is created and bound as the default
80stream. The behaviour is otherwise identical to that of
81B<SSL_DEFAULT_STREAM_MODE_AUTO_BIDI>. The behaviour when L<SSL_read(3)> is
82called prior to any call to L<SSL_write(3)> is unchanged.
83
84=item SSL_DEFAULT_STREAM_MODE_NONE
85
86Default stream creation is inhibited. This is the recommended mode of operation.
87L<SSL_read(3)> and L<SSL_write(3)> calls cannot be made on the QUIC connection
88SSL object directly. You must obtain streams using L<SSL_new_stream(3)> or
89L<SSL_accept_stream(3)> in order to communicate with the peer.
90
91=back
92
93A default stream will not be automatically created on a QUIC connection SSL
94object if the default stream mode is set to B<SSL_DEFAULT_STREAM_MODE_NONE>.
95
96L<SSL_set_incoming_stream_policy(3)> interacts significantly with the default
97stream functionality.
98
99=head1 RETURN VALUES
100
101SSL_set_default_stream_mode() returns 1 on success and 0 on failure.
102
103SSL_set_default_stream_mode() fails if it is called after a default stream has
104already been established.
105
106These functions fail if called on a QUIC stream SSL object or on a non-QUIC SSL
107object.
108
109=head1 SEE ALSO
110
111L<SSL_new_stream(3)>, L<SSL_accept_stream(3)>, L<SSL_free(3)>,
112L<SSL_set_incoming_stream_policy(3)>
113
114=head1 HISTORY
115
116These functions were added in OpenSSL 3.2.
117
118=head1 COPYRIGHT
119
120Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
121
122Licensed under the Apache License 2.0 (the "License").  You may not use
123this file except in compliance with the License.  You can obtain a copy
124in the file LICENSE in the source distribution or at
125L<https://www.openssl.org/source/license.html>.
126
127=cut
128