idnits 2.17.1 draft-daboo-imap-annotatemore-16.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 1035. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1046. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1053. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1059. 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 (November 18, 2008) is 5628 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 521, 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 November 18, 2008 5 Expires: May 22, 2009 7 IMAP METADATA Extension 8 draft-daboo-imap-annotatemore-16 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 May 22, 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 . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . 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 . . . . . . . . . . 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 "/public" 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 ("/public") 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 3.2.1. Entry Names 181 Entry names MUST be specified in a standards track or IESG approved 182 experimental RFC, or fall under the vendor namespace. See 183 Section 6.1 for the registration template. 185 3.2.1.1. Server Entries 187 These entries are set or retrieved when the mailbox name argument to 188 the new SETMETADATA or GETMETATDATA commands is the empty string. 190 /public/comment 191 Defines a comment or note associated with the server shared with 192 authorized users of the server. 194 /public/admin 195 Indicates a method for contacting the server administrator. The 196 value MUST be a URI (e.g., a mailto: or tel: URL). This entry is 197 always read-only - clients cannot change it. It is visible to 198 authorized users of the system. 200 /public/vendor/ 201 Defines the top-level of public entries associated with the server 202 as created by a particular product of some vendor. This entry can 203 be used by vendors to provide server or client specific 204 annotations. The vendor-token MUST be registered with IANA, using 205 the ACAP [RFC2244] vendor subtree registry. 207 /private/vendor/ 208 Defines the top-level of private entries associated with the 209 server as created by a particular product of some vendor. This 210 entry can be used by vendors to provide server or client specific 211 annotations. The vendor-token MUST be registered with IANA, using 212 the ACAP [RFC2244] vendor subtree registry. 214 3.2.1.2. Mailbox Entries 216 These entries are set or retrieved when the mailbox name argument to 217 the new SETMETADATA or GETMETADATA commands is not the empty string. 219 /public/comment 220 Defines a public comment or note associated with a mailbox. 222 /private/comment 223 Defines a private (per-user) comment or note associated with a 224 mailbox. 226 /public/vendor/ 227 Defines the top-level of public entries associated with a specific 228 mailbox as created by a particular product of some vendor. This 229 entry can be used by vendors to provide client specific 230 annotations. The vendor-token MUST be registered with IANA, using 231 the ACAP [RFC2244] vendor subtree registry. 233 /private/vendor/ 234 Defines the top-level of private entries associated with a 235 specific mailbox as created by a particular product of some 236 vendor. This entry can be used by vendors to provide client 237 specific annotations. The vendor-token MUST be registered with 238 IANA, using the ACAP [RFC2244] vendor subtree registry. 240 3.3. Private versus Public and Access Control 242 In the absence of the ACL extension [RFC4314], users can only set and 243 retrieve private or public mailbox annotations on a mailbox which 244 exists and is returned to them via a LIST or LSUB command, and on 245 which they have either read or write access to the actual message 246 content of the mailbox (as determined by the READ-ONLY and READ-WRITE 247 response codes as described in Section 5.2 of [RFC4314]). 249 When the ACL extension [RFC4314] is present, users can only set and 250 retrieve private or public mailbox annotations on a mailbox on which 251 they have the "l" right, and any one of the "r", "s", "w", "i" or "p" 252 rights. 254 If a client attempts to set or retrieve annotations on mailboxes 255 which do not satisfy the conditions above, the server MUST respond 256 with a NO response. 258 Users can always retrieve private or public server annotations if 259 they exist. Servers MAY restrict the creation of private or public 260 server annotations as appropriate. When restricted, the server MUST 261 return a NO response when the SETMETADATA command is used to try and 262 create a server annotation. 264 If the METADATA extension is present, support for public annotations 265 is REQUIRED, whilst support for private annotations is OPTIONAL. 266 This recognizes the fact that support for private annotations may 267 introduce significantly more complexity to a server in terms of 268 tracking ownership of the annotations, how quota is determined for 269 users based on their own annotations etc. 271 4. IMAP Protocol Changes 273 4.1. General Considerations 275 The new SETMETADATA command and the METADATA response each have a 276 mailbox name argument. An empty string is used for the mailbox name 277 to signify server annotations. A non-empty string is used to signify 278 mailbox annotations attached to the corresponding mailbox. 280 Servers SHOULD ensure that mailbox annotations are automatically 281 moved when the mailbox they refer to is renamed, i.e., the 282 annotations follow the mailbox. This applies to a rename of the 283 INBOX, with the additional behavior that the annotations are copied 284 from the original INBOX to the renamed mailbox. i.e., mailbox 285 annotations are preserved on the INBOX when it is renamed. 287 Servers SHOULD delete annotations for a mailbox when the mailbox is 288 deleted, so that a mailbox created with the same name as a previously 289 existing mailbox does not inherit the old mailbox annotations. 291 Servers SHOULD allow annotations on all 'types' of mailbox, including 292 ones reporting \Noselect for their LIST response. Servers can 293 implicitly remove \Noselect mailboxes when all child mailboxes are 294 removed, and as such any annotations associated with the \Noselect 295 mailbox SHOULD be removed. 297 The server is allowed to impose limitations on the size of any one 298 annotation or the total number of annotations for a single mailbox or 299 for the server as a whole. However, the server MUST accept a minimum 300 annotation data size of at least 1024 bytes, and a minimum annotation 301 count per server or mailbox of at least 10. 303 Some annotations may be "read-only" - i.e., they are set by the 304 server and cannot be changed by the client. Also, such annotations 305 may be "computed" - i.e., the value changes based on underlying 306 properties of the mailbox or server. For example, an annotation 307 reporting the total size of all messages in the mailbox would change 308 as messages are added or removed. Or, an annotation containing an 309 IMAP URL for the mailbox would change if the mailbox was renamed. 311 Servers MAY support sending unsolicited responses for use when 312 annotations are changed by some "third-party" (see Section 4.4). In 313 order to do so servers MUST support the ENABLE command [RFC5161] and 314 MUST only send unsolicited responses if the client uses the ENABLE 315 command [RFC5161] extension with the capability string "METADATA" or 316 "METADATA-SERVER" earlier in the session, depending on which of those 317 capabilities is supported by the server. 319 4.2. GETMETADATA Command 321 This extension adds the GETMETADATA command. This allows clients to 322 retrieve server or mailbox annotations. 324 This command is only available in authenticated or selected state 325 [RFC3501]. 327 Arguments: mailbox-name 328 options 329 entry-specifier 331 Responses: required METADATA response 333 Result: OK - command completed 334 NO - command failure: can't access annotations on 335 the server 336 BAD - command unknown or arguments invalid 338 When the mailbox name is the empty string, this command retrieves 339 server annotations. When the mailbox name is not empty, this command 340 retrieves annotations on the specified mailbox. 342 Options MAY be included with this command and are defined below. 344 Example: 346 C: a GETMETADATA "" /public/comment 347 S: * METADATA "" (/public/comment "Shared comment") 348 S: a OK GETMETADATA complete 350 In the above example, the contents of the value of the "/public/ 351 comment" server entry is requested by the client and returned by 352 the server. 354 Example: 356 C: a GETMETADATA "INBOX" /private/comment 357 S: * METADATA "INBOX" (/private/comment "My own comment") 358 S: a OK GETMETADATA complete 360 In the above example, the contents of the value of the "/private/ 361 comment" mailbox entry for the mailbox "INBOX" is requested by the 362 client and returned by the server. 364 Entry specifiers can be lists of atomic specifiers, so that multiple 365 annotations may be returned in a single GETMETADATA command. 367 Example: 369 C: a GETMETADATA "INBOX" (/public/comment /private/comment) 370 S: * METADATA "INBOX" (/public/comment "Shared comment" 371 /private/comment "My own comment") 372 S: a OK GETMETADATA complete 374 In the above example, the values of the two server entries 375 "/public/comment" and "/private/comment" on the mailbox "inbox" 376 are requested by the client and returned by the server. 378 4.2.1. MAXSIZE GETMETADATA Command Option 380 When MAXSIZE option is specified with the GETMETADATA command, it 381 restricts which entry values are returned by the server. Only entry 382 values which are less than or equal in octet size to the specified 383 MAXSIZE limit are returned. If there are any entries with values 384 larger than the MAXSIZE limit, the server MUST include the METADATA 385 LONGENTRIES response code in the tagged OK response for the 386 GETMETADATA command. The METADATA LONGENTRIES response code returns 387 the size of the biggest entry value requested by the client which 388 exceeded the MAXSIZE limit. 390 Example: 392 C: a GETMETADATA "INBOX" (MAXSIZE 1024) 393 (/public/comment /private/comment) 394 S: * METADATA "INBOX" (/private/comment "My own comment") 395 S: a OK [METADATA LONGENTRIES 2199] GETMETADATA complete 397 In the above example, the values of the two server entries 398 "/public/comment" and "/private/comment" on the mailbox "inbox" 399 are requested by the client which wants to restrict the size of 400 returned values to 1024 octets. In this case the "/public/ 401 comment" entry value is 2199 octets and is not returned. 403 4.2.2. DEPTH GETMETADATA Command Option 405 When DEPTH option is specified with the GETMETADATA command, it 406 extends the list of entry values returned by the server. For each 407 entry name specified in the GETMETADATA command, the server returns 408 the value of the specified entry name (if it exists), plus all 409 entries below the entry name up to the specified DEPTH. Three values 410 are allowed for DEPTH: 412 "0" - no entries below the specified entry are returned 413 "1" - only entries immediately below the specified entry are 414 returned 415 "infinity" - all entries below the specified entry are returned 416 Thus, "depth 1" for an entry "/a" will match "/a" as well as its 417 children entries (e.g. "/a/b"), but will not match grandchildren 418 entries (e.g. "/a/b/c"). 420 If the DEPTH option is not specified, this is the same as specifying 421 "DEPTH 0". 423 Example: 425 C: a GETMETADATA "INBOX" (DEPTH 1) 426 (/private/filters/values) 427 S: * METADATA "INBOX" (/private/filters/values/small 428 "SMALLER 5000" /private/filters/values/boss 429 "FROM \"boss@example.com\"") 430 S: a OK GETMETADATA complete 432 In the above example, 2 entries below the /private/filters/values 433 entry exist on the mailbox "INBOX": "/private/filters/values/ 434 small" and "/private/filters/values/boss". 436 4.3. SETMETADATA Command 438 This extension adds the SETMETADATA command. This allows clients to 439 set annotations. 441 This command is only available in authenticated or selected state 442 [RFC3501]. 444 Arguments: mailbox-name 445 entry 446 value 447 list of entry, values 449 Responses: no specific responses for this command 451 Result: OK - command completed 452 NO - command failure: can't set annotations, 453 or annotation too big or too many 454 BAD - command unknown or arguments invalid 456 This command sets the specified list of entries by adding or 457 replacing the specified values provided, on the specified existing 458 mailboxes or on the server (if the mailbox argument is the empty 459 string). Clients can use NIL for the value of entries it wants to 460 remove. The server SHOULD NOT return a METADATA response containing 461 the updated annotation data. Clients MUST NOT assume that a METADATA 462 response will be sent, and MUST assume that if the command succeeds 463 then the annotation has been changed. 465 If the server is unable to set an annotation because the size of its 466 value is too large, the server MUST return a tagged NO response with 467 a "[METADATA MAXSIZE NNN]" response code when NNN is the maximum 468 octet count that it is willingly to accept. 470 If the server is unable to set a new annotation because the maximum 471 number of allowed annotations has already been reached, the server 472 MUST return a tagged NO response with a "[METADATA TOOMANY]" response 473 code. 475 If the server is unable to set a new annotation because it does not 476 support private annotations on one of the specified mailboxes, the 477 server MUST return a tagged NO response with a "[METADATA NOPRIVATE]" 478 response code. 480 When any one annotation fails to be set, resulting in a tagged NO 481 response from the server, then the server MUST NOT change the values 482 for other annotations specified in the SETMETADATA command. 484 Example: 486 C: a SETMETADATA INBOX (/private/comment {33} 487 S: + ready for data 488 My new comment across 489 two lines. 490 ) 491 S: a OK SETMETADATA complete 493 In the above example, the entry "/private/comment" for the mailbox 494 "INBOX" is created (if not already present) and the value set to a 495 multi-line string. 497 Example: 499 C: a SETMETADATA INBOX (/private/comment NIL) 500 S: a OK SETMETADATA complete 502 In the above example, the entry "/private/comment" is removed from 503 the mailbox "INBOX". 505 Multiple entries can be set in a single SETMETADATA command by 506 listing entry-value pairs in the list. 508 Example: 510 C: a SETMETADATA INBOX (/private/comment "My new comment" 511 /public/comment "This one is for you!") 512 S: a OK SETMETADATA complete 514 In the above example, the entries "/private/comment" and "/public/ 515 comment" for the mailbox "INBOX" are created (if not already 516 present) and the values set as specified. 518 Example: 520 C: a SETMETADATA INBOX (/private/comment "My new comment") 521 S: a NO [METADATA TOOMANY] SETMETADATA failed 523 In the above example, the server is unable to set the requested 524 (new) annotation as it has reached the limit on the number of 525 annotations it can support on the specified mailbox. 527 4.4. METADATA Response 529 The METADATA response displays results of a GETMETADATA command, or 530 can be returned as an unsolicited response at anytime by the server 531 in response to a change in a server or mailbox annotation. 533 When unsolicited responses are activated by the ENABLE [RFC5161] 534 command for this extension, servers MUST send unsolicited METADATA 535 responses if server or mailbox annotations are changed by a third- 536 party, allowing servers to keep clients updated with changes. 538 Unsolicited METADATA responses MUST only contain entry names, not the 539 values. If the client wants to update any cached values it must 540 explicitly retrieve those using a GETMETADATA command. 542 The METADATA response can contain multiple entries in a single 543 response, but the server is free to return multiple responses for 544 each entry or group of entries if it desires. 546 This response is only available in authenticated or selected state 547 [RFC3501]. 549 4.4.1. METADATA response with values 551 The response consists of a list of entry-value pairs. 553 Example: 555 C: a GETMETADATA "" /public/comment 556 S: * METADATA "" (/public/comment "My comment") 557 S: a OK GETMETADATA complete 559 In the above example, a single entry with its value is returned by 560 the server. 562 Example: 564 C: a GETMETADATA "INBOX" /private/comment /public/comment 565 S: * METADATA "INBOX" (/private/comment "My comment" 566 /public/comment "Its sunny outside!") 567 S: a OK GETMETADATA complete 569 In the above example, two entries and their values are returned by 570 the server. 572 Example: 574 C: a GETMETADATA "INBOX" /private/comment /public/comment 575 S: * METADATA "INBOX" (/private/comment "My comment") 576 S: * METADATA "INBOX" (/public/comment "Its sunny outside!") 577 S: a OK GETMETADATA complete 579 In the above example, the server returns two separate responses 580 for each of the two entries requested. 582 4.4.2. Unsolicited METADATA response without values 584 The response consists of a list of entries, each of which have 585 changed on the server or mailbox. 587 Example: 589 C: a NOOP 590 S: * METADATA "" /public/comment 591 S: a OK NOOP complete 593 In the above example, the server indicates that the "/public/ 594 comment" server entry has been changed. 596 Example: 598 C: a NOOP 599 S: * METADATA "INBOX" /public/comment /private/comment 600 S: a OK NOOP complete 602 In the above example, the server indicates a change to two mailbox 603 entries. 605 5. Formal Syntax 607 The following syntax specification uses the Augmented Backus-Naur 608 Form (ABNF) notation as specified in [RFC5234]. 610 Non-terminals referenced but not defined below are as defined by 611 [RFC3501] with the new definitions in [RFC4466] superseding those in 612 [RFC3501]. 614 Except as noted otherwise, all alphabetic characters are case- 615 insensitive. The use of upper or lower case characters to define 616 token strings is for editorial clarity only. Implementations MUST 617 accept these strings in a case-insensitive fashion. 619 capability =/ "METADATA" / "METADATA-SERVER" / 620 "METADATA-UNSOLICITED" 621 ; defines the capabilities for this extension 623 command-auth =/ setmetadata / getmetadata 624 ; adds to original IMAP command 626 entries = entry / 627 "(" entry *(SP entry) ")" 628 ; entry specifiers 630 entry = astring 631 ; slash-separated path to entry 632 ; MUST NOT contain "*" or "%" 634 entry-value = entry SP value 636 entry-values = "(" entry-value *(SP entry-value) ")" 638 entry-list = entry *(SP entry) 639 ; list of entries used in unsolicited 640 ; METADATA response 642 getmetadata = "GETMETADATA" [SP getmetadata-options] 643 SP mailbox SP entries 644 ; empty string for mailbox implies 645 ; server annotation. 647 getmetadata-options = "(" getmetadata-option 648 *(SP getmetadata-option) ")" 650 getmetadata-option = tagged-ext-label [SP tagged-ext-val] 651 ; tagged-ext-label, tagged-ext-val are 652 ; defined in [RFC4466]. 654 maxsize-opt = "MAXSIZE" SP number 655 ; Used as a getmetadata-option 657 metadata-resp = "METADATA" SP mailbox SP 658 (entry-values / entry-list) 659 ; empty string for mailbox implies 660 ; server annotation. 662 response-payload =/ metadata-resp 663 ; adds to original IMAP data responses 665 resp-text-code =/ "METADATA" SP "LONGENTRIES" SP number 666 ; new response codes for GETMETADATA 668 resp-text-code =/ "METADATA" SP ("MAXSIZE" SP number / 669 "TOOMANY" / "NOPRIVATE") 670 ; new response codes for SETMETADATA 671 ; failures 673 scope-opt = "DEPTH" SP ("0" / "1" / "infinity") 674 ; Used as a getmetadata-option 676 setmetadata = "SETMETADATA" SP mailbox 677 SP entry-values 678 ; empty string for mailbox implies 679 ; server annotation. 681 value = nstring / literal8 683 6. IANA Considerations 685 Entry names MUST be specified in a standards track or IESG approved 686 experimental RFC, or fall under the vendor namespace. All entries 687 MUST have either "/public" or "/private" as a prefix. 689 Each entry registration MUST include a content-type that is used to 690 indicate the nature of the annotation value. Where applicable a 691 charset parameter MUST be included with the content-type. 693 6.1. Entry and Attribute Registration Template 695 To: iana@iana.org 696 Subject: IMAP METADATA Entry Registration 698 Type: [Either "Mailbox" or "Server"] 700 Name: [the name of the entry] 702 Description: [a description of what the entry is for] 704 Content-type: [MIME Content-Type and charset for the entry value] 706 RFC Number: [for entries published as RFCs] 708 Contact: [email and/or physical address to contact for 709 additional information] 711 6.2. Server Entry Registrations 713 The following templates specify the IANA registrations of annotation 714 entries specified in this document. 716 6.2.1. /public/comment 718 To: iana@iana.org 719 Subject: IMAP METADATA Entry Registration 721 Type: Server 723 Name: /public/comment 725 Description: Defines a comment or note associated with the 726 server shared with authorized users of the server. 728 Content-type: text/plain; charset=utf-8 730 RFC Number: This RFC. 732 Contact: IMAP Extensions mailto:ietf-imapext@imc.org 734 6.2.2. /public/admin 736 To: iana@iana.org 737 Subject: IMAP METADATA Entry Registration 739 Type: Server 741 Name: /public/admin 743 Description: Indicates a method for contacting the server 744 administrator. The value MUST be a URI (e.g., a 745 mailto: or tel: URL). This entry is always 746 read-only - clients cannot change it. It is visible 747 to authorized users of the system. 749 Content-type: text/plain; charset=utf-8 751 RFC Number: This RFC. 753 Contact: IMAP Extensions mailto:ietf-imapext@imc.org 755 6.3. Mailbox Entry Registrations 757 The following templates specify the IANA registrations of annotation 758 entries specified in this document. 760 6.3.1. /public/comment 762 To: iana@iana.org 763 Subject: IMAP METADATA Entry Registration 765 Type: Mailbox 767 Name: /public/comment 769 Description: Defines a public comment or note associated with a 770 mailbox. 772 Content-type: text/plain; charset=utf-8 774 RFC Number: This RFC. 776 Contact: IMAP Extensions mailto:ietf-imapext@imc.org 778 6.3.2. /private/comment 780 To: iana@iana.org 781 Subject: IMAP METADATA Entry Registration 783 Type: Mailbox 785 Name: /private/comment 787 Description: Defines a private comment or note associated with a 788 mailbox. 790 Content-type: text/plain; charset=utf-8 792 RFC Number: This RFC. 794 Contact: IMAP Extensions mailto:ietf-imapext@imc.org 796 7. Security Considerations 798 Annotations can contain arbitrary data of varying size. As such 799 servers MUST ensure that size limits are enforced to prevent a user 800 from using up all available space on a server and preventing use by 801 others. Clients MUST treat annotation data values as an "untrusted" 802 source of data as it is possible for it to contain malicious content. 804 Annotations whose values are intended to remain private MUST be 805 stored only in entries that have the "/private" prefix on the entry 806 name. Servers MUST ensure that /private annotations are only visible 807 to the user that created them. 809 Excluding the above issues the METADATA extension does not raise any 810 security considerations that are not present in the base IMAP 811 protocol, and these issues are discussed in [RFC3501]. 813 8. Normative References 815 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 816 Requirement Levels", BCP 14, RFC 2119, March 1997. 818 [RFC2244] Newman, C. and J. Myers, "ACAP -- Application 819 Configuration Access Protocol", RFC 2244, November 1997. 821 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 822 4rev1", RFC 3501, March 2003. 824 [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", 825 RFC 4314, December 2005. 827 [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 828 ABNF", RFC 4466, April 2006. 830 [RFC5161] Gulbrandsen, A. and A. Melnikov, "The IMAP ENABLE 831 Extension", RFC 5161, March 2008. 833 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 834 Specifications: ABNF", STD 68, RFC 5234, January 2008. 836 Appendix A. Acknowledgments 838 The ideas expressed in this document are based on the message 839 annotation document that was co-authored by Randall Gellens. The 840 participants of the IMAPext working group made significant 841 contributions to this work. 843 Appendix B. Change History (to be removed prior to publication as an 844 RFC) 846 Changes from -15 to -16: 847 1. Tweaked enable capability behavior. 848 2. Changed access control text to be more explicit about which ACL 849 privileges are required. 851 Changes from -14 to -15: 852 1. Addressed minor issues from Gen-ART review on -12 version. 853 2. Removed comparator paragraph - no need to specify how the server 854 does its comparisons. 855 3. Added MAXSIZE GETMETADATA option. 856 4. Added DEPTH GETMETADATA option. 857 5. Additional restriction on entry name octet values added. 858 6. Added text about access restrictions for server annotations. 860 Changes from -13 to -14: 861 1. Add statement that no annotations are set when any one fails in a 862 single SETMETADATA command. 863 2. Make unsolicited responses a MUST when ENABLE is used, but make 864 support for ENABLE METADATA optional so servers aren't required 865 to do unsolicited responses. This required a new capbility for 866 the unsolicited behavior. 867 3. Re-ordered Security considerations paragraphs and added 868 additional text about the possibility of malicious content in 869 data values. [SECDIR suggestion] 871 4. Reworded "all users" to "authorized users" in appropriate places. 872 [SECDIR suggestion] 873 5. Added addition text to Security considerations about the need for 874 servers to keep /private annotations private to the user that 875 created them. [SECDIR suggestion] 876 6. Added comment that string values can be multi-line and that CRLF 877 must be the line end indicator. Also changes one example to be 878 multi-line. [SECDIR suggestion] 880 Changes from -12 to -13: 881 1. Major changes to simplify things. 882 2. Removed dependency on LISTEXT - GETMETADATA now used to get 883 annotations on mailboxes. 884 3. Changed data model to remove attributes - annotations are now 885 only entry-value pairs. 886 4. Removed all wildcard behavior on entry names. 887 5. Cut down the registered annotations to only a few essential ones. 889 Changes from -11 to -12: 890 1. Allow server annotations to be used without mailbox annotations. 891 2. Require i;unicode-casemap when COMPARATOR is not present. 892 3. Use ENABLE to turn on unsolicited responses. 893 4. Use formal syntax elements from SORT/THREAD extensions to define 894 the values for /sort and /thread entries. 895 5. Added a comment that use of IDLE is preferred even when /check 896 is true. 897 6. Use formal syntax element from base spec for the /size value. 898 7. Removed IANA registration for attributes as we don't expect any 899 more to be defined. 900 8. Tweaked IANA registration template to be more compact and add 901 RFC Number reference. 902 9. Some minor re-phrasing was done. 903 10. Added text about handling of annotations on INBOX when it is 904 renamed. 905 11. Require a BAD response when an unknown collation is used in 906 LISTEXT selection option. 908 Changes from -10 to -11: 909 1. Added new paragraph to indicate that values may be read-only or 910 computed. 911 2. /admin server annotation value now must be a URI. 912 3. Clarified that SORT and THREAD extensions are not required. 913 4. Fixed use of undefined entries in some examples. 914 5. Fixed many examples. 915 6. Added IANA registration for LIST-EXTENDED items. 916 7. Added match type and collation identifier to the LIST-EXTENDED 917 selection option. 919 8. Made support for IMAP-I18N a requirement. 920 9. Minor text clarifications applied. 921 10. Remove mailbox list set atomicity requirement. 922 11. Clarified that annotations can only be set on mailboxes that 923 actually exist. 925 Changes from -09 to -10: 926 1. Updated to rfc 4466 reference. 927 2. Reworded data model description. 928 3. Reworked LIST-EXTENDED so that responses have metadata items 929 after the mailbox info. 930 4. Various spelling fixes. 932 Changes from -08 to -09: 933 1. Remove content-language attribute and reference. 934 2. Changed capability and command names. 935 3. Revised abstract. 937 Changes from -07 to -08: 938 1. Changed 'string' formal syntax to 'list-mailbox' and 'astring' 939 for entry/attribute names. 940 2. Updated examples to match new astring syntax. 941 3. Changed CAPABILITY name due to incompatible syntax change. 942 4. Removed content-type attribute. 943 5. Added Content-type to IANA registration for entries. 944 6. Removed vendor attributes. 945 7. Fixed examples in section 3.3 for multi-mailbox and multi-entry 946 cases. 947 8. Removed wildcards for attributes. 948 9. Entry/attributes can now only be ASCII. 949 10. Tied up text wrt storing/fetching. 950 11. Added Conventions section 951 12. Entry/attributes MUST NOT contain consecutive or trailing '/' or 952 '.'. 953 13. Changed to use IMAP ABNF extensions document for some formal 954 syntax items. 956 Changes from -06 to -07: 957 1. Reworded /checkperiod item. 958 2. Clarified unsolicited response behavior. 960 Changes from -05 to -06: 961 1. Removed 'modifiedsince' attribute as there is currently no use 962 for it. 963 2. Added content-language attribute. 964 3. Changed access to allow .priv and .shared on any mailbox returned 965 by LIST/LSUB. 967 4. Added IANA registrations for items defined in this document. 968 5. Added latest IPR statement. 969 6. Updated references. 971 Changes from -04 to -05: 972 1. Fix for valid IMAP state of commands. 973 2. Fix formatting, ID nits etc. 975 Changes from -03 to -04: 976 1. Allow retrieval of shared annotations for READ-ONLY mailbox. 977 2. Clarification of annotation loss on implicit removal of \Noselect 978 mailboxes. 979 3. Now requires roll-back of all changes to matching mailboxes if 980 there is a partial failure in SETANNOTATION. 982 Changes from -02 to -03: 983 1. Reworked entry naming scheme to split out mailbox name and use 984 empty string for server items. 986 Changes from -01 to -02: 987 1. SETANNOTATION lists use (..). 988 2. Explicitly state behavior of unsolicited responses. 989 3. Adding SHOULD behavior for rename/delete of mailboxes. 990 4. Added statement about supporting annotations on \Noselect 991 mailboxes. 992 5. Cleaned up formal syntax to use IMAP string type for entry and 993 attributes, with requirements on how the string is formatted. 994 6. Use of ACAP vendor subtree registry for vendor tokens. 996 Changes from -00 to -01: 997 1. Multiple entry-att responses are now simply delimited by spaces 998 in line with ANNOTATE spec. Adjusted examples to match. 999 2. Fixed entry-list formal syntax item to account for unsolicited 1000 parenthesized list of entries. 1001 3. Removed setentries formal syntax item for simplicity since its 1002 only used once. 1003 4. Removed reference to 'message annotation' in section 5.1. 1004 5. Changed formal syntax to restrict top level entries to /server 1005 and /mailbox/{...} only. Re-arranged entry names section to 1006 account for this change. 1007 6. Added comment and example for ANNOTATION response to allow 1008 servers to return separate responses for each entry if desired. 1010 Author's Address 1012 Cyrus Daboo 1013 Apple Inc. 1014 1 Infinite Loop 1015 Cupertino, CA 95014 1016 USA 1018 Email: cyrus@daboo.name 1019 URI: http://www.apple.com/ 1021 Full Copyright Statement 1023 Copyright (C) The IETF Trust (2008). 1025 This document is subject to the rights, licenses and restrictions 1026 contained in BCP 78, and except as set forth therein, the authors 1027 retain all their rights. 1029 This document and the information contained herein are provided on an 1030 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1031 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1032 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1033 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1034 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1035 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1037 Intellectual Property 1039 The IETF takes no position regarding the validity or scope of any 1040 Intellectual Property Rights or other rights that might be claimed to 1041 pertain to the implementation or use of the technology described in 1042 this document or the extent to which any license under such rights 1043 might or might not be available; nor does it represent that it has 1044 made any independent effort to identify any such rights. Information 1045 on the procedures with respect to rights in RFC documents can be 1046 found in BCP 78 and BCP 79. 1048 Copies of IPR disclosures made to the IETF Secretariat and any 1049 assurances of licenses to be made available, or the result of an 1050 attempt made to obtain a general license or permission for the use of 1051 such proprietary rights by implementers or users of this 1052 specification can be obtained from the IETF on-line IPR repository at 1053 http://www.ietf.org/ipr. 1055 The IETF invites any interested party to bring to its attention any 1056 copyrights, patents or patent applications, or other proprietary 1057 rights that may cover technology that may be required to implement 1058 this standard. Please address the information to the IETF at 1059 ietf-ipr@ietf.org.