mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-01-18 13:44:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

QUIC: Add docs for SSL_VALUE_EVENT_HANDLING_MODE

Browse Source 
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/23535)
This commit is contained in:
Hugo Landau 2024-02-09 12:52:09 +00:00 committed by Tomas Mraz
parent e5313f2048
commit 40c457029e
1 changed files with 90 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
doc/man3/SSL_get_value_uint.pod
View File

@ -11,8 +11,14 @@ SSL_get_quic_stream_uni_remote_avail, SSL_VALUE_CLASS_GENERIC,
SSL_VALUE_CLASS_FEATURE_REQUEST, SSL_VALUE_CLASS_FEATURE_PEER_REQUEST,
SSL_VALUE_CLASS_FEATURE_NEGOTIATED, SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL,
SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL, SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL,
SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL, SSL_VALUE_QUIC_IDLE_TIMEOUT - manage
negotiable features and configuration values for a SSL object
SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL, SSL_VALUE_QUIC_IDLE_TIMEOUT,
SSL_VALUE_EVENT_HANDLING_MODE,
SSL_VALUE_EVENT_HANDLING_MODE_INHERIT,
SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT,
SSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT,
SSL_get_event_handling_mode,
SSL_set_event_handling_mode -
manage negotiable features and configuration values for a SSL object
=head1 SYNOPSIS
@ -34,6 +40,11 @@ negotiable features and configuration values for a SSL object
#define SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL
#define SSL_VALUE_QUIC_IDLE_TIMEOUT
#define SSL_VALUE_EVENT_HANDLING_MODE
#define SSL_VALUE_EVENT_HANDLING_MODE_INHERIT
#define SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT
#define SSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT
The following convenience macros can also be used:
int SSL_get_generic_value_uint(SSL *ssl, uint32_t id, uint64_t *value);
@ -50,6 +61,9 @@ The following convenience macros can also be used:
int SSL_get_quic_stream_uni_local_avail(SSL *ssl, uint64_t *value);
int SSL_get_quic_stream_uni_remote_avail(SSL *ssl, uint64_t *value);
int SSL_get_event_handling_mode(SSL *ssl, uint64_t *value);
int SSL_set_event_handling_mode(SSL *ssl, uint64_t value);
=head1 DESCRIPTION
SSL_get_value_uint() and SSL_set_value_uint() provide access to configurable
@ -119,11 +133,13 @@ SSL_get_feature_negotiated_uint() for brevity.
=head1 CONFIGURABLE VALUES FOR QUIC CONNECTIONS
The following configurable values are supported for QUIC connection SSL objects:
The following configurable values are supported for QUIC SSL objects. Whether a
value is supported for a QUIC connection SSL object or a QUIC stream SSL object
is indicated in the heading for each value:
=over 4
=item B<SSL_VALUE_QUIC_IDLE_TIMEOUT>
=item B<SSL_VALUE_QUIC_IDLE_TIMEOUT> (connection object)
Negotiated feature value. This configures the desired QUIC idle timeout in
milliseconds, where 0 represents a lack of an idle timeout. This feature can
@ -133,7 +149,7 @@ changed.
This release of OpenSSL uses a default value of 30 seconds. This default value
may change between releases of OpenSSL.
=item B<SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL>
=item B<SSL_VALUE_QUIC_STREAM_BIDI_LOCAL_AVAIL> (connection object)
Generic read-only statistical value. The number of bidirectional,
locally-initiated streams available to be created (but not yet created). For
@ -144,7 +160,7 @@ block or fail due to backpressure.
Can be queried using the convenience macro
SSL_get_quic_stream_bidi_local_avail().
=item B<SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL>
=item B<SSL_VALUE_QUIC_STREAM_UNI_LOCAL_AVAIL> (connection object)
As above, but provides the number of unidirectional, locally-initiated streams
available to be created (but not yet created).
@ -152,7 +168,7 @@ available to be created (but not yet created).
Can be queried using the convenience macro
SSL_get_quic_stream_uni_local_avail().
=item B<SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL>
=item B<SSL_VALUE_QUIC_STREAM_BIDI_REMOTE_AVAIL> (connection object)
As above, but provides the number of bidirectional, remotely-initiated streams
available to be created (but not yet created) by the peer. This represents the
@ -162,7 +178,7 @@ of QUIC stream creation flow control.
Can be queried using the convenience macro
SSL_get_quic_stream_bidi_remote_avail().
=item B<SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL>
=item B<SSL_VALUE_QUIC_STREAM_UNI_REMOTE_AVAIL> (connection object)
As above, but provides the number of unidirectional, remotely-initiated streams
available to be created (but not yet created).
@ -170,10 +186,74 @@ available to be created (but not yet created).
Can be queried using the convenience macro
SSL_get_quic_stream_uni_remote_avail().
=item B<SSL_VALUE_EVENT_HANDLING_MODE> (connection or stream object)
Generic value. This is an integer value which takes one of the following values,
and determines the event handling mode in use:
=over 4
=item B<SSL_VALUE_EVENT_HANDLING_MODE_INHERIT>
When set, the event handling mode used is inherited from the value set on the
parent connection (for a stream), or, for a connection, defaults to the implicit
event handling model.
When a new connection is created, or a new stream is created or accepted, it
defaults to this setting.
=item B<SSL_VALUE_EVENT_HANDLING_MODE_IMPLICIT> (Implicit event handling)
If set to this value (the default), the implicit event handling model is used.
Under this model, QUIC objects will automatically perform background event
processing (equivalent to a call to L<SSL_handle_events(3)>) when calls to I/O
functions such as L<SSL_read_ex(3)> or L<SSL_write_ex(3)> are made on a QUIC SSL
object. This helps to maintain the health of the QUIC connection and ensures
that incoming datagrams and timeout events are processed.
=item B<SSL_VALUE_EVENT_HANDLING_MODE_EXPLICIT> (Explicit event handling)
If set to 0, the explicit event handling model is used. Under this model,
B<nonblocking> calls to I/O functions such as L<SSL_read_ex(3)> or
L<SSL_write_ex(3)> do not result in the automatic processing of QUIC events. Any
new incoming network traffic is not handled; no new outgoing network traffic is
generated, and pending timeout events are not processed. This allows an
application to obtain greater control over the circumstances in which QUIC event
processing occurs. If this event handling model is used, it is the application's
responsibility to call L<SSL_handle_events(3)> as and when called for by the
QUIC implementation; see the L<SSL_get_rpoll_descriptor(3)> man page for more
information.
Selecting this model does not affect the operation of blocking I/O calls, which
will continue to use the implicit event handling model. Therefore, applications
using this model will generally want to disable blocking operation using
L<SSL_set_blocking_mode(3)>.
=back
No configurable values are currently defined for QUIC stream SSL objects or for
other kinds of SSL object.
Can be configured using the convenience macros SSL_get_event_handling_mode() and
SSL_set_event_handling_mode().
A call to SSL_set_value_uint() which causes this value to switch back to the
implicit event handling model does not in itself cause implicit event handling
to occur; such handling will occur on the next I/O API call. Equally, a call to
SSL_set_value_uint() which causes this value to switch to the explicit event
handling model will not cause event handling to occur before making that
transition.
This value controls whether implicit event handling occurs when making an I/O
API call on the SSL object it is set on. However, event processing is not
confined to state which relates to only that object. For example, if you
configure explicit event handling on QUIC stream SSL object "A" and configure
implicit event handling on QUIC stream SSL object "B", a call to an I/O function
on "B" may result in state changes to "A". In other words, if event handling
does happen as a result of an API call to an object related to a connection,
processing of background events (for example, received QUIC network traffic) may
also affect the state of any other object related to a connection.
=back
No configurable values are currently defined for non-QUIC SSL objects.
=head1 RETURN VALUES