SOAP-over-CoAP Binding
draft-moritz-core-soap-over-coap-00

Abstract

The scope of this document is to provide a basis for a lightweight SOAP over CoAP binding, to allow usage of SOAP Web services also in resource constrained networks.

Status of this Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. This document may not be modified, and derivative works of it may not be created, and it may not be published except as an Internet-Draft.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

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

This Internet-Draft will expire on July 30, 2011.

Copyright Notice

Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

1.  Introduction
    1.1.  Motivation
    1.2.  Requirements Language
    1.3.  Terminology and Definitions
    1.4.  Requirements
2.  Use of CoAP
    2.1.  CoAP Content-Type
3.  Binding Name
4.  Transport Layer Binding
    4.1.  Source Address and Port
5.  Addressing
    5.1.  URI Scheme
    5.2.  Destination Addressing
6.  Message Patterns
    6.1.  Request response
    6.2.  Retransmission
7.  CoAP Header Options
    7.1.  Unicast one-way
    7.2.  Unicast request-response
8.  IANA Considerations
9.  Security Considerations
10.  References
    10.1.  Normative References
    10.2.  Informative References
§  Author's Address

1.  Introduction

The intention of this document is to provide a basic approach for a SOAP-over-CoAP binding. Readers of this document should be basically familiar with the CoAP draft [I‑D.ietf‑core‑coap] (Shelby, Z., Hartke, K., Bormann, C., and B. Frank, “Constrained Application Protocol (CoAP),” January 2011.), SOAP [W3C.REC‑soap12‑part0‑20070427] (Mitra, N. and Y. Lafon, “SOAP Version 1.2 Part 0: Primer (Second Edition),” April 2007.), SOAP HTTP Binding [W3C.REC‑soap12‑part1‑20070427] (Gudgin, M., Karmarkar, A., Nielsen, H., Hadley, M., Mendelsohn, N., Lafon, Y., and J. Moreau, “SOAP Version 1.2 Part 1: Messaging Framework (Second Edition),” April 2007.) and SOAP UDP binding specifications [SOAP‑over‑UDP] (Jeyaraman, “OASIS SOAP-over-UDP Version 1.1,” 2009.). Parts of this document are derived from these existing specifications. This document will not provide a comprehensive specification, but may be a basis for further discussions and to identify required changes in the current CoAP [I‑D.ietf‑core‑coap] (Shelby, Z., Hartke, K., Bormann, C., and B. Frank, “Constrained Application Protocol (CoAP),” January 2011.) protocol design which is on the way to become an IETF standard. These changes might not be identified directly as the binding described herein will not exploit from all features of CoAP but use CoAP as an 'application layer transport protocol' as SOAP already does with HTTP [W3C.REC‑soap12‑part1‑20070427] (Gudgin, M., Karmarkar, A., Nielsen, H., Hadley, M., Mendelsohn, N., Lafon, Y., and J. Moreau, “SOAP Version 1.2 Part 1: Messaging Framework (Second Edition),” April 2007.).

1.1.  Motivation

The motivation behind this document is based on the initial I-D [I‑D.moritz‑6lowapp‑dpws‑enhancements] (Moritz, G., “DPWS for 6LoWPAN,” June 2010.) and the resulting discussions. The described binding herein is a major enabler for the efforts towards usage of SOAP Web services for highly resource constrained devices like wireless sensor nodes. As core protocol the OASIS Devices Profile for Web Services (DPWS) [DPWS] (Driscoll and Mensch, “OASIS Devices Profile for Web Services (DPWS) Version 1.1,” 2009.) is applied. By combining DPWS with EXI, message size can be reduced significantly as presented in [I‑D.moritz‑6lowapp‑dpws‑enhancements] (Moritz, G., “DPWS for 6LoWPAN,” June 2010.). By providing a binding of SOAP to CoAP, the message overhead can be reduced significantly. Furthermore, SOAP is not required to use inappropriate mechanisms like TCP congestion control. Reliably messaging is guaranteed by CoAP internal mechanisms and thus expensive retransmissions independent of successful or unsuccessful delivery as required by the SOAP-over-UDP binding are avoided. In summary, the major advantages are:

• more compact message format
• probably lower message parsing efforts compared to standard HTTP headers
• avoid inappropriate TCP usage implied by SOAP-over-HTTP binding
• avoid unreliable nature of unicast SOAP-over-UDP binding

1.2.  Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

1.3.  Terminology and Definitions

Defined below are the basic definitions for the terms used in this specification.

Receiver

The endpoint terminating a SOAP/CoAP message

Sender

The endpoint originating a SOAP/CoAP message

SOAP/CoAP message

A CoAP message containing a SOAP envelope in the CoAP message body

This specification uses the constructs [action], [destination], [message id], [reply endpoint], [address] as defined by in WS-Addressing [W3C.PR‑ws‑addr‑core‑20060321] (Gudgin, M., Hadley, M., and T. Rogers, “Web Services Addressing 1.0 - Core,” March 2006.).

The SOAP CoAP Binding is optional and SOAP nodes are not required to implement it. A SOAP node that correctly and completely implements the SOAP CoAP Binding may to be said to 'conform to the CoAP Binding.'

1.4.  Requirements

This specification intends to meet the following requirements:

• Support a one-way message-exchange pattern (MEP) where a SOAP envelope is carried in a CoAP message from Sender to Receiver only.
• Support a request-response message-exchange pattern (MEP) where SOAP envelopes are carried in CoAP messages from Sender to Receiver and back from the origin Receiver to the origin Sender.

Even if reasonable, supporting multicast transmissions of SOAP envelopes carried in CoAP messages are out of scope of this version of this document and require further research. This binding supports SOAP 1.2 [W3C.REC‑soap12‑part0‑20070427] (Mitra, N. and Y. Lafon, “SOAP Version 1.2 Part 0: Primer (Second Edition),” April 2007.) Envelopes. Supporting SOAP 1.1 envelopes is out of scope but might be added in future versions of this document.

Messages conforming to either SOAP specification can use this binding. This specification relies on WS-Addressing. The SOAP envelope MUST use the mechanisms defined in WS-Addressing [W3C.PR‑ws‑addr‑core‑20060321] (Gudgin, M., Hadley, M., and T. Rogers, “Web Services Addressing 1.0 - Core,” March 2006.).

2.  Use of CoAP

This binding of SOAP to CoAP is intended to make appropriate use of CoAP as an application protocol. For example, successful and failure responses are indicated by the appropriated CoAP response codes (e.g. 2xx, 4xx, 5xx). This binding is not intended to fully exploit the features of CoAP, but rather to use CoAP specifically for the purpose of communicating with other SOAP nodes implementing the same binding.

2.1.  CoAP Content-Type

Conforming implementations of this binding:

• MAY be capable of sending and receiving SOAP/CoAP messages serialized using media type 'application/soap+xml'.
• MAY be capable of sending and receiving SOAP/CoAP messages serialized using media type 'application/exi'.
• MUST send requests and responses using such media types provide for at least the transfer of SOAP XML Infoset, including 'application/soap+xml' and 'application/exi'.

A SOAP/CoAP message MUST contain the CoAP Content-type Identifies Option and MUST contain a value which satisfies the three points above.

Note: CoAP has no header option which corresponds to HTTP Accept. Thus the web methods known from the HTTP binding is not possible. In the current CoAP draft only view information are available how to define own header fields.

3.  Binding Name

This binding is identified by the URI (see SOAP 1.2 Part 1 [W3C.REC‑soap12‑part1‑20070427] (Gudgin, M., Karmarkar, A., Nielsen, H., Hadley, M., Mendelsohn, N., Lafon, Y., and J. Moreau, “SOAP Version 1.2 Part 1: Messaging Framework (Second Edition),” April 2007.) SOAP Protocol Binding Framework): http://www.ws4d.org/2011/01/soap/bindings/CoAP/

Note: The binding name is tentative but required to indicate the corresponding binding e.g. in the WSDL of a service.

4.  Transport Layer Binding

The CoAP binding MUST operate over UDP transport layer.

Note: CoAP defines a maximum message size which refers to the IP layer. The existing UDP binding instead refers only to UDP and defines a general maximum packet size independent of IP.

4.1.  Source Address and Port

The source address MUST be supplied at the IP packet level and MUST be the IPv4 address (limited to unicast addresses) or IPv6 address (limited to unicast addresses) of the sender; the receiver SHOULD reject IP packets containing a SOAP/CoAP message that have inappropriate values for the source address.

Even though CoAP is intended to be used on the well-known ports defined in CoAP-04, the use of CoAP is not limited to these ports. As a result, it is possible to have a dedicated CoAP server for handling SOAP processing on a distinct port.

5.  Addressing

5.1.  URI Scheme

The SOAP CoAP binding defines a base URI according to the rules in CoAP-04. I.e., the base URI is the CoAP Request-URI or the value of the CoAP Location option field.

5.2.  Destination Addressing

WS-Addressing defines a URI, 'http://www.w3.org/2005/08/addressing/anonymous', that can appear in the [address] property of an endpoint reference. If the [reply endpoint] property of a SOAP message transmitted over CoAP has an [address] property with this value, the UDP source address (and source port) is considered to be the address to which reply messages should be sent.

The implied value of the [reply endpoint] property for SOAP messages transmitted over CoAP is an endpoint reference with an [address] property whose value is 'http://www.w3.org/2005/08/addressing/anonymous'.

6.  Message Patterns

This specification supports the following message patterns:

• Unicast one-way
• Unicast request, unicast response

as described in the remainder of this section. All SOAP/CoAP messages MUST use the POST method of CoAP, whereby POST is interpreted in accordance to RFC2616.

Note: In the current draft of CoAP-04, response Code 2.00 OK is only possible for GET methods. But GET is not the appropriate method for this binding.

Note: There is no Action field similar to SOAPAction in HTTP, so extensions are required to the basic CoAP Options. Hence the web method feature of the HTTP binding cannot be made possible.

CoAP defines Proxy mechanism for caching of responses. Because the CoAP binding defined herein is intended for service communication and not RESTful resource manipulation, caching should be avoided. CoAP defines the Max-Age option to be default a non-zero value. Hence each SOAP/CoAP message MUST contain the Max-Age option and the value MUST be zero.

6.1.  Request response

To match a request with a response the CoAP Token Option can be used. The CoAP Token Option SHOULD be carried in all request-response SOAP/CoAP messages. WS-Addressing defines the [message id] property to identify messages in time and space and to match requests with response. In case of using the CoAP/SOAP binding the [message id] property is SHOULD be empty and MUST contain a value in case if the CoAP Token Option is not present.

Note: The intention of this paragraph is to reduce message size. The [message id] property has a typical size of 45 Bytes and cannot by compressed by knowledge based encodings like EXI because the value of this property is unique in each message. The CoAP Token Option may be much more compact by providing the same functionality.

CoAP defines the feature of deferred responses where a transaction ACK is sent as response to a CON message to indicate a deferred response. If the value of the [reply endpoint] of the request is 'http://www.w3.org/2005/08/addressing/anonymous', the ACK message SHOULD NOT carry any payload (e.g. a SOAP Envelope) in the CoAP message body if not required by the application logic. If the value of the [reply endpoint] is not 'http://www.w3.org/2005/08/addressing/anonymous', the origin Receiver cannot guarantee that the response is intended to be sent to the same entity like the client and SHOULD include a SOAP Envelope providing details of the request for the entity behind the [reply endpoint].

6.2.  Retransmission

To avoid repeated packet collisions, any retransmission implementation SHOULD observe good practices such as using exponential back-off algorithms and spreading. An implementation SHOULD use the Confirmable (CON) transaction message mechanism described in the CoAP specification to avoid unnecessary retransmissions. For each transmission of such a message, the value of the [message id] property and the CoAP Token Option MUST be the same.

Note: WS-Event Delivery should not use CON due to ACK flood at Event Source. Multicast messages also should use NON messages. Not sure if such requirements are in scope of this document.

7.  CoAP Header Options

In this section, the CoAP header and CoAP header options usage is described in detail.

7.1.  Unicast one-way

The unicast one-way message pattern consists of only one request without a response. Due to the CoAP binding the request consists of one CoAP transaction. If CoAP Confirmable messaging is used, an empty CoAP ACK message must be send back to the origin sender to indicate success or failure.

The request is formulated according to the table below, but can be extended for application specific needs.

If the request is send as Non-Confirmable CoAP message, no response is send back to the origin requester. If the request is a Confirmable CoAP message, the response consists only of a CoAP ACK without any data in the CoAP message body. In case of a Conformable CoAP request the response is formulated according to the table below, but can be extended for application specific needs.

Application developers must be aware that the one-way message exchange patterns returns neither failure nor success messages if Non-Confirmable messages are used.

7.2.  Unicast request-response

The unicast request-response message pattern consists of one request and one response. Due to the CoAP binding the request consists of one or more CoAP transactions.

The request is formulated according to the table below, but can be extended for application specific needs.

If the request is send as Non-Confirmable CoAP message, no CoAP ACK is send back to the origin requester. In this case, for the response, the origin Receiver has to initiate a new CoAP transaction which can be either Non-Confirmable or Confirmable.

If the request is a Confirmable CoAP message, the response consists of a CoAP ACK which may carry the response SOAP envelope as data in the CoAP message body. For the response, the origin receiver may also initiate a new CoAP transaction after sending the CoAP ACK to the origin Sender, which can be either also Non-Confirmable or Confirmable. (see deferred responses in CoAP)

8.  IANA Considerations

No IANA issues have been identified in this draft.

9.  Security Considerations

Will be added in future versions.

10.  References

10.1. Normative References

10.2. Informative References

Author's Address