Small documentation change from Michael Haardt.
[exim.git] / doc / doc-txt / README.SIEVE
d1d97a76 1$Cambridge: exim/doc/doc-txt/README.SIEVE,v 1.3 2005/03/29 15:21:57 ph10 Exp $
3 Notes on the Sieve implementation for Exim
5Exim Filter Versus Sieve Filter
7Exim supports two incompatible filters: The traditional Exim filter and
8the Sieve filter. Since Sieve is a extensible language, it is important
9to understand "Sieve" in this context as "the specific implementation
10of Sieve for Exim".
12The Exim filter contains more features, such as variable expansion, and
13better integration with the host environment, like external processes
14and pipes.
16Sieve is a standard for interoperable filters, defined in RFC 3028,
17with multiple implementations around. If interoperability is important,
18then there is no way around it.
21Exim Implementation
23The Exim Sieve implementation offers the core as defined by RFC 3028, the
24"envelope" (RFC 3028), the "fileinto" (RFC 3028), the "copy" (RFC 3894)
25and the "vacation" (draft-showalter-sieve-vacation-05.txt) extension,
26the "i;ascii-numeric" comparator, but not the "reject" extension.
27Exim does not support MDMs, so adding it just to the sieve filter makes
28little sense.
30The Sieve filter is integrated in Exim and works very similar to the
31Exim filter: Sieve scripts are recognized by the first line containing
32"# sieve filter". When using "keep" or "fileinto" to save a mail into a
33folder, the resulting string is available as the variable $address_file
34in the transport that stores it. A suitable transport could be:
37 driver = appendfile
38 file = ${if eq{$address_file}{inbox} \
39 {/var/mail/$local_part} \
40 {${if eq{${substr_0_1:$address_file}}{/} \
41 {$address_file} \
42 {$home/$address_file} \
43 }} \
44 }
45 delivery_date_add
46 envelope_to_add
47 return_path_add
48 mode = 0600
50Absolute files are stored where specified, relative files are stored
51relative to $home and "inbox" goes to the standard mailbox location.
53To enable "vacation", set sieve_vacation_directory for the router to
54the directory where vacation databases are held (don't put anything
55else in that directory) and point reply_transport to an autoreply
59RFC Compliance
61Exim requires the first line to be "# sieve filter". Of course the RFC
62does not enforce that line. Don't expect examples to work without adding
63it, though.
65RFC 3028 requires using CRLF to terminate the end of a line.
66The rationale was that CRLF is universally used in network protocols
67to mark the end of the line. This implementation does not embed Sieve
68in a network protocol, but uses Sieve scripts as part of the Exim MTA.
69Since all parts of Exim use \n as newline character, this implementation
70does, too. You can change this by defining the macro RFC_EOL at compile
71time to enforce CRLF being used.
73Exim violates RFC 2822, section 3.6.8, by accepting 8-bit header names, so
74this implementation repeats this violation to stay consistent with Exim.
75This is in preparation to UTF-8 data.
77Sieve scripts can not contain NUL characters in strings, but mail
78headers could contain MIME encoded NUL characters, which could never
79be matched by Sieve scripts using exact comparisons. For that reason,
80this implementation extends the Sieve quoted string syntax with \0
81to describe a NUL character, violating \0 being the same as 0 in
82RFC 3028. Even without using \0, the following tests are all true in
83this implementation. Implementations that use C-style strings will only
84evaulate the first test as true.
86Subject: =?iso-8859-1?q?abc=00def
88header :contains "Subject" ["abc"]
89header :contains "Subject" ["def"]
90header :matches "Subject" ["abc?def"]
92Note that by considering Sieve to be a MUA, RFC 2047 can be interpreted
93in a way that NUL characters truncating strings is allowed for Sieve
94implementations, although not recommended. It is further allowed to use
95encoded NUL characters in headers, but that's not recommended either.
96The above example shows why. Good code should still be able to deal
97with it.
99RFC 3028 states that if an implementation fails to convert a character
100set to UTF-8, two strings can not be equal if one contains octects greater
101than 127. Assuming that all unknown character sets are one-byte character
102sets with the lower 128 octects being US-ASCII is not sound, so this
103implementation violates RFC 3028 and treats such MIME words literally.
104That way at least something could be matched.
106The folder specified by "fileinto" must not contain the character
107sequence ".." to avoid security problems. RFC 3028 does not specifiy the
108syntax of folders apart from keep being equivalent to fileinto "INBOX".
109This implementation uses "inbox" instead.
111Sieve script errors currently cause that messages are silently filed into
112"inbox". RFC 3028 requires that the user is notified of that condition.
113This may be implemented in future by adding a header line to mails that
114are filed into "inbox" due to an error in the filter.
d1d97a76 117Strings Containing Header Names Or Envelope Elements
119RFC 3028 does not specify what happens if a string denoting a header
120field or envelope element does not contain a valid name, e.g. it
121contains a colon for a header or it is not "from" or "to" for envelopes.
495ae4b0 122This implementation generates an error instead of ignoring the header
123field in order to ease script debugging, which fits in the common picture
124of Sieve.
127Header Test With Invalid MIME Encoding In Header
129Some MUAs process invalid base64 encoded data, generating junk.
130Others ignore junk after seeing an equal sign in base64 encoded data.
131RFC 2047 does not specify how to react in this case, other than stating
132that a client must not forbid to process a message for that reason.
133RFC 2045 specifies that invalid data should be ignored (appearantly
134looking at end of line characters). It also specifies that invalid data
135may lead to rejecting messages containing them (and there it appears to
136talk about true encoding violations), which is a clear contradiction to
137ignoring them.
139RFC 3028 does not specify how to process incorrect MIME words.
140This implementation treats them literally, as it does if the word is
141correct, but its character set can not be converted to UTF-8.
144Address Test For Multiple Addresses Per Header
146A header may contain multiple addresses. RFC 3028 does not explicitly
147specify how to deal with them, but since the "address" test checks if
148anything matches anything else, matching one address suffices to
149satify the condition. That makes it impossible to test if a header
150contains a certain set of addresses and no more, but it is more logical
151than letting the test fail if the header contains an additional address
152besides the one the test checks for.
155Semantics Of Keep
157The keep command is equivalent to fileinto "inbox": It saves the
158message and resets the implicit keep flag. It does not set the
159implicit keep flag; there is no command to set it once it has
160been reset.
163Semantics of Fileinto
165RFC 3028 does not specify if "fileinto" tries to create a mail folder,
166in case it does not exist. This implementation allows to configure
167that aspect using the appendfile transport options "create_directory",
168"create_file" and "file_must_exist". See the appendfile transport in
169the Exim specification for details.
172Semantics of Redirect
174Sieve scripts are supposed to be interoperable between servers, so this
175implementation does not allow redirecting mail to unqualified addresses,
176because the domain would depend on the used system and on systems with
177virtual mail domains it is probably not what the user expects it to be.
180String Arguments
182There has been confusion if the string arguments to "require" are to be
183matched case-sensitive or not. This implementation matches them with
184the match type ":is" (default, see section 2.7.1) and the comparator
185"i;ascii-casemap" (default, see section 2.7.3). The RFC defines the
186command defaults clearly, so any different implementations violate RFC
1873028. The same is valid for comparator names, also specified as strings.
190Number Units
192There is a mistake in RFC 3028: The suffix G denotes gibi-, not tebibyte.
193The mistake os obvious, because RFC 3028 specifies G to denote 2^30
194(which is gibi, not tebi), and that's what this implementation uses as
195scaling factor for the suffix G.
198Sieve Syntax and Semantics
200RFC 3028 confuses syntax and semantics sometimes. It uses a generic
201grammar as syntax for actions and tests and performs many checks during
202semantic analysis. Syntax is specified as grammar rule, semantics
203with natural language, despire the latter often talking about syntax.
204The intention was to provide a framework for the syntax that describes
205current commands as well as future extensions, and describing commands
206by semantics. Since the semantic analysis is not specified by formal
207rules, it is easy to get that phase wrong, as demonstrated by the mistake
208in RFC 3028 to forbid "elsif" being followed by "elsif" (which is allowed
209in Sieve, it's just not specified correctly).
211RFC 3028 does not define if semantic checks are strict (always treat
212unknown extensions as errors) or lazy (treat unknown extensions as error,
213if they are executed), and since it employs a very generic grammar,
214it is not unreasonable for an implementation using a parser for the
215generic grammar to indeed process scripts that contain unknown commands
216in dead code. It is just required to treat disabled but known extensions
217the same as unknown extensions.
219The following suggestion for section 8.2 gives two grammars, one for
220the framework, and one for specific commands, thus removing most of the
221semantic analysis. Since the parser can not parse unsupported extensions,
222the result is strict error checking. As required in section 2.10.5, known
223but not enabled extensions must behave the same as unknown extensions,
224so those also result strictly in errors (though at the thin semantic
225layer), even if they can be parsed fine.
2278.2. Grammar
229The atoms of the grammar are lexical tokens. White space or comments may
230appear anywhere between lexical tokens, they are not part of the grammar.
231The grammar is specified in ABNF with two extensions to describe tagged
232arguments that can be reordered and grammar extensions: { } denotes a
233sequence of symbols that may appear in any order. Example:
235 start = { a b c }
237is equivalent to:
239 start = ( a b c ) / ( a c b ) / ( b a c ) / ( b c a ) / ( c a b ) / ( c b a )
241The symbol =) is used to append to a rule:
243 start = a
244 start =) b
246is equivalent to
248 start = a b
250All Sieve commands, including extensions, MUST be words of the following
251generic grammar with the start symbol "start". They SHOULD be specified
252using a specific grammar, though.
254 argument = string-list / number / tag
255 arguments = *argument [test / test-list]
256 block = "{" commands "}"
257 commands = *command
258 string = quoted-string / multi-line
259 string-list = "[" string *("," string) "]" / string
260 test = identifier arguments
261 test-list = "(" test *("," test) ")"
262 command = identifier arguments ( ";" / block )
263 start = command
265The basic Sieve commands are specified using the following grammar, which
266language is a subset of the generic grammar above. The start symbol is
269 address-part = ":localpart" / ":domain" / ":all"
270 comparator = ":comparator" string
271 match-type = ":is" / ":contains" / ":matches"
272 string = quoted-string / multi-line
273 string-list = "[" string *("," string) "]" / string
274 address-test = "address" { [address-part] [comparator] [match-type] }
275 string-list string-list
276 test-list = "(" test *("," test) ")"
277 allof-test = "allof" test-list
278 anyof-test = "anyof" test-list
279 exists-test = "exists" string-list
280 false-test = "false"
281 true=test = "true"
282 header-test = "header" { [comparator] [match-type] }
283 string-list string-list
284 not-test = "not" test
285 relop = ":over" / ":under"
286 size-test = "size" relop number
287 block = "{" commands "}"
288 if-command = "if" test block *( "elsif" test block ) [ "else" block ]
289 stop-command = "stop" { stop-options } ";"
290 stop-options =
291 keep-command = "keep" { keep-options } ";"
292 keep-options =
293 discard-command = "discard" { discard-options } ";"
294 discard-options =
295 redirect-command = "redirect" { redirect-options } string ";"
296 redirect-options =
297 require-command = "require" { require-options } string-list ";"
298 require-options =
299 test = address-test / allof-test / anyof-test / exists-test
300 / false-test / true-test / header-test / not-test
301 / size-test
302 command = if-command / stop-command / keep-command
303 / discard-command / redirect-command
304 commands = *command
305 start = *require-command commands
307The extensions "envelope" and "fileinto" are specified using the following
308grammar extension.
310 envelope-test = "envelope" { [comparator] [address-part] [match-type] }
311 string-list string-list
312 test =/ envelope-test
314 fileinto-command = "fileinto" { fileinto-options } string ";"
315 fileinto-options =
316 command =/ fileinto-command
318The extension "copy" is specified as:
320 fileinto-options =) ":copy"
321 redirect-options =) ":copy"
324The i;ascii-numeric Comparator
326RFC 2244 describes this comparator and specifies that non-numeric strings
327are considered equal with an ordinal value higher than any numeric string.
328Although not stated explicitly, this includes the empty string. A range
329of at least 2^31 is required. This implementation does not limit the
330range, because it does not convert numbers to binary representation
331before comparing them.
334The vacation extension
336The extension "vacation" is specified using the following grammar
339 vacation-command = "vacation" { vacation-options } <reason: string>
340 vacation-options = [":days" number]
341 [":addresses" string-list]
342 [":subject" string]
343 [":mime"]
344 command =/ vacation-command
347Semantics Of ":mime"
349RFC 3028 does not specify how strings using MIME parts are used to compose
350messages. The vacation draft refers to RFC 3028 and does not specify it
351either. As a result, different implementations generate different mails.
352The Exim Sieve implementation splits the reason into header and body.
353It adds the header to the mail header and uses the body as mail body.
354Be aware, that other imlementations compose a multipart structure with
355the reason as only part. Both conform to the specification (or lack
359Semantics Of Not Using ":mime"
361Sieve scripts are written in UTF-8, so is the reason string in this
362case. This implementation adds MIME headers to indicate that. This
363is not required by the vacation draft, which does not specify how
364the UTF-8 reason is processed to compose the resulting message.
367Default Subject
369The draft specifies that the default message subject is "Re: "
370plus the old subject, stripped by any leading "Re: " strings.
371This string is to be taken literally, unlike some software which
372matches a regular expression like "[rR][eE]: *". Using this
373subject is dangerous, because many mailing lists verify addresses
374by sending a secret key in the subject of a message, asking to
375reply to the message for confirmation. Using the default vacation
376subject confirms any subscription request of this kind, allowing
377to subscribe a third party to any mailing list, either to annoy
378the user or to declare spam as legitimate mail by proving to
379use opt-in. The draft specifies to use "Re: " in front of the
380subject, but this implementation uses "Auto: ", as suggested in
381the current draft concerning automatic mail responses.
384Rate Limiting Responses
386This implementation hashes the reason, specified subject, ":mime"
387option and ":addresses" option and uses the hex string representation
388as filename within the "sieve_vacation_directory" to store the recipient
389addresses for this vacation parameter set.
391The draft specifies that sites may define a minimum ":days" value than 1.
392This implementation uses 1. The maximum value MUST greater than 7,
393and SHOULD be greater than 30. This implementation uses a maximum of 31.
395Vacation recipient address databases older than 31 days are automatically
396removed. Users do not have to remove them manually when modifying their
397scripts. Don't put anything but vacation databases in that directory
398or you risk that it will be removed, too!
401Global Reply Address Blacklist
403The draft requires that each implementation offers a global black list
404of addresses that will never be replied to. Exim offers this as option
405"never_mail" in the autoreply transport.
408Interaction With Other Sieve Elements
410The draft describes the interaction with vacation, discard, keep,
411fileinto and redirect. It MUST describe compatibility with other
412actions, but doesn't. In this implementation, vacation is compatible
413with any other action.