idnits 2.17.1 draft-ietf-sieve-include-12.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 (September 24, 2011) is 4598 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 September 24, 2011 5 Expires: March 27, 2012 7 Sieve Email Filtering: Include Extension 8 draft-ietf-sieve-include-12 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 March 27, 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 . . . . . . . . . . . . . . . . . . . . . . . . 15 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 final disposition of the 103 message (e.g. delivered, forwarded, discarded, rejected, etc.). 105 immediate script 106 the individual Sieve script file being executed. 108 including script 109 the individual Sieve script file that had an include statement 110 which included the immediate script. 112 3. Include Extension 114 3.1. General Considerations 116 Sieve implementations that implement the "include", "return", and 117 "global" commands described below have an identifier of "include" for 118 use with the capability mechanism. If any of the "include", 119 "return", or "global" commands are used in a script, the "include" 120 capability MUST be listed in the "require" statement in that script. 122 Sieve implementations need to track the use of actions in included 123 scripts so that implicit "keep" behavior can be properly determined 124 based on whether any actions have executed in any script. 126 Sieve implementations are allowed to limit the total number of nested 127 included scripts, but MUST provide for a total of at least three 128 levels of nested scripts including the top-level script. An error 129 MUST be generated either when the script is uploaded to the Sieve 130 repository, or when the script is executed, if any nesting limit is 131 exceeded. If such an error is detected whilst processing a Sieve 132 script, an implicit "keep" action MUST be executed to prevent loss of 133 any messages. 135 Sieve implementations MUST NOT allow recursive script inclusion. An 136 error MUST be generated when such a script is executed. An error 137 SHOULD be generated when such a script is marked active with 138 MANAGESIEVE [RFC5804] or similar mechanisms. Implementations MUST 139 NOT generate errors for recursive inclusions at upload time, as this 140 would force an upload ordering requirement upon script authors / 141 generators. However, if an active script is replaced with a faulty 142 script and would remain the active script, an error MUST be generated 143 and the upload MUST fail. If an include recursion error is detected 144 during script execution, an implicit "keep" action MUST be executed 145 to prevent loss of any messages. 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 / 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 allow variable 176 expansion in 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 The ":optional" parameter indicates that the script may be missing. 200 Ordinarily, an implementation MUST generate an error at runtime if an 201 include command specifies a script that does not exist. When 202 ":optional" is specified, implementations MUST NOT generate an error 203 for a missing script, and MUST continue as if the include command had 204 not been present. 206 Note: It is RECOMMENDED that script authors / generators use this 207 parameter only when including a script that performs general duties 208 such as declaring global variables and making sanity checks of the 209 environment. 211 The included script MUST be a valid Sieve script. Each script MUST 212 have its own "require" statements for all optional capabilities used 213 by that script. The scope of a "require" statement is the script in 214 which it immediately appears, and neither inherits nor passes on 215 capabilities to other scripts during the course of execution. 217 A "stop" command in an included script MUST stop all script 218 processing, including the processing of the scripts that include the 219 immediate one. The "return" command (described below) stops 220 processing of the immediate script only, and allows the scripts that 221 include it to continue. 223 The "include" command MAY appear anywhere in a script where a control 224 structure is legal, and MAY be used within another control structure, 225 e.g., within an "if" or "foreverypart" block (MIME [RFC5703]). 227 Examples: 229 The user has four scripts stored in their personal repository: 231 "default" 233 This is the default active script that includes several others. 235 require ["include"]; 237 include :personal "always_allow"; 238 include :global "spam_tests"; 239 include :personal "spam_tests"; 240 include :personal "mailing_lists"; 242 Personal script "always_allow" 244 This script special-cases some correspondent email addresses and 245 makes sure any message containing those addresses are always kept. 247 if address :is "from" "boss@example.com" 248 { 249 keep; 250 } 251 elsif address :is "from" "ceo@example.com" 252 { 253 keep; 254 } 256 Personal script "spam_tests" (uses "reject" [RFC5429]) 257 This script does some user-specific spam tests to catch spam 258 messages not caught by the site-wide spam tests. 260 require ["reject"]; 262 if header :contains "Subject" "XXXX" 263 { 264 reject "Subject XXXX is unacceptable."; 265 } 266 elsif address :is "from" "money@example.com" 267 { 268 reject "Mail from this sender is unwelcome."; 269 } 271 Personal script "mailing_lists" 273 This script looks for messages from different mailing lists and 274 files each into a mailbox specific to the mailing list. 276 require ["fileinto"]; 278 if header :is "List-ID" "sieve.ietf.org" 279 { 280 fileinto "lists.sieve"; 281 } 282 elsif header :is "List-ID" "ietf-imapext.imc.org" 283 { 284 fileinto "lists.imapext"; 285 } 287 There is one script stored in the global repository: 289 Site script "spam_tests" (uses "reject" [RFC5429]) 291 This script does some site-wide spam tests which any user at the 292 site can include in their own scripts at a suitable point. The 293 script content is kept up to date by the site administrator. 295 require ["reject"]; 297 if anyof (header :contains "Subject" "$$", 298 header :contains "Subject" "Make money") 299 { 300 reject "No thank you."; 301 } 303 3.3. Control Structure return 305 Usage: return 307 The "return" command stops processing of the immediately included 308 script only and returns processing control to the script which 309 includes it. If used in the main script (i.e., not in an included 310 script), it has the same effect as the "stop" command, including the 311 appropriate "keep" action if no other actions have been executed up 312 to that point. 314 3.4. Interaction with Variables 316 In order to avoid problems of variables in an included script 317 "overwriting" those from the script that includes it, this 318 specification requires that all variables defined in a script MUST be 319 kept "private" to the immediate script by default - that is, they are 320 not "visible" to other scripts. This ensures that two script authors 321 cannot inadvertently cause problems by choosing the same name for a 322 variable. 324 However, sometimes there is a need to make a variable defined in one 325 script available to others. This specification defines the new 326 command "global" to declare that a variable is shared among scripts. 327 Effectively, two namespaces are defined: one local to the immediate 328 script, and another shared among all scripts. Implementations MUST 329 allow a non-global variable to have the same name as a global 330 variable but have no interaction between them. 332 3.4.1. Control Structure global 334 Usage: global 336 The "global" command accepts a string list argument that defines one 337 or more names of variables to be stored in the global variable space. 338 Each name MUST be a constant string and conform to the syntax of 339 variable-name as defined in VARIABLES [RFC5229], Section 3. Match 340 variables cannot be specified and namespace prefixes are not allowed. 341 An invalid name MUST be detected as a syntax error. 343 The "global" command is only available when the script has both 344 "include" and "variables" in its require line. If the "global" 345 command appears when only "include" or only "variables" has been 346 required, an error MUST be generated when the script is uploaded. 348 If a "global" command is given the name of a variable that has 349 previously been defined in the immediate script with "set", an error 350 MUST be generated either when the script is uploaded or at execution 351 time. 353 If a "global" command lists a variable that has not been defined in 354 the global namespace, the name of the variable is now marked as 355 global, and any subsequent "set" command will set the value of the 356 variable in global scope. 358 A variable has global scope in all scripts that have declared it with 359 the "global" command. If a script uses that variable name without 360 declaring it global, the name specifies a separate, non-global 361 variable within that script. 363 Interpretation of a string containing a variable marked as global, 364 but without any value set, SHALL behave as any other access to an 365 unknown variable, as specified in VARIABLES [RFC5229], Section 3 366 (i.e., evaluates to an empty string). 368 Example: 370 The active script 372 The included script may contain repetitive code that is 373 effectively a subroutine that can be factored out. In this 374 script, the test which matches last will leave its value in the 375 test_mailbox variable and the top-level script will file the 376 message into that mailbox. If no tests matched, the message will 377 be implicitly kept in the INBOX. 379 require ["fileinto", "include", "variables", "relational"]; 380 global "test"; 381 global "test_mailbox"; 383 set "test" "$$"; 384 include "spam_checks"; 386 set "test" "Make money"; 387 include "spam_checks"; 389 if string :count "eq" "${test_mailbox}" "1" 390 { 391 fileinto "${test_mailbox}"; 392 stop; 393 } 395 Personal script "spam_checks" 396 This script performs a number of tests against the message, sets 397 the global test_mailbox variable with a folder to file the message 398 into, then falls back to the top-level script. 400 require ["include", "variables"]; global 401 ["test", "test_mailbox"]; 403 if header :contains "Subject" "${test}" 404 { 405 set "test_mailbox" "spam-${test}"; 406 } 408 3.4.2. Variables Namespace global 410 In addition to the "global" command, this document defines the 411 variables namespace "global", as specified in VARIABLES [RFC5229], 412 Section 3. The global namespace has no sub-namespaces (e.g., 'set 413 "global.data.from" "me@example.com";' is not allowed). The variable- 414 name part MUST be a valid identifier (e.g., 'set "global.12" 415 "value";' is not valid because "12" is not a valid identifier). 417 Example: 419 require ["variables", "include"]; 421 set "global.i_am_on_vacation" "1"; 423 Variables declared global and variables accessed via the global 424 namespace MUST be one and the same. In the following example script, 425 we see the variable "i_am_on_vacation" used in a "global" command, 426 and again with the "global." namespace. Consider these as two 427 syntaxes with identical meaning. 429 Example: 431 require ["variables", "include", "vacation"]; 432 global "i_am_on_vacation"; 434 set "global.i_am_on_vacation" "1"; 436 if string :is "${i_am_on_vacation}" "1" 437 { 438 vacation "It's true, I am on vacation."; 439 } 441 4. Security Considerations 443 Sieve implementations MUST ensure adequate security for the global 444 script repository to prevent unauthorized changes to global scripts. 445 For example, a site policy might enable only certain users with 446 administrative privileges to modify the global scripts. Site are 447 advised against allowing all users to have write access to the site's 448 global scripts. 450 Sieve implementations MUST ensure that script names are checked for 451 validity and proper permissions prior to inclusion, in order to 452 prevent a malicious user from gaining access to files accessible to 453 the mail server software that should not be accessible to the user. 455 Beyond these, the "include" extension does not raise any security 456 considerations that are not present in the base SIEVE [RFC5228] 457 document and the VARIABLES [RFC5229] extension. 459 5. IANA Considerations 461 The following template specifies the IANA registration of the Sieve 462 extension specified in this document: 464 5.1. "include" Extension Registration 466 Capability name: include 467 Description: adds the "include" command to execute other Sieve 468 scripts, the "return" action from an included 469 script, and the "global" command and "global" 470 variables namespace to access variables shared 471 among included scripts. 472 RFC number: this RFC 473 Contact address: the Sieve discussion list 475 6. References 477 6.1. Normative References 479 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 480 Requirement Levels", BCP 14, RFC 2119, March 1997. 482 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 483 Language", RFC 5228, January 2008. 485 [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", 486 RFC 5229, January 2008. 488 [RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely 489 Managing Sieve Scripts", RFC 5804, July 2010. 491 6.2. Informative References 493 [RFC5429] Stone, A., "Sieve Email Filtering: Reject and Extended 494 Reject Extensions", RFC 5429, March 2009. 496 [RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part 497 Tests, Iteration, Extraction, Replacement, and Enclosure", 498 RFC 5703, October 2009. 500 Appendix A. Acknowledgments 502 Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz, 503 Kjetil Torgrim Homme, Stephan Bosch, Arnt Gulbrandsen, Barry Leiba, 504 and Jeffrey Hutzelman for comments and corrections. 506 Appendix B. Change History (to be removed prior to publication as an 507 RFC) 509 Changes from ietf-10 to ietf-11: 511 a. Nits from Dilyan Palauzov. 513 b. Nits from Stephan Bosch. 515 c. Nits from Alexey Melnikov. 517 Changes from ietf-09 to ietf-10: 519 a. Another example script error caught by Stephan Bosch. 521 b. Add :optional argument to allow a missing script to be ignored. 523 Changes from ietf-08 to ietf-09: 525 a. Better variables language from Stephan Bosch. 527 Changes from ietf-07 to ietf-08: 529 a. Nits from Stephan Bosch. 531 b. Nits from Barry Leiba. 533 c. Wordsmithing and layout wrangling. 535 Changes from ietf-06 to ietf-07: 537 a. Nits from Stephan Bosch. 539 Changes from ietf-05 to ietf-06: 541 a. Nits from Barry Leiba. 543 Changes from ietf-04 to ietf-05: 545 a. Integrate review from Barry Leiba. 547 Changes from ietf-03 to ietf-04: 549 a. No changes. 551 Changes from ietf-02 to ietf-03: 553 a. Setting a variable then calling global on it is an error 554 (something like 'use strict'). 556 b. Specify that the 'global' keyword is only available when 557 'variables' has also been required. 559 c. Uploading a script that includes a nonexistent script is not an 560 error at upload time. 562 Changes from ietf-01 to ietf-02: 564 a. Require that script names must be constant strings, not subject 565 to variable expansion. 567 b. Try the phrase immediate script instead of current script. 569 c. Clarify that "global 'varname'" and "global.varname" refer to the 570 same variable. 572 d. Drop the requirement the global keywords come after require and 573 before anything else. 575 Changes from ietf-00 to ietf-01: 577 a. Replaced import/export with global. 579 b. Added :once modifier to include. 581 c. Added global namespace to see if it holds water. 583 Changes from daboo-06 to ietf-00: 585 a. None 587 Changes from -05 to -06: 589 a. Aaron Stone joins as author. 591 b. Removed | characters from the script examples. 593 c. Updated draft references to published RFCs. 595 Changes from -04 to -05: 597 a. Fixed examples. 599 b. Relaxed requirement that imported/exported variables be set 600 before being used. 602 Changes from -03 to -04: 604 a. Fixed missing 2119 definitions. 606 b. Defined interaction with variables through use of import and 607 export commands. 609 Changes from -02 to -03: 611 a. Refreshing expired draft (updated for nits). 613 b. Syntax -> Usage. 615 c. Updated to 3028bis reference. 617 Changes from -01 to -02: 619 a. Minor formatting changes only - refreshing expired draft. 621 Changes from -00 to -01: 623 a. Added IPR boiler plate. 625 b. Re-ordered sections at start to conform to RFC style. 627 c. Moved recursion comment into General Considerations section. 629 d. Switched to using optional parameter to indicate personal vs 630 global. 632 e. Explicitly state that an error occurs when a missing script is 633 included. 635 Authors' Addresses 637 Cyrus Daboo 639 Email: cyrus@daboo.name 641 Aaron Stone 643 Email: aaron@serendipity.cx