This is a listing of tools for analysing, debugging and visualising QUIC (and potentially the HTTP mapping). See also the Implementations listing.
Wireshark has a GQUIC decoder1 and IETF-QUIC decoder.
HTTP analysis is possible via integration with the HTTP/2 decoder. http3 is not yet supported. To enable handshake/payload decryption, use a Wireshark version that matches the QUIC version:
|#||First Wireshark version||Last WS version||notes|
|-19||v3.1.0rc0-520-ga65f7f5838 / 3.0.2||Done.|
|-18||v2.9.1rc0-487-gd486593ce3||Done since v2.9.1rc0-500-g064a5c90ca|
|-17||v2.9.1rc0-332-ga0b9e8b652||Done since v2.9.1rc0-456-g19630453bf|
|-16||v2.9.1rc0-100-g0964b04ee3||v2.9.1rc0-331-gf1fa8df324||Compatible with -15 (no packet change)|
|-15||v2.9.0rc0-2528-g9bd1c8f155||v2.9.1rc0-331-gf1fa8df324||Available on 2.9.0|
|-11||v2.9.0rc0-291-gee3bc52192||v2.9.0rc0-1829-g1d2fd4f411||+Connection migration (untested)|
|-09||v2.5.2rc0-68-geea63ae2a7||2.6.x / v2.9.0rc0-173-g71ddbb69f5||Supports payload decryption (-09)|
Automated builds (macOS and Windows) for (odd-numbered) development versions: https://www.wireshark.org/download/automated/
Upstream bug (with sample captures/keys): https://bugs.wireshark.org/bugzilla/show_bug.cgi?id=13881
Patches under review: https://code.wireshark.org/review/#/q/status:open+branch:master+topic:QUIC
For payload decryption (>= draft -13), the QUIC traffic secrets are required. The TLS key log file follows the TLS 1.3 labels (with
QUIC_ prepended). Every line follows the format
<label> <ClientRandom> <TrafficSecret> where
<label> is one of:
QUIC_SERVER_TRAFFIC_SECRET_0. Example: https://github.com/ngtcp2/ngtcp2/pull/84
For payload decryption (<= draft -12), the TLS Exporter secret is required which must be provided via a TLS key log file. See for example https://github.com/ngtcp2/ngtcp2/pull/67. Note that since OpenSSL_1_1_1-pre5-21-gd4da95a773 (2018-04-18), OpenSSL supports this via its keylog callback.
1Wireshark is not capable of decrypting GQUIC packets itself, even if NSS Keylogging has been configured. However, if a decrypted trace is supplied to Wireshark it will correctly dissect GQUIC if the "Force decrypt" option is enabled in the Settings.
Wireshark draft support
- TLS 1.3 handshake fragmentation over multiple packets. Related: https://bugs.wireshark.org/bugzilla/show_bug.cgi?id=15537
- Key Update: verify decrypted result before switching cipher.
- Connection migration: supported as of v2.9.0rc0-1879-g17bc055138 (tested with draft -14)
- Stream ID dissection (two LSB -> direction/initiator)
- Stateless reset (format changed again in draft -17 and -20) https://tools.ietf.org/html/draft-ietf-quic-transport-17#section-10.4
Deprecate and alias
QUIC_*SECRET*decryption secrets for
*SECRET*since it is the same since draft -14.
- Missing QPACK and HTTP/3 support. (Planned to be added.)
To-do items for draft -20 completion (completed)
- Stateless reset format has changed again. (It was not supported before anyway)
- New transport error code: CRYPTO_BUFFER_EXCEEDED(0xD) https://code.wireshark.org/review/32961
To-do items for draft -19 completion (completed)
- Removal of VERSION_NEGOTIATION_ERROR (0x9) error code.
- Removal of QuicVersion fields in TransportParameters. https://code.wireshark.org/review/32833
- idle_timeout (0x0001) was changed from seconds to milliseconds.
To-do items for draft -18 completion (completed)
- Rename ACK Blocks to ACK Ranges, move First ACK Range field, rename ECN Section -> ECN Counters. https://code.wireshark.org/review/31688
- Rename 0-RTT Protected -> 0-RTT https://code.wireshark.org/review/31685
- Rename stream Final Offset -> Final Size; FINAL_OFFSET_ERROR -> FINAL_SIZE_ERROR https://code.wireshark.org/review/31687
- PreferredAdress: split ipVersion/ipAddress in ipv4Address/ipv4Port/ipv6Address/ipv6Port fields. https://code.wireshark.org/review/31689
To-do items for draft -17 completion (completed)
- Update PNE -> Header protection, update initial salt, update HKDF label. https://code.wireshark.org/review/31480
- Packet number decryption fixes. https://code.wireshark.org/review/31634
- Display unprotected short header bytes, fix 1RTT decryption (incl. KeyUpdate?, untested) https://code.wireshark.org/review/31637
- Renumbered frames (and rename like BLOCKED -> DATA_BLOCKED, STREAM_BLOCKED -> STREAM_DATA_BLOCKED). https://code.wireshark.org/review/31405
Renumbered transport parameters (TP) and use varints, rename
- NEW_CONNECTION_ID: move Sequence(i) field before CID Length field... (revert draft-15 change!). https://code.wireshark.org/review/31405
- Add Spin bit (short header) https://code.wireshark.org/review/31644
- Display unprotected long header bytes. https://code.wireshark.org/review/31642
To-do items for draft -16 completion (completed)
- Add draft-16 to quic_versions_vals https://code.wireshark.org/review/31169
To-do items for draft -15 completion (completed)
- Merge ACK and ACK_ECN. Renumbers ACK(0x0d) -> ACK(0x1b). (ECN is like ACK frame, but with ECN Section after it) https://code.wireshark.org/review/30420 https://code.wireshark.org/review/30491
- Add 2 transport parameters: max_ack_delay(12) and original_connection_id(13) https://code.wireshark.org/review/30418
- NEW_CONNECTION_ID: move Sequence(i) field after CID Length field. https://code.wireshark.org/review/30419
- Add RETIRE_CONNECTION_ID(0x0d) type (NOTE: conflict with old ACK(0x0d)). https://code.wireshark.org/review/30492
To-do items for draft -14 completion (completed)
- Retry Packet: completely changed. https://code.wireshark.org/review/29689
- ACK_ECN Change value (0x20) => (0x1a) https://code.wireshark.org/review/29702
- Remove error code: UNSOLICITED_PATH_RESPONSE https://code.wireshark.org/review/29703
- Split initial_max_stream_data (0) into initial_max_stream_data_bidi_local (0), initial_max_stream_data_bidi_remote (10), initial_max_stream_data_uni (11) https://code.wireshark.org/review/29722
To-do items for draft -13 completion (more or less complete)
- Long header: "Payload Length" -> "Length" (length of following PKN + payload)
- Initial Packet: can now be sent by server as well, contains Token Length + Token fields following the normal long header. https://code.wireshark.org/review/29641
- New transport parameter: disable_migration (9) https://code.wireshark.org/review/29674
- Stateless Reset packet format change (due to short header type changes)
- CONNECTION_CLOSE: gains new Frame Type (i) field. https://code.wireshark.org/review/29698
- New frame type: CRYPTO (0x18). Replaces "Stream 0" and changes how Initial Packet/Handshake are used.
- Retry Packet: no longer carries a TLS HRR, see 4.4.2. https://code.wireshark.org/review/29687
- New frame type: NEW_TOKEN (0x19) https://code.wireshark.org/review/29699
- New frame type: ACK_ECN (0x20) https://code.wireshark.org/review/29699
- New QUIC Frame Type Registry with IANA. Verified matching.
- Renamed error: FRAME_FORMAT_ERROR -> FRAME_ENCODING_ERROR (0x7) https://code.wireshark.org/review/29700
- New error type: INVALID_MIGRATION (0xC) https://code.wireshark.org/review/29700
- Changed error definition: FRAME_ERROR -> CRYPTO_ERROR (0x1XX) https://code.wireshark.org/review/29740
- TLS extension number change: quic_transport_parameter(26) -> 0xffa5 https://code.wireshark.org/review/29673
To-do items for draft -12 completion (completed and obsolete)
- Short packet: two type bits -> reserved. https://code.wireshark.org/review/29668
- Packet number encryption (starts at zero, there is no special Initial Packet Number). Replaces previous "packet number gap" approach. https://code.wireshark.org/review/29637
- 7, 14, 30-bit variable length packet numbers https://code.wireshark.org/review/29637
- New transport parameter: preferred_address (4) https://code.wireshark.org/review/29671
- Improve connection migration tracking: use Server's Preferred Address
To-do items for draft -11 completion (completed and obsolete)
- new short header flags, long header format https://code.wireshark.org/review/27009
- packet coalescing. Draft -12 clarifies: applies to short packet headers too; packets (within a datagram) with different DCID than the first packet should be ignored. https://code.wireshark.org/review/29607 (framing only, decryption of multiple messages is incomplete)
- storing CID for reference in short header packet https://code.wireshark.org/review/27098
- update NEW_CONNECTION_ID dissection https://code.wireshark.org/review/27107
connection tracking based on CID / connection migration
- Basic connection tracking https://code.wireshark.org/review/27068
- Use NEW_CONNECTION_ID hint (requires user to provide EXPORTER_SECRET keys)
QUIC-Tracker is a test suite for IETF-QUIC. It exchanges packets with IETF-QUIC implementations to verify whether an implementation conforms with the IETF specification. The test suite is consisting of several test scenarii. Each of them aims at testing a particular feature of the QUIC protocol. The test suite runs daily, and its results are available on its website.
It currently supports QUIC draft-17/18 and TLS 1.3.
qvalve can predictably impair QUIC flows, by dropping, reordering or duplicating individual packets and sequences of packets. It is a non-transparent UDP proxy that should be interposed between a QUIC client and a QUIC server. The behavior of qvalve is configured with rules specified in a simple language.
The "Spindump" tool is a Unix command-line utility that can be used for latency monitoring in traffic passing through an interface. The tool performs passive, in-network monitoring. It is not a tool to monitor traffic content or metadata of individual connections, and indeed that is not possible in the Internet as most connections are encrypted. The tool looks at the characteristics of transport protocols, such as the QUIC Spin Bit, and attempts to derive information about round-trip times for individual connections or for the aggregate or average values. The tool supports TCP, QUIC, COAP, DNS, and ICMP traffic.
- Language: C
- Version: draft-16, draft-17
- Roles: in-network tool
- Handshake: QUIC only, does not peek into TLS or HTTP messaging inside
- Public server: n.a.