From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001
From: Thomas Voss <mail@thomasvoss.com>
Date: Wed, 27 Nov 2024 20:54:24 +0100
Subject: doc: Add RFC documents

---
 doc/rfc/rfc5524.txt | 507 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 507 insertions(+)
 create mode 100644 doc/rfc/rfc5524.txt

(limited to 'doc/rfc/rfc5524.txt')

diff --git a/doc/rfc/rfc5524.txt b/doc/rfc/rfc5524.txt
new file mode 100644
index 0000000..3808d1f
--- /dev/null
+++ b/doc/rfc/rfc5524.txt
@@ -0,0 +1,507 @@
+
+
+
+
+
+
+Network Working Group                                        D. Cridland
+Request for Comments: 5524                                 Isode Limited
+Category: Standards Track                                       May 2009
+
+
+            Extended URLFETCH for Binary and Converted Parts
+
+Status of This Memo
+
+   This document specifies an Internet standards track protocol for the
+   Internet community, and requests discussion and suggestions for
+   improvements.  Please refer to the current edition of the "Internet
+   Official Protocol Standards" (STD 1) for the standardization state
+   and status of this protocol.  Distribution of this memo is unlimited.
+
+Copyright Notice
+
+   Copyright (c) 2009 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents in effect on the date of
+   publication of this document (http://trustee.ietf.org/license-info).
+   Please review these documents carefully, as they describe your rights
+   and restrictions with respect to this document.
+
+Abstract
+
+   The URLFETCH command defined as part of URLAUTH provides a mechanism
+   for third parties to gain access to data held within messages in a
+   user's private store; however, this data is sent verbatim, which is
+   not suitable for a number of applications.  This memo specifies a
+   method for obtaining data in forms suitable for non-mail
+   applications.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Cridland                    Standards Track                     [Page 1]
+
+RFC 5524                    URLFETCH Binary                     May 2009
+
+
+Table of Contents
+
+   1. Introduction ....................................................2
+   2. Conventions Used in This Document ...............................2
+   3. Extended URLFETCH ...............................................2
+      3.1. Command Parameters .........................................3
+      3.2. Response Metadata ..........................................3
+   4. Example Exchanges ...............................................4
+   5. Formal Syntax ...................................................6
+   6. IANA Considerations .............................................7
+   7. Security Considerations .........................................7
+   8. Acknowledgements ................................................7
+   9. References ......................................................8
+      9.1. Normative References .......................................8
+      9.2. Informative References .....................................8
+
+1.  Introduction
+
+   Although [URLAUTH] provides a URLFETCH command that can be used to
+   dereference a URL and return the body-part data, it does so by
+   returning the encoded form, without sufficient metadata to decode.
+   This is suitable for use in mail applications such as [BURL], where
+   the encoded form is suitable, but not where access to the actual
+   content is required, such as in [STREAMING].
+
+   This memo specifies a mechanism that returns additional metadata
+   about the part, such as its [MEDIATYPE] type, as well as removes any
+   content transfer encoding that was used on the body part.
+
+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 RFC 2119 [KEYWORDS].
+
+   Protocol examples are line-wrapped for clarity.  Protocol strings are
+   prefixed with C: and S: for client and server respectively, and
+   elided data is represented by [...].  Implementors should note these
+   notations are for editorial clarity only.
+
+3.  Extended URLFETCH
+
+   This extension is available in any IMAP server implementation that
+   includes URLAUTH=BINARY within its capability string.
+
+   Such servers accept additional, per-URL parameters to the URLFETCH
+   command and will provide, upon request, specific data for each URL
+   dereferenced.
+
+
+
+Cridland                    Standards Track                     [Page 2]
+
+RFC 5524                    URLFETCH Binary                     May 2009
+
+
+3.1.  Command Parameters
+
+   The URLFETCH command is extended by the provision of optional
+   parameters.  The extended URLFETCH command is distinct by enclosing
+   each URL and associated parameters in a parenthesized list.  Cases
+   where there is an absence of any parameters or where the URL is sent
+   unenclosed cause the command to behave precisely as specified in
+   [URLAUTH].
+
+   Similarly, if the URL is invalid, the command will behave precisely
+   as specified in [URLAUTH] and return a simple NIL.
+
+   Available parameters are:
+
+   BODYPARTSTRUCTURE
+      Provide a BODYPARTSTRUCTURE.
+
+      BODYPARTSTRUCTURE is defined in [CONVERT] and provides metadata
+      useful for processing applications, such as the type of data.
+
+   BINARY
+      Provide the data without any Content-Transfer-Encoding.
+
+      In particular, this means that the data MAY contain NUL octets and
+      not be formed from textual lines.  Data containing NUL octets MUST
+      be transferred using the literal8 syntax defined in [BINARY].
+
+   BODY
+      Provide the data as-is.
+
+      This will provide the same data as the unextended [URLAUTH] as a
+      metadata item.
+
+   Metadata items MUST NOT appear more than once per URL requested, and
+   clients MUST NOT request both BINARY and BODY.
+
+3.2.  Response Metadata
+
+   In order to carry any requested metadata and provide additional
+   information to the consumer, the URLFETCH response is similarly
+   extended.
+
+   Following the URL itself, servers will include a series of
+   parenthesized metadata elements.  Defined metadata elements are as
+   follows:
+
+
+
+
+
+
+Cridland                    Standards Track                     [Page 3]
+
+RFC 5524                    URLFETCH Binary                     May 2009
+
+
+   BODYPARTSTRUCTURE
+      The BODYPARTSTRUCTURE provides information about the data
+      contained in the response, as it has been returned.  It will
+      reflect any conversions or decoding that have taken place.  In
+      particular, this will show an identity encoding if BINARY is also
+      requested.
+
+   BINARY
+      The BINARY item provides the content, without any content transfer
+      encoding applied.  If this is not possible (for example, the
+      content transfer encoding is unknown to the server), then this MAY
+      contain NIL.  Servers MUST understand all identity content
+      transfer encodings defined in [MIME], as well as the
+      transformation encodings "Base64" [BASE64] and "Quoted-Printable"
+      [MIME].
+
+   BODY
+      The BODY item provides the content as found in the message, with
+      any content transfer encoding still applied.  Requesting only the
+      BODY will provide equivalent functionality to the unextended
+      [URLAUTH], however, using the extended syntax described herein.
+
+   Note that unlike [CONVERT], BODYPARTSTRUCTURE is not appended with
+   the part specifier, as this is implicit in the URL.
+
+4.  Example Exchanges
+
+   A client requests the data with no content transfer encoding.
+
+      C: A001 URLFETCH  ("imap://joe@example.com/INBOX/;uid=20/;
+         section=1.2;urlauth=anonymous:internal:
+         91354a473744909de610943775f92038" BINARY)
+      S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;
+         section=1.2;urlauth=anonymous:internal:
+         91354a473744909de610943775f92038" (BINARY {28}
+      S: Si vis pacem, para bellum.
+      S:
+      S: )
+      S: A001 OK URLFETCH completed
+
+   Note that the data here does not contain a NUL octet; therefore, a
+   literal -- not literal8 -- syntax has been used.
+
+   A client again requests data with no content transfer encoding, but
+   this time requests the body structure.
+
+
+
+
+
+
+Cridland                    Standards Track                     [Page 4]
+
+RFC 5524                    URLFETCH Binary                     May 2009
+
+
+      C: A001 URLFETCH  ("imap://joe@example.com/INBOX/;uid=20/;
+         section=1.3;urlauth=anonymous:internal:
+         ae354a473744909de610943775f92038" BINARY BODYPARTSTRUCTURE)
+      S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;
+         section=1.3;urlauth=anonymous:internal:
+         ae354a473744909de610943775f92038" (BODYPARTSTRUCTURE
+         ("IMAGE" "PNG" () NIL NIL "BINARY" 123)) (BINARY ~{123}
+      S: [123 octets of data, some of which is NUL])
+      S: A001 OK URLFETCH completed
+
+   A client requests only the body structure.
+
+      C: A001 URLFETCH  ("imap://joe@example.com/INBOX/;uid=20/;
+         section=1.3;urlauth=anonymous:internal:
+         ae354a473744909de610943775f92038" BODYPARTSTRUCTURE)
+      S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;
+         section=1.3;urlauth=anonymous:internal:
+         ae354a473744909de610943775f92038" (BODYPARTSTRUCTURE
+         ("IMAGE" "PNG" () NIL NIL "BASE64" 164))
+      S: A001 OK URLFETCH completed
+
+   A client requests the body structure and the original content.
+
+      C: A001 URLFETCH  ("imap://joe@example.com/INBOX/;uid=20/;
+         section=1.3;urlauth=anonymous:internal:
+         ae354a473744909de610943775f92038" BODYPARTSTRUCTURE BODY)
+      S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;
+         section=1.3;urlauth=anonymous:internal:
+         ae354a473744909de610943775f92038" (BODYPARTSTRUCTURE
+         ("IMAGE" "PNG" () NIL NIL "BASE64" 164)) (BODY {164}
+      S: [164 octets of base64 encoded data])
+      S: A001 OK URLFETCH completed
+
+   Some parts cannot be decoded, so the server will provide the
+   BODYPARTSTRUCTURE of the part as is and provide NIL for the binary
+   content:
+
+      C: A001 URLFETCH ("imap://joe@example.com/INBOX/;uid=20/;
+         section=1.4;urlauth=anonymous:internal:
+         87ecbd02095b815e699503fc20d869c8" BODYPARTSTRUCTURE BINARY)
+      S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;
+         section=1.4;urlauth=anonymous:internal:
+         87ecbd02095b815e699503fc20d869c8" (BODYPARTSTRUCTURE
+         ("IMAGE" "PNG" () NIL NIL "X-BLURDYBLOOP" 123))
+         (BINARY NIL)
+      S: A001 OK URLFETCH completed
+
+
+
+
+
+Cridland                    Standards Track                     [Page 5]
+
+RFC 5524                    URLFETCH Binary                     May 2009
+
+
+   If a part simply doesn't exist, however, or the URI is invalid for
+   some other reason, then NIL is returned instead of metadata:
+
+      C: A001 URLFETCH ("imap://joe@example.com/INBOX/;uid=20/;
+         section=200;urlauth=anonymous:internal:
+         88066d37e2e5410e1a6486350a8836ee" BODYPARTSTRUCTURE BODY)
+      S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;
+         section=200;urlauth=anonymous:internal:
+         88066d37e2e5410e1a6486350a8836ee" NIL
+      S: A001 OK URLFETCH completed
+
+5.  Formal Syntax
+
+   This formal syntax uses ABNF as specified in [ABNF], and includes
+   productions defined in [URLAUTH], [BINARY], and [IMAP].
+
+   capability       =/ "URLAUTH=BINARY"
+
+      ; Command parameters; see Section 3.1
+
+   urlfetch         =  "URLFETCH" 1*(SP url-fetch-arg)
+
+   url-fetch-arg    =  url-fetch-simple / url-fetch-ext
+
+   url-fetch-simple =  url-full
+      ; Unextended URLFETCH.
+
+   url-fetch-ext    =  "(" url-full *(SP url-fetch-param) ")"
+      ; If no url-fetch-param present, as unextended.
+
+   url-fetch-param  =  "BODY" / "BINARY" / "BODYPARTSTRUCTURE" / atom
+
+      ; Response; see Section 3.2
+
+   urlfetch-data    =  "*" SP "URLFETCH"
+                       1*(SP (urldata-simple / urldata-ext /
+                              urldata-error))
+
+   urldata-error    =  SP url-full SP nil
+
+   urldata-simple   =  SP url-full SP nstring
+      ; If client issues url-fetch-simple, server MUST respond with
+      ; urldata-simple.
+
+   urldata-ext      =  SP url-full url-metadata
+
+   url-metadata     =  1*(SP "(" url-metadata-el ")")
+
+
+
+
+Cridland                    Standards Track                     [Page 6]
+
+RFC 5524                    URLFETCH Binary                     May 2009
+
+
+   url-metadata-el  =  url-meta-bodystruct / url-meta-body /
+                       url-meta-binary
+
+   url-meta-bodystruct   =  "BODYPARTSTRUCTURE" SP body
+
+   url-meta-binary       =  "BINARY" SP ( nstring / literal8 )
+      ; If content contains a NUL octet, literal8 MUST be used.
+      ; Otherwise, content SHOULD use nstring.
+      ; On decoding error, NIL should be used.
+
+   url-meta-body         =  "BODY" SP nstring
+
+6.  IANA Considerations
+
+   IMAP4 capabilities are registered by publishing a Standards Track or
+   IESG-approved Experimental RFC.
+
+   This document defines the URLFETCH=BINARY IMAP capability.  IANA has
+   added it to the registry accordingly.
+
+7.  Security Considerations
+
+   Implementors are directed to the security considerations within
+   [IMAP], [URLAUTH], and [BINARY].
+
+   The ability of the holder of a URL to be able to fetch metadata about
+   the content pointed to by the URL as well as the content itself
+   allows a potential attacker to discover more about the content than
+   was previously possible, including its original filename and user-
+   supplied description.
+
+   The additional value of this information to an attacker is marginal,
+   and applies only to those URLs for which the attacker does not have
+   direct access, such as those produced by [URLAUTH].  Implementors are
+   therefore directed to the security considerations present in
+   [URLAUTH].
+
+8.  Acknowledgements
+
+   Comments were received on this idea and/or document from Neil Cook,
+   Philip Guenther, Alexey Melnikov, Ken Murchison, and others.  Whether
+   in agreement or dissent, the comments have refined and otherwise
+   influenced this document.
+
+
+
+
+
+
+
+
+Cridland                    Standards Track                     [Page 7]
+
+RFC 5524                    URLFETCH Binary                     May 2009
+
+
+9.  References
+
+9.1.  Normative References
+
+   [ABNF]       Crocker, D. and P. Overell, "Augmented BNF for Syntax
+                Specifications: ABNF", STD 68, RFC 5234, January 2008.
+
+   [BASE64]     Josefsson, S., "The Base16, Base32, and Base64 Data
+                Encodings", RFC 4648, October 2006.
+
+   [BINARY]     Nerenberg, L., "IMAP4 Binary Content Extension",
+                RFC 3516, April 2003.
+
+   [CONVERT]    Melnikov, A. and P. Coates, "Internet Message Access
+                Protocol - CONVERT Extension", RFC 5259, July 2008.
+
+   [IMAP]       Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
+                4rev1", RFC 3501, March 2003.
+
+   [KEYWORDS]   Bradner, S., "Key words for use in RFCs to Indicate
+                Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+   [MIME]       Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+                Extensions (MIME) Part One: Format of Internet Message
+                Bodies", RFC 2045, November 1996.
+
+   [URLAUTH]    Crispin, M., "Internet Message Access Protocol (IMAP) -
+                URLAUTH Extension", RFC 4467, May 2006.
+
+9.2.  Informative References
+
+   [BURL]       Newman, C., "Message Submission BURL Extension",
+                RFC 4468, May 2006.
+
+   [MEDIATYPE]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+                Extensions (MIME) Part Two: Media Types", RFC 2046,
+                November 1996.
+
+   [STREAMING]  Cook, N., "Streaming Internet Messaging Attachments",
+                Work in Progress, March 2009.
+
+
+
+
+
+
+
+
+
+
+
+Cridland                    Standards Track                     [Page 8]
+
+RFC 5524                    URLFETCH Binary                     May 2009
+
+
+Author's Address
+
+   Dave Cridland
+   Isode Limited
+   5 Castle Business Village
+   36, Station Road
+   Hampton, Middlesex  TW12 2BX
+   GB
+
+   EMail: dave.cridland@isode.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Cridland                    Standards Track                     [Page 9]
+
-- 
cgit v1.2.3