diff options
author | Hugo Landau <hlandau@openssl.org> | 2022-12-13 16:37:17 +0000 |
---|---|---|
committer | Hugo Landau <hlandau@openssl.org> | 2023-05-17 11:10:45 +0100 |
commit | f89c2a992690dcc6f3f27706a8a97cb2b7d670ee (patch) | |
tree | cd13f61b0c8fc2034115c41aef74fac2adf241ff /doc | |
parent | a64c48cff88e032cf9513578493c4536df725a22 (diff) |
QUIC man(7) Documentation
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19899)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/build.info | 6 | ||||
-rw-r--r-- | doc/man7/openssl-quic.pod | 681 |
2 files changed, 687 insertions, 0 deletions
diff --git a/doc/build.info b/doc/build.info index 197fead8d8..624fcac5e9 100644 --- a/doc/build.info +++ b/doc/build.info @@ -4725,6 +4725,10 @@ DEPEND[html/man7/openssl-glossary.html]=man7/openssl-glossary.pod GENERATE[html/man7/openssl-glossary.html]=man7/openssl-glossary.pod DEPEND[man/man7/openssl-glossary.7]=man7/openssl-glossary.pod GENERATE[man/man7/openssl-glossary.7]=man7/openssl-glossary.pod +DEPEND[html/man7/openssl-quic.html]=man7/openssl-quic.pod +GENERATE[html/man7/openssl-quic.html]=man7/openssl-quic.pod +DEPEND[man/man7/openssl-quic.7]=man7/openssl-quic.pod +GENERATE[man/man7/openssl-quic.7]=man7/openssl-quic.pod DEPEND[html/man7/openssl-threads.html]=man7/openssl-threads.pod GENERATE[html/man7/openssl-threads.html]=man7/openssl-threads.pod DEPEND[man/man7/openssl-threads.7]=man7/openssl-threads.pod @@ -4940,6 +4944,7 @@ html/man7/openssl-core_dispatch.h.html \ html/man7/openssl-core_names.h.html \ html/man7/openssl-env.html \ html/man7/openssl-glossary.html \ +html/man7/openssl-quic.html \ html/man7/openssl-threads.html \ html/man7/openssl_user_macros.html \ html/man7/ossl_store-file.html \ @@ -5072,6 +5077,7 @@ man/man7/openssl-core_dispatch.h.7 \ man/man7/openssl-core_names.h.7 \ man/man7/openssl-env.7 \ man/man7/openssl-glossary.7 \ +man/man7/openssl-quic.7 \ man/man7/openssl-threads.7 \ man/man7/openssl_user_macros.7 \ man/man7/ossl_store-file.7 \ diff --git a/doc/man7/openssl-quic.pod b/doc/man7/openssl-quic.pod new file mode 100644 index 0000000000..f523503561 --- /dev/null +++ b/doc/man7/openssl-quic.pod @@ -0,0 +1,681 @@ +=pod + +=head1 NAME + +openssl-quic - OpenSSL QUIC + +=head1 DESCRIPTION + +OpenSSL 3.2 and later features support for the QUIC transport protocol. +Currently, only client connectivity and a single stream is supported. +This man page describes the usage of QUIC client functionality for both existing +and new applications. + +QUIC functionality uses the standard SSL API. A QUIC connection is represented +by an SSL object in the same way that a TLS connection is. Only minimal changes +are needed to existing applications making use of the libssl APIs to make use of +QUIC client functionality. To make use of QUIC, use the SSL method +L<OSSL_QUIC_client_method(3)> or L<OSSL_QUIC_client_thread_method(3)> with +L<SSL_CTX_new(3)>. + +When a QUIC connection is created, it has a single bidirectional stream +associated with it. Calls to L<SSL_read(3)> and L<SSL_write(3)> on the QUIC +connection SSL object read and write from that stream. + +The remainder of this man page discusses, in order: + +=over 4 + +=item + +The changes to existing libssl APIs which are driven by QUIC-related implementation +requirements, which existing applications should bear in mind; + +=item + +Aspects which must be considered by existing applications when adopting QUIC, +including potential changes which may be needed. + +=item + +Recommended usage approaches for new applications. + +=item + +New, QUIC-specific APIs. + +=back + +=head1 CHANGES TO EXISTING APIS + +Most SSL APIs, such as L<SSL_read(3)> and L<SSL_write(3)>, function as they do +for TLS connections and do not have changed semantics, with some exceptions. The +changes to the semantics of existing APIs are as follows: + +=over 4 + +=item + +Since QUIC uses UDP, L<SSL_set_bio(3)>, L<SSL_set0_rbio(3)> and +L<SSL_set0_wbio(3)> function as before, but must now receive a BIO with datagram +semantics. There are broadly three options for applications to use as a network +BIO: + +=over 4 + +=item + +L<BIO_s_datagram(3)>, recommended for most applications, replaces +L<BIO_s_socket(3)> and provides a UDP socket. + +=item + +L<BIO_s_dgram_pair(3)> provides BIO pair-like function but with datagram +semantics, and is recommended for existing applications which use a BIO pair or +memory BIO to manage libssl's communication with the network. + +=item + +An application may also choose to implement a custom BIO. The new +L<BIO_sendmmsg(3)> and L<BIO_recvmmsg(3)> APIs must be supported. + +=back + +=item + +L<SSL_set_fd(3)>, L<SSL_set_rfd(3)> and L<SSL_set_wfd(3)> traditionally +instantiate a L<BIO_s_socket(3)>. For QUIC, these functions instead instantiate +a L<BIO_s_datagram(3)>. This is equivalent to instantiating a +L<BIO_s_datagram(3)> and using L<SSL_set0_rbio(3)> and L<SSL_set0_wbio(3)>. + +=item + +L<BIO_new_ssl_connect(3)> has been changed to automatically use a +L<BIO_s_datagram(3)> when used with QUIC, therefore applications which use this +do not need to change the BIO they use. + +=item + +L<BIO_new_buffer_ssl_connect(3)> cannot be used with QUIC and applications must +change to use L<BIO_new_ssl_connect(3)> instead. + +=item + +L<SSL_shutdown(3)> has significant changes in relation to how QUIC connections +must be shut down. In particular, applications should be advised that the full +RFC-conformant QUIC shutdown process may take an extended amount of time. This +may not be suitable for short-lived processes which should exit immediately +after their usage of a QUIC connection is completed. A rapid shutdown mode +is available for such applications. For details, see L<SSL_shutdown(3)>. + +=item + +L<SSL_want(3)>, L<SSL_want_read(3)> and L<SSL_want_write(3)> no longer reflect +the I/O state of the network BIO passed to the QUIC SSL object, but instead +reflect the flow control state of the QUIC stream associated with the SSL +object. + +When used in nonblocking mode, B<SSL_ERROR_WANT_READ> indicates that the +receive part of a QUIC stream does not currently have any more data available to +be read, and B<SSL_ERROR_WANT_WRITE> indicates that the stream's internal buffer +is full. + +To determine if the QUIC implementation currently wishes to be informed of +incoming network datagrams, use the new function L<SSL_net_read_desired(3)>; +likewise, to determine if the QUIC implementation currently wishes to be +informed when it is possible to transmit network datagrams, use the new function +L<SSL_net_write_desired(3)>. Only applications which wish to manage their own event +loops need to use these functions; see B<APPLICATION-DRIVEN EVENT LOOPS> for +further discussion. + +=item + +The use of ALPN is mandatory when using QUIC. For information on how to +configure ALPN, see L<SSL_set_alpn_protos(3)>. + +=item + +The following libssl functionality is not available when used with QUIC. + +=over 4 + +=item + +Async functionality + +=item + +B<SSL_MODE_AUTO_RETRY> + +=item + +Record Padding and Fragmentation (L<SSL_set_block_padding(3)>, etc.) + +=item + +L<SSL_stateless(3)> support + +=item + +SRTP functionality + +=item + +TLSv1.3 Early Data + +=item + +TLS Next Protocol Negotiation cannot be used and is superseded by ALPN, which +must be used instead. The use of ALPN is mandatory with QUIC. + +=item + +Post-Handshake Client Authentication is not available as QUIC prohibits its use. + +=item + +QUIC requires the use of TLSv1.3 or later, therefore functionality only relevant +to older TLS versions is not available. + +=item + +Some cipher suites which are generally available for TLSv1.3 are not available +for QUIC, such as B<TLS_AES_128_CCM_8_SHA256>. Your application may need to +adjust the list of acceptable cipher suites it passes to libssl. + +=item + +CCM mode is not currently supported. + +=back + +The following libssl functionality is also not available when used with QUIC, +but calls to the relevant functions are treated as no-ops: + +=over 4 + +=item + +Readahead (L<SSL_set_read_ahead(3)>, etc.) + +=back + +=back + +=head1 CONSIDERATIONS FOR EXISTING APPLICATIONS + +Existing applications seeking to adopt QUIC should apply the following list to +determine what changes they will need to make: + +=over 4 + +=item + +An application wishing to use QUIC must use L<OSSL_QUIC_client_method(3)> or +L<OSSL_QUIC_client_thread_method(3)> as its SSL method. For more information +on the differences between these two methods, see B<THREAD ASSISTED MODE>. + +=item + +Determine how to provide QUIC with network access. Determine which of the below +apply for your application: + +=over 4 + +=item + +Your application uses L<BIO_s_socket(3)> to construct a BIO which is passed to +the SSL object to provide it with network access. + +Changes needed: Change your application to use L<BIO_s_datagram(3)> instead when +using QUIC. You may or may not need to use L<SSL_set_initial_peer_addr(3)> to +set the initial peer address; see the B<QUIC-SPECIFIC APIS> section for details. + +=item + +Your application uses L<BIO_new_ssl_connect(3)> to +construct a BIO which is passed to the SSL object to provide it with network +access. + +Changes needed: No changes needed. Use of QUIC is detected automatically and a +datagram socket is created instead of a normal TCP socket. + +=item + +Your application uses any other I/O strategy in this list but combines it with a +L<BIO_f_buffer(3)>, for example using L<BIO_push(3)>. + +Changes needed: Disable the usage of L<BIO_f_buffer(3)> when using QUIC. Usage +of such a buffer is incompatible with QUIC as QUIC requires datagram semantics +in its interaction with the network. + +=item + +Your application uses a BIO pair to cause the SSL object to read and write +network traffic to a memory buffer. Your application manages the transmission +and reception of buffered data itself in a way unknown to libssl. + +Changes needed: Switch from using a conventional BIO pair to using +L<BIO_s_dgram_pair(3)> instead, which has the necessary datagram semantics. You +will need to modify your application to transmit and receive using a UDP socket +and to use datagram semantics when interacting with the L<BIO_s_dgram_pair(3)> +instance. + +=item + +Your application uses a custom BIO method to provide the SSL object with network +access. + +Changes needed: The custom BIO must be re-architected to have datagram +semantics. L<BIO_sendmmsg(3)> and L<BIO_recvmmsg(3)> must be implemented. These +calls must operate in a nonblocking fashion. Optionally, implement the +L<BIO_get_rpoll_descriptor(3)> and L<BIO_get_wpoll_descriptor(3)> methods if +desired. Implementing these methods is required if blocking semantics at the SSL +API level are desired. + +=back + +=item + +An application must explicitly configure whether it wishes to use the SSL APIs +in blocking mode or not. Traditionally, an SSL object has automatically operated +in blocking or nonblocking mode based on whether the underlying network BIO +operates in blocking or nonblocking mode. QUIC requires the use of a +nonblocking network BIO, therefore the blocking mode at the application level +must be explicitly configured by the application using the new +L<SSL_set_blocking_mode(3)> API. The default mode is blocking. If an application +wishes to use the SSL object APIs at application level in a nonblocking manner, +it must add a call to L<SSL_set_blocking_mode(3)> to disable blocking mode. + +=item + +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 +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. + +L<SSL_get_tick_timeout(3)> can be used to determine when L<SSL_tick(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. + +Applications which use thread assisted mode do not need to be concerned +with this requirement, as the QUIC implementation ensures timeout events +are handled in a timely manner. See B<THREAD ASSISTED MODE> for details. + +=item + +Ensure that your usage of L<SSL_want(3)>, L<SSL_want_read(3)> and +L<SSL_want_write(3)> reflects the API changes described in B<CHANGES TO EXISTING +APIS>. In particular, you should use these APIs to determine the ability of a +QUIC stream to receive or provide application data, not to to determine if +network I/O is required. + +=item + +Evaluate your application's use of L<SSL_shutdown(3)> in light of the changes +discussed in B<CHANGES TO EXISTING APIS>. Depending on whether your application +wishes to prioritise RFC conformance or rapid shutdown, consider using the new +L<SSL_shutdown_ex(3)> API instead. See B<QUIC-SPECIFIC APIS> for details. + +=back + +=head1 RECOMMENDED USAGE IN NEW APPLICATIONS + +The recommended usage in new applications varies depending on three independent +design decisions: + +=over 4 + +=item + +Whether the application will use blocking or nonblocking I/O at the application +level (configured using L<SSL_set_blocking_mode(3)>). + +If the application does nonblocking I/O at the application level it can choose +to manage its own polling and event loop; see B<APPLICATION-DRIVEN EVENT LOOPS>. + +=item + +Whether the application intends to give the QUIC implementation direct access to +a network socket (e.g. via L<BIO_s_datagram(3)>) or whether it intends to buffer +transmitted and received datagrams via a L<BIO_s_dgram_pair(3)> or custom BIO. + +The former is preferred where possible as it reduces latency to the network, +which enables QUIC to achieve higher performance and more accurate connection +round trip time (RTT) estimation. + +=item + +Whether thread assisted mode will be used (see B<THREAD ASSISTED MODE>). + +=back + +Simple demos for QUIC usage under these various scenarios can be found at +L<https://github.com/openssl/openssl/tree/master/doc/designs/ddd>. + +Applications which wish to implement QUIC-specific protocols should be aware of +the APIs listed under B<QUIC-SPECIFIC APIS> which provide access to +QUIC-specific functionality. For example, L<SSL_stream_conclude(3)> can be used +to indicate the end of the sending part of a stream, and L<SSL_shutdown_ex(3)> +can be used to provide a QUIC application error code when closing a connection. + +=head1 QUIC-SPECIFIC APIS + +This section details new APIs which are directly or indirectly related to QUIC. +For details on the operation of each API, see the referenced man pages. + +The following SSL APIs are new but relevant to both QUIC and DTLS: + +=over 4 + +=item L<SSL_get_tick_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_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)> + +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. + +This can also be used with DTLS and supersedes L<DTLSv1_handle_timeout(3)> for +new usage. + +=back + +The following SSL APIs are specific to QUIC: + +=over 4 + +=item L<SSL_set_blocking_mode(3)>, L<SSL_get_blocking_mode(3)> + +Configures whether blocking semantics are used at the application level. This +determines whether calls to functions such as L<SSL_read(3)> and L<SSL_write(3)> +will block. + +=item L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)> + +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. + +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. + +=item L<SSL_net_read_desired(3)>, L<SSL_net_write_desired(3)> + +These functions facilitate operation in nonblocking mode and are used in +conjunction with L<SSL_get_rpoll_descriptor(3)> and +L<SSL_get_wpoll_descriptor(3)> respectively. They determine whether the +respective poll descriptor is currently relevant for the purposes of polling. + +=item L<SSL_set_initial_peer_addr(3)> + +This functions can be used to set the initial peer address for an outgoing QUIC +connection. This function must be used in the general case when creating an +outgoing QUIC connection; however, the correct initial peer address can be +autodetected in some cases. See L<SSL_set_initial_peer_addr(3)> for details. + +=item L<SSL_shutdown_ex(3)> + +This augments L<SSL_shutdown(3)> by allowing an application error code to be +specified. It also allows a client to decide how quickly it wants a shutdown to +be performed, potentially by trading off strict RFC compliance. + +=item L<SSL_stream_conclude(3)> + +This allows an application to indicate the normal end of the sending part of a +QUIC stream. This corresponds to the FIN flag in the QUIC RFC. The receiving +part of a stream remains usable. + +=item L<SSL_stream_reset(3)> + +This allows an application to indicate the non-normal termination of a stream, +including both its sending and receiving parts. This corresponds to the +RESET_STREAM frame in the QUIC RFC. + +=item L<SSL_get_stream_state(3)> + +This allows an application to determine the current stream state. + +=item L<SSL_get_stream_error_code(3)> + +This allows an application to determine the application error code which was +signalled by a peer which has performed a non-normal stream termination, if any. + +=item L<SSL_get_conn_close_info(3)> + +This allows an application to determine the error code which was signalled when +the local or remote endpoint terminated the QUIC connection. + +=back + +The following BIO APIs are not specific to QUIC but have been added to +facilitate QUIC-specific requirements and are closely associated with its use: + +=over 4 + +=item L<BIO_s_dgram_pair(3)> + +This is a new BIO method which is similar to a conventional BIO pair but +provides datagram semantics. + +=item L<BIO_get_rpoll_descriptor(3)>, L<BIO_get_wpoll_descriptor(3)> + +This is a new BIO API which allows a BIO to expose a poll descriptor. This API +is used to implement the corresponding SSL APIs L<SSL_get_rpoll_descriptor(3)> +and L<SSL_get_wpoll_descriptor(3)>. + +=item L<BIO_sendmmsg(3)>, L<BIO_recvmmsg(3)> + +This is a new BIO API which can be implemented by BIOs which implement datagram +semantics. It is implemented by L<BIO_s_datagram(3)> and L<BIO_s_dgram_pair(3)>. +It is used by the QUIC implementation to send and receive UDP datagrams. + +=item L<BIO_dgram_set_no_trunc(3)>, L<BIO_dgram_get_no_trunc(3)> + +By default, L<BIO_s_dgram_pair(3)> has semantics comparable to those of Berkeley +sockets being used with datagram semantics. This allows an alternative mode +to be enabled in which datagrams will not be silently truncated if they are +too large. + +=item L<BIO_dgram_set_caps(3)>, L<BIO_dgram_get_caps(3)> + +These functions are used to allow the user of one end of a +L<BIO_s_dgram_pair(3)> to indicate its capabilities to the other end of a +L<BIO_s_dgram_pair(3)>. In particular, this allows an application to inform the +QUIC implementation of whether it is prepared to handle local and/or peer +addresses in transmitted datagrams and to provide the applicable information in +received datagrams. + +=item L<BIO_dgram_get_local_addr_cap(3)>, L<BIO_dgram_set_local_addr_enable(3)>, +L<BIO_dgram_get_local_addr_enable(3)> + +Local addressing support refers to the ability of a BIO with datagram semantics +to allow a source address to be specified on transmission and to report the +destination address on reception. These functions can be used to determine if a +BIO can support local addressing and to enable local addressing support if it +can. + +=item L<BIO_err_is_non_fatal(3)> + +This is used to determine if an error while calling L<BIO_sendmmsg(3)> or +L<BIO_recvmmsg(3)> is ephemeral in nature, such as "would block" errors. + +=back + +=head1 THREAD ASSISTED MODE + +The optional thread assisted mode can be used with +L<OSSL_QUIC_client_thread_method(3)>. In this mode, a background thread is +created automatically. The OpenSSL QUIC implementation then takes responsibility +for ensuring that timeout events are handled on a timely basis even if no SSL +I/O function such as L<SSL_read(3)> or L<SSL_write(3)> is called by the +application for a long time. + +All necessary locking is handled automatically internally, but the thread safety +guarantees for the public SSL API are unchanged. Therefore, an application must +still do its own locking if it wishes to make concurrent use of the public SSL +APIs. + +Because this method relies on threads, it is not available on platforms where +threading support is not available or not supported by OpenSSL. However, it +does provide the simplest mode of usage for an application. + +The implementation may or may not use a common thread or thread pool to service +multiple SSL objects in the same B<SSL_CTX>. + +=begin comment + +TODO(QUIC): Amend this man page once thread assisted mode is supported. + +=end comment + +=head1 APPLICATION-DRIVEN EVENT LOOPS + +OpenSSL's QUIC implementation is designed to facilitate applications which wish +to use the SSL APIs in a blocking fashion, but is also designed to facilitate +applications which wish to use the SSL APIs in a nonblocking fashion and manage +their own event loops and polling directly. This is useful when it is desirable +to host OpenSSL's QUIC implementation on top of an application's existing +nonblocking I/O infrastructure. + +This is supported via the concept of poll descriptors; see +L<BIO_get_rpoll_descriptor(3)> for details. Broadly, a B<BIO_POLL_DESCRIPTOR> is +a structure which expresses some kind of OS resource which can be used to +synchronise on I/O events. The QUIC implementation provides a +B<BIO_POLL_DESCRIPTOR> based on the poll descriptor provided by the underlying +network BIO. This is typically an OS socket handle, though custom BIOs could +choose to implement their own custom poll descriptor format. + +Broadly, an application which wishes to manage its own event loop should +interact with the SSL object as follows: + +=over 4 + +=item + +It should provide read and write BIOs with nonblocking datagram semantics to +the SSL object using L<SSL_set0_rbio(3)> and L<SSL_set0_wbio(3)>. This could be +a BIO abstracting a network socket such as L<BIO_s_datagram(3)>, or a BIO +abstracting some kind of memory buffer such as L<BIO_s_dgram_pair(3)>. Use of a +custom BIO is also possible. + +=item + +It should configure the SSL object into nonblocking mode by calling +L<SSL_set_blocking_mode(3)>. + +=item + +It should configure the SSL object as desired, set an initial peer as needed +using L<SSL_set_initial_peer_addr(3)>, and trigger the connection process by +calling L<SSL_connect(3)>. + +=item + +If the network read and write BIOs provided were pollable (for example, +a L<BIO_s_datagram(3)>, or a custom BIO which implements +L<BIO_get_rpoll_descriptor(3)> and L<BIO_get_wpoll_descriptor(3)>), it should +perform the following steps repeatedly: + +=over 4 + +=item + +The application should call L<SSL_get_rpoll_descriptor(3)> and +L<SSL_get_wpoll_descriptor(3)> to identify OS resources which can be used for +synchronisation. + +=item + +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 +applicable in the future. + +=item + +It should wait until one of the following events occurs: + +=over 4 + +=item + +The poll descriptor returned by L<SSL_get_rpoll_descriptor(3)> becomes readable +(if L<SSL_net_read_desired(3)> returned 1); + +=item + +The poll descriptor returned by L<SSL_get_wpoll_descriptor(3)> becomes writable +(if L<SSL_net_write_desired(3)> returned 1); + +=item + +The timeout returned by L<SSL_get_tick_timeout(3)> (if any) expires. + +=back + +Once any of these events occurs, L<SSL_tick(3)> should be called. + +=back + +=item + +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_read(3)> on the +underlying network BIO. The QUIC implementation may output datagrams via a call +to L<BIO_write(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). + +=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)> + +=head1 COPYRIGHT + +Copyright 2022 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 |