idnits 2.17.1 draft-ietf-morg-multimailbox-search-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC4466, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC4466, updated by this document, for RFC5378 checks: 2005-03-09) -- 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 (March 5, 2011) is 4798 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 3501 (Obsoleted by RFC 9051) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Message ORGanization Working Group B. Leiba 3 Internet-Draft Huawei Technologies 4 Updates: 4466 (if approved) A. Melnikov 5 Intended status: Experimental Isode Limited 6 Expires: September 6, 2011 March 5, 2011 8 IMAP4 Multimailbox SEARCH Extension 9 draft-ietf-morg-multimailbox-search-07 11 Abstract 13 The IMAP4 specification allows the searching only of the selected 14 mailbox. A user often wants to search multiple mailboxes, and a 15 client that wishes to support this must issue a series of SELECT and 16 SEARCH commands, waiting for each to complete before moving on to the 17 next. This extension allows a client to search multiple mailboxes 18 with one command, limiting the round-trips and waiting for various 19 searches to complete, and not requiring disruption of the currently 20 selected mailbox. This also uses MAILBOX and TAG fields in ESEARCH 21 responses, allowing a client to pipeline the searches if it chooses. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on September 6, 2011. 40 Copyright Notice 42 Copyright (c) 2011 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Conventions used in this document . . . . . . . . . . . . . 3 60 2. New ESEARCH command . . . . . . . . . . . . . . . . . . . . 3 61 2.1. The ESEARCH response . . . . . . . . . . . . . . . . . . . . 4 62 2.2. Source options: specifying mailboxes to search . . . . . . . 5 64 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7 66 4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . 7 68 5. Security Considerations . . . . . . . . . . . . . . . . . . 8 70 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . 9 72 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 74 8. Normative References . . . . . . . . . . . . . . . . . . . . 9 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 10 78 1. Introduction 80 The IMAP4 specification allows the searching only of the selected 81 mailbox. A user often wants to search multiple mailboxes, and a 82 client that wishes to support this must issue a series of SELECT and 83 SEARCH commands, waiting for each to complete before moving on to the 84 next. The commands can't be pipelined, because the server might run 85 them in parallel, and the untagged SEARCH responses could not then be 86 distinguished from each other. 88 This extension allows a client to search multiple mailboxes with one 89 command, and includes MAILBOX and TAG fields in the ESEARCH response, 90 yielding the following advantages: 92 o A single command limits the number of round-trips needed to search 93 a set of mailboxes. 95 o A single command eliminates the need to wait for one search to 96 complete before starting the next. 98 o A single command allows the server to optimize the search, if it 99 can. 101 o A command that is not dependent upon the selected mailbox 102 eliminates the need to disrupt the selection state, or to open 103 another IMAP connection. 105 o The MAILBOX and TAG fields in the responses allow a client to 106 distinguish which responses go with which search (and which 107 mailbox). A client can safely pipeline these search commands 108 without danger of confusion. 110 1.1. Conventions used in this document 112 In examples, "C:" indicates lines sent by a client that is connected 113 to a server. "S:" indicates lines sent by the server to the client. 115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 117 document are to be interpreted as described in RFC 2119 [RFC2119]. 119 2. New ESEARCH command 120 Arguments: OPTIONAL source options 121 OPTIONAL result options 122 OPTIONAL charset specification (see [RFC2978]) 123 searching criteria (one or more) 125 Responses: REQUIRED untagged response: ESEARCH 127 Result: OK - search completed 128 NO - error: cannot search that charset or criteria 129 BAD - command unknown or arguments invalid 131 This section defines a new ESEARCH command, which works similarly to 132 the UID SEARCH command described in section 2.6.1 of [RFC4466] 133 (initially described in section 6.4.4 of [RFC3501] and extended by 134 [RFC4731]). 136 The ESEARCH command further extends searching by allowing for 137 optional source and result options. This document does not define 138 any new result options (see Section 3.1 of [RFC4731]). A server that 139 supports this extension includes "MULTISEARCH" in its IMAP capability 140 string. 142 Because there has been confusion about this, it is worth pointing out 143 that with ESEARCH, as with *any* SEARCH or UID SEARCH command, it 144 MUST NOT be considered an error if the search terms include a range 145 of message numbers that extends (or, in fact, starts) beyond the end 146 of the mailbox. For example, a client might want to establish a 147 rolling window through the search results this way: 149 C: tag1 UID ESEARCH FROM "frobozz" 1:100 151 ...followed later by this: 153 C: tag1 UID ESEARCH FROM "frobozz" 101:200 155 ...and so on. This tells the server to match only the first hundred 156 messages in the mailbox the first time, the second hundred the second 157 time, etc. In fact, it might likely allow the server to optimize the 158 search significantly. In the above example, whether the mailbox 159 contains 50 or 150 or 250 messages, neither of the search commands 160 shown will result in an error. It is up to the client to know when 161 to stop moving its search window. 163 2.1. The ESEARCH response 165 In response to an ESEARCH command, the server MUST return ESEARCH 166 responses [RFC4731] (that is, not SEARCH responses). Because message 167 numbers are not useful for mailboxes that are not selected, the 168 responses MUST contain information about UIDs, not message numbers. 169 This is true even if the source options specify that only the 170 selected mailbox be searched. 172 Presence of a source option in absence of a result option implies the 173 "ALL" result option (see Section 3.1 of [RFC4731]). Note that this 174 is not the same as the result from the SEARCH command described in 175 the IMAP base protocol. 177 Source options describe which mailboxes must be searched for 178 messages. An ESEARCH command with source options does not affect 179 which mailbox, if any, is currently selected, regardless of which 180 mailboxes are searched. 182 For each mailbox satisfying the source options, a single ESEARCH 183 response MUST be returned if any messages in that mailbox match the 184 search criteria. An ESEARCH response MUST NOT be returned for 185 mailboxes that contain no matching messages. This is true even when 186 result options such as MIN, MAX, and COUNT are specified (see section 187 3.1 of [RFC4731]), and the values returned (lowest UID matched, 188 highest UID matched, and number of messages matched, respectively) 189 apply to the mailbox reported in that ESEARCH response. 191 Note that it is possible for an ESEARCH command to return *no* 192 untagged responses (no ESEARCH responses at all), in the case that 193 there are no matches to the search in any of the mailboxes that 194 satisfy the source options. Clients can detect this situation by 195 finding the tagged OK response without having received any matching 196 untagged ESEARCH responses. 198 Each ESEARCH response MUST contain the MAILBOX, TAG, and UIDVALIDITY 199 correlators. Correlators allow clients to issue several ESEARCH 200 commands at once (pipelined). If the SEARCHRES [RFC5182] extension 201 is used in an ESEARCH command, that ESEARCH command MUST be executed 202 by the server after all previous SEARCH/ESEARCH commands have 203 completed, and before any subsequent SEARCH/ESEARCH commands are 204 executed. The server MAY perform consecutive ESEARCH commands in 205 parallel as long as none of them use the SEARCHRES extension. 207 2.2. Source options: specifying mailboxes to search 209 The source options, if present, MUST contain a mailbox specifier as 210 defined in the IMAP NOTIFY extension [RFC5465], section 6 (using the 211 "filter-mailboxes" ABNF item), with the following differences: 213 1. The "selected-delayed" specifier is not valid here. 215 2. A "subtree-one" specifier is added. The "subtree" specifier 216 results in a search of the specified mailbox and all selectable 217 mailboxes that are subordinate to it, through an indefinitely 218 deep hierarchy. The "subtree-one" specifier results in a search 219 of the specified mailbox and all selectable child mailboxes, one 220 hierarchy level down. 222 If "subtree" is specified, the server MUST defend against loops in 223 the hierarchy (for example, those caused by recursive file-system 224 links within the message store). The server SHOULD do this by 225 keeping track of the mailboxes that have been searched, and 226 terminating the hierarchy traversal when a repeat is found. If it 227 cannot do that, it MAY do it by limiting the hierarchy depth. 229 If the source options are not present, the value "selected" is 230 assumed -- that is, only the currently selected mailbox is searched. 232 The "personal" source option is a particularly convenient way to 233 search all of the current user's mailboxes. Note that there is no 234 way to use wildcard characters to search all mailboxes; the 235 "mailboxes" source option does not do wildcard expansion. 237 If the source options include (or default to) "selected", the IMAP 238 session MUST be in "selected" state. If the source options specify 239 other mailboxes and NOT "selected", then the IMAP session MUST be in 240 either "selected" or "authenticated" state. If the session is not in 241 a correct state, the ESEARCH command MUST return a "BAD" result. 243 If the server supports the SEARCHRES [RFC5182] extension, then the 244 "SAVE" result option is valid *only* if "selected" is specified or 245 defaulted as the sole mailbox to be searched. If any source option 246 other than "selected" is specified, the ESEARCH command MUST return a 247 "BAD" result. 249 If the server supports the CONTEXT=SEARCH and/or CONTEXT=SORT 250 extension [RFC5267], then the following additional rules apply: 252 o The CONTEXT return option (Section 4.2 of [RFC5267]) can be used 253 with an ESEARCH command. 255 o If the UPDATE return option is used (Section 4.3 of [RFC5267]), it 256 MUST apply ONLY to the the currently selected mailbox. If UPDATE 257 is used and there is no mailbox currently selected, the ESEARCH 258 command MUST return a "BAD" result. 260 o The PARTIAL search return option (Section 4.4 of [RFC5267]) can be 261 used and applies to each mailbox searched by the ESEARCH command. 263 If the server supports the ACL [RFC4314] extension, then the logged 264 in user is required to have the 'r' right for each mailbox she wants 265 to search. In addition, any mailboxes that are not explicitly named 266 (accessed through "personal" or "subtree", for example) are required 267 to have the "l" right. Mailboxes matching the source options for 268 which the logged in user lacks sufficient rights MUST be ignored by 269 the ESEARCH command processing. In particular, ESEARCH responses 270 MUST NOT be returned for those mailboxes. 272 3. Examples 274 In the following example, note that two ESEARCH commands are 275 pipelined, and that the server is running them in parallel, 276 interleaving a response to the second search amid the responses to 277 the first (watch the tags). 279 C: tag1 ESEARCH IN (mailboxes "folder1" subtree "folder2") unseen 280 C: tag2 ESEARCH IN (mailboxes "folder1" subtree-one "folder2") 281 subject "chad" 282 S: * ESEARCH (TAG "tag1" MAILBOX "folder1" UIDVALIDITY 1) UID ALL 283 4001,4003,4005,4007,4009 284 S: * ESEARCH (TAG "tag2" MAILBOX "folder1" UIDVALIDITY 1) UID ALL 285 3001:3004,3788 286 S: * ESEARCH (TAG "tag1" MAILBOX "folder2/banana" UIDVALIDITY 503) 287 UID ALL 3002,4004 288 S: * ESEARCH (TAG "tag1" MAILBOX "folder2/peach" UIDVALIDITY 3) UID 289 ALL 921691 290 S: tag1 OK done 291 S: * ESEARCH (TAG "tag2" MAILBOX "folder2/salmon" UIDVALIDITY 292 1111111) UID ALL 50003,50006,50009,50012 293 S: tag2 OK done 295 4. Formal Syntax 297 The following syntax specification uses the Augmented Backus-Naur 298 Form (ABNF) as described in [RFC5234]. Terms not defined here are 299 taken from [RFC3501], [RFC5465], or [RFC4466]. 301 command-auth =/ esearch 302 ; Update definition from IMAP base [RFC3501] 303 ; Add new "esearch" command. 305 command-select =/ esearch 306 ; Update definition from IMAP base [RFC3501] 307 ; Add new "esearch" command. 309 filter-mailboxes-other =/ ("subtree-one" SP one-or-more-mailbox) 310 ; Update definition from IMAP Notify [RFC5465] 311 ; Add new "subtree-one" selector. 313 filter-mailboxes-selected = "selected" 314 ; Update definition from IMAP Notify [RFC5465] 315 ; We forbid the use of "selected-delayed". 317 one-correlator = ("TAG" SP tag-string) / ("MAILBOX" SP astring) / 318 ("UIDVALIDITY" SP nz-number) 319 ; Each correlator MUST appear exactly once 321 scope-option = scope-option-name [SP scope-option-value] 322 ; No options defined here. Syntax for future extensions. 324 scope-option-name = tagged-ext-label 325 ; No options defined here. Syntax for future extensions. 327 scope-option-value = tagged-ext-val 328 ; No options defined here. Syntax for future extensions. 330 scope-options = scope-option *(SP scope-option) 331 ; A given option may only appear once 332 ; No options defined here. Syntax for future extensions. 334 esearch = "ESEARCH" [SP esearch-source-opts] 335 [SP search-return-opts] SP search-program 337 search-correlator = SP "(" one-correlator *(SP one-correlator) ")" 338 ; Updates definition in IMAP4 ABNF [RFC4466] 340 esearch-source-opts = "IN" SP "(" source-mbox [SP 341 "(" scope-options ")"] ")" 343 source-mbox = filter-mailboxes *(SP filter-mailboxes) 344 ; filter-mailboxes is defined in IMAP Notify [RFC5465] 345 ; See updated definition of filter-mailboxes-other, above. 346 ; See updated definition of filter-mailboxes-selected, above. 348 5. Security Considerations 350 This new IMAP ESEARCH command allows a single command to search many 351 mailboxes at once. On the one hand, a client could do that by 352 sending many IMAP SEARCH commands. On the other hand, this makes it 353 easier for a client to overwork a server, by sending a single command 354 that results in an expensive search of tens of thousands of 355 mailboxes. Server implementations need to be aware of that, and 356 provide mechanisms that prevent a client from adversely affecting 357 other users. Limitations on the number of mailboxes that may be 358 searched in one command, and/or on the server resources that will be 359 devoted to responding to a single client, are reasonable limitations 360 for an implementation to impose. 362 Implementations MUST, of course, apply access controls appropriately, 363 limiting a user's access to ESEARCH in the same way its access is 364 limited for any other IMAP commands. This extension has no data- 365 access risks beyond what may be there in the unextended IMAP 366 implementation. 368 Mailboxes matching the source options for which the logged in user 369 lacks sufficient rights MUST be ignored by the ESEARCH command 370 processing (see the paragraph about this in Section 2.2). In 371 particular, any attempt to distinguish insufficient access from non- 372 existent mailboxes may expose information about the mailbox hierarchy 373 that isn't otherwise available to the client. 375 If "subtree" is specified, the server MUST defend against loops in 376 the hierarchy (see the paragraph about this in Section 2.2). 378 6. IANA Considerations 380 IMAP4 capabilities are registered by publishing a standards track or 381 IESG approved experimental RFC. The registry is currently located 382 here: 384 http://www.iana.org/assignments/imap4-capabilities 386 This document defines the IMAP capability "MULTISEARCH" and IANA is 387 asked to add it to the registry. 389 7. Acknowledgements 391 The authors gratefully acknowledge feedback provided by Timo 392 Sirainen, Peter Coates and Arnt Gulbrandsen. 394 8. Normative References 396 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 397 Requirement Levels", BCP 14, RFC 2119, March 1997. 399 [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration 400 Procedures", BCP 19, RFC 2978, October 2000. 402 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 403 4rev1", RFC 3501, March 2003. 405 [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", 406 RFC 4314, December 2005. 408 [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 409 ABNF", RFC 4466, April 2006. 411 [RFC4731] Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH 412 Command for Controlling What Kind of Information Is 413 Returned", RFC 4731, November 2006. 415 [RFC5182] Melnikov, A., "IMAP Extension for Referencing the Last 416 SEARCH Result", RFC 5182, March 2008. 418 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 419 Specifications: ABNF", STD 68, RFC 5234, January 2008. 421 [RFC5267] Cridland, D. and C. King, "Contexts for IMAP4", RFC 5267, 422 July 2008. 424 [RFC5465] Gulbrandsen, A., King, C., and A. Melnikov, "The IMAP 425 NOTIFY Extension", RFC 5465, February 2009. 427 Authors' Addresses 429 Barry Leiba 430 Huawei Technologies 432 Phone: +1 646 827 0648 433 Email: barryleiba@computer.org 434 URI: http://internetmessagingtechnology.org/ 435 Alexey Melnikov 436 Isode Limited 437 5 Castle Business Village 438 36 Station Road 439 Hampton, Middlesex TW12 2BX 440 UK 442 Email: Alexey.Melnikov@isode.com 443 URI: http://www.melnikov.ca/