RFC 5229
Sieve Email Filtering: Variables Extension
RFC 5229: Sieve Email Filtering: Variables Extension ✨
Network Working Group, Request for Comments: 5229 📜
Okay bestie, let's get the paperwork out of the way first 💅. This one was written by K. Homme from the University of Oslo and dated January 2008. It's a Standards Track document, so it's an actual protocol spec and not just a fun idea. It updates RFC 5228, which is the base Sieve filtering language, and the header doesn't list anything it obsoletes. 🦋
Status of This Memo 🌸
This document specifies an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions for improvements 🫶. For the official standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited, so share it with everyone 💜.
Abstract ✨
Okay so in fancy mail filtering rule sets, it's super useful to hold on to state or config details across rules 🧠. This document updates the Sieve filtering language (RFC 5228) with an extension that adds variables 🎀. The extension changes how strings are interpreted, adds an action that stores data in variables, and adds a new test so you can examine the value of a string 🔥.
1. Introduction 🌈
This is an extension to the Sieve language that's defined by [SIEVE] 💖. It adds support for storing and referencing named data. The mechanisms in this document only apply to Sieve scripts that include a require clause for the "variables" extension, and the require clauses themselves aren't affected by any of this 🙈.
For notation, we follow the conventions in [SIEVE] section 1.1, including the use of [KEYWORDS] and [ABNF]. The grammar builds on the grammar of [SIEVE] ✨. In this document, "character" means a character from the ISO 10646 coded character set [ISO10646], which might be made up of multiple octets coded in [UTF-8]. And "variable" is just a named reference to data that gets stored or read back using this extension 🦋.
2. Capability Identifier 🎀
The capability string for this extension is "variables" 💅.
3. Interpretation of Strings 🔥
This extension changes the semantics of quoted-string, multi-line-literal and multi-line-dotstuff from [SIEVE] so that the value of variables can be included in them 🧚.
When a string gets evaluated, any substrings that match variable-ref get replaced by the value of variable-name 💖. Only one pass through the string is done, so no double-dipping 💅. Variable names are case insensitive, which means "foo" and "FOO" refer to the same variable 🌸. Unknown variables get replaced by the empty string 💀.
variable-ref = "${" [namespace] variable-name "}"
namespace = identifier "." *sub-namespace
sub-namespace = variable-name "."
variable-name = num-variable / identifier
num-variable = 1*DIGITExamples:
"&%${}!" => unchanged, as the empty string is an illegal
identifier
"${doh!}" => unchanged, as "!" is illegal in identifiers
The variable "company" holds the value "ACME". No other variables
are set.
"${full}" => the empty string
"${company}" => "ACME"
"${BAD${Company}" => "${BADACME"
"${President, ${Company} Inc.}"
=> "${President, ACME Inc.}"The expanded string is required to use the variable values that are current when control reaches the statement the string is part of 🎯. Basically, the timing matters, bestie ⏰.
Strings where no variable substitutions happen are called constant strings 🍓. Future extensions may specify that passing non-constant strings as arguments to its actions or tests is an error 👀.
Namespaces are for future extensions that make internal state available through variables 🧚♀️. Those variables SHOULD be put in a namespace whose first component is the same as its capability string 💜. Such extensions SHOULD also state which, if any, of the variables in their namespace are modifiable with the "set" action 🫶.
References to namespaces without a prior require statement for the relevant extension MUST cause an error 🚫. Not me trying to use a namespace I never required 💀.
Tests or actions in future extensions may need to access the unexpanded version of the string argument, and they might do the expansion after setting variables in their namespace. The design of the implementation should allow this ✨.
3.1. Quoting and Encoded Characters 🎀
The semantics of quoting with backslash are not changed. Backslash quoting gets resolved before variable substitution happens 🔥. Similarly, encoded character processing (see Section 2.4.2.4 of [SIEVE]) is performed before variable substitution, but after quoting 💅.
Examples:
"${fo\o}" => ${foo} => the expansion of variable foo.
"${fo\\o}" => ${fo\o} => illegal identifier => left verbatim.
"\${foo}" => ${foo} => the expansion of variable foo.
"\\${foo}" => \${foo} => a backslash character followed by the
expansion of variable foo.If you need to include a character sequence such as "${beep}" verbatim in a text literal, you can define a variable to dodge the expansion to the empty string 🙈. Lowkey genius.
Example:
set "dollar" "$";
set "text" "regarding ${dollar}{beep}";Example:
require ["encoded-character", "variables"];
set "name" "Ethelbert"
if header :contains "Subject" "dear${hex:20 24 7b 4e}ame}" {
# the test string is "dear Ethelbert"
}3.2. Match Variables 🦋
A "match variable" has a name made up only of decimal digits, and it has no namespace component 🔢.
The decimal value of the match variable name indexes the list of matching strings from the most recently evaluated successful match of type ":matches" 💖. The list is empty if no match has been successful yet 🌸.
Note: Extra leading zeroes are allowed and ignored. 🧠
The list has one string for each wildcard ("?" and "*") in the match pattern 🎀. Each string holds the substring from the source value that the matching wildcard expands to, and that substring might be the empty string 🫧. The wildcards match as little as possible, which is called non-greedy matching 🤏.
The first string in the list has index 1 ☝️. If the index is out of range, the empty string gets substituted. Index 0 contains the matched part of the source value 💜.
The interpreter MUST short-circuit tests, which means it must not run more tests than it needs to find the result ⚡. Evaluation order MUST be left to right ➡️. If a test has two or more list arguments, the implementation is free to choose which one to iterate over first 🎲.
An extension describing a new match type (for example, [REGEX]) MAY specify that match variables are set as a side effect when that match type is used in a script that has enabled the "variables" extension 🌈.
Example:
require ["fileinto", "variables"];
if header :matches "List-ID" "*<*@*" {
fileinto "INBOX.lists.${2}"; stop;
}
# Imagine the header
# Subject: [acme-users] [fwd] version 1.0 is out
if header :matches "Subject" "[*] *" {
# ${1} will hold "acme-users",
# ${2} will hold "[fwd] version 1.0 is out"
fileinfo "INBOX.lists.${1}"; stop;
}
# Imagine the header
# To: coyote@ACME.Example.COM
if address :matches ["To", "Cc"] ["coyote@**.com",
"wile@**.com"] {
# ${0} is the matching address
# ${1} is always the empty string
# ${2} is part of the domain name ("ACME.Example")
fileinto "INBOX.business.${2}"; stop;
} else {
# Control wouldn't reach this block if any match was
# successful, so no match variables are set at this
# point.
}
if anyof (true, address :domain :matches "To" "*.com") {
# The second test is never evaluated, so there are
# still no match variables set.
stop;
}4. Action set 💅
Usage:
set [MODIFIER] <name: string> <value: string>The "set" action stores the specified value in the variable identified by name 🎀. The name MUST be a constant string and conform to the syntax of variable-name 🎯. Match variables cannot be set 🚫. A namespace cannot be used unless an extension explicitly allows its use in "set" 🧚. An invalid name MUST be detected as a syntax error 💀.
Modifiers are applied to a value before it gets stored in the variable. See the next section for details 🌸.
Variables are only visible to the currently running script 🔒. Future extensions may provide different scoping rules for variables 🔮.
Variable names are case insensitive 🍓.
Example:
set "honorific" "Mr";
set "first_name" "Wile";
set "last_name" "Coyote";
set "vacation" text:
Dear ${HONORIFIC} ${last_name},
I'm out, please leave a message after the meep.
.
;"set" does not affect the implicit keep, and it's compatible with all actions defined in [SIEVE] 🫶.
4.1. Modifiers 🦋
Usage:
":lower" / ":upper" / ":lowerfirst" / ":upperfirst" /
":quotewildcard" / ":length"Modifier names are case insensitive. Unknown modifiers MUST yield a syntax error 🙅♀️. You can specify more than one modifier, and when you do, they get applied according to this precedence list, with the largest value first 📋:
+--------------------------------+
| Precedence Modifier |
+--------------------------------+
| 40 :lower |
| :upper |
+--------------------------------+
| 30 :lowerfirst |
| :upperfirst |
+--------------------------------+
| 20 :quotewildcard |
+--------------------------------+
| 10 :length |
+--------------------------------+It is an error to use two or more modifiers of the same precedence in a single "set" action 🚨.
Examples:
# The value assigned to the variable is printed after the arrow
set "a" "juMBlEd lETteRS"; => "juMBlEd lETteRS"
set :length "b" "${a}"; => "15"
set :lower "b" "${a}"; => "jumbled letters"
set :upperfirst "b" "${a}"; => "JuMBlEd lETteRS"
set :upperfirst :lower "b" "${a}"; => "Jumbled letters"
set :quotewildcard "b" "Rock*"; => "Rock\*"4.1.1. Modifier ":length" 📏
The value is the decimal number of characters in the expansion, converted to a string 🔢.
4.1.2. Modifier ":quotewildcard" 🛡️
This modifier adds the quoting needed to make sure the expanded text only matches a literal occurrence when it's used as a parameter to :matches 🎯. Every character with special meaning ("*", "?", and "") gets prefixed with "" in the expansion 💅.
4.1.3. Case Modifiers 🔤
These modifiers change the letters of the text from upper to lower case, or the other way around. Characters other than "A"-"Z" and "a"-"z" from US-ASCII are left unchanged 🌈.
4.1.3.1. Modifier ":upper" ⬆️
All lower case letters are converted to their upper case counterparts 🔥.
4.1.3.2. Modifier ":lower" ⬇️
All upper case letters are converted to their lower case counterparts 🌸.
4.1.3.3. Modifier ":upperfirst" 🎀
The first character of the string is converted to upper case if it's a letter and is set in lower case. The rest of the string is left unchanged 💖.
4.1.3.4. Modifier ":lowerfirst" 🧁
The first character of the string is converted to lower case if it's a letter and is set in upper case. The rest of the string is left unchanged 🫶.
5. Test string ✨
okay bestie, the string test is literally so good 💖 it checks whether any of the source strings matches any key. If you don't say which kind of match you want, it defaults to ":is" 🎀
Usage: string [MATCH-TYPE] [COMPARATOR]
<source: string-list> <key-list: string-list>Now the big rule for this one 👑 source and key-list both come from the script, NOT the message, and whitespace stripping MUST NOT be done unless the script explicitly asks for it through some future mechanism. no cap, that's a strict vibe 🙈
Example, because you know I love showing you:
Example:
set "state" "${state} pending";
if string :matches " ${state} " "* pending *" {
# the above test always succeeds
}Obsessed with that one tbh 😭 the ${state} gets swapped in first, so the pattern matches no matter what.
The "relational" extension [RELATIONAL] adds a match type called ":count" 🧚 For a single string, the count is 0 if it's the empty string, and 1 otherwise. For a string list, the count is the sum of the counts of the member strings. It's giving math class, but make it cute 💅
6. Implementation Limits 🦋
okay this section is about the limits every implementation has to handle, and I need you to take them seriously 🫶
An implementation of this document MUST support at least 128 distinct variables. The supported length of variable names MUST be at least 32 characters. Each variable MUST be able to hold at least 4000 characters. If you try to set a variable to a value bigger than the implementation can handle, it SHOULD be reported as an error at compile-time if that's possible. If the attempt gets discovered at run-time instead, the value SHOULD be truncated, and it MUST NOT be treated as an error. 😳 that run-time thing is a little plot twist, ngl
Match variables ${1} through ${9} MUST be supported. References to higher indices than the implementation supports MUST be treated as a syntax error, which SHOULD be discovered at compile-time. Bestie, catch these early 🔥
7. Security Considerations 💀
this section is serious, so I'm going to be serious too 🥺
When match variables are used, and the author of the script isn't careful, strings can contain arbitrary values controlled by the sender of the mail. Yikes 😬 the sender can literally write whatever they want into those strings.
⚠️ Since values stored by set that exceed implementation limits are silently truncated, it's not appropriate to store large structures with security implications in variables. Don't do it, periodt.
The introduction of variables makes advanced decision making easier to write, but since no looping construct is provided, all Sieve scripts will terminate in an orderly manner. So no infinite loops, which is honestly iconic 🌈
Sieve filtering should not be relied on as a security measure against hostile mail messages. Sieve is designed to do simple, mostly static tests, and it is not suitable for use as a spam or virus checker, where the perpetrator has a motivation to vary the format of the mail in order to avoid filtering rules. See also [SPAMTEST]. Not me trusting Sieve to stop hackers 💅 it's a filtering tool, not a bodyguard.
8. IANA Considerations 🌸
the IANA part is basically a template for registering the variables extension. Here's how it's written:
To: iana@iana.org
Subject: Registration of new Sieve extension
Capability name: variables
Description: Adds support for variables to the Sieve filtering
language.
RFC number: RFC 5229
Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>9. Acknowledgments 🫶
big thank-you to Cyrus Daboo, Jutta Degener, Ned Freed, Lawrence Greenfield, Jeffrey Hutzelman, Mark E. Mallett, Alexey Melnikov, Peder Stray, and Nigel Swinson for giving valuable feedback. You all ate 👑✨
10. References 📚
10.1. Normative References
- [ABNF] Crocker, D., Ed., and Overell, P., "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005.
- [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [RELATIONAL] Segmuller, W. and B. Leiba, "Sieve Email Filtering: Relational Extension", RFC 5231, January 2008.
- [SIEVE] Guenther, P., Ed., and T. Showalter, Ed., "Sieve: An Email Filtering Language", RFC 5228, January 2008.
- [UTF-8] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO 10646", RFC 3629, November 2003.
10.2. Informative References
- [ISO10646] ISO/IEC, "Information Technology - Universal Multiple-Octet Coded Character Set (UCS) - Part 1: Architecture and Basic Multilingual Plane", May 1993, with amendments.
- [REGEX] Murchison, K., "Sieve Email Filtering -- Regular Expression Extension", Work in Progress, February 2006.
- [SPAMTEST] Daboo, C., "Sieve Email Filtering: Spamtest and Virustest Extensions", RFC 5235, January 2008.
Author's Address 🎀
Kjetil T. Homme
University of Oslo
PO Box 1080
0316 Oslo, Norway
Phone: +47 9366 0091
EMail: kjetilho@ifi.uio.noFull Copyright Statement 🌈
Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.
This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 💖
Intellectual Property 🧚
The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. 🦋
📦 where this page comes from
- ietf: rfc5229 2008-01
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms