idnits 2.17.1 draft-ietf-httpbis-p6-cache-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) 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 seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 26, 2009) is 5296 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) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-08 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-08 == Outdated reference: A later version (-20) exists of draft-ietf-httpbis-p3-payload-08 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-08 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-08 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-08 -- Obsolete informational reference (is this intentional?): RFC 1305 (Obsoleted by RFC 5905) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis Working Group R. Fielding, Ed. 3 Internet-Draft Day Software 4 Obsoletes: 2616 (if approved) J. Gettys 5 Intended status: Standards Track One Laptop per Child 6 Expires: April 29, 2010 J. Mogul 7 HP 8 H. Frystyk 9 Microsoft 10 L. Masinter 11 Adobe Systems 12 P. Leach 13 Microsoft 14 T. Berners-Lee 15 W3C/MIT 16 Y. Lafon, Ed. 17 W3C 18 M. Nottingham, Ed. 20 J. Reschke, Ed. 21 greenbytes 22 October 26, 2009 24 HTTP/1.1, part 6: Caching 25 draft-ietf-httpbis-p6-cache-08 27 Status of this Memo 29 This Internet-Draft is submitted to IETF in full conformance with the 30 provisions of BCP 78 and BCP 79. This document may contain material 31 from IETF Documents or IETF Contributions published or made publicly 32 available before November 10, 2008. The person(s) controlling the 33 copyright in some of this material may not have granted the IETF 34 Trust the right to allow modifications of such material outside the 35 IETF Standards Process. Without obtaining an adequate license from 36 the person(s) controlling the copyright in such materials, this 37 document may not be modified outside the IETF Standards Process, and 38 derivative works of it may not be created outside the IETF Standards 39 Process, except to format it for publication as an RFC or to 40 translate it into languages other than English. 42 Internet-Drafts are working documents of the Internet Engineering 43 Task Force (IETF), its areas, and its working groups. Note that 44 other groups may also distribute working documents as Internet- 45 Drafts. 47 Internet-Drafts are draft documents valid for a maximum of six months 48 and may be updated, replaced, or obsoleted by other documents at any 49 time. It is inappropriate to use Internet-Drafts as reference 50 material or to cite them other than as "work in progress." 52 The list of current Internet-Drafts can be accessed at 53 http://www.ietf.org/ietf/1id-abstracts.txt. 55 The list of Internet-Draft Shadow Directories can be accessed at 56 http://www.ietf.org/shadow.html. 58 This Internet-Draft will expire on April 29, 2010. 60 Copyright Notice 62 Copyright (c) 2009 IETF Trust and the persons identified as the 63 document authors. All rights reserved. 65 This document is subject to BCP 78 and the IETF Trust's Legal 66 Provisions Relating to IETF Documents in effect on the date of 67 publication of this document (http://trustee.ietf.org/license-info). 68 Please review these documents carefully, as they describe your rights 69 and restrictions with respect to this document. 71 Abstract 73 The Hypertext Transfer Protocol (HTTP) is an application-level 74 protocol for distributed, collaborative, hypermedia information 75 systems. This document is Part 6 of the seven-part specification 76 that defines the protocol referred to as "HTTP/1.1" and, taken 77 together, obsoletes RFC 2616. Part 6 defines requirements on HTTP 78 caches and the associated header fields that control cache behavior 79 or indicate cacheable response messages. 81 Editorial Note (To be removed by RFC Editor) 83 Discussion of this draft should take place on the HTTPBIS working 84 group mailing list (ietf-http-wg@w3.org). The current issues list is 85 at and related 86 documents (including fancy diffs) can be found at 87 . 89 The changes in this draft are summarized in Appendix C.9. 91 Table of Contents 93 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 94 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 95 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 96 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 6 97 1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 98 1.4.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 7 99 1.4.2. ABNF Rules defined in other Parts of the 100 Specification . . . . . . . . . . . . . . . . . . . . 7 101 2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 7 102 2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 7 103 2.1.1. Storing Partial and Incomplete Responses . . . . . . . 8 104 2.2. Constructing Responses from Caches . . . . . . . . . . . . 8 105 2.3. Freshness Model . . . . . . . . . . . . . . . . . . . . . 9 106 2.3.1. Calculating Freshness Lifetime . . . . . . . . . . . . 10 107 2.3.2. Calculating Age . . . . . . . . . . . . . . . . . . . 11 108 2.3.3. Serving Stale Responses . . . . . . . . . . . . . . . 13 109 2.4. Validation Model . . . . . . . . . . . . . . . . . . . . . 13 110 2.5. Request Methods that Invalidate . . . . . . . . . . . . . 14 111 2.6. Caching Negotiated Responses . . . . . . . . . . . . . . . 15 112 2.7. Combining Responses . . . . . . . . . . . . . . . . . . . 16 113 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 16 114 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 115 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 17 116 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 18 117 3.2.2. Response Cache-Control Directives . . . . . . . . . . 20 118 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 22 119 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 23 120 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 24 121 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 122 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 25 123 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 28 124 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 125 5.1. Message Header Registration . . . . . . . . . . . . . . . 28 126 6. Security Considerations . . . . . . . . . . . . . . . . . . . 29 127 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29 128 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 129 8.1. Normative References . . . . . . . . . . . . . . . . . . . 29 130 8.2. Informative References . . . . . . . . . . . . . . . . . . 30 131 Appendix A. Compatibility with Previous Versions . . . . . . . . 30 132 A.1. Changes from RFC 2068 . . . . . . . . . . . . . . . . . . 31 133 A.2. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 31 134 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 31 135 Appendix C. Change Log (to be removed by RFC Editor before 136 publication) . . . . . . . . . . . . . . . . . . . . 33 137 C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 33 138 C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 33 139 C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 34 140 C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 34 141 C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 34 142 C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 35 143 C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 35 144 C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 35 145 C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 36 146 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 147 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38 149 1. Introduction 151 HTTP is typically used for distributed information systems, where 152 performance can be improved by the use of response caches. This 153 document defines aspects of HTTP/1.1 related to caching and reusing 154 response messages. 156 1.1. Purpose 158 An HTTP cache is a local store of response messages and the subsystem 159 that controls its message storage, retrieval, and deletion. A cache 160 stores cacheable responses in order to reduce the response time and 161 network bandwidth consumption on future, equivalent requests. Any 162 client or server may include a cache, though a cache cannot be used 163 by a server that is acting as a tunnel. 165 Caching would be useless if it did not significantly improve 166 performance. The goal of caching in HTTP/1.1 is to reuse a prior 167 response message to satisfy a current request. In some cases, a 168 stored response can be reused without the need for a network request, 169 reducing latency and network round-trips; a "freshness" mechanism is 170 used for this purpose (see Section 2.3). Even when a new request is 171 required, it is often possible to reuse all or parts of the payload 172 of a prior response to satisfy the request, thereby reducing network 173 bandwidth usage; a "validation" mechanism is used for this purpose 174 (see Section 2.4). 176 1.2. Terminology 178 This specification uses a number of terms to refer to the roles 179 played by participants in, and objects of, HTTP caching. 181 cacheable 183 A response is cacheable if a cache is allowed to store a copy of 184 the response message for use in answering subsequent requests. 185 Even when a response is cacheable, there may be additional 186 constraints on whether a cache can use the cached copy to satisfy 187 a particular request. 189 explicit expiration time 191 The time at which the origin server intends that an entity should 192 no longer be returned by a cache without further validation. 194 heuristic expiration time 196 An expiration time assigned by a cache when no explicit expiration 197 time is available. 199 age 201 The age of a response is the time since it was sent by, or 202 successfully validated with, the origin server. 204 first-hand 206 A response is first-hand if the freshness model is not in use; 207 i.e., its age is 0. 209 freshness lifetime 211 The length of time between the generation of a response and its 212 expiration time. 214 fresh 216 A response is fresh if its age has not yet exceeded its freshness 217 lifetime. 219 stale 221 A response is stale if its age has passed its freshness lifetime 222 (either explicit or heuristic). 224 validator 226 A protocol element (e.g., an entity tag or a Last-Modified time) 227 that is used to find out whether a stored response is an 228 equivalent copy of an entity. 230 shared cache 232 A cache that is accessible to more than one user. A non-shared 233 cache is dedicated to a single user. 235 1.3. Requirements 237 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 238 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 239 document are to be interpreted as described in [RFC2119]. 241 An implementation is not compliant if it fails to satisfy one or more 242 of the MUST or REQUIRED level requirements for the protocols it 243 implements. An implementation that satisfies all the MUST or 244 REQUIRED level and all the SHOULD level requirements for its 245 protocols is said to be "unconditionally compliant"; one that 246 satisfies all the MUST level requirements but not all the SHOULD 247 level requirements for its protocols is said to be "conditionally 248 compliant." 250 1.4. Syntax Notation 252 This specification uses the ABNF syntax defined in Section 1.2 of 253 [Part1] (which extends the syntax defined in [RFC5234] with a list 254 rule). Appendix B shows the collected ABNF, with the list rule 255 expanded. 257 The following core rules are included by reference, as defined in 258 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 259 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 260 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 261 sequence of data), SP (space), VCHAR (any visible USASCII character), 262 and WSP (whitespace). 264 1.4.1. Core Rules 266 The core rules below are defined in Section 1.2.2 of [Part1]: 268 quoted-string = 269 token = 270 OWS = 272 1.4.2. ABNF Rules defined in other Parts of the Specification 274 The ABNF rules below are defined in other parts: 276 field-name = 277 HTTP-date = 278 port = 279 pseudonym = 280 uri-host = 282 2. Cache Operation 284 2.1. Response Cacheability 286 A cache MUST NOT store a response to any request, unless: 288 o The request method is defined as being cacheable, and 290 o the "no-store" cache directive (see Section 3.2) does not appear 291 in request or response headers, and 293 o the "private" cache response directive (see Section 3.2 does not 294 appear in the response, if the cache is shared, and 296 o the "Authorization" header (see Section 3.1 of [Part7]) does not 297 appear in the request, if the cache is shared (unless the "public" 298 directive is present; see Section 3.2), and 300 o the cache understands partial responses, if the response is 301 partial or incomplete (see Section 2.1.1). 303 Note that in normal operation, most caches will not store a response 304 that has neither a cache validator nor an explicit expiration time, 305 as such responses are not usually useful to store. However, caches 306 are not prohibited from storing such responses. 308 2.1.1. Storing Partial and Incomplete Responses 310 A cache that receives an incomplete response (for example, with fewer 311 bytes of data than specified in a Content-Length header) can store 312 the response, but MUST treat it as a partial response [Part5]. 313 Partial responses can be combined as described in Section 4 of 314 [Part5]; the result might be a full response or might still be 315 partial. A cache MUST NOT return a partial response to a client 316 without explicitly marking it as such using the 206 (Partial Content) 317 status code. 319 A cache that does not support the Range and Content-Range headers 320 MUST NOT store incomplete or partial responses. 322 2.2. Constructing Responses from Caches 324 For a presented request, a cache MUST NOT return a stored response, 325 unless: 327 o The presented Request-URI and that of the stored response match 328 ([[TODO-Request-URI: Need to find a new term for this, as Part 1 329 doesn't define Request-URI anymore; the new term request-target 330 does not work for this. (see 331 )]]), and 333 o the request method associated with the stored response allows it 334 to be used for the presented request, and 336 o selecting request-headers nominated by the stored response (if 337 any) match those presented (see Section 2.6), and 339 o the presented request and stored response are free from directives 340 that would prevent its use (see Section 3.2 and Section 3.4), and 342 o the stored response is either: 344 * fresh (see Section 2.3), or 346 * allowed to be served stale (see Section 2.3.3), or 348 * successfully validated (see Section 2.4). 350 [[TODO-method-cacheability: define method cacheability for GET, HEAD 351 and POST in p2-semantics.]] 353 When a stored response is used to satisfy a request, caches MUST 354 include a single Age header field (Section 3.1) in the response with 355 a value equal to the stored response's current_age; see 356 Section 2.3.2. [[anchor1: DISCUSS: this currently includes 357 successfully validated responses.]] 359 Requests with methods that are unsafe (Section 7.1.1 of [Part2]) MUST 360 be written through the cache to the origin server; i.e., A cache must 361 not reply to such a request before having forwarded the request and 362 having received a corresponding response. 364 Also, note that unsafe requests might invalidate already stored 365 responses; see Section 2.5. 367 Caches MUST use the most recent response (as determined by the Date 368 header) when more than one suitable response is stored. They can 369 also forward a request with "Cache-Control: max-age=0" or "Cache- 370 Control: no-cache" to disambiguate which response to use. 372 [[TODO-header-properties: end-to-end and hop-by-hop headers, non- 373 modifiable headers removed; re-spec in p1]] 375 2.3. Freshness Model 377 When a response is "fresh" in the cache, it can be used to satisfy 378 subsequent requests without contacting the origin server, thereby 379 improving efficiency. 381 The primary mechanism for determining freshness is for an origin 382 server to provide an explicit expiration time in the future, using 383 either the Expires header (Section 3.3) or the max-age response cache 384 directive (Section 3.2.2). Generally, origin servers will assign 385 future explicit expiration times to responses in the belief that the 386 entity is not likely to change in a semantically significant way 387 before the expiration time is reached. 389 If an origin server wishes to force a cache to validate every 390 request, it can assign an explicit expiration time in the past. This 391 means that the response is always stale, so that caches should 392 validate it before using it for subsequent requests. [[anchor2: This 393 wording may cause confusion, because the response may still be served 394 stale.]] 396 Since origin servers do not always provide explicit expiration times, 397 HTTP caches may also assign heuristic expiration times when they are 398 not specified, employing algorithms that use other header values 399 (such as the Last-Modified time) to estimate a plausible expiration 400 time. The HTTP/1.1 specification does not provide specific 401 algorithms, but does impose worst-case constraints on their results. 403 The calculation to determine if a response is fresh is: 405 response_is_fresh = (freshness_lifetime > current_age) 407 The freshness_lifetime is defined in Section 2.3.1; the current_age 408 is defined in Section 2.3.2. 410 Additionally, clients may need to influence freshness calculation. 411 They can do this using several request cache directives, with the 412 effect of either increasing or loosening constraints on freshness. 413 See Section 3.2.1. 415 [[anchor3: ISSUE: there are not requirements directly applying to 416 cache-request-directives and freshness.]] 418 Note that freshness applies only to cache operation; it cannot be 419 used to force a user agent to refresh its display or reload a 420 resource. See Section 4 for an explanation of the difference between 421 caches and history mechanisms. 423 2.3.1. Calculating Freshness Lifetime 425 A cache can calculate the freshness lifetime (denoted as 426 freshness_lifetime) of a response by using the first match of: 428 o If the cache is shared and the s-maxage response cache directive 429 (Section 3.2.2) is present, use its value, or 431 o If the max-age response cache directive (Section 3.2.2) is 432 present, use its value, or 434 o If the Expires response header (Section 3.3) is present, use its 435 value minus the value of the Date response header, or 437 o Otherwise, no explicit expiration time is present in the response, 438 but a heuristic may be used; see Section 2.3.1.1. 440 Note that this calculation is not vulnerable to clock skew, since all 441 of the information comes from the origin server. 443 2.3.1.1. Calculating Heuristic Freshness 445 If no explicit expiration time is present in a stored response that 446 has a status code of 200, 203, 206, 300, 301 or 410, a heuristic 447 expiration time can be calculated. Heuristics MUST NOT be used for 448 other response status codes. 450 When a heuristic is used to calculate freshness lifetime, the cache 451 SHOULD attach a Warning header with a 113 warn-code to the response 452 if its current_age is more than 24 hours and such a warning is not 453 already present. 455 Also, if the response has a Last-Modified header (Section 6.6 of 456 [Part4]), the heuristic expiration value SHOULD be no more than some 457 fraction of the interval since that time. A typical setting of this 458 fraction might be 10%. 460 [[anchor4: REVIEW: took away HTTP/1.0 query string heuristic 461 uncacheability.]] 463 2.3.2. Calculating Age 465 HTTP/1.1 uses the Age response-header to convey the estimated age of 466 the response message when obtained from a cache. The Age field value 467 is the cache's estimate of the amount of time since the response was 468 generated or validated by the origin server. In essence, the Age 469 value is the sum of the time that the response has been resident in 470 each of the caches along the path from the origin server, plus the 471 amount of time it has been in transit along network paths. 473 The term "age_value" denotes the value of the Age header, in a form 474 appropriate for arithmetic operations. 476 HTTP/1.1 requires origin servers to send a Date header, if possible, 477 with every response, giving the time at which the response was 478 generated (see Section 9.3 of [Part1]). The term "date_value" 479 denotes the value of the Date header, in a form appropriate for 480 arithmetic operations. 482 The term "now" means "the current value of the clock at the host 483 performing the calculation." Hosts that use HTTP, but especially 484 hosts running origin servers and caches, SHOULD use NTP [RFC1305] or 485 some similar protocol to synchronize their clocks to a globally 486 accurate time standard. 488 A response's age can be calculated in two entirely independent ways: 490 1. now minus date_value, if the local clock is reasonably well 491 synchronized to the origin server's clock. If the result is 492 negative, the result is replaced by zero. 494 2. age_value, if all of the caches along the response path implement 495 HTTP/1.1. 497 These are combined as 499 corrected_received_age = max(now - date_value, age_value) 501 When an Age value is received, it MUST be interpreted relative to the 502 time the request was initiated, not the time that the response was 503 received. 505 corrected_initial_age = corrected_received_age 506 + (now - request_time) 508 where "request_time" is the time (according to the local clock) when 509 the request that elicited this response was sent. 511 The current_age of a stored response can then be calculated by adding 512 the amount of time (in seconds) since the stored response was last 513 validated by the origin server to the corrected_initial_age. 515 In summary: 517 age_value - Age header field-value received with the response 518 date_value - Date header field-value received with the response 519 request_time - local time when the cache made the request 520 resulting in the stored response 521 response_time - local time when the cache received the response 522 now - current local time 524 apparent_age = max(0, response_time - date_value); 525 corrected_received_age = max(apparent_age, age_value); 526 response_delay = response_time - request_time; 527 corrected_initial_age = corrected_received_age + response_delay; 528 resident_time = now - response_time; 529 current_age = corrected_initial_age + resident_time; 531 2.3.3. Serving Stale Responses 533 A "stale" response is one that either has explicit expiry 534 information, or is allowed to have heuristic expiry calculated, but 535 is not fresh according to the calculations in Section 2.3. 537 Caches MUST NOT return a stale response if it is prohibited by an 538 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" 539 cache directive, a "must-revalidate" cache-response-directive, or an 540 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 541 see Section 3.2.2). 543 Caches SHOULD NOT return stale responses unless they are disconnected 544 (i.e., it cannot contact the origin server or otherwise find a 545 forward path) or otherwise explicitly allowed (e.g., the max-stale 546 request directive; see Section 3.2.1). 548 Stale responses SHOULD have a Warning header with the 110 warn-code 549 (see Section 3.6). Likewise, the 112 warn-code SHOULD be sent on 550 stale responses if the cache is disconnected. 552 If a cache receives a first-hand response (either an entire response, 553 or a 304 (Not Modified) response) that it would normally forward to 554 the requesting client, and the received response is no longer fresh, 555 the cache SHOULD forward it to the requesting client without adding a 556 new Warning (but without removing any existing Warning headers). A 557 cache SHOULD NOT attempt to validate a response simply because that 558 response became stale in transit. 560 2.4. Validation Model 562 When a cache has one or more stored responses for a requested URI, 563 but cannot serve any of them (e.g., because they are not fresh, or 564 one cannot be selected; see Section 2.6), it can use the conditional 565 request mechanism [Part4] in the forwarded request to give the origin 566 server an opportunity to both select a valid stored response to be 567 used, and to update it. This process is known as "validating" or 568 "revalidating" the stored response. 570 When sending such a conditional request, the cache SHOULD add an If- 571 Modified-Since header whose value is that of the Last-Modified header 572 from the selected (see Section 2.6) stored response, if available. 574 Additionally, the cache SHOULD add an If-None-Match header whose 575 value is that of the ETag header(s) from all responses stored for the 576 requested URI, if present. However, if any of the stored responses 577 contains only partial content, its entity-tag SHOULD NOT be included 578 in the If-None-Match header field unless the request is for a range 579 that would be fully satisfied by that stored response. 581 A 304 (Not Modified) response status code indicates that the stored 582 response can be updated and reused; see Section 2.7. 584 A full response (i.e., one with a response body) indicates that none 585 of the stored responses nominated in the conditional request is 586 suitable. Instead, the full response is used both to satisfy the 587 request and replace the stored response. [[anchor5: Should there be a 588 requirement here?]] 590 If a cache receives a 5xx response while attempting to validate a 591 response, it MAY either forward this response to the requesting 592 client, or act as if the server failed to respond. In the latter 593 case, it MAY return a previously stored response (see Section 2.3.3). 595 2.5. Request Methods that Invalidate 597 Because unsafe methods (Section 7.1.1 of [Part2]) have the potential 598 for changing state on the origin server, intervening caches can use 599 them to keep their contents up-to-date. 601 The following HTTP methods MUST cause a cache to invalidate the 602 Request-URI as well as the URI(s) in the Location and Content- 603 Location headers (if present): 605 o PUT 607 o DELETE 609 o POST 611 An invalidation based on a URI from a Location or Content-Location 612 header MUST NOT be performed if the host part of that URI differs 613 from the host part in the Request-URI. This helps prevent denial of 614 service attacks. 616 [[anchor6: TODO: "host part" needs to be specified better.]] 618 A cache that passes through requests for methods it does not 619 understand SHOULD invalidate the Request-URI. 621 Here, "invalidate" means that the cache will either remove all stored 622 responses related to the Request-URI, or will mark these as "invalid" 623 and in need of a mandatory validation before they can be returned in 624 response to a subsequent request. 626 Note that this does not guarantee that all appropriate responses are 627 invalidated. For example, the request that caused the change at the 628 origin server might not have gone through the cache where a response 629 is stored. 631 [[anchor7: TODO: specify that only successful (2xx, 3xx?) responses 632 invalidate.]] 634 2.6. Caching Negotiated Responses 636 When a cache receives a request that can be satisfied by a stored 637 response that has a Vary header field (Section 3.5), it MUST NOT use 638 that response unless all of the selecting request-headers nominated 639 by the Vary header match in both the original request (i.e., that 640 associated with the stored response), and the presented request. 642 The selecting request-headers from two requests are defined to match 643 if and only if the selecting request-headers in the first request can 644 be transformed to the selecting request-headers in the second request 645 by adding or removing linear white space [[anchor8: [ref]]] at places 646 where this is allowed by the corresponding ABNF, and/or combining 647 multiple message-header fields with the same field name following the 648 rules about header fields in Section 3.2 of [Part1]. 650 If a header field is absent from a request, it can only match another 651 request if it is also absent there. 653 A Vary header field-value of "*" always fails to match, and 654 subsequent requests to that resource can only be properly interpreted 655 by the origin server. 657 The stored response with matching selecting request-headers is known 658 as the selected response. 660 If no selected response is available, the cache MAY forward the 661 presented request to the origin server in a conditional request; see 662 Section 2.4. 664 2.7. Combining Responses 666 When a cache receives a 304 (Not Modified) response or a 206 (Partial 667 Content) response (in this section, the "new" response"), it needs to 668 created an updated response by combining the stored response with the 669 new one, so that the updated response can be used to satisfy the 670 request. 672 If the new response contains an ETag, it identifies the stored 673 response to use. [[anchor9: may need language about Content-Location 674 here]][[anchor10: cover case where INM with multiple etags was sent]] 676 If the status code is 206 (partial content), both the stored and new 677 responses MUST have validators, and those validators MUST match using 678 the strong comparison function (see Section 4 of [Part4]). 679 Otherwise, the responses MUST NOT be combined. 681 The stored response headers are used as those of the updated 682 response, except that 684 o any stored Warning headers with warn-code 1xx (see Section 3.6) 685 MUST be deleted from the stored response and the updated response. 687 o any stored Warning headers with warn-code 2xx MUST be retained in 688 the stored response and the updated response. 690 o any headers provided in the new response MUST replace the 691 corresponding headers from the stored response. 693 If a header field-name in the new response matches more than one 694 header in the stored response, all such stored headers MUST be 695 replaced. 697 The updated response can [[[[anchor11: requirement?]]]] be used to 698 replace the stored response in cache. In the case of a 206 response, 699 the combined entity-body MAY be stored. 701 [[anchor12: ISSUE: discuss how to handle HEAD updates]] 703 3. Header Field Definitions 705 This section defines the syntax and semantics of HTTP/1.1 header 706 fields related to caching. 708 For entity-header fields, both sender and recipient refer to either 709 the client or the server, depending on who sends and who receives the 710 entity. 712 3.1. Age 714 The "Age" response-header field conveys the sender's estimate of the 715 amount of time since the response was generated or successfully 716 validated at the origin server. Age values are calculated as 717 specified in Section 2.3.2. 719 Age = "Age" ":" OWS Age-v 720 Age-v = delta-seconds 722 Age field-values are non-negative integers, representing time in 723 seconds. 725 delta-seconds = 1*DIGIT 727 If a cache receives a value larger than the largest positive integer 728 it can represent, or if any of its age calculations overflows, it 729 MUST transmit an Age header with a field-value of 2147483648 (2^31). 730 Caches SHOULD use an arithmetic type of at least 31 bits of range. 732 The presence of an Age header field in a response implies that a 733 response is not first-hand. However, the converse is not true, since 734 HTTP/1.0 caches may not implement the Age header field. 736 3.2. Cache-Control 738 The "Cache-Control" general-header field is used to specify 739 directives that MUST be obeyed by all caches along the request/ 740 response chain. Such cache directives are unidirectional in that the 741 presence of a directive in a request does not imply that the same 742 directive is to be given in the response. 744 Note that HTTP/1.0 caches might not implement Cache-Control and 745 might only implement Pragma: no-cache (see Section 3.4). 747 Cache directives MUST be passed through by a proxy or gateway 748 application, regardless of their significance to that application, 749 since the directives might be applicable to all recipients along the 750 request/response chain. It is not possible to target a directive to 751 a specific cache. 753 Cache-Control = "Cache-Control" ":" OWS Cache-Control-v 754 Cache-Control-v = 1#cache-directive 756 cache-directive = cache-request-directive 757 / cache-response-directive 759 cache-extension = token [ "=" ( token / quoted-string ) ] 761 3.2.1. Request Cache-Control Directives 763 cache-request-directive = 764 "no-cache" 765 / "no-store" 766 / "max-age" "=" delta-seconds 767 / "max-stale" [ "=" delta-seconds ] 768 / "min-fresh" "=" delta-seconds 769 / "no-transform" 770 / "only-if-cached" 771 / cache-extension 773 no-cache 775 The no-cache request directive indicates that a stored response 776 MUST NOT be used to satisfy the request without successful 777 validation on the origin server. 779 no-store 781 The no-store request directive indicates that a cache MUST NOT 782 store any part of either this request or any response to it. This 783 directive applies to both non-shared and shared caches. "MUST NOT 784 store" in this context means that the cache MUST NOT intentionally 785 store the information in non-volatile storage, and MUST make a 786 best-effort attempt to remove the information from volatile 787 storage as promptly as possible after forwarding it. 789 This directive is NOT a reliable or sufficient mechanism for 790 ensuring privacy. In particular, malicious or compromised caches 791 might not recognize or obey this directive, and communications 792 networks may be vulnerable to eavesdropping. 794 max-age 796 The max-age request directive indicates that the client is willing 797 to accept a response whose age is no greater than the specified 798 time in seconds. Unless max-stale directive is also included, the 799 client is not willing to accept a stale response. 801 max-stale 803 The max-stale request directive indicates that the client is 804 willing to accept a response that has exceeded its expiration 805 time. If max-stale is assigned a value, then the client is 806 willing to accept a response that has exceeded its expiration time 807 by no more than the specified number of seconds. If no value is 808 assigned to max-stale, then the client is willing to accept a 809 stale response of any age. [[anchor13: of any staleness? --mnot]] 811 min-fresh 813 The min-fresh request directive indicates that the client is 814 willing to accept a response whose freshness lifetime is no less 815 than its current age plus the specified time in seconds. That is, 816 the client wants a response that will still be fresh for at least 817 the specified number of seconds. 819 no-transform 821 The no-transform request directive indicates that an intermediate 822 cache or proxy MUST NOT change the Content-Encoding, Content-Range 823 or Content-Type request headers, nor the request entity-body. 825 only-if-cached 827 The only-if-cached request directive indicates that the client 828 only wishes to return a stored response. If it receives this 829 directive, a cache SHOULD either respond using a stored response 830 that is consistent with the other constraints of the request, or 831 respond with a 504 (Gateway Timeout) status. If a group of caches 832 is being operated as a unified system with good internal 833 connectivity, such a request MAY be forwarded within that group of 834 caches. 836 3.2.2. Response Cache-Control Directives 838 cache-response-directive = 839 "public" 840 / "private" [ "=" DQUOTE 1#field-name DQUOTE ] 841 / "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] 842 / "no-store" 843 / "no-transform" 844 / "must-revalidate" 845 / "proxy-revalidate" 846 / "max-age" "=" delta-seconds 847 / "s-maxage" "=" delta-seconds 848 / cache-extension 850 public 852 The public response directive indicates that the response MAY be 853 cached, even if it would normally be non-cacheable or cacheable 854 only within a non-shared cache. (See also Authorization, Section 855 3.1 of [Part7], for additional details.) 857 private 859 The private response directive indicates that the response message 860 is intended for a single user and MUST NOT be stored by a shared 861 cache. A private (non-shared) cache MAY store the response. 863 If the private response directive specifies one or more field- 864 names, this requirement is limited to the field-values associated 865 with the listed response headers. That is, the specified field- 866 names(s) MUST NOT be stored by a shared cache, whereas the 867 remainder of the response message MAY be. 869 Note: This usage of the word private only controls where the 870 response may be stored, and cannot ensure the privacy of the 871 message content. Also, private response directives with field- 872 names are often handled by implementations as if an unqualified 873 private directive was recieved; i.e., the special handling for the 874 qualified form is not widely implemented. 876 no-cache 878 The no-cache response directive indicates that the response MUST 879 NOT be used to satisfy a subsequent request without successful 880 validation on the origin server. This allows an origin server to 881 prevent caching even by caches that have been configured to return 882 stale responses. 884 If the no-cache response directive specifies one or more field- 885 names, this requirement is limited to the field-values associated 886 with the listed response headers. That is, the specified field- 887 name(s) MUST NOT be sent in the response to a subsequent request 888 without successful validation on the origin server. This allows 889 an origin server to prevent the re-use of certain header fields in 890 a response, while still allowing caching of the rest of the 891 response. 893 Note: Most HTTP/1.0 caches will not recognize or obey this 894 directive. Also, no-cache response directives with field-names 895 are often handled by implementations as if an unqualified no-cache 896 directive was recieved; i.e., the special handling for the 897 qualified form is not widely implemented. 899 no-store 901 The no-store response directive indicates that a cache MUST NOT 902 store any part of either the immediate request or response. This 903 directive applies to both non-shared and shared caches. "MUST NOT 904 store" in this context means that the cache MUST NOT intentionally 905 store the information in non-volatile storage, and MUST make a 906 best-effort attempt to remove the information from volatile 907 storage as promptly as possible after forwarding it. 909 This directive is NOT a reliable or sufficient mechanism for 910 ensuring privacy. In particular, malicious or compromised caches 911 might not recognize or obey this directive, and communications 912 networks may be vulnerable to eavesdropping. 914 must-revalidate 916 The must-revalidate response directive indicates that once it has 917 become stale, the response MUST NOT be used to satisfy subsequent 918 requests without successful validation on the origin server. 920 The must-revalidate directive is necessary to support reliable 921 operation for certain protocol features. In all circumstances an 922 HTTP/1.1 cache MUST obey the must-revalidate directive; in 923 particular, if the cache cannot reach the origin server for any 924 reason, it MUST generate a 504 (Gateway Timeout) response. 926 Servers SHOULD send the must-revalidate directive if and only if 927 failure to validate a request on the entity could result in 928 incorrect operation, such as a silently unexecuted financial 929 transaction. 931 proxy-revalidate 932 The proxy-revalidate response directive has the same meaning as 933 the must-revalidate response directive, except that it does not 934 apply to non-shared caches. 936 max-age 938 The max-age response directive indicates that response is to be 939 considered stale after its age is greater than the specified 940 number of seconds. 942 s-maxage 944 The s-maxage response directive indicates that, in shared caches, 945 the maximum age specified by this directive overrides the maximum 946 age specified by either the max-age directive or the Expires 947 header. The s-maxage directive also implies the semantics of the 948 proxy-revalidate response directive. 950 no-transform 952 The no-transform response directive indicates that an intermediate 953 cache or proxy MUST NOT change the Content-Encoding, Content-Range 954 or Content-Type response headers, nor the response entity-body. 956 3.2.3. Cache Control Extensions 958 The Cache-Control header field can be extended through the use of one 959 or more cache-extension tokens, each with an optional value. 960 Informational extensions (those that do not require a change in cache 961 behavior) can be added without changing the semantics of other 962 directives. Behavioral extensions are designed to work by acting as 963 modifiers to the existing base of cache directives. Both the new 964 directive and the standard directive are supplied, such that 965 applications that do not understand the new directive will default to 966 the behavior specified by the standard directive, and those that 967 understand the new directive will recognize it as modifying the 968 requirements associated with the standard directive. In this way, 969 extensions to the cache-control directives can be made without 970 requiring changes to the base protocol. 972 This extension mechanism depends on an HTTP cache obeying all of the 973 cache-control directives defined for its native HTTP-version, obeying 974 certain extensions, and ignoring all directives that it does not 975 understand. 977 For example, consider a hypothetical new response directive called 978 "community" that acts as a modifier to the private directive. We 979 define this new directive to mean that, in addition to any non-shared 980 cache, any cache that is shared only by members of the community 981 named within its value may cache the response. An origin server 982 wishing to allow the UCI community to use an otherwise private 983 response in their shared cache(s) could do so by including 985 Cache-Control: private, community="UCI" 987 A cache seeing this header field will act correctly even if the cache 988 does not understand the community cache-extension, since it will also 989 see and understand the private directive and thus default to the safe 990 behavior. 992 Unrecognized cache directives MUST be ignored; it is assumed that any 993 cache directive likely to be unrecognized by an HTTP/1.1 cache will 994 be combined with standard directives (or the response's default 995 cacheability) such that the cache behavior will remain minimally 996 correct even if the cache does not understand the extension(s). 998 3.3. Expires 1000 The "Expires" entity-header field gives the date/time after which the 1001 response is considered stale. See Section 2.3 for further discussion 1002 of the freshness model. 1004 The presence of an Expires field does not imply that the original 1005 resource will change or cease to exist at, before, or after that 1006 time. 1008 The field-value is an absolute date and time as defined by HTTP-date 1009 in Section 6.1 of [Part1]; it MUST be sent in rfc1123-date format. 1011 Expires = "Expires" ":" OWS Expires-v 1012 Expires-v = HTTP-date 1014 For example 1016 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1018 Note: if a response includes a Cache-Control field with the max- 1019 age directive (see Section 3.2.2), that directive overrides the 1020 Expires field. Likewise, the s-maxage directive overrides Expires 1021 in shared caches. 1023 HTTP/1.1 servers SHOULD NOT send Expires dates more than one year in 1024 the future. 1026 HTTP/1.1 clients and caches MUST treat other invalid date formats, 1027 especially including the value "0", as in the past (i.e., "already 1028 expired"). 1030 3.4. Pragma 1032 The "Pragma" general-header field is used to include implementation- 1033 specific directives that might apply to any recipient along the 1034 request/response chain. All pragma directives specify optional 1035 behavior from the viewpoint of the protocol; however, some systems 1036 MAY require that behavior be consistent with the directives. 1038 Pragma = "Pragma" ":" OWS Pragma-v 1039 Pragma-v = 1#pragma-directive 1040 pragma-directive = "no-cache" / extension-pragma 1041 extension-pragma = token [ "=" ( token / quoted-string ) ] 1043 When the no-cache directive is present in a request message, an 1044 application SHOULD forward the request toward the origin server even 1045 if it has a cached copy of what is being requested. This pragma 1046 directive has the same semantics as the no-cache response directive 1047 (see Section 3.2.2) and is defined here for backward compatibility 1048 with HTTP/1.0. Clients SHOULD include both header fields when a no- 1049 cache request is sent to a server not known to be HTTP/1.1 compliant. 1050 HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had 1051 sent "Cache-Control: no-cache". 1053 Note: because the meaning of "Pragma: no-cache" as a response- 1054 header field is not actually specified, it does not provide a 1055 reliable replacement for "Cache-Control: no-cache" in a response. 1057 This mechanism is deprecated; no new Pragma directives will be 1058 defined in HTTP. 1060 3.5. Vary 1062 The "Vary" response-header field conveys the set of request-header 1063 fields that were used to select the representation. 1065 Caches use this information, in part, to determine whether a stored 1066 response can be used to satisdy a given request; see Section 2.6. 1067 determines, while the response is fresh, whether a cache is permitted 1068 to use the response to reply to a subsequent request without 1069 validation; see Section 2.6. 1071 In uncacheable or stale responses, the Vary field value advises the 1072 user agent about the criteria that were used to select the 1073 representation. 1075 Vary = "Vary" ":" OWS Vary-v 1076 Vary-v = "*" / 1#field-name 1078 The set of header fields named by the Vary field value is known as 1079 the selecting request-headers. 1081 Servers SHOULD include a Vary header field with any cacheable 1082 response that is subject to server-driven negotiation. Doing so 1083 allows a cache to properly interpret future requests on that resource 1084 and informs the user agent about the presence of negotiation on that 1085 resource. A server MAY include a Vary header field with a non- 1086 cacheable response that is subject to server-driven negotiation, 1087 since this might provide the user agent with useful information about 1088 the dimensions over which the response varies at the time of the 1089 response. 1091 A Vary field value of "*" signals that unspecified parameters not 1092 limited to the request-headers (e.g., the network address of the 1093 client), play a role in the selection of the response representation; 1094 therefore, a cache cannot determine whether this response is 1095 appropriate. The "*" value MUST NOT be generated by a proxy server; 1096 it may only be generated by an origin server. 1098 The field-names given are not limited to the set of standard request- 1099 header fields defined by this specification. Field names are case- 1100 insensitive. 1102 3.6. Warning 1104 The "Warning" general-header field is used to carry additional 1105 information about the status or transformation of a message that 1106 might not be reflected in the message. This information is typically 1107 used to warn about possible incorrectness introduced by caching 1108 operations or transformations applied to the entity body of the 1109 message. 1111 Warnings can be used for other purposes, both cache-related and 1112 otherwise. The use of a warning, rather than an error status code, 1113 distinguish these responses from true failures. 1115 Warning headers can in general be applied to any message, however 1116 some warn-codes are specific to caches and can only be applied to 1117 response messages. 1119 Warning = "Warning" ":" OWS Warning-v 1120 Warning-v = 1#warning-value 1122 warning-value = warn-code SP warn-agent SP warn-text 1123 [SP warn-date] 1125 warn-code = 3DIGIT 1126 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1127 ; the name or pseudonym of the server adding 1128 ; the Warning header, for use in debugging 1129 warn-text = quoted-string 1130 warn-date = DQUOTE HTTP-date DQUOTE 1132 Multiple warnings can be attached to a response (either by the origin 1133 server or by a cache), including multiple warnings with the same code 1134 number, only differing in warn-text. 1136 When this occurs, the user agent SHOULD inform the user of as many of 1137 them as possible, in the order that they appear in the response. 1139 Systems that generate multiple Warning headers SHOULD order them with 1140 this user agent behavior in mind. New Warning headers SHOULD be 1141 added after any existing Warning headers. 1143 Warnings are assigned three digit warn-codes. The first digit 1144 indicates whether the Warning is required to be deleted from a stored 1145 response after validation: 1147 o 1xx Warnings describe the freshness or validation status of the 1148 response, and so MUST be deleted by caches after validation. They 1149 can only be generated by a cache when validating a cached entry, 1150 and MUST NOT be generated in any other situation. 1152 o 2xx Warnings describe some aspect of the entity body or entity 1153 headers that is not rectified by a validation (for example, a 1154 lossy compression of the entity bodies) and MUST NOT be deleted by 1155 caches after validation, unless a full response is returned, in 1156 which case they MUST be. 1158 If an implementation sends a message with one or more Warning headers 1159 to a receiver whose version is HTTP/1.0 or lower, then the sender 1160 MUST include in each warning-value a warn-date that matches the Date 1161 header in the message. 1163 If an implementation receives a message with a warning-value that 1164 includes a warn-date, and that warn-date is different from the Date 1165 value in the response, then that warning-value MUST be deleted from 1166 the message before storing, forwarding, or using it. (preventing the 1167 consequences of naive caching of Warning header fields.) If all of 1168 the warning-values are deleted for this reason, the Warning header 1169 MUST be deleted as well. 1171 The following warn-codes are defined by this specification, each with 1172 a recommended warn-text in English, and a description of its meaning. 1174 110 Response is stale 1176 SHOULD be included whenever the returned response is stale. 1178 111 Revalidation failed 1180 SHOULD be included if a cache returns a stale response because an 1181 attempt to validate the response failed, due to an inability to 1182 reach the server. 1184 112 Disconnected operation 1186 SHOULD be included if the cache is intentionally disconnected from 1187 the rest of the network for a period of time. 1189 113 Heuristic expiration 1191 SHOULD be included if the cache heuristically chose a freshness 1192 lifetime greater than 24 hours and the response's age is greater 1193 than 24 hours. 1195 199 Miscellaneous warning 1197 The warning text can include arbitrary information to be presented 1198 to a human user, or logged. A system receiving this warning MUST 1199 NOT take any automated action, besides presenting the warning to 1200 the user. 1202 214 Transformation applied 1204 MUST be added by an intermediate cache or proxy if it applies any 1205 transformation changing the content-coding (as specified in the 1206 Content-Encoding header) or media-type (as specified in the 1207 Content-Type header) of the response, or the entity-body of the 1208 response, unless this Warning code already appears in the 1209 response. 1211 299 Miscellaneous persistent warning 1213 The warning text can include arbitrary information to be presented 1214 to a human user, or logged. A system receiving this warning MUST 1215 NOT take any automated action. 1217 4. History Lists 1219 User agents often have history mechanisms, such as "Back" buttons and 1220 history lists, that can be used to redisplay an entity retrieved 1221 earlier in a session. 1223 History mechanisms and caches are different. In particular history 1224 mechanisms SHOULD NOT try to show a correct view of the current state 1225 of a resource. Rather, a history mechanism is meant to show exactly 1226 what the user saw at the time when the resource was retrieved. 1228 By default, an expiration time does not apply to history mechanisms. 1229 If the entity is still in storage, a history mechanism SHOULD display 1230 it even if the entity has expired, unless the user has specifically 1231 configured the agent to refresh expired history documents. 1233 This is not to be construed to prohibit the history mechanism from 1234 telling the user that a view might be stale. 1236 Note: if history list mechanisms unnecessarily prevent users from 1237 viewing stale resources, this will tend to force service authors 1238 to avoid using HTTP expiration controls and cache controls when 1239 they would otherwise like to. Service authors may consider it 1240 important that users not be presented with error messages or 1241 warning messages when they use navigation controls (such as BACK) 1242 to view previously fetched resources. Even though sometimes such 1243 resources ought not be cached, or ought to expire quickly, user 1244 interface considerations may force service authors to resort to 1245 other means of preventing caching (e.g. "once-only" URLs) in order 1246 not to suffer the effects of improperly functioning history 1247 mechanisms. 1249 5. IANA Considerations 1251 5.1. Message Header Registration 1253 The Message Header Registry located at should be 1255 updated with the permanent registrations below (see [RFC3864]): 1257 +-------------------+----------+----------+-------------+ 1258 | Header Field Name | Protocol | Status | Reference | 1259 +-------------------+----------+----------+-------------+ 1260 | Age | http | standard | Section 3.1 | 1261 | Cache-Control | http | standard | Section 3.2 | 1262 | Expires | http | standard | Section 3.3 | 1263 | Pragma | http | standard | Section 3.4 | 1264 | Vary | http | standard | Section 3.5 | 1265 | Warning | http | standard | Section 3.6 | 1266 +-------------------+----------+----------+-------------+ 1268 The change controller is: "IETF (iesg@ietf.org) - Internet 1269 Engineering Task Force". 1271 6. Security Considerations 1273 Caches expose additional potential vulnerabilities, since the 1274 contents of the cache represent an attractive target for malicious 1275 exploitation. Because cache contents persist after an HTTP request 1276 is complete, an attack on the cache can reveal information long after 1277 a user believes that the information has been removed from the 1278 network. Therefore, cache contents should be protected as sensitive 1279 information. 1281 7. Acknowledgments 1283 Much of the content and presentation of the caching design is due to 1284 suggestions and comments from individuals including: Shel Kaphan, 1285 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 1287 8. References 1289 8.1. Normative References 1291 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1292 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1293 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 1294 and Message Parsing", draft-ietf-httpbis-p1-messaging-08 1295 (work in progress), October 2009. 1297 [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1298 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1299 and J. Reschke, Ed., "HTTP/1.1, part 2: Message 1300 Semantics", draft-ietf-httpbis-p2-semantics-08 (work in 1301 progress), October 2009. 1303 [Part3] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1304 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1305 and J. Reschke, Ed., "HTTP/1.1, part 3: Message Payload 1306 and Content Negotiation", draft-ietf-httpbis-p3-payload-08 1307 (work in progress), October 2009. 1309 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1310 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1311 and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional 1312 Requests", draft-ietf-httpbis-p4-conditional-08 (work in 1313 progress), October 2009. 1315 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1316 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1317 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 1318 Partial Responses", draft-ietf-httpbis-p5-range-08 (work 1319 in progress), October 2009. 1321 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1322 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1323 and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", 1324 draft-ietf-httpbis-p7-auth-08 (work in progress), 1325 October 2009. 1327 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1328 Requirement Levels", BCP 14, RFC 2119, March 1997. 1330 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1331 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1333 8.2. Informative References 1335 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1336 Specification, Implementation", RFC 1305, March 1992. 1338 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1339 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1340 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1342 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1343 Procedures for Message Header Fields", BCP 90, RFC 3864, 1344 September 2004. 1346 Appendix A. Compatibility with Previous Versions 1347 A.1. Changes from RFC 2068 1349 A case was missed in the Cache-Control model of HTTP/1.1; s-maxage 1350 was introduced to add this missing case. (Sections 2.1, 3.2). 1352 Transfer-coding and message lengths all interact in ways that 1353 required fixing exactly when chunked encoding is used (to allow for 1354 transfer encoding that may not be self delimiting); it was important 1355 to straighten out exactly how message lengths are computed. (see also 1356 [Part1], [Part3] and [Part5]) [[anchor16: This used to refer to the 1357 text about non-modifiable headers, and will have to be updated later 1358 on. --jre]] 1360 Proxies should be able to add Content-Length when appropriate. 1361 [[anchor17: This used to refer to the text about non-modifiable 1362 headers, and will have to be updated later on. --jre]] 1364 Range request responses would become very verbose if all meta-data 1365 were always returned; by allowing the server to only send needed 1366 headers in a 206 response, this problem can be avoided. 1367 (Section 2.7) 1369 The Cache-Control: max-age directive was not properly defined for 1370 responses. (Section 3.2.2) 1372 Warnings could be cached incorrectly, or not updated appropriately. 1373 (Section 2.3, 2.7, 3.2, and 3.6) Warning also needed to be a general 1374 header, as PUT or other methods may have need for it in requests. 1376 A.2. Changes from RFC 2616 1378 Remove requirement to consider Content-Location in successful 1379 responses in order to determine the appropriate response to use. 1380 (Section 2.4) 1382 Clarify denial of service attack avoidance requirement. 1383 (Section 2.5) 1385 Do not mention RFC 2047 encoding and multiple languages in Warning 1386 headers anymore, as these aspects never were implemented. 1387 (Section 3.6) 1389 Appendix B. Collected ABNF 1391 Age = "Age:" OWS Age-v 1392 Age-v = delta-seconds 1393 Cache-Control = "Cache-Control:" OWS Cache-Control-v 1394 Cache-Control-v = *( "," OWS ) cache-directive *( OWS "," [ OWS 1395 cache-directive ] ) 1397 Expires = "Expires:" OWS Expires-v 1398 Expires-v = HTTP-date 1400 HTTP-date = 1402 OWS = 1404 Pragma = "Pragma:" OWS Pragma-v 1405 Pragma-v = *( "," OWS ) pragma-directive *( OWS "," [ OWS 1406 pragma-directive ] ) 1408 Vary = "Vary:" OWS Vary-v 1409 Vary-v = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name 1410 ] ) ) 1412 Warning = "Warning:" OWS Warning-v 1413 Warning-v = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value 1414 ] ) 1416 cache-directive = cache-request-directive / cache-response-directive 1417 cache-extension = token [ "=" ( token / quoted-string ) ] 1418 cache-request-directive = "no-cache" / "no-store" / ( "max-age=" 1419 delta-seconds ) / ( "max-stale" [ "=" delta-seconds ] ) / ( 1420 "min-fresh=" delta-seconds ) / "no-transform" / "only-if-cached" / 1421 cache-extension 1422 cache-response-directive = "public" / ( "private" [ "=" DQUOTE *( "," 1423 OWS ) field-name *( OWS "," [ OWS field-name ] ) DQUOTE ] ) / ( 1424 "no-cache" [ "=" DQUOTE *( "," OWS ) field-name *( OWS "," [ OWS 1425 field-name ] ) DQUOTE ] ) / "no-store" / "no-transform" / 1426 "must-revalidate" / "proxy-revalidate" / ( "max-age=" delta-seconds 1427 ) / ( "s-maxage=" delta-seconds ) / cache-extension 1429 delta-seconds = 1*DIGIT 1431 extension-pragma = token [ "=" ( token / quoted-string ) ] 1433 field-name = 1435 port = 1436 pragma-directive = "no-cache" / extension-pragma 1437 pseudonym = 1439 quoted-string = 1440 token = 1442 uri-host = 1444 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1445 warn-code = 3DIGIT 1446 warn-date = DQUOTE HTTP-date DQUOTE 1447 warn-text = quoted-string 1448 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date 1449 ] 1451 ABNF diagnostics: 1453 ; Age defined but not used 1454 ; Cache-Control defined but not used 1455 ; Expires defined but not used 1456 ; Pragma defined but not used 1457 ; Vary defined but not used 1458 ; Warning defined but not used 1460 Appendix C. Change Log (to be removed by RFC Editor before publication) 1462 C.1. Since RFC2616 1464 Extracted relevant partitions from [RFC2616]. 1466 C.2. Since draft-ietf-httpbis-p6-cache-00 1468 Closed issues: 1470 o : "Trailer" 1471 () 1473 o : "Invalidation 1474 after Update or Delete" 1475 () 1477 o : "Normative and 1478 Informative references" 1480 o : "Date reference 1481 typo" 1483 o : "Connection 1484 header text" 1486 o : "Informative 1487 references" 1489 o : "ISO-8859-1 1490 Reference" 1492 o : "Normative up- 1493 to-date references" 1495 o : "typo in 1496 13.2.2" 1498 Other changes: 1500 o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress 1501 on ) 1503 C.3. Since draft-ietf-httpbis-p6-cache-01 1505 Closed issues: 1507 o : "rel_path not 1508 used" 1510 Other changes: 1512 o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work 1513 in progress on ) 1515 o Add explicit references to BNF syntax and rules imported from 1516 other parts of the specification. 1518 C.4. Since draft-ietf-httpbis-p6-cache-02 1520 Ongoing work on IANA Message Header Registration 1521 (): 1523 o Reference RFC 3984, and update header registrations for headers 1524 defined in this document. 1526 C.5. Since draft-ietf-httpbis-p6-cache-03 1528 Closed issues: 1530 o : "Vary header 1531 classification" 1533 C.6. Since draft-ietf-httpbis-p6-cache-04 1535 Ongoing work on ABNF conversion 1536 (): 1538 o Use "/" instead of "|" for alternatives. 1540 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1541 whitespace ("OWS") and required whitespace ("RWS"). 1543 o Rewrite ABNFs to spell out whitespace rules, factor out header 1544 value format definitions. 1546 C.7. Since draft-ietf-httpbis-p6-cache-05 1548 This is a total rewrite of this part of the specification. 1550 Affected issues: 1552 o : "Definition of 1553 1xx Warn-Codes" 1555 o : "Placement 1556 of 13.5.1 and 13.5.2" 1558 o : "The role 1559 of Warning and Semantic Transparency in Caching" 1561 o : "Methods 1562 and Caching" 1564 In addition: Final work on ABNF conversion 1565 (): 1567 o Add appendix containing collected and expanded ABNF, reorganize 1568 ABNF introduction. 1570 C.8. Since draft-ietf-httpbis-p6-cache-06 1572 Closed issues: 1574 o : "base for 1575 numeric protocol elements" 1577 Affected issues: 1579 o : Vary and non- 1580 existant headers 1582 C.9. Since draft-ietf-httpbis-p6-cache-07 1584 Closed issues: 1586 o : "Definition of 1587 1xx Warn-Codes" 1589 o : "Content- 1590 Location on 304 responses" 1592 o : "private and 1593 no-cache CC directives with headers" 1595 o : "RFC2047 and 1596 warn-text" 1598 Index 1600 A 1601 age 6 1602 Age header 17 1604 C 1605 cache 5 1606 Cache Directives 1607 max-age 18, 22 1608 max-stale 19 1609 min-fresh 19 1610 must-revalidate 21 1611 no-cache 18, 20 1612 no-store 18, 21 1613 no-transform 19, 22 1614 only-if-cached 19 1615 private 20 1616 proxy-revalidate 21 1617 public 20 1618 s-maxage 22 1619 Cache-Control header 17 1620 cacheable 5 1622 E 1623 Expires header 23 1624 explicit expiration time 5 1626 F 1627 first-hand 6 1628 fresh 6 1629 freshness lifetime 6 1631 G 1632 Grammar 1633 Age 17 1634 Age-v 17 1635 Cache-Control 18 1636 Cache-Control-v 18 1637 cache-extension 18 1638 cache-request-directive 18 1639 cache-response-directive 20 1640 delta-seconds 17 1641 Expires 23 1642 Expires-v 23 1643 extension-pragma 24 1644 Pragma 24 1645 pragma-directive 24 1646 Pragma-v 24 1647 Vary 24 1648 Vary-v 24 1649 warn-agent 26 1650 warn-code 26 1651 warn-date 26 1652 warn-text 26 1653 Warning 26 1654 Warning-v 26 1655 warning-value 26 1657 H 1658 Headers 1659 Age 17 1660 Cache-Control 17 1661 Expires 23 1662 Pragma 24 1663 Vary 24 1664 Warning 25 1665 heuristic expiration time 5 1667 M 1668 max-age 1669 Cache Directive 18, 22 1670 max-stale 1671 Cache Directive 19 1672 min-fresh 1673 Cache Directive 19 1674 must-revalidate 1675 Cache Directive 21 1677 N 1678 no-cache 1679 Cache Directive 18, 20 1680 no-store 1681 Cache Directive 18, 21 1682 no-transform 1683 Cache Directive 19, 22 1685 O 1686 only-if-cached 1687 Cache Directive 19 1689 P 1690 Pragma header 24 1691 private 1692 Cache Directive 20 1693 proxy-revalidate 1694 Cache Directive 21 1695 public 1696 Cache Directive 20 1698 S 1699 s-maxage 1700 Cache Directive 22 1701 stale 6 1703 V 1704 validator 6 1705 Vary header 24 1707 W 1708 Warning header 25 1710 Authors' Addresses 1712 Roy T. Fielding (editor) 1713 Day Software 1714 23 Corporate Plaza DR, Suite 280 1715 Newport Beach, CA 92660 1716 USA 1718 Phone: +1-949-706-5300 1719 Fax: +1-949-706-5305 1720 Email: fielding@gbiv.com 1721 URI: http://roy.gbiv.com/ 1722 Jim Gettys 1723 One Laptop per Child 1724 21 Oak Knoll Road 1725 Carlisle, MA 01741 1726 USA 1728 Email: jg@laptop.org 1729 URI: http://www.laptop.org/ 1731 Jeffrey C. Mogul 1732 Hewlett-Packard Company 1733 HP Labs, Large Scale Systems Group 1734 1501 Page Mill Road, MS 1177 1735 Palo Alto, CA 94304 1736 USA 1738 Email: JeffMogul@acm.org 1740 Henrik Frystyk Nielsen 1741 Microsoft Corporation 1742 1 Microsoft Way 1743 Redmond, WA 98052 1744 USA 1746 Email: henrikn@microsoft.com 1748 Larry Masinter 1749 Adobe Systems, Incorporated 1750 345 Park Ave 1751 San Jose, CA 95110 1752 USA 1754 Email: LMM@acm.org 1755 URI: http://larry.masinter.net/ 1757 Paul J. Leach 1758 Microsoft Corporation 1759 1 Microsoft Way 1760 Redmond, WA 98052 1762 Email: paulle@microsoft.com 1763 Tim Berners-Lee 1764 World Wide Web Consortium 1765 MIT Computer Science and Artificial Intelligence Laboratory 1766 The Stata Center, Building 32 1767 32 Vassar Street 1768 Cambridge, MA 02139 1769 USA 1771 Email: timbl@w3.org 1772 URI: http://www.w3.org/People/Berners-Lee/ 1774 Yves Lafon (editor) 1775 World Wide Web Consortium 1776 W3C / ERCIM 1777 2004, rte des Lucioles 1778 Sophia-Antipolis, AM 06902 1779 France 1781 Email: ylafon@w3.org 1782 URI: http://www.raubacapeu.net/people/yves/ 1784 Mark Nottingham (editor) 1786 Email: mnot@mnot.net 1787 URI: http://www.mnot.net/ 1789 Julian F. Reschke (editor) 1790 greenbytes GmbH 1791 Hafenweg 16 1792 Muenster, NW 48155 1793 Germany 1795 Phone: +49 251 2807760 1796 Fax: +49 251 2807761 1797 Email: julian.reschke@greenbytes.de 1798 URI: http://greenbytes.de/tech/webdav/