Network Working Group D. Karp Internet-Draft Zimbra Expires: June 2, 2007 November 29, 2006 The IMAP COMMENT Extension draft-karp-imap-comment-00 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on June 2, 2007. Copyright Notice Copyright (C) The IETF Trust (2006). Abstract The COMMENT extension to the Internet Message Access Protocol [IMAP] permits a client to attach free-form text comments to messages stored in a mailbox on the server. These comments are persistent, public, mutable, readable, and searchable. 1. Conventions Used in This Document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [KEYWORDS]. In examples, "C:" and "S:" indicate lines sent by the client and server respectively. If a single "C:" or "S:" label applies to multiple lines, then the line breaks between those lines are for editorial clarity only and are not part of the actual protocol exchange. 2. Introduction and Overview At present, there is no way for a client to associate an arbitrary mutable text comment with a message in an IMAP mailbox short of altering the message's body. This document specifies an extension to IMAP that permits clients to associate a single optional piece of text metadata with a message. The value of such a comment is a string of one or more octets comprising UTF-8 [UTF8] characters, or NIL when a comment is not set. The syntax for associating comments with messages and retrieving message comments is designed to closely parallel the existing syntax for setting and retrieving mutable message flags. In addition, the same permissions are required for modifying and retrieving comments as are required for setting and fetching keywords. Should the mailbox also support the [CONDSTORE] extension, changes to message comments qualify as mailbox changes and MUST increment the affected message's MODSEQ attribute and the mailbox's HIGHESTMODSEQ attribute. If a server supports comments, then it MUST store all comment data persistently. The server MAY NOT support "session-only" comments along the lines of "session" flags as defined in the IMAP base specification. Comments MUST be shared publicly with all users who have permission to read and write them. In this respect, they behave as "shared flags" as described in section 5.2 of [ACLPLUS]. The server MAY NOT present a different view of message comments to different users with read access on a mailbox. An IMAP server that supports the COMMENT extension MUST return "COMMENT" in its CAPABILITY response. 3. IMAP Protocol Changes 3.1. COMMENT Parameter to SELECT and EXAMINE This document defines a single optional select parameter, "COMMENT", which tells the server that it MUST return changes to message comments in unsolicited FETCH responses (see section 3.2) for the duration of the session. This is the only way to enable COMMENT data in unsolicited FETCH responses; such responses are NOT implicitly enabled by the use of any other command described in this document. The enabling of COMMENT does not carry over from one SELECT/EXAMINE to another within the same IMAP connection. Example: C: A001 SELECT INBOX (COMMENT) S: * 236 EXISTS S: * 0 RECENT S: * OK [UNSEEN 228] S: * OK [UIDVALIDITY 1] S: * OK [UIDNEXT 713] S: * FLAGS (\Answered \Deleted \Draft \Flagged \Seen) S: * OK [PERMANENTFLAGS (\Answered \Deleted \Draft \Flagged \Seen \*)] S: * OK [COMMENT 8096] S: A001 OK [READ-WRITE] SELECT completed, COMMENT enabled This document also adds a new response code, COMMENT. In the course of a successful SELECT or EXAMINE, any server that advertises the COMMENT capability MUST return an untagged OK response containing the COMMENT response code: OK [COMMENT ] where is the maximum length (in octets) of a comment in the mailbox. If the server cannot support comments for the mailbox, MUST be 0. 3.2. COMMENT Message Data Item for the FETCH Command This document adds a COMMENT message data item to the FETCH command. This allows users to retrieve the comments associated with a range of messages in the currently-selected mailbox: Example: C: A002 FETCH 1:2 (UID COMMENT) S: * 1 FETCH (UID 288 COMMENT NIL) S: * 2 FETCH (UID 289 COMMENT "This is the message's comment") S: A002 OK FETCH completed Unsolicited FETCH responses indicating changes in a message's comment MUST include the full new value of the COMMENT message data item. 3.3. COMMENT Message Data Item for the STORE command This document adds new message data items to the STORE command for setting and removing comments on messages in the selected mailbox: COMMENT Replace the comment for the messsage with the argument. The new value of the comment is returned as if a FETCH of the COMMENT had been requested. COMMENT.SILENT Equivalent to COMMENT, but without returning the new value. If CONDSTORE is enabled for the session, an unsolicted response containing the message's new MODSEQ may still be returned. The new comment must be either NIL or a non-empty octet sequence shorter than the maximum comment length as specified in the SELECT response. If the octet sequence is not valid UTF-8, the server MUST return a tagged NO response with a "[BADCOMMENT NOTUTF8]" response code. If the octet sequence exceeds the maximum comment length supported by the mailbox, the server MUST return a tagged NO response with a "[BADCOMMENT TOOBIG]" response code. Example: C: A003 STORE 1 COMMENT "This message now has a comment!" S: * 1 FETCH (COMMENT "This message now has a comment!") S: A003 OK STORE completed C: A004 STORE 2 COMMENT.SILENT NIL S: A004 OK STORE completed 3.4. COMMENT Search Key for the SEARCH Command This document adds a new search key to the SEARCH command for searching within message COMMENTs: COMMENT Messages that contain the specified string in the message's COMMENT. If is zero-length, matches all messages with non-NIL COMMENTs. Example: C: A005 SEARCH COMMENT "comment" S: * SEARCH 1 12 44 156 S: A005 OK SEARCH completed 3.5. COMMENT Extension for the APPEND Command This document adds a new APPEND extension (as per [IMAPABNF]) to allow specification of a comment on an APPENDed message: COMMENT Specifies a comment for the appended message. If the specified comment is not valid UTF-8, the server MUST return a tagged NO response with a "[BADCOMMENT NOTUTF8]" response code. If the specified comment exceeds the maximum comment length supported by the target mailbox of the APPEND, the server MUST return a tagged NO response with a "[BADCOMMENT TOOBIG]" response code. Example: C: A006 APPEND Sent COMMENT "Attached to new message" {14432+} C: ... S: A006 OK APPEND completed 3.6. COMMENT Interaction with the COPY Command When copying a message from one mailbox to another, the server SHOULD attempt to copy the message's comment along with the copied message. If the server is unable to associate the comment with the copied message -- for instance, because it exceeds the maximum comment length in the target mailbox -- it SHOULD create the copy with a NIL comment. 3.7. COMMENT Interaction with the ACL Extension In general, read and write access to comments is governed by the same rules that control read and write access to message flags. When the [ACL] or [ACLPLUS] extensions are not present, users have read-only access to comments when the mailbox is selected READ-ONLY and read-write access to comments when the mailbox is selected READ-WRITE. When the [ACL] or [ACLPLUS] extensions are present, users have read access to comments when they have been granted the "r" right on the mailbox and write access to comments when they have been granted the "w" right on the mailbox. 4. Formal Syntax The following syntax specification uses the Augmented Backus-Naur Form (ABNF) [ABNF] notation. Elements not defined here can be found in the formal syntax of the ABNF [ABNF], UTF-8 [UTF8], IMAP [IMAP4], and IMAP ABNF extensions [IMAPABNF] specifications. Except as noted otherwise, all alphabetic characters are case- insensitive. The use of upper or lower case characters to define token strings is for editorial clarity only. Implementations MUST accept these strings in a case-insensitive fashion. append-ext =/ "COMMENT" SP comment-value capability =/ "COMMENT" comment-value = "NIL" / comment-text comment-text = utf8-quoted / utf8-literal fetch-att =/ "COMMENT" msg-att-dynamic =/ "COMMENT" SP comment-value resp-text-code =/ "BADCOMMENT" SP ("NOTUTF8" / "TOOBIG") / "COMMENT" SP number search-key =/ "COMMENT" string select-param =/ "COMMENT" store-att-flags =/ "COMMENT" [".SILENT"] SP comment-value utf8-quoted = DQUOTE 1*(QUOTED-CHAR) DQUOTE utf8-literal = "{" nz-number ["+"] "}" CRLF 1*(UTF8-char) ; Number represents the octet count 5. References 5.1. Normative References [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", RFC 3501, March 2003. [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 ABNF", RFC 4466, April 2006. [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [UTF8] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. 5.2. Informative References [ACL] Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997. [ACLPLUS] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", RFC 4314, December 2005. [CONDSTORE] Melnikov, A. and S. Hole, "IMAP Extension for Conditional STORE Operation or Quick Flag Changes Resynchronization", RFC 4551, June 2006. Appendix A. Acknowledgments Many thanks to Cyrus Daboo and Randall Gellens for their extensive work developing the ANNNOTATE draft, upon which this draft is based. Author's Address Dan Karp Zimbra 1500 Fashion Island Blvd. Suite 100 San Mateo, CA 94404 USA Email: dkarp@zimbra.com URI: http://www.zimbra.com/ Full Copyright Statement Copyright (C) The IETF Trust (2006). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Acknowledgment Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA).