draft-ietf-sieve-include-10.txt   draft-ietf-sieve-include-11.txt 
Network Working Group C. Daboo Network Working Group C. Daboo
Internet-Draft A. Stone Internet-Draft A. Stone
Intended status: Standards Track July 10, 2011 Intended status: Standards Track September 23, 2011
Expires: January 11, 2012 Expires: March 26, 2012
Sieve Email Filtering: Include Extension Sieve Email Filtering: Include Extension
draft-ietf-sieve-include-10 draft-ietf-sieve-include-11
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.
Status of this Memo Status of this Memo
skipping to change at page 1, line 34 skipping to change at page 1, line 34
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
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."
This Internet-Draft will expire on January 11, 2012. This Internet-Draft will expire on March 26, 2012.
Copyright Notice Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the Copyright (c) 2011 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 Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
2. Conventions Used in This Document . . . . . . . . . . . . . . 3 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 3 3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 4
3.1. General Considerations . . . . . . . . . . . . . . . . . . 3 3.1. General Considerations . . . . . . . . . . . . . . . . . . 4
3.2. Control Structure include . . . . . . . . . . . . . . . . 4 3.2. Control Structure include . . . . . . . . . . . . . . . . 5
3.3. Control Structure return . . . . . . . . . . . . . . . . . 8 3.3. Control Structure return . . . . . . . . . . . . . . . . . 8
3.4. Interaction with Variables . . . . . . . . . . . . . . . . 8 3.4. Interaction with Variables . . . . . . . . . . . . . . . . 8
3.4.1. Control Structure global . . . . . . . . . . . . . . . 8 3.4.1. Control Structure global . . . . . . . . . . . . . . . 8
3.4.2. Variables Namespace global . . . . . . . . . . . . . . 10 3.4.2. Variables Namespace global . . . . . . . . . . . . . . 10
4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
5.1. "include" Extension Registration . . . . . . . . . . . . . 11 5.1. "include" Extension Registration . . . . . . . . . . . . . 12
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1. Normative References . . . . . . . . . . . . . . . . . . . 11 6.1. Normative References . . . . . . . . . . . . . . . . . . . 12
6.2. Informative References . . . . . . . . . . . . . . . . . . 12 6.2. Informative References . . . . . . . . . . . . . . . . . . 12
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 12 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 12
Appendix B. Change History (to be removed prior to Appendix B. Change History (to be removed prior to
publication as an RFC) . . . . . . . . . . . . . . . 12 publication as an RFC) . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15
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
skipping to change at page 3, line 35 skipping to change at page 3, line 35
The following key phrases are used to describe scripts and script The following key phrases are used to describe scripts and script
execution: execution:
script script
a valid Sieve script. a valid Sieve script.
script execution script execution
an instance of a Sieve interpreter invoked for a given message an instance of a Sieve interpreter invoked for a given message
delivery, starting with the user's active script and continuing delivery, starting with the user's active script and continuing
through any included scripts until the message is delivered. through any included scripts until the message is delivered,
rejected, or otherwise processed. 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 immediate script
the individual Sieve script file being executed. the individual Sieve script file being executed.
including script including script
the individual Sieve script file that had an include statement the individual Sieve script file that had an include statement
which included the immediate script. which included the immediate script.
3. Include Extension 3. Include Extension
skipping to change at page 4, line 33 skipping to change at page 4, line 41
MANAGESIEVE [RFC5804] or similar mechanisms. Implementations MUST MANAGESIEVE [RFC5804] or similar mechanisms. Implementations MUST
NOT generate errors for recursive inclusions at upload time, as this NOT generate errors for recursive inclusions at upload time, as this
would force an upload ordering requirement upon script authors / would force an upload ordering requirement upon script authors /
generators. However, if an active script is replaced with a faulty generators. However, if an active script is replaced with a faulty
script and would remain the active script, an error MUST be generated script and would remain the active script, an error MUST be generated
and the upload MUST fail. If an include recursion error is detected and the upload MUST fail. If an include recursion error is detected
during script execution, an implicit "keep" action MUST be executed during script execution, an implicit "keep" action MUST be executed
to prevent loss of any messages. to prevent loss of any messages.
Sieve implementations MUST generate an error at execution time if an Sieve implementations MUST generate an error at execution time if an
included script does not exist. Implementations MUST NOT generate included script does not exist, except when the ":optional" parameter
errors for scripts missing at upload time, as this would force an is specified. Implementations MUST NOT generate errors for scripts
upload ordering requirement upon script authors / generators. missing at upload time, as this would force an upload ordering
requirement upon script authors / generators.
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.
3.2. Control Structure include 3.2. Control Structure include
Usage: include *[PARAMETERS] <value: string> Usage: include [LOCATION] [":once"] [":optional"] <value: string>
PARAMETERS = LOCATION / :once / :optional
LOCATION = :personal / :global LOCATION = ":personal" / ":global"
The "include" command takes an optional "location" parameter, an The "include" command takes an optional "location" parameter, an
optional ":once" parameter, an optional ":optional" parameter, and a optional ":once" parameter, an optional ":optional" parameter, and a
single string argument representing the name of the script to include single string argument representing the name of the script to include
for processing at that point. It is RECOMMENDED that implementations for processing at that point. Implementations MUST restrict script
restrict script names according to MANAGESIEVE [RFC5804] Section 1.7. names according to MANAGESIEVE [RFC5804], Section 1.6. The script
Implementations MUST NOT allow variables to be expanded into the name argument MUST be a constant string as defined in VARIABLES
names of Sieve scripts; in other words, the value MUST be a constant [RFC5229], Section 3; implementations MUST NOT allow variable
string as defined in VARIABLES [RFC5229], Section 3. expansion in the script name argument.
The "location" parameter MUST default to ":personal" if not The "location" parameter MUST default to ":personal" if not
specified. The "location" parameter MUST NOT be specified more than specified. The "location" parameter MUST NOT be specified more than
once. The "location" has the following meanings: once. 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
skipping to change at page 10, line 4 skipping to change at page 10, line 22
set "test" "Make money"; set "test" "Make money";
include "spam_checks"; include "spam_checks";
if string :count "eq" "${test_mailbox}" "1" if string :count "eq" "${test_mailbox}" "1"
{ {
fileinto "${test_mailbox}"; fileinto "${test_mailbox}";
stop; stop;
} }
Personal script "spam_checks" Personal script "spam_checks"
This script is makes a number of tests against the message,
falling through back to the top-level script having set the global
test_mailbox variable with a target folder to file the message
into.
require ["include", "variables"]; This script performs a number of tests against the message, sets
global ["test", "test_mailbox"]; the global test_mailbox variable with a folder to file the message
into, then falls back to the top-level script.
require ["include", "variables"]; global
["test", "test_mailbox"];
if header :contains "Subject" "${test}" if header :contains "Subject" "${test}"
{ {
set "test_mailbox" "spam-${test}"; set "test_mailbox" "spam-${test}";
} }
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", as specified in VARIABLES [RFC5229], variables namespace "global", as specified in VARIABLES [RFC5229],
skipping to change at page 11, line 16 skipping to change at page 11, line 30
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.
For example, a site policy might enable only certain users with For example, a site policy might enable only certain users with
administrative privileges to modify the global scripts. Site are administrative privileges to modify the global scripts. Site are
advised against allowing all users to have write access to the site's advised against allowing all users to have write access to the site's
global scripts. 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 access 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 and the VARIABLES [RFC5229] extension. 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: adds the "include" command to execute other Sieve Description: adds the "include" command to execute other Sieve
scripts, and the "global" command and "global" scripts, the "return" action from an included script,
variables namespace to access variables shared and the "global" command and "global" variables namespace
among included scripts. to access variables shared among included scripts.
RFC number: this RFC RFC number: this RFC
Contact address: the Sieve discussion list <sieve@ietf.org> Contact address: the Sieve discussion list <sieve@ietf.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.
[RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering
Language", RFC 5228, January 2008. Language", RFC 5228, January 2008.
[RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension",
RFC 5229, January 2008. RFC 5229, January 2008.
[RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely
Managing Sieve Scripts", RFC 5804, July 2010.
6.2. Informative References 6.2. Informative References
[RFC5429] Stone, A., "Sieve Email Filtering: Reject and Extended [RFC5429] Stone, A., "Sieve Email Filtering: Reject and Extended
Reject Extensions", RFC 5429, March 2009. Reject Extensions", RFC 5429, March 2009.
[RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part [RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part
Tests, Iteration, Extraction, Replacement, and Enclosure", Tests, Iteration, Extraction, Replacement, and Enclosure",
RFC 5703, October 2009. RFC 5703, October 2009.
[RFC5804] Melnikov, A. and T. Martin, "A Protocol for Remotely
Managing Sieve Scripts", RFC 5804, July 2010.
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, Arnt Gulbrandsen, Barry Leiba, Kjetil Torgrim Homme, Stephan Bosch, Arnt Gulbrandsen, Barry Leiba,
and Jeffrey Hutzelman for comments and corrections. and Jeffrey Hutzelman for comments and corrections.
Appendix B. Change History (to be removed prior to publication as an Appendix B. Change History (to be removed prior to publication as an
RFC) RFC)
Changes from ietf-10 to ietf-11:
a. Nits from Dilyan Palauzov.
b. Nits from Stephan Bosch.
c. Nits from Alexey Melnikov.
Changes from ietf-09 to ietf-10: Changes from ietf-09 to ietf-10:
a. Another example script error caught by Stephan Bosch. a. Another example script error caught by Stephan Bosch.
b. Add :optional argument to allow a missing script to be ignored. b. Add :optional argument to allow a missing script to be ignored.
Changes from ietf-08 to ietf-09: Changes from ietf-08 to ietf-09:
a. Better variables language from Stephan Bosch. a. Better variables language from Stephan Bosch.
 End of changes. 16 change blocks. 
39 lines changed or deleted 53 lines changed or added

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