15 are needed to existing applications making use of the libssl APIs to make use of
21 mode, which is intended to provide compatibility with existing non-QUIC
23 stream associated with it. Calls to L<SSL_read(3)> and
30 applications. New applications using QUIC are recommended to disable default
44 The changes to existing libssl APIs which are driven by QUIC-related implementation
70 In default stream mode, a stream is implicitly created and bound to the QUIC
71 connection SSL object; L<SSL_read(3)> and L<SSL_write(3)> calls to the QUIC
72 connection SSL object work by default and are mapped to that stream.
76 case it affects the default stream bound to the connection.
80 mode, if a client application calls L<SSL_read(3)> first before any call to
85 application calls L<SSL_write(3)> before any call to L<SSL_read(3)> on the
86 connection, it is assumed that a client-initiated stream is to be used
89 Default stream mode is intended to aid compatibility with legacy applications.
93 It is possible to use additional streams in default stream mode using
95 stream policy will need to be changed using L<SSL_set_incoming_stream_policy(3)>
96 in order to use L<SSL_accept_stream(3)> in this case. However, applications
97 using additional streams are strongly recommended to use multi-stream mode
107 mode, in which no default stream is attached to the QUIC connection SSL object
108 and attempts to call L<SSL_read(3)> and L<SSL_write(3)> on the QUIC connection
110 L<SSL_accept_stream(3)> to create individual stream SSL objects for sending and
115 to initiating the connection. The default stream mode cannot be changed after
119 with the connection, calls to API functions which are defined as operating on a
127 changes to the semantics of existing APIs are as follows:
135 semantics. There are broadly four options for applications to use as a network
149 memory BIO to manage libssl's communication with the network.
158 An application may also choose to implement a custom BIO. The new
167 a L<BIO_s_datagram(3)>. This is equivalent to instantiating a
182 application can still enjoy blocking semantics for calls to application-level
184 network BIO provided to QUIC (such as a L<BIO_s_datagram(3)>) must be configured
190 L<BIO_new_ssl_connect(3)> has been changed to automatically use a
192 do not need to change the BIO they use.
197 change to use L<BIO_new_ssl_connect(3)> instead.
201 L<SSL_shutdown(3)> has significant changes in relation to how QUIC connections
211 the I/O state of the network BIO passed to the QUIC SSL object, but instead
216 receive part of a QUIC stream does not currently have any more data available to
220 To determine if the QUIC implementation currently wishes to be informed of
222 likewise, to determine if the QUIC implementation currently wishes to be
223 informed when it is possible to transmit network datagrams, use the new function
224 L<SSL_net_write_desired(3)>. Only applications which wish to manage their own event
225 loops need to use these functions; see B<APPLICATION-DRIVEN EVENT LOOPS> for
230 The use of ALPN is mandatory when using QUIC. Attempts to connect without
231 configuring ALPN will fail. For information on how to configure ALPN, see
237 B<SSL_METHOD> used, rather than by calls to L<SSL_set_connect_state(3)> or
238 L<SSL_set_accept_state(3)>. It is not necessary to call either of
246 not used and the values passed to them are ignored, as OpenSSL QUIC currently
291 to older TLS versions is not available.
296 for QUIC, such as B<TLS_AES_128_CCM_8_SHA256>. Your application may need to
297 adjust the list of acceptable cipher suites it passes to libssl.
306 but calls to the relevant functions are treated as no-ops:
320 Existing applications seeking to adopt QUIC should apply the following list to
321 determine what changes they will need to make:
327 An application wishing to use QUIC must use L<OSSL_QUIC_client_method(3)> or
333 Determine how to provide QUIC with network access. Determine which of the below
340 Your application uses L<BIO_s_socket(3)> to construct a BIO which is passed to
341 the SSL object to provide it with network access.
343 Changes needed: Change your application to use L<BIO_s_datagram(3)> instead when
345 not need to use L<SSL_set1_initial_peer_addr(3)> to set the initial peer
350 Your application uses L<BIO_new_ssl_connect(3)> to
351 construct a BIO which is passed to the SSL object to provide it with network
368 Your application uses a BIO pair to cause the SSL object to read and write
369 network traffic to a memory buffer. Your application manages the transmission
370 and reception of buffered data itself in a way unknown to libssl.
372 Changes needed: Switch from using a conventional BIO pair to using
374 will need to modify your application to transmit and receive using a UDP socket
375 and to use datagram semantics when interacting with the L<BIO_s_dgram_pair(3)>
380 Your application uses a custom BIO method to provide the SSL object with network
383 Changes needed: The custom BIO must be re-architected to have datagram
394 An application must explicitly configure whether it wishes to use the SSL APIs
401 wishes to use the SSL object APIs at application level in a nonblocking manner,
402 it must add a call to L<SSL_set_blocking_mode(3)> to disable blocking mode.
406 If your application does not choose to use thread assisted mode, it must ensure
409 SSL object is used in blocking mode, an ongoing blocking call to an I/O function
410 satisfies this requirement. This is required to ensure that timer events
417 L<SSL_get_event_timeout(3)> can be used to determine when
422 L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)> to obtain
423 resources which can be used to determine when L<SSL_handle_events(3)> should be
424 called due to network I/O.
426 Applications which use thread assisted mode do not need to be concerned
434 APIS>. In particular, you should use these APIs to determine the ability of a
435 QUIC stream to receive or provide application data, not to to determine if
442 wishes to prioritise RFC conformance or rapid shutdown, consider using the new
460 to manage its own polling and event loop; see B<APPLICATION-DRIVEN EVENT LOOPS>.
464 Whether the application intends to give the QUIC implementation direct access to
465 a network socket (e.g. via L<BIO_s_datagram(3)>) or whether it intends to buffer
468 The former is preferred where possible as it reduces latency to the network,
469 which enables QUIC to achieve higher performance and more accurate connection
481 Applications which wish to implement QUIC-specific protocols should be aware of
482 the APIs listed under B<QUIC-SPECIFIC APIS> which provide access to
484 to indicate the end of the sending part of a stream, and L<SSL_shutdown_ex(3)>
485 can be used to provide a QUIC application error code when closing a connection.
494 This section details new APIs which are directly or indirectly related to QUIC.
497 The following SSL APIs are new but relevant to both QUIC and DTLS:
503 Determines when the QUIC implementation should next be woken up via a call to
512 This is a non-specific I/O operation which makes a best effort attempt to
513 perform any pending I/O or timeout processing. It can be used to advance the
518 only needed if no other I/O function is to be called.
525 The following SSL APIs are specific to QUIC:
532 determines whether calls to functions such as L<SSL_read(3)> and L<SSL_write(3)>
541 can be used to synchronise on network readability events which should result in
542 a call to L<SSL_handle_events(3)>. L<SSL_get_wpoll_descriptor(3)> works in an
557 This function can be used to set the initial peer address for an outgoing QUIC
564 This augments L<SSL_shutdown(3)> by allowing an application error code to be
565 specified. It also allows a client to decide how quickly it wants a shutdown to
570 This allows an application to indicate the normal end of the sending part of a
571 QUIC stream. This corresponds to the FIN flag in the QUIC RFC. The receiving
576 This allows an application to indicate the non-normal termination of the sending
577 part of a stream. This corresponds to the RESET_STREAM frame in the QUIC RFC.
581 This allows an application to determine the current stream states for the
586 This allows an application to determine the application error code which was
592 This allows an application to determine the error code which was signalled when
606 to the SSL object.
622 connection is configured to do so.
631 stream policy can be used to automatically reject streams created by the peer,
632 or allow them to be handled using L<SSL_accept_stream(3)>.
636 Used to configure or disable default stream mode; see the MODES OF OPERATION
641 The following BIO APIs are not specific to QUIC but have been added to
648 This is a new BIO method which is similar to a conventional BIO pair but
653 This is a new BIO API which allows a BIO to expose a poll descriptor. This API
654 is used to implement the corresponding SSL APIs L<SSL_get_rpoll_descriptor(3)>
661 It is used by the QUIC implementation to send and receive UDP datagrams.
665 By default, L<BIO_s_dgram_pair(3)> has semantics comparable to those of Berkeley
667 to be enabled in which datagrams will not be silently truncated if they are
672 These functions are used to allow the user of one end of a
673 L<BIO_s_dgram_pair(3)> to indicate its capabilities to the other end of a
674 L<BIO_s_dgram_pair(3)>. In particular, this allows an application to inform the
675 QUIC implementation of whether it is prepared to handle local and/or peer
676 addresses in transmitted datagrams and to provide the applicable information in
682 Local addressing support refers to the ability of a BIO with datagram semantics
683 to allow a source address to be specified on transmission and to report the
684 destination address on reception. These functions can be used to determine if a
685 BIO can support local addressing and to enable local addressing support if it
690 This is used to determine if an error while calling L<BIO_sendmmsg(3)> or
706 still do its own locking if it wishes to make concurrent use of the public SSL
713 The implementation may or may not use a common thread or thread pool to service
718 OpenSSL's QUIC implementation is designed to facilitate applications which wish
719 to use the SSL APIs in a blocking fashion, but is also designed to facilitate
720 applications which wish to use the SSL APIs in a nonblocking fashion and manage
722 to host OpenSSL's QUIC implementation on top of an application's existing
727 a structure which expresses some kind of OS resource which can be used to
731 choose to implement their own custom poll descriptor format.
733 Broadly, an application which wishes to manage its own event loop should
740 It should provide read and write BIOs with nonblocking datagram semantics to
769 L<SSL_get_wpoll_descriptor(3)> to identify OS resources which can be used for
774 It should call L<SSL_net_read_desired(3)> and L<SSL_net_write_desired(3)> to determine
777 L<SSL_get_event_timeout(3)> to determine if any timeout event will become
811 writes data to a L<BIO_s_dgram_pair(3)> or otherwise takes action so that the
812 QUIC implementation can read new datagrams via a call to L<BIO_recvmmsg(3)> on
814 call to L<BIO_sendmmsg(3)> and the application is responsible for ensuring these
817 The application must call L<SSL_get_event_timeout(3)> after every call to
819 that a call to L<SSL_handle_events(3)> is performed after the specified timeout

Last Index update Mon Nov 25 20:08:26 UTC 2024

Dedicated to & Maintained by Room-11