1=pod 2 3=head1 NAME 4 5SSL_handle_events - advance asynchronous state machine and perform network I/O 6 7=head1 SYNOPSIS 8 9 #include <openssl/ssl.h> 10 11 int SSL_handle_events(SSL *ssl); 12 13=head1 DESCRIPTION 14 15SSL_handle_events() performs any internal processing which is due on a SSL object. The 16exact operations performed by SSL_handle_events() vary depending on what kind of protocol 17is being used with the given SSL object. For example, SSL_handle_events() may handle 18timeout events which have become due, or may attempt, to the extent currently 19possible, to perform network I/O operations on one of the BIOs underlying the 20SSL object. 21 22The primary use case for SSL_handle_events() is to allow an application which uses 23OpenSSL in nonblocking mode to give OpenSSL an opportunity to handle timer 24events, or to respond to the availability of new data to be read from an 25underlying BIO, or to respond to the opportunity to write pending data to an 26underlying BIO. 27 28SSL_handle_events() can be used only with the following types of SSL object: 29 30=over 4 31 32=item DTLS SSL objects 33 34Using SSL_handle_events() on an SSL object being used with a DTLS method allows timeout 35events to be handled properly. This is equivalent to a call to 36L<DTLSv1_handle_timeout(3)>. Since SSL_handle_events() handles a superset of the use 37cases of L<DTLSv1_handle_timeout(3)>, it should be preferred for new 38applications which do not require support for OpenSSL 3.1 or older. 39 40When using DTLS, an application must call SSL_handle_events() as indicated by 41calls to L<SSL_get_event_timeout(3)>; event handling is not performed 42automatically by calls to other SSL functions such as L<SSL_read(3)> or 43L<SSL_write(3)>. Note that this is different to QUIC which also performs event 44handling implicitly; see below. 45 46=item QUIC connection SSL objects 47 48Using SSL_handle_events() on an SSL object which represents a QUIC connection allows 49timeout events to be handled properly, as well as incoming network data to be 50processed, and queued outgoing network data to be written, if the underlying BIO 51has the capacity to accept it. 52 53Ordinarily, when an application uses an SSL object in blocking mode, it does not 54need to call SSL_handle_events() because OpenSSL performs ticking internally on an 55automatic basis. However, if an application uses a QUIC connection in 56nonblocking mode, it must at a minimum ensure that SSL_handle_events() is called 57periodically to allow timeout events to be handled. An application can find out 58when it next needs to call SSL_handle_events() for this purpose (if at all) by calling 59L<SSL_get_event_timeout(3)>. 60 61Calling SSL_handle_events() on a QUIC connection SSL object being used in blocking mode 62is not necessary unless no I/O calls (such as L<SSL_read(3)> or L<SSL_write(3)>) 63will be made to the object for a substantial period of time. So long as at least 64one call to the SSL object is blocking, no such call is needed. However, 65SSL_handle_events() may optionally be used on a QUIC connection object if desired. 66 67With the thread-assisted mode of operation L<OSSL_QUIC_client_thread_method(3)> 68it is unnecessary to call SSL_handle_events() as the assist thread handles the QUIC 69connection events. 70 71=back 72 73Calling SSL_handle_events() on any other kind of SSL object is a no-op. This is 74considered a success case. 75 76Note that SSL_handle_events() supersedes the older L<DTLSv1_handle_timeout(3)> function 77for all use cases. 78 79=head1 RETURN VALUES 80 81Returns 1 on success and 0 on failure. 82 83=head1 SEE ALSO 84 85L<SSL_get_event_timeout(3)>, L<DTLSv1_handle_timeout(3)>, L<ssl(7)> 86 87=head1 HISTORY 88 89The SSL_handle_events() function was added in OpenSSL 3.2. 90 91=head1 COPYRIGHT 92 93Copyright 2023 The OpenSSL Project Authors. All Rights Reserved. 94 95Licensed under the Apache License 2.0 (the "License"). You may not use 96this file except in compliance with the License. You can obtain a copy 97in the file LICENSE in the source distribution or at 98L<https://www.openssl.org/source/license.html>. 99 100=cut 101
