idnits 2.17.1 draft-ietf-sieve-include-00.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 23, 2009) is 5513 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). 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 24, 2009 March 23, 2009 6 Sieve Email Filtering: Include Extension 7 draft-ietf-sieve-include-00 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 24, 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, as well as 58 supporting common 'libraries' of scripts. Users are able to include 59 their own personal scripts or site-wide scripts provided by the local 60 Sieve implementation. 62 Change History (to be removed prior to publication as an RFC) 64 Changes from daboo-06 to ietf-00: 65 a. None 67 Changes from -05 to -06: 68 a. Aaron Stone joins as author. 69 b. Removed | characters from the script examples. 70 c. Updated draft references to published RFCs. 72 Changes from -04 to -05: 73 a. Fixed examples. 74 b. Relaxed requirement that imported/exported variables be set 75 before being used. 77 Changes from -03 to -04: 78 a. Fixed missing 2119 definitions. 79 b. Defined interaction with variables through use of import and 80 export commands. 82 Changes from -02 to -03: 83 a. Refreshing expired draft (updated for nits). 84 b. Syntax -> Usage. 85 c. Updated to 3028bis reference. 87 Changes from -01 to -02: 88 a. Minor formatting changes only - refreshing expired draft. 90 Changes from -00 to -01: 91 a. Added IPR boiler plate. 92 b. Re-ordered sections at start to conform to RFC style. 93 c. Moved recursion comment into General Considerations section. 94 d. Switched to using optional parameter to indicate personal vs 95 global. 97 e. Explicitly state that an error occurs when a missing script is 98 included. 100 Open Issues (to be resolved prior to publication as an RFC) 102 a. Interaction with variables (scoping). Should variables be 103 carried over between scripts that are included? Or should 104 variables defined in an included script be local to that script 105 only? 107 Table of Contents 109 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4 110 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 111 3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 4 112 3.1. General Considerations . . . . . . . . . . . . . . . . . . 4 113 3.2. Control Structure Include . . . . . . . . . . . . . . . . 5 114 3.3. Control Structure Return . . . . . . . . . . . . . . . . . 8 115 3.4. Interaction with Variables . . . . . . . . . . . . . . . . 8 116 3.4.1. Control Structure Import . . . . . . . . . . . . . . . 8 117 3.4.2. Control Structure Export . . . . . . . . . . . . . . . 9 118 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 119 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 120 5.1. "include" Extension Registration . . . . . . . . . . . . . 10 121 6. Normative References . . . . . . . . . . . . . . . . . . . . . 11 122 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 11 123 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 125 1. Introduction and Overview 127 Its convenient to be able to break SIEVE [RFC5228] scripts down into 128 smaller components which can be reused in a variety of different 129 circumstances. For example, users may want to have a default script 130 and a special 'vacation' script, the later being activated when the 131 user goes on vacation. In that case the default actions should 132 continue to be run, but a vacation command should be executed first. 133 One option is to edit the default script to add or remove the 134 vacation command as needed. Another is to have a vacation script 135 that simply has a vacation command and then includes the default 136 script. 138 2. Conventions Used in This Document 140 Conventions for notations are as in SIEVE [RFC5228] Section 1.1. 142 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 143 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 144 document are to be interpreted as described in [RFC2119]. 146 3. Include Extension 148 3.1. General Considerations 150 Sieve implementations that implement the "include", "return", 151 "export" and "import" commands described below have an identifier of 152 "include" for use with the capability mechanism. If any of the 153 "include", "return", "export" or "import" commands are used in a 154 script, the "include" capability MUST be listed in the "require" 155 statement in that script. 157 Sieve implementations must track the use of actions in included 158 scripts so that implicit "keep" behavior can be properly determined 159 based on whether any actions have executed in any script. 161 Sieve implementations are allowed to limit the total number of nested 162 included scripts, but MUST provide for a total of at least three 163 levels of nested scripts including the top-level script. An error 164 MUST be generated either when the script is uploaded to the Sieve 165 repository, or when the script is executed, if any nesting limit is 166 exceeded. If such an error is detected whilst processing a Sieve 167 script, an implicit "keep" action MUST be executed to prevent loss of 168 any messages. 170 Sieve implementations MUST ensure that recursive includes are not 171 possible. i.e. if script "A" includes script "B", and script "B" 172 includes script "A" an error MUST be generated either when the script 173 is uploaded to the Sieve repository, or when the script is executed. 174 If such an error is detected whilst processing a Sieve script, an 175 implicit "keep" action MUST be executed to prevent loss of any 176 messages. 178 Sieve implementations MUST handle missing scripts being referenced 179 via an includes in an existing script. An error MUST be generated 180 when a missing included script is discovered during execution. If 181 such an error is detected an implicit "keep" action MUST be executed 182 to prevent loss of any messages. 184 If the Sieve "variables" extension [RFC5229] is present, an issue 185 arises with the "scope" of variables defined in scripts that may 186 include each other. For example, if a script defines the variable 187 "${status}" with one particular meaning or usage, and another defines 188 "${status}" with a different meaning, then if one script includes the 189 other there is an issue as to which "${status}" is being referenced. 190 To solve this problem, Sieve implementations MUST follow the scoping 191 rules defined in Section 3.4 and support the "import" and "export" 192 commands defined there. 194 3.2. Control Structure Include 196 Usage: include [] 198 LOCATION = ":personal" / ":global" 200 The "include" command includes an optional "location" parameter, and 201 a single string argument representing the name of the script to 202 include in the main script at that point. 204 The "location" parameter defaults to ":personal" if not specified. 205 The "location" has the following meanings: 207 :personal 209 Indicates that the named script is stored in the user's own 210 personal (private) Sieve repository. 212 :global 214 Indicates that the named script is stored in a site-wide Sieve 215 repository, accessible to all users of the Sieve system. 217 The included script MUST be a valid Sieve script, including having 218 necessary "require" statements for all optional capabilities used by 219 the script. The scope of a "require" statement in an included script 220 is for that script only, not the including script. e.g. if script "A" 221 includes script "B", and script "B" uses the "fileinto" extension, 222 script "B" must have a "require" statement for "fileinto", 223 irrespective of whether script "A" has one. In addition, if script 224 "A" does not have a "require" statement for "fileinto", "fileinto" 225 cannot be used anywhere in script "A", even after inclusion of script 226 "B". 228 A "stop" command in an included script MUST stop all script 229 processing, including the processing of the scripts that include the 230 current one. The "return" command (described below) stops processing 231 of the current script only, and allows the scripts that include it to 232 continue. 234 Examples: 236 The user has four scripts stored in their personal repository: 238 "default" 240 This is the default active script that includes several others. 242 require ["include"]; 244 include :personal "always_allow"; 245 include :global "spam_tests"; 246 include :personal "my_spam_tests"; 247 include :personal "mailing_lists"; 249 "always_allow" 251 This script special cases some correspondent email addresses and 252 makes sure any message containing those addresses are always kept. 254 if header :is "From" "boss@example.com" 255 { 256 keep; 257 } 258 elsif header :is "From" "ceo@example.com" 259 { 260 keep; 261 } 263 "my_spam_tests" 264 This script does some user-specific spam tests to catch spam 265 messages not caught by the site-wide spam tests. 267 require ["reject"]; 269 if header :contains "Subject" "XXXX" 270 { 271 reject; 272 } 273 elsif header :is "From" "money@example.com" 274 { 275 reject; 276 } 278 "mailing_lists" 280 This script looks for messages from different mailing lists and 281 files each into a mailbox specific to the mailing list. 283 require ["fileinto"]; 285 if header :is "Sender" "owner-ietf-mta-filters@imc.org" 286 { 287 fileinto "lists.sieve"; 288 } 289 elsif header :is "Sender" "owner-ietf-imapext@imc.org" 290 { 291 fileinto "lists.imapext"; 292 } 294 There is one script stored in the global repository: 296 "spam_tests" 298 This script does some site-wide spam tests which any user at the 299 site can include in their own scripts at a suitable point. The 300 script content is kept up to date by the site administrator. 302 require ["reject"]; 304 if anyof (header :contains "Subject" "$$", 305 header :contains "Subject" "Make money") 306 { 307 reject; 308 } 310 The "include" command may appear anywhere in the script where a 311 control structure is legal. 313 Example: 315 require ["include"]; 317 if anyof (header :contains "Subject" "$$", 318 header :contains "Subject" "Make money") 319 { 320 include "my_reject_script"; 321 } 323 3.3. Control Structure Return 325 Usage: return 327 The "return" command stops processing of the currently included 328 script only and returns processing control to the script which 329 includes it. If used in the main script (i.e. not in an included 330 script), it has the same effect as the "stop" command, including the 331 appropriate "keep" action if no other actions have been executed up 332 to that point. 334 3.4. Interaction with Variables 336 In order to avoid problems of variables in an included script 337 "overwriting" those from the script that includes it, this 338 specification requires that all variables defined in a script MUST be 339 kept "private" to that script by default - i.e. they are not 340 "visible" to other scripts. This ensures that two script authors 341 cannot inadvertently cause problems by choosing the same name for a 342 variable. 344 However, sometimes there is a need to make a variable defined in one 345 script available to others. This specification defines the new 346 commands "export" and "import" to alter the default behavior of 347 variable scoping to allow variables to be "seen" by other scripts. 348 The "export" command takes a list of variable names defined in a 349 script and makes those available to any script that explicitly wants 350 to use them. The "import" command allows a script to gain access to 351 variables that have been explicitly made available by other scripts. 352 The explicit use of "export and "import", coupled with the default 353 behavior of variables only having local scope, ensures that multiple 354 scripts cannot inadvertently overwrite each others variables. 356 3.4.1. Control Structure Import 358 Usage: import 360 The "import" command contains a string list argument that defines one 361 or more names of variables exported by other scripts which should be 362 made available to the current script. 364 The "import" command, if present, MUST be used immediately after any 365 "require" commands (at least one of which will be present listing the 366 "include" extension). Multiple "import" commands are allowed. An 367 error occurs if an "import" command appears after a command other 368 than "require" or "import". Use of the "import" command makes the 369 listed variables immediately available for use in the body of the 370 script that uses it. 372 If an "import" command lists a variable that has not been exported by 373 any other script at that point during the Sieve execution process, 374 then an error MUST occur. 376 Example: 378 require ["variables", "fileinto", "include"]; 379 import "test"; 381 if header :contains "Subject" "${test}" 382 { 383 fileinto "INBOX.spam-${test}; 384 } 386 3.4.2. Control Structure Export 388 Usage: export 390 The "export" command contains a string list argument that defines one 391 or more names of variables defined in the current script which should 392 be made available to any scripts that run during the current Sieve 393 script execution process. 395 The "export" command, if present, MUST be used immediately after any 396 "require" or "import" commands. Multiple "export" commands are 397 allowed. An error occurs if an "export" command appears after a 398 command other than "require", "import" or "export". 400 An error occurs if an "export" command lists a variable that is 401 listed in an "import" command preceding it in the current script. 403 Example: 405 require ["variables", "include"]; 406 export "test"; 408 set "test" "$$" 409 include "spam_filter_script"; 411 set "test" "Make money" 412 include "spam_filter_script"; 414 Example: 416 require ["variables", "include"]; 417 import "test"; 418 export "test-mailbox"; 420 if header :contains "Subject" "${test}" 421 { 422 set "test-mailbox" "INBOX.spam-${test}; 423 include "fileinto-script" 424 } 426 4. Security Considerations 428 Sieve implementations MUST ensure adequate security for the global 429 script repository to prevent unauthorized changes to global scripts. 431 Beyond that, the "include" extension does not raise any security 432 considerations that are not present in the base Sieve protocol, and 433 these issues are discussed in Sieve. 435 5. IANA Considerations 437 The following template specifies the IANA registration of the Sieve 438 extension specified in this document: 440 5.1. "include" Extension Registration 442 Capability name: include 443 Description: add the "include" command to execute other Sieve 444 scripts. 445 RFC number: this RFC 446 Contact address: the Sieve discussion list 448 6. Normative References 450 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 451 Requirement Levels", BCP 14, RFC 2119, March 1997. 453 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering 454 Language", RFC 5228, January 2008. 456 [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", 457 RFC 5229, January 2008. 459 Appendix A. Acknowledgments 461 Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz 462 and Kjetil Torgrim Homme for comments and corrections. 464 Authors' Addresses 466 Cyrus Daboo 468 Email: cyrus@daboo.name 470 Aaron Stone 472 Email: aaron@serendipity.palo-alto.ca.us