1 RX depacketizer 2 =============== 3 4 This component takes a QUIC packet and parses the frames contained therein, 5 to be forwarded to appropriate other components for further processing. 6 7 In the [overview], this is called the "RX Frame Handler". The name "RX 8 depacketizer" was chosen to reflect the kinship with the [TX packetizer]. 9 10 Main structures 11 --------------- 12 13 ### Connection 14 15 Represented by an `QUIC_CONNECTION` object, defined in 16 [`include/internal/quic_ssl.h`](../../../include/internal/quic_ssl.h). 17 18 ### Stream 19 20 Represented by an `QUIC_STREAM` object (yet to be defined). 21 22 ### Packets 23 24 Represented by the `OSSL_QRX_PKT` structure, defined in 25 `include/internal/quic_record_rx.h` in [QUIC Demuxer and Record Layer (RX+TX)]. 26 27 Interactions 28 ------------ 29 30 The RX depacketizer receives a packet from the QUIC Read Record Layer, and 31 then processes frames in two phases: 32 33 1. [Collect information for the ACK Manager](#collect-information-for-the-ack-manager) 34 2. [Pass frame data](#pass-frame-data) 35 36 ### Other components 37 38 There are a number of other components that the RX depacketizer wants to 39 interact with: 40 41 - [ACK manager] 42 - Handshake manager, which is currently unspecified. It's assumed that 43 this will wrap around what is called the "TLS Handshake Record Layer", 44 in the [overview] 45 - Session manager, which is currently unspecified for QUIC, but may very 46 well be the existing `SSL_SESSION` functionality, extended to fit QUIC 47 purposes. 48 - Flow control, which is currently unspecified. In the [overview], it's 49 called the "Flow Controller And Statistics Collector" 50 - Connection manager, which is currently unspecified. In the [overview], 51 there's a "Connection State Machine" that the "RX Frame Handler" isn't 52 talking directly with, so it's possible that the Connection manager will 53 turn out to be the Handshake manager. 54 - Stream SSL objects, to pass the stream data to. 55 56 ### Read and process a packet 57 58 Following how things are designed elsewhere, the depacketizer is assumed to 59 be called "from above" using the following function: 60 61 ``` C 62 __owur int ossl_quic_depacketize(QUIC_CONNECTION *connection); 63 ``` 64 65 This function would create an `OSSL_QRX_PKT` and call the QUIC Read Record 66 Layer with a pointer to it, leaving it to the QUIC Read Record Layer to fill 67 in the data. 68 69 This uses the `ossl_qrx_read_pkt()` packet reading function from 70 [QUIC Demuxer and Record Layer (RX+TX)]. 71 (the `OSSL_QRX_PKT` structure / sub-structure needs to be extended to take 72 an `OSSL_TIME`, possibly by reference, which should be filled in with the 73 packet reception time) 74 75 ### Collect information for the [ACK manager] 76 77 This collects appropriate data into a `QUIC_ACKM_RX_PKT` structure: 78 79 - The packet number (`packet->packet_number`) 80 - The packet receive time (`received`) 81 - The packet space, which is always: 82 - `QUIC_PN_SPACE_INITIAL` when `packet->packet_type == pkt_initial` 83 - `QUIC_PN_SPACE_HANDSHAKE` when `packet->packet_type == pkt_handshake` 84 - `QUIC_PN_SPACE_APP` for all other packet types 85 - The ACK eliciting flag. This is calculated by looping through all 86 frames and noting those that are ACK eliciting, as determined from 87 [Table 1](#table-1) below) 88 89 ### Passing frame data 90 91 This loops through all the frames, extracts data where there is any 92 and calls diverse other components as shown in the Passed to column in 93 [Table 1](#table-1) below. 94 95 #### Table 1 96 97 Taken from [RFC 9000 12.4 Frames and Frame Types] 98 99 | Type | Name | Passed to | ACK eliciting | I | H | 0 | 1 | 100 |------|-------------------------|--------------------------|---------------|----------|----------|----------|----------| 101 | 0x00 | [padding] | - | | ✔ | ✔ | ✔ | ✔ | 102 | 0x01 | [ping] | - | ✔ | ✔ | ✔ | ✔ | ✔ | 103 | 0x02 | [ack 0x02] | [ACK manager] [^1] | | ✔ | ✔ | | ✔ | 104 | 0x03 | [ack 0x03] | [ACK manager] [^1] | | ✔ | ✔ | | ✔ | 105 | 0x04 | [reset_stream] | - [^2] | ✔ | | | ✔ | ✔ | 106 | 0x05 | [stop_sending] | - [^3] | ✔ | | | ✔ | ✔ | 107 | 0x06 | [crypto] | Handshake manager | ✔ | ✔ | ✔ | | ✔ | 108 | 0x07 | [new_token] | Session manager | ✔ | | | | ✔ | 109 | 0x08 | [stream 0x08] | Apprioriate stream [^4] | ✔ | | | ✔ | ✔ | 110 | 0x09 | [stream 0x09] | Apprioriate stream [^4] | ✔ | | | ✔ | ✔ | 111 | 0x0A | [stream 0x0A] | Apprioriate stream [^4] | ✔ | | | ✔ | ✔ | 112 | 0x0B | [stream 0x0B] | Apprioriate stream [^4] | ✔ | | | ✔ | ✔ | 113 | 0x0C | [stream 0x0C] | Apprioriate stream [^4] | ✔ | | | ✔ | ✔ | 114 | 0x0D | [stream 0x0D] | Apprioriate stream [^4] | ✔ | | | ✔ | ✔ | 115 | 0x0E | [stream 0x0E] | Apprioriate stream [^4] | ✔ | | | ✔ | ✔ | 116 | 0x0F | [stream 0x0F] | Apprioriate stream [^4] | ✔ | | | ✔ | ✔ | 117 | 0x10 | [max_data] | Flow control [^5] | ✔ | | | ✔ | ✔ | 118 | 0x11 | [max_stream_data] | Flow control [^5] | ✔ | | | ✔ | ✔ | 119 | 0x12 | [max_streams 0x12] | Connection manager? [^6] | ✔ | | | ✔ | ✔ | 120 | 0x13 | [max_streams 0x13] | Connection manager? [^6] | ✔ | | | ✔ | ✔ | 121 | 0x14 | [data_blocked] | Flow control [^5] | ✔ | | | ✔ | ✔ | 122 | 0x15 | [stream_data_blocked] | Flow control [^5] | ✔ | | | ✔ | ✔ | 123 | 0x16 | [streams_blocked 0x16] | Connection manager? [^6] | ✔ | | | ✔ | ✔ | 124 | 0x17 | [streams_blocked 0x17] | Connection manager? [^6] | ✔ | | | ✔ | ✔ | 125 | 0x18 | [new_connection_id] | Connection manager | ✔ | | | ✔ | ✔ | 126 | 0x19 | [retire_connection_id] | Connection manager | ✔ | | | ✔ | ✔ | 127 | 0x1A | [path_challenge] | Connection manager? [^7] | ✔ | | | ✔ | ✔ | 128 | 0x1B | [path_response] | Connection manager? [^7] | ✔ | | | | ✔ | 129 | 0x1C | [connection_close 0x1C] | Connection manager | | ✔ | ✔ | ✔ | ✔ | 130 | 0x1D | [connection_close 0x1D] | Connection manager | | | | ✔ | ✔ | 131 | 0x1E | [handshake_done] | Handshake manager | ✔ | | | | ✔ | 132 | ???? | *[Extension Frames]* | - [^8] | ✔ | | | | | 133 134 The I, H, 0, and 1 columns are validity in different packet types, with this meaning: 135 136 | Pkts | Description | 137 |:----:|----------------------------| 138 | I | Valid in Initial packets | 139 | H | Valid in Handshake packets | 140 | 0 | Valid in 0-RTT packets | 141 | 1 | Valid in 1-RTT packets | 142 143 Notes: 144 145 [^1]: This creates and populates an `QUIC_ACKM_ACK` structure, then calls 146 `QUIC_ACKM_on_rx_ack_frame()`, with the appropriate context 147 (`QUIC_ACKM`, the created `QUIC_ACKM_ACK`, `pkt_space` and `rx_time`) 148 [^2]: Immediately terminates the appropriate receiving stream `QUIC_STREAM` 149 object. 150 This includes discarding any buffered application data. 151 For a stream that's send-only, the error `STREAM_STATE_ERROR` is raised, 152 and the `QUIC_CONNECTION` object is terminated. 153 [^3]: Immediately terminates the appropriate sending stream `QUIC_STREAM` 154 object. 155 For a stream that's receive-only, the error `STREAM_STATE_ERROR` is 156 raised, and the `QUIC_CONNECTION` object is terminated. 157 [^4]: The frame payload (Stream Data) is passed as is to the `QUIC_STREAM` 158 object, along with available metadata (offset and length, as determined 159 to be available from the lower 3 bits of the frame type). 160 [^5]: The details of what flow control will need are yet to be determined 161 [^6]: I imagine that `max_streams` and `streams_blocked` concern a Connection 162 manager before anything else. 163 [^7]: I imagine that path challenge/response concerns a Connection manager 164 before anything else. 165 [^8]: We have no idea what extension frames there will be. However, we 166 must at least acknowledge their presence, so much is clear from the RFC. 167 168 [overview]: https://github.com/openssl/openssl/blob/master/doc/designs/quic-design/quic-overview.md 169 [TX packetizer]: https://github.com/openssl/openssl/pull/18570 170 [SSL object refactoring using SSL_CONNECTION object]: https://github.com/openssl/openssl/pull/18612 171 [QUIC Demuxer and Record Layer (RX+TX)]: https://github.com/openssl/openssl/pull/18949 172 [ACK manager]: https://github.com/openssl/openssl/pull/18564 173 [RFC 9000 12.4 Frames and Frame Types]: https://datatracker.ietf.org/doc/html/rfc9000#section-12.4 174 [padding]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.1 175 [ping]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.2 176 [ack 0x02]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.3 177 [ack 0x03]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.3 178 [reset_stream]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.4 179 [stop_sending]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.5 180 [crypto]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.6 181 [new_token]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.7 182 [stream 0x08]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.8 183 [stream 0x09]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.8 184 [stream 0x0A]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.8 185 [stream 0x0B]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.8 186 [stream 0x0C]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.8 187 [stream 0x0D]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.8 188 [stream 0x0E]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.8 189 [stream 0x0F]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.8 190 [max_data]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.9 191 [max_stream_data]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.10 192 [max_streams 0x12]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.11 193 [max_streams 0x13]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.11 194 [data_blocked]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.12 195 [stream_data_blocked]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.13 196 [streams_blocked 0x16]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.14 197 [streams_blocked 0x17]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.14 198 [new_connection_id]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.15 199 [retire_connection_id]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.16 200 [path_challenge]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.17 201 [path_response]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.18 202 [connection_close 0x1C]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.19 203 [connection_close 0x1D]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.19 204 [handshake_done]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.20 205 [Extension Frames]: https://datatracker.ietf.org/doc/html/rfc9000#section-19.21 206
Indexes created Sat Aug 22 00:26:31 UTC 2026