1 | |
2 | |
3 | |
4 | |
5 | |
6 | |
7 | Internet Engineering Task Force (IETF) R. Fielding, Ed. |
8 | Request for Comments: 7232 Adobe |
9 | Obsoletes: 2616 J. Reschke, Ed. |
10 | Category: Standards Track greenbytes |
11 | ISSN: 2070-1721 June 2014 |
12 | |
13 | |
14 | Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests |
15 | |
16 | Abstract |
17 | |
18 | The Hypertext Transfer Protocol (HTTP) is a stateless application- |
19 | level protocol for distributed, collaborative, hypertext information |
20 | systems. This document defines HTTP/1.1 conditional requests, |
21 | including metadata header fields for indicating state changes, |
22 | request header fields for making preconditions on such state, and |
23 | rules for constructing the responses to a conditional request when |
24 | one or more preconditions evaluate to false. |
25 | |
26 | Status of This Memo |
27 | |
28 | This is an Internet Standards Track document. |
29 | |
30 | This document is a product of the Internet Engineering Task Force |
31 | (IETF). It represents the consensus of the IETF community. It has |
32 | received public review and has been approved for publication by the |
33 | Internet Engineering Steering Group (IESG). Further information on |
34 | Internet Standards is available in Section 2 of RFC 5741. |
35 | |
36 | Information about the current status of this document, any errata, |
37 | and how to provide feedback on it may be obtained at |
38 | http://www.rfc-editor.org/info/rfc7232. |
39 | |
40 | |
41 | |
42 | |
43 | |
44 | |
45 | |
46 | |
47 | |
48 | |
49 | |
50 | |
51 | |
52 | |
53 | |
54 | |
55 | |
56 | |
57 | |
58 | Fielding & Reschke Standards Track [Page 1] |
60 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
61 | |
62 | |
63 | Copyright Notice |
64 | |
65 | Copyright (c) 2014 IETF Trust and the persons identified as the |
66 | document authors. All rights reserved. |
67 | |
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. |
77 | |
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. |
89 | |
90 | |
91 | |
92 | |
93 | |
94 | |
95 | |
96 | |
97 | |
98 | |
99 | |
100 | |
101 | |
102 | |
103 | |
104 | |
105 | |
106 | |
107 | |
108 | |
109 | |
110 | |
111 | |
112 | |
113 | |
114 | Fielding & Reschke Standards Track [Page 2] |
116 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
117 | |
118 | |
119 | Table of Contents |
120 | |
121 | 1. Introduction ....................................................4 |
122 | 1.1. Conformance and Error Handling .............................4 |
123 | 1.2. Syntax Notation ............................................4 |
124 | 2. Validators ......................................................5 |
125 | 2.1. Weak versus Strong .........................................5 |
126 | 2.2. Last-Modified ..............................................7 |
127 | 2.2.1. Generation ..........................................7 |
128 | 2.2.2. Comparison ..........................................8 |
129 | 2.3. ETag .......................................................9 |
130 | 2.3.1. Generation .........................................10 |
131 | 2.3.2. Comparison .........................................10 |
132 | 2.3.3. Example: Entity-Tags Varying on |
133 | Content-Negotiated Resources .......................11 |
134 | 2.4. When to Use Entity-Tags and Last-Modified Dates ...........12 |
135 | 3. Precondition Header Fields .....................................13 |
136 | 3.1. If-Match ..................................................13 |
137 | 3.2. If-None-Match .............................................14 |
138 | 3.3. If-Modified-Since .........................................16 |
139 | 3.4. If-Unmodified-Since .......................................17 |
140 | 3.5. If-Range ..................................................18 |
141 | 4. Status Code Definitions ........................................18 |
142 | 4.1. 304 Not Modified ..........................................18 |
143 | 4.2. 412 Precondition Failed ...................................19 |
144 | 5. Evaluation .....................................................19 |
145 | 6. Precedence .....................................................20 |
146 | 7. IANA Considerations ............................................22 |
147 | 7.1. Status Code Registration ..................................22 |
148 | 7.2. Header Field Registration .................................22 |
149 | 8. Security Considerations ........................................22 |
150 | 9. Acknowledgments ................................................23 |
151 | 10. References ....................................................24 |
152 | 10.1. Normative References .....................................24 |
153 | 10.2. Informative References ...................................24 |
154 | Appendix A. Changes from RFC 2616 .................................25 |
155 | Appendix B. Imported ABNF .........................................25 |
156 | Appendix C. Collected ABNF ........................................26 |
157 | Index .............................................................27 |
158 | |
159 | |
160 | |
161 | |
162 | |
163 | |
164 | |
165 | |
166 | |
167 | |
168 | |
169 | |
170 | Fielding & Reschke Standards Track [Page 3] |
172 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
173 | |
174 | |
175 | 1. Introduction |
176 | |
177 | Conditional requests are HTTP requests [RFC7231] that include one or |
178 | more header fields indicating a precondition to be tested before |
179 | applying the method semantics to the target resource. This document |
180 | defines the HTTP/1.1 conditional request mechanisms in terms of the |
181 | architecture, syntax notation, and conformance criteria defined in |
182 | [RFC7230]. |
183 | |
184 | Conditional GET requests are the most efficient mechanism for HTTP |
185 | cache updates [RFC7234]. Conditionals can also be applied to |
186 | state-changing methods, such as PUT and DELETE, to prevent the "lost |
187 | update" problem: one client accidentally overwriting the work of |
188 | another client that has been acting in parallel. |
189 | |
190 | Conditional request preconditions are based on the state of the |
191 | target resource as a whole (its current value set) or the state as |
192 | observed in a previously obtained representation (one value in that |
193 | set). A resource might have multiple current representations, each |
194 | with its own observable state. The conditional request mechanisms |
195 | assume that the mapping of requests to a "selected representation" |
196 | (Section 3 of [RFC7231]) will be consistent over time if the server |
197 | intends to take advantage of conditionals. Regardless, if the |
198 | mapping is inconsistent and the server is unable to select the |
199 | appropriate representation, then no harm will result when the |
200 | precondition evaluates to false. |
201 | |
202 | The conditional request preconditions defined by this specification |
203 | (Section 3) are evaluated when applicable to the recipient |
204 | (Section 5) according to their order of precedence (Section 6). |
205 | |
206 | 1.1. Conformance and Error Handling |
207 | |
208 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", |
209 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this |
210 | document are to be interpreted as described in [RFC2119]. |
211 | |
212 | Conformance criteria and considerations regarding error handling are |
213 | defined in Section 2.5 of [RFC7230]. |
214 | |
215 | 1.2. Syntax Notation |
216 | |
217 | This specification uses the Augmented Backus-Naur Form (ABNF) |
218 | notation of [RFC5234] with a list extension, defined in Section 7 of |
219 | [RFC7230], that allows for compact definition of comma-separated |
220 | lists using a '#' operator (similar to how the '*' operator indicates |
221 | |
222 | |
223 | |
224 | |
225 | |
226 | Fielding & Reschke Standards Track [Page 4] |
228 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
229 | |
230 | |
231 | repetition). Appendix B describes rules imported from other |
232 | documents. Appendix C shows the collected grammar with all list |
233 | operators expanded to standard ABNF notation. |
234 | |
235 | 2. Validators |
236 | |
237 | This specification defines two forms of metadata that are commonly |
238 | used to observe resource state and test for preconditions: |
239 | modification dates (Section 2.2) and opaque entity tags |
240 | (Section 2.3). Additional metadata that reflects resource state has |
241 | been defined by various extensions of HTTP, such as Web Distributed |
242 | Authoring and Versioning (WebDAV, [RFC4918]), that are beyond the |
243 | scope of this specification. A resource metadata value is referred |
244 | to as a "validator" when it is used within a precondition. |
245 | |
246 | 2.1. Weak versus Strong |
247 | |
248 | Validators come in two flavors: strong or weak. Weak validators are |
249 | easy to generate but are far less useful for comparisons. Strong |
250 | validators are ideal for comparisons but can be very difficult (and |
251 | occasionally impossible) to generate efficiently. Rather than impose |
252 | that all forms of resource adhere to the same strength of validator, |
253 | HTTP exposes the type of validator in use and imposes restrictions on |
254 | when weak validators can be used as preconditions. |
255 | |
256 | A "strong validator" is representation metadata that changes value |
257 | whenever a change occurs to the representation data that would be |
258 | observable in the payload body of a 200 (OK) response to GET. |
259 | |
260 | A strong validator might change for reasons other than a change to |
261 | the representation data, such as when a semantically significant part |
262 | of the representation metadata is changed (e.g., Content-Type), but |
263 | it is in the best interests of the origin server to only change the |
264 | value when it is necessary to invalidate the stored responses held by |
265 | remote caches and authoring tools. |
266 | |
267 | Cache entries might persist for arbitrarily long periods, regardless |
268 | of expiration times. Thus, a cache might attempt to validate an |
269 | entry using a validator that it obtained in the distant past. A |
270 | strong validator is unique across all versions of all representations |
271 | associated with a particular resource over time. However, there is |
272 | no implication of uniqueness across representations of different |
273 | resources (i.e., the same strong validator might be in use for |
274 | representations of multiple resources at the same time and does not |
275 | imply that those representations are equivalent). |
276 | |
277 | |
278 | |
279 | |
280 | |
281 | |
282 | Fielding & Reschke Standards Track [Page 5] |
284 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
285 | |
286 | |
287 | There are a variety of strong validators used in practice. The best |
288 | are based on strict revision control, wherein each change to a |
289 | representation always results in a unique node name and revision |
290 | identifier being assigned before the representation is made |
291 | accessible to GET. A collision-resistant hash function applied to |
292 | the representation data is also sufficient if the data is available |
293 | prior to the response header fields being sent and the digest does |
294 | not need to be recalculated every time a validation request is |
295 | received. However, if a resource has distinct representations that |
296 | differ only in their metadata, such as might occur with content |
297 | negotiation over media types that happen to share the same data |
298 | format, then the origin server needs to incorporate additional |
299 | information in the validator to distinguish those representations. |
300 | |
301 | In contrast, a "weak validator" is representation metadata that might |
302 | not change for every change to the representation data. This |
303 | weakness might be due to limitations in how the value is calculated, |
304 | such as clock resolution, an inability to ensure uniqueness for all |
305 | possible representations of the resource, or a desire of the resource |
306 | owner to group representations by some self-determined set of |
307 | equivalency rather than unique sequences of data. An origin server |
308 | SHOULD change a weak entity-tag whenever it considers prior |
309 | representations to be unacceptable as a substitute for the current |
310 | representation. In other words, a weak entity-tag ought to change |
311 | whenever the origin server wants caches to invalidate old responses. |
312 | |
313 | For example, the representation of a weather report that changes in |
314 | content every second, based on dynamic measurements, might be grouped |
315 | into sets of equivalent representations (from the origin server's |
316 | perspective) with the same weak validator in order to allow cached |
317 | representations to be valid for a reasonable period of time (perhaps |
318 | adjusted dynamically based on server load or weather quality). |
319 | Likewise, a representation's modification time, if defined with only |
320 | one-second resolution, might be a weak validator if it is possible |
321 | for the representation to be modified twice during a single second |
322 | and retrieved between those modifications. |
323 | |
324 | Likewise, a validator is weak if it is shared by two or more |
325 | representations of a given resource at the same time, unless those |
326 | representations have identical representation data. For example, if |
327 | the origin server sends the same validator for a representation with |
328 | a gzip content coding applied as it does for a representation with no |
329 | content coding, then that validator is weak. However, two |
330 | simultaneous representations might share the same strong validator if |
331 | they differ only in the representation metadata, such as when two |
332 | different media types are available for the same representation data. |
333 | |
334 | |
335 | |
336 | |
337 | |
338 | Fielding & Reschke Standards Track [Page 6] |
340 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
341 | |
342 | |
343 | Strong validators are usable for all conditional requests, including |
344 | cache validation, partial content ranges, and "lost update" |
345 | avoidance. Weak validators are only usable when the client does not |
346 | require exact equality with previously obtained representation data, |
347 | such as when validating a cache entry or limiting a web traversal to |
348 | recent changes. |
349 | |
350 | 2.2. Last-Modified |
351 | |
352 | The "Last-Modified" header field in a response provides a timestamp |
353 | indicating the date and time at which the origin server believes the |
354 | selected representation was last modified, as determined at the |
355 | conclusion of handling the request. |
356 | |
357 | Last-Modified = HTTP-date |
358 | |
359 | An example of its use is |
360 | |
361 | Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT |
362 | |
363 | 2.2.1. Generation |
364 | |
365 | An origin server SHOULD send Last-Modified for any selected |
366 | representation for which a last modification date can be reasonably |
367 | and consistently determined, since its use in conditional requests |
368 | and evaluating cache freshness ([RFC7234]) results in a substantial |
369 | reduction of HTTP traffic on the Internet and can be a significant |
370 | factor in improving service scalability and reliability. |
371 | |
372 | A representation is typically the sum of many parts behind the |
373 | resource interface. The last-modified time would usually be the most |
374 | recent time that any of those parts were changed. How that value is |
375 | determined for any given resource is an implementation detail beyond |
376 | the scope of this specification. What matters to HTTP is how |
377 | recipients of the Last-Modified header field can use its value to |
378 | make conditional requests and test the validity of locally cached |
379 | responses. |
380 | |
381 | An origin server SHOULD obtain the Last-Modified value of the |
382 | representation as close as possible to the time that it generates the |
383 | Date field value for its response. This allows a recipient to make |
384 | an accurate assessment of the representation's modification time, |
385 | especially if the representation changes near the time that the |
386 | response is generated. |
387 | |
388 | An origin server with a clock MUST NOT send a Last-Modified date that |
389 | is later than the server's time of message origination (Date). If |
390 | the last modification time is derived from implementation-specific |
391 | |
392 | |
393 | |
394 | Fielding & Reschke Standards Track [Page 7] |
396 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
397 | |
398 | |
399 | metadata that evaluates to some time in the future, according to the |
400 | origin server's clock, then the origin server MUST replace that value |
401 | with the message origination date. This prevents a future |
402 | modification date from having an adverse impact on cache validation. |
403 | |
404 | An origin server without a clock MUST NOT assign Last-Modified values |
405 | to a response unless these values were associated with the resource |
406 | by some other system or user with a reliable clock. |
407 | |
408 | 2.2.2. Comparison |
409 | |
410 | A Last-Modified time, when used as a validator in a request, is |
411 | implicitly weak unless it is possible to deduce that it is strong, |
412 | using the following rules: |
413 | |
414 | o The validator is being compared by an origin server to the actual |
415 | current validator for the representation and, |
416 | |
417 | o That origin server reliably knows that the associated |
418 | representation did not change twice during the second covered by |
419 | the presented validator. |
420 | |
421 | or |
422 | |
423 | o The validator is about to be used by a client in an |
424 | If-Modified-Since, If-Unmodified-Since, or If-Range header field, |
425 | because the client has a cache entry for the associated |
426 | representation, and |
427 | |
428 | o That cache entry includes a Date value, which gives the time when |
429 | the origin server sent the original response, and |
430 | |
431 | o The presented Last-Modified time is at least 60 seconds before the |
432 | Date value. |
433 | |
434 | or |
435 | |
436 | o The validator is being compared by an intermediate cache to the |
437 | validator stored in its cache entry for the representation, and |
438 | |
439 | o That cache entry includes a Date value, which gives the time when |
.../cache/cache_range.c 173 |
440 | the origin server sent the original response, and |
441 | |
442 | o The presented Last-Modified time is at least 60 seconds before the |
.../cache/cache_range.c 190 |
443 | Date value. |
444 | |
445 | |
446 | |
447 | |
448 | |
449 | |
450 | Fielding & Reschke Standards Track [Page 8] |
452 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
453 | |
454 | |
455 | This method relies on the fact that if two different responses were |
456 | sent by the origin server during the same second, but both had the |
457 | same Last-Modified time, then at least one of those responses would |
458 | have a Date value equal to its Last-Modified time. The arbitrary |
459 | 60-second limit guards against the possibility that the Date and |
460 | Last-Modified values are generated from different clocks or at |
461 | somewhat different times during the preparation of the response. An |
462 | implementation MAY use a value larger than 60 seconds, if it is |
463 | believed that 60 seconds is too short. |
464 | |
465 | 2.3. ETag |
466 | |
467 | The "ETag" header field in a response provides the current entity-tag |
468 | for the selected representation, as determined at the conclusion of |
469 | handling the request. An entity-tag is an opaque validator for |
470 | differentiating between multiple representations of the same |
471 | resource, regardless of whether those multiple representations are |
472 | due to resource state changes over time, content negotiation |
473 | resulting in multiple representations being valid at the same time, |
474 | or both. An entity-tag consists of an opaque quoted string, possibly |
475 | prefixed by a weakness indicator. |
476 | |
477 | ETag = entity-tag |
478 | |
479 | entity-tag = [ weak ] opaque-tag |
480 | weak = %x57.2F ; "W/", case-sensitive |
481 | opaque-tag = DQUOTE *etagc DQUOTE |
482 | etagc = %x21 / %x23-7E / obs-text |
483 | ; VCHAR except double quotes, plus obs-text |
484 | |
485 | Note: Previously, opaque-tag was defined to be a quoted-string |
486 | ([RFC2616], Section 3.11); thus, some recipients might perform |
487 | backslash unescaping. Servers therefore ought to avoid backslash |
488 | characters in entity tags. |
489 | |
490 | An entity-tag can be more reliable for validation than a modification |
491 | date in situations where it is inconvenient to store modification |
492 | dates, where the one-second resolution of HTTP date values is not |
493 | sufficient, or where modification dates are not consistently |
494 | maintained. |
495 | |
496 | Examples: |
497 | |
498 | ETag: "xyzzy" |
499 | ETag: W/"xyzzy" |
500 | ETag: "" |
501 | |
502 | |
503 | |
504 | |
505 | |
506 | Fielding & Reschke Standards Track [Page 9] |
508 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
509 | |
510 | |
511 | An entity-tag can be either a weak or strong validator, with strong |
512 | being the default. If an origin server provides an entity-tag for a |
513 | representation and the generation of that entity-tag does not satisfy |
514 | all of the characteristics of a strong validator (Section 2.1), then |
515 | the origin server MUST mark the entity-tag as weak by prefixing its |
516 | opaque value with "W/" (case-sensitive). |
517 | |
518 | 2.3.1. Generation |
519 | |
520 | The principle behind entity-tags is that only the service author |
521 | knows the implementation of a resource well enough to select the most |
522 | accurate and efficient validation mechanism for that resource, and |
523 | that any such mechanism can be mapped to a simple sequence of octets |
524 | for easy comparison. Since the value is opaque, there is no need for |
525 | the client to be aware of how each entity-tag is constructed. |
526 | |
527 | For example, a resource that has implementation-specific versioning |
528 | applied to all changes might use an internal revision number, perhaps |
529 | combined with a variance identifier for content negotiation, to |
530 | accurately differentiate between representations. Other |
531 | implementations might use a collision-resistant hash of |
532 | representation content, a combination of various file attributes, or |
533 | a modification timestamp that has sub-second resolution. |
534 | |
535 | An origin server SHOULD send an ETag for any selected representation |
536 | for which detection of changes can be reasonably and consistently |
537 | determined, since the entity-tag's use in conditional requests and |
538 | evaluating cache freshness ([RFC7234]) can result in a substantial |
539 | reduction of HTTP network traffic and can be a significant factor in |
540 | improving service scalability and reliability. |
541 | |
542 | 2.3.2. Comparison |
543 | |
544 | There are two entity-tag comparison functions, depending on whether |
545 | or not the comparison context allows the use of weak validators: |
546 | |
547 | o Strong comparison: two entity-tags are equivalent if both are not |
.../cache/cache_range.c 161 |
548 | weak and their opaque-tags match character-by-character. |
.../cache/cache_rfc2616.c 261 |
549 | |
| |
.../cache/cache_range.c 164 |
550 | o Weak comparison: two entity-tags are equivalent if their |
.../cache/cache_rfc2616.c 272 |
551 | opaque-tags match character-by-character, regardless of either or |
552 | both being tagged as "weak". |
553 | |
554 | |
555 | |
556 | |
557 | |
558 | |
559 | |
560 | |
561 | |
562 | Fielding & Reschke Standards Track [Page 10] |
564 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
565 | |
566 | |
567 | The example below shows the results for a set of entity-tag pairs and |
568 | both the weak and strong comparison function results: |
569 | |
570 | +--------+--------+-------------------+-----------------+ |
571 | | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | |
572 | +--------+--------+-------------------+-----------------+ |
573 | | W/"1" | W/"1" | no match | match | |
574 | | W/"1" | W/"2" | no match | no match | |
575 | | W/"1" | "1" | no match | match | |
576 | | "1" | "1" | match | match | |
577 | +--------+--------+-------------------+-----------------+ |
578 | |
579 | 2.3.3. Example: Entity-Tags Varying on Content-Negotiated Resources |
580 | |
581 | Consider a resource that is subject to content negotiation (Section |
582 | 3.4 of [RFC7231]), and where the representations sent in response to |
583 | a GET request vary based on the Accept-Encoding request header field |
584 | (Section 5.3.4 of [RFC7231]): |
585 | |
586 | >> Request: |
587 | |
588 | GET /index HTTP/1.1 |
589 | Host: www.example.com |
590 | Accept-Encoding: gzip |
591 | |
592 | |
593 | In this case, the response might or might not use the gzip content |
594 | coding. If it does not, the response might look like: |
595 | |
596 | >> Response: |
597 | |
598 | HTTP/1.1 200 OK |
599 | Date: Fri, 26 Mar 2010 00:05:00 GMT |
600 | ETag: "123-a" |
601 | Content-Length: 70 |
602 | Vary: Accept-Encoding |
603 | Content-Type: text/plain |
604 | |
605 | Hello World! |
606 | Hello World! |
607 | Hello World! |
608 | Hello World! |
609 | Hello World! |
610 | |
611 | |
612 | |
613 | |
614 | |
615 | |
616 | |
617 | |
618 | Fielding & Reschke Standards Track [Page 11] |
620 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
621 | |
622 | |
623 | An alternative representation that does use gzip content coding would |
624 | be: |
625 | |
626 | >> Response: |
627 | |
628 | HTTP/1.1 200 OK |
629 | Date: Fri, 26 Mar 2010 00:05:00 GMT |
630 | ETag: "123-b" |
631 | Content-Length: 43 |
632 | Vary: Accept-Encoding |
633 | Content-Type: text/plain |
634 | Content-Encoding: gzip |
635 | |
636 | ...binary data... |
637 | |
638 | Note: Content codings are a property of the representation data, |
639 | so a strong entity-tag for a content-encoded representation has to |
640 | be distinct from the entity tag of an unencoded representation to |
641 | prevent potential conflicts during cache updates and range |
642 | requests. In contrast, transfer codings (Section 4 of [RFC7230]) |
643 | apply only during message transfer and do not result in distinct |
644 | entity-tags. |
645 | |
646 | 2.4. When to Use Entity-Tags and Last-Modified Dates |
647 | |
648 | In 200 (OK) responses to GET or HEAD, an origin server: |
649 | |
650 | o SHOULD send an entity-tag validator unless it is not feasible to |
651 | generate one. |
652 | |
653 | o MAY send a weak entity-tag instead of a strong entity-tag, if |
654 | performance considerations support the use of weak entity-tags, or |
655 | if it is unfeasible to send a strong entity-tag. |
656 | |
657 | o SHOULD send a Last-Modified value if it is feasible to send one. |
658 | |
659 | In other words, the preferred behavior for an origin server is to |
660 | send both a strong entity-tag and a Last-Modified value in successful |
661 | responses to a retrieval request. |
662 | |
663 | A client: |
664 | |
665 | o MUST send that entity-tag in any cache validation request (using |
666 | If-Match or If-None-Match) if an entity-tag has been provided by |
667 | the origin server. |
668 | |
669 | |
670 | |
671 | |
672 | |
673 | |
674 | Fielding & Reschke Standards Track [Page 12] |
676 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
677 | |
678 | |
679 | o SHOULD send the Last-Modified value in non-subrange cache |
680 | validation requests (using If-Modified-Since) if only a |
681 | Last-Modified value has been provided by the origin server. |
682 | |
683 | o MAY send the Last-Modified value in subrange cache validation |
684 | requests (using If-Unmodified-Since) if only a Last-Modified value |
685 | has been provided by an HTTP/1.0 origin server. The user agent |
686 | SHOULD provide a way to disable this, in case of difficulty. |
687 | |
688 | o SHOULD send both validators in cache validation requests if both |
689 | an entity-tag and a Last-Modified value have been provided by the |
690 | origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to |
691 | respond appropriately. |
692 | |
693 | 3. Precondition Header Fields |
694 | |
695 | This section defines the syntax and semantics of HTTP/1.1 header |
696 | fields for applying preconditions on requests. Section 5 defines |
697 | when the preconditions are applied. Section 6 defines the order of |
698 | evaluation when more than one precondition is present. |
699 | |
700 | 3.1. If-Match |
701 | |
702 | The "If-Match" header field makes the request method conditional on |
703 | the recipient origin server either having at least one current |
704 | representation of the target resource, when the field-value is "*", |
705 | or having a current representation of the target resource that has an |
706 | entity-tag matching a member of the list of entity-tags provided in |
707 | the field-value. |
708 | |
709 | An origin server MUST use the strong comparison function when |
710 | comparing entity-tags for If-Match (Section 2.3.2), since the client |
711 | intends this precondition to prevent the method from being applied if |
712 | there have been any changes to the representation data. |
713 | |
714 | If-Match = "*" / 1#entity-tag |
715 | |
716 | Examples: |
717 | |
718 | If-Match: "xyzzy" |
719 | If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" |
720 | If-Match: * |
721 | |
722 | If-Match is most often used with state-changing methods (e.g., POST, |
723 | PUT, DELETE) to prevent accidental overwrites when multiple user |
724 | agents might be acting in parallel on the same resource (i.e., to |
725 | |
726 | |
727 | |
728 | |
729 | |
730 | Fielding & Reschke Standards Track [Page 13] |
732 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
733 | |
734 | |
735 | prevent the "lost update" problem). It can also be used with safe |
736 | methods to abort a request if the selected representation does not |
737 | match one already stored (or partially stored) from a prior request. |
738 | |
739 | An origin server that receives an If-Match header field MUST evaluate |
740 | the condition prior to performing the method (Section 5). If the |
741 | field-value is "*", the condition is false if the origin server does |
742 | not have a current representation for the target resource. If the |
743 | field-value is a list of entity-tags, the condition is false if none |
744 | of the listed tags match the entity-tag of the selected |
745 | representation. |
746 | |
747 | An origin server MUST NOT perform the requested method if a received |
748 | If-Match condition evaluates to false; instead, the origin server |
749 | MUST respond with either a) the 412 (Precondition Failed) status code |
750 | or b) one of the 2xx (Successful) status codes if the origin server |
751 | has verified that a state change is being requested and the final |
752 | state is already reflected in the current state of the target |
753 | resource (i.e., the change requested by the user agent has already |
754 | succeeded, but the user agent might not be aware of it, perhaps |
755 | because the prior response was lost or a compatible change was made |
756 | by some other user agent). In the latter case, the origin server |
757 | MUST NOT send a validator header field in the response unless it can |
758 | verify that the request is a duplicate of an immediately prior change |
759 | made by the same user agent. |
760 | |
761 | The If-Match header field can be ignored by caches and intermediaries |
762 | because it is not applicable to a stored response. |
763 | |
764 | 3.2. If-None-Match |
765 | |
766 | The "If-None-Match" header field makes the request method conditional |
767 | on a recipient cache or origin server either not having any current |
768 | representation of the target resource, when the field-value is "*", |
769 | or having a selected representation with an entity-tag that does not |
770 | match any of those listed in the field-value. |
771 | |
772 | A recipient MUST use the weak comparison function when comparing |
773 | entity-tags for If-None-Match (Section 2.3.2), since weak entity-tags |
774 | can be used for cache validation even if there have been changes to |
775 | the representation data. |
776 | |
777 | If-None-Match = "*" / 1#entity-tag |
778 | |
779 | |
780 | |
781 | |
782 | |
783 | |
784 | |
785 | |
786 | Fielding & Reschke Standards Track [Page 14] |
788 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
789 | |
790 | |
791 | Examples: |
792 | |
793 | If-None-Match: "xyzzy" |
794 | If-None-Match: W/"xyzzy" |
795 | If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" |
796 | If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" |
797 | If-None-Match: * |
798 | |
799 | If-None-Match is primarily used in conditional GET requests to enable |
800 | efficient updates of cached information with a minimum amount of |
801 | transaction overhead. When a client desires to update one or more |
802 | stored responses that have entity-tags, the client SHOULD generate an |
803 | If-None-Match header field containing a list of those entity-tags |
804 | when making a GET request; this allows recipient servers to send a |
805 | 304 (Not Modified) response to indicate when one of those stored |
806 | responses matches the selected representation. |
807 | |
808 | If-None-Match can also be used with a value of "*" to prevent an |
809 | unsafe request method (e.g., PUT) from inadvertently modifying an |
810 | existing representation of the target resource when the client |
811 | believes that the resource does not have a current representation |
812 | (Section 4.2.1 of [RFC7231]). This is a variation on the "lost |
813 | update" problem that might arise if more than one client attempts to |
814 | create an initial representation for the target resource. |
815 | |
816 | An origin server that receives an If-None-Match header field MUST |
817 | evaluate the condition prior to performing the method (Section 5). |
818 | If the field-value is "*", the condition is false if the origin |
819 | server has a current representation for the target resource. If the |
820 | field-value is a list of entity-tags, the condition is false if one |
821 | of the listed tags match the entity-tag of the selected |
822 | representation. |
823 | |
824 | An origin server MUST NOT perform the requested method if the |
825 | condition evaluates to false; instead, the origin server MUST respond |
826 | with either a) the 304 (Not Modified) status code if the request |
827 | method is GET or HEAD or b) the 412 (Precondition Failed) status code |
828 | for all other request methods. |
829 | |
830 | Requirements on cache handling of a received If-None-Match header |
831 | field are defined in Section 4.3.2 of [RFC7234]. |
832 | |
833 | |
834 | |
835 | |
836 | |
837 | |
838 | |
839 | |
840 | |
841 | |
842 | Fielding & Reschke Standards Track [Page 15] |
844 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
845 | |
846 | |
847 | 3.3. If-Modified-Since |
848 | |
849 | The "If-Modified-Since" header field makes a GET or HEAD request |
850 | method conditional on the selected representation's modification date |
851 | being more recent than the date provided in the field-value. |
852 | Transfer of the selected representation's data is avoided if that |
853 | data has not changed. |
854 | |
855 | If-Modified-Since = HTTP-date |
856 | |
857 | An example of the field is: |
858 | |
859 | If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT |
860 | |
861 | A recipient MUST ignore If-Modified-Since if the request contains an |
862 | If-None-Match header field; the condition in If-None-Match is |
863 | considered to be a more accurate replacement for the condition in |
864 | If-Modified-Since, and the two are only combined for the sake of |
865 | interoperating with older intermediaries that might not implement |
866 | If-None-Match. |
867 | |
868 | A recipient MUST ignore the If-Modified-Since header field if the |
.../cache/cache_rfc2616.c 308 |
869 | received field-value is not a valid HTTP-date, or if the request |
870 | method is neither GET nor HEAD. |
871 | |
872 | A recipient MUST interpret an If-Modified-Since field-value's |
873 | timestamp in terms of the origin server's clock. |
874 | |
875 | If-Modified-Since is typically used for two distinct purposes: 1) to |
876 | allow efficient updates of a cached representation that does not have |
877 | an entity-tag and 2) to limit the scope of a web traversal to |
878 | resources that have recently changed. |
879 | |
880 | When used for cache updates, a cache will typically use the value of |
881 | the cached message's Last-Modified field to generate the field value |
882 | of If-Modified-Since. This behavior is most interoperable for cases |
883 | where clocks are poorly synchronized or when the server has chosen to |
884 | only honor exact timestamp matches (due to a problem with |
885 | Last-Modified dates that appear to go "back in time" when the origin |
886 | server's clock is corrected or a representation is restored from an |
887 | archived backup). However, caches occasionally generate the field |
888 | value based on other data, such as the Date header field of the |
889 | cached message or the local clock time that the message was received, |
890 | particularly when the cached message does not contain a Last-Modified |
891 | field. |
892 | |
893 | |
894 | |
895 | |
896 | |
897 | |
898 | Fielding & Reschke Standards Track [Page 16] |
900 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
901 | |
902 | |
903 | When used for limiting the scope of retrieval to a recent time |
904 | window, a user agent will generate an If-Modified-Since field value |
905 | based on either its own local clock or a Date header field received |
906 | from the server in a prior response. Origin servers that choose an |
907 | exact timestamp match based on the selected representation's |
908 | Last-Modified field will not be able to help the user agent limit its |
909 | data transfers to only those changed during the specified window. |
910 | |
911 | An origin server that receives an If-Modified-Since header field |
912 | SHOULD evaluate the condition prior to performing the method |
913 | (Section 5). The origin server SHOULD NOT perform the requested |
914 | method if the selected representation's last modification date is |
915 | earlier than or equal to the date provided in the field-value; |
916 | instead, the origin server SHOULD generate a 304 (Not Modified) |
917 | response, including only those metadata that are useful for |
918 | identifying or updating a previously cached response. |
919 | |
920 | Requirements on cache handling of a received If-Modified-Since header |
921 | field are defined in Section 4.3.2 of [RFC7234]. |
922 | |
923 | 3.4. If-Unmodified-Since |
924 | |
925 | The "If-Unmodified-Since" header field makes the request method |
926 | conditional on the selected representation's last modification date |
927 | being earlier than or equal to the date provided in the field-value. |
928 | This field accomplishes the same purpose as If-Match for cases where |
929 | the user agent does not have an entity-tag for the representation. |
930 | |
931 | If-Unmodified-Since = HTTP-date |
932 | |
933 | An example of the field is: |
934 | |
935 | If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT |
936 | |
937 | A recipient MUST ignore If-Unmodified-Since if the request contains |
938 | an If-Match header field; the condition in If-Match is considered to |
939 | be a more accurate replacement for the condition in |
940 | If-Unmodified-Since, and the two are only combined for the sake of |
941 | interoperating with older intermediaries that might not implement |
942 | If-Match. |
943 | |
944 | A recipient MUST ignore the If-Unmodified-Since header field if the |
945 | received field-value is not a valid HTTP-date. |
946 | |
947 | A recipient MUST interpret an If-Unmodified-Since field-value's |
948 | timestamp in terms of the origin server's clock. |
949 | |
950 | |
951 | |
952 | |
953 | |
954 | Fielding & Reschke Standards Track [Page 17] |
956 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
957 | |
958 | |
959 | If-Unmodified-Since is most often used with state-changing methods |
960 | (e.g., POST, PUT, DELETE) to prevent accidental overwrites when |
961 | multiple user agents might be acting in parallel on a resource that |
962 | does not supply entity-tags with its representations (i.e., to |
963 | prevent the "lost update" problem). It can also be used with safe |
964 | methods to abort a request if the selected representation does not |
965 | match one already stored (or partially stored) from a prior request. |
966 | |
967 | An origin server that receives an If-Unmodified-Since header field |
968 | MUST evaluate the condition prior to performing the method |
969 | (Section 5). The origin server MUST NOT perform the requested method |
970 | if the selected representation's last modification date is more |
971 | recent than the date provided in the field-value; instead the origin |
972 | server MUST respond with either a) the 412 (Precondition Failed) |
973 | status code or b) one of the 2xx (Successful) status codes if the |
974 | origin server has verified that a state change is being requested and |
975 | the final state is already reflected in the current state of the |
976 | target resource (i.e., the change requested by the user agent has |
977 | already succeeded, but the user agent might not be aware of that |
978 | because the prior response message was lost or a compatible change |
979 | was made by some other user agent). In the latter case, the origin |
980 | server MUST NOT send a validator header field in the response unless |
981 | it can verify that the request is a duplicate of an immediately prior |
982 | change made by the same user agent. |
983 | |
984 | The If-Unmodified-Since header field can be ignored by caches and |
985 | intermediaries because it is not applicable to a stored response. |
986 | |
987 | 3.5. If-Range |
988 | |
989 | The "If-Range" header field provides a special conditional request |
990 | mechanism that is similar to the If-Match and If-Unmodified-Since |
991 | header fields but that instructs the recipient to ignore the Range |
992 | header field if the validator doesn't match, resulting in transfer of |
993 | the new selected representation instead of a 412 (Precondition |
994 | Failed) response. If-Range is defined in Section 3.2 of [RFC7233]. |
995 | |
996 | 4. Status Code Definitions |
997 | |
998 | 4.1. 304 Not Modified |
999 | |
1000 | The 304 (Not Modified) status code indicates that a conditional GET |
1001 | or HEAD request has been received and would have resulted in a 200 |
1002 | (OK) response if it were not for the fact that the condition |
1003 | evaluated to false. In other words, there is no need for the server |
1004 | to transfer a representation of the target resource because the |
1005 | request indicates that the client, which made the request |
1006 | |
1007 | |
1008 | |
1009 | |
1010 | Fielding & Reschke Standards Track [Page 18] |
1012 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
1013 | |
1014 | |
1015 | conditional, already has a valid representation; the server is |
1016 | therefore redirecting the client to make use of that stored |
1017 | representation as if it were the payload of a 200 (OK) response. |
1018 | |
1019 | The server generating a 304 response MUST generate any of the |
1020 | following header fields that would have been sent in a 200 (OK) |
1021 | response to the same request: Cache-Control, Content-Location, Date, |
1022 | ETag, Expires, and Vary. |
1023 | |
1024 | Since the goal of a 304 response is to minimize information transfer |
1025 | when the recipient already has one or more cached representations, a |
1026 | sender SHOULD NOT generate representation metadata other than the |
1027 | above listed fields unless said metadata exists for the purpose of |
1028 | guiding cache updates (e.g., Last-Modified might be useful if the |
1029 | response does not have an ETag field). |
1030 | |
1031 | Requirements on a cache that receives a 304 response are defined in |
1032 | Section 4.3.4 of [RFC7234]. If the conditional request originated |
1033 | with an outbound client, such as a user agent with its own cache |
1034 | sending a conditional GET to a shared proxy, then the proxy SHOULD |
1035 | forward the 304 response to that client. |
1036 | |
1037 | A 304 response cannot contain a message-body; it is always terminated |
1038 | by the first empty line after the header fields. |
1039 | |
1040 | 4.2. 412 Precondition Failed |
1041 | |
1042 | The 412 (Precondition Failed) status code indicates that one or more |
1043 | conditions given in the request header fields evaluated to false when |
1044 | tested on the server. This response code allows the client to place |
1045 | preconditions on the current resource state (its current |
1046 | representations and metadata) and, thus, prevent the request method |
1047 | from being applied if the target resource is in an unexpected state. |
1048 | |
1049 | 5. Evaluation |
1050 | |
1051 | Except when excluded below, a recipient cache or origin server MUST |
1052 | evaluate received request preconditions after it has successfully |
1053 | performed its normal request checks and just before it would perform |
1054 | the action associated with the request method. A server MUST ignore |
1055 | all received preconditions if its response to the same request |
1056 | without those conditions would have been a status code other than a |
1057 | 2xx (Successful) or 412 (Precondition Failed). In other words, |
1058 | redirects and failures take precedence over the evaluation of |
1059 | preconditions in conditional requests. |
1060 | |
1061 | |
1062 | |
1063 | |
1064 | |
1065 | |
1066 | Fielding & Reschke Standards Track [Page 19] |
1068 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
1069 | |
1070 | |
1071 | A server that is not the origin server for the target resource and |
1072 | cannot act as a cache for requests on the target resource MUST NOT |
1073 | evaluate the conditional request header fields defined by this |
1074 | specification, and it MUST forward them if the request is forwarded, |
1075 | since the generating client intends that they be evaluated by a |
1076 | server that can provide a current representation. Likewise, a server |
1077 | MUST ignore the conditional request header fields defined by this |
1078 | specification when received with a request method that does not |
1079 | involve the selection or modification of a selected representation, |
1080 | such as CONNECT, OPTIONS, or TRACE. |
1081 | |
1082 | Conditional request header fields that are defined by extensions to |
1083 | HTTP might place conditions on all recipients, on the state of the |
1084 | target resource in general, or on a group of resources. For |
1085 | instance, the "If" header field in WebDAV can make a request |
1086 | conditional on various aspects of multiple resources, such as locks, |
1087 | if the recipient understands and implements that field ([RFC4918], |
1088 | Section 10.4). |
1089 | |
1090 | Although conditional request header fields are defined as being |
1091 | usable with the HEAD method (to keep HEAD's semantics consistent with |
1092 | those of GET), there is no point in sending a conditional HEAD |
1093 | because a successful response is around the same size as a 304 (Not |
1094 | Modified) response and more useful than a 412 (Precondition Failed) |
1095 | response. |
1096 | |
1097 | 6. Precedence |
1098 | |
1099 | When more than one conditional request header field is present in a |
1100 | request, the order in which the fields are evaluated becomes |
1101 | important. In practice, the fields defined in this document are |
1102 | consistently implemented in a single, logical order, since "lost |
1103 | update" preconditions have more strict requirements than cache |
1104 | validation, a validated cache is more efficient than a partial |
1105 | response, and entity tags are presumed to be more accurate than date |
1106 | validators. |
1107 | |
1108 | A recipient cache or origin server MUST evaluate the request |
1109 | preconditions defined by this specification in the following order: |
1110 | |
1111 | 1. When recipient is the origin server and If-Match is present, |
1112 | evaluate the If-Match precondition: |
1113 | |
1114 | * if true, continue to step 3 |
1115 | |
1116 | * if false, respond 412 (Precondition Failed) unless it can be |
1117 | determined that the state-changing request has already |
1118 | succeeded (see Section 3.1) |
1119 | |
1120 | |
1121 | |
1122 | Fielding & Reschke Standards Track [Page 20] |
1124 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
1125 | |
1126 | |
1127 | 2. When recipient is the origin server, If-Match is not present, and |
1128 | If-Unmodified-Since is present, evaluate the If-Unmodified-Since |
1129 | precondition: |
1130 | |
1131 | * if true, continue to step 3 |
1132 | |
1133 | * if false, respond 412 (Precondition Failed) unless it can be |
1134 | determined that the state-changing request has already |
1135 | succeeded (see Section 3.4) |
1136 | |
1137 | 3. When If-None-Match is present, evaluate the If-None-Match |
1138 | precondition: |
1139 | |
1140 | * if true, continue to step 5 |
1141 | |
1142 | * if false for GET/HEAD, respond 304 (Not Modified) |
1143 | |
1144 | * if false for other methods, respond 412 (Precondition Failed) |
1145 | |
1146 | 4. When the method is GET or HEAD, If-None-Match is not present, and |
1147 | If-Modified-Since is present, evaluate the If-Modified-Since |
1148 | precondition: |
1149 | |
1150 | * if true, continue to step 5 |
1151 | |
1152 | * if false, respond 304 (Not Modified) |
1153 | |
1154 | 5. When the method is GET and both Range and If-Range are present, |
1155 | evaluate the If-Range precondition: |
1156 | |
1157 | * if the validator matches and the Range specification is |
1158 | applicable to the selected representation, respond 206 |
1159 | (Partial Content) [RFC7233] |
1160 | |
1161 | 6. Otherwise, |
1162 | |
1163 | * all conditions are met, so perform the requested action and |
1164 | respond according to its success or failure. |
1165 | |
1166 | Any extension to HTTP/1.1 that defines additional conditional request |
1167 | header fields ought to define its own expectations regarding the |
1168 | order for evaluating such fields in relation to those defined in this |
1169 | document and other conditionals that might be found in practice. |
1170 | |
1171 | |
1172 | |
1173 | |
1174 | |
1175 | |
1176 | |
1177 | |
1178 | Fielding & Reschke Standards Track [Page 21] |
1180 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
1181 | |
1182 | |
1183 | 7. IANA Considerations |
1184 | |
1185 | 7.1. Status Code Registration |
1186 | |
1187 | The "Hypertext Transfer Protocol (HTTP) Status Code Registry" located |
1188 | at <http://www.iana.org/assignments/http-status-codes> has been |
1189 | updated with the registrations below: |
1190 | |
1191 | +-------+---------------------+-------------+ |
1192 | | Value | Description | Reference | |
1193 | +-------+---------------------+-------------+ |
1194 | | 304 | Not Modified | Section 4.1 | |
1195 | | 412 | Precondition Failed | Section 4.2 | |
1196 | +-------+---------------------+-------------+ |
1197 | |
1198 | 7.2. Header Field Registration |
1199 | |
1200 | HTTP header fields are registered within the "Message Headers" |
1201 | registry maintained at |
1202 | <http://www.iana.org/assignments/message-headers/>. |
1203 | |
1204 | This document defines the following HTTP header fields, so their |
1205 | associated registry entries have been updated according to the |
1206 | permanent registrations below (see [BCP90]): |
1207 | |
1208 | +---------------------+----------+----------+-------------+ |
1209 | | Header Field Name | Protocol | Status | Reference | |
1210 | +---------------------+----------+----------+-------------+ |
1211 | | ETag | http | standard | Section 2.3 | |
1212 | | If-Match | http | standard | Section 3.1 | |
1213 | | If-Modified-Since | http | standard | Section 3.3 | |
1214 | | If-None-Match | http | standard | Section 3.2 | |
1215 | | If-Unmodified-Since | http | standard | Section 3.4 | |
1216 | | Last-Modified | http | standard | Section 2.2 | |
1217 | +---------------------+----------+----------+-------------+ |
1218 | |
1219 | The change controller is: "IETF (iesg@ietf.org) - Internet |
1220 | Engineering Task Force". |
1221 | |
1222 | 8. Security Considerations |
1223 | |
1224 | This section is meant to inform developers, information providers, |
1225 | and users of known security concerns specific to the HTTP conditional |
1226 | request mechanisms. More general security considerations are |
1227 | addressed in HTTP "Message Syntax and Routing" [RFC7230] and |
1228 | "Semantics and Content" [RFC7231]. |
1229 | |
1230 | |
1231 | |
1232 | |
1233 | |
1234 | Fielding & Reschke Standards Track [Page 22] |
1236 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
1237 | |
1238 | |
1239 | The validators defined by this specification are not intended to |
1240 | ensure the validity of a representation, guard against malicious |
1241 | changes, or detect man-in-the-middle attacks. At best, they enable |
1242 | more efficient cache updates and optimistic concurrent writes when |
1243 | all participants are behaving nicely. At worst, the conditions will |
1244 | fail and the client will receive a response that is no more harmful |
1245 | than an HTTP exchange without conditional requests. |
1246 | |
1247 | An entity-tag can be abused in ways that create privacy risks. For |
1248 | example, a site might deliberately construct a semantically invalid |
1249 | entity-tag that is unique to the user or user agent, send it in a |
1250 | cacheable response with a long freshness time, and then read that |
1251 | entity-tag in later conditional requests as a means of re-identifying |
1252 | that user or user agent. Such an identifying tag would become a |
1253 | persistent identifier for as long as the user agent retained the |
1254 | original cache entry. User agents that cache representations ought |
1255 | to ensure that the cache is cleared or replaced whenever the user |
1256 | performs privacy-maintaining actions, such as clearing stored cookies |
1257 | or changing to a private browsing mode. |
1258 | |
1259 | 9. Acknowledgments |
1260 | |
1261 | See Section 10 of [RFC7230]. |
1262 | |
1263 | |
1264 | |
1265 | |
1266 | |
1267 | |
1268 | |
1269 | |
1270 | |
1271 | |
1272 | |
1273 | |
1274 | |
1275 | |
1276 | |
1277 | |
1278 | |
1279 | |
1280 | |
1281 | |
1282 | |
1283 | |
1284 | |
1285 | |
1286 | |
1287 | |
1288 | |
1289 | |
1290 | Fielding & Reschke Standards Track [Page 23] |
1292 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
1293 | |
1294 | |
1295 | 10. References |
1296 | |
1297 | 10.1. Normative References |
1298 | |
1299 | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate |
1300 | Requirement Levels", BCP 14, RFC 2119, March 1997. |
1301 | |
1302 | [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax |
1303 | Specifications: ABNF", STD 68, RFC 5234, January 2008. |
1304 | |
1305 | [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer |
1306 | Protocol (HTTP/1.1): Message Syntax and Routing", |
1307 | RFC 7230, June 2014. |
1308 | |
1309 | [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer |
1310 | Protocol (HTTP/1.1): Semantics and Content", RFC 7231, |
1311 | June 2014. |
1312 | |
1313 | [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., |
1314 | "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", |
1315 | RFC 7233, June 2014. |
1316 | |
1317 | [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, |
1318 | Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", |
1319 | RFC 7234, June 2014. |
1320 | |
1321 | 10.2. Informative References |
1322 | |
1323 | [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration |
1324 | Procedures for Message Header Fields", BCP 90, RFC 3864, |
1325 | September 2004. |
1326 | |
1327 | [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., |
1328 | Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext |
1329 | Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. |
1330 | |
1331 | [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed |
1332 | Authoring and Versioning (WebDAV)", RFC 4918, June 2007. |
1333 | |
1334 | |
1335 | |
1336 | |
1337 | |
1338 | |
1339 | |
1340 | |
1341 | |
1342 | |
1343 | |
1344 | |
1345 | |
1346 | Fielding & Reschke Standards Track [Page 24] |
1348 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
1349 | |
1350 | |
1351 | Appendix A. Changes from RFC 2616 |
1352 | |
1353 | The definition of validator weakness has been expanded and clarified. |
1354 | (Section 2.1) |
1355 | |
1356 | Weak entity-tags are now allowed in all requests except range |
1357 | requests. (Sections 2.1 and 3.2) |
1358 | |
1359 | The ETag header field ABNF has been changed to not use quoted-string, |
1360 | thus avoiding escaping issues. (Section 2.3) |
1361 | |
1362 | ETag is defined to provide an entity tag for the selected |
1363 | representation, thereby clarifying what it applies to in various |
1364 | situations (such as a PUT response). (Section 2.3) |
1365 | |
1366 | The precedence for evaluation of conditional requests has been |
1367 | defined. (Section 6) |
1368 | |
1369 | Appendix B. Imported ABNF |
1370 | |
1371 | The following core rules are included by reference, as defined in |
1372 | Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), |
1373 | CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double |
1374 | quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any |
1375 | 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII |
1376 | character). |
1377 | |
1378 | The rules below are defined in [RFC7230]: |
1379 | |
1380 | OWS = <OWS, see [RFC7230], Section 3.2.3> |
1381 | obs-text = <obs-text, see [RFC7230], Section 3.2.6> |
1382 | |
1383 | The rules below are defined in other parts: |
1384 | |
1385 | HTTP-date = <HTTP-date, see [RFC7231], Section 7.1.1.1> |
1386 | |
1387 | |
1388 | |
1389 | |
1390 | |
1391 | |
1392 | |
1393 | |
1394 | |
1395 | |
1396 | |
1397 | |
1398 | |
1399 | |
1400 | |
1401 | |
1402 | Fielding & Reschke Standards Track [Page 25] |
1404 | RFC 7232 HTTP/1.1 Conditional Requests June 2014 |
1405 | |
1406 | |
1407 | Appendix C. Collected ABNF |
1408 | |
1409 | In the collected ABNF below, list rules are expanded as per Section |
1410 | 1.2 of [RFC7230]. |
1411 | |
1412 | ETag = entity-tag |
1413 | |
1414 | HTTP-date = <HTTP-date, see [RFC7231], Section 7.1.1.1> |
1415 | |
1416 | If-Match = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS |
1417 | entity-tag ] ) ) |
1418 | If-Modified-Since = HTTP-date |
1419 | If-None-Match = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS |
1420 | entity-tag ] ) ) |
1421 | If-Unmodified-Since = HTTP-date |
1422 | |
1423 | Last-Modified = HTTP-date |
1424 | |
1425 | OWS = <OWS, see [RFC7230], Section 3.2.3> |
1426 | |
1427 | entity-tag = [ weak ] opaque-tag |
1428 | etagc = "!" / %x23-7E ; '#'-'~' |
1429 | / obs-text |
1430 | |
1431 | obs-text = <obs-text, see [RFC7230], Section 3.2.6> |
1432 | opaque-tag = DQUOTE *etagc DQUOTE |
1433 | |
1434 | weak = %x57.2F ; W/ |
1435 | |
1436 | |
1437 | |
1438 | |
1439 | |
1440 | |
1441 | |
1442 | |
1443 | |
1444 | |
1445 | |
1446 | |
1447 | |
1448 | |
1449 | |
1450 | |
1451 | |
1452 | |
1453 | |
1454 | |
1455 | |
1456 | |
1457 | |
1458 | Fielding & Reschke Standards Track [Page 26] |