Request for Comments: EECS423-1 Case Western Reserve University Category: Experimental Sept 28, 2004 e-Parcel Stub Protocol 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) Case Western Reserve University (2004). All Rights Reserved. Abstract The e-Parcel protocol is an application-level protocol for exchanging arbitrary length files. The e-Parcel protocol allows the intended recipient of a file to accept or reject the transfer of the file prior to initiating transfer of the file. Table of Contents 1. Introduction 1.1. Purpose 1.2. Scope of this document 1.3. Requirements 1.4. Terminology 1.5. Overall Operation 2. Notational Conventions and Generic Grammar 3. E-Parcel Stubs (e-Stubs) 3.1. Overview 3.2. Element Description 3.2.1. E-Tag 3.2.2. State 3.2.2.1. Proposed 3.2.2.2. Accepted 3.2.2.3. Rejected 3.2.3. From and To 3.2.4. File size 3.2.5. File name 3.2.6. Description 3.2.7. Digest 3.3. E-Stub lists 3.4. E-Stub references 3.5. XML Schema 4. Messages 5. Method definitions 5.1. Session initiation and termination 5.1.1. HELLO 5.1.2. Authentication 5.1.3. QUIT 5.2. E-Stub creation and deletion 5.2.1. E-Stub creation 5.2.2. E-Stub deletion 5.3. Polling 5.4. Acceptance and Rejection 5.4.1. Acceptance 5.4.2. Rejection 5.5. Establishment of mediated connections 6. Responses 6.1. Successful 6.1.1. 200 OK (general) 6.1.2. 201 OK (GET) 6.1.3. 250 (session initiation) 6.1.4. 260 (session termination) 6.2. Errors 6.2.1. 400 Bad Request 6.2.2. 401 System Resource Failure 6.2.3. 402 No Match Found 6.2.4. 403 Size Limit Exceeded 6.2.5. 405 Not Permitted in Current State 7. Connection management 7.1. Transport protocol 7.2. Abort 8. Size limits 9. Full Copyright Statement REFERENCES 1. Introduction 1.1. Purpose The e-Parcel protocol is intended to address the problems encountered when sending attachments of arbitrary length using e-mail (e.g., [1]). The e-Parcel protocol enables the exchange of arbitrary length attachments, using a recipient identifier (which may be the same as the recipient's e-mail address). The protocol allows the recipient to either accept or reject delivery of the attachment. A description of the attachment is provided to the recipient by including at least the name of the attachment, its size, and who it is from. If the transfer is rejected, then no transmission of the attachment occurs. 1.2. Scope of this document This document describes the e-Parcel stub protocol for the effective delivery of e-Stubs and approval or refusal messages from the client to server and from the server to the client. This protocol partially derives from SMTP [1]. 1.3. Requirements 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 [2]. An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements for its protocols is said to be "conditionally compliant." 1.4. Terminology This specification uses a number of terms to refer to the roles played by participants in the e-Parcel Protocol. connection or transmission channel A full-duplex transport layer virtual circuit established between two programs for the exchange of commands, replies, and mail text. client An application program that establishes connections for the purpose of sending requests in cooperation with an e-Parcel server. The client initiates e-Parcel commands, receives replies, and governs the transfer of mail. A local language may be used in the user interface command/reply dialogue. server An application program that accepts connections in order to service requests by sending back responses. It transfers messages and files in cooperation with an e-Parcel client. It waits for a connection to be established via the transport service. It receives e-Parcel commands from the e-Parcel client, sends replies, and performs the specified operations. reply or response A reply (or response) is an acknowledgment (positive or negative) sent from the server to the client via the transmission channel in response to a command. The general form of a reply is a completion code (including error codes) followed by a text string. The codes are for use by programs and the text is usually intended for human users. e-Stub An XML [6] document containing a short description of the file or attachment to be sent to the recipient. command A request for a mail service action sent by the e-Parcel client to the e-Parcel server. approval/refusal message After the recipients approves for receiving the attachment, the e-parcel client will generate an approval/refusal message similar to e-stub. line A sequence of ASCII characters ending with a . mailbox or address A character string (address) which identifies a user to whom mail is to be sent. Mailbox normally consists of the host and user specifications. The standard mailbox naming convention is defined to be "user@domain". Additionally, the "container" in which mail is stored. session The set of exchanges that occur while the transmission channel is open. 1.5. Overall Operation The e-Parcel stub protocol defines the format of an XML document (the e-Stub) that describes a file transfer between a sender and a receiver. The e-Stub identifies an attachment by providing information such as the recipient address, the file name, and the size of the attachment. The e-Parcel stub protocol defines commands for creating, updating, synchronizing, and deleting e-Stubs. The e-Parcel stub protocol is a request-response protocol. An e-Parcel session begins with the establishment of a client-server connection. All requests are initiated by clients and appropriate responses are provided by the server. The client initiates sending of the attachment by issuing the MAIL command followed by an e-Stub. The server accepts the e-Stub and relays it to the recipient when the recipient polls the server. The recipient can then accept or decline delivery. 2. Notational Conventions and Generic Grammar The e-Stub is an XML document, and XML is described in [6]. All other mechanisms specified in this document are described in both prose and an augmented Backus-Naur Form (BNF) similar to that used by RFC 2616 [5]. Refer to [5] for the definition of terms such as mailbox and host. The rest of this section summarizes for completeness the terms that are more commonly used in this RFC, as quoted from [5]. name = definition The name of a rule is simply the name itself (without any enclosing "<" and ">") and is separated from its definition by the equal "=" character. White space is only significant in that indentation of continuation lines is used to indicate a rule definition that spans more than one line. Certain basic rules are in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle brackets are used within definitions whenever their presence will facilitate discerning the use of rule names. "literal" Quotation marks surround literal text. Unless stated otherwise, the text is case-insensitive. rule1 | rule2 Elements separated by a bar ("|") are alternatives, e.g., "yes | no" will accept yes or no. (rule1 rule2) Elements enclosed in parentheses are treated as a single element. Thus, "(elem (foo | bar) elem)" allows the token sequences "elem foo elem" and "elem bar elem". *rule The character "*" preceding an element indicates repetition. The full form is "*element" indicating at least and at most occurrences of element. Default values are 0 and infinity so that "*(element)" allows any number, including zero; "1*element" requires at least one; and "1*2element" allows one or two. [rule] Square brackets enclose optional elements; "[foo bar]" is equivalent to "*1(foo bar)". ; comment A semi-colon, set off some distance to the right of rule text, starts a comment that continues to the end of line. This is a simple way of including useful notes in parallel with the specifications. The following rules are used throughout this specification to describe basic parsing constructs. The US-ASCII coded character set is defined by ANSI X3.4-1986 [8]. CTL = SP = CR = LF = CRLF = CR LF TEXT = DIGIT = HEX = "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT The definition of host is given in RFC 2396 [9] and the definition of mailbox in RFC 822 [4] as updated by RFC 1123 [10]. 3. E-Parcel Stubs (e-Stubs) 3.1. Overview An e-Parcel stub (e-Stub) is a well-formed XML document [6]. The e-Stub root element is . A MUST contain one element, one element, one element, one element, one element, and one element. Additionally, a MAY contain one or more and elements, and other elements that are not defined in this document. Elements which do not appear in this document should have an appropriate XML namespace to distinguish them from extensions introduced by others. For example, phishy-stub-123 bush-kerry@case.edu cheney-edwards@case.edu Video of debate 123456 I did NOT approve this message! MD5 123456 proposed 3.2. Element Description 3.2.1. E-Tag The client is REQUIRED to provide a tag (e-tag) that consists of alphanumeric characters and the dash ("-") character and that will be used in conjunction with the value to univocally identify the e-Stub. The e-tag value MUST be unique among all e-Stubs from the same sender. Once the e-Stub has been successfully deleted, the e-tag MAY be reused. 3.2.2. State The e-Stub state MUST contain one of the values "proposed", "accepted", or "rejected". 3.2.2.1 Proposed The state of an e-Stub when it has been generated by the sending client. This state indicates that the e-Stub is still awaiting action by the receiving client. 3.2.2.2 Accepted The state of an e-Stub when it has been reviewed by the receiving client, and the receiving client has chosen to approve the delivery of the file described in the e-Stub. 3.2.2.3 Rejected The state of an e-Stub when it has been reviewed by the receiving client, and the receiving client has chosen to not approve the delivery of the file described in the e-Stub. 3.2.3. From and To The and elements MUST contain the mailbox of the sending and receiving users, respectively. 3.2.4. File size The represents the size of the file to be transmitted in bytes. This number is sent as a string of hexadecimal digits (1*HEX). 3.2.5. File name The represents the name of the file to be transferred. 3.2.6. Description The is a human-readable description of the file to be transferred. 3.2.7. Digest A short digest of the file supports integrity checks. The element MUST contain a (specifying the digest algorithm used) and a (the file digest). The element MAY take on the values "MD5" and "SHA1" to specify the MD5 [11] and SHA1 algorithms, respectively. The element MAY also take on other values to indicate alternative algorithms, as agreed upon by the Internet community. 3.3. E-Stub lists An e-Stub list is a well-formed XML document whose root is and whose elements are s. 3.4. E-Stub references An e-Stub reference is a well-formed XML document similar to an e-Stub, but its root is and it MUST contain only the and elements. 3.5. XML Schema An XML Schema for e-Stubs, e-Stub lists, and e-Stub references will be specified at a later date. The schemas will implicitly define the rules for eStub, eStubRef, and eStubList. 4. Messages E-Parcel is a request-reply protocol: the client submits a sequence of requests over the transmission channel, and the server MUST reply to each request in the order they were made. Each request or response is conveyed in a message. The general format of a message is Message = Request | Response Request = (((HELLO-REQUEST | QUIT-REQUEST | GET-REQUEST) SP Version CRLF) | ((ACCEPT-REQUEST | REJECT-REQUEST | DELETE-REQUEST | MAIL-REQUEST | SYN-REQUEST) SP Version CRLF Body)) Response = ("201" SP Version SP Explanation CRLF Body | "250" SP Version SP host CRLF | StatusCode SP Version SP Explanation CRLF) StatusCode = "200" | "260" | "401" | "402" | "403" | "405" Explanation = *TEXT Version = "EPP/0.1" If a message Body is included, it conveys one or more e-Stubs: Body = (eStub | eStubRef | eStubList) CRLF "&" CRLF where eStub, eStubRef, eStubList are defined in the previous section. 5. Method definitions The set of common methods and the appropriate responses are defined below. 5.1. Session initiation and termination An e-Parcel session is initiated when a client opens a connection to a server and the server responds with an opening message. An e-Parcel session is terminated when a client sends an appropriate method to the server and the server acknowledges it. 5.1.1 HELLO A client MUST start a session with a HELLO command followed by a client hostname (which SHOULD be fully qualified if possible). HELLO-REQUEST = "HELLO" SP host If the server accepts the connection, it MUST respond with reply code 250. The HELLO command allows the client to identify itself to the e-Parcel server. For example (C is the client and S the server), C: HELLO bender.cwru.edu EPP/0.1 S: 250 EPP/0.1 zoidberg.cwru.edu 5.1.2. Authentication Additional provisions for secure authentication (e.g., login) will be specified at a later date. 5.1.3. QUIT The QUIT command terminates a connection. QUIT-REQUEST = "QUIT" The server MUST close the transmission channel immediately after replying to a QUIT command. Either end-point MAY close or reset the connection asynchronously, for example, if the connection has been idle for too long. 5.2. E-Stub creation and deletion 5.2.1. E-Stub creation The MAIL command instructs the server to create a new e-Stub. MAIL-REQUEST = "MAIL" The MAIL command MUST be followed by a request Body that is an e-Stub whose is "proposed". The MAIL command SHALL NOT use an e-Stub reference or an e-Stub list instead of an e-Stub. If the server replies with code 200, it MUST record the e-Stub before replying. If the server replies with a code other than 200, it MUST NOT record the e-Stub. An example of the exchange between client (C) and server (S) is: C: MAIL EPP/0.1 C: C: C: mothra-123 C: captkirk@enterprise.gov C: eecs423@eecs.cwru.edu C: Video of aliens C: 123456 C: C: Beam us up, Scotty! C: C: proposed C: C: & S: 200 EPP/0.1 OK or S: 401 EPP/0.1 System Resource Failure 5.2.2. E-Stub deletion The delete command allows the sender to delete an e-Stub. DELETE-COMMAND = "DELETE" SP mailbox The DELETE-COMMAND MUST be followed by a request Body that is an e-Stub reference. If the server replies with code 200, it MUST delete, before replying, the e-Stub that has matching and fields with the e-Stub reference. If the server replies with a code other than 200, it MUST NOT delete any e-Stub. If the e-mail address is not the sender of the e-Stub, the server MUST respond with a 402 reply. 5.3. Polling A client can poll the server for the existence and value of e-Stubs. GET-COMMAND = "GET" SP mailbox If the server generates a 201 reply, it SHOULD include in the body an e-Stub list containing all the e-Stubs that are recorded at the server and that include the given e-mail address in the or record but it MUST NOT include any e-Stub in which the address does not appear in either the or record. 5.4. Acceptance and Rejection 5.4.1. Acceptance The recipient of an e-Stub can change its state to "accepted", which signifies that the client accepts delivery of the attachment. ACCEPT-COMMAND = "ACCEPT" SP mailbox The command MUST be followed in the Body by an e-Stub reference. The e-Stub reference will contain the name of the sender and the e-tag. If the and fields of the e-tag reference match that of an e-Stub on the server, the mailbox matches the field of the e-Stub, and the e-Stub is "proposed", the server MUST change the state of the e-stub to "accepted" and then respond to the client with code 200. If the addresses and e-tags do not match up, the server MUST respond with a 402 reply. If the addresses and e-tag do match up, but the e-Stub is not "proposed", the server must respond with a 405 reply. If the server replies with a code other than 200, it MUST NOT change any e-Stub state. 5.4.2. Rejection The recipient of an e-Stub can change its state to "rejected", which signifies that the client rejects delivery of the attachment. REJECT-COMMAND = "REJECT" SP mailbox The command MUST be followed in the Body by an e-Stub reference. The e-Stub reference will contain the name of the sender and the e-tag. If the and fields of the e-Stub reference match that of an e-Stub on the server, the mailbox matches the field of the e-Stub, and the e-Stub is "proposed", the server MUST change the state of the e-Stub to "rejected" and then respond to the client with code 200. If the addresses and e-tag do not match up, the server MUST respond with a 402 reply. If the addresses and e-tag do match up, but the e-Stub is not "proposed", the server must respond with a 405 reply. If the server replies with a code other than 200, it MUST NOT change any e-Stub state. 5.5. Establishment of mediated connections The objective of the SYN command is to establish a connection between sender and receiver. The connection is mediated by the server. SYN-COMMAND = "SYN" SP mailbox SP timeout timeout = 1*HEX The SYN command MUST be followed by an e-Stub reference in whose e-Stub the given mailbox appears as the or field. The server SHOULD reply to the client SYN approximately after the timeout value in milliseconds or earlier, as measured since the time the server received the SYN command. In general, it is difficult to achieve fine grained time-outs, but the server SHOULD take any reasonable step to reply within the time-out. If the server has an e-Stub that has been "accepted", for which both the (sender) and (receiver) are waiting for a reply to a SYN, the server SHOULD reply to both sender and receiver with a 200 status code. If the server generates a 200 reply, the sender must send OCTETs to the server, which MUST relay them to the receiver. Upon completion of the transfer, the server MUST discard the e-Stub. If the addresses and e-tag do not match up, the server MUST respond with a 402 reply. If the addresses and e-tag do match up, but the e-Stub is not "accepted", the server must respond with a 405 reply. 6. Responses The set of responses is defined below. 6.1. Successful 6.1.1. 200 OK (general) The request has succeeded. A suggested Explanation is "OK". The 200 response MUST NOT be used as a reply to HELLO, QUIT, or GET. 6.1.2. 201 OK (GET) The GET command succeeded and an eStubList is being returned in the body of the reply. A suggested Explanation is "OK". The 201 response MUST NOT be used as a reply to any command but GET. 6.1.3. 250 (session initiation) If the server accepts the session in response to a HELLO command, it MUST respond with a 250 reply. The server SHOULD attach its hostname, but the attachment MUST NOT be interpreted by the client and is collected only for management purposes. 6.1.4. 260 (session termination) In response to a QUIT command, the server MUST respond with a 260 reply and close the connection. 6.2. Errors 6.2.1. 400 Bad Request The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications. 6.2.2. 401 System Resource Failure The server does not have enough resources to complete the request. A suggested Explanation is "System Resource Failure". The server MUST NOT use 401 with HELLO and QUIT commands. 6.2.3. 402 No Match Found The server MUST reply with a 402 response if the e-Stub reference supplied by the client does not match any e-Stub on the server A suggested Explanation is "No Match Found". The server MUST NOT use a 402 with HELLO, QUIT, and GET. 6.2.4. 403 Size Limit Exceeded The server MUST send a 403 reply if the size limits defined in section 8 are exceeded. A suggested Explanation is "Size Limit Exceeded". 6.2.5. 405 Not Permitted in Current State The server MUST send a 405 reply if the operation is not permitted in the current state of the e-Stub. A suggested Explanation is "Not Permitted in Current State". 7. Connection management 7.1. Transport protocol E-Parcel is independent of the particular transmission subsystem and requires only a reliable ordered data stream channel. Although this document specifically discusses transport over TCP [7], this does not necessarily preclude e-Parcel from being implemented on top of any other protocol on the Internet, or on other networks. E-Parcel can communicate between processes using different transports by relaying through a process connected to two (or more) transport layers. More specifically, e-Parcel can be relayed between hosts on different transport systems by a host on both transport systems 7.2. Abort If the connection is closed prematurely the server MUST NOT undo any previously completed transaction. 8. Size Limits Size limits are imposed for some of the mail objects. An implementation MUST support objects of at least the following size, but MUST NOT send larger objects. An e-Parcel server MUST send a 403 reply for violation of the following size limits. - The maximum total length of a , , and records is 256 characters (including punctuation and element separators). - The maximum total length of a command line including the command word and is 512 characters. - The maximum total length of a reply line including the reply code and is 512 characters. - The maximum total length of a message line including the is 1000 characters. - The maximum total length of an e-Stub is 65536 characters. - The maximum total length of an e-stub reference is 1024 OCTETs. - The maximum total length of an etag is 512 OCTETS. - The maximum total length of a mailbox is 256 OCTETs (including all punctuation and element separators) 9. Full Copyright Statement Copyright (C) Case Western Reserve University (2004). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/S HE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. REFERENCES [1] Postel, J., "SIMPLE MAIL TRANSFER PROTOCOL" RFC 821, August 1982. [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [3] Bradner, S., "The Internet Standards Process -- Revision 3", RFC 2026, October 1996. [4] Crocker, D. H., "Standard for the format of ARPA Internet Text Messages", RFC 822, August 1982. [5] Fielding, R., Gettys J., Mogul J., Frystyk H., Masinter L., Leach P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2116, June 1999. [6] Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler, "Extensible Markup Language (XML) 1.0 (2nd ed)", W3C Recommendation xml, October 2000. [7] TRANSMISSION CONTROL PROTOCOL, RFC 793, September 1981. [8] US-ASCII. Coded Character Set - 7-Bit American Standard Code for Information Interchange. Standard ANSI X3.4-1986, ANSI, 1986. [9] Berners-Lee, T., Fielding, R. and L. Masinter, Uniform Resource Identifiers (URI): Generic Syntax and Semantics , RFC 2396, August 1998. [10] Braden, R., Requirements for Internet Hosts -- Communication Layers, STD 3, RFC 1123, October 1989. [11] Rivest, R., The MD5 Message-Digest Algorithm, RFC 1321, April 1992.