Norbert Bollow Internet-Draft DotGNU Project Expires: June 2, 2005 December 3, 2004 QRPC - Queueable Remote Procedure Calls Status of this Memo This document is an Internet-Draft and is subject to all provisions of section 3 of RFC 3667. By submitting this Internet-Draft, the author represents that he is not aware of any applicable patent or other IPR claims, and any of which he becomes aware will be disclosed, in accordance with RFC 3668. 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 documents 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. This Internet-Draft will expire on June 2, 2005. Copyright Notice Copyright (C) The Internet Society (2004). Abstract The QRPC (Queueable Remote Procedure Calls) protocol is a fast and versatile general-purpose webservice protocol. QRPC can be used as a faster replacement for XML-RPC or SOAP, or it can be used for more general kinds of webservices which integrate technical and business processes across trusted or untrusted networks. QRPC brings the flexibility of the UNIX inter-process communication mechanism with pipes, signals and redirection of "standard input", "standard output" and "standard error" to the realm of webservices. 1. Introduction 1.1. Overview Over the past few years, "webservices" protocols such as for example SOAP or XML-RPC have started becoming popular. The fundamental idea of "webservices" is to access functionality on another computer by means of standardized multi-purpose protocols and a standardized extensible data format. For example, when using the "webservices" paradigm to specify a message transport system, you don't specify the protocol and data format from scratch like it is done for SMTP in [RFC2821] and [RFC2822]; instead you specify them in terms of a general-purpose data format (often XML) and a general-purpose protocol for transporting data between computers. QRPC is a general-purpose Remote Procedure Call webservice protocol, which is based on the SXDF data format [SXDF] and which uses the QQP protocol [QQP] for data transport. 1.2. Examples of possible uses of QRPC 1.2.1. Simple RPC request and response The fundamental idea of a Remote Procedure Call is to send some data (the parameters) to an URL at a remote computer, where a program will run, which acts on the data and sends a response back. +--------+ request +--------+ | Client |---------->| Server | +--------+ +--------+ +--------+ response +--------+ | Client |<----------| Server | +--------+ +--------+ This can be achieved with QRPC just like this is possible also with XML-RPC or SOAP. For this kind of application, the main difference is that QRPC uses a data representation which is more compact and which can be parsed more efficiently. 1.2.2. Certifying that a given HTTP POST isn't spam As explained in [ANTISPAM], a useful anti-spam measure for messages which are submitted via HTTP POST is to ask the web browser which POSTs the message to request a confirmation (from a server which is operated by the user's ISP) that this user isn't making unreasonably many such HTTP POST requests. With QRPC this can be implemented as follows: +---------+ SHA1 of the +--------------+ assertion +-----------+ | Browser |------------->| ISP's server |----------->| Webserver | | | POST data +--------------+ "looks ok" | | | | | | | | | | | | POST data via HTTP | | | |----------------------------------------->| | +---------+ +-----------+ The main point here is that the Browser can send the SHA1 of the POST data to the ISP's server and then it can proceed immediately to send the POST data to the Webserver via HTTP. The browser does not wait for a response from the ISP's server because QRPC allows to redirect the result of the "create an assertion that this looks ok" webservice request directly to the Webserver. 1.2.3. Requesting a data stream Someone who wishes to listen to streamed audio or video content from a website can send an QRPC request which initiates the transmission of streamed data. QRPC is flexible enough that the streamed data can be sent directly as the response to the webservice request; it is not necessary to set up a separate data connection. QRPC Signals can be used to request a change of bandwidth use, or to stop the transmission altogether. 1.2.4. Secure Webservice Interaction Across Firewalls In QRPC, a client and a server can exchange data over an untrusted network, like this: +--------+ TCP +-----------+ SSL +-----------+ TCP +--------+ | Client |<---->| QQP proxy |<-------->| QQP proxy |<----->| Server | | | LAN | Firewall | Internet | Firewall | LAN | | +--------+ +-----------+ +-----------+ +--------+ Each of the arrows in this picture represents a TCP or SSL connection over which SXDF resources are transmitted. On each of the firewall machines, a QQP proxy server receives and forwards the SXDF resources. The proxy server can also act as a filter which discards unauthorized QRPC requests. 1.3 Editorial and Conformance Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in RFC2119 [KEYWORDS]. Consequently, we use these capitalized key words to unambiguously specify requirements over protocol and application features and behavior that affect the interoperability and security of implementations. These key words are not used (capitalized) to describe the structure of SXDF resources, and this structure is specified unambiguously by means of SXDF Data Structure Descriptions [SXDF, section 4] and we wish to reserve the prominence of these terms for the natural language descriptions of protocols and features. For instance, an SXDF element might be described as being "optional." 1.4 Acknowledgments Discussions with, and comments from the following people are gratefully acknowledged: * Nicolai Guba * Chris Smith * James Michael DuPont 2. QRPC Messages. Section 2.1 provides an overview of how the SXDF resources, which are used in the QRPC protocol, are structured. The formal DSDs are given in section 2.2. The semantics are explained in section 3. 2.1 Overview The SXDF resources used in the QRPC protocol all have the following basic structure: +---------------------------------------------------+ | SXDF resource | | | | +--------------------------------------------+ | | | Data | | | | | | | | | | | | | | | | (optional) | | | | (optional) | | | | (optional) | | | | (optional) | | | | | | | | or | | | | or or | | | +--------------------------------------------+ | | | | (optional) | +---------------------------------------------------+ Remark: While the Signature is optional as far as this protocol specification is concerned, implementations MAY discard every SXDF resource which does not have a valid Signature. Such filtering MAY also be done by a QQP proxy. The ExecutionRequest or StreamedData or Exception or Signal element has the following structure: +-----------------------------------------+ | ExecutionRequest | | | | (optional) | | (optional) | | | | | | (optional) | +-----------------------------------------+ Remark: The is required unless the client will send further data in the form of StreamedData. The Params element can contain any SXDF data. The optional RelayTo element may contain a qrpc: URL or a list of such URLs. +-----------------------------------------+ | Exception | | | | The Exception element can contain any | | SXDF data. The precise semantics are | | application-dependent. | | | +-----------------------------------------+ +-----------------------------------------+ | Signal | | | | The Signal element can contain any | | SXDF data. The precise semantics are | | application-dependent. | | | +-----------------------------------------+ +-----------------------------------------+ | StreamedData | | | | | | | | | | | | (optional) | +-----------------------------------------+ Remark: The EOT is required in the final StreamedData package from the client to the server (the only exception to this rule is if there was an EOT in the ExecutionRequest, which means that the client does not send any StreamedData packages to the server). 2.2. SXDF Data Structure Specifications 1034:14% 8:resource=2% 4:Data=8:1*1@Data 9:Signature=4:*1@s 4:Data=4@ 5:Data1 5:Data2 5:Data3 5:Data4 5:Data1=6% 10:ResourceID=5:1*1@s 6:Action=5:1*1@s 12:ExceptionsTo=4:*1@s 11:FirewallKey=4:*1@s 9:ClientKey=4:*1@s 16:ExecutionRequest=20:1*1@ExecutionRequest 5:Data2=7% 10:ResourceID=5:1*1@s 6:Action=5:1*1@s 12:ExceptionsTo=4:*1@s 11:FirewallKey=4:*1@s 9:ClientKey=4:*1@s 9:ServerKey=4:*1@s 10:Exception=5:1*1@d 5:Data2=7% 10:ResourceID=5:1*1@s 6:Action=5:1*1@s 12:ExceptionsTo=4:*1@s 11:FirewallKey=4:*1@s 9:ClientKey=4:*1@s 9:ServerKey=4:*1@s 6:Signal=5:1*1@d 5:Data3=7% 10:ResourceID=5:1*1@s 6:Action=5:1*1@s 12:ExceptionsTo=4:*1@s 11:FirewallKey=4:*1@s 9:ClientKey=4:*1@s 9:ServerKey=4:*1@s 12:StreamedData=16:1*1@StreamedData 1:s=2:*s 1:d=3% 4:size=1:* 4:keys=2:*s 6:values=2:any 1:a=5:*@any 1:i=2:*i 1:f=2:*f 3:any=5@ 1:s 1:d 1:a 1:i 1:f 16:ExecutionRequest=4% 10:ResponseTo=4:*1@s 7:RelayTo=4:*1@s 6:Params=4:*1@d 3:EOT=*1@0 12:StreamedData=3% 10:SequenceNo=4:*1@s 4:Data4:*1@d 3:EOT=*1@0 ; 3. Processing Streams Of Data Unlike SOAP and XML-RPC the QRPC protocol specified here is also designed to support stateful webservices. The client creates a webservice session by means of an ExecutionRequest. The ExecutionRequest will generally contain some parameters, and subsequent messages will transmit further data. (In such follow-on messages that are intended for the same webservice session, the StreamedData element is used instead of the ExecutionRequest element.) The final data packet from the client contains an EOT ("end of transmission") element which effectively closes the channel. If the client is sending a stream of data (i.e. the ExecutionRequest does not already contain an EOT element), the subsequent data packages have sequence numbers, and generally for each data package, the server will send a response packet (containing a StreamedData element with the same sequence number) back to the client. The only exception to this rule is if due to an error, the server has generated an Exception (see below) and included an EOT element in a response. (If the server includes an EOT element in a response without the client having sent an EOT element first, it MUST generate an Exception.) In this case, the server MUST ignore all subsequent data packages with the same session ID. The client MUST wait until before sending the next data packet until a response packet has been received to the ExecutionRequest. Afterwards the client MAY send multiple data packages without waiting for response packets. However the client MUST stop sending data immediately if it receives a response which contains an EOT element. (Waiting for each response is necessary if the next packet cannot be computed until the response to the previous packet has been received, but it many situations it would just needlessly slow data transmission.) If the server receives a data package with a sequence number which is higher than the expected next sequence number, it MUST NOT process this package until all packages with lower sequence numbers have been received and processed. If this is not possible (e.g. because the necessary resources are not available for buffering packages, or because a configured maximal waiting time has expired) the server MUST generate an Exception and in addition send a StreamedData data package with the SequenceNo set to the expected next sequence, and which in addition contains an EOT element but no or elements. If the client is sending only a single data package (i.e. the ExecutionRequest already contains an EOT element), the server can either respond with a single data package (with sequence number 0 and an EOT element), or it can respond with a stream of data. 3.1. Generation of Session Identifiers. For each QRPC session, there can be up to three different session identifiers. Messages which are sent across untrusted networks SHOULD contain a FirewallKey element. The FirewallKey is generated by the Client before sending the initial ExecutionRequest. This key MUST consist of at least 16 characters in the base64 alphabet, and it SHOULD contain at least 92 bits of entropy. It SHOULD be generated by the QRPC implementation using a cryptographically strong source of random data. The QRPC implementation MAY allow the user to request a FirewallKey size which is different from the default provided that a FirewallKey of the requested size contains at least 92 bits of entropy. The Client MAY use a method for FirewallKey generation which does not guarantee the random bits to be completely independant of each other, but then the size of the key SHOULD be increased to ensure that the minimum of 92 bits of entropy is achieved. Both the Client and the Server MUST include this FirewallKey in each subsequent SXDF resource which is part of the same session. The Client MAY in addition generate a ClientKey and include it in the ExecutionRequest. In this case the server MUST include this ClientKey in every SXDF resource which it generates as part of the same session. The Client is completely free in the choice of this ClientKey. For example, the client MAY use a pre-existing database key for this purpose. If the Server's response to the ExecutionRequest does not already contain an EOT element, the Server MUST generate a ServerKey and include it in the response to the ExecutionRequest. The Client MUST include this ServerKey in every further SXDF resource which is part of the same session. The server SHOULD use a method for ServerKey generation which prevents multiple sessions from using the same ServerKey. For example, the server MAY use a Universal Unique IDentifier (see [UUID]) as ServerKey. 3.2. Exceptions The server reacts to errors by generating an Exception. Depending on the ser verity of the error, the webservice process may possibly need to be terminated, in which case in addition to the Exception a response data package which contains an EOT element MUST be generated. 3.3. Redirection The ExecutionRequest may optionally contain a qrpc: URL to which response packages should be addressed, and it may optionally contain a URL to which Exception packages should be addressed. By default both types of packages are directed to the Sender URL of the original ExecutionRequest. 3.4. Signals Signals are data packages sent from the client to the server which do not contain a sequence number, and which may be sent at any time, i.e. even after the final data package (which contains the EOT element). For example, the server may implement a type of signal which causes it to immediately generates an exception, send a final response data package (containing an EOT element), and discard any remaining data from the client which may still be unprocessed. 3.5. Handling Exceptions. Server and webservice implementations SHOULD have detailed documentation of all exceptions that they can generate. Generally the client forwards all Exception packets which it cannot handle to a general exception handler application that will inform the system operator in an appropriate manner. If the client is not capable of handling any exceptions, redirection of Exceptions to the general exception handler application can be used. 4. Security Considerations Webservices typically act on untrusted data; they therefore need to be carefully designed and reviewed to prevent security breaches. When webservice requests are transmitted over an untrusted network, firewalls are RECOMMENDED as an additional line of defense. 5. IANA Considerations A request will be made to IANA to add qrpc: to the registry of URL schemes. References Normative References [RFC1738] Berners-Lee, T., Masinter, L., McCahill, M., Eds., "Uniform Resource Locators", RFC 1738. [SXDF] Bollow, N., "SXDF - Simple Extensible Data Format", work in progress. [QQP] Bollow, N., "QQP - Quick Queues Protocol", work in progress. [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Informative References [ANTISPAM] Bollow, N., "Spank spammers, but beware the trolls", work in progress. [UUID] International Organization for Standardization: "Information technology - Open Systems Interconnection - Remote Procedure Call (RPC)", ISO/IEC 11578:1996. Authors' Address Norbert Bollow Weidlistrasse 18 CH-8624 Gruet Pone: +41 1 972 2059 EMail: nb@bollow.ch Full Copyright Statement Copyright (C) The Internet Society (2004). This document is subject to the rights, licenses and restrictions contained in BCP 78, and at www.rfc-editor.org, and except as set forth therein, the authors retain all their rights. Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE 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. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society.