Network Working Group W. Segmuller Internet Draft IBM T.J. Watson Research Center Document: draft-segmuller-sieve-relation-01.txt September 2001 Expires: March 2002 Sieve Extension: Relational Tests Status of this Document This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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. The protocol discussed in this document is experimental and subject to change. Persons planning on either implementing or using this protocol are STRONGLY URGED to get in touch with the author before embarking on such a project. Discussion and suggestions for improvement are requested, and should be sent to ietf-mta-filters@imc.org. This document will expire before 31 September 2001. Distribution of this memo is unlimited. Abstract This document describes the RELATIONAL extension to the Sieve mail filtering language [SIEVE]. This extension allows relational operators on field values and on the number of entities in header fields and addresses. 0 Change History changes from version -00 - domain names fixed in examples, thanks to Phil Pennock and Tony Hansen. Segmuller Expires March 2002 [Page 1] Internet Draft Sieve Extension: Relational Tests September 2001 - Strip leading and trailing spaces when using a match-type of ":value". 1 Introduction The RELATIONAL extension provides relational operators on the address, envelope and header tests. This extension also provides a way of counting the entities in a message header or address field. With this extension, the sieve script may now determine if a field is greater than or less than a value instead of just equal to. One use is for the x-priority field: move messages with a priority greater than 3 to the "work on later" folder. Mail could also be sorted by the from address. Those userids that start with 'a'-'m' go to one folder, and the rest go to another folder. The sieve script can also determine the number of fields in the header, or the number of addresses in a recipient field. An example: are there more than 5 addresses in the to and cc fields. 2 Conventions used in this document Conventions for notations are as in [SIEVE] section 1.1, including use of [KEYWORDS] and "Syntax:" label for the definition of action and tagged arguments syntax, and the use of [ABNF] The capability string associated with extension defined in this document is "relational". 3 Match Type This document defines two new match types. They are the VALUE match type and the COUNT match type. The syntax is: MATCH-TYPE =/ COUNT / VALUE COUNT = ":count" relational-match VALUE = ":value" relational-match relational-match = DQUOTE ( "gt" / "ge" / "lt" / "le" / "eq" / "ne" ) DQUOTE 3.1 Match Type Value The VALUE match type does a relational comparison between strings. The VALUE match type may be used with any comparator which returns sort information. Leading and trailing white space MUST be removed from the value from the message for the comparison. White space is defined as Segmuller Expires March 2002 [Page 2] Internet Draft Sieve Extension: Relational Tests September 2001 SP / HTAB / CRLF / CR / LF A value from the message is considered the left side of the relation. A value from the test expression, the key-list for address, envelope, and header tests, is the right side of the relation. If there are multiple values on either side or both sides, the test is considered true if any pair is true. 3.2 Match Type Count The COUNT match type first determines the number of the specified entities in the message and does a relational comparison of the number of entities to the values specified in the test expression. The COUNT match type SHOULD only be used with numeric comparators. A suitable comparator is "i;ascii-numeric" which is defined in [ACAP]. For the Address Test, this counts the number of recipients in the specified fields. Group names are ignored. For the Envelope Test, this counts the number of recipients in the specified envelope parts. For the Header Test, this counts the total number of instances of the specified fields. This does not count individual addresses in the "to", "cc", and other recipient fields. In all cases, if more than one field name is specified, the counts for all specified fields are added together to obtain the number for comparison. Thus, specifying ["to", "cc"] in an address COUNT test will compare the total number of "to" and "cc" addresses; if separate counts are desired, they must be done in two comparisons, perhaps joined by "allof" or "anyof". 4 Security Considerations Security considerations are discussed in [SIEVE]. It is belived that this extension doesn't introduce any additional security concerns. 5 Example Using the message: received: ... received: ... subject: example to: foo@example.com.invalid, baz@example.com.invalid cc: qux@example.com.invalid The test Segmuller Expires March 2002 [Page 3] Internet Draft Sieve Extension: Relational Tests September 2001 address :count "ge" :comparator "i;ascii-numeric" ["to", "cc"] ["3"] would be true and the test anyof ( address :count "ge" :comparator "i;ascii-numeric" ["to"] ["3"], address :count "ge" :comparator "i;ascii-numeric" ["cc"] ["3"] ) would be false. To check the number of received fields in the header, the following test may be used: header :count "ge" :comparator "i;ascii-numeric" ["received"] ["3"] This would return false. But header :count "ge" :comparator "i;ascii-numeric" ["received", "subject"] ["3"] would return true. The test: header :count "ge" :comparator "i;ascii-numeric" ["to", "cc"] ["3"] will always return false on an RFC 822 compliant message [RFC822], since a message can have at most one "to" field and at most one "cc" field. This test counts the number of fields, not the number of addresses. 6 Extended Example require "relational"; if header :value "lt" :comparator "i;ascii-numeric" ["x-priority"] ["3"] { fileinto "Priority"; } elseif address :count "gt" :comparator "i;ascii-numeric" ["to"] ["5"] { # everything with more than 5 recipients in the "to" field # is considered SPAM fileinto "SPAM"; } elseif address :value "gt" :all :comparator "i;ascii-casemap" ["from"] ["M"] Segmuller Expires March 2002 [Page 4] Internet Draft Sieve Extension: Relational Tests September 2001 { fileinto "From N-Z"; } else { fileinto "From A-M"; } if allof ( address :count "eq" :comparator "i;ascii-numeric" ["to", "cc"] ["1"] , address :all :comparator "i;ascii-casemap" ["to", "cc"] ["me@foo.example.com"] { fileinto "Only me"; } 7 Author's Address Wolfgang Segmuller IBM T.J. Watson Research Center 30 Saw Mill River Rd Hawthorne, NY 10532 Phone: 1-914-784-7408 Email: whs@watson.ibm.com Appendix A. References [SIEVE]; Showalter, T.; "Sieve: A Mail Filtering Language"; RFC 3028; Mirapoint, Inc.; January 2001 [Keywords]; Bradner, S.; "Key words for use in RFCs to Indicate Requirement Levels"; RFC 2119; Harvard University; March 1997 [ABNF]; Crocker, D.; "Augmented BNF for Syntax Specifications: ABNF"; RFC 2234; Internet Mail Consortium; November, 1997. [RFC822]; Crocker, D.; "Standard for the Format of ARPA Internet Text Messages"; RFC 822; University of Delaware; August 1982 [ACAP]; Newman, C. and J. G. Myers, "ACAP -- Application Configuration Access Protocol", RFC 2244, November 1997. Appendix B. Full Copyright Statement Copyright (C) The Internet Society 2001. All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for Segmuller Expires March 2002 [Page 5] Internet Draft Sieve Extension: Relational Tests September 2001 copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS 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. Segmuller Expires March 2002 [Page 6]