openssl
/
openssl
mirror of https://github.com/openssl/openssl
1
0
Fork 0
Code Issues Releases Wiki Activity

QUIC CSM: Tweak docs for tick functions, add DTLSv1 docs 

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19703)
This commit is contained in:
Hugo Landau 2023-01-09 11:18:06 +00:00
parent 75b2920a21
commit 8ccc567ef0
6 changed files with 146 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/build.info
View File

@ -1003,6 +1003,14 @@ DEPEND[html/man3/DTLS_set_timer_cb.html]=man3/DTLS_set_timer_cb.pod
GENERATE[html/man3/DTLS_set_timer_cb.html]=man3/DTLS_set_timer_cb.pod
DEPEND[man/man3/DTLS_set_timer_cb.3]=man3/DTLS_set_timer_cb.pod
GENERATE[man/man3/DTLS_set_timer_cb.3]=man3/DTLS_set_timer_cb.pod
DEPEND[html/man3/DTLSv1_get_timeout.html]=man3/DTLSv1_get_timeout.pod
GENERATE[html/man3/DTLSv1_get_timeout.html]=man3/DTLSv1_get_timeout.pod
DEPEND[man/man3/DTLSv1_get_timeout.3]=man3/DTLSv1_get_timeout.pod
GENERATE[man/man3/DTLSv1_get_timeout.3]=man3/DTLSv1_get_timeout.pod
DEPEND[html/man3/DTLSv1_handle_timeout.html]=man3/DTLSv1_handle_timeout.pod
GENERATE[html/man3/DTLSv1_handle_timeout.html]=man3/DTLSv1_handle_timeout.pod
DEPEND[man/man3/DTLSv1_handle_timeout.3]=man3/DTLSv1_handle_timeout.pod
GENERATE[man/man3/DTLSv1_handle_timeout.3]=man3/DTLSv1_handle_timeout.pod
DEPEND[html/man3/DTLSv1_listen.html]=man3/DTLSv1_listen.pod
GENERATE[html/man3/DTLSv1_listen.html]=man3/DTLSv1_listen.pod
DEPEND[man/man3/DTLSv1_listen.3]=man3/DTLSv1_listen.pod
@ -3082,6 +3090,8 @@ html/man3/DSA_sign.html \
html/man3/DSA_size.html \
html/man3/DTLS_get_data_mtu.html \
html/man3/DTLS_set_timer_cb.html \
html/man3/DTLSv1_get_timeout.html \
html/man3/DTLSv1_handle_timeout.html \
html/man3/DTLSv1_listen.html \
html/man3/ECDSA_SIG_new.html \
html/man3/ECDSA_sign.html \
@ -3702,6 +3712,8 @@ man/man3/DSA_sign.3 \
man/man3/DSA_size.3 \
man/man3/DTLS_get_data_mtu.3 \
man/man3/DTLS_set_timer_cb.3 \
man/man3/DTLSv1_get_timeout.3 \
man/man3/DTLSv1_handle_timeout.3 \
man/man3/DTLSv1_listen.3 \
man/man3/ECDSA_SIG_new.3 \
man/man3/ECDSA_sign.3 \

57
doc/man3/DTLSv1_get_timeout.pod Normal file
View File

@ -0,0 +1,57 @@
=pod
=head1 NAME
DTLSv1_get_timeout - determine when a DTLS SSL object next needs a timeout
event to be handled
=head1 SYNOPSIS
#include <openssl/ssl.h>
int DTLSv1_get_timeout(SSL *s, struct timeval *tv);
=head1 DESCRIPTION
DTLSv1_get_timeout() can be used on a DTLS SSL object to determine when the
SSL object next needs to perform internal processing due to the passage of time.
Calling DTLSv1_get_timeout() results in I<*tv> being written with an amount of
time left before the SSL object needs have DTLSv1_handle_timeout() called on it.
If the SSL object needs to be ticked immediately, I<*tv> is zeroed and the
function succeeds, returning 1. If no timeout is currently active, this function
returns 0.
This function is only applicable to DTLS objects. It fails if called on
any other kind of SSL object.
Note that the value output by a call to DTLSv1_get_timeout() may change as a
result of other calls to the SSL object.
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)> supercedes all use cases for this this function and
may be used instead of it.
=head1 RETURN VALUES
On success, writes a duration to I<*tv> and returns 1.
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)>
=head1 COPYRIGHT
Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

50
doc/man3/DTLSv1_handle_timeout.pod Normal file
View File

@ -0,0 +1,50 @@
=pod
=head1 NAME
DTLSv1_handle_timeout - handle a pending timeout event for a DTLS SSL object
=head1 SYNOPSIS
#include <openssl/ssl.h>
int DTLSv1_handle_timeout(SSL *ssl);
=head1 DESCRIPTION
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
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)> supercedes all use cases for this this function and may be used
instead of it.
=head1 RETURN VALUES
Returns 1 if there was a pending timeout event and it was handled successfully.
Returns 0 if there was no pending timeout event, or if the SSL object is not a
DTLS object.
Returns -1 if there was a pending timeout event but it could not be handled
successfully.
=head1 SEE ALSO
L<DTLSv1_get_timeout(3)>, L<SSL_tick(3)>, L<ssl(7)>
=head1 COPYRIGHT
Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

10
doc/man3/SSL_get_tick_timeout.pod
View File

@ -25,19 +25,27 @@ This function is currently applicable only to DTLS and QUIC connection SSL
objects. If it is called on any other kind of SSL object, it always outputs
infinity. This is considered a success condition.
For DTLS, this function can be used instead of the older
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
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)>.
Note that SSL_get_tick_timeout() supersedes the older L<DTLSv1_get_timeout(3)>
function for all use cases.
=head1 RETURN VALUES
Returns 1 on success and 0 on failure.
=head1 SEE ALSO
L<SSL_tick(3)>, L<ssl(7)>
L<SSL_tick(3)>, L<DTLSv1_get_timeout(3)>, L<ssl(7)>
=head1 HISTORY

29
doc/man3/SSL_tick.pod
View File

@ -33,14 +33,14 @@ SSL_tick() can be used only with the following types of SSL object:
Using SSL_tick() on an SSL object being used with a DTLS method allows timeout
events to be handled properly. This is equivalent to a call to
DTLSv1_handle_timeout(). Since SSL_tick() handles a superset of the use cases of
DTLSv1_handle_timeout(), it should be preferred for new applications which do
not require support for OpenSSL 3.1 or older.
L<DTLSv1_handle_timeout(3)>. Since SSL_tick() 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
SSL_get_tick_timeout(); ticking is not performed automatically by calls to other
SSL functions such as SSL_read() or SSL_write(). Note that this is different to
QUIC which also performs ticking implicitly; see below.
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.
=item QUIC connection SSL objects
@ -55,13 +55,13 @@ automatic basis. However, if an application uses a QUIC connection in
nonblocking mode, it must at a minimum ensure that SSL_tick() 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
SSL_get_tick_timeout().
L<SSL_get_tick_timeout(3)>.
Calling SSL_tick() on a QUIC connection SSL object being used in blocking mode
is not necessary unless no I/O calls (such as SSL_read() or SSL_write()) 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.
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.
=begin comment
@ -74,13 +74,16 @@ TODO(QUIC): Update the above paragraph once we support thread assisted mode.
Calling SSL_tick() 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
for all use cases.
=head1 RETURN VALUES
Returns 1 on success and 0 on failure.
=head1 SEE ALSO
L<SSL_get_tick_timeout(3)>, L<ssl(7)>
L<SSL_get_tick_timeout(3)>, L<DTLSv1_handle_timeout(3)>, L<ssl(7)>
=head1 HISTORY
@ -88,7 +91,7 @@ The SSL_tick() function was added in OpenSSL 3.2.
=head1 COPYRIGHT
Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

2
util/other.syms
View File

@ -264,6 +264,8 @@ DES_ede2_cfb64_encrypt define
DES_ede2_ofb64_encrypt define
DTLS_get_link_min_mtu define
DTLS_set_link_mtu define
DTLSv1_get_timeout define
DTLSv1_handle_timeout define
ENGINE_cleanup define deprecated 1.1.0
ERR_FATAL_ERROR define
ERR_GET_LIB define