idnits 2.17.1 draft-ietf-core-coap-tcp-tls-05.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. -- The draft header indicates that this document updates RFC7641, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 11, 2016) is 2753 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 257, but not defined == Missing Reference: '------' is mentioned on line 257, but not defined == Missing Reference: 'RFCthis' is mentioned on line 1503, but not defined ** 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) -- 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 (~~), 4 warnings (==), 4 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 Updates: 7641 (if approved) S. Lemay 5 Intended status: Standards Track Zebra Technologies 6 Expires: April 14, 2017 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 October 11, 2016 16 CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets 17 draft-ietf-core-coap-tcp-tls-05 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 April 14, 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 . . . . . . . . . . . . . . . . . . . . . 7 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 . . . . . . . . . . . . . . . . . . . . 15 78 3.5. Closing the Connection . . . . . . . . . . . . . . . . . 15 79 4. Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . 15 80 4.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 16 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 . . . . . . . . . . . . . . . . 26 93 7. Security Considerations . . . . . . . . . . . . . . . . . . . 27 94 7.1. Signaling Messages . . . . . . . . . . . . . . . . . . . 27 95 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 96 8.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 28 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. Updates to RFC7641 Observing Resources in the 108 Constrained Application Protocol (CoAP) . . . . . . 36 109 A.1. Notifications and Reordering . . . . . . . . . . . . . . 36 110 A.2. Transmission and Acknowledgements . . . . . . . . . . . . 36 111 A.3. Cancellation . . . . . . . . . . . . . . . . . . . . . . 37 112 Appendix B. Negotiating Protocol Versions . . . . . . . . . . . 37 113 Appendix C. CoAP over WebSocket Examples . . . . . . . . . . . . 37 114 Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 41 115 D.1. Since draft-core-coap-tcp-tls-02 . . . . . . . . . . . . 41 116 D.2. Since draft-core-coap-tcp-tls-03 . . . . . . . . . . . . 41 117 D.3. Since draft-core-coap-tcp-tls-04 . . . . . . . . . . . . 41 118 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 41 119 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 41 120 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 122 1. Introduction 124 The Constrained Application Protocol (CoAP) [RFC7252] was designed 125 for Internet of Things (IoT) deployments, assuming that UDP [RFC0768] 126 or DTLS [RFC6347] over UDP can be used unimpeded. UDP is a good 127 choice for transferring small amounts of data across networks that 128 follow the IP architecture. 130 Some CoAP deployments need to integrate well with existing enterprise 131 infrastructures, where UDP-based protocols may not be well-received 132 or may even be blocked by firewalls. Middleboxes that are unaware of 133 CoAP usage for IoT can make the use of UDP brittle, resulting in lost 134 or malformed packets. 136 Emerging standards such as Lightweight Machine to Machine [LWM2M] 137 currently use CoAP over UDP as a transport and require support for 138 CoAP over TCP to address the issues above and to protect investments 139 in existing CoAP implementations and deployments. Although HTTP/2 140 could also potentially address these requirements, there would be 141 additional costs and delays introduced by such a transition. 142 Currently, there are also fewer HTTP/2 implementations available for 143 constrained devices in comparison to CoAP. 145 To address these requirements, this document defines how to transport 146 CoAP over TCP, CoAP over TLS, and CoAP over WebSockets. Figure 1 147 illustrates the layering: 149 +--------------------------------+ 150 | Application | 151 +--------------------------------+ 152 +--------------------------------+ 153 | Requests/Responses/Signaling | CoAP (RFC 7252) / This Document 154 |--------------------------------| 155 | Message Framing | This Document 156 +--------------------------------+ 157 | Reliable Transport | 158 +--------------------------------+ 160 Figure 1: Layering of CoAP over Reliable Transports 162 Where NATs are present, CoAP over TCP can help with their traversal. 163 NATs often calculate expiration timers based on the transport layer 164 protocol being used by application protocols. Many NATs maintain 165 TCP-based NAT bindings for longer periods based on the assumption 166 that a transport layer protocol, such as TCP, offers additional 167 information about the session life cycle. UDP, on the other hand, 168 does not provide such information to a NAT and timeouts tend to be 169 much shorter [HomeGateway]. 171 Some environments may also benefit from the ability of TCP to 172 exchange larger payloads, such as firmware images, without 173 application layer segmentation and to utilize the more sophisticated 174 congestion control capabilities provided by many TCP implementations. 176 CoAP may be integrated into a Web environment where the front-end 177 uses CoAP over UDP from IoT devices to a cloud infrastructure and 178 then CoAP over TCP between the back-end services. A TCP-to-UDP 179 gateway can be used at the cloud boundary to communicate with the 180 UDP-based IoT device. 182 To allow IoT devices to better communicate in these demanding 183 environments, CoAP needs to support different transport protocols, 184 namely TCP [RFC0793], in some situations secured by TLS [RFC5246]. 186 In addition, some corporate networks only allow Internet access via a 187 HTTP proxy. In this case, the best transport for CoAP would be the 188 WebSocket Protocol [RFC6455]. The WebSocket protocol provides two- 189 way communication between a client and a server after upgrading an 190 HTTP/1.1 [RFC7230] connection and may be available in an environment 191 that blocks CoAP over UDP. Another scenario for CoAP over WebSockets 192 is a CoAP application running inside a web browser without access to 193 connectivity other than HTTP and WebSockets. 195 This document specifies how to access resources using CoAP requests 196 and responses over the TCP/TLS and WebSocket protocols. This allows 197 connectivity-limited applications to obtain end-to-end CoAP 198 connectivity either by communicating CoAP directly with a CoAP server 199 accessible over a TCP/TLS or WebSocket connection or via a CoAP 200 intermediary that proxies CoAP requests and responses between 201 different transports, such as between WebSockets and UDP. 203 1.1. Terminology 205 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 206 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 207 "OPTIONAL" in this document are to be interpreted as described in 208 [RFC2119]. 210 This document assumes that readers are familiar with the terms and 211 concepts that are used in [RFC6455], [RFC7252], and [RFC7641]. 213 The term "reliable transport" only refers to stream-based transport 214 protocols such as TCP. 216 BERT Option: 217 A Block1 or Block2 option that includes an SZX value of 7. 219 BERT Block: 220 The payload of a CoAP message that is affected by a BERT Option in 221 descriptive usage (Section 2.1 of [RFC7959]). 223 2. CoAP over TCP 225 The request/response interaction model of CoAP over TCP is the same 226 as CoAP over UDP. The primary differences are in the message layer. 227 CoAP over UDP supports optional reliability by defining four types of 228 messages: Confirmable, Non-confirmable, Acknowledgement, and Reset. 229 TCP eliminates the need for the message layer to support reliability. 230 As a result, message types are not defined in CoAP over TCP. 232 2.1. Messaging Model 234 Conceptually, CoAP over TCP replaces most of the CoAP over UDP 235 message layer with a framing mechanism on top of the byte stream 236 provided by TCP/TLS, conveying the length information for each 237 message that on datagram transports is provided by the UDP/DTLS 238 datagram layer. 240 TCP ensures reliable message transmission, so the CoAP over TCP 241 messaging layer is not required to support acknowledgements or 242 detection of duplicate messages. As a result, both the Type and 243 Message ID fields are no longer required and are removed from the 244 CoAP over TCP message format. All messages are also untyped. 246 Figure 2 illustrates the difference between CoAP over UDP and CoAP 247 over reliable transport. The removed Type and Message ID fields are 248 indicated by dashes. 250 Client Server Client Server 251 | | | | 252 | CON [0xbc90] | | (-------) [------] | 253 | GET /temperature | | GET /temperature | 254 | (Token 0x71) | | (Token 0x71) | 255 +------------------->| +------------------->| 256 | | | | 257 | ACK [0xbc90] | | (-------) [------] | 258 | 2.05 Content | | 2.05 Content | 259 | (Token 0x71) | | (Token 0x71) | 260 | "22.5 C" | | "22.5 C" | 261 |<-------------------+ |<-------------------+ 262 | | | | 264 CoAP over UDP CoAP over reliable 265 transport 267 Figure 2: Comparison between CoAP over unreliable and reliable 268 transport. 270 2.2. UDP-to-TCP gateways 272 A UDP-to-TCP gateway MUST discard all Empty messages (Code 0.00) 273 after processing at the message layer. For Confirmable (CON), Non- 274 Confirmable (NOM), and Acknowledgement (ACK) messages that are not 275 Empty, their contents are repackaged into untyped messages. 277 2.3. Opening Handshake 279 Both the client and the server MUST send a Capability and Settings 280 message (CSM see Section 4.3) as its first message on the connection. 281 This message establishes the initial settings and capabilities for 282 the endpoint such as maximum message size or support for block-wise 283 transfers. The absence of options in the CSM indicates that base 284 values are assumed. 286 To avoid unnecessary latency, a client MAY send additional messages 287 without waiting to receive the server CSM; however, it is important 288 to note that the server CSM might advertise capabilities that impact 289 how a client is expected to communicate with the server. For 290 example, the server CSM could advertise a Max-Message-Size option 291 (See Section 4.3.2) that is smaller than the base value (1152). 293 Clients and servers MUST treat a missing or invalid CSM as a 294 connection error and abort the connection (see Section 4.6). 296 2.4. Message Format 298 The CoAP message format defined in [RFC7252], as shown in Figure 3, 299 relies on the datagram transport (UDP, or DTLS over UDP) for keeping 300 the individual messages separate and for providing length 301 information. 303 0 1 2 3 304 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 305 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 306 |Ver| T | TKL | Code | Message ID | 307 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 308 | Token (if any, TKL bytes) ... 309 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 310 | Options (if any) ... 311 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 312 |1 1 1 1 1 1 1 1| Payload (if any) ... 313 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 315 Figure 3: RFC 7252 defined CoAP Message Format. 317 The CoAP over TCP message format is very similar to the format 318 specified for CoAP over UDP. The differences are as follows: 320 o Since the underlying TCP connection provides retransmissions and 321 deduplication, there is no need for the reliability mechanisms 322 provided by CoAP over UDP. The "T" and "Message ID" fields in the 323 CoAP message header are elided. 325 o The "Ver" field is elided as well. In constrast to the UDP 326 message layer for UDP and DTLS, the CoAP over TCP message layer 327 does not send a version number in each message. If required in 328 the future, a new Capability and Settings Option (See Appendix B) 329 could be defined to support version negotiation. 331 o In a stream oriented transport protocol such as TCP, a form of 332 message delimitation is needed. For this purpose, CoAP over TCP 333 introduces a length field with variable size. Figure 4 shows the 334 adjusted CoAP message format with a modified structure for the 335 fixed header (first 4 bytes of the CoAP over UDP header), which 336 includes the length information of variable size, shown here as an 337 8-bit length. 339 0 1 2 3 340 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 341 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 342 |Len=13 | TKL |Extended Length| Code | TKL bytes ... 343 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 344 | Options (if any) ... 345 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 346 |1 1 1 1 1 1 1 1| Payload (if any) ... 347 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 349 Figure 4: CoAP frame with 8-bit Extended Length field. 351 Length (Len): 4-bit unsigned integer. A value between 0 and 12 352 directly indicates the length of the message in bytes starting 353 with the first bit of the Options field. Three values are 354 reserved for special constructs: 356 13: An 8-bit unsigned integer (Extended Length) follows the 357 initial byte and indicates the length of options/payload minus 358 13. 360 14: A 16-bit unsigned integer (Extended Length) in network byte 361 order follows the initial byte and indicates the length of 362 options/payload minus 269. 364 15: A 32-bit unsigned integer (Extended Length) in network byte 365 order follows the initial byte and indicates the length of 366 options/payload minus 65805. 368 The encoding of the Length field is modeled on CoAP Options (see 369 section 3.1 of [RFC7252]). 371 The following figures show the message format for the 0-bit, 16-bit, 372 and the 32-bit variable length cases. 374 0 1 2 3 375 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 376 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 377 | Len | TKL | Code | Token (if any, TKL bytes) ... 378 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 379 | Options (if any) ... 380 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 381 |1 1 1 1 1 1 1 1| Payload (if any) ... 382 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 384 Figure 5: CoAP message format without an Extended Length field. 386 For example: A CoAP message just containing a 2.03 code with the 387 token 7f and no options or payload would be encoded as shown in 388 Figure 6. 390 0 1 2 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 392 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 393 | 0x01 | 0x43 | 0x7f | 394 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 396 Len = 0 ------> 0x01 397 TKL = 1 ___/ 398 Code = 2.03 --> 0x43 399 Token = 0x7f 401 Figure 6: CoAP message with no options or payload. 403 0 1 2 3 404 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 405 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 406 |Len=14 | TKL | Extended Length (16 bits) | Code | 407 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 408 | Token (if any, TKL bytes) ... 409 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 410 | Options (if any) ... 411 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 412 |1 1 1 1 1 1 1 1| Payload (if any) ... 413 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 415 Figure 7: CoAP message format with 16-bit Extended Length field. 417 0 1 2 3 418 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 419 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 420 |Len=15 | TKL | Extended Length (32 bits) 421 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 422 | | Code | Token (if any, TKL bytes) ... 423 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 424 | Options (if any) ... 425 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 426 |1 1 1 1 1 1 1 1| Payload (if any) ... 427 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 429 Figure 8: CoAP message format with 32-bit Extended Length field. 431 The semantics of the other CoAP header fields are left unchanged. 433 2.5. Message Transmission 435 CoAP requests and responses are exchanged asynchronously over the 436 TCP/TLS connection. A CoAP client can send multiple requests without 437 waiting for a response and the CoAP server can return responses in 438 any order. Responses MUST be returned over the same connection as 439 the originating request. Concurrent requests are differentiated by 440 their Token, which is scoped locally to the connection. 442 The connection is bi-directional, so requests can be sent both by the 443 entity that established the connection and the remote host. 445 Retransmission and deduplication of messages is provided by the TCP/ 446 TLS protocol. 448 3. CoAP over WebSockets 450 CoAP over WebSockets can be used in a number of configurations. The 451 most basic configuration is a CoAP client retrieving or updating a 452 CoAP resource located at a CoAP server that exposes a WebSocket 453 endpoint (Figure 9). The CoAP client acts as the WebSocket client, 454 establishes a WebSocket connection, and sends a CoAP request, to 455 which the CoAP server returns a CoAP response. The WebSocket 456 connection can be used for any number of requests. 458 ___________ ___________ 459 | | | | 460 | _|___ requests ___|_ | 461 | CoAP / \ \ -------------> / / \ CoAP | 462 | Client \__/__/ <------------- \__\__/ Server | 463 | | responses | | 464 |___________| |___________| 465 WebSocket =============> WebSocket 466 Client Connection Server 468 Figure 9: CoAP Client (WebSocket client) accesses CoAP Server 469 (WebSocket server) 471 The challenge with this configuration is how to identify a resource 472 in the namespace of the CoAP server. When the WebSocket protocol is 473 used by a dedicated client directly (i.e., not from a web page 474 through a web browser), the client can connect to any WebSocket 475 endpoint. This means it is necessary for the client to identify both 476 the WebSocket endpoint (identified by a "ws" or "wss" URI) and the 477 path and query of the CoAP resource within that endpoint from the 478 same URI. When the WebSocket protocol is used from a web page, the 479 choices are more limited [RFC6454], but the challenge persists. 481 Section 6.2 defines a new "coap+ws" URI scheme that identifies both a 482 WebSocket endpoint and a resource within that endpoint as follows: 484 coap+ws://example.org/sensors/temperature?u=Cel 485 \______ ______/\___________ ___________/ 486 \/ \/ 487 Uri-Path: "sensors" 488 ws://example.org/.well-known/coap Uri-Path: "temperature" 489 Uri-Query: "u=Cel" 491 Figure 10: The "coap+ws" URI Scheme 493 Another possible configuration is to set up a CoAP forward proxy at 494 the WebSocket endpoint. Depending on what transports are available 495 to the proxy, it could forward the request to a CoAP server with a 496 CoAP UDP endpoint (Figure 11), an SMS endpoint (a.k.a. mobile phone), 497 or even another WebSocket endpoint. The client specifies the 498 resource to be updated or retrieved in the Proxy-URI Option. 500 ___________ ___________ ___________ 501 | | | | | | 502 | _|___ ___|_ _|___ ___|_ | 503 | CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP | 504 | Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server | 505 | | | | | | 506 |___________| |___________| |___________| 507 WebSocket ===> WebSocket UDP UDP 508 Client Server Client Server 510 Figure 11: CoAP Client (WebSocket client) accesses CoAP Server (UDP 511 server) via a CoAP proxy (WebSocket server/UDP client) 513 A third possible configuration is a CoAP server running inside a web 514 browser (Figure 12). The web browser initially connects to a 515 WebSocket endpoint and is then reachable through the WebSocket 516 server. When no connection exists, the CoAP server is unreachable. 517 Because the WebSocket server is the only way to reach the CoAP 518 server, the CoAP proxy should be a Reverse Proxy. 520 ___________ ___________ ___________ 521 | | | | | | 522 | _|___ ___|_ _|___ ___|_ | 523 | CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP | 524 | Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server | 525 | | | | | | 526 |___________| |___________| |___________| 527 UDP UDP WebSocket <=== WebSocket 528 Client Server Server Client 530 Figure 12: CoAP Client (UDP client) accesses sleepy CoAP Server 531 (WebSocket client) via a CoAP proxy (UDP server/WebSocket server) 533 Further configurations are possible, including those where a 534 WebSocket connection is established through an HTTP proxy. 536 CoAP over WebSockets is intentionally very similar to CoAP over UDP. 537 Therefore, instead of presenting CoAP over WebSockets as a new 538 protocol, this document specifies it as a series of deltas from 539 [RFC7252]. 541 3.1. Opening Handshake 543 Before CoAP requests and responses are exchanged, a WebSocket 544 connection is established as defined in Section 4 of [RFC6455]. 545 Figure 13 shows an example. 547 The WebSocket client MUST include the subprotocol name "coap" in the 548 list of protocols, which indicates support for the protocol defined 549 in this document. Any later, incompatible versions of CoAP or CoAP 550 over WebSockets will use a different subprotocol name. 552 The WebSocket client includes the hostname of the WebSocket server in 553 the Host header field of its handshake as per [RFC6455]. The Host 554 header field also indicates the default value of the Uri-Host Option 555 in requests from the WebSocket client to the WebSocket server. 557 GET /.well-known/coap HTTP/1.1 558 Host: example.org 559 Upgrade: websocket 560 Connection: Upgrade 561 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 562 Sec-WebSocket-Protocol: coap 563 Sec-WebSocket-Version: 13 565 HTTP/1.1 101 Switching Protocols 566 Upgrade: websocket 567 Connection: Upgrade 568 Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 569 Sec-WebSocket-Protocol: coap 571 Figure 13: Example of an Opening Handshake 573 3.2. Message Format 575 Once a WebSocket connection is established, CoAP requests and 576 responses can be exchanged as WebSocket messages. Since CoAP uses a 577 binary message format, the messages are transmitted in binary data 578 frames as specified in Sections 5 and 6 of [RFC6455]. 580 The message format shown in Figure 14 is the same as the CoAP over 581 TCP message format (see Section 2.4) with one restriction. The 582 Length (Len) field MUST be set to zero because the WebSockets frame 583 contains the length. 585 0 1 2 3 586 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 587 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 588 | Len | TKL | Code | Token (TKL bytes) ... 589 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 590 | Options (if any) ... 591 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 592 |1 1 1 1 1 1 1 1| Payload (if any) ... 593 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 595 Figure 14: CoAP Message Format over WebSockets 597 The CoAP over TCP message format eliminates the Version field defined 598 in CoAP over UDP. If CoAP version negotiation is required in the 599 future, CoAP over WebSockets can address the requirement by the 600 definition of a new subprotocol identifier that is negotiated during 601 the opening handshake. 603 Requests and response messages can be fragmented as specified in 604 Section 5.4 of [RFC6455], though typically they are sent unfragmented 605 as they tend to be small and fully buffered before transmission. The 606 WebSocket protocol does not provide means for multiplexing. If it is 607 not desirable for a large message to monopolize the connection, 608 requests and responses can be transferred in a block-wise fashion as 609 defined in [RFC7959]. 611 Empty messages (Code 0.00) MUST be ignored by the recipient (see also 612 Section 4.4). 614 3.3. Message Transmission 616 CoAP requests and responses are exchanged asynchronously over the 617 WebSocket connection. A CoAP client can send multiple requests 618 without waiting for a response and the CoAP server can return 619 responses in any order. Responses MUST be returned over the same 620 connection as the originating request. Concurrent requests are 621 differentiated by their Token, which is scoped locally to the 622 connection. 624 The connection is bi-directional, so requests can be sent both by the 625 entity that established the connection and the remote host. 627 Retransmission and deduplication of messages is provided by the 628 WebSocket protocol. CoAP over WebSockets therefore does not make a 629 distinction between Confirmable or Non-Confirmable messages, and does 630 not provide Acknowledgement or Reset messages. 632 3.4. Connection Health 634 When a client does not receive any response for some time after 635 sending a CoAP request (or, similarly, when a client observes a 636 resource and it does not receive any notification for some time), the 637 connection between the WebSocket client and the WebSocket server may 638 be lost or temporarily disrupted without the client being aware of 639 it. 641 To check the health of the WebSocket connection (and thereby of all 642 active requests, if any), a client can send a CoAP Ping Signaling 643 message (Section 4.4). WebSocket Ping and unsolicited Pong frames as 644 specified in Section 5.5 of [RFC6455] SHOULD NOT be used to ensure 645 that redundant maintenance traffic is not transmitted. 647 There is no way to retransmit a request without creating a new one. 648 Re-registering interest in a resource is permitted, but entirely 649 unnecessary. 651 3.5. Closing the Connection 653 The WebSocket connection is closed as specified in Section 7 of 654 [RFC6455]. 656 All requests for which the CoAP client has not received a response 657 yet are cancelled when the connection is closed. 659 4. Signaling 661 Signaling messages are introduced to allow peers to: 663 o Share characteristics such as maximum message size for the 664 connection 666 o Shutdown the connection in an ordered fashion 668 o Terminate the connection in response to a serious error condition 670 Signaling is a third basic kind of message in CoAP, after requests 671 and responses. Signaling messages share a common structure with the 672 existing CoAP messages. There is a code, a token, options, and an 673 optional payload. 675 (See Section 3 of [RFC7252] for the overall structure, as adapted to 676 the specific transport.) 678 4.1. Signaling Codes 680 A code in the 7.01-7.31 range indicates a Signaling message. Values 681 in this range are assigned by the "CoAP Signaling Codes" sub-registry 682 (see Section 8.1). 684 For each message, there is a sender and a peer receiving the message. 686 Payloads in Signaling messages are diagnostic payloads (see 687 Section 5.5.2 of [RFC7252]), unless otherwise defined by a Signaling 688 message option. 690 4.2. Signaling Option Numbers 692 Option numbers for Signaling messages are specific to the message 693 code. They do not share the number space with CoAP options for 694 request/response messages or with Signaling messages using other 695 codes. 697 Option numbers are assigned by the "CoAP Signaling Option Numbers" 698 sub-registry (see Section 8.2). 700 Signaling options are elective or critical as defined in 701 Section 5.4.1 of [RFC7252]). If a Signaling option is critical and 702 not understood by the receiver, it MUST abort the connection (see 703 Section 4.6). If the option is understood but cannot be processed, 704 the option documents the behavior. 706 4.3. Capability and Settings Messages (CSM) 708 Capability and Settings messages (CSM) are used for two purposes: 710 o Each capability option advertises one capability of the sender to 711 the recipient. 713 o Setting options indicate a setting that will be applied by the 714 sender. 716 A Capability and Settings message MUST be sent by both endpoints at 717 the start of the connection and MAY be sent at any other time by 718 either endpoint over the lifetime of the connection. 720 Both capability and settings options are cumulative. A Capability 721 and Settings message does not invalidate a previously sent capability 722 indication or setting even if it is not repeated. A capability 723 message without any option is a no-operation (and can be used as 724 such). An option that is sent might override a previous value for 725 the same option. The option defines how to handle this case if 726 needed. 728 Base values are listed below for CSM Options. These are the values 729 for the Capability and Setting before any Capability and Settings 730 messages send a modified value. 732 These are not default values for the option as defined in 733 Section 5.4.4 in [RFC7252]. A default value would mean that an empty 734 Capability and Settings message would result in the option being set 735 to its default value. 737 Capability and Settings messages are indicated by the 7.01 code 738 (CSM). 740 4.3.1. Server-Name Setting Option 742 +--------+------------+-------------+--------+--------+-------------+ 743 | Number | Applies to | Name | Format | Length | Base Value | 744 +--------+------------+-------------+--------+--------+-------------+ 745 | 1 | CSM | Server-Name | string | 1-255 | (see below) | 746 +--------+------------+-------------+--------+--------+-------------+ 748 A client can use the Server-Name critical option to indicate the 749 default value for the Uri-Host Options in the messages that it sends 750 to the server. It has the same restrictions as the Uri-Host Option 751 (Section 5.10 of [RFC7252]. 753 For TLS, the initial value for the Server-Name Option is given by the 754 SNI value. 756 For Websockets, the initial value for the Server-Name Option is given 757 by the HTTP Host header field. 759 4.3.2. Max-Message-Size Capability Option 761 The sender can use the Max-Message-Size elective option to indicate 762 the maximum message size in bytes that it can receive. 764 +--------+-----------+------------------+--------+--------+---------+ 765 | Number | Applies | Name | Format | Length | Base | 766 | | to | | | | Value | 767 +--------+-----------+------------------+--------+--------+---------+ 768 | 2 | CSM | Max-Message-Size | uint | 0-4 | 1152 | 769 +--------+-----------+------------------+--------+--------+---------+ 771 As per Section 4.6 of [RFC7252], the base value (and the value used 772 when this option is not implemented) is 1152. A peer that relies on 773 this option being indicated with a certain minimum value will enjoy 774 limited interoperability. 776 4.3.3. Block-wise Transfer Capability Option 778 +--------+-----------+----------------+--------+--------+-----------+ 779 | Number | Applies | Name | Format | Length | Base | 780 | | to | | | | Value | 781 +--------+-----------+----------------+--------+--------+-----------+ 782 | 4 | CSM | Block-wise | empty | 0 | (none) | 783 | | | Transfer | | | | 784 +--------+-----------+----------------+--------+--------+-----------+ 786 A sender can use the Block-wise Transfer elective Option to indicate 787 that it supports the block-wise transfer protocol [RFC7959]. 789 If the option is not given, the peer has no information about whether 790 block-wise transfers are supported by the sender or not. An 791 implementation that supports block-wise transfers SHOULD indicate the 792 Block-wise Transfer Option. If a Max-Message-Size Option is 793 indicated with a value that is greater than 1152 (in the same or a 794 different CSM message), the Block-wise Transfer Option also indicates 795 support for BERT (see Section 5). 797 4.4. Ping and Pong Messages 799 In CoAP over TCP, Empty messages (Code 0.00) can always be sent and 800 MUST be ignored by the recipient. This provides a basic keep-alive 801 function that can refresh NAT bindings. In contrast, Ping and Pong 802 messages are a bidirectional exchange. 804 Upon receipt of a Ping message, a single Pong message is returned 805 with the identical token. As with all Signaling messages, the 806 recipient of a Ping or Pong message MUST ignore elective options it 807 does not understand. 809 Ping and Pong messages are indicated by the 7.02 code (Ping) and the 810 7.03 code (Pong). 812 4.4.1. Custody Option 814 +--------+------------+---------+--------+--------+------------+ 815 | Number | Applies to | Name | Format | Length | Base Value | 816 +--------+------------+---------+--------+--------+------------+ 817 | 2 | Ping, Pong | Custody | empty | 0 | (none) | 818 +--------+------------+---------+--------+--------+------------+ 820 A peer replying to a Ping message can add a Custody elective option 821 to the Pong message it returns. This option indicates that the 822 application has processed all request/response messages that it has 823 received in the present connection ahead of the Ping message that 824 prompted the Pong message. (Note that there is no definition of 825 specific application semantics of "processed", but there is an 826 expectation that the sender of the Ping leading to the Pong with a 827 Custody Option should be able to free buffers based on this 828 indication.) 830 A Custody elective option can also be sent in a Ping message to 831 explicitly request the return of a Custody Option in the Pong 832 message. A peer is always free to indicate that it has finished 833 processing all previous request/response messages by sending a 834 Custody Option in a Pong message. A peer is also free NOT to send a 835 Custody Option in case it is still processing previous request/ 836 response messages; however, it SHOULD delay its response to a Ping 837 with a Custody Option until it can also return one. 839 4.5. Release Messages 841 A release message indicates that the sender does not want to continue 842 maintaining the connection and opts for an orderly shutdown; the 843 details are in the options. A diagnostic payload MAY be included. A 844 release message will normally be replied to by the peer by closing 845 the TCP/TLS connection. Messages may be in flight when the sender 846 decides to send a Release message. The general expectation is that 847 these will still be processed. 849 Release messages are indicated by the 7.04 code (Release). 851 Release messages can indicate one or more reasons using elective 852 options. The following options are defined: 854 +--------+-----------+-----------------+--------+--------+----------+ 855 | Number | Applies | Name | Format | Length | Base | 856 | | to | | | | Value | 857 +--------+-----------+-----------------+--------+--------+----------+ 858 | 2 | Release | Bad-Server-Name | empty | 0 | (none) | 859 +--------+-----------+-----------------+--------+--------+----------+ 861 The Bad-Server-Name elective option indicates that the default 862 indicated by the CSM Server-Name Option is unlikely to be useful for 863 this server. 865 +--------+----------+-------------------+--------+--------+---------+ 866 | Number | Applies | Name | Format | Length | Base | 867 | | to | | | | Value | 868 +--------+----------+-------------------+--------+--------+---------+ 869 | 4 | Release | Alternate-Address | string | 1-255 | (none) | 870 +--------+----------+-------------------+--------+--------+---------+ 872 The Alternative-Address elective option requests the peer to instead 873 open a connection of the same scheme as the present connection to the 874 alternative transport address given. Its value is in the form 875 "authority" as defined in Section 3.2 of [RFC3986]. 877 +--------+------------+----------+--------+--------+------------+ 878 | Number | Applies to | Name | Format | Length | Base Value | 879 +--------+------------+----------+--------+--------+------------+ 880 | 6 | Release | Hold-Off | uint | 0-3 | (none) | 881 +--------+------------+----------+--------+--------+------------+ 883 The Hold-Off elective option indicates that the server is requesting 884 that the peer not reconnect to it for the number of seconds given in 885 the value. 887 4.6. Abort Messages 889 An abort message indicates that the sender is unable to continue 890 maintaining the connection and cannot even wait for an orderly 891 release. The sender shuts down the connection immediately after the 892 abort (and may or may not wait for a release or abort message or 893 connection shutdown in the inverse direction). A diagnostic payload 894 SHOULD be included in the Abort message. Messages may be in flight 895 when the sender decides to send an abort message. The general 896 expectation is that these will NOT be processed. 898 Abort messages are indicated by the 7.05 code (Abort). 900 Abort messages can indicate one or more reasons using elective 901 options. The following option is defined: 903 +--------+-----------+----------------+--------+--------+-----------+ 904 | Number | Applies | Name | Format | Length | Base | 905 | | to | | | | Value | 906 +--------+-----------+----------------+--------+--------+-----------+ 907 | 2 | Abort | Bad-CSM-Option | uint | 0-2 | (none) | 908 +--------+-----------+----------------+--------+--------+-----------+ 910 The Bad-CSM-Option Option indicates that the sender is unable to 911 process the CSM option identified by its option number, e.g. when it 912 is critical and the option number is unknown by the sender, or when 913 there is parameter problem with the value of an elective option. 914 More detailed information SHOULD be included as a diagnostic payload. 916 One reason for an sender to generate an abort message is a general 917 syntax error in the byte stream received. No specific option has 918 been defined for this, as the details of that syntax error are best 919 left to a diagnostic payload. 921 4.7. Capability and Settings examples 923 An encoded example of a Ping message with a non-empty token is shown 924 in Figure 15. 926 0 1 2 927 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 928 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 929 | 0x01 | 0xe2 | 0x42 | 930 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 932 Len = 0 -------> 0x01 933 TKL = 1 ___/ 934 Code = 7.02 Ping --> 0xe2 935 Token = 0x42 937 Figure 15: Ping Message Example 939 An encoded example of the corresponding Pong message is shown in 940 Figure 16. 942 0 1 2 943 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 944 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 945 | 0x01 | 0xe3 | 0x42 | 946 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 948 Len = 0 -------> 0x01 949 TKL = 1 ___/ 950 Code = 7.03 Pong --> 0xe3 951 Token = 0x42 953 Figure 16: Pong Message Example 955 5. Block-wise Transfer and Reliable Transports 957 The message size restrictions defined in Section 4.6 of CoAP 958 [RFC7252] to avoid IP fragmentation are not necessary when CoAP is 959 used over a reliable byte stream transport. While this suggests that 960 the Block-wise transfer protocol [RFC7959] is also no longer needed, 961 it remains applicable for a number of cases: 963 o large messages, such as firmware downloads, may cause undesired 964 head-of-line blocking when a single TCP connection is used 966 o a UDP-to-TCP gateway may simply not have the context to convert a 967 message with a Block Option into the equivalent exchange without 968 any use of a Block Option (it would need to convert the entire 969 blockwise exchange from start to end into a single exchange) 971 The 'Block-wise Extension for Reliable Transport (BERT)' extends the 972 Block protocol to enable the use of larger messages over a reliable 973 transport. 975 The use of this new extension is signaled by sending Block1 or Block2 976 Options with SZX == 7 (a "BERT option"). SZX == 7 is a reserved 977 value in [RFC7959]. 979 In control usage, a BERT option is interpreted in the same way as the 980 equivalent Option with SZX == 6, except that it also indicates the 981 capability to process BERT blocks. As with the basic Block protocol, 982 the recipient of a CoAP request with a BERT option in control usage 983 is allowed to respond with a different SZX value, e.g. to send a non- 984 BERT block instead. 986 In descriptive usage, a BERT Option is interpreted in the same way as 987 the equivalent Option with SZX == 6, except that the payload is 988 allowed to contain a multiple of 1024 bytes (non-final BERT block) or 989 more than 1024 bytes (final BERT block). 991 The recipient of a non-final BERT block (M=1) conceptually partitions 992 the payload into a sequence of 1024-byte blocks and acts exactly as 993 if it had received this sequence in conjunction with block numbers 994 starting at, and sequentially increasing from, the block number given 995 in the Block Option. In other words, the entire BERT block is 996 positioned at the byte position that results from multiplying the 997 block number with 1024. The position of further blocks to be 998 transferred is indicated by incrementing the block number by the 999 number of elements in this sequence (i.e., the size of the payload 1000 divided by 1024 bytes). 1002 As with SZX == 6, the recipient of a final BERT block (M=0) simply 1003 appends the payload at the byte position that is indicated by the 1004 block number multiplied with 1024. 1006 The following examples illustrate BERT options. A value of SZX == 7 1007 is labeled as "BERT" or as "BERT(nnn)" to indicate a payload of size 1008 nnn. 1010 In all these examples, a Block Option is decomposed to indicate the 1011 kind of Block Option (1 or 2) followed by a colon, the block number 1012 (NUM), more bit (M), and block size exponent (2**(SZX+4)) separated 1013 by slashes. E.g., a Block2 Option value of 33 would be shown as 1014 2:2/0/32), or a Block1 Option value of 59 would be shown as 1015 1:3/1/128. 1017 5.1. Example: GET with BERT Blocks 1019 Figure 17 shows a GET request with a response that is split into 1020 three BERT blocks. The first response contains 3072 bytes of 1021 payload; the second, 5120; and the third, 4711. Note how the block 1022 number increments to move the position inside the response body 1023 forward. 1025 CLIENT SERVER 1026 | | 1027 | GET, /status ------> | 1028 | | 1029 | <------ 2.05 Content, 2:0/1/BERT(3072) | 1030 | | 1031 | GET, /status, 2:3/0/BERT ------> | 1032 | | 1033 | <------ 2.05 Content, 2:3/1/BERT(5120) | 1034 | | 1035 | GET, /status, 2:8/0/BERT ------> | 1036 | | 1037 | <------ 2.05 Content, 2:8/0/BERT(4711) | 1039 Figure 17: GET with BERT blocks. 1041 5.2. Example: PUT with BERT Blocks 1043 Figure 18 demonstrates a PUT exchange with BERT blocks. 1045 CLIENT SERVER 1046 | | 1047 | PUT, /options, 1:0/1/BERT(8192) ------> | 1048 | | 1049 | <------ 2.31 Continue, 1:0/1/BERT | 1050 | | 1051 | PUT, /options, 1:8/1/BERT(16384) ------> | 1052 | | 1053 | <------ 2.31 Continue, 1:8/1/BERT | 1054 | | 1055 | PUT, /options, 1:24/0/BERT(5683) ------> | 1056 | | 1057 | <------ 2.04 Changed, 1:24/0/BERT | 1058 | | 1060 Figure 18: PUT with BERT blocks. 1062 6. CoAP URIs 1064 CoAP over UDP [RFC7252] defines the "coap" and "coaps" URI schemes 1065 for identifying CoAP resources and providing a means of locating the 1066 resource. 1068 6.1. CoAP over TCP and TLS URIs 1070 CoAP over TCP uses the "coap+tcp" URI scheme. CoAP over TLS uses the 1071 "coaps+tcp" scheme. The rules from Section 6 of [RFC7252] apply to 1072 both of these URI schemes. 1074 [RFC7252], Section 8 (Multicast CoAP) is not applicable to these 1075 schemes. 1077 Resources made available via one of the "coap+tcp" or "coaps+tcp" 1078 schemes have no shared identity with the other scheme or with the 1079 "coap" or "coaps" scheme, even if their resource identifiers indicate 1080 the same authority (the same host listening to the same port). The 1081 schemes constitute distinct namespaces and, in combination with the 1082 authority, are considered to be distinct origin servers. 1084 6.1.1. coap+tcp URI scheme 1086 coap-tcp-URI = "coap+tcp:" "//" host [ ":" port ] path-abempty 1087 [ "?" query ] 1089 The semantics defined in [RFC7252], Section 6.1, apply to this URI 1090 scheme, with the following changes: 1092 o The port subcomponent indicates the TCP port at which the CoAP 1093 server is located. (If it is empty or not given, then the default 1094 port 5683 is assumed, as with UDP.) 1096 6.1.2. coaps+tcp URI scheme 1098 coaps-tcp-URI = "coaps+tcp:" "//" host [ ":" port ] path-abempty 1099 [ "?" query ] 1101 The semantics defined in [RFC7252], Section 6.2, apply to this URI 1102 scheme, with the following changes: 1104 o The port subcomponent indicates the TCP port at which the TLS 1105 server for the CoAP server is located. If it is empty or not 1106 given, then the default port 443 is assumed (this is different 1107 from the default port for "coaps", i.e., CoAP over DTLS over UDP). 1109 o If a server does not support the Application-Layer Protocol 1110 Negotiation Extension (ALPN) [RFC7301] or wishes to accommodate 1111 clients that do not support ALPN, it MAY offer a coaps+tcp 1112 endpoint on TCP port 5684. This endpoint MAY also be ALPN 1113 enabled. A server MAY offer coaps+tcp endpoints on ports other 1114 than TCP port 5684, which MUST be ALPN enabled. 1116 o For TCP ports other than port 5684, the client MUST use the ALPN 1117 extension to advertise the "coap" protocol identifier (see 1118 Section 8.7) in the list of protocols in its ClientHello. If the 1119 server selects and returns the "coap" protocol identifier using 1120 the ALPN extension in its ServerHello, then the connection 1121 succeeds. If the server either does not negotiate the ALPN 1122 extension or returns a no_application_protocol alert, the client 1123 MUST close the connection. 1125 o For TCP port 5684, a client MAY use the ALPN extension to 1126 advertise the "coap" protocol identifier in the list of protocols 1127 in its ClientHello. If the server selects and returns the "coap" 1128 protocol identifier using the ALPN extension in its ServerHello, 1129 then the connection succeeds. If the server returns a 1130 no_application_protocol alert, then the client MUST close the 1131 connection. If the server does not negotiate the ALPN extension, 1132 then coaps+tcp is implicitly selected. 1134 o For TCP port 5684, if the client does not use the ALPN extension 1135 to negotiate the protocol, then coaps+tcp is implicitly selected. 1137 6.2. CoAP over WebSockets URIs 1139 For the first configuration discussed in Section 3, this document 1140 defines two new URIs schemes that can be used for identifying CoAP 1141 resources and providing a means of locating these resources: 1142 "coap+ws" and "coap+wss". 1144 Similar to the "coap" and "coaps" schemes, the "coap+ws" and 1145 "coap+wss" schemes organize resources hierarchically under a CoAP 1146 origin server. The key difference is that the server is potentially 1147 reachable on a WebSocket endpoint instead of a UDP endpoint. 1149 The WebSocket endpoint is identified by a "ws" or "wss" URI that is 1150 composed of the authority part of the "coap+ws" or "coap+wss" URI, 1151 respectively, and the well-known path "/.well-known/coap" [RFC5785]. 1152 The path and query parts of a "coap+ws" or "coap+wss" URI identify a 1153 resource within the specified endpoint which can be operated on by 1154 the methods defined by CoAP. 1156 The syntax of the "coap+ws" and "coap+wss" URI schemes is specified 1157 below in Augmented Backus-Naur Form (ABNF) [RFC5234]. The 1158 definitions of "host", "port", "path-abempty" and "query" are the 1159 same as in [RFC3986]. 1161 coap-ws-URI = 1162 "coap+ws:" "//" host [ ":" port ] path-abempty [ "?" query ] 1164 coap-wss-URI = 1165 "coap+wss:" "//" host [ ":" port ] path-abempty [ "?" query ] 1167 The port component is OPTIONAL; the default for "coap+ws" is port 80, 1168 while the default for "coap+wss" is port 443. 1170 Fragment identifiers are not part of the request URI and thus MUST 1171 NOT be transmitted in a WebSocket handshake or in the URI options of 1172 a CoAP request. 1174 6.2.1. Decomposing and Composing URIs 1176 The steps for decomposing a "coap+ws" or "coap+wss" URI into CoAP 1177 options are the same as specified in Section 6.4 of [RFC7252] with 1178 the following changes: 1180 o The component MUST be "coap+ws" or "coap+wss" when 1181 converted to ASCII lowercase. 1183 o A Uri-Host Option MUST only be included in a request when the 1184 component does not equal the uri-host component in the Host 1185 header field in the WebSocket handshake. 1187 o A Uri-Port Option MUST only be included in a request if |port| 1188 does not equal the port component in the Host header field in the 1189 WebSocket handshake. 1191 The steps to construct a URI from a request's options are changed 1192 accordingly. 1194 7. Security Considerations 1196 The security considerations of [RFC7252] apply. 1198 TLS version 1.2 or higher is mandatory-to-implement and MUST be 1199 enabled by default. An endpoint MAY immediately abort a CoAP over 1200 TLS connection that does not meet this requirement (see Section 4.6) 1201 and SHOULD include a diagnostic payload. 1203 The TLS usage guidance in [RFC7925] SHOULD be followed. 1205 TLS does not protect the TCP header. This may, for example, allow an 1206 on-path adversary to terminate a TCP connection prematurely by 1207 spoofing a TCP reset message. 1209 CoAP over WebSockets and CoAP over TLS-secured WebSockets do not 1210 introduce additional security issues beyond CoAP and DTLS-secured 1211 CoAP respectively [RFC7252]. The security considerations of 1212 [RFC6455] apply. 1214 7.1. Signaling Messages 1216 o The guidance given by an Alternative-Address Option cannot be 1217 followed blindly. In particular, a peer MUST NOT assume that a 1218 successful connection to the Alternative-Address inherits all the 1219 security properties of the current connection. 1221 o SNI vs. Server-Name: Any security negotiated in the TLS handshake 1222 is for the SNI name exchanged in the TLS handshake and checked 1223 against the certificate provided by the server. The Server-Name 1224 Option cannot be used to extend these security properties to the 1225 additional server name. 1227 8. IANA Considerations 1229 8.1. Signaling Codes 1231 IANA is requested to create a third sub-registry for values of the 1232 Code field in the CoAP header (Section 12.1 of [RFC7252]). The name 1233 of this sub-registry is "CoAP Signaling Codes". 1235 Each entry in the sub-registry must include the Signaling Code in the 1236 range 7.01-7.31, its name, and a reference to its documentation. 1238 Initial entries in this sub-registry are as follows: 1240 +------+---------+-----------+ 1241 | Code | Name | Reference | 1242 +------+---------+-----------+ 1243 | 7.01 | CSM | [RFCthis] | 1244 | | | | 1245 | 7.02 | Ping | [RFCthis] | 1246 | | | | 1247 | 7.03 | Pong | [RFCthis] | 1248 | | | | 1249 | 7.04 | Release | [RFCthis] | 1250 | | | | 1251 | 7.05 | Abort | [RFCthis] | 1252 +------+---------+-----------+ 1254 Table 1: CoAP Signal Codes 1256 All other Signaling Codes are Unassigned. 1258 The IANA policy for future additions to this sub-registry is "IETF 1259 Review or IESG Approval" as described in [RFC5226]. 1261 8.2. CoAP Signaling Option Numbers Registry 1263 IANA is requested to create a sub-registry for signaling options 1264 similar to the CoAP Option Numbers Registry (Section 12.2 of 1265 [RFC7252]), with the single change that a fourth column is added to 1266 the sub-registry that is one of the codes in the Signaling Codes 1267 subregistry (Section 8.1). 1269 The name of this sub-registry is "CoAP Signaling Option Numbers". 1271 Initial entries in this sub-registry are as follows: 1273 +--------+------------+---------------------+-----------+ 1274 | Number | Applies to | Name | Reference | 1275 +--------+------------+---------------------+-----------+ 1276 | 1 | CSM | Server-Name | [RFCthis] | 1277 | | | | | 1278 | 2 | CSM | Max-Message-Size | [RFCthis] | 1279 | | | | | 1280 | 4 | CSM | Block-wise-Transfer | [RFCthis] | 1281 | | | | | 1282 | 2 | Ping, Pong | Custody | [RFCthis] | 1283 | | | | | 1284 | 2 | Release | Bad-Server-Name | [RFCthis] | 1285 | | | | | 1286 | 4 | Release | Alternative-Address | [RFCthis] | 1287 | | | | | 1288 | 6 | Release | Hold-Off | [RFCthis] | 1289 | | | | | 1290 | 2 | Abort | Bad-CSM-Option | [RFCthis] | 1291 +--------+------------+---------------------+-----------+ 1293 Table 2: CoAP Signal Option Codes 1295 The IANA policy for future additions to this sub-registry is based on 1296 number ranges for the option numbers, analogous to the policy defined 1297 in Section 12.2 of [RFC7252]. 1299 8.3. Service Name and Port Number Registration 1301 IANA is requested to assign the port number 5683 and the service name 1302 "coap+tcp", in accordance with [RFC6335]. 1304 Service Name. 1305 coap+tcp 1307 Transport Protocol. 1308 tcp 1310 Assignee. 1311 IESG 1313 Contact. 1314 IETF Chair 1316 Description. 1317 Constrained Application Protocol (CoAP) 1319 Reference. 1320 [RFCthis] 1322 Port Number. 1323 5683 1325 8.4. Secure Service Name and Port Number Registration 1327 IANA is requested to assign the port number 5684 and the service name 1328 "coaps+tcp", in accordance with [RFC6335]. The port number is 1329 requested to address the exceptional case of TLS implementations that 1330 do not support the "Application-Layer Protocol Negotiation Extension" 1331 [RFC7301]. 1333 Service Name. 1334 coaps+tcp 1336 Transport Protocol. 1337 tcp 1339 Assignee. 1340 IESG 1342 Contact. 1343 IETF Chair 1345 Description. 1346 Constrained Application Protocol (CoAP) 1348 Reference. 1349 [RFC7301], [RFCthis] 1351 Port Number. 1352 5684 1354 8.5. URI Scheme Registration 1356 This document registers two new URI schemes, namely "coap+tcp" and 1357 "coaps+tcp", for the use of CoAP over TCP and for CoAP over TLS over 1358 TCP, respectively. The "coap+tcp" and "coaps+tcp" URI schemes can 1359 thus be compared to the "http" and "https" URI schemes. 1361 The syntax of the "coap" and "coaps" URI schemes is specified in 1362 Section 6 of [RFC7252] and the present document re-uses their 1363 semantics for "coap+tcp" and "coaps+tcp", respectively, with the 1364 exception that TCP, or TLS over TCP is used as a transport protocol. 1366 IANA is requested to add these new URI schemes to the registry 1367 established with [RFC7595]. 1369 8.5.1. coap+ws 1371 This document requests the registration of the Uniform Resource 1372 Identifier (URI) scheme "coap+ws". The registration request complies 1373 with [RFC4395]. 1375 URL scheme name. 1376 coap+ws 1378 Status. 1379 Permanent 1381 URI scheme syntax. 1382 Defined in Section N of [RFCthis] 1384 URI scheme semantics. 1385 The "coap+ws" URI scheme provides a way to identify resources that 1386 are potentially accessible over the Constrained Application 1387 Protocol (CoAP) using the WebSocket protocol. 1389 Encoding considerations. 1390 The scheme encoding conforms to the encoding rules established for 1391 URIs in [RFC3986], i.e., internationalized and reserved characters 1392 are expressed using UTF-8-based percent-encoding. 1394 Applications/protocols that use this URI scheme name. 1395 The scheme is used by CoAP endpoints to access CoAP resources 1396 using the WebSocket protocol. 1398 Interoperability considerations. 1399 None. 1401 Security Considerations. 1402 See Section N of [RFCthis] 1404 Contact. 1405 IETF chair 1407 Author/Change controller. 1408 IESG 1410 References. 1411 [RFCthis] 1413 8.5.2. coap+wss 1415 This document requests the registration of the Uniform Resource 1416 Identifier (URI) scheme "coap+wss". The registration request 1417 complies with [RFC4395]. 1419 URL scheme name. 1420 coap+wss 1422 Status. 1423 Permanent 1425 URI scheme syntax. 1426 Defined in Section N of [RFCthis] 1428 URI scheme semantics. 1429 The "coap+ws" URI scheme provides a way to identify resources that 1430 are potentially accessible over the Constrained Application 1431 Protocol (CoAP) using the WebSocket protocol secured with 1432 Transport Layer Security (TLS). 1434 Encoding considerations. 1435 The scheme encoding conforms to the encoding rules established for 1436 URIs in [RFC3986], i.e., internationalized and reserved characters 1437 are expressed using UTF-8-based percent-encoding. 1439 Applications/protocols that use this URI scheme name. 1440 The scheme is used by CoAP endpoints to access CoAP resources 1441 using the WebSocket protocol secured with TLS. 1443 Interoperability considerations. 1444 None. 1446 Security Considerations. 1447 See Section N of [RFCthis] 1449 Contact. 1450 IETF chair 1452 Author/Change controller. 1453 IESG 1455 References. 1456 [RFCthis] 1458 8.6. Well-Known URI Suffix Registration 1460 IANA is requested to register the 'coap' well-known URI in the "Well- 1461 Known URIs" registry. This registration request complies with 1462 [RFC5785]: 1464 URI Suffix. 1465 coap 1467 Change controller. 1468 IETF 1470 Specification document(s). 1471 [RFCthis] 1473 Related information. 1474 None. 1476 8.7. ALPN Protocol Identifier 1478 IANA is requested to assign the following value in the registry 1479 "Application Layer Protocol Negotiation (ALPN) Protocol IDs" created 1480 by [RFC7301]. The "coap" string identifies CoAP when used over TLS. 1482 Protocol. 1483 CoAP 1485 Identification Sequence. 1486 0x63 0x6f 0x61 0x70 ("coap") 1488 Reference. 1489 [RFCthis] 1491 8.8. WebSocket Subprotocol Registration 1493 IANA is requested to register the WebSocket CoAP subprotocol under 1494 the "WebSocket Subprotocol Name Registry": 1496 Subprotocol Identifier. 1497 coap 1499 Subprotocol Common Name. 1500 Constrained Application Protocol (CoAP) 1502 Subprotocol Definition. 1503 [RFCthis] 1505 9. References 1507 9.1. Normative References 1509 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC 1510 793, DOI 10.17487/RFC0793, September 1981, 1511 . 1513 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1514 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1515 RFC2119, March 1997, 1516 . 1518 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1519 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1520 3986, DOI 10.17487/RFC3986, January 2005, 1521 . 1523 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 1524 Registration Procedures for New URI Schemes", RFC 4395, 1525 DOI 10.17487/RFC4395, February 2006, 1526 . 1528 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1529 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1530 DOI 10.17487/RFC5226, May 2008, 1531 . 1533 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1534 (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ 1535 RFC5246, August 2008, 1536 . 1538 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1539 Uniform Resource Identifiers (URIs)", RFC 5785, DOI 1540 10.17487/RFC5785, April 2010, 1541 . 1543 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 1544 6455, DOI 10.17487/RFC6455, December 2011, 1545 . 1547 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1548 Application Protocol (CoAP)", RFC 7252, DOI 10.17487/ 1549 RFC7252, June 2014, 1550 . 1552 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 1553 "Transport Layer Security (TLS) Application-Layer Protocol 1554 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1555 July 2014, . 1557 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 1558 and Registration Procedures for URI Schemes", BCP 35, RFC 1559 7595, DOI 10.17487/RFC7595, June 2015, 1560 . 1562 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1563 Application Protocol (CoAP)", RFC 7641, DOI 10.17487/ 1564 RFC7641, September 2015, 1565 . 1567 [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer 1568 Security (TLS) / Datagram Transport Layer Security (DTLS) 1569 Profiles for the Internet of Things", RFC 7925, DOI 1570 10.17487/RFC7925, July 2016, 1571 . 1573 9.2. Informative References 1575 [HomeGateway] 1576 Eggert, L., "An experimental study of home gateway 1577 characteristics", Proceedings of the 10th annual 1578 conference on Internet measurement, 2010. 1580 [LWM2M] Open Mobile Alliance, "Lightweight Machine to Machine 1581 Technical Specification Candidate Version 1.0", April 1582 2016, . 1586 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, DOI 1587 10.17487/RFC0768, August 1980, 1588 . 1590 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1591 Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ 1592 RFC5234, January 2008, 1593 . 1595 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 1596 Cheshire, "Internet Assigned Numbers Authority (IANA) 1597 Procedures for the Management of the Service Name and 1598 Transport Protocol Port Number Registry", BCP 165, RFC 1599 6335, DOI 10.17487/RFC6335, August 2011, 1600 . 1602 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1603 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1604 January 2012, . 1606 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, DOI 1607 10.17487/RFC6454, December 2011, 1608 . 1610 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1611 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 1612 7230, DOI 10.17487/RFC7230, June 2014, 1613 . 1615 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1616 the Constrained Application Protocol (CoAP)", RFC 7959, 1617 DOI 10.17487/RFC7959, August 2016, 1618 . 1620 Appendix A. Updates to RFC7641 Observing Resources in the Constrained 1621 Application Protocol (CoAP) 1623 A.1. Notifications and Reordering 1625 When using the Observe Option with CoAP over UDP, notifications from 1626 the server set the option value to an increasing sequence number for 1627 reordering detection on the client since messages can arrive in a 1628 different order than they were sent. This sequence number is not 1629 required for CoAP over reliable transports since the TCP protocol 1630 ensures reliable and ordered delivery of messages. The value of the 1631 Observe Option in 2.xx notifications MAY be empty on transmission and 1632 MUST be ignored on reception. 1634 A.2. Transmission and Acknowledgements 1636 For CoAP over UDP, server notifications to the client can be 1637 confirmable or non-confirmable. A confirmable message requires the 1638 client to either respond with an acknowledgement message or a reset 1639 message. An acknowledgement message indicates that the client is 1640 alive and wishes to receive further notifications. A reset message 1641 indicates that the client does not recognize the token which causes 1642 the server to remove the associated entry from the list of observers. 1644 Since TCP eliminates the need for the message layer to support 1645 reliability, CoAP over reliable transports does not support 1646 confirmable or non-confirmable message types. All notifications are 1647 delivered reliably to the client with positive acknowledgement of 1648 receipt occurring at the TCP level. If the client does not recognize 1649 the token in a notification, it MAY immediately abort the connection 1650 (see Section 4.6) and SHOULD include a diagnostic payload. 1652 A.3. Cancellation 1654 For CoAP over UDP, a client that is no longer interested in receiving 1655 notifications can "forget" the observation and respond to the next 1656 notification from the server with a reset message to cancel the 1657 observation. 1659 For CoAP over reliable transports, a client MUST explicitly 1660 deregister by issuing a GET request that has the Token field set to 1661 the token of the observation to be cancelled and includes an Observe 1662 Option with the value set to 1 (deregister). 1664 If the client observes one or more resources over a reliable 1665 connection, then the CoAP server (or intermediary in the role of the 1666 CoAP server) MUST remove all entries associated with the client 1667 endpoint from the lists of observers when the connection is either 1668 closed or times out. 1670 Appendix B. Negotiating Protocol Versions 1672 CoAP is defined in [RFC7252] with a version number of 1. At this 1673 time, there is no known reason to support version numbers different 1674 from 1. 1676 In contrast to the message layer for UDP and DTLS, the CoAP over TCP 1677 message format does not include a version number. If version 1678 negotiation needs to be addressed in the future, then Capability and 1679 Settings have been specifically designed to enable such a potential 1680 feature. 1682 Appendix C. CoAP over WebSocket Examples 1684 This section gives examples for the first two configurations 1685 discussed in Section 3. 1687 An example of the process followed by a CoAP client to retrieve the 1688 representation of a resource identified by a "coap+ws" URI might be 1689 as follows. Figure 19 below illustrates the WebSocket and CoAP 1690 messages exchanged in detail. 1692 1. The CoAP client obtains the URI , for example, from a resource representation 1694 that it retrieved previously. 1696 2. It establishes a WebSocket connection to the endpoint URI 1697 composed of the authority "example.org" and the well-known path 1698 "/.well-known/coap", . 1700 3. It sends a single-frame, masked, binary message containing a CoAP 1701 request. The request indicates the target resource with the Uri- 1702 Path ("sensors", "temperature") and Uri-Query ("u=Cel") options. 1704 4. It waits for the server to return a response. 1706 5. The CoAP client uses the connection for further requests, or the 1707 connection is closed. 1709 CoAP CoAP 1710 Client Server 1711 (WebSocket (WebSocket 1712 Client) Server) 1714 | | 1715 | | 1716 +=========>| GET /.well-known/coap HTTP/1.1 1717 | | Host: example.org 1718 | | Upgrade: websocket 1719 | | Connection: Upgrade 1720 | | Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 1721 | | Sec-WebSocket-Protocol: coap 1722 | | Sec-WebSocket-Version: 13 1723 | | 1724 |<=========+ HTTP/1.1 101 Switching Protocols 1725 | | Upgrade: websocket 1726 | | Connection: Upgrade 1727 | | Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 1728 | | Sec-WebSocket-Protocol: coap 1729 | | 1730 | | 1731 +--------->| Binary frame (opcode=%x2, FIN=1, MASK=1) 1732 | | +-------------------------+ 1733 | | | GET | 1734 | | | Token: 0x53 | 1735 | | | Uri-Path: "sensors" | 1736 | | | Uri-Path: "temperature" | 1737 | | | Uri-Query: "u=Cel" | 1738 | | +-------------------------+ 1739 | | 1740 |<---------+ Binary frame (opcode=%x2, FIN=1, MASK=0) 1741 | | +-------------------------+ 1742 | | | 2.05 Content | 1743 | | | Token: 0x53 | 1744 | | | Payload: "22.3 Cel" | 1745 | | +-------------------------+ 1746 : : 1747 : : 1748 | | 1749 +--------->| Close frame (opcode=%x8, FIN=1, MASK=1) 1750 | | 1751 |<---------+ Close frame (opcode=%x8, FIN=1, MASK=0) 1752 | | 1754 Figure 19: A CoAP client retrieves the representation of a resource 1755 identified by a "coap+ws" URI 1757 Figure 20 shows how a CoAP client uses a CoAP forward proxy with a 1758 WebSocket endpoint to retrieve the representation of the resource 1759 "coap://[2001:DB8::1]/". The use of the forward proxy and the 1760 address of the WebSocket endpoint are determined by the client from 1761 local configuration rules. The request URI is specified in the 1762 Proxy-Uri Option. Since the request URI uses the "coap" URI scheme, 1763 the proxy fulfills the request by issuing a Confirmable GET request 1764 over UDP to the CoAP server and returning the response over the 1765 WebSocket connection to the client. 1767 CoAP CoAP CoAP 1768 Client Proxy Server 1769 (WebSocket (WebSocket (UDP 1770 Client) Server) Endpoint) 1772 | | | 1773 +--------->| | Binary frame (opcode=%x2, FIN=1, MASK=1) 1774 | | | +------------------------------------+ 1775 | | | | GET | 1776 | | | | Token: 0x7d | 1777 | | | | Proxy-Uri: "coap://[2001:DB8::1]/" | 1778 | | | +------------------------------------+ 1779 | | | 1780 | +--------->| CoAP message (Ver=1, T=Con, MID=0x8f54) 1781 | | | +------------------------------------+ 1782 | | | | GET | 1783 | | | | Token: 0x0a15 | 1784 | | | +------------------------------------+ 1785 | | | 1786 | |<---------+ CoAP message (Ver=1, T=Ack, MID=0x8f54) 1787 | | | +------------------------------------+ 1788 | | | | 2.05 Content | 1789 | | | | Token: 0x0a15 | 1790 | | | | Payload: "ready" | 1791 | | | +------------------------------------+ 1792 | | | 1793 |<---------+ | Binary frame (opcode=%x2, FIN=1, MASK=0) 1794 | | | +------------------------------------+ 1795 | | | | 2.05 Content | 1796 | | | | Token: 0x7d | 1797 | | | | Payload: "ready" | 1798 | | | +------------------------------------+ 1799 | | | 1801 Figure 20: A CoAP client retrieves the representation of a resource 1802 identified by a "coap" URI via a WebSockets-enabled CoAP proxy 1804 Appendix D. Change Log 1806 The RFC Editor is requested to remove this section at publication. 1808 D.1. Since draft-core-coap-tcp-tls-02 1810 Merged draft-savolainen-core-coap-websockets-07 Merged draft-bormann- 1811 core-block-bert-01 Merged draft-bormann-core-coap-sig-02 1813 D.2. Since draft-core-coap-tcp-tls-03 1815 Editorial updates 1817 Added mandatory exchange of Capabilities and Settings messages after 1818 connecting 1820 Added support for coaps+tcp port 5684 and more details on 1821 Application-Layer Protocol Negotiation (ALPN) 1823 Added guidance on CoAP Signaling Ping-Pong versus WebSocket Ping-Pong 1825 Updated references and requirements for TLS security considerations 1827 D.3. Since draft-core-coap-tcp-tls-04 1829 Updated references 1831 Added Appendix: Updates to RFC7641 Observing Resources in the 1832 Constrained Application Protocol (CoAP) 1834 Updated Capability and Settings Message (CSM) exchange in the Opening 1835 Handshake to allow client to send messages before receiving server 1836 CSM 1838 Acknowledgements 1840 We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier 1841 Delaby, Christian Groves, Nadir Javed, Michael Koster, Matthias 1842 Kovatsch, Achim Kraus, David Navarro, Szymon Sasin, Zach Shelby, 1843 Andrew Summers, Julien Vermillard, and Gengyu Wei for their feedback. 1845 Contributors 1846 Valik Solorzano Barboza 1847 Zebra Technologies 1848 820 W. Jackson Blvd. Suite 700 1849 Chicago 60607 1850 United States of America 1852 Phone: +1-847-634-6700 1853 Email: vsolorzanobarboza@zebra.com 1855 Teemu Savolainen 1856 Nokia Technologies 1857 Hatanpaan valtatie 30 1858 Tampere FI-33100 1859 Finland 1861 Email: teemu.savolainen@nokia.com 1863 Authors' Addresses 1865 Carsten Bormann 1866 Universitaet Bremen TZI 1867 Postfach 330440 1868 Bremen D-28359 1869 Germany 1871 Phone: +49-421-218-63921 1872 Email: cabo@tzi.org 1874 Simon Lemay 1875 Zebra Technologies 1876 820 W. Jackson Blvd. Suite 700 1877 Chicago 60607 1878 United States of America 1880 Phone: +1-847-634-6700 1881 Email: slemay@zebra.com 1883 Hannes Tschofenig 1884 ARM Ltd. 1885 110 Fulbourn Rd 1886 Cambridge CB1 9NJ 1887 Great Britain 1889 Email: Hannes.tschofenig@gmx.net 1890 URI: http://www.tschofenig.priv.at 1891 Klaus Hartke 1892 Universitaet Bremen TZI 1893 Postfach 330440 1894 Bremen D-28359 1895 Germany 1897 Phone: +49-421-218-63905 1898 Email: hartke@tzi.org 1900 Bilhanan Silverajan 1901 Tampere University of Technology 1902 Korkeakoulunkatu 10 1903 Tampere FI-33720 1904 Finland 1906 Email: bilhanan.silverajan@tut.fi 1908 Brian Raymor (editor) 1909 Microsoft 1910 One Microsoft Way 1911 Redmond 98052 1912 United States of America 1914 Email: brian.raymor@microsoft.com