idnits 2.17.1 draft-melnikov-imap-search-ret-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 342. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 358. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 365. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 371. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 413 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 2006) is 6522 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 3501 (ref. 'IMAP4') (Obsoleted by RFC 9051) ** Obsolete normative reference: RFC 4234 (ref. 'ABNF') (Obsoleted by RFC 5234) ** Obsolete normative reference: RFC 4551 (ref. 'CONDSTORE') (Obsoleted by RFC 7162) Summary: 7 errors (**), 0 flaws (~~), 3 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Draft A. Melnikov 2 Document: draft-melnikov-imap-search-ret-03 Isode Ltd 3 Expires: December 2006 D. Cridland 4 Inventure Systems Ltd 5 June 2006 7 IMAP4 extension to SEARCH command for controlling what kind of 8 information is returned 9 draft-melnikov-imap-search-ret-03 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six 24 months and may be updated, replaced, or obsoleted by other 25 documents at any time. It is inappropriate to use Internet-Drafts 26 as reference material or to cite them other than as "work in 27 progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 A revised version of this draft document will be submitted to the 36 RFC editor as a Standard Track RFC for the Internet Community. 37 Discussion and suggestions for improvement are requested, and 38 should be sent to ietf-imapext@imc.org and/or lemonade@ietf.org. 39 Distribution of this memo is unlimited. 41 Abstract 43 This document extends IMAP (RFC 3501) SEARCH and UID SEARCH 44 commands with several result options, which can control what kind 45 of information is returned. The following result options are 46 defined: minimal value, maximal value, all found messages and 47 number of found messages. 49 Table of Contents 51 1. Conventions Used in this Document 2 52 2. Introduction 3 53 3. IMAP Protocol Changes 3 54 3.1 SEARCH/UID SEARCH Commands 3 55 4. Formal Syntax 6 56 5. Security Considerations 7 57 6. IANA Considerations 7 58 7. References 7 59 7.1 Normative References 7 60 7.2 Informative References 8 61 8. Acknowledgments 8 62 9. Author's Addresses 8 63 10. Full Copyright Statement 8 64 11. Intellectual Property 9 65 12. Appendix A. Editorial. 9 66 12.1 Change Log 9 67 12.2 Open Issues for Discussion 10 69 1. Conventions Used in this Document 71 In examples, "C:" and "S:" indicate lines sent by the client and 72 server respectively. 74 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 75 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 76 this document are to be interpreted as described in RFC 2119 [KEYWORDS]. 78 <> 80 2. Introduction 82 [IMAPABNF] extended SEARCH and UID SEARCH commands with result 83 specifiers (also known as result options), which can control what 84 kind of information is returned. 86 A server advertising the X-DRAFT-I02-ESEARCH <> capability supports the following result options: 88 minimal value, maximal value, all found messages and number of 89 found messages. These result options allows clients to get SEARCH 90 results in more convenient forms, while also saving bandwidth 91 required to transport the results, for example finding the first 92 unseen message or returning the number of unseen or deleted 93 messages. Also, when a single MIN or a single MAX result option is 94 specified, servers can optimize execution of SEARCHes. 96 3. IMAP Protocol Changes 98 3.1 New SEARCH/UID SEARCH result options 100 The SEARCH/UID SEARCH commands are extended to allow for the 101 following result options: 103 MIN 104 Return the lowest message number/UID that satisfies the 105 SEARCH criteria. 106 If the SEARCH results in no matches, the server MUST NOT 107 include the MIN result option in the ESEARCH response, 108 however it still MUST send the ESEARCH response. 110 MAX 111 Return the highest message number/UID that satisfies the 112 SEARCH criteria. 113 If the SEARCH results in no matches, the server MUST NOT 114 include the MAX result option in the ESEARCH response, 115 however it still MUST send the ESEARCH response. 117 ALL 118 Return all message numbers/UIDs that satisfy the SEARCH 119 criteria. Unlike regular (unextended) SEARCH, the messages 120 are always returned using the sequence-set syntax. A sequence- 121 set representation may be more compact and can be used as is 122 in a subsequent command that accepts sequence-set. 123 Note, the client MUST NOT assume that messages/UIDs will be 124 listed in any particular order. 126 If the SEARCH results in no matches, the server MUST NOT 127 include the ALL result option in the ESEARCH response, 128 however it still MUST send the ESEARCH response. 130 COUNT 131 Return number of the messages that satisfy the SEARCH 132 criteria. This result option MUST always be included in the 133 ESEARCH response. 135 If one or more result option described above is specified, the 136 extended SEARCH command MUST return a single ESEARCH response 137 [IMAPABNF], instead of the SEARCH response. 138 An extended UID SEARCH command MUST cause a ESEARCH response with 139 the UID indicator present. 141 Note that future extensions to this document can allow servers to 142 return multiple ESEARCH responses for a single extended SEARCH 143 command. These extensions will have to describe how results from 144 multiple ESEARCH responses are to be amalgamated. 146 If the list of result options is empty, that requests the server to 147 return an ESEARCH response instead of the SEARCH response. This is 148 equivalent to "(ALL)". 150 Example: C: A282 SEARCH RETURN (MIN COUNT) FLAGGED 151 SINCE 1-Feb-1994 NOT FROM "Smith" 152 S: * ESEARCH (TAG "A282") MIN 2 COUNT 3 153 S: A282 OK SEARCH completed 155 Example: C: A283 SEARCH RETURN () FLAGGED 156 SINCE 1-Feb-1994 NOT FROM "Smith" 157 S: * ESEARCH (TAG "A283") ALL 2,10:11 158 S: A283 OK SEARCH completed 160 The following example demonstrates finding the first unseen message 161 as returned in the UNSEEN response code on a successful SELECT 162 command: 164 Example: C: A284 SEARCH RETURN (MIN) UNSEEN 165 S: * ESEARCH (TAG "A284") MIN 4 166 S: A284 OK SEARCH completed 168 The following example demonstrates that if the ESEARCH UID 169 indicator is present, all data in the ESEARCH response is referring 170 to UIDs, for example the MIN result specifier will be followed by 171 an UID. 173 Example: C: A285 UID SEARCH RETURN (MIN MAX) 1:5000 174 S: * ESEARCH (TAG "A285") UID MIN 7 MAX 3800 175 S: A285 OK SEARCH completed 177 The following example demonstrates returning the number of deleted 178 messages: 180 Example: C: A286 SEARCH RETURN (COUNT) DELETED 181 S: * ESEARCH (TAG "A286") COUNT 15 182 S: A286 OK SEARCH completed 184 3.2 Interaction with CONDSTORE extension 186 When the server supports both the X-DRAFT-I02-ESEARCH <> and the CONDSTORE [CONDSTORE] extension, and the 188 client requests one or more result option described in section 3.1 189 together with the MODSEQ search criterion in the same SEARCH/UID 190 SEARCH command, then the server MUST return the ESEARCH response 191 containing the MODSEQ result option (described in the following 192 paragraph) instead of the extended SEARCH response described in 193 section 3.5 of [CONDSTORE]. 195 If the SEARCH/UID SEARCH command contained a single MIN or MAX 196 result option, the MODSEQ result option contains the mod-sequence 197 for the found message. If the SEARCH/UID SEARCH command contained 198 both MIN and MAX result options and no ALL/COUNT option, the MODSEQ 199 result option contains the highest mod-sequence for the two 200 returned messages. Otherwise the MODSEQ result option contains the 201 highest mod-sequence for all messages being returned. 203 Example: The following example demonstrates how Example 15 from 204 [CONDSTORE] would look in the presence of one or more result 205 option: 207 C: a1 SEARCH RETURN (MIN) MODSEQ "/flags/\\draft" 208 all 620162338 209 S: * ESEARCH (TAG "a1") MIN 2 MODSEQ 917162488 210 S: a1 OK Search complete 212 C: a2 SEARCH RETURN (MAX) MODSEQ "/flags/\\draft" 213 all 620162338 214 S: * ESEARCH (TAG "a2") MAX 23 MODSEQ 907162321 215 S: a2 OK Search complete 217 C: a3 SEARCH RETURN (MIN MAX) MODSEQ "/flags/\\draft" 218 all 620162338 219 S: * ESEARCH (TAG "a3") MIN 2 MAX 23 MODSEQ 917162488 220 S: a3 OK Search complete 222 C: a4 SEARCH RETURN (MIN COUNT) MODSEQ "/flags/\\draft" 223 all 620162338 224 S: * ESEARCH (TAG "a4") MIN 2 COUNT 10 MODSEQ 917162500 225 S: a4 OK Search complete 227 4. Formal Syntax 229 The following syntax specification uses the Augmented Backus-Naur 230 Form (ABNF) notation as specified in [ABNF]. 232 Non-terminals referenced but not defined below are as defined by 233 [IMAP4], [CONDSTORE] or [IMAPABNF]. 235 Except as noted otherwise, all alphabetic characters are case- 236 insensitive. The use of upper or lower case characters to define 237 token strings is for editorial clarity only. Implementations MUST 238 accept these strings in a case-insensitive fashion. 240 capability =/ "X-DRAFT-I02-ESEARCH" 242 search-return-data = "MIN" SP nz-number / 243 "MAX" SP nz-number / 244 "ALL" SP sequence-set / 245 "COUNT" SP number 246 ;; conforms to the generic 247 ;; search-return-data syntax defined 248 ;; in [IMAPABNF] 250 search-return-opt = "MIN" / "MAX" / "ALL" / "COUNT" 251 ;; conforms to generic search-return-opt 252 ;; syntax defined in [IMAPABNF] 254 When the CONDSTORE [CONDSTORE] IMAP extension is also supported 255 the ABNF is updated as follows: 257 search-return-data =/ "MODSEQ" SP mod-sequence-value 258 ;; mod-sequence-value is defined 259 ;; in [CONDSTORE] 261 5. Security Considerations 263 In general case IMAP SEARCH/UID SEARCH command can be CPU and/or IO 264 intensive, so some sites/implementations even disable it entirely. 265 This is quite unfortunate, as SEARCH command is one of the best 266 examples demonstrating IMAP advantage over POP3. 267 The ALL and COUNT return options don't change how SEARCH is working 268 internally, they only change how information about found messages 269 is returned. MIN and MAX SEARCH result options described in this 270 document can lighten load on IMAP servers, which chose to optimize 271 SEARCHes containing only one or both of them. 273 It is believed that this extension doesn't raise any additional 274 security concerns not already discussed in [IMAP4]. 276 6. IANA Considerations 278 IMAP4 capabilities are registered by publishing a standards track 279 or IESG approved experimental RFC. The registry is currently 280 located at 281 . 282 This document defines the X-DRAFT-I02-ESEARCH <> IMAP capability. IANA is requested to add this 284 capability to the registry. 286 7. References 288 7.1 Normative References 290 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate 291 Requirement Levels", RFC 2119, March 1997. 293 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 294 4rev1", RFC 3501, University of Washington, March 2003. 296 [ABNF] Crocker, D. (Ed.) and P. Overell , "Augmented BNF for Syntax 297 Specifications: ABNF", RFC 4234, October 2005. 299 [IMAPABNF] Melnikov, A. and C. Daboo, "Collected extensions to 300 IMAP4 ABNF", RFC 4466, April 2006.. 302 [CONDSTORE] Melnikov, A. and S. Hole, "IMAP Extension for 303 Conditional STORE", RFC 4551, June 2006. 305 8. Acknowledgments 307 Thanks to Michael Wener, Arnt Gulbrandsen, Cyrus Daboo, Mark 308 Crispin and Pete Maclean for comments and corrections. 310 9. Author's Addresses 312 Alexey Melnikov 313 Isode Limited 314 5 Castle Business Village 315 36 Station Road 316 Hampton, Middlesex, TW12 2BX 317 UK 319 Email: Alexey.Melnikov@isode.com 321 Dave A. Cridland 322 Inventure Systems Limited 324 Email: dave.cridland@inventuresystems.co.uk 325 URL: http://invsys.co.uk/dave/ 327 10. Full Copyright Statement 329 Copyright (C) The Internet Society (2006). 331 This document is subject to the rights, licenses and restrictions 332 contained in BCP 78, and except as set forth therein, the authors 333 retain all their rights. 335 This document and the information contained herein are provided on 336 an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE 337 REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND 338 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, 339 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT 340 THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR 341 ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 342 PARTICULAR PURPOSE. 344 Acknowledgement 346 Funding for the RFC Editor function is currently provided by the 347 Internet Society. 349 11. Intellectual Property 351 The IETF takes no position regarding the validity or scope of any 352 Intellectual Property Rights or other rights that might be claimed 353 to pertain to the implementation or use of the technology described 354 in this document or the extent to which any license under such 355 rights might or might not be available; nor does it represent that 356 it has made any independent effort to identify any such rights. 357 Information on the procedures with respect to rights in RFC 358 documents can be found in BCP 78 and BCP 79. 360 Copies of IPR disclosures made to the IETF Secretariat and any 361 assurances of licenses to be made available, or the result of an 362 attempt made to obtain a general license or permission for the use 363 of such proprietary rights by implementers or users of this 364 specification can be obtained from the IETF on-line IPR repository 365 at http://www.ietf.org/ipr. 367 The IETF invites any interested party to bring to its attention any 368 copyrights, patents or patent applications, or other proprietary 369 rights that may cover technology that may be required to implement 370 this standard. Please address the information to the IETF at ietf- 371 ipr@ietf.org. 373 12. Appendix A. Editorial. 375 <> 378 12.1 Change Log 380 00 Initial Revision. 381 01 Added search correlator. Clarified what should be returned if an 382 extended SEARCH produces no matches. Filled in "IANA 383 considerations" section. Updated references: updated ABNF and 384 added [IMAPABNF]. Changed semantics of the empty list of result 385 options (now equivalent to "(ALL)". 386 02 Clarified that clients can expect a single ESEARCH result to any 387 extended SEARCH command (for result options described in this 388 document). Added more text on intended purpose of the extension. 389 Added more examples. Updated reference to the ABNF document. 390 03 Clarified interaction with CONDSTORE. Multiple editorial changes 391 to align with [IMAPABNF].