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/" or the "/public/filters/ " 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/" (or the server annotation "/public/filters/", if "/private/filters/ " doesn't exist) as described in Section 3.5. Syntax: FILTER 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/" or a "/public/filters/" 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/" or "/public/filters/" server annotation and vice versa, the value of a filter created by setting "/private/filters/" or "/public/filters/" 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 "" can be created (or an existing filter can be modified) by storing a non NIL value in the "/private/ filters/" server entry (or in the "/public/filters/ ") 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/" and the "/public/filters/ " 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/" and "/public/filters/ " server annotations exist, then the value of the "/private/filters/" 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/" or a "/public/filter-descriptions/" server annotation is a human readable description for the filter, encoded in UTF-8 [UTF-8]. If the "/private/filter-descriptions/" server annotation exists, its value is used by the client as the filter description. Otherwise the value of the "/public/ filter-descriptions/" server annotation is used as the filter description. In the absence of both the "/private/ filter-descriptions/" and the "/public/ filter-descriptions/" 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* ;; 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 ;; represented as 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/ 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/ 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/ Description: Contains a user specific human readable description of a named SEARCH criteria stored in the /private/filters/ or /public/filters/ 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/ Description: Contains a global (shared among all users) human readable description of a named SEARCH criteria stored in the /private/filters/ or /public/filters/ 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]