From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc3288.txt | 1123 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1123 insertions(+) create mode 100644 doc/rfc/rfc3288.txt (limited to 'doc/rfc/rfc3288.txt') diff --git a/doc/rfc/rfc3288.txt b/doc/rfc/rfc3288.txt new file mode 100644 index 0000000..2a85c34 --- /dev/null +++ b/doc/rfc/rfc3288.txt @@ -0,0 +1,1123 @@ + + + + + + +Network Working Group E. O'Tuathail +Request for Comments: 3288 Clipcode.com +Category: Standards Track M. Rose + Dover Beach Consulting, Inc. + June 2002 + + + Using the Simple Object Access Protocol (SOAP) + in Blocks Extensible Exchange Protocol (BEEP) + +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) The Internet Society (2002). All Rights Reserved. + +Abstract + + This memo specifies a Simple Object Access Protocol (SOAP) binding to + the Blocks Extensible Exchange Protocol core (BEEP). A SOAP binding + describes how SOAP messages are transmitted in the network. + + The SOAP is an XML-based (extensible markup language) 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. + + + + + + + + + + + + + + + + + +O'Tuathail & Rose Standards Track [Page 1] + +RFC 3288 Using SOAP in BEEP June 2002 + + +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. URL Schemes . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.1 The soap.beep URL Scheme . . . . . . . . . . . . . . . . . . 10 + 5.1.1 Resolving IP/TCP Address Information . . . . . . . . . . . . 10 + 5.2 The soap.beeps URL Scheme . . . . . . . . . . . . . . . . . 11 + 6. Registration Templates . . . . . . . . . . . . . . . . . . . 12 + 6.1 SOAP Profile Feature Registration Template . . . . . . . . . 12 + 7. Initial Registrations . . . . . . . . . . . . . . . . . . . 13 + 7.1 Registration: The SOAP Profile . . . . . . . . . . . . . . . 13 + 7.2 Registration: The soap.beep URL Scheme . . . . . . . . . . . 14 + 7.3 Registration: The soap.beeps URL Scheme . . . . . . . . . . 15 + 7.4 Registration: The System (Well-Known) TCP port number for + SOAP over BEEP . . . . . . . . . . . . . . . . . . . . . . . 15 + 8. Security Considerations . . . . . . . . . . . . . . . . . . 16 + References . . . . . . . . . . . . . . . . . . . . . . . . . 17 + IANA Considerations . . . . . . . . . . . . . . . . . . . . 18 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 18 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 19 + Full Copyright Statement . . . . . . . . . . . . . . . . . . 20 + + + + + + + + + + + + + + + + + + + + + + + +O'Tuathail & Rose Standards Track [Page 2] + +RFC 3288 Using SOAP in BEEP June 2002 + + +1. Introduction + + This memo specifies how SOAP 1.1 envelopes[1] are transmitted using a + BEEP profile[2]. In the W3C, the XMLP effort is evolving SOAP. + Accordingly, this memo provides a mechanism for negotiating the use + of new features. + + 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 Standards Track [Page 3] + +RFC 3288 Using SOAP in BEEP June 2002 + + +2. BEEP Profile Identification + + The BEEP profile for SOAP is identified as + + http://iana.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 Standards Track [Page 4] + +RFC 3288 Using SOAP in BEEP June 2002 + + +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: if new features of SOAP (such as compression) + emerge, their use can be negotiated. + + 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 6.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 + requested resource isn't recognized, the peer acting in the server + role replies with an error message (c.f., Section 7.1 of [2]). + + + + + +O'Tuathail & Rose Standards Track [Page 5] + +RFC 3288 Using SOAP in BEEP June 2002 + + + 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 Standards Track [Page 6] + +RFC 3288 Using SOAP in BEEP June 2002 + + +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 Standards Track [Page 7] + +RFC 3288 Using SOAP in BEEP June 2002 + + + 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 Standards Track [Page 8] + +RFC 3288 Using SOAP in BEEP June 2002 + + +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 for + SOAP faults 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 Standards Track [Page 9] + +RFC 3288 Using SOAP in BEEP June 2002 + + +5. URL Schemes + + This memo defines two URL schemes, "soap.beep" and "soap.beeps", + which identify the use of SOAP over BEEP over TCP. Note that, at + present, a "generic" URL scheme for SOAP is not defined. + +5.1 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.example.com/StockQuote + + might result in the example shown in Section 2.1. + +5.1.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.example.com:1026 + + then the DNS is queried for the A RRs corresponding to the domain + name, and the port number is used directly. + + + + + + + + + + +O'Tuathail & Rose Standards Track [Page 10] + +RFC 3288 Using SOAP in BEEP June 2002 + + + If the authority component contains a domain name and no port number, + e.g., + + soap.beep://stockquoteserver.example.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.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 7.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 + 7.4. + + While the use of literal IPv6 addresses in URLs is discouraged, if a + literal IPv6 address is used in a "soap.beep" URL, it must conform to + the syntax specified in [12]. + +5.2 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.1, 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.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 Standards Track [Page 11] + +RFC 3288 Using SOAP in BEEP June 2002 + + +6. Registration Templates + +6.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 electronic contact information for + the author of the feature. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +O'Tuathail & Rose Standards Track [Page 12] + +RFC 3288 Using SOAP in BEEP June 2002 + + +7. Initial Registrations + +7.1 Registration: The SOAP Profile + + Profile Identification: http://iana.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: Eamon O'Tuathail , + Marshall Rose + + + + + + + + + + + + + + + + + + + + + + + + + + + + +O'Tuathail & Rose Standards Track [Page 13] + +RFC 3288 Using SOAP in BEEP June 2002 + + +7.2 Registration: The soap.beep URL Scheme + + URL scheme name: soap.beep + + URL scheme syntax: c.f., Section 5.1 + + 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 8 + + Relevant Publications: c.f., [1], [6], and [2] + + Contact Information: Eamon O'Tuathail , + Marshall Rose + + Author/Change controller: the IESG + + + + + + + + + + + + + + + + + + + + + + + + + + + +O'Tuathail & Rose Standards Track [Page 14] + +RFC 3288 Using SOAP in BEEP June 2002 + + +7.3 Registration: The soap.beeps URL Scheme + + URL scheme name: soap.beeps + + URL scheme syntax: c.f., Section 5.2 + + 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 8 + + Relevant Publications: c.f., [1], [6], and [2] + + Contact Information: Eamon O'Tuathail , + Marshall Rose + + Author/Change controller: the IESG + + +7.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: Eamon O'Tuathail , + Marshall Rose + + + + + + + +O'Tuathail & Rose Standards Track [Page 15] + +RFC 3288 Using SOAP in BEEP June 2002 + + +8. 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[13] or S/MIME[14]. + + Regardless, consult [2]'s Section 9 for a discussion of BEEP-specific + security issues. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +O'Tuathail & Rose Standards Track [Page 16] + +RFC 3288 Using SOAP in BEEP June 2002 + + +References + + [1] Box, D., Ehnebuske, D., Kakivaya, G., Layman, A., Mendelsohn, + N., Nielsen, H., Thatte, S. and D. Winer, "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] Barton, J., Thatte, S. and H. Nielsen, "SOAP Messages with + Attachments", December 2000, . + + [7] Levinson, E., "Content-ID and Message-ID Uniform Resource + Locators", RFC 2392, August 1998. + + [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. + + [12] Haskin, D. and E. Allen, "IP Version 6 over PPP", RFC 2472, + December 1998. + + [13] Elkins, M., Del Torto, D., Levien, R. and T. Roessler, "MIME + Security with OpenPGP", RFC 3156, August 2001. + + + +O'Tuathail & Rose Standards Track [Page 17] + +RFC 3288 Using SOAP in BEEP June 2002 + + + [14] Ramsdell, B., "S/MIME Version 3 Message Specification", RFC + 2633, June 1999. + +IANA Considerations + + The IANA has registered the profile specified in Section 7.1 as: + + http://iana.org/beep/soap + + The IANA has registered "soap.beep" and "soap.beeps" as URL schemes, + as specified in Section 7.2 and Section 7.3, respectively. + + The IANA has also registered "SOAP over BEEP" as a TCP port number, + as specified in Section 7.4. + + Finally, the IANA maintains a list of SOAP profile features, c.f., + Section 6.1. The IESG is responsible for assigning a designated + expert to review the specification prior to the IANA making the + assignment. Prior to contacting the IESG, developers of SOAP profile + features must use the mailing list beepwg@lists.beepcore.org to + solicit commentary. + +Acknowledgements + + The authors gratefully acknowledge the contributions of: Christopher + Ferris, Huston Franklin, Alexey Melnikov, Bill Mills, and Roy T. + Fielding. + + + + + + + + + + + + + + + + + + + + + + + + +O'Tuathail & Rose Standards Track [Page 18] + +RFC 3288 Using SOAP in BEEP June 2002 + + +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 + Dover Beach Consulting, Inc. + POB 255268 + Sacramento, CA 95865-5268 + US + + Phone: +1 916 483 8878 + EMail: mrose@dbc.mtview.ca.us + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +O'Tuathail & Rose Standards Track [Page 19] + +RFC 3288 Using SOAP in BEEP June 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. + + + + + + + + + + + + + + + + + + + +O'Tuathail & Rose Standards Track [Page 20] + -- cgit v1.2.3