idnits 2.17.1 draft-ietf-sieve-include-06.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 26, 2010) is 5022 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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 255, but not defined == Missing Reference: 'ONCE' is mentioned on line 255, but not defined Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). 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 26, 2010 5 Expires: January 27, 2011 7 Sieve Email Filtering: Include Extension 8 draft-ietf-sieve-include-06 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 27, 2011. 35 Copyright Notice 37 Copyright (c) 2010 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 . . . . . . . . . . . . . . . . . . . 12 62 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 63 5.1. "include" Extension Registration . . . . . . . . . . . . . 13 64 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 65 6.1. Normative References . . . . . . . . . . . . . . . . . . . 13 66 6.2. Informative References . . . . . . . . . . . . . . . . . . 13 67 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 13 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14 70 Change History (to be removed prior to publication as an RFC) 72 Changes from ietf-05 to ietf-06: 74 a. Nits from Barry Leiba. 76 Changes from ietf-04 to ietf-05: 78 a. Integrate review from Barry Leiba. 80 Changes from ietf-03 to ietf-04: 82 a. No changes. 84 Changes from ietf-02 to ietf-03: 86 a. Setting a variable then calling global on it is an error 87 (something like 'use strict'). 89 b. Specify that the 'global' keyword is only available when 90 'variables' has also been required. 92 c. Uploading a script that includes a nonexistent script is not an 93 error at upload time. 95 Changes from ietf-01 to ietf-02: 97 a. Require that script names must be constant strings, not subject 98 to variable expansion. 100 b. Try the phrase immediate script instead of current script. 102 c. Clarify that "global 'varname'" and "global.varname" refer to the 103 same variable. 105 d. Drop the requirement the global keywords come after require and 106 before anything else. 108 Changes from ietf-00 to ietf-01: 110 a. Replaced import/export with global. 112 b. Added :once modifier to include. 114 c. Added global namespace to see if it holds water. 116 Changes from daboo-06 to ietf-00: 118 a. None 120 Changes from -05 to -06: 122 a. Aaron Stone joins as author. 124 b. Removed | characters from the script examples. 126 c. Updated draft references to published RFCs. 128 Changes from -04 to -05: 130 a. Fixed examples. 132 b. Relaxed requirement that imported/exported variables be set 133 before being used. 135 Changes from -03 to -04: 137 a. Fixed missing 2119 definitions. 139 b. Defined interaction with variables through use of import and 140 export commands. 142 Changes from -02 to -03: 144 a. Refreshing expired draft (updated for nits). 146 b. Syntax -> Usage. 148 c. Updated to 3028bis reference. 150 Changes from -01 to -02: 152 a. Minor formatting changes only - refreshing expired draft. 154 Changes from -00 to -01: 156 a. Added IPR boiler plate. 158 b. Re-ordered sections at start to conform to RFC style. 160 c. Moved recursion comment into General Considerations section. 162 d. Switched to using optional parameter to indicate personal vs 163 global. 165 e. Explicitly state that an error occurs when a missing script is 166 included. 168 1. Introduction and Overview 170 It's convenient to be able to break SIEVE [RFC5228] scripts down into 171 smaller components which can be reused in a variety of different 172 circumstances. For example, users may want to have a default script 173 and a special 'vacation' script, the latter being activated when the 174 user goes on vacation. In that case the default actions should 175 continue to be run, but a vacation command should be executed first. 176 One option is to edit the default script to add or remove the 177 vacation command as needed. Another is to have a vacation script 178 that simply has a vacation command and then includes the default 179 script. 181 2. Conventions Used in This Document 183 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 184 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 185 document are to be interpreted as described in [RFC2119]. 187 Conventions for notations are as in SIEVE [RFC5228] Section 1.1. 189 The following key phrases are used to describe scripts and script 190 execution: 192 script 193 a valid Sieve script. 195 script execution 196 an instance of a Sieve interpreter invoked for a given message 197 delivery, starting with the user's active script and continuing 198 through any included scripts until the message is delivered. 200 immediate script 201 the individual Sieve script file being executed. 203 including script 204 the individual Sieve script file that had an include statement 205 which included the immediate script. 207 3. Include Extension 209 3.1. General Considerations 211 Sieve implementations that implement the "include", "return", and 212 "global" commands described below have an identifier of "include" for 213 use with the capability mechanism. If any of the "include", 214 "return", or "global" commands are used in a script, the "include" 215 capability MUST be listed in the "require" statement in that script. 217 Sieve implementations need to track the use of actions in included 218 scripts so that implicit "keep" behavior can be properly determined 219 based on whether any actions have executed in any script. 221 Sieve implementations are allowed to limit the total number of nested 222 included scripts, but MUST provide for a total of at least three 223 levels of nested scripts including the top-level script. An error 224 MUST be generated either when the script is uploaded to the Sieve 225 repository, or when the script is executed, if any nesting limit is 226 exceeded. If such an error is detected whilst processing a Sieve 227 script, an implicit "keep" action MUST be executed to prevent loss of 228 any messages. 230 Sieve implementations MUST ensure that recursive includes are not 231 possible. For example, if script "A" includes script "B", and script 232 "B" includes script "A" an error MUST be generated either when the 233 script is uploaded to the Sieve repository, or when the script is 234 executed. If such an error is detected whilst processing a Sieve 235 script, an implicit "keep" action MUST be executed to prevent loss of 236 any messages. 238 Sieve implementations MUST generate an error at execution time if an 239 included script does not exist. Implementations MUST NOT generate 240 errors for scripts missing at upload time, as this would force an 241 upload ordering requirement upon script authors / generators. 243 If the Sieve "variables" extension [RFC5229] is present, an issue 244 arises with the "scope" of variables defined in scripts that may 245 include each other. For example, if a script defines the variable 246 "${status}" with one particular meaning or usage, and another defines 247 "${status}" with a different meaning, then if one script includes the 248 other there is an issue as to which "${status}" is being referenced. 249 To solve this problem, Sieve implementations MUST follow the scoping 250 rules defined in Section 3.4 and support the "global" command defined 251 there. 253 3.2. Control Structure include 255 Usage: include [LOCATION] [ONCE] 257 LOCATION = ":personal" / ":global" 259 ONCE = ":once" 261 The "include" command takes an optional "location" parameter, an 262 optional ":once" parameter, and a single string argument representing 263 the name of the script to include for processing at that point. It 264 is RECOMMENDED that implementations restrict script names according 265 to MANAGESIEVE [RFC5804] Section 1.7. Implementations MUST NOT allow 266 variables to be expanded into the names of Sieve scripts; in other 267 words, the value MUST be a constant string as defined in VARIABLES 268 [RFC5229], Section 3. 270 The "location" parameter MUST default to ":personal" if not 271 specified. The "location" has the following meanings: 273 :personal 274 Indicates that the named script is stored in the user's own 275 personal (private) Sieve repository. 277 :global 278 Indicates that the named script is stored in a site-wide Sieve 279 repository, accessible to all users of the Sieve system. 281 The ":once" parameter tells the interpreter only to include the named 282 script if it has not already been included at any other point during 283 script execution. If the script has already been included, 284 processing continues immediately following the include command. 285 Implementations MUST NOT generate an error if an "include :once" 286 command names a script whose inclusion would be recursive; in this 287 case, the script MUST be considered previously included and therefore 288 "include :once" will not include it again. 290 Note: It is RECOMMENDED that script authors / generators use this 291 parameter only when including a script that performs general duties 292 such as declaring global variables and making sanity checks of the 293 environment. 295 The included script MUST be a valid Sieve script, including having 296 necessary "require" statements for all optional capabilities used by 297 the script. The scope of a "require" statement in an included script 298 is for the immediate script only, not the including script. For 299 example, if script "A" includes script "B", and script "B" uses the 300 "fileinto" extension, script "B" must have a "require" statement for 301 "fileinto", irrespective of whether script "A" has one. In addition, 302 if script "A" does not have a "require" statement for "fileinto", 303 "fileinto" cannot be used anywhere in script "A", even after 304 inclusion of script "B". 306 A "stop" command in an included script MUST stop all script 307 processing, including the processing of the scripts that include the 308 immediate one. The "return" command (described below) stops 309 processing of the immediate script only, and allows the scripts that 310 include it to continue. 312 Examples: 314 The user has four scripts stored in their personal repository: 316 "default" 318 This is the default active script that includes several others. 320 require ["include"]; 322 include :personal "always_allow"; 323 include :global "spam_tests"; 324 include :personal "spam_tests"; 325 include :personal "mailing_lists"; 327 Personal script "always_allow" 329 This script special-cases some correspondent email addresses and 330 makes sure any message containing those addresses are always kept. 332 if header :is "From" "boss@example.com" 333 { 334 keep; 335 } 336 elsif header :is "From" "ceo@example.com" 337 { 338 keep; 339 } 341 Personal script "spam_tests" 343 This script does some user-specific spam tests to catch spam 344 messages not caught by the site-wide spam tests. 346 require ["reject"]; 348 if header :contains "Subject" "XXXX" 349 { 350 reject; 351 } 352 elsif header :is "From" "money@example.com" 353 { 354 reject; 355 } 357 Personal script "mailing_lists" 359 This script looks for messages from different mailing lists and 360 files each into a mailbox specific to the mailing list. 362 require ["fileinto"]; 364 if header :is "List-ID" "sieve.ietf.org" 365 { 366 fileinto "lists.sieve"; 367 } 368 elsif header :is "List-ID" "ietf-imapext.imc.org" 369 { 370 fileinto "lists.imapext"; 371 } 373 There is one script stored in the global repository: 375 Site script "spam_tests" 377 This script does some site-wide spam tests which any user at the 378 site can include in their own scripts at a suitable point. The 379 script content is kept up to date by the site administrator. 381 require ["reject"]; 383 if anyof (header :contains "Subject" "$$", 384 header :contains "Subject" "Make money") 385 { 386 reject; 387 } 389 The "include" command may appear anywhere in the script where a 390 control structure is legal. 392 Example: 394 require ["include"]; 396 if anyof (header :contains "Subject" "$$", 397 header :contains "Subject" "Make money") 398 { 399 include "my_reject_script"; 400 } 402 3.3. Control Structure return 404 Usage: return 406 The "return" command stops processing of the immediately included 407 script only and returns processing control to the script which 408 includes it. If used in the main script (i.e., not in an included 409 script), it has the same effect as the "stop" command, including the 410 appropriate "keep" action if no other actions have been executed up 411 to that point. 413 3.4. Interaction with Variables 415 In order to avoid problems of variables in an included script 416 "overwriting" those from the script that includes it, this 417 specification requires that all variables defined in a script MUST be 418 kept "private" to the immediate script by default - that is, they are 419 not "visible" to other scripts. This ensures that two script authors 420 cannot inadvertently cause problems by choosing the same name for a 421 variable. 423 However, sometimes there is a need to make a variable defined in one 424 script available to others. This specification defines the new 425 command "global" to declare that a variable is shared among scripts. 426 Effectively, two namespaces are defined: one local to the immediate 427 script, and another shared among all scripts. Implementations MUST 428 allow a non-global variable to have the same name as a global 429 variable but have no interaction between them. 431 3.4.1. Control Structure global 433 Usage: global 435 The "global" command contains a string list argument that defines one 436 or more names of variables to be stored in the global variable space. 438 The "global" command is only available when the script has both 439 "include" and "variables" in its require line. If the "global" 440 command appears when only "include" or only "variables" has been 441 required, an error MUST be generated when the script is uploaded. 443 If a "global" command is given the name of a variable that has 444 previously been defined in the immediate script with "set", an error 445 MUST be generated either when the script is uploaded or at execution 446 time. 448 If a "global" command lists a variable that has not been defined in 449 the global namespace, the name of the variable is now marked as 450 global, and any subsequent "set" command will set the value of the 451 variable in global scope. 453 A variable has global scope in all scripts that have declared it with 454 the "global" command. If a script uses that variable name without 455 declaring it global, the name specifies a separate, non-global 456 variable within that script. 458 Interpretation of a string containing a variable marked as global, 459 but without any value set, SHALL behave as any other access to an 460 unknown variable, as specified in VARIABLES [RFC5229], Section 3 461 (i.e., evaluates to an empty string). 463 Example: 465 require ["variables", "include"]; 466 global "test"; 467 global "test-mailbox"; 469 # The included script may contain repetitive code that is 470 # effectively a subroutine that can be factored out. 471 set "test" "$$" 472 include "spam_filter_script"; 474 set "test" "Make money" 475 include "spam_filter_script"; 477 # Message will be filed according to the test that matched last. 478 if string :count "${test-mailbox}" "1" 479 { 480 fileinto "INBOX${test-mailbox}"; 481 stop; 482 } 484 # If nothing matched, the message is implicitly kept. 486 Active script 488 require ["variables", "include"]; 489 global ["test", "test-mailbox"]; 491 if header :contains "Subject" "${test}" 492 { 493 set "test-mailbox" "spam-${test}; 494 } 496 spam_filter_script 498 3.4.2. Variables Namespace global 500 In addition to the "global" command, this document defines the 501 variables namespace "global", as specified in VARIABLES [RFC5229], 502 Section 3. 504 Example: 506 require ["variables", "include"]; 508 set "global.i_am_on_vacation" "1"; 510 Variables declared global and variables accessed via the global 511 namespace MUST be one and the same. In the following example script, 512 we see the variable "i_am_on_vacation" used in a "global" command, 513 and again with the "global." namespace. Consider these as two 514 syntaxes with identical meaning. 516 Example: 518 require ["variables", "include"]; 519 global "i_am_on_vacation"; 521 set "global.i_am_on_vacation" "1"; 523 if string :is "${i_am_on_vacation}" "1" 524 { 525 vacation "It's true, I am on vacation." 526 } 528 4. Security Considerations 530 Sieve implementations MUST ensure adequate security for the global 531 script repository to prevent unauthorized changes to global scripts. 533 Sieve implementations MUST ensure that script names are checked for 534 validity and proper permissions prior to inclusion, in order to 535 prevent a malicious user from gaining acess to files accessible to 536 the mail server software that should not be accessible to the user. 538 Beyond these, the "include" extension does not raise any security 539 considerations that are not present in the base SIEVE [RFC5228] 540 document and the VARIABLES [RFC5229] extension. 542 5. IANA Considerations 544 The following template specifies the IANA registration of the Sieve 545 extension specified in this document: 547 5.1. "include" Extension Registration 549 Capability name: include 550 Description: adds the "include" command to execute other Sieve 551 scripts, and the "global" command and "global" 552 variables namespace to access variables shared 553 among included scripts. 554 RFC number: this RFC 555 Contact address: the Sieve discussion list 557 6. References 559 6.1. Normative References 561 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 562 Requirement Levels", BCP 14, RFC 2119, March 1997. 564 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 565 Language", RFC 5228, January 2008. 567 [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", 568 RFC 5229, January 2008. 570 6.2. Informative References 572 [RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely 573 Managing Sieve Scripts", RFC 5804, July 2010. 575 Appendix A. Acknowledgments 577 Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz, 578 Kjetil Torgrim Homme, Stephan Bosch, Arnt Gulbrandsen, Barry Leiba, 579 and Jeffrey Hutzelman for comments and corrections. 581 Authors' Addresses 583 Cyrus Daboo 585 Email: cyrus@daboo.name 587 Aaron Stone 589 Email: aaron@serendipity.cx