Network Working Group A. Melnikov
Internet-Draft C. King
Intended status: Standards Track Isode Ltd
Expires: January 6, 2009 July 5, 2008
IMAP4 extension for named searches (filters)
draft-melnikov-imapext-filters-05.txt
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on January 6, 2009.
Abstract
The document defines a way to persistently store named IMAP (RFC
3501) searches on the server. Such named searches can be
subsequently referenced in a SEARCH or any other command that accepts
a search criteria as a parameter.
Melnikov & King Expires January 6, 2009 [Page 1]
Internet-Draft IMAP filters July 2008
Table of Contents
1. Conventions Used in this Document . . . . . . . . . . . . . . 3
2. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 3
3.1. LISTFILTERS command . . . . . . . . . . . . . . . . . . . 3
3.2. SETFILTER command . . . . . . . . . . . . . . . . . . . . 4
3.3. DELETEFILTER command . . . . . . . . . . . . . . . . . . . 5
3.4. FILTER SEARCH criterion . . . . . . . . . . . . . . . . . 6
3.5. Additional requirements on servers that also implement
METADATA-SERVER extension . . . . . . . . . . . . . . . . 7
4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 8
5. Security Considerations . . . . . . . . . . . . . . . . . . . 10
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12
8. Normative References . . . . . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13
Intellectual Property and Copyright Statements . . . . . . . . . . 14
Melnikov & King Expires January 6, 2009 [Page 2]
Internet-Draft IMAP filters July 2008
1. Conventions Used in this Document
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively. If a single "C:" or "S:" label applies to
multiple lines, then the line breaks between those lines are for
editorial clarity only and are not part of the actual protocol
exchange.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
Basic familiarity with the METADATA-SERVER extension [METADATA] and
terms defined therein is required to understand this document.
[[anchor2: Editorial comments and questions are marked like this.]]
2. Introduction and Overview
Persistent named searches described in this document allow clients to
save favourite searches on the server. Such saved searches can save
bandwidth for clients that need to regularly repeat them.
The IMAP extension for persistent named searches is present in any
IMAP4 implementation which advertises "X-DRAFT-I05-FILTERS"
[[anchor4: Note to RFC editor: change upon publication to FILTERS]]
as one of the supported capabilities in the CAPABILITY response or
response code.
3. IMAP Protocol Changes
The "X-DRAFT-I05-FILTERS" IMAP extension [[anchor6: Note to RFC
editor: change upon publication to FILTERS]] adds a new command for
listing defined named searches (a.k.a. "filters") (LISTFILTERS), a
new command for creating named searches (SETFILTER), a new command
for deleting them (DELETEFILTER) and a new FILTER search criterion
for referencing such named searches.
[[anchor7: Is RENAMEFILTER needed?]]
3.1. LISTFILTERS command
Melnikov & King Expires January 6, 2009 [Page 3]
Internet-Draft IMAP filters July 2008
Arguments: OPTIONAL filter name
Responses: untagged responses: FILTER
Result: OK - LISTFILTERS command completed
BAD - unrecognized syntax of an argument,
unexpected extra argument, missing argument, etc.
The LISTFILTERS returns either the value and description of the
specified filter (if the filter name parameter is specified) or
values/descriptions of all existing filters (when no parameter is
specified). Each filter definition is returned in a separate
untagged FILTER response.
The LISTFILTERS command is available in Authenticated and Selected
states.
C: a001 LISTFILTERS
S: * FILTER private "on-the-road" "OR SMALLER 5000 FROM
\"boss@example.com\"" "The filter to be used for
downloading small messages from my boss on
mobile phone"
S: a001 OK LISTFILTERS complete
3.2. SETFILTER command
Arguments: filter name
filter type
search criteria
OPTIONAL filter description
Responses: no specific response for this command
Result: OK - SETFILTER command completed
NO - SETFILTER failed to create or update the specified
filter
BAD - unrecognized syntax of an argument,
unexpected extra argument, missing argument, etc.
A filter can be private (only accessible to the logged in user) or
public (accessible to all logged in users). Both a private and a
public filter with the same name can exist at the same time. If both
filter type with the same exist, the FILTER SEARCH criterion (see
Section 3.4) is going to use the value of the private filter,
otherwise it will use the value of the filter that exists.
Let us call a pair of filter name and filter type a "typed filter".
Melnikov & King Expires January 6, 2009 [Page 4]
Internet-Draft IMAP filters July 2008
Each typed filter can have a value (which is a valid IMAP SEARCH
criteria conforming to ABNF for the "search-criteria" non-terminal)
and an optional human readable description. The SETFILTER command
creates or updates the value and/or the description of a typed
filter. If the filter parameter is not specified, the filter
description is set to the empty string.
If the server is unable to create a new typed filter because the
maximum number of allowed filters has already been reached, the
server MUST return a tagged NO response with a "[METADATA TOOMANY]"
response code.
A filter name is governed by the ABNF for the "filter-name" non-
terminal.
Values of all search keys stored in a filter MUST be encoded in
UTF-8.
Implementation note: As multiple client might read and write filter
values, it is possible that one client will use a SEARCH key that
might not be recognized by another client that tries to present a UI
for editing a filter value. In order to help other clients to
[partially] parse filter values for editing purposes, a client
storing a filter value SHOULD use () around any SEARCH key not
defined in [RFC3501] For example, if there is an IMAP extension that
defines a new x-dsfa SEARCH key that takes 2 parameters, then the
following SEARCH criteria 'from "@example.com>" x-dsfa from 5' should
be stored as 'from "@example.com>" (x-dsfa from 5)'.
The SETFILTER command is available in Authenticated and Selected
states.
C: a002 SETFILTER private "on-the-road"
"OR SMALLER 5000 FROM \"boss@example.com\""
S: a002 OK SETFILTER completed
3.3. DELETEFILTER command
Arguments: filter name
filter type
Responses: no specific response for this command
Result: OK - DELETEFILTER command completed
NO - DELETEFILTER failed to delete the specified filter
BAD - unrecognized syntax of an argument,
unexpected extra argument, missing argument, etc.
Melnikov & King Expires January 6, 2009 [Page 5]
Internet-Draft IMAP filters July 2008
The DELETEFILTER command deletes a typed filter (and its description)
previously created with SETFILTER command (or by setting the
"/private/filters/<filter_name>" or the "/public/filters/
<filter_name>" server annotation as described in Section 3.5).
The DELETEFILTER command is available in Authenticated and Selected
states.
C: a003 DELETEFILTER private "on-the-road"
S: a003 OK DELETEFILTER completed
C: a004 DELETEFILTER public "on-the-road"
S: a004 OK DELETEFILTER completed
3.4. FILTER SEARCH criterion
The FILTER criterion for the SEARCH command allows a client to
reference by name a filter stored on the server. Such filter was
created using the SETFILTER command, or by setting the server
annotation named "/private/filters/<filter_name>" (or the server
annotation "/public/filters/<filter_name>", if "/private/filters/
<filter_name>" doesn't exist) as described in Section 3.5.
Syntax: FILTER <filter_name>
When the named filter exist, its search criterion (i.e. the
associated entry value) is inserted verbatum instead of the FILTER
search-key. For example, the following SEARCH command
C: a SEARCH UID 300:900 FILTER on-the-road SINCE " 3-Dec-2002"
would be equivalent to the following
C: a SEARCH UID 300:900 SMALLER 5000 FROM "boss@example.com"
SINCE " 3-Dec-2002"
assuming the filter "on-the-road" exists and contains the value 'OR
SMALLER 5000 FROM "boss@example.com"'.
A reference to a non-existent or unaccessible (e.g. due to access
control restrictions) filter MUST cause failure of the SEARCH command
with the tagged NO response, that includes the UNDEFINED-FILTER
response code followed by the name of the non-existent/unaccessible
filter.
Note the server SHOULD verify that each search criterion referenced
by the FILTER search key is a full and correct search criterion. For
example, the server should fail the SEARCH command if its SEARCH
Melnikov & King Expires January 6, 2009 [Page 6]
Internet-Draft IMAP filters July 2008
criterion references a filter containing "OR SMALLER" search
criteria, because this value is lacking one parameter and thus is not
a fully specified search criterion.
Note that a named filter itself can reference another filter using
the FILTER search-key. Implementations MUST be able to perform at
least 3 substitution passes on the SEARCH command criterion. If an
implementation allows for more passes, it MUST implement some kind of
loop detection. If an implementation detects a loop or still sees a
FILTER search-key after performing at least 3 substitutions, it MUST
behave as if the specified filter doesn't exist (as described above).
Note that use of the FILTER search key implies the CHARSET "UTF-8"
parameter to the SEARCH/UID SEARCH command. If the SEARCH/UID SEARCH
command includes the explicit CHARSET parameter with the value other
than "UTF-8" or "US-ASCII" then such command MUST result in the
tagged BAD response from the server. Such tagged response MUST
contain the BADCHARSET response code (see [RFC3501]).
3.5. Additional requirements on servers that also implement METADATA-
SERVER extension
Any server compliant that also implement the METADATA-SERVER
[METADATA] extension MUST comply with the additional requirements
specified in this section.
This document reserves hierarchy of per-server entries under the
"/private/filters" and "/public/filters" roots (see [METADATA]) for
storing filters. The value of a "/private/filters/<filter_name>" or
a "/public/filters/<filter_name>" server annotation is an IMAP SEARCH
criteria, conforming to ABNF for the "search-criteria" non-terminal.
A name of a filter is governed by the ABNF for the "filter-name" non-
terminal. Note that the value of a filter created with SETFILTER
command can be retrieved by reading the corresponding "/private/
filters/<filter_name>" or "/public/filters/<filter_name>" server
annotation and vice versa, the value of a filter created by setting
"/private/filters/<filter_name>" or "/public/filters/<filter_name>"
can be retrieved using the LISTFILTERS command.
Note that values of all search keys stored in this annotation MUST be
encoded in UTF-8.
A new filter named "<filter_name>" can be created (or an existing
filter can be modified) by storing a non NIL value in the "/private/
filters/<filter_name>" server entry (or in the "/public/filters/
<filter_name>") using the SETMETADATA [METADATA] command. This is
the same as calling the SETFILTER command with omitted filter
description parameter.
Melnikov & King Expires January 6, 2009 [Page 7]
Internet-Draft IMAP filters July 2008
A filter can be deleted by storing the NIL value in both the
"/private/filters/<filter_name>" and the "/public/filters/
<filter_name>" entries. This is the same as calling the
"DELETEFILTER filter_name private" command followed by "DELETEFILTER
filter_name public".
A filter can be renamed by first creating a filter with the new name
and then deleting filter with the old one.
If both "/private/filters/<filter_name>" and "/public/filters/
<filter_name>" server annotations exist, then the value of the
"/private/filters/<filter_name>" is used when evaluating the
corresponding FILTER SEARCH key (see Section 3.4). Otherwise the
non-NIL value is used.
C: a007 SETMETADATA "" ("/private/filters/on-the-road"
"OR SMALLER 5000 FROM \"boss@example.com\"")
S: a007 OK SETMETADATA complete
This command is equivalent to SETFILTER private "on-the-road" ...
Note that filter names are restricted to a subset of US-ASCII, as
described in Section 4. So they might not always be meaningful to
users and thus not necessarily suitable for display purposes. In
order to help with storing human readable descriptions of filters,
this document also reserves hierarchy of server entries under the
"/private/filter-descriptions" and "/public/filter-descriptions"
roots. The value of a "/private/filter-descriptions/<filter_name>"
or a "/public/filter-descriptions/<filter_name>" server annotation is
a human readable description for the <filter_name> filter, encoded in
UTF-8 [UTF-8]. If the "/private/filter-descriptions/<filter_name>"
server annotation exists, its value is used by the client as the
filter description. Otherwise the value of the "/public/
filter-descriptions/<filter_name>" server annotation is used as the
filter description. In the absence of both the "/private/
filter-descriptions/<filter_name>" and the "/public/
filter-descriptions/<filter_name>" entry the client MAY display the
name of the filter as its description.
4. Formal Syntax
The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) notation as specified in [ABNF].
Non-terminals referenced but not defined below are as defined by
[RFC3501] or [IMAPABNF].
Melnikov & King Expires January 6, 2009 [Page 8]
Internet-Draft IMAP filters July 2008
Except as noted otherwise, all alphabetic characters are case-
insensitive. The use of upper or lower case characters to define
token strings is for editorial clarity only. Implementations MUST
accept these strings in a case-insensitive fashion.
capability =/ "X-DRAFT-I05-FILTERS"
;; [[Note to RFC Editor: change the capability
;; name before publication]]
search-criteria = search-key *(SP search-key)
search-key =/ "FILTER" SP filter-name
;; New SEARCH criterion for referencing filters
filter-name = 1*<any ATOM-CHAR except "/">
;; Note that filter-name disallows UTF-8 or
;; the following characters: "(", ")", "{",
;; " ", "%", "*", "]". See definition of
;; ATOM-CHAR [RFC3501].
resp-text-code =/ "UNDEFINED-FILTER" SP filter-name
response-payload =/ filter-resp
filter-resp = filter-type SP filter-name SP
filter-value SP filter-desc
filter-type = "PUBLIC" / "PRIVATE"
filter-value = astring
;;<search-criteria> represented as <astring>
filter-desc = astring
;;Human readable description of the filter.
;;Empty string, if no description is defined.
command-auth =/ listfilters / setfilter / deletefilter
listfilters = "LISTFILTERS" [SP filter-name]
setfilter = "SETFILTER" SP filter-name SP filter-type
filter-value [SP filter-desc]
deletefilter = "DELETEFILTER" SP filter-name SP filter-type
Melnikov & King Expires January 6, 2009 [Page 9]
Internet-Draft IMAP filters July 2008
5. Security Considerations
General issues relevant to [RFC3501] (in particular to the SEARCH
command) and METADATA-SERVER extension [METADATA] are also relevant
to this document.
Note that excessive use of filters can potentially simplify deny-of-
service attacks, especially if combined with poor implementations and
lack of loop detection (i.e. detection of filters referencing each
other to create a loop). Servers that allow for anonymous access
SHOULD NOT allow anonymous users to create/edit/delete filters.
Also note that stored filters can potentially dislose personal
information about users. When confidentiality of such information is
important, clients MUST use TLS and/or SASL security layer (or
similar) as recommended in [RFC3501]. Also clients should use
private filters instead of public, unless they desire to share such
information with other users.
As always, it is important to thoroughly test clients and servers
when implementing this extension.
6. IANA Considerations
IMAP4 capabilities are registered by publishing a standards track or
IESG approved experimental RFC. The registry is currently located
at:
http://www.iana.org/assignments/imap4-capabilities
This document defines the X-DRAFT-I05-FILTERS [[anchor12: Note to RFC
Editor: change before publication to FILTERS]] IMAP capability. IANA
is requested to add it to the registry.
IANA is also requested to add the following 4 entries to the
[METADATA] registry:
To: iana@iana.org
Subject: IMAP METADATA Entry Registration
Type: Server
Name: /private/filters/<filter_name>
Melnikov & King Expires January 6, 2009 [Page 10]
Internet-Draft IMAP filters July 2008
Description: Contains an IMAP SEARCH criteria. Defined in RFC XXXX.
Content-type: text/plain; charset=utf-8
Contact person: Alexey Melnikov
Email: alexey.melnikov@isode.com
To: iana@iana.org
Subject: IMAP METADATA Entry Registration
Type: Server
Name: /public/filters/<filter_name>
Description: Contains an IMAP SEARCH criteria. Defined in RFC XXXX.
Content-type: text/plain; charset=utf-8
Contact person: Alexey Melnikov
Email: alexey.melnikov@isode.com
To: iana@iana.org
Subject: IMAP METADATA Entry Registration
Type: Server
Name: /private/filter-descriptions/<filter_name>
Description: Contains a user specific human readable description of
a named SEARCH criteria stored in the /private/filters/
<filter_name> or /public/filters/<filter_name> annotation. The
value is in UTF-8. Defined in RFC XXXX.
Content-type: text/plain; charset=utf-8
Contact person: Alexey Melnikov
Email: alexey.melnikov@isode.com
To: iana@iana.org
Melnikov & King Expires January 6, 2009 [Page 11]
Internet-Draft IMAP filters July 2008
Subject: IMAP METADATA Entry Registration
Type: Server
Name: /public/filter-descriptions/<filter_name>
Description: Contains a global (shared among all users) human
readable description of a named SEARCH criteria stored in the
/private/filters/<filter_name> or /public/filters/<filter_name>
annotation. The value is in UTF-8. Defined in RFC XXXX.
Content-type: text/plain; charset=utf-8
Contact person: Alexey Melnikov
Email: alexey.melnikov@isode.com
7. Acknowledgments
Thanks to David Cridland and Arnt Gulbrandsen for comments and
suggestions on this document.
8. Normative References
[ABNF] Crocker, D., Ed. and P. Overell, Ed., "Augmented BNF for
Syntax Specifications: ABNF", RFC 4234, October 2005.
[IMAPABNF]
Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
ABNF", RFC 4466, April 2006.
[METADATA]
Daboo, C., "IMAP METADATA Extension",
draft-daboo-imap-annotatemore-13 (work in progress),
April 2008.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.
[UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
10646", RFC 3629, November 2003.
Melnikov & King Expires January 6, 2009 [Page 12]
Internet-Draft IMAP filters July 2008
Authors' Addresses
Alexey Melnikov
Isode Ltd
5 Castle Business Village
36 Station Road
Hampton, Middlesex TW12 2BX
UK
Email: Alexey.Melnikov@isode.com
Curtis King
Isode Ltd
5 Castle Business Village
36 Station Road
Hampton, Middlesex TW12 2BX
UK
Email: Curtis.King@isode.com
Melnikov & King Expires January 6, 2009 [Page 13]
Internet-Draft IMAP filters July 2008
Full Copyright Statement
Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Melnikov & King Expires January 6, 2009 [Page 14]
