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]
