RFC 5466
IMAP4 Extension for Named Searches (Filters)
RFC 5466: IMAP4 Extension for Named Searches (Filters) 🎀
okay bestie, this one is RFC 5466, and it's giving saved searches 🔍✨ It's a Standards Track doc from the Network Working Group, written by A. Melnikov and C. King at Isode Ltd, and it's dated February 2009. It doesn't list any RFCs it obsoletes or updates, so it's standing on its own 💅
Status of This Memo ✨
This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice 🌸
Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.
Abstract 🦋
So this doc defines a way to persistently store named IMAP (RFC 3501) searches on the server. Those named searches can then be referenced later in a SEARCH command, or in any other command that takes a search criterion as a parameter. Main character energy 👑
Table of Contents 🧚
1. Introduction and Overview . . . . . . . . . . . . . . . . . . . 2
2. Conventions Used in This Document . . . . . . . . . . . . . . . 2
3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . . 2
3.1. FILTER SEARCH Criterion . . . . . . . . . . . . . . . . . . 3
3.2. Managing Filters Using SETMETADATA/GETMETADATA Commands . . 4
4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 6
5. Security Considerations . . . . . . . . . . . . . . . . . . . . 6
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 8
8. Normative References . . . . . . . . . . . . . . . . . . . . . 81. Introduction and Overview 💖
Okay so persistent named searches let clients save their favorite searches on the server 🍓 And honestly? Saved searches can save bandwidth for clients that keep repeating the same ones, which is so smart.
The FILTERS IMAP extension adds a brand new FILTER search criterion for referencing persistent named searches (a.k.a. "filters") 🫶 It also reuses the GETMETADATA/SETMETADATA commands [METADATA] for listing/creating/updating/deleting those filters. Iconic reuse, no notes.
A filter can be private (only accessible to the logged-in user) or public (accessible to all logged-in users). A private filter and a public filter can have the same name and exist at the same time 🙈 If both filter types with that 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. Private wins, periodt 💅
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 the ABNF for the "search-criteria" non-terminal, plus 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 🌈
2. 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 just for editorial clarity and aren't 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]. These are the official rule words, so they're the ones to pay attention to 👀
Basic familiarity with the METADATA-SERVER extension [METADATA] and terms defined therein is required to understand this document 🧠
3. IMAP Protocol Changes 🔥
The IMAP extension for persistent named searches is present in any IMAP4 implementation that advertises "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 lets a client reference, by name, a filter stored on the server. That filter was created by setting the server annotation named "/private/filters/values/<filter_name>" (or the server annotation "/shared/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 exists, its search criterion (i.e., the associated entry value) gets inserted verbatim in place of the FILTER search-key. For example, this SEARCH command:
C: a SEARCH UID 300:900 FILTER on-the-road SINCE "3-Dec-2002"would be equivalent to this one:
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 nonexistent or unaccessible filter (for example, because of access control restrictions) MUST cause the SEARCH command to fail with a tagged NO response. That response includes the UNDEFINED-FILTER response code, followed by the name of the nonexistent or unaccessible filter. Oof, rude 💀
Heads up: 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 an "OR SMALLER" search criterion, because that value is missing a parameter and so isn't a fully specified search criterion 🚩
A named filter can itself 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). No infinite loops allowed, bestie 🔁
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 an explicit CHARSET parameter with a value other than "UTF-8" or "US-ASCII", then that command MUST result in a tagged BAD response from the server. That tagged response MUST contain the BADCHARSET response code (see [RFC3501]). Charset drama, but it's handled 🌸
Part 2 coming next, bestie 🦋
3.2. Managing Filters Using SETMETADATA/GETMETADATA Commands ✨
okay so first things first 🎀 any server that follows this doc MUST either implement the METADATA-SERVER (or METADATA) [METADATA] extension, OR implement the SETMETADATA/GETMETADATA commands from [METADATA] so they work for the empty mailbox name (aka managing server annotations) and for the entries in this section. no skipping 🙅♀️
this doc reserves two hierarchies of per-server entries under the /private/filters/values and /shared/filters/values roots (see [METADATA]) for storing filter values 🦋 the value of a /private/filters/values/<filter_name> or /shared/filters/values/<filter_name> server annotation is an IMAP SEARCH criteria, and it has to match the ABNF for the "search-criteria" non-terminal. a filter name is governed by the ABNF for the "filter-name" non-terminal 💜
⚠️ bestie, read this part twice: values of ALL search keys stored in these entries MUST be encoded in UTF-8. no other encoding, period 🙅♀️
to make a brand new filter named <filter_name> (or edit one that already exists), you store a non-NIL value in /private/filters/values/<filter_name> (or in /shared/filters/values/<filter_name>) using the SETMETADATA [METADATA] command ✨ the server SHOULD verify that each search criterion stored in that entry is a full and correct search criterion. ngl that's a very reasonable ask 💅
deleting a filter is giving "store NIL" 🫶 you store the NIL value in BOTH /private/filters/values/<filter_name> and /shared/filters/values/<filter_name>.
renaming? iconic. first you create a filter with the NEW name (same value as the old one), and THEN you delete the filter with the old name 🦋
now, if BOTH /private/filters/values/<filter_name> and /shared/filters/values/<filter_name> annotations exist, the value of the private one is what gets used when evaluating the matching FILTER SEARCH key (see Section 3.1). otherwise, whichever one has a non-NIL (existent) value is used 🌸
if the server can't create a new typed filter because the max number of allowed filters has already been hit, it MUST return a tagged NO response with a [METADATA TOOMANY] response code, as defined in [METADATA] 💀
here's what that looks like on the wire 🧚
C: a007 SETMETADATA "" ("/private/filters/values/on-the-road"
"OR SMALLER 5000 FROM \"boss@example.com\"")
S: a007 OK SETMETADATA completeClient implementation note (the tea 🍵): multiple clients might read and write filter values, so it's possible one client uses a SEARCH key that another client doesn't recognize. when that other client is trying to show an editing UI, it might not be able to parse the filter value. so to help other clients (partially) parse filter values for editing, a client storing a filter value SHOULD wrap any SEARCH key that's NOT defined in [RFC3501] in () 🎀 example time: say there's an extension with a new x-dsfa SEARCH key that takes 2 parameters. then the criterion 'from "@example.com>" x-dsfa from 5' should be stored as 'from "@example.com>" (x-dsfa from 5)' 💖
heads up, filter names are restricted to a subset of US-ASCII (Section 4 has the deets), so they're not always meaningful to users or suitable for display 🙈 to store human-readable descriptions, this doc also reserves two hierarchies of server entries under /private/filters/descriptions and /shared/filters/descriptions roots 🌈 the value of a /private/filters/descriptions/<filter_name> or /shared/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 description entry exists, the client uses its value as the description. otherwise it uses the shared one. if NEITHER entry exists, the client MAY display the filter's name as its description 🦋
the description string SHOULD be tagged with one or more language tags [RFC4646], as specified in Chapter 16.9 of [Unicode] 🍓 if there's no language tag at all, the "i-default" [RFC2277] language SHOULD be assumed. and yes, you can have descriptions in multiple languages in ONE string, which MAY be present. you just concatenate them, each one prefixed with its language tag, like this:
"<ru><...description in Russian...><fr-ca><...description in French...>"
quick tag breakdown because I'm obsessed with this 🤓 <ru> is a language tag made of 3 Unicode characters: <U+E0001>, <U+E0072>, <U+E0075>. and <fr-ca> is made of 6 Unicode characters: <U+E0001>, <U+E0066>, <U+E0072>, <U+E002D>, <U+E0063>, <U+E0061> 💜
4. Formal Syntax 💅
the syntax below uses ABNF (Augmented Backus-Naur Form) as specified in [ABNF] 🌸 any non-terminal that's referenced but not defined here is defined by [RFC3501] or [IMAPABNF] ✨
all alphabetic characters are case-insensitive, EXCEPT where noted otherwise. upper and lower case are only used to define token strings for editorial clarity. implementations MUST accept these strings in a case-insensitive fashion 🫶
capability =/ "FILTERS"
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-name5. Security Considerations 🔥
okay this section is SERIOUS (dramatic is fine 💀) 🙈
general issues from [RFC3501] (especially the SEARCH command) and the METADATA-SERVER extension [METADATA] are also relevant here, so don't skip those 🖤
excessive use of filters can potentially make denial-of-service attacks easier, especially when combined with poor implementations and no loop detection (aka detecting filters that reference each other in a loop) 😭 so servers that allow anonymous access SHOULD NOT let anonymous users create, edit, or delete filters 🚫
also, stored filters can potentially reveal personal info about users. when confidentiality matters, clients MUST use TLS and/or a SASL security layer (or something similar) as recommended in [RFC3501] 🔐 and clients should use private filters instead of public ones, unless they actually want to share that info with other users 🫶
last but not least: as always, it's SO important to thoroughly test clients and servers when implementing this extension 🧪✨
6. IANA Considerations 🌈
IMAP4 capabilities get registered by publishing a Standards Track or IESG-approved Experimental RFC. the IMAP4 capabilities registry is available from http://www.iana.org 🍓
this document defines the FILTERS IMAP capability, and IANA has added it to the registry 💖
IANA has also added the following 4 entries to the [METADATA] registry 🧚 (they're all the same template, so here they are in full):
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 5466.
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: /shared/filters/values/<filter_name>
Description: Contains an IMAP SEARCH criterion. Defined in RFC
5466.
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 /shared/filters/values/<filter_name> annotation.
The value is in UTF-8. Defined in RFC 5466.
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: /shared/filters/descriptions/<filter_name>
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 /shared/filters/values/
<filter_name> annotation. The value is in UTF-8. Defined in RFC
5466.
Content-type: text/plain; charset=utf-8
Contact person: Alexey Melnikov
Email: alexey.melnikov@isode.com7. Acknowledgments 🫶
big thanks to David Cridland, Arnt Gulbrandsen, Chris Newman, and Timo Sirainen for their comments and suggestions on this doc 💜 and a 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", STD 68, RFC 5234,
January 2008.
[IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
ABNF", RFC 4466, April 2006.
[METADATA] Daboo, C., "The IMAP METADATA Extension", RFC 5464,
February 2009.
[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", BCP 18, 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", BCP 47, RFC 4646, September 2006.
[UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
[Unicode] "The Unicode Standard 5.0", Unicode 5.0, 2007,
<http://www.unicode.org/versions/Unicode5.0.0/>.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📦 where this page comes from
- ietf: rfc5466 2009-02
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms