diff --git a/draft-misell-quic-ex-token.html b/draft-misell-quic-ex-token.html new file mode 100644 index 0000000..e064294 --- /dev/null +++ b/draft-misell-quic-ex-token.html @@ -0,0 +1,1633 @@ + + +
+ + + +Internet-Draft | +QUIC BDP Tokens | +March 2024 | +
Misell | +Expires 5 September 2024 | +[Page] | +
This document describes a method to extend QUIC address validation tokens to include structured data that + a client can parse and make use of. The initial application envisioned in this document is signalling + congestion control parameters for use with Careful Resume.¶
++ This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79.¶
++ Internet-Drafts are working documents of the Internet Engineering Task + Force (IETF). Note that other groups may also distribute working + documents as Internet-Drafts. The list of current Internet-Drafts is + at https://datatracker.ietf.org/drafts/current/.¶
++ Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress."¶
++ This Internet-Draft will expire on 5 September 2024.¶
++ Copyright (c) 2024 IETF Trust and the persons identified as the + document authors. All rights reserved.¶
++ This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (https://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with + respect to this document. Code Components extracted from this + document must include Revised BSD License text as described in + Section 4.e of the Trust Legal Provisions and are provided without + warranty as described in the Revised BSD License.¶
+This document defines a method to extend QUIC address validation tokens to have structure, so that a + client can parse them, and optionally make use of additional information within the token, depending + on the nature of the extensions in use.¶
+The initial application for this is envisioned to be allowing a QUIC server to send calculated Congestion + Control parameters to a client for storage and later use on a future connection with Careful Resume + [I-D.ietf-tsvwg-careful-resume].¶
+The key words MUST, MUST NOT, REQUIRED, SHALL, + SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, + NOT RECOMMENDED, MAY, and OPTIONAL in this document are to be + interpreted as described in [BCP14] when, and only when, they appear in all capitals, + as shown here.¶
+QUIC [RFC9000] defines an address validation token as an opaque blob that + the client should not inspect. This document extends this by providing structure to the token, allowing + arbitrary fields to be defined on the token by this and future documents.¶
+A QUIC client unaware of this document will still be able to make use of extensible tokens without + modification, although it will do nothing but pass the entire token back to the server unmodified.¶
+The format of an extensible token is defined as follows:¶
++BDP Token { + Address Validation Length (i), + Address Validation (..), + Extension ID (i), + Extension Data Length (i), + Extension Data (..), + ... +} ++
The fields are as follows:¶
+Extension ID, Extension Data Length, and Extension Data can be repeated as many times as needed to + include desired extensions. Extension IDs MUST NOT appear multiple times in a token.¶
+The server can send extended tokens to all clients without further negotiation. However a client needs + some way to know that there is meaningful structure to a token its received from the server. To this + end a new transport parameter is defined.¶
+If the server is unable to decode the token received from the client, + or vise versa, this MUST be treated as the connection error + EX_TOKEN_ERROR (0x4143414213370002).¶
+As an extensible token is designed to be presented to clients that may not be aware of what an + extensible token is, all extensions defined for extensible tokens MUST be designed + such that it can handle its data being echoed back to the server unmodified on a future connection.¶
+This document defines the BDP_TOKEN extension, designed to Congestion Control information for use + in Careful Resume [I-D.ietf-tsvwg-careful-resume].¶
+The format of a token extension containing BDP information is defined as follows:¶
++BDP Token { + Private Data Length (i), + Private Data (..), + Capacity (i), + RTT (i), + Requested Capacity (i), +} ++
The fields are as follows:¶
+If the client becomes aware of a change in the available bandwidth of the path, it can use the + Requested Capacity field to signal to the server a change it its available bandwidth. The server + MUST not accept a value higher than that of the Capacity field, as this could cause + an overload of the network path.¶
+If the client sets the Requested Bandwidth field to 0 then it is signalling that the server should + not attempt to prime its congestion controller from previous state and should instead treat this + connection as an entirely new congestion control context.¶
+If a server or client is unable to decode the token received as a valid BDP token then this + MUST be treated as a connection error BDP_TOKEN_ERROR (0x4143414213370003). + A token which is merely expired MUST NOT trigger a connection error, instead it + should be silently discarded.¶
+Per this document, one new entry has been added to the "QUIC Transport Parameters" registry defined in + [RFC9000] section 22.3. This entry is defined below:¶
+Value | +Status | +Specification | +Parameter name | +
---|---|---|---|
0x41434142 13370002 | +Provisional | +This document | +ex_token | +
Per this document, two new entries have been added to the "QUIC Transport Error Codes" registry defined in + [RFC9000] section 22.5. This entry is defined below:¶
+Value | +Status | +Code | +Description | +Specification | +
---|---|---|---|---|
0x41434142 13370002 | +Provisional | +EX_TOKEN_ERROR | +The extensible token received is invalid. | +This document | +
0x41434142 13370003 | +Provisional | +BDP_TOKEN_ERROR | +The BDP token received is invalid. | +This document | +
Per this document, a new registry for "QUIC Extensible Token Extension IDs" is created under the + "QUIC" heading defined in [RFC9000] section 22.¶
+In addition to the fields listed in [RFC9000] section 22.1.1, permanent registrations + in this registry MUST include the following field:¶
+Value | +Extension name | +Specification | +
---|---|---|
0x01 | +BDP_TOKEN | ++ Section 3 + | +
Each value of the form 31 * N + 26 for integer values of N (that is, 26, 57, 88, ...) are reserved + for private use; these values are to be treated as opaque blobs meaningful only to the server + operator.¶
+Each value of the form 31 * N + 27 for integer values of N (that is, 27, 58, 89, ...) are reserved; + these values MUST NOT be assigned by IANA and MUST NOT appear in the + listing of assigned values.¶
+The Congestion Control data MUST be protected against manipulation by malicious or + mis-behaving clients. A client that can modify Congestion Control data could cause an overload of the + network path.¶
+This section is non-normative.¶
+Consider the following private data structure:¶
++Private Data { + IP Address (16 bytes), + Expiry Timestamp (8 bytes) +} ++
This structure contains information that could be used to track a client (its previous IP address), and + therefore MUST be protected from inspection by wire observers. Additionally the Capacity + and RTT fields MUST be protected from modification by a client.¶
+To this end this example uses the ChaCha20-Poly1305 [RFC8439] cipher with additional data. + The ChaCha20-Poly1305 cipher encrypts data, and protects the encrypted data as well as additional + unencrypted data against modification.¶
+The additional data has the following structure:¶
++Additional Data { + Saved Capacity (8 bytes), + Saved RTT (16 bytes) +} ++
After encryption the 12 byte nonce is appended to the Private Data structure to allow the encryption + to be reversed when the token is later used.¶
+View saved issues, or the latest GitHub issues and pull requests in the repo.
+QUIC BDP Tokens | +plain text | +datatracker | +diff with last submission | ++ |