idnits 2.17.1 draft-ietf-sieve-include-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 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 12, 2010) is 5037 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 263, but not defined == Missing Reference: 'ONCE' is mentioned on line 263, but not defined Summary: 1 error (**), 0 flaws (~~), 4 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 12, 2010 5 Expires: January 13, 2011 7 Sieve Email Filtering: Include Extension 8 draft-ietf-sieve-include-05 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 13, 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 This document may contain material from IETF Documents or IETF 51 Contributions published or made publicly available before November 52 10, 2008. The person(s) controlling the copyright in some of this 53 material may not have granted the IETF Trust the right to allow 54 modifications of such material outside the IETF Standards Process. 55 Without obtaining an adequate license from the person(s) controlling 56 the copyright in such materials, this document may not be modified 57 outside the IETF Standards Process, and derivative works of it may 58 not be created outside the IETF Standards Process, except to format 59 it for publication as an RFC or to translate it into languages other 60 than English. 62 Table of Contents 64 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 5 65 2. Conventions Used in This Document . . . . . . . . . . . . . . 5 66 3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 5 67 3.1. General Considerations . . . . . . . . . . . . . . . . . . 5 68 3.2. Control Structure include . . . . . . . . . . . . . . . . 6 69 3.3. Control Structure return . . . . . . . . . . . . . . . . . 10 70 3.4. Interaction with Variables . . . . . . . . . . . . . . . . 10 71 3.4.1. Control Structure global . . . . . . . . . . . . . . . 10 72 3.4.2. Variables Namespace global . . . . . . . . . . . . . . 12 73 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 74 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 75 5.1. "include" Extension Registration . . . . . . . . . . . . . 13 76 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 77 6.1. Normative References . . . . . . . . . . . . . . . . . . . 13 78 6.2. Informative References . . . . . . . . . . . . . . . . . . 13 79 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 13 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 82 Change History (to be removed prior to publication as an RFC) 84 Changes from ietf-04 to ietf-05: 86 a. Integrate review from Barry Leiba. 88 Changes from ietf-03 to ietf-04: 90 a. No changes. 92 Changes from ietf-02 to ietf-03: 94 a. Setting a variable then calling global on it is an error 95 (something like 'use strict'). 97 b. Specify that the 'global' keyword is only available when 98 'variables' has also been required. 100 c. Uploading a script that includes a nonexistent script is not an 101 error at upload time. 103 Changes from ietf-01 to ietf-02: 105 a. Require that script names must be constant strings, not subject 106 to variable expansion. 108 b. Try the phrase immediate script instead of current script. 110 c. Clarify that "global 'varname'" and "global.varname" refer to the 111 same variable. 113 d. Drop the requirement the global keywords come after require and 114 before anything else. 116 Changes from ietf-00 to ietf-01: 118 a. Replaced import/export with global. 120 b. Added :once modifier to include. 122 c. Added global namespace to see if it holds water. 124 Changes from daboo-06 to ietf-00: 126 a. None 128 Changes from -05 to -06: 130 a. Aaron Stone joins as author. 132 b. Removed | characters from the script examples. 134 c. Updated draft references to published RFCs. 136 Changes from -04 to -05: 138 a. Fixed examples. 140 b. Relaxed requirement that imported/exported variables be set 141 before being used. 143 Changes from -03 to -04: 145 a. Fixed missing 2119 definitions. 147 b. Defined interaction with variables through use of import and 148 export commands. 150 Changes from -02 to -03: 152 a. Refreshing expired draft (updated for nits). 154 b. Syntax -> Usage. 156 c. Updated to 3028bis reference. 158 Changes from -01 to -02: 160 a. Minor formatting changes only - refreshing expired draft. 162 Changes from -00 to -01: 164 a. Added IPR boiler plate. 166 b. Re-ordered sections at start to conform to RFC style. 168 c. Moved recursion comment into General Considerations section. 170 d. Switched to using optional parameter to indicate personal vs 171 global. 173 e. Explicitly state that an error occurs when a missing script is 174 included. 176 1. Introduction and Overview 178 It's convenient to be able to break SIEVE [RFC5228] scripts down into 179 smaller components which can be reused in a variety of different 180 circumstances. For example, users may want to have a default script 181 and a special 'vacation' script, the latter being activated when the 182 user goes on vacation. In that case the default actions should 183 continue to be run, but a vacation command should be executed first. 184 One option is to edit the default script to add or remove the 185 vacation command as needed. Another is to have a vacation script 186 that simply has a vacation command and then includes the default 187 script. 189 2. Conventions Used in This Document 191 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 192 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 193 document are to be interpreted as described in [RFC2119]. 195 Conventions for notations are as in SIEVE [RFC5228] Section 1.1. 197 The following key phrases are used to describe scripts and script 198 execution: 200 script 201 a valid Sieve script. 203 script execution 204 an instance of a Sieve interpreter invoked for a given message 205 delivery, starting with the user's active script and continuing 206 through any included scripts until the message is delivered. 208 immediate script 209 the individual Sieve script file being executed. 211 including script 212 the individual Sieve script file that had an include statement 213 which included the immediate script. 215 3. Include Extension 217 3.1. General Considerations 219 Sieve implementations that implement the "include", "return", and 220 "global" commands described below have an identifier of "include" for 221 use with the capability mechanism. If any of the "include", 222 "return", or "global" commands are used in a script, the "include" 223 capability MUST be listed in the "require" statement in that script. 225 Sieve implementations need to track the use of actions in included 226 scripts so that implicit "keep" behavior can be properly determined 227 based on whether any actions have executed in any script. 229 Sieve implementations are allowed to limit the total number of nested 230 included scripts, but MUST provide for a total of at least three 231 levels of nested scripts including the top-level script. An error 232 MUST be generated either when the script is uploaded to the Sieve 233 repository, or when the script is executed, if any nesting limit is 234 exceeded. 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 ensure that recursive includes are not 239 possible. For example, if script "A" includes script "B", and script 240 "B" includes script "A" an error MUST be generated either when the 241 script is uploaded to the Sieve repository, or when the script is 242 executed. If such an error is detected whilst processing a Sieve 243 script, an implicit "keep" action MUST be executed to prevent loss of 244 any messages. 246 Sieve implementations MUST generate an error at execution time if an 247 included script does not exist. Implementations MUST NOT generate 248 errors for scripts missing at upload time, as this would force an 249 upload ordering requirement upon script authors / generators. 251 If the Sieve "variables" extension [RFC5229] is present, an issue 252 arises with the "scope" of variables defined in scripts that may 253 include each other. For example, if a script defines the variable 254 "${status}" with one particular meaning or usage, and another defines 255 "${status}" with a different meaning, then if one script includes the 256 other there is an issue as to which "${status}" is being referenced. 257 To solve this problem, Sieve implementations MUST follow the scoping 258 rules defined in Section 3.4 and support the "global" command defined 259 there. 261 3.2. Control Structure include 263 Usage: include [LOCATION] [ONCE] 265 LOCATION = ":personal" / ":global" 267 ONCE = ":once" 269 The "include" command takes an optional "location" parameter, an 270 optional ":once" parameter, and a single string argument representing 271 the name of the script to include for processing at that point. It 272 is RECOMMENDED that implementations restrict script names according 273 to [I-D.ietf-sieve-managesieve] Section 1.7. Implementations MUST 274 NOT allow variables to be expanded into the names of Sieve scripts; 275 in other words, the value MUST be a constant string as defined in 276 VARIABLES [RFC5229], Section 3. 278 The "location" parameter MUST default to ":personal" if not 279 specified. The "location" has the following meanings: 281 :personal 282 Indicates that the named script is stored in the user's own 283 personal (private) Sieve repository. 285 :global 286 Indicates that the named script is stored in a site-wide Sieve 287 repository, accessible to all users of the Sieve system. 289 The ":once" parameter tells the interpreter only to include the named 290 script if it has not already been included at any other point during 291 script execution. If the script has already been included, 292 processing continues immediately following the include command. 293 Implementations MUST NOT generate an error if an "include :once" 294 command names a script whose inclusion would be recursive; in this 295 case, the script MUST be considered previously included and therefore 296 "include :once" will not include it again. 298 Note: It is RECOMMENDED that script authors / generators use this 299 parameter only when including a script that performs general duties 300 such as declaring global variables and making sanity checks of the 301 environment. 303 The included script MUST be a valid Sieve script, including having 304 necessary "require" statements for all optional capabilities used by 305 the script. The scope of a "require" statement in an included script 306 is for the immediate script only, not the including script. For 307 example, if script "A" includes script "B", and script "B" uses the 308 "fileinto" extension, script "B" must have a "require" statement for 309 "fileinto", irrespective of whether script "A" has one. In addition, 310 if script "A" does not have a "require" statement for "fileinto", 311 "fileinto" cannot be used anywhere in script "A", even after 312 inclusion of script "B". 314 A "stop" command in an included script MUST stop all script 315 processing, including the processing of the scripts that include the 316 immediate one. The "return" command (described below) stops 317 processing of the immediate script only, and allows the scripts that 318 include it to continue. 320 Examples: 322 The user has four scripts stored in their personal repository: 324 "default" 326 This is the default active script that includes several others. 328 require ["include"]; 330 include :personal "always_allow"; 331 include :global "spam_tests"; 332 include :personal "spam_tests"; 333 include :personal "mailing_lists"; 335 Personal script "always_allow" 337 This script special-cases some correspondent email addresses and 338 makes sure any message containing those addresses are always kept. 340 if header :is "From" "boss@example.com" 341 { 342 keep; 343 } 344 elsif header :is "From" "ceo@example.com" 345 { 346 keep; 347 } 349 Personal script "spam_tests" 351 This script does some user-specific spam tests to catch spam 352 messages not caught by the site-wide spam tests. 354 require ["reject"]; 356 if header :contains "Subject" "XXXX" 357 { 358 reject; 359 } 360 elsif header :is "From" "money@example.com" 361 { 362 reject; 364 } 366 Personal script "mailing_lists" 368 This script looks for messages from different mailing lists and 369 files each into a mailbox specific to the mailing list. 371 require ["fileinto"]; 373 if header :is "List-ID" "owner-ietf-mta-filters@imc.org" 374 { 375 fileinto "lists.sieve"; 376 } 377 elsif header :is "List-ID" "owner-ietf-imapext@imc.org" 378 { 379 fileinto "lists.imapext"; 380 } 382 There is one script stored in the global repository: 384 Site script "spam_tests" 386 This script does some site-wide spam tests which any user at the 387 site can include in their own scripts at a suitable point. The 388 script content is kept up to date by the site administrator. 390 require ["reject"]; 392 if anyof (header :contains "Subject" "$$", 393 header :contains "Subject" "Make money") 394 { 395 reject; 396 } 398 The "include" command may appear anywhere in the script where a 399 control structure is legal. 401 Example: 403 require ["include"]; 405 if anyof (header :contains "Subject" "$$", 406 header :contains "Subject" "Make money") 407 { 408 include "my_reject_script"; 409 } 411 3.3. Control Structure return 413 Usage: return 415 The "return" command stops processing of the immediately included 416 script only and returns processing control to the script which 417 includes it. If used in the main script (i.e., not in an included 418 script), it has the same effect as the "stop" command, including the 419 appropriate "keep" action if no other actions have been executed up 420 to that point. 422 3.4. Interaction with Variables 424 In order to avoid problems of variables in an included script 425 "overwriting" those from the script that includes it, this 426 specification requires that all variables defined in a script MUST be 427 kept "private" to the immediate script by default - that is, they are 428 not "visible" to other scripts. This ensures that two script authors 429 cannot inadvertently cause problems by choosing the same name for a 430 variable. 432 However, sometimes there is a need to make a variable defined in one 433 script available to others. This specification defines the new 434 command "global" to declare that a variable is shared among scripts. 435 Effectively, two namespaces are defined: one local to the immediate 436 script, and another shared among all scripts. Implementations MUST 437 allow a non-global variable to have the same name as a global 438 variable but have no interaction between them. 440 3.4.1. Control Structure global 442 Usage: global 444 The "global" command contains a string list argument that defines one 445 or more names of variables to be stored in the global variable space. 447 The "global" command is only available when the script has both 448 "include" and "variables" in its require line. If the "global" 449 command appears when only "include" or only "variables" has been 450 required, an error MUST be generated when the script is uploaded. 452 If a "global" command is given the name of a variable that has 453 previously been defined in the immediate script with "set", an error 454 MUST be generated either when the script is uploaded or at execution 455 time. 457 If a "global" command lists a variable that has not been defined in 458 the global namespace, the name of the variable is now marked as 459 global, and any subsequent "set" command will set the value of the 460 variable in global scope. 462 A variable has global scope in all scripts that have declared it with 463 the "global" command. If a script uses that variable name without 464 declaring it global, the name specifies a separate, non-global 465 variable within that script. 467 Interpretation of a string containing a variable marked as global, 468 but without any value set, SHALL behave as any other access to an 469 unknown variable, as specified in VARIABLES [RFC5229], Section 3 470 (i.e., evaluates to an empty string). 472 Example: 474 require ["variables", "include"]; 475 global "test"; 476 global "test-mailbox"; 478 # The included script may contain repetitive code that is 479 # effectively a subroutine that can be factored out. 480 set "test" "$$" 481 include "spam_filter_script"; 483 set "test" "Make money" 484 include "spam_filter_script"; 486 # Message will be filed according to the test that matched last. 487 if string :count "${test-mailbox}" "1" 488 { 489 fileinto "INBOX${test-mailbox}"; 490 stop; 491 } 493 # If nothing matched, the message is implicitly kept. 495 Active script 497 require ["variables", "include"]; 498 global ["test", "test-mailbox"]; 500 if header :contains "Subject" "${test}" 501 { 502 set "test-mailbox" "spam-${test}; 503 } 505 spam_filter_script 507 3.4.2. Variables Namespace global 509 In addition to the "global" command, this document defines the 510 variables namespace "global", as specified in VARIABLES [RFC5229], 511 Section 3. 513 Example: 515 require ["variables", "include"]; 517 set "global.i_am_on_vacation" "1"; 519 Variables declared global and variables accessed via the global 520 namespace MUST be one and the same. In the following example script, 521 we see the variable "i_am_on_vacation" used in a "global" command, 522 and again with the "global." namespace. Consider these as two 523 syntaxes with identical meaning. 525 Example: 527 require ["variables", "include"]; 528 global "i_am_on_vacation"; 530 set "global.i_am_on_vacation" "1"; 532 if string :is "${i_am_on_vacation}" "1" 533 { 534 vacation "It's true, I am on vacation." 535 } 537 4. Security Considerations 539 Sieve implementations MUST ensure adequate security for the global 540 script repository to prevent unauthorized changes to global scripts. 542 Sieve implementations MUST ensure that script names are checked for 543 validity and proper permissions prior to inclusion, in order to 544 prevent a malicious user from gaining acess to files accessible to 545 the mail server software that should not be accessible to the user. 547 Beyond these, the "include" extension does not raise any security 548 considerations that are not present in the base SIEVE [RFC5228] 549 document and the VARIABLES [RFC5229] extension. 551 5. IANA Considerations 553 The following template specifies the IANA registration of the Sieve 554 extension specified in this document: 556 5.1. "include" Extension Registration 558 Capability name: include 559 Description: adds the "include" command to execute other Sieve 560 scripts, and the "global" command and "global" variables 561 namespace to access variables shared among included scripts. 562 RFC number: this RFC 563 Contact address: the Sieve discussion list 565 6. References 567 6.1. Normative References 569 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 570 Requirement Levels", BCP 14, RFC 2119, March 1997. 572 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 573 Language", RFC 5228, January 2008. 575 [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", 576 RFC 5229, January 2008. 578 6.2. Informative References 580 [I-D.ietf-sieve-managesieve] 581 Melnikov, A. and T. Martin, "A Protocol for Remotely 582 Managing Sieve Scripts", draft-ietf-sieve-managesieve-09 583 (work in progress), January 2009. 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