doc: Add RFC documents

1 files changed, 563 insertions, 0 deletions

diff --git a/doc/rfc/rfc6237.txt b/doc/rfc/rfc6237.txt
new file mode 100644
index 0000000..b5a3a61
--- /dev/null
+++ b/doc/rfc/rfc6237.txt
@@ -0,0 +1,563 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF)                          B. Leiba
+Request for Comments: 6237                           Huawei Technologies
+Updates: 4466                                                A. Melnikov
+Category: Experimental                                     Isode Limited
+ISSN: 2070-1721                                                 May 2011
+
+
+                  IMAP4 Multimailbox SEARCH Extension
+
+Abstract
+
+   The IMAP4 specification allows the searching of only the selected
+   mailbox.  A user often wants to search multiple mailboxes, and a
+   client that wishes to support this must issue a series of SELECT and
+   SEARCH commands, waiting for each to complete before moving on to the
+   next.  This extension allows a client to search multiple mailboxes
+   with one command, limiting the round trips and waiting for various
+   searches to complete, and not requiring disruption of the currently
+   selected mailbox.  This extension also uses MAILBOX and TAG fields in
+   ESEARCH responses, allowing a client to pipeline the searches if it
+   chooses.  This document updates RFC 4466.
+
+Status of This Memo
+
+   This document is not an Internet Standards Track specification; it is
+   published for examination, experimental implementation, and
+   evaluation.
+
+   This document defines an Experimental Protocol for the Internet
+   community.  This document is a product of the Internet Engineering
+   Task Force (IETF).  It represents the consensus of the IETF
+   community.  It has received public review and has been approved for
+   publication by the Internet Engineering Steering Group (IESG).  Not
+   all documents approved by the IESG are a candidate for any level of
+   Internet Standard; see Section 2 of RFC 5741.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   http://www.rfc-editor.org/info/rfc6237.
+
+
+
+
+
+
+
+
+
+
+
+
+Leiba & Melnikov              Experimental                      [Page 1]
+
+RFC 6237           IMAP4 Multimailbox SEARCH Extension          May 2011
+
+
+Copyright Notice
+
+   Copyright (c) 2011 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents
+   (http://trustee.ietf.org/license-info) in effect on the date of
+   publication of this document.  Please review these documents
+   carefully, as they describe your rights and restrictions with respect
+   to this document.  Code Components extracted from this document must
+   include Simplified BSD License text as described in Section 4.e of
+   the Trust Legal Provisions and are provided without warranty as
+   described in the Simplified BSD License.
+
+Table of Contents
+
+   1. Introduction ....................................................2
+      1.1. Conventions Used in This Document ..........................3
+   2. New ESEARCH Command .............................................3
+      2.1. The ESEARCH Response .......................................4
+      2.2. Source Options: Specifying Mailboxes to Search .............5
+   3. Examples ........................................................6
+   4. Formal Syntax ...................................................7
+   5. Security Considerations .........................................8
+   6. IANA Considerations .............................................9
+   7. Acknowledgements ................................................9
+   8. Normative References ............................................9
+
+1.  Introduction
+
+   The IMAP4 specification allows the searching of only the selected
+   mailbox.  A user often wants to search multiple mailboxes, and a
+   client that wishes to support this must issue a series of SELECT and
+   SEARCH commands, waiting for each to complete before moving on to the
+   next.  The commands can't be pipelined, because the server might run
+   them in parallel, and the untagged SEARCH responses could not then be
+   distinguished from each other.
+
+   This extension allows a client to search multiple mailboxes with one
+   command, and includes MAILBOX and TAG fields in the ESEARCH response,
+   yielding the following advantages:
+
+   o  A single command limits the number of round trips needed to search
+      a set of mailboxes.
+
+   o  A single command eliminates the need to wait for one search to
+      complete before starting the next.
+
+
+
+Leiba & Melnikov              Experimental                      [Page 2]
+
+RFC 6237           IMAP4 Multimailbox SEARCH Extension          May 2011
+
+
+   o  A single command allows the server to optimize the search, if it
+      can.
+
+   o  A command that is not dependent upon the selected mailbox
+      eliminates the need to disrupt the selection state or to open
+      another IMAP connection.
+
+   o  The MAILBOX, UIDVALIDITY, and TAG fields in the responses allow a
+      client to distinguish which responses go with which search (and
+      which mailbox).  A client can safely pipeline these search
+      commands without danger of confusion.  The addition of the MAILBOX
+      and UIDVALIDITY fields updates the search-correlator item defined
+      in [RFC4466].
+
+1.1.  Conventions Used in This Document
+
+   In examples, "C:" indicates lines sent by a client that is connected
+   to a server.  "S:" indicates lines sent by the server to the client.
+
+   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 [RFC2119].
+
+2.  New ESEARCH Command
+
+   Arguments:  OPTIONAL source options
+               OPTIONAL result options
+               OPTIONAL charset specification (see [RFC2978])
+               searching criteria (one or more)
+
+   Responses:  REQUIRED untagged response: ESEARCH
+
+   Result:     OK -- search completed
+               NO -- error: cannot search that charset or criteria
+               BAD -- command unknown or arguments invalid
+
+   This section defines a new ESEARCH command, which works similarly to
+   the UID SEARCH command described in Section 2.6.1 of [RFC4466]
+   (initially described in Section 6.4.4 of [RFC3501] and extended by
+   [RFC4731]).
+
+   The ESEARCH command further extends searching by allowing for
+   optional source and result options.  This document does not define
+   any new result options (see Section 3.1 of [RFC4731]).  A server that
+   supports this extension includes "MULTISEARCH" in its IMAP capability
+   string.
+
+
+
+
+
+Leiba & Melnikov              Experimental                      [Page 3]
+
+RFC 6237           IMAP4 Multimailbox SEARCH Extension          May 2011
+
+
+   Because there has been confusion about this, it is worth pointing out
+   that with ESEARCH, as with *any* SEARCH or UID SEARCH command, it
+   MUST NOT be considered an error if the search terms include a range
+   of message numbers that extends (or, in fact, starts) beyond the end
+   of the mailbox.  For example, a client might want to establish a
+   rolling window through the search results this way:
+
+   C: tag1 UID ESEARCH FROM "frobozz" 1:100
+
+   ...followed later by this:
+
+   C: tag1 UID ESEARCH FROM "frobozz" 101:200
+
+   ...and so on.  This tells the server to match only the first hundred
+   messages in the mailbox the first time, the second hundred the second
+   time, etc.  In fact, it might likely allow the server to optimize the
+   search significantly.  In the above example, whether the mailbox
+   contains 50 or 150 or 250 messages, neither of the search commands
+   shown will result in an error.  It is up to the client to know when
+   to stop moving its search window.
+
+2.1.  The ESEARCH Response
+
+   In response to an ESEARCH command, the server MUST return ESEARCH
+   responses [RFC4731] (that is, not SEARCH responses).  Because message
+   numbers are not useful for mailboxes that are not selected, the
+   responses MUST contain information about UIDs, not message numbers.
+   This is true even if the source options specify that only the
+   selected mailbox be searched.
+
+   Presence of a source option in the absence of a result option implies
+   the "ALL" result option (see Section 3.1 of [RFC4731]).  Note that
+   this is not the same as the result from the SEARCH command described
+   in the IMAP base protocol [RFC3501].
+
+   Source options describe which mailboxes must be searched for
+   messages.  An ESEARCH command with source options does not affect
+   which mailbox, if any, is currently selected, regardless of which
+   mailboxes are searched.
+
+   For each mailbox satisfying the source options, a single ESEARCH
+   response MUST be returned if any messages in that mailbox match the
+   search criteria.  An ESEARCH response MUST NOT be returned for
+   mailboxes that contain no matching messages.  This is true even when
+   result options such as MIN, MAX, and COUNT are specified (see
+   Section 3.1 of [RFC4731]), and the values returned (lowest UID
+   matched, highest UID matched, and number of messages matched,
+   respectively) apply to the mailbox reported in that ESEARCH response.
+
+
+
+Leiba & Melnikov              Experimental                      [Page 4]
+
+RFC 6237           IMAP4 Multimailbox SEARCH Extension          May 2011
+
+
+   Note that it is possible for an ESEARCH command to return *no*
+   untagged responses (no ESEARCH responses at all), in the case that
+   there are no matches to the search in any of the mailboxes that
+   satisfy the source options.  Clients can detect this situation by
+   finding the tagged OK response without having received any matching
+   untagged ESEARCH responses.
+
+   Each ESEARCH response MUST contain the MAILBOX, TAG, and UIDVALIDITY
+   correlators.  Correlators allow clients to issue several ESEARCH
+   commands at once (pipelined).  If the SEARCHRES [RFC5182] extension
+   is used in an ESEARCH command, that ESEARCH command MUST be executed
+   by the server after all previous SEARCH/ESEARCH commands have
+   completed and before any subsequent SEARCH/ESEARCH commands are
+   executed.  The server MAY perform consecutive ESEARCH commands in
+   parallel as long as none of them use the SEARCHRES extension.
+
+2.2.  Source Options: Specifying Mailboxes to Search
+
+   The source options, if present, MUST contain a mailbox specifier as
+   defined in the IMAP NOTIFY extension [RFC5465], Section 6 (using the
+   "filter-mailboxes" ABNF item), with the following differences:
+
+   1.  The "selected-delayed" specifier is not valid here.
+
+   2.  A "subtree-one" specifier is added.  The "subtree" specifier
+       results in a search of the specified mailbox and all selectable
+       mailboxes that are subordinate to it, through an indefinitely
+       deep hierarchy.  The "subtree-one" specifier results in a search
+       of the specified mailbox and all selectable child mailboxes, one
+       hierarchy level down.
+
+   If "subtree" is specified, the server MUST defend against loops in
+   the hierarchy (for example, those caused by recursive file-system
+   links within the message store).  The server SHOULD do this by
+   keeping track of the mailboxes that have been searched, and
+   terminating the hierarchy traversal when a repeat is found.  If it
+   cannot do that, it MAY do it by limiting the hierarchy depth.
+
+   If the source options are not present, the value "selected" is
+   assumed -- that is, only the currently selected mailbox is searched.
+
+   The "personal" source option is a particularly convenient way to
+   search all of the current user's mailboxes.  Note that there is no
+   way to use wildcard characters to search all mailboxes; the
+   "mailboxes" source option does not do wildcard expansion.
+
+
+
+
+
+
+Leiba & Melnikov              Experimental                      [Page 5]
+
+RFC 6237           IMAP4 Multimailbox SEARCH Extension          May 2011
+
+
+   If the source options include (or default to) "selected", the IMAP
+   session MUST be in "selected" state.  If the source options specify
+   other mailboxes and NOT "selected", then the IMAP session MUST be in
+   either "selected" or "authenticated" state.  If the session is not in
+   a correct state, the ESEARCH command MUST return a "BAD" result.
+
+   If the server supports the SEARCHRES [RFC5182] extension, then the
+   "SAVE" result option is valid *only* if "selected" is specified or
+   defaulted as the sole mailbox to be searched.  If any source option
+   other than "selected" is specified, the ESEARCH command MUST return a
+   "BAD" result.
+
+   If the server supports the CONTEXT=SEARCH and/or CONTEXT=SORT
+   extension [RFC5267], then the following additional rules apply:
+
+   o  The CONTEXT return option (Section 4.2 of [RFC5267]) can be used
+      with an ESEARCH command.
+
+   o  If the UPDATE return option is used (Section 4.3 of [RFC5267]), it
+      MUST apply ONLY to the currently selected mailbox.  If UPDATE is
+      used and there is no mailbox currently selected, the ESEARCH
+      command MUST return a "BAD" result.
+
+   o  The PARTIAL search return option (Section 4.4 of [RFC5267]) can be
+      used and applies to each mailbox searched by the ESEARCH command.
+
+   If the server supports the Access Control List (ACL) [RFC4314]
+   extension, then the logged-in user is required to have the "r" right
+   for each mailbox she wants to search.  In addition, any mailboxes
+   that are not explicitly named (accessed through "personal" or
+   "subtree", for example) are required to have the "l" right.
+   Mailboxes matching the source options for which the logged-in user
+   lacks sufficient rights MUST be ignored by the ESEARCH command
+   processing.  In particular, ESEARCH responses MUST NOT be returned
+   for those mailboxes.
+
+3.  Examples
+
+   In the following example, note that two ESEARCH commands are
+   pipelined, and that the server is running them in parallel,
+   interleaving a response to the second search amid the responses to
+   the first (watch the tags).
+
+   C: tag1 ESEARCH IN (mailboxes "folder1" subtree "folder2") unseen
+   C: tag2 ESEARCH IN (mailboxes "folder1" subtree-one "folder2")
+   subject "chad"
+   S: * ESEARCH (TAG "tag1" MAILBOX "folder1" UIDVALIDITY 1) UID ALL
+   4001,4003,4005,4007,4009
+
+
+
+Leiba & Melnikov              Experimental                      [Page 6]
+
+RFC 6237           IMAP4 Multimailbox SEARCH Extension          May 2011
+
+
+   S: * ESEARCH (TAG "tag2" MAILBOX "folder1" UIDVALIDITY 1) UID ALL
+   3001:3004,3788
+   S: * ESEARCH (TAG "tag1" MAILBOX "folder2/banana" UIDVALIDITY 503)
+   UID ALL 3002,4004
+   S: * ESEARCH (TAG "tag1" MAILBOX "folder2/peach" UIDVALIDITY 3) UID
+   ALL 921691
+   S: tag1 OK done
+   S: * ESEARCH (TAG "tag2" MAILBOX "folder2/salmon" UIDVALIDITY
+   1111111) UID ALL 50003,50006,50009,50012
+   S: tag2 OK done
+
+4.  Formal Syntax
+
+   The following syntax specification uses the Augmented Backus-Naur
+   Form (ABNF) as described in [RFC5234].  Terms not defined here are
+   taken from [RFC3501], [RFC5465], or [RFC4466].
+
+   command-auth =/  esearch
+           ; Update definition from IMAP base [RFC3501].
+           ; Add new "esearch" command.
+
+   command-select =/  esearch
+           ; Update definition from IMAP base [RFC3501].
+           ; Add new "esearch" command.
+
+   filter-mailboxes-other =/  ("subtree-one" SP one-or-more-mailbox)
+           ; Update definition from IMAP Notify [RFC5465].
+           ; Add new "subtree-one" selector.
+
+   filter-mailboxes-selected =  "selected"
+           ; Update definition from IMAP Notify [RFC5465].
+           ; We forbid the use of "selected-delayed".
+
+   one-correlator =  ("TAG" SP tag-string) / ("MAILBOX" SP astring) /
+           ("UIDVALIDITY" SP nz-number)
+           ; Each correlator MUST appear exactly once.
+
+   scope-option =  scope-option-name [SP scope-option-value]
+           ; No options defined here.  Syntax for future extensions.
+
+   scope-option-name =  tagged-ext-label
+           ; No options defined here.  Syntax for future extensions.
+
+   scope-option-value =  tagged-ext-val
+           ; No options defined here.  Syntax for future extensions.
+
+
+
+
+
+
+Leiba & Melnikov              Experimental                      [Page 7]
+
+RFC 6237           IMAP4 Multimailbox SEARCH Extension          May 2011
+
+
+   scope-options =  scope-option *(SP scope-option)
+           ; A given option may only appear once.
+           ; No options defined here.  Syntax for future extensions.
+
+   esearch =  "ESEARCH" [SP esearch-source-opts]
+           [SP search-return-opts] SP search-program
+
+   search-correlator =  SP "(" one-correlator *(SP one-correlator) ")"
+           ; Updates definition in IMAP4 ABNF [RFC4466].
+
+   esearch-source-opts =  "IN" SP "(" source-mbox [SP
+           "(" scope-options ")"] ")"
+
+   source-mbox =  filter-mailboxes *(SP filter-mailboxes)
+           ; "filter-mailboxes" is defined in IMAP Notify [RFC5465].
+           ; See updated definition of filter-mailboxes-other, above.
+           ; See updated definition of filter-mailboxes-selected, above.
+
+5.  Security Considerations
+
+   This new IMAP ESEARCH command allows a single command to search many
+   mailboxes at once.  On the one hand, a client could do that by
+   sending many IMAP SEARCH commands.  On the other hand, this makes it
+   easier for a client to overwork a server, by sending a single command
+   that results in an expensive search of tens of thousands of
+   mailboxes.  Server implementations need to be aware of that, and
+   provide mechanisms that prevent a client from adversely affecting
+   other users.  Limitations on the number of mailboxes that may be
+   searched in one command, and/or on the server resources that will be
+   devoted to responding to a single client, are reasonable limitations
+   for an implementation to impose.
+
+   Implementations MUST, of course, apply access controls appropriately,
+   limiting a user's access to ESEARCH in the same way its access is
+   limited for any other IMAP commands.  This extension has no data-
+   access risks beyond what may be there in the unextended IMAP
+   implementation.
+
+   Mailboxes matching the source options for which the logged-in user
+   lacks sufficient rights MUST be ignored by the ESEARCH command
+   processing (see the paragraph about this in Section 2.2).  In
+   particular, any attempt to distinguish insufficient access from
+   non-existent mailboxes may expose information about the mailbox
+   hierarchy that isn't otherwise available to the client.
+
+   If "subtree" is specified, the server MUST defend against loops in
+   the hierarchy (see the paragraph about this in Section 2.2).
+
+
+
+
+Leiba & Melnikov              Experimental                      [Page 8]
+
+RFC 6237           IMAP4 Multimailbox SEARCH Extension          May 2011
+
+
+6.  IANA Considerations
+
+   IMAP4 capabilities are registered by publishing a Standards Track or
+   IESG-approved Experimental RFC.  The "IMAP 4 Capabilities" registry
+   is currently located here:
+
+      http://www.iana.org/
+
+   This document defines the IMAP capability "MULTISEARCH", and IANA has
+   added it to the registry.
+
+7.  Acknowledgements
+
+   The authors gratefully acknowledge feedback provided by Timo
+   Sirainen, Peter Coates, and Arnt Gulbrandsen.
+
+8.  Normative References
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+   [RFC2978]  Freed, N. and J. Postel, "IANA Charset Registration
+              Procedures", BCP 19, RFC 2978, October 2000.
+
+   [RFC3501]  Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
+              4rev1", RFC 3501, March 2003.
+
+   [RFC4314]  Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
+              RFC 4314, December 2005.
+
+   [RFC4466]  Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
+              ABNF", RFC 4466, April 2006.
+
+   [RFC4731]  Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH
+              Command for Controlling What Kind of Information Is
+              Returned", RFC 4731, November 2006.
+
+   [RFC5182]  Melnikov, A., "IMAP Extension for Referencing the Last
+              SEARCH Result", RFC 5182, March 2008.
+
+   [RFC5234]  Crocker, D., Ed., and P. Overell, "Augmented BNF for
+              Syntax Specifications: ABNF", STD 68, RFC 5234,
+              January 2008.
+
+   [RFC5267]  Cridland, D. and C. King, "Contexts for IMAP4", RFC 5267,
+              July 2008.
+
+
+
+
+
+Leiba & Melnikov              Experimental                      [Page 9]
+
+RFC 6237           IMAP4 Multimailbox SEARCH Extension          May 2011
+
+
+   [RFC5465]  Gulbrandsen, A., King, C., and A. Melnikov, "The IMAP
+              NOTIFY Extension", RFC 5465, February 2009.
+
+Authors' Addresses
+
+   Barry Leiba
+   Huawei Technologies
+
+   Phone: +1 646 827 0648
+   EMail: barryleiba@computer.org
+   URI:   http://internetmessagingtechnology.org/
+
+
+   Alexey Melnikov
+   Isode Limited
+   5 Castle Business Village
+   36 Station Road
+   Hampton, Middlesex  TW12 2BX
+   UK
+
+   EMail: Alexey.Melnikov@isode.com
+   URI:   http://www.melnikov.ca/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Leiba & Melnikov              Experimental                     [Page 10]
+