Network Working Group L. Nerenberg Internet Draft: IMAP4 Channel Transport Mechanism Orthanc Systems Document: draft-ietf-lemonade-imap-channel-01.txt S. Hole ACI Worldwide B. Leiba IBM Research January 2004 IMAP4 Channel Transport Mechanism 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 docu- ments 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. Copyright 2003,2004 The Internet Society. All Rights Reserved. Please see the Copyright section near the end of this document for more information. Administrivia Discussion concerning this draft should be directed to the mailing list. Changes in -02 Revert text to that from draft-nerenberg-imap-channel-01, which again forms the baseline document for the specification. The usage and implementation guide will be split out into another memo seper- ate from the specification itself. Revert to the simple string "channel" for the capability. The old scheme (channel=foo,bar) required parsable capabilities. A new Nerenberg draft-ietf-lemonade-imap-channel-01.txt [Page 1] Internet Draft IMAP4 Channel Transport Mechanism January 2004 command (CHANNELSCHEMES) is proposed for discovering the supported scheme list. The grammar has been cleaned up and synced with RFC3501. References to schemes in the protocol no longer include the trail- ing ":" in the scheme name (e.g. we now use "ftp" rather than "ftp:"). The grammar is now unambiguous with reference to the use of and (a scheme name cannot contain a ":", and an requires one). Both types are now encoded as . Outstanding Issues The Security Considerations section needs to be expanded. The CHANNELSCHEMES command and response require description. groff with -ms does not know how to shut up hyphenation. The RFC editor deserves raw nroff source of this document. Examples need a seperate section. Abstract This specifications defines a method for IMAP4 clients to retrieve message content via an external (i.e. non-IMAP) protocol mechanism. 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. The examples in this document do NOT form part of the specifica- tion. Where conflicts exist between the text and the formal gram- mar, the grammar is authoritative. 1. Protocol Framework This memo defines the following extensions to [IMAP4rev1]. 1.1. CAPABILITY Identification IMAP4 servers that support this extension MUST advertise the "CHAN- NEL" capability. 1.2. CHANNEL Command The CHANNEL command requests that message data be retrieved through an external scheme. Clients may issue a request specifying a par- tially-qualified URI, in which case the server will determine the Nerenberg draft-ietf-lemonade-imap-channel-01.txt [Page 2] Internet Draft IMAP4 Channel Transport Mechanism January 2004 final connection end-point. What constitutes a partially-qualified URI is implementation defined. The syntax of the CHANNEL command is: tag CHANNEL channel-uri-list channel-set is a list of URIs and schemes specifying how the client desires to retrieve the message data. If contains more than one element the server SHOULD return the message data using the first element in the list it is capable of using. is a list of message-number/body-section pairs describing the content to be retrieved. The message number speci- fies the sequence number of the message to act on. The CHANNEL command is only valid in the selected state. Example: C: 0 CHANNEL (rtsp ftp://marvin@example.net/incoming/) (1 2)(3 1)(3 9.1) asks for section 2 of message 1 and sections 1 and 9.1 of mes- sage 3. The preferred retrieval scheme is RTSP. If RTSP isn't available the IMAP server should attempt to transfer the requested data to the FTP server at example.com. In either case the server will fill in the connection end-point information. 1.3. UID CHANNEL Command The UID CHANNEL command is identical to the CHANNEL command with the exception that the message numbers in the sequence sets refer to unique identifiers instead of message sequence numbers. 1.4. CHANNEL Response An untagged CHANNEL response is returned for each message-num- ber/body-section pair specified by the corresponding CHANNEL com- mand: * message-number CHANNEL section-spec URI The ordering of these responses is arbitrary. The message number and in the response mirror those in the correspond- ing request, therefore responses to UID CHANNEL commands report the message UID rather than the message sequence number. The server MUST NOT issue an untagged CHANNEL response containing a URI until such time as that URI is avaliable for the client to dereference. The lifetime of the URI is implementation defined. Nerenberg draft-ietf-lemonade-imap-channel-01.txt [Page 3] Internet Draft IMAP4 Channel Transport Mechanism January 2004 Example: The responses to the example command in the previous section might look like: S: * 1 CHANNEL 2 rtsp://frobozz.example.com/144124 S: * 3 CHANNEL 1 ftp://marvin@example.com/incoming/abzzqfw11423 S: * 3 CHANNEL 9.1 NIL S: 0 OK done The NIL response to the section 9.1 request indicates that the part could not be retrieved via any of the requested schemes. For example, this could be caused by the inability to convert or represent the content via the requested schemes, or because a resource was unavailable. 2. Command Sequencing There is no way to distinguish between a response to a CHANNEL com- mand and a UID CHANNEL command, therefore clients MUST NOT issue a UID CHANNEL command while a CHANNEL command is in progress. Con- versely, clients MUST NOT issue a CHANNEL command while a UID CHAN- NEL command is in progress. These restrictions are in addition to the normal sequencing rules that apply to UID-style commands. Servers MUST NOT send an EXPUNGE response while responding to a CHANNEL command, however a server MAY send an EXPUNGE response dur- ing a UID CHANNEL command. 3. Formal Protocol Syntax The following syntax specification uses the augmented Backus-Naur Form (ABNF) notation as defined in [ABNF], and incorporates by ref- erence the Core Rules from that document. This syntax extends the grammar specified in [IMAP4rev1]. The following tokens are incorporated from [URI]: absoluteURI, scheme. channel = "CHANNEL" SP channel-uri-list SP channel-set channelschemes = "CHANNELSCHEMES" channelschemes-data = nil / astring / "(" astring 1*(SP astring) ")" channel-data = nz-number SP "CHANNEL" SP section-spec SP astring ; represents an channel-set = 1*("(" nz-number SP section-spec ")") ; refers to the message sequence ; number or unique identifier. Nerenberg draft-ietf-lemonade-imap-channel-01.txt [Page 4] Internet Draft IMAP4 Channel Transport Mechanism January 2004 channel-uri-list = "(" channel-uri *(SP channel-uri) ")" channel-uri = astring ; / ; represented as an IMAP command-auth =/ channelschemes command-select =/ channel response-data = "*" SP (resp-cond-state / resp-cond-bye / mailbox-data / message-data / capability-data / channel-data) CRLF ; adds to uid =/ channel 4. Normative References [ABNF] Crocker, D., P. Overell, "Augmented BNF for Syntax Specifi- cations: ABNF." RFC2234, November 1997 [IMAP4rev1] Crispin, M., "Internet Message Access Protocol - Ver- sion 4rev1," RFC3501, March 2003 [KEYWORD] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels," BCP 9, RFC2119, March 1997 [URI] Berners-Lee, T., et al, "Uniform Resource Identifiers (URI): Generic Syntax," RFC2396, August 1998 5. IANA Considerations The IMAP capabilities registry must be updated to add the CHANNEL capability defined by this memo. 6. Security Considerations It is assumed that the IMAP server and its cooperating client share an authorization (and authentication) namespace. Nerenberg draft-ietf-lemonade-imap-channel-01.txt [Page 5] Internet Draft IMAP4 Channel Transport Mechanism January 2004 7. Authors' Addresses Lyndon Nerenberg Steve Hole Orthanc Systems ACI Worldwide Suite 900 10117 - Jasper Avenue Edmonton, Alberta Canada T5J 1W8 Phone: +1 780 424 4922 Barry Leiba IBM T.J. Watson Research Center 30 Saw Mill River Road Hawthorne, NY 10532 Phone: +1 914 784 7941 Nerenberg draft-ietf-lemonade-imap-channel-01.txt [Page 6]