RFC 8323
CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets
RFC 8323 🎀
CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets
- Stream: Internet Engineering Task Force (IETF)
- Category: Standards Track
- Date: February 2018
- ISSN: 2070-1721
- Updates: RFC 7641, RFC 7959
- Obsoletes: none listed
- Authors: C. Bormann (Universitaet Bremen TZI), S. Lemay (Zebra Technologies), H. Tschofenig (ARM Ltd.), K. Hartke (Universitaet Bremen TZI), B. Silverajan (Tampere University of Technology), B. Raymor, Ed.
Abstract 💖
Okay so CoAP was inspired by HTTP, but it was built to run over UDP instead of TCP. Its message layer over UDP already gives you reliable delivery, simple congestion control, and flow control. It's giving efficient and tiny ✨
Some environments really want CoAP on a reliable transport like TCP or Transport Layer Security (TLS), and this document is all about the changes needed to make that happen over TCP, TLS, and WebSockets 🦋
It also formally updates RFC 7641 so it works with these transports, and RFC 7959 so you can send larger messages over a reliable transport. Iconic glow-up, honestly 👑
Status of This Memo 📜
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community, it went through public review, and the Internet Engineering Steering Group (IESG) approved it for publication. If you want more info on Internet Standards, check Section 2 of RFC 7841 🧚
Info about the current status of this document, any errata, and how to send feedback is at https://www.rfc-editor.org/info/rfc8323 💜
Copyright Notice ©️
Copyright (c) 2018 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, which are at https://trustee.ietf.org/license-info and apply as of the publication date. Please read these carefully, because they spell out your rights and restrictions for this document. Any Code Components pulled out of this document must include the Simplified BSD License text described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as the Simplified BSD License describes 🙈
Table of Contents 🍓
1. Introduction ....................................................3
2. Conventions and Terminology .....................................6
3. CoAP over TCP ...................................................7
3.1. Messaging Model ............................................7
3.2. Message Format .............................................9
3.3. Message Transmission ......................................11
3.4. Connection Health .........................................12
4. CoAP over WebSockets ...........................................13
4.1. Opening Handshake .........................................15
4.2. Message Format ............................................15
4.3. Message Transmission ......................................16
4.4. Connection Health .........................................17
5. Signaling ......................................................17
5.1. Signaling Codes ...........................................17
5.2. Signaling Option Numbers ..................................18
5.3. Capabilities and Settings Messages (CSMs) .................18
5.4. Ping and Pong Messages ....................................20
5.5. Release Messages ..........................................21
5.6. Abort Messages ............................................23
5.7. Signaling Examples ........................................24
6. Block-Wise Transfer and Reliable Transports ....................25
6.1. Example: GET with BERT Blocks .............................27
6.2. Example: PUT with BERT Blocks .............................27
7. Observing Resources over Reliable Transports ...................28
7.1. Notifications and Reordering ..............................28
7.2. Transmission and Acknowledgments ..........................28
7.3. Freshness .................................................28
7.4. Cancellation ..............................................29
8. CoAP over Reliable Transport URIs ..............................29
8.1. coap+tcp URI Scheme .......................................30
8.2. coaps+tcp URI Scheme ......................................31
8.3. coap+ws URI Scheme ........................................32
8.4. coaps+ws URI Scheme .......................................33
8.5. Uri-Host and Uri-Port Options .............................33
8.6. Decomposing URIs into Options .............................34
8.7. Composing URIs from Options ...............................35
9. Securing CoAP ..................................................35
9.1. TLS Binding for CoAP over TCP .............................36
9.2. TLS Usage for CoAP over WebSockets ........................37
10. Security Considerations .......................................37
10.1. Signaling Messages .......................................37
11. IANA Considerations ...........................................38
11.1. Signaling Codes ..........................................38
11.2. CoAP Signaling Option Numbers Registry ...................38
11.3. Service Name and Port Number Registration ................40
11.4. Secure Service Name and Port Number Registration .........40
11.5. URI Scheme Registration ..................................41
11.6. Well-Known URI Suffix Registration .......................43
11.7. ALPN Protocol Identifier .................................44
11.8. WebSocket Subprotocol Registration .......................44
11.9. CoAP Option Numbers Registry .............................44
12. References ....................................................45
12.1. Normative References .....................................45
12.2. Informative References ...................................47
Appendix A. Examples of CoAP over WebSockets ......................49
Acknowledgments ...................................................52
Contributors ......................................................52
Authors' Addresses ................................................53Part 1 is done, bestie! Part 2 comes next 🌈💅
1. Introduction ✨
okay so bestie, CoAP ([RFC7252]) was built for the Internet of Things 🌸, and it assumed UDP [RFC768] could go wherever it wanted, with Datagram Transport Layer Security (DTLS) [RFC6347] running on top of it. CoAP over UDP is all about simplicity 💅, it has a tiny code footprint 🦋, and its messages are small on the wire 🫶.
The main reason we're bringing CoAP over TCP [RFC793] and TLS [RFC5246] into the chat is that some networks just don't forward UDP packets 😭. Complete blocking of UDP happens in roughly 2% to 4% of terrestrial access networks, according to [EK2016]. It's especially common in enterprise networks and in regions with otherwise sketchy connectivity 💀. Some networks also rate-limit UDP traffic, as reported in [BK2015], and when people were standardizing Quick UDP Internet Connections (QUIC), the numbers came out around 0.3% [SW2016]. Lowkey wild.
Using CoAP over TCP also brings a few extra effects that might be super desirable in a specific deployment 🎀:
- Where NATs are present along the communication path, CoAP over TCP leads to different NAT traversal behavior than CoAP over UDP. NATs often calculate expiration timers based on the transport-layer protocol being used by application protocols. Many NATs keep TCP-based NAT bindings around for longer periods, based on the assumption that a transport-layer protocol, such as TCP, offers additional information about the session lifecycle. UDP, on the other hand, doesn't give a NAT that information, and timeouts tend to be much shorter [HomeGateway]. According to [HomeGateway], the mean for TCP and UDP NAT binding timeouts is 386 minutes (TCP) and 160 seconds (UDP). Shorter timeout values mean keepalive messages have to be sent more frequently. Hence, the use of CoAP over TCP requires less-frequent transmission of keepalive messages. Iconic for the vibes 🧚
- TCP uses congestion control and flow control mechanisms that are more sophisticated than the default mechanisms provided by CoAP over UDP, and these TCP mechanisms are useful for transferring larger payloads 🍓. (However, work is ongoing to add advanced congestion control to CoAP over UDP as well; see [CoCoA].)
Note that CoAP over UDP (and CoAP over DTLS over UDP) is still the recommended transport for constrained node networks 🌈, particularly when it's used together with block-wise transfer. CoAP over TCP is for the cases where the networking infrastructure leaves no other choice 😩. Using CoAP over TCP leads to a larger code size, more round trips, increased RAM requirements, and larger packet sizes. Developers implementing CoAP over TCP are encouraged to check out [TCP-in-IoT] for guidance on low-footprint TCP implementations for IoT devices ✨.
Standards built on CoAP, such as Lightweight Machine to Machine [LWM2M], currently use CoAP over UDP as their transport. Adding support for CoAP over TCP lets them address the issues above for specific deployments, and it protects investments in existing CoAP implementations and deployments 💜.
HTTP/2 could also potentially solve the enterprise firewall traversal problem, but moving from CoAP to HTTP/2 would bring extra costs and delays 🙈. There are also fewer HTTP/2 implementations for constrained devices compared to CoAP. And since CoAP also supports group communication using IP-layer multicast and unreliable communication, IoT devices would have to support HTTP/2 in addition to CoAP. Too much, bestie 💀.
CoAP can also be part of a web environment where the front end uses CoAP over UDP from IoT devices to a cloud infrastructure, and then CoAP over TCP runs between the back-end services 🦋. A TCP-to-UDP gateway can sit at the cloud boundary so it can talk to the UDP-based IoT device.
Last but not least, CoAP applications running inside a web browser might have no connectivity other than HTTP 🫣. In that case, the WebSocket Protocol [RFC6455] can carry CoAP requests and responses, instead of cross-proxying them via HTTP to an HTTP-to-CoAP cross-proxy. This preserves CoAP's functionality without translation, and in particular, the Observe Option [RFC7641] keeps working 👑.
To handle these deployment requirements, this document defines how to transport CoAP over TCP, CoAP over TLS, and CoAP over WebSockets. For these cases, the reliability offered by the transport protocol subsumes the reliability functions of the message layer used for CoAP over UDP. (Note that for both a reliable transport and the message layer for CoAP over UDP, the reliability offered is per transport hop: where proxies -- see Sections 5.7 and 10 of [RFC7252] -- are involved, that layer's reliability function does not extend end to end.) Figure 1 shows the layering:
+--------------------------------+
| Application |
+--------------------------------+
+--------------------------------+
| Requests/Responses/Signaling | CoAP (RFC 7252) / This Document
|--------------------------------|
| Message Framing | This Document
+--------------------------------+
| Reliable Transport |
+--------------------------------+
Figure 1: Layering of CoAP over Reliable TransportsThis document specifies how to access resources using CoAP requests and responses over the TCP, TLS, and WebSocket protocols. This lets connectivity-limited applications get end-to-end CoAP connectivity in one of two ways: (1) by talking CoAP directly with a CoAP server reachable over a TCP, TLS, or WebSocket connection, or (2) via a CoAP intermediary that proxies CoAP requests and responses between different transports, such as between WebSockets and UDP 🌸.
Section 7 updates [RFC7641] ("Observing Resources in the Constrained Application Protocol (CoAP)") for use with CoAP over reliable transports. [RFC7641] is an extension to CoAP that lets CoAP clients "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 that representation is updated.) 🔥
2. 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 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
This document assumes readers already know the terms and concepts used in [RFC6455], [RFC7252], [RFC7641], and [RFC7959] 🧠.
The term "reliable transport" is only used to refer to transport protocols, such as TCP, that provide reliable and ordered delivery of a byte stream 💜.
Block-wise Extension for Reliable Transport (BERT): Extends [RFC7959] to enable the use of larger messages over a reliable transport.
BERT Option: A Block1 or Block2 option that includes an SZX (block size) value of 7.
BERT Block: The payload of a CoAP message that is affected by a BERT Option in descriptive usage (see Section 2.1 of [RFC7959]).
Transport Connection: Underlying reliable byte-stream connection, as directly provided by TCP or indirectly provided via TLS or WebSockets.
Connection: Transport Connection, unless explicitly qualified otherwise.
Connection Initiator: The peer that opens a Transport Connection, i.e., the TCP active opener, TLS client, or WebSocket client.
Connection Acceptor: The peer that accepts the Transport Connection opened by the other peer, i.e., the TCP passive opener, TLS server, or WebSocket server.
3. CoAP over TCP 🦋
The request/response interaction model of CoAP over TCP is the same as CoAP over UDP. The main differences are in the message layer. The message layer of CoAP over UDP supports optional reliability by defining four types of messages: Confirmable, Non-confirmable, Acknowledgment, and Reset. On top of that, messages include a Message ID, which relates Acknowledgments to Confirmable messages and helps detect duplicate messages ✨.
Managing transport connections is left to the application. In other words, this specification doesn't describe how an application decides to open a connection or to reopen another one when failures happen (or what it counts as a failure; see also Section 5.4) 🤷. In particular, the Connection Initiator doesn't have to be the client of the first request placed on the connection. Some implementations will want dynamic connection management similar to the technique described in Section 6 of [RFC7230] for HTTP: open a connection when the first client request is ready to send, reuse that connection for subsequent messages until no more messages are sent for a certain time period and no requests are outstanding (possibly with a configurable idle time), and then start a release process (orderly shutdown) (see Section 5.5) 🍓. In implementations like this, connection releases or aborts may not be flagged as errors to the application, and may simply be handled by automatic reconnection once the need comes up again. Other implementations may use configured connections that stay open continuously and trigger management system notifications on release or abort. The protocol defined in this specification is meant to work with either model (or with other, application-specific connection management models) 💅.
3.1. Messaging Model
okay so, conceptually, CoAP over TCP swaps out most of the message layer from CoAP over UDP 💅 and adds a framing layer on top of the byte stream that TCP/TLS gives you ✨. That framing carries the length info for each message, which on datagram transports is handled by the UDP/DTLS datagram layer 🎀.
TCP already makes sure messages arrive reliably, so the message layer here is not required to support Acknowledgment messages or to detect duplicate messages 🙈 ngl that's a whole chunk of work gone. Because of that, both the Type and Message ID fields are no longer required and get removed from the message format for CoAP over TCP 🦋.
Figure 2 shows the difference between CoAP over UDP and CoAP over reliable transports. The removed Type and Message ID fields are marked with 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
transports
Figure 2: Comparison between CoAP over Unreliable Transports and
CoAP over Reliable Transports3.2. Message Format
The CoAP message format from [RFC7252], shown in Figure 3, depends on the datagram transport (UDP, or DTLS over UDP) to keep individual messages separate and to provide 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: CoAP Message Format as Defined in RFC 7252The message format for CoAP over TCP is very similar to the one for CoAP over UDP. Here's what's different 🌸
- Since the underlying TCP connection provides retransmissions and deduplication, there is no need for the reliability mechanisms provided by CoAP over UDP. The Type (T) and Message ID fields in the CoAP message header are elided.
- The Version (Vers) field is elided as well. In contrast to the message format of CoAP over UDP, the message format for CoAP over TCP does not include a version number. 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. If version negotiation needs to be addressed in the future, Capabilities and Settings Messages (CSMs) (see Section 5.3) have been specifically designed to enable such a potential feature.
- 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 header for CoAP over UDP), which includes the length information of variable size.
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 | Extended Length (if any, as chosen by Len) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Code | Token (if any, TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 4: CoAP Frame for Reliable TransportsHere's how the Length (Len) field works 🔥
- Length (Len): 4-bit unsigned integer. A value between 0 and 12 inclusive 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 after the Option Length field of the CoAP Options (see Section 3.1 of [RFC7252]) 🍓
For simplicity, Figure 4 shows a Payload Marker (0xFF). The Payload Marker indicates the start of the optional payload and is absent for zero-length payloads (see Section 3 of [RFC7252]). (If present, the Payload Marker is included in the message length, which counts from the start of the Options field to the end of the Payload field.)
For example, a CoAP message that just contains a 2.03 code with the Token 7f and no options or payload is encoded as shown in Figure 5 ✨
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 5: CoAP Message with No Options or PayloadThe semantics of the other CoAP header fields are left unchanged 💖
3.3. Message Transmission
Once a Transport Connection is established, each endpoint MUST send a CSM (see Section 5.3) as its first message on the connection 🎀 This message sets the initial settings and capabilities for the endpoint, like maximum message size or support for block-wise transfers. If options are absent from the CSM, base values are assumed.
To avoid a deadlock, the Connection Initiator MUST NOT wait for the Connection Acceptor to send its initial CSM before sending its own initial CSM. The Connection Acceptor, on the other hand, MAY wait for the Connection Initiator to send its initial CSM before sending its own initial CSM 🫶
To avoid unnecessary latency, a Connection Initiator MAY send additional messages after its initial CSM without waiting to receive the Connection Acceptor's CSM. It is important to note, though, that the Connection Acceptor's CSM might indicate capabilities that impact how the Connection Initiator is expected to communicate with the Connection Acceptor. For example, the Connection Acceptor's CSM could indicate a Max-Message-Size Option (see Section 5.3.1) that is smaller than the base value (1152) in order to limit both buffering requirements and head-of-line blocking 👑
Endpoints MUST treat a missing or invalid CSM as a connection error and abort the connection (see Section 5.6) 😭
CoAP requests and responses are exchanged asynchronously over the Transport 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 🦋 Each concurrent request is told apart by its Token, which is scoped locally to the connection.
The Transport Connection is bidirectional, so requests can be sent by both the entity that established the connection (Connection Initiator) and the remote host (Connection Acceptor). If one side does not implement a CoAP server, an error response MUST be returned for all CoAP requests from the other side. The simplest approach is to always return 5.01 (Not Implemented). A more elaborate mock server could also return 4.xx responses, such as 4.04 (Not Found) or 4.02 (Bad Option), where appropriate 💅
Retransmission and deduplication of messages are provided by TCP 🌈
3.4. Connection Health
Empty messages (Code 0.00) can always be sent and MUST be ignored by the recipient 🧚 This gives you a basic keepalive function that can refresh NAT bindings, which is lowkey so useful.
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 does not receive any notification for some time), it can send a CoAP Ping Signaling message (see Section 5.4) to test the Transport Connection and verify that the CoAP server is responsive 🔍
When the underlying Transport Connection is closed or reset, the signaling state and any observation state (see Section 7.4) associated with the connection are removed. Messages that are in flight may or may not be lost 💀
4. CoAP over WebSockets ✨
okay so CoAP over WebSockets is giving CoAP over TCP energy 🦋 It's intentionally super similar, so this section only spells out the differences between the two transports. no need to reread everything 💅
CoAP over WebSockets can show up in a few different setups 🌈 The most basic one is a CoAP client retrieving or updating a CoAP resource on a CoAP server that has a WebSocket endpoint (see Figure 6). The CoAP client acts as the WebSocket client, sets up a WebSocket connection, and sends a CoAP request, and the CoAP server sends back a CoAP response. That WebSocket connection can be reused for any number of requests 🔥
___________ ___________
| | | |
| _|___ requests ___|_ |
| CoAP / \ \ -------------> / / \ CoAP |
| Client \__/__/ <------------- \__\__/ Server |
| | responses | |
|___________| |___________|
WebSocket =============> WebSocket
Client Connection Server
Figure 6: CoAP Client (WebSocket Client) Accesses CoAP Server
(WebSocket Server)The tricky part with this setup is figuring out how to identify a resource in the CoAP server's namespace 🙈 When a dedicated client uses the WebSocket Protocol directly (so not from a web page through a browser), it can connect to any WebSocket endpoint. Sections 8.3 and 8.4 define new URI schemes that let the client name both a WebSocket endpoint and the path and query of the CoAP resource inside that endpoint.
Another option is a CoAP forward proxy sitting at the WebSocket endpoint. Depending on which transports the proxy can reach, it could forward the request to a CoAP server with a CoAP UDP endpoint (Figure 7), an SMS endpoint (a.k.a. mobile phone), or even another WebSocket endpoint. The CoAP client names the resource to be updated or retrieved in the Proxy-Uri Option 🧚
___________ ___________ ___________
| | | | | |
| _|___ ___|_ _|___ ___|_ |
| CoAP / \ \ ---> / / \ CoAP / \ \ ---> / / \ CoAP |
| Client \__/__/ <--- \__\__/ Proxy \__/__/ <--- \__\__/ Server |
| | | | | |
|___________| |___________| |___________|
WebSocket ===> WebSocket UDP UDP
Client Server Client Server
Figure 7: CoAP Client (WebSocket Client) Accesses CoAP Server
(UDP Server) via a CoAP Proxy (WebSocket Server / UDP Client)A third possibility is a CoAP server running inside a web browser (Figure 8) 💜 The browser first 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
Figure 8: CoAP Client (UDP Client) Accesses CoAP Server (WebSocket
Client) via a CoAP Proxy (UDP Server / WebSocket Server)Further configurations are possible, including ones where a WebSocket connection is established through an HTTP proxy 🌸
4.1. Opening Handshake
Before CoAP requests and responses get swapped, a WebSocket connection is established as defined in Section 4 of [RFC6455]. Figure 9 shows an example 🎀
The WebSocket client MUST include the subprotocol name "coap" in the list of protocols. This is how it signals that it supports the protocol defined in this document.
The WebSocket client puts the hostname of the WebSocket server in the Host header field of its handshake, as per [RFC6455]. The Host header field also sets 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
Figure 9: Example of an Opening Handshake4.2. Message Format
Once the WebSocket connection is up, CoAP requests and responses can be exchanged as WebSocket messages. Since CoAP uses a binary message format, the messages are sent in binary data frames as specified in Sections 5 and 6 of [RFC6455] 🫶
The message format in Figure 10 is the same as the one for CoAP over TCP (see Section 3.2), with one change: the Length (Len) field MUST be set to zero, because the WebSocket frame already 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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Len=0 | TKL | Code | Token (TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1| Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 10: CoAP Message Format over WebSocketsJust like CoAP over TCP, the message format for CoAP over WebSockets gets rid of the Version field from CoAP over UDP 🙌 If CoAP version negotiation is ever needed in the future, CoAP over WebSockets can handle it by defining a new subprotocol identifier that gets negotiated during the opening handshake.
Requests and responses can be fragmented as specified in Section 5.4 of [RFC6455]. Typically, though, they are sent unfragmented, since they tend to be small and fully buffered before transmission. The WebSocket Protocol doesn't provide any means for multiplexing. If it isn't desirable for a large message to monopolize the connection, requests and responses can be transferred in a block-wise fashion as defined in [RFC7959] 💅
4.3. Message Transmission
Just like with CoAP over TCP, each endpoint MUST send a CSM (see Section 5.3) as its 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. Each concurrent request is told apart by its Token, which is scoped locally to the connection 🦋
The connection is bidirectional, so requests can be sent by both the entity that established the connection and the remote host ✨
Just like with CoAP over TCP, retransmission and deduplication of messages are provided by the WebSocket Protocol. So CoAP over WebSockets doesn't distinguish between Confirmable messages and Non-confirmable messages, and it doesn't provide Acknowledgment or Reset messages 🙈
4.4. Connection Health
Same as CoAP over TCP, a CoAP client can test the health of the connection for CoAP over WebSockets by sending a CoAP Ping Signaling message (Section 5.4). To make sure redundant maintenance traffic isn't sent, WebSocket Ping and unsolicited Pong frames (Section 5.5 of [RFC6455]) SHOULD NOT be used 🌈
5. Signaling 🚦
Signaling messages are introduced specifically for CoAP over reliable transports, so that peers can:
- Learn related characteristics, such as the maximum message size for the connection.
- Shut down the connection in an orderly fashion.
- Provide 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. They have a code, a Token, options, and an optional payload 🧚
(See Section 3 of [RFC7252] for the overall structure of the message format, option format, and option value formats.)
5.1. Signaling Codes
A code in the 7.00-7.31 range indicates a Signaling message. Values in this range are assigned by the "CoAP Signaling Codes" subregistry (see Section 11.1) 🔢
For each message, there is a sender and a peer receiving the message.
Payloads in Signaling messages are diagnostic payloads as defined in Section 5.5.2 of [RFC7252], unless otherwise defined by a Signaling message option 🎀
5.2. Signaling Option Numbers
Option Numbers for Signaling messages are specific to the message code. They don't 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" subregistry (see Section 11.2).
Signaling Options are elective or critical, as defined in Section 5.4.1 of [RFC7252]. If a Signaling Option is critical and not understood by the receiver, it MUST abort the connection (see Section 5.6). If the option is understood but can't be processed, the option documents the behavior 😭
5.3. Capabilities and Settings Messages (CSMs)
CSMs are used for two purposes:
- Each capability option indicates one capability of the sender to the recipient.
- Each setting option indicates a setting that will be applied by the sender.
One CSM MUST be sent by each endpoint at the start of the Transport Connection. Additional CSMs MAY be sent at any other time by either endpoint over the lifetime of the connection 🫧
Both capability options and setting options are cumulative. A CSM does not invalidate a previously sent capability indication or setting, even if it isn't repeated. A capability message without any option is a no-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 the capability and settings before any CSMs send a modified value.
These are not default values (as defined in Section 5.4.4 in [RFC7252]) for the option. Default values apply on a per-message basis and are thus reset when the value is not present in a given CSM.
CSMs are indicated by the 7.01 (CSM) code; see Table 1 (Section 11.1) ✨
5.3.1. Max-Message-Size Capability Option ✨
okay so the elective Max-Message-Size Option is how a sender says "hey, this is the biggest message I can receive, in bytes" 💅. The size counts the whole message, from the very first byte of the message header all the way to the end of the message payload 📏.
ngl this is NOT the same as the total body size you can move with block-wise transfer 🙈. (Like, Figure 13 (Section 6.1) still works if the CoAP client only says around 6000 bytes for Max-Message-Size, even though the body that ends up at the client is 3072 + 5120 + 4711 = 12903 bytes. Wild, right? 🤯)
+---+---+---+---------+------------------+--------+--------+--------+
| # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value |
+---+---+---+---------+------------------+--------+--------+--------+
| 2 | | | CSM | Max-Message-Size | uint | 0-4 | 1152 |
+---+---+---+---------+------------------+--------+--------+--------+
C=Critical, R=RepeatableSo per Section 4.6 of [RFC7252], the base value is 1152, and that's also the value used when this option isn't implemented 🧚.
The active value of the Max-Message-Size Option gets replaced every time the option is sent with a modified value 🔄. Its starting value is its base value 🌸.
5.3.2. Block-Wise-Transfer Capability Option 🎀
+---+---+---+---------+------------------+--------+--------+--------+
| # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value |
+---+---+---+---------+------------------+--------+--------+--------+
| 4 | | | CSM | Block-Wise- | empty | 0 | (none) |
| | | | | Transfer | | | |
+---+---+---+---------+------------------+--------+--------+--------+
C=Critical, R=RepeatableA sender can use the elective Block-Wise-Transfer Option to say it supports the block-wise transfer protocol [RFC7959] 🦋.
If the option isn't given, the peer has zero info about whether the sender does block-wise transfers 🫠. So an implementation that wants to offer block-wise transfers to its peer needs to say so with the Block-Wise-Transfer Option. No mind reading allowed, bestie 🔮.
Now the BERT part, which is lowkey the spicy bit 🌶️. If a Max-Message-Size Option is indicated with a value greater than 1152 (in the same CSM or a different one), the Block-Wise-Transfer Option also indicates support for BERT (see Section 6) ✨. Then, if the Max-Message-Size Option later comes in with a value equal to or less than 1152, BERT support is no longer indicated 💔. (Note that indicating BERT support doesn't oblige either peer to actually use BERT 🙅♀️.)
Implementation note: if you're indicating a Max-Message-Size value to turn BERT on, you might want to (1) pick a particular BERT block size you want to encourage, and (2) add a delta for the header and any options that also need to go into a message with a BERT block that size 🎀. Section 4.6 of [RFC7252] adds 128 bytes to a maximum block size of 1024 to get a default message size of 1152. A BERT-enabled implementation might want to indicate a BERT block size of 2048 (or a higher multiple of 1024) and be a bit more generous with the header and options size (say, 256 or 512) 💅. But adding 1024 or more to the base BERT block size may encourage the peer to vary its BERT block size based on the size of the options included, and that kind of setup could make interop harder 😭.
5.4. Ping and Pong Messages 🏓
In CoAP over reliable transports, Empty messages (Code 0.00) can always be sent, and they MUST be ignored by the recipient 🫶. That's your basic keepalive vibe. Ping and Pong messages are different: they're a bidirectional exchange 🔁.
When a Ping message comes in, the receiver MUST send back a Pong message with an identical Token 💜. Unless the Ping carries an option with delaying semantics (like the Custody Option), it SHOULD respond as soon as practical ⚡. As with all Signaling messages, the recipient of a Ping or Pong message MUST ignore any elective options it doesn't understand 🙈.
Ping and Pong messages are indicated by the 7.02 code (Ping) and the 7.03 code (Pong) 🌈.
Also, as with similar mechanisms in [RFC6455] and [RFC7540], this spec does NOT define a maximum time the sender of a Ping has to wait for a Pong reply ⏳. How patient you are with that reply is up to the application using these messages, and so is how to recover if a reply never shows up 🤷♀️.
5.4.1. Custody Option 📦
+---+---+---+----------+----------------+--------+--------+---------+
| # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value |
+---+---+---+----------+----------------+--------+--------+---------+
| 2 | | | Ping, | Custody | empty | 0 | (none) |
| | | | Pong | | | | |
+---+---+---+----------+----------------+--------+--------+---------+
C=Critical, R=RepeatableWhen responding to a Ping message, the receiver can include an elective Custody Option in the Pong message 🎁. This option tells the sender that the application has processed all the request/response messages received before the Ping on the current connection ✅. (Note that there's no definition of specific application semantics for "processed", but there IS an expectation that the receiver of a Pong with a Custody Option should be able to free buffers based on this indication 🧹.)
A sender can also include an elective Custody Option in a Ping message to explicitly ask for an elective Custody Option in the matching Pong message 🙋♀️. In that case, the receiver SHOULD delay its Pong message until it finishes processing all the request/response messages received before the Ping on the current connection ⏸️.
5.5. Release Messages 👋
A Release message says the sender doesn't want to keep the Transport Connection going, and it's opting for an orderly shutdown 🌷. But it leaves it to the peer to actually start closing the connection. The details live in the options 🗂️. A diagnostic payload (see Section 5.5.2 of [RFC7252]) MAY be included 🩺.
A peer will normally respond to a Release message by closing the Transport Connection 🚪. (And if that doesn't happen, the sender of the Release may want a timeout mechanism, if getting rid of the connection actually matters to it ⏰.)
Messages might be in flight, or responses might still be outstanding, when the sender decides to send a Release (which is one reason it waited before closing the connection in the first place) 🛫. The peer responding to the Release SHOULD delay closing the connection until it has responded to all the requests it got before the Release. It also MAY wait for responses to its own requests ⏳.
It is NOT RECOMMENDED for the sender of a Release to keep sending requests on the connection it already said was being released 🚫. The peer might close the connection at any time and miss those requests 💀. The peer isn't obligated to check for this, though 🤷♀️.
Release messages are indicated by the 7.04 code (Release) 🏷️.
Release messages can indicate one or more reasons using elective options 💭. Here's the one that's defined:
+---+---+---+---------+------------------+--------+--------+--------+
| # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value |
+---+---+---+---------+------------------+--------+--------+--------+
| 2 | | x | Release | Alternative- | string | 1-255 | (none) |
| | | | | Address | | | |
+---+---+---+---------+------------------+--------+--------+--------+
C=Critical, R=RepeatableThe elective Alternative-Address Option asks the peer to open a connection instead, using the same scheme as the current connection, to the alternative transport address given 🌍. Its value is in the form "authority" as defined in Section 3.2 of [RFC3986]. (State tied to the current connection doesn't get carried over to the new one 📭.)
The Alternative-Address Option is a repeatable option, as defined in Section 5.4.5 of [RFC7252] 🔁. If it shows up more than once, the peer can pick any of the alternative transport addresses 🎲.
+---+---+---+---------+-----------------+--------+--------+---------+
| # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value |
+---+---+---+---------+-----------------+--------+--------+---------+
| 4 | | | Release | Hold-Off | uint | 0-3 | (none) |
+---+---+---+---------+-----------------+--------+--------+---------+
C=Critical, R=RepeatableThe elective Hold-Off Option says the server is asking the peer not to reconnect to it for the number of seconds given in the value ⏲️💖.
5.6. Abort Messages ✨
Okay bestie, an Abort message is the "I'm literally leaving rn, no time for goodbyes" move 💀. The sender can't keep the Transport Connection going and doesn't even have time for an orderly release. So it shuts the connection down right after sending the Abort (and it may or may not wait for a Release message, an Abort message, or a connection shutdown coming the other way 🙈). A diagnostic payload (see Section 5.5.2 of [RFC7252]) SHOULD be included in the Abort message 💖. Messages might be in flight, or responses might still be outstanding, when the sender decides to send an Abort. The general expectation is that these will NOT be processed 😭.
Abort messages are indicated by the 7.05 code (Abort) 🎀.
Abort messages can point out one or more reasons using elective options. Here's the one option that's defined 👑:
+---+---+---+---------+-----------------+--------+--------+---------+
| # | C | R | Applies | Name | Format | Length | Base |
| | | | to | | | | Value |
+---+---+---+---------+-----------------+--------+--------+---------+
| 2 | | | Abort | Bad-CSM-Option | uint | 0-2 | (none) |
+---+---+---+---------+-----------------+--------+--------+---------+
C=Critical, R=RepeatableBad-CSM-Option is elective 🌸. It tells the other side that the sender can't process the CSM option identified by its Option Number. That can happen, for example, when the option is critical and the sender doesn't know its Option Number, or when an elective option has a parameter problem with its value. More detailed info SHOULD be included as a diagnostic payload 🧚.
For CoAP over UDP, messages with syntax violations get processed as message format errors. As described in Sections 4.2 and 4.3 of [RFC7252], those messages get rejected by sending a matching Reset message, and otherwise the message gets ignored 🦋.
For CoAP over reliable transports, the recipient rejects those messages by sending an Abort message, and otherwise ignores (doesn't process) the message ✨. No specific Option has been defined for the Abort message in this case, because the details are best left to a diagnostic payload 💅.
5.7. Signaling Examples 🍓
Here's an encoded example of a Ping message with a non-empty Token 🧁:
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 = 0x42Figure 11: Ping Message Example
And here's the matching Pong message 💜:
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 = 0x42Figure 12: Pong Message Example
6. Block-Wise Transfer and Reliable Transports 🌈
Okay so, the message size limits from Section 4.6 of [RFC7252] exist to avoid IP fragmentation, and they aren't needed over a reliable transport 🙌. You might think that means the block-wise transfer protocol [RFC7959] is also no longer needed, but nope, it still matters in a few cases 👀:
- Large messages, like firmware downloads, can cause undesired head-of-line blocking when a single transport connection is used 😬.
- A UDP-to-TCP gateway might not have the context to turn a message with a Block Option into the equivalent exchange without any Block Option. It would have to convert the whole block-wise exchange from start to end into one single exchange 🫠.
BERT is the extension that lets block-wise transfer handle larger messages over a reliable transport ✨.
You signal this new extension 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 read the same way as the equivalent Option with SZX == 6, except it also says "I can process BERT blocks" 🎀. Just like the basic block-wise transfer 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 read the same way as the equivalent Option with SZX == 6, except the payload is also allowed to contain multiple blocks 🍓. For non-final BERT blocks, the payload is always a multiple of 1024 bytes. For final BERT blocks, the payload is a multiple (possibly 0) of 1024 bytes plus a partial block of less than 1024 bytes 🌸.
The recipient of a non-final BERT block (M=1) conceptually splits the payload into a sequence of 1024-byte blocks. It acts exactly as if it had received that sequence with block numbers starting at the block number in the Block Option and going up by one each time. Put simply, the whole BERT block lands at the byte position you get by multiplying the block number by 1024 🦋. The position of the next blocks gets indicated by bumping the block number by the number of elements in that sequence (the payload size divided by 1024 bytes) 👑.
Same as with SZX == 6, the recipient of a final BERT block (M=0) just appends the payload at the byte position you get by multiplying the block number by 1024 💅.
The examples below show BERT Options in action 🧁. A value of SZX == 7 gets labeled as "BERT" or as "BERT(nnn)" to show a payload of size nnn.
In all these examples, a Block Option gets broken down into the kind of Block Option (1 or 2), then a colon, then the block number (NUM), the more bit (M), and the block size (2**(SZX + 4)), separated by slashes. For example, 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. 🙈
6.1. Example: GET with BERT Blocks
Figure 13 shows a GET request with a response that's split into three BERT blocks 📦. The first response has 3072 bytes of payload, the second has 5120, and the third has 4711. Notice how the block number goes up to move the position inside the response body forward 🚀.
CoAP 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) |Figure 13: GET with BERT Blocks
6.2. Example: PUT with BERT Blocks
Figure 14 shows a PUT exchange with BERT blocks 🌷.
CoAP 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 |
| |Figure 14: PUT with BERT Blocks
7. Observing Resources over Reliable Transports 👀
This section explains how the procedures from [RFC7641] for observing resources over CoAP get applied to reliable transports, and what gets modified along the way 💜. In this section, "client" and "server" refer to the CoAP client and CoAP server.
7.1. Notifications and Reordering
With CoAP over UDP, the Observe Option [RFC7641] gets used in notifications from the server. Each notification sets the option value to an increasing sequence number so the client can detect reordering, since messages can arrive in a different order than they were sent 🌀. That sequence number isn't required over reliable transports, because TCP already makes sure messages arrive reliably and in order 🫶. The value of the Observe Option in 2.xx notifications MAY be empty on transmission and MUST be ignored on reception ✨.
Implementation note: This means that a proxy going from a reordering transport to a reliable (in-order) transport, like a UDP-to-TCP proxy, needs to process the Observe Option in notifications according to the rules in Section 3.4 of [RFC7641] 🔥.
7.2. Transmission and Acknowledgments
With CoAP over UDP, server notifications to the client can be Confirmable or Non-confirmable. A Confirmable message requires the client to respond with either an Acknowledgment message or a Reset message. An Acknowledgment message says "I'm alive and I still want more notifications" 🌈. A Reset message says "I don't recognize this Token," and that makes the server remove the matching entry from its list of observers 😭.
Since TCP takes care of reliability, CoAP over reliable transports doesn't support Confirmable or Non-confirmable message types 🙅. Every notification gets delivered reliably to the client, and positive acknowledgment of receipt happens at the TCP level 💖. If the client doesn't recognize the Token in a notification, it MAY immediately abort the connection (see Section 5.6) 💀.
7.3. Freshness
With CoAP over UDP, if a client hasn't received a notification in a while, it can send a new GET request with the same Token as the original request. That re-registers its interest in the resource and checks that the server is still responsive 🔍. With CoAP over reliable transports, it's way more efficient to check the health of the connection (and all its active observations) by sending a single CoAP Ping Signaling message (Section 5.4), instead of sending individual requests to confirm each active observation 🧚. (Note that such a Ping/Pong only confirms a single hop. A proxy isn't obligated or expected to react to a Ping by checking all its own registered interests or all the connections, if any, underlying them 🙈. A proxy MAY maintain its own schedule for confirming the interests it relies on being registered toward the origin server. Still, it's generally inadvisable for a proxy to generate a large number of outgoing checks based on a single incoming check 🫠.)
7.4. Cancellation 🦋
okay so, over UDP, a client that's done with notifications can just "forget" the observation. The next time the server sends a notification, the client answers with a Reset message and the observation is cancelled. Easy peasy 💅
Over reliable transports it's a bit more intentional. A client MUST explicitly deregister by sending a GET request with the Token field set to the Token of the observation it wants to cancel. That GET also includes an Observe Option with the value 1, which means deregister 🫶
And on the server side, if the client observes one or more resources over a reliable transport, the CoAP server (or an intermediary acting as the CoAP server) MUST remove all entries tied to that client endpoint from its lists of observers when the connection either times out or gets closed. No ghost observers allowed 👻✨
8. CoAP over Reliable Transport URIs ✨
CoAP over UDP [RFC7252] already defines the coap and coaps URI schemes. This document adds four more so you can identify CoAP resources and say where to find them 🌸
- The
coap+tcpURI scheme for CoAP over TCP. - The
coaps+tcpURI scheme for CoAP over TCP secured by TLS. - The
coap+wsURI scheme for CoAP over WebSockets. - The
coaps+wsURI scheme for CoAP over WebSockets secured by TLS.
Resources behind these schemes have no shared identity, even if their resource identifiers point at the same authority (the same host listening on the same TCP port). They live in separate namespaces because each URI scheme implies a different origin server. Not the same girl, different vibes 💅
In this section, the syntax for the URI schemes is written in the Augmented Backus-Naur Form (ABNF) [RFC5234]. The definitions of host, port, path-abempty, and query are borrowed from [RFC3986].
Section 8 ("Multicast CoAP") in [RFC7252] doesn't apply to these schemes 🙈
Just like the coap and coaps schemes from [RFC7252], every scheme in this section also supports the /.well-known/ path prefix from [RFC5785] for "well-known locations" in a host's namespace. That's what makes discovery work, as described in Section 7 of [RFC7252] 🧚
8.1. coap+tcp URI Scheme
The coap+tcp URI scheme identifies CoAP resources that are meant to be reached using CoAP over TCP 🍓
coap-tcp-URI = "coap+tcp:" "//" host [ ":" port ]
path-abempty [ "?" query ]The syntax from Section 6.1 of [RFC7252] applies to this scheme, with one tweak:
- The port subcomponent is the TCP port where the CoAP Connection Acceptor lives. (If it's empty or not given, the default port 5683 is assumed, same as UDP.)
Encoding considerations: the scheme encoding follows the encoding rules for URIs in [RFC3986].
Interoperability considerations: none.
Security considerations: see Section 11.1 of [RFC7252].
8.2. coaps+tcp URI Scheme
The coaps+tcp URI scheme identifies CoAP resources that are meant to be reached using CoAP over TCP secured with TLS 🔒
coaps-tcp-URI = "coaps+tcp:" "//" host [ ":" port ]
path-abempty [ "?" query ]The syntax from Section 6.2 of [RFC7252] applies to this scheme, with a few changes:
- The port subcomponent is the TCP port where the TLS server for the CoAP Connection Acceptor lives. If it's empty or not given, the default port 5684 is assumed.
- If a TLS server doesn't support the Application-Layer Protocol Negotiation (ALPN) extension [RFC7301], or wants to accommodate TLS clients that don't support ALPN, it MAY offer a
coaps+tcpendpoint on TCP port 5684. That endpoint MAY also be ALPN enabled. A TLS server MAY offercoaps+tcpendpoints on ports other than TCP port 5684, and those MUST be ALPN enabled ✨ - For TCP ports other than port 5684, the TLS client MUST use the ALPN extension to advertise the "coap" protocol identifier (see Section 11.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, the connection succeeds. If the TLS server either doesn't negotiate the ALPN extension or returns a no_application_protocol alert, the TLS client MUST close the connection. 💀
- 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, the connection succeeds. If the TLS server returns a no_application_protocol alert, the TLS client MUST close the connection. If the TLS server doesn't negotiate the ALPN extension, then
coaps+tcpis implicitly selected. - For TCP port 5684, if the TLS client doesn't use the ALPN extension to negotiate the protocol, then
coaps+tcpis implicitly selected.
Encoding considerations: the scheme encoding follows the encoding rules for URIs in [RFC3986].
Interoperability considerations: none.
Security considerations: see Section 11.1 of [RFC7252].
8.3. coap+ws URI Scheme
The coap+ws URI scheme identifies CoAP resources that are meant to be reached using CoAP over WebSockets 🌈
coap-ws-URI = "coap+ws:" "//" host [ ":" port ]
path-abempty [ "?" query ]The port subcomponent is OPTIONAL. The default is port 80.
The WebSocket endpoint is identified by a "ws" URI made from the authority part of the coap+ws URI plus the well-known path /.well-known/coap [RFC5785] [RFC8307]. Inside the endpoint of a coap+ws URI, the path and query parts identify a resource that the CoAP methods can operate on, like so 👀
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 15: The "coap+ws" URI SchemeEncoding considerations: the scheme encoding follows the encoding rules for URIs in [RFC3986].
Interoperability considerations: none.
Security considerations: see Section 11.1 of [RFC7252].
8.4. coaps+ws URI Scheme
The coaps+ws URI scheme identifies CoAP resources that are meant to be reached using CoAP over WebSockets secured by TLS 🔐
coaps-ws-URI = "coaps+ws:" "//" host [ ":" port ]
path-abempty [ "?" query ]The port subcomponent is OPTIONAL. The default is port 443.
The WebSocket endpoint is identified by a "wss" URI made from the authority part of the coaps+ws URI plus the well-known path /.well-known/coap [RFC5785] [RFC8307]. Inside the endpoint of a coaps+ws URI, the path and query parts identify a resource that the CoAP methods can operate on:
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 16: The "coaps+ws" URI SchemeEncoding considerations: the scheme encoding follows the encoding rules for URIs in [RFC3986].
Interoperability considerations: none.
Security considerations: see Section 11.1 of [RFC7252].
8.5. Uri-Host and Uri-Port Options
CoAP over reliable transports keeps the property from Section 5.10.1 of [RFC7252], which says:
The default values for the Uri-Host and Uri-Port Options are sufficient for requests to most servers.
Unless noted otherwise, the default value of the Uri-Host Option is the IP literal for 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 defaults are the same, unless Server Name Indication (SNI) [RFC6066] is negotiated. In that 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 whatever the Host header field says in the WebSocket handshake.
8.6. Decomposing URIs into Options
The steps are the same as the ones in Section 6.4 of [RFC7252], with a couple of small updates 🧩
This step from [RFC7252]:
3. If |url| does not have a <scheme> component whose value, when
converted to ASCII lowercase, is "coap" or "coaps", then fail
this algorithm.is updated to:
3. If |url| does not have a <scheme> component whose value, when
converted to ASCII lowercase, is "coap+tcp", "coaps+tcp",
"coap+ws", or "coaps+ws", then fail this algorithm.This step from [RFC7252]:
7. If |port| does not equal the request's destination UDP port,
include a Uri-Port Option and let that option's value be |port|.is updated to:
7. If |port| does not equal the request's destination TCP port,
include a Uri-Port Option and let that option's value be |port|.8.7. Composing URIs from Options
The steps are the same as the ones in Section 6.5 of [RFC7252], with a couple of small updates ✨
This step from [RFC7252]:
1. If the request is secured using DTLS, let |url| be the string
"coaps://". Otherwise, let |url| be the string "coap://".is updated to:
1. 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://".This step from [RFC7252]:
4. If the request includes a Uri-Port Option, let |port| be that
option's value. Otherwise, let |port| be the request's
destination UDP port.is updated to:
4. If the request includes a Uri-Port Option, let |port| be that
option's value. Otherwise, let |port| be the request's
destination TCP port.9. Securing CoAP 🔐
"Security Challenges For the Internet Of Things" [SecurityChallenges] recommends the following, and honestly it's giving very good advice:
... it is essential that IoT protocol suites specify a mandatory to implement but optional to use security solution. This will ensure security is available 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.
So here's the big rule 🚨 A security solution MUST be implemented to protect CoAP over reliable transports, and it MUST be enabled by default. This document defines the TLS binding, but alternative solutions at different layers of the protocol stack MAY be used to protect CoAP over reliable transports when that makes sense. There's also ongoing work on a data-object-based security model for CoAP that doesn't depend on the transport (see [OSCORE]). Stay tuned, bestie 💜
9.1. TLS Binding for CoAP over TCP 🔐✨
Okay bestie, the TLS usage guidance in [RFC7925] applies here 💅. That includes the cipher suite guidance in that doc, which is derived from the mandatory-to-implement cipher suites in [RFC7252] 🎀.
This guidance assumes you're building for a constrained device, or talking to one 🧚. But CoAP over TCP/TLS is lowkey way more versatile than that 🌈. It could run on a gateway, or on a less constrained device like a smart phone or a tablet 📱, talking to a peer that's also less constrained. It could also live in a back-end environment that only talks to constrained devices through proxies 🖥️. As an exception to the previous paragraph, in this case, the recommendations in [RFC7525] are the better fit 💖.
Since [RFC7925] and [RFC7525] don't agree on algorithms and credential types 🙈, an implementation of CoAP over TCP/TLS that needs to support both cases should implement the recommendations from both specs. Multitasking, but make it secure 👑.
During the provisioning phase, a CoAP device gets the security info it needs, like keying materials, access control lists, and authorization servers 🔑. At the end of provisioning, the device will be in one of four security modes 🦋:
NoSec: TLS is 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 optional to implement 🙃. The system just sends packets over normal TCP. You can tell because it uses the coap+tcp scheme and the TCP CoAP default port 🍓. The system is only secured 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 for the TLS binding, depending on the credential type used with the device 💜. These modes use TLS, and you can spot them by the coaps+tcp scheme and the TLS-secured CoAP default port 🔥.
9.2. TLS Usage for CoAP over WebSockets 🕸️
A CoAP client that wants a resource identified by a coaps+ws URI negotiates a secure WebSocket connection to a WebSocket server endpoint with a wss URI 💌. This is described in Section 8.4.
The client MUST perform a TLS handshake after opening the connection to the server 🤝. The guidance in Section 4.1 of [RFC6455] applies. When a CoAP server exposes resources identified by a coaps+ws URI, the guidance in Section 4.4 of [RFC7925] applies for the mandatory-to-implement TLS functionality for certificates 📜. For the server-side requirements on accepting incoming connections over an HTTPS (HTTP over TLS) port, the guidance in Section 4.2 of [RFC6455] applies 🏰.
Heads up: the guidance above formally inherits the mandatory-to-implement cipher suites defined in [RFC5246] 🤓. But modern browsers usually implement newer cipher suites, and those get picked up automatically through the JavaScript WebSocket API ✨. So WebSocket servers that provide secure CoAP over WebSockets for the browser use case will need to follow browser preferences, and they MUST follow [RFC7525] 🫶.
10. Security Considerations 🛡️
The security considerations of [RFC7252] apply 🔒. For CoAP over WebSockets and CoAP over TLS-secured WebSockets, the security considerations of [RFC6455] also apply 💅.
10.1. Signaling Messages 📣
Okay, this one is SERIOUS 🚨. 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 💀. Just because the new connection works doesn't mean it's as safe as the old one 🥺.
11. IANA Considerations 📋
11.1. Signaling Codes 🏷️
IANA has created a third subregistry for values of the Code field in the CoAP header (Section 12.1 of [RFC7252]) 🗂️. The name of this subregistry is "CoAP Signaling Codes" 🌸.
Each entry in the subregistry must include the Signaling Code in the range 7.00-7.31, its name, and a reference to its documentation 📝.
Initial entries in this subregistry are below 👇:
+------+---------+-----------+
| Code | Name | Reference |
+------+---------+-----------+
| 7.01 | CSM | RFC 8323 |
| | | |
| 7.02 | Ping | RFC 8323 |
| | | |
| 7.03 | Pong | RFC 8323 |
| | | |
| 7.04 | Release | RFC 8323 |
| | | |
| 7.05 | Abort | RFC 8323 |
+------+---------+-----------+
Table 1: CoAP Signaling CodesAll other Signaling Codes are Unassigned 🫥.
The IANA policy for future additions to this subregistry is "IETF Review" or "IESG Approval" as described in [RFC8126] 🧐.
11.2. CoAP Signaling Option Numbers Registry 🔢
IANA has created a subregistry for Option Numbers used in CoAP Signaling Options within the "Constrained RESTful Environments (CoRE) Parameters" registry 🗃️. The name of this subregistry is "CoAP Signaling Option Numbers" ✨.
Each entry in the subregistry must include one or more of the codes in the "CoAP Signaling Codes" subregistry (Section 11.1), the number for the Option, the name of the Option, and a reference to the Option's documentation 📚.
Initial entries in this subregistry are below 👇:
+------------+--------+---------------------+-----------+
| Applies to | Number | Name | Reference |
+------------+--------+---------------------+-----------+
| 7.01 | 2 | Max-Message-Size | RFC 8323 |
| | | | |
| 7.01 | 4 | Block-Wise-Transfer | RFC 8323 |
| | | | |
| 7.02, 7.03 | 2 | Custody | RFC 8323 |
| | | | |
| 7.04 | 2 | Alternative-Address | RFC 8323 |
| | | | |
| 7.04 | 4 | Hold-Off | RFC 8323 |
| | | | |
| 7.05 | 2 | Bad-CSM-Option | RFC 8323 |
+------------+--------+---------------------+-----------+
Table 2: CoAP Signaling Option CodesThe IANA policy for future additions to this subregistry is based on number ranges for the option numbers, analogous to the policy defined in Section 12.2 of [RFC7252] 🎯. (It's analogous rather than identical because this subregistry has an extra column, "Applies to". But that column has no influence on the policy 🙃.)
The documentation for a Signaling Option Number should specify the semantics of an option with that number, including these properties 🧾:
- Whether the option is critical or elective, as determined by the Option Number.
- Whether the option is repeatable.
- The format and length of the option's value.
- The base value for the option, if any.
11.3. Service Name and Port Number Registration 🔌
IANA has assigned the port number 5683 and the service name "coap", in accordance with [RFC6335] 🎀.
Service Name:
coap
Transport Protocol:
tcp
Assignee:
IESG <iesg@ietf.org>
Contact:
IETF Chair <chair@ietf.org>
Description:
Constrained Application Protocol (CoAP)
Reference:
RFC 8323
Port Number:
568311.4. Secure Service Name and Port Number Registration 🔐
IANA has assigned the port number 5684 and the service name "coaps", in accordance with [RFC6335]. The port number is there to address the exceptional case of TLS implementations that don't support the ALPN extension [RFC7301] 🧩.
Service Name:
coaps
Transport Protocol:
tcp
Assignee:
IESG <iesg@ietf.org>
Contact:
IETF Chair <chair@ietf.org>
Description:
Constrained Application Protocol (CoAP)
Reference:
[RFC7301], RFC 8323
Port Number:
568411.5. URI Scheme Registration 🌐
URI schemes are registered within the "Uniform Resource Identifier (URI) Schemes" registry maintained at [IANA.uri-schemes] 🗺️.
Note: The following has been added as a note for each of the URI schemes defined in this document:
CoAP registers different URI schemes for accessing CoAP resources via different protocols. This approach runs counter to the WWW principle that a URI identifies a resource and that multiple URIs for identifying the same resource should be avoided <https://www.w3.org/TR/webarch/#avoid-uri-aliases>.
This is not a problem for many of the usage scenarios envisioned for CoAP over reliable transports 💖. Additional URI schemes can be introduced to address additional usage scenarios (as being prepared, for example, in [Multi-Transport-URIs] and [CoAP-Alt-Transports]) 🦋.
11.5.1. coap+tcp 🧦
IANA has registered the URI scheme "coap+tcp". This registration request complies with [RFC7595] ✅.
Scheme name:
coap+tcp
Status:
Permanent
Applications/protocols that use this scheme name:
The scheme is used by CoAP endpoints to access CoAP resources
using TCP.
Contact:
IETF Chair <chair@ietf.org>
Change controller:
IESG <iesg@ietf.org>
Reference:
Section 8.1 in RFC 832311.5.2. coaps+tcp 🔒
IANA has registered the URI scheme "coaps+tcp". This registration request complies with [RFC7595] ✅.
Scheme name:
coaps+tcp
Status:
Permanent
Applications/protocols that use this scheme name:
The scheme is used by CoAP endpoints to access CoAP resources
using TLS.
Contact:
IETF Chair <chair@ietf.org>
Change controller:
IESG <iesg@ietf.org>
Reference:
Section 8.2 in RFC 832311.5.3. coap+ws 🕸️
IANA has registered the URI scheme "coap+ws". This registration request complies with [RFC7595] ✅.
Scheme name:
coap+ws
Status:
Permanent
Applications/protocols that use this scheme name:
The scheme is used by CoAP endpoints to access CoAP resources
using the WebSocket Protocol.
Contact:
IETF Chair <chair@ietf.org>
Change controller:
IESG <iesg@ietf.org>
Reference:
Section 8.3 in RFC 832311.5.4. coaps+ws 🦄
IANA has registered the URI scheme "coaps+ws". This registration request complies with [RFC7595] ✅.
Scheme name:
coaps+ws
Status:
Permanent
Applications/protocols that use this scheme name:
The scheme is used by CoAP endpoints to access CoAP resources
using the WebSocket Protocol secured with TLS.
Contact:
IETF Chair <chair@ietf.org>
Change controller:
IESG <iesg@ietf.org>
References:
Section 8.4 in RFC 832311.6. Well-Known URI Suffix Registration 🧭
IANA has registered "coap" in the "Well-Known URIs" registry 🗝️. This registration request complies with [RFC5785] 💅.
URI suffix:
coap
Change controller:
IETF
Specification document(s):
RFC 8323
Related information:
None.11.7. ALPN Protocol Identifier ✨
Okay so IANA gave CoAP its own ALPN ID in the "Application-Layer Protocol Negotiation (ALPN) Protocol IDs" registry that [RFC7301] set up 💖. The coap string is how you spot CoAP when it's running over TLS 🔐.
- Protocol: CoAP
- Identification Sequence:
0x63 0x6f 0x61 0x70 ("coap") - Reference: RFC 8323
11.8. WebSocket Subprotocol Registration 🦋
IANA also registered the WebSocket CoAP subprotocol in the "WebSocket Subprotocol Name Registry" 🌸. The entry looks like this:
- Subprotocol Identifier:
coap - Subprotocol Common Name: Constrained Application Protocol (CoAP)
- Subprotocol Definition: RFC 8323
11.9. CoAP Option Numbers Registry 🎀
IANA added this document as a reference for two entries that [RFC7959] put in the "CoAP Option Numbers" subregistry, which [RFC7252] defined. Both options now point to RFC 7959 and RFC 8323 🧚
+--------+--------+--------------------+
| Number | Name | Reference |
+--------+--------+--------------------+
| 23 | Block2 | RFC 7959, RFC 8323 |
| | | |
| 27 | Block1 | RFC 7959, RFC 8323 |
+--------+--------+--------------------+
Table 3: CoAP Option Numbers12. References 📚
12.1. Normative References
These are the must-reads, bestie 🫶
[RFC793] Postel, J., "Transmission Control Protocol", STD 7,
RFC 793, DOI 10.17487/RFC0793, September 1981,
<https://www.rfc-editor.org/info/rfc793>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://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,
<https://www.rfc-editor.org/info/rfc3986>.
[RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for
Syntax Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008,
<https://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,
<https://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,
<https://www.rfc-editor.org/info/rfc6066>.
[RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol",
RFC 6455, DOI 10.17487/RFC6455, December 2011,
<https://www.rfc-editor.org/info/rfc6455>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014,
<https://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, <https://www.rfc-editor.org/info/rfc7301>.
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525,
May 2015, <https://www.rfc-editor.org/info/rfc7525>.
[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,
<https://www.rfc-editor.org/info/rfc7595>.
[RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015,
<https://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,
<https://www.rfc-editor.org/info/rfc7925>.
[RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in
the Constrained Application Protocol (CoAP)", RFC 7959,
DOI 10.17487/RFC7959, August 2016,
<https://www.rfc-editor.org/info/rfc7959>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in
RFC 2119 Key Words", BCP 14, RFC 8174,
DOI 10.17487/RFC8174, May 2017,
<https://www.rfc-editor.org/info/rfc8174>.
[RFC8307] Bormann, C., "Well-Known URIs for the WebSocket Protocol",
RFC 8307, DOI 10.17487/RFC8307, January 2018,
<https://www.rfc-editor.org/info/rfc8307>.12.2. Informative References
These are the extra-credit reads for when you want the full tea ☕💅
[BK2015] Byrne, C. and J. Kleberg, "Advisory Guidelines for UDP
Deployment", Work in Progress, draft-byrne-opsec-udp-
advisory-00, July 2015.
[CoAP-Alt-Transports]
Silverajan, B. and T. Savolainen, "CoAP Communication with
Alternative Transports", Work in Progress,
draft-silverajan-core-coap-alternative-transports-10,
July 2017.
[CoCoA] Bormann, C., Betzler, A., Gomez, C., and I. Demirkol,
"CoAP Simple Congestion Control/Advanced", Work in
Progress, draft-ietf-core-cocoa-02, October 2017.
[EK2016] Edeline, K., Kuehlewind, M., Trammell, B., Aben, E., and
B. Donnet, "Using UDP for Internet Transport Evolution",
arXiv preprint 1612.07816, December 2016,
<https://arxiv.org/abs/1612.07816>.
[HomeGateway]
Haetoenen, S., Nyrhinen, A., Eggert, L., Strowes, S.,
Sarolahti, P., and N. Kojo, "An experimental study of home
gateway characteristics", Proceedings of the 10th ACM
SIGCOMM conference on Internet measurement,
DOI 10.1145/1879141.1879174, November 2010.
[IANA.uri-schemes]
IANA, "Uniform Resource Identifier (URI) Schemes",
<https://www.iana.org/assignments/uri-schemes>.
[LWM2M] Open Mobile Alliance, "Lightweight Machine to Machine
Technical Specification Version 1.0", February 2017,
<http://www.openmobilealliance.org/release/LightweightM2M/
V1_0-20170208-A/
OMA-TS-LightweightM2M-V1_0-20170208-A.pdf>.
[Multi-Transport-URIs]
Thaler, D., "Using URIs With Multiple Transport Stacks",
Work in Progress, draft-thaler-appsawg-multi-transport-
uris-01, July 2017.
[OSCORE] Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
"Object Security for Constrained RESTful Environments
(OSCORE)", Work in Progress, draft-ietf-core-object-
security-08, January 2018.
[RFC768] Postel, J., "User Datagram Protocol", STD 6, RFC 768,
DOI 10.17487/RFC0768, August 1980,
<https://www.rfc-editor.org/info/rfc768>.
[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,
<https://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, <https://www.rfc-editor.org/info/rfc6347>.
[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,
<https://www.rfc-editor.org/info/rfc7230>.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
DOI 10.17487/RFC7540, May 2015,
<https://www.rfc-editor.org/info/rfc7540>.
[SecurityChallenges]
Polk, T. and S. Turner, "Security Challenges For the
Internet Of Things", Interconnecting Smart Objects with
the Internet / IAB Workshop, February 2011,
<https://www.iab.org/wp-content/IAB-uploads/2011/03/
Turner.pdf>.
[SW2016] Swett, I., "QUIC Deployment Experience @Google", IETF 96
Proceedings, Berlin, Germany, July 2016,
<https://www.ietf.org/proceedings/96/slides/
slides-96-quic-3.pdf>.
[TCP-in-IoT]
Gomez, C., Crowcroft, J., and M. Scharf, "TCP Usage
Guidance in the Internet of Things (IoT)", Work in
Progress, draft-ietf-lwig-tcp-constrained-node-
networks-01, October 2017.Appendix A. Examples of CoAP over WebSockets ✨
okay bestie, this appendix gives examples for the first two configurations from Section 4 💅 🦋
so picture a CoAP client that wants the representation of a resource with a coap+ws URI 🧚 here's how it goes down, step by step:
- the CoAP client gets the URI
<coap+ws://example.org/sensors/temperature?u=Cel>, say from a resource representation it grabbed earlier 🍓 - the CoAP client opens a WebSocket connection to the endpoint URI made from the authority "example.org" and the well-known path "/.well-known/coap", which is
<ws://example.org/.well-known/coap>✨ - CSMs (Section 5.3) get exchanged (not shown) 🫶
- the CoAP client sends a single-frame, masked, binary message with a CoAP request inside 💜 the request points at the target resource with the Uri-Path ("sensors", "temperature") and Uri-Query ("u=Cel") Options
- the CoAP client waits for the server to send back a response 🌸
- the CoAP client keeps using the connection for more requests, or the connection gets closed 👑
Figure 17 shows all of this in detail, WebSocket and CoAP messages included, so you can literally watch it happen 👀
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
: :
:<-------->: Exchange of CSMs (not shown)
| |
+--------->| 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)
| |
Figure 17: A CoAP Client Retrieves the Representation of a Resource
Identified by a "coap+ws" URINow for the second example, and this one is extra 🌈 Figure 18 shows how a CoAP client uses a CoAP forward proxy with a WebSocket endpoint to get the representation of the resource "coap://[2001:db8::1]/" 🦋 The client works out the forward proxy and the WebSocket endpoint's address from local configuration rules, so it already knows where to go. The request URI goes in the Proxy-Uri Option. Since that URI uses the "coap" URI scheme, the proxy handles it by sending a Confirmable GET request over UDP to the CoAP server, then passing the response back 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" |
| | | +------------------------------------+
| | |
Figure 18: A CoAP Client Retrieves the Representation of a Resource
Identified by a "coap" URI via a WebSocket-Enabled CoAP ProxyAcknowledgments ✨
we owe a huge thank-you to Stephen Berard, Geoffrey Cristallo, Olivier Delaby, Esko Dijk, Christian Groves, Nadir Javed, Michael Koster, Achim Kraus, David Navarro, Szymon Sasin, Goeran Selander, Zach Shelby, Andrew Summers, Julien Vermillard, and Gengyu Wei for their feedback 🫶
the Last Call reviews from Yoshifumi Nishida, Mark Nottingham, and Meral Shirazipour, plus several IESG reviewers, left extensive comments that made this so much better 💅 From the IESG, we want to specifically call out Ben Campbell, Mirja Kuehlewind, Eric Rescorla, Adam Roach, and the responsible AD Alexey Melnikov 👑
Contributors 🎀
these lovely people helped write the document too 💖
Matthias Kovatsch
Siemens AG
Otto-Hahn-Ring 6
Munich D-81739
Germany
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, IL 60607
United States of America
Phone: +1-847-634-6700
Email: vsolorzanobarboza@zebra.comAuthors' Addresses 💌
and here are the authors, so you know exactly who to thank (or DM) 🧚
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, IL 60607
United States of America
Phone: +1-847-634-6700
Email: slemay@zebra.com
Hannes Tschofenig
ARM Ltd.
110 Fulbourn Road
Cambridge CB1 9NJ
United Kingdom
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)
Email: brianraymor@hotmail.com📦 where this page comes from
- ietf: rfc8323 2018-02
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms