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