idnits 2.17.1 draft-ietf-httpbis-p4-conditional-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 30. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 993. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1004. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1011. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1017. 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 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 17, 2008) is 5792 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-03 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-03 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-03 -- Obsolete informational reference (is this intentional?): RFC 2068 (Obsoleted by RFC 2616) -- 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 (~~), 4 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network 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: December 19, 2008 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 J. Reschke, Ed. 19 greenbytes 20 June 17, 2008 22 HTTP/1.1, part 4: Conditional Requests 23 draft-ietf-httpbis-p4-conditional-03 25 Status of this Memo 27 By submitting this Internet-Draft, each author represents that any 28 applicable patent or other IPR claims of which he or she is aware 29 have been or will be disclosed, and any of which he or she becomes 30 aware will be disclosed, in accordance with Section 6 of BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF), its areas, and its working groups. Note that 34 other groups may also distribute working documents as Internet- 35 Drafts. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 The list of current Internet-Drafts can be accessed at 43 http://www.ietf.org/ietf/1id-abstracts.txt. 45 The list of Internet-Draft Shadow Directories can be accessed at 46 http://www.ietf.org/shadow.html. 48 This Internet-Draft will expire on December 19, 2008. 50 Abstract 52 The Hypertext Transfer Protocol (HTTP) is an application-level 53 protocol for distributed, collaborative, hypermedia information 54 systems. HTTP has been in use by the World Wide Web global 55 information initiative since 1990. This document is Part 4 of the 56 seven-part specification that defines the protocol referred to as 57 "HTTP/1.1" and, taken together, obsoletes RFC 2616. Part 4 defines 58 request header fields for indicating conditional requests and the 59 rules for constructing responses to those requests. 61 Editorial Note (To be removed by RFC Editor) 63 Discussion of this draft should take place on the HTTPBIS working 64 group mailing list (ietf-http-wg@w3.org). The current issues list is 65 at and related 66 documents (including fancy diffs) can be found at 67 . 69 The changes in this draft are summarized in Appendix B.4. 71 Table of Contents 73 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 74 1.1. Requirements . . . . . . . . . . . . . . . . . . . . . . . 4 75 2. Notational Conventions and Generic Grammar . . . . . . . . . . 4 76 3. Entity Tags . . . . . . . . . . . . . . . . . . . . . . . . . 5 77 4. Status Code Definitions . . . . . . . . . . . . . . . . . . . 5 78 4.1. 304 Not Modified . . . . . . . . . . . . . . . . . . . . . 5 79 4.2. 412 Precondition Failed . . . . . . . . . . . . . . . . . 6 80 5. Weak and Strong Validators . . . . . . . . . . . . . . . . . . 6 81 6. Rules for When to Use Entity Tags and Last-Modified Dates . . 9 82 7. Header Field Definitions . . . . . . . . . . . . . . . . . . . 11 83 7.1. ETag . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 84 7.2. If-Match . . . . . . . . . . . . . . . . . . . . . . . . . 11 85 7.3. If-Modified-Since . . . . . . . . . . . . . . . . . . . . 13 86 7.4. If-None-Match . . . . . . . . . . . . . . . . . . . . . . 14 87 7.5. If-Unmodified-Since . . . . . . . . . . . . . . . . . . . 15 88 7.6. Last-Modified . . . . . . . . . . . . . . . . . . . . . . 16 89 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 90 8.1. Message Header Registration . . . . . . . . . . . . . . . 17 91 9. Security Considerations . . . . . . . . . . . . . . . . . . . 17 92 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 93 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 94 11.1. Normative References . . . . . . . . . . . . . . . . . . . 18 95 11.2. Informative References . . . . . . . . . . . . . . . . . . 18 96 Appendix A. Compatibility with Previous Versions . . . . . . . . 18 97 A.1. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 18 98 Appendix B. Change Log (to be removed by RFC Editor before 99 publication) . . . . . . . . . . . . . . . . . . . . 19 100 B.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 19 101 B.2. Since draft-ietf-httpbis-p4-conditional-00 . . . . . . . . 19 102 B.3. Since draft-ietf-httpbis-p4-conditional-01 . . . . . . . . 19 103 B.4. Since draft-ietf-httpbis-p4-conditional-02 . . . . . . . . 19 104 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 20 106 Intellectual Property and Copyright Statements . . . . . . . . . . 24 108 1. Introduction 110 This document defines HTTP/1.1 response metadata for indicating 111 potential changes to payload content, including modification time 112 stamps and opaque entity-tags, and the HTTP conditional request 113 mechanisms that allow preconditions to be placed on a request method. 114 Conditional GET requests allow for efficient cache updates. Other 115 conditional request methods are used to protect against overwriting 116 or misunderstanding the state of a resource that has been changed 117 unbeknownst to the requesting client. 119 This document is currently disorganized in order to minimize the 120 changes between drafts and enable reviewers to see the smaller errata 121 changes. The next draft will reorganize the sections to better 122 reflect the content. In particular, the sections on resource 123 metadata will be discussed first and then followed by each 124 conditional request-header, concluding with a definition of 125 precedence and the expectation of ordering strong validator checks 126 before weak validator checks. It is likely that more content from 127 [Part6] will migrate to this part, where appropriate. The current 128 mess reflects how widely dispersed these topics and associated 129 requirements had become in [RFC2616]. 131 1.1. Requirements 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 135 document are to be interpreted as described in [RFC2119]. 137 An implementation is not compliant if it fails to satisfy one or more 138 of the MUST or REQUIRED level requirements for the protocols it 139 implements. An implementation that satisfies all the MUST or 140 REQUIRED level and all the SHOULD level requirements for its 141 protocols is said to be "unconditionally compliant"; one that 142 satisfies all the MUST level requirements but not all the SHOULD 143 level requirements for its protocols is said to be "conditionally 144 compliant." 146 2. Notational Conventions and Generic Grammar 148 This specification uses the ABNF syntax defined in Section 2.1 of 149 [Part1] and the core rules defined in Section 2.2 of [Part1]: 150 [[abnf.dep: ABNF syntax and basic rules will be adopted from RFC 151 5234, see .]] 153 quoted-string = 155 The ABNF rules below are defined in other parts: 157 HTTP-date = 159 3. Entity Tags 161 Entity tags are used for comparing two or more entities from the same 162 requested resource. HTTP/1.1 uses entity tags in the ETag 163 (Section 7.1), If-Match (Section 7.2), If-None-Match (Section 7.4), 164 and If-Range (Section 6.3 of [Part5]) header fields. The definition 165 of how they are used and compared as cache validators is in 166 Section 5. An entity tag consists of an opaque quoted string, 167 possibly prefixed by a weakness indicator. 169 entity-tag = [ weak ] opaque-tag 170 weak = "W/" 171 opaque-tag = quoted-string 173 A "strong entity tag" MAY be shared by two entities of a resource 174 only if they are equivalent by octet equality. 176 A "weak entity tag," indicated by the "W/" prefix, MAY be shared by 177 two entities of a resource only if the entities are equivalent and 178 could be substituted for each other with no significant change in 179 semantics. A weak entity tag can only be used for weak comparison. 181 An entity tag MUST be unique across all versions of all entities 182 associated with a particular resource. A given entity tag value MAY 183 be used for entities obtained by requests on different URIs. The use 184 of the same entity tag value in conjunction with entities obtained by 185 requests on different URIs does not imply the equivalence of those 186 entities. 188 4. Status Code Definitions 190 4.1. 304 Not Modified 192 If the client has performed a conditional GET request and access is 193 allowed, but the document has not been modified, the server SHOULD 194 respond with this status code. The 304 response MUST NOT contain a 195 message-body, and thus is always terminated by the first empty line 196 after the header fields. 198 The response MUST include the following header fields: 200 o Date, unless its omission is required by Section 8.3.1 of [Part1] 202 If a clockless origin server obeys these rules, and proxies and 203 clients add their own Date to any response received without one (as 204 already specified by [RFC2068], Section 14.19), caches will operate 205 correctly. 207 o ETag and/or Content-Location, if the header would have been sent 208 in a 200 response to the same request 210 o Expires, Cache-Control, and/or Vary, if the field-value might 211 differ from that sent in any previous response for the same 212 variant 214 If the conditional GET used a strong cache validator (see Section 5), 215 the response SHOULD NOT include other entity-headers. Otherwise 216 (i.e., the conditional GET used a weak validator), the response MUST 217 NOT include other entity-headers; this prevents inconsistencies 218 between cached entity-bodies and updated headers. 220 If a 304 response indicates an entity not currently cached, then the 221 cache MUST disregard the response and repeat the request without the 222 conditional. 224 If a cache uses a received 304 response to update a cache entry, the 225 cache MUST update the entry to reflect any new field values given in 226 the response. 228 4.2. 412 Precondition Failed 230 The precondition given in one or more of the request-header fields 231 evaluated to false when it was tested on the server. This response 232 code allows the client to place preconditions on the current resource 233 metainformation (header field data) and thus prevent the requested 234 method from being applied to a resource other than the one intended. 236 5. Weak and Strong Validators 238 Since both origin servers and caches will compare two validators to 239 decide if they represent the same or different entities, one normally 240 would expect that if the entity (the entity-body or any entity- 241 headers) changes in any way, then the associated validator would 242 change as well. If this is true, then we call this validator a 243 "strong validator." 245 However, there might be cases when a server prefers to change the 246 validator only on semantically significant changes, and not when 247 insignificant aspects of the entity change. A validator that does 248 not always change when the resource changes is a "weak validator." 250 Entity tags are normally "strong validators," but the protocol 251 provides a mechanism to tag an entity tag as "weak." One can think 252 of a strong validator as one that changes whenever the bits of an 253 entity changes, while a weak value changes whenever the meaning of an 254 entity changes. Alternatively, one can think of a strong validator 255 as part of an identifier for a specific entity, while a weak 256 validator is part of an identifier for a set of semantically 257 equivalent entities. 259 Note: One example of a strong validator is an integer that is 260 incremented in stable storage every time an entity is changed. 262 An entity's modification time, if represented with one-second 263 resolution, could be a weak validator, since it is possible that 264 the resource might be modified twice during a single second. 266 Support for weak validators is optional. However, weak validators 267 allow for more efficient caching of equivalent objects; for 268 example, a hit counter on a site is probably good enough if it is 269 updated every few days or weeks, and any value during that period 270 is likely "good enough" to be equivalent. 272 A "use" of a validator is either when a client generates a request 273 and includes the validator in a validating header field, or when a 274 server compares two validators. 276 Strong validators are usable in any context. Weak validators are 277 only usable in contexts that do not depend on exact equality of an 278 entity. For example, either kind is usable for a conditional GET of 279 a full entity. However, only a strong validator is usable for a sub- 280 range retrieval, since otherwise the client might end up with an 281 internally inconsistent entity. 283 Clients MUST NOT use weak validators in range requests ([Part5]). 285 The only function that HTTP/1.1 defines on validators is comparison. 286 There are two validator comparison functions, depending on whether 287 the comparison context allows the use of weak validators or not: 289 o The strong comparison function: in order to be considered equal, 290 both validators MUST be identical in every way, and both MUST NOT 291 be weak. 293 o The weak comparison function: in order to be considered equal, 294 both validators MUST be identical in every way, but either or both 295 of them MAY be tagged as "weak" without affecting the result. 297 An entity tag is strong unless it is explicitly tagged as weak. 298 Section 3 gives the syntax for entity tags. 300 A Last-Modified time, when used as a validator in a request, is 301 implicitly weak unless it is possible to deduce that it is strong, 302 using the following rules: 304 o The validator is being compared by an origin server to the actual 305 current validator for the entity and, 307 o That origin server reliably knows that the associated entity did 308 not change twice during the second covered by the presented 309 validator. 311 or 313 o The validator is about to be used by a client in an If-Modified- 314 Since or If-Unmodified-Since header, because the client has a 315 cache entry for the associated entity, and 317 o That cache entry includes a Date value, which gives the time when 318 the origin server sent the original response, and 320 o The presented Last-Modified time is at least 60 seconds before the 321 Date value. 323 or 325 o The validator is being compared by an intermediate cache to the 326 validator stored in its cache entry for the entity, and 328 o That cache entry includes a Date value, which gives the time when 329 the origin server sent the original response, and 331 o The presented Last-Modified time is at least 60 seconds before the 332 Date value. 334 This method relies on the fact that if two different responses were 335 sent by the origin server during the same second, but both had the 336 same Last-Modified time, then at least one of those responses would 337 have a Date value equal to its Last-Modified time. The arbitrary 60- 338 second limit guards against the possibility that the Date and Last- 339 Modified values are generated from different clocks, or at somewhat 340 different times during the preparation of the response. An 341 implementation MAY use a value larger than 60 seconds, if it is 342 believed that 60 seconds is too short. 344 If a client wishes to perform a sub-range retrieval on a value for 345 which it has only a Last-Modified time and no opaque validator, it 346 MAY do this only if the Last-Modified time is strong in the sense 347 described here. 349 A cache or origin server receiving a conditional range request 350 ([Part5]) MUST use the strong comparison function to evaluate the 351 condition. 353 These rules allow HTTP/1.1 caches and clients to safely perform sub- 354 range retrievals on values that have been obtained from HTTP/1.0 355 servers. 357 6. Rules for When to Use Entity Tags and Last-Modified Dates 359 We adopt a set of rules and recommendations for origin servers, 360 clients, and caches regarding when various validator types ought to 361 be used, and for what purposes. 363 HTTP/1.1 origin servers: 365 o SHOULD send an entity tag validator unless it is not feasible to 366 generate one. 368 o MAY send a weak entity tag instead of a strong entity tag, if 369 performance considerations support the use of weak entity tags, or 370 if it is unfeasible to send a strong entity tag. 372 o SHOULD send a Last-Modified value if it is feasible to send one, 373 unless the risk of a breakdown in semantic transparency that could 374 result from using this date in an If-Modified-Since header would 375 lead to serious problems. 377 In other words, the preferred behavior for an HTTP/1.1 origin server 378 is to send both a strong entity tag and a Last-Modified value. 380 In order to be legal, a strong entity tag MUST change whenever the 381 associated entity value changes in any way. A weak entity tag SHOULD 382 change whenever the associated entity changes in a semantically 383 significant way. 385 Note: in order to provide semantically transparent caching, an 386 origin server must avoid reusing a specific strong entity tag 387 value for two different entities, or reusing a specific weak 388 entity tag value for two semantically different entities. Cache 389 entries might persist for arbitrarily long periods, regardless of 390 expiration times, so it might be inappropriate to expect that a 391 cache will never again attempt to validate an entry using a 392 validator that it obtained at some point in the past. 394 HTTP/1.1 clients: 396 o If an entity tag has been provided by the origin server, MUST use 397 that entity tag in any cache-conditional request (using If-Match 398 or If-None-Match). 400 o If only a Last-Modified value has been provided by the origin 401 server, SHOULD use that value in non-subrange cache-conditional 402 requests (using If-Modified-Since). 404 o If only a Last-Modified value has been provided by an HTTP/1.0 405 origin server, MAY use that value in subrange cache-conditional 406 requests (using If-Unmodified-Since:). The user agent SHOULD 407 provide a way to disable this, in case of difficulty. 409 o If both an entity tag and a Last-Modified value have been provided 410 by the origin server, SHOULD use both validators in cache- 411 conditional requests. This allows both HTTP/1.0 and HTTP/1.1 412 caches to respond appropriately. 414 An HTTP/1.1 origin server, upon receiving a conditional request that 415 includes both a Last-Modified date (e.g., in an If-Modified-Since or 416 If-Unmodified-Since header field) and one or more entity tags (e.g., 417 in an If-Match, If-None-Match, or If-Range header field) as cache 418 validators, MUST NOT return a response status of 304 (Not Modified) 419 unless doing so is consistent with all of the conditional header 420 fields in the request. 422 An HTTP/1.1 caching proxy, upon receiving a conditional request that 423 includes both a Last-Modified date and one or more entity tags as 424 cache validators, MUST NOT return a locally cached response to the 425 client unless that cached response is consistent with all of the 426 conditional header fields in the request. 428 Note: The general principle behind these rules is that HTTP/1.1 429 servers and clients should transmit as much non-redundant 430 information as is available in their responses and requests. 431 HTTP/1.1 systems receiving this information will make the most 432 conservative assumptions about the validators they receive. 434 HTTP/1.0 clients and caches will ignore entity tags. Generally, 435 last-modified values received or used by these systems will 436 support transparent and efficient caching, and so HTTP/1.1 origin 437 servers should provide Last-Modified values. In those rare cases 438 where the use of a Last-Modified value as a validator by an 439 HTTP/1.0 system could result in a serious problem, then HTTP/1.1 440 origin servers should not provide one. 442 7. Header Field Definitions 444 This section defines the syntax and semantics of HTTP/1.1 header 445 fields related to conditional requests. 447 For entity-header fields, both sender and recipient refer to either 448 the client or the server, depending on who sends and who receives the 449 entity. 451 7.1. ETag 453 The ETag response-header field provides the current value of the 454 entity tag for the requested variant. The headers used with entity 455 tags are described in Sections 7.2 and 7.4 of this document, and in 456 Section 6.3 of [Part5]. The entity tag MAY be used for comparison 457 with other entities from the same resource (see Section 5). 459 ETag = "ETag" ":" entity-tag 461 Examples: 463 ETag: "xyzzy" 464 ETag: W/"xyzzy" 465 ETag: "" 467 The ETag response-header field value, an entity tag, provides for an 468 "opaque" cache validator. This might allow more reliable validation 469 in situations where it is inconvenient to store modification dates, 470 where the one-second resolution of HTTP date values is not 471 sufficient, or where the origin server wishes to avoid certain 472 paradoxes that might arise from the use of modification dates. 474 The principle behind entity tags is that only the service author 475 knows the semantics of a resource well enough to select an 476 appropriate cache validation mechanism, and the specification of any 477 validator comparison function more complex than byte-equality would 478 open up a can of worms. Thus, comparisons of any other headers 479 (except Last-Modified, for compatibility with HTTP/1.0) are never 480 used for purposes of validating a cache entry. 482 7.2. If-Match 484 The If-Match request-header field is used with a method to make it 485 conditional. A client that has one or more entities previously 486 obtained from the resource can verify that one of those entities is 487 current by including a list of their associated entity tags in the 488 If-Match header field. Entity tags are defined in Section 3. The 489 purpose of this feature is to allow efficient updates of cached 490 information with a minimum amount of transaction overhead. It is 491 also used, on updating requests, to prevent inadvertent modification 492 of the wrong version of a resource. As a special case, the value "*" 493 matches any current entity of the resource. 495 If-Match = "If-Match" ":" ( "*" | 1#entity-tag ) 497 If any of the entity tags match the entity tag of the entity that 498 would have been returned in the response to a similar GET request 499 (without the If-Match header) on that resource, or if "*" is given 500 and any current entity exists for that resource, then the server MAY 501 perform the requested method as if the If-Match header field did not 502 exist. 504 A server MUST use the strong comparison function (see Section 5) to 505 compare the entity tags in If-Match. 507 If none of the entity tags match, or if "*" is given and no current 508 entity exists, the server MUST NOT perform the requested method, and 509 MUST return a 412 (Precondition Failed) response. This behavior is 510 most useful when the client wants to prevent an updating method, such 511 as PUT, from modifying a resource that has changed since the client 512 last retrieved it. 514 If the request would, without the If-Match header field, result in 515 anything other than a 2xx or 412 status, then the If-Match header 516 MUST be ignored. 518 The meaning of "If-Match: *" is that the method SHOULD be performed 519 if the representation selected by the origin server (or by a cache, 520 possibly using the Vary mechanism, see Section 16.5 of [Part6]) 521 exists, and MUST NOT be performed if the representation does not 522 exist. 524 A request intended to update a resource (e.g., a PUT) MAY include an 525 If-Match header field to signal that the request method MUST NOT be 526 applied if the entity corresponding to the If-Match value (a single 527 entity tag) is no longer a representation of that resource. This 528 allows the user to indicate that they do not wish the request to be 529 successful if the resource has been changed without their knowledge. 530 Examples: 532 If-Match: "xyzzy" 533 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 534 If-Match: * 536 The result of a request having both an If-Match header field and 537 either an If-None-Match or an If-Modified-Since header fields is 538 undefined by this specification. 540 7.3. If-Modified-Since 542 The If-Modified-Since request-header field is used with a method to 543 make it conditional: if the requested variant has not been modified 544 since the time specified in this field, an entity will not be 545 returned from the server; instead, a 304 (Not Modified) response will 546 be returned without any message-body. 548 If-Modified-Since = "If-Modified-Since" ":" HTTP-date 550 An example of the field is: 552 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 554 A GET method with an If-Modified-Since header and no Range header 555 requests that the identified entity be transferred only if it has 556 been modified since the date given by the If-Modified-Since header. 557 The algorithm for determining this includes the following cases: 559 1. If the request would normally result in anything other than a 200 560 (OK) status, or if the passed If-Modified-Since date is invalid, 561 the response is exactly the same as for a normal GET. A date 562 which is later than the server's current time is invalid. 564 2. If the variant has been modified since the If-Modified-Since 565 date, the response is exactly the same as for a normal GET. 567 3. If the variant has not been modified since a valid If-Modified- 568 Since date, the server SHOULD return a 304 (Not Modified) 569 response. 571 The purpose of this feature is to allow efficient updates of cached 572 information with a minimum amount of transaction overhead. 574 Note: The Range request-header field modifies the meaning of If- 575 Modified-Since; see Section 6.4 of [Part5] for full details. 577 Note: If-Modified-Since times are interpreted by the server, whose 578 clock might not be synchronized with the client. 580 Note: When handling an If-Modified-Since header field, some 581 servers will use an exact date comparison function, rather than a 582 less-than function, for deciding whether to send a 304 (Not 583 Modified) response. To get best results when sending an If- 584 Modified-Since header field for cache validation, clients are 585 advised to use the exact date string received in a previous Last- 586 Modified header field whenever possible. 588 Note: If a client uses an arbitrary date in the If-Modified-Since 589 header instead of a date taken from the Last-Modified header for 590 the same request, the client should be aware of the fact that this 591 date is interpreted in the server's understanding of time. The 592 client should consider unsynchronized clocks and rounding problems 593 due to the different encodings of time between the client and 594 server. This includes the possibility of race conditions if the 595 document has changed between the time it was first requested and 596 the If-Modified-Since date of a subsequent request, and the 597 possibility of clock-skew-related problems if the If-Modified- 598 Since date is derived from the client's clock without correction 599 to the server's clock. Corrections for different time bases 600 between client and server are at best approximate due to network 601 latency. 603 The result of a request having both an If-Modified-Since header field 604 and either an If-Match or an If-Unmodified-Since header fields is 605 undefined by this specification. 607 7.4. If-None-Match 609 The If-None-Match request-header field is used with a method to make 610 it conditional. A client that has one or more entities previously 611 obtained from the resource can verify that none of those entities is 612 current by including a list of their associated entity tags in the 613 If-None-Match header field. The purpose of this feature is to allow 614 efficient updates of cached information with a minimum amount of 615 transaction overhead. It is also used to prevent a method (e.g. 616 PUT) from inadvertently modifying an existing resource when the 617 client believes that the resource does not exist. 619 As a special case, the value "*" matches any current entity of the 620 resource. 622 If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag ) 624 If any of the entity tags match the entity tag of the entity that 625 would have been returned in the response to a similar GET request 626 (without the If-None-Match header) on that resource, or if "*" is 627 given and any current entity exists for that resource, then the 628 server MUST NOT perform the requested method, unless required to do 629 so because the resource's modification date fails to match that 630 supplied in an If-Modified-Since header field in the request. 631 Instead, if the request method was GET or HEAD, the server SHOULD 632 respond with a 304 (Not Modified) response, including the cache- 633 related header fields (particularly ETag) of one of the entities that 634 matched. For all other request methods, the server MUST respond with 635 a status of 412 (Precondition Failed). 637 See Section 5 for rules on how to determine if two entity tags match. 639 If none of the entity tags match, then the server MAY perform the 640 requested method as if the If-None-Match header field did not exist, 641 but MUST also ignore any If-Modified-Since header field(s) in the 642 request. That is, if no entity tags match, then the server MUST NOT 643 return a 304 (Not Modified) response. 645 If the request would, without the If-None-Match header field, result 646 in anything other than a 2xx or 304 status, then the If-None-Match 647 header MUST be ignored. (See Section 6 for a discussion of server 648 behavior when both If-Modified-Since and If-None-Match appear in the 649 same request.) 651 The meaning of "If-None-Match: *" is that the method MUST NOT be 652 performed if the representation selected by the origin server (or by 653 a cache, possibly using the Vary mechanism, see Section 16.5 of 654 [Part6]) exists, and SHOULD be performed if the representation does 655 not exist. This feature is intended to be useful in preventing races 656 between PUT operations. 658 Examples: 660 If-None-Match: "xyzzy" 661 If-None-Match: W/"xyzzy" 662 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 663 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 664 If-None-Match: * 666 The result of a request having both an If-None-Match header field and 667 either an If-Match or an If-Unmodified-Since header fields is 668 undefined by this specification. 670 7.5. If-Unmodified-Since 672 The If-Unmodified-Since request-header field is used with a method to 673 make it conditional. If the requested resource has not been modified 674 since the time specified in this field, the server SHOULD perform the 675 requested operation as if the If-Unmodified-Since header were not 676 present. 678 If the requested variant has been modified since the specified time, 679 the server MUST NOT perform the requested operation, and MUST return 680 a 412 (Precondition Failed). 682 If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date 684 An example of the field is: 686 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 688 If the request normally (i.e., without the If-Unmodified-Since 689 header) would result in anything other than a 2xx or 412 status, the 690 If-Unmodified-Since header SHOULD be ignored. 692 If the specified date is invalid, the header is ignored. 694 The result of a request having both an If-Unmodified-Since header 695 field and either an If-None-Match or an If-Modified-Since header 696 fields is undefined by this specification. 698 7.6. Last-Modified 700 The Last-Modified entity-header field indicates the date and time at 701 which the origin server believes the variant was last modified. 703 Last-Modified = "Last-Modified" ":" HTTP-date 705 An example of its use is 707 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 709 The exact meaning of this header field depends on the implementation 710 of the origin server and the nature of the original resource. For 711 files, it may be just the file system last-modified time. For 712 entities with dynamically included parts, it may be the most recent 713 of the set of last-modify times for its component parts. For 714 database gateways, it may be the last-update time stamp of the 715 record. For virtual objects, it may be the last time the internal 716 state changed. 718 An origin server MUST NOT send a Last-Modified date which is later 719 than the server's time of message origination. In such cases, where 720 the resource's last modification would indicate some time in the 721 future, the server MUST replace that date with the message 722 origination date. 724 An origin server SHOULD obtain the Last-Modified value of the entity 725 as close as possible to the time that it generates the Date value of 726 its response. This allows a recipient to make an accurate assessment 727 of the entity's modification time, especially if the entity changes 728 near the time that the response is generated. 730 HTTP/1.1 servers SHOULD send Last-Modified whenever feasible. 732 The Last-Modified entity-header field value is often used as a cache 733 validator. In simple terms, a cache entry is considered to be valid 734 if the entity has not been modified since the Last-Modified value. 736 8. IANA Considerations 738 8.1. Message Header Registration 740 The Message Header Registry located at should be 742 updated with the permanent registrations below (see [RFC3864]): 744 +---------------------+----------+----------+-------------+ 745 | Header Field Name | Protocol | Status | Reference | 746 +---------------------+----------+----------+-------------+ 747 | ETag | http | standard | Section 7.1 | 748 | If-Match | http | standard | Section 7.2 | 749 | If-Modified-Since | http | standard | Section 7.3 | 750 | If-None-Match | http | standard | Section 7.4 | 751 | If-Unmodified-Since | http | standard | Section 7.5 | 752 | Last-Modified | http | standard | Section 7.6 | 753 +---------------------+----------+----------+-------------+ 755 The change controller is: "IETF (iesg@ietf.org) - Internet 756 Engineering Task Force". 758 9. Security Considerations 760 No additional security considerations have been identified beyond 761 those applicable to HTTP in general [Part1]. 763 10. Acknowledgments 765 11. References 766 11.1. Normative References 768 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 769 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 770 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 771 and Message Parsing", draft-ietf-httpbis-p1-messaging-03 772 (work in progress), June 2008. 774 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 775 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 776 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 777 Partial Responses", draft-ietf-httpbis-p5-range-03 (work 778 in progress), June 2008. 780 [Part6] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 781 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 782 and J. Reschke, Ed., "HTTP/1.1, part 6: Caching", 783 draft-ietf-httpbis-p6-cache-03 (work in progress), 784 June 2008. 786 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 787 Requirement Levels", BCP 14, RFC 2119, March 1997. 789 11.2. Informative References 791 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T. 792 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 793 RFC 2068, January 1997. 795 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 796 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 797 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 799 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 800 Procedures for Message Header Fields", BCP 90, RFC 3864, 801 September 2004. 803 Appendix A. Compatibility with Previous Versions 805 A.1. Changes from RFC 2616 807 Allow weak entity tags in all requests except range requests 808 (Sections 5 and 7.4). 810 Appendix B. Change Log (to be removed by RFC Editor before publication) 812 B.1. Since RFC2616 814 Extracted relevant partitions from [RFC2616]. 816 B.2. Since draft-ietf-httpbis-p4-conditional-00 818 Closed issues: 820 o : "Normative 821 and Informative references" 823 Other changes: 825 o Move definitions of 304 and 412 condition codes from Part2. 827 B.3. Since draft-ietf-httpbis-p4-conditional-01 829 Ongoing work on ABNF conversion 830 (): 832 o Add explicit references to BNF syntax and rules imported from 833 other parts of the specification. 835 B.4. Since draft-ietf-httpbis-p4-conditional-02 837 Closed issues: 839 o : "Weak 840 ETags on non-GET requests" 842 Ongoing work on IANA Message Header Registration 843 (): 845 o Reference RFC 3984, and update header registrations for headers 846 defined in this document. 848 Index 850 3 851 304 Not Modified (status code) 5 853 4 854 412 Precondition Failed (status code) 6 856 E 857 ETag header 11 859 G 860 Grammar 861 entity-tag 5 862 ETag 11 863 If-Match 12 864 If-Modified-Since 13 865 If-None-Match 14 866 If-Unmodified-Since 16 867 Last-Modified 16 868 opaque-tag 5 869 weak 5 871 H 872 Headers 873 ETag 11 874 If-Match 11 875 If-Modified-Since 13 876 If-None-Match 14 877 If-Unmodified-Since 15 878 Last-Modified 16 880 I 881 If-Match header 11 882 If-Modified-Since header 13 883 If-None-Match header 14 884 If-Unmodified-Since header 15 886 L 887 Last-Modified header 16 889 S 890 Status Codes 891 304 Not Modified 5 892 412 Precondition Failed 6 894 Authors' Addresses 896 Roy T. Fielding (editor) 897 Day Software 898 23 Corporate Plaza DR, Suite 280 899 Newport Beach, CA 92660 900 USA 902 Phone: +1-949-706-5300 903 Fax: +1-949-706-5305 904 Email: fielding@gbiv.com 905 URI: http://roy.gbiv.com/ 907 Jim Gettys 908 One Laptop per Child 909 21 Oak Knoll Road 910 Carlisle, MA 01741 911 USA 913 Email: jg@laptop.org 914 URI: http://www.laptop.org/ 916 Jeffrey C. Mogul 917 Hewlett-Packard Company 918 HP Labs, Large Scale Systems Group 919 1501 Page Mill Road, MS 1177 920 Palo Alto, CA 94304 921 USA 923 Email: JeffMogul@acm.org 925 Henrik Frystyk Nielsen 926 Microsoft Corporation 927 1 Microsoft Way 928 Redmond, WA 98052 929 USA 931 Email: henrikn@microsoft.com 932 Larry Masinter 933 Adobe Systems, Incorporated 934 345 Park Ave 935 San Jose, CA 95110 936 USA 938 Email: LMM@acm.org 939 URI: http://larry.masinter.net/ 941 Paul J. Leach 942 Microsoft Corporation 943 1 Microsoft Way 944 Redmond, WA 98052 946 Email: paulle@microsoft.com 948 Tim Berners-Lee 949 World Wide Web Consortium 950 MIT Computer Science and Artificial Intelligence Laboratory 951 The Stata Center, Building 32 952 32 Vassar Street 953 Cambridge, MA 02139 954 USA 956 Email: timbl@w3.org 957 URI: http://www.w3.org/People/Berners-Lee/ 959 Yves Lafon (editor) 960 World Wide Web Consortium 961 W3C / ERCIM 962 2004, rte des Lucioles 963 Sophia-Antipolis, AM 06902 964 France 966 Email: ylafon@w3.org 967 URI: http://www.raubacapeu.net/people/yves/ 968 Julian F. Reschke (editor) 969 greenbytes GmbH 970 Hafenweg 16 971 Muenster, NW 48155 972 Germany 974 Phone: +49 251 2807760 975 Fax: +49 251 2807761 976 Email: julian.reschke@greenbytes.de 977 URI: http://greenbytes.de/tech/webdav/ 979 Full Copyright Statement 981 Copyright (C) The IETF Trust (2008). 983 This document is subject to the rights, licenses and restrictions 984 contained in BCP 78, and except as set forth therein, the authors 985 retain all their rights. 987 This document and the information contained herein are provided on an 988 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 989 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 990 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 991 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 992 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 993 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 995 Intellectual Property 997 The IETF takes no position regarding the validity or scope of any 998 Intellectual Property Rights or other rights that might be claimed to 999 pertain to the implementation or use of the technology described in 1000 this document or the extent to which any license under such rights 1001 might or might not be available; nor does it represent that it has 1002 made any independent effort to identify any such rights. Information 1003 on the procedures with respect to rights in RFC documents can be 1004 found in BCP 78 and BCP 79. 1006 Copies of IPR disclosures made to the IETF Secretariat and any 1007 assurances of licenses to be made available, or the result of an 1008 attempt made to obtain a general license or permission for the use of 1009 such proprietary rights by implementers or users of this 1010 specification can be obtained from the IETF on-line IPR repository at 1011 http://www.ietf.org/ipr. 1013 The IETF invites any interested party to bring to its attention any 1014 copyrights, patents or patent applications, or other proprietary 1015 rights that may cover technology that may be required to implement 1016 this standard. Please address the information to the IETF at 1017 ietf-ipr@ietf.org.