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/