Preview
Open Original
Internet Engineering Task Force (IETF) Z. Shelby
Request for Comments: 7252 ARM
Category: Standards Track K. Hartke
ISSN: 2070-1721 C. Bormann
Universitaet Bremen TZI
June 2014
The Constrained Application Protocol (CoAP)
Abstract
The Constrained Application Protocol (CoAP) is a specialized web
transfer protocol for use with constrained nodes and constrained
(e.g., low-power, lossy) networks. The nodes often have 8-bit
microcontrollers with small amounts of ROM and RAM, while constrained
networks such as IPv6 over Low-Power Wireless Personal Area Networks
(6LoWPANs) often have high packet error rates and a typical
throughput of 10s of ...Internet Engineering Task Force (IETF) Z. Shelby
Request for Comments: 7252 ARM
Category: Standards Track K. Hartke
ISSN: 2070-1721 C. Bormann
Universitaet Bremen TZI
June 2014
The Constrained Application Protocol (CoAP)
Abstract
The Constrained Application Protocol (CoAP) is a specialized web
transfer protocol for use with constrained nodes and constrained
(e.g., low-power, lossy) networks. The nodes often have 8-bit
microcontrollers with small amounts of ROM and RAM, while constrained
networks such as IPv6 over Low-Power Wireless Personal Area Networks
(6LoWPANs) often have high packet error rates and a typical
throughput of 10s of kbit/s. The protocol is designed for machine-
to-machine (M2M) applications such as smart energy and building
automation.
CoAP provides a request/response interaction model between
application endpoints, supports built-in discovery of services and
resources, and includes key concepts of the Web such as URIs and
Internet media types. CoAP is designed to easily interface with HTTP
for integration with the Web while meeting specialized requirements
such as multicast support, very low overhead, and simplicity for
constrained environments.
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 has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc7252.
Shelby, et al. Standards Track [Page 1]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
2. Constrained Application Protocol . . . . . . . . . . . . . . 10
2.1. Messaging Model . . . . . . . . . . . . . . . . . . . . . 11
2.2. Request/Response Model . . . . . . . . . . . . . . . . . 12
2.3. Intermediaries and Caching . . . . . . . . . . . . . . . 15
2.4. Resource Discovery . . . . . . . . . . . . . . . . . . . 15
3. Message Format . . . . . . . . . . . . . . . . . . . . . . . 15
3.1. Option Format . . . . . . . . . . . . . . . . . . . . . . 17
3.2. Option Value Formats . . . . . . . . . . . . . . . . . . 19
4. Message Transmission . . . . . . . . . . . . . . . . . . . . 20
4.1. Messages and Endpoints . . . . . . . . . . . . . . . . . 20
4.2. Messages Transmitted Reliably . . . . . . . . . . . . . . 21
4.3. Messages Transmitted without Reliability . . . . . . . . 23
4.4. Message Correlation . . . . . . . . . . . . . . . . . . . 24
4.5. Message Deduplication . . . . . . . . . . . . . . . . . . 24
4.6. Message Size . . . . . . . . . . . . . . . . . . . . . . 25
4.7. Congestion Control . . . . . . . . . . . . . . . . . . . 26
4.8. Transmission Parameters . . . . . . . . . . . . . . . . . 27
4.8.1. Changing the Parameters . . . . . . . . . . . . . . . 27
4.8.2. Time Values Derived from Transmission Parameters . . 28
5. Request/Response Semantics . . . . . . . . . . . . . . . . . 31
5.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . 31
5.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 31
5.2.1. Piggybacked . . . . . . . . . . . . . . . . . . . . . 33
5.2.2. Separate . . . . . . . . . . . . . . . . . . . . . . 33
5.2.3. Non-confirmable . . . . . . . . . . . . . . . . . . . 34
5.3. Request/Response Matching . . . . . . . . . . . . . . . . 34
5.3.1. Token . . . . . . . . . . . . . . . . . . . . . . . . 34
5.3.2. Request/Response Matching Rules . . . . . . . . . . . 35
Shelby, et al. Standards Track [Page 2]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
5.4. Options . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.4.1. Critical/Elective . . . . . . . . . . . . . . . . . . 37
5.4.2. Proxy Unsafe or Safe-to-Forward and NoCacheKey . . . 38
5.4.3. Length . . . . . . . . . . . . . . . . . . . . . . . 38
5.4.4. Default Values . . . . . . . . . . . . . . . . . . . 38
5.4.5. Repeatable Options . . . . . . . . . . . . . . . . . 39
5.4.6. Option Numbers . . . . . . . . . . . . . . . . . . . 39
5.5. Payloads and Representations . . . . . . . . . . . . . . 40
5.5.1. Representation . . . . . . . . . . . . . . . . . . . 40
5.5.2. Diagnostic Payload . . . . . . . . . . . . . . . . . 41
5.5.3. Selected Representation . . . . . . . . . . . . . . . 41
5.5.4. Content Negotiation . . . . . . . . . . . . . . . . . 41
5.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.6.1. Freshness Model . . . . . . . . . . . . . . . . . . . 43
5.6.2. Validation Model . . . . . . . . . . . . . . . . . . 43
5.7. Proxying . . . . . . . . . . . . . . . . . . . . . . . . 44
5.7.1. Proxy Operation . . . . . . . . . . . . . . . . . . . 44
5.7.2. Forward-Proxies . . . . . . . . . . . . . . . . . . . 46
5.7.3. Reverse-Proxies . . . . . . . . . . . . . . . . . . . 46
5.8. Method Definitions . . . . . . . . . . . . . . . . . . . 47
5.8.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.8.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 47
5.8.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 48
5.8.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 48
5.9. Response Code Definitions . . . . . . . . . . . . . . . . 48
5.9.1. Success 2.xx . . . . . . . . . . . . . . . . . . . . 48
5.9.2. Client Error 4.xx . . . . . . . . . . . . . . . . . . 50
5.9.3. Server Error 5.xx . . . . . . . . . . . . . . . . . . 51
5.10. Option Definitions . . . . . . . . . . . . . . . . . . . 52
5.10.1. Uri-Host, Uri-Port, Uri-Path, and Uri-Query . . . . 53
5.10.2. Proxy-Uri and Proxy-Scheme . . . . . . . . . . . . . 54
5.10.3. Content-Format . . . . . . . . . . . . . . . . . . . 55
5.10.4. Accept . . . . . . . . . . . . . . . . . . . . . . . 55
5.10.5. Max-Age . . . . . . . . . . . . . . . . . . . . . . 55
5.10.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . 56
5.10.7. Location-Path and Location-Query . . . . . . . . . . 57
5.10.8. Conditional Request Options . . . . . . . . . . . . 57
5.10.9. Size1 Option . . . . . . . . . . . . . . . . . . . . 59
6. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.1. coap URI Scheme . . . . . . . . . . . . . . . . . . . . . 59
6.2. coaps URI Scheme . . . . . . . . . . . . . . . . . . . . 60
6.3. Normalization and Comparison Rules . . . . . . . . . . . 61
6.4. Decomposing URIs into Options . . . . . . . . . . . . . . 61
6.5. Composing URIs from Options . . . . . . . . . . . . . . . 62
7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 64
7.1. Service Discovery . . . . . . . . . . . . . . . . . . . . 64
7.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 64
7.2.1. 'ct' Attribute . . . . . . . . . . . . . . . . . . . 64
Shelby, et al. Standards Track [Page 3]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
8. Multicast CoAP . . . . . . . . . . . . . . . . . . . . . . . 65
8.1. Messaging Layer . . . . . . . . . . . . . . . . . . . . . 65
8.2. Request/Response Layer . . . . . . . . . . . . . . . . . 66
8.2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . 67
8.2.2. Proxying . . . . . . . . . . . . . . . . . . . . . . 67
9. Securing CoAP . . . . . . . . . . . . . . . . . . . . . . . . 68
9.1. DTLS-Secured CoAP . . . . . . . . . . . . . . . . . . . . 69
9.1.1. Messaging Layer . . . . . . . . . . . . . . . . . . . 70
9.1.2. Request/Response Layer . . . . . . . . . . . . . . . 71
9.1.3. Endpoint Identity . . . . . . . . . . . . . . . . . . 71
10. Cross-Protocol Proxying between CoAP and HTTP . . . . . . . . 74
10.1. CoAP-HTTP Proxying . . . . . . . . . . . . . . . . . . . 75
10.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . 76
10.1.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . 77
10.1.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 77
10.1.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 77
10.2. HTTP-CoAP Proxying . . . . . . . . . . . . . . . . . . . 77
10.2.1. OPTIONS and TRACE . . . . . . . . . . . . . . . . . 78
10.2.2. GET . . . . . . . . . . . . . . . . . . . . . . . . 78
10.2.3. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 79
10.2.4. POST . . . . . . . . . . . . . . . . . . . . . . . . 79
10.2.5. PUT . . . . . . . . . . . . . . . . . . . . . . . . 79
10.2.6. DELETE . . . . . . . . . . . . . . . . . . . . . . . 80
10.2.7. CONNECT . . . . . . . . . . . . . . . . . . . . . . 80
11. Security Considerations . . . . . . . . . . . . . . . . . . . 80
11.1. Parsing the Protocol and Processing URIs . . . . . . . . 80
11.2. Proxying and Caching . . . . . . . . . . . . . . . . . . 81
11.3. Risk of Amplification . . . . . . . . . . . . . . . . . 81
11.4. IP Address Spoofing Attacks . . . . . . . . . . . . . . 83
11.5. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 84
11.6. Constrained-Node Considerations . . . . . . . . . . . . 86
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 86
12.1. CoAP Code Registries . . . . . . . . . . . . . . . . . . 86
12.1.1. Method Codes . . . . . . . . . . . . . . . . . . . . 87
12.1.2. Response Codes . . . . . . . . . . . . . . . . . . . 88
12.2. CoAP Option Numbers Registry . . . . . . . . . . . . . . 89
12.3. CoAP Content-Formats Registry . . . . . . . . . . . . . 91
12.4. URI Scheme Registration . . . . . . . . . . . . . . . . 93
12.5. Secure URI Scheme Registration . . . . . . . . . . . . . 94
12.6. Service Name and Port Number Registration . . . . . . . 95
12.7. Secure Service Name and Port Number Registration . . . . 96
12.8. Multicast Address Registration . . . . . . . . . . . . . 97
13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 97
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 98
14.1. Normative References . . . . . . . . . . . . . . . . . . 98
14.2. Informative References . . . . . . . . . . . . . . . . . 100
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 104
Appendix B. URI Examples . . . . . . . . . . . . . . . . . . . . 110
Shelby, et al. Standards Track [Page 4]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
1. Introduction
The use of web services (web APIs) on the Internet has become
ubiquitous in most applications and depends on the fundamental
Representational State Transfer [REST] architecture of the Web.
The work on Constrained RESTful Environments (CoRE) aims at realizing
the REST architecture in a suitable form for the most constrained
nodes (e.g., 8-bit microcontrollers with limited RAM and ROM) and
networks (e.g., 6LoWPAN, [RFC4944]). Constrained networks such as
6LoWPAN support the fragmentation of IPv6 packets into small link-
layer frames; however, this causes significant reduction in packet
delivery probability. One design goal of CoAP has been to keep
message overhead small, thus limiting the need for fragmentation.
One of the main goals of CoAP is to design a generic web protocol for
the special requirements of this constrained environment, especially
considering energy, building automation, and other machine-to-machine
(M2M) applications. The goal of CoAP is not to blindly compress HTTP
[RFC2616], but rather to realize a subset of REST common with HTTP
but optimized for M2M applications. Although CoAP could be used for
refashioning simple HTTP interfaces into a more compact protocol,
more importantly it also offers features for M2M such as built-in
discovery, multicast support, and asynchronous message exchanges.
This document specifies the Constrained Application Protocol (CoAP),
which easily translates to HTTP for integration with the existing Web
while meeting specialized requirements such as multicast support,
very low overhead, and simplicity for constrained environments and
M2M applications.
1.1. Features
CoAP has the following main features:
o Web protocol fulfilling M2M requirements in constrained
environments
o UDP [RFC0768] binding with optional reliability supporting unicast
and multicast requests.
o Asynchronous message exchanges.
o Low header overhead and parsing complexity.
o URI and Content-type support.
o Simple proxy and caching capabilities.
Shelby, et al. Standards Track [Page 5]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
o A stateless HTTP mapping, allowing proxies to be built providing
access to CoAP resources via HTTP in a uniform way or for HTTP
simple interfaces to be realized alternatively over CoAP.
o Security binding to Datagram Transport Layer Security (DTLS)
[RFC6347].
1.2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
[RFC2119] when they appear in ALL CAPS. These words may also appear
in this document in lowercase, absent their normative meanings.
This specification requires readers to be familiar with all the terms
and concepts that are discussed in [RFC2616], including "resource",
"representation", "cache", and "fresh". (Having been completed
before the updated set of HTTP RFCs, RFC 7230 to RFC 7235, became
available, this specification specifically references the predecessor
version -- RFC 2616.) In addition, this specification defines the
following terminology:
Endpoint
An entity participating in the CoAP protocol. Colloquially, an
endpoint lives on a "Node", although "Host" would be more
consistent with Internet standards usage, and is further
identified by transport-layer multiplexing information that can
include a UDP port number and a security association
(Section 4.1).
Sender
The originating endpoint of a message. When the aspect of
identification of the specific sender is in focus, also "source
endpoint".
Recipient
The destination endpoint of a message. When the aspect of
identification of the specific recipient is in focus, also
"destination endpoint".
Client
The originating endpoint of a request; the destination endpoint of
a response.
Server
The destination endpoint of a request; the originating endpoint of
a response.
Shelby, et al. Standards Track [Page 6]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
Origin Server
The server on which a given resource resides or is to be created.
Intermediary
A CoAP endpoint that acts both as a server and as a client towards
an origin server (possibly via further intermediaries). A common
form of an intermediary is a proxy; several classes of such
proxies are discussed in this specification.
Proxy
An intermediary that mainly is concerned with forwarding requests
and relaying back responses, possibly performing caching,
namespace translation, or protocol translation in the process. As
opposed to intermediaries in the general sense, proxies generally
do not implement specific application semantics. Based on the
position in the overall structure of the request forwarding, there
are two common forms of proxy: forward-proxy and reverse-proxy.
In some cases, a single endpoint might act as an origin server,
forward-proxy, or reverse-proxy, switching behavior based on the
nature of each request.
Forward-Proxy
An endpoint selected by a client, usually via local configuration
rules, to perform requests on behalf of the client, doing any
necessary translations. Some translations are minimal, such as
for proxy requests for "coap" URIs, whereas other requests might
require translation to and from entirely different application-
layer protocols.
Reverse-Proxy
An endpoint that stands in for one or more other server(s) and
satisfies requests on behalf of these, doing any necessary
translations. Unlike a forward-proxy, the client may not be aware
that it is communicating with a reverse-proxy; a reverse-proxy
receives requests as if it were the origin server for the target
resource.
CoAP-to-CoAP Proxy
A proxy that maps from a CoAP request to a CoAP request, i.e.,
uses the CoAP protocol both on the server and the client side.
Contrast to cross-proxy.
Cross-Proxy
A cross-protocol proxy, or "cross-proxy" for short, is a proxy
that translates between different protocols, such as a CoAP-to-
HTTP proxy or an HTTP-to-CoAP proxy. While this specification
makes very specific demands of CoAP-to-CoAP proxies, there is more
variation possible in cross-proxies.
Shelby, et al. Standards Track [Page 7]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
Confirmable Message
Some messages require an acknowledgement. These messages are
called "Confirmable". When no packets are lost, each Confirmable
message elicits exactly one return message of type Acknowledgement
or type Reset.
Non-confirmable Message
Some other messages do not require an acknowledgement. This is
particularly true for messages that are repeated regularly for
application requirements, such as repeated readings from a sensor.
Acknowledgement Message
An Acknowledgement message acknowledges that a specific
Confirmable message arrived. By itself, an Acknowledgement
message does not indicate success or failure of any request
encapsulated in the Confirmable message, but the Acknowledgement
message may also carry a Piggybacked Response (see below).
Reset Message
A Reset message indicates that a specific message (Confirmable or
Non-confirmable) was received, but some context is missing to
properly process it. This condition is usually caused when the
receiving node has rebooted and has forgotten some state that
would be required to interpret the message. Provoking a Reset
message (e.g., by sending an Empty Confirmable message) is also
useful as an inexpensive check of the liveness of an endpoint
("CoAP ping").
Piggybacked Response
A piggybacked Response is included right in a CoAP Acknowledgement
(ACK) message that is sent to acknowledge receipt of the Request
for this Response (Section 5.2.1).
Separate Response
When a Confirmable message carrying a request is acknowledged with
an Empty message (e.g., because the server doesn't have the answer
right away), a Separate Response is sent in a separate message
exchange (Section 5.2.2).
Empty Message
A message with a Code of 0.00; neither a request nor a response.
An Empty message only contains the 4-byte header.
Shelby, et al. Standards Track [Page 8]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
Critical Option
An option that would need to be understood by the endpoint
ultimately receiving the message in order to properly process the
message (Section 5.4.1). Note that the implementation of critical
options is, as the name "Option" implies, generally optional:
unsupported critical options lead to an error response or summary
rejection of the message.
Elective Option
An option that is intended to be ignored by an endpoint that does
not understand it. Processing the message even without
understanding the option is acceptable (Section 5.4.1).
Unsafe Option
An option that would need to be understood by a proxy receiving
the message in order to safely forward the message
(Section 5.4.2). Not every critical option is an unsafe option.
Safe-to-Forward Option
An option that is intended to be safe for forwarding by a proxy
that does not understand it. Forwarding the message even without
understanding the option is acceptable (Section 5.4.2).
Resource Discovery
The process where a CoAP client queries a server for its list of
hosted resources (i.e., links as defined in Section 7).
Content-Format
The combination of an Internet media type, potentially with
specific parameters given, and a content-coding (which is often
the identity content-coding), identified by a numeric identifier
defined by the "CoAP Content-Formats" registry. When the focus is
less on the numeric identifier than on the combination of these
characteristics of a resource representation, this is also called
"representation format".
Additional terminology for constrained nodes and constrained-node
networks can be found in [RFC7228].
In this specification, the term "byte" is used in its now customary
sense as a synonym for "octet".
All multi-byte integers in this protocol are interpreted in network
byte order.
Where arithmetic is used, this specification uses the notation
familiar from the programming language C, except that the operator
"**" stands for exponentiation.
Shelby, et al. Standards Track [Page 9]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
2. Constrained Application Protocol
The interaction model of CoAP is similar to the client/server model
of HTTP. However, machine-to-machine interactions typically result
in a CoAP implementation acting in both client and server roles. A
CoAP request is equivalent to that of HTTP and is sent by a client to
request an action (using a Method Code) on a resource (identified by
a URI) on a server. The server then sends a response with a Response
Code; this response may include a resource representation.
Unlike HTTP, CoAP deals with these interchanges asynchronously over a
datagram-oriented transport such as UDP. This is done logically
using a layer of messages that supports optional reliability (with
exponential back-off). CoAP defines four types of messages:
Confirmable, Non-confirmable, Acknowledgement, Reset. Method Codes
and Response Codes included in some of these messages make them carry
requests or responses. The basic exchanges of the four types of
messages are somewhat orthogonal to the request/response
interactions; requests can be carried in Confirmable and Non-
confirmable messages, and responses can be carried in these as well
as piggybacked in Acknowledgement messages.
One could think of CoAP logically as using a two-layer approach, a
CoAP messaging layer used to deal with UDP and the asynchronous
nature of the interactions, and the request/response interactions
using Method and Response Codes (see Figure 1). CoAP is however a
single protocol, with messaging and request/response as just features
of the CoAP header.
+----------------------+
| Application |
+----------------------+
+----------------------+ \
| Requests/Responses | |
|----------------------| | CoAP
| Messages | |
+----------------------+ /
+----------------------+
| UDP |
+----------------------+
Figure 1: Abstract Layering of CoAP
Shelby, et al. Standards Track [Page 10]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
2.1. Messaging Model
The CoAP messaging model is based on the exchange of messages over
UDP between endpoints.
CoAP uses a short fixed-length binary header (4 bytes) that may be
followed by compact binary options and a payload. This message
format is shared by requests and responses. The CoAP message format
is specified in Section 3. Each message contains a Message ID used
to detect duplicates and for optional reliability. (The Message ID
is compact; its 16-bit size enables up to about 250 messages per
second from one endpoint to another with default protocol
parameters.)
Reliability is provided by marking a message as Confirmable (CON). A
Confirmable message is retransmitted using a default timeout and
exponential back-off between retransmissions, until the recipient
sends an Acknowledgement message (ACK) with the same Message ID (in
this example, 0x7d34) from the corresponding endpoint; see Figure 2.
When a recipient is not at all able to process a Confirmable message
(i.e., not even able to provide a suitable error response), it
replies with a Reset message (RST) instead of an Acknowledgement
(ACK).
Client Server
| |
| CON [0x7d34] |
+----------------->|
| |
| ACK [0x7d34] |
|<-----------------+
| |
Figure 2: Reliable Message Transmission
A message that does not require reliable transmission (for example,
each single measurement out of a stream of sensor data) can be sent
as a Non-confirmable message (NON). These are not acknowledged, but
still have a Message ID for duplicate detection (in this example,
0x01a0); see Figure 3. When a recipient is not able to process a
Non-confirmable message, it may reply with a Reset message (RST).
Shelby, et al. Standards Track [Page 11]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
Client Server
| |
| NON [0x01a0] |
+----------------->|
| |
Figure 3: Unreliable Message Transmission
See Section 4 for details of CoAP messages.
As CoAP runs over UDP, it also supports the use of multicast IP
destination addresses, enabling multicast CoAP requests. Section 8
discusses the proper use of CoAP messages with multicast addresses
and precautions for avoiding response congestion.
Several security modes are defined for CoAP in Section 9 ranging from
no security to certificate-based security. This document specifies a
binding to DTLS for securing the protocol; the use of IPsec with CoAP
is discussed in [IPsec-CoAP].
2.2. Request/Response Model
CoAP request and response semantics are carried in CoAP messages,
which include either a Method Code or Response Code, respectively.
Optional (or default) request and response information, such as the
URI and payload media type are carried as CoAP options. A Token is
used to match responses to requests independently from the underlying
messages (Section 5.3). (Note that the Token is a concept separate
from the Message ID.)
A request is carried in a Confirmable (CON) or Non-confirmable (NON)
message, and, if immediately available, the response to a request
carried in a Confirmable message is carried in the resulting
Acknowledgement (ACK) message. This is called a piggybacked
response, detailed in Section 5.2.1. (There is no need for
separately acknowledging a piggybacked response, as the client will
retransmit the request if the Acknowledgement message carrying the
piggybacked response is lost.) Two examples for a basic GET request
with piggybacked response are shown in Figure 4, one successful, one
resulting in a 4.04 (Not Found) response.
Shelby, et al. Standards Track [Page 12]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
Client Server Client Server
| | | |
| CON [0xbc90] | | CON [0xbc91] |
| GET /temperature | | GET /temperature |
| (Token 0x71) | | (Token 0x72) |
+----------------->| +----------------->|
| | | |
| ACK [0xbc90] | | ACK [0xbc91] |
| 2.05 Content | | 4.04 Not Found |
| (Token 0x71) | | (Token 0x72) |
| "22.5 C" | | "Not found" |
|<-----------------+ |<-----------------+
| | | |
Figure 4: Two GET Requests with Piggybacked Responses
If the server is not able to respond immediately to a request carried
in a Confirmable message, it simply responds with an Empty
Acknowledgement message so that the client can stop retransmitting
the request. When the response is ready, the server sends it in a
new Confirmable message (which then in turn needs to be acknowledged
by the client). This is called a "separate response", as illustrated
in Figure 5 and described in more detail in Section 5.2.2.
Client Server
| |
| CON [0x7a10] |
| GET /temperature |
| (Token 0x73) |
+----------------->|
| |
| ACK [0x7a10] |
|<-----------------+
| |
... Time Passes ...
| |
| CON [0x23bb] |
| 2.05 Content |
| (Token 0x73) |
| "22.5 C" |
|<-----------------+
| |
| ACK [0x23bb] |
+----------------->|
| |
Figure 5: A GET Request with a Separate Response
Shelby, et al. Standards Track [Page 13]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
If a request is sent in a Non-confirmable message, then the response
is sent using a new Non-confirmable message, although the server may
instead send a Confirmable message. This type of exchange is
illustrated in Figure 6.
Client Server
| |
| NON [0x7a11] |
| GET /temperature |
| (Token 0x74) |
+----------------->|
| |
| NON [0x23bc] |
| 2.05 Content |
| (Token 0x74) |
| "22.5 C" |
|<-----------------+
| |
Figure 6: A Request and a Response Carried in Non-confirmable
Messages
CoAP makes use of GET, PUT, POST, and DELETE methods in a similar
manner to HTTP, with the semantics specified in Section 5.8. (Note
that the detailed semantics of CoAP methods are "almost, but not
entirely unlike" [HHGTTG] those of HTTP methods: intuition taken from
HTTP experience generally does apply well, but there are enough
differences that make it worthwhile to actually read the present
specification.)
Methods beyond the basic four can be added to CoAP in separate
specifications. New methods do not necessarily have to use requests
and responses in pairs. Even for existing methods, a single request
may yield multiple responses, e.g., for a multicast request
(Section 8) or with the Observe option [OBSERVE].
URI support in a server is simplified as the client already parses
the URI and splits it into host, port, path, and query components,
making use of default values for efficiency. Response Codes relate
to a small subset of HTTP status codes with a few CoAP-specific codes
added, as defined in Section 5.9.
Shelby, et al. Standards Track [Page 14]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
2.3. Intermediaries and Caching
The protocol supports the caching of responses in order to
efficiently fulfill requests. Simple caching is enabled using
freshness and validity information carried with CoAP responses. A
cache could be located in an endpoint or an intermediary. Caching
functionality is specified in Section 5.6.
Proxying is useful in constrained networks for several reasons,
including to limit network traffic, to improve performance, to access
resources of sleeping devices, and for security reasons. The
proxying of requests on behalf of another CoAP endpoint is supported
in the protocol. When using a proxy, the URI of the resource to
request is included in the request, while the destination IP address
is set to the address of the proxy. See Section 5.7 for more
information on proxy functionality.
As CoAP was designed according to the REST architecture [REST], and
thus exhibits functionality similar to that of the HTTP protocol, it
is quite straightforward to map from CoAP to HTTP and from HTTP to
CoAP. Such a mapping may be used to realize an HTTP REST interface
using CoAP or to convert between HTTP and CoAP. This conversion can
be carried out by a cross-protocol proxy ("cross-proxy"), which
converts the Method or Response Code, media type, and options to the
corresponding HTTP feature. Section 10 provides more detail about
HTTP mapping.
2.4. Resource Discovery
Resource discovery is important for machine-to-machine interactions
and is supported using the CoRE Link Format [RFC6690] as discussed in
Section 7.
3. Message Format
CoAP is based on the exchange of compact messages that, by default,
are transported over UDP (i.e., each CoAP message occupies the data
section of one UDP datagram). CoAP may also be used over Datagram
Transport Layer Security (DTLS) (see Section 9.1). It could also be
used over other transports such as SMS, TCP, or SCTP, the
specification of which is out of this document's scope. (UDP-lite
[RFC3828] and UDP zero checksum [RFC6936] are not supported by CoAP.)
CoAP messages are encoded in a simple binary format. The message
format starts with a fixed-size 4-byte header. This is followed by a
variable-length Token value, which can be between 0 and 8 bytes long.
Shelby, et al. Standards Track [Page 15]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
Following the Token value comes a sequence of zero or more CoAP
Options in Type-Length-Value (TLV) format, optionally followed by a
payload that takes up the rest of the datagram.
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 7: Message Format
The fields in the header are defined as follows:
Version (Ver): 2-bit unsigned integer. Indicates the CoAP version
number. Implementations of this specification MUST set this field
to 1 (01 binary). Other values are reserved for future versions.
Messages with unknown version numbers MUST be silently ignored.
Type (T): 2-bit unsigned integer. Indicates if this message is of
type Confirmable (0), Non-confirmable (1), Acknowledgement (2), or
Reset (3). The semantics of these message types are defined in
Section 4.
Token Length (TKL): 4-bit unsigned integer. Indicates the length of
the variable-length Token field (0-8 bytes). Lengths 9-15 are
reserved, MUST NOT be sent, and MUST be processed as a message
format error.
Code: 8-bit unsigned integer, split into a 3-bit class (most
significant bits) and a 5-bit detail (least significant bits),
documented as "c.dd" where "c" is a digit from 0 to 7 for the
3-bit subfield and "dd" are two digits from 00 to 31 for the 5-bit
subfield. The class can indicate a request (0), a success
response (2), a client error response (4), or a server error
response (5). (All other class values are reserved.) As a
special case, Code 0.00 indicates an Empty message. In case of a
request, the Code field indicates the Request Method; in case of a
response, a Response Code. Possible values are maintained in the
CoAP Code Registries (Section 12.1). The semantics of requests
and responses are defined in Section 5.
Shelby, et al. Standards Track [Page 16]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
Message ID: 16-bit unsigned integer in network byte order. Used to
detect message duplication and to match messages of type
Acknowledgement/Reset to messages of type Confirmable/Non-
confirmable. The rules for generating a Message ID and matching
messages are defined in Section 4.
The header is followed by the Token value, which may be 0 to 8 bytes,
as given by the Token Length field. The Token value is used to
correlate requests and responses. The rules for generating a Token
and correlating requests and responses are defined in Section 5.3.1.
Header and Token are followed by zero or more Options (Section 3.1).
An Option can be followed by the end of the message, by another
Option, or by the Payload Marker and the payload.
Following the header, token, and options, if any, comes the optional
payload. If present and of non-zero length, it is prefixed by a
fixed, one-byte Payload Marker (0xFF), which indicates the end of
options and the start of the payload. The payload data extends from
after the marker to the end of the UDP datagram, i.e., the Payload
Length is calculated from the datagram size. The absence of the
Payload Marker denotes a zero-length payload. The presence of a
marker followed by a zero-length payload MUST be processed as a
message format error.
Implementation Note: The byte value 0xFF may also occur within an
option length or value, so simple byte-wise scanning for 0xFF is
not a viable technique for finding the payload marker. The byte
0xFF has the meaning of a payload marker only where the beginning
of another option could occur.
3.1. Option Format
CoAP defines a number of options that can be included in a message.
Each option instance in a message specifies the Option Number of the
defined CoAP option, the length of the Option Value, and the Option
Value itself.
Instead of specifying the Option Number directly, the instances MUST
appear in order of their Option Numbers and a delta encoding is used
between them: the Option Number for each instance is calculated as
the sum of its delta and the Option Number of the preceding instance
in the message. For the first instance in a message, a preceding
option instance with Option Number zero is assumed. Multiple
instances of the same option can be included by using a delta of
zero.
Shelby, et al. Standards Track [Page 17]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
Option Numbers are maintained in the "CoAP Option Numbers" registry
(Section 12.2). See Section 5.4 for the semantics of the options
defined in this document.
0 1 2 3 4 5 6 7
+---------------+---------------+
| | |
| Option Delta | Option Length | 1 byte
| | |
+---------------+---------------+
\ \
/ Option Delta / 0-2 bytes
\ (extended) \
+-------------------------------+
\ \
/ Option Length / 0-2 bytes
\ (extended) \
+-------------------------------+
\ \
/ /
\ \
/ Option Value / 0 or more bytes
\ \
/ /
\ \
+-------------------------------+
Figure 8: Option Format
The fields in an option are defined as follows:
Option Delta: 4-bit unsigned integer. A value between 0 and 12
indicates the Option Delta. Three values are reserved for special
constructs:
13: An 8-bit unsigned integer follows the initial byte and
indicates the Option Delta minus 13.
14: A 16-bit unsigned integer in network byte order follows the
initial byte and indicates the Option Delta minus 269.
15: Reserved for the Payload Marker. If the field is set to this
value but the entire byte is not the payload marker, this MUST
be processed as a message format error.
Shelby, et al. Standards Track [Page 18]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
The resulting Option Delta is used as the difference between the
Option Number of this option and that of the previous option (or
zero for the first option). In other words, the Option Number is
calculated by simply summing the Option Delta values of this and
all previous options before it.
Option Length: 4-bit unsigned integer. A value between 0 and 12
indicates the length of the Option Value, in bytes. Three values
are reserved for special constructs:
13: An 8-bit unsigned integer precedes the Option Value and
indicates the Option Length minus 13.
14: A 16-bit unsigned integer in network byte order precedes the
Option Value and indicates the Option Length minus 269.
15: Reserved for future use. If the field is set to this value,
it MUST be processed as a message format error.
Value: A sequence of exactly Option Length bytes. The length and
format of the Option Value depend on the respective option, which
MAY define variable-length values. See Section 3.2 for the
formats used in this document; options defined in other documents
MAY make use of other option value formats.
3.2. Option Value Formats
The options defined in this document make use of the following option
value formats.
empty: A zero-length sequence of bytes.
opaque: An opaque sequence of bytes.
uint: A non-negative integer that is represented in network byte
order using the number of bytes given by the Option Length
field.
An option definition may specify a range of permissible
numbers of bytes; if it has a choice, a sender SHOULD
represent the integer with as few bytes as possible, i.e.,
without leading zero bytes. For example, the number 0 is
represented with an empty option value (a zero-length
sequence of bytes) and the number 1 by a single byte with
the numerical value of 1 (bit combination 00000001 in most
significant bit first notation). A recipient MUST be
prepared to process values with leading zero bytes.
Shelby, et al. Standards Track [Page 19]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
Implementation Note: The exceptional behavior permitted
for the sender is intended for highly constrained,
templated implementations (e.g., hardware
implementations) that use fixed-size options in the
templates.
string: A Unicode string that is encoded using UTF-8 [RFC3629] in
Net-Unicode form [RFC5198].
Note that here, and in all other places where UTF-8
encoding is used in the CoAP protocol, the intention is
that the encoded strings can be directly used and compared
as opaque byte strings by CoAP protocol implementations.
There is no expectation and no need to perform
normalization within a CoAP implementation (except where
Unicode strings that are not known to be normalized are
imported from sources outside the CoAP protocol). Note
also that ASCII strings (that do not make use of special
control characters) are always valid UTF-8 Net-Unicode
strings.
4. Message Transmission
CoAP messages are exchanged asynchronously between CoAP endpoints.
They are used to transport CoAP requests and responses, the semantics
of which are defined in Section 5.
As CoAP is bound to unreliable transports such as UDP, CoAP messages
may arrive out of order, appear duplicated, or go missing without
notice. For this reason, CoAP implements a lightweight reliability
mechanism, without trying to re-create the full feature set of a
transport like TCP. It has the following features:
o Simple stop-and-wait retransmission reliability with exponential
back-off for Confirmable messages.
o Duplicate detection for both Confirmable and Non-confirmable
messages.
4.1. Messages and Endpoints
A CoAP endpoint is the source or destination of a CoAP message. The
specific definition of an endpoint depends on the transport being
used for CoAP. For the transports defined in this specification, the
endpoint is identified depending on the security mode used (see
Section 9): With no security, the endpoint is solely identified by an
IP address and a UDP port number. With other security modes, the
endpoint is identified as defined by the security mode.
Shelby, et al. Standards Track [Page 20]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
There are different types of messages. The type of a message is
specified by the Type field of the CoAP Header.
Separate from the message type, a message may carry a request, a
response, or be Empty. This is signaled by the Request/Response Code
field in the CoAP Header and is relevant to the request/response
model. Possible values for the field are maintained in the CoAP Code
Registries (Section 12.1).
An Empty message has the Code field set to 0.00. The Token Length
field MUST be set to 0 and bytes of data MUST NOT be present after
the Message ID field. If there are any bytes, they MUST be processed
as a message format error.
4.2. Messages Transmitted Reliably
The reliable transmission of a message is initiated by marking the
message as Confirmable in the CoAP header. A Confirmable message
always carries either a request or response, unless it is used only
to elicit a Reset message, in which case it is Empty. A recipient
MUST either (a) acknowledge a Confirmable message with an
Acknowledgement message or (b) reject the message if the recipient
lacks context to process the message properly, including situations
where the message is Empty, uses a code with a reserved class (1, 6,
or 7), or has a message format error. Rejecting a Confirmable
message is effected by sending a matching Reset message and otherwise
ignoring it. The Acknowledgement message MUST echo the Message ID of
the Confirmable message and MUST carry a response or be Empty (see
Sections 5.2.1 and 5.2.2). The Reset message MUST echo the Message
ID of the Confirmable message and MUST be Empty. Rejecting an
Acknowledgement or Reset message (including the case where the
Acknowledgement carries a request or a code with a reserved class, or
the Reset message is not Empty) is effected by silently ignoring it.
More generally, recipients of Acknowledgement and Reset messages MUST
NOT respond with either Acknowledgement or Reset messages.
The sender retransmits the Confirmable message at exponentially
increasing intervals, until it receives an acknowledgement (or Reset
message) or runs out of attempts.
Retransmission is controlled by two things that a CoAP endpoint MUST
keep track of for each Confirmable message it sends while waiting for
an acknowledgement (or reset): a timeout and a retransmission
counter. For a new Confirmable message, the initial timeout is set
to a random duration (often not an integral number of seconds)
between ACK_TIMEOUT and (ACK_TIMEOUT * ACK_RANDOM_FACTOR) (see
Section 4.8), and the retransmission counter is set to 0. When the
timeout is triggered and the retransmission counter is less than
Shelby, et al. Standards Track [Page 21]
RFC 7252 The Constrained Application Protocol (CoAP) June 2014
MAX_RETRANSMIT, the message is retransmitted, the retransmission
counter is incremented, and the timeout is doubled. If the
retransmission counter reaches MAX_RETRANSMIT on a timeout, or if the
endpoint receives a Reset message, then the attempt to transmit the
message is canceled and the application process informed of failure.
On the other hand, if the endpoint receives an acknowledgement in
time, transmission is considered successful.
This specification makes no strong requirements on the accuracy of
the clocks used to implement the above binary exponential back-off
algorithm. In particular, an endpoint may be late for a specific
retransmission due to its sleep schedule and may catch up on the next
one. However, the minimum spacing before another retransmission is
ACK_TIMEOUT, and the entire sequence of (re-)transmissions MUST stay
in the envelope of MAX_TRANSMIT_SPAN (see Section 4.8.2), even if
that means a sender may miss an opportunity to transmit.
A CoAP endpoint that sent a Confirmable message MAY give up in
attempting to obtain an ACK even before the MAX_RETRANSMIT counter
value is reached. For example, the application has canceled the
request as it no longer needs a response, or there is some other
indication that the CON message did arrive. In particular, a CoAP
request message may have elicited a separate response, in which case
it is clear to the requester that only the ACK was lost and a
retransmission of the request would serve no purpose. However, a
responder MUST NOT in turn rely on this cross-layer behavior from a
requester, i.e., it MUST retain the state to create the ACK for the
request, if needed, even if a Confirmable response was alr