idnits 2.17.1 draft-ietf-sieve-include-11.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 : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 5 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 23, 2011) is 4597 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 169, but not defined == Unused Reference: 'RFC5429' is defined on line 499, but no explicit reference was found in the text Summary: 1 error (**), 0 flaws (~~), 3 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 23, 2011 5 Expires: March 26, 2012 7 Sieve Email Filtering: Include Extension 8 draft-ietf-sieve-include-11 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 26, 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 . . . . . . . . . . . . . . . . . . . . . . 4 55 3.1. General Considerations . . . . . . . . . . . . . . . . . . 4 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 . . . . . . . . . . . . . 12 64 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 65 6.1. Normative References . . . . . . . . . . . . . . . . . . . 12 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 message is delivered, 103 rejected, or otherwise processed. an instance of a Sieve 104 interpreter invoked for a given message delivery, starting with 105 the user's active script and continuing through any included 106 scripts until the final disposition of the message (e.g. 107 delivered, forwarded, discarded, rejected, etc.). 109 immediate script 110 the individual Sieve script file being executed. 112 including script 113 the individual Sieve script file that had an include statement 114 which included the immediate script. 116 3. Include Extension 118 3.1. General Considerations 120 Sieve implementations that implement the "include", "return", and 121 "global" commands described below have an identifier of "include" for 122 use with the capability mechanism. If any of the "include", 123 "return", or "global" commands are used in a script, the "include" 124 capability MUST be listed in the "require" statement in that script. 126 Sieve implementations need to track the use of actions in included 127 scripts so that implicit "keep" behavior can be properly determined 128 based on whether any actions have executed in any script. 130 Sieve implementations are allowed to limit the total number of nested 131 included scripts, but MUST provide for a total of at least three 132 levels of nested scripts including the top-level script. An error 133 MUST be generated either when the script is uploaded to the Sieve 134 repository, or when the script is executed, if any nesting limit is 135 exceeded. If such an error is detected whilst processing a Sieve 136 script, an implicit "keep" action MUST be executed to prevent loss of 137 any messages. 139 Sieve implementations MUST NOT allow recursive script inclusion. An 140 error MUST be generated when such a script is executed. An error 141 SHOULD be generated when such a script is marked active with 142 MANAGESIEVE [RFC5804] or similar mechanisms. Implementations MUST 143 NOT generate errors for recursive inclusions at upload time, as this 144 would force an upload ordering requirement upon script authors / 145 generators. However, if an active script is replaced with a faulty 146 script and would remain the active script, an error MUST be generated 147 and the upload MUST fail. If an include recursion error is detected 148 during script execution, an implicit "keep" action MUST be executed 149 to prevent loss of any messages. 151 Sieve implementations MUST generate an error at execution time if an 152 included script does not exist, except when the ":optional" parameter 153 is specified. Implementations MUST NOT generate errors for scripts 154 missing at upload time, as this would force an upload ordering 155 requirement upon script authors / generators. 157 If the Sieve "variables" extension [RFC5229] is present, an issue 158 arises with the "scope" of variables defined in scripts that may 159 include each other. For example, if a script defines the variable 160 "${status}" with one particular meaning or usage, and another defines 161 "${status}" with a different meaning, then if one script includes the 162 other there is an issue as to which "${status}" is being referenced. 163 To solve this problem, Sieve implementations MUST follow the scoping 164 rules defined in Section 3.4 and support the "global" command defined 165 there. 167 3.2. Control Structure include 169 Usage: include [LOCATION] [":once"] [":optional"] 171 LOCATION = ":personal" / ":global" 173 The "include" command takes an optional "location" parameter, an 174 optional ":once" parameter, an optional ":optional" parameter, and a 175 single string argument representing the name of the script to include 176 for processing at that point. Implementations MUST restrict script 177 names according to MANAGESIEVE [RFC5804], Section 1.6. The script 178 name argument MUST be a constant string as defined in VARIABLES 179 [RFC5229], Section 3; implementations MUST NOT allow variable 180 expansion in the script name argument. 182 The "location" parameter MUST default to ":personal" if not 183 specified. The "location" parameter MUST NOT be specified more than 184 once. The "location" has the following meanings: 186 :personal 187 Indicates that the named script is stored in the user's own 188 personal (private) Sieve repository. 190 :global 191 Indicates that the named script is stored in a site-wide Sieve 192 repository, accessible to all users of the Sieve system. 194 The ":once" parameter tells the interpreter only to include the named 195 script if it has not already been included at any other point during 196 script execution. If the script has already been included, 197 processing continues immediately following the include command. 198 Implementations MUST NOT generate an error if an "include :once" 199 command names a script whose inclusion would be recursive; in this 200 case, the script MUST be considered previously included and therefore 201 "include :once" will not include it again. 203 The ":optional" parameter indicates that the script may be missing. 204 Ordinarily, an implementation MUST generate an error at runtime if an 205 include command specifies a script that does not exist. When 206 ":optional" is specified, implementations MUST NOT generate an error 207 for a missing script, and MUST continue as if the include command had 208 not been present. 210 Note: It is RECOMMENDED that script authors / generators use this 211 parameter only when including a script that performs general duties 212 such as declaring global variables and making sanity checks of the 213 environment. 215 The included script MUST be a valid Sieve script. Each script MUST 216 have its own "require" statements for all optional capabilities used 217 by that script. The scope of a "require" statement is the script in 218 which it immediately appears, and neither inherits nor passes on 219 capabilities to other scripts during the course of execution. 221 A "stop" command in an included script MUST stop all script 222 processing, including the processing of the scripts that include the 223 immediate one. The "return" command (described below) stops 224 processing of the immediate script only, and allows the scripts that 225 include it to continue. 227 The "include" command MAY appear anywhere in a script where a control 228 structure is legal, and MAY be used within another control structure, 229 e.g., within an "if" or "foreverypart" block (MIME [RFC5703]). 231 Examples: 233 The user has four scripts stored in their personal repository: 235 "default" 237 This is the default active script that includes several others. 239 require ["include"]; 241 include :personal "always_allow"; 242 include :global "spam_tests"; 243 include :personal "spam_tests"; 244 include :personal "mailing_lists"; 246 Personal script "always_allow" 248 This script special-cases some correspondent email addresses and 249 makes sure any message containing those addresses are always kept. 251 if address :is "from" "boss@example.com" 252 { 253 keep; 254 } 255 elsif address :is "from" "ceo@example.com" 256 { 257 keep; 259 } 261 Personal script "spam_tests" 263 This script does some user-specific spam tests to catch spam 264 messages not caught by the site-wide spam tests. 266 require ["reject"]; 268 if header :contains "Subject" "XXXX" 269 { 270 reject "Subject XXXX is unacceptable."; 271 } 272 elsif address :is "from" "money@example.com" 273 { 274 reject "Mail from this sender is unwelcome."; 275 } 277 Personal script "mailing_lists" 279 This script looks for messages from different mailing lists and 280 files each into a mailbox specific to the mailing list. 282 require ["fileinto"]; 284 if header :is "List-ID" "sieve.ietf.org" 285 { 286 fileinto "lists.sieve"; 287 } 288 elsif header :is "List-ID" "ietf-imapext.imc.org" 289 { 290 fileinto "lists.imapext"; 291 } 293 There is one script stored in the global repository: 295 Site script "spam_tests" 297 This script does some site-wide spam tests which any user at the 298 site can include in their own scripts at a suitable point. The 299 script content is kept up to date by the site administrator. 301 require ["reject"]; 303 if anyof (header :contains "Subject" "$$", 304 header :contains "Subject" "Make money") 305 { 306 reject "No thank you."; 307 } 309 3.3. Control Structure return 311 Usage: return 313 The "return" command stops processing of the immediately included 314 script only and returns processing control to the script which 315 includes it. If used in the main script (i.e., not in an included 316 script), it has the same effect as the "stop" command, including the 317 appropriate "keep" action if no other actions have been executed up 318 to that point. 320 3.4. Interaction with Variables 322 In order to avoid problems of variables in an included script 323 "overwriting" those from the script that includes it, this 324 specification requires that all variables defined in a script MUST be 325 kept "private" to the immediate script by default - that is, they are 326 not "visible" to other scripts. This ensures that two script authors 327 cannot inadvertently cause problems by choosing the same name for a 328 variable. 330 However, sometimes there is a need to make a variable defined in one 331 script available to others. This specification defines the new 332 command "global" to declare that a variable is shared among scripts. 333 Effectively, two namespaces are defined: one local to the immediate 334 script, and another shared among all scripts. Implementations MUST 335 allow a non-global variable to have the same name as a global 336 variable but have no interaction between them. 338 3.4.1. Control Structure global 340 Usage: global 342 The "global" command accepts a string list argument that defines one 343 or more names of variables to be stored in the global variable space. 344 Each name MUST be a constant string and conform to the syntax of 345 variable-name as defined in VARIABLES [RFC5229], Section 3. Match 346 variables cannot be specified and namespace prefixes are not allowed. 347 An invalid name MUST be detected as a syntax error. 349 The "global" command is only available when the script has both 350 "include" and "variables" in its require line. If the "global" 351 command appears when only "include" or only "variables" has been 352 required, an error MUST be generated when the script is uploaded. 354 If a "global" command is given the name of a variable that has 355 previously been defined in the immediate script with "set", an error 356 MUST be generated either when the script is uploaded or at execution 357 time. 359 If a "global" command lists a variable that has not been defined in 360 the global namespace, the name of the variable is now marked as 361 global, and any subsequent "set" command will set the value of the 362 variable in global scope. 364 A variable has global scope in all scripts that have declared it with 365 the "global" command. If a script uses that variable name without 366 declaring it global, the name specifies a separate, non-global 367 variable within that script. 369 Interpretation of a string containing a variable marked as global, 370 but without any value set, SHALL behave as any other access to an 371 unknown variable, as specified in VARIABLES [RFC5229], Section 3 372 (i.e., evaluates to an empty string). 374 Example: 376 The active script 378 The included script may contain repetitive code that is 379 effectively a subroutine that can be factored out. In this 380 script, the test which matches last will leave its value in the 381 test_mailbox variable and the top-level script will file the 382 message into that mailbox. If no tests matched, the message will 383 be implicitly kept in the INBOX. 385 require ["fileinto", "include", "variables", "relational"]; 386 global "test"; 387 global "test_mailbox"; 389 set "test" "$$"; 390 include "spam_checks"; 392 set "test" "Make money"; 393 include "spam_checks"; 395 if string :count "eq" "${test_mailbox}" "1" 396 { 397 fileinto "${test_mailbox}"; 398 stop; 399 } 401 Personal script "spam_checks" 403 This script performs a number of tests against the message, sets 404 the global test_mailbox variable with a folder to file the message 405 into, then falls back to the top-level script. 407 require ["include", "variables"]; global 408 ["test", "test_mailbox"]; 410 if header :contains "Subject" "${test}" 411 { 412 set "test_mailbox" "spam-${test}"; 413 } 415 3.4.2. Variables Namespace global 417 In addition to the "global" command, this document defines the 418 variables namespace "global", as specified in VARIABLES [RFC5229], 419 Section 3. The global namespace has no sub-namespaces (e.g., 'set 420 "global.data.from" "me@example.com";' is not allowed). The variable- 421 name part MUST be a valid identifier (e.g., 'set "global.12" 422 "value";' is not valid because "12" is not a valid identifier). 424 Example: 426 require ["variables", "include"]; 428 set "global.i_am_on_vacation" "1"; 430 Variables declared global and variables accessed via the global 431 namespace MUST be one and the same. In the following example script, 432 we see the variable "i_am_on_vacation" used in a "global" command, 433 and again with the "global." namespace. Consider these as two 434 syntaxes with identical meaning. 436 Example: 438 require ["variables", "include", "vacation"]; 439 global "i_am_on_vacation"; 441 set "global.i_am_on_vacation" "1"; 443 if string :is "${i_am_on_vacation}" "1" 444 { 445 vacation "It's true, I am on vacation."; 446 } 448 4. Security Considerations 450 Sieve implementations MUST ensure adequate security for the global 451 script repository to prevent unauthorized changes to global scripts. 452 For example, a site policy might enable only certain users with 453 administrative privileges to modify the global scripts. Site are 454 advised against allowing all users to have write access to the site's 455 global scripts. 457 Sieve implementations MUST ensure that script names are checked for 458 validity and proper permissions prior to inclusion, in order to 459 prevent a malicious user from gaining access to files accessible to 460 the mail server software that should not be accessible to the user. 462 Beyond these, the "include" extension does not raise any security 463 considerations that are not present in the base SIEVE [RFC5228] 464 document and the VARIABLES [RFC5229] extension. 466 5. IANA Considerations 468 The following template specifies the IANA registration of the Sieve 469 extension specified in this document: 471 5.1. "include" Extension Registration 473 Capability name: include 474 Description: adds the "include" command to execute other Sieve 475 scripts, the "return" action from an included script, 476 and the "global" command and "global" variables namespace 477 to access variables shared among included scripts. 478 RFC number: this RFC 479 Contact address: the Sieve discussion list 481 6. References 483 6.1. Normative References 485 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 486 Requirement Levels", BCP 14, RFC 2119, March 1997. 488 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 489 Language", RFC 5228, January 2008. 491 [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", 492 RFC 5229, January 2008. 494 [RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely 495 Managing Sieve Scripts", RFC 5804, July 2010. 497 6.2. Informative References 499 [RFC5429] Stone, A., "Sieve Email Filtering: Reject and Extended 500 Reject Extensions", RFC 5429, March 2009. 502 [RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part 503 Tests, Iteration, Extraction, Replacement, and Enclosure", 504 RFC 5703, October 2009. 506 Appendix A. Acknowledgments 508 Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz, 509 Kjetil Torgrim Homme, Stephan Bosch, Arnt Gulbrandsen, Barry Leiba, 510 and Jeffrey Hutzelman for comments and corrections. 512 Appendix B. Change History (to be removed prior to publication as an 513 RFC) 515 Changes from ietf-10 to ietf-11: 517 a. Nits from Dilyan Palauzov. 519 b. Nits from Stephan Bosch. 521 c. Nits from Alexey Melnikov. 523 Changes from ietf-09 to ietf-10: 525 a. Another example script error caught by Stephan Bosch. 527 b. Add :optional argument to allow a missing script to be ignored. 529 Changes from ietf-08 to ietf-09: 531 a. Better variables language from Stephan Bosch. 533 Changes from ietf-07 to ietf-08: 535 a. Nits from Stephan Bosch. 537 b. Nits from Barry Leiba. 539 c. Wordsmithing and layout wrangling. 541 Changes from ietf-06 to ietf-07: 543 a. Nits from Stephan Bosch. 545 Changes from ietf-05 to ietf-06: 547 a. Nits from Barry Leiba. 549 Changes from ietf-04 to ietf-05: 551 a. Integrate review from Barry Leiba. 553 Changes from ietf-03 to ietf-04: 555 a. No changes. 557 Changes from ietf-02 to ietf-03: 559 a. Setting a variable then calling global on it is an error 560 (something like 'use strict'). 562 b. Specify that the 'global' keyword is only available when 563 'variables' has also been required. 565 c. Uploading a script that includes a nonexistent script is not an 566 error at upload time. 568 Changes from ietf-01 to ietf-02: 570 a. Require that script names must be constant strings, not subject 571 to variable expansion. 573 b. Try the phrase immediate script instead of current script. 575 c. Clarify that "global 'varname'" and "global.varname" refer to the 576 same variable. 578 d. Drop the requirement the global keywords come after require and 579 before anything else. 581 Changes from ietf-00 to ietf-01: 583 a. Replaced import/export with global. 585 b. Added :once modifier to include. 587 c. Added global namespace to see if it holds water. 589 Changes from daboo-06 to ietf-00: 591 a. None 593 Changes from -05 to -06: 595 a. Aaron Stone joins as author. 597 b. Removed | characters from the script examples. 599 c. Updated draft references to published RFCs. 601 Changes from -04 to -05: 603 a. Fixed examples. 605 b. Relaxed requirement that imported/exported variables be set 606 before being used. 608 Changes from -03 to -04: 610 a. Fixed missing 2119 definitions. 612 b. Defined interaction with variables through use of import and 613 export commands. 615 Changes from -02 to -03: 617 a. Refreshing expired draft (updated for nits). 619 b. Syntax -> Usage. 621 c. Updated to 3028bis reference. 623 Changes from -01 to -02: 625 a. Minor formatting changes only - refreshing expired draft. 627 Changes from -00 to -01: 629 a. Added IPR boiler plate. 631 b. Re-ordered sections at start to conform to RFC style. 633 c. Moved recursion comment into General Considerations section. 635 d. Switched to using optional parameter to indicate personal vs 636 global. 638 e. Explicitly state that an error occurs when a missing script is 639 included. 641 Authors' Addresses 643 Cyrus Daboo 645 Email: cyrus@daboo.name 647 Aaron Stone 649 Email: aaron@serendipity.cx