mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-03-31 20:10:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

QUIC: Rename SSL_tick etc. in man(7) docs

Browse Source 
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-18 13:07:00 +01:00 committed by Tomas Mraz
parent 06fb6b9717
commit 041d48c963
2 changed files with 38 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
doc/man7/openssl-quic.pod
View File

@ -401,23 +401,23 @@ it must add a call to L<SSL_set_blocking_mode(3)> to disable blocking mode.
If your application does not choose to use thread assisted mode, it must ensure
that it calls an I/O function on the SSL object (for example, L<SSL_read(3)> or
L<SSL_write(3)>), or the new function L<SSL_tick(3)>, regularly. If the SSL
object is used in blocking mode, an ongoing blocking call to an I/O function
L<SSL_write(3)>), or the new function L<SSL_handle_events(3)>, regularly. If the
SSL object is used in blocking mode, an ongoing blocking call to an I/O function
satisfies this requirement. This is required to ensure that timer events
required by QUIC are handled in a timely fashion.
Most applications will service the SSL object by calling L<SSL_read(3)> or
L<SSL_write(3)> regularly. If an application does not do this, it should ensure
that L<SSL_tick(3)> is called regularly.
that L<SSL_handle_events(3)> is called regularly.
L<SSL_get_tick_timeout(3)> can be used to determine when L<SSL_tick(3)> must
next be called.
L<SSL_get_event_timeout(3)> can be used to determine when
L<SSL_handle_events(3)> must next be called.
If the SSL object is being used with an underlying network BIO which is pollable
(such as L<BIO_s_datagram(3)>), the application can use
L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)> to obtain
resources which can be used to determine when L<SSL_tick(3)> should be called
due to network I/O.
resources which can be used to determine when L<SSL_handle_events(3)> should be
called due to network I/O.
Applications which use thread assisted mode do not need to be concerned
with this requirement, as the QUIC implementation ensures timeout events
@ -494,24 +494,24 @@ The following SSL APIs are new but relevant to both QUIC and DTLS:
=over 4
=item L<SSL_get_tick_timeout(3)>
=item L<SSL_get_event_timeout(3)>
Determines when the QUIC implementation should next be woken up via a call to
L<SSL_tick(3)> (or another I/O function such as L<SSL_read(3)> or
L<SSL_handle_events(3)> (or another I/O function such as L<SSL_read(3)> or
L<SSL_write(3)>), if ever.
This can also be used with DTLS and supersedes L<DTLSv1_get_timeout(3)> for new
usage.
=item L<SSL_tick(3)>
=item L<SSL_handle_events(3)>
This is a non-specific I/O operation which makes a best effort attempt to
perform any pending I/O or timeout processing. It can be used to advance the
QUIC state machine by processing incoming network traffic, generating outgoing
network traffic and handling any expired timeout events. Most other I/O
functions on an SSL object, such as L<SSL_read(3)> and L<SSL_write(3)>
implicitly perform ticking of the SSL object, so calling this function is only
needed if no other I/O function is to be called.
implicitly perform event handling on the SSL object, so calling this function is
only needed if no other I/O function is to be called.
This can also be used with DTLS and supersedes L<DTLSv1_handle_timeout(3)> for
new usage.
@ -535,8 +535,8 @@ These functions facilitate operation in nonblocking mode.
When an SSL object is being used with an underlying network read BIO which
supports polling, L<SSL_get_rpoll_descriptor(3)> outputs an OS resource which
can be used to synchronise on network readability events which should result in
a call to L<SSL_tick(3)>. L<SSL_get_wpoll_descriptor(3)> works in an analogous
fashion for the underlying network write BIO.
a call to L<SSL_handle_events(3)>. L<SSL_get_wpoll_descriptor(3)> works in an
analogous fashion for the underlying network write BIO.
The poll descriptors provided by these functions need only be used when
L<SSL_net_read_desired(3)> and L<SSL_net_write_desired(3)> return 1, respectively.
@ -770,7 +770,7 @@ synchronisation.
It should call L<SSL_net_read_desired(3)> and L<SSL_net_write_desired(3)> to determine
whether the QUIC implementation is currently interested in readability and
writability events on the underlying network BIO which was provided, and call
L<SSL_get_tick_timeout(3)> to determine if any timeout event will become
L<SSL_get_event_timeout(3)> to determine if any timeout event will become
applicable in the future.
=item
@ -791,11 +791,11 @@ The poll descriptor returned by L<SSL_get_wpoll_descriptor(3)> becomes writable
=item
The timeout returned by L<SSL_get_tick_timeout(3)> (if any) expires.
The timeout returned by L<SSL_get_event_timeout(3)> (if any) expires.
=back
Once any of these events occurs, L<SSL_tick(3)> should be called.
Once any of these events occurs, L<SSL_handle_events(3)> should be called.
=back
@ -803,31 +803,32 @@ Once any of these events occurs, L<SSL_tick(3)> should be called.
If the network read and write BIOs provided were not pollable (for example, in
the case of L<BIO_s_dgram_pair(3)>), the application is responsible for managing
and synchronising network I/O. It should call L<SSL_tick(3)> after it writes
data to a L<BIO_s_dgram_pair(3)> or otherwise takes action so that the QUIC
implementation can read new datagrams via a call to L<BIO_recvmmsg(3)> on the
underlying network BIO. The QUIC implementation may output datagrams via a call
to L<BIO_sendmmsg(3)> and the application is responsible for ensuring these are
transmitted.
and synchronising network I/O. It should call L<SSL_handle_events(3)> after it
writes data to a L<BIO_s_dgram_pair(3)> or otherwise takes action so that the
QUIC implementation can read new datagrams via a call to L<BIO_recvmmsg(3)> on
the underlying network BIO. The QUIC implementation may output datagrams via a
call to L<BIO_sendmmsg(3)> and the application is responsible for ensuring these
are transmitted.
The application must call L<SSL_get_tick_timeout(3)> after every call to
L<SSL_tick(3)> (or another I/O function on the SSL object), and ensure that a
call to L<SSL_tick(3)> is performed after the specified timeout (if any).
The application must call L<SSL_get_event_timeout(3)> after every call to
L<SSL_handle_events(3)> (or another I/O function on the SSL object), and ensure
that a call to L<SSL_handle_events(3)> is performed after the specified timeout
(if any).
=back
=head1 SEE ALSO
L<SSL_tick(3)>, L<SSL_get_tick_timeout(3)>, L<SSL_net_read_desired(3)>,
L<SSL_net_write_desired(3)>, L<SSL_get_rpoll_descriptor(3)>,
L<SSL_get_wpoll_descriptor(3)>, L<SSL_set_blocking_mode(3)>,
L<SSL_shutdown_ex(3)>, L<SSL_set_initial_peer_addr(3)>,
L<SSL_stream_conclude(3)>, L<SSL_stream_reset(3)>,
L<SSL_get_stream_read_state(3)>, L<SSL_get_stream_read_error_code(3)>,
L<SSL_get_conn_close_info(3)>, L<SSL_get0_connection(3)>,
L<SSL_get_stream_type(3)>, L<SSL_get_stream_id(3)>, L<SSL_new_stream(3)>,
L<SSL_accept_stream(3)>, L<SSL_set_incoming_stream_policy(3)>,
L<SSL_set_default_stream_mode(3)>
L<SSL_handle_events(3)>, L<SSL_get_event_timeout(3)>,
L<SSL_net_read_desired(3)>, L<SSL_net_write_desired(3)>,
L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)>,
L<SSL_set_blocking_mode(3)>, L<SSL_shutdown_ex(3)>,
L<SSL_set_initial_peer_addr(3)>, L<SSL_stream_conclude(3)>,
L<SSL_stream_reset(3)>, L<SSL_get_stream_read_state(3)>,
L<SSL_get_stream_read_error_code(3)>, L<SSL_get_conn_close_info(3)>,
L<SSL_get0_connection(3)>, L<SSL_get_stream_type(3)>, L<SSL_get_stream_id(3)>,
L<SSL_new_stream(3)>, L<SSL_accept_stream(3)>,
L<SSL_set_incoming_stream_policy(3)>, L<SSL_set_default_stream_mode(3)>
=head1 COPYRIGHT

2
test/quic_newcid_test.c
View File

@ -112,7 +112,7 @@ static int test_ncid_frame(int fail)
goto err;
ossl_quic_tserver_tick(qtserv);
if (!TEST_true(SSL_tick(cssl)))
if (!TEST_true(SSL_handle_events(cssl)))
goto err;
if (!TEST_int_eq(SSL_read(cssl, buf, sizeof(buf)), msglen))