Sieve Working Group W. Segmuller Internet Draft B. Leiba Obsoletes: 3431 (if approved) IBM T.J. Watson Research Center Document: draft-ietf-sieve-3431bis-00.txt February 2005 Expires August 2005 Sieve Extension: Relational Tests Status of this Document This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. 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 become aware will be disclosed, in accordance with RFC 3668. 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 August 14, 2005. Copyright Notice Copyright (C) The Internet Society (2005). Abstract This document describes the RELATIONAL extension to the Sieve mail filtering language defined in RFC 3028. This extension extends existing conditional tests in Sieve to allow relational operators. W. Segmuller, B. Leiba Expires August 2005 [Page 1] Internet DRAFT Sieve Extension: Relational Tests February 2005 In addition to testing their content, it also allows for testing of the number of entities in header and envelope fields. Meta-information on this document This information is intended to facilitate discussion. It will be removed when this document leaves the Internet-Draft stage. This document is intended to be an update to the existing "relational" extension to the Sieve mail filtering language, available from the RFC repository as . This document and the Sieve language itself are being discussed on the MTA Filters mailing list at . Subscription requests can be sent to (send an email message with the word "subscribe" in the body). More information on the mailing list along with a WWW archive of back messages is available at . Conventions used in this document 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 BCP 14, RFC 2119. Conventions for notations are as in [SIEVE] section 1.1, including the 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". 1. Introduction Sieve [SIEVE] is a language for filtering e-mail messages at the time of final delivery. It is designed to be implementable on either a mail client or mail server. It is meant to be extensible, simple, and independent of access protocol, mail architecture, and operating system. It is suitable for running on a mail server where users may not be allowed to execute arbitrary programs, such as on black box Internet Messages Access Protocol (IMAP) servers, as it has no variables, loops, nor the ability to shell out to external programs. The RELATIONAL extension provides relational operators on the W. Segmuller, B. Leiba Expires August 2005 [Page 2] Internet DRAFT Sieve Extension: Relational Tests February 2005 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 equivalent. 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. For example: are there more than 5 addresses in the to and cc fields. 2. Comparators This document does not define any comparators or exempt any comparators from the require clause. Any comparator used, other than "i;octet" and "i;ascii-casemap", MUST be declared a require clause as defined in [SIEVE]. The "i;ascii-numeric" comparator, as defined in [ACAP], MUST be supported for any implementation of this extension. The comparator "i;ascii-numeric" MUST support at least 32 bit unsigned integers. Larger integers MAY be supported. Note: the "i;ascii-numeric" comparator does not support negative numbers. 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 ; "gt" means "greater than", the C operator ">". ; "ge" means "greater than or equal", the C operator ">=". ; "lt" means "less than", the C operator "<". ; "le" means "less than or equal", the C operator "<=". W. Segmuller, B. Leiba Expires August 2005 [Page 3] Internet DRAFT Sieve Extension: Relational Tests February 2005 ; "eq" means "greater than", the C operator "==". ; "ne" means "greater than", the C operator "!=". 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 of the message for the comparison. White space is defined as SP / HTAB / CRLF 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. The Address Test counts the number of recipients in the specified fields. Group names are ignored. The Envelope Test counts the number of recipients in the specified envelope parts. The envelope "to" will always have only one entry, which is the address of the user for whom the sieve script is running. There is no way a sieve script can determine if the message was actually sent to someone else using this test. The envelope "from" will be 0 if the MAIL FROM is blank, or 1 if MAIL FROM is not blank. The Header Test 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 W. Segmuller, B. Leiba Expires August 2005 [Page 4] Internet DRAFT Sieve Extension: Relational Tests February 2005 comparison. Thus, specifying ["to", "cc"] in an address COUNT test, comparing 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. Example Using the message: received: ... received: ... subject: example to: foo@example.com.invalid, baz@example.com.invalid cc: qux@example.com.invalid The test: 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 2822 compliant message [RFC2822], W. Segmuller, B. Leiba Expires August 2005 [Page 5] Internet DRAFT Sieve Extension: Relational Tests February 2005 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. 5. Extended Example require ["relational", "comparator-i;ascii-numeric"]; 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"] { 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.invalid"] { fileinto "Only me"; } 6. IANA Considerations This document requests that the IANA update the entry for the "relational" Sieve extension to point to this document. 7. Security Considerations Security considerations are discussed in [SIEVE]. W. Segmuller, B. Leiba Expires August 2005 [Page 6] Internet DRAFT Sieve Extension: Relational Tests February 2005 An implementation MUST ensure that the test for envelope "to" only reflects the delivery to the current user. It MUST not be possible for a user to determine if this message was delivered to someone else using this test. 8. Normative References [SIEVE]; Showalter, T.; "Sieve: A Mail Filtering Language"; RFC 3028; January 2001. [Keywords]; Bradner, S.; "Key words for use in RFCs to IndicateRequirement Levels"; BCP 14; RFC 2119; March 1997. [ABNF]; Crocker, D.; "Augmented BNF for Syntax Specifications: ABNF"; RFC 2234; November 1997. [RFC2822]; Resnick, P.; "Internet Message Format"; RFC 2822; April 2001. 9. Non-Normative References [ACAP]; Newman, C. and J. G. Myers; "ACAP -- Application Configuration Access Protocol"; RFC 2244; November 1997. 10. Authors' Addresses Wolfgang Segmuller IBM T.J. Watson Research Center 19 Skyline Drive Hawthorne, NY 10532 Phone: 1-914-784-7408 Email: whs@watson.ibm.com Barry Leiba IBM T.J. Watson Research Center 19 Skyline Drive Hawthorne, NY 10532 Phone: 1-914-784-7941 Email: leiba@watson.ibm.com W. Segmuller, B. Leiba Expires August 2005 [Page 7] Internet DRAFT Sieve Extension: Relational Tests February 2005 Intellectual Property Statement 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. Disclaimer of Validity 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 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. Copyright Statement Copyright (C) The Internet Society (2005). 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. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. W. Segmuller, B. Leiba Expires August 2005 [Page 8]