From 5fc256cd6b991cf0fb5f7cb1da7be14c7e90653f Mon Sep 17 00:00:00 2001 From: Hugo Landau Date: Mon, 8 May 2023 19:42:40 +0100 Subject: QUIC MSST: Documentation fixes Reviewed-by: Matt Caswell Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/20765) --- doc/man3/SSL_accept_stream.pod | 3 ++- doc/man3/SSL_attach_stream.pod | 2 +- doc/man3/SSL_get_conn_close_info.pod | 22 +++++++++++----------- doc/man3/SSL_get_stream_read_state.pod | 16 ++++++++-------- doc/man3/SSL_set_incoming_stream_reject_policy.pod | 4 ++-- doc/man3/SSL_stream_reset.pod | 6 +++--- include/internal/quic_stream_map.h | 2 +- 7 files changed, 28 insertions(+), 27 deletions(-) diff --git a/doc/man3/SSL_accept_stream.pod b/doc/man3/SSL_accept_stream.pod index 430b3dd364..e72af899b3 100644 --- a/doc/man3/SSL_accept_stream.pod +++ b/doc/man3/SSL_accept_stream.pod @@ -31,7 +31,7 @@ SSL object; for more information, see 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, +passing the flag B in I. If this flag is set, this function never blocks. SSL_get_accept_stream_queue_len() returns the number of incoming streams @@ -59,6 +59,7 @@ man(7) pages are merged 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, or if called on a SSL object other than a QUIC connection SSL object. +L can be used to obtain further information in this case. SSL_get_accept_stream_queue_len() returns the number of incoming streams currently waiting in the accept queue, or 0 if called on a SSL object other than diff --git a/doc/man3/SSL_attach_stream.pod b/doc/man3/SSL_attach_stream.pod index 8f837acc6e..298000ac2e 100644 --- a/doc/man3/SSL_attach_stream.pod +++ b/doc/man3/SSL_attach_stream.pod @@ -87,7 +87,7 @@ 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: +I may be one of the following options: =over 4 diff --git a/doc/man3/SSL_get_conn_close_info.pod b/doc/man3/SSL_get_conn_close_info.pod index 5f9a2c3e38..9fbf6fe9bc 100644 --- a/doc/man3/SSL_get_conn_close_info.pod +++ b/doc/man3/SSL_get_conn_close_info.pod @@ -24,41 +24,41 @@ SSL_get_conn_close_info - get information about why a QUIC connection was closed 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. +Connection closure information is written to I<*info>, which must be non-NULL. +I must be set to C. The following fields are set: =over 4 -=item B +=item I 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). +(if I is 0) or a 62-bit standard QUIC transport error code (if +I is 1). -=item B +=item I 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 +given in I. 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. +of I 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 +=item I 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) +application request (e.g. if I is 0), or (if I 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 +=item I If 1, connection closure was triggered for QUIC protocol reasons. diff --git a/doc/man3/SSL_get_stream_read_state.pod b/doc/man3/SSL_get_stream_read_state.pod index d04a1ef88a..7373e1dbff 100644 --- a/doc/man3/SSL_get_stream_read_state.pod +++ b/doc/man3/SSL_get_stream_read_state.pod @@ -36,24 +36,24 @@ They both return one of the following values: =over 4 -=item SSL_STREAM_STATE_NONE +=item B 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 +=item B This value is returned on a stream which has not been concluded and remains healthy. -=item SSL_STREAM_STATE_WRONG_DIR +=item B 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 +=item B 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 @@ -64,7 +64,7 @@ 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 +=item B This value is returned when the applicable stream part was reset by the local application. @@ -83,7 +83,7 @@ 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 +=item B This value is returned when the applicable stream part was reset by the remote peer. @@ -101,7 +101,7 @@ 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 +=item B The QUIC connection to which the stream belongs was closed. You can obtain information about the circumstances of this closure using @@ -115,7 +115,7 @@ SSL_get_stream_write_state() will also return this state. 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>. +application error code is written to I<*app_error_code>. =head1 NOTES diff --git a/doc/man3/SSL_set_incoming_stream_reject_policy.pod b/doc/man3/SSL_set_incoming_stream_reject_policy.pod index 3e859b26ad..dfc3dffb03 100644 --- a/doc/man3/SSL_set_incoming_stream_reject_policy.pod +++ b/doc/man3/SSL_set_incoming_stream_reject_policy.pod @@ -28,11 +28,11 @@ 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 +I 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: +The valid values for I are: =over 4 diff --git a/doc/man3/SSL_stream_reset.pod b/doc/man3/SSL_stream_reset.pod index 3f9159024a..e2f6fd35bc 100644 --- a/doc/man3/SSL_stream_reset.pod +++ b/doc/man3/SSL_stream_reset.pod @@ -22,10 +22,10 @@ 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. +If I is non-NULL, I must be set to C. -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. +I is an application-specified error code, which must be in the +range [0, 2**62-1]. If I 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 diff --git a/include/internal/quic_stream_map.h b/include/internal/quic_stream_map.h index 920f3144b4..1af0c57d1e 100644 --- a/include/internal/quic_stream_map.h +++ b/include/internal/quic_stream_map.h @@ -69,7 +69,7 @@ struct quic_stream_st { /* * Application Error Code (AEC) for incoming RESET_STREAM frame. - * This is only valid if peer_reset_stream is 1. + * This is only valid if peer_reset_stream is 1. */ uint64_t peer_reset_stream_aec; -- cgit v1.2.1