idnits 2.17.1 draft-savolainen-core-coap-websockets-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 (April 10, 2014) is 3662 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-13 ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) == Outdated reference: A later version (-06) exists of draft-becker-core-coap-sms-gprs-04 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-14 -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group T. Savolainen 3 Internet-Draft Nokia 4 Intended status: Standards Track K. Hartke 5 Expires: October 12, 2014 Universitaet Bremen TZI 6 B. Silverajan 7 Tampere University of Technology 8 April 10, 2014 10 CoAP over WebSockets 11 draft-savolainen-core-coap-websockets-02 13 Abstract 15 This document specifies how to retrieve and update CoAP resources 16 using CoAP requests and responses over the WebSocket Protocol. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 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 October 12, 2014. 35 Copyright Notice 37 Copyright (c) 2014 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. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 55 2. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . . 6 56 2.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 6 57 2.2. Message Format . . . . . . . . . . . . . . . . . . . . . . 7 58 2.3. Message Transmission . . . . . . . . . . . . . . . . . . . 8 59 2.4. Connection Health . . . . . . . . . . . . . . . . . . . . 8 60 2.5. Closing the Connection . . . . . . . . . . . . . . . . . . 8 61 3. CoAP over WebSockets URIs . . . . . . . . . . . . . . . . . . 9 62 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 63 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 64 5.1. URI Scheme Registrations . . . . . . . . . . . . . . . . . 10 65 5.2. WebSocket Subprotocol Registration . . . . . . . . . . . . 12 66 5.3. Well-Known URI Suffix Registration . . . . . . . . . . . . 12 67 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12 68 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 69 7.1. Normative References . . . . . . . . . . . . . . . . . . . 12 70 7.2. Informative References . . . . . . . . . . . . . . . . . . 13 71 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 14 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 74 1. Introduction 76 The Constrained Application Protocol (CoAP) [I-D.ietf-core-coap] is a 77 web protocol designed for communications between resource constrained 78 nodes. By default, CoAP operates on top of UDP or DTLS, but there is 79 interest in using CoAP also over other types of transports, such as 80 SMS [I-D.becker-core-coap-sms-gprs]. 82 An interesting transport for CoAP could be the WebSocket Protocol 83 [RFC6455]. The WebSocket protocol provides two-way communication 84 between a client and a server after upgrading an HTTP [RFC2616] 85 connection, and may be available in an environment that does not 86 allow transportation of CoAP over UDP. This environment can be, for 87 example, a corporate network with Internet access only via an HTTP 88 proxy, or a CoAP application running in a web browser without access 89 to connectivity means other than HTTP and WebSockets. 91 This document specifies how to access resources using CoAP requests 92 and responses over the WebSocket Protocol. This allows connectivity- 93 limited applications to obtain end-to-end CoAP connectivity either by 94 communicating CoAP directly with a CoAP server that is accessible 95 over a WebSocket Connection, or via an intermediary that proxies CoAP 96 requests and responses between different transports, such as between 97 WebSockets and UDP. 99 +---------------------------------------+ 100 | | 101 | Application | 102 | | 103 +---------------------------------------+ 104 | | 105 | CoAP | 106 | Requests and Responses | 107 | | 108 + - - - - - - - - - +-------------------+ 109 | | | 110 | CoAP | CoAP over | 111 | Messaging | WebSockets | 112 | | | 113 +---------+---------+-------------------+ 114 | | | | 115 | UDP | DTLS | WebSockets | 116 | | | | 117 +---------+---------+-------------------+ 119 Figure 1: Abstract layering of CoAP extended by WebSockets 121 1.1. Overview 123 CoAP over WebSockets can be used in a number of configurations. The 124 most basic configuration is a CoAP client seeking to retrieve or 125 update a CoAP resource located at a CoAP server that exposes a 126 WebSocket endpoint (Figure 2). The CoAP client takes the role of the 127 WebSocket client, establishes a WebSocket Connection and sends a CoAP 128 request, to which the CoAP server returns a CoAP response. The 129 WebSocket Connection can be used for any number of requests. 131 ___________ ___________ 132 | | | | 133 | _|___ requests ___|_ | 134 | CoAP / \ \ -------------> / / \ CoAP | 135 | Client \__/__/ <------------- \__\__/ Server | 136 | | responses | | 137 |___________| |___________| 138 WebSocket =============> WebSocket 139 Client Connection Server 141 Figure 2: CoAP client (WebSocket client) 142 accesses CoAP server (WebSocket server) 144 The challenge in this configuration is to identify resource in the 145 namespace of the CoAP server: When the WebSocket Protocol is used by 146 a dedicated client directly (i.e., not from a web page through a web 147 browser), the client can connect to any WebSocket endpoint. This 148 means it is necessary that the client is able to determine both the 149 WebSocket endpoint (identified by a "ws" or "wss" URI) and the path 150 and query of the CoAP resource within that endpoint from the same 151 URI. When the WebSocket Protocol is used from a web page, the 152 choices are more limited [RFC6454], but the challenge persists. 154 Section 3 proposes a new "coap+ws" URI scheme that identifies both a 155 WebSocket endpoint and a resource within that endpoint as follows: 157 coap+ws://example.org/sensors/temperature?u=Cel 158 \______ ______/\___________ ___________/ 159 \/ \/ 160 Uri-Path: "sensors" 161 ws://example.org/.well-known/coap Uri-Path: "temperature" 162 Uri-Query: "u=Cel" 164 Figure 3: The "coap+ws" URI Scheme 166 Another possible configuration is to set up a CoAP forward proxy at 167 the WebSocket endpoint. Depending on what transports are available 168 to the proxy, it could forward the request to a CoAP server with a 169 CoAP UDP endpoint (Figure 4), an SMS endpoint (a.k.a. mobile phone), 170 or even another WebSocket endpoint. The client specifies the 171 resource to be updated or retrieved in the Proxy-URI Option. 173 ___________ ___________ ___________ 174 | | | | | | 175 | _|___ ___|_ _|___ ___|_ | 176 | CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP | 177 | Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server | 178 | | | | | | 179 |___________| |___________| |___________| 180 WebSocket ===> WebSocket UDP UDP 181 Client Server Client Server 183 Figure 4: CoAP Client (WebSocket client) accesses CoAP Server 184 (UDP server) via a CoAP proxy (WebSocket server/UDP client) 186 In a completely different way, another possible configuration is a 187 CoAP server running inside a web browser (Figure 5). The web browser 188 initially connects to a WebSocket endpoint and is then reachable 189 through the WebSocket server. When no connection exists, the CoAP 190 server is not reachable; it therefore can be considered a Sleepy 191 Endpoint [I-D.dijk-core-sleepy-reqs]. 193 ___________ ___________ ___________ 194 | | | | | | 195 | _|___ ___|_ _|___ ___|_ | 196 | CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP | 197 | Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server | 198 | | | | | | 199 |___________| |___________| |___________| 200 UDP UDP WebSocket <=== WebSocket 201 Client Server Server Client 203 Figure 5: CoAP Client (UDP client) accesses sleepy CoAP Server 204 (WebSocket client) via a CoAP proxy (UDP server/WebSocket server) 206 The challenge, again, is to identify the resource. Since the CoAP 207 server is running inside the web browser, this requires not only to 208 identify the WebSocket client and the path and query, but also the 209 intermediary, which is the only path to reach the server. The 210 problem can be avoided if the intermediary is turned into a Reverse 211 Proxy or a Mirror Server [I-D.vial-core-mirror-server]. 213 Further configurations are possible, including those where a 214 WebSocket Connection is established through an HTTP proxy. 216 1.2. Terminology 218 This document assumes that readers are familiar with the terms and 219 concepts that are used in [RFC6455] and [I-D.ietf-core-coap]. 221 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 222 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 223 document are to be interpreted as described in [RFC2119]. 225 2. CoAP over WebSockets 227 CoAP over WebSockets is intentionally very similar to CoAP as defined 228 over UDP. Therefore, instead of presenting CoAP over WebSockets as a 229 new protocol, this document specifies it as a series of deltas from 230 [I-D.ietf-core-coap]. 232 2.1. Opening Handshake 234 Before CoAP requests and responses can be exchanged, a WebSocket 235 Connection needs to be established as defined in Section 4 of 236 [RFC6455]. The WebSocket client MUST include the subprotocol name 237 "coap.v1" in the list of protocols, which indicates support for the 238 protocol defined in this document. Figure 6 shows an example. 240 GET /.well-known/coap HTTP/1.1 241 Host: example.org 242 Upgrade: websocket 243 Connection: Upgrade 244 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 245 Sec-WebSocket-Protocol: coap.v1 246 Sec-WebSocket-Version: 13 248 HTTP/1.1 101 Switching Protocols 249 Upgrade: websocket 250 Connection: Upgrade 251 Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 252 Sec-WebSocket-Protocol: coap.v1 254 Figure 6: Example of an Opening Handshake 256 2.2. Message Format 258 Once a WebSocket Connection has been established, CoAP requests and 259 responses can be exchanged as WebSocket messages. Since CoAP uses a 260 binary message format, the messages are transmitted in binary data 261 frames as specified in Sections 5 and 6 of [RFC6455]. 263 The message format is very similar to the format specified for CoAP 264 over UDP [I-D.ietf-core-coap]. The differences are as follows: 266 o Since the underlying TCP connection provides retransmissions and 267 deduplication, there is no need for the reliability mechanisms 268 provided by CoAP over UDP. This means the "T" and "Message ID" 269 fields in the CoAP message header can be elided. 271 o Furthermore, since the CoAP version is already negotiated during 272 the opening handshake, the "Ver" field can be elided as well. 274 The resulting message format is shown in Figure 7. The four most- 275 significant bits of the first byte are reserved (R). The remaining 276 fields and structure are the same as defined in [I-D.ietf-core-coap]. 278 0 1 2 3 279 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 280 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 281 | R | TKL | Code | Token (TKL bytes) ... 282 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 283 | Options (if any) ... 284 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 285 |1 1 1 1 1 1 1 1| Payload (if any) ... 286 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 288 Figure 7: CoAP Message Format over WebSockets 290 Requests and response messages can be fragmented as specified in 291 Section 5.4 of [RFC6455], though typically they are sent unfragmented 292 as they tend to be small and fully buffered before transmission. The 293 WebSocket protocol does not provide means for multiplexing; if it is 294 not desirable for a large message to monopolize the connection, a 295 multiplexing extension such as [I-D.ietf-hybi-websocket-multiplexing] 296 can be used. Alternatively, requests and responses can be 297 transferred in a blockwise fashion, as defined in 298 [I-D.ietf-core-block]. 300 Messages MUST NOT be Empty (Code 0.00), i.e., messages always carry 301 either a request or a response. 303 2.3. Message Transmission 305 CoAP requests and responses are exchanged asynchronously over the 306 WebSocket Connection, i.e., a CoAP client can send multiple requests 307 without waiting for a response, and the CoAP server can return 308 responses in any order. Responses MUST be returned over the same 309 connection as the originating request. Concurrent requests are 310 differentiated by the Token, which is locally scoped to the 311 connection. 313 The connection is bi-directional, so requests can be sent both by the 314 entity that established the connection and the remote host. 316 Retransmission and deduplication of messages is provided by the 317 WebSocket Protocol. CoAP over WebSockets therefore does not make a 318 distinction between Confirmable or Non-Confirmable messages, and does 319 not provide Acknowledgement or Reset messages. 321 Since the WebSocket Protocol provides ordered delivery of messages, 322 the mechanism for reordering detection when observing resources 323 [I-D.ietf-core-observe] is not needed. The value of the Observe 324 Option in notifications therefore MAY be empty on transmission and 325 MUST be ignored on reception. 327 2.4. Connection Health 329 When a client does not receive any response for some time after 330 sending a CoAP request (or, similarly, when a client observes a 331 resource and it does not receive any notification), the connection 332 between the WebSocket client and the WebSocket server may be lost or 333 temporarily disrupted without the client being aware of it. 335 To check the health of the WebSocket Connection (and thereby of all 336 active requests, if any), the client can send a Ping frame or an 337 unsolicited Pong frame, as specified in Section 5.5 of [RFC6455]. 339 2.5. Closing the Connection 341 The WebSocket Connection is closed as specified in Section 7 of 342 [RFC6455]. 344 All requests (if any) for which the CoAP client has not received a 345 response yet, are cancelled when the connection is closed. If the 346 client observes one or more resource over the WebSocket Connection, 347 then the CoAP server (or intermediary in the role of the CoAP server) 348 MUST remove all entries associated with the client from the lists of 349 observers when the connection is closed. 351 3. CoAP over WebSockets URIs 353 For the first configuration discussed in Section 1.1, this document 354 defines two new URIs schemes that can be used for identifying CoAP 355 resources and providing a means of locating these resources: 356 "coap+ws" and "coap+wss". 358 Similar to the "coap" and "coaps" schemes, the "coap+ws" and "coap+ 359 wss" schemes organize resources hierarchically under a CoAP origin 360 server. The key difference is that the server is potentially 361 reachable on a WebSocket endpoint instead of a UDP endpoint. 363 The WebSocket endpoint is identified by an "ws" or "wss" URI that is 364 composed of the authority part of the "coap+ws" or "coap+wss" URI, 365 respectively, and the well-known path "/.well-known/coap" [RFC5785]. 366 The path and query parts of a "coap+ws" or "coap+wss" URI identify a 367 resource within the specified endpoint which can be operated on by 368 the methods defined by the CoAP protocol. 370 The syntax of the "coap+ws" and "coap+wss" URI schemes is specified 371 below in Augmented Backus-Naur Form (ABNF) [RFC5234]. The 372 definitions of "host", "port", "path-abempty" and "query" are the 373 same as in [RFC3986]. 375 coap-ws-URI = 376 "coap+ws:" "//" host [ ":" port ] path-abempty [ "?" query ] 378 coap-wss-URI = 379 "coap+wss:" "//" host [ ":" port ] path-abempty [ "?" query ] 381 The port component is OPTIONAL; the default for "coap+ws" is port 80, 382 while the default for "coap+wss" is port 443. 384 Fragment identifiers are not part of the request URI and thus MUST 385 NOT be transmitted in a WebSocket handshake or in a CoAP request. 387 4. Security Considerations 389 CoAP over WebSockets and CoAP over TLS-secured WebSockets do not 390 introduce additional security issues beyond CoAP and DTLS-secured 391 CoAP respectively [I-D.ietf-core-coap]. 393 The security considerations of [RFC6455] apply. 395 5. IANA Considerations 397 5.1. URI Scheme Registrations 399 5.1.1. "coap+ws" 401 This document requests the registration of the Uniform Resource 402 Identifier (URI) scheme "coap+ws". 404 URI scheme name. 405 coap+ws 407 Status. 408 Permanent. 410 URI scheme syntax. 411 Defined in Section 3. 413 URI scheme semantics. 414 The "coap+ws" URI scheme provides a way to identify resources that 415 are potentially accessible over the Constrained Application 416 Protocol (CoAP) using the WebSocket Protocol. 418 Encoding considerations. 419 The scheme encoding conforms to the encoding rules established for 420 URIs in [RFC3986], i.e., internationalized and reserved characters 421 are expressed using UTF-8-based percent-encoding. 423 Applications/protocols that use this URI scheme name. 424 The scheme is used by CoAP endpoints to access CoAP resources 425 using the WebSocket protocol. 427 Interoperability considerations. 428 None. 430 Security considerations. 431 See Section 4. 433 Contact. 434 IETF Chair 436 Author/Change controller. 437 IESG 439 References. 440 This document. 442 5.1.2. "coap+wss" 444 This document requests the registration of the Uniform Resource 445 Identifier (URI) scheme "coap+wss". 447 URI scheme name. 448 coap+wss 450 Status. 451 Permanent. 453 URI scheme syntax. 454 Defined in Section 3. 456 URI scheme semantics. 457 The "coap+wss" URI scheme provides a way to identify resources 458 that are potentially accessible over the Constrained Application 459 Protocol (CoAP) using the WebSocket Protocol secured with 460 Transport Layer Security (TLS). 462 Encoding considerations. 463 The scheme encoding conforms to the encoding rules established for 464 URIs in [RFC3986], i.e., internationalized and reserved characters 465 are expressed using UTF-8-based percent-encoding. 467 Applications/protocols that use this URI scheme name. 468 The scheme is used by CoAP endpoints to access CoAP resources 469 using the WebSocket protocol secured with TLS. 471 Interoperability considerations. 472 None. 474 Security considerations. 475 See Section 4. 477 Contact. 478 IETF Chair 480 Author/Change controller. 481 IESG 483 References. 484 This document. 486 5.2. WebSocket Subprotocol Registration 488 This document requests the registration of the subprotocol name 489 "coap.v1" in the WebSocket Subprotocol Name Registry. 491 Subprotocol Identifier. 492 coap.v1 494 Subprotocol Common Name. 495 Constrained Application Protocol (CoAP). 497 Subprotocol Definition. 498 This document. 500 5.3. Well-Known URI Suffix Registration 502 This document requests the registration of the Well-Known URI suffix 503 "coap" in the Well-Known URI Registry. 505 URI suffix. 506 coap 508 Change controller. 509 IETF. 511 Specification document(s). 512 This document. 514 Related information. 515 None. 517 6. Acknowledgements 519 Thanks to Nadir Javed for helpful comments and discussions that have 520 shaped the document. 522 7. References 524 7.1. Normative References 526 [I-D.ietf-core-coap] 527 Shelby, Z., Hartke, K., and C. Bormann, "Constrained 528 Application Protocol (CoAP)", draft-ietf-core-coap-18 529 (work in progress), June 2013. 531 [I-D.ietf-core-observe] 532 Hartke, K., "Observing Resources in CoAP", 533 draft-ietf-core-observe-13 (work in progress), April 2014. 535 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 536 Requirement Levels", BCP 14, RFC 2119, March 1997. 538 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 539 Resource Identifier (URI): Generic Syntax", STD 66, 540 RFC 3986, January 2005. 542 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 543 Uniform Resource Identifiers (URIs)", RFC 5785, 544 April 2010. 546 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 547 RFC 6455, December 2011. 549 7.2. Informative References 551 [I-D.becker-core-coap-sms-gprs] 552 Becker, M., Li, K., Poetsch, T., and K. Kuladinithi, 553 "Transport of CoAP over SMS", 554 draft-becker-core-coap-sms-gprs-04 (work in progress), 555 August 2013. 557 [I-D.dijk-core-sleepy-reqs] 558 Dijk, E., "Sleepy Devices using CoAP - Requirements", 559 draft-dijk-core-sleepy-reqs-00 (work in progress), 560 June 2013. 562 [I-D.ietf-core-block] 563 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 564 draft-ietf-core-block-14 (work in progress), October 2013. 566 [I-D.ietf-hybi-websocket-multiplexing] 567 Tamplin, J. and T. Yoshino, "A Multiplexing Extension for 568 WebSockets", draft-ietf-hybi-websocket-multiplexing-11 569 (work in progress), July 2013. 571 [I-D.vial-core-mirror-server] 572 Vial, M., "CoRE Mirror Server", 573 draft-vial-core-mirror-server-01 (work in progress), 574 April 2013. 576 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 577 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 578 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 580 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 581 Specifications: ABNF", STD 68, RFC 5234, January 2008. 583 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 584 December 2011. 586 Appendix A. Examples 588 This section gives examples for the first two configurations 589 discussed in Section 1.1. 591 An example of the process followed by a CoAP client to retrieve the 592 representation of a resource identified by a "coap+ws" URI might be 593 as follows. Figure 8 below illustrates the WebSocket and CoAP 594 messages exchanged in detail. 596 1. The CoAP client obtains the URI 597 , for example, 598 from a resource representation that it retrieved previously. 600 2. It establishes a WebSocket Connection to the endpoint URI 601 composed of the authority "example.org" and the well-known path 602 "/.well-known/coap", . 604 3. It sends a single-frame, masked, binary message containing a CoAP 605 request. The request indicates the target resource with the Uri- 606 Path ("sensors", "temperature") and Uri-Query ("u=Cel") options. 608 4. It waits for the server to return a response. 610 5. The CoAP client uses the connection for further requests, or the 611 connection is closed. 613 CoAP CoAP 614 Client Server 615 (WebSocket (WebSocket 616 Client) Server) 618 | | 619 | | 620 +=========>| GET /.well-known/coap HTTP/1.1 621 | | Host: example.org 622 | | Upgrade: websocket 623 | | Connection: Upgrade 624 | | Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 625 | | Sec-WebSocket-Protocol: coap.v1 626 | | Sec-WebSocket-Version: 13 627 | | 628 |<=========+ HTTP/1.1 101 Switching Protocols 629 | | Upgrade: websocket 630 | | Connection: Upgrade 631 | | Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 632 | | Sec-WebSocket-Protocol: coap.v1 633 | | 634 | | 635 +--------->| Binary frame (opcode=%x2, FIN=1, MASK=1) 636 | | +-------------------------+ 637 | | | GET | 638 | | | Token: 0x53 | 639 | | | Uri-Path: "sensors" | 640 | | | Uri-Path: "temperature" | 641 | | | Uri-Query: "u=Cel" | 642 | | +-------------------------+ 643 | | 644 |<---------+ Binary frame (opcode=%x2, FIN=1, MASK=0) 645 | | +-------------------------+ 646 | | | 2.05 Content | 647 | | | Token: 0x53 | 648 | | | Payload: "22.3 Cel" | 649 | | +-------------------------+ 650 : : 651 : : 652 | | 653 +--------->| Close frame (opcode=%x8, FIN=1, MASK=1) 654 | | 655 |<---------+ Close frame (opcode=%x8, FIN=1, MASK=0) 656 | | 658 Figure 8: A CoAP client retrieves the representation of a resource 659 identified by a "coap+ws" URI 661 Figure 9 shows how a CoAP client uses a CoAP forward proxy with a 662 WebSocket endpoint to retrieve the representation of the resource 663 . The use of the forward proxy and the 664 address of the WebSocket endpoint are determined by the client from 665 local configuration rules. The request URI is specified in the 666 Proxy-Uri Option. Since the request URI uses the "coap" URI scheme, 667 the proxy fulfills the request by issuing a Confirmable GET request 668 over UDP to the CoAP server and returning the response over the 669 WebSocket connection to the client. 671 CoAP CoAP CoAP 672 Client Proxy Server 673 (WebSocket (WebSocket (UDP 674 Client) Server) Endpoint) 676 | | | 677 +--------->| | Binary frame (opcode=%x2, FIN=1, MASK=1) 678 | | | +------------------------------------+ 679 | | | | GET | 680 | | | | Token: 0x7d | 681 | | | | Proxy-Uri: "coap://[2001:DB8::1]/" | 682 | | | +------------------------------------+ 683 | | | 684 | +--------->| CoAP message (Ver=1, T=Con, MID=0x8f54) 685 | | | +------------------------------------+ 686 | | | | GET | 687 | | | | Token: 0x0a15 | 688 | | | +------------------------------------+ 689 | | | 690 | |<---------+ CoAP message (Ver=1, T=Ack, MID=0x8f54) 691 | | | +------------------------------------+ 692 | | | | 2.05 Content | 693 | | | | Token: 0x0a15 | 694 | | | | Payload: "ready" | 695 | | | +------------------------------------+ 696 | | | 697 |<---------+ | Binary frame (opcode=%x2, FIN=1, MASK=0) 698 | | | +------------------------------------+ 699 | | | | 2.05 Content | 700 | | | | Token: 0x7d | 701 | | | | Payload: "ready" | 702 | | | +------------------------------------+ 703 | | | 705 Figure 9: A CoAP client retrieves the representation of a resource 706 identified by a "coap" URI via a WebSockets-enabled CoAP proxy 708 Authors' Addresses 710 Teemu Savolainen 711 Nokia 712 Hermiankatu 12 D 713 Tampere FI-33720 714 Finland 716 Email: teemu.savolainen@nokia.com 718 Klaus Hartke 719 Universitaet Bremen TZI 720 Postfach 330440 721 Bremen D-28359 722 Germany 724 Phone: +49-421-218-63905 725 Email: hartke@tzi.org 727 Bilhanan Silverajan 728 Tampere University of Technology 729 Korkeakoulunkatu 10 730 Tampere FI-33720 731 Finland 733 Email: bilhanan.silverajan@tut.fi