< draft-ietf-imapext-annotate-10.txt   draft-ietf-imapext-annotate-11.txt >
IMAP Extensions Working Group R. Gellens IMAP Extensions Working Group R. Gellens
Internet-Draft QUALCOMM Incorporated Internet-Draft QUALCOMM Incorporated
Expires: January 16, 2005 C. Daboo Expires: April 23, 2005 C. Daboo
ISAMET, Inc. ISAMET, Inc.
July 18, 2004 October 23, 2004
IMAP ANNOTATE Extension IMAP ANNOTATE Extension
draft-ietf-imapext-annotate-10 draft-ietf-imapext-annotate-11
Status of this Memo Status of this Memo
By submitting this Internet-Draft, I certify that any applicable This document is an Internet-Draft and is subject to all provisions
patent or other IPR claims of which I am aware have been disclosed, of section 3 of RFC 3667. By submitting this Internet-Draft, each
and any of which I become aware will be disclosed, in accordance with 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 become aware will be disclosed, in accordance with
RFC 3668. RFC 3668.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as other groups may also distribute working documents as
Internet-Drafts. Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on January 16, 2005. This Internet-Draft will expire on April 23, 2005.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2004). All Rights Reserved. Copyright (C) The Internet Society (2004).
Abstract Abstract
The ANNOTATE extension to the Internet Message Access Protocol The ANNOTATE extension to the Internet Message Access Protocol
[IMAP4] permits clients and servers to maintain "metadata" for permits clients and servers to maintain "metadata" for messages
messages stored in an IMAP4 mailbox. stored in an IMAP mailbox.
Change History (to be removed prior to publication as an RFC) Change History (to be removed prior to publication as an RFC)
Changes from -10 to -11:
1. Flags are now read-only and exactly match their IMAP
counterparts.
2. Added new ACL bits for annotations.
3. Revise security considerations.
4. Fixed some references.
Changes from -09 to -10: Changes from -09 to -10:
1. Added Content-Language value. 1. Added Content-Language value.
2. Added IANA registrations for entries/attributes in this document. 2. Added IANA registrations for entries/attributes in this document.
Changes from -08 to -09: Changes from -08 to -09:
1. Fix formatting, ID nits etc. 1. Fix formatting, ID nits etc.
2. Fix subject -> altsubject in examples. 2. Fix subject -> altsubject in examples.
3. Added text to SELECT/EXAMINE optional parameter definition to 3. Added text to SELECT/EXAMINE optional parameter definition to
indicate that the option could trigger a global state change or a indicate that the option could trigger a global state change or a
mailbox specific change. mailbox specific change.
4. Changed entry/attribute names to be case-sensitive to avoid case 4. Changed entry/attribute names to be case-sensitive to avoid case
skipping to change at page 3, line 44 skipping to change at page 4, line 4
addressable using ".priv" and ".shared" suffixes). There is a addressable using ".priv" and ".shared" suffixes). There is a
per-mailbox setting for the default. It is an open issue how per-mailbox setting for the default. It is an open issue how
this is viewed or changed by the client. this is viewed or changed by the client.
3. In ACLs, the "w" right is needed to updated shared state; the "s" 3. In ACLs, the "w" right is needed to updated shared state; the "s"
right is needed to update private state. right is needed to update private state.
4. Various clarifications and text modifications. 4. Various clarifications and text modifications.
5. Added 'forwarded' flag for message parts. 5. Added 'forwarded' flag for message parts.
Changes from pre-imapext to -00: Changes from pre-imapext to -00:
1. Clarified text describing attributions, entries, and attributes. 1. Clarified text describing attributions, entries, and attributes.
2. Changed 'modifiedsince' to 'modtime'; referenced ACAP spec. 2. Changed 'modifiedsince' to 'modtime'; referenced ACAP spec.
3. Deleted 'queued' flag. 3. Deleted 'queued' flag.
4. Expanded and explained smtp-envelope entry. 4. Expanded and explained smtp-envelope entry.
5. Restricted including ANNOTATION data in unsolicited responses 5. Restricted including ANNOTATION data in unsolicited responses
until the client uses it first. (Open issue as to if needed). until the client uses it first. (Open issue as to if needed).
6. Examples now only use valid entries and attributes. 6. Examples now only use valid entries and attributes.
7. Updated Security Considerations. 7. Updated Security Considerations.
8. Content-Type now defaults to text/plain. 8. Content-Type now defaults to text/plain.
9. Open Issue: Shared vs. private annotations. 9. Open Issue: Shared vs. private annotations.
10. Open issue: Annotation Modtime untagged response or VALIDTIME 10. Open issue: Annotation Modtime untagged response or VALIDTIME
FETCH data. FETCH data.
11. Open issue: Conditional annotation STORE. 11. Open issue: Conditional annotation STORE.
12. ANNOTATION criterion available if both "ANNOTATE" and "SORT" in 12. ANNOTATION criterion available if both "ANNOTATE" and "SORT" in
CAPABILITY command response. CAPABILITY command response.
13. Prohibition on annotations in lieu of base spec functionality. 13. Prohibition on annotations in lieu of base spec functionality.
14. Specified required ACL rights. 14. Specified required ACL rights.
15. ANNOTATION message data item in APPEND. 15. ANNOTATION message data item in APPEND.
16. ANNOTATION-MODTIME message data item in STATUS. 16. ANNOTATION-MODTIME message data item in STATUS.
17. Replaced ATOM_CHAR with utf8-char. 17. Replaced ATOM_CHAR with utf8-char.
18. Updated other ABNF entries. 18. Updated other ABNF entries.
Table of Contents Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . 6 1. Introduction and Overview . . . . . . . . . . . . . . . . . 7
2. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 7 2. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 Namespace of entries and attributes . . . . . . . . . . . 7 2.2 Namespace of entries and attributes . . . . . . . . . . . 8
2.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . . 8 2.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . . 9
2.2.2 Attribute Names . . . . . . . . . . . . . . . . . . . 10 2.2.2 Attribute Names . . . . . . . . . . . . . . . . . . . 11
2.3 Private versus Shared and Access Control . . . . . . . . . 11 2.3 Private versus Shared . . . . . . . . . . . . . . . . . . 12
3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . 12 2.4 Access Control . . . . . . . . . . . . . . . . . . . . . . 13
3.1 General Considerations . . . . . . . . . . . . . . . . . . 12 2.5 Access to Standard IMAP Flags and Keywords . . . . . . . . 15
3.2 Optional parameters with the SELECT/EXAMINE commands . . . 12 3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . 15
3.3 ANNOTATION Message Data Item in FETCH Command . . . . . . 14 3.1 General Considerations . . . . . . . . . . . . . . . . . . 15
3.4 ANNOTATION Message Data Item in FETCH Response . . . . . . 16 3.2 Optional parameters with the SELECT/EXAMINE commands . . . 15
3.5 ANNOTATION Message Data Item in STORE . . . . . . . . . . 17 3.3 ANNOTATION Message Data Item in FETCH Command . . . . . . 17
3.6 ANNOTATION interaction with COPY . . . . . . . . . . . . . 19 3.4 ANNOTATION Message Data Item in FETCH Response . . . . . . 19
3.7 ANNOTATION Message Data Item in APPEND . . . . . . . . . . 19 3.5 ANNOTATION Message Data Item in STORE . . . . . . . . . . 20
3.8 ANNOTATION Criterion in SEARCH . . . . . . . . . . . . . . 19 3.6 ANNOTATION interaction with COPY . . . . . . . . . . . . . 22
3.9 ANNOTATION Key in SORT . . . . . . . . . . . . . . . . . . 20 3.7 ANNOTATION Message Data Item in APPEND . . . . . . . . . . 22
4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . 21 3.8 ANNOTATION Criterion in SEARCH . . . . . . . . . . . . . . 22
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . 23 3.9 ANNOTATION Key in SORT . . . . . . . . . . . . . . . . . . 23
5.1 Entry and Attribute Registration Template . . . . . . . . 23 3.10 New ACL Rights . . . . . . . . . . . . . . . . . . . . . 24
5.2 Entry Registrations . . . . . . . . . . . . . . . . . . . 23 4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . 24
5.2.1 /comment . . . . . . . . . . . . . . . . . . . . . . . 24 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . 26
5.2.2 /flags/\answered . . . . . . . . . . . . . . . . . . 24 5.1 Entry and Attribute Registration Template . . . . . . . . 26
5.2.3 /flags/\flagged . . . . . . . . . . . . . . . . . . . 25 5.2 Entry Registrations . . . . . . . . . . . . . . . . . . . 26
5.2.4 /flags/\deleted . . . . . . . . . . . . . . . . . . . 25 5.2.1 /comment . . . . . . . . . . . . . . . . . . . . . . . 27
5.2.5 /flags/\seen . . . . . . . . . . . . . . . . . . . . 26 5.2.2 /flags/\\answered . . . . . . . . . . . . . . . . . . 27
5.2.6 /flags/\draft . . . . . . . . . . . . . . . . . . . . 26 5.2.3 /flags/\\flagged . . . . . . . . . . . . . . . . . . . 28
5.2.7 /flags/\recent . . . . . . . . . . . . . . . . . . . 27 5.2.4 /flags/\\deleted . . . . . . . . . . . . . . . . . . . 28
5.2.8 /flags/$mdnsent . . . . . . . . . . . . . . . . . . . 27 5.2.5 /flags/\\seen . . . . . . . . . . . . . . . . . . . . 29
5.2.9 /flags/$redirected . . . . . . . . . . . . . . . . . . 28 5.2.6 /flags/\\draft . . . . . . . . . . . . . . . . . . . . 29
5.2.10 /flags/$forwarded . . . . . . . . . . . . . . . . . 28 5.2.7 /flags/\\recent . . . . . . . . . . . . . . . . . . . 30
5.2.11 /altsubject . . . . . . . . . . . . . . . . . . . . 29 5.2.8 /flags/$mdnsent . . . . . . . . . . . . . . . . . . . 30
5.2.12 /<section-part>/comment . . . . . . . . . . . . . . 29 5.2.9 /flags/$redirected . . . . . . . . . . . . . . . . . . 31
5.2.13 /<section-part>/flags/seen . . . . . . . . . . . . . 30 5.2.10 /flags/$forwarded . . . . . . . . . . . . . . . . . 31
5.2.14 /<section-part>/flags/answered . . . . . . . . . . . 30 5.2.11 /altsubject . . . . . . . . . . . . . . . . . . . . 32
5.2.15 /<section-part>/flags/flagged . . . . . . . . . . . 31 5.2.12 /<section-part>/comment . . . . . . . . . . . . . . 32
5.2.16 /<section-part>/flags/forwarded . . . . . . . . . . 31 5.2.13 /<section-part>/flags/seen . . . . . . . . . . . . . 33
5.3 Attribute Registrations . . . . . . . . . . . . . . . . . 31 5.2.14 /<section-part>/flags/answered . . . . . . . . . . . 33
5.3.1 value . . . . . . . . . . . . . . . . . . . . . . . . 32 5.2.15 /<section-part>/flags/flagged . . . . . . . . . . . 34
5.3.2 size . . . . . . . . . . . . . . . . . . . . . . . . . 32 5.2.16 /<section-part>/flags/forwarded . . . . . . . . . . 34
5.3.3 content-type . . . . . . . . . . . . . . . . . . . . . 33 5.3 Attribute Registrations . . . . . . . . . . . . . . . . . 34
5.3.4 content-language . . . . . . . . . . . . . . . . . . . 33 5.3.1 value . . . . . . . . . . . . . . . . . . . . . . . . 35
6. Security Considerations . . . . . . . . . . . . . . . . . . 33 5.3.2 size . . . . . . . . . . . . . . . . . . . . . . . . . 35
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 5.3.3 content-type . . . . . . . . . . . . . . . . . . . . . 36
7.1 Normative References . . . . . . . . . . . . . . . . . . . . 34 5.3.4 content-language . . . . . . . . . . . . . . . . . . . 36
7.2 Informative References . . . . . . . . . . . . . . . . . . . 34 6. Security Considerations . . . . . . . . . . . . . . . . . . 36
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 35 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 37
A. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 35 7.1 Normative References . . . . . . . . . . . . . . . . . . . . 37
Intellectual Property and Copyright Statements . . . . . . . 36 7.2 Informative References . . . . . . . . . . . . . . . . . . . 37
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 38
A. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 38
Intellectual Property and Copyright Statements . . . . . . . 39
1. Introduction and Overview 1. Introduction and Overview
The ANNOTATE extension is present in any IMAP4 implementation which The ANNOTATE extension is present in any IMAP [RFC3501]
returns "ANNOTATE" as one of the supported capabilities in the implementation which returns "ANNOTATE" as one of the supported
CAPABILITY response. capabilities in the CAPABILITY response.
The ANNOTATE extension adds a new message data item to the FETCH and The ANNOTATE extension adds a new message data item to the FETCH and
STORE commands, as well as adding SEARCH and SORT keys and an APPEND STORE commands, as well as adding SEARCH and SORT keys and an APPEND
modifier. modifier.
This extension makes the following changes to the IMAP4 protocol: This extension makes the following changes to the IMAP protocol:
a. adds a new ANNOTATION message data item for use in FETCH a. adds a new ANNOTATION message data item for use in FETCH
b. adds a new ANNOTATION message data item for use in STORE b. adds a new ANNOTATION message data item for use in STORE
c. adds a new ANNOTATION search criterion for use in SEARCH c. adds a new ANNOTATION search criterion for use in SEARCH
d. adds a new ANNOTATION sort key for use in SORT extension d. adds a new ANNOTATION sort key for use in SORT extension
e. adds a new ANNOTATION data item for use in APPEND e. adds a new ANNOTATION data item for use in APPEND
f. adds a new requirement on the COPY command f. adds a new requirement on the COPY command
g. adds a extension mechanism for adding parameters to the SELECT/ g. adds a extension mechanism for adding parameters to the SELECT/
EXAMINE commands and defines the ANNOTATE parameter EXAMINE commands and defines the ANNOTATE parameter
h. adds two new response codes to indicate store failures of h. adds two new response codes to indicate store failures of
annotations. annotations.
i. adds a new untagged response codes for the SELECT or EXAMINE i. adds a new untagged response codes for the SELECT or EXAMINE
commands to indicate the maximum size. commands to indicate the maximum size.
j. adds two new ACL 'bits' for use with the ACL [RFC2086] extension.
The data model used for the storage of annotations is based on that The data model used for the storage of annotations is based on that
of the Application Configuration Access Protocol [ACAP]. Note that of the Application Configuration Access Protocol [RFC2244]. Note
there is no inheritance in annotations. that there is no inheritance in annotations.
Clients MUST NOT use annotations in lieu of equivalent IMAP base Clients MUST NOT use annotations in lieu of equivalent IMAP base
specification facilities. For example, use of a "seen" flag in the specification facilities. For example, use of a "seen" flag in the
vendor namespace together with ".PEEK" in fetches. Such behaviour vendor namespace together with ".PEEK" in fetches. Such behaviour
would significantly reduce IMAP interoperability. would significantly reduce IMAP interoperability.
If a server supports annotations, then it MUST store all annotation If a server supports annotations, then it MUST store all annotation
data permanently, i.e. there is no concept of 'session only' data permanently, i.e. there is no concept of 'session only'
annotations that would correspond to the behaviour of 'session' flags annotations that would correspond to the behaviour of 'session' flags
as defined in the IMAP base specification. The exception to this is as defined in the IMAP base specification. The exception to this is
skipping to change at page 7, line 27 skipping to change at page 8, line 29
several attributes. several attributes.
For example, a comment added to a message has an entry name of "/ For example, a comment added to a message has an entry name of "/
comment". This entry is composed of several attributes such as comment". This entry is composed of several attributes such as
"value", "size", etc. which contain the properties and data of the "value", "size", etc. which contain the properties and data of the
entry. entry.
The protocol changes to IMAP described below allow a client to access 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 or change the values of any attributes in any entries in a message
annotation, assuming it has sufficient access rights to do so (see annotation, assuming it has sufficient access rights to do so (see
Section 2.3 for specifics). Section 2.4 for specifics).
2.2 Namespace of entries and attributes 2.2 Namespace of entries and attributes
Each message annotation is made up of a set of entries. Each entry Each message annotation is made up of a set of entries. Each entry
has a hierarchical name in UTF-8, with each component of the name has a hierarchical name in UTF-8, with each component of the name
separated by a slash ("/"). separated by a slash ("/").
Each entry is made up of a set of attributes. Each attribute has a 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 hierarchical name in UTF-8, with each component of the name separated
by a period ("."). by a period (".").
skipping to change at page 8, line 32 skipping to change at page 9, line 32
/comment /comment
Defines a comment or note associated with an entire message. Defines a comment or note associated with an entire message.
/flags /flags
Defines the top-level of entries for flags associated with an Defines the top-level of entries for flags associated with an
entire message. The "value" attribute of each of the entries entire message. The "value" attribute of each of the entries
described below must be either "1", "0" or NIL. "1" corresponds described below must be either "1", "0" or NIL. "1" corresponds
to the flag being set. to the flag being set.
Standard [IMAP4] flags always have a '\' prefix character. Other Standard [RFC3501] flags always have a '\' prefix character.
standard flags have a '$' prefix. The annotation names used for Other standard flags have a '$' prefix. The annotation names used
all flags uses the complete name for that flag, including the for all flags uses the complete name for that flag, including the
prefix character. prefix character.
Flag annotations are read-only. Clients MUST NOT attempt to
change them via the annotation entries, using instead the normal
IMAP STORE FLAGS command.
The set of standard IMAP flags annotations are: The set of standard IMAP flags annotations are:
/flags/\answered /flags/\answered
/flags/\flagged /flags/\flagged
/flags/\deleted /flags/\deleted
/flags/\seen /flags/\seen
/flags/\draft /flags/\draft
/flags/\recent /flags/\recent
Changes to these annotations are reflected in the standard IMAP Note that entry names are sent as IMAP string elements which
flags. The \recent attribute is read only, clients MUST NOT
attempt to change it.
Note that entry names are sent as [IMAP4] string elements which
requires that '\' characters be escaped if sent as a quoted string requires that '\' characters be escaped if sent as a quoted string
as opposed to a literal. as opposed to a literal.
Note that flag and keyword names in [IMAP4] are case-insensitive, Note that flag and keyword names in IMAP are case-insensitive,
however the entry names for the corresponding annotations are however the entry names for the corresponding annotations are
case-sensitive. Thus the [IMAP4] flag and keyword names MUST be case-sensitive. Thus the IMAP flag and keyword names MUST be
mapped to lowercase characters before being used as entry names mapped to lowercase characters before being used as entry names
for annotations. for annotations.
Additional standard flags are: Additional standard flags are:
/flags/$mdnsent /flags/$mdnsent
/flags/$redirected /flags/$redirected
/flags/$forwarded /flags/$forwarded
The '$mdnsent' flag is used to indicate message disposition The '$mdnsent' flag is used to indicate message disposition
notification processing state [MDNSENT]. notification processing state [RFC3503].
The '$redirected' flag indicates that a message has been handed The '$redirected' flag indicates that a message has been handed
off to someone else, by resending the message with minimal off to someone else, by resending the message with minimal
alterations, and in such a way that a reply by the new alterations, and in such a way that a reply by the new
recipient is addressed to the original author, not the user who recipient is addressed to the original author, not the user who
performed the redirection. performed the redirection.
The '$forwarded' flag indicates the message was resent to The '$forwarded' flag indicates the message was resent to
another user, embedded within or attached to a new message. another user, embedded within or attached to a new message.
/altsubject /altsubject
Contains text supplied by the message recipient, to be used by the Contains text supplied by the message recipient, to be used by the
client instead of the original message Subject. client instead of the original message Subject.
/vendor/<vendor-token> /vendor/<vendor-token>
Defines the top-level of entries associated with an entire message Defines the top-level of entries associated with an entire message
as created by a particular product of some vendor. These as created by a particular product of some vendor. These
sub-entries can be used by vendors to provide client-specific sub-entries can be used by vendors to provide client-specific
attributes. The vendor-token MUST be registered with IANA, using attributes. The vendor-token MUST be registered with IANA, using
the [ACAP] vendor subtree registry. the [RFC2244] vendor subtree registry.
/<section-part> /<section-part>
Defines the top-level of entries associated with a specific body Defines the top-level of entries associated with a specific body
part of a message. This entry itself does not contain any part of a message. This entry itself does not contain any
attributes. The section-part uses the same numeric part specifier attributes. The section-part uses the same numeric part specifier
syntax as the BODY message data item in the FETCH command [IMAP4]. syntax as the BODY message data item in the FETCH command
The server MUST return a BAD response if the client uses an [RFC3501]. The server MUST return a BAD response if the client
incorrect part specifier (either incorrect syntax or a specifier uses an incorrect part specifier (either incorrect syntax or a
referring to a non-existent part). The server MUST return a BAD specifier referring to a non-existent part). The server MUST
response if the client uses an empty part specifier (which is used return a BAD response if the client uses an empty part specifier
in [IMAP4] to represent the entire message). (which is used in IMAP to represent the entire message).
/<section-part>/comment /<section-part>/comment
Defines a comment or note associated with a specific body part of Defines a comment or note associated with a specific body part of
a message. a message.
/<section-part>/flags /<section-part>/flags
Defines the top-level of entries associated with flag state for a Defines the top-level of entries associated with flag state for a
specific body part of a message. All sub-entries are maintained specific body part of a message. All sub-entries are maintained
entirely by the client. There is no implicit change to any flag entirely by the client. There is no implicit change to any flag
by the server. by the server.
skipping to change at page 10, line 47 skipping to change at page 11, line 47
value value
A UTF8 string representing the data value of the attribute. To A UTF8 string representing the data value of the attribute. To
delete an annotation, the client can store NIL into the value. delete an annotation, the client can store NIL into the value.
size size
The size of the value, in octets. Set automatically by the The size of the value, in octets. Set automatically by the
server, read-only to clients. server, read-only to clients.
content-type content-type
A MIME [MIME] content type and subtype that describes the nature A MIME [RFC2046] content type and subtype that describes the
of the content of the "value" attribute. If not present, a value nature of the content of the "value" attribute. If not present, a
of "text/plain; charset=utf8" is assumed. value of "text/plain; charset=utf8" is assumed.
content-language content-language
Indicates the language used for the value. This follows the Indicates the language used for the value. This follows the
format described in [RFC3282]. Clients SHOULD set this value when format described in [RFC3282]. Clients SHOULD set this value when
storing an annotation that uses text that can be presented to the storing an annotation that uses text that can be presented to the
user. It is not required for enumerated or numeric values such as user. It is not required for enumerated or numeric values such as
flags etc. flags etc.
vendor.<vendor-token> vendor.<vendor-token>
Defines an attribute associated with a particular product of some Defines an attribute associated with a particular product of some
vendor. This attribute can be used by vendors to provide client vendor. This attribute can be used by vendors to provide client
specific attributes. The vendor-token MUST be registered with specific attributes. The vendor-token MUST be registered with
IANA, using the [ACAP] vendor subtree registry. IANA, using the [RFC2244] vendor subtree registry.
2.3 Private versus Shared and Access Control 2.3 Private versus Shared
Some IMAP mailboxes are private, accessible only to the owning user. Some IMAP mailboxes are private, accessible only to the owning user.
Other mailboxes are not, either because the owner has set an ACL Other mailboxes are not, either because the owner has set an ACL
[ACL] which permits access by other users, or because it is a shared [RFC2086] which permits access by other users, or because it is a
mailbox. shared mailbox.
This raises the issue of shared versus private annotations. This raises the issue of shared versus private annotations.
If all annotations are private, it is impossible to set annotations If all annotations are private, it is impossible to set annotations
in a shared or otherwise non-private mailbox that are visible to in a shared or otherwise non-private mailbox that are visible to
other users. This eliminates what could be a useful aspect of other users. This eliminates what could be a useful aspect of
annotations in a shared environment. An example of such use is a annotations in a shared environment. An example of such use is a
shared IMAP folder containing bug reports. Engineers may want to use shared IMAP folder containing bug reports. Engineers may want to use
annotations to add information to existing messages, indicate annotations to add information to existing messages, indicate
assignments, status, etc. This use requires shared annotations. assignments, status, etc. This use requires shared annotations.
skipping to change at page 12, line 6 skipping to change at page 13, line 6
to differentiate them. Also, it should be as easy as possible for a to differentiate them. Also, it should be as easy as possible for a
client to access both and not overlook either. There is also a client to access both and not overlook either. There is also a
danger in allowing a client to store an annotation without knowing if danger in allowing a client to store an annotation without knowing if
it is shared or private. it is shared or private.
This document proposes two standard suffixes for all attributes: This document proposes two standard suffixes for all attributes:
".shared" and ".priv". A search, fetch, or sort which specifies ".shared" and ".priv". A search, fetch, or sort which specifies
neither uses both. Store operations MUST explicitly use .priv or neither uses both. Store operations MUST explicitly use .priv or
.shared suffixes. .shared suffixes.
A user can only store and fetch private annotations on messages in 2.4 Access Control
any mailbox which they can SELECT or EXAMINE, including ones which
only open READ-ONLY. A user can only store and fetch shared A user needs to have appropriate rights in order to read or write
annotations on messages in any mailbox that they can SELECT and which .priv or .shared annotation values. How those rights are calculated
opens READ-WRITE. If a client attempts to store or fetch a shared depends on whether the ACL [RFC2086] extension is present or not. If
annotation on a READ-ONLY mailbox, the server MUST respond with a NO a client attempts to store or fetch an annotation to which they do
not have the appropriate rights, the server MUST respond with a NO
response. response.
When the ACL extension is not present, access to annotation values is
governed by the nature of the selected state. In particular whether
the mailbox was SELECT'ed or EXAMINE'd in READ-ONLY or READ-WRITE
mode.
When the ACL extension is present, the server MUST recognise two new
ACL rights, 'm' and 'n', in addition to the ones defined by the ACL
extension itself.
The 'm' right controls both read and write access to .priv annotation
values. When it is on, access to .priv annotations is allowed, when
it is off, access to .priv annotations is disallowed.
The 'r' right controls only the read access for .shared annotation
values. When it is on, .shared annotations can be read, when it is
off, .shared annotations cannot be read.
The 'n' right controls only the write access for .shared annotation
values. When it is on, .shared annotations can be changed, when it
is off, .shared annotations cannot be changed. The 'n' right MUST
NOT be present if the 'r' is not present.
A summary of all the access control restrictions is tabulated below
+---------------+---------------+-----------------------------------+
| Server Type | Action on | Type of mailbox |
| | annotation | |
+===============+===============+===================================+
| | | |
| | read .priv | Any mailbox that can be SELECTED |
| | values | or EXAMINED. |
| | | |
| +---------------+-----------------------------------+
| | | |
| | write .priv | Any SELECTED [READ-WRITE] mailbox.|
| | values | SELECTED [READ-ONLY] mailboxes MAY|
| Server | | also permit writes. |
| without | | |
| ACL Extension +---------------+-----------------------------------+
| | | |
| | read .shared | Any mailbox that can be SELECTED |
| | values | or EXAMINED. |
| | | |
| +---------------+-----------------------------------+
| | | |
| | write .shared | Any mailbox that can be SELECTED |
| | values | or EXAMINED and is [READ-WRITE]. |
| | | |
+---------------+---------------+-----------------------------------+
| | | |
| | read .priv | Any mailbox with the 'm' |
| | values | ACL right. |
| | | |
| +---------------+-----------------------------------+
| | | |
| | write .priv | Any mailbox with the 'm' |
| Server | values | ACL right. |
| with | | |
| ACL Extension +---------------+-----------------------------------+
| | | |
| | read .shared | Any mailbox with the 'r' |
| | values | ACL right. |
| | | |
| +---------------+-----------------------------------+
| | | |
| | write .shared | Any mailbox with the 'n' |
| | values | ACL right. |
| | | |
+---------------+---------------+-----------------------------------+
2.5 Access to Standard IMAP Flags and Keywords
Flags cannot be changed through annotations due to ambiguity of how
private and shared values would map to the base IMAP flag and keyword
values. As a result the /flags annotation values are treated as
read-only and MUST NOT be changed by a client. In turn this means
that the .priv and .shared values of a flag annotation are always the
same and represent the value of the base IMAP flag or keyword.
Clients that need to implement shared and private 'flags' can create
their own annotation entries for those, completely bypassing the base
IMAP flag/keyword behaviour.
3. IMAP Protocol Changes 3. IMAP Protocol Changes
3.1 General Considerations 3.1 General Considerations
The server is allowed to impose limitations on the size of any one The server is allowed to impose limitations on the size of any one
annotation or the total number of annotations for a single message. annotation or the total number of annotations for a single message.
However, the server MUST accept a minimum annotation data size of at However, the server MUST accept a minimum annotation data size of at
least 1024 bytes, and a minimum annotation count per message of at least 1024 bytes, and a minimum annotation count per message of at
least 10. least 10.
skipping to change at page 19, line 30 skipping to change at page 22, line 30
3.7 ANNOTATION Message Data Item in APPEND 3.7 ANNOTATION Message Data Item in APPEND
ANNOTATION <parenthesised entry-attribute-value list> ANNOTATION <parenthesised entry-attribute-value list>
Sets the specified list of entries and attributes in the resulting Sets the specified list of entries and attributes in the resulting
message. message.
The APPEND command can include annotations for the message being The APPEND command can include annotations for the message being
appended via the addition of a new append data item. The new data appended via the addition of a new append data item. The new data
item can also be used with the multi-append [MULTIAPPEND] extension item can also be used with the multi-append [RFC3502] extension that
that allows multiple messages to be appended via a single APPEND allows multiple messages to be appended via a single APPEND command.
command.
Example: Example:
C: a APPEND drafts ANNOTATION ("/comment" C: a APPEND drafts ANNOTATION ("/comment"
("value.priv" "Don't send until we hear from Sally")) {310} ("value.priv" "Don't send until we hear from Sally")) {310}
S: + Ready for literal data S: + Ready for literal data
C: MIME-Version: 1.0 C: MIME-Version: 1.0
... ...
C: C:
S: a OK APPEND completed S: a OK APPEND completed
skipping to change at page 21, line 4 skipping to change at page 23, line 50
The ANNOTATION criterion for the SORT command [SORT] instructs the The ANNOTATION criterion for the SORT command [SORT] instructs the
server to return the message numbers or UIDs of a mailbox, sorted server to return the message numbers or UIDs of a mailbox, sorted
using the values of the specified annotations. The ANNOTATION using the values of the specified annotations. The ANNOTATION
criterion is available if the server returns both "ANNOTATE" and criterion is available if the server returns both "ANNOTATE" and
"SORT" as supported capabilities in the CAPABILITY command response. "SORT" as supported capabilities in the CAPABILITY command response.
Messages are sorted using the values of the <attribute-name> Messages are sorted using the values of the <attribute-name>
attributes in the <entry-name> entries. (The charset argument attributes in the <entry-name> entries. (The charset argument
determines sort order, as specified in the SORT extension determines sort order, as specified in the SORT extension
description.) description.)
Example: Example:
C: a SORT (ANNOTATION "/altsubject" "value.shared") UTF-8 ALL C: a SORT (ANNOTATION "/altsubject" "value.shared") UTF-8 ALL
S: * SORT 2 3 4 5 1 11 10 6 7 9 8 S: * SORT 2 3 4 5 1 11 10 6 7 9 8
S: a OK Sort complete S: a OK Sort complete
In the above example, the message numbers of all messages are In the above example, the message numbers of all messages are
returned, sorted according to the shared "value" attribute of the returned, sorted according to the shared "value" attribute of the
"/altsubject" entry. "/altsubject" entry.
Note that the ANNOTATION sort key must include a fully specified Note that the ANNOTATION sort key must include a fully specified
entry and attribute -- wildcards are not allowed. entry and attribute -- wildcards are not allowed.
3.10 New ACL Rights
As discussed in Section 2.4 this extension adds new 'm' and 'n'
rights to the list of rights provided by the ACL [RFC2086] extension.
4. Formal Syntax 4. Formal Syntax
The following syntax specification uses the Augmented Backus-Naur The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) notation as specified in [ABNF]. Form (ABNF) notation as specified in [RFC2234].
Non-terminals referenced but not defined below are as defined by Non-terminals referenced but not defined below are as defined by
[IMAP4]. [RFC3501].
Except as noted otherwise, all alphabetic characters are Except as noted otherwise, all alphabetic characters are
case-insensitive. The use of upper or lower case characters to case-insensitive. The use of upper or lower case characters to
define token strings is for editorial clarity only. Implementations define token strings is for editorial clarity only. Implementations
MUST accept these strings in a case-insensitive fashion. MUST accept these strings in a case-insensitive fashion.
annotate-param = "ANNOTATE" annotate-param = "ANNOTATE"
; defines the select parameter used with ; defines the select parameter used with
; ANNOTATE extension ; ANNOTATE extension
append = "APPEND" SP mailbox [SP flag-list] [SP date-time] append = "APPEND" SP mailbox [SP flag-list] [SP date-time]
[SP "ANNOTATION" SP att-annotate] SP literal [SP "ANNOTATION" SP att-annotate] SP literal
; modifies original IMAP4 APPEND command ; modifies original IMAP APPEND command
append-message = [SP flag-list] [SP date-time] append-message = [SP flag-list] [SP date-time]
[SP "ANNOTATION" SP att-annotate] SP literal [SP "ANNOTATION" SP att-annotate] SP literal
; modifies [MULTIAPPEND] extension behaviour ; modifies [MULTIAPPEND] extension behaviour
att-annotate = "ANNOTATION" SP "(" entry-att *(SP entry-att) ")" att-annotate = "ANNOTATION" SP "(" entry-att *(SP entry-att) ")"
att-match = string att-match = string
; dot-separated attribute name ; dot-separated attribute name
; MAY contain "*" or "%" for use as wildcards ; MAY contain "*" or "%" for use as wildcards
skipping to change at page 22, line 23 skipping to change at page 25, line 25
; slash-separated path to entry ; slash-separated path to entry
; MUST NOT contain "*" or "%" ; MUST NOT contain "*" or "%"
entry-att = entry SP "(" att-value *(SP att-value) ")" entry-att = entry SP "(" att-value *(SP att-value) ")"
entry-match = string entry-match = string
; slash-separated path to entry ; slash-separated path to entry
; MAY contain "*" or "%" for use as wildcards ; MAY contain "*" or "%" for use as wildcards
examine =/ *(SP "(" select-param *(SP select-param) ")" examine =/ *(SP "(" select-param *(SP select-param) ")"
; modifies the original IMAP4 examine command to ; modifies the original IMAP examine command to
; accept optional parameters ; accept optional parameters
fetch-ann-resp = "ANNOTATION" SP "(" entry-att *(SP entry-att) ")" fetch-ann-resp = "ANNOTATION" SP "(" entry-att *(SP entry-att) ")"
fetch-att =/ "ANNOTATION" SP "(" entries SP attribs ")" fetch-att =/ "ANNOTATION" SP "(" entries SP attribs ")"
; modifies original IMAP4 fetch-att ; modifies original IMAP fetch-att
resp-text-code =/ "ANNOTATE" SP "TOOBIG" / resp-text-code =/ "ANNOTATE" SP "TOOBIG" /
"ANNOTATE" SP "TOOMANY" / "ANNOTATE" SP "TOOMANY" /
"ANNOTATESIZE" SP (number / "NIL") "ANNOTATESIZE" SP (number / "NIL")
; new response codes ; new response codes
search-key =/ "ANNOTATION" SP entry-match SP att-match search-key =/ "ANNOTATION" SP entry-match SP att-match
SP value SP value
; modifies original IMAP4 search-key ; modifies original IMAP search-key
select =/ *(SP "(" select-param *(SP select-param) ")" select =/ *(SP "(" select-param *(SP select-param) ")"
; modifies the original IMAP4 select command to ; modifies the original IMAP select command to
; accept optional parameters ; accept optional parameters
select-param = astring / "(" astring SP astring *(SP astring) ")" select-param = astring / "(" astring SP astring *(SP astring) ")"
; parameters to SELECT may contain one or ; parameters to SELECT may contain one or
; more atoms or strings - multiple items ; more atoms or strings - multiple items
; are always parenthesised ; are always parenthesised
sort-key =/ "ANNOTATION" SP entry SP attrib sort-key =/ "ANNOTATION" SP entry SP attrib
; modifies original sort-key [SORT] ; modifies original sort-key <xref target='SORT' />
store-att-flags =/ att-annotate store-att-flags =/ att-annotate
; modifies original IMAP4 STORE command ; modifies original IMAP STORE command
value = nstring value = nstring
5. IANA Considerations 5. IANA Considerations
Both entry names and attribute names MUST be specified in a standards Both entry names and attribute names MUST be specified in a standards
track or IESG approved experimental RFC, or fall under the vendor track or IESG approved experimental RFC, or fall under the vendor
namespace. Vendor names MUST be registered. namespace. Vendor names MUST be registered.
5.1 Entry and Attribute Registration Template 5.1 Entry and Attribute Registration Template
skipping to change at page 24, line 22 skipping to change at page 27, line 22
[X] Entry [] Attribute [X] Entry [] Attribute
Name: /comment Name: /comment
Description: Defined in IMAP ANNOTATE extension document. Description: Defined in IMAP ANNOTATE extension document.
Contact person: Cyrus Daboo Contact person: Cyrus Daboo
email: daboo@isamet.com email: daboo@isamet.com
5.2.2 /flags/\answered 5.2.2 /flags/\\answered
To: iana@iana.org To: iana@iana.org
Subject: IMAP Annotate Registration Subject: IMAP Annotate Registration
Please register the following IMAP Annotate item: Please register the following IMAP Annotate item:
[X] Entry [] Attribute [X] Entry [] Attribute
Name: /flags/\answered Name: /flags/\answered
Description: Defined in IMAP ANNOTATE extension document. Description: Defined in IMAP ANNOTATE extension document.
Contact person: Cyrus Daboo Contact person: Cyrus Daboo
email: daboo@isamet.com email: daboo@isamet.com
5.2.3 /flags/\flagged 5.2.3 /flags/\\flagged
To: iana@iana.org To: iana@iana.org
Subject: IMAP Annotate Registration Subject: IMAP Annotate Registration
Please register the following IMAP Annotate item: Please register the following IMAP Annotate item:
[X] Entry [] Attribute [X] Entry [] Attribute
Name: /flags/\flagged Name: /flags/\flagged
Description: Defined in IMAP ANNOTATE extension document. Description: Defined in IMAP ANNOTATE extension document.
Contact person: Cyrus Daboo Contact person: Cyrus Daboo
email: daboo@isamet.com email: daboo@isamet.com
5.2.4 /flags/\deleted 5.2.4 /flags/\\deleted
To: iana@iana.org To: iana@iana.org
Subject: IMAP Annotate Registration Subject: IMAP Annotate Registration
Please register the following IMAP Annotate item: Please register the following IMAP Annotate item:
[X] Entry [] Attribute [X] Entry [] Attribute
Name: /flags/\deleted Name: /flags/\deleted
Description: Defined in IMAP ANNOTATE extension document. Description: Defined in IMAP ANNOTATE extension document.
Contact person: Cyrus Daboo Contact person: Cyrus Daboo
email: daboo@isamet.com email: daboo@isamet.com
5.2.5 /flags/\seen 5.2.5 /flags/\\seen
To: iana@iana.org To: iana@iana.org
Subject: IMAP Annotate Registration Subject: IMAP Annotate Registration
Please register the following IMAP Annotate item: Please register the following IMAP Annotate item:
[X] Entry [] Attribute [X] Entry [] Attribute
Name: /flags/\seen Name: /flags/\seen
Description: Defined in IMAP ANNOTATE extension document. Description: Defined in IMAP ANNOTATE extension document.
Contact person: Cyrus Daboo Contact person: Cyrus Daboo
email: daboo@isamet.com email: daboo@isamet.com
5.2.6 /flags/\draft 5.2.6 /flags/\\draft
To: iana@iana.org To: iana@iana.org
Subject: IMAP Annotate Registration Subject: IMAP Annotate Registration
Please register the following IMAP Annotate item: Please register the following IMAP Annotate item:
[X] Entry [] Attribute [X] Entry [] Attribute
Name: /flags/\draft Name: /flags/\draft
Description: Defined in IMAP ANNOTATE extension document. Description: Defined in IMAP ANNOTATE extension document.
Contact person: Cyrus Daboo Contact person: Cyrus Daboo
email: daboo@isamet.com email: daboo@isamet.com
5.2.7 /flags/\recent 5.2.7 /flags/\\recent
To: iana@iana.org To: iana@iana.org
Subject: IMAP Annotate Registration Subject: IMAP Annotate Registration
Please register the following IMAP Annotate item: Please register the following IMAP Annotate item:
[X] Entry [] Attribute [X] Entry [] Attribute
Name: /flags/\recent Name: /flags/\recent
skipping to change at page 33, line 41 skipping to change at page 36, line 41
Name: content-language Name: content-language
Description: Defined in IMAP ANNOTATE extension document. Description: Defined in IMAP ANNOTATE extension document.
Contact person: Cyrus Daboo Contact person: Cyrus Daboo
email: daboo@isamet.com email: daboo@isamet.com
6. Security Considerations 6. Security Considerations
Care must be taken to ensure that annotations whose values are Annotations whose values are intended to remain private MUST be
intended to remain private are not stored in mailboxes which are stored in .priv values, and not .shared values which may be
accessible to other users. This includes mailboxes owned by the user accessible to other users.
by whose ACLs permit access by others as well as any shared
mailboxes.
Excluding the above issues the ANNOTATE extension does not raise any Excluding the above issues the ANNOTATE extension does not raise any
security considerations that are not present in the base [IMAP4] security considerations that are not present in the base IMAP
protocol, and these issues are discussed in [IMAP4]. protocol, and these issues are discussed in [RFC3501].
7. References 7. References
7.1 Normative References 7.1 Normative References
[RFC1891] Moore, K., "SMTP Service Extension for Delivery Status [RFC1891] Moore, K., "SMTP Service Extension for Delivery Status
Notifications", RFC 1891, January 1996. Notifications", RFC 1891, January 1996.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996.
[RFC2086] Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997. Specifications: ABNF", RFC 2234, November 1997.
[RFC2244] Newman, C. and J. Myers, "ACAP -- Application [RFC2244] Newman, C. and J. Myers, "ACAP -- Application
Configuration Access Protocol", RFC 2244, November 1997. Configuration Access Protocol", RFC 2244, November 1997.
[RFC3282] Alvestrand, H., "Content Language Headers", RFC 3282, May [RFC3282] Alvestrand, H., "Content Language Headers", RFC 3282, May
skipping to change at page 34, line 45 skipping to change at page 38, line 5
Protocol - Sort and Thread Extension", Protocol - Sort and Thread Extension",
draft-ietf-imapext-sort-17.txt, May 2004. draft-ietf-imapext-sort-17.txt, May 2004.
7.2 Informative References 7.2 Informative References
[CONDSTORE] [CONDSTORE]
Melnikov, A. and S. Hole, "IMAP Extension for Conditional Melnikov, A. and S. Hole, "IMAP Extension for Conditional
STORE operation", draft-ietf-imapext-condstore-05.txt, STORE operation", draft-ietf-imapext-condstore-05.txt,
November 2003. November 2003.
[RFC2086] Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997.
Authors' Addresses Authors' Addresses
Randall Gellens Randall Gellens
QUALCOMM Incorporated QUALCOMM Incorporated
5775 Morehouse Dr. 5775 Morehouse Dr.
San Diego, CA 92121-2779 San Diego, CA 92121-2779
US US
EMail: randy@qualcomm.com EMail: randy@qualcomm.com
 End of changes. 54 change blocks. 
127 lines changed or deleted 228 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/