1*e7be843bSPierre Pronchery=pod 2*e7be843bSPierre Pronchery 3*e7be843bSPierre Pronchery=head1 NAME 4*e7be843bSPierre Pronchery 5*e7be843bSPierre Proncheryossl-guide-quic-introduction 6*e7be843bSPierre Pronchery- OpenSSL Guide: An introduction to QUIC in OpenSSL 7*e7be843bSPierre Pronchery 8*e7be843bSPierre Pronchery=head1 INTRODUCTION 9*e7be843bSPierre Pronchery 10*e7be843bSPierre ProncheryThis page will provide an introduction to some basic QUIC concepts and 11*e7be843bSPierre Proncherybackground and how it is used within OpenSSL. It assumes that you have a basic 12*e7be843bSPierre Proncheryunderstanding of UDP/IP and sockets. It also assumes that you are familiar with 13*e7be843bSPierre Proncherysome OpenSSL and TLS fundamentals (see L<ossl-guide-libraries-introduction(7)> 14*e7be843bSPierre Proncheryand L<ossl-guide-tls-introduction(7)>). 15*e7be843bSPierre Pronchery 16*e7be843bSPierre Pronchery=head1 WHAT IS QUIC? 17*e7be843bSPierre Pronchery 18*e7be843bSPierre ProncheryQUIC is a general purpose protocol for enabling applications to securely 19*e7be843bSPierre Proncherycommunicate over a network. It is defined in RFC9000 (see 20*e7be843bSPierre ProncheryL<https://datatracker.ietf.org/doc/rfc9000/>). QUIC integrates parts of the 21*e7be843bSPierre ProncheryTLS protocol for connection establishment but independently protects packets. 22*e7be843bSPierre ProncheryIt provides similar security guarantees to TLS such as confidentiality, 23*e7be843bSPierre Proncheryintegrity and authentication (see L<ossl-guide-tls-introduction(7)>). 24*e7be843bSPierre Pronchery 25*e7be843bSPierre ProncheryQUIC delivers a number of advantages: 26*e7be843bSPierre Pronchery 27*e7be843bSPierre Pronchery=over 4 28*e7be843bSPierre Pronchery 29*e7be843bSPierre Pronchery=item Multiple streams 30*e7be843bSPierre Pronchery 31*e7be843bSPierre ProncheryIt supports multiple streams of communication (see L</QUIC STREAMS> below), 32*e7be843bSPierre Proncheryallowing application protocols built on QUIC to create arbitrarily many 33*e7be843bSPierre Proncherybytestreams for communication between a client and server. This allows an 34*e7be843bSPierre Proncheryapplication protocol to avoid problems where one packet of data is held up 35*e7be843bSPierre Proncherywaiting on another packet being delivered (commonly referred to as 36*e7be843bSPierre Pronchery"head-of-line blocking"). It also enables an application to open additional 37*e7be843bSPierre Proncherylogical streams without requiring a round-trip exchange of packets between the 38*e7be843bSPierre Proncheryclient and server as is required when opening an additional TLS/TCP 39*e7be843bSPierre Proncheryconnection. 40*e7be843bSPierre Pronchery 41*e7be843bSPierre Pronchery=item HTTP/3 42*e7be843bSPierre Pronchery 43*e7be843bSPierre ProncherySince QUIC is the basis of HTTP/3, support for QUIC also enables applications 44*e7be843bSPierre Proncheryto use HTTP/3 using a suitable third-party library. 45*e7be843bSPierre Pronchery 46*e7be843bSPierre Pronchery=item Fast connection initiation 47*e7be843bSPierre Pronchery 48*e7be843bSPierre ProncheryFuture versions of OpenSSL will offer support for 0-RTT connection initiation, 49*e7be843bSPierre Proncheryallowing a connection to be initiated to a server and application data to be 50*e7be843bSPierre Proncherytransmitted without any waiting time. This is similar to TLS 1.3's 0-RTT 51*e7be843bSPierre Proncheryfunctionality but also avoids the round trip needed to open a TCP socket; thus, 52*e7be843bSPierre Proncheryit is similar to a combination of TLS 1.3 0-RTT and TCP Fast Open. 53*e7be843bSPierre Pronchery 54*e7be843bSPierre Pronchery=item Connection migration 55*e7be843bSPierre Pronchery 56*e7be843bSPierre ProncheryFuture versions of OpenSSL will offer support for connection migration, allowing 57*e7be843bSPierre Proncheryconnections to seamlessly survive IP address changes. 58*e7be843bSPierre Pronchery 59*e7be843bSPierre Pronchery=item Datagram based use cases 60*e7be843bSPierre Pronchery 61*e7be843bSPierre ProncheryFuture versions of OpenSSL will offer support for the QUIC datagram extension, 62*e7be843bSPierre Proncheryallowing support for both TLS and DTLS-style use cases on a single connection. 63*e7be843bSPierre Pronchery 64*e7be843bSPierre Pronchery=item Implemented as application library 65*e7be843bSPierre Pronchery 66*e7be843bSPierre ProncheryBecause most QUIC implementations, including OpenSSL's implementation, are 67*e7be843bSPierre Proncheryimplemented as an application library rather than by an operating system, an 68*e7be843bSPierre Proncheryapplication can gain the benefit of QUIC without needing to wait for an OS 69*e7be843bSPierre Proncheryupdate to be deployed. Future evolutions and enhancements to the QUIC protocol 70*e7be843bSPierre Proncherycan be delivered as quickly as an application can be updated without dependency 71*e7be843bSPierre Proncheryon an OS update cadence. 72*e7be843bSPierre Pronchery 73*e7be843bSPierre Pronchery=item Multiplexing over a single UDP socket 74*e7be843bSPierre Pronchery 75*e7be843bSPierre ProncheryBecause QUIC is UDP-based, it is possible to multiplex a QUIC connection on the 76*e7be843bSPierre Proncherysame UDP socket as some other UDP-based protocols, such as RTP. 77*e7be843bSPierre Pronchery 78*e7be843bSPierre Pronchery=back 79*e7be843bSPierre Pronchery 80*e7be843bSPierre Pronchery=head1 QUIC TIME BASED EVENTS 81*e7be843bSPierre Pronchery 82*e7be843bSPierre ProncheryA key difference between the TLS implementation and the QUIC implementation in 83*e7be843bSPierre ProncheryOpenSSL is how time is handled. The QUIC protocol requires various actions to be 84*e7be843bSPierre Proncheryperformed on a regular basis regardless of whether application data is being 85*e7be843bSPierre Proncherytransmitted or received. 86*e7be843bSPierre Pronchery 87*e7be843bSPierre ProncheryOpenSSL introduces a new function L<SSL_handle_events(3)> that will 88*e7be843bSPierre Proncheryautomatically process any outstanding time based events that must be handled. 89*e7be843bSPierre ProncheryAlternatively calling any I/O function such as L<SSL_read_ex(3)> or 90*e7be843bSPierre ProncheryL<SSL_write_ex(3)> will also process these events. There is also 91*e7be843bSPierre ProncheryL<SSL_get_event_timeout(3)> which tells an application the amount of time that 92*e7be843bSPierre Proncheryremains until L<SSL_handle_events(3)> (or any I/O function) must be called. 93*e7be843bSPierre Pronchery 94*e7be843bSPierre ProncheryFortunately a blocking application that does not leave the QUIC connection idle, 95*e7be843bSPierre Proncheryand is regularly calling I/O functions does not typically need to worry about 96*e7be843bSPierre Proncherythis. However if you are developing a nonblocking application or one that may 97*e7be843bSPierre Proncheryleave the QUIC connection idle for a period of time then you will need to 98*e7be843bSPierre Proncheryarrange to call these functions. 99*e7be843bSPierre Pronchery 100*e7be843bSPierre ProncheryOpenSSL provides an optional "thread assisted mode" that will automatically 101*e7be843bSPierre Proncherycreate a background thread and will regularly call L<SSL_handle_events(3)> in a 102*e7be843bSPierre Proncherythread safe manner. This provides a simple way for an application to satisfy the 103*e7be843bSPierre ProncheryQUIC requirements for time based events without having to implement special 104*e7be843bSPierre Proncherylogic to accomplish it. 105*e7be843bSPierre Pronchery 106*e7be843bSPierre Pronchery=head1 QUIC AND TLS 107*e7be843bSPierre Pronchery 108*e7be843bSPierre ProncheryQUIC reuses parts of the TLS protocol in its implementation. Specifically the 109*e7be843bSPierre ProncheryTLS handshake also exists in QUIC. The TLS handshake messages are wrapped up in 110*e7be843bSPierre ProncheryQUIC protocol messages in order to send them to the peer. Once the TLS handshake 111*e7be843bSPierre Proncheryis complete all application data is sent entirely using QUIC protocol messages 112*e7be843bSPierre Proncherywithout using TLS - although some TLS handshake messages may still be sent in 113*e7be843bSPierre Proncherysome circumstances. 114*e7be843bSPierre Pronchery 115*e7be843bSPierre ProncheryThis relationship between QUIC and TLS means that many of the API functions in 116*e7be843bSPierre ProncheryOpenSSL that apply to TLS connections also apply to QUIC connections and 117*e7be843bSPierre Proncheryapplications can use them in exactly the same way. Some functions do not apply 118*e7be843bSPierre Proncheryto QUIC at all, and others have altered semantics. You should refer to the 119*e7be843bSPierre Proncherydocumentation pages for each function for information on how it applies to QUIC. 120*e7be843bSPierre ProncheryTypically if QUIC is not mentioned in the manual pages then the functions apply 121*e7be843bSPierre Proncheryto both TLS and QUIC. 122*e7be843bSPierre Pronchery 123*e7be843bSPierre Pronchery=head1 QUIC STREAMS 124*e7be843bSPierre Pronchery 125*e7be843bSPierre ProncheryQUIC introduces the concept of "streams". A stream provides a reliable 126*e7be843bSPierre Proncherymechanism for sending and receiving application data between the endpoints. The 127*e7be843bSPierre Proncherybytes transmitted are guaranteed to be received in the same order they were sent 128*e7be843bSPierre Proncherywithout any loss of data or reordering of the bytes. A TLS application 129*e7be843bSPierre Proncheryeffectively has one bi-directional stream available to it per TLS connection. A 130*e7be843bSPierre ProncheryQUIC application can have multiple uni-directional or bi-directional streams 131*e7be843bSPierre Proncheryavailable to it for each connection. 132*e7be843bSPierre Pronchery 133*e7be843bSPierre ProncheryIn OpenSSL an B<SSL> object is used to represent both connections and streams. 134*e7be843bSPierre ProncheryA QUIC application creates an initial B<SSL> object to represent the connection 135*e7be843bSPierre Pronchery(known as the connection B<SSL> object). Once the connection is complete 136*e7be843bSPierre Proncheryadditional B<SSL> objects can be created to represent streams (known as stream 137*e7be843bSPierre ProncheryB<SSL> objects). Unless configured otherwise, a "default" stream is also 138*e7be843bSPierre Proncheryassociated with the connection B<SSL> object so you can still write data and 139*e7be843bSPierre Proncheryread data to/from it. Some OpenSSL API functions can only be used with 140*e7be843bSPierre Proncheryconnection B<SSL> objects, and some can only be used with stream B<SSL> objects. 141*e7be843bSPierre ProncheryCheck the documentation for each function to confirm what type of B<SSL> object 142*e7be843bSPierre Proncherycan be used in any particular context. A connection B<SSL> object that has a 143*e7be843bSPierre Proncherydefault stream attached to it can be used in contexts that require a connection 144*e7be843bSPierre ProncheryB<SSL> object or in contexts that require a stream B<SSL> object. 145*e7be843bSPierre Pronchery 146*e7be843bSPierre Pronchery=head1 SOCKETS AND BLOCKING 147*e7be843bSPierre Pronchery 148*e7be843bSPierre ProncheryTLS assumes "stream" type semantics for its underlying transport layer protocol 149*e7be843bSPierre Pronchery(usually achieved by using TCP). However QUIC assumes "datagram" type semantics 150*e7be843bSPierre Proncheryby using UDP. An OpenSSL application using QUIC is responsible for creating a 151*e7be843bSPierre ProncheryBIO to represent the underlying transport layer. This BIO must support datagrams 152*e7be843bSPierre Proncheryand is typically L<BIO_s_datagram(3)>, but other B<BIO> choices are available. 153*e7be843bSPierre ProncherySee L<bio(7)> for an introduction to OpenSSL's B<BIO> concept. 154*e7be843bSPierre Pronchery 155*e7be843bSPierre ProncheryA significant difference between OpenSSL TLS applications and OpenSSL QUIC 156*e7be843bSPierre Proncheryapplications is the way that blocking is implemented. In TLS if your application 157*e7be843bSPierre Proncheryexpects blocking behaviour then you configure the underlying socket for 158*e7be843bSPierre Proncheryblocking. Conversely if your application wants nonblocking behaviour then the 159*e7be843bSPierre Proncheryunderlying socket is configured to be nonblocking. 160*e7be843bSPierre Pronchery 161*e7be843bSPierre ProncheryWith an OpenSSL QUIC application the underlying socket must always be configured 162*e7be843bSPierre Proncheryto be nonblocking. Howevever the B<SSL> object will, by default, still operate 163*e7be843bSPierre Proncheryin blocking mode. So, from an application's perspective, calls to functions such 164*e7be843bSPierre Proncheryas L<SSL_read_ex(3)>, L<SSL_write_ex(3)> and other I/O functions will still 165*e7be843bSPierre Proncheryblock. OpenSSL itself provides that blocking capability for QUIC instead of the 166*e7be843bSPierre Proncherysocket. If nonblocking behaviour is desired then the application must call 167*e7be843bSPierre ProncheryL<SSL_set_blocking_mode(3)>. 168*e7be843bSPierre Pronchery 169*e7be843bSPierre Pronchery=head1 FURTHER READING 170*e7be843bSPierre Pronchery 171*e7be843bSPierre ProncherySee L<ossl-guide-quic-client-block(7)> to see an example of applying these 172*e7be843bSPierre Proncheryconcepts in order to write a simple blocking QUIC client. 173*e7be843bSPierre Pronchery 174*e7be843bSPierre ProncherySee L<ossl-guide-quic-server-block(7)> to see an example of applying these 175*e7be843bSPierre Proncheryconcepts in order to write a simple blocking QUIC server. 176*e7be843bSPierre Pronchery 177*e7be843bSPierre Pronchery=head1 SEE ALSO 178*e7be843bSPierre Pronchery 179*e7be843bSPierre ProncheryL<ossl-guide-introduction(7)>, L<ossl-guide-libraries-introduction(7)>, 180*e7be843bSPierre ProncheryL<ossl-guide-libssl-introduction(7)>, L<ossl-guide-tls-introduction(7)>, 181*e7be843bSPierre ProncheryL<ossl-guide-tls-client-block(7)>, L<ossl-guide-quic-client-block(7)>, 182*e7be843bSPierre ProncheryL<ossl-guide-quic-client-non-block(7)>, L<ossl-guide-quic-multi-stream(7)>, 183*e7be843bSPierre ProncheryL<ossl-guide-quic-server-block(7)>, L<ossl-guide-quic-server-non-block(7)>, 184*e7be843bSPierre ProncheryL<bio(7)>, 185*e7be843bSPierre Pronchery 186*e7be843bSPierre Pronchery=head1 COPYRIGHT 187*e7be843bSPierre Pronchery 188*e7be843bSPierre ProncheryCopyright 2023-2025 The OpenSSL Project Authors. All Rights Reserved. 189*e7be843bSPierre Pronchery 190*e7be843bSPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 191*e7be843bSPierre Proncherythis file except in compliance with the License. You can obtain a copy 192*e7be843bSPierre Proncheryin the file LICENSE in the source distribution or at 193*e7be843bSPierre ProncheryL<https://www.openssl.org/source/license.html>. 194*e7be843bSPierre Pronchery 195*e7be843bSPierre Pronchery=cut 196