CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets
updated by
- rfc-8974 — Extended Tokens and Stateless Clients in the Constrained Application Protocol (CoAP)
updates
Extracted elements (30)
Although block-wise transfer is no longer required for IP-fragmentation avoidance over TCP, it remains applicable for large messages (to avoid head-of-line blocking) and for UDP-to-TCP gateways that cannot reconstruct a complete body without block context.
CoAP over TCP was introduced primarily because UDP is completely blocked in approximately 2–4% of terrestrial access networks, with higher rates in enterprise environments. TCP also provides longer NAT binding lifetimes (mean 386 minutes vs. 160 seconds for UDP) and more sophisticated congestion/flow control for large payloads.
The Type (T) and Message ID fields from CoAP over UDP are elided in the TCP message format because TCP provides reliable delivery and deduplication, making those fields redundant. The Version field is also elided; if version negotiation is needed in the future, the CSM mechanism was specifically designed to enable that.
A CoAP client observing resources over a reliable transport MUST explicitly deregister by issuing a GET request with the Observe Option set to 1 (deregister), rather than relying on a Reset message as with CoAP over UDP.
A security solution MUST be implemented to protect CoAP over reliable transports and MUST be enabled by default. TLS is the defined binding, but alternative solutions at other protocol layers MAY be used when appropriate.
CoAP responses MUST be returned over the same connection as the originating request. Each concurrent request is differentiated by its Token, which is scoped locally to the connection.
Empty messages (Code 0.00) can always be sent and MUST be ignored by the recipient, providing a basic keepalive function that can refresh NAT bindings.
Endpoints MUST treat a missing or invalid CSM as a connection error and abort the connection.
For CoAP over reliable transports, the Observe Option value in 2.xx notifications MAY be empty on transmission and MUST be ignored on reception, since TCP guarantees ordered delivery and reordering detection is unnecessary.
For coaps+tcp on TCP ports other than 5684, the TLS client MUST use the ALPN extension to advertise the "coap" protocol identifier. If the server does not negotiate ALPN or returns no_application_protocol, the client MUST close the connection.
If a critical Signaling Option is not understood by the receiver, it MUST abort the connection. Elective options that are not understood MUST be ignored.
Once a Transport Connection is established, each endpoint MUST send a CSM as its first message on the connection to establish initial capabilities and settings.
The CoAP server MUST remove all observer list entries associated with a client endpoint when the reliable transport connection either times out or is closed.
The WebSocket client MUST include the subprotocol name "coap" in the list of protocols during the WebSocket opening handshake.
To avoid deadlock, the Connection Initiator MUST NOT wait for the Connection Acceptor to send its initial CSM before sending its own initial CSM.
Upon receipt of a Ping message (code 7.02), the receiver MUST return a Pong message (code 7.03) with an identical Token in response, and SHOULD respond as soon as practical unless the Ping carries the Custody Option.
Block-wise Extension for Reliable Transport (BERT) extends RFC 7959 by using SZX=7 (a reserved BERT Option value). In descriptive usage, a non-final BERT block payload MUST be a multiple of 1024 bytes; a final BERT block is a multiple of 1024 bytes plus a partial block of less than 1024 bytes.
Capabilities and Settings Messages (CSMs, code 7.01) carry capability options (what the sender can receive) and setting options (what the sender will apply). One CSM MUST be sent at connection start; additional CSMs MAY be sent later. Options are cumulative and not reset by subsequent CSMs.
Four new URI schemes are defined: coap+tcp (default port 5683), coaps+tcp (default port 5684), coap+ws (default port 80), and coaps+ws (default port 443). Resources under different schemes have distinct origins even if they share the same authority.
The Abort message (code 7.05) signals an immediate unrecoverable connection error. The sender shuts down immediately after sending. A diagnostic payload SHOULD be included. The Bad-CSM-Option (uint, 0–2 bytes) identifies the offending CSM option number.
The Block-Wise-Transfer Option (CSM option number 4) signals that the sender supports block-wise transfer per RFC 7959. When combined with a Max-Message-Size greater than 1152, it also indicates BERT support.
The Max-Message-Size Option (CSM option number 2) indicates the maximum message size in bytes the sender can receive. Its base value is 1152. Values greater than 1152 in combination with Block-Wise-Transfer Option also signal BERT support.
The Release message (code 7.04) signals an orderly shutdown request, leaving the peer to close the connection. It may carry the Alternative-Address Option (string, 1–255 bytes, repeatable) and Hold-Off Option (uint, 0–3 bytes) to redirect or throttle reconnections.
IANA created the "CoAP Signaling Codes" subregistry (codes 7.00–7.31) with initial entries: 7.01 CSM, 7.02 Ping, 7.03 Pong, 7.04 Release, 7.05 Abort. Future additions require IETF Review or IESG Approval.
IANA created the "CoAP Signaling Option Numbers" subregistry with initial entries: Max-Message-Size (7.01, #2), Block-Wise-Transfer (7.01, #4), Custody (7.02/7.03, #2), Alternative-Address (7.04, #2), Hold-Off (7.04, #4), Bad-CSM-Option (7.05, #2).
IANA registered four permanent URI schemes: coap+tcp, coaps+tcp, coap+ws, and coaps+ws. A note in each registration acknowledges that assigning distinct URI schemes per transport runs counter to the W3C principle of avoiding URI aliases for the same resource.
IANA registered port 5683 (service name "coap", TCP) and port 5684 (service name "coaps", TCP). Port 5684 addresses the exceptional case of TLS implementations that do not support the ALPN extension.
A peer MUST NOT assume that a successful connection to an Alternative-Address (received in a Release message) inherits all the security properties of the current connection. The guidance from an Alternative-Address Option cannot be followed blindly.
For CoAP over WebSockets, the message format is identical to CoAP over TCP except the Length (Len) field MUST be set to zero, because message length is provided by the WebSocket frame itself.
The CoAP over TCP frame replaces the fixed 4-byte UDP header with a variable-length framing header. A 4-bit Len field encodes message length (0–12 = literal bytes; 13 = 8-bit Extended Length minus 13; 14 = 16-bit Extended Length minus 269; 15 = 32-bit Extended Length minus 65805). The Version, Type, and Message ID fields are absent.