1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/rfc/rfc4731.txt	Mon Sep 14 15:17:45 2009 +0900
     1.3 @@ -0,0 +1,451 @@
     1.4 +
     1.5 +
     1.6 +
     1.7 +
     1.8 +
     1.9 +
    1.10 +Network Working Group                                        A. Melnikov
    1.11 +Request for Comments: 4731                                     Isode Ltd
    1.12 +Category: Standards Track                                    D. Cridland
    1.13 +                                                   Inventure Systems Ltd
    1.14 +                                                           November 2006
    1.15 +
    1.16 +
    1.17 +           IMAP4 Extension to SEARCH Command for Controlling
    1.18 +                  What Kind of Information Is Returned
    1.19 +
    1.20 +Status of This Memo
    1.21 +
    1.22 +   This document specifies an Internet standards track protocol for the
    1.23 +   Internet community, and requests discussion and suggestions for
    1.24 +   improvements.  Please refer to the current edition of the "Internet
    1.25 +   Official Protocol Standards" (STD 1) for the standardization state
    1.26 +   and status of this protocol.  Distribution of this memo is unlimited.
    1.27 +
    1.28 +Copyright Notice
    1.29 +
    1.30 +   Copyright (C) The IETF Trust (2006).
    1.31 +
    1.32 +Abstract
    1.33 +
    1.34 +   This document extends IMAP (RFC 3501) SEARCH and UID SEARCH commands
    1.35 +   with several result options, which can control what kind of
    1.36 +   information is returned. The following result options are defined:
    1.37 +   minimal value, maximal value, all found messages, and number of found
    1.38 +   messages.
    1.39 +
    1.40 +Table of Contents
    1.41 +
    1.42 +   1. Introduction ....................................................2
    1.43 +   2. Conventions Used in This Document ...............................2
    1.44 +   3. IMAP Protocol Changes ...........................................2
    1.45 +      3.1. New SEARCH/UID SEARCH Result Options .......................2
    1.46 +      3.2. Interaction with CONDSTORE extension .......................4
    1.47 +   4. Formal Syntax ...................................................5
    1.48 +   5. Security Considerations .........................................6
    1.49 +   6. IANA Considerations .............................................6
    1.50 +   7. Normative References ............................................6
    1.51 +   8. Acknowledgments .................................................6
    1.52 +
    1.53 +
    1.54 +
    1.55 +
    1.56 +
    1.57 +
    1.58 +
    1.59 +
    1.60 +
    1.61 +Melnikov & Cridland         Standards Track                     [Page 1]
    1.62 +
    1.63 +RFC 4731               IMAP4 Extension to SEARCH           November 2006
    1.64 +
    1.65 +
    1.66 +1.  Introduction
    1.67 +
    1.68 +   [IMAPABNF] extended SEARCH and UID SEARCH commands with result
    1.69 +   specifiers (also known as result options), which can control what
    1.70 +   kind of information is returned.
    1.71 +
    1.72 +   A server advertising the ESEARCH capability supports the following
    1.73 +   result options:  minimal value, maximal value, all found messages,
    1.74 +   and number of found messages.  These result options allow clients to
    1.75 +   get SEARCH results in more convenient forms, while also saving
    1.76 +   bandwidth required to transport the results, for example, by finding
    1.77 +   the first unseen message or returning the number of unseen or deleted
    1.78 +   messages.  Also, when a single MIN or a single MAX result option is
    1.79 +   specified, servers can optimize execution of SEARCHes.
    1.80 +
    1.81 +2.  Conventions Used in This Document
    1.82 +
    1.83 +   In examples, "C:" and "S:" indicate lines sent by the client and
    1.84 +   server, respectively.
    1.85 +
    1.86 +   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
    1.87 +   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
    1.88 +   document are to be interpreted as described in RFC 2119 [KEYWORDS].
    1.89 +
    1.90 +3.   IMAP Protocol Changes
    1.91 +
    1.92 +3.1.  New SEARCH/UID SEARCH Result Options
    1.93 +
    1.94 +   The SEARCH/UID SEARCH commands are extended to allow for the
    1.95 +   following result options:
    1.96 +
    1.97 +      MIN
    1.98 +         Return the lowest message number/UID that satisfies the SEARCH
    1.99 +         criteria.
   1.100 +
   1.101 +         If the SEARCH results in no matches, the server MUST NOT
   1.102 +         include the MIN result option in the ESEARCH response; however,
   1.103 +         it still MUST send the ESEARCH response.
   1.104 +
   1.105 +      MAX
   1.106 +         Return the highest message number/UID that satisfies the SEARCH
   1.107 +         criteria.
   1.108 +
   1.109 +         If the SEARCH results in no matches, the server MUST NOT
   1.110 +         include the MAX result option in the ESEARCH response; however,
   1.111 +         it still MUST send the ESEARCH response.
   1.112 +
   1.113 +
   1.114 +
   1.115 +
   1.116 +
   1.117 +Melnikov & Cridland         Standards Track                     [Page 2]
   1.118 +
   1.119 +RFC 4731               IMAP4 Extension to SEARCH           November 2006
   1.120 +
   1.121 +
   1.122 +      ALL
   1.123 +         Return all message numbers/UIDs that satisfy the SEARCH
   1.124 +         criteria.  Unlike regular (unextended) SEARCH, the messages are
   1.125 +         always returned using the sequence-set syntax.  A sequence-set
   1.126 +         representation may be more compact and can be used as is in a
   1.127 +         subsequent command that accepts sequence-set.  Note, the client
   1.128 +         MUST NOT assume that messages/UIDs will be listed in any
   1.129 +         particular order.
   1.130 +
   1.131 +         If the SEARCH results in no matches, the server MUST NOT
   1.132 +         include the ALL result option in the ESEARCH response; however,
   1.133 +         it still MUST send the ESEARCH response.
   1.134 +
   1.135 +      COUNT
   1.136 +         Return number of the messages that satisfy the SEARCH criteria.
   1.137 +         This result option MUST always be included in the ESEARCH
   1.138 +         response.
   1.139 +
   1.140 +   If one or more result options described above are specified, the
   1.141 +   extended SEARCH command MUST return a single ESEARCH response
   1.142 +   [IMAPABNF], instead of the SEARCH response.
   1.143 +
   1.144 +   An extended UID SEARCH command MUST cause an ESEARCH response with
   1.145 +   the UID indicator present.
   1.146 +
   1.147 +   Note that future extensions to this document can allow servers to
   1.148 +   return multiple ESEARCH responses for a single extended SEARCH
   1.149 +   command.  These extensions will have to describe how results from
   1.150 +   multiple ESEARCH responses are to be amalgamated.
   1.151 +
   1.152 +   If the list of result options is empty, that requests the server to
   1.153 +   return an ESEARCH response instead of the SEARCH response.  This is
   1.154 +   equivalent to "(ALL)".
   1.155 +
   1.156 +      Example:    C: A282 SEARCH RETURN (MIN COUNT) FLAGGED
   1.157 +                     SINCE 1-Feb-1994 NOT FROM "Smith"
   1.158 +                  S: * ESEARCH (TAG "A282") MIN 2 COUNT 3
   1.159 +                  S: A282 OK SEARCH completed
   1.160 +
   1.161 +      Example:    C: A283 SEARCH RETURN () FLAGGED
   1.162 +                     SINCE 1-Feb-1994 NOT FROM "Smith"
   1.163 +                  S: * ESEARCH (TAG "A283") ALL 2,10:11
   1.164 +                  S: A283 OK SEARCH completed
   1.165 +
   1.166 +   The following example demonstrates finding the first unseen message
   1.167 +   as returned in the UNSEEN response code on a successful SELECT
   1.168 +   command:
   1.169 +
   1.170 +
   1.171 +
   1.172 +
   1.173 +Melnikov & Cridland         Standards Track                     [Page 3]
   1.174 +
   1.175 +RFC 4731               IMAP4 Extension to SEARCH           November 2006
   1.176 +
   1.177 +
   1.178 +      Example:    C: A284 SEARCH RETURN (MIN) UNSEEN
   1.179 +                  S: * ESEARCH (TAG "A284") MIN 4
   1.180 +                  S: A284 OK SEARCH completed
   1.181 +
   1.182 +   The following example demonstrates that if the ESEARCH UID indicator
   1.183 +   is present, all data in the ESEARCH response is referring to UIDs;
   1.184 +   for example, the MIN result specifier will be followed by a UID.
   1.185 +
   1.186 +      Example:    C: A285 UID SEARCH RETURN (MIN MAX) 1:5000
   1.187 +                  S: * ESEARCH (TAG "A285") UID MIN 7 MAX 3800
   1.188 +                  S: A285 OK SEARCH completed
   1.189 +
   1.190 +   The following example demonstrates returning the number of deleted
   1.191 +   messages:
   1.192 +
   1.193 +      Example:    C: A286 SEARCH RETURN (COUNT) DELETED
   1.194 +                  S: * ESEARCH (TAG "A286") COUNT 15
   1.195 +                  S: A286 OK SEARCH completed
   1.196 +
   1.197 +3.2.  Interaction with CONDSTORE extension
   1.198 +
   1.199 +   When the server supports both the ESEARCH and the CONDSTORE
   1.200 +   [CONDSTORE] extension, and the client requests one or more result
   1.201 +   option described in section 3.1 together with the MODSEQ search
   1.202 +   criterion in the same SEARCH/UID SEARCH command, then the server MUST
   1.203 +   return the ESEARCH response containing the MODSEQ result option
   1.204 +   (described in the following paragraph) instead of the extended SEARCH
   1.205 +   response described in section 3.5 of [CONDSTORE].
   1.206 +
   1.207 +   If the SEARCH/UID SEARCH command contained a single MIN or MAX result
   1.208 +   option, the MODSEQ result option contains the mod-sequence for the
   1.209 +   found message.  If the SEARCH/UID SEARCH command contained both MIN
   1.210 +   and MAX result options and no ALL/COUNT option, the MODSEQ result
   1.211 +   option contains the highest mod-sequence for the two returned
   1.212 +   messages.  Otherwise the MODSEQ result option contains the highest
   1.213 +   mod-sequence for all messages being returned.
   1.214 +
   1.215 +   Example: The following example demonstrates how Example 15 from
   1.216 +   [CONDSTORE] would look in the presence of one or more result option:
   1.217 +
   1.218 +         C: a1 SEARCH RETURN (MIN) MODSEQ "/flags/\\draft"
   1.219 +             all 620162338
   1.220 +         S: * ESEARCH (TAG "a1") MIN 2 MODSEQ 917162488
   1.221 +         S: a1 OK Search complete
   1.222 +
   1.223 +         C: a2 SEARCH RETURN (MAX) MODSEQ "/flags/\\draft"
   1.224 +             all 620162338
   1.225 +         S: * ESEARCH (TAG "a2") MAX 23 MODSEQ 907162321
   1.226 +
   1.227 +
   1.228 +
   1.229 +Melnikov & Cridland         Standards Track                     [Page 4]
   1.230 +
   1.231 +RFC 4731               IMAP4 Extension to SEARCH           November 2006
   1.232 +
   1.233 +
   1.234 +         S: a2 OK Search complete
   1.235 +
   1.236 +         C: a3 SEARCH RETURN (MIN MAX) MODSEQ "/flags/\\draft"
   1.237 +             all 620162338
   1.238 +         S: * ESEARCH (TAG "a3") MIN 2 MAX 23 MODSEQ 917162488
   1.239 +         S: a3 OK Search complete
   1.240 +
   1.241 +         C: a4 SEARCH RETURN (MIN COUNT) MODSEQ "/flags/\\draft"
   1.242 +             all 620162338
   1.243 +         S: * ESEARCH (TAG "a4") MIN 2 COUNT 10 MODSEQ 917162500
   1.244 +         S: a4 OK Search complete
   1.245 +
   1.246 +4.  Formal Syntax
   1.247 +
   1.248 +   The following syntax specification uses the Augmented Backus-Naur
   1.249 +   Form (ABNF) notation as specified in [ABNF].
   1.250 +
   1.251 +   Non-terminals referenced but not defined below are as defined by
   1.252 +   [IMAP4], [CONDSTORE], or [IMAPABNF].
   1.253 +
   1.254 +   Except as noted otherwise, all alphabetic characters are case-
   1.255 +   insensitive.  The use of upper or lowercase characters to define
   1.256 +   token strings is for editorial clarity only.  Implementations MUST
   1.257 +   accept these strings in a case-insensitive fashion.
   1.258 +
   1.259 +     capability         =/ "ESEARCH"
   1.260 +
   1.261 +     search-return-data = "MIN" SP nz-number /
   1.262 +                          "MAX" SP nz-number /
   1.263 +                          "ALL" SP sequence-set /
   1.264 +                          "COUNT" SP number
   1.265 +                          ;; conforms to the generic
   1.266 +                          ;; search-return-data syntax defined
   1.267 +                          ;; in [IMAPABNF]
   1.268 +
   1.269 +     search-return-opt  = "MIN" / "MAX" / "ALL" / "COUNT"
   1.270 +                          ;; conforms to generic search-return-opt
   1.271 +                          ;; syntax defined in [IMAPABNF]
   1.272 +
   1.273 +     When the CONDSTORE [CONDSTORE] IMAP extension is also supported,
   1.274 +     the ABNF is updated as follows:
   1.275 +
   1.276 +     search-return-data =/ "MODSEQ" SP mod-sequence-value
   1.277 +                          ;; mod-sequence-value is defined
   1.278 +                          ;; in [CONDSTORE]
   1.279 +
   1.280 +
   1.281 +
   1.282 +
   1.283 +
   1.284 +
   1.285 +Melnikov & Cridland         Standards Track                     [Page 5]
   1.286 +
   1.287 +RFC 4731               IMAP4 Extension to SEARCH           November 2006
   1.288 +
   1.289 +
   1.290 +5.  Security Considerations
   1.291 +
   1.292 +   In the general case, the IMAP SEARCH/UID SEARCH commands can be CPU
   1.293 +   and/or IO intensive, and are seen by some as a potential attack point
   1.294 +   for denial of service attacks, so some sites/implementations even
   1.295 +   disable them entirely.  This is quite unfortunate, as SEARCH command
   1.296 +   is one of the best examples demonstrating IMAP advantage over POP3.
   1.297 +
   1.298 +   The ALL and COUNT return options don't change how SEARCH is working
   1.299 +   internally; they only change how information about found messages is
   1.300 +   returned.  MIN and MAX SEARCH result options described in this
   1.301 +   document can lighten the load on IMAP servers that choose to optimize
   1.302 +   SEARCHes containing only one or both of them.
   1.303 +
   1.304 +   It is believed that this extension doesn't raise any additional
   1.305 +   security concerns not already discussed in [IMAP4].
   1.306 +
   1.307 +6.  IANA Considerations
   1.308 +
   1.309 +   IMAP4 capabilities are registered by publishing a standards track RFC
   1.310 +   or an IESG-approved experimental RFC.  The registry is currently
   1.311 +   located at <http://www.iana.org/assignments/imap4-capabilities>.
   1.312 +
   1.313 +   This document defines the ESEARCH IMAP capability, which IANA added
   1.314 +   to the registry.
   1.315 +
   1.316 +7.  Normative References
   1.317 +
   1.318 +   [KEYWORDS]  Bradner, S., "Key words for use in RFCs to Indicate
   1.319 +               Requirement Levels", BCP 14, RFC 2119, March 1997.
   1.320 +
   1.321 +   [IMAP4]     Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
   1.322 +               4rev1", RFC 3501, March 2003.
   1.323 +
   1.324 +   [ABNF]      Crocker, D. (Ed.) and P. Overell , "Augmented BNF for
   1.325 +               Syntax Specifications: ABNF", RFC 4234, October 2005.
   1.326 +
   1.327 +   [IMAPABNF]  Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
   1.328 +               ABNF", RFC 4466, April 2006..
   1.329 +
   1.330 +   [CONDSTORE] Melnikov, A. and S. Hole, "IMAP Extension for Conditional
   1.331 +               STORE", RFC 4551, June 2006.
   1.332 +
   1.333 +8.  Acknowledgments
   1.334 +
   1.335 +   Thanks to Michael Wener, Arnt Gulbrandsen, Cyrus Daboo, Mark Crispin,
   1.336 +   and Pete Maclean for comments and corrections.
   1.337 +
   1.338 +
   1.339 +
   1.340 +
   1.341 +Melnikov & Cridland         Standards Track                     [Page 6]
   1.342 +
   1.343 +RFC 4731               IMAP4 Extension to SEARCH           November 2006
   1.344 +
   1.345 +
   1.346 +Authors' Addresses
   1.347 +
   1.348 +   Alexey Melnikov
   1.349 +   Isode Limited
   1.350 +   5 Castle Business Village
   1.351 +   36 Station Road
   1.352 +   Hampton, Middlesex, TW12 2BX
   1.353 +   UK
   1.354 +
   1.355 +   EMail: Alexey.Melnikov@isode.com
   1.356 +
   1.357 +
   1.358 +   Dave A. Cridland
   1.359 +   Inventure Systems Limited
   1.360 +
   1.361 +   EMail: dave.cridland@inventuresystems.co.uk
   1.362 +   URL: http://invsys.co.uk/dave/
   1.363 +
   1.364 +
   1.365 +
   1.366 +
   1.367 +
   1.368 +
   1.369 +
   1.370 +
   1.371 +
   1.372 +
   1.373 +
   1.374 +
   1.375 +
   1.376 +
   1.377 +
   1.378 +
   1.379 +
   1.380 +
   1.381 +
   1.382 +
   1.383 +
   1.384 +
   1.385 +
   1.386 +
   1.387 +
   1.388 +
   1.389 +
   1.390 +
   1.391 +
   1.392 +
   1.393 +
   1.394 +
   1.395 +
   1.396 +
   1.397 +Melnikov & Cridland         Standards Track                     [Page 7]
   1.398 +
   1.399 +RFC 4731               IMAP4 Extension to SEARCH           November 2006
   1.400 +
   1.401 +
   1.402 +Full Copyright Statement
   1.403 +
   1.404 +   Copyright (C) The IETF Trust (2006).
   1.405 +
   1.406 +   This document is subject to the rights, licenses and restrictions
   1.407 +   contained in BCP 78, and except as set forth therein, the authors
   1.408 +   retain all their rights.
   1.409 +
   1.410 +   This document and the information contained herein are provided on an
   1.411 +   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   1.412 +   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST,
   1.413 +   AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES,
   1.414 +   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT
   1.415 +   THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
   1.416 +   IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
   1.417 +   PURPOSE.
   1.418 +
   1.419 +Intellectual Property
   1.420 +
   1.421 +   The IETF takes no position regarding the validity or scope of any
   1.422 +   Intellectual Property Rights or other rights that might be claimed to
   1.423 +   pertain to the implementation or use of the technology described in
   1.424 +   this document or the extent to which any license under such rights
   1.425 +   might or might not be available; nor does it represent that it has
   1.426 +   made any independent effort to identify any such rights.  Information
   1.427 +   on the procedures with respect to rights in RFC documents can be
   1.428 +   found in BCP 78 and BCP 79.
   1.429 +
   1.430 +   Copies of IPR disclosures made to the IETF Secretariat and any
   1.431 +   assurances of licenses to be made available, or the result of an
   1.432 +   attempt made to obtain a general license or permission for the use of
   1.433 +   such proprietary rights by implementers or users of this
   1.434 +   specification can be obtained from the IETF on-line IPR repository at
   1.435 +   http://www.ietf.org/ipr.
   1.436 +
   1.437 +   The IETF invites any interested party to bring to its attention any
   1.438 +   copyrights, patents or patent applications, or other proprietary
   1.439 +   rights that may cover technology that may be required to implement
   1.440 +   this standard.  Please address the information to the IETF at
   1.441 +   ietf-ipr@ietf.org.
   1.442 +
   1.443 +Acknowledgement
   1.444 +
   1.445 +   Funding for the RFC Editor function is currently provided by the
   1.446 +   Internet Society.
   1.447 +
   1.448 +
   1.449 +
   1.450 +
   1.451 +
   1.452 +
   1.453 +Melnikov & Cridland         Standards Track                     [Page 8]
   1.454 +