7
Network Working Group W. Segmuller
8
Request for Comments: 5231 B. Leiba
9
Obsoletes: 3431 IBM T.J. Watson Research Center
10
Category: Standards Track January 2008
13
Sieve Email Filtering: Relational Extension
17
This document specifies an Internet standards track protocol for the
18
Internet community, and requests discussion and suggestions for
19
improvements. Please refer to the current edition of the "Internet
20
Official Protocol Standards" (STD 1) for the standardization state
21
and status of this protocol. Distribution of this memo is unlimited.
25
This document describes the RELATIONAL extension to the Sieve mail
26
filtering language defined in RFC 3028. This extension extends
27
existing conditional tests in Sieve to allow relational operators.
28
In addition to testing their content, it also allows for testing of
29
the number of entities in header and envelope fields.
31
This document obsoletes RFC 3431.
35
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
36
2. Conventions Used in This Document . . . . . . . . . . . . . . . 2
37
3. Comparators . . . . . . . . . . . . . . . . . . . . . . . . . . 2
38
4. Match Types . . . . . . . . . . . . . . . . . . . . . . . . . . 3
39
4.1. Match Type VALUE . . . . . . . . . . . . . . . . . . . . . 3
40
4.2. Match Type COUNT . . . . . . . . . . . . . . . . . . . . . 3
41
5. Interaction with Other Sieve Actions . . . . . . . . . . . . . 4
42
6. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
43
7. Extended Example . . . . . . . . . . . . . . . . . . . . . . . 6
44
8. Changes since RFC 3431 . . . . . . . . . . . . . . . . . . . . 6
45
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7
46
10. Security Considerations . . . . . . . . . . . . . . . . . . . . 7
47
11. Normative References . . . . . . . . . . . . . . . . . . . . . 7
58
Segmuller & Leiba Standards Track [Page 1]
60
RFC 5231 Sieve: Relational Extension January 2008
65
The RELATIONAL extension to the Sieve mail filtering language [Sieve]
66
provides relational operators on the address, envelope, and header
67
tests. This extension also provides a way of counting the entities
68
in a message header or address field.
70
With this extension, the Sieve script may now determine if a field is
71
greater than or less than a value instead of just equivalent. One
72
use is for the x-priority field: move messages with a priority
73
greater than 3 to the "work on later" folder. Mail could also be
74
sorted by the from address. Those userids that start with 'a'-'m' go
75
to one folder, and the rest go to another folder.
77
The Sieve script can also determine the number of fields in the
78
header, or the number of addresses in a recipient field, for example,
79
whether there are more than 5 addresses in the to and cc fields.
81
The capability string associated with the extension defined in this
82
document is "relational".
84
2. Conventions Used in This Document
86
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
87
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
88
document are to be interpreted as described in BCP 14, RFC 2119.
90
Conventions for notations are as in [Sieve] section 1.1, including
91
the use of [Kwds] and the use of [ABNF].
95
This document does not define any comparators or exempt any
96
comparators from the require clause. Any comparator used must be
97
treated as defined in [Sieve].
99
The "i;ascii-numeric" comparator, as defined in [RFC4790], MUST be
100
supported for any implementation of this extension. The comparator
101
"i;ascii-numeric" MUST support at least 32-bit unsigned integers.
103
Larger integers MAY be supported. Note: the "i;ascii-numeric"
104
comparator does not support negative numbers.
114
Segmuller & Leiba Standards Track [Page 2]
116
RFC 5231 Sieve: Relational Extension January 2008
121
This document defines two new match types. They are the VALUE match
122
type and the COUNT match type.
126
MATCH-TYPE =/ COUNT / VALUE
128
COUNT = ":count" relational-match
130
VALUE = ":value" relational-match
132
relational-match = DQUOTE
133
("gt" / "ge" / "lt" / "le" / "eq" / "ne") DQUOTE
134
; "gt" means "greater than", the C operator ">".
135
; "ge" means "greater than or equal", the C operator ">=".
136
; "lt" means "less than", the C operator "<".
137
; "le" means "less than or equal", the C operator "<=".
138
; "eq" means "equal to", the C operator "==".
139
; "ne" means "not equal to", the C operator "!=".
141
4.1. Match Type VALUE
143
The VALUE match type does a relational comparison between strings.
145
The VALUE match type may be used with any comparator that returns
148
A value from the message is considered the left side of the relation.
149
A value from the test expression, the key-list for address, envelope,
150
and header tests, is the right side of the relation.
152
If there are multiple values on either side or both sides, the test
153
is considered true if any pair is true.
155
4.2. Match Type COUNT
157
The COUNT match type first determines the number of the specified
158
entities in the message and does a relational comparison of the
159
number of entities, as defined below, to the values specified in the
162
The COUNT match type SHOULD only be used with numeric comparators.
164
The Address Test counts the number of addresses (the number of
165
"mailbox" elements, as defined in [RFC2822]) in the specified fields.
166
Group names are ignored, but the contained mailboxes are counted.
170
Segmuller & Leiba Standards Track [Page 3]
172
RFC 5231 Sieve: Relational Extension January 2008
175
The Envelope Test counts the number of addresses in the specified
176
envelope parts. The envelope "to" will always have only one entry,
177
which is the address of the user for whom the Sieve script is
178
running. Using this test, there is no way a Sieve script can
179
determine if the message was actually sent to someone else. The
180
envelope "from" will be 0 if the MAIL FROM is empty, or 1 if MAIL
183
The Header Test counts the total number of instances of the specified
184
fields. This does not count individual addresses in the "to", "cc",
185
and other recipient fields.
187
In all cases, if more than one field name is specified, the counts
188
for all specified fields are added together to obtain the number for
189
comparison. Thus, specifying ["to", "cc"] in an address COUNT test
190
compares the total number of "to" and "cc" addresses; if separate
191
counts are desired, they must be done in two comparisons, perhaps
192
joined by "allof" or "anyof".
194
5. Interaction with Other Sieve Actions
196
This specification adds two match types. The VALUE match type only
197
works with comparators that return sort information. The COUNT match
198
type only makes sense with numeric comparators.
200
There is no interaction with any other Sieve operations, nor with any
201
known extensions. In particular, this specification has no effect on
202
implicit KEEP, nor on any explicit message actions.
211
to: foo@example.com, baz@example.com
216
address :count "ge" :comparator "i;ascii-numeric"
219
would evaluate to true, and the test
226
Segmuller & Leiba Standards Track [Page 4]
228
RFC 5231 Sieve: Relational Extension January 2008
231
anyof ( address :count "ge" :comparator "i;ascii-numeric"
233
address :count "ge" :comparator "i;ascii-numeric"
236
would evaluate to false.
238
To check the number of received fields in the header, the following
241
header :count "ge" :comparator "i;ascii-numeric"
244
This would evaluate to false. But
246
header :count "ge" :comparator "i;ascii-numeric"
247
["received", "subject"] ["3"]
249
would evaluate to true.
253
header :count "ge" :comparator "i;ascii-numeric"
256
will always evaluate to false on an RFC 2822 compliant message
257
[RFC2822], since a message can have at most one "to" field and at
258
most one "cc" field. This test counts the number of fields, not the
282
Segmuller & Leiba Standards Track [Page 5]
284
RFC 5231 Sieve: Relational Extension January 2008
289
require ["relational", "comparator-i;ascii-numeric", "fileinto"];
291
if header :value "lt" :comparator "i;ascii-numeric"
297
elsif address :count "gt" :comparator "i;ascii-numeric"
300
# everything with more than 5 recipients in the "to" field
305
elsif address :value "gt" :all :comparator "i;ascii-casemap"
313
if allof ( address :count "eq" :comparator "i;ascii-numeric"
315
address :all :comparator "i;ascii-casemap"
316
["to", "cc"] ["me@foo.example.com"] )
321
8. Changes since RFC 3431
323
Apart from several minor editorial/wording changes, the following
324
list describes the notable changes to this specification since RFC
327
o Updated references, including changing the comparator reference
328
from the Application Configuration Access Protocol (ACAP) to the
329
"Internet Application Protocol Collation Registry" document
332
o Updated and corrected the examples.
338
Segmuller & Leiba Standards Track [Page 6]
340
RFC 5231 Sieve: Relational Extension January 2008
343
o Added definition comments to ABNF for "gt", "lt", etc.
345
o Clarified what RFC 2822 elements are counted in the COUNT test.
347
o Removed the requirement to strip white space from header fields
348
before comparing; a more general version of this requirement has
349
been added to the Sieve base spec.
351
9. IANA Considerations
353
The following template specifies the IANA registration of the
354
relational Sieve extension specified in this document:
357
Subject: Registration of new Sieve extension
359
Capability name: relational
360
Description: Extends existing conditional tests in Sieve language
361
to allow relational operators
363
Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
365
10. Security Considerations
367
An implementation MUST ensure that the test for envelope "to" only
368
reflects the delivery to the current user. Using this test, it MUST
369
not be possible for a user to determine if this message was delivered
372
Additional security considerations are discussed in [Sieve].
374
11. Normative References
376
[ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
377
Specifications: ABNF", RFC 4234, October 2005.
379
[Kwds] Bradner, S., "Key words for use in RFCs to Indicate
380
Requirement Levels", RFC 2119, March 1997.
382
[RFC2822] Resnick, P., "Internet Message Format", RFC 2822,
385
[RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
386
Application Protocol Collation Registry", RFC 4790,
389
[Sieve] Guenther, P., Ed. and T. Showalter, Ed., "Sieve: An Email
390
Filtering Language", RFC 5228, January 2008.
394
Segmuller & Leiba Standards Track [Page 7]
396
RFC 5231 Sieve: Relational Extension January 2008
402
IBM T.J. Watson Research Center
407
Phone: +1 914 784 7408
408
EMail: werewolf@us.ibm.com
412
IBM T.J. Watson Research Center
417
Phone: +1 914 784 7941
418
EMail: leiba@watson.ibm.com
450
Segmuller & Leiba Standards Track [Page 8]
452
RFC 5231 Sieve: Relational Extension January 2008
455
Full Copyright Statement
457
Copyright (C) The IETF Trust (2008).
459
This document is subject to the rights, licenses and restrictions
460
contained in BCP 78, and except as set forth therein, the authors
461
retain all their rights.
463
This document and the information contained herein are provided on an
464
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
465
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
466
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
467
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
468
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
469
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
471
Intellectual Property
473
The IETF takes no position regarding the validity or scope of any
474
Intellectual Property Rights or other rights that might be claimed to
475
pertain to the implementation or use of the technology described in
476
this document or the extent to which any license under such rights
477
might or might not be available; nor does it represent that it has
478
made any independent effort to identify any such rights. Information
479
on the procedures with respect to rights in RFC documents can be
480
found in BCP 78 and BCP 79.
482
Copies of IPR disclosures made to the IETF Secretariat and any
483
assurances of licenses to be made available, or the result of an
484
attempt made to obtain a general license or permission for the use of
485
such proprietary rights by implementers or users of this
486
specification can be obtained from the IETF on-line IPR repository at
487
http://www.ietf.org/ipr.
489
The IETF invites any interested party to bring to its attention any
490
copyrights, patents or patent applications, or other proprietary
491
rights that may cover technology that may be required to implement
492
this standard. Please address the information to the IETF at
506
Segmuller & Leiba Standards Track [Page 9]