diff options
author | Hugo Landau <hlandau@openssl.org> | 2023-05-08 19:42:40 +0100 |
---|---|---|
committer | Hugo Landau <hlandau@openssl.org> | 2023-05-12 14:47:15 +0100 |
commit | 5fc256cd6b991cf0fb5f7cb1da7be14c7e90653f (patch) | |
tree | f7d79b98c8ed5952afad8d89ab6378b2433d1e93 /doc | |
parent | 4f2d32d6b6b4b80ff5f55c5462b545516d252d11 (diff) |
QUIC MSST: Documentation fixes
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20765)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/SSL_accept_stream.pod | 3 | ||||
-rw-r--r-- | doc/man3/SSL_attach_stream.pod | 2 | ||||
-rw-r--r-- | doc/man3/SSL_get_conn_close_info.pod | 22 | ||||
-rw-r--r-- | doc/man3/SSL_get_stream_read_state.pod | 16 | ||||
-rw-r--r-- | doc/man3/SSL_set_incoming_stream_reject_policy.pod | 4 | ||||
-rw-r--r-- | doc/man3/SSL_stream_reset.pod | 6 |
6 files changed, 27 insertions, 26 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<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, +passing the flag B<SSL_ACCEPT_STREAM_NO_BLOCK> in I<flags>. 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<SSL_get_error(3)> 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<SSL_new(3)>, prior to initiating a connection. The argument -B<mode> may be one of the following options: +I<mode> 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<info_len> must be set to B<sizeof(*info)>. +Connection closure information is written to I<*info>, which must be non-NULL. +I<info_len> must be set to C<sizeof(*info)>. The following fields are set: =over 4 -=item B<error_code> +=item I<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). +(if I<is_transport> is 0) or a 62-bit standard QUIC transport error code (if +I<is_transport> is 1). -=item B<reason> +=item I<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 +given in I<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. +of I<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> +=item I<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) +application request (e.g. if I<is_transport> is 0), or (if I<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> +=item I<is_transport> 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<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 +=item B<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 +=item B<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 +=item B<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 @@ -64,7 +64,7 @@ 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 +=item B<SSL_STREAM_STATE_RESET_LOCAL> 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<SSL_STREAM_STATE_RESET_REMOTE> 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<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 @@ -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<app_error_code> is an application error code which will be used in any QUIC +I<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: +The valid values for I<policy> 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<args> is non-NULL, B<args_len> must be set to B<sizeof(*args)>. +If I<args> is non-NULL, I<args_len> must be set to C<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. +I<quic_error_code> is an application-specified error code, which must be in the +range [0, 2**62-1]. If I<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 |