draft-ietf-sieve-include-02.txt   draft-ietf-sieve-include-03.txt 
Network Working Group C. Daboo Network Working Group C. Daboo
Internet-Draft A. Stone Internet-Draft A. Stone
Expires: November 5, 2009 May 4, 2009 Expires: January 30, 2010 July 29, 2009
Sieve Email Filtering: Include Extension Sieve Email Filtering: Include Extension
draft-ietf-sieve-include-02 draft-ietf-sieve-include-03
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79. This document may contain material provisions of BCP 78 and BCP 79. This document may contain material
from IETF Documents or IETF Contributions published or made publicly from IETF Documents or IETF Contributions published or made publicly
available before November 10, 2008. The person(s) controlling the available before November 10, 2008. The person(s) controlling the
copyright in some of this material may not have granted the IETF copyright in some of this material may not have granted the IETF
Trust the right to allow modifications of such material outside the Trust the right to allow modifications of such material outside the
IETF Standards Process. Without obtaining an adequate license from IETF Standards Process. Without obtaining an adequate license from
skipping to change at page 1, line 41 skipping to change at page 1, line 41
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on November 5, 2009. This Internet-Draft will expire on January 30, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents in effect on the date of Provisions Relating to IETF Documents in effect on the date of
publication of this document (http://trustee.ietf.org/license-info). publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
skipping to change at page 2, line 18 skipping to change at page 2, line 18
Abstract Abstract
The Sieve Email Filtering "include" extension permits users to The Sieve Email Filtering "include" extension permits users to
include one Sieve script inside another. This can make managing include one Sieve script inside another. This can make managing
large scripts or multiple sets of scripts much easier, and allows a 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 site and its users to build up libraries of scripts. Users are able
to include their own personal scripts or site-wide scripts. to include their own personal scripts or site-wide scripts.
Change History (to be removed prior to publication as an RFC) Change History (to be removed prior to publication as an RFC)
Changes from ietf-02 to ietf-03:
a. Setting a variable then calling global on it is an error
(something like 'use strict').
b. Specify that the 'global' keyword is only available when
'variables' has also been required.
c. Uploading a script that includes a nonexistent script is not an
error at upload time.
Changes from ietf-01 to ietf-02: Changes from ietf-01 to ietf-02:
a. Require that script names must be constant strings, not subject a. Require that script names must be constant strings, not subject
to variable expansion. to variable expansion.
b. Try the phrase immediate script instead of current script. b. Try the phrase immediate script instead of current script.
c. Clarify that "global 'varname'" and "global.varname" refer to the c. Clarify that "global 'varname'" and "global.varname" refer to the
same variable. same variable.
d. Drop the requirement the global keywords come after require and d. Drop the requirement the global keywords come after require and
before anything else. before anything else.
Changes from ietf-00 to ietf-01: Changes from ietf-00 to ietf-01:
a. Replaced import/export with global. a. Replaced import/export with global.
b. Added :once modifier to include. b. Added :once modifier to include.
c. Added global namespace to see if it holds water. c. Added global namespace to see if it holds water.
Changes from daboo-06 to ietf-00: Changes from daboo-06 to ietf-00:
a. None a. None
Changes from -05 to -06: Changes from -05 to -06:
a. Aaron Stone joins as author. a. Aaron Stone joins as author.
b. Removed | characters from the script examples. b. Removed | characters from the script examples.
c. Updated draft references to published RFCs. c. Updated draft references to published RFCs.
Changes from -04 to -05: Changes from -04 to -05:
a. Fixed examples. a. Fixed examples.
b. Relaxed requirement that imported/exported variables be set b. Relaxed requirement that imported/exported variables be set
before being used. before being used.
Changes from -03 to -04: Changes from -03 to -04:
a. Fixed missing 2119 definitions. a. Fixed missing 2119 definitions.
b. Defined interaction with variables through use of import and b. Defined interaction with variables through use of import and
export commands. export commands.
Changes from -02 to -03: Changes from -02 to -03:
a. Refreshing expired draft (updated for nits). a. Refreshing expired draft (updated for nits).
b. Syntax -> Usage. b. Syntax -> Usage.
c. Updated to 3028bis reference. c. Updated to 3028bis reference.
Changes from -01 to -02: Changes from -01 to -02:
a. Minor formatting changes only - refreshing expired draft. a. Minor formatting changes only - refreshing expired draft.
Changes from -00 to -01: Changes from -00 to -01:
a. Added IPR boiler plate. a. Added IPR boiler plate.
b. Re-ordered sections at start to conform to RFC style. b. Re-ordered sections at start to conform to RFC style.
c. Moved recursion comment into General Considerations section. c. Moved recursion comment into General Considerations section.
d. Switched to using optional parameter to indicate personal vs d. Switched to using optional parameter to indicate personal vs
global. global.
e. Explicitly state that an error occurs when a missing script is e. Explicitly state that an error occurs when a missing script is
included. included.
Table of Contents Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 5
2. Conventions Used in This Document . . . . . . . . . . . . . . 4 2. Conventions Used in This Document . . . . . . . . . . . . . . 5
3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 4 3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 5
3.1. General Considerations . . . . . . . . . . . . . . . . . . 4 3.1. General Considerations . . . . . . . . . . . . . . . . . . 5
3.2. Control Structure include . . . . . . . . . . . . . . . . 5 3.2. Control Structure include . . . . . . . . . . . . . . . . 6
3.3. Control Structure return . . . . . . . . . . . . . . . . . 8 3.3. Control Structure return . . . . . . . . . . . . . . . . . 10
3.4. Interaction with Variables . . . . . . . . . . . . . . . . 8 3.4. Interaction with Variables . . . . . . . . . . . . . . . . 10
3.4.1. Control Structure global . . . . . . . . . . . . . . . 9 3.4.1. Control Structure global . . . . . . . . . . . . . . . 10
3.4.2. Variables Namespace global . . . . . . . . . . . . . . 10 3.4.2. Variables Namespace global . . . . . . . . . . . . . . 12
4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
5.1. "include" Extension Registration . . . . . . . . . . . . . 11 5.1. "include" Extension Registration . . . . . . . . . . . . . 13
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.1. Normative References . . . . . . . . . . . . . . . . . . . 12 6.1. Normative References . . . . . . . . . . . . . . . . . . . 13
6.2. Informative References . . . . . . . . . . . . . . . . . . 12 6.2. Informative References . . . . . . . . . . . . . . . . . . 13
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 12 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13
1. Introduction and Overview 1. Introduction and Overview
It's convenient to be able to break SIEVE [RFC5228] scripts down into It's convenient to be able to break SIEVE [RFC5228] scripts down into
smaller components which can be reused in a variety of different smaller components which can be reused in a variety of different
circumstances. For example, users may want to have a default script circumstances. For example, users may want to have a default script
and a special 'vacation' script, the latter being activated when the and a special 'vacation' script, the latter being activated when the
user goes on vacation. In that case the default actions should user goes on vacation. In that case the default actions should
continue to be run, but a vacation command should be executed first. 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 One option is to edit the default script to add or remove the
skipping to change at page 4, line 26 skipping to change at page 5, line 26
script. script.
2. Conventions Used in This Document 2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
Conventions for notations are as in SIEVE [RFC5228] Section 1.1. Conventions for notations are as in SIEVE [RFC5228] Section 1.1.
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 message is delivered.
immediate script
the individual Sieve script file being executed.
including script
the individual Sieve script file that had an include statement
which included the immediate script.
3. Include Extension 3. Include Extension
3.1. General Considerations 3.1. General Considerations
Sieve implementations that implement the "include", "return", and Sieve implementations that implement the "include", "return", and
"global" commands described below have an identifier of "include" for "global" commands described below have an identifier of "include" for
use with the capability mechanism. If any of the "include", use with the capability mechanism. If any of the "include",
"return", or "global" commands are used in a script, the "include" "return", or "global" commands are used in a script, the "include"
capability MUST be listed in the "require" statement in that script. capability MUST be listed in the "require" statement in that script.
skipping to change at page 5, line 10 skipping to change at page 6, line 28
any messages. any messages.
Sieve implementations MUST ensure that recursive includes are not Sieve implementations MUST ensure that recursive includes are not
possible. For example, if script "A" includes script "B", and script possible. For example, if script "A" includes script "B", and script
"B" includes script "A" an error MUST be generated either when the "B" includes script "A" an error MUST be generated either when the
script is uploaded to the Sieve repository, or when the script is script is uploaded to the Sieve repository, or when the script is
executed. If such an error is detected whilst processing a Sieve executed. If such an error is detected whilst processing a Sieve
script, an implicit "keep" action MUST be executed to prevent loss of script, an implicit "keep" action MUST be executed to prevent loss of
any messages. any messages.
Sieve implementations MUST handle missing scripts being referenced Sieve implementations MUST generate an error at execution time if an
via an includes in an existing script. An error MUST be generated included script does not exist. Implementations MUST NOT generate
when a missing included script is discovered during execution. If errors for scripts missing at upload time, as this would force an
such an error is detected an implicit "keep" action MUST be executed upload ordering requirement upon script authors / generators.
to prevent loss of any messages.
If the Sieve "variables" extension [RFC5229] is present, an issue If the Sieve "variables" extension [RFC5229] is present, an issue
arises with the "scope" of variables defined in scripts that may arises with the "scope" of variables defined in scripts that may
include each other. For example, if a script defines the variable include each other. For example, if a script defines the variable
"${status}" with one particular meaning or usage, and another defines "${status}" with one particular meaning or usage, and another defines
"${status}" with a different meaning, then if one script includes the "${status}" with a different meaning, then if one script includes the
other there is an issue as to which "${status}" is being referenced. other there is an issue as to which "${status}" is being referenced.
To solve this problem, Sieve implementations MUST follow the scoping To solve this problem, Sieve implementations MUST follow the scoping
rules defined in Section 3.4 and support the "global" command defined rules defined in Section 3.4 and support the "global" command defined
there. there.
skipping to change at page 5, line 40 skipping to change at page 7, line 9
LOCATION = ":personal" / ":global" LOCATION = ":personal" / ":global"
ONCE = ":once" ONCE = ":once"
The "include" command takes an optional "location" parameter, an The "include" command takes an optional "location" parameter, an
optional ":once" parameter, and a single string argument representing optional ":once" parameter, and a single string argument representing
the name of the script to include for processing at that point. It the name of the script to include for processing at that point. It
is RECOMMENDED that implementations restrict script names according is RECOMMENDED that implementations restrict script names according
to [I-D.ietf-sieve-managesieve] Section 1.7. Implementations MUST to [I-D.ietf-sieve-managesieve] Section 1.7. Implementations MUST
NOT allow variables to be expanded into the names of Sieve scripts; NOT allow variables to be expanded into the names of Sieve scripts;
in other words, the value MUST be a constant string as defined in by in other words, the value MUST be a constant string as defined in
VARIABLES [RFC5229] Section 3. VARIABLES [RFC5229], Section 3.
The "location" parameter MUST default to ":personal" if not The "location" parameter MUST default to ":personal" if not
specified. The "location" has the following meanings: specified. The "location" has the following meanings:
:personal :personal
Indicates that the named script is stored in the user's own Indicates that the named script is stored in the user's own
personal (private) Sieve repository. personal (private) Sieve repository.
:global :global
Indicates that the named script is stored in a site-wide Sieve Indicates that the named script is stored in a site-wide Sieve
skipping to change at page 9, line 21 skipping to change at page 10, line 41
allow a non-global variable to have the same name as a global allow a non-global variable to have the same name as a global
variable but have no interaction between them. variable but have no interaction between them.
3.4.1. Control Structure global 3.4.1. Control Structure global
Usage: global <value: string-list> Usage: global <value: string-list>
The "global" command contains a string list argument that defines one The "global" command contains a string list argument that defines one
or more names of variables to be stored in the global variable space. or more names of variables to be stored in the global variable space.
If a "global" command is given the name of a variable that has been The "global" command is only available when the script has both
defined in the immediate script, any value stored in the global space "include" and "variables" in its require line. If the "global"
is overwritten with the value of the variable in the script. 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 If a "global" command lists a variable that has not been defined in
the global namespace, the name of the variable is nonetheless marked the global namespace, the name of the variable is now marked as
as global, and any subsequent "set" command will set the value of the global, and any subsequent "set" command will set the value of the
variable in global scope. variable in global scope.
Interpretation of a string containing a variable marked as global, Interpretation of a string containing a variable marked as global,
but without any value set, SHALL behave as any other access to an but without any value set, SHALL behave as any other access to an
unknown variable, as specified in Section 3 of [RFC5229] (that is, unknown variable, as specified in VARIABLES [RFC5229], Section 3
the unknown variable reference evaltuates to an empty string). (i.e., evaluates to an empty string).
Example: Example:
require ["variables", "include"]; require ["variables", "include"];
global "test"; global "test";
global "test-mailbox"; global "test-mailbox";
# The included script may contain repetitive code that is # The included script may contain repetitive code that is
# effectively a subroutine that can be factored out. # effectively a subroutine that can be factored out.
set "test" "$$" set "test" "$$"
skipping to change at page 10, line 41 skipping to change at page 12, line 8
if header :contains "Subject" "${test}" if header :contains "Subject" "${test}"
{ {
set "test-mailbox" "spam-${test}; set "test-mailbox" "spam-${test};
} }
spam_filter_script spam_filter_script
3.4.2. Variables Namespace global 3.4.2. Variables Namespace global
In addition to the "global" command, this document defines the In addition to the "global" command, this document defines the
variables namespace "global", per [RFC5229], Section 3. variables namespace "global", as specified in VARIABLES [RFC5229],
Section 3.
Example: Example:
require ["variables", "include"]; require ["variables", "include"];
set "global.i_am_on_vacation" "1"; set "global.i_am_on_vacation" "1";
Variables declared global and variables accessed via the global Variables declared global and variables accessed via the global
namespace MUST be one and the same. In the following example script, namespace MUST be one and the same. In the following example script,
we see the variable "i_am_on_vacation" used in a "global" command, we see the variable "i_am_on_vacation" used in a "global" command,
skipping to change at page 11, line 31 skipping to change at page 12, line 47
Sieve implementations MUST ensure adequate security for the global Sieve implementations MUST ensure adequate security for the global
script repository to prevent unauthorized changes to global scripts. script repository to prevent unauthorized changes to global scripts.
Sieve implementations MUST ensure that script names are checked for Sieve implementations MUST ensure that script names are checked for
validity and proper permissions prior to inclusion, in order to validity and proper permissions prior to inclusion, in order to
prevent a malicious user from gaining acess to files accessible to prevent a malicious user from gaining acess to files accessible to
the mail server software that should not be accessible to the user. the mail server software that should not be accessible to the user.
Beyond these, the "include" extension does not raise any security Beyond these, the "include" extension does not raise any security
considerations that are not present in the base SIEVE [RFC5228] considerations that are not present in the base SIEVE [RFC5228]
document. document and the VARIABLES [RFC5229] extension.
5. IANA Considerations 5. IANA Considerations
The following template specifies the IANA registration of the Sieve The following template specifies the IANA registration of the Sieve
extension specified in this document: extension specified in this document:
5.1. "include" Extension Registration 5.1. "include" Extension Registration
Capability name: include Capability name: include
Description: add the "include" command to execute other Sieve Description: adds the "include" command to execute other Sieve
scripts. scripts, and the "global" command and "global" variables
namespace to access variables shared among included scripts.
RFC number: this RFC RFC number: this RFC
Contact address: the Sieve discussion list <ietf-mta-filters@imc.org> Contact address: the Sieve discussion list <ietf-mta-filters@imc.org>
6. References 6. References
6.1. Normative References 6.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
skipping to change at page 12, line 26 skipping to change at page 13, line 42
6.2. Informative References 6.2. Informative References
[I-D.ietf-sieve-managesieve] [I-D.ietf-sieve-managesieve]
Martin, T. and A. Melnikov, "A Protocol for Remotely Martin, T. and A. Melnikov, "A Protocol for Remotely
Managing Sieve Scripts", draft-ietf-sieve-managesieve-09 Managing Sieve Scripts", draft-ietf-sieve-managesieve-09
(work in progress), January 2009. (work in progress), January 2009.
Appendix A. Acknowledgments Appendix A. Acknowledgments
Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz, Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz,
Kjetil Torgrim Homme, Stephan Bosch, and Arnt Gulbrandsen for Kjetil Torgrim Homme, Stephan Bosch, Arnt Gulbrandsen, Barry Leiba,
comments and corrections. and Jeffrey Hutzelman for comments and corrections.
Authors' Addresses Authors' Addresses
Cyrus Daboo Cyrus Daboo
Email: cyrus@daboo.name Email: cyrus@daboo.name
Aaron Stone Aaron Stone
Email: aaron@serendipity.palo-alto.ca.us Email: aaron@serendipity.cx
 End of changes. 39 change blocks. 
40 lines changed or deleted 99 lines changed or added

This html diff was produced by rfcdiff 1.35. The latest version is available from http://tools.ietf.org/tools/rfcdiff/