idnits 2.17.1 draft-homme-sieve-variables-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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 ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 12 longer pages, the longest (page 3) being 74 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 12 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 128: '... This extension is in conflict with a MUST in [SIEVE] 2.4: "Tests MUST...' RFC 2119 keyword, line 158: '...strings matching variable-ref SHALL be...' RFC 2119 keyword, line 160: '... string SHALL be done. Variable nam...' RFC 2119 keyword, line 182: '... expanded string MUST use the variable...' RFC 2119 keyword, line 190: '... These variables SHOULD be put in a na...' (14 more instances...) 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 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 (15 Sep 2004) is 7164 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 section? 'SIEVE' on line 449 looks like a reference -- Missing reference section? 'KEYWORDS' on line 445 looks like a reference -- Missing reference section? 'ABNF' on line 441 looks like a reference -- Missing reference section? 'UNICODE' on line 452 looks like a reference -- Missing reference section? 'UTF-8' on line 456 looks like a reference -- Missing reference section? 'MODIFIER' on line 273 looks like a reference -- Missing reference section? 'COMPARATOR' on line 359 looks like a reference -- Missing reference section? 'MATCH-TYPE' on line 359 looks like a reference Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group K. T. Homme 3 Updates: 3028 4 Document: draft-homme-sieve-variables-04.txt University of Oslo 5 Expires Mar 15, 2005 15 Sep 2004 7 Sieve -- Variables Extension 9 Status of this Memo 11 This document is an Internet-Draft and is subject to all provisions 12 of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as Internet- 17 Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six months 20 and may be updated, replaced, or obsoleted by other documents at any 21 time. It is inappropriate to use Internet-Drafts as reference mate- 22 rial or to cite them other than as "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/ietf/1id-abstracts.txt 27 To view the list Internet-Draft Shadow Directories, see 28 http://www.ietf.org/shadow.html. 30 Distribution of this memo is unlimited. 32 Abstract 34 In advanced filtering rule sets, it is useful to keep state or con- 35 figuration details across rules. This extension changes the interpo- 36 lation of strings, adds an action to store data in variables, and 37 supplies a new test so that the value of a string can be examined. 39 0. Meta-information on this draft 41 This information is intended to facilitate discussion. It will be 42 removed when this document leaves the Internet-Draft stage. 44 0.1. Discussion 46 This draft is intended to be an extension to the Sieve mail filtering 47 language, available from the RFC repository as 48 . 50 This draft and the Sieve language itself are being discussed on the 51 MTA Filters mailing list at . Subscription 52 requests can be sent to (send an 53 email message with the word "subscribe" in the body). More informa- 54 tion on the mailing list along with a WWW archive of back messages is 55 available at . 57 0.2. Noted Changes 59 0.2.1. Changes since -00 61 a) allow generic time zone names, without requiring implementations to 62 support it. added a "${timezone}" variable so that the user can 63 check if the implementation does support the time zone name he 64 wants. the default time zone was changed to localtime again. 66 b) allow back references from :matches as well as :regex. 68 c) added a section on implementation limits. 70 d) clarified global scope so that it spans include. 72 e) clarified that this draft only affects scripts which require "vari- 73 ables". 75 f) changed modifiers into being tagged arguments for SET, added prece- 76 dence table. 78 g) added optional COMPARATOR to SET to solve the internationalisation 79 problem with :lower etc. 81 h) the name of the variable being SET is passed in a string to conform 82 with overall Sieve grammar. this string is explicitly disallowed 83 from containing variable references. 85 0.2.2. Changes since -01 87 a) clarify that a character is a Unicode character. 89 b) added paragraph warning against relying on Sieve for virus checking 90 to security section. 92 c) added a paragraph defining constant string. 94 d) added namespace to grammar. 96 e) removed SETDATE. 98 f) added wording and example requiring short-circuiting of test evalu- 99 ation. 101 0.2.3. Changes since -02 103 a) add references to Unicode and UTF-8, also more boilerplate 105 b) fixed a meaningless example. 107 c) changed term "numeric variables" to "numbered variables" to reduce 108 the chance of it being interpreted as variables holding integer 109 values. 111 d) allow future extensions to access the raw string value. 113 e) an unsuccessful match does NOT reset the numbered variables. 115 f) added definition of "string :count" 117 g) exceeding implementation limits on variable lengths should not make 118 scripts abort. 120 0.2.4. Changes since -02 122 a) clarify short-circuiting. 124 b) editorial changes. 126 0.3. Open Issues 128 This extension is in conflict with a MUST in [SIEVE] 2.4: "Tests MUST 129 NOT have side effects." This document therefore can't leave draft 130 status until a revised Sieve specification has been accepted by the 131 IESG. No significant changes to this draft are foreseen before sub- 132 mission as a proposed standard. 134 1. Introduction 136 This is an extension to the Sieve language defined by [SIEVE]. It 137 adds support for storing and referencing data in string variables. 138 The mechanisms detailed in this document will only apply to Sieve 139 scripts that include a require clause for the "variables" extension. 140 The require clauses themselves are not affected by this extension. 142 Conventions for notations are as in [SIEVE] section 1.1, including 143 use of [KEYWORDS] and [ABNF]. In this document, "character" means a 144 [UNICODE] character, which may consist of multiple octets coded in 145 [UTF-8]. 147 2. Capability Identifier 149 The capability string associated with the extension defined in this 150 document is "variables". 152 3. Interpretation of strings 154 This extension changes the semantics of quoted-string, multi-line- 155 literal and multi-line-dotstuff found in [SIEVE] to enable the inclu- 156 sion of the value of variables. 158 When a string is evaluated, substrings matching variable-ref SHALL be 159 replaced by the value of variable-name. Only one pass through the 160 string SHALL be done. Variable names are case insensitive, so "foo" 161 and "FOO" refer to the same variable. Unknown variables are replaced 162 by the empty string. 164 variable-ref = "${" variable-name "}" 165 variable-name = num-variable / *namespace identifier 166 namespace = identifier "." 167 num-variable = 1*DIGIT 169 Examples: 170 "&%${}!" => unchanged, as the empty string is an illegal 171 identifier 172 "${doh!}" => unchanged, as "!" is illegal in identifiers 174 The variable company holds the value "ACME". No other variables 175 are set. 177 "${full}" => the empty string 178 "${company}" => "ACME" 179 "${President, ${Company} Inc.}" 180 => "${President, ACME Inc.}" 182 The expanded string MUST use the variable values which are current 183 when control reaches the statement the string is part of. 185 Strings where no variable substitutions take place are referred to as 186 constant strings. Future extensions may specify that passing non- 187 constant strings as arguments to its actions or tests is an error. 189 Future extensions may make internal state available through vari- 190 ables. These variables SHOULD be put in a namespace with the same 191 name as its capability string. Notice that the user can not specify 192 a namespace when setting variables with SET. 194 Tests or actions in future extensions may need to access the unex- 195 panded version of the string argument and, e.g., do the expansion 196 after setting variables in its namespace. The design of the imple- 197 mentation should allow this. 199 3.1. Quoting 201 The semantics of quoting using backslash are not changed: backslash 202 quoting is resolved before doing variable substitution. 204 Examples: 205 "${fo\o}" => ${foo} => the expansion of variable foo. 206 "${fo\\o}" => ${fo\o} => illegal identifier => left verbatim. 207 "\${foo}" => ${foo} => the expansion of variable foo. 208 "\\${foo}" => \${foo} => a backslash character followed by the 209 expansion of variable foo. 211 If it is required to include a character sequence such as "${beep}" 212 verbatim in a text literal, the user can define a variable to circum- 213 vent expansion to the empty string. 215 Example: 216 set "dollar" "$"; 217 set "text" "regarding ${dollar}{beep}"; 219 3.2. Numbered variables 221 The decimal value of the numbered variable name will index the list 222 of matching strings from the most recently evaluated successful match 223 of type ":matches" or ":regex". The list is empty if no match has 224 been successful. 226 For ":matches", the list will contain one string for each wildcard 227 ("?" and "*") in the match pattern. Each string holds what the cor- 228 responding wildcard expands to, possibly the empty string. The wild- 229 cards expand greedily. 231 For ":regex", the list will contain the strings corresponding to the 232 group operators. The groups are ordered by the position of the open- 233 ing parenthesis, from left to right. 235 The first string in the list has index 1. If the index is out of 236 range, the empty string will be substituted. Index 0 returns the 237 number of strings in the list as a decimal number. 239 The interpreter MUST short-circuit tests, ie. not perform more tests 240 than necessary to find the result. Evaluation order MUST be left to 241 right. If a test has two or more list arguments, the implementation 242 is free to choose which to iterate over first. 244 Example: 246 require [ "fileinto", "regex", "variables" ]; 248 if header :regex "List-ID" "<(.*)@" { 249 fileinto "lists.${1}"; stop; 250 } 252 # this is equivalent to the above: 253 if header :matches "List-ID" "*<*@*" { 254 fileinto "lists.${2}"; stop; 255 } 257 if address :matches [ "To", "Cc" ] "coyote@**.com" { 258 # ${0} is always "2", and ${2} is always the empty string. 259 fileinto "business.${1}"; stop; 260 } else { 261 # control can't reach this block if any match was 262 # successful, so ${0} is always "0" here. 263 stop; 264 } 266 if anyof (true, address :domain :matches "To" "*.com") { 267 # second test is never evaluated, so ${0} is still "0" 268 stop; 269 } 271 4. Action set 273 Syntax: set [MODIFIER] [COMPARATOR] 275 The "set" action stores the specified value in the variable identi- 276 fied by name. The name MUST be a constant string and conform to the 277 syntax of identifier. An illegal name MUST cause a syntax error. 279 The default comparator is "i;ascii-casemap". The comparator only 280 affects the result when certain modifiers are used. 282 All variables have global scope: they are visible until processing 283 stops. Variable names are case insensitive. 285 Example: 286 set "honorific" "Mr"; 287 set "first_name" "Wile"; 288 set "last_name" "Coyote"; 289 set "vacation" text: 290 Dear ${HONORIFIC} ${last_name}, 291 I'm out, please leave a message after the meep. 292 . 293 ; 295 "set" does not affect the implicit keep. 297 4.1. Modifiers 299 Modifiers are applied on a value before it is stored in the variable. 300 Modifier names are case insensitive. Unknown modifiers MUST yield a 301 syntax error. More than one modifier can be specified, in which case 302 they are applied according to this precedence list, highest value 303 first: 305 Precedence Modifier 306 ----------------------------- 307 1 :length 308 ----------------------------- 309 2 :lowerfirst 310 :upperfirst 311 ----------------------------- 312 3 :lower 313 :upper 315 If two or more modifiers of the same precedence are used, they can be 316 applied in any order. 318 Examples: 319 set "a" "juMBlEd lETteRS"; => "juMBlEd lETteRS" 320 set :length "b" "${a}"; => "15" 321 set :lower "b" "${a}"; => "jumbled letters" 322 set :upperfirst "b" "${a}"; => "JuMBlEd lETteRS" 323 set :upperfirst :lower "b" "${a}"; => "Jumbled letters" 325 4.1.1. Modifier ":length" 327 The value is the decimal number of characters in the expansion, con- 328 verted to a string. 330 4.1.2. Case modifiers 332 These modifiers change the letters of the text from upper to lower 333 case or vice versa. The implementation MUST support US-ASCII, but is 334 not required to handle the entire Unicode repertoire. The comparator 335 specified SHOULD be consulted to establish which locale to use. 337 4.1.2.1. Modifier ":upper" 339 All lower case letters are converted to their upper case counterpart. 341 4.1.2.2. Modifier ":lower" 343 All upper case letters are converted to their lower case counterpart. 345 4.1.2.3. Modifier ":upperfirst" 347 The first character of the string is converted to upper case if it is 348 a letter and set in lower case. The rest of the string is left 349 unchanged. 351 4.1.2.4. Modifier ":lowerfirst" 353 The first character of the string is converted to lower case if it is 354 a letter and set in upper case. The rest of the string is left 355 unchanged. 357 5. Test string 359 Syntax: string [MATCH-TYPE] [COMPARATOR] 360 362 The "string" test evaluates to true if any of the source strings 363 matches any key. The type of match defaults to ":is". 365 The "relational" extension adds a match type called ":count". The 366 count of a single string is 0 if it is the empty string, or 1 other- 367 wise. The count of a string list is the sum of the counts of the 368 member strings. 370 6. Implementation Limits 372 An implementation of this draft MUST support at least 128 distinct 373 variables. The supported length of variable names MUST be at least 374 32 characters. Each variable MUST be able to hold at least 4000 375 characters. Attempts to set the variable to a value larger than what 376 the implementation supports SHOULD be reported as an error at com- 377 pile-time if possible. If the attempt is discovered during run-time, 378 the value SHOULD be truncated and it MUST NOT be treated as an error. 380 Numbered variables ${1} through ${9} MUST be supported. References 381 to higher indices than the implementation supports should be treated 382 as a syntax error which MUST be discovered at compile-time. 384 7. Security Considerations 386 When numbered variables are used, and the author of the script isn't 387 careful, strings can contain arbitrary values controlled by the 388 sender of the e-mail. 390 The introduction of variables makes advanced decision making easier 391 to write, but since no looping construct is provided, all Sieve 392 scripts will terminate orderly. 394 Sieve filtering should not be relied on as a security measure against 395 hostile e-mail messages. Sieve is designed to do simple, mostly 396 static tests, and is not suitable for use as a spam or virus checker, 397 where the perpetrator has a motivation to vary the format of the 398 email in order to avoid filtering rules. 400 8. IANA Considerations 402 The following template specifies the IANA registration of the vari- 403 ables Sieve extension specified in this document: 405 To: iana@iana.org 406 Subject: Registration of new Sieve extension 408 Capability name: variables 409 Capability keyword: variables 410 Capability arguments: N/A 411 Standards Track/IESG-approved experimental RFC number: this RFC 412 Person and email address to contact for further information: 414 Kjetil Torgrim Homme 415 University of Oslo 416 Pb 1080, Blindern 417 NO-0316 OSLO 419 E-mail: kjetilho@ifi.uio.no 421 This information should be added to the list of sieve extensions 422 given on http://www.iana.org/assignments/sieve-extensions. 424 9. Acknowledgments 426 Thanks to Jutta Degener, Ned Freed, Lawrence Greenfield, Peder Stray 427 and Nigel Swinson for valuable feedback. 429 10. Author's Address 431 Kjetil T. Homme 432 University of Oslo 433 PO Box 1080 434 0316 Oslo, Norway 436 Phone: +47 9366 0091 437 E-mail: kjetilho@ifi.uio.no 439 Appendix A. Normative References 441 [ABNF] D. Crocker, Ed., "Augmented BNF for Syntax Specifica- 442 tions: ABNF", Internet Mail Consortium, RFC 2234, Novem- 443 ber 1997 445 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate 446 Requirement Levels", Harvard University, RFC 2119, March 447 1997. 449 [SIEVE] Showalter, T., "Sieve: A Mail Filtering Language", Mira- 450 point, RFC 3028, January 2001. 452 [UNICODE] The Unicode Consortium, "The Unicode Standard -- World- 453 wide Character Encoding -- Version 1.0", Addison-Wesley, 454 Volume 1, 1991, Volume 2, 1992. 456 [UTF-8] Yergeau, F., "UTF-8, a transformation format of Unicode 457 and ISO 10646", RFC 2044, October 1996. 459 Appendix B. Intellectual Property Rights Statement 461 The IETF takes no position regarding the validity or scope of any 462 intellectual property or other rights that might be claimed to per- 463 tain to the implementation or use of the technology described in this 464 document or the extent to which any license under such rights might 465 or might not be available; neither does it represent that it has made 466 any effort to identify any such rights. Information on the IETF's 467 procedures with respect to rights in standards-track and standards- 468 related documentation can be found in BCP-11. Copies of claims of 469 rights made available for publication and any assurances of licenses 470 to be made available, or the result of an attempt made to obtain a 471 general license or permission for the use of such proprietary rights 472 by implementors or users of this specification can be obtained from 473 the IETF Secretariat. 475 Appendix C. Full Copyright Statement 477 Copyright (C) The Internet Society 2003. All Rights Reserved. 479 This document and translations of it may be copied and furnished to 480 others, and derivative works that comment on or otherwise explain it 481 or assist in its implementation may be prepared, copied, published 482 and distributed, in whole or in part, without restriction of any 483 kind, provided that the above copyright notice and this paragraph are 484 included on all such copies and derivative works. However, this doc- 485 ument itself may not be modified in any way, such as by removing the 486 copyright notice or references to the Internet Society or other 487 Internet organizations, except as needed for the purpose of develop- 488 ing Internet standards in which case the procedures for copyrights 489 defined in the Internet Standards process must be followed, or as 490 required to translate it into languages other than English. 492 The limited permissions granted above are perpetual and will not be 493 revoked by the Internet Society or its successors or assigns. 495 This document and the information contained herein is provided on an 496 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 497 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 498 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 499 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MER- 500 CHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.