imapext-2007

annotate docs/rfc/rfc4731.txt @ 0:ada5e610ab86

imap-2007e
author yuuji@gentei.org
date Mon, 14 Sep 2009 15:17:45 +0900
parents
children
rev   line source
yuuji@0 1
yuuji@0 2
yuuji@0 3
yuuji@0 4
yuuji@0 5
yuuji@0 6
yuuji@0 7 Network Working Group A. Melnikov
yuuji@0 8 Request for Comments: 4731 Isode Ltd
yuuji@0 9 Category: Standards Track D. Cridland
yuuji@0 10 Inventure Systems Ltd
yuuji@0 11 November 2006
yuuji@0 12
yuuji@0 13
yuuji@0 14 IMAP4 Extension to SEARCH Command for Controlling
yuuji@0 15 What Kind of Information Is Returned
yuuji@0 16
yuuji@0 17 Status of This Memo
yuuji@0 18
yuuji@0 19 This document specifies an Internet standards track protocol for the
yuuji@0 20 Internet community, and requests discussion and suggestions for
yuuji@0 21 improvements. Please refer to the current edition of the "Internet
yuuji@0 22 Official Protocol Standards" (STD 1) for the standardization state
yuuji@0 23 and status of this protocol. Distribution of this memo is unlimited.
yuuji@0 24
yuuji@0 25 Copyright Notice
yuuji@0 26
yuuji@0 27 Copyright (C) The IETF Trust (2006).
yuuji@0 28
yuuji@0 29 Abstract
yuuji@0 30
yuuji@0 31 This document extends IMAP (RFC 3501) SEARCH and UID SEARCH commands
yuuji@0 32 with several result options, which can control what kind of
yuuji@0 33 information is returned. The following result options are defined:
yuuji@0 34 minimal value, maximal value, all found messages, and number of found
yuuji@0 35 messages.
yuuji@0 36
yuuji@0 37 Table of Contents
yuuji@0 38
yuuji@0 39 1. Introduction ....................................................2
yuuji@0 40 2. Conventions Used in This Document ...............................2
yuuji@0 41 3. IMAP Protocol Changes ...........................................2
yuuji@0 42 3.1. New SEARCH/UID SEARCH Result Options .......................2
yuuji@0 43 3.2. Interaction with CONDSTORE extension .......................4
yuuji@0 44 4. Formal Syntax ...................................................5
yuuji@0 45 5. Security Considerations .........................................6
yuuji@0 46 6. IANA Considerations .............................................6
yuuji@0 47 7. Normative References ............................................6
yuuji@0 48 8. Acknowledgments .................................................6
yuuji@0 49
yuuji@0 50
yuuji@0 51
yuuji@0 52
yuuji@0 53
yuuji@0 54
yuuji@0 55
yuuji@0 56
yuuji@0 57
yuuji@0 58 Melnikov & Cridland Standards Track [Page 1]
yuuji@0 59
yuuji@0 60 RFC 4731 IMAP4 Extension to SEARCH November 2006
yuuji@0 61
yuuji@0 62
yuuji@0 63 1. Introduction
yuuji@0 64
yuuji@0 65 [IMAPABNF] extended SEARCH and UID SEARCH commands with result
yuuji@0 66 specifiers (also known as result options), which can control what
yuuji@0 67 kind of information is returned.
yuuji@0 68
yuuji@0 69 A server advertising the ESEARCH capability supports the following
yuuji@0 70 result options: minimal value, maximal value, all found messages,
yuuji@0 71 and number of found messages. These result options allow clients to
yuuji@0 72 get SEARCH results in more convenient forms, while also saving
yuuji@0 73 bandwidth required to transport the results, for example, by finding
yuuji@0 74 the first unseen message or returning the number of unseen or deleted
yuuji@0 75 messages. Also, when a single MIN or a single MAX result option is
yuuji@0 76 specified, servers can optimize execution of SEARCHes.
yuuji@0 77
yuuji@0 78 2. Conventions Used in This Document
yuuji@0 79
yuuji@0 80 In examples, "C:" and "S:" indicate lines sent by the client and
yuuji@0 81 server, respectively.
yuuji@0 82
yuuji@0 83 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
yuuji@0 84 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
yuuji@0 85 document are to be interpreted as described in RFC 2119 [KEYWORDS].
yuuji@0 86
yuuji@0 87 3. IMAP Protocol Changes
yuuji@0 88
yuuji@0 89 3.1. New SEARCH/UID SEARCH Result Options
yuuji@0 90
yuuji@0 91 The SEARCH/UID SEARCH commands are extended to allow for the
yuuji@0 92 following result options:
yuuji@0 93
yuuji@0 94 MIN
yuuji@0 95 Return the lowest message number/UID that satisfies the SEARCH
yuuji@0 96 criteria.
yuuji@0 97
yuuji@0 98 If the SEARCH results in no matches, the server MUST NOT
yuuji@0 99 include the MIN result option in the ESEARCH response; however,
yuuji@0 100 it still MUST send the ESEARCH response.
yuuji@0 101
yuuji@0 102 MAX
yuuji@0 103 Return the highest message number/UID that satisfies the SEARCH
yuuji@0 104 criteria.
yuuji@0 105
yuuji@0 106 If the SEARCH results in no matches, the server MUST NOT
yuuji@0 107 include the MAX result option in the ESEARCH response; however,
yuuji@0 108 it still MUST send the ESEARCH response.
yuuji@0 109
yuuji@0 110
yuuji@0 111
yuuji@0 112
yuuji@0 113
yuuji@0 114 Melnikov & Cridland Standards Track [Page 2]
yuuji@0 115
yuuji@0 116 RFC 4731 IMAP4 Extension to SEARCH November 2006
yuuji@0 117
yuuji@0 118
yuuji@0 119 ALL
yuuji@0 120 Return all message numbers/UIDs that satisfy the SEARCH
yuuji@0 121 criteria. Unlike regular (unextended) SEARCH, the messages are
yuuji@0 122 always returned using the sequence-set syntax. A sequence-set
yuuji@0 123 representation may be more compact and can be used as is in a
yuuji@0 124 subsequent command that accepts sequence-set. Note, the client
yuuji@0 125 MUST NOT assume that messages/UIDs will be listed in any
yuuji@0 126 particular order.
yuuji@0 127
yuuji@0 128 If the SEARCH results in no matches, the server MUST NOT
yuuji@0 129 include the ALL result option in the ESEARCH response; however,
yuuji@0 130 it still MUST send the ESEARCH response.
yuuji@0 131
yuuji@0 132 COUNT
yuuji@0 133 Return number of the messages that satisfy the SEARCH criteria.
yuuji@0 134 This result option MUST always be included in the ESEARCH
yuuji@0 135 response.
yuuji@0 136
yuuji@0 137 If one or more result options described above are specified, the
yuuji@0 138 extended SEARCH command MUST return a single ESEARCH response
yuuji@0 139 [IMAPABNF], instead of the SEARCH response.
yuuji@0 140
yuuji@0 141 An extended UID SEARCH command MUST cause an ESEARCH response with
yuuji@0 142 the UID indicator present.
yuuji@0 143
yuuji@0 144 Note that future extensions to this document can allow servers to
yuuji@0 145 return multiple ESEARCH responses for a single extended SEARCH
yuuji@0 146 command. These extensions will have to describe how results from
yuuji@0 147 multiple ESEARCH responses are to be amalgamated.
yuuji@0 148
yuuji@0 149 If the list of result options is empty, that requests the server to
yuuji@0 150 return an ESEARCH response instead of the SEARCH response. This is
yuuji@0 151 equivalent to "(ALL)".
yuuji@0 152
yuuji@0 153 Example: C: A282 SEARCH RETURN (MIN COUNT) FLAGGED
yuuji@0 154 SINCE 1-Feb-1994 NOT FROM "Smith"
yuuji@0 155 S: * ESEARCH (TAG "A282") MIN 2 COUNT 3
yuuji@0 156 S: A282 OK SEARCH completed
yuuji@0 157
yuuji@0 158 Example: C: A283 SEARCH RETURN () FLAGGED
yuuji@0 159 SINCE 1-Feb-1994 NOT FROM "Smith"
yuuji@0 160 S: * ESEARCH (TAG "A283") ALL 2,10:11
yuuji@0 161 S: A283 OK SEARCH completed
yuuji@0 162
yuuji@0 163 The following example demonstrates finding the first unseen message
yuuji@0 164 as returned in the UNSEEN response code on a successful SELECT
yuuji@0 165 command:
yuuji@0 166
yuuji@0 167
yuuji@0 168
yuuji@0 169
yuuji@0 170 Melnikov & Cridland Standards Track [Page 3]
yuuji@0 171
yuuji@0 172 RFC 4731 IMAP4 Extension to SEARCH November 2006
yuuji@0 173
yuuji@0 174
yuuji@0 175 Example: C: A284 SEARCH RETURN (MIN) UNSEEN
yuuji@0 176 S: * ESEARCH (TAG "A284") MIN 4
yuuji@0 177 S: A284 OK SEARCH completed
yuuji@0 178
yuuji@0 179 The following example demonstrates that if the ESEARCH UID indicator
yuuji@0 180 is present, all data in the ESEARCH response is referring to UIDs;
yuuji@0 181 for example, the MIN result specifier will be followed by a UID.
yuuji@0 182
yuuji@0 183 Example: C: A285 UID SEARCH RETURN (MIN MAX) 1:5000
yuuji@0 184 S: * ESEARCH (TAG "A285") UID MIN 7 MAX 3800
yuuji@0 185 S: A285 OK SEARCH completed
yuuji@0 186
yuuji@0 187 The following example demonstrates returning the number of deleted
yuuji@0 188 messages:
yuuji@0 189
yuuji@0 190 Example: C: A286 SEARCH RETURN (COUNT) DELETED
yuuji@0 191 S: * ESEARCH (TAG "A286") COUNT 15
yuuji@0 192 S: A286 OK SEARCH completed
yuuji@0 193
yuuji@0 194 3.2. Interaction with CONDSTORE extension
yuuji@0 195
yuuji@0 196 When the server supports both the ESEARCH and the CONDSTORE
yuuji@0 197 [CONDSTORE] extension, and the client requests one or more result
yuuji@0 198 option described in section 3.1 together with the MODSEQ search
yuuji@0 199 criterion in the same SEARCH/UID SEARCH command, then the server MUST
yuuji@0 200 return the ESEARCH response containing the MODSEQ result option
yuuji@0 201 (described in the following paragraph) instead of the extended SEARCH
yuuji@0 202 response described in section 3.5 of [CONDSTORE].
yuuji@0 203
yuuji@0 204 If the SEARCH/UID SEARCH command contained a single MIN or MAX result
yuuji@0 205 option, the MODSEQ result option contains the mod-sequence for the
yuuji@0 206 found message. If the SEARCH/UID SEARCH command contained both MIN
yuuji@0 207 and MAX result options and no ALL/COUNT option, the MODSEQ result
yuuji@0 208 option contains the highest mod-sequence for the two returned
yuuji@0 209 messages. Otherwise the MODSEQ result option contains the highest
yuuji@0 210 mod-sequence for all messages being returned.
yuuji@0 211
yuuji@0 212 Example: The following example demonstrates how Example 15 from
yuuji@0 213 [CONDSTORE] would look in the presence of one or more result option:
yuuji@0 214
yuuji@0 215 C: a1 SEARCH RETURN (MIN) MODSEQ "/flags/\\draft"
yuuji@0 216 all 620162338
yuuji@0 217 S: * ESEARCH (TAG "a1") MIN 2 MODSEQ 917162488
yuuji@0 218 S: a1 OK Search complete
yuuji@0 219
yuuji@0 220 C: a2 SEARCH RETURN (MAX) MODSEQ "/flags/\\draft"
yuuji@0 221 all 620162338
yuuji@0 222 S: * ESEARCH (TAG "a2") MAX 23 MODSEQ 907162321
yuuji@0 223
yuuji@0 224
yuuji@0 225
yuuji@0 226 Melnikov & Cridland Standards Track [Page 4]
yuuji@0 227
yuuji@0 228 RFC 4731 IMAP4 Extension to SEARCH November 2006
yuuji@0 229
yuuji@0 230
yuuji@0 231 S: a2 OK Search complete
yuuji@0 232
yuuji@0 233 C: a3 SEARCH RETURN (MIN MAX) MODSEQ "/flags/\\draft"
yuuji@0 234 all 620162338
yuuji@0 235 S: * ESEARCH (TAG "a3") MIN 2 MAX 23 MODSEQ 917162488
yuuji@0 236 S: a3 OK Search complete
yuuji@0 237
yuuji@0 238 C: a4 SEARCH RETURN (MIN COUNT) MODSEQ "/flags/\\draft"
yuuji@0 239 all 620162338
yuuji@0 240 S: * ESEARCH (TAG "a4") MIN 2 COUNT 10 MODSEQ 917162500
yuuji@0 241 S: a4 OK Search complete
yuuji@0 242
yuuji@0 243 4. Formal Syntax
yuuji@0 244
yuuji@0 245 The following syntax specification uses the Augmented Backus-Naur
yuuji@0 246 Form (ABNF) notation as specified in [ABNF].
yuuji@0 247
yuuji@0 248 Non-terminals referenced but not defined below are as defined by
yuuji@0 249 [IMAP4], [CONDSTORE], or [IMAPABNF].
yuuji@0 250
yuuji@0 251 Except as noted otherwise, all alphabetic characters are case-
yuuji@0 252 insensitive. The use of upper or lowercase characters to define
yuuji@0 253 token strings is for editorial clarity only. Implementations MUST
yuuji@0 254 accept these strings in a case-insensitive fashion.
yuuji@0 255
yuuji@0 256 capability =/ "ESEARCH"
yuuji@0 257
yuuji@0 258 search-return-data = "MIN" SP nz-number /
yuuji@0 259 "MAX" SP nz-number /
yuuji@0 260 "ALL" SP sequence-set /
yuuji@0 261 "COUNT" SP number
yuuji@0 262 ;; conforms to the generic
yuuji@0 263 ;; search-return-data syntax defined
yuuji@0 264 ;; in [IMAPABNF]
yuuji@0 265
yuuji@0 266 search-return-opt = "MIN" / "MAX" / "ALL" / "COUNT"
yuuji@0 267 ;; conforms to generic search-return-opt
yuuji@0 268 ;; syntax defined in [IMAPABNF]
yuuji@0 269
yuuji@0 270 When the CONDSTORE [CONDSTORE] IMAP extension is also supported,
yuuji@0 271 the ABNF is updated as follows:
yuuji@0 272
yuuji@0 273 search-return-data =/ "MODSEQ" SP mod-sequence-value
yuuji@0 274 ;; mod-sequence-value is defined
yuuji@0 275 ;; in [CONDSTORE]
yuuji@0 276
yuuji@0 277
yuuji@0 278
yuuji@0 279
yuuji@0 280
yuuji@0 281
yuuji@0 282 Melnikov & Cridland Standards Track [Page 5]
yuuji@0 283
yuuji@0 284 RFC 4731 IMAP4 Extension to SEARCH November 2006
yuuji@0 285
yuuji@0 286
yuuji@0 287 5. Security Considerations
yuuji@0 288
yuuji@0 289 In the general case, the IMAP SEARCH/UID SEARCH commands can be CPU
yuuji@0 290 and/or IO intensive, and are seen by some as a potential attack point
yuuji@0 291 for denial of service attacks, so some sites/implementations even
yuuji@0 292 disable them entirely. This is quite unfortunate, as SEARCH command
yuuji@0 293 is one of the best examples demonstrating IMAP advantage over POP3.
yuuji@0 294
yuuji@0 295 The ALL and COUNT return options don't change how SEARCH is working
yuuji@0 296 internally; they only change how information about found messages is
yuuji@0 297 returned. MIN and MAX SEARCH result options described in this
yuuji@0 298 document can lighten the load on IMAP servers that choose to optimize
yuuji@0 299 SEARCHes containing only one or both of them.
yuuji@0 300
yuuji@0 301 It is believed that this extension doesn't raise any additional
yuuji@0 302 security concerns not already discussed in [IMAP4].
yuuji@0 303
yuuji@0 304 6. IANA Considerations
yuuji@0 305
yuuji@0 306 IMAP4 capabilities are registered by publishing a standards track RFC
yuuji@0 307 or an IESG-approved experimental RFC. The registry is currently
yuuji@0 308 located at <http://www.iana.org/assignments/imap4-capabilities>.
yuuji@0 309
yuuji@0 310 This document defines the ESEARCH IMAP capability, which IANA added
yuuji@0 311 to the registry.
yuuji@0 312
yuuji@0 313 7. Normative References
yuuji@0 314
yuuji@0 315 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
yuuji@0 316 Requirement Levels", BCP 14, RFC 2119, March 1997.
yuuji@0 317
yuuji@0 318 [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
yuuji@0 319 4rev1", RFC 3501, March 2003.
yuuji@0 320
yuuji@0 321 [ABNF] Crocker, D. (Ed.) and P. Overell , "Augmented BNF for
yuuji@0 322 Syntax Specifications: ABNF", RFC 4234, October 2005.
yuuji@0 323
yuuji@0 324 [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
yuuji@0 325 ABNF", RFC 4466, April 2006..
yuuji@0 326
yuuji@0 327 [CONDSTORE] Melnikov, A. and S. Hole, "IMAP Extension for Conditional
yuuji@0 328 STORE", RFC 4551, June 2006.
yuuji@0 329
yuuji@0 330 8. Acknowledgments
yuuji@0 331
yuuji@0 332 Thanks to Michael Wener, Arnt Gulbrandsen, Cyrus Daboo, Mark Crispin,
yuuji@0 333 and Pete Maclean for comments and corrections.
yuuji@0 334
yuuji@0 335
yuuji@0 336
yuuji@0 337
yuuji@0 338 Melnikov & Cridland Standards Track [Page 6]
yuuji@0 339
yuuji@0 340 RFC 4731 IMAP4 Extension to SEARCH November 2006
yuuji@0 341
yuuji@0 342
yuuji@0 343 Authors' Addresses
yuuji@0 344
yuuji@0 345 Alexey Melnikov
yuuji@0 346 Isode Limited
yuuji@0 347 5 Castle Business Village
yuuji@0 348 36 Station Road
yuuji@0 349 Hampton, Middlesex, TW12 2BX
yuuji@0 350 UK
yuuji@0 351
yuuji@0 352 EMail: Alexey.Melnikov@isode.com
yuuji@0 353
yuuji@0 354
yuuji@0 355 Dave A. Cridland
yuuji@0 356 Inventure Systems Limited
yuuji@0 357
yuuji@0 358 EMail: dave.cridland@inventuresystems.co.uk
yuuji@0 359 URL: http://invsys.co.uk/dave/
yuuji@0 360
yuuji@0 361
yuuji@0 362
yuuji@0 363
yuuji@0 364
yuuji@0 365
yuuji@0 366
yuuji@0 367
yuuji@0 368
yuuji@0 369
yuuji@0 370
yuuji@0 371
yuuji@0 372
yuuji@0 373
yuuji@0 374
yuuji@0 375
yuuji@0 376
yuuji@0 377
yuuji@0 378
yuuji@0 379
yuuji@0 380
yuuji@0 381
yuuji@0 382
yuuji@0 383
yuuji@0 384
yuuji@0 385
yuuji@0 386
yuuji@0 387
yuuji@0 388
yuuji@0 389
yuuji@0 390
yuuji@0 391
yuuji@0 392
yuuji@0 393
yuuji@0 394 Melnikov & Cridland Standards Track [Page 7]
yuuji@0 395
yuuji@0 396 RFC 4731 IMAP4 Extension to SEARCH November 2006
yuuji@0 397
yuuji@0 398
yuuji@0 399 Full Copyright Statement
yuuji@0 400
yuuji@0 401 Copyright (C) The IETF Trust (2006).
yuuji@0 402
yuuji@0 403 This document is subject to the rights, licenses and restrictions
yuuji@0 404 contained in BCP 78, and except as set forth therein, the authors
yuuji@0 405 retain all their rights.
yuuji@0 406
yuuji@0 407 This document and the information contained herein are provided on an
yuuji@0 408 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
yuuji@0 409 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST,
yuuji@0 410 AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES,
yuuji@0 411 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT
yuuji@0 412 THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
yuuji@0 413 IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
yuuji@0 414 PURPOSE.
yuuji@0 415
yuuji@0 416 Intellectual Property
yuuji@0 417
yuuji@0 418 The IETF takes no position regarding the validity or scope of any
yuuji@0 419 Intellectual Property Rights or other rights that might be claimed to
yuuji@0 420 pertain to the implementation or use of the technology described in
yuuji@0 421 this document or the extent to which any license under such rights
yuuji@0 422 might or might not be available; nor does it represent that it has
yuuji@0 423 made any independent effort to identify any such rights. Information
yuuji@0 424 on the procedures with respect to rights in RFC documents can be
yuuji@0 425 found in BCP 78 and BCP 79.
yuuji@0 426
yuuji@0 427 Copies of IPR disclosures made to the IETF Secretariat and any
yuuji@0 428 assurances of licenses to be made available, or the result of an
yuuji@0 429 attempt made to obtain a general license or permission for the use of
yuuji@0 430 such proprietary rights by implementers or users of this
yuuji@0 431 specification can be obtained from the IETF on-line IPR repository at
yuuji@0 432 http://www.ietf.org/ipr.
yuuji@0 433
yuuji@0 434 The IETF invites any interested party to bring to its attention any
yuuji@0 435 copyrights, patents or patent applications, or other proprietary
yuuji@0 436 rights that may cover technology that may be required to implement
yuuji@0 437 this standard. Please address the information to the IETF at
yuuji@0 438 ietf-ipr@ietf.org.
yuuji@0 439
yuuji@0 440 Acknowledgement
yuuji@0 441
yuuji@0 442 Funding for the RFC Editor function is currently provided by the
yuuji@0 443 Internet Society.
yuuji@0 444
yuuji@0 445
yuuji@0 446
yuuji@0 447
yuuji@0 448
yuuji@0 449
yuuji@0 450 Melnikov & Cridland Standards Track [Page 8]
yuuji@0 451

UW-IMAP'd extensions by yuuji