idnits 2.17.1 draft-ietf-httpbis-p4-conditional-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 12, 2010) is 5029 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-10 == Outdated reference: A later version (-20) exists of draft-ietf-httpbis-p3-payload-10 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-10 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-10 -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 0 errors (**), 0 flaws (~~), 5 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 Alcatel-Lucent 6 Expires: January 13, 2011 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 12, 2010 22 HTTP/1.1, part 4: Conditional Requests 23 draft-ietf-httpbis-p4-conditional-10 25 Abstract 27 The Hypertext Transfer Protocol (HTTP) is an application-level 28 protocol for distributed, collaborative, hypermedia information 29 systems. HTTP has been in use by the World Wide Web global 30 information initiative since 1990. This document is Part 4 of the 31 seven-part specification that defines the protocol referred to as 32 "HTTP/1.1" and, taken together, obsoletes RFC 2616. Part 4 defines 33 request header fields for indicating conditional requests and the 34 rules for constructing responses to those requests. 36 Editorial Note (To be removed by RFC Editor) 38 Discussion of this draft should take place on the HTTPBIS working 39 group mailing list (ietf-http-wg@w3.org). The current issues list is 40 at and related 41 documents (including fancy diffs) can be found at 42 . 44 The changes in this draft are summarized in Appendix C.11. 46 Status of This Memo 48 This Internet-Draft is submitted in full conformance with the 49 provisions of BCP 78 and BCP 79. 51 Internet-Drafts are working documents of the Internet Engineering 52 Task Force (IETF). Note that other groups may also distribute 53 working documents as Internet-Drafts. The list of current Internet- 54 Drafts is at http://datatracker.ietf.org/drafts/current/. 56 Internet-Drafts are draft documents valid for a maximum of six months 57 and may be updated, replaced, or obsoleted by other documents at any 58 time. It is inappropriate to use Internet-Drafts as reference 59 material or to cite them other than as "work in progress." 61 This Internet-Draft will expire on January 13, 2011. 63 Copyright Notice 65 Copyright (c) 2010 IETF Trust and the persons identified as the 66 document authors. All rights reserved. 68 This document is subject to BCP 78 and the IETF Trust's Legal 69 Provisions Relating to IETF Documents 70 (http://trustee.ietf.org/license-info) in effect on the date of 71 publication of this document. Please review these documents 72 carefully, as they describe your rights and restrictions with respect 73 to this document. Code Components extracted from this document must 74 include Simplified BSD License text as described in Section 4.e of 75 the Trust Legal Provisions and are provided without warranty as 76 described in the Simplified BSD License. 78 This document may contain material from IETF Documents or IETF 79 Contributions published or made publicly available before November 80 10, 2008. The person(s) controlling the copyright in some of this 81 material may not have granted the IETF Trust the right to allow 82 modifications of such material outside the IETF Standards Process. 83 Without obtaining an adequate license from the person(s) controlling 84 the copyright in such materials, this document may not be modified 85 outside the IETF Standards Process, and derivative works of it may 86 not be created outside the IETF Standards Process, except to format 87 it for publication as an RFC or to translate it into languages other 88 than English. 90 Table of Contents 92 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 93 1.1. Requirements . . . . . . . . . . . . . . . . . . . . . . . 4 94 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 4 95 1.2.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 5 96 1.2.2. ABNF Rules defined in other Parts of the 97 Specification . . . . . . . . . . . . . . . . . . . . 5 98 2. Entity Tags . . . . . . . . . . . . . . . . . . . . . . . . . 5 99 2.1. Example: Entity Tags varying on Content-Negotiated 100 Resources . . . . . . . . . . . . . . . . . . . . . . . . 6 101 3. Status Code Definitions . . . . . . . . . . . . . . . . . . . 7 102 3.1. 304 Not Modified . . . . . . . . . . . . . . . . . . . . . 7 103 3.2. 412 Precondition Failed . . . . . . . . . . . . . . . . . 8 104 4. Weak and Strong Validators . . . . . . . . . . . . . . . . . . 8 105 5. Rules for When to Use Entity Tags and Last-Modified Dates . . 11 106 6. Header Field Definitions . . . . . . . . . . . . . . . . . . . 12 107 6.1. ETag . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 108 6.2. If-Match . . . . . . . . . . . . . . . . . . . . . . . . . 13 109 6.3. If-Modified-Since . . . . . . . . . . . . . . . . . . . . 14 110 6.4. If-None-Match . . . . . . . . . . . . . . . . . . . . . . 16 111 6.5. If-Unmodified-Since . . . . . . . . . . . . . . . . . . . 17 112 6.6. Last-Modified . . . . . . . . . . . . . . . . . . . . . . 18 113 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 114 7.1. Status Code Registration . . . . . . . . . . . . . . . . . 19 115 7.2. Message Header Registration . . . . . . . . . . . . . . . 19 116 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19 117 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 118 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 119 10.1. Normative References . . . . . . . . . . . . . . . . . . . 19 120 10.2. Informative References . . . . . . . . . . . . . . . . . . 20 121 Appendix A. Compatibility with Previous Versions . . . . . . . . 20 122 A.1. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 20 123 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 21 124 Appendix C. Change Log (to be removed by RFC Editor before 125 publication) . . . . . . . . . . . . . . . . . . . . 21 126 C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 21 127 C.2. Since draft-ietf-httpbis-p4-conditional-00 . . . . . . . . 22 128 C.3. Since draft-ietf-httpbis-p4-conditional-01 . . . . . . . . 22 129 C.4. Since draft-ietf-httpbis-p4-conditional-02 . . . . . . . . 22 130 C.5. Since draft-ietf-httpbis-p4-conditional-03 . . . . . . . . 22 131 C.6. Since draft-ietf-httpbis-p4-conditional-04 . . . . . . . . 23 132 C.7. Since draft-ietf-httpbis-p4-conditional-05 . . . . . . . . 23 133 C.8. Since draft-ietf-httpbis-p4-conditional-06 . . . . . . . . 23 134 C.9. Since draft-ietf-httpbis-p4-conditional-07 . . . . . . . . 23 135 C.10. Since draft-ietf-httpbis-p4-conditional-08 . . . . . . . . 23 136 C.11. Since draft-ietf-httpbis-p4-conditional-09 . . . . . . . . 23 137 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 139 1. Introduction 141 This document defines HTTP/1.1 response metadata for indicating 142 potential changes to payload content, including modification time 143 stamps and opaque entity-tags, and the HTTP conditional request 144 mechanisms that allow preconditions to be placed on a request method. 145 Conditional GET requests allow for efficient cache updates. Other 146 conditional request methods are used to protect against overwriting 147 or misunderstanding the state of a resource that has been changed 148 unbeknownst to the requesting client. 150 This document is currently disorganized in order to minimize the 151 changes between drafts and enable reviewers to see the smaller errata 152 changes. The next draft will reorganize the sections to better 153 reflect the content. In particular, the sections on resource 154 metadata will be discussed first and then followed by each 155 conditional request-header, concluding with a definition of 156 precedence and the expectation of ordering strong validator checks 157 before weak validator checks. It is likely that more content from 158 [Part6] will migrate to this part, where appropriate. The current 159 mess reflects how widely dispersed these topics and associated 160 requirements had become in [RFC2616]. 162 1.1. Requirements 164 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 165 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 166 document are to be interpreted as described in [RFC2119]. 168 An implementation is not compliant if it fails to satisfy one or more 169 of the "MUST" or "REQUIRED" level requirements for the protocols it 170 implements. An implementation that satisfies all the "MUST" or 171 "REQUIRED" level and all the "SHOULD" level requirements for its 172 protocols is said to be "unconditionally compliant"; one that 173 satisfies all the "MUST" level requirements but not all the "SHOULD" 174 level requirements for its protocols is said to be "conditionally 175 compliant". 177 1.2. Syntax Notation 179 This specification uses the ABNF syntax defined in Section 1.2 of 180 [Part1] (which extends the syntax defined in [RFC5234] with a list 181 rule). Appendix B shows the collected ABNF, with the list rule 182 expanded. 184 The following core rules are included by reference, as defined in 185 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 186 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 187 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 188 sequence of data), SP (space), VCHAR (any visible USASCII character), 189 and WSP (whitespace). 191 1.2.1. Core Rules 193 The core rules below are defined in Section 1.2.2 of [Part1]: 195 quoted-string = 196 OWS = 198 1.2.2. ABNF Rules defined in other Parts of the Specification 200 The ABNF rules below are defined in other parts: 202 HTTP-date = 204 2. Entity Tags 206 Entity tags are used for comparing two or more entities from the same 207 requested resource. HTTP/1.1 uses entity tags in the ETag 208 (Section 6.1), If-Match (Section 6.2), If-None-Match (Section 6.4), 209 and If-Range (Section 5.3 of [Part5]) header fields. The definition 210 of how they are used and compared as cache validators is in 211 Section 4. An entity tag consists of an opaque quoted string, 212 possibly prefixed by a weakness indicator. 214 entity-tag = [ weak ] opaque-tag 215 weak = %x57.2F ; "W/", case-sensitive 216 opaque-tag = quoted-string 218 A "strong entity tag" MAY be shared by two entities of a resource 219 only if they are equivalent by octet equality. 221 A "weak entity tag," indicated by the "W/" prefix, MAY be shared by 222 two entities of a resource only if the entities are equivalent and 223 could be substituted for each other with no significant change in 224 semantics. A weak entity tag can only be used for weak comparison. 226 An entity tag MUST be unique across all versions of all entities 227 associated with a particular resource. A given entity tag value MAY 228 be used for entities obtained by requests on different URIs. The use 229 of the same entity tag value in conjunction with entities obtained by 230 requests on different URIs does not imply the equivalence of those 231 entities. 233 2.1. Example: Entity Tags varying on Content-Negotiated Resources 235 Consider a resource that is subject to content negotiation (Section 4 236 of [Part3]), and where the representations returned upon a GET 237 request vary based on the Accept-Encoding request header field 238 (Section 5.3 of [Part3]): 240 >> Request: 242 GET /index HTTP/1.1 243 Host: www.example.com 244 Accept-Encoding: gzip 246 In this case, the response may use the gzip Content Coding or not. 247 If it does, it might look like that: 249 >> Response: 251 HTTP/1.1 200 OK 252 Date: Thu, 26 Mar 2010 00:05:00 GMT 253 ETag: "123-a" 254 Content-Length: 70 255 Vary: Accept-Encoding 256 Content-Type: text/plain 258 Hello World! 259 Hello World! 260 Hello World! 261 Hello World! 262 Hello World! 264 A variant that does use gzip Content Coding would be: 266 >> Response: 268 HTTP/1.1 200 OK 269 Date: Thu, 26 Mar 2010 00:05:00 GMT 270 ETag: "123-b" 271 Content-Length: 43 272 Vary: Accept-Encoding 273 Content-Type: text/plain 274 Content-Encoding: gzip 276 ...binary data... 278 Note: Content Codings are a property of the response entity, thus 279 affect the Entity Tag. An alternative are Transfer Codings 280 (Section 6.2 of [Part1]) which apply only to the transfer of the 281 message, and thus do not require assigning distinct entity tags. 283 3. Status Code Definitions 285 3.1. 304 Not Modified 287 If the client has performed a conditional GET request and access is 288 allowed, but the document has not been modified, the server SHOULD 289 respond with this status code. The 304 response MUST NOT contain a 290 message-body, and thus is always terminated by the first empty line 291 after the header fields. 293 The response MUST include the following header fields: 295 o Date, unless its omission is required by Section 9.3.1 of [Part1]. 297 If a clockless origin server obeys these rules, and proxies and 298 clients add their own Date to any response received without one 299 (as already specified by Section 9.3 of [Part1], caches will 300 operate correctly. 302 o ETag and/or Content-Location, if the header would have been sent 303 in a 200 response to the same request. 305 o Expires, Cache-Control, and/or Vary, if the field-value might 306 differ from that sent in any previous response for the same 307 variant. 309 If the conditional GET used a strong cache validator (see Section 4), 310 the response SHOULD NOT include other entity-headers. Otherwise 311 (i.e., the conditional GET used a weak validator), the response MUST 312 NOT include other entity-headers; this prevents inconsistencies 313 between cached entity-bodies and updated headers. 315 If a 304 response indicates an entity not currently cached, then the 316 cache MUST disregard the response and repeat the request without the 317 conditional. 319 If a cache uses a received 304 response to update a cache entry, the 320 cache MUST update the entry to reflect any new field values given in 321 the response. 323 3.2. 412 Precondition Failed 325 The precondition given in one or more of the request-header fields 326 evaluated to false when it was tested on the server. This response 327 code allows the client to place preconditions on the current resource 328 metainformation (header field data) and thus prevent the requested 329 method from being applied to a resource other than the one intended. 331 4. Weak and Strong Validators 333 Since both origin servers and caches will compare two validators to 334 decide if they represent the same or different entities, one normally 335 would expect that if the entity (the entity-body or any entity- 336 headers) changes in any way, then the associated validator would 337 change as well. If this is true, then we call this validator a 338 "strong validator." 340 However, there might be cases when a server prefers to change the 341 validator only on semantically significant changes, and not when 342 insignificant aspects of the entity change. A validator that does 343 not always change when the resource changes is a "weak validator." 345 Entity tags are normally "strong validators," but the protocol 346 provides a mechanism to tag an entity tag as "weak." One can think 347 of a strong validator as one that changes whenever the bits of an 348 entity changes, while a weak value changes whenever the meaning of an 349 entity changes. Alternatively, one can think of a strong validator 350 as part of an identifier for a specific entity, while a weak 351 validator is part of an identifier for a set of semantically 352 equivalent entities. 354 Note: One example of a strong validator is an integer that is 355 incremented in stable storage every time an entity is changed. 357 An entity's modification time, if represented with one-second 358 resolution, could be a weak validator, since it is possible that 359 the resource might be modified twice during a single second. 361 Support for weak validators is optional. However, weak validators 362 allow for more efficient caching of equivalent objects; for 363 example, a hit counter on a site is probably good enough if it is 364 updated every few days or weeks, and any value during that period 365 is likely "good enough" to be equivalent. 367 A "use" of a validator is either when a client generates a request 368 and includes the validator in a validating header field, or when a 369 server compares two validators. 371 Strong validators are usable in any context. Weak validators are 372 only usable in contexts that do not depend on exact equality of an 373 entity. For example, either kind is usable for a conditional GET of 374 a full entity. However, only a strong validator is usable for a sub- 375 range retrieval, since otherwise the client might end up with an 376 internally inconsistent entity. 378 Clients MUST NOT use weak validators in range requests ([Part5]). 380 The only function that HTTP/1.1 defines on validators is comparison. 381 There are two validator comparison functions, depending on whether 382 the comparison context allows the use of weak validators or not: 384 o The strong comparison function: in order to be considered equal, 385 both opaque-tags MUST be identical character-by-character, and 386 both MUST NOT be weak. 388 o The weak comparison function: in order to be considered equal, 389 both opaque-tags MUST be identical character-by-character, but 390 either or both of them MAY be tagged as "weak" without affecting 391 the result. 393 The example below shows the results for a set of entity tag pairs, 394 and both the weak and strong comparison function results: 396 +--------+--------+-------------------+-----------------+ 397 | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | 398 +--------+--------+-------------------+-----------------+ 399 | W/"1" | W/"1" | no match | match | 400 | W/"1" | W/"2" | no match | no match | 401 | W/"1" | "1" | no match | match | 402 | "1" | "1" | match | match | 403 +--------+--------+-------------------+-----------------+ 405 An entity tag is strong unless it is explicitly tagged as weak. 406 Section 2 gives the syntax for entity tags. 408 A Last-Modified time, when used as a validator in a request, is 409 implicitly weak unless it is possible to deduce that it is strong, 410 using the following rules: 412 o The validator is being compared by an origin server to the actual 413 current validator for the entity and, 415 o That origin server reliably knows that the associated entity did 416 not change twice during the second covered by the presented 417 validator. 419 or 421 o The validator is about to be used by a client in an If-Modified- 422 Since or If-Unmodified-Since header, because the client has a 423 cache entry for the associated entity, and 425 o That cache entry includes a Date value, which gives the time when 426 the origin server sent the original response, and 428 o The presented Last-Modified time is at least 60 seconds before the 429 Date value. 431 or 433 o The validator is being compared by an intermediate cache to the 434 validator stored in its cache entry for the entity, and 436 o That cache entry includes a Date value, which gives the time when 437 the origin server sent the original response, and 439 o The presented Last-Modified time is at least 60 seconds before the 440 Date value. 442 This method relies on the fact that if two different responses were 443 sent by the origin server during the same second, but both had the 444 same Last-Modified time, then at least one of those responses would 445 have a Date value equal to its Last-Modified time. The arbitrary 60- 446 second limit guards against the possibility that the Date and Last- 447 Modified values are generated from different clocks, or at somewhat 448 different times during the preparation of the response. An 449 implementation MAY use a value larger than 60 seconds, if it is 450 believed that 60 seconds is too short. 452 If a client wishes to perform a sub-range retrieval on a value for 453 which it has only a Last-Modified time and no opaque validator, it 454 MAY do this only if the Last-Modified time is strong in the sense 455 described here. 457 A cache or origin server receiving a conditional range request 458 ([Part5]) MUST use the strong comparison function to evaluate the 459 condition. 461 These rules allow HTTP/1.1 caches and clients to safely perform sub- 462 range retrievals on values that have been obtained from HTTP/1.0 463 servers. 465 5. Rules for When to Use Entity Tags and Last-Modified Dates 467 We adopt a set of rules and recommendations for origin servers, 468 clients, and caches regarding when various validator types ought to 469 be used, and for what purposes. 471 HTTP/1.1 origin servers: 473 o SHOULD send an entity tag validator unless it is not feasible to 474 generate one. 476 o MAY send a weak entity tag instead of a strong entity tag, if 477 performance considerations support the use of weak entity tags, or 478 if it is unfeasible to send a strong entity tag. 480 o SHOULD send a Last-Modified value if it is feasible to send one, 481 unless the risk of a breakdown in semantic transparency that could 482 result from using this date in an If-Modified-Since header would 483 lead to serious problems. 485 In other words, the preferred behavior for an HTTP/1.1 origin server 486 is to send both a strong entity tag and a Last-Modified value. 488 In order to be legal, a strong entity tag MUST change whenever the 489 associated entity changes in any way. A weak entity tag SHOULD 490 change whenever the associated entity changes in a semantically 491 significant way. 493 Note: In order to provide semantically transparent caching, an 494 origin server must avoid reusing a specific strong entity tag 495 value for two different entities, or reusing a specific weak 496 entity tag value for two semantically different entities. Cache 497 entries might persist for arbitrarily long periods, regardless of 498 expiration times, so it might be inappropriate to expect that a 499 cache will never again attempt to validate an entry using a 500 validator that it obtained at some point in the past. 502 HTTP/1.1 clients: 504 o MUST use that entity tag in any cache-conditional request (using 505 If-Match or If-None-Match) if an entity tag has been provided by 506 the origin server. 508 o SHOULD use the Last-Modified value in non-subrange cache- 509 conditional requests (using If-Modified-Since) if only a Last- 510 Modified value has been provided by the origin server. 512 o MAY use the Last-Modified value in subrange cache-conditional 513 requests (using If-Unmodified-Since) if only a Last-Modified value 514 has been provided by an HTTP/1.0 origin server. The user agent 515 SHOULD provide a way to disable this, in case of difficulty. 517 o SHOULD use both validators in cache-conditional requests if both 518 an entity tag and a Last-Modified value have been provided by the 519 origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to 520 respond appropriately. 522 An HTTP/1.1 origin server, upon receiving a conditional request that 523 includes both a Last-Modified date (e.g., in an If-Modified-Since or 524 If-Unmodified-Since header field) and one or more entity tags (e.g., 525 in an If-Match, If-None-Match, or If-Range header field) as cache 526 validators, MUST NOT return a response status of 304 (Not Modified) 527 unless doing so is consistent with all of the conditional header 528 fields in the request. 530 An HTTP/1.1 caching proxy, upon receiving a conditional request that 531 includes both a Last-Modified date and one or more entity tags as 532 cache validators, MUST NOT return a locally cached response to the 533 client unless that cached response is consistent with all of the 534 conditional header fields in the request. 536 Note: The general principle behind these rules is that HTTP/1.1 537 servers and clients should transmit as much non-redundant 538 information as is available in their responses and requests. 539 HTTP/1.1 systems receiving this information will make the most 540 conservative assumptions about the validators they receive. 542 HTTP/1.0 clients and caches will ignore entity tags. Generally, 543 last-modified values received or used by these systems will 544 support transparent and efficient caching, and so HTTP/1.1 origin 545 servers should provide Last-Modified values. In those rare cases 546 where the use of a Last-Modified value as a validator by an 547 HTTP/1.0 system could result in a serious problem, then HTTP/1.1 548 origin servers should not provide one. 550 6. Header Field Definitions 552 This section defines the syntax and semantics of HTTP/1.1 header 553 fields related to conditional requests. 555 For entity-header fields, both sender and recipient refer to either 556 the client or the server, depending on who sends and who receives the 557 entity. 559 6.1. ETag 561 The "ETag" response-header field provides the current value of the 562 entity tag (see Section 2) for the requested variant, which may be 563 used for comparison with other entities from the same resource (see 564 Section 4). 566 ETag = "ETag" ":" OWS ETag-v 567 ETag-v = entity-tag 569 Examples: 571 ETag: "xyzzy" 572 ETag: W/"xyzzy" 573 ETag: "" 575 The ETag response-header field value, an entity tag, provides for an 576 "opaque" cache validator. This might allow more reliable validation 577 in situations where it is inconvenient to store modification dates, 578 where the one-second resolution of HTTP date values is not 579 sufficient, or where the origin server wishes to avoid certain 580 paradoxes that might arise from the use of modification dates. 582 The principle behind entity tags is that only the service author 583 knows the semantics of a resource well enough to select an 584 appropriate cache validation mechanism, and the specification of any 585 validator comparison function more complex than byte-equality would 586 open up a can of worms. Thus, comparisons of any other headers 587 (except Last-Modified, for compatibility with HTTP/1.0) are never 588 used for purposes of validating a cache entry. 590 6.2. If-Match 592 The "If-Match" request-header field is used to make a request method 593 conditional. A client that has one or more entities previously 594 obtained from the resource can verify that one of those entities is 595 current by including a list of their associated entity tags in the 596 If-Match header field. 598 This allows efficient updates of cached information with a minimum 599 amount of transaction overhead. It is also used when updating 600 resources, to prevent inadvertent modification of the wrong version 601 of a resource. As a special case, the value "*" matches any current 602 entity of the resource. 604 If-Match = "If-Match" ":" OWS If-Match-v 605 If-Match-v = "*" / 1#entity-tag 607 If any of the entity tags match the entity tag of the entity that 608 would have been returned in the response to a similar GET request 609 (without the If-Match header) on that resource, or if "*" is given 610 and any current entity exists for that resource, then the server MAY 611 perform the requested method as if the If-Match header field did not 612 exist. 614 If none of the entity tags match, or if "*" is given and no current 615 entity exists, the server MUST NOT perform the requested method, and 616 MUST return a 412 (Precondition Failed) response. This behavior is 617 most useful when the client wants to prevent an updating method, such 618 as PUT, from modifying a resource that has changed since the client 619 last retrieved it. 621 If the request would, without the If-Match header field, result in 622 anything other than a 2xx or 412 status, then the If-Match header 623 MUST be ignored. 625 The meaning of "If-Match: *" is that the method SHOULD be performed 626 if the representation selected by the origin server (or by a cache, 627 possibly using the Vary mechanism, see Section 3.5 of [Part6]) 628 exists, and MUST NOT be performed if the representation does not 629 exist. 631 A request intended to update a resource (e.g., a PUT) MAY include an 632 If-Match header field to signal that the request method MUST NOT be 633 applied if the entity corresponding to the If-Match value (a single 634 entity tag) is no longer a representation of that resource. This 635 allows the user to indicate that they do not wish the request to be 636 successful if the resource has been changed without their knowledge. 637 Examples: 639 If-Match: "xyzzy" 640 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 641 If-Match: * 643 The result of a request having both an If-Match header field and 644 either an If-None-Match or an If-Modified-Since header fields is 645 undefined by this specification. 647 6.3. If-Modified-Since 649 The "If-Modified-Since" request-header field is used to make a 650 request method conditional: if the requested variant has not been 651 modified since the time specified in this field, the server will not 652 return an entity; instead, a 304 (Not Modified) response will be 653 returned. 655 If-Modified-Since = "If-Modified-Since" ":" OWS 656 If-Modified-Since-v 657 If-Modified-Since-v = HTTP-date 659 An example of the field is: 661 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 663 A GET method with an If-Modified-Since header and no Range header 664 requests that the identified entity be transferred only if it has 665 been modified since the date given by the If-Modified-Since header. 666 The algorithm for determining this includes the following cases: 668 1. If the request would normally result in anything other than a 200 669 (OK) status, or if the passed If-Modified-Since date is invalid, 670 the response is exactly the same as for a normal GET. A date 671 which is later than the server's current time is invalid. 673 2. If the variant has been modified since the If-Modified-Since 674 date, the response is exactly the same as for a normal GET. 676 3. If the variant has not been modified since a valid If-Modified- 677 Since date, the server SHOULD return a 304 (Not Modified) 678 response. 680 The purpose of this feature is to allow efficient updates of cached 681 information with a minimum amount of transaction overhead. 683 Note: The Range request-header field modifies the meaning of If- 684 Modified-Since; see Section 5.4 of [Part5] for full details. 686 Note: If-Modified-Since times are interpreted by the server, whose 687 clock might not be synchronized with the client. 689 Note: When handling an If-Modified-Since header field, some 690 servers will use an exact date comparison function, rather than a 691 less-than function, for deciding whether to send a 304 (Not 692 Modified) response. To get best results when sending an If- 693 Modified-Since header field for cache validation, clients are 694 advised to use the exact date string received in a previous Last- 695 Modified header field whenever possible. 697 Note: If a client uses an arbitrary date in the If-Modified-Since 698 header instead of a date taken from the Last-Modified header for 699 the same request, the client should be aware of the fact that this 700 date is interpreted in the server's understanding of time. The 701 client should consider unsynchronized clocks and rounding problems 702 due to the different encodings of time between the client and 703 server. This includes the possibility of race conditions if the 704 document has changed between the time it was first requested and 705 the If-Modified-Since date of a subsequent request, and the 706 possibility of clock-skew-related problems if the If-Modified- 707 Since date is derived from the client's clock without correction 708 to the server's clock. Corrections for different time bases 709 between client and server are at best approximate due to network 710 latency. 712 The result of a request having both an If-Modified-Since header field 713 and either an If-Match or an If-Unmodified-Since header fields is 714 undefined by this specification. 716 6.4. If-None-Match 718 The "If-None-Match" request-header field is used to make a request 719 method conditional. A client that has one or more entities 720 previously obtained from the resource can verify that none of those 721 entities is current by including a list of their associated entity 722 tags in the If-None-Match header field. 724 This allows efficient updates of cached information with a minimum 725 amount of transaction overhead. It is also used to prevent a method 726 (e.g., PUT) from inadvertently modifying an existing resource when 727 the client believes that the resource does not exist. 729 As a special case, the value "*" matches any current entity of the 730 resource. 732 If-None-Match = "If-None-Match" ":" OWS If-None-Match-v 733 If-None-Match-v = "*" / 1#entity-tag 735 If any of the entity tags match the entity tag of the entity that 736 would have been returned in the response to a similar GET request 737 (without the If-None-Match header) on that resource, or if "*" is 738 given and any current entity exists for that resource, then the 739 server MUST NOT perform the requested method, unless required to do 740 so because the resource's modification date fails to match that 741 supplied in an If-Modified-Since header field in the request. 742 Instead, if the request method was GET or HEAD, the server SHOULD 743 respond with a 304 (Not Modified) response, including the cache- 744 related header fields (particularly ETag) of one of the entities that 745 matched. For all other request methods, the server MUST respond with 746 a status of 412 (Precondition Failed). 748 If none of the entity tags match, then the server MAY perform the 749 requested method as if the If-None-Match header field did not exist, 750 but MUST also ignore any If-Modified-Since header field(s) in the 751 request. That is, if no entity tags match, then the server MUST NOT 752 return a 304 (Not Modified) response. 754 If the request would, without the If-None-Match header field, result 755 in anything other than a 2xx or 304 status, then the If-None-Match 756 header MUST be ignored. (See Section 5 for a discussion of server 757 behavior when both If-Modified-Since and If-None-Match appear in the 758 same request.) 760 The meaning of "If-None-Match: *" is that the method MUST NOT be 761 performed if the representation selected by the origin server (or by 762 a cache, possibly using the Vary mechanism, see Section 3.5 of 763 [Part6]) exists, and SHOULD be performed if the representation does 764 not exist. This feature is intended to be useful in preventing races 765 between PUT operations. 767 Examples: 769 If-None-Match: "xyzzy" 770 If-None-Match: W/"xyzzy" 771 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 772 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 773 If-None-Match: * 775 The result of a request having both an If-None-Match header field and 776 either an If-Match or an If-Unmodified-Since header fields is 777 undefined by this specification. 779 6.5. If-Unmodified-Since 781 The "If-Unmodified-Since" request-header field is used to make a 782 request method conditional. If the requested resource has not been 783 modified since the time specified in this field, the server SHOULD 784 perform the requested operation as if the If-Unmodified-Since header 785 were not present. 787 If the requested variant has been modified since the specified time, 788 the server MUST NOT perform the requested operation, and MUST return 789 a 412 (Precondition Failed). 791 If-Unmodified-Since = "If-Unmodified-Since" ":" OWS 792 If-Unmodified-Since-v 793 If-Unmodified-Since-v = HTTP-date 795 An example of the field is: 797 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 799 If the request normally (i.e., without the If-Unmodified-Since 800 header) would result in anything other than a 2xx or 412 status, the 801 If-Unmodified-Since header SHOULD be ignored. 803 If the specified date is invalid, the header is ignored. 805 The result of a request having both an If-Unmodified-Since header 806 field and either an If-None-Match or an If-Modified-Since header 807 fields is undefined by this specification. 809 6.6. Last-Modified 811 The "Last-Modified" entity-header field indicates the date and time 812 at which the origin server believes the variant was last modified. 814 Last-Modified = "Last-Modified" ":" OWS Last-Modified-v 815 Last-Modified-v = HTTP-date 817 An example of its use is 819 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 821 The exact meaning of this header field depends on the implementation 822 of the origin server and the nature of the original resource. For 823 files, it may be just the file system last-modified time. For 824 entities with dynamically included parts, it may be the most recent 825 of the set of last-modify times for its component parts. For 826 database gateways, it may be the last-update time stamp of the 827 record. For virtual objects, it may be the last time the internal 828 state changed. 830 An origin server MUST NOT send a Last-Modified date which is later 831 than the server's time of message origination. In such cases, where 832 the resource's last modification would indicate some time in the 833 future, the server MUST replace that date with the message 834 origination date. 836 An origin server SHOULD obtain the Last-Modified value of the entity 837 as close as possible to the time that it generates the Date value of 838 its response. This allows a recipient to make an accurate assessment 839 of the entity's modification time, especially if the entity changes 840 near the time that the response is generated. 842 HTTP/1.1 servers SHOULD send Last-Modified whenever feasible. 844 The Last-Modified entity-header field value is often used as a cache 845 validator. In simple terms, a cache entry is considered to be valid 846 if the entity has not been modified since the Last-Modified value. 848 7. IANA Considerations 850 7.1. Status Code Registration 852 The HTTP Status Code Registry located at 853 should be updated 854 with the registrations below: 856 +-------+---------------------+-------------+ 857 | Value | Description | Reference | 858 +-------+---------------------+-------------+ 859 | 304 | Not Modified | Section 3.1 | 860 | 412 | Precondition Failed | Section 3.2 | 861 +-------+---------------------+-------------+ 863 7.2. Message Header Registration 865 The Message Header Registry located at should be 867 updated with the permanent registrations below (see [RFC3864]): 869 +---------------------+----------+----------+-------------+ 870 | Header Field Name | Protocol | Status | Reference | 871 +---------------------+----------+----------+-------------+ 872 | ETag | http | standard | Section 6.1 | 873 | If-Match | http | standard | Section 6.2 | 874 | If-Modified-Since | http | standard | Section 6.3 | 875 | If-None-Match | http | standard | Section 6.4 | 876 | If-Unmodified-Since | http | standard | Section 6.5 | 877 | Last-Modified | http | standard | Section 6.6 | 878 +---------------------+----------+----------+-------------+ 880 The change controller is: "IETF (iesg@ietf.org) - Internet 881 Engineering Task Force". 883 8. Security Considerations 885 No additional security considerations have been identified beyond 886 those applicable to HTTP in general [Part1]. 888 9. Acknowledgments 890 10. References 892 10.1. Normative References 894 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 895 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 896 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 897 and Message Parsing", draft-ietf-httpbis-p1-messaging-10 898 (work in progress), July 2010. 900 [Part3] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 901 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 902 and J. Reschke, Ed., "HTTP/1.1, part 3: Message Payload 903 and Content Negotiation", draft-ietf-httpbis-p3-payload-10 904 (work in progress), July 2010. 906 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 907 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 908 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 909 Partial Responses", draft-ietf-httpbis-p5-range-10 (work 910 in progress), July 2010. 912 [Part6] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 913 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 914 Nottingham, M., Ed., and J. Reschke, Ed., "HTTP/1.1, part 915 6: Caching", draft-ietf-httpbis-p6-cache-10 (work in 916 progress), July 2010. 918 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 919 Requirement Levels", BCP 14, RFC 2119, March 1997. 921 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 922 Specifications: ABNF", STD 68, RFC 5234, January 2008. 924 10.2. Informative References 926 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 927 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 928 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 930 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 931 Procedures for Message Header Fields", BCP 90, RFC 3864, 932 September 2004. 934 Appendix A. Compatibility with Previous Versions 936 A.1. Changes from RFC 2616 938 Allow weak entity tags in all requests except range requests 939 (Sections 4 and 6.4). 941 Appendix B. Collected ABNF 943 ETag = "ETag:" OWS ETag-v 944 ETag-v = entity-tag 946 HTTP-date = 948 If-Match = "If-Match:" OWS If-Match-v 949 If-Match-v = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS 950 entity-tag ] ) ) 951 If-Modified-Since = "If-Modified-Since:" OWS If-Modified-Since-v 952 If-Modified-Since-v = HTTP-date 953 If-None-Match = "If-None-Match:" OWS If-None-Match-v 954 If-None-Match-v = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS 955 entity-tag ] ) ) 956 If-Unmodified-Since = "If-Unmodified-Since:" OWS 957 If-Unmodified-Since-v 958 If-Unmodified-Since-v = HTTP-date 960 Last-Modified = "Last-Modified:" OWS Last-Modified-v 961 Last-Modified-v = HTTP-date 963 OWS = 965 entity-tag = [ weak ] opaque-tag 967 opaque-tag = quoted-string 969 quoted-string = 971 weak = %x57.2F ; W/ 973 ABNF diagnostics: 975 ; ETag defined but not used 976 ; If-Match defined but not used 977 ; If-Modified-Since defined but not used 978 ; If-None-Match defined but not used 979 ; If-Unmodified-Since defined but not used 980 ; Last-Modified defined but not used 982 Appendix C. Change Log (to be removed by RFC Editor before publication) 984 C.1. Since RFC2616 986 Extracted relevant partitions from [RFC2616]. 988 C.2. Since draft-ietf-httpbis-p4-conditional-00 990 Closed issues: 992 o : "Normative and 993 Informative references" 995 Other changes: 997 o Move definitions of 304 and 412 condition codes from Part2. 999 C.3. Since draft-ietf-httpbis-p4-conditional-01 1001 Ongoing work on ABNF conversion 1002 (): 1004 o Add explicit references to BNF syntax and rules imported from 1005 other parts of the specification. 1007 C.4. Since draft-ietf-httpbis-p4-conditional-02 1009 Closed issues: 1011 o : "Weak ETags on 1012 non-GET requests" 1014 Ongoing work on IANA Message Header Registration 1015 (): 1017 o Reference RFC 3984, and update header registrations for headers 1018 defined in this document. 1020 C.5. Since draft-ietf-httpbis-p4-conditional-03 1022 Closed issues: 1024 o : "Examples for 1025 ETag matching" 1027 o : "'entity 1028 value' undefined" 1030 o : "bogus 2068 1031 Date header reference" 1033 C.6. Since draft-ietf-httpbis-p4-conditional-04 1035 Ongoing work on ABNF conversion 1036 (): 1038 o Use "/" instead of "|" for alternatives. 1040 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1041 whitespace ("OWS") and required whitespace ("RWS"). 1043 o Rewrite ABNFs to spell out whitespace rules, factor out header 1044 value format definitions. 1046 C.7. Since draft-ietf-httpbis-p4-conditional-05 1048 Final work on ABNF conversion 1049 (): 1051 o Add appendix containing collected and expanded ABNF, reorganize 1052 ABNF introduction. 1054 C.8. Since draft-ietf-httpbis-p4-conditional-06 1056 Closed issues: 1058 o : "case- 1059 sensitivity of etag weakness indicator" 1061 C.9. Since draft-ietf-httpbis-p4-conditional-07 1063 Closed issues: 1065 o : "Weak ETags on 1066 non-GET requests" (If-Match still was defined to require strong 1067 matching) 1069 o : "move IANA 1070 registrations for optional status codes" 1072 C.10. Since draft-ietf-httpbis-p4-conditional-08 1074 No significant changes. 1076 C.11. Since draft-ietf-httpbis-p4-conditional-09 1078 No significant changes. 1080 Index 1082 3 1083 304 Not Modified (status code) 7 1085 4 1086 412 Precondition Failed (status code) 8 1088 E 1089 ETag header 13 1091 G 1092 Grammar 1093 entity-tag 5 1094 ETag 13 1095 ETag-v 13 1096 If-Match 13 1097 If-Match-v 13 1098 If-Modified-Since 15 1099 If-Modified-Since-v 15 1100 If-None-Match 16 1101 If-None-Match-v 16 1102 If-Unmodified-Since 17 1103 If-Unmodified-Since-v 17 1104 Last-Modified 18 1105 Last-Modified-v 18 1106 opaque-tag 5 1107 weak 5 1109 H 1110 Headers 1111 ETag 13 1112 If-Match 13 1113 If-Modified-Since 14 1114 If-None-Match 16 1115 If-Unmodified-Since 17 1116 Last-Modified 18 1118 I 1119 If-Match header 13 1120 If-Modified-Since header 14 1121 If-None-Match header 16 1122 If-Unmodified-Since header 17 1124 L 1125 Last-Modified header 18 1127 S 1128 Status Codes 1129 304 Not Modified 7 1130 412 Precondition Failed 8 1132 Authors' Addresses 1134 Roy T. Fielding (editor) 1135 Day Software 1136 23 Corporate Plaza DR, Suite 280 1137 Newport Beach, CA 92660 1138 USA 1140 Phone: +1-949-706-5300 1141 Fax: +1-949-706-5305 1142 EMail: fielding@gbiv.com 1143 URI: http://roy.gbiv.com/ 1145 Jim Gettys 1146 Alcatel-Lucent Bell Labs 1147 21 Oak Knoll Road 1148 Carlisle, MA 01741 1149 USA 1151 EMail: jg@freedesktop.org 1152 URI: http://gettys.wordpress.com/ 1154 Jeffrey C. Mogul 1155 Hewlett-Packard Company 1156 HP Labs, Large Scale Systems Group 1157 1501 Page Mill Road, MS 1177 1158 Palo Alto, CA 94304 1159 USA 1161 EMail: JeffMogul@acm.org 1163 Henrik Frystyk Nielsen 1164 Microsoft Corporation 1165 1 Microsoft Way 1166 Redmond, WA 98052 1167 USA 1169 EMail: henrikn@microsoft.com 1170 Larry Masinter 1171 Adobe Systems, Incorporated 1172 345 Park Ave 1173 San Jose, CA 95110 1174 USA 1176 EMail: LMM@acm.org 1177 URI: http://larry.masinter.net/ 1179 Paul J. Leach 1180 Microsoft Corporation 1181 1 Microsoft Way 1182 Redmond, WA 98052 1184 EMail: paulle@microsoft.com 1186 Tim Berners-Lee 1187 World Wide Web Consortium 1188 MIT Computer Science and Artificial Intelligence Laboratory 1189 The Stata Center, Building 32 1190 32 Vassar Street 1191 Cambridge, MA 02139 1192 USA 1194 EMail: timbl@w3.org 1195 URI: http://www.w3.org/People/Berners-Lee/ 1197 Yves Lafon (editor) 1198 World Wide Web Consortium 1199 W3C / ERCIM 1200 2004, rte des Lucioles 1201 Sophia-Antipolis, AM 06902 1202 France 1204 EMail: ylafon@w3.org 1205 URI: http://www.raubacapeu.net/people/yves/ 1206 Julian F. Reschke (editor) 1207 greenbytes GmbH 1208 Hafenweg 16 1209 Muenster, NW 48155 1210 Germany 1212 Phone: +49 251 2807760 1213 Fax: +49 251 2807761 1214 EMail: julian.reschke@greenbytes.de 1215 URI: http://greenbytes.de/tech/webdav/