QUIC: Add docs for SSL_VALUE_EVENT_HANDLING_MODE

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)

1 files 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<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
+
+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