idnits 2.17.1 draft-ietf-core-coap-tcp-tls-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. -- The draft header indicates that this document updates RFC6455, but the abstract doesn't seem to directly say this. It does mention RFC6455 though, so this could be OK. -- The draft header indicates that this document updates RFC7959, but the abstract doesn't seem to directly say this. It does mention RFC7959 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 21, 2017) is 2533 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 305, but not defined == Missing Reference: '------' is mentioned on line 305, but not defined == Missing Reference: 'RFCthis' is mentioned on line 1739, 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-01 == Outdated reference: A later version (-16) exists of draft-ietf-core-object-security-02 -- 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: 5 errors (**), 0 flaws (~~), 6 warnings (==), 5 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: 6455, 7641, 7959 (if approved) S. Lemay 5 Intended status: Standards Track Zebra Technologies 6 Expires: October 23, 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 April 21, 2017 16 CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets 17 draft-ietf-core-coap-tcp-tls-08 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 RFC 7641 for use with these 30 transports, RFC 7959 to enable the use of larger messages over a 31 reliable transport, and RFC 6455 to extend the well-known URI 32 mechanism (RFC 5785) to the ws and wss URI schemes. 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at http://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on October 23, 2017. 50 Copyright Notice 52 Copyright (c) 2017 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 68 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 5 69 3. CoAP over TCP . . . . . . . . . . . . . . . . . . . . . . . . 6 70 3.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 6 71 3.2. Message Format . . . . . . . . . . . . . . . . . . . . . 7 72 3.3. Message Transmission . . . . . . . . . . . . . . . . . . 11 73 3.4. Connection Health . . . . . . . . . . . . . . . . . . . . 12 74 4. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . 12 75 4.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 14 76 4.2. Message Format . . . . . . . . . . . . . . . . . . . . . 14 77 4.3. Message Transmission . . . . . . . . . . . . . . . . . . 15 78 4.4. Connection Health . . . . . . . . . . . . . . . . . . . . 16 79 5. Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . 16 80 5.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 16 81 5.2. Signaling Option Numbers . . . . . . . . . . . . . . . . 16 82 5.3. Capabilities and Settings Messages (CSM) . . . . . . . . 17 83 5.4. Ping and Pong Messages . . . . . . . . . . . . . . . . . 18 84 5.5. Release Messages . . . . . . . . . . . . . . . . . . . . 19 85 5.6. Abort Messages . . . . . . . . . . . . . . . . . . . . . 20 86 5.7. Signaling examples . . . . . . . . . . . . . . . . . . . 21 87 6. Block-wise Transfer and Reliable Transports . . . . . . . . . 22 88 6.1. Example: GET with BERT Blocks . . . . . . . . . . . . . . 23 89 6.2. Example: PUT with BERT Blocks . . . . . . . . . . . . . . 24 90 7. CoAP over Reliable Transport URIs . . . . . . . . . . . . . . 24 91 7.1. coap+tcp URI scheme . . . . . . . . . . . . . . . . . . . 25 92 7.2. coaps+tcp URI scheme . . . . . . . . . . . . . . . . . . 26 93 7.3. coap+ws URI scheme . . . . . . . . . . . . . . . . . . . 27 94 7.4. coaps+ws URI scheme . . . . . . . . . . . . . . . . . . . 27 95 7.5. Uri-Host and Uri-Port Options . . . . . . . . . . . . . . 28 96 7.6. Decomposing URIs into Options . . . . . . . . . . . . . . 29 97 7.7. Composing URIs from Options . . . . . . . . . . . . . . . 29 98 8. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 30 99 8.1. TLS binding for CoAP over TCP . . . . . . . . . . . . . . 30 100 8.2. TLS usage for CoAP over WebSockets . . . . . . . . . . . 31 101 9. Security Considerations . . . . . . . . . . . . . . . . . . . 31 102 9.1. Signaling Messages . . . . . . . . . . . . . . . . . . . 31 103 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 104 10.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . 32 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 10.9. CoAP Option Numbers Registry . . . . . . . . . . . . . . 38 113 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 114 11.1. Normative References . . . . . . . . . . . . . . . . . . 38 115 11.2. Informative References . . . . . . . . . . . . . . . . . 40 116 Appendix A. Updates to RFC 7641 Observing Resources in the 117 Constrained Application Protocol (CoAP) . . . . . . 41 118 A.1. Notifications and Reordering . . . . . . . . . . . . . . 41 119 A.2. Transmission and Acknowledgements . . . . . . . . . . . . 41 120 A.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 41 121 A.4. Cancellation . . . . . . . . . . . . . . . . . . . . . . 42 122 Appendix B. CoAP over WebSocket Examples . . . . . . . . . . . . 42 123 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 46 124 C.1. Since draft-ietf-core-coap-tcp-tls-02 . . . . . . . . . . 46 125 C.2. Since draft-ietf-core-coap-tcp-tls-03 . . . . . . . . . . 46 126 C.3. Since draft-ietf-core-coap-tcp-tls-04 . . . . . . . . . . 46 127 C.4. Since draft-ietf-core-coap-tcp-tls-05 . . . . . . . . . . 46 128 C.5. Since draft-ietf-core-coap-tcp-tls-06 . . . . . . . . . . 47 129 C.6. Since draft-ietf-core-coap-tcp-tls-07 . . . . . . . . . . 47 130 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 47 131 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 47 132 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 134 1. Introduction 136 The Constrained Application Protocol (CoAP) [RFC7252] was designed 137 for Internet of Things (IoT) deployments, assuming that UDP [RFC0768] 138 or Datagram Transport Layer Security (DTLS) [RFC6347] over UDP can be 139 used unimpeded. UDP is a good choice for transferring small amounts 140 of data across networks that follow the IP architecture. 142 Some CoAP deployments need to integrate well with existing enterprise 143 infrastructures, where UDP-based protocols may not be well-received 144 or may even be blocked by firewalls. Middleboxes that are unaware of 145 CoAP usage for IoT can make the use of UDP brittle, resulting in lost 146 or malformed packets. 148 Emerging standards such as Lightweight Machine to Machine [LWM2M] 149 currently use CoAP over UDP as a transport and require support for 150 CoAP over TCP to address the issues above and to protect investments 151 in existing CoAP implementations and deployments. Although HTTP/2 152 could also potentially address these requirements, there would be 153 additional costs and delays introduced by such a transition. 154 Currently, there are also fewer HTTP/2 implementations available for 155 constrained devices in comparison to CoAP. 157 To address these requirements, this document defines how to transport 158 CoAP over TCP, CoAP over TLS, and CoAP over WebSockets. Figure 1 159 illustrates the layering: 161 +--------------------------------+ 162 | Application | 163 +--------------------------------+ 164 +--------------------------------+ 165 | Requests/Responses/Signaling | CoAP (RFC 7252) / This Document 166 |--------------------------------| 167 | Message Framing | This Document 168 +--------------------------------+ 169 | Reliable Transport | 170 +--------------------------------+ 172 Figure 1: Layering of CoAP over Reliable Transports 174 Where NATs are present, CoAP over TCP can help with their traversal. 175 NATs often calculate expiration timers based on the transport layer 176 protocol being used by application protocols. Many NATs maintain 177 TCP-based NAT bindings for longer periods based on the assumption 178 that a transport layer protocol, such as TCP, offers additional 179 information about the session life cycle. UDP, on the other hand, 180 does not provide such information to a NAT and timeouts tend to be 181 much shorter [HomeGateway]. 183 Some environments may also benefit from the ability of TCP to 184 exchange larger payloads, such as firmware images, without 185 application layer segmentation and to utilize the more sophisticated 186 congestion control capabilities provided by many TCP implementations. 187 Note that there is ongoing work to add more elaborate congestion 188 control to CoAP (see [I-D.ietf-core-cocoa]). 190 CoAP may be integrated into a Web environment where the front-end 191 uses CoAP over UDP from IoT devices to a cloud infrastructure and 192 then CoAP over TCP between the back-end services. A TCP-to-UDP 193 gateway can be used at the cloud boundary to communicate with the 194 UDP-based IoT device. 196 To allow IoT devices to better communicate in these demanding 197 environments, CoAP needs to support different transport protocols, 198 namely TCP [RFC0793], in some situations secured by TLS [RFC5246]. 200 CoAP applications running inside a web browser without access to 201 connectivity other than HTTP and the WebSocket protocol [RFC6455] may 202 cross-proxy their CoAP requests via HTTP to a HTTP-to-CoAP cross- 203 proxy or transport them via the the WebSocket protocol, which 204 provides two-way communication between a WebSocket client and a 205 WebSocket server after upgrading an HTTP/1.1 [RFC7230] connection. 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 the "Observing Resources in the Constrained 216 Application Protocol" [RFC7641] specification for use with CoAP over 217 reliable transports. [RFC7641] is an extension to the CoAP protocol 218 that enables CoAP clients to "observe" a resource on a CoAP server. 219 (The CoAP client retrieves a representation of a resource and 220 registers to be notified by the CoAP server when the representation 221 is updated.) 223 2. Conventions and Terminology 225 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 226 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 227 "OPTIONAL" in this document are to be interpreted as described in 228 [RFC2119]. 230 This document assumes that readers are familiar with the terms and 231 concepts that are used in [RFC6455], [RFC7252], [RFC7641], and 232 [RFC7959]. 234 The term "reliable transport" is used only to refer to transport 235 protocols, such as TCP, which provide reliable and ordered delivery 236 of a byte-stream. 238 Block-wise Extension for Reliable Transport (BERT): 240 BERT extends [RFC7959] to enable the use of larger messages over a 241 reliable transport. 243 BERT Option: 244 A Block1 or Block2 option that includes an SZX value of 7. 246 BERT Block: 247 The payload of a CoAP message that is affected by a BERT Option in 248 descriptive usage (see Section 2.1 of [RFC7959]). 250 Connection Initiator: 251 The peer that opens a reliable byte stream connection, i.e., the 252 TCP active opener, TLS client, or WebSocket client. 254 Connection Acceptor: 255 The peer that accepts the reliable byte stream connection opened 256 by the other peer, i.e., the TCP passive opener, TLS server, or 257 WebSocket server. 259 For simplicity, a Payload Marker (0xFF) is shown in all examples for 260 message formats: 262 ... 263 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 264 |1 1 1 1 1 1 1 1| Payload (if any) ... 265 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 267 The Payload Marker indicates the start of the optional payload and is 268 absent for zero-length payloads (see Section 3 of [RFC7252]). 270 3. CoAP over TCP 272 The request/response interaction model of CoAP over TCP is the same 273 as CoAP over UDP. The primary differences are in the message layer. 274 The message layer of CoAP over UDP supports optional reliability by 275 defining four types of messages: Confirmable, Non-confirmable, 276 Acknowledgement, and Reset. In addition, messages include a Message 277 ID to relate Acknowledgments to Confirmable messages and to detect 278 duplicate messages. 280 3.1. Messaging Model 282 Conceptually, CoAP over TCP replaces most of the message layer of 283 CoAP over UDP with a framing mechanism on top of the byte-stream 284 provided by TCP/TLS, conveying the length information for each 285 message that on datagram transports is provided by the UDP/DTLS 286 datagram layer. 288 TCP ensures reliable message transmission, so the message layer of 289 CoAP over TCP is not required to support acknowledgements or to 290 detect duplicate messages. As a result, both the Type and Message ID 291 fields are no longer required and are removed from the CoAP over TCP 292 message format. 294 Figure 2 illustrates the difference between CoAP over UDP and CoAP 295 over reliable transport. The removed Type and Message ID fields are 296 indicated by dashes. 298 CoAP Client CoAP Server CoAP Client CoAP Server 299 | | | | 300 | CON [0xbc90] | | (-------) [------] | 301 | GET /temperature | | GET /temperature | 302 | (Token 0x71) | | (Token 0x71) | 303 +------------------->| +------------------->| 304 | | | | 305 | ACK [0xbc90] | | (-------) [------] | 306 | 2.05 Content | | 2.05 Content | 307 | (Token 0x71) | | (Token 0x71) | 308 | "22.5 C" | | "22.5 C" | 309 |<-------------------+ |<-------------------+ 310 | | | | 312 CoAP over UDP CoAP over reliable 313 transport 315 Figure 2: Comparison between CoAP over unreliable and reliable 316 transport 318 3.2. Message Format 320 The CoAP message format defined in [RFC7252], as shown in Figure 3, 321 relies on the datagram transport (UDP, or DTLS over UDP) for keeping 322 the individual messages separate and for providing length 323 information. 325 0 1 2 3 326 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 327 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 328 |Ver| T | TKL | Code | Message ID | 329 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 330 | Token (if any, TKL bytes) ... 331 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 332 | Options (if any) ... 333 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 334 |1 1 1 1 1 1 1 1| Payload (if any) ... 335 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 337 Figure 3: RFC 7252 defined CoAP Message Format 339 The CoAP over TCP message format is very similar to the format 340 specified for CoAP over UDP. The differences are as follows: 342 o Since the underlying TCP connection provides retransmissions and 343 deduplication, there is no need for the reliability mechanisms 344 provided by CoAP over UDP. The Type (T) and Message ID fields in 345 the CoAP message header are elided. 347 o The Version (Vers) field is elided as well. In contrast to the 348 message format of CoAP over UDP, the message format for CoAP over 349 TCP does not include a version number. CoAP is defined in 350 [RFC7252] with a version number of 1. At this time, there is no 351 known reason to support version numbers different from 1. If 352 version negotiation needs to be addressed in the future, then 353 Capabilities and Settings Messages (CSM see Section 5.3) have been 354 specifically designed to enable such a potential feature. 356 o In a stream oriented transport protocol such as TCP, a form of 357 message delimitation is needed. For this purpose, CoAP over TCP 358 introduces a length field with variable size. Figure 4 shows the 359 adjusted CoAP message format with a modified structure for the 360 fixed header (first 4 bytes of the CoAP over UDP header), which 361 includes the length information of variable size, shown here as an 362 8-bit length. 364 0 1 2 3 365 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 366 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 367 |Len=13 | TKL |Extended Length| Code | TKL bytes ... 368 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 369 | Options (if any) ... 370 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 371 |1 1 1 1 1 1 1 1| Payload (if any) ... 372 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 374 Figure 4: CoAP frame with 8-bit Extended Length field 376 Length (Len): 4-bit unsigned integer. A value between 0 and 12 377 directly indicates the length of the message in bytes starting 378 with the first bit of the Options field. Three values are 379 reserved for special constructs: 381 13: An 8-bit unsigned integer (Extended Length) follows the 382 initial byte and indicates the length of options/payload minus 383 13. 385 14: A 16-bit unsigned integer (Extended Length) in network byte 386 order follows the initial byte and indicates the length of 387 options/payload minus 269. 389 15: A 32-bit unsigned integer (Extended Length) in network byte 390 order follows the initial byte and indicates the length of 391 options/payload minus 65805. 393 The encoding of the Length field is modeled after the Option Length 394 field of the CoAP Options (see Section 3.1 of [RFC7252]). 396 The following figures show the message format for the 0-bit, 16-bit, 397 and the 32-bit variable length cases. 399 0 1 2 3 400 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 401 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 402 | Len | TKL | Code | Token (if any, TKL bytes) ... 403 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 404 | Options (if any) ... 405 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 406 |1 1 1 1 1 1 1 1| Payload (if any) ... 407 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 409 Figure 5: CoAP message format without an Extended Length field 411 For example: A CoAP message just containing a 2.03 code with the 412 token 7f and no options or payload would be encoded as shown in 413 Figure 6. 415 0 1 2 416 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 417 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 418 | 0x01 | 0x43 | 0x7f | 419 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 421 Len = 0 ------> 0x01 422 TKL = 1 ___/ 423 Code = 2.03 --> 0x43 424 Token = 0x7f 426 Figure 6: CoAP message with no options or payload 428 0 1 2 3 429 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 430 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 431 |Len=14 | TKL | Extended Length (16 bits) | Code | 432 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 433 | Token (if any, TKL bytes) ... 434 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 435 | Options (if any) ... 436 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 437 |1 1 1 1 1 1 1 1| Payload (if any) ... 438 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 440 Figure 7: CoAP message format with 16-bit Extended Length field 442 0 1 2 3 443 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 444 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 445 |Len=15 | TKL | Extended Length (32 bits) 446 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 447 | Code | Token (if any, TKL bytes) ... 448 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 449 | Options (if any) ... 450 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 451 |1 1 1 1 1 1 1 1| Payload (if any) ... 452 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 454 Figure 8: CoAP message format with 32-bit Extended Length field 456 The semantics of the other CoAP header fields are left unchanged. 458 3.3. Message Transmission 460 Once a connection is established, both endpoints MUST send a 461 Capabilities and Settings message (CSM see Section 5.3) as their 462 first message on the connection. This message establishes the 463 initial settings and capabilities for the endpoint, such as maximum 464 message size or support for block-wise transfers. The absence of 465 options in the CSM indicates that base values are assumed. 467 To avoid a deadlock, the Connection Initiator MUST NOT wait for the 468 Connection Acceptor to send its initial CSM message before sending 469 its own initial CSM message. Conversely, the Connection Acceptor MAY 470 wait for the Connection Initiator to send its initial CSM message 471 before sending its own initial CSM message. 473 To avoid unnecessary latency, a Connection Initiator MAY send 474 additional messages without waiting to receive the Connection 475 Acceptor's CSM; however, it is important to note that the Connection 476 Acceptor's CSM might advertise capabilities that impact how the 477 initiator is expected to communicate with the acceptor. For example, 478 the acceptor CSM could advertise a Max-Message-Size option (see 479 Section 5.3.1) that is smaller than the base value (1152). 481 Endpoints MUST treat a missing or invalid CSM as a connection error 482 and abort the connection (see Section 5.6). 484 CoAP requests and responses are exchanged asynchronously over the 485 TCP/TLS connection. A CoAP client can send multiple requests without 486 waiting for a response and the CoAP server can return responses in 487 any order. Responses MUST be returned over the same connection as 488 the originating request. Concurrent requests are differentiated by 489 their Token, which is scoped locally to the connection. 491 The connection is bi-directional, so requests can be sent both by the 492 entity that established the connection (Connection Initiator) and the 493 remote host (Connection Acceptor). If one side does not implement a 494 CoAP server, an error response MUST be returned for all CoAP requests 495 from the other side. The simplest approach is to always return 5.01 496 (Not Implemented). A more elaborate mock server could also return 497 4.xx responses such as 4.04 (Not Found) or 4.02 (Bad Option) where 498 appropriate. 500 Retransmission and deduplication of messages is provided by the TCP 501 protocol. 503 3.4. Connection Health 505 Empty messages (Code 0.00) can always be sent and MUST be ignored by 506 the recipient. This provides a basic keep-alive function that can 507 refresh NAT bindings. 509 If a CoAP client does not receive any response for some time after 510 sending a CoAP request (or, similarly, when a client observes a 511 resource and it does not receive any notification for some time), it 512 can send a CoAP Ping Signaling message (see Section 5.4) to test the 513 connection and verify that the CoAP server is responsive. 515 When the underlying TCP connection is closed or reset, the signaling 516 state and any observation state (see Appendix A.4) associated with 517 the reliable connection are removed. In flight messages may or may 518 not be lost. 520 4. CoAP over WebSockets 522 CoAP over WebSockets is intentionally similar to CoAP over TCP; 523 therefore, this section only specifies the differences between the 524 transports. 526 CoAP over WebSockets can be used in a number of configurations. The 527 most basic configuration is a CoAP client retrieving or updating a 528 CoAP resource located on a CoAP server that exposes a WebSocket 529 endpoint (see Figure 9). The CoAP client acts as the WebSocket 530 client, establishes a WebSocket connection, and sends a CoAP request, 531 to which the CoAP server returns a CoAP response. The WebSocket 532 connection can be used for any number of requests. 534 ___________ ___________ 535 | | | | 536 | _|___ requests ___|_ | 537 | CoAP / \ \ -------------> / / \ CoAP | 538 | Client \__/__/ <------------- \__\__/ Server | 539 | | responses | | 540 |___________| |___________| 541 WebSocket =============> WebSocket 542 Client Connection Server 544 Figure 9: CoAP Client (WebSocket client) accesses CoAP Server 545 (WebSocket server) 547 The challenge with this configuration is how to identify a resource 548 in the namespace of the CoAP server. When the WebSocket protocol is 549 used by a dedicated client directly (i.e., not from a web page 550 through a web browser), the client can connect to any WebSocket 551 endpoint. Section 7.3 and Section 7.4 define new URI schemes that 552 enable the client to identify both a WebSocket endpoint and the path 553 and query of the CoAP resource within that endpoint. 555 Another possible configuration is to set up a CoAP forward proxy at 556 the WebSocket endpoint. Depending on what transports are available 557 to the proxy, it could forward the request to a CoAP server with a 558 CoAP UDP endpoint (Figure 10), an SMS endpoint (a.k.a. mobile phone), 559 or even another WebSocket endpoint. The CoAP client specifies the 560 resource to be updated or retrieved in the Proxy-Uri Option. 562 ___________ ___________ ___________ 563 | | | | | | 564 | _|___ ___|_ _|___ ___|_ | 565 | CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP | 566 | Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server | 567 | | | | | | 568 |___________| |___________| |___________| 569 WebSocket ===> WebSocket UDP UDP 570 Client Server Client Server 572 Figure 10: CoAP Client (WebSocket client) accesses CoAP Server (UDP 573 server) via a CoAP proxy (WebSocket server/UDP client) 575 A third possible configuration is a CoAP server running inside a web 576 browser (Figure 11). The web browser initially connects to a 577 WebSocket endpoint and is then reachable through the WebSocket 578 server. When no connection exists, the CoAP server is unreachable. 579 Because the WebSocket server is the only way to reach the CoAP 580 server, the CoAP proxy should be a reverse-proxy. 582 ___________ ___________ ___________ 583 | | | | | | 584 | _|___ ___|_ _|___ ___|_ | 585 | CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP | 586 | Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server | 587 | | | | | | 588 |___________| |___________| |___________| 589 UDP UDP WebSocket <=== WebSocket 590 Client Server Server Client 592 Figure 11: CoAP Client (UDP client) accesses CoAP Server (WebSocket 593 client) via a CoAP proxy (UDP server/WebSocket server) 595 Further configurations are possible, including those where a 596 WebSocket connection is established through an HTTP proxy. 598 4.1. Opening Handshake 600 Before CoAP requests and responses are exchanged, a WebSocket 601 connection is established as defined in Section 4 of [RFC6455]. 602 Figure 12 shows an example. 604 The WebSocket client MUST include the subprotocol name "coap" in the 605 list of protocols, which indicates support for the protocol defined 606 in this document. Any later, incompatible versions of CoAP or CoAP 607 over WebSockets will use a different subprotocol name. 609 The WebSocket client includes the hostname of the WebSocket server in 610 the Host header field of its handshake as per [RFC6455]. The Host 611 header field also indicates the default value of the Uri-Host Option 612 in requests from the WebSocket client to the WebSocket server. 614 GET /.well-known/coap HTTP/1.1 615 Host: example.org 616 Upgrade: websocket 617 Connection: Upgrade 618 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 619 Sec-WebSocket-Protocol: coap 620 Sec-WebSocket-Version: 13 622 HTTP/1.1 101 Switching Protocols 623 Upgrade: websocket 624 Connection: Upgrade 625 Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 626 Sec-WebSocket-Protocol: coap 628 Figure 12: Example of an Opening Handshake 630 4.2. Message Format 632 Once a WebSocket connection is established, CoAP requests and 633 responses can be exchanged as WebSocket messages. Since CoAP uses a 634 binary message format, the messages are transmitted in binary data 635 frames as specified in Sections 5 and 6 of [RFC6455]. 637 The message format shown in Figure 13 is the same as the CoAP over 638 TCP message format (see Section 3.2) with one change. The Length 639 (Len) field MUST be set to zero because the WebSockets frame contains 640 the length. 642 0 1 2 3 643 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 644 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 645 | Len=0 | TKL | Code | Token (TKL bytes) ... 646 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 647 | Options (if any) ... 648 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 649 |1 1 1 1 1 1 1 1| Payload (if any) ... 650 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 652 Figure 13: CoAP Message Format over WebSockets 654 As with CoAP over TCP, the message format for CoAP over WebSockets 655 eliminates the Version field defined in CoAP over UDP. If CoAP 656 version negotiation is required in the future, CoAP over WebSockets 657 can address the requirement by the definition of a new subprotocol 658 identifier that is negotiated during the opening handshake. 660 Requests and response messages can be fragmented as specified in 661 Section 5.4 of [RFC6455], though typically they are sent unfragmented 662 as they tend to be small and fully buffered before transmission. The 663 WebSocket protocol does not provide means for multiplexing. If it is 664 not desirable for a large message to monopolize the connection, 665 requests and responses can be transferred in a block-wise fashion as 666 defined in [RFC7959]. 668 4.3. Message Transmission 670 As with CoAP over TCP, both endpoints MUST send a Capabilities and 671 Settings message (CSM see Section 5.3) as their first message on the 672 WebSocket connection. 674 CoAP requests and responses are exchanged asynchronously over the 675 WebSocket connection. A CoAP client can send multiple requests 676 without waiting for a response and the CoAP server can return 677 responses in any order. Responses MUST be returned over the same 678 connection as the originating request. Concurrent requests are 679 differentiated by their Token, which is scoped locally to the 680 connection. 682 The connection is bi-directional, so requests can be sent both by the 683 entity that established the connection and the remote host. 685 As with CoAP over TCP, retransmission and deduplication of messages 686 is provided by the WebSocket protocol. CoAP over WebSockets 687 therefore does not make a distinction between Confirmable or Non- 688 Confirmable messages, and does not provide Acknowledgement or Reset 689 messages. 691 4.4. Connection Health 693 As with CoAP over TCP, a CoAP client can test the health of the CoAP 694 over WebSocket connection by sending a CoAP Ping Signaling message 695 (Section 5.4). WebSocket Ping and unsolicited Pong frames 696 (Section 5.5 of [RFC6455]) SHOULD NOT be used to ensure that 697 redundant maintenance traffic is not transmitted. 699 5. Signaling 701 Signaling messages are introduced to allow peers to: 703 o Learn related characteristics, such as maximum message size for 704 the connection 706 o Shut down the connection in an orderly fashion 708 o Provide diagnostic information when terminating a connection in 709 response to a serious error condition 711 Signaling is a third basic kind of message in CoAP, after requests 712 and responses. Signaling messages share a common structure with the 713 existing CoAP messages. There is a code, a token, options, and an 714 optional payload. 716 (See Section 3 of [RFC7252] for the overall structure of the message 717 format, option format, and option value format.) 719 5.1. Signaling Codes 721 A code in the 7.00-7.31 range indicates a Signaling message. Values 722 in this range are assigned by the "CoAP Signaling Codes" sub-registry 723 (see Section 10.1). 725 For each message, there is a sender and a peer receiving the message. 727 Payloads in Signaling messages are diagnostic payloads as defined in 728 Section 5.5.2 of [RFC7252]), unless otherwise defined by a Signaling 729 message option. 731 5.2. Signaling Option Numbers 733 Option numbers for Signaling messages are specific to the message 734 code. They do not share the number space with CoAP options for 735 request/response messages or with Signaling messages using other 736 codes. 738 Option numbers are assigned by the "CoAP Signaling Option Numbers" 739 sub-registry (see Section 10.2). 741 Signaling options are elective or critical as defined in 742 Section 5.4.1 of [RFC7252]. If a Signaling option is critical and 743 not understood by the receiver, it MUST abort the connection (see 744 Section 5.6). If the option is understood but cannot be processed, 745 the option documents the behavior. 747 5.3. Capabilities and Settings Messages (CSM) 749 Capabilities and Settings messages (CSM) are used for two purposes: 751 o Each capability option advertises one capability of the sender to 752 the recipient. 754 o Each setting option indicates a setting that will be applied by 755 the sender. 757 One CSM MUST be sent by both endpoints at the start of the 758 connection. Further CSM MAY be sent at any other time by either 759 endpoint over the lifetime of the connection. 761 Both capability and setting options are cumulative. A CSM does not 762 invalidate a previously sent capability indication or setting even if 763 it is not repeated. A capability message without any option is a no- 764 operation (and can be used as such). An option that is sent might 765 override a previous value for the same option. The option defines 766 how to handle this case if needed. 768 Base values are listed below for CSM Options. These are the values 769 for the capability and setting before any Capabilities and Settings 770 messages send a modified value. 772 These are not default values for the option, as defined in 773 Section 5.4.4 in [RFC7252]. A default value would mean that an empty 774 Capabilities and Settings message would result in the option being 775 set to its default value. 777 Capabilities and Settings messages are indicated by the 7.01 code 778 (CSM). 780 5.3.1. Max-Message-Size Capability Option 782 The sender can use the elective Max-Message-Size Option to indicate 783 the maximum message size in bytes that it can receive. 785 +---+---+---+---------+------------------+--------+--------+--------+ 786 | # | C | R | Applies | Name | Format | Length | Base | 787 | | | | to | | | | Value | 788 +---+---+---+---------+------------------+--------+--------+--------+ 789 | 2 | | | CSM | Max-Message-Size | uint | 0-4 | 1152 | 790 +---+---+---+---------+------------------+--------+--------+--------+ 792 C=Critical, R=Repeatable 794 As per Section 4.6 of [RFC7252], the base value (and the value used 795 when this option is not implemented) is 1152. 797 The active value of the Max-Message-Size Option is replaced each time 798 the option is sent with a modified value. Its starting value is its 799 base value. 801 5.3.2. Block-wise Transfer Capability Option 803 +---+---+---+---------+-----------------+--------+--------+---------+ 804 | # | C | R | Applies | Name | Format | Length | Base | 805 | | | | to | | | | Value | 806 +---+---+---+---------+-----------------+--------+--------+---------+ 807 | 4 | | | CSM | Block-wise | empty | 0 | (none) | 808 | | | | | Transfer | | | | 809 +---+---+---+---------+-----------------+--------+--------+---------+ 811 C=Critical, R=Repeatable 813 A sender can use the elective Block-wise Transfer Option to indicate 814 that it supports the block-wise transfer protocol [RFC7959]. 816 If the option is not given, the peer has no information about whether 817 block-wise transfers are supported by the sender or not. An 818 implementation that supports block-wise transfers SHOULD indicate the 819 Block-wise Transfer Option. If a Max-Message-Size Option is 820 indicated with a value that is greater than 1152 (in the same or a 821 different CSM message), the Block-wise Transfer Option also indicates 822 support for BERT (see Section 6). Subsequently, if the Max-Message- 823 Size Option is indicated with a value equal to or less than 1152, 824 BERT support is no longer indicated. 826 5.4. Ping and Pong Messages 828 In CoAP over reliable transports, Empty messages (Code 0.00) can 829 always be sent and MUST be ignored by the recipient. This provides a 830 basic keep-alive function. In contrast, Ping and Pong messages are a 831 bidirectional exchange. 833 Upon receipt of a Ping message, the receiver MUST return a Pong 834 message with an identical token in response. Unless there is an 835 option with delaying semantics such as the Custody Option, it SHOULD 836 respond as soon as practical. As with all Signaling messages, the 837 recipient of a Ping or Pong message MUST ignore elective options it 838 does not understand. 840 Ping and Pong messages are indicated by the 7.02 code (Ping) and the 841 7.03 code (Pong). 843 5.4.1. Custody Option 845 +---+---+---+----------+----------------+--------+--------+---------+ 846 | # | C | R | Applies | Name | Format | Length | Base | 847 | | | | to | | | | Value | 848 +---+---+---+----------+----------------+--------+--------+---------+ 849 | 2 | | | Ping, | Custody | empty | 0 | (none) | 850 | | | | Pong | | | | | 851 +---+---+---+----------+----------------+--------+--------+---------+ 853 C=Critical, R=Repeatable 855 When responding to a Ping message, the receiver can include an 856 elective Custody Option in the Pong message. This option indicates 857 that the application has processed all the request/response messages 858 received prior to the Ping message on the current connection. (Note 859 that there is no definition of specific application semantics for 860 "processed", but there is an expectation that the receiver of a Pong 861 Message with a Custody Option should be able to free buffers based on 862 this indication.) 864 A sender can also include an elective Custody Option in a Ping 865 message to explicitly request the inclusion of an elective Custody 866 Option in the corresponding Pong message. In that case, the receiver 867 SHOULD delay its Pong message until it finishes processing all the 868 request/response messages received prior to the Ping message on the 869 current connection. 871 5.5. Release Messages 873 A Release message indicates that the sender does not want to continue 874 maintaining the connection and opts for an orderly shutdown. The 875 details are in the options. A diagnostic payload (see Section 5.5.2 876 of [RFC7252]) MAY be included. A peer will normally respond to a 877 Release message by closing the TCP/TLS connection. Messages may be 878 in flight when the sender decides to send a Release message. The 879 general expectation is that these will still be processed. 881 Release messages are indicated by the 7.04 code (Release). 883 Release messages can indicate one or more reasons using elective 884 options. The following options are defined: 886 +---+---+---+---------+------------------+--------+--------+--------+ 887 | # | C | R | Applies | Name | Format | Length | Base | 888 | | | | to | | | | Value | 889 +---+---+---+---------+------------------+--------+--------+--------+ 890 | 2 | | x | Release | Alternative- | string | 1-255 | (none) | 891 | | | | | Address | | | | 892 +---+---+---+---------+------------------+--------+--------+--------+ 894 C=Critical, R=Repeatable 896 The elective Alternative-Address Option requests the peer to instead 897 open a connection of the same scheme as the present connection to the 898 alternative transport address given. Its value is in the form 899 "authority" as defined in Section 3.2 of [RFC3986]. 901 The Alternative-Address Option is a repeatable option as defined in 902 Section 5.4.5 of [RFC7252]. When multiple occurrences of the option 903 are included, the peer can choose any of the alternative transport 904 addresses. 906 +---+---+---+---------+-----------------+--------+--------+---------+ 907 | # | C | R | Applies | Name | Format | Length | Base | 908 | | | | to | | | | Value | 909 +---+---+---+---------+-----------------+--------+--------+---------+ 910 | 4 | | | Release | Hold-Off | uint | 0-3 | (none) | 911 +---+---+---+---------+-----------------+--------+--------+---------+ 913 C=Critical, R=Repeatable 915 The elective Hold-Off Option indicates that the server is requesting 916 that the peer not reconnect to it for the number of seconds given in 917 the value. 919 5.6. Abort Messages 921 An Abort message indicates that the sender is unable to continue 922 maintaining the connection and cannot even wait for an orderly 923 release. The sender shuts down the connection immediately after the 924 abort (and may or may not wait for a Release or Abort message or 925 connection shutdown in the inverse direction). A diagnostic payload 926 (see Section 5.5.2 of [RFC7252]) SHOULD be included in the Abort 927 message. Messages may be in flight when the sender decides to send 928 an Abort message. The general expectation is that these will NOT be 929 processed. 931 Abort messages are indicated by the 7.05 code (Abort). 933 Abort messages can indicate one or more reasons using elective 934 options. The following option is defined: 936 +---+---+---+---------+-----------------+--------+--------+---------+ 937 | # | C | R | Applies | Name | Format | Length | Base | 938 | | | | to | | | | Value | 939 +---+---+---+---------+-----------------+--------+--------+---------+ 940 | 2 | | | Abort | Bad-CSM-Option | uint | 0-2 | (none) | 941 +---+---+---+---------+-----------------+--------+--------+---------+ 943 C=Critical, R=Repeatable 945 The elective Bad-CSM-Option Option indicates that the sender is 946 unable to process the CSM option identified by its option number, 947 e.g. when it is critical and the option number is unknown by the 948 sender, or when there is parameter problem with the value of an 949 elective option. More detailed information SHOULD be included as a 950 diagnostic payload. 952 For CoAP over UDP, messages which contain syntax violations are 953 processed as message format errors. As described in Sections 4.2 and 954 4.3 of [RFC7252], such messages are rejected by sending a matching 955 Reset message and otherwise ignoring the message. 957 For CoAP over reliable transports, the recipient rejects such 958 messages by sending an Abort message and otherwise ignoring the 959 message. No specific option has been defined for the Abort message 960 in this case, as the details are best left to a diagnostic payload. 962 5.7. Signaling examples 964 An encoded example of a Ping message with a non-empty token is shown 965 in Figure 14. 967 0 1 2 968 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 969 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 970 | 0x01 | 0xe2 | 0x42 | 971 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 973 Len = 0 -------> 0x01 974 TKL = 1 ___/ 975 Code = 7.02 Ping --> 0xe2 976 Token = 0x42 978 Figure 14: Ping Message Example 980 An encoded example of the corresponding Pong message is shown in 981 Figure 15. 983 0 1 2 984 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 985 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 986 | 0x01 | 0xe3 | 0x42 | 987 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 989 Len = 0 -------> 0x01 990 TKL = 1 ___/ 991 Code = 7.03 Pong --> 0xe3 992 Token = 0x42 994 Figure 15: Pong Message Example 996 6. Block-wise Transfer and Reliable Transports 998 The message size restrictions defined in Section 4.6 of CoAP 999 [RFC7252] to avoid IP fragmentation are not necessary when CoAP is 1000 used over a reliable transport. While this suggests that the Block- 1001 wise transfer protocol [RFC7959] is also no longer needed, it remains 1002 applicable for a number of cases: 1004 o large messages, such as firmware downloads, may cause undesired 1005 head-of-line blocking when a single TCP connection is used 1007 o a UDP-to-TCP gateway may simply not have the context to convert a 1008 message with a Block Option into the equivalent exchange without 1009 any use of a Block Option (it would need to convert the entire 1010 blockwise exchange from start to end into a single exchange) 1012 The 'Block-wise Extension for Reliable Transport (BERT)' extends the 1013 Block protocol to enable the use of larger messages over a reliable 1014 transport. 1016 The use of this new extension is signaled by sending Block1 or Block2 1017 Options with SZX == 7 (a "BERT option"). SZX == 7 is a reserved 1018 value in [RFC7959]. 1020 In control usage, a BERT option is interpreted in the same way as the 1021 equivalent Option with SZX == 6, except that it also indicates the 1022 capability to process BERT blocks. As with the basic Block protocol, 1023 the recipient of a CoAP request with a BERT option in control usage 1024 is allowed to respond with a different SZX value, e.g. to send a non- 1025 BERT block instead. 1027 In descriptive usage, a BERT Option is interpreted in the same way as 1028 the equivalent Option with SZX == 6, except that the payload is also 1029 allowed to contain a multiple of 1024 bytes (non-final BERT block) or 1030 more than 1024 bytes (final BERT block). 1032 The recipient of a non-final BERT block (M=1) conceptually partitions 1033 the payload into a sequence of 1024-byte blocks and acts exactly as 1034 if it had received this sequence in conjunction with block numbers 1035 starting at, and sequentially increasing from, the block number given 1036 in the Block Option. In other words, the entire BERT block is 1037 positioned at the byte position that results from multiplying the 1038 block number with 1024. The position of further blocks to be 1039 transferred is indicated by incrementing the block number by the 1040 number of elements in this sequence (i.e., the size of the payload 1041 divided by 1024 bytes). 1043 As with SZX == 6, the recipient of a final BERT block (M=0) simply 1044 appends the payload at the byte position that is indicated by the 1045 block number multiplied with 1024. 1047 The following examples illustrate BERT options. A value of SZX == 7 1048 is labeled as "BERT" or as "BERT(nnn)" to indicate a payload of size 1049 nnn. 1051 In all these examples, a Block Option is decomposed to indicate the 1052 kind of Block Option (1 or 2) followed by a colon, the block number 1053 (NUM), more bit (M), and block size (2**(SZX+4)) separated by 1054 slashes. E.g., a Block2 Option value of 33 would be shown as 1055 2:2/0/32), or a Block1 Option value of 59 would be shown as 1056 1:3/1/128. 1058 6.1. Example: GET with BERT Blocks 1060 Figure 16 shows a GET request with a response that is split into 1061 three BERT blocks. The first response contains 3072 bytes of 1062 payload; the second, 5120; and the third, 4711. Note how the block 1063 number increments to move the position inside the response body 1064 forward. 1066 CoAP Client CoAP Server 1067 | | 1068 | GET, /status ------> | 1069 | | 1070 | <------ 2.05 Content, 2:0/1/BERT(3072) | 1071 | | 1072 | GET, /status, 2:3/0/BERT ------> | 1073 | | 1074 | <------ 2.05 Content, 2:3/1/BERT(5120) | 1075 | | 1076 | GET, /status, 2:8/0/BERT ------> | 1077 | | 1078 | <------ 2.05 Content, 2:8/0/BERT(4711) | 1080 Figure 16: GET with BERT blocks 1082 6.2. Example: PUT with BERT Blocks 1084 Figure 17 demonstrates a PUT exchange with BERT blocks. 1086 CoAP Client CoAP Server 1087 | | 1088 | PUT, /options, 1:0/1/BERT(8192) ------> | 1089 | | 1090 | <------ 2.31 Continue, 1:0/1/BERT | 1091 | | 1092 | PUT, /options, 1:8/1/BERT(16384) ------> | 1093 | | 1094 | <------ 2.31 Continue, 1:8/1/BERT | 1095 | | 1096 | PUT, /options, 1:24/0/BERT(5683) ------> | 1097 | | 1098 | <------ 2.04 Changed, 1:24/0/BERT | 1099 | | 1101 Figure 17: PUT with BERT blocks 1103 7. CoAP over Reliable Transport URIs 1105 CoAP over UDP [RFC7252] defines the "coap" and "coaps" URI schemes. 1106 This document introduces four additional URI schemes for identifying 1107 CoAP resources and providing a means of locating the resource: 1109 o the "coap+tcp" URI scheme for CoAP over TCP 1110 o the "coaps+tcp" URI scheme for CoAP over TCP secured by TLS 1112 o the "coap+ws" URI scheme for CoAP over WebSockets 1114 o the "coaps+ws" URI scheme for CoAP over WebSockets secured by TLS 1116 Resources made available via these schemes have no shared identity 1117 even if their resource identifiers indicate the same authority (the 1118 same host listening to the same TCP port). They are hosted in 1119 distinct namespaces because each URI scheme implies a distinct origin 1120 server. 1122 The syntax for the URI schemes in this section are specified using 1123 Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of 1124 "host", "port", "path-abempty", "query", and "fragment" are adopted 1125 from [RFC3986]. 1127 Section 8 (Multicast CoAP) in [RFC7252] is not applicable to these 1128 schemes. 1130 As with the "coap" and "coaps" schemes defined in [RFC7252], all URI 1131 schemes defined in this section also support the path prefix "/.well- 1132 known/" defined by [RFC5785] for "well-known locations" in the 1133 namespace of a host. This enables discovery as per Section 7 of 1134 [RFC7252]. 1136 7.1. coap+tcp URI scheme 1138 The "coap+tcp" URI scheme identifies CoAP resources that are intended 1139 to be accessible using CoAP over TCP. 1141 coap-tcp-URI = "coap+tcp:" "//" host [ ":" port ] 1142 path-abempty [ "?" query ] [ "#" fragment ] 1144 The syntax defined in Section 6.1 of [RFC7252] applies to this URI 1145 scheme with the following changes: 1147 o The port subcomponent indicates the TCP port at which the CoAP 1148 server is located. (If it is empty or not given, then the default 1149 port 5683 is assumed, as with UDP.) 1151 Encoding considerations: The scheme encoding conforms to the 1152 encoding rules established for URIs in [RFC3986]. 1154 Interoperability considerations: None. 1156 Security considerations: See Section 11.1 of [RFC7252]. 1158 7.2. coaps+tcp URI scheme 1160 The "coaps+tcp" URI scheme identifies CoAP resources that are 1161 intended to be accessible using CoAP over TCP secured with TLS. 1163 coaps-tcp-URI = "coaps+tcp:" "//" host [ ":" port ] 1164 path-abempty [ "?" query ] [ "#" fragment ] 1166 The syntax defined in Section 6.2 of [RFC7252] applies to this URI 1167 scheme, with the following changes: 1169 o The port subcomponent indicates the TCP port at which the TLS 1170 server for the CoAP server is located. If it is empty or not 1171 given, then the default port 443 is assumed (this is different 1172 from the default port for "coaps", i.e., CoAP over DTLS over UDP). 1174 o If a TLS server does not support the Application-Layer Protocol 1175 Negotiation Extension (ALPN) [RFC7301] or wishes to accommodate 1176 TLS clients that do not support ALPN, it MAY offer a coaps+tcp 1177 endpoint on TCP port 5684. This endpoint MAY also be ALPN 1178 enabled. A TLS server MAY offer coaps+tcp endpoints on ports 1179 other than TCP port 5684, which MUST be ALPN enabled. 1181 o For TCP ports other than port 5684, the TLS client MUST use the 1182 ALPN extension to advertise the "coap" protocol identifier (see 1183 Section 10.7) in the list of protocols in its ClientHello. If the 1184 TCP server selects and returns the "coap" protocol identifier 1185 using the ALPN extension in its ServerHello, then the connection 1186 succeeds. If the TLS server either does not negotiate the ALPN 1187 extension or returns a no_application_protocol alert, the TLS 1188 client MUST close the connection. 1190 o For TCP port 5684, a TLS client MAY use the ALPN extension to 1191 advertise the "coap" protocol identifier in the list of protocols 1192 in its ClientHello. If the TLS server selects and returns the 1193 "coap" protocol identifier using the ALPN extension in its 1194 ServerHello, then the connection succeeds. If the TLS server 1195 returns a no_application_protocol alert, then the TLS client MUST 1196 close the connection. If the TLS server does not negotiate the 1197 ALPN extension, then coaps+tcp is implicitly selected. 1199 o For TCP port 5684, if the TLS client does not use the ALPN 1200 extension to negotiate the protocol, then coaps+tcp is implicitly 1201 selected. 1203 Encoding considerations: The scheme encoding conforms to the 1204 encoding rules established for URIs in [RFC3986]. 1206 Interoperability considerations: None. 1208 Security considerations: See Section 11.1 of [RFC7252]. 1210 7.3. coap+ws URI scheme 1212 The "coap+ws" URI scheme identifies CoAP resources that are intended 1213 to be accessible using CoAP over WebSockets. 1215 coap-ws-URI = "coap+ws:" "//" host [ ":" port ] 1216 path-abempty [ "?" query ] [ "#" fragment ] 1218 The port subcomponent is OPTIONAL. The default is port 80. 1220 The WebSocket endpoint is identified by a "ws" URI that is composed 1221 of the authority part of the "coap+ws" URI and the well-known path 1222 "/.well-known/coap" [RFC5785]. The present specification formally 1223 updates [RFC6455], extending the well-known URI mechanism defined in 1224 [RFC5785] to also cover the "ws" URI scheme defined in that document. 1225 The path and query parts of a "coap+ws" URI identify a resource 1226 within the specified endpoint which can be operated on by the methods 1227 defined by CoAP: 1229 coap+ws://example.org/sensors/temperature?u=Cel 1230 \______ ______/\___________ ___________/ 1231 \/ \/ 1232 Uri-Path: "sensors" 1233 ws://example.org/.well-known/coap Uri-Path: "temperature" 1234 Uri-Query: "u=Cel" 1236 Figure 18: The "coap+ws" URI Scheme 1238 Encoding considerations: The scheme encoding conforms to the 1239 encoding rules established for URIs in [RFC3986]. 1241 Interoperability considerations: None. 1243 Security considerations: See Section 11.1 of [RFC7252]. 1245 7.4. coaps+ws URI scheme 1247 The "coaps+ws" URI scheme identifies CoAP resources that are intended 1248 to be accessible using CoAP over WebSockets secured by TLS. 1250 coaps-ws-URI = "coaps+ws:" "//" host [ ":" port ] 1251 path-abempty [ "?" query ] [ "#" fragment ] 1253 The port subcomponent is OPTIONAL. The default is port 443. 1255 The WebSocket endpoint is identified by a "wss" URI that is composed 1256 of the authority part of the "coaps+ws" URI and the well-known path 1257 "/.well-known/coap" [RFC5785]. The present specification formally 1258 updates [RFC6455], extending the well-known URI mechanism defined in 1259 [RFC5785] to also cover the "wss" URI scheme defined in that 1260 document. The path and query parts of a "coaps+ws" URI identify a 1261 resource within the specified endpoint which can be operated on by 1262 the methods defined by CoAP. 1264 coaps+ws://example.org/sensors/temperature?u=Cel 1265 \______ ______/\___________ ___________/ 1266 \/ \/ 1267 Uri-Path: "sensors" 1268 wss://example.org/.well-known/coap Uri-Path: "temperature" 1269 Uri-Query: "u=Cel" 1271 Figure 19: The "coaps+ws" URI Scheme 1273 Encoding considerations: The scheme encoding conforms to the 1274 encoding rules established for URIs in [RFC3986]. 1276 Interoperability considerations: None. 1278 Security considerations: See Section 11.1 of [RFC7252]. 1280 7.5. Uri-Host and Uri-Port Options 1282 CoAP over reliable transports maintains the property from 1283 Section 5.10.1 of [RFC7252]: 1285 The default values for the Uri-Host and Uri-Port Options are 1286 sufficient for requests to most servers. 1288 Unless otherwise noted, the default value of the Uri-Host Option is 1289 the IP literal representing the destination IP address of the request 1290 message. The default value of the Uri-Port Option is the destination 1291 TCP port. 1293 For CoAP over TLS, these default values are the same unless Server 1294 Name Indication (SNI) [RFC6066] is negotiated. In this case, the 1295 default value of the Uri-Host Option in requests from the TLS client 1296 to the TLS server is the SNI host. 1298 For CoAP over WebSockets, the default value of the Uri-Host Option in 1299 requests from the WebSocket client to the WebSocket server is 1300 indicated by the Host header field from the WebSocket handshake. 1302 7.6. Decomposing URIs into Options 1304 The steps are the same as specified in Section 6.4 of [RFC7252] with 1305 minor changes. 1307 This step from [RFC7252]: 1309 3. If |url| does not have a component whose value, when 1310 converted to ASCII lowercase, is "coap" or "coaps", then fail 1311 this algorithm. 1313 is updated to: 1315 3. If |url| does not have a component whose value, when 1316 converted to ASCII lowercase, is "coap+tcp", "coaps+tcp", 1317 "coap+ws", or "coaps+ws", then fail this algorithm. 1319 This step from [RFC7252]: 1321 7. If |port| does not equal the request's destination UDP port, 1322 include a Uri-Port Option and let that option's value be |port|. 1324 is updated to: 1326 7. If |port| does not equal the request's destination TCP port, 1327 include a Uri-Port Option and let that option's value be |port|. 1329 7.7. Composing URIs from Options 1331 The steps are the same as specified in Section 6.5 of [RFC7252] with 1332 minor changes. 1334 This step from [RFC7252]: 1336 1. If the request is secured using DTLS, let |url| be the string 1337 "coaps://". Otherwise, let |url| be the string "coap://". 1339 is updated to: 1341 1. For CoAP over TCP, if the request is secured using TLS, let |url| 1342 be the string "coaps+tcp://". Otherwise, let |url| be the string 1343 "coap+tcp://". For CoAP over WebSockets, if the request is 1344 secured using TLS, let |url| be the string "coaps+ws://". 1345 Otherwise, let |url| be the string "coap+ws://". 1347 This step from [RFC7252]: 1349 4. If the request includes a Uri-Port Option, let |port| be that 1350 option's value. Otherwise, let |port| be the request's 1351 destination UDP port. 1353 is updated to: 1355 4. If the request includes a Uri-Port Option, let |port| be that 1356 option's value. Otherwise, let |port| be the request's 1357 destination TCP port. 1359 8. Securing CoAP 1361 Security Challenges for the Internet of Things [SecurityChallenges] 1362 recommends: 1364 ... it is essential that IoT protocol suites specify a mandatory 1365 to implement but optional to use security solution. This will 1366 ensure security is available in all implementations, but 1367 configurable to use when not necessary (e.g., in closed 1368 environment). ... even if those features stretch the capabilities 1369 of such devices. 1371 A security solution MUST be implemented to protect CoAP over reliable 1372 transports and MUST be enabled by default. This document defines the 1373 TLS binding, but alternative solutions at different layers in the 1374 protocol stack MAY be used to protect CoAP over reliable transports 1375 when appropriate. Note that there is ongoing work to support a data 1376 object-based security model for CoAP that is independent of transport 1377 (see [I-D.ietf-core-object-security]). 1379 8.1. TLS binding for CoAP over TCP 1381 The TLS usage guidance in [RFC7925] applies. 1383 During the provisioning phase, a CoAP device is provided with the 1384 security information that it needs, including keying materials, 1385 access control lists, and authorization servers. At the end of the 1386 provisioning phase, the device will be in one of four security modes: 1388 NoSec: TLS is disabled. 1390 PreSharedKey: TLS is enabled. The guidance in Section 4.2 of 1391 [RFC7925] applies. 1393 RawPublicKey: TLS is enabled. The guidance in Section 4.3 of 1394 [RFC7925] applies. 1396 Certificate: TLS is enabled. The guidance in Section 4.4 of 1397 [RFC7925] applies. 1399 The "NoSec" mode is optional-to-implement. The system simply sends 1400 the packets over normal TCP which is indicated by the "coap+tcp" 1401 scheme and the TCP CoAP default port. The system is secured only by 1402 keeping attackers from being able to send or receive packets from the 1403 network with the CoAP nodes. 1405 "PreSharedKey", "RawPublicKey", or "Certificate" is mandatory-to- 1406 implement for the TLS binding depending on the credential type used 1407 with the device. These security modes are achieved using TLS and are 1408 indicated by the "coaps+tcp" scheme and TLS-secured CoAP default 1409 port. 1411 8.2. TLS usage for CoAP over WebSockets 1413 A CoAP client requesting a resource identified by a "coaps+ws" URI 1414 negotiates a secure WebSocket connection to a WebSocket server 1415 endpoint with a "wss" URI. This is described in Section 7.4. 1417 The client MUST perform a TLS handshake after opening the connection 1418 to the server. The guidance in Section 4.1 of [RFC6455] applies. 1419 When a CoAP server exposes resources identified by a "coaps+ws" URI, 1420 the guidance in Section 4.4 of [RFC7925] applies towards mandatory- 1421 to-implement TLS functionality for certificates. For the server-side 1422 requirements in accepting incoming connections over a HTTPS (HTTP- 1423 over-TLS) port, the guidance in Section 4.2 of [RFC6455] applies. 1425 9. Security Considerations 1427 The security considerations of [RFC7252] apply. For CoAP over 1428 WebSockets and CoAP over TLS-secured WebSockets, the security 1429 considerations of [RFC6455] also apply. 1431 9.1. Signaling Messages 1433 The guidance given by an Alternative-Address Option cannot be 1434 followed blindly. In particular, a peer MUST NOT assume that a 1435 successful connection to the Alternative-Address inherits all the 1436 security properties of the current connection. 1438 10. IANA Considerations 1439 10.1. Signaling Codes 1441 IANA is requested to create a third sub-registry for values of the 1442 Code field in the CoAP header (Section 12.1 of [RFC7252]). The name 1443 of this sub-registry is "CoAP Signaling Codes". 1445 Each entry in the sub-registry must include the Signaling Code in the 1446 range 7.00-7.31, its name, and a reference to its documentation. 1448 Initial entries in this sub-registry are as follows: 1450 +------+---------+-----------+ 1451 | Code | Name | Reference | 1452 +------+---------+-----------+ 1453 | 7.01 | CSM | [RFCthis] | 1454 | | | | 1455 | 7.02 | Ping | [RFCthis] | 1456 | | | | 1457 | 7.03 | Pong | [RFCthis] | 1458 | | | | 1459 | 7.04 | Release | [RFCthis] | 1460 | | | | 1461 | 7.05 | Abort | [RFCthis] | 1462 +------+---------+-----------+ 1464 Table 1: CoAP Signal Codes 1466 All other Signaling Codes are Unassigned. 1468 The IANA policy for future additions to this sub-registry is "IETF 1469 Review or IESG Approval" as described in [RFC5226]. 1471 10.2. CoAP Signaling Option Numbers Registry 1473 IANA is requested to create a sub-registry for Options Numbers used 1474 in CoAP signaling options within the "CoRE Parameters" registry. The 1475 name of this sub-registry is "CoAP Signaling Option Numbers". 1477 Each entry in the sub-registry must include one or more of the codes 1478 in the Signaling Codes subregistry (Section 10.1), the option number, 1479 the name of the option, and a reference to the option's 1480 documentation. 1482 Initial entries in this sub-registry are as follows: 1484 +------------+--------+---------------------+-----------+ 1485 | Applies to | Number | Name | Reference | 1486 +------------+--------+---------------------+-----------+ 1487 | 7.01 | 2 | Max-Message-Size | [RFCthis] | 1488 | | | | | 1489 | 7.01 | 4 | Block-wise-Transfer | [RFCthis] | 1490 | | | | | 1491 | 7.02, 7.03 | 2 | Custody | [RFCthis] | 1492 | | | | | 1493 | 7.04 | 2 | Alternative-Address | [RFCthis] | 1494 | | | | | 1495 | 7.04 | 4 | Hold-Off | [RFCthis] | 1496 | | | | | 1497 | 7.05 | 2 | Bad-CSM-Option | [RFCthis] | 1498 +------------+--------+---------------------+-----------+ 1500 Table 2: CoAP Signal Option Codes 1502 The IANA policy for future additions to this sub-registry is based on 1503 number ranges for the option numbers, analogous to the policy defined 1504 in Section 12.2 of [RFC7252]. 1506 The documentation for a Signaling Option Number should specify the 1507 semantics of an option with that number, including the following 1508 properties: 1510 o Whether the option is critical or elective, as determined by the 1511 Option Number. 1513 o Whether the option is repeatable. 1515 o The format and length of the option's value. 1517 o The base value for the option, if any. 1519 10.3. Service Name and Port Number Registration 1521 IANA is requested to assign the port number 5683 and the service name 1522 "coap+tcp", in accordance with [RFC6335]. 1524 Service Name. 1525 coap+tcp 1527 Transport Protocol. 1528 tcp 1530 Assignee. 1531 IESG 1533 Contact. 1534 IETF Chair 1536 Description. 1537 Constrained Application Protocol (CoAP) 1539 Reference. 1540 [RFCthis] 1542 Port Number. 1543 5683 1545 10.4. Secure Service Name and Port Number Registration 1547 IANA is requested to assign the port number 5684 and the service name 1548 "coaps+tcp", in accordance with [RFC6335]. The port number is 1549 requested to address the exceptional case of TLS implementations that 1550 do not support the "Application-Layer Protocol Negotiation Extension" 1551 [RFC7301]. 1553 Service Name. 1554 coaps+tcp 1556 Transport Protocol. 1557 tcp 1559 Assignee. 1560 IESG 1562 Contact. 1563 IETF Chair 1565 Description. 1566 Constrained Application Protocol (CoAP) 1568 Reference. 1569 [RFC7301], [RFCthis] 1571 Port Number. 1572 5684 1574 10.5. URI Scheme Registration 1576 URI schemes are registered within the "Uniform Resource Identifier 1577 (URI) Schemes" registry maintained at 1578 http://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml . 1580 10.5.1. coap+tcp 1582 IANA is requested to register the Uniform Resource Identifier (URI) 1583 scheme "coap+tcp". This registration request complies with 1584 [RFC7595]. 1586 Scheme name: 1587 coap+tcp 1589 Status: 1590 Permanent 1592 Applications/protocols that use this scheme name: 1593 The scheme is used by CoAP endpoints to access CoAP resources 1594 using TCP. 1596 Contact: 1597 IETF chair 1599 Change controller: 1600 IESG 1602 Reference: 1603 Section 7.1 in [RFCthis] 1605 10.5.2. coaps+tcp 1607 IANA is requested to register the Uniform Resource Identifier (URI) 1608 scheme "coaps+tcp". This registration request complies with 1609 [RFC7595]. 1611 Scheme name: 1612 coaps+tcp 1614 Status: 1615 Permanent 1617 Applications/protocols that use this scheme name: 1618 The scheme is used by CoAP endpoints to access CoAP resources 1619 using TLS. 1621 Contact: 1622 IETF chair 1624 Change controller: 1625 IESG 1627 Reference: 1629 Section 7.2 in [RFCthis] 1631 10.5.3. coap+ws 1633 IANA is requested to register the Uniform Resource Identifier (URI) 1634 scheme "coap+ws". This registration request complies with [RFC7595]. 1636 Scheme name: 1637 coap+ws 1639 Status: 1640 Permanent 1642 Applications/protocols that use this scheme name: 1643 The scheme is used by CoAP endpoints to access CoAP resources 1644 using the WebSocket protocol. 1646 Contact: 1647 IETF chair 1649 Change controller: 1650 IESG 1652 Reference: 1653 Section 7.3 in [RFCthis] 1655 10.5.4. coaps+ws 1657 IANA is requested to register the Uniform Resource Identifier (URI) 1658 scheme "coaps+ws". This registration request complies with 1659 [RFC7595]. 1661 Scheme name: 1662 coaps+ws 1664 Status: 1665 Permanent 1667 Applications/protocols that use this scheme name: 1668 The scheme is used by CoAP endpoints to access CoAP resources 1669 using the WebSocket protocol secured with TLS. 1671 Contact: 1672 IETF chair 1674 Change controller: 1675 IESG 1677 References: 1678 Section 7.4 in [RFCthis] 1680 10.6. Well-Known URI Suffix Registration 1682 IANA is requested to register the 'coap' well-known URI in the "Well- 1683 Known URIs" registry. This registration request complies with 1684 [RFC5785]: 1686 URI Suffix. 1687 coap 1689 Change controller. 1690 IETF 1692 Specification document(s). 1693 [RFCthis] 1695 Related information. 1696 None. 1698 10.7. ALPN Protocol Identifier 1700 IANA is requested to assign the following value in the registry 1701 "Application Layer Protocol Negotiation (ALPN) Protocol IDs" created 1702 by [RFC7301]. The "coap" string identifies CoAP when used over TLS. 1704 Protocol. 1705 CoAP 1707 Identification Sequence. 1708 0x63 0x6f 0x61 0x70 ("coap") 1710 Reference. 1711 [RFCthis] 1713 10.8. WebSocket Subprotocol Registration 1715 IANA is requested to register the WebSocket CoAP subprotocol under 1716 the "WebSocket Subprotocol Name Registry": 1718 Subprotocol Identifier. 1719 coap 1721 Subprotocol Common Name. 1722 Constrained Application Protocol (CoAP) 1724 Subprotocol Definition. 1726 [RFCthis] 1728 10.9. CoAP Option Numbers Registry 1730 IANA is requested to add [RFCthis] to the references for the 1731 following entries registered by [RFC7959] in the "CoAP Option 1732 Numbers" sub-registry defined by [RFC7252]: 1734 +--------+--------+---------------------+ 1735 | Number | Name | Reference | 1736 +--------+--------+---------------------+ 1737 | 23 | Block2 | RFC 7959, [RFCthis] | 1738 | | | | 1739 | 27 | Block1 | RFC 7959, [RFCthis] | 1740 +--------+--------+---------------------+ 1742 Table 3: CoAP Option Numbers 1744 11. References 1746 11.1. Normative References 1748 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 1749 RFC 793, DOI 10.17487/RFC0793, September 1981, 1750 . 1752 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1753 Requirement Levels", BCP 14, RFC 2119, 1754 DOI 10.17487/RFC2119, March 1997, 1755 . 1757 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1758 Resource Identifier (URI): Generic Syntax", STD 66, 1759 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1760 . 1762 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1763 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1764 DOI 10.17487/RFC5226, May 2008, 1765 . 1767 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1768 (TLS) Protocol Version 1.2", RFC 5246, 1769 DOI 10.17487/RFC5246, August 2008, 1770 . 1772 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1773 Uniform Resource Identifiers (URIs)", RFC 5785, 1774 DOI 10.17487/RFC5785, April 2010, 1775 . 1777 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 1778 Extensions: Extension Definitions", RFC 6066, 1779 DOI 10.17487/RFC6066, January 2011, 1780 . 1782 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 1783 RFC 6455, DOI 10.17487/RFC6455, December 2011, 1784 . 1786 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1787 Application Protocol (CoAP)", RFC 7252, 1788 DOI 10.17487/RFC7252, June 2014, 1789 . 1791 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 1792 "Transport Layer Security (TLS) Application-Layer Protocol 1793 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1794 July 2014, . 1796 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 1797 and Registration Procedures for URI Schemes", BCP 35, 1798 RFC 7595, DOI 10.17487/RFC7595, June 2015, 1799 . 1801 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1802 Application Protocol (CoAP)", RFC 7641, 1803 DOI 10.17487/RFC7641, September 2015, 1804 . 1806 [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer 1807 Security (TLS) / Datagram Transport Layer Security (DTLS) 1808 Profiles for the Internet of Things", RFC 7925, 1809 DOI 10.17487/RFC7925, July 2016, 1810 . 1812 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1813 the Constrained Application Protocol (CoAP)", RFC 7959, 1814 DOI 10.17487/RFC7959, August 2016, 1815 . 1817 11.2. Informative References 1819 [HomeGateway] 1820 Eggert, L., "An experimental study of home gateway 1821 characteristics", Proceedings of the 10th annual 1822 conference on Internet measurement , 2010. 1824 [I-D.ietf-core-cocoa] 1825 Bormann, C., Betzler, A., Gomez, C., and I. Demirkol, 1826 "CoAP Simple Congestion Control/Advanced", draft-ietf- 1827 core-cocoa-01 (work in progress), March 2017. 1829 [I-D.ietf-core-object-security] 1830 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1831 "Object Security of CoAP (OSCOAP)", draft-ietf-core- 1832 object-security-02 (work in progress), March 2017. 1834 [LWM2M] Open Mobile Alliance, "Lightweight Machine to Machine 1835 Technical Specification Version 1.0", February 2017, 1836 . 1840 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 1841 DOI 10.17487/RFC0768, August 1980, 1842 . 1844 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1845 Specifications: ABNF", STD 68, RFC 5234, 1846 DOI 10.17487/RFC5234, January 2008, 1847 . 1849 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 1850 Cheshire, "Internet Assigned Numbers Authority (IANA) 1851 Procedures for the Management of the Service Name and 1852 Transport Protocol Port Number Registry", BCP 165, 1853 RFC 6335, DOI 10.17487/RFC6335, August 2011, 1854 . 1856 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1857 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1858 January 2012, . 1860 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1861 Protocol (HTTP/1.1): Message Syntax and Routing", 1862 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1863 . 1865 [SecurityChallenges] 1866 Polk, T. and S. Turner, "Security Challenges for the 1867 Internet of Things", Interconnecting Smart Objects with 1868 the Internet / IAB Workshop , February 2011, 1869 . 1872 Appendix A. Updates to RFC 7641 Observing Resources in the Constrained 1873 Application Protocol (CoAP) 1875 In this appendix, "client" and "server" refer to the CoAP client and 1876 CoAP server. 1878 A.1. Notifications and Reordering 1880 When using the Observe Option with CoAP over UDP, notifications from 1881 the server set the option value to an increasing sequence number for 1882 reordering detection on the client since messages can arrive in a 1883 different order than they were sent. This sequence number is not 1884 required for CoAP over reliable transports since the TCP protocol 1885 ensures reliable and ordered delivery of messages. The value of the 1886 Observe Option in 2.xx notifications MAY be empty on transmission and 1887 MUST be ignored on reception. 1889 A.2. Transmission and Acknowledgements 1891 For CoAP over UDP, server notifications to the client can be 1892 confirmable or non-confirmable. A confirmable message requires the 1893 client to either respond with an acknowledgement message or a reset 1894 message. An acknowledgement message indicates that the client is 1895 alive and wishes to receive further notifications. A reset message 1896 indicates that the client does not recognize the token which causes 1897 the server to remove the associated entry from the list of observers. 1899 Since TCP eliminates the need for the message layer to support 1900 reliability, CoAP over reliable transports does not support 1901 confirmable or non-confirmable message types. All notifications are 1902 delivered reliably to the client with positive acknowledgement of 1903 receipt occurring at the TCP level. If the client does not recognize 1904 the token in a notification, it MAY immediately abort the connection 1905 (see Section 5.6). 1907 A.3. Freshness 1909 For CoAP over UDP, if a client does not receive a notification for 1910 some time, it MAY send a new GET request with the same token as the 1911 original request to re-register its interest in a resource and verify 1912 that the server is still responsive. For CoAP over reliable 1913 transports, it is more efficient to check the health of the 1914 connection (and all its active observations) by sending a CoAP Ping 1915 Signaling message (Section 5.4) rather than individual requests to 1916 confirm active observations. 1918 A.4. Cancellation 1920 For CoAP over UDP, a client that is no longer interested in receiving 1921 notifications can "forget" the observation and respond to the next 1922 notification from the server with a reset message to cancel the 1923 observation. 1925 For CoAP over reliable transports, a client MUST explicitly 1926 deregister by issuing a GET request that has the Token field set to 1927 the token of the observation to be cancelled and includes an Observe 1928 Option with the value set to 1 (deregister). 1930 If the client observes one or more resources over a reliable 1931 transport, then the CoAP server (or intermediary in the role of the 1932 CoAP server) MUST remove all entries associated with the client 1933 endpoint from the lists of observers when the connection is either 1934 closed or times out. 1936 Appendix B. CoAP over WebSocket Examples 1938 This section gives examples for the first two configurations 1939 discussed in Section 4. 1941 An example of the process followed by a CoAP client to retrieve the 1942 representation of a resource identified by a "coap+ws" URI might be 1943 as follows. Figure 20 below illustrates the WebSocket and CoAP 1944 messages exchanged in detail. 1946 1. The CoAP client obtains the URI , for example, from a resource representation 1948 that it retrieved previously. 1950 2. It establishes a WebSocket connection to the endpoint URI 1951 composed of the authority "example.org" and the well-known path 1952 "/.well-known/coap", . 1954 3. It sends a single-frame, masked, binary message containing a CoAP 1955 request. The request indicates the target resource with the Uri- 1956 Path ("sensors", "temperature") and Uri-Query ("u=Cel") options. 1958 4. It waits for the server to return a response. 1960 5. The CoAP client uses the connection for further requests, or the 1961 connection is closed. 1963 CoAP CoAP 1964 Client Server 1965 (WebSocket (WebSocket 1966 Client) Server) 1968 | | 1969 | | 1970 +=========>| GET /.well-known/coap HTTP/1.1 1971 | | Host: example.org 1972 | | Upgrade: websocket 1973 | | Connection: Upgrade 1974 | | Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 1975 | | Sec-WebSocket-Protocol: coap 1976 | | Sec-WebSocket-Version: 13 1977 | | 1978 |<=========+ HTTP/1.1 101 Switching Protocols 1979 | | Upgrade: websocket 1980 | | Connection: Upgrade 1981 | | Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 1982 | | Sec-WebSocket-Protocol: coap 1983 | | 1984 | | 1985 +--------->| Binary frame (opcode=%x2, FIN=1, MASK=1) 1986 | | +-------------------------+ 1987 | | | GET | 1988 | | | Token: 0x53 | 1989 | | | Uri-Path: "sensors" | 1990 | | | Uri-Path: "temperature" | 1991 | | | Uri-Query: "u=Cel" | 1992 | | +-------------------------+ 1993 | | 1994 |<---------+ Binary frame (opcode=%x2, FIN=1, MASK=0) 1995 | | +-------------------------+ 1996 | | | 2.05 Content | 1997 | | | Token: 0x53 | 1998 | | | Payload: "22.3 Cel" | 1999 | | +-------------------------+ 2000 : : 2001 : : 2002 | | 2003 +--------->| Close frame (opcode=%x8, FIN=1, MASK=1) 2004 | | 2005 |<---------+ Close frame (opcode=%x8, FIN=1, MASK=0) 2006 | | 2008 Figure 20: A CoAP client retrieves the representation of a resource 2009 identified by a "coap+ws" URI 2011 Figure 21 shows how a CoAP client uses a CoAP forward proxy with a 2012 WebSocket endpoint to retrieve the representation of the resource 2013 "coap://[2001:db8::1]/". The use of the forward proxy and the 2014 address of the WebSocket endpoint are determined by the client from 2015 local configuration rules. The request URI is specified in the 2016 Proxy-Uri Option. Since the request URI uses the "coap" URI scheme, 2017 the proxy fulfills the request by issuing a Confirmable GET request 2018 over UDP to the CoAP server and returning the response over the 2019 WebSocket connection to the client. 2021 CoAP CoAP CoAP 2022 Client Proxy Server 2023 (WebSocket (WebSocket (UDP 2024 Client) Server) Endpoint) 2026 | | | 2027 +--------->| | Binary frame (opcode=%x2, FIN=1, MASK=1) 2028 | | | +------------------------------------+ 2029 | | | | GET | 2030 | | | | Token: 0x7d | 2031 | | | | Proxy-Uri: "coap://[2001:db8::1]/" | 2032 | | | +------------------------------------+ 2033 | | | 2034 | +--------->| CoAP message (Ver=1, T=Con, MID=0x8f54) 2035 | | | +------------------------------------+ 2036 | | | | GET | 2037 | | | | Token: 0x0a15 | 2038 | | | +------------------------------------+ 2039 | | | 2040 | |<---------+ CoAP message (Ver=1, T=Ack, MID=0x8f54) 2041 | | | +------------------------------------+ 2042 | | | | 2.05 Content | 2043 | | | | Token: 0x0a15 | 2044 | | | | Payload: "ready" | 2045 | | | +------------------------------------+ 2046 | | | 2047 |<---------+ | Binary frame (opcode=%x2, FIN=1, MASK=0) 2048 | | | +------------------------------------+ 2049 | | | | 2.05 Content | 2050 | | | | Token: 0x7d | 2051 | | | | Payload: "ready" | 2052 | | | +------------------------------------+ 2053 | | | 2055 Figure 21: A CoAP client retrieves the representation of a resource 2056 identified by a "coap" URI via a WebSockets-enabled CoAP proxy 2058 Appendix C. Change Log 2060 The RFC Editor is requested to remove this section at publication. 2062 C.1. Since draft-ietf-core-coap-tcp-tls-02 2064 Merged draft-savolainen-core-coap-websockets-07 Merged draft-bormann- 2065 core-block-bert-01 Merged draft-bormann-core-coap-sig-02 2067 C.2. Since draft-ietf-core-coap-tcp-tls-03 2069 Editorial updates 2071 Added mandatory exchange of Capabilities and Settings messages after 2072 connecting 2074 Added support for coaps+tcp port 5684 and more details on 2075 Application-Layer Protocol Negotiation (ALPN) 2077 Added guidance on CoAP Signaling Ping-Pong versus WebSocket Ping-Pong 2079 Updated references and requirements for TLS security considerations 2081 C.3. Since draft-ietf-core-coap-tcp-tls-04 2083 Updated references 2085 Added Appendix: Updates to RFC7641 Observing Resources in the 2086 Constrained Application Protocol (CoAP) 2088 Updated Capability and Settings Message (CSM) exchange in the Opening 2089 Handshake to allow initiator to send messages before receiving 2090 acceptor CSM 2092 C.4. Since draft-ietf-core-coap-tcp-tls-05 2094 Addressed feedback from Working Group Last Call 2096 Added Securing CoAP section and informative reference to OSCOAP 2098 Removed the Server-Name and Bad-Server-Name Options 2100 Clarified the Capability and Settings Message (CSM) exchange 2102 Updated Pong response requirements 2104 Added Connection Initiator and Connection Acceptor terminology where 2105 appropriate 2106 Updated LWM2M 1.0 informative reference 2108 C.5. Since draft-ietf-core-coap-tcp-tls-06 2110 Addressed feedback from second Working Group Last Call 2112 C.6. Since draft-ietf-core-coap-tcp-tls-07 2114 Addressed feedback from IETF Last Call 2116 Addressed feedback from ARTART review 2118 Addressed feedback from GENART review 2120 Addressed feedback from TSVART review 2122 Added fragment identifiers to URI schemes 2124 Added "Updates RFC7959" for BERT 2126 Added "Updates RFC6455" to extend well-known URI mechanism to ws and 2127 wss 2129 Clarified well-known URI mechanism use for all URI schemes 2131 Changed NoSec to optional-to-implement 2133 Acknowledgements 2135 We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier 2136 Delaby, Esko Dijk, Christian Groves, Nadir Javed, Michael Koster, 2137 Matthias Kovatsch, Achim Kraus, David Navarro, Szymon Sasin, Goran 2138 Selander, Zach Shelby, Andrew Summers, Julien Vermillard, and Gengyu 2139 Wei for their feedback. 2141 Contributors 2142 Matthias Kovatsch 2143 Siemens AG 2144 Otto-Hahn-Ring 6 2145 Munich D-81739 2147 Phone: +49-173-5288856 2148 EMail: matthias.kovatsch@siemens.com 2150 Teemu Savolainen 2151 Nokia Technologies 2152 Hatanpaan valtatie 30 2153 Tampere FI-33100 2154 Finland 2156 Email: teemu.savolainen@nokia.com 2158 Valik Solorzano Barboza 2159 Zebra Technologies 2160 820 W. Jackson Blvd. Suite 700 2161 Chicago 60607 2162 United States of America 2164 Phone: +1-847-634-6700 2165 Email: vsolorzanobarboza@zebra.com 2167 Authors' Addresses 2169 Carsten Bormann 2170 Universitaet Bremen TZI 2171 Postfach 330440 2172 Bremen D-28359 2173 Germany 2175 Phone: +49-421-218-63921 2176 Email: cabo@tzi.org 2178 Simon Lemay 2179 Zebra Technologies 2180 820 W. Jackson Blvd. Suite 700 2181 Chicago 60607 2182 United States of America 2184 Phone: +1-847-634-6700 2185 Email: slemay@zebra.com 2186 Hannes Tschofenig 2187 ARM Ltd. 2188 110 Fulbourn Rd 2189 Cambridge CB1 9NJ 2190 Great Britain 2192 Email: Hannes.tschofenig@gmx.net 2193 URI: http://www.tschofenig.priv.at 2195 Klaus Hartke 2196 Universitaet Bremen TZI 2197 Postfach 330440 2198 Bremen D-28359 2199 Germany 2201 Phone: +49-421-218-63905 2202 Email: hartke@tzi.org 2204 Bilhanan Silverajan 2205 Tampere University of Technology 2206 Korkeakoulunkatu 10 2207 Tampere FI-33720 2208 Finland 2210 Email: bilhanan.silverajan@tut.fi 2212 Brian Raymor (editor) 2213 Microsoft 2214 One Microsoft Way 2215 Redmond 98052 2216 United States of America 2218 Email: brian.raymor@microsoft.com