1*e7be843bSPierre ProncheryQUIC Design Overview 2*e7be843bSPierre Pronchery==================== 3*e7be843bSPierre Pronchery 4*e7be843bSPierre ProncheryThe QUIC implementation in OpenSSL is roughly described by the following 5*e7be843bSPierre Proncherypicture. 6*e7be843bSPierre Pronchery 7*e7be843bSPierre Pronchery 8*e7be843bSPierre Pronchery 9*e7be843bSPierre ProncherySSL API 10*e7be843bSPierre Pronchery------- 11*e7be843bSPierre Pronchery 12*e7be843bSPierre ProncheryThe application facing public API of the OpenSSL library. 13*e7be843bSPierre Pronchery 14*e7be843bSPierre ProncheryStream Send and Read Buffers 15*e7be843bSPierre Pronchery---------------------------- 16*e7be843bSPierre Pronchery 17*e7be843bSPierre ProncheryBuffers for stream data to be sent or received from the peer over the 18*e7be843bSPierre ProncheryQUIC protocol. These are necessary to support existing semantics of the 19*e7be843bSPierre ProncherySSL_read and SSL_write functions. 20*e7be843bSPierre Pronchery 21*e7be843bSPierre ProncheryThey will be bypassed with a single-copy API for read and write (_not 22*e7be843bSPierre Proncheryfor MVP_). 23*e7be843bSPierre Pronchery 24*e7be843bSPierre ProncheryFrame in Flight Manager 25*e7be843bSPierre Pronchery----------------------- 26*e7be843bSPierre Pronchery 27*e7be843bSPierre ProncheryThe frame in flight manager manages the queueing of frames which may need to be 28*e7be843bSPierre Proncheryretransmitted if the packets in which they were transmitted were lost. It is 29*e7be843bSPierre Pronchery[discussed in more detail here.](./quic-fifm.md) 30*e7be843bSPierre Pronchery 31*e7be843bSPierre ProncheryConnection State Machine 32*e7be843bSPierre Pronchery------------------------ 33*e7be843bSPierre Pronchery 34*e7be843bSPierre ProncheryA state machine handling the state for a QUIC connection. 35*e7be843bSPierre Pronchery 36*e7be843bSPierre ProncheryConnection ID Cache 37*e7be843bSPierre Pronchery------------------- 38*e7be843bSPierre Pronchery 39*e7be843bSPierre ProncheryA table matching Connection IDs with Connection objects represented 40*e7be843bSPierre Proncheryvia SSL objects. 41*e7be843bSPierre Pronchery 42*e7be843bSPierre Pronchery_In MVP there is a many-to-1 matching of Connection IDs to Connection 43*e7be843bSPierre Proncheryobjects. Refer third paragraph in [5.1]_ 44*e7be843bSPierre Pronchery 45*e7be843bSPierre Pronchery[5.1]: (https://datatracker.ietf.org/doc/html/rfc9000#section-5.1) 46*e7be843bSPierre Pronchery 47*e7be843bSPierre ProncheryTimer And Event Queue 48*e7be843bSPierre Pronchery--------------------- 49*e7be843bSPierre Pronchery 50*e7be843bSPierre ProncheryQueue of events that need to be handled asynchronously or at a later 51*e7be843bSPierre Proncherytime. 52*e7be843bSPierre Pronchery 53*e7be843bSPierre ProncheryTLS Handshake Record Layer 54*e7be843bSPierre Pronchery-------------------------- 55*e7be843bSPierre Pronchery 56*e7be843bSPierre ProncheryA module that uses the Record Layer API to implement the inner TLS-1.3 57*e7be843bSPierre Proncheryprotocol handshake. It produces and parses the QUIC CRYPTO frames. 58*e7be843bSPierre Pronchery 59*e7be843bSPierre ProncheryTX Packetizer 60*e7be843bSPierre Pronchery------------- 61*e7be843bSPierre Pronchery 62*e7be843bSPierre ProncheryThis module creates frames from the application data obtained from 63*e7be843bSPierre Proncherythe application. It also receives CRYPTO frames from the TLS Handshake 64*e7be843bSPierre ProncheryRecord Layer and ACK frames from the ACK Handling And Loss Detector 65*e7be843bSPierre Proncherysubsystem. 66*e7be843bSPierre Pronchery 67*e7be843bSPierre ProncheryRX Frame Handler 68*e7be843bSPierre Pronchery---------------- 69*e7be843bSPierre Pronchery 70*e7be843bSPierre ProncheryDecrypted packets are split into frames here and the frames are forwarded 71*e7be843bSPierre Proncheryeither as data or as events to the subsequent modules based on the frame 72*e7be843bSPierre Proncherytype. Flow Controller And Statistics Collector is consulted for decisions 73*e7be843bSPierre Proncheryand to record the statistics of the received stream data. 74*e7be843bSPierre Pronchery 75*e7be843bSPierre ProncheryFlow Controller 76*e7be843bSPierre Pronchery--------------- 77*e7be843bSPierre Pronchery 78*e7be843bSPierre ProncheryThis module is consulted by the TX Packetizer and RX Frame Handler for flow 79*e7be843bSPierre Proncherycontrol decisions at both the stream and connection levels. 80*e7be843bSPierre Pronchery 81*e7be843bSPierre ProncheryStatistics Collector 82*e7be843bSPierre Pronchery-------------------- 83*e7be843bSPierre Pronchery 84*e7be843bSPierre ProncheryThis module maintains statistics about a connection, most notably the estimated 85*e7be843bSPierre Proncheryround trip time to the remote peer. 86*e7be843bSPierre Pronchery 87*e7be843bSPierre ProncheryQUIC Write Record Layer 88*e7be843bSPierre Pronchery----------------------- 89*e7be843bSPierre Pronchery 90*e7be843bSPierre ProncheryEncryption of packets according to the given encryption level and with 91*e7be843bSPierre Proncherythe appropriate negotiated algorithm happens here. 92*e7be843bSPierre Pronchery 93*e7be843bSPierre ProncheryResulting packets are sent through the Datagram BIO interface to the 94*e7be843bSPierre Proncherynetwork. 95*e7be843bSPierre Pronchery 96*e7be843bSPierre ProncheryQUIC Read Record Layer 97*e7be843bSPierre Pronchery---------------------- 98*e7be843bSPierre Pronchery 99*e7be843bSPierre ProncheryDecryption of packets according to the given encryption level and with 100*e7be843bSPierre Proncherythe appropriate negotiated algorithm happens here. 101*e7be843bSPierre Pronchery 102*e7be843bSPierre ProncheryPackets are received from the network through the Datagram BIO interface. 103*e7be843bSPierre Pronchery 104*e7be843bSPierre ProncheryCongestion Controller 105*e7be843bSPierre Pronchery--------------------- 106*e7be843bSPierre Pronchery 107*e7be843bSPierre ProncheryThis is a pluggable API that provides calls to record data relevant 108*e7be843bSPierre Proncheryfor congestion control decisions and to query for decision on whether 109*e7be843bSPierre Proncherymore data is allowed to be sent or not. 110*e7be843bSPierre Pronchery 111*e7be843bSPierre ProncheryThe module is called by the TX Packetizer and the ACK Handling And 112*e7be843bSPierre ProncheryLoss Detector modules. 113*e7be843bSPierre Pronchery 114*e7be843bSPierre ProncheryACK Handling And Loss Detector 115*e7be843bSPierre Pronchery------------------------------ 116*e7be843bSPierre Pronchery 117*e7be843bSPierre ProncheryA module that tracks packets sent to the peer and received ACK frames. 118*e7be843bSPierre ProncheryIt detects lost packets (after an ACK is not received in time). It informs 119*e7be843bSPierre ProncheryTX packetizer that it can drop frames waiting to be ACKed when ACK is received. 120*e7be843bSPierre ProncheryIt also schedules retransmits of frames from packets that are considered 121*e7be843bSPierre Proncheryto be lost. 122*e7be843bSPierre Pronchery 123*e7be843bSPierre ProncheryThe module also handles the receiving side - it schedules when ACK frames should 124*e7be843bSPierre Proncherybe sent for the received packets. 125*e7be843bSPierre Pronchery 126*e7be843bSPierre ProncheryPath And Conn Demultiplexer 127*e7be843bSPierre Pronchery--------------------------- 128*e7be843bSPierre Pronchery 129*e7be843bSPierre ProncheryOn server side this module is shared between multiple SSL connection objects 130*e7be843bSPierre Proncherywhich makes it a special kind of module. It dispatches the received packets 131*e7be843bSPierre Proncheryto the appropriate SSL Connection by consulting the Connection ID Cache. 132*e7be843bSPierre Pronchery 133*e7be843bSPierre Pronchery_For client side and MVP this module just checks that the received packet has 134*e7be843bSPierre Proncherythe appropriate Connection ID and optionally schedules sending stateless 135*e7be843bSPierre Proncheryreset for packets with other Connection IDs._ 136*e7be843bSPierre Pronchery 137*e7be843bSPierre ProncheryDatagram BIO 138*e7be843bSPierre Pronchery------------ 139*e7be843bSPierre Pronchery 140*e7be843bSPierre ProncheryImplementation of BIO layer that supports `BIO_sendmmsg` and `BIO_recvmmsg` 141*e7be843bSPierre Proncherycalls. 142
