idnits 2.17.1 draft-daboo-imap-annotatemore-05.txt: 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: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 23 instances of too long lines in the document, the longest one being 10 characters in excess of 72. 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 (April 19, 2004) is 7305 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 525, but not defined == Unused Reference: 'RFC2119' is defined on line 763, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 3501 (Obsoleted by RFC 9051) == Outdated reference: A later version (-20) exists of draft-ietf-imapext-sort-15 == Outdated reference: A later version (-16) exists of draft-ietf-imapext-annotate-09 Summary: 4 errors (**), 0 flaws (~~), 7 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Daboo 3 Internet-Draft Cyrusoft International, Inc. 4 Expires: October 18, 2004 April 19, 2004 6 IMAP ANNOTATEMORE Extension 7 draft-daboo-imap-annotatemore-05 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that other 16 groups may also distribute working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six months 19 and may be updated, replaced, or obsoleted by other documents at any 20 time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as "work in progress." 23 The list of current Internet-Drafts can be accessed at http:// 24 www.ietf.org/ietf/1id-abstracts.txt. 26 The list of Internet-Draft Shadow Directories can be accessed at 27 http://www.ietf.org/shadow.html. 29 This Internet-Draft will expire on October 18, 2004. 31 Copyright Notice 33 Copyright (C) The Internet Society (2004). All Rights Reserved. 35 Abstract 37 The ANNOTATEMORE extension to the Internet Message Access Protocol 38 permits clients and servers to maintain "metadata" on IMAP4 servers. 39 It is possible to store data on a per-mailbox basis or on the server 40 as a whole. 42 Change History (to be removed prior to publication as an RFC) 44 Changes from -04 to -05: 45 1. Fix for valid IMAP state of commands. 46 2. Fix formatting, ID nits etc. 48 Changes from -03 to -04: 50 1. Allow retrieval of shared annotations for READ-ONLY mailbox. 51 2. Clarification of annotation loss on implicit removal of \Noselect 52 mailboxes. 53 3. Now requires roll-back of all changes to matching mailboxes if 54 there is a partial failure in SETANNOTATION. 56 Changes from -02 to -03: 57 1. Reworked entry naming scheme to split out mailbox name and use 58 empty string for server items. 60 Changes from -01 to -02: 61 1. SETANNOTATION lists use (..). 62 2. Explicitly state behaviour of unsolicited responses. 63 3. Adding SHOULD behaviour for rename/delete of mailboxes. 64 4. Added statement about supporting annotations on \Noselect 65 mailboxes. 66 5. Cleaned up formal syntax to use IMAP string type for entry and 67 attributes, with requirements on how the string is formatted. 68 6. Use of ACAP vendor subtree registry for vendor tokens. 70 Changes from -00 to -01: 71 1. Multiple entry-att responses are now simply delimited by spaces 72 in line with ANNOTATE spec. Adjusted examples to match. 73 2. Fixed entry-list formal syntax item to account for unsolicited 74 parenthesised list of entries. 75 3. Removed setentries formal syntax item for simplicity since its 76 only used once. 77 4. Removed reference to 'message annotation' in section 5.1. 78 5. Changed formal syntax to restrict top level entries to /server 79 and /mailbox/{...} only. Re-arranged entry names section to 80 account for this change. 81 6. Added comment and example for ANNOTATION response to allow 82 servers to return separate responses for each entry if desired. 84 Table of Contents 86 1. Introduction and Overview . . . . . . . . . . . . . . . . . 4 87 2. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 4 88 2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 89 2.2 Namespace of entries and attributes . . . . . . . . . . . . 5 90 2.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . . . . . 5 91 2.2.2 Attribute Names . . . . . . . . . . . . . . . . . . . . . . 6 92 2.3 Private versus Shared and Access Control . . . . . . . . . . 7 93 3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . 8 94 3.1 General Considerations . . . . . . . . . . . . . . . . . . . 8 95 3.2 GETANNOTATION Command . . . . . . . . . . . . . . . . . . . 8 96 3.3 SETANNOTATION Command . . . . . . . . . . . . . . . . . . . 10 97 3.4 ANNOTATION Response . . . . . . . . . . . . . . . . . . . . 12 98 3.4.1 ANNOTATION response with attributes and values . . . . . . . 13 99 3.4.2 Unsolicited ANNOTATION response without attributes and 100 values . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 101 4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . 15 102 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . 16 103 5.1 Entry and Attribute Registration Template . . . . . . . . . 17 104 6. Security Considerations . . . . . . . . . . . . . . . . . . 17 105 Normative References . . . . . . . . . . . . . . . . . . . . 17 106 Informative References . . . . . . . . . . . . . . . . . . . 18 107 Author's Address . . . . . . . . . . . . . . . . . . . . . . 18 108 A. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 18 109 Intellectual Property and Copyright Statements . . . . . . . 19 111 1. Introduction and Overview 113 The ANNOTATEMORE extension is present in any IMAP4 [RFC3501] 114 implementation which returns "ANNOTATEMORE" as one of the supported 115 capabilities in the CAPABILITY command response. 117 The goal of ANNOTATEMORE is to provide a means for clients to store 118 and retrieve "metadata" on an IMAP4 server. The metadata can be 119 associated with specific mailboxes or the server as a whole. 121 The ANNOTATEMORE extension adds two new commands and one new untagged 122 response to the IMAP4 base protocol. 124 This extension makes the following changes to the IMAP4 protocol: 126 adds a new SETANNOTATION command 127 adds a new GETANNOTATION command 128 adds a new ANNOTATION untagged response 129 adds a new ANNOTATEMORE response code 131 The data model used in ANNOTATEMORE is exactly the same as that used 132 in the ANNOTATE [ANNOTATE] extension to IMAP4. This is modeled after 133 that of the Application Configuration Access Protocol [RFC2244] with 134 the exception of inheritance which is not deemed necessary here. 136 The rest of this document describes the data model and protocol 137 changes more rigorously. 139 2. Data Model 141 2.1 Overview 143 The data model used in ANNOTATEMORE is one of a uniquely named entry 144 with a set of uniquely named attributes, each of which has a value. 145 Annotations can be added to mailboxes when a mailbox name is provided 146 as the first argument to the new commands, or to the server as a 147 whole when the empty string is provided as the first argument to the 148 new commands. 150 An annotation can contain multiple named entries. For example, a 151 general comment being added to a mailbox may have an entry name of "/ 152 comment". This entry could include named attributes such as "value", 153 "modifiedsince", "acl" etc to represent properties and data 154 associated with the entry. 156 The protocol changes to IMAP described below allow a client to access 157 or change the values of any attributes in any entries in an 158 annotation, assuming it has sufficient access rights to do so. 160 2.2 Namespace of entries and attributes 162 Each annotation is made up of a set of entries. Each entry has a 163 hierarchical name in UTF-8, with each component of the name separated 164 by a slash ("/"). 166 Each entry is made up of a set of attributes. Each attribute has a 167 hierarchical name in UTF-8, with each component of the name separated 168 by a period ("."). 170 The value of an attribute is NIL (has no value), or a string of zero 171 or more octets. 173 Entry and attribute names are not permitted to contain asterisk ("*") 174 or percent ("%") characters and MUST be valid UTF-8 strings which do 175 not contain NUL. Invalid entry or attribute names result in a BAD 176 response in any IMAP commands where they are used. 178 Use of non-visible UTF-8 characters in entry and attribute names is 179 discouraged. 181 This specification defines an initial set of entry and attribute 182 names available for use with mailbox and server annotations. In 183 addition an extension mechanism is described to allow additional 184 names to be added for extensibility. 186 2.2.1 Entry Names 188 Entry names MUST be specified in a standards track or IESG approved 189 experimental RFC, or fall under the vendor namespace. See Section 5.1 190 for the registration template. This specification only allows two 191 top-level entry types for servers and mailboxes. 193 2.2.1.1 Server Entries 195 These entries are used when the mailbox name argument to the new 196 commands is the empty string. 198 /comment 199 Defines a comment or note associated with the server. 201 /motd 202 Defines a "message of the day" for the server. This entry is 203 always read-only - clients cannot change it. 205 /admin 206 Indicates a method for contacting the server administrator. This 207 may be a URI (e.g. a mailto URL) or other contact information, 208 such as a telephone number. This entry is always read-only - 209 clients cannot change it. 211 /vendor/ 212 Defines the top-level of entries associated with the server as 213 created by a particular product of some vendor. This entry can be 214 used by vendors to provide server or client specific attributes. 215 The vendor-token MUST be registered with IANA, using the ACAP 216 [RFC2244] vendor subtree registry. 218 2.2.1.2 Mailbox Entries 220 These entries are used when the mailbox name argument to the new 221 commands is not the empty string. 223 /comment 224 Defines a comment or note associated with a mailbox. 226 /sort 227 Defines the default sort criteria [SORT] to use when first 228 displaying the mailbox contents to the user, or NIL if sorting is 229 not required. 231 /thread 232 Defines the default thread criteria [SORT] to use when first 233 displaying the mailbox contents to the user, or NIL if threading 234 is not required. If both sort and thread are not NIL, then 235 threading should take precedence over sorting. 237 /check 238 Boolean value "true" or "false" that indicates whether this 239 mailbox should be checked at regular intervals by the client. The 240 interval in minutes is specified by the /checkperiod entry. 242 /checkperiod 243 Numeric value indicating a period of minutes to use for checking a 244 mailbox that has the /check entry set to "true". 246 /vendor/ 247 Defines the top-level of entries associated with a specific 248 mailbox as created by a particular product of some vendor. This 249 entry can be used by vendors to provide client specific 250 attributes. The vendor-token MUST be registered with IANA, using 251 the ACAP [RFC2244] vendor subtree registry. 253 2.2.2 Attribute Names 255 Attribute names MUST be specified in a standards track or IESG 256 approved experimental RFC, or fall under the vendor namespace. See 257 Section 5.1 for the registration template. 259 All attribute names implicitly have a ".priv" and a ".shared" suffix 260 which maps to private and shared versions of the entry. Searching or 261 fetching without using either suffix includes both. The client MUST 262 specify either a ".priv" or ".shared" suffix when storing an 263 annotation. 265 value 266 The data value of the attribute. 268 size 269 The size of the value, in octets. Set automatically by the server, 270 read-only to clients. 272 modifiedsince 273 An opaque value set by the server when this entry is modified. It 274 can be used by the client to request notification of which entries 275 have changed since a particular point in time and is useful for 276 disconnected/synchronisation operations. 278 content-type 279 A MIME [RFC2046] content type and subtype that describes the 280 nature of the content of the "value" attribute. 282 vendor. 283 Defines an attribute associated with a particular product of some 284 vendor. This attribute can be used by vendors to provide client 285 specific attributes. The vendor-token MUST be registered with 286 IANA, using the ACAP [RFC2244] vendor subtree registry. 288 2.3 Private versus Shared and Access Control 290 As discussed in the ANNOTATE [ANNOTATE] extension there is a need to 291 support both private and shared annotations. This document adopts the 292 scheme used in [ANNOTATE] that adds two standard suffixes for all 293 attributes: ".shared" and ".priv". A GETANNOTATION command which 294 specifies neither uses both. SETANNOTATION commands MUST explicitly 295 use .priv or .shared suffixes. 297 A user can only store and retrieve private annotations on a mailbox 298 which is returned to them via a LIST or LSUB command. A user can only 299 store and retrieve shared annotations on a mailbox that they can 300 SELECT and which opens READ-WRITE. A user can only retrieve shared 301 annotations on a mailbox that they can SELECT and which opens 302 READ-ONLY. If a client attempts to store a shared annotation on a 303 READ-ONLY mailbox, the server MUST respond with a NO response. 305 3. IMAP Protocol Changes 307 3.1 General Considerations 309 The new commands and response each have a mailbox name argument, 310 indicating that the annotations being referred to are attached to the 311 specified mailbox. An empty string can be used for the mailbox name 312 to signify server annotations. 314 Both "*" and "%" list wildcard characters MAY be used in the mailbox 315 name argument to commands to match all possible occurrences of a 316 mailbox name pattern. However, "*" or "%" by themselves MUST NOT 317 match the empty string (server) entries. Server entries can only be 318 accessed by explicitly using the empty string as the mailbox name. 320 Servers SHOULD ensure that mailbox annotations are automatically 321 moved when the mailbox they refer to is renamed, i.e. the annotations 322 follow the mailbox. Servers SHOULD delete annotations for a mailbox 323 when the mailbox is deleted, so that a mailbox created with the same 324 name as a previously existing mailbox does not inherit the old 325 mailbox annotations. Servers SHOULD allow annotations on all 'types' 326 of mailbox, including ones reporting \Noselect for their LIST 327 response. Servers can implicitly remove \Noselect mailboxes when all 328 child mailboxes are removed, and as such any annotations associated 329 with the \Noselect mailbox SHOULD be removed. 331 The server is allowed to impose limitations on the size of any one 332 annotation or the total number of annotations for a single mailbox or 333 for the server as a whole. However, the server MUST accept a minimum 334 annotation data size of at least 1024 bytes, and a minimum annotation 335 count per server or mailbox of at least 10. 337 3.2 GETANNOTATION Command 339 This extension adds the GETANNOTATION command. This allows clients to 340 retrieve annotations. 342 This command is only available in authenticated or selected state 343 [RFC3501]. 345 Arguments: mailbox-name 346 entry-specifier 347 attribute-specifier 349 Responses: required ANNOTATION response 351 Result: OK - command completed 352 NO - command failure: can't access annotations on that mailbox 353 BAD - command unknown or arguments invalid 355 The mailbox-name argument MUST be a valid mailbox name or the empty 356 string. In the later case, the annotations being referred to are the 357 ones for the server as a whole. 359 Example: 361 C: a GETANNOTATION "" "/comment" "value.priv" 362 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 363 S: a OK GETANNOTATION complete 365 In the above example, the contents of the "value" attribute for 366 the "/comment" server entry is requested by the client and 367 returned by the server. 369 "*" and "%" wildcard characters can be used in either specifier to 370 match one or more characters at that position, with the exception 371 that "%" does not match the hierarchy delimiter for the specifier it 372 appears in (i.e. "/" for an entry specifier or "." for an attribute 373 specifier). Thus an entry specifier of "/%" would match entries such 374 as "/comment" and "/version", but not "/comment/note". 376 Example: 378 C: a GETANNOTATION "" "/*" "value.priv" 379 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 380 "/version" ("value.priv" "1.1") 381 "/motd/today" ("value.priv" "Closed at 1 pm") 382 S: a OK GETANNOTATION complete 384 In the above example, the contents of the "value" attributes for 385 any server entries are requested by the client and returned by the 386 server. 388 Example: 390 C: a GETANNOTATION "" "/%" "value" 391 S: * ANNOTATION "/comment" ("value.priv" "My comment") 392 ("value.shared" "Your comment") 393 "/motd" ("value.priv" "Its sunny outside!" 394 ("value.shared" "Today is a Holiday") 395 S: a OK GETANNOTATION complete 397 In the above example, the contents of the "value" attributes for 398 server entries at the top level of the entry hierarchy only, are 399 requested by the client and returned by the server. Both the .priv 400 and .shared values are returned, as neither were explicitly 401 requested. 403 Entry and attribute specifiers can be lists of atomic specifiers, so 404 that multiple items of each type may be returned in a single 405 GETANNOTATION command. 407 Example: 409 C: a GETANNOTATION "" ("/comment" "/motd") "value.priv" 410 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 411 "/motd" ("value.priv" "Its sunny outside!") 412 S: a OK GETANNOTATION complete 414 In the above example, the contents of the "value" attributes for 415 the two server entries "/comment" and "/motd" are requested by the 416 client and returned by the server. 418 Example: 420 C: a GETANNOTATION "" "/comment" ("value.priv" "modifiedsince.priv") 421 S: * ANNOTATION "" "/comment" ("value.priv" "My comment" 422 "modifiedsince.priv" "19990203205432") 423 S: a OK GETANNOTATION complete 425 In the above example, the contents of the "value" and 426 "modifiedsince" attributes for the "/comment" server entry are 427 requested by the client and returned by the server. 429 3.3 SETANNOTATION Command 431 This extension adds the SETANNOTATION command. This allows clients to 432 set annotations. 434 This command is only available in authenticated or selected state 435 [RFC3501]. 437 Arguments: mailbox-name 438 entry 439 attribute-value 440 list of entry, attribute-values 442 Responses: no specific responses for this command 444 Result: OK - command completed 445 NO - command failure: can't set annotations, 446 or annotation too big or too many 447 BAD - command unknown or arguments invalid 449 Sets the specified list of entries by adding or replacing the 450 specified attributes with the values provided. Clients can use NIL 451 for values of attributes it wants to remove from entries. The server 452 MAY return an unsolicited ANNOTATION response containing the updated 453 annotation data. The server SHOULD send such responses for any 454 changes to the server annotations, and SHOULD send such responses for 455 mailbox annotations only for the currently selected mailbox. Clients 456 MUST NOT assume that an unsolicited ANNOTATION response will be sent, 457 and MUST assume that if the command succeeds then the annotation has 458 been changed. 460 If the server is unable to store an annotation because the size of 461 its value is too large, the server MUST return a tagged NO response 462 with a "[ANNOTATEMORE TOOBIG]" response code. 464 If the server is unable to store a new annotation because the maximum 465 number of allowed annotations has already been reached, the server 466 MUST return a tagged NO response with a "[ANNOTATEMORE TOOMANY]" 467 response code. 469 If the server is unable to store the annotations for one or more 470 mailboxes matching the mailbox-name pattern, then the SETANNOTATION 471 command MUST fail and there MUST NOT be any changes to any of the 472 matching mailboxes, even those for which annotations could have been 473 changed successfully. 475 Example: 477 C: a SETANNOTATION "INBOX" "/comment" ("value.priv" "My new comment") 478 S: a OK SETANNOTATION complete 480 In the above example, the entry "/comment" for the mailbox "INBOX" 481 is created (if not already present) and the private attribute 482 "value" with data set to "My new comment" is created if not 483 already present, or replaced if it previously exists. 485 Example: 487 C: a SETANNOTATION "INBOX" "/comment" ("value.priv" NIL) 488 S: a OK SETANNOTATION complete 490 In the above example, the private "value" attribute of the entry 491 "/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: 498 C: a SETANNOTATION "INBOX.%" "/comment" ("value.priv" "My new comment") 499 S: a OK SETANNOTATION complete 501 In the above example, the entry "/comment" for all mailboxes at 502 the top-level of the "INBOX" hierarchy are created (if not already 503 present) and the private and shared attributes "value" are created 504 respectively for each entry if not already present, or replaced if 505 they previously existed. 507 Multiple attributes can be set in a single SETANNOTATION command by 508 listing multiple attribute-value pairs in the entry list. 510 Example: 512 C: a SETANNOTATION "INBOX" "/comment" 513 ("value.priv" "My new comment" 514 "vendor.foobar.bloop.priv" "foo's bar") 515 S: a OK SETANNOTATION complete 517 In the above example, the entry "/comment" for the mailbox "INBOX" 518 is created (if not already present) and the private attributes 519 "value" and "vendor.foobar.bloop" are created if not already 520 present, or replaced if they previously existed. 522 Example: 524 C: a SETANNOTATION "INBOX" "/comment" ("value.priv" "My new comment") 525 S: a NO [ANNOTATEMORE TOOMANY] SETANNOTATION failed 527 In the above example, the server is unable to store the requested 528 (new) annotation as it has reached the limit on the number of 529 annotations it can support on the specified mailbox. 531 3.4 ANNOTATION Response 533 The ANNOTATION response displays results of a GETANNOTATION command, 534 or can be returned as a unsolicited response at anytime by the server 535 in response to a change in an annotation. 537 Servers SHOULD send unsolicited ANNOTATION responses if changed by a 538 third-party, allowing servers to keep clients updated with changes to 539 annotations by other clients. Unsolicited mailbox entries MUST only 540 be returned for the currently selected mailbox. In this case, only 541 the entries are returned in the ANNOTATION response, not the 542 attributes and values. If the client wants to update any cached 543 values it must explicitly retrieve those using a GETANNOTATION 544 command. 546 Separate ANNOTATION responses MUST be used when more than one mailbox 547 matches the mailbox name argument pattern to the command. 549 The ANNOTATION response can contain multiple entries in a single 550 response, but the server is free to return multiple responses for 551 each entry or group of entries if it desires. 553 This response is only available in authenticated state [RFC3501]. 555 3.4.1 ANNOTATION response with attributes and values 557 The response consists of a list of entries each of which has a list 558 of attribute-value pairs. 560 Example: 562 C: a GETANNOTATION "" "/comment" "value.priv" 563 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 564 S: a OK GETANNOTATION complete 566 In the above example, a single entry with a single attribute-value 567 pair is returned by the server. 569 Example: 571 C: a GETANNOTATION "" ("/comment" "/motd") "value.priv" 572 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 573 "/motd" ("value.priv" "Its sunny outside!") 574 S: a OK GETANNOTATION complete 576 In the above example, two entries each with a single 577 attribute-value pair is returned by the server. 579 Example: 581 C: a GETANNOTATION "" ("/comment" "/motd") "value.priv" 582 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 583 S: * ANNOTATION "" "/motd" ("value.priv" "Its sunny outside!") 584 S: a OK GETANNOTATION complete 586 In the above example, the server returns two separate responses 587 for each of the two entries requested. 589 Example: 591 C: a GETANNOTATION "" "/comment" ("value.priv" "modifiedsince.priv") 592 S: * ANNOTATION "" "/comment" ("value.priv" "My comment" 593 "modifiedsince.priv" "19990203205432") 595 S: a OK GETANNOTATION complete 597 In the above example, a single entry with two attribute-value 598 pairs is returned by the server. 600 Example: 602 C: a GETANNOTATION "INBOX.%" "/comment" "value.priv" 603 S: * ANNOTATION "INBOX.1" "/comment" ("value.priv" "My comment for 1") 604 S: * ANNOTATION "INBOX.2" "/comment" ("value.priv" "My comment for 2") 605 S: * ANNOTATION "INBOX.3" "/comment" ("value.priv" "My comment for 3") 606 S: a OK GETANNOTATION complete 608 In the above example, separate responses are returned for each 609 matching mailbox, each containing a single entry with a single 610 attribute-value pair. 612 3.4.2 Unsolicited ANNOTATION response without attributes and values 614 The response consists of a parenthesised list of entries, each of 615 which have changed on the server. 617 Example: 619 C: a NOOP 620 S: * ANNOTATION "" ("/comment") 621 S: a OK NOOP complete 623 In the above example, the server indicates that the "/comment" 624 server entry has been changed. 626 Example: 628 C: a NOOP 629 S: * ANNOTATION "" ("/comment" "/motd") 630 S: a OK NOOP complete 632 In the above example, the server indicates a change to two server 633 entries. 635 Example: 637 C: a NOOP 638 S: * ANNOTATION "" ("/motd") 639 S: * ANNOTATION "INBOX" ("/comment") 640 S: a OK NOOP complete 642 In the above example, the server indicates a change to a server 643 entry, and to the an entry for the currently selected mailbox. 645 4. Formal Syntax 647 The following syntax specification uses the Augmented Backus-Naur 648 Form (ABNF) notation as specified in [RFC2234]. 650 Non-terminals referenced but not defined below are as defined by 651 [RFC3501]. 653 Except as noted otherwise, all alphabetic characters are case- 654 insensitive. The use of upper or lower case characters to define 655 token strings is for editorial clarity only. Implementations MUST 656 accept these strings in a case-insensitive fashion. 658 annotate-data = "ANNOTATION" SP mailbox SP entry-list 659 ; empty string for mailbox implies 660 ; server annotation. 662 att-value = attrib SP value 664 attrib = string 665 ; dot-separated attribute name 666 ; MUST NOT contain "*" or "%" 667 attrib-match = string 668 ; dot-separated attribute name 669 ; MAY contain "*" or "%" for use as wildcards 671 attribs = attrib-match / "(" attrib-match *(SP attrib-match) ")" 672 ; attribute specifiers that can include wildcards 674 command-auth /= setannotation / getannotation 675 ; adds to original IMAP4 command 677 entries = entry-match / "(" entry-match *(SP entry-match) ")" 678 ; entry specifiers that can include wildcards 680 entry = string 681 ; slash-separated path to entry 682 ; MUST NOT contain "*" or "%" 684 entry-att = entry SP "(" att-value *(SP att-value) ")" 686 entry-list = entry-att *(SP entry-att) / 687 "(" entry *(SP entry) ")" 688 ; entry attribute-value pairs list for 689 ; GETANNOTATION response, or 690 ; parenthesised entry list for unsolicited 691 ; notification of annotation changes 693 entry-match = string 694 ; slash-separated path to entry 695 ; MAY contain "*" or "%" for use as wildcards 697 getannotation = "GETANNOTATION" SP list-mailbox SP entries SP attribs 698 ; empty string for list-mailbox implies 699 ; server annotation. 701 response-data /= "*" SP annotate-data CRLF 702 ; adds to original IMAP4 data responses 704 resp-text-code =/ "ANNOTATEMORE" SP "TOOBIG" / 705 "ANNOTATEMORE" SP "TOOMANY" 706 ; new response codes for SETANNOTATION failures 708 setannotation = "SETANNOTATION" SP list-mailbox SP setentryatt 709 ; empty string for list-mailbox implies 710 ; server annotation. 712 setentryatt = entry-att / "(" entry-att *(SP entry-att) ")" 714 value = nstring 716 5. IANA Considerations 718 Both entry names and attribute names MUST be specified in a standards 719 track or IESG approved experimental RFC, or fall under the vendor 720 namespace. 722 5.1 Entry and Attribute Registration Template 724 To: iana@iana.org 725 Subject: IMAP ANNOTATEMORE Registration 727 Please register the following IMAP ANNOTATEMORE item: 729 [] Entry [] Attribute 731 [] Mailbox [] Server 733 Name: ______________________________ 735 Description: _______________________ 737 ____________________________________ 739 ____________________________________ 741 Contact person: ____________________ 743 email: ____________________ 745 6. Security Considerations 747 The ANNOTATEMORE extension does not raise any security considerations 748 that are not present in the base [RFC3501] protocol, and these issues 749 are discussed in [RFC3501]. 751 Care must be taken to ensure that annotations whose values are 752 intended to remain private are not stored in mailboxes which are 753 accessible to other users. This includes mailboxes owned by the user 754 by whose ACLs permit access by others as well as any shared 755 mailboxes. 757 Normative References 759 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 760 Extensions (MIME) Part Two: Media Types", RFC 2046, 761 November 1996. 763 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 764 Requirement Levels", BCP 14, RFC 2119, March 1997. 766 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 767 Specifications: ABNF", RFC 2234, November 1997. 769 [RFC2244] Newman, C. and J. Myers, "ACAP -- Application 770 Configuration Access Protocol", RFC 2244, November 1997. 772 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 773 4rev1", RFC 3501, March 2003. 775 [SORT] Crispin, M. and K. Murchison, "Internet Message Access 776 Protocol - Sort and Thread Extension", 777 draft-ietf-imapext-sort-15.txt, April 2004. 779 Informative References 781 [ANNOTATE] 782 Daboo, C. and R. Gellens, "IMAP ANNOTATE Extension", 783 draft-ietf-imapext-annotate-09.txt, April 2004. 785 Author's Address 787 Cyrus Daboo 788 Cyrusoft International, Inc. 789 5001 Baum Blvd. 790 Suite 650 791 Pittsburgh, PA 15213 792 US 794 EMail: daboo@cyrusoft.com 796 Appendix A. Acknowledgments 798 The ideas expressed in this document are based on the message 799 annotation document that was co-authored by Randall Gellens. 801 Intellectual Property Statement 803 The IETF takes no position regarding the validity or scope of any 804 intellectual property or other rights that might be claimed to 805 pertain to the implementation or use of the technology described in 806 this document or the extent to which any license under such rights 807 might or might not be available; neither does it represent that it 808 has made any effort to identify any such rights. Information on the 809 IETF's procedures with respect to rights in standards-track and 810 standards-related documentation can be found in BCP-11. Copies of 811 claims of rights made available for publication and any assurances of 812 licenses to be made available, or the result of an attempt made to 813 obtain a general license or permission for the use of such 814 proprietary rights by implementors or users of this specification can 815 be obtained from the IETF Secretariat. 817 The IETF invites any interested party to bring to its attention any 818 copyrights, patents or patent applications, or other proprietary 819 rights which may cover technology that may be required to practice 820 this standard. Please address the information to the IETF Executive 821 Director. 823 Full Copyright Statement 825 Copyright (C) The Internet Society (2004). All Rights Reserved. 827 This document and translations of it may be copied and furnished to 828 others, and derivative works that comment on or otherwise explain it 829 or assist in its implementation may be prepared, copied, published 830 and distributed, in whole or in part, without restriction of any 831 kind, provided that the above copyright notice and this paragraph are 832 included on all such copies and derivative works. However, this 833 document itself may not be modified in any way, such as by removing 834 the copyright notice or references to the Internet Society or other 835 Internet organizations, except as needed for the purpose of 836 developing Internet standards in which case the procedures for 837 copyrights defined in the Internet Standards process must be 838 followed, or as required to translate it into languages other than 839 English. 841 The limited permissions granted above are perpetual and will not be 842 revoked by the Internet Society or its successors or assignees. 844 This document and the information contained herein is provided on an 845 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 846 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 847 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 848 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 849 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 851 Acknowledgment 853 Funding for the RFC Editor function is currently provided by the 854 Internet Society.