idnits 2.17.1 draft-ietf-sieve-include-01.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 (March 29, 2009) is 5507 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 198, but not defined == Missing Reference: 'ONCE' is mentioned on line 198, 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: September 30, 2009 March 29, 2009 6 Sieve Email Filtering: Include Extension 7 draft-ietf-sieve-include-01 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 September 30, 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-00 to ietf-01: 64 a. Replaced import/export with global. 65 b. Added :once modifier to include. 66 c. Added global namespace to see if it holds water. 68 Changes from daboo-06 to ietf-00: 69 a. None 71 Changes from -05 to -06: 72 a. Aaron Stone joins as author. 73 b. Removed | characters from the script examples. 74 c. Updated draft references to published RFCs. 76 Changes from -04 to -05: 77 a. Fixed examples. 78 b. Relaxed requirement that imported/exported variables be set 79 before being used. 81 Changes from -03 to -04: 82 a. Fixed missing 2119 definitions. 83 b. Defined interaction with variables through use of import and 84 export commands. 86 Changes from -02 to -03: 87 a. Refreshing expired draft (updated for nits). 88 b. Syntax -> Usage. 89 c. Updated to 3028bis reference. 91 Changes from -01 to -02: 92 a. Minor formatting changes only - refreshing expired draft. 94 Changes from -00 to -01: 96 a. Added IPR boiler plate. 97 b. Re-ordered sections at start to conform to RFC style. 98 c. Moved recursion comment into General Considerations section. 99 d. Switched to using optional parameter to indicate personal vs 100 global. 101 e. Explicitly state that an error occurs when a missing script is 102 included. 104 Open Issues (to be resolved prior to publication as an RFC) 106 a. Interaction with variables (scoping). Idea 1: use a "global" 107 command to make a variable shared between scripts. Idea 2: use a 108 "global" variable namespace and no additional commands. 110 Table of Contents 112 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4 113 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 114 3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 4 115 3.1. General Considerations . . . . . . . . . . . . . . . . . . 4 116 3.2. Control Structure include . . . . . . . . . . . . . . . . 5 117 3.3. Control Structure return . . . . . . . . . . . . . . . . . 8 118 3.4. Interaction with Variables . . . . . . . . . . . . . . . . 8 119 3.4.1. Control Structure global . . . . . . . . . . . . . . . 9 120 3.4.2. Variables Namespace global . . . . . . . . . . . . . . 10 121 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 122 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 123 5.1. "include" Extension Registration . . . . . . . . . . . . . 11 124 6. Normative References . . . . . . . . . . . . . . . . . . . . . 11 125 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 11 126 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 128 1. Introduction and Overview 130 It's convenient to be able to break SIEVE [RFC5228] scripts down into 131 smaller components which can be reused in a variety of different 132 circumstances. For example, users may want to have a default script 133 and a special 'vacation' script, the latter being activated when the 134 user goes on vacation. In that case the default actions should 135 continue to be run, but a vacation command should be executed first. 136 One option is to edit the default script to add or remove the 137 vacation command as needed. Another is to have a vacation script 138 that simply has a vacation command and then includes the default 139 script. 141 2. Conventions Used in This Document 143 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 144 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 145 document are to be interpreted as described in [RFC2119]. 147 Conventions for notations are as in SIEVE [RFC5228] Section 1.1. 149 3. Include Extension 151 3.1. General Considerations 153 Sieve implementations that implement the "include", "return", and 154 "global" commands described below have an identifier of "include" for 155 use with the capability mechanism. If any of the "include", 156 "return", or "global" commands are used in a script, the "include" 157 capability MUST be listed in the "require" statement in that script. 159 Sieve implementations must track the use of actions in included 160 scripts so that implicit "keep" behavior can be properly determined 161 based on whether any actions have executed in any script. 163 Sieve implementations are allowed to limit the total number of nested 164 included scripts, but MUST provide for a total of at least three 165 levels of nested scripts including the top-level script. An error 166 MUST be generated either when the script is uploaded to the Sieve 167 repository, or when the script is executed, if any nesting limit is 168 exceeded. If such an error is detected whilst processing a Sieve 169 script, an implicit "keep" action MUST be executed to prevent loss of 170 any messages. 172 Sieve implementations MUST ensure that recursive includes are not 173 possible. For example, if script "A" includes script "B", and script 174 "B" includes script "A" an error MUST be generated either when the 175 script is uploaded to the Sieve repository, or when the script is 176 executed. If such an error is detected whilst processing a Sieve 177 script, an implicit "keep" action MUST be executed to prevent loss of 178 any messages. 180 Sieve implementations MUST handle missing scripts being referenced 181 via an includes in an existing script. An error MUST be generated 182 when a missing included script is discovered during execution. If 183 such an error is detected an implicit "keep" action MUST be executed 184 to prevent loss of any messages. 186 If the Sieve "variables" extension [RFC5229] is present, an issue 187 arises with the "scope" of variables defined in scripts that may 188 include each other. For example, if a script defines the variable 189 "${status}" with one particular meaning or usage, and another defines 190 "${status}" with a different meaning, then if one script includes the 191 other there is an issue as to which "${status}" is being referenced. 192 To solve this problem, Sieve implementations MUST follow the scoping 193 rules defined in Section 3.4 and support the "global" command defined 194 there. 196 3.2. Control Structure include 198 Usage: include [LOCATION] [ONCE] 200 LOCATION = ":personal" / ":global" 202 ONCE = ":once" 204 The "include" command takes an optional "location" parameter, an 205 optional ":once" parameter, and a single string argument representing 206 the name of the script to include for processing at that point. 208 The "location" parameter MUST default to ":personal" if not 209 specified. The "location" has the following meanings: 211 :personal 212 Indicates that the named script is stored in the user's own 213 personal (private) Sieve repository. 214 :global 215 Indicates that the named script is stored in a site-wide Sieve 216 repository, accessible to all users of the Sieve system. 218 The ":once" parameter tells the interpreter only to include the Sieve 219 script if it has not already been included at any other point during 220 the script execution. If the script has already been included, 221 processing continues immediately following the include command. 223 Implementations MUST NOT generate an error if an "include :once" 224 command names a script whose inclusion would be recursive; in this 225 case, the script MUST be considered previously included and therefore 226 "include :once" will not include it again. 228 Note: It is RECOMMENDED that script authors / generators use this 229 parameter only when including a script that performs general duties 230 such as declaring global variables and making sanity checks of the 231 environment. 233 The included script MUST be a valid Sieve script, including having 234 necessary "require" statements for all optional capabilities used by 235 the script. The scope of a "require" statement in an included script 236 is for that script only, not the including script. For example, if 237 script "A" includes script "B", and script "B" uses the "fileinto" 238 extension, script "B" must have a "require" statement for "fileinto", 239 irrespective of whether script "A" has one. In addition, if script 240 "A" does not have a "require" statement for "fileinto", "fileinto" 241 cannot be used anywhere in script "A", even after inclusion of script 242 "B". 244 A "stop" command in an included script MUST stop all script 245 processing, including the processing of the scripts that include the 246 current one. The "return" command (described below) stops processing 247 of the current script only, and allows the scripts that include it to 248 continue. 250 Examples: 252 The user has four scripts stored in their personal repository: 254 "default" 256 This is the default active script that includes several others. 258 require ["include"]; 260 include :personal "always_allow"; 261 include :global "spam_tests"; 262 include :personal "spam_tests"; 263 include :personal "mailing_lists"; 265 Personal script "always_allow" 267 This script special cases some correspondent email addresses and 268 makes sure any message containing those addresses are always kept. 270 if header :is "From" "boss@example.com" 271 { 272 keep; 273 } 274 elsif header :is "From" "ceo@example.com" 275 { 276 keep; 277 } 279 Personal script "spam_tests" 281 This script does some user-specific spam tests to catch spam 282 messages not caught by the site-wide spam tests. 284 require ["reject"]; 286 if header :contains "Subject" "XXXX" 287 { 288 reject; 289 } 290 elsif header :is "From" "money@example.com" 291 { 292 reject; 293 } 295 Personal script "mailing_lists" 297 This script looks for messages from different mailing lists and 298 files each into a mailbox specific to the mailing list. 300 require ["fileinto"]; 302 if header :is "Sender" "owner-ietf-mta-filters@imc.org" 303 { 304 fileinto "lists.sieve"; 305 } 306 elsif header :is "Sender" "owner-ietf-imapext@imc.org" 307 { 308 fileinto "lists.imapext"; 309 } 311 There is one script stored in the global repository: 313 Site script "spam_tests" 315 This script does some site-wide spam tests which any user at the 316 site can include in their own scripts at a suitable point. The 317 script content is kept up to date by the site administrator. 319 require ["reject"]; 321 if anyof (header :contains "Subject" "$$", 322 header :contains "Subject" "Make money") 323 { 324 reject; 325 } 327 The "include" command may appear anywhere in the script where a 328 control structure is legal. 330 Example: 332 require ["include"]; 334 if anyof (header :contains "Subject" "$$", 335 header :contains "Subject" "Make money") 336 { 337 include "my_reject_script"; 338 } 340 3.3. Control Structure return 342 Usage: return 344 The "return" command stops processing of the currently included 345 script only and returns processing control to the script which 346 includes it. If used in the main script (i.e. not in an included 347 script), it has the same effect as the "stop" command, including the 348 appropriate "keep" action if no other actions have been executed up 349 to that point. 351 3.4. Interaction with Variables 353 In order to avoid problems of variables in an included script 354 "overwriting" those from the script that includes it, this 355 specification requires that all variables defined in a script MUST be 356 kept "private" to that script by default - i.e. they are not 357 "visible" to other scripts. This ensures that two script authors 358 cannot inadvertently cause problems by choosing the same name for a 359 variable. 361 However, sometimes there is a need to make a variable defined in one 362 script available to others. This specification defines the new 363 command "global" to declare that a variable is shared among scripts. 364 Effectively, two namespaces are defined: one local to the current 365 script, and another shared among all scripts. Implementations MUST 366 allow a non-global variable to have the same name as a global 367 variable but have no interaction between them. 369 3.4.1. Control Structure global 371 Usage: global 373 The "global" command contains a string list argument that defines one 374 or more names of variables to be stored in the global variable space. 376 The "global" command, if present, MUST be used immediately after any 377 "require" commands (at least one of which will be present listing the 378 "include" extension). Multiple "global" commands are allowed. An 379 error occurs if an "global" command appears after a command other 380 than "require" or "global". Use of the "global" command makes the 381 listed variables immediately available for use in the body of the 382 script that uses it. 384 If a "global" command lists a variable that has not been defined in 385 the global namespace, the name of the variable is nonetheless marked 386 as global, and any subsequent "set" command will set the value of the 387 variable in global scope. 389 Interpretation of a string containing a variable marked as global, 390 but without any value set, SHALL behave as any other access to an 391 unknown variable, as specified in Section 3 of [RFC5229] (that is, 392 the unknown variable reference evaltuates to an empty string). 394 Example: 396 require ["variables", "include"]; 397 global "test"; 398 global "test-mailbox"; 400 # The included script may contain repetitive code that is 401 # effectively a subroutine that can be factored out. 402 set "test" "$$" 403 include "spam_filter_script"; 405 set "test" "Make money" 406 include "spam_filter_script"; 408 # Message will be filed according to the test that matched last. 409 if string :count "${test-mailbox}" "1" 410 { 411 fileinto "INBOX${test-mailbox}"; 412 stop; 413 } 414 # If nothing matched, the message is implicitly kept. 416 Active script 418 require ["variables", "include"]; 419 global ["test", "test-mailbox"]; 421 if header :contains "Subject" "${test}" 422 { 423 set "test-mailbox" "spam-${test}; 424 } 426 spam_filter_script 428 3.4.2. Variables Namespace global 430 In addition to the "global" command, this document defines the 431 variables namespace "global", per [RFC5229], Section 3. 433 Example: 435 require ["variables", "include"]; 437 set "global.i_am_on_vacation" "1"; 439 [[[ Does it make sense to have this form instead of the "global" 440 command? Does it make sense to have both? If both, it would make 441 sense that the two syntaxes reference the same set of variables. By 442 way of example: 444 require ["variables", "include"]; 445 global "i_am_on_vacation"; 447 set "global.i_am_on_vacation" "1"; 449 if string :is "${i_am_on_vacation}" "1" 450 { 451 vacation "It's true, I am on vacation." 452 } 454 ]]] 456 4. Security Considerations 458 Sieve implementations MUST ensure adequate security for the global 459 script repository to prevent unauthorized changes to global scripts. 461 Beyond that, the "include" extension does not raise any security 462 considerations that are not present in the base Sieve protocol, and 463 these issues are discussed in Sieve. 465 5. IANA Considerations 467 The following template specifies the IANA registration of the Sieve 468 extension specified in this document: 470 5.1. "include" Extension Registration 472 Capability name: include 473 Description: add the "include" command to execute other Sieve 474 scripts. 475 RFC number: this RFC 476 Contact address: the Sieve discussion list 478 6. Normative References 480 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 481 Requirement Levels", BCP 14, RFC 2119, March 1997. 483 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 484 Language", RFC 5228, January 2008. 486 [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", 487 RFC 5229, January 2008. 489 Appendix A. Acknowledgments 491 Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz 492 and Kjetil Torgrim Homme for comments and corrections. 494 Authors' Addresses 496 Cyrus Daboo 498 Email: cyrus@daboo.name 500 Aaron Stone 502 Email: aaron@serendipity.palo-alto.ca.us