idnits 2.17.1 draft-nottingham-site-wide-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 : ---------------------------------------------------------------------------- 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 (August 3, 2016) is 2822 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft August 3, 2016 4 Intended status: Informational 5 Expires: February 4, 2017 7 Site-Wide HTTP Headers 8 draft-nottingham-site-wide-headers-00 10 Abstract 12 This document specifies an alternative way for Web sites to send HTTP 13 response header fields that apply to large numbers of resources, to 14 improve 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 February 4, 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. Example . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 4 53 2. Server Operation . . . . . . . . . . . . . . . . . . . . . . 4 54 2.1. Selecting Site-Wide Headers . . . . . . . . . . . . . . . 5 55 2.2. The "HS" HTTP Response Header Field . . . . . . . . . . . 5 56 3. User Agent Operation . . . . . . . . . . . . . . . . . . . . 5 57 3.1. The "SM" HTTP Request Header Field . . . . . . . . . . . 6 58 4. The "site-headers" well-known URI . . . . . . . . . . . . . . 6 59 4.1. The "text/site-headers" Media Type . . . . . . . . . . . 7 60 4.1.1. Parsing "text/site-headers" . . . . . . . . . . . . . 8 61 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 62 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 63 6.1. Injecting Headers . . . . . . . . . . . . . . . . . . . . 8 64 6.2. Inappropriate Headers . . . . . . . . . . . . . . . . . . 9 65 6.3. Differing Views of Headers . . . . . . . . . . . . . . . 9 66 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 67 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 68 7.2. Informative References . . . . . . . . . . . . . . . . . 10 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 71 1. Introduction 73 HTTP response headers are being used for an increasing amount of 74 metadata that applies to an entire site, or large portions of it. 76 For example, "Strict-Transport-Security" [RFC6797] and "Public-Key- 77 Pins" [RFC7469] both define headers that are explicitly scoped to an 78 entire origin [RFC6454], and number of similar headers are under 79 consideration. 81 Likewise, some HTTP header fields only sensibly have a single value 82 per origin; for example, "Server". 84 Furthermore, some headers are used uniformly across an origin. For 85 example, a site might have a "Content-Security-Policy" 86 [W3C.CR-CSP2-20150721] header that doesn't vary across the site, or 87 only varies slightly from resource to resource. 89 HTTP/2's HPACK [RFC7541] header compression mechanism was designed to 90 reduce bandwidth usage for often-repeated headers, both in responses 91 and requests. However, it limits the amount of compression contents 92 usable for a connection (by default, 4K), which sites are beginning 93 to exceed, thereby reducing the efficiency of HPACK itself. 95 For example, it is not uncommon for a CSP response header field to 96 exceed 1K (and has been observed to be greater than 3K on popular 97 sites). This forces site administrators to make an awkward choice; 98 put the large header in the HPACK table, thereby crowding out other 99 headers, or omit it, requiring its full content to be sent on every 100 applicable response. 102 This document defines a way to specify one or more sets of HTTP 103 response header fields in a well-known resource [RFC5785] that, when 104 their use is negotiated, are appended to HTTP responses by the user 105 agent. This allows common response headers to be omitted both from 106 on-the-wire responses and the HPACK compression table, making both 107 more efficient. 109 This approach is preferable to increasing the HTTP/2 110 SETTINGS_HEADER_TABLE_SIZE ([RFC7540], Section 6.5.2), because 111 increasing that setting incurs a per-connection overhead on the 112 server, whereas using the technique documented here does not. 114 1.1. Example 116 If a user agent has a fresh copy of the well-known resource for an 117 origin (see Section 4), because either it performed a GET, or HTTP/2 118 Server Push was used: 120 HTTP/1.1 200 OK 121 Content-Type: text/site-headers 122 Cache-Control: max-age=3600 123 ETag: "abc123" 124 Content-Length: 1234 126 # a 127 Strict-Transport-Security: max-age=15768000 ; includeSubDomains 128 Server: Apache/2.4.7 (Ubuntu) 129 Public-Key-Pins: max-age=604800; 130 pin-sha256="ZitlqPmA9wodcxkwOW/c7ehlNFk8qJ9FsocodG6GzdjNM="; 131 pin-sha256="XRXP987nz4rd1/gS2fJSNVfyrZbqa00T7PeRXUPd15w="; 132 report-uri="/lib/key-pin.cgi" 134 and the user agent makes the request: 136 GET /images/foo.jpg HTTP/1.1 137 Host: www.example.com 138 SM: "abc123" 140 this indicates that the user agent has processed the well-known 141 resource, and therefore that the server can omit the nominated 142 response header fields on the wire, instead referring to them with 143 the "HS" response header field: 145 HTTP/1.1 200 OK 146 Content-Type: image/jpeg 147 Vary: SM, Accept-Encoding 148 Cache-Control: max-age=3600 149 HS: "a" 150 Transfer-Encoding: chunked 152 Upon receipt of that response, the user agent will consider it 153 equivalent to: 155 HTTP/1.1 200 OK 156 Content-Type: image/jpeg 157 Vary: SM, Accept-Encoding 158 Cache-Control: max-age=3600 159 Connection: close 160 Strict-Transport-Security: max-age=15768000 ; includeSubDomains 161 Server: Apache/2.4.7 (Ubuntu) 162 Public-Key-Pins: max-age=604800; 163 pin-sha256="ZitlqPmA9wodcxkwOW/c7ehlNFk8qJ9FsocodG6GzdjNM="; 164 pin-sha256="XRXP987nz4rd1/gS2fJSNVfyrZbqa00T7PeRXUPd15w="; 165 report-uri="/lib/key-pin.cgi" 167 If a request omits the "SM" header field, or its field-value does not 168 match the current ETag of the well-known resource, all of the header 169 fields above will be sent by the server in the response. 171 1.2. Notational Conventions 173 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 174 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 175 document are to be interpreted as described in [RFC2119]. 177 This document uses the following ABNF rules from [RFC5234]: "DQUOTE", 178 "ALPHA". From [RFC7230]: "OWS", "RWS", "CRLF", "header-field". From 179 [RFC7232]: "entity-tag". 181 2. Server Operation 183 When a server wishes to use site-wide HTTP headers, it places a file 184 in the format specified in Section 4.1 at the well-known URI 185 specified in Section 4. 187 Then, when a request has a "SM" request header field (as per 188 Section 3.1) that matches the current ETag of the well-known 189 resource, the set of response header fields referred to by the "HS" 190 response header field (see Section 2.2) for the requested resource 191 are omitted from the corresponding response. 193 Servers SHOULD include "SM" in the field-value of the "Vary" response 194 header field for all cacheable (as per [RFC7234]) responses of 195 resources that behave in this manner, whether or not headers have 196 been actually appended. This assures correct cache operation, and 197 also advertises support for this specification. 199 Servers MAY use HTTP/2 Server Push ([RFC7540], Section 8.2) to 200 proactively send the well-known resource to user agents (e.g., if 201 they emit "SM: *", indicating that they do not have a fresh copy of 202 the well-known resource). 204 2.1. Selecting Site-Wide Headers 206 Because this mechanism effectively hides response header fields from 207 intermediaries that do not implement it, care ought to be take in 208 selecting the headers to use it upon. 210 For example, the "Cache-Control" and "Vary" headers are poor 211 candidates, because they are often used by intermediaries for HTTP 212 caching [RFC7234]. 214 Likewise, HTTP/1 headers that affect message framing and connection 215 behaviour (e.g., "Content-Length", "Transfer-Encoding", "Connection") 216 MUST NOT be included in the well-known resource. 218 2.2. The "HS" HTTP Response Header Field 220 The "HS" HTTP response header field indicates the header set in the 221 well-known location file (see Section 4.1) that should be applied to 222 the response it occurs within. 224 HS = DQUOTE 1*ALPHA DQUOTE 226 For example: 228 HS: "foo" 230 3. User Agent Operation 232 User agents that support this specification SHOULD always emit a "SM" 233 header field in requests, carrying either the "ETag" of the well- 234 known resource currently held for the origin, or "*" to indicate that 235 they support this specification, but do not have a fresh (as per 236 [RFC7234]) copy of it. 238 User agents might discover that an origin supports this specification 239 when it returns a response containing the "HS" response header field, 240 or they might learn of it when the well-known location's current 241 contents are sent via a HTTP/2 Server Push. 243 In either case, user agents SHOULD send a "SM" request header field 244 on all requests to such an origin. 246 Upon receiving a response to such a request containing the "HS" 247 response header field, user agents MUST locate the header-set 248 referred to by its field-value in the stored well-known response, 249 remove any surrounding white space, and append it to the response 250 headers, stripping the "HS" response header field. 252 If the corresponding header-set cannot be found in the well-known 253 location, the response MUST be considered invalid and MUST NOT be 254 used; the user agent MAY retry the request without the "SM" request 255 header field if its method was safe, or may take alternative recovery 256 strategies. 258 3.1. The "SM" HTTP Request Header Field 260 The "SM" HTTP request header field indicates that the user agent has 261 a fresh (as per [RFC7234]) copy of the well-known resource (see 262 Section 4) for the request's origin ([RFC6454]). 264 SM = "*" / entity-tag 266 Its value is the "entity-tag" [RFC7232] of the freshest valid well- 267 known location response held by the user agent. If none is held, it 268 should be "*" (without quotes). 270 For example: 272 SM: "abc123" 273 SM: * 275 4. The "site-headers" well-known URI 277 The well-known URI [RFC5785] "site-headers" is a resource that, when 278 fetched, returns a file in the "text/site-headers" format (see 279 Section 4.1). 281 Its media type SHOULD be generated as "text/site-headers", although 282 user agents SHOULD NOT reject responses with other types 283 (particularly, "application/octet-stream" and "text/plain"). 285 Its representation MUST contain an "ETag" response header [RFC7232]. 287 User agents SHOULD consider it to be valid for its freshness lifetime 288 (as per [RFC7234]). If it does not have an explicit freshness 289 lifetime, they SHOULD consider it to have a heuristic freshness 290 lifetime of 60 seconds. 292 4.1. The "text/site-headers" Media Type 294 The "text/site-headers" media type is used to indicate that a file 295 contains one or more sets of HTTP header fields, as defined in 296 [RFC7230], Section 3. 298 site-headers = 1*( header-header header-set ) 299 header-header = "#" 1*RWS set-name OWS CRLF 300 set-name = 1*ALPHA 301 header-set = OWS *( header-field CRLF ) OWS 303 Each set of HTTP header fields is started by a header-header, which 304 is indicated by an octothorp ("#") followed by the name of the header 305 set. The following lines, up until the next line beginning with an 306 octothorp or the end of the file are considered to be the header- 307 set's contents. 309 As in HTTP itself, implementations need to be forgiving about line 310 endings; specifically, bare CR MUST be considered to be a line 311 ending. 313 For example: 315 # foo 316 Strict-Transport-Security: max-age=15768000 ; includeSubDomains 317 Server: Apache/2.4.7 (Ubuntu) 318 Public-Key-Pins: max-age=604800; 319 pin-sha256="ZitlqPmA9wodcxkwOW/c7ehlNFk8qJ9FsocodG6GzdjNM="; 320 pin-sha256="XRXP987nz4rd1/gS2fJSNVfyrZbqa00T7PeRXUPd15w="; 321 report-uri="/lib/key-pin.cgi" 322 # bar 323 Strict-Transport-Security: max-age=15768000 ; includeSubDomains 324 Server: Apache/2.4.7 (Ubuntu) 325 Public-Key-Pins: max-age=604800; 326 pin-sha256="ZitlqPmA9wodcxkwOW/c7ehlNFk8qJ9FsocodG6GzdjNM="; 327 pin-sha256="XRXP987nz4rd1/gS2fJSNVfyrZbqa00T7PeRXUPd15w="; 328 report-uri="/lib/key-pin.cgi" 329 Content-Security-Policy: default-src 'self'; img-src 'self' 330 *.staticflickr.com; frame-ancestors 'none'; 331 report-uri https://mnot.report-uri.io/r/default/csp/enforce 333 This file specifies two sets of HTTP headers, "foo" and "bar". Note 334 that the "Public-Key-Pins" and "Content-Security-Policy" header 335 fields are line-folded; as in HTTP, this form of header is deprecated 336 in this format, and SHOULD NOT be used (except in documentation, as 337 we see here). 339 4.1.1. Parsing "text/site-headers" 341 Given a stream of Unicode characters: 343 1. Let "header-sets" be an empty mapping. 345 2. Consume all characters from up to and including the first 346 octothorp ("#"). 348 3. Consume all "WSP" characters. 350 4. Let "set-name" be all characters up to but not including the 351 next "WSP", "CR" or "LF". 353 5. Consume all "WSP", "CR" and "LF characters". 355 6. Let "header-set" be all characters up to but not including the 356 next "CR" or "LF" character followed by an octothorp ("#"), or 357 the end of the file. 359 7. Trim all "WSP" from the end of "header-set". 361 8. Let the value of the "set-name" entry in "header-sets" be 362 "header-set" (removing any existing value). 364 9. If there is more "input", return to step 2. 366 10. Otherwise, return "header-sets". 368 This returns a mapping of "set-name" to a HTTP "header-set", as 369 defined in [RFC7230], Section 3. It SHOULD be parsed as defined 370 there. 372 5. IANA Considerations 374 TBD 376 6. Security Considerations 378 6.1. Injecting Headers 380 Site-wide headers allow a single resource to inject HTTP response 381 headers for an entire origin. Accordingly, the ability to write to 382 that resource needs to be carefully controlled by the origin server. 384 6.2. Inappropriate Headers 386 As noted in Section 2.1, there are a variety of HTTP response headers 387 which are inappropriate for use as site-wide headers, and some (e.g., 388 "Content-Length") can cause both interoperability and security 389 issues. 391 6.3. Differing Views of Headers 393 Because headers sent via this mechanism will not be seen by user 394 agents and intermediaries that do not implement this specification, 395 they will potentially have a different view of the response headers. 397 7. References 399 7.1. Normative References 401 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 402 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 403 RFC2119, March 1997, 404 . 406 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 407 Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ 408 RFC5234, January 2008, 409 . 411 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 412 Uniform Resource Identifiers (URIs)", RFC 5785, DOI 413 10.17487/RFC5785, April 2010, 414 . 416 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, DOI 417 10.17487/RFC6454, December 2011, 418 . 420 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 421 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 422 7230, DOI 10.17487/RFC7230, June 2014, 423 . 425 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 426 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, DOI 427 10.17487/RFC7232, June 2014, 428 . 430 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 431 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 432 RFC 7234, DOI 10.17487/RFC7234, June 2014, 433 . 435 7.2. Informative References 437 [RFC6797] Hodges, J., Jackson, C., and A. Barth, "HTTP Strict 438 Transport Security (HSTS)", RFC 6797, DOI 10.17487/ 439 RFC6797, November 2012, 440 . 442 [RFC7469] Evans, C., Palmer, C., and R. Sleevi, "Public Key Pinning 443 Extension for HTTP", RFC 7469, DOI 10.17487/RFC7469, April 444 2015, . 446 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 447 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 448 10.17487/RFC7540, May 2015, 449 . 451 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 452 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 453 . 455 [W3C.CR-CSP2-20150721] 456 West, M., Barth, A., and D. Veditz, "Content Security 457 Policy Level 2", World Wide Web Consortium CR CR- 458 CSP2-20150721, July 2015, 459 . 461 Author's Address 463 Mark Nottingham 465 Email: mnot@mnot.net 466 URI: https://www.mnot.net/