Debian Codegraph @

rfc5257.html

raw
1 <pre>Network Working Group C. Daboo
2 Request for Comments: 5257 Apple Inc.
3 Category: Experimental R. Gellens
4 QUALCOMM Incorporated
5 June 2008
6
7
8 <span class="h1">Internet Message Access Protocol - ANNOTATE Extension</span>
9
10 Status of This Memo
11
12 This memo defines an Experimental Protocol for the Internet
13 community. It does not specify an Internet standard of any kind.
14 Discussion and suggestions for improvement are requested.
15 Distribution of this memo is unlimited.
16
17 Abstract
18
19 The ANNOTATE extension to the Internet Message Access Protocol
20 permits clients and servers to maintain "meta data" for messages, or
21 individual message parts, stored in a mailbox on the server. For
22 example, this can be used to attach comments and other useful
23 information to a message. It is also possible to attach annotations
24 to specific parts of a message, so that, for example, they could be
25 marked as seen, or important, or a comment added.
26
27 Note that this document was the product of a WG that had good
28 consensus on how to approach the problem. Nevertheless, the WG felt
29 it did not have enough information on implementation and deployment
30 hurdles to meet all of the requirements of a Proposed Standard. The
31 IETF solicits implementations and implementation reports in order to
32 make further progress.
33
34 Implementers should be aware that this specification may change in an
35 incompatible manner when going to Proposed Standard status. However,
36 any incompatible changes will result in a new capability name being
37 used to prevent problems with any deployments of the experimental
38 extension.
39
40
41
42
43
44
45
46
47
48
49
50
51
52 <span class="grey">Daboo &amp; Gellens Experimental [Page 1]</span></pre>
53 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-2" ></span>
54 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
55
56
57 Table of Contents
58
59 <a href="#section-1">1</a>. Introduction and Overview .......................................<a href="#page-3">3</a>
60 <a href="#section-2">2</a>. Conventions Used in This Document ...............................<a href="#page-4">4</a>
61 <a href="#section-3">3</a>. Data Model ......................................................<a href="#page-4">4</a>
62 <a href="#section-3.1">3.1</a>. Overview ...................................................<a href="#page-4">4</a>
63 <a href="#section-3.2">3.2</a>. Namespace of Entries and Attributes ........................<a href="#page-4">4</a>
64 <a href="#section-3.2.1">3.2.1</a>. Entry Names .........................................<a href="#page-5">5</a>
65 <a href="#section-3.2.2">3.2.2</a>. Attribute Names .....................................<a href="#page-7">7</a>
66 <a href="#section-3.3">3.3</a>. Private Versus Shared ......................................<a href="#page-7">7</a>
67 <a href="#section-3.4">3.4</a>. Access Control .............................................<a href="#page-8">8</a>
68 <a href="#section-3.5">3.5</a>. Access to Standard IMAP Flags and Keywords ................<a href="#page-11">11</a>
69 <a href="#section-4">4</a>. IMAP Protocol Changes ..........................................<a href="#page-11">11</a>
70 <a href="#section-4.1">4.1</a>. General Considerations ....................................<a href="#page-11">11</a>
71 <a href="#section-4.2">4.2</a>. ANNOTATE Parameter with the SELECT/EXAMINE Commands .......<a href="#page-12">12</a>
72 <a href="#section-4.3">4.3</a>. ANNOTATION Message Data Item in FETCH Command .............<a href="#page-12">12</a>
73 <a href="#section-4.4">4.4</a>. ANNOTATION Message Data Item in FETCH Response ............<a href="#page-14">14</a>
74 <a href="#section-4.5">4.5</a>. ANNOTATION Message Data Item in STORE .....................<a href="#page-16">16</a>
75 <a href="#section-4.6">4.6</a>. ANNOTATION Interaction with COPY ..........................<a href="#page-18">18</a>
76 <a href="#section-4.7">4.7</a>. ANNOTATION Message Data Item in APPEND ....................<a href="#page-18">18</a>
77 <a href="#section-4.8">4.8</a>. ANNOTATION Criterion in SEARCH ............................<a href="#page-19">19</a>
78 <a href="#section-4.9">4.9</a>. ANNOTATION Key in SORT ....................................<a href="#page-20">20</a>
79 <a href="#section-4.10">4.10</a>. New ACL Rights ...........................................<a href="#page-21">21</a>
80 <a href="#section-5">5</a>. Formal Syntax ..................................................<a href="#page-21">21</a>
81 <a href="#section-6">6</a>. IANA Considerations ............................................<a href="#page-23">23</a>
82 <a href="#section-6.1">6.1</a>. Entry and Attribute Registration Template .................<a href="#page-23">23</a>
83 <a href="#section-6.2">6.2</a>. Entry Registrations .......................................<a href="#page-24">24</a>
84 <a href="#section-6.2.1">6.2.1</a>. /comment ...........................................<a href="#page-24">24</a>
85 <a href="#section-6.2.2">6.2.2</a>. /flags .............................................<a href="#page-24">24</a>
86 <a href="#section-6.2.3">6.2.3</a>. /altsubject ........................................<a href="#page-25">25</a>
87 <a href="#section-6.2.4">6.2.4</a>. /&lt;section-part&gt;/comment ............................<a href="#page-25">25</a>
88 <a href="#section-6.2.5">6.2.5</a>. /&lt;section-part&gt;/flags/seen .........................<a href="#page-26">26</a>
89 <a href="#section-6.2.6">6.2.6</a>. /&lt;section-part&gt;/flags/answered .....................<a href="#page-26">26</a>
90 <a href="#section-6.2.7">6.2.7</a>. /&lt;section-part&gt;/flags/flagged ......................<a href="#page-27">27</a>
91 <a href="#section-6.2.8">6.2.8</a>. /&lt;section-part&gt;/flags/forwarded ....................<a href="#page-27">27</a>
92 <a href="#section-6.3">6.3</a>. Attribute Registrations ...................................<a href="#page-28">28</a>
93 <a href="#section-6.3.1">6.3.1</a>. value ..............................................<a href="#page-28">28</a>
94 <a href="#section-6.3.2">6.3.2</a>. size ...............................................<a href="#page-28">28</a>
95 <a href="#section-6.4">6.4</a>. Capability Registration ...................................<a href="#page-28">28</a>
96 <a href="#section-7">7</a>. Internationalization Considerations ............................<a href="#page-29">29</a>
97 <a href="#section-8">8</a>. Security Considerations ........................................<a href="#page-29">29</a>
98 <a href="#section-9">9</a>. References .....................................................<a href="#page-29">29</a>
99 <a href="#section-9.1">9.1</a>. Normative References ......................................<a href="#page-29">29</a>
100 <a href="#section-9.2">9.2</a>. Informative References ....................................<a href="#page-30">30</a>
101 <a href="#section-10">10</a>. Acknowledgments ...............................................<a href="#page-30">30</a>
102
103
104
105
106
107
108 <span class="grey">Daboo &amp; Gellens Experimental [Page 2]</span></pre>
109 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-3" ></span>
110 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
111
112
113 <span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction and Overview</span>
114
115 The ANNOTATE extension is present in any IMAP [<a href="./rfc3501" title="&quot;INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1&quot;">RFC3501</a>]
116 implementation that returns "ANNOTATE-EXPERIMENT-1" as one of the
117 supported capabilities in the CAPABILITY response.
118
119 This extension makes the following changes to the IMAP protocol:
120
121 a. adds a new ANNOTATION message data item for use in FETCH.
122
123 b. adds a new ANNOTATION message data item for use in STORE.
124
125 c. adds a new ANNOTATION search criterion for use in SEARCH.
126
127 d. adds a new ANNOTATION sort key for use in the SORT extension.
128
129 e. adds a new ANNOTATION data item for use in APPEND.
130
131 f. adds a new requirement on the COPY command.
132
133 g. adds a new ANNOTATE parameter for use with the SELECT/EXAMINE
134 commands.
135
136 h. adds two new response codes to indicate store failures of
137 annotations.
138
139 i. adds a new untagged response code for the SELECT or EXAMINE
140 commands to indicate the maximum sized annotation that can be
141 stored.
142
143 j. adds a new Access Control List (ACL) "bit" for use with the ACL
144 extensions [<a href="./rfc2086" title="&quot;IMAP4 ACL extension&quot;">RFC2086</a>] and [<a href="./rfc4314" title="&quot;IMAP4 Access Control List (ACL) Extension&quot;">RFC4314</a>].
145
146 The data model used for the storage of annotations is based on the
147 Application Configuration Access Protocol [<a href="./rfc2244" title="&quot;ACAP -- Application Configuration Access Protocol&quot;">RFC2244</a>]. Note that there
148 is no inheritance in annotations.
149
150 If a server supports annotations, then it MUST store all annotation
151 data permanently, i.e., there is no concept of "session only"
152 annotations that would correspond to the behavior of "session" flags
153 as defined in the IMAP base specification.
154
155 In order to provide optimum support for a disconnected client (one
156 that needs to synchronize annotations for use when offline), servers
157 SHOULD also support the Conditional STORE [<a href="./rfc4551" title="&quot;IMAP Extension for Conditional STORE Operation or Quick Flag Changes Resynchronization&quot;">RFC4551</a>] extension.
158
159 The rest of this document describes the data model and protocol
160 changes more rigorously.
161
162
163
164 <span class="grey">Daboo &amp; Gellens Experimental [Page 3]</span></pre>
165 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-4" ></span>
166 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
167
168
169 <span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. Conventions Used in This Document</span>
170
171 The examples in this document use "C:" and "S:" to indicate lines
172 sent by the client and server, respectively.
173
174 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
175 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
176 document are to be interpreted as described in [<a href="./rfc2119" title="&quot;Key words for use in RFCs to Indicate Requirement Levels&quot;">RFC2119</a>].
177
178 <span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. Data Model</span>
179
180 <span class="h3"><a class="selflink" id="section-3.1" href="#section-3.1">3.1</a>. Overview</span>
181
182 The data model for annotations in ANNOTATE uses a uniquely named
183 entry that contains a set of standard attributes. Thus, a single
184 coherent unit of "meta data" for a message is stored as a single
185 entry, made up of several attributes.
186
187 For example, a comment annotation added to a message has an entry
188 name of "/comment". This entry is composed of several attributes
189 such as "value", "size", etc., that contain the properties and data
190 of the entry.
191
192 The protocol changes to IMAP, described below, allow a client to
193 access or change the values of any attribute in any entry in a
194 message annotation, assuming it has sufficient access rights to do so
195 (see <a href="#section-3.4">Section 3.4</a> for specifics).
196
197 <span class="h3"><a class="selflink" id="section-3.2" href="#section-3.2">3.2</a>. Namespace of Entries and Attributes</span>
198
199 A message may contain zero or more annotations, each of which is a
200 single uniquely named entry. Each entry has a hierarchical name,
201 with each component of the name separated by a slash ("/"). An entry
202 name MUST NOT contain two consecutive "/" characters and MUST NOT end
203 with a "/" character.
204
205 Each entry is made up of a set of attributes. Each attribute has a
206 hierarchical name, with each component of the name separated by a
207 period ("."). An attribute name MUST NOT contain two consecutive "."
208 characters and MUST NOT end with a "." character.
209
210 The value of an attribute is "NIL" (has no value), or is a string of
211 zero or more octets.
212
213 Entry and attribute names MUST NOT contain asterisk ("*") or percent
214 ("%") characters, and MUST NOT contain non-ASCII characters or the
215 NULL octet. Invalid entry or attribute names result in a BAD
216 response in any IMAP commands where they are used.
217
218
219
220 <span class="grey">Daboo &amp; Gellens Experimental [Page 4]</span></pre>
221 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-5" ></span>
222 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
223
224
225 Attribute names MUST NOT contain any hierarchical components with the
226 names "priv" or "shared", as those have special meaning (see <a href="#section-3.3">Section</a>
227 <a href="#section-3.3">3.3</a>).
228
229 Entry and attribute names are case-sensitive.
230
231 Use of control or punctuation characters in entry and attribute names
232 is strongly discouraged.
233
234 This specification defines an initial set of entry and attribute
235 names available for use in message annotations. In addition, an
236 extension mechanism is described to allow additional names to be
237 added as needed.
238
239 <span class="h4"><a class="selflink" id="section-3.2.1" href="#section-3.2.1">3.2.1</a>. Entry Names</span>
240
241 Entry names MUST be specified in a standards track or IESG approved
242 experimental RFC, or fall under the vendor namespace. See <a href="#section-6.1">Section</a>
243 <a href="#section-6.1">6.1</a> for the registration template.
244
245 /
246 Defines the top-level of entries associated with an entire
247 message. This entry itself does not contain any attributes. All
248 entries that start with a numeric character ("0" - "9") refer to
249 an annotation on a specific body part. All other entries are for
250 annotations on the entire message.
251
252 /comment
253 Defines a comment or note associated with an entire message.
254
255 /flags
256 This entry hierarchy is reserved for future use.
257
258 /altsubject
259 Contains text supplied by the message recipient to be used by the
260 client, instead of the original message Subject.
261
262 /vendor/&lt;vendor-token&gt;
263 Defines the top-level of entries associated with an entire message
264 as created by a particular product of some vendor. These sub-
265 entries can be used by vendors to provide client-specific
266 annotations. The vendor-token MUST be registered with IANA, using
267 the [<a href="./rfc2244" title="&quot;ACAP -- Application Configuration Access Protocol&quot;">RFC2244</a>] vendor subtree registry.
268
269 /&lt;section-part&gt;
270 Defines the top-level of entries associated with a specific body
271 part of a message. This entry itself does not contain any
272 attributes. The section-part is a numeric part specifier. Its
273
274
275
276 <span class="grey">Daboo &amp; Gellens Experimental [Page 5]</span></pre>
277 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-6" ></span>
278 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
279
280
281 syntax is the same as the section-part ABNF element defined in
282 [<a href="./rfc3501" title="&quot;INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1&quot;">RFC3501</a>]. The server MUST return a BAD response if the client
283 uses an incorrect part specifier (either incorrect syntax or a
284 specifier referring to a non-existent part). The server MUST
285 return a BAD response if the client uses an empty part specifier
286 (which is used in IMAP to represent the entire message).
287
288 /&lt;section-part&gt;/comment
289 Defines a comment or note associated with a specific body part of
290 a message.
291
292 /&lt;section-part&gt;/flags
293 Defines the top-level of entries associated with the flag state
294 for a specific body part of a message. All sub-entries are
295 maintained entirely by the client. There is no implicit change to
296 any flag by the server.
297
298 /&lt;section-part&gt;/flags/seen
299 This is similar to the IMAP \Seen flag, except it applies
300 to only the body part referenced by the entry.
301
302 /&lt;section-part&gt;/flags/answered
303 This is similar to the IMAP \Answered flag, except it
304 applies to only the body part referenced by the entry.
305
306 /&lt;section-part&gt;/flags/flagged
307 This is similar to the IMAP \Flagged flag, except it
308 applies to only the body part referenced by the entry.
309
310 /&lt;section-part&gt;/flags/forwarded
311 This is similar to the IMAP $Forwarded keyword, except it
312 applies to only the body part referenced by the entry.
313
314 Defines flags for a specific body part of a message. The "value"
315 attribute of each of the entries described above must be either
316 "1", "0", or "NIL". "1" corresponds to the flag being set.
317
318 /&lt;section-part&gt;/vendor/&lt;vendor-token&gt;
319 Defines the top-level of entries associated with a specific body
320 part of a message as created by a particular product of some
321 vendor. This entry can be used by vendors to provide client
322 specific annotations. The vendor-token MUST be registered with
323 IANA.
324
325
326
327
328
329
330
331
332 <span class="grey">Daboo &amp; Gellens Experimental [Page 6]</span></pre>
333 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-7" ></span>
334 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
335
336
337 <span class="h4"><a class="selflink" id="section-3.2.2" href="#section-3.2.2">3.2.2</a>. Attribute Names</span>
338
339 Attribute names MUST be specified in a standards track or IESG
340 approved experimental RFC. See <a href="#section-6.1">Section 6.1</a> for the registration
341 template.
342
343 All attribute names implicitly have a ".priv" and a ".shared" suffix
344 that maps to private and shared versions of the entry. Searching or
345 fetching without using either suffix will include both. The client
346 MUST specify either a ".priv" or ".shared" suffix when storing an
347 annotation or sorting on annotations.
348
349 value
350 A string or binary data representing the value of the annotation.
351 To delete an annotation, the client can store "NIL" into the
352 value. If the client requests the value attribute for a non-
353 existent entry, then the server MUST return "NIL" for the value.
354 The content represented by the string is determined by the
355 content-type used to register the entry (see <a href="#section-6.1">Section 6.1</a> for entry
356 registration templates). Where applicable, the registered
357 content-type MUST include a charset parameter. Text values SHOULD
358 use the utf-8 [<a href="./rfc3629" title="&quot;UTF-8, a transformation format of ISO 10646&quot;">RFC3629</a>] character set. Note that binary data
359 (data which may contain the NULL octet) is allowed (e.g., for
360 storing images), and this extension uses the "literal8" syntax
361 element [<a href="./rfc4466" title="&quot;Collected Extensions to IMAP4 ABNF&quot;">RFC4466</a>] to allow such data to be written to or read from
362 the server.
363
364 size
365 The size of the value, in octets. Set automatically by the
366 server, read-only to clients. If the client requests the size
367 attribute for a non-existent entry, then the server MUST return
368 "0" (zero) for the size.
369
370 <span class="h3"><a class="selflink" id="section-3.3" href="#section-3.3">3.3</a>. Private Versus Shared</span>
371
372 Some IMAP mailboxes are private, accessible only to the owning user.
373 Other mailboxes are not, either because the owner has set an ACL
374 [<a href="./rfc4314" title="&quot;IMAP4 Access Control List (ACL) Extension&quot;">RFC4314</a>] that permits access by other users, or because it is a
375 shared mailbox.
376
377 This raises the issue of shared versus private annotations.
378
379 If all annotations are private, it is then impossible to have
380 annotations in a shared or otherwise non-private mailbox be visible
381 to other users. This eliminates what could be a useful aspect of
382 annotations in a shared environment. An example of such use is a
383 shared IMAP folder containing bug reports. Engineers may want to use
384
385
386
387
388 <span class="grey">Daboo &amp; Gellens Experimental [Page 7]</span></pre>
389 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-8" ></span>
390 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
391
392
393 annotations to add information to existing messages, indicate
394 assignments, status, etc. This use requires shared annotations.
395
396 If all annotations are shared, it is impossible to use annotations
397 for private notes on messages in shared mailboxes. Also, modifying
398 an ACL to permit access to a mailbox by other users may
399 unintentionally expose private information.
400
401 There are also situations in which both shared and private
402 annotations are useful. For example, an administrator may want to
403 set shared annotations on messages in a shared folder, which
404 individual users may wish to supplement with additional notes.
405
406 If shared and private annotations are to coexist, we need a clear way
407 to differentiate them. Also, it should be as easy as possible for a
408 client to access both and not overlook either. There is also a
409 danger in allowing a client to store an annotation without knowing if
410 it is shared or private.
411
412 This document proposes two standard suffixes for all attributes:
413 ".shared" and ".priv". A SEARCH or FETCH command that specifies
414 neither, uses both. STORE, APPEND, and SORT commands MUST explicitly
415 use ".priv" or ".shared" suffixes.
416
417 If the ANNOTATE extension is present, support for shared annotations
418 in servers is REQUIRED, while support for private annotations in
419 servers is OPTIONAL. This recognizes the fact that support for
420 private annotations may introduce a significant increase in
421 complexity to a server in terms of tracking ownership of the
422 annotations, how quota is determined for users based on their own
423 annotations, etc. Clients that support the ANNOTATE extension MUST
424 handle both shared and private annotations.
425
426 <span class="h3"><a class="selflink" id="section-3.4" href="#section-3.4">3.4</a>. Access Control</span>
427
428 A user needs to have appropriate rights in order to read or write
429 ".priv" or ".shared" annotation values. How those rights are
430 calculated depends on whether or not the ACL [<a href="./rfc2086" title="&quot;IMAP4 ACL extension&quot;">RFC2086</a>] extension or
431 its update [<a href="./rfc4314" title="&quot;IMAP4 Access Control List (ACL) Extension&quot;">RFC4314</a>] is present. If a client attempts to store or
432 fetch an annotation to which they do not have the appropriate rights,
433 the server MUST respond with a NO response.
434
435 When the ACL extension is not present, access to annotation values is
436 governed by the nature of the selected state, in particular whether
437 the mailbox was SELECTED or EXAMINED in READ-ONLY or READ-WRITE mode.
438
439
440
441
442
443
444 <span class="grey">Daboo &amp; Gellens Experimental [Page 8]</span></pre>
445 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-9" ></span>
446 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
447
448
449 When the ACL extension is present, the server MUST recognize the new
450 ACL "n" right, in addition to the ones defined by the ACL extension
451 itself.
452
453 For ".priv" annotation values, the "r" right controls both read and
454 write access. When it is on, access to ".priv" annotations is
455 allowed; when it is off, access to ".priv" annotations is disallowed.
456
457 For ".shared" annotation values, the "r" right controls read access.
458 When it is on, ".shared" annotations can be read; when it is off,
459 ".shared" annotations cannot be read.
460
461 For ".shared" annotation values, the "n" right controls write access.
462 When it is on, ".shared" annotations can be changed or created
463 through either a STORE or APPEND command; when it is off, ".shared"
464 annotations cannot be changed or created. The "n" right constitutes
465 a "shared flag right" as defined in <a href="./rfc4314#section-6.2">Section&nbsp;6.2 of [RFC4314]</a>.
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500 <span class="grey">Daboo &amp; Gellens Experimental [Page 9]</span></pre>
501 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-10" ></span>
502 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
503
504
505 A summary of all the access control restrictions is tabulated below
506
507 +---------------+---------------+-----------------------------------+
508 | Server Type | Action on | Type of mailbox |
509 | | annotation | |
510 +===============+===============+===================================+
511 | | | |
512 | | read .priv | Any mailbox that can be SELECTED |
513 | | values | or EXAMINED. |
514 | | | |
515 | +---------------+-----------------------------------+
516 | | | |
517 | | write .priv | Any SELECTED [READ-WRITE] mailbox.|
518 | | values | SELECTED [READ-ONLY] mailboxes MAY|
519 | Server | | also permit writes. |
520 | without | | |
521 | ACL Extension +---------------+-----------------------------------+
522 | | | |
523 | | read .shared | Any mailbox that can be SELECTED |
524 | | values | or EXAMINED. |
525 | | | |
526 | +---------------+-----------------------------------+
527 | | | |
528 | | write .shared | Any mailbox that can be SELECTED |
529 | | values | or EXAMINED and is [READ-WRITE]. |
530 | | | |
531 +---------------+---------------+-----------------------------------+
532 | | | |
533 | | read .priv | Any mailbox with the "r" |
534 | | values | ACL right. |
535 | | | |
536 | +---------------+-----------------------------------+
537 | | | |
538 | | write .priv | Any mailbox with the "r" |
539 | Server | values | ACL right. |
540 | with | | |
541 | ACL Extension +---------------+-----------------------------------+
542 | | | |
543 | | read .shared | Any mailbox with the "r" |
544 | | values | ACL right. |
545 | | | |
546 | +---------------+-----------------------------------+
547 | | | |
548 | | write .shared | Any mailbox with the "n" |
549 | | values | ACL right. |
550 | | | |
551 +---------------+---------------+-----------------------------------+
552
553
554
555
556 <span class="grey">Daboo &amp; Gellens Experimental [Page 10]</span></pre>
557 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-11" ></span>
558 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
559
560
561 <span class="h3"><a class="selflink" id="section-3.5" href="#section-3.5">3.5</a>. Access to Standard IMAP Flags and Keywords</span>
562
563 Due to the ambiguity of how private and shared values would map to
564 the base IMAP flag and keyword values, the ANNOTATE extension does
565 not expose IMAP flags or keywords as entries. However, the /flags
566 annotation entry is reserved for future use and MUST NOT be used by
567 clients or servers supporting this extension.
568
569 Clients that need to implement shared and private "flags" can create
570 their own annotation entries for those, completely bypassing the base
571 IMAP flag/keyword behavior.
572
573 <span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. IMAP Protocol Changes</span>
574
575 <span class="h3"><a class="selflink" id="section-4.1" href="#section-4.1">4.1</a>. General Considerations</span>
576
577 Servers may be able to offer only a limited level of support for
578 annotations in mailboxes, and it is useful for clients to be able to
579 know what level of support is available. Servers MUST return an
580 ANNOTATIONS response code during the SELECT or EXAMINE command for a
581 mailbox to indicate the level of support. Possible data items used
582 with the ANNOTATIONS response code are:
583
584 "NONE" - this indicates that the mailbox being selected does not
585 support annotations at all. Clients MUST NOT attempt to use
586 annotation extensions in commands for this mailbox.
587
588 "READ-ONLY" - this indicates that the annotations supported by the
589 mailbox cannot be changed by the client. Clients MUST NOT attempt
590 to store annotations on any messages in a mailbox with this
591 response code.
592
593 "NOPRIVATE" - this indicates that the server does not support
594 private annotations on the mailbox. Only shared annotations are
595 supported. Clients SHOULD only attempt to read or store
596 annotations attributes with the ".shared" suffix. If a client
597 uses an attribute with the ".priv" suffix in a FETCH command, then
598 servers should return the attribute value in the FETCH response as
599 "NIL". If a client uses an attribute with the ".priv" suffix in a
600 STORE command (or an APPEND command targeted at the mailbox), then
601 the server MUST return a NO response.
602
603 numeric values - if servers support writable annotations, then the
604 server MUST indicate the maximum size in octets for an annotation
605 value by providing the maximum size value in the response code.
606 Clients MUST NOT store annotation values of a size greater than
607 the amount indicated by the server. Servers MUST accept a minimum
608
609
610
611
612 <span class="grey">Daboo &amp; Gellens Experimental [Page 11]</span></pre>
613 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-12" ></span>
614 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
615
616
617 annotation data size of at least 1024 octets if annotations can be
618 written.
619
620 In addition, the server MAY limit the total number of annotations for
621 a single message. However, the server MUST provide a minimum
622 annotation count per message of at least 10.
623
624 <span class="h3"><a class="selflink" id="section-4.2" href="#section-4.2">4.2</a>. ANNOTATE Parameter with the SELECT/EXAMINE Commands</span>
625
626 The ANNOTATE extension defines a single optional SELECT parameter
627 [<a href="./rfc4466" title="&quot;Collected Extensions to IMAP4 ABNF&quot;">RFC4466</a>] "ANNOTATE", which is used to turn on unsolicited responses
628 for annotations as described in <a href="#section-4.4">Section 4.4</a>. This optional parameter
629 results in a per-mailbox state change, i.e., it must be used in each
630 SELECT/EXAMINE command in order to be effective, irrespective of
631 whether it was used in a previous SELECT/EXAMINE during the same
632 session.
633
634 Example:
635
636 C: a SELECT INBOX (ANNOTATE)
637 S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen)
638 S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft
639 \Deleted \Seen \*)]
640 S: * 10268 EXISTS
641 S: * 1 RECENT
642 S: * OK [UNSEEN 10268]
643 S: * OK [UIDVALIDITY 890061587]
644 S: * OK [UIDNEXT 34643]
645 S: * OK [ANNOTATIONS 20480 NOPRIVATE]
646 S: a OK [READ-WRITE] Completed
647
648 In the above example, a SELECT command with the ANNOTATE parameter
649 is issued. The response from the server includes the required
650 ANNOTATIONS response that indicates that the server supports
651 annotations up to a maximum size of 20480 octets, and does not
652 support private annotations (only shared).
653
654 <span class="h3"><a class="selflink" id="section-4.3" href="#section-4.3">4.3</a>. ANNOTATION Message Data Item in FETCH Command</span>
655
656 This extension adds an ANNOTATION message data item to the FETCH
657 command. This allows clients to retrieve annotations for a range of
658 messages in the currently selected mailbox.
659
660 ANNOTATION &lt;entry-specifier&gt; &lt;attribute-specifier&gt;
661
662 The ANNOTATION message data item, when used by the client in the
663 FETCH command, takes an entry specifier and an attribute
664 specifier.
665
666
667
668 <span class="grey">Daboo &amp; Gellens Experimental [Page 12]</span></pre>
669 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-13" ></span>
670 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
671
672
673 Example:
674
675 C: a FETCH 1 (ANNOTATION (/comment value))
676 S: * 1 FETCH (ANNOTATION (/comment
677 (value.priv "My comment"
678 value.shared "Group note")))
679 S: a OK Fetch complete
680
681 In the above example, the content of the "value" attribute for the
682 "/comment" entry is requested by the client and returned by the
683 server. Since neither ".shared" nor ".priv" was specified, both
684 are returned.
685
686 "*" and "%" wild card characters can be used in entry specifiers to
687 match one or more characters at that position, with the exception
688 that "%" does not match the "/" hierarchy delimiter. Thus, an entry
689 specifier of "/%" matches entries such as "/comment" and
690 "/altsubject", but not "/1/comment".
691
692 Example:
693
694 C: a UID FETCH 1123 (UID ANNOTATION
695 (/* (value.priv size.priv)))
696 S: * 12 FETCH (UID 1123 ANNOTATION
697 (/comment (value.priv "My comment"
698 size.priv "10")
699 /altsubject (value.priv "Rhinoceroses!"
700 size.priv "13")
701 /vendor/foobar/label.priv
702 (value.priv "label43"
703 size.priv "7")
704 /vendor/foobar/personality
705 (value.priv "Tallulah Bankhead"
706 size.priv "17")))
707 S: a OK Fetch complete
708
709 In the above example, the contents of the private "value" and
710 "size" attributes for any entries in the "/" hierarchy are
711 requested by the client and returned by the server.
712
713
714
715
716
717
718
719
720
721
722
723
724 <span class="grey">Daboo &amp; Gellens Experimental [Page 13]</span></pre>
725 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-14" ></span>
726 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
727
728
729 Example:
730
731 C: a FETCH 1 (ANNOTATION (/% value.shared))
732 S: * 1 FETCH (ANNOTATION
733 (/comment (value.shared "Patch Mangler")
734 /altsubject (value.shared "Patches? We don't
735 need no steenkin patches!")))
736 S: a OK Fetch complete
737
738 In the above example, the contents of the shared "value"
739 attributes for entries at the top level only of the "/" hierarchy
740 are requested by the client and returned by the server.
741
742 Entry and attribute specifiers can be lists of atomic specifiers, so
743 that multiple items of each type may be returned in a single FETCH
744 command.
745
746 Example:
747
748 C: a FETCH 1 (ANNOTATION
749 ((/comment /altsubject) value.priv))
750 S: * 1 FETCH (ANNOTATION
751 (/comment (value.priv "What a chowder-head")
752 /altsubject (value.priv "How to crush beer cans")))
753 S: a OK Fetch complete
754
755 In the above example, the contents of the private "value"
756 attributes for the two entries "/comment" and "/altsubject" are
757 requested by the client and returned by the server.
758
759 <span class="h3"><a class="selflink" id="section-4.4" href="#section-4.4">4.4</a>. ANNOTATION Message Data Item in FETCH Response</span>
760
761 The ANNOTATION message data item in the FETCH response displays
762 information about annotations in a message.
763
764 ANNOTATION parenthesized list
765
766 The response consists of a list of entries, each of which have a
767 list of attribute-value pairs.
768
769
770
771
772
773
774
775
776
777
778
779
780 <span class="grey">Daboo &amp; Gellens Experimental [Page 14]</span></pre>
781 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-15" ></span>
782 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
783
784
785 Example:
786
787 C: a FETCH 1 (ANNOTATION (/comment value))
788 S: * 1 FETCH (ANNOTATION (/comment
789 (value.priv "My comment"
790 value.shared NIL)))
791 S: a OK Fetch complete
792
793 In the above example, a single entry with a single attribute-value
794 pair is returned by the server. Since the client did not specify
795 a ".shared" or ".priv" suffix, both are returned. Only the
796 private attribute has a value (the shared value is "NIL").
797
798 Example:
799
800 C: a FETCH 1 (ANNOTATION
801 ((/comment /altsubject) value))
802 S: * 1 FETCH (ANNOTATION
803 (/comment (value.priv "My comment"
804 value.shared NIL)
805 /altsubject (value.priv "My subject"
806 value.shared NIL)))
807 S: a OK Fetch complete
808
809 In the above example, two entries, each with a single attribute-
810 value pair, are returned by the server. Since the client did not
811 specify a ".shared" or ".priv" suffix, both are returned. Only
812 the private attributes have values; the shared attributes are
813 "NIL".
814
815 Example:
816
817 C: a FETCH 1 (ANNOTATION
818 (/comment (value size)))
819 S: * 1 FETCH (ANNOTATION
820 (/comment
821 (value.priv "My comment"
822 value.shared NIL
823 size.priv "10"
824 size.shared "0")))
825 S: a OK Fetch complete
826
827 In the above example, a single entry with two attribute-value
828 pairs is returned by the server. Since the client did not specify
829 a ".shared" or ".priv" suffix, both are returned. Only the
830 private attributes have values; the shared attributes are "NIL".
831
832
833
834
835
836 <span class="grey">Daboo &amp; Gellens Experimental [Page 15]</span></pre>
837 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-16" ></span>
838 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
839
840
841 Servers SHOULD send ANNOTATION message data items in unsolicited
842 FETCH responses if an annotation entry is changed by a third-party,
843 and the ANNOTATE select parameter was used. This allows servers to
844 keep clients updated with changes to annotations by other clients.
845
846 Unsolicited ANNOTATION responses MUST NOT include ANNOTATION data
847 values -- only the entry name of the ANNOTATION that has changed.
848 This restriction avoids sending ANNOTATION data values (which may be
849 large) to a client unless the client explicitly asks for the value.
850
851 Example:
852
853 C: a STORE 1 +FLAGS (\Seen)
854 S: * 1 FETCH (FLAGS (\Seen))
855 ANNOTATION (/comment))
856 S: a OK STORE complete
857
858 In the above example, an unsolicited ANNOTATION response is
859 returned during a STORE command. The unsolicited response
860 contains only the entry name of the annotation that changed, and
861 not its value.
862
863 <span class="h3"><a class="selflink" id="section-4.5" href="#section-4.5">4.5</a>. ANNOTATION Message Data Item in STORE</span>
864
865 ANNOTATION &lt;parenthesized entry-attribute-value list&gt;
866
867 Sets the specified list of entries by adding or replacing the
868 specified attributes with the values provided. Clients can use
869 "NIL" for values of attributes it wants to remove from entries.
870
871 The ANNOTATION message data item used with the STORE command has an
872 implicit ".SILENT" behavior. This means the server does not generate
873 an untagged FETCH in response to the STORE command and assumes that
874 the client updates its own cache if the command succeeds. Though
875 note, that if the Conditional STORE extension [<a href="./rfc4551" title="&quot;IMAP Extension for Conditional STORE Operation or Quick Flag Changes Resynchronization&quot;">RFC4551</a>] is present,
876 then an untagged FETCH response with a MODSEQ data item will be
877 returned by the server as required by [<a href="./rfc4551" title="&quot;IMAP Extension for Conditional STORE Operation or Quick Flag Changes Resynchronization&quot;">RFC4551</a>].
878
879 If the server is unable to store an annotation because the size of
880 its value is too large, the server MUST return a tagged NO response
881 with a "[ANNOTATE TOOBIG]" response code.
882
883 If the server is unable to store a new annotation because the maximum
884 number of allowed annotations has already been reached, the server
885 MUST return a tagged NO response with a "[ANNOTATE TOOMANY]" response
886 code.
887
888
889
890
891
892 <span class="grey">Daboo &amp; Gellens Experimental [Page 16]</span></pre>
893 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-17" ></span>
894 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
895
896
897 Example:
898
899 C: a STORE 1 ANNOTATION (/comment
900 (value.priv "My new comment"))
901 S: a OK Store complete
902
903 In the above example, the entry "/comment" is created (if not
904 already present). Its private attribute "value" is created if not
905 already present, or replaced if it exists. "value.priv" is set to
906 "My new comment".
907
908 Example:
909
910 C: a STORE 1 ANNOTATION (/comment
911 (value.shared NIL))
912 S: a OK Store complete
913
914 In the above example, the shared "value" attribute of the entry
915 "/comment" is removed by storing "NIL" into the attribute.
916
917 Multiple entries can be set in a single STORE command by listing
918 entry-attribute-value pairs in the list.
919
920 Example:
921
922 C: a STORE 1 ANNOTATION (/comment
923 (value.priv "Get tix Tuesday")
924 /altsubject
925 (value.priv "Wots On"))
926 S: a OK Store complete
927
928 In the above example, the entries "/comment" and "/altsubject" are
929 created (if not already present) and the private attribute "value"
930 is created or replaced for each entry.
931
932 Multiple attributes can be set in a single STORE command by listing
933 multiple attribute-value pairs in the entry list.
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948 <span class="grey">Daboo &amp; Gellens Experimental [Page 17]</span></pre>
949 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-18" ></span>
950 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
951
952
953 Example:
954
955 C: a STORE 1 ANNOTATION (/comment
956 (value.priv "My new comment"
957 value.shared "foo's bar"))
958 S: a OK Store complete
959
960 In the above example, the entry "/comment" is created (if not
961 already present) and the private and shared "value" attributes are
962 created if not already present, or replaced if they exist.
963
964 <span class="h3"><a class="selflink" id="section-4.6" href="#section-4.6">4.6</a>. ANNOTATION Interaction with COPY</span>
965
966 The COPY command can be used to move messages from one mailbox to
967 another on the same server. Servers that support the ANNOTATION
968 extension MUST, for each message being copied, copy all ".priv"
969 annotation data for the current user only, and all ".shared"
970 annotation data along with the message to the new mailbox. The only
971 exceptions to this are if the destination mailbox permissions are
972 such that either the ".priv" or ".shared" annotations are not
973 allowed, or if the destination mailbox is of a type that does not
974 support annotations or does not support storing of annotations (a
975 mailbox that returns a "NONE" or "READ-ONLY" response code in its
976 ANNOTATIONS response), or if the destination mailbox cannot support
977 the size of an annotation because it exceeds the ANNOTATIONS value.
978 Servers MUST NOT copy ".priv" annotation data for users other than
979 the current user.
980
981 <span class="h3"><a class="selflink" id="section-4.7" href="#section-4.7">4.7</a>. ANNOTATION Message Data Item in APPEND</span>
982
983 ANNOTATION &lt;parenthesized entry-attribute-value list&gt;
984
985 Sets the specified list of entries and attributes in the resulting
986 message.
987
988 The APPEND command can include annotations for the message being
989 appended via the addition of a new append data item [<a href="./rfc4466" title="&quot;Collected Extensions to IMAP4 ABNF&quot;">RFC4466</a>]. The
990 new data item can also be used with the multi-append [<a href="./rfc3502" title="&quot;Internet Message Access Protocol (IMAP) - MULTIAPPEND Extension&quot;">RFC3502</a>]
991 extension that allows multiple messages to be appended via a single
992 APPEND command.
993
994
995
996
997
998
999
1000
1001
1002
1003
1004 <span class="grey">Daboo &amp; Gellens Experimental [Page 18]</span></pre>
1005 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-19" ></span>
1006 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
1007
1008
1009 Example:
1010
1011 C: a APPEND drafts ANNOTATION (/comment
1012 (value.priv "Don't send until I say so")) {310}
1013 S: + Ready for literal data
1014 C: MIME-Version: 1.0
1015 ...
1016 C:
1017 S: a OK APPEND completed
1018
1019 In the above example, a comment with a private value is added to a
1020 new message appended to the mailbox. The ellipsis represents the
1021 bulk of the message.
1022
1023 <span class="h3"><a class="selflink" id="section-4.8" href="#section-4.8">4.8</a>. ANNOTATION Criterion in SEARCH</span>
1024
1025 ANNOTATION &lt;entry-name&gt; &lt;attribute-name&gt; &lt;value&gt;
1026
1027 The ANNOTATION criterion for the SEARCH command allows a client to
1028 search for a specified string in the value of an annotation entry of
1029 a message.
1030
1031 Messages that have annotations with entries matching &lt;entry-name&gt;,
1032 attributes matching &lt;attribute-name&gt;, and the specified string
1033 &lt;value&gt; in their values are returned in the SEARCH results. The "*"
1034 character can be used in the entry name field to match any content in
1035 those items. The "%" character can be used in the entry name field
1036 to match a single level of hierarchy only.
1037
1038 Only the "value", "value.priv", and "value.shared" attributes can be
1039 searched. Clients MUST NOT specify an attribute other than either
1040 "value", "value.priv", or "value.shared". Servers MUST return a BAD
1041 response if the client tries to search any other attribute.
1042
1043 Example:
1044
1045 C: a SEARCH ANNOTATION /comment value "IMAP4"
1046 S: * SEARCH 2 3 5 7 11 13 17 19 23
1047 S: a OK Search complete
1048
1049 In the above example, the message numbers of any messages
1050 containing the string "IMAP4" in the shared or private "value"
1051 attribute of the "/comment" entry are returned in the search
1052 results.
1053
1054
1055
1056
1057
1058
1059
1060 <span class="grey">Daboo &amp; Gellens Experimental [Page 19]</span></pre>
1061 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-20" ></span>
1062 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
1063
1064
1065 Example:
1066
1067 C: a SEARCH ANNOTATION * value.priv "IMAP4"
1068 S: * SEARCH 1 2 3 5 8 13 21 34
1069 S: a OK Search complete
1070
1071 In the above example, the message numbers of any messages
1072 containing the string "IMAP4" in the private "value" attribute of
1073 any entry are returned in the search results.
1074
1075 <span class="h3"><a class="selflink" id="section-4.9" href="#section-4.9">4.9</a>. ANNOTATION Key in SORT</span>
1076
1077 ANNOTATION &lt;entry-name&gt; &lt;attribute-name&gt;
1078
1079 The ANNOTATION criterion for the SORT command [<a href="./rfc5256" title="&quot;Internet Message Access Protocol - SORT and THREAD Extensions&quot;">RFC5256</a>] instructs the
1080 server to return the sequence numbers or Unique Identifiers (UIDs) of
1081 messages in a mailbox, sorted using the values of the specified
1082 annotations. The ANNOTATION criterion is available if the server
1083 returns both ANNOTATE-EXPERIMENT-1 and SORT as supported capabilities
1084 in the CAPABILITY command response.
1085
1086 Messages are sorted using the values of the &lt;attribute-name&gt;
1087 attributes in the &lt;entry-name&gt; entries.
1088
1089 Clients MUST provide either the ".priv" or ".shared" suffix to the
1090 attribute name to ensure that the server knows which specific value
1091 to sort on.
1092
1093 Only the "value.priv" and "value.shared" attributes can be used for
1094 sorting. Clients MUST NOT specify an attribute other than either
1095 "value.priv" or "value.shared". Servers MUST return a BAD response
1096 if the client tries to sort on any other attribute.
1097
1098 When either "value.priv" or "value.shared" is being sorted, the
1099 server MUST use the character set value specified in the SORT command
1100 to determine the appropriate sort order.
1101
1102 Example:
1103
1104 C: a SORT (ANNOTATION /altsubject value.shared) UTF-8 ALL
1105 S: * SORT 2 3 4 5 1 11 10 6 7 9 8
1106 S: a OK Sort complete
1107
1108 In the above example, the message numbers of all messages are
1109 returned, sorted according to the shared "value" attribute of the
1110 "/altsubject" entry.
1111
1112
1113
1114
1115
1116 <span class="grey">Daboo &amp; Gellens Experimental [Page 20]</span></pre>
1117 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-21" ></span>
1118 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
1119
1120
1121 Note that the ANNOTATION sort key must include a fully specified
1122 entry -- wild cards are not allowed.
1123
1124 <span class="h3"><a class="selflink" id="section-4.10" href="#section-4.10">4.10</a>. New ACL Rights</span>
1125
1126 As discussed in <a href="#section-3.4">Section 3.4</a>, this extension adds a new "n" right to
1127 the list of rights provided by the ACL extensions [<a href="./rfc2086" title="&quot;IMAP4 ACL extension&quot;">RFC2086</a>] and
1128 [<a href="./rfc4314" title="&quot;IMAP4 Access Control List (ACL) Extension&quot;">RFC4314</a>].
1129
1130 <span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>. Formal Syntax</span>
1131
1132 The following syntax specification uses the Augmented Backus-Naur
1133 Form (ABNF) notation as specified in [<a href="./rfc5234" title="&quot;Augmented BNF for Syntax Specifications: ABNF&quot;">RFC5234</a>].
1134
1135 Non-terminals referenced but not defined below are as defined by
1136 [<a href="./rfc3501" title="&quot;INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1&quot;">RFC3501</a>] with the new definitions in [<a href="./rfc4466" title="&quot;Collected Extensions to IMAP4 ABNF&quot;">RFC4466</a>] superseding those in
1137 [<a href="./rfc3501" title="&quot;INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1&quot;">RFC3501</a>].
1138
1139 Except as noted otherwise, all alphabetic characters are case-
1140 insensitive. The use of upper or lower case characters to define
1141 token strings is for editorial clarity only. Implementations MUST
1142 accept these strings in a case-insensitive fashion.
1143
1144 ann-size = "NONE" /
1145 (("READ-ONLY" / nz-number)
1146 [SP "NOPRIVATE"])
1147 ; response codes indicating the level of
1148 ; support for annotations in a mailbox
1149
1150 append-ext =/ att-annotate
1151 ; modifies [<a href="./rfc3501" title="&quot;INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1&quot;">RFC3501</a>] extension behaviour
1152
1153 att-annotate = "ANNOTATION" SP
1154 "(" entry-att *(SP entry-att) ")"
1155
1156 att-search = "value" / "value.priv" / "value.shared"
1157 ; the only attributes that can be searched
1158
1159 att-sort = "value.priv" / "value.shared"
1160 ; the only attributes that can be sorted
1161
1162 att-value = attrib SP value
1163
1164 attrib = astring
1165 ; dot-separated attribute name
1166 ; MUST NOT contain "*" or "%"
1167
1168
1169
1170
1171
1172 <span class="grey">Daboo &amp; Gellens Experimental [Page 21]</span></pre>
1173 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-22" ></span>
1174 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
1175
1176
1177 attribs = attrib / "(" attrib *(SP attrib) ")"
1178 ; one or more attribute specifiers
1179
1180 capability =/ "ANNOTATE-EXPERIMENT-1"
1181 ; defines the capability for this extension
1182
1183 entries = entry-match /
1184 "(" entry-match *(SP entry-match) ")"
1185
1186 entry = astring
1187 ; slash-separated path to entry
1188 ; MUST NOT contain "*" or "%"
1189
1190 entry-att = entry SP "(" att-value *(SP att-value) ")"
1191
1192 entry-match = list-mailbox
1193 ; slash-separated path to entry
1194 ; MAY contain "*" or "%" for use as wild cards
1195
1196 fetch-att =/ "ANNOTATION" SP "(" entries SP attribs ")"
1197 ; modifies original IMAP fetch-att
1198
1199 msg-att-dynamic =/ "ANNOTATION" SP
1200 ( "(" entry-att *(SP entry-att) ")" /
1201 "(" entry *(SP entry) ")" )
1202 ; extends FETCH response with annotation data
1203
1204 resp-text-code =/ "ANNOTATE" SP "TOOBIG" /
1205 "ANNOTATE" SP "TOOMANY" /
1206 "ANNOTATIONS" SP ann-size
1207 ; new response codes
1208
1209 search-key =/ "ANNOTATION" SP entry-match SP att-search
1210 SP value
1211 ; modifies original IMAP search-key
1212
1213 select-param =/ "ANNOTATE"
1214 ; defines the select parameter used with
1215 ; ANNOTATE extension
1216
1217 sort-key =/ "ANNOTATION" SP entry SP att-sort
1218 ; modifies original sort-key
1219
1220 store-att-flags =/ att-annotate
1221 ; modifies original IMAP STORE command
1222
1223 value = nstring / literal8
1224
1225
1226
1227
1228 <span class="grey">Daboo &amp; Gellens Experimental [Page 22]</span></pre>
1229 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-23" ></span>
1230 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
1231
1232
1233 <span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>. IANA Considerations</span>
1234
1235 Entry names MUST be specified in a standards track or IESG approved
1236 experimental RFC, or fall under the vendor namespace. Vendor names
1237 MUST be registered.
1238
1239 Attribute names MUST be specified in a standards track or IESG
1240 approved experimental RFC.
1241
1242 Each entry registration MUST include a content-type that is used to
1243 indicate the nature of the annotation value. Where applicable, a
1244 charset parameter MUST be included with the content-type.
1245
1246 <span class="h3"><a class="selflink" id="section-6.1" href="#section-6.1">6.1</a>. Entry and Attribute Registration Template</span>
1247
1248 To: [email protected]
1249 Subject: IMAP Annotate Registration
1250
1251 Please register the following IMAP Annotate item:
1252
1253 [] Entry [] Attribute
1254
1255 Name: ______________________________
1256
1257 Description: _______________________
1258
1259 ____________________________________
1260
1261 ____________________________________
1262
1263 Content-Type:_______________________
1264
1265 Contact person: ____________________
1266
1267 email: ____________________
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284 <span class="grey">Daboo &amp; Gellens Experimental [Page 23]</span></pre>
1285 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-24" ></span>
1286 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
1287
1288
1289 <span class="h3"><a class="selflink" id="section-6.2" href="#section-6.2">6.2</a>. Entry Registrations</span>
1290
1291 The following templates specify the IANA registrations of annotation
1292 entries specified in this document.
1293
1294 <span class="h4"><a class="selflink" id="section-6.2.1" href="#section-6.2.1">6.2.1</a>. /comment</span>
1295
1296 To: [email protected]
1297 Subject: IMAP Annotate Registration
1298
1299 Please register the following IMAP Annotate item:
1300
1301 [<a id="ref-X">X</a>] Entry [] Attribute
1302
1303 Name: /comment
1304
1305 Description: Defined in IMAP ANNOTATE extension document.
1306
1307 Content-Type: text/plain; charset=utf-8
1308
1309 Contact person: Cyrus Daboo
1310
1311 email: [email protected]
1312
1313 <span class="h4"><a class="selflink" id="section-6.2.2" href="#section-6.2.2">6.2.2</a>. /flags</span>
1314
1315 To: [email protected]
1316 Subject: IMAP Annotate Registration
1317
1318 Please register the following IMAP Annotate item:
1319
1320 [<a id="ref-X">X</a>] Entry [] Attribute
1321
1322 Name: /flags
1323
1324 Description: Reserved entry hierarchy.
1325
1326 Content-Type: -
1327
1328 Contact person: Cyrus Daboo
1329
1330 email: [email protected]
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340 <span class="grey">Daboo &amp; Gellens Experimental [Page 24]</span></pre>
1341 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-25" ></span>
1342 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
1343
1344
1345 <span class="h4"><a class="selflink" id="section-6.2.3" href="#section-6.2.3">6.2.3</a>. /altsubject</span>
1346
1347 To: [email protected]
1348 Subject: IMAP Annotate Registration
1349
1350 Please register the following IMAP Annotate item:
1351
1352 [<a id="ref-X">X</a>] Entry [] Attribute
1353
1354 Name: /altsubject
1355
1356 Description: Defined in IMAP ANNOTATE extension document.
1357
1358 Content-Type: text/plain; charset=utf-8
1359
1360 Contact person: Cyrus Daboo
1361
1362 email: [email protected]
1363
1364 <span class="h4"><a class="selflink" id="section-6.2.4" href="#section-6.2.4">6.2.4</a>. /&lt;section-part&gt;/comment</span>
1365
1366 To: [email protected]
1367 Subject: IMAP Annotate Registration
1368
1369 Please register the following IMAP Annotate item:
1370
1371 [<a id="ref-X">X</a>] Entry [] Attribute
1372
1373 Name: /&lt;section-part&gt;/comment
1374
1375 Description: Defined in IMAP ANNOTATE extension document.
1376
1377 Content-Type: text/plain; charset=utf-8
1378
1379 Contact person: Cyrus Daboo
1380
1381 email: [email protected]
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396 <span class="grey">Daboo &amp; Gellens Experimental [Page 25]</span></pre>
1397 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-26" ></span>
1398 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
1399
1400
1401 <span class="h4"><a class="selflink" id="section-6.2.5" href="#section-6.2.5">6.2.5</a>. /&lt;section-part&gt;/flags/seen</span>
1402
1403 To: [email protected]
1404 Subject: IMAP Annotate Registration
1405
1406 Please register the following IMAP Annotate item:
1407
1408 [<a id="ref-X">X</a>] Entry [] Attribute
1409
1410 Name: /&lt;section-part&gt;/flags/seen
1411
1412 Description: Defined in IMAP ANNOTATE extension document.
1413
1414 Content-Type: text/plain; charset=utf-8
1415
1416 Contact person: Cyrus Daboo
1417
1418 email: [email protected]
1419
1420 <span class="h4"><a class="selflink" id="section-6.2.6" href="#section-6.2.6">6.2.6</a>. /&lt;section-part&gt;/flags/answered</span>
1421
1422 To: [email protected]
1423 Subject: IMAP Annotate Registration
1424
1425 Please register the following IMAP Annotate item:
1426
1427 [<a id="ref-X">X</a>] Entry [] Attribute
1428
1429 Name: /&lt;section-part&gt;/flags/answered
1430
1431 Description: Defined in IMAP ANNOTATE extension document.
1432
1433 Content-Type: text/plain; charset=utf-8
1434
1435 Contact person: Cyrus Daboo
1436
1437 email: [email protected]
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452 <span class="grey">Daboo &amp; Gellens Experimental [Page 26]</span></pre>
1453 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-27" ></span>
1454 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
1455
1456
1457 <span class="h4"><a class="selflink" id="section-6.2.7" href="#section-6.2.7">6.2.7</a>. /&lt;section-part&gt;/flags/flagged</span>
1458
1459 To: [email protected]
1460 Subject: IMAP Annotate Registration
1461
1462 Please register the following IMAP Annotate item:
1463
1464 [<a id="ref-X">X</a>] Entry [] Attribute
1465
1466 Name: /&lt;section-part&gt;/flags/flagged
1467
1468 Description: Defined in IMAP ANNOTATE extension document.
1469
1470 Content-Type: text/plain; charset=utf-8
1471
1472 Contact person: Cyrus Daboo
1473
1474 email: [email protected]
1475
1476 <span class="h4"><a class="selflink" id="section-6.2.8" href="#section-6.2.8">6.2.8</a>. /&lt;section-part&gt;/flags/forwarded</span>
1477
1478 To: [email protected]
1479 Subject: IMAP Annotate Registration
1480
1481 Please register the following IMAP Annotate item:
1482
1483 [<a id="ref-X">X</a>] Entry [] Attribute
1484
1485 Name: /&lt;section-part&gt;/flags/forwarded
1486
1487 Description: Defined in IMAP ANNOTATE extension document.
1488
1489 Content-Type: text/plain; charset=utf-8
1490
1491 Contact person: Cyrus Daboo
1492
1493 email: [email protected]
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508 <span class="grey">Daboo &amp; Gellens Experimental [Page 27]</span></pre>
1509 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-28" ></span>
1510 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
1511
1512
1513 <span class="h3"><a class="selflink" id="section-6.3" href="#section-6.3">6.3</a>. Attribute Registrations</span>
1514
1515 The following templates specify the IANA registrations of annotation
1516 attributes specified in this document.
1517
1518 <span class="h4"><a class="selflink" id="section-6.3.1" href="#section-6.3.1">6.3.1</a>. value</span>
1519
1520 To: [email protected]
1521 Subject: IMAP Annotate Registration
1522
1523 Please register the following IMAP Annotate item:
1524
1525 [] Entry [<a href="#ref-X">X</a>] Attribute
1526
1527 Name: value
1528
1529 Description: Defined in IMAP ANNOTATE extension document.
1530
1531 Contact person: Cyrus Daboo
1532
1533 email: [email protected]
1534
1535 <span class="h4"><a class="selflink" id="section-6.3.2" href="#section-6.3.2">6.3.2</a>. size</span>
1536
1537 To: [email protected]
1538 Subject: IMAP Annotate Registration
1539
1540 Please register the following IMAP Annotate item:
1541
1542 [] Entry [<a href="#ref-X">X</a>] Attribute
1543
1544 Name: size
1545
1546 Description: Defined in IMAP ANNOTATE extension document.
1547
1548 Contact person: Cyrus Daboo
1549
1550 email: [email protected]
1551
1552 <span class="h3"><a class="selflink" id="section-6.4" href="#section-6.4">6.4</a>. Capability Registration</span>
1553
1554 This document registers "ANNOTATE-EXPERIMENT-1" as an IMAPEXT
1555 capability.
1556
1557
1558
1559
1560
1561
1562
1563
1564 <span class="grey">Daboo &amp; Gellens Experimental [Page 28]</span></pre>
1565 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-29" ></span>
1566 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
1567
1568
1569 <span class="h2"><a class="selflink" id="section-7" href="#section-7">7</a>. Internationalization Considerations</span>
1570
1571 Annotations may contain values that include text strings, and both
1572 searching and sorting are possible with annotations. Servers MUST
1573 follow standard IMAP text normalization, character set conversion,
1574 and collation rules when such operations are carried out, as would be
1575 done for other textual fields being searched or sorted on.
1576
1577 <span class="h2"><a class="selflink" id="section-8" href="#section-8">8</a>. Security Considerations</span>
1578
1579 Annotations whose values are intended to remain private MUST be
1580 stored in ".priv" values instead of ".shared" values, which may be
1581 accessible to other users.
1582
1583 Excluding the above issues, the ANNOTATE extension does not raise any
1584 security considerations that are not present in the base IMAP
1585 protocol; these issues are discussed in [<a href="./rfc3501" title="&quot;INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1&quot;">RFC3501</a>].
1586
1587 <span class="h2"><a class="selflink" id="section-9" href="#section-9">9</a>. References</span>
1588
1589 <span class="h3"><a class="selflink" id="section-9.1" href="#section-9.1">9.1</a>. Normative References</span>
1590
1591 [<a id="ref-RFC2086">RFC2086</a>] Myers, J., "IMAP4 ACL extension", <a href="./rfc2086">RFC 2086</a>, January 1997.
1592
1593 [<a id="ref-RFC2119">RFC2119</a>] Bradner, S., "Key words for use in RFCs to Indicate
1594 Requirement Levels", <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>, March 1997.
1595
1596 [<a id="ref-RFC2244">RFC2244</a>] Newman, C. and J. Myers, "ACAP -- Application
1597 Configuration Access Protocol", <a href="./rfc2244">RFC 2244</a>, November 1997.
1598
1599 [<a id="ref-RFC3501">RFC3501</a>] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
1600 4rev1", <a href="./rfc3501">RFC 3501</a>, March 2003.
1601
1602 [<a id="ref-RFC3502">RFC3502</a>] Crispin, M., "Internet Message Access Protocol (IMAP) -
1603 MULTIAPPEND Extension", <a href="./rfc3502">RFC 3502</a>, March 2003.
1604
1605 [<a id="ref-RFC3629">RFC3629</a>] Yergeau, F., "UTF-8, a transformation format of ISO
1606 10646", STD 63, <a href="./rfc3629">RFC 3629</a>, November 2003.
1607
1608 [<a id="ref-RFC4314">RFC4314</a>] Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
1609 <a href="./rfc4314">RFC 4314</a>, December 2005.
1610
1611 [<a id="ref-RFC4466">RFC4466</a>] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
1612 ABNF", <a href="./rfc4466">RFC 4466</a>, April 2006.
1613
1614 [<a id="ref-RFC5234">RFC5234</a>] Crocker, D., Ed., and P. Overell, "Augmented BNF for
1615 Syntax Specifications: ABNF", STD 68, <a href="./rfc5234">RFC 5234</a>, January
1616 2008.
1617
1618
1619
1620 <span class="grey">Daboo &amp; Gellens Experimental [Page 29]</span></pre>
1621 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-30" ></span>
1622 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
1623
1624
1625 [<a id="ref-RFC5256">RFC5256</a>] Crispin, M. and K. Murchison, "Internet Message Access
1626 Protocol - SORT and THREAD Extensions", <a href="./rfc5256">RFC 5256</a>, June
1627 2008.
1628
1629 <span class="h3"><a class="selflink" id="section-9.2" href="#section-9.2">9.2</a>. Informative References</span>
1630
1631 [<a id="ref-RFC4551">RFC4551</a>] Melnikov, A. and S. Hole, "IMAP Extension for Conditional
1632 STORE Operation or Quick Flag Changes Resynchronization",
1633 <a href="./rfc4551">RFC 4551</a>, June 2006.
1634
1635 <span class="h2"><a class="selflink" id="section-10" href="#section-10">10</a>. Acknowledgments</span>
1636
1637 Many thanks to Chris Newman for his detailed comments on the first
1638 draft of this document, and to the participants at the ACAP working
1639 dinner in Pittsburgh. The participants of the IMAPext working group
1640 made significant contributions to this work.
1641
1642 Authors' Addresses
1643
1644 Cyrus Daboo
1645 Apple Inc.
1646 1 Infinite Loop
1647 Cupertino, CA 95014
1648 USA
1649
1650 EMail: [email protected]
1651 URI: <a href="http://www.apple.com/">http://www.apple.com/</a>
1652
1653
1654 Randall Gellens
1655 QUALCOMM Incorporated
1656 5775 Morehouse Dr.
1657 San Diego, CA 92121-2779
1658 USA
1659
1660 EMail: [email protected]
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676 <span class="grey">Daboo &amp; Gellens Experimental [Page 30]</span></pre>
1677 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-31" ></span>
1678 <span class="grey"><a href="./rfc5257">RFC 5257</a> IMAP ANNOTATE Extension June 2008</span>
1679
1680
1681 Full Copyright Statement
1682
1683 Copyright (C) The IETF Trust (2008).
1684
1685 This document is subject to the rights, licenses and restrictions
1686 contained in <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a>, and except as set forth therein, the authors
1687 retain all their rights.
1688
1689 This document and the information contained herein are provided on an
1690 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
1691 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
1692 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
1693 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
1694 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
1695 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1696
1697 Intellectual Property
1698
1699 The IETF takes no position regarding the validity or scope of any
1700 Intellectual Property Rights or other rights that might be claimed to
1701 pertain to the implementation or use of the technology described in
1702 this document or the extent to which any license under such rights
1703 might or might not be available; nor does it represent that it has
1704 made any independent effort to identify any such rights. Information
1705 on the procedures with respect to rights in RFC documents can be
1706 found in <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a> and <a href="https://www.rfc-editor.org/bcp/bcp79">BCP 79</a>.
1707
1708 Copies of IPR disclosures made to the IETF Secretariat and any
1709 assurances of licenses to be made available, or the result of an
1710 attempt made to obtain a general license or permission for the use of
1711 such proprietary rights by implementers or users of this
1712 specification can be obtained from the IETF on-line IPR repository at
1713 <a href="http://www.ietf.org/ipr">http://www.ietf.org/ipr</a>.
1714
1715 The IETF invites any interested party to bring to its attention any
1716 copyrights, patents or patent applications, or other proprietary
1717 rights that may cover technology that may be required to implement
1718 this standard. Please address the information to the IETF at
1719 [email protected].
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732 Daboo &amp; Gellens Experimental [Page 31]
1733 </pre>