idnits 2.17.1 draft-moritz-core-soap-over-coap-00.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 (January 26, 2011) is 4832 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-04 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CORE G. Moritz 3 Internet-Draft University of Rostock 4 Intended status: Informational January 26, 2011 5 Expires: July 30, 2011 7 SOAP-over-CoAP Binding 8 draft-moritz-core-soap-over-coap-00 10 Abstract 12 The scope of this document is to provide a basis for a lightweight 13 SOAP over CoAP binding, to allow usage of SOAP Web services also in 14 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 July 30, 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 . . . . . . . . . . . . . . . . . . 4 55 1.3. Terminology and Definitions . . . . . . . . . . . . . . . 4 56 1.4. Requirements . . . . . . . . . . . . . . . . . . . . . . . 4 57 2. Use of CoAP . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 2.1. CoAP Content-Type . . . . . . . . . . . . . . . . . . . . 5 59 3. Binding Name . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 4. Transport Layer Binding . . . . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . . . . . . . . . . . . . 7 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 . . . . . . . . . . . . . . . . . . . . . 12 72 9. Security Considerations . . . . . . . . . . . . . . . . . . . 12 73 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 74 10.1. Normative References . . . . . . . . . . . . . . . . . . . 12 75 10.2. Informative References . . . . . . . . . . . . . . . . . . 12 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 78 1. Introduction 80 The intention of this document is to provide a basic approach for a 81 SOAP-over-CoAP binding. Readers of this document should be basically 82 familiar with the CoAP draft [I-D.ietf-core-coap], SOAP 83 [W3C.REC-soap12-part0-20070427], SOAP HTTP Binding 84 [W3C.REC-soap12-part1-20070427] and SOAP UDP binding specifications 85 [SOAP-over-UDP]. Parts of this document are derived from these 86 existing specifications. This document will not provide a 87 comprehensive specification, but may be a basis for further 88 discussions and to identify required changes in the current CoAP 89 [I-D.ietf-core-coap] protocol design which is on the way to become an 90 IETF standard. These changes might not be identified directly as the 91 binding described herein will not exploit from all features of CoAP 92 but use CoAP as an 'application layer transport protocol' as SOAP 93 already does with HTTP [W3C.REC-soap12-part1-20070427]. 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 The described binding herein is a major enabler for the efforts 100 towards usage of SOAP Web services for highly resource constrained 101 devices like wireless sensor nodes. As core protocol the OASIS 102 Devices Profile for Web Services (DPWS) [DPWS] is applied. By 103 combining DPWS with EXI, message size can be reduced significantly as 104 presented in [I-D.moritz-6lowapp-dpws-enhancements]. By providing a 105 binding of SOAP to CoAP, the message overhead can be reduced 106 significantly. Furthermore, SOAP is not required to use 107 inappropriate mechanisms like TCP congestion control. Reliably 108 messaging is guaranteed by CoAP internal mechanisms and thus 109 expensive retransmissions independent of successful or unsuccessful 110 delivery as required by the SOAP-over-UDP binding are avoided. In 111 summary, the major advantages are: 113 o more compact message format 115 o probably lower message parsing efforts compared to standard HTTP 116 headers 118 o avoid inappropriate TCP usage implied by SOAP-over-HTTP binding 120 o avoid unreliable nature of unicast SOAP-over-UDP binding 122 1.2. Requirements Language 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 126 document are to be interpreted as described in RFC 2119 [RFC2119]. 128 1.3. Terminology and Definitions 130 Defined below are the basic definitions for the terms used in this 131 specification. 133 Receiver 134 The endpoint terminating a SOAP/CoAP message 136 Sender 137 The endpoint originating a SOAP/CoAP message 139 SOAP/CoAP message 140 A CoAP message containing a SOAP envelope in the CoAP message 141 body 143 This specification uses the constructs [action], [destination], 144 [message id], [reply endpoint], [address] as defined by in WS- 145 Addressing [W3C.PR-ws-addr-core-20060321]. 147 The SOAP CoAP Binding is optional and SOAP nodes are not required to 148 implement it. A SOAP node that correctly and completely implements 149 the SOAP CoAP Binding may to be said to 'conform to the CoAP 150 Binding.' 152 1.4. Requirements 154 This specification intends to meet the following requirements: 156 o Support a one-way message-exchange pattern (MEP) where a SOAP 157 envelope is carried in a CoAP message from Sender to Receiver 158 only. 160 o Support a request-response message-exchange pattern (MEP) where 161 SOAP envelopes are carried in CoAP messages from Sender to 162 Receiver and back from the origin Receiver to the origin Sender. 164 Even if reasonable, supporting multicast transmissions of SOAP 165 envelopes carried in CoAP messages are out of scope of this version 166 of this document and require further research. This binding supports 167 SOAP 1.2 [W3C.REC-soap12-part0-20070427] Envelopes. Supporting SOAP 168 1.1 envelopes is out of scope but might be added in future versions 169 of this document. 171 Messages conforming to either SOAP specification can use this 172 binding. This specification relies on WS-Addressing. The SOAP 173 envelope MUST use the mechanisms defined in WS-Addressing 174 [W3C.PR-ws-addr-core-20060321]. 176 2. Use of CoAP 178 This binding of SOAP to CoAP is intended to make appropriate use of 179 CoAP as an application protocol. For example, successful and failure 180 responses are indicated by the appropriated CoAP response codes (e.g. 181 2xx, 4xx, 5xx). This binding is not intended to fully exploit the 182 features of CoAP, but rather to use CoAP specifically for the purpose 183 of communicating with other SOAP nodes implementing the same binding. 185 2.1. CoAP Content-Type 187 Conforming implementations of this binding: 189 o MAY be capable of sending and receiving SOAP/CoAP messages 190 serialized using media type 'application/soap+xml'. 192 o MAY be capable of sending and receiving SOAP/CoAP messages 193 serialized using media type 'application/exi'. 195 o MUST send requests and responses using such media types provide 196 for at least the transfer of SOAP XML Infoset, including 197 'application/soap+xml' and 'application/exi'. 199 A SOAP/CoAP message MUST contain the CoAP Content-type Identifies 200 Option and MUST contain a value which satisfies the three points 201 above. 203 Note: CoAP has no header option which corresponds to HTTP Accept. 204 Thus the web methods known from the HTTP binding is not possible. In 205 the current CoAP draft only view information are available how to 206 define own header fields. 208 3. Binding Name 210 This binding is identified by the URI (see SOAP 1.2 Part 1 211 [W3C.REC-soap12-part1-20070427] SOAP Protocol Binding Framework): 212 http://www.ws4d.org/2011/01/soap/bindings/CoAP/ 214 Note: The binding name is tentative but required to indicate the 215 corresponding binding e.g. in the WSDL of a service. 217 4. Transport Layer Binding 219 The CoAP binding MUST operate over UDP transport layer. 221 Note: CoAP defines a maximum message size which refers to the IP 222 layer. The existing UDP binding instead refers only to UDP and 223 defines a general maximum packet size independent of IP. 225 4.1. Source Address and Port 227 The source address MUST be supplied at the IP packet level and MUST 228 be the IPv4 address (limited to unicast addresses) or IPv6 address 229 (limited to unicast addresses) of the sender; the receiver SHOULD 230 reject IP packets containing a SOAP/CoAP message that have 231 inappropriate values for the source address. 233 Even though CoAP is intended to be used on the well-known ports 234 defined in CoAP-04, the use of CoAP is not limited to these ports. 235 As a result, it is possible to have a dedicated CoAP server for 236 handling SOAP processing on a distinct port. 238 5. Addressing 240 5.1. URI Scheme 242 The SOAP CoAP binding defines a base URI according to the rules in 243 CoAP-04. I.e., the base URI is the CoAP Request-URI or the value of 244 the CoAP Location option field. 246 5.2. Destination Addressing 248 WS-Addressing defines a URI, 249 'http://www.w3.org/2005/08/addressing/anonymous', that can appear in 250 the [address] property of an endpoint reference. If the [reply 251 endpoint] property of a SOAP message transmitted over CoAP has an 252 [address] property with this value, the UDP source address (and 253 source port) is considered to be the address to which reply messages 254 should be sent. 256 The implied value of the [reply endpoint] property for SOAP messages 257 transmitted over CoAP is an endpoint reference with an [address] 258 property whose value is 259 'http://www.w3.org/2005/08/addressing/anonymous'. 261 6. Message Patterns 263 This specification supports the following message patterns: 265 o Unicast one-way 267 o Unicast request, unicast response 269 as described in the remainder of this section. All SOAP/CoAP 270 messages MUST use the POST method of CoAP, whereby POST is 271 interpreted in accordance to RFC2616. 273 Note: In the current draft of CoAP-04, response Code 2.00 OK is only 274 possible for GET methods. But GET is not the appropriate method for 275 this binding. 277 Note: There is no Action field similar to SOAPAction in HTTP, so 278 extensions are required to the basic CoAP Options. Hence the web 279 method feature of the HTTP binding cannot be made possible. 281 CoAP defines Proxy mechanism for caching of responses. Because the 282 CoAP binding defined herein is intended for service communication and 283 not RESTful resource manipulation, caching should be avoided. CoAP 284 defines the Max-Age option to be default a non-zero value. Hence 285 each SOAP/CoAP message MUST contain the Max-Age option and the value 286 MUST be zero. 288 6.1. Request response 290 To match a request with a response the CoAP Token Option can be used. 291 The CoAP Token Option SHOULD be carried in all request-response SOAP/ 292 CoAP messages. WS-Addressing defines the [message id] property to 293 identify messages in time and space and to match requests with 294 response. In case of using the CoAP/SOAP binding the [message id] 295 property is SHOULD be empty and MUST contain a value in case if the 296 CoAP Token Option is not present. 298 Note: The intention of this paragraph is to reduce message size. The 299 [message id] property has a typical size of 45 Bytes and cannot by 300 compressed by knowledge based encodings like EXI because the value of 301 this property is unique in each message. The CoAP Token Option may 302 be much more compact by providing the same functionality. 304 CoAP defines the feature of deferred responses where a transaction 305 ACK is sent as response to a CON message to indicate a deferred 306 response. If the value of the [reply endpoint] of the request is 307 'http://www.w3.org/2005/08/addressing/anonymous', the ACK message 308 SHOULD NOT carry any payload (e.g. a SOAP Envelope) in the CoAP 309 message body if not required by the application logic. If the value 310 of the [reply endpoint] is not 311 'http://www.w3.org/2005/08/addressing/anonymous', the origin Receiver 312 cannot guarantee that the response is intended to be sent to the same 313 entity like the client and SHOULD include a SOAP Envelope providing 314 details of the request for the entity behind the [reply endpoint]. 316 6.2. Retransmission 318 To avoid repeated packet collisions, any retransmission 319 implementation SHOULD observe good practices such as using 320 exponential back-off algorithms and spreading. An implementation 321 SHOULD use the Confirmable (CON) transaction message mechanism 322 described in the CoAP specification to avoid unnecessary 323 retransmissions. For each transmission of such a message, the value 324 of the [message id] property and the CoAP Token Option MUST be the 325 same. 327 Note: WS-Event Delivery should not use CON due to ACK flood at Event 328 Source. Multicast messages also should use NON messages. Not sure 329 if such requirements are in scope of this document. 331 7. CoAP Header Options 333 In this section, the CoAP header and CoAP header options usage is 334 described in detail. 336 7.1. Unicast one-way 338 The unicast one-way message pattern consists of only one request 339 without a response. Due to the CoAP binding the request consists of 340 one CoAP transaction. If CoAP Confirmable messaging is used, an 341 empty CoAP ACK message must be send back to the origin sender to 342 indicate success or failure. 344 The request is formulated according to the table below, but can be 345 extended for application specific needs. 347 +--------------+----------------------------------------------------+ 348 | CoAP | Value | 349 | field/header | | 350 | option | | 351 +--------------+----------------------------------------------------+ 352 | CoAP Method | POST is the only supported method of this binding. | 353 | Request URI | The request URI confirming a CoAP URI [xxx] and | 354 | | identifying the WS-Addressing [address] endpoint | 355 | | property (network address). If the value of the | 356 | | WS-Addressing [address] endpoint property is | 357 | | 'http://www.w3.org/2005/08/addressing/anonymous' | 358 | | (directly set or implied by an empty [address] | 359 | | property), the CoAP Uri-Path Option and the CoAP | 360 | | Uri-Query Option are empty. | 361 | Message ID | If messaging model is CON, carrying value in | 362 | | accordance to messaging model of CoAP . Otherwise | 363 | | not included. | 364 | Content-type | Media type of CoAP message body. | 365 | Option | | 366 | Token Option | Token in accordance to CoAP specification | 367 | | identifying the transaction in time and space. | 368 | | Only required if message is a CoAP Confirmable | 369 | | message. | 370 | CoAP message | SOAP message serialized according to the rules for | 371 | body | carrying SOAP messages in the media type given by | 372 | | the Content-type Option. | 373 +--------------+----------------------------------------------------+ 375 Table 1: Unicast one-way Request 377 If the request is send as Non-Confirmable CoAP message, no response 378 is send back to the origin requester. If the request is a 379 Confirmable CoAP message, the response consists only of a CoAP ACK 380 without any data in the CoAP message body. In case of a Conformable 381 CoAP request the response is formulated according to the table below, 382 but can be extended for application specific needs. 384 +--------------+----------------------------------------------------+ 385 | CoAP | Value | 386 | field/header | | 387 | option | | 388 +--------------+----------------------------------------------------+ 389 | CoAP Status | Status Code in accordance to codes defined in CoAP | 390 | Code | and interpreted as described in the SOAP-over-HTTP | 391 | | binding. Note: CoAP describes only a subset of | 392 | | HTTP status codes and adds own codes. This must | 393 | | require further alignment. | 394 | Message ID | If messaging model is CON, carrying value in | 395 | | accordance to messaging model of CoAP . Otherwise | 396 | | not included. | 397 | Token Option | Token in accordance to CoAP specification | 398 | | identifying the transaction in time and space. | 399 | | Only required if message is a CoAP Confirmable | 400 | | message. | 401 +--------------+----------------------------------------------------+ 403 Table 2: Unicast one-way ACK Response 405 Application developers must be aware that the one-way message 406 exchange patterns returns neither failure nor success messages if 407 Non-Confirmable messages are used. 409 7.2. Unicast request-response 411 The unicast request-response message pattern consists of one request 412 and one response. Due to the CoAP binding the request consists of 413 one or more CoAP transactions. 415 The request is formulated according to the table below, but can be 416 extended for application specific needs. 418 +--------------+----------------------------------------------------+ 419 | CoAP | Value | 420 | field/header | | 421 | option | | 422 +--------------+----------------------------------------------------+ 423 | CoAP Method | POST is the only supported method of this binding. | 424 | Request URI | The request URI confirming a CoAP URI [xxx] and | 425 | | identifying the WS-Addressing [address] endpoint | 426 | | property (network address). If the value of the | 427 | | WS-Addressing [address] endpoint property is | 428 | | 'http://www.w3.org/2005/08/addressing/anonymous' | 429 | | (directly set or implied by an empty [address] | 430 | | property), the CoAP Uri-Path Option and the CoAP | 431 | | Uri-Query Option are empty. | 432 | Message ID | If messaging model is CON, carrying value in | 433 | | accordance to messaging model of CoAP . Otherwise | 434 | | not included. | 435 | Content-type | Media type of CoAP message body. | 436 | Option | | 437 | Token Option | Token in accordance to CoAP specification | 438 | | identifying the transaction in time and space. | 439 | | Only required if message is a CoAP Confirmable | 440 | | message. | 441 | CoAP message | SOAP message serialized according to the rules for | 442 | body | carrying SOAP messages in the media type given by | 443 | | the Content-type Option. | 444 +--------------+----------------------------------------------------+ 446 Table 3: Unicast request-response Request 448 If the request is send as Non-Confirmable CoAP message, no CoAP ACK 449 is send back to the origin requester. In this case, for the 450 response, the origin Receiver has to initiate a new CoAP transaction 451 which can be either Non-Confirmable or Confirmable. 453 If the request is a Confirmable CoAP message, the response consists 454 of a CoAP ACK which may carry the response SOAP envelope as data in 455 the CoAP message body. For the response, the origin receiver may 456 also initiate a new CoAP transaction after sending the CoAP ACK to 457 the origin Sender, which can be either also Non-Confirmable or 458 Confirmable. (see deferred responses in CoAP) 460 +--------------+----------------------------------------------------+ 461 | CoAP | Value | 462 | field/header | | 463 | option | | 464 +--------------+----------------------------------------------------+ 465 | CoAP Status | Status Code in accordance to codes defined in CoAP | 466 | Code | and interpreted as described in the SOAP-over-HTTP | 467 | | binding. Note: CoAP describes only a subset of | 468 | | HTTP status codes and adds own codes. This must | 469 | | require further alignment. | 470 | Message ID | If messaging model is CON, carrying value in | 471 | | accordance to messaging model of CoAP . Otherwise | 472 | | not included. | 473 | Token Option | Token in accordance to CoAP specification | 474 | | identifying the transaction in time and space. | 475 | | Only required if message is a CoAP Confirmable | 476 | | message. | 477 | Content-type | Media type of CoAP message body. | 478 | Option | | 479 | CoAP message | SOAP message serialized according to the rules for | 480 | body | carrying SOAP messages in the media type given by | 481 | | the Content-type Option. | 482 +--------------+----------------------------------------------------+ 484 Table 4: Unicast request-response ACK with Response 486 8. IANA Considerations 488 No IANA issues have been identified in this draft. 490 9. Security Considerations 492 Will be added in future versions. 494 10. References 496 10.1. Normative References 498 [I-D.ietf-core-coap] 499 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 500 "Constrained Application Protocol (CoAP)", 501 draft-ietf-core-coap-04 (work in progress), January 2011. 503 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 504 Requirement Levels", BCP 14, RFC 2119, March 1997. 506 [W3C.PR-ws-addr-core-20060321] 507 Gudgin, M., Hadley, M., and T. Rogers, "Web Services 508 Addressing 1.0 - Core", W3C PR PR-ws-addr-core-20060321, 509 March 2006. 511 [W3C.REC-soap12-part0-20070427] 512 Mitra, N. and Y. Lafon, "SOAP Version 1.2 Part 0: Primer 513 (Second Edition)", World Wide Web Consortium 514 Recommendation REC-soap12-part0-20070427, April 2007, 515 . 517 10.2. Informative References 519 [DPWS] Driscoll and Mensch, "OASIS Devices Profile for Web 520 Services (DPWS) Version 1.1", 2009, 521 . 523 [I-D.moritz-6lowapp-dpws-enhancements] 524 Moritz, G., "DPWS for 6LoWPAN", 525 draft-moritz-6lowapp-dpws-enhancements-01 (work in 526 progress), June 2010. 528 [SOAP-over-UDP] 529 Jeyaraman, "OASIS SOAP-over-UDP Version 1.1", 2009, . 533 [W3C.REC-soap12-part1-20070427] 534 Gudgin, M., Karmarkar, A., Nielsen, H., Hadley, M., 535 Mendelsohn, N., Lafon, Y., and J. Moreau, "SOAP Version 536 1.2 Part 1: Messaging Framework (Second Edition)", World 537 Wide Web Consortium Recommendation REC-soap12-part1- 538 20070427, April 2007, 539 . 541 Author's Address 543 Guido Moritz 544 University of Rostock 545 18051 Rostock, 546 Germany 548 Phone: +49 381 498 7269 549 Email: guido.moritz@uni-rostock.de