7Network Working Group D. Cridland
8Request for Comments: 5524 Isode Limited
9Category: Standards Track May 2009
12 Extended URLFETCH for Binary and Converted Parts
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.
24 Copyright (c) 2009 IETF Trust and the persons identified as the
25 document authors. All rights reserved.
27 This document is subject to BCP 78 and the IETF Trust's Legal
28 Provisions Relating to IETF Documents in effect on the date of
29 publication of this document (http://trustee.ietf.org/license-info).
30 Please review these documents carefully, as they describe your rights
31 and restrictions with respect to this document.
35 The URLFETCH command defined as part of URLAUTH provides a mechanism
36 for third parties to gain access to data held within messages in a
37 user's private store; however, this data is sent verbatim, which is
38 not suitable for a number of applications. This memo specifies a
39 method for obtaining data in forms suitable for non-mail
58Cridland Standards Track [Page 1]
60RFC 5524 URLFETCH Binary May 2009
65 1. Introduction ....................................................2
66 2. Conventions Used in This Document ...............................2
67 3. Extended URLFETCH ...............................................2
68 3.1. Command Parameters .........................................3
69 3.2. Response Metadata ..........................................3
70 4. Example Exchanges ...............................................4
71 5. Formal Syntax ...................................................6
72 6. IANA Considerations .............................................7
73 7. Security Considerations .........................................7
74 8. Acknowledgements ................................................7
75 9. References ......................................................8
76 9.1. Normative References .......................................8
77 9.2. Informative References .....................................8
81 Although [URLAUTH] provides a URLFETCH command that can be used to
82 dereference a URL and return the body-part data, it does so by
83 returning the encoded form, without sufficient metadata to decode.
84 This is suitable for use in mail applications such as [BURL], where
85 the encoded form is suitable, but not where access to the actual
86 content is required, such as in [STREAMING].
88 This memo specifies a mechanism that returns additional metadata
89 about the part, such as its [MEDIATYPE] type, as well as removes any
90 content transfer encoding that was used on the body part.
922. Conventions Used in This Document
94 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
95 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
96 document are to be interpreted as described in RFC 2119 [KEYWORDS].
98 Protocol examples are line-wrapped for clarity. Protocol strings are
99 prefixed with C: and S: for client and server respectively, and
100 elided data is represented by [...]. Implementors should note these
101 notations are for editorial clarity only.
105 This extension is available in any IMAP server implementation that
106 includes URLAUTH=BINARY within its capability string.
108 Such servers accept additional, per-URL parameters to the URLFETCH
109 command and will provide, upon request, specific data for each URL
114Cridland Standards Track [Page 2]
116RFC 5524 URLFETCH Binary May 2009
1193.1. Command Parameters
121 The URLFETCH command is extended by the provision of optional
122 parameters. The extended URLFETCH command is distinct by enclosing
123 each URL and associated parameters in a parenthesized list. Cases
124 where there is an absence of any parameters or where the URL is sent
125 unenclosed cause the command to behave precisely as specified in
128 Similarly, if the URL is invalid, the command will behave precisely
129 as specified in [URLAUTH] and return a simple NIL.
131 Available parameters are:
134 Provide a BODYPARTSTRUCTURE.
136 BODYPARTSTRUCTURE is defined in [CONVERT] and provides metadata
137 useful for processing applications, such as the type of data.
140 Provide the data without any Content-Transfer-Encoding.
142 In particular, this means that the data MAY contain NUL octets and
143 not be formed from textual lines. Data containing NUL octets MUST
144 be transferred using the literal8 syntax defined in [BINARY].
147 Provide the data as-is.
149 This will provide the same data as the unextended [URLAUTH] as a
152 Metadata items MUST NOT appear more than once per URL requested, and
153 clients MUST NOT request both BINARY and BODY.
1553.2. Response Metadata
157 In order to carry any requested metadata and provide additional
158 information to the consumer, the URLFETCH response is similarly
161 Following the URL itself, servers will include a series of
162 parenthesized metadata elements. Defined metadata elements are as
170Cridland Standards Track [Page 3]
172RFC 5524 URLFETCH Binary May 2009
176 The BODYPARTSTRUCTURE provides information about the data
177 contained in the response, as it has been returned. It will
178 reflect any conversions or decoding that have taken place. In
179 particular, this will show an identity encoding if BINARY is also
183 The BINARY item provides the content, without any content transfer
184 encoding applied. If this is not possible (for example, the
185 content transfer encoding is unknown to the server), then this MAY
186 contain NIL. Servers MUST understand all identity content
187 transfer encodings defined in [MIME], as well as the
188 transformation encodings "Base64" [BASE64] and "Quoted-Printable"
192 The BODY item provides the content as found in the message, with
193 any content transfer encoding still applied. Requesting only the
194 BODY will provide equivalent functionality to the unextended
195 [URLAUTH], however, using the extended syntax described herein.
197 Note that unlike [CONVERT], BODYPARTSTRUCTURE is not appended with
198 the part specifier, as this is implicit in the URL.
202 A client requests the data with no content transfer encoding.
204 C: A001 URLFETCH ("imap://joe@example.com/INBOX/;uid=20/;
205 section=1.2;urlauth=anonymous:internal:
206 91354a473744909de610943775f92038" BINARY)
207 S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;
208 section=1.2;urlauth=anonymous:internal:
209 91354a473744909de610943775f92038" (BINARY {28}
210 S: Si vis pacem, para bellum.
213 S: A001 OK URLFETCH completed
215 Note that the data here does not contain a NUL octet; therefore, a
216 literal -- not literal8 -- syntax has been used.
218 A client again requests data with no content transfer encoding, but
219 this time requests the body structure.
226Cridland Standards Track [Page 4]
228RFC 5524 URLFETCH Binary May 2009
231 C: A001 URLFETCH ("imap://joe@example.com/INBOX/;uid=20/;
232 section=1.3;urlauth=anonymous:internal:
233 ae354a473744909de610943775f92038" BINARY BODYPARTSTRUCTURE)
234 S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;
235 section=1.3;urlauth=anonymous:internal:
236 ae354a473744909de610943775f92038" (BODYPARTSTRUCTURE
237 ("IMAGE" "PNG" () NIL NIL "BINARY" 123)) (BINARY ~{123}
238 S: [123 octets of data, some of which is NUL])
239 S: A001 OK URLFETCH completed
241 A client requests only the body structure.
243 C: A001 URLFETCH ("imap://joe@example.com/INBOX/;uid=20/;
244 section=1.3;urlauth=anonymous:internal:
245 ae354a473744909de610943775f92038" BODYPARTSTRUCTURE)
246 S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;
247 section=1.3;urlauth=anonymous:internal:
248 ae354a473744909de610943775f92038" (BODYPARTSTRUCTURE
249 ("IMAGE" "PNG" () NIL NIL "BASE64" 164))
250 S: A001 OK URLFETCH completed
252 A client requests the body structure and the original content.
254 C: A001 URLFETCH ("imap://joe@example.com/INBOX/;uid=20/;
255 section=1.3;urlauth=anonymous:internal:
256 ae354a473744909de610943775f92038" BODYPARTSTRUCTURE BODY)
257 S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;
258 section=1.3;urlauth=anonymous:internal:
259 ae354a473744909de610943775f92038" (BODYPARTSTRUCTURE
260 ("IMAGE" "PNG" () NIL NIL "BASE64" 164)) (BODY {164}
261 S: [164 octets of base64 encoded data])
262 S: A001 OK URLFETCH completed
264 Some parts cannot be decoded, so the server will provide the
265 BODYPARTSTRUCTURE of the part as is and provide NIL for the binary
268 C: A001 URLFETCH ("imap://joe@example.com/INBOX/;uid=20/;
269 section=1.4;urlauth=anonymous:internal:
270 87ecbd02095b815e699503fc20d869c8" BODYPARTSTRUCTURE BINARY)
271 S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;
272 section=1.4;urlauth=anonymous:internal:
273 87ecbd02095b815e699503fc20d869c8" (BODYPARTSTRUCTURE
274 ("IMAGE" "PNG" () NIL NIL "X-BLURDYBLOOP" 123))
276 S: A001 OK URLFETCH completed
282Cridland Standards Track [Page 5]
284RFC 5524 URLFETCH Binary May 2009
287 If a part simply doesn't exist, however, or the URI is invalid for
288 some other reason, then NIL is returned instead of metadata:
290 C: A001 URLFETCH ("imap://joe@example.com/INBOX/;uid=20/;
291 section=200;urlauth=anonymous:internal:
292 88066d37e2e5410e1a6486350a8836ee" BODYPARTSTRUCTURE BODY)
293 S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;
294 section=200;urlauth=anonymous:internal:
295 88066d37e2e5410e1a6486350a8836ee" NIL
296 S: A001 OK URLFETCH completed
300 This formal syntax uses ABNF as specified in [ABNF], and includes
301 productions defined in [URLAUTH], [BINARY], and [IMAP].
303 capability =/ "URLAUTH=BINARY"
305 ; Command parameters; see Section 3.1
307 urlfetch = "URLFETCH" 1*(SP url-fetch-arg)
309 url-fetch-arg = url-fetch-simple / url-fetch-ext
311 url-fetch-simple = url-full
312 ; Unextended URLFETCH.
314 url-fetch-ext = "(" url-full *(SP url-fetch-param) ")"
315 ; If no url-fetch-param present, as unextended.
317 url-fetch-param = "BODY" / "BINARY" / "BODYPARTSTRUCTURE" / atom
319 ; Response; see Section 3.2
321 urlfetch-data = "*" SP "URLFETCH"
322 1*(SP (urldata-simple / urldata-ext /
325 urldata-error = SP url-full SP nil
327 urldata-simple = SP url-full SP nstring
328 ; If client issues url-fetch-simple, server MUST respond with
331 urldata-ext = SP url-full url-metadata
333 url-metadata = 1*(SP "(" url-metadata-el ")")
338Cridland Standards Track [Page 6]
340RFC 5524 URLFETCH Binary May 2009
343 url-metadata-el = url-meta-bodystruct / url-meta-body /
346 url-meta-bodystruct = "BODYPARTSTRUCTURE" SP body
348 url-meta-binary = "BINARY" SP ( nstring / literal8 )
349 ; If content contains a NUL octet, literal8 MUST be used.
350 ; Otherwise, content SHOULD use nstring.
351 ; On decoding error, NIL should be used.
353 url-meta-body = "BODY" SP nstring
3556. IANA Considerations
357 IMAP4 capabilities are registered by publishing a Standards Track or
358 IESG-approved Experimental RFC.
360 This document defines the URLFETCH=BINARY IMAP capability. IANA has
361 added it to the registry accordingly.
3637. Security Considerations
365 Implementors are directed to the security considerations within
366 [IMAP], [URLAUTH], and [BINARY].
368 The ability of the holder of a URL to be able to fetch metadata about
369 the content pointed to by the URL as well as the content itself
370 allows a potential attacker to discover more about the content than
371 was previously possible, including its original filename and user-
372 supplied description.
374 The additional value of this information to an attacker is marginal,
375 and applies only to those URLs for which the attacker does not have
376 direct access, such as those produced by [URLAUTH]. Implementors are
377 therefore directed to the security considerations present in
382 Comments were received on this idea and/or document from Neil Cook,
383 Philip Guenther, Alexey Melnikov, Ken Murchison, and others. Whether
384 in agreement or dissent, the comments have refined and otherwise
385 influenced this document.
394Cridland Standards Track [Page 7]
396RFC 5524 URLFETCH Binary May 2009
4019.1. Normative References
403 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
404 Specifications: ABNF", STD 68, RFC 5234, January 2008.
406 [BASE64] Josefsson, S., "The Base16, Base32, and Base64 Data
407 Encodings", RFC 4648, October 2006.
409 [BINARY] Nerenberg, L., "IMAP4 Binary Content Extension",
410 RFC 3516, April 2003.
412 [CONVERT] Melnikov, A. and P. Coates, "Internet Message Access
413 Protocol - CONVERT Extension", RFC 5259, July 2008.
415 [IMAP] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
416 4rev1", RFC 3501, March 2003.
418 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
419 Requirement Levels", BCP 14, RFC 2119, March 1997.
421 [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
422 Extensions (MIME) Part One: Format of Internet Message
423 Bodies", RFC 2045, November 1996.
425 [URLAUTH] Crispin, M., "Internet Message Access Protocol (IMAP) -
426 URLAUTH Extension", RFC 4467, May 2006.
4289.2. Informative References
430 [BURL] Newman, C., "Message Submission BURL Extension",
433 [MEDIATYPE] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
434 Extensions (MIME) Part Two: Media Types", RFC 2046,
437 [STREAMING] Cook, N., "Streaming Internet Messaging Attachments",
438 Work in Progress, March 2009.
450Cridland Standards Track [Page 8]
452RFC 5524 URLFETCH Binary May 2009
459 5 Castle Business Village
461 Hampton, Middlesex TW12 2BX
464 EMail: dave.cridland@isode.com
506Cridland Standards Track [Page 9]