| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | SSL_get_stream_id, SSL_get_stream_type, SSL_STREAM_TYPE_NONE,
|
|---|
| 6 | SSL_STREAM_TYPE_READ, SSL_STREAM_TYPE_WRITE, SSL_STREAM_TYPE_BIDI,
|
|---|
| 7 | SSL_is_stream_local - get QUIC stream ID and stream type information
|
|---|
| 8 |
|
|---|
| 9 | =head1 SYNOPSIS
|
|---|
| 10 |
|
|---|
| 11 | #include <openssl/ssl.h>
|
|---|
| 12 |
|
|---|
| 13 | uint64_t SSL_get_stream_id(SSL *ssl);
|
|---|
| 14 |
|
|---|
| 15 | #define SSL_STREAM_TYPE_NONE
|
|---|
| 16 | #define SSL_STREAM_TYPE_BIDI
|
|---|
| 17 | #define SSL_STREAM_TYPE_READ
|
|---|
| 18 | #define SSL_STREAM_TYPE_WRITE
|
|---|
| 19 | int SSL_get_stream_type(SSL *ssl);
|
|---|
| 20 |
|
|---|
| 21 | int SSL_is_stream_local(SSL *ssl);
|
|---|
| 22 |
|
|---|
| 23 | =head1 DESCRIPTION
|
|---|
| 24 |
|
|---|
| 25 | The SSL_get_stream_id() function returns the QUIC stream ID for a QUIC stream
|
|---|
| 26 | SSL object, or for a QUIC connection SSL object which has a default stream
|
|---|
| 27 | attached.
|
|---|
| 28 |
|
|---|
| 29 | The SSL_get_stream_type() function identifies what operations can be performed
|
|---|
| 30 | on the stream, and returns one of the following values:
|
|---|
| 31 |
|
|---|
| 32 | =over 4
|
|---|
| 33 |
|
|---|
| 34 | =item B<SSL_STREAM_TYPE_NONE>
|
|---|
| 35 |
|
|---|
| 36 | The SSL object is a QUIC connection SSL object without a default stream
|
|---|
| 37 | attached.
|
|---|
| 38 |
|
|---|
| 39 | =item B<SSL_STREAM_TYPE_BIDI>
|
|---|
| 40 |
|
|---|
| 41 | The SSL object is a non-QUIC SSL object, or is a QUIC stream object (or QUIC
|
|---|
| 42 | connection SSL object with a default stream attached), and that stream is a
|
|---|
| 43 | bidirectional QUIC stream.
|
|---|
| 44 |
|
|---|
| 45 | =item B<SSL_STREAM_TYPE_READ>
|
|---|
| 46 |
|
|---|
| 47 | The SSL object is a QUIC stream object (or QUIC connection SSL object with a
|
|---|
| 48 | default stream attached), and that stream is a unidirectional QUIC stream which
|
|---|
| 49 | was initiated by the remote peer; thus, it can be read from, but not written to.
|
|---|
| 50 |
|
|---|
| 51 | =item B<SSL_STREAM_TYPE_WRITE>
|
|---|
| 52 |
|
|---|
| 53 | The SSL object is a QUIC stream object (or QUIC connection SSL object with a
|
|---|
| 54 | default stream attached), and that stream is a unidirectional QUIC stream which
|
|---|
| 55 | was initiated by the local application; thus, it can be written to, but not read
|
|---|
| 56 | from.
|
|---|
| 57 |
|
|---|
| 58 | =back
|
|---|
| 59 |
|
|---|
| 60 | The SSL_is_stream_local() function determines whether a stream was locally
|
|---|
| 61 | created.
|
|---|
| 62 |
|
|---|
| 63 | =head1 NOTES
|
|---|
| 64 |
|
|---|
| 65 | While QUICv1 assigns specific meaning to the low two bits of a QUIC stream ID,
|
|---|
| 66 | QUIC stream IDs in future versions of QUIC are not required to have the same
|
|---|
| 67 | semantics. Do not determine stream properties using these bits. Instead, use
|
|---|
| 68 | SSL_get_stream_type() to determine the stream type and SSL_get_stream_is_local()
|
|---|
| 69 | to determine the stream initiator.
|
|---|
| 70 |
|
|---|
| 71 | The SSL_get_stream_type() identifies the type of a QUIC stream based on its
|
|---|
| 72 | identity, and does not indicate whether an operation can currently be
|
|---|
| 73 | successfully performed on a stream. For example, you might locally initiate a
|
|---|
| 74 | unidirectional stream, write to it, and then conclude the stream using
|
|---|
| 75 | L<SSL_stream_conclude(3)>, meaning that it can no longer be written to, but
|
|---|
| 76 | SSL_get_stream_type() would still return B<SSL_STREAM_TYPE_WRITE>. The value
|
|---|
| 77 | returned by SSL_get_stream_type() does not vary over the lifespan of a stream.
|
|---|
| 78 |
|
|---|
| 79 | =head1 RETURN VALUES
|
|---|
| 80 |
|
|---|
| 81 | SSL_get_stream_id() returns a QUIC stream ID, or B<UINT64_MAX> if called on an
|
|---|
| 82 | SSL object which is not a QUIC SSL object, or if called on a QUIC connection SSL
|
|---|
| 83 | object without a default stream attached. Note that valid QUIC stream IDs are
|
|---|
| 84 | always below 2**62.
|
|---|
| 85 |
|
|---|
| 86 | SSL_get_stream_type() returns one of the B<SSL_STREAM_TYPE> values.
|
|---|
| 87 |
|
|---|
| 88 | SSL_is_stream_local() returns 1 if called on a QUIC stream SSL object which
|
|---|
| 89 | represents a stream which was locally initiated. It returns 0 if called on a
|
|---|
| 90 | QUIC stream SSL object which represents a stream which was remotely initiated by
|
|---|
| 91 | a peer, and -1 if called on any other kind of SSL object.
|
|---|
| 92 |
|
|---|
| 93 | =head1 SEE ALSO
|
|---|
| 94 |
|
|---|
| 95 | L<SSL_new_stream(3)>, L<SSL_accept_stream(3)>
|
|---|
| 96 |
|
|---|
| 97 | =head1 HISTORY
|
|---|
| 98 |
|
|---|
| 99 | These functions were added in OpenSSL 3.2.
|
|---|
| 100 |
|
|---|
| 101 | =head1 COPYRIGHT
|
|---|
| 102 |
|
|---|
| 103 | Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 104 |
|
|---|
| 105 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 106 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 107 | in the file LICENSE in the source distribution or at
|
|---|
| 108 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 109 |
|
|---|
| 110 | =cut
|
|---|
