Network Working Group L. Nerenberg Internet Draft: IMAP4 Binary Content Extension ACI/MessagingDirect Document: draft-nerenberg-imap-binary-02.txt February 2001 IMAP4 Binary Content Extension Status of this memo This document is an Internet Draft and is in full conformance with all provisions of Section 10 of RFC 2026. 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.rq 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. A revised version of this draft document will be submitted to the RFC editor as a Proposed Standard for the Internet Community. Discussion and suggestions for improvement are requested. Distribution of this draft is unlimited. 0. Administrivia Changes from version -01 Defined the use of syntax to APPEND binary data. Added BINARYSTRUCTURE. Removed the restriction for terminal body sections only. Added missing ']' in section 4.2 definitions of BINARY and BINARY.PEEK. Clarified when to return [UNKNOWN-TRANSFER-ENCODING] reponse. Nerenberg draft-nerenberg-imap-binary-02.txt [Page 1] Internet Draft IMAP4 Binary Content Extension February 2001 Changes from version -00 Renamed CHARALL to BINCHAR. Changed syntax to "FETCH x BINARY ..." Defined FETCH BINARY response. Modified syntax to distinguish it from . Added examples section. 1. Abstract This memo defines the BINARY extension to the Internet Message Access Protocol [IMAP4rev1]. It provides a mechanism for IMAP4 clients and servers to exchange data encoded with the MIME BINARY content-transfer-encoding. 2. Conventions Used in this Document The key words "MUST," "MUST NOT," "SHOULD," "SHOULD NOT," and "MAY" in this document are to be interpreted as described in [KEYWORD]. In examples, "C:" and "S:" preface lines sent by the client and the server respectively. 3. Overview The MIME extensions to Internet messaging allow for the transmis- sion of non-textual (binary) message content [MIME-IMB]. Since the traditional transports for messaging are not always capable of passing binary data transparently, MIME provides encoding schemes that allow binary content to be transmitted over transports that are not otherwise able to do so. The overhead of MIME encoding this content can be considerable in some contexts (e.g. clients connected over slow radio links). The BINARY extension extends the IMAP4 protocol to allow clients and servers to exchange data in a binary (unencoded) format. 4. Framework for the IMAP4 Binary Extension This memo defines the following extensions to [IMAP4rev1]. 4.1. CAPABILITY Identification IMAP4 servers that support this extension MUST include "BINARY" in the response list to the CAPABILITY command. Nerenberg draft-nerenberg-imap-binary-02.txt [Page 2] Internet Draft IMAP4 Binary Content Extension February 2001 4.2. FETCH Command Extensions This extension defines three new FETCH command data items. BINARY[]<> The binary content of a particular body section. This data item acts as the [IMAP4rev1] BODY data item does, but with the following modifications: The server converts the MIME content-transfer-encoding of the body section to BINARY before transmitting it to the client. This content conversion MUST NOT cause a loss of information. If the server cannot convert the content-transfer-encoding to BINARY it MUST reject the FETCH command with a NO response that includes the "UNKNOWN-TRANSFER-ENCODING" extended response code. When performing a partial FETCH, the offset argument refers to the offset into the CONVERTED body section. BINARY.PEEK[]<> An alternate form of BINARY[
] that does not implic- itly set the \Seen flag. BINARYSTRUCTURE The MIME body structure of the message after converting all body sections to the BINARY content-transfer-encoding. The server computes this by parsing the MIME structure of the mes- sage after performing any required content-transfer-encoding modifications. 4.3. FETCH Response Extensions This extension defines two new FETCH response data items. BINARY[
]<> A expressing the body content of the specified body section after converting the content-transfer-encoding to BINARY. If the origin octet is specified, this string is a substring of the entire body contents, starting at that origin octet. This means that BODY[]<0> MAY be truncated, but BODY[] is NEVER truncated. The offset refers to the body contents after conversion to the BINARY content-transfer-encoding. BINARYSTRUCTURE A parenthesized list describing the MIME body structure of the message after converting all the sections to the BINARY con- tent-transfer-encoding. The contents and format of the list are identical to those of the [IMAP4rev1] BODYSTRUCTURE response, but describe the converted body. Calculating the sizes of the converted content may impose Nerenberg draft-nerenberg-imap-binary-02.txt [Page 3] Internet Draft IMAP4 Binary Content Extension February 2001 considerable overhead on some implementations. A server MAY choose to defer this calculation until the client fetches the item. In this case, all size-related fields where the size of the converted content is unknown MUST be set to NIL. If the server reports a non-NIL value for the message size it MUST match the size of the in a corresponding FETCH BINARY response. For a complex message the server might defer the size calculations for only a subset of the sections. In this case the server SHOULD report the sizes for those sec- tions where they can be easily determined. For example, given a message with a 7BIT-encoded section and a BASE64-encoded section, the server should return the size for the 7BIT- encoded section, since the 7BIT- and BINARY-encoded sizes will be the same. If the server is unable to convert the content-transfer-encod- ing of a section to BINARY, it MUST report the corresponding content encoding and message size fields as NIL, and SHOULD report any other size-related fields as NIL. A section report- ing NIL for content encoding and message size cannot be retrieved using FETCH BINARY, and servers MUST reject such requests with a NO response that includes the "UNKNOWN-TRANS- FER-ENCODING" extended response code. Reporting a message encoding of NIL with a non-NIL message size is a protocol error; servers MUST NOT return this combi- nation of values. 4.4. APPEND Command Extensions The APPEND command is extended to allow the client to append binary data by specifying the octet count using syntax. The server SHOULD NOT perform any content-transfer-encoding conversion of the data. If the specified mailbox does not support the storage of binary content the server MUST reject the APPEND command with a NO response that includes the "UNKNOWN-TRANSFER-ENCODING" extended response code. 5. Examples The examples in this section are illustrative only; they DO NOT form part of this specification. Most of these examples uses a message containing two sections: a text/plain and an application/octet-stream. MIME Content MIME Encoded Unencoded Part# Type Encoding Size Size ---------------------------------------------------------------- 1 text/plain 7bit 105 105 2 application/octet-stream base64 3324344 2429327 Nerenberg draft-nerenberg-imap-binary-02.txt [Page 4] Internet Draft IMAP4 Binary Content Extension February 2001 First, the client requests the BODYSTRUCTURE: C: 42 fetch 6 bodystructure S: * 6 FETCH (BODYSTRUCTURE (("TEXT" "PLAIN" ("CHARSET" "us-ascii") "<1070.981005923.1@localhost>" NIL "7BIT" 105 2 NIL NIL NIL) ("APPLICATION" "OCTET-STREAM" NIL "<1070.981005923.2@localhost>" "The latest BSD kernel" "BASE64" 3324344 NIL NIL NIL) "MIXED" ("BOUNDARY" "----- =_aaaaaaaaaa0") NIL NIL)) S: 42 OK FETCH completed Next the client asks for the BINARYSTRUCTURE: C: 43 fetch 6 binarystructure S: * 6 FETCH (BINARYSTRUCTURE (("TEXT" "PLAIN" ("CHARSET" "us-ascii") "<1070.981005923.1@localhost>" NIL "BINARY" 105 2 NIL NIL NIL) ("APPLICATION" "OCTET-STREAM" NIL "<1070.981005923.2@localhost>" "The latest BSD kernel" "BINARY" 2429327 NIL NIL NIL) "MIXED" ("BOUNDARY" "----- =_aaaaaaaaaa0") NIL NIL)) S: 43 OK FETCH completed Notice that the content transfer encoding for both sections has changed to BINARY. The size for the second section has changed to reflect the conversion of the BASE64 encoding for that section; the size of the first section (both message size and line count) has not changed, since the transformation from 7BIT to BINARY did not result in any change to the data. For sections with transparent content transfer encodings (7BIT, 8BIT, BINARY), FETCH BODY and FETCH BINARY return identical con- tent: C: 3 fetch 1 body[1] S: * 1 FETCH (BODY[1] {80} S: This is a test message to use in the examples section of the S: IMAP BINARY RFC. S: ) S: 3 OK Completed C: 4 fetch 1 binary[1] S: * 1 FETCH (BINARY[1] ~{80} S: This is a test message to use in the examples section of the S: IMAP BINARY RFC. S: ) S: 4 OK Completed Nerenberg draft-nerenberg-imap-binary-02.txt [Page 5] Internet Draft IMAP4 Binary Content Extension February 2001 Here is a misbehaving client trying to retrieve a body the server cannot decode: C: 1 fetch 13 bodystructure S: * 13 FETCH (BODYSTRUCTURE ("TEXT" "PLAIN" ("CHARSET" "iso-8859-1") NIL NIL "FROBOZZ" 1716 49 NIL NIL NIL)) S: 1 OK Completed C: 2 fetch 13 binarystructure S: * 13 FETCH (BINARYSTRUCTURE ("TEXT" "PLAIN" ("CHARSET" "iso-8859-1") NIL NIL NIL NIL NIL NIL NIL NIL)) S: 2 OK Completed C: 3 fetch 13 binary[1] S: 2 BAD [UNKNOWN-TRANSFER-ENCODING] Unknown content encoding (FROBOZZ) for message 13 section 1 6. Interoperability Considerations Messaging clients and servers have been notoriously lax in their adherance to the Internet CRLF convention for terminating lines of textual data in Internet protocols. When sending data using the BINARY extension, servers MUST ensure that textual line-oriented body sections are always transmitted using the IMAP4 CRLF line ter- mination syntax, regardless of the underlying storage representa- tion of the data on the server. This extension provides an optimization that is useful in certain specific situations. It does not absolve clients from providing basic functionality (content transfer decoding) that should be available in all messaging clients. Clients supporting this exten- sion SHOULD be prepared to provide their own content transfer decoding of data. 7. Formal Protocol Syntax The following syntax specification uses the augmented Backus-Naur Form (BNF) notation as used in [IMAP4rev1]. Except as noted otherwise, all alphabetic characters are case- insensitive. The use of upper or lower case characters to define token strings is for editorial clarity only. Implementations MUST accept these strings in a case-insensitive fashion. This syntax extends the grammar specified in [IMAP4rev1]. append =/ "APPEND" SPACE mailbox [SPACE flag_list] [SPACE date_time] SPACE literal8 BINCHAR ::= <0x00 - 0xff> fetch_att =/ "BINARY" [".PEEK"] section_binary ["<" number "." nz_number ">"] / "BINARYSTRUCTURE" Nerenberg draft-nerenberg-imap-binary-02.txt [Page 6] Internet Draft IMAP4 Binary Content Extension February 2001 literal8 ::= "~{" number "}" CRLF *BINCHAR ;; represents the number of BINCHAR octets ;; in the response string. resp_code_text =/ "UNKNOWN-TRANSFER-ENCODING" section_binary ::= "[" [ (nz_number *["." nz_number] ] "]" 8. References [IMAP4rev1] Crispin, M., "Internet Message Access Protocol Version 4rev1," RFC2060, University of Washington, December 1996 [KEYWORD] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels," BCP 9, RFC2119, March 1997 [MIME-IMB] Freed, N., N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies," RFC2045, November 1996. 9. Security Considerations Sending binary data to servers and clients that are expecting well- formed non-binary input is a method commonly used to attempt to bypass security. The IMAP4 BINARY extension is only initiated at a co-operating client's request, therefore the transmission of binary content as defined in this memo should not affect legacy clients that may be unable to properly cope with such binary content. A new protocol syntax has been introduced to further distinguish between and data. 10. Authors' Address Lyndon Nerenberg ACI/MessagingDirect Suite 900 10117 - Jasper Avenue Edmonton, Alberta Canada T5J 1W8 Email: lyndon@messagingdirect.com Nerenberg draft-nerenberg-imap-binary-02.txt [Page 7]