idnits 2.17.1 draft-daboo-imap-annotatemore-15.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 1017. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1028. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1035. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1041. 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 (October 13, 2008) is 5673 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 512, 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 October 13, 2008 5 Expires: April 16, 2009 7 IMAP METADATA Extension 8 draft-daboo-imap-annotatemore-15 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 April 16, 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 Public and Access Control . . . . . . . . . 6 54 4. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . 9 59 4.3. SETMETADATA Command . . . . . . . . . . . . . . . . . . . 10 60 4.4. METADATA Response . . . . . . . . . . . . . . . . . . . . 12 61 4.4.1. METADATA response with values . . . . . . . . . . . . 12 62 4.4.2. Unsolicited METADATA response without values . . . . . 13 63 5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 14 64 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 65 6.1. Entry and Attribute Registration Template . . . . . . . . 16 66 6.2. Server Entry Registrations . . . . . . . . . . . . . . . . 16 67 6.2.1. /public/comment . . . . . . . . . . . . . . . . . . . 16 68 6.2.2. /public/admin . . . . . . . . . . . . . . . . . . . . 17 69 6.3. Mailbox Entry Registrations . . . . . . . . . . . . . . . 17 70 6.3.1. /public/comment . . . . . . . . . . . . . . . . . . . 17 71 6.3.2. /private/comment . . . . . . . . . . . . . . . . . . . 18 72 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 73 8. Normative References . . . . . . . . . . . . . . . . . . . . . 18 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 . . . . . . . . . . . . . . . . . . . . . . . . . 22 78 Intellectual Property and Copyright Statements . . . . . . . . . . 23 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 97 indicates the presence of that feature by returning "METADATA- 98 UNSOLICITED" as one of the supported capabilities in the CAPABILITY 99 command response. The "ENABLE" [RFC5161] extension MUST also be 100 present if the "METADATA-UNSOLICITED" capability is advertised. 102 The METADATA extension adds two new commands and one new untagged 103 response to the IMAP base protocol. 105 This extension makes the following changes to the IMAP protocol: 107 o adds a new SETMETADATA command 108 o adds a new GETMETADATA command 109 o adds a new METADATA untagged response 110 o adds a new METADATA response code 112 The rest of this document describes the data model and protocol 113 changes more rigorously. 115 2. Conventions Used in This Document 117 In examples, "C:" and "S:" indicate lines sent by the client and 118 server respectively. 120 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 121 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 122 document are to be interpreted as described in [RFC2119]. 124 Whitespace and line breaks have been added to the examples in this 125 document to promote readability. 127 3. Data Model 129 3.1. Overview 131 Mailboxes or the server as a whole may have zero or more annotations 132 associated with them. An annotation contains a uniquely named entry 133 each of which has a value. Annotations can be added to mailboxes 134 when a mailbox name is provided as the first argument to the 135 SETMETADATA command, or to the server as a whole when the empty 136 string is provided as the first argument to the command. 138 For example, a general comment being added to a mailbox may have an 139 entry name of "/comment" and a value "Really useful mailbox". 141 The protocol changes to IMAP described below allow a client to access 142 or change the values of any annotation entry, assuming it has 143 sufficient access rights to do so. 145 3.2. Namespace of entries 147 Each annotation is an entry that has a hierarchical name, with each 148 component of the name separated by a slash ("/"). An entry name MUST 149 NOT contain two consecutive "/" characters and MUST NOT end with a 150 "/" character. 152 The value of an entry is NIL (has no value), or a string or binary 153 data of zero or more octets. A string MAY contain multiple lines of 154 text. Clients MUST use the CRLF (0x0D 0x0A) character octet sequence 155 to represent line ends in a multi-line string value. 157 Entry names MUST NOT contain asterisk ("*") or percent ("%") 158 characters and MUST NOT contain non-ASCII characters or characters 159 with octet values in the range 0x00 to 0x19. Invalid entry names 160 result in a BAD response in any IMAP commands where they are used. 162 Entry names are case-insensitive. 164 Use of control or punctuation characters in entry names is strongly 165 discouraged. 167 This specification defines an initial set of entry names available 168 for use with mailbox and server annotations. In addition an 169 extension mechanism is described to allow additional names to be 170 added for extensibility. 172 The first component in entry names defines the scope of the 173 annotation. Currently only the prefixes "/private" or "/public" are 174 defined. These prefixes are used to indicate whether an annotation 175 is stored on a per-user basis ("/private") and not visible to other 176 users, or whether an annotation is shared between authorized users 177 ("/public") with a single value that can be read and changed by 178 authorized users with appropriate access. See Section 3.3 for 179 details. 181 3.2.1. Entry Names 183 Entry names MUST be specified in a standards track or IESG approved 184 experimental RFC, or fall under the vendor namespace. See 185 Section 6.1 for the registration template. 187 3.2.1.1. Server Entries 189 These entries are set or retrieved when the mailbox name argument to 190 the new SETMETADATA or GETMETATDATA commands is the empty string. 192 /public/comment 193 Defines a comment or note associated with the server shared with 194 authorized users of the server. 196 /public/admin 197 Indicates a method for contacting the server administrator. The 198 value MUST be a URI (e.g., a mailto: or tel: URL). This entry is 199 always read-only - clients cannot change it. It is visible to 200 authorized users of the system. 202 /public/vendor/ 203 Defines the top-level of public entries associated with the server 204 as created by a particular product of some vendor. This entry can 205 be used by vendors to provide server or client specific 206 annotations. The vendor-token MUST be registered with IANA, using 207 the ACAP [RFC2244] vendor subtree registry. 209 /private/vendor/ 210 Defines the top-level of private entries associated with the 211 server as created by a particular product of some vendor. This 212 entry can be used by vendors to provide server or client specific 213 annotations. The vendor-token MUST be registered with IANA, using 214 the ACAP [RFC2244] vendor subtree registry. 216 3.2.1.2. Mailbox Entries 218 These entries are set or retrieved when the mailbox name argument to 219 the new SETMETADATA or GETMETADATA commands is not the empty string. 221 /public/comment 222 Defines a public comment or note associated with a mailbox. 224 /private/comment 225 Defines a private (per-user) comment or note associated with a 226 mailbox. 228 /public/vendor/ 229 Defines the top-level of public entries associated with a specific 230 mailbox as created by a particular product of some vendor. This 231 entry can be used by vendors to provide client specific 232 annotations. The vendor-token MUST be registered with IANA, using 233 the ACAP [RFC2244] vendor subtree registry. 235 /private/vendor/ 236 Defines the top-level of private entries associated with a 237 specific mailbox as created by a particular product of some 238 vendor. This entry can be used by vendors to provide client 239 specific annotations. The vendor-token MUST be registered with 240 IANA, using the ACAP [RFC2244] vendor subtree registry. 242 3.3. Private versus Public and Access Control 244 Users can only set and retrieve private or public mailbox annotations 245 on a mailbox which exists and is returned to them via a LIST or LSUB 246 command, irrespective of whether they have read or write access to 247 the actual message content of the mailbox. If a client attempts to 248 set or retrieve annotations on other mailboxes, the server MUST 249 respond with a NO response. 251 Users can always retrieve private or public server annotations if 252 they exist. Servers MAY restrict the creation of private or public 253 server annotations as appropriate. When restricted, the server MUST 254 return a NO response when the SETMETADATA command is used to try and 255 create a server anotation. 257 If the METADATA extension is present, support for public annotations 258 is REQUIRED, whilst support for private annotations is OPTIONAL. 259 This recognizes the fact that support for private annotations may 260 introduce significantly more complexity to a server in terms of 261 tracking ownership of the annotations, how quota is determined for 262 users based on their own annotations etc. 264 4. IMAP Protocol Changes 265 4.1. General Considerations 267 The new SETMETADATA command and the METADATA response each have a 268 mailbox name argument. An empty string is used for the mailbox name 269 to signify server annotations. A non-empty string is used to signify 270 mailbox annotations attached to the corresponding mailbox. 272 Servers SHOULD ensure that mailbox annotations are automatically 273 moved when the mailbox they refer to is renamed, i.e., the 274 annotations follow the mailbox. This applies to a rename of the 275 INBOX, with the additional behavior that the annotations are copied 276 from the original INBOX to the renamed mailbox. i.e., mailbox 277 annotations are preserved on the INBOX when it is renamed. 279 Servers SHOULD delete annotations for a mailbox when the mailbox is 280 deleted, so that a mailbox created with the same name as a previously 281 existing mailbox does not inherit the old mailbox annotations. 283 Servers SHOULD allow annotations on all 'types' of mailbox, including 284 ones reporting \Noselect for their LIST response. Servers can 285 implicitly remove \Noselect mailboxes when all child mailboxes are 286 removed, and as such any annotations associated with the \Noselect 287 mailbox SHOULD be removed. 289 The server is allowed to impose limitations on the size of any one 290 annotation or the total number of annotations for a single mailbox or 291 for the server as a whole. However, the server MUST accept a minimum 292 annotation data size of at least 1024 bytes, and a minimum annotation 293 count per server or mailbox of at least 10. 295 Some annotations may be "read-only" - i.e., they are set by the 296 server and cannot be changed by the client. Also, such annotations 297 may be "computed" - i.e., the value changes based on underlying 298 properties of the mailbox or server. For example, an annotation 299 reporting the total size of all messages in the mailbox would change 300 as messages are added or removed. Or, an annotation containing an 301 IMAP URL for the mailbox would change if the mailbox was renamed. 303 Servers MAY support sending unsolicited responses for use when 304 annotations are changed by some "third-party" (see Section 4.4). 305 Servers indicate their ability to do that by advertising the 306 "METADATA-UNSOLICITED" capability and supporting the ENABLE command. 307 Servers MUST only send unsolicited responses if the client used the 308 ENABLE command [RFC5161] extension with the capability string 309 "METADATA-UNSOLICITED" earlier in the session. 311 4.2. GETMETADATA Command 313 This extension adds the GETMETADATA command. This allows clients to 314 retrieve server or mailbox annotations. 316 This command is only available in authenticated or selected state 317 [RFC3501]. 319 Arguments: mailbox-name 320 options 321 entry-specifier 323 Responses: required METADATA response 325 Result: OK - command completed 326 NO - command failure: can't access annotations on 327 the server 328 BAD - command unknown or arguments invalid 330 When the mailbox name is the empty string, this command retrieves 331 server annotations. When the mailbox name is not empty, this command 332 retrieves annotations on the specified mailbox. 334 Options MAY be included with this command and are defined below. 336 Example: 338 C: a GETMETADATA "" /public/comment 339 S: * METADATA "" (/public/comment "Shared comment") 340 S: a OK GETMETADATA complete 342 In the above example, the contents of the value of the "/public/ 343 comment" server entry is requested by the client and returned by 344 the server. 346 Example: 348 C: a GETMETADATA "INBOX" /private/comment 349 S: * METADATA "INBOX" (/private/comment "My own comment") 350 S: a OK GETMETADATA complete 352 In the above example, the contents of the value of the "/private/ 353 comment" mailbox entry for the mailbox "INBOX" is requested by the 354 client and returned by the server. 356 Entry specifiers can be lists of atomic specifiers, so that multiple 357 annotations may be returned in a single GETMETADATA command. 359 Example: 361 C: a GETMETADATA "INBOX" (/public/comment /private/comment) 362 S: * METADATA "INBOX" (/public/comment "Shared comment" 363 /private/comment "My own comment") 364 S: a OK GETMETADATA complete 366 In the above example, the values of the two server entries 367 "/public/comment" and "/private/comment" on the mailbox "inbox" 368 are requested by the client and returned by the server. 370 4.2.1. MAXSIZE GETMETADATA Command Option 372 When MAXSIZE option is specified with the GETMETADATA command, it 373 restricts which entry values are returned by the server. Only entry 374 values which are less than or equal in octet size to the specified 375 MAXSIZE limit are returned. If there are any entries with values 376 larger than the MAXSIZE limit, the server MUST include the METADATA 377 LONGENTRIES response code in the tagged OK response for the 378 GETMETADATA command. The METADATA LONGENTRIES response code returns 379 the size of the biggest entry value requested by the client which 380 exceeded the MAXSIZE limit. 382 Example: 384 C: a GETMETADATA "INBOX" (MAXSIZE 1024) 385 (/public/comment /private/comment) 386 S: * METADATA "INBOX" (/private/comment "My own comment") 387 S: a OK [METADATA LONGENTRIES 2199] GETMETADATA complete 389 In the above example, the values of the two server entries 390 "/public/comment" and "/private/comment" on the mailbox "inbox" 391 are requested by the client which wants to restrict the size of 392 returned values to 1024 octets. In this case the "/public/ 393 comment" entry value is 2199 octets and is not returned. 395 4.2.2. DEPTH GETMETADATA Command Option 397 When DEPTH option is specified with the GETMETADATA command, it 398 extends the list of entry values returned by the server. For each 399 entry name specified in the GETMETADATA command, the server returns 400 the value of the specified entry name (if it exists), plus all 401 entries below the entry name up to the specified DEPTH. Three values 402 are allowed for DEPTH: 403 "0" - no entries below the specified entry are returned 404 "1" - only entries immediately below the specified entry are 405 returned 406 "infinity" - all entries below the specified entry are returned 407 Thus, "depth 1" for an entry "/a" will match "/a" as well as its 408 children entries (e.g. "/a/b"), but will not match grandchildren 409 entries (e.g. "/a/b/c"). 411 If the DEPTH option is not specified, this is the same as specifying 412 "DEPTH 0". 414 Example: 416 C: a GETMETADATA "INBOX" (DEPTH 1) 417 (/private/filters/values) 418 S: * METADATA "INBOX" (/private/filters/values/small 419 "SMALLER 5000" /private/filters/values/boss 420 "FROM \"boss@example.com\"") 421 S: a OK GETMETADATA complete 423 In the above example, 2 entries below the /private/filters/values 424 entry exist on the mailbox "INBOX": "/private/filters/values/ 425 small" and "/private/filters/values/boss". 427 4.3. SETMETADATA Command 429 This extension adds the SETMETADATA command. This allows clients to 430 set annotations. 432 This command is only available in authenticated or selected state 433 [RFC3501]. 435 Arguments: mailbox-name 436 entry 437 value 438 list of entry, values 440 Responses: no specific responses for this command 442 Result: OK - command completed 443 NO - command failure: can't set annotations, 444 or annotation too big or too many 445 BAD - command unknown or arguments invalid 447 This command sets the specified list of entries by adding or 448 replacing the specified values provided, on the specified existing 449 mailboxes or on the server (if the mailbox argument is the empty 450 string). Clients can use NIL for the value of entries it wants to 451 remove. The server SHOULD NOT return a METADATA response containing 452 the updated annotation data. Clients MUST NOT assume that a METADATA 453 response will be sent, and MUST assume that if the command succeeds 454 then the annotation has been changed. 456 If the server is unable to set an annotation because the size of its 457 value is too large, the server MUST return a tagged NO response with 458 a "[METADATA MAXSIZE NNN]" response code when NNN is the maximum 459 octet count that it is willingly to accept. 461 If the server is unable to set a new annotation because the maximum 462 number of allowed annotations has already been reached, the server 463 MUST return a tagged NO response with a "[METADATA TOOMANY]" response 464 code. 466 If the server is unable to set a new annotation because it does not 467 support private annotations on one of the specified mailboxes, the 468 server MUST return a tagged NO response with a "[METADATA NOPRIVATE]" 469 response code. 471 When any one annotation fails to be set, resulting in a tagged NO 472 response from the server, then the server MUST NOT change the values 473 for other annotations specified in the SETMETADATA command. 475 Example: 477 C: a SETMETADATA INBOX (/private/comment {33} 478 S: + ready for data 479 My new comment across 480 two lines. 481 ) 482 S: a OK SETMETADATA complete 484 In the above example, the entry "/private/comment" for the mailbox 485 "INBOX" is created (if not already present) and the value set to a 486 multi-line string. 488 Example: 490 C: a SETMETADATA INBOX (/private/comment NIL) 491 S: a OK SETMETADATA complete 493 In the above example, the entry "/private/comment" is removed from 494 the mailbox "INBOX". 496 Multiple entries can be set in a single SETMETADATA command by 497 listing entry-value pairs in the list. 499 Example: 501 C: a SETMETADATA INBOX (/private/comment "My new comment" 502 /public/comment "This one is for you!") 503 S: a OK SETMETADATA complete 505 In the above example, the entries "/private/comment" and "/public/ 506 comment" for the mailbox "INBOX" are created (if not already 507 present) and the values set as specified. 509 Example: 511 C: a SETMETADATA INBOX (/private/comment "My new comment") 512 S: a NO [METADATA TOOMANY] SETMETADATA failed 514 In the above example, the server is unable to set the requested 515 (new) annotation as it has reached the limit on the number of 516 annotations it can support on the specified mailbox. 518 4.4. METADATA Response 520 The METADATA response displays results of a GETMETADATA command, or 521 can be returned as an unsolicited response at anytime by the server 522 in response to a change in a server or mailbox annotation. 524 When unsolicited responses are activated by the ENABLE [RFC5161] 525 command for this extension, servers MUST send unsolicited METADATA 526 responses if server or mailbox annotations are changed by a third- 527 party, allowing servers to keep clients updated with changes. 529 Unsolicited METADATA responses MUST only contain entry names, not the 530 values. If the client wants to update any cached values it must 531 explicitly retrieve those using a GETMETADATA command. 533 The METADATA response can contain multiple entries in a single 534 response, but the server is free to return multiple responses for 535 each entry or group of entries if it desires. 537 This response is only available in authenticated or selected state 538 [RFC3501]. 540 4.4.1. METADATA response with values 542 The response consists of a list of entry-value pairs. 544 Example: 546 C: a GETMETADATA "" /public/comment 547 S: * METADATA "" (/public/comment "My comment") 548 S: a OK GETMETADATA complete 550 In the above example, a single entry with its value is returned by 551 the server. 553 Example: 555 C: a GETMETADATA "INBOX" /private/comment /public/comment 556 S: * METADATA "INBOX" (/private/comment "My comment" 557 /public/comment "Its sunny outside!") 558 S: a OK GETMETADATA complete 560 In the above example, two entries and their values are returned by 561 the server. 563 Example: 565 C: a GETMETADATA "INBOX" /private/comment /public/comment 566 S: * METADATA "INBOX" (/private/comment "My comment") 567 S: * METADATA "INBOX" (/public/comment "Its sunny outside!") 568 S: a OK GETMETADATA complete 570 In the above example, the server returns two separate responses 571 for each of the two entries requested. 573 4.4.2. Unsolicited METADATA response without values 575 The response consists of a list of entries, each of which have 576 changed on the server or mailbox. 578 Example: 580 C: a NOOP 581 S: * METADATA "" /public/comment 582 S: a OK NOOP complete 584 In the above example, the server indicates that the "/public/ 585 comment" server entry has been changed. 587 Example: 589 C: a NOOP 590 S: * METADATA "INBOX" /public/comment /private/comment 591 S: a OK NOOP complete 593 In the above example, the server indicates a change to two mailbox 594 entries. 596 5. Formal Syntax 598 The following syntax specification uses the Augmented Backus-Naur 599 Form (ABNF) notation as specified in [RFC5234]. 601 Non-terminals referenced but not defined below are as defined by 602 [RFC3501] with the new definitions in [RFC4466] superseding those in 603 [RFC3501]. 605 Except as noted otherwise, all alphabetic characters are case- 606 insensitive. The use of upper or lower case characters to define 607 token strings is for editorial clarity only. Implementations MUST 608 accept these strings in a case-insensitive fashion. 610 capability =/ "METADATA" / "METADATA-SERVER" / 611 "METADATA-UNSOLICITED" 612 ; defines the capabilities for this extension 614 command-auth =/ setmetadata / getmetadata 615 ; adds to original IMAP command 617 entries = entry / 618 "(" entry *(SP entry) ")" 619 ; entry specifiers 621 entry = astring 622 ; slash-separated path to entry 623 ; MUST NOT contain "*" or "%" 625 entry-value = entry SP value 627 entry-values = "(" entry-value *(SP entry-value) ")" 629 entry-list = entry *(SP entry) 630 ; list of entries used in unsolicited 631 ; METADATA response 633 getmetadata = "GETMETADATA" [SP getmetadata-options] 634 SP mailbox SP entries 635 ; empty string for mailbox implies 636 ; server annotation. 638 getmetadata-options = "(" getmetadata-option 639 *(SP getmetadata-option) ")" 641 getmetadata-option = tagged-ext-label [SP tagged-ext-val] 642 ; tagged-ext-label, tagged-ext-val are 643 ; defined in [RFC4466]. 645 maxsize-opt = "MAXSIZE" SP number 646 ; Used as a getmetadata-option 648 metadata-resp = "METADATA" SP mailbox SP 649 (entry-values / entry-list) 650 ; empty string for mailbox implies 651 ; server annotation. 653 response-payload =/ metadata-resp 654 ; adds to original IMAP data responses 656 resp-text-code =/ "METADATA" SP "LONGENTRIES" SP number 657 ; new response codes for GETMETADATA 659 resp-text-code =/ "METADATA" SP ("MAXSIZE" SP number / 660 "TOOMANY" / "NOPRIVATE") 661 ; new response codes for SETMETADATA 662 ; failures 664 scope-opt = "DEPTH" SP ("0" / "1" / "infinity") 665 ; Used as a getmetadata-option 667 setmetadata = "SETMETADATA" SP mailbox 668 SP entry-values 669 ; empty string for mailbox implies 670 ; server annotation. 672 value = nstring / literal8 674 6. IANA Considerations 676 Entry names MUST be specified in a standards track or IESG approved 677 experimental RFC, or fall under the vendor namespace. All entries 678 MUST have either "/public" or "/private" as a prefix. 680 Each entry registration MUST include a content-type that is used to 681 indicate the nature of the annotation value. Where applicable a 682 charset parameter MUST be included with the content-type. 684 6.1. Entry and Attribute Registration Template 686 To: iana@iana.org 687 Subject: IMAP METADATA Entry Registration 689 Type: [Either "Mailbox" or "Server"] 691 Name: [the name of the entry] 693 Description: [a description of what the entry is for] 695 Content-type: [MIME Content-Type and charset for the entry value] 697 RFC Number: [for entries published as RFCs] 699 Contact: [email and/or physical address to contact for 700 additional information] 702 6.2. Server Entry Registrations 704 The following templates specify the IANA registrations of annotation 705 entries specified in this document. 707 6.2.1. /public/comment 709 To: iana@iana.org 710 Subject: IMAP METADATA Entry Registration 712 Type: Server 714 Name: /public/comment 716 Description: Defines a comment or note associated with the 717 server shared with authorized users of the server. 719 Content-type: text/plain; charset=utf-8 721 RFC Number: This RFC. 723 Contact: IMAP Extensions mailto:ietf-imapext@imc.org 725 6.2.2. /public/admin 727 To: iana@iana.org 728 Subject: IMAP METADATA Entry Registration 730 Type: Server 732 Name: /public/admin 734 Description: Indicates a method for contacting the server 735 administrator. The value MUST be a URI (e.g., a 736 mailto: or tel: URL). This entry is always 737 read-only - clients cannot change it. It is visible 738 to authorized users of the system. 740 Content-type: text/plain; charset=utf-8 742 RFC Number: This RFC. 744 Contact: IMAP Extensions mailto:ietf-imapext@imc.org 746 6.3. Mailbox Entry Registrations 748 The following templates specify the IANA registrations of annotation 749 entries specified in this document. 751 6.3.1. /public/comment 753 To: iana@iana.org 754 Subject: IMAP METADATA Entry Registration 756 Type: Mailbox 758 Name: /public/comment 760 Description: Defines a public comment or note associated with a 761 mailbox. 763 Content-type: text/plain; charset=utf-8 765 RFC Number: This RFC. 767 Contact: IMAP Extensions mailto:ietf-imapext@imc.org 769 6.3.2. /private/comment 771 To: iana@iana.org 772 Subject: IMAP METADATA Entry Registration 774 Type: Mailbox 776 Name: /private/comment 778 Description: Defines a private comment or note associated with a 779 mailbox. 781 Content-type: text/plain; charset=utf-8 783 RFC Number: This RFC. 785 Contact: IMAP Extensions mailto:ietf-imapext@imc.org 787 7. Security Considerations 789 Annotations can contain arbitrary data of varying size. As such 790 servers MUST ensure that size limits are enforced to prevent a user 791 from using up all available space on a server and preventing use by 792 others. Clients MUST treat annotation data values as an "untrusted" 793 source of data as it is possible for it to contain malicious content. 795 Annotations whose values are intended to remain private MUST be 796 stored only in entries that have the "/private" prefix on the entry 797 name. Servers MUST ensure that /private annotations are only visible 798 to the user that created them. 800 Excluding the above issues the METADATA extension does not raise any 801 security considerations that are not present in the base IMAP 802 protocol, and these issues are discussed in [RFC3501]. 804 8. Normative References 806 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 807 Requirement Levels", BCP 14, RFC 2119, March 1997. 809 [RFC2244] Newman, C. and J. Myers, "ACAP -- Application 810 Configuration Access Protocol", RFC 2244, November 1997. 812 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 813 4rev1", RFC 3501, March 2003. 815 [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 816 ABNF", RFC 4466, April 2006. 818 [RFC5161] Gulbrandsen, A. and A. Melnikov, "The IMAP ENABLE 819 Extension", RFC 5161, March 2008. 821 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 822 Specifications: ABNF", STD 68, RFC 5234, January 2008. 824 Appendix A. Acknowledgments 826 The ideas expressed in this document are based on the message 827 annotation document that was co-authored by Randall Gellens. The 828 participants of the IMAPext working group made significant 829 contributions to this work. 831 Appendix B. Change History (to be removed prior to publication as an 832 RFC) 834 Changes from -14 to -15: 835 1. Addressed minor issues from Gen-ART review on -12 version. 836 2. Removed comparator paragraph - no need to specify how the server 837 does its comparisons. 838 3. Added MAXSIZE GETMETADATA option. 839 4. Added DEPTH GETMETADATA option. 840 5. Additional restriction on entry name octet values added. 841 6. Added text about access restrictions for server annotations. 843 Changes from -13 to -14: 844 1. Add statement that no annotations are set when any one fails in a 845 single SETMETADATA command. 846 2. Make unsolicited responses a MUST when ENABLE is used, but make 847 support for ENABLE METADATA optional so servers aren't required 848 to do unsolicited responses. This required a new capbility for 849 the unsolicited behavior. 850 3. Re-ordered Security considerations paragraphs and added 851 additional text about the possibility of malicious content in 852 data values. [SECDIR suggestion] 853 4. Reworded "all users" to "authorized users" in appropriate places. 854 [SECDIR suggestion] 855 5. Added addition text to Security considerations about the need for 856 servers to keep /private annotations private to the user that 857 created them. [SECDIR suggestion] 858 6. Added comment that string values can be multi-line and that CRLF 859 must be the line end indicator. Also changes one example to be 860 multi-line. [SECDIR suggestion] 862 Changes from -12 to -13: 863 1. Major changes to simplify things. 864 2. Removed dependency on LISTEXT - GETMETADATA now used to get 865 annotations on mailboxes. 866 3. Changed data model to remove attributes - annotations are now 867 only entry-value pairs. 868 4. Removed all wildcard behavior on entry names. 869 5. Cut down the registered annotations to only a few essential ones. 871 Changes from -11 to -12: 872 1. Allow server annotations to be used without mailbox annotations. 873 2. Require i;unicode-casemap when COMPARATOR is not present. 874 3. Use ENABLE to turn on unsolicited responses. 875 4. Use formal syntax elements from SORT/THREAD extensions to define 876 the values for /sort and /thread entries. 877 5. Added a comment that use of IDLE is preferred even when /check 878 is true. 879 6. Use formal syntax element from base spec for the /size value. 880 7. Removed IANA registration for attributes as we don't expect any 881 more to be defined. 882 8. Tweaked IANA registration template to be more compact and add 883 RFC Number reference. 884 9. Some minor re-phrasing was done. 885 10. Added text about handling of annotations on INBOX when it is 886 renamed. 887 11. Require a BAD response when an unknown collation is used in 888 LISTEXT selection option. 890 Changes from -10 to -11: 891 1. Added new paragraph to indicate that values may be read-only or 892 computed. 893 2. /admin server annotation value now must be a URI. 894 3. Clarified that SORT and THREAD extensions are not required. 895 4. Fixed use of undefined entries in some examples. 896 5. Fixed many examples. 897 6. Added IANA registration for LIST-EXTENDED items. 898 7. Added match type and collation identifier to the LIST-EXTENDED 899 selection option. 900 8. Made support for IMAP-I18N a requirement. 901 9. Minor text clarifications applied. 902 10. Remove mailbox list set atomicity requirement. 903 11. Clarified that annotations can only be set on mailboxes that 904 actually exist. 906 Changes from -09 to -10: 907 1. Updated to rfc 4466 reference. 909 2. Reworded data model description. 910 3. Reworked LIST-EXTENDED so that responses have metadata items 911 after the mailbox info. 912 4. Various spelling fixes. 914 Changes from -08 to -09: 915 1. Remove content-language attribute and reference. 916 2. Changed capability and command names. 917 3. Revised abstract. 919 Changes from -07 to -08: 920 1. Changed 'string' formal syntax to 'list-mailbox' and 'astring' 921 for entry/attribute names. 922 2. Updated examples to match new astring syntax. 923 3. Changed CAPABILITY name due to incompatible syntax change. 924 4. Removed content-type attribute. 925 5. Added Content-type to IANA registration for entries. 926 6. Removed vendor attributes. 927 7. Fixed examples in section 3.3 for multi-mailbox and multi-entry 928 cases. 929 8. Removed wildcards for attributes. 930 9. Entry/attributes can now only be ASCII. 931 10. Tied up text wrt storing/fetching. 932 11. Added Conventions section 933 12. Entry/attributes MUST NOT contain consecutive or trailing '/' or 934 '.'. 935 13. Changed to use IMAP ABNF extensions document for some formal 936 syntax items. 938 Changes from -06 to -07: 939 1. Reworded /checkperiod item. 940 2. Clarified unsolicited response behavior. 942 Changes from -05 to -06: 943 1. Removed 'modifiedsince' attribute as there is currently no use 944 for it. 945 2. Added content-language attribute. 946 3. Changed access to allow .priv and .shared on any mailbox returned 947 by LIST/LSUB. 948 4. Added IANA registrations for items defined in this document. 949 5. Added latest IPR statement. 950 6. Updated references. 952 Changes from -04 to -05: 953 1. Fix for valid IMAP state of commands. 954 2. Fix formatting, ID nits etc. 956 Changes from -03 to -04: 958 1. Allow retrieval of shared annotations for READ-ONLY mailbox. 959 2. Clarification of annotation loss on implicit removal of \Noselect 960 mailboxes. 961 3. Now requires roll-back of all changes to matching mailboxes if 962 there is a partial failure in SETANNOTATION. 964 Changes from -02 to -03: 965 1. Reworked entry naming scheme to split out mailbox name and use 966 empty string for server items. 968 Changes from -01 to -02: 969 1. SETANNOTATION lists use (..). 970 2. Explicitly state behavior of unsolicited responses. 971 3. Adding SHOULD behavior for rename/delete of mailboxes. 972 4. Added statement about supporting annotations on \Noselect 973 mailboxes. 974 5. Cleaned up formal syntax to use IMAP string type for entry and 975 attributes, with requirements on how the string is formatted. 976 6. Use of ACAP vendor subtree registry for vendor tokens. 978 Changes from -00 to -01: 979 1. Multiple entry-att responses are now simply delimited by spaces 980 in line with ANNOTATE spec. Adjusted examples to match. 981 2. Fixed entry-list formal syntax item to account for unsolicited 982 parenthesized list of entries. 983 3. Removed setentries formal syntax item for simplicity since its 984 only used once. 985 4. Removed reference to 'message annotation' in section 5.1. 986 5. Changed formal syntax to restrict top level entries to /server 987 and /mailbox/{...} only. Re-arranged entry names section to 988 account for this change. 989 6. Added comment and example for ANNOTATION response to allow 990 servers to return separate responses for each entry if desired. 992 Author's Address 994 Cyrus Daboo 995 Apple Inc. 996 1 Infinite Loop 997 Cupertino, CA 95014 998 USA 1000 Email: cyrus@daboo.name 1001 URI: http://www.apple.com/ 1003 Full Copyright Statement 1005 Copyright (C) The IETF Trust (2008). 1007 This document is subject to the rights, licenses and restrictions 1008 contained in BCP 78, and except as set forth therein, the authors 1009 retain all their rights. 1011 This document and the information contained herein are provided on an 1012 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1013 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1014 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1015 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1016 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1017 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1019 Intellectual Property 1021 The IETF takes no position regarding the validity or scope of any 1022 Intellectual Property Rights or other rights that might be claimed to 1023 pertain to the implementation or use of the technology described in 1024 this document or the extent to which any license under such rights 1025 might or might not be available; nor does it represent that it has 1026 made any independent effort to identify any such rights. Information 1027 on the procedures with respect to rights in RFC documents can be 1028 found in BCP 78 and BCP 79. 1030 Copies of IPR disclosures made to the IETF Secretariat and any 1031 assurances of licenses to be made available, or the result of an 1032 attempt made to obtain a general license or permission for the use of 1033 such proprietary rights by implementers or users of this 1034 specification can be obtained from the IETF on-line IPR repository at 1035 http://www.ietf.org/ipr. 1037 The IETF invites any interested party to bring to its attention any 1038 copyrights, patents or patent applications, or other proprietary 1039 rights that may cover technology that may be required to implement 1040 this standard. Please address the information to the IETF at 1041 ietf-ipr@ietf.org.