idnits 2.17.00 (12 Aug 2021) /tmp/idnits7196/draft-ietf-core-coap-tcp-tls-09.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 RFC7959, but the abstract doesn't seem to directly say this. It does mention RFC7959 though, so this could be OK. -- The draft header indicates that this document updates RFC7641, but the abstract doesn't seem to directly say this. It does mention RFC7641 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 (May 16, 2017) is 1830 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 316, but not defined == Missing Reference: '------' is mentioned on line 316, but not defined == Missing Reference: 'RFCthis' is mentioned on line 1630, but not defined == Outdated reference: draft-bormann-hybi-ws-wk has been published as RFC 8307 ** 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: draft-ietf-core-object-security has been published as RFC 8613 == Outdated reference: draft-ietf-core-resource-directory has been published as RFC 9176 -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) -- Obsolete informational reference (is this intentional?): RFC 6555 (Obsoleted by RFC 8305) Summary: 4 errors (**), 0 flaws (~~), 8 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: 7252, 7641, 7959 (if approved) S. Lemay 5 Intended status: Standards Track Zebra Technologies 6 Expires: November 17, 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 May 16, 2017 16 CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets 17 draft-ietf-core-coap-tcp-tls-09 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 7252 fixing an erratum in 30 the URI syntax, RFC 7641 for use with the new transports, and RFC 31 7959 to enable the use of larger messages over a reliable transport. 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at http://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on November 17, 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 . . . . . . . . . . . . . . . . . . . . . 7 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. Use of the "coap" URI scheme with TCP . . . . . . . . . . 25 92 7.2. Use of the "coaps" URI scheme with TLS over TCP . . . . . 25 93 7.3. Use of the "coap" URI scheme with WebSockets . . . . . . 26 94 7.4. Use of the "coaps" URI scheme with WebSockets . . . . . . 27 95 7.5. Uri-Host and Uri-Port Options . . . . . . . . . . . . . . 27 96 7.6. Decomposing URIs into Options . . . . . . . . . . . . . . 28 97 7.7. Composing URIs from Options . . . . . . . . . . . . . . . 28 98 7.8. Trying out multiple transports at once . . . . . . . . . 29 99 8. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 29 100 8.1. TLS binding for CoAP over TCP . . . . . . . . . . . . . . 30 101 8.2. TLS usage for CoAP over WebSockets . . . . . . . . . . . 30 102 9. Security Considerations . . . . . . . . . . . . . . . . . . . 31 103 9.1. Signaling Messages . . . . . . . . . . . . . . . . . . . 31 104 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 105 10.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . 31 106 10.2. CoAP Signaling Option Numbers Registry . . . . . . . . . 32 107 10.3. Service Name and Port Number Registration . . . . . . . 33 108 10.4. Secure Service Name and Port Number Registration . . . . 34 109 10.5. Well-Known URI Suffix Registration . . . . . . . . . . . 34 110 10.6. ALPN Protocol Identifier . . . . . . . . . . . . . . . . 35 111 10.7. WebSocket Subprotocol Registration . . . . . . . . . . . 35 112 10.8. CoAP Option Numbers Registry . . . . . . . . . . . . . . 35 113 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 114 11.1. Normative References . . . . . . . . . . . . . . . . . . 36 115 11.2. Informative References . . . . . . . . . . . . . . . . . 37 116 Appendix A. Updates to RFC 7641 Observing Resources in the 117 Constrained Application Protocol (CoAP) . . . . . . 39 118 A.1. Notifications and Reordering . . . . . . . . . . . . . . 39 119 A.2. Transmission and Acknowledgements . . . . . . . . . . . . 39 120 A.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 40 121 A.4. Cancellation . . . . . . . . . . . . . . . . . . . . . . 40 122 Appendix B. CoAP over WebSocket Examples . . . . . . . . . . . . 40 123 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 44 124 C.1. Since draft-ietf-core-coap-tcp-tls-02 . . . . . . . . . . 44 125 C.2. Since draft-ietf-core-coap-tcp-tls-03 . . . . . . . . . . 44 126 C.3. Since draft-ietf-core-coap-tcp-tls-04 . . . . . . . . . . 44 127 C.4. Since draft-ietf-core-coap-tcp-tls-05 . . . . . . . . . . 44 128 C.5. Since draft-ietf-core-coap-tcp-tls-06 . . . . . . . . . . 45 129 C.6. Since draft-ietf-core-coap-tcp-tls-07 . . . . . . . . . . 45 130 C.7. Since draft-ietf-core-coap-tcp-tls-08 . . . . . . . . . . 45 131 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 45 132 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 46 133 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 46 135 1. Introduction 137 The Constrained Application Protocol (CoAP) [RFC7252] was designed 138 for Internet of Things (IoT) deployments, assuming that UDP [RFC0768] 139 or Datagram Transport Layer Security (DTLS) [RFC6347] over UDP can be 140 used unimpeded. UDP is a good choice for transferring small amounts 141 of data across networks that follow the IP architecture. 143 Some CoAP deployments need to integrate well with existing enterprise 144 infrastructures, where UDP-based protocols may not be well-received 145 or may even be blocked by firewalls. Middleboxes that are unaware of 146 CoAP usage for IoT can make the use of UDP brittle, resulting in lost 147 or malformed packets. 149 Emerging standards such as Lightweight Machine to Machine [LWM2M] 150 currently use CoAP over UDP as a transport and require support for 151 CoAP over TCP to address the issues above and to protect investments 152 in existing CoAP implementations and deployments. Although HTTP/2 153 could also potentially address these requirements, there would be 154 additional costs and delays introduced by such a transition. 155 Currently, there are also fewer HTTP/2 implementations available for 156 constrained devices in comparison to CoAP. 158 To address these requirements, this document defines how to transport 159 CoAP over TCP, CoAP over TLS, and CoAP over WebSockets. For these 160 cases, the reliability offered by the transport protocol subsumes the 161 reliability functions of the message layer used for CoAP over UDP. 162 (Note that both for a reliable transport and the CoAP over UDP 163 message layer, the reliability offered is per transport hop: where 164 proxies -- see Sections 5.7 and 10 of [RFC7252] -- are involved, that 165 layer's reliability function does not extend end-to-end.) Figure 1 166 illustrates the layering: 168 +--------------------------------+ 169 | Application | 170 +--------------------------------+ 171 +--------------------------------+ 172 | Requests/Responses/Signaling | CoAP (RFC 7252) / This Document 173 |--------------------------------| 174 | Message Framing | This Document 175 +--------------------------------+ 176 | Reliable Transport | 177 +--------------------------------+ 179 Figure 1: Layering of CoAP over Reliable Transports 181 Where NATs are present, CoAP over TCP can help with their traversal. 182 NATs often calculate expiration timers based on the transport layer 183 protocol being used by application protocols. Many NATs maintain 184 TCP-based NAT bindings for longer periods based on the assumption 185 that a transport layer protocol, such as TCP, offers additional 186 information about the session life cycle. UDP, on the other hand, 187 does not provide such information to a NAT and timeouts tend to be 188 much shorter [HomeGateway]. 190 Some environments may also benefit from the ability of TCP to 191 exchange larger payloads, such as firmware images, without 192 application layer segmentation and to utilize the more sophisticated 193 congestion control capabilities provided by many TCP implementations. 195 Note that there is ongoing work to add more elaborate congestion 196 control to CoAP (see [I-D.ietf-core-cocoa]). 198 CoAP may be integrated into a Web environment where the front-end 199 uses CoAP over UDP from IoT devices to a cloud infrastructure and 200 then CoAP over TCP between the back-end services. A TCP-to-UDP 201 gateway can be used at the cloud boundary to communicate with the 202 UDP-based IoT device. 204 To allow IoT devices to better communicate in these demanding 205 environments, CoAP needs to support different transport protocols, 206 namely TCP [RFC0793], in some situations secured by TLS [RFC5246]. 208 CoAP applications running inside a web browser without access to 209 connectivity other than HTTP and the WebSocket protocol [RFC6455] may 210 cross-proxy their CoAP requests via HTTP to a HTTP-to-CoAP cross- 211 proxy or transport them via the the WebSocket protocol, which 212 provides two-way communication between a WebSocket client and a 213 WebSocket server after upgrading an HTTP/1.1 [RFC7230] connection. 215 This document specifies how to access resources using CoAP requests 216 and responses over the TCP, TLS and WebSocket protocols. This allows 217 connectivity-limited applications to obtain end-to-end CoAP 218 connectivity either by communicating CoAP directly with a CoAP server 219 accessible over a TCP, TLS or WebSocket connection or via a CoAP 220 intermediary that proxies CoAP requests and responses between 221 different transports, such as between WebSockets and UDP. 223 Appendix A updates the "Observing Resources in the Constrained 224 Application Protocol" [RFC7641] specification for use with CoAP over 225 reliable transports. [RFC7641] is an extension to the CoAP protocol 226 that enables CoAP clients to "observe" a resource on a CoAP server. 227 (The CoAP client retrieves a representation of a resource and 228 registers to be notified by the CoAP server when the representation 229 is updated.) 231 Section 7 fixes an erratum on the URI scheme syntax in [RFC7252]. 232 Section 6 defines semantics for a value 7 for the field "SZX" in a 233 Block1 or Block2 option, updating [RFC7959]. 235 2. Conventions and Terminology 237 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 238 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 239 "OPTIONAL" in this document are to be interpreted as described in 240 [RFC2119]. 242 This document assumes that readers are familiar with the terms and 243 concepts that are used in [RFC6455], [RFC7252], [RFC7641], and 244 [RFC7959]. 246 The term "reliable transport" is used only to refer to transport 247 protocols, such as TCP, which provide reliable and ordered delivery 248 of a byte-stream. 250 Block-wise Extension for Reliable Transport (BERT): 251 BERT extends [RFC7959] to enable the use of larger messages over a 252 reliable transport. 254 BERT Option: 255 A Block1 or Block2 option that includes an SZX value of 7. 257 BERT Block: 258 The payload of a CoAP message that is affected by a BERT Option in 259 descriptive usage (see Section 2.1 of [RFC7959]). 261 Connection Initiator: 262 The peer that opens a reliable byte stream connection, i.e., the 263 TCP active opener, TLS client, or WebSocket client. 265 Connection Acceptor: 266 The peer that accepts the reliable byte stream connection opened 267 by the other peer, i.e., the TCP passive opener, TLS server, or 268 WebSocket server. 270 For simplicity, a Payload Marker (0xFF) is shown in all examples for 271 message formats: 273 ... 274 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 275 |1 1 1 1 1 1 1 1| Payload (if any) ... 276 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 278 The Payload Marker indicates the start of the optional payload and is 279 absent for zero-length payloads (see Section 3 of [RFC7252]). 281 3. CoAP over TCP 283 The request/response interaction model of CoAP over TCP is the same 284 as CoAP over UDP. The primary differences are in the message layer. 285 The message layer of CoAP over UDP supports optional reliability by 286 defining four types of messages: Confirmable, Non-confirmable, 287 Acknowledgement, and Reset. In addition, messages include a Message 288 ID to relate Acknowledgments to Confirmable messages and to detect 289 duplicate messages. 291 3.1. Messaging Model 293 Conceptually, CoAP over TCP replaces most of the message layer of 294 CoAP over UDP with a framing mechanism on top of the byte-stream 295 provided by TCP/TLS, conveying the length information for each 296 message that on datagram transports is provided by the UDP/DTLS 297 datagram layer. 299 TCP ensures reliable message transmission, so the message layer of 300 CoAP over TCP is not required to support acknowledgements or to 301 detect duplicate messages. As a result, both the Type and Message ID 302 fields are no longer required and are removed from the CoAP over TCP 303 message format. 305 Figure 2 illustrates the difference between CoAP over UDP and CoAP 306 over reliable transport. The removed Type and Message ID fields are 307 indicated by dashes. 309 CoAP Client CoAP Server CoAP Client CoAP Server 310 | | | | 311 | CON [0xbc90] | | (-------) [------] | 312 | GET /temperature | | GET /temperature | 313 | (Token 0x71) | | (Token 0x71) | 314 +------------------->| +------------------->| 315 | | | | 316 | ACK [0xbc90] | | (-------) [------] | 317 | 2.05 Content | | 2.05 Content | 318 | (Token 0x71) | | (Token 0x71) | 319 | "22.5 C" | | "22.5 C" | 320 |<-------------------+ |<-------------------+ 321 | | | | 323 CoAP over UDP CoAP over reliable 324 transport 326 Figure 2: Comparison between CoAP over unreliable and reliable 327 transport 329 3.2. Message Format 331 The CoAP message format defined in [RFC7252], as shown in Figure 3, 332 relies on the datagram transport (UDP, or DTLS over UDP) for keeping 333 the individual messages separate and for providing length 334 information. 336 0 1 2 3 337 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 338 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 339 |Ver| T | TKL | Code | Message ID | 340 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 341 | Token (if any, TKL bytes) ... 342 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 343 | Options (if any) ... 344 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 345 |1 1 1 1 1 1 1 1| Payload (if any) ... 346 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 348 Figure 3: RFC 7252 defined CoAP Message Format 350 The CoAP over TCP message format is very similar to the format 351 specified for CoAP over UDP. The differences are as follows: 353 o Since the underlying TCP connection provides retransmissions and 354 deduplication, there is no need for the reliability mechanisms 355 provided by CoAP over UDP. The Type (T) and Message ID fields in 356 the CoAP message header are elided. 358 o The Version (Vers) field is elided as well. In contrast to the 359 message format of CoAP over UDP, the message format for CoAP over 360 TCP does not include a version number. CoAP is defined in 361 [RFC7252] with a version number of 1. At this time, there is no 362 known reason to support version numbers different from 1. If 363 version negotiation needs to be addressed in the future, then 364 Capabilities and Settings Messages (CSM see Section 5.3) have been 365 specifically designed to enable such a potential feature. 367 o In a stream oriented transport protocol such as TCP, a form of 368 message delimitation is needed. For this purpose, CoAP over TCP 369 introduces a length field with variable size. Figure 4 shows the 370 adjusted CoAP message format with a modified structure for the 371 fixed header (first 4 bytes of the CoAP over UDP header), which 372 includes the length information of variable size, shown here as an 373 8-bit length. 375 0 1 2 3 376 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 377 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 378 |Len=13 | TKL |Extended Length| Code | TKL bytes ... 379 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 380 | Options (if any) ... 381 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 382 |1 1 1 1 1 1 1 1| Payload (if any) ... 383 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 385 Figure 4: CoAP frame with 8-bit Extended Length field 387 Length (Len): 4-bit unsigned integer. A value between 0 and 12 388 directly indicates the length of the message in bytes starting 389 with the first bit of the Options field. Three values are 390 reserved for special constructs: 392 13: An 8-bit unsigned integer (Extended Length) follows the 393 initial byte and indicates the length of options/payload minus 394 13. 396 14: A 16-bit unsigned integer (Extended Length) in network byte 397 order follows the initial byte and indicates the length of 398 options/payload minus 269. 400 15: A 32-bit unsigned integer (Extended Length) in network byte 401 order follows the initial byte and indicates the length of 402 options/payload minus 65805. 404 The encoding of the Length field is modeled after the Option Length 405 field of the CoAP Options (see Section 3.1 of [RFC7252]). 407 The following figures show the message format for the 0-bit, 16-bit, 408 and the 32-bit variable length cases. 410 0 1 2 3 411 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 412 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 413 | Len | TKL | Code | Token (if any, TKL bytes) ... 414 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 415 | Options (if any) ... 416 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 417 |1 1 1 1 1 1 1 1| Payload (if any) ... 418 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 420 Figure 5: CoAP message format without an Extended Length field 422 For example: A CoAP message just containing a 2.03 code with the 423 token 7f and no options or payload would be encoded as shown in 424 Figure 6. 426 0 1 2 427 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 428 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 429 | 0x01 | 0x43 | 0x7f | 430 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 432 Len = 0 ------> 0x01 433 TKL = 1 ___/ 434 Code = 2.03 --> 0x43 435 Token = 0x7f 437 Figure 6: CoAP message with no options or payload 439 0 1 2 3 440 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 441 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 442 |Len=14 | TKL | Extended Length (16 bits) | Code | 443 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 444 | Token (if any, TKL bytes) ... 445 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 446 | Options (if any) ... 447 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 448 |1 1 1 1 1 1 1 1| Payload (if any) ... 449 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 451 Figure 7: CoAP message format with 16-bit Extended Length field 453 0 1 2 3 454 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 455 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 456 |Len=15 | TKL | Extended Length (32 bits) 457 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 458 | Code | Token (if any, TKL bytes) ... 459 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 460 | Options (if any) ... 461 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 462 |1 1 1 1 1 1 1 1| Payload (if any) ... 463 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 465 Figure 8: CoAP message format with 32-bit Extended Length field 467 The semantics of the other CoAP header fields are left unchanged. 469 3.3. Message Transmission 471 Once a connection is established, both endpoints MUST send a 472 Capabilities and Settings message (CSM see Section 5.3) as their 473 first message on the connection. This message establishes the 474 initial settings and capabilities for the endpoint, such as maximum 475 message size or support for block-wise transfers. The absence of 476 options in the CSM indicates that base values are assumed. 478 To avoid a deadlock, the Connection Initiator MUST NOT wait for the 479 Connection Acceptor to send its initial CSM message before sending 480 its own initial CSM message. Conversely, the Connection Acceptor MAY 481 wait for the Connection Initiator to send its initial CSM message 482 before sending its own initial CSM message. 484 To avoid unnecessary latency, a Connection Initiator MAY send 485 additional messages without waiting to receive the Connection 486 Acceptor's CSM; however, it is important to note that the Connection 487 Acceptor's CSM might advertise capabilities that impact how the 488 initiator is expected to communicate with the acceptor. For example, 489 the acceptor CSM could advertise a Max-Message-Size option (see 490 Section 5.3.1) that is smaller than the base value (1152). 492 Endpoints MUST treat a missing or invalid CSM as a connection error 493 and abort the connection (see Section 5.6). 495 CoAP requests and responses are exchanged asynchronously over the 496 TCP/TLS connection. A CoAP client can send multiple requests without 497 waiting for a response and the CoAP server can return responses in 498 any order. Responses MUST be returned over the same connection as 499 the originating request. Concurrent requests are differentiated by 500 their Token, which is scoped locally to the connection. 502 The connection is bi-directional, so requests can be sent both by the 503 entity that established the connection (Connection Initiator) and the 504 remote host (Connection Acceptor). If one side does not implement a 505 CoAP server, an error response MUST be returned for all CoAP requests 506 from the other side. The simplest approach is to always return 5.01 507 (Not Implemented). A more elaborate mock server could also return 508 4.xx responses such as 4.04 (Not Found) or 4.02 (Bad Option) where 509 appropriate. 511 Retransmission and deduplication of messages is provided by the TCP 512 protocol. 514 3.4. Connection Health 516 Empty messages (Code 0.00) can always be sent and MUST be ignored by 517 the recipient. This provides a basic keep-alive function that can 518 refresh NAT bindings. 520 If a CoAP client does not receive any response for some time after 521 sending a CoAP request (or, similarly, when a client observes a 522 resource and it does not receive any notification for some time), it 523 can send a CoAP Ping Signaling message (see Section 5.4) to test the 524 connection and verify that the CoAP server is responsive. 526 When the underlying TCP connection is closed or reset, the signaling 527 state and any observation state (see Appendix A.4) associated with 528 the reliable connection are removed. In flight messages may or may 529 not be lost. 531 4. CoAP over WebSockets 533 CoAP over WebSockets is intentionally similar to CoAP over TCP; 534 therefore, this section only specifies the differences between the 535 transports. 537 CoAP over WebSockets can be used in a number of configurations. The 538 most basic configuration is a CoAP client retrieving or updating a 539 CoAP resource located on a CoAP server that exposes a WebSocket 540 endpoint (see Figure 9). The CoAP client acts as the WebSocket 541 client, establishes a WebSocket connection, and sends a CoAP request, 542 to which the CoAP server returns a CoAP response. The WebSocket 543 connection can be used for any number of requests. 545 ___________ ___________ 546 | | | | 547 | _|___ requests ___|_ | 548 | CoAP / \ \ -------------> / / \ CoAP | 549 | Client \__/__/ <------------- \__\__/ Server | 550 | | responses | | 551 |___________| |___________| 552 WebSocket =============> WebSocket 553 Client Connection Server 555 Figure 9: CoAP Client (WebSocket client) accesses CoAP Server 556 (WebSocket server) 558 The challenge with this configuration is how to identify a resource 559 in the namespace of the CoAP server. When the WebSocket protocol is 560 used by a dedicated client directly (i.e., not from a web page 561 through a web browser), the client can connect to any WebSocket 562 endpoint. Section 7.3 and Section 7.4 define how the "coap" and 563 "coaps" URI schemes can be used to enable the client to identify both 564 a WebSocket endpoint and the path and query of the CoAP resource 565 within that endpoint. 567 Another possible configuration is to set up a CoAP forward proxy at 568 the WebSocket endpoint. Depending on what transports are available 569 to the proxy, it could forward the request to a CoAP server with a 570 CoAP UDP endpoint (Figure 10), an SMS endpoint (a.k.a. mobile phone), 571 or even another WebSocket endpoint. The CoAP client specifies the 572 resource to be updated or retrieved in the Proxy-Uri Option. 574 ___________ ___________ ___________ 575 | | | | | | 576 | _|___ ___|_ _|___ ___|_ | 577 | CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP | 578 | Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server | 579 | | | | | | 580 |___________| |___________| |___________| 581 WebSocket ===> WebSocket UDP UDP 582 Client Server Client Server 584 Figure 10: CoAP Client (WebSocket client) accesses CoAP Server (UDP 585 server) via a CoAP proxy (WebSocket server/UDP client) 587 A third possible configuration is a CoAP server running inside a web 588 browser (Figure 11). The web browser initially connects to a 589 WebSocket endpoint and is then reachable through the WebSocket 590 server. When no connection exists, the CoAP server is unreachable. 591 Because the WebSocket server is the only way to reach the CoAP 592 server, the CoAP proxy should be a reverse-proxy. 594 ___________ ___________ ___________ 595 | | | | | | 596 | _|___ ___|_ _|___ ___|_ | 597 | CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP | 598 | Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server | 599 | | | | | | 600 |___________| |___________| |___________| 601 UDP UDP WebSocket <=== WebSocket 602 Client Server Server Client 604 Figure 11: CoAP Client (UDP client) accesses CoAP Server (WebSocket 605 client) via a CoAP proxy (UDP server/WebSocket server) 607 Further configurations are possible, including those where a 608 WebSocket connection is established through an HTTP proxy. 610 4.1. Opening Handshake 612 Before CoAP requests and responses are exchanged, a WebSocket 613 connection is established as defined in Section 4 of [RFC6455]. 614 Figure 12 shows an example. 616 The WebSocket client MUST include the subprotocol name "coap" in the 617 list of protocols, which indicates support for the protocol defined 618 in this document. Any later, incompatible versions of CoAP or CoAP 619 over WebSockets will use a different subprotocol name. 621 The WebSocket client includes the hostname of the WebSocket server in 622 the Host header field of its handshake as per [RFC6455]. The Host 623 header field also indicates the default value of the Uri-Host Option 624 in requests from the WebSocket client to the WebSocket server. 626 GET /.well-known/coap HTTP/1.1 627 Host: example.org 628 Upgrade: websocket 629 Connection: Upgrade 630 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 631 Sec-WebSocket-Protocol: coap 632 Sec-WebSocket-Version: 13 634 HTTP/1.1 101 Switching Protocols 635 Upgrade: websocket 636 Connection: Upgrade 637 Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 638 Sec-WebSocket-Protocol: coap 640 Figure 12: Example of an Opening Handshake 642 4.2. Message Format 644 Once a WebSocket connection is established, CoAP requests and 645 responses can be exchanged as WebSocket messages. Since CoAP uses a 646 binary message format, the messages are transmitted in binary data 647 frames as specified in Sections 5 and 6 of [RFC6455]. 649 The message format shown in Figure 13 is the same as the CoAP over 650 TCP message format (see Section 3.2) with one change. The Length 651 (Len) field MUST be set to zero because the WebSockets frame contains 652 the length. 654 0 1 2 3 655 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 656 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 657 | Len=0 | TKL | Code | Token (TKL bytes) ... 658 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 659 | Options (if any) ... 660 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 661 |1 1 1 1 1 1 1 1| Payload (if any) ... 662 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 664 Figure 13: CoAP Message Format over WebSockets 666 As with CoAP over TCP, the message format for CoAP over WebSockets 667 eliminates the Version field defined in CoAP over UDP. If CoAP 668 version negotiation is required in the future, CoAP over WebSockets 669 can address the requirement by the definition of a new subprotocol 670 identifier that is negotiated during the opening handshake. 672 Requests and response messages can be fragmented as specified in 673 Section 5.4 of [RFC6455], though typically they are sent unfragmented 674 as they tend to be small and fully buffered before transmission. The 675 WebSocket protocol does not provide means for multiplexing. If it is 676 not desirable for a large message to monopolize the connection, 677 requests and responses can be transferred in a block-wise fashion as 678 defined in [RFC7959]. 680 4.3. Message Transmission 682 As with CoAP over TCP, both endpoints MUST send a Capabilities and 683 Settings message (CSM see Section 5.3) as their first message on the 684 WebSocket connection. 686 CoAP requests and responses are exchanged asynchronously over the 687 WebSocket connection. A CoAP client can send multiple requests 688 without waiting for a response and the CoAP server can return 689 responses in any order. Responses MUST be returned over the same 690 connection as the originating request. Concurrent requests are 691 differentiated by their Token, which is scoped locally to the 692 connection. 694 The connection is bi-directional, so requests can be sent both by the 695 entity that established the connection and the remote host. 697 As with CoAP over TCP, retransmission and deduplication of messages 698 is provided by the WebSocket protocol. CoAP over WebSockets 699 therefore does not make a distinction between Confirmable or Non- 700 Confirmable messages, and does not provide Acknowledgement or Reset 701 messages. 703 4.4. Connection Health 705 As with CoAP over TCP, a CoAP client can test the health of the CoAP 706 over WebSocket connection by sending a CoAP Ping Signaling message 707 (Section 5.4). WebSocket Ping and unsolicited Pong frames 708 (Section 5.5 of [RFC6455]) SHOULD NOT be used to ensure that 709 redundant maintenance traffic is not transmitted. 711 5. Signaling 713 Signaling messages are introduced to allow peers to: 715 o Learn related characteristics, such as maximum message size for 716 the connection 718 o Shut down the connection in an orderly fashion 720 o Provide diagnostic information when terminating a connection in 721 response to a serious error condition 723 Signaling is a third basic kind of message in CoAP, after requests 724 and responses. Signaling messages share a common structure with the 725 existing CoAP messages. There is a code, a token, options, and an 726 optional payload. 728 (See Section 3 of [RFC7252] for the overall structure of the message 729 format, option format, and option value format.) 731 5.1. Signaling Codes 733 A code in the 7.00-7.31 range indicates a Signaling message. Values 734 in this range are assigned by the "CoAP Signaling Codes" sub-registry 735 (see Section 10.1). 737 For each message, there is a sender and a peer receiving the message. 739 Payloads in Signaling messages are diagnostic payloads as defined in 740 Section 5.5.2 of [RFC7252]), unless otherwise defined by a Signaling 741 message option. 743 5.2. Signaling Option Numbers 745 Option numbers for Signaling messages are specific to the message 746 code. They do not share the number space with CoAP options for 747 request/response messages or with Signaling messages using other 748 codes. 750 Option numbers are assigned by the "CoAP Signaling Option Numbers" 751 sub-registry (see Section 10.2). 753 Signaling options are elective or critical as defined in 754 Section 5.4.1 of [RFC7252]. If a Signaling option is critical and 755 not understood by the receiver, it MUST abort the connection (see 756 Section 5.6). If the option is understood but cannot be processed, 757 the option documents the behavior. 759 5.3. Capabilities and Settings Messages (CSM) 761 Capabilities and Settings messages (CSM) are used for two purposes: 763 o Each capability option advertises one capability of the sender to 764 the recipient. 766 o Each setting option indicates a setting that will be applied by 767 the sender. 769 One CSM MUST be sent by both endpoints at the start of the 770 connection. Further CSM MAY be sent at any other time by either 771 endpoint over the lifetime of the connection. 773 Both capability and setting options are cumulative. A CSM does not 774 invalidate a previously sent capability indication or setting even if 775 it is not repeated. A capability message without any option is a no- 776 operation (and can be used as such). An option that is sent might 777 override a previous value for the same option. The option defines 778 how to handle this case if needed. 780 Base values are listed below for CSM Options. These are the values 781 for the capability and setting before any Capabilities and Settings 782 messages send a modified value. 784 These are not default values for the option, as defined in 785 Section 5.4.4 in [RFC7252]. A default value would mean that an empty 786 Capabilities and Settings message would result in the option being 787 set to its default value. 789 Capabilities and Settings messages are indicated by the 7.01 code 790 (CSM). 792 5.3.1. Max-Message-Size Capability Option 794 The sender can use the elective Max-Message-Size Option to indicate 795 the maximum message size in bytes that it can receive. 797 +---+---+---+---------+------------------+--------+--------+--------+ 798 | # | C | R | Applies | Name | Format | Length | Base | 799 | | | | to | | | | Value | 800 +---+---+---+---------+------------------+--------+--------+--------+ 801 | 2 | | | CSM | Max-Message-Size | uint | 0-4 | 1152 | 802 +---+---+---+---------+------------------+--------+--------+--------+ 804 C=Critical, R=Repeatable 806 As per Section 4.6 of [RFC7252], the base value (and the value used 807 when this option is not implemented) is 1152. 809 The active value of the Max-Message-Size Option is replaced each time 810 the option is sent with a modified value. Its starting value is its 811 base value. 813 5.3.2. Block-wise Transfer Capability Option 815 +---+---+---+---------+-----------------+--------+--------+---------+ 816 | # | C | R | Applies | Name | Format | Length | Base | 817 | | | | to | | | | Value | 818 +---+---+---+---------+-----------------+--------+--------+---------+ 819 | 4 | | | CSM | Block-wise | empty | 0 | (none) | 820 | | | | | Transfer | | | | 821 +---+---+---+---------+-----------------+--------+--------+---------+ 823 C=Critical, R=Repeatable 825 A sender can use the elective Block-wise Transfer Option to indicate 826 that it supports the block-wise transfer protocol [RFC7959]. 828 If the option is not given, the peer has no information about whether 829 block-wise transfers are supported by the sender or not. An 830 implementation that supports block-wise transfers SHOULD indicate the 831 Block-wise Transfer Option. If a Max-Message-Size Option is 832 indicated with a value that is greater than 1152 (in the same or a 833 different CSM message), the Block-wise Transfer Option also indicates 834 support for BERT (see Section 6). Subsequently, if the Max-Message- 835 Size Option is indicated with a value equal to or less than 1152, 836 BERT support is no longer indicated. 838 5.4. Ping and Pong Messages 840 In CoAP over reliable transports, Empty messages (Code 0.00) can 841 always be sent and MUST be ignored by the recipient. This provides a 842 basic keep-alive function. In contrast, Ping and Pong messages are a 843 bidirectional exchange. 845 Upon receipt of a Ping message, the receiver MUST return a Pong 846 message with an identical token in response. Unless there is an 847 option with delaying semantics such as the Custody Option, it SHOULD 848 respond as soon as practical. As with all Signaling messages, the 849 recipient of a Ping or Pong message MUST ignore elective options it 850 does not understand. 852 Ping and Pong messages are indicated by the 7.02 code (Ping) and the 853 7.03 code (Pong). 855 5.4.1. Custody Option 857 +---+---+---+----------+----------------+--------+--------+---------+ 858 | # | C | R | Applies | Name | Format | Length | Base | 859 | | | | to | | | | Value | 860 +---+---+---+----------+----------------+--------+--------+---------+ 861 | 2 | | | Ping, | Custody | empty | 0 | (none) | 862 | | | | Pong | | | | | 863 +---+---+---+----------+----------------+--------+--------+---------+ 865 C=Critical, R=Repeatable 867 When responding to a Ping message, the receiver can include an 868 elective Custody Option in the Pong message. This option indicates 869 that the application has processed all the request/response messages 870 received prior to the Ping message on the current connection. (Note 871 that there is no definition of specific application semantics for 872 "processed", but there is an expectation that the receiver of a Pong 873 Message with a Custody Option should be able to free buffers based on 874 this indication.) 876 A sender can also include an elective Custody Option in a Ping 877 message to explicitly request the inclusion of an elective Custody 878 Option in the corresponding Pong message. In that case, the receiver 879 SHOULD delay its Pong message until it finishes processing all the 880 request/response messages received prior to the Ping message on the 881 current connection. 883 5.5. Release Messages 885 A Release message indicates that the sender does not want to continue 886 maintaining the connection and opts for an orderly shutdown. The 887 details are in the options. A diagnostic payload (see Section 5.5.2 888 of [RFC7252]) MAY be included. A peer will normally respond to a 889 Release message by closing the TCP/TLS connection. Messages may be 890 in flight when the sender decides to send a Release message. The 891 general expectation is that these will still be processed. 893 Release messages are indicated by the 7.04 code (Release). 895 Release messages can indicate one or more reasons using elective 896 options. The following options are defined: 898 +---+---+---+---------+------------------+--------+--------+--------+ 899 | # | C | R | Applies | Name | Format | Length | Base | 900 | | | | to | | | | Value | 901 +---+---+---+---------+------------------+--------+--------+--------+ 902 | 2 | | x | Release | Alternative- | string | 1-255 | (none) | 903 | | | | | Address | | | | 904 +---+---+---+---------+------------------+--------+--------+--------+ 906 C=Critical, R=Repeatable 908 The elective Alternative-Address Option requests the peer to instead 909 open a connection of the same scheme as the present connection to the 910 alternative transport address given. Its value is in the form 911 "authority" as defined in Section 3.2 of [RFC3986]. 913 The Alternative-Address Option is a repeatable option as defined in 914 Section 5.4.5 of [RFC7252]. When multiple occurrences of the option 915 are included, the peer can choose any of the alternative transport 916 addresses. 918 +---+---+---+---------+-----------------+--------+--------+---------+ 919 | # | C | R | Applies | Name | Format | Length | Base | 920 | | | | to | | | | Value | 921 +---+---+---+---------+-----------------+--------+--------+---------+ 922 | 4 | | | Release | Hold-Off | uint | 0-3 | (none) | 923 +---+---+---+---------+-----------------+--------+--------+---------+ 925 C=Critical, R=Repeatable 927 The elective Hold-Off Option indicates that the server is requesting 928 that the peer not reconnect to it for the number of seconds given in 929 the value. 931 5.6. Abort Messages 933 An Abort message indicates that the sender is unable to continue 934 maintaining the connection and cannot even wait for an orderly 935 release. The sender shuts down the connection immediately after the 936 abort (and may or may not wait for a Release or Abort message or 937 connection shutdown in the inverse direction). A diagnostic payload 938 (see Section 5.5.2 of [RFC7252]) SHOULD be included in the Abort 939 message. Messages may be in flight when the sender decides to send 940 an Abort message. The general expectation is that these will NOT be 941 processed. 943 Abort messages are indicated by the 7.05 code (Abort). 945 Abort messages can indicate one or more reasons using elective 946 options. The following option is defined: 948 +---+---+---+---------+-----------------+--------+--------+---------+ 949 | # | C | R | Applies | Name | Format | Length | Base | 950 | | | | to | | | | Value | 951 +---+---+---+---------+-----------------+--------+--------+---------+ 952 | 2 | | | Abort | Bad-CSM-Option | uint | 0-2 | (none) | 953 +---+---+---+---------+-----------------+--------+--------+---------+ 955 C=Critical, R=Repeatable 957 The elective Bad-CSM-Option Option indicates that the sender is 958 unable to process the CSM option identified by its option number, 959 e.g. when it is critical and the option number is unknown by the 960 sender, or when there is parameter problem with the value of an 961 elective option. More detailed information SHOULD be included as a 962 diagnostic payload. 964 For CoAP over UDP, messages which contain syntax violations are 965 processed as message format errors. As described in Sections 4.2 and 966 4.3 of [RFC7252], such messages are rejected by sending a matching 967 Reset message and otherwise ignoring the message. 969 For CoAP over reliable transports, the recipient rejects such 970 messages by sending an Abort message and otherwise ignoring the 971 message. No specific option has been defined for the Abort message 972 in this case, as the details are best left to a diagnostic payload. 974 5.7. Signaling examples 976 An encoded example of a Ping message with a non-empty token is shown 977 in Figure 14. 979 0 1 2 980 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 981 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 982 | 0x01 | 0xe2 | 0x42 | 983 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 985 Len = 0 -------> 0x01 986 TKL = 1 ___/ 987 Code = 7.02 Ping --> 0xe2 988 Token = 0x42 990 Figure 14: Ping Message Example 992 An encoded example of the corresponding Pong message is shown in 993 Figure 15. 995 0 1 2 996 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 997 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 998 | 0x01 | 0xe3 | 0x42 | 999 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1001 Len = 0 -------> 0x01 1002 TKL = 1 ___/ 1003 Code = 7.03 Pong --> 0xe3 1004 Token = 0x42 1006 Figure 15: Pong Message Example 1008 6. Block-wise Transfer and Reliable Transports 1010 The message size restrictions defined in Section 4.6 of CoAP 1011 [RFC7252] to avoid IP fragmentation are not necessary when CoAP is 1012 used over a reliable transport. While this suggests that the Block- 1013 wise transfer protocol [RFC7959] is also no longer needed, it remains 1014 applicable for a number of cases: 1016 o large messages, such as firmware downloads, may cause undesired 1017 head-of-line blocking when a single TCP connection is used 1019 o a UDP-to-TCP gateway may simply not have the context to convert a 1020 message with a Block Option into the equivalent exchange without 1021 any use of a Block Option (it would need to convert the entire 1022 blockwise exchange from start to end into a single exchange) 1024 The 'Block-wise Extension for Reliable Transport (BERT)' extends the 1025 Block protocol to enable the use of larger messages over a reliable 1026 transport. 1028 The use of this new extension is signaled by sending Block1 or Block2 1029 Options with SZX == 7 (a "BERT option"). SZX == 7 is a reserved 1030 value in [RFC7959]. 1032 In control usage, a BERT option is interpreted in the same way as the 1033 equivalent Option with SZX == 6, except that it also indicates the 1034 capability to process BERT blocks. As with the basic Block protocol, 1035 the recipient of a CoAP request with a BERT option in control usage 1036 is allowed to respond with a different SZX value, e.g. to send a non- 1037 BERT block instead. 1039 In descriptive usage, a BERT Option is interpreted in the same way as 1040 the equivalent Option with SZX == 6, except that the payload is also 1041 allowed to contain a multiple of 1024 bytes (non-final BERT block) or 1042 more than 1024 bytes (final BERT block). 1044 The recipient of a non-final BERT block (M=1) conceptually partitions 1045 the payload into a sequence of 1024-byte blocks and acts exactly as 1046 if it had received this sequence in conjunction with block numbers 1047 starting at, and sequentially increasing from, the block number given 1048 in the Block Option. In other words, the entire BERT block is 1049 positioned at the byte position that results from multiplying the 1050 block number with 1024. The position of further blocks to be 1051 transferred is indicated by incrementing the block number by the 1052 number of elements in this sequence (i.e., the size of the payload 1053 divided by 1024 bytes). 1055 As with SZX == 6, the recipient of a final BERT block (M=0) simply 1056 appends the payload at the byte position that is indicated by the 1057 block number multiplied with 1024. 1059 The following examples illustrate BERT options. A value of SZX == 7 1060 is labeled as "BERT" or as "BERT(nnn)" to indicate a payload of size 1061 nnn. 1063 In all these examples, a Block Option is decomposed to indicate the 1064 kind of Block Option (1 or 2) followed by a colon, the block number 1065 (NUM), more bit (M), and block size (2**(SZX+4)) separated by 1066 slashes. E.g., a Block2 Option value of 33 would be shown as 1067 2:2/0/32), or a Block1 Option value of 59 would be shown as 1068 1:3/1/128. 1070 6.1. Example: GET with BERT Blocks 1072 Figure 16 shows a GET request with a response that is split into 1073 three BERT blocks. The first response contains 3072 bytes of 1074 payload; the second, 5120; and the third, 4711. Note how the block 1075 number increments to move the position inside the response body 1076 forward. 1078 CoAP Client CoAP Server 1079 | | 1080 | GET, /status ------> | 1081 | | 1082 | <------ 2.05 Content, 2:0/1/BERT(3072) | 1083 | | 1084 | GET, /status, 2:3/0/BERT ------> | 1085 | | 1086 | <------ 2.05 Content, 2:3/1/BERT(5120) | 1087 | | 1088 | GET, /status, 2:8/0/BERT ------> | 1089 | | 1090 | <------ 2.05 Content, 2:8/0/BERT(4711) | 1092 Figure 16: GET with BERT blocks 1094 6.2. Example: PUT with BERT Blocks 1096 Figure 17 demonstrates a PUT exchange with BERT blocks. 1098 CoAP Client CoAP Server 1099 | | 1100 | PUT, /options, 1:0/1/BERT(8192) ------> | 1101 | | 1102 | <------ 2.31 Continue, 1:0/1/BERT | 1103 | | 1104 | PUT, /options, 1:8/1/BERT(16384) ------> | 1105 | | 1106 | <------ 2.31 Continue, 1:8/1/BERT | 1107 | | 1108 | PUT, /options, 1:24/0/BERT(5683) ------> | 1109 | | 1110 | <------ 2.04 Changed, 1:24/0/BERT | 1111 | | 1113 Figure 17: PUT with BERT blocks 1115 7. CoAP over Reliable Transport URIs 1117 CoAP over UDP [RFC7252] defines the "coap" and "coaps" URI schemes. 1118 This document corrects an erratum in Sections 6.1 and 6.2 of 1119 [RFC7252] and defines how to use the schemes with the new transports. 1120 Section 8 (Multicast CoAP) in [RFC7252] is not applicable to these 1121 new transports. 1123 The syntax for the URI schemes in this section are specified using 1124 Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of 1125 "host", "port", "path-abempty", "query", and "fragment" are adopted 1126 from [RFC3986]. 1128 The ABNF syntax defined in Sections 6.1 and 6.2 of [RFC7252] for 1129 "coap" and "coaps" schemes lacks the fragment identifer. This 1130 specification updates the two rules in those sections as follows: 1132 coap-URI = "coap:" "//" host [ ":" port ] 1133 path-abempty [ "?" query ] [ "#" fragment ] 1134 coaps-URI = "coaps:" "//" host [ ":" port ] 1135 path-abempty [ "?" query ] [ "#" fragment ] 1137 7.1. Use of the "coap" URI scheme with TCP 1139 The "coap" URI scheme defined in Section 6.1 of [RFC7252] can also be 1140 used to identify CoAP resources that are intended to be accessible 1141 using CoAP over TCP. 1143 The syntax defined in Section 6.1 of [RFC7252] applies to this 1144 transport, with the following change: 1146 o The port subcomponent indicates the TCP port at which the CoAP 1147 server is located. (If it is empty or not given, then the default 1148 port 5683 is assumed, as with UDP.) 1150 7.2. Use of the "coaps" URI scheme with TLS over TCP 1152 The "coaps" URI scheme defined in Section 6.2 of [RFC7252] can also 1153 be used to identify CoAP resources that are intended to be accessible 1154 using CoAP over TCP secured with TLS. 1156 The syntax defined in Section 6.2 of [RFC7252] applies to this 1157 transport, with the following changes: 1159 o The port subcomponent indicates the TCP port at which the TLS 1160 server for the CoAP Connection Acceptor is located. If it is 1161 empty or not given, then the default port 5684 is assumed. 1163 o If a TLS server does not support the Application-Layer Protocol 1164 Negotiation Extension (ALPN) [RFC7301] or wishes to accommodate 1165 TLS clients that do not support ALPN, it MAY offer a coaps 1166 endpoint on the default TCP port 5684. This endpoint MAY also be 1167 ALPN enabled. A TLS server MAY offer coaps endpoints on TCP ports 1168 other than 5684; these then MUST be ALPN enabled. 1170 o For TCP ports other than port 5684, the TLS client MUST use the 1171 ALPN extension to advertise the "coap" protocol identifier (see 1172 Section 10.6) in the list of protocols in its ClientHello. If the 1173 TCP server selects and returns the "coap" protocol identifier 1174 using the ALPN extension in its ServerHello, then the connection 1175 succeeds. If the TLS server either does not negotiate the ALPN 1176 extension or returns a no_application_protocol alert, the TLS 1177 client MUST close the connection. 1179 o For TCP port 5684, a TLS client MAY use the ALPN extension to 1180 advertise the "coap" protocol identifier in the list of protocols 1181 in its ClientHello. If the TLS server selects and returns the 1182 "coap" protocol identifier using the ALPN extension in its 1183 ServerHello, then the connection succeeds. If the TLS server 1184 returns a no_application_protocol alert, then the TLS client MUST 1185 close the connection. If the TLS server does not negotiate the 1186 ALPN extension, then coaps over TCP is implicitly selected. 1188 o For TCP port 5684, if the TLS client does not use the ALPN 1189 extension to negotiate the protocol, then coaps over TCP is 1190 implicitly selected. 1192 7.3. Use of the "coap" URI scheme with WebSockets 1194 The "coap" URI scheme defined in Section 6.1 of [RFC7252] can also be 1195 used to identify CoAP resources that are intended to be accessible 1196 using CoAP over WebSockets. 1198 The WebSocket endpoint is identified by a "ws" URI that is composed 1199 of the authority part of the "coap" URI and the well-known path 1200 "/.well-known/coap" [RFC5785] [I-D.bormann-hybi-ws-wk]. The path and 1201 query parts of the "coap" URI identify a resource within the 1202 specified endpoint which can be operated on by the methods defined by 1203 CoAP: 1205 coap://example.org/sensors/temperature?u=Cel 1206 \______ ______/\___________ ___________/ 1207 \/ \/ 1208 Uri-Path: "sensors" 1209 ws://example.org/.well-known/coap Uri-Path: "temperature" 1210 Uri-Query: "u=Cel" 1212 Figure 18: Building ws URIs and Uri options from coap URIs 1214 Note that the default port for "coap" is 5683, while the default port 1215 for "ws" is 80. Therefore, if the port given for "coap" is 80, the 1216 default port for "ws" can be used. If the port is not given for 1217 "coap", then an explicit port number of 5683 needs to be given for 1218 "ws". 1220 7.4. Use of the "coaps" URI scheme with WebSockets 1222 The "coaps" URI scheme defined in Section 6.2 of [RFC7252] can also 1223 be used to identify CoAP resources that are intended to be accessible 1224 using CoAP over WebSockets secured by TLS. 1226 The WebSocket endpoint is identified by a "wss" URI that is composed 1227 of the authority part of the "coaps" URI and the well-known path 1228 "/.well-known/coap" [RFC5785] [I-D.bormann-hybi-ws-wk]. The path and 1229 query parts of the "coaps" URI identify a resource within the 1230 specified endpoint which can be operated on by the methods defined by 1231 CoAP. 1233 coaps://example.org/sensors/temperature?u=Cel 1234 \______ ______/\___________ ___________/ 1235 \/ \/ 1236 Uri-Path: "sensors" 1237 wss://example.org/.well-known/coap Uri-Path: "temperature" 1238 Uri-Query: "u=Cel" 1240 Figure 19: Building wss URIs and Uri options from coaps URIs 1242 Note that the default port for "coaps" is 5684, while the default 1243 port for "wss" is 443. If the port given for "coap" is 443, the 1244 default port for "wss" can be used. If the port is not given for 1245 "coaps", then an explicit port number of 5684 needs to be given for 1246 "wss". 1248 7.5. Uri-Host and Uri-Port Options 1250 Except for the transports over WebSockets, CoAP over reliable 1251 transports maintains the property from Section 5.10.1 of [RFC7252]: 1253 The default values for the Uri-Host and Uri-Port Options are 1254 sufficient for requests to most servers. 1256 Unless otherwise noted, the default value of the Uri-Host Option is 1257 the IP literal representing the destination IP address of the request 1258 message. The default value of the Uri-Port Option is the destination 1259 TCP port. 1261 For CoAP over TLS, these default values are the same unless Server 1262 Name Indication (SNI) [RFC6066] is negotiated. In this case, the 1263 default value of the Uri-Host Option in requests from the TLS client 1264 to the TLS server is the SNI host. 1266 For CoAP over WebSockets, the default value of the Uri-Host Option in 1267 requests from the WebSocket client to the WebSocket server is 1268 indicated by the Host header field from the WebSocket handshake. 1270 7.6. Decomposing URIs into Options 1272 The steps are the same as specified in Section 6.4 of [RFC7252] with 1273 minor changes. 1275 This step from [RFC7252]: 1277 7. If |port| does not equal the request's destination UDP port, 1278 include a Uri-Port Option and let that option's value be |port|. 1280 is updated to: 1282 7. If |port| does not equal the request's destination UDP port or 1283 TCP port, include a Uri-Port Option and let that option's value 1284 be |port|. 1286 7.7. Composing URIs from Options 1288 The steps are the same as specified in Section 6.5 of [RFC7252] with 1289 minor changes. 1291 This step from [RFC7252]: 1293 1. If the request is secured using DTLS, let |url| be the string 1294 "coaps://". Otherwise, let |url| be the string "coap://". 1296 is updated to: 1298 1. If the request is secured using DTLS or TLS, let |url| be 1299 the string "coaps://". Otherwise, let |url| be the string 1300 "coap://". 1302 This step from [RFC7252]: 1304 4. If the request includes a Uri-Port Option, let |port| be that 1305 option's value. Otherwise, let |port| be the request's 1306 destination UDP port. 1308 is updated to: 1310 4. If the request includes a Uri-Port Option, let |port| be that 1311 option's value. Otherwise, let |port| be the request's 1312 destination UDP port or TCP port. 1314 7.8. Trying out multiple transports at once 1316 As in the "Happy Eyeballs" approach to using IPv6 and IPv4 [RFC6555], 1317 an application may want to try out multiple transports for a given 1318 URI at the same time, e.g., DTLS over UDP and TLS over TCP. However, 1319 two important caveats need to be considered: 1321 o Initiating multiple instances of the same exchange with the 1322 intention of using only one of the successful results is only safe 1323 for idempotent exchanges (see Section 5.1 of [RFC7252]). 1325 o An important setback in using the UDP or DTLS over UDP transport 1326 through NATs and other middleboxes can be the quick loss of NAT 1327 bindings during idling periods [HomeGateway]. This will not be 1328 evident right on the initial exchange. 1330 After the initial exchange, or whenever important information is 1331 learned about which selection to prefer, an endpoint may want to 1332 cache this information; however, the information may become stale 1333 after the endpoint moves or the network changes. A cache timeout 1334 (possibly enhanced by movement detection) is advisable. 1336 Alternatively, or additionally, the choice of transport may be aided 1337 by configuration and resource directory information; the self- 1338 description of a node may also include target attributes for links 1339 given to resources there. Details of such attributes are out of 1340 scope for the present document; see for instance 1341 [I-D.ietf-core-resource-directory]. 1343 8. Securing CoAP 1345 Security Challenges for the Internet of Things [SecurityChallenges] 1346 recommends: 1348 ... it is essential that IoT protocol suites specify a mandatory 1349 to implement but optional to use security solution. This will 1350 ensure security is available in all implementations, but 1351 configurable to use when not necessary (e.g., in closed 1352 environment). ... even if those features stretch the capabilities 1353 of such devices. 1355 A security solution MUST be implemented to protect CoAP over reliable 1356 transports and MUST be enabled by default. This document defines the 1357 TLS binding, but alternative solutions at different layers in the 1358 protocol stack MAY be used to protect CoAP over reliable transports 1359 when appropriate. Note that there is ongoing work to support a data 1360 object-based security model for CoAP that is independent of transport 1361 (see [I-D.ietf-core-object-security]). 1363 8.1. TLS binding for CoAP over TCP 1365 The TLS usage guidance in [RFC7925] applies, including the guidance 1366 about cipher suites in that document that are derived from the 1367 mandatory to implement (MTI) cipher suites defined in [RFC7252]. 1368 (Note that this selection caters for the device-to-cloud use case of 1369 CoAP over TLS more than for any use within a back-end environment, 1370 where the standard TLS 1.2 cipher suites or the more recent ones 1371 defined in [RFC7525] are more appropriate.) 1373 During the provisioning phase, a CoAP device is provided with the 1374 security information that it needs, including keying materials, 1375 access control lists, and authorization servers. At the end of the 1376 provisioning phase, the device will be in one of four security modes: 1378 NoSec: TLS is disabled. 1380 PreSharedKey: TLS is enabled. The guidance in Section 4.2 of 1381 [RFC7925] applies. 1383 RawPublicKey: TLS is enabled. The guidance in Section 4.3 of 1384 [RFC7925] applies. 1386 Certificate: TLS is enabled. The guidance in Section 4.4 of 1387 [RFC7925] applies. 1389 The "NoSec" mode is optional-to-implement. The system simply sends 1390 the packets over normal TCP which is indicated by the "coap" scheme 1391 and the TCP CoAP default port. The system is secured only by keeping 1392 attackers from being able to send or receive packets from the network 1393 with the CoAP nodes. 1395 "PreSharedKey", "RawPublicKey", or "Certificate" is mandatory-to- 1396 implement for the TLS binding depending on the credential type used 1397 with the device. These security modes are achieved using TLS and are 1398 indicated by the "coaps" scheme and TLS-secured CoAP default port. 1400 8.2. TLS usage for CoAP over WebSockets 1402 A CoAP client requesting a resource identified by a "coaps" URI 1403 negotiates a secure WebSocket connection to a WebSocket server 1404 endpoint with a "wss" URI. This is described in Section 7.4. 1406 The client MUST perform a TLS handshake after opening the connection 1407 to the server. The guidance in Section 4.1 of [RFC6455] applies. 1408 When a CoAP server exposes resources identified by a "coaps" URI, the 1409 guidance in Section 4.4 of [RFC7925] applies towards mandatory-to- 1410 implement TLS functionality for certificates. For the server-side 1411 requirements in accepting incoming connections over a HTTPS (HTTP- 1412 over-TLS) port, the guidance in Section 4.2 of [RFC6455] applies. 1414 Note that this formally inherits the mandatory to implement cipher 1415 suites defined in [RFC5246]. However, modern usually browsers 1416 implement more recent cipher suites that then are automatically 1417 picked up via the JavaScript WebSocket API. WebSocket Servers that 1418 provide Secure CoAP over WebSockets for the browser use case will 1419 need to follow the browser preferences and MUST follow [RFC7525]. 1421 9. Security Considerations 1423 The security considerations of [RFC7252] apply. For CoAP over 1424 WebSockets and CoAP over TLS-secured WebSockets, the security 1425 considerations of [RFC6455] also apply. 1427 9.1. Signaling Messages 1429 The guidance given by an Alternative-Address Option cannot be 1430 followed blindly. In particular, a peer MUST NOT assume that a 1431 successful connection to the Alternative-Address inherits all the 1432 security properties of the current connection. 1434 10. IANA Considerations 1436 10.1. Signaling Codes 1438 IANA is requested to create a third sub-registry for values of the 1439 Code field in the CoAP header (Section 12.1 of [RFC7252]). The name 1440 of this sub-registry is "CoAP Signaling Codes". 1442 Each entry in the sub-registry must include the Signaling Code in the 1443 range 7.00-7.31, its name, and a reference to its documentation. 1445 Initial entries in this sub-registry are as follows: 1447 +------+---------+-----------+ 1448 | Code | Name | Reference | 1449 +------+---------+-----------+ 1450 | 7.01 | CSM | [RFCthis] | 1451 | | | | 1452 | 7.02 | Ping | [RFCthis] | 1453 | | | | 1454 | 7.03 | Pong | [RFCthis] | 1455 | | | | 1456 | 7.04 | Release | [RFCthis] | 1457 | | | | 1458 | 7.05 | Abort | [RFCthis] | 1459 +------+---------+-----------+ 1461 Table 1: CoAP Signal Codes 1463 All other Signaling Codes are Unassigned. 1465 The IANA policy for future additions to this sub-registry is "IETF 1466 Review or IESG Approval" as described in [RFC5226]. 1468 10.2. CoAP Signaling Option Numbers Registry 1470 IANA is requested to create a sub-registry for Options Numbers used 1471 in CoAP signaling options within the "CoRE Parameters" registry. The 1472 name of this sub-registry is "CoAP Signaling Option Numbers". 1474 Each entry in the sub-registry must include one or more of the codes 1475 in the Signaling Codes subregistry (Section 10.1), the option number, 1476 the name of the option, and a reference to the option's 1477 documentation. 1479 Initial entries in this sub-registry are as follows: 1481 +------------+--------+---------------------+-----------+ 1482 | Applies to | Number | Name | Reference | 1483 +------------+--------+---------------------+-----------+ 1484 | 7.01 | 2 | Max-Message-Size | [RFCthis] | 1485 | | | | | 1486 | 7.01 | 4 | Block-wise-Transfer | [RFCthis] | 1487 | | | | | 1488 | 7.02, 7.03 | 2 | Custody | [RFCthis] | 1489 | | | | | 1490 | 7.04 | 2 | Alternative-Address | [RFCthis] | 1491 | | | | | 1492 | 7.04 | 4 | Hold-Off | [RFCthis] | 1493 | | | | | 1494 | 7.05 | 2 | Bad-CSM-Option | [RFCthis] | 1495 +------------+--------+---------------------+-----------+ 1497 Table 2: CoAP Signal Option Codes 1499 The IANA policy for future additions to this sub-registry is based on 1500 number ranges for the option numbers, analogous to the policy defined 1501 in Section 12.2 of [RFC7252]. 1503 The documentation for a Signaling Option Number should specify the 1504 semantics of an option with that number, including the following 1505 properties: 1507 o Whether the option is critical or elective, as determined by the 1508 Option Number. 1510 o Whether the option is repeatable. 1512 o The format and length of the option's value. 1514 o The base value for the option, if any. 1516 10.3. Service Name and Port Number Registration 1518 IANA is requested to assign the port number 5683 and the service name 1519 "coap", in accordance with [RFC6335]. 1521 Service Name. 1522 coap 1524 Transport Protocol. 1525 tcp 1527 Assignee. 1528 IESG 1530 Contact. 1531 IETF Chair 1533 Description. 1534 Constrained Application Protocol (CoAP) 1536 Reference. 1537 [RFCthis] 1539 Port Number. 1540 5683 1542 10.4. Secure Service Name and Port Number Registration 1544 IANA is requested to assign the port number 5684 and the service name 1545 "coaps+tcp", in accordance with [RFC6335]. The port number is 1546 requested also to address the exceptional case of TLS implementations 1547 that do not support the "Application-Layer Protocol Negotiation 1548 Extension" [RFC7301]. 1550 Service Name. 1551 coaps 1553 Transport Protocol. 1554 tcp 1556 Assignee. 1557 IESG 1559 Contact. 1560 IETF Chair 1562 Description. 1563 Constrained Application Protocol (CoAP) 1565 Reference. 1566 [RFC7301], [RFCthis] 1568 Port Number. 1569 5684 1571 10.5. Well-Known URI Suffix Registration 1573 IANA is requested to register the 'coap' well-known URI in the "Well- 1574 Known URIs" registry. This registration request complies with 1575 [RFC5785]: 1577 URI Suffix. 1579 coap 1581 Change controller. 1582 IETF 1584 Specification document(s). 1585 [RFCthis] 1587 Related information. 1588 None. 1590 10.6. ALPN Protocol Identifier 1592 IANA is requested to assign the following value in the registry 1593 "Application Layer Protocol Negotiation (ALPN) Protocol IDs" created 1594 by [RFC7301]. The "coap" string identifies CoAP when used over TLS. 1596 Protocol. 1597 CoAP 1599 Identification Sequence. 1600 0x63 0x6f 0x61 0x70 ("coap") 1602 Reference. 1603 [RFCthis] 1605 10.7. WebSocket Subprotocol Registration 1607 IANA is requested to register the WebSocket CoAP subprotocol under 1608 the "WebSocket Subprotocol Name Registry": 1610 Subprotocol Identifier. 1611 coap 1613 Subprotocol Common Name. 1614 Constrained Application Protocol (CoAP) 1616 Subprotocol Definition. 1617 [RFCthis] 1619 10.8. CoAP Option Numbers Registry 1621 IANA is requested to add [RFCthis] to the references for the 1622 following entries registered by [RFC7959] in the "CoAP Option 1623 Numbers" sub-registry defined by [RFC7252]: 1625 +--------+--------+---------------------+ 1626 | Number | Name | Reference | 1627 +--------+--------+---------------------+ 1628 | 23 | Block2 | RFC 7959, [RFCthis] | 1629 | | | | 1630 | 27 | Block1 | RFC 7959, [RFCthis] | 1631 +--------+--------+---------------------+ 1633 Table 3: CoAP Option Numbers 1635 11. References 1637 11.1. Normative References 1639 [I-D.bormann-hybi-ws-wk] 1640 Bormann, C., "Well-known URIs for the WebSocket Protocol", 1641 draft-bormann-hybi-ws-wk-00 (work in progress), May 2017. 1643 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 1644 RFC 793, DOI 10.17487/RFC0793, September 1981, 1645 . 1647 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1648 Requirement Levels", BCP 14, RFC 2119, 1649 DOI 10.17487/RFC2119, March 1997, 1650 . 1652 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1653 Resource Identifier (URI): Generic Syntax", STD 66, 1654 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1655 . 1657 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1658 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1659 DOI 10.17487/RFC5226, May 2008, 1660 . 1662 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1663 (TLS) Protocol Version 1.2", RFC 5246, 1664 DOI 10.17487/RFC5246, August 2008, 1665 . 1667 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1668 Uniform Resource Identifiers (URIs)", RFC 5785, 1669 DOI 10.17487/RFC5785, April 2010, 1670 . 1672 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 1673 Extensions: Extension Definitions", RFC 6066, 1674 DOI 10.17487/RFC6066, January 2011, 1675 . 1677 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 1678 RFC 6455, DOI 10.17487/RFC6455, December 2011, 1679 . 1681 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1682 Application Protocol (CoAP)", RFC 7252, 1683 DOI 10.17487/RFC7252, June 2014, 1684 . 1686 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 1687 "Transport Layer Security (TLS) Application-Layer Protocol 1688 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1689 July 2014, . 1691 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 1692 "Recommendations for Secure Use of Transport Layer 1693 Security (TLS) and Datagram Transport Layer Security 1694 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 1695 2015, . 1697 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1698 Application Protocol (CoAP)", RFC 7641, 1699 DOI 10.17487/RFC7641, September 2015, 1700 . 1702 [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer 1703 Security (TLS) / Datagram Transport Layer Security (DTLS) 1704 Profiles for the Internet of Things", RFC 7925, 1705 DOI 10.17487/RFC7925, July 2016, 1706 . 1708 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1709 the Constrained Application Protocol (CoAP)", RFC 7959, 1710 DOI 10.17487/RFC7959, August 2016, 1711 . 1713 11.2. Informative References 1715 [HomeGateway] 1716 Eggert, L., "An experimental study of home gateway 1717 characteristics", Proceedings of the 10th annual 1718 conference on Internet measurement , 2010. 1720 [I-D.ietf-core-cocoa] 1721 Bormann, C., Betzler, A., Gomez, C., and I. Demirkol, 1722 "CoAP Simple Congestion Control/Advanced", draft-ietf- 1723 core-cocoa-01 (work in progress), March 2017. 1725 [I-D.ietf-core-object-security] 1726 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1727 "Object Security of CoAP (OSCOAP)", draft-ietf-core- 1728 object-security-03 (work in progress), May 2017. 1730 [I-D.ietf-core-resource-directory] 1731 Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE 1732 Resource Directory", draft-ietf-core-resource-directory-10 1733 (work in progress), March 2017. 1735 [LWM2M] Open Mobile Alliance, "Lightweight Machine to Machine 1736 Technical Specification Version 1.0", February 2017, 1737 . 1741 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 1742 DOI 10.17487/RFC0768, August 1980, 1743 . 1745 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1746 Specifications: ABNF", STD 68, RFC 5234, 1747 DOI 10.17487/RFC5234, January 2008, 1748 . 1750 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 1751 Cheshire, "Internet Assigned Numbers Authority (IANA) 1752 Procedures for the Management of the Service Name and 1753 Transport Protocol Port Number Registry", BCP 165, 1754 RFC 6335, DOI 10.17487/RFC6335, August 2011, 1755 . 1757 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1758 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1759 January 2012, . 1761 [RFC6555] Wing, D. and A. Yourtchenko, "Happy Eyeballs: Success with 1762 Dual-Stack Hosts", RFC 6555, DOI 10.17487/RFC6555, April 1763 2012, . 1765 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1766 Protocol (HTTP/1.1): Message Syntax and Routing", 1767 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1768 . 1770 [SecurityChallenges] 1771 Polk, T. and S. Turner, "Security Challenges for the 1772 Internet of Things", Interconnecting Smart Objects with 1773 the Internet / IAB Workshop , February 2011, 1774 . 1777 Appendix A. Updates to RFC 7641 Observing Resources in the Constrained 1778 Application Protocol (CoAP) 1780 In this appendix, "client" and "server" refer to the CoAP client and 1781 CoAP server. 1783 A.1. Notifications and Reordering 1785 When using the Observe Option with CoAP over UDP, notifications from 1786 the server set the option value to an increasing sequence number for 1787 reordering detection on the client since messages can arrive in a 1788 different order than they were sent. This sequence number is not 1789 required for CoAP over reliable transports since the TCP protocol 1790 ensures reliable and ordered delivery of messages. The value of the 1791 Observe Option in 2.xx notifications MAY be empty on transmission and 1792 MUST be ignored on reception. 1794 A.2. Transmission and Acknowledgements 1796 For CoAP over UDP, server notifications to the client can be 1797 confirmable or non-confirmable. A confirmable message requires the 1798 client to either respond with an acknowledgement message or a reset 1799 message. An acknowledgement message indicates that the client is 1800 alive and wishes to receive further notifications. A reset message 1801 indicates that the client does not recognize the token which causes 1802 the server to remove the associated entry from the list of observers. 1804 Since TCP eliminates the need for the message layer to support 1805 reliability, CoAP over reliable transports does not support 1806 confirmable or non-confirmable message types. All notifications are 1807 delivered reliably to the client with positive acknowledgement of 1808 receipt occurring at the TCP level. If the client does not recognize 1809 the token in a notification, it MAY immediately abort the connection 1810 (see Section 5.6). 1812 A.3. Freshness 1814 For CoAP over UDP, if a client does not receive a notification for 1815 some time, it MAY send a new GET request with the same token as the 1816 original request to re-register its interest in a resource and verify 1817 that the server is still responsive. For CoAP over reliable 1818 transports, it is more efficient to check the health of the 1819 connection (and all its active observations) by sending a CoAP Ping 1820 Signaling message (Section 5.4) rather than individual requests to 1821 confirm active observations. 1823 A.4. Cancellation 1825 For CoAP over UDP, a client that is no longer interested in receiving 1826 notifications can "forget" the observation and respond to the next 1827 notification from the server with a reset message to cancel the 1828 observation. 1830 For CoAP over reliable transports, a client MUST explicitly 1831 deregister by issuing a GET request that has the Token field set to 1832 the token of the observation to be cancelled and includes an Observe 1833 Option with the value set to 1 (deregister). 1835 If the client observes one or more resources over a reliable 1836 transport, then the CoAP server (or intermediary in the role of the 1837 CoAP server) MUST remove all entries associated with the client 1838 endpoint from the lists of observers when the connection is either 1839 closed or times out. 1841 Appendix B. CoAP over WebSocket Examples 1843 This section gives examples for the first two configurations 1844 discussed in Section 4. 1846 An example of the process followed by a CoAP client to retrieve the 1847 representation of a resource identified by a "coap" URI might be as 1848 follows. Figure 20 below illustrates the WebSocket and CoAP messages 1849 exchanged in detail. 1851 1. The CoAP client obtains the URI , for example, from a resource representation 1853 that it retrieved previously. 1855 2. It establishes a WebSocket connection to the endpoint URI 1856 composed of the authority "example.org" and the well-known path 1857 "/.well-known/coap", . 1859 3. It sends a single-frame, masked, binary message containing a CoAP 1860 request. The request indicates the target resource with the Uri- 1861 Path ("sensors", "temperature") and Uri-Query ("u=Cel") options. 1863 4. It waits for the server to return a response. 1865 5. The CoAP client uses the connection for further requests, or the 1866 connection is closed. 1868 CoAP CoAP 1869 Client Server 1870 (WebSocket (WebSocket 1871 Client) Server) 1873 | | 1874 | | 1875 +=========>| GET /.well-known/coap HTTP/1.1 1876 | | Host: example.org 1877 | | Upgrade: websocket 1878 | | Connection: Upgrade 1879 | | Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 1880 | | Sec-WebSocket-Protocol: coap 1881 | | Sec-WebSocket-Version: 13 1882 | | 1883 |<=========+ HTTP/1.1 101 Switching Protocols 1884 | | Upgrade: websocket 1885 | | Connection: Upgrade 1886 | | Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 1887 | | Sec-WebSocket-Protocol: coap 1888 | | 1889 | | 1890 +--------->| Binary frame (opcode=%x2, FIN=1, MASK=1) 1891 | | +-------------------------+ 1892 | | | GET | 1893 | | | Token: 0x53 | 1894 | | | Uri-Path: "sensors" | 1895 | | | Uri-Path: "temperature" | 1896 | | | Uri-Query: "u=Cel" | 1897 | | +-------------------------+ 1898 | | 1899 |<---------+ Binary frame (opcode=%x2, FIN=1, MASK=0) 1900 | | +-------------------------+ 1901 | | | 2.05 Content | 1902 | | | Token: 0x53 | 1903 | | | Payload: "22.3 Cel" | 1904 | | +-------------------------+ 1905 : : 1906 : : 1907 | | 1908 +--------->| Close frame (opcode=%x8, FIN=1, MASK=1) 1909 | | 1910 |<---------+ Close frame (opcode=%x8, FIN=1, MASK=0) 1911 | | 1913 Figure 20: A CoAP client retrieves the representation of a resource 1914 identified by a "coap" URI over the WebSocket protocol 1916 Figure 21 shows how a CoAP client uses a CoAP forward proxy with a 1917 WebSocket endpoint to retrieve the representation of the resource 1918 "coap://[2001:db8::1]/". The use of the forward proxy and the 1919 address of the WebSocket endpoint are determined by the client from 1920 local configuration rules. The request URI is specified in the 1921 Proxy-Uri Option. Since the request URI uses the "coap" URI scheme, 1922 the proxy fulfills the request by issuing a Confirmable GET request 1923 over UDP to the CoAP server and returning the response over the 1924 WebSocket connection to the client. 1926 CoAP CoAP CoAP 1927 Client Proxy Server 1928 (WebSocket (WebSocket (UDP 1929 Client) Server) Endpoint) 1931 | | | 1932 +--------->| | Binary frame (opcode=%x2, FIN=1, MASK=1) 1933 | | | +------------------------------------+ 1934 | | | | GET | 1935 | | | | Token: 0x7d | 1936 | | | | Proxy-Uri: "coap://[2001:db8::1]/" | 1937 | | | +------------------------------------+ 1938 | | | 1939 | +--------->| CoAP message (Ver=1, T=Con, MID=0x8f54) 1940 | | | +------------------------------------+ 1941 | | | | GET | 1942 | | | | Token: 0x0a15 | 1943 | | | +------------------------------------+ 1944 | | | 1945 | |<---------+ CoAP message (Ver=1, T=Ack, MID=0x8f54) 1946 | | | +------------------------------------+ 1947 | | | | 2.05 Content | 1948 | | | | Token: 0x0a15 | 1949 | | | | Payload: "ready" | 1950 | | | +------------------------------------+ 1951 | | | 1952 |<---------+ | Binary frame (opcode=%x2, FIN=1, MASK=0) 1953 | | | +------------------------------------+ 1954 | | | | 2.05 Content | 1955 | | | | Token: 0x7d | 1956 | | | | Payload: "ready" | 1957 | | | +------------------------------------+ 1958 | | | 1960 Figure 21: A CoAP client retrieves the representation of a resource 1961 identified by a "coap" URI via a WebSocket-enabled CoAP proxy 1963 Appendix C. Change Log 1965 The RFC Editor is requested to remove this section at publication. 1967 C.1. Since draft-ietf-core-coap-tcp-tls-02 1969 Merged draft-savolainen-core-coap-websockets-07 Merged draft-bormann- 1970 core-block-bert-01 Merged draft-bormann-core-coap-sig-02 1972 C.2. Since draft-ietf-core-coap-tcp-tls-03 1974 Editorial updates 1976 Added mandatory exchange of Capabilities and Settings messages after 1977 connecting 1979 Added support for coaps+tcp port 5684 and more details on 1980 Application-Layer Protocol Negotiation (ALPN) 1982 Added guidance on CoAP Signaling Ping-Pong versus WebSocket Ping-Pong 1984 Updated references and requirements for TLS security considerations 1986 C.3. Since draft-ietf-core-coap-tcp-tls-04 1988 Updated references 1990 Added Appendix: Updates to RFC7641 Observing Resources in the 1991 Constrained Application Protocol (CoAP) 1993 Updated Capability and Settings Message (CSM) exchange in the Opening 1994 Handshake to allow initiator to send messages before receiving 1995 acceptor CSM 1997 C.4. Since draft-ietf-core-coap-tcp-tls-05 1999 Addressed feedback from Working Group Last Call 2001 Added Securing CoAP section and informative reference to OSCOAP 2003 Removed the Server-Name and Bad-Server-Name Options 2005 Clarified the Capability and Settings Message (CSM) exchange 2007 Updated Pong response requirements 2009 Added Connection Initiator and Connection Acceptor terminology where 2010 appropriate 2011 Updated LWM2M 1.0 informative reference 2013 C.5. Since draft-ietf-core-coap-tcp-tls-06 2015 Addressed feedback from second Working Group Last Call 2017 C.6. Since draft-ietf-core-coap-tcp-tls-07 2019 Addressed feedback from IETF Last Call 2021 Addressed feedback from ARTART review 2023 Addressed feedback from GENART review 2025 Addressed feedback from TSVART review 2027 Added fragment identifiers to URI schemes 2029 Added "Updates RFC7959" for BERT 2031 Added "Updates RFC6455" to extend well-known URI mechanism to ws and 2032 wss 2034 Clarified well-known URI mechanism use for all URI schemes 2036 Changed NoSec to optional-to-implement 2038 C.7. Since draft-ietf-core-coap-tcp-tls-08 2040 Reverted "Updates RFC6455" to extend well-known URI mechanism to ws 2041 and wss; point to [I-D.bormann-hybi-ws-wk] instead 2043 Don't use port 443 as the default port for coaps+tcp 2045 Remove coap+tt and coaps+tt URI schemes (where tt is tcp or ws); map 2046 everything to coap/coaps 2048 Acknowledgements 2050 We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier 2051 Delaby, Esko Dijk, Christian Groves, Nadir Javed, Michael Koster, 2052 Matthias Kovatsch, Achim Kraus, David Navarro, Szymon Sasin, Goran 2053 Selander, Zach Shelby, Andrew Summers, Julien Vermillard, and Gengyu 2054 Wei for their feedback. Last-call reviews from Mark Nottingham and 2055 Yoshifumi Nishida as well as several IESG reviewers provided 2056 extensive comments; from the IESG, we would like to specifically call 2057 out Adam Roach, Ben Campbell, Eric Rescorla, Mirja Kuehlewind, and 2058 the responsible AD Alexey Melnikov. 2060 Contributors 2062 Matthias Kovatsch 2063 Siemens AG 2064 Otto-Hahn-Ring 6 2065 Munich D-81739 2067 Phone: +49-173-5288856 2068 EMail: matthias.kovatsch@siemens.com 2070 Teemu Savolainen 2071 Nokia Technologies 2072 Hatanpaan valtatie 30 2073 Tampere FI-33100 2074 Finland 2076 Email: teemu.savolainen@nokia.com 2078 Valik Solorzano Barboza 2079 Zebra Technologies 2080 820 W. Jackson Blvd. Suite 700 2081 Chicago 60607 2082 United States of America 2084 Phone: +1-847-634-6700 2085 Email: vsolorzanobarboza@zebra.com 2087 Authors' Addresses 2089 Carsten Bormann 2090 Universitaet Bremen TZI 2091 Postfach 330440 2092 Bremen D-28359 2093 Germany 2095 Phone: +49-421-218-63921 2096 Email: cabo@tzi.org 2097 Simon Lemay 2098 Zebra Technologies 2099 820 W. Jackson Blvd. Suite 700 2100 Chicago 60607 2101 United States of America 2103 Phone: +1-847-634-6700 2104 Email: slemay@zebra.com 2106 Hannes Tschofenig 2107 ARM Ltd. 2108 110 Fulbourn Rd 2109 Cambridge CB1 9NJ 2110 Great Britain 2112 Email: Hannes.tschofenig@gmx.net 2113 URI: http://www.tschofenig.priv.at 2115 Klaus Hartke 2116 Universitaet Bremen TZI 2117 Postfach 330440 2118 Bremen D-28359 2119 Germany 2121 Phone: +49-421-218-63905 2122 Email: hartke@tzi.org 2124 Bilhanan Silverajan 2125 Tampere University of Technology 2126 Korkeakoulunkatu 10 2127 Tampere FI-33720 2128 Finland 2130 Email: bilhanan.silverajan@tut.fi 2132 Brian Raymor (editor) 2133 Microsoft 2134 One Microsoft Way 2135 Redmond 98052 2136 United States of America 2138 Email: brian.raymor@microsoft.com