IMAP4 Extension for Named Searches (Filters)
draft-melnikov-imapext-filters-08

Network Working Group                                        A. Melnikov
Internet-Draft                                                   C. King
Intended status: Standards Track                               Isode Ltd
Expires: June 14, 2009                                 December 11, 2008

              IMAP4 extension for named searches (filters)
                 draft-melnikov-imapext-filters-08.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 June 14, 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 criterion as a parameter.

Melnikov & King           Expires June 14, 2009                 [Page 1]
Internet-Draft                IMAP filters                 December 2008

Table of Contents

   1.  Conventions Used in this Document  . . . . . . . . . . . . . .  3
   2.  Introduction and Overview  . . . . . . . . . . . . . . . . . .  3
   3.  IMAP Protocol Changes  . . . . . . . . . . . . . . . . . . . .  4
     3.1.  FILTER SEARCH criterion  . . . . . . . . . . . . . . . . .  4
     3.2.  Managing filters using SETMETADATA/GETMETADATA commands  .  5
   4.  Formal Syntax  . . . . . . . . . . . . . . . . . . . . . . . .  7
   5.  Security Considerations  . . . . . . . . . . . . . . . . . . .  7
   6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  8
   7.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 10
   8.  Normative References . . . . . . . . . . . . . . . . . . . . . 10
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11
   Intellectual Property and Copyright Statements . . . . . . . . . . 12

Melnikov & King           Expires June 14, 2009                 [Page 2]
Internet-Draft                IMAP filters                 December 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 "X-DRAFT-I06-FILTERS" IMAP extension [[anchor4: Note to RFC
   editor: change upon publication to FILTERS]] adds a new FILTER search
   criterion for referencing persistent named searches (a.k.a.
   "filters"), as well as reuses GETMETADATA/SETMETADATA commands
   [METADATA] for listing/creating/updating/deleting such filters.

   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 types with the same name exist, the FILTER SEARCH criterion
   (see Section 3.1) MUST use the value of the private filter, otherwise
   it MUST use the value of the filter that exists.

   Let us call a pair of filter name and filter type a "typed filter".
   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 SETMETADATA command
   creates or updates the value and/or the description of a typed
   filter.

   Values of all search keys stored in a filter MUST be encoded in
   UTF-8.

Melnikov & King           Expires June 14, 2009                 [Page 3]
Internet-Draft                IMAP filters                 December 2008

3.  IMAP Protocol Changes

   The IMAP extension for persistent named searches is present in any
   IMAP4 implementation which advertises "X-DRAFT-I06-FILTERS"
   [[anchor6: Note to RFC editor: change upon publication to FILTERS]]
   as one of the supported capabilities in the CAPABILITY response or
   response code.

3.1.  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 by setting the server annotation named "/private/filters/
   values/<filter_name>" (or the server annotation "/public/filters/
   values/<filter_name>", if "/private/filters/values/<filter_name>"
   doesn't exist) using the SETMETADATA command as described in
   Section 3.2.

   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 OR 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
   criterion references a filter containing "OR SMALLER" search
   criterion, 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

Melnikov & King           Expires June 14, 2009                 [Page 4]
Internet-Draft                IMAP filters                 December 2008

   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.2.  Managing filters using SETMETADATA/GETMETADATA commands

   Any server compliant with this document MUST either implement the
   METADATA-SERVER (or METADATA) [METADATA] extension, or implement
   SETMETADATA/GETMETADATA commands described in [METADATA] so that they
   work for the case of empty mailbox name (i.e. for managing server
   annotations) and entries specified in this section.

   This document reserves hierarchy of per-server entries under the
   "/private/filters/values" and "/public/filters/values" roots (see
   [METADATA]) for storing filter values.  The value of a "/private/
   filters/values/<filter_name>" or a "/public/filters/values/
   <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 these entries 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/values/<filter_name>" server entry (or in the "/public/
   filters/values/<filter_name>") using the SETMETADATA [METADATA]
   command.  The server SHOULD verify that each search criterion stored
   in such server entry is a full and correct search criterion.

   A filter can be deleted by storing the NIL value in both the
   "/private/filters/values/<filter_name>" and the "/public/filters/
   values/<filter_name>" entries.

   A filter can be renamed by first creating a filter with the new name
   (that has the same value as the old one) and then deleting filter
   with the old one.

Melnikov & King           Expires June 14, 2009                 [Page 5]
Internet-Draft                IMAP filters                 December 2008

   If both "/private/filters/values/<filter_name>" and "/public/filters/
   values/<filter_name>" server annotations exist, then the value of the
   "/private/filters/values/<filter_name>" is used when evaluating the
   corresponding FILTER SEARCH key (see Section 3.1).  Otherwise the
   non-NIL (existent) value is used.

   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, as defined in [METADATA].

           C: a007 SETMETADATA "" ("/private/filters/values/on-the-road"
               "OR SMALLER 5000 FROM \"boss@example.com\"")
           S: a007 OK SETMETADATA complete

   Client 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 criterion '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/filters/descriptions" and "/public/filters/descriptions"
   roots.  The value of a "/private/filters/descriptions/<filter_name>"
   or a "/public/filters/descriptions/<filter_name>" server annotation
   is a human readable description for the <filter_name> filter, encoded
   in UTF-8 [UTF-8].  If the "/private/filters/descriptions/
   <filter_name>" server annotation exists, its value is used by the
   client as the filter description.  Otherwise the value of the
   "/public/filters/descriptions/<filter_name>" server annotation is
   used as the filter description.  In the absence of both the
   "/private/filters/descriptions/<filter_name>" and the "/public/
   filters/descriptions/<filter_name>" entry the client MAY display the
   name of the filter as its description.

   The description string SHOULD be annotated with one or more language
   tags [RFC4646] as specified in Chapter 16.9 of [Unicode].  In the
   absence of any language tag, the "i-default" [RFC2277] language

Melnikov & King           Expires June 14, 2009                 [Page 6]
Internet-Draft                IMAP filters                 December 2008

   SHOULD be assumed.  Description in multiple languages MAY be present
   in a single description string.  This is done by concatenating
   descriptions in multiple languages into a single string, each
   description prefixed with its language tag, for example
   "<ru><...description in Russian...><fr-ca><...description in
   French...>".  Note that here <ru> is a language tag consisting of 3
   Unicode characters: <U+E0001>, <U+E0072>, <U+E0075>; and <fr-ca> is a
   language tag consisting of 6 Unicode characters: <U+E0001>,
   <U+E0066>, <U+E0072> <U+E002D>, <U+E0063> <U+E0061>.

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-I06-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.

Melnikov & King           Expires June 14, 2009                 [Page 7]
Internet-Draft                IMAP filters                 December 2008

   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-I06-FILTERS [[anchor9: 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/values/<filter_name>

   Description:  Contains an IMAP SEARCH criteria.  Defined in RFC XXXX.

   Content-type:  text/plain; charset=utf-8

   Contact person:  Alexey Melnikov

Melnikov & King           Expires June 14, 2009                 [Page 8]
Internet-Draft                IMAP filters                 December 2008

   Email:  alexey.melnikov@isode.com

   To:  iana@iana.org

   Subject:  IMAP METADATA Entry Registration

   Type:  Server

   Name:  /public/filters/values/<filter_name>

   Description:  Contains an IMAP SEARCH criterion.  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/filters/descriptions/<filter_name>

   Description:  Contains a user specific human readable description of
      a named SEARCH criterion stored in the /private/filters/values/
      <filter_name> or /public/filters/values/<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/filters/descriptions/<filter_name>

Melnikov & King           Expires June 14, 2009                 [Page 9]
Internet-Draft                IMAP filters                 December 2008

   Description:  Contains a global (shared among all users) human
      readable description of a named SEARCH criterion stored in the
      /private/filters/values/<filter_name> or /public/filters/values/
      <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.  Special thank you to Brian E.
   Carpenter for the GenArt review.

8.  Normative References

   [ABNF]     Crocker, D., Ed. and P. Overell, Ed., "Augmented BNF for
              Syntax Specifications: ABNF", RFC 5234, January 2008.

   [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-16 (work in progress),
              November 2008.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2277]  Alvestrand, H., "IETF Policy on Character Sets and
              Languages", RFC 2277, January 1998.

   [RFC3501]  Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
              4rev1", RFC 3501, March 2003.

   [RFC4646]  Phillips, A. and M. Davis, "Tags for Identifying
              Languages", RFC 4646, September 2006.

   [UTF-8]    Yergeau, F., "UTF-8, a transformation format of ISO
              10646", RFC 3629, November 2003.

Melnikov & King           Expires June 14, 2009                [Page 10]
Internet-Draft                IMAP filters                 December 2008

   [Unicode]  "The Unicode Standard 5.0", Unicode 5.0, 2007.

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 June 14, 2009                [Page 11]
Internet-Draft                IMAP filters                 December 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 June 14, 2009                [Page 12]