--- /dev/null
+
+
+
+
+
+
+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]
+\f
+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]
+\f
+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]
+\f
+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]
+\f
+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]
+\f
+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]
+\f
+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]
+\f
+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]
+\f
projects / uw-imap / commitdiff