Internet-Draft | Binary Structured HTTP Field Values | June 2022 |
Nottingham | Expires 24 December 2022 | [Page] |
This specification defines a binary serialisation of Structured Field Values for HTTP, along with a negotiation mechanism for its use in HTTP/2.¶
This note is to be removed before publishing as an RFC.¶
Status information for this document may be found at https://datatracker.ietf.org/doc/draft-nottingham-binary-structured-headers/.¶
information can be found at https://mnot.github.io/I-D/.¶
Source for this draft and an issue tracker can be found at https://github.com/mnot/I-D/labels/binary-structured-headers.¶
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 24 December 2022.¶
Copyright (c) 2022 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.¶
Structured Field Values for HTTP [STRUCTURED-FIELDS] offers a set of data types that new fields can use to express their semantics in a familiar textual syntax. This specification defines an alternative, binary serialisation of those structures in Section 2, and specifies its use in HTTP/2 in Section 3.¶
The primary goal is to reduce parsing overhead and associated costs, as compared to the textual representation of Structured Fields. A secondary goal is a more compact wire format in common situations. An additional goal is to enable future work on more granular field compression mechanisms.¶
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 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
This specification describes formats using the convention described in Section 1.3 of [QUIC].¶
This section defines a binary serialisation for the Structured Field Types defined in [STRUCTURED-FIELDS].¶
The types permissable as the top-level of Structured Field values -- Dictionary, List, and Item -- are defined in terms of a Binary Representation (Section 2.1), which is a replacement for the String Literal Representation in [RFC7541].¶
Binary representations of the remaining structured field types are defined in Section 2.2.¶
Binary Representations are a replacement for the String Literal Representation defined in Section 5.2 of [RFC7541], and can be used to serialise any field, including but not limited to those defined as Structured Fields.¶
All Binary Representations share the following header:¶
Binary Representation { Top Level Type (3), Length (5..), }¶
Its fields are:¶
The following top-level types are defined:¶
Binary Literal field values (type=0x0) carry the string value of a field; they are used to carry field values that are not structured using the data types defined in Section 3 of [STRUCTURED-FIELDS]. This might be because the field is not recognised as a Structured Field, or it might be because a field that is understood to be a Structured Field cannot be parsed successfully as one.¶
A binary literal field value's payload is the raw octets of the field value. As such, they are functionally equivalent to String Literal Representations in Section 5.2 of [RFC7541].¶
Binary Literal Field Value { Top Level Type (3) = 0, Length (5..), Payload (..) }¶
Structured fields whose values are known to be a List as per Section 3.1 of [STRUCTURED-FIELDS] can be conveyed as a binary representation with a top level type of 0x1. They have a payload consisting of one or more Binary Data Types (Section 2.2) representing the members of the list.¶
List Field Value { Top Level Type (3) = 1, Length (5..), Binary Data Type (..) ... }¶
Structured fields whose values are known to be a Dictionary as per Section 3.2 of [STRUCTURED-FIELDS] can be conveyed in a binary representation with a top level type of 0x2. They have a payload consisting of one or more Dictionary Members.¶
Dictionary Field Value { Top Level Type (3) = 2, Length (5..), Dictionary Member (..) ... }¶
Each Dictionary member is represented by a length, followed by that many bytes of the member-name, followed by the Binary Data Type(s) representing the member-value.¶
Dictionary Member { Name Length (8..), Member Name (..), Binary Data Type (..), [Parameters (..)] }¶
The Binary Data Type in a Dictionary Member MUST NOT be a Parameters (0x2).¶
Structured field values that are known to be an Item as per Section 3.3 of [STRUCTURED-FIELDS] can be conveyed in a binary representation with a top level type of 0x3. They have a payload consisting of a single Binary Data Type (Section 2.2), with optional parameters (Section 2.2.2).¶
Item Field Value { Top Level Type (3) = 3, Length (5..), Binary Data Type (..), [Parameters (..)] }¶
The Binary Data Type in an Item Field Value MUST NOT be an Inner List (0x1) or Parameters (0x2).¶
Binary data types are discrete values that are composed into binary representations (Section 2.1) to represent the structured field values.¶
Every binary data type starts with a 4-bit type field that identifies the format of its payload.¶
Binary Data Type { Type (4) }¶
Some data types contain padding bits; senders MUST set padding bits to 0; recipients MUST ignore their values.¶
The Inner List data type (type=0x1) has a payload in the format:¶
Inner List { Type (4) = 1, Length (4..), Binary Data Type (..) ... }¶
Length conveys the number of octets used to represent the inner list, encoded as per Section 5.1 of [RFC7541], with a 4-bit prefix.¶
A Binary Data Type in an Inner List MUST NOT be an Inner List (0x1).¶
Parameters on the Inner List itself, if present, are serialised in a following Parameter type (Section 2.2.2); they do not form part of the payload of the Inner List (and therefore are not counted in Length).¶
The Parameters data type (type=0x2) has a payload in the format:¶
Parameters { Type (4) = 2, Length (4..), Parameter (..) ... }¶
Length conveys the number of octets used to represent the parameters, encoded as per Section 5.1 of [RFC7541], with a 4-bit prefix.¶
Each Parameter conveys a key and a value:¶
Parameter { Parameter Name Length (8..), Parameter Name (..), Binary Data Type (..) }¶
A parameter's fields are:¶
The Binary Data Type in a Parameter MUST NOT be an Inner List (0x1) or Parameters (0x2).¶
Parameters are always associated with the Binary Data Type that immediately preceded them. Therefore, Parameters MUST NOT be the first Binary Data Type in a Binary Representation, and MUST NOT follow another Parameters.¶
The Integer data type (type=0x3) has a payload in the format:¶
Integer { Type (4) = 3, Sign (1), Payload (3..) }¶
Its fields are:¶
The Float data type (type=0x4) have a payload in the format:¶
Float { Type (4) = 4, Sign (1), Integer (3..), Fractional (8..) }¶
Its fields are:¶
The String data type (type=0x5) has a payload in the format:¶
String { Type (4) = 5, Length (4..), Payload (..) }¶
Its payload is Length octets long and ASCII-encoded.¶
The Token data type (type=0x6) has a payload in the format:¶
Token { Type (4) = 6, Length (4..), Payload (..) }¶
Its payload is Length octets long and ASCII-encoded.¶
The Byte Sequence data type (type=0x7) has a payload in the format:¶
Byte Sequence { Type (4) = 7, Length (4..), Payload (..) }¶
The payload is is Length octets long, containing the raw octets of the byte sequence.¶
When both peers on a connection support this specification, they can take advantage of that knowledge to serialise fields that they know to be Structured Fields as binary data, rather than strings.¶
Peers advertise and discover this support using a HTTP/2 setting defined in Section 3.1, and convey Binary Structured Fields in streams whose HEADERS frame uses the flag defined in Section 3.2.¶
Advertising support for Binary Structured Fields is accomplished using a HTTP/2 setting, SETTINGS_BINARY_STRUCTURED_FIELDS (0xTODO).¶
Receiving SETTINGS_BINARY_STRUCTURED_FIELDS with a non-zero value from a peer indicates that:¶
When passing the message to a downstream consumer (whether on the network or not), the peer will:¶
The default value of SETTINGS_BINARY_STRUCTURED_FIELDS is 0, whereas a value of 1 indicates that this specification is supported with no further extensions. Future specifications might use values greater than one to indicate support for extensions.¶
When a peer has indicated that it supports this specification as per Section 3.1, a sender can send the BINARY_STRUCTURED flag (0xTODO) on the HEADERS frame.¶
This flag indicates that the HEADERS frame containing it and subsequent CONTINUATION frames on the same stream use the Binary Representation defined in Section 2.1 instead of the String Literal Representation defined in Section 5.2 of [RFC7541] for all field values. Field names are still serialised as String Literal Representations.¶
In such frames, field values that are known to be Structured Fields and those that can be converted to Structured Fields (as per [RETROFIT]) MAY be sent using the applicable Binary Representation. However, any field value (including those defined as Structured Fields) can also be serialised as a Binary Literal (Section 2.1.1) to accommodate fields that are not defined as Structured Fields, not valid Structured Fields, or that the sending implementation does not wish to send as a Structured Field for some other reason.¶
Binary Representations are stored in the HPACK [RFC7541] dynamic table, and their lengths are used for the purposes of maintaining dynamic table size (see [RFC7541], Section 4).¶
Note that HEADERS frames with and without the BINARY_STRUCTURED flag MAY be mixed on the same connection, depending on the requirements of the sender.¶
As is so often the case, having alternative representations of data brings the potential for security weaknesses, when attackers exploit the differences between those representations and their handling.¶
One mitigation to this risk is the strictness of parsing for both non-binary and binary Structured Fields data types, along with the "escape valve" of Binary Literals (Section 2.1.1). Therefore, implementation divergence from this strictness can have security impact.¶