< draft-daboo-imap-annotatemore-16.txt   draft-daboo-imap-annotatemore-17.txt >
Network Working Group C. Daboo Network Working Group C. Daboo
Internet-Draft Apple, Inc. Internet-Draft Apple, Inc.
Intended status: Standards Track November 18, 2008 Intended status: Standards Track December 11, 2008
Expires: May 22, 2009 Expires: June 14, 2009
IMAP METADATA Extension IMAP METADATA Extension
draft-daboo-imap-annotatemore-16 draft-daboo-imap-annotatemore-17
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware 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 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. aware will be disclosed, in accordance with Section 6 of BCP 79.
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
skipping to change at page 1, line 34 skipping to change at page 1, line 34
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 May 22, 2009. This Internet-Draft will expire on June 14, 2009.
Abstract Abstract
The METADATA extension to the Internet Message Access Protocol The METADATA extension to the Internet Message Access Protocol
permits clients and servers to maintain "annotations" or "meta data" permits clients and servers to maintain "annotations" or "meta data"
on IMAP servers. It is possible to have annotations on a per-mailbox on IMAP servers. It is possible to have annotations on a per-mailbox
basis or on the server as a whole. For example, this would allow basis or on the server as a whole. For example, this would allow
comments about the purpose of a particular mailbox to be "attached" comments about the purpose of a particular mailbox to be "attached"
to that mailbox, or a "message of the day" containing server status to that mailbox, or a "message of the day" containing server status
information to be made available to anyone logging in to the server. information to be made available to anyone logging in to the server.
Table of Contents Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
2. Conventions Used in This Document . . . . . . . . . . . . . . 3 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
3. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.2. Namespace of entries . . . . . . . . . . . . . . . . . . . 4 3.2. Namespace of entries . . . . . . . . . . . . . . . . . . . 4
3.2.1. Entry Names . . . . . . . . . . . . . . . . . . . . . 5 3.2.1. Entry Names . . . . . . . . . . . . . . . . . . . . . 5
3.3. Private versus Public and Access Control . . . . . . . . . 6 3.3. Private versus Shared and Access Control . . . . . . . . . 6
4. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 7 4. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 7
4.1. General Considerations . . . . . . . . . . . . . . . . . . 7 4.1. General Considerations . . . . . . . . . . . . . . . . . . 7
4.2. GETMETADATA Command . . . . . . . . . . . . . . . . . . . 8 4.2. GETMETADATA Command . . . . . . . . . . . . . . . . . . . 8
4.2.1. MAXSIZE GETMETADATA Command Option . . . . . . . . . . 9 4.2.1. MAXSIZE GETMETADATA Command Option . . . . . . . . . . 9
4.2.2. DEPTH GETMETADATA Command Option . . . . . . . . . . . 9 4.2.2. DEPTH GETMETADATA Command Option . . . . . . . . . . . 10
4.3. SETMETADATA Command . . . . . . . . . . . . . . . . . . . 10 4.3. SETMETADATA Command . . . . . . . . . . . . . . . . . . . 10
4.4. METADATA Response . . . . . . . . . . . . . . . . . . . . 12 4.4. METADATA Response . . . . . . . . . . . . . . . . . . . . 12
4.4.1. METADATA response with values . . . . . . . . . . . . 12 4.4.1. METADATA response with values . . . . . . . . . . . . 13
4.4.2. Unsolicited METADATA response without values . . . . . 13 4.4.2. Unsolicited METADATA response without values . . . . . 13
5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 14 5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 14
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
6.1. Entry and Attribute Registration Template . . . . . . . . 16 6.1. Entry and Attribute Registration Template . . . . . . . . 16
6.2. Server Entry Registrations . . . . . . . . . . . . . . . . 16 6.2. Server Entry Registrations . . . . . . . . . . . . . . . . 16
6.2.1. /public/comment . . . . . . . . . . . . . . . . . . . 16 6.2.1. /shared/comment . . . . . . . . . . . . . . . . . . . 17
6.2.2. /public/admin . . . . . . . . . . . . . . . . . . . . 17 6.2.2. /shared/admin . . . . . . . . . . . . . . . . . . . . 17
6.3. Mailbox Entry Registrations . . . . . . . . . . . . . . . 17 6.3. Mailbox Entry Registrations . . . . . . . . . . . . . . . 17
6.3.1. /public/comment . . . . . . . . . . . . . . . . . . . 17 6.3.1. /shared/comment . . . . . . . . . . . . . . . . . . . 18
6.3.2. /private/comment . . . . . . . . . . . . . . . . . . . 18 6.3.2. /private/comment . . . . . . . . . . . . . . . . . . . 18
7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18
8. Normative References . . . . . . . . . . . . . . . . . . . . . 18 8. Normative References . . . . . . . . . . . . . . . . . . . . . 19
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 19 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 19
Appendix B. Change History (to be removed prior to Appendix B. Change History (to be removed prior to
publication as an RFC) . . . . . . . . . . . . . . . 19 publication as an RFC) . . . . . . . . . . . . . . . 19
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 23
Intellectual Property and Copyright Statements . . . . . . . . . . 24 Intellectual Property and Copyright Statements . . . . . . . . . . 24
1. Introduction and Overview 1. Introduction and Overview
The goal of the METADATA extension is to provide a means for clients The goal of the METADATA extension is to provide a means for clients
to set and retrieve "annotations" or "meta data" on an IMAP server. to set and retrieve "annotations" or "meta data" on an IMAP server.
The annotations can be associated with specific mailboxes or the The annotations can be associated with specific mailboxes or the
server as a whole. The server can choose to support only server server as a whole. The server can choose to support only server
annotations or both server and mailbox annotations. annotations or both server and mailbox annotations.
skipping to change at page 4, line 51 skipping to change at page 4, line 51
Use of control or punctuation characters in entry names is strongly Use of control or punctuation characters in entry names is strongly
discouraged. discouraged.
This specification defines an initial set of entry names available This specification defines an initial set of entry names available
for use with mailbox and server annotations. In addition an for use with mailbox and server annotations. In addition an
extension mechanism is described to allow additional names to be extension mechanism is described to allow additional names to be
added for extensibility. added for extensibility.
The first component in entry names defines the scope of the The first component in entry names defines the scope of the
annotation. Currently only the prefixes "/private" or "/public" are annotation. Currently only the prefixes "/private" or "/shared" are
defined. These prefixes are used to indicate whether an annotation defined. These prefixes are used to indicate whether an annotation
is stored on a per-user basis ("/private") and not visible to other is stored on a per-user basis ("/private") and not visible to other
users, or whether an annotation is shared between authorized users users, or whether an annotation is shared between authorized users
("/public") with a single value that can be read and changed by ("/shared") with a single value that can be read and changed by
authorized users with appropriate access. See Section 3.3 for authorized users with appropriate access. See Section 3.3 for
details. details.
Entry names can have any number of components starting at 2, unless
they fall under the vendor namespaces (i.e., have /shared/vendor/
<vendor-token> or /private/vendor/<vendor-token> prefix as described
below), in which case they have at least 4 components.
3.2.1. Entry Names 3.2.1. Entry Names
Entry names MUST be specified in a standards track or IESG approved Entry names MUST be specified in a standards track or IESG approved
experimental RFC, or fall under the vendor namespace. See experimental RFC, or fall under the vendor namespace. See
Section 6.1 for the registration template. Section 6.1 for the registration template.
3.2.1.1. Server Entries 3.2.1.1. Server Entries
These entries are set or retrieved when the mailbox name argument to These entries are set or retrieved when the mailbox name argument to
the new SETMETADATA or GETMETATDATA commands is the empty string. the new SETMETADATA or GETMETATDATA commands is the empty string.
/public/comment /shared/comment
Defines a comment or note associated with the server shared with Defines a comment or note associated with the server shared with
authorized users of the server. authorized users of the server.
/public/admin /shared/admin
Indicates a method for contacting the server administrator. The Indicates a method for contacting the server administrator. The
value MUST be a URI (e.g., a mailto: or tel: URL). This entry is value MUST be a URI (e.g., a mailto: or tel: URL). This entry is
always read-only - clients cannot change it. It is visible to always read-only - clients cannot change it. It is visible to
authorized users of the system. authorized users of the system.
/public/vendor/<vendor-token> /shared/vendor/<vendor-token>
Defines the top-level of public entries associated with the server Defines the top-level of shared entries associated with the server
as created by a particular product of some vendor. This entry can as created by a particular product of some vendor. This entry can
be used by vendors to provide server or client specific be used by vendors to provide server or client specific
annotations. The vendor-token MUST be registered with IANA, using annotations. The vendor-token MUST be registered with IANA, using
the ACAP [RFC2244] vendor subtree registry. the ACAP [RFC2244] vendor subtree registry.
/private/vendor/<vendor-token> /private/vendor/<vendor-token>
Defines the top-level of private entries associated with the Defines the top-level of private entries associated with the
server as created by a particular product of some vendor. This server as created by a particular product of some vendor. This
entry can be used by vendors to provide server or client specific entry can be used by vendors to provide server or client specific
annotations. The vendor-token MUST be registered with IANA, using annotations. The vendor-token MUST be registered with IANA, using
the ACAP [RFC2244] vendor subtree registry. the ACAP [RFC2244] vendor subtree registry.
3.2.1.2. Mailbox Entries 3.2.1.2. Mailbox Entries
These entries are set or retrieved when the mailbox name argument to These entries are set or retrieved when the mailbox name argument to
the new SETMETADATA or GETMETADATA commands is not the empty string. the new SETMETADATA or GETMETADATA commands is not the empty string.
/public/comment /shared/comment
Defines a public comment or note associated with a mailbox. Defines a shared comment or note associated with a mailbox.
/private/comment /private/comment
Defines a private (per-user) comment or note associated with a Defines a private (per-user) comment or note associated with a
mailbox. mailbox.
/public/vendor/<vendor-token> /shared/vendor/<vendor-token>
Defines the top-level of public entries associated with a specific Defines the top-level of shared entries associated with a specific
mailbox as created by a particular product of some vendor. This mailbox as created by a particular product of some vendor. This
entry can be used by vendors to provide client specific entry can be used by vendors to provide client specific
annotations. The vendor-token MUST be registered with IANA, using annotations. The vendor-token MUST be registered with IANA, using
the ACAP [RFC2244] vendor subtree registry. the ACAP [RFC2244] vendor subtree registry.
/private/vendor/<vendor-token> /private/vendor/<vendor-token>
Defines the top-level of private entries associated with a Defines the top-level of private entries associated with a
specific mailbox as created by a particular product of some specific mailbox as created by a particular product of some
vendor. This entry can be used by vendors to provide client vendor. This entry can be used by vendors to provide client
specific annotations. The vendor-token MUST be registered with specific annotations. The vendor-token MUST be registered with
IANA, using the ACAP [RFC2244] vendor subtree registry. IANA, using the ACAP [RFC2244] vendor subtree registry.
3.3. Private versus Public and Access Control 3.3. Private versus Shared and Access Control
In the absence of the ACL extension [RFC4314], users can only set and In the absence of the ACL extension [RFC4314], users can only set and
retrieve private or public mailbox annotations on a mailbox which retrieve private or shared mailbox annotations on a mailbox which
exists and is returned to them via a LIST or LSUB command, and on exists and is returned to them via a LIST or LSUB command, and on
which they have either read or write access to the actual message which they have either read or write access to the actual message
content of the mailbox (as determined by the READ-ONLY and READ-WRITE content of the mailbox (as determined by the READ-ONLY and READ-WRITE
response codes as described in Section 5.2 of [RFC4314]). response codes as described in Section 5.2 of [RFC4314]).
When the ACL extension [RFC4314] is present, users can only set and When the ACL extension [RFC4314] is present, users can only set and
retrieve private or public mailbox annotations on a mailbox on which retrieve private or shared mailbox annotations on a mailbox on which
they have the "l" right, and any one of the "r", "s", "w", "i" or "p" they have the "l" right, and any one of the "r", "s", "w", "i" or "p"
rights. rights.
If a client attempts to set or retrieve annotations on mailboxes If a client attempts to set or retrieve annotations on mailboxes
which do not satisfy the conditions above, the server MUST respond which do not satisfy the conditions above, the server MUST respond
with a NO response. with a NO response.
Users can always retrieve private or public server annotations if Users can always retrieve private or shared server annotations if
they exist. Servers MAY restrict the creation of private or public they exist. Servers MAY restrict the creation of private or shared
server annotations as appropriate. When restricted, the server MUST server annotations as appropriate. When restricted, the server MUST
return a NO response when the SETMETADATA command is used to try and return a NO response when the SETMETADATA command is used to try and
create a server annotation. create a server annotation.
If the METADATA extension is present, support for public annotations If the METADATA extension is present, support for shared annotations
is REQUIRED, whilst support for private annotations is OPTIONAL. is REQUIRED, whilst support for private annotations is OPTIONAL.
This recognizes the fact that support for private annotations may This recognizes the fact that support for private annotations may
introduce significantly more complexity to a server in terms of introduce significantly more complexity to a server in terms of
tracking ownership of the annotations, how quota is determined for tracking ownership of the annotations, how quota is determined for
users based on their own annotations etc. users based on their own annotations etc.
4. IMAP Protocol Changes 4. IMAP Protocol Changes
4.1. General Considerations 4.1. General Considerations
skipping to change at page 7, line 35 skipping to change at page 7, line 41
existing mailbox does not inherit the old mailbox annotations. existing mailbox does not inherit the old mailbox annotations.
Servers SHOULD allow annotations on all 'types' of mailbox, including Servers SHOULD allow annotations on all 'types' of mailbox, including
ones reporting \Noselect for their LIST response. Servers can ones reporting \Noselect for their LIST response. Servers can
implicitly remove \Noselect mailboxes when all child mailboxes are implicitly remove \Noselect mailboxes when all child mailboxes are
removed, and as such any annotations associated with the \Noselect removed, and as such any annotations associated with the \Noselect
mailbox SHOULD be removed. mailbox SHOULD be removed.
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 mailbox or annotation or the total number of annotations for a single mailbox or
for the server as a whole. However, the server MUST accept a minimum for the server as a whole. However, the server MUST accept an
annotation data size of at least 1024 bytes, and a minimum annotation annotation data size of at least 1024 bytes, and an annotation count
count per server or mailbox of at least 10. per server or mailbox of at least 10.
Some annotations may be "read-only" - i.e., they are set by the Some annotations may be "read-only" - i.e., they are set by the
server and cannot be changed by the client. Also, such annotations server and cannot be changed by the client. Also, such annotations
may be "computed" - i.e., the value changes based on underlying may be "computed" - i.e., the value changes based on underlying
properties of the mailbox or server. For example, an annotation properties of the mailbox or server. For example, an annotation
reporting the total size of all messages in the mailbox would change reporting the total size of all messages in the mailbox would change
as messages are added or removed. Or, an annotation containing an as messages are added or removed. Or, an annotation containing an
IMAP URL for the mailbox would change if the mailbox was renamed. IMAP URL for the mailbox would change if the mailbox was renamed.
Servers MAY support sending unsolicited responses for use when Servers MAY support sending unsolicited responses for use when
skipping to change at page 8, line 35 skipping to change at page 8, line 41
BAD - command unknown or arguments invalid BAD - command unknown or arguments invalid
When the mailbox name is the empty string, this command retrieves When the mailbox name is the empty string, this command retrieves
server annotations. When the mailbox name is not empty, this command server annotations. When the mailbox name is not empty, this command
retrieves annotations on the specified mailbox. retrieves annotations on the specified mailbox.
Options MAY be included with this command and are defined below. Options MAY be included with this command and are defined below.
Example: Example:
C: a GETMETADATA "" /public/comment C: a GETMETADATA "" /shared/comment
S: * METADATA "" (/public/comment "Shared comment") S: * METADATA "" (/shared/comment "Shared comment")
S: a OK GETMETADATA complete S: a OK GETMETADATA complete
In the above example, the contents of the value of the "/public/ In the above example, the contents of the value of the "/shared/
comment" server entry is requested by the client and returned by comment" server entry is requested by the client and returned by
the server. the server.
Example: Example:
C: a GETMETADATA "INBOX" /private/comment C: a GETMETADATA "INBOX" /private/comment
S: * METADATA "INBOX" (/private/comment "My own comment") S: * METADATA "INBOX" (/private/comment "My own comment")
S: a OK GETMETADATA complete S: a OK GETMETADATA complete
In the above example, the contents of the value of the "/private/ In the above example, the contents of the value of the "/private/
comment" mailbox entry for the mailbox "INBOX" is requested by the comment" mailbox entry for the mailbox "INBOX" is requested by the
client and returned by the server. client and returned by the server.
Entry specifiers can be lists of atomic specifiers, so that multiple Entry specifiers can be lists of atomic specifiers, so that multiple
annotations may be returned in a single GETMETADATA command. annotations may be returned in a single GETMETADATA command.
Example: Example:
C: a GETMETADATA "INBOX" (/public/comment /private/comment) C: a GETMETADATA "INBOX" (/shared/comment /private/comment)
S: * METADATA "INBOX" (/public/comment "Shared comment" S: * METADATA "INBOX" (/shared/comment "Shared comment"
/private/comment "My own comment") /private/comment "My own comment")
S: a OK GETMETADATA complete S: a OK GETMETADATA complete
In the above example, the values of the two server entries In the above example, the values of the two server entries
"/public/comment" and "/private/comment" on the mailbox "inbox" "/shared/comment" and "/private/comment" on the mailbox "inbox"
are requested by the client and returned by the server. are requested by the client and returned by the server.
4.2.1. MAXSIZE GETMETADATA Command Option 4.2.1. MAXSIZE GETMETADATA Command Option
When MAXSIZE option is specified with the GETMETADATA command, it When MAXSIZE option is specified with the GETMETADATA command, it
restricts which entry values are returned by the server. Only entry restricts which entry values are returned by the server. Only entry
values which are less than or equal in octet size to the specified values which are less than or equal in octet size to the specified
MAXSIZE limit are returned. If there are any entries with values MAXSIZE limit are returned. If there are any entries with values
larger than the MAXSIZE limit, the server MUST include the METADATA larger than the MAXSIZE limit, the server MUST include the METADATA
LONGENTRIES response code in the tagged OK response for the LONGENTRIES response code in the tagged OK response for the
GETMETADATA command. The METADATA LONGENTRIES response code returns GETMETADATA command. The METADATA LONGENTRIES response code returns
the size of the biggest entry value requested by the client which the size of the biggest entry value requested by the client which
exceeded the MAXSIZE limit. exceeded the MAXSIZE limit.
Example: Example:
C: a GETMETADATA "INBOX" (MAXSIZE 1024) C: a GETMETADATA "INBOX" (MAXSIZE 1024)
(/public/comment /private/comment) (/shared/comment /private/comment)
S: * METADATA "INBOX" (/private/comment "My own comment") S: * METADATA "INBOX" (/private/comment "My own comment")
S: a OK [METADATA LONGENTRIES 2199] GETMETADATA complete S: a OK [METADATA LONGENTRIES 2199] GETMETADATA complete
In the above example, the values of the two server entries In the above example, the values of the two server entries
"/public/comment" and "/private/comment" on the mailbox "inbox" "/shared/comment" and "/private/comment" on the mailbox "inbox"
are requested by the client which wants to restrict the size of are requested by the client which wants to restrict the size of
returned values to 1024 octets. In this case the "/public/ returned values to 1024 octets. In this case the "/shared/
comment" entry value is 2199 octets and is not returned. comment" entry value is 2199 octets and is not returned.
4.2.2. DEPTH GETMETADATA Command Option 4.2.2. DEPTH GETMETADATA Command Option
When DEPTH option is specified with the GETMETADATA command, it When DEPTH option is specified with the GETMETADATA command, it
extends the list of entry values returned by the server. For each extends the list of entry values returned by the server. For each
entry name specified in the GETMETADATA command, the server returns entry name specified in the GETMETADATA command, the server returns
the value of the specified entry name (if it exists), plus all the value of the specified entry name (if it exists), plus all
entries below the entry name up to the specified DEPTH. Three values entries below the entry name up to the specified DEPTH. Three values
are allowed for DEPTH: are allowed for DEPTH:
skipping to change at page 10, line 4 skipping to change at page 10, line 13
comment" entry value is 2199 octets and is not returned. comment" entry value is 2199 octets and is not returned.
4.2.2. DEPTH GETMETADATA Command Option 4.2.2. DEPTH GETMETADATA Command Option
When DEPTH option is specified with the GETMETADATA command, it When DEPTH option is specified with the GETMETADATA command, it
extends the list of entry values returned by the server. For each extends the list of entry values returned by the server. For each
entry name specified in the GETMETADATA command, the server returns entry name specified in the GETMETADATA command, the server returns
the value of the specified entry name (if it exists), plus all the value of the specified entry name (if it exists), plus all
entries below the entry name up to the specified DEPTH. Three values entries below the entry name up to the specified DEPTH. Three values
are allowed for DEPTH: are allowed for DEPTH:
"0" - no entries below the specified entry are returned "0" - no entries below the specified entry are returned
"1" - only entries immediately below the specified entry are "1" - only entries immediately below the specified entry are
returned returned
"infinity" - all entries below the specified entry are returned "infinity" - all entries below the specified entry are returned
Thus, "depth 1" for an entry "/a" will match "/a" as well as its Thus, "depth 1" for an entry "/a" will match "/a" as well as its
children entries (e.g. "/a/b"), but will not match grandchildren children entries (e.g., "/a/b"), but will not match grandchildren
entries (e.g. "/a/b/c"). entries (e.g., "/a/b/c").
If the DEPTH option is not specified, this is the same as specifying If the DEPTH option is not specified, this is the same as specifying
"DEPTH 0". "DEPTH 0".
Example: Example:
C: a GETMETADATA "INBOX" (DEPTH 1) C: a GETMETADATA "INBOX" (DEPTH 1)
(/private/filters/values) (/private/filters/values)
S: * METADATA "INBOX" (/private/filters/values/small S: * METADATA "INBOX" (/private/filters/values/small
"SMALLER 5000" /private/filters/values/boss "SMALLER 5000" /private/filters/values/boss
skipping to change at page 12, line 8 skipping to change at page 12, line 23
In the above example, the entry "/private/comment" is removed from In the above example, the entry "/private/comment" is removed from
the mailbox "INBOX". the mailbox "INBOX".
Multiple entries can be set in a single SETMETADATA command by Multiple entries can be set in a single SETMETADATA command by
listing entry-value pairs in the list. listing entry-value pairs in the list.
Example: Example:
C: a SETMETADATA INBOX (/private/comment "My new comment" C: a SETMETADATA INBOX (/private/comment "My new comment"
/public/comment "This one is for you!") /shared/comment "This one is for you!")
S: a OK SETMETADATA complete S: a OK SETMETADATA complete
In the above example, the entries "/private/comment" and "/public/ In the above example, the entries "/private/comment" and "/shared/
comment" for the mailbox "INBOX" are created (if not already comment" for the mailbox "INBOX" are created (if not already
present) and the values set as specified. present) and the values set as specified.
Example: Example:
C: a SETMETADATA INBOX (/private/comment "My new comment") C: a SETMETADATA INBOX (/private/comment "My new comment")
S: a NO [METADATA TOOMANY] SETMETADATA failed S: a NO [METADATA TOOMANY] SETMETADATA failed
In the above example, the server is unable to set the requested In the above example, the server is unable to set the requested
(new) annotation as it has reached the limit on the number of (new) annotation as it has reached the limit on the number of
skipping to change at page 13, line 5 skipping to change at page 13, line 18
This response is only available in authenticated or selected state This response is only available in authenticated or selected state
[RFC3501]. [RFC3501].
4.4.1. METADATA response with values 4.4.1. METADATA response with values
The response consists of a list of entry-value pairs. The response consists of a list of entry-value pairs.
Example: Example:
C: a GETMETADATA "" /public/comment C: a GETMETADATA "" /shared/comment
S: * METADATA "" (/public/comment "My comment") S: * METADATA "" (/shared/comment "My comment")
S: a OK GETMETADATA complete S: a OK GETMETADATA complete
In the above example, a single entry with its value is returned by In the above example, a single entry with its value is returned by
the server. the server.
Example: Example:
C: a GETMETADATA "INBOX" /private/comment /public/comment C: a GETMETADATA "INBOX" /private/comment /shared/comment
S: * METADATA "INBOX" (/private/comment "My comment" S: * METADATA "INBOX" (/private/comment "My comment"
/public/comment "Its sunny outside!") /shared/comment "Its sunny outside!")
S: a OK GETMETADATA complete S: a OK GETMETADATA complete
In the above example, two entries and their values are returned by In the above example, two entries and their values are returned by
the server. the server.
Example: Example:
C: a GETMETADATA "INBOX" /private/comment /public/comment C: a GETMETADATA "INBOX" /private/comment /shared/comment
S: * METADATA "INBOX" (/private/comment "My comment") S: * METADATA "INBOX" (/private/comment "My comment")
S: * METADATA "INBOX" (/public/comment "Its sunny outside!") S: * METADATA "INBOX" (/shared/comment "Its sunny outside!")
S: a OK GETMETADATA complete S: a OK GETMETADATA complete
In the above example, the server returns two separate responses In the above example, the server returns two separate responses
for each of the two entries requested. for each of the two entries requested.
4.4.2. Unsolicited METADATA response without values 4.4.2. Unsolicited METADATA response without values
The response consists of a list of entries, each of which have The response consists of a list of entries, each of which have
changed on the server or mailbox. changed on the server or mailbox.
Example: Example:
C: a NOOP C: a NOOP
S: * METADATA "" /public/comment S: * METADATA "" /shared/comment
S: a OK NOOP complete S: a OK NOOP complete
In the above example, the server indicates that the "/public/ In the above example, the server indicates that the "/shared/
comment" server entry has been changed. comment" server entry has been changed.
Example: Example:
C: a NOOP C: a NOOP
S: * METADATA "INBOX" /public/comment /private/comment S: * METADATA "INBOX" /shared/comment /private/comment
S: a OK NOOP complete S: a OK NOOP complete
In the above example, the server indicates a change to two mailbox In the above example, the server indicates a change to two mailbox
entries. entries.
5. Formal Syntax 5. 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 [RFC5234]. Form (ABNF) notation as specified in [RFC5234].
Non-terminals referenced but not defined below are as defined by Non-terminals referenced but not defined below are as defined by
[RFC3501] with the new definitions in [RFC4466] superseding those in [RFC3501] with the new definitions in [RFC4466] superseding those in
[RFC3501]. [RFC3501].
Except as noted otherwise, all alphabetic characters are case- Except as noted otherwise, all alphabetic characters are case-
insensitive. The use of upper or lower case characters to define insensitive. The use of upper or lower case characters to define
token strings is for editorial clarity only. Implementations MUST token strings is for editorial clarity only. Implementations MUST
accept these strings in a case-insensitive fashion. accept these strings in a case-insensitive fashion.
capability =/ "METADATA" / "METADATA-SERVER" / capability =/ "METADATA" / "METADATA-SERVER"
"METADATA-UNSOLICITED"
; defines the capabilities for this extension ; defines the capabilities for this extension
command-auth =/ setmetadata / getmetadata command-auth =/ setmetadata / getmetadata
; adds to original IMAP command ; adds to original IMAP command
entries = entry / entries = entry /
"(" entry *(SP entry) ")" "(" entry *(SP entry) ")"
; entry specifiers ; entry specifiers
entry = astring entry = astring
skipping to change at page 15, line 40 skipping to change at page 16, line 7
setmetadata = "SETMETADATA" SP mailbox setmetadata = "SETMETADATA" SP mailbox
SP entry-values SP entry-values
; empty string for mailbox implies ; empty string for mailbox implies
; server annotation. ; server annotation.
value = nstring / literal8 value = nstring / literal8
6. IANA Considerations 6. IANA Considerations
All entries MUST have either "/shared" or "/private" as a prefix.
Entry names MUST be specified in a standards track or IESG approved Entry names MUST be specified in a standards track or IESG approved
experimental RFC, or fall under the vendor namespace. All entries experimental RFC, or fall under the vendor namespace (i.e., use
MUST have either "/public" or "/private" as a prefix. /shared/vendor/<vendor-token> or /private/vendor/<vendor-token> as
the prefix).
Each entry registration MUST include a content-type that is used to Each entry registration MUST include a content-type that is used to
indicate the nature of the annotation value. Where applicable a indicate the nature of the annotation value. Where applicable a
charset parameter MUST be included with the content-type. charset parameter MUST be included with the content-type.
6.1. Entry and Attribute Registration Template 6.1. Entry and Attribute Registration Template
To: iana@iana.org To: iana@iana.org
Subject: IMAP METADATA Entry Registration Subject: IMAP METADATA Entry Registration
skipping to change at page 16, line 28 skipping to change at page 17, line 5
RFC Number: [for entries published as RFCs] RFC Number: [for entries published as RFCs]
Contact: [email and/or physical address to contact for Contact: [email and/or physical address to contact for
additional information] additional information]
6.2. Server Entry Registrations 6.2. Server Entry Registrations
The following templates specify the IANA registrations of annotation The following templates specify the IANA registrations of annotation
entries specified in this document. entries specified in this document.
6.2.1. /public/comment 6.2.1. /shared/comment
To: iana@iana.org To: iana@iana.org
Subject: IMAP METADATA Entry Registration Subject: IMAP METADATA Entry Registration
Type: Server Type: Server
Name: /public/comment Name: /shared/comment
Description: Defines a comment or note associated with the Description: Defines a comment or note associated with the
server shared with authorized users of the server. server shared with authorized users of the server.
Content-type: text/plain; charset=utf-8 Content-type: text/plain; charset=utf-8
RFC Number: This RFC. RFC Number: This RFC.
Contact: IMAP Extensions mailto:ietf-imapext@imc.org Contact: IMAP Extensions mailto:ietf-imapext@imc.org
6.2.2. /public/admin 6.2.2. /shared/admin
To: iana@iana.org To: iana@iana.org
Subject: IMAP METADATA Entry Registration Subject: IMAP METADATA Entry Registration
Type: Server Type: Server
Name: /public/admin Name: /shared/admin
Description: Indicates a method for contacting the server Description: Indicates a method for contacting the server
administrator. The value MUST be a URI (e.g., a administrator. The value MUST be a URI (e.g., a
mailto: or tel: URL). This entry is always mailto: or tel: URL). This entry is always
read-only - clients cannot change it. It is visible read-only - clients cannot change it. It is visible
to authorized users of the system. to authorized users of the system.
Content-type: text/plain; charset=utf-8 Content-type: text/plain; charset=utf-8
RFC Number: This RFC. RFC Number: This RFC.
Contact: IMAP Extensions mailto:ietf-imapext@imc.org Contact: IMAP Extensions mailto:ietf-imapext@imc.org
6.3. Mailbox Entry Registrations 6.3. Mailbox Entry Registrations
The following templates specify the IANA registrations of annotation The following templates specify the IANA registrations of annotation
entries specified in this document. entries specified in this document.
6.3.1. /public/comment 6.3.1. /shared/comment
To: iana@iana.org To: iana@iana.org
Subject: IMAP METADATA Entry Registration Subject: IMAP METADATA Entry Registration
Type: Mailbox Type: Mailbox
Name: /public/comment Name: /shared/comment
Description: Defines a public comment or note associated with a Description: Defines a shared comment or note associated with a
mailbox. mailbox.
Content-type: text/plain; charset=utf-8 Content-type: text/plain; charset=utf-8
RFC Number: This RFC. RFC Number: This RFC.
Contact: IMAP Extensions mailto:ietf-imapext@imc.org Contact: IMAP Extensions mailto:ietf-imapext@imc.org
6.3.2. /private/comment 6.3.2. /private/comment
skipping to change at page 18, line 25 skipping to change at page 18, line 43
mailbox. mailbox.
Content-type: text/plain; charset=utf-8 Content-type: text/plain; charset=utf-8
RFC Number: This RFC. RFC Number: This RFC.
Contact: IMAP Extensions mailto:ietf-imapext@imc.org Contact: IMAP Extensions mailto:ietf-imapext@imc.org
7. Security Considerations 7. Security Considerations
The security considerations in Section 11 of [RFC3501] apply with
respect to protecting annotations from snooping. Servers MAY choose
to only support the METADATA and/or METADATA-SERVER extensions after
a privacy layer has been negotiated by the client.
Annotations can contain arbitrary data of varying size. As such Annotations can contain arbitrary data of varying size. As such
servers MUST ensure that size limits are enforced to prevent a user servers MUST ensure that size limits are enforced to prevent a user
from using up all available space on a server and preventing use by from using up all available space on a server and preventing use by
others. Clients MUST treat annotation data values as an "untrusted" others. Clients MUST treat annotation data values as an "untrusted"
source of data as it is possible for it to contain malicious content. source of data as it is possible for it to contain malicious content.
Annotations whose values are intended to remain private MUST be Annotations whose values are intended to remain private MUST be
stored only in entries that have the "/private" prefix on the entry stored only in entries that have the "/private" prefix on the entry
name. Servers MUST ensure that /private annotations are only visible name.
to the user that created them.
Excluding the above issues the METADATA extension does not raise any Excluding the above issues the METADATA extension does not raise any
security considerations that are not present in the base IMAP security considerations that are not present in the base IMAP
protocol, and these issues are discussed in [RFC3501]. protocol, and these issues are discussed in [RFC3501].
8. Normative References 8. Normative References
[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.
skipping to change at page 19, line 21 skipping to change at page 19, line 41
[RFC5161] Gulbrandsen, A. and A. Melnikov, "The IMAP ENABLE [RFC5161] Gulbrandsen, A. and A. Melnikov, "The IMAP ENABLE
Extension", RFC 5161, March 2008. Extension", RFC 5161, March 2008.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. Specifications: ABNF", STD 68, RFC 5234, January 2008.
Appendix A. Acknowledgments Appendix A. Acknowledgments
The ideas expressed in this document are based on the message The ideas expressed in this document are based on the message
annotation document that was co-authored by Randall Gellens. The annotation document that was co-authored by Randall Gellens. The
participants of the IMAPext working group made significant author would like to thank the following individuals for contributing
contributions to this work. their ideas and support for writing this specification: Dave
Cridland, Arnt Gulbrandsen, Dan Karp, Alexey Melnikov, Ken Murchison,
Chris Newman, Michael Wener.
Appendix B. Change History (to be removed prior to publication as an Appendix B. Change History (to be removed prior to publication as an
RFC) RFC)
Changes from -16 to -17:
1. Removed "METADATA-UNSOLICITED" capability from ABNF.
2. Additional text added to Security Considerations to emphasize
3501 privacy statement.
3. Additional text added to clarify that multiple components can
appear in entry names.
4. Changed /public prefix to /shared.
5. Fixed minor Gen-ART review issues.
Changes from -15 to -16: Changes from -15 to -16:
1. Tweaked enable capability behavior. 1. Tweaked enable capability behavior.
2. Changed access control text to be more explicit about which ACL 2. Changed access control text to be more explicit about which ACL
privileges are required. privileges are required.
Changes from -14 to -15: Changes from -14 to -15:
1. Addressed minor issues from Gen-ART review on -12 version. 1. Addressed minor issues from Gen-ART review on -12 version.
2. Removed comparator paragraph - no need to specify how the server 2. Removed comparator paragraph - no need to specify how the server
does its comparisons. does its comparisons.
3. Added MAXSIZE GETMETADATA option. 3. Added MAXSIZE GETMETADATA option.
 End of changes. 58 change blocks. 
70 lines changed or deleted 90 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/