idnits 2.17.1 draft-ietf-sieve-include-08.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 (July 8, 2011) is 4674 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 163, but not defined == Missing Reference: 'ONCE' is mentioned on line 163, but not defined == Unused Reference: 'RFC5429' is defined on line 477, but no explicit reference was found in the text Summary: 0 errors (**), 0 flaws (~~), 4 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 July 8, 2011 5 Expires: January 9, 2012 7 Sieve Email Filtering: Include Extension 8 draft-ietf-sieve-include-08 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 January 9, 2012. 35 Copyright Notice 37 Copyright (c) 2011 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 . . . . . . . . . . . . . . . . 8 59 3.4.1. Control Structure global . . . . . . . . . . . . . . . 8 60 3.4.2. Variables Namespace global . . . . . . . . . . . . . . 10 61 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 62 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 63 5.1. "include" Extension Registration . . . . . . . . . . . . . 11 64 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 65 6.1. Normative References . . . . . . . . . . . . . . . . . . . 11 66 6.2. Informative References . . . . . . . . . . . . . . . . . . 11 67 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 12 68 Appendix B. Change History (to be removed prior to 69 publication as an RFC) . . . . . . . . . . . . . . . 12 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14 72 1. Introduction and Overview 74 It's convenient to be able to break SIEVE [RFC5228] scripts down into 75 smaller components which can be reused in a variety of different 76 circumstances. For example, users may want to have a default script 77 and a special 'vacation' script, the latter being activated when the 78 user goes on vacation. In that case the default actions should 79 continue to be run, but a vacation command should be executed first. 80 One option is to edit the default script to add or remove the 81 vacation command as needed. Another is to have a vacation script 82 that simply has a vacation command and then includes the default 83 script. 85 2. Conventions Used in This Document 87 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 89 document are to be interpreted as described in [RFC2119]. 91 Conventions for notations are as in SIEVE [RFC5228] Section 1.1. 93 The following key phrases are used to describe scripts and script 94 execution: 96 script 97 a valid Sieve script. 99 script execution 100 an instance of a Sieve interpreter invoked for a given message 101 delivery, starting with the user's active script and continuing 102 through any included scripts until the message is delivered. 104 immediate script 105 the individual Sieve script file being executed. 107 including script 108 the individual Sieve script file that had an include statement 109 which included the immediate script. 111 3. Include Extension 113 3.1. General Considerations 115 Sieve implementations that implement the "include", "return", and 116 "global" commands described below have an identifier of "include" for 117 use with the capability mechanism. If any of the "include", 118 "return", or "global" commands are used in a script, the "include" 119 capability MUST be listed in the "require" statement in that script. 121 Sieve implementations need to track the use of actions in included 122 scripts so that implicit "keep" behavior can be properly determined 123 based on whether any actions have executed in any script. 125 Sieve implementations are allowed to limit the total number of nested 126 included scripts, but MUST provide for a total of at least three 127 levels of nested scripts including the top-level script. An error 128 MUST be generated either when the script is uploaded to the Sieve 129 repository, or when the script is executed, if any nesting limit is 130 exceeded. If such an error is detected whilst processing a Sieve 131 script, an implicit "keep" action MUST be executed to prevent loss of 132 any messages. 134 Sieve implementations MUST NOT allow recursive script inclusion. An 135 error MUST be generated when such a script is executed. An error 136 SHOULD be generated when such a script is marked active with 137 MANAGESIEVE [RFC5804] or similar mechanisms. Implementations MUST 138 NOT generate errors for recursive inclusions at upload time, as this 139 would force an upload ordering requirement upon script authors / 140 generators. However, if an active script is replaced with a faulty 141 script and would remain the active script, an error MUST be generated 142 and the upload MUST fail. If an include recursion error is detected 143 during script execution, an implicit "keep" action MUST be executed 144 to prevent loss of any messages. 146 Sieve implementations MUST generate an error at execution time if an 147 included script does not exist. Implementations MUST NOT generate 148 errors for scripts missing at upload time, as this would force an 149 upload ordering requirement upon script authors / generators. 151 If the Sieve "variables" extension [RFC5229] is present, an issue 152 arises with the "scope" of variables defined in scripts that may 153 include each other. For example, if a script defines the variable 154 "${status}" with one particular meaning or usage, and another defines 155 "${status}" with a different meaning, then if one script includes the 156 other there is an issue as to which "${status}" is being referenced. 157 To solve this problem, Sieve implementations MUST follow the scoping 158 rules defined in Section 3.4 and support the "global" command defined 159 there. 161 3.2. Control Structure include 163 Usage: include [LOCATION] [ONCE] 165 LOCATION = ":personal" / ":global" 167 ONCE = ":once" 169 The "include" command takes an optional "location" parameter, an 170 optional ":once" parameter, and a single string argument representing 171 the name of the script to include for processing at that point. It 172 is RECOMMENDED that implementations restrict script names according 173 to MANAGESIEVE [RFC5804] Section 1.7. Implementations MUST NOT allow 174 variables to be expanded into the names of Sieve scripts; in other 175 words, the value MUST be a constant string as defined in VARIABLES 176 [RFC5229], Section 3. 178 The "location" parameter MUST default to ":personal" if not 179 specified. The "location" has the following meanings: 181 :personal 182 Indicates that the named script is stored in the user's own 183 personal (private) Sieve repository. 185 :global 186 Indicates that the named script is stored in a site-wide Sieve 187 repository, accessible to all users of the Sieve system. 189 The ":once" parameter tells the interpreter only to include the named 190 script if it has not already been included at any other point during 191 script execution. If the script has already been included, 192 processing continues immediately following the include command. 193 Implementations MUST NOT generate an error if an "include :once" 194 command names a script whose inclusion would be recursive; in this 195 case, the script MUST be considered previously included and therefore 196 "include :once" will not include it again. 198 Note: It is RECOMMENDED that script authors / generators use this 199 parameter only when including a script that performs general duties 200 such as declaring global variables and making sanity checks of the 201 environment. 203 The included script MUST be a valid Sieve script. Each script MUST 204 have its own "require" statements for all optional capabilities used 205 by that script. The scope of a "require" statement is the script in 206 which it immediately appears, and neither inherits nor passes on 207 capabilities to other scripts during the course of execution. 209 A "stop" command in an included script MUST stop all script 210 processing, including the processing of the scripts that include the 211 immediate one. The "return" command (described below) stops 212 processing of the immediate script only, and allows the scripts that 213 include it to continue. 215 The "include" command MAY appear anywhere in a script where a control 216 structure is legal, and MAY be used within another control structure, 217 e.g., within an "if" or "foreverypart" block (MIME [RFC5703]). 219 Examples: 221 The user has four scripts stored in their personal repository: 223 "default" 225 This is the default active script that includes several others. 227 require ["include"]; 229 include :personal "always_allow"; 230 include :global "spam_tests"; 231 include :personal "spam_tests"; 232 include :personal "mailing_lists"; 234 Personal script "always_allow" 236 This script special-cases some correspondent email addresses and 237 makes sure any message containing those addresses are always kept. 239 if address :is "from" "boss@example.com" 240 { 241 keep; 242 } 243 elsif address :is "from" "ceo@example.com" 244 { 245 keep; 246 } 248 Personal script "spam_tests" 250 This script does some user-specific spam tests to catch spam 251 messages not caught by the site-wide spam tests. 253 require ["reject"]; 255 if header :contains "Subject" "XXXX" 256 { 257 reject "Subject XXXX is unacceptable."; 258 } 259 elsif address :is "from" "money@example.com" 260 { 261 reject "Mail from this sender is unwelcome."; 262 } 264 Personal script "mailing_lists" 266 This script looks for messages from different mailing lists and 267 files each into a mailbox specific to the mailing list. 269 require ["fileinto"]; 271 if header :is "List-ID" "sieve.ietf.org" 272 { 273 fileinto "lists.sieve"; 274 } 275 elsif header :is "List-ID" "ietf-imapext.imc.org" 276 { 277 fileinto "lists.imapext"; 278 } 280 There is one script stored in the global repository: 282 Site script "spam_tests" 284 This script does some site-wide spam tests which any user at the 285 site can include in their own scripts at a suitable point. The 286 script content is kept up to date by the site administrator. 288 require ["reject"]; 290 if anyof (header :contains "Subject" "$$", 291 header :contains "Subject" "Make money") 292 { 293 reject "No thank you."; 294 } 296 3.3. Control Structure return 298 Usage: return 300 The "return" command stops processing of the immediately included 301 script only and returns processing control to the script which 302 includes it. If used in the main script (i.e., not in an included 303 script), it has the same effect as the "stop" command, including the 304 appropriate "keep" action if no other actions have been executed up 305 to that point. 307 3.4. Interaction with Variables 309 In order to avoid problems of variables in an included script 310 "overwriting" those from the script that includes it, this 311 specification requires that all variables defined in a script MUST be 312 kept "private" to the immediate script by default - that is, they are 313 not "visible" to other scripts. This ensures that two script authors 314 cannot inadvertently cause problems by choosing the same name for a 315 variable. 317 However, sometimes there is a need to make a variable defined in one 318 script available to others. This specification defines the new 319 command "global" to declare that a variable is shared among scripts. 320 Effectively, two namespaces are defined: one local to the immediate 321 script, and another shared among all scripts. Implementations MUST 322 allow a non-global variable to have the same name as a global 323 variable but have no interaction between them. 325 3.4.1. Control Structure global 327 Usage: global 329 The "global" command contains a string list argument that defines one 330 or more names of variables to be stored in the global variable space. 332 The "global" command is only available when the script has both 333 "include" and "variables" in its require line. If the "global" 334 command appears when only "include" or only "variables" has been 335 required, an error MUST be generated when the script is uploaded. 337 If a "global" command is given the name of a variable that has 338 previously been defined in the immediate script with "set", an error 339 MUST be generated either when the script is uploaded or at execution 340 time. 342 If a "global" command lists a variable that has not been defined in 343 the global namespace, the name of the variable is now marked as 344 global, and any subsequent "set" command will set the value of the 345 variable in global scope. 347 A variable has global scope in all scripts that have declared it with 348 the "global" command. If a script uses that variable name without 349 declaring it global, the name specifies a separate, non-global 350 variable within that script. 352 Interpretation of a string containing a variable marked as global, 353 but without any value set, SHALL behave as any other access to an 354 unknown variable, as specified in VARIABLES [RFC5229], Section 3 355 (i.e., evaluates to an empty string). 357 Example: 359 The active script 361 The included script may contain repetitive code that is 362 effectively a subroutine that can be factored out. In this 363 script, the test which matches last will leave its value in the 364 test_mailbox variable and the top-level script will file the 365 message into that mailbox. If no tests matched, the message will 366 be implicitly kept in the INBOX. 368 require ["fileinto", "include", "variables", "relational"]; 369 global "test"; 370 global "test_mailbox"; 372 set "test" "$$"; 373 include "spam_checks"; 375 set "test" "Make money"; 376 include "spam_checks"; 378 if string :count "eq" "${test_mailbox}" "1" 379 { 380 fileinto "${test_mailbox}"; 381 stop; 382 } 384 Personal script "spam_checks" 386 This script is makes a number of tests against the message, 387 falling through back to the top-level script having set the global 388 test_mailbox variable with a target folder to file the message 389 into. 391 require ["include", "variables"]; 392 global ["test", "test_mailbox"]; 394 if header :contains "Subject" "${test}" 395 { 396 set "test_mailbox" "spam-${test}"; 397 } 399 3.4.2. Variables Namespace global 401 In addition to the "global" command, this document defines the 402 variables namespace "global", as specified in VARIABLES [RFC5229], 403 Section 3. 405 Example: 407 require ["variables", "include"]; 409 set "global.i_am_on_vacation" "1"; 411 Variables declared global and variables accessed via the global 412 namespace MUST be one and the same. In the following example script, 413 we see the variable "i_am_on_vacation" used in a "global" command, 414 and again with the "global." namespace. Consider these as two 415 syntaxes with identical meaning. 417 Example: 419 require ["variables", "include"]; 420 global "i_am_on_vacation"; 422 set "global.i_am_on_vacation" "1"; 424 if string :is "${i_am_on_vacation}" "1" 425 { 426 vacation "It's true, I am on vacation."; 427 } 429 4. Security Considerations 431 Sieve implementations MUST ensure adequate security for the global 432 script repository to prevent unauthorized changes to global scripts. 433 For example, a site policy might enable only certain users with 434 administrative privileges to modify the global scripts. Site are 435 advised against allowing all users to have write access to the site's 436 global scripts. 438 Sieve implementations MUST ensure that script names are checked for 439 validity and proper permissions prior to inclusion, in order to 440 prevent a malicious user from gaining acess to files accessible to 441 the mail server software that should not be accessible to the user. 443 Beyond these, the "include" extension does not raise any security 444 considerations that are not present in the base SIEVE [RFC5228] 445 document and the VARIABLES [RFC5229] extension. 447 5. IANA Considerations 449 The following template specifies the IANA registration of the Sieve 450 extension specified in this document: 452 5.1. "include" Extension Registration 454 Capability name: include 455 Description: adds the "include" command to execute other Sieve 456 scripts, and the "global" command and "global" 457 variables namespace to access variables shared 458 among included scripts. 459 RFC number: this RFC 460 Contact address: the Sieve discussion list 462 6. References 464 6.1. Normative References 466 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 467 Requirement Levels", BCP 14, RFC 2119, March 1997. 469 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 470 Language", RFC 5228, January 2008. 472 [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", 473 RFC 5229, January 2008. 475 6.2. Informative References 477 [RFC5429] Stone, A., "Sieve Email Filtering: Reject and Extended 478 Reject Extensions", RFC 5429, March 2009. 480 [RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part 481 Tests, Iteration, Extraction, Replacement, and Enclosure", 482 RFC 5703, October 2009. 484 [RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely 485 Managing Sieve Scripts", RFC 5804, July 2010. 487 Appendix A. Acknowledgments 489 Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz, 490 Kjetil Torgrim Homme, Stephan Bosch, Arnt Gulbrandsen, Barry Leiba, 491 and Jeffrey Hutzelman for comments and corrections. 493 Appendix B. Change History (to be removed prior to publication as an 494 RFC) 496 Changes from ietf-07 to ietf-08: 498 a. Nits from Stephan Bosch. 500 b. Nits from Barry Leiba. 502 c. Wordsmithing and layout wrangling. 504 Changes from ietf-06 to ietf-07: 506 a. Nits from Stephan Bosch. 508 Changes from ietf-05 to ietf-06: 510 a. Nits from Barry Leiba. 512 Changes from ietf-04 to ietf-05: 514 a. Integrate review from Barry Leiba. 516 Changes from ietf-03 to ietf-04: 518 a. No changes. 520 Changes from ietf-02 to ietf-03: 522 a. Setting a variable then calling global on it is an error 523 (something like 'use strict'). 525 b. Specify that the 'global' keyword is only available when 526 'variables' has also been required. 528 c. Uploading a script that includes a nonexistent script is not an 529 error at upload time. 531 Changes from ietf-01 to ietf-02: 533 a. Require that script names must be constant strings, not subject 534 to variable expansion. 536 b. Try the phrase immediate script instead of current script. 538 c. Clarify that "global 'varname'" and "global.varname" refer to the 539 same variable. 541 d. Drop the requirement the global keywords come after require and 542 before anything else. 544 Changes from ietf-00 to ietf-01: 546 a. Replaced import/export with global. 548 b. Added :once modifier to include. 550 c. Added global namespace to see if it holds water. 552 Changes from daboo-06 to ietf-00: 554 a. None 556 Changes from -05 to -06: 558 a. Aaron Stone joins as author. 560 b. Removed | characters from the script examples. 562 c. Updated draft references to published RFCs. 564 Changes from -04 to -05: 566 a. Fixed examples. 568 b. Relaxed requirement that imported/exported variables be set 569 before being used. 571 Changes from -03 to -04: 573 a. Fixed missing 2119 definitions. 575 b. Defined interaction with variables through use of import and 576 export commands. 578 Changes from -02 to -03: 580 a. Refreshing expired draft (updated for nits). 582 b. Syntax -> Usage. 584 c. Updated to 3028bis reference. 586 Changes from -01 to -02: 588 a. Minor formatting changes only - refreshing expired draft. 590 Changes from -00 to -01: 592 a. Added IPR boiler plate. 594 b. Re-ordered sections at start to conform to RFC style. 596 c. Moved recursion comment into General Considerations section. 598 d. Switched to using optional parameter to indicate personal vs 599 global. 601 e. Explicitly state that an error occurs when a missing script is 602 included. 604 Authors' Addresses 606 Cyrus Daboo 608 Email: cyrus@daboo.name 610 Aaron Stone 612 Email: aaron@serendipity.cx