2356 lines
86 KiB
Plaintext
2356 lines
86 KiB
Plaintext
|
||
|
||
|
||
|
||
|
||
|
||
Network Working Group P. Guenther, Ed.
|
||
Request for Comments: 5228 Sendmail, Inc.
|
||
Obsoletes: 3028 T. Showalter, Ed.
|
||
Category: Standards Track January 2008
|
||
|
||
|
||
Sieve: An Email Filtering Language
|
||
|
||
Status of This Memo
|
||
|
||
This document specifies an Internet standards track protocol for the
|
||
Internet community, and requests discussion and suggestions for
|
||
improvements. Please refer to the current edition of the "Internet
|
||
Official Protocol Standards" (STD 1) for the standardization state
|
||
and status of this protocol. Distribution of this memo is unlimited.
|
||
|
||
Abstract
|
||
|
||
This document describes a language for filtering email messages at
|
||
time of final delivery. It is designed to be implementable on either
|
||
a mail client or mail server. It is meant to be extensible, simple,
|
||
and independent of access protocol, mail architecture, and operating
|
||
system. It is suitable for running on a mail server where users may
|
||
not be allowed to execute arbitrary programs, such as on black box
|
||
Internet Message Access Protocol (IMAP) servers, as the base language
|
||
has no variables, loops, or ability to shell out to external
|
||
programs.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 1]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
Table of Contents
|
||
|
||
1. Introduction ....................................................4
|
||
1.1. Conventions Used in This Document ..........................4
|
||
1.2. Example Mail Messages ......................................5
|
||
2. Design ..........................................................6
|
||
2.1. Form of the Language .......................................6
|
||
2.2. Whitespace .................................................7
|
||
2.3. Comments ...................................................7
|
||
2.4. Literal Data ...............................................7
|
||
2.4.1. Numbers .............................................7
|
||
2.4.2. Strings .............................................8
|
||
2.4.2.1. String Lists ...............................9
|
||
2.4.2.2. Headers ....................................9
|
||
2.4.2.3. Addresses .................................10
|
||
2.4.2.4. Encoding Characters Using
|
||
"encoded-character" .......................10
|
||
2.5. Tests .....................................................11
|
||
2.5.1. Test Lists .........................................12
|
||
2.6. Arguments .................................................12
|
||
2.6.1. Positional Arguments ...............................12
|
||
2.6.2. Tagged Arguments ...................................12
|
||
2.6.3. Optional Arguments .................................13
|
||
2.6.4. Types of Arguments .................................13
|
||
2.7. String Comparison .........................................13
|
||
2.7.1. Match Type .........................................14
|
||
2.7.2. Comparisons across Character Sets ..................15
|
||
2.7.3. Comparators ........................................15
|
||
2.7.4. Comparisons against Addresses ......................16
|
||
2.8. Blocks ....................................................17
|
||
2.9. Commands ..................................................17
|
||
2.10. Evaluation ...............................................18
|
||
2.10.1. Action Interaction ................................18
|
||
2.10.2. Implicit Keep .....................................18
|
||
2.10.3. Message Uniqueness in a Mailbox ...................19
|
||
2.10.4. Limits on Numbers of Actions ......................19
|
||
2.10.5. Extensions and Optional Features ..................19
|
||
2.10.6. Errors ............................................20
|
||
2.10.7. Limits on Execution ...............................20
|
||
3. Control Commands ...............................................21
|
||
3.1. Control if ................................................21
|
||
3.2. Control require ...........................................22
|
||
3.3. Control stop ..............................................22
|
||
4. Action Commands ................................................23
|
||
4.1. Action fileinto ...........................................23
|
||
4.2. Action redirect ...........................................23
|
||
4.3. Action keep ...............................................24
|
||
4.4. Action discard ............................................25
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 2]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
5. Test Commands ..................................................26
|
||
5.1. Test address ..............................................26
|
||
5.2. Test allof ................................................27
|
||
5.3. Test anyof ................................................27
|
||
5.4. Test envelope .............................................27
|
||
5.5. Test exists ...............................................28
|
||
5.6. Test false ................................................28
|
||
5.7. Test header ...............................................29
|
||
5.8. Test not ..................................................29
|
||
5.9. Test size .................................................29
|
||
5.10. Test true ................................................30
|
||
6. Extensibility ..................................................30
|
||
6.1. Capability String .........................................31
|
||
6.2. IANA Considerations .......................................31
|
||
6.2.1. Template for Capability Registrations ..............32
|
||
6.2.2. Handling of Existing Capability Registrations ......32
|
||
6.2.3. Initial Capability Registrations ...................32
|
||
6.3. Capability Transport ......................................33
|
||
7. Transmission ...................................................33
|
||
8. Parsing ........................................................34
|
||
8.1. Lexical Tokens ............................................34
|
||
8.2. Grammar ...................................................36
|
||
8.3. Statement Elements ........................................36
|
||
9. Extended Example ...............................................37
|
||
10. Security Considerations .......................................38
|
||
11. Acknowledgments ...............................................39
|
||
12. Normative References ..........................................39
|
||
13. Informative References ........................................40
|
||
14. Changes from RFC 3028 .........................................41
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 3]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
1. Introduction
|
||
|
||
This memo documents a language that can be used to create filters for
|
||
electronic mail. It is not tied to any particular operating system
|
||
or mail architecture. It requires the use of [IMAIL]-compliant
|
||
messages, but should otherwise generalize to many systems.
|
||
|
||
The language is powerful enough to be useful but limited in order to
|
||
allow for a safe server-side filtering system. The intention is to
|
||
make it impossible for users to do anything more complex (and
|
||
dangerous) than write simple mail filters, along with facilitating
|
||
the use of graphical user interfaces (GUIs) for filter creation and
|
||
manipulation. The base language was not designed to be Turing-
|
||
complete: it does not have a loop control structure or functions.
|
||
|
||
Scripts written in Sieve are executed during final delivery, when the
|
||
message is moved to the user-accessible mailbox. In systems where
|
||
the Mail Transfer Agent (MTA) does final delivery, such as
|
||
traditional Unix mail, it is reasonable to filter when the MTA
|
||
deposits mail into the user's mailbox.
|
||
|
||
There are a number of reasons to use a filtering system. Mail
|
||
traffic for most users has been increasing due to increased usage of
|
||
email, the emergence of unsolicited email as a form of advertising,
|
||
and increased usage of mailing lists.
|
||
|
||
Experience at Carnegie Mellon has shown that if a filtering system is
|
||
made available to users, many will make use of it in order to file
|
||
messages from specific users or mailing lists. However, many others
|
||
did not make use of the Andrew system's FLAMES filtering language
|
||
[FLAMES] due to difficulty in setting it up.
|
||
|
||
Because of the expectation that users will make use of filtering if
|
||
it is offered and easy to use, this language has been made simple
|
||
enough to allow many users to make use of it, but rich enough that it
|
||
can be used productively. However, it is expected that GUI-based
|
||
editors will be the preferred way of editing filters for a large
|
||
number of users.
|
||
|
||
1.1. Conventions Used in This Document
|
||
|
||
In the sections of this document that discuss the requirements of
|
||
various keywords and operators, the following conventions have been
|
||
adopted.
|
||
|
||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
|
||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
|
||
document are to be interpreted as described in [KEYWORDS].
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 4]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
Each section on a command (test, action, or control) has a line
|
||
labeled "Usage:". This line describes the usage of the command,
|
||
including its name and its arguments. Required arguments are listed
|
||
inside angle brackets ("<" and ">"). Optional arguments are listed
|
||
inside square brackets ("[" and "]"). Each argument is followed by
|
||
its type, so "<key: string>" represents an argument called "key" that
|
||
is a string. Literal strings are represented with double-quoted
|
||
strings. Alternatives are separated with slashes, and parentheses
|
||
are used for grouping, similar to [ABNF].
|
||
|
||
In the "Usage:" line, there are three special pieces of syntax that
|
||
are frequently repeated, MATCH-TYPE, COMPARATOR, and ADDRESS-PART.
|
||
These are discussed in sections 2.7.1, 2.7.3, and 2.7.4,
|
||
respectively.
|
||
|
||
The formal grammar for these commands is defined in section 8 and is
|
||
the authoritative reference on how to construct commands, but the
|
||
formal grammar does not specify the order, semantics, number or types
|
||
of arguments to commands, or the legal command names. The intent is
|
||
to allow for extension without changing the grammar.
|
||
|
||
1.2. Example Mail Messages
|
||
|
||
The following mail messages will be used throughout this document in
|
||
examples.
|
||
|
||
Message A
|
||
-----------------------------------------------------------
|
||
Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST)
|
||
From: coyote@desert.example.org
|
||
To: roadrunner@acme.example.com
|
||
Subject: I have a present for you
|
||
|
||
Look, I'm sorry about the whole anvil thing, and I really
|
||
didn't mean to try and drop it on you from the top of the
|
||
cliff. I want to try to make it up to you. I've got some
|
||
great birdseed over here at my place--top of the line
|
||
stuff--and if you come by, I'll have it all wrapped up
|
||
for you. I'm really sorry for all the problems I've caused
|
||
for you over the years, but I know we can work this out.
|
||
--
|
||
Wile E. Coyote "Super Genius" coyote@desert.example.org
|
||
-----------------------------------------------------------
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 5]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
Message B
|
||
-----------------------------------------------------------
|
||
From: youcouldberich!@reply-by-postal-mail.invalid
|
||
Sender: b1ff@de.res.example.com
|
||
To: rube@landru.example.com
|
||
Date: Mon, 31 Mar 1997 18:26:10 -0800
|
||
Subject: $$$ YOU, TOO, CAN BE A MILLIONAIRE! $$$
|
||
|
||
YOU MAY HAVE ALREADY WON TEN MILLION DOLLARS, BUT I DOUBT
|
||
IT! SO JUST POST THIS TO SIX HUNDRED NEWSGROUPS! IT WILL
|
||
GUARANTEE THAT YOU GET AT LEAST FIVE RESPONSES WITH MONEY!
|
||
MONEY! MONEY! COLD HARD CASH! YOU WILL RECEIVE OVER
|
||
$20,000 IN LESS THAN TWO MONTHS! AND IT'S LEGAL!!!!!!!!!
|
||
!!!!!!!!!!!!!!!!!!111111111!!!!!!!11111111111!!1 JUST
|
||
SEND $5 IN SMALL, UNMARKED BILLS TO THE ADDRESSES BELOW!
|
||
-----------------------------------------------------------
|
||
|
||
2. Design
|
||
|
||
2.1. Form of the Language
|
||
|
||
The language consists of a set of commands. Each command consists of
|
||
a set of tokens delimited by whitespace. The command identifier is
|
||
the first token and it is followed by zero or more argument tokens.
|
||
Arguments may be literal data, tags, blocks of commands, or test
|
||
commands.
|
||
|
||
With the exceptions of strings and comments, the language is limited
|
||
to US-ASCII characters. Strings and comments may contain octets
|
||
outside the US-ASCII range. Specifically, they will normally be in
|
||
UTF-8, as specified in [UTF-8]. NUL (US-ASCII 0) is never permitted
|
||
in scripts, while CR and LF can only appear as the CRLF line ending.
|
||
|
||
Note: While this specification permits arbitrary octets to appear
|
||
in Sieve scripts inside strings and comments, this has made it
|
||
difficult to robustly handle Sieve scripts in programs that are
|
||
sensitive to the encodings used. The "encoded-character"
|
||
capability (section 2.4.2.4) provides an alternative means of
|
||
representing such octets in strings using just US-ASCII
|
||
characters. As such, the use of non-UTF-8 text in scripts should
|
||
be considered a deprecated feature that may be abandoned.
|
||
|
||
Tokens other than strings are considered case-insensitive.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 6]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
2.2. Whitespace
|
||
|
||
Whitespace is used to separate tokens. Whitespace is made up of
|
||
tabs, newlines (CRLF, never just CR or LF), and the space character.
|
||
The amount of whitespace used is not significant.
|
||
|
||
2.3. Comments
|
||
|
||
Two types of comments are offered. Comments are semantically
|
||
equivalent to whitespace and can be used anyplace that whitespace is
|
||
(with one exception in multi-line strings, as described in the
|
||
grammar).
|
||
|
||
Hash comments begin with a "#" character that is not contained within
|
||
a string and continue until the next CRLF.
|
||
|
||
Example: if size :over 100k { # this is a comment
|
||
discard;
|
||
}
|
||
|
||
Bracketed comments begin with the token "/*" and end with "*/"
|
||
outside of a string. Bracketed comments may span multiple lines.
|
||
Bracketed comments do not nest.
|
||
|
||
Example: if size :over 100K { /* this is a comment
|
||
this is still a comment */ discard /* this is a comment
|
||
*/ ;
|
||
}
|
||
|
||
2.4. Literal Data
|
||
|
||
Literal data means data that is not executed, merely evaluated "as
|
||
is", to be used as arguments to commands. Literal data is limited to
|
||
numbers, strings, and string lists.
|
||
|
||
2.4.1. Numbers
|
||
|
||
Numbers are given as ordinary decimal numbers. As a shorthand for
|
||
expressing larger values, such as message sizes, a suffix of "K",
|
||
"M", or "G" MAY be appended to indicate a multiple of a power of two.
|
||
To be comparable with the power-of-two-based versions of SI units
|
||
that computers frequently use, "K" specifies kibi-, or 1,024 (2^10)
|
||
times the value of the number; "M" specifies mebi-, or 1,048,576
|
||
(2^20) times the value of the number; and "G" specifies gibi-, or
|
||
1,073,741,824 (2^30) times the value of the number [BINARY-SI].
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 7]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
Implementations MUST support integer values in the inclusive range
|
||
zero to 2,147,483,647 (2^31 - 1), but MAY support larger values.
|
||
|
||
Only non-negative integers are permitted by this specification.
|
||
|
||
2.4.2. Strings
|
||
|
||
Scripts involve large numbers of string values as they are used for
|
||
pattern matching, addresses, textual bodies, etc. Typically, short
|
||
quoted strings suffice for most uses, but a more convenient form is
|
||
provided for longer strings such as bodies of messages.
|
||
|
||
A quoted string starts and ends with a single double quote (the <">
|
||
character, US-ASCII 34). A backslash ("\", US-ASCII 92) inside of a
|
||
quoted string is followed by either another backslash or a double
|
||
quote. These two-character sequences represent a single backslash or
|
||
double quote within the value, respectively.
|
||
|
||
Scripts SHOULD NOT escape other characters with a backslash.
|
||
|
||
An undefined escape sequence (such as "\a" in a context where "a" has
|
||
no special meaning) is interpreted as if there were no backslash (in
|
||
this case, "\a" is just "a"), though that may be changed by
|
||
extensions.
|
||
|
||
Non-printing characters such as tabs, CRLF, and control characters
|
||
are permitted in quoted strings. Quoted strings MAY span multiple
|
||
lines. An unencoded NUL (US-ASCII 0) is not allowed in strings; see
|
||
section 2.4.2.4 for how it can be encoded.
|
||
|
||
As message header data is converted to [UTF-8] for comparison (see
|
||
section 2.7.2), most string values will use the UTF-8 encoding.
|
||
However, implementations MUST accept all strings that match the
|
||
grammar in section 8. The ability to use non-UTF-8 encoded strings
|
||
matches existing practice and has proven to be useful both in tests
|
||
for invalid data and in arguments containing raw MIME parts for
|
||
extension actions that generate outgoing messages.
|
||
|
||
For entering larger amounts of text, such as an email message, a
|
||
multi-line form is allowed. It starts with the keyword "text:",
|
||
followed by a CRLF, and ends with the sequence of a CRLF, a single
|
||
period, and another CRLF. The CRLF before the final period is
|
||
considered part of the value. In order to allow the message to
|
||
contain lines with a single dot, lines are dot-stuffed. That is,
|
||
when composing a message body, an extra '.' is added before each line
|
||
that begins with a '.'. When the server interprets the script, these
|
||
extra dots are removed. Note that a line that begins with a dot
|
||
followed by a non-dot character is not interpreted as dot-stuffed;
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 8]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
that is, ".foo" is interpreted as ".foo". However, because this is
|
||
potentially ambiguous, scripts SHOULD be properly dot-stuffed so such
|
||
lines do not appear.
|
||
|
||
Note that a hashed comment or whitespace may occur in between the
|
||
"text:" and the CRLF, but not within the string itself. Bracketed
|
||
comments are not allowed here.
|
||
|
||
2.4.2.1. String Lists
|
||
|
||
When matching patterns, it is frequently convenient to match against
|
||
groups of strings instead of single strings. For this reason, a list
|
||
of strings is allowed in many tests, implying that if the test is
|
||
true using any one of the strings, then the test is true.
|
||
|
||
For instance, the test 'header :contains ["To", "Cc"]
|
||
["me@example.com", "me00@landru.example.com"]' is true if either a To
|
||
header or Cc header of the input message contains either of the email
|
||
addresses "me@example.com" or "me00@landru.example.com".
|
||
|
||
Conversely, in any case where a list of strings is appropriate, a
|
||
single string is allowed without being a member of a list: it is
|
||
equivalent to a list with a single member. This means that the test
|
||
'exists "To"' is equivalent to the test 'exists ["To"]'.
|
||
|
||
2.4.2.2. Headers
|
||
|
||
Headers are a subset of strings. In the Internet Message
|
||
Specification [IMAIL], each header line is allowed to have whitespace
|
||
nearly anywhere in the line, including after the field name and
|
||
before the subsequent colon. Extra spaces between the header name
|
||
and the ":" in a header field are ignored.
|
||
|
||
A header name never contains a colon. The "From" header refers to a
|
||
line beginning "From:" (or "From :", etc.). No header will match
|
||
the string "From:" due to the trailing colon.
|
||
|
||
Similarly, no header will match a syntactically invalid header name.
|
||
An implementation MUST NOT cause an error for syntactically invalid
|
||
header names in tests.
|
||
|
||
Header lines are unfolded as described in [IMAIL] section 2.2.3.
|
||
Interpretation of header data SHOULD be done according to [MIME3]
|
||
section 6.2 (see section 2.7.2 below for details).
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 9]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
2.4.2.3. Addresses
|
||
|
||
A number of commands call for email addresses, which are also a
|
||
subset of strings. When these addresses are used in outbound
|
||
contexts, addresses must be compliant with [IMAIL], but are further
|
||
constrained within this document. Using the symbols defined in
|
||
[IMAIL], section 3, the syntax of an address is:
|
||
|
||
sieve-address = addr-spec ; simple address
|
||
/ phrase "<" addr-spec ">" ; name & addr-spec
|
||
|
||
That is, routes and group syntax are not permitted. If multiple
|
||
addresses are required, use a string list. Named groups are not
|
||
permitted.
|
||
|
||
It is an error for a script to execute an action with a value for use
|
||
as an outbound address that doesn't match the "sieve-address" syntax.
|
||
|
||
2.4.2.4. Encoding Characters Using "encoded-character"
|
||
|
||
When the "encoded-character" extension is in effect, certain
|
||
character sequences in strings are replaced by their decoded value.
|
||
This happens after escape sequences are interpreted and dot-
|
||
unstuffing has been done. Implementations SHOULD support "encoded-
|
||
character".
|
||
|
||
Arbitrary octets can be embedded in strings by using the syntax
|
||
encoded-arb-octets. The sequence is replaced by the octets with the
|
||
hexadecimal values given by each hex-pair.
|
||
|
||
blank = WSP / CRLF
|
||
encoded-arb-octets = "${hex:" hex-pair-seq "}"
|
||
hex-pair-seq = *blank hex-pair *(1*blank hex-pair) *blank
|
||
hex-pair = 1*2HEXDIG
|
||
|
||
Where WSP and HEXDIG non-terminals are defined in Appendix B.1 of
|
||
[ABNF].
|
||
|
||
It may be inconvenient or undesirable to enter Unicode characters
|
||
verbatim, and for these cases the syntax encoded-unicode-char can be
|
||
used. The sequence is replaced by the UTF-8 encoding of the
|
||
specified Unicode characters, which are identified by the hexadecimal
|
||
value of unicode-hex.
|
||
|
||
encoded-unicode-char = "${unicode:" unicode-hex-seq "}"
|
||
unicode-hex-seq = *blank unicode-hex
|
||
*(1*blank unicode-hex) *blank
|
||
unicode-hex = 1*HEXDIG
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 10]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
It is an error for a script to use a hexadecimal value that isn't in
|
||
either the range 0 to D7FF or the range E000 to 10FFFF. (The range
|
||
D800 to DFFF is excluded as those character numbers are only used as
|
||
part of the UTF-16 encoding form and are not applicable to the UTF-8
|
||
encoding that the syntax here represents.)
|
||
|
||
Note: Implementations MUST NOT raise an error for an out-of-range
|
||
Unicode value unless the sequence containing it is well-formed
|
||
according to the grammar.
|
||
|
||
The capability string for use with the require command is "encoded-
|
||
character".
|
||
|
||
In the following script, message B is discarded, since the specified
|
||
test string is equivalent to "$$$".
|
||
|
||
Example: require "encoded-character";
|
||
if header :contains "Subject" "$${hex:24 24}" {
|
||
discard;
|
||
}
|
||
The following examples demonstrate valid and invalid encodings and
|
||
how they are handled:
|
||
|
||
"$${hex:40}" -> "$@"
|
||
"${hex: 40 }" -> "@"
|
||
"${HEX: 40}" -> "@"
|
||
"${hex:40" -> "${hex:40"
|
||
"${hex:400}" -> "${hex:400}"
|
||
"${hex:4${hex:30}}" -> "${hex:40}"
|
||
"${unicode:40}" -> "@"
|
||
"${ unicode:40}" -> "${ unicode:40}"
|
||
"${UNICODE:40}" -> "@"
|
||
"${UnICoDE:0000040}" -> "@"
|
||
"${Unicode:40}" -> "@"
|
||
"${Unicode:Cool}" -> "${Unicode:Cool}"
|
||
"${unicode:200000}" -> error
|
||
"${Unicode:DF01} -> error
|
||
|
||
2.5. Tests
|
||
|
||
Tests are given as arguments to commands in order to control their
|
||
actions. In this document, tests are given to if/elsif to decide
|
||
which block of code is run.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 11]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
2.5.1. Test Lists
|
||
|
||
Some tests ("allof" and "anyof", which implement logical "and" and
|
||
logical "or", respectively) may require more than a single test as an
|
||
argument. The test-list syntax element provides a way of grouping
|
||
tests as a comma-separated list in parentheses.
|
||
|
||
Example: if anyof (not exists ["From", "Date"],
|
||
header :contains "from" "fool@example.com") {
|
||
discard;
|
||
}
|
||
|
||
2.6. Arguments
|
||
|
||
In order to specify what to do, most commands take arguments. There
|
||
are three types of arguments: positional, tagged, and optional.
|
||
|
||
It is an error for a script, on a single command, to use conflicting
|
||
arguments or to use a tagged or optional argument more than once.
|
||
|
||
2.6.1. Positional Arguments
|
||
|
||
Positional arguments are given to a command that discerns their
|
||
meaning based on their order. When a command takes positional
|
||
arguments, all positional arguments must be supplied and must be in
|
||
the order prescribed.
|
||
|
||
2.6.2. Tagged Arguments
|
||
|
||
This document provides for tagged arguments in the style of
|
||
CommonLISP. These are also similar to flags given to commands in
|
||
most command-line systems.
|
||
|
||
A tagged argument is an argument for a command that begins with ":"
|
||
followed by a tag naming the argument, such as ":contains". This
|
||
argument means that zero or more of the next tokens have some
|
||
particular meaning depending on the argument. These next tokens may
|
||
be literal data, but they are never blocks.
|
||
|
||
Tagged arguments are similar to positional arguments, except that
|
||
instead of the meaning being derived from the command, it is derived
|
||
from the tag.
|
||
|
||
Tagged arguments must appear before positional arguments, but they
|
||
may appear in any order with other tagged arguments. For simplicity
|
||
of the specification, this is not expressed in the syntax definitions
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 12]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
with commands, but they still may be reordered arbitrarily provided
|
||
they appear before positional arguments. Tagged arguments may be
|
||
mixed with optional arguments.
|
||
|
||
Tagged arguments SHOULD NOT take tagged arguments as arguments.
|
||
|
||
2.6.3. Optional Arguments
|
||
|
||
Optional arguments are exactly like tagged arguments except that they
|
||
may be left out, in which case a default value is implied. Because
|
||
optional arguments tend to result in shorter scripts, they have been
|
||
used far more than tagged arguments.
|
||
|
||
One particularly noteworthy case is the ":comparator" argument, which
|
||
allows the user to specify which comparator [COLLATION] will be used
|
||
to compare two strings, since different languages may impose
|
||
different orderings on UTF-8 [UTF-8] strings.
|
||
|
||
2.6.4. Types of Arguments
|
||
|
||
Abstractly, arguments may be literal data, tests, or blocks of
|
||
commands. In this way, an "if" control structure is merely a command
|
||
that happens to take a test and a block as arguments and may execute
|
||
the block of code.
|
||
|
||
However, this abstraction is ambiguous from a parsing standpoint.
|
||
|
||
The grammar in section 8.2 presents a parsable version of this:
|
||
Arguments are string lists (string-lists), numbers, and tags, which
|
||
may be followed by a test or a test list (test-list), which may be
|
||
followed by a block of commands. No more than one test or test list,
|
||
or more than one block of commands, may be used, and commands that
|
||
end with a block of commands do not end with semicolons.
|
||
|
||
2.7. String Comparison
|
||
|
||
When matching one string against another, there are a number of ways
|
||
of performing the match operation. These are accomplished with three
|
||
types of matches: an exact match, a substring match, and a wildcard
|
||
glob-style match. These are described below.
|
||
|
||
In order to provide for matches between character sets and case
|
||
insensitivity, Sieve uses the comparators defined in the Internet
|
||
Application Protocol Collation Registry [COLLATION].
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 13]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
However, when a string represents the name of a header, the
|
||
comparator is never user-specified. Header comparisons are always
|
||
done with the "i;ascii-casemap" operator, i.e., case-insensitive
|
||
comparisons, because this is the way things are defined in the
|
||
message specification [IMAIL].
|
||
|
||
2.7.1. Match Type
|
||
|
||
Commands that perform string comparisons may have an optional match
|
||
type argument. The three match types in this specification are
|
||
":contains", ":is", and ":matches".
|
||
|
||
The ":contains" match type describes a substring match. If the value
|
||
argument contains the key argument as a substring, the match is true.
|
||
For instance, the string "frobnitzm" contains "frob" and "nit", but
|
||
not "fbm". The empty key ("") is contained in all values.
|
||
|
||
The ":is" match type describes an absolute match; if the contents of
|
||
the first string are absolutely the same as the contents of the
|
||
second string, they match. Only the string "frobnitzm" is the string
|
||
"frobnitzm". The empty key ("") only ":is" matches with the empty
|
||
value.
|
||
|
||
The ":matches" match type specifies a wildcard match using the
|
||
characters "*" and "?"; the entire value must be matched. "*"
|
||
matches zero or more characters in the value and "?" matches a single
|
||
character in the value, where the comparator that is used (see
|
||
section 2.7.3) defines what a character is. For example, the
|
||
comparators "i;octet" and "i;ascii-casemap" define a character to be
|
||
a single octet, so "?" will always match exactly one octet when one
|
||
of those comparators is in use. In contrast, a Unicode-based
|
||
comparator would define a character to be any UTF-8 octet sequence
|
||
encoding one Unicode character and thus "?" may match more than one
|
||
octet. "?" and "*" may be escaped as "\\?" and "\\*" in strings to
|
||
match against themselves. The first backslash escapes the second
|
||
backslash; together, they escape the "*". This is awkward, but it is
|
||
commonplace in several programming languages that use globs and
|
||
regular expressions.
|
||
|
||
In order to specify what type of match is supposed to happen,
|
||
commands that support matching take optional arguments ":matches",
|
||
":is", and ":contains". Commands default to using ":is" matching if
|
||
no match type argument is supplied. Note that these modifiers
|
||
interact with comparators; in particular, only comparators that
|
||
support the "substring match" operation are suitable for matching
|
||
with ":contains" or ":matches". It is an error to use a comparator
|
||
with ":contains" or ":matches" that is not compatible with it.
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 14]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
It is an error to give more than one of these arguments to a given
|
||
command.
|
||
|
||
For convenience, the "MATCH-TYPE" syntax element is defined here as
|
||
follows:
|
||
|
||
Syntax: ":is" / ":contains" / ":matches"
|
||
|
||
2.7.2. Comparisons across Character Sets
|
||
|
||
Messages may involve a number of character sets. In order for
|
||
comparisons to work across character sets, implementations SHOULD
|
||
implement the following behavior:
|
||
|
||
Comparisons are performed on octets. Implementations convert text
|
||
from header fields in all charsets [MIME3] to Unicode, encoded as
|
||
UTF-8, as input to the comparator (see section 2.7.3).
|
||
Implementations MUST be capable of converting US-ASCII, ISO-8859-
|
||
1, the US-ASCII subset of ISO-8859-* character sets, and UTF-8.
|
||
Text that the implementation cannot convert to Unicode for any
|
||
reason MAY be treated as plain US-ASCII (including any [MIME3]
|
||
syntax) or processed according to local conventions. An encoded
|
||
NUL octet (character zero) SHOULD NOT cause early termination of
|
||
the header content being compared against.
|
||
|
||
If implementations fail to support the above behavior, they MUST
|
||
conform to the following:
|
||
|
||
No two strings can be considered equal if one contains octets
|
||
greater than 127.
|
||
|
||
2.7.3. Comparators
|
||
|
||
In order to allow for language-independent, case-independent matches,
|
||
the match type may be coupled with a comparator name. The Internet
|
||
Application Protocol Collation Registry [COLLATION] provides the
|
||
framework for describing and naming comparators.
|
||
|
||
All implementations MUST support the "i;octet" comparator (simply
|
||
compares octets) and the "i;ascii-casemap" comparator (which treats
|
||
uppercase and lowercase characters in the US-ASCII subset of UTF-8 as
|
||
the same). If left unspecified, the default is "i;ascii-casemap".
|
||
|
||
Some comparators may not be usable with substring matches; that is,
|
||
they may only work with ":is". It is an error to try to use a
|
||
comparator with ":matches" or ":contains" that is not compatible with
|
||
it.
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 15]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
Sieve treats a comparator result of "undefined" the same as a result
|
||
of "no-match". That is, this base specification does not provide any
|
||
means to directly detect invalid comparator input.
|
||
|
||
A comparator is specified by the ":comparator" option with commands
|
||
that support matching. This option is followed by a string providing
|
||
the name of the comparator to be used. For convenience, the syntax
|
||
of a comparator is abbreviated to "COMPARATOR", and (repeated in
|
||
several tests) is as follows:
|
||
|
||
Syntax: ":comparator" <comparator-name: string>
|
||
|
||
So in this example,
|
||
|
||
Example: if header :contains :comparator "i;octet" "Subject"
|
||
"MAKE MONEY FAST" {
|
||
discard;
|
||
}
|
||
|
||
would discard any message with subjects like "You can MAKE MONEY
|
||
FAST", but not "You can Make Money Fast", since the comparator used
|
||
is case-sensitive.
|
||
|
||
Comparators other than "i;octet" and "i;ascii-casemap" must be
|
||
declared with require, as they are extensions. If a comparator
|
||
declared with require is not known, it is an error, and execution
|
||
fails. If the comparator is not declared with require, it is also an
|
||
error, even if the comparator is supported. (See section 2.10.5.)
|
||
|
||
Both ":matches" and ":contains" match types are compatible with the
|
||
"i;octet" and "i;ascii-casemap" comparators and may be used with
|
||
them.
|
||
|
||
It is an error to give more than one of these arguments to a given
|
||
command.
|
||
|
||
2.7.4. Comparisons against Addresses
|
||
|
||
Addresses are one of the most frequent things represented as strings.
|
||
These are structured, and being able to compare against the local-
|
||
part or the domain of an address is useful, so some tests that act
|
||
exclusively on addresses take an additional optional argument that
|
||
specifies what the test acts on.
|
||
|
||
These optional arguments are ":localpart", ":domain", and ":all",
|
||
which act on the local-part (left side), the domain-part (right
|
||
side), and the whole address.
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 16]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
If an address is not syntactically valid, then it will not be matched
|
||
by tests specifying ":localpart" or ":domain".
|
||
|
||
The kind of comparison done, such as whether or not the test done is
|
||
case-insensitive, is specified as a comparator argument to the test.
|
||
|
||
If an optional address-part is omitted, the default is ":all".
|
||
|
||
It is an error to give more than one of these arguments to a given
|
||
command.
|
||
|
||
For convenience, the "ADDRESS-PART" syntax element is defined here as
|
||
follows:
|
||
|
||
Syntax: ":localpart" / ":domain" / ":all"
|
||
|
||
2.8. Blocks
|
||
|
||
Blocks are sets of commands enclosed within curly braces and supplied
|
||
as the final argument to a command. Such a command is a control
|
||
structure: when executed it has control over the number of times the
|
||
commands in the block are executed.
|
||
|
||
With the commands supplied in this memo, there are no loops. The
|
||
control structures supplied--if, elsif, and else--run a block either
|
||
once or not at all.
|
||
|
||
2.9. Commands
|
||
|
||
Sieve scripts are sequences of commands. Commands can take any of
|
||
the tokens above as arguments, and arguments may be either tagged or
|
||
positional arguments. Not all commands take all arguments.
|
||
|
||
There are three kinds of commands: test commands, action commands,
|
||
and control commands.
|
||
|
||
The simplest is an action command. An action command is an
|
||
identifier followed by zero or more arguments, terminated by a
|
||
semicolon. Action commands do not take tests or blocks as arguments.
|
||
The actions referenced in this document are:
|
||
|
||
- keep, to save the message in the default location
|
||
- fileinto, to save the message in a specific mailbox
|
||
- redirect, to forward the message to another address
|
||
- discard, to silently throw away the message
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 17]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
A control command is a command that affects the parsing or the flow
|
||
of execution of the Sieve script in some way. A control structure is
|
||
a control command that ends with a block instead of a semicolon.
|
||
|
||
A test command is used as part of a control command. It is used to
|
||
specify whether or not the block of code given to the control command
|
||
is executed.
|
||
|
||
2.10. Evaluation
|
||
|
||
2.10.1. Action Interaction
|
||
|
||
Some actions cannot be used with other actions because the result
|
||
would be absurd. These restrictions are noted throughout this memo.
|
||
|
||
Extension actions MUST state how they interact with actions defined
|
||
in this specification.
|
||
|
||
2.10.2. Implicit Keep
|
||
|
||
Previous experience with filtering systems suggests that cases tend
|
||
to be missed in scripts. To prevent errors, Sieve has an "implicit
|
||
keep".
|
||
|
||
An implicit keep is a keep action (see section 4.3) performed in
|
||
absence of any action that cancels the implicit keep.
|
||
|
||
An implicit keep is performed if a message is not written to a
|
||
mailbox, redirected to a new address, or explicitly thrown out. That
|
||
is, if a fileinto, a keep, a redirect, or a discard is performed, an
|
||
implicit keep is not.
|
||
|
||
Some actions may be defined to not cancel the implicit keep. These
|
||
actions may not directly affect the delivery of a message, and are
|
||
used for their side effects. None of the actions specified in this
|
||
document meet that criteria, but extension actions may.
|
||
|
||
For instance, with any of the short messages offered above, the
|
||
following script produces no actions.
|
||
|
||
Example: if size :over 500K { discard; }
|
||
|
||
As a result, the implicit keep is taken.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 18]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
2.10.3. Message Uniqueness in a Mailbox
|
||
|
||
Implementations SHOULD NOT deliver a message to the same mailbox more
|
||
than once, even if a script explicitly asks for a message to be
|
||
written to a mailbox twice.
|
||
|
||
The test for equality of two messages is implementation-defined.
|
||
|
||
If a script asks for a message to be written to a mailbox twice, it
|
||
MUST NOT be treated as an error.
|
||
|
||
2.10.4. Limits on Numbers of Actions
|
||
|
||
Site policy MAY limit the number of actions taken and MAY impose
|
||
restrictions on which actions can be used together. In the event
|
||
that a script hits a policy limit on the number of actions taken for
|
||
a particular message, an error occurs.
|
||
|
||
Implementations MUST allow at least one keep or one fileinto. If
|
||
fileinto is not implemented, implementations MUST allow at least one
|
||
keep.
|
||
|
||
2.10.5. Extensions and Optional Features
|
||
|
||
Because of the differing capabilities of many mail systems, several
|
||
features of this specification are optional. Before any of these
|
||
extensions can be executed, they must be declared with the "require"
|
||
action.
|
||
|
||
If an extension is not enabled with "require", implementations MUST
|
||
treat it as if they did not support it at all. This protects scripts
|
||
from having their behavior altered by extensions that the script
|
||
author might not have even been aware of.
|
||
|
||
Implementations MUST NOT execute any Sieve script test or command
|
||
subsequent to "require" if one of the required extensions is
|
||
unavailable.
|
||
|
||
Note: The reason for this restriction is that prior experiences
|
||
with languages such as LISP and Tcl suggest that this is a
|
||
workable way of noting that a given script uses an extension.
|
||
|
||
Extensions that define actions MUST state how they interact with
|
||
actions discussed in the base specification.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 19]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
2.10.6. Errors
|
||
|
||
In any programming language, there are compile-time and run-time
|
||
errors.
|
||
|
||
Compile-time errors are ones in syntax that are detectable if a
|
||
syntax check is done.
|
||
|
||
Run-time errors are not detectable until the script is run. This
|
||
includes transient failures like disk full conditions, but also
|
||
includes issues like invalid combinations of actions.
|
||
|
||
When an error occurs in a Sieve script, all processing stops.
|
||
|
||
Implementations MAY choose to do a full parse, then evaluate the
|
||
script, then do all actions. Implementations might even go so far as
|
||
to ensure that execution is atomic (either all actions are executed
|
||
or none are executed).
|
||
|
||
Other implementations may choose to parse and run at the same time.
|
||
Such implementations are simpler, but have issues with partial
|
||
failure (some actions happen, others don't).
|
||
|
||
Implementations MUST perform syntactic, semantic, and run-time checks
|
||
on code that is actually executed. Implementations MAY perform those
|
||
checks or any part of them on code that is not reached during
|
||
execution.
|
||
|
||
When an error happens, implementations MUST notify the user that an
|
||
error occurred and which actions (if any) were taken, and do an
|
||
implicit keep.
|
||
|
||
2.10.7. Limits on Execution
|
||
|
||
Implementations may limit certain constructs. However, this
|
||
specification places a lower bound on some of these limits.
|
||
|
||
Implementations MUST support fifteen levels of nested blocks.
|
||
|
||
Implementations MUST support fifteen levels of nested test lists.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 20]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
3. Control Commands
|
||
|
||
Control structures are needed to allow for multiple and conditional
|
||
actions.
|
||
|
||
3.1. Control if
|
||
|
||
There are three pieces to if: "if", "elsif", and "else". Each is
|
||
actually a separate command in terms of the grammar. However, an
|
||
elsif or else MUST only follow an if or elsif. An error occurs if
|
||
these conditions are not met.
|
||
|
||
Usage: if <test1: test> <block1: block>
|
||
|
||
Usage: elsif <test2: test> <block2: block>
|
||
|
||
Usage: else <block3: block>
|
||
|
||
The semantics are similar to those of any of the many other
|
||
programming languages these control structures appear in. When the
|
||
interpreter sees an "if", it evaluates the test associated with it.
|
||
If the test is true, it executes the block associated with it.
|
||
|
||
If the test of the "if" is false, it evaluates the test of the first
|
||
"elsif" (if any). If the test of "elsif" is true, it runs the
|
||
elsif's block. An elsif may be followed by an elsif, in which case,
|
||
the interpreter repeats this process until it runs out of elsifs.
|
||
|
||
When the interpreter runs out of elsifs, there may be an "else" case.
|
||
If there is, and none of the if or elsif tests were true, the
|
||
interpreter runs the else's block.
|
||
|
||
This provides a way of performing exactly one of the blocks in the
|
||
chain.
|
||
|
||
In the following example, both messages A and B are dropped.
|
||
|
||
Example: require "fileinto";
|
||
if header :contains "from" "coyote" {
|
||
discard;
|
||
} elsif header :contains ["subject"] ["$$$"] {
|
||
discard;
|
||
} else {
|
||
fileinto "INBOX";
|
||
}
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 21]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
When the script below is run over message A, it redirects the message
|
||
to acm@example.com; message B, to postmaster@example.com; any other
|
||
message is redirected to field@example.com.
|
||
|
||
Example: if header :contains ["From"] ["coyote"] {
|
||
redirect "acm@example.com";
|
||
} elsif header :contains "Subject" "$$$" {
|
||
redirect "postmaster@example.com";
|
||
} else {
|
||
redirect "field@example.com";
|
||
}
|
||
|
||
Note that this definition prohibits the "... else if ..." sequence
|
||
used by C. This is intentional, because this construct produces a
|
||
shift-reduce conflict.
|
||
|
||
3.2. Control require
|
||
|
||
Usage: require <capabilities: string-list>
|
||
|
||
The require action notes that a script makes use of a certain
|
||
extension. Such a declaration is required to use the extension, as
|
||
discussed in section 2.10.5. Multiple capabilities can be declared
|
||
with a single require.
|
||
|
||
The require command, if present, MUST be used before anything other
|
||
than a require can be used. An error occurs if a require appears
|
||
after a command other than require.
|
||
|
||
Example: require ["fileinto", "reject"];
|
||
|
||
Example: require "fileinto";
|
||
require "vacation";
|
||
|
||
3.3. Control stop
|
||
|
||
Usage: stop
|
||
|
||
The "stop" action ends all processing. If the implicit keep has not
|
||
been cancelled, then it is taken.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 22]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
4. Action Commands
|
||
|
||
This document supplies four actions that may be taken on a message:
|
||
keep, fileinto, redirect, and discard.
|
||
|
||
Implementations MUST support the "keep", "discard", and "redirect"
|
||
actions.
|
||
|
||
Implementations SHOULD support "fileinto".
|
||
|
||
Implementations MAY limit the number of certain actions taken (see
|
||
section 2.10.4).
|
||
|
||
4.1. Action fileinto
|
||
|
||
Usage: fileinto <mailbox: string>
|
||
|
||
The "fileinto" action delivers the message into the specified
|
||
mailbox. Implementations SHOULD support fileinto, but in some
|
||
environments this may be impossible. Implementations MAY place
|
||
restrictions on mailbox names; use of an invalid mailbox name MAY be
|
||
treated as an error or result in delivery to an implementation-
|
||
defined mailbox. If the specified mailbox doesn't exist, the
|
||
implementation MAY treat it as an error, create the mailbox, or
|
||
deliver the message to an implementation-defined mailbox. If the
|
||
implementation uses a different encoding scheme than UTF-8 for
|
||
mailbox names, it SHOULD reencode the mailbox name from UTF-8 to its
|
||
encoding scheme. For example, the Internet Message Access Protocol
|
||
[IMAP] uses modified UTF-7, such that a mailbox argument of "odds &
|
||
ends" would appear in IMAP as "odds &- ends".
|
||
|
||
The capability string for use with the require command is "fileinto".
|
||
|
||
In the following script, message A is filed into mailbox
|
||
"INBOX.harassment".
|
||
|
||
Example: require "fileinto";
|
||
if header :contains ["from"] "coyote" {
|
||
fileinto "INBOX.harassment";
|
||
}
|
||
|
||
4.2. Action redirect
|
||
|
||
Usage: redirect <address: string>
|
||
|
||
The "redirect" action is used to send the message to another user at
|
||
a supplied address, as a mail forwarding feature does. The
|
||
"redirect" action makes no changes to the message body or existing
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 23]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
headers, but it may add new headers. In particular, existing
|
||
Received headers MUST be preserved and the count of Received headers
|
||
in the outgoing message MUST be larger than the same count on the
|
||
message as received by the implementation. (An implementation that
|
||
adds a Received header before processing the message does not need to
|
||
add another when redirecting.)
|
||
|
||
The message is sent back out with the address from the redirect
|
||
command as an envelope recipient. Implementations MAY combine
|
||
separate redirects for a given message into a single submission with
|
||
multiple envelope recipients. (This is not a Mail User Agent (MUA)-
|
||
style forward, which creates a new message with a different sender
|
||
and message ID, wrapping the old message in a new one.)
|
||
|
||
The envelope sender address on the outgoing message is chosen by the
|
||
sieve implementation. It MAY be copied from the message being
|
||
processed. However, if the message being processed has an empty
|
||
envelope sender address the outgoing message MUST also have an empty
|
||
envelope sender address. This last requirement is imposed to prevent
|
||
loops in the case where a message is redirected to an invalid address
|
||
when then returns a delivery status notification that also ends up
|
||
being redirected to the same invalid address.
|
||
|
||
A simple script can be used for redirecting all mail:
|
||
|
||
Example: redirect "bart@example.com";
|
||
|
||
Implementations MUST take measures to implement loop control,
|
||
possibly including adding headers to the message or counting Received
|
||
headers as specified in section 6.2 of [SMTP]. If an implementation
|
||
detects a loop, it causes an error.
|
||
|
||
Implementations MUST provide means of limiting the number of
|
||
redirects a Sieve script can perform. See section 10 for more
|
||
details.
|
||
|
||
Implementations MAY ignore a redirect action silently due to policy
|
||
reasons. For example, an implementation MAY choose not to redirect
|
||
to an address that is known to be undeliverable. Any ignored
|
||
redirect MUST NOT cancel the implicit keep.
|
||
|
||
4.3. Action keep
|
||
|
||
Usage: keep
|
||
|
||
The "keep" action is whatever action is taken in lieu of all other
|
||
actions, if no filtering happens at all; generally, this simply means
|
||
to file the message into the user's main mailbox. This command
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 24]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
provides a way to execute this action without needing to know the
|
||
name of the user's main mailbox, providing a way to call it without
|
||
needing to understand the user's setup or the underlying mail system.
|
||
|
||
For instance, in an implementation where the IMAP server is running
|
||
scripts on behalf of the user at time of delivery, a keep command is
|
||
equivalent to a fileinto "INBOX".
|
||
|
||
Example: if size :under 1M { keep; } else { discard; }
|
||
|
||
Note that the above script is identical to the one below.
|
||
|
||
Example: if not size :under 1M { discard; }
|
||
|
||
4.4. Action discard
|
||
|
||
Usage: discard
|
||
|
||
Discard is used to silently throw away the message. It does so by
|
||
simply canceling the implicit keep. If discard is used with other
|
||
actions, the other actions still happen. Discard is compatible with
|
||
all other actions. (For instance, fileinto+discard is equivalent to
|
||
fileinto.)
|
||
|
||
Discard MUST be silent; that is, it MUST NOT return a non-delivery
|
||
notification of any kind ([DSN], [MDN], or otherwise).
|
||
|
||
In the following script, any mail from "idiot@example.com" is thrown
|
||
out.
|
||
|
||
Example: if header :contains ["from"] ["idiot@example.com"] {
|
||
discard;
|
||
}
|
||
|
||
While an important part of this language, "discard" has the potential
|
||
to create serious problems for users: Students who leave themselves
|
||
logged in to an unattended machine in a public computer lab may find
|
||
their script changed to just "discard". In order to protect users in
|
||
this situation (along with similar situations), implementations MAY
|
||
keep messages destroyed by a script for an indefinite period, and MAY
|
||
disallow scripts that throw out all mail.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 25]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
5. Test Commands
|
||
|
||
Tests are used in conditionals to decide which part(s) of the
|
||
conditional to execute.
|
||
|
||
Implementations MUST support these tests: "address", "allof",
|
||
"anyof", "exists", "false", "header", "not", "size", and "true".
|
||
|
||
Implementations SHOULD support the "envelope" test.
|
||
|
||
5.1. Test address
|
||
|
||
Usage: address [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE]
|
||
<header-list: string-list> <key-list: string-list>
|
||
|
||
The "address" test matches Internet addresses in structured headers
|
||
that contain addresses. It returns true if any header contains any
|
||
key in the specified part of the address, as modified by the
|
||
comparator and the match keyword. Whether there are other addresses
|
||
present in the header doesn't affect this test; this test does not
|
||
provide any way to determine whether an address is the only address
|
||
in a header.
|
||
|
||
Like envelope and header, this test returns true if any combination
|
||
of the header-list and key-list arguments match and returns false
|
||
otherwise.
|
||
|
||
Internet email addresses [IMAIL] have the somewhat awkward
|
||
characteristic that the local-part to the left of the at-sign is
|
||
considered case sensitive, and the domain-part to the right of the
|
||
at-sign is case insensitive. The "address" command does not deal
|
||
with this itself, but provides the ADDRESS-PART argument for allowing
|
||
users to deal with it.
|
||
|
||
The address primitive never acts on the phrase part of an email
|
||
address or on comments within that address. It also never acts on
|
||
group names, although it does act on the addresses within the group
|
||
construct.
|
||
|
||
Implementations MUST restrict the address test to headers that
|
||
contain addresses, but MUST include at least From, To, Cc, Bcc,
|
||
Sender, Resent-From, and Resent-To, and it SHOULD include any other
|
||
header that utilizes an "address-list" structured header body.
|
||
|
||
Example: if address :is :all "from" "tim@example.com" {
|
||
discard;
|
||
}
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 26]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
5.2. Test allof
|
||
|
||
Usage: allof <tests: test-list>
|
||
|
||
The "allof" test performs a logical AND on the tests supplied to it.
|
||
|
||
Example: allof (false, false) => false
|
||
allof (false, true) => false
|
||
allof (true, true) => true
|
||
|
||
The allof test takes as its argument a test-list.
|
||
|
||
5.3. Test anyof
|
||
|
||
Usage: anyof <tests: test-list>
|
||
|
||
The "anyof" test performs a logical OR on the tests supplied to it.
|
||
|
||
Example: anyof (false, false) => false
|
||
anyof (false, true) => true
|
||
anyof (true, true) => true
|
||
|
||
5.4. Test envelope
|
||
|
||
Usage: envelope [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE]
|
||
<envelope-part: string-list> <key-list: string-list>
|
||
|
||
The "envelope" test is true if the specified part of the [SMTP] (or
|
||
equivalent) envelope matches the specified key. This specification
|
||
defines the interpretation of the (case insensitive) "from" and "to"
|
||
envelope-parts. Additional envelope-parts may be defined by other
|
||
extensions; implementations SHOULD consider unknown envelope parts an
|
||
error.
|
||
|
||
If one of the envelope-part strings is (case insensitive) "from",
|
||
then matching occurs against the FROM address used in the SMTP MAIL
|
||
command. The null reverse-path is matched against as the empty
|
||
string, regardless of the ADDRESS-PART argument specified.
|
||
|
||
If one of the envelope-part strings is (case insensitive) "to", then
|
||
matching occurs against the TO address used in the SMTP RCPT command
|
||
that resulted in this message getting delivered to this user. Note
|
||
that only the most recent TO is available, and only the one relevant
|
||
to this user.
|
||
|
||
The envelope-part is a string list and may contain more than one
|
||
parameter, in which case all of the strings specified in the key-list
|
||
are matched against all parts given in the envelope-part list.
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 27]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
Like address and header, this test returns true if any combination of
|
||
the envelope-part list and key-list arguments match and returns false
|
||
otherwise.
|
||
|
||
All tests against envelopes MUST drop source routes.
|
||
|
||
If the SMTP transaction involved several RCPT commands, only the data
|
||
from the RCPT command that caused delivery to this user is available
|
||
in the "to" part of the envelope.
|
||
|
||
If a protocol other than SMTP is used for message transport,
|
||
implementations are expected to adapt this command appropriately.
|
||
|
||
The envelope command is optional. Implementations SHOULD support it,
|
||
but the necessary information may not be available in all cases. The
|
||
capability string for use with the require command is "envelope".
|
||
|
||
Example: require "envelope";
|
||
if envelope :all :is "from" "tim@example.com" {
|
||
discard;
|
||
}
|
||
|
||
5.5. Test exists
|
||
|
||
Usage: exists <header-names: string-list>
|
||
|
||
The "exists" test is true if the headers listed in the header-names
|
||
argument exist within the message. All of the headers must exist or
|
||
the test is false.
|
||
|
||
The following example throws out mail that doesn't have a From header
|
||
and a Date header.
|
||
|
||
Example: if not exists ["From","Date"] {
|
||
discard;
|
||
}
|
||
|
||
5.6. Test false
|
||
|
||
Usage: false
|
||
|
||
The "false" test always evaluates to false.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 28]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
5.7. Test header
|
||
|
||
Usage: header [COMPARATOR] [MATCH-TYPE]
|
||
<header-names: string-list> <key-list: string-list>
|
||
|
||
The "header" test evaluates to true if the value of any of the named
|
||
headers, ignoring leading and trailing whitespace, matches any key.
|
||
The type of match is specified by the optional match argument, which
|
||
defaults to ":is" if not specified, as specified in section 2.6.
|
||
|
||
Like address and envelope, this test returns true if any combination
|
||
of the header-names list and key-list arguments match and returns
|
||
false otherwise.
|
||
|
||
If a header listed in the header-names argument exists, it contains
|
||
the empty key (""). However, if the named header is not present, it
|
||
does not match any key, including the empty key. So if a message
|
||
contained the header
|
||
|
||
X-Caffeine: C8H10N4O2
|
||
|
||
these tests on that header evaluate as follows:
|
||
|
||
header :is ["X-Caffeine"] [""] => false
|
||
header :contains ["X-Caffeine"] [""] => true
|
||
|
||
Testing whether a given header is either absent or doesn't contain
|
||
any non-whitespace characters can be done using a negated "header"
|
||
test:
|
||
|
||
not header :matches "Cc" "?*"
|
||
|
||
5.8. Test not
|
||
|
||
Usage: not <test1: test>
|
||
|
||
The "not" test takes some other test as an argument, and yields the
|
||
opposite result. "not false" evaluates to "true" and "not true"
|
||
evaluates to "false".
|
||
|
||
5.9. Test size
|
||
|
||
Usage: size <":over" / ":under"> <limit: number>
|
||
|
||
The "size" test deals with the size of a message. It takes either a
|
||
tagged argument of ":over" or ":under", followed by a number
|
||
representing the size of the message.
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 29]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
If the argument is ":over", and the size of the message is greater
|
||
than the number provided, the test is true; otherwise, it is false.
|
||
|
||
If the argument is ":under", and the size of the message is less than
|
||
the number provided, the test is true; otherwise, it is false.
|
||
|
||
Exactly one of ":over" or ":under" must be specified, and anything
|
||
else is an error.
|
||
|
||
The size of a message is defined to be the number of octets in the
|
||
[IMAIL] representation of the message.
|
||
|
||
Note that for a message that is exactly 4,000 octets, the message is
|
||
neither ":over" nor ":under" 4000 octets.
|
||
|
||
5.10. Test true
|
||
|
||
Usage: true
|
||
|
||
The "true" test always evaluates to true.
|
||
|
||
6. Extensibility
|
||
|
||
New control commands, actions, and tests can be added to the
|
||
language. Sites must make these features known to their users; this
|
||
document does not define a way to discover the list of extensions
|
||
supported by the server.
|
||
|
||
Any extensions to this language MUST define a capability string that
|
||
uniquely identifies that extension. Capability string are case-
|
||
sensitive; for example, "foo" and "FOO" are different capabilities.
|
||
If a new version of an extension changes the functionality of a
|
||
previously defined extension, it MUST use a different name.
|
||
Extensions may register a set of related capabilities by registering
|
||
just a unique prefix for them. The "comparator-" prefix is an
|
||
example of this. The prefix MUST end with a "-" and MUST NOT overlap
|
||
any existing registrations.
|
||
|
||
In a situation where there is a script submission protocol and an
|
||
extension advertisement mechanism aware of the details of this
|
||
language, scripts submitted can be checked against the mail server to
|
||
prevent use of an extension that the server does not support.
|
||
|
||
Extensions MUST state how they interact with constraints defined in
|
||
section 2.10, e.g., whether they cancel the implicit keep, and which
|
||
actions they are compatible and incompatible with. Extensions MUST
|
||
NOT change the behavior of the "require" control command or alter the
|
||
interpretation of the argument to the "require" control.
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 30]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
Extensions that can submit new email messages or otherwise generate
|
||
new protocol requests MUST consider loop suppression, at least to
|
||
document any security considerations.
|
||
|
||
6.1. Capability String
|
||
|
||
Capability strings are typically short strings describing what
|
||
capabilities are supported by the server.
|
||
|
||
Capability strings beginning with "vnd." represent vendor-defined
|
||
extensions. Such extensions are not defined by Internet standards or
|
||
RFCs, but are still registered with IANA in order to prevent
|
||
conflicts. Extensions starting with "vnd." SHOULD be followed by the
|
||
name of the vendor and product, such as "vnd.acme.rocket-sled".
|
||
|
||
The following capability strings are defined by this document:
|
||
|
||
encoded-character The string "encoded-character" indicates that the
|
||
implementation supports the interpretation of
|
||
"${hex:...}" and "${unicode:...}" in strings.
|
||
|
||
envelope The string "envelope" indicates that the implementation
|
||
supports the "envelope" command.
|
||
|
||
fileinto The string "fileinto" indicates that the implementation
|
||
supports the "fileinto" command.
|
||
|
||
comparator- The string "comparator-elbonia" is provided if the
|
||
implementation supports the "elbonia" comparator.
|
||
Therefore, all implementations have at least the
|
||
"comparator-i;octet" and "comparator-i;ascii-casemap"
|
||
capabilities. However, these comparators may be used
|
||
without being declared with require.
|
||
|
||
6.2. IANA Considerations
|
||
|
||
In order to provide a standard set of extensions, a registry is
|
||
maintained by IANA. This registry contains both vendor-controlled
|
||
capability names (beginning with "vnd.") and IETF-controlled
|
||
capability names. Vendor-controlled capability names may be
|
||
registered on a first-come, first-served basis, by applying to IANA
|
||
with the form in the following section. Registration of capability
|
||
prefixes that do not begin with "vnd." REQUIRES a standards track or
|
||
IESG-approved experimental RFC.
|
||
|
||
Extensions designed for interoperable use SHOULD use IETF-controlled
|
||
capability names.
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 31]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
6.2.1. Template for Capability Registrations
|
||
|
||
The following template is to be used for registering new Sieve
|
||
extensions with IANA.
|
||
|
||
To: iana@iana.org
|
||
Subject: Registration of new Sieve extension
|
||
|
||
Capability name: [the string for use in the 'require' statement]
|
||
Description: [a brief description of what the extension adds
|
||
or changes]
|
||
RFC number: [for extensions published as RFCs]
|
||
Contact address: [email and/or physical address to contact for
|
||
additional information]
|
||
|
||
6.2.2. Handling of Existing Capability Registrations
|
||
|
||
In order to bring the existing capability registrations in line with
|
||
the new template, IANA has modified each as follows:
|
||
|
||
1. The "capability name" and "capability arguments" fields have been
|
||
eliminated
|
||
2. The "capability keyword" field have been renamed to "Capability
|
||
name"
|
||
3. An empty "Description" field has been added
|
||
4. The "Standards Track/IESG-approved experimental RFC number" field
|
||
has been renamed to "RFC number"
|
||
5. The "Person and email address to contact for further information"
|
||
field should be renamed to "Contact address"
|
||
|
||
6.2.3. Initial Capability Registrations
|
||
|
||
This RFC updates the following entries in the IANA registry for Sieve
|
||
extensions.
|
||
|
||
Capability name: encoded-character
|
||
Description: changes the interpretation of strings to allow
|
||
arbitrary octets and Unicode characters to be
|
||
represented using US-ASCII
|
||
RFC number: RFC 5228 (Sieve base spec)
|
||
Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
|
||
|
||
Capability name: fileinto
|
||
Description: adds the 'fileinto' action for delivering to a
|
||
mailbox other than the default
|
||
RFC number: RFC 5228 (Sieve base spec)
|
||
Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 32]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
Capability name: envelope
|
||
Description: adds the 'envelope' test for testing the message
|
||
transport sender and recipient address
|
||
RFC number: RFC 5228 (Sieve base spec)
|
||
Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
|
||
|
||
Capability name: comparator-* (anything starting with "comparator-")
|
||
Description: adds the indicated comparator for use with the
|
||
:comparator argument
|
||
RFC number: RFC 5228 (Sieve base spec) and [COLLATION]
|
||
Contact address: The Sieve discussion list <ietf-mta-filters@imc.org>
|
||
|
||
6.3. Capability Transport
|
||
|
||
A method of advertising which capabilities an implementation supports
|
||
is difficult due to the wide range of possible implementations. Such
|
||
a mechanism, however, should have the property that the
|
||
implementation can advertise the complete set of extensions that it
|
||
supports.
|
||
|
||
7. Transmission
|
||
|
||
The [MIME] type for a Sieve script is "application/sieve".
|
||
|
||
The registration of this type for RFC 2048 requirements is updated as
|
||
follows:
|
||
|
||
Subject: Registration of MIME media type application/sieve
|
||
|
||
MIME media type name: application
|
||
MIME subtype name: sieve
|
||
Required parameters: none
|
||
Optional parameters: none
|
||
Encoding considerations: Most Sieve scripts will be textual,
|
||
written in UTF-8. When non-7bit characters are used,
|
||
quoted-printable is appropriate for transport systems
|
||
that require 7bit encoding.
|
||
Security considerations: Discussed in section 10 of this RFC.
|
||
Interoperability considerations: Discussed in section 2.10.5
|
||
of this RFC.
|
||
Published specification: this RFC.
|
||
Applications that use this media type: sieve-enabled mail
|
||
servers and clients
|
||
Additional information:
|
||
Magic number(s):
|
||
File extension(s): .siv .sieve
|
||
Macintosh File Type Code(s):
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 33]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
Person & email address to contact for further information:
|
||
See the discussion list at ietf-mta-filters@imc.org.
|
||
Intended usage:
|
||
COMMON
|
||
Author/Change controller:
|
||
The SIEVE WG, delegated by the IESG.
|
||
|
||
8. Parsing
|
||
|
||
The Sieve grammar is separated into tokens and a separate grammar as
|
||
most programming languages are. Additional rules are supplied here
|
||
for common arguments to various language facilities.
|
||
|
||
8.1. Lexical Tokens
|
||
|
||
Sieve scripts are encoded in UTF-8. The following assumes a valid
|
||
UTF-8 encoding; special characters in Sieve scripts are all US-ASCII.
|
||
|
||
The following are tokens in Sieve:
|
||
|
||
- identifiers
|
||
- tags
|
||
- numbers
|
||
- quoted strings
|
||
- multi-line strings
|
||
- other separators
|
||
|
||
Identifiers, tags, and numbers are case-insensitive, while quoted
|
||
strings and multi-line strings are case-sensitive.
|
||
|
||
Blanks, horizontal tabs, CRLFs, and comments ("whitespace") are
|
||
ignored except as they separate tokens. Some whitespace is required
|
||
to separate otherwise adjacent tokens and in specific places in the
|
||
multi-line strings. CR and LF can only appear in CRLF pairs.
|
||
|
||
The other separators are single individual characters and are
|
||
mentioned explicitly in the grammar.
|
||
|
||
The lexical structure of sieve is defined in the following grammar
|
||
(as described in [ABNF]):
|
||
|
||
bracket-comment = "/*" *not-star 1*STAR
|
||
*(not-star-slash *not-star 1*STAR) "/"
|
||
; No */ allowed inside a comment.
|
||
; (No * is allowed unless it is the last
|
||
; character, or unless it is followed by a
|
||
; character that isn't a slash.)
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 34]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
comment = bracket-comment / hash-comment
|
||
|
||
hash-comment = "#" *octet-not-crlf CRLF
|
||
|
||
identifier = (ALPHA / "_") *(ALPHA / DIGIT / "_")
|
||
|
||
multi-line = "text:" *(SP / HTAB) (hash-comment / CRLF)
|
||
*(multiline-literal / multiline-dotstart)
|
||
"." CRLF
|
||
|
||
multiline-literal = [ octet-not-period *octet-not-crlf ] CRLF
|
||
|
||
multiline-dotstart = "." 1*octet-not-crlf CRLF
|
||
; A line containing only "." ends the
|
||
; multi-line. Remove a leading '.' if
|
||
; followed by another '.'.
|
||
|
||
not-star = CRLF / %x01-09 / %x0B-0C / %x0E-29 / %x2B-FF
|
||
; either a CRLF pair, OR a single octet
|
||
; other than NUL, CR, LF, or star
|
||
|
||
not-star-slash = CRLF / %x01-09 / %x0B-0C / %x0E-29 / %x2B-2E /
|
||
%x30-FF
|
||
; either a CRLF pair, OR a single octet
|
||
; other than NUL, CR, LF, star, or slash
|
||
|
||
number = 1*DIGIT [ QUANTIFIER ]
|
||
|
||
octet-not-crlf = %x01-09 / %x0B-0C / %x0E-FF
|
||
; a single octet other than NUL, CR, or LF
|
||
|
||
octet-not-period = %x01-09 / %x0B-0C / %x0E-2D / %x2F-FF
|
||
; a single octet other than NUL,
|
||
; CR, LF, or period
|
||
|
||
octet-not-qspecial = %x01-09 / %x0B-0C / %x0E-21 / %x23-5B / %x5D-FF
|
||
; a single octet other than NUL,
|
||
; CR, LF, double-quote, or backslash
|
||
|
||
QUANTIFIER = "K" / "M" / "G"
|
||
|
||
quoted-other = "\" octet-not-qspecial
|
||
; represents just the octet-no-qspecial
|
||
; character. SHOULD NOT be used
|
||
|
||
quoted-safe = CRLF / octet-not-qspecial
|
||
; either a CRLF pair, OR a single octet other
|
||
; than NUL, CR, LF, double-quote, or backslash
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 35]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
quoted-special = "\" (DQUOTE / "\")
|
||
; represents just a double-quote or backslash
|
||
|
||
quoted-string = DQUOTE quoted-text DQUOTE
|
||
|
||
quoted-text = *(quoted-safe / quoted-special / quoted-other)
|
||
|
||
STAR = "*"
|
||
|
||
tag = ":" identifier
|
||
|
||
white-space = 1*(SP / CRLF / HTAB) / comment
|
||
|
||
8.2. Grammar
|
||
|
||
The following is the grammar of Sieve after it has been lexically
|
||
interpreted. No whitespace or comments appear below. The start
|
||
symbol is "start".
|
||
|
||
argument = string-list / number / tag
|
||
|
||
arguments = *argument [ test / test-list ]
|
||
|
||
block = "{" commands "}"
|
||
|
||
command = identifier arguments (";" / block)
|
||
|
||
commands = *command
|
||
|
||
start = commands
|
||
|
||
string = quoted-string / multi-line
|
||
|
||
string-list = "[" string *("," string) "]" / string
|
||
; if there is only a single string, the brackets
|
||
; are optional
|
||
|
||
test = identifier arguments
|
||
|
||
test-list = "(" test *("," test) ")"
|
||
|
||
8.3. Statement Elements
|
||
|
||
These elements are collected from the "Syntax" sections elsewhere in
|
||
this document, and are provided here in [ABNF] syntax so that they
|
||
can be modified by extensions.
|
||
|
||
ADDRESS-PART = ":localpart" / ":domain" / ":all"
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 36]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
COMPARATOR = ":comparator" string
|
||
|
||
MATCH-TYPE = ":is" / ":contains" / ":matches"
|
||
|
||
9. Extended Example
|
||
|
||
The following is an extended example of a Sieve script. Note that it
|
||
does not make use of the implicit keep.
|
||
|
||
#
|
||
# Example Sieve Filter
|
||
# Declare any optional features or extension used by the script
|
||
#
|
||
require ["fileinto"];
|
||
|
||
#
|
||
# Handle messages from known mailing lists
|
||
# Move messages from IETF filter discussion list to filter mailbox
|
||
#
|
||
if header :is "Sender" "owner-ietf-mta-filters@imc.org"
|
||
{
|
||
fileinto "filter"; # move to "filter" mailbox
|
||
}
|
||
#
|
||
# Keep all messages to or from people in my company
|
||
#
|
||
elsif address :DOMAIN :is ["From", "To"] "example.com"
|
||
{
|
||
keep; # keep in "In" mailbox
|
||
}
|
||
|
||
#
|
||
# Try and catch unsolicited email. If a message is not to me,
|
||
# or it contains a subject known to be spam, file it away.
|
||
#
|
||
elsif anyof (NOT address :all :contains
|
||
["To", "Cc", "Bcc"] "me@example.com",
|
||
header :matches "subject"
|
||
["*make*money*fast*", "*university*dipl*mas*"])
|
||
{
|
||
fileinto "spam"; # move to "spam" mailbox
|
||
}
|
||
else
|
||
{
|
||
# Move all other (non-company) mail to "personal"
|
||
# mailbox.
|
||
fileinto "personal";
|
||
}
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 37]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
10. Security Considerations
|
||
|
||
Users must get their mail. It is imperative that whatever
|
||
implementations use to store the user-defined filtering scripts
|
||
protect them from unauthorized modification, to preserve the
|
||
integrity of the mail system. An attacker who can modify a script
|
||
can cause mail to be discarded, rejected, or forwarded to an
|
||
unauthorized recipient. In addition, it's possible that Sieve
|
||
scripts might expose private information, such as mailbox names, or
|
||
email addresses of favored (or disfavored) correspondents. Because
|
||
of that, scripts SHOULD also be protected from unauthorized
|
||
retrieval.
|
||
|
||
Several commands, such as "discard", "redirect", and "fileinto",
|
||
allow for actions to be taken that are potentially very dangerous.
|
||
|
||
Use of the "redirect" command to generate notifications may easily
|
||
overwhelm the target address, especially if it was not designed to
|
||
handle large messages.
|
||
|
||
Allowing a single script to redirect to multiple destinations can be
|
||
used as a means of amplifying the number of messages in an attack.
|
||
Moreover, if loop detection is not properly implemented, it may be
|
||
possible to set up exponentially growing message loops. Accordingly,
|
||
Sieve implementations:
|
||
|
||
(1) MUST implement facilities to detect and break message loops. See
|
||
section 6.2 of [SMTP] for additional information on basic loop
|
||
detection strategies.
|
||
|
||
(2) MUST provide the means for administrators to limit the ability of
|
||
users to abuse redirect. In particular, it MUST be possible to
|
||
limit the number of redirects a script can perform.
|
||
Additionally, if no use cases exist for using redirect to
|
||
multiple destinations, this limit SHOULD be set to 1. Additional
|
||
limits, such as the ability to restrict redirect to local users,
|
||
MAY also be implemented.
|
||
|
||
(3) MUST provide facilities to log use of redirect in order to
|
||
facilitate tracking down abuse.
|
||
|
||
(4) MAY use script analysis to determine whether or not a given
|
||
script can be executed safely. While the Sieve language is
|
||
sufficiently complex that full analysis of all possible scripts
|
||
is computationally infeasible, the majority of real-world scripts
|
||
are amenable to analysis. For example, an implementation might
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 38]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
allow scripts that it has determined are safe to run unhindered,
|
||
block scripts that are potentially problematic, and subject
|
||
unclassifiable scripts to additional auditing and logging.
|
||
|
||
Allowing redirects at all may not be appropriate in situations where
|
||
email accounts are freely available and/or not trackable to a human
|
||
who can be held accountable for creating message bombs or other
|
||
abuse.
|
||
|
||
As with any filter on a message stream, if the Sieve implementation
|
||
and the mail agents 'behind' Sieve in the message stream differ in
|
||
their interpretation of the messages, it may be possible for an
|
||
attacker to subvert the filter. Of particular note are differences
|
||
in the interpretation of malformed messages (e.g., missing or extra
|
||
syntax characters) or those that exhibit corner cases (e.g., NUL
|
||
octets encoded via [MIME3]).
|
||
|
||
11. Acknowledgments
|
||
|
||
This document has been revised in part based on comments and
|
||
discussions that took place on and off the SIEVE mailing list.
|
||
Thanks to Sharon Chisholm, Cyrus Daboo, Ned Freed, Arnt Gulbrandsen,
|
||
Michael Haardt, Kjetil Torgrim Homme, Barry Leiba, Mark E. Mallett,
|
||
Alexey Melnikov, Eric Rescorla, Rob Siemborski, and Nigel Swinson for
|
||
reviews and suggestions.
|
||
|
||
12. Normative References
|
||
|
||
[ABNF] Crocker, D., Ed., and P. Overell, "Augmented BNF for
|
||
Syntax Specifications: ABNF", RFC 4234, October 2005.
|
||
|
||
[COLLATION] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
|
||
Application Protocol Collation Registry", RFC 4790, March
|
||
2007.
|
||
|
||
[IMAIL] Resnick, P., Ed., "Internet Message Format", RFC 2822,
|
||
April 2001.
|
||
|
||
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
|
||
Requirement Levels", BCP 14, RFC 2119, March 1997.
|
||
|
||
[MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
|
||
Extensions (MIME) Part One: Format of Internet Message
|
||
Bodies", RFC 2045, November 1996.
|
||
|
||
[MIME3] Moore, K., "MIME (Multipurpose Internet Mail Extensions)
|
||
Part Three: Message Header Extensions for Non-ASCII
|
||
Text", RFC 2047, November 1996.
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 39]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
[SMTP] Klensin, J., Ed., "Simple Mail Transfer Protocol", RFC
|
||
2821, April 2001.
|
||
|
||
[UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
|
||
10646", STD 63, RFC 3629, November 2003.
|
||
|
||
13. Informative References
|
||
|
||
[BINARY-SI] "Standard IEC 60027-2: Letter symbols to be used in
|
||
electrical technology - Part 2: Telecommunications and
|
||
electronics", January 1999.
|
||
|
||
[DSN] Moore, K. and G. Vaudreuil, "An Extensible Message Format
|
||
for Delivery Status Notifications", RFC 3464, January
|
||
2003.
|
||
|
||
[FLAMES] Borenstein, N, and C. Thyberg, "Power, Ease of Use, and
|
||
Cooperative Work in a Practical Multimedia Message
|
||
System", Int. J. of Man-Machine Studies, April, 1991.
|
||
Reprinted in Computer-Supported Cooperative Work and
|
||
Groupware, Saul Greenberg, editor, Harcourt Brace
|
||
Jovanovich, 1991. Reprinted in Readings in Groupware and
|
||
Computer-Supported Cooperative Work, Ronald Baecker,
|
||
editor, Morgan Kaufmann, 1993.
|
||
|
||
[IMAP] Crispin, M., "Internet Message Access Protocol - version
|
||
4rev1", RFC 3501, March 2003.
|
||
|
||
[MDN] Hansen, T., Ed., and G. Vaudreuil, Ed., "Message
|
||
Disposition Notification", RFC 3798, May 2004.
|
||
|
||
[RFC3028] Showalter, T., "Sieve: A Mail Filtering Language", RFC
|
||
3028, January 2001.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 40]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
14. Changes from RFC 3028
|
||
|
||
This following list is a summary of the changes that have been made
|
||
in the Sieve language base specification from [RFC3028].
|
||
|
||
1. Removed ban on tests having side-effects
|
||
2. Removed reject extension (will be specified in a separate RFC)
|
||
3. Clarified description of comparators to match [COLLATION], the
|
||
new base specification for them
|
||
4. Require stripping of leading and trailing whitespace in "header"
|
||
test
|
||
5. Clarified or tightened handling of many minor items, including:
|
||
- invalid [MIME3] encoding
|
||
- invalid addresses in headers
|
||
- invalid header field names in tests
|
||
- 'undefined' comparator result
|
||
- unknown envelope parts
|
||
- null return-path in "envelope" test
|
||
6. Capability strings are case-sensitive
|
||
7. Clarified that fileinto should reencode non-ASCII mailbox
|
||
names to match the mailstore's conventions
|
||
8. Errors in the ABNF were corrected
|
||
9. The references were updated and split into normative and
|
||
informative
|
||
10. Added encoded-character capability and deprecated (but did not
|
||
remove) use of arbitrary binary octets in Sieve scripts.
|
||
11. Updated IANA registration template, and added IANA
|
||
considerations to permit capability prefix registrations.
|
||
12. Added .sieve as a valid extension for Sieve scripts.
|
||
|
||
Editors' Addresses
|
||
|
||
Philip Guenther
|
||
Sendmail, Inc.
|
||
6425 Christie St. Ste 400
|
||
Emeryville, CA 94608
|
||
EMail: guenther@sendmail.com
|
||
|
||
Tim Showalter
|
||
EMail: tjs@psaux.com
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 41]
|
||
|
||
RFC 5228 Sieve: An Email Filtering Language January 2008
|
||
|
||
|
||
Full 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.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Guenther & Showalter Standards Track [Page 42]
|
||
|