idnits 2.17.1 draft-nottingham-binary-structured-headers-02.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 (March 4, 2020) is 1514 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 825 -- Looks like a reference, but probably isn't: '2' on line 827 -- Looks like a reference, but probably isn't: '3' on line 829 -- Looks like a reference, but probably isn't: '4' on line 832 -- Looks like a reference, but probably isn't: '5' on line 835 -- Looks like a reference, but probably isn't: '6' on line 837 -- Looks like a reference, but probably isn't: '7' on line 839 -- Looks like a reference, but probably isn't: '8' on line 841 -- Looks like a reference, but probably isn't: '9' on line 843 -- Looks like a reference, but probably isn't: '10' on line 845 -- Looks like a reference, but probably isn't: '11' on line 847 -- Looks like a reference, but probably isn't: '12' on line 849 -- Looks like a reference, but probably isn't: '13' on line 859 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-header-structure-15 ** 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 (==), 14 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 March 4, 2020 5 Expires: September 5, 2020 7 Binary Structured HTTP Headers 8 draft-nottingham-binary-structured-headers-02 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 September 5, 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 . . . . . . . . . . . . . . . . . 6 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 o ISSUE: use Huffman coding? https://github.com/mnot/I-D/issues/305 229 [5] 231 2.2. Binary Structured Types 233 Every Binary Structured Type starts with a 5-bit type field that 234 identifies the format of its payload: 236 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 237 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 238 Type (5) | Payload... 239 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 241 Some Binary Structured Types contain padding bits; senders MUST set 242 padding bits to 0; recipients MUST ignore their values. 244 2.2.1. Inner Lists 246 The Inner List data type (type=0x1) has a payload in the format: 248 5 6 7 0 1 2 3 4 5 6 7 249 +---+---+---+---+---+---+---+---+---+---+--- 250 L(3+) | Members (L octets) 251 +---+---+---+---+---+---+---+---+---+---+--- 253 Its fields are: 255 o L: The number of octets used to represent the members, encoded as 256 per [RFC7541], Section 5.1, with a 3-bit prefix 258 o Members: L octets 260 Each member of the list will be represented as an Item 261 (Section 2.2.3); if any member cannot, the entire field value will be 262 serialised as a String Literal (Section 2.1.4). 264 The inner list's parameters, if present, are serialised in a 265 following Parameter type (Section 2.2.2); they do not form part of 266 the payload of the inner list. 268 2.2.2. Parameters 270 The Parameters data type (type=0x2) has a payload in the format: 272 5 6 7 0 1 2 3 4 5 6 7 273 +---+---+---+---+---+---+---+---+---+---+--- 274 L(3+) | Parameters (L octets) 275 +---+---+---+---+---+---+---+---+---+---+--- 277 Its fields are: 279 o L: The number of octets used to represent the token, encoded as 280 per [RFC7541], Section 5.1, with a 3-bit prefix 282 o Parameters: L octets 284 Each parameter is represented by key length, followed by that many 285 bytes of the parameter-name, followed by a Binary Structured Type 286 representing the parameter-value. 288 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 289 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 290 | KL (8+) | parameter-name (KL octets) 291 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 293 0 1 2 3 4 5 6 7 294 +---+---+---+---+---+---+---+--- 295 | parameter-value (VL octets) 296 +---+---+---+---+---+---+---+--- 298 A parameter's fields are: 300 o KL: The number of octets used to represent the parameter-name, 301 encoded as per [RFC7541], Section 5.1, with a 8-bit prefix 303 o parameter-name: KL octets of the parameter-name 305 o parameter-value: A Binary Structured type representing a bare item 306 (Section 2.2.3) 308 Parameter-values are bare items; that is, they MUST NOT have 309 parameters themselves. 311 If the parameters cannot be represented, the entire field value will 312 be serialised as a String Literal (Section 2.1.4). 314 Parameters are always associated with the Binary Structured Type that 315 immediately preceded them. If parameters are not explicitly allowed 316 on the preceding type, or there is no preceding type, it is an error. 318 o ISSUE: use Huffman coding for parameter-name? 319 https://github.com/mnot/I-D/issues/305 [6] 321 2.2.3. Item Payload Types 323 Individual Structured Header Items can be represented using the 324 Binary Payload Types defined below. 326 The item's parameters, if present, are serialised in a following 327 Parameter type (Section 2.2.2); they do not form part of the payload 328 of the item. 330 2.2.3.1. Integers 332 The Integer data type (type=0x3) has a payload in the format: 334 5 6 7 0 1 2 3 4 5 6 7 335 +---+---+---+---+---+---+---+---+---+---+--- 336 S | Integer (2+) 337 +---+---+---+---+---+---+---+---+---+---+--- 339 Its fields are: 341 o S: sign bit; 0 is negative, 1 is positive 343 o Integer: The integer, encoded as per [RFC7541], Section 5.1, with 344 a 2-bit prefix 346 2.2.3.2. Floats 348 The Float data type (type=0x4) have a payload in the format: 350 5 6 7 0 1 2 3 4 5 6 7 351 +---+---+---+---+---+---+---+---+---+---+--- 352 S | Integer (2+) 353 +---+---+---+---+---+---+---+---+---+---+--- 355 0 1 2 3 4 5 6 7 356 +---+---+---+---+---+---+---+--- 357 | FLength (8+) 358 +---+---+---+---+---+---+---+--- 360 0 1 2 3 4 5 6 7 361 +---+---+---+---+---+---+---+--- 362 | Fractional (8+) 363 +---+---+---+---+---+---+---+--- 365 Its fields are: 367 o S: sign bit; 0 is negative, 1 is positive 369 o Integer: The integer component, encoded as per [RFC7541], 370 Section 5.1, with a 2-bit prefix. 372 o Fractional: The fractional component, encoded as per [RFC7541], 373 Section 5.1, with a 8-bit prefix. 375 2.2.3.3. Strings 377 The String data type (type=0x5) has a payload in the format: 379 5 6 7 0 1 2 3 4 5 6 7 380 +---+---+---+---+---+---+---+---+---+---+--- 381 L(3+) | String (L octets) 382 +---+---+---+---+---+---+---+---+---+---+--- 384 Its fields are: 386 o L: The number of octets used to represent the string, encoded as 387 per [RFC7541], Section 5.1, with a 3-bit prefix. 389 o String: L octets. 391 o ISSUE: use Huffman coding? https://github.com/mnot/I-D/issues/305 392 [7] 394 2.2.3.4. Tokens 396 The Token data type (type=0x6) has a payload in the format: 398 5 6 7 0 1 2 3 4 5 6 7 399 +---+---+---+---+---+---+---+---+---+---+--- 400 L(3+) | Token (L octets) 401 +---+---+---+---+---+---+---+---+---+---+--- 403 Its fields are: 405 o L: The number of octets used to represent the token, encoded as 406 per [RFC7541], Section 5.1, with a 3-bit prefix. 408 o Token: L octets. 410 o ISSUE: use Huffman coding? https://github.com/mnot/I-D/issues/305 411 [8] 413 2.2.3.5. Byte Sequences 415 The Byte Sequence data type (type=0x7) has a payload in the format: 417 5 6 7 0 1 2 3 4 5 6 7 418 +---+---+---+---+---+---+---+---+---+---+--- 419 L(3+) | Byte Sequence (L octets) 420 +---+---+---+---+---+---+---+---+---+---+--- 422 Its fields are: 424 o L: The number of octets used to represent the byte sequence, 425 encoded as per [RFC7541], Section 5.1, with a 3-bit prefix. 427 o Byte Sequence: L octets. 429 2.2.3.6. Booleans 431 The Boolean data type (type=0x8) has a payload of two bits: 433 5 6 7 434 +---+---+---+ 435 B | X | 436 +---+---+---+ 438 If B is 0, the value is False; if B is 1, the value is True. X is 439 padding. 441 3. Using Binary Structured Headers in HTTP/2 443 When both peers on a connection support this specification, they can 444 take advantage of that knowledge to serialise headers that they know 445 to be Structured Headers (or compatible with them; see Section 4). 447 Peers advertise and discover this support using a HTTP/2 setting 448 defined in Section 3.1, and convey Binary Structured Headers in a 449 frame type defined in Section 3.2. 451 3.1. Binary Structured Headers Setting 453 Advertising support for Binary Structured Headers is accomplished 454 using a HTTP/2 setting, SETTINGS_BINARY_STRUCTURED_HEADERS (0xTODO). 456 Receiving SETTINGS_BINARY_STRUCTURED_HEADERS from a peer indicates 457 that: 459 1. The peer supports the Binary Structured Types defined in 460 Section 2. 462 2. The peer will process the BINHEADERS frames as defined in 463 Section 3.2. 465 3. When a downstream consumer does not likewise support that 466 encoding, the peer will transform them into HEADERS frames (if 467 the peer is HTTP/2) or a form it will understand (e.g., the 468 textual representation of Structured Headers data types defined 469 in [I-D.ietf-httpbis-header-structure]). 471 4. The peer will likewise transform all fields defined as Aliased 472 Fields (Section 4.2) into their non-aliased forms as necessary. 474 The default value of SETTINGS_BINARY_STRUCTURED_HEADERS is 0. Future 475 extensions to Structured Headers might use it to indicate support for 476 new types. 478 3.2. The BINHEADERS Frame 480 When a peer has indicated that it supports this specification 481 {#setting}, a sender can send the BINHEADERS Frame Type (0xTODO). 483 The BINHEADERS Frame Type behaves and is represented exactly as a 484 HEADERS Frame type ([RFC7540], Section 6.2), with one exception; 485 instead of using the String Literal Representation defined in 486 [RFC7541], Section 5.2, it uses the Binary Literal Representation 487 defined in Section 2.1. 489 Fields that are Structured Headers can have their values represented 490 using the Binary Literal Representation corresponding to that 491 header's top-level type - List, Dictionary, or Item; their values 492 will then be serialised as a stream of Binary Structured Types. 494 Additionally, any field (including those defined as Structured 495 Headers) can be serialised as a String Literal (Section 2.1.4), which 496 accommodates headers that are not defined as Structured Headers, not 497 valid Structured Headers, or that the sending implementation does not 498 wish to send as Binary Structured Types for some other reason. 500 Note that Field Names are always serialised as String Literals 501 (Section 2.1.4). 503 This means that a BINHEADERS frame can be converted to a HEADERS 504 frame by converting the field values to the string representations of 505 the various Structured Headers Types, and String Literals 506 (Section 2.1.4) to their string counterparts. 508 Conversely, a HEADERS frame can be converted to a BINHEADERS frame by 509 encoding all of the Literal field values as Binary Structured Types. 510 In this case, the header types used are informed by the 511 implementations knowledge of the individual header field semantics; 512 see Section 4. Those which it cannot (do to either lack of knowledge 513 or an error) or does not wish to convert into Structured Headers are 514 conveyed in BINHEADERS as String Literals (Section 2.1.4). 516 Field values are stored in the HPACK [RFC7541] dynamic table without 517 Huffman encoding, although specific Binary Structured Types might 518 specify the use of such encodings. 520 Note that BINHEADERS and HEADERS frames MAY be mixed on the same 521 connection, depending on the requirements of the sender. Also, note 522 that only the field values are encoded as Binary Structured Types; 523 field names are encoded as they are in HPACK. 525 4. Using Binary Structured Headers with Existing Fields 527 Any header field can potentially be parsed as a Structured Header 528 according to the algorithms in [I-D.ietf-httpbis-header-structure] 529 and serialised as a Binary Structured Header. However, many cannot, 530 so optimistically parsing them can be expensive. 532 This section identifies fields that will usually succeed in 533 Section 4.1, and those that can be mapped into Structured Headers by 534 using an alias field name in Section 4.2. 536 4.1. Directly Represented Fields 538 The following HTTP field names can have their values parsed as 539 Structured Headers according to the algorithms in 540 [I-D.ietf-httpbis-header-structure], and thus can usually be 541 serialised using the corresponding Binary Structured Types. 543 When one of these fields' values cannot be represented using 544 Structured Types, its value can instead be represented as a String 545 Literal (Section 2.1.4). 547 o Accept - List 549 o Accept-Encoding - List 551 o Accept-Language - List 553 o Accept-Patch - List 555 o Accept-Ranges - List 557 o Access-Control-Allow-Credentials - Item 559 o Access-Control-Allow-Headers - List 561 o Access-Control-Allow-Methods - List 563 o Access-Control-Allow-Origin - Item 565 o Access-Control-Max-Age - Item 567 o Access-Control-Request-Headers - List 568 o Access-Control-Request-Method - Item 570 o Age - Item 572 o Allow - List 574 o ALPN - List 576 o Alt-Svc - Dictionary 578 o Alt-Used - Item 580 o Cache-Control - Dictionary 582 o Connection - List 584 o Content-Encoding - List 586 o Content-Language - List 588 o Content-Length - Item 590 o Content-Type - Item 592 o Expect - Item 594 o Expect-CT - Dictionary 596 o Forwarded - Dictionary 598 o Host - Item 600 o Keep-Alive - Dictionary 602 o Origin - Item 604 o Pragma - Dictionary 606 o Prefer - Dictionary 608 o Preference-Applied - Dictionary 610 o Retry-After - Item (see caveat below) 612 o Surrogate-Control - Dictionary 614 o TE - List 615 o Trailer - List 617 o Transfer-Encoding - List 619 o Vary - List 621 o X-Content-Type-Options - Item 623 o X-XSS-Protection - List 625 Note that only the delta-seconds form of Retry-After is supported; a 626 Retry-After value containing a http-date will need to be either 627 converted into delta-seconds or serialised as a String Literal 628 (Section 2.1.4). 630 4.2. Aliased Fields 632 The following HTTP field names can have their values represented in 633 Structured headers by mapping them into its data types and then 634 serialising the resulting Structured Header using an alternative 635 field name. 637 For example, the Date HTTP header field carries a http-date, which is 638 a string representing a date: 640 Date: Sun, 06 Nov 1994 08:49:37 GMT 642 Its value is more efficiently represented as an integer number of 643 delta seconds from the Unix epoch (00:00:00 UTC on 1 January 1970, 644 minus leap seconds). Thus, the example above would be represented in 645 (non-binary) Structured headers as: 647 SH-Date: 784072177 649 As with directly represented fields, if the intended value of an 650 aliased field cannot be represented using Structured Types 651 successfully, its value can instead be represented as a String 652 Literal (Section 2.1.4). 654 Note that senders MUST know that the next-hop recipient understands 655 these fields (typically, using the negotiation mechanism defined in 656 Section 3) before using them. Likewise, recipients MUST transform 657 them back to their unaliased form before forwarding the message to a 658 peer or other consuming components that do not have this capability. 660 Each field name listed below indicates a replacement field name and a 661 way to map its value to Structured Headers. 663 o ISSUE: using separate names assures that the different syntax 664 doesn't "leak" into normal headers, but it isn't strictly 665 necessary if implementations always convert back to the correct 666 form when giving it to peers or consuming software that doesn't 667 understand this. https://github.com/mnot/I-D/issues/307 [9] 669 4.2.1. URLs 671 The following field names (paired with their replacement field names) 672 have values that can be represented in Binary Structured Headers by 673 considering their payload a string. 675 o Content-Location - SH-Content-Location 677 o Location - SH-Location 679 o Referer - SH-Referer 681 For example, a (non-binary) Location: 683 SH-Location: "https://example.com/foo" 685 TOOD: list of strings, one for each path segment, to allow better 686 compression in the future? 688 4.2.2. Dates 690 The following field names (paired with their replacement field names) 691 have values that can be represented in Binary Structured Headers by 692 parsing their payload according to [RFC7230], Section 7.1.1.1, and 693 representing the result as an integer number of seconds delta from 694 the Unix Epoch (00:00:00 UTC on 1 January 1970, minus leap seconds). 696 o Date - SH-Date 698 o Expires - SH-Expires 700 o If-Modified-Since - SH-IMS 702 o If-Unmodified-Since - SH-IUS 704 o Last-Modified - SH-LM 706 For example, a (non-binary) Expires: 708 SH-Expires: 1571965240 710 4.2.3. ETags 712 The following field names (paired with their replacement field names) 713 have values that can be represented in Binary Structured Headers by 714 representing the entity-tag as a string, and the weakness flag as a 715 boolean "w" parameter on it, where true indicates that the entity-tag 716 is weak; if 0 or unset, the entity-tag is strong. 718 o ETag - SH-ETag 720 For example, a (non-Binary) ETag: 722 SH-ETag: "abcdef"; w=?1 724 If-None-Match is a list of the structure described above. 726 o If-None-Match - SH-INM 728 For example, a (non-binary) If-None-Match: 730 SH-INM: "abcdef"; w=?1, "ghijkl" 732 4.2.4. Links 734 The field-value of the Link header field [RFC8288] can be represented 735 in Binary Structured Headers by representing the URI-Reference as a 736 string, and link-param as parameters. 738 o Link: SH-Link 740 For example, a (non-binary) Link: 742 SH-Link: "/terms"; rel="copyright"; anchor="#foo" 744 4.2.5. Cookies 746 The field-value of the Cookie and Set-Cookie fields [RFC6265] can be 747 represented in Binary Structured Headers as a List with parameters 748 and a Dictionary, respectively. The serialisation is almost 749 identical, except that the Expires parameter is always a string (as 750 it can contain a comma), multiple cookie-strings can appear in Set- 751 Cookie, and cookie-pairs are delimited in Cookie by a comma, rather 752 than a semicolon. 754 Set-Cookie: SH-Set-Cookie Cookie: SH-Cookie 756 SH-Set-Cookie: lang=en-US, Expires="Wed, 09 Jun 2021 10:18:14 GMT" 757 SH-Cookie: SID=31d4d96e407aad42, lang=en-US 758 o ISSUE: explicitly convert Expires to an integer? 759 https://github.com/mnot/I-D/issues/308 [10] 761 o ISSUE: dictionary keys cannot contain UC alpha. 762 https://github.com/mnot/I-D/issues/312 [11] 764 o ISSUE: explicitly allow non-string content. 765 https://github.com/mnot/I-D/issues/313 [12] 767 5. IANA Considerations 769 o ISSUE: todo 771 6. Security Considerations 773 As is so often the case, having alternative representations of data 774 brings the potential for security weaknesses, when attackers exploit 775 the differences between those representations and their handling. 777 One mitigation to this risk is the strictness of parsing for both 778 non-binary and binary Structured Headers data types, along with the 779 "escape valve" of String Literals (Section 2.1.4). Therefore, 780 implementation divergence from this strictness can have security 781 impact. 783 7. References 785 7.1. Normative References 787 [I-D.ietf-httpbis-header-structure] 788 Nottingham, M. and P. Kamp, "Structured Headers for HTTP", 789 draft-ietf-httpbis-header-structure-15 (work in progress), 790 January 2020. 792 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 793 Requirement Levels", BCP 14, RFC 2119, 794 DOI 10.17487/RFC2119, March 1997, 795 . 797 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 798 DOI 10.17487/RFC6265, April 2011, 799 . 801 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 802 Protocol (HTTP/1.1): Message Syntax and Routing", 803 RFC 7230, DOI 10.17487/RFC7230, June 2014, 804 . 806 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 807 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 808 DOI 10.17487/RFC7540, May 2015, 809 . 811 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 812 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 813 . 815 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 816 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 817 May 2017, . 819 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 820 DOI 10.17487/RFC8288, October 2017, 821 . 823 7.2. URIs 825 [1] https://github.com/mnot/I-D/labels/binary-structured-headers 827 [2] https://mnot.github.io/I-D/binary-structured-headers/ 829 [3] https://github.com/mnot/I-D/commits/gh-pages/binary-structured- 830 headers 832 [4] https://datatracker.ietf.org/doc/draft-nottingham-binary- 833 structured-headers/ 835 [5] https://github.com/mnot/I-D/issues/305 837 [6] https://github.com/mnot/I-D/issues/305 839 [7] https://github.com/mnot/I-D/issues/305 841 [8] https://github.com/mnot/I-D/issues/305 843 [9] https://github.com/mnot/I-D/issues/307 845 [10] https://github.com/mnot/I-D/issues/308 847 [11] https://github.com/mnot/I-D/issues/312 849 [12] https://github.com/mnot/I-D/issues/313 851 [13] https://httparchive.org 853 Appendix A. Data Supporting Directly Represented Field Mappings 855 _RFC EDITOR: please remove this section before publication_ 857 To help guide decisions about Directly Represented Fields, the HTTP 858 response headers captured by the HTTP Archive https://httparchive.org 859 [13] in February 2020, representing more than 350,000,000 HTTP 860 exchanges, were parsed as Structured Headers using the types listed 861 in Section 4.1, with the indicated number of successful header 862 instances, failures, and the resulting failure rate: 864 o accept: 9,201 / 10 = 0.109% 866 o accept-encoding: 34,158 / 74 = 0.216% 868 o accept-language: 381,037 / 512 = 0.134% 870 o accept-patch: 5 / 0 = 0.000% 872 o accept-ranges: 197,759,320 / 3,960 = 0.002% 874 o access-control-allow-credentials: 16,687,349 / 7,357 = 0.044% 876 o access-control-allow-headers: 12,979,869 / 14,960 = 0.115% 878 o access-control-allow-methods: 15,469,948 / 28,203 = 0.182% 880 o access-control-allow-origin: 105,326,437 / 264,278 = 0.250% 882 o access-control-max-age: 5,287,263 / 7,749 = 0.146% 884 o access-control-request-headers: 39,340 / 624 = 1.561% 886 o access-control-request-method: 146,566 / 13,822 = 8.618% 888 o age: 71,292,543 / 168,572 = 0.236% 890 o allow: 351,707 / 1,886 = 0.533% 892 o alt-svc: 19,777,530 / 15,682,026 = 44.225% 894 o cache-control: 264,666,876 / 946,434 = 0.356% 896 o connection: 105,884,722 / 2,915 = 0.003% 898 o content-encoding: 139,812,089 / 379 = 0.000% 900 o content-language: 2,368,912 / 728 = 0.031% 901 o content-length: 296,649,810 / 787,897 = 0.265% 903 o content-type: 341,948,525 / 794,864 = 0.232% 905 o expect: 0 / 47 = 100.000% 907 o expect-ct: 26,573,905 / 29,117 = 0.109% 909 o forwarded: 119 / 35 = 22.727% 911 o host: 25,335 / 1,441 = 5.382% 913 o keep-alive: 43,063,257 / 796 = 0.002% 915 o origin: 24,336 / 1,539 = 5.948% 917 o pragma: 46,826,446 / 81,707 = 0.174% 919 o preference-applied: 57 / 0 = 0.000% 921 o retry-after: 605,926 / 6,194 = 1.012% 923 o strict-transport-security: 26,826,043 / 35,266,676 = 56.797% 925 o surrogate-control: 121,124 / 861 = 0.706% 927 o te: 1 / 0 = 0.000% 929 o trailer: 282 / 0 = 0.000% 931 o transfer-encoding: 13,953,547 / 0 = 0.000% 933 o vary: 150,802,211 / 41,317 = 0.027% 935 o x-content-type-options: 99,982,040 / 203,824 = 0.203% 937 o x-xss-protection: 79,878,780 / 362,984 = 0.452% 939 This data set focuses on response headers, although some request 940 headers are present (because, the Web). 942 "alt-svc" has a high failure rate because some currently-used ALPN 943 tokens (e.g., "h3-Q43") do not conform to key's syntax. Since the 944 final version of HTTP/3 will use the "h3" token, this shouldn't be a 945 long-term issue, although future tokens may again violate this 946 assumption. 948 "forwarded" has a high failure rate because many senders use the 949 unquoted form for IP addresses, which makes integer parsing fail; 950 e.g., "for=192.168.1.1". 952 "strict-transport-security" has a high failure rate because the 953 "includeSubDomains" flag does not conform to the key syntax. 955 The most common problem causing failure for many other headers is 956 duplicated values; e.g., a Content-Length with "2, 2". 958 The top ten header fields in that data set that were not parsed as 959 Directly Represented Fields are: 961 o date: 354,682,923 963 o server: 311,299,092 965 o last-modified: 263,851,521 967 o expires: 199,985,746 969 o status: 192,439,616 971 o etag: 172,071,630 973 o timing-allow-origin: 64,413,748 975 o x-cache: 41,743,978 977 o p3p: 39,495,307 979 o x-frame-options: 34,041,316 981 Author's Address 983 Mark Nottingham 984 Fastly 986 Email: mnot@mnot.net 987 URI: https://www.mnot.net/