Network Working Group A. Melnikov, Ed.
Internet-Draft Isode Ltd
Intended status: Standards Track P. Coates, Ed.
Expires: August 15, 2008 Sun Microsystems
February 12, 2008
IMAP CONVERT extension
draft-ietf-lemonade-convert-14.txt
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 15, 2008.
Copyright Notice
Copyright (C) The IETF Trust (2008).
Abstract
CONVERT defines extensions to IMAP allowing clients to request
adaptation and/or transcoding of attachments. Clients can specify
the conversion details or allow servers to decide based on knowledge
of client capabilities, on user or administrator preferences or its
settings.
Melnikov & Coates Expires August 15, 2008 [Page 1]
Internet-Draft IMAP CONVERT extension February 2008
Table of Contents
1. Introduction and Conventions used in this document . . . . . . 3
2. Conventions used in this document . . . . . . . . . . . . . . 3
3. Relation with other IMAP specifications . . . . . . . . . . . 4
3.1. CAPABILITY response . . . . . . . . . . . . . . . . . . . 4
4. Scope of Conversions . . . . . . . . . . . . . . . . . . . . . 4
5. Discovery of available conversions and controlling default
conversions . . . . . . . . . . . . . . . . . . . . . . . . . 4
5.1. Client preferences regarding default conversions:
MEDIACAPS Command . . . . . . . . . . . . . . . . . . . . 4
5.2. Discovery of available conversions . . . . . . . . . . . . 6
5.2.1. CONVERSIONS command . . . . . . . . . . . . . . . . . 6
6. CONVERT and UID CONVERT commands . . . . . . . . . . . . . . . 7
7. CONVERT transcoding parameters . . . . . . . . . . . . . . . . 12
7.1. Mandatory to Implement Transcoding parameters . . . . . . 13
7.2. Additional features for mobile usage . . . . . . . . . . . 13
8. Request/response data items to CONVERT/UID CONVERT commands . 14
8.1. CONVERTED untagged response . . . . . . . . . . . . . . . 14
8.2. BODYPARTSTRUCTURE CONVERT request and response item . . . 14
8.3. BINARY.SIZE CONVERT request and response item . . . . . . 15
8.4. Implementation considerations . . . . . . . . . . . . . . 16
9. Status responses, Response code extensions . . . . . . . . . . 16
10. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 19
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22
11.1. Registration of unknown-character-replacement media
type parameter . . . . . . . . . . . . . . . . . . . . . . 22
12. Security Considerations . . . . . . . . . . . . . . . . . . . 24
13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24
14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25
14.1. Normative References . . . . . . . . . . . . . . . . . . . 25
14.2. Informative References . . . . . . . . . . . . . . . . . . 26
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 26
Intellectual Property and Copyright Statements . . . . . . . . . . 28
Melnikov & Coates Expires August 15, 2008 [Page 2]
Internet-Draft IMAP CONVERT extension February 2008
1. Introduction and Conventions used in this document
This document defines the CONVERT extension to IMAP4 [RFC3501].
CONVERT provides adaptation and transcoding of body parts as needed
by the client. Conversion (adaptation, transcoding) may be requested
by the client and performed by the server on a best effort basis or,
when requested by the client, decided by the server based on server's
knowledge of the client capabilities, user or administrator
preferences or server settings.
This extension is primarily intended to be useful to mobile clients.
It satisfies requirements specified in [OMA-ME-RD]
A server that supports CONVERT can convert body parts to other
formats to be viewed (for example) on a mobile device. The client
can explicitly request a particular conversion or ask the server to
select the best available conversion. When allowed by the client,
the server determines how to convert based on its own strategy (e.g.
based on knowledge of the client as discussed hereafter). If the
server knows the characteristics of the device (out of scope for
CONVERT) or can determine them, for example using the MEDIACAPS
command described below, converted body parts can also be optimized
for capabilities of the device (e.g. form factor of pictures). The
client is able to control conversions using optional conversion (or
transcoding) parameters.
This document relies on the registry of transcoding parameters
established by [MEDIAFEAT-REG]. The registry can be used to discover
the underlying legal values that these parameters may take.
Additional transcoding parameters, such as those defined by
[OMA-STI], are expected to be registered in the future.
2. Conventions used in this document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively. If a single "C:" or "S:" label applies to
multiple lines, then the line breaks between those lines are for
editorial clarity only and are not part of the actual protocol
exchange. The five characters [...] means that something has been
elided.
When describing the general syntax, some definitions are omitted as
they are defined in [RFC3501]. In particular, the term "session" is
Melnikov & Coates Expires August 15, 2008 [Page 3]
Internet-Draft IMAP CONVERT extension February 2008
used in this document as defined in Section 1.2 of [RFC3501].
[[anchor3: Editorial comments and questions are marked like this.]]
3. Relation with other IMAP specifications
The CONVERT extension does not address conversion during streaming of
attachments.
A server claiming compliance with this specification, MUST support
the IMAP Binary specification [RFC3516].
3.1. CAPABILITY response
A server that supports the CONVERT extension MUST return "CONVERT",
and "BINARY" in the CAPABILITY response or response code. (Client
and server authors are reminded that the order of tokens returned in
the CAPABILITY response or response code is arbitrary.)
Example: A server that implements CONVERT
C: a001 CAPABILITY
S: * CAPABILITY IMAP4rev1 CONVERT BINARY [...]
S: a001 OK CAPABILITY completed
4. Scope of Conversions
Conversions only affect what is sent to the client; the original data
in the message store MUST NOT be altered. This document does not
specify how the server performs conversions.
Note: The requirement that original data be unaltered allows such
data to remain accessible by other clients, permits replies or
forwards of the original documents, permits signature verification
(the converted body parts are not likely to contain any signatures),
and preserves BODYSTRUCTURE and related information.
5. Discovery of available conversions and controlling default
conversions
5.1. Client preferences regarding default conversions: MEDIACAPS
Command
Melnikov & Coates Expires August 15, 2008 [Page 4]
Internet-Draft IMAP CONVERT extension February 2008
Arguments: list of supported MIME types and corresponding conversion
parameters
Responses: none
Result: OK - MEDIACAPS command completed
BAD - unrecognized syntax of an argument
The client list MIME types and corresponding conversion parameters in
the order of preference, starting with the most prefered MIME media
type(s).
Servers MUST ignore conversion parameters and MIME types that they
don't recognize.
If a MEDIACAPS command was issued on a connection and the client has
requested to perform the default conversion (see Section 6 for more
details), the server MUST use one of the MIME types specified by the
client in this command as the target MIME type. The server SHOULD
use the first MIME type from the ordered list that it supports.
Example:
C: A01 MEDIACAPS ("TEXT" "HTML") ("TEXT" "PLAIN" "FORMAT" ("FLOWED"
"FIXED")) ("TEXT" "*" "CHARSET" ("UTF-8" "US-ASCII")) ("IMAGE"
("JPEG" "PNG" "GIF") "PIX-X" "240" "PIX-Y" "320")
[[anchor9: The FORMAT conversion parameter is not registered with
IANA]]
With such command the client is saying (each parenthesized list
converted to a sentence): "I do text/html. I will also do text/
plain, preferably with format=flowed, but I can handle format=fixed
too. For all text media types I do, I can handle a charset of either
UTF-8 or US-ASCII. I can handle image/jpeg, image/png, and, least
preferred, image/gif, and my ideal resolution is 240x320."
ABNF for this command is as follows:
Melnikov & Coates Expires August 15, 2008 [Page 5]
Internet-Draft IMAP CONVERT extension February 2008
mediacaps-cmd = "MEDIACAPS" 1*(SP mediacap)
mediacap = "(" media-type SP media-subtype
*( SP media-param SP media-param-values ) ")"
media-type = astring
media-subtype = DQUOTE "*" DQUOTE /
astring /
"(" astring *( SP astring ) ")"
;; "*" means all subtypes for the media-type specified
;; in the command.
;; Otherwise, either the specific subtype or a list of them.
media-param = astring
media-param-values = astring / "(" astring *(SP astring) ")"
;; Either a single acceptable value or a list of
;; acceptable values.
5.2. Discovery of available conversions
5.2.1. CONVERSIONS command
Arguments: source MIME type
target MIME type
Responses: untagged responses: CONVERSION
Result: OK - CONVERSIONS command completed
BAD - unrecognized syntax of an argument,
unexpected extra argument, missing argument, etc.
The first parameter to the CONVERSIONS command is a source MIME type,
the second parameter is the target MIME type. Both parameters are
partially (e.g. "text/*") or completely ("*") wildcardable.
Conversions matching the source/target pair and their associated
conversion parameters are returned in untagged CONVERSIONS responses.
If source/target doesn't match any conversion supported by the
server, no CONVERSIONS response is returned.
Examples:
For conversion info from GIF to JPEG (no untagged CONVERT would be
returned if no conversion was possible):
Melnikov & Coates Expires August 15, 2008 [Page 6]
Internet-Draft IMAP CONVERT extension February 2008
C: a CONVERSIONS "image/gif" "image/jpeg"
S: * CONVERSION "image/gif" "image/jpeg" ("width" "height"
"depth" "interlaced")
S: a OK CONVERSIONS completed
For conversion info from GIF to anything:
C: b CONVERSIONS "image/gif" *
S: * CONVERSION "image/gif" "image/jpeg" ("width" "height"
"depth" "interlaced")
S: * CONVERSION "image/gif" "image/png" (...)
[...]
S: b OK CONVERSIONS completed
For conversion of anything to JPEG:
C: c CONVERSIONS * "image/jpeg"
S: * CONVERSION "image/gif" "image/jpeg" ("width" "height"
"depth" "interlaced")
S: * CONVERSION "image/png" "image/jpeg" (...)
[...]
S: c OK CONVERSIONS completed
For conversions from all image formats to all text formats (maybe via
OCR?):
C: d CONVERSIONS "image/*" "text/*"
S: d OK CONVERSIONS completed
[[anchor12: ABNF is missing for this proposal.]]
6. CONVERT and UID CONVERT commands
Arguments: sequence set
conversion parameters
CONVERT data item names
Responses: untagged responses: CONVERTED
Result: OK - convert completed
NO - convert error: can't fetch and/or convert that data
BAD - unrecognized syntax of an argument,
unexpected extra argument, missing argument, etc.
The CONVERT extension defines CONVERT and UID CONVERT commands which
are used to transcode the media type of a MIME part into another
media type, and/or the same media type with different encoding
Melnikov & Coates Expires August 15, 2008 [Page 7]
Internet-Draft IMAP CONVERT extension February 2008
parameters. These commands are structured and behave similarly to
FETCH/UID FETCH commands as extended by [RFC3516]:
o A successful CONVERT/UID CONVERT command results in one or more
untagged CONVERTED responses (one per message). They are similar
to the untagged FETCH responses. Note that a single CONVERT/ UID
CONVERT command can only perform a single type of conversion as
defined by the conversion parameters. A client that needs to
perform multiple different conversions needs to issue multiple
CONVERT/UID CONVERT commands. Such client MAY pipeline them.
o BINARY[...] data item requests conversion of a body part or of the
whole message according to conversion parameters and returning it
as binary.
o BINARY.SIZE data item is similar to RFC822.SIZE, but it requests
size of a converted body part/message.
o BODYPARTSTRUCTURE data item is similar to BODYSTRUCTURE FETCH data
item, but it returns the MIME structure of the converted body
part.
o BODY[...HEADER] encoded words in the requested headers are
converted to the specified charset. The CHARSET parameter is
REQUIRED for this conversion.
o BODY[...MIME] encoded words in the requested headers are converted
to the specified charset. The CHARSET parameter is REQUIRED for
this conversion.
o [[anchor13: Add AVAILABLECONVERSIONS here]]
The CONVERT extension also adds one new response code. See Section 9
for more details.
Typically clients will request conversion of leaf body parts. In
addition to support of leaf body part conversion, servers MAY offer
conversion of non-leaf body parts (e.g. conversion from multipart/
related).
Instead of specifying the exact target MIME media type the client
wants to convert to, the client MAY use a special marker NIL (also
known as "default conversion") to request the server to pick a
suitable target media type. This document doesn't describe how the
server makes such a choice. For example, the server can know
characteristics of the device through a device description mechanism,
or it can have a prioritized list of MIME types based on how
widespread they are, how difficult their rendering is, etc. Note
Melnikov & Coates Expires August 15, 2008 [Page 8]
Internet-Draft IMAP CONVERT extension February 2008
that servers are REQUIRED to support "default conversion" requests.
CONVERT's command syntax is modeled after the FETCH command syntax in
[RFC3501], as extended by [RFC3516]. CONVERT data items are
generally structured as:
BINARY[section-part]<partial>
BINARY.SIZE[section-part]
BODYPARTSTRUCTURE[section-part]
BODY[HEADER]
BODY[section-part.HEADER]
BODY[section-part.MIME]
The semantics of a partial CONVERT BINARY[...] command is the same as
for a partial FETCH BODY[...] command, with the exception that the
<partial> arguments refer to the TRANSCODED and DECODED section data.
Note that unlike the FETCH command, the CONVERT command never sets
the \Seen flag on converted messages. A client wishing to mark a
message with the \Seen flag would need to issue a STORE command
(possibly pipelined with the CONVERT request) to do that.
The UID CONVERT command is different from the CONVERT command in the
same way as the UID FETCH command is different from the FETCH
command:
o UID CONVERT takes as a parameter a sequence of UIDs instead of a
sequence of message numbers.
o UID CONVERT requires that the server returns UID data item in a
corresponding CONVERTED response.
Example: The client fetches body part section 3 in the message with
the message sequence number of 2 and asks to have that attachment
converted to pdf format.
C: a001 CONVERT 2 ("APPLICATION/PDF") BINARY[3]
S: * 2 CONVERTED (TAG "a001") (BINARY[3] {2135}
<the document in .pdf format>
)
S: a001 OK CONVERT COMPLETED
Example: The client requests for conversion of a text/html body part
Melnikov & Coates Expires August 15, 2008 [Page 9]
Internet-Draft IMAP CONVERT extension February 2008
to text/plain and asks for a charset of us-ascii. The server cannot
respect the charset conversion request because there are non-us-ascii
characters in the text/html body part, so it fails the request by
returning an ERROR phrase in place of the converted data (see
Section 9).
C: b001 CONVERT 2 ("text/plain" ("charset" "us-ascii")) BINARY[3]
S: * 2 CONVERTED (tag "b001") (BINARY[3]
(ERROR "Source text has non us-ascii" BADPARAMETERS
"text/html" "text/plain" ("charset" "us-ascii")))
S: b001 NO All conversions failed
If the client also specified the "unknown-character-replacement"
conversion parameter (see Section 11.1), the same example can look
like this:
C: b001 CONVERT 2 ("text/plain" ("charset" "us-ascii"
"unknown-character-replacement" "?")) BINARY[3]
S: * 2 CONVERTED (TAG "b001") (BINARY[3] {2135}
<the document in text/plain format with us-ascii
charset>
)
S: b001 OK CONVERT COMPLETED
The server replaced non-us-ascii characters with a us-ascii character
such as "?".
Example: The client first requests the converted size of a text/html
body part converted to text/plain:
C: c000 CONVERT 2 ("TEXT/PLAIN" ("CHARSET" "us-ascii"))
BINARY.SIZE[4]
S: * 2 CONVERTED (TAG "c000") (BINARY.SIZE[4] 3135)
S: c000 OK CONVERT COMPLETED
Later on the client requests 1000 bytes from the converted body part,
starting from byte 2001:
C: c001 CONVERT 2 ("TEXT/PLAIN" ("CHARSET" "us-ascii"))
BINARY[4]<2001.1000>
S: * 2 CONVERTED (TAG "c001") (BINARY[4]<2001> {135}
<bytes 2001 - 2135 of the document in text/plain format>
)
S: c001 OK CONVERT COMPLETED
The server MUST respect the target MIME type and transcoding
parameters specified by the client in the transcoding request. Note
that some transcoding parameters can restrict what kind of conversion
Melnikov & Coates Expires August 15, 2008 [Page 10]
Internet-Draft IMAP CONVERT extension February 2008
is possible, while others can remove some restrictions.
Specifying any non leaf section part requires that the server know
how to convert a multipart message, for instance into a PDF document.
The client can request header convertions using the BODY[...HEADER]
CONVERT request, for example
C: D001 FETCH 2 BODY[HEADER]
S: * 2 FETCH (BODY[HEADER] {140}
S: Date: Mon, 20 Apr 2007 20:05:43 +0200
S: From: Peter <peter@siroe.com>
S: To: Alexey <alexey@siroe.com>
S: Subject: =?KOI8-R?Q?why encode this?=
S:
S: )
S: D001 OK
C: D002 CONVERT 2 (NIL ("CHARSET" "utf-8")) BODY[HEADER]
S: * 2 CONVERTED (TAG "d002") (BODY[HEADER] {139}
S: Date: Mon, 20 Apr 2007 20:05:43 +0200
S: From: Peter <peter@siroe.com>
S: To: Alexey <alexey@siroe.com>
S: Subject: =?UTF-8?Q?why encode this?=
S:
S: )
S: D002 OK
Such request REQUIREs that the server decode any encoded words (as
described in [RFC2047]) in headers and return them re-encoded in the
specified charset. (Note that encoded-words might not be needed if
the result can be represented entirely in US-ASCII.) Any such
request REQUIREs the CHARSET parameter. Servers SHOULD also support
decoding of any parameters as described in [RFC2231]. These
parameters are non-trivial, and converting them without reformatting
the header is not always going to be possible. Consider the
following
C: D011 FETCH 3 BODY[1.MIME]
S: * 3 FETCH (BODY[1.MIME] {118}
S: Content-Type: text/plain; charset=utf-8;
S: foo*0*=utf-8'fr'tr%c0;
S: foo*1*(very)=%03s_m%c0;
S: foo*2*=(nasty)%09chant
S:
S: D011 OK
The server ought to endeavour to preserve the headers during the
conversion as much as possible. In case the characters are split
Melnikov & Coates Expires August 15, 2008 [Page 11]
Internet-Draft IMAP CONVERT extension February 2008
(legally!) between fragments of an encoded parameter, the server MUST
consolidate the parameter fragments, and convert, emit and re-
fragment them as necessary in order to keep the line length less than
78. Comments embedded like this SHOULD be preserved during
conversion, but MAY be removed entirely. If they are preserved, they
MAY be moved after the parameter. For example (continuing the
previous example):
C: D012 CONVERT 3 (NIL) BODY[1.MIME]
S: * 3 CONVERTED (TAG "D012") (BODY[1.MIME] {109}
S: Content-Type: text/plain; charset=utf-8;
S: foo*0*=utf-8'fr'tr%c0%03s_;
S: foo*1*=%m%c0%09chant (very)(nasty)
S:
S: D012 OK
No destination MIME type may be specified with BODY[HEADER],
BODY[section.HEADER], or BODY[section.MIME]. It is important the
encoded words be left as encoded words as to do otherwise may alter
the semantics of structured headers.
7. CONVERT transcoding parameters
IMAP servers which support CONVERT MAY support additional transcoding
parameters for each media type, as defined by the registry
established by [MEDIAFEAT-REG]. All such servers MUST at least
support recognition of the "charset" [CHARSET-REG] parameter for
text/plain, text/html, text/css, text/csv, text/enriched and text/xml
MIME types. Note, a server implementation is not required to support
any conversion from the text MIME subtypes specified above, except
for the mandatory to implement conversion described in Section 7.1.
I.e., a server implementation MUST support the "charset" parameter
for text/csv, only if it supports any conversion from text/csv.
Note, that according to [MEDIAFEAT-REG], transcoding parameter names
are case-insensitive.
The following example illustrates how target picture dimensions can
be specified in a CONVERT request using the PIX-X and PIX-Y
parameters defined in [DISPLAY-FEATURES].
C: d001 UID CONVERT 100 ("IMAGE/JPG" ("PIX-X" "128"
"PIX-Y" "96")) BINARY[2]
S: * 2 CONVERTED (TAG "d001") (UID 100 BINARY[2] ~{4182}
<this part of a document is a rescaled image in
JPG format with width=128, height=96.>
)
Melnikov & Coates Expires August 15, 2008 [Page 12]
Internet-Draft IMAP CONVERT extension February 2008
S: d001 OK UID CONVERT COMPLETED
7.1. Mandatory to Implement Transcoding parameters
A server implementing CONVERT MUST support charset conversions for
the text/plain MIME type, and MUST support charset conversions from
iso-8859-1, iso-8859-2, iso-8859-3, iso-8859-4, iso-8859-5,
iso-8859-6, iso-8859-7, iso-8859-8 and iso-8859-15 to utf-8.
The server MUST list "text/plain" as an allowed destination
conversion in the "/convert/text/plain/types" annotation. A request
for annotation "/convert/text/plain/text/plain/params" MUST return
"charset" and "unknown-character-replacement" (see Section 11.1) as
supported transcoding parameters.
The server MUST support decoding of [RFC2047] headers and their
conversion to UTF-8 as long as the encoded words are in one of the
supported charsets.
Servers SHOULD offer additional character encoding conversions where
they make sense as character conversion libraries are generally
available on many platforms.
If the server cannot carry out the charset conversion while
preserving all the characters (i.e. a source character can't be
represented in the target charset), and the "unknown-character-
replacement" conversion parameter is not specified, then the server
MUST fail the conversion and MUST return the untagged ERROR
BADPARAMETERS response (see Section 9). If the value specified in
the "unknown-character-replacement" conversion itself can't be
represented in the target charset, then the server MUST also fail the
conversion and MUST return the untagged ERROR BADPARAMETERS response
(see Section 9).
7.2. Additional features for mobile usage
This section is informative.
Based on the expected usage of convert in mobile environments, server
implementors should consider support for the following conversions:
o Conversion of HTML and XHTML documents to text/plain in ways that
preserve at the minimum the document structure and tables.
o Image conversions among the types image/gif, image/jpeg and image/
png for at least the following parameters:
Melnikov & Coates Expires August 15, 2008 [Page 13]
Internet-Draft IMAP CONVERT extension February 2008
* Size limit (i.e. reduce quality),
* width,
* height,
* resize directive (crop, stretch, aspect ratio)
The support for "depth" may also be of interest.
Audio conversion is also of interest but the relevant formats depend
significantly on the usage context.
8. Request/response data items to CONVERT/UID CONVERT commands
8.1. CONVERTED untagged response
Contents: convert correlator
CONVERTED return data items
The CONVERTED response may be sent as a result of a successful,
partially successful or unsuccessful CONVERT or UID CONVERT command
specified in section 5 of this document.
The CONVERTED response starts with a message number, followed by the
"CONVERTED" label. The label is followed by a convert correlator,
which contains the tag of the command that caused the response to be
returned. This can be used by a client to match a CONVERTED response
against a corresponding CONVERT/UID CONVERT command.
The convert correlator is followed by a list of one or more CONVERT
return data items. If the UID data item is returned, it MUST be
returned as the first data item in the CONVERTED response. This
requirement is to simplify client implementations. See Section 10
and the remainder of Section 8 for more details.
8.2. BODYPARTSTRUCTURE CONVERT request and response item
The CONVERT extension defines the BODYPARTSTRUCTURE CONVERT data
item. Data contained in the BODYPARTSTRUCTURE return data item
follows the exact syntax specified in the [RFC3501] BODYSTRUCTURE
data item, but only contains information for the converted part. All
information contained in BODYPARTSTRUCTURE pertains to the state of
the part after it is converted, such as the converted MIME type, sub-
type, size, or charset. Note that the client can expect the returned
MIME type to match the one it requested (as the server is required to
obey the requested MIME type) and can treat mismatch as an error.
Melnikov & Coates Expires August 15, 2008 [Page 14]
Internet-Draft IMAP CONVERT extension February 2008
The returned BODYPARTSTRUCTURE data MUST match the BINARY data
returned for the exactly the same conversion in the same IMAP
"session". This requirement allows a client to request
BODYPARTSTRUCTURE and BINARY data in separate commands in the same
IMAP session.
A response to a CONVERT command containing the BODYPARTSTRUCTURE data
item MUST return a BODYPARTSTRUCTURE data item (in the CONVERTED
response) before any other data items for the same body part. The
BODYSTRUCTURE data item MUST be after the UID data item if the UID
data item is present. This requirement is to simplify handling of
converted data in clients.
Example:
C: e001 CONVERT 2 (NIL ("PIX-X" "128" "PIX-Y" "96")) (BINARY[2]
BODYPARTSTRUCTURE[2])
S: * 2 CONVERTED (TAG "e001") (BODYPARTSTRUCTURE[2] ("IMAGE"
"JPG" () NIL NIL "8bit" 4182 NIL NIL NIL) BINARY[2]
~{4182}
<this part of a document is a rescaled image in
JPG format with width=128, height=96.>
)
S: e001 OK CONVERT COMPLETED
8.3. BINARY.SIZE CONVERT request and response item
BINARY.SIZE[section-part ("media type/subtype" (parameters))]
Requests the converted size of the section (i.e., the size to expect
in a response to the corresponding CONVERT BINARY request). The
returned value MUST be exact and MUST NOT change during a duration of
an IMAP "session". This allows a client to download a converted part
in chunks (using "<partial>"). This requirement means that in most
cases the server needs to perform conversion of the requested body
part before returning its size.
In order to allow for upgrade of server transcoding components,
clients MUST NOT assume that repeating a particular body part
conversion in another IMAP "session" would yield the same result as a
previous conversion of the very same body part - any characteristics
of the converted body part might be different (format, size, etc).
In particular clients MUST NOT cache sizes of converted messages/body
parts beyond duration of any IMAP "session", or use sizes obtained in
one connection in another IMAP connection to the same server.
Historical Note: Previous experience with IMAP servers which returned
estimated RFC822.SIZE value shows that this caused interoperability
problems. If the server returns a value which is smaller that the
Melnikov & Coates Expires August 15, 2008 [Page 15]
Internet-Draft IMAP CONVERT extension February 2008
actual size, this will result in data truncation if <partial>
download is used. If the server returns a value which is bigger that
the actual size, this might mislead a client to believe that it
doesn't have enough storage to download a body part.
Note for client implementors: client authors are cautioned that this
might be an expensive operation for some server implementations.
Needlessly issuing this request could result in degraded performance
due to servers having to calculate the value every time the request
is issued. For that reason it is not a good idea to needlessly
request BINARY.SIZE and use it in a UI to allow a user to chose
between multiple conversions.
8.4. Implementation considerations
Servers may disallow a conversion request on multiple messages at
once, e.g.
C: g001 CONVERT 1:* ("text/plain" ("charset" "us-ascii"))
BINARY[3]
S: g001 NO [MAXCONVERTMESSAGES 1]
Note for server implementors: In order to improve performance,
implementations are encouraged to cache converted body parts. For
example, the server may perform a body part conversion when it
receives BINARY.SIZE[...], BODYPARTSTRUCTURE[...] or BINARY[...]
request and cache it until the client requests conversion/download of
another body part, or until mailbox is closed. In order to mitigate
Denial-of-Service attacks from misbehaving or badly-written clients,
a server SHOULD limit the number of converted body parts it can
cache. Servers SHOULD be able to cache at least 2 conversions at any
given time. Servers MAY refuse to execute conversion requests that
convert multiple messages and/or body parts at once, e.g. a
conversion request that specifies multiple message numbers/UIDs.
For instance
C: h001 CONVERT 1 ("text/plain" ("charset" "us-ascii"))
(BINARY[1] BINARY[2])
S: g001 NO [MAXCONVERTPARTS 1]
9. Status responses, Response code extensions
A syntactically invalid MIME media type SHOULD generate a BAD tagged
response from the server. An unrecognized MIME media type generates
Melnikov & Coates Expires August 15, 2008 [Page 16]
Internet-Draft IMAP CONVERT extension February 2008
a NO tagged response.
Some transcodings may require parameters. If a transcoding request
with no parameters is sent for a format which requires parameters,
the server will return an ERROR MISSINGPARAMETERS phrase in place of
the data associated with the data items requested. This is analogous
to the NIL response in FETCH, but with structured data associated
with the failure.
If the server is unable to perform the requested conversion because a
resource is temporary unavailable (e.g., lack of disk space,
temporary internal error, transcoding service down) then the server
MUST return a tagged NO response that SHOULD contain the TEMPFAIL
response code (see below), or an ERROR TEMPFAIL phrase.
If the requested conversion cannot be performed because of a
permanent error, for example if a proprietary document format has no
existing transcoding implementation, the server MUST return a
CONVERTED response containing a ERROR BADPARAMETERS or ERROR
MISSINGPARAMETERS phrase.
The server MAY choose to return one ERROR phrase for a single
conversion if several related data items are requested. For
instance:
C: b002 CONVERT 2 ("text/plain" ("charset" "us-ascii"))
(BINARY[3] BODYPARTSTRUCTURE[3])
S: * 2 CONVERTED (tag "b002") (BODYPARTSTRUCTURE[3]
(ERROR "Source text has non us-ascii" BADPARAMETERS
"text/html" "text/plain" ("charset" "us-ascii")))
S: b002 NO All conversions failed
If at least one conversion succeeds the server MUST return an OK
response. If all conversions fail, the server MAY return OK or NO.
For instance
C: b002 CONVERT 2 ("text/plain" ("charset" "us-ascii"))
(BINARY[3] BODYPARTSTRUCTURE[3] BINARY[4]
BODYPARTSTRUCTURE[4])
S: * 2 CONVERTED (tag "b002") (BODYPARTSTRUCTURE[3]
(ERROR "Source text has non us-ascii" BADPARAMETERS
"text/html" "text/plain" ("charset" "us-ascii"))
BODYSTRUCTURE[4] ("TEXT" "PLAIN" (CHARSET US-ASCII)
NIL NIL "8bit" 4182 NIL NIL NIL) BINARY[4] {4182}
<body in text plain>
)
S: b002 OK Some conversions failed
Melnikov & Coates Expires August 15, 2008 [Page 17]
Internet-Draft IMAP CONVERT extension February 2008
The client in general can tell from the BODYPARTSTRUCTURE response
whether or not its request was honored exactly, but may not know the
reasons why.
This document defines the following response code which can be
returned in the tagged NO response code:
TEMPFAIL - the transcoding request failed temporarily. It might
succeed later, so the client may retry.
MAXCONVERTMESSAGES <number> - the server is unable or unwilling to
convert more than <number> messages in any given CONVERT/UID CONVERT
request.
MAXCONVERTPARTS <number> - the server is unable or unwilling to
convert more than <number> body parts of a message at once in any
given CONVERT/UID CONVERT request.
The word ERROR is always followed by an informal human readable
descriptive text, which is followed by the convert-error-code. The
convert-error-code, MUST be one of the following:
TEMPFAIL mm - the transcoding request failed temporarily. It might
succeed later, so the client may retry. The client SHOULD wait for
at least mm minutes before retrying.
BADPARAMETERS from-concrete-mime-type to-mime-type "(" transcoding-
params ")" -
the listed parameters were not understood, not valid for the source/
destination MIME type pair, had invalid values or could not be
honored for another reason noted in the human readable text that was
specified after the ERROR label. The transcoding-params can be
omitted, in which case it means that the conversion from the from-
concrete-mime-type to the to-mime-type is not possible. If the from-
concrete-mime-type is NIL, this means that the specified body part
doesn't exist. All unrecognised or irrelevent parameters MUST be
listed in the transcoding-params. It is not legal behaviour to
ignore irrelevent parameters.
Note that if the client requested the "default conversion" (see
Section 6), the to-mime-type contains the destination MIME type
chosen by the server.
MISSINGPARAMETERS from-concrete-mime-type to-mime-type "("
transcoding-params ")" -
the listed parameters are required for conversion of the specified
source MIME type to the destination MIME type, but were not seen in
the request. Note that if the client requested the "default
Melnikov & Coates Expires August 15, 2008 [Page 18]
Internet-Draft IMAP CONVERT extension February 2008
conversion" (see Section 6), the to-mime-type contains the
destination MIME type chosen by the server.
Examples:
C: b002 CONVERT 2 ("APPLICATION/PDF") BINARY[3]
S: b002 NO [TEMPFAIL] All conversions failed
C: b003 CONVERT 2 ("TEXT/PLAIN") BINARY[3]
S: * 2 CONVERTED (tag "b003") (BINARY[3]
(ERROR "CHARSET must be specified for text conversions"
MISSINGPARAMETERS (CHARSET)))
S: b003 NO All conversions failed
C: b005 CONVERT 2 ("TEXT/PLAIN" (CHARSET "US-ASCII"
UNKNOWN-CHARACTER-REPLACEMENT "<badchar>")) BINARY[3]
S: * 2 CONVERTED (tag "b005") (BINARY[3]
(ERROR "UNKNOWN-CHARACTER-REPLACEMENT limited to 4
bytes" BADPARAMETERS (UNKNOWN-CHARACTER-REPLACEMENT
"<badchar>")))
S: b005 NO All conversions failed
10. Formal Syntax
The following syntax specification uses the augmented Backus-Naur
Form (ABNF) notation as used in [ABNF], and incorporates by reference
the Core Rules defined in that document.
This syntax augments the grammar specified in [RFC3501] and
[RFC3516]. Non-terminals not defined in this document can be found
in [RFC3501], [RFC3516], [IMAPABNF], [MIME-MTSRP] and
[MEDIAFEAT-REG].
command-select =/ convert
uid =/ "UID" SP convert
; Unique identifiers used instead of message
; sequence numbers
convert = "CONVERT" SP sequence-set SP convert-params SP
( convert-att /
"(" convert-att *(SP convert-att) ")" )
convert-att = "UID" /
"BODYPARTSTRUCTURE" section-convert /
"BINARY" section-convert [partial] /
"BINARY.SIZE" section-convert /
Melnikov & Coates Expires August 15, 2008 [Page 19]
Internet-Draft IMAP CONVERT extension February 2008
"BODY[HEADER]" /
"BODY[" section-part ".HEADER]" /
"BODY[" section-part ".MIME]"
; "partial" is defined in [RFC3516]
; section-part is defined in [RFC3501].
convert-params = "(" (quoted-to-mime-type / default-conversion)
[SP "(" transcoding-params ")"] ")"
quoted-to-mime-type = DQUOTE to-mime-type DQUOTE
transcoding-params = transcoding-param
*(SP transcoding-param)
transcoding-param-names = transcoding-param-name
*(SP transcoding-param-name)
transcoding-param = transcoding-param-name SP
transcoding-param-value
transcoding-param-name = astring
; <transcod-param-name-nq> represented as a quoted,
; literal or atom. Note that
; <transcod-param-name-nq> allows for "%" which is
; not allowed in atoms. Such values must be
; represented as quoted or literal.
transcod-param-name-nq = Feature-tag
; Feature-tag is defined in [MEDIAFEAT-REG].
transcoding-param-value = astring
default-conversion = "NIL"
message-data =/ nz-number SP "CONVERTED" SP convert-correlator
SP convert-msg-attrs
convert-correlator = "(" "TAG" SP tag-string ")"
tag-string = string
; tag of the command that caused
; the CONVERTED response, sent as
; a string.
convert-msg-attrs = "(" convert-msg-att *(SP convert-msg-att) ")"
; "UID" MUST be the first data item, if present.
convert-msg-att = msg-att-semistat / msg-att-conv-static
Melnikov & Coates Expires August 15, 2008 [Page 20]
Internet-Draft IMAP CONVERT extension February 2008
msg-att-conv-static = "UID" SP uniqueid
; MUST NOT change for a message
msg-att-semistat =
( "BINARY" section-convert ["<" number ">"] SP
(nstring / literal8 / converterror-phrase) ) /
( "BINARY.SIZE" section-convert SP
(number / converterror-phrase) ) /
( "BODYPARTSTRUCTURE" section-convert SP
(body / converterror-phrase) )
; MUST NOT change during an IMAP "session",
; but not necessarily static in a long term.
section-convert = section-binary
; <section-binary> is defined in [RFC3516].
;
; Note that unlike [RFC3516], conversion
; of a top level multipart/* is allowed.
In the ABNF syntax "resp-text-code" of [RFC3501], is amended to:
resp-text-code =/ "TEMPFAIL" /
"MAXCONVERTMESSAGES" SP nz-number /
"MAXCONVERTPARTS" SP nz-number
mimetype-and-params = quoted-to-mime-type
[SP "(" transcoding-params ")"]
; always includes a specific MIME type
converterror-phrase = "(" "ERROR" SP
convert-err-descript SP convert-error-code ")"
convert-error-code = "TEMPFAIL" [SP nz-number]
/ bad-params
/ missing-params
convert-err-descript = string
; Human readable text explaining the conversion error
quoted-from-mime-type = DQUOTE from-concrete-mime-type DQUOTE
bad-params = "BADPARAMETERS"
1*(SP (quoted-from-mime-type / nil)
SP mimetype-and-params)
; nil is only returned when the body part doesn't exist
missing-params = "MISSINGPARAMETERS"
1*(SP quoted-from-mime-type SP
Melnikov & Coates Expires August 15, 2008 [Page 21]
Internet-Draft IMAP CONVERT extension February 2008
mimetype-and-missing-params)
mimetype-and-missing-params = quoted-to-mime-type
"(" transcoding-param-names ")"
; always includes a specific MIME type
concrete-mime-type = type-name "/" subtype-name
; i.e. "type/subtype".
; type-name and subtype-name
; are defined in [MIME-MTSRP].
from-concrete-mime-type = concrete-mime-type
to-mime-type = concrete-mime-type
11. IANA Considerations
IMAP4 capabilities are registered by publishing a standards track or
IESG approved experimental RFC. The registry is currently located at
<http://www.iana.org/assignments/imap4-capabilities>. This document
defines the CONVERT IMAP capability. IANA is requested to add this
extension to the IANA IMAP Capability registry.
IANA is also requested to perform registrations as defined in
subsections of this section.
11.1. Registration of unknown-character-replacement media type
parameter
IANA is requested to add the following registration to the registry
established by RFC 2506.
To: "Media feature tags mailing list"
<media-feature-tags@apps.ietf.org>
Subject: Registration of media feature tag
unknown-character-replacement
Media feature tag name:
unknown-character-replacement
ASN.1 identifier associated with feature tag:
New assignment by IANA
Summary of the media feature indicated by this feature tag:
Allows servers that can perform charset conversion for text/plain
text/html, text/css, text/csv, text/enriched and text/xml MIME
types to replace characters not supported by the target charset
Melnikov & Coates Expires August 15, 2008 [Page 22]
Internet-Draft IMAP CONVERT extension February 2008
with a fixed string, such as "?".
This feature tag is also applicable to other conversions
to text, e.g. conversion of images using OCR.
Values appropriate for use with this feature tag:
The feature tag contains a UTF-8 string used to replace any
characters from the source media type that can't be
represented in the target media type.
The feature tag is intended primarily for use in the following
applications, protocols, services, or negotiation mechanisms:
IMAP CONVERT extension [RFC XXXX]
Examples of typical use:
C: b001 CONVERT 2 BINARY[3 ("text/plain" ("charset"
"us-ascii" "unknown-character-replacement" "?"))]
Related standards or documents:
[RFC XXXX]
[CHARSET-REG]
Considerations particular to use in individual applications,
protocols, services, or negotiation mechanisms:
None
Interoperability considerations: None
Security considerations: None
Additional information:
This media feature only make sense for MIME types that
also support the "charset" media type parameter
[CHARSET-REG].
Name(s) & email address(es) of person(s) to contact for further
information:
Alexey Melnikov <alexey.melnikov@isode.com>
Intended usage:
COMMON
Author/Change controller:
IETF
Requested IANA publication delay:
None
Other information:
Melnikov & Coates Expires August 15, 2008 [Page 23]
Internet-Draft IMAP CONVERT extension February 2008
None
12. Security Considerations
It is to be noted that some conversions may present security threats
(e.g. converting a document to a damaging executable, exploiting a
buffer overflow in a media codec/parser, or a denial of service
attack against a client or server such as requesting an image be
scaled to extremely large dimensions). Clients should be careful
when requesting conversions or processing transformed attachments.
Servers should avoid dangerous conversions if possible. Whenever
possible, servers should perform verification of the converted
attachments before returning them to the client.
When the client requests a server-side conversion of a signed body
part (e.g. a part inside multipart/signed), there is no way for the
client to verify that the converted content is authentic. A client
not trusting the server to perform conversion of a signed body part
can download the signed object, verify the signature and perform the
conversion itself.
A client can create a carefully crafted bad message with the APPEND
command followed by the CONVERT command to attack the server. If the
server's conversion function or library has a security problem, this
could result in privilege escalation or Denial of Service.
On bandwidth limited mobile networks where users pay per data
volumes, spam may become an important issue. It can be mitigated
with appropriate filters and server-side spam prevention tools.
These are of course outside the scope of CONVERT.
Deployments in which the actual transcoding is done outside the IMAP
server in a separate server are recommended to keep the servers in
the same trusted domain (e.g. subnet).
13. Acknowledgments
Stephane H. Maes and Ray Cromwell from Oracle edited several earlier
versions of this document. Their contribution is gratefully
acknowledged.
Authors want to specifically acknowledge the excellent criticism and
comments received from Randall Gellens (Qualcomm), Arnt Gulbrandsen
(Oryx), Zoltan Ordogh (Nokia), Ben Last (Emccsoft), Dan Karp
(Zimbra), Pete Resnick (Qualcomm), Chris Newman (Sun), Ted Hardie
(Qualcomm), Larry Masinter (Adobe), Philip Guenther (Sendmail), Greg
Melnikov & Coates Expires August 15, 2008 [Page 24]
Internet-Draft IMAP CONVERT extension February 2008
Vaudreuil (Alcatel-Lucent) and Dave Cridland (Isode) which improved
the quality of this specification considerably.
Authors would also like to specially thank Dave Cridland for the
MEDIACAPS command proposal and Dan Karp for the CONVERSIONS command
proposal.
Authors also want to thank all who have contributed key insight and
extensively reviewed and discussed the concepts of CONVERT and its
predecessor P-IMAP. In particular, this includes the authors of the
LCONVERT draft: Rafiul Ahad (Oracle Corporation), Eugene Chiu (Oracle
Corporation), Ray Cromwell (Oracle Corporation), Jia-der Day (Oracle
Corporation), Vi Ha (Oracle Corporation), Wook- Hyun Jeong (Samsung
Electronics Co. LTF), Chang Kuang (Oracle Corporation), Rodrigo Lima
(Oracle Corporation), Stephane H. Maes (Oracle Corporation), Gustaf
Rosell (Sony Ericsson), Jean Sini (Symbol Technologies), Sung-Mu Son
(LG Electronics), Fan Xiaohui (CHINA MOBILE COMMUNICATIONS
CORPORATION (CMCC)), Zhao Lijun (CHINA MOBILE COMMUNICATIONS
CORPORATION (CMCC)).
14. References
14.1. Normative References
[ABNF] Crocker, D., Ed. and P. Overell, Ed., "Augmented BNF for
Syntax Specifications: ABNF", RFC 5234, January 2008.
[CHARSET-REG]
Hoffman, P., "Registration of Charset and Languages Media
Features Tags", RFC 2987, November 2000.
[IMAPABNF]
Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
ABNF", RFC 4466, April 2006.
[MEDIAFEAT-REG]
Holtman, K., Mutz, A., and T. Hardie, "Media Feature Tag
Registration Procedure", BCP 31, RFC 2506, March 1999.
[MIME-IMT]
Freed, N. and N. Borenstein, "MIME (Multipurpose Internet
Mail Extensions) Part Two: Media Types", RFC 2046,
November 1996.
[MIME-MTSRP]
Freed, N. and J. Klensin, "Media Type Specifications and
Registration Procedures", BCP 13, RFC 4288, December 2005.
Melnikov & Coates Expires August 15, 2008 [Page 25]
Internet-Draft IMAP CONVERT extension February 2008
[RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions)
Part Three: Message Header Extensions for Non-ASCII Text",
RFC 2047, November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded
Word Extensions:
Character Sets, Languages, and Continuations", RFC 2231,
November 1997.
[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.
[RFC3516] Nerenberg, L., "IMAP4 Binary Content Extension", RFC 3516,
April 2003.
14.2. Informative References
[DISPLAY-FEATURES]
Masinter, L., Wing, D., Mutz, A., and K. Holtman, "Media
Features for Display, Print, and Fax", RFC 2534,
March 1999.
[OMA-ME-RD]
OMA, "Open Mobile Alliance Mobile Email Requirement
Document".
[OMA-STI] OMA, "Open Mobile Alliance, Standard Transcoding Interface
Specification".
Authors' Addresses
Alexey Melnikov (editor)
Isode Ltd
5 Castle Business Village
36 Station Road
Hampton, Middlesex TW12 2BX
UK
Email: Alexey.Melnikov@isode.com
Melnikov & Coates Expires August 15, 2008 [Page 26]
Internet-Draft IMAP CONVERT extension February 2008
Peter Coates (editor)
Sun Microsystems
185 Falcon Drive
Whitehorse, YT Y1A 6T2
Canada
Email: peter.coates@Sun.COM
Melnikov & Coates Expires August 15, 2008 [Page 27]
Internet-Draft IMAP CONVERT extension February 2008
Full Copyright Statement
Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Acknowledgment
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Melnikov & Coates Expires August 15, 2008 [Page 28]
