Network Working Group                                            C. King
Internet-Draft                                               A. Melnikov
Intended status: Standards Track                               Isode Ltd
Expires: November 15, 2007                                  May 14, 2007

              IMAP4 extension for named searches (filters)

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-

   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

   The list of Internet-Draft Shadow Directories can be accessed at

   This Internet-Draft will expire on November 15, 2007.

Copyright Notice

   Copyright (C) The IETF Trust (2007).


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

King & Melnikov         Expires November 15, 2007               [Page 1]

Internet-Draft                IMAP filters                      May 2007

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  . . . . . . . . . . . . . . . . .  4
   4.  Formal Syntax  . . . . . . . . . . . . . . . . . . . . . . . .  5
   5.  Security Considerations  . . . . . . . . . . . . . . . . . . .  6
   6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  6
   7.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . .  8
   8.  Normative References . . . . . . . . . . . . . . . . . . . . .  8
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . .  8
   Intellectual Property and Copyright Statements . . . . . . . . . . 10

King & Melnikov         Expires November 15, 2007               [Page 2]

Internet-Draft                IMAP filters                      May 2007

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

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   document are to be interpreted as described in [RFC2119].

   [[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-I01-FILTERS"
   [[anchor4: Change upon publication]] as one of the supported
   capabilities in the CAPABILITY command response.

3.  IMAP Protocol Changes

3.1.  Registration of a new server entries

   This document reserves hierarchy of entries under the "/filters" root
   for storing named searches (a.k.a. "filters").  The "value"
   ("value.priv" or "value.shared") attribute of a "/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 ABNF for the "filter-name" non-terminal.

   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
   "value.priv" or "value.shared" attribute of a "/filters/
   <filter_name>" entry using the SETMETADATA [METADATA] command.  A
   filter can be deleted by storing the NIL value in the
   "value.priv"/"value.shared" attribute of the "/filters/<filter_name>"
   entry.  A filter can be renamed by first creating a filter with the

King & Melnikov         Expires November 15, 2007               [Page 3]

Internet-Draft                IMAP filters                      May 2007

   new name and then deleting filter with the old one.

   If both "value.priv" and "value.shared" attributes exist for a
   "/filters/<filter_name>" server annotation, then the "value.priv" is
   used when evaluating the corresponding FILTER SEARCH key (see
   Section 3.2).  Otherwise the non-NIL value is used.

           C: a SETMETADATA "" "/filters/on-the-road"
               (value.priv "OR SMALLER 5000
                   FROM \"\"")
           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 allow clients for partial
   parsing of 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 ">" x-dsfa from 5' should be stored
   as 'from ">" (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 entries under the "/filter-
   descriptions" root.  The "value" attribute of a "/filter-
   descriptions/<filter_name>" server annotation is a human readable
   description for the <filter_name> filter, encoded in UTF-8 [UTF-8].
   In the absence of "/filter-descriptions/<filter_name>" the client MAY
   display the 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 "/filters/
   <filter_name>" as described in Section 3.1.

   Syntax: FILTER <filter_name>

   When the named filter exist, its search criteria (i.e. the associated
   "value" attribute) is inserted verbatum instead of the FILTER search-
   key.  For example, the following SEARCH command

King & Melnikov         Expires November 15, 2007               [Page 4]

Internet-Draft                IMAP filters                      May 2007

   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 ""
   SINCE " 3-Dec-2002"

   assuming the filter "on-the-road" is as defined in 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

   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.

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

   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.

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.

King & Melnikov         Expires November 15, 2007               [Page 5]

Internet-Draft                IMAP filters                      May 2007

   capability         =/ "X-DRAFT-I01-FILTERS"
                         ;; [[Note to RFC Editor: change the capability
                         ;; name before publication]]

                         [[anchor6: IMAPABNF only defines "search-
                         program", which includes the charset]]

   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] are also relevant to this document.

   Note that excessive use of filters can potentially simplify DoS
   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 should use TLS and/or SASL security layer (or
   similar) as recommended in [RFC3501].

   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

King & Melnikov         Expires November 15, 2007               [Page 6]

Internet-Draft                IMAP filters                      May 2007

   This document defines the X-DRAFT-I01-FILTERS [[anchor9: Note to RFC
   Editor: fix before publication]] 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:


   Subject:  IMAP METADATA Registration

      Please register the following IMAP METADATA item:

      [x] Entry [ ] Attribute

      [ ] Mailbox [x] Server

   Name:  /filters/<filter_name>

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

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

   Contact person:  Alexey Melnikov



   Subject:  IMAP METADATA Registration

      Please register the following IMAP METADATA item:

      [x] Entry [ ] Attribute

      [ ] Mailbox [x] Server

   Name:  /filter-descriptions/<filter_name>

   Description:  Contains a human readable description of a named SEARCH
      criteria stored in the /filters/<filter_name> annotation.  The
      value is in UTF-8.  Defined in RFC XXXX.

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

King & Melnikov         Expires November 15, 2007               [Page 7]

Internet-Draft                IMAP filters                      May 2007

   Contact person:  Alexey Melnikov


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.

              Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
              ABNF", RFC 4466, April 2006.

              Daboo, C., "IMAP ANNOTATEMORE Extension",
              draft-daboo-imap-annotatemore-09 (work in progress),
              March 2006.

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

              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


King & Melnikov         Expires November 15, 2007               [Page 8]

Internet-Draft                IMAP filters                      May 2007

   Alexey Melnikov
   Isode Ltd
   5 Castle Business Village
   36 Station Road
   Hampton, Middlesex  TW12 2BX


King & Melnikov         Expires November 15, 2007               [Page 9]

Internet-Draft                IMAP filters                      May 2007

Full Copyright Statement

   Copyright (C) The IETF Trust (2007).

   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

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

   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


   Funding for the RFC Editor function is provided by the IETF
   Administrative Support Activity (IASA).

King & Melnikov         Expires November 15, 2007              [Page 10]