7Network Working Group K. Homme
8Request for Comments: 5229 University of Oslo
9Updates: 5228 January 2008
10Category: Standards Track
13 Sieve Email Filtering: Variables Extension
17 This document specifies an Internet standards track protocol for the
18 Internet community, and requests discussion and suggestions for
19 improvements. Please refer to the current edition of the "Internet
20 Official Protocol Standards" (STD 1) for the standardization state
21 and status of this protocol. Distribution of this memo is unlimited.
25 In advanced mail filtering rule sets, it is useful to keep state or
26 configuration details across rules. This document updates the Sieve
27 filtering language (RFC 5228) with an extension to support variables.
28 The extension changes the interpretation of strings, adds an action
29 to store data in variables, and supplies a new test so that the value
30 of a string can be examined.
58Homme Standards Track [Page 1]
60RFC 5229 Sieve: Variables Extension January 2008
65 This is an extension to the Sieve language defined by [SIEVE]. It
66 adds support for storing and referencing named data. The mechanisms
67 detailed in this document will only apply to Sieve scripts that
68 include a require clause for the "variables" extension. The require
69 clauses themselves are not affected by this extension.
71 Conventions for notations are as in [SIEVE] section 1.1, including
72 use of [KEYWORDS] and [ABNF]. The grammar builds on the grammar of
73 [SIEVE]. In this document, "character" means a character from the
74 ISO 10646 coded character set [ISO10646], which may consist of
75 multiple octets coded in [UTF-8], and "variable" is a named reference
76 to data stored or read back using the mechanisms of this extension.
782. Capability Identifier
80 The capability string associated with the extension defined in this
81 document is "variables".
833. Interpretation of Strings
85 This extension changes the semantics of quoted-string, multi-line-
86 literal and multi-line-dotstuff found in [SIEVE] to enable the
87 inclusion of the value of variables.
89 When a string is evaluated, substrings matching variable-ref SHALL be
90 replaced by the value of variable-name. Only one pass through the
91 string SHALL be done. Variable names are case insensitive, so "foo"
92 and "FOO" refer to the same variable. Unknown variables are replaced
95 variable-ref = "${" [namespace] variable-name "}"
96 namespace = identifier "." *sub-namespace
97 sub-namespace = variable-name "."
98 variable-name = num-variable / identifier
99 num-variable = 1*DIGIT
102 "&%${}!" => unchanged, as the empty string is an illegal
104 "${doh!}" => unchanged, as "!" is illegal in identifiers
106 The variable "company" holds the value "ACME". No other variables
109 "${full}" => the empty string
110 "${company}" => "ACME"
114Homme Standards Track [Page 2]
116RFC 5229 Sieve: Variables Extension January 2008
119 "${BAD${Company}" => "${BADACME"
120 "${President, ${Company} Inc.}"
121 => "${President, ACME Inc.}"
123 The expanded string MUST use the variable values that are current
124 when control reaches the statement the string is part of.
126 Strings where no variable substitutions take place are referred to as
127 constant strings. Future extensions may specify that passing non-
128 constant strings as arguments to its actions or tests is an error.
130 Namespaces are meant for future extensions that make internal state
131 available through variables. These variables SHOULD be put in a
132 namespace whose first component is the same as its capability string.
133 Such extensions SHOULD state which, if any, of the variables in its
134 namespace are modifiable with the "set" action.
136 References to namespaces without a prior require statement for the
137 relevant extension MUST cause an error.
139 Tests or actions in future extensions may need to access the
140 unexpanded version of the string argument and, e.g., do the expansion
141 after setting variables in its namespace. The design of the
142 implementation should allow this.
1443.1. Quoting and Encoded Characters
146 The semantics of quoting using backslash are not changed: backslash
147 quoting is resolved before doing variable substitution. Similarly,
148 encoded character processing (see Section 2.4.2.4 of [SIEVE]) is
149 performed before doing variable substitution, but after quoting.
152 "${fo\o}" => ${foo} => the expansion of variable foo.
153 "${fo\\o}" => ${fo\o} => illegal identifier => left verbatim.
154 "\${foo}" => ${foo} => the expansion of variable foo.
155 "\\${foo}" => \${foo} => a backslash character followed by the
156 expansion of variable foo.
158 If it is required to include a character sequence such as
159 "${beep}" verbatim in a text literal, the user can define a
160 variable to circumvent expansion to the empty string.
164 set "text" "regarding ${dollar}{beep}";
170Homme Standards Track [Page 3]
172RFC 5229 Sieve: Variables Extension January 2008
176 require ["encoded-character", "variables"];
177 set "name" "Ethelbert"
178 if header :contains "Subject" "dear${hex:20 24 7b 4e}ame}" {
179 # the test string is "dear Ethelbert"
184 A "match variable" has a name consisting only of decimal digits and
185 has no namespace component.
187 The decimal value of the match variable name will index the list of
188 matching strings from the most recently evaluated successful match of
189 type ":matches". The list is empty if no match has been successful.
191 Note: Extra leading zeroes are allowed and ignored.
193 The list will contain one string for each wildcard ("?" and "*") in
194 the match pattern. Each string holds the substring from the source
195 value that the corresponding wildcard expands to, possibly the empty
196 string. The wildcards match as little as possible (non-greedy
199 The first string in the list has index 1. If the index is out of
200 range, the empty string will be substituted. Index 0 contains the
201 matched part of the source value.
203 The interpreter MUST short-circuit tests, i.e., not perform more
204 tests than necessary to find the result. Evaluation order MUST be
205 left to right. If a test has two or more list arguments, the
206 implementation is free to choose which to iterate over first.
208 An extension describing a new match type (e.g., [REGEX]) MAY specify
209 that match variables are set as a side effect when the match type is
210 used in a script that has enabled the "variables" extension.
214 require ["fileinto", "variables"];
216 if header :matches "List-ID" "*<*@*" {
217 fileinto "INBOX.lists.${2}"; stop;
226Homme Standards Track [Page 4]
228RFC 5229 Sieve: Variables Extension January 2008
232 # Subject: [acme-users] [fwd] version 1.0 is out
233 if header :matches "Subject" "[*] *" {
234 # ${1} will hold "acme-users",
235 # ${2} will hold "[fwd] version 1.0 is out"
236 fileinfo "INBOX.lists.${1}"; stop;
240 # To: coyote@ACME.Example.COM
241 if address :matches ["To", "Cc"] ["coyote@**.com",
243 # ${0} is the matching address
244 # ${1} is always the empty string
245 # ${2} is part of the domain name ("ACME.Example")
246 fileinto "INBOX.business.${2}"; stop;
248 # Control wouldn't reach this block if any match was
249 # successful, so no match variables are set at this
253 if anyof (true, address :domain :matches "To" "*.com") {
254 # The second test is never evaluated, so there are
255 # still no match variables set.
261 Usage: set [MODIFIER] <name: string> <value: string>
263 The "set" action stores the specified value in the variable
264 identified by name. The name MUST be a constant string and conform
265 to the syntax of variable-name. Match variables cannot be set. A
266 namespace cannot be used unless an extension explicitly allows its
267 use in "set". An invalid name MUST be detected as a syntax error.
269 Modifiers are applied on a value before it is stored in the variable.
270 See the next section for details.
272 Variables are only visible to the currently running script. Note:
273 Future extensions may provide different scoping rules for variables.
275 Variable names are case insensitive.
282Homme Standards Track [Page 5]
284RFC 5229 Sieve: Variables Extension January 2008
288 set "honorific" "Mr";
289 set "first_name" "Wile";
290 set "last_name" "Coyote";
292 Dear ${HONORIFIC} ${last_name},
293 I'm out, please leave a message after the meep.
297 "set" does not affect the implicit keep. It is compatible with all
298 actions defined in [SIEVE].
302 Usage: ":lower" / ":upper" / ":lowerfirst" / ":upperfirst" /
303 ":quotewildcard" / ":length"
305 Modifier names are case insensitive. Unknown modifiers MUST yield a
306 syntax error. More than one modifier can be specified, in which case
307 they are applied according to this precedence list, largest value
310 +--------------------------------+
311 | Precedence Modifier |
312 +--------------------------------+
315 +--------------------------------+
318 +--------------------------------+
319 | 20 :quotewildcard |
320 +--------------------------------+
322 +--------------------------------+
324 It is an error to use two or more modifiers of the same precedence in
325 a single "set" action.
328 # The value assigned to the variable is printed after the arrow
329 set "a" "juMBlEd lETteRS"; => "juMBlEd lETteRS"
330 set :length "b" "${a}"; => "15"
331 set :lower "b" "${a}"; => "jumbled letters"
332 set :upperfirst "b" "${a}"; => "JuMBlEd lETteRS"
333 set :upperfirst :lower "b" "${a}"; => "Jumbled letters"
334 set :quotewildcard "b" "Rock*"; => "Rock\*"
338Homme Standards Track [Page 6]
340RFC 5229 Sieve: Variables Extension January 2008
3434.1.1. Modifier ":length"
345 The value is the decimal number of characters in the expansion,
346 converted to a string.
3484.1.2. Modifier ":quotewildcard"
350 This modifier adds the necessary quoting to ensure that the expanded
351 text will only match a literal occurrence if used as a parameter to
352 :matches. Every character with special meaning ("*", "?", and "\")
353 is prefixed with "\" in the expansion.
357 These modifiers change the letters of the text from upper to lower
358 case or vice versa. Characters other than "A"-"Z" and "a"-"z" from
359 US-ASCII are left unchanged.
3614.1.3.1. Modifier ":upper"
363 All lower case letters are converted to their upper case
3664.1.3.2. Modifier ":lower"
368 All upper case letters are converted to their lower case
3714.1.3.3. Modifier ":upperfirst"
373 The first character of the string is converted to upper case if it is
374 a letter and set in lower case. The rest of the string is left
3774.1.3.4. Modifier ":lowerfirst"
379 The first character of the string is converted to lower case if it is
380 a letter and set in upper case. The rest of the string is left
385 Usage: string [MATCH-TYPE] [COMPARATOR]
386 <source: string-list> <key-list: string-list>
388 The "string" test evaluates to true if any of the source strings
389 matches any key. The type of match defaults to ":is".
394Homme Standards Track [Page 7]
396RFC 5229 Sieve: Variables Extension January 2008
399 In the "string" test, both source and key-list are taken from the
400 script, not the message, and whitespace stripping MUST NOT be done
401 unless the script explicitly requests this through some future
405 set "state" "${state} pending";
406 if string :matches " ${state} " "* pending *" {
407 # the above test always succeeds
410 The "relational" extension [RELATIONAL] adds a match type called
411 ":count". The count of a single string is 0 if it is the empty
412 string, or 1 otherwise. The count of a string list is the sum of the
413 counts of the member strings.
4156. Implementation Limits
417 An implementation of this document MUST support at least 128 distinct
418 variables. The supported length of variable names MUST be at least
419 32 characters. Each variable MUST be able to hold at least 4000
420 characters. Attempts to set the variable to a value larger than what
421 the implementation supports SHOULD be reported as an error at
422 compile-time if possible. If the attempt is discovered during run-
423 time, the value SHOULD be truncated, and it MUST NOT be treated as an
426 Match variables ${1} through ${9} MUST be supported. References to
427 higher indices than those the implementation supports MUST be treated
428 as a syntax error, which SHOULD be discovered at compile-time.
4307. Security Considerations
432 When match variables are used, and the author of the script isn't
433 careful, strings can contain arbitrary values controlled by the
436 Since values stored by "set" that exceed implementation limits are
437 silently truncated, it's not appropriate to store large structures
438 with security implications in variables.
440 The introduction of variables makes advanced decision making easier
441 to write, but since no looping construct is provided, all Sieve
442 scripts will terminate in an orderly manner.
444 Sieve filtering should not be relied on as a security measure against
445 hostile mail messages. Sieve is designed to do simple, mostly static
446 tests, and is not suitable for use as a spam or virus checker, where
450Homme Standards Track [Page 8]
452RFC 5229 Sieve: Variables Extension January 2008
455 the perpetrator has a motivation to vary the format of the mail in
456 order to avoid filtering rules. See also [SPAMTEST].
4588. IANA Considerations
460 The following template specifies the IANA registration of the
461 variables Sieve extension specified in this document:
464 Subject: Registration of new Sieve extension
466 Capability name: variables
467 Description: Adds support for variables to the Sieve filtering
470 Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
474 Thanks to Cyrus Daboo, Jutta Degener, Ned Freed, Lawrence Greenfield,
475 Jeffrey Hutzelman, Mark E. Mallett, Alexey Melnikov, Peder Stray, and
476 Nigel Swinson for valuable feedback.
48010.1. Normative References
482 [ABNF] Crocker, D., Ed., and Overell, P., "Augmented BNF for
483 Syntax Specifications: ABNF", RFC 4234, October 2005.
485 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
486 Requirement Levels", BCP 14, RFC 2119, March 1997.
488 [RELATIONAL] Segmuller, W. and B. Leiba, "Sieve Email Filtering:
489 Relational Extension", RFC 5231, January 2008.
491 [SIEVE] Guenther, P., Ed., and T. Showalter, Ed., "Sieve: An
492 Email Filtering Language", RFC 5228, January 2008.
494 [UTF-8] Yergeau, F., "UTF-8, a transformation format of Unicode
495 and ISO 10646", RFC 3629, November 2003.
49710.2. Informative References
499 [ISO10646] ISO/IEC, "Information Technology - Universal Multiple-
500 Octet Coded Character Set (UCS) - Part 1: Architecture
501 and Basic Multilingual Plane", May 1993, with
506Homme Standards Track [Page 9]
508RFC 5229 Sieve: Variables Extension January 2008
511 [REGEX] Murchison, K., "Sieve Email Filtering -- Regular
512 Expression Extension", Work in Progress, February 2006.
514 [SPAMTEST] Daboo, C., "Sieve Email Filtering: Spamtest and
515 Virustest Extensions", RFC 5235, January 2008.
525 EMail: kjetilho@ifi.uio.no
562Homme Standards Track [Page 10]
564RFC 5229 Sieve: Variables Extension January 2008
567Full Copyright Statement
569 Copyright (C) The IETF Trust (2008).
571 This document is subject to the rights, licenses and restrictions
572 contained in BCP 78, and except as set forth therein, the authors
573 retain all their rights.
575 This document and the information contained herein are provided on an
576 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
577 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
578 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
579 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
580 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
581 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
585 The IETF takes no position regarding the validity or scope of any
586 Intellectual Property Rights or other rights that might be claimed to
587 pertain to the implementation or use of the technology described in
588 this document or the extent to which any license under such rights
589 might or might not be available; nor does it represent that it has
590 made any independent effort to identify any such rights. Information
591 on the procedures with respect to rights in RFC documents can be
592 found in BCP 78 and BCP 79.
594 Copies of IPR disclosures made to the IETF Secretariat and any
595 assurances of licenses to be made available, or the result of an
596 attempt made to obtain a general license or permission for the use of
597 such proprietary rights by implementers or users of this
598 specification can be obtained from the IETF on-line IPR repository at
599 http://www.ietf.org/ipr.
601 The IETF invites any interested party to bring to its attention any
602 copyrights, patents or patent applications, or other proprietary
603 rights that may cover technology that may be required to implement
604 this standard. Please address the information to the IETF at
618Homme Standards Track [Page 11]