idnits 2.17.1 draft-daboo-sieve-include-00.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** There are 48 instances of lines with control characters in the document. ** The abstract seems to contain references ([SIEVE]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. 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 the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 (April 2003) is 7674 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) ** Obsolete normative reference: RFC 3028 (ref. 'SIEVE') (Obsoleted by RFC 5228, RFC 5429) Summary: 7 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group C. Daboo 2 Internet Draft: SIEVE Include Extension 3 Document: draft-daboo-sieve-include-00.txt April 2003 5 SIEVE Include Extension 7 Status of this Memo 9 This document is an Internet-Draft and is in full conformance with 10 all provisions of Section 10 of RFC2026. 12 Internet-Drafts are working documents of the Internet Engineering 13 Task Force (IETF), its areas, and its working groups. Note that 14 other groups may also distribute working documents as 15 Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six 18 months and may be updated, replaced, or obsoleted by other documents 19 at any time. It is inappropriate to use Internet-Drafts as 20 reference material or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt. 25 The list of Internet- Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html. 28 Copyright Notice 30 Copyright (C) The Internet Society 2003. All Rights Reserved. 32 Table of Contents 33 1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . 2 34 2 Conventions Used in This Document . . . . . . . . . . . . . . 2 35 3 Change History . . . . . . . . . . . . . . . . . . . . . . . 2 36 4 Open Issues: . . . . . . . . . . . . . . . . . . . . . . . . . 2 37 5 Introduction and Overview . . . . . . . . . . . . . . . . . . 2 38 6 SIEVE Include Extension . . . . . . . . . . . . . . . . . . . 3 39 6.1 General Considerations . . . . . . . . . . . . . . . . . 3 40 6.2 Control Structure Include . . . . . . . . . . . . . . . . 3 41 6.3 Control Structure Return . . . . . . . . . . . . . . . . 6 42 7 Security Considerations . . . . . . . . . . . . . . . . . . . 6 43 8 IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 44 8.1 include registration . . . . . . . . . . . . . . . . . . . 6 45 9 Normative References . . . . . . . . . . . . . . . . . . . . 7 46 10 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 7 47 11 Author's Address . . . . . . . . . . . . . . . . . . . . . . 7 48 12 Full Copyright Statement . . . . . . . . . . . . . . . . . . . 7 50 1 Abstract 52 The SIEVE [SIEVE] "include" extension permits users to include one 53 SIEVE script inside another. This can make managing large scripts 54 or multiple sets of scripts much easier, as well as supporting 55 common 'libraries' of scripts. Users are able to include their own 56 personal scripts or site-wide scripts provided by the local SIEVE 57 implementation. 59 2 Conventions Used in This Document 61 Conventions for notations are as in [SIEVE] section 1.1, including 62 use of [KEYWORDS]. 64 3 Change History 66 Initial Document 68 4 Open Issues: 70 1 Should we allow URIs to point to scripts to include? 71 2 Should we allow string lists as argument to include? 72 3 How should non-exist include scripts be handled? 73 4 Interaction with variables? 75 5 Introduction and Overview 77 Its convenient to be able to break SIEVE scripts down into smaller 78 components which can be reused in a variety of different 79 circumstances. For example, users may want to have a default script 80 and a special 'vacation' script, the later being activated when the 81 user goes on vacation. In that case the default actions should 82 continue to be run, but a vacation command should be executed first. 84 One option is to edit the default script to add or remove the 85 vacation command as needed. Another is to have a vacation script 86 that simply has a vacation command and then includes the default 87 script. 89 6 SIEVE Include Extension 91 6.1 General Considerations 93 SIEVE implementations that implement the "include" and "return" 94 control structures described below have an identifier of "include" 95 for use with the capability mechanism. If either of the "include" 96 or "return" control structures are used in a script, the "include" 97 capability MUST be listed in the "require" statement in that script. 99 SIEVE implementations must track the use of actions in included 100 scripts so that implicit "keep" behaviour can be properly determined 101 based on whether any actions have executed in any script. 103 SIEVE implementations are allowed to limit the total number of 104 nested included scripts, but MUST provide for a total of at least 105 three levels of nested scripts including the top-level script. An 106 error MUST be generated either when the script is uploaded to the 107 SIEVE repository, or when the script is executed, if any nesting 108 limit is exceeded. If such an error is detected whilst processing a 109 SIEVE script, an implicit "keep" action MUST be executed to prevent 110 loss of any messages. 112 6.2 Control Structure Include 114 Syntax: include 116 The "include" control structure includes a single string argument 117 representing the name of the script to include in the main script at 118 that point. 120 The script name contains one of two prefixes: 122 "/personal/" 123 Indicates that the named script is stored in the user's own 124 personal (private) SIEVE repository. 126 "/global/" 127 Indicates that the named script is stored in a site-wide 128 SIEVE repository, accessible to all users of the SIEVE 129 system. 131 The second component of the name represents an implementation 132 dependent script name. 134 The included script MUST be a valid SIEVE script, including having 135 necessary "require" statements for all optional capabilities used by 136 the script. The scope of a "require" statement in an included 137 script is for that script only, not the including script. e.g. if 138 script "A" includes script "B", and script "B" uses the "fileinto" 139 extension, script "B" must have a "require" statement for 140 "fileinto", irrespective of whether script "A" has one. In 141 addition, if script "A" does not have a "require" statement for 142 "fileinto", "fileinto" cannot be used anywhere in script "A", even 143 after inclusion of script "B". 145 A "stop" control statement in an included script MUST stop all 146 script processing, including the processing of the scripts that 147 include the current one. The "return" control statement (described 148 below) stops processing of the current script only, and allows the 149 scripts that include it to continue. 151 Examples: 153 In the example below, script content is indicated by a '|' as the 154 first non-space character on a line for clarity. The '|' characters 155 are not part of the script itself. 157 The user has four scripts stored in their personal repository: 159 "default" 161 This is the default active script that includes several others. 163 | require ["include"]; 164 | 165 | include "/personal/always_allow"; 166 | include "/global/spam_tests"; 167 | include "/personal/my_spam_tests"; 168 | include "/personal/mailing_lists"; 170 "always_allow" 172 This script special cases some correspondent email addresses and 173 makes sure any message containing those addresses are always 174 kept. 176 | if header :is "From" "boss@example.com" 177 | { 178 | keep; 179 | } 180 | elsif header :is "From" "ceo@example.com" 181 | { 182 | keep; 183 | } 184 "my_spam_tests" 186 This script does some user-specific spam tests to catch spam 187 messages not caught by the site-wide spam tests. 189 | require ["reject"]; 190 | 191 | if header :contains "Subject" "XXXX" 192 | { 193 | reject; 194 | } 195 | elsif header :is "From" "money@example.com" 196 | { 197 | reject; 198 | } 200 "mailing_lists" 202 This script looks for messages from different mailing lists and 203 files each into a mailbox specific to the mailing list. 205 | require ["fileinto"]; 206 | 207 | if header :is "Sender" "owner-ietf-mta-filters@imc.org" 208 | { 209 | fileinto "lists.sieve"; 210 | } 211 | elsif header :is "Sender" "owner-ietf-imapext@imc.org" 212 | { 213 | fileinto "lists.imapext"; 214 | } 216 There is one script stored in the global repository: 218 "spam_tests" 220 This script does some site-wide spam tests which any user at the 221 site can include in their own scripts at a suitable point. The 222 script content is kept up to date by the site administrator. 224 | require ["reject"]; 225 | 226 | if anyof (header :contains "Subject" "$$", 227 | header :contains "Subject" "Make money") 228 | { 229 | reject; 230 | } 232 The "include" control structure may appear anywhere in the script 233 where a control structure is legal. 235 Example: 237 | require ["include"]; 238 | 239 | if anyof (header :contains "Subject" "$$", 240 | header :contains "Subject" "Make money") 241 | { 242 | include "my_reject_script"; 243 | } 245 6.3 Control Structure Return 247 Syntax: return 249 The "return" control structure stops processing of the currently 250 included script only and returns processing control to the script 251 which includes it. If used in the main script (i.e. not in an 252 included script), it has the same effect as the "stop" control 253 structure, including the appropriate "keep" action if no other 254 actions have been executed up to that point. 256 7 Security Considerations 258 SIEVE implementations MUST ensure that recursive includes are not 259 possible. i.e. if script "A" includes script "B", and script "B" 260 includes script "A" an error MUST be generated either when the 261 script is uploaded to the SIEVE repository, or when the script is 262 executed. If such an error is detected whilst processing a SIEVE 263 script, an implicit "keep" action MUST be executed to prevent loss 264 of any messages. 266 SIEVE implementations MUST ensure adequate security for the global 267 script repository to prevent unauthorized changes to global scripts. 269 Beyond that, the "include" extension does not raise any security 270 considerations that are not present in the base [SIEVE] protocol, 271 and these issues are discussed in [SIEVE]. 273 8 IANA Considerations 275 The following template specifies the IANA registration of the Sieve 276 extension specified in this document: 278 8.1 include registration 280 To: iana@iana.org 281 Subject: Registration of new Sieve extension 283 Capability name: include 284 Capability keyword: include 285 Capability arguments: N/A 286 Standards Track/IESG-approved experimental RFC number: this RFC 287 Person and email address to contact for further information: 289 Cyrus Daboo 290 Cyrusoft International, Inc. 291 Suite 780, 5001 Baum Blvd. 292 Pittsburgh, PA 15213 293 U.S.A. 295 Email: daboo@cyrusoft.com 297 This information should be added to the list of sieve extensions 298 given on http://www.iana.org/assignments/sieve-extensions. 300 9 Normative References 302 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate 303 Requirement Levels", RFC 2119, March 1997. 305 [SIEVE] Showalter, "Sieve: A Mail Filtering Language", RFC 3028, 306 January 2001. 308 10 Acknowledgments 310 Thanks to Ken Murchison and Rob Siemborski for comments and 311 suggestions. 313 11 Author's Address 315 Cyrus Daboo 316 Cyrusoft International, Inc. 317 Suite 780, 5001 Baum Blvd. 318 Pittsburgh, PA 15213 319 U.S.A. 321 Email: daboo@cyrusoft.com 323 12 Full Copyright Statement 325 Copyright (C) The Internet Society 2003. All Rights Reserved. 327 This document and translations of it may be copied and furnished to 328 others, and derivative works that comment on or otherwise explain it 329 or assist in its implementation may be prepared, copied, published 330 and distributed, in whole or in part, without restriction of any 331 kind, provided that the above copyright notice and this paragraph 332 are included on all such copies and derivative works. However, this 333 document itself may not be modified in any way, such as by removing 334 the copyright notice or references to the Internet Society or other 335 Internet organizations, except as needed for the purpose of 336 developing Internet standards in which case the procedures for 337 copyrights defined in the Internet Standards process must be 338 followed, or as required to translate it into languages other than 339 English. 341 The limited permissions granted above are perpetual and will not be 342 revoked by the Internet Society or its successors or assigns. 344 This document and the information contained herein is provided on an 345 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 346 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 347 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 348 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 349 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.