idnits 2.17.1 draft-ietf-sieve-variables-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1.a on line 15. -- Found old boilerplate from RFC 3978, Section 5.5 on line 588. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 606. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 612. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. ** The document seems to lack an RFC 3979 Section 5, para. 1 IPR Disclosure Acknowledgement -- however, there's a paragraph with a matching beginning. Boilerplate error? ( - It does however have an RFC 2026 Section 10.4(A) Disclaimer.) ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page == No 'Intended status' indicated for this document; assuming Proposed Standard == It seems as if not all pages are separated by form feeds - found 0 form feeds but 14 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (5 Apr 2005) is 6959 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'MODIFIER' is mentioned on line 342, but not defined == Missing Reference: 'COMPARATOR' is mentioned on line 439, but not defined == Missing Reference: 'MATCH-TYPE' is mentioned on line 439, but not defined ** Obsolete normative reference: RFC 2234 (ref. 'ABNF') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 3431 (ref. 'RELATIONAL') (Obsoleted by RFC 5231) ** Obsolete normative reference: RFC 3028 (ref. 'SIEVE') (Obsoleted by RFC 5228, RFC 5429) -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' -- Obsolete informational reference (is this intentional?): RFC 3685 (ref. 'SPAMTEST') (Obsoleted by RFC 5235) Summary: 10 errors (**), 0 flaws (~~), 7 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group K. T. Homme 2 Updates: 3028 3 Document: draft-ietf-sieve-variables-02.txt University of Oslo 4 Expires Oct 5, 2005 5 Apr 2005 6 Sieve Mail Filtering Language: Variables Extension 8 Status of this Memo 10 This document is an Internet-Draft and is subject to all provisions 11 of section 3 of RFC 3667. By submitting this Internet-Draft, each 12 author represents that any applicable patent or other IPR claims of 13 which he or she is aware have been or will be disclosed, and any of 14 which he or she become aware will be disclosed, in accordance with 15 RFC 3668. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 Distribution of this memo is unlimited. 35 Abstract 37 In advanced filtering rule sets, it is useful to keep state or 38 configuration details across rules. This extension changes the 39 interpretation of strings, adds an action to store data in variables, 40 and supplies a new test so that the value of a string can be 41 examined. 43 0. Meta-information on this draft 45 This information is intended to facilitate discussion. It will be 46 removed when this document leaves the Internet-Draft stage. 48 0.1. Discussion 50 This draft is intended to be an extension to the Sieve mail filtering 51 language, available from the RFC repository as 52 . 54 This draft and the Sieve language itself are being discussed on the 55 MTA Filters mailing list at . Subscription 56 requests can be sent to (send an 57 email message with the word "subscribe" in the body). More 58 information on the mailing list along with a WWW archive of back 59 messages is available at . 61 0.2. Noted Changes 63 0.2.1. Changes since -00 65 a) allow generic time zone names, without requiring implementations to 66 support it. added a "${timezone}" variable so that the user can 67 check if the implementation does support the time zone name he 68 wants. the default time zone was changed to localtime again. 70 b) allow back references from :matches as well as :regex. 72 c) added a section on implementation limits. 74 d) clarified global scope so that it spans include. 76 e) clarified that this draft only affects scripts which require 77 "variables". 79 f) changed modifiers into being tagged arguments for SET, added 80 precedence table. 82 g) added optional COMPARATOR to SET to solve the internationalisation 83 problem with :lower etc. 85 h) the name of the variable being SET is passed in a string to conform 86 with overall Sieve grammar. this string is explicitly disallowed 87 from containing variable references. 89 0.2.2. Changes since -01 91 a) clarify that a character is a Unicode character. 93 b) added paragraph warning against relying on Sieve for virus checking 94 to security section. 96 c) added a paragraph defining constant string. 98 d) added namespace to grammar. 100 e) removed SETDATE. 102 f) added wording and example requiring short-circuiting of test 103 evaluation. 105 0.2.3. Changes since -02 107 a) add references to Unicode and UTF-8, also more boilerplate 109 b) fixed a meaningless example. 111 c) changed term "numeric variables" to "numbered variables" to reduce 112 the chance of it being interpreted as variables holding integer 113 values. 115 d) allow future extensions to access the raw string value. 117 e) an unsuccessful match does NOT reset the numbered variables. 119 f) added definition of "string :count" 121 g) exceeding implementation limits on variable lengths should not make 122 scripts abort. 124 0.2.4. Changes since -03 126 a) clarify short-circuiting. 128 b) editorial changes. 130 0.2.5. Changes since -04 132 a) the wildcards in :matches was changed from greedy to non-greedy to 133 better support "principle of least surprise". added example to 134 illustrate the difference. 136 b) add definition of "variable"; clarify grammar is based on [SIEVE]; 137 clarify role of namespaces; add informative references for [REGEX] 138 and [SPAMTEST]; add normative reference for [RELATIONAL] 140 c) the use of unsupported numbered variables must be flagged as a 141 syntax error by implementations. 143 0.2.6. Changes since -00 (WG series) 145 a) added example for string test 147 b) moved introductory text for MODIFIER from 5.1 into 5.0 149 c) added Syntax line for MODIFIER. 151 d) added comment to an example showing that the non-greedy "*" still 152 matches everything due to implicit anchors. 154 e) added example of expansion of string with unbalanced braces. 156 f) updated reference to [SPAMTEST]. 158 0.2.7. Changes since -01 160 a) moved References from appendix into the document itself. 162 b) added example of SET with a comparator. 164 c) changed "highest value" to the less ambiguous "largest value". 166 d) updated reference to [UTF-8]. 168 e) allow numbered variables in namespaces. 170 f) change ${0} to mean the complete match. 172 0.3. Open Issues 174 Should we allow all-digit namespace components? e.g., array.var.2.3 175 to provide array variables. 177 This extension is in conflict with a MUST in [SIEVE] 2.4: "Tests MUST 178 NOT have side effects." This document therefore can't leave draft 179 status until a revised Sieve specification has been accepted by the 180 IESG. No significant changes to this draft are foreseen before 181 submission as a proposed standard. 183 1. Introduction 185 This is an extension to the Sieve language defined by [SIEVE]. It 186 adds support for storing and referencing named data. The mechanisms 187 detailed in this document will only apply to Sieve scripts that 188 include a require clause for the "variables" extension. The require 189 clauses themselves are not affected by this extension. 191 Conventions for notations are as in [SIEVE] section 1.1, including 192 use of [KEYWORDS] and [ABNF]. The grammar builds on the grammar of 193 [SIEVE]. In this document, "character" means a [UNICODE] character, 194 which may consist of multiple octets coded in [UTF-8], and "variable" 195 is a named reference to data stored or read back using the mechanisms 196 of this extension. 198 2. Capability Identifier 200 The capability string associated with the extension defined in this 201 document is "variables". 203 3. Interpretation of strings 205 This extension changes the semantics of quoted-string, multi-line- 206 literal and multi-line-dotstuff found in [SIEVE] to enable the 207 inclusion of the value of variables. 209 When a string is evaluated, substrings matching variable-ref SHALL be 210 replaced by the value of variable-name. Only one pass through the 211 string SHALL be done. Variable names are case insensitive, so "foo" 212 and "FOO" refer to the same variable. Unknown variables are replaced 213 by the empty string. 215 variable-ref = "${" *namespace variable-name "}" 216 variable-name = num-variable / identifier 217 namespace = identifier "." 218 num-variable = 1*DIGIT 220 Examples: 222 "&%${}!" => unchanged, as the empty string is an illegal 223 identifier 224 "${doh!}" => unchanged, as "!" is illegal in identifiers 226 The variable "company" holds the value "ACME". No other variables 227 are set. 229 "${full}" => the empty string 230 "${company}" => "ACME" 231 "${President, ${Company} Inc.}" 232 => "${President, ACME Inc.}" 233 "${BAD${Company}"=>"${BADACME" 235 The expanded string MUST use the variable values which are current 236 when control reaches the statement the string is part of. 238 Strings where no variable substitutions take place are referred to as 239 constant strings. Future extensions may specify that passing non- 240 constant strings as arguments to its actions or tests is an error. 242 Namespaces are meant for future extensions which make internal state 243 available through variables. These variables SHOULD be put in a 244 namespace with the same name as its capability string. Notice that 245 the user can not specify a namespace when setting variables with SET. 247 Tests or actions in future extensions may need to access the 248 unexpanded version of the string argument and, e.g., do the expansion 249 after setting variables in its namespace. The design of the 250 implementation should allow this. 252 3.1. Quoting 254 The semantics of quoting using backslash are not changed: backslash 255 quoting is resolved before doing variable substitution. 257 Examples: 258 "${fo\o}" => ${foo} => the expansion of variable foo. 259 "${fo\\o}" => ${fo\o} => illegal identifier => left verbatim. 260 "\${foo}" => ${foo} => the expansion of variable foo. 261 "\\${foo}" => \${foo} => a backslash character followed by the 262 expansion of variable foo. 264 If it is required to include a character sequence such as "${beep}" 265 verbatim in a text literal, the user can define a variable to 266 circumvent expansion to the empty string. 268 Example: 269 set "dollar" "$"; 270 set "text" "regarding ${dollar}{beep}"; 272 3.2. Numbered variables 274 The decimal value of the numbered variable name will index the list 275 of matching strings from the most recently evaluated successful match 276 of type ":matches" or ":regex" (see [REGEX]). The list is empty if 277 no match has been successful. 279 For ":matches", the list will contain one string for each wildcard 280 ("?" and "*") in the match pattern. Each string holds what the 281 corresponding wildcard expands to, possibly the empty string. The 282 wildcards match as little as possible (non-greedy matching). 284 For ":regex", the list will contain the strings corresponding to the 285 group operators. The groups are ordered by the position of the 286 opening parenthesis, from left to right. Note that in regular 287 expressions, expansions match as much as possible (greedy matching). 289 The first string in the list has index 1. If the index is out of 290 range, the empty string will be substituted. Index 0 contains the 291 matched part of the source value. 293 The interpreter MUST short-circuit tests, ie. not perform more tests 294 than necessary to find the result. Evaluation order MUST be left to 295 right. If a test has two or more list arguments, the implementation 296 is free to choose which to iterate over first. 298 Example: 300 require ["fileinto", "regex", "variables"]; 302 if header :regex "List-ID" "<(.*)@" { 303 fileinto "lists.${1}"; stop; 304 } 306 # This usually gives the same result as the above 307 if header :matches "List-ID" "*<*@*" { 308 fileinto "lists.${2}"; stop; 309 } 311 # Imagine the header 312 # Subject: [acme-users] [fwd] version 1.0 is out 313 if header :regex "Subject" "^[(.*)] (.*)$" { 314 # ${1} will hold "acme-users] [fwd" 315 stop; 316 } 317 if header :matches "Subject" "[*] *" { 318 # ${1} will hold "acme-users", 319 # ${2} will hold "[fwd] version 1.0 is out" 320 fileinfo "lists.${1}"; stop; 321 } 323 if address :matches ["To", "Cc"] ["coyote@**.com", 324 "wile@**.com"] { 325 # ${0} is the matching address. 326 # ${1} is always the empty string. 327 fileinto "business.${2}"; stop; 328 } else { 329 # Control wouldn't reach this block if any match was 330 # successful, so no numbered variables are set at this 331 # point. 332 } 334 if anyof (true, address :domain :matches "To" "*.com") { 335 # The second test is never evaluated, so there are 336 # still no numbered variables set. 337 stop; 338 } 340 4. Action set 342 Syntax: set [MODIFIER] [COMPARATOR] 344 The "set" action stores the specified value in the variable 345 identified by name. The name MUST be a constant string and conform 346 to the syntax of identifier. An illegal name MUST be detected as a 347 syntax error. 349 Modifiers are applied on a value before it is stored in the variable. 350 See next section for details. 352 The default comparator is "i;ascii-casemap". The comparator only 353 affects the result when certain modifiers are used. 355 All variables have global scope: they are visible until processing 356 stops. Variable names are case insensitive. 358 Example: 359 set "honorific" "Mr"; 360 set "first_name" "Wile"; 361 set "last_name" "Coyote"; 362 set "vacation" text: 363 Dear ${HONORIFIC} ${last_name}, 364 I'm out, please leave a message after the meep. 365 . 366 ; 368 "set" does not affect the implicit keep. 370 4.1. Modifiers 372 Syntax: ":lower" / ":upper" / ":lowerfirst" / ":upperfirst" / 373 ":length" 375 Modifier names are case insensitive. Unknown modifiers MUST yield a 376 syntax error. More than one modifier can be specified, in which case 377 they are applied according to this precedence list, largest value 378 first: 380 +-----------------------------+ 381 | Precedence Modifier | 382 +-----------------------------+ 383 | 3 :lower | 384 | :upper | 385 +-----------------------------+ 386 | 2 :lowerfirst | 387 | :upperfirst | 388 +-----------------------------+ 389 | 1 :length | 390 +-----------------------------+ 392 If two or more modifiers of the same precedence are used, they can be 393 applied in any order. 395 Examples: 396 # The value assigned to the variable is printed after the arrow 397 set "a" "juMBlEd lETteRS"; => "juMBlEd lETteRS" 398 set :length "b" "${a}"; => "15" 399 set :lower "b" "${a}"; => "jumbled letters" 400 set :lower :comparator "i;octet" 401 "b" "${a}"; => "juMBlEd lETteRS" 402 set :upperfirst "b" "${a}"; => "JuMBlEd lETteRS" 403 set :upperfirst :lower "b" "${a}"; => "Jumbled letters" 405 4.1.1. Modifier ":length" 407 The value is the decimal number of characters in the expansion, 408 converted to a string. 410 4.1.2. Case modifiers 412 These modifiers change the letters of the text from upper to lower 413 case or vice versa. The implementation MUST support US-ASCII, but is 414 not required to handle the entire Unicode repertoire. The comparator 415 specified SHOULD be consulted to establish which locale to use. 417 4.1.2.1. Modifier ":upper" 419 All lower case letters are converted to their upper case counterpart. 421 4.1.2.2. Modifier ":lower" 423 All upper case letters are converted to their lower case counterpart. 425 4.1.2.3. Modifier ":upperfirst" 427 The first character of the string is converted to upper case if it is 428 a letter and set in lower case. The rest of the string is left 429 unchanged. 431 4.1.2.4. Modifier ":lowerfirst" 433 The first character of the string is converted to lower case if it is 434 a letter and set in upper case. The rest of the string is left 435 unchanged. 437 5. Test string 439 Syntax: string [MATCH-TYPE] [COMPARATOR] 440 442 The "string" test evaluates to true if any of the source strings 443 matches any key. The type of match defaults to ":is". 445 Example: 446 set "state" "${state} pending"; 447 if string :matches " ${state} " "* pending *" { 448 # the above test always succeeds 449 } 451 The "relational" extension [RELATIONAL] adds a match type called 452 ":count". The count of a single string is 0 if it is the empty 453 string, or 1 otherwise. The count of a string list is the sum of the 454 counts of the member strings. 456 6. Implementation Limits 458 An implementation of this draft MUST support at least 128 distinct 459 variables. The supported length of variable names MUST be at least 460 32 characters. Each variable MUST be able to hold at least 4000 461 characters. Attempts to set the variable to a value larger than what 462 the implementation supports SHOULD be reported as an error at 463 compile-time if possible. If the attempt is discovered during run- 464 time, the value SHOULD be truncated and it MUST NOT be treated as an 465 error. 467 Numbered variables ${1} through ${9} MUST be supported. References 468 to higher indices than the implementation supports MUST be treated as 469 a syntax error which SHOULD be discovered at compile-time. 471 7. Security Considerations 473 When numbered variables are used, and the author of the script isn't 474 careful, strings can contain arbitrary values controlled by the 475 sender of the e-mail. 477 The introduction of variables makes advanced decision making easier 478 to write, but since no looping construct is provided, all Sieve 479 scripts will terminate in an orderly manner. 481 Sieve filtering should not be relied on as a security measure against 482 hostile e-mail messages. Sieve is designed to do simple, mostly 483 static tests, and is not suitable for use as a spam or virus checker, 484 where the perpetrator has a motivation to vary the format of the 485 email in order to avoid filtering rules. See also [SPAMTEST]. 487 8. IANA Considerations 489 The following template specifies the IANA registration of the 490 variables Sieve extension specified in this document: 492 To: iana@iana.org 493 Subject: Registration of new Sieve extension 495 Capability name: variables 496 Capability keyword: variables 497 Capability arguments: N/A 498 Standards Track/IESG-approved experimental RFC number: this RFC 499 Person and email address to contact for further information: 501 Kjetil Torgrim Homme 502 University of Oslo 503 Pb 1080, Blindern 504 NO-0316 OSLO 506 E-mail: kjetilho@ifi.uio.no 508 This information should be added to the list of sieve extensions 509 given on http://www.iana.org/assignments/sieve-extensions. 511 9. Acknowledgments 513 Thanks to Cyrus Daboo, Jutta Degener, Ned Freed, Lawrence Greenfield, 514 Mark E. Mallett, Alexey Melnikov, Peder Stray and Nigel Swinson for 515 valuable feedback. 517 10. Author's Address 519 Kjetil T. Homme 520 University of Oslo 521 PO Box 1080 522 0316 Oslo, Norway 524 Phone: +47 9366 0091 525 E-mail: kjetilho@ifi.uio.no 527 11. References 529 11.1. Normative references 531 [ABNF] Crocker, D. and Overell, P., "Augmented BNF for Syntax 532 Specifications: ABNF", RFC 2234, November 1997 534 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate 535 Requirement Levels", RFC 2119, March 1997. 537 [RELATIONAL] Segmuller, W., "Sieve Extension: Relational Tests", 538 RFC 3431, December 2002 540 [SIEVE] Showalter, T., "Sieve: A Mail Filtering Language", RFC 541 3028, January 2001. 543 [UNICODE] The Unicode Consortium, "The Unicode Standard -- 544 Worldwide Character Encoding -- Version 1.0", Addison- 545 Wesley, Volume 1, 1991, Volume 2, 1992. 547 [UTF-8] Yergeau, F., "UTF-8, a transformation format of 548 Unicode and ISO 10646", RFC 3629, November 2003. 550 11.2. Informative References 552 [REGEX] K. Murchison, "Sieve Email Filtering -- Regular 553 Expression Extension", Work in Progress. 555 [SPAMTEST] C. Daboo, "SIEVE Email Filtering: Spamtest and 556 VirusTest Extensions", RFC 3685, February 2004 558 Appendix B. Intellectual Property Rights Statement 560 The IETF takes no position regarding the validity or scope of any 561 intellectual property or other rights that might be claimed to 562 pertain to the implementation or use of the technology described in 563 this document or the extent to which any license under such rights 564 might or might not be available; neither does it represent that it 565 has made any effort to identify any such rights. Information on the 566 IETF's procedures with respect to rights in standards-track and 567 standards-related documentation can be found in BCP-11. Copies of 568 claims of rights made available for publication and any assurances of 569 licenses to be made available, or the result of an attempt made to 570 obtain a general license or permission for the use of such 571 proprietary rights by implementors or users of this specification can 572 be obtained from the IETF Secretariat. 574 Appendix C. Full Copyright Statement 576 Copyright (C) The Internet Society (2005). 578 This document is subject to the rights, licenses and restrictions 579 contained in BCP 78, and except as set forth therein, the authors 580 retain all their rights. 582 This document and the information contained herein are provided on an 583 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 584 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 585 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 586 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 587 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 588 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 590 Intellectual Property 592 The IETF takes no position regarding the validity or scope of any 593 Intellectual Property Rights or other rights that might be claimed to 594 pertain to the implementation or use of the technology described in 595 this document or the extent to which any license under such rights 596 might or might not be available; nor does it represent that it has 597 made any independent effort to identify any such rights. Information 598 on the IETF's procedures with respect to rights in IETF Documents can 599 be found in BCP 78 and BCP 79. 601 Copies of IPR disclosures made to the IETF Secretariat and any 602 assurances of licenses to be made available, or the result of an 603 attempt made to obtain a general license or permission for the use of 604 such proprietary rights by implementers or users of this 605 specification can be obtained from the IETF on-line IPR repository at 606 http://www.ietf.org/ipr. 608 The IETF invites any interested party to bring to its attention any 609 copyrights, patents or patent applications, or other proprietary 610 rights that may cover technology that may be required to implement 611 this standard. Please address the information to the IETF at ietf- 612 ipr@ietf.org. 614 Acknowledgement 616 Funding for the RFC Editor function is currently provided by the 617 Internet Society.