idnits 2.17.1 draft-daboo-sieve-include-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 14. -- Found old boilerplate from RFC 3978, Section 5.5 on line 506. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 483. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 490. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 496. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. 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 RFC 3978 Section 5.4 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 25, 2006) is 6508 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) == Missing Reference: 'LOCATION' is mentioned on line 183, but not defined == Outdated reference: A later version (-13) exists of draft-ietf-sieve-3028bis-06 Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Daboo 3 Internet-Draft June 25, 2006 4 Expires: December 27, 2006 6 SIEVE Email Filtering: Include Extension 7 draft-daboo-sieve-include-05 9 Status of this Memo 11 By submitting this Internet-Draft, each author represents that any 12 applicable patent or other IPR claims of which he or she is aware 13 have been or will be disclosed, and any of which he or she becomes 14 aware will be disclosed, in accordance with Section 6 of BCP 79. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on December 27, 2006. 34 Copyright Notice 36 Copyright (C) The Internet Society (2006). 38 Abstract 40 The SIEVE Email Filtering "include" extension permits users to 41 include one SIEVE script inside another. This can make managing 42 large scripts or multiple sets of scripts much easier, as well as 43 supporting common 'libraries' of scripts. Users are able to include 44 their own personal scripts or site-wide scripts provided by the local 45 SIEVE implementation. 47 Change History (to be removed prior to publication as an RFC) 48 Changes from -04 to -05: 49 a. Fixed examples. 50 b. Relaxed requirement that imported/exported variables be set 51 before being used. 53 Changes from -03 to -04: 54 a. Fixed missing 2119 definitions. 55 b. Defined interaction with variables through use of import and 56 export commands. 58 Changes from -02 to -03: 59 a. Refreshing expired draft (updated for nits). 60 b. Syntax -> Usage. 61 c. Updated to 3028bis reference. 63 Changes from -01 to -02: 64 a. Minor formatting changes only - refreshing expired draft. 66 Changes from -00 to -01: 67 a. Added IPR boiler plate. 68 b. Re-ordered sections at start to conform to RFC style. 69 c. Moved recursion comment into General Considerations section. 70 d. Switched to using optional parameter to indicate personal vs 71 global. 72 e. Explicitly state that an error occurs when a missing script is 73 included. 75 Open Issues (to be resolved prior to publication as an RFC) 77 a. Interaction with variables (scoping). Should variables be 78 carried over between scripts that are included? Or should 79 variables defined in an included script be local to that script 80 only? 82 Table of Contents 84 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4 85 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 86 3. SIEVE Include Extension . . . . . . . . . . . . . . . . . . . 4 87 3.1. General Considerations . . . . . . . . . . . . . . . . . . 4 88 3.2. Control Structure Include . . . . . . . . . . . . . . . . 5 89 3.3. Control Structure Return . . . . . . . . . . . . . . . . . 8 90 3.4. Interaction with Variables . . . . . . . . . . . . . . . . 8 91 3.4.1. Control Structure Import . . . . . . . . . . . . . . . 9 92 3.4.2. Control Structure Export . . . . . . . . . . . . . . . 9 93 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 94 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 95 5.1. include registration . . . . . . . . . . . . . . . . . . . 11 96 6. Normative References . . . . . . . . . . . . . . . . . . . . . 11 97 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 11 98 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 99 Intellectual Property and Copyright Statements . . . . . . . . . . 13 101 1. Introduction and Overview 103 Its convenient to be able to break SIEVE [I-D.ietf-sieve-3028bis] 104 scripts down into smaller components which can be reused in a variety 105 of different circumstances. For example, users may want to have a 106 default script and a special 'vacation' script, the later being 107 activated when the user goes on vacation. In that case the default 108 actions should continue to be run, but a vacation command should be 109 executed first. One option is to edit the default script to add or 110 remove the vacation command as needed. Another is to have a vacation 111 script that simply has a vacation command and then includes the 112 default script. 114 2. Conventions Used in This Document 116 Conventions for notations are as in SIEVE [I-D.ietf-sieve-3028bis] 117 section 1.1. 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 121 document are to be interpreted as described in [RFC2119]. 123 3. SIEVE Include Extension 125 3.1. General Considerations 127 SIEVE implementations that implement the "include", "return", 128 "export" and "import" commands described below have an identifier of 129 "include" for use with the capability mechanism. If any of the 130 "include", "return", "export" or "import" commands are used in a 131 script, the "include" capability MUST be listed in the "require" 132 statement in that script. 134 SIEVE implementations must track the use of actions in included 135 scripts so that implicit "keep" behavior can be properly determined 136 based on whether any actions have executed in any script. 138 SIEVE implementations are allowed to limit the total number of nested 139 included scripts, but MUST provide for a total of at least three 140 levels of nested scripts including the top-level script. An error 141 MUST be generated either when the script is uploaded to the SIEVE 142 repository, or when the script is executed, if any nesting limit is 143 exceeded. If such an error is detected whilst processing a SIEVE 144 script, an implicit "keep" action MUST be executed to prevent loss of 145 any messages. 147 SIEVE implementations MUST ensure that recursive includes are not 148 possible. i.e. if script "A" includes script "B", and script "B" 149 includes script "A" an error MUST be generated either when the script 150 is uploaded to the SIEVE repository, or when the script is executed. 151 If such an error is detected whilst processing a SIEVE script, an 152 implicit "keep" action MUST be executed to prevent loss of any 153 messages. 155 SIEVE implementations MUST handle missing scripts being referenced 156 via an includes in an existing script. An error MUST be generated 157 when a missing included script is discovered during execution. If 158 such an error is detected an implicit "keep" action MUST be executed 159 to prevent loss of any messages. 161 If the SIEVE "variables" extension [I-D.ietf-sieve-variables] is 162 present, an issue arises with the "scope" of variables defined in 163 scripts that may include each other. For example, if a script 164 defines the variable "${status}" with one particular meaning or 165 usage, and another defines "${status}" with a different meaning, then 166 if one script includes the other there is an issue as to which 167 "${status}" is being referenced. To solve this problem, SIEVE 168 implementations MUST follow the scoping rules defined in Section 3.4 169 and support the "import" and "export" commands defined there. 171 3.2. Control Structure Include 173 Usage: include [LOCATION] 175 The "include" command includes an optional parameter, and a single 176 string argument representing the name of the script to include in the 177 main script at that point. 179 [LOCATION] is an optional parameter that has one of two values: 181 Usage: ":personal" / ":global" 183 If the [LOCATION] parameter is not present, the location defaults to 184 :personal. 186 The location has the following meanings: 188 :personal 190 Indicates that the named script is stored in the user's own 191 personal (private) SIEVE repository. 193 :global 195 Indicates that the named script is stored in a site-wide SIEVE 196 repository, accessible to all users of the SIEVE system. 198 The included script MUST be a valid SIEVE script, including having 199 necessary "require" statements for all optional capabilities used by 200 the script. The scope of a "require" statement in an included script 201 is for that script only, not the including script. e.g. if script "A" 202 includes script "B", and script "B" uses the "fileinto" extension, 203 script "B" must have a "require" statement for "fileinto", 204 irrespective of whether script "A" has one. In addition, if script 205 "A" does not have a "require" statement for "fileinto", "fileinto" 206 cannot be used anywhere in script "A", even after inclusion of script 207 "B". 209 A "stop" command in an included script MUST stop all script 210 processing, including the processing of the scripts that include the 211 current one. The "return" command (described below) stops processing 212 of the current script only, and allows the scripts that include it to 213 continue. 215 Examples: 217 In the examples below, script content is indicated by a '|' as the 218 first non-space character on a line for clarity. The '|' characters 219 are not part of the script itself. 221 The user has four scripts stored in their personal repository: 223 "default" 225 This is the default active script that includes several others. 227 | require ["include"]; 228 | 229 | include :personal "always_allow"; 230 | include :global "spam_tests"; 231 | include :personal "my_spam_tests"; 232 | include :personal "mailing_lists"; 234 "always_allow" 236 This script special cases some correspondent email addresses and 237 makes sure any message containing those addresses are always kept. 239 | if header :is "From" "boss@example.com" 240 | { 241 | keep; 242 | } 243 | elsif header :is "From" "ceo@example.com" 244 | { 245 | keep; 246 | } 248 "my_spam_tests" 250 This script does some user-specific spam tests to catch spam 251 messages not caught by the site-wide spam tests. 253 | require ["reject"]; 254 | 255 | if header :contains "Subject" "XXXX" 256 | { 257 | reject; 258 | } 259 | elsif header :is "From" "money@example.com" 260 | { 261 | reject; 262 | } 264 "mailing_lists" 266 This script looks for messages from different mailing lists and 267 files each into a mailbox specific to the mailing list. 269 | require ["fileinto"]; 270 | 271 | if header :is "Sender" "owner-ietf-mta-filters@imc.org" 272 | { 273 | fileinto "lists.sieve"; 274 | } 275 | elsif header :is "Sender" "owner-ietf-imapext@imc.org" 276 | { 277 | fileinto "lists.imapext"; 278 | } 280 There is one script stored in the global repository: 282 "spam_tests" 284 This script does some site-wide spam tests which any user at the 285 site can include in their own scripts at a suitable point. The 286 script content is kept up to date by the site administrator. 288 | require ["reject"]; 289 | 290 | if anyof (header :contains "Subject" "$$", 291 | header :contains "Subject" "Make money") 292 | { 293 | reject; 294 | } 296 The "include" command may appear anywhere in the script where a 297 control structure is legal. 299 Example: 301 | require ["include"]; 302 | 303 | if anyof (header :contains "Subject" "$$", 304 | header :contains "Subject" "Make money") 305 | { 306 | include "my_reject_script"; 307 | } 309 3.3. Control Structure Return 311 Usage: return 313 The "return" command stops processing of the currently included 314 script only and returns processing control to the script which 315 includes it. If used in the main script (i.e. not in an included 316 script), it has the same effect as the "stop" command, including the 317 appropriate "keep" action if no other actions have been executed up 318 to that point. 320 3.4. Interaction with Variables 322 In order to avoid problems of variables in an included script 323 "overwriting" those from the script that includes it, this 324 specification requires that all variables defined in a script MUST be 325 kept "private" to that script by default - i.e. they are not 326 "visible" to other scripts. This ensures that two script authors 327 cannot inadvertently cause problems by choosing the same name for a 328 variable. 330 However, sometimes there is a need to make a variable defined in one 331 script available to others. This specification defines the new 332 commands "export" and "import" to alter the default behavior of 333 variable scoping to allow variables to be "seen" by other scripts. 334 The "export" command takes a list of variable names defined in a 335 script and makes those available to any script that explicitly wants 336 to use them. The "import" command allows a script to gain access to 337 variables that have been explicitly made available by other scripts. 338 The explicit use of "export and "import", coupled with the default 339 behavior of variables only having local scope, ensures that multiple 340 scripts cannot inadvertently overwrite each others variables. 342 3.4.1. Control Structure Import 344 Usage: import 346 The "import" command contains a string list argument that defines one 347 or more variables names of variables exported by other scripts which 348 should be made available to the current script. 350 The "import" command, if present, MUST be used immediately after any 351 "require" commands (at least one of which will be present listing the 352 "include" extension). Multiple "import" commands are allowed. An 353 error occurs if an "import" command appears after a command other 354 than "require" or "import". Use of the "import" command makes the 355 listed variables immediately available for use in the body of the 356 script that uses it. 358 If an "import" command lists a variable that has not been exported by 359 any other script at that point during the SIEVE execution process, 360 then an error MUST occur. 362 Example: 364 | require ["variables", "fileinto", "include"]; 365 | import "test"; 366 | 367 | if header :contains "Subject" "${test}" 368 | { 369 | fileinto "INBOX.spam-${test}; 370 | } 372 3.4.2. Control Structure Export 374 Usage: export 376 The "export" command contains a string list argument that defines one 377 or more variables names of variables defined in the current script 378 which should be made available to any scripts that run during the 379 current SIEVE script execution process. 381 The "export" command, if present, MUST be used immediately after any 382 "require" or "import" commands. Multiple "export" commands are 383 allowed. An error occurs if an "export" command appears after a 384 command other than "require", "import" or "export". 386 An error occurs if an "export" command lists a variable that is 387 listed in an "import" command preceding it in the current script. 389 Example: 391 | require ["variables", "include"]; 392 | export "test"; 393 | 394 | set "test" "$$" 395 | include "spam_filter_script"; 396 | 397 | set "test" "Make money" 398 | include "spam_filter_script"; 400 Example: 402 | require ["variables", "include"]; 403 | import "test"; 404 | export "test-mailbox"; 405 | 406 | if header :contains "Subject" "${test}" 407 | { 408 | set "test-mailbox" "INBOX.spam-${test}; 409 | include "fileinto-script" 410 | } 412 4. Security Considerations 414 SIEVE implementations MUST ensure adequate security for the global 415 script repository to prevent unauthorized changes to global scripts. 417 Beyond that, the "include" extension does not raise any security 418 considerations that are not present in the base SIEVE protocol, and 419 these issues are discussed in SIEVE. 421 5. IANA Considerations 423 The following template specifies the IANA registration of the Sieve 424 extension specified in this document: 426 5.1. include registration 428 To: iana@iana.org 429 Subject: Registration of new Sieve extension 431 Capability name: include 432 Capability keyword: include 433 Capability arguments: N/A 434 Standards Track/IESG-approved experimental RFC number: this RFC 435 Person and email address to contact for further information: 437 Cyrus Daboo 439 441 This information should be added to the list of sieve extensions 442 given on http://www.iana.org/assignments/sieve-extensions. 444 This information should be added to the list of sieve extensions 445 given on http://www.iana.org/assignments/sieve-extensions. 447 6. Normative References 449 [I-D.ietf-sieve-3028bis] 450 Showalter, T. and P. Guenther, "Sieve: An Email Filtering 451 Language", draft-ietf-sieve-3028bis-06 (work in progress), 452 March 2006. 454 [I-D.ietf-sieve-variables] 455 Homme, K., "Sieve Extension: Variables", 456 draft-ietf-sieve-variables-08 (work in progress), 457 December 2005. 459 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 460 Requirement Levels", BCP 14, RFC 2119, March 1997. 462 Appendix A. Acknowledgments 464 Thanks to Aaron Stone, Ken Murchison, Rob Siemborski, Alexey 465 Melnikov, Marc Mutz and Kjetil Torgrim Homme for comments and 466 corrections. 468 Author's Address 470 Cyrus Daboo 472 Email: cyrus@daboo.name 474 Intellectual Property Statement 476 The IETF takes no position regarding the validity or scope of any 477 Intellectual Property Rights or other rights that might be claimed to 478 pertain to the implementation or use of the technology described in 479 this document or the extent to which any license under such rights 480 might or might not be available; nor does it represent that it has 481 made any independent effort to identify any such rights. Information 482 on the procedures with respect to rights in RFC documents can be 483 found in BCP 78 and BCP 79. 485 Copies of IPR disclosures made to the IETF Secretariat and any 486 assurances of licenses to be made available, or the result of an 487 attempt made to obtain a general license or permission for the use of 488 such proprietary rights by implementers or users of this 489 specification can be obtained from the IETF on-line IPR repository at 490 http://www.ietf.org/ipr. 492 The IETF invites any interested party to bring to its attention any 493 copyrights, patents or patent applications, or other proprietary 494 rights that may cover technology that may be required to implement 495 this standard. Please address the information to the IETF at 496 ietf-ipr@ietf.org. 498 Disclaimer of Validity 500 This document and the information contained herein are provided on an 501 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 502 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 503 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 504 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 505 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 506 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 508 Copyright Statement 510 Copyright (C) The Internet Society (2006). This document is subject 511 to the rights, licenses and restrictions contained in BCP 78, and 512 except as set forth therein, the authors retain all their rights. 514 Acknowledgment 516 Funding for the RFC Editor function is currently provided by the 517 Internet Society.