The Constrained Application Protocol (CoAP)
updated by
- rfc-7959 — Block-Wise Transfers in the Constrained Application Protocol (CoAP)
- rfc-8613 — Object Security for Constrained RESTful Environments (OSCORE)
- rfc-8974 — Extended Tokens and Stateless Clients in the Constrained Application Protocol (CoAP)
- rfc-9175 — Constrained Application Protocol (CoAP): Echo, Request-Tag, and Token Processing
- rfc-9876 — Updates to the IANA Registration Procedures for Constrained Application Protocol (CoAP) Content-Formats
Extracted elements (31)
CoAP's goal is not to blindly compress HTTP but to realize a subset of REST optimized for M2M and constrained environments, adding features absent from HTTP such as built-in multicast support, asynchronous exchanges, and very low overhead. Mapping to and from HTTP is straightforward but CoAP method semantics are 'almost, but not entirely unlike' those of HTTP and must be read independently.
The Token is kept conceptually separate from the Message ID because Message IDs serve the messaging layer (matching ACK/RST to CON/NON) while Tokens serve the request/response layer (matching responses to outstanding requests). This separation allows a single CON to carry a request while the response arrives in a separate message exchange with a different Message ID.
Cross-proxy translation between CoAP and HTTP requires mapping Method Codes (GET/POST/PUT/DELETE) and Response Codes bidirectionally. CoAP 2.05 Content maps to HTTP 200 OK; CoAP 4.04 maps to HTTP 404; HTTP OPTIONS and TRACE have no CoAP equivalent and MUST be rejected by an HTTP-to-CoAP proxy with 501 Not Implemented. Max-Age maps to HTTP Cache-Control max-age.
A CoAP message SHOULD fit within a single IP packet to avoid IP fragmentation. If the Path MTU is unknown, an IP MTU of 1280 bytes SHOULD be assumed; good upper bounds are 1152 bytes for message size and 1024 bytes for payload size.
A recipient of a Confirmable message MUST either acknowledge it with an ACK (echoing the Message ID) or reject it with a matching RST. Recipients of ACK and RST messages MUST NOT respond with either ACK or RST messages.
Clients (including proxies) MUST strictly limit simultaneous outstanding interactions to a given server to NSTART (default 1). An endpoint MUST NOT exceed an average data rate of PROBING_RATE (1 byte/second) when sending to a non-responding endpoint. Configurations MUST NOT decrease ACK_TIMEOUT or increase NSTART without mechanisms that ensure congestion control safety.
For multicast CoAP, only NON messages SHOULD be used for requests to multicast addresses. Responses to multicast requests MUST be suppressed if the server would return a 5.xx or 4.xx error. Servers SHOULD delay their response by a random interval within DEFAULT_LEISURE (5 s) to avoid a response implosion.
Once a server sends an Empty ACK for a CON request (initiating a separate response), it MUST NOT later send the response in another ACK. If a retransmitted request arrives, another Empty ACK is sent and the response MUST be sent as a separate response. The client's ACK to a Confirmable separate response MUST be an Empty message.
The GET method MUST NOT take any action on a resource other than retrieval. GET, PUT, and DELETE MUST be performed in an idempotent manner. POST is not idempotent.
The same Message ID MUST NOT be reused when communicating with the same endpoint within the EXCHANGE_LIFETIME (247 seconds with default parameters). An ACK or RST matches a CON or NON only if the Message ID and source endpoint of the reply match the Message ID and destination endpoint of the original message.
The server MUST echo the client's Token unmodified in any resulting response. A client sending a request without TLS SHOULD use a nontrivial, randomized token to guard against response spoofing; a client connected to the general Internet SHOULD use at least 32 bits of randomness.
The Version field in the CoAP header MUST be set to 1 (binary 01). Messages with unknown version numbers MUST be silently ignored.
Token Length values 9-15 are reserved, MUST NOT be sent, and MUST be processed as a message format error. The presence of a Payload Marker (0xFF) followed by a zero-length payload MUST also be processed as a message format error.
CoAP defines four message types: Confirmable (CON, requires ACK or RST), Non-confirmable (NON, no ACK required but has a Message ID for deduplication), Acknowledgement (ACK, echoes Message ID of CON), and Reset (RST, indicates missing context). Requests may be carried in CON or NON; responses may be carried in CON, NON, or piggybacked in ACK.
CoAP defines three response delivery modes: Piggybacked (response carried in the ACK message that acknowledges the CON request), Separate (server sends an Empty ACK immediately, then a new CON or NON carrying the response), and Non-confirmable (response in a NON message, used when request was NON). The server chooses which mode to use; the client MUST be prepared to receive any of them.
CoAP defines two URI schemes: 'coap' (default port 5683, no security) and 'coaps' (default port 5684, DTLS-secured). The client decomposes the URI into Uri-Host, Uri-Port, Uri-Path, and Uri-Query options before sending the request, using default values for efficiency; the server reconstructs the URI from these options.
CoAP options are classified as Critical (odd option number bit 0 set) or Elective (even), and as Safe-to-Forward or Unsafe for proxies. An endpoint that does not understand a critical option MUST return an error or reject the message; an endpoint that does not understand an elective option MUST silently ignore it. Proxies MUST forward safe-to-forward options even without understanding them.
CoAP Response Codes follow a c.dd notation where the 3-bit class encodes success (2), client error (4), or server error (5). Unrecognized 4.xx and 5.xx codes are treated as 4.00 and 5.00 respectively; unrecognized 2.xx codes indicate success without further detail. The full set of codes is maintained in the CoAP Response Code Registry.
CoAP transmission is governed by configurable parameters: ACK_TIMEOUT (2 s), ACK_RANDOM_FACTOR (1.5), MAX_RETRANSMIT (4), NSTART (1), DEFAULT_LEISURE (5 s), PROBING_RATE (1 byte/s). Derived values include EXCHANGE_LIFETIME (247 s), NON_LIFETIME (145 s), MAX_TRANSMIT_SPAN (45 s), and MAX_TRANSMIT_WAIT (93 s) with default settings.
Resource discovery uses the CoRE Link Format (RFC 6690) served at the well-known URI '/.well-known/core'. A CoAP client queries this resource to retrieve a list of hosted resources. Multicast service discovery uses the 'All CoAP Nodes' multicast address.
The Token (0-8 bytes) is a client-generated identifier used to match responses to requests independently of the Message ID. Every message carries a token (possibly zero-length); the server MUST echo it unmodified in any resulting response. The Token is separate from the Message ID: Message ID correlates CON/NON with ACK/RST at the messaging layer, while Token correlates requests with responses at the request/response layer.
This document establishes the 'CoAP Content-Formats' registry (Expert Review) mapping (media-type, content-coding) pairs to numeric identifiers; initial entries include text/plain;charset=utf-8 (0), application/link-format (40), application/xml (41), application/octet-stream (42), application/exi (47), application/json (50).
This document establishes the 'CoAP Method Codes' registry (Expert Review) containing GET (0.01), POST (0.02), PUT (0.03), DELETE (0.04), and the 'CoAP Response Codes' registry (Expert Review) with 2.xx success codes, 4.xx client error codes, and 5.xx server error codes.
This document establishes the 'CoAP Option Numbers' registry (IETF Review for 0-255, Expert Review for 256-65535) with initial entries including If-Match (1), Uri-Host (3), ETag (4), If-None-Match (5), Uri-Port (7), Location-Path (8), Uri-Path (11), Content-Format (12), Max-Age (14), Uri-Query (15), Accept (17), Location-Query (20), Proxy-Uri (35), Proxy-Scheme (39), Size1 (60).
CoAP defines four security modes: NoSec (no security), PreSharedKey (DTLS with pre-shared keys), RawPublicKey (DTLS with asymmetric keys without certificates), and Certificate (DTLS with X.509 certificates). The 'coaps' URI scheme signals mandatory use of DTLS; 'coap' URIs without explicit proxying use NoSec mode.
CoAP is susceptible to amplification attacks because a small multicast or unicast request can elicit large responses from many nodes. Servers SHOULD implement rate limiting for response transmission. For multicast, clients MUST NOT use CON messages; this limits the amplification factor.
Cross-protocol attacks are possible when a CoAP message is crafted to look like another protocol (e.g., HTTP). To mitigate, implementations parsing CoAP over TCP or TLS MUST verify the CoAP version and reject mismatched messages; endpoints SHOULD use DTLS to prevent injection of foreign-protocol messages.
IP address spoofing attacks are a concern since CoAP runs over UDP. Clients SHOULD use randomized tokens (at least 32 bits for Internet-connected clients) to guard against spoofed responses. ICMP errors should be verified against the original datagram's port, Message ID, and Token fields before acting on them.
Reliable transmission state: for each CON message, a sender maintains a timeout (initially random between ACK_TIMEOUT and ACK_TIMEOUT*ACK_RANDOM_FACTOR) and a retransmission counter (initially 0). On timeout, if counter < MAX_RETRANSMIT, the message is retransmitted, counter incremented, and timeout doubled. On counter reaching MAX_RETRANSMIT or receiving RST, transmission is canceled. On receiving ACK, transmission succeeds.
CoAP messages begin with a fixed 4-byte header containing: Ver (2-bit, MUST be 1), Type T (2-bit: CON/NON/ACK/RST), Token Length TKL (4-bit, 0-8), Code (8-bit, class.detail), and Message ID (16-bit network byte order). The header is followed by a variable-length Token (0-8 bytes), zero or more options, and an optional payload preceded by the 0xFF payload marker.
CoAP options are encoded in delta-TLV format: each option specifies a 4-bit Option Delta and 4-bit Option Length, with extended 1- or 2-byte fields for values 13 and 14 respectively. Options MUST appear in ascending Option Number order; the actual number is the sum of all preceding deltas. Delta or length value 15 is reserved and MUST be processed as a message format error.