diff options
Diffstat (limited to 'imap/docs/rfc/rfc4731.txt')
| -rw-r--r-- | imap/docs/rfc/rfc4731.txt | 451 |
1 files changed, 451 insertions, 0 deletions
diff --git a/imap/docs/rfc/rfc4731.txt b/imap/docs/rfc/rfc4731.txt new file mode 100644 index 00000000..8c4869aa --- /dev/null +++ b/imap/docs/rfc/rfc4731.txt @@ -0,0 +1,451 @@ + + + + + + +Network Working Group A. Melnikov +Request for Comments: 4731 Isode Ltd +Category: Standards Track D. Cridland + Inventure Systems Ltd + November 2006 + + + IMAP4 Extension to SEARCH Command for Controlling + What Kind of Information Is Returned + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The IETF Trust (2006). + +Abstract + + This document extends IMAP (RFC 3501) SEARCH and UID SEARCH commands + with several result options, which can control what kind of + information is returned. The following result options are defined: + minimal value, maximal value, all found messages, and number of found + messages. + +Table of Contents + + 1. Introduction ....................................................2 + 2. Conventions Used in This Document ...............................2 + 3. IMAP Protocol Changes ...........................................2 + 3.1. New SEARCH/UID SEARCH Result Options .......................2 + 3.2. Interaction with CONDSTORE extension .......................4 + 4. Formal Syntax ...................................................5 + 5. Security Considerations .........................................6 + 6. IANA Considerations .............................................6 + 7. Normative References ............................................6 + 8. Acknowledgments .................................................6 + + + + + + + + + +Melnikov & Cridland Standards Track [Page 1] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + +1. Introduction + + [IMAPABNF] extended SEARCH and UID SEARCH commands with result + specifiers (also known as result options), which can control what + kind of information is returned. + + A server advertising the ESEARCH capability supports the following + result options: minimal value, maximal value, all found messages, + and number of found messages. These result options allow clients to + get SEARCH results in more convenient forms, while also saving + bandwidth required to transport the results, for example, by finding + the first unseen message or returning the number of unseen or deleted + messages. Also, when a single MIN or a single MAX result option is + specified, servers can optimize execution of SEARCHes. + +2. Conventions Used in This Document + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [KEYWORDS]. + +3. IMAP Protocol Changes + +3.1. New SEARCH/UID SEARCH Result Options + + The SEARCH/UID SEARCH commands are extended to allow for the + following result options: + + MIN + Return the lowest message number/UID that satisfies the SEARCH + criteria. + + If the SEARCH results in no matches, the server MUST NOT + include the MIN result option in the ESEARCH response; however, + it still MUST send the ESEARCH response. + + MAX + Return the highest message number/UID that satisfies the SEARCH + criteria. + + If the SEARCH results in no matches, the server MUST NOT + include the MAX result option in the ESEARCH response; however, + it still MUST send the ESEARCH response. + + + + + +Melnikov & Cridland Standards Track [Page 2] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + + ALL + Return all message numbers/UIDs that satisfy the SEARCH + criteria. Unlike regular (unextended) SEARCH, the messages are + always returned using the sequence-set syntax. A sequence-set + representation may be more compact and can be used as is in a + subsequent command that accepts sequence-set. Note, the client + MUST NOT assume that messages/UIDs will be listed in any + particular order. + + If the SEARCH results in no matches, the server MUST NOT + include the ALL result option in the ESEARCH response; however, + it still MUST send the ESEARCH response. + + COUNT + Return number of the messages that satisfy the SEARCH criteria. + This result option MUST always be included in the ESEARCH + response. + + If one or more result options described above are specified, the + extended SEARCH command MUST return a single ESEARCH response + [IMAPABNF], instead of the SEARCH response. + + An extended UID SEARCH command MUST cause an ESEARCH response with + the UID indicator present. + + Note that future extensions to this document can allow servers to + return multiple ESEARCH responses for a single extended SEARCH + command. These extensions will have to describe how results from + multiple ESEARCH responses are to be amalgamated. + + If the list of result options is empty, that requests the server to + return an ESEARCH response instead of the SEARCH response. This is + equivalent to "(ALL)". + + Example: C: A282 SEARCH RETURN (MIN COUNT) FLAGGED + SINCE 1-Feb-1994 NOT FROM "Smith" + S: * ESEARCH (TAG "A282") MIN 2 COUNT 3 + S: A282 OK SEARCH completed + + Example: C: A283 SEARCH RETURN () FLAGGED + SINCE 1-Feb-1994 NOT FROM "Smith" + S: * ESEARCH (TAG "A283") ALL 2,10:11 + S: A283 OK SEARCH completed + + The following example demonstrates finding the first unseen message + as returned in the UNSEEN response code on a successful SELECT + command: + + + + +Melnikov & Cridland Standards Track [Page 3] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + + Example: C: A284 SEARCH RETURN (MIN) UNSEEN + S: * ESEARCH (TAG "A284") MIN 4 + S: A284 OK SEARCH completed + + The following example demonstrates that if the ESEARCH UID indicator + is present, all data in the ESEARCH response is referring to UIDs; + for example, the MIN result specifier will be followed by a UID. + + Example: C: A285 UID SEARCH RETURN (MIN MAX) 1:5000 + S: * ESEARCH (TAG "A285") UID MIN 7 MAX 3800 + S: A285 OK SEARCH completed + + The following example demonstrates returning the number of deleted + messages: + + Example: C: A286 SEARCH RETURN (COUNT) DELETED + S: * ESEARCH (TAG "A286") COUNT 15 + S: A286 OK SEARCH completed + +3.2. Interaction with CONDSTORE extension + + When the server supports both the ESEARCH and the CONDSTORE + [CONDSTORE] extension, and the client requests one or more result + option described in section 3.1 together with the MODSEQ search + criterion in the same SEARCH/UID SEARCH command, then the server MUST + return the ESEARCH response containing the MODSEQ result option + (described in the following paragraph) instead of the extended SEARCH + response described in section 3.5 of [CONDSTORE]. + + If the SEARCH/UID SEARCH command contained a single MIN or MAX result + option, the MODSEQ result option contains the mod-sequence for the + found message. If the SEARCH/UID SEARCH command contained both MIN + and MAX result options and no ALL/COUNT option, the MODSEQ result + option contains the highest mod-sequence for the two returned + messages. Otherwise the MODSEQ result option contains the highest + mod-sequence for all messages being returned. + + Example: The following example demonstrates how Example 15 from + [CONDSTORE] would look in the presence of one or more result option: + + C: a1 SEARCH RETURN (MIN) MODSEQ "/flags/\\draft" + all 620162338 + S: * ESEARCH (TAG "a1") MIN 2 MODSEQ 917162488 + S: a1 OK Search complete + + C: a2 SEARCH RETURN (MAX) MODSEQ "/flags/\\draft" + all 620162338 + S: * ESEARCH (TAG "a2") MAX 23 MODSEQ 907162321 + + + +Melnikov & Cridland Standards Track [Page 4] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + + S: a2 OK Search complete + + C: a3 SEARCH RETURN (MIN MAX) MODSEQ "/flags/\\draft" + all 620162338 + S: * ESEARCH (TAG "a3") MIN 2 MAX 23 MODSEQ 917162488 + S: a3 OK Search complete + + C: a4 SEARCH RETURN (MIN COUNT) MODSEQ "/flags/\\draft" + all 620162338 + S: * ESEARCH (TAG "a4") MIN 2 COUNT 10 MODSEQ 917162500 + S: a4 OK Search complete + +4. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. + + Non-terminals referenced but not defined below are as defined by + [IMAP4], [CONDSTORE], or [IMAPABNF]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lowercase characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + capability =/ "ESEARCH" + + search-return-data = "MIN" SP nz-number / + "MAX" SP nz-number / + "ALL" SP sequence-set / + "COUNT" SP number + ;; conforms to the generic + ;; search-return-data syntax defined + ;; in [IMAPABNF] + + search-return-opt = "MIN" / "MAX" / "ALL" / "COUNT" + ;; conforms to generic search-return-opt + ;; syntax defined in [IMAPABNF] + + When the CONDSTORE [CONDSTORE] IMAP extension is also supported, + the ABNF is updated as follows: + + search-return-data =/ "MODSEQ" SP mod-sequence-value + ;; mod-sequence-value is defined + ;; in [CONDSTORE] + + + + + + +Melnikov & Cridland Standards Track [Page 5] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + +5. Security Considerations + + In the general case, the IMAP SEARCH/UID SEARCH commands can be CPU + and/or IO intensive, and are seen by some as a potential attack point + for denial of service attacks, so some sites/implementations even + disable them entirely. This is quite unfortunate, as SEARCH command + is one of the best examples demonstrating IMAP advantage over POP3. + + The ALL and COUNT return options don't change how SEARCH is working + internally; they only change how information about found messages is + returned. MIN and MAX SEARCH result options described in this + document can lighten the load on IMAP servers that choose to optimize + SEARCHes containing only one or both of them. + + It is believed that this extension doesn't raise any additional + security concerns not already discussed in [IMAP4]. + +6. IANA Considerations + + IMAP4 capabilities are registered by publishing a standards track RFC + or an IESG-approved experimental RFC. The registry is currently + located at <http://www.iana.org/assignments/imap4-capabilities>. + + This document defines the ESEARCH IMAP capability, which IANA added + to the registry. + +7. Normative References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [ABNF] Crocker, D. (Ed.) and P. Overell , "Augmented BNF for + Syntax Specifications: ABNF", RFC 4234, October 2005. + + [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006.. + + [CONDSTORE] Melnikov, A. and S. Hole, "IMAP Extension for Conditional + STORE", RFC 4551, June 2006. + +8. Acknowledgments + + Thanks to Michael Wener, Arnt Gulbrandsen, Cyrus Daboo, Mark Crispin, + and Pete Maclean for comments and corrections. + + + + +Melnikov & Cridland Standards Track [Page 6] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + +Authors' Addresses + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex, TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + + + Dave A. Cridland + Inventure Systems Limited + + EMail: dave.cridland@inventuresystems.co.uk + URL: http://invsys.co.uk/dave/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov & Cridland Standards Track [Page 7] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, + AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT + THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY + IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR + PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + +Melnikov & Cridland Standards Track [Page 8] + |