diff --git a/draft-ietf-quic-http.md b/draft-ietf-quic-http.md index 180452b952..90ddbce398 100644 --- a/draft-ietf-quic-http.md +++ b/draft-ietf-quic-http.md @@ -872,74 +872,81 @@ establishment to servers. QUIC allows the application to abruptly terminate (reset) individual streams or the entire connection when an error is encountered. These are referred to as "stream errors" or "connection errors" and are described in more detail in -[QUIC-TRANSPORT]. +{{QUIC-TRANSPORT}}. This section describes HTTP-specific error codes which can be used to express the cause of a connection or stream error. -## HTTP-Defined QUIC Error Codes {#http-error-codes} +## HTTP/QUIC Error Codes {#http-error-codes} -QUIC allocates error codes 0x0000-0x3FFF to application protocol definition. The -following error codes are defined by HTTP for use in QUIC RST_STREAM and -CONNECTION_CLOSE frames. +The following error codes are defined for use in QUIC RST_STREAM and +APPLICATION_CLOSE frames when using HTTP/QUIC. -HTTP_PUSH_REFUSED (0x01): +STOPPING (0x00): +: This value is reserved by the transport to be used in response to QUIC + STOP_SENDING frames. + +HTTP_NO_ERROR (0x01): +: No error. This is used when the connection or stream needs to be closed, but + there is no error to signal. + +HTTP_PUSH_REFUSED (0x02): : The server has attempted to push content which the client will not accept on this connection. -HTTP_INTERNAL_ERROR (0x02): +HTTP_INTERNAL_ERROR (0x03): : An internal error has occurred in the HTTP stack. -HTTP_PUSH_ALREADY_IN_CACHE (0x03): +HTTP_PUSH_ALREADY_IN_CACHE (0x04): : The server has attempted to push content which the client has cached. -HTTP_REQUEST_CANCELLED (0x04): +HTTP_REQUEST_CANCELLED (0x05): : The client no longer needs the requested data. -HTTP_HPACK_DECOMPRESSION_FAILED (0x05): +HTTP_HPACK_DECOMPRESSION_FAILED (0x06): : HPACK failed to decompress a frame and cannot continue. -HTTP_CONNECT_ERROR (0x06): +HTTP_CONNECT_ERROR (0x07): : The connection established in response to a CONNECT request was reset or abnormally closed. -HTTP_EXCESSIVE_LOAD (0x07): +HTTP_EXCESSIVE_LOAD (0x08): : The endpoint detected that its peer is exhibiting a behavior that might be generating excessive load. -HTTP_VERSION_FALLBACK (0x08): +HTTP_VERSION_FALLBACK (0x09): : The requested operation cannot be served over HTTP/QUIC. The peer should retry over HTTP/2. -HTTP_MALFORMED_HEADERS (0x09): +HTTP_MALFORMED_HEADERS (0x0A): : A HEADERS frame has been received with an invalid format. -HTTP_MALFORMED_PRIORITY (0x0A): +HTTP_MALFORMED_PRIORITY (0x0B): : A PRIORITY frame has been received with an invalid format. -HTTP_MALFORMED_SETTINGS (0x0B): +HTTP_MALFORMED_SETTINGS (0x0C): : A SETTINGS frame has been received with an invalid format. -HTTP_MALFORMED_PUSH_PROMISE (0x0C): +HTTP_MALFORMED_PUSH_PROMISE (0x0D): : A PUSH_PROMISE frame has been received with an invalid format. -HTTP_MALFORMED_DATA (0x0D): +HTTP_MALFORMED_DATA (0x0E): : A DATA frame has been received with an invalid format. -HTTP_INTERRUPTED_HEADERS (0x0E): +HTTP_INTERRUPTED_HEADERS (0x0F): : A HEADERS frame without the End Header Block flag was followed by a frame other than HEADERS. -HTTP_WRONG_STREAM (0x0F): +HTTP_WRONG_STREAM (0x10): : A frame was received on stream where it is not permitted. -HTTP_MULTIPLE_SETTINGS (0x10): +HTTP_MULTIPLE_SETTINGS (0x11): : More than one SETTINGS frame was received. -HTTP_MALFORMED_PUSH (0x11): +HTTP_MALFORMED_PUSH (0x12): : A push stream header was malformed or included an invalid Push ID. -HTTP_MALFORMED_MAX_PUSH_ID (0x12): +HTTP_MALFORMED_MAX_PUSH_ID (0x13): : A MAX_PUSH_ID frame has been received with an invalid format. @@ -1089,11 +1096,11 @@ QUIC has the same concepts of "stream" and "connection" errors that HTTP/2 provides. However, because the error code space is shared between multiple components, there is no direct portability of HTTP/2 error codes. -The HTTP/2 error codes defined in Section 7 of {{!RFC7540}} map to QUIC error -codes as follows: +The HTTP/2 error codes defined in Section 7 of {{!RFC7540}} map to the HTTP over +QUIC error codes as follows: NO_ERROR (0x0): -: QUIC_NO_ERROR +: HTTP_NO_ERROR in {{http-error-codes}}. PROTOCOL_ERROR (0x1): : No single mapping. See new HTTP_MALFORMED_* error codes defined in @@ -1270,7 +1277,7 @@ The entries in the following table are registered by this document. ## Error Codes {#iana-error-codes} This document establishes a registry for HTTP/QUIC error codes. The -"HTTP/QUIC Error Code" registry manages a 30-bit space. The "HTTP/QUIC +"HTTP/QUIC Error Code" registry manages a 32-bit space. The "HTTP/QUIC Error Code" registry operates under the "Expert Review" policy {{?RFC5226}}. @@ -1285,7 +1292,7 @@ Name: : A name for the error code. Specifying an error code name is optional. Code: -: The 30-bit error code value. +: The 32-bit error code value. Description: : A brief description of the error code semantics, longer if no detailed @@ -1299,24 +1306,26 @@ The entries in the following table are registered by this document. |-----------------------------------|--------|----------------------------------------|----------------------| | Name | Code | Description | Specification | |-----------------------------------|--------|----------------------------------------|----------------------| -| HTTP_PUSH_REFUSED | 0x01 | Client refused pushed content | {{http-error-codes}} | -| HTTP_INTERNAL_ERROR | 0x02 | Internal error | {{http-error-codes}} | -| HTTP_PUSH_ALREADY_IN_CACHE | 0x03 | Pushed content already cached | {{http-error-codes}} | -| HTTP_REQUEST_CANCELLED | 0x04 | Data no longer needed | {{http-error-codes}} | -| HTTP_HPACK_DECOMPRESSION_FAILED | 0x05 | HPACK cannot continue | {{http-error-codes}} | -| HTTP_CONNECT_ERROR | 0x06 | TCP reset or error on CONNECT request | {{http-error-codes}} | -| HTTP_EXCESSIVE_LOAD | 0x07 | Peer generating excessive load | {{http-error-codes}} | -| HTTP_VERSION_FALLBACK | 0x08 | Retry over HTTP/2 | {{http-error-codes}} | -| HTTP_MALFORMED_HEADERS | 0x09 | Invalid HEADERS frame | {{http-error-codes}} | -| HTTP_MALFORMED_PRIORITY | 0x0A | Invalid PRIORITY frame | {{http-error-codes}} | -| HTTP_MALFORMED_SETTINGS | 0x0B | Invalid SETTINGS frame | {{http-error-codes}} | -| HTTP_MALFORMED_PUSH_PROMISE | 0x0C | Invalid PUSH_PROMISE frame | {{http-error-codes}} | -| HTTP_MALFORMED_DATA | 0x0D | Invalid DATA frame | {{http-error-codes}} | -| HTTP_INTERRUPTED_HEADERS | 0x0E | Incomplete HEADERS block | {{http-error-codes}} | -| HTTP_WRONG_STREAM | 0x0F | A frame was sent on the wrong stream | {{http-error-codes}} | -| HTTP_MULTIPLE_SETTINGS | 0x10 | Multiple SETTINGS frames | {{http-error-codes}} | -| HTTP_MALFORMED_PUSH | 0x11 | Invalid push stream header | {{http-error-codes}} | -| HTTP_MALFORMED_MAX_PUSH_ID | 0x12 | Invalid MAX_PUSH_ID frame | {{http-error-codes}} | +| STOPPING | 0x00 | Reserved by QUIC | {{QUIC-TRANSPORT}} | +| HTTP_NO_ERROR | 0x01 | No error | {{http-error-codes}} | +| HTTP_PUSH_REFUSED | 0x02 | Client refused pushed content | {{http-error-codes}} | +| HTTP_INTERNAL_ERROR | 0x03 | Internal error | {{http-error-codes}} | +| HTTP_PUSH_ALREADY_IN_CACHE | 0x04 | Pushed content already cached | {{http-error-codes}} | +| HTTP_REQUEST_CANCELLED | 0x05 | Data no longer needed | {{http-error-codes}} | +| HTTP_HPACK_DECOMPRESSION_FAILED | 0x06 | HPACK cannot continue | {{http-error-codes}} | +| HTTP_CONNECT_ERROR | 0x07 | TCP reset or error on CONNECT request | {{http-error-codes}} | +| HTTP_EXCESSIVE_LOAD | 0x08 | Peer generating excessive load | {{http-error-codes}} | +| HTTP_VERSION_FALLBACK | 0x09 | Retry over HTTP/2 | {{http-error-codes}} | +| HTTP_MALFORMED_HEADERS | 0x0A | Invalid HEADERS frame | {{http-error-codes}} | +| HTTP_MALFORMED_PRIORITY | 0x0B | Invalid PRIORITY frame | {{http-error-codes}} | +| HTTP_MALFORMED_SETTINGS | 0x0C | Invalid SETTINGS frame | {{http-error-codes}} | +| HTTP_MALFORMED_PUSH_PROMISE | 0x0D | Invalid PUSH_PROMISE frame | {{http-error-codes}} | +| HTTP_MALFORMED_DATA | 0x0E | Invalid DATA frame | {{http-error-codes}} | +| HTTP_INTERRUPTED_HEADERS | 0x0F | Incomplete HEADERS block | {{http-error-codes}} | +| HTTP_WRONG_STREAM | 0x10 | A frame was sent on the wrong stream | {{http-error-codes}} | +| HTTP_MULTIPLE_SETTINGS | 0x11 | Multiple SETTINGS frames | {{http-error-codes}} | +| HTTP_MALFORMED_PUSH | 0x12 | Invalid push stream header | {{http-error-codes}} | +| HTTP_MALFORMED_MAX_PUSH_ID | 0x13 | Invalid MAX_PUSH_ID frame | {{http-error-codes}} | |-----------------------------------|--------|----------------------------------------|----------------------| diff --git a/draft-ietf-quic-tls.md b/draft-ietf-quic-tls.md index eff99dfe85..ef96c23ae5 100644 --- a/draft-ietf-quic-tls.md +++ b/draft-ietf-quic-tls.md @@ -1505,42 +1505,54 @@ SHOULD track redundant packets and treat excessive volumes of any non-productive packets as indicative of an attack. -# Error codes {#errors} +# Error Codes {#errors} -The portion of the QUIC error code space allocated for the crypto handshake is -0xC0000000-0xFFFFFFFF. The following error codes are defined when TLS is used -for the crypto handshake: +This section defines error codes from the error code space used in +{{QUIC-TRANSPORT}}. -TLS_HANDSHAKE_FAILED (0xC000001C): +The following error codes are defined when TLS is used for the crypto handshake: + +TLS_HANDSHAKE_FAILED (0x201): : The TLS handshake failed. -TLS_FATAL_ALERT_GENERATED (0xC000001D): +TLS_FATAL_ALERT_GENERATED (0x202): : A TLS fatal alert was sent, causing the TLS connection to end prematurely. -TLS_FATAL_ALERT_RECEIVED (0xC000001E): +TLS_FATAL_ALERT_RECEIVED (0x203): : A TLS fatal alert was received, causing the TLS connection to end prematurely. # IANA Considerations -This document does not create any new IANA registries, but it does utilize the -following registries: +This document does not create any new IANA registries, but it registers the +values in the following registries: -* QUIC Transport Parameter Registry - IANA is to register the three values found - in {{errors}}. +* QUIC Transport Error Codes Registry {{QUIC-TRANSPORT}} - IANA is to register + the three error codes found in {{errors}}, these are summarized in + {{iana-errors}}. -* TLS ExtensionsType Registry - IANA is to register the - quic_transport_parameters extension found in {{quic_parameters}}. Assigning - 26 to the extension would be greatly appreciated. The Recommended column is - to be marked Yes. +* TLS ExtensionsType Registry + {{!TLS-REGISTRIES=I-D.ietf-tls-iana-registry-updates}} - IANA is to register + the quic_transport_parameters extension found in {{quic_parameters}}. + Assigning 26 to the extension would be greatly appreciated. The Recommended + column is to be marked Yes. -* TLS Exporter Label Registry - IANA is requested to register - "EXPORTER-QUIC 0-RTT Secret" from {{zero-rtt-secrets}}; +* TLS Exporter Label Registry {{!TLS-REGISTRIES}} - IANA is requested to + register "EXPORTER-QUIC 0-RTT Secret" from {{zero-rtt-secrets}}; "EXPORTER-QUIC client 1-RTT Secret" and "EXPORTER-QUIC server 1-RTT Secret" from {{one-rtt-secrets}}; "EXPORTER-QUIC Packet Number Secret" {{packet-number-gaps}}. The DTLS column is to be marked No. The Recommended column is to be marked Yes. +| Value | Error | Description | Specification | +|:------|:--------------------------|:----------------------|:--------------| +| 0x201 | TLS_HANDSHAKE_FAILED | TLS handshake failure | {{errors}} | +| 0x202 | TLS_FATAL_ALERT_GENERATED | Sent TLS alert | {{errors}} | +| 0x203 | TLS_FATAL_ALERT_RECEIVED | Receives TLS alert | {{errors}} | +{: #iana-errors title="QUIC Transport Error Codes for TLS"} + + + --- back # Contributors diff --git a/draft-ietf-quic-transport.md b/draft-ietf-quic-transport.md index 1e0482ca07..9d276ca799 100644 --- a/draft-ietf-quic-transport.md +++ b/draft-ietf-quic-transport.md @@ -846,6 +846,7 @@ explained in more detail as they are referenced later in the document. | 0x00 | PADDING | {{frame-padding}} | | 0x01 | RST_STREAM | {{frame-rst-stream}} | | 0x02 | CONNECTION_CLOSE | {{frame-connection-close}} | +| 0x03 | APPLICATION_CLOSE | {{frame-application-close}} | | 0x04 | MAX_DATA | {{frame-max-data}} | | 0x05 | MAX_STREAM_DATA | {{frame-max-stream-data}} | | 0x06 | MAX_STREAM_ID | {{frame-max-stream-id}} | @@ -1497,19 +1498,19 @@ signal the timeout using an immediate close. ### Immediate Close -An endpoint sends a CONNECTION_CLOSE frame to terminate the connection -immediately. A CONNECTION_CLOSE causes all open streams to immediately become -closed; open streams can be assumed to be implicitly reset. After sending or -receiving a CONNECTION_CLOSE frame, endpoints immediately enter a draining -period. +An endpoint sends a CONNECTION_CLOSE or APPLICATION_CLOSE frame to terminate the +connection immediately. Either frame causes all open streams to immediately +become closed; open streams can be assumed to be implicitly reset. After +sending or receiving a CONNECTION_CLOSE frame, endpoints immediately enter a +draining period. -During the draining period, an endpoint that sends a CONNECTION_CLOSE frame -SHOULD respond to any subsequent packet that it receives with another packet -containing a CONNECTION_CLOSE frame. To reduce the state that an endpoint -maintains in this case, it MAY send the exact same packet. However, endpoints -SHOULD limit the number of CONNECTION_CLOSE messages they generate. For -instance, an endpoint could progressively increase the number of packets that it -receives before sending additional CONNECTION_CLOSE frames. +During the draining period, an endpoint that sends a CONNECTION_CLOSE or +APPLICATION_CLOSE frame SHOULD respond to any subsequent packet that it receives +with another packet containing either close frame. To reduce the state that an +endpoint maintains in this case, it MAY send the exact same packet. However, +endpoints SHOULD limit the number of packets they generate containing either +close frame. For instance, an endpoint could progressively increase the number +of packets that it receives before sending additional packets. Note: @@ -1519,9 +1520,9 @@ Note: control, which are not expected to be relevant for a closed connection. Retransmitting the final packet requires less state. -An endpoint can cease sending CONNECTION_CLOSE frames if it receives either a -CONNECTION_CLOSE or an acknowledgement for a packet that contained a -CONNECTION_CLOSE. +An endpoint can cease sending CONNECTION_CLOSE or APPLICATION_CLOSE frames if it +receives either a CONNECTION_CLOSE, APPLICATION_CLOSE or an acknowledgement for +a packet that contained a either close frame. ### Stateless Reset {#stateless-reset} @@ -1530,7 +1531,8 @@ A stateless reset is provided as an option of last resort for a server that does not have access to the state of a connection. A server crash or outage might result in clients continuing to send data to a server that is unable to properly continue the connection. A server that wishes to communicate a fatal connection -error MUST use a CONNECTION_CLOSE frame if it has sufficient state to do so. +error MUST use a CONNECTION_CLOSE or APPLICATION_CLOSE frame if it has +sufficient state to do so. To support this process, the server sends a stateless_reset_token value during the handshake in the transport parameters. This value is protected by @@ -1584,7 +1586,7 @@ indistinguishable from a regular packet. A stateless reset is not appropriate for signaling error conditions. An endpoint that wishes to communicate a fatal connection error MUST use a -CONNECTION_CLOSE frame if it has sufficient state to do so. +CONNECTION_CLOSE or APPLICATION_CLOSE frame if it has sufficient state to do so. #### Detecting a Stateless Reset @@ -1670,7 +1672,7 @@ The RST_STREAM frame is as follows: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Stream ID (32) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Error Code (32) | +| Application Protocol Error Code (32) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | + Final Offset (64) + @@ -1684,11 +1686,12 @@ Stream ID: : The 32-bit Stream ID of the stream being terminated. -Error code: +Application Protocol Error Code: -: A 32-bit error code which indicates why the stream is being closed. +: A 32-bit application protocol error code (see {{app-error-codes}}) which + indicates why the stream is being closed. -Final offset: +Final Offset: : A 64-bit unsigned integer indicating the absolute byte offset of the end of data written on this stream by the RST_STREAM sender. @@ -1697,15 +1700,19 @@ Final offset: ## CONNECTION_CLOSE frame {#frame-connection-close} An endpoint sends a CONNECTION_CLOSE frame (type=0x02) to notify its peer that -the connection is being closed. If there are open streams that haven't been -explicitly closed, they are implicitly closed when the connection is closed. -The frame is as follows: +the connection is being closed. CONNECTION_CLOSE is used to signal errors at +the QUIC layer, or the absence of errors (with the NO_ERROR code). + +If there are open streams that haven't been explicitly closed, they are +implicitly closed when the connection is closed. + +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 (32) | +| Error Code (32) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Reason Phrase Length (16) | [Reason Phrase (*)] ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ @@ -1716,6 +1723,9 @@ The fields of a CONNECTION_CLOSE frame are as follows: Error Code: : A 32-bit error code which indicates the reason for closing this connection. + CONNECTION_CLOSE uses codes from the space defined in {{error-codes}} + (APPLICATION_CLOSE uses codes from the application protocol error code space, + see {{app-error-codes}}). Reason Phrase Length: @@ -1731,6 +1741,17 @@ Reason Phrase: This SHOULD be a UTF-8 encoded string {{!RFC3629}}. +## APPLICATION_CLOSE frame {#frame-application-close} + +An APPLICATION_CLOSE frame (type=0x03) uses the same format as the +CONNECTION_CLOSE frame ({{frame-connection-close}}), except that it uses error +codes from the application protocol error code space ({{app-error-codes}}) +instead of the transport error code space. + +Other than the error code space, the format and semantics of the +APPLICATION_CLOSE frame are identical to the CONNECTION_CLOSE frame. + + ## MAX_DATA Frame {#frame-max-data} The MAX_DATA frame (type=0x04) is used in flow control to inform the peer of @@ -1963,8 +1984,9 @@ Stateless Reset Token: An endpoint may use a STOP_SENDING frame (type=0x0c) to communicate that incoming data is being discarded on receipt at application request. This -signals a peer to abruptly terminate transmission on a stream. The frame is as -follows: +signals a peer to abruptly terminate transmission on a stream. + +The STOP_SENDING frame is as follows: ~~~ 0 1 2 3 @@ -1972,17 +1994,21 @@ follows: +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Stream ID (32) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Error Code (32) | +| Application Error Code (32) | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ~~~ The fields are: Stream ID: + : The 32-bit Stream ID of the stream being ignored. -Error Code: -: The application-specified reason the sender is ignoring the stream. +Application Error Code: + +: A 32-bit, application-specified reason the sender is ignoring the stream (see + {{app-error-codes}}). + ## ACK Frame {#frame-ack} @@ -2690,23 +2716,25 @@ Reordering might cause frames to be received after closing, see ## Solicited State Transitions -If an endpoint is no longer interested in the data being received, it MAY send a -STOP_SENDING frame on a stream in the "open" or "half-closed (local)" state to -prompt closure of the stream in the opposite direction. This typically -indicates that the receiving application is no longer reading from the stream, -but is not a guarantee that incoming data will be ignored. +If an endpoint is no longer interested in the data it is receiving on a stream, +it MAY send a STOP_SENDING frame identifying that stream to prompt closure of +the stream in the opposite direction. This typically indicates that the +receiving application is no longer reading data it receives from the stream, but +is not a guarantee that incoming data will be ignored. STREAM frames received after sending STOP_SENDING are still counted toward the connection and stream flow-control windows, even though these frames will be discarded upon receipt. This avoids potential ambiguity about which STREAM frames count toward flow control. -Upon receipt of a STOP_SENDING frame on a stream in the "open" or "half-closed -(remote)" states, an endpoint MUST send a RST_STREAM with an error code of -QUIC_RECEIVED_RST. If the STOP_SENDING frame is received on a stream that is -already in the "half-closed (local)" or "closed" states, a RST_STREAM frame MAY -still be sent in order to cancel retransmission of previously-sent STREAM -frames. +STOP_SENDING can only be sent for any stream that is not "idle", however it is +mostly useful for streams in the "open" or "half-closed (local)" states. A +STOP_SENDING frame requests that the receiving application send a RST_STREAM +frame. An endpoint that receives a STOP_SENDING frame MUST send a RST_STREAM +frame for that stream with an error code of STOPPING. If the STOP_SENDING frame +is received on a stream that is already in the "half-closed (local)" or "closed" +states, a RST_STREAM frame MAY still be sent in order to cancel retransmission +of previously-sent STREAM frames. While STOP_SENDING frames are retransmittable, an implementation MAY choose not to retransmit a lost STOP_SENDING frame if the stream has already been closed @@ -2980,32 +3008,39 @@ frame that signals the error. Where this specification identifies error conditions, it also identifies the error code that is used. A stateless reset ({{stateless-reset}}) is not suitable for any error that can -be signaled with a CONNECTION_CLOSE or RST_STREAM frame. A stateless reset MUST -NOT be used by an endpoint that has the state necessary to send a frame on the -connection. +be signaled with a CONNECTION_CLOSE, APPLICATION_CLOSE, or RST_STREAM frame. A +stateless reset MUST NOT be used by an endpoint that has the state necessary to +send a frame on the connection. ## Connection Errors Errors that result in the connection being unusable, such as an obvious violation of protocol semantics or corruption of state that affects an entire -connection, MUST be signaled using a CONNECTION_CLOSE frame -({{frame-connection-close}}). An endpoint MAY close the connection in this -manner, even if the error only affects a single stream. - -A CONNECTION_CLOSE frame could be sent in a packet that is lost. An endpoint -SHOULD be prepared to retransmit a packet containing a CONNECTION_CLOSE frame if -it receives more packets on a terminated connection. Limiting the number of -retransmissions and the time over which this final packet is sent limits the -effort expended on terminated connections. +connection, MUST be signaled using a CONNECTION_CLOSE or APPLICATION_CLOSE frame +({{frame-connection-close}}, {{frame-application-close}}). An endpoint MAY close +the connection in this manner even if the error only affects a single stream. + +Application protocols can signal application-specific protocol errors using the +APPLICATION_CLOSE frame. Errors that are specific to the transport, including +all those described in this document, are carried in a CONNECTION_CLOSE frame. +Other than the type of error code they carry, these frames are identical in +format and semantics. + +A CONNECTION_CLOSE or APPLICATION_CLOSE frame could be sent in a packet that is +lost. An endpoint SHOULD be prepared to retransmit a packet containing either +frame type if it receives more packets on a terminated connection. Limiting the +number of retransmissions and the time over which this final packet is sent +limits the effort expended on terminated connections. An endpoint that chooses not to retransmit packets containing CONNECTION_CLOSE -risks a peer missing the first such packet. The only mechanism available to an -endpoint that continues to receive data for a terminated connection is to use -the stateless reset process ({{stateless-reset}}). +or APPLICATION_CLOSE risks a peer missing the first such packet. The only +mechanism available to an endpoint that continues to receive data for a +terminated connection is to use the stateless reset process +({{stateless-reset}}). -An endpoint that receives an invalid CONNECTION_CLOSE frame MUST NOT signal the -existence of the error to its peer. +An endpoint that receives an invalid CONNECTION_CLOSE or APPLICATION_CLOSE frame +MUST NOT signal the existence of the error to its peer. ## Stream Errors @@ -3019,74 +3054,46 @@ Stream 0 is critical to the functioning of the entire connection. If stream 0 is closed with either a RST_STREAM or STREAM frame bearing the FIN flag, an endpoint MUST generate a connection error of type PROTOCOL_VIOLATION. -Some application protocols make other streams critical to that protocol. An -application protocol does not need to inform the transport that a stream is -critical; it can instead generate appropriate errors in response to being -notified that the critical stream is closed. +RST_STREAM MUST be instigated by the application and MUST carry an application +error code. Resetting a stream without knowledge of the application protocol +could cause the protocol to enter an unrecoverable state. Application protocols +might require certain streams to be reliably delivered in order to guarantee +consistent state between endpoints. -An endpoint MAY send a RST_STREAM frame in the same packet as a CONNECTION_CLOSE -frame. +## Transport Error Codes {#error-codes} -## Error Codes - -Error codes are 32 bits long, with the first two bits indicating the source of -the error code: - -0x00000000-0x3FFFFFFF: -: Application-specific error codes. Defined by each application-layer protocol. - -0x40000000-0x7FFFFFFF: -: Reserved for host-local error codes. These codes MUST NOT be sent to a peer, - but MAY be used in API return codes and logs. - -0x80000000-0xBFFFFFFF: -: QUIC transport error codes, including packet protection errors. Applicable to - all uses of QUIC. - -0xC0000000-0xFFFFFFFF: -: Cryptographic error codes. Defined by the cryptographic handshake protocol - in use. +Transport error codes are 32 bits long. This section lists the defined QUIC transport error codes that may be used in a -CONNECTION_CLOSE or RST_STREAM frame. Error codes share a common code space. -Some error codes apply only to either streams or the entire connection and have -no defined semantics in the other context. +CONNECTION_CLOSE frame. These errors apply to the entire connection. -NO_ERROR (0x80000000): +NO_ERROR (0x0): : An endpoint uses this with CONNECTION_CLOSE to signal that the connection is - being closed abruptly in the absence of any error. An endpoint uses this with - RST_STREAM to signal that the stream is no longer wanted or in response to the - receipt of a RST_STREAM for that stream. + being closed abruptly in the absence of any error. -INTERNAL_ERROR (0x80000001): +INTERNAL_ERROR (0x1): : The endpoint encountered an internal error and cannot continue with the connection. -CANCELLED (0x80000002): - -: An endpoint sends this with RST_STREAM to indicate that the stream is not - wanted and that no application action was taken for the stream. This error - code is not valid for use with CONNECTION_CLOSE. - -FLOW_CONTROL_ERROR (0x80000003): +FLOW_CONTROL_ERROR (0x3): : An endpoint received more data than it permitted in its advertised data limits (see {{flow-control}}). -STREAM_ID_ERROR (0x80000004): +STREAM_ID_ERROR (0x4): : An endpoint received a frame for a stream identifier that exceeded its advertised maximum stream ID. -STREAM_STATE_ERROR (0x80000005): +STREAM_STATE_ERROR (0x5): : An endpoint received a frame for a stream that was not in a state that permitted that frame (see {{stream-states}}). -FINAL_OFFSET_ERROR (0x80000006): +FINAL_OFFSET_ERROR (0x6): : An endpoint received a STREAM frame containing data that exceeded the previously established final offset. Or an endpoint received a RST_STREAM @@ -3094,40 +3101,51 @@ FINAL_OFFSET_ERROR (0x80000006): 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 (0x80000007): +FRAME_FORMAT_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 (0x800001XX) if possible. + error codes (0x1XX) if possible. -TRANSPORT_PARAMETER_ERROR (0x80000008): +TRANSPORT_PARAMETER_ERROR (0x8): : An endpoint received transport parameters that were badly formatted, included an invalid value, was absent even though it is mandatory, was present though it is forbidden, or is otherwise in error. -VERSION_NEGOTIATION_ERROR (0x80000009): +VERSION_NEGOTIATION_ERROR (0x9): : An endpoint received transport parameters that contained version negotiation parameters that disagreed with the version negotiation that it performed. This error code indicates a potential version downgrade attack. -PROTOCOL_VIOLATION (0x8000000A): +PROTOCOL_VIOLATION (0xA): : An endpoint detected an error with protocol compliance that was not covered by more specific error codes. -QUIC_RECEIVED_RST (0x80000035): - -: Terminating stream because peer sent a RST_STREAM or STOP_SENDING. - -FRAME_ERROR (0x800001XX): +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 (0x80000106). + MAX_STREAM_ID frame would be indicated with the code (0x106). + +See {{iana-error-codes}} for details of registering new error codes. + + +## Application Protocol Error Codes {#app-error-codes} + +Application protocol error codes are 32-bits long, but the management of +application error codes are left to application protocols. Application protocol +error codes are used for the RST_STREAM ({{frame-rst-stream}}) and +APPLICATION_CLOSE ({{frame-application-close}}) frames. + +There is no restriction on the use of the 16-bit error code space for +application protocols. However, QUIC reserves the error code with a value of 0 +to mean STOPPING. The application error code of STOPPING (0) is used by the +transport to cancel a stream in response to receipt of a STOP_SENDING frame. # Security and Privacy Considerations @@ -3248,8 +3266,7 @@ accessible. The 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 shown in -{{iana-tp-table}}. +The initial contents of this registry are shown in {{iana-tp-table}}. | Value | Parameter Name | Specification | |:-------|:------------------------|:------------------------------------| @@ -3263,6 +3280,57 @@ The initial contents of this registry are shown in {: #iana-tp-table title="Initial QUIC Transport Parameters Entries"} +## QUIC Transport Error Codes Registry {#iana-error-codes} + +IANA \[SHALL add/has added] a registry for "QUIC Transport Error Codes" under a +"QUIC Protocol" heading. + +The "QUIC Transport Error Codes" registry governs a 32-bit space. This space is +split into two spaces that are governed by different policies. Values with the +first byte in the range 0x00 to 0xfe (in hexadecimal) are assigned via the +Specification Required policy {{!RFC5226}}. Values with the first byte 0xff are +reserved for Private Use {{!RFC5226}}. + +Registrations MUST include the following fields: + +Value: + +: The numeric value of the assignment (registrations will be between 0x00000000 + and 0xfeffffff). + +Code: + +: A short mnemonic for the parameter. + +Description: + +: A brief description of the error code semantics, which MAY be a summary if a + specification reference is provided. + +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 0XFE000000 to 0XFFFFFFFF. + +| Value | Error | Description | Specification | +|:------------|:--------------------------|:------------------------------|:----------------| +| 0x0 | NO_ERROR | No error | {{error-codes}} | +| 0x1 | INTERNAL_ERROR | Implementation error | {{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}} | +| 0x100-0x1FF | FRAME_ERROR | Specific frame format error | {{error-codes}} | +{: #iana-error-table title="Initial QUIC Transport Error Codes Entries"} + + --- back # Contributors