idnits 2.17.1 draft-ietf-httpbis-p4-conditional-07.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 (July 13, 2009) is 5398 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-07 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-07 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-07 -- 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: January 14, 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 July 13, 2009 22 HTTP/1.1, part 4: Conditional Requests 23 draft-ietf-httpbis-p4-conditional-07 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 January 14, 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.8. 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 . . . . . . . . . . . . . . . . . . . . . . 20 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 C.8. Since draft-ietf-httpbis-p4-conditional-06 . . . . . . . . 22 130 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 131 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 133 1. Introduction 135 This document defines HTTP/1.1 response metadata for indicating 136 potential changes to payload content, including modification time 137 stamps and opaque entity-tags, and the HTTP conditional request 138 mechanisms that allow preconditions to be placed on a request method. 139 Conditional GET requests allow for efficient cache updates. Other 140 conditional request methods are used to protect against overwriting 141 or misunderstanding the state of a resource that has been changed 142 unbeknownst to the requesting client. 144 This document is currently disorganized in order to minimize the 145 changes between drafts and enable reviewers to see the smaller errata 146 changes. The next draft will reorganize the sections to better 147 reflect the content. In particular, the sections on resource 148 metadata will be discussed first and then followed by each 149 conditional request-header, concluding with a definition of 150 precedence and the expectation of ordering strong validator checks 151 before weak validator checks. It is likely that more content from 152 [Part6] will migrate to this part, where appropriate. The current 153 mess reflects how widely dispersed these topics and associated 154 requirements had become in [RFC2616]. 156 1.1. Requirements 158 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 159 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 160 document are to be interpreted as described in [RFC2119]. 162 An implementation is not compliant if it fails to satisfy one or more 163 of the MUST or REQUIRED level requirements for the protocols it 164 implements. An implementation that satisfies all the MUST or 165 REQUIRED level and all the SHOULD level requirements for its 166 protocols is said to be "unconditionally compliant"; one that 167 satisfies all the MUST level requirements but not all the SHOULD 168 level requirements for its protocols is said to be "conditionally 169 compliant." 171 1.2. Syntax Notation 173 This specification uses the ABNF syntax defined in Section 1.2 of 174 [Part1] (which extends the syntax defined in [RFC5234] with a list 175 rule). Appendix B shows the collected ABNF, with the list rule 176 expanded. 178 The following core rules are included by reference, as defined in 179 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 180 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 181 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 182 sequence of data), SP (space), VCHAR (any visible USASCII character), 183 and WSP (whitespace). 185 1.2.1. Core Rules 187 The core rules below are defined in Section 1.2.2 of [Part1]: 189 quoted-string = 190 OWS = 192 1.2.2. ABNF Rules defined in other Parts of the Specification 194 The ABNF rules below are defined in other parts: 196 HTTP-date = 198 2. Entity Tags 200 Entity tags are used for comparing two or more entities from the same 201 requested resource. HTTP/1.1 uses entity tags in the ETag 202 (Section 6.1), If-Match (Section 6.2), If-None-Match (Section 6.4), 203 and If-Range (Section 5.3 of [Part5]) header fields. The definition 204 of how they are used and compared as cache validators is in 205 Section 4. An entity tag consists of an opaque quoted string, 206 possibly prefixed by a weakness indicator. 208 entity-tag = [ weak ] opaque-tag 209 weak = %x57.2F ; "W/", case-sensitive 210 opaque-tag = quoted-string 212 A "strong entity tag" MAY be shared by two entities of a resource 213 only if they are equivalent by octet equality. 215 A "weak entity tag," indicated by the "W/" prefix, MAY be shared by 216 two entities of a resource only if the entities are equivalent and 217 could be substituted for each other with no significant change in 218 semantics. A weak entity tag can only be used for weak comparison. 220 An entity tag MUST be unique across all versions of all entities 221 associated with a particular resource. A given entity tag value MAY 222 be used for entities obtained by requests on different URIs. The use 223 of the same entity tag value in conjunction with entities obtained by 224 requests on different URIs does not imply the equivalence of those 225 entities. 227 3. Status Code Definitions 229 3.1. 304 Not Modified 231 If the client has performed a conditional GET request and access is 232 allowed, but the document has not been modified, the server SHOULD 233 respond with this status code. The 304 response MUST NOT contain a 234 message-body, and thus is always terminated by the first empty line 235 after the header fields. 237 The response MUST include the following header fields: 239 o Date, unless its omission is required by Section 8.3.1 of [Part1]. 241 If a clockless origin server obeys these rules, and proxies and 242 clients add their own Date to any response received without one 243 (as already specified by Section 8.3 of [Part1], caches will 244 operate correctly. 246 o ETag and/or Content-Location, if the header would have been sent 247 in a 200 response to the same request. 249 o Expires, Cache-Control, and/or Vary, if the field-value might 250 differ from that sent in any previous response for the same 251 variant. 253 If the conditional GET used a strong cache validator (see Section 4), 254 the response SHOULD NOT include other entity-headers. Otherwise 255 (i.e., the conditional GET used a weak validator), the response MUST 256 NOT include other entity-headers; this prevents inconsistencies 257 between cached entity-bodies and updated headers. 259 If a 304 response indicates an entity not currently cached, then the 260 cache MUST disregard the response and repeat the request without the 261 conditional. 263 If a cache uses a received 304 response to update a cache entry, the 264 cache MUST update the entry to reflect any new field values given in 265 the response. 267 3.2. 412 Precondition Failed 269 The precondition given in one or more of the request-header fields 270 evaluated to false when it was tested on the server. This response 271 code allows the client to place preconditions on the current resource 272 metainformation (header field data) and thus prevent the requested 273 method from being applied to a resource other than the one intended. 275 4. Weak and Strong Validators 277 Since both origin servers and caches will compare two validators to 278 decide if they represent the same or different entities, one normally 279 would expect that if the entity (the entity-body or any entity- 280 headers) changes in any way, then the associated validator would 281 change as well. If this is true, then we call this validator a 282 "strong validator." 284 However, there might be cases when a server prefers to change the 285 validator only on semantically significant changes, and not when 286 insignificant aspects of the entity change. A validator that does 287 not always change when the resource changes is a "weak validator." 289 Entity tags are normally "strong validators," but the protocol 290 provides a mechanism to tag an entity tag as "weak." One can think 291 of a strong validator as one that changes whenever the bits of an 292 entity changes, while a weak value changes whenever the meaning of an 293 entity changes. Alternatively, one can think of a strong validator 294 as part of an identifier for a specific entity, while a weak 295 validator is part of an identifier for a set of semantically 296 equivalent entities. 298 Note: One example of a strong validator is an integer that is 299 incremented in stable storage every time an entity is changed. 301 An entity's modification time, if represented with one-second 302 resolution, could be a weak validator, since it is possible that 303 the resource might be modified twice during a single second. 305 Support for weak validators is optional. However, weak validators 306 allow for more efficient caching of equivalent objects; for 307 example, a hit counter on a site is probably good enough if it is 308 updated every few days or weeks, and any value during that period 309 is likely "good enough" to be equivalent. 311 A "use" of a validator is either when a client generates a request 312 and includes the validator in a validating header field, or when a 313 server compares two validators. 315 Strong validators are usable in any context. Weak validators are 316 only usable in contexts that do not depend on exact equality of an 317 entity. For example, either kind is usable for a conditional GET of 318 a full entity. However, only a strong validator is usable for a sub- 319 range retrieval, since otherwise the client might end up with an 320 internally inconsistent entity. 322 Clients MUST NOT use weak validators in range requests ([Part5]). 324 The only function that HTTP/1.1 defines on validators is comparison. 325 There are two validator comparison functions, depending on whether 326 the comparison context allows the use of weak validators or not: 328 o The strong comparison function: in order to be considered equal, 329 both opaque-tags MUST be identical character-by-character, and 330 both MUST NOT be weak. 332 o The weak comparison function: in order to be considered equal, 333 both opaque-tags MUST be identical character-by-character. 335 The example below shows the results for a set of entity tag pairs, 336 and both the weak and strong comparison function results: 338 +--------+--------+-------------------+-----------------+ 339 | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | 340 +--------+--------+-------------------+-----------------+ 341 | W/"1" | W/"1" | no match | match | 342 | W/"1" | W/"2" | no match | no match | 343 | W/"1" | "1" | no match | match | 344 | "1" | "1" | match | match | 345 +--------+--------+-------------------+-----------------+ 347 An entity tag is strong unless it is explicitly tagged as weak. 348 Section 2 gives the syntax for entity tags. 350 A Last-Modified time, when used as a validator in a request, is 351 implicitly weak unless it is possible to deduce that it is strong, 352 using the following rules: 354 o The validator is being compared by an origin server to the actual 355 current validator for the entity and, 357 o That origin server reliably knows that the associated entity did 358 not change twice during the second covered by the presented 359 validator. 361 or 363 o The validator is about to be used by a client in an If-Modified- 364 Since or If-Unmodified-Since header, because the client has a 365 cache entry for the associated entity, and 367 o That cache entry includes a Date value, which gives the time when 368 the origin server sent the original response, and 370 o The presented Last-Modified time is at least 60 seconds before the 371 Date value. 373 or 375 o The validator is being compared by an intermediate cache to the 376 validator stored in its cache entry for the entity, and 378 o That cache entry includes a Date value, which gives the time when 379 the origin server sent the original response, and 381 o The presented Last-Modified time is at least 60 seconds before the 382 Date value. 384 This method relies on the fact that if two different responses were 385 sent by the origin server during the same second, but both had the 386 same Last-Modified time, then at least one of those responses would 387 have a Date value equal to its Last-Modified time. The arbitrary 60- 388 second limit guards against the possibility that the Date and Last- 389 Modified values are generated from different clocks, or at somewhat 390 different times during the preparation of the response. An 391 implementation MAY use a value larger than 60 seconds, if it is 392 believed that 60 seconds is too short. 394 If a client wishes to perform a sub-range retrieval on a value for 395 which it has only a Last-Modified time and no opaque validator, it 396 MAY do this only if the Last-Modified time is strong in the sense 397 described here. 399 A cache or origin server receiving a conditional range request 400 ([Part5]) MUST use the strong comparison function to evaluate the 401 condition. 403 These rules allow HTTP/1.1 caches and clients to safely perform sub- 404 range retrievals on values that have been obtained from HTTP/1.0 405 servers. 407 5. Rules for When to Use Entity Tags and Last-Modified Dates 409 We adopt a set of rules and recommendations for origin servers, 410 clients, and caches regarding when various validator types ought to 411 be used, and for what purposes. 413 HTTP/1.1 origin servers: 415 o SHOULD send an entity tag validator unless it is not feasible to 416 generate one. 418 o MAY send a weak entity tag instead of a strong entity tag, if 419 performance considerations support the use of weak entity tags, or 420 if it is unfeasible to send a strong entity tag. 422 o SHOULD send a Last-Modified value if it is feasible to send one, 423 unless the risk of a breakdown in semantic transparency that could 424 result from using this date in an If-Modified-Since header would 425 lead to serious problems. 427 In other words, the preferred behavior for an HTTP/1.1 origin server 428 is to send both a strong entity tag and a Last-Modified value. 430 In order to be legal, a strong entity tag MUST change whenever the 431 associated entity changes in any way. A weak entity tag SHOULD 432 change whenever the associated entity changes in a semantically 433 significant way. 435 Note: in order to provide semantically transparent caching, an 436 origin server must avoid reusing a specific strong entity tag 437 value for two different entities, or reusing a specific weak 438 entity tag value for two semantically different entities. Cache 439 entries might persist for arbitrarily long periods, regardless of 440 expiration times, so it might be inappropriate to expect that a 441 cache will never again attempt to validate an entry using a 442 validator that it obtained at some point in the past. 444 HTTP/1.1 clients: 446 o If an entity tag has been provided by the origin server, MUST use 447 that entity tag in any cache-conditional request (using If-Match 448 or If-None-Match). 450 o If only a Last-Modified value has been provided by the origin 451 server, SHOULD use that value in non-subrange cache-conditional 452 requests (using If-Modified-Since). 454 o If only a Last-Modified value has been provided by an HTTP/1.0 455 origin server, MAY use that value in subrange cache-conditional 456 requests (using If-Unmodified-Since:). The user agent SHOULD 457 provide a way to disable this, in case of difficulty. 459 o If both an entity tag and a Last-Modified value have been provided 460 by the origin server, SHOULD use both validators in cache- 461 conditional requests. This allows both HTTP/1.0 and HTTP/1.1 462 caches to respond appropriately. 464 An HTTP/1.1 origin server, upon receiving a conditional request that 465 includes both a Last-Modified date (e.g., in an If-Modified-Since or 466 If-Unmodified-Since header field) and one or more entity tags (e.g., 467 in an If-Match, If-None-Match, or If-Range header field) as cache 468 validators, MUST NOT return a response status of 304 (Not Modified) 469 unless doing so is consistent with all of the conditional header 470 fields in the request. 472 An HTTP/1.1 caching proxy, upon receiving a conditional request that 473 includes both a Last-Modified date and one or more entity tags as 474 cache validators, MUST NOT return a locally cached response to the 475 client unless that cached response is consistent with all of the 476 conditional header fields in the request. 478 Note: The general principle behind these rules is that HTTP/1.1 479 servers and clients should transmit as much non-redundant 480 information as is available in their responses and requests. 481 HTTP/1.1 systems receiving this information will make the most 482 conservative assumptions about the validators they receive. 484 HTTP/1.0 clients and caches will ignore entity tags. Generally, 485 last-modified values received or used by these systems will 486 support transparent and efficient caching, and so HTTP/1.1 origin 487 servers should provide Last-Modified values. In those rare cases 488 where the use of a Last-Modified value as a validator by an 489 HTTP/1.0 system could result in a serious problem, then HTTP/1.1 490 origin servers should not provide one. 492 6. Header Field Definitions 494 This section defines the syntax and semantics of HTTP/1.1 header 495 fields related to conditional requests. 497 For entity-header fields, both sender and recipient refer to either 498 the client or the server, depending on who sends and who receives the 499 entity. 501 6.1. ETag 503 The response-header field "ETag" provides the current value of the 504 entity tag (see Section 2) for the requested variant. The headers 505 used with entity tags are described in Sections 6.2 and 6.4 of this 506 document, and in Section 5.3 of [Part5]. The entity tag MAY be used 507 for comparison with other entities from the same resource (see 508 Section 4). 510 ETag = "ETag" ":" OWS ETag-v 511 ETag-v = entity-tag 513 Examples: 515 ETag: "xyzzy" 516 ETag: W/"xyzzy" 517 ETag: "" 519 The ETag response-header field value, an entity tag, provides for an 520 "opaque" cache validator. This might allow more reliable validation 521 in situations where it is inconvenient to store modification dates, 522 where the one-second resolution of HTTP date values is not 523 sufficient, or where the origin server wishes to avoid certain 524 paradoxes that might arise from the use of modification dates. 526 The principle behind entity tags is that only the service author 527 knows the semantics of a resource well enough to select an 528 appropriate cache validation mechanism, and the specification of any 529 validator comparison function more complex than byte-equality would 530 open up a can of worms. Thus, comparisons of any other headers 531 (except Last-Modified, for compatibility with HTTP/1.0) are never 532 used for purposes of validating a cache entry. 534 6.2. If-Match 536 The request-header field "If-Match" is used with a method to make it 537 conditional. A client that has one or more entities previously 538 obtained from the resource can verify that one of those entities is 539 current by including a list of their associated entity tags in the 540 If-Match header field. Entity tags are defined in Section 2. The 541 purpose of this feature is to allow efficient updates of cached 542 information with a minimum amount of transaction overhead. It is 543 also used, on updating requests, to prevent inadvertent modification 544 of the wrong version of a resource. As a special case, the value "*" 545 matches any current entity of the resource. 547 If-Match = "If-Match" ":" OWS If-Match-v 548 If-Match-v = "*" / 1#entity-tag 550 If any of the entity tags match the entity tag of the entity that 551 would have been returned in the response to a similar GET request 552 (without the If-Match header) on that resource, or if "*" is given 553 and any current entity exists for that resource, then the server MAY 554 perform the requested method as if the If-Match header field did not 555 exist. 557 A server MUST use the strong comparison function (see Section 4) to 558 compare the entity tags in If-Match. 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 request-header field "If-Modified-Since" is used with a method to 596 make it conditional: if the requested variant has not been modified 597 since the time specified in this field, an entity will not be 598 returned from the server; instead, a 304 (Not Modified) response will 599 be returned without any message-body. 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 request-header field "If-None-Match" is used with a method to 665 make it 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. The purpose of this feature 669 is to allow efficient updates of cached information with a minimum 670 amount of transaction overhead. It is also used to prevent a method 671 (e.g. PUT) from inadvertently modifying an existing resource when 672 the client believes that the resource does not exist. 674 As a special case, the value "*" matches any current entity of the 675 resource. 677 If-None-Match = "If-None-Match" ":" OWS If-None-Match-v 678 If-None-Match-v = "*" / 1#entity-tag 680 If any of the entity tags match the entity tag of the entity that 681 would have been returned in the response to a similar GET request 682 (without the If-None-Match header) on that resource, or if "*" is 683 given and any current entity exists for that resource, then the 684 server MUST NOT perform the requested method, unless required to do 685 so because the resource's modification date fails to match that 686 supplied in an If-Modified-Since header field in the request. 687 Instead, if the request method was GET or HEAD, the server SHOULD 688 respond with a 304 (Not Modified) response, including the cache- 689 related header fields (particularly ETag) of one of the entities that 690 matched. For all other request methods, the server MUST respond with 691 a status of 412 (Precondition Failed). 693 See Section 4 for rules on how to determine if two entity tags match. 695 If none of the entity tags match, then the server MAY perform the 696 requested method as if the If-None-Match header field did not exist, 697 but MUST also ignore any If-Modified-Since header field(s) in the 698 request. That is, if no entity tags match, then the server MUST NOT 699 return a 304 (Not Modified) response. 701 If the request would, without the If-None-Match header field, result 702 in anything other than a 2xx or 304 status, then the If-None-Match 703 header MUST be ignored. (See Section 5 for a discussion of server 704 behavior when both If-Modified-Since and If-None-Match appear in the 705 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 request-header field "If-Unmodified-Since" is used with a method 728 to make it 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 entity-header field "Last-Modified" 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. Message Header Registration 798 The Message Header Registry located at should be 800 updated with the permanent registrations below (see [RFC3864]): 802 +---------------------+----------+----------+-------------+ 803 | Header Field Name | Protocol | Status | Reference | 804 +---------------------+----------+----------+-------------+ 805 | ETag | http | standard | Section 6.1 | 806 | If-Match | http | standard | Section 6.2 | 807 | If-Modified-Since | http | standard | Section 6.3 | 808 | If-None-Match | http | standard | Section 6.4 | 809 | If-Unmodified-Since | http | standard | Section 6.5 | 810 | Last-Modified | http | standard | Section 6.6 | 811 +---------------------+----------+----------+-------------+ 813 The change controller is: "IETF (iesg@ietf.org) - Internet 814 Engineering Task Force". 816 8. Security Considerations 818 No additional security considerations have been identified beyond 819 those applicable to HTTP in general [Part1]. 821 9. Acknowledgments 823 10. References 825 10.1. Normative References 827 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 828 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 829 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 830 and Message Parsing", draft-ietf-httpbis-p1-messaging-07 831 (work in progress), July 2009. 833 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 834 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 835 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 836 Partial Responses", draft-ietf-httpbis-p5-range-07 (work 837 in progress), July 2009. 839 [Part6] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 840 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 841 Nottingham, M., Ed., and J. Reschke, Ed., "HTTP/1.1, part 842 6: Caching", draft-ietf-httpbis-p6-cache-07 (work in 843 progress), July 2009. 845 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 846 Requirement Levels", BCP 14, RFC 2119, March 1997. 848 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 849 Specifications: ABNF", STD 68, RFC 5234, January 2008. 851 10.2. Informative References 853 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 854 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 855 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 857 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 858 Procedures for Message Header Fields", BCP 90, RFC 3864, 859 September 2004. 861 Appendix A. Compatibility with Previous Versions 863 A.1. Changes from RFC 2616 865 Allow weak entity tags in all requests except range requests 866 (Sections 4 and 6.4). 868 Appendix B. Collected ABNF 870 ETag = "ETag:" OWS ETag-v 871 ETag-v = entity-tag 873 HTTP-date = 875 If-Match = "If-Match:" OWS If-Match-v 876 If-Match-v = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS 877 entity-tag ] ) ) 878 If-Modified-Since = "If-Modified-Since:" OWS If-Modified-Since-v 879 If-Modified-Since-v = HTTP-date 880 If-None-Match = "If-None-Match:" OWS If-None-Match-v 881 If-None-Match-v = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS 882 entity-tag ] ) ) 883 If-Unmodified-Since = "If-Unmodified-Since:" OWS 884 If-Unmodified-Since-v 885 If-Unmodified-Since-v = HTTP-date 887 Last-Modified = "Last-Modified:" OWS Last-Modified-v 888 Last-Modified-v = HTTP-date 890 OWS = 892 entity-tag = [ weak ] opaque-tag 894 opaque-tag = quoted-string 896 quoted-string = 898 weak = %x57.2F ; W/ 900 ABNF diagnostics: 902 ; ETag defined but not used 903 ; If-Match defined but not used 904 ; If-Modified-Since defined but not used 905 ; If-None-Match defined but not used 906 ; If-Unmodified-Since defined but not used 907 ; Last-Modified defined but not used 909 Appendix C. Change Log (to be removed by RFC Editor before publication) 911 C.1. Since RFC2616 913 Extracted relevant partitions from [RFC2616]. 915 C.2. Since draft-ietf-httpbis-p4-conditional-00 917 Closed issues: 919 o : "Normative and 920 Informative references" 922 Other changes: 924 o Move definitions of 304 and 412 condition codes from Part2. 926 C.3. Since draft-ietf-httpbis-p4-conditional-01 928 Ongoing work on ABNF conversion 929 (): 931 o Add explicit references to BNF syntax and rules imported from 932 other parts of the specification. 934 C.4. Since draft-ietf-httpbis-p4-conditional-02 936 Closed issues: 938 o : "Weak ETags on 939 non-GET requests" 941 Ongoing work on IANA Message Header Registration 942 (): 944 o Reference RFC 3984, and update header registrations for headers 945 defined in this document. 947 C.5. Since draft-ietf-httpbis-p4-conditional-03 949 Closed issues: 951 o : "Examples for 952 ETag matching" 954 o : "'entity 955 value' undefined" 957 o : "bogus 2068 958 Date header reference" 960 C.6. Since draft-ietf-httpbis-p4-conditional-04 962 Ongoing work on ABNF conversion 963 (): 965 o Use "/" instead of "|" for alternatives. 967 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 968 whitespace ("OWS") and required whitespace ("RWS"). 970 o Rewrite ABNFs to spell out whitespace rules, factor out header 971 value format definitions. 973 C.7. Since draft-ietf-httpbis-p4-conditional-05 975 Final work on ABNF conversion 976 (): 978 o Add appendix containing collected and expanded ABNF, reorganize 979 ABNF introduction. 981 C.8. Since draft-ietf-httpbis-p4-conditional-06 983 Closed issues: 985 o : "case- 986 sensitivity of etag weakness indicator" 988 Index 990 3 991 304 Not Modified (status code) 6 993 4 994 412 Precondition Failed (status code) 6 996 E 997 ETag header 11 999 G 1000 Grammar 1001 entity-tag 5 1002 ETag 11 1003 ETag-v 11 1004 If-Match 12 1005 If-Match-v 12 1006 If-Modified-Since 13 1007 If-Modified-Since-v 13 1008 If-None-Match 15 1009 If-None-Match-v 15 1010 If-Unmodified-Since 16 1011 If-Unmodified-Since-v 16 1012 Last-Modified 17 1013 Last-Modified-v 17 1014 opaque-tag 5 1015 weak 5 1017 H 1018 Headers 1019 ETag 11 1020 If-Match 12 1021 If-Modified-Since 13 1022 If-None-Match 15 1023 If-Unmodified-Since 16 1024 Last-Modified 17 1026 I 1027 If-Match header 12 1028 If-Modified-Since header 13 1029 If-None-Match header 15 1030 If-Unmodified-Since header 16 1032 L 1033 Last-Modified header 17 1035 S 1036 Status Codes 1037 304 Not Modified 6 1038 412 Precondition Failed 6 1040 Authors' Addresses 1042 Roy T. Fielding (editor) 1043 Day Software 1044 23 Corporate Plaza DR, Suite 280 1045 Newport Beach, CA 92660 1046 USA 1048 Phone: +1-949-706-5300 1049 Fax: +1-949-706-5305 1050 Email: fielding@gbiv.com 1051 URI: http://roy.gbiv.com/ 1052 Jim Gettys 1053 One Laptop per Child 1054 21 Oak Knoll Road 1055 Carlisle, MA 01741 1056 USA 1058 Email: jg@laptop.org 1059 URI: http://www.laptop.org/ 1061 Jeffrey C. Mogul 1062 Hewlett-Packard Company 1063 HP Labs, Large Scale Systems Group 1064 1501 Page Mill Road, MS 1177 1065 Palo Alto, CA 94304 1066 USA 1068 Email: JeffMogul@acm.org 1070 Henrik Frystyk Nielsen 1071 Microsoft Corporation 1072 1 Microsoft Way 1073 Redmond, WA 98052 1074 USA 1076 Email: henrikn@microsoft.com 1078 Larry Masinter 1079 Adobe Systems, Incorporated 1080 345 Park Ave 1081 San Jose, CA 95110 1082 USA 1084 Email: LMM@acm.org 1085 URI: http://larry.masinter.net/ 1087 Paul J. Leach 1088 Microsoft Corporation 1089 1 Microsoft Way 1090 Redmond, WA 98052 1092 Email: paulle@microsoft.com 1093 Tim Berners-Lee 1094 World Wide Web Consortium 1095 MIT Computer Science and Artificial Intelligence Laboratory 1096 The Stata Center, Building 32 1097 32 Vassar Street 1098 Cambridge, MA 02139 1099 USA 1101 Email: timbl@w3.org 1102 URI: http://www.w3.org/People/Berners-Lee/ 1104 Yves Lafon (editor) 1105 World Wide Web Consortium 1106 W3C / ERCIM 1107 2004, rte des Lucioles 1108 Sophia-Antipolis, AM 06902 1109 France 1111 Email: ylafon@w3.org 1112 URI: http://www.raubacapeu.net/people/yves/ 1114 Julian F. Reschke (editor) 1115 greenbytes GmbH 1116 Hafenweg 16 1117 Muenster, NW 48155 1118 Germany 1120 Phone: +49 251 2807760 1121 Fax: +49 251 2807761 1122 Email: julian.reschke@greenbytes.de 1123 URI: http://greenbytes.de/tech/webdav/