From f8503ede86115b67e1552cf332d53fe43f0cb5bd Mon Sep 17 00:00:00 2001 From: Hugo Landau Date: Wed, 3 May 2023 19:00:03 +0100 Subject: [PATCH] QUIC Documentation: Rename SSL_tick, SSL_get_tick_timeout Reviewed-by: Matt Caswell Reviewed-by: Tim Hudson Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/20879) --- doc/build.info | 24 ++++----- doc/man3/BIO_get_rpoll_descriptor.pod | 2 +- doc/man3/DTLSv1_get_timeout.pod | 4 +- doc/man3/DTLSv1_handle_timeout.pod | 8 +-- ..._timeout.pod => SSL_get_event_timeout.pod} | 21 ++++---- doc/man3/SSL_get_rpoll_descriptor.pod | 18 +++---- .../{SSL_tick.pod => SSL_handle_events.pod} | 49 ++++++++++--------- doc/man3/SSL_inject_net_dgram.pod | 2 +- doc/man3/SSL_set_blocking_mode.pod | 4 +- 9 files changed, 67 insertions(+), 65 deletions(-) rename doc/man3/{SSL_get_tick_timeout.pod => SSL_get_event_timeout.pod} (64%) rename doc/man3/{SSL_tick.pod => SSL_handle_events.pod} (52%) diff --git a/doc/build.info b/doc/build.info index 624fcac5e9..52db908985 100644 --- a/doc/build.info +++ b/doc/build.info @@ -2535,6 +2535,10 @@ DEPEND[html/man3/SSL_get_error.html]=man3/SSL_get_error.pod GENERATE[html/man3/SSL_get_error.html]=man3/SSL_get_error.pod DEPEND[man/man3/SSL_get_error.3]=man3/SSL_get_error.pod GENERATE[man/man3/SSL_get_error.3]=man3/SSL_get_error.pod +DEPEND[html/man3/SSL_get_event_timeout.html]=man3/SSL_get_event_timeout.pod +GENERATE[html/man3/SSL_get_event_timeout.html]=man3/SSL_get_event_timeout.pod +DEPEND[man/man3/SSL_get_event_timeout.3]=man3/SSL_get_event_timeout.pod +GENERATE[man/man3/SSL_get_event_timeout.3]=man3/SSL_get_event_timeout.pod DEPEND[html/man3/SSL_get_extms_support.html]=man3/SSL_get_extms_support.pod GENERATE[html/man3/SSL_get_extms_support.html]=man3/SSL_get_extms_support.pod DEPEND[man/man3/SSL_get_extms_support.3]=man3/SSL_get_extms_support.pod @@ -2587,10 +2591,6 @@ DEPEND[html/man3/SSL_get_stream_read_state.html]=man3/SSL_get_stream_read_state. GENERATE[html/man3/SSL_get_stream_read_state.html]=man3/SSL_get_stream_read_state.pod DEPEND[man/man3/SSL_get_stream_read_state.3]=man3/SSL_get_stream_read_state.pod GENERATE[man/man3/SSL_get_stream_read_state.3]=man3/SSL_get_stream_read_state.pod -DEPEND[html/man3/SSL_get_tick_timeout.html]=man3/SSL_get_tick_timeout.pod -GENERATE[html/man3/SSL_get_tick_timeout.html]=man3/SSL_get_tick_timeout.pod -DEPEND[man/man3/SSL_get_tick_timeout.3]=man3/SSL_get_tick_timeout.pod -GENERATE[man/man3/SSL_get_tick_timeout.3]=man3/SSL_get_tick_timeout.pod DEPEND[html/man3/SSL_get_verify_result.html]=man3/SSL_get_verify_result.pod GENERATE[html/man3/SSL_get_verify_result.html]=man3/SSL_get_verify_result.pod DEPEND[man/man3/SSL_get_verify_result.3]=man3/SSL_get_verify_result.pod @@ -2603,6 +2603,10 @@ DEPEND[html/man3/SSL_group_to_name.html]=man3/SSL_group_to_name.pod GENERATE[html/man3/SSL_group_to_name.html]=man3/SSL_group_to_name.pod DEPEND[man/man3/SSL_group_to_name.3]=man3/SSL_group_to_name.pod GENERATE[man/man3/SSL_group_to_name.3]=man3/SSL_group_to_name.pod +DEPEND[html/man3/SSL_handle_events.html]=man3/SSL_handle_events.pod +GENERATE[html/man3/SSL_handle_events.html]=man3/SSL_handle_events.pod +DEPEND[man/man3/SSL_handle_events.3]=man3/SSL_handle_events.pod +GENERATE[man/man3/SSL_handle_events.3]=man3/SSL_handle_events.pod DEPEND[html/man3/SSL_in_init.html]=man3/SSL_in_init.pod GENERATE[html/man3/SSL_in_init.html]=man3/SSL_in_init.pod DEPEND[man/man3/SSL_in_init.3]=man3/SSL_in_init.pod @@ -2723,10 +2727,6 @@ DEPEND[html/man3/SSL_stream_reset.html]=man3/SSL_stream_reset.pod GENERATE[html/man3/SSL_stream_reset.html]=man3/SSL_stream_reset.pod DEPEND[man/man3/SSL_stream_reset.3]=man3/SSL_stream_reset.pod GENERATE[man/man3/SSL_stream_reset.3]=man3/SSL_stream_reset.pod -DEPEND[html/man3/SSL_tick.html]=man3/SSL_tick.pod -GENERATE[html/man3/SSL_tick.html]=man3/SSL_tick.pod -DEPEND[man/man3/SSL_tick.3]=man3/SSL_tick.pod -GENERATE[man/man3/SSL_tick.3]=man3/SSL_tick.pod DEPEND[html/man3/SSL_want.html]=man3/SSL_want.pod GENERATE[html/man3/SSL_want.html]=man3/SSL_want.pod DEPEND[man/man3/SSL_want.3]=man3/SSL_want.pod @@ -3525,6 +3525,7 @@ html/man3/SSL_get_conn_close_info.html \ html/man3/SSL_get_current_cipher.html \ html/man3/SSL_get_default_timeout.html \ html/man3/SSL_get_error.html \ +html/man3/SSL_get_event_timeout.html \ html/man3/SSL_get_extms_support.html \ html/man3/SSL_get_fd.html \ html/man3/SSL_get_peer_cert_chain.html \ @@ -3538,10 +3539,10 @@ html/man3/SSL_get_session.html \ html/man3/SSL_get_shared_sigalgs.html \ html/man3/SSL_get_stream_id.html \ html/man3/SSL_get_stream_read_state.html \ -html/man3/SSL_get_tick_timeout.html \ html/man3/SSL_get_verify_result.html \ html/man3/SSL_get_version.html \ html/man3/SSL_group_to_name.html \ +html/man3/SSL_handle_events.html \ html/man3/SSL_in_init.html \ html/man3/SSL_inject_net_dgram.html \ html/man3/SSL_key_update.html \ @@ -3572,7 +3573,6 @@ html/man3/SSL_shutdown.html \ html/man3/SSL_state_string.html \ html/man3/SSL_stream_conclude.html \ html/man3/SSL_stream_reset.html \ -html/man3/SSL_tick.html \ html/man3/SSL_want.html \ html/man3/SSL_write.html \ html/man3/TS_RESP_CTX_new.html \ @@ -4160,6 +4160,7 @@ man/man3/SSL_get_conn_close_info.3 \ man/man3/SSL_get_current_cipher.3 \ man/man3/SSL_get_default_timeout.3 \ man/man3/SSL_get_error.3 \ +man/man3/SSL_get_event_timeout.3 \ man/man3/SSL_get_extms_support.3 \ man/man3/SSL_get_fd.3 \ man/man3/SSL_get_peer_cert_chain.3 \ @@ -4173,10 +4174,10 @@ man/man3/SSL_get_session.3 \ man/man3/SSL_get_shared_sigalgs.3 \ man/man3/SSL_get_stream_id.3 \ man/man3/SSL_get_stream_read_state.3 \ -man/man3/SSL_get_tick_timeout.3 \ man/man3/SSL_get_verify_result.3 \ man/man3/SSL_get_version.3 \ man/man3/SSL_group_to_name.3 \ +man/man3/SSL_handle_events.3 \ man/man3/SSL_in_init.3 \ man/man3/SSL_inject_net_dgram.3 \ man/man3/SSL_key_update.3 \ @@ -4207,7 +4208,6 @@ man/man3/SSL_shutdown.3 \ man/man3/SSL_state_string.3 \ man/man3/SSL_stream_conclude.3 \ man/man3/SSL_stream_reset.3 \ -man/man3/SSL_tick.3 \ man/man3/SSL_want.3 \ man/man3/SSL_write.3 \ man/man3/TS_RESP_CTX_new.3 \ diff --git a/doc/man3/BIO_get_rpoll_descriptor.pod b/doc/man3/BIO_get_rpoll_descriptor.pod index 423ad1cdda..9de9f1fb01 100644 --- a/doc/man3/BIO_get_rpoll_descriptor.pod +++ b/doc/man3/BIO_get_rpoll_descriptor.pod @@ -92,7 +92,7 @@ not pollable for readability or writeability respectively. =head1 SEE ALSO -L, L, L, +L, L, L, L, L =head1 HISTORY diff --git a/doc/man3/DTLSv1_get_timeout.pod b/doc/man3/DTLSv1_get_timeout.pod index 8ef916415c..91ebd2d570 100644 --- a/doc/man3/DTLSv1_get_timeout.pod +++ b/doc/man3/DTLSv1_get_timeout.pod @@ -32,7 +32,7 @@ Once the timeout expires, DTLSv1_handle_timeout() should be called to handle any internal processing which is due; for more information, see L. -L supersedes all use cases for this this function and +L supersedes all use cases for this this function and may be used instead of it. =head1 RETURN VALUES @@ -43,7 +43,7 @@ Returns 0 on failure, or if no timeout is currently active. =head1 SEE ALSO -L, L, L +L, L, L =head1 COPYRIGHT diff --git a/doc/man3/DTLSv1_handle_timeout.pod b/doc/man3/DTLSv1_handle_timeout.pod index a188f08924..4a91fcfc2c 100644 --- a/doc/man3/DTLSv1_handle_timeout.pod +++ b/doc/man3/DTLSv1_handle_timeout.pod @@ -15,14 +15,14 @@ DTLSv1_handle_timeout - handle a pending timeout event for a DTLS SSL object DTLSv1_handle_timeout() handles any timeout events which have become pending on a DTLS SSL object. -Use L or L to determine +Use L or L to determine when to call DTLSv1_handle_timeout(). This function is only applicable to DTLS objects. It returns 0 if called on any other kind of SSL object. -L supersedes all use cases for this this function and may be used -instead of it. +L supersedes all use cases for this this function and may +be used instead of it. =head1 RETURN VALUES @@ -36,7 +36,7 @@ successfully. =head1 SEE ALSO -L, L, L +L, L, L =head1 COPYRIGHT diff --git a/doc/man3/SSL_get_tick_timeout.pod b/doc/man3/SSL_get_event_timeout.pod similarity index 64% rename from doc/man3/SSL_get_tick_timeout.pod rename to doc/man3/SSL_get_event_timeout.pod index 8decc35a62..5c02281aa2 100644 --- a/doc/man3/SSL_get_tick_timeout.pod +++ b/doc/man3/SSL_get_event_timeout.pod @@ -2,20 +2,20 @@ =head1 NAME -SSL_get_tick_timeout - determine when an SSL object next needs to be ticked +SSL_get_event_timeout - determine when an SSL object next needs to be ticked =head1 SYNOPSIS #include - int SSL_get_tick_timeout(SSL *s, struct timeval *tv); + int SSL_get_event_timeout(SSL *s, struct timeval *tv); =head1 DESCRIPTION -SSL_get_tick_timeout() determines when the SSL object next needs to perform +SSL_get_event_timeout() determines when the SSL object next needs to perform internal processing due to the passage of time. -Calling SSL_get_tick_timeout() results in I<*tv> being written with an amount of +Calling SSL_get_event_timeout() results in I<*tv> being written with an amount of time left before the SSL object needs to be ticked. If the SSL object needs to be ticked immediately, it is set to zero; if the SSL object currently does not need to be ticked at any point in the future, Itv_sec> is set to -1, @@ -30,13 +30,14 @@ L function. Note that this function differs from L in that the case where no timeout is active is considered a success condition. -Note that the value output by a call to SSL_get_tick_timeout() may change as a +Note that the value output by a call to SSL_get_event_timeout() may change as a result of other calls to the SSL object. -Once the timeout expires, SSL_tick() should be called to handle any internal -processing which is due; for more information, see L. +Once the timeout expires, SSL_handle_events() should be called to handle any +internal processing which is due; for more information, see +L. -Note that SSL_get_tick_timeout() supersedes the older L +Note that SSL_get_event_timeout() supersedes the older L function for all use cases. =head1 RETURN VALUES @@ -45,11 +46,11 @@ Returns 1 on success and 0 on failure. =head1 SEE ALSO -L, L, L +L, L, L =head1 HISTORY -The SSL_get_tick_timeout() function was added in OpenSSL 3.2. +The SSL_get_event_timeout() function was added in OpenSSL 3.2. =head1 COPYRIGHT diff --git a/doc/man3/SSL_get_rpoll_descriptor.pod b/doc/man3/SSL_get_rpoll_descriptor.pod index 475aac6a44..0d17bce698 100644 --- a/doc/man3/SSL_get_rpoll_descriptor.pod +++ b/doc/man3/SSL_get_rpoll_descriptor.pod @@ -20,7 +20,7 @@ network I/O can be performed The functions SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() can be used to determine when an SSL object which represents a QUIC connection can perform useful network I/O, so that an application using a QUIC connection SSL -object in nonblocking mode can determine when it should call SSL_tick(). +object in nonblocking mode can determine when it should call SSL_handle_events(). On success, these functions output poll descriptors. For more information on poll descriptors, see L. @@ -34,9 +34,9 @@ not interested in writing data to the network at the current time, SSL_net_write_desired() will return 0. The intention is that an application using QUIC in nonblocking mode can use -these calls, in conjunction with L to wait for network +these calls, in conjunction with L to wait for network I/O conditions which allow the SSL object to perform useful work. When such a -condition arises, L should be called. +condition arises, L should be called. In particular, the expected usage is as follows: @@ -44,18 +44,18 @@ In particular, the expected usage is as follows: =item * -SSL_tick() should be called whenever the timeout returned by -SSL_get_tick_timeout(3) (if any) expires +SSL_handle_events() should be called whenever the timeout returned by +SSL_get_event_timeout(3) (if any) expires =item * -If the last call to SSL_net_read_desired() returned 1, SSL_tick() should be called +If the last call to SSL_net_read_desired() returned 1, SSL_handle_events() should be called whenever the poll descriptor output by SSL_get_rpoll_descriptor() becomes readable. =item * -If the last call to SSL_net_write_desired() returned 1, SSL_tick() should be called +If the last call to SSL_net_write_desired() returned 1, SSL_handle_events() should be called whenever the poll descriptor output by SSL_get_wpoll_descriptor() becomes writable. @@ -64,7 +64,7 @@ writable. The return values of the SSL_net_read_desired() and SSL_net_write_desired() functions may change in response to any call to the SSL object other than SSL_net_read_desired(), SSL_net_write_desired(), SSL_get_rpoll_descriptor(), -SSL_get_wpoll_descriptor() and SSL_get_tick_timeout(). +SSL_get_wpoll_descriptor() and SSL_get_event_timeout(). These functions are not supported on non-QUIC SSL objects. @@ -74,7 +74,7 @@ These functions return 1 on success and 0 on failure. =head1 SEE ALSO -L, L, L +L, L, L =head1 HISTORY diff --git a/doc/man3/SSL_tick.pod b/doc/man3/SSL_handle_events.pod similarity index 52% rename from doc/man3/SSL_tick.pod rename to doc/man3/SSL_handle_events.pod index 66ee0c7e29..85184ec8eb 100644 --- a/doc/man3/SSL_tick.pod +++ b/doc/man3/SSL_handle_events.pod @@ -2,66 +2,67 @@ =head1 NAME -SSL_tick - advance asynchronous state machine and perform network I/O +SSL_handle_events - advance asynchronous state machine and perform network I/O =head1 SYNOPSIS #include - int SSL_tick(SSL *ssl); + int SSL_handle_events(SSL *ssl); =head1 DESCRIPTION -SSL_tick() performs any internal processing which is due on a SSL object. The -exact operations performed by SSL_tick() vary depending on what kind of protocol -is being used with the given SSL object. For example, SSL_tick() may handle +SSL_handle_events() performs any internal processing which is due on a SSL object. The +exact operations performed by SSL_handle_events() vary depending on what kind of protocol +is being used with the given SSL object. For example, SSL_handle_events() may handle timeout events which have become due, or may attempt, to the extent currently possible, to perform network I/O operations on one of the BIOs underlying the SSL object. -The primary use case for SSL_tick() is to allow an application which uses +The primary use case for SSL_handle_events() is to allow an application which uses OpenSSL in nonblocking mode to give OpenSSL an opportunity to handle timer events, or to respond to the availability of new data to be read from an underlying BIO, or to respond to the opportunity to write pending data to an underlying BIO. -SSL_tick() can be used only with the following types of SSL object: +SSL_handle_events() can be used only with the following types of SSL object: =over 4 =item DTLS SSL objects -Using SSL_tick() on an SSL object being used with a DTLS method allows timeout +Using SSL_handle_events() on an SSL object being used with a DTLS method allows timeout events to be handled properly. This is equivalent to a call to -L. Since SSL_tick() handles a superset of the use +L. Since SSL_handle_events() handles a superset of the use cases of L, it should be preferred for new applications which do not require support for OpenSSL 3.1 or older. -When using DTLS, an application must call SSL_tick() as indicated by calls to -L; ticking is not performed automatically by calls to -other SSL functions such as L or L. Note that this is -different to QUIC which also performs ticking implicitly; see below. +When using DTLS, an application must call SSL_handle_events() as indicated by +calls to L; ticking is not performed automatically by +calls to other SSL functions such as L or L. Note +that this is different to QUIC which also performs ticking implicitly; see +below. =item QUIC connection SSL objects -Using SSL_tick() on an SSL object which represents a QUIC connection allows +Using SSL_handle_events() on an SSL object which represents a QUIC connection allows timeout events to be handled properly, as well as incoming network data to be processed, and queued outgoing network data to be written, if the underlying BIO has the capacity to accept it. Ordinarily, when an application uses an SSL object in blocking mode, it does not -need to call SSL_tick() because OpenSSL performs ticking internally on an +need to call SSL_handle_events() because OpenSSL performs ticking internally on an automatic basis. However, if an application uses a QUIC connection in -nonblocking mode, it must at a minimum ensure that SSL_tick() is called +nonblocking mode, it must at a minimum ensure that SSL_handle_events() is called periodically to allow timeout events to be handled. An application can find out -when it next needs to call SSL_tick() for this purpose (if at all) by calling -L. +when it next needs to call SSL_handle_events() for this purpose (if at all) by calling +L. -Calling SSL_tick() on a QUIC connection SSL object being used in blocking mode +Calling SSL_handle_events() on a QUIC connection SSL object being used in blocking mode is not necessary unless no I/O calls (such as L or L) will be made to the object for a substantial period of time. So long as at least one call to the SSL object is blocking, no such call is needed. However, -SSL_tick() may optionally be used on a QUIC connection object if desired. +SSL_handle_events() may optionally be used on a QUIC connection object if desired. =begin comment @@ -71,10 +72,10 @@ TODO(QUIC): Update the above paragraph once we support thread assisted mode. =back -Calling SSL_tick() on any other kind of SSL object is a no-op. This is +Calling SSL_handle_events() on any other kind of SSL object is a no-op. This is considered a success case. -Note that SSL_tick() supersedes the older L function +Note that SSL_handle_events() supersedes the older L function for all use cases. =head1 RETURN VALUES @@ -83,11 +84,11 @@ Returns 1 on success and 0 on failure. =head1 SEE ALSO -L, L, L +L, L, L =head1 HISTORY -The SSL_tick() function was added in OpenSSL 3.2. +The SSL_handle_events() function was added in OpenSSL 3.2. =head1 COPYRIGHT diff --git a/doc/man3/SSL_inject_net_dgram.pod b/doc/man3/SSL_inject_net_dgram.pod index b859a316f0..7ff8facf64 100644 --- a/doc/man3/SSL_inject_net_dgram.pod +++ b/doc/man3/SSL_inject_net_dgram.pod @@ -37,7 +37,7 @@ on a SSL object which is not a QUIC connection SSL object. =head1 SEE ALSO -L, L, L +L, L, L =head1 HISTORY diff --git a/doc/man3/SSL_set_blocking_mode.pod b/doc/man3/SSL_set_blocking_mode.pod index ce4f3db96c..602045c0ef 100644 --- a/doc/man3/SSL_set_blocking_mode.pod +++ b/doc/man3/SSL_set_blocking_mode.pod @@ -37,7 +37,7 @@ provided to the SSL object are themselves configured in nonblocking mode. Where a QUIC connection SSL object is used in nonblocking mode, an application is responsible for ensuring that the SSL object is ticked regularly; see -L. +L. Blocking mode is disabled automatically if the application provides a QUIC connection SSL object with a network BIO which cannot support blocking mode. To @@ -55,7 +55,7 @@ SSL_get_blocking_mode() returns 1 if blocking is currently enabled. It returns =head1 SEE ALSO -L, L +L, L =head1 HISTORY