idnits 2.17.1 draft-savolainen-core-coap-websockets-01.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 (October 18, 2013) is 3843 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-11 == 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-12 -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 0 errors (**), 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 K. Hartke 4 Intended status: Standards Track Nokia 5 Expires: April 21, 2014 B. Silverajan 6 Tampere University of Technology 7 October 18, 2013 9 CoAP over WebSockets 10 draft-savolainen-core-coap-websockets-01 12 Abstract 14 This document specifies how to retrieve and update CoAP resources 15 using CoAP requests and responses over the WebSocket Protocol. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on April 21, 2014. 34 Copyright Notice 36 Copyright (c) 2013 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 53 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 54 2. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . . 6 55 2.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 6 56 2.2. Message Format . . . . . . . . . . . . . . . . . . . . . . 7 57 2.3. Message Transmission . . . . . . . . . . . . . . . . . . . 8 58 2.4. Request Cancellation . . . . . . . . . . . . . . . . . . . 8 59 2.5. Connection Health . . . . . . . . . . . . . . . . . . . . 9 60 2.6. Closing the Connection . . . . . . . . . . . . . . . . . . 9 61 3. CoAP over WebSockets URIs . . . . . . . . . . . . . . . . . . 9 62 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 63 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 64 5.1. URI Scheme Registrations . . . . . . . . . . . . . . . . . 10 65 5.2. WebSocket Subprotocol Registration . . . . . . . . . . . . 12 66 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12 67 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 68 7.1. Normative References . . . . . . . . . . . . . . . . . . . 12 69 7.2. Informative References . . . . . . . . . . . . . . . . . . 13 70 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 14 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 73 1. Introduction 75 The Constrained Application Protocol (CoAP) [I-D.ietf-core-coap] is a 76 web protocol designed for communications between resource constrained 77 nodes. By default, CoAP operates on top of UDP or DTLS, but there is 78 interest in using CoAP also over other types of transports, such as 79 SMS [I-D.becker-core-coap-sms-gprs]. 81 An interesting transport for CoAP could be the WebSocket Protocol 82 [RFC6455]. The WebSocket protocol provides two-way communication 83 between a client and a server after upgrading an HTTP [RFC2616] 84 connection, and may be available in an environment that does not 85 allow transportation of CoAP over UDP. This environment can be, for 86 example, a corporate network with Internet access only via an HTTP 87 proxy, or a CoAP application running in a web browser without access 88 to connectivity means other than HTTP and WebSockets. 90 This document specifies how to access resources using CoAP requests 91 and responses over the WebSocket Protocol. This allows connectivity- 92 limited applications to obtain end-to-end CoAP connectivity either by 93 communicating CoAP directly with a CoAP server that is accessible 94 over a WebSocket Connection, or via an intermediary that proxies CoAP 95 requests and responses between different transports, such as between 96 WebSockets and UDP. 98 +---------------------------------------+ 99 | | 100 | Application | 101 | | 102 +---------------------------------------+ 103 | | 104 | CoAP | 105 | Requests and Responses | 106 | | 107 + - - - - - - - - - +-------------------+ 108 | | | 109 | CoAP | CoAP over | 110 | Messaging | WebSockets | 111 | | | 112 +---------+---------+-------------------+ 113 | | | | 114 | UDP | DTLS | WebSockets | 115 | | | | 116 +---------+---------+-------------------+ 118 Figure 1: Abstract layering of CoAP extended by WebSockets 120 1.1. Overview 122 CoAP over WebSockets can be used in a number of configurations. The 123 most basic configuration is a CoAP client seeking to retrieve or 124 update a CoAP resource located at a CoAP server that exposes a 125 WebSocket endpoint (Figure 2). The CoAP client takes the role of the 126 WebSocket client, establishes a WebSocket Connection and sends a CoAP 127 request, to which the CoAP server returns a CoAP response. The 128 WebSocket Connection can be used for any number of requests. 130 ___________ ___________ 131 | | | | 132 | _|___ requests ___|_ | 133 | CoAP / \ \ -------------> / / \ CoAP | 134 | Client \__/__/ <------------- \__\__/ Server | 135 | | responses | | 136 |___________| |___________| 137 WebSocket =============> WebSocket 138 Client Connection Server 140 Figure 2: CoAP client (WebSocket client) 141 accesses CoAP server (WebSocket server) 143 The challenge in this configuration is to identify resource in the 144 namespace of the CoAP server: When the WebSocket Protocol is used by 145 a dedicated client directly (i.e., not from a web page through a web 146 browser), the client can connect to any WebSocket endpoint. This 147 means it is necessary that the client is able to determine both the 148 endpoint (identified by a "ws" or "wss" URI) and the path and query 149 of the resource within that endpoint from the same URI. When the 150 WebSocket Protocol is used from a web page, the choices are more 151 limited [RFC6454], but the challenge persists. 153 Section 3 proposes a new "coap+ws" URI scheme that identifies both a 154 WebSocket endpoint and a resource within that endpoint as follows: 156 coap+ws://example.org/path/to/endpoint?/sensors/temperature?u=degC 157 \_______________ ______________/ \____________ ___________/ 158 \/ \/ 159 Uri-Path: "sensors" 160 ws://example.org/path/to/endpoint Uri-Path: "temperature" 161 Uri-Query: "u=degC" 163 Figure 3: The "coap+ws" URI Scheme 165 Another possible configuration is to set up a CoAP forward proxy at 166 the WebSocket endpoint. Depending on what transports are available 167 to the proxy, it could forward the request to a CoAP server with a 168 CoAP UDP endpoint (Figure 4), an SMS endpoint (a.k.a. mobile phone), 169 or even another WebSocket endpoint. The client specifies the 170 resource to be updated or retrieved in the Proxy-URI Option. 172 ___________ ___________ ___________ 173 | | | | | | 174 | _|___ ___|_ _|___ ___|_ | 175 | CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP | 176 | Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server | 177 | | | | | | 178 |___________| |___________| |___________| 179 WebSocket ===> WebSocket UDP UDP 180 Client Server Client Server 182 Figure 4: CoAP Client (WebSocket client) accesses CoAP Server 183 (UDP server) via a CoAP proxy (WebSocket server/UDP client) 185 In a completely different direction, another possible configuration 186 is a CoAP server running inside a web browser (Figure 5). The web 187 browser initially connects to a WebSocket endpoint and is then 188 reachable through the WebSocket server. When no connection exists, 189 the CoAP server is not reachable; it therefore can be considered a 190 sleepy endpoint (SEP) [I-D.dijk-core-sleepy-reqs]. 192 ___________ ___________ ___________ 193 | | | | | | 194 | _|___ ___|_ _|___ ___|_ | 195 | CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP | 196 | Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server | 197 | | | | | | 198 |___________| |___________| |___________| 199 UDP UDP WebSocket <=== WebSocket 200 Client Server Server Client 202 Figure 5: CoAP Client (UDP client) accesses sleepy CoAP Server 203 (WebSocket client) via a CoAP proxy (UDP server/WebSocket server) 205 The challenge, again, is to identify the resource. Since the CoAP 206 server is running inside the web browser, this requires not only to 207 identify the WebSocket client and the path and query, but also the 208 intermediary, which is the only path to reach the server. The 209 problem can be avoided if the intermediary is turned into a reverse 210 proxy or a mirror server [I-D.vial-core-mirror-server]. 212 Further configurations are possible, including those where a 213 WebSocket Connection is established through an HTTP proxy. 215 1.2. Terminology 217 This document assumes that readers are familiar with the terms and 218 concepts that are used in [RFC6455] and [I-D.ietf-core-coap]. 220 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 221 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 222 document are to be interpreted as described in [RFC2119]. 224 2. CoAP over WebSockets 226 CoAP over WebSockets is intentionally very similar to CoAP as defined 227 over UDP. Therefore, instead of presenting CoAP over WebSockets as a 228 new protocol, this document specifies it as a series of deltas from 229 [I-D.ietf-core-coap]. 231 2.1. Opening Handshake 233 Before CoAP requests and responses can be exchanged, a WebSocket 234 Connection needs to be established as defined in Section 4 of 235 [RFC6455]. The WebSocket client MUST include the subprotocol name 236 "coap.v1" in the list of protocols, which indicates support for the 237 protocol defined in this document. Figure 6 shows an example. 239 GET /path/to/endpoint HTTP/1.1 240 Host: example.org 241 Upgrade: websocket 242 Connection: Upgrade 243 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 244 Sec-WebSocket-Protocol: coap.v1 245 Sec-WebSocket-Version: 13 247 HTTP/1.1 101 Switching Protocols 248 Upgrade: websocket 249 Connection: Upgrade 250 Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 251 Sec-WebSocket-Protocol: coap.v1 253 Figure 6: Example of an Opening Handshake 255 2.2. Message Format 257 Once a WebSocket Connection has been established, CoAP requests and 258 responses can be exchanged as WebSocket messages. Since CoAP uses a 259 binary message format, the messages are transmitted in binary data 260 frames as specified in Sections 5 and 6 of [RFC6455]. 262 The message format is very similar to the format specified for CoAP 263 over UDP [I-D.ietf-core-coap]. The differences are as follows: 265 o Since the underlying TCP connection provides retransmissions and 266 deduplication, there is no need for the reliability mechanisms 267 provided by CoAP. This means the "T" and "Message ID" fields in 268 the CoAP message header can be elided. 270 o Furthermore, since the CoAP version is already negotiated during 271 the opening handshake, the "Ver" field can be elided as well. 273 The resulting message format is shown in Figure 7. The four most- 274 significant bits of the first byte are reserved (R). The remaining 275 fields and structure are the same as defined in [I-D.ietf-core-coap]. 277 0 1 2 3 278 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 279 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 280 | R | TKL | Code | Token (TKL bytes) ... 281 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 282 | Options (if any) ... 283 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 284 |1 1 1 1 1 1 1 1| Payload (if any) ... 285 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 287 Figure 7: CoAP Message Format over WebSockets 289 Requests and response messages can be fragmented as specified in 290 Section 5.4 of [RFC6455], though typically they are sent unfragmented 291 as they tend to be small and fully buffered before transmission. The 292 WebSocket protocol does not provide means for multiplexing; if it is 293 not desirable for a large message to monopolize the connection, a 294 multiplexing extension such as [I-D.ietf-hybi-websocket-multiplexing] 295 can be used. Alternatively, requests and responses can be 296 transferred in a blockwise fashion as defined in 297 [I-D.ietf-core-block]. 299 Messages MUST NOT be Empty (Code 0.00), i.e., they always carry 300 either a request or a response. 302 2.3. Message Transmission 304 CoAP requests and responses are exchanged asynchronously over the 305 WebSocket Connection, i.e., a CoAP client can send multiple requests 306 without waiting for a response, and the CoAP server can return 307 responses in any order. Responses MUST be returned over the same 308 connection as the originating request. Concurrent requests are 309 differentiated by the Token, which is local to the connection. 311 The connection is bi-directional, so requests can be sent both by the 312 entity that established the connection and the remote host. 314 Retransmission and deduplication of messages is provided by the 315 WebSocket Protocol. CoAP over WebSockets therefore does not make a 316 distinction between Confirmable or Non-Confirmable messages, and does 317 not provide Acknowledgement or Reset messages. 319 Since the WebSocket Protocol provides ordered delivery of messages, 320 the mechanism for reordering detection when observing resources 321 [I-D.ietf-core-observe] is not needed. The value of the Observe 322 Option in notifications therefore MAY be empty on transmission and 323 MUST be ignored on reception. 325 2.4. Request Cancellation 327 [I-D.ietf-core-coap] defines that a CoAP client that is no longer 328 interest in receiving a separate response or further notifications 329 while observing a resource [I-D.ietf-core-observe], can simply 330 "forget" the pending request. When the server then sends the 331 response or the next notification, the client will not recognize the 332 Token in the message and return a Reset message. 334 Since the "T" field in the CoAP message header is elided when sent 335 over the WebSocket Protocol, a client cannot send Reset messages. 336 Instead, a client MAY request the cancellation of a pending request 337 at any time by sending a CoAP message with the Code field set to 7.31 338 and the Token field set to the token of the request to be cancelled 339 [I-D.hartke-core-coap-liveliness]. 341 A server SHOULD NOT send any response or further notification in 342 reply to the specified request after receiving such a message, and 343 MUST remove any matching entry from the list of observers of the 344 target resource of the request. 346 The server SHOULD abort any ongoing tasks related to the request. 347 However, if it is not possible to abort the tasks without leaving the 348 system in an inconsistent state, it MAY continue to execute the tasks 349 and just suppress the return of the resulting response. 351 2.5. Connection Health 353 If a client does not receive any response for some time after sending 354 a CoAP request, the connection between the WebSocket client and the 355 WebSocket server may be lost or temporarily disrupted without the 356 client being aware of it. In this case, the client can send an 357 unsolicited Pong frame to check the health of the WebSocket 358 Connection, as specified in Section 5.5.3 of [RFC6455]. 360 2.6. Closing the Connection 362 The WebSocket Connection is closed as specified in Section 7 of 363 [RFC6455]. 365 If there are any requests for which the CoAP client has not received 366 a response yet, each request is cancelled when the connection is 367 closed. If the CoAP client observes one or more resource over a 368 WebSocket Connection, the CoAP server (or intermediary in the role of 369 the CoAP server) MUST remove all associated entries from the list of 370 observers when the connection is closed. 372 3. CoAP over WebSockets URIs 374 For the first configuration discussed in Section 1.1, this document 375 defines two new URIs schemes that can be used for identifying CoAP 376 resources and providing a means of locating these resources: 377 "coap+ws" and "coap+wss". 379 Similar to the "coap" and "coaps" schemes, the "coap+ws" and "coap+ 380 wss" schemes organize resources hierarchically under a CoAP origin 381 server. The key difference is that the server is potentially 382 reachable on a WebSocket endpoint instead of a UDP endpoint. The 383 endpoint is identified by an embedded "ws" or "wss" URI respectively. 384 The remainder of the URI identifies a resource which can be operated 385 on by the methods defined by the CoAP protocol. 387 The syntax of the "coap+ws" and "coap+wss" URI schemes is specified 388 below in Augmented Backus-Naur Form (ABNF) [RFC5234]. The 389 definitions of "host", "port", "path-abempty" and "query" are the 390 same as in [RFC3986]. 392 coap-ws-URI = "coap+" ws-URI-nq [ "?" path-abempty [ "?" query ] ] 393 coap-wss-URI = "coap+" wss-URI-nq [ "?" path-abempty [ "?" query ] ] 395 ws-URI-nq = "ws:" "//" host [ ":" port ] path-abempty 396 wss-URI-nq = "wss:" "//" host [ ":" port ] path-abempty 398 The port component is OPTIONAL; the default for "coap+ws" is port 80, 399 while the default for "coap+wss" is port 443. 401 Fragment identifiers are not part of the request URI and thus MUST 402 NOT be transmitted in a WebSocket handshake or a CoAP request. 404 4. Security Considerations 406 CoAP over WebSockets and CoAP over TLS-secured WebSockets do not 407 introduce additional security issues beyond CoAP and DTLS-secured 408 CoAP respectively [I-D.ietf-core-coap]. The security considerations 409 of [RFC6455] apply. 411 5. IANA Considerations 413 5.1. URI Scheme Registrations 415 5.1.1. "coap+ws" 417 This document requests the registration of the Uniform Resource 418 Identifier (URI) scheme "coap+ws". 420 URI scheme name. 421 coap+ws 423 Status. 424 Permanent. 426 URI scheme syntax. 427 Defined in Section 3. 429 URI scheme semantics. 430 The "coap+ws" URI scheme provides a way to identify resources that 431 are potentially accessible over the Constrained Application 432 Protocol (CoAP) using the WebSocket Protocol. 434 Encoding considerations. 435 The scheme encoding conforms to the encoding rules established for 436 URIs in [RFC3986], i.e., internationalized and reserved characters 437 are expressed using UTF-8-based percent-encoding. 439 Applications/protocols that use this URI scheme name. 440 The scheme is used by CoAP endpoints to access CoAP resources 441 using the WebSocket protocol. 443 Interoperability considerations. 444 None. 446 Security considerations. 447 See Section 4. 449 Contact. 450 IETF Chair 452 Author/Change controller. 453 IESG 455 References. 456 This document. 458 5.1.2. "coap+wss" 460 This document requests the registration of the Uniform Resource 461 Identifier (URI) scheme "coap+wss". 463 URI scheme name. 464 coap+wss 466 Status. 467 Permanent. 469 URI scheme syntax. 470 Defined in Section 3. 472 URI scheme semantics. 473 The "coap+wss" URI scheme provides a way to identify resources 474 that are potentially accessible over the Constrained Application 475 Protocol (CoAP) using the WebSocket Protocol secured with 476 Transport Layer Security (TLS). 478 Encoding considerations. 479 The scheme encoding conforms to the encoding rules established for 480 URIs in [RFC3986], i.e., internationalized and reserved characters 481 are expressed using UTF-8-based percent-encoding. 483 Applications/protocols that use this URI scheme name. 484 The scheme is used by CoAP endpoints to access CoAP resources 485 using the WebSocket protocol secured with TLS. 487 Interoperability considerations. 488 None. 490 Security considerations. 491 See Section 4. 493 Contact. 494 IETF Chair 496 Author/Change controller. 497 IESG 499 References. 500 This document. 502 5.2. WebSocket Subprotocol Registration 504 This document requests the registration of the subprotocol name 505 "coap.v1" in the WebSocket Subprotocol Name Registry. 507 Subprotocol Identifier. 508 coap.v1 510 Subprotocol Common Name. 511 Constrained Application Protocol (CoAP). 513 Subprotocol Definition. 514 This document. 516 6. Acknowledgements 518 Thanks to Nadir Javed for helpful comments and discussions that have 519 shaped the document. 521 7. References 523 7.1. Normative References 525 [I-D.ietf-core-coap] 526 Shelby, Z., Hartke, K., and C. Bormann, "Constrained 527 Application Protocol (CoAP)", draft-ietf-core-coap-18 528 (work in progress), June 2013. 530 [I-D.ietf-core-observe] 531 Hartke, K., "Observing Resources in CoAP", 532 draft-ietf-core-observe-11 (work in progress), 533 October 2013. 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 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 543 RFC 6455, December 2011. 545 7.2. Informative References 547 [I-D.becker-core-coap-sms-gprs] 548 Becker, M., Li, K., Poetsch, T., and K. Kuladinithi, 549 "Transport of CoAP over SMS", 550 draft-becker-core-coap-sms-gprs-04 (work in progress), 551 August 2013. 553 [I-D.dijk-core-sleepy-reqs] 554 Dijk, E., "Sleepy Devices using CoAP - Requirements", 555 draft-dijk-core-sleepy-reqs-00 (work in progress), 556 June 2013. 558 [I-D.hartke-core-coap-liveliness] 559 Hartke, K., "Liveliness and Cancellation of Separate 560 Responses and Observations", 561 draft-hartke-core-coap-liveliness-00 (work in progress), 562 July 2013. 564 [I-D.ietf-core-block] 565 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 566 draft-ietf-core-block-12 (work in progress), June 2013. 568 [I-D.ietf-hybi-websocket-multiplexing] 569 Tamplin, J. and T. Yoshino, "A Multiplexing Extension for 570 WebSockets", draft-ietf-hybi-websocket-multiplexing-11 571 (work in progress), July 2013. 573 [I-D.vial-core-mirror-server] 574 Vial, M., "CoRE Mirror Server", 575 draft-vial-core-mirror-server-01 (work in progress), 576 April 2013. 578 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 579 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 580 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 582 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 583 Specifications: ABNF", STD 68, RFC 5234, January 2008. 585 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 586 December 2011. 588 Appendix A. Examples 590 This section gives examples for the first two configurations 591 discussed in Section 1.1. 593 An example of the process followed by a CoAP client to retrieve the 594 representation of a resource identified by a "coap+ws" URI might be 595 as follows. Figure 8 below illustrates the WebSocket and CoAP 596 messages exchanged in detail. 598 1. The CoAP client obtains the URI , for example, from a 600 resource representation that it retrieved previously. 602 2. It establishes a WebSocket Connection to the endpoint identified 603 by the embedded "ws" URI, . 605 3. It sends a single-frame, masked, binary message containing a CoAP 606 request. The request indicates the target resource with the Uri- 607 Path ("sensors", "temperature") and Uri-Query ("u=degC") options. 609 4. It waits for server to return a response. 611 5. The CoAP client uses the connection for further requests, or the 612 connection is closed. 614 CoAP CoAP 615 Client Server 616 (WebSocket (WebSocket 617 Client) Server) 619 | | 620 | | 621 +=========>| GET /path/to/endpoint HTTP/1.1 622 | | Host: example.org 623 | | Upgrade: websocket 624 | | Connection: Upgrade 625 | | Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 626 | | Sec-WebSocket-Protocol: coap.v1 627 | | Sec-WebSocket-Version: 13 628 | | 629 |<=========+ HTTP/1.1 101 Switching Protocols 630 | | Upgrade: websocket 631 | | Connection: Upgrade 632 | | Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 633 | | Sec-WebSocket-Protocol: coap.v1 634 | | 635 | | 636 +--------->| Binary frame (opcode=%x2, FIN=1, MASK=1) 637 | | +-------------------------+ 638 | | | GET | 639 | | | Token: 0x53 | 640 | | | Uri-Path: "sensors" | 641 | | | Uri-Path: "temperature" | 642 | | | Uri-Query: "u=degC" | 643 | | +-------------------------+ 644 | | 645 |<---------+ Binary frame (opcode=%x2, FIN=1, MASK=0) 646 | | +-------------------------+ 647 | | | 2.05 Content | 648 | | | Token: 0x53 | 649 | | | Payload: "22.3 C" | 650 | | +-------------------------+ 651 : : 652 : : 653 | | 654 +--------->| Close frame (opcode=%x8, FIN=1, MASK=1) 655 | | 656 |<---------+ Close frame (opcode=%x8, FIN=1, MASK=0) 657 | | 659 Figure 8: A CoAP client retrieves the representation of a resource 660 identified by a "coap+ws" URI 662 Figure 9 shows how a CoAP client uses a CoAP forward proxy with a 663 WebSocket endpoint to retrieve the representation of the resource 664 . The use of the forward proxy and the 665 address of the WebSocket endpoint are determined by the client from 666 local configuration rules. The request URI is specified in the 667 Proxy-Uri Option. Since the request URI uses the "coap" URI scheme, 668 the proxy fulfills the request by issuing a Confirmable GET request 669 over UDP to the CoAP server and returning the response 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 Nokia 720 Hermiankatu 12 D 721 Tampere FI-33720 722 Finland 724 Email: klaus.hartke@nokia.com 726 Bilhanan Silverajan 727 Tampere University of Technology 728 Korkeakoulunkatu 10 729 Tampere FI-33720 730 Finland 732 Email: bilhanan.silverajan@tut.fi