idnits 2.17.1 draft-daboo-imap-annotatemore-04.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 5 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 (October 2003) is 7499 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 521, but not defined == Unused Reference: 'IMAPURL' is defined on line 750, 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-04.txt October 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 Change History . . . . . . . . . . . . . . . . . . . . . . . 2 36 4 Introduction and Overview . . . . . . . . . . . . . . . . . 3 37 5 Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 4 38 5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 4 39 5.2 Namespace of entries and attributes . . . . . . . . . . . 4 40 5.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . 5 41 5.2.1.1 Server Entries . . . . . . . . . . . . . . . . . 5 42 5.2.1.2 Mailbox Entries . . . . . . . . . . . . . . . . 5 43 5.2.2 Attribute Names . . . . . . . . . . . . . . . . . . . 6 44 6 Private versus Shared and Access Control . . . . . . . . . . 7 45 7 IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 7 46 7.1 General Considerations . . . . . . . . . . . . . . . . . 7 47 7.2 GETANNOTATION Command . . . . . . . . . . . . . . . . . . 8 48 7.3 SETANNOTATION command . . . . . . . . . . . . . . . . . 9 49 7.4 ANNOTATION Response . . . . . . . . . . . . . . . . . . . 11 50 7.4.1 ANNOTATION response with attributes and values . . . 12 51 7.4.2 Unsolicited ANNOTATION response without attributes an 12 52 8 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . 13 53 9 IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 54 9.1 Entry and Attribute Registration Template . . . . . . . 15 55 10 Security Considerations . . . . . . . . . . . . . . . . . . . 15 56 11 Normative References . . . . . . . . . . . . . . . . . . . . 15 57 12 Informative References . . . . . . . . . . . . . . . . . . . 16 58 13 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 16 59 14 Author's Address . . . . . . . . . . . . . . . . . . . . . . 16 60 15 Full Copyright Statement . . . . . . . . . . . . . . . . . . 16 62 1 Abstract 64 The ANNOTATEMORE extension to the Internet Message Access Protocol 65 [IMAP4] permits clients and servers to maintain "metadata" on IMAP4 66 servers. It is possible to store data on a per-mailbox basis or on 67 the server as a whole. 69 2 Conventions Used in This Document 71 The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD 72 NOT", and "MAY" in this document are to be interpreted as described 73 in "Key words for use in RFCs to Indicate Requirement Levels" 74 [KEYWORDS]. 76 Formal syntax is defined using ABNF [ABNF] as modified by [IMAP4]. 78 In examples, "C:" and "S:" indicate lines sent by the client and 79 server respectively. 81 3 Change History 82 Changes from -03 to -04: 83 1. Allow retrieval of shared annotations for READ-ONLY mailbox. 84 2. Clarification of annotation loss on implicit removal of 85 \Noselect mailboxes. 86 3. Now requires roll-back of all changes to matching mailboxes 87 if there is a partial failure in SETANNOTATION. 89 Changes from -02 to -03: 90 1. Reworked entry naming scheme to split out mailbox name and use 91 empty string for server items. 93 Changes from -01 to -02: 94 1. SETANNOTATION lists use (..). 95 2. Explicitly state behaviour of unsolicited responses. 96 3. Adding SHOULD behaviour for rename/delete of mailboxes. 97 4. Added statement about supporting annotations on \Noselect mailboxes. 98 5. Cleaned up formal syntax to use IMAP string type for entry 99 and attributes, with requirements on how the string is formatted. 100 6. Use of ACAP vendor subtree registry for vendor tokens. 102 Changes from -00 to -01: 103 1. Multiple entry-att responses are now simply delimited by 104 spaces in line with ANNOTATE spec. Adjusted examples to match. 105 2. Fixed entry-list formal syntax item to account for unsolicited 106 parenthesised list of entries. 107 3. Removed setentries formal syntax item for simplicity since 108 its only used once. 109 4. Removed reference to 'message annotation' in section 5.1. 110 5. Changed formal syntax to restrict top level entries to 111 /server and /mailbox/{...} only. Re-arranged entry names 112 section to account for this change. 113 6. Added comment and example for ANNOTATION response to allow 114 servers to return separate responses for each entry if desired. 116 4 Introduction and Overview 118 The ANNOTATEMORE extension is present in any IMAP4 implementation 119 which returns "ANNOTATEMORE" as one of the supported capabilities in 120 the CAPABILITY command response. 122 The goal of ANNOTATEMORE is to provide a means for clients to store 123 and retrieve "metadata" on an IMAP4 server. The metadata can be 124 associated with specific mailboxes or the server as a whole. 126 The ANNOTATEMORE extension adds two new commands and one new 127 untagged response to the IMAP4 base protocol. 129 This extension makes the following changes to the IMAP4 protocol: 131 a adds a new SETANNOTATION command 132 b adds a new GETANNOTATION command 133 c adds a new ANNOTATION untagged response 134 d adds a new ANNOTATEMORE response code 136 The data model used in ANNOTATEMORE is exactly the same as that used 137 in the ANNOTATE [ANNOTATE] extension to IMAP4. This is modeled 138 after that of the Application Configuration Access Protocol [ACAP] 139 with the exception of inheritance which is not deemed necessary 140 here. 142 The rest of this document describes the data model and protocol 143 changes more rigorously. 145 5 Data Model 147 5.1 Overview 149 The data model used in ANNOTATEMORE is one of a uniquely named entry 150 with a set of uniquely named attributes, each of which has a value. 151 Annotations can be added to mailboxes when a mailbox name is 152 provided as the first argument to the new commands, or to the server 153 as a whole when the empty string is provided as the first argument 154 to the new commands. 156 An annotation can contain multiple named entries. For example, a 157 general comment being added to a mailbox may have an entry name of 158 "/comment". This entry could include named attributes such as 159 "value", "modifiedsince", "acl" etc to represent properties and data 160 associated with the entry. 162 The protocol changes to IMAP described below allow a client to 163 access or change the values of any attributes in any entries in an 164 annotation, assuming it has sufficient access rights to do so. 166 5.2 Namespace of entries and attributes 168 Each annotation is made up of a set of entries. Each entry has a 169 hierarchical name in UTF-8, with each component of the name 170 separated by a slash ("/"). 172 Each entry is made up of a set of attributes. Each attribute has a 173 hierarchical name in UTF-8, with each component of the name 174 separated by a period ("."). 176 The value of an attribute is NIL (has no value), or a string of zero 177 or more octets. 179 Entry and attribute names are not permitted to contain asterisk 180 ("*") or percent ("%") characters and MUST be valid UTF-8 strings 181 which do not contain NUL. Invalid entry or attribute names result 182 in a BAD response in any IMAP commands where they are used. 184 Use of non-visible UTF-8 characters in entry and attribute names is 185 discouraged. 187 This specification defines an initial set of entry and attribute 188 names available for use with mailbox and server annotations. In 189 addition an extension mechanism is described to allow additional 190 names to be added for extensibility. 192 5.2.1 Entry Names 194 Entry names MUST be specified in a standards track or IESG approved 195 experimental RFC, or fall under the vendor namespace. See Section 196 9.1 for the registration template. This specification only allows 197 two top-level entry types for servers and mailboxes. 199 5.2.1.1 Server Entries 201 These entries are used when the mailbox name argument to the new 202 commands is the empty string. 204 /comment 205 Defines a comment or note associated with the server. 207 /motd 208 Defines a "message of the day" for the server. This entry is 209 always read-only - clients cannot change it. 211 /admin 212 Indicates a method for contacting the server administrator. 213 This may be a URI (e.g. a mailto URL) or other contact 214 information, such as a telephone number. This entry is always 215 read-only - clients cannot change it. 217 /vendor/ 218 Defines the top-level of entries associated with the server as 219 created by a particular product of some vendor. This entry can 220 be used by vendors to provide server or client specific 221 attributes. The vendor-token MUST be registered with IANA, 222 using the [ACAP] vendor subtree registry. 224 5.2.1.2 Mailbox Entries 226 These entries are used when the mailbox name argument to the new 227 commands is not the empty string. 229 /comment 230 Defines a comment or note associated with a mailbox. 232 /sort 233 Defines the default sort criteria [SORT] to use when first 234 displaying the mailbox contents to the user, or NIL if sorting 235 is not required. 237 /thread 238 Defines the default thread criteria [SORT] to use when first 239 displaying the mailbox contents to the user, or NIL if threading 240 is not required. If both sort and thread are not NIL, then 241 threading should take precedence over sorting. 243 /check 244 Boolean value "true" or "false" that indicates whether this 245 mailbox should be checked at regular intervals by the client. 246 The interval in minutes is specified by the /checkperiod entry. 248 /checkperiod 249 Numeric value indicating a period of minutes to use for checking 250 a mailbox that has the /check entry set to "true". 252 /vendor/ 253 Defines the top-level of entries associated with a specific 254 mailbox as created by a particular product of some vendor. This 255 entry can be used by vendors to provide client specific 256 attributes. The vendor-token MUST be registered with IANA, 257 using the [ACAP] vendor subtree registry. 259 5.2.2 Attribute Names 261 Attribute names MUST be specified in a standards track or IESG 262 approved experimental RFC, or fall under the vendor namespace. See 263 Section 9.1 for the registration template. 265 All attribute names implicitly have a ".priv" and a ".shared" suffix 266 which maps to private and shared versions of the entry. Searching 267 or fetching without using either suffix includes both. The client 268 MUST specify either a ".priv" or ".shared" suffix when storing an 269 annotation. 271 value 272 The data value of the attribute. 274 size 275 The size of the value, in octets. Set automatically by the 276 server, read-only to clients. 278 modifiedsince 279 An opaque value set by the server when this entry is modified. 280 It can be used by the client to request notification of which 281 entries have changed since a particular point in time and is 282 useful for disconnected/synchronisation operations. 284 content-type 285 A MIME [MIME] content type and subtype that describes the nature 286 of the content of the "value" attribute. 288 vendor. 289 Defines an attribute associated with a particular product of 290 some vendor. This attribute can be used by vendors to provide 291 client specific attributes. The vendor-token MUST be registered 292 with IANA, using the [ACAP] vendor subtree registry. 294 6 Private versus Shared and Access Control 296 As discussed in the ANNOTATE extension [ANNOTATE] there is a need to 297 support both private and shared annotations. This document adopts 298 the scheme used in [ANNOTATE] that adds two standard suffixes for 299 all attributes: ".shared" and ".priv". A GETANNOTATION command 300 which specifies neither uses both. SETANNOTATION commands MUST 301 explicitly use .priv or .shared suffixes. 303 A user can only store and retrieve private annotations on a mailbox 304 which is returned to them via a LIST or LSUB command. A user can 305 only store and retrieve shared annotations on a mailbox that they 306 can SELECT and which opens READ-WRITE. A user can only retrieve 307 shared annotations on a mailbox that they can SELECT and which opens 308 READ-ONLY. If a client attempts to store a shared annotation on a 309 READ-ONLY mailbox, the server MUST respond with a NO response. 311 7 IMAP Protocol Changes 313 7.1 General Considerations 315 The new commands and response each have a mailbox name argument, 316 indicating that the annotations being referred to are attached to 317 the specified mailbox. An empty string can be used for the mailbox 318 name to signify server annotations. 320 Both "*" and "%" list wildcard characters MAY be used in the mailbox 321 name argument to commands to match all possible occurrences of a 322 mailbox name pattern. However, "*" or "%" by themselves MUST NOT 323 match the empty string (server) entries. Server entries can only be 324 accessed by explicitly using the empty string as the mailbox name. 326 Servers SHOULD ensure that mailbox annotations are automatically 327 moved when the mailbox they refer to is renamed, i.e. the 328 annotations follow the mailbox. Servers SHOULD delete annotations 329 for a mailbox when the mailbox is deleted, so that a mailbox created 330 with the same name as a previously existing mailbox does not inherit 331 the old mailbox annotations. Servers SHOULD allow annotations on 332 all 'types' of mailbox, including ones reporting \Noselect for their 333 LIST response. Servers can implicitly remove \Noselect mailboxes 334 when all child mailboxes are removed, and as such any annotations 335 associated with the \Noselect mailbox SHOULD be removed. 337 The server is allowed to impose limitations on the size of any one 338 annotation or the total number of annotations for a single mailbox 339 or for the server as a whole. However, the server MUST accept a 340 minimum annotation data size of at least 1024 bytes, and a minimum 341 annotation count per server or mailbox of at least 10. 343 7.2 GETANNOTATION Command 345 This extension adds the GETANNOTATION command. This allows clients 346 to retrieve annotations. 348 This command is only available in authenticated state [IMAP4]. 350 Arguments: mailbox-name 351 entry-specifier 352 attribute-specifier 354 Responses: required ANNOTATION response 356 Result: OK - command completed 357 NO - command failure: can't access annotations on that mailbox 358 BAD - command unknown or arguments invalid 360 The mailbox-name argument MUST be a valid mailbox name or the empty 361 string. In the later case, the annotations being referred to are 362 the ones for the server as a whole. 364 Example: 366 C: a GETANNOTATION "" "/comment" "value.priv" 367 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 368 S: a OK GETANNOTATION complete 370 In the above example, the contents of the "value" attribute 371 for the "/comment" server entry is requested by the client 372 and returned by the server. 374 "*" and "%" wildcard characters can be used in either specifier to 375 match one or more characters at that position, with the exception 376 that "%" does not match the hierarchy delimiter for the specifier it 377 appears in (i.e. "/" for an entry specifier or "." for an attribute 378 specifier). Thus an entry specifier of "/%" would match entries 379 such as "/comment" and "/version", but not "/comment/note". 381 Examples: 383 C: a GETANNOTATION "" "/*" "value.priv" 384 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 385 "/version" ("value.priv" "1.1") 386 "/motd/today" ("value.priv" "Closed at 1 pm") 387 S: a OK GETANNOTATION complete 389 In the above example, the contents of the "value" attributes 390 for any server entries are requested by the client and 391 returned by the server. 393 C: a GETANNOTATION "" "/%" "value" 394 S: * ANNOTATION "/comment" ("value.priv" "My comment") 395 ("value.shared" "Your comment") 396 "/motd" ("value.priv" "Its sunny outside!" 397 ("value.shared" "Today is a Holiday") 398 S: a OK GETANNOTATION complete 400 In the above example, the contents of the "value" attributes 401 for server entries at the top level of the entry hierarchy 402 only, are requested by the client and returned by the 403 server. Both the .priv and .shared values are returned, as 404 neither were explicitly requested. 406 Entry and attribute specifiers can be lists of atomic specifiers, so 407 that multiple items of each type may be returned in a single 408 GETANNOTATION command. 410 Examples: 412 C: a GETANNOTATION "" ("/comment" "/motd") "value.priv" 413 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 414 "/motd" ("value.priv" "Its sunny outside!") 415 S: a OK GETANNOTATION complete 417 In the above example, the contents of the "value" attributes 418 for the two server entries "/comment" and "/motd" are 419 requested by the client and returned by the server. 421 C: a GETANNOTATION "" "/comment" ("value.priv" "modifiedsince.priv") 422 S: * ANNOTATION "" "/comment" ("value.priv" "My comment" 423 "modifiedsince.priv" "19990203205432") 424 S: a OK GETANNOTATION complete 426 In the above example, the contents of the "value" and 427 "modifiedsince" attributes for the "/comment" server entry 428 are requested by the client and returned by the server. 430 7.3 SETANNOTATION command 432 This extension adds the SETANNOTATION command. This allows clients 433 to set annotations. 435 This command is only available in authenticated state [IMAP4]. 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 452 server MAY return an unsolicited ANNOTATION response containing the 453 updated annotation data. The server SHOULD send such responses for 454 any changes to the server annotations, and SHOULD send such 455 responses for mailbox annotations only for the currently selected 456 mailbox. Clients MUST NOT assume that an unsolicited ANNOTATION 457 response will be sent, and MUST assume that if the command succeeds 458 then the annotation has 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 465 maximum number of allowed annotations has already been reached, the 466 server MUST return a tagged NO response with a "[ANNOTATEMORE 467 TOOMANY]" 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 Examples: 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 481 "INBOX" is created (if not already present) and the private 482 attribute "value" with data set to "My new comment" is 483 created if not already present, or replaced if it previously 484 exists. 486 C: a SETANNOTATION "INBOX" "/comment" ("value.priv" NIL) 487 S: a OK SETANNOTATION complete 489 In the above example, the private "value" attribute of the 490 entry "/comment" is removed from the mailbox "INBOX". 492 Multiple entries can be set in a single SETANNOTATION command by 493 listing entry-attribute-value pairs in the list. 495 Example: 496 C: a SETANNOTATION "INBOX.%" "/comment" ("value.priv" "My new comment") 497 S: a OK SETANNOTATION complete 499 In the above example, the entry "/comment" for all mailboxes 500 at the top-level of the "INBOX" hierarchy are created (if 501 not already present) and the private and shared attributes 502 "value" are created respectively for each entry if not 503 already present, or replaced if they previously existed. 505 Multiple attributes can be set in a single SETANNOTATION command by 506 listing multiple attribute-value pairs in the entry list. 508 Example: 509 C: a SETANNOTATION "INBOX" "/comment" 510 ("value.priv" "My new comment" 511 "vendor.foobar.bloop.priv" "foo's bar") 512 S: a OK SETANNOTATION complete 514 In the above example, the entry "/comment" for the mailbox 515 "INBOX" is created (if not already present) and the private 516 attributes "value" and "vendor.foobar.bloop" are created if 517 not already present, or replaced if they previously existed. 519 Example: 520 C: a SETANNOTATION "INBOX" "/comment" ("value.priv" "My new comment") 521 S: a NO [ANNOTATEMORE TOOMANY] SETANNOTATION failed 523 In the above example, the server is unable to store the 524 requested (new) annotation as it has reached the limit on 525 the number of annotations it can support on the specified 526 mailbox. 528 7.4 ANNOTATION Response 530 The ANNOTATION response displays results of a GETANNOTATION command, 531 or can be returned as a unsolicited response at anytime by the 532 server in response to a change in an annotation. 534 Servers SHOULD send unsolicited ANNOTATION responses if changed by a 535 third-party, allowing servers to keep clients updated with changes 536 to annotations by other clients. Unsolicited mailbox entries MUST 537 only be returned for the currently selected mailbox. In this case, 538 only the entries are returned in the ANNOTATION response, not the 539 attributes and values. If the client wants to update any cached 540 values it must explicitly retrieve those using a GETANNOTATION 541 command. 543 Separate ANNOTATION responses MUST be used when more than one 544 mailbox matches the mailbox name argument pattern to the command. 546 The ANNOTATION response can contain multiple entries in a single 547 response, but the server is free to return multiple responses for 548 each entry or group of entries if it desires. 550 This response is only available in authenticated state [IMAP4]. 552 7.4.1 ANNOTATION response with attributes and values 553 The response consists of a list of entries each of which has a 554 list of attribute-value pairs. 556 Examples: 558 C: a GETANNOTATION "" "/comment" "value.priv" 559 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 560 S: a OK GETANNOTATION complete 562 In the above example, a single entry with a single 563 attribute-value pair is returned by the server. 565 C: a GETANNOTATION "" ("/comment" "/motd") "value.priv" 566 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 567 "/motd" ("value.priv" "Its sunny outside!") 568 S: a OK GETANNOTATION complete 570 In the above example, two entries each with a single 571 attribute-value pair is returned by the server. 573 C: a GETANNOTATION "" ("/comment" "/motd") "value.priv" 574 S: * ANNOTATION "" "/comment" ("value.priv" "My comment") 575 S: * ANNOTATION "" "/motd" ("value.priv" "Its sunny outside!") 576 S: a OK GETANNOTATION complete 578 In the above example, the server returns two separate 579 responses for each of the two entries requested. 581 C: a GETANNOTATION "" "/comment" ("value.priv" "modifiedsince.priv") 582 S: * ANNOTATION "" "/comment" ("value.priv" "My comment" 583 "modifiedsince.priv" "19990203205432") 584 S: a OK GETANNOTATION complete 586 In the above example, a single entry with two 587 attribute-value pairs is returned by the server. 589 C: a GETANNOTATION "INBOX.%" "/comment" "value.priv" 590 S: * ANNOTATION "INBOX.1" "/comment" ("value.priv" "My comment for 1") 591 S: * ANNOTATION "INBOX.2" "/comment" ("value.priv" "My comment for 2") 592 S: * ANNOTATION "INBOX.3" "/comment" ("value.priv" "My comment for 3") 593 S: a OK GETANNOTATION complete 595 In the above example, separate responses are returned for 596 each matching mailbox, each containing a single entry with a 597 single attribute-value pair. 599 7.4.2 Unsolicited ANNOTATION response without attributes and values 600 The response consists of a parenthesised list of entries, each 601 of which have changed on the server. 603 Examples: 605 C: a NOOP 606 S: * ANNOTATION "" ("/comment") 607 S: a OK NOOP complete 609 In the above example, the server indicates that the 610 "/comment" server entry has been changed. 612 C: a NOOP 613 S: * ANNOTATION "" ("/comment" "/motd") 614 S: a OK NOOP complete 616 In the above example, the server indicates a change to two 617 server entries. 619 C: a NOOP 620 S: * ANNOTATION "" ("/motd") 621 S: * ANNOTATION "INBOX" ("/comment") 622 S: a OK NOOP complete 624 In the above example, the server indicates a change to a 625 server entry, and to the an entry for the currently selected 626 mailbox. 628 8 Formal Syntax 630 The following syntax specification uses the Augmented Backus-Naur 631 Form (ABNF) notation as specified in [ABNF]. 633 Non-terminals referenced but not defined below are as defined by 634 [IMAP4]. 636 Except as noted otherwise, all alphabetic characters are case- 637 insensitive. The use of upper or lower case characters to define 638 token strings is for editorial clarity only. Implementations MUST 639 accept these strings in a case-insensitive fashion. 641 annotate-data = "ANNOTATION" SP mailbox SP entry-list 642 ; empty string for mailbox implies 643 ; server annotation. 645 att-value = attrib SP value 647 attrib = string 648 ; dot-separated attribute name 649 ; MUST NOT contain "*" or "%" 650 attrib-match = string 651 ; dot-separated attribute name 652 ; MAY contain "*" or "%" for use as wildcards 654 attribs = attrib-match / "(" attrib-match *(SP attrib-match) ")" 655 ; attribute specifiers that can include wildcards 657 command-auth /= setannotation / getannotation 658 ; adds to original IMAP4 command 660 entries = entry-match / "(" entry-match *(SP entry-match) ")" 661 ; entry specifiers that can include wildcards 663 entry = string 664 ; slash-separated path to entry 665 ; MUST NOT contain "*" or "%" 667 entry-att = entry SP "(" att-value *(SP att-value) ")" 669 entry-list = entry-att *(SP entry-att) / 670 "(" entry *(SP entry) ")" 671 ; entry attribute-value pairs list for 672 ; GETANNOTATION response, or 673 ; parenthesised entry list for unsolicited 674 ; notification of annotation changes 676 entry-match = string 677 ; slash-separated path to entry 678 ; MAY contain "*" or "%" for use as wildcards 680 getannotation = "GETANNOTATION" SP list-mailbox SP entries SP attribs 681 ; empty string for list-mailbox implies 682 ; server annotation. 684 response-data /= "*" SP annotate-data CRLF 685 ; adds to original IMAP4 data responses 687 resp-text-code =/ "ANNOTATEMORE" SP "TOOBIG" / 688 "ANNOTATEMORE" SP "TOOMANY" 689 ; new response codes for SETANNOTATION failures 691 setannotation = "SETANNOTATION" SP list-mailbox SP setentryatt 692 ; empty string for list-mailbox implies 693 ; server annotation. 695 setentryatt = entry-att / "(" entry-att *(SP entry-att) ")" 697 value = nstring 698 9 IANA Considerations 700 Both entry names and attribute names MUST be specified in a 701 standards track or IESG approved experimental RFC, or fall under the 702 vendor namespace. 704 9.1 Entry and Attribute Registration Template 706 To: iana@iana.org 707 Subject: IMAP ANNOTATEMORE Registration 709 Please register the following IMAP ANNOTATEMORE item: 711 [] Entry [] Attribute 713 [] Mailbox [] Server 715 Name: ______________________________ 717 Description: _______________________ 719 ____________________________________ 721 ____________________________________ 723 Contact person: ____________________ 725 email: ____________________ 727 10 Security Considerations 729 The ANNOTATEMORE extension does not raise any security 730 considerations that are not present in the base [IMAP4] protocol, 731 and these issues are discussed in [IMAP4]. 733 Care must be taken to ensure that annotations whose values are 734 intended to remain private are not stored in mailboxes which are 735 accessible to other users. This includes mailboxes owned by the 736 user by whose ACLs permit access by others as well as any shared 737 mailboxes. 739 11 Normative References 741 [ABNF] Crocker, Overell, "Augmented BNF for Syntax Specifications: 742 ABNF", RFC 2234, November 1997. 744 [ACAP] Newman, C., and Myers, J. "ACAP -- Application Configuration 745 Access Protocol", RFC 2244, November 1997. 747 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 748 4rev1", RFC 3501, March 2003. 750 [IMAPURL] Newman, C., "IMAP URL Scheme", RFC 2192, September 1997. 752 [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate 753 Requirement Levels", RFC 2119, March 1997. 755 [MIME] Freed, N., and Borenstein, N. "MIME (Multipurpose Internet 756 Mail Extensions) Part Two: Media Types", RFC 2046, November 1996. 758 [SORT] Crispin, M., Murchison, K., "Internet Message Access Protocol 759 - Sort and Thread Extension", draft-ietf-imapext-sort-13.txt, May 760 2003. 762 12 Informative References 764 [ANNOTATE] Daboo, C., Gellens, R., "IMAP ANNOTATE Extension", 765 draft-ietf-imapext-annotate-07.txt, May 2003. 767 13 Acknowledgments 769 The ideas expressed in this document are based on the message 770 annotation document that was co-authored by Randall Gellens. 772 14 Author's Address 774 Cyrus Daboo 775 Cyrusoft International, Inc. 776 Suite 780, 5001 Baum Blvd. 777 Pittsburgh, PA 15213 778 U.S.A. 780 Email: daboo@cyrusoft.com 782 15 Full Copyright Statement 784 Copyright (C) The Internet Society 2003. All Rights Reserved. 786 This document and translations of it may be copied and furnished to 787 others, and derivative works that comment on or otherwise explain it 788 or assist in its implementation may be prepared, copied, published 789 and distributed, in whole or in part, without restriction of any 790 kind, provided that the above copyright notice and this paragraph 791 are included on all such copies and derivative works. However, this 792 document itself may not be modified in any way, such as by removing 793 the copyright notice or references to the Internet Society or other 794 Internet organizations, except as needed for the purpose of 795 developing Internet standards in which case the procedures for 796 copyrights defined in the Internet Standards process must be 797 followed, or as required to translate it into languages other than 798 English. 800 The limited permissions granted above are perpetual and will not be 801 revoked by the Internet Society or its successors or assigns. 803 This document and the information contained herein is provided on an 804 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 805 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 806 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 807 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 808 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.