1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
.\" -*- 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_GET_STREAM_ID 3SSL"
.TH SSL_GET_STREAM_ID 3SSL 2024-04-04 3.2.2-dev 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_get_stream_id, SSL_get_stream_type, SSL_STREAM_TYPE_NONE,
SSL_STREAM_TYPE_READ, SSL_STREAM_TYPE_WRITE, SSL_STREAM_TYPE_BIDI,
SSL_is_stream_local \- get QUIC stream ID and stream type information
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/ssl.h>
\&
\& uint64_t SSL_get_stream_id(SSL *ssl);
\&
\& #define SSL_STREAM_TYPE_NONE
\& #define SSL_STREAM_TYPE_BIDI
\& #define SSL_STREAM_TYPE_READ
\& #define SSL_STREAM_TYPE_WRITE
\& int SSL_get_stream_type(SSL *ssl);
\&
\& int SSL_is_stream_local(SSL *ssl);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fBSSL_get_stream_id()\fR function returns the QUIC stream ID for a QUIC stream
SSL object, or for a QUIC connection SSL object which has a default stream
attached.
.PP
The \fBSSL_get_stream_type()\fR function identifies what operations can be performed
on the stream, and returns one of the following values:
.IP \fBSSL_STREAM_TYPE_NONE\fR 4
.IX Item "SSL_STREAM_TYPE_NONE"
The SSL object is a QUIC connection SSL object without a default stream
attached.
.IP \fBSSL_STREAM_TYPE_BIDI\fR 4
.IX Item "SSL_STREAM_TYPE_BIDI"
The SSL object is a non-QUIC SSL object, or is a QUIC stream object (or QUIC
connection SSL object with a default stream attached), and that stream is a
bidirectional QUIC stream.
.IP \fBSSL_STREAM_TYPE_READ\fR 4
.IX Item "SSL_STREAM_TYPE_READ"
The SSL object is a QUIC stream object (or QUIC connection SSL object with a
default stream attached), and that stream is a unidirectional QUIC stream which
was initiated by the remote peer; thus, it can be read from, but not written to.
.IP \fBSSL_STREAM_TYPE_WRITE\fR 4
.IX Item "SSL_STREAM_TYPE_WRITE"
The SSL object is a QUIC stream object (or QUIC connection SSL object with a
default stream attached), and that stream is a unidirectional QUIC stream which
was initiated by the local application; thus, it can be written to, but not read
from.
.PP
The \fBSSL_is_stream_local()\fR function determines whether a stream was locally
created.
.SH NOTES
.IX Header "NOTES"
While QUICv1 assigns specific meaning to the low two bits of a QUIC stream ID,
QUIC stream IDs in future versions of QUIC are not required to have the same
semantics. Do not determine stream properties using these bits. Instead, use
\&\fBSSL_get_stream_type()\fR to determine the stream type and \fBSSL_get_stream_is_local()\fR
to determine the stream initiator.
.PP
The \fBSSL_get_stream_type()\fR identifies the type of a QUIC stream based on its
identity, and does not indicate whether an operation can currently be
successfully performed on a stream. For example, you might locally initiate a
unidirectional stream, write to it, and then conclude the stream using
\&\fBSSL_stream_conclude\fR\|(3), meaning that it can no longer be written to, but
\&\fBSSL_get_stream_type()\fR would still return \fBSSL_STREAM_TYPE_WRITE\fR. The value
returned by \fBSSL_get_stream_type()\fR does not vary over the lifespan of a stream.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBSSL_get_stream_id()\fR returns a QUIC stream ID, or \fBUINT64_MAX\fR if called on an
SSL object which is not a QUIC SSL object, or if called on a QUIC connection SSL
object without a default stream attached. Note that valid QUIC stream IDs are
always below 2**62.
.PP
\&\fBSSL_get_stream_type()\fR returns one of the \fBSSL_STREAM_TYPE\fR values.
.PP
\&\fBSSL_is_stream_local()\fR returns 1 if called on a QUIC stream SSL object which
represents a stream which was locally initiated. It returns 0 if called on a
QUIC stream SSL object which represents a stream which was remotely initiated by
a peer, and \-1 if called on any other kind of SSL object.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBSSL_new_stream\fR\|(3), \fBSSL_accept_stream\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
<https://www.openssl.org/source/license.html>.
|
