rfc5231.txt - rohrpost - A commandline mail client to change the world as we see it.
(HTM) git clone git://r-36.net/rohrpost
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
rfc5231.txt (15243B)
---
1
2
3
4
5
6
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
11
12
13 Sieve Email Filtering: Relational Extension
14
15 Status of This Memo
16
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.
22
23 Abstract
24
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.
30
31 This document obsoletes RFC 3431.
32
33 Table of Contents
34
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
48
49
50
51
52
53
54
55
56
57
58 Segmuller & Leiba Standards Track [Page 1]
59
60 RFC 5231 Sieve: Relational Extension January 2008
61
62
63 1. Introduction
64
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.
69
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.
76
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.
80
81 The capability string associated with the extension defined in this
82 document is "relational".
83
84 2. Conventions Used in This Document
85
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.
89
90 Conventions for notations are as in [Sieve] section 1.1, including
91 the use of [Kwds] and the use of [ABNF].
92
93 3. Comparators
94
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].
98
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.
102
103 Larger integers MAY be supported. Note: the "i;ascii-numeric"
104 comparator does not support negative numbers.
105
106
107
108
109
110
111
112
113
114 Segmuller & Leiba Standards Track [Page 2]
115
116 RFC 5231 Sieve: Relational Extension January 2008
117
118
119 4. Match Types
120
121 This document defines two new match types. They are the VALUE match
122 type and the COUNT match type.
123
124 The syntax is:
125
126 MATCH-TYPE =/ COUNT / VALUE
127
128 COUNT = ":count" relational-match
129
130 VALUE = ":value" relational-match
131
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 "!=".
140
141 4.1. Match Type VALUE
142
143 The VALUE match type does a relational comparison between strings.
144
145 The VALUE match type may be used with any comparator that returns
146 sort information.
147
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.
151
152 If there are multiple values on either side or both sides, the test
153 is considered true if any pair is true.
154
155 4.2. Match Type COUNT
156
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
160 test expression.
161
162 The COUNT match type SHOULD only be used with numeric comparators.
163
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.
167
168
169
170 Segmuller & Leiba Standards Track [Page 3]
171
172 RFC 5231 Sieve: Relational Extension January 2008
173
174
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
181 FROM is not empty.
182
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.
186
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".
193
194 5. Interaction with Other Sieve Actions
195
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.
199
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.
203
204 6. Example
205
206 Using the message:
207
208 received: ...
209 received: ...
210 subject: example
211 to: foo@example.com, baz@example.com
212 cc: qux@example.com
213
214 The test:
215
216 address :count "ge" :comparator "i;ascii-numeric"
217 ["to", "cc"] ["3"]
218
219 would evaluate to true, and the test
220
221
222
223
224
225
226 Segmuller & Leiba Standards Track [Page 4]
227
228 RFC 5231 Sieve: Relational Extension January 2008
229
230
231 anyof ( address :count "ge" :comparator "i;ascii-numeric"
232 ["to"] ["3"],
233 address :count "ge" :comparator "i;ascii-numeric"
234 ["cc"] ["3"] )
235
236 would evaluate to false.
237
238 To check the number of received fields in the header, the following
239 test may be used:
240
241 header :count "ge" :comparator "i;ascii-numeric"
242 ["received"] ["3"]
243
244 This would evaluate to false. But
245
246 header :count "ge" :comparator "i;ascii-numeric"
247 ["received", "subject"] ["3"]
248
249 would evaluate to true.
250
251 The test:
252
253 header :count "ge" :comparator "i;ascii-numeric"
254 ["to", "cc"] ["3"]
255
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
259 number of addresses.
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282 Segmuller & Leiba Standards Track [Page 5]
283
284 RFC 5231 Sieve: Relational Extension January 2008
285
286
287 7. Extended Example
288
289 require ["relational", "comparator-i;ascii-numeric", "fileinto"];
290
291 if header :value "lt" :comparator "i;ascii-numeric"
292 ["x-priority"] ["3"]
293 {
294 fileinto "Priority";
295 }
296
297 elsif address :count "gt" :comparator "i;ascii-numeric"
298 ["to"] ["5"]
299 {
300 # everything with more than 5 recipients in the "to" field
301 # is considered SPAM
302 fileinto "SPAM";
303 }
304
305 elsif address :value "gt" :all :comparator "i;ascii-casemap"
306 ["from"] ["M"]
307 {
308 fileinto "From N-Z";
309 } else {
310 fileinto "From A-M";
311 }
312
313 if allof ( address :count "eq" :comparator "i;ascii-numeric"
314 ["to", "cc"] ["1"] ,
315 address :all :comparator "i;ascii-casemap"
316 ["to", "cc"] ["me@foo.example.com"] )
317 {
318 fileinto "Only me";
319 }
320
321 8. Changes since RFC 3431
322
323 Apart from several minor editorial/wording changes, the following
324 list describes the notable changes to this specification since RFC
325 3431.
326
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
330 [RFC4790].
331
332 o Updated and corrected the examples.
333
334
335
336
337
338 Segmuller & Leiba Standards Track [Page 6]
339
340 RFC 5231 Sieve: Relational Extension January 2008
341
342
343 o Added definition comments to ABNF for "gt", "lt", etc.
344
345 o Clarified what RFC 2822 elements are counted in the COUNT test.
346
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.
350
351 9. IANA Considerations
352
353 The following template specifies the IANA registration of the
354 relational Sieve extension specified in this document:
355
356 To: iana@iana.org
357 Subject: Registration of new Sieve extension
358
359 Capability name: relational
360 Description: Extends existing conditional tests in Sieve language
361 to allow relational operators
362 RFC number: RFC 5231
363 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
364
365 10. Security Considerations
366
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
370 to someone else.
371
372 Additional security considerations are discussed in [Sieve].
373
374 11. Normative References
375
376 [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
377 Specifications: ABNF", RFC 4234, October 2005.
378
379 [Kwds] Bradner, S., "Key words for use in RFCs to Indicate
380 Requirement Levels", RFC 2119, March 1997.
381
382 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822,
383 April 2001.
384
385 [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
386 Application Protocol Collation Registry", RFC 4790,
387 March 2007.
388
389 [Sieve] Guenther, P., Ed. and T. Showalter, Ed., "Sieve: An Email
390 Filtering Language", RFC 5228, January 2008.
391
392
393
394 Segmuller & Leiba Standards Track [Page 7]
395
396 RFC 5231 Sieve: Relational Extension January 2008
397
398
399 Authors' Addresses
400
401 Wolfgang Segmuller
402 IBM T.J. Watson Research Center
403 19 Skyline Drive
404 Hawthorne, NY 10532
405 US
406
407 Phone: +1 914 784 7408
408 EMail: werewolf@us.ibm.com
409
410
411 Barry Leiba
412 IBM T.J. Watson Research Center
413 19 Skyline Drive
414 Hawthorne, NY 10532
415 US
416
417 Phone: +1 914 784 7941
418 EMail: leiba@watson.ibm.com
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450 Segmuller & Leiba Standards Track [Page 8]
451
452 RFC 5231 Sieve: Relational Extension January 2008
453
454
455 Full Copyright Statement
456
457 Copyright (C) The IETF Trust (2008).
458
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.
462
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.
470
471 Intellectual Property
472
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.
481
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.
488
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
493 ietf-ipr@ietf.org.
494
495
496
497
498
499
500
501
502
503
504
505
506 Segmuller & Leiba Standards Track [Page 9]
507