From 1e4a9d882f77977f518dcad418b05822efb172fe Mon Sep 17 00:00:00 2001 From: Hugo Landau Date: Tue, 18 Apr 2023 19:30:56 +0100 Subject: QUIC MSST: Add documentation for new APIs Reviewed-by: Matt Caswell Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/20765) --- doc/man3/SSL_accept_stream.pod | 74 ++++++++++ doc/man3/SSL_attach_stream.pod | 160 ++++++++++++++++++++ doc/man3/SSL_get0_connection.pod | 54 +++++++ doc/man3/SSL_get_conn_close_info.pod | 93 ++++++++++++ doc/man3/SSL_get_stream_id.pod | 98 +++++++++++++ doc/man3/SSL_get_stream_read_state.pod | 162 +++++++++++++++++++++ doc/man3/SSL_new_stream.pod | 62 ++++++++ doc/man3/SSL_set_incoming_stream_reject_policy.pod | 108 ++++++++++++++ doc/man3/SSL_stream_reset.pod | 79 ++++++++++ util/other.syms | 19 +++ 10 files changed, 909 insertions(+) create mode 100644 doc/man3/SSL_accept_stream.pod create mode 100644 doc/man3/SSL_attach_stream.pod create mode 100644 doc/man3/SSL_get0_connection.pod create mode 100644 doc/man3/SSL_get_conn_close_info.pod create mode 100644 doc/man3/SSL_get_stream_id.pod create mode 100644 doc/man3/SSL_get_stream_read_state.pod create mode 100644 doc/man3/SSL_new_stream.pod create mode 100644 doc/man3/SSL_set_incoming_stream_reject_policy.pod create mode 100644 doc/man3/SSL_stream_reset.pod diff --git a/doc/man3/SSL_accept_stream.pod b/doc/man3/SSL_accept_stream.pod new file mode 100644 index 0000000000..55c1868323 --- /dev/null +++ b/doc/man3/SSL_accept_stream.pod @@ -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 + + #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. + +This function will block if the QUIC connection SSL object is configured in +blocking mode (see L), but this may be bypassed by +passing the flag B in B. 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. + +=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, L, L + +=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. + +=cut diff --git a/doc/man3/SSL_attach_stream.pod b/doc/man3/SSL_attach_stream.pod new file mode 100644 index 0000000000..45e40c82e5 --- /dev/null +++ b/doc/man3/SSL_attach_stream.pod @@ -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 + + 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 and L +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 or L 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 is called first (before any call to +L) 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 is called before any call to +L, 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. 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 or L 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, prior to initiating a connection. The argument +B may be one of the following options: + +=over 4 + +=item SSL_DEFAULT_STREAM_MODE_AUTO_BIDI + +This is the default setting. If L is called prior to any call to +L, a bidirectional client-initiated stream is created and bound as +the default stream. If L is called prior to any call to +L, OpenSSL waits for an incoming stream from the peer (causing +L 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 is called first. To determine the +type of a stream after a call to L, use L. + +=item SSL_DEFAULT_STREAM_MODE_AUTO_UNI + +In this mode, if L is called prior to any call to L, +a unidirectional client-initiated stream is created and bound as the default +stream. The behaviour is otherwise identical to that of +B. The behaviour when L is +called prior to any call to L is unchanged. + +=item SSL_DEFAULT_STREAM_MODE_NONE + +Default stream creation is inhibited. This is the recommended mode of operation. +L and L calls cannot be made on the QUIC connection +SSL object directly. You must obtain streams using L or +L 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, or +if the QUIC connection SSL object previously had a default stream which was +detached using SSL_detach_stream(). + +L 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, L, L, +L + +=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. + +=cut diff --git a/doc/man3/SSL_get0_connection.pod b/doc/man3/SSL_get0_connection.pod new file mode 100644 index 0000000000..b6c21ad344 --- /dev/null +++ b/doc/man3/SSL_get0_connection.pod @@ -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 + + 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, L, L + +=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. + +=cut diff --git a/doc/man3/SSL_get_conn_close_info.pod b/doc/man3/SSL_get_conn_close_info.pod new file mode 100644 index 0000000000..5f9a2c3e38 --- /dev/null +++ b/doc/man3/SSL_get_conn_close_info.pod @@ -0,0 +1,93 @@ +=pod + +=head1 NAME + +SSL_get_conn_close_info - get information about why a QUIC connection was closed + +=head1 SYNOPSIS + + #include + + 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 must be set to B. + +The following fields are set: + +=over 4 + +=item B + +This is a 62-bit QUIC error code. It is either a 62-bit application error code +(if B is 0) or a 62-bit standard QUIC transport error code (if +B is 1). + +=item B + +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. 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 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 + +If 1, connection closure was locally triggered. This could be due to an +application request (e.g. if B is 0), or (if B 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 + +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 + +=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. + +=cut diff --git a/doc/man3/SSL_get_stream_id.pod b/doc/man3/SSL_get_stream_id.pod new file mode 100644 index 0000000000..b3ac31e3b2 --- /dev/null +++ b/doc/man3/SSL_get_stream_id.pod @@ -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 + + 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 + +The SSL object is a non-QUIC SSL object, or is a QUIC connection SSL object +without a default stream attached (see L). + +=item B + +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 + +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 + +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, meaning that it can no longer be written to, but +SSL_get_stream_type() would still return B. 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 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 values. + +=head1 SEE ALSO + +L, L, L + +=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. + +=cut diff --git a/doc/man3/SSL_get_stream_read_state.pod b/doc/man3/SSL_get_stream_read_state.pod new file mode 100644 index 0000000000..d04a1ef88a --- /dev/null +++ b/doc/man3/SSL_get_stream_read_state.pod @@ -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 + + #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 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. Future +L 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 frame. It +may or may not still be possible to obtain any residual data which remains to be +read by calling L. + +For SSL_get_stream_write_state(), this means that the sending part of the stream +was aborted, for example because the application called L, +or because a QUIC stream SSL object with an un-concluded sending part was freed +using L. Calls to L 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 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 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 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. There may still be residual data available to +read via L when this state is returned. Calls to L +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, 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. + +=head1 RETURN VALUES + +SSL_get_stream_read_state() and SSL_get_stream_write_state() return one of the +B values. If called on a non-QUIC SSL object, or a QUIC +connection SSL object without a default stream, B 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, L, L, +L, L + +=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. + +=cut diff --git a/doc/man3/SSL_new_stream.pod b/doc/man3/SSL_new_stream.pod new file mode 100644 index 0000000000..13f66474ab --- /dev/null +++ b/doc/man3/SSL_new_stream.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +SSL_new_stream, SSL_STREAM_FLAG_UNI - create a new locally-initiated QUIC stream + +=head1 SYNOPSIS + + #include + + #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 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. + +It is the caller's responsibility to free the QUIC stream SSL object using +L. 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 and L. + +This function can only be used to create stream objects for locally-initiated +streams. To accept incoming streams initiated by a peer, use +L. + +=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, L + +=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. + +=cut diff --git a/doc/man3/SSL_set_incoming_stream_reject_policy.pod b/doc/man3/SSL_set_incoming_stream_reject_policy.pod new file mode 100644 index 0000000000..3e859b26ad --- /dev/null +++ b/doc/man3/SSL_set_incoming_stream_reject_policy.pod @@ -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 + + #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 is an application error code which will be used in any QUIC +B or B frames generated to implement the rejection +policy. The default application error code is 0. + +The valid values for B 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 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) is set to +B (the default) or +B, the incoming stream is rejected. + +=item * + +Otherwise (where the default stream mode is B), +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. + +=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. The stream +is rejected using QUIC B and B 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, L, +L, L + +=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. + +=cut diff --git a/doc/man3/SSL_stream_reset.pod b/doc/man3/SSL_stream_reset.pod new file mode 100644 index 0000000000..3f9159024a --- /dev/null +++ b/doc/man3/SSL_stream_reset.pod @@ -0,0 +1,79 @@ +=pod + +=head1 NAME + +SSL_stream_reset - reset a QUIC stream + +=head1 SYNOPSIS + + #include + + 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 is non-NULL, B must be set to B. + +B is an application-specified error code, which must be in the +range [0, 2**62-1]. If B 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 will be +received by the peer, and data already passed to L 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; see the +documentation for L for details. + +The receiving part of the stream (for bidirectional streams) continues to +function normally. + +=head1 NOTES + +This function corresponds to the QUIC B 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 + +=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. + +=cut diff --git a/util/other.syms b/util/other.syms index daa3be067f..cecfe4d742 100644 --- a/util/other.syms +++ b/util/other.syms @@ -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 -- cgit v1.2.1