idnits 2.17.1 draft-ietf-sieve-include-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 31, 2012) is 4440 days in the past. Is this intentional? 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: 'LOCATION' is mentioned on line 165, but not defined Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Daboo 3 Internet-Draft A. Stone 4 Intended status: Standards Track January 31, 2012 5 Expires: August 3, 2012 7 Sieve Email Filtering: Include Extension 8 draft-ietf-sieve-include-15 10 Abstract 12 The Sieve Email Filtering "include" extension permits users to 13 include one Sieve script inside another. This can make managing 14 large scripts or multiple sets of scripts much easier, and allows a 15 site and its users to build up libraries of scripts. Users are able 16 to include their own personal scripts or site-wide scripts. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on August 3, 2012. 35 Copyright Notice 37 Copyright (c) 2012 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 53 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 54 3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 3 55 3.1. General Considerations . . . . . . . . . . . . . . . . . . 3 56 3.2. Control Structure include . . . . . . . . . . . . . . . . 5 57 3.3. Control Structure return . . . . . . . . . . . . . . . . . 8 58 3.4. Interaction with Variables Extension . . . . . . . . . . . 8 59 3.4.1. Control Structure global . . . . . . . . . . . . . . . 8 60 3.4.2. Variables Namespace global . . . . . . . . . . . . . . 10 61 3.5. Interaction with Other Extensions . . . . . . . . . . . . 11 62 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 63 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 64 5.1. "include" Extension Registration . . . . . . . . . . . . . 13 65 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 66 6.1. Normative References . . . . . . . . . . . . . . . . . . . 13 67 6.2. Informative References . . . . . . . . . . . . . . . . . . 13 68 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 14 69 Appendix B. Change History (to be removed prior to 70 publication as an RFC) . . . . . . . . . . . . . . . 14 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 73 1. Introduction and Overview 75 It's convenient to be able to break SIEVE [RFC5228] scripts down into 76 smaller components which can be reused in a variety of different 77 circumstances. For example, users may want to have a default script 78 and a special 'vacation' script, the latter being activated when the 79 user goes on vacation. In that case the default actions should 80 continue to be run, but a vacation command should be executed first. 81 One option is to edit the default script to add or remove the 82 vacation command as needed. Another is to have a vacation script 83 that simply has a vacation command and then includes the default 84 script. 86 2. Conventions Used in This Document 88 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 89 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 90 document are to be interpreted as described in [RFC2119]. 92 Conventions for notations are as in SIEVE [RFC5228] Section 1.1. 94 The following key phrases are used to describe scripts and script 95 execution: 97 script 98 a valid Sieve script. 100 script execution 101 an instance of a Sieve interpreter invoked for a given message 102 delivery, starting with the user's active script and continuing 103 through any included scripts until the final disposition of the 104 message (e.g. delivered, forwarded, discarded, rejected, etc.). 106 immediate script 107 the individual Sieve script file being executed. 109 including script 110 the individual Sieve script file that had an include statement 111 which included the immediate script. 113 3. Include Extension 115 3.1. General Considerations 117 Sieve implementations that implement the "include", "return", and 118 "global" commands described below have an identifier of "include" for 119 use with the capability mechanism. If any of the "include", 120 "return", or "global" commands are used in a script, the "include" 121 capability MUST be listed in the "require" statement in that script. 123 Sieve implementations need to track the use of actions in included 124 scripts so that implicit "keep" behavior can be properly determined 125 based on whether any actions have executed in any script. 127 Sieve implementations are allowed to limit the total number of nested 128 included scripts, but MUST provide for a total of at least three 129 levels of nested scripts including the top-level script. An error 130 MUST be generated either when the script is uploaded to the Sieve 131 repository, or when the script is executed, if any nesting limit is 132 exceeded. If such an error is detected whilst processing a Sieve 133 script, an implicit "keep" action MUST be executed to prevent loss of 134 any messages. 136 Sieve implementations MUST NOT allow recursive script inclusion. 137 Both direct recursion, where script A includes script A (itself), and 138 indirect recursion, where script A includes script B which includes 139 script A once again, are prohibited. 141 Sieve implementations MUST generate an error at execution time if an 142 included script is a recursive inclusion. Implementations MUST NOT 143 generate errors for recursive includes at upload time, as this would 144 force an upload ordering requirement upon script authors and 145 generators. 147 Sieve implementations MUST generate an error at execution time if an 148 included script does not exist, except when the ":optional" parameter 149 is specified. Implementations MUST NOT generate errors for scripts 150 missing at upload time, as this would force an upload ordering 151 requirement upon script authors and generators. 153 If the Sieve "variables" extension [RFC5229] is present, an issue 154 arises with the "scope" of variables defined in scripts that may 155 include each other. For example, if a script defines the variable 156 "${status}" with one particular meaning or usage, and another defines 157 "${status}" with a different meaning, then if one script includes the 158 other there is an issue as to which "${status}" is being referenced. 159 To solve this problem, Sieve implementations MUST follow the scoping 160 rules defined in Section 3.4 and support the "global" command defined 161 there. 163 3.2. Control Structure include 165 Usage: include [LOCATION] [":once"] [":optional"] 167 LOCATION = ":personal" / ":global" 169 The "include" command takes an optional "location" parameter, an 170 optional ":once" parameter, an optional ":optional" parameter, and a 171 single string argument representing the name of the script to include 172 for processing at that point. Implementations MUST restrict script 173 names according to MANAGESIEVE [RFC5804], Section 1.6. The script 174 name argument MUST be a constant string as defined in VARIABLES 175 [RFC5229], Section 3; implementations MUST NOT expand variables in 176 the script name argument. 178 The "location" parameter MUST default to ":personal" if not 179 specified. The "location" parameter MUST NOT be specified more than 180 once. The "location" has the following meanings: 182 :personal 183 Indicates that the named script is stored in the user's own 184 personal (private) Sieve repository. 186 :global 187 Indicates that the named script is stored in a site-wide Sieve 188 repository, accessible to all users of the Sieve system. 190 The ":once" parameter tells the interpreter only to include the named 191 script if it has not already been included at any other point during 192 script execution. If the script has already been included, 193 processing continues immediately following the include command. 194 Implementations MUST NOT generate an error if an "include :once" 195 command names a script whose inclusion would be recursive; in this 196 case, the script MUST be considered previously included and therefore 197 "include :once" will not include it again. 199 Note: It is RECOMMENDED that script authors and generators use the 200 ":once" parameter only when including a script that performs general 201 duties such as declaring global variables and making sanity checks of 202 the environment. 204 The ":optional" parameter indicates that the script may be missing. 205 Ordinarily, an implementation MUST generate an error during execution 206 if an include command specifies a script that does not exist. When 207 ":optional" is specified, implementations MUST NOT generate an error 208 for a missing script, and MUST continue as if the include command had 209 not been present. 211 The included script MUST be a valid Sieve script. Implementations 212 MUST validate that each script has its own "require" statements for 213 all optional capabilities used by that script. The scope of a 214 "require" statement is the script in which it immediately appears, 215 and neither inherits nor passes on capabilities to other scripts 216 during the course of execution. 218 A "stop" command in an included script MUST stop all script 219 processing, including the processing of the scripts that include the 220 immediate one. The "return" command (described below) stops 221 processing of the immediate script only, and allows the scripts that 222 include it to continue. 224 The "include" command MAY appear anywhere in a script where a control 225 structure is legal, and MAY be used within another control structure, 226 e.g., an "if" block. 228 Examples: 230 The user has four scripts stored in their personal repository: 232 "default" 234 This is the default active script that includes several others. 236 require ["include"]; 238 include :personal "always_allow"; 239 include :global "spam_tests"; 240 include :personal "spam_tests"; 241 include :personal "mailing_lists"; 243 Personal script "always_allow" 245 This script special-cases some correspondent email addresses and 246 makes sure any message containing those addresses are always kept. 248 if address :is "from" "boss@example.com" 249 { 250 keep; 251 } 252 elsif address :is "from" "ceo@example.com" 253 { 254 keep; 255 } 257 Personal script "spam_tests" (uses "reject" [RFC5429]) 259 This script does some user-specific spam tests to catch spam 260 messages not caught by the site-wide spam tests. 262 require ["reject"]; 264 if header :contains "Subject" "XXXX" 265 { 266 reject "Subject XXXX is unacceptable."; 267 } 268 elsif address :is "from" "money@example.com" 269 { 270 reject "Mail from this sender is unwelcome."; 271 } 273 Personal script "mailing_lists" 275 This script looks for messages from different mailing lists and 276 files each into a mailbox specific to the mailing list. 278 require ["fileinto"]; 280 if header :is "List-ID" "sieve.ietf.org" 281 { 282 fileinto "lists.sieve"; 283 } 284 elsif header :is "List-ID" "ietf-imapext.imc.org" 285 { 286 fileinto "lists.imapext"; 287 } 289 There is one script stored in the global repository: 291 Site script "spam_tests" (uses "reject" [RFC5429]) 293 This script does some site-wide spam tests which any user at the 294 site can include in their own scripts at a suitable point. The 295 script content is kept up to date by the site administrator. 297 require ["reject"]; 299 if anyof (header :contains "Subject" "$$", 300 header :contains "Subject" "Make money") 301 { 302 reject "No thank you."; 303 } 305 3.3. Control Structure return 307 Usage: return 309 The "return" command stops processing of the immediately included 310 script only and returns processing control to the script which 311 includes it. If used in the main script (i.e., not in an included 312 script), it has the same effect as the "stop" command, including the 313 appropriate "keep" action if no other actions have been executed up 314 to that point. 316 3.4. Interaction with Variables Extension 318 In order to avoid problems of variables in an included script 319 "overwriting" those from the script that includes it, this 320 specification requires that all variables defined in a script MUST be 321 kept "private" to the immediate script by default - that is, they are 322 not "visible" to other scripts. This ensures that two script authors 323 cannot inadvertently cause problems by choosing the same name for a 324 variable. 326 However, sometimes there is a need to make a variable defined in one 327 script available to others. This specification defines the new 328 command "global" to declare that a variable is shared among scripts. 329 Effectively, two namespaces are defined: one local to the immediate 330 script, and another shared among all scripts. Implementations MUST 331 allow a non-global variable to have the same name as a global 332 variable but have no interaction between them. 334 3.4.1. Control Structure global 336 Usage: global 338 The "global" command accepts a string list argument that defines one 339 or more names of variables to be stored in the global variable space. 340 Each name MUST be a constant string and conform to the syntax of 341 variable-name as defined in VARIABLES [RFC5229], Section 3. Match 342 variables cannot be specified and namespace prefixes are not allowed. 343 An invalid name MUST be detected as a syntax error. 345 The "global" command is only available when the script has both 346 "include" and "variables" in its require line. If the "global" 347 command appears when only "include" or only "variables" has been 348 required, an error MUST be generated when the script is uploaded. 350 If a "global" command is given the name of a variable that has 351 previously been defined in the immediate script with "set", an error 352 MUST be generated either when the script is uploaded or at execution 353 time. 355 If a "global" command lists a variable that has not been defined in 356 the global namespace, the name of the variable is now marked as 357 global, and any subsequent "set" command will set the value of the 358 variable in global scope. 360 A variable has global scope in all scripts that have declared it with 361 the "global" command. If a script uses that variable name without 362 declaring it global, the name specifies a separate, non-global 363 variable within that script. 365 Interpretation of a string containing a variable marked as global, 366 but without any value set, SHALL behave as any other access to an 367 unknown variable, as specified in VARIABLES [RFC5229], Section 3 368 (i.e., evaluates to an empty string). 370 Example: 372 The active script 374 The included script may contain repetitive code that is 375 effectively a subroutine that can be factored out. In this 376 script, the test which matches last will leave its value in the 377 test_mailbox variable and the top-level script will file the 378 message into that mailbox. If no tests matched, the message will 379 be implicitly kept in the INBOX. 381 require ["fileinto", "include", "variables", "relational"]; 382 global "test"; 383 global "test_mailbox"; 385 set "test" "$$"; 386 include "subject_tests"; 388 set "test" "Make money"; 389 include "subject_tests"; 391 if string :count "eq" "${test_mailbox}" "1" 392 { 393 fileinto "${test_mailbox}"; 394 stop; 395 } 397 Personal script "subject_tests" 399 This script performs a number of tests against the message, sets 400 the global test_mailbox variable with a folder to file the message 401 into, then falls back to the top-level script. 403 require ["include", "variables"]; 404 global ["test", "test_mailbox"]; 406 if header :contains "Subject" "${test}" 407 { 408 set "test_mailbox" "spam-${test}"; 409 } 411 3.4.2. Variables Namespace global 413 In addition to the "global" command, this document defines the 414 variables namespace "global", as specified in VARIABLES [RFC5229], 415 Section 3. The global namespace has no sub-namespaces (e.g., 'set 416 "global.data.from" "me@example.com";' is not allowed). The variable- 417 name part MUST be a valid identifier (e.g., 'set "global.12" 418 "value";' is not valid because "12" is not a valid identifier). 420 Note that VARIABLES [RFC5229], Section 3, suggests that extensions 421 should define a namespace that is the same as its capability string 422 (in this case, "include" rather than "global"). Nevertheless, 423 references to the "global" namespace without a prior require 424 statement for the "include" extension MUST cause an error. 426 Example: 428 require ["variables", "include"]; 430 set "global.i_am_on_vacation" "1"; 432 Variables declared global and variables accessed via the global 433 namespace MUST each be one and the same. In the following example 434 script, we see the variable "i_am_on_vacation" used in a "global" 435 command, and again with the "global." namespace. Consider these as 436 two syntaxes with identical meaning. 438 Example: 440 require ["variables", "include", "vacation"]; 441 global "i_am_on_vacation"; 443 set "global.i_am_on_vacation" "1"; 445 if string :is "${i_am_on_vacation}" "1" 446 { 447 vacation "It's true, I am on vacation."; 448 } 450 3.5. Interaction with Other Extensions 452 When "include" is used with the Editheader extension [RFC5293], any 453 changes made to headers in a script MUST be propagated both to and 454 from included scripts. By way of example, if a script deletes one 455 header and add another, then includes a second script, the included 456 script MUST NOT see the removed header, and MUST see the added 457 header. Likewise, if the included script adds or removes a header, 458 upon returning to the including script, subsequent actions MUST see 459 the added headers and MUST NOT see the removed headers. 461 When "include" is used with the MIME extension [RFC5703] 462 "foreverypart" control structure, the included script MUST be 463 presented with the current MIME part as though it were the entire 464 message. A script SHALL NOT have any special control over the 465 control structure it was included from. In the MIME example once 466 again, a "stop" or "return" in an included script cannot directly 467 terminate or continue flow of a "foreverypart" block. In such a 468 case, the included script should set a global variable that the 469 including script can test. A "stop" in an included script, even 470 within a "foreverpart" loop, still halts all script execution, per 471 Section 3.2. 473 When "include" is used with the Reject extension [RFC5429], calling 474 "reject" or "ereject" at any time sets the reject action on the 475 message, and continues script execution. Apropos of the MIME 476 extension, if an included script sees only a portion of the message 477 and calls a reject, it is the entire message and not the single MIME 478 part which carries the rejection. 480 4. Security Considerations 482 Sieve implementations MUST ensure adequate security for the global 483 script repository to prevent unauthorized changes to global scripts. 484 For example, a site policy might enable only certain users with 485 administrative privileges to modify the global scripts. Site are 486 advised against allowing all users to have write access to the site's 487 global scripts. 489 Sieve implementations MUST ensure that script names are checked for 490 validity and proper permissions prior to inclusion, in order to 491 prevent a malicious user from gaining access to files accessible to 492 the mail server software that should not be accessible to the user. 494 Sieve implementations MUST ensure that script names are safe for use 495 with their storage system. An error MUST be generated either when 496 the script is uploaded or at execution time for a script including a 497 name that could be used as a vector to attack the storage system. By 498 way of example, the following include commands should be considered 499 hostile: 'include "./../..//etc/passwd"', 'include "foo$(`rm 500 star`)"'. 502 Beyond these, the "include" extension does not raise any security 503 considerations that are not present in the base SIEVE [RFC5228] 504 document and the VARIABLES [RFC5229] extension. 506 5. IANA Considerations 508 The following template specifies the IANA registration of the Sieve 509 extension specified in this document: 511 5.1. "include" Extension Registration 513 To: iana@iana.org 514 Subject: Registration of new Sieve extension 516 Capability name: include 517 Description: adds the "include" command to execute other Sieve 518 scripts, the "return" action from an included 519 script, and the "global" command and "global" 520 variables namespace to access variables shared 521 among included scripts. 522 RFC number: this RFC 523 Contact address: the Sieve discussion list 525 This information has been added to the IANA registry of Sieve 526 Extensions (currently found at http://www.iana.org). 528 6. References 530 6.1. Normative References 532 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 533 Requirement Levels", BCP 14, RFC 2119, March 1997. 535 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 536 Language", RFC 5228, January 2008. 538 [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", 539 RFC 5229, January 2008. 541 [RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely 542 Managing Sieve Scripts", RFC 5804, July 2010. 544 6.2. Informative References 546 [RFC5293] Degener, J. and P. Guenther, "Sieve Email Filtering: 547 Editheader Extension", RFC 5293, August 2008. 549 [RFC5429] Stone, A., "Sieve Email Filtering: Reject and Extended 550 Reject Extensions", RFC 5429, March 2009. 552 [RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part 553 Tests, Iteration, Extraction, Replacement, and Enclosure", 554 RFC 5703, October 2009. 556 Appendix A. Acknowledgments 558 Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz, 559 Kjetil Torgrim Homme, Stephan Bosch, Arnt Gulbrandsen, Barry Leiba, 560 and Jeffrey Hutzelman for comments and corrections. 562 Appendix B. Change History (to be removed prior to publication as an 563 RFC) 565 Changes from ietf-14 to ietf-15: 567 a. Interaction with reject, stop. 569 Changes from ietf-13 to ietf-14: 571 a. Updated for Last Call comments. 573 Changes from ietf-12 to ietf-13: 575 a. Nits from Stephan Bosch. 577 b. Nits from Robert Burrell Donkin. 579 Changes from ietf-11 to ietf-12: 581 a. Nits from Alexey Melnikov. 583 b. Nits from Barry Leiba. 585 Changes from ietf-10 to ietf-11: 587 a. Nits from Dilyan Palauzov. 589 b. Nits from Stephan Bosch. 591 c. Nits from Alexey Melnikov. 593 Changes from ietf-09 to ietf-10: 595 a. Another example script error caught by Stephan Bosch. 597 b. Add :optional argument to allow a missing script to be ignored. 599 Changes from ietf-08 to ietf-09: 601 a. Better variables language from Stephan Bosch. 603 Changes from ietf-07 to ietf-08: 605 a. Nits from Stephan Bosch. 607 b. Nits from Barry Leiba. 609 c. Wordsmithing and layout wrangling. 611 Changes from ietf-06 to ietf-07: 613 a. Nits from Stephan Bosch. 615 Changes from ietf-05 to ietf-06: 617 a. Nits from Barry Leiba. 619 Changes from ietf-04 to ietf-05: 621 a. Integrate review from Barry Leiba. 623 Changes from ietf-03 to ietf-04: 625 a. No changes. 627 Changes from ietf-02 to ietf-03: 629 a. Setting a variable then calling global on it is an error 630 (something like 'use strict'). 632 b. Specify that the 'global' keyword is only available when 633 'variables' has also been required. 635 c. Uploading a script that includes a nonexistent script is not an 636 error at upload time. 638 Changes from ietf-01 to ietf-02: 640 a. Require that script names must be constant strings, not subject 641 to variable expansion. 643 b. Try the phrase immediate script instead of current script. 645 c. Clarify that "global 'varname'" and "global.varname" refer to the 646 same variable. 648 d. Drop the requirement the global keywords come after require and 649 before anything else. 651 Changes from ietf-00 to ietf-01: 653 a. Replaced import/export with global. 655 b. Added :once modifier to include. 657 c. Added global namespace to see if it holds water. 659 Changes from daboo-06 to ietf-00: 661 a. None 663 Changes from -05 to -06: 665 a. Aaron Stone joins as author. 667 b. Removed | characters from the script examples. 669 c. Updated draft references to published RFCs. 671 Changes from -04 to -05: 673 a. Fixed examples. 675 b. Relaxed requirement that imported/exported variables be set 676 before being used. 678 Changes from -03 to -04: 680 a. Fixed missing 2119 definitions. 682 b. Defined interaction with variables through use of import and 683 export commands. 685 Changes from -02 to -03: 687 a. Refreshing expired draft (updated for nits). 689 b. Syntax -> Usage. 691 c. Updated to 3028bis reference. 693 Changes from -01 to -02: 695 a. Minor formatting changes only - refreshing expired draft. 697 Changes from -00 to -01: 699 a. Added IPR boiler plate. 701 b. Re-ordered sections at start to conform to RFC style. 703 c. Moved recursion comment into General Considerations section. 705 d. Switched to using optional parameter to indicate personal vs 706 global. 708 e. Explicitly state that an error occurs when a missing script is 709 included. 711 Authors' Addresses 713 Cyrus Daboo 715 Email: cyrus@daboo.name 717 Aaron Stone 719 Email: aaron@serendipity.cx