idnits 2.17.1 draft-ietf-httpbis-p4-conditional-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 26, 2009) is 5295 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-08 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-08 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-08 -- 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: April 29, 2010 J. Mogul 7 HP 8 H. Frystyk 9 Microsoft 10 L. Masinter 11 Adobe Systems 12 P. Leach 13 Microsoft 14 T. Berners-Lee 15 W3C/MIT 16 Y. Lafon, Ed. 17 W3C 18 J. Reschke, Ed. 19 greenbytes 20 October 26, 2009 22 HTTP/1.1, part 4: Conditional Requests 23 draft-ietf-httpbis-p4-conditional-08 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 April 29, 2010. 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.9. 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. Status Code Registration . . . . . . . . . . . . . . . . . 17 112 7.2. Message Header Registration . . . . . . . . . . . . . . . 18 113 8. Security Considerations . . . . . . . . . . . . . . . . . . . 18 114 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 115 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 116 10.1. Normative References . . . . . . . . . . . . . . . . . . . 18 117 10.2. Informative References . . . . . . . . . . . . . . . . . . 19 118 Appendix A. Compatibility with Previous Versions . . . . . . . . 19 119 A.1. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 19 120 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 20 121 Appendix C. Change Log (to be removed by RFC Editor before 122 publication) . . . . . . . . . . . . . . . . . . . . 20 123 C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 20 124 C.2. Since draft-ietf-httpbis-p4-conditional-00 . . . . . . . . 21 125 C.3. Since draft-ietf-httpbis-p4-conditional-01 . . . . . . . . 21 126 C.4. Since draft-ietf-httpbis-p4-conditional-02 . . . . . . . . 21 127 C.5. Since draft-ietf-httpbis-p4-conditional-03 . . . . . . . . 21 128 C.6. Since draft-ietf-httpbis-p4-conditional-04 . . . . . . . . 22 129 C.7. Since draft-ietf-httpbis-p4-conditional-05 . . . . . . . . 22 130 C.8. Since draft-ietf-httpbis-p4-conditional-06 . . . . . . . . 22 131 C.9. Since draft-ietf-httpbis-p4-conditional-07 . . . . . . . . 22 132 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 133 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 135 1. Introduction 137 This document defines HTTP/1.1 response metadata for indicating 138 potential changes to payload content, including modification time 139 stamps and opaque entity-tags, and the HTTP conditional request 140 mechanisms that allow preconditions to be placed on a request method. 141 Conditional GET requests allow for efficient cache updates. Other 142 conditional request methods are used to protect against overwriting 143 or misunderstanding the state of a resource that has been changed 144 unbeknownst to the requesting client. 146 This document is currently disorganized in order to minimize the 147 changes between drafts and enable reviewers to see the smaller errata 148 changes. The next draft will reorganize the sections to better 149 reflect the content. In particular, the sections on resource 150 metadata will be discussed first and then followed by each 151 conditional request-header, concluding with a definition of 152 precedence and the expectation of ordering strong validator checks 153 before weak validator checks. It is likely that more content from 154 [Part6] will migrate to this part, where appropriate. The current 155 mess reflects how widely dispersed these topics and associated 156 requirements had become in [RFC2616]. 158 1.1. Requirements 160 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 161 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 162 document are to be interpreted as described in [RFC2119]. 164 An implementation is not compliant if it fails to satisfy one or more 165 of the MUST or REQUIRED level requirements for the protocols it 166 implements. An implementation that satisfies all the MUST or 167 REQUIRED level and all the SHOULD level requirements for its 168 protocols is said to be "unconditionally compliant"; one that 169 satisfies all the MUST level requirements but not all the SHOULD 170 level requirements for its protocols is said to be "conditionally 171 compliant." 173 1.2. Syntax Notation 175 This specification uses the ABNF syntax defined in Section 1.2 of 176 [Part1] (which extends the syntax defined in [RFC5234] with a list 177 rule). Appendix B shows the collected ABNF, with the list rule 178 expanded. 180 The following core rules are included by reference, as defined in 181 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 182 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 183 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 184 sequence of data), SP (space), VCHAR (any visible USASCII character), 185 and WSP (whitespace). 187 1.2.1. Core Rules 189 The core rules below are defined in Section 1.2.2 of [Part1]: 191 quoted-string = 192 OWS = 194 1.2.2. ABNF Rules defined in other Parts of the Specification 196 The ABNF rules below are defined in other parts: 198 HTTP-date = 200 2. Entity Tags 202 Entity tags are used for comparing two or more entities from the same 203 requested resource. HTTP/1.1 uses entity tags in the ETag 204 (Section 6.1), If-Match (Section 6.2), If-None-Match (Section 6.4), 205 and If-Range (Section 5.3 of [Part5]) header fields. The definition 206 of how they are used and compared as cache validators is in 207 Section 4. An entity tag consists of an opaque quoted string, 208 possibly prefixed by a weakness indicator. 210 entity-tag = [ weak ] opaque-tag 211 weak = %x57.2F ; "W/", case-sensitive 212 opaque-tag = quoted-string 214 A "strong entity tag" MAY be shared by two entities of a resource 215 only if they are equivalent by octet equality. 217 A "weak entity tag," indicated by the "W/" prefix, MAY be shared by 218 two entities of a resource only if the entities are equivalent and 219 could be substituted for each other with no significant change in 220 semantics. A weak entity tag can only be used for weak comparison. 222 An entity tag MUST be unique across all versions of all entities 223 associated with a particular resource. A given entity tag value MAY 224 be used for entities obtained by requests on different URIs. The use 225 of the same entity tag value in conjunction with entities obtained by 226 requests on different URIs does not imply the equivalence of those 227 entities. 229 3. Status Code Definitions 231 3.1. 304 Not Modified 233 If the client has performed a conditional GET request and access is 234 allowed, but the document has not been modified, the server SHOULD 235 respond with this status code. The 304 response MUST NOT contain a 236 message-body, and thus is always terminated by the first empty line 237 after the header fields. 239 The response MUST include the following header fields: 241 o Date, unless its omission is required by Section 9.3.1 of [Part1]. 243 If a clockless origin server obeys these rules, and proxies and 244 clients add their own Date to any response received without one 245 (as already specified by Section 9.3 of [Part1], caches will 246 operate correctly. 248 o ETag and/or Content-Location, if the header would have been sent 249 in a 200 response to the same request. 251 o Expires, Cache-Control, and/or Vary, if the field-value might 252 differ from that sent in any previous response for the same 253 variant. 255 If the conditional GET used a strong cache validator (see Section 4), 256 the response SHOULD NOT include other entity-headers. Otherwise 257 (i.e., the conditional GET used a weak validator), the response MUST 258 NOT include other entity-headers; this prevents inconsistencies 259 between cached entity-bodies and updated headers. 261 If a 304 response indicates an entity not currently cached, then the 262 cache MUST disregard the response and repeat the request without the 263 conditional. 265 If a cache uses a received 304 response to update a cache entry, the 266 cache MUST update the entry to reflect any new field values given in 267 the response. 269 3.2. 412 Precondition Failed 271 The precondition given in one or more of the request-header fields 272 evaluated to false when it was tested on the server. This response 273 code allows the client to place preconditions on the current resource 274 metainformation (header field data) and thus prevent the requested 275 method from being applied to a resource other than the one intended. 277 4. Weak and Strong Validators 279 Since both origin servers and caches will compare two validators to 280 decide if they represent the same or different entities, one normally 281 would expect that if the entity (the entity-body or any entity- 282 headers) changes in any way, then the associated validator would 283 change as well. If this is true, then we call this validator a 284 "strong validator." 286 However, there might be cases when a server prefers to change the 287 validator only on semantically significant changes, and not when 288 insignificant aspects of the entity change. A validator that does 289 not always change when the resource changes is a "weak validator." 291 Entity tags are normally "strong validators," but the protocol 292 provides a mechanism to tag an entity tag as "weak." One can think 293 of a strong validator as one that changes whenever the bits of an 294 entity changes, while a weak value changes whenever the meaning of an 295 entity changes. Alternatively, one can think of a strong validator 296 as part of an identifier for a specific entity, while a weak 297 validator is part of an identifier for a set of semantically 298 equivalent entities. 300 Note: One example of a strong validator is an integer that is 301 incremented in stable storage every time an entity is changed. 303 An entity's modification time, if represented with one-second 304 resolution, could be a weak validator, since it is possible that 305 the resource might be modified twice during a single second. 307 Support for weak validators is optional. However, weak validators 308 allow for more efficient caching of equivalent objects; for 309 example, a hit counter on a site is probably good enough if it is 310 updated every few days or weeks, and any value during that period 311 is likely "good enough" to be equivalent. 313 A "use" of a validator is either when a client generates a request 314 and includes the validator in a validating header field, or when a 315 server compares two validators. 317 Strong validators are usable in any context. Weak validators are 318 only usable in contexts that do not depend on exact equality of an 319 entity. For example, either kind is usable for a conditional GET of 320 a full entity. However, only a strong validator is usable for a sub- 321 range retrieval, since otherwise the client might end up with an 322 internally inconsistent entity. 324 Clients MUST NOT use weak validators in range requests ([Part5]). 326 The only function that HTTP/1.1 defines on validators is comparison. 327 There are two validator comparison functions, depending on whether 328 the comparison context allows the use of weak validators or not: 330 o The strong comparison function: in order to be considered equal, 331 both opaque-tags MUST be identical character-by-character, and 332 both MUST NOT be weak. 334 o The weak comparison function: in order to be considered equal, 335 both opaque-tags MUST be identical character-by-character, but 336 either or both of them MAY be tagged as "weak" without affecting 337 the result. 339 The example below shows the results for a set of entity tag pairs, 340 and both the weak and strong comparison function results: 342 +--------+--------+-------------------+-----------------+ 343 | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | 344 +--------+--------+-------------------+-----------------+ 345 | W/"1" | W/"1" | no match | match | 346 | W/"1" | W/"2" | no match | no match | 347 | W/"1" | "1" | no match | match | 348 | "1" | "1" | match | match | 349 +--------+--------+-------------------+-----------------+ 351 An entity tag is strong unless it is explicitly tagged as weak. 352 Section 2 gives the syntax for entity tags. 354 A Last-Modified time, when used as a validator in a request, is 355 implicitly weak unless it is possible to deduce that it is strong, 356 using the following rules: 358 o The validator is being compared by an origin server to the actual 359 current validator for the entity and, 361 o That origin server reliably knows that the associated entity did 362 not change twice during the second covered by the presented 363 validator. 365 or 367 o The validator is about to be used by a client in an If-Modified- 368 Since or If-Unmodified-Since header, because the client has a 369 cache entry for the associated entity, and 371 o That cache entry includes a Date value, which gives the time when 372 the origin server sent the original response, and 374 o The presented Last-Modified time is at least 60 seconds before the 375 Date value. 377 or 379 o The validator is being compared by an intermediate cache to the 380 validator stored in its cache entry for the entity, and 382 o That cache entry includes a Date value, which gives the time when 383 the origin server sent the original response, and 385 o The presented Last-Modified time is at least 60 seconds before the 386 Date value. 388 This method relies on the fact that if two different responses were 389 sent by the origin server during the same second, but both had the 390 same Last-Modified time, then at least one of those responses would 391 have a Date value equal to its Last-Modified time. The arbitrary 60- 392 second limit guards against the possibility that the Date and Last- 393 Modified values are generated from different clocks, or at somewhat 394 different times during the preparation of the response. An 395 implementation MAY use a value larger than 60 seconds, if it is 396 believed that 60 seconds is too short. 398 If a client wishes to perform a sub-range retrieval on a value for 399 which it has only a Last-Modified time and no opaque validator, it 400 MAY do this only if the Last-Modified time is strong in the sense 401 described here. 403 A cache or origin server receiving a conditional range request 404 ([Part5]) MUST use the strong comparison function to evaluate the 405 condition. 407 These rules allow HTTP/1.1 caches and clients to safely perform sub- 408 range retrievals on values that have been obtained from HTTP/1.0 409 servers. 411 5. Rules for When to Use Entity Tags and Last-Modified Dates 413 We adopt a set of rules and recommendations for origin servers, 414 clients, and caches regarding when various validator types ought to 415 be used, and for what purposes. 417 HTTP/1.1 origin servers: 419 o SHOULD send an entity tag validator unless it is not feasible to 420 generate one. 422 o MAY send a weak entity tag instead of a strong entity tag, if 423 performance considerations support the use of weak entity tags, or 424 if it is unfeasible to send a strong entity tag. 426 o SHOULD send a Last-Modified value if it is feasible to send one, 427 unless the risk of a breakdown in semantic transparency that could 428 result from using this date in an If-Modified-Since header would 429 lead to serious problems. 431 In other words, the preferred behavior for an HTTP/1.1 origin server 432 is to send both a strong entity tag and a Last-Modified value. 434 In order to be legal, a strong entity tag MUST change whenever the 435 associated entity changes in any way. A weak entity tag SHOULD 436 change whenever the associated entity changes in a semantically 437 significant way. 439 Note: in order to provide semantically transparent caching, an 440 origin server must avoid reusing a specific strong entity tag 441 value for two different entities, or reusing a specific weak 442 entity tag value for two semantically different entities. Cache 443 entries might persist for arbitrarily long periods, regardless of 444 expiration times, so it might be inappropriate to expect that a 445 cache will never again attempt to validate an entry using a 446 validator that it obtained at some point in the past. 448 HTTP/1.1 clients: 450 o If an entity tag has been provided by the origin server, MUST use 451 that entity tag in any cache-conditional request (using If-Match 452 or If-None-Match). 454 o If only a Last-Modified value has been provided by the origin 455 server, SHOULD use that value in non-subrange cache-conditional 456 requests (using If-Modified-Since). 458 o If only a Last-Modified value has been provided by an HTTP/1.0 459 origin server, MAY use that value in subrange cache-conditional 460 requests (using If-Unmodified-Since:). The user agent SHOULD 461 provide a way to disable this, in case of difficulty. 463 o If both an entity tag and a Last-Modified value have been provided 464 by the origin server, SHOULD use both validators in cache- 465 conditional requests. This allows both HTTP/1.0 and HTTP/1.1 466 caches to respond appropriately. 468 An HTTP/1.1 origin server, upon receiving a conditional request that 469 includes both a Last-Modified date (e.g., in an If-Modified-Since or 470 If-Unmodified-Since header field) and one or more entity tags (e.g., 471 in an If-Match, If-None-Match, or If-Range header field) as cache 472 validators, MUST NOT return a response status of 304 (Not Modified) 473 unless doing so is consistent with all of the conditional header 474 fields in the request. 476 An HTTP/1.1 caching proxy, upon receiving a conditional request that 477 includes both a Last-Modified date and one or more entity tags as 478 cache validators, MUST NOT return a locally cached response to the 479 client unless that cached response is consistent with all of the 480 conditional header fields in the request. 482 Note: The general principle behind these rules is that HTTP/1.1 483 servers and clients should transmit as much non-redundant 484 information as is available in their responses and requests. 485 HTTP/1.1 systems receiving this information will make the most 486 conservative assumptions about the validators they receive. 488 HTTP/1.0 clients and caches will ignore entity tags. Generally, 489 last-modified values received or used by these systems will 490 support transparent and efficient caching, and so HTTP/1.1 origin 491 servers should provide Last-Modified values. In those rare cases 492 where the use of a Last-Modified value as a validator by an 493 HTTP/1.0 system could result in a serious problem, then HTTP/1.1 494 origin servers should not provide one. 496 6. Header Field Definitions 498 This section defines the syntax and semantics of HTTP/1.1 header 499 fields related to conditional requests. 501 For entity-header fields, both sender and recipient refer to either 502 the client or the server, depending on who sends and who receives the 503 entity. 505 6.1. ETag 507 The "ETag" response-header field provides the current value of the 508 entity tag (see Section 2) for the requested variant, which may be 509 used for comparison with other entities from the same resource (see 510 Section 4). 512 ETag = "ETag" ":" OWS ETag-v 513 ETag-v = entity-tag 515 Examples: 517 ETag: "xyzzy" 518 ETag: W/"xyzzy" 519 ETag: "" 521 The ETag response-header field value, an entity tag, provides for an 522 "opaque" cache validator. This might allow more reliable validation 523 in situations where it is inconvenient to store modification dates, 524 where the one-second resolution of HTTP date values is not 525 sufficient, or where the origin server wishes to avoid certain 526 paradoxes that might arise from the use of modification dates. 528 The principle behind entity tags is that only the service author 529 knows the semantics of a resource well enough to select an 530 appropriate cache validation mechanism, and the specification of any 531 validator comparison function more complex than byte-equality would 532 open up a can of worms. Thus, comparisons of any other headers 533 (except Last-Modified, for compatibility with HTTP/1.0) are never 534 used for purposes of validating a cache entry. 536 6.2. If-Match 538 The "If-Match" request-header field is used to make a request method 539 conditional. A client that has one or more entities previously 540 obtained from the resource can verify that one of those entities is 541 current by including a list of their associated entity tags in the 542 If-Match header field. 544 This allows efficient updates of cached information with a minimum 545 amount of transaction overhead. It is also used when updating 546 resources, to prevent inadvertent modification of the wrong version 547 of a resource. As a special case, the value "*" matches any current 548 entity of the resource. 550 If-Match = "If-Match" ":" OWS If-Match-v 551 If-Match-v = "*" / 1#entity-tag 553 If any of the entity tags match the entity tag of the entity that 554 would have been returned in the response to a similar GET request 555 (without the If-Match header) on that resource, or if "*" is given 556 and any current entity exists for that resource, then the server MAY 557 perform the requested method as if the If-Match header field did not 558 exist. 560 If none of the entity tags match, or if "*" is given and no current 561 entity exists, the server MUST NOT perform the requested method, and 562 MUST return a 412 (Precondition Failed) response. This behavior is 563 most useful when the client wants to prevent an updating method, such 564 as PUT, from modifying a resource that has changed since the client 565 last retrieved it. 567 If the request would, without the If-Match header field, result in 568 anything other than a 2xx or 412 status, then the If-Match header 569 MUST be ignored. 571 The meaning of "If-Match: *" is that the method SHOULD be performed 572 if the representation selected by the origin server (or by a cache, 573 possibly using the Vary mechanism, see Section 3.5 of [Part6]) 574 exists, and MUST NOT be performed if the representation does not 575 exist. 577 A request intended to update a resource (e.g., a PUT) MAY include an 578 If-Match header field to signal that the request method MUST NOT be 579 applied if the entity corresponding to the If-Match value (a single 580 entity tag) is no longer a representation of that resource. This 581 allows the user to indicate that they do not wish the request to be 582 successful if the resource has been changed without their knowledge. 583 Examples: 585 If-Match: "xyzzy" 586 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 587 If-Match: * 589 The result of a request having both an If-Match header field and 590 either an If-None-Match or an If-Modified-Since header fields is 591 undefined by this specification. 593 6.3. If-Modified-Since 595 The "If-Modified-Since" request-header field is used to make a 596 request method conditional: if the requested variant has not been 597 modified since the time specified in this field, the server will not 598 return an entity; instead, a 304 (Not Modified) response will be 599 returned. 601 If-Modified-Since = "If-Modified-Since" ":" OWS 602 If-Modified-Since-v 603 If-Modified-Since-v = HTTP-date 605 An example of the field is: 607 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 609 A GET method with an If-Modified-Since header and no Range header 610 requests that the identified entity be transferred only if it has 611 been modified since the date given by the If-Modified-Since header. 612 The algorithm for determining this includes the following cases: 614 1. If the request would normally result in anything other than a 200 615 (OK) status, or if the passed If-Modified-Since date is invalid, 616 the response is exactly the same as for a normal GET. A date 617 which is later than the server's current time is invalid. 619 2. If the variant has been modified since the If-Modified-Since 620 date, the response is exactly the same as for a normal GET. 622 3. If the variant has not been modified since a valid If-Modified- 623 Since date, the server SHOULD return a 304 (Not Modified) 624 response. 626 The purpose of this feature is to allow efficient updates of cached 627 information with a minimum amount of transaction overhead. 629 Note: The Range request-header field modifies the meaning of If- 630 Modified-Since; see Section 5.4 of [Part5] for full details. 632 Note: If-Modified-Since times are interpreted by the server, whose 633 clock might not be synchronized with the client. 635 Note: When handling an If-Modified-Since header field, some 636 servers will use an exact date comparison function, rather than a 637 less-than function, for deciding whether to send a 304 (Not 638 Modified) response. To get best results when sending an If- 639 Modified-Since header field for cache validation, clients are 640 advised to use the exact date string received in a previous Last- 641 Modified header field whenever possible. 643 Note: If a client uses an arbitrary date in the If-Modified-Since 644 header instead of a date taken from the Last-Modified header for 645 the same request, the client should be aware of the fact that this 646 date is interpreted in the server's understanding of time. The 647 client should consider unsynchronized clocks and rounding problems 648 due to the different encodings of time between the client and 649 server. This includes the possibility of race conditions if the 650 document has changed between the time it was first requested and 651 the If-Modified-Since date of a subsequent request, and the 652 possibility of clock-skew-related problems if the If-Modified- 653 Since date is derived from the client's clock without correction 654 to the server's clock. Corrections for different time bases 655 between client and server are at best approximate due to network 656 latency. 658 The result of a request having both an If-Modified-Since header field 659 and either an If-Match or an If-Unmodified-Since header fields is 660 undefined by this specification. 662 6.4. If-None-Match 664 The "If-None-Match" request-header field is used to make a request 665 method conditional. A client that has one or more entities 666 previously obtained from the resource can verify that none of those 667 entities is current by including a list of their associated entity 668 tags in the If-None-Match header field. 670 This allows efficient updates of cached information with a minimum 671 amount of transaction overhead. It is also used to prevent a method 672 (e.g. PUT) from inadvertently modifying an existing resource when 673 the client believes that the resource does not exist. 675 As a special case, the value "*" matches any current entity of the 676 resource. 678 If-None-Match = "If-None-Match" ":" OWS If-None-Match-v 679 If-None-Match-v = "*" / 1#entity-tag 681 If any of the entity tags match the entity tag of the entity that 682 would have been returned in the response to a similar GET request 683 (without the If-None-Match header) on that resource, or if "*" is 684 given and any current entity exists for that resource, then the 685 server MUST NOT perform the requested method, unless required to do 686 so because the resource's modification date fails to match that 687 supplied in an If-Modified-Since header field in the request. 688 Instead, if the request method was GET or HEAD, the server SHOULD 689 respond with a 304 (Not Modified) response, including the cache- 690 related header fields (particularly ETag) of one of the entities that 691 matched. For all other request methods, the server MUST respond with 692 a status of 412 (Precondition Failed). 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.) 706 The meaning of "If-None-Match: *" is that the method MUST NOT be 707 performed if the representation selected by the origin server (or by 708 a cache, possibly using the Vary mechanism, see Section 3.5 of 709 [Part6]) exists, and SHOULD be performed if the representation does 710 not exist. This feature is intended to be useful in preventing races 711 between PUT operations. 713 Examples: 715 If-None-Match: "xyzzy" 716 If-None-Match: W/"xyzzy" 717 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 718 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 719 If-None-Match: * 721 The result of a request having both an If-None-Match header field and 722 either an If-Match or an If-Unmodified-Since header fields is 723 undefined by this specification. 725 6.5. If-Unmodified-Since 727 The "If-Unmodified-Since" request-header field is used to make a 728 request method conditional. If the requested resource has not been 729 modified since the time specified in this field, the server SHOULD 730 perform the requested operation as if the If-Unmodified-Since header 731 were not present. 733 If the requested variant has been modified since the specified time, 734 the server MUST NOT perform the requested operation, and MUST return 735 a 412 (Precondition Failed). 737 If-Unmodified-Since = "If-Unmodified-Since" ":" OWS 738 If-Unmodified-Since-v 739 If-Unmodified-Since-v = HTTP-date 741 An example of the field is: 743 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 745 If the request normally (i.e., without the If-Unmodified-Since 746 header) would result in anything other than a 2xx or 412 status, the 747 If-Unmodified-Since header SHOULD be ignored. 749 If the specified date is invalid, the header is ignored. 751 The result of a request having both an If-Unmodified-Since header 752 field and either an If-None-Match or an If-Modified-Since header 753 fields is undefined by this specification. 755 6.6. Last-Modified 757 The "Last-Modified" entity-header field indicates the date and time 758 at which the origin server believes the variant was last modified. 760 Last-Modified = "Last-Modified" ":" OWS Last-Modified-v 761 Last-Modified-v = HTTP-date 763 An example of its use is 765 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 767 The exact meaning of this header field depends on the implementation 768 of the origin server and the nature of the original resource. For 769 files, it may be just the file system last-modified time. For 770 entities with dynamically included parts, it may be the most recent 771 of the set of last-modify times for its component parts. For 772 database gateways, it may be the last-update time stamp of the 773 record. For virtual objects, it may be the last time the internal 774 state changed. 776 An origin server MUST NOT send a Last-Modified date which is later 777 than the server's time of message origination. In such cases, where 778 the resource's last modification would indicate some time in the 779 future, the server MUST replace that date with the message 780 origination date. 782 An origin server SHOULD obtain the Last-Modified value of the entity 783 as close as possible to the time that it generates the Date value of 784 its response. This allows a recipient to make an accurate assessment 785 of the entity's modification time, especially if the entity changes 786 near the time that the response is generated. 788 HTTP/1.1 servers SHOULD send Last-Modified whenever feasible. 790 The Last-Modified entity-header field value is often used as a cache 791 validator. In simple terms, a cache entry is considered to be valid 792 if the entity has not been modified since the Last-Modified value. 794 7. IANA Considerations 796 7.1. Status Code Registration 798 The HTTP Status Code Registry located at 799 should be updated 800 with the registrations below: 802 +-------+---------------------+-------------+ 803 | Value | Description | Reference | 804 +-------+---------------------+-------------+ 805 | 304 | Not Modified | Section 3.1 | 806 | 412 | Precondition Failed | Section 3.2 | 807 +-------+---------------------+-------------+ 809 7.2. Message Header Registration 811 The Message Header Registry located at should be 813 updated with the permanent registrations below (see [RFC3864]): 815 +---------------------+----------+----------+-------------+ 816 | Header Field Name | Protocol | Status | Reference | 817 +---------------------+----------+----------+-------------+ 818 | ETag | http | standard | Section 6.1 | 819 | If-Match | http | standard | Section 6.2 | 820 | If-Modified-Since | http | standard | Section 6.3 | 821 | If-None-Match | http | standard | Section 6.4 | 822 | If-Unmodified-Since | http | standard | Section 6.5 | 823 | Last-Modified | http | standard | Section 6.6 | 824 +---------------------+----------+----------+-------------+ 826 The change controller is: "IETF (iesg@ietf.org) - Internet 827 Engineering Task Force". 829 8. Security Considerations 831 No additional security considerations have been identified beyond 832 those applicable to HTTP in general [Part1]. 834 9. Acknowledgments 836 10. References 838 10.1. Normative References 840 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 841 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 842 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 843 and Message Parsing", draft-ietf-httpbis-p1-messaging-08 844 (work in progress), October 2009. 846 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 847 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 848 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 849 Partial Responses", draft-ietf-httpbis-p5-range-08 (work 850 in progress), October 2009. 852 [Part6] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 853 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 854 Nottingham, M., Ed., and J. Reschke, Ed., "HTTP/1.1, part 855 6: Caching", draft-ietf-httpbis-p6-cache-08 (work in 856 progress), October 2009. 858 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 859 Requirement Levels", BCP 14, RFC 2119, March 1997. 861 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 862 Specifications: ABNF", STD 68, RFC 5234, January 2008. 864 10.2. Informative References 866 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 867 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 868 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 870 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 871 Procedures for Message Header Fields", BCP 90, RFC 3864, 872 September 2004. 874 Appendix A. Compatibility with Previous Versions 876 A.1. Changes from RFC 2616 878 Allow weak entity tags in all requests except range requests 879 (Sections 4 and 6.4). 881 Appendix B. Collected ABNF 883 ETag = "ETag:" OWS ETag-v 884 ETag-v = entity-tag 886 HTTP-date = 888 If-Match = "If-Match:" OWS If-Match-v 889 If-Match-v = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS 890 entity-tag ] ) ) 891 If-Modified-Since = "If-Modified-Since:" OWS If-Modified-Since-v 892 If-Modified-Since-v = HTTP-date 893 If-None-Match = "If-None-Match:" OWS If-None-Match-v 894 If-None-Match-v = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS 895 entity-tag ] ) ) 896 If-Unmodified-Since = "If-Unmodified-Since:" OWS 897 If-Unmodified-Since-v 898 If-Unmodified-Since-v = HTTP-date 900 Last-Modified = "Last-Modified:" OWS Last-Modified-v 901 Last-Modified-v = HTTP-date 903 OWS = 905 entity-tag = [ weak ] opaque-tag 907 opaque-tag = quoted-string 909 quoted-string = 911 weak = %x57.2F ; W/ 913 ABNF diagnostics: 915 ; ETag defined but not used 916 ; If-Match defined but not used 917 ; If-Modified-Since defined but not used 918 ; If-None-Match defined but not used 919 ; If-Unmodified-Since defined but not used 920 ; Last-Modified defined but not used 922 Appendix C. Change Log (to be removed by RFC Editor before publication) 924 C.1. Since RFC2616 926 Extracted relevant partitions from [RFC2616]. 928 C.2. Since draft-ietf-httpbis-p4-conditional-00 930 Closed issues: 932 o : "Normative and 933 Informative references" 935 Other changes: 937 o Move definitions of 304 and 412 condition codes from Part2. 939 C.3. Since draft-ietf-httpbis-p4-conditional-01 941 Ongoing work on ABNF conversion 942 (): 944 o Add explicit references to BNF syntax and rules imported from 945 other parts of the specification. 947 C.4. Since draft-ietf-httpbis-p4-conditional-02 949 Closed issues: 951 o : "Weak ETags on 952 non-GET requests" 954 Ongoing work on IANA Message Header Registration 955 (): 957 o Reference RFC 3984, and update header registrations for headers 958 defined in this document. 960 C.5. Since draft-ietf-httpbis-p4-conditional-03 962 Closed issues: 964 o : "Examples for 965 ETag matching" 967 o : "'entity 968 value' undefined" 970 o : "bogus 2068 971 Date header reference" 973 C.6. Since draft-ietf-httpbis-p4-conditional-04 975 Ongoing work on ABNF conversion 976 (): 978 o Use "/" instead of "|" for alternatives. 980 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 981 whitespace ("OWS") and required whitespace ("RWS"). 983 o Rewrite ABNFs to spell out whitespace rules, factor out header 984 value format definitions. 986 C.7. Since draft-ietf-httpbis-p4-conditional-05 988 Final work on ABNF conversion 989 (): 991 o Add appendix containing collected and expanded ABNF, reorganize 992 ABNF introduction. 994 C.8. Since draft-ietf-httpbis-p4-conditional-06 996 Closed issues: 998 o : "case- 999 sensitivity of etag weakness indicator" 1001 C.9. Since draft-ietf-httpbis-p4-conditional-07 1003 Closed issues: 1005 o : "Weak ETags on 1006 non-GET requests" (If-Match still was defined to require strong 1007 matching) 1009 o : "move IANA 1010 registrations for optional status codes" 1012 Index 1014 3 1015 304 Not Modified (status code) 6 1017 4 1018 412 Precondition Failed (status code) 6 1020 E 1021 ETag header 11 1023 G 1024 Grammar 1025 entity-tag 5 1026 ETag 11 1027 ETag-v 11 1028 If-Match 12 1029 If-Match-v 12 1030 If-Modified-Since 13 1031 If-Modified-Since-v 13 1032 If-None-Match 15 1033 If-None-Match-v 15 1034 If-Unmodified-Since 16 1035 If-Unmodified-Since-v 16 1036 Last-Modified 17 1037 Last-Modified-v 17 1038 opaque-tag 5 1039 weak 5 1041 H 1042 Headers 1043 ETag 11 1044 If-Match 12 1045 If-Modified-Since 13 1046 If-None-Match 15 1047 If-Unmodified-Since 16 1048 Last-Modified 17 1050 I 1051 If-Match header 12 1052 If-Modified-Since header 13 1053 If-None-Match header 15 1054 If-Unmodified-Since header 16 1056 L 1057 Last-Modified header 17 1059 S 1060 Status Codes 1061 304 Not Modified 6 1062 412 Precondition Failed 6 1064 Authors' Addresses 1066 Roy T. Fielding (editor) 1067 Day Software 1068 23 Corporate Plaza DR, Suite 280 1069 Newport Beach, CA 92660 1070 USA 1072 Phone: +1-949-706-5300 1073 Fax: +1-949-706-5305 1074 Email: fielding@gbiv.com 1075 URI: http://roy.gbiv.com/ 1077 Jim Gettys 1078 One Laptop per Child 1079 21 Oak Knoll Road 1080 Carlisle, MA 01741 1081 USA 1083 Email: jg@laptop.org 1084 URI: http://www.laptop.org/ 1086 Jeffrey C. Mogul 1087 Hewlett-Packard Company 1088 HP Labs, Large Scale Systems Group 1089 1501 Page Mill Road, MS 1177 1090 Palo Alto, CA 94304 1091 USA 1093 Email: JeffMogul@acm.org 1095 Henrik Frystyk Nielsen 1096 Microsoft Corporation 1097 1 Microsoft Way 1098 Redmond, WA 98052 1099 USA 1101 Email: henrikn@microsoft.com 1102 Larry Masinter 1103 Adobe Systems, Incorporated 1104 345 Park Ave 1105 San Jose, CA 95110 1106 USA 1108 Email: LMM@acm.org 1109 URI: http://larry.masinter.net/ 1111 Paul J. Leach 1112 Microsoft Corporation 1113 1 Microsoft Way 1114 Redmond, WA 98052 1116 Email: paulle@microsoft.com 1118 Tim Berners-Lee 1119 World Wide Web Consortium 1120 MIT Computer Science and Artificial Intelligence Laboratory 1121 The Stata Center, Building 32 1122 32 Vassar Street 1123 Cambridge, MA 02139 1124 USA 1126 Email: timbl@w3.org 1127 URI: http://www.w3.org/People/Berners-Lee/ 1129 Yves Lafon (editor) 1130 World Wide Web Consortium 1131 W3C / ERCIM 1132 2004, rte des Lucioles 1133 Sophia-Antipolis, AM 06902 1134 France 1136 Email: ylafon@w3.org 1137 URI: http://www.raubacapeu.net/people/yves/ 1138 Julian F. Reschke (editor) 1139 greenbytes GmbH 1140 Hafenweg 16 1141 Muenster, NW 48155 1142 Germany 1144 Phone: +49 251 2807760 1145 Fax: +49 251 2807761 1146 Email: julian.reschke@greenbytes.de 1147 URI: http://greenbytes.de/tech/webdav/