idnits 2.17.00 (12 Aug 2021) /tmp/idnits8766/draft-nottingham-site-wide-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 24, 2016) is 1997 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) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft November 24, 2016 4 Intended status: Standards Track 5 Expires: May 28, 2017 7 Site-Wide HTTP Headers 8 draft-nottingham-site-wide-headers-01 10 Abstract 12 This document specifies an alternative way for Web sites to send HTTP 13 response header fields that apply to an entire origin, to improve 14 efficiency. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on May 28, 2017. 33 Copyright Notice 35 Copyright (c) 2016 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Selecting Site-Wide Headers . . . . . . . . . . . . . . . 3 52 1.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 4 53 1.3. Notational Conventions . . . . . . . . . . . . . . . . . 5 54 2. Server Operation . . . . . . . . . . . . . . . . . . . . . . 5 55 3. User Agent Operation . . . . . . . . . . . . . . . . . . . . 6 56 3.1. The "SH" HTTP Request Header Field . . . . . . . . . . . 6 57 3.2. The "HS" HTTP Response Header Field . . . . . . . . . . . 7 58 4. The "site-headers" well-known URI . . . . . . . . . . . . . . 7 59 4.1. The "text/site-headers" Media Type . . . . . . . . . . . 7 60 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 62 6.1. Injecting Headers . . . . . . . . . . . . . . . . . . . . 8 63 6.2. Differing Views of Headers . . . . . . . . . . . . . . . 8 64 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 65 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 66 7.2. Informative References . . . . . . . . . . . . . . . . . 9 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 69 1. Introduction 71 HTTP response headers are being used for an increasing amount of 72 metadata that applies to an entire Web site (i.e., the entire origin, 73 as per [RFC6454]). 75 For example, "Strict-Transport-Security" [RFC6797] and "Public-Key- 76 Pins" [RFC7469] both define headers that are explicitly scoped to an 77 entire origin, and number of similar headers are under consideration. 79 Likewise, some HTTP header fields only sensibly have a single value 80 per origin; for example, "Server". 82 Furthermore, some headers are used uniformly across an origin. For 83 example, a site might have a homogenous "Content-Security-Policy" 84 [W3C.CR-CSP2-20150721] header. 86 HTTP/2's HPACK [RFC7541] header compression mechanism was designed to 87 reduce bandwidth usage for often-repeated headers, both in responses 88 and requests. However, it limits the amount of compression contents 89 usable for a connection (by default, 4K), and some sites are 90 beginning to exceed this limit, thereby reducing the efficiency of 91 HPACK itself. 93 For example, it is not uncommon for a CSP response header field to 94 exceed 1K (and has been observed to be greater than 3K on popular 95 sites). This forces site administrators to make an awkward choice; 96 put the large header in the HPACK table, thereby crowding out other 97 headers, or omit it, requiring its full content to be sent on every 98 applicable response. 100 This document defines a way to specify one or more sets of HTTP 101 response header fields in a well-known resource [RFC5785] that, when 102 their use is negotiated, are appended to the header blocks of all 103 HTTP responses on that site by the user agent. This allows common 104 response headers to be omitted both from on-the-wire responses and 105 the HPACK compression table, making both more efficient. 107 This approach is preferable to increasing the HTTP/2 108 SETTINGS_HEADER_TABLE_SIZE ([RFC7540], Section 6.5.2), because 109 increasing that setting incurs a per-connection overhead on the 110 server, whereas using the technique documented here does not. 112 1.1. Selecting Site-Wide Headers 114 Only certain header fields are suitable for being set for an entire 115 origin. Therefore, a header field MUST be listed below, or its field 116 name MUST start with the characters "site-" (case insensitive) to be 117 usable as a site-wide header. 119 The whitelisted field names are: 121 o Access-Control-Allow-Origin 123 o Alt-Svc 125 o Content-Security-Policy 127 o P3P 129 o Public-Key-Pins 131 o Public-Key-Pins-Report-Only 133 o Server 135 o Strict-Transport-Security 137 Note that inclusion in this list does not imply that a header field 138 is always site-wide. 140 Future specifications SHOULD NOT update this whitelist; instead, they 141 SHOULD use the "site-" prefix. 143 1.2. Example 145 If a user agent has a fresh copy of the well-known resource for an 146 origin (see Section 4) (e.g., because it performed a GET, or HTTP/2 147 Server Push was used): 149 HTTP/1.1 200 OK 150 Content-Type: text/site-headers 151 Cache-Control: max-age=3600 152 ETag: "abc123" 153 Content-Length: 284 155 Strict-Transport-Security: max-age=15768000 ; includeSubDomains 156 Server: Apache/2.4.7 (Ubuntu) 157 Public-Key-Pins: max-age=604800; 158 pin-sha256="ZitlqPmA9wodcxkwOW/c7ehlNFk8qJ9FsocodG6GzdjNM="; 159 pin-sha256="XRXP987nz4rd1/gS2fJSNVfyrZbqa00T7PeRXUPd15w="; 160 report-uri="/lib/key-pin.cgi" 161 Site-Foo: bar 163 and the user agent makes a subsequent request: 165 GET /images/foo.jpg HTTP/1.1 166 Host: www.example.com 167 SH: "abc123" 169 That indicates that the user agent has processed the well-known 170 resource (because the "SH" header field is present, and its value 171 matches the current value of the "ETag" of the well-known resource). 172 Therefore, the server can omit the nominated response header fields 173 on the wire, replacing them with the "HS" response header field, 174 whose value is the same as that of the "SH" field: 176 HTTP/1.1 200 OK 177 Content-Type: image/jpeg 178 Vary: SH, Accept-Encoding 179 Cache-Control: max-age=3600 180 Transfer-Encoding: chunked 181 HS: "abc123" 183 Upon receipt of that response, the user agent will consider it 184 equivalent to: 186 HTTP/1.1 200 OK 187 Content-Type: image/jpeg 188 Vary: SH, Accept-Encoding 189 Cache-Control: max-age=3600 190 Connection: close 191 Strict-Transport-Security: max-age=15768000 ; includeSubDomains 192 Server: Apache/2.4.7 (Ubuntu) 193 Public-Key-Pins: max-age=604800; 194 pin-sha256="ZitlqPmA9wodcxkwOW/c7ehlNFk8qJ9FsocodG6GzdjNM="; 195 pin-sha256="XRXP987nz4rd1/gS2fJSNVfyrZbqa00T7PeRXUPd15w="; 196 report-uri="/lib/key-pin.cgi" 197 Site-Foo: bar 199 If a request omits the "SH" header field, or its field-value does not 200 match the current "ETag" of the well-known resource, all of the 201 header fields above will be sent by the server in the response, and 202 "HS" will not be sent. 204 1.3. Notational Conventions 206 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 207 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 208 document are to be interpreted as described in [RFC2119]. 210 This document uses the following ABNF rules from [RFC7230]: "OWS", 211 "CRLF", "header-field". From [RFC7232]: "entity-tag". 213 2. Server Operation 215 When a server wishes to use site-wide HTTP headers, it places a file 216 in the format specified in Section 4.1 at the well-known URI 217 specified in Section 4. That file SHOULD NOT contain header fields 218 not allowed by Section 1.1. 220 Then, when a request has a "SH" request header field (as per 221 Section 3.1) whose value matches the current ETag of the well-known 222 resource, the set of response header fields in the payload of the 223 well-known resource are omitted from the corresponding response, and 224 the "HS" response header field is sent with the same value as the 225 "SH" request header field. 227 Servers MUST include "SH" in the field-value of the "Vary" response 228 header field for all cacheable (as per [RFC7234]) responses of 229 resources that behave in this manner, whether or not headers have 230 been actually appended. This assures correct cache operation, and 231 also advertises support for this specification. 233 Servers MAY use HTTP/2 Server Push ([RFC7540], Section 8.2) to 234 proactively send the well-known resource to user agents (e.g., if 235 they emit "SH: *", indicating that they do not have a fresh copy of 236 the well-known resource). 238 3. User Agent Operation 240 User agents that support this specification SHOULD always emit a "SH" 241 header field in requests. 243 When a valid representation of the well-known resource is held (as 244 defined in Section 4), its value will be its "ETag". When one is not 245 (e.g., because it has not been requested, the one held is 246 syntactically invalid, or it is stale, as per [RFC7234]), its value 247 is "*" (unquoted). 249 When an "ETag" is sent and the response contains the "HS" response 250 header field (see Section 3.2), user agents MUST confirm that the 251 value of the "HS" response header is character-for-character 252 identical (after removing leading and trailing whitespace) to that of 253 the "SH" request header field it sent. If it is not, the response 254 MUST be considered invalid and MUST NOT be used; the user agent MAY 255 retry the request without the "SH" request header field if its method 256 was safe, MAY attempt to re-fetch the well-known location beforehand, 257 and MAY take alternative recovery strategies. 259 If the values match, the user agent MUST append the contents of the 260 well-known resource that are currently held to be appended to the 261 response headers received, but MUST NOT include any headers not 262 allowed by Section 1.1. 264 3.1. The "SH" HTTP Request Header Field 266 The "SH" HTTP request header field indicates that the user agent has 267 a fresh (as per [RFC7234]) copy of the well-known resource (see 268 Section 4) for the request's origin ([RFC6454]). 270 SH = "*" / entity-tag 272 Its value is the "entity-tag" [RFC7232] of the freshest valid well- 273 known location response held by the user agent. If none is held, it 274 should be "*" (without quotes). 276 For example: 278 SH: "abc123" 279 SH: * 281 3.2. The "HS" HTTP Response Header Field 283 The "HS" HTTP response header field indicates that the server has 284 chosen to omit the headers in the well-known resource's response that 285 shares its "ETag" with the field value. 287 HS = entity-tag 289 Its value is the "entity-tag" [RFC7232] of the well-known response 290 whose headers are being used, and MUST match that received in the 291 "SH" header field of the request. 293 For example: 295 HS: "abc123" 297 4. The "site-headers" well-known URI 299 The well-known URI [RFC5785] "site-headers" is a resource that, when 300 fetched, returns a representation in the "text/site-headers" format 301 (see Section 4.1). 303 Its media type SHOULD be generated as "text/site-headers", although 304 user agents SHOULD NOT reject responses with other types 305 (particularly, "application/octet-stream" and "text/plain"). 307 Its representation MUST contain an "ETag" response header [RFC7232]. 309 User agents SHOULD NOT consider it valid if it fails to parse, but 310 MAY attempt to recover from errors in a manner similar to how headers 311 are normally handled. 313 User agents SHOULD consider it to be valid for its freshness lifetime 314 (as per [RFC7234]). If it does not have an explicit freshness 315 lifetime, they SHOULD consider it to have a heuristic freshness 316 lifetime of 120 seconds. 318 4.1. The "text/site-headers" Media Type 320 The "text/site-headers" media type is used to indicate that a file 321 contains a set of HTTP header fields, as defined in [RFC7230], 322 Section 3. 324 site-headers = OWS *( header-field CRLF ) OWS 326 As in HTTP itself, implementations need to be forgiving about line 327 endings; specifically, bare CR MUST be considered to be a line 328 ending. 330 For example: 332 Strict-Transport-Security: max-age=15768000 ; includeSubDomains 333 Server: Apache/2.4.7 (Ubuntu) 334 Public-Key-Pins: max-age=604800; 335 pin-sha256="ZitlqPmA9wodcxkwOW/c7ehlNFk8qJ9FsocodG6GzdjNM="; 336 pin-sha256="XRXP987nz4rd1/gS2fJSNVfyrZbqa00T7PeRXUPd15w="; 337 report-uri="/lib/key-pin.cgi" 338 Content-Security-Policy: default-src 'self'; img-src 'self' 339 *.staticflickr.com; frame-ancestors 'none'; 340 report-uri https://mnot.report-uri.io/r/default/csp/enforce 342 Note that the "Public-Key-Pins" and "Content-Security-Policy" header 343 fields are line-folded; as in HTTP, this form of header is deprecated 344 in this format, and SHOULD NOT be used (except in documentation, as 345 we see here). 347 5. IANA Considerations 349 TBD 351 6. Security Considerations 353 6.1. Injecting Headers 355 Site-wide headers allow a single resource to inject HTTP response 356 headers for an entire origin. Accordingly, the ability to write to 357 that resource needs to be carefully controlled by the origin server. 359 6.2. Differing Views of Headers 361 Because headers sent via this mechanism will not be seen by user 362 agents and intermediaries that do not implement this specification, 363 they will potentially have a different view of the response headers. 365 7. References 367 7.1. Normative References 369 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 370 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 371 RFC2119, March 1997, 372 . 374 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 375 Uniform Resource Identifiers (URIs)", RFC 5785, DOI 376 10.17487/RFC5785, April 2010, 377 . 379 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, DOI 380 10.17487/RFC6454, December 2011, 381 . 383 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 384 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 385 7230, DOI 10.17487/RFC7230, June 2014, 386 . 388 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 389 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, DOI 390 10.17487/RFC7232, June 2014, 391 . 393 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 394 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 395 RFC 7234, DOI 10.17487/RFC7234, June 2014, 396 . 398 7.2. Informative References 400 [RFC6797] Hodges, J., Jackson, C., and A. Barth, "HTTP Strict 401 Transport Security (HSTS)", RFC 6797, DOI 10.17487/ 402 RFC6797, November 2012, 403 . 405 [RFC7469] Evans, C., Palmer, C., and R. Sleevi, "Public Key Pinning 406 Extension for HTTP", RFC 7469, DOI 10.17487/RFC7469, April 407 2015, . 409 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 410 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 411 10.17487/RFC7540, May 2015, 412 . 414 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 415 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 416 . 418 [W3C.CR-CSP2-20150721] 419 West, M., Barth, A., and D. Veditz, "Content Security 420 Policy Level 2", World Wide Web Consortium CR CR- 421 CSP2-20150721, July 2015, 422 . 424 Author's Address 426 Mark Nottingham 428 Email: mnot@mnot.net 429 URI: https://www.mnot.net/