7Network Working Group N. Freed
8Request for Comments: 5463 Sun Microsystems
9Category: Standards Track March 2009
12 Sieve Email Filtering: Ihave Extension
16 This document specifies an Internet standards track protocol for the
17 Internet community, and requests discussion and suggestions for
18 improvements. Please refer to the current edition of the "Internet
19 Official Protocol Standards" (STD 1) for the standardization state
20 and status of this protocol. Distribution of this memo is unlimited.
24 Copyright (c) 2009 IETF Trust and the persons identified as the
25 document authors. All rights reserved.
27 This document is subject to BCP 78 and the IETF Trust's Legal
28 Provisions Relating to IETF Documents in effect on the date of
29 publication of this document (http://trustee.ietf.org/license-info).
30 Please review these documents carefully, as they describe your rights
31 and restrictions with respect to this document.
35 This document describes the "ihave" extension to the Sieve email
36 filtering language. The "ihave" extension provides a means to write
37 scripts that can take advantage of optional Sieve features but can
38 still run when those optional features are not available. The
39 extension also defines a new error control command intended to be
40 used to report situations where no combination of available
41 extensions satisfies the needs of the script.
45 Sieve [RFC5228] is a language for filtering email messages at or
46 around the time of final delivery. It is designed to be
47 implementable on either a mail client or mail server. It is suitable
48 for running on a mail server where users may not be allowed to
49 execute arbitrary programs, such as on black-box Internet Message
50 Access Protocol [RFC3501] servers, as it has no user-controlled loops
51 or the ability to run external programs.
58Freed Standards Track [Page 1]
60RFC 5463 Sieve Ihave Extension March 2009
63 Various sieve extensions have already been defined, e.g., [RFC5229],
64 [RFC5230], [RFC5231], [RFC5232], [RFC5233], [RFC5235], and many more
65 are sure to be created over time. Sieve's require clause is used to
66 specify the extensions a particular sieve needs; an error results if
67 the script's require clause calls for an extension that isn't
68 available. This mechanism is sufficient in most situations.
69 However, there can be cases where a script may be able to take
70 advantage of an extension if it is available but can still operate if
71 it is not, possibly with some degradation of functionality. Cases
72 can also arise where a script would prefer one extension but can
73 employ a different one if the first one is not available.
75 The "ihave" extension provides a means to write scripts that make use
76 of extensions only when they are actually available. It defines a
77 new "ihave" test that takes a list of capability names as an argument
78 and succeeds if and only if all of those capabilities are present.
79 Additionally, specification of the "ihave" extension in the require
80 clause disables parse-time checking of extension use in scripts; run-
81 time checking must be used instead. This makes it possible to write
82 portable scripts that can operate in multiple environments making
83 effective use of whatever extensions are available even though
84 differing sets of extensions are provided in different places.
86 The "ihave" extension also defines a new error control command. An
87 error causes script execution to terminate with the error message
88 given as the argument to the error control.
902. Conventions Used in This Document
92 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
93 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
94 document are to be interpreted as described in [RFC2119].
96 The terms used to describe the various components of the Sieve
97 language are taken from Section 1.1 of [RFC5228].
993. Capability Identifiers
101 The capability string associated with the extension defined in this
106 Usage: ihave <capabilities: string-list>
108 The "ihave" test provides a means for Sieve scripts to test for the
109 existence of a given extension prior to actually using it. The
110 capabilities argument to "ihave" is the same as the similarly-named
114Freed Standards Track [Page 2]
116RFC 5463 Sieve Ihave Extension March 2009
119 argument to the require control statement: It specifies the names of
120 one or more Sieve extensions or comparators. The "ihave" test
121 succeeds if all the extensions specified in the capabilities list are
122 available to the script.
124 Unlike most Sieve tests, "ihave" accepts no match or comparator
125 arguments. The type of match for "ihave" is always ":is" and the
126 comparator is always "i;octet".
128 The strings in the capabilities list are constant strings in the
129 context of Sieve variables [RFC5229]. It is an error to pass a non-
130 constant string as an argument to "ihave".
132 The Sieve base specification demands that all Sieve extensions used
133 in a given script be specified in the initial require control
134 statement. It is an error for a script to call for extensions the
135 interpreter doesn't support or to attempt to use extensions that have
136 not been listed in the script's require clause. Using "ihave"
137 changes Sieve interpreter behavior and the underlying requirements in
140 1. Use of a given extension is allowed subsequent to the successful
141 evaluation of an "ihave" test on that extension all the way to
142 the end of the script, even outside the block enclosed by the
143 "ihave" test. In other words, subsequent to a successful
144 "ihave", things operate just as if the extension had been
145 specified in the script's require clause. The extension cannot
146 be used prior to the evaluation of such a test and a run-time
147 error MUST be generated if such usage is attempted. However,
148 subsequent use of that extension may still need to be
149 conditionally handled via an "ihave" test to deal with the case
150 where it is not supported.
152 2. Sieve interpreters normally have the option of checking extension
153 use at either parse time or execution time. The specification of
154 "ihave" in a script's require clause changes this behavior:
155 Scripts MUST either defer extension checking to run time or else
156 take the presence of "ihave" tests into account at parse time.
157 Note that since "ihave" can be used inside of "anyof", "allof",
158 and "not" tests, full parse-time checking of "ihave" may be very
159 difficult to implement.
161 3. Although it makes little sense to do so, an extension can be
162 specified in both the require control statement and in an "ihave"
163 test. If this is done and the extension has been implemented,
164 the extension can be used anywhere in the script and an "ihave"
165 test of that extension will always return true.
170Freed Standards Track [Page 3]
172RFC 5463 Sieve Ihave Extension March 2009
175 4. The "ihave" test accepts a list of capabilities. If any of the
176 specified capabilities are unavailable, the test fails and none
177 of the capabilities are enabled.
179 5. The Sieve base specification does not require that interpreters
180 evaluate arguments in any particular order or that test
181 evaluation be short-circuited. If "ihave" is enabled, the
182 interpreter MUST short-circuit tests, i.e., not perform more
183 tests than necessary to find the result. Additionally,
184 evaluation order MUST be left to right if "ihave" is enabled.
186 The "ihave" extension is designed to be used with other extensions
187 that add tests, actions, comparators, or arguments. Implementations
188 MUST NOT allow it to be used with extensions that change the
189 underlying Sieve grammar, or extensions like encoded-character
190 [RFC5228], or variables [RFC5229] that change how the content of
191 Sieve scripts are interpreted. The test MUST fail and the extension
192 MUST NOT be enabled if such usage is attempted.
196 Usage: error <message: string>
198 The error control causes script execution to terminate with a run-
199 time error. The message argument provides a text description of the
200 error condition that SHOULD be included in any generated report
201 regarding the error. Section 2.10.6 of [RFC5228] describes how run-
202 time errors are handled in Sieve.
204 Note that the message argument, like all Sieve strings, employs the
205 UTF-8 charset and can contain non-US-ASCII characters. This must be
206 taken into consideration when reporting script errors.
208 The error control is included as part of the "ihave" extension so
209 that it is unconditionally available to scripts using ihave.
2116. Security Considerations
213 A potential security issue with Sieve scripts is that when a script
214 fails to run due to the lack of some extension, it may fail to block
215 dangerous email. The "ihave" extension makes it possible to improve
216 script portability and generality, which may improve the overall
217 security provided by Sieve.
219 Script robustness aside, ihave is essentially a more flexible variant
220 of Sieve's existing require mechanism. As such, it does not add any
221 additional capabilities to a Sieve implementation that could create
226Freed Standards Track [Page 4]
228RFC 5463 Sieve Ihave Extension March 2009
231 security issues. Of course, all of the security considerations given
232 in the base Sieve specification and in any extensions that are
233 employed are still relevant.
2357. IANA Considerations
237 The following template specifies the IANA registration of the Sieve
238 extension specified in this document:
241 Subject: Registration of new Sieve extension
243 Capability name: ihave
244 Description: The "ihave" extension provides a means to write
245 scripts that make use of other extensions only
246 when they are actually available.
248 Contact address: Sieve discussion list <ietf-mta-filters@imc.org>
2528.1. Normative References
254 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
255 Requirement Levels", BCP 14, RFC 2119, March 1997.
257 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering
258 Language", RFC 5228, January 2008.
2608.2. Informative References
262 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
263 4rev1", RFC 3501, March 2003.
265 [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension",
266 RFC 5229, January 2008.
268 [RFC5230] Showalter, T. and N. Freed, "Sieve Email Filtering:
269 Vacation Extension", RFC 5230, January 2008.
271 [RFC5231] Segmuller, W. and B. Leiba, "Sieve Email Filtering:
272 Relational Extension", RFC 5231, January 2008.
274 [RFC5232] Melnikov, A., "Sieve Email Filtering: Imap4flags
275 Extension", RFC 5232, January 2008.
277 [RFC5233] Murchison, K., "Sieve Email Filtering: Subaddress
278 Extension", RFC 5233, January 2008.
282Freed Standards Track [Page 5]
284RFC 5463 Sieve Ihave Extension March 2009
287 [RFC5235] Daboo, C., "Sieve Email Filtering: Spamtest and Virustest
288 Extensions", RFC 5235, January 2008.
292 Stephan Bosch, Cyrus Daboo, Arnt Gulbrandsen, Andrew McKeon, and
293 Alexey Melnikov provided helpful suggestions and corrections.
300 Monrovia, CA 91016-6347
303 Phone: +1 909 457 4293
304 EMail: ned.freed@mrochek.com
338Freed Standards Track [Page 6]