idnits 2.17.1 draft-ietf-imapext-annotate-02.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. == 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. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There is 1 instance of too long lines in the document, the longest one being 6 characters in excess of 72. ** 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 (November 2001) is 8195 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: 'MIME' is mentioned on line 339, but not defined ** Obsolete normative reference: RFC 2234 (ref. 'ABNF') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2086 (ref. 'ACL-EXT') (Obsoleted by RFC 4314) ** Obsolete normative reference: RFC 2060 (ref. 'IMAP4') (Obsoleted by RFC 3501) -- Possible downref: Non-RFC (?) normative reference: ref. 'MODTIME-EXT' ** Obsolete normative reference: RFC 1891 (ref. 'SMTP-DSN') (Obsoleted by RFC 3461) -- Possible downref: Non-RFC (?) normative reference: ref. 'SORT-EXT' Summary: 11 errors (**), 0 flaws (~~), 3 warnings (==), 5 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-02.txt November 2001 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. Internet-Drafts are 11 working documents of the Internet Engineering Task Force (IETF), its 12 areas, and its working groups. Note that other groups may also 13 distribute working documents as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six 16 months and may be updated, replaced, or obsoleted by other documents 17 at any time. It is inappropriate to use Internet-Drafts as 18 reference material or to cite them other than as "work in progress." 20 The list of current Internet-Drafts can be accessed at 21 http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet- 22 Draft Shadow Directories can be accessed at 23 http://www.ietf.org/shadow.html. 25 Copyright Notice 27 Copyright (C) The Internet Society 2001. All Rights Reserved. 29 Table of Contents 30 1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . 2 31 2 Discussion . . . . . . . . . . . . . . . . . . . . . . . . . 2 32 3 Conventions Used in This Document . . . . . . . . . . . . . . 2 33 4 Document Meta-Data . . . . . . . . . . . . . . . . . . . . . 3 34 4.1 Open Issues . . . . . . . . . . . . . . . . . . . . . . . 3 35 4.2 Change History . . . . . . . . . . . . . . . . . . . . . 3 36 5 Introduction and Overview . . . . . . . . . . . . . . . . . . 4 37 6 Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 4 38 6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 4 39 6.2 Namespace of Entries and Attributes . . . . . . . . . . 5 40 6.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . . 5 41 6.2.2 Attribute Names . . . . . . . . . . . . . . . . . . 7 42 7 Private versus Shared . . . . . . . . . . . . . . . . . . . . 8 43 8 IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . 9 44 8.1 ANNOTATION Message Data Item in FETCH Command . . . . . . 9 45 8.2 ANNOTATION Message Data Item in FETCH Response . . . . . 10 46 8.3 ANNOTATION Message Data Item in STORE . . . . . . . . . . 11 47 8.4 ANNOTATION Message Data Item in APPEND . . . . . . . . . 13 48 8.5 ANNOTATION Criterion in SEARCH . . . . . . . . . . . . . 13 49 8.6 ANNOTATION Key in SORT . . . . . . . . . . . . . . . . . 14 50 8.7 ACL Rights . . . . . . . . . . . . . . . . . . . . . . . 15 51 9 Interaction with MODTIME . . . . . . . . . . . . . . . . . . 15 52 10 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 15 53 11 IANA Considerations . . . . . . . . . . . . . . . . . . . . 16 54 11.1 Entry and Attribute Registration Template . . . . . . . . 16 55 12 Security Considerations . . . . . . . . . . . . . . . . . . 17 56 13 References . . . . . . . . . . . . . . . . . . . . . . . . . 17 57 14 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 18 58 15 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 18 59 16 Full Copyright Statement . . . . . . . . . . . . . . . . . . 18 61 1 Abstract 63 The ANNOTATE extension to the Internet Message Access Protocol 64 [IMAP4] permits clients and servers to maintain "metadata" for 65 messages stored in an IMAP4 mailbox. 67 2 Discussion 69 Public comments can be sent to the IETF IMAP Extensions mailing 70 list, . To subscribe, send a message to 71 with the word SUBSCRIBE as the body. 72 Private comments should be sent to the authors. 74 3 Conventions Used in This Document 76 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 77 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 78 document are to be interpreted as described in RFC 2119 [KEYWORDS]. 80 Formal syntax is defined using ABNF [ABNF] as modified by [IMAP4]. 82 In examples, "C:" and "S:" indicate lines sent by the client and 83 server respectively. Line breaks not preceded by a "C:" or "S:" are 84 for editorial clarity only. 86 4 Document Meta-Data 88 4.1 Open Issues 90 At points in this document open issues are discussed, marked by the 91 text "<<>>". These are items which have not been 92 finalized. Discussion and comment is requested. Please use the 93 IETF IMAP Extensions mailing list, as described in section 2. 95 4.2 Change History 97 Changes from -01 to -02: 98 1. Now require .pric or .shared on store operations. 100 Changes from -00 to -01: 101 1. MODTIME moved to its own draft, which this draft now 102 depends on. Thus, Conditional Annotation STORE and 103 related items deleted from this draft. 104 2. Private versus Shared Annotations: both are possible 105 (separately addressable using ".priv" and ".shared" 106 suffixes). There is a per-mailbox setting for the 107 default. It is an open issue how this is viewed or 108 changed by the client. 109 3. In ACLs, the "w" right is needed to updated shared state; 110 the "s" right is needed to update private state. 111 4. Various clarifications and text modifications. 112 5. Added 'forwarded' flag for message parts. 114 Changes from pre-imapext to -00: 115 1. Clarified text describing attributions, entries, and 116 attributes. 117 2. Changed 'modifiedsince' to 'modtime'; referenced ACAP spec. 118 3. Deleted 'queued' flag. 119 4. Expanded and explained smtp-envelope entry. 120 5. Restricted including ANNOTATION data in unsolicited responses 121 until the client uses it first. (Open issue as to if needed). 122 6. Examples now only use valid entries and attributes. 123 7. Updated Security Considerations. 124 8. Content-Type now defaults to text/plain. 125 9. Open Issue: Shared vs. private annotations. 126 10. Open issue: Annotation Modtime untagged response or VALIDTIME 127 FETCH data. 128 11. Open issue: Conditional annotation STORE. 129 12. ANNOTATION criterion available if both "ANNOTATE" and "SORT" 130 in CAPABILITY command response. 132 13. Prohibition on annotations in lieu of base spec functionality. 133 14. Specified required ACL rights. 134 15. ANNOTATION message data item in APPEND. 135 16. ANNOTATION-MODTIME message data item in STATUS. 136 17. Replaced ATOM_CHAR with utf8-char. 137 18. Updated other ABNF entries. 139 5 Introduction and Overview 141 The ANNOTATE extension is present in any IMAP4 implementation which 142 returns "ANNOTATE" as one of the supported capabilities in the 143 CAPABILITY command response. 145 The ANNOTATE extension adds a new message data item to the FETCH and 146 STORE commands, as well as adding SEARCH and SORT keys and APPEND 147 and STATUS modifiers. 149 This extension makes the following changes to the IMAP4 protocol: 151 a) adds a new ANNOTATION message data item for use in FETCH 152 b) adds a new ANNOTATION message data item for use in STORE 153 c) adds a new ANNOTATION search criterion for use in SEARCH 154 d) adds a new ANNOTATION sort key for use in SORT extension 155 e) adds a new ANNOTATION data item for use in APPEND 157 The data model used for the storage of annotations is based on that 158 of the Application Configuration Access Protocol [ACAP]. Note that 159 there is no inheritance in annotations. 161 Clients MUST NOT use annotations in lieu of equivalent IMAP base 162 specification facilities. For example, use of a "seen" flag in the 163 vendor namespace together with ".PEEK" in fetches. Such behavior 164 would significantly reduce IMAP interoperability. 166 <<>> 168 A possible exception to this rule is the potential use of annotation 169 flags in lieu of or as an alternate means of accessing IMAP flags. 171 The rest of this document describes the data model and protocol 172 changes more rigorously. 174 6 Data Model 176 6.1 Overview 178 The data model used in ANNOTATE is that of a uniquely named entry 179 which contains a set of standard attributes. A single coherent unit 180 of "metadata" for a message is stored as a single entry, made up of 181 several attributes. 183 For example, a comment added to a message has an entry name of 184 "/message/comment". This entry is composed of several attributes 185 such as "value", "modtime", etc. which contain the properties and 186 data of the entry. 188 The protocol changes to IMAP described below allow a client to 189 access or change the values of any attributes in any entries in a 190 message annotation, assuming it has sufficient access rights to do 191 so (see section 8.7 for specifics). 193 6.2 Namespace of Entries and Attributes 195 Each message annotation is made up of a set of entries. Each entry 196 has a hierarchical name in UTF-8, with each component of the name 197 separated by a slash ("/"). 199 Each entry is made up of a set of attributes. Each attribute has a 200 hierarchical name in UTF-8, with each component of the name 201 separated by a period ("."). 203 The value of an attribute is NIL (has no value), or is a string of 204 zero or more octets. 206 Entry and attribute names MUST NOT contain asterisk ("*") or percent 207 ("%") characters and MUST be valid UTF-8 strings which do not 208 contain the NULL octet. Invalid entry or attribute names result in 209 a BAD response in any IMAP commands where they are used. 211 Use of non-visible UTF-8 characters in entry and attribute names is 212 strongly discouraged. 214 This specification defines an initial set of entry and attribute 215 names available for use in message annotations. In addition, an 216 extension mechanism is described to allow additional names to be 217 added for extensibility. 219 6.2.1 Entry Names 221 Entry names MUST be specified in a standards track or IESG approved 222 experimental RFC, or fall under the vendor namespace. See section 223 11.1 for the registration template. 225 /message 226 Defines the top-level of entries associated with an entire 227 message. This entry itself does not contain any attributes. 229 /message/comment 230 Defines a comment or note associated with an entire message. 232 /message/flags 233 Defines the top-level of entries for client-use flags associated 234 with an entire message. All sub-entries are maintained entirely 235 by the client. There is no implicit change to any flag by the 236 server. 238 /message/flags/redirected 239 /message/flags/forwarded 240 Defines client-use flags for an entire message. The "value" 241 attribute of these entries must be either "1", "0" or NIL. The 242 'redirected' flag indicates that a message has been handed off 243 to someone else, by resending the message with minimal 244 alterations, and in such a way that a reply by the new recipient 245 is addressed to the original author, not the user who performed 246 the redirection. The 'forwarded' flag indicates the message was 247 resent to another user, embedded within or attached to a new 248 message. 250 /message/smtp-envelope 251 Defines the top-level of entries which together describe the 252 SMTP envelope used in delivery of the message. There are no 253 attributes at this level. The client SHOULD NOT modify the 254 /message/smtp-envelope entry or any sub-entries or any of their 255 attributes, except in messages which have the DRAFT flag set. 256 /message/smtp-envelope/from 257 /message/smtp-envelope/to 258 /message/smtp-envelope/orcpt 259 /message/smtp-envelope/envid 260 Contains the properties of the SMTP envelope: 'from' is the 261 return-path of the message; 'to' is the recipient of the 262 message. 'orcpt' and 'envid' contain the original recipient and 263 envelope ID as specified in [SMTP-DSN]. 265 /message/subject 266 Contains text supplied by the message recipient, to be used by 267 the client instead of the original message Subject. 269 /message/vendor/ 270 Defines the top-level of entries associated with an entire 271 message as created by a particular product of some vendor. 272 These sub-entries can be used by vendors to provide 273 client-specific attributes. The vendor-token MUST be registered 274 with IANA. 276 /body/ 277 Defines the top-level of entries associated with a specific body 278 part of a message. This entry itself does not contain any 279 attributes. The part-specifier uses the same part specifier 280 syntax as the BODY message data item in the FETCH command 281 [IMAP4]. 283 /body//comment 284 Defines a comment or note associated with a specific body part 285 of a message. 287 /body//flags 288 Defines the top-level of entries associated with flag state for 289 a specific body part of a message. All sub-entries are 290 maintained entirely by the client. There is no implicit change 291 to any flag by the server. 293 /body//flags/seen 294 /body//flags/answered 295 /body//flags/flagged 296 /body//flags/forwarded 297 Defines flags for a specific body part of a message. The 298 "value" attribute of these entries must be either "1", "0" or 299 NIL. 301 /body//vendor/ 302 Defines the top-level of entries associated with a specific body 303 part of a message as created by a particular product of some 304 vendor. This entry can be used by vendors to provide client 305 specific attributes. The vendor-token MUST be registered with 306 IANA. 308 6.2.2 Attribute Names 310 Attribute names MUST be specified in a standards track or IESG 311 approved experimental RFC, or fall under the vendor namespace. See 312 section 11.1 for the registration template. 314 All attribute names implicitly have a ".priv" and a ".shared" suffix 315 which maps to private and shared versions of the entry. Searching 316 or fetching without using either suffix includes both. Storing 317 without using either suffix stores into the default. The default is 318 set per-mailbox. See section 7 for more information. 320 value 321 The data value of the attribute. 323 size 324 The size of the value, in octets. Set automatically by the 325 server, read-only to clients. 327 modtime 328 An opaque value set by the server when this entry is modified. 329 It can be used by the client to request notification of which 330 entries have changed relative to that of a known entry. In 331 addition to its use in disconnected/synchronization operations, 332 it can also be helpful in determining which entries have changed 333 while a client is connected. (The value is intended to be used 334 only for comparisons within a server, not as an accurate 335 timestamp.) It is described more fully in section 3.1.1 of 336 [ACAP]. 338 content-type 339 A MIME [MIME] content type and subtype that describes the nature 340 of the content of the "value" attribute. If not present, a 341 value of "text/plain; charset=utf8" is assumed. 343 vendor. 344 Defines an attribute associated with a particular product of 345 some vendor. This attribute can be used by vendors to provide 346 client specific attributes. The vendor-token MUST be registered 347 with IANA. 349 7 Private versus Shared 351 Some IMAP mailboxes are private, accessible only to the owning user. 352 Other mailboxes are not, either because the owner has set an ACL 353 [ACL-EXT] which permits access by other users, or because it is a 354 shared mailbox. 356 This raises the issue of shared versus private annotations. 358 If all annotations are private, it is impossible to set annotations 359 in a shared or otherwise non-private mailbox that are visible to 360 other users. This eliminates what could be a useful aspect of 361 annotations in a shared environment. An example of such use is a 362 shared IMAP folder containing bug reports. Engineers may want to 363 use annotations to add information to existing messages, indicate 364 assignments, status, etc. This use requires shared annotations. 366 If all annotations are shared, it is impossible to use annotations 367 for private notes on messages in shared mailboxes. Also, modifying 368 an ACL to permit access to a mailbox by other users may 369 unintentionally expose private information. 371 There are also situations in which both shared and private 372 annotations are useful. For example, an administrator may want to 373 set shared annotations on messages in a shared folder, which 374 individual users may wish to supplement with additional notes. 376 If shared and private annotations are to coexist, we need a clear 377 way to differentiate them. Also, it should be as easy as possible 378 for a client to access both and not overlook either. There is also 379 a danger in allowing a client to store an annotation without knowing 380 if it is shared or private. 382 This document proposes two standard suffixes for all attributes: 383 ".shared" and ".priv". A search, fetch, or sort which specifies 384 neither uses both. Store operations MUST explicitly use .priv or 385 .shared suffixes. 387 8 IMAP Protocol Changes 389 8.1 ANNOTATION Message Data Item in FETCH Command 391 This extension adds an ANNOTATION message data item to the FETCH 392 command. This allows clients to retrieve annotations for a range of 393 messages in the currently selected mailbox. 395 ANNOTATION 396 The ANNOTATION message data item, when used by the client in the 397 FETCH command, takes an entry specifier and an attribute 398 specifier. 400 Example: 401 C: a FETCH 1 (ANNOTATION ("/message/comment" "value")) 402 S: * 1 FETCH (ANNOTATION ("/message/comment" 403 ("value.priv" "My comment" 404 "value.shared" "Group note"))) 405 S: a OK Fetch complete 407 In the above example, the content of the "value" attribute 408 for the "/message/comment" entry is requested by the client 409 and returned by the server. Since neither ".shared" nor 410 ".priv" was specified, both are returned. 412 "*" and "%" wildcard characters can be used in either specifier to 413 match one or more characters at that position, with the exception 414 that "%" does not match the hierarchy delimiter for the specifier it 415 appears in (that is, "/" for an entry specifier or "." for an 416 attribute specifier). Thus an entry specifier of "/message/%" 417 matches entries such as "/message/comment" and "/message/subject", 418 but not "/message/flags/redirected". 420 Examples: 421 C: a FETCH 1 (ANNOTATION ("/message/*" ("value.priv" 422 "modtime.priv"))) 423 S: * 1 FETCH (ANNOTATION 424 (("/message/comment" ("value.priv" "My comment" 425 "modtime.priv" "20000704000001")) 426 ("/message/subject" ("value.priv" "Rhinoceroses!" 427 "modtime.priv" "19991231235959")) 428 ("/message/vendor/eudora/label.priv" 429 ("value.priv" "label43" 430 "modtime.priv" "20000705101502")) 431 ("/message/vendor/eudora/personality" 432 ("value.priv" "Tallulah Bankhead" 433 "modtime.priv" "20000705101558")))) 434 S: a OK Fetch complete 435 In the above example, the contents of the private "value" and 436 "modtime" attributes for any entries in the "/message" hierarchy are 437 requested by the client and returned by the server. 439 C: a FETCH 1 (ANNOTATION ("/message/%" "value.shared")) 440 S: * 1 FETCH (ANNOTATION 441 (("/message/comment" ("value.shared" "Patch Mangler")) 442 ("/message/subject" ("value.shared" "Patches? We don' 443 need no steenkin patches!")))) 444 S: a OK Fetch complete 446 In the above example, the contents of the shared "value" 447 attributes for entries at the top level only of the 448 "/message" hierarchy are requested by the client and 449 returned by the server. 451 Entry and attribute specifiers can be lists of atomic specifiers, so 452 that multiple items of each type may be returned in a single FETCH 453 command. 455 Examples: 456 C: a FETCH 1 (ANNOTATION 457 (("/message/comment" "/message/subject") "value.priv")) 458 S: * 1 FETCH (ANNOTATION 459 (("/message/comment" ("value.priv" "What a chowder-head")) 460 ("/message/subject" ("value.priv" "How to crush beer 461 cans")))) 462 S: a OK Fetch complete 464 In the above example, the contents of the private "value" attributes 465 for the two entries "/message/comment" and "/message/subject" are 466 requested by the client and returned by the server. 468 8.2 ANNOTATION Message Data Item in FETCH Response 470 The ANNOTATION message data item in the FETCH response displays 471 information about annotations in a message. 473 ANNOTATION parenthesised list 475 The response consists of a list of entries, each of which has a 476 list of attribute-value pairs. 478 Examples: 479 C: a FETCH 1 (ANNOTATION ("/message/comment" "value")) 480 S: * 1 FETCH (ANNOTATION ("/message/comment" 481 ("value.priv" "My comment" 482 "value.shared" NIL))) 483 S: a OK Fetch complete 484 In the above example, a single entry with a single attribute-value 485 pair is returned by the server. Since the client did not specify a 486 ".shared" or ".priv" suffix, both are returned. Only the private 487 attribute has a value (the shared value is NIL). 489 C: a FETCH 1 (ANNOTATION 490 (("/message/comment" "/message/subject") "value")) 491 S: * 1 FETCH (ANNOTATION 492 (("/message/comment" ("value.priv" "My comment" 493 "value.shared" NIL)) 494 ("/message/subject" ("value.priv" "My subject" 495 "value.shared" NIL)))) 496 S: a OK Fetch complete 498 In the above example, two entries each with a single attribute-value 499 pair are returned by the server. Since the client did not specify a 500 ".shared" or ".priv" suffix, both are returned. Only the private 501 attributes have values; the shared attributes are NIL. 503 C: a FETCH 1 (ANNOTATION 504 ("/message/comment" ("value" "modtime"))) 505 S: * 1 FETCH (ANNOTATION 506 (("/message/comment" 507 ("value.priv" "My comment" 508 "value.shared" NIL 509 "modtime.priv" "19990203205432" 510 "modtime.shared" NIL)))) 511 S: a OK Fetch complete 513 In the above example, a single entry with two attribute-value pairs 514 is returned by the server. Since the client did not specify a 515 ".shared" or ".priv" suffix, both are returned. Only the private 516 attributes have values; the shared attributes are NIL. 518 Servers SHOULD send ANNOTATION message data items in unsolicited 519 FETCH responses if an annotation entry is changed by a third-party. 520 This allows servers to keep clients updated with changes to 521 annotations by other clients. 523 Servers MUST NOT include ANNOTATION data in unsolicited responses 524 until the client has used ANNOTATION data in a FETCH command. This 525 restriction avoids sending ANNOTATION data to a client until the 526 client has shown it is capable of handling it. 528 <<>> 529 Is this prohibition really necessary? 531 * OK [ANNOTATIONS FLAGS MODTIME ] 533 8.3 ANNOTATION Message Data Item in STORE 534 ANNOTATION 535 Sets the specified list of entries by adding or replacing the 536 specified attributes with the values provided. Clients can use 537 NIL for values of attributes it wants to remove from entries. 539 The ANNOTATION message data item used with the STORE command has an 540 implicit ".SILENT" behavior. This means the server does not 541 generate an untagged FETCH in response to the STORE command and 542 assumes that the client updates its own cache if the command 543 succeeds. 545 Examples: 546 C: a STORE 1 ANNOTATION ("/message/comment" 547 ("value.priv" "My new comment")) 548 S: a OK Store complete 550 In the above example, the entry "/message/comment" is created (if 551 not already present) and the private attribute "value" with data set 552 to "My new comment" is created if not already present, or replaced 553 if it exists. 555 C: a STORE 1 ANNOTATION ("/message/comment" 556 ("value.shared" NIL)) 557 S: a OK Store complete 559 In the above example, the shared "value" attribute of the entry 560 "/message/comment" is removed. 562 Multiple entries can be set in a single STORE command by listing 563 entry-attribute-value pairs in the list. 565 Example: 566 C: a STORE 1 ANNOTATION ("/message/comment" ("value.priv" 567 "Get tix Tuesday") 568 "/message/subject" ("value.priv" 569 "Wots On")) 570 S: a OK Store complete 572 In the above example, the entries "/message/comment" and 573 "/message/subject" are created (if not already present) and the 574 private attribute "value" is created for each entry if not already 575 present, or replaced if they exist. 577 Multiple attributes can be set in a single STORE command by listing 578 multiple attribute-value pairs in the entry list. 580 Example: 581 C: a STORE 1 ANNOTATION ("/message/comment" 582 ("value.priv" "My new comment" 583 "vendor.foobar.priv" "foo's bar")) 584 S: a OK Store complete 585 In the above example, the entry "/message/comment" is created (if 586 not already present) and the private attributes "value" and 587 "vendor.foobar" are created if not already present, or replaced if 588 they exist. 590 8.4 ANNOTATION Message Data Item in APPEND 592 ANNOTATION 593 Sets the specified list of entries and attributes in the 594 resulting message. 596 Example: 597 C: a APPEND drafts ANNOTATION ("/message/comment" 598 ("value.priv" "Don't send until we hear from Sally")) {310} 599 S: + Ready for literal data 600 C: MIME-Version: 1.0 601 ... 602 C: 603 S: a OK APPEND completed 605 In the above example, a comment with a private value is added to a 606 new message appended to the mailbox. The ellipsis represents the 607 bulk of the message. 609 8.5 ANNOTATION Criterion in SEARCH 611 The ANNOTATION criterion for the SEARCH command allows a client to 612 search for a specified string in the value of an annotation entry of 613 a message. 614 ANNOTATION 616 Messages that have annotations with entries matching 617 and attributes matching and the specified string 618 in their values are returned in the SEARCH results. The "*" 619 character can be used in the entry or attribute name fields to match 620 any content in those items. The "%" character can be used in the 621 entry or attribute name fields to match a single level of hierarchy 622 only. 624 Examples: 625 C: a SEARCH ANNOTATION "/message/comment" "value" "IMAP4" 626 S: * SEARCH 2 3 5 7 11 13 17 19 23 627 S: a OK Search complete 629 In the above example, the message numbers of any messages containing 630 the string "IMAP4" in the shared or private "value" attribute of the 631 "/message/comment" entry are returned in the search results. 633 C: a SEARCH ANNOTATION "*" "*" "IMAP4" 634 S: * SEARCH 1 2 3 5 8 13 21 34 635 S: a OK Search complete 637 In the above example, the message numbers of any messages containing 638 the string "IMAP4" in any attribute (public or private) of any entry 639 are returned in the search results. 641 A special case exists when the "modtime" attribute is used as the 642 parameter in the ANNOTATION search criterion. In 643 this case the server matches messages when the corresponding 644 "modtime" value is greater than the value supplied in the ANNOTATION 645 criterion. This allows a client, for example, to find out which 646 messages contain annotations that have changed since the last time 647 it updated its disconnected cache. 649 Example: 650 C: a SEARCH ANNOTATION "*" "modtime" "1999101713283412" 651 S: * SEARCH 1 3 6 10 15 21 28 36 45 55 652 S: a OK Search complete 654 In the above example, the message numbers of any messages whose 655 "modtime" attribute of any entry exceeds the value 656 "1999101713283412" are returned in the search results. Both public 657 and private attributes are searched. 659 8.6 ANNOTATION Key in SORT 661 The ANNOTATION criterion for the SORT command [SORT-EXT] instructs 662 the server to return the message numbers or UIDs of a mailbox, 663 sorted using the values of the specified annotations. The 664 ANNOTATION criterion is available if the server returns both 665 "ANNOTATE" and "SORT" as supported capabilities in the CAPABILITY 666 command response. 667 ANNOTATION 669 Messages are sorted using the values of the 670 attributes in the entries. (The charset argument 671 determines sort order, as specified in the SORT extension 672 description.) 674 Examples: 675 C: a SORT (ANNOTATION "/message/subject" "value.shared") UTF-8 676 ALL 677 S: * SORT 2 3 4 5 1 11 10 6 7 9 8 678 S: a OK Sort complete 680 In the above example, the message numbers of all messages are 681 returned, sorted according to the shared "value" attribute of the 682 "/message/subject" entry. 684 Note that the ANNOTATION sort key must include a fully specified 685 entry and attribute -- wildcards are not allowed. 687 8.7 ACL Rights 689 The "r" right, as specified in [ACL-EXT], is required to use 690 annotations in any command other than STORE. 692 The "w" right is needed to use shared annotations in the STORE 693 command. 695 The "s" right is needed to use private annotations in the STORE 696 command. 698 <<>> 700 Should there be a special ACL bit to indicate if annotations are 701 shared or private by default for a mailbox? 703 9 Interaction with MODTIME 705 The [MODTIME-EXT] document defines an IMAP extension which allows 706 clients to be supplied with an opaque value called a modtime. The 707 specific value is server dependent, but has the property that all 708 such values issued by a server are numerically increasing with 709 respect to the order of changes. That is, for any two items, the 710 one that was modified later has a greater modtime. 712 10 Formal Syntax 714 The following syntax specification uses the Augmented Backus-Naur 715 Form (ABNF) notation as specified in [ABNF]. 717 Non-terminals referenced but not defined below are as defined by 718 [IMAP4]. 720 Except as noted otherwise, all alphabetic characters are case- 721 insensitive. The use of upper or lower case characters to define 722 token strings is for editorial clarity only. Implementations MUST 723 accept these strings in a case-insensitive fashion. 725 append = "APPEND" SP mailbox [SP flag-list] [SP date-time] 726 [SP "ANNOTATION" SP att-annotate] 727 SP literal 728 ; modifies original IMAP4 APPEND command 730 att-annotate = "(" entry-att *(SP entry-att) ")" 732 fetch-att =/ fetch-annotate 733 ; modifies original IMAP4 fetch-att 735 fetch-annotate = "ANNOTATION" SP "(" entries SP attribs ")" 736 fetch-ann-resp = "ANNOTATION" SP "(" entry-att *(SP entry-att) ")" 737 store-att-flags =/ att-annotate 738 ; modifies original IMAP4 STORE command 740 search-key =/ search-annotate 741 ; modifies original IMAP4 search-key 743 search-annotate = "ANNOTATION" SP entry-match SP attrib-match 744 SP value 746 sort-key =/ sort-annotate 747 ; modifies original 748 ; draft-crispin-imapext-sort-xx.txt sort-key 750 sort-annotate = "ANNOTATION" SP entry SP attrib 752 status =/ "ANNOTATION-MODTIME" 753 ; modifies original IMAP4 STATUS command 755 entries = entry-match / 756 "(" entry-match *(SP entry-match) ")" 757 attribs = attrib-match / 758 "(" attrib-match *(SP attrib-match) ")" 759 entry-att = entry SP "(" att-value *(SP att-value) ") 760 att-value = attrib SP value 762 utf8-char = %x01-FF 763 ; any character, excluding NUL 764 atom-slash = any utf8-char except "/" 765 atom-dot = any utf8-char except "." 767 entry = DQUOTE 1*atom-slash *("/" 1*atom-slash) DQUOTE 768 entry-match = DQUOTE 1*entry-match-atom 769 *("/" 1*entry-match-atom) DQUOTE 770 entry-match-atom = 1*(list-wildcards / atom-slash) 771 *(list-wildcards / atom-slash) 773 attrib = DQUOTE 1*atom-dot *("/" 1*atom-dot) DQUOTE 774 attrib-match = DQUOTE 1*attrib-match-atom 775 *("/" 1*attrib-match-atom) DQUOTE 776 attrib-match-atom = 1*(list-wildcards / atom-dot) 777 *(list-wildcards / atom-dot) 779 value = nstring 781 11 IANA Considerations 783 Both entry names and attribute names MUST be specified in a 784 standards track or IESG approved experimental RFC, or fall under the 785 vendor namespace. Vendor names MUST be registered. 787 11.1 Entry and Attribute Registration Template 789 To: iana@iana.org 790 Subject: IMAP Annotate Registration 792 Please register the following IMAP Annotate item: 794 [] Entry [] Attribute 795 [] Vendor [] Open: RFC _______ 797 Name: ______________________________ 799 Description: _______________________ 801 ____________________________________ 803 ____________________________________ 805 Contact person: ____________________ 807 email: ____________________ 809 12 Security Considerations 811 Care must be taken to ensure that annotations whose values are 812 intended to remain private are not stored in mailboxes which are 813 accessible to other users. This includes mailboxes owned by the 814 user by whose ACLs permit access by others as well as any shared 815 mailboxes. 817 13 References 819 [ABNF] Crocker, Overell, "Augmented BNF for Syntax Specifications: 820 ABNF", RFC 2234, Internet Mail Consortium, Demon Internet Ltd, 821 November 1997. 823 [ACAP] Newman, Myers, "ACAP -- Application Configuration Access 824 Protocol", RFC 2244, Innosoft, Netscape, November 1997. 826 [ACL-EXT] Myers, "IMAP4 ACL extension", RFC 2086, Carnegie Mellon, 827 January 1997. 829 [IMAP4] Crispin, "Internet Message Access Protocol - Version 4rev1", 830 RFC 2060, University of Washington, December 1996. 832 [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate 833 Requirement Levels", RFC 2119, Harvard University, March 1997. 835 [MODTIME-EXT] Melnikov, "IMAP Conditional Store", work in progress. 836 838 [SMTP-DSN] Moore, "SMTP Service Extension for Delivery Status 839 Notifications", RFC 1891, University of Tennessee, January 1996. 841 [SORT-EXT] Crispin, "Internet Message Access Protocol -- SORT 842 Extension", work in progress. 843 845 14 Acknowledgments 847 Many thanks to Chris Newman for his detailed comments on the first 848 draft of this document, and to the participants at the ACAP working 849 dinner in Pittsburgh. 851 15 Authors' Addresses 853 Randall Gellens 854 QUALCOMM Incorporated 855 5775 Morehouse Dr. 856 San Diego, CA 92121-2779 857 U.S.A. 859 Email: randy@qualcomm.com 861 Cyrus Daboo 862 Cyrusoft International, Inc. 863 Suite 780, 5001 Baum Blvd. 864 Pittsburgh, PA 15213 865 U.S.A. 867 Email: daboo@cyrusoft.com 869 16 Full Copyright Statement 871 Copyright (C) The Internet Society 2001. All Rights Reserved. 873 This document and translations of it may be copied and furnished to 874 others, and derivative works that comment on or otherwise explain it 875 or assist in its implementation may be prepared, copied, published 876 and distributed, in whole or in part, without restriction of any 877 kind, provided that the above copyright notice and this paragraph 878 are included on all such copies and derivative works. However, this 879 document itself may not be modified in any way, such as by removing 880 the copyright notice or references to the Internet Society or other 881 Internet organizations, except as needed for the purpose of 882 developing Internet standards in which case the procedures for 883 copyrights defined in the Internet Standards process must be 884 followed, or as required to translate it into languages other than 885 English. 887 The limited permissions granted above are perpetual and will not be 888 revoked by the Internet Society or its successors or assigns. 890 This document and the information contained herein is provided on an 891 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 892 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 893 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 894 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 895 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.