idnits 2.17.1 draft-ietf-sieve-include-02.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 : ---------------------------------------------------------------------------- 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 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 (May 4, 2009) is 5471 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 203, but not defined == Missing Reference: 'ONCE' is mentioned on line 203, but not defined Summary: 1 error (**), 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: November 5, 2009 May 4, 2009 6 Sieve Email Filtering: Include Extension 7 draft-ietf-sieve-include-02 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 November 5, 2009. 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-01 to ietf-02: 64 a. Require that script names must be constant strings, not subject 65 to variable expansion. 66 b. Try the phrase immediate script instead of current script. 67 c. Clarify that "global 'varname'" and "global.varname" refer to the 68 same variable. 69 d. Drop the requirement the global keywords come after require and 70 before anything else. 72 Changes from ietf-00 to ietf-01: 73 a. Replaced import/export with global. 74 b. Added :once modifier to include. 75 c. Added global namespace to see if it holds water. 77 Changes from daboo-06 to ietf-00: 78 a. None 80 Changes from -05 to -06: 81 a. Aaron Stone joins as author. 82 b. Removed | characters from the script examples. 83 c. Updated draft references to published RFCs. 85 Changes from -04 to -05: 86 a. Fixed examples. 87 b. Relaxed requirement that imported/exported variables be set 88 before being used. 90 Changes from -03 to -04: 91 a. Fixed missing 2119 definitions. 92 b. Defined interaction with variables through use of import and 93 export commands. 95 Changes from -02 to -03: 97 a. Refreshing expired draft (updated for nits). 98 b. Syntax -> Usage. 99 c. Updated to 3028bis reference. 101 Changes from -01 to -02: 102 a. Minor formatting changes only - refreshing expired draft. 104 Changes from -00 to -01: 105 a. Added IPR boiler plate. 106 b. Re-ordered sections at start to conform to RFC style. 107 c. Moved recursion comment into General Considerations section. 108 d. Switched to using optional parameter to indicate personal vs 109 global. 110 e. Explicitly state that an error occurs when a missing script is 111 included. 113 Table of Contents 115 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4 116 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 117 3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 4 118 3.1. General Considerations . . . . . . . . . . . . . . . . . . 4 119 3.2. Control Structure include . . . . . . . . . . . . . . . . 5 120 3.3. Control Structure return . . . . . . . . . . . . . . . . . 8 121 3.4. Interaction with Variables . . . . . . . . . . . . . . . . 8 122 3.4.1. Control Structure global . . . . . . . . . . . . . . . 9 123 3.4.2. Variables Namespace global . . . . . . . . . . . . . . 10 124 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 125 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 126 5.1. "include" Extension Registration . . . . . . . . . . . . . 11 127 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 128 6.1. Normative References . . . . . . . . . . . . . . . . . . . 12 129 6.2. Informative References . . . . . . . . . . . . . . . . . . 12 130 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 12 131 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 133 1. Introduction and Overview 135 It's convenient to be able to break SIEVE [RFC5228] scripts down into 136 smaller components which can be reused in a variety of different 137 circumstances. For example, users may want to have a default script 138 and a special 'vacation' script, the latter being activated when the 139 user goes on vacation. In that case the default actions should 140 continue to be run, but a vacation command should be executed first. 141 One option is to edit the default script to add or remove the 142 vacation command as needed. Another is to have a vacation script 143 that simply has a vacation command and then includes the default 144 script. 146 2. Conventions Used in This Document 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 150 document are to be interpreted as described in [RFC2119]. 152 Conventions for notations are as in SIEVE [RFC5228] Section 1.1. 154 3. Include Extension 156 3.1. General Considerations 158 Sieve implementations that implement the "include", "return", and 159 "global" commands described below have an identifier of "include" for 160 use with the capability mechanism. If any of the "include", 161 "return", or "global" commands are used in a script, the "include" 162 capability MUST be listed in the "require" statement in that script. 164 Sieve implementations must track the use of actions in included 165 scripts so that implicit "keep" behavior can be properly determined 166 based on whether any actions have executed in any script. 168 Sieve implementations are allowed to limit the total number of nested 169 included scripts, but MUST provide for a total of at least three 170 levels of nested scripts including the top-level script. An error 171 MUST be generated either when the script is uploaded to the Sieve 172 repository, or when the script is executed, if any nesting limit is 173 exceeded. If such an error is detected whilst processing a Sieve 174 script, an implicit "keep" action MUST be executed to prevent loss of 175 any messages. 177 Sieve implementations MUST ensure that recursive includes are not 178 possible. For example, if script "A" includes script "B", and script 179 "B" includes script "A" an error MUST be generated either when the 180 script is uploaded to the Sieve repository, or when the script is 181 executed. If such an error is detected whilst processing a Sieve 182 script, an implicit "keep" action MUST be executed to prevent loss of 183 any messages. 185 Sieve implementations MUST handle missing scripts being referenced 186 via an includes in an existing script. An error MUST be generated 187 when a missing included script is discovered during execution. If 188 such an error is detected an implicit "keep" action MUST be executed 189 to prevent loss of any messages. 191 If the Sieve "variables" extension [RFC5229] is present, an issue 192 arises with the "scope" of variables defined in scripts that may 193 include each other. For example, if a script defines the variable 194 "${status}" with one particular meaning or usage, and another defines 195 "${status}" with a different meaning, then if one script includes the 196 other there is an issue as to which "${status}" is being referenced. 197 To solve this problem, Sieve implementations MUST follow the scoping 198 rules defined in Section 3.4 and support the "global" command defined 199 there. 201 3.2. Control Structure include 203 Usage: include [LOCATION] [ONCE] 205 LOCATION = ":personal" / ":global" 207 ONCE = ":once" 209 The "include" command takes an optional "location" parameter, an 210 optional ":once" parameter, and a single string argument representing 211 the name of the script to include for processing at that point. It 212 is RECOMMENDED that implementations restrict script names according 213 to [I-D.ietf-sieve-managesieve] Section 1.7. Implementations MUST 214 NOT allow variables to be expanded into the names of Sieve scripts; 215 in other words, the value MUST be a constant string as defined in by 216 VARIABLES [RFC5229] Section 3. 218 The "location" parameter MUST default to ":personal" if not 219 specified. The "location" has the following meanings: 221 :personal 222 Indicates that the named script is stored in the user's own 223 personal (private) Sieve repository. 225 :global 226 Indicates that the named script is stored in a site-wide Sieve 227 repository, accessible to all users of the Sieve system. 229 The ":once" parameter tells the interpreter only to include the named 230 script if it has not already been included at any other point during 231 script execution. If the script has already been included, 232 processing continues immediately following the include command. 233 Implementations MUST NOT generate an error if an "include :once" 234 command names a script whose inclusion would be recursive; in this 235 case, the script MUST be considered previously included and therefore 236 "include :once" will not include it again. 238 Note: It is RECOMMENDED that script authors / generators use this 239 parameter only when including a script that performs general duties 240 such as declaring global variables and making sanity checks of the 241 environment. 243 The included script MUST be a valid Sieve script, including having 244 necessary "require" statements for all optional capabilities used by 245 the script. The scope of a "require" statement in an included script 246 is for the immediate script only, not the including script. For 247 example, if script "A" includes script "B", and script "B" uses the 248 "fileinto" extension, script "B" must have a "require" statement for 249 "fileinto", irrespective of whether script "A" has one. In addition, 250 if script "A" does not have a "require" statement for "fileinto", 251 "fileinto" cannot be used anywhere in script "A", even after 252 inclusion of script "B". 254 A "stop" command in an included script MUST stop all script 255 processing, including the processing of the scripts that include the 256 immediate one. The "return" command (described below) stops 257 processing of the immediate script only, and allows the scripts that 258 include it to continue. 260 Examples: 262 The user has four scripts stored in their personal repository: 264 "default" 266 This is the default active script that includes several others. 268 require ["include"]; 270 include :personal "always_allow"; 271 include :global "spam_tests"; 272 include :personal "spam_tests"; 273 include :personal "mailing_lists"; 275 Personal script "always_allow" 277 This script special cases some correspondent email addresses and 278 makes sure any message containing those addresses are always kept. 280 if header :is "From" "boss@example.com" 281 { 282 keep; 283 } 284 elsif header :is "From" "ceo@example.com" 285 { 286 keep; 287 } 289 Personal script "spam_tests" 291 This script does some user-specific spam tests to catch spam 292 messages not caught by the site-wide spam tests. 294 require ["reject"]; 296 if header :contains "Subject" "XXXX" 297 { 298 reject; 299 } 300 elsif header :is "From" "money@example.com" 301 { 302 reject; 303 } 305 Personal script "mailing_lists" 307 This script looks for messages from different mailing lists and 308 files each into a mailbox specific to the mailing list. 310 require ["fileinto"]; 312 if header :is "Sender" "owner-ietf-mta-filters@imc.org" 313 { 314 fileinto "lists.sieve"; 315 } 316 elsif header :is "Sender" "owner-ietf-imapext@imc.org" 317 { 318 fileinto "lists.imapext"; 319 } 321 There is one script stored in the global repository: 323 Site script "spam_tests" 325 This script does some site-wide spam tests which any user at the 326 site can include in their own scripts at a suitable point. The 327 script content is kept up to date by the site administrator. 329 require ["reject"]; 331 if anyof (header :contains "Subject" "$$", 332 header :contains "Subject" "Make money") 333 { 334 reject; 335 } 337 The "include" command may appear anywhere in the script where a 338 control structure is legal. 340 Example: 342 require ["include"]; 344 if anyof (header :contains "Subject" "$$", 345 header :contains "Subject" "Make money") 346 { 347 include "my_reject_script"; 348 } 350 3.3. Control Structure return 352 Usage: return 354 The "return" command stops processing of the immediately included 355 script only and returns processing control to the script which 356 includes it. If used in the main script (i.e. not in an included 357 script), it has the same effect as the "stop" command, including the 358 appropriate "keep" action if no other actions have been executed up 359 to that point. 361 3.4. Interaction with Variables 363 In order to avoid problems of variables in an included script 364 "overwriting" those from the script that includes it, this 365 specification requires that all variables defined in a script MUST be 366 kept "private" to the immediate script by default - i.e. they are not 367 "visible" to other scripts. This ensures that two script authors 368 cannot inadvertently cause problems by choosing the same name for a 369 variable. 371 However, sometimes there is a need to make a variable defined in one 372 script available to others. This specification defines the new 373 command "global" to declare that a variable is shared among scripts. 374 Effectively, two namespaces are defined: one local to the immediate 375 script, and another shared among all scripts. Implementations MUST 376 allow a non-global variable to have the same name as a global 377 variable but have no interaction between them. 379 3.4.1. Control Structure global 381 Usage: global 383 The "global" command contains a string list argument that defines one 384 or more names of variables to be stored in the global variable space. 386 If a "global" command is given the name of a variable that has been 387 defined in the immediate script, any value stored in the global space 388 is overwritten with the value of the variable in the script. 390 If a "global" command lists a variable that has not been defined in 391 the global namespace, the name of the variable is nonetheless marked 392 as global, and any subsequent "set" command will set the value of the 393 variable in global scope. 395 Interpretation of a string containing a variable marked as global, 396 but without any value set, SHALL behave as any other access to an 397 unknown variable, as specified in Section 3 of [RFC5229] (that is, 398 the unknown variable reference evaltuates to an empty string). 400 Example: 402 require ["variables", "include"]; 403 global "test"; 404 global "test-mailbox"; 406 # The included script may contain repetitive code that is 407 # effectively a subroutine that can be factored out. 408 set "test" "$$" 409 include "spam_filter_script"; 411 set "test" "Make money" 412 include "spam_filter_script"; 414 # Message will be filed according to the test that matched last. 415 if string :count "${test-mailbox}" "1" 416 { 417 fileinto "INBOX${test-mailbox}"; 418 stop; 419 } 421 # If nothing matched, the message is implicitly kept. 423 Active script 425 require ["variables", "include"]; 426 global ["test", "test-mailbox"]; 428 if header :contains "Subject" "${test}" 429 { 430 set "test-mailbox" "spam-${test}; 431 } 433 spam_filter_script 435 3.4.2. Variables Namespace global 437 In addition to the "global" command, this document defines the 438 variables namespace "global", per [RFC5229], Section 3. 440 Example: 442 require ["variables", "include"]; 444 set "global.i_am_on_vacation" "1"; 446 Variables declared global and variables accessed via the global 447 namespace MUST be one and the same. In the following example script, 448 we see the variable "i_am_on_vacation" used in a "global" command, 449 and again with the "global." namespace. Consider these as two 450 syntaxes with identical meaning. 452 Example: 454 require ["variables", "include"]; 455 global "i_am_on_vacation"; 457 set "global.i_am_on_vacation" "1"; 459 if string :is "${i_am_on_vacation}" "1" 460 { 461 vacation "It's true, I am on vacation." 462 } 464 4. Security Considerations 466 Sieve implementations MUST ensure adequate security for the global 467 script repository to prevent unauthorized changes to global scripts. 469 Sieve implementations MUST ensure that script names are checked for 470 validity and proper permissions prior to inclusion, in order to 471 prevent a malicious user from gaining acess to files accessible to 472 the mail server software that should not be accessible to the user. 474 Beyond these, the "include" extension does not raise any security 475 considerations that are not present in the base SIEVE [RFC5228] 476 document. 478 5. IANA Considerations 480 The following template specifies the IANA registration of the Sieve 481 extension specified in this document: 483 5.1. "include" Extension Registration 485 Capability name: include 486 Description: add the "include" command to execute other Sieve 487 scripts. 488 RFC number: this RFC 489 Contact address: the Sieve discussion list 491 6. References 492 6.1. Normative References 494 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 495 Requirement Levels", BCP 14, RFC 2119, March 1997. 497 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 498 Language", RFC 5228, January 2008. 500 [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", 501 RFC 5229, January 2008. 503 6.2. Informative References 505 [I-D.ietf-sieve-managesieve] 506 Martin, T. and A. Melnikov, "A Protocol for Remotely 507 Managing Sieve Scripts", draft-ietf-sieve-managesieve-09 508 (work in progress), January 2009. 510 Appendix A. Acknowledgments 512 Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz, 513 Kjetil Torgrim Homme, Stephan Bosch, and Arnt Gulbrandsen for 514 comments and corrections. 516 Authors' Addresses 518 Cyrus Daboo 520 Email: cyrus@daboo.name 522 Aaron Stone 524 Email: aaron@serendipity.palo-alto.ca.us