idnits 2.17.1 draft-ietf-imapext-annotate-16.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 1528. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1539. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1546. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1552. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([ANNOTATETOOBIG], [ANNOTATETOOMANY]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 2006) is 6463 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'ANNOTATE TOOBIG' is mentioned on line 173, but not defined == Missing Reference: 'ANNOTATE TOOMANY' is mentioned on line 173, but not defined == Missing Reference: 'READ-WRITE' is mentioned on line 637, but not defined == Missing Reference: 'READ-ONLY' is mentioned on line 626, but not defined == Missing Reference: 'UNSEEN 10268' is mentioned on line 732, but not defined == Missing Reference: 'UIDVALIDITY 890061587' is mentioned on line 733, but not defined == Missing Reference: 'UIDNEXT 34643' is mentioned on line 734, but not defined == Missing Reference: 'X' is mentioned on line 1419, but not defined == Outdated reference: A later version (-20) exists of draft-ietf-imapext-sort-17 ** Obsolete normative reference: RFC 2086 (Obsoleted by RFC 4314) ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 3501 (Obsoleted by RFC 9051) -- Obsolete informational reference (is this intentional?): RFC 4551 (Obsoleted by RFC 7162) Summary: 7 errors (**), 0 flaws (~~), 10 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 IMAP Extensions Working Group C. Daboo 3 Internet-Draft Apple Computer 4 Intended status: Informational R. Gellens 5 Expires: February 2, 2007 QUALCOMM Incorporated 6 August 2006 8 IMAP ANNOTATE Extension 9 draft-ietf-imapext-annotate-16 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on February 2, 2007. 36 Copyright Notice 38 Copyright (C) The Internet Society (2006). 40 Abstract 42 The ANNOTATE extension to the Internet Message Access Protocol 43 permits clients and servers to maintain "meta data" for messages, or 44 individual message parts, stored in a mailbox on the server. For 45 example, this can be used to attach comments and other useful 46 information to a message. It is also possible to attach annotations 47 to specific parts of a message, so that, for example, they could be 48 marked as seen or important, or a comment added. 50 Change History (to be removed prior to publication as an RFC) 52 Changes from -15 to -16: 53 1. Updated to rfc 4551 reference. 54 2. Updated to rfc 4466 reference. 55 3. Reworded first sentence of 4.2. 56 4. Added proper description of body part flag meaning. 57 5. Added text about 0 for size and NIL for value of non-existent 58 entries. 59 6. Added note about CONDSTORE behavior in 5.5. 60 7. Reworded first sentence of 5.1 for consistency with base spec 61 elements. 62 8. Various spelling fixes. 64 Changes from -14 to -15: 65 1. Updated to rfc 4314 reference. 66 2. Removed Content-Language value and reference. 67 3. Added statement about experimental status. 68 4. Changed to experimental capability name. 69 5. Removed ability to sort on size attribute. 70 6. Expanded abstract. 72 Changes from -13 to -14: 73 1. Changed 'string' formal syntax to 'list-mailbox' and 'astring' 74 for entry/attribute names. 75 2. Updated examples to match new astring syntax. 76 3. Now requires explicit use of .priv or .shared in SORT. 77 4. Removed requirement that 'n' right only be present if 'r' right 78 is also present. 79 5. Changed ANNOTATESIZE response to ANNOTATIONS response. 80 6. Allow servers to indicate that they do not support private 81 annotations. 82 7. Added example for extended SELECT including ANNOTATIONS response 83 code. 84 8. Removed content-type attribute. 85 9. Removed display-name attribute. 86 10. Prevent use of * and % wildcards in attributes. 87 11. Only allow "value" attributes in SEARCH. 88 12. Only allow "value" or "size" attributes in SORT. 89 13. Removed vendor attributes. 90 14. Removed IMAP flags, though the /flags entry path is reserved. 91 15. Added internationalization considerations. 93 Changes from -12 to -13: 94 1. Sync with change from DC meeting wrt 'r' right for both read and 95 write of .priv. 97 2. Add text about 'n' right being a 'shared flag right' as defined 98 in 2086upd. 99 3. Allow NIL in //flags entries. 100 4. Expand abstract to also indicate that annotations can apply on a 101 per-body part basis as well as per message. 102 5. Fix resp-text-code to use nil instead of "NIL". 103 6. Use double-quotes consistently around ANNOTATESIZE etc. 104 7. Fix typos. 105 8. Remove redundant second para of Introduction. 106 9. Added 'Conventions' section with RFC2119 reference.. 107 10. Describe S:, C: example behavior in conventions section.. 108 11. Clarify that new rights must also be present if only old ACL is 109 present. 110 12. Entry/attributes MUST NOT contain consecutive or trailing '/' or 111 '.'. 112 13. Clarify default charset for content-type text/plain. 113 14. Recommend use of utf-8 for all non-ascii text. 114 15. Clarify terminology of ANNOTATESIZE response code. 115 16. Require servers to return ANNOTATESIZE on SELECT. 116 17. Change an example to use UID FETCH for variety. 117 18. Clarify what to do about annotations exceeding allowed 118 ANNOTATESIZE when doing copy. 119 19. Use ABNFext document for extended SELECT etc. 120 20. Remove RFC1891 reference. 121 21. capability syntax extension. 122 22. Comment on validation content-type attribute. 123 23. Added recommended content-type in IANA registration. 124 24. Added use of literal8 for values. 125 25. Prevent use of 'shared' and 'priv' as separate hierarchy 126 components. 127 26. Restrict entry/attribute names to ascii and added display-name 128 attribute. 129 27. Remove references to CATENATE and use ABNFext for extended 130 APPEND syntax. 132 Changes from -11 to -12: 133 1. Fixed raw XML in formal syntax. 134 2. Fixed double \ in IANA section titles. 135 3. Fixed APPEND formal syntax. 136 4. Added annotations to CATENATE extension. 137 5. Reworded text for unsolicited responses. 138 6. Fixed formal syntax for fetch responses to extend base spec item. 140 Changes from -10 to -11: 141 1. Flags are now read-only and exactly match their IMAP 142 counterparts. 144 2. Added new ACL bits for annotations. 145 3. Revise security considerations. 146 4. Fixed some references. 148 Changes from -09 to -10: 149 1. Added Content-Language value. 150 2. Added IANA registrations for entries/attributes in this document. 152 Changes from -08 to -09: 153 1. Fix formatting, ID nits etc. 154 2. Fix subject -> altsubject in examples. 155 3. Added text to SELECT/EXAMINE optional parameter definition to 156 indicate that the option could trigger a global state change or a 157 mailbox specific change. 158 4. Changed entry/attribute names to be case-sensitive to avoid case 159 mapping issues with utf8 text. 160 5. Clarify COPY interaction to indicate that only the current user's 161 '.priv's are copied, not the '.priv's of other users. 163 Changes from -07 to -08: 164 1. ANNOTATESIZE response changed to use "NIL" for a mailbox that 165 does not support any type of annotations, and "0" for a mailbox 166 that only supports read-only annotations. 168 Changes from -06 to -07: 169 1. Added text to state entry and attribute names are always case- 170 insensitive. 171 2. Removed top-level entry namespace. 172 3. Added server accept minima for annotation size and count. 173 4. Added [ANNOTATE TOOBIG] & [ANNOTATE TOOMANY] response codes. 174 5. Added [ANNOTATESIZE <>] response code. 175 6. Added comment on suggested CONDSTORE support. 176 7. Modified append behavior to account for MULTIAPPEND. 177 8. Tweaked ABNF. 179 Changes from -05 to -06: 180 1. Split references into Normative and Informative. 181 2. Reworked flags to allow IMAP4 flag prefix to appear in annotation 182 name. 183 3. Removed smtp-envelope annotation - a future extension can add 184 this. 185 4. Changed subject to altsubject. 186 5. Added $MDNSent flag and reference to document. 187 6. Cleaned up formal syntax to use IMAP string type for entry and 188 attributes, with requirements on how the string is formatted. 189 7. Use of ACAP vendor subtree registry for vendor tokens. 191 8. Fixed STORE syntax. 193 Changes from -04 to -05: 194 1. Fixed examples to match formal syntax for FETCH responses where 195 parenthesis do not appear around entry-att items. 197 Changes from -03 to -04: 198 1. Fixed attrib/attrib-match grammar to use "." instead of "/". 199 2. Add text for server to reject unknown . 200 3. Do not allow empty part-specifier. 201 4. Store NIL to value to delete. 202 5. Comment on COPY interaction with ANNOTATE. 203 6. Added comment that IMAP flags are mapped one-to-one with their 204 corresponding FLAGS items. 205 7. Added comment that the recent flag annotation is read-only. 207 Changes from -02 to -03: 208 1. Removed reference to status modtime item. 209 2. Added missing 'notify' and 'ret' dsn annotations for /message/ 210 smtp-envelope. 211 3. Added requirement to store data permanently - no 'session only' 212 annotations. 213 4. Removed Access Control section. Replaced with comments on read- 214 only/read-write mailboxes and storing private or shared 215 annotations. 216 5. Removed STORE to default .priv or .shared. 217 6. Added section on optional select parameters. 219 Changes from -01 to -02: 220 1. Now require .priv or .shared on store operations. 222 Changes from -00 to -01: 223 1. MODTIME moved to its own draft, which this draft now depends on. 224 Thus, Conditional Annotation STORE and related items deleted from 225 this draft. 226 2. Private versus Shared Annotations: both are possible (separately 227 addressable using ".priv" and ".shared" suffixes). There is a 228 per-mailbox setting for the default. It is an open issue how 229 this is viewed or changed by the client. 230 3. In ACLs, the "w" right is needed to updated shared state; the "s" 231 right is needed to update private state. 232 4. Various clarifications and text modifications. 233 5. Added 'forwarded' flag for message parts. 235 Changes from pre-imapext to -00: 236 1. Clarified text describing attributions, entries, and attributes. 238 2. Changed 'modifiedsince' to 'modtime'; referenced ACAP spec. 239 3. Deleted 'queued' flag. 240 4. Expanded and explained smtp-envelope entry. 241 5. Restricted including ANNOTATION data in unsolicited responses 242 until the client uses it first. (Open issue as to if needed). 243 6. Examples now only use valid entries and attributes. 244 7. Updated Security Considerations. 245 8. Content-Type now defaults to text/plain. 246 9. Open Issue: Shared vs. private annotations. 247 10. Open issue: Annotation Modtime untagged response or VALIDTIME 248 FETCH data. 249 11. Open issue: Conditional annotation STORE. 250 12. ANNOTATION criterion available if both "ANNOTATE" and "SORT" in 251 CAPABILITY command response. 252 13. Prohibition on annotations in lieu of base spec functionality. 253 14. Specified required ACL rights. 254 15. ANNOTATION message data item in APPEND. 255 16. ANNOTATION-MODTIME message data item in STATUS. 256 17. Replaced ATOM_CHAR with utf8-char. 257 18. Updated other ABNF entries. 259 Table of Contents 261 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 8 262 2. Working Group Note on Status . . . . . . . . . . . . . . . . . 8 263 3. Conventions Used in This Document . . . . . . . . . . . . . . 9 264 4. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . 9 265 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 9 266 4.2. Namespace of entries and attributes . . . . . . . . . . . 9 267 4.2.1. Entry Names . . . . . . . . . . . . . . . . . . . . . 10 268 4.2.2. Attribute Names . . . . . . . . . . . . . . . . . . . 12 269 4.3. Private versus Shared . . . . . . . . . . . . . . . . . . 12 270 4.4. Access Control . . . . . . . . . . . . . . . . . . . . . . 13 271 4.5. Access to Standard IMAP Flags and Keywords . . . . . . . . 16 272 5. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 16 273 5.1. General Considerations . . . . . . . . . . . . . . . . . . 16 274 5.2. ANNOTATE parameter with the SELECT/EXAMINE commands . . . 17 275 5.3. ANNOTATION Message Data Item in FETCH Command . . . . . . 17 276 5.4. ANNOTATION Message Data Item in FETCH Response . . . . . . 19 277 5.5. ANNOTATION Message Data Item in STORE . . . . . . . . . . 21 278 5.6. ANNOTATION interaction with COPY . . . . . . . . . . . . . 22 279 5.7. ANNOTATION Message Data Item in APPEND . . . . . . . . . . 23 280 5.8. ANNOTATION Criterion in SEARCH . . . . . . . . . . . . . . 23 281 5.9. ANNOTATION Key in SORT . . . . . . . . . . . . . . . . . . 24 282 5.10. New ACL Rights . . . . . . . . . . . . . . . . . . . . . . 25 283 6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 25 284 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 285 7.1. Entry and Attribute Registration Template . . . . . . . . 27 286 7.2. Entry Registrations . . . . . . . . . . . . . . . . . . . 28 287 7.2.1. /comment . . . . . . . . . . . . . . . . . . . . . . . 28 288 7.2.2. /flags . . . . . . . . . . . . . . . . . . . . . . . . 28 289 7.2.3. /altsubject . . . . . . . . . . . . . . . . . . . . . 29 290 7.2.4. //comment . . . . . . . . . . . . . . . 29 291 7.2.5. //flags/seen . . . . . . . . . . . . . . 30 292 7.2.6. //flags/answered . . . . . . . . . . . . 30 293 7.2.7. //flags/flagged . . . . . . . . . . . . 31 294 7.2.8. //flags/forwarded . . . . . . . . . . . 31 295 7.3. Attribute Registrations . . . . . . . . . . . . . . . . . 31 296 7.3.1. value . . . . . . . . . . . . . . . . . . . . . . . . 32 297 7.3.2. size . . . . . . . . . . . . . . . . . . . . . . . . . 32 298 8. Internationalization Considerations . . . . . . . . . . . . . 32 299 9. Security Considerations . . . . . . . . . . . . . . . . . . . 32 300 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 33 301 10.1. Normative References . . . . . . . . . . . . . . . . . . . 33 302 10.2. Informative References . . . . . . . . . . . . . . . . . . 33 303 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 34 304 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 34 305 Intellectual Property and Copyright Statements . . . . . . . . . . 35 307 1. Introduction and Overview 309 The ANNOTATE extension is present in any IMAP [RFC3501] 310 implementation which returns "ANNOTATE-EXPERIMENT-1" as one of the 311 supported capabilities in the CAPABILITY response. 313 This extension makes the following changes to the IMAP protocol: 315 a. adds a new ANNOTATION message data item for use in FETCH 316 b. adds a new ANNOTATION message data item for use in STORE 317 c. adds a new ANNOTATION search criterion for use in SEARCH 318 d. adds a new ANNOTATION sort key for use in SORT extension 319 e. adds a new ANNOTATION data item for use in APPEND 320 f. adds a new requirement on the COPY command 321 g. adds a new ANNOTATE parameter for use with the SELECT/EXAMINE 322 commands 323 h. adds two new response codes to indicate store failures of 324 annotations. 325 i. adds a new untagged response code for the SELECT or EXAMINE 326 commands to indicate the maximum size. 327 j. adds a new ACL "bit" for use with the ACL extensions [RFC2086] 328 and [RFC4314] . 330 The data model used for the storage of annotations is based on that 331 of the Application Configuration Access Protocol [RFC2244]. Note 332 that there is no inheritance in annotations. 334 If a server supports annotations, then it MUST store all annotation 335 data permanently, i.e. there is no concept of "session only" 336 annotations that would correspond to the behavior of "session" flags 337 as defined in the IMAP base specification. 339 In order to provide optimum support for a disconnected client (one 340 that needs to synchronize annotations for use when offline), servers 341 SHOULD also support the Conditional STORE [RFC4551] extension. 343 The rest of this document describes the data model and protocol 344 changes more rigorously. 346 2. Working Group Note on Status 348 The IMAP Extensions Working Group, which produced this specification, 349 has felt it important to first gain implementation experience with 350 this specification before submitting it as a 'proposed standard' for 351 more general deployment, and therefore suggests that it be published 352 as Experimental. As such the Working Group strongly encourages 353 implementers to implement this specification as-is and provide their 354 valuable feedback on any problems or issues found when doing that or 355 when attempting to interoperate with other products. 357 Implementers should be aware that this specification may change in an 358 incompatible manner when going to 'proposed standard' status. 359 However, any incompatible changes will result in a new capability 360 name being used to prevent problems with any deployments of the 361 experimental extension. 363 3. Conventions Used in This Document 365 In examples, "C:" and "S:" indicate lines sent by the client and 366 server respectively. 368 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 369 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 370 document are to be interpreted as described in [RFC2119]. 372 4. Data Model 374 4.1. Overview 376 The data model used in ANNOTATE is that of a uniquely named entry 377 which contains a set of standard attributes. A single coherent unit 378 of "meta data" for a message is stored as a single entry, made up of 379 several attributes. 381 For example, a comment annotation added to a message has an entry 382 name of "/comment". This entry is composed of several attributes 383 such as "value", "size", etc. which contain the properties and data 384 of the entry. 386 The protocol changes to IMAP described below allow a client to access 387 or change the values of any attributes in any entries in a message 388 annotation, assuming it has sufficient access rights to do so (see 389 Section 4.4 for specifics). 391 4.2. Namespace of entries and attributes 393 A message may contain zero or more annotations, each of which is a 394 single uniquely named entry. Each entry has a hierarchical name, 395 with each component of the name separated by a slash ("/"). An entry 396 name MUST NOT contain two consecutive "/" characters and MUST NOT end 397 with a "/" character. 399 Each entry is made up of a set of attributes. Each attribute has a 400 hierarchical name, with each component of the name separated by a 401 period ("."). An attribute name MUST NOT contain two consecutive "." 402 characters and MUST NOT end with a "." character. 404 The value of an attribute is "NIL" (has no value), or is a string of 405 zero or more octets. 407 Entry and attribute names MUST NOT contain asterisk ("*") or percent 408 ("%") characters and MUST NOT contain non-ASCII characters or the 409 NULL octet. Invalid entry or attribute names result in a BAD 410 response in any IMAP commands where they are used. 412 Attribute names MUST NOT contain any hierarchical components with the 413 names "priv" or "shared" as those have special meaning (see 414 Section 4.3). 416 Entry and attribute names are case-sensitive. 418 Use of control or punctuation characters in entry and attribute names 419 is strongly discouraged. 421 This specification defines an initial set of entry and attribute 422 names available for use in message annotations. In addition, an 423 extension mechanism is described to allow additional names to be 424 added as needed. 426 4.2.1. Entry Names 428 Entry names MUST be specified in a standards track or IESG approved 429 experimental RFC, or fall under the vendor namespace. See 430 Section 7.1 for the registration template. 432 / 433 Defines the top-level of entries associated with an entire 434 message. This entry itself does not contain any attributes. All 435 entries that start with a numeric character ("0" - "9") refer to 436 an annotation on a specific body part. All other entries are for 437 annotations on the entire message. 439 /comment 440 Defines a comment or note associated with an entire message. 442 /flags 443 This entry hierarchy is reserved for future use. 445 /altsubject 446 Contains text supplied by the message recipient, to be used by the 447 client instead of the original message Subject. 449 /vendor/ 450 Defines the top-level of entries associated with an entire message 451 as created by a particular product of some vendor. These sub- 452 entries can be used by vendors to provide client-specific 453 annotations. The vendor-token MUST be registered with IANA, using 454 the [RFC2244] vendor subtree registry. 456 / 457 Defines the top-level of entries associated with a specific body 458 part of a message. This entry itself does not contain any 459 attributes. The section-part is a numeric part specifier. Its 460 syntax is the same as the section-part ABNF element defined in 461 [RFC3501]. The server MUST return a BAD response if the client 462 uses an incorrect part specifier (either incorrect syntax or a 463 specifier referring to a non-existent part). The server MUST 464 return a BAD response if the client uses an empty part specifier 465 (which is used in IMAP to represent the entire message). 467 //comment 468 Defines a comment or note associated with a specific body part of 469 a message. 471 //flags 472 Defines the top-level of entries associated with flag state for a 473 specific body part of a message. All sub-entries are maintained 474 entirely by the client. There is no implicit change to any flag 475 by the server. 477 //flags/seen 478 This is similar to the IMAP \Seen flag except it applies to 479 only the body part referenced by the entry. 480 //flags/answered 481 This is similar to the IMAP \Answered flag except it applies 482 to only the body part referenced by the entry. 483 //flags/flagged 484 This is similar to the IMAP \Flagged flag except it applies 485 to only the body part referenced by the entry. 486 //flags/forwarded 487 This is similar to the IMAP $Forwarded keyword except it 488 applies to only the body part referenced by the entry. 490 Defines flags for a specific body part of a message. The "value" 491 attribute of each of the entries described above must be either 492 "1", "0" or "NIL". "1" corresponds to the flag being set. 494 //vendor/ 495 Defines the top-level of entries associated with a specific body 496 part of a message as created by a particular product of some 497 vendor. This entry can be used by vendors to provide client 498 specific annotations. The vendor-token MUST be registered with 499 IANA. 501 4.2.2. Attribute Names 503 Attribute names MUST be specified in a standards track or IESG 504 approved experimental RFC. See Section 7.1 for the registration 505 template. 507 All attribute names implicitly have a ".priv" and a ".shared" suffix 508 which maps to private and shared versions of the entry. Searching or 509 fetching without using either suffix includes both. The client MUST 510 specify either a ".priv" or ".shared" suffix when storing an 511 annotation or sorting on annotations. 513 value 514 A string or binary data representing the value of the annotation. 515 To delete an annotation, the client can store "NIL" into the 516 value. If the client requests the value attribute for a non- 517 existent entry, then the server MUST return "NIL" for the value. 518 The content represented by the string is determined by the 519 content-type used to register the entry (see Section 7.1 for entry 520 registration templates). Where applicable, the registered 521 content-type MUST include a charset parameter. Text values SHOULD 522 use the utf-8 [RFC3629] character set. 523 Note that binary data (data which may contain the NULL octet) is 524 allowed (e.g. for storing images etc), and this extension uses the 525 "literal8" syntax element [RFC4466] to allow such data to be 526 written to or read from the server. 528 size 529 The size of the value, in octets. Set automatically by the 530 server, read-only to clients. If the client requests the size 531 attribute for a non-existent entry, then the server MUST return 532 "0" (zero) for the size. 534 4.3. Private versus Shared 536 Some IMAP mailboxes are private, accessible only to the owning user. 537 Other mailboxes are not, either because the owner has set an ACL 538 [RFC4314] which permits access by other users, or because it is a 539 shared mailbox. 541 This raises the issue of shared versus private annotations. 543 If all annotations are private, it is impossible to set annotations 544 in a shared or otherwise non-private mailbox that are visible to 545 other users. This eliminates what could be a useful aspect of 546 annotations in a shared environment. An example of such use is a 547 shared IMAP folder containing bug reports. Engineers may want to use 548 annotations to add information to existing messages, indicate 549 assignments, status, etc. This use requires shared annotations. 551 If all annotations are shared, it is impossible to use annotations 552 for private notes on messages in shared mailboxes. Also, modifying 553 an ACL to permit access to a mailbox by other users may 554 unintentionally expose private information. 556 There are also situations in which both shared and private 557 annotations are useful. For example, an administrator may want to 558 set shared annotations on messages in a shared folder, which 559 individual users may wish to supplement with additional notes. 561 If shared and private annotations are to coexist, we need a clear way 562 to differentiate them. Also, it should be as easy as possible for a 563 client to access both and not overlook either. There is also a 564 danger in allowing a client to store an annotation without knowing if 565 it is shared or private. 567 This document proposes two standard suffixes for all attributes: 568 ".shared" and ".priv". A SEARCH or FETCH command which specifies 569 neither uses both. STORE, APPEND and SORT commands MUST explicitly 570 use ".priv" or ".shared" suffixes. 572 If the ANNOTATE extension is present, support for shared annotations 573 in servers is REQUIRED, whilst support for private annotations in 574 servers is OPTIONAL. This recognizes the fact that support for 575 private annotations may introduce significantly more complexity to a 576 server in terms of tracking ownership of the annotations, how quota 577 is determined for users based on their own annotations etc. Clients 578 that support the ANNOTATE extension MUST handle both shared and 579 private annotations. 581 4.4. Access Control 583 A user needs to have appropriate rights in order to read or write 584 ".priv" or ".shared" annotation values. How those rights are 585 calculated depends on whether the ACL [RFC2086] extension or its 586 update [RFC4314] is present or not. If a client attempts to store or 587 fetch an annotation to which they do not have the appropriate rights, 588 the server MUST respond with a NO response. 590 When the ACL extension is not present, access to annotation values is 591 governed by the nature of the selected state. In particular whether 592 the mailbox was SELECT'ed or EXAMINE'd in READ-ONLY or READ-WRITE 593 mode. 595 When the ACL extension is present, the server MUST recognize the new 596 ACL right "n", in addition to the ones defined by the ACL extension 597 itself. 599 The "r" right controls both read and write access to ".priv" 600 annotation values. When it is on, access to ".priv" annotations is 601 allowed, when it is off, access to ".priv" annotations is disallowed. 603 The "r" right controls only the read access for ".shared" annotation 604 values. When it is on, ".shared" annotations can be read, when it is 605 off, ".shared" annotations cannot be read. 607 The "n" right controls only the write access for ".shared" annotation 608 values. When it is on, ".shared" annotations can be changed or 609 created through either a STORE or APPEND command, when it is off, 610 ".shared" annotations cannot be changed or created. The "n" right 611 constitutes a "shared flag right" as defined in [RFC4314] Section 612 6.2. 614 A summary of all the access control restrictions is tabulated below 615 +---------------+---------------+-----------------------------------+ 616 | Server Type | Action on | Type of mailbox | 617 | | annotation | | 618 +===============+===============+===================================+ 619 | | | | 620 | | read .priv | Any mailbox that can be SELECTED | 621 | | values | or EXAMINED. | 622 | | | | 623 | +---------------+-----------------------------------+ 624 | | | | 625 | | write .priv | Any SELECTED [READ-WRITE] mailbox.| 626 | | values | SELECTED [READ-ONLY] mailboxes MAY| 627 | Server | | also permit writes. | 628 | without | | | 629 | ACL Extension +---------------+-----------------------------------+ 630 | | | | 631 | | read .shared | Any mailbox that can be SELECTED | 632 | | values | or EXAMINED. | 633 | | | | 634 | +---------------+-----------------------------------+ 635 | | | | 636 | | write .shared | Any mailbox that can be SELECTED | 637 | | values | or EXAMINED and is [READ-WRITE]. | 638 | | | | 639 +---------------+---------------+-----------------------------------+ 640 | | | | 641 | | read .priv | Any mailbox with the "r" | 642 | | values | ACL right. | 643 | | | | 644 | +---------------+-----------------------------------+ 645 | | | | 646 | | write .priv | Any mailbox with the "r" | 647 | Server | values | ACL right. | 648 | with | | | 649 | ACL Extension +---------------+-----------------------------------+ 650 | | | | 651 | | read .shared | Any mailbox with the "r" | 652 | | values | ACL right. | 653 | | | | 654 | +---------------+-----------------------------------+ 655 | | | | 656 | | write .shared | Any mailbox with the "n" | 657 | | values | ACL right. | 658 | | | | 659 +---------------+---------------+-----------------------------------+ 661 4.5. Access to Standard IMAP Flags and Keywords 663 Due to ambiguity of how private and shared values would map to the 664 base IMAP flag and keyword values, the ANNOTATE extension does not 665 expose IMAP flags or keywords as entries. However, the /flags 666 annotation entry is reserved for future use and MUST NOT be used by 667 clients or servers supporting this extension. 669 Clients that need to implement shared and private "flags" can create 670 their own annotation entries for those, completely bypassing the base 671 IMAP flag/keyword behavior. 673 5. IMAP Protocol Changes 675 5.1. General Considerations 677 Servers may be able to offer only a limited level of support for 678 annotations in mailboxes, and it is useful for clients to be able to 679 know what level of support is available. Servers MUST return an 680 ANNOTATIONS response code during the SELECT or EXAMINE command for a 681 mailbox to indicate the level of support. Possible data items used 682 with the ANNOTATIONS response code are: 684 "NONE" - this indicates that the mailbox being selected does not 685 support annotations at all. Clients MUST NOT attempt to use 686 annotation extensions in commands. 688 "READ-ONLY" - this indicates that the annotations supported by the 689 mailbox cannot be changed by the client. Clients MUST NOT attempt 690 to store annotations on any messages in a mailbox with this 691 response code. 693 "NOPRIVATE" - this indicates that the server does not support 694 private annotations on the mailbox. Only shared annotations are 695 supported. Clients SHOULD only attempt to read or store 696 annotations attributes with the ".shared" suffix. If a client 697 uses an attribute with the ".priv" suffix in a FETCH command, then 698 servers should return the attribute value in the FETCH response as 699 "NIL". If a client uses an attribute with the ".priv" suffix in a 700 STORE command (or an APPEND command targeted at the mailbox) then 701 the server MUST return a NO response. 703 numeric values - if servers support writable annotations, then the 704 server MUST indicate the maximum size for an annotation value by 705 providing the maximum size value in the response code. Clients 706 MUST NOT store annotation values of a size greater than the amount 707 indicated by the server. Servers MUST accept a minimum annotation 708 data size of at least 1024 bytes if annotations can be written. 710 In addition the server MAY limit the total number of annotations for 711 a single message. However, the server MUST provide a minimum 712 annotation count per message of at least 10. 714 5.2. ANNOTATE parameter with the SELECT/EXAMINE commands 716 The ANNOTATE extension defines a single optional SELECT parameter 717 [RFC4466] "ANNOTATE", which is used to turn on unsolicited responses 718 for annotations as described in Section 5.4. This optional parameter 719 results in a per-mailbox state change, i.e. it must be used in each 720 SELECT/EXAMINE command in order to be effective, irrespective of 721 whether it was used in a previous SELECT/EXAMINE during the same 722 session. 724 Example: 726 C: a SELECT INBOX (ANNOTATE) 727 S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen) 728 S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft 729 \Deleted \Seen \*)] 730 S: * 10268 EXISTS 731 S: * 1 RECENT 732 S: * OK [UNSEEN 10268] 733 S: * OK [UIDVALIDITY 890061587] 734 S: * OK [UIDNEXT 34643] 735 S: * OK [ANNOTATIONS 20480 NOPRIVATE] 736 S: a OK [READ-WRITE] Completed 738 In the above example, a SELECT command with the ANNOTATE parameter 739 is issued. The response from the server includes the required 740 ANNOTATIONS response that indicates that the server supports 741 annotations up to a maximum size of 20480 bytes and does not 742 support private annotations (only shared). 744 5.3. ANNOTATION Message Data Item in FETCH Command 746 This extension adds an ANNOTATION message data item to the FETCH 747 command. This allows clients to retrieve annotations for a range of 748 messages in the currently selected mailbox. 750 ANNOTATION 752 The ANNOTATION message data item, when used by the client in the 753 FETCH command, takes an entry specifier and an attribute 754 specifier. 756 Example: 758 C: a FETCH 1 (ANNOTATION (/comment value)) 759 S: * 1 FETCH (ANNOTATION (/comment 760 (value.priv "My comment" 761 value.shared "Group note"))) 762 S: a OK Fetch complete 764 In the above example, the content of the "value" attribute for the 765 "/comment" entry is requested by the client and returned by the 766 server. Since neither ".shared" nor ".priv" was specified, both 767 are returned. 769 "*" and "%" wild card characters can be used in entry specifiers to 770 match one or more characters at that position, with the exception 771 that "%" does not match the "/" hierarchy delimiter. Thus an entry 772 specifier of "/%" matches entries such as "/comment" and 773 "/altsubject", but not "/1/comment". 775 Example: 777 C: a UID FETCH 1123 (UID ANNOTATION 778 (/* (value.priv size.priv))) 779 S: * 12 FETCH (UID 1123 ANNOTATION 780 (/comment (value.priv "My comment" 781 size.priv "10") 782 /altsubject (value.priv "Rhinoceroses!" 783 size.priv "13") 784 /vendor/foobar/label.priv 785 (value.priv "label43" 786 size.priv "7") 787 /vendor/foobar/personality 788 (value.priv "Tallulah Bankhead" 789 size.priv "17"))) 790 S: a OK Fetch complete 792 In the above example, the contents of the private "value" and 793 "size" attributes for any entries in the "/" hierarchy are 794 requested by the client and returned by the server. 796 Example: 798 C: a FETCH 1 (ANNOTATION (/% value.shared)) 799 S: * 1 FETCH (ANNOTATION 800 (/comment (value.shared "Patch Mangler") 801 /altsubject (value.shared "Patches? We don't 802 need no steenkin patches!"))) 803 S: a OK Fetch complete 805 In the above example, the contents of the shared "value" 806 attributes for entries at the top level only of the "/" hierarchy 807 are requested by the client and returned by the server. 809 Entry and attribute specifiers can be lists of atomic specifiers, so 810 that multiple items of each type may be returned in a single FETCH 811 command. 813 Example: 815 C: a FETCH 1 (ANNOTATION 816 ((/comment /altsubject) value.priv)) 817 S: * 1 FETCH (ANNOTATION 818 (/comment (value.priv "What a chowder-head") 819 /altsubject (value.priv "How to crush beer cans"))) 820 S: a OK Fetch complete 822 In the above example, the contents of the private "value" 823 attributes for the two entries "/comment" and "/altsubject" are 824 requested by the client and returned by the server. 826 5.4. ANNOTATION Message Data Item in FETCH Response 828 The ANNOTATION message data item in the FETCH response displays 829 information about annotations in a message. 831 ANNOTATION parenthesized list 833 The response consists of a list of entries, each of which has a 834 list of attribute-value pairs. 836 Example: 838 C: a FETCH 1 (ANNOTATION (/comment value)) 839 S: * 1 FETCH (ANNOTATION (/comment 840 (value.priv "My comment" 841 value.shared NIL))) 842 S: a OK Fetch complete 844 In the above example, a single entry with a single attribute-value 845 pair is returned by the server. Since the client did not specify 846 a ".shared" or ".priv" suffix, both are returned. Only the 847 private attribute has a value (the shared value is "NIL"). 849 Example: 851 C: a FETCH 1 (ANNOTATION 852 ((/comment /altsubject) value)) 853 S: * 1 FETCH (ANNOTATION 854 (/comment (value.priv "My comment" 855 value.shared NIL) 856 /altsubject (value.priv "My subject" 857 value.shared NIL))) 858 S: a OK Fetch complete 860 In the above example, two entries each with a single attribute- 861 value pair are returned by the server. Since the client did not 862 specify a ".shared" or ".priv" suffix, both are returned. Only 863 the private attributes have values; the shared attributes are 864 "NIL". 866 Example: 868 C: a FETCH 1 (ANNOTATION 869 (/comment (value size))) 870 S: * 1 FETCH (ANNOTATION 871 (/comment 872 (value.priv "My comment" 873 value.shared NIL 874 size.priv "10" 875 size.shared "0"))) 876 S: a OK Fetch complete 878 In the above example, a single entry with two attribute-value 879 pairs is returned by the server. Since the client did not specify 880 a ".shared" or ".priv" suffix, both are returned. Only the 881 private attributes have values; the shared attributes are "NIL". 883 Servers SHOULD send ANNOTATION message data items in unsolicited 884 FETCH responses if an annotation entry is changed by a third-party, 885 and the ANNOTATE select parameter was used. This allows servers to 886 keep clients updated with changes to annotations by other clients. 888 Unsolicited ANNOTATION responses MUST NOT include ANNOTATION data 889 values - only the entry name of the ANNOTATION that has changed. 890 This restriction avoids sending ANNOTATION data values (which may be 891 large) to a client unless the client explicitly asks for the value. 893 Example: 895 C: a STORE 1 +FLAGS (\Seen) 896 S: * 1 FETCH (FLAGS (\Seen)) 897 ANNOTATION (/comment)) 898 S: a OK STORE complete 900 In the above example, an unsolicited ANNOTATION response is 901 returned during a STORE command. The unsolicited response 902 contains only the entry name of the annotation that changed, and 903 not its value. 905 5.5. ANNOTATION Message Data Item in STORE 907 ANNOTATION 909 Sets the specified list of entries by adding or replacing the 910 specified attributes with the values provided. Clients can use 911 "NIL" for values of attributes it wants to remove from entries. 913 The ANNOTATION message data item used with the STORE command has an 914 implicit ".SILENT" behavior. This means the server does not generate 915 an untagged FETCH in response to the STORE command and assumes that 916 the client updates its own cache if the command succeeds. Though 917 note, that if the Conditional STORE extension [RFC4551] is present, 918 then an untagged FETCH response with a MODSEQ data item will be 919 returned by the server as required by [RFC4551]. 921 If the server is unable to store an annotation because the size of 922 its value is too large, the server MUST return a tagged NO response 923 with a "[ANNOTATE TOOBIG]" response code. 925 If the server is unable to store a new annotation because the maximum 926 number of allowed annotations has already been reached, the server 927 MUST return a tagged NO response with a "[ANNOTATE TOOMANY]" response 928 code. 930 Example: 932 C: a STORE 1 ANNOTATION (/comment 933 (value.priv "My new comment")) 934 S: a OK Store complete 936 In the above example, the entry "/comment" is created (if not 937 already present) and the private attribute "value" with data set 938 to "My new comment" is created if not already present, or replaced 939 if it exists. 941 Example: 943 C: a STORE 1 ANNOTATION (/comment 944 (value.shared NIL)) 945 S: a OK Store complete 947 In the above example, the shared "value" attribute of the entry 948 "/comment" is removed by storing "NIL" into the attribute. 950 Multiple entries can be set in a single STORE command by listing 951 entry-attribute-value pairs in the list. 953 Example: 955 C: a STORE 1 ANNOTATION (/comment 956 (value.priv "Get tix Tuesday") 957 /altsubject 958 (value.priv "Wots On")) 959 S: a OK Store complete 961 In the above example, the entries "/comment" and "/altsubject" are 962 created (if not already present) and the private attribute "value" 963 is created for each entry if not already present, or replaced if 964 they exist. 966 Multiple attributes can be set in a single STORE command by listing 967 multiple attribute-value pairs in the entry list. 969 Example: 971 C: a STORE 1 ANNOTATION (/comment 972 (value.priv "My new comment" 973 value.shared "foo's bar")) 974 S: a OK Store complete 976 In the above example, the entry "/comment" is created (if not already 977 present) and the private and shared "value" attributes are created if 978 not already present, or replaced if they exist. 980 5.6. ANNOTATION interaction with COPY 982 The COPY command can be used to move messages from one mailbox to 983 another on the same server. Servers that support the ANNOTATION 984 extension MUST, for each message being copied, copy all ".priv" 985 annotation data for the current user only, and all ".shared" 986 annotation data along with the message to the new mailbox. The only 987 exceptions to this are if the destination mailbox permissions are 988 such that either the ".priv" or ".shared" annotations are not 989 allowed, or if the destination mailbox is of a type that does not 990 support annotations or does not support storing of annotations (a 991 mailbox that returns a "NONE" or "READ-ONLY" response code in its 992 ANNOTATIONS response), or if the destination mailbox cannot support 993 the size of a annotation because it exceeds the ANNOTATIONS value. 994 Servers MUST NOT copy ".priv" annotation data for users other than 995 the current user. 997 5.7. ANNOTATION Message Data Item in APPEND 999 ANNOTATION 1001 Sets the specified list of entries and attributes in the resulting 1002 message. 1004 The APPEND command can include annotations for the message being 1005 appended via the addition of a new append data item [RFC4466]. The 1006 new data item can also be used with the multi-append [RFC3502] 1007 extension that allows multiple messages to be appended via a single 1008 APPEND command. 1010 Example: 1012 C: a APPEND drafts ANNOTATION (/comment 1013 (value.priv "Don't send until I say so")) {310} 1014 S: + Ready for literal data 1015 C: MIME-Version: 1.0 1016 ... 1017 C: 1018 S: a OK APPEND completed 1020 In the above example, a comment with a private value is added to a 1021 new message appended to the mailbox. The ellipsis represents the 1022 bulk of the message. 1024 5.8. ANNOTATION Criterion in SEARCH 1026 ANNOTATION 1028 The ANNOTATION criterion for the SEARCH command allows a client to 1029 search for a specified string in the value of an annotation entry of 1030 a message. 1032 Messages that have annotations with entries matching and 1033 attributes matching and the specified string 1034 in their values are returned in the SEARCH results. The "*" 1035 character can be used in the entry name field to match any content in 1036 those items. The "%" character can be used in the entry name field 1037 to match a single level of hierarchy only. 1039 Only the "value", "value.priv" and "value.shared" attributes can be 1040 searched. Clients MUST NOT specify an attribute other than either 1041 "value", "value.priv" or "value.shared". Servers MUST return a BAD 1042 response if the client tries to search any other attribute. 1044 Example: 1046 C: a SEARCH ANNOTATION /comment value "IMAP4" 1047 S: * SEARCH 2 3 5 7 11 13 17 19 23 1048 S: a OK Search complete 1050 In the above example, the message numbers of any messages 1051 containing the string "IMAP4" in the shared or private "value" 1052 attribute of the "/comment" entry are returned in the search 1053 results. 1055 Example: 1057 C: a SEARCH ANNOTATION * value.priv "IMAP4" 1058 S: * SEARCH 1 2 3 5 8 13 21 34 1059 S: a OK Search complete 1061 In the above example, the message numbers of any messages 1062 containing the string "IMAP4" in the private "value" attribute of 1063 any entry are returned in the search results. 1065 5.9. ANNOTATION Key in SORT 1067 ANNOTATION 1069 The ANNOTATION criterion for the SORT command [I-D.ietf-imapext-sort] 1070 instructs the server to return the message numbers or UIDs of a 1071 mailbox, sorted using the values of the specified annotations. The 1072 ANNOTATION criterion is available if the server returns both 1073 ANNOTATE-EXPERIMENT-1 and SORT as supported capabilities in the 1074 CAPABILITY command response. 1076 Messages are sorted using the values of the 1077 attributes in the entries. 1079 Clients MUST provide either the ".priv" or ".shared" suffix to the 1080 attribute name to ensure that the server knows which specific value 1081 to sort on. 1083 Only the "value.priv" and "value.shared" attributes can be used for 1084 sorting. Clients MUST NOT specify an attribute other than either 1085 "value.priv" or "value.shared". Servers MUST return a BAD response 1086 if the client tries to sort on any other attribute. 1088 When either "value.priv" or "value.shared" is being sorted, the 1089 server MUST use the character set value specified in the SORT command 1090 to determine the appropriate sort order. 1092 Example: 1094 C: a SORT (ANNOTATION /altsubject value.shared) UTF-8 ALL 1095 S: * SORT 2 3 4 5 1 11 10 6 7 9 8 1096 S: a OK Sort complete 1098 In the above example, the message numbers of all messages are 1099 returned, sorted according to the shared "value" attribute of the 1100 "/altsubject" entry. 1102 Note that the ANNOTATION sort key must include a fully specified 1103 entry - wild cards are not allowed. 1105 5.10. New ACL Rights 1107 As discussed in Section 4.4 this extension adds a new "n" right to 1108 the list of rights provided by the ACL extensions [RFC2086] and 1109 [RFC4314]. 1111 6. Formal Syntax 1113 The following syntax specification uses the Augmented Backus-Naur 1114 Form (ABNF) notation as specified in [RFC2234]. 1116 Non-terminals referenced but not defined below are as defined by 1117 [RFC3501] with the new definitions in [RFC4466] superseding those in 1118 [RFC3501]. 1120 Except as noted otherwise, all alphabetic characters are case- 1121 insensitive. The use of upper or lower case characters to define 1122 token strings is for editorial clarity only. Implementations MUST 1123 accept these strings in a case-insensitive fashion. 1125 ann-size = "NONE" / 1126 (("READ-ONLY" / nz-size) 1127 [SP "NOPRIVATE"]) 1128 ; response codes indicating the level of 1129 ; support for annotations in a mailbox 1131 append-ext =/ att-annotate 1132 ; modifies [RFC3501] extension behaviour 1134 att-annotate = "ANNOTATION" SP 1135 "(" entry-att *(SP entry-att) ")" 1137 att-search = "value" / "value.priv" / "value.shared" 1138 ; the only attributes that can be searched 1140 att-sort = "value.priv" / "value.shared" 1141 ; the only attributes that can be sorted 1143 att-value = attrib SP value 1145 attrib = astring 1146 ; dot-separated attribute name 1147 ; MUST NOT contain "*" or "%" 1149 attribs = attrib / "(" attrib *(SP attrib) ")" 1150 ; one or more attribute specifiers 1152 capability =/ "ANNOTATE-EXPERIMENT-1" 1153 ; defines the capability for this extension 1155 entries = entry-match / 1156 "(" entry-match *(SP entry-match) ")" 1158 entry = astring 1159 ; slash-separated path to entry 1160 ; MUST NOT contain "*" or "%" 1162 entry-att = entry SP "(" att-value *(SP att-value) ")" 1164 entry-match = list-mailbox 1165 ; slash-separated path to entry 1166 ; MAY contain "*" or "%" for use as wild cards 1168 fetch-att =/ "ANNOTATION" SP "(" entries SP attribs ")" 1169 ; modifies original IMAP fetch-att 1171 msg-att-dynamic =/ "ANNOTATION" SP 1172 ( "(" entry-att *(SP entry-att) ")" / 1173 "(" entry *(SP entry) ")" ) 1174 ; extends FETCH response with annotation data 1176 resp-text-code =/ "ANNOTATE" SP "TOOBIG" / 1177 "ANNOTATE" SP "TOOMANY" / 1178 "ANNOTATIONS" SP ann-size 1179 ; new response codes 1181 search-key =/ "ANNOTATION" SP entry-match SP att-search 1182 SP value 1183 ; modifies original IMAP search-key 1185 select-param =/ "ANNOTATE" 1186 ; defines the select parameter used with 1187 ; ANNOTATE extension 1189 sort-key =/ "ANNOTATION" SP entry SP att-sort 1190 ; modifies original sort-key 1192 store-att-flags =/ att-annotate 1193 ; modifies original IMAP STORE command 1195 value = nstring / literal8 1197 7. IANA Considerations 1199 Entry names MUST be specified in a standards track or IESG approved 1200 experimental RFC, or fall under the vendor namespace. Vendor names 1201 MUST be registered. 1203 Attribute names MUST be specified in a standards track or IESG 1204 approved experimental RFC. 1206 Each entry registration MUST include a content-type that is used to 1207 indicate the nature of the annotation value. Where applicable a 1208 charset parameter MUST be included with the content-type. 1210 7.1. Entry and Attribute Registration Template 1212 To: iana@iana.org 1213 Subject: IMAP Annotate Registration 1215 Please register the following IMAP Annotate item: 1217 [] Entry [] Attribute 1219 Name: ______________________________ 1221 Description: _______________________ 1223 ____________________________________ 1225 ____________________________________ 1227 Content-Type:_______________________ 1229 Contact person: ____________________ 1231 email: ____________________ 1233 7.2. Entry Registrations 1235 The following templates specify the IANA registrations of annotation 1236 entries specified in this document. 1238 7.2.1. /comment 1240 To: iana@iana.org 1241 Subject: IMAP Annotate Registration 1243 Please register the following IMAP Annotate item: 1245 [X] Entry [] Attribute 1247 Name: /comment 1249 Description: Defined in IMAP ANNOTATE extension document. 1251 Content-Type: text/plain; charset=utf-8 1253 Contact person: Cyrus Daboo 1255 email: cyrus@daboo.name 1257 7.2.2. /flags 1259 To: iana@iana.org 1260 Subject: IMAP Annotate Registration 1262 Please register the following IMAP Annotate item: 1264 [X] Entry [] Attribute 1266 Name: /flags 1268 Description: Reserved entry hierarchy. 1270 Content-Type: - 1272 Contact person: Cyrus Daboo 1274 email: cyrus@daboo.name 1276 7.2.3. /altsubject 1278 To: iana@iana.org 1279 Subject: IMAP Annotate Registration 1281 Please register the following IMAP Annotate item: 1283 [X] Entry [] Attribute 1285 Name: /altsubject 1287 Description: Defined in IMAP ANNOTATE extension document. 1289 Content-Type: text/plain; charset=utf-8 1291 Contact person: Cyrus Daboo 1293 email: cyrus@daboo.name 1295 7.2.4. //comment 1297 To: iana@iana.org 1298 Subject: IMAP Annotate Registration 1300 Please register the following IMAP Annotate item: 1302 [X] Entry [] Attribute 1304 Name: //comment 1306 Description: Defined in IMAP ANNOTATE extension document. 1308 Content-Type: text/plain; charset=utf-8 1310 Contact person: Cyrus Daboo 1312 email: cyrus@daboo.name 1314 7.2.5. //flags/seen 1316 To: iana@iana.org 1317 Subject: IMAP Annotate Registration 1319 Please register the following IMAP Annotate item: 1321 [X] Entry [] Attribute 1323 Name: //flags/seen 1325 Description: Defined in IMAP ANNOTATE extension document. 1327 Content-Type: text/plain; charset=utf-8 1329 Contact person: Cyrus Daboo 1331 email: cyrus@daboo.name 1333 7.2.6. //flags/answered 1335 To: iana@iana.org 1336 Subject: IMAP Annotate Registration 1338 Please register the following IMAP Annotate item: 1340 [X] Entry [] Attribute 1342 Name: //flags/answered 1344 Description: Defined in IMAP ANNOTATE extension document. 1346 Content-Type: text/plain; charset=utf-8 1348 Contact person: Cyrus Daboo 1350 email: cyrus@daboo.name 1352 7.2.7. //flags/flagged 1354 To: iana@iana.org 1355 Subject: IMAP Annotate Registration 1357 Please register the following IMAP Annotate item: 1359 [X] Entry [] Attribute 1361 Name: //flags/flagged 1363 Description: Defined in IMAP ANNOTATE extension document. 1365 Content-Type: text/plain; charset=utf-8 1367 Contact person: Cyrus Daboo 1369 email: cyrus@daboo.name 1371 7.2.8. //flags/forwarded 1373 To: iana@iana.org 1374 Subject: IMAP Annotate Registration 1376 Please register the following IMAP Annotate item: 1378 [X] Entry [] Attribute 1380 Name: //flags/forwarded 1382 Description: Defined in IMAP ANNOTATE extension document. 1384 Content-Type: text/plain; charset=utf-8 1386 Contact person: Cyrus Daboo 1388 email: cyrus@daboo.name 1390 7.3. Attribute Registrations 1392 The following templates specify the IANA registrations of annotation 1393 attributes specified in this document. 1395 7.3.1. value 1397 To: iana@iana.org 1398 Subject: IMAP Annotate Registration 1400 Please register the following IMAP Annotate item: 1402 [] Entry [X] Attribute 1404 Name: value 1406 Description: Defined in IMAP ANNOTATE extension document. 1408 Contact person: Cyrus Daboo 1410 email: cyrus@daboo.name 1412 7.3.2. size 1414 To: iana@iana.org 1415 Subject: IMAP Annotate Registration 1417 Please register the following IMAP Annotate item: 1419 [] Entry [X] Attribute 1421 Name: size 1423 Description: Defined in IMAP ANNOTATE extension document. 1425 Contact person: Cyrus Daboo 1427 email: cyrus@daboo.name 1429 8. Internationalization Considerations 1431 Annotations may contain values that include text strings, and both 1432 searching and sorting are possible with annotations. Servers MUST 1433 follow standard IMAP text normalization, character set conversion and 1434 collation rules when such operations are carried out, as they would 1435 for other textual fields being searched or sorted on. 1437 9. Security Considerations 1439 Annotations whose values are intended to remain private MUST be 1440 stored in ".priv" values, and not ".shared" values which may be 1441 accessible to other users. 1443 Excluding the above issues the ANNOTATE extension does not raise any 1444 security considerations that are not present in the base IMAP 1445 protocol, and these issues are discussed in [RFC3501]. 1447 10. References 1449 10.1. Normative References 1451 [I-D.ietf-imapext-sort] 1452 Crispin, M. and K. Murchison, "INTERNET MESSAGE ACCESS 1453 PROTOCOL - SORT AND THREAD EXTENSION", 1454 draft-ietf-imapext-sort-17 (work in progress), May 2004. 1456 [RFC2086] Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997. 1458 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1459 Requirement Levels", BCP 14, RFC 2119, March 1997. 1461 [RFC2234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1462 Specifications: ABNF", RFC 2234, November 1997. 1464 [RFC2244] Newman, C. and J. Myers, "ACAP -- Application 1465 Configuration Access Protocol", RFC 2244, November 1997. 1467 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 1468 4rev1", RFC 3501, March 2003. 1470 [RFC3502] Crispin, M., "Internet Message Access Protocol (IMAP) - 1471 MULTIAPPEND Extension", RFC 3502, March 2003. 1473 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1474 10646", STD 63, RFC 3629, November 2003. 1476 [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", 1477 RFC 4314, December 2005. 1479 [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 1480 ABNF", RFC 4466, April 2006. 1482 10.2. Informative References 1484 [RFC4551] Melnikov, A. and S. Hole, "IMAP Extension for Conditional 1485 STORE Operation or Quick Flag Changes Resynchronization", 1486 RFC 4551, June 2006. 1488 Appendix A. Acknowledgments 1490 Many thanks to Chris Newman for his detailed comments on the first 1491 draft of this document, and to the participants at the ACAP working 1492 dinner in Pittsburgh. The participants of the IMAPext working group 1493 made significant contributions to this work. 1495 Authors' Addresses 1497 Cyrus Daboo 1498 Apple Computer, Inc. 1499 1 Infinite Loop 1500 Cupertino, CA 95014 1501 USA 1503 Email: cyrus@daboo.name 1504 URI: http://www.apple.com/ 1506 Randall Gellens 1507 QUALCOMM Incorporated 1508 5775 Morehouse Dr. 1509 San Diego, CA 92121-2779 1510 US 1512 Email: randy@qualcomm.com 1514 Full Copyright Statement 1516 Copyright (C) The Internet Society (2006). 1518 This document is subject to the rights, licenses and restrictions 1519 contained in BCP 78, and except as set forth therein, the authors 1520 retain all their rights. 1522 This document and the information contained herein are provided on an 1523 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1524 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1525 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1526 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1527 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1528 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1530 Intellectual Property 1532 The IETF takes no position regarding the validity or scope of any 1533 Intellectual Property Rights or other rights that might be claimed to 1534 pertain to the implementation or use of the technology described in 1535 this document or the extent to which any license under such rights 1536 might or might not be available; nor does it represent that it has 1537 made any independent effort to identify any such rights. Information 1538 on the procedures with respect to rights in RFC documents can be 1539 found in BCP 78 and BCP 79. 1541 Copies of IPR disclosures made to the IETF Secretariat and any 1542 assurances of licenses to be made available, or the result of an 1543 attempt made to obtain a general license or permission for the use of 1544 such proprietary rights by implementers or users of this 1545 specification can be obtained from the IETF on-line IPR repository at 1546 http://www.ietf.org/ipr. 1548 The IETF invites any interested party to bring to its attention any 1549 copyrights, patents or patent applications, or other proprietary 1550 rights that may cover technology that may be required to implement 1551 this standard. Please address the information to the IETF at 1552 ietf-ipr@ietf.org. 1554 Acknowledgment 1556 Funding for the RFC Editor function is provided by the IETF 1557 Administrative Support Activity (IASA).