idnits 2.17.1 draft-melnikov-imapext-filters-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 553. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 564. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 571. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 577. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 5, 2008) is 5771 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 4234 (ref. 'ABNF') (Obsoleted by RFC 5234) == Outdated reference: A later version (-17) exists of draft-daboo-imap-annotatemore-13 ** Obsolete normative reference: RFC 3501 (Obsoleted by RFC 9051) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Melnikov 3 Internet-Draft C. King 4 Intended status: Standards Track Isode Ltd 5 Expires: January 6, 2009 July 5, 2008 7 IMAP4 extension for named searches (filters) 8 draft-melnikov-imapext-filters-05.txt 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on January 6, 2009. 35 Abstract 37 The document defines a way to persistently store named IMAP (RFC 38 3501) searches on the server. Such named searches can be 39 subsequently referenced in a SEARCH or any other command that accepts 40 a search criteria as a parameter. 42 Table of Contents 44 1. Conventions Used in this Document . . . . . . . . . . . . . . 3 45 2. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 46 3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 3 47 3.1. LISTFILTERS command . . . . . . . . . . . . . . . . . . . 3 48 3.2. SETFILTER command . . . . . . . . . . . . . . . . . . . . 4 49 3.3. DELETEFILTER command . . . . . . . . . . . . . . . . . . . 5 50 3.4. FILTER SEARCH criterion . . . . . . . . . . . . . . . . . 6 51 3.5. Additional requirements on servers that also implement 52 METADATA-SERVER extension . . . . . . . . . . . . . . . . 7 53 4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 8 54 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 55 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 56 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 57 8. Normative References . . . . . . . . . . . . . . . . . . . . . 12 58 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 59 Intellectual Property and Copyright Statements . . . . . . . . . . 14 61 1. Conventions Used in this Document 63 In examples, "C:" and "S:" indicate lines sent by the client and 64 server respectively. If a single "C:" or "S:" label applies to 65 multiple lines, then the line breaks between those lines are for 66 editorial clarity only and are not part of the actual protocol 67 exchange. 69 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 70 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 71 document are to be interpreted as described in [RFC2119]. 73 Basic familiarity with the METADATA-SERVER extension [METADATA] and 74 terms defined therein is required to understand this document. 76 [[anchor2: Editorial comments and questions are marked like this.]] 78 2. Introduction and Overview 80 Persistent named searches described in this document allow clients to 81 save favourite searches on the server. Such saved searches can save 82 bandwidth for clients that need to regularly repeat them. 84 The IMAP extension for persistent named searches is present in any 85 IMAP4 implementation which advertises "X-DRAFT-I05-FILTERS" 86 [[anchor4: Note to RFC editor: change upon publication to FILTERS]] 87 as one of the supported capabilities in the CAPABILITY response or 88 response code. 90 3. IMAP Protocol Changes 92 The "X-DRAFT-I05-FILTERS" IMAP extension [[anchor6: Note to RFC 93 editor: change upon publication to FILTERS]] adds a new command for 94 listing defined named searches (a.k.a. "filters") (LISTFILTERS), a 95 new command for creating named searches (SETFILTER), a new command 96 for deleting them (DELETEFILTER) and a new FILTER search criterion 97 for referencing such named searches. 99 [[anchor7: Is RENAMEFILTER needed?]] 101 3.1. LISTFILTERS command 102 Arguments: OPTIONAL filter name 104 Responses: untagged responses: FILTER 106 Result: OK - LISTFILTERS command completed 107 BAD - unrecognized syntax of an argument, 108 unexpected extra argument, missing argument, etc. 110 The LISTFILTERS returns either the value and description of the 111 specified filter (if the filter name parameter is specified) or 112 values/descriptions of all existing filters (when no parameter is 113 specified). Each filter definition is returned in a separate 114 untagged FILTER response. 116 The LISTFILTERS command is available in Authenticated and Selected 117 states. 119 C: a001 LISTFILTERS 120 S: * FILTER private "on-the-road" "OR SMALLER 5000 FROM 121 \"boss@example.com\"" "The filter to be used for 122 downloading small messages from my boss on 123 mobile phone" 124 S: a001 OK LISTFILTERS complete 126 3.2. SETFILTER command 128 Arguments: filter name 129 filter type 130 search criteria 131 OPTIONAL filter description 133 Responses: no specific response for this command 135 Result: OK - SETFILTER command completed 136 NO - SETFILTER failed to create or update the specified 137 filter 138 BAD - unrecognized syntax of an argument, 139 unexpected extra argument, missing argument, etc. 141 A filter can be private (only accessible to the logged in user) or 142 public (accessible to all logged in users). Both a private and a 143 public filter with the same name can exist at the same time. If both 144 filter type with the same exist, the FILTER SEARCH criterion (see 145 Section 3.4) is going to use the value of the private filter, 146 otherwise it will use the value of the filter that exists. 148 Let us call a pair of filter name and filter type a "typed filter". 150 Each typed filter can have a value (which is a valid IMAP SEARCH 151 criteria conforming to ABNF for the "search-criteria" non-terminal) 152 and an optional human readable description. The SETFILTER command 153 creates or updates the value and/or the description of a typed 154 filter. If the filter parameter is not specified, the filter 155 description is set to the empty string. 157 If the server is unable to create a new typed filter because the 158 maximum number of allowed filters has already been reached, the 159 server MUST return a tagged NO response with a "[METADATA TOOMANY]" 160 response code. 162 A filter name is governed by the ABNF for the "filter-name" non- 163 terminal. 165 Values of all search keys stored in a filter MUST be encoded in 166 UTF-8. 168 Implementation note: As multiple client might read and write filter 169 values, it is possible that one client will use a SEARCH key that 170 might not be recognized by another client that tries to present a UI 171 for editing a filter value. In order to help other clients to 172 [partially] parse filter values for editing purposes, a client 173 storing a filter value SHOULD use () around any SEARCH key not 174 defined in [RFC3501] For example, if there is an IMAP extension that 175 defines a new x-dsfa SEARCH key that takes 2 parameters, then the 176 following SEARCH criteria 'from "@example.com>" x-dsfa from 5' should 177 be stored as 'from "@example.com>" (x-dsfa from 5)'. 179 The SETFILTER command is available in Authenticated and Selected 180 states. 182 C: a002 SETFILTER private "on-the-road" 183 "OR SMALLER 5000 FROM \"boss@example.com\"" 184 S: a002 OK SETFILTER completed 186 3.3. DELETEFILTER command 188 Arguments: filter name 189 filter type 191 Responses: no specific response for this command 193 Result: OK - DELETEFILTER command completed 194 NO - DELETEFILTER failed to delete the specified filter 195 BAD - unrecognized syntax of an argument, 196 unexpected extra argument, missing argument, etc. 198 The DELETEFILTER command deletes a typed filter (and its description) 199 previously created with SETFILTER command (or by setting the 200 "/private/filters/" or the "/public/filters/ 201 " server annotation as described in Section 3.5). 203 The DELETEFILTER command is available in Authenticated and Selected 204 states. 206 C: a003 DELETEFILTER private "on-the-road" 207 S: a003 OK DELETEFILTER completed 208 C: a004 DELETEFILTER public "on-the-road" 209 S: a004 OK DELETEFILTER completed 211 3.4. FILTER SEARCH criterion 213 The FILTER criterion for the SEARCH command allows a client to 214 reference by name a filter stored on the server. Such filter was 215 created using the SETFILTER command, or by setting the server 216 annotation named "/private/filters/" (or the server 217 annotation "/public/filters/", if "/private/filters/ 218 " doesn't exist) as described in Section 3.5. 220 Syntax: FILTER 222 When the named filter exist, its search criterion (i.e. the 223 associated entry value) is inserted verbatum instead of the FILTER 224 search-key. For example, the following SEARCH command 226 C: a SEARCH UID 300:900 FILTER on-the-road SINCE " 3-Dec-2002" 228 would be equivalent to the following 230 C: a SEARCH UID 300:900 SMALLER 5000 FROM "boss@example.com" 231 SINCE " 3-Dec-2002" 233 assuming the filter "on-the-road" exists and contains the value 'OR 234 SMALLER 5000 FROM "boss@example.com"'. 236 A reference to a non-existent or unaccessible (e.g. due to access 237 control restrictions) filter MUST cause failure of the SEARCH command 238 with the tagged NO response, that includes the UNDEFINED-FILTER 239 response code followed by the name of the non-existent/unaccessible 240 filter. 242 Note the server SHOULD verify that each search criterion referenced 243 by the FILTER search key is a full and correct search criterion. For 244 example, the server should fail the SEARCH command if its SEARCH 245 criterion references a filter containing "OR SMALLER" search 246 criteria, because this value is lacking one parameter and thus is not 247 a fully specified search criterion. 249 Note that a named filter itself can reference another filter using 250 the FILTER search-key. Implementations MUST be able to perform at 251 least 3 substitution passes on the SEARCH command criterion. If an 252 implementation allows for more passes, it MUST implement some kind of 253 loop detection. If an implementation detects a loop or still sees a 254 FILTER search-key after performing at least 3 substitutions, it MUST 255 behave as if the specified filter doesn't exist (as described above). 257 Note that use of the FILTER search key implies the CHARSET "UTF-8" 258 parameter to the SEARCH/UID SEARCH command. If the SEARCH/UID SEARCH 259 command includes the explicit CHARSET parameter with the value other 260 than "UTF-8" or "US-ASCII" then such command MUST result in the 261 tagged BAD response from the server. Such tagged response MUST 262 contain the BADCHARSET response code (see [RFC3501]). 264 3.5. Additional requirements on servers that also implement METADATA- 265 SERVER extension 267 Any server compliant that also implement the METADATA-SERVER 268 [METADATA] extension MUST comply with the additional requirements 269 specified in this section. 271 This document reserves hierarchy of per-server entries under the 272 "/private/filters" and "/public/filters" roots (see [METADATA]) for 273 storing filters. The value of a "/private/filters/" or 274 a "/public/filters/" server annotation is an IMAP SEARCH 275 criteria, conforming to ABNF for the "search-criteria" non-terminal. 276 A name of a filter is governed by the ABNF for the "filter-name" non- 277 terminal. Note that the value of a filter created with SETFILTER 278 command can be retrieved by reading the corresponding "/private/ 279 filters/" or "/public/filters/" server 280 annotation and vice versa, the value of a filter created by setting 281 "/private/filters/" or "/public/filters/" 282 can be retrieved using the LISTFILTERS command. 284 Note that values of all search keys stored in this annotation MUST be 285 encoded in UTF-8. 287 A new filter named "" can be created (or an existing 288 filter can be modified) by storing a non NIL value in the "/private/ 289 filters/" server entry (or in the "/public/filters/ 290 ") using the SETMETADATA [METADATA] command. This is 291 the same as calling the SETFILTER command with omitted filter 292 description parameter. 294 A filter can be deleted by storing the NIL value in both the 295 "/private/filters/" and the "/public/filters/ 296 " entries. This is the same as calling the 297 "DELETEFILTER filter_name private" command followed by "DELETEFILTER 298 filter_name public". 300 A filter can be renamed by first creating a filter with the new name 301 and then deleting filter with the old one. 303 If both "/private/filters/" and "/public/filters/ 304 " server annotations exist, then the value of the 305 "/private/filters/" is used when evaluating the 306 corresponding FILTER SEARCH key (see Section 3.4). Otherwise the 307 non-NIL value is used. 309 C: a007 SETMETADATA "" ("/private/filters/on-the-road" 310 "OR SMALLER 5000 FROM \"boss@example.com\"") 311 S: a007 OK SETMETADATA complete 313 This command is equivalent to SETFILTER private "on-the-road" ... 315 Note that filter names are restricted to a subset of US-ASCII, as 316 described in Section 4. So they might not always be meaningful to 317 users and thus not necessarily suitable for display purposes. In 318 order to help with storing human readable descriptions of filters, 319 this document also reserves hierarchy of server entries under the 320 "/private/filter-descriptions" and "/public/filter-descriptions" 321 roots. The value of a "/private/filter-descriptions/" 322 or a "/public/filter-descriptions/" server annotation is 323 a human readable description for the filter, encoded in 324 UTF-8 [UTF-8]. If the "/private/filter-descriptions/" 325 server annotation exists, its value is used by the client as the 326 filter description. Otherwise the value of the "/public/ 327 filter-descriptions/" server annotation is used as the 328 filter description. In the absence of both the "/private/ 329 filter-descriptions/" and the "/public/ 330 filter-descriptions/" entry the client MAY display the 331 name of the filter as its description. 333 4. Formal Syntax 335 The following syntax specification uses the Augmented Backus-Naur 336 Form (ABNF) notation as specified in [ABNF]. 338 Non-terminals referenced but not defined below are as defined by 339 [RFC3501] or [IMAPABNF]. 341 Except as noted otherwise, all alphabetic characters are case- 342 insensitive. The use of upper or lower case characters to define 343 token strings is for editorial clarity only. Implementations MUST 344 accept these strings in a case-insensitive fashion. 346 capability =/ "X-DRAFT-I05-FILTERS" 347 ;; [[Note to RFC Editor: change the capability 348 ;; name before publication]] 350 search-criteria = search-key *(SP search-key) 352 search-key =/ "FILTER" SP filter-name 353 ;; New SEARCH criterion for referencing filters 355 filter-name = 1* 356 ;; Note that filter-name disallows UTF-8 or 357 ;; the following characters: "(", ")", "{", 358 ;; " ", "%", "*", "]". See definition of 359 ;; ATOM-CHAR [RFC3501]. 361 resp-text-code =/ "UNDEFINED-FILTER" SP filter-name 363 response-payload =/ filter-resp 365 filter-resp = filter-type SP filter-name SP 366 filter-value SP filter-desc 368 filter-type = "PUBLIC" / "PRIVATE" 370 filter-value = astring 371 ;; represented as 373 filter-desc = astring 374 ;;Human readable description of the filter. 375 ;;Empty string, if no description is defined. 377 command-auth =/ listfilters / setfilter / deletefilter 379 listfilters = "LISTFILTERS" [SP filter-name] 381 setfilter = "SETFILTER" SP filter-name SP filter-type 382 filter-value [SP filter-desc] 384 deletefilter = "DELETEFILTER" SP filter-name SP filter-type 386 5. Security Considerations 388 General issues relevant to [RFC3501] (in particular to the SEARCH 389 command) and METADATA-SERVER extension [METADATA] are also relevant 390 to this document. 392 Note that excessive use of filters can potentially simplify deny-of- 393 service attacks, especially if combined with poor implementations and 394 lack of loop detection (i.e. detection of filters referencing each 395 other to create a loop). Servers that allow for anonymous access 396 SHOULD NOT allow anonymous users to create/edit/delete filters. 398 Also note that stored filters can potentially dislose personal 399 information about users. When confidentiality of such information is 400 important, clients MUST use TLS and/or SASL security layer (or 401 similar) as recommended in [RFC3501]. Also clients should use 402 private filters instead of public, unless they desire to share such 403 information with other users. 405 As always, it is important to thoroughly test clients and servers 406 when implementing this extension. 408 6. IANA Considerations 410 IMAP4 capabilities are registered by publishing a standards track or 411 IESG approved experimental RFC. The registry is currently located 412 at: 414 http://www.iana.org/assignments/imap4-capabilities 416 This document defines the X-DRAFT-I05-FILTERS [[anchor12: Note to RFC 417 Editor: change before publication to FILTERS]] IMAP capability. IANA 418 is requested to add it to the registry. 420 IANA is also requested to add the following 4 entries to the 421 [METADATA] registry: 423 To: iana@iana.org 425 Subject: IMAP METADATA Entry Registration 427 Type: Server 429 Name: /private/filters/ 430 Description: Contains an IMAP SEARCH criteria. Defined in RFC XXXX. 432 Content-type: text/plain; charset=utf-8 434 Contact person: Alexey Melnikov 436 Email: alexey.melnikov@isode.com 438 To: iana@iana.org 440 Subject: IMAP METADATA Entry Registration 442 Type: Server 444 Name: /public/filters/ 446 Description: Contains an IMAP SEARCH criteria. Defined in RFC XXXX. 448 Content-type: text/plain; charset=utf-8 450 Contact person: Alexey Melnikov 452 Email: alexey.melnikov@isode.com 454 To: iana@iana.org 456 Subject: IMAP METADATA Entry Registration 458 Type: Server 460 Name: /private/filter-descriptions/ 462 Description: Contains a user specific human readable description of 463 a named SEARCH criteria stored in the /private/filters/ 464 or /public/filters/ annotation. The 465 value is in UTF-8. Defined in RFC XXXX. 467 Content-type: text/plain; charset=utf-8 469 Contact person: Alexey Melnikov 471 Email: alexey.melnikov@isode.com 473 To: iana@iana.org 474 Subject: IMAP METADATA Entry Registration 476 Type: Server 478 Name: /public/filter-descriptions/ 480 Description: Contains a global (shared among all users) human 481 readable description of a named SEARCH criteria stored in the 482 /private/filters/ or /public/filters/ 483 annotation. The value is in UTF-8. Defined in RFC XXXX. 485 Content-type: text/plain; charset=utf-8 487 Contact person: Alexey Melnikov 489 Email: alexey.melnikov@isode.com 491 7. Acknowledgments 493 Thanks to David Cridland and Arnt Gulbrandsen for comments and 494 suggestions on this document. 496 8. Normative References 498 [ABNF] Crocker, D., Ed. and P. Overell, Ed., "Augmented BNF for 499 Syntax Specifications: ABNF", RFC 4234, October 2005. 501 [IMAPABNF] 502 Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 503 ABNF", RFC 4466, April 2006. 505 [METADATA] 506 Daboo, C., "IMAP METADATA Extension", 507 draft-daboo-imap-annotatemore-13 (work in progress), 508 April 2008. 510 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 511 Requirement Levels", BCP 14, RFC 2119, March 1997. 513 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 514 4rev1", RFC 3501, March 2003. 516 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO 517 10646", RFC 3629, November 2003. 519 Authors' Addresses 521 Alexey Melnikov 522 Isode Ltd 523 5 Castle Business Village 524 36 Station Road 525 Hampton, Middlesex TW12 2BX 526 UK 528 Email: Alexey.Melnikov@isode.com 530 Curtis King 531 Isode Ltd 532 5 Castle Business Village 533 36 Station Road 534 Hampton, Middlesex TW12 2BX 535 UK 537 Email: Curtis.King@isode.com 539 Full Copyright Statement 541 Copyright (C) The IETF Trust (2008). 543 This document is subject to the rights, licenses and restrictions 544 contained in BCP 78, and except as set forth therein, the authors 545 retain all their rights. 547 This document and the information contained herein are provided on an 548 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 549 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 550 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 551 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 552 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 553 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 555 Intellectual Property 557 The IETF takes no position regarding the validity or scope of any 558 Intellectual Property Rights or other rights that might be claimed to 559 pertain to the implementation or use of the technology described in 560 this document or the extent to which any license under such rights 561 might or might not be available; nor does it represent that it has 562 made any independent effort to identify any such rights. Information 563 on the procedures with respect to rights in RFC documents can be 564 found in BCP 78 and BCP 79. 566 Copies of IPR disclosures made to the IETF Secretariat and any 567 assurances of licenses to be made available, or the result of an 568 attempt made to obtain a general license or permission for the use of 569 such proprietary rights by implementers or users of this 570 specification can be obtained from the IETF on-line IPR repository at 571 http://www.ietf.org/ipr. 573 The IETF invites any interested party to bring to its attention any 574 copyrights, patents or patent applications, or other proprietary 575 rights that may cover technology that may be required to implement 576 this standard. Please address the information to the IETF at 577 ietf-ipr@ietf.org.