draft-ietf-sieve-include-11.txt   draft-ietf-sieve-include-12.txt 
Network Working Group C. Daboo Network Working Group C. Daboo
Internet-Draft A. Stone Internet-Draft A. Stone
Intended status: Standards Track September 23, 2011 Intended status: Standards Track September 24, 2011
Expires: March 26, 2012 Expires: March 27, 2012
Sieve Email Filtering: Include Extension Sieve Email Filtering: Include Extension
draft-ietf-sieve-include-11 draft-ietf-sieve-include-12
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 26, 2012. This Internet-Draft will expire on March 27, 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 . . . . . . . . . . . . . . . . . . . . . . 4 3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 3
3.1. General Considerations . . . . . . . . . . . . . . . . . . 4 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 . . . . . . . . . . . . . 12 5.1. "include" Extension Registration . . . . . . . . . . . . . 11
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11
6.1. Normative References . . . . . . . . . . . . . . . . . . . 12 6.1. Normative References . . . . . . . . . . . . . . . . . . . 11
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 final disposition of the
rejected, or otherwise processed. an instance of a Sieve message (e.g. delivered, forwarded, discarded, rejected, etc.).
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 5, line 9 skipping to change at page 5, line 7
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 [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 allow variable
expansion in the script name argument. expansion in the script name argument.
skipping to change at page 7, line 4 skipping to change at page 6, line 48
This script special-cases some correspondent email addresses and This script special-cases some correspondent email addresses and
makes sure any message containing those addresses are always kept. makes sure any message containing those addresses are always kept.
if address :is "from" "boss@example.com" if address :is "from" "boss@example.com"
{ {
keep; keep;
} }
elsif address :is "from" "ceo@example.com" elsif address :is "from" "ceo@example.com"
{ {
keep; keep;
} }
Personal script "spam_tests" Personal script "spam_tests" (uses "reject" [RFC5429])
This script does some user-specific spam tests to catch spam This script does some user-specific spam tests to catch spam
messages not caught by the site-wide spam tests. messages not caught by the site-wide spam tests.
require ["reject"]; require ["reject"];
if header :contains "Subject" "XXXX" if header :contains "Subject" "XXXX"
{ {
reject "Subject XXXX is unacceptable."; reject "Subject XXXX is unacceptable.";
} }
elsif address :is "from" "money@example.com" elsif address :is "from" "money@example.com"
skipping to change at page 7, line 41 skipping to change at page 7, line 36
{ {
fileinto "lists.sieve"; fileinto "lists.sieve";
} }
elsif header :is "List-ID" "ietf-imapext.imc.org" elsif header :is "List-ID" "ietf-imapext.imc.org"
{ {
fileinto "lists.imapext"; fileinto "lists.imapext";
} }
There is one script stored in the global repository: There is one script stored in the global repository:
Site script "spam_tests" Site script "spam_tests" (uses "reject" [RFC5429])
This script does some site-wide spam tests which any user at the This script does some site-wide spam tests which any user at the
site can include in their own scripts at a suitable point. The site can include in their own scripts at a suitable point. The
script content is kept up to date by the site administrator. script content is kept up to date by the site administrator.
require ["reject"]; require ["reject"];
if anyof (header :contains "Subject" "$$", if anyof (header :contains "Subject" "$$",
header :contains "Subject" "Make money") header :contains "Subject" "Make money")
{ {
reject "No thank you."; reject "No thank you.";
} }
3.3. Control Structure return 3.3. Control Structure return
Usage: return Usage: return
The "return" command stops processing of the immediately included The "return" command stops processing of the immediately included
script only and returns processing control to the script which script only and returns processing control to the script which
includes it. If used in the main script (i.e., not in an included 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 script), it has the same effect as the "stop" command, including the
appropriate "keep" action if no other actions have been executed up appropriate "keep" action if no other actions have been executed up
to that point. to that point.
3.4. Interaction with Variables 3.4. Interaction with Variables
skipping to change at page 8, line 44 skipping to change at page 8, line 36
However, sometimes there is a need to make a variable defined in one However, sometimes there is a need to make a variable defined in one
script available to others. This specification defines the new script available to others. This specification defines the new
command "global" to declare that a variable is shared among scripts. command "global" to declare that a variable is shared among scripts.
Effectively, two namespaces are defined: one local to the immediate Effectively, two namespaces are defined: one local to the immediate
script, and another shared among all scripts. Implementations MUST script, and another shared among all scripts. Implementations MUST
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 accepts a string list argument that defines one The "global" command accepts 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.
Each name MUST be a constant string and conform to the syntax of Each name MUST be a constant string and conform to the syntax of
variable-name as defined in VARIABLES [RFC5229], Section 3. Match variable-name as defined in VARIABLES [RFC5229], Section 3. Match
variables cannot be specified and namespace prefixes are not allowed. variables cannot be specified and namespace prefixes are not allowed.
An invalid name MUST be detected as a syntax error. An invalid name MUST be detected as a syntax error.
The "global" command is only available when the script has both The "global" command is only available when the script has both
"include" and "variables" in its require line. If the "global" "include" and "variables" in its require line. If the "global"
skipping to change at page 12, line 7 skipping to change at page 11, line 30
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, the "return" action from an included script, scripts, the "return" action from an included
and the "global" command and "global" variables namespace script, and the "global" command and "global"
to access variables shared among included scripts. variables namespace to access variables shared
RFC number: this RFC among included scripts.
Contact address: the Sieve discussion list <sieve@ietf.org> RFC number: this RFC
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.
 End of changes. 14 change blocks. 
30 lines changed or deleted 25 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/