idnits 2.17.1 draft-ietf-sieve-include-04.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 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 2) being 63 lines 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 8 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 seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 28, 2010) is 5051 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 262, but not defined == Missing Reference: 'ONCE' is mentioned on line 262, but not defined Summary: 1 error (**), 0 flaws (~~), 6 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 Expires: December 28, 2010 June 28, 2010 6 Sieve Email Filtering: Include Extension 7 draft-ietf-sieve-include-04 9 Status of this Memo 11 This Internet-Draft is submitted to IETF in full conformance with the 12 provisions of BCP 78 and BCP 79. This document may contain material 13 from IETF Documents or IETF Contributions published or made publicly 14 available before November 10, 2008. The person(s) controlling the 15 copyright in some of this material may not have granted the IETF 16 Trust the right to allow modifications of such material outside the 17 IETF Standards Process. Without obtaining an adequate license from 18 the person(s) controlling the copyright in such materials, this 19 document may not be modified outside the IETF Standards Process, and 20 derivative works of it may not be created outside the IETF Standards 21 Process, except to format it for publication as an RFC or to 22 translate it into languages other than English. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF), its areas, and its working groups. Note that 26 other groups may also distribute working documents as Internet- 27 Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt. 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html. 40 This Internet-Draft will expire on December 28, 2010. 42 Copyright Notice 44 Copyright (c) 2010 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal Provisions 48 Relating to IETF Documents (http://trustee.ietf.org/license-info) 49 in effect on the date of publication of this document. Please 50 review these documents carefully, as they describe your rights and 51 restrictions with respect to this document. Code Components 52 extracted from this document must include Simplified BSD License 53 text as described in Section 4.e of the Trust Legal Provisions and 54 are provided without warranty as described in the Simplified BSD 55 License. 57 Abstract 59 The Sieve Email Filtering "include" extension permits users to 60 include one Sieve script inside another. This can make managing 61 large scripts or multiple sets of scripts much easier, and allows a 62 site and its users to build up libraries of scripts. Users are able 63 to include their own personal scripts or site-wide scripts. 65 Change History (to be removed prior to publication as an RFC) 67 Changes from ietf-03 to ietf-04: 69 a. No changes. 71 Changes from ietf-02 to ietf-03: 73 a. Setting a variable then calling global on it is an error 74 (something like 'use strict'). 76 b. Specify that the 'global' keyword is only available when 77 'variables' has also been required. 79 c. Uploading a script that includes a nonexistent script is not an 80 error at upload time. 82 Changes from ietf-01 to ietf-02: 84 a. Require that script names must be constant strings, not subject 85 to variable expansion. 87 b. Try the phrase immediate script instead of current script. 89 c. Clarify that "global 'varname'" and "global.varname" refer to the 90 same variable. 92 d. Drop the requirement the global keywords come after require and 93 before anything else. 95 Changes from ietf-00 to ietf-01: 97 a. Replaced import/export with global. 99 b. Added :once modifier to include. 101 c. Added global namespace to see if it holds water. 103 Changes from daboo-06 to ietf-00: 105 a. None 107 Changes from -05 to -06: 109 a. Aaron Stone joins as author. 111 b. Removed | characters from the script examples. 113 c. Updated draft references to published RFCs. 115 Changes from -04 to -05: 117 a. Fixed examples. 119 b. Relaxed requirement that imported/exported variables be set 120 before being used. 122 Changes from -03 to -04: 124 a. Fixed missing 2119 definitions. 126 b. Defined interaction with variables through use of import and 127 export commands. 129 Changes from -02 to -03: 131 a. Refreshing expired draft (updated for nits). 133 b. Syntax -> Usage. 135 c. Updated to 3028bis reference. 137 Changes from -01 to -02: 139 a. Minor formatting changes only - refreshing expired draft. 141 Changes from -00 to -01: 143 a. Added IPR boiler plate. 145 b. Re-ordered sections at start to conform to RFC style. 147 c. Moved recursion comment into General Considerations section. 149 d. Switched to using optional parameter to indicate personal vs 150 global. 152 e. Explicitly state that an error occurs when a missing script is 153 included. 155 Table of Contents 157 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 5 158 2. Conventions Used in This Document . . . . . . . . . . . . . . 5 159 3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 5 160 3.1. General Considerations . . . . . . . . . . . . . . . . . . 5 161 3.2. Control Structure include . . . . . . . . . . . . . . . . 6 162 3.3. Control Structure return . . . . . . . . . . . . . . . . . 10 163 3.4. Interaction with Variables . . . . . . . . . . . . . . . . 10 164 3.4.1. Control Structure global . . . . . . . . . . . . . . . 10 165 3.4.2. Variables Namespace global . . . . . . . . . . . . . . 12 166 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 167 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 168 5.1. "include" Extension Registration . . . . . . . . . . . . . 13 169 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 170 6.1. Normative References . . . . . . . . . . . . . . . . . . . 13 171 6.2. Informative References . . . . . . . . . . . . . . . . . . 13 172 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 13 173 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 175 1. Introduction and Overview 177 It's convenient to be able to break SIEVE [RFC5228] scripts down into 178 smaller components which can be reused in a variety of different 179 circumstances. For example, users may want to have a default script 180 and a special 'vacation' script, the latter being activated when the 181 user goes on vacation. In that case the default actions should 182 continue to be run, but a vacation command should be executed first. 183 One option is to edit the default script to add or remove the 184 vacation command as needed. Another is to have a vacation script 185 that simply has a vacation command and then includes the default 186 script. 188 2. Conventions Used in This Document 190 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 191 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 192 document are to be interpreted as described in [RFC2119]. 194 Conventions for notations are as in SIEVE [RFC5228] Section 1.1. 196 The following key phrases are used to describe scripts and script 197 execution: 199 script 200 a valid Sieve script. 202 script execution 203 an instance of a Sieve interpreter invoked for a given message 204 delivery, starting with the user's active script and continuing 205 through any included scripts until the message is delivered. 207 immediate script 208 the individual Sieve script file being executed. 210 including script 211 the individual Sieve script file that had an include statement 212 which included the immediate script. 214 3. Include Extension 216 3.1. General Considerations 218 Sieve implementations that implement the "include", "return", and 219 "global" commands described below have an identifier of "include" for 220 use with the capability mechanism. If any of the "include", 221 "return", or "global" commands are used in a script, the "include" 222 capability MUST be listed in the "require" statement in that script. 224 Sieve implementations must track the use of actions in included 225 scripts so that implicit "keep" behavior can be properly determined 226 based on whether any actions have executed in any script. 228 Sieve implementations are allowed to limit the total number of nested 229 included scripts, but MUST provide for a total of at least three 230 levels of nested scripts including the top-level script. An error 231 MUST be generated either when the script is uploaded to the Sieve 232 repository, or when the script is executed, if any nesting limit is 233 exceeded. If such an error is detected whilst processing a Sieve 234 script, an implicit "keep" action MUST be executed to prevent loss of 235 any messages. 237 Sieve implementations MUST ensure that recursive includes are not 238 possible. For example, if script "A" includes script "B", and script 239 "B" includes script "A" an error MUST be generated either when the 240 script is uploaded to the Sieve repository, or when the script is 241 executed. If such an error is detected whilst processing a Sieve 242 script, an implicit "keep" action MUST be executed to prevent loss of 243 any messages. 245 Sieve implementations MUST generate an error at execution time if an 246 included script does not exist. Implementations MUST NOT generate 247 errors for scripts missing at upload time, as this would force an 248 upload ordering requirement upon script authors / generators. 250 If the Sieve "variables" extension [RFC5229] is present, an issue 251 arises with the "scope" of variables defined in scripts that may 252 include each other. For example, if a script defines the variable 253 "${status}" with one particular meaning or usage, and another defines 254 "${status}" with a different meaning, then if one script includes the 255 other there is an issue as to which "${status}" is being referenced. 256 To solve this problem, Sieve implementations MUST follow the scoping 257 rules defined in Section 3.4 and support the "global" command defined 258 there. 260 3.2. Control Structure include 262 Usage: include [LOCATION] [ONCE] 264 LOCATION = ":personal" / ":global" 266 ONCE = ":once" 268 The "include" command takes an optional "location" parameter, an 269 optional ":once" parameter, and a single string argument representing 270 the name of the script to include for processing at that point. It 271 is RECOMMENDED that implementations restrict script names according 272 to [I-D.ietf-sieve-managesieve] Section 1.7. Implementations MUST 273 NOT allow variables to be expanded into the names of Sieve scripts; 274 in other words, the value MUST be a constant string as defined in 275 VARIABLES [RFC5229], Section 3. 277 The "location" parameter MUST default to ":personal" if not 278 specified. The "location" has the following meanings: 280 :personal 281 Indicates that the named script is stored in the user's own 282 personal (private) Sieve repository. 284 :global 285 Indicates that the named script is stored in a site-wide Sieve 286 repository, accessible to all users of the Sieve system. 288 The ":once" parameter tells the interpreter only to include the named 289 script if it has not already been included at any other point during 290 script execution. If the script has already been included, 291 processing continues immediately following the include command. 292 Implementations MUST NOT generate an error if an "include :once" 293 command names a script whose inclusion would be recursive; in this 294 case, the script MUST be considered previously included and therefore 295 "include :once" will not include it again. 297 Note: It is RECOMMENDED that script authors / generators use this 298 parameter only when including a script that performs general duties 299 such as declaring global variables and making sanity checks of the 300 environment. 302 The included script MUST be a valid Sieve script, including having 303 necessary "require" statements for all optional capabilities used by 304 the script. The scope of a "require" statement in an included script 305 is for the immediate script only, not the including script. For 306 example, if script "A" includes script "B", and script "B" uses the 307 "fileinto" extension, script "B" must have a "require" statement for 308 "fileinto", irrespective of whether script "A" has one. In addition, 309 if script "A" does not have a "require" statement for "fileinto", 310 "fileinto" cannot be used anywhere in script "A", even after 311 inclusion of script "B". 313 A "stop" command in an included script MUST stop all script 314 processing, including the processing of the scripts that include the 315 immediate one. The "return" command (described below) stops 316 processing of the immediate script only, and allows the scripts that 317 include it to continue. 319 Examples: 321 The user has four scripts stored in their personal repository: 323 "default" 325 This is the default active script that includes several others. 327 require ["include"]; 329 include :personal "always_allow"; 330 include :global "spam_tests"; 331 include :personal "spam_tests"; 332 include :personal "mailing_lists"; 334 Personal script "always_allow" 336 This script special cases some correspondent email addresses and 337 makes sure any message containing those addresses are always kept. 339 if header :is "From" "boss@example.com" 340 { 341 keep; 342 } 343 elsif header :is "From" "ceo@example.com" 344 { 345 keep; 346 } 348 Personal script "spam_tests" 350 This script does some user-specific spam tests to catch spam 351 messages not caught by the site-wide spam tests. 353 require ["reject"]; 355 if header :contains "Subject" "XXXX" 356 { 357 reject; 358 } 359 elsif header :is "From" "money@example.com" 360 { 361 reject; 363 } 365 Personal script "mailing_lists" 367 This script looks for messages from different mailing lists and 368 files each into a mailbox specific to the mailing list. 370 require ["fileinto"]; 372 if header :is "Sender" "owner-ietf-mta-filters@imc.org" 373 { 374 fileinto "lists.sieve"; 375 } 376 elsif header :is "Sender" "owner-ietf-imapext@imc.org" 377 { 378 fileinto "lists.imapext"; 379 } 381 There is one script stored in the global repository: 383 Site script "spam_tests" 385 This script does some site-wide spam tests which any user at the 386 site can include in their own scripts at a suitable point. The 387 script content is kept up to date by the site administrator. 389 require ["reject"]; 391 if anyof (header :contains "Subject" "$$", 392 header :contains "Subject" "Make money") 393 { 394 reject; 395 } 397 The "include" command may appear anywhere in the script where a 398 control structure is legal. 400 Example: 402 require ["include"]; 404 if anyof (header :contains "Subject" "$$", 405 header :contains "Subject" "Make money") 406 { 407 include "my_reject_script"; 408 } 410 3.3. Control Structure return 412 Usage: return 414 The "return" command stops processing of the immediately included 415 script only and returns processing control to the script which 416 includes it. If used in the main script (i.e. not in an included 417 script), it has the same effect as the "stop" command, including the 418 appropriate "keep" action if no other actions have been executed up 419 to that point. 421 3.4. Interaction with Variables 423 In order to avoid problems of variables in an included script 424 "overwriting" those from the script that includes it, this 425 specification requires that all variables defined in a script MUST be 426 kept "private" to the immediate script by default - i.e. they are not 427 "visible" to other scripts. This ensures that two script authors 428 cannot inadvertently cause problems by choosing the same name for a 429 variable. 431 However, sometimes there is a need to make a variable defined in one 432 script available to others. This specification defines the new 433 command "global" to declare that a variable is shared among scripts. 434 Effectively, two namespaces are defined: one local to the immediate 435 script, and another shared among all scripts. Implementations MUST 436 allow a non-global variable to have the same name as a global 437 variable but have no interaction between them. 439 3.4.1. Control Structure global 441 Usage: global 443 The "global" command contains a string list argument that defines one 444 or more names of variables to be stored in the global variable space. 446 The "global" command is only available when the script has both 447 "include" and "variables" in its require line. If the "global" 448 command appears when only "include" or only "variables" has been 449 required, an error MUST be generated when the script is uploaded. 451 If a "global" command is given the name of a variable that has 452 previously been defined in the immediate script with "set", an error 453 MUST be generated either when the script is uploaded or at execution 454 time. 456 If a "global" command lists a variable that has not been defined in 457 the global namespace, the name of the variable is now marked as 458 global, and any subsequent "set" command will set the value of the 459 variable in global scope. 461 Interpretation of a string containing a variable marked as global, 462 but without any value set, SHALL behave as any other access to an 463 unknown variable, as specified in VARIABLES [RFC5229], Section 3 464 (i.e., evaluates to an empty string). 466 Example: 468 require ["variables", "include"]; 469 global "test"; 470 global "test-mailbox"; 472 # The included script may contain repetitive code that is 473 # effectively a subroutine that can be factored out. 474 set "test" "$$" 475 include "spam_filter_script"; 477 set "test" "Make money" 478 include "spam_filter_script"; 480 # Message will be filed according to the test that matched last. 481 if string :count "${test-mailbox}" "1" 482 { 483 fileinto "INBOX${test-mailbox}"; 484 stop; 485 } 487 # If nothing matched, the message is implicitly kept. 489 Active script 491 require ["variables", "include"]; 492 global ["test", "test-mailbox"]; 494 if header :contains "Subject" "${test}" 495 { 496 set "test-mailbox" "spam-${test}; 497 } 499 spam_filter_script 501 3.4.2. Variables Namespace global 503 In addition to the "global" command, this document defines the 504 variables namespace "global", as specified in VARIABLES [RFC5229], 505 Section 3. 507 Example: 509 require ["variables", "include"]; 511 set "global.i_am_on_vacation" "1"; 513 Variables declared global and variables accessed via the global 514 namespace MUST be one and the same. In the following example script, 515 we see the variable "i_am_on_vacation" used in a "global" command, 516 and again with the "global." namespace. Consider these as two 517 syntaxes with identical meaning. 519 Example: 521 require ["variables", "include"]; 522 global "i_am_on_vacation"; 524 set "global.i_am_on_vacation" "1"; 526 if string :is "${i_am_on_vacation}" "1" 527 { 528 vacation "It's true, I am on vacation." 529 } 531 4. Security Considerations 533 Sieve implementations MUST ensure adequate security for the global 534 script repository to prevent unauthorized changes to global scripts. 536 Sieve implementations MUST ensure that script names are checked for 537 validity and proper permissions prior to inclusion, in order to 538 prevent a malicious user from gaining acess to files accessible to 539 the mail server software that should not be accessible to the user. 541 Beyond these, the "include" extension does not raise any security 542 considerations that are not present in the base SIEVE [RFC5228] 543 document and the VARIABLES [RFC5229] extension. 545 5. IANA Considerations 547 The following template specifies the IANA registration of the Sieve 548 extension specified in this document: 550 5.1. "include" Extension Registration 552 Capability name: include 553 Description: adds the "include" command to execute other Sieve 554 scripts, and the "global" command and "global" variables 555 namespace to access variables shared among included scripts. 556 RFC number: this RFC 557 Contact address: the Sieve discussion list 559 6. References 561 6.1. Normative References 563 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 564 Requirement Levels", BCP 14, RFC 2119, March 1997. 566 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 567 Language", RFC 5228, January 2008. 569 [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", 570 RFC 5229, January 2008. 572 6.2. Informative References 574 [I-D.ietf-sieve-managesieve] 575 Martin, T. and A. Melnikov, "A Protocol for Remotely 576 Managing Sieve Scripts", draft-ietf-sieve-managesieve-09 577 (work in progress), January 2009. 579 Appendix A. Acknowledgments 581 Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz, 582 Kjetil Torgrim Homme, Stephan Bosch, Arnt Gulbrandsen, Barry Leiba, 583 and Jeffrey Hutzelman for comments and corrections. 585 Authors' Addresses 587 Cyrus Daboo 589 Email: cyrus@daboo.name 591 Aaron Stone 593 Email: aaron@serendipity.cx