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