1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/rfc/rfc3348.txt	Mon Sep 14 15:17:45 2009 +0900
     1.3 @@ -0,0 +1,339 @@
     1.4 +
     1.5 +
     1.6 +
     1.7 +
     1.8 +
     1.9 +
    1.10 +Network Working Group                                          M. Gahrns
    1.11 +Request for Comments: 3348                                      R. Cheng
    1.12 +Category: Informational                                        Microsoft
    1.13 +                                                               July 2002
    1.14 +
    1.15 +
    1.16 +             The Internet Message Action Protocol (IMAP4)
    1.17 +                        Child Mailbox Extension
    1.18 +
    1.19 +Status of this Memo
    1.20 +
    1.21 +   This memo provides information for the Internet community.  It does
    1.22 +   not specify an Internet standard of any kind.  Distribution of this
    1.23 +   memo is unlimited.
    1.24 +
    1.25 +Copyright Notice
    1.26 +
    1.27 +   Copyright (C) The Internet Society (2002).  All Rights Reserved.
    1.28 +
    1.29 +Abstract
    1.30 +
    1.31 +   The Internet Message Action Protocol (IMAP4) CHILDREN extension
    1.32 +   provides a mechanism for a client to efficiently determine if a
    1.33 +   particular mailbox has children, without issuing a LIST "" * or a
    1.34 +   LIST "" % for each mailbox.
    1.35 +
    1.36 +1. Conventions used in this document
    1.37 +
    1.38 +   In examples, "C:" and "S:" indicate lines sent by the client and
    1.39 +   server respectively.  If such lines are wrapped without a new "C:" or
    1.40 +   "S:" label, then the wrapping is for editorial clarity and is not
    1.41 +   part of the command.
    1.42 +
    1.43 +   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
    1.44 +   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this
    1.45 +   document are to be interpreted as described in [RFC-2119].
    1.46 +
    1.47 +2. Introduction and Overview
    1.48 +
    1.49 +   Many IMAP4 [RFC-2060] clients present to the user a hierarchical view
    1.50 +   of the mailboxes that a user has access to.  Rather than initially
    1.51 +   presenting to the user the entire mailbox hierarchy, it is often
    1.52 +   preferable to show to the user a collapsed outline list of the
    1.53 +   mailbox hierarchy (particularly if there is a large number of
    1.54 +   mailboxes).  The user can then expand the collapsed outline hierarchy
    1.55 +   as needed.  It is common to include within the collapsed hierarchy a
    1.56 +
    1.57 +
    1.58 +
    1.59 +
    1.60 +
    1.61 +Gahrns, et al.               Informational                      [Page 1]
    1.62 +
    1.63 +RFC 3348             IMAP4 Child Mailbox Extension             July 2002
    1.64 +
    1.65 +
    1.66 +   visual clue (such as a "+") to indicate that there are child
    1.67 +   mailboxes under a particular mailbox.  When the visual clue is
    1.68 +   clicked the hierarchy list is expanded to show the child mailboxes.
    1.69 +
    1.70 +   Several IMAP vendors implemented this proposal, and it is proposed to
    1.71 +   document this behavior and functionality as an Informational RFC.
    1.72 +
    1.73 +   There is interest in addressing the general extensibility of the IMAP
    1.74 +   LIST command through an IMAP LIST Extension draft.  Similar
    1.75 +   functionality to the \HasChildren and \HasNoChildren flags could be
    1.76 +   incorporated into this new LIST Extension.  It is proposed that the
    1.77 +   more general LIST Extension draft proceed on the standards track with
    1.78 +   this proposal being relegated to informational status only.
    1.79 +
    1.80 +   If the functionality of the \HasChildren and \HasNoChildren flags
    1.81 +   were incorporated into a more general LIST extension, this would have
    1.82 +   the advantage that a client could then have the opportunity to
    1.83 +   request whether or not the server should return this information.
    1.84 +   This would be an advantage over the current draft for servers where
    1.85 +   this information is expensive to compute, since the server would only
    1.86 +   need to compute the information when it knew that the client
    1.87 +   requesting the information was able to consume it.
    1.88 +
    1.89 +3. Requirements
    1.90 +
    1.91 +   IMAP4 servers that support this extension MUST list the keyword
    1.92 +   CHILDREN in their CAPABILITY response.
    1.93 +
    1.94 +   The CHILDREN extension defines two new attributes that MAY be
    1.95 +   returned within a LIST response.
    1.96 +
    1.97 +   \HasChildren - The presence of this attribute indicates that the
    1.98 +   mailbox has child mailboxes.
    1.99 +
   1.100 +   Servers SHOULD NOT return \HasChildren if child mailboxes exist, but
   1.101 +   none will be displayed to the current user in a LIST response (as
   1.102 +   should be the case where child mailboxes exist, but a client does not
   1.103 +   have permissions to access them.)  In this case, \HasNoChildren
   1.104 +   SHOULD be used.
   1.105 +
   1.106 +   In many cases, however, a server may not be able to efficiently
   1.107 +   compute whether a user has access to all child mailboxes, or multiple
   1.108 +   users may be accessing the same account and simultaneously changing
   1.109 +   the mailbox hierarchy.  As such a client MUST be prepared to accept
   1.110 +   the \HasChildren attribute as a hint.  That is, a mailbox MAY be
   1.111 +   flagged with the \HasChildren attribute, but no child mailboxes will
   1.112 +   appear in a subsequent LIST response.
   1.113 +
   1.114 +
   1.115 +
   1.116 +
   1.117 +Gahrns, et al.               Informational                      [Page 2]
   1.118 +
   1.119 +RFC 3348             IMAP4 Child Mailbox Extension             July 2002
   1.120 +
   1.121 +
   1.122 +   Example 3.1:
   1.123 +   ============
   1.124 +
   1.125 +   /*** Consider a server that has the following mailbox hierarchy:
   1.126 +
   1.127 +   INBOX
   1.128 +   ITEM_1
   1.129 +      ITEM_1A
   1.130 +   ITEM_2
   1.131 +      TOP_SECRET
   1.132 +
   1.133 +   Where INBOX, ITEM_1 and ITEM_2 are top level mailboxes.  ITEM_1A is a
   1.134 +   child mailbox of ITEM_1 and TOP_SECRET is a child mailbox of ITEM_2
   1.135 +   that the currently logged on user does NOT have access to.
   1.136 +
   1.137 +   Note that in this case, the server is not able to efficiently compute
   1.138 +   access rights to child mailboxes and responds with a \HasChildren
   1.139 +   attribute for mailbox ITEM_2, even though ITEM_2/TOP_SECRET does not
   1.140 +   appear in the list response.  ***/
   1.141 +
   1.142 +   C: A001 LIST "" *
   1.143 +   S: * LIST (\HasNoChildren) "/" INBOX
   1.144 +   S: * LIST (\HasChildren) "/" ITEM_1
   1.145 +   S: * LIST (\HasNoChildren) "/" ITEM_1/ITEM_1A
   1.146 +   S: * LIST (\HasChildren) "/" ITEM_2
   1.147 +   S: A001 OK LIST Completed
   1.148 +
   1.149 +   \HasNoChildren - The presence of this attribute indicates that the
   1.150 +   mailbox has NO child mailboxes that are accessible to the currently
   1.151 +   authenticated user.  If a mailbox has the \Noinferiors attribute, the
   1.152 +   \HasNoChildren attribute is redundant and SHOULD be omitted in the
   1.153 +   LIST response.
   1.154 +
   1.155 +   In some instances a server that supports the CHILDREN extension MAY
   1.156 +   NOT be able to determine whether a mailbox has children.  For example
   1.157 +   it may have difficulty determining whether there are child mailboxes
   1.158 +   when LISTing mailboxes while operating in a particular namespace.
   1.159 +
   1.160 +   In these cases, a server MAY exclude both the \HasChildren and
   1.161 +   \HasNoChildren attributes in the LIST response.  As such, a client
   1.162 +   can not make any assumptions about whether a mailbox has children
   1.163 +   based upon the absence of a single attribute.
   1.164 +
   1.165 +   It is an error for the server to return both a \HasChildren and a
   1.166 +   \HasNoChildren attribute in a LIST response.
   1.167 +
   1.168 +
   1.169 +
   1.170 +
   1.171 +
   1.172 +
   1.173 +Gahrns, et al.               Informational                      [Page 3]
   1.174 +
   1.175 +RFC 3348             IMAP4 Child Mailbox Extension             July 2002
   1.176 +
   1.177 +
   1.178 +   It is an error for the server to return both a \HasChildren and a
   1.179 +   \NoInferiors attribute in a LIST response.
   1.180 +
   1.181 +   Note: the \HasNoChildren attribute should not be confused with the
   1.182 +   IMAP4 [RFC-2060] defined attribute \Noinferiors which indicates that
   1.183 +   no child mailboxes exist now and none can be created in the future.
   1.184 +
   1.185 +   The \HasChildren and \HasNoChildren attributes might not be returned
   1.186 +   in response to a LSUB response.  Many servers maintain a simple
   1.187 +   mailbox subscription list that is not updated when the underlying
   1.188 +   mailbox structure is changed.  A client MUST NOT assume that
   1.189 +   hierarchy information will be maintained in the subscription list.
   1.190 +
   1.191 +   RLIST is a command defined in [RFC-2193] that includes in a LIST
   1.192 +   response mailboxes that are accessible only via referral.  That is, a
   1.193 +   client must explicitly issue an RLIST command to see a list of these
   1.194 +   mailboxes.  Thus in the case where a mailbox has child mailboxes that
   1.195 +   are available only via referral, the mailboxes would appear as
   1.196 +   \HasNoChildren in response to the LIST command, and \HasChildren in
   1.197 +   response to the RLIST command.
   1.198 +
   1.199 +5. Formal Syntax
   1.200 +
   1.201 +   The following syntax specification uses the augmented Backus-Naur
   1.202 +   Form (BNF) as described in [ABNF].
   1.203 +
   1.204 +   Two new mailbox attributes are defined as flag_extensions to the
   1.205 +   IMAP4 mailbox_list response:
   1.206 +
   1.207 +   HasChildren = "\HasChildren"
   1.208 +
   1.209 +   HasNoChildren = "\HasNoChildren"
   1.210 +
   1.211 +6. Security Considerations
   1.212 +
   1.213 +   This extension provides a client a more efficient means of
   1.214 +   determining whether a particular mailbox has children.  If a mailbox
   1.215 +   has children, but the currently authenticated user does not have
   1.216 +   access to any of them, the server SHOULD respond with a
   1.217 +   \HasNoChildren attribute.  In many cases, however, a server may not
   1.218 +   be able to efficiently compute whether a user has access to all child
   1.219 +   mailboxes.  If such a server responds with a \HasChildren attribute,
   1.220 +   when in fact the currently authenticated user does not have access to
   1.221 +   any child mailboxes, potentially more information is conveyed about
   1.222 +   the mailbox than intended.  A server designed with such levels of
   1.223 +   security in mind SHOULD NOT attach the \HasChildren attribute to a
   1.224 +   mailbox unless the server is certain that the user has access to at
   1.225 +   least one of the child mailboxes.
   1.226 +
   1.227 +
   1.228 +
   1.229 +Gahrns, et al.               Informational                      [Page 4]
   1.230 +
   1.231 +RFC 3348             IMAP4 Child Mailbox Extension             July 2002
   1.232 +
   1.233 +
   1.234 +7. References
   1.235 +
   1.236 +   [RFC-2060] Crispin, M., "Internet Message Access Protocol - Version
   1.237 +              4rev1", RFC 2060, December 1996.
   1.238 +
   1.239 +   [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate
   1.240 +              Requirement Levels", BCP 14, RFC 2119, March 1997.
   1.241 +
   1.242 +   [RFC-2234] Crocker, D. and P. Overell, Editors, "Augmented BNF for
   1.243 +              Syntax Specifications: ABNF", RFC 2234, November 1997.
   1.244 +
   1.245 +   [RFC-2193] Gahrns, M., "IMAP4 Mailbox Referrals", RFC 2193, September
   1.246 +              1997.
   1.247 +
   1.248 +8.  Acknowledgments
   1.249 +
   1.250 +   The authors would like to thank the participants of several IMC Mail
   1.251 +   Connect events for their input when this idea was originally
   1.252 +   presented and refined.
   1.253 +
   1.254 +9. Author's Address
   1.255 +
   1.256 +   Mike Gahrns
   1.257 +   Microsoft
   1.258 +   One Microsoft Way
   1.259 +   Redmond, WA, 98052
   1.260 +   Phone: (425) 936-9833
   1.261 +   EMail: mikega@microsoft.com
   1.262 +
   1.263 +   Raymond Cheng
   1.264 +   Microsoft
   1.265 +   One Microsoft Way
   1.266 +   Redmond, WA, 98052
   1.267 +   Phone: (425) 703-4913
   1.268 +   EMail: raych@microsoft.com
   1.269 +
   1.270 +
   1.271 +
   1.272 +
   1.273 +
   1.274 +
   1.275 +
   1.276 +
   1.277 +
   1.278 +
   1.279 +
   1.280 +
   1.281 +
   1.282 +
   1.283 +
   1.284 +
   1.285 +Gahrns, et al.               Informational                      [Page 5]
   1.286 +
   1.287 +RFC 3348             IMAP4 Child Mailbox Extension             July 2002
   1.288 +
   1.289 +
   1.290 +10. Full Copyright Statement
   1.291 +
   1.292 +   Copyright (C) The Internet Society (2002).  All Rights Reserved.
   1.293 +
   1.294 +   This document and translations of it may be copied and furnished to
   1.295 +   others, and derivative works that comment on or otherwise explain it
   1.296 +   or assist in its implementation may be prepared, copied, published
   1.297 +   and distributed, in whole or in part, without restriction of any
   1.298 +   kind, provided that the above copyright notice and this paragraph are
   1.299 +   included on all such copies and derivative works.  However, this
   1.300 +   document itself may not be modified in any way, such as by removing
   1.301 +   the copyright notice or references to the Internet Society or other
   1.302 +   Internet organizations, except as needed for the purpose of
   1.303 +   developing Internet standards in which case the procedures for
   1.304 +   copyrights defined in the Internet Standards process must be
   1.305 +   followed, or as required to translate it into languages other than
   1.306 +   English.
   1.307 +
   1.308 +   The limited permissions granted above are perpetual and will not be
   1.309 +   revoked by the Internet Society or its successors or assigns.
   1.310 +
   1.311 +   This document and the information contained herein is provided on an
   1.312 +   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   1.313 +   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   1.314 +   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   1.315 +   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   1.316 +   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
   1.317 +
   1.318 +Acknowledgement
   1.319 +
   1.320 +   Funding for the RFC Editor function is currently provided by the
   1.321 +   Internet Society.
   1.322 +
   1.323 +
   1.324 +
   1.325 +
   1.326 +
   1.327 +
   1.328 +
   1.329 +
   1.330 +
   1.331 +
   1.332 +
   1.333 +
   1.334 +
   1.335 +
   1.336 +
   1.337 +
   1.338 +
   1.339 +
   1.340 +
   1.341 +Gahrns, et al.               Informational                      [Page 6]
   1.342 +