idnits 2.17.1 draft-nottingham-binary-structured-headers-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [3], [4], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 10, 2020) is 1540 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 818 -- Looks like a reference, but probably isn't: '2' on line 820 -- Looks like a reference, but probably isn't: '3' on line 822 -- Looks like a reference, but probably isn't: '4' on line 825 -- Looks like a reference, but probably isn't: '5' on line 828 -- Looks like a reference, but probably isn't: '6' on line 830 -- Looks like a reference, but probably isn't: '7' on line 832 -- Looks like a reference, but probably isn't: '8' on line 834 -- Looks like a reference, but probably isn't: '9' on line 836 -- Looks like a reference, but probably isn't: '10' on line 838 -- Looks like a reference, but probably isn't: '11' on line 840 -- Looks like a reference, but probably isn't: '12' on line 842 -- Looks like a reference, but probably isn't: '13' on line 854 -- Looks like a reference, but probably isn't: '14' on line 935 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-header-structure-14 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 15 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft Fastly 4 Intended status: Standards Track January 10, 2020 5 Expires: July 13, 2020 7 Binary Structured HTTP Headers 8 draft-nottingham-binary-structured-headers-01 10 Abstract 12 This specification defines a binary serialisation of Structured 13 Headers for HTTP, along with a negotiation mechanism for its use in 14 HTTP/2. It also defines how to use Structured Headers for many 15 existing headers - thereby "backporting" them - when supported by two 16 peers. 18 Note to Readers 20 _RFC EDITOR: please remove this section before publication_ 22 The issues list for this draft can be found at 23 https://github.com/mnot/I-D/labels/binary-structured-headers [1]. 25 The most recent (often, unpublished) draft is at 26 https://mnot.github.io/I-D/binary-structured-headers/ [2]. 28 Recent changes are listed at https://github.com/mnot/I-D/commits/gh- 29 pages/binary-structured-headers [3]. 31 See also the draft's current status in the IETF datatracker, at 32 https://datatracker.ietf.org/doc/draft-nottingham-binary-structured- 33 headers/ [4]. 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at https://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on July 13, 2020. 51 Copyright Notice 53 Copyright (c) 2020 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents 58 (https://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with respect 61 to this document. Code Components extracted from this document must 62 include Simplified BSD License text as described in Section 4.e of 63 the Trust Legal Provisions and are provided without warranty as 64 described in the Simplified BSD License. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 69 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 70 2. Binary Structured Headers . . . . . . . . . . . . . . . . . . 3 71 2.1. The Binary Literal Representation . . . . . . . . . . . . 4 72 2.1.1. Lists . . . . . . . . . . . . . . . . . . . . . . . . 4 73 2.1.2. Dictionaries . . . . . . . . . . . . . . . . . . . . 4 74 2.1.3. Items . . . . . . . . . . . . . . . . . . . . . . . . 5 75 2.1.4. String Literals . . . . . . . . . . . . . . . . . . . 5 76 2.2. Binary Structured Types . . . . . . . . . . . . . . . . . 5 77 2.2.1. Inner Lists . . . . . . . . . . . . . . . . . . . . . 6 78 2.2.2. Parameters . . . . . . . . . . . . . . . . . . . . . 6 79 2.2.3. Item Payload Types . . . . . . . . . . . . . . . . . 7 80 3. Using Binary Structured Headers in HTTP/2 . . . . . . . . . . 10 81 3.1. Binary Structured Headers Setting . . . . . . . . . . . . 10 82 3.2. The BINHEADERS Frame . . . . . . . . . . . . . . . . . . 11 83 4. Using Binary Structured Headers with Existing Fields . . . . 12 84 4.1. Directly Represented Fields . . . . . . . . . . . . . . . 12 85 4.2. Aliased Fields . . . . . . . . . . . . . . . . . . . . . 14 86 4.2.1. URLs . . . . . . . . . . . . . . . . . . . . . . . . 15 87 4.2.2. Dates . . . . . . . . . . . . . . . . . . . . . . . . 15 88 4.2.3. ETags . . . . . . . . . . . . . . . . . . . . . . . . 16 89 4.2.4. Links . . . . . . . . . . . . . . . . . . . . . . . . 16 90 4.2.5. Cookies . . . . . . . . . . . . . . . . . . . . . . . 16 91 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 92 6. Security Considerations . . . . . . . . . . . . . . . . . . . 17 93 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 94 7.1. Normative References . . . . . . . . . . . . . . . . . . 17 95 7.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 18 96 Appendix A. Data Supporting Directly Represented Field Mappings 19 97 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 99 1. Introduction 101 HTTP messages often pass through several systems - clients, 102 intermediaries, servers, and subsystems of each - that parse and 103 process their header and trailer fields. This repeated parsing (and 104 often re-serialisation) adds latency and consumes CPU, energy, and 105 other resources. 107 Structured Headers for HTTP [I-D.ietf-httpbis-header-structure] 108 offers a set of data types that new headers can combine to express 109 their semantics. This specification defines a binary serialisation 110 of those structures in Section 2, and specifies its use in HTTP/2 - 111 specifically, as part of HPACK Literal Header Field Representations 112 ([RFC7541]) - in Section 3. 114 Section 4 defines how to use Structured Headers for many existing 115 headers when supported by two peers. 117 The primary goal of this specification are to reduce parsing overhead 118 and associated costs, as compared to the textual representation of 119 Structured Headers. A secondary goal is a more compact wire format 120 in common situations. An additional goal is to enable future work on 121 more granular header compression mechanisms. 123 1.1. Notational Conventions 125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 126 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 127 "OPTIONAL" in this document are to be interpreted as described in BCP 128 14 [RFC2119] [RFC8174] when, and only when, they appear in all 129 capitals, as shown here. 131 2. Binary Structured Headers 133 This section defines a binary serialisation for the Structured Header 134 Types defined in [I-D.ietf-httpbis-header-structure]. 136 The types permissable as the top-level of Structured Header field 137 values - Dictionary, List, and Item - are defined in terms of a 138 Binary Literal Representation (Section 2.1), which is a replacement 139 for the String Literal Representation in [RFC7541]. 141 Binary representations of the remaining types are defined in 142 Section 2.2. 144 2.1. The Binary Literal Representation 146 The Binary Literal Representation is a replacement for the String 147 Literal Representation defined in [RFC7541], Section 5.2, for use in 148 BINHEADERS frames (Section 3.2). 150 0 1 2 3 4 5 6 7 151 +---+---+---+---+---+---+---+---+ 152 | Type (4) | PLength (4+) | 153 +---+---------------------------+ 154 | Payload Data (Length octets) | 155 +-------------------------------+ 157 A binary literal representation contains the following fields: 159 o Type: Four bits indicating the type of the payload. 161 o PLength: The number of octets used to represent the payload, 162 encoded as per [RFC7541], Section 5.1, with a 4-bit prefix. 164 o Payload Data: The payload, as per below. 166 The following payload types are defined: 168 2.1.1. Lists 170 List values (type=0x1) have a payload consisting of a stream of 171 Binary Structured Types representing the members of the list. 172 Members that are Items are represented as per Section 2.2.3; members 173 that are inner-lists are represented as per Section 2.2.1. 175 If any member cannot be represented, the entire field value MUST be 176 serialised as a String Literal (Section 2.1.4). 178 2.1.2. Dictionaries 180 Dictionary values (type=0x2) have a payload consisting of a stream of 181 members. 183 Each member is represented by a key length, followed by that many 184 bytes of the member-name, followed by Binary Structured Types 185 representing the member-value. 187 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 188 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 189 | KL (8+) | member-name (KL octets) 190 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 192 0 1 2 3 4 5 6 7 193 +---+---+---+---+---+---+---+--- 194 | member-value 195 +---+---+---+---+---+---+---+--- 197 A parameter's fields are: 199 o KL: The number of octets used to represent the member-name, 200 encoded as per [RFC7541], Section 5.1, with a 8-bit prefix 202 o member-name: KL octets of the member-name 204 o member-value: One or more Binary Structure Types 206 member-values that are Items are represented as per Section 2.2.3; 207 member-values that are inner-lists are represented as per 208 Section 2.2.1. 210 If any member cannot be represented, the entire field value MUST be 211 serialised as a String Literal (Section 2.1.4). 213 2.1.3. Items 215 Item values (type=0x3) have a payload consisting of Binary Structured 216 Types, as described in Section 2.2.3. 218 2.1.4. String Literals 220 String Literals (type=0x4) are the string value of a header field; 221 they are used to carry header field values that are not Binary 222 Structured Headers, and may not be Structured Headers at all. As 223 such, their semantics are that of String Literal Representations in 224 [RFC7541], Section 5.2. 226 Their payload is the octets of the field value. 228 ISSUE: use Huffman coding? https://github.com/mnot/I-D/issues/305 [5] 230 2.2. Binary Structured Types 232 Every Binary Structured Type starts with a 5-bit type field that 233 identifies the format of its payload: 235 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 236 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 237 Type (5) | Payload... 238 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 240 Some Binary Structured Types contain padding bits; senders MUST set 241 padding bits to 0; recipients MUST ignore their values. 243 2.2.1. Inner Lists 245 The Inner List data type (type=0x1) has a payload in the format: 247 5 6 7 0 1 2 3 4 5 6 7 248 +---+---+---+---+---+---+---+---+---+---+--- 249 L(3+) | Members (L octets) 250 +---+---+---+---+---+---+---+---+---+---+--- 252 Its fields are: 254 o L: The number of octets used to represent the members, encoded as 255 per [RFC7541], Section 5.1, with a 3-bit prefix 257 o Members: L octets 259 Each member of the list will be represented as an Item 260 (Section 2.2.3); if any member cannot, the entire field value will be 261 serialised as a String Literal (Section 2.1.4). 263 The inner list's parameters, if present, are serialised in a 264 following Parameter type (Section 2.2.2); they do not form part of 265 the payload of the inner list. 267 2.2.2. Parameters 269 The Parameters data type (type=0x2) has a payload in the format: 271 5 6 7 0 1 2 3 4 5 6 7 272 +---+---+---+---+---+---+---+---+---+---+--- 273 L(3+) | Parameters (L octets) 274 +---+---+---+---+---+---+---+---+---+---+--- 276 Its fields are: 278 o L: The number of octets used to represent the token, encoded as 279 per [RFC7541], Section 5.1, with a 3-bit prefix 281 o Parameters: L octets 282 Each parameter is represented by key length, followed by that many 283 bytes of the parameter-name, followed by a Binary Structured Type 284 representing the parameter-value. 286 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 287 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 288 | KL (8+) | parameter-name (KL octets) 289 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 291 0 1 2 3 4 5 6 7 292 +---+---+---+---+---+---+---+--- 293 | parameter-value (VL octets) 294 +---+---+---+---+---+---+---+--- 296 A parameter's fields are: 298 o KL: The number of octets used to represent the parameter-name, 299 encoded as per [RFC7541], Section 5.1, with a 8-bit prefix 301 o parameter-name: KL octets of the parameter-name 303 o parameter-value: A Binary Structured type representing a bare item 304 (Section 2.2.3) 306 Parameter-values are bare items; that is, they MUST NOT have 307 parameters themselves. 309 If the parameters cannot be represented, the entire field value will 310 be serialised as a String Literal (Section 2.1.4). 312 Parameters are always associated with the Binary Structured Type that 313 immediately preceded them. If parameters are not explicitly allowed 314 on the preceding type, or there is no preceding type, it is an error. 316 ISSUE: use Huffman coding for parameter-name? 317 https://github.com/mnot/I-D/issues/305 [6] 319 2.2.3. Item Payload Types 321 Individual Structured Header Items can be represented using the 322 Binary Payload Types defined below. 324 The item's parameters, if present, are serialised in a following 325 Parameter type (Section 2.2.2); they do not form part of the payload 326 of the item. 328 2.2.3.1. Integers 330 The Integer data type (type=0x3) has a payload in the format: 332 5 6 7 0 1 2 3 4 5 6 7 333 +---+---+---+---+---+---+---+---+---+---+--- 334 S | Integer (2+) 335 +---+---+---+---+---+---+---+---+---+---+--- 337 Its fields are: 339 o S: sign bit; 0 is negative, 1 is positive 341 o Integer: The integer, encoded as per [RFC7541], Section 5.1, with 342 a 2-bit prefix 344 2.2.3.2. Floats 346 The Float data type (type=0x4) have a payload in the format: 348 5 6 7 0 1 2 3 4 5 6 7 349 +---+---+---+---+---+---+---+---+---+---+--- 350 S | Integer (2+) 351 +---+---+---+---+---+---+---+---+---+---+--- 353 0 1 2 3 4 5 6 7 354 +---+---+---+---+---+---+---+--- 355 | FLength (8+) 356 +---+---+---+---+---+---+---+--- 358 0 1 2 3 4 5 6 7 359 +---+---+---+---+---+---+---+--- 360 | Fractional (8+) 361 +---+---+---+---+---+---+---+--- 363 Its fields are: 365 o S: sign bit; 0 is negative, 1 is positive 367 o Integer: The integer component, encoded as per [RFC7541], 368 Section 5.1, with a 2-bit prefix. 370 o Fractional: The fractional component, encoded as per [RFC7541], 371 Section 5.1, with a 8-bit prefix. 373 2.2.3.3. Strings 375 The String data type (type=0x5) has a payload in the format: 377 5 6 7 0 1 2 3 4 5 6 7 378 +---+---+---+---+---+---+---+---+---+---+--- 379 L(3+) | String (L octets) 380 +---+---+---+---+---+---+---+---+---+---+--- 382 Its fields are: 384 o L: The number of octets used to represent the string, encoded as 385 per [RFC7541], Section 5.1, with a 3-bit prefix. 387 o String: L octets. 389 ISSUE: use Huffman coding? https://github.com/mnot/I-D/issues/305 [7] 391 2.2.3.4. Tokens 393 The Token data type (type=0x6) has a payload in the format: 395 5 6 7 0 1 2 3 4 5 6 7 396 +---+---+---+---+---+---+---+---+---+---+--- 397 L(3+) | Token (L octets) 398 +---+---+---+---+---+---+---+---+---+---+--- 400 Its fields are: 402 o L: The number of octets used to represent the token, encoded as 403 per [RFC7541], Section 5.1, with a 3-bit prefix. 405 o Token: L octets. 407 ISSUE: use Huffman coding? https://github.com/mnot/I-D/issues/305 [8] 409 2.2.3.5. Byte Sequences 411 The Byte Sequence data type (type=0x7) has a payload in the format: 413 5 6 7 0 1 2 3 4 5 6 7 414 +---+---+---+---+---+---+---+---+---+---+--- 415 L(3+) | Byte Sequence (L octets) 416 +---+---+---+---+---+---+---+---+---+---+--- 418 Its fields are: 420 o L: The number of octets used to represent the byte sequence, 421 encoded as per [RFC7541], Section 5.1, with a 3-bit prefix. 423 o Byte Sequence: L octets. 425 2.2.3.6. Booleans 427 The Boolean data type (type=0x8) has a payload of two bits: 429 5 6 7 430 +---+---+---+ 431 B | X | 432 +---+---+---+ 434 If B is 0, the value is False; if B is 1, the value is True. X is 435 padding. 437 3. Using Binary Structured Headers in HTTP/2 439 When both peers on a connection support this specification, they can 440 take advantage of that knowledge to serialise headers that they know 441 to be Structured Headers (or compatible with them; see Section 4). 443 Peers advertise and discover this support using a HTTP/2 setting 444 defined in Section 3.1, and convey Binary Structured Headers in a 445 frame type defined in Section 3.2. 447 3.1. Binary Structured Headers Setting 449 Advertising support for Binary Structured Headers is accomplished 450 using a HTTP/2 setting, SETTINGS_BINARY_STRUCTURED_HEADERS (0xTODO). 452 Receiving SETTINGS_BINARY_STRUCTURED_HEADERS from a peer indicates 453 that: 455 1. The peer supports the Binary Structured Types defined in 456 Section 2. 458 2. The peer will process the BINHEADERS frames as defined in 459 Section 3.2. 461 3. When a downstream consumer does not likewise support that 462 encoding, the peer will transform them into HEADERS frames (if 463 the peer is HTTP/2) or a form it will understand (e.g., the 464 textual representation of Structured Headers data types defined 465 in [I-D.ietf-httpbis-header-structure]). 467 4. The peer will likewise transform all fields defined as Aliased 468 Fields (Section 4.2) into their non-aliased forms as necessary. 470 The default value of SETTINGS_BINARY_STRUCTURED_HEADERS is 0. Future 471 extensions to Structured Headers might use it to indicate support for 472 new types. 474 3.2. The BINHEADERS Frame 476 When a peer has indicated that it supports this specification 477 {#setting}, a sender can send the BINHEADERS Frame Type (0xTODO). 479 The BINHEADERS Frame Type behaves and is represented exactly as a 480 HEADERS Frame type ([RFC7540], Section 6.2), with one exception; 481 instead of using the String Literal Representation defined in 482 [RFC7541], Section 5.2, it uses the Binary Literal Representation 483 defined in Section 2.1. 485 Fields that are Structured Headers can have their values represented 486 using the Binary Literal Representation corresponding to that 487 header's top-level type - List, Dictionary, or Item; their values 488 will then be serialised as a stream of Binary Structured Types. 490 Additionally, any field (including those defined as Structured 491 Headers) can be serialised as a String Literal (Section 2.1.4), which 492 accommodates headers that are not defined as Structured Headers, not 493 valid Structured Headers, or that the sending implementation does not 494 wish to send as Binary Structured Types for some other reason. 496 Note that Field Names are always serialised as String Literals 497 (Section 2.1.4). 499 This means that a BINHEADERS frame can be converted to a HEADERS 500 frame by converting the field values to the string representations of 501 the various Structured Headers Types, and String Literals 502 (Section 2.1.4) to their string counterparts. 504 Conversely, a HEADERS frame can be converted to a BINHEADERS frame by 505 encoding all of the Literal field values as Binary Structured Types. 506 In this case, the header types used are informed by the 507 implementations knowledge of the individual header field semantics; 508 see Section 4. Those which it cannot (do to either lack of knowledge 509 or an error) or does not wish to convert into Structured Headers are 510 conveyed in BINHEADERS as String Literals (Section 2.1.4). 512 Field values are stored in the HPACK [RFC7541] dynamic table without 513 Huffman encoding, although specific Binary Structured Types might 514 specify the use of such encodings. 516 Note that BINHEADERS and HEADERS frames MAY be mixed on the same 517 connection, depending on the requirements of the sender. Also, note 518 that only the field values are encoded as Binary Structured Types; 519 field names are encoded as they are in HPACK. 521 4. Using Binary Structured Headers with Existing Fields 523 Any header field can potentially be parsed as a Structured Header 524 according to the algorithms in [I-D.ietf-httpbis-header-structure] 525 and serialised as a Binary Structured Header. However, many cannot, 526 so optimistically parsing them can be expensive. 528 This section identifies fields that will usually succeed in 529 Section 4.1, and those that can be mapped into Structured Headers by 530 using an alias field name in Section 4.2. 532 4.1. Directly Represented Fields 534 The following HTTP field names can have their values parsed as 535 Structured Headers according to the algorithms in 536 [I-D.ietf-httpbis-header-structure], and thus can usually be 537 serialised using the corresponding Binary Structured Types. 539 When one of these fields' values cannot be represented using 540 Structured Types, its value can instead be represented as a String 541 Literal (Section 2.1.4). 543 o Accept - List 545 o Accept-Encoding - List 547 o Accept-Language - List 549 o Accept-Patch - List 551 o Accept-Ranges - List 553 o Access-Control-Allow-Credentials - Item 555 o Access-Control-Allow-Headers - List 557 o Access-Control-Allow-Methods - List 559 o Access-Control-Allow-Origin - Item 561 o Access-Control-Max-Age - Item 563 o Access-Control-Request-Headers - List 564 o Access-Control-Request-Method - Item 566 o Age - Item 568 o Allow - List 570 o ALPN - List 572 o Alt-Svc - Dictionary 574 o Alt-Used - Item 576 o Cache-Control - Dictionary 578 o Connection - List 580 o Content-Encoding - Item 582 o Content-Language - List 584 o Content-Length - Item 586 o Content-Type - Item 588 o Expect - Item 590 o Expect-CT - Dictionary 592 o Forwarded - Dictionary 594 o Host - Item 596 o Keep-Alive - Dictionary 598 o Origin - Item 600 o Pragma - Dictionary 602 o Prefer - Dictionary 604 o Preference-Applied - Dictionary 606 o Retry-After - Item (see caveat below) 608 o Surrogate-Control - Dictionary 610 o TE - List 611 o Trailer - List 613 o Transfer-Encoding - List 615 o Vary - List 617 o X-Content-Type-Options - Item 619 o X-XSS-Protection - List 621 Note that only the delta-seconds form of Retry-After is supported; a 622 Retry-After value containing a http-date will need to be either 623 converted into delta-seconds or serialised as a String Literal 624 (Section 2.1.4). 626 4.2. Aliased Fields 628 The following HTTP field names can have their values represented in 629 Structured headers by mapping them into its data types and then 630 serialising the resulting Structured Header using an alternative 631 field name. 633 For example, the Date HTTP header field carries a http-date, which is 634 a string representing a date: 636 Date: Sun, 06 Nov 1994 08:49:37 GMT 638 Its value is more efficiently represented as an integer number of 639 delta seconds from the Unix epoch (00:00:00 UTC on 1 January 1970, 640 minus leap seconds). Thus, the example above would be represented in 641 (non-binary) Structured headers as: 643 SH-Date: 784072177 645 As with directly represented fields, if the intended value of an 646 aliased field cannot be represented using Structured Types 647 successfully, its value can instead be represented as a String 648 Literal (Section 2.1.4). 650 Note that senders MUST know that the next-hop recipient understands 651 these fields (typically, using the negotiation mechanism defined in 652 Section 3) before using them. Likewise, recipients MUST transform 653 them back to their unaliased form before forwarding the message to a 654 peer or other consuming components that do not have this capability. 656 Each field name listed below indicates a replacement field name and a 657 way to map its value to Structured Headers. 659 ISSUE: using separate names assures that the different syntax doesn't 660 "leak" into normal headers, but it isn't strictly necessary if 661 implementations always convert back to the correct form when giving 662 it to peers or consuming software that doesn't understand this. 663 https://github.com/mnot/I-D/issues/307 [9] 665 4.2.1. URLs 667 The following field names (paired with their replacement field names) 668 have values that can be represented in Binary Structured Headers by 669 considering their payload a string. 671 o Content-Location - SH-Content-Location 673 o Location - SH-Location 675 o Referer - SH-Referer 677 For example, a (non-binary) Location: 679 SH-Location: "https://example.com/foo" 681 TOOD: list of strings, one for each path segment, to allow better 682 compression in the future? 684 4.2.2. Dates 686 The following field names (paired with their replacement field names) 687 have values that can be represented in Binary Structured Headers by 688 parsing their payload according to [RFC7230], Section 7.1.1.1, and 689 representing the result as an integer number of seconds delta from 690 the Unix Epoch (00:00:00 UTC on 1 January 1970, minus leap seconds). 692 o Date - SH-Date 694 o Expires - SH-Expires 696 o If-Modified-Since - SH-IMS 698 o If-Unmodified-Since - SH-IUS 700 o Last-Modified - SH-LM 702 For example, a (non-binary) Expires: 704 SH-Expires: 1571965240 706 4.2.3. ETags 708 The following field names (paired with their replacement field names) 709 have values that can be represented in Binary Structured Headers by 710 representing the entity-tag as a string, and the weakness flag as a 711 boolean "w" parameter on it, where true indicates that the entity-tag 712 is weak; if 0 or unset, the entity-tag is strong. 714 o ETag - SH-ETag 716 For example, a (non-Binary) ETag: 718 SH-ETag: "abcdef"; w=?1 720 If-None-Match is a list of the structure described above. 722 o If-None-Match - SH-INM 724 For example, a (non-binary) If-None-Match: 726 SH-INM: "abcdef"; w=?1, "ghijkl" 728 4.2.4. Links 730 The field-value of the Link header field [RFC8288] can be represented 731 in Binary Structured Headers by representing the URI-Reference as a 732 string, and link-param as parameters. 734 o Link: SH-Link 736 For example, a (non-binary) Link: 738 SH-Link: "/terms"; rel="copyright"; anchor="#foo" 740 4.2.5. Cookies 742 The field-value of the Cookie and Set-Cookie fields [RFC6265] can be 743 represented in Binary Structured Headers as a List with parameters 744 and a Dictionary, respectively. The serialisation is almost 745 identical, except that the Expires parameter is always a string (as 746 it can contain a comma), multiple cookie-strings can appear in Set- 747 Cookie, and cookie-pairs are delimited in Cookie by a comma, rather 748 than a semicolon. 750 Set-Cookie: SH-Set-Cookie Cookie: SH-Cookie 752 SH-Set-Cookie: lang=en-US, Expires="Wed, 09 Jun 2021 10:18:14 GMT" 753 SH-Cookie: SID=31d4d96e407aad42, lang=en-US 754 ISSUE: explicitly convert Expires to an integer? 755 https://github.com/mnot/I-D/issues/308 [10] ISSUE: dictionary keys 756 cannot contain UC alpha. https://github.com/mnot/I-D/issues/312 [11] 757 ISSUE: explicitly allow non-string content. https://github.com/mnot/ 758 I-D/issues/313 [12] 760 5. IANA Considerations 762 ISSUE: todo 764 6. Security Considerations 766 As is so often the case, having alternative representations of data 767 brings the potential for security weaknesses, when attackers exploit 768 the differences between those representations and their handling. 770 One mitigation to this risk is the strictness of parsing for both 771 non-binary and binary Structured Headers data types, along with the 772 "escape valve" of String Literals (Section 2.1.4). Therefore, 773 implementation divergence from this strictness can have security 774 impact. 776 7. References 778 7.1. Normative References 780 [I-D.ietf-httpbis-header-structure] 781 Nottingham, M. and P. Kamp, "Structured Headers for HTTP", 782 draft-ietf-httpbis-header-structure-14 (work in progress), 783 October 2019. 785 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 786 Requirement Levels", BCP 14, RFC 2119, 787 DOI 10.17487/RFC2119, March 1997, 788 . 790 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 791 DOI 10.17487/RFC6265, April 2011, 792 . 794 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 795 Protocol (HTTP/1.1): Message Syntax and Routing", 796 RFC 7230, DOI 10.17487/RFC7230, June 2014, 797 . 799 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 800 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 801 DOI 10.17487/RFC7540, May 2015, 802 . 804 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 805 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 806 . 808 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 809 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 810 May 2017, . 812 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 813 DOI 10.17487/RFC8288, October 2017, 814 . 816 7.2. URIs 818 [1] https://github.com/mnot/I-D/labels/binary-structured-headers 820 [2] https://mnot.github.io/I-D/binary-structured-headers/ 822 [3] https://github.com/mnot/I-D/commits/gh-pages/binary-structured- 823 headers 825 [4] https://datatracker.ietf.org/doc/draft-nottingham-binary- 826 structured-headers/ 828 [5] https://github.com/mnot/I-D/issues/305 830 [6] https://github.com/mnot/I-D/issues/305 832 [7] https://github.com/mnot/I-D/issues/305 834 [8] https://github.com/mnot/I-D/issues/305 836 [9] https://github.com/mnot/I-D/issues/307 838 [10] https://github.com/mnot/I-D/issues/308 840 [11] https://github.com/mnot/I-D/issues/312 842 [12] https://github.com/mnot/I-D/issues/313 844 [13] https://httparchive.org 846 [14] https://discuss.httparchive.org/t/working-with-csv-dumps/1835 848 Appendix A. Data Supporting Directly Represented Field Mappings 850 _RFC EDITOR: please remove this section before publication_ 852 To help guide decisions about Directly Represented Fields, the HTTP 853 response headers captured by the HTTP Archive https://httparchive.org 854 [13], representing more than 400,000,000 HTTP exchanges, were parsed 855 as Structured Headers using the types listed in Section 4.1, with the 856 indicated number of successful header instances, failures, and the 857 resulting failure rate: 859 o accept: 10060 / 8 = 0% 861 o accept-encoding: 37322 / 4 = 0% 863 o accept-language: 216051 / 199 = 0% 865 o accept-patch: 3 / 0 = 0% 867 o accept-ranges: 277520850 / 240940 = 0% 869 o access-control-allow-credentials: 17305094 / 16503 = 0% 871 o access-control-allow-headers: 10829889 / 19028 = 0% 873 o access-control-allow-methods: 15706123 / 12994 = 0% 875 o access-control-allow-origin: 79694513 / 209447 = 0% 877 o access-control-max-age: 5166126 / 9236 = 0% 879 o access-control-request-headers: 48937 / 532 = 1% 881 o access-control-request-method: 151702 / 12859 = 7% 883 o age: 222024968 / 417140 = 0% 885 o allow: 398227 / 567 = 0% 887 o alt-svc: 26793600 / 1779280 = 6% 889 o cache-control: 373807306 / 4119381 = 1% 891 o connection: 188382722 / 244317 = 0% 893 o content-encoding: 301904345 / 23368 = 0% 895 o content-language: 152252635 / 81760 = 0% 896 o content-length: 367973320 / 209032 = 0% 898 o content-type: 398500045 / 432427 = 0% 900 o expect: 0 / 1 = 100% 902 o expect-ct: 26129601 / 30226 = 0% 904 o forwarded: 23 / 59 = 71% 906 o host: 23003 / 781 = 3% 908 o keep-alive: 2 / 0 = 0% 910 o origin: 27921 / 1677 = 5% 912 o pragma: 219160866 / 890328 = 0% 914 o preference-applied: 2 / 59 = 96% 916 o retry-after: 680494 / 2832 = 0% 918 o surrogate-control: 156370 / 736 = 0% 920 o trailer: 1 / 0 = 0% 922 o transfer-encoding: 127553768 / 458 = 0% 924 o vary: 310245980 / 866776 = 0% 926 o x-content-type-options: 94309348 / 608045 = 0% 928 o x-xss-protection: 72910239 / 348566 = 0% 930 This data set focuses on response headers, although some request 931 headers are present (because, the Web). 933 Some failure rates are slightly raised because of a bug in the input 934 data (see https://discuss.httparchive.org/t/working-with-csv- 935 dumps/1835 [14]). 937 "preference-applied" has a high failure rate because of the occurence 938 of '.' in keys (e.g., "odata.include-annotations") 940 "forwarded" has a high failure rate because many senders use the 941 unquoted form for IP addresses, which makes integer parsing fail; 942 e.g., "for=192.168.1.1" 943 The top ten header fields in that data set that were not parsed as 944 Directly Represented Fields are: 946 o date: 405374834 948 o server: 367671207 950 o expires: 326515189 952 o last-modified: 325777639 954 o etag: 271541372 956 o location: 180398510 958 o via: 179060017 960 o x-powered-by: 178075863 962 o status: 169014311 964 o content-location: 126069665 966 Author's Address 968 Mark Nottingham 969 Fastly 971 Email: mnot@mnot.net 972 URI: https://www.mnot.net/