idnits 2.17.00 (12 Aug 2021) /tmp/idnits10605/draft-ietf-core-coap-tcp-tls-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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 (March 06, 2017) is 1901 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 301, but not defined == Missing Reference: '------' is mentioned on line 301, but not defined == Missing Reference: 'RFCthis' is mentioned on line 1704, but not defined ** 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: draft-ietf-core-object-security has been published as RFC 8613 -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) Summary: 5 errors (**), 0 flaws (~~), 6 warnings (==), 2 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: September 7, 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 March 06, 2017 16 CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets 17 draft-ietf-core-coap-tcp-tls-07 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 September 7, 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 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 5 68 3. CoAP over TCP . . . . . . . . . . . . . . . . . . . . . . . . 6 69 3.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 6 70 3.2. Message Format . . . . . . . . . . . . . . . . . . . . . 7 71 3.3. Message Transmission . . . . . . . . . . . . . . . . . . 10 72 3.4. Connection Health . . . . . . . . . . . . . . . . . . . . 11 73 4. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . 11 74 4.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 13 75 4.2. Message Format . . . . . . . . . . . . . . . . . . . . . 14 76 4.3. Message Transmission . . . . . . . . . . . . . . . . . . 15 77 4.4. Connection Health . . . . . . . . . . . . . . . . . . . . 15 78 5. Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . 15 79 5.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 16 80 5.2. Signaling Option Numbers . . . . . . . . . . . . . . . . 16 81 5.3. Capabilities and Settings Messages (CSM) . . . . . . . . 16 82 5.4. Ping and Pong Messages . . . . . . . . . . . . . . . . . 18 83 5.5. Release Messages . . . . . . . . . . . . . . . . . . . . 19 84 5.6. Abort Messages . . . . . . . . . . . . . . . . . . . . . 20 85 5.7. Signaling examples . . . . . . . . . . . . . . . . . . . 21 86 6. Block-wise Transfer and Reliable Transports . . . . . . . . . 22 87 6.1. Example: GET with BERT Blocks . . . . . . . . . . . . . . 23 88 6.2. Example: PUT with BERT Blocks . . . . . . . . . . . . . . 24 89 7. CoAP over Reliable Transport URIs . . . . . . . . . . . . . . 24 90 7.1. coap+tcp URI scheme . . . . . . . . . . . . . . . . . . . 25 91 7.2. coaps+tcp URI scheme . . . . . . . . . . . . . . . . . . 25 92 7.3. coap+ws URI scheme . . . . . . . . . . . . . . . . . . . 26 93 7.4. coaps+ws URI scheme . . . . . . . . . . . . . . . . . . . 27 94 7.5. Uri-Host and Uri-Port Options . . . . . . . . . . . . . . 28 95 7.6. Decomposing URIs into Options . . . . . . . . . . . . . . 28 96 7.7. Composing URIs from Options . . . . . . . . . . . . . . . 29 98 8. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 29 99 8.1. TLS binding for CoAP over TCP . . . . . . . . . . . . . . 30 100 8.2. TLS usage for CoAP over WebSockets . . . . . . . . . . . 30 101 9. Security Considerations . . . . . . . . . . . . . . . . . . . 31 102 9.1. Signaling Messages . . . . . . . . . . . . . . . . . . . 31 103 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 104 10.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . 31 105 10.2. CoAP Signaling Option Numbers Registry . . . . . . . . . 32 106 10.3. Service Name and Port Number Registration . . . . . . . 33 107 10.4. Secure Service Name and Port Number Registration . . . . 34 108 10.5. URI Scheme Registration . . . . . . . . . . . . . . . . 34 109 10.6. Well-Known URI Suffix Registration . . . . . . . . . . . 37 110 10.7. ALPN Protocol Identifier . . . . . . . . . . . . . . . . 37 111 10.8. WebSocket Subprotocol Registration . . . . . . . . . . . 37 112 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 113 11.1. Normative References . . . . . . . . . . . . . . . . . . 38 114 11.2. Informative References . . . . . . . . . . . . . . . . . 39 115 Appendix A. Updates to RFC 7641 Observing Resources in the 116 Constrained Application Protocol (CoAP) . . . . . . 40 117 A.1. Notifications and Reordering . . . . . . . . . . . . . . 40 118 A.2. Transmission and Acknowledgements . . . . . . . . . . . . 41 119 A.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 41 120 A.4. Cancellation . . . . . . . . . . . . . . . . . . . . . . 41 121 Appendix B. CoAP over WebSocket Examples . . . . . . . . . . . . 42 122 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 45 123 C.1. Since draft-ietf-core-coap-tcp-tls-02 . . . . . . . . . . 45 124 C.2. Since draft-ietf-core-coap-tcp-tls-03 . . . . . . . . . . 45 125 C.3. Since draft-ietf-core-coap-tcp-tls-04 . . . . . . . . . . 45 126 C.4. Since draft-ietf-core-coap-tcp-tls-05 . . . . . . . . . . 45 127 C.5. Since draft-ietf-core-coap-tcp-tls-06 . . . . . . . . . . 46 128 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 46 129 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 46 130 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 46 132 1. Introduction 134 The Constrained Application Protocol (CoAP) [RFC7252] was designed 135 for Internet of Things (IoT) deployments, assuming that UDP [RFC0768] 136 or DTLS [RFC6347] over UDP can be used unimpeded. UDP is a good 137 choice for transferring small amounts of data across networks that 138 follow the IP architecture. 140 Some CoAP deployments need to integrate well with existing enterprise 141 infrastructures, where UDP-based protocols may not be well-received 142 or may even be blocked by firewalls. Middleboxes that are unaware of 143 CoAP usage for IoT can make the use of UDP brittle, resulting in lost 144 or malformed packets. 146 Emerging standards such as Lightweight Machine to Machine [LWM2M] 147 currently use CoAP over UDP as a transport and require support for 148 CoAP over TCP to address the issues above and to protect investments 149 in existing CoAP implementations and deployments. Although HTTP/2 150 could also potentially address these requirements, there would be 151 additional costs and delays introduced by such a transition. 152 Currently, there are also fewer HTTP/2 implementations available for 153 constrained devices in comparison to CoAP. 155 To address these requirements, this document defines how to transport 156 CoAP over TCP, CoAP over TLS, and CoAP over WebSockets. Figure 1 157 illustrates the layering: 159 +--------------------------------+ 160 | Application | 161 +--------------------------------+ 162 +--------------------------------+ 163 | Requests/Responses/Signaling | CoAP (RFC 7252) / This Document 164 |--------------------------------| 165 | Message Framing | This Document 166 +--------------------------------+ 167 | Reliable Transport | 168 +--------------------------------+ 170 Figure 1: Layering of CoAP over Reliable Transports 172 Where NATs are present, CoAP over TCP can help with their traversal. 173 NATs often calculate expiration timers based on the transport layer 174 protocol being used by application protocols. Many NATs maintain 175 TCP-based NAT bindings for longer periods based on the assumption 176 that a transport layer protocol, such as TCP, offers additional 177 information about the session life cycle. UDP, on the other hand, 178 does not provide such information to a NAT and timeouts tend to be 179 much shorter [HomeGateway]. 181 Some environments may also benefit from the ability of TCP to 182 exchange larger payloads, such as firmware images, without 183 application layer segmentation and to utilize the more sophisticated 184 congestion control capabilities provided by many TCP implementations. 185 Note that there is ongoing work to add more elaborate congestion 186 control to CoAP (see [I-D.ietf-core-cocoa]). 188 CoAP may be integrated into a Web environment where the front-end 189 uses CoAP over UDP from IoT devices to a cloud infrastructure and 190 then CoAP over TCP between the back-end services. A TCP-to-UDP 191 gateway can be used at the cloud boundary to communicate with the 192 UDP-based IoT device. 194 To allow IoT devices to better communicate in these demanding 195 environments, CoAP needs to support different transport protocols, 196 namely TCP [RFC0793], in some situations secured by TLS [RFC5246]. 198 In addition, some corporate networks only allow Internet access via a 199 HTTP proxy. In this case, the best transport for CoAP might be the 200 WebSocket protocol [RFC6455]. The WebSocket protocol provides two- 201 way communication between a WebSocket client and a WebSocket server 202 after upgrading an HTTP/1.1 [RFC7230] connection and may be available 203 in an environment that blocks CoAP over UDP. Another scenario for 204 CoAP over WebSockets is a CoAP application running inside a web 205 browser without access to connectivity other than HTTP and 206 WebSockets. 208 This document specifies how to access resources using CoAP requests 209 and responses over the TCP, TLS and WebSocket protocols. This allows 210 connectivity-limited applications to obtain end-to-end CoAP 211 connectivity either by communicating CoAP directly with a CoAP server 212 accessible over a TCP, TLS or WebSocket connection or via a CoAP 213 intermediary that proxies CoAP requests and responses between 214 different transports, such as between WebSockets and UDP. 216 Appendix A updates the "Observing Resources in the Constrained 217 Application Protocol" [RFC7641] specification for use with CoAP over 218 reliable transports. [RFC7641] is an extension to the CoAP protocol 219 that enables CoAP clients to "observe" a resource on a CoAP server. 220 (The CoAP client retrieves a representation of a resource and 221 registers to be notified by the CoAP server when the representation 222 is updated.) 224 2. Conventions and Terminology 226 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 227 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 228 "OPTIONAL" in this document are to be interpreted as described in 229 [RFC2119]. 231 This document assumes that readers are familiar with the terms and 232 concepts that are used in [RFC6455], [RFC7252], [RFC7641], and 233 [RFC7959]. 235 The term "reliable transport" is used only to refer to transport 236 protocols, such as TCP, which provide reliable and ordered delivery 237 of a byte-stream. 239 BERT Option: 240 A Block1 or Block2 option that includes an SZX value of 7. 242 BERT Block: 243 The payload of a CoAP message that is affected by a BERT Option in 244 descriptive usage (see Section 2.1 of [RFC7959]). 246 Connection Initiator: 247 The peer that opens a reliable byte stream connection, i.e., the 248 TCP active opener, TLS client, or WebSocket client. 250 Connection Acceptor: 251 The peer that accepts the reliable byte stream connection opened 252 by the other peer, i.e., the TCP passive opener, TLS server, or 253 WebSocket server. 255 For simplicity, a Payload Marker (0xFF) is shown in all examples for 256 message formats: 258 ... 259 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 260 |1 1 1 1 1 1 1 1| Payload (if any) ... 261 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 263 The Payload Marker indicates the start of the optional payload and is 264 absent for zero-length payloads (see Section 3 of [RFC7252]). 266 3. CoAP over TCP 268 The request/response interaction model of CoAP over TCP is the same 269 as CoAP over UDP. The primary differences are in the message layer. 270 The message layer of CoAP over UDP supports optional reliability by 271 defining four types of messages: Confirmable, Non-confirmable, 272 Acknowledgement, and Reset. In addition, messages include a Message 273 ID to relate Acknowledgments to Confirmable messages and to detect 274 duplicate messages. 276 3.1. Messaging Model 278 Conceptually, CoAP over TCP replaces most of the message layer of 279 CoAP over UDP with a framing mechanism on top of the byte-stream 280 provided by TCP/TLS, conveying the length information for each 281 message that on datagram transports is provided by the UDP/DTLS 282 datagram layer. 284 TCP ensures reliable message transmission, so the message layer of 285 CoAP over TCP is not required to support acknowledgements or to 286 detect duplicate messages. As a result, both the Type and Message ID 287 fields are no longer required and are removed from the CoAP over TCP 288 message format. 290 Figure 2 illustrates the difference between CoAP over UDP and CoAP 291 over reliable transport. The removed Type and Message ID fields are 292 indicated by dashes. 294 CoAP Client CoAP Server CoAP Client CoAP Server 295 | | | | 296 | CON [0xbc90] | | (-------) [------] | 297 | GET /temperature | | GET /temperature | 298 | (Token 0x71) | | (Token 0x71) | 299 +------------------->| +------------------->| 300 | | | | 301 | ACK [0xbc90] | | (-------) [------] | 302 | 2.05 Content | | 2.05 Content | 303 | (Token 0x71) | | (Token 0x71) | 304 | "22.5 C" | | "22.5 C" | 305 |<-------------------+ |<-------------------+ 306 | | | | 308 CoAP over UDP CoAP over reliable 309 transport 311 Figure 2: Comparison between CoAP over unreliable and reliable 312 transport 314 3.2. Message Format 316 The CoAP message format defined in [RFC7252], as shown in Figure 3, 317 relies on the datagram transport (UDP, or DTLS over UDP) for keeping 318 the individual messages separate and for providing length 319 information. 321 0 1 2 3 322 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 323 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 324 |Ver| T | TKL | Code | Message ID | 325 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 326 | Token (if any, TKL bytes) ... 327 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 328 | Options (if any) ... 329 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 330 |1 1 1 1 1 1 1 1| Payload (if any) ... 331 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 333 Figure 3: RFC 7252 defined CoAP Message Format 335 The CoAP over TCP message format is very similar to the format 336 specified for CoAP over UDP. The differences are as follows: 338 o Since the underlying TCP connection provides retransmissions and 339 deduplication, there is no need for the reliability mechanisms 340 provided by CoAP over UDP. The Type (T) and Message ID fields in 341 the CoAP message header are elided. 343 o The Version (Vers) field is elided as well. In contrast to the 344 message format of CoAP over UDP, the message format for CoAP over 345 TCP does not include a version number. CoAP is defined in 346 [RFC7252] with a version number of 1. At this time, there is no 347 known reason to support version numbers different from 1. If 348 version negotiation needs to be addressed in the future, then 349 Capabilities and Settings Messages (CSM see Section 5.3) have been 350 specifically designed to enable such a potential feature. 352 o In a stream oriented transport protocol such as TCP, a form of 353 message delimitation is needed. For this purpose, CoAP over TCP 354 introduces a length field with variable size. Figure 4 shows the 355 adjusted CoAP message format with a modified structure for the 356 fixed header (first 4 bytes of the CoAP over UDP header), which 357 includes the length information of variable size, shown here as an 358 8-bit length. 360 0 1 2 3 361 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 362 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 363 |Len=13 | TKL |Extended Length| Code | TKL bytes ... 364 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 365 | Options (if any) ... 366 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 367 |1 1 1 1 1 1 1 1| Payload (if any) ... 368 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 370 Figure 4: CoAP frame with 8-bit Extended Length field 372 Length (Len): 4-bit unsigned integer. A value between 0 and 12 373 directly indicates the length of the message in bytes starting 374 with the first bit of the Options field. Three values are 375 reserved for special constructs: 377 13: An 8-bit unsigned integer (Extended Length) follows the 378 initial byte and indicates the length of options/payload minus 379 13. 381 14: A 16-bit unsigned integer (Extended Length) in network byte 382 order follows the initial byte and indicates the length of 383 options/payload minus 269. 385 15: A 32-bit unsigned integer (Extended Length) in network byte 386 order follows the initial byte and indicates the length of 387 options/payload minus 65805. 389 The encoding of the Length field is modeled after the Option Length 390 field of the CoAP Options (see Section 3.1 of [RFC7252]). 392 The following figures show the message format for the 0-bit, 16-bit, 393 and the 32-bit variable length cases. 395 0 1 2 3 396 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 397 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 398 | Len | TKL | Code | Token (if any, TKL bytes) ... 399 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 400 | Options (if any) ... 401 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 402 |1 1 1 1 1 1 1 1| Payload (if any) ... 403 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 405 Figure 5: CoAP message format without an Extended Length field 407 For example: A CoAP message just containing a 2.03 code with the 408 token 7f and no options or payload would be encoded as shown in 409 Figure 6. 411 0 1 2 412 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 413 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 414 | 0x01 | 0x43 | 0x7f | 415 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 417 Len = 0 ------> 0x01 418 TKL = 1 ___/ 419 Code = 2.03 --> 0x43 420 Token = 0x7f 422 Figure 6: CoAP message with no options or payload 424 0 1 2 3 425 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 426 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 427 |Len=14 | TKL | Extended Length (16 bits) | Code | 428 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 429 | Token (if any, TKL bytes) ... 430 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 431 | Options (if any) ... 432 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 433 |1 1 1 1 1 1 1 1| Payload (if any) ... 434 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 436 Figure 7: CoAP message format with 16-bit Extended Length field 438 0 1 2 3 439 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 440 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 441 |Len=15 | TKL | Extended Length (32 bits) 442 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 443 | Code | Token (if any, TKL bytes) ... 444 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 445 | Options (if any) ... 446 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 447 |1 1 1 1 1 1 1 1| Payload (if any) ... 448 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 450 Figure 8: CoAP message format with 32-bit Extended Length field 452 The semantics of the other CoAP header fields are left unchanged. 454 3.3. Message Transmission 456 Once a connection is established, both endpoints MUST send a 457 Capabilities and Settings message (CSM see Section 5.3) as their 458 first message on the connection. This message establishes the 459 initial settings and capabilities for the endpoint, such as maximum 460 message size or support for block-wise transfers. The absence of 461 options in the CSM indicates that base values are assumed. 463 To avoid a deadlock, the Connection Initiator MUST NOT wait for the 464 Connection Acceptor to send its initial CSM message before sending 465 its own initial CSM message. Conversely, the Connection Acceptor MAY 466 wait for the Connection Initiator to send its initial CSM message 467 before sending its own initial CSM message. 469 To avoid unnecessary latency, a Connection Initiator MAY send 470 additional messages without waiting to receive the Connection 471 Acceptor's CSM; however, it is important to note that the Connection 472 Acceptor's CSM might advertise capabilities that impact how the 473 initiator is expected to communicate with the acceptor. For example, 474 the acceptor CSM could advertise a Max-Message-Size option (see 475 Section 5.3.1) that is smaller than the base value (1152). 477 Endpoints MUST treat a missing or invalid CSM as a connection error 478 and abort the connection (see Section 5.6). 480 CoAP requests and responses are exchanged asynchronously over the 481 TCP/TLS connection. A CoAP client can send multiple requests without 482 waiting for a response and the CoAP server can return responses in 483 any order. Responses MUST be returned over the same connection as 484 the originating request. Concurrent requests are differentiated by 485 their Token, which is scoped locally to the connection. 487 The connection is bi-directional, so requests can be sent both by the 488 entity that established the connection (Connection Initiator) and the 489 remote host (Connection Acceptor). If one side does not implement a 490 CoAP server, an appropriate error response such as 4.04 (Not Found) 491 or 5.01 (Not Implemented) MUST be returned for all CoAP requests from 492 the other side. 494 Retransmission and deduplication of messages is provided by the TCP 495 protocol. 497 3.4. Connection Health 499 Empty messages (Code 0.00) can always be sent and MUST be ignored by 500 the recipient. This provides a basic keep-alive function that can 501 refresh NAT bindings. 503 If a CoAP client does not receive any response for some time after 504 sending a CoAP request (or, similarly, when a client observes a 505 resource and it does not receive any notification for some time), it 506 can send a CoAP Ping Signaling message (see Section 5.4) to test the 507 connection and verify that the CoAP server is responsive. 509 4. CoAP over WebSockets 511 CoAP over WebSockets is intentionally similar to CoAP over TCP; 512 therefore, this section only specifies the differences between the 513 transports. 515 CoAP over WebSockets can be used in a number of configurations. The 516 most basic configuration is a CoAP client retrieving or updating a 517 CoAP resource located on a CoAP server that exposes a WebSocket 518 endpoint (see Figure 9). The CoAP client acts as the WebSocket 519 client, establishes a WebSocket connection, and sends a CoAP request, 520 to which the CoAP server returns a CoAP response. The WebSocket 521 connection can be used for any number of requests. 523 ___________ ___________ 524 | | | | 525 | _|___ requests ___|_ | 526 | CoAP / \ \ -------------> / / \ CoAP | 527 | Client \__/__/ <------------- \__\__/ Server | 528 | | responses | | 529 |___________| |___________| 530 WebSocket =============> WebSocket 531 Client Connection Server 533 Figure 9: CoAP Client (WebSocket client) accesses CoAP Server 534 (WebSocket server) 536 The challenge with this configuration is how to identify a resource 537 in the namespace of the CoAP server. When the WebSocket protocol is 538 used by a dedicated client directly (i.e., not from a web page 539 through a web browser), the client can connect to any WebSocket 540 endpoint. Section 7.3 and Section 7.4 define new URI schemes that 541 enable the client to identify both a WebSocket endpoint and the path 542 and query of the CoAP resource within that endpoint. 544 Another possible configuration is to set up a CoAP forward proxy at 545 the WebSocket endpoint. Depending on what transports are available 546 to the proxy, it could forward the request to a CoAP server with a 547 CoAP UDP endpoint (Figure 10), an SMS endpoint (a.k.a. mobile phone), 548 or even another WebSocket endpoint. The CoAP client specifies the 549 resource to be updated or retrieved in the Proxy-Uri Option. 551 ___________ ___________ ___________ 552 | | | | | | 553 | _|___ ___|_ _|___ ___|_ | 554 | CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP | 555 | Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server | 556 | | | | | | 557 |___________| |___________| |___________| 558 WebSocket ===> WebSocket UDP UDP 559 Client Server Client Server 561 Figure 10: CoAP Client (WebSocket client) accesses CoAP Server (UDP 562 server) via a CoAP proxy (WebSocket server/UDP client) 564 A third possible configuration is a CoAP server running inside a web 565 browser (Figure 11). The web browser initially connects to a 566 WebSocket endpoint and is then reachable through the WebSocket 567 server. When no connection exists, the CoAP server is unreachable. 569 Because the WebSocket server is the only way to reach the CoAP 570 server, the CoAP proxy should be a reverse-proxy. 572 ___________ ___________ ___________ 573 | | | | | | 574 | _|___ ___|_ _|___ ___|_ | 575 | CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP | 576 | Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server | 577 | | | | | | 578 |___________| |___________| |___________| 579 UDP UDP WebSocket <=== WebSocket 580 Client Server Server Client 582 Figure 11: CoAP Client (UDP client) accesses CoAP Server (WebSocket 583 client) via a CoAP proxy (UDP server/WebSocket server) 585 Further configurations are possible, including those where a 586 WebSocket connection is established through an HTTP proxy. 588 4.1. Opening Handshake 590 Before CoAP requests and responses are exchanged, a WebSocket 591 connection is established as defined in Section 4 of [RFC6455]. 592 Figure 12 shows an example. 594 The WebSocket client MUST include the subprotocol name "coap" in the 595 list of protocols, which indicates support for the protocol defined 596 in this document. Any later, incompatible versions of CoAP or CoAP 597 over WebSockets will use a different subprotocol name. 599 The WebSocket client includes the hostname of the WebSocket server in 600 the Host header field of its handshake as per [RFC6455]. The Host 601 header field also indicates the default value of the Uri-Host Option 602 in requests from the WebSocket client to the WebSocket server. 604 GET /.well-known/coap HTTP/1.1 605 Host: example.org 606 Upgrade: websocket 607 Connection: Upgrade 608 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 609 Sec-WebSocket-Protocol: coap 610 Sec-WebSocket-Version: 13 612 HTTP/1.1 101 Switching Protocols 613 Upgrade: websocket 614 Connection: Upgrade 615 Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 616 Sec-WebSocket-Protocol: coap 618 Figure 12: Example of an Opening Handshake 620 4.2. Message Format 622 Once a WebSocket connection is established, CoAP requests and 623 responses can be exchanged as WebSocket messages. Since CoAP uses a 624 binary message format, the messages are transmitted in binary data 625 frames as specified in Sections 5 and 6 of [RFC6455]. 627 The message format shown in Figure 13 is the same as the CoAP over 628 TCP message format (see Section 3.2) with one change. The Length 629 (Len) field MUST be set to zero because the WebSockets frame contains 630 the length. 632 0 1 2 3 633 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 634 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 635 | Len=0 | TKL | Code | Token (TKL bytes) ... 636 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 637 | Options (if any) ... 638 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 639 |1 1 1 1 1 1 1 1| Payload (if any) ... 640 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 642 Figure 13: CoAP Message Format over WebSockets 644 As with CoAP over TCP, the message format for CoAP over WebSockets 645 eliminates the Version field defined in CoAP over UDP. If CoAP 646 version negotiation is required in the future, CoAP over WebSockets 647 can address the requirement by the definition of a new subprotocol 648 identifier that is negotiated during the opening handshake. 650 Requests and response messages can be fragmented as specified in 651 Section 5.4 of [RFC6455], though typically they are sent unfragmented 652 as they tend to be small and fully buffered before transmission. The 653 WebSocket protocol does not provide means for multiplexing. If it is 654 not desirable for a large message to monopolize the connection, 655 requests and responses can be transferred in a block-wise fashion as 656 defined in [RFC7959]. 658 4.3. Message Transmission 660 As with CoAP over TCP, both endpoints MUST send a Capabilities and 661 Settings message (CSM see Section 5.3) as their first message on the 662 WebSocket connection. 664 CoAP requests and responses are exchanged asynchronously over the 665 WebSocket connection. A CoAP client can send multiple requests 666 without waiting for a response and the CoAP server can return 667 responses in any order. Responses MUST be returned over the same 668 connection as the originating request. Concurrent requests are 669 differentiated by their Token, which is scoped locally to the 670 connection. 672 The connection is bi-directional, so requests can be sent both by the 673 entity that established the connection and the remote host. 675 As with CoAP over TCP, retransmission and deduplication of messages 676 is provided by the WebSocket protocol. CoAP over WebSockets 677 therefore does not make a distinction between Confirmable or Non- 678 Confirmable messages, and does not provide Acknowledgement or Reset 679 messages. 681 4.4. Connection Health 683 As with CoAP over TCP, a CoAP client can test the health of the CoAP 684 over WebSocket connection by sending a CoAP Ping Signaling message 685 (Section 5.4). WebSocket Ping and unsolicited Pong frames 686 (Section 5.5 of [RFC6455]) SHOULD NOT be used to ensure that 687 redundant maintenance traffic is not transmitted. 689 5. Signaling 691 Signaling messages are introduced to allow peers to: 693 o Learn related characteristics, such as maximum message size for 694 the connection 696 o Shut down the connection in an orderly fashion 698 o Provide diagnostic information when terminating a connection in 699 response to a serious error condition 701 Signaling is a third basic kind of message in CoAP, after requests 702 and responses. Signaling messages share a common structure with the 703 existing CoAP messages. There is a code, a token, options, and an 704 optional payload. 706 (See Section 3 of [RFC7252] for the overall structure of the message 707 format, option format, and option value format.) 709 5.1. Signaling Codes 711 A code in the 7.00-7.31 range indicates a Signaling message. Values 712 in this range are assigned by the "CoAP Signaling Codes" sub-registry 713 (see Section 10.1). 715 For each message, there is a sender and a peer receiving the message. 717 Payloads in Signaling messages are diagnostic payloads as defined in 718 Section 5.5.2 of [RFC7252]), unless otherwise defined by a Signaling 719 message option. 721 5.2. Signaling Option Numbers 723 Option numbers for Signaling messages are specific to the message 724 code. They do not share the number space with CoAP options for 725 request/response messages or with Signaling messages using other 726 codes. 728 Option numbers are assigned by the "CoAP Signaling Option Numbers" 729 sub-registry (see Section 10.2). 731 Signaling options are elective or critical as defined in 732 Section 5.4.1 of [RFC7252]. If a Signaling option is critical and 733 not understood by the receiver, it MUST abort the connection (see 734 Section 5.6). If the option is understood but cannot be processed, 735 the option documents the behavior. 737 5.3. Capabilities and Settings Messages (CSM) 739 Capabilities and Settings messages (CSM) are used for two purposes: 741 o Each capability option advertises one capability of the sender to 742 the recipient. 744 o Each setting option indicates a setting that will be applied by 745 the sender. 747 One CSM MUST be sent by both endpoints at the start of the 748 connection. Further CSM MAY be sent at any other time by either 749 endpoint over the lifetime of the connection. 751 Both capability and setting options are cumulative. A CSM does not 752 invalidate a previously sent capability indication or setting even if 753 it is not repeated. A capability message without any option is a no- 754 operation (and can be used as such). An option that is sent might 755 override a previous value for the same option. The option defines 756 how to handle this case if needed. 758 Base values are listed below for CSM Options. These are the values 759 for the capability and setting before any Capabilities and Settings 760 messages send a modified value. 762 These are not default values for the option, as defined in 763 Section 5.4.4 in [RFC7252]. A default value would mean that an empty 764 Capabilities and Settings message would result in the option being 765 set to its default value. 767 Capabilities and Settings messages are indicated by the 7.01 code 768 (CSM). 770 5.3.1. Max-Message-Size Capability Option 772 The sender can use the elective Max-Message-Size Option to indicate 773 the maximum message size in bytes that it can receive. 775 +---+---+---+---------+------------------+--------+--------+--------+ 776 | # | C | R | Applies | Name | Format | Length | Base | 777 | | | | to | | | | Value | 778 +---+---+---+---------+------------------+--------+--------+--------+ 779 | 2 | | | CSM | Max-Message-Size | uint | 0-4 | 1152 | 780 +---+---+---+---------+------------------+--------+--------+--------+ 782 C=Critical, R=Repeatable 784 As per Section 4.6 of [RFC7252], the base value (and the value used 785 when this option is not implemented) is 1152. 787 The active value of the Max-Message-Size Option is replaced each time 788 the option is sent with a modified value. Its starting value is its 789 base value. 791 5.3.2. Block-wise Transfer Capability Option 793 +---+---+---+---------+-----------------+--------+--------+---------+ 794 | # | C | R | Applies | Name | Format | Length | Base | 795 | | | | to | | | | Value | 796 +---+---+---+---------+-----------------+--------+--------+---------+ 797 | 4 | | | CSM | Block-wise | empty | 0 | (none) | 798 | | | | | Transfer | | | | 799 +---+---+---+---------+-----------------+--------+--------+---------+ 801 C=Critical, R=Repeatable 803 A sender can use the elective Block-wise Transfer Option to indicate 804 that it supports the block-wise transfer protocol [RFC7959]. 806 If the option is not given, the peer has no information about whether 807 block-wise transfers are supported by the sender or not. An 808 implementation that supports block-wise transfers SHOULD indicate the 809 Block-wise Transfer Option. If a Max-Message-Size Option is 810 indicated with a value that is greater than 1152 (in the same or a 811 different CSM message), the Block-wise Transfer Option also indicates 812 support for BERT (see Section 6). Subsequently, if the Max-Message- 813 Size Option is indicated with a value equal to or less than 1152, 814 BERT support is no longer indicated. 816 5.4. Ping and Pong Messages 818 In CoAP over reliable transports, Empty messages (Code 0.00) can 819 always be sent and MUST be ignored by the recipient. This provides a 820 basic keep-alive function. In contrast, Ping and Pong messages are a 821 bidirectional exchange. 823 Upon receipt of a Ping message, the receiver MUST return a Pong 824 message with an identical token in response. Unless there is an 825 option with delaying semantics such as the Custody Option, it SHOULD 826 respond as soon as practical. As with all Signaling messages, the 827 recipient of a Ping or Pong message MUST ignore elective options it 828 does not understand. 830 Ping and Pong messages are indicated by the 7.02 code (Ping) and the 831 7.03 code (Pong). 833 5.4.1. Custody Option 834 +---+---+---+----------+----------------+--------+--------+---------+ 835 | # | C | R | Applies | Name | Format | Length | Base | 836 | | | | to | | | | Value | 837 +---+---+---+----------+----------------+--------+--------+---------+ 838 | 2 | | | Ping, | Custody | empty | 0 | (none) | 839 | | | | Pong | | | | | 840 +---+---+---+----------+----------------+--------+--------+---------+ 842 C=Critical, R=Repeatable 844 When responding to a Ping message, the receiver can include an 845 elective Custody Option in the Pong message. This option indicates 846 that the application has processed all the request/response messages 847 received prior to the Ping message on the current connection. (Note 848 that there is no definition of specific application semantics for 849 "processed", but there is an expectation that the receiver of a Pong 850 Message with a Custody Option should be able to free buffers based on 851 this indication.) 853 A sender can also include an elective Custody Option in a Ping 854 message to explicitly request the inclusion of an elective Custody 855 Option in the corresponding Pong message. In that case, the receiver 856 SHOULD delay its Pong message until it finishes processing all the 857 request/response messages received prior to the Ping message on the 858 current connection. 860 5.5. Release Messages 862 A Release message indicates that the sender does not want to continue 863 maintaining the connection and opts for an orderly shutdown. The 864 details are in the options. A diagnostic payload (see Section 5.5.2 865 of [RFC7252]) MAY be included. A peer will normally respond to a 866 Release message by closing the TCP/TLS connection. Messages may be 867 in flight when the sender decides to send a Release message. The 868 general expectation is that these will still be processed. 870 Release messages are indicated by the 7.04 code (Release). 872 Release messages can indicate one or more reasons using elective 873 options. The following options are defined: 875 +---+---+---+---------+------------------+--------+--------+--------+ 876 | # | C | R | Applies | Name | Format | Length | Base | 877 | | | | to | | | | Value | 878 +---+---+---+---------+------------------+--------+--------+--------+ 879 | 2 | | x | Release | Alternative- | string | 1-255 | (none) | 880 | | | | | Address | | | | 881 +---+---+---+---------+------------------+--------+--------+--------+ 883 C=Critical, R=Repeatable 885 The elective Alternative-Address Option requests the peer to instead 886 open a connection of the same scheme as the present connection to the 887 alternative transport address given. Its value is in the form 888 "authority" as defined in Section 3.2 of [RFC3986]. 890 The Alternative-Address Option is a repeatable option as defined in 891 Section 5.4.5 of [RFC7252]. When multiple occurrences of the option 892 are included, the peer can choose any of the alternative transport 893 addresses. 895 +---+---+---+---------+-----------------+--------+--------+---------+ 896 | # | C | R | Applies | Name | Format | Length | Base | 897 | | | | to | | | | Value | 898 +---+---+---+---------+-----------------+--------+--------+---------+ 899 | 4 | | | Release | Hold-Off | uint | 0-3 | (none) | 900 +---+---+---+---------+-----------------+--------+--------+---------+ 902 C=Critical, R=Repeatable 904 The elective Hold-Off Option indicates that the server is requesting 905 that the peer not reconnect to it for the number of seconds given in 906 the value. 908 5.6. Abort Messages 910 An Abort message indicates that the sender is unable to continue 911 maintaining the connection and cannot even wait for an orderly 912 release. The sender shuts down the connection immediately after the 913 abort (and may or may not wait for a Release or Abort message or 914 connection shutdown in the inverse direction). A diagnostic payload 915 (see Section 5.5.2 of [RFC7252]) SHOULD be included in the Abort 916 message. Messages may be in flight when the sender decides to send 917 an Abort message. The general expectation is that these will NOT be 918 processed. 920 Abort messages are indicated by the 7.05 code (Abort). 922 Abort messages can indicate one or more reasons using elective 923 options. The following option is defined: 925 +---+---+---+---------+-----------------+--------+--------+---------+ 926 | # | C | R | Applies | Name | Format | Length | Base | 927 | | | | to | | | | Value | 928 +---+---+---+---------+-----------------+--------+--------+---------+ 929 | 2 | | | Abort | Bad-CSM-Option | uint | 0-2 | (none) | 930 +---+---+---+---------+-----------------+--------+--------+---------+ 932 C=Critical, R=Repeatable 934 The elective Bad-CSM-Option Option indicates that the sender is 935 unable to process the CSM option identified by its option number, 936 e.g. when it is critical and the option number is unknown by the 937 sender, or when there is parameter problem with the value of an 938 elective option. More detailed information SHOULD be included as a 939 diagnostic payload. 941 For CoAP over UDP, messages which contain syntax violations are 942 processed as message format errors. As described in Sections 4.2 and 943 4.3 of [RFC7252], such messages are rejected by sending a matching 944 Reset message and otherwise ignoring the message. 946 For CoAP over reliable transports, the recipient rejects such 947 messages by sending an Abort message and otherwise ignoring the 948 message. No specific option has been defined for the Abort message 949 in this case, as the details are best left to a diagnostic payload. 951 5.7. Signaling examples 953 An encoded example of a Ping message with a non-empty token is shown 954 in Figure 14. 956 0 1 2 957 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 958 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 959 | 0x01 | 0xe2 | 0x42 | 960 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 962 Len = 0 -------> 0x01 963 TKL = 1 ___/ 964 Code = 7.02 Ping --> 0xe2 965 Token = 0x42 967 Figure 14: Ping Message Example 969 An encoded example of the corresponding Pong message is shown in 970 Figure 15. 972 0 1 2 973 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 974 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 975 | 0x01 | 0xe3 | 0x42 | 976 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 978 Len = 0 -------> 0x01 979 TKL = 1 ___/ 980 Code = 7.03 Pong --> 0xe3 981 Token = 0x42 983 Figure 15: Pong Message Example 985 6. Block-wise Transfer and Reliable Transports 987 The message size restrictions defined in Section 4.6 of CoAP 988 [RFC7252] to avoid IP fragmentation are not necessary when CoAP is 989 used over a reliable transport. While this suggests that the Block- 990 wise transfer protocol [RFC7959] is also no longer needed, it remains 991 applicable for a number of cases: 993 o large messages, such as firmware downloads, may cause undesired 994 head-of-line blocking when a single TCP connection is used 996 o a UDP-to-TCP gateway may simply not have the context to convert a 997 message with a Block Option into the equivalent exchange without 998 any use of a Block Option (it would need to convert the entire 999 blockwise exchange from start to end into a single exchange) 1001 The 'Block-wise Extension for Reliable Transport (BERT)' extends the 1002 Block protocol to enable the use of larger messages over a reliable 1003 transport. 1005 The use of this new extension is signaled by sending Block1 or Block2 1006 Options with SZX == 7 (a "BERT option"). SZX == 7 is a reserved 1007 value in [RFC7959]. 1009 In control usage, a BERT option is interpreted in the same way as the 1010 equivalent Option with SZX == 6, except that it also indicates the 1011 capability to process BERT blocks. As with the basic Block protocol, 1012 the recipient of a CoAP request with a BERT option in control usage 1013 is allowed to respond with a different SZX value, e.g. to send a non- 1014 BERT block instead. 1016 In descriptive usage, a BERT Option is interpreted in the same way as 1017 the equivalent Option with SZX == 6, except that the payload is also 1018 allowed to contain a multiple of 1024 bytes (non-final BERT block) or 1019 more than 1024 bytes (final BERT block). 1021 The recipient of a non-final BERT block (M=1) conceptually partitions 1022 the payload into a sequence of 1024-byte blocks and acts exactly as 1023 if it had received this sequence in conjunction with block numbers 1024 starting at, and sequentially increasing from, the block number given 1025 in the Block Option. In other words, the entire BERT block is 1026 positioned at the byte position that results from multiplying the 1027 block number with 1024. The position of further blocks to be 1028 transferred is indicated by incrementing the block number by the 1029 number of elements in this sequence (i.e., the size of the payload 1030 divided by 1024 bytes). 1032 As with SZX == 6, the recipient of a final BERT block (M=0) simply 1033 appends the payload at the byte position that is indicated by the 1034 block number multiplied with 1024. 1036 The following examples illustrate BERT options. A value of SZX == 7 1037 is labeled as "BERT" or as "BERT(nnn)" to indicate a payload of size 1038 nnn. 1040 In all these examples, a Block Option is decomposed to indicate the 1041 kind of Block Option (1 or 2) followed by a colon, the block number 1042 (NUM), more bit (M), and block size (2**(SZX+4)) separated by 1043 slashes. E.g., a Block2 Option value of 33 would be shown as 1044 2:2/0/32), or a Block1 Option value of 59 would be shown as 1045 1:3/1/128. 1047 6.1. Example: GET with BERT Blocks 1049 Figure 16 shows a GET request with a response that is split into 1050 three BERT blocks. The first response contains 3072 bytes of 1051 payload; the second, 5120; and the third, 4711. Note how the block 1052 number increments to move the position inside the response body 1053 forward. 1055 CoAP Client CoAP Server 1056 | | 1057 | GET, /status ------> | 1058 | | 1059 | <------ 2.05 Content, 2:0/1/BERT(3072) | 1060 | | 1061 | GET, /status, 2:3/0/BERT ------> | 1062 | | 1063 | <------ 2.05 Content, 2:3/1/BERT(5120) | 1064 | | 1065 | GET, /status, 2:8/0/BERT ------> | 1066 | | 1067 | <------ 2.05 Content, 2:8/0/BERT(4711) | 1069 Figure 16: GET with BERT blocks 1071 6.2. Example: PUT with BERT Blocks 1073 Figure 17 demonstrates a PUT exchange with BERT blocks. 1075 CoAP Client CoAP Server 1076 | | 1077 | PUT, /options, 1:0/1/BERT(8192) ------> | 1078 | | 1079 | <------ 2.31 Continue, 1:0/1/BERT | 1080 | | 1081 | PUT, /options, 1:8/1/BERT(16384) ------> | 1082 | | 1083 | <------ 2.31 Continue, 1:8/1/BERT | 1084 | | 1085 | PUT, /options, 1:24/0/BERT(5683) ------> | 1086 | | 1087 | <------ 2.04 Changed, 1:24/0/BERT | 1088 | | 1090 Figure 17: PUT with BERT blocks 1092 7. CoAP over Reliable Transport URIs 1094 CoAP over UDP [RFC7252] defines the "coap" and "coaps" URI schemes. 1095 This document introduces four additional URI schemes for identifying 1096 CoAP resources and providing a means of locating the resource: 1098 o the "coap+tcp" URI scheme for CoAP over TCP 1100 o the "coaps+tcp" URI scheme for CoAP over TCP secured by TLS 1102 o the "coap+ws" URI scheme for CoAP over WebSockets 1103 o the "coaps+ws" URI scheme for CoAP over WebSockets secured by TLS 1105 Resources made available via these schemes have no shared identity 1106 even if their resource identifiers indicate the same authority (the 1107 same host listening to the same TCP port). They are hosted in 1108 distinct namespaces because each URI scheme implies a distinct origin 1109 server. 1111 The syntax for the URI schemes in this section are specified using 1112 Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of 1113 "host", "port", "path-abempty", and "query" are adopted from 1114 [RFC3986]. 1116 Section 8 (Multicast CoAP) in [RFC7252] is not applicable to these 1117 schemes. 1119 7.1. coap+tcp URI scheme 1121 The "coap+tcp" URI scheme identifies CoAP resources that are intended 1122 to be accessible using CoAP over TCP. 1124 coap+tcp-URI = 1125 "coap+tcp:" "//" host [ ":" port ] path-abempty [ "?" query ] 1127 The syntax defined in Section 6.1 of [RFC7252] applies to this URI 1128 scheme with the following changes: 1130 o The port subcomponent indicates the TCP port at which the CoAP 1131 server is located. (If it is empty or not given, then the default 1132 port 5683 is assumed, as with UDP.) 1134 Encoding considerations: The scheme encoding conforms to the 1135 encoding rules established for URIs in [RFC3986]. 1137 Interoperability considerations: None. 1139 Security considerations: See Section 11.1 of [RFC7252]. 1141 7.2. coaps+tcp URI scheme 1143 The "coaps+tcp" URI scheme identifies CoAP resources that are 1144 intended to be accessible using CoAP over TCP secured with TLS. 1146 coaps+tcp-URI = 1147 "coaps+tcp:" "//" host [ ":" port ] path-abempty [ "?" query ] 1149 The syntax defined in Section 6.2 of [RFC7252] applies to this URI 1150 scheme, with the following changes: 1152 o The port subcomponent indicates the TCP port at which the TLS 1153 server for the CoAP server is located. If it is empty or not 1154 given, then the default port 443 is assumed (this is different 1155 from the default port for "coaps", i.e., CoAP over DTLS over UDP). 1157 o If a TLS server does not support the Application-Layer Protocol 1158 Negotiation Extension (ALPN) [RFC7301] or wishes to accommodate 1159 TLS clients that do not support ALPN, it MAY offer a coaps+tcp 1160 endpoint on TCP port 5684. This endpoint MAY also be ALPN 1161 enabled. A TLS server MAY offer coaps+tcp endpoints on ports 1162 other than TCP port 5684, which MUST be ALPN enabled. 1164 o For TCP ports other than port 5684, the TLS client MUST use the 1165 ALPN extension to advertise the "coap" protocol identifier (see 1166 Section 10.7) in the list of protocols in its ClientHello. If the 1167 TCP server selects and returns the "coap" protocol identifier 1168 using the ALPN extension in its ServerHello, then the connection 1169 succeeds. If the TLS server either does not negotiate the ALPN 1170 extension or returns a no_application_protocol alert, the TLS 1171 client MUST close the connection. 1173 o For TCP port 5684, a TLS client MAY use the ALPN extension to 1174 advertise the "coap" protocol identifier in the list of protocols 1175 in its ClientHello. If the TLS server selects and returns the 1176 "coap" protocol identifier using the ALPN extension in its 1177 ServerHello, then the connection succeeds. If the TLS server 1178 returns a no_application_protocol alert, then the TLS client MUST 1179 close the connection. If the TLS server does not negotiate the 1180 ALPN extension, then coaps+tcp is implicitly selected. 1182 o For TCP port 5684, if the TLS client does not use the ALPN 1183 extension to negotiate the protocol, then coaps+tcp is implicitly 1184 selected. 1186 Encoding considerations: The scheme encoding conforms to the 1187 encoding rules established for URIs in [RFC3986]. 1189 Interoperability considerations: None. 1191 Security considerations: See Section 11.1 of [RFC7252]. 1193 7.3. coap+ws URI scheme 1195 The "coap+ws" URI scheme identifies CoAP resources that are intended 1196 to be accessible using CoAP over WebSockets. 1198 coap-ws-URI = 1199 "coap+ws:" "//" host [ ":" port ] path-abempty [ "?" query ] 1201 The port subcomponent is OPTIONAL. The default is port 80. 1203 The WebSocket endpoint is identified by a "ws" URI that is composed 1204 of the authority part of the "coap+ws" URI and the well-known path 1205 "/.well-known/coap" [RFC5785]. The path and query parts of a 1206 "coap+ws" URI identify a resource within the specified endpoint which 1207 can be operated on by the methods defined by CoAP: 1209 coap+ws://example.org/sensors/temperature?u=Cel 1210 \______ ______/\___________ ___________/ 1211 \/ \/ 1212 Uri-Path: "sensors" 1213 ws://example.org/.well-known/coap Uri-Path: "temperature" 1214 Uri-Query: "u=Cel" 1216 Figure 18: The "coap+ws" URI Scheme 1218 Encoding considerations: The scheme encoding conforms to the 1219 encoding rules established for URIs in [RFC3986]. 1221 Interoperability considerations: None. 1223 Security considerations: See Section 11.1 of [RFC7252]. 1225 7.4. coaps+ws URI scheme 1227 The "coaps+ws" URI scheme identifies CoAP resources that are intended 1228 to be accessible using CoAP over WebSockets secured by TLS. 1230 coaps-ws-URI = 1231 "coaps+ws:" "//" host [ ":" port ] path-abempty [ "?" query ] 1233 The port subcomponent is OPTIONAL. The default is port 443. 1235 The WebSocket endpoint is identified by a "wss" URI that is composed 1236 of the authority part of the "coaps+ws" URI and the well-known path 1237 "/.well-known/coap" [RFC5785]. The path and query parts of a 1238 "coaps+ws" URI identify a resource within the specified endpoint 1239 which can be operated on by the methods defined by CoAP. 1241 coaps+ws://example.org/sensors/temperature?u=Cel 1242 \______ ______/\___________ ___________/ 1243 \/ \/ 1244 Uri-Path: "sensors" 1245 wss://example.org/.well-known/coap Uri-Path: "temperature" 1246 Uri-Query: "u=Cel" 1248 Figure 19: The "coaps+ws" URI Scheme 1250 Encoding considerations: The scheme encoding conforms to the 1251 encoding rules established for URIs in [RFC3986]. 1253 Interoperability considerations: None. 1255 Security considerations: See Section 11.1 of [RFC7252]. 1257 7.5. Uri-Host and Uri-Port Options 1259 CoAP over reliable transports maintains the property from 1260 Section 5.10.1 of [RFC7252]: 1262 The default values for the Uri-Host and Uri-Port Options are 1263 sufficient for requests to most servers. 1265 Unless otherwise noted, the default value of the Uri-Host Option is 1266 the IP literal representing the destination IP address of the request 1267 message. The default value of the Uri-Port Option is the destination 1268 TCP port. 1270 For CoAP over TLS, these default values are the same unless Server 1271 Name Indication (SNI) [RFC6066] is negotiated. In this case, the 1272 default value of the Uri-Host Option in requests from the TLS client 1273 to the TLS server is the SNI host. 1275 For CoAP over WebSockets, the default value of the Uri-Host Option in 1276 requests from the WebSocket client to the WebSocket server is 1277 indicated by the Host header field from the WebSocket handshake. 1279 7.6. Decomposing URIs into Options 1281 The steps are the same as specified in Section 6.4 of [RFC7252] with 1282 minor changes. 1284 This step from [RFC7252]: 1286 3. If |url| does not have a component whose value, when 1287 converted to ASCII lowercase, is "coap" or "coaps", then fail 1288 this algorithm. 1290 is updated to: 1292 3. If |url| does not have a component whose value, when 1293 converted to ASCII lowercase, is "coap+tcp", "coaps+tcp", 1294 "coap+ws", or "coaps+ws", then fail this algorithm. 1296 This step from [RFC7252]: 1298 7. If |port| does not equal the request's destination UDP port, 1299 include a Uri-Port Option and let that option's value be |port|. 1301 is updated to: 1303 7. If |port| does not equal the request's destination TCP port, 1304 include a Uri-Port Option and let that option's value be |port|. 1306 7.7. Composing URIs from Options 1308 The steps are the same as specified in Section 6.5 of [RFC7252] with 1309 minor changes. 1311 This step from [RFC7252]: 1313 1. If the request is secured using DTLS, let |url| be the string 1314 "coaps://". Otherwise, let |url| be the string "coap://". 1316 is updated to: 1318 1. For CoAP over TCP, if the request is secured using TLS, let |url| 1319 be the string "coaps+tcp://". Otherwise, let |url| be the string 1320 "coap+tcp://". For CoAP over WebSockets, if the request is 1321 secured using TLS, let |url| be the string "coaps+ws://". 1322 Otherwise, let |url| be the string "coap+ws://". 1324 This step from [RFC7252]: 1326 4. If the request includes a Uri-Port Option, let |port| be that 1327 option's value. Otherwise, let |port| be the request's 1328 destination UDP port. 1330 is updated to: 1332 4. If the request includes a Uri-Port Option, let |port| be that 1333 option's value. Otherwise, let |port| be the request's 1334 destination TCP port. 1336 8. Securing CoAP 1338 Security Challenges for the Internet of Things [SecurityChallenges] 1339 recommends: 1341 ... it is essential that IoT protocol suites specify a mandatory 1342 to implement but optional to use security solution. This will 1343 ensure security is available in all implementations, but 1344 configurable to use when not necessary (e.g., in closed 1345 environment). ... even if those features stretch the capabilities 1346 of such devices. 1348 A security solution MUST be implemented to protect CoAP over reliable 1349 transports and MUST be enabled by default. This document defines the 1350 TLS binding, but alternative solutions at different layers in the 1351 protocol stack MAY be used to protect CoAP over reliable transports 1352 when appropriate. Note that there is ongoing work to support a data 1353 object-based security model for CoAP that is independent of transport 1354 (see [I-D.ietf-core-object-security]). 1356 8.1. TLS binding for CoAP over TCP 1358 The TLS usage guidance in [RFC7925] applies. 1360 During the provisioning phase, a CoAP device is provided with the 1361 security information that it needs, including keying materials, 1362 access control lists, and authorization servers. At the end of the 1363 provisioning phase, the device will be in one of four security modes: 1365 NoSec: TLS is disabled. 1367 PreSharedKey: TLS is enabled. The guidance in Section 4.2 of 1368 [RFC7925] applies. 1370 RawPublicKey: TLS is enabled. The guidance in Section 4.3 of 1371 [RFC7925] applies. 1373 Certificate: TLS is enabled. The guidance in Section 4.4 of 1374 [RFC7925] applies. 1376 The "NoSec" mode is mandatory-to-implement. The system simply sends 1377 the packets over normal TCP which is indicated by the "coap+tcp" 1378 scheme and the TCP CoAP default port. The system is secured only by 1379 keeping attackers from being able to send or receive packets from the 1380 network with the CoAP nodes. 1382 "PreSharedKey", "RawPublicKey", or "Certificate" is mandatory-to- 1383 implement for the TLS binding depending on the credential type used 1384 with the device. These security modes are achieved using TLS and are 1385 indicated by the "coaps+tcp" scheme and TLS-secured CoAP default 1386 port. 1388 8.2. TLS usage for CoAP over WebSockets 1390 A CoAP client requesting a resource identified by a "coaps+ws" URI 1391 negotiates a secure WebSocket connection to a WebSocket server 1392 endpoint with a "wss" URI. This is described in Section 7.4. 1394 The client MUST perform a TLS handshake after opening the connection 1395 to the server. The guidance in Section 4.1 of [RFC6455] applies. 1396 When a CoAP server exposes resources identified by a "coaps+ws" URI, 1397 the guidance in Section 4.4 of [RFC7925] applies towards mandatory- 1398 to-implement TLS functionality for certificates. For the server-side 1399 requirements in accepting incoming connections over a HTTPS (HTTP- 1400 over-TLS) port, the guidance in Section 4.2 of [RFC6455] applies. 1402 9. Security Considerations 1404 The security considerations of [RFC7252] apply. For CoAP over 1405 WebSockets and CoAP over TLS-secured WebSockets, the security 1406 considerations of [RFC6455] also apply. 1408 9.1. Signaling Messages 1410 The guidance given by an Alternative-Address Option cannot be 1411 followed blindly. In particular, a peer MUST NOT assume that a 1412 successful connection to the Alternative-Address inherits all the 1413 security properties of the current connection. 1415 10. IANA Considerations 1417 10.1. Signaling Codes 1419 IANA is requested to create a third sub-registry for values of the 1420 Code field in the CoAP header (Section 12.1 of [RFC7252]). The name 1421 of this sub-registry is "CoAP Signaling Codes". 1423 Each entry in the sub-registry must include the Signaling Code in the 1424 range 7.00-7.31, its name, and a reference to its documentation. 1426 Initial entries in this sub-registry are as follows: 1428 +------+---------+-----------+ 1429 | Code | Name | Reference | 1430 +------+---------+-----------+ 1431 | 7.01 | CSM | [RFCthis] | 1432 | | | | 1433 | 7.02 | Ping | [RFCthis] | 1434 | | | | 1435 | 7.03 | Pong | [RFCthis] | 1436 | | | | 1437 | 7.04 | Release | [RFCthis] | 1438 | | | | 1439 | 7.05 | Abort | [RFCthis] | 1440 +------+---------+-----------+ 1442 Table 1: CoAP Signal Codes 1444 All other Signaling Codes are Unassigned. 1446 The IANA policy for future additions to this sub-registry is "IETF 1447 Review or IESG Approval" as described in [RFC5226]. 1449 10.2. CoAP Signaling Option Numbers Registry 1451 IANA is requested to create a sub-registry for Options Numbers used 1452 in CoAP signaling options within the "CoRE Parameters" registry. The 1453 name of this sub-registry is "CoAP Signaling Option Numbers". 1455 Each entry in the sub-registry must include one or more of the codes 1456 in the Signaling Codes subregistry (Section 10.1), the option number, 1457 the name of the option, and a reference to the option's 1458 documentation. 1460 Initial entries in this sub-registry are as follows: 1462 +------------+--------+---------------------+-----------+ 1463 | Applies to | Number | Name | Reference | 1464 +------------+--------+---------------------+-----------+ 1465 | 7.01 | 2 | Max-Message-Size | [RFCthis] | 1466 | | | | | 1467 | 7.01 | 4 | Block-wise-Transfer | [RFCthis] | 1468 | | | | | 1469 | 7.02, 7.03 | 2 | Custody | [RFCthis] | 1470 | | | | | 1471 | 7.04 | 2 | Alternative-Address | [RFCthis] | 1472 | | | | | 1473 | 7.04 | 4 | Hold-Off | [RFCthis] | 1474 | | | | | 1475 | 7.05 | 2 | Bad-CSM-Option | [RFCthis] | 1476 +------------+--------+---------------------+-----------+ 1478 Table 2: CoAP Signal Option Codes 1480 The IANA policy for future additions to this sub-registry is based on 1481 number ranges for the option numbers, analogous to the policy defined 1482 in Section 12.2 of [RFC7252]. 1484 The documentation for a Signaling Option Number should specify the 1485 semantics of an option with that number, including the following 1486 properties: 1488 o Whether the option is critical or elective, as determined by the 1489 Option Number. 1491 o Whether the option is repeatable. 1493 o The format and length of the option's value. 1495 o The base value for the option, if any. 1497 10.3. Service Name and Port Number Registration 1499 IANA is requested to assign the port number 5683 and the service name 1500 "coap+tcp", in accordance with [RFC6335]. 1502 Service Name. 1503 coap+tcp 1505 Transport Protocol. 1506 tcp 1508 Assignee. 1509 IESG 1511 Contact. 1512 IETF Chair 1514 Description. 1515 Constrained Application Protocol (CoAP) 1517 Reference. 1518 [RFCthis] 1520 Port Number. 1521 5683 1523 10.4. Secure Service Name and Port Number Registration 1525 IANA is requested to assign the port number 5684 and the service name 1526 "coaps+tcp", in accordance with [RFC6335]. The port number is 1527 requested to address the exceptional case of TLS implementations that 1528 do not support the "Application-Layer Protocol Negotiation Extension" 1529 [RFC7301]. 1531 Service Name. 1532 coaps+tcp 1534 Transport Protocol. 1535 tcp 1537 Assignee. 1538 IESG 1540 Contact. 1541 IETF Chair 1543 Description. 1544 Constrained Application Protocol (CoAP) 1546 Reference. 1547 [RFC7301], [RFCthis] 1549 Port Number. 1550 5684 1552 10.5. URI Scheme Registration 1554 URI schemes are registered within the "Uniform Resource Identifier 1555 (URI) Schemes" registry maintained at 1556 http://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml . 1558 10.5.1. coap+tcp 1560 IANA is requested to register the Uniform Resource Identifier (URI) 1561 scheme "coap+tcp". This registration request complies with 1562 [RFC7595]. 1564 Scheme name: 1565 coap+tcp 1567 Status: 1568 Permanent 1570 Applications/protocols that use this scheme name: 1571 The scheme is used by CoAP endpoints to access CoAP resources 1572 using TCP. 1574 Contact: 1575 IETF chair 1577 Change controller: 1578 IESG 1580 Reference: 1581 Section 7.1 in [RFCthis] 1583 10.5.2. coaps+tcp 1585 IANA is requested to register the Uniform Resource Identifier (URI) 1586 scheme "coaps+tcp". This registration request complies with 1587 [RFC7595]. 1589 Scheme name: 1590 coaps+tcp 1592 Status: 1593 Permanent 1595 Applications/protocols that use this scheme name: 1596 The scheme is used by CoAP endpoints to access CoAP resources 1597 using TLS. 1599 Contact: 1600 IETF chair 1602 Change controller: 1603 IESG 1605 Reference: 1607 Section 7.2 in [RFCthis] 1609 10.5.3. coap+ws 1611 IANA is requested to register the Uniform Resource Identifier (URI) 1612 scheme "coap+ws". This registration request complies with [RFC7595]. 1614 Scheme name: 1615 coap+ws 1617 Status: 1618 Permanent 1620 Applications/protocols that use this scheme name: 1621 The scheme is used by CoAP endpoints to access CoAP resources 1622 using the WebSocket protocol. 1624 Contact: 1625 IETF chair 1627 Change controller: 1628 IESG 1630 Reference: 1631 Section 7.3 in [RFCthis] 1633 10.5.4. coaps+ws 1635 IANA is requested to register the Uniform Resource Identifier (URI) 1636 scheme "coaps+ws". This registration request complies with 1637 [RFC7595]. 1639 Scheme name: 1640 coaps+ws 1642 Status: 1643 Permanent 1645 Applications/protocols that use this scheme name: 1646 The scheme is used by CoAP endpoints to access CoAP resources 1647 using the WebSocket protocol secured with TLS. 1649 Contact: 1650 IETF chair 1652 Change controller: 1653 IESG 1655 References: 1656 Section 7.4 in [RFCthis] 1658 10.6. Well-Known URI Suffix Registration 1660 IANA is requested to register the 'coap' well-known URI in the "Well- 1661 Known URIs" registry. This registration request complies with 1662 [RFC5785]: 1664 URI Suffix. 1665 coap 1667 Change controller. 1668 IETF 1670 Specification document(s). 1671 [RFCthis] 1673 Related information. 1674 None. 1676 10.7. ALPN Protocol Identifier 1678 IANA is requested to assign the following value in the registry 1679 "Application Layer Protocol Negotiation (ALPN) Protocol IDs" created 1680 by [RFC7301]. The "coap" string identifies CoAP when used over TLS. 1682 Protocol. 1683 CoAP 1685 Identification Sequence. 1686 0x63 0x6f 0x61 0x70 ("coap") 1688 Reference. 1689 [RFCthis] 1691 10.8. WebSocket Subprotocol Registration 1693 IANA is requested to register the WebSocket CoAP subprotocol under 1694 the "WebSocket Subprotocol Name Registry": 1696 Subprotocol Identifier. 1697 coap 1699 Subprotocol Common Name. 1700 Constrained Application Protocol (CoAP) 1702 Subprotocol Definition. 1704 [RFCthis] 1706 11. References 1708 11.1. Normative References 1710 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 1711 RFC 793, DOI 10.17487/RFC0793, September 1981, 1712 . 1714 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1715 Requirement Levels", BCP 14, RFC 2119, 1716 DOI 10.17487/RFC2119, March 1997, 1717 . 1719 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1720 Resource Identifier (URI): Generic Syntax", STD 66, 1721 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1722 . 1724 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1725 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1726 DOI 10.17487/RFC5226, May 2008, 1727 . 1729 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1730 (TLS) Protocol Version 1.2", RFC 5246, 1731 DOI 10.17487/RFC5246, August 2008, 1732 . 1734 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1735 Uniform Resource Identifiers (URIs)", RFC 5785, 1736 DOI 10.17487/RFC5785, April 2010, 1737 . 1739 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 1740 Extensions: Extension Definitions", RFC 6066, 1741 DOI 10.17487/RFC6066, January 2011, 1742 . 1744 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 1745 RFC 6455, DOI 10.17487/RFC6455, December 2011, 1746 . 1748 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1749 Application Protocol (CoAP)", RFC 7252, 1750 DOI 10.17487/RFC7252, June 2014, 1751 . 1753 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 1754 "Transport Layer Security (TLS) Application-Layer Protocol 1755 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1756 July 2014, . 1758 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 1759 and Registration Procedures for URI Schemes", BCP 35, 1760 RFC 7595, DOI 10.17487/RFC7595, June 2015, 1761 . 1763 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1764 Application Protocol (CoAP)", RFC 7641, 1765 DOI 10.17487/RFC7641, September 2015, 1766 . 1768 [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer 1769 Security (TLS) / Datagram Transport Layer Security (DTLS) 1770 Profiles for the Internet of Things", RFC 7925, 1771 DOI 10.17487/RFC7925, July 2016, 1772 . 1774 11.2. Informative References 1776 [HomeGateway] 1777 Eggert, L., "An experimental study of home gateway 1778 characteristics", Proceedings of the 10th annual 1779 conference on Internet measurement , 2010. 1781 [I-D.ietf-core-cocoa] 1782 Bormann, C., Betzler, A., Gomez, C., and I. Demirkol, 1783 "CoAP Simple Congestion Control/Advanced", draft-ietf- 1784 core-cocoa-00 (work in progress), October 2016. 1786 [I-D.ietf-core-object-security] 1787 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1788 "Object Security of CoAP (OSCOAP)", draft-ietf-core- 1789 object-security-01 (work in progress), December 2016. 1791 [LWM2M] Open Mobile Alliance, "Lightweight Machine to Machine 1792 Technical Specification Version 1.0", February 2017, 1793 . 1797 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 1798 DOI 10.17487/RFC0768, August 1980, 1799 . 1801 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1802 Specifications: ABNF", STD 68, RFC 5234, 1803 DOI 10.17487/RFC5234, January 2008, 1804 . 1806 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 1807 Cheshire, "Internet Assigned Numbers Authority (IANA) 1808 Procedures for the Management of the Service Name and 1809 Transport Protocol Port Number Registry", BCP 165, 1810 RFC 6335, DOI 10.17487/RFC6335, August 2011, 1811 . 1813 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1814 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1815 January 2012, . 1817 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1818 Protocol (HTTP/1.1): Message Syntax and Routing", 1819 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1820 . 1822 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1823 the Constrained Application Protocol (CoAP)", RFC 7959, 1824 DOI 10.17487/RFC7959, August 2016, 1825 . 1827 [SecurityChallenges] 1828 Polk, T. and S. Turner, "Security Challenges for the 1829 Internet of Things", Interconnecting Smart Objects with 1830 the Internet / IAB Workshop , February 2011, 1831 . 1834 Appendix A. Updates to RFC 7641 Observing Resources in the Constrained 1835 Application Protocol (CoAP) 1837 In this appendix, "client" and "server" refer to the CoAP client and 1838 CoAP server. 1840 A.1. Notifications and Reordering 1842 When using the Observe Option with CoAP over UDP, notifications from 1843 the server set the option value to an increasing sequence number for 1844 reordering detection on the client since messages can arrive in a 1845 different order than they were sent. This sequence number is not 1846 required for CoAP over reliable transports since the TCP protocol 1847 ensures reliable and ordered delivery of messages. The value of the 1848 Observe Option in 2.xx notifications MAY be empty on transmission and 1849 MUST be ignored on reception. 1851 A.2. Transmission and Acknowledgements 1853 For CoAP over UDP, server notifications to the client can be 1854 confirmable or non-confirmable. A confirmable message requires the 1855 client to either respond with an acknowledgement message or a reset 1856 message. An acknowledgement message indicates that the client is 1857 alive and wishes to receive further notifications. A reset message 1858 indicates that the client does not recognize the token which causes 1859 the server to remove the associated entry from the list of observers. 1861 Since TCP eliminates the need for the message layer to support 1862 reliability, CoAP over reliable transports does not support 1863 confirmable or non-confirmable message types. All notifications are 1864 delivered reliably to the client with positive acknowledgement of 1865 receipt occurring at the TCP level. If the client does not recognize 1866 the token in a notification, it MAY immediately abort the connection 1867 (see Section 5.6). 1869 A.3. Freshness 1871 For CoAP over UDP, if a client does not receive a notification for 1872 some time, it MAY send a new GET request with the same token as the 1873 original request to re-register its interest in a resource and verify 1874 that the server is still responsive. For CoAP over reliable 1875 transports, it is more efficient to check the health of the 1876 connection (and all its active observations) by sending a CoAP Ping 1877 Signaling message (Section 5.4) rather than individual requests to 1878 confirm active observations. 1880 A.4. Cancellation 1882 For CoAP over UDP, a client that is no longer interested in receiving 1883 notifications can "forget" the observation and respond to the next 1884 notification from the server with a reset message to cancel the 1885 observation. 1887 For CoAP over reliable transports, a client MUST explicitly 1888 deregister by issuing a GET request that has the Token field set to 1889 the token of the observation to be cancelled and includes an Observe 1890 Option with the value set to 1 (deregister). 1892 If the client observes one or more resources over a reliable 1893 transport, then the CoAP server (or intermediary in the role of the 1894 CoAP server) MUST remove all entries associated with the client 1895 endpoint from the lists of observers when the connection is either 1896 closed or times out. 1898 Appendix B. CoAP over WebSocket Examples 1900 This section gives examples for the first two configurations 1901 discussed in Section 4. 1903 An example of the process followed by a CoAP client to retrieve the 1904 representation of a resource identified by a "coap+ws" URI might be 1905 as follows. Figure 20 below illustrates the WebSocket and CoAP 1906 messages exchanged in detail. 1908 1. The CoAP client obtains the URI , for example, from a resource representation 1910 that it retrieved previously. 1912 2. It establishes a WebSocket connection to the endpoint URI 1913 composed of the authority "example.org" and the well-known path 1914 "/.well-known/coap", . 1916 3. It sends a single-frame, masked, binary message containing a CoAP 1917 request. The request indicates the target resource with the Uri- 1918 Path ("sensors", "temperature") and Uri-Query ("u=Cel") options. 1920 4. It waits for the server to return a response. 1922 5. The CoAP client uses the connection for further requests, or the 1923 connection is closed. 1925 CoAP CoAP 1926 Client Server 1927 (WebSocket (WebSocket 1928 Client) Server) 1930 | | 1931 | | 1932 +=========>| GET /.well-known/coap HTTP/1.1 1933 | | Host: example.org 1934 | | Upgrade: websocket 1935 | | Connection: Upgrade 1936 | | Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 1937 | | Sec-WebSocket-Protocol: coap 1938 | | Sec-WebSocket-Version: 13 1939 | | 1940 |<=========+ HTTP/1.1 101 Switching Protocols 1941 | | Upgrade: websocket 1942 | | Connection: Upgrade 1943 | | Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 1944 | | Sec-WebSocket-Protocol: coap 1945 | | 1946 | | 1947 +--------->| Binary frame (opcode=%x2, FIN=1, MASK=1) 1948 | | +-------------------------+ 1949 | | | GET | 1950 | | | Token: 0x53 | 1951 | | | Uri-Path: "sensors" | 1952 | | | Uri-Path: "temperature" | 1953 | | | Uri-Query: "u=Cel" | 1954 | | +-------------------------+ 1955 | | 1956 |<---------+ Binary frame (opcode=%x2, FIN=1, MASK=0) 1957 | | +-------------------------+ 1958 | | | 2.05 Content | 1959 | | | Token: 0x53 | 1960 | | | Payload: "22.3 Cel" | 1961 | | +-------------------------+ 1962 : : 1963 : : 1964 | | 1965 +--------->| Close frame (opcode=%x8, FIN=1, MASK=1) 1966 | | 1967 |<---------+ Close frame (opcode=%x8, FIN=1, MASK=0) 1968 | | 1970 Figure 20: A CoAP client retrieves the representation of a resource 1971 identified by a "coap+ws" URI 1973 Figure 21 shows how a CoAP client uses a CoAP forward proxy with a 1974 WebSocket endpoint to retrieve the representation of the resource 1975 "coap://[2001:db8::1]/". The use of the forward proxy and the 1976 address of the WebSocket endpoint are determined by the client from 1977 local configuration rules. The request URI is specified in the 1978 Proxy-Uri Option. Since the request URI uses the "coap" URI scheme, 1979 the proxy fulfills the request by issuing a Confirmable GET request 1980 over UDP to the CoAP server and returning the response over the 1981 WebSocket connection to the client. 1983 CoAP CoAP CoAP 1984 Client Proxy Server 1985 (WebSocket (WebSocket (UDP 1986 Client) Server) Endpoint) 1988 | | | 1989 +--------->| | Binary frame (opcode=%x2, FIN=1, MASK=1) 1990 | | | +------------------------------------+ 1991 | | | | GET | 1992 | | | | Token: 0x7d | 1993 | | | | Proxy-Uri: "coap://[2001:db8::1]/" | 1994 | | | +------------------------------------+ 1995 | | | 1996 | +--------->| CoAP message (Ver=1, T=Con, MID=0x8f54) 1997 | | | +------------------------------------+ 1998 | | | | GET | 1999 | | | | Token: 0x0a15 | 2000 | | | +------------------------------------+ 2001 | | | 2002 | |<---------+ CoAP message (Ver=1, T=Ack, MID=0x8f54) 2003 | | | +------------------------------------+ 2004 | | | | 2.05 Content | 2005 | | | | Token: 0x0a15 | 2006 | | | | Payload: "ready" | 2007 | | | +------------------------------------+ 2008 | | | 2009 |<---------+ | Binary frame (opcode=%x2, FIN=1, MASK=0) 2010 | | | +------------------------------------+ 2011 | | | | 2.05 Content | 2012 | | | | Token: 0x7d | 2013 | | | | Payload: "ready" | 2014 | | | +------------------------------------+ 2015 | | | 2017 Figure 21: A CoAP client retrieves the representation of a resource 2018 identified by a "coap" URI via a WebSockets-enabled CoAP proxy 2020 Appendix C. Change Log 2022 The RFC Editor is requested to remove this section at publication. 2024 C.1. Since draft-ietf-core-coap-tcp-tls-02 2026 Merged draft-savolainen-core-coap-websockets-07 Merged draft-bormann- 2027 core-block-bert-01 Merged draft-bormann-core-coap-sig-02 2029 C.2. Since draft-ietf-core-coap-tcp-tls-03 2031 Editorial updates 2033 Added mandatory exchange of Capabilities and Settings messages after 2034 connecting 2036 Added support for coaps+tcp port 5684 and more details on 2037 Application-Layer Protocol Negotiation (ALPN) 2039 Added guidance on CoAP Signaling Ping-Pong versus WebSocket Ping-Pong 2041 Updated references and requirements for TLS security considerations 2043 C.3. Since draft-ietf-core-coap-tcp-tls-04 2045 Updated references 2047 Added Appendix: Updates to RFC7641 Observing Resources in the 2048 Constrained Application Protocol (CoAP) 2050 Updated Capability and Settings Message (CSM) exchange in the Opening 2051 Handshake to allow initiator to send messages before receiving 2052 acceptor CSM 2054 C.4. Since draft-ietf-core-coap-tcp-tls-05 2056 Addressed feedback from Working Group Last Call 2058 Added Securing CoAP section and informative reference to OSCOAP 2060 Removed the Server-Name and Bad-Server-Name Options 2062 Clarified the Capability and Settings Message (CSM) exchange 2064 Updated Pong response requirements 2066 Added Connection Initiator and Connection Acceptor terminology where 2067 appropriate 2068 Updated LWM2M 1.0 informative reference 2070 C.5. Since draft-ietf-core-coap-tcp-tls-06 2072 Addressed feedback from second Working Group Last Call 2074 Acknowledgements 2076 We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier 2077 Delaby, Esko Dijk, Christian Groves, Nadir Javed, Michael Koster, 2078 Matthias Kovatsch, Achim Kraus, David Navarro, Szymon Sasin, Goran 2079 Selander, Zach Shelby, Andrew Summers, Julien Vermillard, and Gengyu 2080 Wei for their feedback. 2082 Contributors 2084 Matthias Kovatsch 2085 Siemens AG 2086 Otto-Hahn-Ring 6 2087 Munich D-81739 2089 Phone: +49-173-5288856 2090 EMail: matthias.kovatsch@siemens.com 2092 Teemu Savolainen 2093 Nokia Technologies 2094 Hatanpaan valtatie 30 2095 Tampere FI-33100 2096 Finland 2098 Email: teemu.savolainen@nokia.com 2100 Valik Solorzano Barboza 2101 Zebra Technologies 2102 820 W. Jackson Blvd. Suite 700 2103 Chicago 60607 2104 United States of America 2106 Phone: +1-847-634-6700 2107 Email: vsolorzanobarboza@zebra.com 2109 Authors' Addresses 2110 Carsten Bormann 2111 Universitaet Bremen TZI 2112 Postfach 330440 2113 Bremen D-28359 2114 Germany 2116 Phone: +49-421-218-63921 2117 Email: cabo@tzi.org 2119 Simon Lemay 2120 Zebra Technologies 2121 820 W. Jackson Blvd. Suite 700 2122 Chicago 60607 2123 United States of America 2125 Phone: +1-847-634-6700 2126 Email: slemay@zebra.com 2128 Hannes Tschofenig 2129 ARM Ltd. 2130 110 Fulbourn Rd 2131 Cambridge CB1 9NJ 2132 Great Britain 2134 Email: Hannes.tschofenig@gmx.net 2135 URI: http://www.tschofenig.priv.at 2137 Klaus Hartke 2138 Universitaet Bremen TZI 2139 Postfach 330440 2140 Bremen D-28359 2141 Germany 2143 Phone: +49-421-218-63905 2144 Email: hartke@tzi.org 2146 Bilhanan Silverajan 2147 Tampere University of Technology 2148 Korkeakoulunkatu 10 2149 Tampere FI-33720 2150 Finland 2152 Email: bilhanan.silverajan@tut.fi 2153 Brian Raymor (editor) 2154 Microsoft 2155 One Microsoft Way 2156 Redmond 98052 2157 United States of America 2159 Email: brian.raymor@microsoft.com