idnits 2.17.1 draft-savolainen-core-coap-websockets-07.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 (June 16, 2016) is 2870 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) == Missing Reference: 'RFCXXXX' is mentioned on line 545, but not defined ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) == Outdated reference: A later version (-06) exists of draft-becker-core-coap-sms-gprs-05 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-20 == Outdated reference: A later version (-11) exists of draft-ietf-core-coap-tcp-tls-02 -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 1 error (**), 0 flaws (~~), 5 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: December 18, 2016 Universitaet Bremen TZI 6 B. Silverajan 7 Tampere University of Technology 8 June 16, 2016 10 CoAP over WebSockets 11 draft-savolainen-core-coap-websockets-07 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 December 18, 2016. 35 Copyright Notice 37 Copyright (c) 2016 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 55 2. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . 5 56 2.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 5 57 2.2. Message Format . . . . . . . . . . . . . . . . . . . . . 6 58 2.3. Message Transmission . . . . . . . . . . . . . . . . . . 7 59 2.4. Connection Health . . . . . . . . . . . . . . . . . . . . 7 60 2.5. Closing the Connection . . . . . . . . . . . . . . . . . 8 61 3. CoAP over WebSockets URIs . . . . . . . . . . . . . . . . . . 8 62 3.1. Decomposing and Composing URIs . . . . . . . . . . . . . 9 63 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 64 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 65 5.1. URI Scheme Registrations . . . . . . . . . . . . . . . . 9 66 5.2. WebSocket Subprotocol Registration . . . . . . . . . . . 11 67 5.3. Well-Known URI Suffix Registration . . . . . . . . . . . 12 68 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 69 6.1. Normative References . . . . . . . . . . . . . . . . . . 12 70 6.2. Informative References . . . . . . . . . . . . . . . . . 13 71 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 13 72 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 17 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 75 1. Introduction 77 The Constrained Application Protocol (CoAP) [RFC7252] is a web 78 protocol designed for communications between resource constrained 79 nodes. By default, CoAP operates as a layer on top of UDP or DTLS, 80 but there is interest in using CoAP also over other types of 81 transports, such as TCP, TLS [I-D.ietf-core-coap-tcp-tls], or SMS 82 [I-D.becker-core-coap-sms-gprs]. 84 An interesting transport for CoAP could be the WebSocket Protocol 85 [RFC6455]. The WebSocket protocol provides two-way communication 86 between a client and a server after upgrading an HTTP/1.1 [RFC7230] 87 connection, and may be available in an environment that does not 88 allow transportation of CoAP over UDP. This environment can be, for 89 example, a corporate network with Internet access only via an HTTP 90 proxy, or a CoAP application running inside a web browser without 91 access to connectivity means other than HTTP and WebSockets. 93 This document specifies how to access resources using CoAP requests 94 and responses over the WebSocket Protocol. This allows connectivity- 95 limited applications to obtain end-to-end CoAP connectivity either by 96 communicating CoAP directly with a CoAP server accessible over a 97 WebSocket Connection or via a CoAP intermediary that proxies CoAP 98 requests and responses between different transports, such as between 99 WebSockets and UDP. 101 +-----------------------------------------------------------+ 102 | | 103 | Application | 104 | | 105 +-----------------------------------------------------------+ 106 | | 107 | CoAP | 108 | Requests and Responses | 109 | | 110 + - - - - - - - - - +-------------------+-------------------+ 111 | | | | 112 | CoAP | CoAP over | CoAP over | 113 | Messaging | TCP and TLS | WebSockets | 114 | | | | 115 +---------+---------+---------+---------+-------------------+ 116 | | | | | | 117 | UDP | DTLS | TCP | TLS | WebSockets | 118 | | | | | | 119 +---------+---------+---------+---------+-------------------+ 121 Figure 1: Abstract layering of CoAP extended by WebSockets 123 1.1. Overview 125 CoAP over WebSockets can be used in a number of configurations. The 126 most basic configuration is a CoAP client seeking to retrieve or 127 update a CoAP resource located at a CoAP server that exposes a 128 WebSocket endpoint (Figure 2). The CoAP client takes the role of the 129 WebSocket client, establishes a WebSocket Connection and sends a CoAP 130 request, to which the CoAP server returns a CoAP response. The 131 WebSocket Connection can be used for any number of requests. 133 ___________ ___________ 134 | | | | 135 | _|___ requests ___|_ | 136 | CoAP / \ \ -------------> / / \ CoAP | 137 | Client \__/__/ <------------- \__\__/ Server | 138 | | responses | | 139 |___________| |___________| 140 WebSocket =============> WebSocket 141 Client Connection Server 143 Figure 2: CoAP client (WebSocket client) 144 accesses CoAP server (WebSocket server) 146 The challenge in this configuration is to identify resource in the 147 namespace of the CoAP server: When the WebSocket Protocol is used by 148 a dedicated client directly (i.e., not from a web page through a web 149 browser), the client can connect to any WebSocket endpoint. This 150 means it is necessary that the client is able to determine both the 151 WebSocket endpoint (identified by a "ws" or "wss" URI) and the path 152 and query of the CoAP resource within that endpoint from the same 153 URI. When the WebSocket Protocol is used from a web page, the 154 choices are more limited [RFC6454], but the challenge persists. 156 Section 3 proposes a new "coap+ws" URI scheme that identifies both a 157 WebSocket endpoint and a resource within that endpoint as follows: 159 coap+ws://example.org/sensors/temperature?u=Cel 160 \______ ______/\___________ ___________/ 161 \/ \/ 162 Uri-Path: "sensors" 163 ws://example.org/.well-known/coap Uri-Path: "temperature" 164 Uri-Query: "u=Cel" 166 Figure 3: The "coap+ws" URI Scheme 168 Another possible configuration is to set up a CoAP forward proxy at 169 the WebSocket endpoint. Depending on what transports are available 170 to the proxy, it could forward the request to a CoAP server with a 171 CoAP UDP endpoint (Figure 4), an SMS endpoint (a.k.a. mobile phone), 172 or even another WebSocket endpoint. The client specifies the 173 resource to be updated or retrieved in the Proxy-URI Option. 175 ___________ ___________ ___________ 176 | | | | | | 177 | _|___ ___|_ _|___ ___|_ | 178 | CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP | 179 | Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server | 180 | | | | | | 181 |___________| |___________| |___________| 182 WebSocket ===> WebSocket UDP UDP 183 Client Server Client Server 185 Figure 4: CoAP Client (WebSocket client) accesses CoAP Server 186 (UDP server) via a CoAP proxy (WebSocket server/UDP client) 188 A third possible configuration is a CoAP server running inside a web 189 browser (Figure 5). The web browser initially connects to a 190 WebSocket endpoint and is then reachable through the WebSocket 191 server. When no connection exists, the CoAP server is not reachable; 192 it therefore can be considered a Sleepy Endpoint (SEP) 193 [I-D.dijk-core-sleepy-reqs]. Because the WebSocket server is the 194 only way to reach the CoAP server, the CoAP proxy should be a Reverse 195 Proxy. 197 ___________ ___________ ___________ 198 | | | | | | 199 | _|___ ___|_ _|___ ___|_ | 200 | CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP | 201 | Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server | 202 | | | | | | 203 |___________| |___________| |___________| 204 UDP UDP WebSocket <=== WebSocket 205 Client Server Server Client 207 Figure 5: CoAP Client (UDP client) accesses sleepy CoAP Server 208 (WebSocket client) via a CoAP proxy (UDP server/WebSocket server) 210 Further configurations are possible, including those where a 211 WebSocket Connection is established through an HTTP proxy. 213 1.2. Terminology 215 This document assumes that readers are familiar with the terms and 216 concepts that are used in [RFC6455] and [RFC7252]. 218 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 219 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 220 document are to be interpreted as described in [RFC2119]. 222 2. CoAP over WebSockets 224 CoAP over WebSockets is intentionally very similar to CoAP as defined 225 over UDP. Therefore, instead of presenting CoAP over WebSockets as a 226 new protocol, this document specifies it as a series of deltas from 227 [RFC7252]. 229 2.1. Opening Handshake 231 Before CoAP requests and responses can be exchanged, a WebSocket 232 Connection needs to be established as defined in Section 4 of 233 [RFC6455]. Figure 6 shows an example. 235 The WebSocket client MUST include the subprotocol name "coap" in the 236 list of protocols, which indicates support for the protocol defined 237 in this document. Any later, incompatible versions of CoAP or CoAP 238 over WebSockets will use a different subprotocol name. 240 The WebSocket client includes the hostname of the WebSocket server in 241 the Host header field of its handshake as per [RFC6455]. The Host 242 header field also indicates the default value of the Uri-Host Option 243 in requests from the WebSocket client to the WebSocket server. 245 GET /.well-known/coap HTTP/1.1 246 Host: example.org 247 Upgrade: websocket 248 Connection: Upgrade 249 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 250 Sec-WebSocket-Protocol: coap 251 Sec-WebSocket-Version: 13 253 HTTP/1.1 101 Switching Protocols 254 Upgrade: websocket 255 Connection: Upgrade 256 Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 257 Sec-WebSocket-Protocol: coap 259 Figure 6: Example of an Opening Handshake 261 2.2. Message Format 263 Once a WebSocket Connection has been established, CoAP requests and 264 responses can be exchanged as WebSocket messages. Since CoAP uses a 265 binary message format, the messages are transmitted in binary data 266 frames as specified in Sections 5 and 6 of [RFC6455]. 268 The message format is very similar to the format specified for CoAP 269 over UDP [RFC7252]. The differences are as follows: 271 o Since the underlying TCP connection provides retransmissions and 272 deduplication, there is no need for the reliability mechanisms 273 provided by CoAP over UDP. This means the "T" and "Message ID" 274 fields in the CoAP message header can be elided. 276 o Furthermore, since the CoAP version is already negotiated during 277 the opening handshake, the "Ver" field can be elided as well. 279 0 1 2 3 280 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 281 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 282 | R | TKL | Code | Token (TKL bytes) ... 283 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 284 | Options (if any) ... 285 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 286 |1 1 1 1 1 1 1 1| Payload (if any) ... 287 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 289 Figure 7: CoAP Message Format over WebSockets 291 The resulting message format is shown in Figure 7. The four most- 292 significant bits of the first byte are reserved (R) and MUST be set 293 to zero. The remaining fields and structure are the same as defined 294 in [RFC7252]. 296 Requests and response messages can be fragmented as specified in 297 Section 5.4 of [RFC6455], though typically they are sent unfragmented 298 as they tend to be small and fully buffered before transmission. The 299 WebSocket protocol does not provide means for multiplexing; if it is 300 not desirable for a large message to monopolize the connection, 301 requests and responses can be transferred in a blockwise fashion as 302 defined in [I-D.ietf-core-block]. 304 Messages MUST NOT be Empty (Code 0.00), i.e., messages always carry 305 either a request or a response. 307 2.3. Message Transmission 309 CoAP requests and responses are exchanged asynchronously over the 310 WebSocket Connection, i.e., a CoAP client can send multiple requests 311 without waiting for a response and the CoAP server can return 312 responses in any order. Responses MUST be returned over the same 313 connection as the originating request. Concurrent requests are 314 differentiated by their Token, which are scoped locally to the 315 connection. 317 The connection is bi-directional, so requests can be sent both by the 318 entity that established the connection and the remote host. 320 Retransmission and deduplication of messages is provided by the 321 WebSocket Protocol. CoAP over WebSockets therefore does not make a 322 distinction between Confirmable or Non-Confirmable messages, and does 323 not provide Acknowledgement or Reset messages. 325 Since the WebSocket Protocol provides ordered delivery of messages, 326 the mechanism for reordering detection when observing resources 327 [RFC7641] is not needed. The value of the Observe Option in 328 notifications therefore MAY be empty on transmission and MUST be 329 ignored on reception. 331 2.4. Connection Health 333 When a client does not receive any response for some time after 334 sending a CoAP request (or, similarly, when a client observes a 335 resource and it does not receive any notification for some time), the 336 connection between the WebSocket client and the WebSocket server may 337 be lost or temporarily disrupted without the client being aware of 338 it. 340 To check the health of the WebSocket Connection (and thereby of all 341 active requests, if any), the client can send a Ping frame or an 342 unsolicited Pong frame as specified in Section 5.5 of [RFC6455]. 343 There is no way to retransmit a request without creating a new one. 344 Re-registering interest in a resource is permitted, but entirely 345 unnecessary. 347 2.5. Closing the Connection 349 The WebSocket Connection is closed as specified in Section 7 of 350 [RFC6455]. 352 All requests for which the CoAP client has not received a response 353 yet are cancelled when the connection is closed. If the client 354 observes one or more resources over the WebSocket Connection, then 355 the CoAP server (or intermediary in the role of the CoAP server) MUST 356 remove all entries associated with the client from the lists of 357 observers when the connection is closed. 359 3. CoAP over WebSockets URIs 361 For the first configuration discussed in Section 1.1, this document 362 defines two new URIs schemes that can be used for identifying CoAP 363 resources and providing a means of locating these resources: 364 "coap+ws" and "coap+wss". 366 Similar to the "coap" and "coaps" schemes, the "coap+ws" and 367 "coap+wss" schemes organize resources hierarchically under a CoAP 368 origin server. The key difference is that the server is potentially 369 reachable on a WebSocket endpoint instead of a UDP endpoint. 371 The WebSocket endpoint is identified by a "ws" or "wss" URI that is 372 composed of the authority part of the "coap+ws" or "coap+wss" URI, 373 respectively, and the well-known path "/.well-known/coap" [RFC5785]. 374 The path and query parts of a "coap+ws" or "coap+wss" URI identify a 375 resource within the specified endpoint which can be operated on by 376 the methods defined by the CoAP protocol. 378 The syntax of the "coap+ws" and "coap+wss" URI schemes is specified 379 below in Augmented Backus-Naur Form (ABNF) [RFC5234]. The 380 definitions of "host", "port", "path-abempty" and "query" are the 381 same as in [RFC3986]. 383 coap-ws-URI = 384 "coap+ws:" "//" host [ ":" port ] path-abempty [ "?" query ] 386 coap-wss-URI = 387 "coap+wss:" "//" host [ ":" port ] path-abempty [ "?" query ] 389 The port component is OPTIONAL; the default for "coap+ws" is port 80, 390 while the default for "coap+wss" is port 443. 392 Fragment identifiers are not part of the request URI and thus MUST 393 NOT be transmitted in a WebSocket handshake or in the URI options of 394 a CoAP request. 396 3.1. Decomposing and Composing URIs 398 The steps for decomposing a "coap+ws" or "coap+wss" URI into CoAP 399 options are the same as specified in Section 6.4 of [RFC7252] with 400 the following changes: 402 o The component MUST be "coap+ws" or "coap+wss" when 403 converted to ASCII lowercase. 405 o A Uri-Host Option MUST only be included in a request when the 406 component does not equal the uri-host component in the Host 407 header field in the WebSocket handshake. 409 o A Uri-Port Option MUST only be included in a request if |port| 410 does not equal the port component in the Host header field in the 411 WebSocket handshake. 413 The steps to construct a URI from a request's options are changed 414 accordingly. 416 4. Security Considerations 418 CoAP over WebSockets and CoAP over TLS-secured WebSockets do not 419 introduce additional security issues beyond CoAP and DTLS-secured 420 CoAP respectively [RFC7252]. 422 The security considerations of [RFC6455] apply. 424 5. IANA Considerations 426 [Note to RFC Editor: Please replace XXXX in this section with the RFC 427 number of this specification.] 429 5.1. URI Scheme Registrations 431 5.1.1. "coap+ws" 433 This document requests the registration of the Uniform Resource 434 Identifier (URI) scheme "coap+ws". 436 URI scheme name. 438 coap+ws 440 Status. 441 Permanent. 443 URI scheme syntax. 444 Defined in Section 3 of [RFCXXXX]. 446 URI scheme semantics. 447 The "coap+ws" URI scheme provides a way to identify resources that 448 are potentially accessible over the Constrained Application 449 Protocol (CoAP) using the WebSocket Protocol. 451 Encoding considerations. 452 The scheme encoding conforms to the encoding rules established for 453 URIs in [RFC3986], i.e., internationalized and reserved characters 454 are expressed using UTF-8-based percent-encoding. 456 Applications/protocols that use this URI scheme name. 457 The scheme is used by CoAP endpoints to access CoAP resources 458 using the WebSocket protocol. 460 Interoperability considerations. 461 None. 463 Security considerations. 464 See Section 4 of [RFCXXXX]. 466 Contact. 467 IETF Chair 469 Author/Change controller. 470 IESG 472 References. 473 [RFCXXXX] 475 5.1.2. "coap+wss" 477 This document requests the registration of the Uniform Resource 478 Identifier (URI) scheme "coap+wss". 480 URI scheme name. 481 coap+wss 483 Status. 484 Permanent. 486 URI scheme syntax. 487 Defined in Section 3 of [RFCXXXX]. 489 URI scheme semantics. 490 The "coap+wss" URI scheme provides a way to identify resources 491 that are potentially accessible over the Constrained Application 492 Protocol (CoAP) using the WebSocket Protocol secured with 493 Transport Layer Security (TLS). 495 Encoding considerations. 496 The scheme encoding conforms to the encoding rules established for 497 URIs in [RFC3986], i.e., internationalized and reserved characters 498 are expressed using UTF-8-based percent-encoding. 500 Applications/protocols that use this URI scheme name. 501 The scheme is used by CoAP endpoints to access CoAP resources 502 using the WebSocket protocol secured with TLS. 504 Interoperability considerations. 505 None. 507 Security considerations. 508 See Section 4 of [RFCXXXX]. 510 Contact. 511 IETF Chair 513 Author/Change controller. 514 IESG 516 References. 517 [RFCXXXX] 519 5.2. WebSocket Subprotocol Registration 521 This document requests the registration of the subprotocol name 522 "coap" in the WebSocket Subprotocol Name Registry. 524 Subprotocol Identifier. 525 coap 527 Subprotocol Common Name. 528 Constrained Application Protocol (CoAP) 530 Subprotocol Definition. 531 [RFCXXXX] 533 5.3. Well-Known URI Suffix Registration 535 This document requests the registration of the Well-Known URI suffix 536 "coap" in the Well-Known URI Registry. 538 URI suffix. 539 coap 541 Change controller. 542 IETF 544 Specification document(s). 545 [RFCXXXX] 547 Related information. 548 None. 550 6. References 552 6.1. Normative References 554 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 555 Requirement Levels", BCP 14, RFC 2119, 556 DOI 10.17487/RFC2119, March 1997, 557 . 559 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 560 Resource Identifier (URI): Generic Syntax", STD 66, 561 RFC 3986, DOI 10.17487/RFC3986, January 2005, 562 . 564 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 565 Uniform Resource Identifiers (URIs)", RFC 5785, 566 DOI 10.17487/RFC5785, April 2010, 567 . 569 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 570 RFC 6455, DOI 10.17487/RFC6455, December 2011, 571 . 573 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 574 Application Protocol (CoAP)", RFC 7252, 575 DOI 10.17487/RFC7252, June 2014, 576 . 578 [RFC7641] Hartke, K., "Observing Resources in the Constrained 579 Application Protocol (CoAP)", RFC 7641, 580 DOI 10.17487/RFC7641, September 2015, 581 . 583 6.2. Informative References 585 [I-D.becker-core-coap-sms-gprs] 586 Becker, M., Li, K., Kuladinithi, K., and T. Poetsch, 587 "Transport of CoAP over SMS", draft-becker-core-coap-sms- 588 gprs-05 (work in progress), August 2014. 590 [I-D.dijk-core-sleepy-reqs] 591 Dijk, E., "Sleepy Devices using CoAP - Requirements", 592 draft-dijk-core-sleepy-reqs-00 (work in progress), June 593 2013. 595 [I-D.ietf-core-block] 596 Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", 597 draft-ietf-core-block-20 (work in progress), April 2016. 599 [I-D.ietf-core-coap-tcp-tls] 600 Bormann, C., Lemay, S., Technologies, Z., and H. 601 Tschofenig, "A TCP and TLS Transport for the Constrained 602 Application Protocol (CoAP)", draft-ietf-core-coap-tcp- 603 tls-02 (work in progress), April 2016. 605 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 606 Specifications: ABNF", STD 68, RFC 5234, 607 DOI 10.17487/RFC5234, January 2008, 608 . 610 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 611 DOI 10.17487/RFC6454, December 2011, 612 . 614 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 615 Protocol (HTTP/1.1): Message Syntax and Routing", 616 RFC 7230, DOI 10.17487/RFC7230, June 2014, 617 . 619 Appendix A. Examples 621 This section gives examples for the first two configurations 622 discussed in Section 1.1. 624 An example of the process followed by a CoAP client to retrieve the 625 representation of a resource identified by a "coap+ws" URI might be 626 as follows. Figure 8 below illustrates the WebSocket and CoAP 627 messages exchanged in detail. 629 1. The CoAP client obtains the URI , for example, from a resource representation 631 that it retrieved previously. 633 2. It establishes a WebSocket Connection to the endpoint URI 634 composed of the authority "example.org" and the well-known path 635 "/.well-known/coap", . 637 3. It sends a single-frame, masked, binary message containing a CoAP 638 request. The request indicates the target resource with the Uri- 639 Path ("sensors", "temperature") and Uri-Query ("u=Cel") options. 641 4. It waits for the server to return a response. 643 5. The CoAP client uses the connection for further requests, or the 644 connection is closed. 646 CoAP CoAP 647 Client Server 648 (WebSocket (WebSocket 649 Client) Server) 651 | | 652 | | 653 +=========>| GET /.well-known/coap HTTP/1.1 654 | | Host: example.org 655 | | Upgrade: websocket 656 | | Connection: Upgrade 657 | | Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 658 | | Sec-WebSocket-Protocol: coap 659 | | Sec-WebSocket-Version: 13 660 | | 661 |<=========+ HTTP/1.1 101 Switching Protocols 662 | | Upgrade: websocket 663 | | Connection: Upgrade 664 | | Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 665 | | Sec-WebSocket-Protocol: coap 666 | | 667 | | 668 +--------->| Binary frame (opcode=%x2, FIN=1, MASK=1) 669 | | +-------------------------+ 670 | | | GET | 671 | | | Token: 0x53 | 672 | | | Uri-Path: "sensors" | 673 | | | Uri-Path: "temperature" | 674 | | | Uri-Query: "u=Cel" | 675 | | +-------------------------+ 676 | | 677 |<---------+ Binary frame (opcode=%x2, FIN=1, MASK=0) 678 | | +-------------------------+ 679 | | | 2.05 Content | 680 | | | Token: 0x53 | 681 | | | Payload: "22.3 Cel" | 682 | | +-------------------------+ 683 : : 684 : : 685 | | 686 +--------->| Close frame (opcode=%x8, FIN=1, MASK=1) 687 | | 688 |<---------+ Close frame (opcode=%x8, FIN=1, MASK=0) 689 | | 691 Figure 8: A CoAP client retrieves the representation of a resource 692 identified by a "coap+ws" URI 694 Figure 9 shows how a CoAP client uses a CoAP forward proxy with a 695 WebSocket endpoint to retrieve the representation of the resource 696 . The use of the forward proxy and the 697 address of the WebSocket endpoint are determined by the client from 698 local configuration rules. The request URI is specified in the 699 Proxy-Uri Option. Since the request URI uses the "coap" URI scheme, 700 the proxy fulfills the request by issuing a Confirmable GET request 701 over UDP to the CoAP server and returning the response over the 702 WebSocket connection to the client. 704 CoAP CoAP CoAP 705 Client Proxy Server 706 (WebSocket (WebSocket (UDP 707 Client) Server) Endpoint) 709 | | | 710 +--------->| | Binary frame (opcode=%x2, FIN=1, MASK=1) 711 | | | +------------------------------------+ 712 | | | | GET | 713 | | | | Token: 0x7d | 714 | | | | Proxy-Uri: "coap://[2001:DB8::1]/" | 715 | | | +------------------------------------+ 716 | | | 717 | +--------->| CoAP message (Ver=1, T=Con, MID=0x8f54) 718 | | | +------------------------------------+ 719 | | | | GET | 720 | | | | Token: 0x0a15 | 721 | | | +------------------------------------+ 722 | | | 723 | |<---------+ CoAP message (Ver=1, T=Ack, MID=0x8f54) 724 | | | +------------------------------------+ 725 | | | | 2.05 Content | 726 | | | | Token: 0x0a15 | 727 | | | | Payload: "ready" | 728 | | | +------------------------------------+ 729 | | | 730 |<---------+ | Binary frame (opcode=%x2, FIN=1, MASK=0) 731 | | | +------------------------------------+ 732 | | | | 2.05 Content | 733 | | | | Token: 0x7d | 734 | | | | Payload: "ready" | 735 | | | +------------------------------------+ 736 | | | 738 Figure 9: A CoAP client retrieves the representation of a resource 739 identified by a "coap" URI via a WebSockets-enabled CoAP proxy 741 Acknowledgements 743 Thanks to Nadir Javed for helpful comments and discussions that have 744 shaped the document. 746 Authors' Addresses 748 Teemu Savolainen 749 Nokia 750 Hermiankatu 12 D 751 Tampere FI-33720 752 Finland 754 Email: teemu.savolainen@nokia.com 756 Klaus Hartke 757 Universitaet Bremen TZI 758 Postfach 330440 759 Bremen D-28359 760 Germany 762 Phone: +49-421-218-63905 763 Email: hartke@tzi.org 765 Bilhanan Silverajan 766 Tampere University of Technology 767 Korkeakoulunkatu 10 768 Tampere FI-33720 769 Finland 771 Email: bilhanan.silverajan@tut.fi