1 ../imapserver/server.go:139
2
3
4
5
6
7Network Working Group L. Nerenberg
8Request for Comments: 3516 Orthanc Systems
9Category: Standards Track April 2003
10
11
12 IMAP4 Binary Content Extension
13
14Status of this Memo
15
16 This document specifies an Internet standards track protocol for the
17 Internet community, and requests discussion and suggestions for
18 improvements. Please refer to the current edition of the "Internet
19 Official Protocol Standards" (STD 1) for the standardization state
20 and status of this protocol. Distribution of this memo is unlimited.
21
22Copyright Notice
23
24 Copyright (C) The Internet Society (2003). All Rights Reserved.
25
26Abstract
27
28 This memo defines the Binary extension to the Internet Message Access
29 Protocol (IMAP4). It provides a mechanism for IMAP4 clients and
30 servers to exchange message body data without using a MIME content-
31 transfer-encoding.
32
331. Conventions Used in this Document
34
35 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
36 in this document are to be interpreted as described in [KEYWORD].
37
38 The abbreviation "CTE" means content-transfer-encoding.
39
402. Introduction
41
42 The MIME extensions to Internet messaging allow for the transmission
43 of non-textual (binary) message content [MIME-IMB]. Since the
44 traditional transports for messaging are not always capable of
45 passing binary data transparently, MIME provides encoding schemes
46 that allow binary content to be transmitted over transports that are
47 not otherwise able to do so.
48
49 The overhead of MIME-encoding this content can be considerable in
50 some contexts (e.g., slow radio links, streaming multimedia).
51 Reducing the overhead associated with CTE schemes such as base64
52
53
54
55
56
57
58Nerenberg Standards Track [Page 1]
59
60RFC 3516 IMAP4 Binary Content Extension April 2003
61
62
63 can give a noticeable reduction in resource consumption. The Binary
64 extension lets the server perform CTE decoding prior to transmitting
65 message data to the client.
66
673. Content-Transfer-Encoding Considerations
68
69 Every IMAP4 body section has a MIME content-transfer-encoding.
70 (Those without an explicit Content-Transfer-Encoding header are
71 implicitly labeled as "7bit" content.) In the terminology of [MIME-
72 IMB], the CTE specifies both a decoding algorithm and the domain of
73 the decoded data. In this memo, "decoding" refers to the CTE
74 decoding step described in [MIME-IMB].
75
76 Certain CTEs use an identity encoding transformation. For these CTEs
77 there is no decoding required, however the domain of the underlying
78 data may not be expressible in the IMAP4 protocol (e.g., MIME
79 "binary" content containing NUL octets). To accommodate these cases
80 the Binary extension introduces a new type of literal protocol
81 element that is fully eight bit transparent.
82
83 Thus, server processing of the FETCH BINARY command involves two
84 logical steps:
85
86 1) perform any CTE-related decoding
87
88 2) determine the domain of the decoded data
89
90 Step 2 is necessary to determine which protocol element should be
91 used to transmit the decoded data. (See FETCH Response Extensions
92 for further details.)
93
944. Framework for the IMAP4 Binary Extension
95
96 This memo defines the following extensions to [IMAP4rev1].
97
984.1. CAPABILITY Identification
99
100 IMAP4 servers that support this extension MUST include "BINARY" in
101 the response list to the CAPABILITY command.
102
1034.2. FETCH Command Extensions
104
105 This extension defines three new FETCH command data items.
106
107 BINARY<section-binary>[<partial>]
108
109 Requests that the specified section be transmitted after
110 performing CTE-related decoding.
111
112
113
114Nerenberg Standards Track [Page 2]
115
116RFC 3516 IMAP4 Binary Content Extension April 2003
117
118
119 The <partial> argument, if present, requests that a subset of
120 the data be returned. The semantics of a partial FETCH BINARY
121 command are the same as for a partial FETCH BODY command, with
122 the exception that the <partial> arguments refer to the DECODED
123 section data.
124
125 BINARY.PEEK<section-binary>[<partial>]
126
127 An alternate form of FETCH BINARY that does not implicitly set
128 the \Seen flag.
129
130 BINARY.SIZE<section-binary>
131
132 Requests the decoded size of the section (i.e., the size to
133 expect in response to the corresponding FETCH BINARY request).
134
135 Note: client authors are cautioned that this might be an
136 expensive operation for some server implementations.
137 Needlessly issuing this request could result in degraded
138 performance due to servers having to calculate the value every
139 time the request is issued.
140
1414.3. FETCH Response Extensions
142
143 This extension defines two new FETCH response data items.
144
145 BINARY<section-binary>[<<number>>]
146
147 An <nstring> or <literal8> expressing the content of the
148 specified section after removing any CTE-related encoding. If
149 <number> is present it refers to the offset within the DECODED
150 section data.
151
152 If the domain of the decoded data is "8bit" and the data does
153 not contain the NUL octet, the server SHOULD return the data in
154 a <string> instead of a <literal8>; this allows the client to
155 determine if the "8bit" data contains the NUL octet without
156 having to explicitly scan the data stream for for NULs.
157
158 If the server does not know how to decode the section's CTE, it
159 MUST fail the request and issue a "NO" response that contains
160 the "UNKNOWN-CTE" extended response code.
161
162
163
164
165
166
167
168
169
170Nerenberg Standards Track [Page 3]
171
172RFC 3516 IMAP4 Binary Content Extension April 2003
173
174
175 BINARY.SIZE<section-binary>
176
177 The size of the section after removing any CTE-related
178 encoding. The value returned MUST match the size of the
179 <nstring> or <literal8> that will be returned by the
180 corresponding FETCH BINARY request.
181
182 If the server does not know how to decode the section's CTE, it
183 MUST fail the request and issue a "NO" response that contains
184 the "UNKNOWN-CTE" extended response code.
185
1864.4. APPEND Command Extensions
187
188 The APPEND command is extended to allow the client to append data
189 containing NULs by using the <literal8> syntax. The server MAY
190 modify the CTE of the appended data, however any such transformation
191 MUST NOT result in a loss of data.
192
193 If the destination mailbox does not support the storage of binary
194 content, the server MUST fail the request and issue a "NO" response
195 that contains the "UNKNOWN-CTE" extended response code.
196
1975. MIME Encoded Headers
198
199 [MIME-MHE] defines an encoding that allows for non-US-ASCII text in
200 message headers. This encoding is not the same as the content-
201 transfer-encoding applied to message bodies, and the decoding
202 transformations described in this memo do not apply to [MIME-MHE]
203 encoded header text. A server MUST NOT perform any conversion of
204 [MIME-MHE] encoded header text in response to any binary FETCH or
205 APPEND request.
206
2076. Implementation Considerations
208
209 Messaging clients and servers have been notoriously lax in their
210 adherence to the Internet CRLF convention for terminating lines of
211 textual data in Internet protocols. When sending data using the
212 Binary extension, servers MUST ensure that textual line-oriented
213 sections are always transmitted using the IMAP4 CRLF line termination
214 syntax, regardless of the underlying storage representation of the
215 data on the server.
216
217 A server may choose to store message body binary content in a non-
218 encoded format. Regardless of the internal storage representation
219 used, the server MUST issue BODYSTRUCTURE responses that describe the
220 message as though the binary-encoded sections are encoded in a CTE
221
222
223
224
225
226Nerenberg Standards Track [Page 4]
227
228RFC 3516 IMAP4 Binary Content Extension April 2003
229
230
231 acceptable to the IMAP4 base specification. Furthermore, the results
232 of a FETCH BODY MUST return the message body content in the format
233 described by the corresponding FETCH BODYSTRUCTURE response.
234
235 While the server is allowed to modify the CTE of APPENDed <literal8>
236 data, this should only be done when it is absolutely necessary.
237 Gratuitous encoding changes will render useless most cryptographic
238 operations that have been performed on the message.
239
240 This extension provides an optimization that is useful in certain
241 specific situations. It does not absolve clients from providing
242 basic functionality (content transfer decoding) that should be
243 available in all messaging clients. Clients supporting this
244 extension SHOULD be prepared to perform their own CTE decoding
245 operations.
246
2477. Formal Protocol Syntax
248
249 The following syntax specification uses the augmented Backus-Naur
250 Form (ABNF) notation as used in [ABNF], and incorporates by reference
251 the Core Rules defined in that document.
252
253 This syntax augments the grammar specified in [IMAP4rev1].
254
255 append =/ "APPEND" SP mailbox [SP flag-list]
256 [SP date-time] SP literal8
257
258 fetch-att =/ "BINARY" [".PEEK"] section-binary [partial]
259 / "BINARY.SIZE" section-binary
260
261 literal8 = "~{" number "}" CRLF *OCTET
262 ; <number> represents the number of OCTETs
263 ; in the response string.
264
265 msg-att-static =/ "BINARY" section-binary SP (nstring / literal8)
266 / "BINARY.SIZE" section-binary SP number
267
268 partial = "<" number "." nz-number ">"
269
270 resp-text-code =/ "UNKNOWN-CTE"
271
272 section-binary = "[" [section-part] "]"
273
274
275
276
277
278
279
280
281
282Nerenberg Standards Track [Page 5]
283
284RFC 3516 IMAP4 Binary Content Extension April 2003
285
286
2878. Normative References
288
289 [ABNF] Crocker, D., Editor, and P. Overell, "Augmented BNF for
290 Syntax Specifications: ABNF", RFC 2234, November 1997.
291
292 [IMAP4rev1] Crispin, M., "Internet Message Access Protocol Version
293 4rev1", RFC 3501, March 2003.
294
295 [KEYWORD] Bradner, S., "Key words for use in RFCs to Indicate
296 Requirement Levels", BCP 14, RFC 2119, March 1997.
297
298 [MIME-IMB] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
299 Extensions (MIME) Part One: Format of Internet Message
300 Bodies", RFC 2045, November 1996.
301
302 [MIME-MHE] Moore, K., "MIME (Multipurpose Internet Mail Extensions)
303 Part Three: Message Header Extensions for Non-ASCII
304 Text", RFC 2047, November 1996.
305
3069. Security Considerations
307
308 There are no known additional security issues with this extension
309 beyond those described in the base protocol described in [IMAP4rev1].
310
31110. Intellectual Property
312
313 The IETF takes no position regarding the validity or scope of any
314 intellectual property or other rights that might be claimed to
315 pertain to the implementation or use of the technology described in
316 this document or the extent to which any license under such rights
317 might or might not be available; neither does it represent that it
318 has made any effort to identify any such rights. Information on the
319 IETF's procedures with respect to rights in standards-track and
320 standards-related documentation can be found in BCP-11. Copies of
321 claims of rights made available for publication and any assurances of
322 licenses to be made available, or the result of an attempt made to
323 obtain a general license or permission for the use of such
324 proprietary rights by implementors or users of this specification can
325 be obtained from the IETF Secretariat.
326
327 The IETF invites any interested party to bring to its attention any
328 copyrights, patents or patent applications, or other proprietary
329 rights which may cover technology that may be required to practice
330 this standard. Please address the information to the IETF Executive
331 Director.
332
333
334
335
336
337
338Nerenberg Standards Track [Page 6]
339
340RFC 3516 IMAP4 Binary Content Extension April 2003
341
342
34311. Author's Address
344
345 Lyndon Nerenberg
346 Orthanc Systems
347 1606 - 10770 Winterburn Road
348 Edmonton, Alberta
349 Canada T5S 1T6
350
351 EMail: lyndon@orthanc.ab.ca
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394Nerenberg Standards Track [Page 7]
395
396RFC 3516 IMAP4 Binary Content Extension April 2003
397
398
39912. Full Copyright Statement
400
401 Copyright (C) The Internet Society (2003). All Rights Reserved.
402
403 This document and translations of it may be copied and furnished to
404 others, and derivative works that comment on or otherwise explain it
405 or assist in its implementation may be prepared, copied, published
406 and distributed, in whole or in part, without restriction of any
407 kind, provided that the above copyright notice and this paragraph are
408 included on all such copies and derivative works. However, this
409 document itself may not be modified in any way, such as by removing
410 the copyright notice or references to the Internet Society or other
411 Internet organizations, except as needed for the purpose of
412 developing Internet standards in which case the procedures for
413 copyrights defined in the Internet Standards process must be
414 followed, or as required to translate it into languages other than
415 English.
416
417 The limited permissions granted above are perpetual and will not be
418 revoked by the Internet Society or its successors or assigns.
419
420 This document and the information contained herein is provided on an
421 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
422 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
423 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
424 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
425 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
426
427Acknowledgement
428
429 Funding for the RFC Editor function is currently provided by the
430 Internet Society.
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450Nerenberg Standards Track [Page 8]
451
452