7Network Working Group A. Melnikov
8Request for Comments: 5466 C. King
9Category: Standards Track Isode Ltd
13 IMAP4 Extension for Named Searches (Filters)
17 This document specifies an Internet standards track protocol for the
18 Internet community, and requests discussion and suggestions for
19 improvements. Please refer to the current edition of the "Internet
20 Official Protocol Standards" (STD 1) for the standardization state
21 and status of this protocol. Distribution of this memo is unlimited.
25 Copyright (c) 2009 IETF Trust and the persons identified as the
26 document authors. All rights reserved.
28 This document is subject to BCP 78 and the IETF Trust's Legal
29 Provisions Relating to IETF Documents (http://trustee.ietf.org/
30 license-info) in effect on the date of publication of this document.
31 Please review these documents carefully, as they describe your rights
32 and restrictions with respect to this document.
36 The document defines a way to persistently store named IMAP (RFC
37 3501) searches on the server. Such named searches can be
38 subsequently referenced in a SEARCH or any other command that accepts
39 a search criterion as a parameter.
43 1. Introduction and Overview . . . . . . . . . . . . . . . . . . . 2
44 2. Conventions Used in This Document . . . . . . . . . . . . . . . 2
45 3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . . 2
46 3.1. FILTER SEARCH Criterion . . . . . . . . . . . . . . . . . . 3
47 3.2. Managing Filters Using SETMETADATA/GETMETADATA Commands . . 4
48 4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 6
49 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 6
50 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7
51 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 8
52 8. Normative References . . . . . . . . . . . . . . . . . . . . . 8
58Melnikov & King Standards Track [Page 1]
60RFC 5466 IMAP Filters February 2009
631. Introduction and Overview
65 Persistent named searches described in this document allow clients to
66 save favorite searches on the server. Such saved searches can save
67 bandwidth for clients that need to regularly repeat them.
69 The FILTERS IMAP extension adds a new FILTER search criterion for
70 referencing persistent named searches (a.k.a. "filters"), as well as
71 reuses GETMETADATA/SETMETADATA commands [METADATA] for listing/
72 creating/updating/deleting such filters.
74 A filter can be private (only accessible to the logged-in user) or
75 public (accessible to all logged-in users). Both a private and a
76 public filter with the same name can exist at the same time. If both
77 filter types with the same name exist, the FILTER SEARCH criterion
78 (see Section 3.1) MUST use the value of the private filter;
79 otherwise, it MUST use the value of the filter that exists.
81 Let us call a pair of filter name and filter type a "typed filter".
82 Each typed filter can have a value (which is a valid IMAP SEARCH
83 criteria conforming to ABNF for the "search-criteria" non-terminal)
84 and an optional human-readable description. The SETMETADATA command
85 creates or updates the value and/or the description of a typed
88 Values of all search keys stored in a filter MUST be encoded in
912. Conventions Used in This Document
93 In examples, "C:" and "S:" indicate lines sent by the client and
94 server, respectively. If a single "C:" or "S:" label applies to
95 multiple lines, then the line breaks between those lines are for
96 editorial clarity only and are not part of the actual protocol
99 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
100 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
101 document are to be interpreted as described in [RFC2119].
103 Basic familiarity with the METADATA-SERVER extension [METADATA] and
104 terms defined therein is required to understand this document.
1063. IMAP Protocol Changes
108 The IMAP extension for persistent named searches is present in any
109 IMAP4 implementation that advertises "FILTERS" as one of the
110 supported capabilities in the CAPABILITY response or response code.
114Melnikov & King Standards Track [Page 2]
116RFC 5466 IMAP Filters February 2009
1193.1. FILTER SEARCH Criterion
121 The FILTER criterion for the SEARCH command allows a client to
122 reference by name a filter stored on the server. Such filter was
123 created by setting the server annotation named "/private/filters/
124 values/<filter_name>" (or the server annotation "/shared/filters/
125 values/<filter_name>", if "/private/filters/values/<filter_name>"
126 doesn't exist) using the SETMETADATA command as described in
129 Syntax: FILTER <filter_name>
131 When the named filter exists, its search criterion (i.e., the
132 associated entry value) is inserted verbatim instead of the FILTER
133 search-key. For example, the following SEARCH command
135 C: a SEARCH UID 300:900 FILTER on-the-road SINCE "3-Dec-2002"
137 would be equivalent to the following
139 C: a SEARCH UID 300:900 OR SMALLER 5000 FROM "boss@example.com"
142 assuming the filter "on-the-road" exists and contains the value 'OR
143 SMALLER 5000 FROM "boss@example.com"'.
145 A reference to a nonexistent or unaccessible (e.g., due to access
146 control restrictions) filter MUST cause failure of the SEARCH command
147 with the tagged NO response that includes the UNDEFINED-FILTER
148 response code followed by the name of the nonexistent/unaccessible
151 Note the server SHOULD verify that each search criterion referenced
152 by the FILTER search key is a full and correct search criterion. For
153 example, the server should fail the SEARCH command if its SEARCH
154 criterion references a filter containing "OR SMALLER" search
155 criterion, because this value is lacking one parameter and thus is
156 not a fully specified search criterion.
158 Note that a named filter itself can reference another filter using
159 the FILTER search-key. Implementations MUST be able to perform at
160 least 3 substitution passes on the SEARCH command criterion. If an
161 implementation allows for more passes, it MUST implement some kind of
162 loop detection. If an implementation detects a loop or still sees a
163 FILTER search-key after performing at least 3 substitutions, it MUST
164 behave as if the specified filter doesn't exist (as described above).
170Melnikov & King Standards Track [Page 3]
172RFC 5466 IMAP Filters February 2009
175 Note that use of the FILTER search key implies the CHARSET "UTF-8"
176 parameter to the SEARCH/UID SEARCH command. If the SEARCH/UID SEARCH
177 command includes the explicit CHARSET parameter with the value other
178 than "UTF-8" or "US-ASCII", then such command MUST result in the
179 tagged BAD response from the server. Such tagged response MUST
180 contain the BADCHARSET response code (see [RFC3501]).
1823.2. Managing Filters Using SETMETADATA/GETMETADATA Commands
184 Any server compliant with this document MUST either implement the
185 METADATA-SERVER (or METADATA) [METADATA] extension, or implement
186 SETMETADATA/GETMETADATA commands described in [METADATA] so that they
187 work for the case of empty mailbox name (i.e., for managing server
188 annotations) and for the entries specified in this section.
190 This document reserves two hierarchies of per-server entries under
191 the "/private/filters/values" and "/shared/filters/values" roots (see
192 [METADATA]) for storing filter values. The value of a "/private/
193 filters/values/<filter_name>" or a "/shared/filters/values/
194 <filter_name>" server annotation is an IMAP SEARCH criteria,
195 conforming to ABNF for the "search-criteria" non-terminal. A name of
196 a filter is governed by the ABNF for the "filter-name" non-terminal.
198 Note that values of all search keys stored in these entries MUST be
201 A new filter named "<filter_name>" can be created (or an existing
202 filter can be modified) by storing a non-NIL value in the "/private/
203 filters/values/<filter_name>" server entry (or in the "/shared/
204 filters/values/<filter_name>") using the SETMETADATA [METADATA]
205 command. The server SHOULD verify that each search criterion stored
206 in such a server entry is a full and correct search criterion.
208 A filter can be deleted by storing the NIL value in both the
209 "/private/filters/values/<filter_name>" and the "/shared/filters/
210 values/<filter_name>" entries.
212 A filter can be renamed by first creating a filter with the new name
213 (that has the same value as the old one) and then deleting the filter
216 If both "/private/filters/values/<filter_name>" and "/shared/filters/
217 values/<filter_name>" server annotations exist, then the value of the
218 "/private/filters/values/<filter_name>" is used when evaluating the
219 corresponding FILTER SEARCH key (see Section 3.1). Otherwise the
220 non-NIL (existent) value is used.
226Melnikov & King Standards Track [Page 4]
228RFC 5466 IMAP Filters February 2009
231 If the server is unable to create a new typed filter because the
232 maximum number of allowed filters has already been reached, the
233 server MUST return a tagged NO response with a "[METADATA TOOMANY]"
234 response code, as defined in [METADATA].
236 C: a007 SETMETADATA "" ("/private/filters/values/on-the-road"
237 "OR SMALLER 5000 FROM \"boss@example.com\"")
238 S: a007 OK SETMETADATA complete
240 Client implementation note: As multiple clients might read and write
241 filter values, it is possible that one client will use a SEARCH key
242 that might not be recognized by another client that tries to present
243 a user interface for editing a filter value. In order to help other
244 clients to (partially) parse filter values for editing purposes, a
245 client storing a filter value SHOULD use () around any SEARCH key not
246 defined in [RFC3501]. For example, if there is an IMAP extension
247 that defines a new x-dsfa SEARCH key that takes 2 parameters, then
248 the following SEARCH criterion 'from "@example.com>" x-dsfa from 5'
249 should be stored as 'from "@example.com>" (x-dsfa from 5)'.
251 Note that filter names are restricted to a subset of US-ASCII, as
252 described in Section 4. So they might not always be meaningful to
253 users and thus not necessarily suitable for display purposes. In
254 order to help with storing human-readable descriptions of filters,
255 this document also reserves two hierarchies of server entries under
256 the "/private/filters/descriptions" and "/shared/filters/
257 descriptions" roots. The value of a "/private/filters/descriptions/
258 <filter_name>" or a "/shared/filters/descriptions/<filter_name>"
259 server annotation is a human-readable description for the
260 <filter_name> filter, encoded in UTF-8 [UTF-8]. If the "/private/
261 filters/descriptions/<filter_name>" server annotation exists, its
262 value is used by the client as the filter description. Otherwise,
263 the value of the "/shared/filters/descriptions/<filter_name>" server
264 annotation is used as the filter description. In the absence of both
265 the "/private/filters/descriptions/<filter_name>" and the "/shared/
266 filters/descriptions/<filter_name>" entries, the client MAY display
267 the name of the filter as its description.
269 The description string SHOULD be annotated with one or more language
270 tags [RFC4646] as specified in Chapter 16.9 of [Unicode]. In the
271 absence of any language tag, the "i-default" [RFC2277] language
272 SHOULD be assumed. Description in multiple languages MAY be present
273 in a single description string. This is done by concatenating
274 descriptions in multiple languages into a single string, each
275 description prefixed with its language tag, for example
276 "<ru><...description in Russian...><fr-ca><...description in
277 French...>". Note that here <ru> is a language tag consisting of 3
278 Unicode characters: <U+E0001>, <U+E0072>, <U+E0075>; and <fr-ca> is a
282Melnikov & King Standards Track [Page 5]
284RFC 5466 IMAP Filters February 2009
287 language tag consisting of 6 Unicode characters: <U+E0001>,
288 <U+E0066>, <U+E0072>, <U+E002D>, <U+E0063>, <U+E0061>.
292 The following syntax specification uses the Augmented Backus-Naur
293 Form (ABNF) notation as specified in [ABNF].
295 Non-terminals referenced but not defined below are as defined by
296 [RFC3501] or [IMAPABNF].
298 Except as noted otherwise, all alphabetic characters are case-
299 insensitive. The use of upper or lower case characters to define
300 token strings is for editorial clarity only. Implementations MUST
301 accept these strings in a case-insensitive fashion.
303 capability =/ "FILTERS"
305 search-criteria = search-key *(SP search-key)
307 search-key =/ "FILTER" SP filter-name
308 ;; New SEARCH criterion for referencing filters
310 filter-name = 1*<any ATOM-CHAR except "/">
311 ;; Note that filter-name disallows UTF-8 or
312 ;; the following characters: "(", ")", "{",
313 ;; " ", "%", "*", "]". See definition of
314 ;; ATOM-CHAR [RFC3501].
316 resp-text-code =/ "UNDEFINED-FILTER" SP filter-name
3185. Security Considerations
320 General issues relevant to [RFC3501] (in particular to the SEARCH
321 command) and METADATA-SERVER extension [METADATA] are also relevant
324 Note that excessive use of filters can potentially simplify denial-
325 of-service attacks, especially if combined with poor implementations
326 and lack of loop detection (i.e., detection of filters referencing
327 each other to create a loop). Servers that allow for anonymous
328 access SHOULD NOT allow anonymous users to create/edit/delete
331 Also note that stored filters can potentially disclose personal
332 information about users. When confidentiality of such information is
333 important, clients MUST use TLS and/or SASL security layer (or
334 similar) as recommended in [RFC3501]. Also, clients should use
338Melnikov & King Standards Track [Page 6]
340RFC 5466 IMAP Filters February 2009
343 private filters instead of public, unless they desire to share such
344 information with other users.
346 As always, it is important to thoroughly test clients and servers
347 when implementing this extension.
3496. IANA Considerations
351 IMAP4 capabilities are registered by publishing a Standards Track or
352 IESG-approved Experimental RFC. The IMAP4 capabilities registry is
353 available from http://www.iana.org.
355 This document defines the FILTERS IMAP capability. IANA has added it
358 IANA has added the following 4 entries to the [METADATA] registry:
361 Subject: IMAP METADATA Entry Registration
363 Name: /private/filters/values/<filter_name>
364 Description: Contains an IMAP SEARCH criteria. Defined in RFC 5466.
365 Content-type: text/plain; charset=utf-8
366 Contact person: Alexey Melnikov
367 Email: alexey.melnikov@isode.com
370 Subject: IMAP METADATA Entry Registration
372 Name: /shared/filters/values/<filter_name>
373 Description: Contains an IMAP SEARCH criterion. Defined in RFC
375 Content-type: text/plain; charset=utf-8
376 Contact person: Alexey Melnikov
377 Email: alexey.melnikov@isode.com
380 Subject: IMAP METADATA Entry Registration
382 Name: /private/filters/descriptions/<filter_name>
383 Description: Contains a user-specific human-readable description of
384 a named SEARCH criterion stored in the /private/filters/values/
385 <filter_name> or /shared/filters/values/<filter_name> annotation.
386 The value is in UTF-8. Defined in RFC 5466.
387 Content-type: text/plain; charset=utf-8
388 Contact person: Alexey Melnikov
389 Email: alexey.melnikov@isode.com
394Melnikov & King Standards Track [Page 7]
396RFC 5466 IMAP Filters February 2009
400 Subject: IMAP METADATA Entry Registration
402 Name: /shared/filters/descriptions/<filter_name>
403 Description: Contains a global (shared among all users) human-
404 readable description of a named SEARCH criterion stored in the
405 /private/filters/values/<filter_name> or /shared/filters/values/
406 <filter_name> annotation. The value is in UTF-8. Defined in RFC
408 Content-type: text/plain; charset=utf-8
409 Contact person: Alexey Melnikov
410 Email: alexey.melnikov@isode.com
414 Thanks to David Cridland, Arnt Gulbrandsen, Chris Newman, and Timo
415 Sirainen for comments and suggestions on this document. Special
416 thank you to Brian E. Carpenter for the GenArt review.
4188. Normative References
420 [ABNF] Crocker, D., Ed. and P. Overell, Ed., "Augmented BNF for
421 Syntax Specifications: ABNF", STD 68, RFC 5234,
424 [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
425 ABNF", RFC 4466, April 2006.
427 [METADATA] Daboo, C., "The IMAP METADATA Extension", RFC 5464,
430 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
431 Requirement Levels", BCP 14, RFC 2119, March 1997.
433 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
434 Languages", BCP 18, RFC 2277, January 1998.
436 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
437 4rev1", RFC 3501, March 2003.
439 [RFC4646] Phillips, A. and M. Davis, "Tags for Identifying
440 Languages", BCP 47, RFC 4646, September 2006.
442 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
443 10646", STD 63, RFC 3629, November 2003.
445 [Unicode] "The Unicode Standard 5.0", Unicode 5.0, 2007,
446 <http://www.unicode.org/versions/Unicode5.0.0/>.
450Melnikov & King Standards Track [Page 8]
452RFC 5466 IMAP Filters February 2009
459 5 Castle Business Village
461 Hampton, Middlesex TW12 2BX
464 EMail: Alexey.Melnikov@isode.com
469 5 Castle Business Village
471 Hampton, Middlesex TW12 2BX
474 EMail: Curtis.King@isode.com
506Melnikov & King Standards Track [Page 9]