Network Working Group E. O'Tuathail Internet-Draft Clipcode.com Expires: December 29, 2001 M. Rose Invisible Worlds, Inc. June 30, 2001 Using SOAP in BEEP draft-etal-beep-soap-02 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 December 29, 2001. Copyright Notice Copyright (C) The Internet Society (2001). All Rights Reserved. Abstract SOAP is an XML-based messaging protocol used to implement a wide variety of distributed messaging models. It defines a message format and describes a variety of message patterns, including, but not limited to, RPC, asynchronous event notification, unacknowledged messages, and forwarding via SOAP intermediaries. A SOAP binding describes how SOAP messages are transmitted in the network. This memo specifies a SOAP binding to BEEP. O'Tuathail & Rose Expires December 29, 2001 [Page 1] Internet-Draft Using SOAP in BEEP June 2001 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. BEEP Profile Identification . . . . . . . . . . . . . . . . . 4 2.1 Profile Initialization . . . . . . . . . . . . . . . . . . . . 5 3. SOAP Message Packages . . . . . . . . . . . . . . . . . . . . 7 4. SOAP Message Patterns . . . . . . . . . . . . . . . . . . . . 9 4.1 One-way Message . . . . . . . . . . . . . . . . . . . . . . . 9 4.2 Request-Response Exchange . . . . . . . . . . . . . . . . . . 9 4.3 Request/N-Responses Exchange . . . . . . . . . . . . . . . . . 9 5. The soap.beep URL Scheme . . . . . . . . . . . . . . . . . . . 10 5.1 Resolving IP/TCP Address Information . . . . . . . . . . . . . 11 6. The soap.beeps URL Scheme . . . . . . . . . . . . . . . . . . 12 7. Registration Templates . . . . . . . . . . . . . . . . . . . . 13 7.1 SOAP Profile Feature Registration Template . . . . . . . . . . 13 8. Initial Registrations . . . . . . . . . . . . . . . . . . . . 14 8.1 Registration: The SOAP Profile . . . . . . . . . . . . . . . . 14 8.2 Registration: The soap.beep URL Scheme . . . . . . . . . . . . 15 8.3 Registration: The soap.beeps URL Scheme . . . . . . . . . . . 16 8.4 Registration: The System (Well-Known) TCP port number for SOAP over BEEP . . . . . . . . . . . . . . . . . . . . . . . . 16 9. Security Considerations . . . . . . . . . . . . . . . . . . . 17 References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 19 A. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 20 B. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 C. Revision History . . . . . . . . . . . . . . . . . . . . . . . 22 C.1 Changes from draft-etal-beep-soap-01 . . . . . . . . . . . . . 22 C.2 Changes from draft-etal-beep-soap-00 . . . . . . . . . . . . . 22 Full Copyright Statement . . . . . . . . . . . . . . . . . . . 23 O'Tuathail & Rose Expires December 29, 2001 [Page 2] Internet-Draft Using SOAP in BEEP June 2001 1. Introduction This memo specifies how SOAP 1.1 envelopes [1] are transmitted using a BEEP profile [2]. Throughout this memo, the term "envelope" refers to the "SOAP- Env:Envelope" element defined in Section 4 of [1]. Further, the terms "peer", "client", "server", "one-to-one", and "one-to-many" are used in the context of BEEP. In particular, Sections 2.1 and 2.1.1 of [2] discuss BEEP roles and exchange styles. O'Tuathail & Rose Expires December 29, 2001 [Page 3] Internet-Draft Using SOAP in BEEP June 2001 2. BEEP Profile Identification The BEEP profile for SOAP is identified as http://clipcode.org/beep/soap 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 SOAP, "boot" 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), then no state change occurs. o In the "ready" state, either peer begins a SOAP message pattern by sending a "MSG" message containing an envelope. The other peer completes the message pattern either by: * sending back a "RPY" message containing an envelope; or, * sending back zero or more "ANS" messages, each containing an envelope, followed by a "NUL" message. Regardless, no state change occurs. O'Tuathail & Rose Expires December 29, 2001 [Page 4] Internet-Draft Using SOAP in BEEP June 2001 2.1 Profile Initialization The boot message is used for two purposes: resource identification: each channel bound to the BEEP profile for SOAP provides access to a single resource (a network data object or service). feature negotiation: SOAP is an evolving protocol. New versions of the SOAP (such as the W3C's XMLP effort), and new features (such as compression), are likely to emerge. For example, if a new version of SOAP is specified, a corresponding feature for the BEEP profile for SOAP should be defined that allows negotiated use of the new version. The DTD syntax for the boot message and its response are: The boot message contains a mandatory and an optional attribute: o the "resource" attribute, which is analagous to HTTP's "abs_path" Request-URI parameter (c.f., Section 5.1.2 of [3]); and, o the "features" attribute, which, if present, contains one or more feature tokens, each indicating an optional feature of the BEEP profile for SOAP that is being requested for possible use over the channel. Section 7.1 defines a registration template for optional features. If the peer acting in the server role recognizes the requested resource, it replies with the boot response that contains one optional attribute: o the "features attribute, if present, contains a subset of the feature tokens in the boot message, indicating which features may be used over the channel. (If not present or empty, then no features may be used.) Otherwise, if the boot message is improperly formed, or if the O'Tuathail & Rose Expires December 29, 2001 [Page 5] Internet-Draft Using SOAP in BEEP June 2001 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 SOAP is now in the "ready" state. 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. O'Tuathail & Rose Expires December 29, 2001 [Page 6] Internet-Draft Using SOAP in BEEP June 2001 3. SOAP Message Packages The BEEP profile for SOAP transmits envelopes encoded as UTF-8 using the media type "application/xml" [4], e.g., MSG 1 1 . 0 364 Content-Type: application/xml DIS END O'Tuathail & Rose Expires December 29, 2001 [Page 7] Internet-Draft Using SOAP in BEEP June 2001 In addition, the BEEP profile for SOAP also allows envelopes to be transmitted as the root part of a "multipart/related" [5] content, and with subordinate parts referenced using the rules of Section 3 of [6] (i.e., using either the "Content-ID:" [7] or "Content-Location:" [8] headers), e.g., MSG 1 2 . 364 668 Content-Type: multipart/related; boundary="MIME_boundary"; type=application/xml; start="" --MIME_boundary Content-Type: application/xml Content-ID: .. .. --MIME_boundary Content-Type: image/tiff Content-Transfer-Encoding: binary Content-ID: ...binary TIFF image... --MIME_boundary-- END Consistent with Section 2 of [6], it is strongly recommended that the multipart contain a "start" parameter, and that the root part contain a "Content-ID:" header. However, because BEEP provides an 8bit-wide path, a "transformative" Content-Transfer-Encoding (e.g., "base64" or "quoted-printable") should not be used. Further note that MIME [9] requires that the value of the "Content-ID" header be globally unique. O'Tuathail & Rose Expires December 29, 2001 [Page 8] Internet-Draft Using SOAP in BEEP June 2001 4. SOAP Message Patterns 4.1 One-way Message A one-way message involves sending a message without any response being returned. The BEEP profile for SOAP achieves this using a one-to-many exchange, in which the client sends a "MSG" message containing an envelope, and the server immediately sends back a "NUL" message, before processing the contents of the envelope. 4.2 Request-Response Exchange A request/response exchange involves sending a request, which results in a response being returned. The BEEP profile for SOAP achieves this using a one-to-one exchange, in which the client sends a "MSG" message containing an envelope, and the server sends back a "RPY" message containing an envelope. Finally, the BEEP profile for SOAP does not use the "ERR" message when performing one-to-one exchanges -- whatever response is generated by the server is always returned in the "RPY" message. 4.3 Request/N-Responses Exchange A request/N-responses exchange involves sending a request, which results in zero or more responses being returned. The BEEP profile for SOAP achieves this using a one-to-many exchange, in which the client sends a "MSG" message containing an envelope, and the server sends back zero or more "ANS" messages, each containing an envelope, followed by a "NUL" message. O'Tuathail & Rose Expires December 29, 2001 [Page 9] Internet-Draft Using SOAP in BEEP June 2001 5. The soap.beep URL Scheme The "soap.beep" URL scheme uses the "generic URI" syntax defined in Section 3 of [10], specifically: o the value "soap.beep" is used for the scheme component; and, o the server-based naming authority defined in Section 3.2.2 of [10] 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 soap.beep://stockquoteserver.com/StockQuote might result in the example shown in Section 2.1. O'Tuathail & Rose Expires December 29, 2001 [Page 10] Internet-Draft Using SOAP in BEEP June 2001 5.1 Resolving IP/TCP Address Information The "soap.beep" URL scheme indicates the use of the BEEP profile for SOAP running over TCP/IP. If the authority component contains a domain name and a port number, e.g., soap.beep://stockquoteserver.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., soap.beep://stockquoteserver.com the SRV algorithm [11] is used with a service parameter of "soap- beep" and a protocol parameter of "tcp" to determine the IP/TCP addressing information. If no appropriate SRV RRs are found (e.g., for "_soap-beep._tcp.stockquoteserver.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 8.4. If the authority component contains an IP address, e.g., soap.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 8.4. O'Tuathail & Rose Expires December 29, 2001 [Page 11] Internet-Draft Using SOAP in BEEP June 2001 6. The soap.beeps URL Scheme The "soap.beeps" URL scheme is identical, in all ways, to the "soap.beep" URL scheme specified in Section 5, with the exception that prior to starting the BEEP profile for SOAP, 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 (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. Regardless, upon completion of the negotiation process, a tuning reset occurs in which both BEEP peers issue a new greeting. Consult Section 3 of [2] for an example of how a BEEP peer may choose to issue different greetings based on whether privacy is in use. O'Tuathail & Rose Expires December 29, 2001 [Page 12] Internet-Draft Using SOAP in BEEP June 2001 7. Registration Templates 7.1 SOAP Profile Feature Registration Template When a feature for the BEEP profile for SOAP is registered, the following information is supplied: Feature Identification: specify a string that identifies this feature. Unless the feature is registered with the IANA, the feature's identification must start with "x-". Feature Semantics: specify the semantics of the feature. Contact Information: specify the postal and electronic contact information for the author of the feature. O'Tuathail & Rose Expires December 29, 2001 [Page 13] Internet-Draft Using SOAP in BEEP June 2001 8. Initial Registrations 8.1 Registration: The SOAP Profile Profile Identification: http://clipcode.org/beep/SOAP Messages exchanged during Channel Creation: bootmsg, bootrpy Messages starting one-to-one exchanges: bootmsg, SOAP-Env:Envelope Messages in positive replies: bootrpy, SOAP-Env:Envelope Messages in negative replies: error Messages in one-to-many exchanges: SOAP-Env:Envelope Message Syntax: SOAP-Env:Envelope as defined in Section 4 of [1] and [6] Message Semantics: c.f., [1] Contact Information: c.f., the "Authors' Addresses" section of this memo O'Tuathail & Rose Expires December 29, 2001 [Page 14] Internet-Draft Using SOAP in BEEP June 2001 8.2 Registration: The soap.beep URL Scheme URL scheme name: soap.beep URL scheme syntax: c.f., Section 5 Character encoding considerations: c.f., the "generic URI" syntax defined in Section 3 of [10] Intended usage: identifies a SOAP resource made available using the BEEP profile for SOAP Applications using this scheme: c.f., "Intended usage", above Interoperability considerations: n/a Security Considerations: c.f., Section 9 Relevant Publications: c.f., [1], [6], and [2] Contact for further information: c.f., the "Author's Address" section of this memo Author/Change controller: the IESG O'Tuathail & Rose Expires December 29, 2001 [Page 15] Internet-Draft Using SOAP in BEEP June 2001 8.3 Registration: The soap.beeps URL Scheme URL scheme name: soap.beeps URL scheme syntax: c.f., Section 6 Character encoding considerations: c.f., the "generic URI" syntax defined in Section 3 of [10] Intended usage: identifies a SOAP resource made available using the BEEP profile for SOAP 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 9 Relevant Publications: c.f., [1], [6], and [2] Contact for further information: c.f., the "Author's Address" section of this memo Author/Change controller: the IESG 8.4 Registration: The System (Well-Known) TCP port number for SOAP 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: SOAP over BEEP Short name: soap-beep Contact Information: c.f., the "Authors' Addresses" section of this memo O'Tuathail & Rose Expires December 29, 2001 [Page 16] Internet-Draft Using SOAP in BEEP June 2001 9. Security Considerations Consult [2]'s Section 9 for a discussion of BEEP-specific security issues. Don't bother consulting [1]'s Section 8 for a discussion of SOAP- specific security issues. O'Tuathail & Rose Expires December 29, 2001 [Page 17] Internet-Draft Using SOAP in BEEP June 2001 References [1] World Wide Web Consortium, "Simple Object Access Protocol (SOAP) 1.1", May 2000, . [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] Levinson, E., "The MIME Multipart/Related Content-type", RFC 2387, August 1998. [6] World Wide Web Consortium, "SOAP Messages with Attachments", December 2000, . [7] Levinson, E., "Content-ID and Message-ID Uniform Resource Locators", RFC 2111, March 1997. [8] Palme, F., Hopmann, A., Shelness, N. and E. Stefferud, "MIME Encapsulation of Aggregate Documents, such as HTML (MHTML)", RFC 2557, March 1999. [9] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996. [10] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. [11] Gulbrandsen, A., Vixie, P. and L. Esibov, "A DNS RR for specifying the location of services (DNS SRV)", RFC 2782, February 2000. O'Tuathail & Rose Expires December 29, 2001 [Page 18] Internet-Draft Using SOAP in BEEP June 2001 Authors' Addresses Eamon O'Tuathail Clipcode.com 24 Thomastown Road Dun Laoghaire Dublin IE Phone: +353 1 2350 424 EMail: eamon.otuathail@clipcode.com URI: http://www.clipcode.com/ Marshall T. Rose Invisible Worlds, Inc. 131 Stony Circle Suite 500 Santa Rosa, CA 95401 US Phone: +1 707 578 2350 EMail: mrose@invisible.net URI: http://invisible.net/ O'Tuathail & Rose Expires December 29, 2001 [Page 19] Internet-Draft Using SOAP in BEEP June 2001 Appendix A. Acknowledgements The authors gratefully acknowledge the contributions of: Christopher Ferris, Huston Franklin, Bill Mills, and Roy T. Fielding. O'Tuathail & Rose Expires December 29, 2001 [Page 20] Internet-Draft Using SOAP in BEEP June 2001 Appendix B. IANA Considerations If the IESG approves this memo for standards-track publication, then the IANA registers the profile specified in Section 8.1, and selects an appropriate standards-track URI, e.g., http://iana.org/beep/soap The IANA registers "soap.beep" and "soap.beeps" as URL schemes, as specified in Section 8.2 and Section 8.3, respectively. The IANA registers "SOAP over BEEP" as a TCP port number, as specified in Section 8.4. Finally, the IANA maintains a list of SOAP profile features, c.f., Section 7.1. The IESG is responsible for assigning a designated expert to review the specification prior to the IANA making the assignment. As a courtesy to developers of non-standards track BEEP profiles and channel management features, the mailing list bxxpwg@invisible.net may be used to solicit commentary. O'Tuathail & Rose Expires December 29, 2001 [Page 21] Internet-Draft Using SOAP in BEEP June 2001 Appendix C. Revision History C.1 Changes from draft-etal-beep-soap-01 o Added the "soap.beeps" URL scheme. o The use of SOAP profile features was clarified. o A small number of typos were corrected. C.2 Changes from draft-etal-beep-soap-00 o Replaced URI parameters with explicit profile initialization. o Added SOAP profile features. o Added multipart/related support for SOAP packages. o Added the "soap.beep" URL scheme. O'Tuathail & Rose Expires December 29, 2001 [Page 22] Internet-Draft Using SOAP in BEEP June 2001 Full Copyright Statement Copyright (C) The Internet Society (2001). 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. O'Tuathail & Rose Expires December 29, 2001 [Page 23]