RFC3431: Sieve Extension: Relational Tests
Download in PDF format Download in text format
Obsoleted By:
RFC5231
Related keywords:
(filtering language)
(sieve mail)
Network Working Group W. Segmuller
Request for Comment: 3431 IBM T.J. Watson Research Center
Category: Standards Track December 2002
Sieve Extension: Relational Tests
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) The Internet Society (2002). All Rights Reserved.
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.
In addition to testing their content, it also allows for testing of
the number of entities in header and envelope fields.
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
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.
Segmuller Standards Track [Page 1]
RFC 3431 Sieve Extension: Relational Tests December 2002
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 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".
3 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.
4 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
Segmuller Standards Track [Page 2]
RFC 3431 Sieve Extension: Relational Tests December 2002
4.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.
4.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
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".
Segmuller Standards Track [Page 3]
RFC 3431 Sieve Extension: Relational Tests December 2002
5 Security Considerations
Security considerations are discussed in [SIEVE].
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.
6 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.
Segmuller Standards Track [Page 4]
RFC 3431 Sieve Extension: Relational Tests December 2002
The test:
header :count "ge" :comparator "i;ascii-numeric"
["to", "cc"] ["3"]
will always return false on an RFC 2822 compliant message [RFC2822],
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.
7 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";
}
Segmuller Standards Track [Page 5]
RFC 3431 Sieve Extension: Relational Tests December 2002
8 IANA Considerations
The following template specifies the IANA registration of the Sieve
extension specified in this document:
To: iana@iana.org
Subject: Registration of new Sieve extension
Capability name: RELATIONAL
Capability keyword: relational
Capability arguments: N/A
Standards Track/IESG-approved experimental RFC number: this RFC
Person and email address to contact for further information:
Wolfgang Segmuller
IBM T.J. Watson Research Center
30 Saw Mill River Rd
Hawthorne, NY 10532
Email: whs@watson.ibm.com
This information should be added to the list of sieve extensions
given on http://www.iana.org/assignments/sieve-extensions.
9 References
9.1 Normative References
[SIEVE] Showalter, T., "Sieve: A Mail Filtering Language", RFC
3028, January 2001.
[Keywords] Bradner, S., "Key words for use in RFCs to Indicate
Requirement 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.2 Non-Normative References
[ACAP] Newman, C. and J. G. Myers, "ACAP -- Application
Configuration Access Protocol", RFC 2244, November 1997.
Segmuller Standards Track [Page 6]
RFC 3431 Sieve Extension: Relational Tests December 2002
10 Author's Address
Wolfgang Segmuller
IBM T.J. Watson Research Center
30 Saw Mill River Rd
Hawthorne, NY 10532
EMail: whs@watson.ibm.com
Segmuller Standards Track [Page 7]
RFC 3431 Sieve Extension: Relational Tests December 2002
11 Full Copyright Statement
Copyright (C) The Internet Society (2002). 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
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.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
Segmuller Standards Track [Page 8]