QUIC Glossary

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20803)

1 files changed, 240 insertions, 0 deletions

diff --git a/doc/designs/quic-design/glossary.md b/doc/designs/quic-design/glossary.md
new file mode 100644
index 0000000000..1237b63885
--- /dev/null
+++ b/doc/designs/quic-design/glossary.md
@@ -0,0 +1,240 @@
+Glossary of QUIC Terms
+======================
+
+**ACKM:** ACK Manager. Responsible for tracking packets in flight and generating
+notifications when they are lost, or when they are successfully delivered.
+
+**Active Stream:** A stream which has data or control frames ready for
+transmission. Active stream status is managed by the QSM.
+
+**AEC:** Application error code. An error code provided by a local or remote
+application to be signalled as an error code value by QUIC. See QUIC RFCs
+(`STOP_SENDING`, `RESET_STREAM`, `CONNECTION_CLOSE`).
+
+**APL:** API Personality Layer. The QUIC API Personality Layer lives in
+`quic_impl.c` and implements the libssl API personality (`SSL_read`, etc.) in
+terms of an underlying `QUIC_CHANNEL` object.
+
+**Bidi:** Abbreviation of bidirectional, referring to a QUIC bidirectional
+stream.
+
+**CC:** Congestion controller. Estimates network channel capacity and imposes
+limits on transmissions accordingly.
+
+**CFQ:** Control Frame Queue. Considered part of the FIFM, this implements
+the CFQ strategy for frame in flight management. For details, see FIFM
+design document.
+
+**Channel:** Core QUIC connection handling object and connection state machine
+implementation. This is fused tightly with the RXDP.
+
+**CID:** Connection ID.
+
+**CMPL:** The maximum number of bytes left to serialize another QUIC packet into
+the same datagram as one or more previous packets. This is just the MDPL minus
+the total size of all previous packets already serialized into to the same
+datagram.
+
+**CMPPL:** The maximum number of payload bytes we can put in the payload of
+another QUIC packet which is to be coalesced with one or more previous QUIC
+packets and placed into the same datagram. Essentially, this is the room we have
+left for another packet payload.
+
+**CSM:** Connection state machine. Refers to some aspects of a QUIC channel. Not
+implemented as an explicit state machine.
+
+**DCID:** Destination Connection ID. Found in most QUIC packet headers.
+
+**DEMUX:** The demuxer routes incoming packets to the correct connection QRX by
+DCID.
+
+**DGRAM:** (UDP) datagram.
+
+**DISPATCH:** Refers to the QUIC-specific dispatch code in `ssl_lib.c`. This
+dispatches calls to libssl public APIs to the APL.
+
+**EL:** Encryption level. See RFC 9000.
+
+**FC:** Flow control. Comprises TXFC and RXFC.
+
+**FIFD:** Frame-in-flight dispatcher. Ties together the CFQ and TXPIM to handle
+frame tracking and retransmission on loss.
+
+**FIFM:** Frame-in-flight manager. Tracks frames in flight until their
+containing packets are deemed delivered or lost, so that frames can be
+retransmitted if necessary. Comprises the CFQ, TXPIM and FIFD.
+
+**GCR:** Generic Control Frame Retransmission. A strategy for regenerating lost
+frames. Stores raw frame in a queue so that it can be retransmitted if lost. See
+FIFM design document for details.
+
+**Key epoch:** Non-negative number designating a generation of QUIC keys used to
+encrypt or decrypt packets, starting at 0. This increases by 1 when a QUIC key
+update occurs.
+
+**Key Phase:** Key phase bit in QUIC packet headers. See RFC 9000.
+
+**Keyslot**: A set of cryptographic state used to encrypt or decrypt QUIC
+packets by a QRX or QTX. Due to the QUIC key update mechanism, multiple keyslots
+may be maintained at a given time. See `quic_record_rx.h` for details.
+
+**KP:** See Key Phase.
+
+**KS:** See Keyslot.
+
+**Locally-initiated:** Refers to a QUIC stream which was initiated by the local
+application rather than the remote peer.
+
+**MDPL:** Maximum Datagram Payload Length. The maximum number of UDP payload
+bytes we can put in a UDP packet. This is derived from the applicable PMTU. This
+is also the maximum size of a single QUIC packet if we place only one packet in
+a datagram. The MDPL may vary based on both local source IP and destination IP
+due to different path MTUs.
+
+**MinDPL:** In some cases we must ensure a datagram has a minimum size of a
+certain number of bytes. This does not need to be accomplished with a single
+packet, but we may need to add PADDING frames to the final packet added to a
+datagram in this case.
+
+**MinPL:** The minimum serialized packet length we are using while serializing a
+given packet. May often be 0. Used to meet MinDPL requirements, and thus equal
+to MinDPL minus the length of any packets we have already encoded into the
+datagram.
+
+**MinPPL:** The minimum number of bytes which must be placed into a packet
+payload in order to meet the MinPL minimum size when the packet is encoded.
+
+**MPL:** Maximum Packet Length. The maximum size of a fully encrypted and
+serialized QUIC packet in bytes in some given context. Typically equal to the
+MDPL and never greater than it.
+
+**MPPL:** The maximum number of plaintext bytes we can put in the payload of a
+QUIC packet. This is related to the MDPL by the size of the encoded header and
+the size of any AEAD authentication tag which will be attached to the
+ciphertext.
+
+**MSMT:** Multi-stream multi-thread. Refers to a type of multi-stream QUIC usage
+in which API calls can be made on different threads.
+
+**MSST:** Multi-stream single-thread. Refers to a type of multi-stream QUIC
+usage in which API calls must not be made concurrently.
+
+**PN:** Packet number. Most QUIC packet types have a packet number (PN); see RFC
+9000.
+
+**PTO:** Probe timeout. See RFC 9000.
+
+**QC:** See `QUIC_CONNECTION`.
+
+**QCSO:** QUIC Connection SSL Object. This is an SSL object created using
+`SSL_new` using a QUIC method.
+
+**QRL:** QUIC record layer. Refers collectively to the QRX and QTX.
+
+**QRX:** QUIC Record Layer RX. Receives incoming datagrams and decrypts the
+packets contained in them. Manages decrypted packets in a queue pending
+processing by upper layers.
+
+**QS:** See `QUIC_STREAM`.
+
+**QSM:** QUIC Streams Mapper. Manages internal `QUIC_STREAM` objects and maps
+IDs to those objects. Allows iteration of active streams.
+
+**QSO:** QUIC SSL Object. May be a QCSO or a QSSO.
+
+**QSSO:** QUIC Stream SSL Object. This is an SSL object which is subsidiary to a
+given QCSO, obtained using (for example) `SSL_new_stream` or
+`SSL_accept_stream`.
+
+**QTLS**, **QUIC_TLS**: Implements the QUIC handshake layer using TLS 1.3,
+wrapping libssl TLS code to implement the QUIC-specific aspects of QUIC TLS.
+
+**QTX:** QUIC Record Layer TX. Encrypts and sends packets in datagrams.
+
+**QUIC_CONNECTION:** QUIC connection. This is the object representing a QUIC
+connection in the APL.
+
+**QUIC_STREAM**: Internal object tracking a QUIC stream. Unlike an XSO this is
+not part of the APL. An XSO wraps a QUIC_STREAM once that stream is exposed as
+an API object. As such, a `QUIC_CONNECTION` is to a `QUIC_CHANNEL` what a
+`QUIC_XSO` is to a `QUIC_STREAM`.
+
+**REGEN:** A strategy for regenerating lost frames. This strategy regenerates
+the frame from canonical data sources without having to store a copy of the
+frame which was transmitted. See FIFM design document for details.
+
+**Remotely-initiated:** Refers to a QUIC stream which was initiated by the
+remote peer, rather than by the local application.
+
+**RSTREAM:** Receive stream. Internal receive buffer management object used to
+store data which has been RX'd but not yet read by the application.
+
+**RTT:** Round trip time. Time for a datagram to reach a given peer and a reply
+to reach the local machine, assuming the peer responds immediately.
+
+**RXDP:** RX depacketiser. Handles frames in packets which have been decrypted
+by a QRX.
+
+**RXE:** RX entry. Structure containing decrypted received packets awaiting
+processing. Stored in a queue known as the RXL. These structures belong to a
+QRX.
+
+**RXFC:** RX flow control. This determines how much a peer may send to us and
+provides indication of when flow control frames increasing a peer's flow control
+budget should be generated. Exists in both connection-level and stream-level
+instances.
+
+**RXL:** RXE list. See RXE.
+
+**RCMPPL:** The number of bytes left in a packet whose payload we are currently
+forming. This is the CMPPL minus any bytes we have already put into the payload.
+
+**SCID:** Source Connection ID. Found in some QUIC packet headers.
+
+**SSTREAM:** Send stream. Internal send buffer management object used to store
+data which has been passed to libssl for sending but which has not yet been
+transmitted, or not yet been acknowledged.
+
+**STATM:** Statistics manager. Measures estimated connection RTT.
+
+**TA:** Thread assisted mode.
+
+**TPARAM:** Transport parameter.  See RFC 9000.
+
+**TSERVER:** Test server. Internal test server object built around a channel.
+
+**TXE:** TX entry. Structure containing encrypted data pending transmission.
+Owned by the QTX.
+
+**TXFC:** TX flow control. This determines how much can be transmitted to the
+peer. Exists in both connection-level and stream-level instances.
+
+**TXL:** TXE list. See TXE.
+
+**TXP:** TX packetiser. This is responsible for generating yet-unencrypted
+packets and passing them to a QTX for encryption and transmission. It must
+decide how to spend the space available in a datagram.
+
+**TXPIM:** Transmitted Packet Information Manager. Stores information about
+transmitted packets and the frames contained within them. This information
+is needed to facilitate retransmission of frames if the packets they are in
+are lost. Note that the ACKM records only receipt or loss of entire packets,
+whereas TXPIM tracks information about individual frames in those packets.
+
+**TX/RX v. Send/Receive:** The terms *TX*  and *RX* are used for *network-level*
+communication, whereas *send* and *receive* are used for application-level
+communication. An application *sends*  on a stream (causing data to be appended
+to a *send stream buffer*, and that data is eventually TX'd by the TXP and QTX.)
+
+**Uni:** Abbreviation of unidirectional, referring to a QUIC unidirectional
+stream.
+
+**URXE:** Unprocessed RX entry. Structure containing yet-undecrypted received
+datagrams pending processing. Stored in a queue known as the URXL.
+Ownership of URXEs is shared between DEMUX and QRX.
+
+**URXL:** URXE list. See URXE.
+
+**XSO:** External Stream Object. This is the API object representing a QUIC
+stream in the APL. Internally, it is the `QUIC_XSO` structure, externally it is
+a `SSL *` (and is a QSSO).