draft-ietf-httpbis-sfbis-05.txt   draft-ietf-httpbis-sfbis-latest.txt 
HTTP Working Group M. Nottingham HTTP Working Group M. Nottingham
Internet-Draft Cloudflare Internet-Draft Cloudflare
Obsoletes: 8941 (if approved) P. Kamp Obsoletes: 8941 (if approved) P. Kamp
Intended status: Standards Track The Varnish Cache Project Intended status: Standards Track The Varnish Cache Project
Expires: July 26, 2024 January 23, 2024 Expires: August 18, 2024 February 15, 2024
Structured Field Values for HTTP Structured Field Values for HTTP
draft-ietf-httpbis-sfbis-05 draft-ietf-httpbis-sfbis-latest
Abstract Abstract
This document describes a set of data types and associated algorithms This document describes a set of data types and associated algorithms
that are intended to make it easier and safer to define and handle that are intended to make it easier and safer to define and handle
HTTP header and trailer fields, known as "Structured Fields", HTTP header and trailer fields, known as "Structured Fields",
"Structured Headers", or "Structured Trailers". It is intended for "Structured Headers", or "Structured Trailers". It is intended for
use by specifications of new HTTP fields that wish to use a common use by specifications of new HTTP fields that wish to use a common
syntax that is more restrictive than traditional HTTP field values. syntax that is more restrictive than traditional HTTP field values.
skipping to change at page 2, line 7 skipping to change at page 2, line 7
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on July 26, 2024. This Internet-Draft will expire on August 18, 2024.
Copyright Notice Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 15 skipping to change at page 3, line 15
4.1.4. Serializing an Integer . . . . . . . . . . . . . . . 20 4.1.4. Serializing an Integer . . . . . . . . . . . . . . . 20
4.1.5. Serializing a Decimal . . . . . . . . . . . . . . . . 21 4.1.5. Serializing a Decimal . . . . . . . . . . . . . . . . 21
4.1.6. Serializing a String . . . . . . . . . . . . . . . . 21 4.1.6. Serializing a String . . . . . . . . . . . . . . . . 21
4.1.7. Serializing a Token . . . . . . . . . . . . . . . . . 22 4.1.7. Serializing a Token . . . . . . . . . . . . . . . . . 22
4.1.8. Serializing a Byte Sequence . . . . . . . . . . . . . 22 4.1.8. Serializing a Byte Sequence . . . . . . . . . . . . . 22
4.1.9. Serializing a Boolean . . . . . . . . . . . . . . . . 23 4.1.9. Serializing a Boolean . . . . . . . . . . . . . . . . 23
4.1.10. Serializing a Date . . . . . . . . . . . . . . . . . 23 4.1.10. Serializing a Date . . . . . . . . . . . . . . . . . 23
4.1.11. Serializing a Display String . . . . . . . . . . . . 23 4.1.11. Serializing a Display String . . . . . . . . . . . . 23
4.2. Parsing Structured Fields . . . . . . . . . . . . . . . . 24 4.2. Parsing Structured Fields . . . . . . . . . . . . . . . . 24
4.2.1. Parsing a List . . . . . . . . . . . . . . . . . . . 26 4.2.1. Parsing a List . . . . . . . . . . . . . . . . . . . 26
4.2.2. Parsing a Dictionary . . . . . . . . . . . . . . . . 27 4.2.2. Parsing a Dictionary . . . . . . . . . . . . . . . . 28
4.2.3. Parsing an Item . . . . . . . . . . . . . . . . . . . 29 4.2.3. Parsing an Item . . . . . . . . . . . . . . . . . . . 29
4.2.4. Parsing an Integer or Decimal . . . . . . . . . . . . 31 4.2.4. Parsing an Integer or Decimal . . . . . . . . . . . . 31
4.2.5. Parsing a String . . . . . . . . . . . . . . . . . . 32 4.2.5. Parsing a String . . . . . . . . . . . . . . . . . . 32
4.2.6. Parsing a Token . . . . . . . . . . . . . . . . . . . 33 4.2.6. Parsing a Token . . . . . . . . . . . . . . . . . . . 33
4.2.7. Parsing a Byte Sequence . . . . . . . . . . . . . . . 34 4.2.7. Parsing a Byte Sequence . . . . . . . . . . . . . . . 34
4.2.8. Parsing a Boolean . . . . . . . . . . . . . . . . . . 34 4.2.8. Parsing a Boolean . . . . . . . . . . . . . . . . . . 35
4.2.9. Parsing a Date . . . . . . . . . . . . . . . . . . . 35 4.2.9. Parsing a Date . . . . . . . . . . . . . . . . . . . 35
4.2.10. Parsing a Display String . . . . . . . . . . . . . . 35 4.2.10. Parsing a Display String . . . . . . . . . . . . . . 35
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36
6. Security Considerations . . . . . . . . . . . . . . . . . . . 37 6. Security Considerations . . . . . . . . . . . . . . . . . . . 37
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.1. Normative References . . . . . . . . . . . . . . . . . . 37 7.1. Normative References . . . . . . . . . . . . . . . . . . 38
7.2. Informative References . . . . . . . . . . . . . . . . . 38 7.2. Informative References . . . . . . . . . . . . . . . . . 38
Appendix A. Frequently Asked Questions . . . . . . . . . . . . . 39 Appendix A. Frequently Asked Questions . . . . . . . . . . . . . 39
A.1. Why Not JSON? . . . . . . . . . . . . . . . . . . . . . . 39 A.1. Why Not JSON? . . . . . . . . . . . . . . . . . . . . . . 39
Appendix B. Implementation Notes . . . . . . . . . . . . . . . . 40 Appendix B. Implementation Notes . . . . . . . . . . . . . . . . 40
Appendix C. ABNF . . . . . . . . . . . . . . . . . . . . . . . . 40 Appendix C. ABNF . . . . . . . . . . . . . . . . . . . . . . . . 40
Appendix D. Changes from RFC 8941 . . . . . . . . . . . . . . . 41 Appendix D. Changes from RFC 8941 . . . . . . . . . . . . . . . 42
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 42 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 42
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42
1. Introduction 1. Introduction
Specifying the syntax of new HTTP header (and trailer) fields is an Specifying the syntax of new HTTP header (and trailer) fields is an
onerous task; even with the guidance in Section 16.3.2 of [HTTP], onerous task; even with the guidance in Section 16.3.2 of [HTTP],
there are many decisions -- and pitfalls -- for a prospective HTTP there are many decisions -- and pitfalls -- for a prospective HTTP
field author. field author.
skipping to change at page 9, line 7 skipping to change at page 9, line 7
accommodate Dates. An RFC8941 implementation would fail parsing such accommodate Dates. An RFC8941 implementation would fail parsing such
a field instance, because they are not defined in that specification. a field instance, because they are not defined in that specification.
If that implementation were upgraded to this specification, parsing If that implementation were upgraded to this specification, parsing
would now succeed. In some cases, the resulting Date value will be would now succeed. In some cases, the resulting Date value will be
rejected by field-specific logic, but values in fields that are rejected by field-specific logic, but values in fields that are
otherwise ignored (such as extension parameters) might not be otherwise ignored (such as extension parameters) might not be
detected and the field might subsequently be accepted and processed. detected and the field might subsequently be accepted and processed.
3. Structured Data Types 3. Structured Data Types
This section defines the abstract types for Structured Fields, and This section provides an overview of the abstract types that
summarizes how those types are serialized into textual HTTP fields. Structured Fields use, and gives a brief description and examples of
how each of those types are serialized into textual HTTP fields.
Section 4 specifies the details of how they are parsed from and
serialized into textual HTTP fields.
In summary: In summary:
o There are three top-level types that an HTTP field can be defined o There are three top-level types that an HTTP field can be defined
as: Lists, Dictionaries, and Items. as: Lists, Dictionaries, and Items.
o Lists and Dictionaries are containers; their members can be Items o Lists and Dictionaries are containers; their members can be Items
or Inner Lists (which are themselves arrays of Items). or Inner Lists (which are themselves arrays of Items).
o Both Items and Inner Lists can be Parameterized with key/value o Both Items and Inner Lists can be Parameterized with key/value
skipping to change at page 15, line 50 skipping to change at page 15, line 50
Example-Date: @1659578233 Example-Date: @1659578233
Parsers MUST support Dates whose values include all days in years 1 Parsers MUST support Dates whose values include all days in years 1
to 9999 (i.e., -62,135,596,800 to 253,402,214,400 delta seconds from to 9999 (i.e., -62,135,596,800 to 253,402,214,400 delta seconds from
1970-01-01T00:00:00Z). 1970-01-01T00:00:00Z).
3.3.8. Display Strings 3.3.8. Display Strings
Display Strings are similar to Strings, in that they consist of zero Display Strings are similar to Strings, in that they consist of zero
or more characters, but they allow Unicode content, unlike Strings. or more characters, but they allow Unicode scalar values (i.e., all
Unicode code points except for surrogates), unlike Strings.
Display Strings are intended for use in cases where a value is Display Strings are intended for use in cases where a value is
displayed to end users, and therefore may need to carry non-ASCII displayed to end users, and therefore may need to carry non-ASCII
content. It is NOT RECOMMENDED that they be used in situations where content. It is NOT RECOMMENDED that they be used in situations where
a String (Section 3.3.3) or Token (Section 3.3.4) would be adequate, a String (Section 3.3.3) or Token (Section 3.3.4) would be adequate,
because Unicode has processing considerations (e.g., normalization) because Unicode has processing considerations (e.g., normalization)
and security considerations (e.g., homograph attacks) that make it and security considerations (e.g., homograph attacks) that make it
more difficult to handle correctly. more difficult to handle correctly.
Note that Display Strings do not indicate the language used in the Note that Display Strings do not indicate the language used in the
skipping to change at page 16, line 26 skipping to change at page 16, line 26
For example: For example:
Example-DisplayString: %"This is intended for display to %c3%bcsers." Example-DisplayString: %"This is intended for display to %c3%bcsers."
See Section 6 for additional security considerations when handling See Section 6 for additional security considerations when handling
Display Strings. Display Strings.
4. Working with Structured Fields in HTTP 4. Working with Structured Fields in HTTP
This section defines how to serialize and parse Structured Fields in This section defines how to serialize and parse the abstract types
textual HTTP field values and other encodings compatible with them defined by Section 3 into textual HTTP field values and other
(e.g., in HTTP/2 [RFC9113] before compression with HPACK [HPACK]). encodings compatible with them (e.g., in HTTP/2 [RFC9113] before
compression with HPACK [HPACK]).
4.1. Serializing Structured Fields 4.1. Serializing Structured Fields
Given a structure defined in this specification, return an ASCII Given a structure defined in this specification, return an ASCII
string suitable for use in an HTTP field value. string suitable for use in an HTTP field value.
1. If the structure is a Dictionary or List and its value is empty 1. If the structure is a Dictionary or List and its value is empty
(i.e., it has no members), do not serialize the field at all (i.e., it has no members), do not serialize the field at all
(i.e., omit both the field-name and field-value). (i.e., omit both the field-name and field-value).
skipping to change at page 24, line 34 skipping to change at page 24, line 34
3. Append encoded_byte to encoded_string. 3. Append encoded_byte to encoded_string.
2. Otherwise, decode byte as an ASCII character and append the 2. Otherwise, decode byte as an ASCII character and append the
result to encoded_string. result to encoded_string.
5. Append DQUOTE to encoded_string. 5. Append DQUOTE to encoded_string.
6. Return encoded_string. 6. Return encoded_string.
Note that [UTF8] prohibits the encoding of codepoints between U+D800
and U+DFFF (surrogates); if they occur in input_sequence,
serialization will fail.
4.2. Parsing Structured Fields 4.2. Parsing Structured Fields
When a receiving implementation parses HTTP fields that are known to When a receiving implementation parses HTTP fields that are known to
be Structured Fields, it is important that care be taken, as there be Structured Fields, it is important that care be taken, as there
are a number of edge cases that can cause interoperability or even are a number of edge cases that can cause interoperability or even
security problems. This section specifies the algorithm for doing security problems. This section specifies the algorithm for doing
so. so.
Given an array of bytes as input_bytes that represent the chosen Given an array of bytes as input_bytes that represent the chosen
field's field-value (which is empty if that field is not present) and field's field-value (which is empty if that field is not present) and
skipping to change at page 36, line 47 skipping to change at page 37, line 8
Please add the following note to the "Hypertext Transfer Protocol Please add the following note to the "Hypertext Transfer Protocol
(HTTP) Field Name Registry": (HTTP) Field Name Registry":
The "Structured Type" column indicates the type of the field (per The "Structured Type" column indicates the type of the field (per
RFC nnnn), if any, and may be "Dictionary", "List" or "Item". RFC nnnn), if any, and may be "Dictionary", "List" or "Item".
Note that field names beginning with characters other than ALPHA Note that field names beginning with characters other than ALPHA
or "*" will not be able to be represented as a Structured Fields or "*" will not be able to be represented as a Structured Fields
Token, and therefore may be incompatible with being mapped into Token, and therefore may be incompatible with being mapped into
fields that refer to it. field values that refer to it.
Then, add a new column, "Structured Type". Then, add a new column, "Structured Type".
Then, add the indicated Structured Type for each existing registry Then, add the indicated Structured Type for each existing registry
entry listed in Table 1. entry listed in Table 1.
+------------------------------------------+-----------------+ +------------------------------------------+-----------------+
| Field Name | Structured Type | | Field Name | Structured Type |
+------------------------------------------+-----------------+ +------------------------------------------+-----------------+
| Accept-CH | List | | Accept-CH | List |
skipping to change at page 37, line 43 skipping to change at page 37, line 50
It is possible for parties with the ability to inject new HTTP fields It is possible for parties with the ability to inject new HTTP fields
to change the meaning of a Structured Field. In some circumstances, to change the meaning of a Structured Field. In some circumstances,
this will cause parsing to fail, but it is not possible to reliably this will cause parsing to fail, but it is not possible to reliably
fail in all such circumstances. fail in all such circumstances.
The Display String type can convey any possible Unicode code point The Display String type can convey any possible Unicode code point
without sanitization; for example, they might contain unassigned code without sanitization; for example, they might contain unassigned code
points, control points (including NUL), or noncharacters. Therefore, points, control points (including NUL), or noncharacters. Therefore,
applications consuming Display Strings need to consider strategies applications consuming Display Strings need to consider strategies
such as filtering or escaping untrusted content before displaying it. such as filtering or escaping untrusted content before displaying it.
See also [UNICODE-SECURITY] and [I-D.draft-bray-unichars]. See also [UNICODE-SECURITY].
7. References 7. References
7.1. Normative References 7.1. Normative References
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110, Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022, DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/info/rfc9110>. <https://www.rfc-editor.org/info/rfc9110>.
skipping to change at page 38, line 22 skipping to change at page 38, line 31
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>. <https://www.rfc-editor.org/info/rfc4648>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[UTF8] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003,
<http://www.rfc-editor.org/info/std63>.
7.2. Informative References 7.2. Informative References
[HPACK] Peon, R. and H. Ruellan, "HPACK: Header Compression for [HPACK] Peon, R. and H. Ruellan, "HPACK: Header Compression for
HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015,
<https://www.rfc-editor.org/info/rfc7541>. <https://www.rfc-editor.org/info/rfc7541>.
[I-D.draft-bray-unichars]
Bray, T. and P. Hoffman, "Unicode Character Repertoire
Subsets", draft-bray-unichars-07 (work in progress),
October 2023.
[IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", [IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic",
IEEE 754-2019, DOI 10.1109/IEEESTD.2019.8766229, IEEE 754-2019, DOI 10.1109/IEEESTD.2019.8766229,
ISBN 978-1-5044-5924-2, July 2019, ISBN 978-1-5044-5924-2, July 2019,
<https://ieeexplore.ieee.org/document/8766229>. <https://ieeexplore.ieee.org/document/8766229>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>. <https://www.rfc-editor.org/info/rfc5234>.
skipping to change at page 39, line 14 skipping to change at page 39, line 23
[RFC9113] Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113, [RFC9113] Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113,
DOI 10.17487/RFC9113, June 2022, DOI 10.17487/RFC9113, June 2022,
<https://www.rfc-editor.org/info/rfc9113>. <https://www.rfc-editor.org/info/rfc9113>.
[UNICODE-SECURITY] [UNICODE-SECURITY]
Davis, M. and M. Suignard, "Unicode Security Davis, M. and M. Suignard, "Unicode Security
Considerations", Unicode Technical Report #16, September Considerations", Unicode Technical Report #16, September
2014, <http://www.unicode.org/reports/tr36/>. 2014, <http://www.unicode.org/reports/tr36/>.
[UTF8] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003,
<http://www.rfc-editor.org/info/std63>.
Appendix A. Frequently Asked Questions Appendix A. Frequently Asked Questions
A.1. Why Not JSON? A.1. Why Not JSON?
Earlier proposals for Structured Fields were based upon JSON Earlier proposals for Structured Fields were based upon JSON
[RFC8259]. However, constraining its use to make it suitable for [RFC8259]. However, constraining its use to make it suitable for
HTTP fields required senders and recipients to implement specific HTTP fields required senders and recipients to implement specific
additional handling. additional handling.
For example, JSON has specification issues around large numbers and For example, JSON has specification issues around large numbers and
 End of changes. 16 change blocks. 
25 lines changed or deleted 29 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/