summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc6609.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc6609.txt')
-rw-r--r--doc/rfc/rfc6609.txt787
1 files changed, 787 insertions, 0 deletions
diff --git a/doc/rfc/rfc6609.txt b/doc/rfc/rfc6609.txt
new file mode 100644
index 0000000..08620a5
--- /dev/null
+++ b/doc/rfc/rfc6609.txt
@@ -0,0 +1,787 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) C. Daboo
+Request for Comments: 6609 Apple, Inc.
+Category: Standards Track A. Stone
+ISSN: 2070-1721 Serendipity
+ May 2012
+
+
+ Sieve Email Filtering: Include Extension
+
+Abstract
+
+ The Sieve Email Filtering "include" extension permits users to
+ include one Sieve script inside another. This can make managing
+ large scripts or multiple sets of scripts much easier, and allows a
+ site and its users to build up libraries of scripts. Users are able
+ to include their own personal scripts or site-wide scripts.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc6609.
+
+Copyright Notice
+
+ Copyright (c) 2012 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+
+
+
+
+
+Daboo & Stone Standards Track [Page 1]
+
+RFC 6609 Sieve Extension: Include May 2012
+
+
+Table of Contents
+
+ 1. Introduction and Overview .......................................2
+ 2. Conventions Used in This Document ...............................2
+ 3. Include Extension ...............................................3
+ 3.1. General Considerations .....................................3
+ 3.2. Control Structure "include" ................................4
+ 3.3. Control Structure "return" .................................7
+ 3.4. Interaction with the "variables" Extension .................8
+ 3.4.1. Control Structure "global" ..........................8
+ 3.4.2. Variables Namespace global .........................10
+ 3.5. Interaction with Other Extensions .........................11
+ 4. Security Considerations ........................................12
+ 5. IANA Considerations ............................................12
+ 6. References .....................................................13
+ 6.1. Normative References ......................................13
+ 6.2. Informative References ....................................13
+ Appendix A. Acknowledgments .......................................14
+
+1. Introduction and Overview
+
+ It's convenient to be able to break Sieve [RFC5228] scripts down into
+ smaller components that can be reused in a variety of different
+ circumstances. For example, users may want to have a default script
+ and a special 'vacation' script, the latter being activated when the
+ user goes on vacation. In that case, the default actions should
+ continue to be run, but a vacation command should be executed first.
+ One option is to edit the default script to add or remove the
+ vacation command as needed. Another is to have a vacation script
+ that simply has a vacation command and then includes the default
+ script.
+
+ This document defines the Sieve Email Filtering "include" extension,
+ which permits users to include one Sieve script inside another.
+
+2. Conventions Used in This Document
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [RFC2119].
+
+ Conventions for notations are as in Sieve [RFC5228], Section 1.1.
+
+
+
+
+
+
+
+
+
+Daboo & Stone Standards Track [Page 2]
+
+RFC 6609 Sieve Extension: Include May 2012
+
+
+ The following key phrases are used to describe scripts and script
+ execution:
+
+ script
+ a valid Sieve script.
+
+ script execution
+ an instance of a Sieve interpreter invoked for a given message
+ delivery, starting with the user's active script and continuing
+ through any included scripts until the final disposition of the
+ message (e.g., delivered, forwarded, discarded, rejected, etc.).
+
+ immediate script
+ the individual Sieve script file being executed.
+
+ including script
+ the individual Sieve script file that had an include statement
+ that included the immediate script.
+
+3. Include Extension
+
+3.1. General Considerations
+
+ Sieve implementations that implement the "include", "return", and
+ "global" commands described below have an identifier of "include" for
+ use with the capability mechanism. If any of the "include",
+ "return", or "global" commands are used in a script, the "include"
+ capability MUST be listed in the "require" statement in that script.
+
+ Sieve implementations need to track the use of actions in included
+ scripts so that implicit "keep" behavior can be properly determined
+ based on whether any actions have executed in any script.
+
+ Sieve implementations are allowed to limit the total number of nested
+ included scripts, but MUST provide for a total of at least three
+ levels of nested scripts including the top-level script. An error
+ MUST be generated either when the script is uploaded to the Sieve
+ repository, or when the script is executed, if any nesting limit is
+ exceeded. If such an error is detected whilst processing a Sieve
+ script, an implicit "keep" action MUST be executed to prevent loss of
+ any messages.
+
+ Sieve implementations MUST NOT allow recursive script inclusion.
+ Both direct recursion, where script A includes script A (itself), and
+ indirect recursion, where script A includes script B which includes
+ script A once again, are prohibited.
+
+
+
+
+
+Daboo & Stone Standards Track [Page 3]
+
+RFC 6609 Sieve Extension: Include May 2012
+
+
+ Sieve implementations MUST generate an error at execution time if an
+ included script is a recursive inclusion. Implementations MUST NOT
+ generate errors for recursive includes at upload time, as this would
+ force an upload ordering requirement upon script authors and
+ generators.
+
+ Sieve implementations MUST generate an error at execution time if an
+ included script does not exist, except when the ":optional" parameter
+ is specified. Implementations MUST NOT generate errors for scripts
+ missing at upload time, as this would force an upload ordering
+ requirement upon script authors and generators.
+
+ If the Sieve "variables" extension [RFC5229] is present, an issue
+ arises with the "scope" of variables defined in scripts that may
+ include each other. For example, if a script defines the variable
+ "${status}" with one particular meaning or usage, and another defines
+ "${status}" with a different meaning, then if one script includes the
+ other there is an issue as to which "${status}" is being referenced.
+ To solve this problem, Sieve implementations MUST follow the scoping
+ rules defined in Section 3.4 and support the "global" command defined
+ there.
+
+3.2. Control Structure "include"
+
+ Usage: include [LOCATION] [":once"] [":optional"] <value: string>
+
+ LOCATION = ":personal" / ":global"
+
+ The "include" command takes an optional "location" parameter, an
+ optional ":once" parameter, an optional ":optional" parameter, and a
+ single string argument representing the name of the script to include
+ for processing at that point. Implementations MUST restrict script
+ names according to ManageSieve [RFC5804], Section 1.6. The script
+ name argument MUST be a constant string as defined in [RFC5229],
+ Section 3; implementations MUST NOT expand variables in the script
+ name argument.
+
+ The "location" parameter MUST default to ":personal" if not
+ specified. The "location" parameter MUST NOT be specified more than
+ once. The "location" has the following meanings:
+
+ :personal
+ Indicates that the named script is stored in the user's own
+ personal (private) Sieve repository.
+
+ :global
+ Indicates that the named script is stored in a site-wide Sieve
+ repository, accessible to all users of the Sieve system.
+
+
+
+Daboo & Stone Standards Track [Page 4]
+
+RFC 6609 Sieve Extension: Include May 2012
+
+
+ The ":once" parameter tells the interpreter only to include the named
+ script if it has not already been included at any other point during
+ script execution. If the script has already been included,
+ processing continues immediately following the "include" command.
+ Implementations MUST NOT generate an error if an "include :once"
+ command names a script whose inclusion would be recursive; in this
+ case, the script MUST be considered previously included, and
+ therefore "include :once" will not include it again.
+
+ Note: It is RECOMMENDED that script authors and generators use the
+ ":once" parameter only when including a script that performs general
+ duties such as declaring global variables and making sanity checks of
+ the environment.
+
+ The ":optional" parameter indicates that the script may be missing.
+ Ordinarily, an implementation MUST generate an error during execution
+ if an "include" command specifies a script that does not exist. When
+ ":optional" is specified, implementations MUST NOT generate an error
+ for a missing script, and MUST continue as if the "include" command
+ had not been present.
+
+ The included script MUST be a valid Sieve script. Implementations
+ MUST validate that each script has its own "require" statements for
+ all optional capabilities used by that script. The scope of a
+ "require" statement is the script in which it immediately appears,
+ and neither inherits nor passes on capabilities to other scripts
+ during the course of execution.
+
+ A "stop" command in an included script MUST stop all script
+ processing, including the processing of the scripts that include the
+ immediate one. The "return" command (described below) stops
+ processing of the immediate script only, and allows the scripts that
+ include it to continue.
+
+ The "include" command MAY appear anywhere in a script where a control
+ structure is legal, and MAY be used within another control structure,
+ e.g., an "if" block.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Stone Standards Track [Page 5]
+
+RFC 6609 Sieve Extension: Include May 2012
+
+
+ Examples:
+
+ The user has four scripts stored in their personal repository:
+
+ "default"
+
+ This is the default active script that includes several others.
+
+ require ["include"];
+
+ include :personal "always_allow";
+ include :global "spam_tests";
+ include :personal "spam_tests";
+ include :personal "mailing_lists";
+
+ Personal script "always_allow"
+
+ This script special-cases some correspondent email addresses and
+ makes sure any message containing those addresses is always kept.
+
+ if address :is "from" "boss@example.com"
+ {
+ keep;
+ }
+ elsif address :is "from" "ceo@example.com"
+ {
+ keep;
+ }
+
+ Personal script "spam_tests" (uses "reject" [RFC5429])
+
+ This script does some user-specific spam tests to catch spam
+ messages not caught by the site-wide spam tests.
+
+ require ["reject"];
+
+ if header :contains "Subject" "XXXX"
+ {
+ reject "Subject XXXX is unacceptable.";
+ }
+ elsif address :is "from" "money@example.com"
+ {
+ reject "Mail from this sender is unwelcome.";
+ }
+
+
+
+
+
+
+
+Daboo & Stone Standards Track [Page 6]
+
+RFC 6609 Sieve Extension: Include May 2012
+
+
+ Personal script "mailing_lists"
+
+ This script looks for messages from different mailing lists and
+ files each into a mailbox specific to the mailing list.
+
+ require ["fileinto"];
+
+ if header :is "List-ID" "sieve.ietf.org"
+ {
+ fileinto "lists.sieve";
+ }
+ elsif header :is "List-ID" "ietf-imapext.imc.org"
+ {
+ fileinto "lists.imapext";
+ }
+
+ There is one script stored in the global repository:
+
+ Site script "spam_tests" (uses "reject" [RFC5429])
+
+ This script does some site-wide spam tests that any user at the
+ site can include in their own scripts at a suitable point. The
+ script content is kept up to date by the site administrator.
+
+ require ["reject"];
+
+ if anyof (header :contains "Subject" "$$",
+ header :contains "Subject" "Make money")
+ {
+ reject "No thank you.";
+ }
+
+3.3. Control Structure "return"
+
+ Usage: return
+
+ The "return" command stops processing of the immediately included
+ script only and returns processing control to the script that
+ includes it. If used in the main script (i.e., not in an included
+ script), it has the same effect as the "stop" command, including the
+ appropriate "keep" action if no other actions have been executed up
+ to that point.
+
+
+
+
+
+
+
+
+
+Daboo & Stone Standards Track [Page 7]
+
+RFC 6609 Sieve Extension: Include May 2012
+
+
+3.4. Interaction with the "variables" Extension
+
+ In order to avoid problems of variables in an included script
+ "overwriting" those from the script that includes it, this
+ specification requires that all variables defined in a script MUST be
+ kept "private" to the immediate script by default -- that is, they
+ are not "visible" to other scripts. This ensures that two script
+ authors cannot inadvertently cause problems by choosing the same name
+ for a variable.
+
+ However, sometimes there is a need to make a variable defined in one
+ script available to others. This specification defines the new
+ command "global" to declare that a variable is shared among scripts.
+ Effectively, two namespaces are defined: one local to the immediate
+ script, and another shared among all scripts. Implementations MUST
+ allow a non-global variable to have the same name as a global
+ variable but have no interaction between them.
+
+3.4.1. Control Structure "global"
+
+ Usage: global <value: string-list>
+
+ The "global" command accepts a string list argument that defines one
+ or more names of variables to be stored in the global variable space.
+ Each name MUST be a constant string and conform to the syntax of
+ variable-name as defined in the "variables" extension document
+ [RFC5229], Section 3. Match variables cannot be specified, and
+ namespace prefixes are not allowed. An invalid name MUST be detected
+ as a syntax error.
+
+ The "global" command is only available when the script has both
+ "include" and "variables" in its require line. If the "global"
+ command appears when only "include" or only "variables" has been
+ required, an error MUST be generated when the script is uploaded.
+
+ If a "global" command is given the name of a variable that has
+ previously been defined in the immediate script with "set", an error
+ MUST be generated either when the script is uploaded or at execution
+ time.
+
+ If a "global" command lists a variable that has not been defined in
+ the "global" namespace, the name of the variable is now marked as
+ global, and any subsequent "set" command will set the value of the
+ variable in global scope.
+
+
+
+
+
+
+
+Daboo & Stone Standards Track [Page 8]
+
+RFC 6609 Sieve Extension: Include May 2012
+
+
+ A variable has global scope in all scripts that have declared it with
+ the "global" command. If a script uses that variable name without
+ declaring it global, the name specifies a separate, non-global
+ variable within that script.
+
+ Interpretation of a string containing a variable marked as global,
+ but without any value set, SHALL behave as any other access to an
+ unknown variable, as specified in the "variables" extension document
+ [RFC5229], Section 3 (i.e., evaluates to an empty string).
+
+ Example:
+
+ The active script
+
+ The included script may contain repetitive code that is
+ effectively a subroutine that can be factored out. In this
+ script, the test that matches last will leave its value in the
+ test_mailbox variable, and the top-level script will file the
+ message into that mailbox. If no tests matched, the message will
+ be implicitly kept in the INBOX.
+
+ require ["fileinto", "include", "variables", "relational"];
+ global "test";
+ global "test_mailbox";
+
+ set "test" "$$";
+ include "subject_tests";
+
+ set "test" "Make money";
+ include "subject_tests";
+
+ if string :count "eq" "${test_mailbox}" "1"
+ {
+ fileinto "${test_mailbox}";
+ stop;
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Stone Standards Track [Page 9]
+
+RFC 6609 Sieve Extension: Include May 2012
+
+
+ Personal script "subject_tests"
+
+ This script performs a number of tests against the message, sets
+ the global test_mailbox variable with a folder to file the message
+ into, and then falls back to the top-level script.
+
+
+ require ["include", "variables"];
+ global ["test", "test_mailbox"];
+
+ if header :contains "Subject" "${test}"
+ {
+ set "test_mailbox" "spam-${test}";
+ }
+
+3.4.2. Variables Namespace global
+
+ In addition to the "global" command, this document defines the
+ variables namespace "global", in accordance with the "variables"
+ extension document [RFC5229], Section 3. The "global" namespace has
+ no sub-namespaces (e.g., 'set "global.data.from" "me@example.com";'
+ is not allowed). The variable-name part MUST be a valid identifier
+ (e.g., 'set "global.12" "value";' is not valid because "12" is not a
+ valid identifier).
+
+ Note that the "variables" extension document [RFC5229], Section 3
+ suggests that extensions should define a namespace that is the same
+ as its capability string (in this case, "include" rather than
+ "global"). Nevertheless, references to the "global" namespace
+ without a prior require statement for the "include" extension MUST
+ cause an error.
+
+ Example:
+
+ require ["variables", "include"];
+
+ set "global.i_am_on_vacation" "1";
+
+ Variables declared global and variables accessed via the "global"
+ namespace MUST each be one and the same. In the following example
+ script, we see the variable "i_am_on_vacation" used in a "global"
+ command, and again with the "global" namespace. Consider these as
+ two syntaxes with identical meaning.
+
+
+
+
+
+
+
+
+Daboo & Stone Standards Track [Page 10]
+
+RFC 6609 Sieve Extension: Include May 2012
+
+
+ Example:
+
+ require ["variables", "include", "vacation"];
+ global "i_am_on_vacation";
+
+ set "global.i_am_on_vacation" "1";
+
+ if string :is "${i_am_on_vacation}" "1"
+ {
+ vacation "It's true, I am on vacation.";
+ }
+
+3.5. Interaction with Other Extensions
+
+ When "include" is used with the "editheader" extension [RFC5293], any
+ changes made to headers in a script MUST be propagated both to and
+ from included scripts. By way of example, if a script deletes one
+ header and adds another, then includes a second script, the included
+ script MUST NOT see the removed header, and MUST see the added
+ header. Likewise, if the included script adds or removes a header,
+ upon returning to the including script, subsequent actions MUST see
+ the added headers and MUST NOT see the removed headers.
+
+ When "include" is used with the MIME extension [RFC5703]
+ "foreverypart" control structure, the included script MUST be
+ presented with the current MIME part as though it were the entire
+ message. A script SHALL NOT have any special control over the
+ control structure it was included from. The "break" command in an
+ included script is not valid on its own and may not terminate a
+ "foreverypart" iteration in another script. The included script can
+ use "return" to transfer control back to the including script. A
+ global variable can be used to convey results to the including
+ script. A "stop" in an included script, even within a "foreverypart"
+ loop, still halts all script execution, per Section 3.2.
+
+ When "include" is used with the "reject" extension [RFC5429], calling
+ "reject" or "ereject" at any time sets the reject action on the
+ message, and continues script execution. Apropos of the MIME
+ extension, if an included script sees only a portion of the message
+ and calls a reject, it is the entire message and not the single MIME
+ part that carries the rejection.
+
+
+
+
+
+
+
+
+
+
+Daboo & Stone Standards Track [Page 11]
+
+RFC 6609 Sieve Extension: Include May 2012
+
+
+4. Security Considerations
+
+ Sieve implementations MUST ensure adequate security for the global
+ script repository to prevent unauthorized changes to global scripts.
+ For example, a site policy might enable only certain users with
+ administrative privileges to modify the global scripts. Sites are
+ advised against allowing all users to have write access to the sites'
+ global scripts.
+
+ Sieve implementations MUST ensure that script names are checked for
+ validity and proper permissions prior to inclusion, in order to
+ prevent a malicious user from gaining access to files accessible to
+ the mail server software that should not be accessible to the user.
+
+ Sieve implementations MUST ensure that script names are safe for use
+ with their storage system. An error MUST be generated either when
+ the script is uploaded or at execution time for a script including a
+ name that could be used as a vector to attack the storage system. By
+ way of example, the following include commands should be considered
+ hostile: 'include "./../..//etc/passwd"', 'include "foo$(`rm
+ star`)"'.
+
+ Beyond these, the "include" extension does not raise any security
+ considerations that are not discussed in the base Sieve [RFC5228]
+ document and the "variables" extension document [RFC5229].
+
+5. IANA Considerations
+
+ The following template specifies the IANA registration of the Sieve
+ extension specified in this document:
+
+ To: iana@iana.org
+ Subject: Registration of new Sieve extension
+
+ Capability name: include
+ Description: adds the "include" command to execute other Sieve
+ scripts, the "return" action from an included
+ script, and the "global" command and "global"
+ variables namespace to access variables shared
+ among included scripts.
+ RFC number: this RFC
+ Contact address: the Sieve discussion list <sieve@ietf.org>
+
+ This information has been added to IANA's "Sieve Extensions" registry
+ (http://www.iana.org).
+
+
+
+
+
+
+Daboo & Stone Standards Track [Page 12]
+
+RFC 6609 Sieve Extension: Include May 2012
+
+
+6. References
+
+6.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC5228] Guenther, P., Ed., and T. Showalter, Ed., "Sieve: An Email
+ Filtering Language", RFC 5228, January 2008.
+
+ [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension",
+ RFC 5229, January 2008.
+
+ [RFC5804] Melnikov, A., Ed., and T. Martin, "A Protocol for Remotely
+ Managing Sieve Scripts", RFC 5804, July 2010.
+
+6.2. Informative References
+
+ [RFC5293] Degener, J. and P. Guenther, "Sieve Email Filtering:
+ Editheader Extension", RFC 5293, August 2008.
+
+ [RFC5429] Stone, A., Ed., "Sieve Email Filtering: Reject and
+ Extended Reject Extensions", RFC 5429, March 2009.
+
+ [RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part
+ Tests, Iteration, Extraction, Replacement, and Enclosure",
+ RFC 5703, October 2009.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Stone Standards Track [Page 13]
+
+RFC 6609 Sieve Extension: Include May 2012
+
+
+Appendix A. Acknowledgments
+
+ Thanks to Stephan Bosch, Ned Freed, Arnt Gulbrandsen, Tony Hansen,
+ Kjetil Torgrim Homme, Jeffrey Hutzelman, Barry Leiba, Alexey
+ Melnikov, Ken Murchison, Marc Mutz, and Rob Siemborski, for comments
+ and corrections.
+
+Authors' Addresses
+
+ Cyrus Daboo
+ Apple Inc.
+ 1 Infinite Loop
+ Cupertino, CA 95014
+ USA
+
+ EMail: cyrus@daboo.name
+ URI: http://www.apple.com/
+
+
+ Aaron Stone
+ Serendipity
+ 1817 California St. #104
+ San Francisco, CA 94109
+ USA
+
+ EMail: aaron@serendipity.cx
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Stone Standards Track [Page 14]
+