idnits 2.17.00 (12 Aug 2021) /tmp/idnits44416/draft-nottingham-binary-structured-headers-00.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 (November 1, 2019) is 931 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 827 -- Looks like a reference, but probably isn't: '2' on line 829 -- Looks like a reference, but probably isn't: '3' on line 831 -- Looks like a reference, but probably isn't: '4' on line 834 -- Looks like a reference, but probably isn't: '5' on line 837 -- Looks like a reference, but probably isn't: '6' on line 839 -- Looks like a reference, but probably isn't: '7' on line 841 -- Looks like a reference, but probably isn't: '8' on line 843 -- Looks like a reference, but probably isn't: '9' on line 845 -- Looks like a reference, but probably isn't: '10' on line 847 == Outdated reference: draft-ietf-httpbis-header-structure has been published as RFC 8941 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 11 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 November 1, 2019 5 Expires: May 4, 2020 7 Binary Structured HTTP Headers 8 draft-nottingham-binary-structured-headers-00 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 May 4, 2020. 51 Copyright Notice 53 Copyright (c) 2019 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 . . . . . . . . . . . . 11 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 . . . . . . . . . . . . . . . . . . . . . . . 17 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 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19 98 1. Introduction 100 HTTP messages often pass through several systems - clients, 101 intermediaries, servers, and subsystems of each - that parse and 102 process their header and trailer fields. This repeated parsing (and 103 often re-serialisation) adds latency and consumes CPU, energy, and 104 other resources. 106 Structured Headers for HTTP [I-D.ietf-httpbis-header-structure] 107 offers a set of data types that new headers can combine to express 108 their semantics. This specification defines a binary serialisation 109 of those structures in Section 2, and specifies its use in HTTP/2 - 110 specifically, as part of HPACK Literal Header Field Representations 111 ([RFC7541]) - in Section 3. 113 Section 4 defines how to use Structured Headers for many existing 114 headers when supported by two peers. 116 The primary goal of this specification are to reduce parsing overhead 117 and associated costs, as compared to the textual representation of 118 Structured Headers. A secondary goal is a more compact wire format 119 in common situations. An additional goal is to enable future work on 120 more granular header compression mechanisms. 122 1.1. Notational Conventions 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 126 "OPTIONAL" in this document are to be interpreted as described in BCP 127 14 [RFC2119] [RFC8174] when, and only when, they appear in all 128 capitals, as shown here. 130 2. Binary Structured Headers 132 This section defines a binary serialisation for the Structured Header 133 Types defined in [I-D.ietf-httpbis-header-structure]. 135 The types permissable as the top-level of Structured Header field 136 values - Dictionary, List, and Item - are defined in terms of a 137 Binary Literal Representation (Section 2.1), which is a replacement 138 for the String Literal Representation in [RFC7541]. 140 Binary representations of the remaining types are defined in 141 Section 2.2. 143 2.1. The Binary Literal Representation 145 The Binary Literal Representation is a replacement for the String 146 Literal Representation defined in [RFC7541], Section 5.2, for use in 147 BINHEADERS frames (Section 3.2). 149 0 1 2 3 4 5 6 7 150 +---+---+---+---+---+---+---+---+ 151 | Type (4) | PLength (4+) | 152 +---+---------------------------+ 153 | Payload Data (Length octets) | 154 +-------------------------------+ 156 A binary literal representation contains the following fields: 158 o Type: Four bits indicating the type of the payload. 160 o PLength: The number of octets used to represent the payload, 161 encoded as per [RFC7541], Section 5.1, with a 4-bit prefix. 163 o Payload Data: The payload, as per below. 165 The following payload types are defined: 167 2.1.1. Lists 169 List values (type=0x1) have a payload consisting of a stream of 170 Binary Structured Types representing the members of the list. 171 Members that are Items are represented as per Section 2.2.3; members 172 that are inner-lists are represented as per Section 2.2.1. 174 If any member cannot be represented, the entire field value MUST be 175 serialised as a String Literal (Section 2.1.4). 177 2.1.2. Dictionaries 179 Dictionary values (type=0x2) have a payload consisting of a stream of 180 members. 182 Each member is represented by a key length, followed by that many 183 bytes of the member-name, followed by Binary Structured Types 184 representing the member-value. 186 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 187 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 188 | KL (8+) | member-name (KL octets) 189 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 191 0 1 2 3 4 5 6 7 192 +---+---+---+---+---+---+---+--- 193 | member-value 194 +---+---+---+---+---+---+---+--- 196 A parameter's fields are: 198 o KL: The number of octets used to represent the member-name, 199 encoded as per [RFC7541], Section 5.1, with a 8-bit prefix 201 o member-name: KL octets of the member-name 203 o member-value: One or more Binary Structure Types 205 member-values that are Items are represented as per Section 2.2.3; 206 member-values that are inner-lists are represented as per 207 Section 2.2.1. 209 If any member cannot be represented, the entire field value MUST be 210 serialised as a String Literal (Section 2.1.4). 212 2.1.3. Items 214 Item values (type=0x3) have a payload consisting of Binary Structured 215 Types, as described in Section 2.2.3. 217 2.1.4. String Literals 219 String Literals (type=0x4) are the string value of a header field; 220 they are used to carry header field values that are not Binary 221 Structured Headers, and may not be Structured Headers at all. As 222 such, their semantics are that of String Literal Representations in 223 [RFC7541], Section 5.2. 225 Their payload is the octets of the field value. 227 ISSUE: use Huffman coding? https://github.com/mnot/I-D/issues/305 [5] 229 2.2. Binary Structured Types 231 Every Binary Structured Type starts with a 5-bit type field that 232 identifies the format of its payload: 234 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 235 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 236 Type (5) | Payload... 237 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 239 Some Binary Structured Types contain padding bits; senders MUST set 240 padding bits to 0; recipients MUST ignore their values. 242 2.2.1. Inner Lists 244 The Inner List data type (type=0x1) has a payload in the format: 246 5 6 7 0 1 2 3 4 5 6 7 247 +---+---+---+---+---+---+---+---+---+---+--- 248 L(3+) | Members (L octets) 249 +---+---+---+---+---+---+---+---+---+---+--- 251 Its fields are: 253 o L: The number of octets used to represent the members, encoded as 254 per [RFC7541], Section 5.1, with a 3-bit prefix 256 o Members: L octets 258 Each member of the list will be represented as an Item 259 (Section 2.2.3); if any member cannot, the entire field value will be 260 serialised as a String Literal (Section 2.1.4). 262 The inner list's parameters, if present, are serialised in a 263 following Parameter type (Section 2.2.2); they do not form part of 264 the payload of the inner list. 266 2.2.2. Parameters 268 The Parameters data type (type=0x2) has a payload in the format: 270 5 6 7 0 1 2 3 4 5 6 7 271 +---+---+---+---+---+---+---+---+---+---+--- 272 L(3+) | Parameters (L octets) 273 +---+---+---+---+---+---+---+---+---+---+--- 275 Its fields are: 277 o L: The number of octets used to represent the token, encoded as 278 per [RFC7541], Section 5.1, with a 3-bit prefix 280 o Parameters: L octets 281 Each parameter is represented by key length, followed by that many 282 bytes of the parameter-name, followed by a Binary Structured Type 283 representing the parameter-value. 285 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 286 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 287 | KL (8+) | parameter-name (KL octets) 288 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+--- 290 0 1 2 3 4 5 6 7 291 +---+---+---+---+---+---+---+--- 292 | parameter-value (VL octets) 293 +---+---+---+---+---+---+---+--- 295 A parameter's fields are: 297 o KL: The number of octets used to represent the parameter-name, 298 encoded as per [RFC7541], Section 5.1, with a 8-bit prefix 300 o parameter-name: KL octets of the parameter-name 302 o parameter-value: A Binary Structured type representing a bare item 303 (Section 2.2.3) 305 Parameter-values are bare items; that is, they MUST NOT have 306 parameters themselves. 308 If the parameters cannot be represented, the entire field value will 309 be serialised as a String Literal (Section 2.1.4). 311 Parameters are always associated with the Binary Structured Type that 312 immediately preceded them. If parameters are not explicitly allowed 313 on the preceding type, or there is no preceding type, it is an error. 315 ISSUE: use Huffman coding for parameter-name? 316 https://github.com/mnot/I-D/issues/305 [6] 318 2.2.3. Item Payload Types 320 Individual Structured Header Items can be represented using the 321 Binary Payload Types defined below. 323 The item's parameters, if present, are serialised in a following 324 Parameter type (Section 2.2.2); they do not form part of the payload 325 of the item. 327 2.2.3.1. Integers 329 The Integer data type (type=0x3) has a payload in the format: 331 5 6 7 0 1 2 3 4 5 6 7 332 +---+---+---+---+---+---+---+---+---+---+--- 333 S | X | Length (8+) 334 +---+---+---+---+---+---+---+---+---+---+--- 336 0 1 2 3 4 5 6 7 337 +---+---+---+---+---+---+---+--- 338 | Integer (Length octets) 339 +---+---+---+---+---+---+---+--- 341 Its fields are: 343 o S: sign bit; 0 is negative, 1 is positive 345 o X: 2 bits of padding 347 o Length: The number of octets used to represent the integer, 348 encoded as per [RFC7541], Section 5.1, with a 2-bit prefix 350 o Integer: Length octets 352 2.2.3.2. Floats 354 The Float data type (type=0x4) have a payload in the format: 356 5 6 7 0 1 2 3 4 5 6 7 357 +---+---+---+---+---+---+---+---+---+---+--- 358 S | X | ILength (8+) 359 +---+---+---+---+---+---+---+---+---+---+--- 361 0 1 2 3 4 5 6 7 362 +---+---+---+---+---+---+---+--- 363 | Integer (ILength octets) 364 +---+---+---+---+---+---+---+--- 366 0 1 2 3 4 5 6 7 367 +---+---+---+---+---+---+---+--- 368 | FLength (8+) 369 +---+---+---+---+---+---+---+--- 371 0 1 2 3 4 5 6 7 372 +---+---+---+---+---+---+---+--- 373 | Fractional (FLength octets) 374 +---+---+---+---+---+---+---+--- 375 Its fields are: 377 o S: sign bit; 0 is negative, 1 is positive 379 o X: 2 bits of padding 381 o ILength: The number of octets used to represent the integer 382 component, encoded as per [RFC7541], Section 5.1, with a 2-bit 383 prefix. 385 o Integer - ILength octets 387 o FLength: The number of octets used to represent the fractional 388 component, encoded as per [RFC7541], Section 5.1, with a 2-bit 389 prefix. 391 o Fractional: FLength octets 393 2.2.3.3. Strings 395 The String data type (type=0x5) has a payload in the format: 397 5 6 7 0 1 2 3 4 5 6 7 398 +---+---+---+---+---+---+---+---+---+---+--- 399 L(3+) | String (L octets) 400 +---+---+---+---+---+---+---+---+---+---+--- 402 Its fields are: 404 o L: The number of octets used to represent the string, encoded as 405 per [RFC7541], Section 5.1, with a 3-bit prefix. 407 o String: L octets. 409 ISSUE: use Huffman coding? https://github.com/mnot/I-D/issues/305 [7] 411 2.2.3.4. Tokens 413 The Token data type (type=0x6) has a payload in the format: 415 5 6 7 0 1 2 3 4 5 6 7 416 +---+---+---+---+---+---+---+---+---+---+--- 417 L(3+) | Token (L octets) 418 +---+---+---+---+---+---+---+---+---+---+--- 420 Its fields are: 422 o L: The number of octets used to represent the token, encoded as 423 per [RFC7541], Section 5.1, with a 3-bit prefix. 425 o Token: L octets. 427 ISSUE: use Huffman coding? https://github.com/mnot/I-D/issues/305 [8] 429 2.2.3.5. Byte Sequences 431 The Byte Sequence data type (type=0x7) has a payload in the format: 433 5 6 7 0 1 2 3 4 5 6 7 434 +---+---+---+---+---+---+---+---+---+---+--- 435 L(3+) | Byte Sequence (L octets) 436 +---+---+---+---+---+---+---+---+---+---+--- 438 Its fields are: 440 o L: The number of octets used to represent the byte sequence, 441 encoded as per [RFC7541], Section 5.1, with a 3-bit prefix. 443 o Byte Sequence: L octets. 445 2.2.3.6. Booleans 447 The Boolean data type (type=0x8) has a payload of two bits: 449 5 6 7 450 +---+---+---+ 451 B | X | 452 +---+---+---+ 454 If B is 0, the value is False; if B is 1, the value is True. X is 455 padding. 457 3. Using Binary Structured Headers in HTTP/2 459 When both peers on a connection support this specification, they can 460 take advantage of that knowledge to serialise headers that they know 461 to be Structured Headers (or compatible with them; see Section 4). 463 Peers advertise and discover this support using a HTTP/2 setting 464 defined in Section 3.1, and convey Binary Structured Headers in a 465 frame type defined in Section 3.2. 467 3.1. Binary Structured Headers Setting 469 Advertising support for Binary Structured Headers is accomplished 470 using a HTTP/2 setting, SETTINGS_BINARY_STRUCTURED_HEADERS (0xTODO). 472 Receiving SETTINGS_BINARY_STRUCTURED_HEADERS from a peer indicates 473 that: 475 1. The peer supports the Binary Structured Types defined in 476 Section 2. 478 2. The peer will process the BINHEADERS frames as defined in 479 Section 3.2. 481 3. When a downstream consumer does not likewise support that 482 encoding, the peer will transform them into HEADERS frames (if 483 the peer is HTTP/2) or a form it will understand (e.g., the 484 textual representation of Structured Headers data types defined 485 in [I-D.ietf-httpbis-header-structure]). 487 4. The peer will likewise transform all fields defined as Aliased 488 Fields (Section 4.2) into their non-aliased forms as necessary. 490 The default value of SETTINGS_BINARY_STRUCTURED_HEADERS is 0. Future 491 extensions to Structured Headers might use it to indicate support for 492 new types. 494 3.2. The BINHEADERS Frame 496 When a peer has indicated that it supports this specification 497 {#setting}, a sender can send the BINHEADERS Frame Type (0xTODO). 499 The BINHEADERS Frame Type behaves and is represented exactly as a 500 HEADERS Frame type ([RFC7540], Section 6.2), with one exception; 501 instead of using the String Literal Representation defined in 502 [RFC7541], Section 5.2, it uses the Binary Literal Representation 503 defined in Section 2.1. 505 Fields that are Structured Headers can have their values represented 506 using the Binary Literal Representation corresponding to that 507 header's top-level type - List, Dictionary, or Item; their values 508 will then be serialised as a stream of Binary Structured Types. 510 Additionally, any field (including those defined as Structured 511 Headers) can be serialised as a String Literal (Section 2.1.4), which 512 accommodates headers that are not defined as Structured Headers, not 513 valid Structured Headers, or that the sending implementation does not 514 wish to send as Binary Structured Types for some other reason. 516 Note that Field Names are always serialised as String Literals 517 (Section 2.1.4). 519 This means that a BINHEADERS frame can be converted to a HEADERS 520 frame by converting the field values to the string representations of 521 the various Structured Headers Types, and String Literals 522 (Section 2.1.4) to their string counterparts. 524 Conversely, a HEADERS frame can be converted to a BINHEADERS frame by 525 encoding all of the Literal field values as Binary Structured Types. 526 In this case, the header types used are informed by the 527 implementations knowledge of the individual header field semantics; 528 see Section 4. Those which it cannot (do to either lack of knowledge 529 or an error) or does not wish to convert into Structured Headers are 530 conveyed in BINHEADERS as String Literals (Section 2.1.4). 532 Field values are stored in the HPACK [RFC7541] dynamic table without 533 Huffman encoding, although specific Binary Structured Types might 534 specify the use of such encodings. 536 Note that BINHEADERS and HEADERS frames MAY be mixed on the same 537 connection, depending on the requirements of the sender. Also, note 538 that only the field values are encoded as Binary Structured Types; 539 field names are encoded as they are in HPACK. 541 4. Using Binary Structured Headers with Existing Fields 543 Any header field can potentially be parsed as a Structured Header 544 according to the algorithms in [I-D.ietf-httpbis-header-structure] 545 and serialised as a Binary Structured Header. However, many cannot, 546 so optimistically parsing them can be expensive. 548 This section identifies fields that will usually succeed in 549 Section 4.1, and those that can be mapped into Structured Headers by 550 using an alias field name in Section 4.2. 552 4.1. Directly Represented Fields 554 The following HTTP field names can have their values parsed as 555 Structured Headers according to the algorithms in 556 [I-D.ietf-httpbis-header-structure], and thus can usually be 557 serialised using the corresponding Binary Structured Types. 559 When one of these fields' values cannot be represented using 560 Structured Types, its value can instead be represented as a String 561 Literal (Section 2.1.4). 563 o Accept - List 564 o Accept-Encoding - List 566 o Accept-Language - List 568 o Accept-Patch - List 570 o Accept-Ranges - List 572 o Access-Control-Allow-Credentials - Item 574 o Access-Control-Allow-Headers - List 576 o Access-Control-Allow-Methods - List 578 o Access-Control-Allow-Origin - Item 580 o Access-Control-Max-Age - Item 582 o Access-Control-Request-Headers - List 584 o Access-Control-Request-Method - Item 586 o Age - Item 588 o Allow - List 590 o ALPN - List 592 o Alt-Svc - List 594 o Alt-Used - Item 596 o Cache-Control - Dictionary 598 o Content-Encoding - Item 600 o Content-Language - List 602 o Content-Length - Item 604 o Content-Type - Item 606 o Expect - Item 608 o Forwarded - List 610 o Host - Item 611 o Origin - Item 613 o Pragma - Dictionary 615 o Prefer - Dictionary 617 o Preference-Applied - Dictionary 619 o Retry-After - Item (see caveat below) 621 o Surrogate-Control - Dictionary 623 o TE - List 625 o Trailer - List 627 o Transfer-Encoding - List 629 o Vary - List 631 o X-Content-Type-Options - Item 633 Note that only the delta-seconds form of Retry-After is supported; a 634 Retry-After value containing a http-date will need to be either 635 converted into delta-seconds or serialised as a String Literal 636 (Section 2.1.4). 638 4.2. Aliased Fields 640 The following HTTP field names can have their values represented in 641 Structured headers by mapping them into its data types and then 642 serialising the resulting Structured Header using an alternative 643 field name. 645 For example, the Date HTTP header field carries a http-date, which is 646 a string representing a date: 648 Date: Sun, 06 Nov 1994 08:49:37 GMT 650 Its value is more efficiently represented as an integer number of 651 delta seconds from the Unix epoch (00:00:00 UTC on 1 January 1970, 652 minus leap seconds). Thus, the example above would be represented in 653 (non-binary) Structured headers as: 655 SH-Date: 784072177 657 As with directly represented fields, if the intended value of an 658 aliased field cannot be represented using Structured Types 659 successfully, its value can instead be represented as a String 660 Literal (Section 2.1.4). 662 Note that senders MUST know that the next-hop recipient understands 663 these fields (typically, using the negotiation mechanism defined in 664 Section 3) before using them. Likewise, recipients MUST transform 665 them back to their unaliased form before forwarding the message to a 666 peer or other consuming components that do not have this capability. 668 Each field name listed below indicates a replacement field name and a 669 way to map its value to Structured Headers. 671 ISSUE: using separate names assures that the different syntax doesn't 672 "leak" into normal headers, but it isn't strictly necessary if 673 implementations always convert back to the correct form when giving 674 it to peers or consuming software that doesn't understand this. 675 https://github.com/mnot/I-D/issues/307 [9] 677 4.2.1. URLs 679 The following field names (paired with their replacement field names) 680 have values that can be represented in Binary Structured Headers by 681 considering their payload a string. 683 o Content-Location - SH-Content-Location 685 o Location - SH-Location 687 o Referer - SH-Referer 689 For example, a (non-binary) Location: 691 SH-Location: "https://example.com/foo" 693 TOOD: list of strings, one for each path segment, to allow better 694 compression in the future? 696 4.2.2. Dates 698 The following field names (paired with their replacement field names) 699 have values that can be represented in Binary Structured Headers by 700 parsing their payload according to [RFC7230], Section 7.1.1.1, and 701 representing the result as an integer number of seconds delta from 702 the Unix Epoch (00:00:00 UTC on 1 January 1970, minus leap seconds). 704 o Date - SH-Date 706 o Expires - SH-Expires 707 o If-Modified-Since - SH-IMS 709 o If-Unmodified-Since - SH-IUS 711 o Last-Modified - SH-LM 713 For example, a (non-binary) Expires: 715 SH-Expires: 1571965240 717 4.2.3. ETags 719 The following field names (paired with their replacement field names) 720 have values that can be represented in Binary Structured Headers by 721 representing the entity-tag as a string, and the weakness flag as a 722 boolean "w" parameter on it, where true indicates that the entity-tag 723 is weak; if 0 or unset, the entity-tag is strong. 725 o ETag - SH-ETag 727 For example, a (non-Binary) ETag: 729 SH-ETag: "abcdef"; w=?1 731 If-None-Match is a list of the structure described above. 733 o If-None-Match - SH-INM 735 For example, a (non-binary) If-None-Match: 737 SH-INM: "abcdef"; w=?1, "ghijkl" 739 4.2.4. Links 741 The field-value of the Link header field [RFC8288] can be represented 742 in Binary Structured Headers by representing the URI-Reference as a 743 string, and link-param as parameters. 745 o Link: SH-Link 747 For example, a (non-binary) Link: 749 SH-Link: "/terms"; rel="copyright"; anchor="#foo" 751 4.2.5. Cookies 753 The field-value of the Cookie and Set-Cookie fields [RFC6265] can be 754 represented in Binary Structured Headers as a List with parameters 755 and a Dictionary, respectively. The serialisation is almost 756 identical, except that the Expires parameter is always a string (as 757 it can contain a comma), multiple cookie-strings can appear in Set- 758 Cookie, and cookie-pairs are delimited in Cookie by a comma, rather 759 than a semicolon. 761 Set-Cookie: SH-Set-Cookie Cookie: SH-Cookie 763 SH-Set-Cookie: lang=en-US, Expires="Wed, 09 Jun 2021 10:18:14 GMT" 764 SH-Cookie: SID=31d4d96e407aad42, lang=en-US 766 ISSUE: explicitly convert Expires to an integer? 767 https://github.com/mnot/I-D/issues/308 [10] 769 5. IANA Considerations 771 ISSUE: todo 773 6. Security Considerations 775 As is so often the case, having alternative representations of data 776 brings the potential for security weaknesses, when attackers exploit 777 the differences between those representations and their handling. 779 One mitigation to this risk is the strictness of parsing for both 780 non-binary and binary Structured Headers data types, along with the 781 "escape valve" of String Literals (Section 2.1.4). Therefore, 782 implementation divergence from this strictness can have security 783 impact. 785 7. References 787 7.1. Normative References 789 [I-D.ietf-httpbis-header-structure] 790 Nottingham, M. and P. Kamp, "Structured Headers for HTTP", 791 draft-ietf-httpbis-header-structure-14 (work in progress), 792 October 2019. 794 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 795 Requirement Levels", BCP 14, RFC 2119, 796 DOI 10.17487/RFC2119, March 1997, 797 . 799 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 800 DOI 10.17487/RFC6265, April 2011, 801 . 803 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 804 Protocol (HTTP/1.1): Message Syntax and Routing", 805 RFC 7230, DOI 10.17487/RFC7230, June 2014, 806 . 808 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 809 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 810 DOI 10.17487/RFC7540, May 2015, 811 . 813 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 814 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 815 . 817 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 818 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 819 May 2017, . 821 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 822 DOI 10.17487/RFC8288, October 2017, 823 . 825 7.2. URIs 827 [1] https://github.com/mnot/I-D/labels/binary-structured-headers 829 [2] https://mnot.github.io/I-D/binary-structured-headers/ 831 [3] https://github.com/mnot/I-D/commits/gh-pages/binary-structured- 832 headers 834 [4] https://datatracker.ietf.org/doc/draft-nottingham-binary- 835 structured-headers/ 837 [5] https://github.com/mnot/I-D/issues/305 839 [6] https://github.com/mnot/I-D/issues/305 841 [7] https://github.com/mnot/I-D/issues/305 843 [8] https://github.com/mnot/I-D/issues/305 845 [9] https://github.com/mnot/I-D/issues/307 847 [10] https://github.com/mnot/I-D/issues/308 849 Author's Address 851 Mark Nottingham 852 Fastly 854 Email: mnot@mnot.net 855 URI: https://www.mnot.net/