Network Working Group W. Harold Internet-Draft Tivoli Software Expires: April 1, 2003 October 2002 Using XML-RPC in BEEP draft-harold-beep-xmlrpc-03 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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 April 1, 2003. Copyright Notice Copyright (C) The Internet Society (2002). All Rights Reserved. Abstract XML-RPC is a Remote Procedure Calling protocol that works over the Internet. It defines an XML format for messages that are transfered between clients and servers using HTTP. An XML-RPC message encodes either a procedure to be invoked by the server, along with the parameters to use in the invocation, or the result of an invocation. Procedure parameters and results can be scalars, numbers, strings, dates, etc.; they can also be complex record and list structures. This document specifies a how to use the Blocks Extensible Exchange Protocol (BEEP) to transfer messages encoded in the XML-RPC format between clients and servers. Harold Expires April 1, 2003 [Page 1] Internet-Draft Using XML-RPC in BEEP October 2002 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. BEEP Profile Identification . . . . . . . . . . . . . . . . 4 2.1 Profile Initialization . . . . . . . . . . . . . . . . . . 5 3. XML-RPC Message Packages . . . . . . . . . . . . . . . . . . 7 4. XML-RPC Message Exchange . . . . . . . . . . . . . . . . . . 8 5. URL Schemes . . . . . . . . . . . . . . . . . . . . . . . . 9 5.1 The xmlrpc.beep URL Scheme . . . . . . . . . . . . . . . . . 9 5.1.1 Resolving IP/TCP Address Information . . . . . . . . . . . 9 5.2 The xmlrpc.beeps URL Scheme . . . . . . . . . . . . . . . . 10 6. Initial Registrations . . . . . . . . . . . . . . . . . . . 13 6.1 Registration: The XML-RPC Profile . . . . . . . . . . . . . 13 6.2 Registration: The xmlrpc.beep URL Scheme . . . . . . . . . . 14 6.3 Registration: The xmlrpc.beeps URL Scheme . . . . . . . . . 15 6.4 Registration: The System (Well-Known) TCP port number for XML-RPC over BEEP . . . . . . . . . . . . . . . . . . . 15 7. Security Considerations . . . . . . . . . . . . . . . . . . 16 References . . . . . . . . . . . . . . . . . . . . . . . . . 17 Author's Address . . . . . . . . . . . . . . . . . . . . . . 18 A. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19 B. IANA Considerations . . . . . . . . . . . . . . . . . . . . 20 C. Revision History . . . . . . . . . . . . . . . . . . . . . . 21 C.1 Changes from draft-harold-beep-xmlrpc-00 . . . . . . . . . . 21 C.2 Changes from draft-harold-beep-xmlrpc-01 . . . . . . . . . . 21 C.3 Changes from draft-harold-beep-xmlrpc-02 . . . . . . . . . . 21 Full Copyright Statement . . . . . . . . . . . . . . . . . . 22 Harold Expires April 1, 2003 [Page 2] Internet-Draft Using XML-RPC in BEEP October 2002 1. Introduction This memo specifies how messages encoded in the XML-RPC [1] format are transmitted using a BEEP profile [2]. Throughout this memo, the terms "request" and "response" refer to the "methodCall" and "methodResponse" elements defined by the XML-RPC specification [1]. Further the terms "peer", "client", "server", and "one-to-one" are used in the context of BEEP. In particular, Sections 2.1 and 2.1.1 of [2] discuss BEEP roles and exchange styles. Harold Expires April 1, 2003 [Page 3] Internet-Draft Using XML-RPC in BEEP October 2002 2. BEEP Profile Identification The BEEP profile for XML-RPC is identified as http://iana.org/beep/transient/xmlrpc in the BEEP "profile" element during channel creation. In BEEP, when the first channel is successfully created, the "serverName" attribute in the "start" element identifies the "virtual host" associated with the peer acting in the server role, e.g., The "serverName" attribute is analagous to HTTP's "Host" request- header field (c.f., Section 14.23 of [3]). There are two states in the BEEP profile for XML-RPC, "boot", the profile's initial state, and "ready": o In the "boot" state, the peer requesting the creation of the channel sends a "bootmsg" (either during channel initialization or in a "MSG" message). * If the other peer sends a "bootrpy" (either during channel initialization or in a "RPY" message), then the "ready" state is entered * Otherwise, the other peer sends an "error" (either during channel initialization or in a "ERR" message), and no state change occurs. o In the "ready" state, the initiating peer begins an XML-RPC message pattern by sending a "MSG" message containing a request. The other peer completes the message pattern by sending back a "RPY" message containing a response. Harold Expires April 1, 2003 [Page 4] Internet-Draft Using XML-RPC in BEEP October 2002 2.1 Profile Initialization The boot message is used to identify the resource accessed by the channel bound to the BEEP profile for XML-RPC. The DTD syntax for the boot message and its response are: The boot message contains a single mandatory attribute: "resource", which is analagous to HTTP's "abs_path" Request-URI parameter (c.f., Section 5.1.2 of [3]) If the peer acting in the server role recognizes the requested resource, it replies with a boot response. Otherwise, if the boot message is improperly formed, or if the requested resource isn't recognized, the peer acting in the server role replies with an error message (c.f., Section 7.1 of [2]). Typically, the boot message and its response are exchanged during channel initialization (c.f., Section 2.3.1.2 of [2]). For example, here the boot message and its response are exchanged during channel initialization: C: C: C: ]]> C: C: S: S: ]]> S: The channel bound to the BEEP profile for XML-RPC is now in the "ready" state. Harold Expires April 1, 2003 [Page 5] Internet-Draft Using XML-RPC in BEEP October 2002 Alternatively, here is an example in which the boot exchange is unsuccessful: C: C: C: ]]> C: C: S: S: resource not S: supported]]> S: Although the channel was created successfully, it remains in the "boot" state. Harold Expires April 1, 2003 [Page 6] Internet-Draft Using XML-RPC in BEEP October 2002 3. XML-RPC Message Packages The BEEP profile for XML-RPC transmits requests and responses encoded as UTF-8 using the media type "application/xml" [4], e.g., I: MSG 1 1 . 0 364 I: Content-Type: application/xml I: I: I: I: examples.getStateName I: I: I: 41 I: I: I: I: END and its associated response L: RPY 1 1 . 201 100 L: Content-Type: application/xml L: L: L: L: L: L: South Dakota L: L: L: L: END Harold Expires April 1, 2003 [Page 7] Internet-Draft Using XML-RPC in BEEP October 2002 4. XML-RPC Message Exchange A request/response exchange involves sending a request, which results in a response being returned. The BEEP profile for XML-RPC achieves this using a one-to-one exchange, in which the client sends a "MSG" message containing an request, and the server sends back a "RPY" message containing an response. The BEEP profile for XML-RPC does not use the "ERR" message for XML- RPC faults when performing one-to-one exchanges — whatever response is generated by the server is always returned in the "RPY" message. Harold Expires April 1, 2003 [Page 8] Internet-Draft Using XML-RPC in BEEP October 2002 5. URL Schemes This memo defines two URL schemes, "xmlrpc.beep" and "xmlrpc.beeps", which identify the use of XML-RPC over BEEP over TCP. Note that, at present, a "generic" URL scheme for XML-RPC is not defined. 5.1 The xmlrpc.beep URL Scheme The "xmlrpc.beep" URL scheme uses the "generic URI" syntax defined in Section 3 of [5], specifically: o the value "xmlrpc.beep" is used for the scheme component; and, o the server-based naming authority defined in Section 3.2.2 of [5] is used for the authority component. o the path component maps to the "resource" component of the boot message sent during profile initialization (if absent, it defaults to "/"). The values of both the scheme and authority components are case- insensitive. For example, the URL xmlrpc.beep://stateserver.example.com/NumberToName might result in the example shown in Section 2.1. 5.1.1 Resolving IP/TCP Address Information The "xmlrpc.beep" URL scheme indicates the use of the BEEP profile for XML-RPC running over TCP/IP. If the authority component contains a domain name and a port number, e.g., xmlrpc.beep://stateserver.example.com:1026 then the DNS is queried for the A RRs corresponding to the domain name, and the port number is used directly. If the authority component contains a domain name and no port number, e.g., xmlrpc.beep://stateserver.example.com the SRV algorithm [6] is used with a service parameter of "xmlrpc- Harold Expires April 1, 2003 [Page 9] Internet-Draft Using XML-RPC in BEEP October 2002 beep" and a protocol parameter of "tcp" to determine the IP/TCP addressing information. If no appropriate SRV RRs are found (e.g., for "_xmlrpc-beep._tcp.stateserver.example.com"), then the DNS is queried for the A RRs corresponding to the domain name and the port number used is assigned by the IANA for the registration in Section 6.4. If the authority component contains an IP address, e.g., xmlrpc.beep://10.0.0.2:1026 then the DNS is not queried, and the IP address is used directly. If a port number is present, it is used directly; otherwise, the port number used is assigned by the IANA for the registration in Section 6.4. While the use of literal IPv6 addresses in URLs is discouraged, if a literal IPv6 address is used in a "xmlrpc.beep" URL, it must conform to the syntax specified in [7]. 5.2 The xmlrpc.beeps URL Scheme The "xmlrpc.beeps" URL scheme is identical, in all ways, to the "xmlrpc.beep" URL scheme specified in Section 5.1, with the exception that prior to starting the BEEP profile for XML-RPC, the BEEP session must be tuned for privacy. In particular, note that both URL schemes use the identical algorithms and parameters for address resolution as specified in Section 5.1.1 (e.g., the same service name for SRV lookups, the same port number for TCP, and so on). There are two ways to perform privacy tuning on a BEEP session, either: o a transport security profile may be successfully started; or, o a user authentication profile that supports transport security may be successfully started. In either case the client must present the authority component of the URL in the "serverName" attribute of the "start" element it uses to tune the session for privacy. When TLS is used for privacy the client must verify that the authority component of the URL matches the server's identity as presented in the server's certificate. Section 2.4 of [9] describes the matching process. Harold Expires April 1, 2003 [Page 10] Internet-Draft Using XML-RPC in BEEP October 2002 For the URL: xmlrpc.beeps://stateserver.example.com/NumberToName the whole process might look like: S: C: C: RPY 0 0 . 0 52 C: Content-Type: application/xml C: C: C: END S: RPY 0 0 . 0 110 S: Content-Type: application/xml S: S: S: S: S: S: END C: MSG 0 1 . 52 158 C: Content-Type: application/xml C: C: C: C: ]]> C: C: C: END S: RPY 0 1 . 110 121 S: Content-Type: application/xml S: S: S: ]]> S: S: END ... TLS negotiations ... S: RPY 0 0 . 0 88 S: Content-Type: application/xml S: S: S: S: S: END Harold Expires April 1, 2003 [Page 11] Internet-Draft Using XML-RPC in BEEP October 2002 C: RPY 0 0 . 0 52 C: Content-Type: application/xml C: C: C: END ... use the server's certificate to verify that it is in fact stateserver.example.com ... C: MSG 0 1 . 112 211 C: Content-Type: application/xml C: C: C: C: ]]> C: C: C: END S: RPY 0 2 . 341 402 S: Content-Type: application/xml S: S: S: ]]> S: S: END Harold Expires April 1, 2003 [Page 12] Internet-Draft Using XML-RPC in BEEP October 2002 6. Initial Registrations 6.1 Registration: The XML-RPC Profile Profile Identification: http://iana.org/beep/transient/xmlrpc Messages exchanged during Channel Creation: bootmsg, bootrpy Messages starting one-to-one exchanges: bootmsg, methodCall Messages in positive replies: bootrpy, methodResponse Messages in negative replies: error Messages in one-to-many exchanges: none Message Syntax: methodCall, methodResponse as defined in [1] Message Semantics: c.f., [1] Contact Information: Ward Harold Harold Expires April 1, 2003 [Page 13] Internet-Draft Using XML-RPC in BEEP October 2002 6.2 Registration: The xmlrpc.beep URL Scheme URL scheme name: xmlrpc.beep URL scheme syntax: c.f., Section 5.1 Character encoding considerations: c.f., the "generic URI" syntax defined in Section 3 of [5] Intended usage: identifies a XML-RPC resource made available using the BEEP profile for XML-RPC Applications using this scheme: c.f., "Intended usage", above Interoperability considerations: n/a Security Considerations: c.f., Section 7 Relevant Publications: c.f., [1], and [2] Contact Information: Ward Harold Author/Change controller: the IESG Harold Expires April 1, 2003 [Page 14] Internet-Draft Using XML-RPC in BEEP October 2002 6.3 Registration: The xmlrpc.beeps URL Scheme URL scheme name: xmlrpc.beeps URL scheme syntax: c.f., Section 5.2 Character encoding considerations: c.f., the "generic URI" syntax defined in Section 3 of [5] Intended usage: identifies a XML-RPC resource made available using the BEEP profile for XML-RPC after the BEEP session has been tuned for privacy Applications using this scheme: c.f., "Intended usage", above Interoperability considerations: n/a Security Considerations: c.f., Section 7 Relevant Publications: c.f., [1], and [2] Contact Information: Ward Harold Author/Change controller: the IESG 6.4 Registration: The System (Well-Known) TCP port number for XML-RPC over BEEP Protocol Number: TCP Message Formats, Types, Opcodes, and Sequences: c.f., Section 2.1 Functions: c.f., [1] Use of Broadcast/Multicast: none Proposed Name: XML-RPC over BEEP Short name: xmlrpc-beep Contact Information: Ward Harold Harold Expires April 1, 2003 [Page 15] Internet-Draft Using XML-RPC in BEEP October 2002 7. Security Considerations Although service provisioning is a policy matter, at a minimum, all implementations must provide the following tuning profiles: for authentication: http://iana.org/beep/SASL/DIGEST-MD5 for confidentiality: http://iana.org/beep/TLS (using the TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher) for both: http://iana.org/beep/TLS (using the TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher supporting client-side certificates) Further, implementations may choose to offer MIME-based security services providing message integrity and confidentiality, such as OpenPGP [8] or S/MIME [10]. Regardless, consult [2]'s Section 9 for a discussion of BEEP-specific security issues. Harold Expires April 1, 2003 [Page 16] Internet-Draft Using XML-RPC in BEEP October 2002 References [1] Winer, D., "XML-RPC Specification", January 1999, . [2] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC 3080, March 2001. [3] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [4] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC 3023, January 2001. [5] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. [6] Gulbrandsen, A., Vixie, P. and L. Esibov, "A DNS RR for specifying the location of services (DNS SRV)", RFC 2782, February 2000. [7] Hinden, R., Carpenter, B. and L. Masinter, "Format for Literal IPv6 Addresses in URL's", RFC 2732, December 1999. [8] Elkins, M., Del Torto, D., Levien, R. and T. Roessler, "MIME Security with OpenPGP", RFC 3156, August 2001. [9] Newman, C., "Using TLS with IMAP, POP3 and ACAP", RFC 2595, June 1999. [10] Ramsdell, B., "S/MIME Version 3 Message Specification", RFC 2633, June 1999. [11] O'Tuathail, E. and M. Rose, "Using the Simple Object Access Protocol (SOAP) in Blocks Extensible Exchange Protocol (BEEP)", RFC 3288, June 2002. Harold Expires April 1, 2003 [Page 17] Internet-Draft Using XML-RPC in BEEP October 2002 Author's Address Ward K Harold Tivoli Software 9442 Capital of Texas Highway North Austin, Texas 78759 US Phone: +1 512 436 8622 EMail: wharold@us.ibm.com Harold Expires April 1, 2003 [Page 18] Internet-Draft Using XML-RPC in BEEP October 2002 Appendix A. Acknowledgements This document is based, in part, on Using SOAP in BEEP [11] and the author gratefully acknowledges the contributions of Marshall Rose Harold Expires April 1, 2003 [Page 19] Internet-Draft Using XML-RPC in BEEP October 2002 Appendix B. IANA Considerations If the IESG approves this memo for publication, then the IANA registers the profile specified in Section 6.1, and selects an IANA- specific URI, e.g., http://iana.org/beep/xmlrpc The IANA registers "xmlrpc.beep" and "xmlrpc.beeps" as URL schemes, as specified in Section 6.2 and Section 6.3, respectively. The IANA registers "XML-RPC over BEEP" as a TCP port number, as specified in Section 6.4. Harold Expires April 1, 2003 [Page 20] Internet-Draft Using XML-RPC in BEEP October 2002 Appendix C. Revision History Note to RFC editor: please remove this entire appendix, and the corresponding entries in the table of contents, prior to publication. C.1 Changes from draft-harold-beep-xmlrpc-00 Clarified the relationship between XML-RPC and HTTP in the abstract C.2 Changes from draft-harold-beep-xmlrpc-01 Refer to RFC 2732 rather than 2472 for format of IPv6 Addresses in URLs Update reference to "Using SOAP over BEEP" from I-D to RFC 3288 Require clients to present the URL authority component in the "serverName" attribute of the "start" element used to tune for privacy when using an xmlrpc.beeps URL Require clients tuning with TLS to verify the server's identity via the process described in Section 2.4 of RFC 2595 Added an example of tuning for privacy when using an xmlrpc.beeps URL C.3 Changes from draft-harold-beep-xmlrpc-02 Corrected 'Content-Type' headers in message traces. Harold Expires April 1, 2003 [Page 21] Internet-Draft Using XML-RPC in BEEP October 2002 Full Copyright Statement Copyright (C) The Internet Society (2002). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Harold Expires April 1, 2003 [Page 22]