1
2
3
4
5
6
7Network Working Group A. Melnikov, Ed.
8Request for Comments: 5259 Isode Ltd
9Category: Standards Track P. Coates, Ed.
10 Sun Microsystems
11 July 2008
12
13
14 Internet Message Access Protocol - CONVERT Extension
15
16Status of This Memo
17
18 This document specifies an Internet standards track protocol for the
19 Internet community, and requests discussion and suggestions for
20 improvements. Please refer to the current edition of the "Internet
21 Official Protocol Standards" (STD 1) for the standardization state
22 and status of this protocol. Distribution of this memo is unlimited.
23
24Abstract
25
26 CONVERT defines extensions to IMAP allowing clients to request
27 adaptation and/or transcoding of attachments. Clients can specify
28 the conversion details or allow servers to decide based on knowledge
29 of client capabilities, on user or administrator preferences, or on
30 server settings.
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58Melnikov & Coates Standards Track [Page 1]
59
60RFC 5259 IMAP CONVERT extension July 2008
61
62
63Table of Contents
64
65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
66 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
67 3. Relation with Other IMAP Specifications . . . . . . . . . . . 4
68 3.1. CAPABILITY Response . . . . . . . . . . . . . . . . . . . 4
69 4. Scope of Conversions . . . . . . . . . . . . . . . . . . . . . 4
70 5. Discovery of Available Conversions . . . . . . . . . . . . . . 4
71 5.1. CONVERSIONS Command . . . . . . . . . . . . . . . . . . . 4
72 5.2. CONVERSION Response . . . . . . . . . . . . . . . . . . . 6
73 6. CONVERT and UID CONVERT Commands . . . . . . . . . . . . . . . 6
74 7. CONVERT Conversion Parameters . . . . . . . . . . . . . . . . 12
75 7.1. Mandatory-to-Implement Conversions and Conversion
76 Parameters . . . . . . . . . . . . . . . . . . . . . . . . 12
77 7.2. Additional Features for Mobile Usage . . . . . . . . . . . 13
78 8. Request/Response Data Items to CONVERT/UID CONVERT Commands . 14
79 8.1. CONVERTED Untagged Response . . . . . . . . . . . . . . . 14
80 8.2. BODYPARTSTRUCTURE CONVERT Request and Response Item . . . 14
81 8.3. BINARY.SIZE CONVERT Request and Response Item . . . . . . 15
82 8.4. AVAILABLECONVERSIONS CONVERT Request and Response Item . . 16
83 8.5. Implementation Considerations . . . . . . . . . . . . . . 17
84 9. Status Responses and Response Code Extensions . . . . . . . . 17
85 10. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 20
86 11. Manageability Considerations . . . . . . . . . . . . . . . . . 24
87 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
88 12.1. Registration of unknown-character-replacement Media
89 Type Parameter . . . . . . . . . . . . . . . . . . . . . . 25
90 13. Security Considerations . . . . . . . . . . . . . . . . . . . 26
91 14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 27
92 15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28
93 15.1. Normative References . . . . . . . . . . . . . . . . . . . 28
94 15.2. Informative References . . . . . . . . . . . . . . . . . . 29
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114Melnikov & Coates Standards Track [Page 2]
115
116RFC 5259 IMAP CONVERT extension July 2008
117
118
1191. Introduction
120
121 This document defines the CONVERT extension to IMAP4 [RFC3501].
122 CONVERT provides adaptation and transcoding of body parts as needed
123 by the client. Conversion (adaptation, transcoding) may be requested
124 by the client and performed by the server on a best effort basis or,
125 when requested by the client, decided by the server based on the
126 server's knowledge of the client capabilities, user or administrator
127 preferences, or server settings.
128
129 This extension is primarily intended to be useful to mobile clients.
130 It satisfies requirements specified in [OMA-ME-RD].
131
132 A server that supports CONVERT can convert body parts to other
133 formats to be viewed (for example) on a mobile device. The client
134 can explicitly request a particular conversion or ask the server to
135 select the best available conversion. When allowed by the client,
136 the server determines how to convert based on its own strategy (e.g.,
137 based on knowledge of the client as discussed hereafter). If the
138 server knows the characteristics of the device (out of scope for
139 CONVERT) or can determine them (for example, using a conversion
140 parameter containing device type), converted body parts can also be
141 optimized for capabilities of the device (e.g., form factor of
142 pictures). The client is able to control conversions using optional
143 conversion (also referred to as "transcoding" in this document)
144 parameters.
145
146 This document relies on the registry of conversion parameters
147 established by [MEDIAFEAT-REG]. The registry can be used to discover
148 the underlying legal values that these parameters can take.
149 Additional conversion parameters, such as those defined by [OMA-STI],
150 are expected to be registered in the future.
151
1522. Conventions Used in This Document
153
154 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
155 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
156 document are to be interpreted as described in [RFC2119].
157
158 In examples, "C:" and "S:" indicate lines sent by the client and
159 server, respectively. If a single "C:" or "S:" label applies to
160 multiple lines, then the line breaks between those lines are for
161 editorial clarity only and are not part of the actual protocol
162 exchange. The five characters [...] mean that something has been
163 elided.
164
165
166
167
168
169
170Melnikov & Coates Standards Track [Page 3]
171
172RFC 5259 IMAP CONVERT extension July 2008
173
174
175 When describing the general syntax, some definitions are omitted as
176 they are defined in [RFC3501]. In particular, the term "session" is
177 used in this document as defined in Section 1.2 of [RFC3501].
178
1793. Relation with Other IMAP Specifications
180
181 Conversion of attachments during streaming is out of scope for the
182 CONVERT extension and is described in a separate Lemonade WG document
183 [LEM-STREAMING].
184
185 A server claiming compliance with this specification MUST support the
186 IMAP Binary specification [RFC3516].
187
1883.1. CAPABILITY Response
189
190 A server that supports the CONVERT extension MUST return "CONVERT"
191 and "BINARY" in the CAPABILITY response or response code. (Client
192 and server authors are reminded that the order of tokens returned in
193 the CAPABILITY response or response code is arbitrary.)
194
195 Example: A server that implements CONVERT.
196
197 C: a000 CAPABILITY
198 S: * CAPABILITY IMAP4rev1 CONVERT BINARY [...]
199 S: a000 OK CAPABILITY completed
200
2014. Scope of Conversions
202
203 Conversions only affect what is sent to the client; the original data
204 in the message store MUST NOT be altered. This document does not
205 specify how the server performs conversions.
206
207 Note: The requirement that original data be unaltered allows such
208 data to remain accessible by other clients, permits replies or
209 forwards of the original documents, permits signature verification
210 (the converted body parts are not likely to contain any signatures),
211 and preserves BODYSTRUCTURE and related information.
212
2135. Discovery of Available Conversions
214
2155.1. CONVERSIONS Command
216
217 Arguments: source MIME type
218 target MIME type
219
220 Responses: untagged responses: CONVERSION
221
222
223
224
225
226Melnikov & Coates Standards Track [Page 4]
227
228RFC 5259 IMAP CONVERT extension July 2008
229
230
231 Result: OK - CONVERSIONS command completed
232 BAD - unrecognized syntax of an argument, unexpected extra
233 argument, missing argument, etc.
234
235 The CONVERSIONS command is allowed in Authenticated and Selected IMAP
236 states.
237
238 The first parameter to the CONVERSIONS command is a source MIME type,
239 the second parameter is the target MIME type. Both parameters are
240 partially (e.g., "text/*") or completely ("*") wildcardable.
241
242 Conversions matching the source/target pair and their associated
243 conversion parameters are returned in untagged CONVERSION responses.
244 If source/target doesn't match any conversion supported by the
245 server, no CONVERSION response is returned.
246
247 Examples:
248
249 For conversion information from GIF to JPEG image format (no untagged
250 CONVERSION response would be returned if no conversion is possible):
251
252 C: a CONVERSIONS "image/gif" "image/jpeg"
253 S: * CONVERSION "image/gif" "image/jpeg" ("pix-y" "pix-x"
254 "image-interleave")
255 S: a OK CONVERSIONS completed
256
257 For conversion information from GIF image format to anything:
258
259 C: b CONVERSIONS "image/gif" "*"
260 S: * CONVERSION "image/gif" "image/jpeg" ("pix-y" "pix-x"
261 "image-interleave")
262 S: * CONVERSION "image/gif" "image/png" ([...])
263 [...]
264 S: b OK CONVERSIONS completed
265
266 For conversion of anything to JPEG:
267
268 C: c CONVERSIONS "*" "image/jpeg"
269 S: * CONVERSION "image/gif" "image/jpeg" ("pix-y" "pix-x"
270 "image-interleave")
271 S: * CONVERSION "image/png" "image/jpeg" (...)
272 [...]
273 S: c OK CONVERSIONS completed
274
275 For conversions from all image formats to all text formats, the
276 client can issue the following command:
277
278 C: d CONVERSIONS "image/*" "text/*"
279
280
281
282Melnikov & Coates Standards Track [Page 5]
283
284RFC 5259 IMAP CONVERT extension July 2008
285
286
2875.2. CONVERSION Response
288
289 Contents: source MIME type
290 target MIME type
291 optional list of supported conversion parameters
292
293 As a result of executing a CONVERSIONS command, the server can return
294 one or more CONVERSION responses. Each CONVERSION response specifies
295 which source MIME type can be converted to the target MIME type, and
296 also lists supported conversion parameters.
297
2986. CONVERT and UID CONVERT Commands
299
300 Arguments: sequence set
301 conversion parameters
302 CONVERT data item names
303
304 Responses: untagged responses: CONVERTED
305
306 Result: OK - convert completed
307 NO - convert error: can't fetch and/or convert that data
308 BAD - unrecognized syntax of an argument, unexpected extra
309 argument, missing argument, etc.
310
311 The CONVERT extension defines CONVERT and UID CONVERT commands that
312 are used to transcode the media type of a MIME part into another
313 media type, and/or the same media type with different encoding
314 parameters. These commands are structured and behave similarly to
315 FETCH/UID FETCH commands as extended by [RFC3516]:
316
317 o A successful CONVERT/UID CONVERT command results in one or more
318 untagged CONVERTED responses (one per message). They are similar
319 to the untagged FETCH responses. Note that a single CONVERT/ UID
320 CONVERT command can only perform a single type of conversion as
321 defined by the conversion parameters. A client that needs to
322 perform multiple different conversions needs to issue multiple
323 CONVERT/UID CONVERT commands. Such a client MAY pipeline them.
324
325 o BINARY[...] data item requests conversion of a body part or of the
326 whole message according to conversion parameters and requests that
327 the converted message/body part be returned as binary.
328
329 o BINARY.SIZE data item is similar to RFC822.SIZE, but it requests
330 size of a converted body part/message.
331
332 o BODYPARTSTRUCTURE data item is similar to BODYSTRUCTURE FETCH data
333 item, but it returns the MIME structure of the converted body
334 part.
335
336
337
338Melnikov & Coates Standards Track [Page 6]
339
340RFC 5259 IMAP CONVERT extension July 2008
341
342
343 o BODY[...HEADER] encoded words in the requested headers are
344 converted to the specified charset. The CHARSET parameter is
345 REQUIRED for this conversion.
346
347 o BODY[...MIME] encoded words in the requested headers are converted
348 to the specified charset. The CHARSET parameter is REQUIRED for
349 this conversion.
350
351 o AVAILABLECONVERSIONS data item requests the list of target MIME
352 types the specified body part (or the whole message) can be
353 converted to.
354
355 The CONVERT extension also adds one new response code. See Section 9
356 for more details.
357
358 Typically clients will request conversion of leaf body parts. In
359 addition to support of leaf body part conversion, servers MAY offer
360 conversion of non-leaf body parts (e.g., conversion from multipart/
361 related).
362
363 Instead of specifying the exact target MIME media type the client
364 wants to convert to, the client MAY use a special marker NIL (also
365 known as "default conversion") to request the server to pick a
366 suitable target media type. This document doesn't describe how
367 exactly the server makes such a choice; however, some basic
368 guidelines are described in this paragraph. If the server knows
369 characteristics of the device using an in-band (such as device type
370 specified in a conversion parameter) or an out-of-band mechanism,
371 then it should convert the request body part to a media type the
372 device is likely to support and display/play successfully. Unless
373 specifically overridden by a conversion parameter, the server MAY
374 also remove any unnecessary detail that exceeds the capabilities of
375 the device (e.g., scaling images to just fit on the device's screen).
376 In the absence of any in-band or out-of-band mechanism for
377 determining device characteristics, the server should convert the
378 request body part to the most standard or widely deployed media type
379 available in that media category, for example, to convert to text/
380 plain, image/jpeg. In such case, the server should minimize quality
381 loss. Servers are REQUIRED to support "default conversion" requests.
382 Server implementations that support conversions to multiple target
383 MIME types SHOULD make the default conversion configurable. Clients
384 SHOULD avoid using the default conversion unless they provided a way
385 (in-band or out-band) to signal their capabilities to the server, as
386 there is no guaranty that the server would guess their capability
387 correctly. Client implementors should consider using
388 AVAILABLECONVERSIONS CONVERT data item or CONVERSIONS command instead
389 of the default conversion.
390
391
392
393
394Melnikov & Coates Standards Track [Page 7]
395
396RFC 5259 IMAP CONVERT extension July 2008
397
398
399 CONVERT's command syntax is modeled after the FETCH command syntax in
400 [RFC3501], as extended by [RFC3516]. CONVERT data items are
401 generally structured as:
402
403 BINARY[section-part]<partial>
404
405 BINARY.SIZE[section-part]
406
407 BODYPARTSTRUCTURE[section-part]
408
409 BODY[HEADER]
410
411 BODY[section-part.HEADER]
412
413 BODY[section-part.MIME]
414
415 AVAILABLECONVERSIONS[section-part]
416
417 The semantics of a partial CONVERT BINARY[...] command is the same as
418 for a partial FETCH BODY[...] command, with the exception that the
419 <partial> arguments refer to the TRANSCODED and DECODED section data.
420
421 Note that unlike the FETCH command, the CONVERT command never sets
422 the \Seen flag on converted messages. A client wishing to mark a
423 message with the \Seen flag would need to issue a STORE command
424 (possibly pipelined with the CONVERT request) to do that.
425
426 The UID CONVERT command is different from the CONVERT command in the
427 same way as the UID FETCH command is different from the FETCH
428 command:
429
430 o UID CONVERT takes as a parameter a sequence of UIDs instead of a
431 sequence of message numbers.
432
433 o UID CONVERT command MUST result in the UID data item in a
434 corresponding CONVERTED response.
435
436 o An EXPUNGE response MUST NOT be sent while responding to a CONVERT
437 command. This rule is necessary to prevent a loss of
438 synchronization of message sequence numbers between client and
439 server. Note that an EXPUNGE response MAY be sent during a UID
440 CONVERT command.
441
442
443
444
445
446
447
448
449
450Melnikov & Coates Standards Track [Page 8]
451
452RFC 5259 IMAP CONVERT extension July 2008
453
454
455 Example: The client fetches body part section 3 in the message with
456 the message sequence number of 2 and asks to have that attachment
457 converted to pdf format.
458
459 C: a001 CONVERT 2 ("APPLICATION/PDF") BINARY[3]
460 S: * 2 CONVERTED (TAG "a001") (BINARY[3] {2135}
461 <the document in .pdf format>
462 )
463 S: a001 OK CONVERT COMPLETED
464
465 Example: The client requests for conversion of a text/html body part
466 to text/plain and asks for a charset of us-ascii. The server cannot
467 respect the charset conversion request because there are non-us-ascii
468 characters in the text/html body part, so it fails the request by
469 returning an ERROR phrase in place of the converted data (see
470 Section 9).
471
472 C: b001 CONVERT 2 ("text/plain" ("charset" "us-ascii")) BINARY[3]
473 S: * 2 CONVERTED (tag "b001") (BINARY[3]
474 (ERROR "Source text has non us-ascii" BADPARAMETERS
475 "text/html" "text/plain" ("charset" "us-ascii")))
476 S: b001 NO All conversions failed
477
478 If the client also specified the "unknown-character-replacement"
479 conversion parameter (see Section 12.1), the same example can look
480 like this:
481
482 C: b001 CONVERT 2 ("text/plain" ("charset" "us-ascii"
483 "unknown-character-replacement" "?")) BINARY[3]
484 S: * 2 CONVERTED (TAG "b001") (BINARY[3] {2135}
485 <the document in text/plain format with us-ascii
486 charset>
487 )
488 S: b001 OK CONVERT COMPLETED
489
490 The server replaced non-us-ascii characters with a us-ascii character
491 such as "?".
492
493 Example: The client first requests the converted size of a text/html
494 body part converted to text/plain:
495
496 C: c000 CONVERT 2 ("TEXT/PLAIN" ("CHARSET" "us-ascii"))
497 BINARY.SIZE[4]
498 S: * 2 CONVERTED (TAG "c000") (BINARY.SIZE[4] 3135)
499 S: c000 OK CONVERT COMPLETED
500
501
502
503
504
505
506Melnikov & Coates Standards Track [Page 9]
507
508RFC 5259 IMAP CONVERT extension July 2008
509
510
511 Later on, the client requests 1000 bytes from the converted body
512 part, starting from byte 2001:
513
514 C: c001 CONVERT 2 ("TEXT/PLAIN" ("CHARSET" "us-ascii"))
515 BINARY[4]<2001.1000>
516 S: * 2 CONVERTED (TAG "c001") (BINARY[4]<2001> {135}
517 <bytes 2001 - 2135 of the document in text/plain format>
518 )
519 S: c001 OK CONVERT COMPLETED
520
521 The server MUST respect the target MIME type and conversion
522 parameters specified by the client in the transcoding request. Note
523 that some conversion parameters can restrict what kind of conversion
524 is possible, while others can remove some restrictions.
525
526 It is legal for a client to request conversion of a non-leaf body
527 part, for example, to request conversion of a multipart/* into a PDF
528 document. However, servers implementing this extension are not
529 required to support such conversions. Servers that support such
530 conversions MUST return one or more CONVERSION responses in response
531 to a 'CONVERSIONS "multipart/*" "*"' command. See Section 5.1 for
532 more details.
533
534 The client can request header conversions using the BODY[...HEADER]
535 CONVERT request, for example
536
537 C: D001 FETCH 2 BODY[HEADER]
538 S: * 2 FETCH (BODY[HEADER] {158}
539 S: Date: Mon, 20 Apr 2007 20:05:43 +0200
540 S: From: Peter <peter@siroe.example.com>
541 S: To: Alexey <alexey@siroe.example.com>
542 S: Subject: =?KOI8-R?Q?why encode this?=
543 S:
544 S: )
545 S: D001 OK
546 C: D002 CONVERT 2 (NIL ("CHARSET" "utf-8")) BODY[HEADER]
547 S: * 2 CONVERTED (TAG "d002") (BODY[HEADER] {157}
548 S: Date: Mon, 20 Apr 2007 20:05:43 +0200
549 S: From: Peter <peter@siroe.example.com>
550 S: To: Alexey <alexey@siroe.example.com>
551 S: Subject: =?UTF-8?Q?why encode this?=
552 S:
553 S: )
554 S: D002 OK
555
556 Any such request MUST include the CHARSET parameter. Upon receipt of
557 the request, the server MUST decode any encoded words (as described
558 in [RFC2047]) in headers and return them re-encoded in the specified
559
560
561
562Melnikov & Coates Standards Track [Page 10]
563
564RFC 5259 IMAP CONVERT extension July 2008
565
566
567 charset. (Note that encoded-words might not be needed if the result
568 can be represented entirely in US-ASCII, so the server MAY replace
569 the resulting encoded-words with their pure US-ASCII representation.)
570 If the server can't decode any particular encoded word, for example,
571 if the charset or encoding is not recognized, it MUST leave them as
572 is. Servers SHOULD also support decoding of any parameters as
573 described in [RFC2231]. Support for RFC 2231 parameters might
574 require reformatting of header fields during conversion. Consider
575 the following
576
577 C: D011 FETCH 3 BODY[1.MIME]
578 S: * 3 FETCH (BODY[1.MIME] {118}
579 S: Content-Type: text/plain; charset=utf-8;
580 S: foo*0*=utf-8'fr'tr%c0;
581 S: foo*1*(very)=%03s_m%c0;
582 S: foo*2*=(nasty)%09chant
583 S:
584 S: D011 OK
585
586 The server should preserve the headers during the conversion as much
587 as possible. In case the characters are split (legally!) between
588 fragments of an encoded parameter, the server MUST consolidate the
589 parameter fragments, and convert, emit, and re-fragment them as
590 necessary in order to keep the line length less than 78. Comments
591 embedded like this SHOULD be preserved during conversion, but clients
592 MUST gracefully handle the situation where comments are removed
593 entirely. If the comments are preserved, they MAY be moved after the
594 parameter. For example (continuing the previous example):
595
596 C: D012 CONVERT 3 (NIL) BODY[1.MIME]
597 S: * 3 CONVERTED (TAG "D012") (BODY[1.MIME] {109}
598 S: Content-Type: text/plain; charset=utf-8;
599 S: foo*0*=utf-8'fr'tr%c0%03s_;
600 S: foo*1*=%m%c0%09chant (very)(nasty)
601 S:
602 S: D012 OK
603
604 No destination MIME type MUST be specified with BODY[HEADER],
605 BODY[section.HEADER], or BODY[section.MIME]. That is, BODY[HEADER],
606 BODY[section.HEADER], or BODY[section.MIME] can only be used with the
607 "default conversion". When performing these conversions, the server
608 SHOULD leave encoded words as encoded words. A failure to do so may
609 alter the semantics of structured headers.
610
611
612
613
614
615
616
617
618Melnikov & Coates Standards Track [Page 11]
619
620RFC 5259 IMAP CONVERT extension July 2008
621
622
6237. CONVERT Conversion Parameters
624
625 The registry established by [MEDIAFEAT-REG] defines names of
626 conversion parameters that can be used in the CONVERT command.
627 Support for some conversion parameters is mandatory, as described in
628 Section 7.1.
629
630 According to [MEDIAFEAT-REG], conversion parameter names are case-
631 insensitive.
632
633 The following example illustrates how target picture dimensions can
634 be specified in a CONVERT request using the PIX-X and PIX-Y
635 parameters defined in [DISP-FEATURES].
636
637 C: e001 UID CONVERT 100 ("IMAGE/JPEG" ("PIX-X" "128"
638 "PIX-Y" "96")) BINARY[2]
639 S: * 2 CONVERTED (TAG "e001") (UID 100 BINARY[2] ~{4182}
640 <this part of a document is a rescaled image in
641 JPEG format with width=128, height=96.>
642 )
643 S: e001 OK UID CONVERT COMPLETED
644
6457.1. Mandatory-to-Implement Conversions and Conversion Parameters
646
647 A server implementing CONVERT MUST support charset conversions for
648 the text/plain MIME type, and MUST support charset conversions from
649 iso-8859-1, iso-8859-2, iso-8859-3, iso-8859-4, iso-8859-5,
650 iso-8859-6, iso-8859-7, iso-8859-8, and iso-8859-15 to utf-8.
651
652 The server MUST list "text/plain" as an allowed destination
653 conversion from "text/plain" MIME type (see Section 5.1). A command
654 'CONVERSIONS "text/plain" "text/plain"' MUST also return "charset"
655 and "unknown-character-replacement" (see Section 12.1) as supported
656 conversion parameters in the corresponding CONVERSION response.
657
658 IMAP servers implementing the CONVERT extension MUST support
659 recognition of the "charset" [CHARSET-REG] parameter for text/plain,
660 text/html, text/css, text/csv, text/enriched, and text/xml MIME
661 types. Note, a server implementation is not required to support any
662 conversion from the text MIME subtypes specified above, except for
663 the mandatory-to-implement conversion described above. That is, a
664 server implementation MUST support the "charset" parameter for text/
665 csv, only if it supports any conversion from text/csv.
666
667 The server MUST support decoding of [RFC2047] headers and their
668 conversion to UTF-8 as long as the encoded words are in one of the
669 supported charsets.
670
671
672
673
674Melnikov & Coates Standards Track [Page 12]
675
676RFC 5259 IMAP CONVERT extension July 2008
677
678
679 Servers SHOULD offer additional character encoding conversions where
680 they make sense, as character conversion libraries are generally
681 available on many platforms.
682
683 If the server cannot carry out the charset conversion while
684 preserving all the characters (i.e., a source character can't be
685 represented in the target charset), and the "unknown-character-
686 replacement" conversion parameter is not specified, then the server
687 MUST fail the conversion and MUST return the untagged ERROR
688 BADPARAMETERS response (see Section 9). If the value specified in
689 the "unknown-character-replacement" conversion itself can't be
690 represented in the target charset, then the server MUST also fail the
691 conversion and MUST return the untagged ERROR BADPARAMETERS response
692 (see Section 9).
693
6947.2. Additional Features for Mobile Usage
695
696 This section is informative.
697
698 Based on the expected usage of CONVERT in mobile environments, server
699 implementors should consider support for the following conversions:
700
701 o Conversion of HTML and XHTML documents to text/plain in ways that
702 preserve at the minimum the document structure and tables.
703
704 o Image conversions among the types image/gif, image/jpeg, and
705 image/png for at least the following parameters:
706
707 * size limit (i.e., reduce quality)
708
709 * width ("pix-x" parameter)
710
711 * height ("pix-y" parameter)
712
713 * resize directive (crop, stretch, aspect ratio)
714
715 The support for "depth" may also be of interest.
716
717 Audio conversion is also of interest but the relevant formats depend
718 significantly on the usage context.
719
720
721
722
723
724
725
726
727
728
729
730Melnikov & Coates Standards Track [Page 13]
731
732RFC 5259 IMAP CONVERT extension July 2008
733
734
7358. Request/Response Data Items to CONVERT/UID CONVERT Commands
736
7378.1. CONVERTED Untagged Response
738
739 Contents: convert correlator
740 CONVERTED return data items
741
742 The CONVERTED response may be sent as a result of a successful,
743 partially successful, or unsuccessful CONVERT or UID CONVERT command
744 specified in Section 6.
745
746 The CONVERTED response starts with a message number, followed by the
747 "CONVERTED" label. The label is followed by a convert correlator,
748 which contains the tag of the command that caused the response to be
749 returned. This can be used by a client to match a CONVERTED response
750 against a corresponding CONVERT/UID CONVERT command.
751
752 The convert correlator is followed by a list of one or more CONVERT
753 return data items. If the UID data item is returned, it MUST be
754 returned as the first data item in the CONVERTED response. This
755 requirement is to simplify client implementations. See Section 10
756 and the remainder of Section 8 for more details.
757
7588.2. BODYPARTSTRUCTURE CONVERT Request and Response Item
759
760 BODYPARTSTRUCTURE[section-part]
761
762 The CONVERT extension defines the BODYPARTSTRUCTURE CONVERT data
763 item. Data contained in the BODYPARTSTRUCTURE return data item
764 follows the exact syntax specified in the [RFC3501] BODYSTRUCTURE
765 data item, but only contains information for the converted part. All
766 information contained in BODYPARTSTRUCTURE pertains to the state of
767 the part after it is converted, such as the converted MIME type, sub-
768 type, size, or charset. Note that the client can expect the returned
769 MIME type to match the one it requested (as the server is required to
770 obey the requested MIME type) and can treat mismatch as an error.
771
772 The returned BODYPARTSTRUCTURE data MUST match the BINARY data
773 returned for exactly the same conversion in the same IMAP "session".
774 This requirement allows a client to request BODYPARTSTRUCTURE and
775 BINARY data in separate commands in the same IMAP session.
776
777 If the client lists a BODYPARTSTRUCTURE data item for a section-part
778 before a BINARY data item for the same section-part, then, in the
779 CONVERTED response, the server MUST return the BODYPARTSTRUCTURE data
780 prior to the corresponding BINARY data. Also, any BODYSTRUCTURE data
781
782
783
784
785
786Melnikov & Coates Standards Track [Page 14]
787
788RFC 5259 IMAP CONVERT extension July 2008
789
790
791 items MUST be after the UID data item if the UID data item is
792 present. Both requirements are to simplify handling of converted
793 data in clients.
794
795 Example:
796 C: e002 CONVERT 2 (NIL ("PIX-X" "128" "PIX-Y" "96")) (BINARY[2]
797 BODYPARTSTRUCTURE[2])
798 S: * 2 CONVERTED (TAG "e002") (BODYPARTSTRUCTURE[2] ("IMAGE"
799 "JPEG" () NIL NIL "8bit" 4182 NIL NIL NIL) BINARY[2]
800 ~{4182}
801 <this part of a document is a rescaled image in
802 JPEG format with width=128, height=96.>
803 )
804 S: e002 OK CONVERT COMPLETED
805
8068.3. BINARY.SIZE CONVERT Request and Response Item
807
808 BINARY.SIZE[section-part]
809
810 This item requests the converted size of the section (i.e., the size
811 to expect in a response to the corresponding CONVERT BINARY request).
812 The returned value MUST be exact and MUST NOT change during a
813 duration of an IMAP "session", unless the message is expunged in
814 another session (see below). This allows a client to download a
815 converted part in chunks (using "<partial>"). This requirement means
816 that in most cases the server needs to perform conversion of the
817 requested body part before returning its size.
818
819 If the message is expunged in another session, then the server MAY
820 return the value 0 in response to the BINARY.SIZE request item later
821 in the same session.
822
823 In order to allow for upgrade of server transcoding components,
824 clients MUST NOT assume that repeating a particular body part
825 conversion in another IMAP "session" would yield the same result as a
826 previous conversion of the very same body part -- any characteristics
827 of the converted body part might be different (format, size, etc.).
828 In particular, clients MUST NOT cache sizes of converted messages/
829 body parts beyond duration of any IMAP "session", or use sizes
830 obtained in one connection in another IMAP connection to the same
831 server.
832
833 Historical note: Previous experience with IMAP servers that returned
834 estimated RFC822.SIZE value shows that this caused interoperability
835 problems. If the server returns a value that is smaller than the
836 actual size, this will result in data truncation if <partial>
837
838
839
840
841
842Melnikov & Coates Standards Track [Page 15]
843
844RFC 5259 IMAP CONVERT extension July 2008
845
846
847 download is used. If the server returns a value that is bigger than
848 the actual size, this might mislead a client to believe that it
849 doesn't have enough storage to download a body part.
850
851 Note for client implementors: client authors are cautioned that this
852 might be an expensive operation for some server implementations.
853 Requesting BINARY.SIZE for a large number of converted body parts or
854 for multiple conversions of the same body part can result in slow
855 performance and/or excessive server load and is discouraged. Client
856 implementors should consider implementation approaches that limit
857 this request to only the most necessary cases and are encouraged to
858 test the performance impact of BINARY.SIZE with multiple server
859 implementations.
860
8618.4. AVAILABLECONVERSIONS CONVERT Request and Response Item
862
863 AVAILABLECONVERSIONS[section-part] allows the client to request the
864 list of target MIME types the specified body part of a message or the
865 whole message can be converted to. This data item is only useful
866 when the default conversion (see Section 6) is requested.
867
868 This data item MUST return a list of target MIME types that is a
869 subset of the list returned by the CONVERSIONS command for the same
870 source and target MIME type pairs. If specific conversion is
871 requested, it MUST return the target MIME type as requested in the
872 CONVERT command, or the ERROR phrase.
873
874 For both specific or default conversion requests, if conversion
875 parameters are specified, then the server must take them into
876 consideration when generating the list of target MIME types. For
877 example, if one or more of the conversion parameters doesn't apply to
878 a potential target MIME type, then such MIME type MUST be omitted
879 from the resulting list. If the server only had a single target MIME
880 type candidate and it was discarded due to the list of conversion
881 parameters, then the server SHOULD return the ERROR phrase instead of
882 the empty list of the target MIME types.
883
884 The AVAILABLECONVERSIONS request SHOULD be processed quickly if
885 specified by itself. Note that if a MIME type is returned in
886 response to the AVAILABLECONVERSIONS, there is no guaranty that the
887 corresponding BINARY/BINARY.SIZE/BODYPARTSTRUCTURE CONVERT request
888 will not fail.
889
890 Example:
891 C: f001 CONVERT 2 (NIL) (AVAILABLECONVERSIONS[2])
892 S: * 2 CONVERTED (TAG "f001") (AVAILABLECONVERSIONS[2]
893 (("IMAGE/JPEG" "application/PostScript"))
894 S: f001 OK CONVERT COMPLETED
895
896
897
898Melnikov & Coates Standards Track [Page 16]
899
900RFC 5259 IMAP CONVERT extension July 2008
901
902
9038.5. Implementation Considerations
904
905 Note that this section is normative.
906
907 Servers MAY refuse to execute conversion requests that convert
908 multiple messages and/or body parts at once, e.g., a conversion
909 request that specifies multiple message numbers/UIDs. If the server
910 refuses a conversion because the request lists too many messages, the
911 server MUST return the MAXCONVERTMESSAGES response code (see
912 Section 9). For example:
913
914 C: g001 CONVERT 1:* ("text/plain" ("charset" "us-ascii"))
915 BINARY[3]
916 S: g001 NO [MAXCONVERTMESSAGES 1]
917
918 If the server refuses a conversion because the request lists too many
919 body parts, the server MUST return the MAXCONVERTPARTS response code
920 (see Section 9). For example:
921
922 C: h001 CONVERT 1 ("text/plain" ("charset" "us-ascii"))
923 (BINARY[1] BINARY[2])
924
925 S: g001 NO [MAXCONVERTPARTS 1] You can only request 1 body part at
926 any given time
927
928 Note for server implementors: In order to improve performance,
929 implementations SHOULD cache converted body parts. For example, the
930 server may perform a body part conversion when it receives the first
931 BINARY.SIZE[...], BODYPARTSTRUCTURE[...], or BINARY[...] request and
932 cache it until the client requests conversion/download of another
933 body part, a different conversion of the same body part, or until the
934 mailbox is closed. In order to mitigate denial-of-service attacks
935 from misbehaving or badly-written clients, a server SHOULD limit the
936 number of converted body parts it can cache. Servers SHOULD be able
937 to cache at least 2 conversions at any given time.
938
9399. Status Responses and Response Code Extensions
940
941 A syntactically invalid MIME media type SHOULD generate a BAD tagged
942 response from the server. An unrecognized MIME media type generates
943 a NO tagged response.
944
945 Some transcodings may require parameters. If a transcoding request
946 with no parameters is sent for a format which requires parameters,
947 the server will return an ERROR MISSINGPARAMETERS phrase in place of
948 the data associated with the data items requested. This is analogous
949 to the NIL response in FETCH, but with structured data associated
950 with the failure.
951
952
953
954Melnikov & Coates Standards Track [Page 17]
955
956RFC 5259 IMAP CONVERT extension July 2008
957
958
959 If the server is unable to perform the requested conversion because a
960 resource is temporary unavailable (e.g., lack of disk space,
961 temporary internal error, transcoding service down), then the server
962 MUST return a tagged NO response that SHOULD contain the TEMPFAIL
963 response code (see below), or an ERROR TEMPFAIL phrase.
964
965 If the requested conversion cannot be performed because of a
966 permanent error, for example, if a proprietary document format has no
967 existing transcoding implementation, the server MUST return a
968 CONVERTED response containing a ERROR BADPARAMETERS or ERROR
969 MISSINGPARAMETERS phrase.
970
971 The server MAY choose to return one ERROR phrase for a single
972 conversion if several related data items are requested. For
973 instance:
974
975 C: b002 CONVERT 2 ("text/plain" ("charset" "us-ascii"))
976 (BINARY[3] BODYPARTSTRUCTURE[3])
977 S: * 2 CONVERTED (tag "b002") (BODYPARTSTRUCTURE[3]
978 (ERROR "Source text has non us-ascii" BADPARAMETERS
979 "text/html" "text/plain" ("charset" "us-ascii")))
980 S: b002 NO All conversions failed
981
982 If at least one conversion succeeds, the server MUST return an OK
983 response. If all conversions fail, the server MAY return OK or NO.
984 For instance:
985
986 C: b002 CONVERT 2 ("text/plain" ("charset" "us-ascii"))
987 (BINARY[3] BODYPARTSTRUCTURE[3] BINARY[4]
988 BODYPARTSTRUCTURE[4])
989 S: * 2 CONVERTED (tag "b002") (BODYPARTSTRUCTURE[3]
990 (ERROR "Source text has non us-ascii" BADPARAMETERS
991 "text/html" "text/plain" ("charset" "us-ascii"))
992 BODYSTRUCTURE[4] ("TEXT" "PLAIN" (CHARSET US-ASCII)
993 NIL NIL "8bit" 4182 NIL NIL NIL) BINARY[4] {4182}
994 <body in text plain>
995 )
996 S: b002 OK Some conversions failed
997
998 In general, the client can tell from the BODYPARTSTRUCTURE response
999 whether or not its request was honored exactly, but may not know the
1000 reasons why.
1001
1002 This document defines the following response codes that can be
1003 returned in the tagged NO response code.
1004
1005 TEMPFAIL - The transcoding request failed temporarily. It might
1006 succeed later, so the client MAY retry.
1007
1008
1009
1010Melnikov & Coates Standards Track [Page 18]
1011
1012RFC 5259 IMAP CONVERT extension July 2008
1013
1014
1015 MAXCONVERTMESSAGES <number> - The server is unable or unwilling to
1016 convert more than <number> messages in any given CONVERT/UID
1017 CONVERT request.
1018
1019 MAXCONVERTPARTS <number> - The server is unable or unwilling to
1020 convert more than <number> body parts of a message at once in
1021 any given CONVERT/UID CONVERT request.
1022
1023 The word ERROR is always followed by an informal human-readable
1024 descriptive text, which is followed by the convert-error-code. The
1025 convert-error-code MUST be one of the following:
1026
1027 TEMPFAIL mm - The transcoding request failed temporarily. It might
1028 succeed later, so the client MAY retry. The client SHOULD wait
1029 for at least mm minutes before retrying.
1030
1031 BADPARAMETERS from-concrete-mime-type to-mime-type
1032 "(" transcoding-params ")" -
1033 The listed parameters were not understood, not valid for the
1034 source/destination MIME type pair, had invalid values or could
1035 not be honored for another reason noted in the human-readable
1036 text that was specified after the ERROR label. The
1037 transcoding-params can be omitted, in which case, it means that
1038 the conversion from the from-concrete-mime-type to the to-mime-
1039 type is not possible. If the from-concrete-mime-type is NIL,
1040 this means that the specified body part doesn't exist. All
1041 unrecognized or irrelevant parameters MUST be listed in the
1042 transcoding-params. It is not legal behavior to ignore
1043 irrelevant parameters.
1044
1045 Note that if the client requested the "default conversion" (see
1046 Section 6), the to-mime-type contains the destination MIME type
1047 chosen by the server.
1048
1049 MISSINGPARAMETERS from-concrete-mime-type to-mime-type
1050 "(" transcoding-params ")" -
1051 The listed parameters are required for conversion of the
1052 specified source MIME type to the destination MIME type, but
1053 were not seen in the request. Note that if the client
1054 requested the "default conversion" (see Section 6), the to-
1055 mime-type contains the destination MIME type chosen by the
1056 server.
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066Melnikov & Coates Standards Track [Page 19]
1067
1068RFC 5259 IMAP CONVERT extension July 2008
1069
1070
1071 Examples:
1072
1073 C: b002 CONVERT 2 ("APPLICATION/PDF") BINARY[3]
1074 S: b002 NO [TEMPFAIL] All conversions failed
1075
1076 C: b003 CONVERT 2 ("TEXT/PLAIN") BINARY[3]
1077 S: * 2 CONVERTED (tag "b003") (BINARY[3]
1078 (ERROR "CHARSET must be specified for text conversions"
1079 MISSINGPARAMETERS (CHARSET)))
1080 S: b003 NO All conversions failed
1081
1082 C: b005 CONVERT 2 ("TEXT/PLAIN" (CHARSET "US-ASCII"
1083 UNKNOWN-CHARACTER-REPLACEMENT "<badchar>")) BINARY[3]
1084 S: * 2 CONVERTED (tag "b005") (BINARY[3]
1085 (ERROR "UNKNOWN-CHARACTER-REPLACEMENT limited to 4
1086 bytes" BADPARAMETERS (UNKNOWN-CHARACTER-REPLACEMENT
1087 "<badchar>")))
1088 S: b005 NO All conversions failed
1089
109010. Formal Syntax
1091
1092 The following syntax specification uses the augmented Backus-Naur
1093 Form (ABNF) notation as used in [ABNF], and incorporates by reference
1094 the core rules defined in that document.
1095
1096 This syntax augments the grammar specified in [RFC3501] and
1097 [RFC3516]. Non-terminals not defined in this document can be found
1098 in [RFC3501], [RFC3516], [IMAPABNF], [MIME-MTSRP], and
1099 [MEDIAFEAT-REG].
1100
1101 command-select =/ convert
1102
1103 uid =/ "UID" SP convert
1104 ; Unique identifiers used instead of message
1105 ; sequence numbers
1106
1107 convert = "CONVERT" SP sequence-set SP convert-params SP
1108 ( convert-att /
1109 "(" convert-att *(SP convert-att) ")" )
1110
1111 convert-att = "UID" /
1112 "BODYPARTSTRUCTURE" section-convert /
1113 "BINARY" section-convert [partial] /
1114 "BINARY.SIZE" section-convert /
1115 "BODY[HEADER]" /
1116 "BODY[" section-part ".HEADER]" /
1117 "BODY[" section-part ".MIME]" /
1118 "AVAILABLECONVERSIONS" section-convert
1119
1120
1121
1122Melnikov & Coates Standards Track [Page 20]
1123
1124RFC 5259 IMAP CONVERT extension July 2008
1125
1126
1127 ; <partial> is defined in [RFC3516].
1128 ; <section-part> is defined in [RFC3501].
1129
1130 convert-params = "(" (quoted-to-mime-type / default-conversion)
1131 [SP "(" transcoding-params ")"] ")"
1132
1133 quoted-to-mime-type = DQUOTE to-mime-type DQUOTE
1134
1135 transcoding-params = transcoding-param
1136 *(SP transcoding-param)
1137
1138 transcoding-param-names = transcoding-param-name
1139 *(SP transcoding-param-name)
1140
1141 transcoding-param = transcoding-param-name SP
1142 transcoding-param-value
1143
1144 transcoding-param-name = astring
1145 ; <transcod-param-name-nq> represented as a quoted,
1146 ; literal or atom. Note that
1147 ; <transcod-param-name-nq> allows for "%", which is
1148 ; not allowed in atoms. Such values must be
1149 ; represented as quoted or literal.
1150
1151 transcod-param-name-nq = Feature-tag
1152 ; <Feature-tag> is defined in [MEDIAFEAT-REG].
1153
1154 transcoding-param-value = astring
1155
1156 default-conversion = "NIL"
1157
1158 message-data =/ nz-number SP "CONVERTED" SP convert-correlator
1159 SP convert-msg-attrs
1160
1161 convert-correlator = "(" "TAG" SP tag-string ")"
1162
1163 tag-string = string 4466:707 9051:7087 ../imapserver/search.go:225
1164 ; tag of the command that caused
1165 ; the CONVERTED response, sent as
1166 ; a string.
1167
1168 convert-msg-attrs = "(" convert-msg-att *(SP convert-msg-att) ")"
1169 ; "UID" MUST be the first data item, if present.
1170
1171 convert-msg-att = msg-att-semistat / msg-att-conv-static
1172
1173 msg-att-conv-static = "UID" SP uniqueid
1174 ; MUST NOT change for a message
1175
1176
1177
1178Melnikov & Coates Standards Track [Page 21]
1179
1180RFC 5259 IMAP CONVERT extension July 2008
1181
1182
1183 msg-att-semistat =
1184 ( "BINARY" section-convert ["<" number ">"] SP
1185 (nstring / literal8 / converterror-phrase) ) /
1186 ( "BINARY.SIZE" section-convert SP
1187 (number / converterror-phrase) ) /
1188 ( "BODYPARTSTRUCTURE" section-convert SP
1189 (body / converterror-phrase) ) /
1190 ( "AVAILABLECONVERSIONS" section-convert SP
1191 (mimetype-list / converterror-phrase) )
1192 ; MUST NOT change during an IMAP "session",
1193 ; but not necessarily static in the long term.
1194
1195 section-convert = section-binary
1196 ; <section-binary> is defined in [RFC3516].
1197 ;
1198 ; Note that unlike [RFC3516], conversion
1199 ; of a top level multipart/* is allowed.
1200
1201 resp-text-code =/ "TEMPFAIL" /
1202 "MAXCONVERTMESSAGES" SP nz-number /
1203 "MAXCONVERTPARTS" SP nz-number
1204 ; <resp-text-code> is defined in [RFC3501].
1205
1206 mimetype-and-params = quoted-to-mime-type
1207 [SP "(" transcoding-params ")"]
1208 ; always includes a specific MIME type
1209
1210 mimetype-list = "(" "(" [quoted-to-mime-type
1211 *(SP quoted-to-mime-type)] ")" ")"
1212 ; Unordered list of MIME types. It can be empty.
1213 ;
1214 ; Two levels of parenthesis is needed to distinguish this
1215 ; data from <converterror-phrase>.
1216
1217 converterror-phrase = "(" "ERROR" SP
1218 convert-err-descript SP convert-error-code ")"
1219
1220 convert-error-code = "TEMPFAIL" [SP nz-number]
1221 / bad-params
1222 / missing-params
1223
1224 convert-err-descript = string
1225 ; Human-readable text explaining the conversion error.
1226 ; The default charset is US-ASCII, unless
1227 ; the LANGUAGE command [IMAP-I18N] is called, when
1228 ; the charset changes to UTF-8.
1229
1230 quoted-from-mime-type = DQUOTE from-concrete-mime-type DQUOTE
1231
1232
1233
1234Melnikov & Coates Standards Track [Page 22]
1235
1236RFC 5259 IMAP CONVERT extension July 2008
1237
1238
1239 bad-params = "BADPARAMETERS"
1240 1*(SP (quoted-from-mime-type / nil)
1241 SP mimetype-and-params)
1242 ; nil is only returned when the body part doesn't exist.
1243
1244 missing-params = "MISSINGPARAMETERS"
1245 1*(SP quoted-from-mime-type SP
1246 mimetype-and-missing-params)
1247
1248 mimetype-and-missing-params = quoted-to-mime-type
1249 "(" transcoding-param-names ")"
1250 ; always includes a specific MIME type
1251
1252 concrete-mime-type = type-name "/" subtype-name
1253 ; i.e., "type/subtype".
1254 ; type-name and subtype-name
1255 ; are defined in [MIME-MTSRP].
1256
1257 from-concrete-mime-type = concrete-mime-type
1258
1259 to-mime-type = concrete-mime-type
1260
1261 command-auth =/ conversions-cmd
1262
1263 conversions-cmd = "CONVERSIONS" SP from-mime-type-req SP
1264 to-mime-type-req
1265
1266 from-mime-type-req = astring
1267 ; "mime-type-req" represented as IMAP <atom>,
1268 ; <quoted> or <literal>
1269
1270 to-mime-type-req = astring
1271 ; <mime-type-req> represented as IMAP <atom>,
1272 ; <quoted> or <literal>.
1273 ; Note that <mime-type-req> allows for "*",
1274 ; which is not allowed in <atom>. Such values must
1275 ; be represented as <quoted> or <literal>.
1276
1277 any-mime-type = "*"
1278
1279 mime-type-req = any-mime-type /
1280 (type-name "/" any-mime-type) /
1281 concrete-mime-type
1282 ; '*', 'type/*' or 'type/subtype'.
1283 ; type-name is defined in [MIME-MTSRP].
1284
1285 response-payload =/ conversion-data
1286
1287
1288
1289
1290Melnikov & Coates Standards Track [Page 23]
1291
1292RFC 5259 IMAP CONVERT extension July 2008
1293
1294
1295 conversion-data = "CONVERSION" SP quoted-from-mime-type SP
1296 quoted-to-mime-type
1297 [SP "(" transcoding-param-name
1298 *(SP transcoding-param-name) ")"]
1299
130011. Manageability Considerations
1301
1302 The monitoring of CONVERT operation is similar to monitoring of the
1303 IMAP FETCH operation.
1304
1305 At the time of writing this document, there is no standard IMAP MIB
1306 defined. Similarly, a standard MIB for monitoring CONVERT operations
1307 and their failures does not exist. However, the authors believe that
1308 in the absence of such a MIB, server implementations SHOULD provide
1309 operators with tools to report the following information:
1310
1311 o which conversions (source and target MIME types and possibly
1312 conversion parameters used) are invoked more frequently and how
1313 long they take,
1314
1315 o information about conversion errors and which error condition
1316 caused them (see Section 9), and
1317
1318 o information about users which invoke conversion operation.
1319
1320 This information can help operators to detect client abuse of this
1321 extension and scalability issues that might arise from its use.
1322
1323 Standardizing these tools may be the subject of future work.
1324
132512. IANA Considerations
1326
1327 IMAP4 capabilities are registered by publishing a Standards Track or
1328 IESG-approved Experimental RFC. This document defines the CONVERT
1329 IMAP capability. IANA has added this extension to the IANA IMAP
1330 Capability registry.
1331
1332 IANA has performed registrations as defined in the following
1333 subsections.
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346Melnikov & Coates Standards Track [Page 24]
1347
1348RFC 5259 IMAP CONVERT extension July 2008
1349
1350
135112.1. Registration of unknown-character-replacement Media Type
1352 Parameter
1353
1354 IANA has added the following registration to the registry established
1355 by RFC 2506.
1356
1357 To: "Media feature tags mailing list"
1358 <media-feature-tags@apps.ietf.org>
1359
1360 Subject: Registration of media feature tag
1361 unknown-character-replacement
1362
1363 Media feature tag name:
1364 unknown-character-replacement
1365
1366 ASN.1 identifier associated with feature tag:
1367 1.3.6.1.8.1.33
1368
1369 Summary of the media feature indicated by this feature tag:
1370 Allows servers that can perform charset conversion for text/plain
1371 text/html, text/css, text/csv, text/enriched, and text/xml MIME
1372 types to replace characters not supported by the target charset
1373 with a fixed string, such as "?".
1374 This feature tag is also applicable to other conversions
1375 to text, e.g., conversion of images using OCR (optical
1376 character recognition).
1377
1378 Values appropriate for use with this feature tag:
1379 The feature tag contains a UTF-8 string used to replace any
1380 characters from the source media type that can't be
1381 represented in the target media type.
1382
1383 The feature tag is intended primarily for use in the following
1384 applications, protocols, services, or negotiation mechanisms:
1385 IMAP CONVERT extension [RFC5259]
1386
1387 Examples of typical use:
1388 C: b001 CONVERT 2 BINARY[3 ("text/plain" ("charset"
1389 "us-ascii" "unknown-character-replacement" "?"))]
1390
1391 Related standards or documents:
1392 [RFC5259]
1393 [CHARSET-REG]
1394
1395 Considerations particular to use in individual applications,
1396 protocols, services, or negotiation mechanisms:
1397 None
1398
1399
1400
1401
1402Melnikov & Coates Standards Track [Page 25]
1403
1404RFC 5259 IMAP CONVERT extension July 2008
1405
1406
1407 Interoperability considerations: None
1408
1409 Security considerations: None
1410
1411 Additional information:
1412 This media feature only make sense for MIME types that
1413 also support the "charset" media type parameter
1414 [CHARSET-REG].
1415
1416 Name(s) & email address(es) of person(s) to contact for further
1417 information:
1418 Alexey Melnikov <alexey.melnikov@isode.com>
1419
1420 Intended usage:
1421 COMMON
1422
1423 Author/Change controller:
1424 IETF
1425
1426 Requested IANA publication delay:
1427 None
1428
1429 Other information:
1430 None
1431
143213. Security Considerations
1433
1434 It is to be noted that some conversions may present security threats
1435 (e.g., converting a document to a damaging executable, exploiting a
1436 buffer overflow in a media codec/parser, or a denial-of-service
1437 attack against a client or a server such as requesting an image be
1438 scaled to extremely large dimensions). Server SHOULD refuse to
1439 execute CPU-expensive conversions. Servers should avoid dangerous
1440 conversions if possible. Whenever possible, servers should perform
1441 verification of the converted attachments before returning them to
1442 the client. Clients should be careful when requesting conversions or
1443 processing transformed attachments. Clients SHOULD use mutual Simple
1444 Authentication and Security Layer (SASL) authentication and the SASL/
1445 TLS integrity layer, to make sure they are talking to trusted
1446 servers.
1447
1448 When the client requests a server-side conversion of a signed body
1449 part (e.g., a part inside multipart/signed), there is no way for the
1450 client to verify that the converted content is authentic. A client
1451 not trusting the server to perform conversion of a signed body part
1452 can download the signed object, verify the signature, and perform the
1453 conversion itself.
1454
1455
1456
1457
1458Melnikov & Coates Standards Track [Page 26]
1459
1460RFC 5259 IMAP CONVERT extension July 2008
1461
1462
1463 A client can create a carefully crafted bad message with the APPEND
1464 command followed by the CONVERT command to attack the server. If the
1465 server's conversion function or library has a security problem (such
1466 as vulnerability to a buffer overflow), this could result in
1467 privilege escalation or denial of service. In order to mitigate such
1468 attacks, servers SHOULD log the client authentication identity on
1469 APPEND and/or CONVERT operations in order to facilitate tracking of
1470 abusive clients. Also server implementors SHOULD isolate the
1471 conversion function or library from the privileged mailstore, perhaps
1472 by running it within a distinct process.
1473
1474 Deployments in which the actual transcoding is done outside the IMAP
1475 server in a separate server are recommended to keep the servers in
1476 the same trusted domain (e.g., subnet).
1477
147814. Acknowledgments
1479
1480 Stephane H. Maes and Ray Cromwell from Oracle edited several earlier
1481 versions of this document. Their contribution is gratefully
1482 acknowledged.
1483
1484 The authors want to specifically acknowledge the excellent criticism
1485 and comments received from Randall Gellens (Qualcomm), Arnt
1486 Gulbrandsen (Oryx), Zoltan Ordogh (Nokia), Ben Last (Emccsoft), Dan
1487 Karp (Zimbra), Pete Resnick (Qualcomm), Chris Newman (Sun), Ted
1488 Hardie (Qualcomm), Larry Masinter (Adobe), Philip Guenther
1489 (Sendmail), Greg Vaudreuil (Alcatel-Lucent), David Harrington
1490 (Comcast), Dave Cridland (Isode), Pasi Eronen (Nokia), Magnus
1491 Westerlund (Ericsson), and Jari Arkko (Ericsson), which improved the
1492 quality of this specification considerably.
1493
1494 The authors would also like to specially thank Dave Cridland for the
1495 MEDIACAPS command proposal and Dan Karp for the CONVERSIONS command
1496 proposal.
1497
1498 The authors also want to thank all who have contributed key insight
1499 and extensively reviewed and discussed the concepts of CONVERT and
1500 its predecessor P-IMAP. In particular, this includes the authors of
1501 the LCONVERT document: Rafiul Ahad (Oracle Corporation), Eugene Chiu
1502 (Oracle Corporation), Ray Cromwell (Oracle Corporation), Jia-der Day
1503 (Oracle Corporation), Vi Ha (Oracle Corporation), Wook-Hyun Jeong
1504 (Samsung Electronics Co. LTF), Chang Kuang (Oracle Corporation),
1505 Rodrigo Lima (Oracle Corporation), Stephane H. Maes (Oracle
1506 Corporation), Gustaf Rosell (Sony Ericsson), Jean Sini (Symbol
1507 Technologies), Sung-Mu Son (LG Electronics), Fan Xiaohui (China
1508 Mobile Communications Corporation (CMCC)), and Zhao Lijun (China
1509 Mobile Communications Corporation (CMCC)).
1510
1511
1512
1513
1514Melnikov & Coates Standards Track [Page 27]
1515
1516RFC 5259 IMAP CONVERT extension July 2008
1517
1518
151915. References
1520
152115.1. Normative References
1522
1523 [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for
1524 Syntax Specifications: ABNF", STD 68, RFC 5234,
1525 January 2008.
1526
1527 [CHARSET-REG] Hoffman, P., "Registration of Charset and Languages
1528 Media Features Tags", RFC 2987, November 2000.
1529
1530 [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to
1531 IMAP4 ABNF", RFC 4466, April 2006.
1532
1533 [MEDIAFEAT-REG] Holtman, K., Mutz, A., and T. Hardie, "Media Feature
1534 Tag Registration Procedure", BCP 31, RFC 2506,
1535 March 1999.
1536
1537 [MIME-MTSRP] Freed, N. and J. Klensin, "Media Type Specifications
1538 and Registration Procedures", BCP 13, RFC 4288,
1539 December 2005.
1540
1541 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail
1542 Extensions) Part Three: Message Header Extensions
1543 for Non-ASCII Text", RFC 2047, November 1996.
1544
1545 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1546 Requirement Levels", BCP 14, RFC 2119, March 1997.
1547
1548 [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and
1549 Encoded Word Extensions:
1550 Character Sets, Languages, and Continuations",
1551 RFC 2231, November 1997.
1552
1553 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL -
1554 VERSION 4rev1", RFC 3501, March 2003.
1555
1556 [RFC3516] Nerenberg, L., "IMAP4 Binary Content Extension",
1557 RFC 3516, April 2003.
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570Melnikov & Coates Standards Track [Page 28]
1571
1572RFC 5259 IMAP CONVERT extension July 2008
1573
1574
157515.2. Informative References
1576
1577 [DISP-FEATURES] Masinter, L., Wing, D., Mutz, A., and K. Holtman,
1578 "Media Features for Display, Print, and Fax",
1579 RFC 2534, March 1999.
1580
1581 [IMAP-I18N] Newman, C., Gulbrandsen, A., and A. Melnikov,
1582 "Internet Message Access Protocol
1583 Internationalization", RFC 5255, June 2008.
1584
1585 [LEM-STREAMING] Cook, N., "Streaming Internet Messaging
1586 Attachments", Work in Progress, June 2008.
1587
1588 [OMA-ME-RD] OMA, "Open Mobile Alliance Mobile Email Requirement
1589 Document", OMA 55.919 3.0.0, December 2007.
1590
1591 [OMA-STI] OMA, "Open Mobile Alliance, Standard Transcoding
1592 Interface Specification", OMA OMA-STI-V1_0,
1593 December 2005.
1594
1595Authors' Addresses
1596
1597 Alexey Melnikov (editor)
1598 Isode Ltd
1599 5 Castle Business Village
1600 36 Station Road
1601 Hampton, Middlesex TW12 2BX
1602 UK
1603
1604 EMail: Alexey.Melnikov@isode.com
1605
1606
1607 Peter Coates (editor)
1608 Sun Microsystems
1609 185 Falcon Drive
1610 Whitehorse, YT Y1A 6T2
1611 Canada
1612
1613 EMail: peter.coates@Sun.COM
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626Melnikov & Coates Standards Track [Page 29]
1627
1628RFC 5259 IMAP CONVERT extension July 2008
1629
1630
1631Full Copyright Statement
1632
1633 Copyright (C) The IETF Trust (2008).
1634
1635 This document is subject to the rights, licenses and restrictions
1636 contained in BCP 78, and except as set forth therein, the authors
1637 retain all their rights.
1638
1639 This document and the information contained herein are provided on an
1640 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
1641 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
1642 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
1643 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
1644 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
1645 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1646
1647Intellectual Property
1648
1649 The IETF takes no position regarding the validity or scope of any
1650 Intellectual Property Rights or other rights that might be claimed to
1651 pertain to the implementation or use of the technology described in
1652 this document or the extent to which any license under such rights
1653 might or might not be available; nor does it represent that it has
1654 made any independent effort to identify any such rights. Information
1655 on the procedures with respect to rights in RFC documents can be
1656 found in BCP 78 and BCP 79.
1657
1658 Copies of IPR disclosures made to the IETF Secretariat and any
1659 assurances of licenses to be made available, or the result of an
1660 attempt made to obtain a general license or permission for the use of
1661 such proprietary rights by implementers or users of this
1662 specification can be obtained from the IETF on-line IPR repository at
1663 http://www.ietf.org/ipr.
1664
1665 The IETF invites any interested party to bring to its attention any
1666 copyrights, patents or patent applications, or other proprietary
1667 rights that may cover technology that may be required to implement
1668 this standard. Please address the information to the IETF at
1669 ietf-ipr@ietf.org.
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682Melnikov & Coates Standards Track [Page 30]
1683
1684