rfc3431.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
---
rfc3431.txt (12849B)
---
1
2
3
4
5
6
7 Network Working Group W. Segmuller
8 Request for Comment: 3431 IBM T.J. Watson Research Center
9 Category: Standards Track December 2002
10
11
12 Sieve Extension: Relational Tests
13
14 Status of this Memo
15
16 This document specifies an Internet standards track protocol for the
17 Internet community, and requests discussion and suggestions for
18 improvements. Please refer to the current edition of the "Internet
19 Official Protocol Standards" (STD 1) for the standardization state
20 and status of this protocol. Distribution of this memo is unlimited.
21
22 Copyright Notice
23
24 Copyright (C) The Internet Society (2002). All Rights Reserved.
25
26 Abstract
27
28 This document describes the RELATIONAL extension to the Sieve mail
29 filtering language defined in RFC 3028. This extension extends
30 existing conditional tests in Sieve to allow relational operators.
31 In addition to testing their content, it also allows for testing of
32 the number of entities in header and envelope fields.
33
34 1 Introduction
35
36 Sieve [SIEVE] is a language for filtering e-mail messages at the time
37 of final delivery. It is designed to be implementable on either a
38 mail client or mail server. It is meant to be extensible, simple,
39 and independent of access protocol, mail architecture, and operating
40 system. It is suitable for running on a mail server where users may
41 not be allowed to execute arbitrary programs, such as on black box
42 Internet Messages Access Protocol (IMAP) servers, as it has no
43 variables, loops, nor the ability to shell out to external programs.
44
45 The RELATIONAL extension provides relational operators on the
46 address, envelope, and header tests. This extension also provides a
47 way of counting the entities in a message header or address field.
48
49 With this extension, the sieve script may now determine if a field is
50 greater than or less than a value instead of just equivalent. One
51 use is for the x-priority field: move messages with a priority
52 greater than 3 to the "work on later" folder. Mail could also be
53 sorted by the from address. Those userids that start with 'a'-'m' go
54 to one folder, and the rest go to another folder.
55
56
57
58 Segmuller Standards Track [Page 1]
59
60 RFC 3431 Sieve Extension: Relational Tests December 2002
61
62
63 The sieve script can also determine the number of fields in the
64 header, or the number of addresses in a recipient field. For
65 example: are there more than 5 addresses in the to and cc fields.
66
67 2 Conventions used in this document
68
69 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
70 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
71 document are to be interpreted as described in BCP 14, RFC 2119.
72
73 Conventions for notations are as in [SIEVE] section 1.1, including
74 the use of [KEYWORDS] and "Syntax:" label for the definition of
75 action and tagged arguments syntax, and the use of [ABNF].
76
77 The capability string associated with extension defined in this
78 document is "relational".
79
80 3 Comparators
81
82 This document does not define any comparators or exempt any
83 comparators from the require clause. Any comparator used, other than
84 "i;octet" and "i;ascii-casemap", MUST be declared a require clause as
85 defined in [SIEVE].
86
87 The "i;ascii-numeric" comparator, as defined in [ACAP], MUST be
88 supported for any implementation of this extension. The comparator
89 "i;ascii-numeric" MUST support at least 32 bit unsigned integers.
90
91 Larger integers MAY be supported. Note: the "i;ascii-numeric"
92 comparator does not support negative numbers.
93
94 4 Match Type
95
96 This document defines two new match types. They are the VALUE match
97 type and the COUNT match type.
98
99 The syntax is:
100
101 MATCH-TYPE =/ COUNT / VALUE
102
103 COUNT = ":count" relational-match
104
105 VALUE = ":value" relational-match
106
107 relational-match = DQUOTE ( "gt" / "ge" / "lt"
108 / "le" / "eq" / "ne" ) DQUOTE
109
110
111
112
113
114 Segmuller Standards Track [Page 2]
115
116 RFC 3431 Sieve Extension: Relational Tests December 2002
117
118
119 4.1 Match Type Value
120
121 The VALUE match type does a relational comparison between strings.
122
123 The VALUE match type may be used with any comparator which returns
124 sort information.
125
126 Leading and trailing white space MUST be removed from the value of
127 the message for the comparison. White space is defined as
128
129 SP / HTAB / CRLF
130
131 A value from the message is considered the left side of the relation.
132 A value from the test expression, the key-list for address, envelope,
133 and header tests, is the right side of the relation.
134
135 If there are multiple values on either side or both sides, the test
136 is considered true, if any pair is true.
137
138 4.2 Match Type Count
139
140 The COUNT match type first determines the number of the specified
141 entities in the message and does a relational comparison of the
142 number of entities to the values specified in the test expression.
143
144 The COUNT match type SHOULD only be used with numeric comparators.
145
146 The Address Test counts the number of recipients in the specified
147 fields. Group names are ignored.
148
149 The Envelope Test counts the number of recipients in the specified
150 envelope parts. The envelope "to" will always have only one entry,
151 which is the address of the user for whom the sieve script is
152 running. There is no way a sieve script can determine if the message
153 was actually sent to someone else using this test. The envelope
154 "from" will be 0 if the MAIL FROM is blank, or 1 if MAIL FROM is not
155 blank.
156
157 The Header Test counts the total number of instances of the specified
158 fields. This does not count individual addresses in the "to", "cc",
159 and other recipient fields.
160
161 In all cases, if more than one field name is specified, the counts
162 for all specified fields are added together to obtain the number for
163 comparison. Thus, specifying ["to", "cc"] in an address COUNT test,
164 comparing the total number of "to" and "cc" addresses; if separate
165 counts are desired, they must be done in two comparisons, perhaps
166 joined by "allof" or "anyof".
167
168
169
170 Segmuller Standards Track [Page 3]
171
172 RFC 3431 Sieve Extension: Relational Tests December 2002
173
174
175 5 Security Considerations
176
177 Security considerations are discussed in [SIEVE].
178
179 An implementation MUST ensure that the test for envelope "to" only
180 reflects the delivery to the current user. It MUST not be possible
181 for a user to determine if this message was delivered to someone else
182 using this test.
183
184 6 Example
185
186 Using the message:
187
188 received: ...
189 received: ...
190 subject: example
191 to: foo@example.com.invalid, baz@example.com.invalid
192 cc: qux@example.com.invalid
193
194 The test:
195
196 address :count "ge" :comparator "i;ascii-numeric" ["to", "cc"]
197 ["3"]
198
199 would be true and the test
200
201 anyof ( address :count "ge" :comparator "i;ascii-numeric"
202 ["to"] ["3"],
203 address :count "ge" :comparator "i;ascii-numeric"
204 ["cc"] ["3"] )
205
206 would be false.
207
208 To check the number of received fields in the header, the
209 following test may be used:
210
211 header :count "ge" :comparator "i;ascii-numeric"
212 ["received"] ["3"]
213
214 This would return false. But
215
216 header :count "ge" :comparator "i;ascii-numeric"
217 ["received", "subject"] ["3"]
218
219 would return true.
220
221
222
223
224
225
226 Segmuller Standards Track [Page 4]
227
228 RFC 3431 Sieve Extension: Relational Tests December 2002
229
230
231 The test:
232
233 header :count "ge" :comparator "i;ascii-numeric"
234 ["to", "cc"] ["3"]
235
236 will always return false on an RFC 2822 compliant message [RFC2822],
237 since a message can have at most one "to" field and at most one "cc"
238 field. This test counts the number of fields, not the number of
239 addresses.
240
241 7 Extended Example
242
243 require ["relational", "comparator-i;ascii-numeric"];
244
245 if header :value "lt" :comparator "i;ascii-numeric"
246 ["x-priority"] ["3"]
247 {
248 fileinto "Priority";
249 }
250
251 elseif address :count "gt" :comparator "i;ascii-numeric"
252 ["to"] ["5"]
253 {
254 # everything with more than 5 recipients in the "to" field
255 # is considered SPAM
256 fileinto "SPAM";
257 }
258
259 elseif address :value "gt" :all :comparator "i;ascii-casemap"
260 ["from"] ["M"]
261 {
262 fileinto "From N-Z";
263 } else {
264 fileinto "From A-M";
265 }
266
267 if allof ( address :count "eq" :comparator "i;ascii-numeric"
268 ["to", "cc"] ["1"] ,
269 address :all :comparator "i;ascii-casemap"
270 ["to", "cc"] ["me@foo.example.com.invalid"]
271 {
272 fileinto "Only me";
273 }
274
275
276
277
278
279
280
281
282 Segmuller Standards Track [Page 5]
283
284 RFC 3431 Sieve Extension: Relational Tests December 2002
285
286
287 8 IANA Considerations
288
289 The following template specifies the IANA registration of the Sieve
290 extension specified in this document:
291
292 To: iana@iana.org
293 Subject: Registration of new Sieve extension
294
295 Capability name: RELATIONAL
296 Capability keyword: relational
297 Capability arguments: N/A
298 Standards Track/IESG-approved experimental RFC number: this RFC
299 Person and email address to contact for further information:
300 Wolfgang Segmuller
301 IBM T.J. Watson Research Center
302 30 Saw Mill River Rd
303 Hawthorne, NY 10532
304
305 Email: whs@watson.ibm.com
306
307 This information should be added to the list of sieve extensions
308 given on http://www.iana.org/assignments/sieve-extensions.
309
310 9 References
311
312 9.1 Normative References
313
314 [SIEVE] Showalter, T., "Sieve: A Mail Filtering Language", RFC
315 3028, January 2001.
316
317 [Keywords] Bradner, S., "Key words for use in RFCs to Indicate
318 Requirement Levels", BCP 14, RFC 2119, March 1997.
319
320 [ABNF] Crocker, D., "Augmented BNF for Syntax Specifications:
321 ABNF", RFC 2234, November 1997.
322
323 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April
324 2001.
325
326 9.2 Non-Normative References
327
328 [ACAP] Newman, C. and J. G. Myers, "ACAP -- Application
329 Configuration Access Protocol", RFC 2244, November 1997.
330
331
332
333
334
335
336
337
338 Segmuller Standards Track [Page 6]
339
340 RFC 3431 Sieve Extension: Relational Tests December 2002
341
342
343 10 Author's Address
344
345 Wolfgang Segmuller
346 IBM T.J. Watson Research Center
347 30 Saw Mill River Rd
348 Hawthorne, NY 10532
349
350 EMail: whs@watson.ibm.com
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394 Segmuller Standards Track [Page 7]
395
396 RFC 3431 Sieve Extension: Relational Tests December 2002
397
398
399 11 Full Copyright Statement
400
401 Copyright (C) The Internet Society (2002). All Rights Reserved.
402
403 This document and translations of it may be copied and furnished to
404 others, and derivative works that comment on or otherwise explain it
405 or assist in its implementation may be prepared, copied, published
406 and distributed, in whole or in part, without restriction of any
407 kind, provided that the above copyright notice and this paragraph are
408 included on all such copies and derivative works. However, this
409 document itself may not be modified in any way, such as by removing
410 the copyright notice or references to the Internet Society or other
411 Internet organizations, except as needed for the purpose of
412 developing Internet standards in which case the procedures for
413 copyrights defined in the Internet Standards process must be
414 followed, or as required to translate it into languages other than
415 English.
416
417 The limited permissions granted above are perpetual and will not be
418 revoked by the Internet Society or its successors or assigns.
419
420 This document and the information contained herein is provided on an
421 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
422 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
423 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
424 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
425 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
426
427 Acknowledgement
428
429 Funding for the RFC Editor function is currently provided by the
430 Internet Society.
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450 Segmuller Standards Track [Page 8]
451