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