QUIC Documentation: Rename SSL_tick, SSL_get_tick_timeout

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20879)
This commit is contained in:
Hugo Landau 2023-05-03 19:00:03 +01:00 committed by Tomas Mraz
parent 0bf7e94c10
commit f8503ede86
9 changed files with 67 additions and 65 deletions

View File

@ -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 \

View File

@ -92,7 +92,7 @@ not pollable for readability or writeability respectively.
=head1 SEE ALSO
L<SSL_tick(3)>, L<SSL_get_tick_timeout(3)>, L<SSL_get_rpoll_descriptor(3)>,
L<SSL_handle_events(3)>, L<SSL_get_event_timeout(3)>, L<SSL_get_rpoll_descriptor(3)>,
L<SSL_get_wpoll_descriptor(3)>, L<bio(7)>
=head1 HISTORY

View File

@ -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<DTLSv1_handle_timeout(3)>.
L<SSL_get_tick_timeout(3)> supersedes all use cases for this this function and
L<SSL_get_event_timeout(3)> 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<DTLSv1_handle_timeout(3)>, L<SSL_get_tick_timeout(3)>, L<ssl(7)>
L<DTLSv1_handle_timeout(3)>, L<SSL_get_event_timeout(3)>, L<ssl(7)>
=head1 COPYRIGHT

View File

@ -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<DTLSv1_get_timeout(3)> or L<SSL_get_tick_timeout(3)> to determine
Use L<DTLSv1_get_timeout(3)> or L<SSL_get_event_timeout(3)> 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<SSL_tick(3)> supersedes all use cases for this this function and may be used
instead of it.
L<SSL_handle_events(3)> 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<DTLSv1_get_timeout(3)>, L<SSL_tick(3)>, L<ssl(7)>
L<DTLSv1_get_timeout(3)>, L<SSL_handle_events(3)>, L<ssl(7)>
=head1 COPYRIGHT

View File

@ -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 <openssl/ssl.h>
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, I<tv->tv_sec> is set to -1,
@ -30,13 +30,14 @@ L<DTLSv1_get_timeout(3)> function. Note that this function differs from
L<DTLSv1_get_timeout(3)> 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<SSL_tick(3)>.
Once the timeout expires, SSL_handle_events() should be called to handle any
internal processing which is due; for more information, see
L<SSL_handle_events(3)>.
Note that SSL_get_tick_timeout() supersedes the older L<DTLSv1_get_timeout(3)>
Note that SSL_get_event_timeout() supersedes the older L<DTLSv1_get_timeout(3)>
function for all use cases.
=head1 RETURN VALUES
@ -45,11 +46,11 @@ Returns 1 on success and 0 on failure.
=head1 SEE ALSO
L<SSL_tick(3)>, L<DTLSv1_get_timeout(3)>, L<ssl(7)>
L<SSL_handle_events(3)>, L<DTLSv1_get_timeout(3)>, L<ssl(7)>
=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

View File

@ -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<BIO_get_rpoll_descriptor(3)>.
@ -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<SSL_get_tick_timeout(3)> to wait for network
these calls, in conjunction with L<SSL_get_event_timeout(3)> to wait for network
I/O conditions which allow the SSL object to perform useful work. When such a
condition arises, L<SSL_tick(3)> should be called.
condition arises, L<SSL_handle_events(3)> 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<SSL_tick(3)>, L<SSL_get_tick_timeout(3)>, L<ssl(7)>
L<SSL_handle_events(3)>, L<SSL_get_event_timeout(3)>, L<ssl(7)>
=head1 HISTORY

View File

@ -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 <openssl/ssl.h>
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<DTLSv1_handle_timeout(3)>. Since SSL_tick() handles a superset of the use
L<DTLSv1_handle_timeout(3)>. Since SSL_handle_events() handles a superset of the use
cases of L<DTLSv1_handle_timeout(3)>, 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<SSL_get_tick_timeout(3)>; ticking is not performed automatically by calls to
other SSL functions such as L<SSL_read(3)> or L<SSL_write(3)>. 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<SSL_get_event_timeout(3)>; ticking is not performed automatically by
calls to other SSL functions such as L<SSL_read(3)> or L<SSL_write(3)>. 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<SSL_get_tick_timeout(3)>.
when it next needs to call SSL_handle_events() for this purpose (if at all) by calling
L<SSL_get_event_timeout(3)>.
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<SSL_read(3)> or L<SSL_write(3)>)
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<DTLSv1_handle_timeout(3)> function
Note that SSL_handle_events() supersedes the older L<DTLSv1_handle_timeout(3)> function
for all use cases.
=head1 RETURN VALUES
@ -83,11 +84,11 @@ Returns 1 on success and 0 on failure.
=head1 SEE ALSO
L<SSL_get_tick_timeout(3)>, L<DTLSv1_handle_timeout(3)>, L<ssl(7)>
L<SSL_get_event_timeout(3)>, L<DTLSv1_handle_timeout(3)>, L<ssl(7)>
=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

View File

@ -37,7 +37,7 @@ on a SSL object which is not a QUIC connection SSL object.
=head1 SEE ALSO
L<OSSL_QUIC_client_method(3)>, L<SSL_tick(3)>, L<SSL_set_blocking_mode(3)>
L<OSSL_QUIC_client_method(3)>, L<SSL_handle_events(3)>, L<SSL_set_blocking_mode(3)>
=head1 HISTORY

View File

@ -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<SSL_tick(3)>.
L<SSL_handle_events(3)>.
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<SSL_tick(3)>, L<ssl(7)>
L<SSL_handle_events(3)>, L<ssl(7)>
=head1 HISTORY