[Docs] [txt|pdf] [Tracker] [Email] [Nits]
Versions: 00 01 02 03 04 05 06 07 08 09 10 11
12 13 14 15 16 17 RFC 5464
Network Working Group C. Daboo
Internet Draft: IMAP ANNOTATEMORE Extension
Document: draft-daboo-imap-annotatemore-00.txt February 2002
IMAP ANNOTATEMORE Extension
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. 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.
Copyright Notice
Copyright (C) The Internet Society 2002. All Rights Reserved.
Daboo Expires August 2002 [Page 1]
Internet Draft IMAP ANNOTATEMORE Extension February 2002
Table of Contents
1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2 Conventions Used in This Document . . . . . . . . . . . . . 2
3 Open Issues: . . . . . . . . . . . . . . . . . . . . . . . . 2
4 Introduction and Overview . . . . . . . . . . . . . . . . . 3
5 Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 3
5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 3
5.2 Namespace of entries and attributes . . . . . . . . . . . 4
5.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . 4
5.2.2 Attribute Names . . . . . . . . . . . . . . . . . . . 6
6 Private versus Shared and Access Control . . . . . . . . . . 6
7 IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 7
7.1 GETANNOTATION Command . . . . . . . . . . . . . . . . . 7
7.2 SETANNOTATION command . . . . . . . . . . . . . . . . . . 8
7.3 ANNOTATION Response . . . . . . . . . . . . . . . . . . 10
7.3.1 ANNOTATION response with attributes and values . . . 10
7.3.2 Unsolicted ANNOTATION response without attributes and 11
8 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 11
9 IANA Considerations . . . . . . . . . . . . . . . . . . . . 12
9.1 Entry and Attribute Registration Template . . . . . . . . 13
10 Security Considerations . . . . . . . . . . . . . . . . . . 13
11 References . . . . . . . . . . . . . . . . . . . . . . . . . 13
12 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 14
13 Author's Address . . . . . . . . . . . . . . . . . . . . . . 14
1 Abstract
The ANNOTATEMORE extension to the Internet Message Access Protocol
[IMAP4] permits clients and servers to maintain "metadata" on IMAP4
servers. This document describes two "profiles" for mailbox and
server metadata.
2 Conventions Used in This Document
The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD
NOT", and "MAY" in this document are to be interpreted as described
in "Key words for use in RFCs to Indicate Requirement Levels"
[KEYWORDS].
Formal syntax is defined using ABNF [ABNF] as modified by [IMAP4].
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively.
3 Open Issues:
1 Handling of failures in SETANNOTATION with multiple mailbox
entries specified, and at least one fails but others succeed.
2 Do we want explicit access control for the /server hierarchy,
beyond simply defining certain attributes as read-only in the spec?
Daboo Expires August 2002 [Page 2]
Internet Draft IMAP ANNOTATEMORE Extension February 2002
3 Should mailbox name in entry use IMAPURL encoding or should it
be pure UTF8?
4 SETANNOTATION does not currently implement conditional store
behaviour. Do we want this?
5 Should LIST flags, mailbox referrals, STATUS info be attributes
of the /mailbox annotations?
6 Do we want the ability to search for annotations in the /server
or /mailbox hierarchies?
4 Introduction and Overview
The ANNOTATEMORE extension is present in any IMAP4 implementation
which returns "ANNOTATEMORE" as one of the supported capabilities in
the CAPABILITY command response.
The goal of ANNOTATEMORE is to provide a means for clients to store
and retrieve "metadata" on an IMAP4 server. This draft defines
"profiles" for storing metadata associated with specific mailboxes
and the server as a whole.
The ANNOTATEMORE extension adds two new commands and one new
untagged response to the IMAP4 base protocol.
This extension makes the following changes to the IMAP4 protocol:
1 adds a new SETANNOTATION command
2 adds a new GETANNOTATION command
3 adds a new ANNOTATION untagged response
The data model used in ANNOTATEMORE is exactly the same as that used
in the ANNOTATE [ANNOTATE] extension to IMAP4. This is modeled
after that of the Application Configuration Access Protocol [ACAP]
with the exception of inheritance which is not deemed necessary
here.
The rest of this document describes the data model and protocol
changes more rigorously.
5 Data Model
5.1 Overview
The data model used in ANNOTATEMORE is one of a uniquely named entry
with a set of uniquely named attributes, each of which has a value.
An annotation can contain multiple named entries. For example, a
general comment being added to a mailbox may have an entry name of
"/mailbox/{INBOX}/comment". This entry could include named
Daboo Expires August 2002 [Page 3]
Internet Draft IMAP ANNOTATEMORE Extension February 2002
attributes such as "value", "modifiedsince", "acl" etc to represent
properties and data associated with the entry.
The protocol changes to IMAP described below allow a client to
access or change the values of any attributes in any entries in a
message annotation, assuming it has sufficient access rights to do
so.
5.2 Namespace of entries and attributes
Each annotation is made up of a set of entries. Each entry has a
hierarchical name in UTF-8, with each component of the name
separated by a slash ("/").
Each entry is made up of a set of attributes. Each attribute has a
hierarchical name in UTF-8, with each component of the name
separated by a period (".").
The value of an attribute is NIL (has no value), or a string of zero
or more octets.
Entry and attribute names are not permitted to contain asterisk
("*") or percent ("%") characters and MUST be valid UTF-8 strings
which do not contain NUL. Invalid entry or attribute names result
in a BAD response in any IMAP commands where they are used.
Use of non-visible UTF-8 characters in entry and attribute names is
discouraged.
This specification defines an initial set of entry and attribute
names available for use with mailbox and server annotations. In
addition an extension mechanism is described to allow additional
names to be added for extensibility.
5.2.1 Entry Names
Entry names MUST be specified in a standards track or IESG approved
experimental RFC, or fall under the vendor namespace. See Section
9.1 for the registration template.
/mailbox
Defines the top-level of entries associated with mailboxes.
This entry itself does not have any associated attributes.
Daboo Expires August 2002 [Page 4]
Internet Draft IMAP ANNOTATEMORE Extension February 2002
/mailbox/{<mailbox-name>}
Defines the top-level of entries associated with a specific
mailbox. The <mailbox-name> is the name of the mailbox encoded
using the mailbox name encoding rules described in the IMAP URL
standard [IMAPURL]. The mailbox name appears inside
curly-braces to delimit it from the following levels of entry
name hierarchy, since it is possible that the mailbox name
itself contains the '/' characters uses to delimit entry name
hierarchical components. This entry itself does not have any
associated attributes.
/mailbox/{<mailbox-name>}/comment
Defines a comment or note associated with a mailbox.
/mailbox/{<mailbox-name>}/sort
Defines the default sort criteria [SORT] to use when first
displaying the mailbox contents to the user, or NIL if sorting
is not required.
/mailbox/{<mailbox-name>}/thread
Defines the default thread criteria [THREAD] to use when first
displaying the mailbox contents to the user, or NIL if threading
is not required. If both sort and thread are not NIL, then
threading should take precedence over sorting.
/mailbox/{<mailbox-name>}/check
Boolean value "true" or "false" that indicates whether this
mailbox should be checked at regular intervals by the client.
The interval in minutes is specified by the checkperiod
attribute.
/mailbox/{<mailbox-name>}/checkperiod
Numeric value indicating a period of minutes to use for checking
a mailbox that has the check attribute set to "true".
/mailbox/{<mailbox-name>}/vendor/<vendor-token>
Defines the top-level of entries associated with a specific
mailbox as created by a particular product of some vendor. This
entry can be used by vendors to provide client specific
attributes. The vendor-token MUST be registered with IANA.
/server
Defines the top-level of entries associated with the server.
This entry itself does not have any associated attributes.
/server/comment
Defines a comment or note associated with the server.
/server/motd
Defines a "message of the day" for the server. This entry is
always read-only - clients cannot change it.
Daboo Expires August 2002 [Page 5]
Internet Draft IMAP ANNOTATEMORE Extension February 2002
/server/admin
Indicates a method for contacting the server administrator.
This may be a URL (e.g. a mailto URL) or other contact
information, such as a telephone number. This entry is always
read-only - clients cannot change it.
/server/vendor/<vendor-token>
Defines the top-level of entries associated with the server as
created by a particular product of some vendor. This entry can
be used by vendors to provide server or client specific
attributes. The vendor-token MUST be registered with IANA.
5.2.2 Attribute Names
Attribute names MUST be specified in a standards track or IESG
approved experimental RFC, or fall under the vendor namespace. See
Section 9.1 for the registration template.
All attribute names implicitly have a ".priv" and a ".shared" suffix
which maps to private and shared versions of the entry. Searching
or fetching without using either suffix includes both. The client
MUST specify either a ".priv" or ".shared" suffix when storing an
annotation.
value
The data value of the attribute.
size
The size of the value, in octets. Set automatically by the
server, read-only to clients.
modifiedsince
An opaque value set by the server when this entry is modified.
It can be used by the client to request notification of which
entries have changed since a particular point in time and is
useful for disconnected/synchronisation operations.
content-type
A MIME [MIME] content type and subtype that describes the nature
of the content of the "value" attribute.
vendor.<vendor-token>
Defines an attribute associated with a particular product of
some vendor. This attribute can be used by vendors to provide
client specific attributes. The vendor-token MUST be registered
with IANA.
6 Private versus Shared and Access Control
As discussed in the ANNOTATE extension [ANNOTATE] there is a need to
support both private and shared annotations. This document adopts
Daboo Expires August 2002 [Page 6]
Internet Draft IMAP ANNOTATEMORE Extension February 2002
the scheme used in [ANNOTATE] that adds two standard suffixes for
all attributes: ".shared" and ".priv". A GETANNOTATION command
which specifies neither uses both. SETANNOTATION commands MUST
explicitly use .priv or .shared suffixes.
A user can only store and retrieve private annotations on a mailbox
which is returned to them via a LIST or LSUB command. A user can
only store and retrieve shared annotations on a mailbox that they
can SELECT and which opens READ-WRITE. If a client attempts to
store or retrieve a shared annotation on a READ-ONLY mailbox, the
server MUST respond with a NO response.
7 IMAP Protocol Changes
7.1 GETANNOTATION Command
This extension adds the GETANNOTATION command. This allows clients
to retrieve annotations.
This command is only available in authenticated state [IMAP4].
Arguments: entry-specifier
attribute-specifier
Responses: required ANNOTATION response
Result: OK - command completed
NO - command failure: can't access annotations on that mailbox
BAD - command unknown or arguments invalid
Example:
C: a GETANNOTATION "/server/comment" "value.priv"
S: * ANNOTATION "/server/comment" ("value.priv" "My comment")
S: a OK GETANNOTATION complete
In the above example, the contents of the "value" attribute
for the "/server/comment" entry is requested by the client
and returned by the server.
"*" and "%" wildcard characters can be used in either specifier to
match match one or more characters at that position, with the
exception that "%" does not match the hierarchy delimiter for the
specifier it appears in (i.e. "/" for an entry specifier or "." for
an attribute specifer). Thus an entry specifier of "/server/%"
would match entries such as "/server/comment" and "/server/version",
but not "/server/comment/note".
Examples:
C: a GETANNOTATION "/server/*" "value.priv"
S: * ANNOTATION ("/server/comment" ("value.priv" "My comment"))
Daboo Expires August 2002 [Page 7]
Internet Draft IMAP ANNOTATEMORE Extension February 2002
("/server/version" ("value.priv" "1.1"))
("/server/motd/today" ("value.priv" "Closed at 1 pm"))
S: a OK GETANNOTATION complete
In the above example, the contents of the "value" attributes
for any entries in the "/server" hierarchy are requested by
the client and returned by the server.
C: a GETANNOTATION "/server/%" "value"
S: * ANNOTATION ("/server/comment" ("value.priv" "My comment")
("value.shared" "Your comment"))
("/server/motd" ("value.priv" "Its sunny outside!")
("value.shared" "Today is a Holiday"))
S: a OK GETANNOTATION complete
In the above example, the contents of the "value" attributes
for entries at the top level of the "/server" hierarchy
only, are requested by the client and returned by the
server. Both the .priv and .shared values are returned, as
neither were explicitly requested.
Entry and attribute specifiers can be lists of atomic specifiers, so
that multiple items of each type may be returned in a single
GETANNOTATION command.
Examples:
C: a GETANNOTATION ("/server/comment" "/server/motd") "value.priv"
S: * ANNOTATION ("/server/comment" ("value.priv" "My comment"))
("/server/motd" ("value.priv" "Its sunny outside!"))
S: a OK GETANNOTATION complete
In the above example, the contents of the "value" attributes
for the two entries "/server/comment" and "/server/motd" are
requested by the client and returned by the server.
C: a GETANNOTATION "/server/comment" ("value.priv" "modifiedsince.priv")
S: * ANNOTATION "/server/comment"
("value.priv" "My comment"
"modifiedsince.priv" "19990203205432")
S: a OK GETANNOTATION complete
In the above example, the contents of the "value" and
"modifiedsince" attributes for the "/server/comment" entry
are requested by the client and returned by the server.
7.2 SETANNOTATION command
This extension adds the SETANNOTATION command. This allows clients
to set annotations.
Daboo Expires August 2002 [Page 8]
Internet Draft IMAP ANNOTATEMORE Extension February 2002
This command is only available in authenticated state [IMAP4].
Arguments: entry
attribute-value
list of entry, attribute-values
Responses: no specific responses for this command
Result: OK - command completed
NO - command failure: can't set annotations
BAD - command unknown or arguments invalid
Sets the specified list of entries by adding or replacing the
specified attributes with the values provided. Clients can use NIL
for values of attributes it wants to remove from entries. The
server MAY return an unsolicited ANNOTATION response containing the
updated annotation data. Clients MUST NOT assume that an
unsolicited ANNOTATION response will be sent, and MUST assume that
if the command succeeds then the annotation has been changed.
Examples:
C: a SETANNOTATION "/mailbox/{INBOX}/comment"
("value.priv" "My new comment")
S: a OK SETANNOTATION complete
In the above example, the entry "/mailbox/{INBOX}/comment"
is created (if not already present) and the private
attribute "value" with data set to "My new comment" is
created if not already present, or replaced if it previously
exists.
C: a SETANNOTATION "/mailbox/{INBOX}/comment" ("value.priv" NIL)
S: a OK SETANNOTATION complete
In the above example, the private "value" attribute of the
entry "/mailbox/{INBOX}/comment" is removed.
Multiple entries can be set in a single SETANNOTATION command by
listing entry-attribute-value pairs in the list.
Example:
C: a SETANNOTATION "/mailbox/{INBOX}/comment"
("value.priv" "My new comment")
"/mailbox/{INBOX.shared}/comment"
("value.shared" "This is a shared mailbox")
S: a OK SETANNOTATION complete
In the above example, the entries "/mailbox/{INBOX}/comment"
and "/mailbox/{INBOX.shared}/comment" are created (if not
already present) and the private and shared attributes
"value" are created respectively for each entry if not
Daboo Expires August 2002 [Page 9]
Internet Draft IMAP ANNOTATEMORE Extension February 2002
already present, or replaced if they previously existed.
Multiple attributes can be set in a single SETANNOTATION command by
listing multiple attribute-value pairs in the entry list.
Example:
C: a SETANNOTATION "/mailbox/{INBOX}/comment"
("value.priv" "My new comment"
"vendor.foobar.bloop.priv" "foo's bar")
S: a OK SETANNOTATION complete
In the above example, the entry "/mailbox/{INBOX}/comment"
is created (if not already present) and the private
attributes "value" and "vendor.foobar.bloop" are created if
not already present, or replaced if they previously existed.
7.3 ANNOTATION Response
The ANNOTATION response displays results of a GETANNOTATION command,
or can be returned as a unsolicited response at anytime by the
server in response to a change in an annotation.
Servers SHOULD send unsolicited ANNOTATION responses if an
annotation is changed by a third-party, allowing servers to keep
clients updated with changes to annotations by other clients. In
this case, only the entries are returned in the ANNOTATION response,
not the attributes and values. If the client wants to update any
cached values it must explicitly retrieve those using a
GETANNOTATION command.
This response is only available in authenticated state [IMAP4].
7.3.1 ANNOTATION response with attributes and values
The response consists of a list of entries each of which has a
list of attribute-value pairs.
Examples:
C: a GETANNOTATION "/server/comment" "value.priv"
S: * ANNOTATION "/server/comment" ("value.priv" "My comment")
S: a OK GETANNOTATION complete
In the above example, a single entry with a single
attribute-value pair is returned by the server.
C: a GETANNOTATION ("/server/comment" "/server/motd") "value.priv"
S: * ANNOTATION ("/server/comment" ("value.priv" "My comment"))
("/server/motd" ("value.priv" "Its sunny outside!"))
S: a OK GETANNOTATION complete
In the above example, two entries each with a single
attribute-value pair is returned by the server.
Daboo Expires August 2002 [Page 10]
Internet Draft IMAP ANNOTATEMORE Extension February 2002
C: a GETANNOTATION "/server/comment" ("value.priv" "modifiedsince.priv")
S: * ANNOTATION "/server/comment" (("value.priv" "My comment")
("modifiedsince.priv" "19990203205432"))
S: a OK GETANNOTATION complete
In the above example, a single entry with two
attribute-value pairs is returned by the server.
7.3.2 Unsolicted ANNOTATION response without attributes and values
The response consists of a list of entries each which have
changed on the server.
Examples:
C: a NOOP
S: * ANNOTATION "/server/comment"
S: a OK NOOP complete
In the above example, the server indicates that the
"/server/comment" entry has been changed.
C: a NOOP
S: * ANNOTATION ("/server/comment")("/server/motd")
S: a OK NOOP complete
In the above example, the server indicates a change to two
entries.
8 Formal Syntax
The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) notation as specified in [ABNF].
Non-terminals referenced but not defined below are as defined by
[IMAP4].
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.
command-auth /= setannotation / getannotation
; adds to original IMAP4 command
response-data /= "*" SP annotate-data CRLF
; adds to original IMAP4 data responses
getannotation = "GETANNOTATION" SP entries SP attribs
; new command
setannotation = "SETANNOTATION" SP setentries
; new command
Daboo Expires August 2002 [Page 11]
Internet Draft IMAP ANNOTATEMORE Extension February 2002
annotate-data = "ANNOTATION" SP entry-list
; new response
entries = entry-match / "(" entry-match *(SP entry-match) ")"
; entry specifiers that can include wildcards
attribs = attrib-match / "(" attrib-match *(SP attrib-match) ")"
; attribute specifiers that can include wildcards
entry-list = entry-att / "(" entry-att *(SP entry-att) ")"
; entry, attribute-value pairs list
setentries = entry-att *(SP entry-att)
; multiple entry, attribute-value pairs list
entry-att = entry SP "(" att-value *(SP att-value) ")"
att-value = attrib SP value
atom-slash = any ATOM-CHAR except "/"
atom-dot = any ATOM-CHAR except "."
entry = DQUOTE 1*atom-slash *("/" 1*atom-slash) DQUOTE
entry-match = DQUOTE 1*entry-match-atom
*("/" 1*entry-match-atom) DQUOTE
entry-match-atom = 1*(list-wildcards / atom-slash)
attrib = DQUOTE 1*atom-dot *("." 1*atom-dot) DQUOTE
attrib-match = DQUOTE 1*attrib-match-atom
*("." 1*attrib-match-atom) DQUOTE
attrib-match-atom = 1*(list-wildcards / atom-dot)
value = nstring
Daboo Expires August 2002 [Page 12]
Internet Draft IMAP ANNOTATEMORE Extension February 2002
9 IANA Considerations
Both entry names and attribute names MUST be specified in a
standards track or IESG approved experimental RFC, or fall under the
vendor namespace. Vendor names MUST be registered.
9.1 Entry and Attribute Registration Template
To: iana@iana.org
Subject: IMAP Annotate More Registration
Please register the following IMAP Annotate More item:
[] Entry [] Attribute
[] Vendor [] Open: RFC _______
Name: ______________________________
Description: _______________________
____________________________________
____________________________________
Contact person: ____________________
email: ____________________
10 Security Considerations
There are no known security issues with this extension.
11 References
[ABNF] Crocker, Overell, "Augmented BNF for Syntax Specifications:
ABNF", RFC 2234, Internet Mail Consortium, Demon Internet Ltd,
November 1997.
[ACAP] Newman, C., and Myers, J. "ACAP -- Application Configuration
Access Protocol", RFC 2244, November 1997.
[ANNOTATE] Daboo, C., Gellens, R., "IMAP ANNOTATE Extension",
draft-ietf-imapext-annotate-03.txt, January 2002.
[IMAP4] Crispin, M., "Internet Message Access Protocol - Version
4rev1", RFC 2060, University of Washington, December 1996.
[IMAPURL] Newman, C., "IMAP URL Scheme", RFC 2192, Innosoft,
September 1997.
Daboo Expires August 2002 [Page 13]
Internet Draft IMAP ANNOTATEMORE Extension February 2002
[KEYWORDS] Bradner, "Key words for use in RFCs to Indicate
Requirement Levels", RFC 2119, Harvard University, March 1997.
[MIME] Freed, N., and Borenstein, N. "MIME (Multipurpose Internet
Mail Extensions) Part Two: Media Types", RFC 2046, November 1996.
[SORT] Crispin, M., Murchison, K., "Internet Message Access Protocol
- Sort Extension", draft-ietf-imapext-sort-07.txt, University of
Washington, Oceana Matrix Ltd., September 2001.
[THREAD] Crispin, M., Murchison, K., "Internet Message Access
Protocol - Thread Extension", draft-ietf-imapext-thread-07.txt,
University of Washington, Oceana Matrix Ltd., September 2001.
12 Acknowledgments
The ideas expressed in this document are based on the message
annotation document that was co-authored by Randall Gellens.
13 Author's Address
Cyrus Daboo
Cyrusoft International, Inc.
Suite 780, 5001 Baum Blvd.
Pittsburgh, PA 15213
U.S.A.
Email: daboo@cyrusoft.com
Daboo Expires August 2002 [Page 14]
Html markup produced by rfcmarkup 1.129b, available from
https://tools.ietf.org/tools/rfcmarkup/