summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc3348.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc3348.txt')
-rw-r--r--doc/rfc/rfc3348.txt339
1 files changed, 339 insertions, 0 deletions
diff --git a/doc/rfc/rfc3348.txt b/doc/rfc/rfc3348.txt
new file mode 100644
index 0000000..500871c
--- /dev/null
+++ b/doc/rfc/rfc3348.txt
@@ -0,0 +1,339 @@
+
+
+
+
+
+
+Network Working Group M. Gahrns
+Request for Comments: 3348 R. Cheng
+Category: Informational Microsoft
+ July 2002
+
+
+ The Internet Message Action Protocol (IMAP4)
+ Child Mailbox Extension
+
+Status of this Memo
+
+ This memo provides information for the Internet community. It does
+ not specify an Internet standard of any kind. Distribution of this
+ memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+Abstract
+
+ The Internet Message Action Protocol (IMAP4) CHILDREN extension
+ provides a mechanism for a client to efficiently determine if a
+ particular mailbox has children, without issuing a LIST "" * or a
+ LIST "" % for each mailbox.
+
+1. Conventions used in this document
+
+ In examples, "C:" and "S:" indicate lines sent by the client and
+ server respectively. If such lines are wrapped without a new "C:" or
+ "S:" label, then the wrapping is for editorial clarity and is not
+ part of the command.
+
+ 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].
+
+2. Introduction and Overview
+
+ Many IMAP4 [RFC-2060] clients present to the user a hierarchical view
+ of the mailboxes that a user has access to. Rather than initially
+ presenting to the user the entire mailbox hierarchy, it is often
+ preferable to show to the user a collapsed outline list of the
+ mailbox hierarchy (particularly if there is a large number of
+ mailboxes). The user can then expand the collapsed outline hierarchy
+ as needed. It is common to include within the collapsed hierarchy a
+
+
+
+
+
+Gahrns, et al. Informational [Page 1]
+
+RFC 3348 IMAP4 Child Mailbox Extension July 2002
+
+
+ visual clue (such as a "+") to indicate that there are child
+ mailboxes under a particular mailbox. When the visual clue is
+ clicked the hierarchy list is expanded to show the child mailboxes.
+
+ Several IMAP vendors implemented this proposal, and it is proposed to
+ document this behavior and functionality as an Informational RFC.
+
+ There is interest in addressing the general extensibility of the IMAP
+ LIST command through an IMAP LIST Extension draft. Similar
+ functionality to the \HasChildren and \HasNoChildren flags could be
+ incorporated into this new LIST Extension. It is proposed that the
+ more general LIST Extension draft proceed on the standards track with
+ this proposal being relegated to informational status only.
+
+ If the functionality of the \HasChildren and \HasNoChildren flags
+ were incorporated into a more general LIST extension, this would have
+ the advantage that a client could then have the opportunity to
+ request whether or not the server should return this information.
+ This would be an advantage over the current draft for servers where
+ this information is expensive to compute, since the server would only
+ need to compute the information when it knew that the client
+ requesting the information was able to consume it.
+
+3. Requirements
+
+ IMAP4 servers that support this extension MUST list the keyword
+ CHILDREN in their CAPABILITY response.
+
+ The CHILDREN extension defines two new attributes that MAY be
+ returned within a LIST response.
+
+ \HasChildren - The presence of this attribute indicates that the
+ mailbox has child mailboxes.
+
+ Servers SHOULD NOT return \HasChildren if child mailboxes exist, but
+ none will be displayed to the current user in a LIST response (as
+ should be the case where child mailboxes exist, but a client does not
+ have permissions to access them.) In this case, \HasNoChildren
+ SHOULD be used.
+
+ In many cases, however, a server may not be able to efficiently
+ compute whether a user has access to all child mailboxes, or multiple
+ users may be accessing the same account and simultaneously changing
+ the mailbox hierarchy. As such a client MUST be prepared to accept
+ the \HasChildren attribute as a hint. That is, a mailbox MAY be
+ flagged with the \HasChildren attribute, but no child mailboxes will
+ appear in a subsequent LIST response.
+
+
+
+
+Gahrns, et al. Informational [Page 2]
+
+RFC 3348 IMAP4 Child Mailbox Extension July 2002
+
+
+ Example 3.1:
+ ============
+
+ /*** Consider a server that has the following mailbox hierarchy:
+
+ INBOX
+ ITEM_1
+ ITEM_1A
+ ITEM_2
+ TOP_SECRET
+
+ Where INBOX, ITEM_1 and ITEM_2 are top level mailboxes. ITEM_1A is a
+ child mailbox of ITEM_1 and TOP_SECRET is a child mailbox of ITEM_2
+ that the currently logged on user does NOT have access to.
+
+ Note that in this case, the server is not able to efficiently compute
+ access rights to child mailboxes and responds with a \HasChildren
+ attribute for mailbox ITEM_2, even though ITEM_2/TOP_SECRET does not
+ appear in the list response. ***/
+
+ C: A001 LIST "" *
+ S: * LIST (\HasNoChildren) "/" INBOX
+ S: * LIST (\HasChildren) "/" ITEM_1
+ S: * LIST (\HasNoChildren) "/" ITEM_1/ITEM_1A
+ S: * LIST (\HasChildren) "/" ITEM_2
+ S: A001 OK LIST Completed
+
+ \HasNoChildren - The presence of this attribute indicates that the
+ mailbox has NO child mailboxes that are accessible to the currently
+ authenticated user. If a mailbox has the \Noinferiors attribute, the
+ \HasNoChildren attribute is redundant and SHOULD be omitted in the
+ LIST response.
+
+ In some instances a server that supports the CHILDREN extension MAY
+ NOT be able to determine whether a mailbox has children. For example
+ it may have difficulty determining whether there are child mailboxes
+ when LISTing mailboxes while operating in a particular namespace.
+
+ In these cases, a server MAY exclude both the \HasChildren and
+ \HasNoChildren attributes in the LIST response. As such, a client
+ can not make any assumptions about whether a mailbox has children
+ based upon the absence of a single attribute.
+
+ It is an error for the server to return both a \HasChildren and a
+ \HasNoChildren attribute in a LIST response.
+
+
+
+
+
+
+Gahrns, et al. Informational [Page 3]
+
+RFC 3348 IMAP4 Child Mailbox Extension July 2002
+
+
+ It is an error for the server to return both a \HasChildren and a
+ \NoInferiors attribute in a LIST response.
+
+ Note: the \HasNoChildren attribute should not be confused with the
+ IMAP4 [RFC-2060] defined attribute \Noinferiors which indicates that
+ no child mailboxes exist now and none can be created in the future.
+
+ The \HasChildren and \HasNoChildren attributes might not be returned
+ in response to a LSUB response. Many servers maintain a simple
+ mailbox subscription list that is not updated when the underlying
+ mailbox structure is changed. A client MUST NOT assume that
+ hierarchy information will be maintained in the subscription list.
+
+ RLIST is a command defined in [RFC-2193] that includes in a LIST
+ response mailboxes that are accessible only via referral. That is, a
+ client must explicitly issue an RLIST command to see a list of these
+ mailboxes. Thus in the case where a mailbox has child mailboxes that
+ are available only via referral, the mailboxes would appear as
+ \HasNoChildren in response to the LIST command, and \HasChildren in
+ response to the RLIST command.
+
+5. Formal Syntax
+
+ The following syntax specification uses the augmented Backus-Naur
+ Form (BNF) as described in [ABNF].
+
+ Two new mailbox attributes are defined as flag_extensions to the
+ IMAP4 mailbox_list response:
+
+ HasChildren = "\HasChildren"
+
+ HasNoChildren = "\HasNoChildren"
+
+6. Security Considerations
+
+ This extension provides a client a more efficient means of
+ determining whether a particular mailbox has children. If a mailbox
+ has children, but the currently authenticated user does not have
+ access to any of them, the server SHOULD respond with a
+ \HasNoChildren attribute. In many cases, however, a server may not
+ be able to efficiently compute whether a user has access to all child
+ mailboxes. If such a server responds with a \HasChildren attribute,
+ when in fact the currently authenticated user does not have access to
+ any child mailboxes, potentially more information is conveyed about
+ the mailbox than intended. A server designed with such levels of
+ security in mind SHOULD NOT attach the \HasChildren attribute to a
+ mailbox unless the server is certain that the user has access to at
+ least one of the child mailboxes.
+
+
+
+Gahrns, et al. Informational [Page 4]
+
+RFC 3348 IMAP4 Child Mailbox Extension July 2002
+
+
+7. References
+
+ [RFC-2060] Crispin, M., "Internet Message Access Protocol - Version
+ 4rev1", RFC 2060, December 1996.
+
+ [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC-2234] Crocker, D. and P. Overell, Editors, "Augmented BNF for
+ Syntax Specifications: ABNF", RFC 2234, November 1997.
+
+ [RFC-2193] Gahrns, M., "IMAP4 Mailbox Referrals", RFC 2193, September
+ 1997.
+
+8. Acknowledgments
+
+ The authors would like to thank the participants of several IMC Mail
+ Connect events for their input when this idea was originally
+ presented and refined.
+
+9. Author's Address
+
+ Mike Gahrns
+ Microsoft
+ One Microsoft Way
+ Redmond, WA, 98052
+ Phone: (425) 936-9833
+ EMail: mikega@microsoft.com
+
+ Raymond Cheng
+ Microsoft
+ One Microsoft Way
+ Redmond, WA, 98052
+ Phone: (425) 703-4913
+ EMail: raych@microsoft.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Gahrns, et al. Informational [Page 5]
+
+RFC 3348 IMAP4 Child Mailbox Extension July 2002
+
+
+10. Full Copyright Statement
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Gahrns, et al. Informational [Page 6]
+