idnits 2.17.1 draft-ietf-sieve-include-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 2 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 (July 29, 2009) is 5385 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 254, but not defined == Missing Reference: 'ONCE' is mentioned on line 254, but not defined Summary: 2 errors (**), 0 flaws (~~), 5 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: January 30, 2010 July 29, 2009 6 Sieve Email Filtering: Include Extension 7 draft-ietf-sieve-include-03 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 January 30, 2010. 42 Copyright Notice 44 Copyright (c) 2009 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 48 Provisions Relating to IETF Documents in effect on the date of 49 publication of this document (http://trustee.ietf.org/license-info). 50 Please review these documents carefully, as they describe your rights 51 and restrictions with respect to this document. 53 Abstract 55 The Sieve Email Filtering "include" extension permits users to 56 include one Sieve script inside another. This can make managing 57 large scripts or multiple sets of scripts much easier, and allows a 58 site and its users to build up libraries of scripts. Users are able 59 to include their own personal scripts or site-wide scripts. 61 Change History (to be removed prior to publication as an RFC) 63 Changes from ietf-02 to ietf-03: 65 a. Setting a variable then calling global on it is an error 66 (something like 'use strict'). 68 b. Specify that the 'global' keyword is only available when 69 'variables' has also been required. 71 c. Uploading a script that includes a nonexistent script is not an 72 error at upload time. 74 Changes from ietf-01 to ietf-02: 76 a. Require that script names must be constant strings, not subject 77 to variable expansion. 79 b. Try the phrase immediate script instead of current script. 81 c. Clarify that "global 'varname'" and "global.varname" refer to the 82 same variable. 84 d. Drop the requirement the global keywords come after require and 85 before anything else. 87 Changes from ietf-00 to ietf-01: 89 a. Replaced import/export with global. 91 b. Added :once modifier to include. 93 c. Added global namespace to see if it holds water. 95 Changes from daboo-06 to ietf-00: 97 a. None 99 Changes from -05 to -06: 101 a. Aaron Stone joins as author. 103 b. Removed | characters from the script examples. 105 c. Updated draft references to published RFCs. 107 Changes from -04 to -05: 109 a. Fixed examples. 111 b. Relaxed requirement that imported/exported variables be set 112 before being used. 114 Changes from -03 to -04: 116 a. Fixed missing 2119 definitions. 118 b. Defined interaction with variables through use of import and 119 export commands. 121 Changes from -02 to -03: 123 a. Refreshing expired draft (updated for nits). 125 b. Syntax -> Usage. 127 c. Updated to 3028bis reference. 129 Changes from -01 to -02: 131 a. Minor formatting changes only - refreshing expired draft. 133 Changes from -00 to -01: 135 a. Added IPR boiler plate. 137 b. Re-ordered sections at start to conform to RFC style. 139 c. Moved recursion comment into General Considerations section. 141 d. Switched to using optional parameter to indicate personal vs 142 global. 144 e. Explicitly state that an error occurs when a missing script is 145 included. 147 Table of Contents 149 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 5 150 2. Conventions Used in This Document . . . . . . . . . . . . . . 5 151 3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 5 152 3.1. General Considerations . . . . . . . . . . . . . . . . . . 5 153 3.2. Control Structure include . . . . . . . . . . . . . . . . 6 154 3.3. Control Structure return . . . . . . . . . . . . . . . . . 10 155 3.4. Interaction with Variables . . . . . . . . . . . . . . . . 10 156 3.4.1. Control Structure global . . . . . . . . . . . . . . . 10 157 3.4.2. Variables Namespace global . . . . . . . . . . . . . . 12 158 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 159 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 160 5.1. "include" Extension Registration . . . . . . . . . . . . . 13 161 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 162 6.1. Normative References . . . . . . . . . . . . . . . . . . . 13 163 6.2. Informative References . . . . . . . . . . . . . . . . . . 13 164 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 13 165 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 167 1. Introduction and Overview 169 It's convenient to be able to break SIEVE [RFC5228] scripts down into 170 smaller components which can be reused in a variety of different 171 circumstances. For example, users may want to have a default script 172 and a special 'vacation' script, the latter being activated when the 173 user goes on vacation. In that case the default actions should 174 continue to be run, but a vacation command should be executed first. 175 One option is to edit the default script to add or remove the 176 vacation command as needed. Another is to have a vacation script 177 that simply has a vacation command and then includes the default 178 script. 180 2. Conventions Used in This Document 182 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 183 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 184 document are to be interpreted as described in [RFC2119]. 186 Conventions for notations are as in SIEVE [RFC5228] Section 1.1. 188 The following key phrases are used to describe scripts and script 189 execution: 191 script 192 a valid Sieve script. 194 script execution 195 an instance of a Sieve interpreter invoked for a given message 196 delivery, starting with the user's active script and continuing 197 through any included scripts until the message is delivered. 199 immediate script 200 the individual Sieve script file being executed. 202 including script 203 the individual Sieve script file that had an include statement 204 which included the immediate script. 206 3. Include Extension 208 3.1. General Considerations 210 Sieve implementations that implement the "include", "return", and 211 "global" commands described below have an identifier of "include" for 212 use with the capability mechanism. If any of the "include", 213 "return", or "global" commands are used in a script, the "include" 214 capability MUST be listed in the "require" statement in that script. 216 Sieve implementations must track the use of actions in included 217 scripts so that implicit "keep" behavior can be properly determined 218 based on whether any actions have executed in any script. 220 Sieve implementations are allowed to limit the total number of nested 221 included scripts, but MUST provide for a total of at least three 222 levels of nested scripts including the top-level script. An error 223 MUST be generated either when the script is uploaded to the Sieve 224 repository, or when the script is executed, if any nesting limit is 225 exceeded. If such an error is detected whilst processing a Sieve 226 script, an implicit "keep" action MUST be executed to prevent loss of 227 any messages. 229 Sieve implementations MUST ensure that recursive includes are not 230 possible. For example, if script "A" includes script "B", and script 231 "B" includes script "A" an error MUST be generated either when the 232 script is uploaded to the Sieve repository, or when the script is 233 executed. 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 generate an error at execution time if an 238 included script does not exist. Implementations MUST NOT generate 239 errors for scripts missing at upload time, as this would force an 240 upload ordering requirement upon script authors / generators. 242 If the Sieve "variables" extension [RFC5229] is present, an issue 243 arises with the "scope" of variables defined in scripts that may 244 include each other. For example, if a script defines the variable 245 "${status}" with one particular meaning or usage, and another defines 246 "${status}" with a different meaning, then if one script includes the 247 other there is an issue as to which "${status}" is being referenced. 248 To solve this problem, Sieve implementations MUST follow the scoping 249 rules defined in Section 3.4 and support the "global" command defined 250 there. 252 3.2. Control Structure include 254 Usage: include [LOCATION] [ONCE] 256 LOCATION = ":personal" / ":global" 258 ONCE = ":once" 260 The "include" command takes an optional "location" parameter, an 261 optional ":once" parameter, and a single string argument representing 262 the name of the script to include for processing at that point. It 263 is RECOMMENDED that implementations restrict script names according 264 to [I-D.ietf-sieve-managesieve] Section 1.7. Implementations MUST 265 NOT allow variables to be expanded into the names of Sieve scripts; 266 in other words, the value MUST be a constant string as defined in 267 VARIABLES [RFC5229], Section 3. 269 The "location" parameter MUST default to ":personal" if not 270 specified. The "location" has the following meanings: 272 :personal 273 Indicates that the named script is stored in the user's own 274 personal (private) Sieve repository. 276 :global 277 Indicates that the named script is stored in a site-wide Sieve 278 repository, accessible to all users of the Sieve system. 280 The ":once" parameter tells the interpreter only to include the named 281 script if it has not already been included at any other point during 282 script execution. If the script has already been included, 283 processing continues immediately following the include command. 284 Implementations MUST NOT generate an error if an "include :once" 285 command names a script whose inclusion would be recursive; in this 286 case, the script MUST be considered previously included and therefore 287 "include :once" will not include it again. 289 Note: It is RECOMMENDED that script authors / generators use this 290 parameter only when including a script that performs general duties 291 such as declaring global variables and making sanity checks of the 292 environment. 294 The included script MUST be a valid Sieve script, including having 295 necessary "require" statements for all optional capabilities used by 296 the script. The scope of a "require" statement in an included script 297 is for the immediate script only, not the including script. For 298 example, if script "A" includes script "B", and script "B" uses the 299 "fileinto" extension, script "B" must have a "require" statement for 300 "fileinto", irrespective of whether script "A" has one. In addition, 301 if script "A" does not have a "require" statement for "fileinto", 302 "fileinto" cannot be used anywhere in script "A", even after 303 inclusion of script "B". 305 A "stop" command in an included script MUST stop all script 306 processing, including the processing of the scripts that include the 307 immediate one. The "return" command (described below) stops 308 processing of the immediate script only, and allows the scripts that 309 include it to continue. 311 Examples: 313 The user has four scripts stored in their personal repository: 315 "default" 317 This is the default active script that includes several others. 319 require ["include"]; 321 include :personal "always_allow"; 322 include :global "spam_tests"; 323 include :personal "spam_tests"; 324 include :personal "mailing_lists"; 326 Personal script "always_allow" 328 This script special cases some correspondent email addresses and 329 makes sure any message containing those addresses are always kept. 331 if header :is "From" "boss@example.com" 332 { 333 keep; 334 } 335 elsif header :is "From" "ceo@example.com" 336 { 337 keep; 338 } 340 Personal script "spam_tests" 342 This script does some user-specific spam tests to catch spam 343 messages not caught by the site-wide spam tests. 345 require ["reject"]; 347 if header :contains "Subject" "XXXX" 348 { 349 reject; 350 } 351 elsif header :is "From" "money@example.com" 352 { 353 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 "Sender" "owner-ietf-mta-filters@imc.org" 365 { 366 fileinto "lists.sieve"; 367 } 368 elsif header :is "Sender" "owner-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 - i.e. they are not 419 "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 Interpretation of a string containing a variable marked as global, 454 but without any value set, SHALL behave as any other access to an 455 unknown variable, as specified in VARIABLES [RFC5229], Section 3 456 (i.e., evaluates to an empty string). 458 Example: 460 require ["variables", "include"]; 461 global "test"; 462 global "test-mailbox"; 464 # The included script may contain repetitive code that is 465 # effectively a subroutine that can be factored out. 466 set "test" "$$" 467 include "spam_filter_script"; 469 set "test" "Make money" 470 include "spam_filter_script"; 472 # Message will be filed according to the test that matched last. 473 if string :count "${test-mailbox}" "1" 474 { 475 fileinto "INBOX${test-mailbox}"; 476 stop; 477 } 479 # If nothing matched, the message is implicitly kept. 481 Active script 483 require ["variables", "include"]; 484 global ["test", "test-mailbox"]; 486 if header :contains "Subject" "${test}" 487 { 488 set "test-mailbox" "spam-${test}; 489 } 491 spam_filter_script 493 3.4.2. Variables Namespace global 495 In addition to the "global" command, this document defines the 496 variables namespace "global", as specified in VARIABLES [RFC5229], 497 Section 3. 499 Example: 501 require ["variables", "include"]; 503 set "global.i_am_on_vacation" "1"; 505 Variables declared global and variables accessed via the global 506 namespace MUST be one and the same. In the following example script, 507 we see the variable "i_am_on_vacation" used in a "global" command, 508 and again with the "global." namespace. Consider these as two 509 syntaxes with identical meaning. 511 Example: 513 require ["variables", "include"]; 514 global "i_am_on_vacation"; 516 set "global.i_am_on_vacation" "1"; 518 if string :is "${i_am_on_vacation}" "1" 519 { 520 vacation "It's true, I am on vacation." 521 } 523 4. Security Considerations 525 Sieve implementations MUST ensure adequate security for the global 526 script repository to prevent unauthorized changes to global scripts. 528 Sieve implementations MUST ensure that script names are checked for 529 validity and proper permissions prior to inclusion, in order to 530 prevent a malicious user from gaining acess to files accessible to 531 the mail server software that should not be accessible to the user. 533 Beyond these, the "include" extension does not raise any security 534 considerations that are not present in the base SIEVE [RFC5228] 535 document and the VARIABLES [RFC5229] extension. 537 5. IANA Considerations 539 The following template specifies the IANA registration of the Sieve 540 extension specified in this document: 542 5.1. "include" Extension Registration 544 Capability name: include 545 Description: adds the "include" command to execute other Sieve 546 scripts, and the "global" command and "global" variables 547 namespace to access variables shared among included scripts. 548 RFC number: this RFC 549 Contact address: the Sieve discussion list 551 6. References 553 6.1. Normative References 555 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 556 Requirement Levels", BCP 14, RFC 2119, March 1997. 558 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 559 Language", RFC 5228, January 2008. 561 [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", 562 RFC 5229, January 2008. 564 6.2. Informative References 566 [I-D.ietf-sieve-managesieve] 567 Martin, T. and A. Melnikov, "A Protocol for Remotely 568 Managing Sieve Scripts", draft-ietf-sieve-managesieve-09 569 (work in progress), January 2009. 571 Appendix A. Acknowledgments 573 Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz, 574 Kjetil Torgrim Homme, Stephan Bosch, Arnt Gulbrandsen, Barry Leiba, 575 and Jeffrey Hutzelman for comments and corrections. 577 Authors' Addresses 579 Cyrus Daboo 581 Email: cyrus@daboo.name 583 Aaron Stone 585 Email: aaron@serendipity.cx