draft-ietf-sieve-variables-04.txt   draft-ietf-sieve-variables-05.txt 
Network Working Group K. T. Homme Network Working Group K. T. Homme
Updates: 3028 Updates: 3028
Document: draft-ietf-sieve-variables-04.txt University of Oslo Document: draft-ietf-sieve-variables-05.txt University of Oslo
Expires Jan 14, 2006 14 Jul 2005 Expires Feb 10, 2006 10 Aug 2005
Sieve Mail Filtering Language: Variables Extension Sieve Extension: Variables
Status of this Memo Status of this Memo
This document is an Internet-Draft and is subject to all provisions This document is an Internet-Draft and is subject to all provisions
of section 3 of RFC 3978. By submitting this Internet-Draft, each of section 3 of RFC 3978. By submitting this Internet-Draft, each
author represents that any applicable patent or other IPR claims of author represents that any applicable patent or other IPR claims of
which he or she is aware have been or will be disclosed, and any of which he or she is aware have been or will be disclosed, and any of
which he or she becomes aware will be disclosed, in accordance with which he or she becomes aware will be disclosed, in accordance with
Section 6 of BCP 79. Section 6 of BCP 79.
skipping to change at page 2, line 19 skipping to change at page 2, line 19
0.1. Discussion 0.1. Discussion
This draft is intended to be an extension to the Sieve mail filtering This draft is intended to be an extension to the Sieve mail filtering
language, available from the RFC repository as language, available from the RFC repository as
<ftp://ftp.ietf.org/rfc/rfc3028.txt>. <ftp://ftp.ietf.org/rfc/rfc3028.txt>.
This draft and the Sieve language itself are being discussed on the This draft and the Sieve language itself are being discussed on the
MTA Filters mailing list at <ietf-mta-filters@imc.org>. Subscription MTA Filters mailing list at <ietf-mta-filters@imc.org>. Subscription
requests can be sent to <ietf-mta-filters-request@imc.org> (send an requests can be sent to <ietf-mta-filters-request@imc.org> (send an
email message with the word "subscribe" in the body). More mail message with the word "subscribe" in the body). More
information on the mailing list along with a WWW archive of back information on the mailing list along with a WWW archive of back
messages is available at <http://www.imc.org/ietf-mta-filters/>. messages is available at <http://www.imc.org/ietf-mta-filters/>.
0.2. Noted Changes 0.2. Noted Changes
0.2.1. Changes since -00 0.2.1. Changes since -00
a) allow generic time zone names, without requiring implementations to a) allow generic time zone names, without requiring implementations to
support it. added a "${timezone}" variable so that the user can support it. added a "${timezone}" variable so that the user can
check if the implementation does support the time zone name he check if the implementation does support the time zone name he
skipping to change at page 5, line 13 skipping to change at page 5, line 13
b) "numbered variables" are now called "match variables". b) "numbered variables" are now called "match variables".
c) clarify definition of "match variable". c) clarify definition of "match variable".
d) it's not the whole namespace which should match the extension d) it's not the whole namespace which should match the extension
keyword, only the first component. keyword, only the first component.
e) allow level 2 and above of the namespace specification to be all- e) allow level 2 and above of the namespace specification to be all-
digit. digit.
f) combining :upper and :lower etc. is a now syntax error. f) combining :upper and :lower etc. is now a syntax error.
g) allow SET to set variables in namespaces if the extension allows g) allow SET to set variables in namespaces if the extension allows
it. it.
0.2.9. Changes since -03 0.2.9. Changes since -03
a) added two new modifiers, ":quoteregex" and ":quotewildcard". a) added two new modifiers, ":quoteregex" and ":quotewildcard".
b) added wording about security implications of silent truncation. b) added wording about security implications of silent truncation.
0.2.10. Changes since -04
a) fix buggy markup and add missing modifier to syntax description
b) changed two "syntax error" (which really weren't) into just
"error".
c) changed "Syntax:" into "Usage:" to mirror [SIEVE] convention.
d) removed description of regex interaction and :quoteregex
e) added note to clarify that ${0010} is the same as ${10}.
f) changed name of document to align better with other extensions
(uses same format at 3431 and 3894)
0.3. Open Issues 0.3. Open Issues
This extension is in conflict with a MUST in [SIEVE] 2.4: "Tests MUST This extension is in conflict with a MUST in [SIEVE] 2.4: "Tests MUST
NOT have side effects." This document therefore can't leave draft NOT have side effects." This document therefore can't leave draft
status until a revised Sieve specification has been accepted by the status until a revised Sieve specification has been accepted by the
IESG. No significant changes to this draft are foreseen before IESG. No significant changes to this draft are foreseen before
submission as a proposed standard. submission as a proposed standard.
1. Introduction 1. Introduction
skipping to change at page 6, line 38 skipping to change at page 7, line 7
Examples: Examples:
"&%${}!" => unchanged, as the empty string is an illegal "&%${}!" => unchanged, as the empty string is an illegal
identifier identifier
"${doh!}" => unchanged, as "!" is illegal in identifiers "${doh!}" => unchanged, as "!" is illegal in identifiers
The variable "company" holds the value "ACME". No other variables The variable "company" holds the value "ACME". No other variables
are set. are set.
"${full}" => the empty string "${full}" => the empty string
"${company}" => "ACME" "${company}" => "ACME"
"${BAD${Company}" => "${BADACME"
"${President, ${Company} Inc.}" "${President, ${Company} Inc.}"
=> "${President, ACME Inc.}" => "${President, ACME Inc.}"
"${BAD${Company}"=>"${BADACME"
The expanded string MUST use the variable values which are current The expanded string MUST use the variable values which are current
when control reaches the statement the string is part of. when control reaches the statement the string is part of.
Strings where no variable substitutions take place are referred to as Strings where no variable substitutions take place are referred to as
constant strings. Future extensions may specify that passing non- constant strings. Future extensions may specify that passing non-
constant strings as arguments to its actions or tests is an error. constant strings as arguments to its actions or tests is an error.
Namespaces are meant for future extensions which make internal state Namespaces are meant for future extensions which make internal state
available through variables. These variables SHOULD be put in a available through variables. These variables SHOULD be put in a
skipping to change at page 7, line 4 skipping to change at page 7, line 21
The expanded string MUST use the variable values which are current The expanded string MUST use the variable values which are current
when control reaches the statement the string is part of. when control reaches the statement the string is part of.
Strings where no variable substitutions take place are referred to as Strings where no variable substitutions take place are referred to as
constant strings. Future extensions may specify that passing non- constant strings. Future extensions may specify that passing non-
constant strings as arguments to its actions or tests is an error. constant strings as arguments to its actions or tests is an error.
Namespaces are meant for future extensions which make internal state Namespaces are meant for future extensions which make internal state
available through variables. These variables SHOULD be put in a available through variables. These variables SHOULD be put in a
namespace whose first component is the same as its capability string. namespace whose first component is the same as its capability string.
Such extensions SHOULD state which, if any, of the variables in its Such extensions SHOULD state which, if any, of the variables in its
namespace are modifiable with the "set" action. namespace are modifiable with the "set" action.
References to namespaces without a prior require statement for the References to namespaces without a prior require statement for the
relevant extension MUST cause a syntax error. relevant extension MUST cause an error.
Tests or actions in future extensions may need to access the Tests or actions in future extensions may need to access the
unexpanded version of the string argument and, e.g., do the expansion unexpanded version of the string argument and, e.g., do the expansion
after setting variables in its namespace. The design of the after setting variables in its namespace. The design of the
implementation should allow this. implementation should allow this.
3.1. Quoting 3.1. Quoting
The semantics of quoting using backslash are not changed: backslash The semantics of quoting using backslash are not changed: backslash
quoting is resolved before doing variable substitution. quoting is resolved before doing variable substitution.
skipping to change at page 7, line 43 skipping to change at page 8, line 12
set "dollar" "$"; set "dollar" "$";
set "text" "regarding ${dollar}{beep}"; set "text" "regarding ${dollar}{beep}";
3.2. Match variables 3.2. Match variables
A "match variable" has a name consisting only of decimal digits and A "match variable" has a name consisting only of decimal digits and
has no namespace component. has no namespace component.
The decimal value of the match variable name will index the list of The decimal value of the match variable name will index the list of
matching strings from the most recently evaluated successful match of matching strings from the most recently evaluated successful match of
type ":matches" or ":regex" (see [REGEX]). The list is empty if no type ":matches". The list is empty if no match has been successful.
match has been successful. An extension describing a new match type (e.g., [REGEX]) MAY specify
that match variables are set as a side effect when the match type is
used in a script which has enabled the "variables" extension.
Note: Extra leading zeroes are allowed and ignored.
For ":matches", the list will contain one string for each wildcard For ":matches", the list will contain one string for each wildcard
("?" and "*") in the match pattern. Each string holds what the ("?" and "*") in the match pattern. Each string holds what the
corresponding wildcard expands to, possibly the empty string. The corresponding wildcard expands to, possibly the empty string. The
wildcards match as little as possible (non-greedy matching). wildcards match as little as possible (non-greedy matching).
For ":regex", the list will contain the strings corresponding to the
group operators. The groups are ordered by the position of the
opening parenthesis, from left to right. Note that in regular
expressions, expansions match as much as possible (greedy matching).
The first string in the list has index 1. If the index is out of The first string in the list has index 1. If the index is out of
range, the empty string will be substituted. Index 0 contains the range, the empty string will be substituted. Index 0 contains the
matched part of the source value. matched part of the source value.
The interpreter MUST short-circuit tests, ie. not perform more tests The interpreter MUST short-circuit tests, ie. not perform more tests
than necessary to find the result. Evaluation order MUST be left to than necessary to find the result. Evaluation order MUST be left to
right. If a test has two or more list arguments, the implementation right. If a test has two or more list arguments, the implementation
is free to choose which to iterate over first. is free to choose which to iterate over first.
Example: Example:
require ["fileinto", "regex", "variables"]; require ["fileinto", "variables"];
if header :regex "List-ID" "<(.*)@" {
fileinto "lists.${1}"; stop;
}
# This usually gives the same result as the above
if header :matches "List-ID" "*<*@*" { if header :matches "List-ID" "*<*@*" {
fileinto "lists.${2}"; stop; fileinto "lists.${2}"; stop;
} }
# Imagine the header # Imagine the header
# Subject: [acme-users] [fwd] version 1.0 is out # Subject: [acme-users] [fwd] version 1.0 is out
if header :regex "Subject" "^[(.*)] (.*)$" {
# ${1} will hold "acme-users] [fwd"
stop;
}
if header :matches "Subject" "[*] *" { if header :matches "Subject" "[*] *" {
# ${1} will hold "acme-users", # ${1} will hold "acme-users",
# ${2} will hold "[fwd] version 1.0 is out" # ${2} will hold "[fwd] version 1.0 is out"
fileinfo "lists.${1}"; stop; fileinfo "lists.${1}"; stop;
} }
if address :matches ["To", "Cc"] ["coyote@**.com", if address :matches ["To", "Cc"] ["coyote@**.com",
"wile@**.com"] { "wile@**.com"] {
# ${0} is the matching address. # ${0} is the matching address.
# ${1} is always the empty string. # ${1} is always the empty string.
skipping to change at page 9, line 15 skipping to change at page 9, line 20
} }
if anyof (true, address :domain :matches "To" "*.com") { if anyof (true, address :domain :matches "To" "*.com") {
# The second test is never evaluated, so there are # The second test is never evaluated, so there are
# still no match variables set. # still no match variables set.
stop; stop;
} }
4. Action set 4. Action set
Syntax: set [MODIFIER] [COMPARATOR] <name: string> <value: string> Usage: set [MODIFIER] [COMPARATOR] <name: string> <value: string>
The "set" action stores the specified value in the variable The "set" action stores the specified value in the variable
identified by name. The name MUST be a constant string and conform identified by name. The name MUST be a constant string and conform
to the syntax of variable-name. Match variables can not be set. A to the syntax of variable-name. Match variables can not be set. A
namespace can not be used unless an extension explicitly allows its namespace can not be used unless an extension explicitly allows its
use in "set". An invalid name MUST be detected as a syntax error. use in "set". An invalid name MUST be detected as a syntax error.
Modifiers are applied on a value before it is stored in the variable. Modifiers are applied on a value before it is stored in the variable.
See next section for details. See next section for details.
skipping to change at page 9, line 47 skipping to change at page 10, line 7
Dear ${HONORIFIC} ${last_name}, Dear ${HONORIFIC} ${last_name},
I'm out, please leave a message after the meep. I'm out, please leave a message after the meep.
. .
; ;
"set" does not affect the implicit keep. It is compatible with all "set" does not affect the implicit keep. It is compatible with all
actions defined in [SIEVE]. actions defined in [SIEVE].
4.1. Modifiers 4.1. Modifiers
Syntax: ":lower" / ":upper" / ":lowerfirst" / ":upperfirst" / Usage: ":lower" / ":upper" / ":lowerfirst" / ":upperfirst" /
":length" ":quotewildcard" / ":length"
Modifier names are case insensitive. Unknown modifiers MUST yield a Modifier names are case insensitive. Unknown modifiers MUST yield a
syntax error. More than one modifier can be specified, in which case syntax error. More than one modifier can be specified, in which case
they are applied according to this precedence list, largest value they are applied according to this precedence list, largest value
first: first:
+--------------------------------+ +--------------------------------+
| Precedence Modifier | | Precedence Modifier |
+--------------------------------+ +--------------------------------+
| 40 :lower | | 40 :lower |
| :upper | | :upper |
+--------------------------------+ +--------------------------------+
| 30 :lowerfirst | | 30 :lowerfirst |
| :upperfirst | | :upperfirst |
+--------------------------------+ +--------------------------------+
| 20 :quotewildcard | | 20 :quotewildcard |
| :quoteregex |
+--------------------------------+ +--------------------------------+
| 10 :length | | 10 :length |
+--------------------------------+ +--------------------------------+
Using two or more modifiers of the same precedence is a syntax error. It is an error to use two or more modifiers of the same precedence in
a single SET command.
Examples: Examples:
# The value assigned to the variable is printed after the arrow # The value assigned to the variable is printed after the arrow
set "a" "juMBlEd lETteRS"; => "juMBlEd lETteRS" set "a" "juMBlEd lETteRS"; => "juMBlEd lETteRS"
set :length "b" "${a}"; => "15" set :length "b" "${a}"; => "15"
set :lower "b" "${a}"; => "jumbled letters" set :lower "b" "${a}"; => "jumbled letters"
set :lower :comparator "i;octet" set :lower :comparator "i;octet"
"b" "${a}"; => "juMBlEd lETteRS" "b" "${a}"; => "juMBlEd lETteRS"
set :upperfirst "b" "${a}"; => "JuMBlEd lETteRS" set :upperfirst "b" "${a}"; => "JuMBlEd lETteRS"
set :upperfirst :lower "b" "${a}"; => "Jumbled letters" set :upperfirst :lower "b" "${a}"; => "Jumbled letters"
set :quotewildcard "b" "Rock*"; => "Rock\*" set :quotewildcard "b" "Rock*"; => "Rock\*"
4.1.1. Modifier ":length" 4.1.1. Modifier ":length"
The value is the decimal number of characters in the expansion, The value is the decimal number of characters in the expansion,
converted to a string. converted to a string.
4.1.2. Quoting modifiers 4.1.2. Modifier ":quotewildcard"
These modifiers add the necessary quotes to ensure that the expanded
text will only match a literal occurence if used as a parameter for
:matches or :regex.
4.1.2.1. Modifier ":quotewildcard"
Every character with special meaning for :matches ("*", "?" and " is
prefixed with "
4.1.2.2. Modifier ":quoteregex"
Every character with special meaning for :regex (".", "*", "?" etc.) This modifier adds the necessary quoting to ensure that the expanded
is prefixed with " text will only match a literal occurence if used as a parameter to
:matches. Every character with special meaning ("*", "?" and "\")
is prefixed with "\" in the expansion.
4.1.3. Case modifiers 4.1.3. Case modifiers
These modifiers change the letters of the text from upper to lower These modifiers change the letters of the text from upper to lower
case or vice versa. The implementation MUST support US-ASCII, but is case or vice versa. The implementation MUST support US-ASCII, but is
not required to handle the entire Unicode repertoire. The comparator not required to handle the entire Unicode repertoire. The comparator
specified SHOULD be consulted to establish which locale to use. specified SHOULD be consulted to establish which locale to use.
4.1.3.1. Modifier ":upper" 4.1.3.1. Modifier ":upper"
skipping to change at page 11, line 44 skipping to change at page 11, line 41
unchanged. unchanged.
4.1.3.4. Modifier ":lowerfirst" 4.1.3.4. Modifier ":lowerfirst"
The first character of the string is converted to lower case if it is The first character of the string is converted to lower case if it is
a letter and set in upper case. The rest of the string is left a letter and set in upper case. The rest of the string is left
unchanged. unchanged.
5. Test string 5. Test string
Syntax: string [MATCH-TYPE] [COMPARATOR] Usage: string [MATCH-TYPE] [COMPARATOR]
<source: string-list> <key-list: string-list> <source: string-list> <key-list: string-list>
The "string" test evaluates to true if any of the source strings The "string" test evaluates to true if any of the source strings
matches any key. The type of match defaults to ":is". matches any key. The type of match defaults to ":is".
Example: Example:
set "state" "${state} pending"; set "state" "${state} pending";
if string :matches " ${state} " "* pending *" { if string :matches " ${state} " "* pending *" {
# the above test always succeeds # the above test always succeeds
} }
The "relational" extension [RELATIONAL] adds a match type called The "relational" extension [RELATIONAL] adds a match type called
":count". The count of a single string is 0 if it is the empty ":count". The count of a single string is 0 if it is the empty
string, or 1 otherwise. The count of a string list is the sum of the string, or 1 otherwise. The count of a string list is the sum of the
counts of the member strings. counts of the member strings.
skipping to change at page 12, line 36 skipping to change at page 12, line 34
error. error.
Match variables ${1} through ${9} MUST be supported. References to Match variables ${1} through ${9} MUST be supported. References to
higher indices than the implementation supports MUST be treated as a higher indices than the implementation supports MUST be treated as a
syntax error which SHOULD be discovered at compile-time. syntax error which SHOULD be discovered at compile-time.
7. Security Considerations 7. Security Considerations
When match variables are used, and the author of the script isn't When match variables are used, and the author of the script isn't
careful, strings can contain arbitrary values controlled by the careful, strings can contain arbitrary values controlled by the
sender of the e-mail. sender of the mail.
Since values stored by SET exceeding implementation limits are Since values stored by SET exceeding implementation limits are
silently truncated, it's not appropriate to store large structures silently truncated, it's not appropriate to store large structures
with security implications in variables. with security implications in variables.
The introduction of variables makes advanced decision making easier The introduction of variables makes advanced decision making easier
to write, but since no looping construct is provided, all Sieve to write, but since no looping construct is provided, all Sieve
scripts will terminate in an orderly manner. scripts will terminate in an orderly manner.
Sieve filtering should not be relied on as a security measure against Sieve filtering should not be relied on as a security measure against
hostile e-mail messages. Sieve is designed to do simple, mostly hostile mail messages. Sieve is designed to do simple, mostly static
static tests, and is not suitable for use as a spam or virus checker, tests, and is not suitable for use as a spam or virus checker, where
where the perpetrator has a motivation to vary the format of the the perpetrator has a motivation to vary the format of the mail in
email in order to avoid filtering rules. See also [SPAMTEST]. order to avoid filtering rules. See also [SPAMTEST].
8. IANA Considerations 8. IANA Considerations
The following template specifies the IANA registration of the The following template specifies the IANA registration of the
variables Sieve extension specified in this document: variables Sieve extension specified in this document:
To: iana@iana.org To: iana@iana.org
Subject: Registration of new Sieve extension Subject: Registration of new Sieve extension
Capability name: variables Capability name: variables
Capability keyword: variables Capability keyword: variables
Capability arguments: N/A Capability arguments: N/A
Standards Track/IESG-approved experimental RFC number: this RFC Standards Track/IESG-approved experimental RFC number:
this RFC
Person and email address to contact for further information: Person and email address to contact for further information:
Kjetil Torgrim Homme Kjetil Torgrim Homme
University of Oslo kjetilho@ifi.uio.no
Pb 1080, Blindern
NO-0316 OSLO
E-mail: kjetilho@ifi.uio.no
This information should be added to the list of sieve extensions This information should be added to the list of sieve extensions
given on http://www.iana.org/assignments/sieve-extensions. given on http://www.iana.org/assignments/sieve-extensions.
9. Acknowledgments 9. Acknowledgments
Thanks to Cyrus Daboo, Jutta Degener, Ned Freed, Lawrence Greenfield, Thanks to Cyrus Daboo, Jutta Degener, Ned Freed, Lawrence Greenfield,
Jeffrey Hutzelman, Mark E. Mallett, Alexey Melnikov, Peder Stray and Jeffrey Hutzelman, Mark E. Mallett, Alexey Melnikov, Peder Stray and
Nigel Swinson for valuable feedback. Nigel Swinson for valuable feedback.
skipping to change at page 14, line 10 skipping to change at page 13, line 46
0316 Oslo, Norway 0316 Oslo, Norway
Phone: +47 9366 0091 Phone: +47 9366 0091
E-mail: kjetilho@ifi.uio.no E-mail: kjetilho@ifi.uio.no
11. References 11. References
11.1. Normative references 11.1. Normative references
[ABNF] Crocker, D. and Overell, P., "Augmented BNF for Syntax [ABNF] Crocker, D. and Overell, P., "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997 Specifications: ABNF", RFC 2234, November 1997.
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", RFC 2119, March 1997. Requirement Levels", RFC 2119, March 1997.
[RELATIONAL] Segmuller, W., "Sieve Extension: Relational Tests", [RELATIONAL] Segmuller, W., "Sieve Extension: Relational Tests",
RFC 3431, December 2002 RFC 3431, December 2002.
[SIEVE] Showalter, T., "Sieve: A Mail Filtering Language", RFC [SIEVE] Guenther, P. and Showalter, T., "Sieve: An Email
3028, January 2001. Filtering Language", Work in Progress, draft-ietf-
sieve-3028bis-XX.txt
[UNICODE] The Unicode Consortium, "The Unicode Standard -- [UNICODE] The Unicode Consortium, "The Unicode Standard --
Worldwide Character Encoding -- Version 1.0", Addison- Worldwide Character Encoding -- Version 1.0", Addison-
Wesley, Volume 1, 1991, Volume 2, 1992. Wesley, Volume 1, 1991, Volume 2, 1992.
[UTF-8] Yergeau, F., "UTF-8, a transformation format of [UTF-8] Yergeau, F., "UTF-8, a transformation format of
Unicode and ISO 10646", RFC 3629, November 2003. Unicode and ISO 10646", RFC 3629, November 2003.
11.2. Informative References 11.2. Informative References
[REGEX] K. Murchison, "Sieve Email Filtering -- Regular [REGEX] Murchison, K., "Sieve Email Filtering -- Regular
Expression Extension", Work in Progress. Expression Extension", Work in Progress.
[SPAMTEST] C. Daboo, "SIEVE Email Filtering: Spamtest and [SPAMTEST] Daboo, C., "SIEVE Email Filtering: Spamtest and
VirusTest Extensions", RFC 3685, February 2004 VirusTest Extensions", RFC 3685, February 2004
Appendix B. Intellectual Property Rights Statement Appendix B. Intellectual Property Rights Statement
The IETF takes no position regarding the validity or scope of any The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to intellectual property or other rights that might be claimed to
pertain to the implementation or use of the technology described in pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights this document or the extent to which any license under such rights
might or might not be available; neither does it represent that it might or might not be available; neither does it represent that it
has made any effort to identify any such rights. Information on the has made any effort to identify any such rights. Information on the
 End of changes. 

This html diff was produced by rfcdiff 1.25, available from http://www.levkowetz.com/ietf/tools/rfcdiff/