idnits 2.17.1 draft-ietf-sieve-include-07.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 5, 2011) is 4678 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 259, but not defined == Missing Reference: 'ONCE' is mentioned on line 259, but not defined Summary: 0 errors (**), 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 July 5, 2011 5 Expires: January 6, 2012 7 Sieve Email Filtering: Include Extension 8 draft-ietf-sieve-include-07 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 6, 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 . . . . . . . . . . . . . . . . . . 5 53 2. Conventions Used in This Document . . . . . . . . . . . . . . 5 54 3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 6 55 3.1. General Considerations . . . . . . . . . . . . . . . . . . 6 56 3.2. Control Structure include . . . . . . . . . . . . . . . . 7 57 3.3. Control Structure return . . . . . . . . . . . . . . . . . 10 58 3.4. Interaction with Variables . . . . . . . . . . . . . . . . 10 59 3.4.1. Control Structure global . . . . . . . . . . . . . . . 10 60 3.4.2. Variables Namespace global . . . . . . . . . . . . . . 12 61 4. Security Considerations . . . . . . . . . . . . . . . . . . . 13 62 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 63 5.1. "include" Extension Registration . . . . . . . . . . . . . 13 64 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 65 6.1. Normative References . . . . . . . . . . . . . . . . . . . 14 66 6.2. Informative References . . . . . . . . . . . . . . . . . . 14 67 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 14 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14 70 Change History (to be removed prior to publication as an RFC) 72 Changes from ietf-06 to ietf-07: 74 a. Nits from Stephan Bosch. 76 Changes from ietf-05 to ietf-06: 78 a. Nits from Barry Leiba. 80 Changes from ietf-04 to ietf-05: 82 a. Integrate review from Barry Leiba. 84 Changes from ietf-03 to ietf-04: 86 a. No changes. 88 Changes from ietf-02 to ietf-03: 90 a. Setting a variable then calling global on it is an error 91 (something like 'use strict'). 93 b. Specify that the 'global' keyword is only available when 94 'variables' has also been required. 96 c. Uploading a script that includes a nonexistent script is not an 97 error at upload time. 99 Changes from ietf-01 to ietf-02: 101 a. Require that script names must be constant strings, not subject 102 to variable expansion. 104 b. Try the phrase immediate script instead of current script. 106 c. Clarify that "global 'varname'" and "global.varname" refer to the 107 same variable. 109 d. Drop the requirement the global keywords come after require and 110 before anything else. 112 Changes from ietf-00 to ietf-01: 114 a. Replaced import/export with global. 116 b. Added :once modifier to include. 118 c. Added global namespace to see if it holds water. 120 Changes from daboo-06 to ietf-00: 122 a. None 124 Changes from -05 to -06: 126 a. Aaron Stone joins as author. 128 b. Removed | characters from the script examples. 130 c. Updated draft references to published RFCs. 132 Changes from -04 to -05: 134 a. Fixed examples. 136 b. Relaxed requirement that imported/exported variables be set 137 before being used. 139 Changes from -03 to -04: 141 a. Fixed missing 2119 definitions. 143 b. Defined interaction with variables through use of import and 144 export commands. 146 Changes from -02 to -03: 148 a. Refreshing expired draft (updated for nits). 150 b. Syntax -> Usage. 152 c. Updated to 3028bis reference. 154 Changes from -01 to -02: 156 a. Minor formatting changes only - refreshing expired draft. 158 Changes from -00 to -01: 160 a. Added IPR boiler plate. 162 b. Re-ordered sections at start to conform to RFC style. 164 c. Moved recursion comment into General Considerations section. 166 d. Switched to using optional parameter to indicate personal vs 167 global. 169 e. Explicitly state that an error occurs when a missing script is 170 included. 172 1. Introduction and Overview 174 It's convenient to be able to break SIEVE [RFC5228] scripts down into 175 smaller components which can be reused in a variety of different 176 circumstances. For example, users may want to have a default script 177 and a special 'vacation' script, the latter being activated when the 178 user goes on vacation. In that case the default actions should 179 continue to be run, but a vacation command should be executed first. 180 One option is to edit the default script to add or remove the 181 vacation command as needed. Another is to have a vacation script 182 that simply has a vacation command and then includes the default 183 script. 185 2. Conventions Used in This Document 187 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 188 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 189 document are to be interpreted as described in [RFC2119]. 191 Conventions for notations are as in SIEVE [RFC5228] Section 1.1. 193 The following key phrases are used to describe scripts and script 194 execution: 196 script 197 a valid Sieve script. 199 script execution 200 an instance of a Sieve interpreter invoked for a given message 201 delivery, starting with the user's active script and continuing 202 through any included scripts until the message is delivered. 204 immediate script 205 the individual Sieve script file being executed. 207 including script 208 the individual Sieve script file that had an include statement 209 which included the immediate script. 211 3. Include Extension 213 3.1. General Considerations 215 Sieve implementations that implement the "include", "return", and 216 "global" commands described below have an identifier of "include" for 217 use with the capability mechanism. If any of the "include", 218 "return", or "global" commands are used in a script, the "include" 219 capability MUST be listed in the "require" statement in that script. 221 Sieve implementations need to track the use of actions in included 222 scripts so that implicit "keep" behavior can be properly determined 223 based on whether any actions have executed in any script. 225 Sieve implementations are allowed to limit the total number of nested 226 included scripts, but MUST provide for a total of at least three 227 levels of nested scripts including the top-level script. An error 228 MUST be generated either when the script is uploaded to the Sieve 229 repository, or when the script is executed, if any nesting limit is 230 exceeded. If such an error is detected whilst processing a Sieve 231 script, an implicit "keep" action MUST be executed to prevent loss of 232 any messages. 234 Sieve implementations MUST ensure that recursive includes are not 235 possible. For example, if script "A" includes script "B", and script 236 "B" includes script "A" an error MUST be generated either when the 237 script is uploaded to the Sieve repository, or when the script is 238 executed. If such an error is detected whilst processing a Sieve 239 script, an implicit "keep" action MUST be executed to prevent loss of 240 any messages. 242 Sieve implementations MUST generate an error at execution time if an 243 included script does not exist. Implementations MUST NOT generate 244 errors for scripts missing at upload time, as this would force an 245 upload ordering requirement upon script authors / generators. 247 If the Sieve "variables" extension [RFC5229] is present, an issue 248 arises with the "scope" of variables defined in scripts that may 249 include each other. For example, if a script defines the variable 250 "${status}" with one particular meaning or usage, and another defines 251 "${status}" with a different meaning, then if one script includes the 252 other there is an issue as to which "${status}" is being referenced. 253 To solve this problem, Sieve implementations MUST follow the scoping 254 rules defined in Section 3.4 and support the "global" command defined 255 there. 257 3.2. Control Structure include 259 Usage: include [LOCATION] [ONCE] 261 LOCATION = ":personal" / ":global" 263 ONCE = ":once" 265 The "include" command takes an optional "location" parameter, an 266 optional ":once" parameter, and a single string argument representing 267 the name of the script to include for processing at that point. It 268 is RECOMMENDED that implementations restrict script names according 269 to MANAGESIEVE [RFC5804] Section 1.7. Implementations MUST NOT allow 270 variables to be expanded into the names of Sieve scripts; in other 271 words, the value MUST be a constant string as defined in VARIABLES 272 [RFC5229], Section 3. 274 The "location" parameter MUST default to ":personal" if not 275 specified. The "location" has the following meanings: 277 :personal 278 Indicates that the named script is stored in the user's own 279 personal (private) Sieve repository. 281 :global 282 Indicates that the named script is stored in a site-wide Sieve 283 repository, accessible to all users of the Sieve system. 285 The ":once" parameter tells the interpreter only to include the named 286 script if it has not already been included at any other point during 287 script execution. If the script has already been included, 288 processing continues immediately following the include command. 289 Implementations MUST NOT generate an error if an "include :once" 290 command names a script whose inclusion would be recursive; in this 291 case, the script MUST be considered previously included and therefore 292 "include :once" will not include it again. 294 Note: It is RECOMMENDED that script authors / generators use this 295 parameter only when including a script that performs general duties 296 such as declaring global variables and making sanity checks of the 297 environment. 299 The included script MUST be a valid Sieve script, including having 300 necessary "require" statements for all optional capabilities used by 301 the script. The scope of a "require" statement in an included script 302 is for the immediate script only, not the including script. For 303 example, if script "A" includes script "B", and script "B" uses the 304 "fileinto" extension, script "B" must have a "require" statement for 305 "fileinto", irrespective of whether script "A" has one. In addition, 306 if script "A" does not have a "require" statement for "fileinto", 307 "fileinto" cannot be used anywhere in script "A", even after 308 inclusion of script "B". 310 A "stop" command in an included script MUST stop all script 311 processing, including the processing of the scripts that include the 312 immediate one. The "return" command (described below) stops 313 processing of the immediate script only, and allows the scripts that 314 include it to continue. 316 Examples: 318 The user has four scripts stored in their personal repository: 320 "default" 322 This is the default active script that includes several others. 324 require ["include"]; 326 include :personal "always_allow"; 327 include :global "spam_tests"; 328 include :personal "spam_tests"; 329 include :personal "mailing_lists"; 331 Personal script "always_allow" 333 This script special-cases some correspondent email addresses and 334 makes sure any message containing those addresses are always kept. 336 if address :is "from" "boss@example.com" 337 { 338 keep; 339 } 340 elsif address :is "from" "ceo@example.com" 341 { 342 keep; 343 } 345 Personal script "spam_tests" 347 This script does some user-specific spam tests to catch spam 348 messages not caught by the site-wide spam tests. 350 require ["reject"]; 352 if header :contains "Subject" "XXXX" 353 { 354 reject "Subject XXXX is unacceptable."; 355 } 356 elsif address :is "from" "money@example.com" 357 { 358 reject "Mail from this sender is unwelcome."; 359 } 361 Personal script "mailing_lists" 363 This script looks for messages from different mailing lists and 364 files each into a mailbox specific to the mailing list. 366 require ["fileinto"]; 368 if header :is "List-ID" "sieve.ietf.org" 369 { 370 fileinto "lists.sieve"; 371 } 372 elsif header :is "List-ID" "ietf-imapext.imc.org" 373 { 374 fileinto "lists.imapext"; 375 } 377 There is one script stored in the global repository: 379 Site script "spam_tests" 381 This script does some site-wide spam tests which any user at the 382 site can include in their own scripts at a suitable point. The 383 script content is kept up to date by the site administrator. 385 require ["reject"]; 387 if anyof (header :contains "Subject" "$$", 388 header :contains "Subject" "Make money") 389 { 390 reject; 391 } 393 The "include" command may appear anywhere in the script where a 394 control structure is legal. 396 Example: 398 require ["include"]; 400 if anyof (header :contains "Subject" "$$", 401 header :contains "Subject" "Make money") 402 { 403 include "my_reject_script"; 404 } 406 3.3. Control Structure return 408 Usage: return 410 The "return" command stops processing of the immediately included 411 script only and returns processing control to the script which 412 includes it. If used in the main script (i.e., not in an included 413 script), it has the same effect as the "stop" command, including the 414 appropriate "keep" action if no other actions have been executed up 415 to that point. 417 3.4. Interaction with Variables 419 In order to avoid problems of variables in an included script 420 "overwriting" those from the script that includes it, this 421 specification requires that all variables defined in a script MUST be 422 kept "private" to the immediate script by default - that is, they are 423 not "visible" to other scripts. This ensures that two script authors 424 cannot inadvertently cause problems by choosing the same name for a 425 variable. 427 However, sometimes there is a need to make a variable defined in one 428 script available to others. This specification defines the new 429 command "global" to declare that a variable is shared among scripts. 430 Effectively, two namespaces are defined: one local to the immediate 431 script, and another shared among all scripts. Implementations MUST 432 allow a non-global variable to have the same name as a global 433 variable but have no interaction between them. 435 3.4.1. Control Structure global 437 Usage: global 439 The "global" command contains a string list argument that defines one 440 or more names of variables to be stored in the global variable space. 442 The "global" command is only available when the script has both 443 "include" and "variables" in its require line. If the "global" 444 command appears when only "include" or only "variables" has been 445 required, an error MUST be generated when the script is uploaded. 447 If a "global" command is given the name of a variable that has 448 previously been defined in the immediate script with "set", an error 449 MUST be generated either when the script is uploaded or at execution 450 time. 452 If a "global" command lists a variable that has not been defined in 453 the global namespace, the name of the variable is now marked as 454 global, and any subsequent "set" command will set the value of the 455 variable in global scope. 457 A variable has global scope in all scripts that have declared it with 458 the "global" command. If a script uses that variable name without 459 declaring it global, the name specifies a separate, non-global 460 variable within that script. 462 Interpretation of a string containing a variable marked as global, 463 but without any value set, SHALL behave as any other access to an 464 unknown variable, as specified in VARIABLES [RFC5229], Section 3 465 (i.e., evaluates to an empty string). 467 Example: 469 The active script 471 The included script may contain repetitive code that is 472 effectively a subroutine that can be factored out. In this 473 script, the test which matches last will leave its value in the 474 test-mailbox variable and the top-level script will file the 475 message into that mailbox. If no tests matched, the message will 476 be implicitly kept in the INBOX. 478 require ["include", "variables", "relational"]; 479 global "test"; 480 global "test-mailbox"; 482 set "test" "$$" 483 include "spam_checks"; 485 set "test" "Make money" 486 include "spam_checks"; 488 if string :count "eq" "${test-mailbox}" "1" 489 { 490 fileinto "${test-mailbox}"; 491 stop; 492 } 494 Personal script "spam_checks" 496 This script is makes a number of tests against the message, 497 falling through back to the top-level script having set the global 498 test-mailbox variable with a target folder to file the message 499 into. 501 require ["include", "variables"]; 502 global ["test", "test-mailbox"]; 504 if header :contains "Subject" "${test}" 505 { 506 set "test-mailbox" "spam-${test}"; 507 } 509 3.4.2. Variables Namespace global 511 In addition to the "global" command, this document defines the 512 variables namespace "global", as specified in VARIABLES [RFC5229], 513 Section 3. 515 Example: 517 require ["variables", "include"]; 519 set "global.i_am_on_vacation" "1"; 521 Variables declared global and variables accessed via the global 522 namespace MUST be one and the same. In the following example script, 523 we see the variable "i_am_on_vacation" used in a "global" command, 524 and again with the "global." namespace. Consider these as two 525 syntaxes with identical meaning. 527 Example: 529 require ["variables", "include"]; 530 global "i_am_on_vacation"; 532 set "global.i_am_on_vacation" "1"; 534 if string :is "${i_am_on_vacation}" "1" 535 { 536 vacation "It's true, I am on vacation." 537 } 539 4. Security Considerations 541 Sieve implementations MUST ensure adequate security for the global 542 script repository to prevent unauthorized changes to global scripts. 544 Sieve implementations MUST ensure that script names are checked for 545 validity and proper permissions prior to inclusion, in order to 546 prevent a malicious user from gaining acess to files accessible to 547 the mail server software that should not be accessible to the user. 549 Beyond these, the "include" extension does not raise any security 550 considerations that are not present in the base SIEVE [RFC5228] 551 document and the VARIABLES [RFC5229] extension. 553 5. IANA Considerations 555 The following template specifies the IANA registration of the Sieve 556 extension specified in this document: 558 5.1. "include" Extension Registration 560 Capability name: include 561 Description: adds the "include" command to execute other Sieve 562 scripts, and the "global" command and "global" 563 variables namespace to access variables shared 564 among included scripts. 565 RFC number: this RFC 566 Contact address: the Sieve discussion list 568 6. References 569 6.1. Normative References 571 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 572 Requirement Levels", BCP 14, RFC 2119, March 1997. 574 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 575 Language", RFC 5228, January 2008. 577 [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", 578 RFC 5229, January 2008. 580 6.2. Informative References 582 [RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely 583 Managing Sieve Scripts", RFC 5804, July 2010. 585 Appendix A. Acknowledgments 587 Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz, 588 Kjetil Torgrim Homme, Stephan Bosch, Arnt Gulbrandsen, Barry Leiba, 589 and Jeffrey Hutzelman for comments and corrections. 591 Authors' Addresses 593 Cyrus Daboo 595 Email: cyrus@daboo.name 597 Aaron Stone 599 Email: aaron@serendipity.cx