idnits 2.17.1 draft-ietf-core-coap-tcp-tls-04.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 24, 2016) is 2801 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: '0xbc90' is mentioned on line 251, but not defined == Missing Reference: '------' is mentioned on line 251, but not defined == Missing Reference: 'RFCthis' is mentioned on line 1505, but not defined == Unused Reference: 'I-D.becker-core-coap-sms-gprs' is defined on line 1582, but no explicit reference was found in the text ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 4395 (Obsoleted by RFC 7595) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) == Outdated reference: A later version (-06) exists of draft-becker-core-coap-sms-gprs-05 -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 6 errors (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CORE C. Bormann 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Standards Track S. Lemay 5 Expires: February 25, 2017 Zebra Technologies 6 H. Tschofenig 7 ARM Ltd. 8 K. Hartke 9 Universitaet Bremen TZI 10 B. Silverajan 11 Tampere University of Technology 12 B. Raymor, Ed. 13 Microsoft 14 August 24, 2016 16 CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets 17 draft-ietf-core-coap-tcp-tls-04 19 Abstract 21 The Constrained Application Protocol (CoAP), although inspired by 22 HTTP, was designed to use UDP instead of TCP. The message layer of 23 the CoAP over UDP protocol includes support for reliable delivery, 24 simple congestion control, and flow control. 26 Some environments benefit from the availability of CoAP carried over 27 reliable transports such as TCP or TLS. This document outlines the 28 changes required to use CoAP over TCP, TLS, and WebSockets 29 transports. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on February 25, 2017. 48 Copyright Notice 50 Copyright (c) 2016 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (http://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 67 2. CoAP over TCP . . . . . . . . . . . . . . . . . . . . . . . . 5 68 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 5 69 2.2. UDP-to-TCP gateways . . . . . . . . . . . . . . . . . . . 6 70 2.3. Opening Handshake . . . . . . . . . . . . . . . . . . . . 6 71 2.4. Message Format . . . . . . . . . . . . . . . . . . . . . 6 72 2.5. Message Transmission . . . . . . . . . . . . . . . . . . 10 73 3. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . 10 74 3.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 12 75 3.2. Message Format . . . . . . . . . . . . . . . . . . . . . 13 76 3.3. Message Transmission . . . . . . . . . . . . . . . . . . 14 77 3.4. Connection Health . . . . . . . . . . . . . . . . . . . . 14 78 3.5. Closing the Connection . . . . . . . . . . . . . . . . . 15 79 4. Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . 15 80 4.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 15 81 4.2. Signaling Option Numbers . . . . . . . . . . . . . . . . 16 82 4.3. Capability and Settings Messages (CSM) . . . . . . . . . 16 83 4.4. Ping and Pong Messages . . . . . . . . . . . . . . . . . 18 84 4.5. Release Messages . . . . . . . . . . . . . . . . . . . . 19 85 4.6. Abort Messages . . . . . . . . . . . . . . . . . . . . . 20 86 4.7. Capability and Settings examples . . . . . . . . . . . . 21 87 5. Block-wise Transfer and Reliable Transports . . . . . . . . . 21 88 5.1. Example: GET with BERT Blocks . . . . . . . . . . . . . . 23 89 5.2. Example: PUT with BERT Blocks . . . . . . . . . . . . . . 23 90 6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 24 91 6.1. CoAP over TCP and TLS URIs . . . . . . . . . . . . . . . 24 92 6.2. CoAP over WebSockets URIs . . . . . . . . . . . . . . . . 25 93 7. Security Considerations . . . . . . . . . . . . . . . . . . . 26 94 7.1. Signaling Messages . . . . . . . . . . . . . . . . . . . 27 95 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 96 8.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 27 97 8.2. CoAP Signaling Option Numbers Registry . . . . . . . . . 28 98 8.3. Service Name and Port Number Registration . . . . . . . . 29 99 8.4. Secure Service Name and Port Number Registration . . . . 30 100 8.5. URI Scheme Registration . . . . . . . . . . . . . . . . . 30 101 8.6. Well-Known URI Suffix Registration . . . . . . . . . . . 33 102 8.7. ALPN Protocol Identifier . . . . . . . . . . . . . . . . 33 103 8.8. WebSocket Subprotocol Registration . . . . . . . . . . . 33 104 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 105 9.1. Normative References . . . . . . . . . . . . . . . . . . 34 106 9.2. Informative References . . . . . . . . . . . . . . . . . 35 107 Appendix A. Negotiating Protocol Versions . . . . . . . . . . . 36 108 Appendix B. CoAP over WebSocket Examples . . . . . . . . . . . . 36 109 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 40 110 C.1. Since draft-core-coap-tcp-tls-02 . . . . . . . . . . . . 40 111 C.2. Since draft-core-coap-tcp-tls-03 . . . . . . . . . . . . 40 112 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 40 113 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 40 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41 116 1. Introduction 118 The Constrained Application Protocol (CoAP) [RFC7252] was designed 119 for Internet of Things (IoT) deployments, assuming that UDP [RFC0768] 120 or DTLS [RFC6347] over UDP can be used unimpeded. UDP is a good 121 choice for transferring small amounts of data across networks that 122 follow the IP architecture. 124 Some CoAP deployments need to integrate well with existing enterprise 125 infrastructures, where UDP-based protocols may not be well-received 126 or may even be blocked by firewalls. Middleboxes that are unaware of 127 CoAP usage for IoT can make the use of UDP brittle, resulting in lost 128 or malformed packets. 130 Emerging standards such as Lightweight Machine to Machine [LWM2M] 131 currently use CoAP over UDP as a transport and require support for 132 CoAP over TCP to address the issues above and to protect investments 133 in existing CoAP implementations and deployments. Although HTTP/2 134 could also potentially address these requirements, there would be 135 additional costs and delays introduced by such a transition. 136 Currently, there are also fewer HTTP/2 implementations available for 137 constrained devices in comparison to CoAP. 139 To address these requirements, this document defines how to transport 140 CoAP over TCP, CoAP over TLS, and CoAP over WebSockets. Figure 1 141 illustrates the layering: 143 +--------------------------------+ 144 | Application | 145 +--------------------------------+ 146 +--------------------------------+ 147 | Requests/Responses/Signaling | CoAP (RFC 7252) / This Document 148 |--------------------------------| 149 | Message Framing | This Document 150 +--------------------------------+ 151 | Reliable Transport | 152 +--------------------------------+ 154 Figure 1: Layering of CoAP over Reliable Transports 156 Where NATs are present, CoAP over TCP can help with their traversal. 157 NATs often calculate expiration timers based on the transport layer 158 protocol being used by application protocols. Many NATs maintain 159 TCP-based NAT bindings for longer periods based on the assumption 160 that a transport layer protocol, such as TCP, offers additional 161 information about the session life cycle. UDP, on the other hand, 162 does not provide such information to a NAT and timeouts tend to be 163 much shorter [HomeGateway]. 165 Some environments may also benefit from the ability of TCP to 166 exchange larger payloads, such as firmware images, without 167 application layer segmentation and to utilize the more sophisticated 168 congestion control capabilities provided by many TCP implementations. 170 CoAP may be integrated into a Web environment where the front-end 171 uses CoAP over UDP from IoT devices to a cloud infrastructure and 172 then CoAP over TCP between the back-end services. A TCP-to-UDP 173 gateway can be used at the cloud boundary to communicate with the 174 UDP-based IoT device. 176 To allow IoT devices to better communicate in these demanding 177 environments, CoAP needs to support different transport protocols, 178 namely TCP [RFC0793], in some situations secured by TLS [RFC5246]. 180 In addition, some corporate networks only allow Internet access via a 181 HTTP proxy. In this case, the best transport for CoAP would be the 182 WebSocket Protocol [RFC6455]. The WebSocket protocol provides two- 183 way communication between a client and a server after upgrading an 184 HTTP/1.1 [RFC7230] connection and may be available in an environment 185 that blocks CoAP over UDP. Another scenario for CoAP over WebSockets 186 is a CoAP application running inside a web browser without access to 187 connectivity other than HTTP and WebSockets. 189 This document specifies how to access resources using CoAP requests 190 and responses over the TCP/TLS and WebSocket protocols. This allows 191 connectivity-limited applications to obtain end-to-end CoAP 192 connectivity either by communicating CoAP directly with a CoAP server 193 accessible over a TCP/TLS or WebSocket connection or via a CoAP 194 intermediary that proxies CoAP requests and responses between 195 different transports, such as between WebSockets and UDP. 197 1.1. Terminology 199 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 200 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 201 "OPTIONAL" in this document are to be interpreted as described in 202 [RFC2119]. 204 This document assumes that readers are familiar with the terms and 205 concepts that are used in [RFC6455] and [RFC7252]. 207 The term "reliable transport" only refers to stream-based transport 208 protocols such as TCP. 210 BERT Option: 211 A Block1 or Block2 option that includes an SZX value of 7. 213 BERT Block: 214 The payload of a CoAP message that is affected by a BERT Option in 215 descriptive usage (Section 2.1 of [I-D.ietf-core-block]). 217 2. CoAP over TCP 219 The request/response interaction model of CoAP over TCP is the same 220 as CoAP over UDP. The primary differences are in the message layer. 221 CoAP over UDP supports optional reliability by defining four types of 222 messages: Confirmable, Non-confirmable, Acknowledgement, and Reset. 223 TCP eliminates the need for the message layer to support reliability. 224 As a result, message types are not defined in CoAP over TCP. 226 2.1. Messaging Model 228 Conceptually, CoAP over TCP replaces most of the CoAP over UDP 229 message layer with a framing mechanism on top of the byte stream 230 provided by TCP/TLS, conveying the length information for each 231 message that on datagram transports is provided by the UDP/DTLS 232 datagram layer. 234 TCP ensures reliable message transmission, so the CoAP over TCP 235 messaging layer is not required to support acknowledgements or 236 detection of duplicate messages. As a result, both the Type and 237 Message ID fields are no longer required and are removed from the 238 CoAP over TCP message format. All messages are also untyped. 240 Figure 2 illustrates the difference between CoAP over UDP and CoAP 241 over reliable transport. The removed Type and Message ID fields are 242 indicated by dashes. 244 Client Server Client Server 245 | | | | 246 | CON [0xbc90] | | (-------) [------] | 247 | GET /temperature | | GET /temperature | 248 | (Token 0x71) | | (Token 0x71) | 249 +------------------->| +------------------->| 250 | | | | 251 | ACK [0xbc90] | | (-------) [------] | 252 | 2.05 Content | | 2.05 Content | 253 | (Token 0x71) | | (Token 0x71) | 254 | "22.5 C" | | "22.5 C" | 255 |<-------------------+ |<-------------------+ 256 | | | | 258 CoAP over UDP CoAP over reliable 259 transport 261 Figure 2: Comparison between CoAP over unreliable and reliable 262 transport. 264 2.2. UDP-to-TCP gateways 266 A UDP-to-TCP gateway MUST discard all Empty messages (Code 0.00) 267 after processing at the message layer. For Confirmable (CON), Non- 268 Confirmable (NOM), and Acknowledgement (ACK) messages that are not 269 Empty, their contents are repackaged into untyped messages. 271 2.3. Opening Handshake 273 Both the client and the server MUST send a Capability and Settings 274 message (CSM see Section 4.3) as its first message on the connection. 275 This message establishes the initial settings and capabilities for 276 the endpoint such as maximum message size or support for block-wise 277 transfers. The absence of options in the CSM indicates that base 278 values are assumed. 280 Clients and servers MUST treat a missing or invalid CSM as a 281 connection error and abort the connection (see Section 4.6). 283 2.4. Message Format 285 The CoAP message format defined in [RFC7252], as shown in Figure 3, 286 relies on the datagram transport (UDP, or DTLS over UDP) for keeping 287 the individual messages separate and for providing length 288 information. 290 0 1 2 3 291 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 292 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 293 |Ver| T | TKL | Code | Message ID | 294 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 295 | Token (if any, TKL bytes) ... 296 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 297 | Options (if any) ... 298 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 299 |1 1 1 1 1 1 1 1| Payload (if any) ... 300 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 302 Figure 3: RFC 7252 defined CoAP Message Format. 304 The CoAP over TCP message format is very similar to the format 305 specified for CoAP over UDP. The differences are as follows: 307 o Since the underlying TCP connection provides retransmissions and 308 deduplication, there is no need for the reliability mechanisms 309 provided by CoAP over UDP. The "T" and "Message ID" fields in the 310 CoAP message header are elided. 312 o The "Ver" field is elided as well. In constrast to the UDP 313 message layer for UDP and DTLS, the CoAP over TCP message layer 314 does not send a version number in each message. If required in 315 the future, a new Capability and Settings Option (See Appendix A) 316 could be defined to support version negotiation. 318 o In a stream oriented transport protocol such as TCP, a form of 319 message delimitation is needed. For this purpose, CoAP over TCP 320 introduces a length field with variable size. Figure 4 shows the 321 adjusted CoAP message format with a modified structure for the 322 fixed header (first 4 bytes of the CoAP over UDP header), which 323 includes the length information of variable size, shown here as an 324 8-bit length. 326 0 1 2 3 327 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 328 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 329 |Len=13 | TKL |Extended Length| Code | TKL bytes ... 330 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 331 | Options (if any) ... 332 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 333 |1 1 1 1 1 1 1 1| Payload (if any) ... 334 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 336 Figure 4: CoAP frame with 8-bit Extended Length field. 338 Length (Len): 4-bit unsigned integer. A value between 0 and 12 339 directly indicates the length of the message in bytes starting 340 with the first bit of the Options field. Three values are 341 reserved for special constructs: 343 13: An 8-bit unsigned integer (Extended Length) follows the 344 initial byte and indicates the length of options/payload minus 345 13. 347 14: A 16-bit unsigned integer (Extended Length) in network byte 348 order follows the initial byte and indicates the length of 349 options/payload minus 269. 351 15: A 32-bit unsigned integer (Extended Length) in network byte 352 order follows the initial byte and indicates the length of 353 options/payload minus 65805. 355 The encoding of the Length field is modeled on CoAP Options (see 356 section 3.1 of [RFC7252]). 358 The following figures show the message format for the 0-bit, 16-bit, 359 and the 32-bit variable length cases. 361 0 1 2 3 362 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 363 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 364 | Len | TKL | Code | Token (if any, TKL bytes) ... 365 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 366 | Options (if any) ... 367 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 368 |1 1 1 1 1 1 1 1| Payload (if any) ... 369 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 371 Figure 5: CoAP message format without an Extended Length field. 373 For example: A CoAP message just containing a 2.03 code with the 374 token 7f and no options or payload would be encoded as shown in 375 Figure 6. 377 0 1 2 378 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 379 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 380 | 0x01 | 0x43 | 0x7f | 381 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 383 Len = 0 ------> 0x01 384 TKL = 1 ___/ 385 Code = 2.03 --> 0x43 386 Token = 0x7f 388 Figure 6: CoAP message with no options or payload. 390 0 1 2 3 391 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 392 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 393 |Len=14 | TKL | Extended Length (16 bits) | Code | 394 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 395 | Token (if any, TKL bytes) ... 396 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 397 | Options (if any) ... 398 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 399 |1 1 1 1 1 1 1 1| Payload (if any) ... 400 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 402 Figure 7: CoAP message format with 16-bit Extended Length field. 404 0 1 2 3 405 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 406 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 407 |Len=15 | TKL | Extended Length (32 bits) 408 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 409 | | Code | Token (if any, TKL bytes) ... 410 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 411 | Options (if any) ... 412 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 413 |1 1 1 1 1 1 1 1| Payload (if any) ... 414 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 416 Figure 8: CoAP message format with 32-bit Extended Length field. 418 The semantics of the other CoAP header fields are left unchanged. 420 2.5. Message Transmission 422 CoAP requests and responses are exchanged asynchronously over the 423 TCP/TLS connection. A CoAP client can send multiple requests without 424 waiting for a response and the CoAP server can return responses in 425 any order. Responses MUST be returned over the same connection as 426 the originating request. Concurrent requests are differentiated by 427 their Token, which is scoped locally to the connection. 429 The connection is bi-directional, so requests can be sent both by the 430 entity that established the connection and the remote host. 432 Retransmission and deduplication of messages is provided by the TCP/ 433 TLS protocol. 435 Since the TCP protocol provides ordered delivery of messages, the 436 mechanism for reordering detection when observing resources [RFC7641] 437 is not needed. The value of the Observe Option in notifications MAY 438 be empty on transmission and MUST be ignored on reception. 440 3. CoAP over WebSockets 442 CoAP over WebSockets can be used in a number of configurations. The 443 most basic configuration is a CoAP client retrieving or updating a 444 CoAP resource located at a CoAP server that exposes a WebSocket 445 endpoint (Figure 9). The CoAP client acts as the WebSocket client, 446 establishes a WebSocket connection, and sends a CoAP request, to 447 which the CoAP server returns a CoAP response. The WebSocket 448 connection can be used for any number of requests. 450 ___________ ___________ 451 | | | | 452 | _|___ requests ___|_ | 453 | CoAP / \ \ -------------> / / \ CoAP | 454 | Client \__/__/ <------------- \__\__/ Server | 455 | | responses | | 456 |___________| |___________| 457 WebSocket =============> WebSocket 458 Client Connection Server 460 Figure 9: CoAP Client (WebSocket client) accesses CoAP Server 461 (WebSocket server) 463 The challenge with this configuration is how to identify a resource 464 in the namespace of the CoAP server. When the WebSocket protocol is 465 used by a dedicated client directly (i.e., not from a web page 466 through a web browser), the client can connect to any WebSocket 467 endpoint. This means it is necessary for the client to identify both 468 the WebSocket endpoint (identified by a "ws" or "wss" URI) and the 469 path and query of the CoAP resource within that endpoint from the 470 same URI. When the WebSocket protocol is used from a web page, the 471 choices are more limited [RFC6454], but the challenge persists. 473 Section 6.2 defines a new "coap+ws" URI scheme that identifies both a 474 WebSocket endpoint and a resource within that endpoint as follows: 476 coap+ws://example.org/sensors/temperature?u=Cel 477 \______ ______/\___________ ___________/ 478 \/ \/ 479 Uri-Path: "sensors" 480 ws://example.org/.well-known/coap Uri-Path: "temperature" 481 Uri-Query: "u=Cel" 483 Figure 10: The "coap+ws" URI Scheme 485 Another possible configuration is to set up a CoAP forward proxy at 486 the WebSocket endpoint. Depending on what transports are available 487 to the proxy, it could forward the request to a CoAP server with a 488 CoAP UDP endpoint (Figure 11), an SMS endpoint (a.k.a. mobile phone), 489 or even another WebSocket endpoint. The client specifies the 490 resource to be updated or retrieved in the Proxy-URI Option. 492 ___________ ___________ ___________ 493 | | | | | | 494 | _|___ ___|_ _|___ ___|_ | 495 | CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP | 496 | Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server | 497 | | | | | | 498 |___________| |___________| |___________| 499 WebSocket ===> WebSocket UDP UDP 500 Client Server Client Server 502 Figure 11: CoAP Client (WebSocket client) accesses CoAP Server (UDP 503 server) via a CoAP proxy (WebSocket server/UDP client) 505 A third possible configuration is a CoAP server running inside a web 506 browser (Figure 12). The web browser initially connects to a 507 WebSocket endpoint and is then reachable through the WebSocket 508 server. When no connection exists, the CoAP server is unreachable. 509 Because the WebSocket server is the only way to reach the CoAP 510 server, the CoAP proxy should be a Reverse Proxy. 512 ___________ ___________ ___________ 513 | | | | | | 514 | _|___ ___|_ _|___ ___|_ | 515 | CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP | 516 | Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server | 517 | | | | | | 518 |___________| |___________| |___________| 519 UDP UDP WebSocket <=== WebSocket 520 Client Server Server Client 522 Figure 12: CoAP Client (UDP client) accesses sleepy CoAP Server 523 (WebSocket client) via a CoAP proxy (UDP server/WebSocket server) 525 Further configurations are possible, including those where a 526 WebSocket connection is established through an HTTP proxy. 528 CoAP over WebSockets is intentionally very similar to CoAP over UDP. 529 Therefore, instead of presenting CoAP over WebSockets as a new 530 protocol, this document specifies it as a series of deltas from 531 [RFC7252]. 533 3.1. Opening Handshake 535 Before CoAP requests and responses are exchanged, a WebSocket 536 connection is established as defined in Section 4 of [RFC6455]. 537 Figure 13 shows an example. 539 The WebSocket client MUST include the subprotocol name "coap" in the 540 list of protocols, which indicates support for the protocol defined 541 in this document. Any later, incompatible versions of CoAP or CoAP 542 over WebSockets will use a different subprotocol name. 544 The WebSocket client includes the hostname of the WebSocket server in 545 the Host header field of its handshake as per [RFC6455]. The Host 546 header field also indicates the default value of the Uri-Host Option 547 in requests from the WebSocket client to the WebSocket server. 549 GET /.well-known/coap HTTP/1.1 550 Host: example.org 551 Upgrade: websocket 552 Connection: Upgrade 553 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 554 Sec-WebSocket-Protocol: coap 555 Sec-WebSocket-Version: 13 557 HTTP/1.1 101 Switching Protocols 558 Upgrade: websocket 559 Connection: Upgrade 560 Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 561 Sec-WebSocket-Protocol: coap 563 Figure 13: Example of an Opening Handshake 565 3.2. Message Format 567 Once a WebSocket connection is established, CoAP requests and 568 responses can be exchanged as WebSocket messages. Since CoAP uses a 569 binary message format, the messages are transmitted in binary data 570 frames as specified in Sections 5 and 6 of [RFC6455]. 572 The message format shown in Figure 14 is the same as the CoAP over 573 TCP message format (see Section 2.4) with one restriction. The 574 Length (Len) field MUST be set to zero because the WebSockets frame 575 contains the length. 577 0 1 2 3 578 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 579 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 580 | Len | TKL | Code | Token (TKL bytes) ... 581 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 582 | Options (if any) ... 583 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 584 |1 1 1 1 1 1 1 1| Payload (if any) ... 585 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 587 Figure 14: CoAP Message Format over WebSockets 589 The CoAP over TCP message format eliminates the Version field defined 590 in CoAP over UDP. If CoAP version negotiation is required in the 591 future, CoAP over WebSockets can address the requirement by the 592 definition of a new subprotocol identifier that is negotiated during 593 the opening handshake. 595 Requests and response messages can be fragmented as specified in 596 Section 5.4 of [RFC6455], though typically they are sent unfragmented 597 as they tend to be small and fully buffered before transmission. The 598 WebSocket protocol does not provide means for multiplexing. If it is 599 not desirable for a large message to monopolize the connection, 600 requests and responses can be transferred in a block-wise fashion as 601 defined in [I-D.ietf-core-block]. 603 Empty messages (Code 0.00) MUST be ignored by the recipient (see also 604 Section 4.4). 606 3.3. Message Transmission 608 CoAP requests and responses are exchanged asynchronously over the 609 WebSocket connection. A CoAP client can send multiple requests 610 without waiting for a response and the CoAP server can return 611 responses in any order. Responses MUST be returned over the same 612 connection as the originating request. Concurrent requests are 613 differentiated by their Token, which is scoped locally to the 614 connection. 616 The connection is bi-directional, so requests can be sent both by the 617 entity that established the connection and the remote host. 619 Retransmission and deduplication of messages is provided by the 620 WebSocket protocol. CoAP over WebSockets therefore does not make a 621 distinction between Confirmable or Non-Confirmable messages, and does 622 not provide Acknowledgement or Reset messages. 624 Since the WebSocket protocol provides ordered delivery of messages, 625 the mechanism for reordering detection when observing resources 626 [RFC7641] is not needed. The value of the Observe Option in 627 notifications MAY be empty on transmission and MUST be ignored on 628 reception. 630 3.4. Connection Health 632 When a client does not receive any response for some time after 633 sending a CoAP request (or, similarly, when a client observes a 634 resource and it does not receive any notification for some time), the 635 connection between the WebSocket client and the WebSocket server may 636 be lost or temporarily disrupted without the client being aware of 637 it. 639 To check the health of the WebSocket connection (and thereby of all 640 active requests, if any), a client can send a CoAP Ping Signaling 641 message (Section 4.4). WebSocket Ping and unsolicited Pong frames as 642 specified in Section 5.5 of [RFC6455] SHOULD NOT be used to ensure 643 that redundant maintenance traffic is not transmitted. 645 There is no way to retransmit a request without creating a new one. 646 Re-registering interest in a resource is permitted, but entirely 647 unnecessary. 649 3.5. Closing the Connection 651 The WebSocket connection is closed as specified in Section 7 of 652 [RFC6455]. 654 All requests for which the CoAP client has not received a response 655 yet are cancelled when the connection is closed. If the client 656 observes one or more resources over the WebSocket connection, then 657 the CoAP server (or intermediary in the role of the CoAP server) MUST 658 remove all entries associated with the client from the lists of 659 observers when the connection is closed. 661 4. Signaling 663 Signaling messages are introduced to allow peers to: 665 o Share characteristics such as maximum message size for the 666 connection 668 o Shutdown the connection in an ordered fashion 670 o Terminate the connection in response to a serious error condition 672 Signaling is a third basic kind of message in CoAP, after requests 673 and responses. Signaling messages share a common structure with the 674 existing CoAP messages. There is a code, a token, options, and an 675 optional payload. 677 (See Section 3 of [RFC7252] for the overall structure, as adapted to 678 the specific transport.) 680 4.1. Signaling Codes 682 A code in the 7.01-7.31 range indicates a Signaling message. Values 683 in this range are assigned by the "CoAP Signaling Codes" sub-registry 684 (see Section 8.1). 686 For each message, there is a sender and a peer receiving the message. 688 Payloads in Signaling messages are diagnostic payloads (see 689 Section 5.5.2 of [RFC7252]), unless otherwise defined by a Signaling 690 message option. 692 4.2. Signaling Option Numbers 694 Option numbers for Signaling messages are specific to the message 695 code. They do not share the number space with CoAP options for 696 request/response messages or with Signaling messages using other 697 codes. 699 Option numbers are assigned by the "CoAP Signaling Option Numbers" 700 sub-registry (see Section 8.2). 702 Signaling options are elective or critical as defined in 703 Section 5.4.1 of [RFC7252]). If a Signaling option is critical and 704 not understood by the receiver, it MUST abort the connection (see 705 Section 4.6). If the option is understood but cannot be processed, 706 the option documents the behavior. 708 4.3. Capability and Settings Messages (CSM) 710 Capability and Settings messages (CSM) are used for two purposes: 712 o Each capability option advertises one capability of the sender to 713 the recipient. 715 o Setting options indicate a setting that will be applied by the 716 sender. 718 A Capability and Settings message MUST be sent by both endpoints at 719 the start of the connection and MAY be sent at any other time by 720 either endpoint over the lifetime of the connection. 722 Both capability and settings options are cumulative. A Capability 723 and Settings message does not invalidate a previously sent capability 724 indication or setting even if it is not repeated. A capability 725 message without any option is a no-operation (and can be used as 726 such). An option that is sent might override a previous value for 727 the same option. The option defines how to handle this case if 728 needed. 730 Base values are listed below for CSM Options. These are the values 731 for the Capability and Setting before any Capability and Settings 732 messages send a modified value. 734 These are not default values for the option as defined in 735 Section 5.4.4 in [RFC7252]. A default value would mean that an empty 736 Capability and Settings message would result in the option being set 737 to its default value. 739 Capability and Settings messages are indicated by the 7.01 code 740 (CSM). 742 4.3.1. Server-Name Setting Option 744 +--------+------------+-------------+--------+--------+-------------+ 745 | Number | Applies to | Name | Format | Length | Base Value | 746 +--------+------------+-------------+--------+--------+-------------+ 747 | 1 | CSM | Server-Name | string | 1-255 | (see below) | 748 +--------+------------+-------------+--------+--------+-------------+ 750 A client can use the Server-Name critical option to indicate the 751 default value for the Uri-Host Options in the messages that it sends 752 to the server. It has the same restrictions as the Uri-Host Option 753 (Section 5.10 of [RFC7252]. 755 For TLS, the initial value for the Server-Name Option is given by the 756 SNI value. 758 For Websockets, the initial value for the Server-Name Option is given 759 by the HTTP Host header field. 761 4.3.2. Max-Message-Size Capability Option 763 The sender can use the Max-Message-Size elective option to indicate 764 the maximum message size in bytes that it can receive. 766 +--------+-----------+------------------+--------+--------+---------+ 767 | Number | Applies | Name | Format | Length | Base | 768 | | to | | | | Value | 769 +--------+-----------+------------------+--------+--------+---------+ 770 | 2 | CSM | Max-Message-Size | uint | 0-4 | 1152 | 771 +--------+-----------+------------------+--------+--------+---------+ 773 As per Section 4.6 of [RFC7252], the base value (and the value used 774 when this option is not implemented) is 1152. A peer that relies on 775 this option being indicated with a certain minimum value will enjoy 776 limited interoperability. 778 4.3.3. Block-wise Transfer Capability Option 780 +--------+-----------+----------------+--------+--------+-----------+ 781 | Number | Applies | Name | Format | Length | Base | 782 | | to | | | | Value | 783 +--------+-----------+----------------+--------+--------+-----------+ 784 | 4 | CSM | Block-wise | empty | 0 | (none) | 785 | | | Transfer | | | | 786 +--------+-----------+----------------+--------+--------+-----------+ 787 A sender can use the Block-wise Transfer elective Option to indicate 788 that it supports the block-wise transfer protocol 789 [I-D.ietf-core-block]. 791 If the option is not given, the peer has no information about whether 792 block-wise transfers are supported by the sender or not. An 793 implementation that supports block-wise transfers SHOULD indicate the 794 Block-wise Transfer Option. If a Max-Message-Size Option is 795 indicated with a value that is greater than 1152 (in the same or a 796 different CSM message), the Block-wise Transfer Option also indicates 797 support for BERT (see Section 5). 799 4.4. Ping and Pong Messages 801 In CoAP over TCP, Empty messages (Code 0.00) can always be sent and 802 MUST be ignored by the recipient. This provides a basic keep-alive 803 function that can refresh NAT bindings. In contrast, Ping and Pong 804 messages are a bidirectional exchange. 806 Upon receipt of a Ping message, a single Pong message is returned 807 with the identical token. As with all Signaling messages, the 808 recipient of a Ping or Pong message MUST ignore elective options it 809 does not understand. 811 Ping and Pong messages are indicated by the 7.02 code (Ping) and the 812 7.03 code (Pong). 814 4.4.1. Custody Option 816 +--------+------------+---------+--------+--------+------------+ 817 | Number | Applies to | Name | Format | Length | Base Value | 818 +--------+------------+---------+--------+--------+------------+ 819 | 2 | Ping, Pong | Custody | empty | 0 | (none) | 820 +--------+------------+---------+--------+--------+------------+ 822 A peer replying to a Ping message can add a Custody elective option 823 to the Pong message it returns. This option indicates that the 824 application has processed all request/response messages that it has 825 received in the present connection ahead of the Ping message that 826 prompted the Pong message. (Note that there is no definition of 827 specific application semantics of "processed", but there is an 828 expectation that the sender of the Ping leading to the Pong with a 829 Custody Option should be able to free buffers based on this 830 indication.) 832 A Custody elective option can also be sent in a Ping message to 833 explicitly request the return of a Custody Option in the Pong 834 message. A peer is always free to indicate that it has finished 835 processing all previous request/response messages by sending a 836 Custody Option in a Pong message. A peer is also free NOT to send a 837 Custody Option in case it is still processing previous request/ 838 response messages; however, it SHOULD delay its response to a Ping 839 with a Custody Option until it can also return one. 841 4.5. Release Messages 843 A release message indicates that the sender does not want to continue 844 maintaining the connection and opts for an orderly shutdown; the 845 details are in the options. A diagnostic payload MAY be included. A 846 release message will normally be replied to by the peer by closing 847 the TCP/TLS connection. Messages may be in flight when the sender 848 decides to send a Release message. The general expectation is that 849 these will still be processed. 851 Release messages are indicated by the 7.04 code (Release). 853 Release messages can indicate one or more reasons using elective 854 options. The following options are defined: 856 +--------+-----------+-----------------+--------+--------+----------+ 857 | Number | Applies | Name | Format | Length | Base | 858 | | to | | | | Value | 859 +--------+-----------+-----------------+--------+--------+----------+ 860 | 2 | Release | Bad-Server-Name | empty | 0 | (none) | 861 +--------+-----------+-----------------+--------+--------+----------+ 863 The Bad-Server-Name elective option indicates that the default 864 indicated by the CSM Server-Name Option is unlikely to be useful for 865 this server. 867 +--------+----------+-------------------+--------+--------+---------+ 868 | Number | Applies | Name | Format | Length | Base | 869 | | to | | | | Value | 870 +--------+----------+-------------------+--------+--------+---------+ 871 | 4 | Release | Alternate-Address | string | 1-255 | (none) | 872 +--------+----------+-------------------+--------+--------+---------+ 874 The Alternative-Address elective option requests the peer to instead 875 open a connection of the same kind as the present connection to the 876 alternative transport address given. Its value is in the form 877 "authority" as defined in Section 3.2 of [RFC3986]. 879 +--------+------------+----------+--------+--------+------------+ 880 | Number | Applies to | Name | Format | Length | Base Value | 881 +--------+------------+----------+--------+--------+------------+ 882 | 6 | Release | Hold-Off | uint | 0-3 | (none) | 883 +--------+------------+----------+--------+--------+------------+ 885 The Hold-Off elective option indicates that the server is requesting 886 that the peer not reconnect to it for the number of seconds given in 887 the value. 889 4.6. Abort Messages 891 An abort message indicates that the sender is unable to continue 892 maintaining the connection and cannot even wait for an orderly 893 release. The sender shuts down the connection immediately after the 894 abort (and may or may not wait for a release or abort message or 895 connection shutdown in the inverse direction). A diagnostic payload 896 SHOULD be included in the Abort message. Messages may be in flight 897 when the sender decides to send an abort message. The general 898 expectation is that these will NOT be processed. 900 Abort messages are indicated by the 7.05 code (Abort). 902 Abort messages can indicate one or more reasons using elective 903 options. The following option is defined: 905 +--------+-----------+----------------+--------+--------+-----------+ 906 | Number | Applies | Name | Format | Length | Base | 907 | | to | | | | Value | 908 +--------+-----------+----------------+--------+--------+-----------+ 909 | 2 | Abort | Bad-CSM-Option | uint | 0-2 | (none) | 910 +--------+-----------+----------------+--------+--------+-----------+ 912 The Bad-CSM-Option Option indicates that the sender is unable to 913 process the CSM option identified by its option number, e.g. when it 914 is critical and the option number is unknown by the sender, or when 915 there is parameter problem with the value of an elective option. 916 More detailed information SHOULD be included as a diagnostic payload. 918 One reason for an sender to generate an abort message is a general 919 syntax error in the byte stream received. No specific option has 920 been defined for this, as the details of that syntax error are best 921 left to a diagnostic payload. 923 4.7. Capability and Settings examples 925 An encoded example of a Ping message with a non-empty token is shown 926 in Figure 15. 928 0 1 2 929 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 930 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 931 | 0x01 | 0xe2 | 0x42 | 932 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 934 Len = 0 -------> 0x01 935 TKL = 1 ___/ 936 Code = 7.02 Ping --> 0xe2 937 Token = 0x42 939 Figure 15: Ping Message Example 941 An encoded example of the corresponding Pong message is shown in 942 Figure 16. 944 0 1 2 945 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 946 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 947 | 0x01 | 0xe3 | 0x42 | 948 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 950 Len = 0 -------> 0x01 951 TKL = 1 ___/ 952 Code = 7.03 Pong --> 0xe3 953 Token = 0x42 955 Figure 16: Pong Message Example 957 5. Block-wise Transfer and Reliable Transports 959 The message size restrictions defined in Section 4.6 of CoAP 960 [RFC7252] to avoid IP fragmentation are not necessary when CoAP is 961 used over a reliable byte stream transport. While this suggests that 962 the Block-wise transfer protocol [I-D.ietf-core-block] is also no 963 longer needed, it remains applicable for a number of cases: 965 o large messages, such as firmware downloads, may cause undesired 966 head-of-line blocking when a single TCP connection is used 968 o a UDP-to-TCP gateway may simply not have the context to convert a 969 message with a Block Option into the equivalent exchange without 970 any use of a Block Option (it would need to convert the entire 971 blockwise exchange from start to end into a single exchange) 973 The 'Block-wise Extension for Reliable Transport (BERT)' extends the 974 Block protocol to enable the use of larger messages over a reliable 975 transport. 977 The use of this new extension is signaled by sending Block1 or Block2 978 Options with SZX == 7 (a "BERT option"). SZX == 7 is a reserved 979 value in [I-D.ietf-core-block]. 981 In control usage, a BERT option is interpreted in the same way as the 982 equivalent Option with SZX == 6, except that it also indicates the 983 capability to process BERT blocks. As with the basic Block protocol, 984 the recipient of a CoAP request with a BERT option in control usage 985 is allowed to respond with a different SZX value, e.g. to send a non- 986 BERT block instead. 988 In descriptive usage, a BERT Option is interpreted in the same way as 989 the equivalent Option with SZX == 6, except that the payload is 990 allowed to contain a multiple of 1024 bytes (non-final BERT block) or 991 more than 1024 bytes (final BERT block). 993 The recipient of a non-final BERT block (M=1) conceptually partitions 994 the payload into a sequence of 1024-byte blocks and acts exactly as 995 if it had received this sequence in conjunction with block numbers 996 starting at, and sequentially increasing from, the block number given 997 in the Block Option. In other words, the entire BERT block is 998 positioned at the byte position that results from multiplying the 999 block number with 1024. The position of further blocks to be 1000 transferred is indicated by incrementing the block number by the 1001 number of elements in this sequence (i.e., the size of the payload 1002 divided by 1024 bytes). 1004 As with SZX == 6, the recipient of a final BERT block (M=0) simply 1005 appends the payload at the byte position that is indicated by the 1006 block number multiplied with 1024. 1008 The following examples illustrate BERT options. A value of SZX == 7 1009 is labeled as "BERT" or as "BERT(nnn)" to indicate a payload of size 1010 nnn. 1012 In all these examples, a Block Option is decomposed to indicate the 1013 kind of Block Option (1 or 2) followed by a colon, the block number 1014 (NUM), more bit (M), and block size exponent (2**(SZX+4)) separated 1015 by slashes. E.g., a Block2 Option value of 33 would be shown as 1016 2:2/0/32), or a Block1 Option value of 59 would be shown as 1017 1:3/1/128. 1019 5.1. Example: GET with BERT Blocks 1021 Figure 17 shows a GET request with a response that is split into 1022 three BERT blocks. The first response contains 3072 bytes of 1023 payload; the second, 5120; and the third, 4711. Note how the block 1024 number increments to move the position inside the response body 1025 forward. 1027 CLIENT SERVER 1028 | | 1029 | GET, /status ------> | 1030 | | 1031 | <------ 2.05 Content, 2:0/1/BERT(3072) | 1032 | | 1033 | GET, /status, 2:3/0/BERT ------> | 1034 | | 1035 | <------ 2.05 Content, 2:3/1/BERT(5120) | 1036 | | 1037 | GET, /status, 2:8/0/BERT ------> | 1038 | | 1039 | <------ 2.05 Content, 2:8/0/BERT(4711) | 1041 Figure 17: GET with BERT blocks. 1043 5.2. Example: PUT with BERT Blocks 1045 Figure 18 demonstrates a PUT exchange with BERT blocks. 1047 CLIENT SERVER 1048 | | 1049 | PUT, /options, 1:0/1/BERT(8192) ------> | 1050 | | 1051 | <------ 2.31 Continue, 1:0/1/BERT | 1052 | | 1053 | PUT, /options, 1:8/1/BERT(16384) ------> | 1054 | | 1055 | <------ 2.31 Continue, 1:8/1/BERT | 1056 | | 1057 | PUT, /options, 1:24/0/BERT(5683) ------> | 1058 | | 1059 | <------ 2.04 Changed, 1:24/0/BERT | 1060 | | 1062 Figure 18: PUT with BERT blocks. 1064 6. CoAP URIs 1066 CoAP over UDP [RFC7252] defines the "coap" and "coaps" URI schemes 1067 for identifying CoAP resources and providing a means of locating the 1068 resource. 1070 6.1. CoAP over TCP and TLS URIs 1072 CoAP over TCP uses the "coap+tcp" URI scheme. CoAP over TLS uses the 1073 "coaps+tcp" scheme. The rules from Section 6 of [RFC7252] apply to 1074 both of these URI schemes. 1076 [RFC7252], Section 8 (Multicast CoAP) is not applicable to these 1077 schemes. 1079 Resources made available via one of the "coap+tcp" or "coaps+tcp" 1080 schemes have no shared identity with the other scheme or with the 1081 "coap" or "coaps" scheme, even if their resource identifiers indicate 1082 the same authority (the same host listening to the same port). The 1083 schemes constitute distinct namespaces and, in combination with the 1084 authority, are considered to be distinct origin servers. 1086 6.1.1. coap+tcp URI scheme 1088 coap-tcp-URI = "coap+tcp:" "//" host [ ":" port ] path-abempty 1089 [ "?" query ] 1091 The semantics defined in [RFC7252], Section 6.1, apply to this URI 1092 scheme, with the following changes: 1094 o The port subcomponent indicates the TCP port at which the CoAP 1095 server is located. (If it is empty or not given, then the default 1096 port 5683 is assumed, as with UDP.) 1098 6.1.2. coaps+tcp URI scheme 1100 coaps-tcp-URI = "coaps+tcp:" "//" host [ ":" port ] path-abempty 1101 [ "?" query ] 1103 The semantics defined in [RFC7252], Section 6.2, apply to this URI 1104 scheme, with the following changes: 1106 o The port subcomponent indicates the TCP port at which the TLS 1107 server for the CoAP server is located. If it is empty or not 1108 given, then the default port 443 is assumed (this is different 1109 from the default port for "coaps", i.e., CoAP over DTLS over UDP). 1111 o If a server does not support the Application-Layer Protocol 1112 Negotiation Extension (ALPN) [RFC7301] or wishes to accommodate 1113 clients that do not support ALPN, it MAY offer a coaps+tcp 1114 endpoint on TCP port 5684. This endpoint MAY also be ALPN 1115 enabled. A server MAY offer coaps+tcp endpoints on ports other 1116 than TCP port 5684, which MUST be ALPN enabled. 1118 o For TCP ports other than port 5684, the client MUST use the ALPN 1119 extension to advertise the "coap" protocol identifier (see 1120 Section 8.7) in the list of protocols in its ClientHello. If the 1121 server selects and returns the "coap" protocol identifier using 1122 the ALPN extension in its ServerHello, then the connection 1123 succeeds. If the server either does not negotiate the ALPN 1124 extension or returns a no_application_protocol alert, the client 1125 MUST close the connection. 1127 o For TCP port 5684, a client MAY use the ALPN extension to 1128 advertise the "coap" protocol identifier in the list of protocols 1129 in its ClientHello. If the server selects and returns the "coap" 1130 protocol identifier using the ALPN extension in its ServerHello, 1131 then the connection succeeds. If the server returns a 1132 no_application_protocol alert, then the client MUST close the 1133 connection. If the server does not negotiate the ALPN extension, 1134 then coaps+tcp is implicitly selected. 1136 o For TCP port 5684, if the client does not use the ALPN extension 1137 to negotiate the protocol, then coaps+tcp is implicitly selected. 1139 6.2. CoAP over WebSockets URIs 1141 For the first configuration discussed in Section 3, this document 1142 defines two new URIs schemes that can be used for identifying CoAP 1143 resources and providing a means of locating these resources: 1144 "coap+ws" and "coap+wss". 1146 Similar to the "coap" and "coaps" schemes, the "coap+ws" and 1147 "coap+wss" schemes organize resources hierarchically under a CoAP 1148 origin server. The key difference is that the server is potentially 1149 reachable on a WebSocket endpoint instead of a UDP endpoint. 1151 The WebSocket endpoint is identified by a "ws" or "wss" URI that is 1152 composed of the authority part of the "coap+ws" or "coap+wss" URI, 1153 respectively, and the well-known path "/.well-known/coap" [RFC5785]. 1154 The path and query parts of a "coap+ws" or "coap+wss" URI identify a 1155 resource within the specified endpoint which can be operated on by 1156 the methods defined by CoAP. 1158 The syntax of the "coap+ws" and "coap+wss" URI schemes is specified 1159 below in Augmented Backus-Naur Form (ABNF) [RFC5234]. The 1160 definitions of "host", "port", "path-abempty" and "query" are the 1161 same as in [RFC3986]. 1163 coap-ws-URI = 1164 "coap+ws:" "//" host [ ":" port ] path-abempty [ "?" query ] 1166 coap-wss-URI = 1167 "coap+wss:" "//" host [ ":" port ] path-abempty [ "?" query ] 1169 The port component is OPTIONAL; the default for "coap+ws" is port 80, 1170 while the default for "coap+wss" is port 443. 1172 Fragment identifiers are not part of the request URI and thus MUST 1173 NOT be transmitted in a WebSocket handshake or in the URI options of 1174 a CoAP request. 1176 6.2.1. Decomposing and Composing URIs 1178 The steps for decomposing a "coap+ws" or "coap+wss" URI into CoAP 1179 options are the same as specified in Section 6.4 of [RFC7252] with 1180 the following changes: 1182 o The component MUST be "coap+ws" or "coap+wss" when 1183 converted to ASCII lowercase. 1185 o A Uri-Host Option MUST only be included in a request when the 1186 component does not equal the uri-host component in the Host 1187 header field in the WebSocket handshake. 1189 o A Uri-Port Option MUST only be included in a request if |port| 1190 does not equal the port component in the Host header field in the 1191 WebSocket handshake. 1193 The steps to construct a URI from a request's options are changed 1194 accordingly. 1196 7. Security Considerations 1198 The security considerations of [RFC7252] apply. 1200 TLS version 1.2 or higher is mandatory-to-implement and MUST be 1201 enabled by default. An endpoint MAY immediately abort a CoAP over 1202 TLS connection that does not meet this requirement (see Section 4.6) 1203 and SHOULD include a diagnostic payload. 1205 The TLS usage guidance in [RFC7925] SHOULD be followed. 1207 TLS does not protect the TCP header. This may, for example, allow an 1208 on-path adversary to terminate a TCP connection prematurely by 1209 spoofing a TCP reset message. 1211 CoAP over WebSockets and CoAP over TLS-secured WebSockets do not 1212 introduce additional security issues beyond CoAP and DTLS-secured 1213 CoAP respectively [RFC7252]. The security considerations of 1214 [RFC6455] apply. 1216 7.1. Signaling Messages 1218 o The guidance given by an Alternative-Address Option cannot be 1219 followed blindly. In particular, a peer MUST NOT assume that a 1220 successful connection to the Alternative-Address inherits all the 1221 security properties of the current connection. 1223 o SNI vs. Server-Name: Any security negotiated in the TLS handshake 1224 is for the SNI name exchanged in the TLS handshake and checked 1225 against the certificate provided by the server. The Server-Name 1226 Option cannot be used to extend these security properties to the 1227 additional server name. 1229 8. IANA Considerations 1231 8.1. Signaling Codes 1233 IANA is requested to create a third sub-registry for values of the 1234 Code field in the CoAP header (Section 12.1 of [RFC7252]). The name 1235 of this sub-registry is "CoAP Signaling Codes". 1237 Each entry in the sub-registry must include the Signaling Code in the 1238 range 7.01-7.31, its name, and a reference to its documentation. 1240 Initial entries in this sub-registry are as follows: 1242 +------+---------+-----------+ 1243 | Code | Name | Reference | 1244 +------+---------+-----------+ 1245 | 7.01 | CSM | [RFCthis] | 1246 | | | | 1247 | 7.02 | Ping | [RFCthis] | 1248 | | | | 1249 | 7.03 | Pong | [RFCthis] | 1250 | | | | 1251 | 7.04 | Release | [RFCthis] | 1252 | | | | 1253 | 7.05 | Abort | [RFCthis] | 1254 +------+---------+-----------+ 1256 Table 1: CoAP Signal Codes 1258 All other Signaling Codes are Unassigned. 1260 The IANA policy for future additions to this sub-registry is "IETF 1261 Review or IESG Approval" as described in [RFC5226]. 1263 8.2. CoAP Signaling Option Numbers Registry 1265 IANA is requested to create a sub-registry for signaling options 1266 similar to the CoAP Option Numbers Registry (Section 12.2 of 1267 [RFC7252]), with the single change that a fourth column is added to 1268 the sub-registry that is one of the codes in the Signaling Codes 1269 subregistry (Section 8.1). 1271 The name of this sub-registry is "CoAP Signaling Option Numbers". 1273 Initial entries in this sub-registry are as follows: 1275 +--------+------------+---------------------+-----------+ 1276 | Number | Applies to | Name | Reference | 1277 +--------+------------+---------------------+-----------+ 1278 | 1 | CSM | Server-Name | [RFCthis] | 1279 | | | | | 1280 | 2 | CSM | Max-Message-Size | [RFCthis] | 1281 | | | | | 1282 | 4 | CSM | Block-wise-Transfer | [RFCthis] | 1283 | | | | | 1284 | 2 | Ping, Pong | Custody | [RFCthis] | 1285 | | | | | 1286 | 2 | Release | Bad-Server-Name | [RFCthis] | 1287 | | | | | 1288 | 4 | Release | Alternative-Address | [RFCthis] | 1289 | | | | | 1290 | 6 | Release | Hold-Off | [RFCthis] | 1291 | | | | | 1292 | 2 | Abort | Bad-CSM-Option | [RFCthis] | 1293 +--------+------------+---------------------+-----------+ 1295 Table 2: CoAP Signal Option Codes 1297 The IANA policy for future additions to this sub-registry is based on 1298 number ranges for the option numbers, analogous to the policy defined 1299 in Section 12.2 of [RFC7252]. 1301 8.3. Service Name and Port Number Registration 1303 IANA is requested to assign the port number 5683 and the service name 1304 "coap+tcp", in accordance with [RFC6335]. 1306 Service Name. 1307 coap+tcp 1309 Transport Protocol. 1310 tcp 1312 Assignee. 1313 IESG 1315 Contact. 1316 IETF Chair 1318 Description. 1319 Constrained Application Protocol (CoAP) 1321 Reference. 1322 [RFCthis] 1324 Port Number. 1325 5683 1327 8.4. Secure Service Name and Port Number Registration 1329 IANA is requested to assign the port number 5684 and the service name 1330 "coaps+tcp", in accordance with [RFC6335]. The port number is 1331 requested to address the exceptional case of TLS implementations that 1332 do not support the "Application-Layer Protocol Negotiation Extension" 1333 [RFC7301]. 1335 Service Name. 1336 coaps+tcp 1338 Transport Protocol. 1339 tcp 1341 Assignee. 1342 IESG 1344 Contact. 1345 IETF Chair 1347 Description. 1348 Constrained Application Protocol (CoAP) 1350 Reference. 1351 [RFC7301], [RFCthis] 1353 Port Number. 1354 5684 1356 8.5. URI Scheme Registration 1358 This document registers two new URI schemes, namely "coap+tcp" and 1359 "coaps+tcp", for the use of CoAP over TCP and for CoAP over TLS over 1360 TCP, respectively. The "coap+tcp" and "coaps+tcp" URI schemes can 1361 thus be compared to the "http" and "https" URI schemes. 1363 The syntax of the "coap" and "coaps" URI schemes is specified in 1364 Section 6 of [RFC7252] and the present document re-uses their 1365 semantics for "coap+tcp" and "coaps+tcp", respectively, with the 1366 exception that TCP, or TLS over TCP is used as a transport protocol. 1368 IANA is requested to add these new URI schemes to the registry 1369 established with [RFC7595]. 1371 8.5.1. coap+ws 1373 This document requests the registration of the Uniform Resource 1374 Identifier (URI) scheme "coap+ws". The registration request complies 1375 with [RFC4395]. 1377 URL scheme name. 1378 coap+ws 1380 Status. 1381 Permanent 1383 URI scheme syntax. 1384 Defined in Section N of [RFCthis] 1386 URI scheme semantics. 1387 The "coap+ws" URI scheme provides a way to identify resources that 1388 are potentially accessible over the Constrained Application 1389 Protocol (CoAP) using the WebSocket protocol. 1391 Encoding considerations. 1392 The scheme encoding conforms to the encoding rules established for 1393 URIs in [RFC3986], i.e., internationalized and reserved characters 1394 are expressed using UTF-8-based percent-encoding. 1396 Applications/protocols that use this URI scheme name. 1397 The scheme is used by CoAP endpoints to access CoAP resources 1398 using the WebSocket protocol. 1400 Interoperability considerations. 1401 None. 1403 Security Considerations. 1404 See Section N of [RFCthis] 1406 Contact. 1407 IETF chair 1409 Author/Change controller. 1410 IESG 1412 References. 1413 [RFCthis] 1415 8.5.2. coap+wss 1417 This document requests the registration of the Uniform Resource 1418 Identifier (URI) scheme "coap+wss". The registration request 1419 complies with [RFC4395]. 1421 URL scheme name. 1422 coap+wss 1424 Status. 1425 Permanent 1427 URI scheme syntax. 1428 Defined in Section N of [RFCthis] 1430 URI scheme semantics. 1431 The "coap+ws" URI scheme provides a way to identify resources that 1432 are potentially accessible over the Constrained Application 1433 Protocol (CoAP) using the WebSocket protocol secured with 1434 Transport Layer Security (TLS). 1436 Encoding considerations. 1437 The scheme encoding conforms to the encoding rules established for 1438 URIs in [RFC3986], i.e., internationalized and reserved characters 1439 are expressed using UTF-8-based percent-encoding. 1441 Applications/protocols that use this URI scheme name. 1442 The scheme is used by CoAP endpoints to access CoAP resources 1443 using the WebSocket protocol secured with TLS. 1445 Interoperability considerations. 1446 None. 1448 Security Considerations. 1449 See Section N of [RFCthis] 1451 Contact. 1452 IETF chair 1454 Author/Change controller. 1455 IESG 1457 References. 1458 [RFCthis] 1460 8.6. Well-Known URI Suffix Registration 1462 IANA is requested to register the 'coap' well-known URI in the "Well- 1463 Known URIs" registry. This registration request complies with 1464 [RFC5785]: 1466 URI Suffix. 1467 coap 1469 Change controller. 1470 IETF 1472 Specification document(s). 1473 [RFCthis] 1475 Related information. 1476 None. 1478 8.7. ALPN Protocol Identifier 1480 IANA is requested to assign the following value in the registry 1481 "Application Layer Protocol Negotiation (ALPN) Protocol IDs" created 1482 by [RFC7301]. The "coap" string identifies CoAP when used over TLS. 1484 Protocol. 1485 CoAP 1487 Identification Sequence. 1488 0x63 0x6f 0x61 0x70 ("coap") 1490 Reference. 1491 [RFCthis] 1493 8.8. WebSocket Subprotocol Registration 1495 IANA is requested to register the WebSocket CoAP subprotocol under 1496 the "WebSocket Subprotocol Name Registry": 1498 Subprotocol Identifier. 1499 coap 1501 Subprotocol Common Name. 1502 Constrained Application Protocol (CoAP) 1504 Subprotocol Definition. 1505 [RFCthis] 1507 9. References 1509 9.1. Normative References 1511 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC 1512 793, DOI 10.17487/RFC0793, September 1981, 1513 . 1515 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1516 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1517 RFC2119, March 1997, 1518 . 1520 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1521 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1522 3986, DOI 10.17487/RFC3986, January 2005, 1523 . 1525 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 1526 Registration Procedures for New URI Schemes", RFC 4395, 1527 DOI 10.17487/RFC4395, February 2006, 1528 . 1530 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1531 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1532 DOI 10.17487/RFC5226, May 2008, 1533 . 1535 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1536 (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ 1537 RFC5246, August 2008, 1538 . 1540 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1541 Uniform Resource Identifiers (URIs)", RFC 5785, DOI 1542 10.17487/RFC5785, April 2010, 1543 . 1545 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 1546 6455, DOI 10.17487/RFC6455, December 2011, 1547 . 1549 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1550 Application Protocol (CoAP)", RFC 7252, DOI 10.17487/ 1551 RFC7252, June 2014, 1552 . 1554 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 1555 "Transport Layer Security (TLS) Application-Layer Protocol 1556 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1557 July 2014, . 1559 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 1560 and Registration Procedures for URI Schemes", BCP 35, RFC 1561 7595, DOI 10.17487/RFC7595, June 2015, 1562 . 1564 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1565 Application Protocol (CoAP)", RFC 7641, DOI 10.17487/ 1566 RFC7641, September 2015, 1567 . 1569 [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer 1570 Security (TLS) / Datagram Transport Layer Security (DTLS) 1571 Profiles for the Internet of Things", RFC 7925, DOI 1572 10.17487/RFC7925, July 2016, 1573 . 1575 9.2. Informative References 1577 [HomeGateway] 1578 Eggert, L., "An experimental study of home gateway 1579 characteristics", Proceedings of the 10th annual 1580 conference on Internet measurement, 2010. 1582 [I-D.becker-core-coap-sms-gprs] 1583 Becker, M., Li, K., Kuladinithi, K., and T. Poetsch, 1584 "Transport of CoAP over SMS", draft-becker-core-coap-sms- 1585 gprs-05 (work in progress), August 2014. 1587 [I-D.ietf-core-block] 1588 Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", 1589 draft-ietf-core-block-21 (work in progress), July 2016. 1591 [LWM2M] Open Mobile Alliance, "Lightweight Machine to Machine 1592 Technical Specification Candidate Version 1.0", April 1593 2016, . 1597 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, DOI 1598 10.17487/RFC0768, August 1980, 1599 . 1601 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1602 Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ 1603 RFC5234, January 2008, 1604 . 1606 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 1607 Cheshire, "Internet Assigned Numbers Authority (IANA) 1608 Procedures for the Management of the Service Name and 1609 Transport Protocol Port Number Registry", BCP 165, RFC 1610 6335, DOI 10.17487/RFC6335, August 2011, 1611 . 1613 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1614 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1615 January 2012, . 1617 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, DOI 1618 10.17487/RFC6454, December 2011, 1619 . 1621 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1622 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 1623 7230, DOI 10.17487/RFC7230, June 2014, 1624 . 1626 Appendix A. Negotiating Protocol Versions 1628 CoAP is defined in [RFC7252] with a version number of 1. At this 1629 time, there is no known reason to support version numbers different 1630 from 1. 1632 In contrast to the message layer for UDP and DTLS, the CoAP over TCP 1633 message format does not include a version number. If version 1634 negotiation needs to be addressed in the future, then Capability and 1635 Settings have been specifically designed to enable such a potential 1636 feature. 1638 Appendix B. CoAP over WebSocket Examples 1640 This section gives examples for the first two configurations 1641 discussed in Section 3. 1643 An example of the process followed by a CoAP client to retrieve the 1644 representation of a resource identified by a "coap+ws" URI might be 1645 as follows. Figure 19 below illustrates the WebSocket and CoAP 1646 messages exchanged in detail. 1648 1. The CoAP client obtains the URI , for example, from a resource representation 1650 that it retrieved previously. 1652 2. It establishes a WebSocket connection to the endpoint URI 1653 composed of the authority "example.org" and the well-known path 1654 "/.well-known/coap", . 1656 3. It sends a single-frame, masked, binary message containing a CoAP 1657 request. The request indicates the target resource with the Uri- 1658 Path ("sensors", "temperature") and Uri-Query ("u=Cel") options. 1660 4. It waits for the server to return a response. 1662 5. The CoAP client uses the connection for further requests, or the 1663 connection is closed. 1665 CoAP CoAP 1666 Client Server 1667 (WebSocket (WebSocket 1668 Client) Server) 1670 | | 1671 | | 1672 +=========>| GET /.well-known/coap HTTP/1.1 1673 | | Host: example.org 1674 | | Upgrade: websocket 1675 | | Connection: Upgrade 1676 | | Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 1677 | | Sec-WebSocket-Protocol: coap 1678 | | Sec-WebSocket-Version: 13 1679 | | 1680 |<=========+ HTTP/1.1 101 Switching Protocols 1681 | | Upgrade: websocket 1682 | | Connection: Upgrade 1683 | | Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 1684 | | Sec-WebSocket-Protocol: coap 1685 | | 1686 | | 1687 +--------->| Binary frame (opcode=%x2, FIN=1, MASK=1) 1688 | | +-------------------------+ 1689 | | | GET | 1690 | | | Token: 0x53 | 1691 | | | Uri-Path: "sensors" | 1692 | | | Uri-Path: "temperature" | 1693 | | | Uri-Query: "u=Cel" | 1694 | | +-------------------------+ 1695 | | 1696 |<---------+ Binary frame (opcode=%x2, FIN=1, MASK=0) 1697 | | +-------------------------+ 1698 | | | 2.05 Content | 1699 | | | Token: 0x53 | 1700 | | | Payload: "22.3 Cel" | 1701 | | +-------------------------+ 1702 : : 1703 : : 1704 | | 1705 +--------->| Close frame (opcode=%x8, FIN=1, MASK=1) 1706 | | 1707 |<---------+ Close frame (opcode=%x8, FIN=1, MASK=0) 1708 | | 1710 Figure 19: A CoAP client retrieves the representation of a resource 1711 identified by a "coap+ws" URI 1713 Figure 20 shows how a CoAP client uses a CoAP forward proxy with a 1714 WebSocket endpoint to retrieve the representation of the resource 1715 "coap://[2001:DB8::1]/". The use of the forward proxy and the 1716 address of the WebSocket endpoint are determined by the client from 1717 local configuration rules. The request URI is specified in the 1718 Proxy-Uri Option. Since the request URI uses the "coap" URI scheme, 1719 the proxy fulfills the request by issuing a Confirmable GET request 1720 over UDP to the CoAP server and returning the response over the 1721 WebSocket connection to the client. 1723 CoAP CoAP CoAP 1724 Client Proxy Server 1725 (WebSocket (WebSocket (UDP 1726 Client) Server) Endpoint) 1728 | | | 1729 +--------->| | Binary frame (opcode=%x2, FIN=1, MASK=1) 1730 | | | +------------------------------------+ 1731 | | | | GET | 1732 | | | | Token: 0x7d | 1733 | | | | Proxy-Uri: "coap://[2001:DB8::1]/" | 1734 | | | +------------------------------------+ 1735 | | | 1736 | +--------->| CoAP message (Ver=1, T=Con, MID=0x8f54) 1737 | | | +------------------------------------+ 1738 | | | | GET | 1739 | | | | Token: 0x0a15 | 1740 | | | +------------------------------------+ 1741 | | | 1742 | |<---------+ CoAP message (Ver=1, T=Ack, MID=0x8f54) 1743 | | | +------------------------------------+ 1744 | | | | 2.05 Content | 1745 | | | | Token: 0x0a15 | 1746 | | | | Payload: "ready" | 1747 | | | +------------------------------------+ 1748 | | | 1749 |<---------+ | Binary frame (opcode=%x2, FIN=1, MASK=0) 1750 | | | +------------------------------------+ 1751 | | | | 2.05 Content | 1752 | | | | Token: 0x7d | 1753 | | | | Payload: "ready" | 1754 | | | +------------------------------------+ 1755 | | | 1757 Figure 20: A CoAP client retrieves the representation of a resource 1758 identified by a "coap" URI via a WebSockets-enabled CoAP proxy 1760 Appendix C. Change Log 1762 The RFC Editor is requested to remove this section at publication. 1764 C.1. Since draft-core-coap-tcp-tls-02 1766 Merged draft-savolainen-core-coap-websockets-07 Merged draft-bormann- 1767 core-block-bert-01 Merged draft-bormann-core-coap-sig-02 1769 C.2. Since draft-core-coap-tcp-tls-03 1771 Editorial updates 1773 Added mandatory exchange of Capabilities and Settings messages after 1774 connecting 1776 Added support for coaps+tcp port 5684 and more details on 1777 Application-Layer Protocol Negotiation (ALPN) 1779 Added guidance on CoAP Signaling Ping-Pong versus WebSocket Ping-Pong 1781 Updated references and requirements for TLS security considerations 1783 Acknowledgements 1785 We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier 1786 Delaby, Christian Groves, Nadir Javed, Michael Koster, Matthias 1787 Kovatsch, Achim Kraus, David Navarro, Szymon Sasin, Zach Shelby, 1788 Andrew Summers, Julien Vermillard, and Gengyu Wei for their feedback. 1790 Contributors 1792 Valik Solorzano Barboza 1793 Zebra Technologies 1794 820 W. Jackson Blvd. Suite 700 1795 Chicago 60607 1796 United States of America 1798 Phone: +1-847-634-6700 1799 Email: vsolorzanobarboza@zebra.com 1801 Teemu Savolainen 1802 Nokia Technologies 1803 Hatanpaan valtatie 30 1804 Tampere FI-33100 1805 Finland 1807 Email: teemu.savolainen@nokia.com 1809 Authors' Addresses 1811 Carsten Bormann 1812 Universitaet Bremen TZI 1813 Postfach 330440 1814 Bremen D-28359 1815 Germany 1817 Phone: +49-421-218-63921 1818 Email: cabo@tzi.org 1820 Simon Lemay 1821 Zebra Technologies 1822 820 W. Jackson Blvd. Suite 700 1823 Chicago 60607 1824 United States of America 1826 Phone: +1-847-634-6700 1827 Email: slemay@zebra.com 1829 Hannes Tschofenig 1830 ARM Ltd. 1831 110 Fulbourn Rd 1832 Cambridge CB1 9NJ 1833 Great Britain 1835 Email: Hannes.tschofenig@gmx.net 1836 URI: http://www.tschofenig.priv.at 1838 Klaus Hartke 1839 Universitaet Bremen TZI 1840 Postfach 330440 1841 Bremen D-28359 1842 Germany 1844 Phone: +49-421-218-63905 1845 Email: hartke@tzi.org 1846 Bilhanan Silverajan 1847 Tampere University of Technology 1848 Korkeakoulunkatu 10 1849 Tampere FI-33720 1850 Finland 1852 Email: bilhanan.silverajan@tut.fi 1854 Brian Raymor (editor) 1855 Microsoft 1856 One Microsoft Way 1857 Redmond 98052 1858 United States of America 1860 Email: brian.raymor@microsoft.com