QLOG: Add debugging guide

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
(Merged from #22037)

doc/designs/quic-design/debugging.md

@@ -0,0 +1,143 @@
+QUIC: Debugging and Tracing
+===========================
+
+When debugging the QUIC stack it is extremely useful to have protocol traces
+available. There are two approaches you can use to obtain this data:
+
+- QLOG
+- Packet capture
+
+Neither of these approaches is strictly superior to the other and both have pros
+and cons:
+
+- In general, QLOG is aimed at storing only information relevant to the
+  QUIC protocol itself without storing bulk data. This includes both transmitted
+  and received packets but also information about the internal state of a QUIC
+  implementation which is not directly observable from the network.
+
+- By comparison, packet capture stores all packets in their entirety.
+  Packet captures are thus larger, but they also provide more complete
+  information in general and do not have information removed. On the other hand,
+  because they work from a network viewpoint, they cannot provide direct
+  information on the internal state of a QUIC implementation. For example,
+  packet capture cannot directly tell you when an implementation deems a packet
+  lost.
+
+Both of these approaches have good GUI visualisation tools available for viewing
+the logged data.
+
+To summarise:
+
+- QLOG:
+  - Pro: Smaller files
+  - Con: May leave out data assumed to be irrelevant
+  - Pro: Information on internal states and decisions made by a QUIC
+    implementation
+  - Pro: No need to obtain a keylog
+- PCAP:
+  - Pro: Complete capture
+  - Con: No direct information on internal states of a QUIC implementation
+  - Con: Need to obtain a keylog
+
+Using QLOG
+----------
+
+To enable QLOG you must:
+
+- build using the `enable-unstable-qlog` build-time configuration option;
+
+- set the environment variable `QLOGDIR` to a directory where QLOG log files
+  are to be written;
+
+- set the environment variable `QFILTER` to a filter specifying the events
+  you want to be written (set `QFILTER='*'` for all events).
+
+Any process using the libssl QUIC implementation will then automatically write
+QLOG files in the JSON-SEQ format to the specified directory. The files have the
+naming convention recommended by the specification: `{ODCID}_{ROLE}.sqlog`,
+where `{ODCID}` is the initial (original) DCID of a connection and `{ROLE}` is
+`client` or `server`.
+
+The log files can be loaded into [qvis](https://qvis.quictools.info/). The [qvis
+website](https://qvis.quictools.info/) also has some sample QLOG files which you
+can load at the click of a button, which enables you to see what kind of
+information qvis can offer you.
+
+Note that since the QLOG specification is not finalised and still evolving,
+the format of the output may change, as may the method of configuring this
+logging support.
+
+Currently this implementation tracks qvis's QLOG support, as that is the
+main target use case at this time.
+
+Note that since QLOG emphasises logging only data which is relevant to a QUIC
+protocol implementation, for the purposes of reducing the volume of logging
+data, application data is generally not logged. (However, this is not a
+guarantee and must not be relied upon from a privacy perspective.)
+
+[See here for more details on the design of the QLOG facility.](qlog.md)
+
+Using PCAP
+----------
+
+To use PCAP you can use any standard packet capture tool, such as Wireshark or
+tcpdump (e.g. `tcpdump -U -i "$IFACE" -w "$FILE" 'udp port 1234'`).
+
+**Using Wireshark.** Once you have obtained a packet capture as a standard
+`pcap` or `pcapng` file, you can load it into Wireshark, which has excellent
+QUIC protocol decoding support.
+
+**Activating the decoder.** If you are using QUIC on a port not known to be
+commonly used for QUIC, you may need to tell Wireshark to try and decode a flow
+as QUIC. To do this, right click on the Protocol column and select “Decode
+As...”. Click on “(none)” under the Current column and select QUIC.
+
+**Keylogs.** Since QUIC is an encrypted protocol, Wireshark cannot provide much
+information without access to the encryption keys used for the connection
+(though it is able to decrypt Initial packets).
+
+In order to provide this information you need to provide Wireshark with a keylog
+file. This is a log file containing encryption keys for the connection which is
+written directly by a QUIC implementation for debugging purposes. The purpose of
+such a file is to enable a TLS or QUIC session to be decrypted for development
+purposes in a lab environment. It should go without saying that the export of a
+keylog file should never be used in a production environment.
+
+For the OpenSSL QUIC implementation, OpenSSL must be instructed to save a keylog
+file using the SSL_CTX_set_keylog_callback(3) API call. If the application you
+are using does not provide a way to enable this functionality, this requires
+recompiling the application you are using as OpenSSL does not provide a way
+to enable this functionality directly.
+
+If you are using OpenSSL QUIC to talk to another QUIC implementation, you also
+may be able to obtain a keylog from that other implementation. (It does not
+matter from which side of the connection you obtain the keylog.)
+
+Once you have a keylog file you can configure Wireshark to use it.
+There are two ways to do this:
+
+- **Manual configuration.** Select Edit →
+  Preferences and navigate to Protocols → TLS. Enter the path to the keylog file
+  under “(Pre)-Master-Secret log filename". You can have key information being
+  appended to this log continuously if desired. Press OK and Wireshark should
+  now be able to decrypt any TLS or QUIC session described by the log file.
+
+- **Embedding.** Alternatively, you can embed a keylog file into a `.pcapng`
+  file directly, so that Wireshark can decrypt the packets automatically when
+  the packet capture file is opened. This avoids the need to have a centralised
+  key log file and ensures that the key log for a specific packet capture is
+  kept together with the captured packets. It is also highly useful if you want
+  to distribute a packet capture file publicly, for example for educational
+  purposes.
+
+  To embed a keylog, you can use the `editcap` command provided by Wireshark
+  after taking a packet capture (note that `tls` should be specified below
+  regardless of whether TLS or QUIC is being used):
+
+  ```bash
+  $ editcap --inject-secrets tls,$PATH_TO_KEYLOG_FILE \
+    "$INPUT_FILENAME" "$OUTPUT_FILENAME"
+  ```
+
+  This tool accepts `.pcap` or `.pcapng` input and will generate a `.pcapng`
+  output file.