mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-04-06 20:20:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

QUIC MSST: Add documentation for new APIs

Browse Source 
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20765)
This commit is contained in:
Hugo Landau 2023-04-18 19:30:56 +01:00
parent 9aaafc26e0
commit 1e4a9d882f
10 changed files with 909 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
doc/man3/SSL_accept_stream.pod Normal file
View File

@ -0,0 +1,74 @@
=pod
=head1 NAME
SSL_accept_stream, SSL_get_accept_stream_queue_len, SSL_ACCEPT_STREAM_NO_BLOCK -
accept an incoming QUIC stream from a QUIC peer
=head1 SYNOPSIS
#include <openssl/ssl.h>
#define SSL_ACCEPT_STREAM_NO_BLOCK
SSL *SSL_accept_stream(SSL *ssl, uint64_t flags);
size_t SSL_get_accept_stream_queue_len(SSL *ssl);
=head1 DESCRIPTION
The SSL_accept_stream() function attempts to dequeue an incoming stream from the
given QUIC connection SSL object and returns the newly allocated QUIC stream SSL
object.
If the queue of incoming streams is empty, this function returns NULL (in
nonblocking mode) or waits for an incoming stream (in blocking mode). This
function may still return NULL in blocking mode, for example if the underlying
connection is terminated.
The caller is responsible for managing the lifetime of the returned QUIC stream
SSL object. The lifespan of the parent QUIC connection SSL object must exceed
that of the QUIC stream SSL object; that is, the stream object must be freed
first, using L<SSL_free(3)>.
This function will block if the QUIC connection SSL object is configured in
blocking mode (see L<SSL_set_blocking_mode(3)>), but this may be bypassed by
passing the flag B<SSL_ACCEPT_STREAM_NO_BLOCK> in B<flags>. If this flag is set,
this function never blocks.
SSL_accept_stream_queue_len() returns the number of incoming streams currently
waiting in the accept queue. It is intended for informational use only, as this
number may change between a call to it and a subsequent call to
SSL_accept_stream(), due to SSL_accept_stream() calls by other threads.
Depending on whether default stream functionality is being used, it may be
necessary to explicitly configure the incoming stream rejection policy before
streams can be accepted; see L<SSL_set_incoming_stream_reject_policy(3)>.
=head1 RETURN VALUES
SSL_accept_stream() returns a newly allocated QUIC stream SSL object, or NULL if
no new incoming streams are available, or if the connection has been terminated.
SSL_get_accept_stream_queue_len() returns the number of incoming streams
currently waiting in the accept queue.
=head1 SEE ALSO
L<SSL_new_stream(3)>, L<SSL_set_blocking_mode(3)>, L<SSL_free(3)>
=head1 HISTORY
SSL_accept_stream() and SSL_get_accept_stream_queue_len() were added in OpenSSL
3.2.
=head1 COPYRIGHT
Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
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
L<https://www.openssl.org/source/license.html>.
=cut

160
doc/man3/SSL_attach_stream.pod Normal file
View File

@ -0,0 +1,160 @@
=pod
=head1 NAME
SSL_attach_stream, SSL_detach_stream, SSL_set_default_stream_mode,
SSL_DEFAULT_STREAM_MODE_NONE, SSL_DEFAULT_STREAM_MODE_AUTO_BIDI,
SSL_DEFAULT_STREAM_MODE_AUTO_UNI - manage the default stream for a QUIC
connection
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_attach_stream(SSL *conn, SSL *stream);
SSL *SSL_detach_stream(SSL *conn);
#define SSL_DEFAULT_STREAM_MODE_NONE
#define SSL_DEFAULT_STREAM_MODE_AUTO_BIDI
#define SSL_DEFAULT_STREAM_MODE_AUTO_UNI
int SSL_set_default_stream_mode(SSL *conn, uint32_t mode);
=head1 DESCRIPTION
A QUIC connection SSL object may have a default stream attached to it. A default
stream is a QUIC stream to which calls to L<SSL_read(3)> and L<SSL_write(3)>
made on a QUIC connection SSL object are redirected. Default stream handling
allows legacy applications to use QUIC similarly to a traditional TLS
connection.
When not disabled, a default stream is automatically created on an outgoing
connection once L<SSL_read(3)> or L<SSL_write(3)> is called.
A QUIC stream must be explicitly designated as client-initiated or
server-initiated up front. This broadly corresponds to whether an application
protocol involves the client transmitting first, or the server transmitting
first. As such, if L<SSL_read(3)> is called first (before any call to
L<SSL_write(3)>) after establishing a connection, OpenSSL will wait for the
server to open the first server-initiated stream, and then bind this as the
default stream. Conversely, if L<SSL_write(3)> is called before any call to
L<SSL_read(3)>, OpenSSL assumes the client wishes to transmit first, creates a
client-initiated stream, and binds this as the default stream.
By default, the default stream created is bidirectional. If a unidirectional
stream is desired, or if the application wishes to disable default stream
functionality, SSL_set_default_stream_mode() (discussed below) can be used to
accomplish this.
If a default stream is currently bound to a QUIC connection SSL object, it can
be detached from that QUIC connection SSL object and used explicitly by calling
SSL_detach_stream(), which detaches the default stream and returns it as an
explicit QUIC stream SSL object.
Once detached, the caller is responsible for managing the lifetime of the QUIC
stream SSL object and must free it by calling L<SSL_free(3)>. The lifetime of a
QUIC connection SSL object must exceed that of any subsidiary QUIC stream SSL
objects; in other words, QUIC stream SSL objects must be freed before the parent
QUIC connection SSL object is freed.
When a QUIC connection SSL object has no default stream currently associated
with it, for example because the default stream was detached or because default
stream functionality was disabled, calls to functions which require a stream on
the QUIC connection SSL object will fail.
The act of detaching a stream from a QUIC connection SSL object can be reversed
by calling SSL_attach_stream(). This can also be used to designate a stream
obtained via L<SSL_new_stream(3)> or L<SSL_accept_stream(3)> as the default
stream. SSL_attach_stream() cannot be used if there is already a default stream
associated with the QUIC connection SSL object; therefore, you may need to call
SSL_detach_stream() first.
It is recommended that new applications and applications which rely on multiple
streams forego use of the default stream functionality, which is intended for
legacy applications.
SSL_set_default_stream_mode() can be used to configure or disable default stream
handling. It can only be called on a QUIC connection SSL object prior to any
default stream being created. If used, it is recommended to call it immediately
after calling L<SSL_new(3)>, prior to initiating a connection. The argument
B<mode> may be one of the following options:
=over 4
=item SSL_DEFAULT_STREAM_MODE_AUTO_BIDI
This is the default setting. If L<SSL_write(3)> is called prior to any call to
L<SSL_read(3)>, a bidirectional client-initiated stream is created and bound as
the default stream. If L<SSL_read(3)> is called prior to any call to
L<SSL_write(3)>, OpenSSL waits for an incoming stream from the peer (causing
L<SSL_read(3)> to block if the connection is in blocking mode), and then binds
that stream as the default stream. Note that this incoming stream may be either
bidirectional or unidirectional; thus, this setting does not guarantee presence
of a bidirectional stream when L<SSL_read(3)> is called first. To determine the
type of a stream after a call to L<SSL_read(3)>, use L<SSL_get_stream_type(3)>.
=item SSL_DEFAULT_STREAM_MODE_AUTO_UNI
In this mode, if L<SSL_write(3)> is called prior to any call to L<SSL_read(3)>,
a unidirectional client-initiated stream is created and bound as the default
stream. The behaviour is otherwise identical to that of
B<SSL_DEFAULT_STREAM_MODE_AUTO_BIDI>. The behaviour when L<SSL_read(3)> is
called prior to any call to L<SSL_write(3)> is unchanged.
=item SSL_DEFAULT_STREAM_MODE_NONE
Default stream creation is inhibited. This is the recommended mode of operation.
L<SSL_read(3)> and L<SSL_write(3)> calls cannot be made on the QUIC connection
SSL object directly. You must obtain streams using L<SSL_new_stream(3)> or
L<SSL_accept_stream(3)> in order to communicate with the peer.
It is still possible to explicitly attach a stream as the default stream using
SSL_attach_stream().
=back
A default stream will not be automatically created on a QUIC connection SSL
object if the default stream mode is set to B<SSL_DEFAULT_STREAM_MODE_NONE>, or
if the QUIC connection SSL object previously had a default stream which was
detached using SSL_detach_stream().
L<SSL_set_incoming_stream_reject_policy(3)> interacts significantly with the
default stream functionality.
=head1 RETURN VALUES
SSL_detach_stream() returns a QUIC stream SSL object, or NULL if there is no
default stream currently attached.
SSL_attach_stream() returns 1 on success and 0 on failure.
SSL_attach_stream() fails if a default stream is already attached to the QUIC
connection SSL object.
SSL_set_default_stream_mode() returns 1 on success and 0 on failure.
SSL_set_default_stream_mode() fails if it is called after a default stream has
already been established.
These functions fail if called on a QUIC stream SSL object or on a non-QUIC SSL
object.
=head1 SEE ALSO
L<SSL_new_stream(3)>, L<SSL_accept_stream(3)>, L<SSL_free(3)>,
L<SSL_set_incoming_stream_reject_policy(3)>
=head1 HISTORY
These functions were added in OpenSSL 3.2.
=head1 COPYRIGHT
Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
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
L<https://www.openssl.org/source/license.html>.
=cut

54
doc/man3/SSL_get0_connection.pod Normal file
View File

@ -0,0 +1,54 @@
=pod
=head1 NAME
SSL_get0_connection, SSL_is_connection - get a QUIC connection SSL object from a
QUIC stream SSL object
=head1 SYNOPSIS
#include <openssl/ssl.h>
SSL *SSL_get0_connection(SSL *ssl);
int SSL_is_connection(SSL *ssl);
=head1 DESCRIPTION
The SSL_get0_connection() function, when called on a QUIC stream SSL object,
returns the QUIC connection SSL object which the QUIC stream SSL object belongs
to.
When called on a QUIC connection SSL object, it returns the same object.
When called on a non-QUIC object, it returns the same object it was passed.
SSL_is_connection() returns 1 for QUIC connection SSL objects and for non-QUIC
SSL objects, but returns 0 for QUIC stream SSL objects.
=head1 RETURN VALUES
SSL_get0_connection() returns the QUIC connection SSL object (for a QUIC stream
SSL object) and otherwise returns the same SSL object passed. It always returns
non-NULL.
SSL_is_connection() returns 1 if the SSL object is not a QUIC stream SSL object
and 0 otherwise.
=head1 SEE ALSO
L<SSL_new(3)>, L<SSL_new_stream(3)>, L<SSL_accept_stream(3)>
=head1 HISTORY
These functions were added in OpenSSL 3.2.
=head1 COPYRIGHT
Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
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
L<https://www.openssl.org/source/license.html>.
=cut

93
doc/man3/SSL_get_conn_close_info.pod Normal file
View File

@ -0,0 +1,93 @@
=pod
=head1 NAME
SSL_get_conn_close_info - get information about why a QUIC connection was closed
=head1 SYNOPSIS
#include <openssl/ssl.h>
typedef struct ssl_conn_close_info_st {
uint64_t error_code;
char *reason;
size_t reason_len;
char is_local;
char is_transport;
} SSL_CONN_CLOSE_INFO;
int SSL_get_conn_close_info(SSL *ssl, SSL_CONN_CLOSE_INFO *info,
size_t info_len);
=head1 DESCRIPTION
The SSL_get_conn_close_info() function provides information about why and how a
QUIC connection was closed.
Connection closure information is written to B<*info>, which must be non-NULL.
B<info_len> must be set to B<sizeof(*info)>.
The following fields are set:
=over 4
=item B<error_code>
This is a 62-bit QUIC error code. It is either a 62-bit application error code
(if B<is_transport> is 0) or a 62-bit standard QUIC transport error code (if
B<is_transport> is 1).
=item B<reason>
If non-NULL, this is intended to be a UTF-8 textual string briefly describing
the reason for connection closure. The length of the reason string in bytes is
given in B<reason_len>. While, if non-NULL, OpenSSL guarantees that this string
will be zero terminated, consider that this buffer may originate from the
(untrusted) peer and thus may also contain zero bytes elsewhere. Therefore, use
of B<reason_len> is recommended.
While it is intended as per the QUIC protocol that this be a UTF-8 string, there
is no guarantee that this is the case for strings received from the peer.
=item B<is_local>
If 1, connection closure was locally triggered. This could be due to an
application request (e.g. if B<is_transport> is 0), or (if B<is_transport> is 1)
due to logic internal to the QUIC implementation (for example, if the peer
engages in a protocol violation, or an idle timeout occurs).
If 0, connection closure was remotely triggered.
=item B<is_transport>
If 1, connection closure was triggered for QUIC protocol reasons.
If 0, connection closure was triggered by the local or remote application.
=back
=head1 RETURN VALUES
SSL_get_conn_close_info() returns 1 on success and 0 on failure. This function
fails if called on a QUIC connection SSL object which has not yet been
terminated. It also fails if called on a QUIC stream SSL object or a non-QUIC
SSL object.
=head1 SEE ALSO
L<SSL_shutdown_ex(3)>
=head1 HISTORY
This function was added in OpenSSL 3.2.
=head1 COPYRIGHT
Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
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
L<https://www.openssl.org/source/license.html>.
=cut

98
doc/man3/SSL_get_stream_id.pod Normal file
View File

@ -0,0 +1,98 @@
=pod
=head1 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 - get QUIC
stream ID and stream type information
=head1 SYNOPSIS
#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);
=head1 DESCRIPTION
The SSL_get_stream_id() 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.
The SSL_get_stream_type() function identifies what operations can be performed
on the stream, and returns one of the following values:
=over 4
=item B<SSL_STREAM_TYPE_NONE>
The SSL object is a non-QUIC SSL object, or is a QUIC connection SSL object
without a default stream attached (see L<SSL_attach_stream(3)>).
=item B<SSL_STREAM_TYPE_BIDI>
The SSL object is a QUIC stream object (or QUIC connection SSL object with a
default stream attached), and that stream is a bidirectional QUIC stream.
=item B<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.
=item B<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.
=back
=head1 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
SSL_get_stream_type() to determine the stream type.
The SSL_get_stream_type() 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
L<SSL_stream_conclude(3)>, meaning that it can no longer be written to, but
SSL_get_stream_type() would still return B<SSL_STREAM_TYPE_WRITE>. The value
returned by SSL_get_stream_type() does not vary over the lifespan of a stream.
=head1 RETURN VALUES
SSL_get_stream_id() returns a QUIC stream ID, or B<UINT64_MAX> 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.
SSL_get_stream_type() returns one of the B<SSL_STREAM_TYPE> values.
=head1 SEE ALSO
L<SSL_attach_stream(3)>, L<SSL_new_stream(3)>, L<SSL_accept_stream(3)>
=head1 HISTORY
These functions were added in OpenSSL 3.2.
=head1 COPYRIGHT
Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
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
L<https://www.openssl.org/source/license.html>.
=cut

162
doc/man3/SSL_get_stream_read_state.pod Normal file
View File

@ -0,0 +1,162 @@
=pod
=head1 NAME
SSL_get_stream_read_state, SSL_get_stream_write_state,
SSL_get_stream_read_error_code, SSL_get_stream_write_error_code,
SSL_STREAM_STATE_NONE, SSL_STREAM_STATE_OK, SSL_STREAM_STATE_WRONG_DIR,
SSL_STREAM_STATE_FINISHED, SSL_STREAM_STATE_RESET_LOCAL,
SSL_STREAM_STATE_RESET_REMOTE, SSL_STREAM_STATE_CONN_CLOSED - get QUIC stream
state
=head1 SYNOPSIS
#include <openssl/ssl.h>
#define SSL_STREAM_STATE_NONE
#define SSL_STREAM_STATE_OK
#define SSL_STREAM_STATE_WRONG_DIR
#define SSL_STREAM_STATE_FINISHED
#define SSL_STREAM_STATE_RESET_LOCAL
#define SSL_STREAM_STATE_RESET_REMOTE
#define SSL_STREAM_STATE_CONN_CLOSED
int SSL_get_stream_read_state(SSL *ssl);
int SSL_get_stream_write_state(SSL *ssl);
int SSL_get_stream_read_error_code(SSL *ssl, uint64_t *app_error_code);
int SSL_get_stream_write_error_code(SSL *ssl, uint64_t *app_error_code);
=head1 DESCRIPTION
SSL_get_stream_read_state() and SSL_get_stream_write_state() retrieve the
overall state of the receiving and sending parts of a QUIC stream, respectively.
They both return one of the following values:
=over 4
=item SSL_STREAM_STATE_NONE
This value is returned if called on a non-QUIC SSL object, or on a QUIC
connection SSL object without a default stream attached.
=item SSL_STREAM_STATE_OK
This value is returned on a stream which has not been concluded and remains
healthy.
=item SSL_STREAM_STATE_WRONG_DIR
This value is returned if SSL_get_stream_read_state() is called on a
locally-initiated (and thus send-only) unidirectional stream, or, conversely, if
SSL_get_stream_write_state() is called on a remotely-initiated (and thus
receive-only) unidirectional stream.
=item SSL_STREAM_STATE_FINISHED
For SSL_get_stream_read_state(), this value is returned when the remote peer has
signalled the end of the receiving part of the stream. Note that there may still
be residual data available to read via L<SSL_read(3)> when this state is
returned.
For SSL_get_stream_write_state(), this value is returned when the local
application has concluded the stream using L<SSL_stream_conclude(3)>. Future
L<SSL_write(3)> calls will not succeed.
=item SSL_STREAM_STATE_RESET_LOCAL
This value is returned when the applicable stream part was reset by the local
application.
For SSL_get_stream_read_state(), this means that the receiving part of the
stream was aborted using a locally transmitted QUIC B<STOP_SENDING> frame. It
may or may not still be possible to obtain any residual data which remains to be
read by calling L<SSL_read(3)>.
For SSL_get_stream_write_state(), this means that the sending part of the stream
was aborted, for example because the application called L<SSL_stream_reset(3)>,
or because a QUIC stream SSL object with an un-concluded sending part was freed
using L<SSL_free(3)>. Calls to L<SSL_write(3)> will fail.
When this value is returned, the application error code which was signalled can
be obtained by calling SSL_get_stream_read_error_code() or
SSL_get_stream_write_error_code() as appropriate.
=item SSL_STREAM_STATE_RESET_REMOTE
This value is returned when the applicable stream part was reset by the remote
peer.
For SSL_get_stream_read_state(), this means that the peer sent a QUIC
B<RESET_STREAM> frame for the receiving part of the stream; the receiving part
of the stream was logically aborted by the peer.
For SSL_get_stream_write_state(), this means that the peer sent a QUIC
B<STOP_SENDING> frame for the sending part of the stream; the peer has indicated
that it does not wish to receive further data on the sending part of the stream.
Calls to L<SSL_write(3)> will fail.
When this value is returned, the application error code which was signalled can
be obtained by calling SSL_get_stream_read_error_code() or
SSL_get_stream_write_error_code() as appropriate.
=item SSL_STREAM_STATE_CONN_CLOSED
The QUIC connection to which the stream belongs was closed. You can obtain
information about the circumstances of this closure using
L<SSL_get_conn_close_info(3)>. There may still be residual data available to
read via L<SSL_read(3)> when this state is returned. Calls to L<SSL_write(3)>
will fail. SSL_get_stream_read_state() will return this state if and only if
SSL_get_stream_write_state() will also return this state.
=back
SSL_get_stream_read_error_code() and SSL_get_stream_write_error_code() provide
the application error code which was signalled during non-normal termination of
the receiving or sending parts of a stream, respectively. On success, the
application error code is written to B<*app_error_code>.
=head1 NOTES
If a QUIC connection is closed, the stream state for all streams transitions to
B<SSL_STREAM_STATE_CONN_CLOSED>, but no application error code can be retrieved
using SSL_get_stream_read_error_code() or SSL_get_stream_write_error_code(), as
the QUIC connection closure process does not cause an application error code to
be associated with each individual stream still existing at the time of
connection closure. However, you can obtain the overall error code associated
with the connection closure using L<SSL_get_conn_close_info(3)>.
=head1 RETURN VALUES
SSL_get_stream_read_state() and SSL_get_stream_write_state() return one of the
B<SSL_STREAM_STATE> values. If called on a non-QUIC SSL object, or a QUIC
connection SSL object without a default stream, B<SSL_STREAM_STATE_NONE> is
returned.
SSL_get_stream_read_error_code() and SSL_get_stream_write_error_code() return 1
on success and 0 if the stream was terminated normally. They return -1 on error,
for example if the stream is still healthy, was still healthy at the time of
connection closure, if called on a stream for which the respective stream part
does not exist (e.g. on a unidirectional stream), or if called on a non-QUIC
object or a QUIC connection SSL object without a default stream attached.
=head1 SEE ALSO
L<SSL_stream_conclude(3)>, L<SSL_stream_reset(3)>, L<SSL_new_stream(3)>,
L<SSL_accept_stream(3)>, L<SSL_get_conn_close_info(3)>
=head1 HISTORY
These functions were added in OpenSSL 3.2.
=head1 COPYRIGHT
Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
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
L<https://www.openssl.org/source/license.html>.
=cut

62
doc/man3/SSL_new_stream.pod Normal file
View File

@ -0,0 +1,62 @@
=pod
=head1 NAME
SSL_new_stream, SSL_STREAM_FLAG_UNI - create a new locally-initiated QUIC stream
=head1 SYNOPSIS
#include <openssl/ssl.h>
#define SSL_STREAM_FLAG_UNI (1U << 0)
SSL *SSL_new_stream(SSL *ssl, uint64_t flags);
=head1 DESCRIPTION
The SSL_new_stream() function, when passed a QUIC connection SSL object, creates
a new locally-initiated bidirectional or unidirectional QUIC stream and returns
the newly created QUIC stream SSL object.
If the B<SSL_STREAM_FLAG_UNI> flag is passed, a unidirectional stream is
created; else a bidirectional stream is created.
To retrieve the stream ID of the newly created stream, use
L<SSL_get_stream_id(3)>.
It is the caller's responsibility to free the QUIC stream SSL object using
L<SSL_free(3)>. The lifetime of the QUIC connection SSL object must exceed that
of the QUIC stream SSL object; in other words, the QUIC stream SSL object must
be freed first.
Once a stream has been created using SSL_new_stream(), it may be used in the
normal way using L<SSL_read(3)> and L<SSL_write(3)>.
This function can only be used to create stream objects for locally-initiated
streams. To accept incoming streams initiated by a peer, use
L<SSL_accept_stream(3)>.
=head1 RETURN VALUES
SSL_new_stream() returns a new stream object, or NULL on error.
This function fails if called on a QUIC stream SSL object or on a non-QUIC SSL
object.
=head1 SEE ALSO
L<SSL_accept_stream(3)>, L<SSL_free(3)>
=head1 HISTORY
SSL_new_stream() was added in OpenSSL 3.2.
=head1 COPYRIGHT
Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
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
L<https://www.openssl.org/source/license.html>.
=cut

108
doc/man3/SSL_set_incoming_stream_reject_policy.pod Normal file
View File

@ -0,0 +1,108 @@
=pod
=head1 NAME
SSL_set_incoming_stream_reject_policy, SSL_INCOMING_STREAM_REJECT_POLICY_AUTO,
SSL_INCOMING_STREAM_REJECT_POLICY_ACCEPT,
SSL_INCOMING_STREAM_REJECT_POLICY_REJECT - manage the QUIC incoming stream
rejection policy
=head1 SYNOPSIS
#include <openssl/ssl.h>
#define SSL_INCOMING_STREAM_REJECT_POLICY_AUTO
#define SSL_INCOMING_STREAM_REJECT_POLICY_ACCEPT
#define SSL_INCOMING_STREAM_REJECT_POLICY_REJECT
int SSL_set_incoming_stream_reject_policy(SSL *conn, int policy,
uint64_t app_error_code);
=head1 DESCRIPTION
SSL_set_incoming_stream_reject_policy() policy changes the incoming stream
rejection policy for a QUIC connection. Depending on the policy configured,
OpenSSL QUIC may automatically reject incoming streams initiated by the peer.
This is intended to ensure that legacy applications using single-stream
operation with a default stream on a QUIC connection SSL object are not passed
remotely-initiated streams by a peer which those applications are not prepared
to handle.
B<app_error_code> is an application error code which will be used in any QUIC
B<STOP_SENDING> or B<RESET_STREAM> frames generated to implement the rejection
policy. The default application error code is 0.
The valid values for B<policy> are:
=over 4
=item SSL_INCOMING_STREAM_REJECT_POLICY_AUTO
This is the default setting. Incoming streams are accepted according to the
following rules:
=over 4
=item *
An incoming stream is accepted if L<SSL_detach_stream(3)> has ever been called
on a QUIC connection SSL object, as the application is assumed to be
stream-aware in this case.
=item *
Otherwise, if the default stream mode (configured using
L<SSL_set_default_stream_mode(3)>) is set to
B<SSL_DEFAULT_STREAM_MODE_AUTO_BIDI> (the default) or
B<SSL_DEFAULT_STREAM_MODE_AUTO_UNI>, the incoming stream is rejected.
=item *
Otherwise (where the default stream mode is B<SSL_DEFAULT_STREAM_MODE_NONE>),
the application is assumed to be stream aware, and the incoming stream is
accepted.
=back
=item SSL_INCOMING_STREAM_REJECT_POLICY_ACCEPT
Always accept incoming streams, allowing them to be dequeued using
L<SSL_accept_stream(3)>.
=item SSL_INCOMING_STREAM_REJECT_POLICY_REJECT
Always reject incoming streams.
=back
Where an incoming stream is rejected, it is rejected immediately and it is not
possible to gain access to the stream using L<SSL_accept_stream(3)>. The stream
is rejected using QUIC B<STOP_SENDING> and B<RESET_STREAM> frames as
appropriate.
=head1 RETURN VALUES
Returns 1 on success and 0 on failure.
This function fails if called on a QUIC stream SSL object, or on a non-QUIC SSL
object.
=head1 SEE ALSO
L<SSL_attach_stream(3)>, L<SSL_detach_stream(3)>,
L<SSL_set_default_stream_mode(3)>, L<SSL_accept_stream(3)>
=head1 HISTORY
SSL_set_incoming_stream_reject_policy() was added in OpenSSL 3.2.
=head1 COPYRIGHT
Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
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
L<https://www.openssl.org/source/license.html>.
=cut

79
doc/man3/SSL_stream_reset.pod Normal file
View File

@ -0,0 +1,79 @@
=pod
=head1 NAME
SSL_stream_reset - reset a QUIC stream
=head1 SYNOPSIS
#include <openssl/ssl.h>
typedef struct ssl_stream_reset_args_st {
uint64_t quic_error_code;
} SSL_STREAM_RESET_ARGS;
int SSL_stream_reset(SSL *ssl,
const SSL_STREAM_RESET_ARGS *args,
size_t args_len);
=head1 DESCRIPTION
The SSL_stream_reset() function resets the send part of a QUIC stream when
called on a QUIC stream SSL object, or on a QUIC connection SSL object with a
default stream attached.
If B<args> is non-NULL, B<args_len> must be set to B<sizeof(*args)>.
B<quic_error_code> is an application-specified error code, which must be in the
range [0, 2**62-1]. If B<args> is NULL, a value of 0 is used.
Resetting a stream indicates to an application that the sending part of the
stream is terminating abnormally. When a stream is reset, the implementation
does not guarantee that any data already passed to L<SSL_write(3)> will be
received by the peer, and data already passed to L<SSL_write(3)> but not yet
transmitted may or may not be discarded. As such, you should only reset
a stream when the information transmitted on the stream no longer matters, for
example due to an error condition.
This function cannot be called on a unidirectional stream initiated by the peer,
as only the sending side of a stream can initiate a stream reset.
It is also possible to trigger a stream reset by calling L<SSL_free(3)>; see the
documentation for L<SSL_free(3)> for details.
The receiving part of the stream (for bidirectional streams) continues to
function normally.
=head1 NOTES
This function corresponds to the QUIC B<RESET_STREAM> frame.
=head1 RETURN VALUES
Returns 1 on success and 0 on failure.
This function fails if called on a QUIC connection SSL object without a default
stream attached, or on a non-QUIC SSL object.
After the first call to this function succeeds for a given stream,
subsequent calls succeed but are ignored. The application error code
used is that passed to the first successful call to this function.
=head1 SEE ALSO
L<SSL_free(3)>
=head1 HISTORY
SSL_stream_reset() was added in OpenSSL 3.2.
=head1 COPYRIGHT
Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved.
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
L<https://www.openssl.org/source/license.html>.
=cut

19
util/other.syms
View File

@ -646,6 +646,25 @@ SSL_want_x509_lookup define
SSLv23_client_method define
SSLv23_method define
SSLv23_server_method define
SSL_STREAM_FLAG_UNI define
SSL_STREAM_TYPE_NONE define
SSL_STREAM_TYPE_READ define
SSL_STREAM_TYPE_WRITE define
SSL_STREAM_TYPE_BIDI define
SSL_STREAM_STATE_NONE define
SSL_STREAM_STATE_WRONG_DIR define
SSL_STREAM_STATE_OK define
SSL_STREAM_STATE_FINISHED define
SSL_STREAM_STATE_RESET_LOCAL define
SSL_STREAM_STATE_RESET_REMOTE define
SSL_STREAM_STATE_CONN_CLOSED define
SSL_ACCEPT_STREAM_NO_BLOCK define
SSL_DEFAULT_STREAM_MODE_AUTO_BIDI define
SSL_DEFAULT_STREAM_MODE_AUTO_UNI define
SSL_DEFAULT_STREAM_MODE_NONE define
SSL_INCOMING_STREAM_REJECT_POLICY_ACCEPT define
SSL_INCOMING_STREAM_REJECT_POLICY_AUTO define
SSL_INCOMING_STREAM_REJECT_POLICY_REJECT define
TLS_DEFAULT_CIPHERSUITES define deprecated 3.0.0
X509_CRL_http_nbio define deprecated 3.0.0
X509_http_nbio define deprecated 3.0.0