*The language in these things is paralytic. Oh well, that’s why engineers get paid.
*They don’t get paid anywhere near like financiers, mind you, but they get paid something.
http://tools.ietf.org/html/rfc7252
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 © 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….
