idnits 2.17.1 draft-ietf-httpbis-p4-conditional-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 9, 2009) is 5527 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-06 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-06 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-06 -- 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 (==), 3 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 10, 2009 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 March 9, 2009 22 HTTP/1.1, part 4: Conditional Requests 23 draft-ietf-httpbis-p4-conditional-06 25 Status of this Memo 27 This Internet-Draft is submitted to IETF in full conformance with the 28 provisions of BCP 78 and BCP 79. This document may contain material 29 from IETF Documents or IETF Contributions published or made publicly 30 available before November 10, 2008. The person(s) controlling the 31 copyright in some of this material may not have granted the IETF 32 Trust the right to allow modifications of such material outside the 33 IETF Standards Process. Without obtaining an adequate license from 34 the person(s) controlling the copyright in such materials, this 35 document may not be modified outside the IETF Standards Process, and 36 derivative works of it may not be created outside the IETF Standards 37 Process, except to format it for publication as an RFC or to 38 translate it into languages other than English. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF), its areas, and its working groups. Note that 42 other groups may also distribute working documents as Internet- 43 Drafts. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 The list of current Internet-Drafts can be accessed at 50 http://www.ietf.org/ietf/1id-abstracts.txt. 52 The list of Internet-Draft Shadow Directories can be accessed at 53 http://www.ietf.org/shadow.html. 55 This Internet-Draft will expire on September 10, 2009. 57 Copyright Notice 59 Copyright (c) 2009 IETF Trust and the persons identified as the 60 document authors. All rights reserved. 62 This document is subject to BCP 78 and the IETF Trust's Legal 63 Provisions Relating to IETF Documents in effect on the date of 64 publication of this document (http://trustee.ietf.org/license-info). 65 Please review these documents carefully, as they describe your rights 66 and restrictions with respect to this document. 68 Abstract 70 The Hypertext Transfer Protocol (HTTP) is an application-level 71 protocol for distributed, collaborative, hypermedia information 72 systems. HTTP has been in use by the World Wide Web global 73 information initiative since 1990. This document is Part 4 of the 74 seven-part specification that defines the protocol referred to as 75 "HTTP/1.1" and, taken together, obsoletes RFC 2616. Part 4 defines 76 request header fields for indicating conditional requests and the 77 rules for constructing responses to those requests. 79 Editorial Note (To be removed by RFC Editor) 81 Discussion of this draft should take place on the HTTPBIS working 82 group mailing list (ietf-http-wg@w3.org). The current issues list is 83 at and related 84 documents (including fancy diffs) can be found at 85 . 87 The changes in this draft are summarized in Appendix C.7. 89 Table of Contents 91 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 92 1.1. Requirements . . . . . . . . . . . . . . . . . . . . . . . 4 93 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 4 94 1.2.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 5 95 1.2.2. ABNF Rules defined in other Parts of the 96 Specification . . . . . . . . . . . . . . . . . . . . 5 97 2. Entity Tags . . . . . . . . . . . . . . . . . . . . . . . . . 5 98 3. Status Code Definitions . . . . . . . . . . . . . . . . . . . 6 99 3.1. 304 Not Modified . . . . . . . . . . . . . . . . . . . . . 6 100 3.2. 412 Precondition Failed . . . . . . . . . . . . . . . . . 6 101 4. Weak and Strong Validators . . . . . . . . . . . . . . . . . . 7 102 5. Rules for When to Use Entity Tags and Last-Modified Dates . . 9 103 6. Header Field Definitions . . . . . . . . . . . . . . . . . . . 11 104 6.1. ETag . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 105 6.2. If-Match . . . . . . . . . . . . . . . . . . . . . . . . . 12 106 6.3. If-Modified-Since . . . . . . . . . . . . . . . . . . . . 13 107 6.4. If-None-Match . . . . . . . . . . . . . . . . . . . . . . 15 108 6.5. If-Unmodified-Since . . . . . . . . . . . . . . . . . . . 16 109 6.6. Last-Modified . . . . . . . . . . . . . . . . . . . . . . 17 110 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 111 7.1. Message Header Registration . . . . . . . . . . . . . . . 17 112 8. Security Considerations . . . . . . . . . . . . . . . . . . . 18 113 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 114 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 115 10.1. Normative References . . . . . . . . . . . . . . . . . . . 18 116 10.2. Informative References . . . . . . . . . . . . . . . . . . 19 117 Appendix A. Compatibility with Previous Versions . . . . . . . . 19 118 A.1. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 19 119 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 20 120 Appendix C. Change Log (to be removed by RFC Editor before 121 publication) . . . . . . . . . . . . . . . . . . . . 20 122 C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 21 123 C.2. Since draft-ietf-httpbis-p4-conditional-00 . . . . . . . . 21 124 C.3. Since draft-ietf-httpbis-p4-conditional-01 . . . . . . . . 21 125 C.4. Since draft-ietf-httpbis-p4-conditional-02 . . . . . . . . 21 126 C.5. Since draft-ietf-httpbis-p4-conditional-03 . . . . . . . . 21 127 C.6. Since draft-ietf-httpbis-p4-conditional-04 . . . . . . . . 22 128 C.7. Since draft-ietf-httpbis-p4-conditional-05 . . . . . . . . 22 129 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 130 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 132 1. Introduction 134 This document defines HTTP/1.1 response metadata for indicating 135 potential changes to payload content, including modification time 136 stamps and opaque entity-tags, and the HTTP conditional request 137 mechanisms that allow preconditions to be placed on a request method. 138 Conditional GET requests allow for efficient cache updates. Other 139 conditional request methods are used to protect against overwriting 140 or misunderstanding the state of a resource that has been changed 141 unbeknownst to the requesting client. 143 This document is currently disorganized in order to minimize the 144 changes between drafts and enable reviewers to see the smaller errata 145 changes. The next draft will reorganize the sections to better 146 reflect the content. In particular, the sections on resource 147 metadata will be discussed first and then followed by each 148 conditional request-header, concluding with a definition of 149 precedence and the expectation of ordering strong validator checks 150 before weak validator checks. It is likely that more content from 151 [Part6] will migrate to this part, where appropriate. The current 152 mess reflects how widely dispersed these topics and associated 153 requirements had become in [RFC2616]. 155 1.1. Requirements 157 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 158 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 159 document are to be interpreted as described in [RFC2119]. 161 An implementation is not compliant if it fails to satisfy one or more 162 of the MUST or REQUIRED level requirements for the protocols it 163 implements. An implementation that satisfies all the MUST or 164 REQUIRED level and all the SHOULD level requirements for its 165 protocols is said to be "unconditionally compliant"; one that 166 satisfies all the MUST level requirements but not all the SHOULD 167 level requirements for its protocols is said to be "conditionally 168 compliant." 170 1.2. Syntax Notation 172 This specification uses the ABNF syntax defined in Section 1.2 of 173 [Part1] (which extends the syntax defined in [RFC5234] with a list 174 rule). Appendix B shows the collected ABNF, with the list rule 175 expanded. 177 The following core rules are included by reference, as defined in 178 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 179 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 180 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 181 sequence of data), SP (space), VCHAR (any visible USASCII character), 182 and WSP (whitespace). 184 1.2.1. Core Rules 186 The core rules below are defined in Section 1.2.2 of [Part1]: 188 quoted-string = 189 OWS = 191 1.2.2. ABNF Rules defined in other Parts of the Specification 193 The ABNF rules below are defined in other parts: 195 HTTP-date = 197 2. Entity Tags 199 Entity tags are used for comparing two or more entities from the same 200 requested resource. HTTP/1.1 uses entity tags in the ETag 201 (Section 6.1), If-Match (Section 6.2), If-None-Match (Section 6.4), 202 and If-Range (Section 5.3 of [Part5]) header fields. The definition 203 of how they are used and compared as cache validators is in 204 Section 4. An entity tag consists of an opaque quoted string, 205 possibly prefixed by a weakness indicator. 207 entity-tag = [ weak ] opaque-tag 208 weak = "W/" 209 opaque-tag = quoted-string 211 A "strong entity tag" MAY be shared by two entities of a resource 212 only if they are equivalent by octet equality. 214 A "weak entity tag," indicated by the "W/" prefix, MAY be shared by 215 two entities of a resource only if the entities are equivalent and 216 could be substituted for each other with no significant change in 217 semantics. A weak entity tag can only be used for weak comparison. 219 An entity tag MUST be unique across all versions of all entities 220 associated with a particular resource. A given entity tag value MAY 221 be used for entities obtained by requests on different URIs. The use 222 of the same entity tag value in conjunction with entities obtained by 223 requests on different URIs does not imply the equivalence of those 224 entities. 226 3. Status Code Definitions 228 3.1. 304 Not Modified 230 If the client has performed a conditional GET request and access is 231 allowed, but the document has not been modified, the server SHOULD 232 respond with this status code. The 304 response MUST NOT contain a 233 message-body, and thus is always terminated by the first empty line 234 after the header fields. 236 The response MUST include the following header fields: 238 o Date, unless its omission is required by Section 8.3.1 of [Part1]. 240 If a clockless origin server obeys these rules, and proxies and 241 clients add their own Date to any response received without one 242 (as already specified by Section 8.3 of [Part1], caches will 243 operate correctly. 245 o ETag and/or Content-Location, if the header would have been sent 246 in a 200 response to the same request. 248 o Expires, Cache-Control, and/or Vary, if the field-value might 249 differ from that sent in any previous response for the same 250 variant. 252 If the conditional GET used a strong cache validator (see Section 4), 253 the response SHOULD NOT include other entity-headers. Otherwise 254 (i.e., the conditional GET used a weak validator), the response MUST 255 NOT include other entity-headers; this prevents inconsistencies 256 between cached entity-bodies and updated headers. 258 If a 304 response indicates an entity not currently cached, then the 259 cache MUST disregard the response and repeat the request without the 260 conditional. 262 If a cache uses a received 304 response to update a cache entry, the 263 cache MUST update the entry to reflect any new field values given in 264 the response. 266 3.2. 412 Precondition Failed 268 The precondition given in one or more of the request-header fields 269 evaluated to false when it was tested on the server. This response 270 code allows the client to place preconditions on the current resource 271 metainformation (header field data) and thus prevent the requested 272 method from being applied to a resource other than the one intended. 274 4. Weak and Strong Validators 276 Since both origin servers and caches will compare two validators to 277 decide if they represent the same or different entities, one normally 278 would expect that if the entity (the entity-body or any entity- 279 headers) changes in any way, then the associated validator would 280 change as well. If this is true, then we call this validator a 281 "strong validator." 283 However, there might be cases when a server prefers to change the 284 validator only on semantically significant changes, and not when 285 insignificant aspects of the entity change. A validator that does 286 not always change when the resource changes is a "weak validator." 288 Entity tags are normally "strong validators," but the protocol 289 provides a mechanism to tag an entity tag as "weak." One can think 290 of a strong validator as one that changes whenever the bits of an 291 entity changes, while a weak value changes whenever the meaning of an 292 entity changes. Alternatively, one can think of a strong validator 293 as part of an identifier for a specific entity, while a weak 294 validator is part of an identifier for a set of semantically 295 equivalent entities. 297 Note: One example of a strong validator is an integer that is 298 incremented in stable storage every time an entity is changed. 300 An entity's modification time, if represented with one-second 301 resolution, could be a weak validator, since it is possible that 302 the resource might be modified twice during a single second. 304 Support for weak validators is optional. However, weak validators 305 allow for more efficient caching of equivalent objects; for 306 example, a hit counter on a site is probably good enough if it is 307 updated every few days or weeks, and any value during that period 308 is likely "good enough" to be equivalent. 310 A "use" of a validator is either when a client generates a request 311 and includes the validator in a validating header field, or when a 312 server compares two validators. 314 Strong validators are usable in any context. Weak validators are 315 only usable in contexts that do not depend on exact equality of an 316 entity. For example, either kind is usable for a conditional GET of 317 a full entity. However, only a strong validator is usable for a sub- 318 range retrieval, since otherwise the client might end up with an 319 internally inconsistent entity. 321 Clients MUST NOT use weak validators in range requests ([Part5]). 323 The only function that HTTP/1.1 defines on validators is comparison. 324 There are two validator comparison functions, depending on whether 325 the comparison context allows the use of weak validators or not: 327 o The strong comparison function: in order to be considered equal, 328 both opaque-tags MUST be identical character-by-character, and 329 both MUST NOT be weak. 331 o The weak comparison function: in order to be considered equal, 332 both opaque-tags MUST be identical character-by-character. 334 The example below shows the results for a set of entity tag pairs, 335 and both the weak and strong comparison function results: 337 +--------+--------+-------------------+-----------------+ 338 | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | 339 +--------+--------+-------------------+-----------------+ 340 | W/"1" | W/"1" | no match | match | 341 | W/"1" | W/"2" | no match | no match | 342 | W/"1" | "1" | no match | match | 343 | "1" | "1" | match | match | 344 +--------+--------+-------------------+-----------------+ 346 An entity tag is strong unless it is explicitly tagged as weak. 347 Section 2 gives the syntax for entity tags. 349 A Last-Modified time, when used as a validator in a request, is 350 implicitly weak unless it is possible to deduce that it is strong, 351 using the following rules: 353 o The validator is being compared by an origin server to the actual 354 current validator for the entity and, 356 o That origin server reliably knows that the associated entity did 357 not change twice during the second covered by the presented 358 validator. 360 or 362 o The validator is about to be used by a client in an If-Modified- 363 Since or If-Unmodified-Since header, because the client has a 364 cache entry for the associated entity, and 366 o That cache entry includes a Date value, which gives the time when 367 the origin server sent the original response, and 369 o The presented Last-Modified time is at least 60 seconds before the 370 Date value. 372 or 374 o The validator is being compared by an intermediate cache to the 375 validator stored in its cache entry for the entity, and 377 o That cache entry includes a Date value, which gives the time when 378 the origin server sent the original response, and 380 o The presented Last-Modified time is at least 60 seconds before the 381 Date value. 383 This method relies on the fact that if two different responses were 384 sent by the origin server during the same second, but both had the 385 same Last-Modified time, then at least one of those responses would 386 have a Date value equal to its Last-Modified time. The arbitrary 60- 387 second limit guards against the possibility that the Date and Last- 388 Modified values are generated from different clocks, or at somewhat 389 different times during the preparation of the response. An 390 implementation MAY use a value larger than 60 seconds, if it is 391 believed that 60 seconds is too short. 393 If a client wishes to perform a sub-range retrieval on a value for 394 which it has only a Last-Modified time and no opaque validator, it 395 MAY do this only if the Last-Modified time is strong in the sense 396 described here. 398 A cache or origin server receiving a conditional range request 399 ([Part5]) MUST use the strong comparison function to evaluate the 400 condition. 402 These rules allow HTTP/1.1 caches and clients to safely perform sub- 403 range retrievals on values that have been obtained from HTTP/1.0 404 servers. 406 5. Rules for When to Use Entity Tags and Last-Modified Dates 408 We adopt a set of rules and recommendations for origin servers, 409 clients, and caches regarding when various validator types ought to 410 be used, and for what purposes. 412 HTTP/1.1 origin servers: 414 o SHOULD send an entity tag validator unless it is not feasible to 415 generate one. 417 o MAY send a weak entity tag instead of a strong entity tag, if 418 performance considerations support the use of weak entity tags, or 419 if it is unfeasible to send a strong entity tag. 421 o SHOULD send a Last-Modified value if it is feasible to send one, 422 unless the risk of a breakdown in semantic transparency that could 423 result from using this date in an If-Modified-Since header would 424 lead to serious problems. 426 In other words, the preferred behavior for an HTTP/1.1 origin server 427 is to send both a strong entity tag and a Last-Modified value. 429 In order to be legal, a strong entity tag MUST change whenever the 430 associated entity changes in any way. A weak entity tag SHOULD 431 change whenever the associated entity changes in a semantically 432 significant way. 434 Note: in order to provide semantically transparent caching, an 435 origin server must avoid reusing a specific strong entity tag 436 value for two different entities, or reusing a specific weak 437 entity tag value for two semantically different entities. Cache 438 entries might persist for arbitrarily long periods, regardless of 439 expiration times, so it might be inappropriate to expect that a 440 cache will never again attempt to validate an entry using a 441 validator that it obtained at some point in the past. 443 HTTP/1.1 clients: 445 o If an entity tag has been provided by the origin server, MUST use 446 that entity tag in any cache-conditional request (using If-Match 447 or If-None-Match). 449 o If only a Last-Modified value has been provided by the origin 450 server, SHOULD use that value in non-subrange cache-conditional 451 requests (using If-Modified-Since). 453 o If only a Last-Modified value has been provided by an HTTP/1.0 454 origin server, MAY use that value in subrange cache-conditional 455 requests (using If-Unmodified-Since:). The user agent SHOULD 456 provide a way to disable this, in case of difficulty. 458 o If both an entity tag and a Last-Modified value have been provided 459 by the origin server, SHOULD use both validators in cache- 460 conditional requests. This allows both HTTP/1.0 and HTTP/1.1 461 caches to respond appropriately. 463 An HTTP/1.1 origin server, upon receiving a conditional request that 464 includes both a Last-Modified date (e.g., in an If-Modified-Since or 465 If-Unmodified-Since header field) and one or more entity tags (e.g., 466 in an If-Match, If-None-Match, or If-Range header field) as cache 467 validators, MUST NOT return a response status of 304 (Not Modified) 468 unless doing so is consistent with all of the conditional header 469 fields in the request. 471 An HTTP/1.1 caching proxy, upon receiving a conditional request that 472 includes both a Last-Modified date and one or more entity tags as 473 cache validators, MUST NOT return a locally cached response to the 474 client unless that cached response is consistent with all of the 475 conditional header fields in the request. 477 Note: The general principle behind these rules is that HTTP/1.1 478 servers and clients should transmit as much non-redundant 479 information as is available in their responses and requests. 480 HTTP/1.1 systems receiving this information will make the most 481 conservative assumptions about the validators they receive. 483 HTTP/1.0 clients and caches will ignore entity tags. Generally, 484 last-modified values received or used by these systems will 485 support transparent and efficient caching, and so HTTP/1.1 origin 486 servers should provide Last-Modified values. In those rare cases 487 where the use of a Last-Modified value as a validator by an 488 HTTP/1.0 system could result in a serious problem, then HTTP/1.1 489 origin servers should not provide one. 491 6. Header Field Definitions 493 This section defines the syntax and semantics of HTTP/1.1 header 494 fields related to conditional requests. 496 For entity-header fields, both sender and recipient refer to either 497 the client or the server, depending on who sends and who receives the 498 entity. 500 6.1. ETag 502 The response-header field "ETag" provides the current value of the 503 entity tag (see Section 2) for the requested variant. The headers 504 used with entity tags are described in Sections 6.2 and 6.4 of this 505 document, and in Section 5.3 of [Part5]. The entity tag MAY be used 506 for comparison with other entities from the same resource (see 507 Section 4). 509 ETag = "ETag" ":" OWS ETag-v 510 ETag-v = entity-tag 512 Examples: 514 ETag: "xyzzy" 515 ETag: W/"xyzzy" 516 ETag: "" 518 The ETag response-header field value, an entity tag, provides for an 519 "opaque" cache validator. This might allow more reliable validation 520 in situations where it is inconvenient to store modification dates, 521 where the one-second resolution of HTTP date values is not 522 sufficient, or where the origin server wishes to avoid certain 523 paradoxes that might arise from the use of modification dates. 525 The principle behind entity tags is that only the service author 526 knows the semantics of a resource well enough to select an 527 appropriate cache validation mechanism, and the specification of any 528 validator comparison function more complex than byte-equality would 529 open up a can of worms. Thus, comparisons of any other headers 530 (except Last-Modified, for compatibility with HTTP/1.0) are never 531 used for purposes of validating a cache entry. 533 6.2. If-Match 535 The request-header field "If-Match" is used with a method to make it 536 conditional. A client that has one or more entities previously 537 obtained from the resource can verify that one of those entities is 538 current by including a list of their associated entity tags in the 539 If-Match header field. Entity tags are defined in Section 2. The 540 purpose of this feature is to allow efficient updates of cached 541 information with a minimum amount of transaction overhead. It is 542 also used, on updating requests, to prevent inadvertent modification 543 of the wrong version of a resource. As a special case, the value "*" 544 matches any current entity of the resource. 546 If-Match = "If-Match" ":" OWS If-Match-v 547 If-Match-v = "*" / 1#entity-tag 549 If any of the entity tags match the entity tag of the entity that 550 would have been returned in the response to a similar GET request 551 (without the If-Match header) on that resource, or if "*" is given 552 and any current entity exists for that resource, then the server MAY 553 perform the requested method as if the If-Match header field did not 554 exist. 556 A server MUST use the strong comparison function (see Section 4) to 557 compare the entity tags in If-Match. 559 If none of the entity tags match, or if "*" is given and no current 560 entity exists, the server MUST NOT perform the requested method, and 561 MUST return a 412 (Precondition Failed) response. This behavior is 562 most useful when the client wants to prevent an updating method, such 563 as PUT, from modifying a resource that has changed since the client 564 last retrieved it. 566 If the request would, without the If-Match header field, result in 567 anything other than a 2xx or 412 status, then the If-Match header 568 MUST be ignored. 570 The meaning of "If-Match: *" is that the method SHOULD be performed 571 if the representation selected by the origin server (or by a cache, 572 possibly using the Vary mechanism, see Section 3.5 of [Part6]) 573 exists, and MUST NOT be performed if the representation does not 574 exist. 576 A request intended to update a resource (e.g., a PUT) MAY include an 577 If-Match header field to signal that the request method MUST NOT be 578 applied if the entity corresponding to the If-Match value (a single 579 entity tag) is no longer a representation of that resource. This 580 allows the user to indicate that they do not wish the request to be 581 successful if the resource has been changed without their knowledge. 582 Examples: 584 If-Match: "xyzzy" 585 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 586 If-Match: * 588 The result of a request having both an If-Match header field and 589 either an If-None-Match or an If-Modified-Since header fields is 590 undefined by this specification. 592 6.3. If-Modified-Since 594 The request-header field "If-Modified-Since" is used with a method to 595 make it conditional: if the requested variant has not been modified 596 since the time specified in this field, an entity will not be 597 returned from the server; instead, a 304 (Not Modified) response will 598 be returned without any message-body. 600 If-Modified-Since = "If-Modified-Since" ":" OWS 601 If-Modified-Since-v 602 If-Modified-Since-v = HTTP-date 604 An example of the field is: 606 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 608 A GET method with an If-Modified-Since header and no Range header 609 requests that the identified entity be transferred only if it has 610 been modified since the date given by the If-Modified-Since header. 611 The algorithm for determining this includes the following cases: 613 1. If the request would normally result in anything other than a 200 614 (OK) status, or if the passed If-Modified-Since date is invalid, 615 the response is exactly the same as for a normal GET. A date 616 which is later than the server's current time is invalid. 618 2. If the variant has been modified since the If-Modified-Since 619 date, the response is exactly the same as for a normal GET. 621 3. If the variant has not been modified since a valid If-Modified- 622 Since date, the server SHOULD return a 304 (Not Modified) 623 response. 625 The purpose of this feature is to allow efficient updates of cached 626 information with a minimum amount of transaction overhead. 628 Note: The Range request-header field modifies the meaning of If- 629 Modified-Since; see Section 5.4 of [Part5] for full details. 631 Note: If-Modified-Since times are interpreted by the server, whose 632 clock might not be synchronized with the client. 634 Note: When handling an If-Modified-Since header field, some 635 servers will use an exact date comparison function, rather than a 636 less-than function, for deciding whether to send a 304 (Not 637 Modified) response. To get best results when sending an If- 638 Modified-Since header field for cache validation, clients are 639 advised to use the exact date string received in a previous Last- 640 Modified header field whenever possible. 642 Note: If a client uses an arbitrary date in the If-Modified-Since 643 header instead of a date taken from the Last-Modified header for 644 the same request, the client should be aware of the fact that this 645 date is interpreted in the server's understanding of time. The 646 client should consider unsynchronized clocks and rounding problems 647 due to the different encodings of time between the client and 648 server. This includes the possibility of race conditions if the 649 document has changed between the time it was first requested and 650 the If-Modified-Since date of a subsequent request, and the 651 possibility of clock-skew-related problems if the If-Modified- 652 Since date is derived from the client's clock without correction 653 to the server's clock. Corrections for different time bases 654 between client and server are at best approximate due to network 655 latency. 657 The result of a request having both an If-Modified-Since header field 658 and either an If-Match or an If-Unmodified-Since header fields is 659 undefined by this specification. 661 6.4. If-None-Match 663 The request-header field "If-None-Match" is used with a method to 664 make it conditional. A client that has one or more entities 665 previously obtained from the resource can verify that none of those 666 entities is current by including a list of their associated entity 667 tags in the If-None-Match header field. The purpose of this feature 668 is to allow efficient updates of cached information with a minimum 669 amount of transaction overhead. It is also used to prevent a method 670 (e.g. PUT) from inadvertently modifying an existing resource when 671 the client believes that the resource does not exist. 673 As a special case, the value "*" matches any current entity of the 674 resource. 676 If-None-Match = "If-None-Match" ":" OWS If-None-Match-v 677 If-None-Match-v = "*" / 1#entity-tag 679 If any of the entity tags match the entity tag of the entity that 680 would have been returned in the response to a similar GET request 681 (without the If-None-Match header) on that resource, or if "*" is 682 given and any current entity exists for that resource, then the 683 server MUST NOT perform the requested method, unless required to do 684 so because the resource's modification date fails to match that 685 supplied in an If-Modified-Since header field in the request. 686 Instead, if the request method was GET or HEAD, the server SHOULD 687 respond with a 304 (Not Modified) response, including the cache- 688 related header fields (particularly ETag) of one of the entities that 689 matched. For all other request methods, the server MUST respond with 690 a status of 412 (Precondition Failed). 692 See Section 4 for rules on how to determine if two entity tags match. 694 If none of the entity tags match, then the server MAY perform the 695 requested method as if the If-None-Match header field did not exist, 696 but MUST also ignore any If-Modified-Since header field(s) in the 697 request. That is, if no entity tags match, then the server MUST NOT 698 return a 304 (Not Modified) response. 700 If the request would, without the If-None-Match header field, result 701 in anything other than a 2xx or 304 status, then the If-None-Match 702 header MUST be ignored. (See Section 5 for a discussion of server 703 behavior when both If-Modified-Since and If-None-Match appear in the 704 same request.) 705 The meaning of "If-None-Match: *" is that the method MUST NOT be 706 performed if the representation selected by the origin server (or by 707 a cache, possibly using the Vary mechanism, see Section 3.5 of 708 [Part6]) exists, and SHOULD be performed if the representation does 709 not exist. This feature is intended to be useful in preventing races 710 between PUT operations. 712 Examples: 714 If-None-Match: "xyzzy" 715 If-None-Match: W/"xyzzy" 716 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 717 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 718 If-None-Match: * 720 The result of a request having both an If-None-Match header field and 721 either an If-Match or an If-Unmodified-Since header fields is 722 undefined by this specification. 724 6.5. If-Unmodified-Since 726 The request-header field "If-Unmodified-Since" is used with a method 727 to make it conditional. If the requested resource has not been 728 modified since the time specified in this field, the server SHOULD 729 perform the requested operation as if the If-Unmodified-Since header 730 were not present. 732 If the requested variant has been modified since the specified time, 733 the server MUST NOT perform the requested operation, and MUST return 734 a 412 (Precondition Failed). 736 If-Unmodified-Since = "If-Unmodified-Since" ":" OWS 737 If-Unmodified-Since-v 738 If-Unmodified-Since-v = HTTP-date 740 An example of the field is: 742 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 744 If the request normally (i.e., without the If-Unmodified-Since 745 header) would result in anything other than a 2xx or 412 status, the 746 If-Unmodified-Since header SHOULD be ignored. 748 If the specified date is invalid, the header is ignored. 750 The result of a request having both an If-Unmodified-Since header 751 field and either an If-None-Match or an If-Modified-Since header 752 fields is undefined by this specification. 754 6.6. Last-Modified 756 The entity-header field "Last-Modified" indicates the date and time 757 at which the origin server believes the variant was last modified. 759 Last-Modified = "Last-Modified" ":" OWS Last-Modified-v 760 Last-Modified-v = HTTP-date 762 An example of its use is 764 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 766 The exact meaning of this header field depends on the implementation 767 of the origin server and the nature of the original resource. For 768 files, it may be just the file system last-modified time. For 769 entities with dynamically included parts, it may be the most recent 770 of the set of last-modify times for its component parts. For 771 database gateways, it may be the last-update time stamp of the 772 record. For virtual objects, it may be the last time the internal 773 state changed. 775 An origin server MUST NOT send a Last-Modified date which is later 776 than the server's time of message origination. In such cases, where 777 the resource's last modification would indicate some time in the 778 future, the server MUST replace that date with the message 779 origination date. 781 An origin server SHOULD obtain the Last-Modified value of the entity 782 as close as possible to the time that it generates the Date value of 783 its response. This allows a recipient to make an accurate assessment 784 of the entity's modification time, especially if the entity changes 785 near the time that the response is generated. 787 HTTP/1.1 servers SHOULD send Last-Modified whenever feasible. 789 The Last-Modified entity-header field value is often used as a cache 790 validator. In simple terms, a cache entry is considered to be valid 791 if the entity has not been modified since the Last-Modified value. 793 7. IANA Considerations 795 7.1. Message Header Registration 797 The Message Header Registry located at should be 799 updated with the permanent registrations below (see [RFC3864]): 801 +---------------------+----------+----------+-------------+ 802 | Header Field Name | Protocol | Status | Reference | 803 +---------------------+----------+----------+-------------+ 804 | ETag | http | standard | Section 6.1 | 805 | If-Match | http | standard | Section 6.2 | 806 | If-Modified-Since | http | standard | Section 6.3 | 807 | If-None-Match | http | standard | Section 6.4 | 808 | If-Unmodified-Since | http | standard | Section 6.5 | 809 | Last-Modified | http | standard | Section 6.6 | 810 +---------------------+----------+----------+-------------+ 812 The change controller is: "IETF (iesg@ietf.org) - Internet 813 Engineering Task Force". 815 8. Security Considerations 817 No additional security considerations have been identified beyond 818 those applicable to HTTP in general [Part1]. 820 9. Acknowledgments 822 10. References 824 10.1. Normative References 826 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 827 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 828 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 829 and Message Parsing", draft-ietf-httpbis-p1-messaging-06 830 (work in progress), March 2009. 832 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 833 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 834 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 835 Partial Responses", draft-ietf-httpbis-p5-range-06 (work 836 in progress), March 2009. 838 [Part6] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 839 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 840 and J. Reschke, Ed., "HTTP/1.1, part 6: Caching", 841 draft-ietf-httpbis-p6-cache-06 (work in progress), 842 March 2009. 844 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 845 Requirement Levels", BCP 14, RFC 2119, March 1997. 847 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 848 Specifications: ABNF", STD 68, RFC 5234, January 2008. 850 10.2. Informative References 852 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 853 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 854 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 856 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 857 Procedures for Message Header Fields", BCP 90, RFC 3864, 858 September 2004. 860 Appendix A. Compatibility with Previous Versions 862 A.1. Changes from RFC 2616 864 Allow weak entity tags in all requests except range requests 865 (Sections 4 and 6.4). 867 Appendix B. Collected ABNF 869 ETag = "ETag:" OWS ETag-v 870 ETag-v = entity-tag 872 HTTP-date = 874 If-Match = "If-Match:" OWS If-Match-v 875 If-Match-v = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS 876 entity-tag ] ) ) 877 If-Modified-Since = "If-Modified-Since:" OWS If-Modified-Since-v 878 If-Modified-Since-v = HTTP-date 879 If-None-Match = "If-None-Match:" OWS If-None-Match-v 880 If-None-Match-v = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS 881 entity-tag ] ) ) 882 If-Unmodified-Since = "If-Unmodified-Since:" OWS 883 If-Unmodified-Since-v 884 If-Unmodified-Since-v = HTTP-date 886 Last-Modified = "Last-Modified:" OWS Last-Modified-v 887 Last-Modified-v = HTTP-date 889 OWS = 891 entity-tag = [ weak ] opaque-tag 893 opaque-tag = quoted-string 895 quoted-string = 897 weak = "W/" 899 ABNF diagnostics: 901 ; ETag defined but not used 902 ; If-Match defined but not used 903 ; If-Modified-Since defined but not used 904 ; If-None-Match defined but not used 905 ; If-Unmodified-Since defined but not used 906 ; Last-Modified defined but not used 908 Appendix C. Change Log (to be removed by RFC Editor before publication) 909 C.1. Since RFC2616 911 Extracted relevant partitions from [RFC2616]. 913 C.2. Since draft-ietf-httpbis-p4-conditional-00 915 Closed issues: 917 o : "Normative and 918 Informative references" 920 Other changes: 922 o Move definitions of 304 and 412 condition codes from Part2. 924 C.3. Since draft-ietf-httpbis-p4-conditional-01 926 Ongoing work on ABNF conversion 927 (): 929 o Add explicit references to BNF syntax and rules imported from 930 other parts of the specification. 932 C.4. Since draft-ietf-httpbis-p4-conditional-02 934 Closed issues: 936 o : "Weak ETags on 937 non-GET requests" 939 Ongoing work on IANA Message Header Registration 940 (): 942 o Reference RFC 3984, and update header registrations for headers 943 defined in this document. 945 C.5. Since draft-ietf-httpbis-p4-conditional-03 947 Closed issues: 949 o : "Examples for 950 ETag matching" 952 o : "'entity 953 value' undefined" 955 o : "bogus 2068 956 Date header reference" 958 C.6. Since draft-ietf-httpbis-p4-conditional-04 960 Ongoing work on ABNF conversion 961 (): 963 o Use "/" instead of "|" for alternatives. 965 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 966 whitespace ("OWS") and required whitespace ("RWS"). 968 o Rewrite ABNFs to spell out whitespace rules, factor out header 969 value format definitions. 971 C.7. Since draft-ietf-httpbis-p4-conditional-05 973 Final work on ABNF conversion 974 (): 976 o Add appendix containing collected and expanded ABNF, reorganize 977 ABNF introduction. 979 Index 981 3 982 304 Not Modified (status code) 6 984 4 985 412 Precondition Failed (status code) 6 987 E 988 ETag header 11 990 G 991 Grammar 992 entity-tag 5 993 ETag 11 994 ETag-v 11 995 If-Match 12 996 If-Match-v 12 997 If-Modified-Since 13 998 If-Modified-Since-v 13 999 If-None-Match 15 1000 If-None-Match-v 15 1001 If-Unmodified-Since 16 1002 If-Unmodified-Since-v 16 1003 Last-Modified 17 1004 Last-Modified-v 17 1005 opaque-tag 5 1006 weak 5 1008 H 1009 Headers 1010 ETag 11 1011 If-Match 12 1012 If-Modified-Since 13 1013 If-None-Match 15 1014 If-Unmodified-Since 16 1015 Last-Modified 17 1017 I 1018 If-Match header 12 1019 If-Modified-Since header 13 1020 If-None-Match header 15 1021 If-Unmodified-Since header 16 1023 L 1024 Last-Modified header 17 1026 S 1027 Status Codes 1028 304 Not Modified 6 1029 412 Precondition Failed 6 1031 Authors' Addresses 1033 Roy T. Fielding (editor) 1034 Day Software 1035 23 Corporate Plaza DR, Suite 280 1036 Newport Beach, CA 92660 1037 USA 1039 Phone: +1-949-706-5300 1040 Fax: +1-949-706-5305 1041 Email: fielding@gbiv.com 1042 URI: http://roy.gbiv.com/ 1043 Jim Gettys 1044 One Laptop per Child 1045 21 Oak Knoll Road 1046 Carlisle, MA 01741 1047 USA 1049 Email: jg@laptop.org 1050 URI: http://www.laptop.org/ 1052 Jeffrey C. Mogul 1053 Hewlett-Packard Company 1054 HP Labs, Large Scale Systems Group 1055 1501 Page Mill Road, MS 1177 1056 Palo Alto, CA 94304 1057 USA 1059 Email: JeffMogul@acm.org 1061 Henrik Frystyk Nielsen 1062 Microsoft Corporation 1063 1 Microsoft Way 1064 Redmond, WA 98052 1065 USA 1067 Email: henrikn@microsoft.com 1069 Larry Masinter 1070 Adobe Systems, Incorporated 1071 345 Park Ave 1072 San Jose, CA 95110 1073 USA 1075 Email: LMM@acm.org 1076 URI: http://larry.masinter.net/ 1078 Paul J. Leach 1079 Microsoft Corporation 1080 1 Microsoft Way 1081 Redmond, WA 98052 1083 Email: paulle@microsoft.com 1084 Tim Berners-Lee 1085 World Wide Web Consortium 1086 MIT Computer Science and Artificial Intelligence Laboratory 1087 The Stata Center, Building 32 1088 32 Vassar Street 1089 Cambridge, MA 02139 1090 USA 1092 Email: timbl@w3.org 1093 URI: http://www.w3.org/People/Berners-Lee/ 1095 Yves Lafon (editor) 1096 World Wide Web Consortium 1097 W3C / ERCIM 1098 2004, rte des Lucioles 1099 Sophia-Antipolis, AM 06902 1100 France 1102 Email: ylafon@w3.org 1103 URI: http://www.raubacapeu.net/people/yves/ 1105 Julian F. Reschke (editor) 1106 greenbytes GmbH 1107 Hafenweg 16 1108 Muenster, NW 48155 1109 Germany 1111 Phone: +49 251 2807760 1112 Fax: +49 251 2807761 1113 Email: julian.reschke@greenbytes.de 1114 URI: http://greenbytes.de/tech/webdav/