RFC 
 3529 
 TOC 
Network Working GroupW. Harold
Request for Comments: 3529IBM
Category: ExperimentalApril 2003


Using Extensible Markup Language-Remote Procedure Calling (XML-RPC) in Blocks Extensible Exchange Protocol (BEEP)

Status of this Memo

This memo defines an Experimental Protocol for the Internet community. It does not specify an Internet standard of any kind. Discussion and suggestions for improvement are requested. Distribution of this memo is unlimited.

Copyright Notice

Copyright © The Internet Society (2003). All Rights Reserved.

Abstract

XML-RPC is an Extensible Markup Language-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.


 RFC 
 3529 
 TOC 

Table of Contents

1.  Introduction
2.  BEEP Profile Identification
    2.1.  Profile Initialization
3.  XML-RPC Message Packages
4.  XML-RPC Message Exchange
5.  URL Schemes
    5.1.  The xmlrpc.beep URL Scheme
        5.1.1.  Resolving IP/TCP Address Information
    5.2.  The xmlrpc.beeps URL Scheme
6.  Initial Registrations
    6.1.  Registration: The XML-RPC Profile
    6.2.  Registration: The xmlrpc.beep URL Scheme
    6.3.  Registration: The xmlrpc.beeps URL Scheme
    6.4.  Registration: The System (Well-Known) TCP port number for XML-RPC over BEEP
7.  Security Considerations
8.  References
Appendix A.  Acknowledgements
Appendix B.  IANA Considerations
§  Author's Address
§  Intellectual Property and Copyright Statements




 TOC 

1.  Introduction

This memo specifies how messages encoded in the XML-RPC (Winer, D., “XML-RPC Specification,” January 1999.) [XML‑RPC.SPEC] format are transmitted using a BEEP profile (Rose, M., “The Blocks Extensible Exchange Protocol Core,” March 2001.) [RFC3080].

Throughout this memo, the terms "request" and "response" refer to the "methodCall" and "methodResponse" elements defined by the XML-RPC specification [XML‑RPC.SPEC] (Winer, D., “XML-RPC Specification,” January 1999.). 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 [RFC3080] (Rose, M., “The Blocks Extensible Exchange Protocol Core,” March 2001.) discuss BEEP roles and exchange styles.



 TOC 

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.,

    <start number='1' serverName='stateserver.example.com'>
        <profile uri='http://iana.org/beep/transient/xmlrpc' />
    </start>

The "serverName" attribute is analogous to HTTP's "Host" request-header field (c.f., Section 14.23 of [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.)).

There are two states in the BEEP profile for XML-RPC, "boot", the profile's initial state, and "ready":



 TOC 

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:

    <!ELEMENT bootmsg     EMPTY>
    <!ATTLIST bootmsg
              resource    CDATA             #REQUIRED>

    <!ELEMENT bootrpy     EMPTY>

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 [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.))

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 [RFC3080] (Rose, M., “The Blocks Extensible Exchange Protocol Core,” March 2001.)).

Typically, the boot message and its response are exchanged during channel initialization (c.f., Section 2.3.1.2 of [RFC3080] (Rose, M., “The Blocks Extensible Exchange Protocol Core,” March 2001.)).

For example, here the boot message and its response are exchanged during channel initialization:

    C: <start number='1' serverName='stateserver.example.com'>
    C:     <profile uri='http://iana.org/beep/transient/xmlrpc'>
    C:         <![CDATA[<bootmsg resource='/NumberToName' />]]>
    C:     </profile>
    C: </start>

    S: <profile uri='http://iana.org/beep/transient/xmlrpc'>
    S:     <![CDATA[<bootrpy />]]>
    S: </profile>

The channel bound to the BEEP profile for XML-RPC is now in the "ready" state.

Alternatively, here is an example in which the boot exchange is unsuccessful:

    C: <start number='1' serverName='stateserver.example.com'>
    C:     <profile uri='http://iana.org/beep/transient/xmlrpc'>
    C:         <![CDATA[<bootmsg resource='/NameToCapital' />]]>
    C:     </profile>
    C: </start>

    S: <profile uri='http://iana.org/beep/transient/xmlrpc'>
    S:     <![CDATA[<error code='550'>resource not
    S:                                supported</error>]]>
    S: </profile>

Although the channel was created successfully, it remains in the "boot" state.



 TOC 

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" (Murata, M., St. Laurent, S., and D. Kohn, “XML Media Types,” January 2001.) [RFC3023], e.g.,

    I: MSG 1 1 . 0 364
    I: Content-Type: application/xml
    I:
    I: <?xml version="1.0"?>
    I:   <methodCall>
    I:     <methodName>examples.getStateName</methodName>
    I:     <params>
    I:       <param>
    I:         <value><i4>41</i4></value>
    I:       </param>
    I:     </params>
    I:   </methodCall>
    I: END

and its associated response

    L: RPY 1 1 . 201 100
    L: Content-Type: application/xml
    L:
    L: <?xml version="1.0"?>
    L:   <methodResponse>
    L:     <params>
    L:       <param>
    L:         <value><string>South Dakota</string></value>
    L:       </param>
    L:     </params>
    L:   </methodRespose>
    L: END


 TOC 

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.



 TOC 

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.



 TOC 

5.1.  The xmlrpc.beep URL Scheme

The "xmlrpc.beep" URL scheme uses the "generic URI" syntax defined in Section 3 of [RFC2396] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifiers (URI): Generic Syntax,” August 1998.), specifically:

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 (Profile Initialization).



 TOC 

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 (Gulbrandsen, A., Vixie, P., and L. Esibov, “A DNS RR for specifying the location of services (DNS SRV),” February 2000.) [RFC2782] is used with a service parameter of "xmlrpc-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 (Registration: The System (Well-Known) TCP port number for XML-RPC over BEEP).

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 (Registration: The System (Well-Known) TCP port number for XML-RPC over BEEP).

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 [RFC2732] (Hinden, R., Carpenter, B., and L. Masinter, “Format for Literal IPv6 Addresses in URL's,” December 1999.).



 TOC 

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 (The xmlrpc.beep URL Scheme), 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 (Resolving IP/TCP Address Information) (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:

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 [RFC2595] (Newman, C., “Using TLS with IMAP, POP3 and ACAP,” June 1999.) describes the matching process.

For the URL:

    xmlrpc.beeps://stateserver.example.com/NumberToName

the whole process might look like:

    S: <wait for incoming connection @ stateserver.example.com>
    C: <open connection to stateserver.example.com>
    C: RPY 0 0 . 0 52
    C: Content-Type: application/xml
    C:
    C: <greeting />
    C: END
    S: RPY 0 0 . 0 110
    S: Content-Type: application/xml
    S:
    S: <greeting>
    S:   <profile uri='http://iana.org/beep/TLS' />
    S:   <profile uri='http://iana.org/beep/SASL/DIGEST-MD5' />
    S: </greeting>
    S: END
    C: MSG 0 1 . 52 158
    C: Content-Type: application/xml
    C:
    C: <start number='1' serverName='stateserver.example.com'>
    C:   <profile uri='http://iana.org/beep/TLS'>
    C:     <![CDATA[<ready />]]>
    C:   </profile>
    C: </start>
    C: END
    S: RPY 0 1 . 110 121
    S: Content-Type: application/xml
    S:
    S: <profile uri='http://iana.org/beep/TLS'>
    S:   <![CDATA[<proceed />]]>
    S: </profile>
    S: END

    ... TLS negotiations ...

    S: RPY 0 0 . 0 88
    S: Content-Type: application/xml
    S:
    S: <greeting>
    S:   <profile uri='http://iana.org/beep/transient/xmlrpc'>
    S: </greeting>
    S: END
    C: RPY 0 0 . 0 52
    C: Content-Type: application/xml
    C:
    C: <greeting />
    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: <start number='3' serverName='stateserver.example.com'>
    C:     <profile uri='http://iana.org/beep/transient/xmlrpc'>
    C:         <![CDATA[<bootmsg resource='/NumberToName' />]]>
    C:     </profile>
    C: </start>
    C: END
    S: RPY 0 2 . 341 402
    S: Content-Type: application/xml
    S:
    S: <profile uri='http://iana.org/beep/transient/xmlrpc'>
    S:     <![CDATA[<bootrpy />]]>
    S: </profile>
    S: END



 TOC 

6.  Initial Registrations



 TOC 

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 [XML‑RPC.SPEC] (Winer, D., “XML-RPC Specification,” January 1999.)
Message Semantics:
c.f., [XML‑RPC.SPEC] (Winer, D., “XML-RPC Specification,” January 1999.)
Contact Information:
Ward Harold <wharold@us.ibm.com>


 TOC 

6.2.  Registration: The xmlrpc.beep URL Scheme

URL scheme name:
xmlrpc.beep
URL scheme syntax:
c.f., Section 5.1 (The xmlrpc.beep URL Scheme)
Character encoding considerations:
c.f., the "generic URI" syntax defined in Section 3 of [RFC2396] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifiers (URI): Generic Syntax,” August 1998.)
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 (Security Considerations)
Relevant Publications:
c.f., [XML‑RPC.SPEC] (Winer, D., “XML-RPC Specification,” January 1999.), and [RFC3080] (Rose, M., “The Blocks Extensible Exchange Protocol Core,” March 2001.)
Contact Information:
Ward Harold <wharold@us.ibm.com>
Author/Change controller:
the IESG


 TOC 

6.3.  Registration: The xmlrpc.beeps URL Scheme

URL scheme name:
xmlrpc.beeps
URL scheme syntax:
c.f., Section 5.2 (The xmlrpc.beeps URL Scheme)
Character encoding considerations:
c.f., the "generic URI" syntax defined in Section 3 of [RFC2396] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifiers (URI): Generic Syntax,” August 1998.)
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 (Security Considerations)
Relevant Publications:
c.f., [XML‑RPC.SPEC] (Winer, D., “XML-RPC Specification,” January 1999.), and [RFC3080] (Rose, M., “The Blocks Extensible Exchange Protocol Core,” March 2001.)
Contact Information:
Ward Harold <wharold@us.ibm.com>
Author/Change controller:
the IESG


 TOC 

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 (Profile Initialization)
Functions:
c.f., [XML‑RPC.SPEC] (Winer, D., “XML-RPC Specification,” January 1999.)
Use of Broadcast/Multicast:
none
Proposed Name:
XML-RPC over BEEP
Short name:
xmlrpc-beep
Contact Information:
Ward Harold <wharold@us.ibm.com>


 TOC 

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 (Elkins, M., Del Torto, D., Levien, R., and T. Roessler, “MIME Security with OpenPGP,” August 2001.) [RFC3156] or S/MIME (Ramsdell, B., “S/MIME Version 3 Message Specification,” June 1999.) [RFC2633].

Regardless, consult [RFC3080] (Rose, M., “The Blocks Extensible Exchange Protocol Core,” March 2001.)'s Section 9 for a discussion of BEEP-specific security issues.



 TOC 

8. References

[XML-RPC.SPEC] Winer, D., “XML-RPC Specification,” January 1999.
[RFC3080] Rose, M., “The Blocks Extensible Exchange Protocol Core,” RFC 3080, March 2001 (TXT, HTML, XML).
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” RFC 2616, June 1999 (TXT, PS, PDF, HTML, XML).
[RFC3023] Murata, M., St. Laurent, S., and D. Kohn, “XML Media Types,” RFC 3023, January 2001 (TXT).
[RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifiers (URI): Generic Syntax,” RFC 2396, August 1998 (TXT, HTML, XML).
[RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, “A DNS RR for specifying the location of services (DNS SRV),” RFC 2782, February 2000 (TXT).
[RFC2732] Hinden, R., Carpenter, B., and L. Masinter, “Format for Literal IPv6 Addresses in URL's,” RFC 2732, December 1999 (TXT).
[RFC3156] Elkins, M., Del Torto, D., Levien, R., and T. Roessler, “MIME Security with OpenPGP,” RFC 3156, August 2001 (TXT).
[RFC2595] Newman, C., “Using TLS with IMAP, POP3 and ACAP,” RFC 2595, June 1999 (TXT).
[RFC2633] Ramsdell, B., “S/MIME Version 3 Message Specification,” RFC 2633, June 1999 (TXT).
[RFC3288] O'Tuathail, E. and M. Rose, “Using the Simple Object Access Protocol (SOAP) in Blocks Extensible Exchange Protocol (BEEP),” RFC 3288, June 2002 (TXT, HTML, XML).


 TOC 

Appendix A.  Acknowledgements

This document is based, in part, on Using SOAP in BEEP (O'Tuathail, E. and M. Rose, “Using the Simple Object Access Protocol (SOAP) in Blocks Extensible Exchange Protocol (BEEP),” June 2002.) [RFC3288] and the author gratefully acknowledges the contributions of Marshall Rose



 TOC 

Appendix B.  IANA Considerations

The IANA has registered the profile specified in Section 6.1, and has selected an IANA-specific URI, e.g.,

    http://iana.org/beep/xmlrpc

The IANA has registered "xmlrpc.beep" and "xmlrpc.beeps" as URL schemes, as specified in Section 6.2 (Registration: The xmlrpc.beep URL Scheme) and Section 6.3 (Registration: The xmlrpc.beeps URL Scheme), respectively. (See: http://www.iana.org/assignments/uri-schemes)

The IANA has registered "XML-RPC over BEEP" as a TCP port number (602), as specified in Section 6.4 (Registration: The System (Well-Known) TCP port number for XML-RPC over BEEP). (See: http://www.iana.org/assignments/port-numbers)



 TOC 

Author's Address

  Ward K Harold
  IBM
  11400 Burnet Road
  Austin, Texas 78758
  US
Phone:  +1 512 838 3022
Email:  wharold@us.ibm.com


 TOC 

Full Copyright Statement

Intellectual Property

Acknowledgment