idnits 2.17.1 draft-daboo-imap-annotatemore-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1.a on line 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 1110. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1087. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1094. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1100. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard == It seems as if not all pages are separated by form feeds - found 0 form feeds but 25 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 21 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.) -- Couldn't find a document date in the document -- date freshness check skipped. -- 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 556, but not defined == Unused Reference: 'RFC2119' is defined on line 1037, 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-17 == Outdated reference: A later version (-16) exists of draft-ietf-imapext-annotate-11 Summary: 8 errors (**), 0 flaws (~~), 8 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Daboo 3 Internet-Draft ISAMET, Inc. 4 Expires: August 2, 2005 February 2005 6 IMAP ANNOTATEMORE Extension 7 draft-daboo-imap-annotatemore-07 9 Status of this Memo 11 This document is an Internet-Draft and is subject to all provisions 12 of section 3 of RFC 3667. By submitting this Internet-Draft, each 13 author represents that any applicable patent or other IPR claims of 14 which he or she is aware have been or will be disclosed, and any of 15 which he or she become aware will be disclosed, in accordance with 16 RFC 3668. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as 21 Internet-Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on August 2, 2005. 36 Copyright Notice 38 Copyright (C) The Internet Society (2005). 40 Abstract 42 The ANNOTATEMORE extension to the Internet Message Access Protocol 43 permits clients and servers to maintain "metadata" on IMAP servers. 44 It is possible to store data on a per-mailbox basis or on the server 45 as a whole. 47 Change History (to be removed prior to publication as an RFC) 49 Changes from -06 to -07: 51 1. Reworded /checkperiod item. 52 2. Clarified unsolicited response behaviour. 54 Changes from -05 to -06: 55 1. Removed 'modifiedsince' attribute as there is currently no use 56 for it. 57 2. Added content-language attribute. 58 3. Changed access to allow .priv and .shared on any mailbox returned 59 by LIST/LSUB. 60 4. Added IANA registrations for items defined in this document. 61 5. Added latest IPR statement. 62 6. Updated references. 64 Changes from -04 to -05: 65 1. Fix for valid IMAP state of commands. 66 2. Fix formatting, ID nits etc. 68 Changes from -03 to -04: 69 1. Allow retrieval of shared annotations for READ-ONLY mailbox. 70 2. Clarification of annotation loss on implicit removal of \Noselect 71 mailboxes. 72 3. Now requires roll-back of all changes to matching mailboxes if 73 there is a partial failure in SETANNOTATION. 75 Changes from -02 to -03: 76 1. Reworked entry naming scheme to split out mailbox name and use 77 empty string for server items. 79 Changes from -01 to -02: 80 1. SETANNOTATION lists use (..). 81 2. Explicitly state behaviour of unsolicited responses. 82 3. Adding SHOULD behaviour for rename/delete of mailboxes. 83 4. Added statement about supporting annotations on \Noselect 84 mailboxes. 85 5. Cleaned up formal syntax to use IMAP string type for entry and 86 attributes, with requirements on how the string is formatted. 87 6. Use of ACAP vendor subtree registry for vendor tokens. 89 Changes from -00 to -01: 90 1. Multiple entry-att responses are now simply delimited by spaces 91 in line with ANNOTATE spec. Adjusted examples to match. 92 2. Fixed entry-list formal syntax item to account for unsolicited 93 parenthesised list of entries. 94 3. Removed setentries formal syntax item for simplicity since its 95 only used once. 96 4. Removed reference to 'message annotation' in section 5.1. 97 5. Changed formal syntax to restrict top level entries to /server 98 and /mailbox/{...} only. Re-arranged entry names section to 99 account for this change. 100 6. Added comment and example for ANNOTATION response to allow 101 servers to return separate responses for each entry if desired. 103 Table of Contents 105 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4 106 2. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . 4 107 2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 108 2.2 Namespace of entries and attributes . . . . . . . . . . . 5 109 2.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . . 5 110 2.2.2 Attribute Names . . . . . . . . . . . . . . . . . . . 7 111 2.3 Private versus Shared and Access Control . . . . . . . . . 7 112 3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 8 113 3.1 General Considerations . . . . . . . . . . . . . . . . . . 8 114 3.2 GETANNOTATION Command . . . . . . . . . . . . . . . . . . 8 115 3.3 SETANNOTATION Command . . . . . . . . . . . . . . . . . . 10 116 3.4 ANNOTATION Response . . . . . . . . . . . . . . . . . . . 12 117 3.4.1 ANNOTATION response with attributes and values . . . . 13 118 3.4.2 Unsolicited ANNOTATION response without attributes 119 and values . . . . . . . . . . . . . . . . . . . . . . 14 120 4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 15 121 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 122 5.1 Entry and Attribute Registration Template . . . . . . . . 17 123 5.2 Server Entry Registrations . . . . . . . . . . . . . . . . 17 124 5.2.1 /comment . . . . . . . . . . . . . . . . . . . . . . . 17 125 5.2.2 /motd . . . . . . . . . . . . . . . . . . . . . . . . 18 126 5.2.3 /admin . . . . . . . . . . . . . . . . . . . . . . . . 18 127 5.3 Mailbox Entry Registrations . . . . . . . . . . . . . . . 18 128 5.3.1 /comment . . . . . . . . . . . . . . . . . . . . . . . 19 129 5.3.2 /sort . . . . . . . . . . . . . . . . . . . . . . . . 19 130 5.3.3 /thread . . . . . . . . . . . . . . . . . . . . . . . 20 131 5.3.4 /check . . . . . . . . . . . . . . . . . . . . . . . . 20 132 5.3.5 /checkperiod . . . . . . . . . . . . . . . . . . . . . 21 133 5.4 Attribute Registrations . . . . . . . . . . . . . . . . . 21 134 5.4.1 value . . . . . . . . . . . . . . . . . . . . . . . . 21 135 5.4.2 size . . . . . . . . . . . . . . . . . . . . . . . . . 22 136 5.4.3 content-type . . . . . . . . . . . . . . . . . . . . . 22 137 5.4.4 content-language . . . . . . . . . . . . . . . . . . . 23 138 6. Security Considerations . . . . . . . . . . . . . . . . . . . 23 139 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 140 7.1 Normative References . . . . . . . . . . . . . . . . . . . . 23 141 7.2 Informative References . . . . . . . . . . . . . . . . . . . 24 142 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 24 143 A. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 144 Intellectual Property and Copyright Statements . . . . . . . . 25 146 1. Introduction and Overview 148 The ANNOTATEMORE extension is present in any IMAP [RFC3501] 149 implementation which returns "ANNOTATEMORE" as one of the supported 150 capabilities in the CAPABILITY command response. 152 The goal of ANNOTATEMORE is to provide a means for clients to store 153 and retrieve "metadata" on an IMAP server. The metadata can be 154 associated with specific mailboxes or the server as a whole. 156 The ANNOTATEMORE extension adds two new commands and one new untagged 157 response to the IMAP base protocol. 159 This extension makes the following changes to the IMAP protocol: 161 adds a new SETANNOTATION command 162 adds a new GETANNOTATION command 163 adds a new ANNOTATION untagged response 164 adds a new ANNOTATEMORE response code 166 The data model used in ANNOTATEMORE is exactly the same as that used 167 in the ANNOTATE [ANNOTATE] extension to IMAP. This is modeled after 168 that of the Application Configuration Access Protocol [RFC2244] with 169 the exception of inheritance which is not deemed necessary here. 171 The rest of this document describes the data model and protocol 172 changes more rigorously. 174 2. Data Model 176 2.1 Overview 178 The data model used in ANNOTATEMORE is one of a uniquely named entry 179 with a set of uniquely named attributes, each of which has a value. 180 Annotations can be added to mailboxes when a mailbox name is provided 181 as the first argument to the new commands, or to the server as a 182 whole when the empty string is provided as the first argument to the 183 new commands. 185 An annotation can contain multiple named entries. For example, a 186 general comment being added to a mailbox may have an entry name of "/ 187 comment". This entry could include named attributes such as "value", 188 "size", "content-type" etc to represent properties and data 189 associated with the entry. 191 The protocol changes to IMAP described below allow a client to access 192 or change the values of any attributes in any entries in an 193 annotation, assuming it has sufficient access rights to do so. 195 2.2 Namespace of entries and attributes 197 Each annotation is made up of a set of entries. Each entry has a 198 hierarchical name in UTF-8, with each component of the name separated 199 by a slash ("/"). 201 Each entry is made up of a set of attributes. Each attribute has a 202 hierarchical name in UTF-8, with each component of the name separated 203 by a period ("."). 205 The value of an attribute is NIL (has no value), or a string of zero 206 or more octets. 208 Entry and attribute names are not permitted to contain asterisk ("*") 209 or percent ("%") characters and MUST be valid UTF-8 strings which do 210 not contain NUL. Invalid entry or attribute names result in a BAD 211 response in any IMAP commands where they are used. 213 Use of non-visible UTF-8 characters in entry and attribute names is 214 discouraged. 216 This specification defines an initial set of entry and attribute 217 names available for use with mailbox and server annotations. In 218 addition an extension mechanism is described to allow additional 219 names to be added for extensibility. 221 2.2.1 Entry Names 223 Entry names MUST be specified in a standards track or IESG approved 224 experimental RFC, or fall under the vendor namespace. See Section 225 5.1 for the registration template. This specification only allows 226 two top-level entry types for servers and mailboxes. 228 2.2.1.1 Server Entries 230 These entries are used when the mailbox name argument to the new 231 commands is the empty string. 233 /comment 234 Defines a comment or note associated with the server. 236 /motd 237 Defines a "message of the day" for the server. This entry is 238 always read-only - clients cannot change it. 240 /admin 241 Indicates a method for contacting the server administrator. This 242 may be a URI (e.g. a mailto URL) or other contact information, 243 such as a telephone number. This entry is always read-only - 244 clients cannot change it. 246 /vendor/ 247 Defines the top-level of entries associated with the server as 248 created by a particular product of some vendor. This entry can be 249 used by vendors to provide server or client specific attributes. 250 The vendor-token MUST be registered with IANA, using the ACAP 251 [RFC2244] vendor subtree registry. 253 2.2.1.2 Mailbox Entries 255 These entries are used when the mailbox name argument to the new 256 commands is not the empty string. 258 /comment 259 Defines a comment or note associated with a mailbox. 261 /sort 262 Defines the default sort criteria [SORT] to use when first 263 displaying the mailbox contents to the user, or NIL if sorting is 264 not required. 266 /thread 267 Defines the default thread criteria [SORT] to use when first 268 displaying the mailbox contents to the user, or NIL if threading 269 is not required. If both sort and thread are not NIL, then 270 threading should take precedence over sorting. 272 /check 273 Boolean value "true" or "false" that indicates whether this 274 mailbox should be checked at regular intervals by the client. The 275 interval in minutes is specified by the /checkperiod entry. 277 /checkperiod 278 Numeric value indicating a period of minutes that the client uses 279 to determine the interval of regular 'new mail' checks for the 280 corresponding mailbox. 282 /vendor/ 283 Defines the top-level of entries associated with a specific 284 mailbox as created by a particular product of some vendor. This 285 entry can be used by vendors to provide client specific 286 attributes. The vendor-token MUST be registered with IANA, using 287 the ACAP [RFC2244] vendor subtree registry. 289 2.2.2 Attribute Names 291 Attribute names MUST be specified in a standards track or IESG 292 approved experimental RFC, or fall under the vendor namespace. See 293 Section 5.1 for the registration template. 295 All attribute names implicitly have a ".priv" and a ".shared" suffix 296 which maps to private and shared versions of the entry. Searching or 297 fetching without using either suffix includes both. The client MUST 298 specify either a ".priv" or ".shared" suffix when storing an 299 annotation. 301 value 302 The data value of the attribute. 304 size 305 The size of the value, in octets. Set automatically by the 306 server, read-only to clients. 308 content-type 309 A MIME [RFC2046] content type and subtype that describes the 310 nature of the content of the "value" attribute. 312 content-language 313 Indicates the language used for the value. This follows the 314 format described in [RFC3282]. Clients SHOULD set this value when 315 storing an annotation that uses text that can be presented to the 316 user. It is not required for enumerated or numeric values such as 317 flags etc. 319 vendor. 320 Defines an attribute associated with a particular product of some 321 vendor. This attribute can be used by vendors to provide client 322 specific attributes. The vendor-token MUST be registered with 323 IANA, using the ACAP [RFC2244] vendor subtree registry. 325 2.3 Private versus Shared and Access Control 327 As discussed in the ANNOTATE [ANNOTATE] extension there is a need to 328 support both private and shared annotations. This document adopts 329 the scheme used in [ANNOTATE] that adds two standard suffixes for all 330 attributes: ".shared" and ".priv". A GETANNOTATION command which 331 specifies neither uses both. SETANNOTATION commands MUST explicitly 332 use .priv or .shared suffixes. 334 A user can only store and retrieve private or shared annotations on a 335 mailbox which is returned to them via a LIST or LSUB command. If the 336 client attempts to store or retrieve annotations on other mailboxes, 337 the MUST respond with a NO response 339 3. IMAP Protocol Changes 341 3.1 General Considerations 343 The new commands and response each have a mailbox name argument, 344 indicating that the annotations being referred to are attached to the 345 specified mailbox. An empty string can be used for the mailbox name 346 to signify server annotations. 348 Both "*" and "%" list wildcard characters MAY be used in the mailbox 349 name argument to commands to match all possible occurrences of a 350 mailbox name pattern. However, "*" or "%" by themselves MUST NOT 351 match the empty string (server) entries. Server entries can only be 352 accessed by explicitly using the empty string as the mailbox name. 354 Servers SHOULD ensure that mailbox annotations are automatically 355 moved when the mailbox they refer to is renamed, i.e. the 356 annotations follow the mailbox. Servers SHOULD delete annotations 357 for a mailbox when the mailbox is deleted, so that a mailbox created 358 with the same name as a previously existing mailbox does not inherit 359 the old mailbox annotations. Servers SHOULD allow annotations on all 360 'types' of mailbox, including ones reporting \Noselect for their LIST 361 response. Servers can implicitly remove \Noselect mailboxes when all 362 child mailboxes are removed, and as such any annotations associated 363 with the \Noselect mailbox SHOULD be removed. 365 The server is allowed to impose limitations on the size of any one 366 annotation or the total number of annotations for a single mailbox or 367 for the server as a whole. However, the server MUST accept a minimum 368 annotation data size of at least 1024 bytes, and a minimum annotation 369 count per server or mailbox of at least 10. 371 3.2 GETANNOTATION Command 373 This extension adds the GETANNOTATION command. This allows clients 374 to retrieve annotations. 376 This command is only available in authenticated or selected state 377 [RFC3501]. 379 Arguments: mailbox-name 380 entry-specifier 381 attribute-specifier 383 Responses: required ANNOTATION response 385 Result: OK - command completed 386 NO - command failure: can't access annotations on that mailbox 387 BAD - command unknown or arguments invalid 389 The mailbox-name argument MUST be a valid mailbox name or the empty 390 string. In the later case, the annotations being referred to are the 391 ones for the server as a whole. 393 Example: 395 C: a GETANNOTATION "" "/comment" "value.priv" 396 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 397 S: a OK GETANNOTATION complete 399 In the above example, the contents of the "value" attribute for 400 the "/comment" server entry is requested by the client and 401 returned by the server. 403 "*" and "%" wildcard characters can be used in either specifier to 404 match one or more characters at that position, with the exception 405 that "%" does not match the hierarchy delimiter for the specifier it 406 appears in (i.e. "/" for an entry specifier or "." for an attribute 407 specifier). Thus an entry specifier of "/%" would match entries such 408 as "/comment" and "/version", but not "/comment/note". 410 Example: 412 C: a GETANNOTATION "" "/*" "value.priv" 413 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 414 "/version" ("value.priv" "1.1") 415 "/motd/today" ("value.priv" "Closed at 1 pm") 416 S: a OK GETANNOTATION complete 418 In the above example, the contents of the "value" attributes for 419 any server entries are requested by the client and returned by the 420 server. 422 Example: 424 C: a GETANNOTATION "" "/%" "value" 425 S: * ANNOTATION "/comment" ("value.priv" "My comment") 426 ("value.shared" "Your comment") 427 "/motd" ("value.priv" "Its sunny outside!" 428 ("value.shared" "Today is a Holiday") 429 S: a OK GETANNOTATION complete 431 In the above example, the contents of the "value" attributes for 432 server entries at the top level of the entry hierarchy only, are 433 requested by the client and returned by the server. Both the 434 .priv and .shared values are returned, as neither were explicitly 435 requested. 437 Entry and attribute specifiers can be lists of atomic specifiers, so 438 that multiple items of each type may be returned in a single 439 GETANNOTATION command. 441 Example: 443 C: a GETANNOTATION "" ("/comment" "/motd") "value.priv" 444 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 445 "/motd" ("value.priv" "Its sunny outside!") 446 S: a OK GETANNOTATION complete 448 In the above example, the contents of the "value" attributes for 449 the two server entries "/comment" and "/motd" are requested by the 450 client and returned by the server. 452 Example: 454 C: a GETANNOTATION "" "/comment" ("value.priv" "content-type.priv") 455 S: * ANNOTATION "" "/comment" ("value.priv" "My comment" 456 "content-type.priv" "text/plain") 457 S: a OK GETANNOTATION complete 459 In the above example, the contents of the "value" and 460 "content-type" attributes for the "/comment" server entry are 461 requested by the client and returned by the server. 463 3.3 SETANNOTATION Command 465 This extension adds the SETANNOTATION command. This allows clients 466 to set annotations. 468 This command is only available in authenticated or selected state 469 [RFC3501]. 471 Arguments: mailbox-name 472 entry 473 attribute-value 474 list of entry, attribute-values 476 Responses: no specific responses for this command 478 Result: OK - command completed 479 NO - command failure: can't set annotations, 480 or annotation too big or too many 481 BAD - command unknown or arguments invalid 483 Sets the specified list of entries by adding or replacing the 484 specified attributes with the values provided. Clients can use NIL 485 for values of attributes it wants to remove from entries. The server 486 MAY return an ANNOTATION response containing the updated annotation 487 data. Clients MUST NOT assume that an ANNOTATION response will be 488 sent, and MUST assume that if the command succeeds then the 489 annotation has been changed. 491 If the server is unable to store an annotation because the size of 492 its value is too large, the server MUST return a tagged NO response 493 with a "[ANNOTATEMORE TOOBIG]" response code. 495 If the server is unable to store a new annotation because the maximum 496 number of allowed annotations has already been reached, the server 497 MUST return a tagged NO response with a "[ANNOTATEMORE TOOMANY]" 498 response code. 500 If the server is unable to store the annotations for one or more 501 mailboxes matching the mailbox-name pattern, then the SETANNOTATION 502 command MUST fail and there MUST NOT be any changes to any of the 503 matching mailboxes, even those for which annotations could have been 504 changed successfully. 506 Example: 508 C: a SETANNOTATION "INBOX" "/comment" ("value.priv" "My new comment") 509 S: a OK SETANNOTATION complete 511 In the above example, the entry "/comment" for the mailbox "INBOX" 512 is created (if not already present) and the private attribute 513 "value" with data set to "My new comment" is created if not 514 already present, or replaced if it previously exists. 516 Example: 518 C: a SETANNOTATION "INBOX" "/comment" ("value.priv" NIL) 519 S: a OK SETANNOTATION complete 521 In the above example, the private "value" attribute of the entry 522 "/comment" is removed from the mailbox "INBOX". 524 Multiple entries can be set in a single SETANNOTATION command by 525 listing entry-attribute-value pairs in the list. 527 Example: 529 C: a SETANNOTATION "INBOX.%" "/comment" ("value.priv" "My new comment") 530 S: a OK SETANNOTATION complete 532 In the above example, the entry "/comment" for all mailboxes at 533 the top-level of the "INBOX" hierarchy are created (if not already 534 present) and the private and shared attributes "value" are created 535 respectively for each entry if not already present, or replaced if 536 they previously existed. 538 Multiple attributes can be set in a single SETANNOTATION command by 539 listing multiple attribute-value pairs in the entry list. 541 Example: 543 C: a SETANNOTATION "INBOX" "/comment" 544 ("value.priv" "My new comment" 545 "vendor.foobar.bloop.priv" "foo's bar") 546 S: a OK SETANNOTATION complete 548 In the above example, the entry "/comment" for the mailbox "INBOX" 549 is created (if not already present) and the private attributes 550 "value" and "vendor.foobar.bloop" are created if not already 551 present, or replaced if they previously existed. 553 Example: 555 C: a SETANNOTATION "INBOX" "/comment" ("value.priv" "My new comment") 556 S: a NO [ANNOTATEMORE TOOMANY] SETANNOTATION failed 558 In the above example, the server is unable to store the requested 559 (new) annotation as it has reached the limit on the number of 560 annotations it can support on the specified mailbox. 562 3.4 ANNOTATION Response 564 The ANNOTATION response displays results of a GETANNOTATION command, 565 or can be returned as a unsolicited response at anytime by the server 566 in response to a change in an annotation. 568 Servers SHOULD send unsolicited ANNOTATION responses if mailbox or 569 server annotations are changed by a third-party, allowing servers to 570 keep clients updated with changes. Unsolicited mailbox annotations 571 MUST only be returned for the currently selected mailbox. 573 Unsolicited ANNOTATION responses MUST only contain entry names, not 574 the attributes and values. If the client wants to update any cached 575 values it must explicitly retrieve those using a GETANNOTATION 576 command. 578 Separate ANNOTATION responses MUST be used when more than one mailbox 579 matches the mailbox name argument pattern to the command. 581 The ANNOTATION response can contain multiple entries in a single 582 response, but the server is free to return multiple responses for 583 each entry or group of entries if it desires. 585 This response is only available in authenticated state [RFC3501]. 587 3.4.1 ANNOTATION response with attributes and values 589 The response consists of a list of entries each of which has a list 590 of attribute-value pairs. 592 Example: 594 C: a GETANNOTATION "" "/comment" "value.priv" 595 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 596 S: a OK GETANNOTATION complete 598 In the above example, a single entry with a single attribute-value 599 pair is returned by the server. 601 Example: 603 C: a GETANNOTATION "" ("/comment" "/motd") "value.priv" 604 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 605 "/motd" ("value.priv" "Its sunny outside!") 606 S: a OK GETANNOTATION complete 608 In the above example, two entries each with a single 609 attribute-value pair is returned by the server. 611 Example: 613 C: a GETANNOTATION "" ("/comment" "/motd") "value.priv" 614 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 615 S: * ANNOTATION "" "/motd" ("value.priv" "Its sunny outside!") 616 S: a OK GETANNOTATION complete 618 In the above example, the server returns two separate responses 619 for each of the two entries requested. 621 Example: 623 C: a GETANNOTATION "" "/comment" ("value.priv" "size.priv") 624 S: * ANNOTATION "" "/comment" ("value.priv" "My comment" 625 "size.priv" "10") 626 S: a OK GETANNOTATION complete 628 In the above example, a single entry with two attribute-value 629 pairs is returned by the server. 631 Example: 633 C: a GETANNOTATION "INBOX.%" "/comment" "value.priv" 634 S: * ANNOTATION "INBOX.1" "/comment" ("value.priv" "My comment for 1") 635 S: * ANNOTATION "INBOX.2" "/comment" ("value.priv" "My comment for 2") 636 S: * ANNOTATION "INBOX.3" "/comment" ("value.priv" "My comment for 3") 637 S: a OK GETANNOTATION complete 639 In the above example, separate responses are returned for each 640 matching mailbox, each containing a single entry with a single 641 attribute-value pair. 643 3.4.2 Unsolicited ANNOTATION response without attributes and values 645 The response consists of a parenthesised list of entries, each of 646 which have changed on the server. 648 Example: 650 C: a NOOP 651 S: * ANNOTATION "" ("/comment") 652 S: a OK NOOP complete 654 In the above example, the server indicates that the "/comment" 655 server entry has been changed. 657 Example: 659 C: a NOOP 660 S: * ANNOTATION "" ("/comment" "/motd") 661 S: a OK NOOP complete 663 In the above example, the server indicates a change to two server 664 entries. 666 Example: 668 C: a NOOP 669 S: * ANNOTATION "" ("/motd") 670 S: * ANNOTATION "INBOX" ("/comment") 671 S: a OK NOOP complete 673 In the above example, the server indicates a change to a server 674 entry, and to the an entry for the currently selected mailbox. 676 4. Formal Syntax 678 The following syntax specification uses the Augmented Backus-Naur 679 Form (ABNF) notation as specified in [RFC2234]. 681 Non-terminals referenced but not defined below are as defined by 682 [RFC3501]. 684 Except as noted otherwise, all alphabetic characters are case- 685 insensitive. The use of upper or lower case characters to define 686 token strings is for editorial clarity only. Implementations MUST 687 accept these strings in a case-insensitive fashion. 689 annotate-data = "ANNOTATION" SP mailbox SP entry-list 690 ; empty string for mailbox implies 691 ; server annotation. 693 att-value = attrib SP value 695 attrib = string 696 ; dot-separated attribute name 697 ; MUST NOT contain "*" or "%" 698 attrib-match = string 699 ; dot-separated attribute name 700 ; MAY contain "*" or "%" for use as wildcards 702 attribs = attrib-match / "(" attrib-match *(SP attrib-match) ")" 703 ; attribute specifiers that can include wildcards 705 command-auth /= setannotation / getannotation 706 ; adds to original IMAP command 708 entries = entry-match / "(" entry-match *(SP entry-match) ")" 709 ; entry specifiers that can include wildcards 711 entry = string 712 ; slash-separated path to entry 713 ; MUST NOT contain "*" or "%" 715 entry-att = entry SP "(" att-value *(SP att-value) ")" 717 entry-list = entry-att *(SP entry-att) / 718 "(" entry *(SP entry) ")" 719 ; entry attribute-value pairs list for 720 ; GETANNOTATION response, or 721 ; parenthesised entry list for unsolicited 722 ; notification of annotation changes 724 entry-match = string 725 ; slash-separated path to entry 726 ; MAY contain "*" or "%" for use as wildcards 728 getannotation = "GETANNOTATION" SP list-mailbox SP entries SP attribs 729 ; empty string for list-mailbox implies 730 ; server annotation. 732 response-data /= "*" SP annotate-data CRLF 733 ; adds to original IMAP data responses 735 resp-text-code =/ "ANNOTATEMORE" SP "TOOBIG" / 736 "ANNOTATEMORE" SP "TOOMANY" 737 ; new response codes for SETANNOTATION failures 739 setannotation = "SETANNOTATION" SP list-mailbox SP setentryatt 740 ; empty string for list-mailbox implies 741 ; server annotation. 743 setentryatt = entry-att / "(" entry-att *(SP entry-att) ")" 745 value = nstring 747 5. IANA Considerations 749 Both entry names and attribute names MUST be specified in a standards 750 track or IESG approved experimental RFC, or fall under the vendor 751 namespace. 753 5.1 Entry and Attribute Registration Template 755 To: iana@iana.org 756 Subject: IMAP ANNOTATEMORE Registration 758 Please register the following IMAP ANNOTATEMORE item: 760 [ ] Entry [ ] Attribute 762 [ ] Mailbox [ ] Server 764 Name: ______________________________ 766 Description: _______________________ 768 ____________________________________ 770 ____________________________________ 772 Contact person: ____________________ 774 email: ____________________ 776 5.2 Server Entry Registrations 778 The following templates specify the IANA registrations of annotation 779 entries specified in this document. 781 5.2.1 /comment 783 To: iana@iana.org 784 Subject: IMAP ANNOTATEMORE Registration 786 Please register the following IMAP ANNOTATEMORE item: 788 [x] Entry [ ] Attribute 790 [ ] Mailbox [x] Server 792 Name: /comment 794 Description: Defined in IMAP ANNOTATEMORE extension document. 796 Contact person: Cyrus Daboo 798 email: daboo@isamet.com 800 5.2.2 /motd 802 To: iana@iana.org 803 Subject: IMAP ANNOTATEMORE Registration 805 Please register the following IMAP ANNOTATEMORE item: 807 [x] Entry [ ] Attribute 809 [ ] Mailbox [x] Server 811 Name: /motd 813 Description: Defined in IMAP ANNOTATEMORE extension document. 815 Contact person: Cyrus Daboo 817 email: daboo@isamet.com 819 5.2.3 /admin 821 To: iana@iana.org 822 Subject: IMAP ANNOTATEMORE Registration 824 Please register the following IMAP ANNOTATEMORE item: 826 [x] Entry [ ] Attribute 828 [ ] Mailbox [x] Server 830 Name: /admin 832 Description: Defined in IMAP ANNOTATEMORE extension document. 834 Contact person: Cyrus Daboo 836 email: daboo@isamet.com 838 5.3 Mailbox Entry Registrations 840 The following templates specify the IANA registrations of annotation 841 entries specified in this document. 843 5.3.1 /comment 845 To: iana@iana.org 846 Subject: IMAP ANNOTATEMORE Registration 848 Please register the following IMAP ANNOTATEMORE item: 850 [x] Entry [ ] Attribute 852 [x] Mailbox [ ] Server 854 Name: /comment 856 Description: Defined in IMAP ANNOTATEMORE extension document. 858 Contact person: Cyrus Daboo 860 email: daboo@isamet.com 862 5.3.2 /sort 864 To: iana@iana.org 865 Subject: IMAP ANNOTATEMORE Registration 867 Please register the following IMAP ANNOTATEMORE item: 869 [x] Entry [ ] Attribute 871 [x] Mailbox [ ] Server 873 Name: /sort 875 Description: Defined in IMAP ANNOTATEMORE extension document. 877 Contact person: Cyrus Daboo 879 email: daboo@isamet.com 881 5.3.3 /thread 883 To: iana@iana.org 884 Subject: IMAP ANNOTATEMORE Registration 886 Please register the following IMAP ANNOTATEMORE item: 888 [x] Entry [ ] Attribute 890 [x] Mailbox [ ] Server 892 Name: /thread 894 Description: Defined in IMAP ANNOTATEMORE extension document. 896 Contact person: Cyrus Daboo 898 email: daboo@isamet.com 900 5.3.4 /check 902 To: iana@iana.org 903 Subject: IMAP ANNOTATEMORE Registration 905 Please register the following IMAP ANNOTATEMORE item: 907 [x] Entry [ ] Attribute 909 [x] Mailbox [ ] Server 911 Name: /check 913 Description: Defined in IMAP ANNOTATEMORE extension document. 915 Contact person: Cyrus Daboo 917 email: daboo@isamet.com 919 5.3.5 /checkperiod 921 To: iana@iana.org 922 Subject: IMAP ANNOTATEMORE Registration 924 Please register the following IMAP ANNOTATEMORE item: 926 [x] Entry [ ] Attribute 928 [x] Mailbox [ ] Server 930 Name: /checkperiod 932 Description: Defined in IMAP ANNOTATEMORE extension document. 934 Contact person: Cyrus Daboo 936 email: daboo@isamet.com 938 5.4 Attribute Registrations 940 The following templates specify the IANA registrations of annotation 941 attributes specified in this document. 943 5.4.1 value 945 To: iana@iana.org 946 Subject: IMAP ANNOTATEMORE Registration 948 Please register the following IMAP ANNOTATEMORE item: 950 [ ] Entry [x] Attribute 952 [ ] Mailbox [ ] Server 954 Name: value 956 Description: Defined in IMAP ANNOTATEMORE extension document. 958 Contact person: Cyrus Daboo 960 email: daboo@isamet.com 962 5.4.2 size 964 To: iana@iana.org 965 Subject: IMAP ANNOTATEMORE Registration 967 Please register the following IMAP ANNOTATEMORE item: 969 [ ] Entry [x] Attribute 971 [ ] Mailbox [ ] Server 973 Name: size 975 Description: Defined in IMAP ANNOTATEMORE extension document. 977 Contact person: Cyrus Daboo 979 email: daboo@isamet.com 981 5.4.3 content-type 983 To: iana@iana.org 984 Subject: IMAP ANNOTATEMORE Registration 986 Please register the following IMAP ANNOTATEMORE item: 988 [ ] Entry [x] Attribute 990 [ ] Mailbox [ ] Server 992 Name: content-type 994 Description: Defined in IMAP ANNOTATEMORE extension document. 996 Contact person: Cyrus Daboo 998 email: daboo@isamet.com 1000 5.4.4 content-language 1002 To: iana@iana.org 1003 Subject: IMAP ANNOTATEMORE Registration 1005 Please register the following IMAP ANNOTATEMORE item: 1007 [ ] Entry [x] Attribute 1009 [ ] Mailbox [ ] Server 1011 Name: content-language 1013 Description: Defined in IMAP ANNOTATEMORE extension document. 1015 Contact person: Cyrus Daboo 1017 email: daboo@isamet.com 1019 6. Security Considerations 1021 Annotations whose values are intended to remain private MUST be 1022 stored in .priv values, and not .shared values which may be 1023 accessible to other users. 1025 >Excluding the above issues the ANNOTATEMORE extension does not raise 1026 any security considerations that are not present in the base IMAP 1027 protocol, and these issues are discussed in [RFC3501]. 1029 7. References 1031 7.1 Normative References 1033 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1034 Extensions (MIME) Part Two: Media Types", RFC 2046, 1035 November 1996. 1037 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1038 Requirement Levels", BCP 14, RFC 2119, March 1997. 1040 [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1041 Specifications: ABNF", RFC 2234, November 1997. 1043 [RFC2244] Newman, C. and J. Myers, "ACAP -- Application 1044 Configuration Access Protocol", RFC 2244, November 1997. 1046 [RFC3282] Alvestrand, H., "Content Language Headers", RFC 3282, May 1047 2002. 1049 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 1050 4rev1", RFC 3501, March 2003. 1052 [SORT] Crispin, M. and K. Murchison, "Internet Message Access 1053 Protocol - Sort and Thread Extension", 1054 draft-ietf-imapext-sort-17.txt, May 2004. 1056 7.2 Informative References 1058 [ANNOTATE] 1059 Daboo, C. and R. Gellens, "IMAP ANNOTATE Extension", 1060 draft-ietf-imapext-annotate-11.txt, October 2004. 1062 Author's Address 1064 Cyrus Daboo 1065 ISAMET, Inc. 1066 5001 Baum Blvd. 1067 Suite 650 1068 Pittsburgh, PA 15213 1069 US 1071 EMail: daboo@isamet.com 1073 Appendix A. Acknowledgments 1075 The ideas expressed in this document are based on the message 1076 annotation document that was co-authored by Randall Gellens. 1078 Intellectual Property Statement 1080 The IETF takes no position regarding the validity or scope of any 1081 Intellectual Property Rights or other rights that might be claimed to 1082 pertain to the implementation or use of the technology described in 1083 this document or the extent to which any license under such rights 1084 might or might not be available; nor does it represent that it has 1085 made any independent effort to identify any such rights. Information 1086 on the procedures with respect to rights in RFC documents can be 1087 found in BCP 78 and BCP 79. 1089 Copies of IPR disclosures made to the IETF Secretariat and any 1090 assurances of licenses to be made available, or the result of an 1091 attempt made to obtain a general license or permission for the use of 1092 such proprietary rights by implementers or users of this 1093 specification can be obtained from the IETF on-line IPR repository at 1094 http://www.ietf.org/ipr. 1096 The IETF invites any interested party to bring to its attention any 1097 copyrights, patents or patent applications, or other proprietary 1098 rights that may cover technology that may be required to implement 1099 this standard. Please address the information to the IETF at 1100 ietf-ipr@ietf.org. 1102 Disclaimer of Validity 1104 This document and the information contained herein are provided on an 1105 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1106 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1107 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1108 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1109 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1110 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1112 Copyright Statement 1114 Copyright (C) The Internet Society (2005). This document is subject 1115 to the rights, licenses and restrictions contained in BCP 78, and 1116 except as set forth therein, the authors retain all their rights. 1118 Acknowledgment 1120 Funding for the RFC Editor function is currently provided by the 1121 Internet Society.