idnits 2.17.1 draft-ietf-imapext-annotate-03.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. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 2 instances of too long lines in the document, the longest one being 1 character 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 (January 2002) is 8135 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 349, 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) ** Obsolete normative reference: RFC 1891 (ref. 'SMTP-DSN') (Obsoleted by RFC 3461) -- Possible downref: Non-RFC (?) normative reference: ref. 'SORT-EXT' Summary: 12 errors (**), 0 flaws (~~), 3 warnings (==), 4 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-03.txt January 2002 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 2002. 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 . . . . . . . . . . . . . . . . . . . . . . . . . 5 39 6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 5 40 6.2 Namespace of Entries and Attributes . . . . . . . . . . 5 41 6.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . . 5 42 6.2.2 Attribute Names . . . . . . . . . . . . . . . . . . 7 43 7 Private versus Shared and Access Control . . . . . . . . . . 8 44 8 IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . 9 45 8.1 Optional parameters with the SELECT/EXAMINE commands . . 9 46 8.2 ANNOTATION Message Data Item in FETCH Command . . . . . 10 47 8.3 ANNOTATION Message Data Item in FETCH Response . . . . . 11 48 8.4 ANNOTATION Message Data Item in STORE . . . . . . . . . 13 49 8.5 ANNOTATION Message Data Item in APPEND . . . . . . . . . 14 50 8.6 ANNOTATION Criterion in SEARCH . . . . . . . . . . . . . 14 51 8.7 ANNOTATION Key in SORT . . . . . . . . . . . . . . . . . 15 52 9 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . 15 53 10 IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 54 10.1 Entry and Attribute Registration Template . . . . . . . 17 55 11 Security Considerations . . . . . . . . . . . . . . . . . . . 17 56 12 References . . . . . . . . . . . . . . . . . . . . . . . . . 18 57 13 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 58 14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 18 59 15 Full Copyright Statement . . . . . . . . . . . . . . . . . . 19 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 Change History 88 Changes from -02 to -03: 89 1. Removed reference to status modtime item. 90 2. Added missing 'notify' and 'ret' dsn annotations for 91 /message/smtp-envelope. 92 3. Added requirement to store data permanently - no 93 'session only' annotations. 94 4. Removed Access Control section. Replaced with comments 95 on read-only/read-write mailboxes and storing private or 96 shared annotations. 97 5. Removed STORE to default .priv or .shared. 98 6. Added section on optional select parameters. 100 Changes from -01 to -02: 101 1. Now require .priv or .shared on store operations. 103 Changes from -00 to -01: 104 1. MODTIME moved to its own draft, which this draft now 105 depends on. Thus, Conditional Annotation STORE and 106 related items deleted from this draft. 107 2. Private versus Shared Annotations: both are possible 108 (separately addressable using ".priv" and ".shared" 109 suffixes). There is a per-mailbox setting for the 110 default. It is an open issue how this is viewed or 111 changed by the client. 112 3. In ACLs, the "w" right is needed to updated shared state; 113 the "s" right is needed to update private state. 114 4. Various clarifications and text modifications. 115 5. Added 'forwarded' flag for message parts. 117 Changes from pre-imapext to -00: 118 1. Clarified text describing attributions, entries, and 119 attributes. 120 2. Changed 'modifiedsince' to 'modtime'; referenced ACAP spec. 121 3. Deleted 'queued' flag. 122 4. Expanded and explained smtp-envelope entry. 123 5. Restricted including ANNOTATION data in unsolicited responses 124 until the client uses it first. (Open issue as to if needed). 125 6. Examples now only use valid entries and attributes. 126 7. Updated Security Considerations. 127 8. Content-Type now defaults to text/plain. 128 9. Open Issue: Shared vs. private annotations. 129 10. Open issue: Annotation Modtime untagged response or VALIDTIME 130 FETCH data. 131 11. Open issue: Conditional annotation STORE. 132 12. ANNOTATION criterion available if both "ANNOTATE" and "SORT" 133 in CAPABILITY command response. 134 13. Prohibition on annotations in lieu of base spec functionality. 135 14. Specified required ACL rights. 136 15. ANNOTATION message data item in APPEND. 137 16. ANNOTATION-MODTIME message data item in STATUS. 138 17. Replaced ATOM_CHAR with utf8-char. 139 18. Updated other ABNF entries. 141 5 Introduction and Overview 143 The ANNOTATE extension is present in any IMAP4 implementation which 144 returns "ANNOTATE" as one of the supported capabilities in the 145 CAPABILITY response. 147 The ANNOTATE extension adds a new message data item to the FETCH and 148 STORE commands, as well as adding SEARCH and SORT keys and an APPEND 149 modifier. 151 This extension makes the following changes to the IMAP4 protocol: 153 a) adds a new ANNOTATION message data item for use in FETCH 154 b) adds a new ANNOTATION message data item for use in STORE 155 c) adds a new ANNOTATION search criterion for use in SEARCH 156 d) adds a new ANNOTATION sort key for use in SORT extension 157 e) adds a new ANNOTATION data item for use in APPEND 158 f) adds a extension mechanism for adding parameters to the 159 SELECT/EXAMINE commands and defines the ANNOTATE parameter 161 The data model used for the storage of annotations is based on that 162 of the Application Configuration Access Protocol [ACAP]. Note that 163 there is no inheritance in annotations. 165 Clients MUST NOT use annotations in lieu of equivalent IMAP base 166 specification facilities. For example, use of a "seen" flag in the 167 vendor namespace together with ".PEEK" in fetches. Such behaviour 168 would significantly reduce IMAP interoperability. 170 If a server supports annotations, then it MUST store all annotation 171 data permanently, i.e. there is no concept of 'session only' 172 annotations that would correspond to the behaviour of 'session' 173 flags as defined in the IMAP base specification. The exception to 174 this is IMAP flags (which are accessible directly through 175 annotations) which may be 'session only' as determined by the FLAGS 176 and PERMANENTFLAGS responses to a SELECT or EXAMINE command. 178 This extension also introduces a generalised mechanism for adding 179 parameters to the SELECT or EXAMINE commands. It is anticipated 180 that other extensions may want to utilise this, so it is not 181 strictly dependent on the ANNOTATE extension being present. 183 The rest of this document describes the data model and protocol 184 changes more rigorously. 186 6 Data Model 188 6.1 Overview 190 The data model used in ANNOTATE is that of a uniquely named entry 191 which contains a set of standard attributes. A single coherent unit 192 of "metadata" for a message is stored as a single entry, made up of 193 several attributes. 195 For example, a comment added to a message has an entry name of 196 "/message/comment". This entry is composed of several attributes 197 such as "value", "size", etc. which contain the properties and data 198 of the entry. 200 The protocol changes to IMAP described below allow a client to 201 access or change the values of any attributes in any entries in a 202 message annotation, assuming it has sufficient access rights to do 203 so (see Section 7 for specifics). 205 6.2 Namespace of Entries and Attributes 207 Each message annotation is made up of a set of entries. Each entry 208 has a hierarchical name in UTF-8, with each component of the name 209 separated by a slash ("/"). 211 Each entry is made up of a set of attributes. Each attribute has a 212 hierarchical name in UTF-8, with each component of the name 213 separated by a period ("."). 215 The value of an attribute is NIL (has no value), or is a string of 216 zero or more octets. 218 Entry and attribute names MUST NOT contain asterisk ("*") or percent 219 ("%") characters and MUST be valid UTF-8 strings which do not 220 contain the NULL octet. Invalid entry or attribute names result in 221 a BAD response in any IMAP commands where they are used. 223 Use of non-visible UTF-8 characters in entry and attribute names is 224 strongly discouraged. 226 This specification defines an initial set of entry and attribute 227 names available for use in message annotations. In addition, an 228 extension mechanism is described to allow additional names to be 229 added for extensibility. 231 6.2.1 Entry Names 233 Entry names MUST be specified in a standards track or IESG approved 234 experimental RFC, or fall under the vendor namespace. See Section 235 10.1 for the registration template. 237 /message 238 Defines the top-level of entries associated with an entire 239 message. This entry itself does not contain any attributes. 241 /message/comment 242 Defines a comment or note associated with an entire message. 244 /message/flags 245 Defines the top-level of entries for flags associated with an 246 entire message. The "value" attribute of each of the entries 247 described below must be either "1", "0" or NIL. "1" corresponds 248 to the flag being set. 250 /message/flags/answered 251 /message/flags/flagged 252 /message/flags/deleted 253 /message/flags/seen 254 /message/flags/draft 255 /message/flags/recent 256 These correspond to the standard IMAP flags. 258 /message/flags/redirected 259 /message/flags/forwarded 260 The 'redirected' flag indicates that a message has been handed 261 off to someone else, by resending the message with minimal 262 alterations, and in such a way that a reply by the new recipient 263 is addressed to the original author, not the user who performed 264 the redirection. The 'forwarded' flag indicates the message was 265 resent to another user, embedded within or attached to a new 266 message. 268 /message/smtp-envelope 269 Defines the top-level of entries which together describe the 270 SMTP envelope used in delivery of the message. There are no 271 attributes at this level. The client SHOULD NOT modify the 272 /message/smtp-envelope entry or any sub-entries or any of their 273 attributes, except in messages which have the DRAFT flag set. 274 /message/smtp-envelope/from 275 /message/smtp-envelope/to 276 /message/smtp-envelope/orcpt 277 /message/smtp-envelope/envid 278 /message/smtp-envelope/notify 279 /message/smtp-envelope/ret 280 Contains the properties of the SMTP envelope: 'from' is the 281 return-path of the message; 'to' is the recipient of the 282 message. 'notify', 'orcpt', 'ret' and 'envid' contain the 283 notification options, original recipient, envelope ID and return 284 options as specified in [SMTP-DSN]. 286 /message/subject 287 Contains text supplied by the message recipient, to be used by 288 the client instead of the original message Subject. 290 /message/vendor/ 291 Defines the top-level of entries associated with an entire 292 message as created by a particular product of some vendor. 293 These sub-entries can be used by vendors to provide 294 client-specific attributes. The vendor-token MUST be registered 295 with IANA. 297 /body/ 298 Defines the top-level of entries associated with a specific body 299 part of a message. This entry itself does not contain any 300 attributes. The part-specifier uses the same part specifier 301 syntax as the BODY message data item in the FETCH command 302 [IMAP4]. 304 /body//comment 305 Defines a comment or note associated with a specific body part 306 of a message. 308 /body//flags 309 Defines the top-level of entries associated with flag state for 310 a specific body part of a message. All sub-entries are 311 maintained entirely by the client. There is no implicit change 312 to any flag by the server. 314 /body//flags/seen 315 /body//flags/answered 316 /body//flags/flagged 317 /body//flags/forwarded 318 Defines flags for a specific body part of a message. The 319 "value" attribute of these entries must be either "1", "0" or 320 NIL. 322 /body//vendor/ 323 Defines the top-level of entries associated with a specific body 324 part of a message as created by a particular product of some 325 vendor. This entry can be used by vendors to provide client 326 specific attributes. The vendor-token MUST be registered with 327 IANA. 329 6.2.2 Attribute Names 331 Attribute names MUST be specified in a standards track or IESG 332 approved experimental RFC, or fall under the vendor namespace. See 333 Section 10.1 for the registration template. 335 All attribute names implicitly have a ".priv" and a ".shared" suffix 336 which maps to private and shared versions of the entry. Searching 337 or fetching without using either suffix includes both. The client 338 MUST specify either a ".priv" or ".shared" suffix when storing an 339 annotation. 341 value 342 The data value of the attribute. 344 size 345 The size of the value, in octets. Set automatically by the 346 server, read-only to clients. 348 content-type 349 A MIME [MIME] content type and subtype that describes the nature 350 of the content of the "value" attribute. If not present, a 351 value of "text/plain; charset=utf8" is assumed. 353 vendor. 354 Defines an attribute associated with a particular product of 355 some vendor. This attribute can be used by vendors to provide 356 client specific attributes. The vendor-token MUST be registered 357 with IANA. 359 7 Private versus Shared and Access Control 361 Some IMAP mailboxes are private, accessible only to the owning user. 362 Other mailboxes are not, either because the owner has set an ACL 363 [ACL-EXT] which permits access by other users, or because it is a 364 shared mailbox. 366 This raises the issue of shared versus private annotations. 368 If all annotations are private, it is impossible to set annotations 369 in a shared or otherwise non-private mailbox that are visible to 370 other users. This eliminates what could be a useful aspect of 371 annotations in a shared environment. An example of such use is a 372 shared IMAP folder containing bug reports. Engineers may want to 373 use annotations to add information to existing messages, indicate 374 assignments, status, etc. This use requires shared annotations. 376 If all annotations are shared, it is impossible to use annotations 377 for private notes on messages in shared mailboxes. Also, modifying 378 an ACL to permit access to a mailbox by other users may 379 unintentionally expose private information. 381 There are also situations in which both shared and private 382 annotations are useful. For example, an administrator may want to 383 set shared annotations on messages in a shared folder, which 384 individual users may wish to supplement with additional notes. 386 If shared and private annotations are to coexist, we need a clear 387 way to differentiate them. Also, it should be as easy as possible 388 for a client to access both and not overlook either. There is also 389 a danger in allowing a client to store an annotation without knowing 390 if it is shared or private. 392 This document proposes two standard suffixes for all attributes: 393 ".shared" and ".priv". A search, fetch, or sort which specifies 394 neither uses both. Store operations MUST explicitly use .priv or 395 .shared suffixes. 397 A user can only store and fetch private annotations on messages in 398 any mailbox which they can SELECT or EXAMINE, including ones which 399 only open READ-ONLY. A user can only store and fetch shared 400 annotations on messages in any mailbox that they can SELECT and 401 which opens READ-WRITE. If a client attempts to store or fetch a 402 shared annotation on a READ-ONLY mailbox, the server MUST respond 403 with a NO response. 405 8 IMAP Protocol Changes 407 8.1 Optional parameters with the SELECT/EXAMINE commands 409 This extension adds the ability to include one or more parameters 410 with the IMAP SELECT or EXAMINE commands, to turn on or off certain 411 standard behaviour, or to add new optional behaviours required for a 412 particular extension. It is anticipated that other extensions may 413 want to use this facility, so a generalised approach is given here. 414 This facility is not dependent on the presence of the ANNOTATE 415 extension - other extensions can use it with a server that does not 416 implement ANNOTATE. 418 Optional parameters to the SELECT or EXAMINE commands are added as a 419 parenthesised list of atoms or strings, and appear after the mailbox 420 name in the standard SELECT or EXAMINE command. The order of 421 individual parameters is arbitrary. Individual parameters may 422 consist of one or more atoms or strings in a specific order. If a 423 parameter consists of more than one atom or string, it MUST appear 424 in its own parenthesised list. Any parameter not defined by 425 extensions that the server supports MUST be rejected with a NO 426 response. 428 Example: 429 C: a SELECT INBOX (ANNOTATE) 430 S: ... 431 S: a OK SELECT complete 433 In the above example, a single parameter is used with the 434 SELECT command. 436 C: a EXAMINE INBOX (ANNOTATE (RESPONSES "UID Responses") MODTIME) 437 S: ... 439 S: a OK EXAMINE complete 441 In the above example, three parameters are used with the 442 EXAMINE command. The second parameter consists of two 443 items: an atom followed by a quoted string. 445 C: a SELECT INBOX (BLURDYBLOOP) 446 S: a NO Unknown parameter in SELECT command 448 In the above example, a parameter not supported by the 449 server is incorrectly used. 451 The ANNOTATE extension defines a single optional select parameter 452 "ANNOTATE", which is used to turn on unsolicited responses for 453 annotations as described in Section 8.3. 455 8.2 ANNOTATION Message Data Item in FETCH Command 457 This extension adds an ANNOTATION message data item to the FETCH 458 command. This allows clients to retrieve annotations for a range of 459 messages in the currently selected mailbox. 461 ANNOTATION 462 The ANNOTATION message data item, when used by the client in the 463 FETCH command, takes an entry specifier and an attribute 464 specifier. 466 Example: 467 C: a FETCH 1 (ANNOTATION ("/message/comment" "value")) 468 S: * 1 FETCH (ANNOTATION ("/message/comment" 469 ("value.priv" "My comment" 470 "value.shared" "Group note"))) 471 S: a OK Fetch complete 473 In the above example, the content of the "value" attribute 474 for the "/message/comment" entry is requested by the client 475 and returned by the server. Since neither ".shared" nor 476 ".priv" was specified, both are returned. 478 "*" and "%" wildcard characters can be used in either specifier to 479 match one or more characters at that position, with the exception 480 that "%" does not match the hierarchy delimiter for the specifier it 481 appears in (that is, "/" for an entry specifier or "." for an 482 attribute specifier). Thus an entry specifier of "/message/%" 483 matches entries such as "/message/comment" and "/message/subject", 484 but not "/message/flags/redirected". 486 Examples: 487 C: a FETCH 1 (ANNOTATION ("/message/*" ("value.priv" 488 "size.priv"))) 489 S: * 1 FETCH (ANNOTATION 490 (("/message/comment" ("value.priv" "My comment" 491 "size.priv" "10")) 492 ("/message/subject" ("value.priv" "Rhinoceroses!" 493 "size.priv" "13")) 494 ("/message/vendor/foobar/label.priv" 495 ("value.priv" "label43" 496 "size.priv" "7")) 497 ("/message/vendor/foobar/personality" 498 ("value.priv" "Tallulah Bankhead" 499 "size.priv" "17")))) 500 S: a OK Fetch complete 502 In the above example, the contents of the private "value" and "size" 503 attributes for any entries in the "/message" hierarchy are requested 504 by the client and returned by the server. 506 C: a FETCH 1 (ANNOTATION ("/message/%" "value.shared")) 507 S: * 1 FETCH (ANNOTATION 508 (("/message/comment" ("value.shared" "Patch Mangler")) 509 ("/message/subject" ("value.shared" "Patches? We don' 510 need no steenkin patches!")))) 511 S: a OK Fetch complete 513 In the above example, the contents of the shared "value" 514 attributes for entries at the top level only of the 515 "/message" hierarchy are requested by the client and 516 returned by the server. 518 Entry and attribute specifiers can be lists of atomic specifiers, so 519 that multiple items of each type may be returned in a single FETCH 520 command. 522 Examples: 523 C: a FETCH 1 (ANNOTATION 524 (("/message/comment" "/message/subject") "value.priv")) 525 S: * 1 FETCH (ANNOTATION 526 (("/message/comment" ("value.priv" "What a chowder-head")) 527 ("/message/subject" ("value.priv" "How to crush beer 528 cans")))) 529 S: a OK Fetch complete 531 In the above example, the contents of the private "value" attributes 532 for the two entries "/message/comment" and "/message/subject" are 533 requested by the client and returned by the server. 535 8.3 ANNOTATION Message Data Item in FETCH Response 537 The ANNOTATION message data item in the FETCH response displays 538 information about annotations in a message. 540 ANNOTATION parenthesised list 541 The response consists of a list of entries, each of which has a 542 list of attribute-value pairs. 544 Examples: 545 C: a FETCH 1 (ANNOTATION ("/message/comment" "value")) 546 S: * 1 FETCH (ANNOTATION ("/message/comment" 547 ("value.priv" "My comment" 548 "value.shared" NIL))) 549 S: a OK Fetch complete 551 In the above example, a single entry with a single attribute-value 552 pair is returned by the server. Since the client did not specify a 553 ".shared" or ".priv" suffix, both are returned. Only the private 554 attribute has a value (the shared value is NIL). 556 C: a FETCH 1 (ANNOTATION 557 (("/message/comment" "/message/subject") "value")) 558 S: * 1 FETCH (ANNOTATION 559 (("/message/comment" ("value.priv" "My comment" 560 "value.shared" NIL)) 561 ("/message/subject" ("value.priv" "My subject" 562 "value.shared" NIL)))) 563 S: a OK Fetch complete 565 In the above example, two entries each with a single attribute-value 566 pair are returned by the server. Since the client did not specify a 567 ".shared" or ".priv" suffix, both are returned. Only the private 568 attributes have values; the shared attributes are NIL. 570 C: a FETCH 1 (ANNOTATION 571 ("/message/comment" ("value" "size"))) 572 S: * 1 FETCH (ANNOTATION 573 (("/message/comment" 574 ("value.priv" "My comment" 575 "value.shared" NIL 576 "size.priv" "10" 577 "size.shared" 0)))) 578 S: a OK Fetch complete 580 In the above example, a single entry with two attribute-value pairs 581 is returned by the server. Since the client did not specify a 582 ".shared" or ".priv" suffix, both are returned. Only the private 583 attributes have values; the shared attributes are NIL. 585 Servers MUST NOT include ANNOTATION data in unsolicited responses 586 unless the client used the ANNOTATE select parameter when it issued 587 the last SELECT or EXAMINE command. This restriction avoids sending 588 ANNOTATION data to a client unless the client explicitly asks for 589 it. 591 Servers SHOULD send ANNOTATION message data items in unsolicited 592 FETCH responses if an annotation entry is changed by a third-party, 593 and the ANNOTATE select parameter was used. This allows servers to 594 keep clients updated with changes to annotations by other clients. 596 8.4 ANNOTATION Message Data Item in STORE 598 ANNOTATION 599 Sets the specified list of entries by adding or replacing the 600 specified attributes with the values provided. Clients can use 601 NIL for values of attributes it wants to remove from entries. 603 The ANNOTATION message data item used with the STORE command has an 604 implicit ".SILENT" behaviour. This means the server does not 605 generate an untagged FETCH in response to the STORE command and 606 assumes that the client updates its own cache if the command 607 succeeds. 609 Examples: 610 C: a STORE 1 ANNOTATION ("/message/comment" 611 ("value.priv" "My new comment")) 612 S: a OK Store complete 614 In the above example, the entry "/message/comment" is created (if 615 not already present) and the private attribute "value" with data set 616 to "My new comment" is created if not already present, or replaced 617 if it exists. 619 C: a STORE 1 ANNOTATION ("/message/comment" 620 ("value.shared" NIL)) 621 S: a OK Store complete 623 In the above example, the shared "value" attribute of the entry 624 "/message/comment" is removed. 626 Multiple entries can be set in a single STORE command by listing 627 entry-attribute-value pairs in the list. 629 Example: 630 C: a STORE 1 ANNOTATION ("/message/comment" ("value.priv" 631 "Get tix Tuesday") 632 "/message/subject" ("value.priv" 633 "Wots On")) 634 S: a OK Store complete 636 In the above example, the entries "/message/comment" and 637 "/message/subject" are created (if not already present) and the 638 private attribute "value" is created for each entry if not already 639 present, or replaced if they exist. 641 Multiple attributes can be set in a single STORE command by listing 642 multiple attribute-value pairs in the entry list. 644 Example: 645 C: a STORE 1 ANNOTATION ("/message/comment" 646 ("value.priv" "My new comment" 647 "vendor.foobar.priv" "foo's bar")) 648 S: a OK Store complete 650 In the above example, the entry "/message/comment" is created (if 651 not already present) and the private attributes "value" and 652 "vendor.foobar" are created if not already present, or replaced if 653 they exist. 655 8.5 ANNOTATION Message Data Item in APPEND 657 ANNOTATION 658 Sets the specified list of entries and attributes in the 659 resulting message. 661 Example: 662 C: a APPEND drafts ANNOTATION ("/message/comment" 663 ("value.priv" "Don't send until we hear from Sally")) {310} 664 S: + Ready for literal data 665 C: MIME-Version: 1.0 666 ... 667 C: 668 S: a OK APPEND completed 670 In the above example, a comment with a private value is added to a 671 new message appended to the mailbox. The ellipsis represents the 672 bulk of the message. 674 8.6 ANNOTATION Criterion in SEARCH 676 The ANNOTATION criterion for the SEARCH command allows a client to 677 search for a specified string in the value of an annotation entry of 678 a message. 679 ANNOTATION 681 Messages that have annotations with entries matching 682 and attributes matching and the specified string 683 in their values are returned in the SEARCH results. The "*" 684 character can be used in the entry or attribute name fields to match 685 any content in those items. The "%" character can be used in the 686 entry or attribute name fields to match a single level of hierarchy 687 only. 689 Examples: 690 C: a SEARCH ANNOTATION "/message/comment" "value" "IMAP4" 691 S: * SEARCH 2 3 5 7 11 13 17 19 23 692 S: a OK Search complete 693 In the above example, the message numbers of any messages containing 694 the string "IMAP4" in the shared or private "value" attribute of the 695 "/message/comment" entry are returned in the search results. 697 C: a SEARCH ANNOTATION "*" "*" "IMAP4" 698 S: * SEARCH 1 2 3 5 8 13 21 34 699 S: a OK Search complete 701 In the above example, the message numbers of any messages containing 702 the string "IMAP4" in any attribute (public or private) of any entry 703 are returned in the search results. 705 8.7 ANNOTATION Key in SORT 707 The ANNOTATION criterion for the SORT command [SORT-EXT] instructs 708 the server to return the message numbers or UIDs of a mailbox, 709 sorted using the values of the specified annotations. The 710 ANNOTATION criterion is available if the server returns both 711 "ANNOTATE" and "SORT" as supported capabilities in the CAPABILITY 712 command response. 713 ANNOTATION 715 Messages are sorted using the values of the 716 attributes in the entries. (The charset argument 717 determines sort order, as specified in the SORT extension 718 description.) 720 Examples: 721 C: a SORT (ANNOTATION "/message/subject" "value.shared") UTF-8 722 ALL 723 S: * SORT 2 3 4 5 1 11 10 6 7 9 8 724 S: a OK Sort complete 726 In the above example, the message numbers of all messages are 727 returned, sorted according to the shared "value" attribute of the 728 "/message/subject" entry. 730 Note that the ANNOTATION sort key must include a fully specified 731 entry and attribute -- wildcards are not allowed. 733 9 Formal Syntax 735 The following syntax specification uses the Augmented Backus-Naur 736 Form (ABNF) notation as specified in [ABNF]. 738 Non-terminals referenced but not defined below are as defined by 739 [IMAP4]. 741 Except as noted otherwise, all alphabetic characters are case- 742 insensitive. The use of upper or lower case characters to define 743 token strings is for editorial clarity only. Implementations MUST 744 accept these strings in a case-insensitive fashion. 746 append = "APPEND" SP mailbox [SP flag-list] [SP date-time] 747 [SP "ANNOTATION" SP att-annotate] 748 SP literal 749 ; modifies original IMAP4 APPEND command 751 att-annotate = "(" entry-att *(SP entry-att) ")" 753 fetch-att =/ fetch-annotate 754 ; modifies original IMAP4 fetch-att 756 fetch-annotate = "ANNOTATION" SP "(" entries SP attribs ")" 757 fetch-ann-resp = "ANNOTATION" SP "(" entry-att *(SP entry-att) ")" 759 store-att-flags =/ att-annotate 760 ; modifies original IMAP4 STORE command 762 search-key =/ search-annotate 763 ; modifies original IMAP4 search-key 765 search-annotate = "ANNOTATION" SP entry-match SP attrib-match 766 SP value 768 sort-key =/ sort-annotate 769 ; modifies original 770 ; draft-crispin-imapext-sort-xx.txt sort-key 772 sort-annotate = "ANNOTATION" SP entry SP attrib 774 entries = entry-match / 775 "(" entry-match *(SP entry-match) ")" 776 attribs = attrib-match / 777 "(" attrib-match *(SP attrib-match) ")" 778 entry-att = entry SP "(" att-value *(SP att-value) ") 779 att-value = attrib SP value 781 utf8-char = %x01-FF 782 ; any character, excluding NUL 783 atom-slash = any utf8-char except "/" 784 atom-dot = any utf8-char except "." 786 entry = DQUOTE 1*atom-slash *("/" 1*atom-slash) DQUOTE 787 entry-match = DQUOTE 1*entry-match-atom 788 *("/" 1*entry-match-atom) DQUOTE 789 entry-match-atom = 1*(list-wildcards / atom-slash) 790 *(list-wildcards / atom-slash) 792 attrib = DQUOTE 1*atom-dot *("/" 1*atom-dot) DQUOTE 793 attrib-match = DQUOTE 1*attrib-match-atom 794 *("/" 1*attrib-match-atom) DQUOTE 795 attrib-match-atom = 1*(list-wildcards / atom-dot) 796 *(list-wildcards / atom-dot) 798 value = nstring 800 select =/ *(SP "(" select-param *(SP select-param) ")" 801 ; modifies the original IMAP4 select command to 802 ; accept optional parameters 804 examine =/ *(SP "(" select-param *(SP select-param) ")" 805 ; modifies the original IMAP4 examine command to 806 ; accept optional parameters 808 select-param = astring / "(" astring SP astring *(SP astring) ")" 809 ; parameters to SELECT may contain one or 810 ; more atoms or strings - multiple items 811 ; are always parenthesised 813 annotate-param = "ANNOTATE" 814 ; defines the select parameter used with 815 ; ANNOTATE extension 817 10 IANA Considerations 819 Both entry names and attribute names MUST be specified in a 820 standards track or IESG approved experimental RFC, or fall under the 821 vendor namespace. Vendor names MUST be registered. 823 10.1 Entry and Attribute Registration Template 825 To: iana@iana.org 826 Subject: IMAP Annotate Registration 828 Please register the following IMAP Annotate item: 830 [] Entry [] Attribute 831 [] Vendor [] Open: RFC _______ 833 Name: ______________________________ 835 Description: _______________________ 837 ____________________________________ 839 ____________________________________ 841 Contact person: ____________________ 843 email: ____________________ 844 11 Security Considerations 846 Care must be taken to ensure that annotations whose values are 847 intended to remain private are not stored in mailboxes which are 848 accessible to other users. This includes mailboxes owned by the 849 user by whose ACLs permit access by others as well as any shared 850 mailboxes. 852 12 References 854 [ABNF] Crocker, Overell, "Augmented BNF for Syntax Specifications: 855 ABNF", RFC 2234, Internet Mail Consortium, Demon Internet Ltd, 856 November 1997. 858 [ACAP] Newman, Myers, "ACAP -- Application Configuration Access 859 Protocol", RFC 2244, Innosoft, Netscape, November 1997. 861 [ACL-EXT] Myers, "IMAP4 ACL extension", RFC 2086, Carnegie Mellon, 862 January 1997. 864 [IMAP4] Crispin, "Internet Message Access Protocol - Version 4rev1", 865 RFC 2060, University of Washington, December 1996. 867 [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate 868 Requirement Levels", RFC 2119, Harvard University, March 1997. 870 [SMTP-DSN] Moore, "SMTP Service Extension for Delivery Status 871 Notifications", RFC 1891, University of Tennessee, January 1996. 873 [SORT-EXT] Crispin, "Internet Message Access Protocol -- SORT 874 Extension", work in progress. 875 877 13 Acknowledgments 879 Many thanks to Chris Newman for his detailed comments on the first 880 draft of this document, and to the participants at the ACAP working 881 dinner in Pittsburgh. 883 14 Authors' Addresses 885 Randall Gellens 886 QUALCOMM Incorporated 887 5775 Morehouse Dr. 888 San Diego, CA 92121-2779 889 U.S.A. 891 Email: randy@qualcomm.com 892 Cyrus Daboo 893 Cyrusoft International, Inc. 894 Suite 780, 5001 Baum Blvd. 895 Pittsburgh, PA 15213 896 U.S.A. 898 Email: daboo@cyrusoft.com 900 15 Full Copyright Statement 902 Copyright (C) The Internet Society 2002. All Rights Reserved. 904 This document and translations of it may be copied and furnished to 905 others, and derivative works that comment on or otherwise explain it 906 or assist in its implementation may be prepared, copied, published 907 and distributed, in whole or in part, without restriction of any 908 kind, provided that the above copyright notice and this paragraph 909 are included on all such copies and derivative works. However, this 910 document itself may not be modified in any way, such as by removing 911 the copyright notice or references to the Internet Society or other 912 Internet organizations, except as needed for the purpose of 913 developing Internet standards in which case the procedures for 914 copyrights defined in the Internet Standards process must be 915 followed, or as required to translate it into languages other than 916 English. 918 The limited permissions granted above are perpetual and will not be 919 revoked by the Internet Society or its successors or assigns. 921 This document and the information contained herein is provided on an 922 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 923 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 924 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 925 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 926 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.