mirror of https://github.com/openssl/openssl
QUIC MSST: Add documentation for new APIs
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
parent
9aaafc26e0
commit
1e4a9d882f
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue