draft-ietf-httpbis-sfbis-03.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: February 4, 2024 August 3, 2023 | Expires: March 15, 2024 September 12, 2023 | |||
Structured Field Values for HTTP | Structured Field Values for HTTP | |||
draft-ietf-httpbis-sfbis-03 | 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 February 4, 2024. | This Internet-Draft will expire on March 15, 2024. | |||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2023 IETF Trust and the persons identified as the | Copyright (c) 2023 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 33 ¶ | skipping to change at page 3, line 33 ¶ | |||
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 . . . . . . . . . . . . . . . . . . . 36 | 6. Security Considerations . . . . . . . . . . . . . . . . . . . 36 | |||
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 | 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 | |||
7.1. Normative References . . . . . . . . . . . . . . . . . . 37 | 7.1. Normative References . . . . . . . . . . . . . . . . . . 37 | |||
7.2. Informative References . . . . . . . . . . . . . . . . . 37 | 7.2. Informative References . . . . . . . . . . . . . . . . . 37 | |||
Appendix A. Frequently Asked Questions . . . . . . . . . . . . . 38 | Appendix A. Frequently Asked Questions . . . . . . . . . . . . . 38 | |||
A.1. Why Not JSON? . . . . . . . . . . . . . . . . . . . . . . 38 | A.1. Why Not JSON? . . . . . . . . . . . . . . . . . . . . . . 38 | |||
Appendix B. Implementation Notes . . . . . . . . . . . . . . . . 39 | Appendix B. Implementation Notes . . . . . . . . . . . . . . . . 39 | |||
Appendix C. ABNF . . . . . . . . . . . . . . . . . . . . . . . . 40 | Appendix C. ABNF . . . . . . . . . . . . . . . . . . . . . . . . 40 | |||
Appendix D. Changes from RFC 8941 . . . . . . . . . . . . . . . 42 | Appendix D. Changes from RFC 8941 . . . . . . . . . . . . . . . 41 | |||
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 15, line 52 ¶ | skipping to change at page 15, line 52 ¶ | |||
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 | |||
value; that can be done separately if necessary (e.g., with a | value; that can be done separately if necessary (e.g., with a | |||
parameter). | parameter). | |||
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 Structured Fields in | |||
textual HTTP field values and other encodings compatible with them | textual HTTP field values and other encodings compatible with them | |||
(e.g., in HTTP/2 [RFC9113] before compression with HPACK [HPACK]). | (e.g., in HTTP/2 [RFC9113] before compression with HPACK [HPACK]). | |||
4.1. Serializing Structured Fields | 4.1. Serializing Structured Fields | |||
skipping to change at page 23, line 40 ¶ | skipping to change at page 23, line 40 ¶ | |||
with input_date (Section 4.1.4). | with input_date (Section 4.1.4). | |||
3. Return output. | 3. Return output. | |||
4.1.11. Serializing a Display String | 4.1.11. Serializing a Display String | |||
Given a sequence of Unicode codepoints as input_sequence, return an | Given a sequence of Unicode codepoints as input_sequence, return an | |||
ASCII string suitable for use in an HTTP field value. | ASCII string suitable for use in an HTTP field value. | |||
1. If input_sequence is not a sequence of Unicode codepoints, fail | 1. If input_sequence is not a sequence of Unicode codepoints, fail | |||
parsing. | serialization. | |||
2. Let byte_array be the result of applying UTF-8 encoding [UTF8] to | 2. Let byte_array be the result of applying UTF-8 encoding [UTF8] to | |||
input_sequence. | input_sequence. | |||
3. Let encoded_string be a string containing "%" followed by DQUOTE. | 3. Let encoded_string be a string containing "%" followed by DQUOTE. | |||
4. For each byte in byte_array: | 4. For each byte in byte_array: | |||
1. If byte is %x25 ("%"), %x22 (DQUOTE), or in the ranges | 1. If byte is %x25 ("%"), %x22 (DQUOTE), or in the ranges | |||
%x00-1f or %x7f-ff: | %x00-1f or %x7f-ff: | |||
1. Append "%" to encoded_string. | 1. Append "%" to encoded_string. | |||
2. Let encoded_byte be the result of applying base16 | 2. Let encoded_byte be the result of applying base16 | |||
encoding (Section 8 of [RFC4648]) to byte. | encoding (Section 8 of [RFC4648]) to byte, with any | |||
alphabetic characters converted to lowercase. | ||||
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. | |||
skipping to change at page 35, line 31 ¶ | skipping to change at page 35, line 31 ¶ | |||
2. If char is in the range %x00-1f or %x7f-ff (i.e., it is not | 2. If char is in the range %x00-1f or %x7f-ff (i.e., it is not | |||
in VCHAR or SP), fail parsing. | in VCHAR or SP), fail parsing. | |||
3. If char is "%": | 3. If char is "%": | |||
1. Let octet_hex be the result of consuming two characters | 1. Let octet_hex be the result of consuming two characters | |||
from input_string. If there are not two characters, fail | from input_string. If there are not two characters, fail | |||
parsing. | parsing. | |||
2. Let octet be the result of hex decoding octet_hex | 2. If octet_hex contains characters outside the range | |||
(Section 8 of [RFC4648]), in a case-insensitive fashion. | %x30-39 or %x61-66 (i.e., it is not in 0-9 or lowercase | |||
If decoding fails, fail parsing. | a-f), fail parsing. | |||
3. Append octet to byte_array. | 3. Let octet be the result of hex decoding octet_hex | |||
(Section 8 of [RFC4648]). | ||||
4. Append octet to byte_array. | ||||
4. If char is DQUOTE: | 4. If char is DQUOTE: | |||
1. Let unicode_sequence be the result of decoding byte_array | 1. Let unicode_sequence be the result of decoding byte_array | |||
as a UTF-8 string [UTF8]. Fail parsing if decoding | as a UTF-8 string [UTF8]. Fail parsing if decoding | |||
fails. | fails. | |||
2. Return unicode_sequence. | 2. Return unicode_sequence. | |||
5. Otherwise, if char is not "%" or DQUOTE: | 5. Otherwise, if char is not "%" or DQUOTE: | |||
skipping to change at page 40, line 9 ¶ | skipping to change at page 40, line 11 ¶ | |||
Implementations are allowed to limit the size of different | Implementations are allowed to limit the size of different | |||
structures, subject to the minimums defined for each type. When a | structures, subject to the minimums defined for each type. When a | |||
structure exceeds an implementation limit, that structure fails | structure exceeds an implementation limit, that structure fails | |||
parsing or serialization. | parsing or serialization. | |||
Appendix C. ABNF | Appendix C. ABNF | |||
This section uses the Augmented Backus-Naur Form (ABNF) notation | This section uses the Augmented Backus-Naur Form (ABNF) notation | |||
[RFC5234] to illustrate expected syntax of Structured Fields. | [RFC5234] to illustrate expected syntax of Structured Fields. | |||
However, it cannot be used to validate their syntax, because it does | ||||
not capture all requirements. | ||||
This section is non-normative. If there is disagreement between the | This section is non-normative. If there is disagreement between the | |||
parsing algorithms and ABNF, the specified algorithms take | parsing algorithms and ABNF, the specified algorithms take | |||
precedence. | precedence. | |||
sf-list = list-member *( OWS "," OWS list-member ) | sf-list = list-member *( OWS "," OWS list-member ) | |||
list-member = sf-item / inner-list | list-member = sf-item / inner-list | |||
inner-list = "(" *SP [ sf-item *( 1*SP sf-item ) *SP ] ")" | ||||
parameters | ||||
parameters = *( ";" *SP parameter ) | ||||
parameter = param-key [ "=" param-value ] | ||||
param-key = key | ||||
key = ( lcalpha / "*" ) | ||||
*( lcalpha / DIGIT / "_" / "-" / "." / "*" ) | ||||
lcalpha = %x61-7A ; a-z | ||||
param-value = bare-item | ||||
sf-dictionary = dict-member *( OWS "," OWS dict-member ) | ||||
dict-member = member-key ( parameters / ( "=" member-value )) | ||||
member-key = key | ||||
member-value = sf-item / inner-list | ||||
sf-item = bare-item parameters | ||||
bare-item = sf-integer / sf-decimal / sf-string / sf-token | ||||
/ sf-binary / sf-boolean / sf-date | ||||
sf-integer = ["-"] 1*15DIGIT | inner-list = "(" *SP [ sf-item *( 1*SP sf-item ) *SP ] ")" | |||
parameters | ||||
sf-decimal = ["-"] 1*12DIGIT "." 1*3DIGIT | parameters = *( ";" *SP parameter ) | |||
parameter = param-key [ "=" param-value ] | ||||
param-key = key | ||||
key = ( lcalpha / "*" ) | ||||
*( lcalpha / DIGIT / "_" / "-" / "." / "*" ) | ||||
lcalpha = %x61-7A ; a-z | ||||
param-value = bare-item | ||||
sf-string = DQUOTE *chr DQUOTE | sf-dictionary = dict-member *( OWS "," OWS dict-member ) | |||
chr = unescaped / escaped | dict-member = member-key ( parameters / ( "=" member-value )) | |||
unescaped = %x20-21 / %x23-5B / %x5D-7E | member-key = key | |||
escaped = "\" ( DQUOTE / "\" ) | member-value = sf-item / inner-list | |||
sf-token = ( ALPHA / "*" ) *( tchar / ":" / "/" ) | sf-item = bare-item parameters | |||
bare-item = sf-integer / sf-decimal / sf-string / sf-token | ||||
/ sf-binary / sf-boolean / sf-date / sf-displaystring | ||||
sf-binary = ":" *(base64) ":" | sf-integer = ["-"] 1*15DIGIT | |||
base64 = ALPHA / DIGIT / "+" / "/" / "=" | sf-decimal = ["-"] 1*12DIGIT "." 1*3DIGIT | |||
sf-string = DQUOTE *( unescaped / "%" / bs-escaped ) DQUOTE | ||||
sf-token = ( ALPHA / "*" ) *( tchar / ":" / "/" ) | ||||
sf-binary = ":" base64 ":" | ||||
sf-boolean = "?" ( "0" / "1" ) | ||||
sf-date = "@" sf-integer | ||||
sf-displaystring = "%" DQUOTE *( unescaped / "\" / pct-encoded ) DQUOTE | ||||
sf-boolean = "?" boolean | base64 = *( ALPHA / DIGIT / "+" / "/" ) *"=" | |||
boolean = "0" / "1" | ||||
sf-date = "@" sf-integer | unescaped = %x20-21 / %x23-24 / %x26-5B / %x5D-7E | |||
bs-escaped = "\" ( DQUOTE / "\" ) | ||||
sf-displaystring = "%" DQUOTE *uchr DQUOTE | pct-encoded = "%" lc-hexdig lc-hexdig | |||
uchr = chr / uescaped | lc-hexdig = DIGIT / %x61-66 ; 0-9, a-f | |||
uescaped = "%" HEXDIG HEXDIG | ||||
Appendix D. Changes from RFC 8941 | Appendix D. Changes from RFC 8941 | |||
This revision of the Structured Field Values for HTTP specification | This revision of the Structured Field Values for HTTP specification | |||
has made the following changes: | has made the following changes: | |||
o Added the Date structured type. (Section 3.3.7) | o Added the Date structured type. (Section 3.3.7) | |||
o Stopped encouraging use of ABNF in definitions of new structured | o Stopped encouraging use of ABNF in definitions of new structured | |||
fields. (Section 2) | fields. (Section 2) | |||
o Moved ABNF to an informative appendix. (Appendix C) | o Moved ABNF to an informative appendix. (Appendix C) | |||
o Added a "Structured Type" column to the HTTP Field Name Registry. | o Added a "Structured Type" column to the HTTP Field Name Registry. | |||
(Section 5) | (Section 5) | |||
o Refined parse failure handling. (Section 4.2) | o Refined parse failure handling. (Section 4.2) | |||
End of changes. 20 change blocks. | ||||
49 lines changed or deleted | 48 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/ |