idnits 2.17.1 draft-ietf-core-coap-tcp-tls-10.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 : ---------------------------------------------------------------------------- -- 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 (October 30, 2017) is 2367 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 330, but not defined == Missing Reference: '------' is mentioned on line 330, but not defined == Missing Reference: 'RFCthis' is mentioned on line 1862, but not defined ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) == 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-06 -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) Summary: 5 errors (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CORE C. Bormann 3 Internet-Draft Universitaet Bremen TZI 4 Updates: 7641, 7959 (if approved) S. Lemay 5 Intended status: Standards Track Zebra Technologies 6 Expires: May 3, 2018 H. Tschofenig 7 ARM Ltd. 8 K. Hartke 9 Universitaet Bremen TZI 10 B. Silverajan 11 Tampere University of Technology 12 B. Raymor, Ed. 13 Microsoft 14 October 30, 2017 16 CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets 17 draft-ietf-core-coap-tcp-tls-10 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 and RFC 7959 to enable the use of larger messages over a 31 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 https://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 May 3, 2018. 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 (https://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 . . . . . . . . . . . . . . . . . 6 69 3. CoAP over TCP . . . . . . . . . . . . . . . . . . . . . . . . 7 70 3.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 7 71 3.2. Message Format . . . . . . . . . . . . . . . . . . . . . 8 72 3.3. Message Transmission . . . . . . . . . . . . . . . . . . 10 73 3.4. Connection Health . . . . . . . . . . . . . . . . . . . . 11 74 4. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . . 11 75 4.1. Opening Handshake . . . . . . . . . . . . . . . . . . . . 13 76 4.2. Message Format . . . . . . . . . . . . . . . . . . . . . 14 77 4.3. Message Transmission . . . . . . . . . . . . . . . . . . 15 78 4.4. Connection Health . . . . . . . . . . . . . . . . . . . . 15 79 5. Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . 15 80 5.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 16 81 5.2. Signaling Option Numbers . . . . . . . . . . . . . . . . 16 82 5.3. Capabilities and Settings Messages (CSM) . . . . . . . . 16 83 5.4. Ping and Pong Messages . . . . . . . . . . . . . . . . . 18 84 5.5. Release Messages . . . . . . . . . . . . . . . . . . . . 20 85 5.6. Abort Messages . . . . . . . . . . . . . . . . . . . . . 21 86 5.7. Signaling examples . . . . . . . . . . . . . . . . . . . 22 87 6. Block-wise Transfer and Reliable Transports . . . . . . . . . 22 88 6.1. Example: GET with BERT Blocks . . . . . . . . . . . . . . 24 89 6.2. Example: PUT with BERT Blocks . . . . . . . . . . . . . . 24 90 7. Observing Resources over Reliable Transports . . . . . . . . 25 91 7.1. Notifications and Reordering . . . . . . . . . . . . . . 25 92 7.2. Transmission and Acknowledgements . . . . . . . . . . . . 25 93 7.3. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 25 94 7.4. Cancellation . . . . . . . . . . . . . . . . . . . . . . 26 95 8. CoAP over Reliable Transport URIs . . . . . . . . . . . . . . 26 96 8.1. coap+tcp URI scheme . . . . . . . . . . . . . . . . . . . 27 97 8.2. coaps+tcp URI scheme . . . . . . . . . . . . . . . . . . 27 98 8.3. coap+ws URI scheme . . . . . . . . . . . . . . . . . . . 28 99 8.4. coaps+ws URI scheme . . . . . . . . . . . . . . . . . . . 29 100 8.5. Uri-Host and Uri-Port Options . . . . . . . . . . . . . . 30 101 8.6. Decomposing URIs into Options . . . . . . . . . . . . . . 30 102 8.7. Composing URIs from Options . . . . . . . . . . . . . . . 31 103 9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 32 104 9.1. TLS binding for CoAP over TCP . . . . . . . . . . . . . . 32 105 9.2. TLS usage for CoAP over WebSockets . . . . . . . . . . . 33 106 10. Security Considerations . . . . . . . . . . . . . . . . . . . 33 107 10.1. Signaling Messages . . . . . . . . . . . . . . . . . . . 34 108 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 109 11.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . 34 110 11.2. CoAP Signaling Option Numbers Registry . . . . . . . . . 34 111 11.3. Service Name and Port Number Registration . . . . . . . 36 112 11.4. Secure Service Name and Port Number Registration . . . . 36 113 11.5. URI Scheme Registration . . . . . . . . . . . . . . . . 37 114 11.6. Well-Known URI Suffix Registration . . . . . . . . . . . 39 115 11.7. ALPN Protocol Identifier . . . . . . . . . . . . . . . . 39 116 11.8. WebSocket Subprotocol Registration . . . . . . . . . . . 40 117 11.9. CoAP Option Numbers Registry . . . . . . . . . . . . . . 40 118 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 119 12.1. Normative References . . . . . . . . . . . . . . . . . . 40 120 12.2. Informative References . . . . . . . . . . . . . . . . . 42 121 Appendix A. CoAP over WebSocket Examples . . . . . . . . . . . . 44 122 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 47 123 B.1. Since draft-ietf-core-coap-tcp-tls-02 . . . . . . . . . . 47 124 B.2. Since draft-ietf-core-coap-tcp-tls-03 . . . . . . . . . . 47 125 B.3. Since draft-ietf-core-coap-tcp-tls-04 . . . . . . . . . . 47 126 B.4. Since draft-ietf-core-coap-tcp-tls-05 . . . . . . . . . . 47 127 B.5. Since draft-ietf-core-coap-tcp-tls-06 . . . . . . . . . . 48 128 B.6. Since draft-ietf-core-coap-tcp-tls-07 . . . . . . . . . . 48 129 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 48 130 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 48 131 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 49 133 1. Introduction 135 The Constrained Application Protocol (CoAP) [RFC7252] was designed 136 for Internet of Things (IoT) deployments, assuming that UDP [RFC0768] 137 can be used unimpeded, as can the Datagram Transport Layer Security 138 protocol (DTLS [RFC6347]) over UDP. The use of CoAP over UDP is 139 focused on simplicity, has a low code footprint, and a small over- 140 the-wire message size. 142 The primary reason for introducing CoAP over TCP [RFC0793] and TLS 143 [RFC5246] is that some networks do not forward UDP packets. Complete 144 blocking of UDP happens in between about 2% and 4% of terrestrial 145 access networks, according to [EK2016]. UDP impairment is especially 146 concentrated in enterprise networks and networks in geographic 147 regions with otherwise challenged connectivity. Some networks also 148 rate-limit UDP traffic, as reported in [BK2015] and deployment 149 investigations related to the standardization of QUIC revealed 150 numbers around 0.3 % [SW2016]. 152 The introduction of CoAP over TCP also leads to some additional 153 effects that may be desirable in a specific deployment: 155 o Where NATs are present along the communication path, CoAP over TCP 156 leads to different NAT traversal behavior than CoAP over UDP. 157 NATs often calculate expiration timers based on the transport 158 layer protocol being used by application protocols. Many NATs 159 maintain TCP-based NAT bindings for longer periods based on the 160 assumption that a transport layer protocol, such as TCP, offers 161 additional information about the session lifecycle. UDP, on the 162 other hand, does not provide such information to a NAT and 163 timeouts tend to be much shorter [HomeGateway]. According to 164 [HomeGateway] the mean for TCP and UDP NAT binding timeouts is 386 165 minutes (TCP) and 160 seconds (UDP). Shorter timeout values 166 require keepalive messages to be sent more frequently. Hence, the 167 use of CoAP over TCP requires less frequent transmission of keep- 168 alive messages. 170 o TCP utilizes more sophisticated congestion and flow control 171 mechanisms than the default mechanisms provided by CoAP over UDP, 172 which is useful for the transfer of larger payloads. (Work is, 173 however, ongoing to add advanced congestion control to CoAP over 174 UDP as well, see [I-D.ietf-core-cocoa].) 176 Note that the use of CoAP over UDP (and CoAP over DTLS over UDP) is 177 still the recommended transport for use in constrained node networks, 178 particularly when used in concert with blockwise transfer. CoAP over 179 TCP is applicable for those cases where the networking infrastructure 180 leaves no other choice. The use of CoAP over TCP leads to a larger 181 code size, more roundtrips, increased RAM requirements and larger 182 packet sizes. Developers implementing CoAP over TCP are encouraged 183 to consult [I-D.gomez-lwig-tcp-constrained-node-networks] for 184 guidance on low-footprint TCP implementations for IoT devices. 186 Standards based on CoAP such as Lightweight Machine to Machine 187 [LWM2M] currently use CoAP over UDP as a transport; adding support 188 for CoAP over TCP enables them to address the issues above for 189 specific deployments and to protect investments in existing CoAP 190 implementations and deployments. 192 Although HTTP/2 could also potentially address the need for 193 enterprise firewall traversal, there would be additional costs and 194 delays introduced by such a transition from CoAP to HTTP/2. 195 Currently, there are also fewer HTTP/2 implementations available for 196 constrained devices in comparison to CoAP. Since CoAP also support 197 group communication using IP layer multicast and unreliable 198 communication IoT devices would have to support HTTP/2 in addition to 199 CoAP. 201 Furthermore, CoAP may be integrated into a Web environment where the 202 front-end uses CoAP over UDP from IoT devices to a cloud 203 infrastructure and then CoAP over TCP between the back-end services. 204 A TCP-to-UDP gateway can be used at the cloud boundary to communicate 205 with the UDP-based IoT device. 207 Finally, CoAP applications running inside a web browser may be 208 without access to connectivity other than HTTP. In this case, the 209 WebSocket protocol [RFC6455] may be used to transport CoAP requests 210 and responses, as opposed to cross-proxying them via HTTP to an HTTP- 211 to-CoAP cross-proxy. This preserves the functionality of CoAP 212 without translation, in particular the Observe mechanism [RFC7641]. 214 To address the above-mentioned deployment requirements, this document 215 defines how to transport CoAP over TCP, CoAP over TLS, and CoAP over 216 WebSockets. For these cases, the reliability offered by the 217 transport protocol subsumes the reliability functions of the message 218 layer used for CoAP over UDP. (Note that both for a reliable 219 transport and the CoAP over UDP message layer, the reliability 220 offered is per transport hop: where proxies -- see Sections 5.7 and 221 10 of [RFC7252] -- are involved, that layer's reliability function 222 does not extend end-to-end.) Figure 1 illustrates the layering: 224 +--------------------------------+ 225 | Application | 226 +--------------------------------+ 227 +--------------------------------+ 228 | Requests/Responses/Signaling | CoAP (RFC 7252) / This Document 229 |--------------------------------| 230 | Message Framing | This Document 231 +--------------------------------+ 232 | Reliable Transport | 233 +--------------------------------+ 235 Figure 1: Layering of CoAP over Reliable Transports 237 This document specifies how to access resources using CoAP requests 238 and responses over the TCP, TLS and WebSocket protocols. This allows 239 connectivity-limited applications to obtain end-to-end CoAP 240 connectivity either by communicating CoAP directly with a CoAP server 241 accessible over a TCP, TLS or WebSocket connection or via a CoAP 242 intermediary that proxies CoAP requests and responses between 243 different transports, such as between WebSockets and UDP. 245 Section 7 updates the "Observing Resources in the Constrained 246 Application Protocol" [RFC7641] specification for use with CoAP over 247 reliable transports. [RFC7641] is an extension to the CoAP protocol 248 that enables CoAP clients to "observe" a resource on a CoAP server. 249 (The CoAP client retrieves a representation of a resource and 250 registers to be notified by the CoAP server when the representation 251 is updated.) 253 2. Conventions and Terminology 255 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 256 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 257 "OPTIONAL" in this document are to be interpreted as described in 258 [RFC2119]. 260 This document assumes that readers are familiar with the terms and 261 concepts that are used in [RFC6455], [RFC7252], [RFC7641], and 262 [RFC7959]. 264 The term "reliable transport" is used only to refer to transport 265 protocols, such as TCP, which provide reliable and ordered delivery 266 of a byte-stream. 268 Block-wise Extension for Reliable Transport (BERT): 269 BERT extends [RFC7959] to enable the use of larger messages over a 270 reliable transport. 272 BERT Option: 273 A Block1 or Block2 option that includes an SZX value of 7. 275 BERT Block: 276 The payload of a CoAP message that is affected by a BERT Option in 277 descriptive usage (see Section 2.1 of [RFC7959]). 279 Connection Initiator: 280 The peer that opens a reliable byte stream connection, i.e., the 281 TCP active opener, TLS client, or WebSocket client. 283 Connection Acceptor: 284 The peer that accepts the reliable byte stream connection opened 285 by the other peer, i.e., the TCP passive opener, TLS server, or 286 WebSocket server. 288 3. CoAP over TCP 290 The request/response interaction model of CoAP over TCP is the same 291 as CoAP over UDP. The primary differences are in the message layer. 292 The message layer of CoAP over UDP supports optional reliability by 293 defining four types of messages: Confirmable, Non-confirmable, 294 Acknowledgement, and Reset. In addition, messages include a Message 295 ID to relate Acknowledgments to Confirmable messages and to detect 296 duplicate messages. 298 The management of the connections is left to the application, i.e., 299 the present specification does not describe how an application 300 decides to open a connection or to re-open another one in the 301 presence of failures (or what it would deem to be a failure, see also 302 Section 5.4). In particular, the Connection Initiator need not be 303 the client of the first request placed on the connection. 305 3.1. Messaging Model 307 Conceptually, CoAP over TCP replaces most of the message layer of 308 CoAP over UDP with a framing mechanism on top of the byte-stream 309 provided by TCP/TLS, conveying the length information for each 310 message that on datagram transports is provided by the UDP/DTLS 311 datagram layer. 313 TCP ensures reliable message transmission, so the message layer of 314 CoAP over TCP is not required to support acknowledgements or to 315 detect duplicate messages. As a result, both the Type and Message ID 316 fields are no longer required and are removed from the CoAP over TCP 317 message format. 319 Figure 2 illustrates the difference between CoAP over UDP and CoAP 320 over reliable transport. The removed Type and Message ID fields are 321 indicated by dashes. 323 CoAP Client CoAP Server CoAP Client CoAP Server 324 | | | | 325 | CON [0xbc90] | | (-------) [------] | 326 | GET /temperature | | GET /temperature | 327 | (Token 0x71) | | (Token 0x71) | 328 +------------------->| +------------------->| 329 | | | | 330 | ACK [0xbc90] | | (-------) [------] | 331 | 2.05 Content | | 2.05 Content | 332 | (Token 0x71) | | (Token 0x71) | 333 | "22.5 C" | | "22.5 C" | 334 |<-------------------+ |<-------------------+ 335 | | | | 337 CoAP over UDP CoAP over reliable 338 transport 340 Figure 2: Comparison between CoAP over unreliable and reliable 341 transport 343 3.2. Message Format 345 The CoAP message format defined in [RFC7252], as shown in Figure 3, 346 relies on the datagram transport (UDP, or DTLS over UDP) for keeping 347 the individual messages separate and for providing length 348 information. 350 0 1 2 3 351 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 352 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 353 |Ver| T | TKL | Code | Message ID | 354 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 355 | Token (if any, TKL bytes) ... 356 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 357 | Options (if any) ... 358 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 359 |1 1 1 1 1 1 1 1| Payload (if any) ... 360 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 362 Figure 3: RFC 7252 defined CoAP Message Format 364 The CoAP over TCP message format is very similar to the format 365 specified for CoAP over UDP. The differences are as follows: 367 o Since the underlying TCP connection provides retransmissions and 368 deduplication, there is no need for the reliability mechanisms 369 provided by CoAP over UDP. The Type (T) and Message ID fields in 370 the CoAP message header are elided. 372 o The Version (Vers) field is elided as well. In contrast to the 373 message format of CoAP over UDP, the message format for CoAP over 374 TCP does not include a version number. CoAP is defined in 375 [RFC7252] with a version number of 1. At this time, there is no 376 known reason to support version numbers different from 1. If 377 version negotiation needs to be addressed in the future, then 378 Capabilities and Settings Messages (CSM see Section 5.3) have been 379 specifically designed to enable such a potential feature. 381 o In a stream oriented transport protocol such as TCP, a form of 382 message delimitation is needed. For this purpose, CoAP over TCP 383 introduces a length field with variable size. Figure 4 shows the 384 adjusted CoAP message format with a modified structure for the 385 fixed header (first 4 bytes of the CoAP over UDP header), which 386 includes the length information of variable size. 388 0 1 2 3 389 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 390 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 391 | Len | TKL | Extended Length (if any, as chosen by Len) ... 392 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 393 | Code | Token (if any, TKL bytes) ... 394 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 395 | Options (if any) ... 396 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 397 |1 1 1 1 1 1 1 1| Payload (if any) ... 398 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 400 Figure 4: CoAP frame for reliable transports 402 Length (Len): 4-bit unsigned integer. A value between 0 and 12 403 inclusive indicates the length of the message in bytes starting 404 with the first bit of the Options field. Three values are 405 reserved for special constructs: 407 13: An 8-bit unsigned integer (Extended Length) follows the 408 initial byte and indicates the length of options/payload minus 409 13. 411 14: A 16-bit unsigned integer (Extended Length) in network byte 412 order follows the initial byte and indicates the length of 413 options/payload minus 269. 415 15: A 32-bit unsigned integer (Extended Length) in network byte 416 order follows the initial byte and indicates the length of 417 options/payload minus 65805. 419 The encoding of the Length field is modeled after the Option Length 420 field of the CoAP Options (see Section 3.1 of [RFC7252]). 422 For simplicity, a Payload Marker (0xFF) is shown in Figure 4; the 423 Payload Marker indicates the start of the optional payload and is 424 absent for zero-length payloads (see Section 3 of [RFC7252]). (If 425 present, the Payload Marker is included in the message length, which 426 counts from the start of the Options field to the end of the Payload 427 field.) 429 For example: A CoAP message just containing a 2.03 code with the 430 token 7f and no options or payload is encoded as shown in Figure 5. 432 0 1 2 433 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 434 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 435 | 0x01 | 0x43 | 0x7f | 436 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 438 Len = 0 ------> 0x01 439 TKL = 1 ___/ 440 Code = 2.03 --> 0x43 441 Token = 0x7f 443 Figure 5: CoAP message with no options or payload 445 The semantics of the other CoAP header fields are left unchanged. 447 3.3. Message Transmission 449 Once a connection is established, each endpoint MUST send a 450 Capabilities and Settings message (CSM see Section 5.3) as their 451 first message on the connection. This message establishes the 452 initial settings and capabilities for the endpoint, such as maximum 453 message size or support for block-wise transfers. The absence of 454 options in the CSM indicates that base values are assumed. 456 To avoid a deadlock, the Connection Initiator MUST NOT wait for the 457 Connection Acceptor to send its initial CSM message before sending 458 its own initial CSM message. Conversely, the Connection Acceptor MAY 459 wait for the Connection Initiator to send its initial CSM message 460 before sending its own initial CSM message. 462 To avoid unnecessary latency, a Connection Initiator MAY send 463 additional messages after its initial CSM without waiting to receive 464 the Connection Acceptor's CSM; however, it is important to note that 465 the Connection Acceptor's CSM might indicate capabilities that impact 466 how the initiator is expected to communicate with the acceptor. For 467 example, the acceptor CSM could indicate a Max-Message-Size option 468 (see Section 5.3.1) that is smaller than the base value (1152) in 469 order to limit both buffering requirements and head-of-line blocking. 471 Endpoints MUST treat a missing or invalid CSM as a connection error 472 and abort the connection (see Section 5.6). 474 CoAP requests and responses are exchanged asynchronously over the 475 TCP/TLS connection. A CoAP client can send multiple requests without 476 waiting for a response and the CoAP server can return responses in 477 any order. Responses MUST be returned over the same connection as 478 the originating request. Concurrent requests are differentiated by 479 their Token, which is scoped locally to the connection. 481 The connection is bi-directional, so requests can be sent both by the 482 entity that established the connection (Connection Initiator) and the 483 remote host (Connection Acceptor). If one side does not implement a 484 CoAP server, an error response MUST be returned for all CoAP requests 485 from the other side. The simplest approach is to always return 5.01 486 (Not Implemented). A more elaborate mock server could also return 487 4.xx responses such as 4.04 (Not Found) or 4.02 (Bad Option) where 488 appropriate. 490 Retransmission and deduplication of messages is provided by the TCP 491 protocol. 493 3.4. Connection Health 495 Empty messages (Code 0.00) can always be sent and MUST be ignored by 496 the recipient. This provides a basic keep-alive function that can 497 refresh NAT bindings. 499 If a CoAP client does not receive any response for some time after 500 sending a CoAP request (or, similarly, when a client observes a 501 resource and it does not receive any notification for some time), it 502 can send a CoAP Ping Signaling message (see Section 5.4) to test the 503 connection and verify that the CoAP server is responsive. 505 When the underlying TCP connection is closed or reset, the signaling 506 state and any observation state (see Section 7.4) associated with the 507 reliable connection are removed. In flight messages may or may not 508 be lost. 510 4. CoAP over WebSockets 512 CoAP over WebSockets is intentionally similar to CoAP over TCP; 513 therefore, this section only specifies the differences between the 514 transports. 516 CoAP over WebSockets can be used in a number of configurations. The 517 most basic configuration is a CoAP client retrieving or updating a 518 CoAP resource located on a CoAP server that exposes a WebSocket 519 endpoint (see Figure 6). The CoAP client acts as the WebSocket 520 client, establishes a WebSocket connection, and sends a CoAP request, 521 to which the CoAP server returns a CoAP response. The WebSocket 522 connection can be used for any number of requests. 524 ___________ ___________ 525 | | | | 526 | _|___ requests ___|_ | 527 | CoAP / \ \ -------------> / / \ CoAP | 528 | Client \__/__/ <------------- \__\__/ Server | 529 | | responses | | 530 |___________| |___________| 531 WebSocket =============> WebSocket 532 Client Connection Server 534 Figure 6: CoAP Client (WebSocket client) accesses CoAP Server 535 (WebSocket server) 537 The challenge with this configuration is how to identify a resource 538 in the namespace of the CoAP server. When the WebSocket protocol is 539 used by a dedicated client directly (i.e., not from a web page 540 through a web browser), the client can connect to any WebSocket 541 endpoint. Section 8.3 and Section 8.4 define new URI schemes that 542 enable the client to identify both a WebSocket endpoint and the path 543 and query of the CoAP resource within that endpoint. 545 Another possible configuration is to set up a CoAP forward proxy at 546 the WebSocket endpoint. Depending on what transports are available 547 to the proxy, it could forward the request to a CoAP server with a 548 CoAP UDP endpoint (Figure 7), an SMS endpoint (a.k.a. mobile phone), 549 or even another WebSocket endpoint. The CoAP client specifies the 550 resource to be updated or retrieved in the Proxy-Uri Option. 552 ___________ ___________ ___________ 553 | | | | | | 554 | _|___ ___|_ _|___ ___|_ | 555 | CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP | 556 | Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server | 557 | | | | | | 558 |___________| |___________| |___________| 559 WebSocket ===> WebSocket UDP UDP 560 Client Server Client Server 562 Figure 7: CoAP Client (WebSocket client) accesses CoAP Server (UDP 563 server) via a CoAP proxy (WebSocket server/UDP client) 565 A third possible configuration is a CoAP server running inside a web 566 browser (Figure 8). The web browser initially connects to a 567 WebSocket endpoint and is then reachable through the WebSocket 568 server. When no connection exists, the CoAP server is unreachable. 569 Because the WebSocket server is the only way to reach the CoAP 570 server, the CoAP proxy should be a reverse-proxy. 572 ___________ ___________ ___________ 573 | | | | | | 574 | _|___ ___|_ _|___ ___|_ | 575 | CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP | 576 | Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server | 577 | | | | | | 578 |___________| |___________| |___________| 579 UDP UDP WebSocket <=== WebSocket 580 Client Server Server Client 582 Figure 8: CoAP Client (UDP client) accesses CoAP Server (WebSocket 583 client) via a CoAP proxy (UDP server/WebSocket server) 585 Further configurations are possible, including those where a 586 WebSocket connection is established through an HTTP proxy. 588 4.1. Opening Handshake 590 Before CoAP requests and responses are exchanged, a WebSocket 591 connection is established as defined in Section 4 of [RFC6455]. 592 Figure 9 shows an example. 594 The WebSocket client MUST include the subprotocol name "coap" in the 595 list of protocols, which indicates support for the protocol defined 596 in this document. 598 The WebSocket client includes the hostname of the WebSocket server in 599 the Host header field of its handshake as per [RFC6455]. The Host 600 header field also indicates the default value of the Uri-Host Option 601 in requests from the WebSocket client to the WebSocket server. 603 GET /.well-known/coap HTTP/1.1 604 Host: example.org 605 Upgrade: websocket 606 Connection: Upgrade 607 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 608 Sec-WebSocket-Protocol: coap 609 Sec-WebSocket-Version: 13 611 HTTP/1.1 101 Switching Protocols 612 Upgrade: websocket 613 Connection: Upgrade 614 Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 615 Sec-WebSocket-Protocol: coap 617 Figure 9: Example of an Opening Handshake 619 4.2. Message Format 621 Once a WebSocket connection is established, CoAP requests and 622 responses can be exchanged as WebSocket messages. Since CoAP uses a 623 binary message format, the messages are transmitted in binary data 624 frames as specified in Sections 5 and 6 of [RFC6455]. 626 The message format shown in Figure 10 is the same as the CoAP over 627 TCP message format (see Section 3.2) with one change. The Length 628 (Len) field MUST be set to zero because the WebSockets frame contains 629 the length. 631 0 1 2 3 632 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 633 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 634 | Len=0 | TKL | Code | Token (TKL bytes) ... 635 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 636 | Options (if any) ... 637 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 638 |1 1 1 1 1 1 1 1| Payload (if any) ... 639 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 641 Figure 10: CoAP Message Format over WebSockets 643 As with CoAP over TCP, the message format for CoAP over WebSockets 644 eliminates the Version field defined in CoAP over UDP. If CoAP 645 version negotiation is required in the future, CoAP over WebSockets 646 can address the requirement by the definition of a new subprotocol 647 identifier that is negotiated during the opening handshake. 649 Requests and response messages can be fragmented as specified in 650 Section 5.4 of [RFC6455], though typically they are sent unfragmented 651 as they tend to be small and fully buffered before transmission. The 652 WebSocket protocol does not provide means for multiplexing. If it is 653 not desirable for a large message to monopolize the connection, 654 requests and responses can be transferred in a block-wise fashion as 655 defined in [RFC7959]. 657 4.3. Message Transmission 659 As with CoAP over TCP, each endpoint MUST send a Capabilities and 660 Settings message (CSM see Section 5.3) as their first message on the 661 WebSocket connection. 663 CoAP requests and responses are exchanged asynchronously over the 664 WebSocket connection. A CoAP client can send multiple requests 665 without waiting for a response and the CoAP server can return 666 responses in any order. Responses MUST be returned over the same 667 connection as the originating request. Concurrent requests are 668 differentiated by their Token, which is scoped locally to the 669 connection. 671 The connection is bi-directional, so requests can be sent both by the 672 entity that established the connection and the remote host. 674 As with CoAP over TCP, retransmission and deduplication of messages 675 is provided by the WebSocket protocol. CoAP over WebSockets 676 therefore does not make a distinction between Confirmable or Non- 677 Confirmable messages, and does not provide Acknowledgement or Reset 678 messages. 680 4.4. Connection Health 682 As with CoAP over TCP, a CoAP client can test the health of the CoAP 683 over WebSocket connection by sending a CoAP Ping Signaling message 684 (Section 5.4). WebSocket Ping and unsolicited Pong frames 685 (Section 5.5 of [RFC6455]) SHOULD NOT be used to ensure that 686 redundant maintenance traffic is not transmitted. 688 5. Signaling 690 Signaling messages are specifically introduced only for CoAP over 691 reliable transports to allow peers to: 693 o Learn related characteristics, such as maximum message size for 694 the connection 696 o Shut down the connection in an orderly fashion 697 o Provide diagnostic information when terminating a connection in 698 response to a serious error condition 700 Signaling is a third basic kind of message in CoAP, after requests 701 and responses. Signaling messages share a common structure with the 702 existing CoAP messages. There is a code, a token, options, and an 703 optional payload. 705 (See Section 3 of [RFC7252] for the overall structure of the message 706 format, option format, and option value format.) 708 5.1. Signaling Codes 710 A code in the 7.00-7.31 range indicates a Signaling message. Values 711 in this range are assigned by the "CoAP Signaling Codes" sub-registry 712 (see Section 11.1). 714 For each message, there is a sender and a peer receiving the message. 716 Payloads in Signaling messages are diagnostic payloads as defined in 717 Section 5.5.2 of [RFC7252]), unless otherwise defined by a Signaling 718 message option. 720 5.2. Signaling Option Numbers 722 Option numbers for Signaling messages are specific to the message 723 code. They do not share the number space with CoAP options for 724 request/response messages or with Signaling messages using other 725 codes. 727 Option numbers are assigned by the "CoAP Signaling Option Numbers" 728 sub-registry (see Section 11.2). 730 Signaling options are elective or critical as defined in 731 Section 5.4.1 of [RFC7252]. If a Signaling option is critical and 732 not understood by the receiver, it MUST abort the connection (see 733 Section 5.6). If the option is understood but cannot be processed, 734 the option documents the behavior. 736 5.3. Capabilities and Settings Messages (CSM) 738 Capabilities and Settings messages (CSM) are used for two purposes: 740 o Each capability option indicates one capability of the sender to 741 the recipient. 743 o Each setting option indicates a setting that will be applied by 744 the sender. 746 One CSM MUST be sent by each endpoint at the start of the connection. 747 Further CSM MAY be sent at any other time by either endpoint over the 748 lifetime of the connection. 750 Both capability and setting options are cumulative. A CSM does not 751 invalidate a previously sent capability indication or setting even if 752 it is not repeated. A capability message without any option is a no- 753 operation (and can be used as such). An option that is sent might 754 override a previous value for the same option. The option defines 755 how to handle this case if needed. 757 Base values are listed below for CSM Options. These are the values 758 for the capability and setting before any Capabilities and Settings 759 messages send a modified value. 761 These are not default values for the option, as defined in 762 Section 5.4.4 in [RFC7252]. Default values apply on a per-message 763 basis and thus reset when the value is not present in a given 764 Capabilities and Settings message. 766 Capabilities and Settings messages are indicated by the 7.01 code 767 (CSM). 769 5.3.1. Max-Message-Size Capability Option 771 The sender can use the elective Max-Message-Size Option to indicate 772 the maximum size of a message in bytes that it can receive. The 773 message size indicated includes the entire message, starting from the 774 first byte of the message header and ending at the end of the message 775 payload (there is no relationship of the message size to the overall 776 request or response body size that may be achievable in block-wise 777 transfer.) 779 +---+---+---+---------+------------------+--------+--------+--------+ 780 | # | C | R | Applies | Name | Format | Length | Base | 781 | | | | to | | | | Value | 782 +---+---+---+---------+------------------+--------+--------+--------+ 783 | 2 | | | CSM | Max-Message-Size | uint | 0-4 | 1152 | 784 +---+---+---+---------+------------------+--------+--------+--------+ 786 C=Critical, R=Repeatable 788 As per Section 4.6 of [RFC7252], the base value (and the value used 789 when this option is not implemented) is 1152. 791 The active value of the Max-Message-Size Option is replaced each time 792 the option is sent with a modified value. Its starting value is its 793 base value. 795 5.3.2. Block-wise Transfer Capability Option 797 +---+---+---+---------+-----------------+--------+--------+---------+ 798 | # | C | R | Applies | Name | Format | Length | Base | 799 | | | | to | | | | Value | 800 +---+---+---+---------+-----------------+--------+--------+---------+ 801 | 4 | | | CSM | Block-wise | empty | 0 | (none) | 802 | | | | | Transfer | | | | 803 +---+---+---+---------+-----------------+--------+--------+---------+ 805 C=Critical, R=Repeatable 807 A sender can use the elective Block-wise Transfer Option to indicate 808 that it supports the block-wise transfer protocol [RFC7959]. 810 If the option is not given, the peer has no information about whether 811 block-wise transfers are supported by the sender or not. An 812 implementation wishing to offer block-wise transfers to its peer 813 therefore needs to indicate the Block-wise Transfer Option. 815 If a Max-Message-Size Option is indicated with a value that is 816 greater than 1152 (in the same or a different CSM message), the 817 Block-wise Transfer Option also indicates support for BERT (see 818 Section 6). Subsequently, if the Max-Message-Size Option is 819 indicated with a value equal to or less than 1152, BERT support is no 820 longer indicated. (Note that indication of BERT support obliges 821 neither peer to actually choose to make use of BERT.) 823 Implementation note: When indicating a value of the Max-Message-Size 824 option with an intention to enable BERT, the indicating 825 implementation may want to choose a BERT size message it wants to 826 encourage and add a delta for the header and any options that also 827 need to be included in the message. Section 4.6 of [RFC7252] adds 828 128 bytes to a maximum block size of 1024 to arrive at a default 829 message size of 1152. A BERT-enabled implementation may want to 830 indicate a BERT block size of 2048 or a higher multiple of 1024, and 831 at the same time be more generous for the size of header and options 832 added (say, 256 or 512). Adding 1024 or more however to the base 833 BERT block size may encourage the peer implementation to vary the 834 BERT block size based on the size of the options included, which can 835 be harder to establish interoperability for. 837 5.4. Ping and Pong Messages 839 In CoAP over reliable transports, Empty messages (Code 0.00) can 840 always be sent and MUST be ignored by the recipient. This provides a 841 basic keep-alive function. In contrast, Ping and Pong messages are a 842 bidirectional exchange. 844 Upon receipt of a Ping message, the receiver MUST return a Pong 845 message with an identical token in response. Unless the Ping carries 846 an option with delaying semantics such as the Custody Option, it 847 SHOULD respond as soon as practical. As with all Signaling messages, 848 the recipient of a Ping or Pong message MUST ignore elective options 849 it does not understand. 851 Ping and Pong messages are indicated by the 7.02 code (Ping) and the 852 7.03 code (Pong). 854 Note that, as with similar mechanisms defined in [RFC6455] and 855 [RFC7540], the present specification does not define any specific 856 maximum time that the sender of a Ping message has to allow waiting 857 for a Pong reply. Any limitations on the patience for this reply are 858 a matter of the application making use of these messages, as is any 859 approach to recover from a failure to respond in time. 861 5.4.1. Custody Option 863 +---+---+---+----------+----------------+--------+--------+---------+ 864 | # | C | R | Applies | Name | Format | Length | Base | 865 | | | | to | | | | Value | 866 +---+---+---+----------+----------------+--------+--------+---------+ 867 | 2 | | | Ping, | Custody | empty | 0 | (none) | 868 | | | | Pong | | | | | 869 +---+---+---+----------+----------------+--------+--------+---------+ 871 C=Critical, R=Repeatable 873 When responding to a Ping message, the receiver can include an 874 elective Custody Option in the Pong message. This option indicates 875 that the application has processed all the request/response messages 876 received prior to the Ping message on the current connection. (Note 877 that there is no definition of specific application semantics for 878 "processed", but there is an expectation that the receiver of a Pong 879 Message with a Custody Option should be able to free buffers based on 880 this indication.) 882 A sender can also include an elective Custody Option in a Ping 883 message to explicitly request the inclusion of an elective Custody 884 Option in the corresponding Pong message. In that case, the receiver 885 SHOULD delay its Pong message until it finishes processing all the 886 request/response messages received prior to the Ping message on the 887 current connection. 889 5.5. Release Messages 891 A Release message indicates that the sender does not want to continue 892 maintaining the connection and opts for an orderly shutdown. The 893 details are in the options. A diagnostic payload (see Section 5.5.2 894 of [RFC7252]) MAY be included. A peer will normally respond to a 895 Release message by closing the TCP/TLS connection. Messages may be 896 in flight or responses outstanding when the sender decides to send a 897 Release message. The peer responding to the Release message SHOULD 898 delay the closing of the connection until it has responded to all 899 requests received by it before the Release message. It also MAY wait 900 for the responses to its own requests. 902 Release messages are indicated by the 7.04 code (Release). 904 Release messages can indicate one or more reasons using elective 905 options. The following options are defined: 907 +---+---+---+---------+------------------+--------+--------+--------+ 908 | # | C | R | Applies | Name | Format | Length | Base | 909 | | | | to | | | | Value | 910 +---+---+---+---------+------------------+--------+--------+--------+ 911 | 2 | | x | Release | Alternative- | string | 1-255 | (none) | 912 | | | | | Address | | | | 913 +---+---+---+---------+------------------+--------+--------+--------+ 915 C=Critical, R=Repeatable 917 The elective Alternative-Address Option requests the peer to instead 918 open a connection of the same scheme as the present connection to the 919 alternative transport address given. Its value is in the form 920 "authority" as defined in Section 3.2 of [RFC3986]. (Existing state 921 related to the connection is not transferred from the present 922 connection to the new connection.) 924 The Alternative-Address Option is a repeatable option as defined in 925 Section 5.4.5 of [RFC7252]. When multiple occurrences of the option 926 are included, the peer can choose any of the alternative transport 927 addresses. 929 +---+---+---+---------+-----------------+--------+--------+---------+ 930 | # | C | R | Applies | Name | Format | Length | Base | 931 | | | | to | | | | Value | 932 +---+---+---+---------+-----------------+--------+--------+---------+ 933 | 4 | | | Release | Hold-Off | uint | 0-3 | (none) | 934 +---+---+---+---------+-----------------+--------+--------+---------+ 936 C=Critical, R=Repeatable 938 The elective Hold-Off Option indicates that the server is requesting 939 that the peer not reconnect to it for the number of seconds given in 940 the value. 942 5.6. Abort Messages 944 An Abort message indicates that the sender is unable to continue 945 maintaining the connection and cannot even wait for an orderly 946 release. The sender shuts down the connection immediately after the 947 abort (and may or may not wait for a Release or Abort message or 948 connection shutdown in the inverse direction). A diagnostic payload 949 (see Section 5.5.2 of [RFC7252]) SHOULD be included in the Abort 950 message. Messages may be in flight or responses outstanding when the 951 sender decides to send an Abort message. The general expectation is 952 that these will NOT be processed. 954 Abort messages are indicated by the 7.05 code (Abort). 956 Abort messages can indicate one or more reasons using elective 957 options. The following option is defined: 959 +---+---+---+---------+-----------------+--------+--------+---------+ 960 | # | C | R | Applies | Name | Format | Length | Base | 961 | | | | to | | | | Value | 962 +---+---+---+---------+-----------------+--------+--------+---------+ 963 | 2 | | | Abort | Bad-CSM-Option | uint | 0-2 | (none) | 964 +---+---+---+---------+-----------------+--------+--------+---------+ 966 C=Critical, R=Repeatable 968 The elective Bad-CSM-Option Option indicates that the sender is 969 unable to process the CSM option identified by its option number, 970 e.g. when it is critical and the option number is unknown by the 971 sender, or when there is parameter problem with the value of an 972 elective option. More detailed information SHOULD be included as a 973 diagnostic payload. 975 For CoAP over UDP, messages which contain syntax violations are 976 processed as message format errors. As described in Sections 4.2 and 977 4.3 of [RFC7252], such messages are rejected by sending a matching 978 Reset message and otherwise ignoring the message. 980 For CoAP over reliable transports, the recipient rejects such 981 messages by sending an Abort message and otherwise ignoring (not 982 processing) the message. No specific option has been defined for the 983 Abort message in this case, as the details are best left to a 984 diagnostic payload. 986 5.7. Signaling examples 988 An encoded example of a Ping message with a non-empty token is shown 989 in Figure 11. 991 0 1 2 992 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 993 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 994 | 0x01 | 0xe2 | 0x42 | 995 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 997 Len = 0 -------> 0x01 998 TKL = 1 ___/ 999 Code = 7.02 Ping --> 0xe2 1000 Token = 0x42 1002 Figure 11: Ping Message Example 1004 An encoded example of the corresponding Pong message is shown in 1005 Figure 12. 1007 0 1 2 1008 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 1009 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1010 | 0x01 | 0xe3 | 0x42 | 1011 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1013 Len = 0 -------> 0x01 1014 TKL = 1 ___/ 1015 Code = 7.03 Pong --> 0xe3 1016 Token = 0x42 1018 Figure 12: Pong Message Example 1020 6. Block-wise Transfer and Reliable Transports 1022 The message size restrictions defined in Section 4.6 of CoAP 1023 [RFC7252] to avoid IP fragmentation are not necessary when CoAP is 1024 used over a reliable transport. While this suggests that the Block- 1025 wise transfer protocol [RFC7959] is also no longer needed, it remains 1026 applicable for a number of cases: 1028 o large messages, such as firmware downloads, may cause undesired 1029 head-of-line blocking when a single TCP connection is used 1031 o a UDP-to-TCP gateway may simply not have the context to convert a 1032 message with a Block Option into the equivalent exchange without 1033 any use of a Block Option (it would need to convert the entire 1034 blockwise exchange from start to end into a single exchange) 1036 The 'Block-wise Extension for Reliable Transport (BERT)' extends the 1037 Block protocol to enable the use of larger messages over a reliable 1038 transport. 1040 The use of this new extension is signaled by sending Block1 or Block2 1041 Options with SZX == 7 (a "BERT option"). SZX == 7 is a reserved 1042 value in [RFC7959]. 1044 In control usage, a BERT option is interpreted in the same way as the 1045 equivalent Option with SZX == 6, except that it also indicates the 1046 capability to process BERT blocks. As with the basic Block protocol, 1047 the recipient of a CoAP request with a BERT option in control usage 1048 is allowed to respond with a different SZX value, e.g. to send a non- 1049 BERT block instead. 1051 In descriptive usage, a BERT Option is interpreted in the same way as 1052 the equivalent Option with SZX == 6, except that the payload is also 1053 allowed to contain multiple blocks. For non-final BERT blocks, the 1054 payload is always a multiple of 1024 bytes. For final BERT blocks, 1055 the payload is a multiple (possibly 0) of 1024 bytes plus a partial 1056 block of less than 1024 bytes. 1058 The recipient of a non-final BERT block (M=1) conceptually partitions 1059 the payload into a sequence of 1024-byte blocks and acts exactly as 1060 if it had received this sequence in conjunction with block numbers 1061 starting at, and sequentially increasing from, the block number given 1062 in the Block Option. In other words, the entire BERT block is 1063 positioned at the byte position that results from multiplying the 1064 block number with 1024. The position of further blocks to be 1065 transferred is indicated by incrementing the block number by the 1066 number of elements in this sequence (i.e., the size of the payload 1067 divided by 1024 bytes). 1069 As with SZX == 6, the recipient of a final BERT block (M=0) simply 1070 appends the payload at the byte position that is indicated by the 1071 block number multiplied with 1024. 1073 The following examples illustrate BERT options. A value of SZX == 7 1074 is labeled as "BERT" or as "BERT(nnn)" to indicate a payload of size 1075 nnn. 1077 In all these examples, a Block Option is decomposed to indicate the 1078 kind of Block Option (1 or 2) followed by a colon, the block number 1079 (NUM), more bit (M), and block size (2**(SZX+4)) separated by 1080 slashes. E.g., a Block2 Option value of 33 would be shown as 1081 2:2/0/32), or a Block1 Option value of 59 would be shown as 1082 1:3/1/128. 1084 6.1. Example: GET with BERT Blocks 1086 Figure 13 shows a GET request with a response that is split into 1087 three BERT blocks. The first response contains 3072 bytes of 1088 payload; the second, 5120; and the third, 4711. Note how the block 1089 number increments to move the position inside the response body 1090 forward. 1092 CoAP Client CoAP Server 1093 | | 1094 | GET, /status ------> | 1095 | | 1096 | <------ 2.05 Content, 2:0/1/BERT(3072) | 1097 | | 1098 | GET, /status, 2:3/0/BERT ------> | 1099 | | 1100 | <------ 2.05 Content, 2:3/1/BERT(5120) | 1101 | | 1102 | GET, /status, 2:8/0/BERT ------> | 1103 | | 1104 | <------ 2.05 Content, 2:8/0/BERT(4711) | 1106 Figure 13: GET with BERT blocks 1108 6.2. Example: PUT with BERT Blocks 1110 Figure 14 demonstrates a PUT exchange with BERT blocks. 1112 CoAP Client CoAP Server 1113 | | 1114 | PUT, /options, 1:0/1/BERT(8192) ------> | 1115 | | 1116 | <------ 2.31 Continue, 1:0/1/BERT | 1117 | | 1118 | PUT, /options, 1:8/1/BERT(16384) ------> | 1119 | | 1120 | <------ 2.31 Continue, 1:8/1/BERT | 1121 | | 1122 | PUT, /options, 1:24/0/BERT(5683) ------> | 1123 | | 1124 | <------ 2.04 Changed, 1:24/0/BERT | 1125 | | 1127 Figure 14: PUT with BERT blocks 1129 7. Observing Resources over Reliable Transports 1131 This section describes how the procedures defined in [RFC7641] for 1132 observing resources over CoAP are applied (and modified, as needed) 1133 for reliable transports. In this section, "client" and "server" 1134 refer to the CoAP client and CoAP server. 1136 7.1. Notifications and Reordering 1138 When using the Observe Option with CoAP over UDP, notifications from 1139 the server set the option value to an increasing sequence number for 1140 reordering detection on the client since messages can arrive in a 1141 different order than they were sent. This sequence number is not 1142 required for CoAP over reliable transports since the TCP protocol 1143 ensures reliable and ordered delivery of messages. The value of the 1144 Observe Option in 2.xx notifications MAY be empty on transmission and 1145 MUST be ignored on reception. 1147 Implementation note: This means that a proxy from a reordering 1148 transport to a reliable (in-order) transport (such as a UDP-to-TCP 1149 proxy) needs to process the Observe Option in notifications according 1150 to the rules in Section 3.4 of [RFC7641]. 1152 7.2. Transmission and Acknowledgements 1154 For CoAP over UDP, server notifications to the client can be 1155 confirmable or non-confirmable. A confirmable message requires the 1156 client to either respond with an acknowledgement message or a reset 1157 message. An acknowledgement message indicates that the client is 1158 alive and wishes to receive further notifications. A reset message 1159 indicates that the client does not recognize the token which causes 1160 the server to remove the associated entry from the list of observers. 1162 Since TCP eliminates the need for the message layer to support 1163 reliability, CoAP over reliable transports does not support 1164 confirmable or non-confirmable message types. All notifications are 1165 delivered reliably to the client with positive acknowledgement of 1166 receipt occurring at the TCP level. If the client does not recognize 1167 the token in a notification, it MAY immediately abort the connection 1168 (see Section 5.6). 1170 7.3. Freshness 1172 For CoAP over UDP, if a client does not receive a notification for 1173 some time, it MAY send a new GET request with the same token as the 1174 original request to re-register its interest in a resource and verify 1175 that the server is still responsive. For CoAP over reliable 1176 transports, it is more efficient to check the health of the 1177 connection (and all its active observations) by sending a single CoAP 1178 Ping Signaling message (Section 5.4) rather than individual requests 1179 to confirm each active observation. (Note that such a Ping/Pong only 1180 confirms a single hop: there is no obligation, and no expectation, of 1181 a proxy to react to a Ping by checking all its onward observations or 1182 all the connections, if any, underlying them. A proxy MAY maintain 1183 its own schedule for confirming the onward observations it relies on; 1184 it is however generally inadvisable for a proxy to generate a large 1185 number of outgoing checks based on a single incoming check.) 1187 7.4. Cancellation 1189 For CoAP over UDP, a client that is no longer interested in receiving 1190 notifications can "forget" the observation and respond to the next 1191 notification from the server with a reset message to cancel the 1192 observation. 1194 For CoAP over reliable transports, a client MUST explicitly 1195 deregister by issuing a GET request that has the Token field set to 1196 the token of the observation to be cancelled and includes an Observe 1197 Option with the value set to 1 (deregister). 1199 If the client observes one or more resources over a reliable 1200 transport, then the CoAP server (or intermediary in the role of the 1201 CoAP server) MUST remove all entries associated with the client 1202 endpoint from the lists of observers when the connection is either 1203 closed or times out. 1205 8. CoAP over Reliable Transport URIs 1207 CoAP over UDP [RFC7252] defines the "coap" and "coaps" URI schemes. 1208 This document introduces four additional URI schemes for identifying 1209 CoAP resources and providing a means of locating the resource: 1211 o the "coap+tcp" URI scheme for CoAP over TCP 1213 o the "coaps+tcp" URI scheme for CoAP over TCP secured by TLS 1215 o the "coap+ws" URI scheme for CoAP over WebSockets 1217 o the "coaps+ws" URI scheme for CoAP over WebSockets secured by TLS 1219 Resources made available via these schemes have no shared identity 1220 even if their resource identifiers indicate the same authority (the 1221 same host listening to the same TCP port). They are hosted in 1222 distinct namespaces because each URI scheme implies a distinct origin 1223 server. 1225 The syntax for the URI schemes in this section are specified using 1226 Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of 1227 "host", "port", "path-abempty", and "query" are adopted from 1228 [RFC3986]. 1230 Section 8 (Multicast CoAP) in [RFC7252] is not applicable to these 1231 schemes. 1233 As with the "coap" and "coaps" schemes defined in [RFC7252], all URI 1234 schemes defined in this section also support the path prefix "/.well- 1235 known/" defined by [RFC5785] for "well-known locations" in the 1236 namespace of a host. This enables discovery as per Section 7 of 1237 [RFC7252]. 1239 8.1. coap+tcp URI scheme 1241 The "coap+tcp" URI scheme identifies CoAP resources that are intended 1242 to be accessible using CoAP over TCP. 1244 coap-tcp-URI = "coap+tcp:" "//" host [ ":" port ] 1245 path-abempty [ "?" query ] 1247 The syntax defined in Section 6.1 of [RFC7252] applies to this URI 1248 scheme with the following changes: 1250 o The port subcomponent indicates the TCP port at which the CoAP 1251 Connection Acceptor is located. (If it is empty or not given, 1252 then the default port 5683 is assumed, as with UDP.) 1254 Encoding considerations: The scheme encoding conforms to the 1255 encoding rules established for URIs in [RFC3986]. 1257 Interoperability considerations: None. 1259 Security considerations: See Section 11.1 of [RFC7252]. 1261 8.2. coaps+tcp URI scheme 1263 The "coaps+tcp" URI scheme identifies CoAP resources that are 1264 intended to be accessible using CoAP over TCP secured with TLS. 1266 coaps-tcp-URI = "coaps+tcp:" "//" host [ ":" port ] 1267 path-abempty [ "?" query ] 1269 The syntax defined in Section 6.2 of [RFC7252] applies to this URI 1270 scheme, with the following changes: 1272 o The port subcomponent indicates the TCP port at which the TLS 1273 server for the CoAP Connection Acceptor is located. If it is 1274 empty or not given, then the default port 5684 is assumed. 1276 o If a TLS server does not support the Application-Layer Protocol 1277 Negotiation Extension (ALPN) [RFC7301] or wishes to accommodate 1278 TLS clients that do not support ALPN, it MAY offer a coaps+tcp 1279 endpoint on TCP port 5684. This endpoint MAY also be ALPN 1280 enabled. A TLS server MAY offer coaps+tcp endpoints on ports 1281 other than TCP port 5684, which MUST be ALPN enabled. 1283 o For TCP ports other than port 5684, the TLS client MUST use the 1284 ALPN extension to advertise the "coap" protocol identifier (see 1285 Section 11.7) in the list of protocols in its ClientHello. If the 1286 TCP server selects and returns the "coap" protocol identifier 1287 using the ALPN extension in its ServerHello, then the connection 1288 succeeds. If the TLS server either does not negotiate the ALPN 1289 extension or returns a no_application_protocol alert, the TLS 1290 client MUST close the connection. 1292 o For TCP port 5684, a TLS client MAY use the ALPN extension to 1293 advertise the "coap" protocol identifier in the list of protocols 1294 in its ClientHello. If the TLS server selects and returns the 1295 "coap" protocol identifier using the ALPN extension in its 1296 ServerHello, then the connection succeeds. If the TLS server 1297 returns a no_application_protocol alert, then the TLS client MUST 1298 close the connection. If the TLS server does not negotiate the 1299 ALPN extension, then coaps+tcp is implicitly selected. 1301 o For TCP port 5684, if the TLS client does not use the ALPN 1302 extension to negotiate the protocol, then coaps+tcp is implicitly 1303 selected. 1305 Encoding considerations: The scheme encoding conforms to the 1306 encoding rules established for URIs in [RFC3986]. 1308 Interoperability considerations: None. 1310 Security considerations: See Section 11.1 of [RFC7252]. 1312 8.3. coap+ws URI scheme 1314 The "coap+ws" URI scheme identifies CoAP resources that are intended 1315 to be accessible using CoAP over WebSockets. 1317 coap-ws-URI = "coap+ws:" "//" host [ ":" port ] 1318 path-abempty [ "?" query ] 1320 The port subcomponent is OPTIONAL. The default is port 80. 1322 The WebSocket endpoint is identified by a "ws" URI that is composed 1323 of the authority part of the "coap+ws" URI and the well-known path 1324 "/.well-known/coap" [RFC5785] [I-D.bormann-hybi-ws-wk]. The path and 1325 query parts of a "coap+ws" URI identify a resource within the 1326 specified endpoint which can be operated on by the methods defined by 1327 CoAP: 1329 coap+ws://example.org/sensors/temperature?u=Cel 1330 \______ ______/\___________ ___________/ 1331 \/ \/ 1332 Uri-Path: "sensors" 1333 ws://example.org/.well-known/coap Uri-Path: "temperature" 1334 Uri-Query: "u=Cel" 1336 Figure 15: The "coap+ws" URI Scheme 1338 Encoding considerations: The scheme encoding conforms to the 1339 encoding rules established for URIs in [RFC3986]. 1341 Interoperability considerations: None. 1343 Security considerations: See Section 11.1 of [RFC7252]. 1345 8.4. coaps+ws URI scheme 1347 The "coaps+ws" URI scheme identifies CoAP resources that are intended 1348 to be accessible using CoAP over WebSockets secured by TLS. 1350 coaps-ws-URI = "coaps+ws:" "//" host [ ":" port ] 1351 path-abempty [ "?" query ] 1353 The port subcomponent is OPTIONAL. The default is port 443. 1355 The WebSocket endpoint is identified by a "wss" URI that is composed 1356 of the authority part of the "coaps+ws" URI and the well-known path 1357 "/.well-known/coap" [RFC5785] [I-D.bormann-hybi-ws-wk]. The path and 1358 query parts of a "coaps+ws" URI identify a resource within the 1359 specified endpoint which can be operated on by the methods defined by 1360 CoAP. 1362 coaps+ws://example.org/sensors/temperature?u=Cel 1363 \______ ______/\___________ ___________/ 1364 \/ \/ 1365 Uri-Path: "sensors" 1366 wss://example.org/.well-known/coap Uri-Path: "temperature" 1367 Uri-Query: "u=Cel" 1369 Figure 16: The "coaps+ws" URI Scheme 1371 Encoding considerations: The scheme encoding conforms to the 1372 encoding rules established for URIs in [RFC3986]. 1374 Interoperability considerations: None. 1376 Security considerations: See Section 11.1 of [RFC7252]. 1378 8.5. Uri-Host and Uri-Port Options 1380 CoAP over reliable transports maintains the property from 1381 Section 5.10.1 of [RFC7252]: 1383 The default values for the Uri-Host and Uri-Port Options are 1384 sufficient for requests to most servers. 1386 Unless otherwise noted, the default value of the Uri-Host Option is 1387 the IP literal representing the destination IP address of the request 1388 message. The default value of the Uri-Port Option is the destination 1389 TCP port. 1391 For CoAP over TLS, these default values are the same unless Server 1392 Name Indication (SNI) [RFC6066] is negotiated. In this case, the 1393 default value of the Uri-Host Option in requests from the TLS client 1394 to the TLS server is the SNI host. 1396 For CoAP over WebSockets, the default value of the Uri-Host Option in 1397 requests from the WebSocket client to the WebSocket server is 1398 indicated by the Host header field from the WebSocket handshake. 1400 8.6. Decomposing URIs into Options 1402 The steps are the same as specified in Section 6.4 of [RFC7252] with 1403 minor changes. 1405 This step from [RFC7252]: 1407 3. If |url| does not have a component whose value, when 1408 converted to ASCII lowercase, is "coap" or "coaps", then fail 1409 this algorithm. 1411 is updated to: 1413 3. If |url| does not have a component whose value, when 1414 converted to ASCII lowercase, is "coap+tcp", "coaps+tcp", 1415 "coap+ws", or "coaps+ws", then fail this algorithm. 1417 This step from [RFC7252]: 1419 7. If |port| does not equal the request's destination UDP port, 1420 include a Uri-Port Option and let that option's value be |port|. 1422 is updated to: 1424 7. If |port| does not equal the request's destination TCP port, 1425 include a Uri-Port Option and let that option's value be |port|. 1427 8.7. Composing URIs from Options 1429 The steps are the same as specified in Section 6.5 of [RFC7252] with 1430 minor changes. 1432 This step from [RFC7252]: 1434 1. If the request is secured using DTLS, let |url| be the string 1435 "coaps://". Otherwise, let |url| be the string "coap://". 1437 is updated to: 1439 1. For CoAP over TCP, if the request is secured using TLS, let |url| 1440 be the string "coaps+tcp://". Otherwise, let |url| be the string 1441 "coap+tcp://". For CoAP over WebSockets, if the request is 1442 secured using TLS, let |url| be the string "coaps+ws://". 1443 Otherwise, let |url| be the string "coap+ws://". 1445 This step from [RFC7252]: 1447 4. If the request includes a Uri-Port Option, let |port| be that 1448 option's value. Otherwise, let |port| be the request's 1449 destination UDP port. 1451 is updated to: 1453 4. If the request includes a Uri-Port Option, let |port| be that 1454 option's value. Otherwise, let |port| be the request's 1455 destination TCP port. 1457 9. Securing CoAP 1459 Security Challenges for the Internet of Things [SecurityChallenges] 1460 recommends: 1462 ... it is essential that IoT protocol suites specify a mandatory 1463 to implement but optional to use security solution. This will 1464 ensure security is available in all implementations, but 1465 configurable to use when not necessary (e.g., in closed 1466 environment). ... even if those features stretch the capabilities 1467 of such devices. 1469 A security solution MUST be implemented to protect CoAP over reliable 1470 transports and MUST be enabled by default. This document defines the 1471 TLS binding, but alternative solutions at different layers in the 1472 protocol stack MAY be used to protect CoAP over reliable transports 1473 when appropriate. Note that there is ongoing work to support a data 1474 object-based security model for CoAP that is independent of transport 1475 (see [I-D.ietf-core-object-security]). 1477 9.1. TLS binding for CoAP over TCP 1479 The TLS usage guidance in [RFC7925] applies, including the guidance 1480 about cipher suites in that document that are derived from the 1481 mandatory-to-implement (MTI) cipher suites defined in [RFC7252]. 1483 This guidance assumes implementation in a constrained device or for 1484 communication with a constrained device. CoAP over TCP/TLS has, 1485 however, a wider applicability. It may, for example, be implemented 1486 on a gateway or on a device that is less constrained (such as a smart 1487 phone or a tablet), for communication with a peer that is likewise 1488 less constrained, or within a backend environment that only 1489 communicates with constrained devices via proxies. As an exception 1490 to the previous paragraph, in this case, the recommendations in 1491 [RFC7525] are more appropriate. 1493 Since the guidance offered in [RFC7925] and [RFC7525] differs in 1494 terms of algorithms and credential types, it is assumed that a CoAP 1495 over TCP/TLS implementation that needs to support both cases 1496 implements the recommendations offered by both specifications. 1498 During the provisioning phase, a CoAP device is provided with the 1499 security information that it needs, including keying materials, 1500 access control lists, and authorization servers. At the end of the 1501 provisioning phase, the device will be in one of four security modes: 1503 NoSec: TLS is disabled. 1505 PreSharedKey: TLS is enabled. The guidance in Section 4.2 of 1506 [RFC7925] applies. 1508 RawPublicKey: TLS is enabled. The guidance in Section 4.3 of 1509 [RFC7925] applies. 1511 Certificate: TLS is enabled. The guidance in Section 4.4 of 1512 [RFC7925] applies. 1514 The "NoSec" mode is optional-to-implement. The system simply sends 1515 the packets over normal TCP which is indicated by the "coap+tcp" 1516 scheme and the TCP CoAP default port. The system is secured only by 1517 keeping attackers from being able to send or receive packets from the 1518 network with the CoAP nodes. 1520 "PreSharedKey", "RawPublicKey", or "Certificate" is mandatory-to- 1521 implement for the TLS binding depending on the credential type used 1522 with the device. These security modes are achieved using TLS and are 1523 indicated by the "coaps+tcp" scheme and TLS-secured CoAP default 1524 port. 1526 9.2. TLS usage for CoAP over WebSockets 1528 A CoAP client requesting a resource identified by a "coaps+ws" URI 1529 negotiates a secure WebSocket connection to a WebSocket server 1530 endpoint with a "wss" URI. This is described in Section 8.4. 1532 The client MUST perform a TLS handshake after opening the connection 1533 to the server. The guidance in Section 4.1 of [RFC6455] applies. 1534 When a CoAP server exposes resources identified by a "coaps+ws" URI, 1535 the guidance in Section 4.4 of [RFC7925] applies towards mandatory- 1536 to-implement TLS functionality for certificates. For the server-side 1537 requirements in accepting incoming connections over a HTTPS (HTTP- 1538 over-TLS) port, the guidance in Section 4.2 of [RFC6455] applies. 1540 Note that this formally inherits the mandatory-to-implement cipher 1541 suites defined in [RFC5246]. However, usually modern browsers 1542 implement more recent cipher suites that then are automatically 1543 picked up via the JavaScript WebSocket API. WebSocket Servers that 1544 provide Secure CoAP over WebSockets for the browser use case will 1545 need to follow the browser preferences and MUST follow [RFC7525]. 1547 10. Security Considerations 1549 The security considerations of [RFC7252] apply. For CoAP over 1550 WebSockets and CoAP over TLS-secured WebSockets, the security 1551 considerations of [RFC6455] also apply. 1553 10.1. Signaling Messages 1555 The guidance given by an Alternative-Address Option cannot be 1556 followed blindly. In particular, a peer MUST NOT assume that a 1557 successful connection to the Alternative-Address inherits all the 1558 security properties of the current connection. 1560 11. IANA Considerations 1562 11.1. Signaling Codes 1564 IANA is requested to create a third sub-registry for values of the 1565 Code field in the CoAP header (Section 12.1 of [RFC7252]). The name 1566 of this sub-registry is "CoAP Signaling Codes". 1568 Each entry in the sub-registry must include the Signaling Code in the 1569 range 7.00-7.31, its name, and a reference to its documentation. 1571 Initial entries in this sub-registry are as follows: 1573 +------+---------+-----------+ 1574 | Code | Name | Reference | 1575 +------+---------+-----------+ 1576 | 7.01 | CSM | [RFCthis] | 1577 | | | | 1578 | 7.02 | Ping | [RFCthis] | 1579 | | | | 1580 | 7.03 | Pong | [RFCthis] | 1581 | | | | 1582 | 7.04 | Release | [RFCthis] | 1583 | | | | 1584 | 7.05 | Abort | [RFCthis] | 1585 +------+---------+-----------+ 1587 Table 1: CoAP Signal Codes 1589 All other Signaling Codes are Unassigned. 1591 The IANA policy for future additions to this sub-registry is "IETF 1592 Review or IESG Approval" as described in [RFC8126]. 1594 11.2. CoAP Signaling Option Numbers Registry 1596 IANA is requested to create a sub-registry for Options Numbers used 1597 in CoAP signaling options within the "CoRE Parameters" registry. The 1598 name of this sub-registry is "CoAP Signaling Option Numbers". 1600 Each entry in the sub-registry must include one or more of the codes 1601 in the Signaling Codes subregistry (Section 11.1), the option number, 1602 the name of the option, and a reference to the option's 1603 documentation. 1605 Initial entries in this sub-registry are as follows: 1607 +------------+--------+---------------------+-----------+ 1608 | Applies to | Number | Name | Reference | 1609 +------------+--------+---------------------+-----------+ 1610 | 7.01 | 2 | Max-Message-Size | [RFCthis] | 1611 | | | | | 1612 | 7.01 | 4 | Block-wise-Transfer | [RFCthis] | 1613 | | | | | 1614 | 7.02, 7.03 | 2 | Custody | [RFCthis] | 1615 | | | | | 1616 | 7.04 | 2 | Alternative-Address | [RFCthis] | 1617 | | | | | 1618 | 7.04 | 4 | Hold-Off | [RFCthis] | 1619 | | | | | 1620 | 7.05 | 2 | Bad-CSM-Option | [RFCthis] | 1621 +------------+--------+---------------------+-----------+ 1623 Table 2: CoAP Signal Option Codes 1625 The IANA policy for future additions to this sub-registry is based on 1626 number ranges for the option numbers, analogous to the policy defined 1627 in Section 12.2 of [RFC7252]. (The policy is analogous rather than 1628 identical because the structure of the subregistry includes an 1629 additional column; however, the value of this column has no influence 1630 on the policy.) 1632 The documentation for a Signaling Option Number should specify the 1633 semantics of an option with that number, including the following 1634 properties: 1636 o Whether the option is critical or elective, as determined by the 1637 Option Number. 1639 o Whether the option is repeatable. 1641 o The format and length of the option's value. 1643 o The base value for the option, if any. 1645 11.3. Service Name and Port Number Registration 1647 IANA is requested to assign the port number 5683 and the service name 1648 "coap+tcp", in accordance with [RFC6335]. 1650 Service Name. 1651 coap+tcp 1653 Transport Protocol. 1654 tcp 1656 Assignee. 1657 IESG 1659 Contact. 1660 IETF Chair 1662 Description. 1663 Constrained Application Protocol (CoAP) 1665 Reference. 1666 [RFCthis] 1668 Port Number. 1669 5683 1671 11.4. Secure Service Name and Port Number Registration 1673 IANA is requested to assign the port number 5684 and the service name 1674 "coaps+tcp", in accordance with [RFC6335]. The port number is 1675 requested to address the exceptional case of TLS implementations that 1676 do not support the "Application-Layer Protocol Negotiation Extension" 1677 [RFC7301]. 1679 Service Name. 1680 coaps+tcp 1682 Transport Protocol. 1683 tcp 1685 Assignee. 1686 IESG 1688 Contact. 1689 IETF Chair 1691 Description. 1692 Constrained Application Protocol (CoAP) 1694 Reference. 1695 [RFC7301], [RFCthis] 1697 Port Number. 1698 5684 1700 11.5. URI Scheme Registration 1702 URI schemes are registered within the "Uniform Resource Identifier 1703 (URI) Schemes" registry maintained at [IANA.uri-schemes]. 1705 11.5.1. coap+tcp 1707 IANA is requested to register the Uniform Resource Identifier (URI) 1708 scheme "coap+tcp". This registration request complies with 1709 [RFC7595]. 1711 Scheme name: 1712 coap+tcp 1714 Status: 1715 Permanent 1717 Applications/protocols that use this scheme name: 1718 The scheme is used by CoAP endpoints to access CoAP resources 1719 using TCP. 1721 Contact: 1722 IETF chair 1724 Change controller: 1725 IESG 1727 Reference: 1728 Section 8.1 in [RFCthis] 1730 11.5.2. coaps+tcp 1732 IANA is requested to register the Uniform Resource Identifier (URI) 1733 scheme "coaps+tcp". This registration request complies with 1734 [RFC7595]. 1736 Scheme name: 1737 coaps+tcp 1739 Status: 1740 Permanent 1742 Applications/protocols that use this scheme name: 1743 The scheme is used by CoAP endpoints to access CoAP resources 1744 using TLS. 1746 Contact: 1747 IETF chair 1749 Change controller: 1750 IESG 1752 Reference: 1753 Section 8.2 in [RFCthis] 1755 11.5.3. coap+ws 1757 IANA is requested to register the Uniform Resource Identifier (URI) 1758 scheme "coap+ws". This registration request complies with [RFC7595]. 1760 Scheme name: 1761 coap+ws 1763 Status: 1764 Permanent 1766 Applications/protocols that use this scheme name: 1767 The scheme is used by CoAP endpoints to access CoAP resources 1768 using the WebSocket protocol. 1770 Contact: 1771 IETF chair 1773 Change controller: 1774 IESG 1776 Reference: 1777 Section 8.3 in [RFCthis] 1779 11.5.4. coaps+ws 1781 IANA is requested to register the Uniform Resource Identifier (URI) 1782 scheme "coaps+ws". This registration request complies with 1783 [RFC7595]. 1785 Scheme name: 1786 coaps+ws 1788 Status: 1789 Permanent 1791 Applications/protocols that use this scheme name: 1792 The scheme is used by CoAP endpoints to access CoAP resources 1793 using the WebSocket protocol secured with TLS. 1795 Contact: 1796 IETF chair 1798 Change controller: 1799 IESG 1801 References: 1802 Section 8.4 in [RFCthis] 1804 11.6. Well-Known URI Suffix Registration 1806 IANA is requested to register the 'coap' well-known URI in the "Well- 1807 Known URIs" registry. This registration request complies with 1808 [RFC5785]: 1810 URI Suffix. 1811 coap 1813 Change controller. 1814 IETF 1816 Specification document(s). 1817 [RFCthis] 1819 Related information. 1820 None. 1822 11.7. ALPN Protocol Identifier 1824 IANA is requested to assign the following value in the registry 1825 "Application Layer Protocol Negotiation (ALPN) Protocol IDs" created 1826 by [RFC7301]. The "coap" string identifies CoAP when used over TLS. 1828 Protocol. 1829 CoAP 1831 Identification Sequence. 1832 0x63 0x6f 0x61 0x70 ("coap") 1834 Reference. 1835 [RFCthis] 1837 11.8. WebSocket Subprotocol Registration 1839 IANA is requested to register the WebSocket CoAP subprotocol under 1840 the "WebSocket Subprotocol Name Registry": 1842 Subprotocol Identifier. 1843 coap 1845 Subprotocol Common Name. 1846 Constrained Application Protocol (CoAP) 1848 Subprotocol Definition. 1849 [RFCthis] 1851 11.9. CoAP Option Numbers Registry 1853 IANA is requested to add [RFCthis] to the references for the 1854 following entries registered by [RFC7959] in the "CoAP Option 1855 Numbers" sub-registry defined by [RFC7252]: 1857 +--------+--------+---------------------+ 1858 | Number | Name | Reference | 1859 +--------+--------+---------------------+ 1860 | 23 | Block2 | RFC 7959, [RFCthis] | 1861 | | | | 1862 | 27 | Block1 | RFC 7959, [RFCthis] | 1863 +--------+--------+---------------------+ 1865 Table 3: CoAP Option Numbers 1867 12. References 1869 12.1. Normative References 1871 [I-D.bormann-hybi-ws-wk] 1872 Bormann, C., "Well-known URIs for the WebSocket Protocol", 1873 draft-bormann-hybi-ws-wk-00 (work in progress), May 2017. 1875 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 1876 RFC 793, DOI 10.17487/RFC0793, September 1981, 1877 . 1879 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1880 Requirement Levels", BCP 14, RFC 2119, 1881 DOI 10.17487/RFC2119, March 1997, 1882 . 1884 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1885 Resource Identifier (URI): Generic Syntax", STD 66, 1886 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1887 . 1889 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1890 (TLS) Protocol Version 1.2", RFC 5246, 1891 DOI 10.17487/RFC5246, August 2008, 1892 . 1894 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 1895 Uniform Resource Identifiers (URIs)", RFC 5785, 1896 DOI 10.17487/RFC5785, April 2010, 1897 . 1899 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 1900 Extensions: Extension Definitions", RFC 6066, 1901 DOI 10.17487/RFC6066, January 2011, 1902 . 1904 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 1905 RFC 6455, DOI 10.17487/RFC6455, December 2011, 1906 . 1908 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1909 Application Protocol (CoAP)", RFC 7252, 1910 DOI 10.17487/RFC7252, June 2014, 1911 . 1913 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 1914 "Transport Layer Security (TLS) Application-Layer Protocol 1915 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 1916 July 2014, . 1918 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 1919 "Recommendations for Secure Use of Transport Layer 1920 Security (TLS) and Datagram Transport Layer Security 1921 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 1922 2015, . 1924 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1925 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1926 DOI 10.17487/RFC7540, May 2015, 1927 . 1929 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 1930 and Registration Procedures for URI Schemes", BCP 35, 1931 RFC 7595, DOI 10.17487/RFC7595, June 2015, 1932 . 1934 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1935 Application Protocol (CoAP)", RFC 7641, 1936 DOI 10.17487/RFC7641, September 2015, 1937 . 1939 [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer 1940 Security (TLS) / Datagram Transport Layer Security (DTLS) 1941 Profiles for the Internet of Things", RFC 7925, 1942 DOI 10.17487/RFC7925, July 2016, 1943 . 1945 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1946 the Constrained Application Protocol (CoAP)", RFC 7959, 1947 DOI 10.17487/RFC7959, August 2016, 1948 . 1950 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1951 Writing an IANA Considerations Section in RFCs", BCP 26, 1952 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1953 . 1955 12.2. Informative References 1957 [BK2015] Byrne, C. and J. Kleberg, "Advisory Guidelines for UDP 1958 Deployment", Proceedings draft-byrne-opsec-udp-advisory-00 1959 (expired), 2015. 1961 [EK2016] Edeline, K., Kuehlewind, M., Trammell, B., Aben, E., and 1962 B. Donnet, "Using UDP for Internet Transport Evolution", 1963 Proceedings arXiv preprint 1612.07816, 2016. 1965 [HomeGateway] 1966 Eggert, L., "An experimental study of home gateway 1967 characteristics", Proceedings of the 10th annual 1968 conference on Internet measurement , 2010. 1970 [I-D.gomez-lwig-tcp-constrained-node-networks] 1971 Gomez, C., Crowcroft, J., and M. Scharf, "TCP over 1972 Constrained-Node Networks", draft-gomez-lwig-tcp- 1973 constrained-node-networks-03 (work in progress), June 1974 2017. 1976 [I-D.ietf-core-cocoa] 1977 Bormann, C., Betzler, A., Gomez, C., and I. Demirkol, 1978 "CoAP Simple Congestion Control/Advanced", draft-ietf- 1979 core-cocoa-01 (work in progress), March 2017. 1981 [I-D.ietf-core-object-security] 1982 Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1983 "Object Security for Constrained RESTful Environments 1984 (OSCORE)", draft-ietf-core-object-security-06 (work in 1985 progress), October 2017. 1987 [IANA.uri-schemes] 1988 IANA, "Uniform Resource Identifier (URI) Schemes", 1989 . 1991 [LWM2M] Open Mobile Alliance, "Lightweight Machine to Machine 1992 Technical Specification Version 1.0", February 2017, 1993 . 1997 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 1998 DOI 10.17487/RFC0768, August 1980, 1999 . 2001 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2002 Specifications: ABNF", STD 68, RFC 5234, 2003 DOI 10.17487/RFC5234, January 2008, 2004 . 2006 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 2007 Cheshire, "Internet Assigned Numbers Authority (IANA) 2008 Procedures for the Management of the Service Name and 2009 Transport Protocol Port Number Registry", BCP 165, 2010 RFC 6335, DOI 10.17487/RFC6335, August 2011, 2011 . 2013 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2014 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2015 January 2012, . 2017 [SecurityChallenges] 2018 Polk, T. and S. Turner, "Security Challenges for the 2019 Internet of Things", Interconnecting Smart Objects with 2020 the Internet / IAB Workshop , February 2011, 2021 . 2024 [SW2016] Swett, I., "QUIC Deployment Experience @Google", 2025 Proceedings 2026 https://www.ietf.org/proceedings/96/slides/slides-96-quic- 2027 3.pdf, 2016. 2029 Appendix A. CoAP over WebSocket Examples 2031 This section gives examples for the first two configurations 2032 discussed in Section 4. 2034 An example of the process followed by a CoAP client to retrieve the 2035 representation of a resource identified by a "coap+ws" URI might be 2036 as follows. Figure 17 below illustrates the WebSocket and CoAP 2037 messages exchanged in detail. 2039 1. The CoAP client obtains the URI , for example, from a resource representation 2041 that it retrieved previously. 2043 2. It establishes a WebSocket connection to the endpoint URI 2044 composed of the authority "example.org" and the well-known path 2045 "/.well-known/coap", . 2047 3. It sends a single-frame, masked, binary message containing a CoAP 2048 request. The request indicates the target resource with the Uri- 2049 Path ("sensors", "temperature") and Uri-Query ("u=Cel") options. 2051 4. It waits for the server to return a response. 2053 5. The CoAP client uses the connection for further requests, or the 2054 connection is closed. 2056 CoAP CoAP 2057 Client Server 2058 (WebSocket (WebSocket 2059 Client) Server) 2061 | | 2062 | | 2063 +=========>| GET /.well-known/coap HTTP/1.1 2064 | | Host: example.org 2065 | | Upgrade: websocket 2066 | | Connection: Upgrade 2067 | | Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== 2068 | | Sec-WebSocket-Protocol: coap 2069 | | Sec-WebSocket-Version: 13 2070 | | 2071 |<=========+ HTTP/1.1 101 Switching Protocols 2072 | | Upgrade: websocket 2073 | | Connection: Upgrade 2074 | | Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= 2075 | | Sec-WebSocket-Protocol: coap 2076 | | 2077 | | 2078 +--------->| Binary frame (opcode=%x2, FIN=1, MASK=1) 2079 | | +-------------------------+ 2080 | | | GET | 2081 | | | Token: 0x53 | 2082 | | | Uri-Path: "sensors" | 2083 | | | Uri-Path: "temperature" | 2084 | | | Uri-Query: "u=Cel" | 2085 | | +-------------------------+ 2086 | | 2087 |<---------+ Binary frame (opcode=%x2, FIN=1, MASK=0) 2088 | | +-------------------------+ 2089 | | | 2.05 Content | 2090 | | | Token: 0x53 | 2091 | | | Payload: "22.3 Cel" | 2092 | | +-------------------------+ 2093 : : 2094 : : 2095 | | 2096 +--------->| Close frame (opcode=%x8, FIN=1, MASK=1) 2097 | | 2098 |<---------+ Close frame (opcode=%x8, FIN=1, MASK=0) 2099 | | 2101 Figure 17: A CoAP client retrieves the representation of a resource 2102 identified by a "coap+ws" URI 2104 Figure 18 shows how a CoAP client uses a CoAP forward proxy with a 2105 WebSocket endpoint to retrieve the representation of the resource 2106 "coap://[2001:db8::1]/". The use of the forward proxy and the 2107 address of the WebSocket endpoint are determined by the client from 2108 local configuration rules. The request URI is specified in the 2109 Proxy-Uri Option. Since the request URI uses the "coap" URI scheme, 2110 the proxy fulfills the request by issuing a Confirmable GET request 2111 over UDP to the CoAP server and returning the response over the 2112 WebSocket connection to the client. 2114 CoAP CoAP CoAP 2115 Client Proxy Server 2116 (WebSocket (WebSocket (UDP 2117 Client) Server) Endpoint) 2119 | | | 2120 +--------->| | Binary frame (opcode=%x2, FIN=1, MASK=1) 2121 | | | +------------------------------------+ 2122 | | | | GET | 2123 | | | | Token: 0x7d | 2124 | | | | Proxy-Uri: "coap://[2001:db8::1]/" | 2125 | | | +------------------------------------+ 2126 | | | 2127 | +--------->| CoAP message (Ver=1, T=Con, MID=0x8f54) 2128 | | | +------------------------------------+ 2129 | | | | GET | 2130 | | | | Token: 0x0a15 | 2131 | | | +------------------------------------+ 2132 | | | 2133 | |<---------+ CoAP message (Ver=1, T=Ack, MID=0x8f54) 2134 | | | +------------------------------------+ 2135 | | | | 2.05 Content | 2136 | | | | Token: 0x0a15 | 2137 | | | | Payload: "ready" | 2138 | | | +------------------------------------+ 2139 | | | 2140 |<---------+ | Binary frame (opcode=%x2, FIN=1, MASK=0) 2141 | | | +------------------------------------+ 2142 | | | | 2.05 Content | 2143 | | | | Token: 0x7d | 2144 | | | | Payload: "ready" | 2145 | | | +------------------------------------+ 2146 | | | 2148 Figure 18: A CoAP client retrieves the representation of a resource 2149 identified by a "coap" URI via a WebSocket-enabled CoAP proxy 2151 Appendix B. Change Log 2153 The RFC Editor is requested to remove this section at publication. 2155 B.1. Since draft-ietf-core-coap-tcp-tls-02 2157 Merged draft-savolainen-core-coap-websockets-07 Merged draft-bormann- 2158 core-block-bert-01 Merged draft-bormann-core-coap-sig-02 2160 B.2. Since draft-ietf-core-coap-tcp-tls-03 2162 Editorial updates 2164 Added mandatory exchange of Capabilities and Settings messages after 2165 connecting 2167 Added support for coaps+tcp port 5684 and more details on 2168 Application-Layer Protocol Negotiation (ALPN) 2170 Added guidance on CoAP Signaling Ping-Pong versus WebSocket Ping-Pong 2172 Updated references and requirements for TLS security considerations 2174 B.3. Since draft-ietf-core-coap-tcp-tls-04 2176 Updated references 2178 Added Appendix: Updates to RFC7641 Observing Resources in the 2179 Constrained Application Protocol (CoAP) 2181 Updated Capability and Settings Message (CSM) exchange in the Opening 2182 Handshake to allow initiator to send messages before receiving 2183 acceptor CSM 2185 B.4. Since draft-ietf-core-coap-tcp-tls-05 2187 Addressed feedback from Working Group Last Call 2189 Added Securing CoAP section and informative reference to OSCOAP 2191 Removed the Server-Name and Bad-Server-Name Options 2193 Clarified the Capability and Settings Message (CSM) exchange 2195 Updated Pong response requirements 2197 Added Connection Initiator and Connection Acceptor terminology where 2198 appropriate 2199 Updated LWM2M 1.0 informative reference 2201 B.5. Since draft-ietf-core-coap-tcp-tls-06 2203 Addressed feedback from second Working Group Last Call 2205 B.6. Since draft-ietf-core-coap-tcp-tls-07 2207 Addressed feedback from IETF Last Call 2209 Addressed feedback from ARTART review 2211 Addressed feedback from GENART review 2213 Addressed feedback from TSVART review 2215 Added fragment identifiers to URI schemes 2217 Added "Updates RFC7959" for BERT 2219 Added "Updates RFC6455" to extend well-known URI mechanism to ws and 2220 wss 2222 Clarified well-known URI mechanism use for all URI schemes 2224 Changed NoSec to optional-to-implement 2226 Acknowledgements 2228 We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier 2229 Delaby, Esko Dijk, Christian Groves, Nadir Javed, Michael Koster, 2230 Matthias Kovatsch, Achim Kraus, David Navarro, Szymon Sasin, Goran 2231 Selander, Zach Shelby, Andrew Summers, Julien Vermillard, and Gengyu 2232 Wei for their feedback. 2234 Last-call reviews from Yoshifumi Nishida, Mark Nottingham, and Meral 2235 Shirazipour as well as several IESG reviewers provided extensive 2236 comments; from the IESG, we would like to specifically call out Ben 2237 Campbell, Mirja Kuehlewind, Eric Rescorla, Adam Roach, and the 2238 responsible AD Alexey Melnikov. 2240 Contributors 2241 Matthias Kovatsch 2242 Siemens AG 2243 Otto-Hahn-Ring 6 2244 Munich D-81739 2246 Phone: +49-173-5288856 2247 EMail: matthias.kovatsch@siemens.com 2249 Teemu Savolainen 2250 Nokia Technologies 2251 Hatanpaan valtatie 30 2252 Tampere FI-33100 2253 Finland 2255 Email: teemu.savolainen@nokia.com 2257 Valik Solorzano Barboza 2258 Zebra Technologies 2259 820 W. Jackson Blvd. Suite 700 2260 Chicago 60607 2261 United States of America 2263 Phone: +1-847-634-6700 2264 Email: vsolorzanobarboza@zebra.com 2266 Authors' Addresses 2268 Carsten Bormann 2269 Universitaet Bremen TZI 2270 Postfach 330440 2271 Bremen D-28359 2272 Germany 2274 Phone: +49-421-218-63921 2275 Email: cabo@tzi.org 2277 Simon Lemay 2278 Zebra Technologies 2279 820 W. Jackson Blvd. Suite 700 2280 Chicago 60607 2281 United States of America 2283 Phone: +1-847-634-6700 2284 Email: slemay@zebra.com 2285 Hannes Tschofenig 2286 ARM Ltd. 2287 110 Fulbourn Rd 2288 Cambridge CB1 9NJ 2289 Great Britain 2291 Email: Hannes.tschofenig@gmx.net 2292 URI: http://www.tschofenig.priv.at 2294 Klaus Hartke 2295 Universitaet Bremen TZI 2296 Postfach 330440 2297 Bremen D-28359 2298 Germany 2300 Phone: +49-421-218-63905 2301 Email: hartke@tzi.org 2303 Bilhanan Silverajan 2304 Tampere University of Technology 2305 Korkeakoulunkatu 10 2306 Tampere FI-33720 2307 Finland 2309 Email: bilhanan.silverajan@tut.fi 2311 Brian Raymor (editor) 2312 Microsoft 2313 One Microsoft Way 2314 Redmond 98052 2315 United States of America 2317 Email: brian.raymor@microsoft.com