RFC 3288

Using the Simple Object Access Protocol (SOAP) in Blocks Extensible Exchange Protocol (BEEP)

📅 published June 2002, from ietf

RFC 3288: Using the Simple Object Access Protocol (SOAP) in Blocks Extensible Exchange Protocol (BEEP) 🦋

okay bestie, the title block is giving us all the tea 🫖✨ This is a Standards Track doc from the Network Working Group, dated June 2002. The authors are E. O'Tuathail (Clipcode.com) and M. Rose (Dover Beach Consulting, Inc.). The header doesn't list anything it obsoletes or updates, so no drama there 💅

Status of this Memo 📜

This doc specifies an Internet standards track protocol for the Internet community, and it asks for discussion and suggestions for improvements. For the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited 🌈

Copyright (C) The Internet Society (2002). All Rights Reserved. 💜

Abstract 🌸

This memo is all about a SOAP binding to the BEEP core, aka the Blocks Extensible Exchange Protocol core 🧚 A SOAP binding just describes how SOAP messages get transmitted across the network.

SOAP is an XML-based messaging protocol (XML = extensible markup language) that powers a whole bunch 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. Main character energy 👑

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

1. Introduction 🎀

This memo spells out how SOAP 1.1 envelopes[1] get transmitted using a BEEP profile[2] ✨ Over at the W3C, the XMLP effort is evolving SOAP, so this memo gives us a way to negotiate the use of new features. Iconic behavior 💅

Throughout this memo, the term "envelope" refers to the "SOAP-Env:Envelope" element defined in Section 4 of [1]. The terms "peer", "client", "server", "one-to-one", and "one-to-many" are used in the context of BEEP. Specifically, Sections 2.1 and 2.1.1 of [2] discuss BEEP roles and exchange styles 🦋

2. BEEP Profile Identification 🧩

The BEEP profile for SOAP is identified as:

    http://iana.org/beep/soap

It goes in the BEEP "profile" element during channel creation 🫶

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. For example:

    <start number='1' serverName='stockquoteserver.example.com'>
        <profile uri='http://iana.org/beep/soap' />
    </start>

The "serverName" attribute is analogous to HTTP's "Host" request-header field (c.f., Section 14.23 of [3]). It's giving "same energy" 🌸

There are two states in the BEEP profile for SOAP, "boot" and "ready":

  • 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 an "ERR" message), then no state change occurs.
  • 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. 🔥

2.1. Profile Initialization 🌱

The boot message has two jobs:

  • 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 is:

    <!ELEMENT bootmsg     EMPTY>
    <!ATTLIST bootmsg
              resource    CDATA             #REQUIRED
              features    NMTOKENS          "">

    <!ELEMENT bootrpy     EMPTY>
    <!ATTLIST bootrpy
              features    NMTOKENS          "">

The boot message has one mandatory attribute and one optional attribute:

  • the "resource" attribute, which is analogous to HTTP's "abs_path" Request-URI parameter (c.f., Section 5.1.2 of [3]); and,
  • the "features" attribute, which, if present, contains one or more feature tokens. Each token indicates 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, which has one optional attribute:

  • 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]). Yikes 💀

Typically, the boot message and its response are exchanged during channel initialization (c.f., Section 2.3.1.2 of [2]) ✨

Here's an example where the boot message and its response get exchanged during channel initialization:

    C: <start number='1' serverName='stockquoteserver.example.com'>
    C:     <profile uri='http://iana.org/beep/soap'>
    C:         <![CDATA[<bootmsg resource='/StockQuote' />]]>
    C:     </profile>
    C: </start>

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

The channel bound to the BEEP profile for SOAP is now in the "ready" state 🎉

Alternatively, here's an example where the boot exchange doesn't work out:

    C: <start number='1' serverName='stockquoteserver.example.com'>
    C:     <profile uri='http://iana.org/beep/soap'>
    C:         <![CDATA[<bootmsg resource='/StockPick' />]]>
    C:     </profile>
    C: </start>

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

The channel was created successfully, but it stays in the "boot" state 🙈

3. SOAP Message Packages 📦

The BEEP profile for SOAP transmits envelopes encoded as UTF-8, using the media type "application/xml"[4]. Here's a quick look:

MSG 1 1 . 0 364
Content-Type: application/xml

<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
       <m:GetLastTradePrice xmlns:m="Some-URI">
           <symbol>DIS</symbol>
       </m:GetLastTradePrice>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
END

The BEEP profile for SOAP also lets envelopes be transmitted as the root part of "multipart/related"[5] content. Subordinate parts can be referenced using the rules of Section 3 of [6] (i.e., using either the "Content-ID:"[7] or "Content-Location:"[8] headers). Here's how that looks 🧶

MSG 1 2 . 364 668
Content-Type: multipart/related; boundary="MIME_boundary";
              type=application/xml;
              start="<claim061400a.xml@claiming-it.com>"

--MIME_boundary
Content-Type: application/xml
Content-ID: <claim061400a.xml@claiming-it.com>

<?xml version='1.0' ?>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
..
<theSignedForm href="cid:claim061400a.tiff@claiming-it.com" />
..
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

--MIME_boundary
Content-Type: image/tiff
Content-Transfer-Encoding: binary
Content-ID: <claim061400a.tiff@claiming-it.com>

...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. Also note that MIME[9] requires the value of the "Content-ID" header to be globally unique 🌍

4. SOAP Message Patterns 🎯

4.1. One-way Message 📨

A one-way message means sending a message without any response coming back 🫠

The BEEP profile for SOAP does this with a one-to-many exchange. The client sends a "MSG" message containing an envelope, and the server immediately sends back a "NUL" message, before it processes the contents of the envelope 🏃‍♀️

4.2. Request-Response Exchange 🔁

A request/response exchange means sending a request, which results in a response coming back 💌

The BEEP profile for SOAP does this with a one-to-one exchange. 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 the server generates is always returned in the "RPY" message. No exceptions, bestie 🙅‍♀️💖

4.3 Request/N-Responses Exchange ✨

okay so this one is a request/N-responses exchange 💖 you send one request and you get back zero or more responses 🦋

the BEEP profile for SOAP does this with a one-to-many exchange 🎀 the client sends a MSG message with an envelope inside, then the server sends back zero or more ANS messages (each with its own envelope) and then a NUL message to close it out 🫶

5. URL Schemes 🌸

okay so this memo defines two URL schemes, soap.beep and soap.beeps 💅 they both point at SOAP over BEEP over TCP. and fair warning: there's no "generic" URL scheme for SOAP yet, so don't go looking for one 🙈

5.1 The soap.beep URL Scheme 🦋

the soap.beep scheme uses the "generic URI" syntax from Section 3 of [10] 💖 specifically:

  • the value soap.beep goes in the scheme component; and,
  • the server-based naming authority from Section 3.2.2 of [10] goes in the authority component.
  • the path component maps to the resource component of the boot message sent during profile initialization. if it's absent, it defaults to / ✨

the scheme and authority are both case-insensitive, so don't stress about capitals 🫶

for example, this 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 🔥

soap.beep tells you to use the BEEP profile for SOAP running over TCP/IP 🌈

if the authority has a domain name and a port number, like this:

soap.beep://stockquoteserver.example.com:1026

then DNS gets queried for the A RRs of that domain name, and the port number gets used directly 💅

if the authority has a domain name and no port number, like this:

soap.beep://stockquoteserver.example.com

then the SRV algorithm[11] gets used, with a service parameter of soap-beep and a protocol parameter of tcp, to figure out the IP/TCP addressing info ✨ if there are no matching SRV RRs (for example, _soap-beep._tcp.stockquoteserver.example.com), then DNS gets queried for the A RRs of the domain name instead, and the port number is whatever IANA assigned for the registration in Section 7.4 🎀

if the authority has an IP address, like this:

soap.beep://10.0.0.2:1026

then DNS doesn't get queried at all, and the IP address is used directly 🦋 if a port number is there, it gets used directly too. if not, the port number is whatever IANA assigned for the registration in Section 7.4 💖

now, using literal IPv6 addresses in URLs is discouraged 🙈 but if you do use one in a soap.beep URL, it must conform to the syntax in [12] 🫶

5.2 The soap.beeps URL Scheme 🔐

soap.beeps is basically identical to soap.beep from Section 5.1 in every way, with one big exception 💅 before you start the BEEP profile for SOAP, the BEEP session must be tuned for privacy 🌸 also, both schemes use the exact same address resolution algorithms and parameters from Section 5.1.1 (same SRV service name, same TCP port number, and so on) 🧚

there are two ways to do privacy tuning on a BEEP session, either:

  • a transport security profile gets successfully started; or,
  • a user authentication profile that supports transport security gets successfully started.

either way, once negotiation finishes, a tuning reset happens and both BEEP peers send a new greeting 🦋 if you want an example of a BEEP peer choosing different greetings depending on whether privacy is in use, check out Section 3 of [2] 👑

6. Registration Templates 🎀

6.1 SOAP Profile Feature Registration Template 🍓

when a feature for the BEEP profile for SOAP gets registered, you need to supply this info:

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.

7. Initial Registrations 🌈

7.1 Registration: The SOAP Profile 💜

here's the registration for the SOAP profile, all the juicy details ✨

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 <eamon.otuathail@clipcode.com>,
   Marshall Rose <mrose@dbc.mtview.ca.us>

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 <eamon.otuathail@clipcode.com>,
   Marshall Rose <mrose@dbc.mtview.ca.us>

Author/Change controller: the IESG

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 <eamon.otuathail@clipcode.com>,
   Marshall Rose <mrose@dbc.mtview.ca.us>

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 <eamon.otuathail@clipcode.com>,
   Marshall Rose <mrose@dbc.mtview.ca.us>

Copyright (C) The Internet Society (2002). All Rights Reserved.

Okay, bestie, the legal part, but make it cute 💅 Anyone can copy and share this document, including translations, and write derivative works that comment on it, explain it, or help people implement it. You can publish, copy, and distribute those, in whole or in part, with no restrictions of any kind, as long as the copyright notice and this paragraph appear on every copy and derivative work. 🌸

The document itself can't be modified in any way, though. You can't remove the copyright notice or the references to the Internet Society or other Internet organizations. There are two exceptions: you can change it for developing Internet standards, but then the copyright procedures in the Internet Standards process must be followed, or you can translate it into languages other than English. 🧚

The permissions above are perpetual, and the Internet Society or its successors or assigns won't revoke them. ✨

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 🫶

Right now, the Internet Society is the one funding the RFC Editor function. 🌈

📦 where this page comes from