idnits 2.17.1 draft-ietf-httpbis-p6-cache-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (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 (March 8, 2010) is 5157 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-09 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-09 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-09 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-09 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-09 -- 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 (~~), 6 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: September 9, 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 March 8, 2010 24 HTTP/1.1, part 6: Caching 25 draft-ietf-httpbis-p6-cache-09 27 Abstract 29 The Hypertext Transfer Protocol (HTTP) is an application-level 30 protocol for distributed, collaborative, hypermedia information 31 systems. This document is Part 6 of the seven-part specification 32 that defines the protocol referred to as "HTTP/1.1" and, taken 33 together, obsoletes RFC 2616. Part 6 defines requirements on HTTP 34 caches and the associated header fields that control cache behavior 35 or indicate cacheable response messages. 37 Editorial Note (To be removed by RFC Editor) 39 Discussion of this draft should take place on the HTTPBIS working 40 group mailing list (ietf-http-wg@w3.org). The current issues list is 41 at and related 42 documents (including fancy diffs) can be found at 43 . 45 The changes in this draft are summarized in Appendix C.10. 47 Status of this Memo 48 This Internet-Draft is submitted to IETF in full conformance with the 49 provisions of BCP 78 and BCP 79. 51 Internet-Drafts are working documents of the Internet Engineering 52 Task Force (IETF), its areas, and its working groups. Note that 53 other groups may also distribute working documents as Internet- 54 Drafts. 56 Internet-Drafts are draft documents valid for a maximum of six months 57 and may be updated, replaced, or obsoleted by other documents at any 58 time. It is inappropriate to use Internet-Drafts as reference 59 material or to cite them other than as "work in progress." 61 The list of current Internet-Drafts can be accessed at 62 http://www.ietf.org/ietf/1id-abstracts.txt. 64 The list of Internet-Draft Shadow Directories can be accessed at 65 http://www.ietf.org/shadow.html. 67 This Internet-Draft will expire on September 9, 2010. 69 Copyright Notice 71 Copyright (c) 2010 IETF Trust and the persons identified as the 72 document authors. All rights reserved. 74 This document is subject to BCP 78 and the IETF Trust's Legal 75 Provisions Relating to IETF Documents 76 (http://trustee.ietf.org/license-info) in effect on the date of 77 publication of this document. Please review these documents 78 carefully, as they describe your rights and restrictions with respect 79 to this document. Code Components extracted from this document must 80 include Simplified BSD License text as described in Section 4.e of 81 the Trust Legal Provisions and are provided without warranty as 82 described in the BSD License. 84 This document may contain material from IETF Documents or IETF 85 Contributions published or made publicly available before November 86 10, 2008. The person(s) controlling the copyright in some of this 87 material may not have granted the IETF Trust the right to allow 88 modifications of such material outside the IETF Standards Process. 89 Without obtaining an adequate license from the person(s) controlling 90 the copyright in such materials, this document may not be modified 91 outside the IETF Standards Process, and derivative works of it may 92 not be created outside the IETF Standards Process, except to format 93 it for publication as an RFC or to translate it into languages other 94 than English. 96 Table of Contents 98 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 99 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 100 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 101 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 6 102 1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 103 1.4.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 7 104 1.4.2. ABNF Rules defined in other Parts of the 105 Specification . . . . . . . . . . . . . . . . . . . . 7 106 2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 7 107 2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 7 108 2.1.1. Storing Partial and Incomplete Responses . . . . . . . 8 109 2.2. Constructing Responses from Caches . . . . . . . . . . . . 9 110 2.3. Freshness Model . . . . . . . . . . . . . . . . . . . . . 10 111 2.3.1. Calculating Freshness Lifetime . . . . . . . . . . . . 11 112 2.3.2. Calculating Age . . . . . . . . . . . . . . . . . . . 12 113 2.3.3. Serving Stale Responses . . . . . . . . . . . . . . . 13 114 2.4. Validation Model . . . . . . . . . . . . . . . . . . . . . 14 115 2.5. Request Methods that Invalidate . . . . . . . . . . . . . 14 116 2.6. Caching Negotiated Responses . . . . . . . . . . . . . . . 15 117 2.7. Combining Responses . . . . . . . . . . . . . . . . . . . 16 118 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 17 119 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 120 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 18 121 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 18 122 3.2.2. Response Cache-Control Directives . . . . . . . . . . 20 123 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 22 124 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 23 125 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 24 126 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 127 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 25 128 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 28 129 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 130 5.1. Message Header Registration . . . . . . . . . . . . . . . 28 131 6. Security Considerations . . . . . . . . . . . . . . . . . . . 28 132 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29 133 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 134 8.1. Normative References . . . . . . . . . . . . . . . . . . . 29 135 8.2. Informative References . . . . . . . . . . . . . . . . . . 30 136 Appendix A. Compatibility with Previous Versions . . . . . . . . 30 137 A.1. Changes from RFC 2068 . . . . . . . . . . . . . . . . . . 30 138 A.2. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 30 139 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 31 140 Appendix C. Change Log (to be removed by RFC Editor before 141 publication) . . . . . . . . . . . . . . . . . . . . 32 142 C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 32 143 C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 32 144 C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 33 145 C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 33 146 C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 34 147 C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 34 148 C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 34 149 C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 35 150 C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 35 151 C.10. Since draft-ietf-httpbis-p6-cache-08 . . . . . . . . . . . 35 152 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 153 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38 155 1. Introduction 157 HTTP is typically used for distributed information systems, where 158 performance can be improved by the use of response caches. This 159 document defines aspects of HTTP/1.1 related to caching and reusing 160 response messages. 162 1.1. Purpose 164 An HTTP cache is a local store of response messages and the subsystem 165 that controls its message storage, retrieval, and deletion. A cache 166 stores cacheable responses in order to reduce the response time and 167 network bandwidth consumption on future, equivalent requests. Any 168 client or server may include a cache, though a cache cannot be used 169 by a server that is acting as a tunnel. 171 Caching would be useless if it did not significantly improve 172 performance. The goal of caching in HTTP/1.1 is to reuse a prior 173 response message to satisfy a current request. In some cases, a 174 stored response can be reused without the need for a network request, 175 reducing latency and network round-trips; a "freshness" mechanism is 176 used for this purpose (see Section 2.3). Even when a new request is 177 required, it is often possible to reuse all or parts of the payload 178 of a prior response to satisfy the request, thereby reducing network 179 bandwidth usage; a "validation" mechanism is used for this purpose 180 (see Section 2.4). 182 1.2. Terminology 184 This specification uses a number of terms to refer to the roles 185 played by participants in, and objects of, HTTP caching. 187 cacheable 189 A response is cacheable if a cache is allowed to store a copy of 190 the response message for use in answering subsequent requests. 191 Even when a response is cacheable, there may be additional 192 constraints on whether a cache can use the cached copy to satisfy 193 a particular request. 195 explicit expiration time 197 The time at which the origin server intends that an entity should 198 no longer be returned by a cache without further validation. 200 heuristic expiration time 202 An expiration time assigned by a cache when no explicit expiration 203 time is available. 205 age 207 The age of a response is the time since it was sent by, or 208 successfully validated with, the origin server. 210 first-hand 212 A response is first-hand if the freshness model is not in use; 213 i.e., its age is 0. 215 freshness lifetime 217 The length of time between the generation of a response and its 218 expiration time. 220 fresh 222 A response is fresh if its age has not yet exceeded its freshness 223 lifetime. 225 stale 227 A response is stale if its age has passed its freshness lifetime 228 (either explicit or heuristic). 230 validator 232 A protocol element (e.g., an entity tag or a Last-Modified time) 233 that is used to find out whether a stored response is an 234 equivalent copy of an entity. 236 shared cache 238 A cache that is accessible to more than one user. A non-shared 239 cache is dedicated to a single user. 241 1.3. Requirements 243 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 244 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 245 document are to be interpreted as described in [RFC2119]. 247 An implementation is not compliant if it fails to satisfy one or more 248 of the MUST or REQUIRED level requirements for the protocols it 249 implements. An implementation that satisfies all the MUST or 250 REQUIRED level and all the SHOULD level requirements for its 251 protocols is said to be "unconditionally compliant"; one that 252 satisfies all the MUST level requirements but not all the SHOULD 253 level requirements for its protocols is said to be "conditionally 254 compliant." 256 1.4. Syntax Notation 258 This specification uses the ABNF syntax defined in Section 1.2 of 259 [Part1] (which extends the syntax defined in [RFC5234] with a list 260 rule). Appendix B shows the collected ABNF, with the list rule 261 expanded. 263 The following core rules are included by reference, as defined in 264 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 265 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 266 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 267 sequence of data), SP (space), VCHAR (any visible USASCII character), 268 and WSP (whitespace). 270 1.4.1. Core Rules 272 The core rules below are defined in Section 1.2.2 of [Part1]: 274 quoted-string = 275 token = 276 OWS = 278 1.4.2. ABNF Rules defined in other Parts of the Specification 280 The ABNF rules below are defined in other parts: 282 field-name = 283 HTTP-date = 284 port = 285 pseudonym = 286 uri-host = 288 2. Cache Operation 290 2.1. Response Cacheability 292 A cache MUST NOT store a response to any request, unless: 294 o The request method is understood by the cache and defined as being 295 cacheable, and 297 o the response status code is understood by the cache, and 299 o the "no-store" cache directive (see Section 3.2) does not appear 300 in request or response headers, and 302 o the "private" cache response directive (see Section 3.2.2 does not 303 appear in the response, if the cache is shared, and 305 o the "Authorization" header (see Section 3.1 of [Part7]) does not 306 appear in the request, if the cache is shared (unless the "public" 307 directive is present; see Section 3.2), and 309 o the response either: 311 * contains an Expires header (see Section 3.3), or 313 * contains a max-age response cache directive (see 314 Section 3.2.2), or 316 * contains a s-maxage response cache directive and the cache is 317 shared, or 319 * contains a Cache Control Extension (see Section 3.2.3) that 320 allows it to be cached, or 322 * has a status code that can be served with heuristic freshness 323 (see Section 2.3.1.1). 325 In this context, a cache has "understood" a request method or a 326 response status code if it recognises it and implements any cache- 327 specific behaviour. In particular, 206 Partial Content responses 328 cannot be cached by an implementation that does not handle partial 329 content (see Section 2.1.1). 331 Note that in normal operation, most caches will not store a response 332 that has neither a cache validator nor an explicit expiration time, 333 as such responses are not usually useful to store. However, caches 334 are not prohibited from storing such responses. 336 2.1.1. Storing Partial and Incomplete Responses 338 A cache that receives an incomplete response (for example, with fewer 339 bytes of data than specified in a Content-Length header) can store 340 the response, but MUST treat it as a partial response [Part5]. 341 Partial responses can be combined as described in Section 4 of 343 [Part5]; the result might be a full response or might still be 344 partial. A cache MUST NOT return a partial response to a client 345 without explicitly marking it as such using the 206 (Partial Content) 346 status code. 348 A cache that does not support the Range and Content-Range headers 349 MUST NOT store incomplete or partial responses. 351 2.2. Constructing Responses from Caches 353 For a presented request, a cache MUST NOT return a stored response, 354 unless: 356 o The presented Request-URI and that of the stored response match 357 ([[TODO-Request-URI: Need to find a new term for this, as Part 1 358 doesn't define Request-URI anymore; the new term request-target 359 does not work for this. (see 360 )]]), and 362 o the request method associated with the stored response allows it 363 to be used for the presented request, and 365 o selecting request-headers nominated by the stored response (if 366 any) match those presented (see Section 2.6), and 368 o the presented request and stored response are free from directives 369 that would prevent its use (see Section 3.2 and Section 3.4), and 371 o the stored response is either: 373 * fresh (see Section 2.3), or 375 * allowed to be served stale (see Section 2.3.3), or 377 * successfully validated (see Section 2.4). 379 [[TODO-method-cacheability: define method cacheability for GET, HEAD 380 and POST in p2-semantics.]] 382 When a stored response is used to satisfy a request, caches MUST 383 include a single Age header field (Section 3.1) in the response with 384 a value equal to the stored response's current_age; see 385 Section 2.3.2. [[DISCUSS-includes-validated: this currently includes 386 successfully validated responses.]] 388 Requests with methods that are unsafe (Section 7.1.1 of [Part2]) MUST 389 be written through the cache to the origin server; i.e., a cache must 390 not reply to such a request before having forwarded the request and 391 having received a corresponding response. 393 Also, note that unsafe requests might invalidate already stored 394 responses; see Section 2.5. 396 Caches MUST use the most recent response (as determined by the Date 397 header) when more than one suitable response is stored. They can 398 also forward a request with "Cache-Control: max-age=0" or "Cache- 399 Control: no-cache" to disambiguate which response to use. 401 [[TODO-header-properties: end-to-end and hop-by-hop headers, non- 402 modifiable headers removed; re-spec in p1]] 404 2.3. Freshness Model 406 When a response is "fresh" in the cache, it can be used to satisfy 407 subsequent requests without contacting the origin server, thereby 408 improving efficiency. 410 The primary mechanism for determining freshness is for an origin 411 server to provide an explicit expiration time in the future, using 412 either the Expires header (Section 3.3) or the max-age response cache 413 directive (Section 3.2.2). Generally, origin servers will assign 414 future explicit expiration times to responses in the belief that the 415 entity is not likely to change in a semantically significant way 416 before the expiration time is reached. 418 If an origin server wishes to force a cache to validate every 419 request, it can assign an explicit expiration time in the past. This 420 means that the response is always stale, so that caches should 421 validate it before using it for subsequent requests. [[TODO- 422 response-stale: This wording may cause confusion, because the 423 response may still be served stale.]] 425 Since origin servers do not always provide explicit expiration times, 426 HTTP caches may also assign heuristic expiration times when they are 427 not specified, employing algorithms that use other header values 428 (such as the Last-Modified time) to estimate a plausible expiration 429 time. The HTTP/1.1 specification does not provide specific 430 algorithms, but does impose worst-case constraints on their results. 432 The calculation to determine if a response is fresh is: 434 response_is_fresh = (freshness_lifetime > current_age) 436 The freshness_lifetime is defined in Section 2.3.1; the current_age 437 is defined in Section 2.3.2. 439 Additionally, clients may need to influence freshness calculation. 440 They can do this using several request cache directives, with the 441 effect of either increasing or loosening constraints on freshness. 442 See Section 3.2.1. 444 [[ISSUE-no-req-for-directives: there are not requirements directly 445 applying to cache-request-directives and freshness.]] 447 Note that freshness applies only to cache operation; it cannot be 448 used to force a user agent to refresh its display or reload a 449 resource. See Section 4 for an explanation of the difference between 450 caches and history mechanisms. 452 2.3.1. Calculating Freshness Lifetime 454 A cache can calculate the freshness lifetime (denoted as 455 freshness_lifetime) of a response by using the first match of: 457 o If the cache is shared and the s-maxage response cache directive 458 (Section 3.2.2) is present, use its value, or 460 o If the max-age response cache directive (Section 3.2.2) is 461 present, use its value, or 463 o If the Expires response header (Section 3.3) is present, use its 464 value minus the value of the Date response header, or 466 o Otherwise, no explicit expiration time is present in the response, 467 but a heuristic may be used; see Section 2.3.1.1. 469 Note that this calculation is not vulnerable to clock skew, since all 470 of the information comes from the origin server. 472 2.3.1.1. Calculating Heuristic Freshness 474 If no explicit expiration time is present in a stored response that 475 has a status code of 200, 203, 206, 300, 301 or 410, a heuristic 476 expiration time can be calculated. Heuristics MUST NOT be used for 477 other response status codes. 479 When a heuristic is used to calculate freshness lifetime, the cache 480 SHOULD attach a Warning header with a 113 warn-code to the response 481 if its current_age is more than 24 hours and such a warning is not 482 already present. 484 Also, if the response has a Last-Modified header (Section 6.6 of 485 [Part4]), the heuristic expiration value SHOULD be no more than some 486 fraction of the interval since that time. A typical setting of this 487 fraction might be 10%. 489 [[REVIEW-query-string-heuristics: took away HTTP/1.0 query string 490 heuristic uncacheability.]] 492 2.3.2. Calculating Age 494 HTTP/1.1 uses the Age response-header to convey the estimated age of 495 the response message when obtained from a cache. The Age field value 496 is the cache's estimate of the amount of time since the response was 497 generated or validated by the origin server. In essence, the Age 498 value is the sum of the time that the response has been resident in 499 each of the caches along the path from the origin server, plus the 500 amount of time it has been in transit along network paths. 502 The term "age_value" denotes the value of the Age header, in a form 503 appropriate for arithmetic operations. 505 HTTP/1.1 requires origin servers to send a Date header, if possible, 506 with every response, giving the time at which the response was 507 generated (see Section 9.3 of [Part1]). The term "date_value" 508 denotes the value of the Date header, in a form appropriate for 509 arithmetic operations. 511 The term "now" means "the current value of the clock at the host 512 performing the calculation." Hosts that use HTTP, but especially 513 hosts running origin servers and caches, SHOULD use NTP [RFC1305] or 514 some similar protocol to synchronize their clocks to a globally 515 accurate time standard. 517 A response's age can be calculated in two entirely independent ways: 519 1. now minus date_value, if the local clock is reasonably well 520 synchronized to the origin server's clock. If the result is 521 negative, the result is replaced by zero. 523 2. age_value, if all of the caches along the response path implement 524 HTTP/1.1. 526 These are combined as 528 corrected_received_age = max(now - date_value, age_value) 530 When an Age value is received, it MUST be interpreted relative to the 531 time the request was initiated, not the time that the response was 532 received. 534 corrected_initial_age = corrected_received_age 535 + (now - request_time) 537 where "request_time" is the time (according to the local clock) when 538 the request that elicited this response was sent. 540 The current_age of a stored response can then be calculated by adding 541 the amount of time (in seconds) since the stored response was last 542 validated by the origin server to the corrected_initial_age. 544 In summary: 546 age_value - Age header field-value received with the response 547 date_value - Date header field-value received with the response 548 request_time - local time when the cache made the request 549 resulting in the stored response 550 response_time - local time when the cache received the response 551 now - current local time 553 apparent_age = max(0, response_time - date_value); 554 corrected_received_age = max(apparent_age, age_value); 555 response_delay = response_time - request_time; 556 corrected_initial_age = corrected_received_age + response_delay; 557 resident_time = now - response_time; 558 current_age = corrected_initial_age + resident_time; 560 2.3.3. Serving Stale Responses 562 A "stale" response is one that either has explicit expiry 563 information, or is allowed to have heuristic expiry calculated, but 564 is not fresh according to the calculations in Section 2.3. 566 Caches MUST NOT return a stale response if it is prohibited by an 567 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" 568 cache directive, a "must-revalidate" cache-response-directive, or an 569 applicable "s-maxage" or "proxy-revalidate" cache-response-directive; 570 see Section 3.2.2). 572 Caches SHOULD NOT return stale responses unless they are disconnected 573 (i.e., it cannot contact the origin server or otherwise find a 574 forward path) or otherwise explicitly allowed (e.g., the max-stale 575 request directive; see Section 3.2.1). 577 Stale responses SHOULD have a Warning header with the 110 warn-code 578 (see Section 3.6). Likewise, the 112 warn-code SHOULD be sent on 579 stale responses if the cache is disconnected. 581 If a cache receives a first-hand response (either an entire response, 582 or a 304 (Not Modified) response) that it would normally forward to 583 the requesting client, and the received response is no longer fresh, 584 the cache SHOULD forward it to the requesting client without adding a 585 new Warning (but without removing any existing Warning headers). A 586 cache SHOULD NOT attempt to validate a response simply because that 587 response became stale in transit. 589 2.4. Validation Model 591 When a cache has one or more stored responses for a requested URI, 592 but cannot serve any of them (e.g., because they are not fresh, or 593 one cannot be selected; see Section 2.6), it can use the conditional 594 request mechanism [Part4] in the forwarded request to give the origin 595 server an opportunity to both select a valid stored response to be 596 used, and to update it. This process is known as "validating" or 597 "revalidating" the stored response. 599 When sending such a conditional request, the cache SHOULD add an If- 600 Modified-Since header whose value is that of the Last-Modified header 601 from the selected (see Section 2.6) stored response, if available. 603 Additionally, the cache SHOULD add an If-None-Match header whose 604 value is that of the ETag header(s) from all responses stored for the 605 requested URI, if present. However, if any of the stored responses 606 contains only partial content, its entity-tag SHOULD NOT be included 607 in the If-None-Match header field unless the request is for a range 608 that would be fully satisfied by that stored response. 610 A 304 (Not Modified) response status code indicates that the stored 611 response can be updated and reused; see Section 2.7. 613 A full response (i.e., one with a response body) indicates that none 614 of the stored responses nominated in the conditional request is 615 suitable. Instead, the full response is used both to satisfy the 616 request and replace the stored response. [[TODO-req-missing: Should 617 there be a requirement here?]] 619 If a cache receives a 5xx response while attempting to validate a 620 response, it MAY either forward this response to the requesting 621 client, or act as if the server failed to respond. In the latter 622 case, it MAY return a previously stored response (see Section 2.3.3). 624 2.5. Request Methods that Invalidate 626 Because unsafe methods (Section 7.1.1 of [Part2]) have the potential 627 for changing state on the origin server, intervening caches can use 628 them to keep their contents up-to-date. 630 The following HTTP methods MUST cause a cache to invalidate the 631 Request-URI as well as the URI(s) in the Location and Content- 632 Location headers (if present): 634 o PUT 636 o DELETE 638 o POST 640 An invalidation based on a URI from a Location or Content-Location 641 header MUST NOT be performed if the host part of that URI differs 642 from the host part in the Request-URI. This helps prevent denial of 643 service attacks. 645 [[TODO-def-host-part: "host part" needs to be specified better.]] 647 A cache that passes through requests for methods it does not 648 understand SHOULD invalidate the Request-URI. 650 Here, "invalidate" means that the cache will either remove all stored 651 responses related to the Request-URI, or will mark these as "invalid" 652 and in need of a mandatory validation before they can be returned in 653 response to a subsequent request. 655 Note that this does not guarantee that all appropriate responses are 656 invalidated. For example, the request that caused the change at the 657 origin server might not have gone through the cache where a response 658 is stored. 660 [[TODO-spec-success-invalidate: specify that only successful (2xx, 661 3xx?) responses invalidate.]] 663 2.6. Caching Negotiated Responses 665 When a cache receives a request that can be satisfied by a stored 666 response that has a Vary header field (Section 3.5), it MUST NOT use 667 that response unless all of the selecting request-headers nominated 668 by the Vary header match in both the original request (i.e., that 669 associated with the stored response), and the presented request. 671 The selecting request-headers from two requests are defined to match 672 if and only if those in the first request can be transformed to those 673 in the second request by applying any of the following: 675 o adding or removing whitespace, where allowed in the header's 676 syntax 678 o combining multiple message-header fields with the same field name 679 (see Section 3.2 of [Part1]) 681 o normalizing both header values in a way that is known to have 682 identical semantics, according to the header's specification 683 (e.g., re-ordering field values when order is not significant; 684 case-normalization, where values are defined to be case- 685 insensitive) 687 If (after any normalisation that may take place) a header field is 688 absent from a request, it can only match another request if it is 689 also absent there. 691 A Vary header field-value of "*" always fails to match, and 692 subsequent requests to that resource can only be properly interpreted 693 by the origin server. 695 The stored response with matching selecting request-headers is known 696 as the selected response. 698 If no selected response is available, the cache MAY forward the 699 presented request to the origin server in a conditional request; see 700 Section 2.4. 702 2.7. Combining Responses 704 When a cache receives a 304 (Not Modified) response or a 206 (Partial 705 Content) response (in this section, the "new" response"), it needs to 706 created an updated response by combining the stored response with the 707 new one, so that the updated response can be used to satisfy the 708 request. 710 If the new response contains an ETag, it identifies the stored 711 response to use. [[TODO-mention-CL: may need language about Content- 712 Location here]][[TODO-inm-mult-etags: cover case where INM with 713 multiple etags was sent]] 715 If the status code is 206 (partial content), both the stored and new 716 responses MUST have validators, and those validators MUST match using 717 the strong comparison function (see Section 4 of [Part4]). 718 Otherwise, the responses MUST NOT be combined. 720 The stored response headers are used as those of the updated 721 response, except that 723 o any stored Warning headers with warn-code 1xx (see Section 3.6) 724 MUST be deleted from the stored response and the updated response. 726 o any stored Warning headers with warn-code 2xx MUST be retained in 727 the stored response and the updated response. 729 o any headers provided in the new response MUST replace the 730 corresponding headers from the stored response. 732 If a header field-name in the new response matches more than one 733 header in the stored response, all such stored headers MUST be 734 replaced. 736 The updated response can [[TODO-is-req: requirement?]] be used to 737 replace the stored response in cache. In the case of a 206 response, 738 the combined entity-body MAY be stored. 740 [[ISSUE-how-head: discuss how to handle HEAD updates]] 742 3. Header Field Definitions 744 This section defines the syntax and semantics of HTTP/1.1 header 745 fields related to caching. 747 For entity-header fields, both sender and recipient refer to either 748 the client or the server, depending on who sends and who receives the 749 entity. 751 3.1. Age 753 The "Age" response-header field conveys the sender's estimate of the 754 amount of time since the response was generated or successfully 755 validated at the origin server. Age values are calculated as 756 specified in Section 2.3.2. 758 Age = "Age" ":" OWS Age-v 759 Age-v = delta-seconds 761 Age field-values are non-negative integers, representing time in 762 seconds. 764 delta-seconds = 1*DIGIT 766 If a cache receives a value larger than the largest positive integer 767 it can represent, or if any of its age calculations overflows, it 768 MUST transmit an Age header with a field-value of 2147483648 (2^31). 769 Caches SHOULD use an arithmetic type of at least 31 bits of range. 771 The presence of an Age header field in a response implies that a 772 response is not first-hand. However, the converse is not true, since 773 HTTP/1.0 caches may not implement the Age header field. 775 3.2. Cache-Control 777 The "Cache-Control" general-header field is used to specify 778 directives that MUST be obeyed by all caches along the request/ 779 response chain. Such cache directives are unidirectional in that the 780 presence of a directive in a request does not imply that the same 781 directive is to be given in the response. 783 Note that HTTP/1.0 caches might not implement Cache-Control and 784 might only implement Pragma: no-cache (see Section 3.4). 786 Cache directives MUST be passed through by a proxy or gateway 787 application, regardless of their significance to that application, 788 since the directives might be applicable to all recipients along the 789 request/response chain. It is not possible to target a directive to 790 a specific cache. 792 Cache-Control = "Cache-Control" ":" OWS Cache-Control-v 793 Cache-Control-v = 1#cache-directive 795 cache-directive = cache-request-directive 796 / cache-response-directive 798 cache-extension = token [ "=" ( token / quoted-string ) ] 800 3.2.1. Request Cache-Control Directives 802 cache-request-directive = 803 "no-cache" 804 / "no-store" 805 / "max-age" "=" delta-seconds 806 / "max-stale" [ "=" delta-seconds ] 807 / "min-fresh" "=" delta-seconds 808 / "no-transform" 809 / "only-if-cached" 810 / cache-extension 812 no-cache 814 The no-cache request directive indicates that a stored response 815 MUST NOT be used to satisfy the request without successful 816 validation on the origin server. 818 no-store 819 The no-store request directive indicates that a cache MUST NOT 820 store any part of either this request or any response to it. This 821 directive applies to both non-shared and shared caches. "MUST NOT 822 store" in this context means that the cache MUST NOT intentionally 823 store the information in non-volatile storage, and MUST make a 824 best-effort attempt to remove the information from volatile 825 storage as promptly as possible after forwarding it. 827 This directive is NOT a reliable or sufficient mechanism for 828 ensuring privacy. In particular, malicious or compromised caches 829 might not recognize or obey this directive, and communications 830 networks may be vulnerable to eavesdropping. 832 max-age 834 The max-age request directive indicates that the client is willing 835 to accept a response whose age is no greater than the specified 836 time in seconds. Unless max-stale directive is also included, the 837 client is not willing to accept a stale response. 839 max-stale 841 The max-stale request directive indicates that the client is 842 willing to accept a response that has exceeded its expiration 843 time. If max-stale is assigned a value, then the client is 844 willing to accept a response that has exceeded its expiration time 845 by no more than the specified number of seconds. If no value is 846 assigned to max-stale, then the client is willing to accept a 847 stale response of any age. [[TODO-staleness: of any staleness? 848 --mnot]] 850 min-fresh 852 The min-fresh request directive indicates that the client is 853 willing to accept a response whose freshness lifetime is no less 854 than its current age plus the specified time in seconds. That is, 855 the client wants a response that will still be fresh for at least 856 the specified number of seconds. 858 no-transform 860 The no-transform request directive indicates that an intermediate 861 cache or proxy MUST NOT change the Content-Encoding, Content-Range 862 or Content-Type request headers, nor the request entity-body. 864 only-if-cached 865 The only-if-cached request directive indicates that the client 866 only wishes to return a stored response. If it receives this 867 directive, a cache SHOULD either respond using a stored response 868 that is consistent with the other constraints of the request, or 869 respond with a 504 (Gateway Timeout) status. If a group of caches 870 is being operated as a unified system with good internal 871 connectivity, such a request MAY be forwarded within that group of 872 caches. 874 3.2.2. Response Cache-Control Directives 876 cache-response-directive = 877 "public" 878 / "private" [ "=" DQUOTE 1#field-name DQUOTE ] 879 / "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] 880 / "no-store" 881 / "no-transform" 882 / "must-revalidate" 883 / "proxy-revalidate" 884 / "max-age" "=" delta-seconds 885 / "s-maxage" "=" delta-seconds 886 / cache-extension 888 public 890 The public response directive indicates that the response MAY be 891 cached, even if it would normally be non-cacheable or cacheable 892 only within a non-shared cache. (See also Authorization, Section 893 3.1 of [Part7], for additional details.) 895 private 897 The private response directive indicates that the response message 898 is intended for a single user and MUST NOT be stored by a shared 899 cache. A private (non-shared) cache MAY store the response. 901 If the private response directive specifies one or more field- 902 names, this requirement is limited to the field-values associated 903 with the listed response headers. That is, the specified field- 904 names(s) MUST NOT be stored by a shared cache, whereas the 905 remainder of the response message MAY be. 907 Note: This usage of the word private only controls where the 908 response may be stored, and cannot ensure the privacy of the 909 message content. Also, private response directives with field- 910 names are often handled by implementations as if an unqualified 911 private directive was received; i.e., the special handling for the 912 qualified form is not widely implemented. 914 no-cache 916 The no-cache response directive indicates that the response MUST 917 NOT be used to satisfy a subsequent request without successful 918 validation on the origin server. This allows an origin server to 919 prevent caching even by caches that have been configured to return 920 stale responses. 922 If the no-cache response directive specifies one or more field- 923 names, this requirement is limited to the field-values associated 924 with the listed response headers. That is, the specified field- 925 name(s) MUST NOT be sent in the response to a subsequent request 926 without successful validation on the origin server. This allows 927 an origin server to prevent the re-use of certain header fields in 928 a response, while still allowing caching of the rest of the 929 response. 931 Note: Most HTTP/1.0 caches will not recognize or obey this 932 directive. Also, no-cache response directives with field-names 933 are often handled by implementations as if an unqualified no-cache 934 directive was received; i.e., the special handling for the 935 qualified form is not widely implemented. 937 no-store 939 The no-store response directive indicates that a cache MUST NOT 940 store any part of either the immediate request or response. This 941 directive applies to both non-shared and shared caches. "MUST NOT 942 store" in this context means that the cache MUST NOT intentionally 943 store the information in non-volatile storage, and MUST make a 944 best-effort attempt to remove the information from volatile 945 storage as promptly as possible after forwarding it. 947 This directive is NOT a reliable or sufficient mechanism for 948 ensuring privacy. In particular, malicious or compromised caches 949 might not recognize or obey this directive, and communications 950 networks may be vulnerable to eavesdropping. 952 must-revalidate 954 The must-revalidate response directive indicates that once it has 955 become stale, the response MUST NOT be used to satisfy subsequent 956 requests without successful validation on the origin server. 958 The must-revalidate directive is necessary to support reliable 959 operation for certain protocol features. In all circumstances an 960 HTTP/1.1 cache MUST obey the must-revalidate directive; in 961 particular, if the cache cannot reach the origin server for any 962 reason, it MUST generate a 504 (Gateway Timeout) response. 964 Servers SHOULD send the must-revalidate directive if and only if 965 failure to validate a request on the entity could result in 966 incorrect operation, such as a silently unexecuted financial 967 transaction. 969 proxy-revalidate 971 The proxy-revalidate response directive has the same meaning as 972 the must-revalidate response directive, except that it does not 973 apply to non-shared caches. 975 max-age 977 The max-age response directive indicates that response is to be 978 considered stale after its age is greater than the specified 979 number of seconds. 981 s-maxage 983 The s-maxage response directive indicates that, in shared caches, 984 the maximum age specified by this directive overrides the maximum 985 age specified by either the max-age directive or the Expires 986 header. The s-maxage directive also implies the semantics of the 987 proxy-revalidate response directive. 989 no-transform 991 The no-transform response directive indicates that an intermediate 992 cache or proxy MUST NOT change the Content-Encoding, Content-Range 993 or Content-Type response headers, nor the response entity-body. 995 3.2.3. Cache Control Extensions 997 The Cache-Control header field can be extended through the use of one 998 or more cache-extension tokens, each with an optional value. 999 Informational extensions (those that do not require a change in cache 1000 behavior) can be added without changing the semantics of other 1001 directives. Behavioral extensions are designed to work by acting as 1002 modifiers to the existing base of cache directives. Both the new 1003 directive and the standard directive are supplied, such that 1004 applications that do not understand the new directive will default to 1005 the behavior specified by the standard directive, and those that 1006 understand the new directive will recognize it as modifying the 1007 requirements associated with the standard directive. In this way, 1008 extensions to the cache-control directives can be made without 1009 requiring changes to the base protocol. 1011 This extension mechanism depends on an HTTP cache obeying all of the 1012 cache-control directives defined for its native HTTP-version, obeying 1013 certain extensions, and ignoring all directives that it does not 1014 understand. 1016 For example, consider a hypothetical new response directive called 1017 "community" that acts as a modifier to the private directive. We 1018 define this new directive to mean that, in addition to any non-shared 1019 cache, any cache that is shared only by members of the community 1020 named within its value may cache the response. An origin server 1021 wishing to allow the UCI community to use an otherwise private 1022 response in their shared cache(s) could do so by including 1024 Cache-Control: private, community="UCI" 1026 A cache seeing this header field will act correctly even if the cache 1027 does not understand the community cache-extension, since it will also 1028 see and understand the private directive and thus default to the safe 1029 behavior. 1031 Unrecognized cache directives MUST be ignored; it is assumed that any 1032 cache directive likely to be unrecognized by an HTTP/1.1 cache will 1033 be combined with standard directives (or the response's default 1034 cacheability) such that the cache behavior will remain minimally 1035 correct even if the cache does not understand the extension(s). 1037 3.3. Expires 1039 The "Expires" entity-header field gives the date/time after which the 1040 response is considered stale. See Section 2.3 for further discussion 1041 of the freshness model. 1043 The presence of an Expires field does not imply that the original 1044 resource will change or cease to exist at, before, or after that 1045 time. 1047 The field-value is an absolute date and time as defined by HTTP-date 1048 in Section 6.1 of [Part1]; it MUST be sent in rfc1123-date format. 1050 Expires = "Expires" ":" OWS Expires-v 1051 Expires-v = HTTP-date 1053 For example 1055 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1056 Note: If a response includes a Cache-Control field with the max- 1057 age directive (see Section 3.2.2), that directive overrides the 1058 Expires field. Likewise, the s-maxage directive overrides Expires 1059 in shared caches. 1061 HTTP/1.1 servers SHOULD NOT send Expires dates more than one year in 1062 the future. 1064 HTTP/1.1 clients and caches MUST treat other invalid date formats, 1065 especially including the value "0", as in the past (i.e., "already 1066 expired"). 1068 3.4. Pragma 1070 The "Pragma" general-header field is used to include implementation- 1071 specific directives that might apply to any recipient along the 1072 request/response chain. All pragma directives specify optional 1073 behavior from the viewpoint of the protocol; however, some systems 1074 MAY require that behavior be consistent with the directives. 1076 Pragma = "Pragma" ":" OWS Pragma-v 1077 Pragma-v = 1#pragma-directive 1078 pragma-directive = "no-cache" / extension-pragma 1079 extension-pragma = token [ "=" ( token / quoted-string ) ] 1081 When the no-cache directive is present in a request message, an 1082 application SHOULD forward the request toward the origin server even 1083 if it has a cached copy of what is being requested. This pragma 1084 directive has the same semantics as the no-cache response directive 1085 (see Section 3.2.2) and is defined here for backward compatibility 1086 with HTTP/1.0. Clients SHOULD include both header fields when a no- 1087 cache request is sent to a server not known to be HTTP/1.1 compliant. 1088 HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had 1089 sent "Cache-Control: no-cache". 1091 Note: Because the meaning of "Pragma: no-cache" as a response- 1092 header field is not actually specified, it does not provide a 1093 reliable replacement for "Cache-Control: no-cache" in a response. 1095 This mechanism is deprecated; no new Pragma directives will be 1096 defined in HTTP. 1098 3.5. Vary 1100 The "Vary" response-header field conveys the set of request-header 1101 fields that were used to select the representation. 1103 Caches use this information, in part, to determine whether a stored 1104 response can be used to satisfy a given request; see Section 2.6. 1105 determines, while the response is fresh, whether a cache is permitted 1106 to use the response to reply to a subsequent request without 1107 validation; see Section 2.6. 1109 In uncacheable or stale responses, the Vary field value advises the 1110 user agent about the criteria that were used to select the 1111 representation. 1113 Vary = "Vary" ":" OWS Vary-v 1114 Vary-v = "*" / 1#field-name 1116 The set of header fields named by the Vary field value is known as 1117 the selecting request-headers. 1119 Servers SHOULD include a Vary header field with any cacheable 1120 response that is subject to server-driven negotiation. Doing so 1121 allows a cache to properly interpret future requests on that resource 1122 and informs the user agent about the presence of negotiation on that 1123 resource. A server MAY include a Vary header field with a non- 1124 cacheable response that is subject to server-driven negotiation, 1125 since this might provide the user agent with useful information about 1126 the dimensions over which the response varies at the time of the 1127 response. 1129 A Vary field value of "*" signals that unspecified parameters not 1130 limited to the request-headers (e.g., the network address of the 1131 client), play a role in the selection of the response representation; 1132 therefore, a cache cannot determine whether this response is 1133 appropriate. The "*" value MUST NOT be generated by a proxy server; 1134 it may only be generated by an origin server. 1136 The field-names given are not limited to the set of standard request- 1137 header fields defined by this specification. Field names are case- 1138 insensitive. 1140 3.6. Warning 1142 The "Warning" general-header field is used to carry additional 1143 information about the status or transformation of a message that 1144 might not be reflected in the message. This information is typically 1145 used to warn about possible incorrectness introduced by caching 1146 operations or transformations applied to the entity body of the 1147 message. 1149 Warnings can be used for other purposes, both cache-related and 1150 otherwise. The use of a warning, rather than an error status code, 1151 distinguishes these responses from true failures. 1153 Warning headers can in general be applied to any message, however 1154 some warn-codes are specific to caches and can only be applied to 1155 response messages. 1157 Warning = "Warning" ":" OWS Warning-v 1158 Warning-v = 1#warning-value 1160 warning-value = warn-code SP warn-agent SP warn-text 1161 [SP warn-date] 1163 warn-code = 3DIGIT 1164 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1165 ; the name or pseudonym of the server adding 1166 ; the Warning header, for use in debugging 1167 warn-text = quoted-string 1168 warn-date = DQUOTE HTTP-date DQUOTE 1170 Multiple warnings can be attached to a response (either by the origin 1171 server or by a cache), including multiple warnings with the same code 1172 number, only differing in warn-text. 1174 When this occurs, the user agent SHOULD inform the user of as many of 1175 them as possible, in the order that they appear in the response. 1177 Systems that generate multiple Warning headers SHOULD order them with 1178 this user agent behavior in mind. New Warning headers SHOULD be 1179 added after any existing Warning headers. 1181 Warnings are assigned three digit warn-codes. The first digit 1182 indicates whether the Warning is required to be deleted from a stored 1183 response after validation: 1185 o 1xx Warnings describe the freshness or validation status of the 1186 response, and so MUST be deleted by caches after validation. They 1187 can only be generated by a cache when validating a cached entry, 1188 and MUST NOT be generated in any other situation. 1190 o 2xx Warnings describe some aspect of the entity body or entity 1191 headers that is not rectified by a validation (for example, a 1192 lossy compression of the entity bodies) and MUST NOT be deleted by 1193 caches after validation, unless a full response is returned, in 1194 which case they MUST be. 1196 If an implementation sends a message with one or more Warning headers 1197 to a receiver whose version is HTTP/1.0 or lower, then the sender 1198 MUST include in each warning-value a warn-date that matches the Date 1199 header in the message. 1201 If an implementation receives a message with a warning-value that 1202 includes a warn-date, and that warn-date is different from the Date 1203 value in the response, then that warning-value MUST be deleted from 1204 the message before storing, forwarding, or using it. (preventing the 1205 consequences of naive caching of Warning header fields.) If all of 1206 the warning-values are deleted for this reason, the Warning header 1207 MUST be deleted as well. 1209 The following warn-codes are defined by this specification, each with 1210 a recommended warn-text in English, and a description of its meaning. 1212 110 Response is stale 1214 SHOULD be included whenever the returned response is stale. 1216 111 Revalidation failed 1218 SHOULD be included if a cache returns a stale response because an 1219 attempt to validate the response failed, due to an inability to 1220 reach the server. 1222 112 Disconnected operation 1224 SHOULD be included if the cache is intentionally disconnected from 1225 the rest of the network for a period of time. 1227 113 Heuristic expiration 1229 SHOULD be included if the cache heuristically chose a freshness 1230 lifetime greater than 24 hours and the response's age is greater 1231 than 24 hours. 1233 199 Miscellaneous warning 1235 The warning text can include arbitrary information to be presented 1236 to a human user, or logged. A system receiving this warning MUST 1237 NOT take any automated action, besides presenting the warning to 1238 the user. 1240 214 Transformation applied 1242 MUST be added by an intermediate cache or proxy if it applies any 1243 transformation changing the content-coding (as specified in the 1244 Content-Encoding header) or media-type (as specified in the 1245 Content-Type header) of the response, or the entity-body of the 1246 response, unless this Warning code already appears in the 1247 response. 1249 299 Miscellaneous persistent warning 1251 The warning text can include arbitrary information to be presented 1252 to a human user, or logged. A system receiving this warning MUST 1253 NOT take any automated action. 1255 4. History Lists 1257 User agents often have history mechanisms, such as "Back" buttons and 1258 history lists, that can be used to redisplay an entity retrieved 1259 earlier in a session. 1261 The freshness model (Section 2.3) does not necessarily apply to 1262 history mechanisms. I.e., a history mechanism can display a previous 1263 representation even if it has expired. 1265 This does not prohibit the history mechanism from telling the user 1266 that a view might be stale, or from honoring cache directives (e.g., 1267 Cache-Control: no-store). 1269 5. IANA Considerations 1271 5.1. Message Header Registration 1273 The Message Header Registry located at should be 1275 updated with the permanent registrations below (see [RFC3864]): 1277 +-------------------+----------+----------+-------------+ 1278 | Header Field Name | Protocol | Status | Reference | 1279 +-------------------+----------+----------+-------------+ 1280 | Age | http | standard | Section 3.1 | 1281 | Cache-Control | http | standard | Section 3.2 | 1282 | Expires | http | standard | Section 3.3 | 1283 | Pragma | http | standard | Section 3.4 | 1284 | Vary | http | standard | Section 3.5 | 1285 | Warning | http | standard | Section 3.6 | 1286 +-------------------+----------+----------+-------------+ 1288 The change controller is: "IETF (iesg@ietf.org) - Internet 1289 Engineering Task Force". 1291 6. Security Considerations 1293 Caches expose additional potential vulnerabilities, since the 1294 contents of the cache represent an attractive target for malicious 1295 exploitation. Because cache contents persist after an HTTP request 1296 is complete, an attack on the cache can reveal information long after 1297 a user believes that the information has been removed from the 1298 network. Therefore, cache contents should be protected as sensitive 1299 information. 1301 7. Acknowledgments 1303 Much of the content and presentation of the caching design is due to 1304 suggestions and comments from individuals including: Shel Kaphan, 1305 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 1307 8. References 1309 8.1. Normative References 1311 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1312 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1313 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 1314 and Message Parsing", draft-ietf-httpbis-p1-messaging-09 1315 (work in progress), March 2010. 1317 [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1318 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1319 and J. Reschke, Ed., "HTTP/1.1, part 2: Message 1320 Semantics", draft-ietf-httpbis-p2-semantics-09 (work in 1321 progress), March 2010. 1323 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1324 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1325 and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional 1326 Requests", draft-ietf-httpbis-p4-conditional-09 (work in 1327 progress), March 2010. 1329 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1330 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1331 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 1332 Partial Responses", draft-ietf-httpbis-p5-range-09 (work 1333 in progress), March 2010. 1335 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1336 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1337 and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", 1338 draft-ietf-httpbis-p7-auth-09 (work in progress), 1339 March 2010. 1341 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1342 Requirement Levels", BCP 14, RFC 2119, March 1997. 1344 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1345 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1347 8.2. Informative References 1349 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1350 Specification, Implementation", RFC 1305, March 1992. 1352 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1353 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1354 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1356 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1357 Procedures for Message Header Fields", BCP 90, RFC 3864, 1358 September 2004. 1360 Appendix A. Compatibility with Previous Versions 1362 A.1. Changes from RFC 2068 1364 A case was missed in the Cache-Control model of HTTP/1.1; s-maxage 1365 was introduced to add this missing case. (Sections 2.1, 3.2). 1367 Range request responses would become very verbose if all meta-data 1368 were always returned; by allowing the server to only send needed 1369 headers in a 206 response, this problem can be avoided. 1370 (Section 2.7) 1372 The Cache-Control: max-age directive was not properly defined for 1373 responses. (Section 3.2.2) 1375 Warnings could be cached incorrectly, or not updated appropriately. 1376 (Section 2.3, 2.7, 3.2, and 3.6) Warning also needed to be a general 1377 header, as PUT or other methods may have need for it in requests. 1379 A.2. Changes from RFC 2616 1381 Remove requirement to consider Content-Location in successful 1382 responses in order to determine the appropriate response to use. 1383 (Section 2.4) 1385 Clarify denial of service attack avoidance requirement. 1386 (Section 2.5) 1387 Do not mention RFC 2047 encoding and multiple languages in Warning 1388 headers anymore, as these aspects never were implemented. 1389 (Section 3.6) 1391 Appendix B. Collected ABNF 1393 Age = "Age:" OWS Age-v 1394 Age-v = delta-seconds 1396 Cache-Control = "Cache-Control:" OWS Cache-Control-v 1397 Cache-Control-v = *( "," OWS ) cache-directive *( OWS "," [ OWS 1398 cache-directive ] ) 1400 Expires = "Expires:" OWS Expires-v 1401 Expires-v = HTTP-date 1403 HTTP-date = 1405 OWS = 1407 Pragma = "Pragma:" OWS Pragma-v 1408 Pragma-v = *( "," OWS ) pragma-directive *( OWS "," [ OWS 1409 pragma-directive ] ) 1411 Vary = "Vary:" OWS Vary-v 1412 Vary-v = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name 1413 ] ) ) 1415 Warning = "Warning:" OWS Warning-v 1416 Warning-v = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value 1417 ] ) 1419 cache-directive = cache-request-directive / cache-response-directive 1420 cache-extension = token [ "=" ( token / quoted-string ) ] 1421 cache-request-directive = "no-cache" / "no-store" / ( "max-age=" 1422 delta-seconds ) / ( "max-stale" [ "=" delta-seconds ] ) / ( 1423 "min-fresh=" delta-seconds ) / "no-transform" / "only-if-cached" / 1424 cache-extension 1425 cache-response-directive = "public" / ( "private" [ "=" DQUOTE *( "," 1426 OWS ) field-name *( OWS "," [ OWS field-name ] ) DQUOTE ] ) / ( 1427 "no-cache" [ "=" DQUOTE *( "," OWS ) field-name *( OWS "," [ OWS 1428 field-name ] ) DQUOTE ] ) / "no-store" / "no-transform" / 1429 "must-revalidate" / "proxy-revalidate" / ( "max-age=" delta-seconds 1430 ) / ( "s-maxage=" delta-seconds ) / cache-extension 1432 delta-seconds = 1*DIGIT 1433 extension-pragma = token [ "=" ( token / quoted-string ) ] 1435 field-name = 1437 port = 1438 pragma-directive = "no-cache" / extension-pragma 1439 pseudonym = 1441 quoted-string = 1443 token = 1445 uri-host = 1447 warn-agent = ( uri-host [ ":" port ] ) / pseudonym 1448 warn-code = 3DIGIT 1449 warn-date = DQUOTE HTTP-date DQUOTE 1450 warn-text = quoted-string 1451 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date 1452 ] 1454 ABNF diagnostics: 1456 ; Age defined but not used 1457 ; Cache-Control defined but not used 1458 ; Expires defined but not used 1459 ; Pragma defined but not used 1460 ; Vary defined but not used 1461 ; Warning defined but not used 1463 Appendix C. Change Log (to be removed by RFC Editor before publication) 1465 C.1. Since RFC2616 1467 Extracted relevant partitions from [RFC2616]. 1469 C.2. Since draft-ietf-httpbis-p6-cache-00 1471 Closed issues: 1473 o : "Trailer" 1474 () 1476 o : "Invalidation 1477 after Update or Delete" 1478 () 1480 o : "Normative and 1481 Informative references" 1483 o : "Date reference 1484 typo" 1486 o : "Connection 1487 header text" 1489 o : "Informative 1490 references" 1492 o : "ISO-8859-1 1493 Reference" 1495 o : "Normative up- 1496 to-date references" 1498 o : "typo in 1499 13.2.2" 1501 Other changes: 1503 o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress 1504 on ) 1506 C.3. Since draft-ietf-httpbis-p6-cache-01 1508 Closed issues: 1510 o : "rel_path not 1511 used" 1513 Other changes: 1515 o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work 1516 in progress on ) 1518 o Add explicit references to BNF syntax and rules imported from 1519 other parts of the specification. 1521 C.4. Since draft-ietf-httpbis-p6-cache-02 1523 Ongoing work on IANA Message Header Registration 1524 (): 1526 o Reference RFC 3984, and update header registrations for headers 1527 defined in this document. 1529 C.5. Since draft-ietf-httpbis-p6-cache-03 1531 Closed issues: 1533 o : "Vary header 1534 classification" 1536 C.6. Since draft-ietf-httpbis-p6-cache-04 1538 Ongoing work on ABNF conversion 1539 (): 1541 o Use "/" instead of "|" for alternatives. 1543 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1544 whitespace ("OWS") and required whitespace ("RWS"). 1546 o Rewrite ABNFs to spell out whitespace rules, factor out header 1547 value format definitions. 1549 C.7. Since draft-ietf-httpbis-p6-cache-05 1551 This is a total rewrite of this part of the specification. 1553 Affected issues: 1555 o : "Definition of 1556 1xx Warn-Codes" 1558 o : "Placement 1559 of 13.5.1 and 13.5.2" 1561 o : "The role 1562 of Warning and Semantic Transparency in Caching" 1564 o : "Methods 1565 and Caching" 1567 In addition: Final work on ABNF conversion 1568 (): 1570 o Add appendix containing collected and expanded ABNF, reorganize 1571 ABNF introduction. 1573 C.8. Since draft-ietf-httpbis-p6-cache-06 1575 Closed issues: 1577 o : "base for 1578 numeric protocol elements" 1580 Affected issues: 1582 o : Vary and non- 1583 existant headers 1585 C.9. Since draft-ietf-httpbis-p6-cache-07 1587 Closed issues: 1589 o : "Definition of 1590 1xx Warn-Codes" 1592 o : "Content- 1593 Location on 304 responses" 1595 o : "private and 1596 no-cache CC directives with headers" 1598 o : "RFC2047 and 1599 warn-text" 1601 C.10. Since draft-ietf-httpbis-p6-cache-08 1603 Closed issues: 1605 o : "serving 1606 negotiated responses from cache: header-specific canonicalization" 1608 o : "Effect of CC 1609 directives on history lists" 1611 Affected issues: 1613 o : Status codes 1614 and caching 1616 Partly resolved issues: 1618 o : "Placement of 1619 13.5.1 and 13.5.2" 1621 Index 1623 A 1624 age 6 1625 Age header 17 1627 C 1628 cache 5 1629 Cache Directives 1630 max-age 19, 22 1631 max-stale 19 1632 min-fresh 19 1633 must-revalidate 21 1634 no-cache 18, 21 1635 no-store 18, 21 1636 no-transform 19, 22 1637 only-if-cached 19 1638 private 20 1639 proxy-revalidate 22 1640 public 20 1641 s-maxage 22 1642 Cache-Control header 18 1643 cacheable 5 1645 E 1646 Expires header 23 1647 explicit expiration time 5 1649 F 1650 first-hand 6 1651 fresh 6 1652 freshness lifetime 6 1654 G 1655 Grammar 1656 Age 17 1657 Age-v 17 1658 Cache-Control 18 1659 Cache-Control-v 18 1660 cache-extension 18 1661 cache-request-directive 18 1662 cache-response-directive 20 1663 delta-seconds 17 1664 Expires 23 1665 Expires-v 23 1666 extension-pragma 24 1667 Pragma 24 1668 pragma-directive 24 1669 Pragma-v 24 1670 Vary 25 1671 Vary-v 25 1672 warn-agent 26 1673 warn-code 26 1674 warn-date 26 1675 warn-text 26 1676 Warning 26 1677 Warning-v 26 1678 warning-value 26 1680 H 1681 Headers 1682 Age 17 1683 Cache-Control 18 1684 Expires 23 1685 Pragma 24 1686 Vary 24 1687 Warning 25 1688 heuristic expiration time 5 1690 M 1691 max-age 1692 Cache Directive 19, 22 1693 max-stale 1694 Cache Directive 19 1695 min-fresh 1696 Cache Directive 19 1697 must-revalidate 1698 Cache Directive 21 1700 N 1701 no-cache 1702 Cache Directive 18, 21 1703 no-store 1704 Cache Directive 18, 21 1705 no-transform 1706 Cache Directive 19, 22 1708 O 1709 only-if-cached 1710 Cache Directive 19 1712 P 1713 Pragma header 24 1714 private 1715 Cache Directive 20 1716 proxy-revalidate 1717 Cache Directive 22 1718 public 1719 Cache Directive 20 1721 S 1722 s-maxage 1723 Cache Directive 22 1724 stale 6 1726 V 1727 validator 6 1728 Vary header 24 1730 W 1731 Warning header 25 1733 Authors' Addresses 1735 Roy T. Fielding (editor) 1736 Day Software 1737 23 Corporate Plaza DR, Suite 280 1738 Newport Beach, CA 92660 1739 USA 1741 Phone: +1-949-706-5300 1742 Fax: +1-949-706-5305 1743 Email: fielding@gbiv.com 1744 URI: http://roy.gbiv.com/ 1746 Jim Gettys 1747 One Laptop per Child 1748 21 Oak Knoll Road 1749 Carlisle, MA 01741 1750 USA 1752 Email: jg@laptop.org 1753 URI: http://www.laptop.org/ 1754 Jeffrey C. Mogul 1755 Hewlett-Packard Company 1756 HP Labs, Large Scale Systems Group 1757 1501 Page Mill Road, MS 1177 1758 Palo Alto, CA 94304 1759 USA 1761 Email: JeffMogul@acm.org 1763 Henrik Frystyk Nielsen 1764 Microsoft Corporation 1765 1 Microsoft Way 1766 Redmond, WA 98052 1767 USA 1769 Email: henrikn@microsoft.com 1771 Larry Masinter 1772 Adobe Systems, Incorporated 1773 345 Park Ave 1774 San Jose, CA 95110 1775 USA 1777 Email: LMM@acm.org 1778 URI: http://larry.masinter.net/ 1780 Paul J. Leach 1781 Microsoft Corporation 1782 1 Microsoft Way 1783 Redmond, WA 98052 1785 Email: paulle@microsoft.com 1787 Tim Berners-Lee 1788 World Wide Web Consortium 1789 MIT Computer Science and Artificial Intelligence Laboratory 1790 The Stata Center, Building 32 1791 32 Vassar Street 1792 Cambridge, MA 02139 1793 USA 1795 Email: timbl@w3.org 1796 URI: http://www.w3.org/People/Berners-Lee/ 1797 Yves Lafon (editor) 1798 World Wide Web Consortium 1799 W3C / ERCIM 1800 2004, rte des Lucioles 1801 Sophia-Antipolis, AM 06902 1802 France 1804 Email: ylafon@w3.org 1805 URI: http://www.raubacapeu.net/people/yves/ 1807 Mark Nottingham (editor) 1809 Email: mnot@mnot.net 1810 URI: http://www.mnot.net/ 1812 Julian F. Reschke (editor) 1813 greenbytes GmbH 1814 Hafenweg 16 1815 Muenster, NW 48155 1816 Germany 1818 Phone: +49 251 2807760 1819 Fax: +49 251 2807761 1820 Email: julian.reschke@greenbytes.de 1821 URI: http://greenbytes.de/tech/webdav/