diff --git a/draft-ietf-quic-transport.md b/draft-ietf-quic-transport.md index fb42e7ead4..c087c5fe63 100644 --- a/draft-ietf-quic-transport.md +++ b/draft-ietf-quic-transport.md @@ -995,22 +995,25 @@ Protected payloads MUST contain at least one frame, and MAY contain multiple frames and multiple frame types. Frames MUST fit within a single QUIC packet and MUST NOT span a QUIC packet -boundary. Each frame begins with a Frame Type byte, indicating its type, -followed by additional type-dependent fields: +boundary. Each frame begins with a Frame Type, indicating its type, followed by +additional type-dependent fields: ~~~ 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Type (8) | Type-Dependent Fields (*) ... +| Type (i) ... ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Type-Dependent Fields (*) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~~~ {: #frame-layout title="Generic Frame Layout"} -Frame types are listed in {{frame-types}}. Note that the Frame Type byte in -STREAM frames is used to carry other frame-specific flags. For all -other frames, the Frame Type byte simply identifies the frame. These frames are -explained in more detail as they are referenced later in the document. +The frame types defined in this specification are listed in {{frame-types}}. +The Frame Type in STREAM frames is used to carry other frame-specific flags. +For all other frames, the Frame Type field simply identifies the frame. These +frames are explained in more detail as they are referenced later in the +document. | Type Value | Frame Type Name | Definition | |:------------|:------------------|:----------------------------| @@ -1038,6 +1041,32 @@ explained in more detail as they are referenced later in the document. All QUIC frames are idempotent. That is, a valid frame does not cause undesirable side effects or errors when received more than once. +The Frame Type field uses a variable length integer encoding (see +{{integer-encoding}}) with one exception. To ensure simple and efficient +implementations of frame parsing, a frame type MUST use the shortest possible +encoding. Though a two-, four- or eight-octet encoding of the frame types +defined in this document is possible, the Frame Type field for these frames are +encoded on a single octet. For instance, though 0x4007 is a legitimate +two-octet encoding for a variable-length integer with a value of 7, PING frames +are always encoded as a single octet with the value 0x07. An endpoint MUST +treat the receipt of a frame type that uses a longer encoding than necessary as +a connection error of type PROTOCOL_VIOLATION. + +## Extension Frames + +QUIC frames do not use a self-describing encoding. An endpoint therefore needs +to understand the syntax of all frames before it can successfully process a +packet. This allows for efficient encoding of frames, but it means that an +endpoint cannot send a frame of a type that is unknown to its peer. + +An extension to QUIC that wishes to use a new type of frame MUST first ensure +that a peer is able to understand the frame. An endpoint can use a transport +parameter to signal its willingness to receive one or more extension frame types +with the one transport parameter. + +An IANA registry is used to manage the assignment of frame types, see +{{iana-frames}}. + # Life of a Connection @@ -2531,7 +2560,11 @@ The CONNECTION_CLOSE frame is as follows: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Error Code (16) | Reason Phrase Length (i) ... +| Error Code (16) | ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Frame Type (i) ... ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +| Reason Phrase Length (i) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Reason Phrase (*) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ @@ -2546,6 +2579,11 @@ Error Code: (APPLICATION_CLOSE uses codes from the application protocol error code space, see {{app-error-codes}}). +Frame Type: + +: The type of frame that triggered the error. A value of 0 (equivalent to the + mention of the PADDING frame) is used when the frame type is unknown. + Reason Phrase Length: : A variable-length integer specifying the length of the reason phrase in bytes. @@ -3027,8 +3065,8 @@ ACK block that follows the gap using the following formula: ~~~ If the calculated value for largest or smallest packet number for any ACK Block -is negative, an endpoint MUST generate a connection error of type FRAME_ERROR -indicating an error in an ACK frame (that is, 0x10d). +is negative, an endpoint MUST generate a connection error of type +FRAME_ENCODING_ERROR indicating an error in an ACK frame. The fields in the ACK Block Section are: @@ -4279,13 +4317,11 @@ FINAL_OFFSET_ERROR (0x6): that was already received. Or an endpoint received a RST_STREAM frame containing a different final offset to the one already established. -FRAME_FORMAT_ERROR (0x7): +FRAME_ENCODING_ERROR (0x7): : An endpoint received a frame that was badly formatted. For instance, an empty STREAM frame that omitted the FIN flag, or an ACK frame that has more - acknowledgment ranges than the remainder of the packet could carry. This is a - generic error code; an endpoint SHOULD use the more specific frame format - error codes (0x1XX) if possible. + acknowledgment ranges than the remainder of the packet could carry. TRANSPORT_PARAMETER_ERROR (0x8): @@ -4314,12 +4350,6 @@ INVALID_MIGRATION (0xC): : A peer has migrated to a different network when the endpoint had disabled migration. -FRAME_ERROR (0x1XX): - -: An endpoint detected an error in a specific frame type. The frame type is - included as the last octet of the error code. For example, an error in a - MAX_STREAM_ID frame would be indicated with the code (0x106). - CRYPTO_ERROR (0x2XX): : The cryptographic handshake failed. A range of 256 values is reserved for @@ -4516,7 +4546,7 @@ Specification: The nominated expert(s) verify that a specification exists and is readily -accessible. The expert(s) are encouraged to be biased towards approving +accessible. Expert(s) are encouraged to be biased towards approving registrations unless they are abusive, frivolous, or actively harmful (not merely aesthetically displeasing, or architecturally dubious). @@ -4536,6 +4566,48 @@ The initial contents of this registry are shown in {{iana-tp-table}}. {: #iana-tp-table title="Initial QUIC Transport Parameters Entries"} +## QUIC Frame Type Registry {#iana-frames} + +IANA \[SHALL add/has added] a registry for "QUIC Frame Types" under a +"QUIC Protocol" heading. + +The "QUIC Frame Types" registry governs a 62-bit space. This space is split +into three spaces that are governed by different policies. Values between 0x00 +and 0x3f (in hexadecimal) are assigned via the Standards Action or IESG Review +policies {{!RFC8126}}. Values from 0x40 to 0x3fff operate on the Specification +Required policy {{!RFC8126}}. All other values are assigned to Private Use +{{!RFC8126}}. + +Registrations MUST include the following fields: + +Value: + +: The numeric value of the assignment (registrations will be between 0x00 and + 0x3fff). A range of values MAY be assigned. + +Frame Name: + +: A short mnemonic for the frame type. + +Specification: + +: A reference to a publicly available specification for the value. + +The nominated expert(s) verify that a specification exists and is readily +accessible. Specifications for new registrations need to describe the means by +which an endpoint might determine that it can send the identified type of frame. +An accompanying transport parameter registration (see +{{iana-transport-parameters}}) is expected for most registrations. The +specification needs to describe the format and assigned semantics of any fields +in the frame. + +Expert(s) are encouraged to be biased towards approving registrations unless +they are abusive, frivolous, or actively harmful (not merely aesthetically +displeasing, or architecturally dubious). + +The initial contents of this registry are tabulated in {{frame-types}}. + + ## QUIC Transport Error Codes Registry {#iana-error-codes} IANA \[SHALL add/has added] a registry for "QUIC Transport Error Codes" under a @@ -4567,26 +4639,24 @@ Specification: : A reference to a publicly available specification for the value. -The initial contents of this registry are shown in {{iana-error-table}}. Note -that FRAME_ERROR takes the range from 0x100 to 0x1FF and private use occupies -the range from 0xFE00 to 0xFFFF. - -| Value | Error | Description | Specification | -|:------------|:--------------------------|:------------------------------|:----------------| -| 0x0 | NO_ERROR | No error | {{error-codes}} | -| 0x1 | INTERNAL_ERROR | Implementation error | {{error-codes}} | -| 0x2 | SERVER_BUSY | Server currently busy | {{error-codes}} | -| 0x3 | FLOW_CONTROL_ERROR | Flow control error | {{error-codes}} | -| 0x4 | STREAM_ID_ERROR | Invalid stream ID | {{error-codes}} | -| 0x5 | STREAM_STATE_ERROR | Frame received in invalid stream state | {{error-codes}} | -| 0x6 | FINAL_OFFSET_ERROR | Change to final stream offset | {{error-codes}} | -| 0x7 | FRAME_FORMAT_ERROR | Generic frame format error | {{error-codes}} | -| 0x8 | TRANSPORT_PARAMETER_ERROR | Error in transport parameters | {{error-codes}} | -| 0x9 | VERSION_NEGOTIATION_ERROR | Version negotiation failure | {{error-codes}} | -| 0xA | PROTOCOL_VIOLATION | Generic protocol violation | {{error-codes}} | -| 0xB | UNSOLICITED_PATH_RESPONSE | Unsolicited PATH_RESPONSE frame | {{error-codes}} | -| 0xC | INVALID_MIGRATION | Violated disabled migration | {{error-codes}} | -| 0x100-0x1FF | FRAME_ERROR | Specific frame format error | {{error-codes}} | +The initial contents of this registry are shown in {{iana-error-table}}. Values +from 0xFF00 to 0xFFFF are reserved for Private Use {{!RFC8126}}. + +| Value | Error | Description | Specification | +|:------|:--------------------------|:------------------------------|:----------------| +| 0x0 | NO_ERROR | No error | {{error-codes}} | +| 0x1 | INTERNAL_ERROR | Implementation error | {{error-codes}} | +| 0x2 | SERVER_BUSY | Server currently busy | {{error-codes}} | +| 0x3 | FLOW_CONTROL_ERROR | Flow control error | {{error-codes}} | +| 0x4 | STREAM_ID_ERROR | Invalid stream ID | {{error-codes}} | +| 0x5 | STREAM_STATE_ERROR | Frame received in invalid stream state | {{error-codes}} | +| 0x6 | FINAL_OFFSET_ERROR | Change to final stream offset | {{error-codes}} | +| 0x7 | FRAME_ENCODING_ERROR | Frame encoding error | {{error-codes}} | +| 0x8 | TRANSPORT_PARAMETER_ERROR | Error in transport parameters | {{error-codes}} | +| 0x9 | VERSION_NEGOTIATION_ERROR | Version negotiation failure | {{error-codes}} | +| 0xA | PROTOCOL_VIOLATION | Generic protocol violation | {{error-codes}} | +| 0xB | UNSOLICITED_PATH_RESPONSE | Unsolicited PATH_RESPONSE frame | {{error-codes}} | +| 0xC | INVALID_MIGRATION | Violated disabled migration | {{error-codes}} | {: #iana-error-table title="Initial QUIC Transport Error Codes Entries"}