idnits 2.17.1 draft-ietf-imapext-list-extensions-04.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([MboxRefer]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 2004) is 7369 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2060 (ref. 'IMAP4') (Obsoleted by RFC 3501) ** Obsolete normative reference: RFC 3348 (ref. 'ChildMbox') (Obsoleted by RFC 5258) ** Obsolete normative reference: RFC 2234 (ref. 'ABNF') (Obsoleted by RFC 4234) Summary: 11 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 IMAP Extensions Working Group B. Leiba 2 Internet Draft IBM T.J. Watson Research Center 3 Document: draft-ietf-imapext-list-extensions-04.txt August 2003 4 Expires January 2004 5 IMAP4 LIST Command Extensions 6 Status of this Document 8 This document is an Internet-Draft and is in full conformance with 9 all provisions of Section 10 of RFC2026. Internet-Drafts are working 10 documents of the Internet Engineering Task Force (IETF), its areas, 11 and its working groups. Note that other groups may also distribute 12 working documents as Internet-Drafts. 13 Internet-Drafts are draft documents valid for a maximum of six months 14 and may be updated, replaced, or obsoleted by other documents at any 15 time. It is inappropriate to use Internet-Drafts as reference 16 material or to cite them other than as "work in progress." 18 The list of current Internet-Drafts can be accessed at 19 http://www.ietf.org/ietf/1id-abstracts.txt 20 The list of Internet-Draft Shadow Directories can be accessed at 21 http://www.ietf.org/shadow.html. 23 A revised version of this draft document will be submitted to the RFC 24 editor as an Proposed Standard for the Internet Community. 25 Discussion and suggestions for improvement are requested, and should 26 be sent to ietf-imapext@imc.org. This document will expire before 31 27 January 2004. Distribution of this memo is unlimited. 29 1. Abstract 31 IMAP4 has two commands for listing mailboxes: LIST and LSUB. As we 32 have added extensions that have required specialized lists (see 33 [MboxRefer] for an example) we have had to expand the number of list 34 commands, since each extension must add its function to both LIST and 35 LSUB, and these commands are not, as they are defined, extensible. 36 If we've needed the extensions to work together, we've had to add a 37 set of commands to mix the different options, the set increasing in 38 size with each new extension. This document describes an extension 39 to the base LIST command that will allow these additions to be done 40 with mutually compatible options to the LIST command, avoiding the 41 exponential increase in specialized list commands. 43 Internet DRAFT IMAP4 LIST Command Extensions August 2003 44 2. Conventions used in this document 45 In examples, "C:" indicates lines sent by a client that is connected 46 to a server. "S:" indicates lines sent by the server to the client. 47 The words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are 48 used in this document as specified in RFC 2119 [Keywords]. 49 3. Introduction 50 The extensions to the LIST command will be accomplished by amending 51 the syntax to allow options to be specified. The list of options 52 will replace the several commands that are currently used to mix and 53 match the information requested. The new syntax is backward- 54 compatible, with no ambiguity: if the first word after the command 55 name begins with a parenthesis, the new syntax is being used; if it 56 does not, it's in the original syntax. 57 By adding options to the LIST command, we are announcing the intent 58 to phase out and eventually to deprecate the RLIST and RLSUB commands 59 described in [MboxRefer]. We are also defining the mechanism to 60 request extended mailbox information, such as is described in the 61 now-expired "Child Mailbox Extension" draft [ChildMbox]. The base 62 LSUB command is not deprecated by this extension; rather, this 63 extension adds a way to obtain subscription information with more 64 options, with those server implementations that support it. Clients 65 that simply need a list of subscribed mailboxes, as provided by the 66 LSUB command, SHOULD continue to use that command. 67 4. LIST Command Options 68 The LIST command syntax is extended by adding a parenthesized list of 69 command options between the command name and the reference name (see 70 the formal syntax in section 6 for specific details). Command 71 options will be defined in this document and in approved extension 72 documents; each option will be enabled by a capability string (one 73 capability may enable multiple options), and a client MUST NOT send 74 an option for which the server has not advertised support. A server 75 MUST respond to options it does not recognize with a NO response. 76 This extension is identified by the capability string "LISTEXT", and 77 support for it is a prerequisite for any future extensions that 78 require specialized forms of the LIST command. Such extensions MUST 79 refer to this document and MUST add their function through command 80 options as described herein. This document also defines the "LIST- 81 Internet DRAFT IMAP4 LIST Command Extensions August 2003 82 SUBSCRIBED" capability string; see the "SUBSCRIBED" option below. 83 This extension also defines extensions to the LIST response, allowing 84 a series of extended fields at the end, a parenthesized list of 85 attriobute/value pairs. Each attribute is a string, each value may 86 be a string or a nested parenthesized list of the same 87 attribute/value pairs. An example of this extended set might be 88 (("ACL" (("id" "user=fred")("rights" "rwi")))("X-Sample" 89 "text")) 90 or... 91 (("ACL" ("user=fred" "rwi"))("X-Sample" "text")) 92 See the formal grammar, below, for the full syntatic details. 93 The options defined in this specification are 94 SUBSCRIBED - causes the LIST command to list subscribed 95 mailboxes, rather than the actual mailboxes. This will often 96 be a subset of the actual mailboxes. It's also possible for 97 this list to contain the names of mailboxes that don't exist. 98 In any case, the list MUST include exactly those mailbox names 99 that match the selection criteria and are subscribed to. This 100 option is intended to supplement the LSUB command, and support 101 for it is optional -- a server that supports the SUBSCRIBED 102 option indicates so through the LIST-SUBSCRIBED capability. 103 Of particular note are the mailbox flags as returned by this 104 option, compared with what is returned by LSUB. With the 105 latter, the flags returned may not reflect the actual flag 106 status on the mailbox, and the \NoSelect flag has a special 107 meaning (it indicates that this mailbox is not, itself, 108 subscribed, but that it has child mailboxes that are). With 109 the SUBSCRIBED option described here, the flags are accurate 110 and complete, and have no special meanings. 111 "LSUB" and "LIST (SUBSCRIBED)" are, thus, not the same thing, 112 and some servers must do significant extra work to respond to 113 "LIST (SUBSCRIBED)". Because of this, clients SHOULD continue 114 to use "LSUB" unless they specifically want the additional 115 information offered by "LIST (SUBSCRIBED)". At the same time, 116 servers SHOULD support the LIST-SUBSCRIBED capability even if 117 it entails extra work, because a client that wants the 118 information will still obtain it by using LSUB followed by a 119 series of LIST commands, so servers might as well make it 120 easier. 121 This option defines a new mailbox flag, "\NonExistent", that 122 indicates that a mailbox is subscribed to, but does not 123 actually exist. The "\NonExistent" flag MUST be supported and 124 MUST be accurately computed. 126 Internet DRAFT IMAP4 LIST Command Extensions August 2003 127 REMOTE - causes the LIST command to show remote mailboxes as 128 well as local ones, as described in [MboxRefer]. This option 129 is intended to replace the RLIST command and, in conjunction 130 with the SUBSCRIBED option, the RLSUB command. This option is 131 only available on servers that also support RFC-2193. 132 CHILDREN - Requests mailbox child information as originally 133 proposed in [ChildMbox]. See section 5, below, for details. 134 Support for this is optional, but this option MUST be accepted 135 by all servers (though it MAY be ignored). 136 The LISTEXT capability also defines a new mailbox flag, 137 "\PlaceHolder", that indicates that the designated mailbox does not 138 meet the selection criteria of the given LIST command, but that it 139 has one or more child mailboxes that do [EDITORIAL NOTE: "might"?]. 140 The LSUB command indicates this condition by using the "\NoSelect" 141 flag, but the LIST (SUBSCRIBED) command MUST NOT do that, since 142 "\NoSelect" retains its original meaning here. Further, the 143 "\PlaceHolder" flag is more general, in that it can be used with any 144 extended set of selection criteria. 145 5. The CHILDREN Option 146 The CHILDREN option implements the Child Mailbox Extension, 147 originally proposed by Mike Gahrns and Raymond Cheng, of Microsoft 148 Corporation. Most of the information in this section is taken 149 directly from their original specification [ChildMbox]. The CHILDREN 150 option is simply an indication that the client wants this 151 information; a server MAY provide it even if the option is not 152 specified, or MAY ignore the option entirely. 153 Many IMAP4 [IMAP4] clients present to the user a hierarchical view of 154 the mailboxes that a user has access to. Rather than initially 155 presenting to the user the entire mailbox hierarchy, it is often 156 preferable to show to the user a collapsed outline list of the 157 mailbox hierarchy (particularly if there is a large number of 158 mailboxes). The user can then expand the collapsed outline hierarchy 159 as needed. It is common to include within the collapsed hierarchy a 160 visual clue (such as a ''+'') to indicate that there are child 161 mailboxes under a particular mailbox. When the visual clue is 162 clicked the hierarchy list is expanded to show the child mailboxes. 163 The Child Mailbox Extension provides a mechanism for a client to 164 efficiently determine if a particular mailbox has children, without 165 issuing a LIST '' * or a LIST '' % for each mailbox name. 166 The Child Mailbox Extension defines two new attributes that MAY be 167 Internet DRAFT IMAP4 LIST Command Extensions August 2003 168 returned within a LIST response: \HasChildren and \HasNoChildren. 169 While these attributes MAY be returned in response to any LIST 170 command, the CHILDREN option is provided to indicate that the client 171 particularly wants this information. If the CHILDREN option is 172 present, the server SHOULD return these attributes even if their 173 computation is expensive. 174 \HasChildren - The presence of this attribute indicates that the mailbox 175 has child mailboxes. 176 A server SHOULD NOT set this attribute if there are child 177 mailboxes, and the user does not have permissions to access any 178 of them. In this case, \HasNoChildren SHOULD be used. 179 In many cases, however, a server may not be able to efficiently 180 compute whether a user has access to all child mailboxes. As 181 such a client MUST be prepared to accept the \HasChildren 182 attribute as a hint. That is, a mailbox MAY be flagged with the 183 \HasChildren attribute, but no child mailboxes will appear in 184 the LIST response. 185 \HasNoChildren - The presence of this attribute indicates that the 186 mailbox has NO child mailboxes that are accessible to the 187 currently authenticated user. 188 In some instances a server that supports the Child Mailbox Extension 189 might not be able to determine whether a mailbox has children. For 190 example it may have difficulty determining whether there are child 191 mailboxes when LISTing mailboxes while operating in a particular 192 namespace. 193 In these cases, a server MAY exclude both the \HasChildren and 194 \HasNoChildren attributes in the LIST response. As such, a client 195 can not make any assumptions about whether a mailbox has children 196 based upon the absence of a single attribute. In particular, some 197 servers may not be able to combine the SUBSCRIBED and CHILDREN 198 options. Such servers MUST honour the SUBSCRIBED option, and they 199 will simply ignore the CHILDREN option if both are requested. 200 It is an error for the server to return both a \HasChildren and a 201 \HasNoChildren attribute in a LIST response. 202 Note: the \HasNoChildren attribute should not be confused with the 203 IMAP4 [IMAP4] defined attribute \NoInferiors which indicates that no 204 child mailboxes exist now and none can be created in the future. 205 6. Examples 206 Internet DRAFT IMAP4 LIST Command Extensions August 2003 207 The first example shows the complete local hierarchy that will be 208 used for the other examples. 209 C: A01 LIST "" "*" 210 S: * LIST (\Marked \NoInferiors) "/" "inbox" 211 S: * LIST () "/" "Fruit" 212 S: * LIST () "/" "Fruit/Apple" 213 S: * LIST () "/" "Fruit/Banana" 214 S: * LIST () "/" "Tofu" 215 S: * LIST () "/" "Vegetable" 216 S: * LIST () "/" "Vegetable/Broccoli" 217 S: A01 OK done 218 In the next example, we'll see the subscribed mailboxes. This is 219 similar, but not equivalent, to . Note that the mailbox 220 called "Fruit/Peach" is subscribed to, but does not actually exist 221 (perhaps it was deleted while still subscribed). And the "Fruit" 222 mailbox is not subscribed to, but it has two subscribed children. 223 C: A02 LIST (SUBSCRIBED) "" "*" 224 S: * LIST (\Marked \NoInferiors) "/" "inbox" 225 S: * LIST (\PlaceHolder) "/" "Fruit" 226 S: * LIST () "/" "Fruit/Banana" 227 S: * LIST (\NonExistent) "/" "Fruit/Peach" 228 S: A02 OK done 229 The next example shows the use of the CHILDREN option. The client, 230 without having to list the second level of hierarchy, now knows which 231 of the top-level mailboxes have sub-mailboxes (children) and which do 232 not. Note that it's not necessary for the server to return the 233 \HasNoChildren flag for the inbox, because the \NoInferiors flag 234 already implies that, and has a stronger meaning. 235 C: A03 LIST (CHILDREN) "" "%" 236 S: * LIST (\Marked \NoInferiors) "/" "inbox" 237 S: * LIST (\HasChildren) "/" "Fruit" 238 S: * LIST (\HasNoChildren) "/" "Tofu" 239 S: * LIST (\HasChildren) "/" "Vegetable" 240 S: A03 OK done 241 In this example we see more mailboxes, which reside on another server 242 to which we may obtain referrals. This is similar to the command 243 . We also see the mixing of two options. Note that in 244 the case of the remote mailboxes, the server might or might not be 245 able to include CHILDREN information; it includes it if it can, and 246 omits it if it can't. 247 C: A04 LIST (REMOTE CHILDREN) "" "%" 248 S: * LIST (\Marked \NoInferiors) "/" "inbox" 249 Internet DRAFT IMAP4 LIST Command Extensions August 2003 250 S: * LIST (\HasChildren) "/" "Fruit" 251 S: * LIST (\HasNoChildren) "/" "Tofu" 252 S: * LIST (\HasChildren) "/" "Vegetable" 253 S: * LIST () "/" "Bread" 254 S: * LIST (\HasChildren) "/" "Meat" 255 S: A04 OK done 256 7. Formal Syntax 257 The following syntax specification uses the augmented Backus-Naur 258 Form (BNF) as described in [ABNF]. Terms not defined here are taken 259 from [IMAP4]. 260 child-mbox-flag = "\HasChildren" / "\HasNoChildren" 261 ; flags for Child Mailbox Extension, at most one 262 ; possible per LIST response 263 list = "LIST" [SP list-options] SP mailbox SP list-mailbox 264 list-options = "(" [option *(SP option)] ")" 265 mailbox-list = "(" [mbx-list-flags] ")" SP 266 (DQUOTE QUOTED-CHAR DQUOTE / nil) SP mailbox 267 [SP mbox-list-extended] 268 mbox-list-extended = "(" [mbox-list-extended-item 269 *(SP mbox-list-extended-item)] ")" 270 mbox-list-extended-item = "(" string SP (nstring / mbox-list- 271 extended-item) ")" 272 / mailbox-list-extended 273 mbox-list-oflag := child-mbox-flag / "\NonExistent" / "\PlaceHolder" 274 option = "SUBSCRIBED" / "CHILDREN" / "REMOTE" / 275 option-extension 276 option-extension = atom 277 8. Security Considerations 278 This document describes syntactic changes to the specification of the 279 IMAP4 commands LIST, LSUB, RLIST, and RLSUB, and the modified LIST 280 command has the same security considerations as those commands. They 281 are described in [IMAP4] and [MboxRefer]. 282 The Child Mailbox Extension provides a client a more efficient means 283 Internet DRAFT IMAP4 LIST Command Extensions August 2003 284 of determining whether a particular mailbox has children. If a 285 mailbox has children, but the currently authenticated user does not 286 have access to any of them, the server SHOULD respond with a 287 \HasNoChildren attribute. In many cases, however, a server may not 288 be able to efficiently compute whether a user has access to all child 289 mailboxes. If such a server responds with a \HasChildren attribute, 290 when in fact the currently authenticated user does not have access to 291 any child mailboxes, potentially more information is conveyed about 292 the mailbox than intended. In most situations this will not be a 293 security concern, because if information regarding whether a mailbox 294 has children is considered sensitive, a user would not be granted 295 access to that mailbox in the first place. 296 9. References 297 [IMAP4]; Crispin, M.; "Internet Message Access Protocol - Version 298 4rev1"; RFC 2060; University of Washington; December 1996. 299 [MboxRefer]; Gahrns, M.; "IMAP4 Mailbox Referrals"; RFC 2193; 300 Microsoft Corporation; September 1997. 301 [ChildMbox]; Gahrns, M. & Cheng, R.; "IMAP4 Child Mailbox Extension"; 302 RFC 3348; Microsoft Corporation; July 2002. 303 [Keywords]; Bradner, S.; "Key words for use in RFCs to Indicate 304 Requirement Levels"; RFC 2119; Harvard University; March 1997. 305 [ABNF]; Crocker, D., and Overell, P. "Augmented BNF for Syntax 306 Specifications: ABNF", RFC 2234, November 1997. 307 10. Acknowledgements 308 Mike Gahrns and Raymond Cheng of Microsoft Corporation originally 309 devised the Child Mailbox Extension and proposed it in 1997; the 310 idea, as well as most of the text in section 5, is theirs. 311 11. Author's Address 312 Barry Leiba 313 IBM T.J. Watson Research Center 314 30 Saw Mill River Road 315 Hawthorne, NY 10532 316 Phone: 1-914-784-7941 317 Email: leiba@watson.ibm.com