From: Hugo Landau Date: Mon, 9 Jan 2023 11:18:06 +0000 (+0000) Subject: QUIC CSM: Tweak docs for tick functions, add DTLSv1 docs X-Git-Tag: openssl-3.2.0-alpha1~1463 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8ccc567ef0af03a312d7742f451556eb788d5286;p=thirdparty%2Fopenssl.git QUIC CSM: Tweak docs for tick functions, add DTLSv1 docs Reviewed-by: Tomas Mraz Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/19703) --- diff --git a/doc/build.info b/doc/build.info index 2b169f1cf2c..6ac83952e43 100644 --- a/doc/build.info +++ b/doc/build.info @@ -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 \ diff --git a/doc/man3/DTLSv1_get_timeout.pod b/doc/man3/DTLSv1_get_timeout.pod new file mode 100644 index 00000000000..fbaf0f96123 --- /dev/null +++ b/doc/man3/DTLSv1_get_timeout.pod @@ -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 + + 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. + +L 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, L, L + +=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. + +=cut diff --git a/doc/man3/DTLSv1_handle_timeout.pod b/doc/man3/DTLSv1_handle_timeout.pod new file mode 100644 index 00000000000..77c1a89ab4f --- /dev/null +++ b/doc/man3/DTLSv1_handle_timeout.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +DTLSv1_handle_timeout - handle a pending timeout event for a DTLS SSL object + +=head1 SYNOPSIS + + #include + + 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 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 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, L, L + +=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. + +=cut diff --git a/doc/man3/SSL_get_tick_timeout.pod b/doc/man3/SSL_get_tick_timeout.pod index e944620bed5..8decc35a628 100644 --- a/doc/man3/SSL_get_tick_timeout.pod +++ b/doc/man3/SSL_get_tick_timeout.pod @@ -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 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 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. +Note that SSL_get_tick_timeout() supersedes the older L +function for all use cases. + =head1 RETURN VALUES Returns 1 on success and 0 on failure. =head1 SEE ALSO -L, L +L, L, L =head1 HISTORY diff --git a/doc/man3/SSL_tick.pod b/doc/man3/SSL_tick.pod index a0a43ecb66e..66ee0c7e29d 100644 --- a/doc/man3/SSL_tick.pod +++ b/doc/man3/SSL_tick.pod @@ -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. Since SSL_tick() 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 -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; 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 @@ -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. 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 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. =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 function +for all use cases. + =head1 RETURN VALUES Returns 1 on success and 0 on failure. =head1 SEE ALSO -L, L +L, L, L =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 diff --git a/util/other.syms b/util/other.syms index 267c0ff39c1..91a1559b5d6 100644 --- a/util/other.syms +++ b/util/other.syms @@ -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