draft-ietf-sieve-include-12.txt   draft-ietf-sieve-include-13.txt 
Network Working Group C. Daboo Network Working Group C. Daboo
Internet-Draft A. Stone Internet-Draft A. Stone
Intended status: Standards Track September 24, 2011 Intended status: Standards Track September 27, 2011
Expires: March 27, 2012 Expires: March 30, 2012
Sieve Email Filtering: Include Extension Sieve Email Filtering: Include Extension
draft-ietf-sieve-include-12 draft-ietf-sieve-include-13
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 March 27, 2012. This Internet-Draft will expire on March 30, 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
skipping to change at page 2, line 18 skipping to change at page 2, line 18
2. Conventions Used in This Document . . . . . . . . . . . . . . 3 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 3 3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 3
3.1. General Considerations . . . . . . . . . . . . . . . . . . 3 3.1. General Considerations . . . . . . . . . . . . . . . . . . 3
3.2. Control Structure include . . . . . . . . . . . . . . . . 5 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 5, line 17 skipping to change at page 5, line 17
Usage: include [LOCATION] [":once"] [":optional"] <value: string> Usage: include [LOCATION] [":once"] [":optional"] <value: string>
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. Implementations MUST restrict script for processing at that point. Implementations MUST restrict script
names according to MANAGESIEVE [RFC5804], Section 1.6. The script names according to MANAGESIEVE [RFC5804], Section 1.6. The script
name argument MUST be a constant string as defined in VARIABLES name argument MUST be a constant string as defined in VARIABLES
[RFC5229], Section 3; implementations MUST NOT allow variable [RFC5229], Section 3; implementations MUST NOT expand variables in
expansion in the script name argument. 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 5, line 41 skipping to change at page 5, line 41
The ":once" parameter tells the interpreter only to include the named 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 if it has not already been included at any other point during
script execution. If the script has already been included, script execution. If the script has already been included,
processing continues immediately following the include command. processing continues immediately following the include command.
Implementations MUST NOT generate an error if an "include :once" Implementations MUST NOT generate an error if an "include :once"
command names a script whose inclusion would be recursive; in this command names a script whose inclusion would be recursive; in this
case, the script MUST be considered previously included and therefore case, the script MUST be considered previously included and therefore
"include :once" will not include it again. "include :once" will not include it again.
Note: It is RECOMMENDED that script authors / 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. The ":optional" parameter indicates that the script may be missing.
Ordinarily, an implementation MUST generate an error at runtime if an Ordinarily, an implementation MUST generate an error during execution
include command specifies a script that does not exist. When if an include command specifies a script that does not exist. When
":optional" is specified, implementations MUST NOT generate an error ":optional" is specified, implementations MUST NOT generate an error
for a missing script, and MUST continue as if the include command had for a missing script, and MUST continue as if the include command had
not been present. not been present.
Note: It is RECOMMENDED that script authors / generators use this
parameter only when including a script that performs general duties
such as declaring global variables and making sanity checks of the
environment.
The included script MUST be a valid Sieve script. Each script MUST The included script MUST be a valid Sieve script. Each script MUST
have its own "require" statements for all optional capabilities used have its own "require" statements for all optional capabilities used
by that script. The scope of a "require" statement is the script in by that script. The scope of a "require" statement is the script in
which it immediately appears, and neither inherits nor passes on which it immediately appears, and neither inherits nor passes on
capabilities to other scripts during the course of execution. capabilities to other scripts during the course of execution.
A "stop" command in an included script MUST stop all script A "stop" command in an included script MUST stop all script
processing, including the processing of the scripts that include the processing, including the processing of the scripts that include the
immediate one. The "return" command (described below) stops immediate one. The "return" command (described below) stops
processing of the immediate script only, and allows the scripts that processing of the immediate script only, and allows the scripts that
include it to continue. include it to continue.
The "include" command MAY appear anywhere in a script where a control The "include" command MAY appear anywhere in a script where a control
structure is legal, and MAY be used within another control structure, structure is legal, and MAY be used within another control structure,
e.g., within an "if" or "foreverypart" block (MIME [RFC5703]). e.g., within an "if" or "foreverypart" block (MIME [RFC5703]). The
included script SHALL NOT have any special control over the control
structure it was included from, e.g., inclusion from within a
"foreverypart" block does not allow the included script to directly
terminate or continue flow of that block.
Examples: Examples:
The user has four scripts stored in their personal repository: The user has four scripts stored in their personal repository:
"default" "default"
This is the default active script that includes several others. This is the default active script that includes several others.
require ["include"]; require ["include"];
skipping to change at page 9, line 37 skipping to change at page 10, line 10
script, the test which matches last will leave its value in the script, the test which matches last will leave its value in the
test_mailbox variable and the top-level script will file the test_mailbox variable and the top-level script will file the
message into that mailbox. If no tests matched, the message will message into that mailbox. If no tests matched, the message will
be implicitly kept in the INBOX. be implicitly kept in the INBOX.
require ["fileinto", "include", "variables", "relational"]; require ["fileinto", "include", "variables", "relational"];
global "test"; global "test";
global "test_mailbox"; global "test_mailbox";
set "test" "$$"; set "test" "$$";
include "spam_checks"; include "subject_tests";
set "test" "Make money"; set "test" "Make money";
include "spam_checks"; include "subject_tests";
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 "subject_tests"
This script performs a number of tests against the message, sets This script performs a number of tests against the message, sets
the global test_mailbox variable with a folder to file the message the global test_mailbox variable with a folder to file the message
into, then falls back to the top-level script. into, then falls back to the top-level script.
require ["include", "variables"]; global require ["include", "variables"];
["test", "test_mailbox"]; 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 19 skipping to change at page 11, line 34
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 access 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.
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.
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
skipping to change at page 12, line 26 skipping to change at page 13, line 5
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-12 to ietf-13:
a. Nits from Stephan Bosch.
b. Nits from Robert Burrell Donkin.
Changes from ietf-11 to ietf-12:
a. Nits from Alexey Melnikov.
b. Nits from Barry Leiba.
Changes from ietf-10 to ietf-11: Changes from ietf-10 to ietf-11:
a. Nits from Dilyan Palauzov. a. Nits from Dilyan Palauzov.
b. Nits from Stephan Bosch. b. Nits from Stephan Bosch.
c. Nits from Alexey Melnikov. c. Nits from Alexey Melnikov.
Changes from ietf-09 to ietf-10: Changes from ietf-09 to ietf-10:
 End of changes. 15 change blocks. 
22 lines changed or deleted 44 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/