Network Working Group C. King
Internet-Draft A. Melnikov
Intended status: Standards Track Isode Ltd
Expires: December 20, 2008 June 18, 2008
IMAP4 extension for named searches (filters)
draft-melnikov-imapext-filters-04.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 December 20, 2008.
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.
King & Melnikov Expires December 20, 2008 [Page 1]
Internet-Draft IMAP filters June 2008
Table of Contents
1. Conventions Used in this Document . . . . . . . . . . . . . . 3
2. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 3
3.1. Registration of a new server entries . . . . . . . . . . . 3
3.2. FILTER SEARCH criterion . . . . . . . . . . . . . . . . . 5
4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 6
5. Security Considerations . . . . . . . . . . . . . . . . . . . 6
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9
8. Normative References . . . . . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9
Intellectual Property and Copyright Statements . . . . . . . . . . 11
King & Melnikov Expires December 20, 2008 [Page 2]
Internet-Draft IMAP filters June 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-I04-FILTERS"
[[anchor4: Note to RFC editor: change upon publication to FILTERS]]
as one of the supported capabilities in the CAPABILITY response or
response code.
Any server compliant with this extension MUST also implement the
METADATA-SERVER [METADATA].
3. IMAP Protocol Changes
3.1. Registration of a new server entries
This document reserves hierarchy of per-server entries under the
"/private/filters" and "/public/filters" roots (see [METADATA]) for
storing named searches (a.k.a. "filters"). The value 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 values of all search keys stored in this annotation MUST be
encoded in UTF-8.
King & Melnikov Expires December 20, 2008 [Page 3]
Internet-Draft IMAP filters June 2008
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>" entry (or in the "/public/filters/
<filter_name>", if the "/private/filters/<filter_name>" entry doesn't
exist) using the SETMETADATA [METADATA] command. A filter can be
deleted by storing the NIL value in both the "/private/filters/
<filter_name>" and the "/public/filters/<filter_name>" entries. 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.2). Otherwise the
non-NIL value is used.
C: a SETMETADATA "" ("/private/filters/on-the-road"
"OR SMALLER 5000 FROM \"boss@example.com\"")
S: a OK SETMETADATA complete
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)'.
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
King & Melnikov Expires December 20, 2008 [Page 4]
Internet-Draft IMAP filters June 2008
name of the filter as its description.
3.2. FILTER SEARCH criterion
The FILTER criterion for the SEARCH command allows a client to
reference a filter stored on the server by name. A filter called
"<filter_name>" is stored in the server annotation named "/private/
filters/<filter_name>" (or in the entry "/public/filters/
<filter_name>", if "/private/filters/<filter_name>" doesn't exist) as
described in Section 3.1.
Syntax: FILTER <filter_name>
When the named filter exist, its search criteria (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" is as defined in the example from
Section 3.1.
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 criteria referenced by
the FILTER search key is a full and correct search criteria. For
example, the server should fail the SEARCH command if its SEARCH
criteria references a filter containing "OR SMALLER" search criteria,
because this value lacking one parameter and thus is not a fully
specified search criteria.
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 criteria. 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).
King & Melnikov Expires December 20, 2008 [Page 5]
Internet-Draft IMAP filters June 2008
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]).
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].
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-I04-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
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
King & Melnikov Expires December 20, 2008 [Page 6]
Internet-Draft IMAP filters June 2008
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/... annotations 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-I04-FILTERS [[anchor8: 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 2 entries to the
[METADATA] registry:
To: iana@iana.org
Subject: IMAP METADATA Entry Registration
Type: Server
Name: /private/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
King & Melnikov Expires December 20, 2008 [Page 7]
Internet-Draft IMAP filters June 2008
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
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.
King & Melnikov Expires December 20, 2008 [Page 8]
Internet-Draft IMAP filters June 2008
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.
Authors' Addresses
Curtis King
Isode Ltd
5 Castle Business Village
36 Station Road
Hampton, Middlesex TW12 2BX
UK
Email: Curtis.King@isode.com
King & Melnikov Expires December 20, 2008 [Page 9]
Internet-Draft IMAP filters June 2008
Alexey Melnikov
Isode Ltd
5 Castle Business Village
36 Station Road
Hampton, Middlesex TW12 2BX
UK
Email: Alexey.Melnikov@isode.com
King & Melnikov Expires December 20, 2008 [Page 10]
Internet-Draft IMAP filters June 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.
King & Melnikov Expires December 20, 2008 [Page 11]
