idnits 2.17.1 draft-ietf-core-coap-tcp-tls-06.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 abstract seems to contain references ([RFC7641]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 14, 2017) is 2627 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 300, but not defined == Missing Reference: '------' is mentioned on line 300, but not defined == Missing Reference: 'RFCthis' is mentioned on line 1678, but not defined ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** 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 (-03) exists of draft-ietf-core-cocoa-00 == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-01 -- 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 Updates: 7641 (if approved) S. Lemay 5 Intended status: Standards Track Zebra Technologies 6 Expires: August 18, 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 February 14, 2017 16 CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets 17 draft-ietf-core-coap-tcp-tls-06 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. It also formally updates [RFC7641] for use with these 30 transports. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on August 18, 2017. 49 Copyright Notice 51 Copyright (c) 2017 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 5 68 2. CoAP over TCP . . . . . . . . . . . . . . . . . . . . . . . . 6 69 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 6 70 2.2. Message Format . . . . . . . . . . . . . . . . . . . . . 7 71 2.3. Message Transmission . . . . . . . . . . . . . . . . . . 10 72 2.4. Connection Health . . . . . . . . . . . . . . . . . . . . 11 73 3. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . 11 74 3.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 13 75 3.2. Message Format . . . . . . . . . . . . . . . . . . . . . 14 76 3.3. Message Transmission . . . . . . . . . . . . . . . . . . 15 77 3.4. Connection Health . . . . . . . . . . . . . . . . . . . . 15 78 4. Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . 15 79 4.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 16 80 4.2. Signaling Option Numbers . . . . . . . . . . . . . . . . 16 81 4.3. Capabilities and Settings Messages (CSM) . . . . . . . . 16 82 4.4. Ping and Pong Messages . . . . . . . . . . . . . . . . . 18 83 4.5. Release Messages . . . . . . . . . . . . . . . . . . . . 19 84 4.6. Abort Messages . . . . . . . . . . . . . . . . . . . . . 20 85 4.7. Signaling examples . . . . . . . . . . . . . . . . . . . 21 86 5. Block-wise Transfer and Reliable Transports . . . . . . . . . 22 87 5.1. Example: GET with BERT Blocks . . . . . . . . . . . . . . 23 88 5.2. Example: PUT with BERT Blocks . . . . . . . . . . . . . . 24 89 6. CoAP over Reliable Transport URIs . . . . . . . . . . . . . . 24 90 6.1. coap+tcp URI scheme . . . . . . . . . . . . . . . . . . . 25 91 6.2. coaps+tcp URI scheme . . . . . . . . . . . . . . . . . . 25 92 6.3. coap+ws URI scheme . . . . . . . . . . . . . . . . . . . 26 93 6.4. coaps+ws URI scheme . . . . . . . . . . . . . . . . . . . 27 94 6.5. Uri-Host and Uri-Port Options . . . . . . . . . . . . . . 28 95 6.6. Decomposing URIs into Options . . . . . . . . . . . . . . 28 96 6.7. Composing URIs from Options . . . . . . . . . . . . . . . 29 98 7. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 29 99 7.1. TLS binding for CoAP over TCP . . . . . . . . . . . . . . 29 100 7.2. TLS usage for CoAP over WebSockets . . . . . . . . . . . 30 101 8. Security Considerations . . . . . . . . . . . . . . . . . . . 30 102 8.1. Signaling Messages . . . . . . . . . . . . . . . . . . . 31 103 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 104 9.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 31 105 9.2. CoAP Signaling Option Numbers Registry . . . . . . . . . 31 106 9.3. Service Name and Port Number Registration . . . . . . . . 32 107 9.4. Secure Service Name and Port Number Registration . . . . 33 108 9.5. URI Scheme Registration . . . . . . . . . . . . . . . . . 34 109 9.6. Well-Known URI Suffix Registration . . . . . . . . . . . 36 110 9.7. ALPN Protocol Identifier . . . . . . . . . . . . . . . . 36 111 9.8. WebSocket Subprotocol Registration . . . . . . . . . . . 36 112 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 113 10.1. Normative References . . . . . . . . . . . . . . . . . . 37 114 10.2. Informative References . . . . . . . . . . . . . . . . . 38 115 Appendix A. Updates to RFC7641 Observing Resources in the 116 Constrained Application Protocol (CoAP) . . . . . . 40 117 A.1. Notifications and Reordering . . . . . . . . . . . . . . 40 118 A.2. Transmission and Acknowledgements . . . . . . . . . . . . 40 119 A.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 40 120 A.4. Cancellation . . . . . . . . . . . . . . . . . . . . . . 41 121 Appendix B. CoAP over WebSocket Examples . . . . . . . . . . . . 41 122 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 44 123 C.1. Since draft-core-coap-tcp-tls-02 . . . . . . . . . . . . 44 124 C.2. Since draft-core-coap-tcp-tls-03 . . . . . . . . . . . . 44 125 C.3. Since draft-core-coap-tcp-tls-04 . . . . . . . . . . . . 44 126 C.4. Since draft-core-coap-tcp-tls-05 . . . . . . . . . . . . 44 127 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 45 128 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 45 129 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45 131 1. Introduction 133 The Constrained Application Protocol (CoAP) [RFC7252] was designed 134 for Internet of Things (IoT) deployments, assuming that UDP [RFC0768] 135 or DTLS [RFC6347] over UDP can be used unimpeded. UDP is a good 136 choice for transferring small amounts of data across networks that 137 follow the IP architecture. 139 Some CoAP deployments need to integrate well with existing enterprise 140 infrastructures, where UDP-based protocols may not be well-received 141 or may even be blocked by firewalls. Middleboxes that are unaware of 142 CoAP usage for IoT can make the use of UDP brittle, resulting in lost 143 or malformed packets. 145 Emerging standards such as Lightweight Machine to Machine [LWM2M] 146 currently use CoAP over UDP as a transport and require support for 147 CoAP over TCP to address the issues above and to protect investments 148 in existing CoAP implementations and deployments. Although HTTP/2 149 could also potentially address these requirements, there would be 150 additional costs and delays introduced by such a transition. 151 Currently, there are also fewer HTTP/2 implementations available for 152 constrained devices in comparison to CoAP. 154 To address these requirements, this document defines how to transport 155 CoAP over TCP, CoAP over TLS, and CoAP over WebSockets. Figure 1 156 illustrates the layering: 158 +--------------------------------+ 159 | Application | 160 +--------------------------------+ 161 +--------------------------------+ 162 | Requests/Responses/Signaling | CoAP (RFC 7252) / This Document 163 |--------------------------------| 164 | Message Framing | This Document 165 +--------------------------------+ 166 | Reliable Transport | 167 +--------------------------------+ 169 Figure 1: Layering of CoAP over Reliable Transports 171 Where NATs are present, CoAP over TCP can help with their traversal. 172 NATs often calculate expiration timers based on the transport layer 173 protocol being used by application protocols. Many NATs maintain 174 TCP-based NAT bindings for longer periods based on the assumption 175 that a transport layer protocol, such as TCP, offers additional 176 information about the session life cycle. UDP, on the other hand, 177 does not provide such information to a NAT and timeouts tend to be 178 much shorter [HomeGateway]. 180 Some environments may also benefit from the ability of TCP to 181 exchange larger payloads, such as firmware images, without 182 application layer segmentation and to utilize the more sophisticated 183 congestion control capabilities provided by many TCP implementations. 184 Note that there is ongoing work to add more elaborate congestion 185 control to CoAP (see [I-D.ietf-core-cocoa]). 187 CoAP may be integrated into a Web environment where the front-end 188 uses CoAP over UDP from IoT devices to a cloud infrastructure and 189 then CoAP over TCP between the back-end services. A TCP-to-UDP 190 gateway can be used at the cloud boundary to communicate with the 191 UDP-based IoT device. 193 To allow IoT devices to better communicate in these demanding 194 environments, CoAP needs to support different transport protocols, 195 namely TCP [RFC0793], in some situations secured by TLS [RFC5246]. 197 In addition, some corporate networks only allow Internet access via a 198 HTTP proxy. In this case, the best transport for CoAP might be the 199 WebSocket Protocol [RFC6455]. The WebSocket protocol provides two- 200 way communication between a WebSocket client and a WebSocket server 201 after upgrading an HTTP/1.1 [RFC7230] connection and may be available 202 in an environment that blocks CoAP over UDP. Another scenario for 203 CoAP over WebSockets is a CoAP application running inside a web 204 browser without access to connectivity other than HTTP and 205 WebSockets. 207 This document specifies how to access resources using CoAP requests 208 and responses over the TCP/TLS and WebSocket protocols. This allows 209 connectivity-limited applications to obtain end-to-end CoAP 210 connectivity either by communicating CoAP directly with a CoAP server 211 accessible over a TCP/TLS or WebSocket connection or via a CoAP 212 intermediary that proxies CoAP requests and responses between 213 different transports, such as between WebSockets and UDP. 215 Appendix A updates Observing Resources in the Constrained Application 216 Protocol [RFC7641] for use with CoAP over reliable transports. 217 [RFC7641] is an extension to the CoAP core protocol that enables CoAP 218 clients to "observe" a resource on a CoAP server. (The CoAP client 219 retrieves a representation of a resource and registers to be notified 220 by the CoAP server when the representation is updated.) 222 1.1. Conventions and Terminology 224 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 225 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 226 "OPTIONAL" in this document are to be interpreted as described in 227 [RFC2119]. 229 This document assumes that readers are familiar with the terms and 230 concepts that are used in [RFC6455], [RFC7252], [RFC7641], and 231 [RFC7959]. 233 The term "reliable transport" is used only to refer to transport 234 protocols such as TCP which provide reliable and ordered delivery of 235 a byte-stream. 237 BERT Option: 238 A Block1 or Block2 option that includes an SZX value of 7. 240 BERT Block: 242 The payload of a CoAP message that is affected by a BERT Option in 243 descriptive usage (Section 2.1 of [RFC7959]). 245 Connection Initiator: 246 The peer that opens a reliable byte stream connection, i.e., the 247 TCP active opener, TLS client, or WebSocket client. 249 Connection Acceptor: 250 The peer that accepts the reliable byte stream connection opened 251 by the other peer, i.e., the TCP passive opener, TLS server, or 252 WebSocket server. 254 For simplicity, a Payload Marker (0xFF) is shown in all examples for 255 message formats: 257 ... 258 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 259 |1 1 1 1 1 1 1 1| Payload (if any) ... 260 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 262 The Payload Marker indicates the start of the optional payload and is 263 absent for zero-length payloads (see section 3 of [RFC7252]). 265 2. CoAP over TCP 267 The request/response interaction model of CoAP over TCP is the same 268 as CoAP over UDP. The primary differences are in the message layer. 269 The message layer of CoAP over UDP supports optional reliability by 270 defining four Types of messages: Confirmable, Non-confirmable, 271 Acknowledgement, and Reset. In addition, messages include a Message 272 ID to relate Acknowledgments to Confirmable messages and to detect 273 duplicate messages. 275 2.1. Messaging Model 277 Conceptually, CoAP over TCP replaces most of the message layer of 278 CoAP over UDP with a framing mechanism on top of the byte-stream 279 provided by TCP/TLS, conveying the length information for each 280 message that on datagram transports is provided by the UDP/DTLS 281 datagram layer. 283 TCP ensures reliable message transmission, so the message layer of 284 CoAP over TCP is not required to support acknowledgements or to 285 detect duplicate messages. As a result, both the Type and Message ID 286 fields are no longer required and are removed from the CoAP over TCP 287 message format. 289 Figure 2 illustrates the difference between CoAP over UDP and CoAP 290 over reliable transport. The removed Type and Message ID fields are 291 indicated by dashes. 293 CoAP Client CoAP Server CoAP Client CoAP Server 294 | | | | 295 | CON [0xbc90] | | (-------) [------] | 296 | GET /temperature | | GET /temperature | 297 | (Token 0x71) | | (Token 0x71) | 298 +------------------->| +------------------->| 299 | | | | 300 | ACK [0xbc90] | | (-------) [------] | 301 | 2.05 Content | | 2.05 Content | 302 | (Token 0x71) | | (Token 0x71) | 303 | "22.5 C" | | "22.5 C" | 304 |<-------------------+ |<-------------------+ 305 | | | | 307 CoAP over UDP CoAP over reliable 308 transport 310 Figure 2: Comparison between CoAP over unreliable and reliable 311 transport 313 2.2. Message Format 315 The CoAP message format defined in [RFC7252], as shown in Figure 3, 316 relies on the datagram transport (UDP, or DTLS over UDP) for keeping 317 the individual messages separate and for providing length 318 information. 320 0 1 2 3 321 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 322 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 323 |Ver| T | TKL | Code | Message ID | 324 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 325 | Token (if any, TKL bytes) ... 326 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 327 | Options (if any) ... 328 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 329 |1 1 1 1 1 1 1 1| Payload (if any) ... 330 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 332 Figure 3: RFC 7252 defined CoAP Message Format 334 The CoAP over TCP message format is very similar to the format 335 specified for CoAP over UDP. The differences are as follows: 337 o Since the underlying TCP connection provides retransmissions and 338 deduplication, there is no need for the reliability mechanisms 339 provided by CoAP over UDP. The Type (T) and Message ID fields in 340 the CoAP message header are elided. 342 o The Version (Vers) field is elided as well. In contrast to the 343 message format of CoAP over UDP, the message format for CoAP over 344 TCP does not include a version number. CoAP is defined in 345 [RFC7252] with a version number of 1. At this time, there is no 346 known reason to support version numbers different from 1. If 347 version negotiation needs to be addressed in the future, then 348 Capabilities and Settings Messages (CSM see Section 4.3) have been 349 specifically designed to enable such a potential feature. 351 o In a stream oriented transport protocol such as TCP, a form of 352 message delimitation is needed. For this purpose, CoAP over TCP 353 introduces a length field with variable size. Figure 4 shows the 354 adjusted CoAP message format with a modified structure for the 355 fixed header (first 4 bytes of the CoAP over UDP header), which 356 includes the length information of variable size, shown here as an 357 8-bit length. 359 0 1 2 3 360 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 361 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 362 |Len=13 | TKL |Extended Length| Code | TKL bytes ... 363 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 364 | Options (if any) ... 365 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 366 |1 1 1 1 1 1 1 1| Payload (if any) ... 367 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 369 Figure 4: CoAP frame with 8-bit Extended Length field 371 Length (Len): 4-bit unsigned integer. A value between 0 and 12 372 directly indicates the length of the message in bytes starting 373 with the first bit of the Options field. Three values are 374 reserved for special constructs: 376 13: An 8-bit unsigned integer (Extended Length) follows the 377 initial byte and indicates the length of options/payload minus 378 13. 380 14: A 16-bit unsigned integer (Extended Length) in network byte 381 order follows the initial byte and indicates the length of 382 options/payload minus 269. 384 15: A 32-bit unsigned integer (Extended Length) in network byte 385 order follows the initial byte and indicates the length of 386 options/payload minus 65805. 388 The encoding of the Length field is modeled on CoAP Options (see 389 section 3.1 of [RFC7252]). 391 The following figures show the message format for the 0-bit, 16-bit, 392 and the 32-bit variable length cases. 394 0 1 2 3 395 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 396 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 397 | Len | TKL | Code | Token (if any, TKL bytes) ... 398 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 399 | Options (if any) ... 400 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 401 |1 1 1 1 1 1 1 1| Payload (if any) ... 402 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 404 Figure 5: CoAP message format without an Extended Length field 406 For example: A CoAP message just containing a 2.03 code with the 407 token 7f and no options or payload would be encoded as shown in 408 Figure 6. 410 0 1 2 411 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 412 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 413 | 0x01 | 0x43 | 0x7f | 414 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 416 Len = 0 ------> 0x01 417 TKL = 1 ___/ 418 Code = 2.03 --> 0x43 419 Token = 0x7f 421 Figure 6: CoAP message with no options or payload 423 0 1 2 3 424 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 425 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 426 |Len=14 | TKL | Extended Length (16 bits) | Code | 427 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 428 | Token (if any, TKL bytes) ... 429 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 430 | Options (if any) ... 431 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 432 |1 1 1 1 1 1 1 1| Payload (if any) ... 433 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 435 Figure 7: CoAP message format with 16-bit Extended Length field 437 0 1 2 3 438 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 439 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 440 |Len=15 | TKL | Extended Length (32 bits) 441 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 442 | | Code | Token (if any, TKL bytes) ... 443 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 444 | Options (if any) ... 445 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 446 |1 1 1 1 1 1 1 1| Payload (if any) ... 447 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 449 Figure 8: CoAP message format with 32-bit Extended Length field 451 The semantics of the other CoAP header fields are left unchanged. 453 2.3. Message Transmission 455 Once a connection is established, both endpoints MUST send a 456 Capabilities and Settings message (CSM see Section 4.3) as their 457 first message on the connection. This message establishes the 458 initial settings and capabilities for the endpoint such as maximum 459 message size or support for block-wise transfers. The absence of 460 options in the CSM indicates that base values are assumed. 462 To avoid a deadlock, the Connection Initiator MUST NOT wait for the 463 Connection Acceptor to send its initial CSM message before sending 464 its own initial CSM message. Conversely, the Connection Acceptor MAY 465 wait for the Connection Initiator to send its initial CSM message 466 before sending its own initial CSM message. 468 To avoid unnecessary latency, a Connection Initiator MAY send 469 additional messages without waiting to receive the Connection 470 Acceptor's CSM; however, it is important to note that the Connection 471 Acceptor's CSM might advertise capabilities that impact how the 472 initiator is expected to communicate with the acceptor. For example, 473 the acceptor CSM could advertise a Max-Message-Size option (see 474 Section 4.3.1) that is smaller than the base value (1152). 476 Endpoints MUST treat a missing or invalid CSM as a connection error 477 and abort the connection (see Section 4.6). 479 CoAP requests and responses are exchanged asynchronously over the 480 TCP/TLS connection. A CoAP client can send multiple requests without 481 waiting for a response and the CoAP server can return responses in 482 any order. Responses MUST be returned over the same connection as 483 the originating request. Concurrent requests are differentiated by 484 their Token, which is scoped locally to the connection. 486 The connection is bi-directional, so requests can be sent both by the 487 entity that established the connection and the remote host. 489 Retransmission and deduplication of messages is provided by the TCP/ 490 TLS protocol. 492 2.4. Connection Health 494 Empty messages (Code 0.00) can always be sent and MUST be ignored by 495 the recipient. This provides a basic keep-alive function that can 496 refresh NAT bindings. 498 If a CoAP client does not receive any response for some time after 499 sending a CoAP request (or, similarly, when a client observes a 500 resource and it does not receive any notification for some time), it 501 can send a CoAP Ping Signaling message (Section 4.4) to test the 502 connection and verify that the CoAP server is responsive. 504 3. CoAP over WebSockets 506 CoAP over WebSockets is intentionally similar to CoAP over TCP; 507 therefore, this section only specifies the differences between the 508 transports. 510 CoAP over WebSockets can be used in a number of configurations. The 511 most basic configuration is a CoAP client retrieving or updating a 512 CoAP resource located on a CoAP server that exposes a WebSocket 513 endpoint (Figure 9). The CoAP client acts as the WebSocket client, 514 establishes a WebSocket connection, and sends a CoAP request, to 515 which the CoAP server returns a CoAP response. The WebSocket 516 connection can be used for any number of requests. 518 ___________ ___________ 519 | | | | 520 | _|___ requests ___|_ | 521 | CoAP / \ \ -------------> / / \ CoAP | 522 | Client \__/__/ <------------- \__\__/ Server | 523 | | responses | | 524 |___________| |___________| 525 WebSocket =============> WebSocket 526 Client Connection Server 528 Figure 9: CoAP Client (WebSocket client) accesses CoAP Server 529 (WebSocket server) 531 The challenge with this configuration is how to identify a resource 532 in the namespace of the CoAP server. When the WebSocket protocol is 533 used by a dedicated client directly (i.e., not from a web page 534 through a web browser), the client can connect to any WebSocket 535 endpoint. Section 6.3 and Section 6.4 define new URI schemes that 536 enable the client to identify both a WebSocket endpoint and the path 537 and query of the CoAP resource within that endpoint. When the 538 WebSocket protocol is used from a web page, the choices are more 539 limited [RFC6454], but the challenge persists. 541 Another possible configuration is to set up a CoAP forward proxy at 542 the WebSocket endpoint. Depending on what transports are available 543 to the proxy, it could forward the request to a CoAP server with a 544 CoAP UDP endpoint (Figure 10), an SMS endpoint (a.k.a. mobile phone), 545 or even another WebSocket endpoint. The CoAP client specifies the 546 resource to be updated or retrieved in the Proxy-Uri Option. 548 ___________ ___________ ___________ 549 | | | | | | 550 | _|___ ___|_ _|___ ___|_ | 551 | CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP | 552 | Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server | 553 | | | | | | 554 |___________| |___________| |___________| 555 WebSocket ===> WebSocket UDP UDP 556 Client Server Client Server 558 Figure 10: CoAP Client (WebSocket client) accesses CoAP Server (UDP 559 server) via a CoAP proxy (WebSocket server/UDP client) 561 A third possible configuration is a CoAP server running inside a web 562 browser (Figure 11). The web browser initially connects to a 563 WebSocket endpoint and is then reachable through the WebSocket 564 server. When no connection exists, the CoAP server is unreachable. 566 Because the WebSocket server is the only way to reach the CoAP 567 server, the CoAP proxy should be a Reverse Proxy. 569 ___________ ___________ ___________ 570 | | | | | | 571 | _|___ ___|_ _|___ ___|_ | 572 | CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP | 573 | Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server | 574 | | | | | | 575 |___________| |___________| |___________| 576 UDP UDP WebSocket <=== WebSocket 577 Client Server Server Client 579 Figure 11: CoAP Client (UDP client) accesses CoAP Server (WebSocket 580 client) via a CoAP proxy (UDP server/WebSocket server) 582 Further configurations are possible, including those where a 583 WebSocket connection is established through an HTTP proxy. 585 3.1. Opening Handshake 587 Before CoAP requests and responses are exchanged, a WebSocket 588 connection is established as defined in Section 4 of [RFC6455]. 589 Figure 12 shows an example. 591 The WebSocket client MUST include the subprotocol name "coap" in the 592 list of protocols, which indicates support for the protocol defined 593 in this document. Any later, incompatible versions of CoAP or CoAP 594 over WebSockets will use a different subprotocol name. 596 The WebSocket client includes the hostname of the WebSocket server in 597 the Host header field of its handshake as per [RFC6455]. The Host 598 header field also indicates the default value of the Uri-Host Option 599 in requests from the WebSocket client to the WebSocket server. 601 GET /.well-known/coap HTTP/1.1 602 Host: example.org 603 Upgrade: websocket 604 Connection: Upgrade 605 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 606 Sec-WebSocket-Protocol: coap 607 Sec-WebSocket-Version: 13 609 HTTP/1.1 101 Switching Protocols 610 Upgrade: websocket 611 Connection: Upgrade 612 Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 613 Sec-WebSocket-Protocol: coap 615 Figure 12: Example of an Opening Handshake 617 3.2. Message Format 619 Once a WebSocket connection is established, CoAP requests and 620 responses can be exchanged as WebSocket messages. Since CoAP uses a 621 binary message format, the messages are transmitted in binary data 622 frames as specified in Sections 5 and 6 of [RFC6455]. 624 The message format shown in Figure 13 is the same as the CoAP over 625 TCP message format (see Section 2.2) with one change. The Length 626 (Len) field MUST be set to zero because the WebSockets frame contains 627 the length. 629 0 1 2 3 630 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 631 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 632 | Len=0 | TKL | Code | Token (TKL bytes) ... 633 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 634 | Options (if any) ... 635 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 636 |1 1 1 1 1 1 1 1| Payload (if any) ... 637 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 639 Figure 13: CoAP Message Format over WebSockets 641 As with CoAP over TCP, the message format for CoAP over WebSockets 642 eliminates the Version field defined in CoAP over UDP. If CoAP 643 version negotiation is required in the future, CoAP over WebSockets 644 can address the requirement by the definition of a new subprotocol 645 identifier that is negotiated during the opening handshake. 647 Requests and response messages can be fragmented as specified in 648 Section 5.4 of [RFC6455], though typically they are sent unfragmented 649 as they tend to be small and fully buffered before transmission. The 650 WebSocket protocol does not provide means for multiplexing. If it is 651 not desirable for a large message to monopolize the connection, 652 requests and responses can be transferred in a block-wise fashion as 653 defined in [RFC7959]. 655 3.3. Message Transmission 657 As with CoAP over TCP, both endpoints MUST send a Capabilities and 658 Settings message (CSM see Section 4.3) as their first message on the 659 WebSocket connection. 661 CoAP requests and responses are exchanged asynchronously over the 662 WebSocket connection. A CoAP client can send multiple requests 663 without waiting for a response and the CoAP server can return 664 responses in any order. Responses MUST be returned over the same 665 connection as the originating request. Concurrent requests are 666 differentiated by their Token, which is scoped locally to the 667 connection. 669 The connection is bi-directional, so requests can be sent both by the 670 entity that established the connection and the remote host. 672 As with CoAP over TCP, retransmission and deduplication of messages 673 is provided by the WebSocket protocol. CoAP over WebSockets 674 therefore does not make a distinction between Confirmable or Non- 675 Confirmable messages, and does not provide Acknowledgement or Reset 676 messages. 678 3.4. Connection Health 680 As with CoAP over TCP, a CoAP client can test the health of the CoAP 681 over WebSocket connection by sending a CoAP Ping Signaling message 682 (Section 4.4). WebSocket Ping and unsolicited Pong frames 683 (Section 5.5 of [RFC6455]) SHOULD NOT be used to ensure that 684 redundant maintenance traffic is not transmitted. 686 4. Signaling 688 Signaling messages are introduced to allow peers to: 690 o Related characteristics such as maximum message size for the 691 connection 693 o Shut down the connection in an orderly fashion 695 o Provide diagnostic information when terminating a connection in 696 response to a serious error condition 698 Signaling is a third basic kind of message in CoAP, after requests 699 and responses. Signaling messages share a common structure with the 700 existing CoAP messages. There is a code, a token, options, and an 701 optional payload. 703 (See Section 3 of [RFC7252] for the overall structure, as adapted to 704 the specific transport.) 706 4.1. Signaling Codes 708 A code in the 7.00-7.31 range indicates a Signaling message. Values 709 in this range are assigned by the "CoAP Signaling Codes" sub-registry 710 (see Section 9.1). 712 For each message, there is a sender and a peer receiving the message. 714 Payloads in Signaling messages are diagnostic payloads as defined in 715 Section 5.5.2 of [RFC7252]), unless otherwise defined by a Signaling 716 message option. 718 4.2. Signaling Option Numbers 720 Option numbers for Signaling messages are specific to the message 721 code. They do not share the number space with CoAP options for 722 request/response messages or with Signaling messages using other 723 codes. 725 Option numbers are assigned by the "CoAP Signaling Option Numbers" 726 sub-registry (see Section 9.2). 728 Signaling options are elective or critical as defined in 729 Section 5.4.1 of [RFC7252]. If a Signaling option is critical and 730 not understood by the receiver, it MUST abort the connection (see 731 Section 4.6). If the option is understood but cannot be processed, 732 the option documents the behavior. 734 4.3. Capabilities and Settings Messages (CSM) 736 Capabilities and Settings messages (CSM) are used for two purposes: 738 o Each capability option advertises one capability of the sender to 739 the recipient. 741 o Setting options indicate a setting that will be applied by the 742 sender. 744 One CSM MUST be sent by both endpoints at the start of the 745 connection. Further CSM MAY be sent at any other time by either 746 endpoint over the lifetime of the connection. 748 Both capability and setting options are cumulative. A CSM does not 749 invalidate a previously sent capability indication or setting even if 750 it is not repeated. A capability message without any option is a no- 751 operation (and can be used as such). An option that is sent might 752 override a previous value for the same option. The option defines 753 how to handle this case if needed. 755 Base values are listed below for CSM Options. These are the values 756 for the capability and setting before any Capabilities and Settings 757 messages send a modified value. 759 These are not default values for the option as defined in 760 Section 5.4.4 in [RFC7252]. A default value would mean that an empty 761 Capabilities and Settings message would result in the option being 762 set to its default value. 764 Capabilities and Settings messages are indicated by the 7.01 code 765 (CSM). 767 4.3.1. Max-Message-Size Capability Option 769 The sender can use the elective Max-Message-Size Option to indicate 770 the maximum message size in bytes that it can receive. 772 +---+---+---+---------+------------------+--------+--------+--------+ 773 | # | C | R | Applies | Name | Format | Length | Base | 774 | | | | to | | | | Value | 775 +---+---+---+---------+------------------+--------+--------+--------+ 776 | 2 | | | CSM | Max-Message-Size | uint | 0-4 | 1152 | 777 +---+---+---+---------+------------------+--------+--------+--------+ 779 C=Critical, R=Repeatable 781 As per Section 4.6 of [RFC7252], the base value (and the value used 782 when this option is not implemented) is 1152. 784 The active value of the Max-Message-Size Option is replaced each time 785 the option is sent with a modified value. Its starting value is its 786 base value. 788 4.3.2. Block-wise Transfer Capability Option 790 +---+---+---+---------+-----------------+--------+--------+---------+ 791 | # | C | R | Applies | Name | Format | Length | Base | 792 | | | | to | | | | Value | 793 +---+---+---+---------+-----------------+--------+--------+---------+ 794 | 4 | | | CSM | Block-wise | empty | 0 | (none) | 795 | | | | | Transfer | | | | 796 +---+---+---+---------+-----------------+--------+--------+---------+ 798 C=Critical, R=Repeatable 800 A sender can use the elective Block-wise Transfer Option to indicate 801 that it supports the block-wise transfer protocol [RFC7959]. 803 If the option is not given, the peer has no information about whether 804 block-wise transfers are supported by the sender or not. An 805 implementation that supports block-wise transfers SHOULD indicate the 806 Block-wise Transfer Option. If a Max-Message-Size Option is 807 indicated with a value that is greater than 1152 (in the same or a 808 different CSM message), the Block-wise Transfer Option also indicates 809 support for BERT (see Section 5). Subsequently, if the Max-Message- 810 Size Option is indicated with a value equal or less than 1152, BERT 811 support is no longer indicated. 813 4.4. Ping and Pong Messages 815 In CoAP over reliable transports, Empty messages (Code 0.00) can 816 always be sent and MUST be ignored by the recipient. This provides a 817 basic keep-alive function. In contrast, Ping and Pong messages are a 818 bidirectional exchange. 820 Upon receipt of a Ping message, the receiver MUST return a Pong 821 message with an identical token in response. Unless there is an 822 option with delaying semantics such as the Custody Option, it SHOULD 823 respond as soon as practical. As with all Signaling messages, the 824 recipient of a Ping or Pong message MUST ignore elective options it 825 does not understand. 827 Ping and Pong messages are indicated by the 7.02 code (Ping) and the 828 7.03 code (Pong). 830 4.4.1. Custody Option 831 +---+---+---+----------+----------------+--------+--------+---------+ 832 | # | C | R | Applies | Name | Format | Length | Base | 833 | | | | to | | | | Value | 834 +---+---+---+----------+----------------+--------+--------+---------+ 835 | 2 | | | Ping, | Custody | empty | 0 | (none) | 836 | | | | Pong | | | | | 837 +---+---+---+----------+----------------+--------+--------+---------+ 839 C=Critical, R=Repeatable 841 When responding to a Ping message, the receiver can include an 842 elective Custody Option in the Pong message. This option indicates 843 that the application has processed all the request/response messages 844 received prior to the Ping message on the current connection. (Note 845 that there is no definition of specific application semantics for 846 "processed", but there is an expectation that the receiver of a Pong 847 Message with a Custody Option should be able to free buffers based on 848 this indication.) 850 A sender can also include an elective Custody Option in a Ping 851 message to explicitly request the inclusion of an elective Custody 852 Option in the corresponding Pong message. The receiver SHOULD delay 853 its Pong message until it finishes processing all the request/ 854 response messages received prior to the Ping message on the current 855 connection. 857 4.5. Release Messages 859 A Release message indicates that the sender does not want to continue 860 maintaining the connection and opts for an orderly shutdown. The 861 details are in the options. A diagnostic payload (see Section 5.5.2 862 of [RFC7252]) MAY be included. A peer will normally respond to a 863 Release message by closing the TCP/TLS connection. Messages may be 864 in flight when the sender decides to send a Release message. The 865 general expectation is that these will still be processed. 867 Release messages are indicated by the 7.04 code (Release). 869 Release messages can indicate one or more reasons using elective 870 options. The following options are defined: 872 +---+---+---+---------+------------------+--------+--------+--------+ 873 | # | C | R | Applies | Name | Format | Length | Base | 874 | | | | to | | | | Value | 875 +---+---+---+---------+------------------+--------+--------+--------+ 876 | 2 | | x | Release | Alternative- | string | 1-255 | (none) | 877 | | | | | Address | | | | 878 +---+---+---+---------+------------------+--------+--------+--------+ 880 C=Critical, R=Repeatable 882 The elective Alternative-Address Option requests the peer to instead 883 open a connection of the same scheme as the present connection to the 884 alternative transport address given. Its value is in the form 885 "authority" as defined in Section 3.2 of [RFC3986]. 887 The Alternative-Address Option is a repeatable option as defined in 888 Section 5.4.5 of [RFC7252]. 890 +---+---+---+---------+-----------------+--------+--------+---------+ 891 | # | C | R | Applies | Name | Format | Length | Base | 892 | | | | to | | | | Value | 893 +---+---+---+---------+-----------------+--------+--------+---------+ 894 | 4 | | | Release | Hold-Off | uint | 0-3 | (none) | 895 +---+---+---+---------+-----------------+--------+--------+---------+ 897 C=Critical, R=Repeatable 899 The elective Hold-Off Option indicates that the server is requesting 900 that the peer not reconnect to it for the number of seconds given in 901 the value. 903 4.6. Abort Messages 905 An Abort message indicates that the sender is unable to continue 906 maintaining the connection and cannot even wait for an orderly 907 release. The sender shuts down the connection immediately after the 908 abort (and may or may not wait for a Release or Abort message or 909 connection shutdown in the inverse direction). A diagnostic payload 910 (see Section 5.5.2 of [RFC7252]) SHOULD be included in the Abort 911 message. Messages may be in flight when the sender decides to send 912 an Abort message. The general expectation is that these will NOT be 913 processed. 915 Abort messages are indicated by the 7.05 code (Abort). 917 Abort messages can indicate one or more reasons using elective 918 options. The following option is defined: 920 +---+---+---+---------+-----------------+--------+--------+---------+ 921 | # | C | R | Applies | Name | Format | Length | Base | 922 | | | | to | | | | Value | 923 +---+---+---+---------+-----------------+--------+--------+---------+ 924 | 2 | | | Abort | Bad-CSM-Option | uint | 0-2 | (none) | 925 +---+---+---+---------+-----------------+--------+--------+---------+ 927 C=Critical, R=Repeatable 929 The elective Bad-CSM-Option Option indicates that the sender is 930 unable to process the CSM option identified by its option number, 931 e.g. when it is critical and the option number is unknown by the 932 sender, or when there is parameter problem with the value of an 933 elective option. More detailed information SHOULD be included as a 934 diagnostic payload. 936 One reason for an sender to generate an Abort message is a general 937 syntax error in the byte-stream received. No specific option has 938 been defined for this, as the details of that syntax error are best 939 left to a diagnostic payload. 941 4.7. Signaling examples 943 An encoded example of a Ping message with a non-empty token is shown 944 in Figure 14. 946 0 1 2 947 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 948 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 949 | 0x01 | 0xe2 | 0x42 | 950 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 952 Len = 0 -------> 0x01 953 TKL = 1 ___/ 954 Code = 7.02 Ping --> 0xe2 955 Token = 0x42 957 Figure 14: Ping Message Example 959 An encoded example of the corresponding Pong message is shown in 960 Figure 15. 962 0 1 2 963 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 964 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 965 | 0x01 | 0xe3 | 0x42 | 966 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 968 Len = 0 -------> 0x01 969 TKL = 1 ___/ 970 Code = 7.03 Pong --> 0xe3 971 Token = 0x42 973 Figure 15: Pong Message Example 975 5. Block-wise Transfer and Reliable Transports 977 The message size restrictions defined in Section 4.6 of CoAP 978 [RFC7252] to avoid IP fragmentation are not necessary when CoAP is 979 used over a reliable transport. While this suggests that the Block- 980 wise transfer protocol [RFC7959] is also no longer needed, it remains 981 applicable for a number of cases: 983 o large messages, such as firmware downloads, may cause undesired 984 head-of-line blocking when a single TCP connection is used 986 o a UDP-to-TCP gateway may simply not have the context to convert a 987 message with a Block Option into the equivalent exchange without 988 any use of a Block Option (it would need to convert the entire 989 blockwise exchange from start to end into a single exchange) 991 The 'Block-wise Extension for Reliable Transport (BERT)' extends the 992 Block protocol to enable the use of larger messages over a reliable 993 transport. 995 The use of this new extension is signaled by sending Block1 or Block2 996 Options with SZX == 7 (a "BERT option"). SZX == 7 is a reserved 997 value in [RFC7959]. 999 In control usage, a BERT option is interpreted in the same way as the 1000 equivalent Option with SZX == 6, except that it also indicates the 1001 capability to process BERT blocks. As with the basic Block protocol, 1002 the recipient of a CoAP request with a BERT option in control usage 1003 is allowed to respond with a different SZX value, e.g. to send a non- 1004 BERT block instead. 1006 In descriptive usage, a BERT Option is interpreted in the same way as 1007 the equivalent Option with SZX == 6, except that the payload is 1008 allowed to contain a multiple of 1024 bytes (non-final BERT block) or 1009 more than 1024 bytes (final BERT block). 1011 The recipient of a non-final BERT block (M=1) conceptually partitions 1012 the payload into a sequence of 1024-byte blocks and acts exactly as 1013 if it had received this sequence in conjunction with block numbers 1014 starting at, and sequentially increasing from, the block number given 1015 in the Block Option. In other words, the entire BERT block is 1016 positioned at the byte position that results from multiplying the 1017 block number with 1024. The position of further blocks to be 1018 transferred is indicated by incrementing the block number by the 1019 number of elements in this sequence (i.e., the size of the payload 1020 divided by 1024 bytes). 1022 As with SZX == 6, the recipient of a final BERT block (M=0) simply 1023 appends the payload at the byte position that is indicated by the 1024 block number multiplied with 1024. 1026 The following examples illustrate BERT options. A value of SZX == 7 1027 is labeled as "BERT" or as "BERT(nnn)" to indicate a payload of size 1028 nnn. 1030 In all these examples, a Block Option is decomposed to indicate the 1031 kind of Block Option (1 or 2) followed by a colon, the block number 1032 (NUM), more bit (M), and block size exponent (2**(SZX+4)) separated 1033 by slashes. E.g., a Block2 Option value of 33 would be shown as 1034 2:2/0/32), or a Block1 Option value of 59 would be shown as 1035 1:3/1/128. 1037 5.1. Example: GET with BERT Blocks 1039 Figure 16 shows a GET request with a response that is split into 1040 three BERT blocks. The first response contains 3072 bytes of 1041 payload; the second, 5120; and the third, 4711. Note how the block 1042 number increments to move the position inside the response body 1043 forward. 1045 CoAP Client CoAP Server 1046 | | 1047 | GET, /status ------> | 1048 | | 1049 | <------ 2.05 Content, 2:0/1/BERT(3072) | 1050 | | 1051 | GET, /status, 2:3/0/BERT ------> | 1052 | | 1053 | <------ 2.05 Content, 2:3/1/BERT(5120) | 1054 | | 1055 | GET, /status, 2:8/0/BERT ------> | 1056 | | 1057 | <------ 2.05 Content, 2:8/0/BERT(4711) | 1059 Figure 16: GET with BERT blocks 1061 5.2. Example: PUT with BERT Blocks 1063 Figure 17 demonstrates a PUT exchange with BERT blocks. 1065 CoAP Client CoAP Server 1066 | | 1067 | PUT, /options, 1:0/1/BERT(8192) ------> | 1068 | | 1069 | <------ 2.31 Continue, 1:0/1/BERT | 1070 | | 1071 | PUT, /options, 1:8/1/BERT(16384) ------> | 1072 | | 1073 | <------ 2.31 Continue, 1:8/1/BERT | 1074 | | 1075 | PUT, /options, 1:24/0/BERT(5683) ------> | 1076 | | 1077 | <------ 2.04 Changed, 1:24/0/BERT | 1078 | | 1080 Figure 17: PUT with BERT blocks 1082 6. CoAP over Reliable Transport URIs 1084 CoAP over UDP [RFC7252] defines the "coap" and "coaps" URI schemes. 1085 This document introduces four additional URI schemes for identifying 1086 CoAP resources and providing a means of locating the resource: 1088 o the "coap+tcp" URI scheme for CoAP over TCP 1090 o the "coaps+tcp" URI scheme for CoAP over TCP secured by TLS 1092 o the "coap+ws" URI scheme for CoAP over WebSockets 1093 o the "coaps+ws" URI scheme for CoAP over WebSockets secured by TLS 1095 Resources made available via these schemes have no shared identity 1096 even if their resource identifiers indicate the same authority (the 1097 same host listening to the same TCP port). They are distinct 1098 namespaces and are considered to be distinct origin servers. 1100 The syntax for the URI schemes in this section are specified using 1101 Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of 1102 "host", "port", "path-abempty", and "query" are adopted from 1103 [RFC3986]. 1105 Section 8 (Multicast CoAP) in [RFC7252] is not applicable to these 1106 schemes. 1108 6.1. coap+tcp URI scheme 1110 The "coap+tcp" URI scheme identifies CoAP resources that are intended 1111 to be accessible using CoAP over TCP. 1113 coap+tcp-URI = 1114 "coap+tcp:" "//" host [ ":" port ] path-abempty [ "?" query ] 1116 The syntax defined in Section 6.1 of [RFC7252] applies to this URI 1117 scheme with the following changes: 1119 o The port subcomponent indicates the TCP port at which the CoAP 1120 server is located. (If it is empty or not given, then the default 1121 port 5683 is assumed, as with UDP.) 1123 Encoding considerations: The scheme encoding conforms to the 1124 encoding rules established for URIs in [RFC3986]. 1126 Interoperability considerations: None. 1128 Security considerations: See Section 11.1 of [RFC7252]. 1130 6.2. coaps+tcp URI scheme 1132 The "coaps+tcp" URI scheme identifies CoAP resources that are 1133 intended to be accessible using CoAP over TCP secured with TLS. 1135 coaps+tcp-URI = 1136 "coaps+tcp:" "//" host [ ":" port ] path-abempty [ "?" query ] 1138 The syntax defined in Section 6.2 of [RFC7252] applies to this URI 1139 scheme, with the following changes: 1141 o The port subcomponent indicates the TCP port at which the TLS 1142 server for the CoAP server is located. If it is empty or not 1143 given, then the default port 443 is assumed (this is different 1144 from the default port for "coaps", i.e., CoAP over DTLS over UDP). 1146 o If a TLS server does not support the Application-Layer Protocol 1147 Negotiation Extension (ALPN) [RFC7301] or wishes to accommodate 1148 TLS clients that do not support ALPN, it MAY offer a coaps+tcp 1149 endpoint on TCP port 5684. This endpoint MAY also be ALPN 1150 enabled. A TLS server MAY offer coaps+tcp endpoints on ports 1151 other than TCP port 5684, which MUST be ALPN enabled. 1153 o For TCP ports other than port 5684, the TLS client MUST use the 1154 ALPN extension to advertise the "coap" protocol identifier (see 1155 Section 9.7) in the list of protocols in its ClientHello. If the 1156 TCP server selects and returns the "coap" protocol identifier 1157 using the ALPN extension in its ServerHello, then the connection 1158 succeeds. If the TLS server either does not negotiate the ALPN 1159 extension or returns a no_application_protocol alert, the TLS 1160 client MUST close the connection. 1162 o For TCP port 5684, a TLS client MAY use the ALPN extension to 1163 advertise the "coap" protocol identifier in the list of protocols 1164 in its ClientHello. If the TLS server selects and returns the 1165 "coap" protocol identifier using the ALPN extension in its 1166 ServerHello, then the connection succeeds. If the TLS server 1167 returns a no_application_protocol alert, then the TLS client MUST 1168 close the connection. If the TLS server does not negotiate the 1169 ALPN extension, then coaps+tcp is implicitly selected. 1171 o For TCP port 5684, if the TLS client does not use the ALPN 1172 extension to negotiate the protocol, then coaps+tcp is implicitly 1173 selected. 1175 Encoding considerations: The scheme encoding conforms to the 1176 encoding rules established for URIs in [RFC3986]. 1178 Interoperability considerations: None. 1180 Security considerations: See Section 11.1 of [RFC7252]. 1182 6.3. coap+ws URI scheme 1184 The "coap+ws" URI scheme identifies CoAP resources that are intended 1185 to be accessible using CoAP over WebSockets. 1187 coap-ws-URI = 1188 "coap+ws:" "//" host [ ":" port ] path-abempty [ "?" query ] 1190 The port component is OPTIONAL. The default is port 80. 1192 The WebSocket endpoint is identified by a "ws" URI that is composed 1193 of the authority part of the "coap+ws" URI and the well-known path 1194 "/.well-known/coap" [RFC5785]. The path and query parts of a 1195 "coap+ws" URI identify a resource within the specified endpoint which 1196 can be operated on by the methods defined by CoAP: 1198 coap+ws://example.org/sensors/temperature?u=Cel 1199 \______ ______/\___________ ___________/ 1200 \/ \/ 1201 Uri-Path: "sensors" 1202 ws://example.org/.well-known/coap Uri-Path: "temperature" 1203 Uri-Query: "u=Cel" 1205 Figure 18: The "coap+ws" URI Scheme 1207 Encoding considerations: The scheme encoding conforms to the 1208 encoding rules established for URIs in [RFC3986]. 1210 Interoperability considerations: None. 1212 Security considerations: See Section 11.1 of [RFC7252]. 1214 6.4. coaps+ws URI scheme 1216 The "coaps+ws" URI scheme identifies CoAP resources that are intended 1217 to be accessible using CoAP over WebSockets secured by TLS. 1219 coaps-ws-URI = 1220 "coaps+ws:" "//" host [ ":" port ] path-abempty [ "?" query ] 1222 The port component is OPTIONAL. The default is port 443. 1224 The WebSocket endpoint is identified by a "wss" URI that is composed 1225 of the authority part of the "coaps+ws" URI and the well-known path 1226 "/.well-known/coap" [RFC5785]. The path and query parts of a 1227 "coaps+ws" URI identify a resource within the specified endpoint 1228 which can be operated on by the methods defined by CoAP. 1230 coaps+ws://example.org/sensors/temperature?u=Cel 1231 \______ ______/\___________ ___________/ 1232 \/ \/ 1233 Uri-Path: "sensors" 1234 wss://example.org/.well-known/coap Uri-Path: "temperature" 1235 Uri-Query: "u=Cel" 1237 Figure 19: The "coaps+ws" URI Scheme 1239 Encoding considerations: The scheme encoding conforms to the 1240 encoding rules established for URIs in [RFC3986]. 1242 Interoperability considerations: None. 1244 Security considerations: See Section 11.1 of [RFC7252]. 1246 6.5. Uri-Host and Uri-Port Options 1248 CoAP over reliable transports maintains the property from 1249 Section 5.10.1 of [RFC7252]: 1251 The default values for the Uri-Host and Uri-Port Options are 1252 sufficient for requests to most servers. 1254 Unless otherwise noted, the default value of the Uri-Host Option is 1255 the IP literal representing the destination IP address of the request 1256 message. The default value of the Uri-Port Option is the destination 1257 TCP port. 1259 For CoAP over TLS, these default values are the same unless Server 1260 Name Indication (SNI) [RFC6066] is negotiated. In this case, the 1261 default value of the Uri-Host Option in requests from the TLS client 1262 to the TLS server is the SNI host. 1264 For CoAP over WebSockets, the default value of the Uri-Host Option in 1265 requests from the WebSocket client to the WebSocket server is 1266 indicated by the Host header field from the WebSocket handshake. 1268 6.6. Decomposing URIs into Options 1270 The steps are the same as specified in Section 6.4 of [RFC7252] with 1271 the following changes: 1273 3. If |url| does not have a component whose value, when 1274 converted to ASCII lowercase, is "coap" or "coaps", then fail 1275 this algorithm. 1277 If |url| does not have a component whose value, when 1278 converted to ASCII lowercase, is "coap+tcp", "coaps+tcp", "coap+ws", 1279 or "coaps+ws" then fail this algorithm. 1281 7. If |port| does not equal the request's destination UDP port, 1282 include a Uri-Port Option and let that option's value be |port|. 1284 If |port| does not equal the request's destination TCP port, include 1285 a Uri-Port Option and let that option's value be |port|. 1287 6.7. Composing URIs from Options 1289 The steps are the same as specified in Section 6.5 of [RFC7252] with 1290 the following changes: 1292 1. If the request is secured using DTLS, let |url| be the string 1293 "coaps://". Otherwise, let |url| be the string "coap://". 1295 For CoAP over TCP, if the request is secured using TLS, let |url| be 1296 the string "coaps+tcp://". Otherwise, let |url| be the string 1297 "coap+tcp://". For CoAP over WebSockets, if the request is secured 1298 using TLS, let |url| be the string "coaps+ws://". Otherwise, 1299 let |url| be the string "coap+ws://". 1301 4. If the request includes a Uri-Port Option, let |port| be that 1302 option's value. Otherwise, let |port| be the request's 1303 destination UDP port. 1305 If the request includes a Uri-Port Option, let |port| be that 1306 option's value. Otherwise, let |port| be the request's destination 1307 TCP port. 1309 7. Securing CoAP 1311 Security Challenges for the Internet of Things [SecurityChallenges] 1312 recommends: 1314 ... it is essential that IoT protocol suites specify a mandatory 1315 to implement but optional to use security solution. This will 1316 ensure security is available in all implementations, but 1317 configurable to use when not necessary (e.g., in closed 1318 environment). ... even if those features stretch the capabilities 1319 of such devices. 1321 A security solution MUST be implemented to protect CoAP over reliable 1322 transports and MUST be enabled by default. This document defines the 1323 TLS binding, but alternative solutions at different layers in the 1324 protocol stack MAY be used to protect CoAP over reliable transports 1325 when appropriate. Note that there is ongoing work to support a data 1326 object-based security model for CoAP that is independent of transport 1327 (see [I-D.ietf-core-object-security]). 1329 7.1. TLS binding for CoAP over TCP 1331 The TLS usage guidance in [RFC7925] applies. 1333 During the provisioning phase, a CoAP device is provided with the 1334 security information that it needs, including keying materials, 1335 access control lists, and authorization servers. At the end of the 1336 provisioning phase, the device will be in one of four security modes: 1338 NoSec: TLS is disabled. 1340 PreSharedKey: TLS is enabled. The guidance in Section 4.2 of 1341 [RFC7925] applies. 1343 RawPublicKey: TLS is enabled. The guidance in Section 4.3 of 1344 [RFC7925] applies. 1346 Certificate: TLS is enabled. The guidance in Section 4.4 of 1347 [RFC7925] applies. 1349 The "NoSec" mode is mandatory-to-implement. The system simply sends 1350 the packets over normal TCP which is indicated by the "coap+tcp" 1351 scheme and the TCP CoAP default port. The system is secured only by 1352 keeping attackers from being able to send or receive packets from the 1353 network with the CoAP nodes. 1355 "PreSharedKey", "RawPublicKey", or "Certificate" is mandatory-to- 1356 implement for the TLS binding depending on the credential type used 1357 with the device. These security modes are achieved using TLS and are 1358 indicated by the "coaps+tcp" scheme and TLS-secured CoAP default 1359 port. 1361 7.2. TLS usage for CoAP over WebSockets 1363 A CoAP client requesting a resource identified by a "coaps+ws" URI 1364 negotiates a secure WebSocket connection to a WebSocket server 1365 endpoint with a "wss" URI. This is described in Section 6.4. 1367 The client MUST perform a TLS handshake after opening the connection 1368 to the server. The guidance in Section 4.1 of [RFC6455] applies. 1369 When a CoAP server exposes resources identified by a "coaps+ws" URI, 1370 the guidance in Section 4.4 of [RFC7925] applies towards mandatory- 1371 to-implement TLS functionality for certificates. For the server-side 1372 requirements in accepting incoming connections over a HTTPS (HTTP- 1373 over-TLS) port, the guidance in Section 4.2 of [RFC6455] applies. 1375 8. Security Considerations 1377 The security considerations of [RFC7252] apply. For CoAP over 1378 WebSockets and CoAP over TLS-secured WebSockets, the security 1379 considerations of [RFC6455] also apply. 1381 8.1. Signaling Messages 1383 o The guidance given by an Alternative-Address Option cannot be 1384 followed blindly. In particular, a peer MUST NOT assume that a 1385 successful connection to the Alternative-Address inherits all the 1386 security properties of the current connection. 1388 9. IANA Considerations 1390 9.1. Signaling Codes 1392 IANA is requested to create a third sub-registry for values of the 1393 Code field in the CoAP header (Section 12.1 of [RFC7252]). The name 1394 of this sub-registry is "CoAP Signaling Codes". 1396 Each entry in the sub-registry must include the Signaling Code in the 1397 range 7.00-7.31, its name, and a reference to its documentation. 1399 Initial entries in this sub-registry are as follows: 1401 +------+---------+-----------+ 1402 | Code | Name | Reference | 1403 +------+---------+-----------+ 1404 | 7.01 | CSM | [RFCthis] | 1405 | | | | 1406 | 7.02 | Ping | [RFCthis] | 1407 | | | | 1408 | 7.03 | Pong | [RFCthis] | 1409 | | | | 1410 | 7.04 | Release | [RFCthis] | 1411 | | | | 1412 | 7.05 | Abort | [RFCthis] | 1413 +------+---------+-----------+ 1415 Table 1: CoAP Signal Codes 1417 All other Signaling Codes are Unassigned. 1419 The IANA policy for future additions to this sub-registry is "IETF 1420 Review or IESG Approval" as described in [RFC5226]. 1422 9.2. CoAP Signaling Option Numbers Registry 1424 IANA is requested to create a sub-registry for Options Numbers used 1425 in CoAP signaling options within the "CoRE Parameters" registry. The 1426 name of this sub-registry is "CoAP Signaling Option Numbers". 1428 Each entry in the sub-registry must include one or more of the codes 1429 in the Signaling Codes subregistry (Section 9.1), the option number, 1430 the name of the option, and a reference to the option's 1431 documentation. 1433 Initial entries in this sub-registry are as follows: 1435 +------------+--------+---------------------+-----------+ 1436 | Applies to | Number | Name | Reference | 1437 +------------+--------+---------------------+-----------+ 1438 | 7.01 | 2 | Max-Message-Size | [RFCthis] | 1439 | | | | | 1440 | 7.01 | 4 | Block-wise-Transfer | [RFCthis] | 1441 | | | | | 1442 | 7.02, 7.03 | 2 | Custody | [RFCthis] | 1443 | | | | | 1444 | 7.04 | 2 | Alternative-Address | [RFCthis] | 1445 | | | | | 1446 | 7.04 | 4 | Hold-Off | [RFCthis] | 1447 | | | | | 1448 | 7.05 | 2 | Bad-CSM-Option | [RFCthis] | 1449 +------------+--------+---------------------+-----------+ 1451 Table 2: CoAP Signal Option Codes 1453 The IANA policy for future additions to this sub-registry is based on 1454 number ranges for the option numbers, analogous to the policy defined 1455 in Section 12.2 of [RFC7252]. 1457 The documentation for a Signaling Option Number should specify the 1458 semantics of an option with that number, including the following 1459 properties: 1461 o Whether the option is critical or elective, as determined by the 1462 Option Number. 1464 o Whether the option is repeatable. 1466 o The format and length of the option's value. 1468 o The base value for the option, if any. 1470 9.3. Service Name and Port Number Registration 1472 IANA is requested to assign the port number 5683 and the service name 1473 "coap+tcp", in accordance with [RFC6335]. 1475 Service Name. 1477 coap+tcp 1479 Transport Protocol. 1480 tcp 1482 Assignee. 1483 IESG 1485 Contact. 1486 IETF Chair 1488 Description. 1489 Constrained Application Protocol (CoAP) 1491 Reference. 1492 [RFCthis] 1494 Port Number. 1495 5683 1497 9.4. Secure Service Name and Port Number Registration 1499 IANA is requested to assign the port number 5684 and the service name 1500 "coaps+tcp", in accordance with [RFC6335]. The port number is 1501 requested to address the exceptional case of TLS implementations that 1502 do not support the "Application-Layer Protocol Negotiation Extension" 1503 [RFC7301]. 1505 Service Name. 1506 coaps+tcp 1508 Transport Protocol. 1509 tcp 1511 Assignee. 1512 IESG 1514 Contact. 1515 IETF Chair 1517 Description. 1518 Constrained Application Protocol (CoAP) 1520 Reference. 1521 [RFC7301], [RFCthis] 1523 Port Number. 1524 5684 1526 9.5. URI Scheme Registration 1528 URI schemes are registered within the "Uniform Resource Identifier 1529 (URI) Schemes" registry maintained at 1530 http://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml . 1532 9.5.1. coap+tcp 1534 IANA is requested to register the Uniform Resource Identifier (URI) 1535 scheme "coap+tcp". This registration request complies with 1536 [RFC7595]. 1538 Scheme name: 1539 coap+tcp 1541 Status: 1542 Permanent 1544 Applications/protocols that use this scheme name: 1545 The scheme is used by CoAP endpoints to access CoAP resources 1546 using TCP. 1548 Contact: 1549 IETF chair 1551 Change controller: 1552 IESG 1554 Reference: 1555 Section 6.1 in [RFCthis] 1557 9.5.2. coaps+tcp 1559 IANA is requested to register the Uniform Resource Identifier (URI) 1560 scheme "coaps+tcp". This registration request complies with 1561 [RFC7595]. 1563 Scheme name: 1564 coaps+tcp 1566 Status: 1567 Permanent 1569 Applications/protocols that use this scheme name: 1570 The scheme is used by CoAP endpoints to access CoAP resources 1571 using TLS. 1573 Contact: 1575 IETF chair 1577 Change controller: 1578 IESG 1580 Reference: 1581 Section 6.2 in [RFCthis] 1583 9.5.3. coap+ws 1585 IANA is requested to register the Uniform Resource Identifier (URI) 1586 scheme "coap+ws". This registration request complies with [RFC7595]. 1588 Scheme name: 1589 coap+ws 1591 Status: 1592 Permanent 1594 Applications/protocols that use this scheme name: 1595 The scheme is used by CoAP endpoints to access CoAP resources 1596 using the WebSocket protocol. 1598 Contact: 1599 IETF chair 1601 Change controller: 1602 IESG 1604 Reference: 1605 Section 6.3 in [RFCthis] 1607 9.5.4. coaps+ws 1609 IANA is requested to register the Uniform Resource Identifier (URI) 1610 scheme "coaps+ws". This registration request complies with 1611 [RFC7595]. 1613 Scheme name: 1614 coaps+ws 1616 Status: 1617 Permanent 1619 Applications/protocols that use this scheme name: 1620 The scheme is used by CoAP endpoints to access CoAP resources 1621 using the WebSocket protocol secured with TLS. 1623 Contact: 1624 IETF chair 1626 Change controller: 1627 IESG 1629 References: 1630 Section 6.4 in [RFCthis] 1632 9.6. Well-Known URI Suffix Registration 1634 IANA is requested to register the 'coap' well-known URI in the "Well- 1635 Known URIs" registry. This registration request complies with 1636 [RFC5785]: 1638 URI Suffix. 1639 coap 1641 Change controller. 1642 IETF 1644 Specification document(s). 1645 [RFCthis] 1647 Related information. 1648 None. 1650 9.7. ALPN Protocol Identifier 1652 IANA is requested to assign the following value in the registry 1653 "Application Layer Protocol Negotiation (ALPN) Protocol IDs" created 1654 by [RFC7301]. The "coap" string identifies CoAP when used over TLS. 1656 Protocol. 1657 CoAP 1659 Identification Sequence. 1660 0x63 0x6f 0x61 0x70 ("coap") 1662 Reference. 1663 [RFCthis] 1665 9.8. WebSocket Subprotocol Registration 1667 IANA is requested to register the WebSocket CoAP subprotocol under 1668 the "WebSocket Subprotocol Name Registry": 1670 Subprotocol Identifier. 1672 coap 1674 Subprotocol Common Name. 1675 Constrained Application Protocol (CoAP) 1677 Subprotocol Definition. 1678 [RFCthis] 1680 10. References 1682 10.1. Normative References 1684 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 1685 RFC 793, DOI 10.17487/RFC0793, September 1981, 1686 . 1688 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1689 Requirement Levels", BCP 14, RFC 2119, 1690 DOI 10.17487/RFC2119, March 1997, 1691 . 1693 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1694 Resource Identifier (URI): Generic Syntax", STD 66, 1695 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1696 . 1698 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1699 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1700 DOI 10.17487/RFC5226, May 2008, 1701 . 1703 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1704 (TLS) Protocol Version 1.2", RFC 5246, 1705 DOI 10.17487/RFC5246, August 2008, 1706 . 1708 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1709 Uniform Resource Identifiers (URIs)", RFC 5785, 1710 DOI 10.17487/RFC5785, April 2010, 1711 . 1713 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 1714 Extensions: Extension Definitions", RFC 6066, 1715 DOI 10.17487/RFC6066, January 2011, 1716 . 1718 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 1719 RFC 6455, DOI 10.17487/RFC6455, December 2011, 1720 . 1722 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1723 Application Protocol (CoAP)", RFC 7252, 1724 DOI 10.17487/RFC7252, June 2014, 1725 . 1727 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 1728 "Transport Layer Security (TLS) Application-Layer Protocol 1729 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1730 July 2014, . 1732 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 1733 and Registration Procedures for URI Schemes", BCP 35, 1734 RFC 7595, DOI 10.17487/RFC7595, June 2015, 1735 . 1737 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1738 Application Protocol (CoAP)", RFC 7641, 1739 DOI 10.17487/RFC7641, September 2015, 1740 . 1742 [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer 1743 Security (TLS) / Datagram Transport Layer Security (DTLS) 1744 Profiles for the Internet of Things", RFC 7925, 1745 DOI 10.17487/RFC7925, July 2016, 1746 . 1748 10.2. Informative References 1750 [HomeGateway] 1751 Eggert, L., "An experimental study of home gateway 1752 characteristics", Proceedings of the 10th annual 1753 conference on Internet measurement , 2010. 1755 [I-D.ietf-core-cocoa] 1756 Bormann, C., Betzler, A., Gomez, C., and I. Demirkol, 1757 "CoAP Simple Congestion Control/Advanced", draft-ietf- 1758 core-cocoa-00 (work in progress), October 2016. 1760 [I-D.ietf-core-object-security] 1761 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1762 "Object Security of CoAP (OSCOAP)", draft-ietf-core- 1763 object-security-01 (work in progress), December 2016. 1765 [LWM2M] Open Mobile Alliance, "Lightweight Machine to Machine 1766 Technical Specification Version 1.0", February 2017, 1767 . 1771 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 1772 DOI 10.17487/RFC0768, August 1980, 1773 . 1775 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1776 Specifications: ABNF", STD 68, RFC 5234, 1777 DOI 10.17487/RFC5234, January 2008, 1778 . 1780 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 1781 Cheshire, "Internet Assigned Numbers Authority (IANA) 1782 Procedures for the Management of the Service Name and 1783 Transport Protocol Port Number Registry", BCP 165, 1784 RFC 6335, DOI 10.17487/RFC6335, August 2011, 1785 . 1787 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1788 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1789 January 2012, . 1791 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1792 DOI 10.17487/RFC6454, December 2011, 1793 . 1795 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1796 Protocol (HTTP/1.1): Message Syntax and Routing", 1797 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1798 . 1800 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1801 the Constrained Application Protocol (CoAP)", RFC 7959, 1802 DOI 10.17487/RFC7959, August 2016, 1803 . 1805 [SecurityChallenges] 1806 Polk, T. and S. Turner, "Security Challenges for the 1807 Internet of Things", Interconnecting Smart Objects with 1808 the Internet / IAB Workshop , February 2011, 1809 . 1812 Appendix A. Updates to RFC7641 Observing Resources in the Constrained 1813 Application Protocol (CoAP) 1815 In this appendix, "client" and "server" refer to the CoAP client and 1816 CoAP server. 1818 A.1. Notifications and Reordering 1820 When using the Observe Option with CoAP over UDP, notifications from 1821 the server set the option value to an increasing sequence number for 1822 reordering detection on the client since messages can arrive in a 1823 different order than they were sent. This sequence number is not 1824 required for CoAP over reliable transports since the TCP protocol 1825 ensures reliable and ordered delivery of messages. The value of the 1826 Observe Option in 2.xx notifications MAY be empty on transmission and 1827 MUST be ignored on reception. 1829 A.2. Transmission and Acknowledgements 1831 For CoAP over UDP, server notifications to the client can be 1832 confirmable or non-confirmable. A confirmable message requires the 1833 client to either respond with an acknowledgement message or a reset 1834 message. An acknowledgement message indicates that the client is 1835 alive and wishes to receive further notifications. A reset message 1836 indicates that the client does not recognize the token which causes 1837 the server to remove the associated entry from the list of observers. 1839 Since TCP eliminates the need for the message layer to support 1840 reliability, CoAP over reliable transports does not support 1841 confirmable or non-confirmable message types. All notifications are 1842 delivered reliably to the client with positive acknowledgement of 1843 receipt occurring at the TCP level. If the client does not recognize 1844 the token in a notification, it MAY immediately abort the connection 1845 (see Section 4.6). 1847 A.3. Freshness 1849 For CoAP over UDP, if a client does not receive a notification for 1850 some time, it MAY send a new GET request with the same token as the 1851 original request to re-register its interest in a resource and verify 1852 that the server is still responsive. For CoAP over reliable 1853 transports, it is more efficient to check the health of the 1854 connection (and all its active observations) by sending a CoAP Ping 1855 Signaling message (Section 4.4) rather than individual requests to 1856 confirm active observations. 1858 A.4. Cancellation 1860 For CoAP over UDP, a client that is no longer interested in receiving 1861 notifications can "forget" the observation and respond to the next 1862 notification from the server with a reset message to cancel the 1863 observation. 1865 For CoAP over reliable transports, a client MUST explicitly 1866 deregister by issuing a GET request that has the Token field set to 1867 the token of the observation to be cancelled and includes an Observe 1868 Option with the value set to 1 (deregister). 1870 If the client observes one or more resources over a reliable 1871 transport, then the CoAP server (or intermediary in the role of the 1872 CoAP server) MUST remove all entries associated with the client 1873 endpoint from the lists of observers when the connection is either 1874 closed or times out. 1876 Appendix B. CoAP over WebSocket Examples 1878 This section gives examples for the first two configurations 1879 discussed in Section 3. 1881 An example of the process followed by a CoAP client to retrieve the 1882 representation of a resource identified by a "coap+ws" URI might be 1883 as follows. Figure 20 below illustrates the WebSocket and CoAP 1884 messages exchanged in detail. 1886 1. The CoAP client obtains the URI , for example, from a resource representation 1888 that it retrieved previously. 1890 2. It establishes a WebSocket connection to the endpoint URI 1891 composed of the authority "example.org" and the well-known path 1892 "/.well-known/coap", . 1894 3. It sends a single-frame, masked, binary message containing a CoAP 1895 request. The request indicates the target resource with the Uri- 1896 Path ("sensors", "temperature") and Uri-Query ("u=Cel") options. 1898 4. It waits for the server to return a response. 1900 5. The CoAP client uses the connection for further requests, or the 1901 connection is closed. 1903 CoAP CoAP 1904 Client Server 1905 (WebSocket (WebSocket 1906 Client) Server) 1908 | | 1909 | | 1910 +=========>| GET /.well-known/coap HTTP/1.1 1911 | | Host: example.org 1912 | | Upgrade: websocket 1913 | | Connection: Upgrade 1914 | | Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 1915 | | Sec-WebSocket-Protocol: coap 1916 | | Sec-WebSocket-Version: 13 1917 | | 1918 |<=========+ HTTP/1.1 101 Switching Protocols 1919 | | Upgrade: websocket 1920 | | Connection: Upgrade 1921 | | Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 1922 | | Sec-WebSocket-Protocol: coap 1923 | | 1924 | | 1925 +--------->| Binary frame (opcode=%x2, FIN=1, MASK=1) 1926 | | +-------------------------+ 1927 | | | GET | 1928 | | | Token: 0x53 | 1929 | | | Uri-Path: "sensors" | 1930 | | | Uri-Path: "temperature" | 1931 | | | Uri-Query: "u=Cel" | 1932 | | +-------------------------+ 1933 | | 1934 |<---------+ Binary frame (opcode=%x2, FIN=1, MASK=0) 1935 | | +-------------------------+ 1936 | | | 2.05 Content | 1937 | | | Token: 0x53 | 1938 | | | Payload: "22.3 Cel" | 1939 | | +-------------------------+ 1940 : : 1941 : : 1942 | | 1943 +--------->| Close frame (opcode=%x8, FIN=1, MASK=1) 1944 | | 1945 |<---------+ Close frame (opcode=%x8, FIN=1, MASK=0) 1946 | | 1948 Figure 20: A CoAP client retrieves the representation of a resource 1949 identified by a "coap+ws" URI 1951 Figure 21 shows how a CoAP client uses a CoAP forward proxy with a 1952 WebSocket endpoint to retrieve the representation of the resource 1953 "coap://[2001:DB8::1]/". The use of the forward proxy and the 1954 address of the WebSocket endpoint are determined by the client from 1955 local configuration rules. The request URI is specified in the 1956 Proxy-Uri Option. Since the request URI uses the "coap" URI scheme, 1957 the proxy fulfills the request by issuing a Confirmable GET request 1958 over UDP to the CoAP server and returning the response over the 1959 WebSocket connection to the client. 1961 CoAP CoAP CoAP 1962 Client Proxy Server 1963 (WebSocket (WebSocket (UDP 1964 Client) Server) Endpoint) 1966 | | | 1967 +--------->| | Binary frame (opcode=%x2, FIN=1, MASK=1) 1968 | | | +------------------------------------+ 1969 | | | | GET | 1970 | | | | Token: 0x7d | 1971 | | | | Proxy-Uri: "coap://[2001:DB8::1]/" | 1972 | | | +------------------------------------+ 1973 | | | 1974 | +--------->| CoAP message (Ver=1, T=Con, MID=0x8f54) 1975 | | | +------------------------------------+ 1976 | | | | GET | 1977 | | | | Token: 0x0a15 | 1978 | | | +------------------------------------+ 1979 | | | 1980 | |<---------+ CoAP message (Ver=1, T=Ack, MID=0x8f54) 1981 | | | +------------------------------------+ 1982 | | | | 2.05 Content | 1983 | | | | Token: 0x0a15 | 1984 | | | | Payload: "ready" | 1985 | | | +------------------------------------+ 1986 | | | 1987 |<---------+ | Binary frame (opcode=%x2, FIN=1, MASK=0) 1988 | | | +------------------------------------+ 1989 | | | | 2.05 Content | 1990 | | | | Token: 0x7d | 1991 | | | | Payload: "ready" | 1992 | | | +------------------------------------+ 1993 | | | 1995 Figure 21: A CoAP client retrieves the representation of a resource 1996 identified by a "coap" URI via a WebSockets-enabled CoAP proxy 1998 Appendix C. Change Log 2000 The RFC Editor is requested to remove this section at publication. 2002 C.1. Since draft-core-coap-tcp-tls-02 2004 Merged draft-savolainen-core-coap-websockets-07 Merged draft-bormann- 2005 core-block-bert-01 Merged draft-bormann-core-coap-sig-02 2007 C.2. Since draft-core-coap-tcp-tls-03 2009 Editorial updates 2011 Added mandatory exchange of Capabilities and Settings messages after 2012 connecting 2014 Added support for coaps+tcp port 5684 and more details on 2015 Application-Layer Protocol Negotiation (ALPN) 2017 Added guidance on CoAP Signaling Ping-Pong versus WebSocket Ping-Pong 2019 Updated references and requirements for TLS security considerations 2021 C.3. Since draft-core-coap-tcp-tls-04 2023 Updated references 2025 Added Appendix: Updates to RFC7641 Observing Resources in the 2026 Constrained Application Protocol (CoAP) 2028 Updated Capability and Settings Message (CSM) exchange in the Opening 2029 Handshake to allow initiator to send messages before receiving 2030 acceptor CSM 2032 C.4. Since draft-core-coap-tcp-tls-05 2034 Addressed feedback from Working Group Last Call 2036 Added Securing CoAP section and informative reference to OSCOAP 2038 Removed the Server-Name and Bad-Server-Name Options 2040 Clarified the Capability and Settings Message (CSM) exchange 2042 Updated Pong response requirements 2044 Added Connection Initiator and Connection Acceptor terminology where 2045 appropriate 2046 Updated LWM2M 1.0 informative reference 2048 Acknowledgements 2050 We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier 2051 Delaby, Christian Groves, Nadir Javed, Michael Koster, Matthias 2052 Kovatsch, Achim Kraus, David Navarro, Szymon Sasin, Goran Selander, 2053 Zach Shelby, Andrew Summers, Julien Vermillard, and Gengyu Wei for 2054 their feedback. 2056 Contributors 2058 Matthias Kovatsch 2059 Siemens AG 2060 Otto-Hahn-Ring 6 2061 Munich D-81739 2063 Phone: +49-173-5288856 2064 EMail: matthias.kovatsch@siemens.com 2066 Teemu Savolainen 2067 Nokia Technologies 2068 Hatanpaan valtatie 30 2069 Tampere FI-33100 2070 Finland 2072 Email: teemu.savolainen@nokia.com 2074 Valik Solorzano Barboza 2075 Zebra Technologies 2076 820 W. Jackson Blvd. Suite 700 2077 Chicago 60607 2078 United States of America 2080 Phone: +1-847-634-6700 2081 Email: vsolorzanobarboza@zebra.com 2083 Authors' Addresses 2084 Carsten Bormann 2085 Universitaet Bremen TZI 2086 Postfach 330440 2087 Bremen D-28359 2088 Germany 2090 Phone: +49-421-218-63921 2091 Email: cabo@tzi.org 2093 Simon Lemay 2094 Zebra Technologies 2095 820 W. Jackson Blvd. Suite 700 2096 Chicago 60607 2097 United States of America 2099 Phone: +1-847-634-6700 2100 Email: slemay@zebra.com 2102 Hannes Tschofenig 2103 ARM Ltd. 2104 110 Fulbourn Rd 2105 Cambridge CB1 9NJ 2106 Great Britain 2108 Email: Hannes.tschofenig@gmx.net 2109 URI: http://www.tschofenig.priv.at 2111 Klaus Hartke 2112 Universitaet Bremen TZI 2113 Postfach 330440 2114 Bremen D-28359 2115 Germany 2117 Phone: +49-421-218-63905 2118 Email: hartke@tzi.org 2120 Bilhanan Silverajan 2121 Tampere University of Technology 2122 Korkeakoulunkatu 10 2123 Tampere FI-33720 2124 Finland 2126 Email: bilhanan.silverajan@tut.fi 2127 Brian Raymor (editor) 2128 Microsoft 2129 One Microsoft Way 2130 Redmond 98052 2131 United States of America 2133 Email: brian.raymor@microsoft.com