idnits 2.17.1 draft-daboo-imap-annotatemore-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. ** There are 19 instances of too long lines in the document, the longest one being 7 characters in excess of 72. ** There are 4 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 the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 (May 2003) is 7645 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: 'ANNOTATEMORE TOOMANY' is mentioned on line 522, but not defined == Unused Reference: 'IMAPURL' is defined on line 751, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2234 (ref. 'ABNF') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 3501 (ref. 'IMAP4') (Obsoleted by RFC 9051) ** Obsolete normative reference: RFC 2192 (ref. 'IMAPURL') (Obsoleted by RFC 5092) == Outdated reference: A later version (-20) exists of draft-ietf-imapext-sort-13 == Outdated reference: A later version (-16) exists of draft-ietf-imapext-annotate-07 Summary: 10 errors (**), 0 flaws (~~), 7 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group C. Daboo 2 Internet Draft: IMAP ANNOTATEMORE Extension 3 Document: draft-daboo-imap-annotatemore-03.txt May 2003 5 IMAP ANNOTATEMORE 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 Conventions Used in This Document . . . . . . . . . . . . . 2 35 3 Open Issues: . . . . . . . . . . . . . . . . . . . . . . . . 2 36 4 Change History . . . . . . . . . . . . . . . . . . . . . . . 3 37 5 Introduction and Overview . . . . . . . . . . . . . . . . . . 3 38 6 Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 4 39 6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 4 40 6.2 Namespace of entries and attributes . . . . . . . . . . 4 41 6.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . . 5 42 6.2.1.1 Server Entries . . . . . . . . . . . . . . . . . 5 43 6.2.1.2 Mailbox Entries . . . . . . . . . . . . . . . . . 5 44 6.2.2 Attribute Names . . . . . . . . . . . . . . . . . . 6 45 7 Private versus Shared and Access Control . . . . . . . . . . 7 46 8 IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . 7 47 8.1 General Considerations . . . . . . . . . . . . . . . . . 7 48 8.2 GETANNOTATION Command . . . . . . . . . . . . . . . . . 8 49 8.3 SETANNOTATION command . . . . . . . . . . . . . . . . . . 9 50 8.4 ANNOTATION Response . . . . . . . . . . . . . . . . . . 11 51 8.4.1 ANNOTATION response with attributes and values . . . 12 52 8.4.2 Unsolicited ANNOTATION response without attributes an 13 53 9 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 13 54 10 IANA Considerations . . . . . . . . . . . . . . . . . . . . 15 55 10.1 Entry and Attribute Registration Template . . . . . . . . 15 56 11 Security Considerations . . . . . . . . . . . . . . . . . . 15 57 12 Normative References . . . . . . . . . . . . . . . . . . . . 15 58 13 Informative References . . . . . . . . . . . . . . . . . . . 16 59 14 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 60 15 Author's Address . . . . . . . . . . . . . . . . . . . . . . 16 61 16 Full Copyright Statement . . . . . . . . . . . . . . . . . . 16 63 1 Abstract 65 The ANNOTATEMORE extension to the Internet Message Access Protocol 66 [IMAP4] permits clients and servers to maintain "metadata" on IMAP4 67 servers. It is possible to store data on a per-mailbox basis or on 68 the server as a whole. 70 2 Conventions Used in This Document 72 The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD 73 NOT", and "MAY" in this document are to be interpreted as described 74 in "Key words for use in RFCs to Indicate Requirement Levels" 75 [KEYWORDS]. 77 Formal syntax is defined using ABNF [ABNF] as modified by [IMAP4]. 79 In examples, "C:" and "S:" indicate lines sent by the client and 80 server respectively. 82 3 Open Issues: 84 1 Handling of failures in SETANNOTATION with multiple mailbox 85 entries specified, and at least one fails but others succeed. 87 2 Do we want explicit access control for the server hierarchy, 88 beyond simply defining certain attributes as read-only in the spec? 90 3 SETANNOTATION does not currently implement conditional store 91 behaviour. Do we want this? 93 4 Should LIST flags, mailbox referrals, STATUS info be attributes 94 of the mailbox annotations? 96 5 Do we want the ability to search for annotations in 97 hierarchies? 99 4 Change History 101 Changes from -02 to -03: 102 1. Reworked entry naming scheme to split out mailbox name and use 103 empty string for server items. 105 Changes from -01 to -02: 106 1. SETANNOTATION lists use (..). 107 2. Explicitly state behaviour of unsolicited responses. 108 3. Adding SHOULD behaviour for rename/delete of mailboxes. 109 4. Added statement about supporting annotations on \Noselect mailboxes. 110 5. Cleaned up formal syntax to use IMAP string type for entry 111 and attributes, with requirements on how the string is formatted. 112 6. Use of ACAP vendor subtree registry for vendor tokens. 114 Changes from -00 to -01: 115 1. Multiple entry-att responses are now simply delimited by 116 spaces in line with ANNOTATE spec. Adjusted examples to match. 117 2. Fixed entry-list formal syntax item to account for unsolicited 118 parenthesised list of entries. 119 3. Removed setentries formal syntax item for simplicity since 120 its only used once. 121 4. Removed reference to 'message annotation' in section 5.1. 122 5. Changed formal syntax to restrict top level entries to 123 /server and /mailbox/{...} only. Re-arranged entry names 124 section to account for this change. 125 6. Added comment and example for ANNOTATION response to allow 126 servers to return separate responses for each entry if desired. 128 5 Introduction and Overview 130 The ANNOTATEMORE extension is present in any IMAP4 implementation 131 which returns "ANNOTATEMORE" as one of the supported capabilities in 132 the CAPABILITY command response. 134 The goal of ANNOTATEMORE is to provide a means for clients to store 135 and retrieve "metadata" on an IMAP4 server. The metadata can be 136 associated with specific mailboxes or the server as a whole. 138 The ANNOTATEMORE extension adds two new commands and one new 139 untagged response to the IMAP4 base protocol. 141 This extension makes the following changes to the IMAP4 protocol: 143 a adds a new SETANNOTATION command 144 b adds a new GETANNOTATION command 145 c adds a new ANNOTATION untagged response 146 d adds a new ANNOTATIONMORE response code 148 The data model used in ANNOTATEMORE is exactly the same as that used 149 in the ANNOTATE [ANNOTATE] extension to IMAP4. This is modeled 150 after that of the Application Configuration Access Protocol [ACAP] 151 with the exception of inheritance which is not deemed necessary 152 here. 154 The rest of this document describes the data model and protocol 155 changes more rigorously. 157 6 Data Model 159 6.1 Overview 161 The data model used in ANNOTATEMORE is one of a uniquely named entry 162 with a set of uniquely named attributes, each of which has a value. 163 Annotations can be added to mailboxes when a mailbox name is 164 provided as the first argument to the new commands, or to the server 165 as a whole when the empty string is provided as the first argument 166 to the new commands. 168 An annotation can contain multiple named entries. For example, a 169 general comment being added to a mailbox may have an entry name of 170 "/comment". This entry could include named attributes such as 171 "value", "modifiedsince", "acl" etc to represent properties and data 172 associated with the entry. 174 The protocol changes to IMAP described below allow a client to 175 access or change the values of any attributes in any entries in an 176 annotation, assuming it has sufficient access rights to do so. 178 6.2 Namespace of entries and attributes 180 Each annotation is made up of a set of entries. Each entry has a 181 hierarchical name in UTF-8, with each component of the name 182 separated by a slash ("/"). 184 Each entry is made up of a set of attributes. Each attribute has a 185 hierarchical name in UTF-8, with each component of the name 186 separated by a period ("."). 188 The value of an attribute is NIL (has no value), or a string of zero 189 or more octets. 191 Entry and attribute names are not permitted to contain asterisk 192 ("*") or percent ("%") characters and MUST be valid UTF-8 strings 193 which do not contain NUL. Invalid entry or attribute names result 194 in a BAD response in any IMAP commands where they are used. 196 Use of non-visible UTF-8 characters in entry and attribute names is 197 discouraged. 199 This specification defines an initial set of entry and attribute 200 names available for use with mailbox and server annotations. In 201 addition an extension mechanism is described to allow additional 202 names to be added for extensibility. 204 6.2.1 Entry Names 206 Entry names MUST be specified in a standards track or IESG approved 207 experimental RFC, or fall under the vendor namespace. See Section 208 10.1 for the registration template. This specification only allows 209 two top-level entry types for servers and mailboxes. 211 6.2.1.1 Server Entries 213 These entries are used when the mailbox name argument to the new 214 commands is the empty string. 216 /comment 217 Defines a comment or note associated with the server. 219 /motd 220 Defines a "message of the day" for the server. This entry is 221 always read-only - clients cannot change it. 223 /admin 224 Indicates a method for contacting the server administrator. 225 This may be a URI (e.g. a mailto URL) or other contact 226 information, such as a telephone number. This entry is always 227 read-only - clients cannot change it. 229 /vendor/ 230 Defines the top-level of entries associated with the server as 231 created by a particular product of some vendor. This entry can 232 be used by vendors to provide server or client specific 233 attributes. The vendor-token MUST be registered with IANA, 234 using the [ACAP] vendor subtree registry. 236 6.2.1.2 Mailbox Entries 238 These entries are used when the mailbox name argument to the new 239 commands is not the empty string. 241 /comment 242 Defines a comment or note associated with a mailbox. 244 /sort 245 Defines the default sort criteria [SORT] to use when first 246 displaying the mailbox contents to the user, or NIL if sorting 247 is not required. 249 /thread 250 Defines the default thread criteria [SORT] to use when first 251 displaying the mailbox contents to the user, or NIL if threading 252 is not required. If both sort and thread are not NIL, then 253 threading should take precedence over sorting. 255 /check 256 Boolean value "true" or "false" that indicates whether this 257 mailbox should be checked at regular intervals by the client. 258 The interval in minutes is specified by the /checkperiod entry. 260 /checkperiod 261 Numeric value indicating a period of minutes to use for checking 262 a mailbox that has the /check entry set to "true". 264 /vendor/ 265 Defines the top-level of entries associated with a specific 266 mailbox as created by a particular product of some vendor. This 267 entry can be used by vendors to provide client specific 268 attributes. The vendor-token MUST be registered with IANA, 269 using the [ACAP] vendor subtree registry. 271 6.2.2 Attribute Names 273 Attribute names MUST be specified in a standards track or IESG 274 approved experimental RFC, or fall under the vendor namespace. See 275 Section 10.1 for the registration template. 277 All attribute names implicitly have a ".priv" and a ".shared" suffix 278 which maps to private and shared versions of the entry. Searching 279 or fetching without using either suffix includes both. The client 280 MUST specify either a ".priv" or ".shared" suffix when storing an 281 annotation. 283 value 284 The data value of the attribute. 286 size 287 The size of the value, in octets. Set automatically by the 288 server, read-only to clients. 290 modifiedsince 291 An opaque value set by the server when this entry is modified. 292 It can be used by the client to request notification of which 293 entries have changed since a particular point in time and is 294 useful for disconnected/synchronisation operations. 296 content-type 297 A MIME [MIME] content type and subtype that describes the nature 298 of the content of the "value" attribute. 300 vendor. 301 Defines an attribute associated with a particular product of 302 some vendor. This attribute can be used by vendors to provide 303 client specific attributes. The vendor-token MUST be registered 304 with IANA, using the [ACAP] vendor subtree registry. 306 7 Private versus Shared and Access Control 308 As discussed in the ANNOTATE extension [ANNOTATE] there is a need to 309 support both private and shared annotations. This document adopts 310 the scheme used in [ANNOTATE] that adds two standard suffixes for 311 all attributes: ".shared" and ".priv". A GETANNOTATION command 312 which specifies neither uses both. SETANNOTATION commands MUST 313 explicitly use .priv or .shared suffixes. 315 A user can only store and retrieve private annotations on a mailbox 316 which is returned to them via a LIST or LSUB command. A user can 317 only store and retrieve shared annotations on a mailbox that they 318 can SELECT and which opens READ-WRITE. If a client attempts to 319 store or retrieve a shared annotation on a READ-ONLY mailbox, the 320 server MUST respond with a NO response. 322 8 IMAP Protocol Changes 324 8.1 General Considerations 326 The new commands and response each have a mailbox name argument, 327 indicating that the annotations being referred to are attached to 328 the specified mailbox. An empty string can be used for the mailbox 329 name to signify server annotations. 331 Both "*" and "%" list wildcard characters MAY be used in the mailbox 332 name argument to commands to match all possible occurrences of a 333 mailbox name pattern. However, "*" or "%" by themselves MUST NOT 334 match the empty string (server) entries. Server entries can only be 335 accessed by explicitly using the empty string as the mailbox name. 337 Servers SHOULD ensure that mailbox annotations are automatically 338 moved when the mailbox they refer to is renamed, i.e. the 339 annotations follow the mailbox. Servers SHOULD delete annotations 340 for a mailbox when the mailbox is deleted, so that a mailbox created 341 with the same name as a previously existing mailbox does not inherit 342 the old mailbox annotations. Servers SHOULD allow annotations on 343 all 'types' of mailbox, including ones reporting \Noselect for their 344 LIST response. 346 The server is allowed to impose limitations on the size of any one 347 annotation or the total number of annotations for a single mailbox 348 or for the server as a whole. However, the server MUST accept a 349 minimum annotation data size of at least 1024 bytes, and a minimum 350 annotation count per server or mailbox of at least 10. 352 8.2 GETANNOTATION Command 354 This extension adds the GETANNOTATION command. This allows clients 355 to retrieve annotations. 357 This command is only available in authenticated state [IMAP4]. 359 Arguments: mailbox-name 360 entry-specifier 361 attribute-specifier 363 Responses: required ANNOTATION response 365 Result: OK - command completed 366 NO - command failure: can't access annotations on that mailbox 367 BAD - command unknown or arguments invalid 369 The mailbox-name argument MUST be a valid mailbox name or the empty 370 string. In the later case, the annotations being referred to are 371 the ones for the server as a whole. 373 Example: 375 C: a GETANNOTATION "" "/comment" "value.priv" 376 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 377 S: a OK GETANNOTATION complete 379 In the above example, the contents of the "value" attribute 380 for the "/comment" server entry is requested by the client 381 and returned by the server. 383 "*" and "%" wildcard characters can be used in either specifier to 384 match one or more characters at that position, with the exception 385 that "%" does not match the hierarchy delimiter for the specifier it 386 appears in (i.e. "/" for an entry specifier or "." for an attribute 387 specifier). Thus an entry specifier of "/%" would match entries 388 such as "/comment" and "/version", but not "/comment/note". 390 Examples: 392 C: a GETANNOTATION "" "/*" "value.priv" 393 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 394 "/version" ("value.priv" "1.1") 395 "/motd/today" ("value.priv" "Closed at 1 pm") 396 S: a OK GETANNOTATION complete 398 In the above example, the contents of the "value" attributes 399 for any server entries are requested by the client and 400 returned by the server. 402 C: a GETANNOTATION "" "/%" "value" 403 S: * ANNOTATION "/comment" ("value.priv" "My comment") 404 ("value.shared" "Your comment") 405 "/motd" ("value.priv" "Its sunny outside!" 406 ("value.shared" "Today is a Holiday") 407 S: a OK GETANNOTATION complete 409 In the above example, the contents of the "value" attributes 410 for server entries at the top level of the entry hierarchy 411 only, are requested by the client and returned by the 412 server. Both the .priv and .shared values are returned, as 413 neither were explicitly requested. 415 Entry and attribute specifiers can be lists of atomic specifiers, so 416 that multiple items of each type may be returned in a single 417 GETANNOTATION command. 419 Examples: 421 C: a GETANNOTATION "" ("/comment" "/motd") "value.priv" 422 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 423 "/motd" ("value.priv" "Its sunny outside!") 424 S: a OK GETANNOTATION complete 426 In the above example, the contents of the "value" attributes 427 for the two server entries "/comment" and "/motd" are 428 requested by the client and returned by the server. 430 C: a GETANNOTATION "" "/comment" ("value.priv" "modifiedsince.priv") 431 S: * ANNOTATION "" "/comment" ("value.priv" "My comment" 432 "modifiedsince.priv" "19990203205432") 433 S: a OK GETANNOTATION complete 435 In the above example, the contents of the "value" and 436 "modifiedsince" attributes for the "/comment" server entry 437 are requested by the client and returned by the server. 439 8.3 SETANNOTATION command 440 This extension adds the SETANNOTATION command. This allows clients 441 to set annotations. 443 This command is only available in authenticated state [IMAP4]. 445 Arguments: mailbox-name 446 entry 447 attribute-value 448 list of entry, attribute-values 450 Responses: no specific responses for this command 452 Result: OK - command completed 453 NO - command failure: can't set annotations, 454 or annotation too big or too many 455 BAD - command unknown or arguments invalid 457 Sets the specified list of entries by adding or replacing the 458 specified attributes with the values provided. Clients can use NIL 459 for values of attributes it wants to remove from entries. The 460 server MAY return an unsolicited ANNOTATION response containing the 461 updated annotation data. The server SHOULD send such responses for 462 any changes to the server annotations, and SHOULD send such 463 responses for mailbox annotations only for the currently selected 464 mailbox. Clients MUST NOT assume that an unsolicited ANNOTATION 465 response will be sent, and MUST assume that if the command succeeds 466 then the annotation has been changed. 468 If the server is unable to store an annotation because the size of 469 its value is too large, the server MUST return a tagged NO response 470 with a "[ANNOTATEMORE TOOBIG]" response code. 472 If the server is unable to store a new annotation because the 473 maximum number of allowed annotations has already been reached, the 474 server MUST return a tagged NO response with a "[ANNOTATEMORE 475 TOOMANY]" response code. 477 Examples: 479 C: a SETANNOTATION "INBOX" "/comment" ("value.priv" "My new comment") 480 S: a OK SETANNOTATION complete 482 In the above example, the entry "/comment" for the mailbox 483 "INBOX" is created (if not already present) and the private 484 attribute "value" with data set to "My new comment" is 485 created if not already present, or replaced if it previously 486 exists. 488 C: a SETANNOTATION "INBOX" "/comment" ("value.priv" NIL) 489 S: a OK SETANNOTATION complete 490 In the above example, the private "value" attribute of the 491 entry "/comment" is removed from the mailbox "INBOX". 493 Multiple entries can be set in a single SETANNOTATION command by 494 listing entry-attribute-value pairs in the list. 496 Example: 497 C: a SETANNOTATION "INBOX.%" "/comment" ("value.priv" "My new comment") 498 S: a OK SETANNOTATION complete 500 In the above example, the entry "/comment" for all mailboxes 501 at the top-level of the "INBOX" hierarchy are created (if 502 not already present) and the private and shared attributes 503 "value" are created respectively for each entry if not 504 already present, or replaced if they previously existed. 506 Multiple attributes can be set in a single SETANNOTATION command by 507 listing multiple attribute-value pairs in the entry list. 509 Example: 510 C: a SETANNOTATION "INBOX" "/comment" 511 ("value.priv" "My new comment" 512 "vendor.foobar.bloop.priv" "foo's bar") 513 S: a OK SETANNOTATION complete 515 In the above example, the entry "/comment" for the mailbox 516 "INBOX" is created (if not already present) and the private 517 attributes "value" and "vendor.foobar.bloop" are created if 518 not already present, or replaced if they previously existed. 520 Example: 521 C: a SETANNOTATION "INBOX" "/comment" ("value.priv" "My new comment") 522 S: a NO [ANNOTATEMORE TOOMANY] SETANNOTATION failed 524 In the above example, the server is unable to store the 525 requested (new) annotation as it has reached the limit on 526 the number of annotations it can support on the specified 527 mailbox. 529 8.4 ANNOTATION Response 531 The ANNOTATION response displays results of a GETANNOTATION command, 532 or can be returned as a unsolicited response at anytime by the 533 server in response to a change in an annotation. 535 Servers SHOULD send unsolicited ANNOTATION responses if changed by a 536 third-party, allowing servers to keep clients updated with changes 537 to annotations by other clients. Unsolicited mailbox entries MUST 538 only be returned for the currently selected mailbox. In this case, 539 only the entries are returned in the ANNOTATION response, not the 540 attributes and values. If the client wants to update any cached 541 values it must explicitly retrieve those using a GETANNOTATION 542 command. 544 Separate ANNOTATION responses MUST be used when more than one 545 mailbox matches the mailbox name argument pattern to the command. 547 The ANNOTATION response can contain multiple entries in a single 548 response, but the server is free to return multiple responses for 549 each entry or group of entries if it desires. 551 This response is only available in authenticated state [IMAP4]. 553 8.4.1 ANNOTATION response with attributes and values 554 The response consists of a list of entries each of which has a 555 list of attribute-value pairs. 557 Examples: 559 C: a GETANNOTATION "" "/comment" "value.priv" 560 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 561 S: a OK GETANNOTATION complete 563 In the above example, a single entry with a single 564 attribute-value pair is returned by the server. 566 C: a GETANNOTATION "" ("/comment" "/motd") "value.priv" 567 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 568 "/motd" ("value.priv" "Its sunny outside!") 569 S: a OK GETANNOTATION complete 571 In the above example, two entries each with a single 572 attribute-value pair is returned by the server. 574 C: a GETANNOTATION "" ("/comment" "/motd") "value.priv" 575 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 576 S: * ANNOTATION "" "/motd" ("value.priv" "Its sunny outside!") 577 S: a OK GETANNOTATION complete 579 In the above example, the server returns two separate 580 responses for each of the two entries requested. 582 C: a GETANNOTATION "" "/comment" ("value.priv" "modifiedsince.priv") 583 S: * ANNOTATION "" "/comment" ("value.priv" "My comment" 584 "modifiedsince.priv" "19990203205432") 585 S: a OK GETANNOTATION complete 587 In the above example, a single entry with two 588 attribute-value pairs is returned by the server. 590 C: a GETANNOTATION "INBOX.%" "/comment" "value.priv" 591 S: * ANNOTATION "INBOX.1" "/comment" ("value.priv" "My comment for 1") 592 S: * ANNOTATION "INBOX.2" "/comment" ("value.priv" "My comment for 2") 593 S: * ANNOTATION "INBOX.3" "/comment" ("value.priv" "My comment for 3") 594 S: a OK GETANNOTATION complete 596 In the above example, separate responses are returned for 597 each matching mailbox, each containing a single entry with a 598 single attribute-value pair. 600 8.4.2 Unsolicited ANNOTATION response without attributes and values 601 The response consists of a parenthesised list of entries, each 602 of which have changed on the server. 604 Examples: 606 C: a NOOP 607 S: * ANNOTATION "" ("/comment") 608 S: a OK NOOP complete 610 In the above example, the server indicates that the 611 "/comment" server entry has been changed. 613 C: a NOOP 614 S: * ANNOTATION "" ("/comment" "/motd") 615 S: a OK NOOP complete 617 In the above example, the server indicates a change to two 618 server entries. 620 C: a NOOP 621 S: * ANNOTATION "" ("/motd") 622 S: * ANNOTATION "INBOX" ("/comment") 623 S: a OK NOOP complete 625 In the above example, the server indicates a change to a 626 server entry, and to the an entry for the currently selected 627 mailbox. 629 9 Formal Syntax 631 The following syntax specification uses the Augmented Backus-Naur 632 Form (ABNF) notation as specified in [ABNF]. 634 Non-terminals referenced but not defined below are as defined by 635 [IMAP4]. 637 Except as noted otherwise, all alphabetic characters are case- 638 insensitive. The use of upper or lower case characters to define 639 token strings is for editorial clarity only. Implementations MUST 640 accept these strings in a case-insensitive fashion. 642 annotate-data = "ANNOTATION" SP mailbox SP entry-list 643 ; empty string for mailbox implies 644 ; server annotation. 646 att-value = attrib SP value 648 attrib = string 649 ; dot-separated attribute name 650 ; MUST NOT contain "*" or "%" 651 attrib-match = string 652 ; dot-separated attribute name 653 ; MAY contain "*" or "%" for use as wildcards 655 attribs = attrib-match / "(" attrib-match *(SP attrib-match) ")" 656 ; attribute specifiers that can include wildcards 658 command-auth /= setannotation / getannotation 659 ; adds to original IMAP4 command 661 entries = entry-match / "(" entry-match *(SP entry-match) ")" 662 ; entry specifiers that can include wildcards 664 entry = string 665 ; slash-separated path to entry 666 ; MUST NOT contain "*" or "%" 668 entry-att = entry SP "(" att-value *(SP att-value) ")" 670 entry-list = entry-att *(SP entry-att) / 671 "(" entry *(SP entry) ")" 672 ; entry attribute-value pairs list for 673 ; GETANNOTATION response, or 674 ; parenthesised entry list for unsolicited 675 ; notification of annotation changes 677 entry-match = string 678 ; slash-separated path to entry 679 ; MAY contain "*" or "%" for use as wildcards 681 getannotation = "GETANNOTATION" SP list-mailbox SP entries SP attribs 682 ; empty string for list-mailbox implies 683 ; server annotation. 685 response-data /= "*" SP annotate-data CRLF 686 ; adds to original IMAP4 data responses 688 resp-text-code =/ "ANNOTATEMORE" SP "TOOBIG" / 689 "ANNOTATEMORE" SP "TOOMANY" 690 ; new response codes for SETANNOTATION failures 692 setannotation = "SETANNOTATION" SP list-mailbox SP setentryatt 693 ; empty string for list-mailbox implies 694 ; server annotation. 696 setentryatt = entry-att / "(" entry-att *(SP entry-att) ")" 697 value = nstring 699 10 IANA Considerations 701 Both entry names and attribute names MUST be specified in a 702 standards track or IESG approved experimental RFC, or fall under the 703 vendor namespace. 705 10.1 Entry and Attribute Registration Template 707 To: iana@iana.org 708 Subject: IMAP ANNOTATEMORE Registration 710 Please register the following IMAP ANNOTATEMORE item: 712 [] Entry [] Attribute 714 [] Mailbox [] Server 716 Name: ______________________________ 718 Description: _______________________ 720 ____________________________________ 722 ____________________________________ 724 Contact person: ____________________ 726 email: ____________________ 728 11 Security Considerations 730 The ANNOTATEMORE extension does not raise any security 731 considerations that are not present in the base [IMAP4] protocol, 732 and these issues are discussed in [IMAP4]. 734 Care must be taken to ensure that annotations whose values are 735 intended to remain private are not stored in mailboxes which are 736 accessible to other users. This includes mailboxes owned by the 737 user by whose ACLs permit access by others as well as any shared 738 mailboxes. 740 12 Normative References 742 [ABNF] Crocker, Overell, "Augmented BNF for Syntax Specifications: 743 ABNF", RFC 2234, November 1997. 745 [ACAP] Newman, C., and Myers, J. "ACAP -- Application Configuration 746 Access Protocol", RFC 2244, November 1997. 748 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 749 4rev1", RFC 3501, March 2003. 751 [IMAPURL] Newman, C., "IMAP URL Scheme", RFC 2192, September 1997. 753 [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate 754 Requirement Levels", RFC 2119, March 1997. 756 [MIME] Freed, N., and Borenstein, N. "MIME (Multipurpose Internet 757 Mail Extensions) Part Two: Media Types", RFC 2046, November 1996. 759 [SORT] Crispin, M., Murchison, K., "Internet Message Access Protocol 760 - Sort and Thread Extension", draft-ietf-imapext-sort-13.txt, May 761 2003. 763 13 Informative References 765 [ANNOTATE] Daboo, C., Gellens, R., "IMAP ANNOTATE Extension", 766 draft-ietf-imapext-annotate-07.txt, May 2003. 768 14 Acknowledgments 770 The ideas expressed in this document are based on the message 771 annotation document that was co-authored by Randall Gellens. 773 15 Author's Address 775 Cyrus Daboo 776 Cyrusoft International, Inc. 777 Suite 780, 5001 Baum Blvd. 778 Pittsburgh, PA 15213 779 U.S.A. 781 Email: daboo@cyrusoft.com 783 16 Full Copyright Statement 785 Copyright (C) The Internet Society 2003. All Rights Reserved. 787 This document and translations of it may be copied and furnished to 788 others, and derivative works that comment on or otherwise explain it 789 or assist in its implementation may be prepared, copied, published 790 and distributed, in whole or in part, without restriction of any 791 kind, provided that the above copyright notice and this paragraph 792 are included on all such copies and derivative works. However, this 793 document itself may not be modified in any way, such as by removing 794 the copyright notice or references to the Internet Society or other 795 Internet organizations, except as needed for the purpose of 796 developing Internet standards in which case the procedures for 797 copyrights defined in the Internet Standards process must be 798 followed, or as required to translate it into languages other than 799 English. 801 The limited permissions granted above are perpetual and will not be 802 revoked by the Internet Society or its successors or assigns. 804 This document and the information contained herein is provided on an 805 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 806 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 807 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 808 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 809 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.