1 ../imapserver/server.go:146
2
3
4
5
6
7Network Working Group B. Leiba
8Request for Comments: 5258 IBM T.J. Watson Research Center
9Obsoletes: 3348 A. Melnikov
10Updates: 2193 Isode Limited
11Category: Standards Track June 2008
12
13
14 Internet Message Access Protocol version 4 - LIST Command Extensions
15
16Status of This Memo
17
18 This document specifies an Internet standards track protocol for the
19 Internet community, and requests discussion and suggestions for
20 improvements. Please refer to the current edition of the "Internet
21 Official Protocol Standards" (STD 1) for the standardization state
22 and status of this protocol. Distribution of this memo is unlimited.
23
24Abstract
25
26 IMAP4 has two commands for listing mailboxes: LIST and LSUB. As we
27 have added extensions, such as Mailbox Referrals, that have required
28 specialized lists we have had to expand the number of list commands,
29 since each extension must add its function to both LIST and LSUB, and
30 these commands are not, as they are defined, extensible. If we've
31 needed the extensions to work together, we've had to add a set of
32 commands to mix the different options, the set increasing in size
33 with each new extension. This document describes an extension to the
34 base LIST command that will allow these additions to be done with
35 mutually compatible options to the LIST command, avoiding the
36 exponential increase in specialized list commands.
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58Leiba & Melnikov Standards Track [Page 1]
59
60RFC 5258 IMAP4 LIST Command Extensions June 2008
61
62
63Table of Contents
64
65 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
66 2. Conventions Used in This Document . . . . . . . . . . . . . . 4
67 3. Extended LIST Command . . . . . . . . . . . . . . . . . . . . 4
68 3.1. Initial List of Selection Options . . . . . . . . . . . . 7
69 3.2. Initial List of Return Options . . . . . . . . . . . . . . 8
70 3.3. General Principles for Returning LIST Responses . . . . . 9
71 3.4. Additional Requirements on LIST-EXTENDED Clients . . . . . 9
72 3.5. CHILDINFO Extended Data Item . . . . . . . . . . . . . . . 10
73 4. The CHILDREN Return Option . . . . . . . . . . . . . . . . . . 11
74 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
75 6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 19
76 7. Internationalization Considerations . . . . . . . . . . . . . 22
77 8. Security Considerations . . . . . . . . . . . . . . . . . . . 23
78 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23
79 9.1. Guidelines for IANA . . . . . . . . . . . . . . . . . . . 23
80 9.2. Registration Procedure and Change Control . . . . . . . . 23
81 9.3. Registration Template for LIST-EXTENDED Options . . . . . 25
82 9.4. Initial LIST-EXTENDED Option Registrations . . . . . . . . 25
83 9.5. Registration Template for LIST-EXTENDED Extended Data
84 Item . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
85 9.6. Initial LIST-EXTENDED Extended Data Item Registrations . . 28
86 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 29
87 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29
88 11.1. Normative References . . . . . . . . . . . . . . . . . . . 29
89 11.2. Informative References . . . . . . . . . . . . . . . . . . 30
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114Leiba & Melnikov Standards Track [Page 2]
115
116RFC 5258 IMAP4 LIST Command Extensions June 2008
117
118
1191. Introduction and Overview
120
121 The LIST command is extended by amending the syntax to allow options
122 and multiple patterns to be specified. The list of options replaces
123 the several commands that are currently used to mix and match the
124 information requested. The new syntax is backward compatible, with
125 no ambiguity: the new syntax is being used if one of the following
126 conditions is true:
127
128 1. if the first word after the command name begins with a
129 parenthesis ("LIST selection options")
130
131 2. if the second word after the command name begins with a
132 parenthesis ("multiple mailbox patterns")
133
134 3. if the LIST command has more than 2 parameters ("LIST return
135 options")
136
137 Otherwise the original syntax is used.
138
139 By adding options to the LIST command, we are announcing the intent
140 to phase out and eventually to deprecate the RLIST and RLSUB commands
141 described in [MBRef]. We are also defining the mechanism to request
142 extended mailbox information, such as is described in the Child
143 Mailbox Extension [CMbox]. The base LSUB command is not deprecated
144 by this extension; rather, this extension adds a way to obtain
145 subscription information with more options, with those server
146 implementations that support it. Clients that simply need a list of
147 subscribed mailboxes, as provided by the LSUB command, SHOULD
148 continue to use that command.
149
150 This document defines an IMAP4 extension that is identified by the
151 capability string "LIST-EXTENDED". The LIST-EXTENDED extension makes
152 the following changes to the IMAP4 protocol, which are described in
153 more detail in Section 3 and Section 4:
154
155 a. defines new syntax for LIST command options.
156
157 b. extends LIST to allow for multiple mailbox patterns.
158
159 c. adds LIST command selection options: SUBSCRIBED, REMOTE, and
160 RECURSIVEMATCH.
161
162 d. adds LIST command return options: SUBSCRIBED and CHILDREN.
163
164 e. adds new mailbox attributes: "\NonExistent", "\Subscribed",
165 "\Remote", "\HasChildren", and "\HasNoChildren".
166
167
168
169
170Leiba & Melnikov Standards Track [Page 3]
171
172RFC 5258 IMAP4 LIST Command Extensions June 2008
173
174
175 f. adds CHILDINFO extended data item.
176
1772. Conventions Used in This Document
178
179 In examples, "C:" indicates lines sent by a client that is connected
180 to a server. "S:" indicates lines sent by the server to the client.
181
182 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
183 are used in this document as specified in RFC 2119 [Kwds].
184
185 The term "canonical LIST pattern" refers to the canonical pattern
186 constructed internally by the server from the reference and mailbox
187 name arguments (Section 6.3.8 of [IMAP4]). The [IMAP4] LIST command
188 returns only mailboxes that match the canonical LIST pattern.
189
190 Other terms are introduced where they are referenced for the first
191 time.
192
1933. Extended LIST Command 9051:2224 6154:144 3501:2191 ../imapserver/list.go:18
194
195 This extension updates the syntax of the LIST command to allow for
196 multiple mailbox patterns to be specified, if they are enclosed in
197 parentheses. A mailbox name matches a list of mailbox patterns if it
198 matches at least one mailbox pattern. If a mailbox name matches
199 multiple mailbox patterns from the list, the server SHOULD return
200 only a single LIST response.
201
202 Note that the non-extended LIST command is required to treat an empty
203 ("" string) mailbox name argument as a special request to return the
204 hierarchy delimiter and the root name of the name given in the
205 reference parameter (as per [IMAP4]). However, ANY extended LIST
206 command (extended in any of 3 ways specified in Section 1, or any
207 combination thereof) MUST NOT treat the empty mailbox name as such a
208 special request, and any regular processing described in this
209 document applies. In particular, if an extended LIST command has
210 multiple mailbox names and one (or more) of them is the empty string,
211 the empty string MUST be ignored for the purpose of matching.
212
213 Some servers might restrict which patterns are allowed in a LIST
214 command. If a server doesn't accept a particular pattern, it MUST
215 silently ignore it.
216
217 The LIST command syntax is also extended in two additional ways: by
218 adding a parenthesized list of command options between the command
219 name and the reference name (LIST selection options) and an optional
220
221
222
223
224
225
226Leiba & Melnikov Standards Track [Page 4]
227
228RFC 5258 IMAP4 LIST Command Extensions June 2008
229
230
231 list of options at the end that control what kind of information
232 should be returned (LIST return options). See the formal syntax in
233 Section 6 for specific details.
234
235 A LIST selection option tells the server which mailbox names should
236 be selected by the LIST operation. The server should return
237 information about all mailbox names that match any of the "canonical
238 LIST pattern" (as described above) and satisfy additional selection
239 criteria (if any) specified by the LIST selection options. Let's
240 call any such mailbox name a "matched mailbox name". When multiple
241 selection options are specified, the server MUST return information
242 about mailbox names that satisfy every selection option, unless a
243 description of a particular specified option prescribes special
244 rules. An example of an option prescribing special rules is the
245 RECURSIVEMATCH selection option described later in this section. We
246 will use the term "selection criteria" when referring collectively to
247 all selection options specified in a LIST command.
248
249 A LIST return option controls which information is returned for each
250 matched mailbox name. Note that return options MUST NOT cause the
251 server to report information about additional mailbox names. If the
252 client has not specified any return option, only information about
253 attributes should be returned by the server. (Of course, the server
254 is allowed to include any other information at will.)
255
256 Both selection and return command options will be defined in this
257 document and in approved extension documents; each option will be
258 enabled by a capability string (one capability may enable multiple
259 options), and a client MUST NOT send an option for which the server
260 has not advertised support. A server MUST respond to options it does
261 not recognize with a BAD response. The client SHOULD NOT specify any
262 option more than once; however, if the client does this, the server
263 MUST act as if it received the option only once. The order in which
264 options are specified by the client is not significant.
265
266 In general, each selection option except RECURSIVEMATCH will have a
267 corresponding return option. The REMOTE selection option is an
268 anomaly in this regard, and does not have a corresponding return
269 option. That is because it expands, rather than restricts, the set
270 of mailboxes that are returned. Future extensions to this
271 specification should keep parallelism in mind and define a pair of
272 corresponding options.
273
274 This extension is identified by the capability string
275 "LIST-EXTENDED", and support for it is a prerequisite for any future
276 extensions that require specialized forms of the LIST command. Such
277 extensions MUST refer to this document and MUST add their function
278 through command options as described herein. Note that extensions
279
280
281
282Leiba & Melnikov Standards Track [Page 5]
283
284RFC 5258 IMAP4 LIST Command Extensions June 2008
285
286
287 that don't require support for an extended LIST command, but use
288 extended LIST responses (see below), don't need to advertise the
289 "LIST-EXTENDED" capability string.
290
291 This extension also defines extensions to the LIST response, allowing
292 a series of extended fields at the end, a parenthesized list of
293 tagged data (also referred to as "extended data item"). The first
294 element of an extended field is a tag, which identifies the type of
295 data. Tags MUST be registered with IANA, as described in Section 9.5
296 of this document. An example of such an extended set might be
297
298 tablecloth (("edge" "lacy") ("color" "red"))) (X-Sample "text"))
299
300 or
301
302 tablecloth ("edge" "lacy")) (X-Sample "text" "more text"))
303
304 See the formal syntax, in Section 6, for the full syntactic details.
305 The server MUST NOT return any extended data item unless the client
306 has expressed its ability to support extended LIST responses, for
307 example, by using an extended LIST command. The server MAY return
308 data in the extended fields that was not directly solicited by the
309 client in the corresponding LIST command. For example, the client
310 can enable extra extended fields by using another IMAP extension that
311 make use of the extended LIST responses. The client MUST ignore all
312 extended fields it doesn't recognize.
313
314 The LIST-EXTENDED capability also defines several new mailbox
315 attributes.
316
317 The "\NonExistent" attribute indicates that a mailbox name does not
318 refer to an existing mailbox. Note that this attribute is not
319 meaningful by itself, as mailbox names that match the canonical LIST
320 pattern but don't exist must not be returned unless one of the two
321 conditions listed below is also satisfied:
322
323 a. The mailbox name also satisfies the selection criteria (for
324 example, it is subscribed and the "SUBSCRIBED" selection option
325 has been specified).
326
327 b. "RECURSIVEMATCH" has been specified, and the mailbox name has at
328 least one descendant mailbox name that does not match the LIST
329 pattern and does match the selection criteria.
330
331 In practice, this means that the "\NonExistent" attribute is usually
332 returned with one or more of "\Subscribed", "\Remote",
333 "\HasChildren", or the CHILDINFO extended data item (see their
334 description below).
335
336
337
338Leiba & Melnikov Standards Track [Page 6]
339
340RFC 5258 IMAP4 LIST Command Extensions June 2008
341
342
343 The "\NonExistent" attribute implies "\NoSelect". The "\NonExistent"
344 attribute MUST be supported and MUST be accurately computed.
345
3463.1. Initial List of Selection Options
347
348 The selection options defined in this specification are as follows:
349
350 SUBSCRIBED - causes the LIST command to list subscribed names,
351 rather than the existing mailboxes. This will often be a subset
352 of the actual mailboxes. It's also possible for this list to
353 contain the names of mailboxes that don't exist. In any case, the
354 list MUST include exactly those mailbox names that match the
355 canonical list pattern and are subscribed to. This option is
356 intended to supplement the LSUB command. Of particular note are
357 the mailbox attributes as returned by this option, compared with
358 what is returned by LSUB. With the latter, the attributes
359 returned may not reflect the actual attribute status on the
360 mailbox name, and the \NoSelect attribute has a second special
361 meaning (it indicates that this mailbox is not, itself,
362 subscribed, but that it has descendant mailboxes that are). With
363 the SUBSCRIBED selection option described here, the attributes are
364 accurate and complete, and have no special meanings. "LSUB" and
365 "LIST (SUBSCRIBED)" are, thus, not the same thing, and some
366 servers must do significant extra work to respond to "LIST
367 (SUBSCRIBED)". Because of this, clients SHOULD continue to use
368 "LSUB" unless they specifically want the additional information
369 offered by "LIST (SUBSCRIBED)".
370
371 This option defines a new mailbox attribute, "\Subscribed", that
372 indicates that a mailbox name is subscribed to. The "\Subscribed"
373 attribute MUST be supported and MUST be accurately computed when
374 the SUBSCRIBED selection option is specified.
375
376 Note that the SUBSCRIBED selection option implies the SUBSCRIBED
377 return option (see below).
378
379 REMOTE - causes the LIST command to show remote mailboxes as well as
380 local ones, as described in [MBRef]. This option is intended to
381 replace the RLIST command and, in conjunction with the SUBSCRIBED
382 selection option, the RLSUB command.
383
384 This option defines a new mailbox attribute, "\Remote", that
385 indicates that a mailbox is a remote mailbox. The "\Remote"
386 attribute MUST be accurately computed when the REMOTE option is
387 specified.
388
389 The REMOTE selection option has no interaction with other options.
390 Its effect is to tell the server to apply the other options, if
391
392
393
394Leiba & Melnikov Standards Track [Page 7]
395
396RFC 5258 IMAP4 LIST Command Extensions June 2008
397
398
399 any, to remote mailboxes, in addition to local ones. In
400 particular, it has no interaction with RECURSIVEMATCH (see below).
401 A request for (REMOTE RECURSIVEMATCH) is invalid, because a
402 request for (RECURSIVEMATCH) is. A request for (REMOTE
403 RECURSIVEMATCH SUBSCRIBED) is asking for all subscribed mailboxes,
404 both local and remote.
405
406 RECURSIVEMATCH - this option forces the server to return information
407 about parent mailboxes that don't match other selection options,
408 but have some submailboxes that do. Information about children is
409 returned in the CHILDINFO extended data item, as described in
410 Section 3.5.
411
412 Note 1: In order for a parent mailbox to be returned, it still has
413 to match the canonical LIST pattern.
414
415 Note 2: When returning the CHILDINFO extended data item, it
416 doesn't matter whether or not the submailbox matches the canonical
417 LIST pattern. See also example 9 in Section 5.
418
419 The RECURSIVEMATCH option MUST NOT occur as the only selection
420 option (or only with REMOTE), as it only makes sense when other
421 selection options are also used. The server MUST return BAD
422 tagged response in such case.
423
424 Note that even if the RECURSIVEMATCH option is specified, the
425 client MUST still be able to handle a case when a CHILDINFO
426 extended data item is returned and there are no submailboxes that
427 meet the selection criteria of the subsequent LIST command, as
428 they can be deleted/renamed after the LIST response was sent, but
429 before the client had a chance to access them.
430
4313.2. Initial List of Return Options
432
433 The return options defined in this specification are as follows:
434
435 SUBSCRIBED - causes the LIST command to return subscription state
436 for all matching mailbox names. The "\Subscribed" attribute MUST
437 be supported and MUST be accurately computed when the SUBSCRIBED
438 return option is specified. Further, all mailbox flags MUST be
439 accurately computed (this differs from the behavior of the LSUB
440 command).
441
442 CHILDREN - requests mailbox child information as originally proposed
443 in [CMbox]. See Section 4, below, for details. This option MUST
444 be supported by all servers.
445
446
447
448
449
450Leiba & Melnikov Standards Track [Page 8]
451
452RFC 5258 IMAP4 LIST Command Extensions June 2008
453
454
4553.3. General Principles for Returning LIST Responses
456
457 This section outlines several principles that can be used by server
458 implementations of this document to decide whether a LIST response
459 should be returned, as well as how many responses and what kind of
460 information they may contain.
461
462 1. At most one LIST response should be returned for each mailbox
463 name that matches the canonical LIST pattern. Server
464 implementors must not assume that clients will be able to
465 assemble mailbox attributes and other information returned in
466 multiple LIST responses.
467
468 2. There are only two reasons for including a matching mailbox name
469 in the responses to the LIST command (note that the server is
470 allowed to return unsolicited responses at any time, and such
471 responses are not governed by this rule):
472
473 A. The mailbox name also satisfies the selection criteria.
474
475 B. The mailbox name doesn't satisfy the selection criteria, but
476 it has at least one descendant mailbox name that satisfies
477 the selection criteria and that doesn't match the canonical
478 LIST pattern.
479
480 For more information on this case, see the CHILDINFO extended
481 data item described in Section 3.5. Note that the CHILDINFO
482 extended data item can only be returned when the
483 RECURSIVEMATCH selection option is specified.
484
485 3. Attributes returned in the same LIST response must be treated
486 additively. For example, the following response
487
488 S: * LIST (\Subscribed \NonExistent) "/" "Fruit/Peach"
489
490 means that the "Fruit/Peach" mailbox doesn't exist, but it is
491 subscribed.
492
4933.4. Additional Requirements on LIST-EXTENDED Clients
494
495 All clients that support this extension MUST treat an attribute with
496 a stronger meaning as implying any attribute that can be inferred
497 from it. For example, the client must treat the presence of the
498 \NoInferiors attribute as if the \HasNoChildren attribute was also
499 sent by the server.
500
501
502
503
504
505
506Leiba & Melnikov Standards Track [Page 9]
507
508RFC 5258 IMAP4 LIST Command Extensions June 2008
509
510
511 The following table summarizes inference rules described in
512 Section 3.
513
514 +--------------------+-------------------+
515 | returned attribute | implied attribute |
516 +--------------------+-------------------+
517 | \NoInferiors | \HasNoChildren |
518 | \NonExistent | \NoSelect |
519 +--------------------+-------------------+
520
5213.5. CHILDINFO Extended Data Item
522
523 The CHILDINFO extended data item MUST NOT be returned unless the
524 client has specified the RECURSIVEMATCH selection option.
525
526 The CHILDINFO extended data item in a LIST response describes the
527 selection criteria that has caused it to be returned and indicates
528 that the mailbox has at least one descendant mailbox that matches the
529 selection criteria.
530
531 The LSUB command indicates this condition by using the "\NoSelect"
532 attribute, but the LIST (SUBSCRIBED) command MUST NOT do that, since
533 "\NoSelect" retains its original meaning here. Further, the
534 CHILDINFO extended data item is more general, in that it can be used
535 with any extended set of selection criteria.
536
537 Note: Some servers allow for mailboxes to exist without requiring
538 their parent to exist. For example, a mailbox "Customers/ABC" can
539 exist while the mailbox "Customers" does not. As CHILDINFO extended
540 data item is not allowed if the RECURSIVEMATCH selection option is
541 not specified, such servers SHOULD use the "\NonExistent
542 \HasChildren" attribute pair to signal to the client that there is a
543 descendant mailbox that matches the selection criteria. See example
544 11 in Section 5.
545
546 The returned selection criteria allow the client to distinguish a
547 solicited response from an unsolicited one, as well as to distinguish
548 among solicited responses caused by multiple pipelined LIST commands
549 that specify different criteria.
550
551 Servers SHOULD ONLY return a non-matching mailbox name along with
552 CHILDINFO if at least one matching child is not also being returned.
553 That is, servers SHOULD suppress redundant CHILDINFO responses.
554
555 Examples 8 and 10 in Section 5 demonstrate the difference between
556 present CHILDINFO extended data item and the "\HasChildren"
557 attribute.
558
559
560
561
562Leiba & Melnikov Standards Track [Page 10]
563
564RFC 5258 IMAP4 LIST Command Extensions June 2008
565
566
567 The following table summarizes interaction between the "\NonExistent"
568 attribute and CHILDINFO (the first column indicates whether the
569 parent mailbox exists):
570
571 +--------+--------------+--------------------+----------------------+
572 | exists | meets the | has a child that | returned |
573 | | selection | meets the | LIST-EXTENDED |
574 | | criteria | selection criteria | attributes and |
575 | | | | CHILDINFO |
576 +--------+--------------+--------------------+----------------------+
577 | no | no | no | no LIST response |
578 | | | | returned |
579 | yes | no | no | no LIST response |
580 | | | | returned |
581 | no | yes | no | (\NonExistent |
582 | | | | <attr>) |
583 | yes | yes | no | (<attr>) |
584 | no | no | yes | (\NonExistent) + |
585 | | | | CHILDINFO |
586 | yes | no | yes | () + CHILDINFO |
587 | no | yes | yes | (\NonExistent |
588 | | | | <attr>) + CHILDINFO |
589 | yes | yes | yes | (<attr>) + CHILDINFO |
590 +--------+--------------+--------------------+----------------------+
591
592 where <attr> is one or more attributes that correspond to the
593 selection criteria; for example, for the SUBSCRIBED option the <attr>
594 is \Subscribed.
595
5964. The CHILDREN Return Option
597
598 The CHILDREN return option implements the Child Mailbox Extension,
599 originally proposed by Mike Gahrns and Raymond Cheng, of Microsoft
600 Corporation. Most of the information in this section is taken
601 directly from their original specification [CMbox]. The CHILDREN
602 return option is simply an indication that the client wants this
603 information; a server MAY provide it even if the option is not
604 specified.
605
606 Many IMAP4 [IMAP4] clients present to the user a hierarchical view of
607 the mailboxes that a user has access to. Rather than initially
608 presenting to the user the entire mailbox hierarchy, it is often
609 preferable to show to the user a collapsed outline list of the
610 mailbox hierarchy (particularly if there is a large number of
611 mailboxes). The user can then expand the collapsed outline hierarchy
612 as needed. It is common to include within the collapsed hierarchy a
613 visual clue (such as a ''+'') to indicate that there are child
614 mailboxes under a particular mailbox. When the visual clue is
615
616
617
618Leiba & Melnikov Standards Track [Page 11]
619
620RFC 5258 IMAP4 LIST Command Extensions June 2008
621
622
623 clicked, the hierarchy list is expanded to show the child mailboxes.
624 The CHILDREN return option provides a mechanism for a client to
625 efficiently determine whether a particular mailbox has children,
626 without issuing a LIST "" * or a LIST "" % for each mailbox name.
627 The CHILDREN return option defines two new attributes that MUST be
628 returned within a LIST response: \HasChildren and \HasNoChildren.
629 Although these attributes MAY be returned in response to any LIST
630 command, the CHILDREN return option is provided to indicate that the
631 client particularly wants this information. If the CHILDREN return
632 option is present, the server MUST return these attributes even if
633 their computation is expensive.
634
635 \HasChildren
636
637 The presence of this attribute indicates that the mailbox has child
638 mailboxes. A server SHOULD NOT set this attribute if there are
639 child mailboxes and the user does not have permission to access
640 any of them. In this case, \HasNoChildren SHOULD be used. In
641 many cases, however, a server may not be able to efficiently
642 compute whether a user has access to any child mailbox. Note
643 that even though the \HasChildren attribute for a mailbox must
644 be correct at the time of processing of the mailbox, a client
645 must be prepared to deal with a situation when a mailbox is
646 marked with the \HasChildren attribute, but no child mailbox
647 appears in the response to the LIST command. This might happen,
648 for example, due to children mailboxes being deleted or made
649 inaccessible to the user (using access control) by another
650 client before the server is able to list them.
651
652 \HasNoChildren
653
654 The presence of this attribute indicates that the mailbox has NO
655 child mailboxes that are accessible to the currently
656 authenticated user.
657
658 It is an error for the server to return both a \HasChildren and a
659 \HasNoChildren attribute in the same LIST response.
660
661 Note: the \HasNoChildren attribute should not be confused with the
662 IMAP4 [IMAP4] defined attribute \NoInferiors, which indicates that no
663 child mailboxes exist now and none can be created in the future.
664
665
666
667
668
669
670
671
672
673
674Leiba & Melnikov Standards Track [Page 12]
675
676RFC 5258 IMAP4 LIST Command Extensions June 2008
677
678
6795. Examples 9051:2755 6154:347 3501:2359 ../imapserver/list.go:19
680
681 1: The first example shows the complete local hierarchy that will
682 be used for the other examples.
683
684 C: A01 LIST "" "*"
685 S: * LIST (\Marked \NoInferiors) "/" "inbox"
686 S: * LIST () "/" "Fruit"
687 S: * LIST () "/" "Fruit/Apple"
688 S: * LIST () "/" "Fruit/Banana"
689 S: * LIST () "/" "Tofu"
690 S: * LIST () "/" "Vegetable"
691 S: * LIST () "/" "Vegetable/Broccoli"
692 S: * LIST () "/" "Vegetable/Corn"
693 S: A01 OK done
694
695 2: In the next example, we will see the subscribed mailboxes. This
696 is similar to, but not equivalent with, <LSUB "" "*">. Note
697 that the mailbox called "Fruit/Peach" is subscribed to, but does
698 not actually exist (perhaps it was deleted while still
699 subscribed). The "Fruit" mailbox is not subscribed to, but it
700 has two subscribed children. The "Vegetable" mailbox is
701 subscribed and has two children; one of them is subscribed as
702 well.
703
704 C: A02 LIST (SUBSCRIBED) "" "*"
705 S: * LIST (\Marked \NoInferiors \Subscribed) "/" "inbox"
706 S: * LIST (\Subscribed) "/" "Fruit/Banana"
707 S: * LIST (\Subscribed \NonExistent) "/" "Fruit/Peach"
708 S: * LIST (\Subscribed) "/" "Vegetable"
709 S: * LIST (\Subscribed) "/" "Vegetable/Broccoli"
710 S: A02 OK done
711
712 3: The next example shows the use of the CHILDREN option. The
713 client, without having to list the second level of hierarchy,
714 now knows which of the top-level mailboxes have submailboxes
715 (children) and which do not. Note that it's not necessary for
716 the server to return the \HasNoChildren attribute for the inbox,
717 because the \NoInferiors attribute already implies that, and has
718 a stronger meaning.
719
720 C: A03 LIST () "" "%" RETURN (CHILDREN)
721 S: * LIST (\Marked \NoInferiors) "/" "inbox"
722 S: * LIST (\HasChildren) "/" "Fruit"
723 S: * LIST (\HasNoChildren) "/" "Tofu"
724 S: * LIST (\HasChildren) "/" "Vegetable"
725 S: A03 OK done
726
727
728
729
730Leiba & Melnikov Standards Track [Page 13]
731
732RFC 5258 IMAP4 LIST Command Extensions June 2008
733
734
735 4: In this example, we see more mailboxes that reside on another
736 server. This is similar to the command <RLIST "" "%">.
737
738 C: A04 LIST (REMOTE) "" "%" RETURN (CHILDREN)
739 S: * LIST (\Marked \NoInferiors) "/" "inbox"
740 S: * LIST (\HasChildren) "/" "Fruit"
741 S: * LIST (\HasNoChildren) "/" "Tofu"
742 S: * LIST (\HasChildren) "/" "Vegetable"
743 S: * LIST (\Remote) "/" "Bread"
744 S: * LIST (\HasChildren \Remote) "/" "Meat"
745 S: A04 OK done
746
747 5: The following example also requests the server to include
748 mailboxes that reside on another server. The server returns
749 information about all mailboxes that are subscribed. This is
750 similar to the command <RLSUB "" "*">. We also see the use of
751 two selection options.
752
753 C: A05 LIST (REMOTE SUBSCRIBED) "" "*"
754 S: * LIST (\Marked \NoInferiors \Subscribed) "/" "inbox"
755 S: * LIST (\Subscribed) "/" "Fruit/Banana"
756 S: * LIST (\Subscribed \NonExistent) "/" "Fruit/Peach"
757 S: * LIST (\Subscribed) "/" "Vegetable"
758 S: * LIST (\Subscribed) "/" "Vegetable/Broccoli"
759 S: * LIST (\Remote \Subscribed) "/" "Bread"
760 S: A05 OK done
761
762 6: The following example requests the server to include mailboxes
763 that reside on another server. The server is asked to return
764 subscription information for all returned mailboxes. This is
765 different from the example above.
766
767 Note that the output of this command is not a superset of the
768 output in the previous example, as it doesn't include LIST
769 response for the non-existent "Fruit/Peach".
770
771 C: A06 LIST (REMOTE) "" "*" RETURN (SUBSCRIBED)
772 S: * LIST (\Marked \NoInferiors \Subscribed) "/" "inbox"
773 S: * LIST () "/" "Fruit"
774 S: * LIST () "/" "Fruit/Apple"
775 S: * LIST (\Subscribed) "/" "Fruit/Banana"
776 S: * LIST () "/" "Tofu"
777 S: * LIST (\Subscribed) "/" "Vegetable"
778 S: * LIST (\Subscribed) "/" "Vegetable/Broccoli"
779 S: * LIST () "/" "Vegetable/Corn"
780 S: * LIST (\Remote \Subscribed) "/" "Bread"
781 S: * LIST (\Remote) "/" "Meat"
782 S: A06 OK done
783
784
785
786Leiba & Melnikov Standards Track [Page 14]
787
788RFC 5258 IMAP4 LIST Command Extensions June 2008
789
790
791 7: In the following example, the client has specified multiple
792 mailbox patterns. Note that this example does not use the
793 mailbox hierarchy used in the previous examples.
794
795 C: BBB LIST "" ("INBOX" "Drafts" "Sent/%")
796 S: * LIST () "/" "INBOX"
797 S: * LIST (\NoInferiors) "/" "Drafts"
798 S: * LIST () "/" "Sent/March2004"
799 S: * LIST (\Marked) "/" "Sent/December2003"
800 S: * LIST () "/" "Sent/August2004"
801 S: BBB OK done
802
803 8: The following example demonstrates the difference between the
804 \HasChildren attribute and the CHILDINFO extended data item.
805
806 Let's assume there is the following hierarchy:
807
808 C: C01 LIST "" "*"
809 S: * LIST (\Marked \NoInferiors) "/" "inbox"
810 S: * LIST () "/" "Foo"
811 S: * LIST () "/" "Foo/Bar"
812 S: * LIST () "/" "Foo/Baz"
813 S: * LIST () "/" "Moo"
814 S: C01 OK done
815
816 If the client asks RETURN (CHILDREN), it will get this:
817
818 C: CA3 LIST "" "%" RETURN (CHILDREN)
819 S: * LIST (\Marked \NoInferiors) "/" "inbox"
820 S: * LIST (\HasChildren) "/" "Foo"
821 S: * LIST (\HasNoChildren) "/" "Moo"
822 S: CA3 OK done
823
824 A) Let's also assume that the mailbox "Foo/Baz" is the only
825 subscribed mailbox. Then we get this result:
826
827 C: C02 LIST (SUBSCRIBED) "" "*"
828 S: * LIST (\Subscribed) "/" "Foo/Baz"
829 S: C02 OK done
830
831 Now, if the client issues <LIST (SUBSCRIBED) "" "%">, the server will
832 return no mailboxes (as the mailboxes "Moo", "Foo", and "Inbox" are
833 NOT subscribed). However, if the client issues this:
834
835 C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%"
836 S: * LIST () "/" "Foo" ("CHILDINFO" ("SUBSCRIBED"))
837 S: C04 OK done
838
839
840
841
842Leiba & Melnikov Standards Track [Page 15]
843
844RFC 5258 IMAP4 LIST Command Extensions June 2008
845
846
847 (i.e., the mailbox "Foo" is not subscribed, but it has a child that
848 is.)
849
850 A1) If the mailbox "Foo" had also been subscribed, the last command
851 would return this:
852
853 C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%"
854 S: * LIST (\Subscribed) "/" "Foo" ("CHILDINFO" ("SUBSCRIBED"))
855 S: C04 OK done
856
857 or even this:
858
859 C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%"
860 S: * LIST (\Subscribed \HasChildren) "/" "Foo" ("CHILDINFO"
861 ("SUBSCRIBED"))
862 S: C04 OK done
863
864 A2) If we assume instead that the mailbox "Foo" is not part of the
865 original hierarchy and is not subscribed, the last command will give
866 this result:
867
868 C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%"
869 S: * LIST (\NonExistent) "/" "Foo" ("CHILDINFO" ("SUBSCRIBED"))
870 S: C04 OK done
871
872 B) Now, let's assume that no mailbox is subscribed. In this case,
873 the command <LIST (SUBSCRIBED RECURSIVEMATCH) "" "%"> will return no
874 responses, as there are no subscribed children (even though "Foo" has
875 children).
876
877 C) And finally, suppose that only the mailboxes "Foo" and "Moo" are
878 subscribed. In that case, we see this result:
879
880 C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%" RETURN (CHILDREN)
881 S: * LIST (\HasChildren \Subscribed) "/" "Foo"
882 S: * LIST (\HasNoChildren \Subscribed) "/" "Moo"
883 S: C04 OK done
884
885 (which means that the mailbox "Foo" has children, but none of them is
886 subscribed).
887
888 9: The following example demonstrates that the CHILDINFO extended
889 data item is returned whether or not children mailboxes match
890 the canonical LIST pattern.
891
892
893
894
895
896
897
898Leiba & Melnikov Standards Track [Page 16]
899
900RFC 5258 IMAP4 LIST Command Extensions June 2008
901
902
903 Let's assume there is the following hierarchy:
904
905 C: D01 LIST "" "*"
906 S: * LIST (\Marked \NoInferiors) "/" "inbox"
907 S: * LIST () "/" "foo2"
908 S: * LIST () "/" "foo2/bar1"
909 S: * LIST () "/" "foo2/bar2"
910 S: * LIST () "/" "baz2"
911 S: * LIST () "/" "baz2/bar2"
912 S: * LIST () "/" "baz2/bar22"
913 S: * LIST () "/" "baz2/bar222"
914 S: * LIST () "/" "eps2"
915 S: * LIST () "/" "eps2/mamba"
916 S: * LIST () "/" "qux2/bar2"
917 S: D01 OK done
918
919 And that the following mailboxes are subscribed:
920
921 C: D02 LIST (SUBSCRIBED) "" "*"
922 S: * LIST (\Subscribed) "/" "foo2/bar1"
923 S: * LIST (\Subscribed) "/" "foo2/bar2"
924 S: * LIST (\Subscribed) "/" "baz2/bar2"
925 S: * LIST (\Subscribed) "/" "baz2/bar22"
926 S: * LIST (\Subscribed) "/" "baz2/bar222"
927 S: * LIST (\Subscribed) "/" "eps2"
928 S: * LIST (\Subscribed) "/" "eps2/mamba"
929 S: * LIST (\Subscribed) "/" "qux2/bar2"
930 S: D02 OK done
931
932 The client issues the following command first:
933
934 C: D03 LIST (RECURSIVEMATCH SUBSCRIBED) "" "*2"
935 S: * LIST () "/" "foo2" ("CHILDINFO" ("SUBSCRIBED"))
936 S: * LIST (\Subscribed) "/" "foo2/bar2"
937 S: * LIST (\Subscribed) "/" "baz2/bar2"
938 S: * LIST (\Subscribed) "/" "baz2/bar22"
939 S: * LIST (\Subscribed) "/" "baz2/bar222"
940 S: * LIST (\Subscribed) "/" "eps2" ("CHILDINFO" ("SUBSCRIBED"))
941 S: * LIST (\Subscribed) "/" "qux2/bar2"
942 S: D03 OK done
943
944 and the server may also include (but this would violate a SHOULD NOT
945 in Section 3.5, because CHILDINFO is redundant)
946
947 S: * LIST () "/" "baz2" ("CHILDINFO" ("SUBSCRIBED"))
948 S: * LIST (\NonExistent) "/" "qux2" ("CHILDINFO" ("SUBSCRIBED"))
949
950
951
952
953
954Leiba & Melnikov Standards Track [Page 17]
955
956RFC 5258 IMAP4 LIST Command Extensions June 2008
957
958
959 The CHILDINFO extended data item is returned for mailboxes "foo2",
960 "baz2", and "eps2", because all of them have subscribed children,
961 even though for the mailbox "foo2" only one of the two subscribed
962 children matches the pattern, for the mailbox "baz2" all the
963 subscribed children match the pattern, and for the mailbox "eps2"
964 none of the subscribed children matches the pattern.
965
966 Note that if the client issues
967
968 C: D03 LIST (RECURSIVEMATCH SUBSCRIBED) "" "*"
969 S: * LIST () "/" "foo2" ("CHILDINFO" ("SUBSCRIBED"))
970 S: * LIST (\Subscribed) "/" "foo2/bar1"
971 S: * LIST (\Subscribed) "/" "foo2/bar2"
972 S: * LIST () "/" "baz2" ("CHILDINFO" ("SUBSCRIBED"))
973 S: * LIST (\Subscribed) "/" "baz2/bar2"
974 S: * LIST (\Subscribed) "/" "baz2/bar22"
975 S: * LIST (\Subscribed) "/" "baz2/bar222"
976 S: * LIST (\Subscribed) "/" "eps2" ("CHILDINFO" ("SUBSCRIBED"))
977 S: * LIST (\Subscribed) "/" "eps2/mamba"
978 S: * LIST (\Subscribed) "/" "qux2/bar2"
979 S: D03 OK done
980
981 The LIST responses for mailboxes "foo2", "baz2", and "eps2" still
982 have the CHILDINFO extended data item, even though this information
983 is redundant and the client can determine it by itself.
984
985 10: The following example shows usage of multiple mailbox patterns.
986 It also demonstrates that the presence of the CHILDINFO extended
987 data item doesn't necessarily imply \HasChildren.
988
989 C: a1 LIST "" ("foo" "foo/*")
990 S: * LIST () "/" foo
991 S: a1 OK done
992
993 C: a2 LIST (SUBSCRIBED) "" "foo/*"
994 S: * LIST (\Subscribed \NonExistent) "/" foo/bar
995 S: a2 OK done
996
997 C: a3 LIST (SUBSCRIBED RECURSIVEMATCH) "" foo RETURN (CHILDREN)
998 S: * LIST (\HasNoChildren) "/" foo ("CHILDINFO" ("SUBSCRIBED"))
999 S: a3 OK done
1000
1001 11: The following example shows how a server that supports missing
1002 mailbox hierarchy elements can signal to a client that didn't
1003 specify the RECURSIVEMATCH selection option that there is a
1004 child mailbox that matches the selection criteria.
1005
1006
1007
1008
1009
1010Leiba & Melnikov Standards Track [Page 18]
1011
1012RFC 5258 IMAP4 LIST Command Extensions June 2008
1013
1014
1015 C: a1 LIST (REMOTE) "" *
1016 S: * LIST () "/" music/rock
1017 S: * LIST (\Remote) "/" also/jazz
1018 S: a1 OK done
1019
1020 C: a2 LIST () "" %
1021 S: * LIST (\NonExistent \HasChildren) "/" music
1022 S: a2 OK done
1023
1024 C: a3 LIST (REMOTE) "" %
1025 S: * LIST (\NonExistent \HasChildren) "/" music
1026 S: * LIST (\NonExistent \HasChildren) "/" also
1027 S: a3 OK done
1028
1029 C: a3.1 LIST "" (% music/rock)
1030 S: * LIST () "/" music/rock
1031 S: a3.1 OK done
1032
1033 Because "music/rock" is the only mailbox under "music", there's no
1034 need for the server to also return "music". However clients must
1035 handle both cases.
1036
10376. Formal Syntax
1038
1039 The following syntax specification uses the Augmented Backus-Naur
1040 Form (ABNF) as described in [ABNF]. Terms not defined here are taken
1041 from [IMAP4]. In particular, note that the version of "mailbox-list"
1042 below, which defines the payload of the LIST response, updates the
1043 version defined in the IMAP specification. It is pointed to by
1044 "mailbox-data", which is defined in [IMAP4].
1045
1046 "vendor-token" is defined in [ACAP]. Note that this normative
1047 reference to ACAP will be an issue in moving this spec forward, since
1048 it introduces a dependency on ACAP. The definitions of
1049 "vendor-token" and of the IANA registry must eventually go somewhere
1050 else, in a document that can be moved forward on the standards track
1051 independently of ACAP.
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066Leiba & Melnikov Standards Track [Page 19]
1067
1068RFC 5258 IMAP4 LIST Command Extensions June 2008
1069
1070
1071 childinfo-extended-item = "CHILDINFO" SP "("
1072 list-select-base-opt-quoted
1073 *(SP list-select-base-opt-quoted) ")"
1074 ; Extended data item (mbox-list-extended-item)
1075 ; returned when the RECURSIVEMATCH
1076 ; selection option is specified.
1077 ; Note 1: the CHILDINFO tag can be returned
1078 ; with and without surrounding quotes, as per
1079 ; mbox-list-extended-item-tag production.
1080 ; Note 2: The selection options are always returned
1081 ; quoted, unlike their specification in
1082 ; the extended LIST command.
1083
1084 child-mbox-flag = "\HasChildren" / "\HasNoChildren"
1085 ; attributes for CHILDREN return option, at most one
1086 ; possible per LIST response
1087
1088 eitem-standard-tag = atom
1089 ; a tag for extended list data defined in a Standard
1090 ; Track or Experimental RFC.
1091
1092 eitem-vendor-tag = vendor-token "-" atom
1093 ; a vendor-specific tag for extended list data
1094
1095 list = "LIST" [SP list-select-opts] SP mailbox SP mbox-or-pat 9051:6600 6154:478 3501:4793 9051:6707 9051:6848 5258:1169 5258:1196 ../imapserver/list.go:21 ../imapserver/parse.go:428
1096 [SP list-return-opts]
1097
1098 list-return-opts = "RETURN" SP
1099 "(" [return-option *(SP return-option)] ")"
1100 ; list return options, e.g., CHILDREN
1101
1102 list-select-base-opt = "SUBSCRIBED" / option-extension
1103 ; options that can be used by themselves
1104
1105 list-select-base-opt-quoted = DQUOTE list-select-base-opt DQUOTE
1106
1107 list-select-independent-opt = "REMOTE" / option-extension
1108 ; options that do not syntactically interact with
1109 ; other options
1110
1111 list-select-mod-opt = "RECURSIVEMATCH" / option-extension
1112 ; options that require a list-select-base-opt
1113 ; to also be present
1114
1115 list-select-opt = list-select-base-opt / list-select-independent-opt
1116 / list-select-mod-opt
1117 ; An option registration template is described in
1118 ; Section 9.3 of this document.
1119
1120
1121
1122Leiba & Melnikov Standards Track [Page 20]
1123
1124RFC 5258 IMAP4 LIST Command Extensions June 2008
1125
1126
1127 list-select-opts = "(" [
1128 (*(list-select-opt SP) list-select-base-opt
1129 *(SP list-select-opt))
1130 / (list-select-independent-opt
1131 *(SP list-select-independent-opt))
1132 ] ")"
1133 ; Any number of options may be in any order.
1134 ; If a list-select-mod-opt appears, then a
1135 ; list-select-base-opt must also appear.
1136 ; This allows these:
1137 ; ()
1138 ; (REMOTE)
1139 ; (SUBSCRIBED)
1140 ; (SUBSCRIBED REMOTE)
1141 ; (SUBSCRIBED RECURSIVEMATCH)
1142 ; (SUBSCRIBED REMOTE RECURSIVEMATCH)
1143 ; But does NOT allow these:
1144 ; (RECURSIVEMATCH)
1145 ; (REMOTE RECURSIVEMATCH)
1146
1147 mailbox-list = "(" [mbx-list-flags] ")" SP
1148 (DQUOTE QUOTED-CHAR DQUOTE / nil) SP mailbox
1149 [SP mbox-list-extended]
1150 ; This is the list information pointed to by the ABNF
1151 ; item "mailbox-data", which is defined in [IMAP4]
1152
1153 mbox-list-extended = "(" [mbox-list-extended-item
1154 *(SP mbox-list-extended-item)] ")"
1155
1156 mbox-list-extended-item = mbox-list-extended-item-tag SP
1157 tagged-ext-val
1158
1159 mbox-list-extended-item-tag = astring
1160 ; The content MUST conform to either "eitem-vendor-tag"
1161 ; or "eitem-standard-tag" ABNF productions.
1162 ; A tag registration template is described in this
1163 ; document in Section 9.5.
1164
1165 mbx-list-oflag =/ child-mbox-flag / "\Subscribed" / "\Remote"
1166
1167 mbx-list-sflag =/ "\NonExistent"
1168
1169 mbox-or-pat = list-mailbox / patterns 9051:6707 9051:6848 5258:1095 5258:1196 ../imapserver/parse.go:428
1170
1171 option-extension = (option-standard-tag / option-vendor-tag)
1172 [SP option-value]
1173
1174
1175
1176
1177
1178Leiba & Melnikov Standards Track [Page 21]
1179
1180RFC 5258 IMAP4 LIST Command Extensions June 2008
1181
1182
1183 option-standard-tag = atom
1184 ; an option defined in a Standards Track or
1185 ; Experimental RFC
1186
1187 option-val-comp = astring /
1188 option-val-comp *(SP option-val-comp) /
1189 "(" option-val-comp ")"
1190
1191 option-value = "(" option-val-comp ")"
1192
1193 option-vendor-tag = vendor-token "-" atom
1194 ; a vendor-specific option, non-standard
1195
1196 patterns = "(" list-mailbox *(SP list-mailbox) ")" 9051:6707 9051:6848 5258:1095 5258:1169 ../imapserver/parse.go:428
1197
1198 return-option = "SUBSCRIBED" / "CHILDREN" / option-extension
1199
1200 tagged-ext-comp = astring /
1201 tagged-ext-comp *(SP tagged-ext-comp) /
1202 "(" tagged-ext-comp ")"
1203 ; Extensions that follow this general
1204 ; syntax should use nstring instead of
1205 ; astring when appropriate in the context
1206 ; of the extension.
1207 ; Note that a message set or a "number"
1208 ; can always be represented as an "atom".
1209 ; A URL should be represented as
1210 ; a "quoted" string.
1211
1212 tagged-ext-simple = sequence-set / number
1213
1214 tagged-ext-val = tagged-ext-simple /
1215 "(" [tagged-ext-comp] ")"
1216
12177. Internationalization Considerations
1218
1219 The LIST command selection option types defined in this specification
1220 involve simple tests of mailbox properties. However, future
1221 extensions to LIST-EXTENDED may define selection options that do more
1222 sophisticated tests. In the case of a test that requires matching
1223 text, in the presence of the COMPARATOR [I18N] extension, the active
1224 comparator must be used to do comparisons. Such LIST-EXTENDED
1225 extensions MUST indicate in their specification the interaction with
1226 the COMPARATOR [I18N] extension.
1227
1228
1229
1230
1231
1232
1233
1234Leiba & Melnikov Standards Track [Page 22]
1235
1236RFC 5258 IMAP4 LIST Command Extensions June 2008
1237
1238
12398. Security Considerations
1240
1241 This document describes syntactic changes to the specification of the
1242 IMAP4 commands LIST, LSUB, RLIST, and RLSUB, and the modified LIST
1243 command has the same security considerations as those commands. They
1244 are described in [IMAP4] and [MBRef].
1245
1246 The Child Mailbox Extension provides a client a more efficient means
1247 of determining whether a particular mailbox has children. If a
1248 mailbox has children, but the currently authenticated user does not
1249 have access to any of them, the server SHOULD respond with a
1250 \HasNoChildren attribute. In many cases, however, a server may not
1251 be able to efficiently compute whether a user has access to any child
1252 mailbox. If such a server responds with a \HasChildren attribute,
1253 when in fact the currently authenticated user does not have access to
1254 any child mailboxes, potentially more information is conveyed about
1255 the mailbox than intended. In most situations, this will not be a
1256 security concern, because if information regarding whether a mailbox
1257 has children is considered sensitive, a user would not be granted
1258 access to that mailbox in the first place.
1259
1260 The CHILDINFO extended data item has the same security considerations
1261 as the \HasChildren attribute described above.
1262
12639. IANA Considerations
1264
12659.1. Guidelines for IANA
1266
1267 IANA has created two new registries for LIST-EXTENDED options and
1268 LIST-EXTENDED response data. The templates and the initial
1269 registrations are detailed below.
1270
12719.2. Registration Procedure and Change Control
1272
1273 Registration of a LIST-EXTENDED option is done by filling in the
1274 template in Section 9.3 and sending it via electronic mail to
1275 iana@iana.org. Registration of a LIST-EXTENDED extended data item is
1276 done by filling in the template in Section 9.5 and sending it via
1277 electronic mail to iana@iana.org. IANA has the right to reject
1278 obviously bogus registrations, but will perform no review of claims
1279 made in the registration form.
1280
1281 A LIST-EXTENDED option/extended data item name that starts with "V-"
1282 is reserved for vendor-specific options/extended data items. All
1283 options, whether they are vendor specific or global, should be
1284 registered with IANA. If a LIST-EXTENDED extended data item is
1285 returned as a result of requesting a particular LIST-EXTENDED option,
1286
1287
1288
1289
1290Leiba & Melnikov Standards Track [Page 23]
1291
1292RFC 5258 IMAP4 LIST Command Extensions June 2008
1293
1294
1295 the name of the option SHOULD be used as the name of the
1296 LIST-EXTENDED extended data item.
1297
1298 Each vendor-specific option/extended data item MUST start with its
1299 vendor-token ("vendor prefix"). The vendor-token MUST be registered
1300 with IANA, using the [ACAP] vendor subtree registry.
1301
1302 Standard LIST-EXTENDED option/extended data item names are case
1303 insensitive. If the vendor prefix is omitted from a vendor-specific
1304 LIST-EXTENDED option/extended data item name, the rest is case
1305 insensitive. The vendor prefix itself is not case sensitive, as it
1306 might contain non-ASCII characters. While the registration
1307 procedures do not require it, authors of
1308 LIST-EXTENDED options/extended data items are encouraged to seek
1309 community review and comment whenever that is feasible. Authors may
1310 seek community review by posting a specification of their proposed
1311 mechanism as an
1312 Internet-Draft. LIST-EXTENDED option/extended data items intended
1313 for widespread use should be standardized through the normal IETF
1314 process, when appropriate.
1315
1316 Comments on registered LIST-EXTENDED options/extended response data
1317 should first be sent to the "owner" of the mechanism and/or to the
1318 IMAPEXT WG mailing list. Submitters of comments may, after a
1319 reasonable attempt to contact the owner, request IANA to attach their
1320 comment to the registration itself. If IANA approves of this, the
1321 comment will be made accessible in conjunction with the registration
1322 LIST-EXTENDED options/extended response data itself.
1323
1324 Once a LIST-EXTENDED registration has been published by IANA, the
1325 author may request a change to its definition. The change request
1326 follows the same procedure as the registration request.
1327
1328 The owner of a LIST-EXTENDED registration may pass responsibility for
1329 the registered option/extended data item to another person or agency
1330 by informing IANA; this can be done without discussion or review.
1331
1332 The IESG may reassign responsibility for a LIST-EXTENDED
1333 option/extended data item. The most common case of this will be to
1334 enable changes to be made to mechanisms where the author of the
1335 registration has died, has moved out of contact, or is otherwise
1336 unable to make changes that are important to the community.
1337
1338 LIST-EXTENDED registrations may not be deleted; mechanisms that are
1339 no longer believed appropriate for use can be declared OBSOLETE by a
1340 change to their "intended use" field. Such LIST-EXTENDED
1341 options/extended data items will be clearly marked in the lists
1342 published by IANA.
1343
1344
1345
1346Leiba & Melnikov Standards Track [Page 24]
1347
1348RFC 5258 IMAP4 LIST Command Extensions June 2008
1349
1350
1351 The IESG is considered to be the owner of all LIST-EXTENDED
1352 options/extended data items that are on the IETF standards track.
1353
13549.3. Registration Template for LIST-EXTENDED Options
1355
1356 To: iana@iana.org
1357 Subject: Registration of LIST-EXTENDED option X
1358
1359 LIST-EXTENDED option name:
1360
1361 LIST-EXTENDED option type: (One of SELECTION or RETURN)
1362
1363 Implied return options(s), if the option type is SELECTION: (zero or
1364 more)
1365
1366 LIST-EXTENDED option description:
1367
1368 Published specification (optional, recommended):
1369
1370 Security considerations:
1371
1372 Intended usage:
1373 (One of COMMON, LIMITED USE, or OBSOLETE)
1374
1375 Person and email address to contact for further information:
1376
1377 Owner/Change controller:
1378
1379 (Any other information that the author deems interesting may be added
1380 below this line.)
1381
13829.4. Initial LIST-EXTENDED Option Registrations
1383
1384 The LIST-EXTENDED option registry has been populated with the
1385 following entries:
1386
1387 1. To: iana@iana.org
1388 Subject: Registration of LIST-EXTENDED option SUBSCRIBED
1389
1390 LIST-EXTENDED option name: SUBSCRIBED
1391
1392 LIST-EXTENDED option type: SELECTION
1393
1394 Implied return options(s): SUBSCRIBED
1395
1396 LIST-EXTENDED option description: Causes the LIST command to list
1397 subscribed mailboxes, rather than the actual mailboxes.
1398
1399
1400
1401
1402Leiba & Melnikov Standards Track [Page 25]
1403
1404RFC 5258 IMAP4 LIST Command Extensions June 2008
1405
1406
1407 Published specification: RFC 5258, Section 3.
1408
1409 Security considerations: RFC 5258, Section 8.
1410
1411 Intended usage: COMMON
1412
1413 Person and email address to contact for further information:
1414 Alexey Melnikov <Alexey.Melnikov@isode.com>
1415
1416 Owner/Change controller: iesg@ietf.org
1417
1418 2. To: iana@iana.org
1419 Subject: Registration of LIST-EXTENDED option REMOTE
1420
1421 LIST-EXTENDED option name: REMOTE
1422
1423 LIST-EXTENDED option type: SELECTION
1424
1425 Implied return options(s): (none)
1426
1427 LIST-EXTENDED option description: Causes the LIST command to
1428 return remote mailboxes as well as local ones, as described in
1429 RFC 2193.
1430
1431 Published specification: RFC 5258, Section 3.
1432
1433 Security considerations: RFC 5258, Section 8.
1434
1435 Intended usage: COMMON
1436
1437 Person and email address to contact for further information:
1438 Alexey Melnikov <Alexey.Melnikov@isode.com>
1439
1440 Owner/Change controller: iesg@ietf.org
1441
1442 3. To: iana@iana.org
1443 Subject: Registration of LIST-EXTENDED option SUBSCRIBED
1444
1445 LIST-EXTENDED option name: SUBSCRIBED
1446
1447 LIST-EXTENDED option type: RETURN
1448
1449 LIST-EXTENDED option description: Causes the LIST command to
1450 return subscription state.
1451
1452 Published specification: RFC 5258, Section 3.
1453
1454 Security considerations: RFC 5258, Section 8.
1455
1456
1457
1458Leiba & Melnikov Standards Track [Page 26]
1459
1460RFC 5258 IMAP4 LIST Command Extensions June 2008
1461
1462
1463 Intended usage: COMMON
1464
1465 Person and email address to contact for further information:
1466 Alexey Melnikov <Alexey.Melnikov@isode.com>
1467
1468 Owner/Change controller: iesg@ietf.org
1469
1470 4. To: iana@iana.org
1471 Subject: Registration of LIST-EXTENDED option RECURSIVEMATCH
1472
1473 LIST-EXTENDED option name: RECURSIVEMATCH
1474
1475 LIST-EXTENDED option type: SELECTION
1476
1477 Implied return options(s): (none)
1478
1479 LIST-EXTENDED option description: Requests that CHILDINFO
1480 extended data item (childinfo-extended-item) is to be returned.
1481
1482 Published specification: RFC 5258, Section 3.
1483
1484 Security considerations: RFC 5258, Section 8.
1485
1486 Intended usage: COMMON
1487
1488 Person and email address to contact for further information:
1489 Alexey Melnikov <Alexey.Melnikov@isode.com>
1490
1491 Owner/Change controller: iesg@ietf.org
1492
1493 5. To: iana@iana.org
1494 Subject: Registration of LIST-EXTENDED option CHILDREN
1495
1496 LIST-EXTENDED option name: CHILDREN
1497
1498 LIST-EXTENDED option type: RETURN
1499
1500 LIST-EXTENDED option description: Requests mailbox child
1501 information.
1502
1503 Published specification: RFC 5258, Section 3 and Section 4.
1504
1505 Security considerations: RFC 5258, Section 8.
1506
1507 Intended usage: COMMON
1508
1509 Person and email address to contact for further information:
1510 Alexey Melnikov <Alexey.Melnikov@isode.com>
1511
1512
1513
1514Leiba & Melnikov Standards Track [Page 27]
1515
1516RFC 5258 IMAP4 LIST Command Extensions June 2008
1517
1518
1519 Owner/Change controller: iesg@ietf.org
1520
15219.5. Registration Template for LIST-EXTENDED Extended Data Item
1522
1523 To: iana@iana.org
1524 Subject: Registration of X LIST-EXTENDED extended data item
1525
1526 LIST-EXTENDED extended data item tag:
1527
1528 LIST-EXTENDED extended data item description:
1529
1530 Which LIST-EXTENDED option(s) (and their types) causes this extended
1531 data item to be returned (if any):
1532
1533 Published specification (optional, recommended):
1534
1535 Security considerations:
1536
1537 Intended usage:
1538 (One of COMMON, LIMITED USE, or OBSOLETE)
1539
1540 Person and email address to contact for further information:
1541
1542 Owner/Change controller:
1543
1544 (Any other information that the author deems interesting may be added
1545 below this line.)
1546
15479.6. Initial LIST-EXTENDED Extended Data Item Registrations
1548
1549 The LIST-EXTENDED extended data item registry has been populated with
1550 the following entries:
1551
1552 1. To: iana@iana.org
1553 Subject: Registration of CHILDINFO LIST-EXTENDED extended data
1554 item
1555
1556 LIST-EXTENDED extended data item tag: CHILDINFO
1557
1558 LIST-EXTENDED extended data item description: The CHILDINFO
1559 extended data item describes the selection criteria that has
1560 caused it to be returned and indicates that the mailbox has one
1561 or more child mailboxes that match the selection criteria.
1562
1563 Which LIST-EXTENDED option(s) (and their types) causes this
1564 extended data item to be returned (if any): RECURSIVEMATCH
1565 selection option
1566
1567
1568
1569
1570Leiba & Melnikov Standards Track [Page 28]
1571
1572RFC 5258 IMAP4 LIST Command Extensions June 2008
1573
1574
1575 Published specification: RFC 5258, Section 3.5.
1576
1577 Security considerations: RFC 5258, Section 8.
1578
1579 Intended usage: COMMON
1580
1581 Person and email address to contact for further information:
1582 Alexey Melnikov <Alexey.Melnikov@isode.com>
1583
1584 Owner/Change controller: iesg@ietf.org
1585
158610. Acknowledgements
1587
1588 Mike Gahrns and Raymond Cheng of Microsoft Corporation originally
1589 devised the Child Mailbox Extension and proposed it in 1997; the
1590 idea, as well as most of the text in Section 4, is theirs.
1591
1592 This document is the result of discussions on the IMAP4 and IMAPEXT
1593 mailing lists and is meant to reflect consensus of those groups. In
1594 particular, Mark Crispin, Philip Guenther, Cyrus Daboo, Timo
1595 Sirainen, Ken Murchison, Rob Siemborski, Steve Hole, Arnt
1596 Gulbrandsen, Larry Greenfield, Dave Cridland, and Pete Maclean were
1597 active participants in those discussions or made suggestions to this
1598 document.
1599
160011. References
1601
160211.1. Normative References
1603
1604 [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
1605 Specifications: ABNF", STD 68, RFC 5234, January 2008.
1606
1607 [ACAP] Newman, C. and J. Myers, "ACAP -- Application Configuration
1608 Access Protocol", RFC 2244, November 1997.
1609
1610 [I18N] Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet
1611 Message Access Protocol Internationalization", RFC 5255,
1612 June 2008.
1613
1614 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version
1615 4rev1", RFC 3501, March 2003.
1616
1617 [Kwds] Bradner, S., "Key words for use in RFCs to Indicate
1618 Requirement Levels", RFC 2119, March 1997.
1619
1620 [MBRef] Gahrns, M., "IMAP4 Mailbox Referrals", RFC 2193,
1621 September 1997.
1622
1623
1624
1625
1626Leiba & Melnikov Standards Track [Page 29]
1627
1628RFC 5258 IMAP4 LIST Command Extensions June 2008
1629
1630
163111.2. Informative References
1632
1633 [CMbox] Gahrns, M. and R. Cheng, "The Internet Message Action
1634 Protocol (IMAP4) Child Mailbox Extension", RFC 3348,
1635 July 2002.
1636
1637Authors' Addresses
1638
1639 Barry Leiba
1640 IBM T.J. Watson Research Center
1641 19 Skyline Drive
1642 Hawthorne, NY 10532
1643 US
1644
1645 Phone: +1 914 784 7941
1646 EMail: leiba@watson.ibm.com
1647
1648
1649 Alexey Melnikov
1650 Isode Limited
1651 5 Castle Business Village
1652 36 Station Road
1653 Hampton, Middlesex TW12 2BX
1654 UK
1655
1656 EMail: Alexey.Melnikov@isode.com
1657 URI: http://www.melnikov.ca/
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682Leiba & Melnikov Standards Track [Page 30]
1683
1684RFC 5258 IMAP4 LIST Command Extensions June 2008
1685
1686
1687Full Copyright Statement
1688
1689 Copyright (C) The IETF Trust (2008).
1690
1691 This document is subject to the rights, licenses and restrictions
1692 contained in BCP 78, and except as set forth therein, the authors
1693 retain all their rights.
1694
1695 This document and the information contained herein are provided on an
1696 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
1697 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
1698 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
1699 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
1700 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
1701 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1702
1703Intellectual Property
1704
1705 The IETF takes no position regarding the validity or scope of any
1706 Intellectual Property Rights or other rights that might be claimed to
1707 pertain to the implementation or use of the technology described in
1708 this document or the extent to which any license under such rights
1709 might or might not be available; nor does it represent that it has
1710 made any independent effort to identify any such rights. Information
1711 on the procedures with respect to rights in RFC documents can be
1712 found in BCP 78 and BCP 79.
1713
1714 Copies of IPR disclosures made to the IETF Secretariat and any
1715 assurances of licenses to be made available, or the result of an
1716 attempt made to obtain a general license or permission for the use of
1717 such proprietary rights by implementers or users of this
1718 specification can be obtained from the IETF on-line IPR repository at
1719 http://www.ietf.org/ipr.
1720
1721 The IETF invites any interested party to bring to its attention any
1722 copyrights, patents or patent applications, or other proprietary
1723 rights that may cover technology that may be required to implement
1724 this standard. Please address the information to the IETF at
1725 ietf-ipr@ietf.org.
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738Leiba & Melnikov Standards Track [Page 31]
1739
1740