Debian Codegraph @

upstream/debian-unstable/man3/SSL_set_default_stream_mode.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_SET_DEFAULT_STREAM_MODE 3SSL"
58 .TH SSL_SET_DEFAULT_STREAM_MODE 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_set_default_stream_mode,
65 SSL_DEFAULT_STREAM_MODE_NONE, SSL_DEFAULT_STREAM_MODE_AUTO_BIDI,
66 SSL_DEFAULT_STREAM_MODE_AUTO_UNI \- manage the default stream for a QUIC
67 connection
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/ssl.h>
72 \&
73 \& #define SSL_DEFAULT_STREAM_MODE_NONE
74 \& #define SSL_DEFAULT_STREAM_MODE_AUTO_BIDI
75 \& #define SSL_DEFAULT_STREAM_MODE_AUTO_UNI
76 \&
77 \& int SSL_set_default_stream_mode(SSL *conn, uint32_t mode);
78 .Ve
79 .SH DESCRIPTION
80 .IX Header "DESCRIPTION"
81 A QUIC connection SSL object may have a default stream attached to it. A default
82 stream is a QUIC stream to which calls to \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3)
83 made on a QUIC connection SSL object are redirected. Default stream handling
84 allows legacy applications to use QUIC similarly to a traditional TLS
85 connection.
86 .PP
87 When not disabled, a default stream is automatically created on an outgoing
88 connection once \fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called.
89 .PP
90 A QUIC stream must be explicitly designated as client-initiated or
91 server-initiated up front. This broadly corresponds to whether an application
92 protocol involves the client transmitting first, or the server transmitting
93 first. As such, if \fBSSL_read\fR\|(3) is called first (before any call to
94 \&\fBSSL_write\fR\|(3)) after establishing a connection, OpenSSL will wait for the
95 server to open the first server-initiated stream, and then bind this as the
96 default stream. Conversely, if \fBSSL_write\fR\|(3) is called before any call to
97 \&\fBSSL_read\fR\|(3), OpenSSL assumes the client wishes to transmit first, creates a
98 client-initiated stream, and binds this as the default stream.
99 .PP
100 By default, the default stream created is bidirectional. If a unidirectional
101 stream is desired, or if the application wishes to disable default stream
102 functionality, \fBSSL_set_default_stream_mode()\fR (discussed below) can be used to
103 accomplish this.
104 .PP
105 When a QUIC connection SSL object has no default stream currently associated
106 with it, for example because default stream functionality was disabled, calls to
107 functions which require a stream on the QUIC connection SSL object (for example,
108 \&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3)) will fail.
109 .PP
110 It is recommended that new applications and applications which rely on multiple
111 streams forego use of the default stream functionality, which is intended for
112 legacy applications.
113 .PP
114 \&\fBSSL_set_default_stream_mode()\fR can be used to configure or disable default stream
115 handling. It can only be called on a QUIC connection SSL object prior to any
116 default stream being created. If used, it is recommended to call it immediately
117 after calling \fBSSL_new\fR\|(3), prior to initiating a connection. The argument
118 \&\fImode\fR may be one of the following options:
119 .IP SSL_DEFAULT_STREAM_MODE_AUTO_BIDI 4
120 .IX Item "SSL_DEFAULT_STREAM_MODE_AUTO_BIDI"
121 This is the default setting. If \fBSSL_write\fR\|(3) is called prior to any call to
122 \&\fBSSL_read\fR\|(3), a bidirectional client-initiated stream is created and bound as
123 the default stream. If \fBSSL_read\fR\|(3) is called prior to any call to
124 \&\fBSSL_write\fR\|(3), OpenSSL waits for an incoming stream from the peer (causing
125 \&\fBSSL_read\fR\|(3) to block if the connection is in blocking mode), and then binds
126 that stream as the default stream. Note that this incoming stream may be either
127 bidirectional or unidirectional; thus, this setting does not guarantee the
128 presence of a bidirectional stream when \fBSSL_read\fR\|(3) is called first. To
129 determine the type of a stream after a call to \fBSSL_read\fR\|(3), use
130 \&\fBSSL_get_stream_type\fR\|(3).
131 .IP SSL_DEFAULT_STREAM_MODE_AUTO_UNI 4
132 .IX Item "SSL_DEFAULT_STREAM_MODE_AUTO_UNI"
133 In this mode, if \fBSSL_write\fR\|(3) is called prior to any call to \fBSSL_read\fR\|(3),
134 a unidirectional client-initiated stream is created and bound as the default
135 stream. The behaviour is otherwise identical to that of
136 \&\fBSSL_DEFAULT_STREAM_MODE_AUTO_BIDI\fR. The behaviour when \fBSSL_read\fR\|(3) is
137 called prior to any call to \fBSSL_write\fR\|(3) is unchanged.
138 .IP SSL_DEFAULT_STREAM_MODE_NONE 4
139 .IX Item "SSL_DEFAULT_STREAM_MODE_NONE"
140 Default stream creation is inhibited. This is the recommended mode of operation.
141 \&\fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) calls cannot be made on the QUIC connection
142 SSL object directly. You must obtain streams using \fBSSL_new_stream\fR\|(3) or
143 \&\fBSSL_accept_stream\fR\|(3) in order to communicate with the peer.
144 .PP
145 A default stream will not be automatically created on a QUIC connection SSL
146 object if the default stream mode is set to \fBSSL_DEFAULT_STREAM_MODE_NONE\fR.
147 .PP
148 \&\fBSSL_set_incoming_stream_policy\fR\|(3) interacts significantly with the default
149 stream functionality.
150 .SH "RETURN VALUES"
151 .IX Header "RETURN VALUES"
152 \&\fBSSL_set_default_stream_mode()\fR returns 1 on success and 0 on failure.
153 .PP
154 \&\fBSSL_set_default_stream_mode()\fR fails if it is called after a default stream has
155 already been established.
156 .PP
157 These functions fail if called on a QUIC stream SSL object or on a non-QUIC SSL
158 object.
159 .SH "SEE ALSO"
160 .IX Header "SEE ALSO"
161 \&\fBSSL_new_stream\fR\|(3), \fBSSL_accept_stream\fR\|(3), \fBSSL_free\fR\|(3),
162 \&\fBSSL_set_incoming_stream_policy\fR\|(3)
163 .SH HISTORY
164 .IX Header "HISTORY"
165 These functions were added in OpenSSL 3.2.
166 .SH COPYRIGHT
167 .IX Header "COPYRIGHT"
168 Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved.
169 .PP
170 Licensed under the Apache License 2.0 (the "License"). You may not use
171 this file except in compliance with the License. You can obtain a copy
172 in the file LICENSE in the source distribution or at
173 <https://www.openssl.org/source/license.html>.