From 84775d46796a7762e5416c85285b146192205e51 Mon Sep 17 00:00:00 2001 From: Mark Nottingham Date: Sun, 2 Feb 2020 14:09:18 +0100 Subject: [PATCH 01/29] Start using 'field' correctly --- draft-ietf-httpbis-semantics-latest.xml | 144 ++++++++++++------------ 1 file changed, 72 insertions(+), 72 deletions(-) diff --git a/draft-ietf-httpbis-semantics-latest.xml b/draft-ietf-httpbis-semantics-latest.xml index ddb996a13..1e9e2ad55 100644 --- a/draft-ietf-httpbis-semantics-latest.xml +++ b/draft-ietf-httpbis-semantics-latest.xml @@ -1086,26 +1086,26 @@ Content-Type: text/plain -
+
This section defines the abstraction for message fields as field-name and field-value pairs. -
+
- Header fields are key:value pairs that can be used to communicate data about - the message, its payload, the target resource, or the connection - (i.e., control data). + Header and trailer fields are key:value pairs that can be used to + communicate data about the message, its payload, the target resource, or + the connection (i.e., control data). - The requirements for header field names are defined in + The requirements for field names are defined in . The field-name token labels the corresponding field-value as having the - semantics defined by that header field. For example, the Date + semantics defined by that field. For example, the Date header field is defined in as containing the origination timestamp for the message in which it appears. @@ -1113,18 +1113,18 @@ Content-Type: text/plain field-name = token - The interpretation of a header field does not change between minor + The interpretation of a field does not change between minor versions of the same major HTTP version, though the default behavior of a recipient in the absence of such a field can change. Unless specified - otherwise, header fields are defined for all versions of HTTP. + otherwise, fields are defined for all versions of HTTP. In particular, the Host and Connection - header fields ought to be implemented by all HTTP/1.x implementations + fields ought to be implemented by all HTTP/1.x implementations whether or not they advertise conformance with HTTP/1.1. - New header fields can be introduced without changing the protocol version + New fields can be introduced without changing the protocol version if their defined semantics allow them to be safely ignored by recipients - that do not recognize them. Header field extensibility is discussed in + that do not recognize them. Field extensibility is discussed in . @@ -1420,29 +1420,29 @@ Content-Type: text/plain -
+
-The "Hypertext Transfer Protocol (HTTP) Header Field Registry" defines the -namespace for HTTP header field names. +The "Hypertext Transfer Protocol (HTTP) Field Registry" defines the +namespace for HTTP field names. -Any party can request registration of a HTTP header field. See Any party can request registration of a HTTP field. See for considerations to take -into account when creating a new HTTP header field. +into account when creating a new HTTP field. -The "HTTP Header Field Name" registry is located at +The "HTTP Field Name" registry is located at "https://www.iana.org/assignments/http-headers/". Registration requests can be made by following the instructions located there or by sending an email to the "ietf-http-wg@ietf.org" mailing list. -Header field names are registered on the advice of a Designated Expert -(appointed by the IESG or their delegate). Header fields with the status +Field names are registered on the advice of a Designated Expert +(appointed by the IESG or their delegate). Fields with the status 'permanent' are Specification Required (using terminology from ). Registration requests consist of at least the following information:
    -
  • Header field name: The requested field name. It MUST conform to the +
  • Field name: The requested field name. It MUST conform to the field-name syntax defined in , and SHOULD be restricted to just letters, digits, hyphen ('-') and underscore ('_') characters, with the first character being a letter.
    • @@ -1450,7 +1450,7 @@ the "ietf-http-wg@ietf.org" mailing list.
  • Status: "permanent" or "provisional"
  • Specification document(s): Reference to the document that specifies - the header field, preferably including a URI that can be used to retrieve + the field, preferably including a URI that can be used to retrieve a copy of the document. An indication of the relevant section(s) can also be included, but is not required.
@@ -1473,18 +1473,18 @@ deployed and not likely to be registered in a timely manner otherwise.
-
+
- Header fields are fully extensible: there is no limit on the + HTTP fields are fully extensible: there is no limit on the introduction of new field names, each presumably defining new semantics, - nor on the number of header fields used in a given message. Existing + nor on the number of fields used in a given message. Existing fields are defined in each part of this specification and in many other specifications outside this document set. - New header fields can be defined such that, when they are understood by a + New fields can be defined such that, when they are understood by a recipient, they might override or enhance the interpretation of previously - defined header fields, define preconditions on request evaluation, or + defined fields, define preconditions on request evaluation, or refine the meaning of responses. @@ -1492,18 +1492,18 @@ deployed and not likely to be registered in a timely manner otherwise. field-name is listed in the Connection header field () or the proxy is specifically configured to block, or otherwise transform, such fields. - Other recipients &SHOULD; ignore unrecognized header fields. + Other recipients &SHOULD; ignore unrecognized header and trailer fields. These requirements allow HTTP's functionality to be enhanced without requiring prior update of deployed intermediaries. - All defined header fields ought to be registered with IANA in the - "HTTP Header Field Name" registry. + All defined fields ought to be registered with IANA in the + "HTTP Field Name" registry.
-
+
@@ -1522,7 +1522,7 @@ deployed and not likely to be registered in a timely manner otherwise. field-vchar = VCHAR / obs-text - Historically, HTTP header field values could be extended over multiple + Historically, HTTP field values could be extended over multiple lines by preceding each extra line with at least one space or horizontal tab (obs-fold). This document assumes that any such obs-fold has been replaced with one or more @@ -1533,16 +1533,16 @@ deployed and not likely to be registered in a timely manner otherwise. Historically, HTTP has allowed field content with text in the ISO&nbhy;8859&nbhy;1 charset , supporting other charsets only through use of encoding. - In practice, most HTTP header field values use only a subset of the + In practice, most HTTP field values use only a subset of the US-ASCII charset . Newly defined - header fields &SHOULD; limit their field values to US&nbhy;ASCII octets. + fields &SHOULD; limit their values to US&nbhy;ASCII octets. A recipient &SHOULD; treat other octets in field content (obs&nbhy;text) as opaque data. -
+
- The order in which header fields with differing field names are + The order in which fields with differing names are received is not significant. However, it is good practice to send header fields that contain control data first, such as Host on requests and Date on responses, so that implementations @@ -1554,19 +1554,19 @@ deployed and not likely to be registered in a timely manner otherwise. Aside from the well-known exception noted below, a sender &MUST-NOT; - generate multiple header fields with the same field name in a message, or - append a header field when a field of the same name already exists in the - message, unless that field's definition allows multiple field values to be - recombined as a comma-separated list [i.e., at least one alternative of - the field's definition allows a comma-separated list, such as an ABNF rule - of #(values)]. + generate multiple fields with the same name in a message (whether in the + headers or trailers), or append a field when a field of the same name + already exists in the message, unless that field's definition allows + multiple field values to be recombined as a comma-separated list [i.e., at + least one alternative of the field's definition allows a comma-separated + list, such as an ABNF rule of #(values)]. - A recipient &MAY; combine multiple header fields with the same field name + A recipient &MAY; combine multiple fields with the same name into one "field-name: field-value" pair, without changing the semantics of the message, by appending each subsequent field value to the combined field value in order, separated by a comma. The order in which - header fields with the same field name are received is therefore + fields with the same name are received is therefore significant to the interpretation of the combined field value; a proxy &MUST-NOT; change the order of these field values when forwarding a message. @@ -1583,34 +1583,34 @@ deployed and not likely to be registered in a timely manner otherwise.
-
+
- HTTP does not place a predefined limit on the length of each header field - or on the length of the header section as a whole, as described in + HTTP does not place a predefined limit on the length of each field + or on the length of the header or trailer section as a whole, as described in . Various ad hoc limitations on individual - header field length are found in practice, often depending on the specific - field semantics. + field length are found in practice, often depending on the specific + field's semantics. - A server that receives a request header field, or set of fields, larger + A server that receives a request header field or set of fields larger than it wishes to process &MUST; respond with an appropriate 4xx (Client Error) status code. Ignoring such header fields would increase the server's vulnerability to request smuggling attacks (). - A client &MAY; discard or truncate received header fields that are larger + A client &MAY; discard or truncate received fields that are larger than the client wishes to process if the field semantics are such that the dropped value(s) can be safely ignored without changing the message framing or response semantics.
-
+
- Many HTTP header field values are defined using common syntax + Many HTTP field values are defined using common syntax components, separated by whitespace or specific delimiting characters. Delimiters are chosen from the set of US-ASCII visual characters not allowed in a token (DQUOTE and "(),/:;<=>?@[\]{}"). @@ -1672,7 +1672,7 @@ deployed and not likely to be registered in a timely manner otherwise. - Comments can be included in some HTTP header fields by surrounding + Comments can be included in some HTTP fields by surrounding the comment text with parentheses. Comments are only allowed in fields containing "comment" as part of their field value definition. @@ -1686,7 +1686,7 @@ deployed and not likely to be registered in a timely manner otherwise. - A parameter is a name=value pair that is often defined within header field + A parameter is a name=value pair that is often defined within field values as a common syntax for appending auxiliary information to an item. Each parameter is usually delimited by an immediately preceding semicolon. @@ -1730,7 +1730,7 @@ deployed and not likely to be registered in a timely manner otherwise. For example, the chunked coding in HTTP/1.1 allows a trailer section after the payload body () which can contain trailer fields: field names and values that share the same syntax and - namespace as header fields but are received after the header section. + namespace as header fields but that are received after the header section. Trailer fields ought to be processed and stored separately from the fields @@ -1744,9 +1744,9 @@ deployed and not likely to be registered in a timely manner otherwise.
- Many header fields cannot be processed outside the header section because + Many fields cannot be processed outside the header section because their evaluation is necessary prior to receiving the message body, such as - fields that describe message framing, routing, authentication, + those that describe message framing, routing, authentication, request modifiers, response controls, or payload format. A sender &MUST-NOT; generate a trailer field unless the sender knows the corresponding header field name's definition permits the field to be sent @@ -1802,7 +1802,7 @@ deployed and not likely to be registered in a timely manner otherwise.
-
+
Authors of specifications defining new fields are advised to choose a short but descriptive field name. Short names avoid needless data transmission; @@ -1817,20 +1817,20 @@ deployed and not likely to be registered in a timely manner otherwise. and "Foo-Description" is needlessly long. - Header field names ought not be prefixed with "X-"; see + Field names ought not be prefixed with "X-"; see for further information. - Other prefixes are sometimes used in HTTP header field names; for example, + Other prefixes are sometimes used in HTTP field names; for example, "Accept-" is used in many content negotiation headers. These prefixes are - only an aid to recognizing the purpose of a header field, and do not + only an aid to recognizing the purpose of a field, and do not trigger automatic processing. - Header field values typically have their syntax defined using ABNF + Field values typically have their syntax defined using ABNF (), using the extension defined in as necessary, and are usually constrained to the range of US-ASCII characters. - Header fields needing a greater range of characters can use an encoding + Fields needing a greater range of characters can use an encoding such as the one defined in . @@ -1860,7 +1860,7 @@ deployed and not likely to be registered in a timely manner otherwise. will likely cause unnecessary confusion. - Many header fields (such as Content-Type, defined in + Many fields (such as Content-Type, defined in ) use a common syntax for parameters that allows both unquoted (token) and quoted (quoted-string) syntax for a parameter value (). Use of common syntax @@ -1869,7 +1869,7 @@ deployed and not likely to be registered in a timely manner otherwise. was received as a token or a quoted string. - Authors of specifications defining new header fields are advised to consider + Authors of specifications defining new fields are advised to consider documenting:
    @@ -1881,13 +1881,13 @@ deployed and not likely to be registered in a timely manner otherwise. be to ignore the field, but this might not always be the right choice). Note that intermediaries and software libraries might combine - multiple header field instances into a single one, despite the + multiple field instances into a single one, despite the field's definition not allowing the list syntax. A robust format enables recipients to discover these situations (good example: "Content-Type", as the comma can only appear inside quoted strings; bad example: "Location", as a comma can occur inside a URI). -
  • Under what conditions the header field can be used; e.g., only in +
  • Under what conditions the field can be used; e.g., only in responses or requests, in all messages, only on responses to a particular request method, etc.
  • Whether the field should be stored by origin servers that @@ -1895,7 +1895,7 @@ deployed and not likely to be registered in a timely manner otherwise.
  • Whether the field semantics are further refined by the context, such as by existing request methods or status codes.
  • Whether it is appropriate to list the field-name in the - Connection header field (i.e., if the header field is to + Connection header field (i.e., if the field is to be hop-by-hop; see ).
  • Under what conditions intermediaries are allowed to insert, delete, or modify the field's value.
    • @@ -1903,9 +1903,9 @@ deployed and not likely to be registered in a timely manner otherwise. Vary response header field (e.g., when the request header field is used by an origin server's content selection algorithm; see ). -
  • Whether the header field is useful or allowable in trailers (see - ).
    • -
  • Whether the header field ought to be preserved across redirects.
    • +
  • Whether the field is allowable in trailers (see + ).
    • +
  • Whether the field ought to be preserved across redirects.
  • Whether it introduces any additional security considerations, such as disclosure of privacy-related data.
From c079d58897333ebc5f4f9a6217b818ea5ffbb0c7 Mon Sep 17 00:00:00 2001 From: Mark Nottingham Date: Sun, 2 Feb 2020 14:11:20 +0100 Subject: [PATCH 02/29] Move some things into the section intro --- draft-ietf-httpbis-semantics-latest.xml | 45 ++++++++++++------------- 1 file changed, 21 insertions(+), 24 deletions(-) diff --git a/draft-ietf-httpbis-semantics-latest.xml b/draft-ietf-httpbis-semantics-latest.xml index 1e9e2ad55..f5d091538 100644 --- a/draft-ietf-httpbis-semantics-latest.xml +++ b/draft-ietf-httpbis-semantics-latest.xml @@ -1087,18 +1087,30 @@ Content-Type: text/plain
- - This section defines the abstraction for message fields as field-name and - field-value pairs. - + + Header and trailer fields are key:value pairs that can be used to + communicate data about the message, its payload, the target resource, or + the connection (i.e., control data). + + + The interpretation of a field does not change between minor + versions of the same major HTTP version, though the default behavior of a + recipient in the absence of such a field can change. Unless specified + otherwise, fields are defined for all versions of HTTP. + In particular, the Host and Connection + fields ought to be implemented by all HTTP/1.x implementations + whether or not they advertise conformance with HTTP/1.1. + + + New fields can be introduced without changing the protocol version + if their defined semantics allow them to be safely ignored by recipients + that do not recognize them. Field extensibility is discussed in + . +
- - Header and trailer fields are key:value pairs that can be used to - communicate data about the message, its payload, the target resource, or - the connection (i.e., control data). - + The requirements for field names are defined in . @@ -1112,21 +1124,6 @@ Content-Type: text/plain field-name = token - - The interpretation of a field does not change between minor - versions of the same major HTTP version, though the default behavior of a - recipient in the absence of such a field can change. Unless specified - otherwise, fields are defined for all versions of HTTP. - In particular, the Host and Connection - fields ought to be implemented by all HTTP/1.x implementations - whether or not they advertise conformance with HTTP/1.1. - - - New fields can be introduced without changing the protocol version - if their defined semantics allow them to be safely ignored by recipients - that do not recognize them. Field extensibility is discussed in - . - The following field names are defined by this document: From 0f24a978e3ac6213d41de939a5f996b3305e9838 Mon Sep 17 00:00:00 2001 From: Mark Nottingham Date: Sun, 2 Feb 2020 14:13:30 +0100 Subject: [PATCH 03/29] Move fields defined in this spec down --- draft-ietf-httpbis-semantics-latest.xml | 586 ++++++++++++------------ 1 file changed, 294 insertions(+), 292 deletions(-) diff --git a/draft-ietf-httpbis-semantics-latest.xml b/draft-ietf-httpbis-semantics-latest.xml index f5d091538..bf04747a9 100644 --- a/draft-ietf-httpbis-semantics-latest.xml +++ b/draft-ietf-httpbis-semantics-latest.xml @@ -1124,298 +1124,6 @@ Content-Type: text/plain field-name = token - - The following field names are defined by this document: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Header Field NameStatusReference
Acceptstandard - -
Accept-Charsetdeprecated - -
Accept-Encodingstandard - -
Accept-Languagestandard - -
Accept-Rangesstandard - -
Allowstandard - -
Authentication-Infostandard - -
Authorizationstandard - -
Content-Encodingstandard - -
Content-Languagestandard - -
Content-Lengthstandard - -
Content-Locationstandard - -
Content-Rangestandard - -
Content-Typestandard - -
Datestandard - -
ETagstandard - -
Expectstandard - -
Fromstandard - -
Hoststandard - -
If-Matchstandard - -
If-Modified-Sincestandard - -
If-None-Matchstandard - -
If-Rangestandard - -
If-Unmodified-Sincestandard - -
Last-Modifiedstandard - -
Locationstandard - -
Max-Forwardsstandard - -
Proxy-Authenticatestandard - -
Proxy-Authentication-Infostandard - -
Proxy-Authorizationstandard - -
Rangestandard - -
Refererstandard - -
Retry-Afterstandard - -
Serverstandard - -
Trailerstandard - -
User-Agentstandard - -
Varystandard - -
Viastandard - -
WWW-Authenticatestandard - -
- - -
@@ -1907,6 +1615,300 @@ deployed and not likely to be registered in a timely manner otherwise. as disclosure of privacy-related data.
+
+ + The following fields are defined by this document: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Header Field NameStatusReference
Acceptstandard + +
Accept-Charsetdeprecated + +
Accept-Encodingstandard + +
Accept-Languagestandard + +
Accept-Rangesstandard + +
Allowstandard + +
Authentication-Infostandard + +
Authorizationstandard + +
Content-Encodingstandard + +
Content-Languagestandard + +
Content-Lengthstandard + +
Content-Locationstandard + +
Content-Rangestandard + +
Content-Typestandard + +
Datestandard + +
ETagstandard + +
Expectstandard + +
Fromstandard + +
Hoststandard + +
If-Matchstandard + +
If-Modified-Sincestandard + +
If-None-Matchstandard + +
If-Rangestandard + +
If-Unmodified-Sincestandard + +
Last-Modifiedstandard + +
Locationstandard + +
Max-Forwardsstandard + +
Proxy-Authenticatestandard + +
Proxy-Authentication-Infostandard + +
Proxy-Authorizationstandard + +
Rangestandard + +
Refererstandard + +
Retry-Afterstandard + +
Serverstandard + +
Trailerstandard + +
User-Agentstandard + +
Varystandard + +
Viastandard + +
WWW-Authenticatestandard + +
+ + + +
From 9bbd428f569783f2ab262e8374adcbc548a03485 Mon Sep 17 00:00:00 2001 From: Mark Nottingham Date: Sun, 2 Feb 2020 14:16:32 +0100 Subject: [PATCH 04/29] Section title tweaks --- draft-ietf-httpbis-semantics-latest.xml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/draft-ietf-httpbis-semantics-latest.xml b/draft-ietf-httpbis-semantics-latest.xml index bf04747a9..f1bac2b98 100644 --- a/draft-ietf-httpbis-semantics-latest.xml +++ b/draft-ietf-httpbis-semantics-latest.xml @@ -1110,7 +1110,6 @@ Content-Type: text/plain
- The requirements for field names are defined in . @@ -1311,7 +1310,7 @@ deployed and not likely to be registered in a timely manner otherwise.
-
+
@@ -1615,7 +1614,7 @@ deployed and not likely to be registered in a timely manner otherwise. as disclosure of privacy-related data.
-
+
The following fields are defined by this document: From c2401e91ee353a6e7de956ba6253bd653a6c56dd Mon Sep 17 00:00:00 2001 From: Mark Nottingham Date: Sun, 2 Feb 2020 14:36:41 +0100 Subject: [PATCH 05/29] Rough in the intro --- draft-ietf-httpbis-semantics-latest.xml | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/draft-ietf-httpbis-semantics-latest.xml b/draft-ietf-httpbis-semantics-latest.xml index f1bac2b98..522bd02fc 100644 --- a/draft-ietf-httpbis-semantics-latest.xml +++ b/draft-ietf-httpbis-semantics-latest.xml @@ -1088,9 +1088,27 @@ Content-Type: text/plain
- Header and trailer fields are key:value pairs that can be used to - communicate data about the message, its payload, the target resource, or - the connection (i.e., control data). + HTTP messages use key/value pairs to convey data about the + message, its payload, the target resource, or the connection (i.e., + control data). They are called "HTTP fields" or just "fields." + + + Every message has two separate areas that such fields can occur within; + the "header field set" (or just "header set") preceding the message + body and containing "header fields" (or just "headers", colloquially) + and the "trailer field set" (or just "trailer set") after the message + body containing "trailer fields" (or just "trailers" colloquially). + Header fields are more common; see for + discussion of the applicability and limitations of trailer fields. + + + Each field has a "field name" (see ) + identifying the field, and a "field value" (see ) that conveys the field's data. + + + See for a discussion of the semantics of + field ordering in messages. The interpretation of a field does not change between minor From e5c6380173b08b155c777502b2f9583453a66c03 Mon Sep 17 00:00:00 2001 From: Mark Nottingham Date: Sun, 2 Feb 2020 14:46:31 +0100 Subject: [PATCH 06/29] remove BCP90 reference, update IANA instructions --- draft-ietf-httpbis-semantics-latest.xml | 33 +++---------------------- 1 file changed, 4 insertions(+), 29 deletions(-) diff --git a/draft-ietf-httpbis-semantics-latest.xml b/draft-ietf-httpbis-semantics-latest.xml index 522bd02fc..8aa457100 100644 --- a/draft-ietf-httpbis-semantics-latest.xml +++ b/draft-ietf-httpbis-semantics-latest.xml @@ -1128,10 +1128,6 @@ Content-Type: text/plain
- - The requirements for field names are defined in - . - The field-name token labels the corresponding field-value as having the semantics defined by that field. For example, the Date @@ -1152,7 +1148,7 @@ target="considerations.for.new.header.fields"/> for considerations to take into account when creating a new HTTP field. The "HTTP Field Name" registry is located at -"https://www.iana.org/assignments/http-headers/". Registration requests can +"https://www.iana.org/assignments/http-fields/". Registration requests can be made by following the instructions located there or by sending an email to the "ietf-http-wg@ietf.org" mailing list. @@ -10403,7 +10399,7 @@ Content-Encoding: gzip
-
+
Please create a new registry as outlined in . @@ -10427,12 +10423,12 @@ Content-Encoding: gzip Please annotate the Permanent and Provisional Message Header registries to - indicate that HTTP header field registrations have moved, with an + indicate that HTTP field registrations have moved, with an appropriate link. After that is complete, please update the new registry with the - header field names listed in the table of . + field names listed in the table of . @@ -11400,27 +11396,6 @@ Content-Encoding: gzip - - - Registration Procedures for Message Header Fields - - Nine by Nine -
GK-IETF@ninebynine.org
- - - BEA Systems -
mnot@pobox.com
- - - HP Labs -
JeffMogul@acm.org
- - - - - - - Deprecating the "X-" Prefix and Similar Constructs in Application Protocols From acc2c24d48f83f392b1fa720b01ca2d231cd1a78 Mon Sep 17 00:00:00 2001 From: Mark Nottingham Date: Sun, 2 Feb 2020 14:49:25 +0100 Subject: [PATCH 07/29] move field order and field limits up --- draft-ietf-httpbis-semantics-latest.xml | 132 ++++++++++++------------ 1 file changed, 66 insertions(+), 66 deletions(-) diff --git a/draft-ietf-httpbis-semantics-latest.xml b/draft-ietf-httpbis-semantics-latest.xml index 8aa457100..915d33d84 100644 --- a/draft-ietf-httpbis-semantics-latest.xml +++ b/draft-ietf-httpbis-semantics-latest.xml @@ -1126,6 +1126,72 @@ Content-Type: text/plain . +
+ + The order in which fields with differing names are + received is not significant. However, it is good practice to send + header fields that contain control data first, such as Host + on requests and Date on responses, so that implementations + can decide when not to handle a message as early as possible. + A server &MUST-NOT; apply a request to the target resource until the entire + request header section is received, since later header fields might include + conditionals, authentication credentials, or deliberately misleading + duplicate header fields that would impact request processing. + + + Aside from the well-known exception noted below, a sender &MUST-NOT; + generate multiple fields with the same name in a message (whether in the + headers or trailers), or append a field when a field of the same name + already exists in the message, unless that field's definition allows + multiple field values to be recombined as a comma-separated list [i.e., at + least one alternative of the field's definition allows a comma-separated + list, such as an ABNF rule of #(values)]. + + + A recipient &MAY; combine multiple fields with the same name + into one "field-name: field-value" pair, without changing the semantics of + the message, by appending each subsequent field value to the combined + field value in order, separated by a comma. The order in which + fields with the same name are received is therefore + significant to the interpretation of the combined field value; + a proxy &MUST-NOT; change the order of these field values when + forwarding a message. + + +
+ +
+ + HTTP does not place a predefined limit on the length of each field + or on the length of the header or trailer section as a whole, as described in + . Various ad hoc limitations on individual + field length are found in practice, often depending on the specific + field's semantics. + + + A server that receives a request header field or set of fields larger + than it wishes to process &MUST; respond with an appropriate + 4xx (Client Error) status code. Ignoring such header fields + would increase the server's vulnerability to request smuggling attacks + (). + + + A client &MAY; discard or truncate received fields that are larger + than the client wishes to process if the field semantics are such that the + dropped value(s) can be safely ignored without changing the + message framing or response semantics. + +
+
@@ -1258,72 +1324,6 @@ deployed and not likely to be registered in a timely manner otherwise. opaque data. -
- - The order in which fields with differing names are - received is not significant. However, it is good practice to send - header fields that contain control data first, such as Host - on requests and Date on responses, so that implementations - can decide when not to handle a message as early as possible. - A server &MUST-NOT; apply a request to the target resource until the entire - request header section is received, since later header fields might include - conditionals, authentication credentials, or deliberately misleading - duplicate header fields that would impact request processing. - - - Aside from the well-known exception noted below, a sender &MUST-NOT; - generate multiple fields with the same name in a message (whether in the - headers or trailers), or append a field when a field of the same name - already exists in the message, unless that field's definition allows - multiple field values to be recombined as a comma-separated list [i.e., at - least one alternative of the field's definition allows a comma-separated - list, such as an ABNF rule of #(values)]. - - - A recipient &MAY; combine multiple fields with the same name - into one "field-name: field-value" pair, without changing the semantics of - the message, by appending each subsequent field value to the combined - field value in order, separated by a comma. The order in which - fields with the same name are received is therefore - significant to the interpretation of the combined field value; - a proxy &MUST-NOT; change the order of these field values when - forwarding a message. - - -
- -
- - HTTP does not place a predefined limit on the length of each field - or on the length of the header or trailer section as a whole, as described in - . Various ad hoc limitations on individual - field length are found in practice, often depending on the specific - field's semantics. - - - A server that receives a request header field or set of fields larger - than it wishes to process &MUST; respond with an appropriate - 4xx (Client Error) status code. Ignoring such header fields - would increase the server's vulnerability to request smuggling attacks - (). - - - A client &MAY; discard or truncate received fields that are larger - than the client wishes to process if the field semantics are such that the - dropped value(s) can be safely ignored without changing the - message framing or response semantics. - -
-
From 61dea5dca6feaaaaf9fd2aaedd8d8092ead39f5f Mon Sep 17 00:00:00 2001 From: Mark Nottingham Date: Sun, 2 Feb 2020 14:50:09 +0100 Subject: [PATCH 08/29] ... "in a message" --- draft-ietf-httpbis-semantics-latest.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-ietf-httpbis-semantics-latest.xml b/draft-ietf-httpbis-semantics-latest.xml index 915d33d84..bbf5d9b3e 100644 --- a/draft-ietf-httpbis-semantics-latest.xml +++ b/draft-ietf-httpbis-semantics-latest.xml @@ -1129,7 +1129,7 @@ Content-Type: text/plain
The order in which fields with differing names are - received is not significant. However, it is good practice to send + received in a message is not significant. However, it is good practice to send header fields that contain control data first, such as Host on requests and Date on responses, so that implementations can decide when not to handle a message as early as possible. From 97077302dd6eeb48515b8992aa5e7517b5fb1d2e Mon Sep 17 00:00:00 2001 From: Mark Nottingham Date: Sun, 2 Feb 2020 14:50:56 +0100 Subject: [PATCH 09/29] set -> section --- draft-ietf-httpbis-semantics-latest.xml | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/draft-ietf-httpbis-semantics-latest.xml b/draft-ietf-httpbis-semantics-latest.xml index bbf5d9b3e..712128b32 100644 --- a/draft-ietf-httpbis-semantics-latest.xml +++ b/draft-ietf-httpbis-semantics-latest.xml @@ -1094,12 +1094,13 @@ Content-Type: text/plain Every message has two separate areas that such fields can occur within; - the "header field set" (or just "header set") preceding the message - body and containing "header fields" (or just "headers", colloquially) - and the "trailer field set" (or just "trailer set") after the message - body containing "trailer fields" (or just "trailers" colloquially). - Header fields are more common; see for - discussion of the applicability and limitations of trailer fields. + the "header field section" (or just "header section") preceding the + message body and containing "header fields" (or just "headers", + colloquially) and the "trailer field section" (or just "trailer + section") after the message body containing "trailer fields" (or just + "trailers" colloquially). Header fields are more common; see for discussion of the applicability and + limitations of trailer fields. Each field has a "field name" (see ) From 1e20692b27bbb8c0023587537a91764d900a1a26 Mon Sep 17 00:00:00 2001 From: Mark Nottingham Date: Sun, 2 Feb 2020 14:52:17 +0100 Subject: [PATCH 10/29] shorten --- draft-ietf-httpbis-semantics-latest.xml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/draft-ietf-httpbis-semantics-latest.xml b/draft-ietf-httpbis-semantics-latest.xml index 712128b32..220dd910c 100644 --- a/draft-ietf-httpbis-semantics-latest.xml +++ b/draft-ietf-httpbis-semantics-latest.xml @@ -1121,10 +1121,9 @@ Content-Type: text/plain whether or not they advertise conformance with HTTP/1.1. - New fields can be introduced without changing the protocol version - if their defined semantics allow them to be safely ignored by recipients - that do not recognize them. Field extensibility is discussed in - . + New fields can be introduced without changing the protocol version if + their defined semantics allow them to be safely ignored by recipients + that do not recognize them; see .
From 510b90df8020f05a824bae75d6625eba5b4c8024 Mon Sep 17 00:00:00 2001 From: Mark Nottingham Date: Sun, 2 Feb 2020 14:57:32 +0100 Subject: [PATCH 11/29] move "field extensibility" up a bit --- draft-ietf-httpbis-semantics-latest.xml | 55 ++++++++++++------------- 1 file changed, 26 insertions(+), 29 deletions(-) diff --git a/draft-ietf-httpbis-semantics-latest.xml b/draft-ietf-httpbis-semantics-latest.xml index 220dd910c..2a7a387d5 100644 --- a/draft-ietf-httpbis-semantics-latest.xml +++ b/draft-ietf-httpbis-semantics-latest.xml @@ -1204,6 +1204,32 @@ Content-Type: text/plain field-name = token +
+ + There is no limit on the introduction of new field names, each presumably + defining new semantics. + + + New fields can be defined such that, when they are understood by a + recipient, they might override or enhance the interpretation of previously + defined fields, define preconditions on request evaluation, or + refine the meaning of responses. + + + A proxy &MUST; forward unrecognized header fields unless the + field-name is listed in the Connection header field + () or the proxy is specifically + configured to block, or otherwise transform, such fields. + Other recipients &SHOULD; ignore unrecognized header and trailer fields. + These requirements allow HTTP's functionality to be enhanced without + requiring prior update of deployed intermediaries. + + + All defined fields ought to be registered with IANA in the + "HTTP Field Name" registry; see . + +
+
The "Hypertext Transfer Protocol (HTTP) Field Registry" defines the @@ -1255,35 +1281,6 @@ Experts can change a provisional entry's status to permanent at any time. Expert(s)), if the Expert(s) determines that an unregistered name is widely deployed and not likely to be registered in a timely manner otherwise. -
- -
- - HTTP fields are fully extensible: there is no limit on the - introduction of new field names, each presumably defining new semantics, - nor on the number of fields used in a given message. Existing - fields are defined in each part of this specification and in many other - specifications outside this document set. - - - New fields can be defined such that, when they are understood by a - recipient, they might override or enhance the interpretation of previously - defined fields, define preconditions on request evaluation, or - refine the meaning of responses. - - - A proxy &MUST; forward unrecognized header fields unless the - field-name is listed in the Connection header field - () or the proxy is specifically - configured to block, or otherwise transform, such fields. - Other recipients &SHOULD; ignore unrecognized header and trailer fields. - These requirements allow HTTP's functionality to be enhanced without - requiring prior update of deployed intermediaries. - - - All defined fields ought to be registered with IANA in the - "HTTP Field Name" registry. -
From e63b519d1183e8f1ee61f1d184c9382033f3f61b Mon Sep 17 00:00:00 2001 From: Mark Nottingham Date: Sun, 2 Feb 2020 14:59:33 +0100 Subject: [PATCH 12/29] make note about ABNF an aside --- draft-ietf-httpbis-semantics-latest.xml | 38 ++++++++++++++----------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/draft-ietf-httpbis-semantics-latest.xml b/draft-ietf-httpbis-semantics-latest.xml index 2a7a387d5..3c37962d7 100644 --- a/draft-ietf-httpbis-semantics-latest.xml +++ b/draft-ietf-httpbis-semantics-latest.xml @@ -1288,14 +1288,7 @@ deployed and not likely to be registered in a timely manner otherwise. - - This specification does not use ABNF rules to define each - "Field-Name: Field Value" pair, as was done in earlier editions. - Instead, this specification uses ABNF rules that are named according to - each registered field name, wherein the rule defines the valid grammar for - that field's corresponding field values (i.e., after the field-value - has been extracted by a generic field parser). - + field-value = *( field-content / obs-fold ) field-content = field-vchar @@ -1303,15 +1296,7 @@ deployed and not likely to be registered in a timely manner otherwise. field-vchar = VCHAR / obs-text - Historically, HTTP field values could be extended over multiple - lines by preceding each extra line with at least one space or horizontal - tab (obs-fold). - This document assumes that any such obs-fold has been replaced with one or more - SP octets prior to interpreting the field value, - as described in . - - - Historically, HTTP has allowed field content with text in the ISO&nbhy;8859&nbhy;1 + Historically, HTTP allowed field content with text in the ISO&nbhy;8859&nbhy;1 charset , supporting other charsets only through use of encoding. In practice, most HTTP field values use only a subset of the @@ -1320,6 +1305,25 @@ deployed and not likely to be registered in a timely manner otherwise. A recipient &SHOULD; treat other octets in field content (obs&nbhy;text) as opaque data. + + Historically, HTTP field values could be extended over multiple + lines by preceding each extra line with at least one space or horizontal + tab (obs-fold). + This document assumes that any such obs-fold has been replaced with one or more + SP octets prior to interpreting the field value, + as described in . + + +
From 59fe08b14698de576aeebde76470b710d940d7f8 Mon Sep 17 00:00:00 2001 From: Mark Nottingham Date: Sun, 2 Feb 2020 15:15:23 +0100 Subject: [PATCH 13/29] rework field ordering and combination --- draft-ietf-httpbis-semantics-latest.xml | 31 +++++++++++++++---------- 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/draft-ietf-httpbis-semantics-latest.xml b/draft-ietf-httpbis-semantics-latest.xml index 3c37962d7..5716c60cb 100644 --- a/draft-ietf-httpbis-semantics-latest.xml +++ b/draft-ietf-httpbis-semantics-latest.xml @@ -1108,8 +1108,11 @@ Content-Type: text/plain target="field.values"/>) that conveys the field's data. - See for a discussion of the semantics of - field ordering in messages. + When defining and processing fields, a given field's value is + considered to be all of the values for the given field name in that + section, concatenated together and separated with commas; see for further discussion of the semantics of + field ordering and combination in messages. The interpretation of a field does not change between minor @@ -1126,7 +1129,7 @@ Content-Type: text/plain that do not recognize them; see . -
+
The order in which fields with differing names are received in a message is not significant. However, it is good practice to send @@ -1138,15 +1141,6 @@ Content-Type: text/plain conditionals, authentication credentials, or deliberately misleading duplicate header fields that would impact request processing. - - Aside from the well-known exception noted below, a sender &MUST-NOT; - generate multiple fields with the same name in a message (whether in the - headers or trailers), or append a field when a field of the same name - already exists in the message, unless that field's definition allows - multiple field values to be recombined as a comma-separated list [i.e., at - least one alternative of the field's definition allows a comma-separated - list, such as an ABNF rule of #(values)]. - A recipient &MAY; combine multiple fields with the same name into one "field-name: field-value" pair, without changing the semantics of @@ -1157,6 +1151,16 @@ Content-Type: text/plain a proxy &MUST-NOT; change the order of these field values when forwarding a message. + + Therefore, aside from the well-known exception noted below, a sender + &MUST-NOT; generate multiple fields with the same name in a message + (whether in the headers or trailers), or append a field when a field of + the same name already exists in the message, unless that field's + definition allows multiple field values to be recombined as a + comma-separated list [i.e., at least one alternative of the field's + definition allows a comma-separated list, such as an ABNF rule of + #(values)]. +