OPENSSL-QUIC(7ossl)

📦 version 3.5.0, in opensuse-leap 16.0

bestie, come sit with me — this is OPENSSL-QUIC, from the OpenSSL manual set (7ossl), and it's honestly the glow-up era of libssl. Buckle up. 🦋

✨ NAME ✨

openssl-quic — OpenSSL's QUIC situation. That's it, that's the name. 💅

🌸 DESCRIPTION 🌸

okay so OpenSSL 3.2 and later ships with support for the QUIC transport protocol, no cap. You can use OpenSSL's QUIC abilities for both client and server applications. This man page is the whole tour of how to let your apps speak QUIC via the libssl API. ✨

Here's the iconic part: the QUIC protocol maps onto the standard SSL API. A QUIC connection is represented by an SSL object, exactly the same way a TLS connection is. So if your app already uses the libssl API, you need only minimal changes to bring QUIC support in. Obsessed. 🫶

The rest of this man page goes through, in order:

  • Default stream mode versus multi-stream mode for clients;
  • The changes to existing libssl APIs which are driven by QUIC-related implementation requirements, which existing applications should bear in mind;
  • Aspects which must be considered by existing applications when adopting QUIC, including potential changes which may be needed.
  • Recommended usage approaches for new applications.
  • New, QUIC-specific APIs.

🔥 CLIENT MODES OF OPERATION 🔥

When a client creates a QUIC connection, by default it operates in default stream mode, which is literally there to provide compatibility with existing non-QUIC application usage patterns. In this mode, the connection has a single stream associated with it. Calls to SSL_read(3) and SSL_write(3) on the QUIC connection SSL object read and write from that stream. And whether the stream is client-initiated or server-initiated from a QUIC perspective depends on whether SSL_read(3) or SSL_write(3) is called first. Sneaky but makes sense. 👀

Default stream mode is primarily for compatibility with existing applications. For new applications utilizing QUIC, it's recommended to disable this mode and instead adopt the multi-stream API. See the RECOMMENDATIONS FOR NEW APPLICATIONS section for more details.

🎀 Default Stream Mode 🎀

A QUIC client connection can be used in either default stream mode or multi-stream mode. By default, a newly created QUIC connection SSL object uses default stream mode. 💫

In default stream mode, a stream is implicitly created and bound to the QUIC connection SSL object; SSL_read(3) and SSL_write(3) calls to the QUIC connection SSL object work by default and are mapped to that stream.

When default stream mode is used, any API function which can be called on a QUIC stream SSL object can also be called on a QUIC connection SSL object — in which case it affects the default stream bound to the connection. Cute, right? 🎀

The identity of a QUIC stream, including its stream ID, varies depending on whether a stream is client-initiated or server-initiated. In default stream mode, if a client application calls SSL_read(3) first before any call to SSL_write(3) on the connection, it is assumed that the application protocol is using a server-initiated stream, and the SSL_read(3) call will not complete (either blocking, or failing appropriately if nonblocking mode is configured) until the server initiates a stream. Conversely, if the client application calls SSL_write(3) before any call to SSL_read(3) on the connection, it is assumed that a client-initiated stream is to be used and such a stream is created automatically. first move decides the vibe, basically.

Default stream mode is intended to aid compatibility with legacy applications. New applications adopting QUIC should use multi-stream mode, described below, and avoid use of the default stream functionality.

It is possible to use additional streams in default stream mode using SSL_new_stream(3) and SSL_accept_stream(3); note that the default incoming stream policy will need to be changed using SSL_set_incoming_stream_policy(3) in order to use SSL_accept_stream(3) in this case. However, applications using additional streams are strongly recommended to use multi-stream mode instead. 🙈

⚠️ heads up: calling SSL_new_stream(3) or SSL_accept_stream(3) before a default stream has been associated with the QUIC connection SSL object will inhibit future creation of a default stream. like, it's done. no default stream for you. 💀

🦋 Multi-Stream Mode 🦋

The recommended usage mode for new applications adopting QUIC is multi-stream mode, in which no default stream is attached to the QUIC connection SSL object, and attempts to call SSL_read(3) and SSL_write(3) on the QUIC connection SSL object fail. Instead, an application calls SSL_new_stream(3) or SSL_accept_stream(3) to create individual stream SSL objects for sending and receiving application data using SSL_read(3) and SSL_write(3). it's giving main character energy, one stream at a time. 👑

To use multi-stream mode, call SSL_set_default_stream_mode(3) with an argument of SSL_DEFAULT_STREAM_MODE_NONE; this function must be called prior to initiating the connection. The default stream mode cannot be changed after initiating a connection. Periodt. 🚫

When multi-stream mode is used, meaning that no default stream is associated with the connection, calls to API functions which are defined as operating on a QUIC stream fail if called on the QUIC connection SSL object. For example, calls such as SSL_write(3) or SSL_get_stream_id(3) will fail. connection object ≠ stream object, bestie, know the difference. ✨

💅 CHANGES TO EXISTING APIS 💅

okay so here's the tea ☕ — most SSL APIs, like SSL_read(3) and SSL_write(3), literally function exactly the way they do for TLS connections and their semantics did not change. no cap. but bestie, there are some exceptions 👀 and the changes to the semantics of the existing APIs are as follows:

  • QUIC runs on UDP 🛰️ so SSL_set_bio(3), SSL_set0_rbio(3) and SSL_set0_wbio(3) still function as before, but they must now receive a BIO with datagram semantics. broadly speaking, you've got four options for what your application can use as a network BIO:
    • BIO_s_datagram(3) — the recommended one for most applications 💖 it replaces BIO_s_socket(3) and gives you a UDP socket.
    • BIO_s_dgram_pair(3) — gives you BIO pair-like functionality but with datagram semantics 🦋 and it's the recommended pick for existing applications that use a BIO pair or memory BIO to manage libssl's communication with the network.
    • BIO_s_dgram_mem(3) — a simple memory BIO-like interface but with datagram semantics. unlike BIO_s_dgram_pair(3), it's unidirectional.
    • your app can also choose to implement a custom BIO if you're feeling brave ✨ the new BIO_sendmmsg(3) and BIO_recvmmsg(3) APIs must be supported.
  • SSL_set_fd(3), SSL_set_rfd(3) and SSL_set_wfd(3) traditionally instantiate a BIO_s_socket(3). but for QUIC? they instantiate a BIO_s_datagram(3) instead 🌈 this is equivalent to instantiating a BIO_s_datagram(3) and using SSL_set0_rbio(3) and SSL_set0_wbio(3).
  • bestie this one's a big vibe shift 🔥 traditionally, whether the application-level I/O APIs (like SSL_read(3) and SSL_write(3)) operated in a blocking fashion was directly correlated with whether the underlying network socket was configured in a blocking fashion. that is no longer the case. applications must explicitly configure the desired application-level blocking mode using SSL_set_blocking_mode(3). see SSL_set_blocking_mode(3) for the details, iykyk.
  • network-level I/O must always be performed in a nonblocking manner, periodt. your app can still enjoy blocking semantics for calls to application-level I/O functions such as SSL_read(3) and SSL_write(3) 💅 but the underlying network BIO you hand to QUIC (like a BIO_s_datagram(3)) must be configured in nonblocking mode. for that application-level blocking functionality, see SSL_set_blocking_mode(3).
  • BIO_new_ssl_connect(3) got a glow-up ✨ it's been changed to automatically use a BIO_s_datagram(3) when used with QUIC, so applications using this don't need to change the BIO they use at all. we love a low-effort migration.
  • BIO_new_buffer_ssl_connect(3) cannot be used with QUIC 😭 applications must switch to using BIO_new_ssl_connect(3) instead.
  • 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 SSL_shutdown(3).
  • SSL_want(3), SSL_want_read(3) and SSL_want_write(3) no longer reflect the I/O state of the network BIO passed to the QUIC SSL object 🫠 instead they reflect the flow control state of the QUIC stream associated with the SSL object. when used in nonblocking mode, 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 SSL_ERROR_WANT_WRITE indicates that the stream's internal buffer is full. to figure out if the QUIC implementation currently wishes to be informed of incoming network datagrams, use the new function SSL_net_read_desired(3) ✨ likewise, to determine if the QUIC implementation currently wishes to be informed when it's possible to transmit network datagrams, use the new function SSL_net_write_desired(3). only applications which wish to manage their own event loops need to use these functions — see APPLICATION-DRIVEN EVENT LOOPS for further discussion.
  • the use of ALPN is mandatory when using QUIC 😤 attempts to connect without configuring ALPN will fail. for info on how to configure ALPN, see SSL_set_alpn_protos(3).
  • whether QUIC operates in a client or server mode is determined by the SSL_METHOD used, rather than by calls to SSL_set_connect_state(3) or SSL_set_accept_state(3) 👑 it's not necessary to call either of SSL_set_connect_state(3) or SSL_set_accept_state(3) before connecting, but if either of these are called, the function called must be congruent with the SSL_METHOD being used.
  • the SSL_set_min_proto_version(3) and SSL_set_max_proto_version(3) APIs are not used and the values passed to them are ignored 🙈 because OpenSSL QUIC currently always uses TLS 1.3.
  • the following libssl functionality is not available when used with QUIC 🚫
    • Async functionality
    • SSL_MODE_AUTO_RETRY
    • Record Padding and Fragmentation (SSL_set_block_padding(3), etc.)
    • SSL_stateless(3) support
    • SRTP functionality
    • TLSv1.3 Early Data
    • 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.
    • Post-Handshake Client Authentication is not available as QUIC prohibits its use.
    • QUIC requires the use of TLSv1.3 or later, therefore functionality only relevant to older TLS versions is not available.
    • some cipher suites which are generally available for TLSv1.3 are not available for QUIC, such as TLS_AES_128_CCM_8_SHA256 💀 your application may need to adjust the list of acceptable cipher suites it passes to libssl.
    • CCM mode is not currently supported.
  • the following libssl functionality is also not available when used with QUIC, but calls to the relevant functions are treated as no-ops 🫶

💖 CONSIDERATIONS FOR EXISTING APPLICATIONS 💖

Okay so if you already have an app and you're trying to adopt QUIC, bestie, run through this list to figure out what you gotta change. No cap, it's the whole vibe check:

Changes needed: switch your app to use BIO_s_datagram(3) instead when using QUIC. The socket must be configured in nonblocking mode. You may or may not need to use SSL_set1_initial_peer_addr(3) to set the initial peer address; see QUIC-SPECIFIC APIS for the details.

  • Your app uses BIO_new_ssl_connect(3) to construct a BIO that gets passed to the SSL object so it has network access.

Changes needed: none, slay. Use of QUIC is detected automatically and a datagram socket is created instead of a normal TCP socket.

Changes needed: disable the usage of BIO_f_buffer(3) when using QUIC. Using that kind of buffer is incompatible with QUIC because QUIC requires datagram semantics in its interaction with the network.

  • Your app uses a BIO pair to make the SSL object read and write network traffic to a memory buffer. Your app manages the transmission and reception of buffered data itself in a way libssl doesn't know about.

Changes needed: switch from using a conventional BIO pair to using BIO_s_dgram_pair(3) instead, which has the datagram semantics you need. You'll need to modify your app to transmit and receive using a UDP socket and to use datagram semantics when interacting with the BIO_s_dgram_pair(3) instance.

  • Your app 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. BIO_sendmmsg(3) and BIO_recvmmsg(3) must be implemented. These calls must operate in a nonblocking fashion. Optionally, implement the BIO_get_rpoll_descriptor(3) and BIO_get_wpoll_descriptor(3) methods if desired. Implementing these methods is required if blocking semantics at the SSL API level are desired.

  • Blocking mode has entered the chat: an application must explicitly configure whether it wants to use the SSL APIs in blocking mode or not. Traditionally, an SSL object automatically operated in blocking or nonblocking mode based on whether the underlying network BIO operated in blocking or nonblocking mode. QUIC requires the use of a nonblocking network BIO, so the blocking mode at the application level can be explicitly configured by the application using the new SSL_set_blocking_mode(3) API. The default mode is blocking. If an application wants to use the SSL object APIs at the application level in a nonblocking manner, it must add a call to SSL_set_blocking_mode(3) to disable blocking mode.
  • Timer events need attention, periodt: if your client app does not choose to use thread assisted mode, it must ensure that it calls an I/O function on the SSL object (for example, SSL_read(3) or SSL_write(3)), or the new function SSL_handle_events(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 SSL_read(3) or SSL_write(3) regularly. If an application does not do this, it should ensure that SSL_handle_events(3) is called regularly.

SSL_get_event_timeout(3) can be used to determine when SSL_handle_events(3) must next be called.

If the SSL object is being used with an underlying network BIO which is pollable (such as BIO_s_datagram(3)), the application can use SSL_get_rpoll_descriptor(3) and SSL_get_wpoll_descriptor(3) to obtain resources which can be used to determine when SSL_handle_events(3) should be called due to network I/O.

Client 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 THREAD ASSISTED MODE for details.

  • SSL_want behavior check: make sure your usage of SSL_want(3), SSL_want_read(3) and SSL_want_write(3) reflects the API changes described in 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 determine if network I/O is required.
  • Shutdown glow-up: evaluate your application's use of SSL_shutdown(3) in light of the changes discussed in CHANGES TO EXISTING APIS. Depending on whether your application wishes to prioritise RFC conformance or rapid shutdown, consider using the new SSL_shutdown_ex(3) API instead. See QUIC-SPECIFIC APIS for the tea.

If you're building something brand new, the recommended usage depends on three independent design decisions. Think of them like three separate sliders, bestie:

If the application does nonblocking I/O at the application level, it can choose to manage its own polling and event loop; see APPLICATION-DRIVEN EVENT LOOPS.

  • Direct socket access or buffered datagrams? Does the application intend to give the QUIC implementation direct access to a network socket (e.g. via BIO_s_datagram(3)), or does it intend to buffer transmitted and received datagrams via a 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.

  • Thread assisted mode? Will it be used? See THREAD ASSISTED MODE.

Simple demos for QUIC usage under these various scenarios can be found at 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 QUIC-SPECIFIC APIS, which provide access to QUIC-specific functionality. For example, SSL_stream_conclude(3) can be used to indicate the end of the sending part of a stream, and SSL_shutdown_ex(3) can be used to provide a QUIC application error code when closing a connection.

Regardless of the design decisions chosen above, it is recommended that new applications avoid use of the default stream mode and use the multi-stream API by calling SSL_set_default_stream_mode(3); see the MODES OF OPERATION section for details.

✨ QUIC-SPECIFIC APIS ✨

okay so this section details new APIs which are directly or indirectly related to QUIC. For the full tea on the operation of each API, see the referenced man pages—iykyk 💅

The following SSL APIs are new but relevant to both QUIC and DTLS:

  • SSL_get_event_timeout(3) — Determines when the QUIC implementation should next be woken up via a call to SSL_handle_events(3) (or another I/O function such as SSL_read(3) or SSL_write(3)), if ever. This can also be used with DTLS and supersedes DTLSv1_get_timeout(3) for new usage.
  • SSL_handle_events(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 SSL_read(3) and SSL_write(3), implicitly perform event handling on 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 DTLSv1_handle_timeout(3) for new usage.

The following SSL APIs are specific to QUIC—and bestie, this list is long but every single one is eating:

  • SSL_new_listener(3) — Creates a listener SSL object, which differs from an ordinary SSL object in that it is used to provide an abstraction for the acceptance of network connections in a protocol-agnostic manner. Currently, listener SSL objects are only supported for QUIC server usage or client-only usage. The listener interface may expand to support additional protocols in the future.
  • SSL_new_listener_from(3) — Creates a listener SSL object which is subordinate to a QUIC domain SSL object ssl. See SSL_new_domain(3) and openssl-quic-concurrency(7) for details on QUIC domain SSL objects.
  • SSL_is_listener(3) — Returns 1 if and only if an SSL object is a listener SSL object.
  • SSL_get0_listener(3) — Returns an SSL object pointer (potentially to the same object on which it is called) or NULL.
  • SSL_listen(3) — Begin listening after a listener has been created. It is ordinarily not needed to call this because it will be called automatically on the first call to SSL_accept_connection(3).
  • SSL_accept_connection(3) — Accepts a new incoming connection for a listner SSL object. A new SSL object representing the accepted connection is created and returned on success. If no incoming connection is available and the listener SSL object is configured in nonblocking mode, NULL is returned.
  • SSL_get_accept_connection_queue_len(3) — Returns an informational value listing the number of connections waiting to be popped from the queue via calls to SSL_accept_connection().
  • SSL_new_from_listener(3) — Creates a client connection under a given listener SSL object. For QUIC, it is also possible to use SSL_new_from_listener() in conjunction with a listener which does accept incoming connections (i.e., which was not created using SSL_LISTENER_FLAG_NO_ACCEPT), leading to a UDP network endpoint which has both incoming and outgoing connections.
  • SSL_new_domain(3) — Creates a new QUIC event domain, represented as an SSL object. This is known as a QUIC domain SSL object. The concept of a QUIC event domain is discussed in detail in openssl-quic-concurrency(7).
  • SSL_is_domain(3) — Returns 1 if an SSL object is a QUIC domain SSL object.
  • SSL_get0_domain(3) — SSL_get0_domain() obtains a pointer to the QUIC domain SSL object in an SSL object hierarchy (if any).
  • SSL_set_blocking_mode(3), SSL_get_blocking_mode(3) — Configures whether blocking semantics are used at the application level. This determines whether calls to functions such as SSL_read(3) and SSL_write(3) will block.
  • SSL_get_rpoll_descriptor(3), 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, 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 SSL_handle_events(3). SSL_get_wpoll_descriptor(3) works in an analogous fashion for the underlying network write BIO. The poll descriptors provided by these functions should be used only when SSL_net_read_desired(3) and SSL_net_write_desired(3) return 1, respectively. 🦋
  • SSL_net_read_desired(3), SSL_net_write_desired(3) — These functions facilitate operation in nonblocking mode and are used in conjunction with SSL_get_rpoll_descriptor(3) and SSL_get_wpoll_descriptor(3) respectively. They determine whether the respective poll descriptor is currently relevant for the purposes of polling.
  • SSL_set1_initial_peer_addr(3) — This function 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 SSL_set1_initial_peer_addr(3) for details.
  • SSL_shutdown_ex(3) — This augments SSL_shutdown(3) by allowing an application error code to be specified. It also allows an application to decide how quickly it wants a shutdown to be performed, potentially by trading off strict RFC compliance.
  • 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.
  • SSL_stream_reset(3) — This allows an application to indicate the non-normal termination of the sending part of a stream. This corresponds to the RESET_STREAM frame in the QUIC RFC.
  • SSL_get_stream_write_state(3) and SSL_get_stream_read_state(3) — This allows an application to determine the current stream states for the sending and receiving parts of a stream respectively.
  • SSL_get_stream_write_error_code(3) and SSL_get_stream_read_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 of the respective sending or receiving part of a stream, if any.
  • 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.
  • SSL_get0_connection(3) — Gets the QUIC connection SSL object from a QUIC stream SSL object.
  • SSL_is_connection(3) — Returns 1 if an SSL object is not a QUIC stream SSL object.
  • SSL_get_stream_type(3) — Provides information on the kind of QUIC stream which is attached to the SSL object.
  • SSL_get_stream_id(3) — Returns the QUIC stream ID which the QUIC protocol has associated with a QUIC stream.
  • SSL_new_stream(3) — Creates a new QUIC stream SSL object representing a new, locally-initiated QUIC stream.
  • SSL_accept_stream(3) — Potentially yields a new QUIC stream SSL object representing a new remotely-initiated QUIC stream, blocking until one is available if the connection is configured to do so.
  • SSL_get_accept_stream_queue_len(3) — Provides information on the number of pending remotely-initiated streams.
  • SSL_set_incoming_stream_policy(3) — Configures how incoming, remotely-initiated streams are handled. The incoming stream policy can be used to automatically reject streams created by the peer, or allow them to be handled using SSL_accept_stream(3).
  • SSL_set_default_stream_mode(3) — Used to configure or disable default stream mode; see the MODES OF OPERATION section for details.

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—supporting cast, but they still ate:

💅 THREAD ASSISTED MODE

okay so there's this optional thread assisted mode for clients, and you turn it on with OSSL_QUIC_client_thread_method(3). bestie, what happens is a background thread just… spawns itself automatically ✨. And then OpenSSL's QUIC implementation takes full responsibility for making sure timeout events get handled on a timely basis, even if your app doesn't call an SSL I/O function like SSL_read(3) or SSL_write(3) for a long time. like, it just handles it. iconic behavior honestly 💖.

All the necessary locking is handled automatically, internally, but — and this is important — the thread safety guarantees for the public SSL API are unchanged. So your application still has to do its own locking if it wants to make concurrent use of the public SSL APIs. no cap, that part is on you 🫶.

Because this method relies on threads, it's not available on platforms where threading support isn't available, or isn't supported by OpenSSL 😭. But when it is available? It gives you the simplest mode of usage for an application. periodt.

heads up: the implementation may or may not use a common thread or thread pool to service multiple SSL objects in the same SSL_CTX. iykyk — don't build your whole life around it 💀.

🌈 APPLICATION-DRIVEN EVENT LOOPS

OpenSSL's QUIC implementation is designed to facilitate applications that want to use the SSL APIs in a blocking fashion — but it's also designed to facilitate applications that want to use the SSL APIs in a nonblocking fashion and manage their own event loops and polling directly 🔥. That second one is super useful when you want to host OpenSSL's QUIC implementation on top of your application's existing nonblocking I/O infrastructure. it's giving "fit seamlessly into your existing setup" 💅.

This is supported via the concept of poll descriptors — peep BIO_get_rpoll_descriptor(3) for the details. Broadly speaking, a BIO_POLL_DESCRIPTOR is a structure that expresses some kind of OS resource which can be used to synchronise on I/O events. The QUIC implementation provides a BIO_POLL_DESCRIPTOR based on the poll descriptor provided by the underlying network BIO. Typically that's an OS socket handle, though custom BIOs could choose to implement their own custom poll descriptor format ✨.

Broadly, an application that wishes to manage its own event loop should interact with the SSL object like this:

Once any of these events occurs, SSL_handle_events(3) should be called 👑

  • If the network read and write BIOs provided were not pollable (for example, in the case of BIO_s_dgram_pair(3)), the application is responsible for managing and synchronising network I/O. It should call SSL_handle_events(3) after it writes data to a BIO_s_dgram_pair(3) or otherwise takes action so that the QUIC implementation can read new datagrams via a call to BIO_recvmmsg(3) on the underlying network BIO. The QUIC implementation may output datagrams via a call to BIO_sendmmsg(3) and the application is responsible for ensuring these are transmitted 🫡.

The application must call SSL_get_event_timeout(3) after every call to SSL_handle_events(3) (or another I/O function on the SSL object), and ensure that a call to SSL_handle_events(3) is performed after the specified timeout (if any). no skipping this one bestie, fr fr 😤

✨ SEE ALSO

okay gather round, the whole squad is here 🎀:

SSL_handle_events(3), SSL_get_event_timeout(3), SSL_net_read_desired(3), SSL_net_write_desired(3), SSL_get_rpoll_descriptor(3), SSL_get_wpoll_descriptor(3), SSL_set_blocking_mode(3), SSL_shutdown_ex(3), SSL_set1_initial_peer_addr(3), SSL_stream_conclude(3), SSL_stream_reset(3), SSL_get_stream_read_state(3), SSL_get_stream_read_error_code(3), SSL_get_conn_close_info(3), SSL_get0_connection(3), SSL_get_stream_type(3), SSL_get_stream_id(3), SSL_new_stream(3), SSL_accept_stream(3), SSL_set_incoming_stream_policy(3), SSL_set_default_stream_mode(3), SSL_new_listener(3), SSL_new_listener_from(3), SSL_is_listener(3), SSL_get0_listener(3), SSL_listen(3), SSL_accept_connection(3), SSL_get_accept_connection_queue_len(3), SSL_new_domain(3), SSL_is_domain(3), SSL_get0_domain(3)

Copyright 2022-2025 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 <https://www.openssl.org/source/license.html>.

that's a wrap bestie 💖 this whole thing is from OpenSSL 3.5.0, dated 2026-09-25, and the page is OPENSSL-QUIC(7ossl) — go forth and slay your QUIC implementation 🌈👑✨

📦 where this page comes from