idnits 2.17.1 draft-ietf-sieve-include-09.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 4666 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 483, 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-09 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 . . . . . . . . . . . . . . . . . . . 11 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 . . . . . . . . . . . . . . . . . . 12 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 accepts a string list argument that defines one 330 or more names of variables to be stored in the global variable space. 331 Each name MUST be a constant string and conform to the syntax of 332 variable-name as defined in VARIABLES [RFC5229], Section 3. Match 333 variables cannot be specified and namespace prefixes are not allowed. 334 An invalid name MUST be detected as a syntax error. 336 The "global" command is only available when the script has both 337 "include" and "variables" in its require line. If the "global" 338 command appears when only "include" or only "variables" has been 339 required, an error MUST be generated when the script is uploaded. 341 If a "global" command is given the name of a variable that has 342 previously been defined in the immediate script with "set", an error 343 MUST be generated either when the script is uploaded or at execution 344 time. 346 If a "global" command lists a variable that has not been defined in 347 the global namespace, the name of the variable is now marked as 348 global, and any subsequent "set" command will set the value of the 349 variable in global scope. 351 A variable has global scope in all scripts that have declared it with 352 the "global" command. If a script uses that variable name without 353 declaring it global, the name specifies a separate, non-global 354 variable within that script. 356 Interpretation of a string containing a variable marked as global, 357 but without any value set, SHALL behave as any other access to an 358 unknown variable, as specified in VARIABLES [RFC5229], Section 3 359 (i.e., evaluates to an empty string). 361 Example: 363 The active script 365 The included script may contain repetitive code that is 366 effectively a subroutine that can be factored out. In this 367 script, the test which matches last will leave its value in the 368 test_mailbox variable and the top-level script will file the 369 message into that mailbox. If no tests matched, the message will 370 be implicitly kept in the INBOX. 372 require ["fileinto", "include", "variables", "relational"]; 373 global "test"; 374 global "test_mailbox"; 376 set "test" "$$"; 377 include "spam_checks"; 379 set "test" "Make money"; 380 include "spam_checks"; 382 if string :count "eq" "${test_mailbox}" "1" 383 { 384 fileinto "${test_mailbox}"; 385 stop; 386 } 388 Personal script "spam_checks" 389 This script is makes a number of tests against the message, 390 falling through back to the top-level script having set the global 391 test_mailbox variable with a target folder to file the message 392 into. 394 require ["include", "variables"]; 395 global ["test", "test_mailbox"]; 397 if header :contains "Subject" "${test}" 398 { 399 set "test_mailbox" "spam-${test}"; 400 } 402 3.4.2. Variables Namespace global 404 In addition to the "global" command, this document defines the 405 variables namespace "global", as specified in VARIABLES [RFC5229], 406 Section 3. The global namespace has no sub-namespaces (e.g., 'set 407 "global.data.from" "me@example.com";' is not allowed). The variable- 408 name part MUST be a valid identifier (e.g., 'set "global.12" 409 "value";' is not valid because "12" is not a valid identifier). 411 Example: 413 require ["variables", "include"]; 415 set "global.i_am_on_vacation" "1"; 417 Variables declared global and variables accessed via the global 418 namespace MUST be one and the same. In the following example script, 419 we see the variable "i_am_on_vacation" used in a "global" command, 420 and again with the "global." namespace. Consider these as two 421 syntaxes with identical meaning. 423 Example: 425 require ["variables", "include"]; 426 global "i_am_on_vacation"; 428 set "global.i_am_on_vacation" "1"; 430 if string :is "${i_am_on_vacation}" "1" 431 { 432 vacation "It's true, I am on vacation."; 433 } 435 4. Security Considerations 437 Sieve implementations MUST ensure adequate security for the global 438 script repository to prevent unauthorized changes to global scripts. 439 For example, a site policy might enable only certain users with 440 administrative privileges to modify the global scripts. Site are 441 advised against allowing all users to have write access to the site's 442 global scripts. 444 Sieve implementations MUST ensure that script names are checked for 445 validity and proper permissions prior to inclusion, in order to 446 prevent a malicious user from gaining acess to files accessible to 447 the mail server software that should not be accessible to the user. 449 Beyond these, the "include" extension does not raise any security 450 considerations that are not present in the base SIEVE [RFC5228] 451 document and the VARIABLES [RFC5229] extension. 453 5. IANA Considerations 455 The following template specifies the IANA registration of the Sieve 456 extension specified in this document: 458 5.1. "include" Extension Registration 460 Capability name: include 461 Description: adds the "include" command to execute other Sieve 462 scripts, and the "global" command and "global" 463 variables namespace to access variables shared 464 among included scripts. 465 RFC number: this RFC 466 Contact address: the Sieve discussion list 468 6. References 470 6.1. Normative References 472 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 473 Requirement Levels", BCP 14, RFC 2119, March 1997. 475 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 476 Language", RFC 5228, January 2008. 478 [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", 479 RFC 5229, January 2008. 481 6.2. Informative References 483 [RFC5429] Stone, A., "Sieve Email Filtering: Reject and Extended 484 Reject Extensions", RFC 5429, March 2009. 486 [RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part 487 Tests, Iteration, Extraction, Replacement, and Enclosure", 488 RFC 5703, October 2009. 490 [RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely 491 Managing Sieve Scripts", RFC 5804, July 2010. 493 Appendix A. Acknowledgments 495 Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz, 496 Kjetil Torgrim Homme, Stephan Bosch, Arnt Gulbrandsen, Barry Leiba, 497 and Jeffrey Hutzelman for comments and corrections. 499 Appendix B. Change History (to be removed prior to publication as an 500 RFC) 502 Changes from ietf-08 to ietf-09: 504 a. Better variables language from Stephan Bosch. 506 Changes from ietf-07 to ietf-08: 508 a. Nits from Stephan Bosch. 510 b. Nits from Barry Leiba. 512 c. Wordsmithing and layout wrangling. 514 Changes from ietf-06 to ietf-07: 516 a. Nits from Stephan Bosch. 518 Changes from ietf-05 to ietf-06: 520 a. Nits from Barry Leiba. 522 Changes from ietf-04 to ietf-05: 524 a. Integrate review from Barry Leiba. 526 Changes from ietf-03 to ietf-04: 528 a. No changes. 530 Changes from ietf-02 to ietf-03: 532 a. Setting a variable then calling global on it is an error 533 (something like 'use strict'). 535 b. Specify that the 'global' keyword is only available when 536 'variables' has also been required. 538 c. Uploading a script that includes a nonexistent script is not an 539 error at upload time. 541 Changes from ietf-01 to ietf-02: 543 a. Require that script names must be constant strings, not subject 544 to variable expansion. 546 b. Try the phrase immediate script instead of current script. 548 c. Clarify that "global 'varname'" and "global.varname" refer to the 549 same variable. 551 d. Drop the requirement the global keywords come after require and 552 before anything else. 554 Changes from ietf-00 to ietf-01: 556 a. Replaced import/export with global. 558 b. Added :once modifier to include. 560 c. Added global namespace to see if it holds water. 562 Changes from daboo-06 to ietf-00: 564 a. None 566 Changes from -05 to -06: 568 a. Aaron Stone joins as author. 570 b. Removed | characters from the script examples. 572 c. Updated draft references to published RFCs. 574 Changes from -04 to -05: 576 a. Fixed examples. 578 b. Relaxed requirement that imported/exported variables be set 579 before being used. 581 Changes from -03 to -04: 583 a. Fixed missing 2119 definitions. 585 b. Defined interaction with variables through use of import and 586 export commands. 588 Changes from -02 to -03: 590 a. Refreshing expired draft (updated for nits). 592 b. Syntax -> Usage. 594 c. Updated to 3028bis reference. 596 Changes from -01 to -02: 598 a. Minor formatting changes only - refreshing expired draft. 600 Changes from -00 to -01: 602 a. Added IPR boiler plate. 604 b. Re-ordered sections at start to conform to RFC style. 606 c. Moved recursion comment into General Considerations section. 608 d. Switched to using optional parameter to indicate personal vs 609 global. 611 e. Explicitly state that an error occurs when a missing script is 612 included. 614 Authors' Addresses 616 Cyrus Daboo 618 Email: cyrus@daboo.name 619 Aaron Stone 621 Email: aaron@serendipity.cx