CORE C. Bormann Internet-Draft Universitaet Bremen TZI Updates: 7641 (if approved) S. Lemay Intended status: Standards Track Zebra Technologies Expires:April 14,August 18, 2017 H. Tschofenig ARM Ltd. K. Hartke Universitaet Bremen TZI B. Silverajan Tampere University of Technology B. Raymor, Ed. MicrosoftOctober 11, 2016February 14, 2017 CoAP (Constrained Application Protocol) over TCP, TLS, and WebSocketsdraft-ietf-core-coap-tcp-tls-05draft-ietf-core-coap-tcp-tls-06 Abstract The Constrained Application Protocol (CoAP), although inspired by HTTP, was designed to use UDP instead of TCP. The message layer of the CoAP over UDP protocol includes support for reliable delivery, simple congestion control, and flow control. Some environments benefit from the availability of CoAP carried over reliable transports such as TCP or TLS. This document outlines the changes required to use CoAP over TCP, TLS, and WebSockets transports. It also formally updates [RFC7641] for use with these transports. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire onApril 14,August 18, 2017. Copyright Notice Copyright (c)20162017 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Conventions and Terminology . . . . . . . . . . . . . . .. . . . . . . .5 2. CoAP over TCP . . . . . . . . . . . . . . . . . . . . . . . .56 2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . .56 2.2.UDP-to-TCP gateways . . . . . . . . . . . . . . . . . .Message Format .6 2.3. Opening Handshake. . . . . . . . . . . . . . . . . . . .6 2.4.7 2.3. MessageFormat .Transmission . . . . . . . . . . . . . . . . . . 10 2.4. Connection Health . .7 2.5. Message Transmission. . . . . . . . . . . . . . . . . .1011 3. CoAP over WebSockets . . . . . . . . . . . . . . . . . . . .1011 3.1. Opening Handshake . . . . . . . . . . . . . . . . . . . .1213 3.2. Message Format . . . . . . . . . . . . . . . . . . . . .1314 3.3. Message Transmission . . . . . . . . . . . . . . . . . .1415 3.4. Connection Health . . . . . . . . . . . . . . . . . . . . 153.5. Closing the Connection . . . . . . . . . . . . . . . . . 154. Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . . 16 4.2. Signaling Option Numbers . . . . . . . . . . . . . . . . 16 4.3.CapabilityCapabilities and Settings Messages (CSM) . . . . . . . ..16 4.4. Ping and Pong Messages . . . . . . . . . . . . . . . . . 18 4.5. Release Messages . . . . . . . . . . . . . . . . . . . . 19 4.6. Abort Messages . . . . . . . . . . . . . . . . . . . . . 20 4.7.Capability and SettingsSignaling examples . . . . . . . . . . . . . . . . . . . 21 5. Block-wise Transfer and Reliable Transports . . . . . . . . .2122 5.1. Example: GET with BERT Blocks . . . . . . . . . . . . . . 23 5.2. Example: PUT with BERT Blocks . . . . . . . . . . . . . .2324 6. CoAP over Reliable Transport URIs . . . . . . . . . . . . . . 24 6.1. coap+tcp URI scheme . . . . . . . . . . . .24 6.1. CoAP over TCP. . . . . . . 25 6.2. coaps+tcp URI scheme . . . . . . . . . . . . . . . . . . 25 6.3. coap+ws URI scheme . . . . . . . . . . . . . . . . . . . 26 6.4. coaps+ws URI scheme . . . . . . . . . . . . . . . . . . . 27 6.5. Uri-Host andTLSUri-Port Options . . . . . . . . . . . . . . 28 6.6. Decomposing URIs into Options . . . . . . . . . . . . . . 28 6.7. Composing URIs from Options .24 6.2.. . . . . . . . . . . . . . 29 7. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 29 7.1. TLS binding for CoAP overWebSockets URIsTCP . . . . . . . . . . . . . . 29 7.2. TLS usage for CoAP over WebSockets . . . . . . . . .26 7.. . 30 8. Security Considerations . . . . . . . . . . . . . . . . . . .27 7.1.30 8.1. Signaling Messages . . . . . . . . . . . . . . . . . . .27 8.31 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . .28 8.1.31 9.1. Signaling Codes . . . . . . . . . . . . . . . . . . . . .28 8.2.31 9.2. CoAP Signaling Option Numbers Registry . . . . . . . . .28 8.3.31 9.3. Service Name and Port Number Registration . . . . . . . .29 8.4.32 9.4. Secure Service Name and Port Number Registration . . . .30 8.5.33 9.5. URI Scheme Registration . . . . . . . . . . . . . . . . .30 8.6.34 9.6. Well-Known URI Suffix Registration . . . . . . . . . . .33 8.7.36 9.7. ALPN Protocol Identifier . . . . . . . . . . . . . . . .33 8.8.36 9.8. WebSocket Subprotocol Registration . . . . . . . . . . .33 9.36 10. References . . . . . . . . . . . . . . . . . . . . . . . . .34 9.1.37 10.1. Normative References . . . . . . . . . . . . . . . . . .34 9.2.37 10.2. Informative References . . . . . . . . . . . . . . . . .3538 Appendix A. Updates to RFC7641 Observing Resources in the Constrained Application Protocol (CoAP) . . . . . .3640 A.1. Notifications and Reordering . . . . . . . . . . . . . .3640 A.2. Transmission and Acknowledgements . . . . . . . . . . . .3640 A.3.CancellationFreshness . . . . . . . . . . . . . . . . . . . . . .37 Appendix B. Negotiating Protocol Versions. . 40 A.4. Cancellation . . . . . . . . .37. . . . . . . . . . . . . 41 AppendixC.B. CoAP over WebSocket Examples . . . . . . . . . . . .3741 AppendixD.C. Change Log . . . . . . . . . . . . . . . . . . . . .41 D.1.44 C.1. Since draft-core-coap-tcp-tls-02 . . . . . . . . . . . .41 D.2.44 C.2. Since draft-core-coap-tcp-tls-03 . . . . . . . . . . . .41 D.3.44 C.3. Since draft-core-coap-tcp-tls-04 . . . . . . . . . . . .4144 C.4. Since draft-core-coap-tcp-tls-05 . . . . . . . . . . . . 44 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . .4145 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . .4145 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . .4245 1. Introduction The Constrained Application Protocol (CoAP) [RFC7252] was designed for Internet of Things (IoT) deployments, assuming that UDP [RFC0768] or DTLS [RFC6347] over UDP can be used unimpeded. UDP is a good choice for transferring small amounts of data across networks that follow the IP architecture. Some CoAP deployments need to integrate well with existing enterprise infrastructures, where UDP-based protocols may not be well-received or may even be blocked by firewalls. Middleboxes that are unaware of CoAP usage for IoT can make the use of UDP brittle, resulting in lost or malformed packets. Emerging standards such as Lightweight Machine to Machine [LWM2M] currently use CoAP over UDP as a transport and require support for CoAP over TCP to address the issues above and to protect investments in existing CoAP implementations and deployments. Although HTTP/2 could also potentially address these requirements, there would be additional costs and delays introduced by such a transition. Currently, there are also fewer HTTP/2 implementations available for constrained devices in comparison to CoAP. To address these requirements, this document defines how to transport CoAP over TCP, CoAP over TLS, and CoAP over WebSockets. Figure 1 illustrates the layering: +--------------------------------+ | Application | +--------------------------------+ +--------------------------------+ | Requests/Responses/Signaling | CoAP (RFC 7252) / This Document |--------------------------------| | Message Framing | This Document +--------------------------------+ | Reliable Transport | +--------------------------------+ Figure 1: Layering of CoAP over Reliable Transports Where NATs are present, CoAP over TCP can help with their traversal. NATs often calculate expiration timers based on the transport layer protocol being used by application protocols. Many NATs maintain TCP-based NAT bindings for longer periods based on the assumption that a transport layer protocol, such as TCP, offers additional information about the session life cycle. UDP, on the other hand, does not provide such information to a NAT and timeouts tend to be much shorter [HomeGateway]. Some environments may also benefit from the ability of TCP to exchange larger payloads, such as firmware images, without application layer segmentation and to utilize the more sophisticated congestion control capabilities provided by many TCP implementations. Note that there is ongoing work to add more elaborate congestion control to CoAP (see [I-D.ietf-core-cocoa]). CoAP may be integrated into a Web environment where the front-end uses CoAP over UDP from IoT devices to a cloud infrastructure and then CoAP over TCP between the back-end services. A TCP-to-UDP gateway can be used at the cloud boundary to communicate with the UDP-based IoT device. To allow IoT devices to better communicate in these demanding environments, CoAP needs to support different transport protocols, namely TCP [RFC0793], in some situations secured by TLS [RFC5246]. In addition, some corporate networks only allow Internet access via a HTTP proxy. In this case, the best transport for CoAPwouldmight be the WebSocket Protocol [RFC6455]. The WebSocket protocol provides two- way communication between a WebSocket client and a WebSocket server after upgrading an HTTP/1.1 [RFC7230] connection and may be available in an environment that blocks CoAP over UDP. Another scenario for CoAP over WebSockets is a CoAP application running inside a web browser without access to connectivity other than HTTP and WebSockets. This document specifies how to access resources using CoAP requests and responses over the TCP/TLS and WebSocket protocols. This allows connectivity-limited applications to obtain end-to-end CoAP connectivity either by communicating CoAP directly with a CoAP server accessible over a TCP/TLS or WebSocket connection or via a CoAP intermediary that proxies CoAP requests and responses between different transports, such as between WebSockets and UDP. Appendix A updates Observing Resources in the Constrained Application Protocol [RFC7641] for use with CoAP over reliable transports. [RFC7641] is an extension to the CoAP core protocol that enables CoAP clients to "observe" a resource on a CoAP server. (The CoAP client retrieves a representation of a resource and registers to be notified by the CoAP server when the representation is updated.) 1.1. Conventions and Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. This document assumes that readers are familiar with the terms and concepts that are used in [RFC6455], [RFC7252], [RFC7641], and[RFC7641].[RFC7959]. The term "reliable transport" is used onlyreferstostream-basedrefer to transport protocols such asTCP.TCP which provide reliable and ordered delivery of a byte-stream. BERT Option: A Block1 or Block2 option that includes an SZX value of 7. BERT Block: The payload of a CoAP message that is affected by a BERT Option in descriptive usage (Section 2.1 of [RFC7959]). Connection Initiator: The peer that opens a reliable byte stream connection, i.e., the TCP active opener, TLS client, or WebSocket client. Connection Acceptor: The peer that accepts the reliable byte stream connection opened by the other peer, i.e., the TCP passive opener, TLS server, or WebSocket server. For simplicity, a Payload Marker (0xFF) is shown in all examples for message formats: ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1 1 1 1 1 1 1 1| Payload (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The Payload Marker indicates the start of the optional payload and is absent for zero-length payloads (see section 3 of [RFC7252]). 2. CoAP over TCP The request/response interaction model of CoAP over TCP is the same as CoAP over UDP. The primary differences are in the message layer. The message layer of CoAP over UDP supports optional reliability by defining fourtypesTypes of messages: Confirmable, Non-confirmable, Acknowledgement, and Reset.TCP eliminates the need for the message layer to support reliability. AsIn addition, messages include aresult, message types are not defined in CoAP over TCP.Message ID to relate Acknowledgments to Confirmable messages and to detect duplicate messages. 2.1. Messaging Model Conceptually, CoAP over TCP replaces most of the message layer of CoAP over UDPmessage layerwith a framing mechanism on top of thebyte streambyte-stream provided by TCP/TLS, conveying the length information for each message that on datagram transports is provided by the UDP/DTLS datagram layer. TCP ensures reliable message transmission, so the message layer of CoAP over TCPmessaging layeris not required to support acknowledgements ordetection ofto detect duplicate messages. As a result, both the Type and Message ID fields are no longer required and are removed from the CoAP over TCP message format.All messages are also untyped.Figure 2 illustrates the difference between CoAP over UDP and CoAP over reliable transport. The removed Type and Message ID fields are indicated by dashes. CoAP Client CoAP Server CoAP Client CoAP Server | | | | | CON [0xbc90] | | (-------) [------] | | GET /temperature | | GET /temperature | | (Token 0x71) | | (Token 0x71) | +------------------->| +------------------->| | | | | | ACK [0xbc90] | | (-------) [------] | | 2.05 Content | | 2.05 Content | | (Token 0x71) | | (Token 0x71) | | "22.5 C" | | "22.5 C" | |<-------------------+ |<-------------------+ | | | | CoAP over UDP CoAP over reliable transport Figure 2: Comparison between CoAP over unreliable and reliabletransport.transport 2.2.UDP-to-TCP gateways A UDP-to-TCP gateway MUST discard all Empty messages (Code 0.00) after processing at the message layer. For Confirmable (CON), Non- Confirmable (NOM), and Acknowledgement (ACK) messages that are not Empty, their contents are repackaged into untyped messages. 2.3. Opening Handshake Both the client and the server MUST send a Capability and Settings message (CSM see Section 4.3) as its first message on the connection. This message establishes the initial settings and capabilities for the endpoint such as maximum message size or support for block-wise transfers. The absence of options in the CSM indicates that base values are assumed. To avoid unnecessary latency, a client MAY send additional messages without waiting to receive the server CSM; however, it is important to note that the server CSM might advertise capabilities that impact how a client is expected to communicate with the server. For example, the server CSM could advertise a Max-Message-Size option (See Section 4.3.2) that is smaller than the base value (1152). Clients and servers MUST treat a missing or invalid CSM as a connection error and abort the connection (see Section 4.6). 2.4.Message Format The CoAP message format defined in [RFC7252], as shown in Figure 3, relies on the datagram transport (UDP, or DTLS over UDP) for keeping the individual messages separate and for providing length information. 0 1 2 3 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Ver| T | TKL | Code | Message ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Token (if any, TKL bytes) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Options (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1 1 1 1 1 1 1 1| Payload (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 3: RFC 7252 defined CoAP MessageFormat.Format The CoAP over TCP message format is very similar to the format specified for CoAP over UDP. The differences are as follows: o Since the underlying TCP connection provides retransmissions and deduplication, there is no need for the reliability mechanisms provided by CoAP over UDP. The"T"Type (T) and"Message ID"Message ID fields in the CoAP message header are elided. o The"Ver"Version (Vers) field is elided as well. Inconstrastcontrast to theUDPmessagelayer for UDP and DTLS,format of CoAP over UDP, the message format for CoAP over TCPmessage layerdoes notsendinclude a versionnumbernumber. CoAP is defined ineach message.[RFC7252] with a version number of 1. At this time, there is no known reason to support version numbers different from 1. Ifrequiredversion negotiation needs to be addressed in the future,a new Capabilitythen Capabilities and SettingsOption (See Appendix B) could be definedMessages (CSM see Section 4.3) have been specifically designed tosupport version negotiation.enable such a potential feature. o In a stream oriented transport protocol such as TCP, a form of message delimitation is needed. For this purpose, CoAP over TCP introduces a length field with variable size. Figure 4 shows the adjusted CoAP message format with a modified structure for the fixed header (first 4 bytes of the CoAP over UDP header), which includes the length information of variable size, shown here as an 8-bit length. 0 1 2 3 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Len=13 | TKL |Extended Length| Code | TKL bytes ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Options (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1 1 1 1 1 1 1 1| Payload (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 4: CoAP frame with 8-bit Extended Lengthfield.field Length (Len): 4-bit unsigned integer. A value between 0 and 12 directly indicates the length of the message in bytes starting with the first bit of the Options field. Three values are reserved for special constructs: 13: An 8-bit unsigned integer (Extended Length) follows the initial byte and indicates the length of options/payload minus 13. 14: A 16-bit unsigned integer (Extended Length) in network byte order follows the initial byte and indicates the length of options/payload minus 269. 15: A 32-bit unsigned integer (Extended Length) in network byte order follows the initial byte and indicates the length of options/payload minus 65805. The encoding of the Length field is modeled on CoAP Options (see section 3.1 of [RFC7252]). The following figures show the message format for the 0-bit, 16-bit, and the 32-bit variable length cases. 0 1 2 3 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Len | TKL | Code | Token (if any, TKL bytes) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Options (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1 1 1 1 1 1 1 1| Payload (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 5: CoAP message format without an Extended Lengthfield.field For example: A CoAP message just containing a 2.03 code with the token 7f and no options or payload would be encoded as shown in Figure 6. 0 1 2 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x01 | 0x43 | 0x7f | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Len = 0 ------> 0x01 TKL = 1 ___/ Code = 2.03 --> 0x43 Token = 0x7f Figure 6: CoAP message with no options orpayload.payload 0 1 2 3 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Len=14 | TKL | Extended Length (16 bits) | Code | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Token (if any, TKL bytes) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Options (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1 1 1 1 1 1 1 1| Payload (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 7: CoAP message format with 16-bit Extended Lengthfield.field 0 1 2 3 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Len=15 | TKL | Extended Length (32 bits) +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | Code | Token (if any, TKL bytes) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Options (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1 1 1 1 1 1 1 1| Payload (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 8: CoAP message format with 32-bit Extended Lengthfield.field The semantics of the other CoAP header fields are left unchanged.2.5.2.3. Message Transmission Once a connection is established, both endpoints MUST send a Capabilities and Settings message (CSM see Section 4.3) as their first message on the connection. This message establishes the initial settings and capabilities for the endpoint such as maximum message size or support for block-wise transfers. The absence of options in the CSM indicates that base values are assumed. To avoid a deadlock, the Connection Initiator MUST NOT wait for the Connection Acceptor to send its initial CSM message before sending its own initial CSM message. Conversely, the Connection Acceptor MAY wait for the Connection Initiator to send its initial CSM message before sending its own initial CSM message. To avoid unnecessary latency, a Connection Initiator MAY send additional messages without waiting to receive the Connection Acceptor's CSM; however, it is important to note that the Connection Acceptor's CSM might advertise capabilities that impact how the initiator is expected to communicate with the acceptor. For example, the acceptor CSM could advertise a Max-Message-Size option (see Section 4.3.1) that is smaller than the base value (1152). Endpoints MUST treat a missing or invalid CSM as a connection error and abort the connection (see Section 4.6). CoAP requests and responses are exchanged asynchronously over the TCP/TLS connection. A CoAP client can send multiple requests without waiting for a response and the CoAP server can return responses in any order. Responses MUST be returned over the same connection as the originating request. Concurrent requests are differentiated by their Token, which is scoped locally to the connection. The connection is bi-directional, so requests can be sent both by the entity that established the connection and the remote host. Retransmission and deduplication of messages is provided by the TCP/ TLS protocol. 2.4. Connection Health Empty messages (Code 0.00) can always be sent and MUST be ignored by the recipient. This provides a basic keep-alive function that can refresh NAT bindings. If a CoAP client does not receive any response for some time after sending a CoAP request (or, similarly, when a client observes a resource and it does not receive any notification for some time), it can send a CoAP Ping Signaling message (Section 4.4) to test the connection and verify that the CoAP server is responsive. 3. CoAP over WebSockets CoAP over WebSockets is intentionally similar to CoAP over TCP; therefore, this section only specifies the differences between the transports. CoAP over WebSockets can be used in a number of configurations. The most basic configuration is a CoAP client retrieving or updating a CoAP resource locatedaton a CoAP server that exposes a WebSocket endpoint (Figure 9). The CoAP client acts as the WebSocket client, establishes a WebSocket connection, and sends a CoAP request, to which the CoAP server returns a CoAP response. The WebSocket connection can be used for any number of requests. ___________ ___________ | | | | | _|___ requests ___|_ | | CoAP / \ \ -------------> / / \ CoAP | | Client \__/__/ <------------- \__\__/ Server | | | responses | | |___________| |___________| WebSocket =============> WebSocket Client Connection Server Figure 9: CoAP Client (WebSocket client) accesses CoAP Server (WebSocket server) The challenge with this configuration is how to identify a resource in the namespace of the CoAP server. When the WebSocket protocol is used by a dedicated client directly (i.e., not from a web page through a web browser), the client can connect to any WebSocket endpoint.This means it is necessary forSection 6.3 and Section 6.4 define new URI schemes that enable the client to identify boththea WebSocket endpoint(identified by a "ws" or "wss" URI)and the path and query of the CoAP resource within thatendpoint from the same URI.endpoint. When the WebSocket protocol is used from a web page, the choices are more limited [RFC6454], but the challenge persists.Section 6.2 defines a new "coap+ws" URI scheme that identifies both a WebSocket endpoint and a resource within that endpoint as follows: coap+ws://example.org/sensors/temperature?u=Cel \______ ______/\___________ ___________/ \/ \/ Uri-Path: "sensors" ws://example.org/.well-known/coap Uri-Path: "temperature" Uri-Query: "u=Cel" Figure 10: The "coap+ws" URI SchemeAnother possible configuration is to set up a CoAP forward proxy at the WebSocket endpoint. Depending on what transports are available to the proxy, it could forward the request to a CoAP server with a CoAP UDP endpoint (Figure11),10), an SMS endpoint (a.k.a. mobile phone), or even another WebSocket endpoint. The CoAP client specifies the resource to be updated or retrieved in theProxy-URIProxy-Uri Option. ___________ ___________ ___________ | | | | | | | _|___ ___|_ _|___ ___|_ | | CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP | | Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server | | | | | | | |___________| |___________| |___________| WebSocket ===> WebSocket UDP UDP Client Server Client Server Figure11:10: CoAP Client (WebSocket client) accesses CoAP Server (UDP server) via a CoAP proxy (WebSocket server/UDP client) A third possible configuration is a CoAP server running inside a web browser (Figure12).11). The web browser initially connects to a WebSocket endpoint and is then reachable through the WebSocket server. When no connection exists, the CoAP server is unreachable. Because the WebSocket server is the only way to reach the CoAP server, the CoAP proxy should be a Reverse Proxy. ___________ ___________ ___________ | | | | | | | _|___ ___|_ _|___ ___|_ | | CoAP / \ \ ---> / / \ CoAP / / \ ---> / \ \ CoAP | | Client \__/__/ <--- \__\__/ Proxy \__\__/ <--- \__/__/ Server | | | | | | | |___________| |___________| |___________| UDP UDP WebSocket <=== WebSocket Client Server Server Client Figure12:11: CoAP Client (UDP client) accessessleepyCoAP Server (WebSocket client) via a CoAP proxy (UDP server/WebSocket server) Further configurations are possible, including those where a WebSocket connection is established through an HTTP proxy.CoAP over WebSockets is intentionally very similar to CoAP over UDP. Therefore, instead of presenting CoAP over WebSockets as a new protocol, this document specifies it as a series of deltas from [RFC7252].3.1. Opening Handshake Before CoAP requests and responses are exchanged, a WebSocket connection is established as defined in Section 4 of [RFC6455]. Figure1312 shows an example. The WebSocket client MUST include the subprotocol name "coap" in the list of protocols, which indicates support for the protocol defined in this document. Any later, incompatible versions of CoAP or CoAP over WebSockets will use a different subprotocol name. The WebSocket client includes the hostname of the WebSocket server in the Host header field of its handshake as per [RFC6455]. The Host header field also indicates the default value of the Uri-Host Option in requests from the WebSocket client to the WebSocket server. GET /.well-known/coap HTTP/1.1 Host: example.org Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Protocol: coap Sec-WebSocket-Version: 13 HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= Sec-WebSocket-Protocol: coap Figure13:12: Example of an Opening Handshake 3.2. Message Format Once a WebSocket connection is established, CoAP requests and responses can be exchanged as WebSocket messages. Since CoAP uses a binary message format, the messages are transmitted in binary data frames as specified in Sections 5 and 6 of [RFC6455]. The message format shown in Figure1413 is the same as the CoAP over TCP message format (see Section2.4)2.2) with onerestriction.change. The Length (Len) field MUST be set to zero because the WebSockets frame contains the length. 0 1 2 3 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |LenLen=0 | TKL | Code | Token (TKL bytes) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Options (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |1 1 1 1 1 1 1 1| Payload (if any) ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure14:13: CoAP Message Format over WebSocketsTheAs with CoAP overTCPTCP, the message format for CoAP over WebSockets eliminates the Version field defined in CoAP over UDP. If CoAP version negotiation is required in the future, CoAP over WebSockets can address the requirement by the definition of a new subprotocol identifier that is negotiated during the opening handshake. Requests and response messages can be fragmented as specified in Section 5.4 of [RFC6455], though typically they are sent unfragmented as they tend to be small and fully buffered before transmission. The WebSocket protocol does not provide means for multiplexing. If it is not desirable for a large message to monopolize the connection, requests and responses can be transferred in a block-wise fashion as defined in [RFC7959].Empty messages (Code 0.00) MUST be ignored by the recipient (see also Section 4.4).3.3. Message Transmission As with CoAP over TCP, both endpoints MUST send a Capabilities and Settings message (CSM see Section 4.3) as their first message on the WebSocket connection. CoAP requests and responses are exchanged asynchronously over the WebSocket connection. A CoAP client can send multiple requests without waiting for a response and the CoAP server can return responses in any order. Responses MUST be returned over the same connection as the originating request. Concurrent requests are differentiated by their Token, which is scoped locally to the connection. The connection is bi-directional, so requests can be sent both by the entity that established the connection and the remote host.RetransmissionAs with CoAP over TCP, retransmission and deduplication of messages is provided by the WebSocket protocol. CoAP over WebSockets therefore does not make a distinction between Confirmable orNon-ConfirmableNon- Confirmable messages, and does not provide Acknowledgement or Reset messages. 3.4. Connection HealthWhen a client does not receive any response for some time after sending aAs with CoAPrequest (or, similarly, when a client observesover TCP, aresource and it does not receive any notification for some time), the connection between the WebSocket client and the WebSocket server may be lost or temporarily disrupted without theCoAP clientbeing aware of it. To checkcan test the health of the CoAP over WebSocket connection(and thereby of all active requests, if any), a client can sendby sending a CoAP Ping Signaling message (Section 4.4). WebSocket Ping and unsolicited Pong framesas specified in Section(Section 5.5 of[RFC6455][RFC6455]) SHOULD NOT be used to ensure that redundant maintenance traffic is not transmitted.There is no way to retransmit a request without creating a new one. Re-registering interest in a resource is permitted, but entirely unnecessary. 3.5. Closing the Connection The WebSocket connection is closed as specified in Section 7 of [RFC6455]. All requests for which the CoAP client has not received a response yet are cancelled when the connection is closed.4. Signaling Signaling messages are introduced to allow peers to: oShareRelated characteristics such as maximum message size for the connection oShutdownShut down the connection in anorderedorderly fashion oTerminate theProvide diagnostic information when terminating a connection in response to a serious error condition Signaling is a third basic kind of message in CoAP, after requests and responses. Signaling messages share a common structure with the existing CoAP messages. There is a code, a token, options, and an optional payload. (See Section 3 of [RFC7252] for the overall structure, as adapted to the specific transport.) 4.1. Signaling Codes A code in the7.01-7.317.00-7.31 range indicates a Signaling message. Values in this range are assigned by the "CoAP Signaling Codes" sub-registry (see Section8.1).9.1). For each message, there is a sender and a peer receiving the message. Payloads in Signaling messages are diagnostic payloads(seeas defined in Section 5.5.2 of [RFC7252]), unless otherwise defined by a Signaling message option. 4.2. Signaling Option Numbers Option numbers for Signaling messages are specific to the message code. They do not share the number space with CoAP options for request/response messages or with Signaling messages using other codes. Option numbers are assigned by the "CoAP Signaling Option Numbers" sub-registry (see Section8.2).9.2). Signaling options are elective or critical as defined in Section 5.4.1 of[RFC7252]).[RFC7252]. If a Signaling option is critical and not understood by the receiver, it MUST abort the connection (see Section 4.6). If the option is understood but cannot be processed, the option documents the behavior. 4.3.CapabilityCapabilities and Settings Messages (CSM)CapabilityCapabilities and Settings messages (CSM) are used for two purposes: o Each capability option advertises one capability of the sender to the recipient. o Setting options indicate a setting that will be applied by the sender.A Capability and Settings messageOne CSM MUST be sent by both endpoints at the start of theconnection andconnection. Further CSM MAY be sent at any other time by either endpoint over the lifetime of the connection. Both capability andsettingssetting options are cumulative. ACapability and Settings messageCSM does not invalidate a previously sent capability indication or setting even if it is not repeated. A capability message without any option is ano-operationno- operation (and can be used as such). An option that is sent might override a previous value for the same option. The option defines how to handle this case if needed. Base values are listed below for CSM Options. These are the values for theCapabilitycapability andSettingsetting before anyCapabilityCapabilities and Settings messages send a modified value. These are not default values for the option as defined in Section 5.4.4 in [RFC7252]. A default value would mean that an emptyCapabilityCapabilities and Settings message would result in the option being set to its default value.CapabilityCapabilities and Settings messages are indicated by the 7.01 code (CSM). 4.3.1.Server-Name Setting Option +--------+------------+-------------+--------+--------+-------------+ | Number | Applies to | Name | Format | Length | Base Value | +--------+------------+-------------+--------+--------+-------------+ | 1 | CSM | Server-Name | string | 1-255 | (see below) | +--------+------------+-------------+--------+--------+-------------+ A client can use the Server-Name critical option to indicate the default value for the Uri-Host Options in the messages that it sends to the server. It has the same restrictions as the Uri-Host Option (Section 5.10 of [RFC7252]. For TLS, the initial value for the Server-Name Option is given by the SNI value. For Websockets, the initial value for the Server-Name Option is given by the HTTP Host header field. 4.3.2.Max-Message-Size Capability Option The sender can use theMax-Message-SizeelectiveoptionMax-Message-Size Option to indicate the maximum message size in bytes that it can receive.+--------+-----------+------------------+--------+--------+---------++---+---+---+---------+------------------+--------+--------+--------+ |Number# | C | R | Applies | Name | Format | Length | Base | | | | | to | | | | Value |+--------+-----------+------------------+--------+--------+---------++---+---+---+---------+------------------+--------+--------+--------+ | 2 | | | CSM | Max-Message-Size | uint | 0-4 | 1152 |+--------+-----------+------------------+--------+--------+---------++---+---+---+---------+------------------+--------+--------+--------+ C=Critical, R=Repeatable As per Section 4.6 of [RFC7252], the base value (and the value used when this option is not implemented) is 1152.A peer that relies on thisThe active value of the Max-Message-Size Option is replaced each time the optionbeing indicatedis sent with acertain minimummodified value. Its starting valuewill enjoy limited interoperability. 4.3.3.is its base value. 4.3.2. Block-wise Transfer Capability Option+--------+-----------+----------------+--------+--------+-----------++---+---+---+---------+-----------------+--------+--------+---------+ |Number# | C | R | Applies | Name | Format | Length | Base | | | | | to | | | | Value |+--------+-----------+----------------+--------+--------+-----------++---+---+---+---------+-----------------+--------+--------+---------+ | 4 | | | CSM | Block-wise | empty | 0 | (none) | | | | | | Transfer | | | |+--------+-----------+----------------+--------+--------+-----------++---+---+---+---------+-----------------+--------+--------+---------+ C=Critical, R=Repeatable A sender can use the elective Block-wise TransferelectiveOption to indicate that it supports the block-wise transfer protocol [RFC7959]. If the option is not given, the peer has no information about whether block-wise transfers are supported by the sender or not. An implementation that supports block-wise transfers SHOULD indicate the Block-wise Transfer Option. If a Max-Message-Size Option is indicated with a value that is greater than 1152 (in the same or a different CSM message), the Block-wise Transfer Option also indicates support for BERT (see Section 5). Subsequently, if the Max-Message- Size Option is indicated with a value equal or less than 1152, BERT support is no longer indicated. 4.4. Ping and Pong Messages In CoAP overTCP,reliable transports, Empty messages (Code 0.00) can always be sent and MUST be ignored by the recipient. This provides a basic keep-alivefunction that can refresh NAT bindings.function. In contrast, Ping and Pong messages are a bidirectional exchange. Upon receipt of a Ping message, the receiver MUST return asinglePong message with an identical token in response. Unless there isreturnedan option with delaying semantics such as theidentical token.Custody Option, it SHOULD respond as soon as practical. As with all Signaling messages, the recipient of a Ping or Pong message MUST ignore elective options it does not understand. Ping and Pong messages are indicated by the 7.02 code (Ping) and the 7.03 code (Pong). 4.4.1. Custody Option+--------+------------+---------+--------+--------+------------++---+---+---+----------+----------------+--------+--------+---------+ |Number# | C | R | Appliesto| Name | Format | Length | Base | | | | | to | | | | Value |+--------+------------+---------+--------+--------+------------++---+---+---+----------+----------------+--------+--------+---------+ | 2 | | | Ping,Pong| Custody | empty | 0 | (none) |+--------+------------+---------+--------+--------+------------+ A peer replying| | | | Pong | | | | | +---+---+---+----------+----------------+--------+--------+---------+ C=Critical, R=Repeatable When responding to a Pingmessagemessage, the receiver canadd a Custodyinclude an electiveoption toCustody Option in the Pongmessage it returns.message. This option indicates that the application has processed all the request/response messagesthat it hasreceivedin the present connection ahead ofprior to the Ping messagethat promptedon thePong message.current connection. (Note that there is no definition of specific application semanticsoffor "processed", but there is an expectation that thesenderreceiver ofthe Ping leading to thea Pong Message with a Custody Option should be able to free buffers based on this indication.) ACustody elective optionsender can alsobe sentinclude an elective Custody Option in a Ping message to explicitly request thereturninclusion ofaan elective Custody Option in the corresponding Pong message.A peer is always free to indicate that it has finished processing all previous request/response messages by sending a Custody Option in aThe receiver SHOULD delay its Pongmessage. A peer is also free NOT to send a Custody Option in casemessage until itis stillfinishes processingpreviousall the request/ responsemessages; however, it SHOULD delay its responsemessages received prior toathe Pingwith a Custody Option until it can also return one.message on the current connection. 4.5. Release Messages AreleaseRelease message indicates that the sender does not want to continue maintaining the connection and opts for an orderlyshutdown; theshutdown. The details are in the options. A diagnostic payload (see Section 5.5.2 of [RFC7252]) MAY be included. Arelease messagepeer will normallybe repliedrespond toby the peera Release message by closing the TCP/TLS connection. Messages may be in flight when the sender decides to send a Release message. The general expectation is that these will still be processed. Release messages are indicated by the 7.04 code (Release). Release messages can indicate one or more reasons using elective options. The following options are defined:+--------+-----------+-----------------+--------+--------+----------++---+---+---+---------+------------------+--------+--------+--------+ |Number# | C | R | Applies | Name | Format | Length | Base | | | | | to | | | | Value |+--------+-----------+-----------------+--------+--------+----------++---+---+---+---------+------------------+--------+--------+--------+ | 2 |Release | Bad-Server-Name | empty | 0|(none) | +--------+-----------+-----------------+--------+--------+----------+ The Bad-Server-Name elective option indicates that the default indicated by the CSM Server-Name Option is unlikely to be useful for this server. +--------+----------+-------------------+--------+--------+---------+ | Number | Applies | Name | Format | Length | Basex | Release | Alternative- |tostring | 1-255 | (none) | |Value|+--------+----------+-------------------+--------+--------+---------+|4|Release|Alternate-AddressAddress |string|1-255|(none)|+--------+----------+-------------------+--------+--------+---------++---+---+---+---------+------------------+--------+--------+--------+ C=Critical, R=Repeatable TheAlternative-AddresselectiveoptionAlternative-Address Option requests the peer to instead open a connection of the same scheme as the present connection to the alternative transport address given. Its value is in the form "authority" as defined in Section 3.2 of [RFC3986].+--------+------------+----------+--------+--------+------------+The Alternative-Address Option is a repeatable option as defined in Section 5.4.5 of [RFC7252]. +---+---+---+---------+-----------------+--------+--------+---------+ |Number# | C | R | Appliesto| Name | Format | Length | Base | | | | | to | | | | Value |+--------+------------+----------+--------+--------+------------++---+---+---+---------+-----------------+--------+--------+---------+ | 4 | |6| Release | Hold-Off | uint | 0-3 | (none) |+--------+------------+----------+--------+--------+------------++---+---+---+---------+-----------------+--------+--------+---------+ C=Critical, R=Repeatable TheHold-OffelectiveoptionHold-Off Option indicates that the server is requesting that the peer not reconnect to it for the number of seconds given in the value. 4.6. Abort Messages AnabortAbort message indicates that the sender is unable to continue maintaining the connection and cannot even wait for an orderly release. The sender shuts down the connection immediately after the abort (and may or may not wait for areleaseRelease orabortAbort message or connection shutdown in the inverse direction). A diagnostic payload (see Section 5.5.2 of [RFC7252]) SHOULD be included in the Abort message. Messages may be in flight when the sender decides to send anabortAbort message. The general expectation is that these will NOT be processed. Abort messages are indicated by the 7.05 code (Abort). Abort messages can indicate one or more reasons using elective options. The following option is defined:+--------+-----------+----------------+--------+--------+-----------++---+---+---+---------+-----------------+--------+--------+---------+ |Number# | C | R | Applies | Name | Format | Length | Base | | | | | to | | | | Value |+--------+-----------+----------------+--------+--------+-----------++---+---+---+---------+-----------------+--------+--------+---------+ | 2 | | | Abort | Bad-CSM-Option | uint | 0-2 | (none) |+--------+-----------+----------------+--------+--------+-----------++---+---+---+---------+-----------------+--------+--------+---------+ C=Critical, R=Repeatable The elective Bad-CSM-Option Option indicates that the sender is unable to process the CSM option identified by its option number, e.g. when it is critical and the option number is unknown by the sender, or when there is parameter problem with the value of an elective option. More detailed information SHOULD be included as a diagnostic payload. One reason for an sender to generate anabortAbort message is a general syntax error in thebyte streambyte-stream received. No specific option has been defined for this, as the details of that syntax error are best left to a diagnostic payload. 4.7.Capability and SettingsSignaling examples An encoded example of a Ping message with a non-empty token is shown in Figure15.14. 0 1 2 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x01 | 0xe2 | 0x42 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Len = 0 -------> 0x01 TKL = 1 ___/ Code = 7.02 Ping --> 0xe2 Token = 0x42 Figure15:14: Ping Message Example An encoded example of the corresponding Pong message is shown in Figure16.15. 0 1 2 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x01 | 0xe3 | 0x42 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Len = 0 -------> 0x01 TKL = 1 ___/ Code = 7.03 Pong --> 0xe3 Token = 0x42 Figure16:15: Pong Message Example 5. Block-wise Transfer and Reliable Transports The message size restrictions defined in Section 4.6 of CoAP [RFC7252] to avoid IP fragmentation are not necessary when CoAP is used over a reliablebyte streamtransport. While this suggests that theBlock-wiseBlock- wise transfer protocol [RFC7959] is also no longer needed, it remains applicable for a number of cases: o large messages, such as firmware downloads, may cause undesired head-of-line blocking when a single TCP connection is used o a UDP-to-TCP gateway may simply not have the context to convert a message with a Block Option into the equivalent exchange without any use of a Block Option (it would need to convert the entire blockwise exchange from start to end into a single exchange) The 'Block-wise Extension for Reliable Transport (BERT)' extends the Block protocol to enable the use of larger messages over a reliable transport. The use of this new extension is signaled by sending Block1 or Block2 Options with SZX == 7 (a "BERT option"). SZX == 7 is a reserved value in [RFC7959]. In control usage, a BERT option is interpreted in the same way as the equivalent Option with SZX == 6, except that it also indicates the capability to process BERT blocks. As with the basic Block protocol, the recipient of a CoAP request with a BERT option in control usage is allowed to respond with a different SZX value, e.g. to send a non- BERT block instead. In descriptive usage, a BERT Option is interpreted in the same way as the equivalent Option with SZX == 6, except that the payload is allowed to contain a multiple of 1024 bytes (non-final BERT block) or more than 1024 bytes (final BERT block). The recipient of a non-final BERT block (M=1) conceptually partitions the payload into a sequence of 1024-byte blocks and acts exactly as if it had received this sequence in conjunction with block numbers starting at, and sequentially increasing from, the block number given in the Block Option. In other words, the entire BERT block is positioned at the byte position that results from multiplying the block number with 1024. The position of further blocks to be transferred is indicated by incrementing the block number by the number of elements in this sequence (i.e., the size of the payload divided by 1024 bytes). As with SZX == 6, the recipient of a final BERT block (M=0) simply appends the payload at the byte position that is indicated by the block number multiplied with 1024. The following examples illustrate BERT options. A value of SZX == 7 is labeled as "BERT" or as "BERT(nnn)" to indicate a payload of size nnn. In all these examples, a Block Option is decomposed to indicate the kind of Block Option (1 or 2) followed by a colon, the block number (NUM), more bit (M), and block size exponent (2**(SZX+4)) separated by slashes. E.g., a Block2 Option value of 33 would be shown as 2:2/0/32), or a Block1 Option value of 59 would be shown as 1:3/1/128. 5.1. Example: GET with BERT Blocks Figure1716 shows a GET request with a response that is split into three BERT blocks. The first response contains 3072 bytes of payload; the second, 5120; and the third, 4711. Note how the block number increments to move the position inside the response body forward.CLIENT SERVERCoAP Client CoAP Server | | | GET, /status ------> | | | | <------ 2.05 Content, 2:0/1/BERT(3072) | | | | GET, /status, 2:3/0/BERT ------> | | | | <------ 2.05 Content, 2:3/1/BERT(5120) | | | | GET, /status, 2:8/0/BERT ------> | | | | <------ 2.05 Content, 2:8/0/BERT(4711) | Figure17:16: GET with BERTblocks.blocks 5.2. Example: PUT with BERT Blocks Figure1817 demonstrates a PUT exchange with BERT blocks.CLIENT SERVERCoAP Client CoAP Server | | | PUT, /options, 1:0/1/BERT(8192) ------> | | | | <------ 2.31 Continue, 1:0/1/BERT | | | | PUT, /options, 1:8/1/BERT(16384) ------> | | | | <------ 2.31 Continue, 1:8/1/BERT | | | | PUT, /options, 1:24/0/BERT(5683) ------> | | | | <------ 2.04 Changed, 1:24/0/BERT | | | Figure18:17: PUT with BERTblocks.blocks 6. CoAP over Reliable Transport URIs CoAP over UDP [RFC7252] defines the "coap" and "coaps" URI schemes. This document introduces four additional URI schemes for identifying CoAP resources and providing a means of locating theresource. 6.1.resource: o the "coap+tcp" URI scheme for CoAP over TCPand TLS URIso the "coaps+tcp" URI scheme for CoAP over TCPusessecured by TLS o the"coap+tcp""coap+ws" URIscheme.scheme for CoAP overTLS usesWebSockets o the"coaps+tcp" scheme. The rules from Section 6 of [RFC7252] apply to both of these"coaps+ws" URIschemes. [RFC7252], Section 8 (Multicast CoAP) is not applicable to these schemes.scheme for CoAP over WebSockets secured by TLS Resources made available viaone of the "coap+tcp" or "coaps+tcp"these schemes have no shared identitywith the other scheme or with the "coap" or "coaps" scheme,even if their resource identifiers indicate the same authority (the same host listening to the same TCP port).The schemes constituteThey are distinct namespacesand, in combination with the authority,and are considered to be distinct origin servers.6.1.1.The syntax for the URI schemes in this section are specified using Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of "host", "port", "path-abempty", and "query" are adopted from [RFC3986]. Section 8 (Multicast CoAP) in [RFC7252] is not applicable to these schemes. 6.1. coap+tcp URI schemecoap-tcp-URIThe "coap+tcp" URI scheme identifies CoAP resources that are intended to be accessible using CoAP over TCP. coap+tcp-URI = "coap+tcp:" "//" host [ ":" port ] path-abempty [ "?" query ] Thesemanticssyntax defined in[RFC7252],Section6.1, apply6.1 of [RFC7252] applies to this URIscheme,scheme with the following changes: o The port subcomponent indicates the TCP port at which the CoAP server is located. (If it is empty or not given, then the default port 5683 is assumed, as with UDP.)6.1.2.Encoding considerations: The scheme encoding conforms to the encoding rules established for URIs in [RFC3986]. Interoperability considerations: None. Security considerations: See Section 11.1 of [RFC7252]. 6.2. coaps+tcp URI schemecoaps-tcp-URIThe "coaps+tcp" URI scheme identifies CoAP resources that are intended to be accessible using CoAP over TCP secured with TLS. coaps+tcp-URI = "coaps+tcp:" "//" host [ ":" port ] path-abempty [ "?" query ] Thesemanticssyntax defined in[RFC7252],Section6.2, apply6.2 of [RFC7252] applies to this URI scheme, with the following changes: o The port subcomponent indicates the TCP port at which the TLS server for the CoAP server is located. If it is empty or not given, then the default port 443 is assumed (this is different from the default port for "coaps", i.e., CoAP over DTLS over UDP). o If a TLS server does not support the Application-Layer Protocol Negotiation Extension (ALPN) [RFC7301] or wishes to accommodate TLS clients that do not support ALPN, it MAY offer a coaps+tcp endpoint on TCP port 5684. This endpoint MAY also be ALPN enabled. A TLS server MAY offer coaps+tcp endpoints on ports other than TCP port 5684, which MUST be ALPN enabled. o For TCP ports other than port 5684, the TLS client MUST use the ALPN extension to advertise the "coap" protocol identifier (see Section8.7)9.7) in the list of protocols in its ClientHello. If the TCP server selects and returns the "coap" protocol identifier using the ALPN extension in its ServerHello, then the connection succeeds. If the TLS server either does not negotiate the ALPN extension or returns a no_application_protocol alert, the TLS client MUST close the connection. o For TCP port 5684, a TLS client MAY use the ALPN extension to advertise the "coap" protocol identifier in the list of protocols in its ClientHello. If the TLS server selects and returns the "coap" protocol identifier using the ALPN extension in its ServerHello, then the connection succeeds. If the TLS server returns a no_application_protocol alert, then the TLS client MUST close the connection. If the TLS server does not negotiate the ALPN extension, then coaps+tcp is implicitly selected. o For TCP port 5684, if the TLS client does not use the ALPN extension to negotiate the protocol, then coaps+tcp is implicitly selected.6.2. CoAP over WebSockets URIs ForEncoding considerations: The scheme encoding conforms to thefirst configuration discussedencoding rules established for URIs in [RFC3986]. Interoperability considerations: None. Security considerations: See Section3, this document defines two new URIs schemes that can be used for identifying CoAP resources and providing a means11.1 oflocating these resources: "coap+ws" and "coap+wss". Similar to the "coap" and "coaps" schemes, the[RFC7252]. 6.3. coap+ws URI scheme The "coap+ws"and "coap+wss" schemes organizeURI scheme identifies CoAP resourceshierarchically under athat are intended to be accessible using CoAPorigin server.over WebSockets. coap-ws-URI = "coap+ws:" "//" host [ ":" port ] path-abempty [ "?" query ] Thekey differenceport component isthat the serverOPTIONAL. The default ispotentially reachable on a WebSocket endpoint instead of a UDP endpoint.port 80. The WebSocket endpoint is identified by a "ws"or "wss"URI that is composed of the authority part of the "coap+ws"or "coap+wss" URI, respectively,URI and the well-known path "/.well-known/coap" [RFC5785]. The path and query parts of a "coap+ws"or "coap+wss"URI identify a resource within the specified endpoint which can be operated on by the methods defined byCoAP.CoAP: coap+ws://example.org/sensors/temperature?u=Cel \______ ______/\___________ ___________/ \/ \/ Uri-Path: "sensors" ws://example.org/.well-known/coap Uri-Path: "temperature" Uri-Query: "u=Cel" Figure 18: Thesyntax of the"coap+ws"and "coap+wss"URIschemes is specified below in Augmented Backus-Naur Form (ABNF) [RFC5234].Scheme Encoding considerations: Thedefinitions of "host", "port", "path-abempty" and "query" arescheme encoding conforms to thesame asencoding rules established for URIs in [RFC3986].coap-ws-URI = "coap+ws:" "//" host [ ":" port ] path-abempty [ "?" query ] coap-wss-URIInteroperability considerations: None. Security considerations: See Section 11.1 of [RFC7252]. 6.4. coaps+ws URI scheme The "coaps+ws" URI scheme identifies CoAP resources that are intended to be accessible using CoAP over WebSockets secured by TLS. coaps-ws-URI ="coap+wss:""coaps+ws:" "//" host [ ":" port ] path-abempty [ "?" query ] The port component isOPTIONAL; the default for "coap+ws" is port 80, while theOPTIONAL. The defaultfor "coap+wss"is port 443.Fragment identifiers are notThe WebSocket endpoint is identified by a "wss" URI that is composed of the authority part of therequest"coaps+ws" URI andthus MUST NOT be transmitted inthe well-known path "/.well-known/coap" [RFC5785]. The path and query parts of aWebSocket handshake or in"coaps+ws" URI identify a resource within the specified endpoint which can be operated on by the methods defined by CoAP. coaps+ws://example.org/sensors/temperature?u=Cel \______ ______/\___________ ___________/ \/ \/ Uri-Path: "sensors" wss://example.org/.well-known/coap Uri-Path: "temperature" Uri-Query: "u=Cel" Figure 19: The "coaps+ws" URIoptionsScheme Encoding considerations: The scheme encoding conforms to the encoding rules established for URIs in [RFC3986]. Interoperability considerations: None. Security considerations: See Section 11.1 ofa[RFC7252]. 6.5. Uri-Host and Uri-Port Options CoAPrequest. 6.2.1. Decomposingover reliable transports maintains the property from Section 5.10.1 of [RFC7252]: The default values for the Uri-Host andComposingUri-Port Options are sufficient for requests to most servers. Unless otherwise noted, the default value of the Uri-Host Option is the IP literal representing the destination IP address of the request message. The default value of the Uri-Port Option is the destination TCP port. For CoAP over TLS, these default values are the same unless Server Name Indication (SNI) [RFC6066] is negotiated. In this case, the default value of the Uri-Host Option in requests from the TLS client to the TLS server is the SNI host. For CoAP over WebSockets, the default value of the Uri-Host Option in requests from the WebSocket client to the WebSocket server is indicated by the Host header field from the WebSocket handshake. 6.6. Decomposing URIs into Options The stepsfor decomposing a "coap+ws" or "coap+wss" URI into CoAP optionsare the same as specified in Section 6.4 of [RFC7252] with the following changes:o The3. If |url| does not have a <scheme> componentMUST be "coap+ws" or "coap+wss"whose value, when converted to ASCIIlowercase. o A Uri-Host Option MUST only be included inlowercase, is "coap" or "coaps", then fail this algorithm. If |url| does not have arequest when the <host><scheme> component whose value, when converted to ASCII lowercase, is "coap+tcp", "coaps+tcp", "coap+ws", or "coaps+ws" then fail this algorithm. 7. If |port| does not equal theuri-host component in the Host header field in the WebSocket handshake. o Arequest's destination UDP port, include a Uri-Port OptionMUST onlyand let that option's value beincluded in a request if|port|. If |port| does not equal theport component inrequest's destination TCP port, include a Uri-Port Option and let that option's value be |port|. 6.7. Composing URIs from Options The steps are theHost header fieldsame as specified in Section 6.5 of [RFC7252] with theWebSocket handshake. The steps to constructfollowing changes: 1. If the request is secured using DTLS, let |url| be the string "coaps://". Otherwise, let |url| be the string "coap://". For CoAP over TCP, if the request is secured using TLS, let |url| be the string "coaps+tcp://". Otherwise, let |url| be the string "coap+tcp://". For CoAP over WebSockets, if the request is secured using TLS, let |url| be the string "coaps+ws://". Otherwise, let |url| be the string "coap+ws://". 4. If the request includes aURI fromUri-Port Option, let |port| be that option's value. Otherwise, let |port| be the request's destination UDP port. If the request includes a Uri-Port Option, let |port| be that option's value. Otherwise, let |port| be the request'soptions are changed accordingly.destination TCP port. 7. Securing CoAP SecurityConsiderations The security considerationsChallenges for the Internet of[RFC7252] apply. TLS version 1.2 or higherThings [SecurityChallenges] recommends: ... it is essential that IoT protocol suites specify a mandatory to implement but optional to use security solution. This will ensure security ismandatory-to-implementavailable in all implementations, but configurable to use when not necessary (e.g., in closed environment). ... even if those features stretch the capabilities of such devices. A security solution MUST be implemented to protect CoAP over reliable transports and MUST be enabled by default.An endpointThis document defines the TLS binding, but alternative solutions at different layers in the protocol stack MAYimmediately abort abe used to protect CoAP overTLS connectionreliable transports when appropriate. Note thatdoes not meet this requirement (see Section 4.6) and SHOULD includethere is ongoing work to support adiagnostic payload.data object-based security model for CoAP that is independent of transport (see [I-D.ietf-core-object-security]). 7.1. TLS binding for CoAP over TCP The TLS usage guidance in [RFC7925]SHOULDapplies. During the provisioning phase, a CoAP device is provided with the security information that it needs, including keying materials, access control lists, and authorization servers. At the end of the provisioning phase, the device will befollowed.in one of four security modes: NoSec: TLSdoes not protectis disabled. PreSharedKey: TLS is enabled. The guidance in Section 4.2 of [RFC7925] applies. RawPublicKey: TLS is enabled. The guidance in Section 4.3 of [RFC7925] applies. Certificate: TLS is enabled. The guidance in Section 4.4 of [RFC7925] applies. The "NoSec" mode is mandatory-to-implement. The system simply sends the packets over normal TCPheader. This may,which is indicated by the "coap+tcp" scheme and the TCP CoAP default port. The system is secured only by keeping attackers from being able to send or receive packets from the network with the CoAP nodes. "PreSharedKey", "RawPublicKey", or "Certificate" is mandatory-to- implement forexample, allow an on-path adversarythe TLS binding depending on the credential type used with the device. These security modes are achieved using TLS and are indicated by the "coaps+tcp" scheme and TLS-secured CoAP default port. 7.2. TLS usage for CoAP over WebSockets A CoAP client requesting a resource identified by a "coaps+ws" URI negotiates a secure WebSocket connection toterminateaTCPWebSocket server endpoint with a "wss" URI. This is described in Section 6.4. The client MUST perform a TLS handshake after opening the connectionprematurelyto the server. The guidance in Section 4.1 of [RFC6455] applies. When a CoAP server exposes resources identified byspoofingaTCP reset message."coaps+ws" URI, the guidance in Section 4.4 of [RFC7925] applies towards mandatory- to-implement TLS functionality for certificates. For the server-side requirements in accepting incoming connections over a HTTPS (HTTP- over-TLS) port, the guidance in Section 4.2 of [RFC6455] applies. 8. Security Considerations The security considerations of [RFC7252] apply. For CoAP over WebSockets and CoAP over TLS-securedWebSockets do not introduce additional security issues beyond CoAP and DTLS-secured CoAP respectively [RFC7252]. TheWebSockets, the security considerations of [RFC6455] also apply.7.1.8.1. Signaling Messages o The guidance given by an Alternative-Address Option cannot be followed blindly. In particular, a peer MUST NOT assume that a successful connection to the Alternative-Address inherits all the security properties of the current connection.o SNI vs. Server-Name: Any security negotiated in the TLS handshake is for the SNI name exchanged in the TLS handshake and checked against the certificate provided by the server. The Server-Name Option cannot be used to extend these security properties to the additional server name. 8.9. IANA Considerations8.1.9.1. Signaling Codes IANA is requested to create a third sub-registry for values of the Code field in the CoAP header (Section 12.1 of [RFC7252]). The name of this sub-registry is "CoAP Signaling Codes". Each entry in the sub-registry must include the Signaling Code in the range7.01-7.31,7.00-7.31, its name, and a reference to its documentation. Initial entries in this sub-registry are as follows: +------+---------+-----------+ | Code | Name | Reference | +------+---------+-----------+ | 7.01 | CSM | [RFCthis] | | | | | | 7.02 | Ping | [RFCthis] | | | | | | 7.03 | Pong | [RFCthis] | | | | | | 7.04 | Release | [RFCthis] | | | | | | 7.05 | Abort | [RFCthis] | +------+---------+-----------+ Table 1: CoAP Signal Codes All other Signaling Codes are Unassigned. The IANA policy for future additions to this sub-registry is "IETF Review or IESG Approval" as described in [RFC5226].8.2.9.2. CoAP Signaling Option Numbers Registry IANA is requested to create a sub-registry for Options Numbers used in CoAP signaling optionssimilar towithin theCoAP Option Numbers Registry (Section 12.2"CoRE Parameters" registry. The name of[RFC7252]), with the single change that a fourth columnthis sub-registry isadded to"CoAP Signaling Option Numbers". Each entry in the sub-registrythat ismust include one or more of the codes in the Signaling Codes subregistry (Section8.1). The9.1), the option number, the name ofthis sub-registry is "CoAP Signaling Option Numbers".the option, and a reference to the option's documentation. Initial entries in this sub-registry are as follows:+--------+------------+---------------------+-----------+ | Number+------------+--------+---------------------+-----------+ | Applies to | Number | Name | Reference |+--------+------------+---------------------+-----------+ | 1 | CSM | Server-Name | [RFCthis] | | | | |+------------+--------+---------------------+-----------+ | 7.01 | 2 |CSM |Max-Message-Size | [RFCthis] | | | | | | |47.01 |CSM4 | Block-wise-Transfer | [RFCthis] | | | | | | |2 | Ping, Pong | Custody | [RFCthis] | | | | | |7.02, 7.03 | 2 |Release | Bad-Server-NameCustody | [RFCthis] | | | | | | |47.04 |Release2 | Alternative-Address | [RFCthis] | | | | | | |67.04 |Release4 | Hold-Off | [RFCthis] | | | | | | |27.05 |Abort2 | Bad-CSM-Option | [RFCthis] |+--------+------------+---------------------+-----------++------------+--------+---------------------+-----------+ Table 2: CoAP Signal Option Codes The IANA policy for future additions to this sub-registry is based on number ranges for the option numbers, analogous to the policy defined in Section 12.2 of [RFC7252].8.3.The documentation for a Signaling Option Number should specify the semantics of an option with that number, including the following properties: o Whether the option is critical or elective, as determined by the Option Number. o Whether the option is repeatable. o The format and length of the option's value. o The base value for the option, if any. 9.3. Service Name and Port Number Registration IANA is requested to assign the port number 5683 and the service name "coap+tcp", in accordance with [RFC6335]. Service Name. coap+tcp Transport Protocol. tcp Assignee. IESG <iesg@ietf.org> Contact. IETF Chair <chair@ietf.org> Description. Constrained Application Protocol (CoAP) Reference. [RFCthis] Port Number. 56838.4.9.4. Secure Service Name and Port Number Registration IANA is requested to assign the port number 5684 and the service name "coaps+tcp", in accordance with [RFC6335]. The port number is requested to address the exceptional case of TLS implementations that do not support the "Application-Layer Protocol Negotiation Extension" [RFC7301]. Service Name. coaps+tcp Transport Protocol. tcp Assignee. IESG <iesg@ietf.org> Contact. IETF Chair <chair@ietf.org> Description. Constrained Application Protocol (CoAP) Reference. [RFC7301], [RFCthis] Port Number. 56848.5.9.5. URI Scheme RegistrationThis document registers two new URI schemes, namely "coap+tcp" and "coaps+tcp", for the use of CoAP over TCP and for CoAP over TLS over TCP, respectively. The "coap+tcp" and "coaps+tcp" URI schemes can thus be compared to the "http" and "https" URI schemes. The syntax of the "coap" and "coaps"URI schemesis specified in Section 6 of [RFC7252] and the present document re-uses their semantics for "coap+tcp" and "coaps+tcp", respectively, withare registered within theexception that TCP, or TLS over TCP is used as a transport protocol."Uniform Resource Identifier (URI) Schemes" registry maintained at http://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml . 9.5.1. coap+tcp IANA is requested toadd these new URI schemes to the registry established with [RFC7595]. 8.5.1. coap+ws This document requests the registration ofregister the Uniform Resource Identifier (URI) scheme"coap+ws". The"coap+tcp". This registration request complies with[RFC4395]. URL scheme name. coap+ws Status.[RFC7595]. Scheme name: coap+tcp Status: PermanentURI scheme syntax. Defined in Section N of [RFCthis] URIApplications/protocols that use this schemesemantics.name: The"coap+ws" URIschemeprovides a wayis used by CoAP endpoints toidentifyaccess CoAP resourcesthat are potentially accessible over the Constrained Application Protocol (CoAP)usingthe WebSocket protocol. Encoding considerations. The scheme encoding conformsTCP. Contact: IETF chair <chair@ietf.org> Change controller: IESG <iesg@ietf.org> Reference: Section 6.1 in [RFCthis] 9.5.2. coaps+tcp IANA is requested to register theencoding rules established for URIs in [RFC3986], i.e., internationalized and reserved characters are expressed using UTF-8-based percent-encoding.Uniform Resource Identifier (URI) scheme "coaps+tcp". This registration request complies with [RFC7595]. Scheme name: coaps+tcp Status: Permanent Applications/protocols that use thisURIschemename.name: The scheme is used by CoAP endpoints to access CoAP resources usingthe WebSocket protocol. Interoperability considerations. None. Security Considerations. See Section N of [RFCthis] Contact.TLS. Contact: IETF chair <chair@ietf.org>Author/Change controller.Change controller: IESG <iesg@ietf.org>References.Reference: Section 6.2 in [RFCthis]8.5.2. coap+wss This document requests the registration of9.5.3. coap+ws IANA is requested to register the Uniform Resource Identifier (URI) scheme"coap+wss". The"coap+ws". This registration request complies with[RFC4395]. URL scheme name. coap+wss Status.[RFC7595]. Scheme name: coap+ws Status: PermanentURI scheme syntax. Defined in Section N of [RFCthis] URIApplications/protocols that use this schemesemantics.name: The"coap+ws" URIschemeprovides a wayis used by CoAP endpoints toidentifyaccess CoAP resourcesthat are potentially accessible over the Constrained Application Protocol (CoAP)using the WebSocketprotocol secured with Transport Layer Security (TLS). Encoding considerations. The scheme encoding conformsprotocol. Contact: IETF chair <chair@ietf.org> Change controller: IESG <iesg@ietf.org> Reference: Section 6.3 in [RFCthis] 9.5.4. coaps+ws IANA is requested to register theencoding rules established for URIs in [RFC3986], i.e., internationalized and reserved characters are expressed using UTF-8-based percent-encoding.Uniform Resource Identifier (URI) scheme "coaps+ws". This registration request complies with [RFC7595]. Scheme name: coaps+ws Status: Permanent Applications/protocols that use thisURIschemename.name: The scheme is used by CoAP endpoints to access CoAP resources using the WebSocket protocol secured with TLS.Interoperability considerations. None. Security Considerations. See Section N of [RFCthis] Contact.Contact: IETF chair <chair@ietf.org>Author/Change controller.Change controller: IESG <iesg@ietf.org>References.References: Section 6.4 in [RFCthis]8.6.9.6. Well-Known URI Suffix Registration IANA is requested to register the 'coap' well-known URI in the "Well- Known URIs" registry. This registration request complies with [RFC5785]: URI Suffix. coap Change controller. IETF Specification document(s). [RFCthis] Related information. None.8.7.9.7. ALPN Protocol Identifier IANA is requested to assign the following value in the registry "Application Layer Protocol Negotiation (ALPN) Protocol IDs" created by [RFC7301]. The "coap" string identifies CoAP when used over TLS. Protocol. CoAP Identification Sequence. 0x63 0x6f 0x61 0x70 ("coap") Reference. [RFCthis]8.8.9.8. WebSocket Subprotocol Registration IANA is requested to register the WebSocket CoAP subprotocol under the "WebSocket Subprotocol Name Registry": Subprotocol Identifier. coap Subprotocol Common Name. Constrained Application Protocol (CoAP) Subprotocol Definition. [RFCthis]9.10. References9.1.10.1. Normative References [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, DOI 10.17487/RFC0793, September 1981, <http://www.rfc-editor.org/info/rfc793>. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI10.17487/ RFC2119,10.17487/RFC2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <http://www.rfc-editor.org/info/rfc3986>.[RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and Registration Procedures for New URI Schemes", RFC 4395, DOI 10.17487/RFC4395, February 2006, <http://www.rfc-editor.org/info/rfc4395>.[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, DOI 10.17487/RFC5226, May 2008, <http://www.rfc-editor.org/info/rfc5226>. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI10.17487/ RFC5246,10.17487/RFC5246, August 2008, <http://www.rfc-editor.org/info/rfc5246>. [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known Uniform Resource Identifiers (URIs)", RFC 5785, DOI 10.17487/RFC5785, April 2010, <http://www.rfc-editor.org/info/rfc5785>. [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) Extensions: Extension Definitions", RFC 6066, DOI 10.17487/RFC6066, January 2011, <http://www.rfc-editor.org/info/rfc6066>. [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 6455, DOI 10.17487/RFC6455, December 2011, <http://www.rfc-editor.org/info/rfc6455>. [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI10.17487/ RFC7252,10.17487/RFC7252, June 2014, <http://www.rfc-editor.org/info/rfc7252>. [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, "Transport Layer Security (TLS) Application-Layer Protocol Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, July 2014, <http://www.rfc-editor.org/info/rfc7301>. [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines and Registration Procedures for URI Schemes", BCP 35, RFC 7595, DOI 10.17487/RFC7595, June 2015, <http://www.rfc-editor.org/info/rfc7595>. [RFC7641] Hartke, K., "Observing Resources in the Constrained Application Protocol (CoAP)", RFC 7641, DOI10.17487/ RFC7641,10.17487/RFC7641, September 2015, <http://www.rfc-editor.org/info/rfc7641>. [RFC7925] Tschofenig, H., Ed. and T. Fossati, "Transport Layer Security (TLS) / Datagram Transport Layer Security (DTLS) Profiles for the Internet of Things", RFC 7925, DOI 10.17487/RFC7925, July 2016, <http://www.rfc-editor.org/info/rfc7925>.9.2.10.2. Informative References [HomeGateway] Eggert, L., "An experimental study of home gateway characteristics", Proceedings of the 10th annual conference on Internetmeasurement,measurement , 2010. [I-D.ietf-core-cocoa] Bormann, C., Betzler, A., Gomez, C., and I. Demirkol, "CoAP Simple Congestion Control/Advanced", draft-ietf- core-cocoa-00 (work in progress), October 2016. [I-D.ietf-core-object-security] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security of CoAP (OSCOAP)", draft-ietf-core- object-security-01 (work in progress), December 2016. [LWM2M] Open Mobile Alliance, "Lightweight Machine to Machine Technical SpecificationCandidateVersion 1.0",April 2016, <http://technical.openmobilealliance.org/Technical/R elease_Program/docs/LightweightM2M/V1_0-20160407-C/ OMA-TS-LightweightM2M-V1_0-20160407-C.pdf>.February 2017, <http://www.openmobilealliance.org/release/LightweightM2M/ V1_0-20170208-A/ OMA-TS-LightweightM2M-V1_0-20170208-A.pdf>. [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, DOI 10.17487/RFC0768, August 1980, <http://www.rfc-editor.org/info/rfc768>. [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI10.17487/ RFC5234,10.17487/RFC5234, January 2008, <http://www.rfc-editor.org/info/rfc5234>. [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. Cheshire, "Internet Assigned Numbers Authority (IANA) Procedures for the Management of the Service Name and Transport Protocol Port Number Registry", BCP 165, RFC 6335, DOI 10.17487/RFC6335, August 2011, <http://www.rfc-editor.org/info/rfc6335>. [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, January 2012, <http://www.rfc-editor.org/info/rfc6347>. [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, DOI 10.17487/RFC6454, December 2011, <http://www.rfc-editor.org/info/rfc6454>. [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, <http://www.rfc-editor.org/info/rfc7230>. [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in the Constrained Application Protocol (CoAP)", RFC 7959, DOI 10.17487/RFC7959, August 2016, <http://www.rfc-editor.org/info/rfc7959>. [SecurityChallenges] Polk, T. and S. Turner, "Security Challenges for the Internet of Things", Interconnecting Smart Objects with the Internet / IAB Workshop , February 2011, <http://www.iab.org/wp-content/IAB-uploads/2011/03/ Turner.pdf>. Appendix A. Updates to RFC7641 Observing Resources in the Constrained Application Protocol (CoAP) In this appendix, "client" and "server" refer to the CoAP client and CoAP server. A.1. Notifications and Reordering When using the Observe Option with CoAP over UDP, notifications from the server set the option value to an increasing sequence number for reordering detection on the client since messages can arrive in a different order than they were sent. This sequence number is not required for CoAP over reliable transports since the TCP protocol ensures reliable and ordered delivery of messages. The value of the Observe Option in 2.xx notifications MAY be empty on transmission and MUST be ignored on reception. A.2. Transmission and Acknowledgements For CoAP over UDP, server notifications to the client can be confirmable or non-confirmable. A confirmable message requires the client to either respond with an acknowledgement message or a reset message. An acknowledgement message indicates that the client is alive and wishes to receive further notifications. A reset message indicates that the client does not recognize the token which causes the server to remove the associated entry from the list of observers. Since TCP eliminates the need for the message layer to support reliability, CoAP over reliable transports does not support confirmable or non-confirmable message types. All notifications are delivered reliably to the client with positive acknowledgement of receipt occurring at the TCP level. If the client does not recognize the token in a notification, it MAY immediately abort the connection (see Section4.6)4.6). A.3. Freshness For CoAP over UDP, if a client does not receive a notification for some time, it MAY send a new GET request with the same token as the original request to re-register its interest in a resource andSHOULD includeverify that the server is still responsive. For CoAP over reliable transports, it is more efficient to check the health of the connection (and all its active observations) by sending adiagnostic payload. A.3.CoAP Ping Signaling message (Section 4.4) rather than individual requests to confirm active observations. A.4. Cancellation For CoAP over UDP, a client that is no longer interested in receiving notifications can "forget" the observation and respond to the next notification from the server with a reset message to cancel the observation. For CoAP over reliable transports, a client MUST explicitly deregister by issuing a GET request that has the Token field set to the token of the observation to be cancelled and includes an Observe Option with the value set to 1 (deregister). If the client observes one or more resources over a reliableconnection,transport, then the CoAP server (or intermediary in the role of the CoAP server) MUST remove all entries associated with the client endpoint from the lists of observers when the connection is either closed or times out. Appendix B.Negotiating Protocol Versions CoAP is defined in [RFC7252] with a version number of 1. At this time, there is no known reason to support version numbers different from 1. In contrast to the message layer for UDP and DTLS, the CoAP over TCP message format does not include a version number. If version negotiation needs to be addressed in the future, then Capability and Settings have been specifically designed to enable such a potential feature. Appendix C.CoAP over WebSocket Examples This section gives examples for the first two configurations discussed in Section 3. An example of the process followed by a CoAP client to retrieve the representation of a resource identified by a "coap+ws" URI might be as follows. Figure1920 below illustrates the WebSocket and CoAP messages exchanged in detail. 1. The CoAP client obtains the URI <coap+ws://example.org/sensors/ temperature?u=Cel>, for example, from a resource representation that it retrieved previously. 2. It establishes a WebSocket connection to the endpoint URI composed of the authority "example.org" and the well-known path "/.well-known/coap", <ws://example.org/.well-known/coap>. 3. It sends a single-frame, masked, binary message containing a CoAP request. The request indicates the target resource with the Uri- Path ("sensors", "temperature") and Uri-Query ("u=Cel") options. 4. It waits for the server to return a response. 5. The CoAP client uses the connection for further requests, or the connection is closed. CoAP CoAP Client Server (WebSocket (WebSocket Client) Server) | | | | +=========>| GET /.well-known/coap HTTP/1.1 | | Host: example.org | | Upgrade: websocket | | Connection: Upgrade | | Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== | | Sec-WebSocket-Protocol: coap | | Sec-WebSocket-Version: 13 | | |<=========+ HTTP/1.1 101 Switching Protocols | | Upgrade: websocket | | Connection: Upgrade | | Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= | | Sec-WebSocket-Protocol: coap | | | | +--------->| Binary frame (opcode=%x2, FIN=1, MASK=1) | | +-------------------------+ | | | GET | | | | Token: 0x53 | | | | Uri-Path: "sensors" | | | | Uri-Path: "temperature" | | | | Uri-Query: "u=Cel" | | | +-------------------------+ | | |<---------+ Binary frame (opcode=%x2, FIN=1, MASK=0) | | +-------------------------+ | | | 2.05 Content | | | | Token: 0x53 | | | | Payload: "22.3 Cel" | | | +-------------------------+ : : : : | | +--------->| Close frame (opcode=%x8, FIN=1, MASK=1) | | |<---------+ Close frame (opcode=%x8, FIN=1, MASK=0) | | Figure19:20: A CoAP client retrieves the representation of a resource identified by a "coap+ws" URI Figure2021 shows how a CoAP client uses a CoAP forward proxy with a WebSocket endpoint to retrieve the representation of the resource "coap://[2001:DB8::1]/". The use of the forward proxy and the address of the WebSocket endpoint are determined by the client from local configuration rules. The request URI is specified in the Proxy-Uri Option. Since the request URI uses the "coap" URI scheme, the proxy fulfills the request by issuing a Confirmable GET request over UDP to the CoAP server and returning the response over the WebSocket connection to the client. CoAP CoAP CoAP Client Proxy Server (WebSocket (WebSocket (UDP Client) Server) Endpoint) | | | +--------->| | Binary frame (opcode=%x2, FIN=1, MASK=1) | | | +------------------------------------+ | | | | GET | | | | | Token: 0x7d | | | | | Proxy-Uri: "coap://[2001:DB8::1]/" | | | | +------------------------------------+ | | | | +--------->| CoAP message (Ver=1, T=Con, MID=0x8f54) | | | +------------------------------------+ | | | | GET | | | | | Token: 0x0a15 | | | | +------------------------------------+ | | | | |<---------+ CoAP message (Ver=1, T=Ack, MID=0x8f54) | | | +------------------------------------+ | | | | 2.05 Content | | | | | Token: 0x0a15 | | | | | Payload: "ready" | | | | +------------------------------------+ | | | |<---------+ | Binary frame (opcode=%x2, FIN=1, MASK=0) | | | +------------------------------------+ | | | | 2.05 Content | | | | | Token: 0x7d | | | | | Payload: "ready" | | | | +------------------------------------+ | | | Figure20:21: A CoAP client retrieves the representation of a resource identified by a "coap" URI via a WebSockets-enabled CoAP proxy AppendixD.C. Change Log The RFC Editor is requested to remove this section at publication.D.1.C.1. Since draft-core-coap-tcp-tls-02 Merged draft-savolainen-core-coap-websockets-07 Merged draft-bormann- core-block-bert-01 Merged draft-bormann-core-coap-sig-02D.2.C.2. Since draft-core-coap-tcp-tls-03 Editorial updates Added mandatory exchange of Capabilities and Settings messages after connecting Added support for coaps+tcp port 5684 and more details on Application-Layer Protocol Negotiation (ALPN) Added guidance on CoAP Signaling Ping-Pong versus WebSocket Ping-Pong Updated references and requirements for TLS security considerationsD.3.C.3. Since draft-core-coap-tcp-tls-04 Updated references Added Appendix: Updates to RFC7641 Observing Resources in the Constrained Application Protocol (CoAP) Updated Capability and Settings Message (CSM) exchange in the Opening Handshake to allowclientinitiator to send messages before receivingserveracceptor CSM C.4. Since draft-core-coap-tcp-tls-05 Addressed feedback from Working Group Last Call Added Securing CoAP section and informative reference to OSCOAP Removed the Server-Name and Bad-Server-Name Options Clarified the Capability and Settings Message (CSM) exchange Updated Pong response requirements Added Connection Initiator and Connection Acceptor terminology where appropriate Updated LWM2M 1.0 informative reference Acknowledgements We would like to thank Stephen Berard, Geoffrey Cristallo, Olivier Delaby, Christian Groves, Nadir Javed, Michael Koster, Matthias Kovatsch, Achim Kraus, David Navarro, Szymon Sasin, Goran Selander, Zach Shelby, Andrew Summers, Julien Vermillard, and Gengyu Wei for their feedback. Contributors Matthias Kovatsch Siemens AG Otto-Hahn-Ring 6 Munich D-81739 Phone: +49-173-5288856 EMail: matthias.kovatsch@siemens.com Teemu Savolainen Nokia Technologies Hatanpaan valtatie 30 Tampere FI-33100 Finland Email: teemu.savolainen@nokia.com Valik Solorzano Barboza Zebra Technologies 820 W. Jackson Blvd. Suite 700 Chicago 60607 United States of America Phone: +1-847-634-6700 Email: vsolorzanobarboza@zebra.comTeemu Savolainen Nokia Technologies Hatanpaan valtatie 30 Tampere FI-33100 Finland Email: teemu.savolainen@nokia.comAuthors' Addresses Carsten Bormann Universitaet Bremen TZI Postfach 330440 Bremen D-28359 Germany Phone: +49-421-218-63921 Email: cabo@tzi.org Simon Lemay Zebra Technologies 820 W. Jackson Blvd. Suite 700 Chicago 60607 United States of America Phone: +1-847-634-6700 Email: slemay@zebra.com Hannes Tschofenig ARM Ltd. 110 Fulbourn Rd Cambridge CB1 9NJ Great Britain Email: Hannes.tschofenig@gmx.net URI: http://www.tschofenig.priv.at Klaus Hartke Universitaet Bremen TZI Postfach 330440 Bremen D-28359 Germany Phone: +49-421-218-63905 Email: hartke@tzi.org Bilhanan Silverajan Tampere University of Technology Korkeakoulunkatu 10 Tampere FI-33720 Finland Email: bilhanan.silverajan@tut.fi Brian Raymor (editor) Microsoft One Microsoft Way Redmond 98052 United States of America Email: brian.raymor@microsoft.com