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
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 \
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 \
--- /dev/null
+=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
--- /dev/null
+=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
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
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
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
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
=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
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
projects / openssl.git / commitdiff