idnits 2.17.1 draft-ietf-imapext-annotate-08.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** There are 6 instances of too long lines in the document, the longest one being 8 characters in excess of 72. ** There are 2 instances of lines with control characters in the document. ** The abstract seems to contain references ([IMAP4]), 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 (October 2003) is 7489 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'ANNOTATE TOOBIG' is mentioned on line 101, but not defined == Missing Reference: 'ANNOTATE TOOMANY' is mentioned on line 101, but not defined == Missing Reference: 'MIME' is mentioned on line 418, but not defined == Unused Reference: 'SMTP-DSN' is defined on line 1003, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2234 (ref. 'ABNF') (Obsoleted by RFC 4234) -- Possible downref: Non-RFC (?) normative reference: ref. 'CONDSTORE' ** Obsolete normative reference: RFC 3501 (ref. 'IMAP4') (Obsoleted by RFC 9051) ** Obsolete normative reference: RFC 1891 (ref. 'SMTP-DSN') (Obsoleted by RFC 3461) -- Possible downref: Non-RFC (?) normative reference: ref. 'SORT' -- Obsolete informational reference (is this intentional?): RFC 2086 (ref. 'ACL') (Obsoleted by RFC 4314) Summary: 10 errors (**), 0 flaws (~~), 6 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 IMAP Extensions Working Group R. Gellens 2 Internet Draft: IMAP ANNOTATE Extension C. Daboo 3 Document: draft-ietf-imapext-annotate-08.txt October 2003 5 IMAP ANNOTATE Extension 7 Status of this Memo 9 This document is an Internet-Draft and is in full conformance with 10 all provisions of Section 10 of RFC2026. 12 Internet-Drafts are working documents of the Internet Engineering 13 Task Force (IETF), its areas, and its working groups. Note that 14 other groups may also distribute working documents as 15 Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six 18 months and may be updated, replaced, or obsoleted by other documents 19 at any time. It is inappropriate to use Internet-Drafts as 20 reference material or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt. 25 The list of Internet- Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html. 28 Copyright Notice 30 Copyright (C) The Internet Society 2003. All Rights Reserved. 32 Table of Contents 33 1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . 2 34 2 Discussion . . . . . . . . . . . . . . . . . . . . . . . . . 2 35 3 Conventions Used in This Document . . . . . . . . . . . . . . 2 36 4 Change History . . . . . . . . . . . . . . . . . . . . . . . 3 37 5 Introduction and Overview . . . . . . . . . . . . . . . . . . 4 38 6 Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 6 39 6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 6 40 6.2 Namespace of Entries and Attributes . . . . . . . . . . 6 41 6.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . . 7 42 6.2.2 Attribute Names . . . . . . . . . . . . . . . . . . 9 43 7 Private versus Shared and Access Control . . . . . . . . . . 9 44 8 IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . 10 45 8.1 General considerations . . . . . . . . . . . . . . . . . 10 46 8.2 Optional parameters with the SELECT/EXAMINE commands . . 11 47 8.3 ANNOTATION Message Data Item in FETCH Command . . . . . . 12 48 8.4 ANNOTATION Message Data Item in FETCH Response . . . . . 13 49 8.5 ANNOTATION Message Data Item in STORE . . . . . . . . . . 14 50 8.6 ANNOTATION interaction with COPY . . . . . . . . . . . . 16 51 8.7 ANNOTATION Message Data Item in APPEND . . . . . . . . . 16 52 8.8 ANNOTATION Criterion in SEARCH . . . . . . . . . . . . . 16 53 8.9 ANNOTATION Key in SORT . . . . . . . . . . . . . . . . . 17 54 9 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . 18 55 10 IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 56 10.1 Entry and Attribute Registration Template . . . . . . . 19 57 11 Security Considerations . . . . . . . . . . . . . . . . . . . 20 58 12 Normative References . . . . . . . . . . . . . . . . . . . . 20 59 13 Informative References . . . . . . . . . . . . . . . . . . . 21 60 14 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 21 61 15 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 21 62 16 Full Copyright Statement . . . . . . . . . . . . . . . . . . 21 64 1 Abstract 66 The ANNOTATE extension to the Internet Message Access Protocol 67 [IMAP4] permits clients and servers to maintain "metadata" for 68 messages stored in an IMAP4 mailbox. 70 2 Discussion 72 Public comments can be sent to the IETF IMAP Extensions mailing 73 list, . To subscribe, send a message to 74 with the word SUBSCRIBE as the body. 75 Private comments should be sent to the authors. 77 3 Conventions Used in This Document 79 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 80 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 81 document are to be interpreted as described in RFC 2119 [KEYWORDS]. 83 Formal syntax is defined using ABNF [ABNF] as modified by [IMAP4]. 85 In examples, "C:" and "S:" indicate lines sent by the client and 86 server respectively. Line breaks not preceded by a "C:" or "S:" are 87 for editorial clarity only. 89 4 Change History 91 Changes from -07 to -08: 92 1. ANNOTATESIZE response changed to use "NIL" for a mailbox that 93 does not support any type of annotations, and "0" for a mailbox 94 that only supports read-only annotations. 96 Changes from -06 to -07: 97 1. Added text to state entry and attribute names are always 98 case-insensitive. 99 2. Removed top-level entry namespace. 100 3. Added server accept minima for annotation size and count. 101 4. Added [ANNOTATE TOOBIG] & [ANNOTATE TOOMANY] response codes. 102 5. Added [ANNOTATESIZE <>] response code. 103 6. Added comment on suggested CONDSTORE support. 104 7. Modified append behaviour to account for MULTIAPPEND. 105 8. Tweaked ABNF. 107 Changes from -05 to -06: 108 1. Split references into Normative and Informative. 109 2. Reworked flags to allow IMAP4 flag prefix to appear in annotation name. 110 3. Removed smtp-envelope annotation - a future extension can add this. 111 4. Changed subject to altsubject. 112 5. Added $MDNSent flag and reference to document. 113 6. Cleaned up formal syntax to use IMAP string type for entry 114 and attributes, with requirements on how the string is formatted. 115 7. Use of ACAP vendor subtree registry for vendor tokens. 116 8. Fixed STORE syntax. 118 Changes from -04 to -05: 119 1. Fixed examples to match formal syntax for FETCH responses where 120 parenthesis do not appear around entry-att items. 122 Changes from -03 to -04: 123 1. Fixed attrib/attrib-match grammar to use "." instead of "/". 124 2. Add text for server to reject unknown . 125 3. Do not allow empty part-specifier. 126 4. Store NIL to value to delete. 127 5. Comment on COPY interaction with ANNOTATE. 128 6. Added comment that IMAP flags are mapped one-to-one with their 129 corresponding FLAGS items. 130 7. Added comment that the recent flag annotation is read-only. 132 Changes from -02 to -03: 133 1. Removed reference to status modtime item. 135 2. Added missing 'notify' and 'ret' dsn annotations for 136 /message/smtp-envelope. 137 3. Added requirement to store data permanently - no 138 'session only' annotations. 139 4. Removed Access Control section. Replaced with comments 140 on read-only/read-write mailboxes and storing private or 141 shared annotations. 142 5. Removed STORE to default .priv or .shared. 143 6. Added section on optional select parameters. 145 Changes from -01 to -02: 146 1. Now require .priv or .shared on store operations. 148 Changes from -00 to -01: 149 1. MODTIME moved to its own draft, which this draft now 150 depends on. Thus, Conditional Annotation STORE and 151 related items deleted from this draft. 152 2. Private versus Shared Annotations: both are possible 153 (separately addressable using ".priv" and ".shared" 154 suffixes). There is a per-mailbox setting for the 155 default. It is an open issue how this is viewed or 156 changed by the client. 157 3. In ACLs, the "w" right is needed to updated shared state; 158 the "s" right is needed to update private state. 159 4. Various clarifications and text modifications. 160 5. Added 'forwarded' flag for message parts. 162 Changes from pre-imapext to -00: 163 1. Clarified text describing attributions, entries, and 164 attributes. 165 2. Changed 'modifiedsince' to 'modtime'; referenced ACAP spec. 166 3. Deleted 'queued' flag. 167 4. Expanded and explained smtp-envelope entry. 168 5. Restricted including ANNOTATION data in unsolicited responses 169 until the client uses it first. (Open issue as to if needed). 170 6. Examples now only use valid entries and attributes. 171 7. Updated Security Considerations. 172 8. Content-Type now defaults to text/plain. 173 9. Open Issue: Shared vs. private annotations. 174 10. Open issue: Annotation Modtime untagged response or VALIDTIME 175 FETCH data. 176 11. Open issue: Conditional annotation STORE. 177 12. ANNOTATION criterion available if both "ANNOTATE" and "SORT" 178 in CAPABILITY command response. 179 13. Prohibition on annotations in lieu of base spec functionality. 180 14. Specified required ACL rights. 181 15. ANNOTATION message data item in APPEND. 182 16. ANNOTATION-MODTIME message data item in STATUS. 183 17. Replaced ATOM_CHAR with utf8-char. 184 18. Updated other ABNF entries. 186 5 Introduction and Overview 188 The ANNOTATE extension is present in any IMAP4 implementation which 189 returns "ANNOTATE" as one of the supported capabilities in the 190 CAPABILITY response. 192 The ANNOTATE extension adds a new message data item to the FETCH and 193 STORE commands, as well as adding SEARCH and SORT keys and an APPEND 194 modifier. 196 This extension makes the following changes to the IMAP4 protocol: 198 a) adds a new ANNOTATION message data item for use in FETCH 199 b) adds a new ANNOTATION message data item for use in STORE 200 c) adds a new ANNOTATION search criterion for use in SEARCH 201 d) adds a new ANNOTATION sort key for use in SORT extension 202 e) adds a new ANNOTATION data item for use in APPEND 203 f) adds a new requirement on the COPY command 204 g) adds a extension mechanism for adding parameters to the 205 SELECT/EXAMINE commands and defines the ANNOTATE parameter 206 h) adds two new response codes to indicate store failures of 207 annotations. 208 i) adds a new untagged response codes for the SELECT or EXAMINE 209 commands to indicate the maximum size. 211 The data model used for the storage of annotations is based on that 212 of the Application Configuration Access Protocol [ACAP]. Note that 213 there is no inheritance in annotations. 215 Clients MUST NOT use annotations in lieu of equivalent IMAP base 216 specification facilities. For example, use of a "seen" flag in the 217 vendor namespace together with ".PEEK" in fetches. Such behaviour 218 would significantly reduce IMAP interoperability. 220 If a server supports annotations, then it MUST store all annotation 221 data permanently, i.e. there is no concept of 'session only' 222 annotations that would correspond to the behaviour of 'session' 223 flags as defined in the IMAP base specification. The exception to 224 this is IMAP flags (which are accessible directly through 225 annotations) which may be 'session only' as determined by the FLAGS 226 and PERMANENTFLAGS responses to a SELECT or EXAMINE command. 228 This extension also introduces a generalised mechanism for adding 229 parameters to the SELECT or EXAMINE commands. It is anticipated 230 that other extensions may want to utilise this, so it is not 231 strictly dependent on the ANNOTATE extension being present. 233 In order to provide optimum support for a disconnected client (one 234 that needs to synchronise annotations for use when offline), servers 235 SHOULD also support the Conditional STORE [CONDSTORE] extension. 237 The rest of this document describes the data model and protocol 238 changes more rigorously. 240 6 Data Model 242 6.1 Overview 244 The data model used in ANNOTATE is that of a uniquely named entry 245 which contains a set of standard attributes. A single coherent unit 246 of "metadata" for a message is stored as a single entry, made up of 247 several attributes. 249 For example, a comment added to a message has an entry name of 250 "/comment". This entry is composed of several attributes such as 251 "value", "size", etc. which contain the properties and data of the 252 entry. 254 The protocol changes to IMAP described below allow a client to 255 access or change the values of any attributes in any entries in a 256 message annotation, assuming it has sufficient access rights to do 257 so (see Section 7 for specifics). 259 6.2 Namespace of Entries and Attributes 261 Each message annotation is made up of a set of entries. Each entry 262 has a hierarchical name in UTF-8, with each component of the name 263 separated by a slash ("/"). 265 Each entry is made up of a set of attributes. Each attribute has a 266 hierarchical name in UTF-8, with each component of the name 267 separated by a period ("."). 269 The value of an attribute is NIL (has no value), or is a string of 270 zero or more octets. 272 Entry and attribute names MUST NOT contain asterisk ("*") or percent 273 ("%") characters and MUST be valid UTF-8 strings which do not 274 contain the NULL octet. Invalid entry or attribute names result in 275 a BAD response in any IMAP commands where they are used. 277 Entry and attribute names are case-insensitive. 279 Use of non-visible UTF-8 characters in entry and attribute names is 280 strongly discouraged. 282 This specification defines an initial set of entry and attribute 283 names available for use in message annotations. In addition, an 284 extension mechanism is described to allow additional names to be 285 added for extensibility. 287 6.2.1 Entry Names 289 Entry names MUST be specified in a standards track or IESG approved 290 experimental RFC, or fall under the vendor namespace. See Section 291 10.1 for the registration template. 293 / 294 Defines the top-level of entries associated with an entire 295 message. This entry itself does not contain any attributes. 296 All entries that start with a numeric character ("0" - "9") 297 refer to an annotation on a specific body part. All other 298 entries are for annotations on the entire message. 300 /comment 301 Defines a comment or note associated with an entire message. 303 /flags 304 Defines the top-level of entries for flags associated with an 305 entire message. The "value" attribute of each of the entries 306 described below must be either "1", "0" or NIL. "1" corresponds 307 to the flag being set. 309 Standard [IMAP4] flags always have a '\' prefix character. 310 Other standard flags have a '$' prefix. The annotation names 311 used for all flags uses the complete name for that flag, 312 including the prefix character. 314 The set of standard IMAP flags annotations are: 316 /flags/\answered 317 /flags/\flagged 318 /flags/\deleted 319 /flags/\seen 320 /flags/\draft 321 /flags/\recent 323 Changes to these annotations are reflected in the standard IMAP 324 flags. The \recent attribute is read only, clients MUST NOT 325 attempt to change it. 327 Note that entry names are sent as [IMAP4] string elements which 328 requires that '\' characters be escaped if sent as a quoted 329 string as opposed to a literal. 331 Additional standard flags are: 333 /flags/$mdnsent 334 /flags/$redirected 335 /flags/$forwarded 337 The '$mdnsent' flag is used to indicate message disposition 338 notification processing state [MDNSENT]. 340 The '$redirected' flag indicates that a message has been handed 341 off to someone else, by resending the message with minimal 342 alterations, and in such a way that a reply by the new recipient 343 is addressed to the original author, not the user who performed 344 the redirection. 346 The '$forwarded' flag indicates the message was resent to 347 another user, embedded within or attached to a new message. 349 /altsubject 350 Contains text supplied by the message recipient, to be used by 351 the client instead of the original message Subject. 353 /vendor/ 354 Defines the top-level of entries associated with an entire 355 message as created by a particular product of some vendor. 356 These sub-entries can be used by vendors to provide 357 client-specific attributes. The vendor-token MUST be registered 358 with IANA, using the [ACAP] vendor subtree registry. 360 / 361 Defines the top-level of entries associated with a specific body 362 part of a message. This entry itself does not contain any 363 attributes. The section-part uses the same numeric part 364 specifier syntax as the BODY message data item in the FETCH 365 command [IMAP4]. The server MUST return a BAD response if the 366 client uses an incorrect part specifier (either incorrect syntax 367 or a specifier referring to a non-existent part). The server 368 MUST return a BAD response if the client uses an empty part 369 specifier (which is used in [IMAP4] to represent the entire 370 message). 372 //comment 373 Defines a comment or note associated with a specific body part 374 of a message. 376 //flags 377 Defines the top-level of entries associated with flag state for 378 a specific body part of a message. All sub-entries are 379 maintained entirely by the client. There is no implicit change 380 to any flag by the server. 382 //flags/seen 383 //flags/answered 384 //flags/flagged 385 //flags/forwarded 386 Defines flags for a specific body part of a message. The 387 "value" attribute of these entries must be either "1", "0" or 388 NIL. 390 //vendor/ 391 Defines the top-level of entries associated with a specific body 392 part of a message as created by a particular product of some 393 vendor. This entry can be used by vendors to provide client 394 specific attributes. The vendor-token MUST be registered with 395 IANA. 397 6.2.2 Attribute Names 399 Attribute names MUST be specified in a standards track or IESG 400 approved experimental RFC, or fall under the vendor namespace. See 401 Section 10.1 for the registration template. 403 All attribute names implicitly have a ".priv" and a ".shared" suffix 404 which maps to private and shared versions of the entry. Searching 405 or fetching without using either suffix includes both. The client 406 MUST specify either a ".priv" or ".shared" suffix when storing an 407 annotation. 409 value 410 A UTF8 string representing the data value of the attribute. To 411 delete an annotation, the client can store NIL into the value. 413 size 414 The size of the value, in octets. Set automatically by the 415 server, read-only to clients. 417 content-type 418 A MIME [MIME] content type and subtype that describes the nature 419 of the content of the "value" attribute. If not present, a 420 value of "text/plain; charset=utf8" is assumed. 422 vendor. 423 Defines an attribute associated with a particular product of 424 some vendor. This attribute can be used by vendors to provide 425 client specific attributes. The vendor-token MUST be registered 426 with IANA, using the [ACAP] vendor subtree registry. 428 7 Private versus Shared and Access Control 430 Some IMAP mailboxes are private, accessible only to the owning user. 431 Other mailboxes are not, either because the owner has set an ACL 432 [ACL] which permits access by other users, or because it is a shared 433 mailbox. 435 This raises the issue of shared versus private annotations. 437 If all annotations are private, it is impossible to set annotations 438 in a shared or otherwise non-private mailbox that are visible to 439 other users. This eliminates what could be a useful aspect of 440 annotations in a shared environment. An example of such use is a 441 shared IMAP folder containing bug reports. Engineers may want to 442 use annotations to add information to existing messages, indicate 443 assignments, status, etc. This use requires shared annotations. 445 If all annotations are shared, it is impossible to use annotations 446 for private notes on messages in shared mailboxes. Also, modifying 447 an ACL to permit access to a mailbox by other users may 448 unintentionally expose private information. 450 There are also situations in which both shared and private 451 annotations are useful. For example, an administrator may want to 452 set shared annotations on messages in a shared folder, which 453 individual users may wish to supplement with additional notes. 455 If shared and private annotations are to coexist, we need a clear 456 way to differentiate them. Also, it should be as easy as possible 457 for a client to access both and not overlook either. There is also 458 a danger in allowing a client to store an annotation without knowing 459 if it is shared or private. 461 This document proposes two standard suffixes for all attributes: 462 ".shared" and ".priv". A search, fetch, or sort which specifies 463 neither uses both. Store operations MUST explicitly use .priv or 464 .shared suffixes. 466 A user can only store and fetch private annotations on messages in 467 any mailbox which they can SELECT or EXAMINE, including ones which 468 only open READ-ONLY. A user can only store and fetch shared 469 annotations on messages in any mailbox that they can SELECT and 470 which opens READ-WRITE. If a client attempts to store or fetch a 471 shared annotation on a READ-ONLY mailbox, the server MUST respond 472 with a NO response. 474 8 IMAP Protocol Changes 476 8.1 General considerations 478 The server is allowed to impose limitations on the size of any one 479 annotation or the total number of annotations for a single message. 480 However, the server MUST accept a minimum annotation data size of at 481 least 1024 bytes, and a minimum annotation count per message of at 482 least 10. 484 The server SHOULD indicate the maximum size for an annotation value 485 by sending an untagged "ANNOTATESIZE" response during a SELECT or 486 EXAMINE command. Clients MUST NOT store annotation values of a size 487 greater than the amount indicated by the server in the 488 "ANNOTATESIZE" response. 490 In some cases, servers may be able to offer annotations on some 491 mailboxes and not others, or may be able to provide only read-only 492 annotations on some mailboxes. For mailboxes that cannot have 493 annotations associated with them, the server MUST return an 494 "ANNOTATESIZE" response with a value of "NIL" during the SELECT or 495 EXAMINE command for that mailbox. Clients MUST NOT attempt to fetch 496 or store annotations on any messages in a mailbox for which the 497 "ANNOTATESIZE" response was "NIL". For mailboxes that can only have 498 read-only annotations associated with them, the server MUST return 499 an "ANNOTATESIZE" response with a value of "0" (zero) during the 500 SELECT or EXAMINE command for that mailbox. Clients MUST NOT 501 attempt to store annotations on any messages in a mailbox for which 502 the "ANNOTATESIZE" response was zero. 504 8.2 Optional parameters with the SELECT/EXAMINE commands 506 This extension adds the ability to include one or more parameters 507 with the IMAP SELECT or EXAMINE commands, to turn on or off certain 508 standard behaviour, or to add new optional behaviours required for a 509 particular extension. It is anticipated that other extensions may 510 want to use this facility, so a generalised approach is given here. 511 This facility is not dependent on the presence of the ANNOTATE 512 extension - other extensions can use it with a server that does not 513 implement ANNOTATE. 515 Optional parameters to the SELECT or EXAMINE commands are added as a 516 parenthesised list of atoms or strings, and appear after the mailbox 517 name in the standard SELECT or EXAMINE command. The order of 518 individual parameters is arbitrary. Individual parameters may 519 consist of one or more atoms or strings in a specific order. If a 520 parameter consists of more than one atom or string, it MUST appear 521 in its own parenthesised list. Any parameter not defined by 522 extensions that the server supports MUST be rejected with a NO 523 response. 525 Example: 526 C: a SELECT INBOX (ANNOTATE) 527 S: ... 528 S: a OK SELECT complete 530 In the above example, a single parameter is used with the 531 SELECT command. 533 C: a EXAMINE INBOX (ANNOTATE (RESPONSES "UID Responses") MODTIME) 534 S: ... 535 S: a OK EXAMINE complete 537 In the above example, three parameters are used with the 538 EXAMINE command. The second parameter consists of two 539 items: an atom followed by a quoted string. 541 C: a SELECT INBOX (BLURDYBLOOP) 542 S: a NO Unknown parameter in SELECT command 543 In the above example, a parameter not supported by the 544 server is incorrectly used. 546 The ANNOTATE extension defines a single optional select parameter 547 "ANNOTATE", which is used to turn on unsolicited responses for 548 annotations as described in Section 8.4. 550 8.3 ANNOTATION Message Data Item in FETCH Command 552 This extension adds an ANNOTATION message data item to the FETCH 553 command. This allows clients to retrieve annotations for a range of 554 messages in the currently selected mailbox. 556 ANNOTATION 557 The ANNOTATION message data item, when used by the client in the 558 FETCH command, takes an entry specifier and an attribute 559 specifier. 561 Example: 562 C: a FETCH 1 (ANNOTATION ("/comment" "value")) 563 S: * 1 FETCH (ANNOTATION ("/comment" 564 ("value.priv" "My comment" 565 "value.shared" "Group note"))) 566 S: a OK Fetch complete 568 In the above example, the content of the "value" attribute 569 for the "/comment" entry is requested by the client and 570 returned by the server. Since neither ".shared" nor ".priv" 571 was specified, both are returned. 573 "*" and "%" wildcard characters can be used in either specifier to 574 match one or more characters at that position, with the exception 575 that "%" does not match the hierarchy delimiter for the specifier it 576 appears in (that is, "/" for an entry specifier or "." for an 577 attribute specifier). Thus an entry specifier of "/%" matches 578 entries such as "/comment" and "/subject", but not 579 "/flags/$redirected". 581 Examples: 582 C: a FETCH 1 (ANNOTATION ("/*" ("value.priv" "size.priv"))) 583 S: * 1 FETCH (ANNOTATION 584 ("/comment" ("value.priv" "My comment" 585 "size.priv" "10") 586 "/subject" ("value.priv" "Rhinoceroses!" 587 "size.priv" "13") 588 "/vendor/foobar/label.priv" 589 ("value.priv" "label43" 590 "size.priv" "7") 591 "/vendor/foobar/personality" 592 ("value.priv" "Tallulah Bankhead" 593 "size.priv" "17"))) 594 S: a OK Fetch complete 595 In the above example, the contents of the private "value" and "size" 596 attributes for any entries in the "" hierarchy are requested by the 597 client and returned by the server. 599 C: a FETCH 1 (ANNOTATION ("/%" "value.shared")) 600 S: * 1 FETCH (ANNOTATION 601 ("/comment" ("value.shared" "Patch Mangler") 602 "/subject" ("value.shared" "Patches? We don't 603 need no steenkin patches!"))) 604 S: a OK Fetch complete 606 In the above example, the contents of the shared "value" 607 attributes for entries at the top level only of the "" 608 hierarchy are requested by the client and returned by the 609 server. 611 Entry and attribute specifiers can be lists of atomic specifiers, so 612 that multiple items of each type may be returned in a single FETCH 613 command. 615 Examples: 616 C: a FETCH 1 (ANNOTATION 617 (("/comment" "/subject") "value.priv")) 618 S: * 1 FETCH (ANNOTATION 619 ("/comment" ("value.priv" "What a chowder-head") 620 "/subject" ("value.priv" "How to crush beer cans"))) 621 S: a OK Fetch complete 623 In the above example, the contents of the private "value" attributes 624 for the two entries "/comment" and "/subject" are requested by the 625 client and returned by the server. 627 8.4 ANNOTATION Message Data Item in FETCH Response 629 The ANNOTATION message data item in the FETCH response displays 630 information about annotations in a message. 632 ANNOTATION parenthesised list 634 The response consists of a list of entries, each of which has a 635 list of attribute-value pairs. 637 Examples: 638 C: a FETCH 1 (ANNOTATION ("/comment" "value")) 639 S: * 1 FETCH (ANNOTATION ("/comment" 640 ("value.priv" "My comment" 641 "value.shared" NIL))) 642 S: a OK Fetch complete 644 In the above example, a single entry with a single attribute-value 645 pair is returned by the server. Since the client did not specify a 646 ".shared" or ".priv" suffix, both are returned. Only the private 647 attribute has a value (the shared value is NIL). 649 C: a FETCH 1 (ANNOTATION 650 (("/comment" "/subject") "value")) 651 S: * 1 FETCH (ANNOTATION 652 ("/comment" ("value.priv" "My comment" 653 "value.shared" NIL) 654 "/subject" ("value.priv" "My subject" 655 "value.shared" NIL))) 656 S: a OK Fetch complete 658 In the above example, two entries each with a single attribute-value 659 pair are returned by the server. Since the client did not specify a 660 ".shared" or ".priv" suffix, both are returned. Only the private 661 attributes have values; the shared attributes are NIL. 663 C: a FETCH 1 (ANNOTATION 664 ("/comment" ("value" "size"))) 665 S: * 1 FETCH (ANNOTATION 666 ("/comment" 667 ("value.priv" "My comment" 668 "value.shared" NIL 669 "size.priv" "10" 670 "size.shared" "0"))) 671 S: a OK Fetch complete 673 In the above example, a single entry with two attribute-value pairs 674 is returned by the server. Since the client did not specify a 675 ".shared" or ".priv" suffix, both are returned. Only the private 676 attributes have values; the shared attributes are NIL. 678 Servers MUST NOT include ANNOTATION data in unsolicited responses 679 unless the client used the ANNOTATE select parameter when it issued 680 the last SELECT or EXAMINE command. This restriction avoids sending 681 ANNOTATION data to a client unless the client explicitly asks for 682 it. 684 Servers SHOULD send ANNOTATION message data items in unsolicited 685 FETCH responses if an annotation entry is changed by a third-party, 686 and the ANNOTATE select parameter was used. This allows servers to 687 keep clients updated with changes to annotations by other clients. 689 8.5 ANNOTATION Message Data Item in STORE 691 ANNOTATION 692 Sets the specified list of entries by adding or replacing the 693 specified attributes with the values provided. Clients can use 694 NIL for values of attributes it wants to remove from entries. 696 The ANNOTATION message data item used with the STORE command has an 697 implicit ".SILENT" behaviour. This means the server does not 698 generate an untagged FETCH in response to the STORE command and 699 assumes that the client updates its own cache if the command 700 succeeds. 702 If the server is unable to store an annotation because the size of 703 its value is too large, the server MUST return a tagged NO response 704 with a "[ANNOTATE TOOBIG]" response code. 706 If the server is unable to store a new annotation because the 707 maximum number of allowed annotations has already been reached, the 708 server MUST return a tagged NO response with a "[ANNOTATE TOOMANY]" 709 response code. 711 Examples: 712 C: a STORE 1 ANNOTATION ("/comment" 713 ("value.priv" "My new comment")) 714 S: a OK Store complete 716 In the above example, the entry "/comment" is created (if not 717 already present) and the private attribute "value" with data set to 718 "My new comment" is created if not already present, or replaced if 719 it exists. 721 C: a STORE 1 ANNOTATION ("/comment" 722 ("value.shared" NIL)) 723 S: a OK Store complete 725 In the above example, the shared "value" attribute of the entry 726 "/comment" is removed by storing NIL into the attribute. 728 Multiple entries can be set in a single STORE command by listing 729 entry-attribute-value pairs in the list. 731 Example: 732 C: a STORE 1 ANNOTATION ("/comment" 733 ("value.priv" "Get tix Tuesday") 734 "/subject" 735 ("value.priv" "Wots On")) 736 S: a OK Store complete 738 In the above example, the entries "/comment" and "/subject" are 739 created (if not already present) and the private attribute "value" 740 is created for each entry if not already present, or replaced if 741 they exist. 743 Multiple attributes can be set in a single STORE command by listing 744 multiple attribute-value pairs in the entry list. 746 Example: 747 C: a STORE 1 ANNOTATION ("/comment" 748 ("value.priv" "My new comment" 749 "vendor.foobar.priv" "foo's bar")) 750 S: a OK Store complete 752 In the above example, the entry "/comment" is created (if not 753 already present) and the private attributes "value" and 754 "vendor.foobar" are created if not already present, or replaced if 755 they exist. 757 8.6 ANNOTATION interaction with COPY 759 The COPY command can be used to move messages from one mailbox to 760 another on the same server. Servers that support the ANNOTATION 761 extension MUST copy all the annotation data associated with any 762 messages being copied via the COPY command. The only exceptions to 763 this are if the destination mailbox permissions are such that either 764 the '.priv' or '.shared' annotations are not allowed, or if the 765 destination mailbox is of a type that does not support annotations 766 or does not support storing of annotations (a mailbox that returns a 767 zero or "NIL" value for its ANNOTATESIZE response code). 769 8.7 ANNOTATION Message Data Item in APPEND 771 ANNOTATION 772 Sets the specified list of entries and attributes in the 773 resulting message. 775 The APPEND command can include annotations for the message being 776 appended via the addition of a new append data item. The new data 777 item can also be used with the multi-append [MULTIAPPEND] extension 778 that allows multiple messages to be appended via a single APPEND 779 command. 781 Examples: 782 C: a APPEND drafts ANNOTATION ("/comment" 783 ("value.priv" "Don't send until we hear from Sally")) {310} 784 S: + Ready for literal data 785 C: MIME-Version: 1.0 786 ... 787 C: 788 S: a OK APPEND completed 790 In the above example, a comment with a private value is added to a 791 new message appended to the mailbox. The ellipsis represents the 792 bulk of the message. 794 8.8 ANNOTATION Criterion in SEARCH 796 ANNOTATION 797 The ANNOTATION criterion for the SEARCH command allows a client to 798 search for a specified string in the value of an annotation entry of 799 a message. 801 Messages that have annotations with entries matching 802 and attributes matching and the specified string 803 in their values are returned in the SEARCH results. The "*" 804 character can be used in the entry or attribute name fields to match 805 any content in those items. The "%" character can be used in the 806 entry or attribute name fields to match a single level of hierarchy 807 only. 809 Examples: 810 C: a SEARCH ANNOTATION "/comment" "value" "IMAP4" 811 S: * SEARCH 2 3 5 7 11 13 17 19 23 812 S: a OK Search complete 814 In the above example, the message numbers of any messages containing 815 the string "IMAP4" in the shared or private "value" attribute of the 816 "/comment" entry are returned in the search results. 818 C: a SEARCH ANNOTATION "*" "*" "IMAP4" 819 S: * SEARCH 1 2 3 5 8 13 21 34 820 S: a OK Search complete 822 In the above example, the message numbers of any messages containing 823 the string "IMAP4" in any attribute (public or private) of any entry 824 are returned in the search results. 826 8.9 ANNOTATION Key in SORT 828 ANNOTATION 830 The ANNOTATION criterion for the SORT command [SORT] instructs the 831 server to return the message numbers or UIDs of a mailbox, sorted 832 using the values of the specified annotations. The ANNOTATION 833 criterion is available if the server returns both "ANNOTATE" and 834 "SORT" as supported capabilities in the CAPABILITY command response. 836 Messages are sorted using the values of the 837 attributes in the entries. (The charset argument 838 determines sort order, as specified in the SORT extension 839 description.) 841 Examples: 842 C: a SORT (ANNOTATION "/subject" "value.shared") UTF-8 ALL 843 S: * SORT 2 3 4 5 1 11 10 6 7 9 8 844 S: a OK Sort complete 846 In the above example, the message numbers of all messages are 847 returned, sorted according to the shared "value" attribute of the 848 "/subject" entry. 850 Note that the ANNOTATION sort key must include a fully specified 851 entry and attribute -- wildcards are not allowed. 853 9 Formal Syntax 855 The following syntax specification uses the Augmented Backus-Naur 856 Form (ABNF) notation as specified in [ABNF]. 858 Non-terminals referenced but not defined below are as defined by 859 [IMAP4]. 861 Except as noted otherwise, all alphabetic characters are case- 862 insensitive. The use of upper or lower case characters to define 863 token strings is for editorial clarity only. Implementations MUST 864 accept these strings in a case-insensitive fashion. 866 annotate-param = "ANNOTATE" 867 ; defines the select parameter used with 868 ; ANNOTATE extension 870 append = "APPEND" SP mailbox [SP flag-list] [SP date-time] 871 [SP "ANNOTATION" SP att-annotate] SP literal 872 ; modifies original IMAP4 APPEND command 874 append-message = [SP flag-list] [SP date-time] 875 [SP "ANNOTATION" SP att-annotate] SP literal 876 ; modifies [MULTIAPPEND] extension behaviour 878 att-annotate = "ANNOTATION" SP "(" entry-att *(SP entry-att) ")" 880 att-match = string 881 ; dot-separated attribute name 882 ; MAY contain "*" or "%" for use as wildcards 884 att-value = attrib SP value 886 attrib = string 887 ; dot-separated attribute name 888 ; MUST NOT contain "*" or "%" 890 attribs = att-match / 891 "(" att-match *(SP att-match) ")" 893 entries = entry-match / 894 "(" entry-match *(SP entry-match) ")" 896 entry = string 897 ; slash-separated path to entry 898 ; MUST NOT contain "*" or "%" 899 entry-att = entry SP "(" att-value *(SP att-value) ")" 901 entry-match = string 902 ; slash-separated path to entry 903 ; MAY contain "*" or "%" for use as wildcards 905 examine =/ *(SP "(" select-param *(SP select-param) ")" 906 ; modifies the original IMAP4 examine command to 907 ; accept optional parameters 909 fetch-ann-resp = "ANNOTATION" SP "(" entry-att *(SP entry-att) ")" 911 fetch-att =/ "ANNOTATION" SP "(" entries SP attribs ")" 912 ; modifies original IMAP4 fetch-att 914 resp-text-code =/ "ANNOTATE" SP "TOOBIG" / 915 "ANNOTATE" SP "TOOMANY" / 916 "ANNOTATESIZE" SP (number / "NIL") 917 ; new response codes for STORE failures 919 search-key =/ "ANNOTATION" SP entry-match SP att-match 920 SP value 921 ; modifies original IMAP4 search-key 923 select =/ *(SP "(" select-param *(SP select-param) ")" 924 ; modifies the original IMAP4 select command to 925 ; accept optional parameters 927 select-param = astring / "(" astring SP astring *(SP astring) ")" 928 ; parameters to SELECT may contain one or 929 ; more atoms or strings - multiple items 930 ; are always parenthesised 932 sort-key =/ "ANNOTATION" SP entry SP attrib 933 ; modifies original sort-key [SORT] 935 store-att-flags =/ att-annotate 936 ; modifies original IMAP4 STORE command 938 value = nstring 940 10 IANA Considerations 942 Both entry names and attribute names MUST be specified in a 943 standards track or IESG approved experimental RFC, or fall under the 944 vendor namespace. Vendor names MUST be registered. 946 10.1 Entry and Attribute Registration Template 947 To: iana@iana.org 948 Subject: IMAP Annotate Registration 950 Please register the following IMAP Annotate item: 952 [] Entry [] Attribute 954 Name: ______________________________ 956 Description: _______________________ 958 ____________________________________ 960 ____________________________________ 962 Contact person: ____________________ 964 email: ____________________ 966 11 Security Considerations 968 The ANNOTATE extension does not raise any security considerations 969 that are not present in the base [IMAP4] protocol, and these issues 970 are discussed in [IMAP4]. 972 Care must be taken to ensure that annotations whose values are 973 intended to remain private are not stored in mailboxes which are 974 accessible to other users. This includes mailboxes owned by the 975 user by whose ACLs permit access by others as well as any shared 976 mailboxes. 978 12 Normative References 980 [ABNF] Crocker, Overell, "Augmented BNF for Syntax Specifications: 981 ABNF", RFC 2234, November 1997. 983 [ACAP] Newman, Myers, "ACAP -- Application Configuration Access 984 Protocol", RFC 2244, November 1997. 986 [CONDSTORE] Melnikov, Hole, "IMAP Extension for Conditional STORE 987 operation", 988 1010 13 Informative References 1012 [ACL] Myers, "IMAP4 ACL extension", RFC 2086, January 1997. 1014 14 Acknowledgments 1016 Many thanks to Chris Newman for his detailed comments on the first 1017 draft of this document, and to the participants at the ACAP working 1018 dinner in Pittsburgh. 1020 15 Authors' Addresses 1022 Randall Gellens 1023 QUALCOMM Incorporated 1024 5775 Morehouse Dr. 1025 San Diego, CA 92121-2779 1026 U.S.A. 1028 Email: randy@qualcomm.com 1030 Cyrus Daboo 1031 Cyrusoft International, Inc. 1032 Suite 780, 5001 Baum Blvd. 1033 Pittsburgh, PA 15213 1034 U.S.A. 1036 Email: daboo@cyrusoft.com 1038 16 Full Copyright Statement 1040 Copyright (C) The Internet Society 2003. All Rights Reserved. 1042 This document and translations of it may be copied and furnished to 1043 others, and derivative works that comment on or otherwise explain it 1044 or assist in its implementation may be prepared, copied, published 1045 and distributed, in whole or in part, without restriction of any 1046 kind, provided that the above copyright notice and this paragraph 1047 are included on all such copies and derivative works. However, this 1048 document itself may not be modified in any way, such as by removing 1049 the copyright notice or references to the Internet Society or other 1050 Internet organizations, except as needed for the purpose of 1051 developing Internet standards in which case the procedures for 1052 copyrights defined in the Internet Standards process must be 1053 followed, or as required to translate it into languages other than 1054 English. 1056 The limited permissions granted above are perpetual and will not be 1057 revoked by the Internet Society or its successors or assigns. 1059 This document and the information contained herein is provided on an 1060 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1061 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1062 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1063 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1064 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.