7Internet Engineering Task Force (IETF) A. Melnikov
8Request for Comments: 6558 Isode Limited
9Category: Standards Track B. Leiba
15 Sieve Extension for Converting Messages before Delivery
19 This document describes how the "CONVERT" IMAP extension can be used
20 within the Sieve mail filtering language to transform messages before
25 This is an Internet Standards Track document.
27 This document is a product of the Internet Engineering Task Force
28 (IETF). It represents the consensus of the IETF community. It has
29 received public review and has been approved for publication by the
30 Internet Engineering Steering Group (IESG). Further information on
31 Internet Standards is available in Section 2 of RFC 5741.
33 Information about the current status of this document, any errata,
34 and how to provide feedback on it may be obtained at
35 http://www.rfc-editor.org/info/rfc6558.
39 Copyright (c) 2012 IETF Trust and the persons identified as the
40 document authors. All rights reserved.
42 This document is subject to BCP 78 and the IETF Trust's Legal
43 Provisions Relating to IETF Documents
44 (http://trustee.ietf.org/license-info) in effect on the date of
45 publication of this document. Please review these documents
46 carefully, as they describe your rights and restrictions with respect
47 to this document. Code Components extracted from this document must
48 include Simplified BSD License text as described in Section 4.e of
49 the Trust Legal Provisions and are provided without warranty as
50 described in the Simplified BSD License.
58Melnikov, et al. Standards Track [Page 1]
60RFC 6558 Sieve CONVERT March 2012
65 1. Introduction ....................................................2
66 1.1. Conventions Used in This Document ..........................2
67 2. "convert" Action ................................................2
68 2.1. Interaction with Other Tests and Actions ...................3
69 2.2. "convert" as a Test ........................................4
70 3. Examples ........................................................5
71 3.1. Example 1 ..................................................5
72 3.2. Example 2 ..................................................5
73 3.3. Example 3 ..................................................5
74 3.4. Example 4 ..................................................6
75 4. Security Considerations .........................................7
76 5. IANA Considerations .............................................7
77 6. Acknowledgements ................................................7
78 7. Normative References ............................................7
82 The IMAP "CONVERT" extension [RFC5259] adds an IMAP command for
83 performing client-controlled conversions on whole messages or their
84 body parts. This document defines a similar extension to the Sieve
85 mail filtering language [RFC5228], which reuses the conversion
86 parameters and framework established by IMAP CONVERT.
881.1. Conventions Used in This Document
90 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
91 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
92 document are to be interpreted as described in RFC 2119 [RFC2119].
94 Conventions for notations are as in Sieve [RFC5228], Section 1.1.
98 Usage: convert <quoted-from-media-type: string>
99 <quoted-to-media-type: string>
100 <transcoding-params: string-list>
102 The "convert" action specifies that all body parts with a media type
103 [RFC2046] (sometimes called "MIME type") equal to <quoted-from-media-
104 type> be converted to the media type in <quoted-to-media-type> using
105 conversion parameters specified in <transcoding-params>. Each
106 conversion parameter value has the following syntax: "<transcoding-
107 param-name>=<transcoding-param-value>", where <transcoding-param-
108 name> and <transcoding-param-value> are defined in CONVERT [RFC5259].
109 Messages that don't have any body parts with the <quoted-from-media-
110 type> media type are not affected by the conversion.
114Melnikov, et al. Standards Track [Page 2]
116RFC 6558 Sieve CONVERT March 2012
119 The "convert" action can be used with Sieve MIME Part Tests
120 [RFC5703], in the case that some, but not all of the body parts need
121 to be converted, or where different body parts might require
122 different conversions. When the "convert" action appears in a
123 "foreverypart" loop, it applies only to the body part being
124 processed, and not to any other body parts (see Section 3.2 for an
127 When the "convert" action appears outside a "foreverypart" loop, the
128 conversion applies equally to all body parts -- that is, all body
129 parts that have the "quoted-from-media-type" are converted, using the
130 same transcoding parameters.
132 A single "convert" action will only apply once to any body part. If,
133 for example, << convert "image/jpeg" "image/jpeg" ["pix-x=100","pix-
134 y=120"] >> converts a larger JPEG image to the smaller 100 x 120
135 size, that will be the end of that "convert" action on that body
136 part. The action will not see a "new" JPEG body part to process,
137 resulting from the conversion.
139 If a "convert" action cannot be completed -- perhaps because the
140 conversion failed, or because the requested conversion is not
141 available -- that "convert" action MUST terminate and leave the
142 message unchanged, rolling back any other conversions done by that
143 action. The script processing continues, and prior or subsequent
144 "convert" actions are not affected. No error condition is raised,
145 and no partial conversions from a single "convert" action are
148 Implementations might defer any actual conversion until the results
149 of the conversion are needed for script processing, to avoid doing
150 conversions unnecessarily. Consider the case wherein a "convert"
151 action is processed but a "discard" action results without the need
152 to actually perform the conversion.
154 When conversions actually need to be done, they can put a significant
155 load on the server. Computationally expensive conversions of a lot
156 of body parts can constitute an attack vector; even if done
157 legitimately, they can create an unacceptable load. Servers MAY
158 refuse conversions, or do them at lower priority, effectively slowing
159 the requesting process in order to avoid negative effects on service
1622.1. Interaction with Other Tests and Actions
164 Whether or not the actual conversion has been done yet, a successful
165 "convert" action effectively changes the message, and all subsequent
166 actions, including any other "convert" actions, apply to the changed
170Melnikov, et al. Standards Track [Page 3]
172RFC 6558 Sieve CONVERT March 2012
175 message. The "convert" action does not affect the applicability of
176 other actions; any action that was applicable before the "convert" is
177 equally applicable to the changed message afterward.
179 When a disposition-type action, such as "fileinto" or "redirect", is
180 encountered, the state of the message with respect to conversions is
181 "locked in" for that disposition-type action. Whether the
182 implementation performs the action at that point or batches it for
183 later, it MUST perform the action on the message as it stood at the
184 time, and MUST NOT include subsequent conversions encountered later
185 in the script processing. Therefore, the sequence "convert,
186 fileinto, convert, fileinto" will store two different versions of the
187 message: the first "fileinto" uses only the first conversion, while
188 the second uses both. See Section 3.4 for an example of how this can
191 In addition, any tests done on the message and its parts will test
192 the message after prior conversions have been done. The fourth block
193 of Section 3.4 shows an example of this situation.
195 Convert actions are cumulative, and each conversion operates on the
196 message as it stands after all prior conversions. See the fourth
197 block of Section 3.4 for an example of how this might be tricky.
199 Because the implicit keep (see Section 2.10.2 of [RFC5228]), if it is
200 in effect, acts on the final state of the message, all conversions
201 are performed before any implicit keep.
2032.2. "convert" as a Test
205 To simplify testing for supported and successful conversions, the
206 "convert" action can also be used as a test. As such, it will
207 attempt to perform the requested conversion(s) and will evaluate to
208 "false" if and only if at least one conversion failed. The failure
209 can be because a conversion was unsupported or because the data could
210 not be converted (perhaps it had been corrupted in transit or
211 mislabeled at its origin).
213 This creates a new type of Sieve action, a "testable action". The
214 usage as a test is exactly the same as for an action, and it doubles
215 as an action and a test of the action's result at the same time. See
216 Section 3.2 for an example of how this test can be used.
218 Note that defining this new testable action does not change the
219 definitions of any other actions -- it does not imply that other
220 actions can be used as tests. Future extensions might define other
221 testable actions, but those specifications would be responsible for
222 clearly specifying that.
226Melnikov, et al. Standards Track [Page 4]
228RFC 6558 Sieve CONVERT March 2012
235 In the following example, all "image/tiff" body parts of the message
236 are converted to "image/jpeg" with image resolution of 320x240
237 pixels. The converted message is then subject to the implicit keep.
240 convert "image/tiff" "image/jpeg" ["pix-x=320","pix-y=240"];
244 In the following example, all "image/tiff" body parts of the message
245 are converted to "image/jpeg", as in Example 1. If the conversions
246 were successful, those messages are then filed into a mailbox called
247 "INBOX.pics". Other messages (those with no image/tiff body parts)
248 are subject to the implicit keep, and have not been converted.
250 require ["mime", "fileinto", "convert"];
251 if header :mime :anychild :contenttype
252 "Content-Type" "image/tiff"
254 if (convert "image/tiff" "image/jpeg" ["pix-x=320","pix-y=240"])
256 fileinto "INBOX.pics";
262 In the following example, only "image/tiff" body parts with a
263 Content-Disposition of "inline" are converted. Matching parts that
264 are larger than 500 kilobytes are converted using an image resolution
265 of 640x480 pixels, and those smaller are converted to 320x240 pixels.
266 The message disposition is not changed, so the implicit keep will be
267 in effect unless something else in the script changes that.
269 require ["mime", "foreverypart", "fileinto", "convert"];
272 if header :mime :param "filename" :contains
273 "Content-Disposition" "inline"
277 convert "image/tiff" "image/jpeg" ["pix-x=640","pix-y=480"];
282Melnikov, et al. Standards Track [Page 5]
284RFC 6558 Sieve CONVERT March 2012
287 convert "image/tiff" "image/jpeg" ["pix-x=320","pix-y=240"];
292 [... script continues ...]
296 The following example shows some tricky interactions between multiple
297 "convert" actions and other disposition-type actions.
299 require ["mime", "foreverypart",
300 "fileinto", "redirect", "convert"];
302 # The first "if" block will convert all image/tiff body parts
303 # to 640x480 jpegs and will file the message
304 # into the "INBOX.pics" mailbox as converted at this point.
305 if header :mime :anychild :contenttype
306 "Content-Type" "image/tiff"
308 convert "image/tiff" "image/jpeg" ["pix-x=640","pix-y=480"];
309 fileinto "INBOX.pics";
312 # The second block, the "foreverypart" loop, will convert all
313 # inline jpegs to 320x240 resolution... including any tiff body
314 # parts that had been converted in the first block, above.
315 # Therefore, any tiff that had been converted to a 640x480 jpeg
316 # will be re-converted to a 320x240 jpeg here if its
317 # Content-Disposition is specified as "inline".
320 if header :mime :param "filename" :contains
321 "Content-Disposition" "inline"
323 convert "image/jpeg" "image/jpeg" ["pix-x=320","pix-y=240"];
327 # The third block will take any message that contains a header
328 # field called "Mobile-Link" and redirect it to the user's
329 # mobile address. The redirected message will include both
330 # conversions above, from block one and block two.
331 if exists "Mobile-Link"
333 redirect "joe@mobile.example.com";
338Melnikov, et al. Standards Track [Page 6]
340RFC 6558 Sieve CONVERT March 2012
343 # The fourth block will file the message into "Tiff" if it
344 # contains any tiff body parts. But because of the earlier
345 # conversion (in the first block), there will never be any
346 # tiff body parts, so this "fileinto" will never happen.
347 if header :mime :anychild :contenttype
348 "Content-Type" "image/tiff"
353 # Now, at the end of the script processing, the Sieve
354 # processor will perform an implicit keep if none of
355 # the "fileinto" and "redirect" actions were taken.
356 # The kept message will include any conversions that
357 # were done (that is, any from the second block).
3594. Security Considerations
361 Security considerations given in IMAP CONVERT [RFC5259] and Sieve
362 [RFC5228] are relevant to this document. There are no additional
363 security considerations resulting from combining the two.
3655. IANA Considerations
367 IANA has added the following registration to the "Sieve Extensions"
368 registry, as defined in RFC 5228:
370 Capability name: convert
371 Description: adds a new Sieve test and action that enable Sieve
372 scripts to perform data conversions on the message being
375 Contact address: The Sieve discussion list <sieve@ietf.org>
379 The authors also want to thank all who have contributed key insight
380 and extensively reviewed and discussed the concepts of CONVERT.
382 Qian Sun contributed text to this document.
3847. Normative References
386 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
387 Extensions (MIME) Part Two: Media Types", RFC 2046,
394Melnikov, et al. Standards Track [Page 7]
396RFC 6558 Sieve CONVERT March 2012
399 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
400 Requirement Levels", BCP 14, RFC 2119, March 1997.
402 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering
403 Language", RFC 5228, January 2008.
405 [RFC5259] Melnikov, A. and P. Coates, "Internet Message Access
406 Protocol - CONVERT Extension", RFC 5259, July 2008.
408 [RFC5703] Hansen, T. and C. Daboo, "Sieve Email Filtering: MIME Part
409 Tests, Iteration, Extraction, Replacement, and Enclosure",
410 RFC 5703, October 2009.
416 5 Castle Business Village
418 Hampton, Middlesex TW12 2BX
421 EMail: Alexey.Melnikov@isode.com
422 URI: http://www.melnikov.ca/
428 Phone: +1 646 827 0648
429 EMail: barryleiba@computer.org
430 URI: http://internetmessagingtechnology.org/
435 Huawei Base, Bantian, Longgang District
436 Shenzhen, Guangdong 518129
439 Phone: +86-755-28974289
440 EMail: likepeng@huawei.com
450Melnikov, et al. Standards Track [Page 8]