diff options
Diffstat (limited to 'doc/rfc/rfc8508.txt')
| -rw-r--r-- | doc/rfc/rfc8508.txt | 619 |
1 files changed, 619 insertions, 0 deletions
diff --git a/doc/rfc/rfc8508.txt b/doc/rfc/rfc8508.txt new file mode 100644 index 0000000..7ba4fe6 --- /dev/null +++ b/doc/rfc/rfc8508.txt @@ -0,0 +1,619 @@ + + + + + + +Internet Engineering Task Force (IETF) S. Brandt +Request for Comments: 8508 Verizon +Category: Standards Track January 2019 +ISSN: 2070-1721 + + + IMAP REPLACE Extension + +Abstract + + This document defines an IMAP extension that can be used to replace + an existing message in a message store with a new message. Message + replacement is a common operation for clients that automatically save + drafts or notes as a user composes them. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc8508. + +Copyright Notice + + Copyright (c) 2019 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (https://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + + + + +Brandt Standards Track [Page 1] + +RFC 8508 IMAP REPLACE Extension January 2019 + + +Table of Contents + + 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 2 + 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 + 3. REPLACE and UID REPLACE . . . . . . . . . . . . . . . . . . . 3 + 3.1. Advertising Support for REPLACE . . . . . . . . . . . . . 3 + 3.2. REPLACE Command . . . . . . . . . . . . . . . . . . . . . 3 + 3.3. UID REPLACE Command . . . . . . . . . . . . . . . . . . . 4 + 3.4. Semantics of REPLACE and UID REPLACE . . . . . . . . . . 5 + 3.5. IMAP State Diagram Impacts . . . . . . . . . . . . . . . 6 + 4. Interaction with Other Extensions . . . . . . . . . . . . . . 6 + 4.1. ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 4.2. CATENATE . . . . . . . . . . . . . . . . . . . . . . . . 6 + 4.3. UIDPLUS . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 4.4. IMAP Events in Sieve . . . . . . . . . . . . . . . . . . 8 + 4.5. CONDSTORE/QRESYNC . . . . . . . . . . . . . . . . . . . . 8 + 4.6. OBJECTID . . . . . . . . . . . . . . . . . . . . . . . . 8 + 4.7. MULTIAPPEND . . . . . . . . . . . . . . . . . . . . . . . 8 + 5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 9 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 + 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 + 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 8.1. Normative References . . . . . . . . . . . . . . . . . . 9 + 8.2. Informative References . . . . . . . . . . . . . . . . . 10 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 11 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 + +1. Overview + + This document defines an IMAP ([RFC3501]) extension to facilitate the + replacement of an existing message with a new one. This is + accomplished by defining a new REPLACE command and extending the + Unique Identifier (UID) command to allow UID REPLACE. + + Since there is no replace function in the base IMAP specification, + clients have instead had to use a combination of three separate + commands issued in serial fashion; APPEND, STORE, and EXPUNGE. + Pipelining of these three commands is not recommended since failure + of any individual command should prevent subsequent commands from + being executed lest the original message version be lost. + + Because of the non-atomic nature of the existing sequence, + interruptions can leave messages in intermediate states that can be + seen and acted upon by other clients. Such interruptions can also + strand older revisions of messages, thereby forcing the user to + manually clean up multiple revisions of the same message in order to + avoid wasteful quota consumption. Additionally, the existing + sequence can fail on APPEND due to an over-quota condition even + + + +Brandt Standards Track [Page 2] + +RFC 8508 IMAP REPLACE Extension January 2019 + + + though the subsequent STORE/EXPUNGE would free up enough space for + the newly revised message. And finally, server efficiencies may be + possible with a single logical message replacement operation as + compared to the existing APPEND/STORE/EXPUNGE sequence. + + In its simplest form, the REPLACE command is a single-command + encapsulation of APPEND, STORE +flags \DELETED, and UID EXPUNGE for a + message, except that it avoids any of the quota implications or + intermediate states associated with the three-command sequence. + Server developers are encouraged to implement REPLACE as an atomic + operation to simplify error handling, minimize operational concerns, + and reduce potential security problems. For systems where this is + not possible, communication with the requesting client must ensure no + confusion of message store state. A server MUST NOT generate a + response code for the STORE +flags \DELETED portion of the sequence. + Additionally, servers supporting the REPLACE command MUST NOT infer + any inheritance of content, flags, or annotations from the message + being replaced. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + + Formal syntax is defined by [RFC5234]. + + Example lines prefaced by "C:" are sent by the client, and ones + prefaced by "S:" are sent by the server. + +3. REPLACE and UID REPLACE + +3.1. Advertising Support for REPLACE + + Servers that implement the REPLACE extension will return "REPLACE" as + one of the supported capabilities in the CAPABILITY command response. + +3.2. REPLACE Command + + Arguments: message sequence number + mailbox name + OPTIONAL flag parenthesized list + OPTIONAL date/time string + message literal + + Responses: no specific responses for this command + + + +Brandt Standards Track [Page 3] + +RFC 8508 IMAP REPLACE Extension January 2019 + + + Result: OK - replace completed + NO - replace error; can't remove specified message + or can't add new message content + BAD - command unknown or arguments invalid + + Example: + C: A003 REPLACE 4 Drafts (\Seen \Draft) {312} + S: + Ready for literal data + C: Date: Thu, 1 Jan 2015 00:05:00 -0500 (EST) + C: From: Fritz Schmidt <fritz.ze@example.org> + C: Subject: happy new year !! + C: To: miss.mitzy@example.org + C: Message-Id: <B238822388-0100000@example.org> + C: MIME-Version: 1.0 + C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII + C: + C: Just saw the best fireworks show. Wish you were here. + C: + S: * OK [APPENDUID 1 2000] Replacement Message ready + S: * 5 EXISTS + S: * 4 EXPUNGE + S: A003 OK Replace completed + +3.3. UID REPLACE Command + + This extends the first form of the UID command (see Section 6.4.8 of + [RFC3501]) to add the REPLACE command defined above as a valid + argument. This form of REPLACE uses a UID rather than a sequence + number as its first parameter. + + Example: + C: A004 UID REPLACE 2000 Drafts (\Seen \Draft) {350} + S: + Ready for literal data + C: Date: Thu, 1 Jan 2015 00:06:00 -0500 (EST) + C: From: Fritz Schmidt <fritz.ze@example.org> + C: Subject: happy new year !! + C: To: miss.mitzy@example.org + C: Message-Id: <B238822389-0100000@example.org> + C: MIME-Version: 1.0 + C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII + C: + C: Just saw the best fireworks show. Wish you were here. + C: Hopefully next year you can join us. + C: + S: * OK [APPENDUID 1 2001] Replacement Message ready + S: * 5 EXISTS + S: * 4 EXPUNGE + S: A004 OK Replace completed + + + +Brandt Standards Track [Page 4] + +RFC 8508 IMAP REPLACE Extension January 2019 + + +3.4. Semantics of REPLACE and UID REPLACE + + The REPLACE and UID REPLACE commands take five arguments: a message + identifier, a named mailbox, an optional parenthesized flag list, an + optional message date/time string, and a message literal. The + message literal will be appended to the named mailbox, and the + message specified by the message identifier will be removed from the + selected mailbox. These operations will appear to the client as a + single action. This has the same effect as the following sequence: + + 1. APPEND + 2. [UID] STORE +FLAGS.SILENT \DELETED + 3. UID EXPUNGE + + In the cited sequence, the quota implications of APPEND are evaluated + within the context of the pending EXPUNGE so that only the net quota + consumption is considered. Additionally, the EXPUNGE portion of the + sequence only applies to the specified message, not all messages + flagged as "\Deleted". + + Although the effect of REPLACE is identical to the steps above, the + semantics are not identical; similar to MOVE [RFC6851], the + intermediate states do not occur and the response codes are + different. In particular, the response codes for APPEND and EXPUNGE + will be returned while those for the STORE operation MUST NOT be + generated. + + When an error occurs while processing REPLACE or UID REPLACE, the + server MUST NOT leave the selected mailbox in an inconsistent state; + any untagged EXPUNGE response MUST NOT be sent until all actions are + successfully completed. + + While it may be common for the named mailbox argument to match the + selected mailbox for the common use case of replacing a draft, the + REPLACE extension intentionally does not require the two to be the + same. As an example, it's possible to use the REPLACE command to + replace a message in the \Drafts special-use mailbox (see Section 2 + of [RFC6154]) with a message in the \Sent special-use mailbox + following message submission. + + Because of the similarity of REPLACE to APPEND, extensions that + affect APPEND affect REPLACE in the same way. Response codes such as + TRYCREATE (see Section 6.3.11 of [RFC3501]), along with those defined + by extensions, are sent as appropriate. See Section 4 for more + information about how REPLACE interacts with other IMAP extensions. + + + + + + +Brandt Standards Track [Page 5] + +RFC 8508 IMAP REPLACE Extension January 2019 + + +3.5. IMAP State Diagram Impacts + + Unlike the APPEND command, which is valid in the authenticated state, + the REPLACE and UID REPLACE commands MUST only be valid in the + selected state. This difference from APPEND is necessary since + REPLACE operates on message sequence numbers. Additionally, the + REPLACE extension intentionally follows the convention for UID + commands found in Section 6.4.8 of [RFC3501] in that the UID variant + of the command does not support use from the authenticated state. + +4. Interaction with Other Extensions + + This section describes how REPLACE interacts with some other IMAP + extensions. + +4.1. ACL + + The Access Control List (ACL) rights [RFC4314] required for UID + REPLACE are the union of the ACL rights required for UID STORE and + UID EXPUNGE in the current mailbox, and APPEND in the target mailbox. + +4.2. CATENATE + + Servers supporting both REPLACE and CATENATE [RFC4469] MUST support + the additional append-data and resp-text-code elements defined in + Section 5 ("Formal Syntax") of [RFC4469] in conjunction with the + REPLACE command. When combined with CATENATE, REPLACE can become + quite an efficient way of message manipulation. + + + + + + + + + + + + + + + + + + + + + + + +Brandt Standards Track [Page 6] + +RFC 8508 IMAP REPLACE Extension January 2019 + + + Example: + + User composes message and attaches photo + ---------------------------------------- + C: A010 APPEND Drafts (\Seen \Draft) {1201534} + S: + Ready for literal data + C: Date: Thu, 1 Jan 2015 00:10:00 -0500 (EST) + C: From: Fritz Schmidt <fritz.ze@example.org> + C: Message-ID: <B238822388-0100003@example.org> + C: MIME-Version: 1.0 + C: Content-Type: multipart/mixed; + C: boundary="------------030305060306060609050804" + C: + C: --------------030305060306060609050804 + C: Content-Type: text/plain; charset=utf-8; format=flowed + C: Content-Transfer-Encoding: 7bit + C: + C: Here is picture from the fireworks + C: + C: Yours... + C: Fritz + C: + C: --------------030305060306060609050804 + C: Content-Type: image/jpeg; + C: name="Fireworks.jpg" + C: Content-Transfer-Encoding: base64 + C: Content-Disposition: attachment; + C: filename="Fireworks.jpg" + C: + <large base64 encoded part goes here> + C: + C: --------------030305060306060609050804-- + S: A010 OK [APPENDUID 1 3002] APPEND complete + + User completes message with To: and Subject: fields + --------------------------------------------------- + C: A011 UID REPLACE 3002 Drafts CATENATE (TEXT {71} + S: + Ready for literal data + C: To: Mitzy <miss.mitzy@example.org> + C: Subject: My view of the fireworks + C: URL "/Drafts/;UID=3002") + S: * OK [APPENDUID 1 3003] Replacement Message ready + S: * 5 EXISTS + S: * 4 EXPUNGE + S: A011 OK REPLACE completed + + + + + + +Brandt Standards Track [Page 7] + +RFC 8508 IMAP REPLACE Extension January 2019 + + +4.3. UIDPLUS + + Servers supporting both REPLACE and UIDPLUS [RFC4315] SHOULD send + APPENDUID in response to a UID REPLACE command. For additional + information, see Section 3 of [RFC4315]. Servers implementing + REPLACE and UIDPLUS are also advised to send the APPENDUID response + code in an untagged OK before sending the EXPUNGE or replaced + responses. (Sending APPENDUID in the tagged OK as described in the + UIDPLUS specification means that the client first receives EXPUNGE + for a message and afterwards APPENDUID for the new message. It can + be unnecessarily difficult to process that sequence usefully.) + +4.4. IMAP Events in Sieve + + REPLACE applies to IMAP events in Sieve [RFC6785] in the same way + that APPEND does. Therefore, REPLACE can cause a Sieve script to be + invoked with the imap.cause set to "APPEND". Because the + intermediate state of STORE +FLAGS.SILENT \DELETED is not exposed by + REPLACE, no action will be taken that results in an imap.cause of + FLAG. + +4.5. CONDSTORE/QRESYNC + + Servers implementing both REPLACE and CONDSTORE/QRESYNC [RFC7162] + MUST treat the message being replaced as if it were being removed + with a UID EXPUNGE command. Sections 3.2.9 and 3.2.10 of [RFC7162] + are particularly relevant for this condition. + +4.6. OBJECTID + + Servers implementing both REPLACE and OBJECTID [RFC8474] MUST return + different EMAILIDs for both the replaced and replacing messages. The + only exception to this is the case outlined in Section 5.1 ("EMAILID + Identifier for Identical Messages") of [RFC8474] when the server + detects that both messages' immutable content is identical. + +4.7. MULTIAPPEND + + The REPLACE extension has no interaction with MULTIAPPEND [RFC3502]. + This document explicitly does not outline a method for replacing + multiple messages concurrently. + + + + + + + + + + +Brandt Standards Track [Page 8] + +RFC 8508 IMAP REPLACE Extension January 2019 + + +5. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [RFC5234]. [RFC3501] defines + the non-terminals "capability","command-select", "mailbox", + "seq-number", and "uid". [RFC4466] defines the non-terminal + "append-message". + + Except as noted otherwise, all alphabetic characters are case + insensitive. The use of uppercase or lowercase characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + capability =/ "REPLACE" + + command-select =/ replace + replace = "REPLACE" SP seq-number SP mailbox append-message + uid =/ "UID" SP replace + +6. Security Considerations + + This document is believed to add no security problems beyond those + that may already exist with the base IMAP specification. The REPLACE + command may actually prevent some potential security problems because + it avoids intermediate message states that could possibly be + exploited by an attacker. + +7. IANA Considerations + + The IANA has added REPLACE to the "IMAP Capabilities" registry at + <https://www.iana.org/assignments/imap-capabilities>. + +8. References + +8.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + <https://www.rfc-editor.org/info/rfc2119>. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003, + <https://www.rfc-editor.org/info/rfc3501>. + + [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", + RFC 4314, DOI 10.17487/RFC4314, December 2005, + <https://www.rfc-editor.org/info/rfc4314>. + + + +Brandt Standards Track [Page 9] + +RFC 8508 IMAP REPLACE Extension January 2019 + + + [RFC4315] Crispin, M., "Internet Message Access Protocol (IMAP) - + UIDPLUS extension", RFC 4315, DOI 10.17487/RFC4315, + December 2005, <https://www.rfc-editor.org/info/rfc4315>. + + [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, DOI 10.17487/RFC4466, April 2006, + <https://www.rfc-editor.org/info/rfc4466>. + + [RFC4469] Resnick, P., "Internet Message Access Protocol (IMAP) + CATENATE Extension", RFC 4469, DOI 10.17487/RFC4469, April + 2006, <https://www.rfc-editor.org/info/rfc4469>. + + [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, + DOI 10.17487/RFC5234, January 2008, + <https://www.rfc-editor.org/info/rfc5234>. + + [RFC6785] Leiba, B., "Support for Internet Message Access Protocol + (IMAP) Events in Sieve", RFC 6785, DOI 10.17487/RFC6785, + November 2012, <https://www.rfc-editor.org/info/rfc6785>. + + [RFC7162] Melnikov, A. and D. Cridland, "IMAP Extensions: Quick Flag + Changes Resynchronization (CONDSTORE) and Quick Mailbox + Resynchronization (QRESYNC)", RFC 7162, + DOI 10.17487/RFC7162, May 2014, + <https://www.rfc-editor.org/info/rfc7162>. + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, <https://www.rfc-editor.org/info/rfc8174>. + + [RFC8474] Gondwana, B., Ed., "IMAP Extension for Object + Identifiers", RFC 8474, DOI 10.17487/RFC8474, September + 2018, <https://www.rfc-editor.org/info/rfc8474>. + +8.2. Informative References + + [RFC3502] Crispin, M., "Internet Message Access Protocol (IMAP) - + MULTIAPPEND Extension", RFC 3502, DOI 10.17487/RFC3502, + March 2003, <https://www.rfc-editor.org/info/rfc3502>. + + [RFC6154] Leiba, B. and J. Nicolson, "IMAP LIST Extension for + Special-Use Mailboxes", RFC 6154, DOI 10.17487/RFC6154, + March 2011, <https://www.rfc-editor.org/info/rfc6154>. + + + + + + + +Brandt Standards Track [Page 10] + +RFC 8508 IMAP REPLACE Extension January 2019 + + + [RFC6851] Gulbrandsen, A. and N. Freed, Ed., "Internet Message + Access Protocol (IMAP) - MOVE Extension", RFC 6851, + DOI 10.17487/RFC6851, January 2013, + <https://www.rfc-editor.org/info/rfc6851>. + +Acknowledgements + + The author would like to thank the participants of IMAPEXT with + particular thanks to Arnt Gulbrandsen, Alexey Melnikov, Chris Newman, + and Bron Gondwana for their specific contributions. + +Author's Address + + Stuart Brandt + Verizon + 22001 Loudoun County Parkway + Ashburn, VA 20147 + United States of America + + Email: stujenerin@aol.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Brandt Standards Track [Page 11] + |