idnits 2.17.1 draft-moritz-core-soap-over-coap-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- -- The document has an IETF Trust Provisions (28 Dec 2009) Section 6.c(ii) Publication Limitation clause. If this document is intended for submission to the IESG for publication, this constitutes an error. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 17, 2011) is 4691 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'DPWS' is defined on line 498, but no explicit reference was found in the text == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-06 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CORE G. Moritz, Ed. 3 Internet-Draft University of Rostock 4 Intended status: Informational June 17, 2011 5 Expires: December 19, 2011 7 SOAP-over-CoAP Binding 8 draft-moritz-core-soap-over-coap-01 10 Abstract 12 The scope of this document is to provide the basis for a lightweight 13 SOAP over CoAP binding. By the binding described in this document, 14 SOAP Web services can also be used in resource constrained networks. 16 Status of this Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. This document may not be modified, 20 and derivative works of it may not be created, and it may not be 21 published except as an Internet-Draft. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on December 19, 2011. 35 Copyright Notice 37 Copyright (c) 2011 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.2. Requirements Language . . . . . . . . . . . . . . . . . . 3 55 1.3. Terminology and Definitions . . . . . . . . . . . . . . . 4 56 1.4. Requirements . . . . . . . . . . . . . . . . . . . . . . . 4 57 2. Use of CoAP . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 2.1. CoAP Media Types . . . . . . . . . . . . . . . . . . . . . 5 59 3. Binding Name . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 4. Transport Layer Binding . . . . . . . . . . . . . . . . . . . 5 61 4.1. Source Address and Port . . . . . . . . . . . . . . . . . 6 62 5. Addressing . . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 5.1. URI Scheme . . . . . . . . . . . . . . . . . . . . . . . . 6 64 5.2. Destination Addressing . . . . . . . . . . . . . . . . . . 6 65 6. Message Patterns . . . . . . . . . . . . . . . . . . . . . . . 6 66 6.1. Request response . . . . . . . . . . . . . . . . . . . . . 7 67 6.2. Retransmission . . . . . . . . . . . . . . . . . . . . . . 8 68 7. CoAP Header Options . . . . . . . . . . . . . . . . . . . . . 8 69 7.1. Unicast one-way . . . . . . . . . . . . . . . . . . . . . 8 70 7.2. Unicast request-response . . . . . . . . . . . . . . . . . 10 71 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 72 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 73 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 74 10.1. Normative References . . . . . . . . . . . . . . . . . . . 11 75 10.2. Informative References . . . . . . . . . . . . . . . . . . 12 76 Appendix A. Changelog . . . . . . . . . . . . . . . . . . . . . . 12 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 79 1. Introduction 81 The intention of this document is to provide the basic approach for a 82 SOAP-over-CoAP binding. Readers of this document should be basically 83 familiar with the CoAP draft [I-D.ietf-core-coap], SOAP 84 [W3C.REC-soap12-part0-20070427], the SOAP HTTP binding 85 [W3C.REC-soap12-part1-20070427] and the SOAP UDP binding 86 [SOAP-over-UDP]. Parts of this document are derived from these 87 existing specifications. This document will not provide a 88 comprehensive specification. It may be used as basis for further 89 discussions and to identify required changes in the current CoAP 90 [I-D.ietf-core-coap] protocol design, which is on the way to become 91 an IETF standard. This binding does not exploit from all features of 92 CoAP, but uses CoAP as an application layer transport mechanism for 93 SOAP envelopes. 95 1.1. Motivation 97 The motivation behind this document is based on the initial I-D 98 [I-D.moritz-6lowapp-dpws-enhancements] and the resulting discussions. 99 By combining SOAP with EXI, message size can be reduced significantly 100 as presented in [I-D.moritz-6lowapp-dpws-enhancements]. Beside EXI, 101 the herein described binding is the second major enabler towards 102 usage of SOAP Web services in highly resource constrained 103 environments. By implementing this binding, SOAP Web services are 104 not required to use inappropriate mechanisms like TCP handshakes and 105 congestion control implied by the existing SOAP-over-HTTP binding. 106 But in contrast to the existing standard SOAP-over-UDP binding, 107 reliably messaging is guaranteed by the SOAP-over-CoAP binding 108 through CoAP internal mechanisms. In summary the major advantages 109 are: 111 o more compact (binary) message format compared to SOAP-over-HTPP 112 binding 114 o probably lower message parsing efforts compared to standard HTTP 115 headers 117 o avoid inappropriate TCP usage implied by SOAP-over-HTTP binding 119 o avoid unreliable nature of the SOAP-over-UDP binding 121 1.2. Requirements Language 123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 125 document are to be interpreted as described in RFC 2119 [RFC2119]. 127 1.3. Terminology and Definitions 129 Defined below are the basic definitions for the terms used in this 130 specification. 132 SOAP/CoAP message 133 A CoAP message containing a SOAP envelope in the CoAP message 134 body 136 Receiver 137 The endpoint terminating a SOAP/CoAP message 139 Sender 140 The endpoint originating a SOAP/CoAP message 142 This specification uses the constructs [action], [destination], 143 [message id], [reply endpoint], [address] as defined in WS-Addressing 144 [W3C.PR-ws-addr-core-20060321]. 146 The SOAP CoAP Binding is optional and SOAP nodes are not required to 147 implement it. A SOAP node that correctly and completely implements 148 the SOAP CoAP Binding may to be said to 'conform to the CoAP 149 Binding.' 151 1.4. Requirements 153 This specification intends to meet the following requirements: 155 o Support a one-way message-exchange pattern (MEP) where a SOAP 156 envelope is carried in a CoAP message from Sender to Receiver 157 only. 159 o Support a request-response message-exchange pattern (MEP) where 160 SOAP envelopes are carried in CoAP messages from Sender to 161 Receiver and back from the origin Receiver to the origin Sender. 163 Even if supported by CoAP, supporting multicast transmissions of SOAP 164 envelopes carried in CoAP messages are out of scope of this version 165 of this document and require further research. For such multicast 166 messages, the existing SOAP-over-UDP binding may be sufficient. 168 This binding supports SOAP 1.2 [W3C.REC-soap12-part0-20070427] 169 envelopes. Supporting SOAP 1.1 envelopes is out of scope but might 170 be added in future versions of this document. 172 This specification relies on WS-Addressing. The SOAP envelope MUST 173 use the mechanisms defined in WS-Addressing 174 [W3C.PR-ws-addr-core-20060321]. 176 Note: CoAP has no header option which corresponds to HTTP Accept and 177 the existing SOAPAction HTTP header extension field. Thus the web 178 methods feature known from the HTTP binding is not possible. In the 179 current CoAP draft only few information are available how to define 180 own header fields. 182 2. Use of CoAP 184 This binding of SOAP to CoAP is intended to make appropriate use of 185 CoAP as an application protocol. For example, successful and failure 186 responses are indicated by the corresponding CoAP response codes 187 (e.g. 2.xx, 4.xx, 5.xx). This binding is not intended to fully 188 exploit the features of CoAP, but rather to use CoAP specifically for 189 the purpose of communicating with other SOAP nodes implementing the 190 same binding. 192 2.1. CoAP Media Types 194 Conforming implementations of this binding: 196 o MAY be capable of sending and receiving SOAP/CoAP messages 197 serialized using media type 'application/xml'. 199 o MAY be capable of sending and receiving SOAP/CoAP messages 200 serialized using media type 'application/exi'. 202 o MUST be capable of sending and receiving SOAP/CoAP messages using 203 such media types providing for at least the transfer of SOAP XML 204 Infoset, including 'application/xml' and 'application/exi'. 206 A SOAP/CoAP message MUST contain the CoAP Content-Type option. This 207 option MUST contain a value which satisfies the three points above. 209 3. Binding Name 211 This binding is identified by the URI (see SOAP 1.2 Part 1 212 [W3C.REC-soap12-part1-20070427] SOAP Protocol Binding Framework): 213 http://www.ws4d.org/2011/06/soap/bindings/CoAP/ 215 Note: The binding name is tentative but required to indicate the 216 corresponding binding e.g. in the WSDL of a service. 218 4. Transport Layer Binding 220 The CoAP binding MUST operate over UDP transport layer. 222 Note: CoAP defines a maximum message size which refers to the IP 223 layer. The existing SOAP-over-UDP binding instead refers only to UDP 224 and defines a general maximum packet size independent of the IP 225 layer. Hence, it might be required to define the CoAP Block 226 mechanism as mandatory as follows: Endpoints which support only 227 messages serialized using the media type 'application/xml' SHOULD 228 implement CoAP Block. 230 4.1. Source Address and Port 232 The source address MUST be supplied at the IP packet level and MUST 233 be the IPv4 address (limited to unicast addresses) or IPv6 address 234 (limited to unicast addresses) of the sender; the receiver SHOULD 235 reject IP packets containing a SOAP/CoAP message that have 236 inappropriate values for the source address. 238 Even though CoAP is intended to be used on the well-known ports as 239 defined in CoAP, the use of CoAP is not limited to these ports. As a 240 result, it is possible to have a dedicated CoAP server for handling 241 SOAP processing on a distinct port. 243 5. Addressing 245 5.1. URI Scheme 247 The SOAP CoAP binding defines a base URI according to the rules in 248 CoAP. I.e., the base URI is the CoAP Request-URI options. 250 5.2. Destination Addressing 252 WS-Addressing defines a URI, 253 'http://www.w3.org/2005/08/addressing/anonymous', that can appear in 254 the [address] property of an endpoint reference. If the [reply 255 endpoint] property of a SOAP message transmitted over CoAP has an 256 [address] property with this value, the UDP source address (and 257 source port) is considered to be the address to which reply messages 258 should be sent. 260 In absence, the implied value of the [reply endpoint] property for 261 SOAP messages transmitted over CoAP is an endpoint reference with an 262 [address] property whose value is 263 'http://www.w3.org/2005/08/addressing/anonymous'. 265 6. Message Patterns 267 This specification supports the following message patterns: 269 o Unicast one-way 271 o Unicast request, unicast response 273 as described in the remainder of this section. 275 All SOAP/CoAP messages MUST use the POST method of CoAP. In the 276 response, success SHOULD be indicated by the response code '2.04 277 Changed'. This changes the original meaning of the response code and 278 is only valid for this SOAP-over-CoAP binding. 280 Note: In the current draft of CoAP-06, POST allows no payload in the 281 response. This will be changed in future versions of the CoAP draft. 283 Note: The CoAP draft is very strict in how each response code must be 284 interpreted. Since there is no generic code similar to '200 OK' of 285 HTTP, an existing response code must be adapted to conform to this 286 binding. The code might be changed after the adaptations of CoAP to 287 allow payload in POST requests and responses. Further details are 288 required how to map the response codes at a HTTP/CoAP proxy to 289 conform to this binding. 291 Note: There is no CoAP Action option similar to SOAPAction in HTTP. 292 Hence the web method feature of the HTTP binding cannot be made 293 possible without extensions of CoAP. 295 Note: CoAP defines Proxy mechanism for caching of responses. Because 296 the CoAP binding defined herein is intended for SOAP transport and 297 not RESTful resource manipulation, caching should be avoided. CoAP 298 defines the Max-Age option to be default a non-zero value. But the 299 POST method is already not cachable. Hence, it is not required by a 300 SOAP/CoAP message to contain the Max-Age option with a value of zero. 302 6.1. Request response 304 To match a request with a response, the CoAP Token Option can be 305 used. The CoAP Token Option SHOULD be carried in all request- 306 response SOAP/CoAP messages. WS-Addressing defines the [message id] 307 property to identify messages in time and space and also to match 308 requests with response. In case of using the SOAP/CoAP binding, the 309 [message id] property SHOULD be empty and MUST contain a value in 310 case if the CoAP Token Option is not present. 312 Note: The intention of this paragraph is to reduce message size. The 313 [message id] property has a typical size of 45 Bytes and cannot by 314 compressed by knowledge based encodings like EXI, because the value 315 of this property is unique for each request/response. The CoAP Token 316 Option may be much more compact by providing the same functionality. 318 CoAP defines the feature of 'separeated responses' (c.f. piggy backed 319 response). The ACK message of a separated response SHOULD NOT carry 320 any payload (e.g. a SOAP Envelope) in the CoAP message body. If the 321 value of the [reply endpoint] is not 322 'http://www.w3.org/2005/08/addressing/anonymous', the origin Receiver 323 cannot guarantee that the response is intended to be sent to the same 324 entity like the origin Sender and SHOULD include the origin Token 325 Option value in the ACK of the separated response to provide details 326 of the request for the entity behind the [reply endpoint]. 328 6.2. Retransmission 330 To avoid repeated packet collisions, any retransmission 331 implementation SHOULD observe good practices such as using 332 exponential back-off algorithms and spreading. An implementation 333 SHOULD use the Confirmable (CON) transaction message mechanism 334 described in the CoAP specification to avoid unnecessary 335 retransmissions. For each transmission of such a message, the value 336 of the [message id] property and the CoAP Token Option MUST be the 337 same. 339 Note: WS-Event Delivery should not use CON due to ACK flood at Event 340 Source. Multicast messages also should use NON messages. Because 341 this specification focuses SOAP in general, it is not sure if such 342 requirements are in scope of this document. 344 7. CoAP Header Options 346 In this section, the CoAP header and CoAP header options usage is 347 described in detail. 349 7.1. Unicast one-way 351 The unicast one-way message pattern consists one complete CoAP 352 request/response, which again can be seperated in different CoAP 353 message exchanges. Only the request carries a SOAP envelope in the 354 message body while the response message body is empty. 356 The request is formulated according to the table below, but can be 357 extended for application specific needs. 359 +--------------+----------------------------------------------------+ 360 | CoAP header | Value | 361 | option | | 362 +--------------+----------------------------------------------------+ 363 | CoAP Method | POST is the only supported method of this binding. | 364 | Request URI | The request URI confirming a CoAP URI and | 365 | | identifying the WS-Addressing [address] endpoint | 366 | | property (network address). If the value of the | 367 | | WS-Addressing [address] endpoint property is | 368 | | 'http://www.w3.org/2005/08/addressing/anonymous' | 369 | | (directly set or implied by an empty [address] | 370 | | property), the CoAP Uri-Path Option and the CoAP | 371 | | Uri-Query Option are empty. | 372 | Token Option | Token in accordance to CoAP specification to match | 373 | | the request/response in time and space. | 374 | Content-type | Media type of CoAP message body. | 375 | Option | | 376 | CoAP message | SOAP message serialized according to the rules for | 377 | body | carrying SOAP messages in the media type given by | 378 | | the Content-type Option. | 379 +--------------+----------------------------------------------------+ 381 Table 1: Unicast one-way Request 383 The response is formulated according to the table below, but can be 384 extended for application specific needs. 386 +---------+---------------------------------------------------------+ 387 | CoAP | Value | 388 | header | | 389 | option | | 390 +---------+---------------------------------------------------------+ 391 | CoAP | Status Code in accordance to codes defined in CoAP and | 392 | Status | in this binding. Note: CoAP describes only a subset of | 393 | Code | HTTP status codes and adds own codes. This requires | 394 | | further alignment. | 395 | Token | Token in accordance to CoAP specification to match the | 396 | Option | request/response in time and space. | 397 | CoAP | MUST NOT be included in the one-way message pattern. | 398 | message | | 399 | body | | 400 +---------+---------------------------------------------------------+ 402 Table 2: Unicast one-way Response 404 7.2. Unicast request-response 406 The unicast request-response message pattern consists one complete 407 CoAP request/response, which again can be seperated in different CoAP 408 message exchanges. Both request and response cary a SOAP envelope in 409 the message body. 411 The request is formulated according to the table below, but can be 412 extended for application specific needs. 414 +--------------+----------------------------------------------------+ 415 | CoAP | Value | 416 | field/header | | 417 | option | | 418 +--------------+----------------------------------------------------+ 419 | CoAP Method | POST is the only supported method of this binding. | 420 | Request URI | The request URI confirming a CoAP URI and | 421 | | identifying the WS-Addressing [address] endpoint | 422 | | property (network address). If the value of the | 423 | | WS-Addressing [address] endpoint property is | 424 | | 'http://www.w3.org/2005/08/addressing/anonymous' | 425 | | (directly set or implied by an empty [address] | 426 | | property), the CoAP Uri-Path Option and the CoAP | 427 | | Uri-Query Option are empty. | 428 | Content-type | Media type of CoAP message body. | 429 | Option | | 430 | Token Option | Token in accordance to CoAP specification to match | 431 | | the request/response in time and space. | 432 | CoAP message | SOAP message serialized according to the rules for | 433 | body | carrying SOAP messages in the media type given by | 434 | | the Content-type Option. | 435 +--------------+----------------------------------------------------+ 437 Table 3: Unicast request-response Request 439 If the request is a Confirmable CoAP message, the response consists 440 of a CoAP ACK which may carry the response SOAP envelope as data in 441 the CoAP message body. For the response, the origin receiver may 442 also initiate a new CoAP transaction after sending the CoAP ACK to 443 the origin Sender, which can be either also Non-Confirmable or 444 Confirmable. (see separated vs. piggy backed responses in CoAP) 445 +--------------+----------------------------------------------------+ 446 | CoAP | Value | 447 | field/header | | 448 | option | | 449 +--------------+----------------------------------------------------+ 450 | CoAP Status | Status Code in accordance to codes defined in CoAP | 451 | Code | and in this binding. Note: CoAP describes only a | 452 | | subset of HTTP status codes and adds own codes. | 453 | | This requires further alignment. | 454 | Content-type | Media type of CoAP message body. | 455 | Option | | 456 | Token Option | Token in accordance to CoAP specification to match | 457 | | the request/response in time and space. | 458 | CoAP message | SOAP message serialized according to the rules for | 459 | body | carrying SOAP messages in the media type given by | 460 | | the Content-type Option. | 461 +--------------+----------------------------------------------------+ 463 Table 4: Unicast request-response Response 465 8. IANA Considerations 467 No IANA issues have been identified in this draft. 469 9. Security Considerations 471 Will be added in future versions. 473 10. References 475 10.1. Normative References 477 [I-D.ietf-core-coap] 478 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 479 "Constrained Application Protocol (CoAP)", 480 draft-ietf-core-coap-06 (work in progress), May 2011. 482 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 483 Requirement Levels", BCP 14, RFC 2119, March 1997. 485 [W3C.PR-ws-addr-core-20060321] 486 Gudgin, M., Hadley, M., and T. Rogers, "Web Services 487 Addressing 1.0 - Core", W3C PR PR-ws-addr-core-20060321, 488 March 2006. 490 [W3C.REC-soap12-part0-20070427] 491 Mitra, N. and Y. Lafon, "SOAP Version 1.2 Part 0: Primer 492 (Second Edition)", World Wide Web Consortium 493 Recommendation REC-soap12-part0-20070427, April 2007, 494 . 496 10.2. Informative References 498 [DPWS] Driscoll and Mensch, "OASIS Devices Profile for Web 499 Services (DPWS) Version 1.1", 2009, 500 . 502 [I-D.moritz-6lowapp-dpws-enhancements] 503 Moritz, G., "DPWS for 6LoWPAN", 504 draft-moritz-6lowapp-dpws-enhancements-01 (work in 505 progress), June 2010. 507 [SOAP-over-UDP] 508 Jeyaraman, "OASIS SOAP-over-UDP Version 1.1", 2009, . 512 [W3C.REC-soap12-part1-20070427] 513 Nielsen, H., Hadley, M., Karmarkar, A., Lafon, Y., 514 Mendelsohn, N., Moreau, J., and M. Gudgin, "SOAP Version 515 1.2 Part 1: Messaging Framework (Second Edition)", World 516 Wide Web Consortium Recommendation REC-soap12-part1- 517 20070427, April 2007, 518 . 520 Appendix A. Changelog 522 Changed from soap-over-coap-00 to soap-over-coap-01: 524 o Updated to coap-06 526 o Changed behavior of one-way MEP 528 o Added response code considerations 530 o Updated CoAP header option usage 532 o Changed caching considerations 534 o Editorial updates 536 Author's Address 538 Guido Moritz (editor) 539 University of Rostock 540 18051 Rostock, 541 Germany 543 Phone: +49 381 498 7269 544 Email: guido.moritz@uni-rostock.de