doc/http3.md

   1
   2 # Supported features
   3 The HTTP3 dissector is a work in progress.
   4
   5 At the moment, the following aspects of HTTP3 are supported:
   6 - Diseciton of different HTTP3 stream types
   7 - Dissection of different HTTP3 frame types
   8 - Dissection of HTTP header fields
   9 - Dissection of QPACK instructions
  10
  11 In addition, the dissector suports decoding of the HTTP3
  12 header fields. This ability requires `nghttp3` third-party library.
  13
  14 ## High-level overview
  15 The HTTP3 dissector is invoked by the QUIC dissector.
  16
  17 The essential call tree:
  18 -  `dissect_http3`
  19    Main entry point. Depending on the stream type, invokes one of the following:
  20    -  `dissect_http3_uni_stream`
  21       Processes unidirectional streams, including the control streams,
  22       the QPACK encoder/decoder streams, and the HTTP3 server push streams.
  23       NOTE: the HTTP3 server push streams support is rudimental.
  24       -  `dissect_http3_qpack_enc`
  25          Dissects the QPACK encoder stream.
  26          If Wireshark was built with the optional `nghttp3` library,
  27          this function is also responsible on updating the state
  28          of the QPACK decoder.
  29    -  `dissect_http3_frame`
  30       Processed HTTP3 frames from the client-initiated bidirectional stream.
  31       Determines the frame type, and dispatches the call to one of the
  32       sub-dissectors:
  33       -  `dissect_http3_data`
  34          Dissects the `HTTP3_DATA` frames.
  35       -  `dissect_http3_headers`
  36          Dissects the `HTTP3_HEADER` frames.
  37          If Wireshark was built with the optional `nghttp3` library,
  38          this function attempts to decode the header fields, using
  39          the QPACK decoder.
  40       -  `dissect_http3_settings`
  41          Dissects the `HTTP3_SETTINGS` frames.
  42
  43 ### Overview of the HTTP3 header dissection
  44 The QPACK implementation from `nghttp3` requires a separate QPACK decoder instance
  45 for every HTTP3 connection. The different HTTP3 streams that constitute a single
  46 HTTP3 conneciton are sharing the same QPACK decoder instance.
  47
  48 The HTTP3 dissector interacts with the QPACK decoder in 2 ways:
  49 -  On the reception of QPACK encoder data (which is delivered on a dedicated unidirectional stream),
  50    the dissector updates the connection's decoder instance.
  51 -  On the reception of compressed HTTP3 headers, the dissector uses the connection's decoder
  52    to uncompress the HTTP headers.
  53
  54 If decompression succeeds, the dissector adds tree items to the packet tree. Otherwise,
  55 the dissector adds expert info items.
  56
  57 The decompression can fail due to several reasons:
  58 -  If the instruction count required by the compressed HTTP3 headers
  59    exceeds the maximal instruction count that the QPACK decoder is aware of,
  60    the decoding becomes "blocked". This situation can occure when the QUIC packets
  61    that carry the QPACK encoder instructions are dropped/reordered.
  62 -  If the state of the decoder becomes invalid, which may happen when a "garbage"
  63    data is received on the QUIC stream.
  64 -  Lastly, the decoding can fail if the underlying QUIC desegmentation is
  65    not working correctly.
  66
  67 ### Overview of HTTP3 data frames dissection
  68 The higher-level dissectors that could use HTTP3 (e.g. WebTransport) need to be able
  69 to access the contents of a single HTTP3 stream as a contiguous span of data.
  70
  71 For that purpose, the HTTP3 dissector is defining a custom conversation finder.
  72 See functions `http3_find_inner_conversation` and `http3_reset_inner_conversation`.
  73
  74 ## Essential data structures
  75 ### File-level state
  76 #### `HTTP3_CONN_INFO_MAP`
  77 The `HTTP3_CONN_INFO_MAP` contains session-level information for every HTTP3 connection
  78 in a PCAP file. This map is lazily allocated, and is cleared upon exiting the file scope.
  79
  80 ### HTTP3 header caches
  81 The dissector attempts to conserve memory, by avoding allocating memory for
  82 duplicate header names/values. Instead, the dissector keeps the decoded names/values
  83 in two caches: `HTTP3_HEADER_CACHE` and `HTTP3_HEADER_DEF_CACHE`. The former stores
  84 the decoded HTTP3 header values, and the latter stores the decoded HTTP3 header names.
  85
  86 ### Connection-level state
  87 #### `http3_session_info_t`
  88 The `http3_session_info_t` keeps the state of the QPACK decoder. Every HTTP3 connection
  89 corresponds to a single session. In the future, the session may be shared between multiple
  90 connections, to support connection migration or multipath HTTP3.
  91 At the moment, there are no shared sessions.
  92
  93 ### Stream-level state
  94 #### `http3_stream_info_t`
  95 The `http3_stream_info_t` keeps the information about the individual HTTP3 streams,
  96 as well as mapping to the underlying QUIC streams.
  97
  98 ### Frame-level state
  99 #### `http3_header_field_t`
 100 The `http3_header_field_t` keeps the information about a single HTTP header.
 101 It contains both the encoded and the decoded representation of the header.
 102 The actual decoded strings are stored in `HTTP3_HEADER_CACHE`/`HTTP3_HEADER_DEF_CACHE`;
 103 the individual `http3_header_field_t` instances contain pointers to the strings.