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