From 40c457029e7861eeedae5c5ca3267e4b668ba205 Mon Sep 17 00:00:00 2001 From: Hugo Landau Date: Fri, 9 Feb 2024 12:52:09 +0000 Subject: QUIC: Add docs for SSL_VALUE_EVENT_HANDLING_MODE Reviewed-by: Matt Caswell Reviewed-by: Neil Horman Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/23535) --- doc/man3/SSL_get_value_uint.pod | 100 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 90 insertions(+), 10 deletions(-) diff --git a/doc/man3/SSL_get_value_uint.pod b/doc/man3/SSL_get_value_uint.pod index 5502559178..0be08e2e12 100644 --- a/doc/man3/SSL_get_value_uint.pod +++ b/doc/man3/SSL_get_value_uint.pod @@ -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 +=item B (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 +=item B (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 +=item B (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 +=item B (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 +=item B (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 (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 + +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 (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) when calls to I/O +functions such as L or L 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 (Explicit event handling) + +If set to 0, the explicit event handling model is used. Under this model, +B calls to I/O functions such as L or +L 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 as and when called for by the +QUIC implementation; see the L 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. + +=back + +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 QUIC stream SSL objects or for -other kinds of SSL object. +No configurable values are currently defined for non-QUIC SSL objects. =head1 RETURN VALUES -- cgit v1.2.3