idnits 2.17.1 draft-daboo-imap-annotatemore-17.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 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 1053. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1064. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1071. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1077. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 11, 2008) is 5614 days in the past. Is this intentional? 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: 'METADATA TOOMANY' is mentioned on line 525, but not defined ** Obsolete normative reference: RFC 3501 (Obsoleted by RFC 9051) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Daboo 3 Internet-Draft Apple, Inc. 4 Intended status: Standards Track December 11, 2008 5 Expires: June 14, 2009 7 IMAP METADATA Extension 8 draft-daboo-imap-annotatemore-17 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on June 14, 2009. 35 Abstract 37 The METADATA extension to the Internet Message Access Protocol 38 permits clients and servers to maintain "annotations" or "meta data" 39 on IMAP servers. It is possible to have annotations on a per-mailbox 40 basis or on the server as a whole. For example, this would allow 41 comments about the purpose of a particular mailbox to be "attached" 42 to that mailbox, or a "message of the day" containing server status 43 information to be made available to anyone logging in to the server. 45 Table of Contents 47 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 48 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 49 3. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . 4 50 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 51 3.2. Namespace of entries . . . . . . . . . . . . . . . . . . . 4 52 3.2.1. Entry Names . . . . . . . . . . . . . . . . . . . . . 5 53 3.3. Private versus Shared and Access Control . . . . . . . . . 6 54 4. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 7 55 4.1. General Considerations . . . . . . . . . . . . . . . . . . 7 56 4.2. GETMETADATA Command . . . . . . . . . . . . . . . . . . . 8 57 4.2.1. MAXSIZE GETMETADATA Command Option . . . . . . . . . . 9 58 4.2.2. DEPTH GETMETADATA Command Option . . . . . . . . . . . 10 59 4.3. SETMETADATA Command . . . . . . . . . . . . . . . . . . . 10 60 4.4. METADATA Response . . . . . . . . . . . . . . . . . . . . 12 61 4.4.1. METADATA response with values . . . . . . . . . . . . 13 62 4.4.2. Unsolicited METADATA response without values . . . . . 13 63 5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 14 64 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 65 6.1. Entry and Attribute Registration Template . . . . . . . . 16 66 6.2. Server Entry Registrations . . . . . . . . . . . . . . . . 16 67 6.2.1. /shared/comment . . . . . . . . . . . . . . . . . . . 17 68 6.2.2. /shared/admin . . . . . . . . . . . . . . . . . . . . 17 69 6.3. Mailbox Entry Registrations . . . . . . . . . . . . . . . 17 70 6.3.1. /shared/comment . . . . . . . . . . . . . . . . . . . 18 71 6.3.2. /private/comment . . . . . . . . . . . . . . . . . . . 18 72 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 73 8. Normative References . . . . . . . . . . . . . . . . . . . . . 19 74 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 19 75 Appendix B. Change History (to be removed prior to 76 publication as an RFC) . . . . . . . . . . . . . . . 19 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 23 78 Intellectual Property and Copyright Statements . . . . . . . . . . 24 80 1. Introduction and Overview 82 The goal of the METADATA extension is to provide a means for clients 83 to set and retrieve "annotations" or "meta data" on an IMAP server. 84 The annotations can be associated with specific mailboxes or the 85 server as a whole. The server can choose to support only server 86 annotations or both server and mailbox annotations. 88 A server that supports both server and mailbox annotations indicates 89 the presence of this extension by returning "METADATA" as one of the 90 supported capabilities in the CAPABILITY command response. 92 A server that supports only server annotations indicates the presence 93 of this extension by returning "METADATA-SERVER" as one of the 94 supported capabilities in the CAPABILITY command response. 96 A server that supports unsolicited annotation change responses MUST 97 support the "ENABLE" [RFC5161] extension to allow clients to turn 98 that feature on. 100 The METADATA extension adds two new commands and one new untagged 101 response to the IMAP base protocol. 103 This extension makes the following changes to the IMAP protocol: 105 o adds a new SETMETADATA command 106 o adds a new GETMETADATA command 107 o adds a new METADATA untagged response 108 o adds a new METADATA response code 110 The rest of this document describes the data model and protocol 111 changes more rigorously. 113 2. Conventions Used in This Document 115 In examples, "C:" and "S:" indicate lines sent by the client and 116 server respectively. 118 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 119 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 120 document are to be interpreted as described in [RFC2119]. 122 Whitespace and line breaks have been added to the examples in this 123 document to promote readability. 125 3. Data Model 127 3.1. Overview 129 Mailboxes or the server as a whole may have zero or more annotations 130 associated with them. An annotation contains a uniquely named entry 131 each of which has a value. Annotations can be added to mailboxes 132 when a mailbox name is provided as the first argument to the 133 SETMETADATA command, or to the server as a whole when the empty 134 string is provided as the first argument to the command. 136 For example, a general comment being added to a mailbox may have an 137 entry name of "/comment" and a value "Really useful mailbox". 139 The protocol changes to IMAP described below allow a client to access 140 or change the values of any annotation entry, assuming it has 141 sufficient access rights to do so. 143 3.2. Namespace of entries 145 Each annotation is an entry that has a hierarchical name, with each 146 component of the name separated by a slash ("/"). An entry name MUST 147 NOT contain two consecutive "/" characters and MUST NOT end with a 148 "/" character. 150 The value of an entry is NIL (has no value), or a string or binary 151 data of zero or more octets. A string MAY contain multiple lines of 152 text. Clients MUST use the CRLF (0x0D 0x0A) character octet sequence 153 to represent line ends in a multi-line string value. 155 Entry names MUST NOT contain asterisk ("*") or percent ("%") 156 characters and MUST NOT contain non-ASCII characters or characters 157 with octet values in the range 0x00 to 0x19. Invalid entry names 158 result in a BAD response in any IMAP commands where they are used. 160 Entry names are case-insensitive. 162 Use of control or punctuation characters in entry names is strongly 163 discouraged. 165 This specification defines an initial set of entry names available 166 for use with mailbox and server annotations. In addition an 167 extension mechanism is described to allow additional names to be 168 added for extensibility. 170 The first component in entry names defines the scope of the 171 annotation. Currently only the prefixes "/private" or "/shared" are 172 defined. These prefixes are used to indicate whether an annotation 173 is stored on a per-user basis ("/private") and not visible to other 174 users, or whether an annotation is shared between authorized users 175 ("/shared") with a single value that can be read and changed by 176 authorized users with appropriate access. See Section 3.3 for 177 details. 179 Entry names can have any number of components starting at 2, unless 180 they fall under the vendor namespaces (i.e., have /shared/vendor/ 181 or /private/vendor/ prefix as described 182 below), in which case they have at least 4 components. 184 3.2.1. Entry Names 186 Entry names MUST be specified in a standards track or IESG approved 187 experimental RFC, or fall under the vendor namespace. See 188 Section 6.1 for the registration template. 190 3.2.1.1. Server Entries 192 These entries are set or retrieved when the mailbox name argument to 193 the new SETMETADATA or GETMETATDATA commands is the empty string. 195 /shared/comment 196 Defines a comment or note associated with the server shared with 197 authorized users of the server. 199 /shared/admin 200 Indicates a method for contacting the server administrator. The 201 value MUST be a URI (e.g., a mailto: or tel: URL). This entry is 202 always read-only - clients cannot change it. It is visible to 203 authorized users of the system. 205 /shared/vendor/ 206 Defines the top-level of shared entries associated with the server 207 as created by a particular product of some vendor. This entry can 208 be used by vendors to provide server or client specific 209 annotations. The vendor-token MUST be registered with IANA, using 210 the ACAP [RFC2244] vendor subtree registry. 212 /private/vendor/ 213 Defines the top-level of private entries associated with the 214 server as created by a particular product of some vendor. This 215 entry can be used by vendors to provide server or client specific 216 annotations. The vendor-token MUST be registered with IANA, using 217 the ACAP [RFC2244] vendor subtree registry. 219 3.2.1.2. Mailbox Entries 221 These entries are set or retrieved when the mailbox name argument to 222 the new SETMETADATA or GETMETADATA commands is not the empty string. 224 /shared/comment 225 Defines a shared comment or note associated with a mailbox. 227 /private/comment 228 Defines a private (per-user) comment or note associated with a 229 mailbox. 231 /shared/vendor/ 232 Defines the top-level of shared entries associated with a specific 233 mailbox as created by a particular product of some vendor. This 234 entry can be used by vendors to provide client specific 235 annotations. The vendor-token MUST be registered with IANA, using 236 the ACAP [RFC2244] vendor subtree registry. 238 /private/vendor/ 239 Defines the top-level of private entries associated with a 240 specific mailbox as created by a particular product of some 241 vendor. This entry can be used by vendors to provide client 242 specific annotations. The vendor-token MUST be registered with 243 IANA, using the ACAP [RFC2244] vendor subtree registry. 245 3.3. Private versus Shared and Access Control 247 In the absence of the ACL extension [RFC4314], users can only set and 248 retrieve private or shared mailbox annotations on a mailbox which 249 exists and is returned to them via a LIST or LSUB command, and on 250 which they have either read or write access to the actual message 251 content of the mailbox (as determined by the READ-ONLY and READ-WRITE 252 response codes as described in Section 5.2 of [RFC4314]). 254 When the ACL extension [RFC4314] is present, users can only set and 255 retrieve private or shared mailbox annotations on a mailbox on which 256 they have the "l" right, and any one of the "r", "s", "w", "i" or "p" 257 rights. 259 If a client attempts to set or retrieve annotations on mailboxes 260 which do not satisfy the conditions above, the server MUST respond 261 with a NO response. 263 Users can always retrieve private or shared server annotations if 264 they exist. Servers MAY restrict the creation of private or shared 265 server annotations as appropriate. When restricted, the server MUST 266 return a NO response when the SETMETADATA command is used to try and 267 create a server annotation. 269 If the METADATA extension is present, support for shared annotations 270 is REQUIRED, whilst support for private annotations is OPTIONAL. 271 This recognizes the fact that support for private annotations may 272 introduce significantly more complexity to a server in terms of 273 tracking ownership of the annotations, how quota is determined for 274 users based on their own annotations etc. 276 4. IMAP Protocol Changes 278 4.1. General Considerations 280 The new SETMETADATA command and the METADATA response each have a 281 mailbox name argument. An empty string is used for the mailbox name 282 to signify server annotations. A non-empty string is used to signify 283 mailbox annotations attached to the corresponding mailbox. 285 Servers SHOULD ensure that mailbox annotations are automatically 286 moved when the mailbox they refer to is renamed, i.e., the 287 annotations follow the mailbox. This applies to a rename of the 288 INBOX, with the additional behavior that the annotations are copied 289 from the original INBOX to the renamed mailbox. i.e., mailbox 290 annotations are preserved on the INBOX when it is renamed. 292 Servers SHOULD delete annotations for a mailbox when the mailbox is 293 deleted, so that a mailbox created with the same name as a previously 294 existing mailbox does not inherit the old mailbox annotations. 296 Servers SHOULD allow annotations on all 'types' of mailbox, including 297 ones reporting \Noselect for their LIST response. Servers can 298 implicitly remove \Noselect mailboxes when all child mailboxes are 299 removed, and as such any annotations associated with the \Noselect 300 mailbox SHOULD be removed. 302 The server is allowed to impose limitations on the size of any one 303 annotation or the total number of annotations for a single mailbox or 304 for the server as a whole. However, the server MUST accept an 305 annotation data size of at least 1024 bytes, and an annotation count 306 per server or mailbox of at least 10. 308 Some annotations may be "read-only" - i.e., they are set by the 309 server and cannot be changed by the client. Also, such annotations 310 may be "computed" - i.e., the value changes based on underlying 311 properties of the mailbox or server. For example, an annotation 312 reporting the total size of all messages in the mailbox would change 313 as messages are added or removed. Or, an annotation containing an 314 IMAP URL for the mailbox would change if the mailbox was renamed. 316 Servers MAY support sending unsolicited responses for use when 317 annotations are changed by some "third-party" (see Section 4.4). In 318 order to do so servers MUST support the ENABLE command [RFC5161] and 319 MUST only send unsolicited responses if the client uses the ENABLE 320 command [RFC5161] extension with the capability string "METADATA" or 321 "METADATA-SERVER" earlier in the session, depending on which of those 322 capabilities is supported by the server. 324 4.2. GETMETADATA Command 326 This extension adds the GETMETADATA command. This allows clients to 327 retrieve server or mailbox annotations. 329 This command is only available in authenticated or selected state 330 [RFC3501]. 332 Arguments: mailbox-name 333 options 334 entry-specifier 336 Responses: required METADATA response 338 Result: OK - command completed 339 NO - command failure: can't access annotations on 340 the server 341 BAD - command unknown or arguments invalid 343 When the mailbox name is the empty string, this command retrieves 344 server annotations. When the mailbox name is not empty, this command 345 retrieves annotations on the specified mailbox. 347 Options MAY be included with this command and are defined below. 349 Example: 351 C: a GETMETADATA "" /shared/comment 352 S: * METADATA "" (/shared/comment "Shared comment") 353 S: a OK GETMETADATA complete 355 In the above example, the contents of the value of the "/shared/ 356 comment" server entry is requested by the client and returned by 357 the server. 359 Example: 361 C: a GETMETADATA "INBOX" /private/comment 362 S: * METADATA "INBOX" (/private/comment "My own comment") 363 S: a OK GETMETADATA complete 365 In the above example, the contents of the value of the "/private/ 366 comment" mailbox entry for the mailbox "INBOX" is requested by the 367 client and returned by the server. 369 Entry specifiers can be lists of atomic specifiers, so that multiple 370 annotations may be returned in a single GETMETADATA command. 372 Example: 374 C: a GETMETADATA "INBOX" (/shared/comment /private/comment) 375 S: * METADATA "INBOX" (/shared/comment "Shared comment" 376 /private/comment "My own comment") 377 S: a OK GETMETADATA complete 379 In the above example, the values of the two server entries 380 "/shared/comment" and "/private/comment" on the mailbox "inbox" 381 are requested by the client and returned by the server. 383 4.2.1. MAXSIZE GETMETADATA Command Option 385 When MAXSIZE option is specified with the GETMETADATA command, it 386 restricts which entry values are returned by the server. Only entry 387 values which are less than or equal in octet size to the specified 388 MAXSIZE limit are returned. If there are any entries with values 389 larger than the MAXSIZE limit, the server MUST include the METADATA 390 LONGENTRIES response code in the tagged OK response for the 391 GETMETADATA command. The METADATA LONGENTRIES response code returns 392 the size of the biggest entry value requested by the client which 393 exceeded the MAXSIZE limit. 395 Example: 397 C: a GETMETADATA "INBOX" (MAXSIZE 1024) 398 (/shared/comment /private/comment) 399 S: * METADATA "INBOX" (/private/comment "My own comment") 400 S: a OK [METADATA LONGENTRIES 2199] GETMETADATA complete 402 In the above example, the values of the two server entries 403 "/shared/comment" and "/private/comment" on the mailbox "inbox" 404 are requested by the client which wants to restrict the size of 405 returned values to 1024 octets. In this case the "/shared/ 406 comment" entry value is 2199 octets and is not returned. 408 4.2.2. DEPTH GETMETADATA Command Option 410 When DEPTH option is specified with the GETMETADATA command, it 411 extends the list of entry values returned by the server. For each 412 entry name specified in the GETMETADATA command, the server returns 413 the value of the specified entry name (if it exists), plus all 414 entries below the entry name up to the specified DEPTH. Three values 415 are allowed for DEPTH: 416 "0" - no entries below the specified entry are returned 417 "1" - only entries immediately below the specified entry are 418 returned 419 "infinity" - all entries below the specified entry are returned 420 Thus, "depth 1" for an entry "/a" will match "/a" as well as its 421 children entries (e.g., "/a/b"), but will not match grandchildren 422 entries (e.g., "/a/b/c"). 424 If the DEPTH option is not specified, this is the same as specifying 425 "DEPTH 0". 427 Example: 429 C: a GETMETADATA "INBOX" (DEPTH 1) 430 (/private/filters/values) 431 S: * METADATA "INBOX" (/private/filters/values/small 432 "SMALLER 5000" /private/filters/values/boss 433 "FROM \"boss@example.com\"") 434 S: a OK GETMETADATA complete 436 In the above example, 2 entries below the /private/filters/values 437 entry exist on the mailbox "INBOX": "/private/filters/values/ 438 small" and "/private/filters/values/boss". 440 4.3. SETMETADATA Command 442 This extension adds the SETMETADATA command. This allows clients to 443 set annotations. 445 This command is only available in authenticated or selected state 446 [RFC3501]. 448 Arguments: mailbox-name 449 entry 450 value 451 list of entry, values 453 Responses: no specific responses for this command 455 Result: OK - command completed 456 NO - command failure: can't set annotations, 457 or annotation too big or too many 458 BAD - command unknown or arguments invalid 460 This command sets the specified list of entries by adding or 461 replacing the specified values provided, on the specified existing 462 mailboxes or on the server (if the mailbox argument is the empty 463 string). Clients can use NIL for the value of entries it wants to 464 remove. The server SHOULD NOT return a METADATA response containing 465 the updated annotation data. Clients MUST NOT assume that a METADATA 466 response will be sent, and MUST assume that if the command succeeds 467 then the annotation has been changed. 469 If the server is unable to set an annotation because the size of its 470 value is too large, the server MUST return a tagged NO response with 471 a "[METADATA MAXSIZE NNN]" response code when NNN is the maximum 472 octet count that it is willingly to accept. 474 If the server is unable to set a new annotation because the maximum 475 number of allowed annotations has already been reached, the server 476 MUST return a tagged NO response with a "[METADATA TOOMANY]" response 477 code. 479 If the server is unable to set a new annotation because it does not 480 support private annotations on one of the specified mailboxes, the 481 server MUST return a tagged NO response with a "[METADATA NOPRIVATE]" 482 response code. 484 When any one annotation fails to be set, resulting in a tagged NO 485 response from the server, then the server MUST NOT change the values 486 for other annotations specified in the SETMETADATA command. 488 Example: 490 C: a SETMETADATA INBOX (/private/comment {33} 491 S: + ready for data 492 My new comment across 493 two lines. 494 ) 495 S: a OK SETMETADATA complete 497 In the above example, the entry "/private/comment" for the mailbox 498 "INBOX" is created (if not already present) and the value set to a 499 multi-line string. 501 Example: 503 C: a SETMETADATA INBOX (/private/comment NIL) 504 S: a OK SETMETADATA complete 506 In the above example, the entry "/private/comment" is removed from 507 the mailbox "INBOX". 509 Multiple entries can be set in a single SETMETADATA command by 510 listing entry-value pairs in the list. 512 Example: 514 C: a SETMETADATA INBOX (/private/comment "My new comment" 515 /shared/comment "This one is for you!") 516 S: a OK SETMETADATA complete 518 In the above example, the entries "/private/comment" and "/shared/ 519 comment" for the mailbox "INBOX" are created (if not already 520 present) and the values set as specified. 522 Example: 524 C: a SETMETADATA INBOX (/private/comment "My new comment") 525 S: a NO [METADATA TOOMANY] SETMETADATA failed 527 In the above example, the server is unable to set 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 4.4. METADATA Response 533 The METADATA response displays results of a GETMETADATA command, or 534 can be returned as an unsolicited response at anytime by the server 535 in response to a change in a server or mailbox annotation. 537 When unsolicited responses are activated by the ENABLE [RFC5161] 538 command for this extension, servers MUST send unsolicited METADATA 539 responses if server or mailbox annotations are changed by a third- 540 party, allowing servers to keep clients updated with changes. 542 Unsolicited METADATA responses MUST only contain entry names, not the 543 values. If the client wants to update any cached values it must 544 explicitly retrieve those using a GETMETADATA command. 546 The METADATA 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 or selected state 551 [RFC3501]. 553 4.4.1. METADATA response with values 555 The response consists of a list of entry-value pairs. 557 Example: 559 C: a GETMETADATA "" /shared/comment 560 S: * METADATA "" (/shared/comment "My comment") 561 S: a OK GETMETADATA complete 563 In the above example, a single entry with its value is returned by 564 the server. 566 Example: 568 C: a GETMETADATA "INBOX" /private/comment /shared/comment 569 S: * METADATA "INBOX" (/private/comment "My comment" 570 /shared/comment "Its sunny outside!") 571 S: a OK GETMETADATA complete 573 In the above example, two entries and their values are returned by 574 the server. 576 Example: 578 C: a GETMETADATA "INBOX" /private/comment /shared/comment 579 S: * METADATA "INBOX" (/private/comment "My comment") 580 S: * METADATA "INBOX" (/shared/comment "Its sunny outside!") 581 S: a OK GETMETADATA complete 583 In the above example, the server returns two separate responses 584 for each of the two entries requested. 586 4.4.2. Unsolicited METADATA response without values 588 The response consists of a list of entries, each of which have 589 changed on the server or mailbox. 591 Example: 593 C: a NOOP 594 S: * METADATA "" /shared/comment 595 S: a OK NOOP complete 597 In the above example, the server indicates that the "/shared/ 598 comment" server entry has been changed. 600 Example: 602 C: a NOOP 603 S: * METADATA "INBOX" /shared/comment /private/comment 604 S: a OK NOOP complete 606 In the above example, the server indicates a change to two mailbox 607 entries. 609 5. Formal Syntax 611 The following syntax specification uses the Augmented Backus-Naur 612 Form (ABNF) notation as specified in [RFC5234]. 614 Non-terminals referenced but not defined below are as defined by 615 [RFC3501] with the new definitions in [RFC4466] superseding those in 616 [RFC3501]. 618 Except as noted otherwise, all alphabetic characters are case- 619 insensitive. The use of upper or lower case characters to define 620 token strings is for editorial clarity only. Implementations MUST 621 accept these strings in a case-insensitive fashion. 623 capability =/ "METADATA" / "METADATA-SERVER" 624 ; defines the capabilities for this extension 626 command-auth =/ setmetadata / getmetadata 627 ; adds to original IMAP command 629 entries = entry / 630 "(" entry *(SP entry) ")" 631 ; entry specifiers 633 entry = astring 634 ; slash-separated path to entry 635 ; MUST NOT contain "*" or "%" 637 entry-value = entry SP value 639 entry-values = "(" entry-value *(SP entry-value) ")" 640 entry-list = entry *(SP entry) 641 ; list of entries used in unsolicited 642 ; METADATA response 644 getmetadata = "GETMETADATA" [SP getmetadata-options] 645 SP mailbox SP entries 646 ; empty string for mailbox implies 647 ; server annotation. 649 getmetadata-options = "(" getmetadata-option 650 *(SP getmetadata-option) ")" 652 getmetadata-option = tagged-ext-label [SP tagged-ext-val] 653 ; tagged-ext-label, tagged-ext-val are 654 ; defined in [RFC4466]. 656 maxsize-opt = "MAXSIZE" SP number 657 ; Used as a getmetadata-option 659 metadata-resp = "METADATA" SP mailbox SP 660 (entry-values / entry-list) 661 ; empty string for mailbox implies 662 ; server annotation. 664 response-payload =/ metadata-resp 665 ; adds to original IMAP data responses 667 resp-text-code =/ "METADATA" SP "LONGENTRIES" SP number 668 ; new response codes for GETMETADATA 670 resp-text-code =/ "METADATA" SP ("MAXSIZE" SP number / 671 "TOOMANY" / "NOPRIVATE") 672 ; new response codes for SETMETADATA 673 ; failures 675 scope-opt = "DEPTH" SP ("0" / "1" / "infinity") 676 ; Used as a getmetadata-option 678 setmetadata = "SETMETADATA" SP mailbox 679 SP entry-values 680 ; empty string for mailbox implies 681 ; server annotation. 683 value = nstring / literal8 685 6. IANA Considerations 687 All entries MUST have either "/shared" or "/private" as a prefix. 688 Entry names MUST be specified in a standards track or IESG approved 689 experimental RFC, or fall under the vendor namespace (i.e., use 690 /shared/vendor/ or /private/vendor/ as 691 the prefix). 693 Each entry registration MUST include a content-type that is used to 694 indicate the nature of the annotation value. Where applicable a 695 charset parameter MUST be included with the content-type. 697 6.1. Entry and Attribute Registration Template 699 To: iana@iana.org 700 Subject: IMAP METADATA Entry Registration 702 Type: [Either "Mailbox" or "Server"] 704 Name: [the name of the entry] 706 Description: [a description of what the entry is for] 708 Content-type: [MIME Content-Type and charset for the entry value] 710 RFC Number: [for entries published as RFCs] 712 Contact: [email and/or physical address to contact for 713 additional information] 715 6.2. Server Entry Registrations 717 The following templates specify the IANA registrations of annotation 718 entries specified in this document. 720 6.2.1. /shared/comment 722 To: iana@iana.org 723 Subject: IMAP METADATA Entry Registration 725 Type: Server 727 Name: /shared/comment 729 Description: Defines a comment or note associated with the 730 server shared with authorized users of the server. 732 Content-type: text/plain; charset=utf-8 734 RFC Number: This RFC. 736 Contact: IMAP Extensions mailto:ietf-imapext@imc.org 738 6.2.2. /shared/admin 740 To: iana@iana.org 741 Subject: IMAP METADATA Entry Registration 743 Type: Server 745 Name: /shared/admin 747 Description: Indicates a method for contacting the server 748 administrator. The value MUST be a URI (e.g., a 749 mailto: or tel: URL). This entry is always 750 read-only - clients cannot change it. It is visible 751 to authorized users of the system. 753 Content-type: text/plain; charset=utf-8 755 RFC Number: This RFC. 757 Contact: IMAP Extensions mailto:ietf-imapext@imc.org 759 6.3. Mailbox Entry Registrations 761 The following templates specify the IANA registrations of annotation 762 entries specified in this document. 764 6.3.1. /shared/comment 766 To: iana@iana.org 767 Subject: IMAP METADATA Entry Registration 769 Type: Mailbox 771 Name: /shared/comment 773 Description: Defines a shared comment or note associated with a 774 mailbox. 776 Content-type: text/plain; charset=utf-8 778 RFC Number: This RFC. 780 Contact: IMAP Extensions mailto:ietf-imapext@imc.org 782 6.3.2. /private/comment 784 To: iana@iana.org 785 Subject: IMAP METADATA Entry Registration 787 Type: Mailbox 789 Name: /private/comment 791 Description: Defines a private comment or note associated with a 792 mailbox. 794 Content-type: text/plain; charset=utf-8 796 RFC Number: This RFC. 798 Contact: IMAP Extensions mailto:ietf-imapext@imc.org 800 7. Security Considerations 802 The security considerations in Section 11 of [RFC3501] apply with 803 respect to protecting annotations from snooping. Servers MAY choose 804 to only support the METADATA and/or METADATA-SERVER extensions after 805 a privacy layer has been negotiated by the client. 807 Annotations can contain arbitrary data of varying size. As such 808 servers MUST ensure that size limits are enforced to prevent a user 809 from using up all available space on a server and preventing use by 810 others. Clients MUST treat annotation data values as an "untrusted" 811 source of data as it is possible for it to contain malicious content. 813 Annotations whose values are intended to remain private MUST be 814 stored only in entries that have the "/private" prefix on the entry 815 name. 817 Excluding the above issues the METADATA extension does not raise any 818 security considerations that are not present in the base IMAP 819 protocol, and these issues are discussed in [RFC3501]. 821 8. Normative References 823 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 824 Requirement Levels", BCP 14, RFC 2119, March 1997. 826 [RFC2244] Newman, C. and J. Myers, "ACAP -- Application 827 Configuration Access Protocol", RFC 2244, November 1997. 829 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 830 4rev1", RFC 3501, March 2003. 832 [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", 833 RFC 4314, December 2005. 835 [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 836 ABNF", RFC 4466, April 2006. 838 [RFC5161] Gulbrandsen, A. and A. Melnikov, "The IMAP ENABLE 839 Extension", RFC 5161, March 2008. 841 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 842 Specifications: ABNF", STD 68, RFC 5234, January 2008. 844 Appendix A. Acknowledgments 846 The ideas expressed in this document are based on the message 847 annotation document that was co-authored by Randall Gellens. The 848 author would like to thank the following individuals for contributing 849 their ideas and support for writing this specification: Dave 850 Cridland, Arnt Gulbrandsen, Dan Karp, Alexey Melnikov, Ken Murchison, 851 Chris Newman, Michael Wener. 853 Appendix B. Change History (to be removed prior to publication as an 854 RFC) 856 Changes from -16 to -17: 857 1. Removed "METADATA-UNSOLICITED" capability from ABNF. 858 2. Additional text added to Security Considerations to emphasize 859 3501 privacy statement. 860 3. Additional text added to clarify that multiple components can 861 appear in entry names. 862 4. Changed /public prefix to /shared. 863 5. Fixed minor Gen-ART review issues. 865 Changes from -15 to -16: 866 1. Tweaked enable capability behavior. 867 2. Changed access control text to be more explicit about which ACL 868 privileges are required. 870 Changes from -14 to -15: 871 1. Addressed minor issues from Gen-ART review on -12 version. 872 2. Removed comparator paragraph - no need to specify how the server 873 does its comparisons. 874 3. Added MAXSIZE GETMETADATA option. 875 4. Added DEPTH GETMETADATA option. 876 5. Additional restriction on entry name octet values added. 877 6. Added text about access restrictions for server annotations. 879 Changes from -13 to -14: 880 1. Add statement that no annotations are set when any one fails in a 881 single SETMETADATA command. 882 2. Make unsolicited responses a MUST when ENABLE is used, but make 883 support for ENABLE METADATA optional so servers aren't required 884 to do unsolicited responses. This required a new capbility for 885 the unsolicited behavior. 886 3. Re-ordered Security considerations paragraphs and added 887 additional text about the possibility of malicious content in 888 data values. [SECDIR suggestion] 889 4. Reworded "all users" to "authorized users" in appropriate places. 890 [SECDIR suggestion] 891 5. Added addition text to Security considerations about the need for 892 servers to keep /private annotations private to the user that 893 created them. [SECDIR suggestion] 894 6. Added comment that string values can be multi-line and that CRLF 895 must be the line end indicator. Also changes one example to be 896 multi-line. [SECDIR suggestion] 898 Changes from -12 to -13: 899 1. Major changes to simplify things. 900 2. Removed dependency on LISTEXT - GETMETADATA now used to get 901 annotations on mailboxes. 903 3. Changed data model to remove attributes - annotations are now 904 only entry-value pairs. 905 4. Removed all wildcard behavior on entry names. 906 5. Cut down the registered annotations to only a few essential ones. 908 Changes from -11 to -12: 909 1. Allow server annotations to be used without mailbox annotations. 910 2. Require i;unicode-casemap when COMPARATOR is not present. 911 3. Use ENABLE to turn on unsolicited responses. 912 4. Use formal syntax elements from SORT/THREAD extensions to define 913 the values for /sort and /thread entries. 914 5. Added a comment that use of IDLE is preferred even when /check 915 is true. 916 6. Use formal syntax element from base spec for the /size value. 917 7. Removed IANA registration for attributes as we don't expect any 918 more to be defined. 919 8. Tweaked IANA registration template to be more compact and add 920 RFC Number reference. 921 9. Some minor re-phrasing was done. 922 10. Added text about handling of annotations on INBOX when it is 923 renamed. 924 11. Require a BAD response when an unknown collation is used in 925 LISTEXT selection option. 927 Changes from -10 to -11: 928 1. Added new paragraph to indicate that values may be read-only or 929 computed. 930 2. /admin server annotation value now must be a URI. 931 3. Clarified that SORT and THREAD extensions are not required. 932 4. Fixed use of undefined entries in some examples. 933 5. Fixed many examples. 934 6. Added IANA registration for LIST-EXTENDED items. 935 7. Added match type and collation identifier to the LIST-EXTENDED 936 selection option. 937 8. Made support for IMAP-I18N a requirement. 938 9. Minor text clarifications applied. 939 10. Remove mailbox list set atomicity requirement. 940 11. Clarified that annotations can only be set on mailboxes that 941 actually exist. 943 Changes from -09 to -10: 944 1. Updated to rfc 4466 reference. 945 2. Reworded data model description. 946 3. Reworked LIST-EXTENDED so that responses have metadata items 947 after the mailbox info. 948 4. Various spelling fixes. 950 Changes from -08 to -09: 952 1. Remove content-language attribute and reference. 953 2. Changed capability and command names. 954 3. Revised abstract. 956 Changes from -07 to -08: 957 1. Changed 'string' formal syntax to 'list-mailbox' and 'astring' 958 for entry/attribute names. 959 2. Updated examples to match new astring syntax. 960 3. Changed CAPABILITY name due to incompatible syntax change. 961 4. Removed content-type attribute. 962 5. Added Content-type to IANA registration for entries. 963 6. Removed vendor attributes. 964 7. Fixed examples in section 3.3 for multi-mailbox and multi-entry 965 cases. 966 8. Removed wildcards for attributes. 967 9. Entry/attributes can now only be ASCII. 968 10. Tied up text wrt storing/fetching. 969 11. Added Conventions section 970 12. Entry/attributes MUST NOT contain consecutive or trailing '/' or 971 '.'. 972 13. Changed to use IMAP ABNF extensions document for some formal 973 syntax items. 975 Changes from -06 to -07: 976 1. Reworded /checkperiod item. 977 2. Clarified unsolicited response behavior. 979 Changes from -05 to -06: 980 1. Removed 'modifiedsince' attribute as there is currently no use 981 for it. 982 2. Added content-language attribute. 983 3. Changed access to allow .priv and .shared on any mailbox returned 984 by LIST/LSUB. 985 4. Added IANA registrations for items defined in this document. 986 5. Added latest IPR statement. 987 6. Updated references. 989 Changes from -04 to -05: 990 1. Fix for valid IMAP state of commands. 991 2. Fix formatting, ID nits etc. 993 Changes from -03 to -04: 994 1. Allow retrieval of shared annotations for READ-ONLY mailbox. 995 2. Clarification of annotation loss on implicit removal of \Noselect 996 mailboxes. 997 3. Now requires roll-back of all changes to matching mailboxes if 998 there is a partial failure in SETANNOTATION. 1000 Changes from -02 to -03: 1001 1. Reworked entry naming scheme to split out mailbox name and use 1002 empty string for server items. 1004 Changes from -01 to -02: 1005 1. SETANNOTATION lists use (..). 1006 2. Explicitly state behavior of unsolicited responses. 1007 3. Adding SHOULD behavior for rename/delete of mailboxes. 1008 4. Added statement about supporting annotations on \Noselect 1009 mailboxes. 1010 5. Cleaned up formal syntax to use IMAP string type for entry and 1011 attributes, with requirements on how the string is formatted. 1012 6. Use of ACAP vendor subtree registry for vendor tokens. 1014 Changes from -00 to -01: 1015 1. Multiple entry-att responses are now simply delimited by spaces 1016 in line with ANNOTATE spec. Adjusted examples to match. 1017 2. Fixed entry-list formal syntax item to account for unsolicited 1018 parenthesized list of entries. 1019 3. Removed setentries formal syntax item for simplicity since its 1020 only used once. 1021 4. Removed reference to 'message annotation' in section 5.1. 1022 5. Changed formal syntax to restrict top level entries to /server 1023 and /mailbox/{...} only. Re-arranged entry names section to 1024 account for this change. 1025 6. Added comment and example for ANNOTATION response to allow 1026 servers to return separate responses for each entry if desired. 1028 Author's Address 1030 Cyrus Daboo 1031 Apple Inc. 1032 1 Infinite Loop 1033 Cupertino, CA 95014 1034 USA 1036 Email: cyrus@daboo.name 1037 URI: http://www.apple.com/ 1039 Full Copyright Statement 1041 Copyright (C) The IETF Trust (2008). 1043 This document is subject to the rights, licenses and restrictions 1044 contained in BCP 78, and except as set forth therein, the authors 1045 retain all their rights. 1047 This document and the information contained herein are provided on an 1048 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1049 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1050 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1051 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1052 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1053 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1055 Intellectual Property 1057 The IETF takes no position regarding the validity or scope of any 1058 Intellectual Property Rights or other rights that might be claimed to 1059 pertain to the implementation or use of the technology described in 1060 this document or the extent to which any license under such rights 1061 might or might not be available; nor does it represent that it has 1062 made any independent effort to identify any such rights. Information 1063 on the procedures with respect to rights in RFC documents can be 1064 found in BCP 78 and BCP 79. 1066 Copies of IPR disclosures made to the IETF Secretariat and any 1067 assurances of licenses to be made available, or the result of an 1068 attempt made to obtain a general license or permission for the use of 1069 such proprietary rights by implementers or users of this 1070 specification can be obtained from the IETF on-line IPR repository at 1071 http://www.ietf.org/ipr. 1073 The IETF invites any interested party to bring to its attention any 1074 copyrights, patents or patent applications, or other proprietary 1075 rights that may cover technology that may be required to implement 1076 this standard. Please address the information to the IETF at 1077 ietf-ipr@ietf.org.