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