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