7.1. Service Discovery
As a part of discovering the services offered by a CoAP server, a
client has to learn about the endpoint used by a server.
A server is discovered by a client (knowing or) learning a URI that
references a resource in the namespace of the server. Alternatively,
clients can use multicast CoAP (see Section 8) and the "All CoAP
Nodes" multicast address to find CoAP servers.
Unless the port subcomponent in a "coap" or "coaps" URI indicates the
UDP port at which the CoAP server is located, the server is assumed
to be reachable at the default port.
The CoAP default port number 5683 MUST be supported by a server that
offers resources for resource discovery (see Section 7.2 below) and
SHOULD be supported for providing access to other resources. The
default port number 5684 for DTLS-secured CoAP MAY be supported by a
server for resource discovery and for providing access to other
resources. In addition, other endpoints may be hosted at other
ports, e.g., in the dynamic port space.
Implementation Note: When a CoAP server is hosted by a 6LoWPAN node,
header compression efficiency is improved when it also supports a
port number in the 61616-61631 compressed UDP port space defined
in [RFC4944] and [RFC6282]. (Note that, as its UDP port differs
from the default port, it is a different endpoint from the server
at the default port.)
7.2. Resource Discovery
The discovery of resources offered by a CoAP endpoint is extremely
important in machine-to-machine applications where there are no
humans in the loop and static interfaces result in fragility. To
maximize interoperability in a CoRE environment, a CoAP endpoint
SHOULD support the CoRE Link Format of discoverable resources as
described in [RFC6690], except where fully manual configuration is
desired. It is up to the server which resources are made
discoverable (if any).
7.2.1. 'ct' Attribute
This section defines a new Web Linking [RFC5988] attribute for use
with [RFC6690]. The Content-Format code "ct" attribute provides a
hint about the Content-Formats this resource returns. Note that this
is only a hint, and it does not override the Content-Format Option of
a CoAP response obtained by actually requesting the representation of
the resource. The value is in the CoAP identifier code format as a
decimal ASCII integer and MUST be in the range of 0-65535 (16-bit
unsigned integer). For example, "application/xml" would be indicated
as "ct=41". If no Content-Format code attribute is present, then
nothing about the type can be assumed. The Content-Format code
attribute MAY include a space-separated sequence of Content-Format
codes, indicating that multiple content-formats are available. The
syntax of the attribute value is summarized in the production "ct-
value" in Figure 12, where "cardinal", "SP", and "DQUOTE" are defined
as in [RFC6690].
ct-value = cardinal
/ DQUOTE cardinal *( 1*SP cardinal ) DQUOTE
Figure 128. Multicast CoAP
CoAP supports making requests to an IP multicast group. This is
defined by a series of deltas to unicast CoAP. A more general
discussion of group communication with CoAP is in [GROUPCOMM].
CoAP endpoints that offer services that they want other endpoints to
be able to find using multicast service discovery join one or more of
the appropriate all-CoAP-node multicast addresses (Section 12.8) and
listen on the default CoAP port. Note that an endpoint might receive
multicast requests on other multicast addresses, including the all-
nodes IPv6 address (or via broadcast on IPv4); an endpoint MUST
therefore be prepared to receive such messages but MAY ignore them if
multicast service discovery is not desired.
8.1. Messaging Layer
A multicast request is characterized by being transported in a CoAP
message that is addressed to an IP multicast address instead of a
CoAP endpoint. Such multicast requests MUST be Non-confirmable.
A server SHOULD be aware that a request arrived via multicast, e.g.,
by making use of modern APIs such as IPV6_RECVPKTINFO [RFC3542], if
To avoid an implosion of error responses, when a server is aware that
a request arrived via multicast, it MUST NOT return a Reset message
in reply to a Non-confirmable message. If it is not aware, it MAY
return a Reset message in reply to a Non-confirmable message as
usual. Because such a Reset message will look identical to one for a
unicast message from the sender, the sender MUST avoid using a
Message ID that is also still active from this endpoint with any
unicast endpoint that might receive the multicast message.
At the time of writing, multicast messages can only be carried in UDP
not in DTLS. This means that the security modes defined for CoAP in
this document are not applicable to multicast.
8.2. Request/Response Layer
When a server is aware that a request arrived via multicast, the
server MAY always ignore the request, in particular if it doesn't
have anything useful to respond (e.g., if it only has an empty
payload or an error response). The decision for this may depend on
the application. (For example, in query filtering as described in
[RFC6690], a server should not respond to a multicast request if the
filter does not match. More examples are in [GROUPCOMM].)
If a server does decide to respond to a multicast request, it should
not respond immediately. Instead, it should pick a duration for the
period of time during which it intends to respond. For the purposes
of this exposition, we call the length of this period the Leisure.
The specific value of this Leisure may depend on the application or
MAY be derived as described below. The server SHOULD then pick a
random point of time within the chosen leisure period to send back
the unicast response to the multicast request. If further responses
need to be sent based on the same multicast address membership, a new
leisure period starts at the earliest after the previous one
To compute a value for Leisure, the server should have a group size
estimate G, a target data transfer rate R (which both should be
chosen conservatively), and an estimated response size S; a rough
lower bound for Leisure can then be computed as
lb_Leisure = S * G / R
For example, for a multicast request with link-local scope on a 2.4
GHz IEEE 802.15.4 (6LoWPAN) network, G could be (relatively
conservatively) set to 100, S to 100 bytes, and the target rate to 8
kbit/s = 1 kB/s. The resulting lower bound for the Leisure is 10
If a CoAP endpoint does not have suitable data to compute a value for
Leisure, it MAY resort to DEFAULT_LEISURE.
When matching a response to a multicast request, only the token MUST
match; the source endpoint of the response does not need to (and will
not) be the same as the destination endpoint of the original request.
For the purposes of interpreting the Location-* options and any links
embedded in the representation, the request URI (i.e., the base URI
relative to which the response is interpreted) is formed by replacing
the multicast address in the Host component of the original request
URI by the literal IP address of the endpoint actually responding.
When a client makes a multicast request, it always makes a new
request to the multicast group (since there may be new group members
that joined meanwhile or ones that did not get the previous request).
It MAY update a cache with the received responses. Then, it uses
both cached-still-fresh and new responses as the result of the
A response received in reply to a GET request to a multicast group
MAY be used to satisfy a subsequent request on the related unicast
request URI. The unicast request URI is obtained by replacing the
authority part of the request URI with the transport-layer source
address of the response message.
A cache MAY revalidate a response by making a GET request on the
related unicast request URI.
A GET request to a multicast group MUST NOT contain an ETag option.
A mechanism to suppress responses the client already has is left for
When a forward-proxy receives a request with a Proxy-Uri or URI
constructed from Proxy-Scheme that indicates a multicast address, the
proxy obtains a set of responses as described above and sends all
responses (both cached-still-fresh and new) back to the original
This specification does not provide a way to indicate the unicast-
modified request URI (base URI) in responses thus forwarded.
Proxying multicast requests is discussed in more detail in
[GROUPCOMM]; one proposal to address the base URI issue can be found
in Section 3 of [CoAP-MISC].
9. Securing CoAP
This section defines the DTLS binding for CoAP.
During the provisioning phase, a CoAP device is provided with the
security information that it needs, including keying materials and
access control lists. This specification defines provisioning for
the RawPublicKey mode in Section 22.214.171.124.1. At the end of the
provisioning phase, the device will be in one of four security modes
with the following information for the given mode. The NoSec and
RawPublicKey modes are mandatory to implement for this specification.
NoSec: There is no protocol-level security (DTLS is disabled).
Alternative techniques to provide lower-layer security SHOULD be
used when appropriate. The use of IPsec is discussed in
[IPsec-CoAP]. Certain link layers in use with constrained nodes
also provide link-layer security, which may be appropriate with
proper key management.
PreSharedKey: DTLS is enabled, there is a list of pre-shared keys
[RFC4279], and each key includes a list of which nodes it can be
used to communicate with as described in Section 126.96.36.199. At the
extreme, there may be one key for each node this CoAP node needs
to communicate with (1:1 node/key ratio). Conversely, if more
than two entities share a specific pre-shared key, this key only
enables the entities to authenticate as a member of that group and
not as a specific peer.
RawPublicKey: DTLS is enabled and the device has an asymmetric key
pair without a certificate (a raw public key) that is validated
using an out-of-band mechanism [RFC7250] as described in
Section 188.8.131.52. The device also has an identity calculated from
the public key and a list of identities of the nodes it can
Certificate: DTLS is enabled and the device has an asymmetric key
pair with an X.509 certificate [RFC5280] that binds it to its
subject and is signed by some common trust root as described in
Section 184.108.40.206. The device also has a list of root trust anchors
that can be used for validating a certificate.
In the "NoSec" mode, the system simply sends the packets over normal
UDP over IP and is indicated by the "coap" scheme and the CoAP
default port. The system is secured only by keeping attackers from
being able to send or receive packets from the network with the CoAP
nodes; see Section 11.5 for an additional complication with this
The other three security modes are achieved using DTLS and are
indicated by the "coaps" scheme and DTLS-secured CoAP default port.
The result is a security association that can be used to authenticate
(within the limits of the security model) and, based on this
authentication, authorize the communication partner. CoAP itself
does not provide protocol primitives for authentication or
authorization; where this is required, it can either be provided by
communication security (i.e., IPsec or DTLS) or by object security
(within the payload). Devices that require authorization for certain
operations are expected to require one of these two forms of
security. Necessarily, where an intermediary is involved,
communication security only works when that intermediary is part of
the trust relationships. CoAP does not provide a way to forward
different levels of authorization that clients may have with an
intermediary to further intermediaries or origin servers -- it
therefore may be required to perform all authorization at the first
9.1. DTLS-Secured CoAP
Just as HTTP is secured using Transport Layer Security (TLS) over
TCP, CoAP is secured using Datagram TLS (DTLS) [RFC6347] over UDP
(see Figure 13). This section defines the CoAP binding to DTLS,
along with the minimal mandatory-to-implement configurations
appropriate for constrained environments. The binding is defined by
a series of deltas to unicast CoAP. In practice, DTLS is TLS with
added features to deal with the unreliable nature of the UDP
| Application |
| Requests/Responses |
| Messages |
| DTLS |
| UDP |
Figure 13: Abstract Layering of DTLS-Secured CoAP
In some constrained nodes (limited flash and/or RAM) and networks
(limited bandwidth or high scalability requirements), and depending
on the specific cipher suites in use, all modes of DTLS may not be
applicable. Some DTLS cipher suites can add significant
implementation complexity as well as some initial handshake overhead
needed when setting up the security association. Once the initial
handshake is completed, DTLS adds a limited per-datagram overhead of
approximately 13 bytes, not including any initialization vectors/
nonces (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8 [RFC6655]),
integrity check values (e.g., 8 bytes with TLS_PSK_WITH_AES_128_CCM_8
[RFC6655]), and padding required by the cipher suite. Whether the
use of a given mode of DTLS is applicable for a CoAP-based
application should be carefully weighed considering the specific
cipher suites that may be applicable, whether the session maintenance
makes it compatible with application flows, and whether sufficient
resources are available on the constrained nodes and for the added
network overhead. (For some modes of using DTLS, this specification
identifies a mandatory-to-implement cipher suite. This is an
implementation requirement to maximize interoperability in those
cases where these cipher suites are indeed appropriate. The specific
security policies of an application may determine the actual set of
cipher suites that can be used.) DTLS is not applicable to group
keying (multicast communication); however, it may be a component in a
future group key management protocol.
9.1.1. Messaging Layer
The endpoint acting as the CoAP client should also act as the DTLS
client. It should initiate a session to the server on the
appropriate port. When the DTLS handshake has finished, the client
may initiate the first CoAP request. All CoAP messages MUST be sent
as DTLS "application data".
The following rules are added for matching an Acknowledgement message
or Reset message to a Confirmable message, or a Reset message to a
Non-confirmable message: The DTLS session MUST be the same, and the
epoch MUST be the same.
A message is the same when it is sent within the same DTLS session
and same epoch and has the same Message ID.
Note: When a Confirmable message is retransmitted, a new DTLS
sequence_number is used for each attempt, even though the CoAP
Message ID stays the same. So a recipient still has to perform
deduplication as described in Section 4.5. Retransmissions MUST NOT
be performed across epochs.
DTLS connections in RawPublicKey and Certificate mode are set up
using mutual authentication so they can remain up and be reused for
future message exchanges in either direction. Devices can close a
DTLS connection when they need to recover resources, but in general
they should keep the connection up for as long as possible. Closing
the DTLS connection after every CoAP message exchange is very
9.1.2. Request/Response Layer
The following rules are added for matching a response to a request:
The DTLS session MUST be the same, and the epoch MUST be the same.
This means the response to a DTLS secured request MUST always be DTLS
secured using the same security session and epoch. Any attempt to
supply a NoSec response to a DTLS request simply does not match the
request and therefore MUST be rejected (unless it does match an
unrelated NoSec request).
9.1.3. Endpoint Identity
Devices SHOULD support the Server Name Indication (SNI) to indicate
their authority in the SNI HostName field as defined in Section 3 of
[RFC6066]. This is needed so that when a host that acts as a virtual
server for multiple Authorities receives a new DTLS connection, it
knows which keys to use for the DTLS session.
220.127.116.11. Pre-Shared Keys
When forming a connection to a new node, the system selects an
appropriate key based on which nodes it is trying to reach and then
forms a DTLS session using a PSK (Pre-Shared Key) mode of DTLS.
Implementations in these modes MUST support the mandatory-to-
implement cipher suite TLS_PSK_WITH_AES_128_CCM_8 as specified in
Depending on the commissioning model, applications may need to define
an application profile for identity hints (as required and detailed
in Section 5.2 of [RFC4279]) to enable the use of PSK identity hints.
The security considerations of Section 7 of [RFC4279] apply. In
particular, applications should carefully weigh whether or not they
need Perfect Forward Secrecy (PFS) and select an appropriate cipher
suite (Section 7.1 of [RFC4279]). The entropy of the PSK must be
sufficient to mitigate against brute-force and (where the PSK is not
chosen randomly but by a human) dictionary attacks (Section 7.2 of
[RFC4279]). The cleartext communication of client identities may
leak data or compromise privacy (Section 7.3 of [RFC4279]).
18.104.22.168. Raw Public Key Certificates
In this mode, the device has an asymmetric key pair but without an
X.509 certificate (called a raw public key); for example, the
asymmetric key pair is generated by the manufacturer and installed on
the device (see also Section 11.6). A device MAY be configured with
multiple raw public keys. The type and length of the raw public key
depends on the cipher suite used. Implementations in RawPublicKey
mode MUST support the mandatory-to-implement cipher suite
TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as specified in [RFC7251],
[RFC5246], and [RFC4492]. The key used MUST be ECDSA capable. The
curve secp256r1 MUST be supported [RFC4492]; this curve is equivalent
to the NIST P-256 curve. The hash algorithm is SHA-256.
Implementations MUST use the Supported Elliptic Curves and Supported
Point Formats Extensions [RFC4492]; the uncompressed point format
MUST be supported; [RFC6090] can be used as an implementation method.
Some guidance relevant to the implementation of this cipher suite can
be found in [W3CXMLSEC]. The mechanism for using raw public keys
with TLS is specified in [RFC7250].
Implementation Note: Specifically, this means the extensions listed
in Figure 14 with at least the values listed will be present in
the DTLS handshake.
Type: elliptic_curves (0x000a)
Elliptic Curves Length: 2
Elliptic curves (1 curve)
Elliptic curve: secp256r1 (0x0017)
Type: ec_point_formats (0x000b)
EC point formats Length: 1
Elliptic curves point formats (1)
EC point format: uncompressed (0)
Type: signature_algorithms (0x000d)
Data (4 bytes): 00 02 04 03
HashAlgorithm: sha256 (4)
SignatureAlgorithm: ecdsa (3)
Figure 14: DTLS Extensions Present for
The RawPublicKey mode was designed to be easily provisioned in M2M
deployments. It is assumed that each device has an appropriate
asymmetric public key pair installed. An identifier is calculated by
the endpoint from the public key as described in Section 2 of
[RFC6920]. All implementations that support checking RawPublicKey
identities MUST support at least the sha-256-120 mode (SHA-256
truncated to 120 bits). Implementations SHOULD also support longer
length identifiers and MAY support shorter lengths. Note that the
shorter lengths provide less security against attacks, and their use
is NOT RECOMMENDED.
Depending on how identifiers are given to the system that verifies
them, support for URI, binary, and/or human-speakable format
[RFC6920] needs to be implemented. All implementations SHOULD
support the binary mode, and implementations that have a user
interface SHOULD also support the human-speakable format.
During provisioning, the identifier of each node is collected, for
example, by reading a barcode on the outside of the device or by
obtaining a pre-compiled list of the identifiers. These identifiers
are then installed in the corresponding endpoint, for example, an M2M
data collection server. The identifier is used for two purposes, to
associate the endpoint with further device information and to perform
access control. During (initial and ongoing) provisioning, an access
control list of identifiers with which the device may start DTLS
sessions SHOULD also be installed and maintained.
22.214.171.124. X.509 Certificates
Implementations in Certificate Mode MUST support the mandatory-to-
implement cipher suite TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 as
specified in [RFC7251], [RFC5246], and [RFC4492]. Namely, the
certificate includes a SubjectPublicKeyInfo that indicates an
algorithm of id-ecPublicKey with namedCurves secp256r1 [RFC5480]; the
public key format is uncompressed [RFC5480]; the hash algorithm is
SHA-256; if included, the key usage extension indicates
digitalSignature. Certificates MUST be signed with ECDSA using
secp256r1, and the signature MUST use SHA-256. The key used MUST be
ECDSA capable. The curve secp256r1 MUST be supported [RFC4492]; this
curve is equivalent to the NIST P-256 curve. The hash algorithm is
SHA-256. Implementations MUST use the Supported Elliptic Curves and
Supported Point Formats Extensions [RFC4492]; the uncompressed point
format MUST be supported; [RFC6090] can be used as an implementation
The subject in the certificate would be built out of a long-term
unique identifier for the device such as the EUI-64 [EUI64]. The
subject could also be based on the Fully Qualified Domain Name (FQDN)
that was used as the Host part of the CoAP URI. However, the
device's IP address should not typically be used as the subject, as
it would change over time. The discovery process used in the system
would build up the mapping between IP addresses of the given devices
and the subject for each device. Some devices could have more than
one subject and would need more than a single certificate.
When a new connection is formed, the certificate from the remote
device needs to be verified. If the CoAP node has a source of
absolute time, then the node SHOULD check that the validity dates of
the certificate are within range. The certificate MUST be validated
as appropriate for the security requirements, using functionality
equivalent to the algorithm specified in Section 6 of [RFC5280]. If
the certificate contains a SubjectAltName, then the authority of the
request URI MUST match at least one of the authorities of any CoAP
URI found in a field of URI type in the SubjectAltName set. If there
is no SubjectAltName in the certificate, then the authority of the
request URI MUST match the Common Name (CN) found in the certificate
using the matching rules defined in [RFC3280] with the exception that
certificates with wildcards are not allowed.
CoRE support for certificate status checking requires further study.
As a mapping of the Online Certificate Status Protocol (OCSP)
[RFC6960] onto CoAP is not currently defined and OCSP may also not be
easily applicable in all environments, an alternative approach may be
using the TLS Certificate Status Request extension (Section 8 of
[RFC6066]; also known as "OCSP stapling") or preferably the Multiple
Certificate Status Extension ([RFC6961]), if available.
If the system has a shared key in addition to the certificate, then a
cipher suite that includes the shared key such as
TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA [RFC5489] SHOULD be used.
10. Cross-Protocol Proxying between CoAP and HTTP
CoAP supports a limited subset of HTTP functionality, and thus cross-
protocol proxying to HTTP is straightforward. There might be several
reasons for proxying between CoAP and HTTP, for example, when
designing a web interface for use over either protocol or when
realizing a CoAP-HTTP proxy. Likewise, CoAP could equally be proxied
to other protocols such as XMPP [RFC6120] or SIP [RFC3264]; the
definition of these mechanisms is out of scope for this
There are two possible directions to access a resource via a forward-
CoAP-HTTP Proxying: Enables CoAP clients to access resources on HTTP
servers through an intermediary. This is initiated by including
the Proxy-Uri or Proxy-Scheme Option with an "http" or "https" URI
in a CoAP request to a CoAP-HTTP proxy.
HTTP-CoAP Proxying: Enables HTTP clients to access resources on CoAP
servers through an intermediary. This is initiated by specifying
a "coap" or "coaps" URI in the Request-Line of an HTTP request to
an HTTP-CoAP proxy.
Either way, only the request/response model of CoAP is mapped to
HTTP. The underlying model of Confirmable or Non-confirmable
messages, etc., is invisible and MUST have no effect on a proxy
function. The following sections describe the handling of requests
to a forward-proxy. Reverse-proxies are not specified, as the proxy
function is transparent to the client with the proxy acting as if it
were the origin server. However, similar considerations apply to
reverse-proxies as to forward-proxies, and there generally will be an
expectation that reverse-proxies operate in a similar way forward-
proxies would. As an implementation note, HTTP client libraries may
make it hard to operate an HTTP-CoAP forward-proxy by not providing a
way to put a CoAP URI on the HTTP Request-Line; reverse-proxying may
therefore lead to wider applicability of a proxy. A separate
specification may define a convention for URIs operating such an
HTTP-CoAP reverse-proxy [MAPPING].
10.1. CoAP-HTTP Proxying
If a request contains a Proxy-Uri or Proxy-Scheme Option with an
'http' or 'https' URI [RFC2616], then the receiving CoAP endpoint
(called "the proxy" henceforth) is requested to perform the operation
specified by the request method on the indicated HTTP resource and
return the result to the client. (See also Section 5.7 for how the
request to the proxy is formulated, including security requirements.)
This section specifies for any CoAP request the CoAP response that
the proxy should return to the client. How the proxy actually
satisfies the request is an implementation detail, although the
typical case is expected to be that the proxy translates and forwards
the request to an HTTP origin server.
Since HTTP and CoAP share the basic set of request methods,
performing a CoAP request on an HTTP resource is not so different
from performing it on a CoAP resource. The meanings of the
individual CoAP methods when performed on HTTP resources are
explained in the subsections of this section.
If the proxy is unable or unwilling to service a request with an HTTP
URI, a 5.05 (Proxying Not Supported) response is returned to the
client. If the proxy services the request by interacting with a
third party (such as the HTTP origin server) and is unable to obtain
a result within a reasonable time frame, a 5.04 (Gateway Timeout)
response is returned; if a result can be obtained but is not
understood, a 5.02 (Bad Gateway) response is returned.
The GET method requests the proxy to return a representation of the
HTTP resource identified by the request URI.
Upon success, a 2.05 (Content) Response Code SHOULD be returned. The
payload of the response MUST be a representation of the target HTTP
resource, and the Content-Format Option MUST be set accordingly. The
response MUST indicate a Max-Age value that is no greater than the
remaining time the representation can be considered fresh. If the
HTTP entity has an entity-tag, the proxy SHOULD include an ETag
Option in the response and process ETag Options in requests as
A client can influence the processing of a GET request by including
the following option:
Accept: The request MAY include an Accept Option, identifying the
preferred response content-format.
ETag: The request MAY include one or more ETag Options, identifying
responses that the client has stored. This requests the proxy to
send a 2.03 (Valid) response whenever it would send a 2.05
(Content) response with an entity-tag in the requested set
otherwise. Note that CoAP ETags are always strong ETags in the
HTTP sense; CoAP does not have the equivalent of HTTP weak ETags,
and there is no good way to make use of these in a cross-proxy.
The PUT method requests the proxy to update or create the HTTP
resource identified by the request URI with the enclosed
If a new resource is created at the request URI, a 2.01 (Created)
response MUST be returned to the client. If an existing resource is
modified, a 2.04 (Changed) response MUST be returned to indicate
successful completion of the request.
The DELETE method requests the proxy to delete the HTTP resource
identified by the request URI at the HTTP origin server.
A 2.02 (Deleted) response MUST be returned to the client upon success
or if the resource does not exist at the time of the request.
The POST method requests the proxy to have the representation
enclosed in the request be processed by the HTTP origin server. The
actual function performed by the POST method is determined by the
origin server and dependent on the resource identified by the request
If the action performed by the POST method does not result in a
resource that can be identified by a URI, a 2.04 (Changed) response
MUST be returned to the client. If a resource has been created on
the origin server, a 2.01 (Created) response MUST be returned.
10.2. HTTP-CoAP Proxying
If an HTTP request contains a Request-URI with a "coap" or "coaps"
URI, then the receiving HTTP endpoint (called "the proxy" henceforth)
is requested to perform the operation specified by the request method
on the indicated CoAP resource and return the result to the client.
This section specifies for any HTTP request the HTTP response that
the proxy should return to the client. Unless otherwise specified,
all the statements made are RECOMMENDED behavior; some highly
constrained implementations may need to resort to shortcuts. How the
proxy actually satisfies the request is an implementation detail,
although the typical case is expected to be that the proxy translates
and forwards the request to a CoAP origin server. The meanings of
the individual HTTP methods when performed on CoAP resources are
explained in the subsections of this section.
If the proxy is unable or unwilling to service a request with a CoAP
URI, a 501 (Not Implemented) response is returned to the client. If
the proxy services the request by interacting with a third party
(such as the CoAP origin server) and is unable to obtain a result
within a reasonable time frame, a 504 (Gateway Timeout) response is
returned; if a result can be obtained but is not understood, a 502
(Bad Gateway) response is returned.
10.2.1. OPTIONS and TRACE
As the OPTIONS and TRACE methods are not supported in CoAP, a 501
(Not Implemented) error MUST be returned to the client.
The GET method requests the proxy to return a representation of the
CoAP resource identified by the Request-URI.
Upon success, a 200 (OK) response is returned. The payload of the
response MUST be a representation of the target CoAP resource, and
the Content-Type and Content-Encoding header fields MUST be set
accordingly. The response MUST indicate a max-age directive that
indicates a value no greater than the remaining time the
representation can be considered fresh. If the CoAP response has an
ETag option, the proxy should include an ETag header field in the
A client can influence the processing of a GET request by including
the following options:
Accept: The most-preferred media type of the HTTP Accept header
field in a request is mapped to a CoAP Accept option. HTTP Accept
media-type ranges, parameters, and extensions are not supported by
the CoAP Accept option. If the proxy cannot send a response that
is acceptable according to the combined Accept field value, then
the proxy sends a 406 (Not Acceptable) response. The proxy MAY
then retry the request with further media types from the HTTP
Accept header field.
Conditional GETs: Conditional HTTP GET requests that include an "If-
Match" or "If-None-Match" request-header field can be mapped to a
corresponding CoAP request. The "If-Modified-Since" and "If-
Unmodified-Since" request-header fields are not directly supported
by CoAP but are implemented locally by a caching proxy.
The HEAD method is identical to GET except that the server MUST NOT
return a message-body in the response.
Although there is no direct equivalent of HTTP's HEAD method in CoAP,
an HTTP-CoAP proxy responds to HEAD requests for CoAP resources, and
the HTTP headers are returned without a message-body.
Implementation Note: An HTTP-CoAP proxy may want to try using a
block-wise transfer option [BLOCK] to minimize the amount of data
actually transferred, but it needs to be prepared for the case
that the origin server does not support block-wise transfers.
The POST method requests the proxy to have the representation
enclosed in the request be processed by the CoAP origin server. The
actual function performed by the POST method is determined by the
origin server and dependent on the resource identified by the request
If the action performed by the POST method does not result in a
resource that can be identified by a URI, a 200 (OK) or 204 (No
Content) response MUST be returned to the client. If a resource has
been created on the origin server, a 201 (Created) response MUST be
If any of the Location-* Options are present in the CoAP response, a
Location header field constructed from the values of these options is
The PUT method requests the proxy to update or create the CoAP
resource identified by the Request-URI with the enclosed
If a new resource is created at the Request-URI, a 201 (Created)
response is returned to the client. If an existing resource is
modified, either the 200 (OK) or 204 (No Content) Response Codes is
sent to indicate successful completion of the request.
The DELETE method requests the proxy to delete the CoAP resource
identified by the Request-URI at the CoAP origin server.
A successful response is 200 (OK) if the response includes an entity
describing the status or 204 (No Content) if the action has been
enacted but the response does not include an entity.
This method cannot currently be satisfied by an HTTP-CoAP proxy
function, as TLS to DTLS tunneling has not yet been specified. For
now, a 501 (Not Implemented) error is returned to the client.
11. Security Considerations
This section analyzes the possible threats to the protocol. It is
meant to inform protocol and application developers about the
security limitations of CoAP as described in this document. As CoAP
realizes a subset of the features in HTTP/1.1, the security
considerations in Section 15 of [RFC2616] are also pertinent to CoAP.
This section concentrates on describing limitations specific to CoAP.
11.1. Parsing the Protocol and Processing URIs
A network-facing application can exhibit vulnerabilities in its
processing logic for incoming packets. Complex parsers are well-
known as a likely source of such vulnerabilities, such as the ability
to remotely crash a node, or even remotely execute arbitrary code on
it. CoAP attempts to narrow the opportunities for introducing such
vulnerabilities by reducing parser complexity, by giving the entire
range of encodable values a meaning where possible, and by
aggressively reducing complexity that is often caused by unnecessary
choice between multiple representations that mean the same thing.
Much of the URI processing has been moved to the clients, further
reducing the opportunities for introducing vulnerabilities into the
servers. Even so, the URI processing code in CoAP implementations is
likely to be a large source of remaining vulnerabilities and should
be implemented with special care. CoAP access control
implementations need to ensure they don't introduce vulnerabilities
through discrepancies between the code deriving access control
decisions from a URI and the code finally serving up the resource
addressed by the URI. The most complex parser remaining could be the
one for the CoRE Link Format, although this also has been designed
with a goal of reduced implementation complexity [RFC6690]. (See
also Section 15.2 of [RFC2616].)
11.2. Proxying and Caching
As mentioned in Section 15.7 of [RFC2616], proxies are by their very
nature men-in-the-middle, breaking any IPsec or DTLS protection that
a direct CoAP message exchange might have. They are therefore
interesting targets for breaking confidentiality or integrity of CoAP
message exchanges. As noted in [RFC2616], they are also interesting
targets for breaking availability.
The threat to confidentiality and integrity of request/response data
is amplified where proxies also cache. Note that CoAP does not
define any of the cache-suppressing Cache-Control options that
HTTP/1.1 provides to better protect sensitive data.
For a caching implementation, any access control considerations that
would apply to making the request that generated the cache entry also
need to be applied to the value in the cache. This is relevant for
clients that implement multiple security domains, as well as for
proxies that may serve multiple clients. Also, a caching proxy MUST
NOT make cached values available to requests that have lesser
transport-security properties than those the proxy would require to
perform request forwarding in the first place.
Unlike the "coap" scheme, responses to "coaps" identified requests
are never "public" and thus MUST NOT be reused for shared caching,
unless the cache is able to make equivalent access control decisions
to the ones that led to the cached entry. They can, however, be
reused in a private cache if the message is cacheable by default in
Finally, a proxy that fans out Separate Responses (as opposed to
piggybacked Responses) to multiple original requesters may provide
additional amplification (see Section 11.3).
11.3. Risk of Amplification
CoAP servers generally reply to a request packet with a response
packet. This response packet may be significantly larger than the
request packet. An attacker might use CoAP nodes to turn a small
attack packet into a larger attack packet, an approach known as
amplification. There is therefore a danger that CoAP nodes could
become implicated in denial-of-service (DoS) attacks by using the
amplifying properties of the protocol: an attacker that is attempting
to overload a victim but is limited in the amount of traffic it can
generate can use amplification to generate a larger amount of
This is particularly a problem in nodes that enable NoSec access, are
accessible from an attacker, and can access potential victims (e.g.,
on the general Internet), as the UDP protocol provides no way to
verify the source address given in the request packet. An attacker
need only place the IP address of the victim in the source address of
a suitable request packet to generate a larger packet directed at the
As a mitigating factor, many constrained networks will only be able
to generate a small amount of traffic, which may make CoAP nodes less
attractive for this attack. However, the limited capacity of the
constrained network makes the network itself a likely victim of an
Therefore, large amplification factors SHOULD NOT be provided in the
response if the request is not authenticated. A CoAP server can
reduce the amount of amplification it provides to an attacker by
using slicing/blocking modes of CoAP [BLOCK] and offering large
resource representations only in relatively small slices. For
example, for a 1000-byte resource, a 10-byte request might result in
an 80-byte response (with a 64-byte block) instead of a 1016-byte
response, considerably reducing the amplification provided.
CoAP also supports the use of multicast IP addresses in requests, an
important requirement for M2M. Multicast CoAP requests may be the
source of accidental or deliberate DoS attacks, especially over
constrained networks. This specification attempts to reduce the
amplification effects of multicast requests by limiting when a
response is returned. To limit the possibility of malicious use,
CoAP servers SHOULD NOT accept multicast requests that can not be
authenticated in some way, cryptographically or by some multicast
boundary limiting the potential sources. If possible, a CoAP server
SHOULD limit the support for multicast requests to the specific
resources where the feature is required.
On some general-purpose operating systems providing a POSIX-style API
[IEEE1003.1], it is not straightforward to find out whether a packet
received was addressed to a multicast address. While many
implementations will know whether they have joined a multicast group,
this creates a problem for packets addressed to multicast addresses
of the form FF0x::1, which are received by every IPv6 node.
Implementations SHOULD make use of modern APIs such as
IPV6_RECVPKTINFO [RFC3542], if available, to make this determination.
11.4. IP Address Spoofing Attacks
Due to the lack of a handshake in UDP, a rogue endpoint that is free
to read and write messages carried by the constrained network (i.e.,
NoSec or PreSharedKey deployments with a nodes/key ratio > 1:1), may
easily attack a single endpoint, a group of endpoints, as well as the
whole network, e.g., by:
1. spoofing a Reset message in response to a Confirmable message or
Non-confirmable message, thus making an endpoint "deaf"; or
2. spoofing an ACK in response to a CON message, thus potentially
preventing the sender of the CON message from retransmitting, and
drowning out the actual response; or
3. spoofing the entire response with forged payload/options (this
has different levels of impact: from single-response disruption,
to much bolder attacks on the supporting infrastructure, e.g.,
poisoning proxy caches, or tricking validation/lookup interfaces
in resource directories and, more generally, any component that
stores global network state and uses CoAP as the messaging
facility to handle setting or updating state is a potential
4. spoofing a multicast request for a target node; this may result
in network congestion/collapse, a DoS attack on the victim, or
forced wake-up from sleeping; or
5. spoofing observe messages, etc.
Response spoofing by off-path attackers can be detected and mitigated
even without transport layer security by choosing a nontrivial,
randomized token in the request (Section 5.3.1). [RFC4086] discusses
randomness requirements for security.
In principle, other kinds of spoofing can be detected by CoAP only in
case Confirmable message semantics is used, because of unexpected
Acknowledgement or Reset messages coming from the deceived endpoint.
But this imposes keeping track of the used Message IDs, which is not
always possible, and moreover detection becomes available usually
after the damage is already done. This kind of attack can be
prevented using security modes other than NoSec.
With or without source address spoofing, a client can attempt to
overload a server by sending requests, preferably complex ones, to a
server; address spoofing makes tracing back, and blocking, this
attack harder. Given that the cost of a CON request is small, this
attack can easily be executed. Under this attack, a constrained node
with limited total energy available may exhaust that energy much more
quickly than planned (battery depletion attack). Also, if the client
uses a Confirmable message and the server responds with a Confirmable
separate response to a (possibly spoofed) address that does not
respond, the server will have to allocate buffer and retransmission
logic for each response up to the exhaustion of MAX_TRANSMIT_SPAN,
making it more likely that it runs out of resources for processing
legitimate traffic. The latter problem can be mitigated somewhat by
limiting the rate of responses as discussed in Section 4.7. An
attacker could also spoof the address of a legitimate client; this
might cause the server, if it uses separate responses, to block
legitimate responses to that client because of NSTART=1. All these
attacks can be prevented using a security mode other than NoSec, thus
leaving only attacks on the security protocol.
11.5. Cross-Protocol Attacks
The ability to incite a CoAP endpoint to send packets to a fake
source address can be used not only for amplification, but also for
cross-protocol attacks against a victim listening to UDP packets at a
given address (IP address and port). This would occur as follows:
o The attacker sends a message to a CoAP endpoint with the given
address as the fake source address.
o The CoAP endpoint replies with a message to the given source
o The victim at the given address receives a UDP packet that it
interprets according to the rules of a different protocol.
This may be used to circumvent firewall rules that prevent direct
communication from the attacker to the victim but happen to allow
communication from the CoAP endpoint (which may also host a valid
role in the other protocol) to the victim.
Also, CoAP endpoints may be the victim of a cross-protocol attack
generated through an endpoint of another UDP-based protocol such as
DNS. In both cases, attacks are possible if the security properties
of the endpoints rely on checking IP addresses (and firewalling off
direct attacks sent from outside using fake IP addresses). In
general, because of their lack of context, UDP-based protocols are
relatively easy targets for cross-protocol attacks.
Finally, CoAP URIs transported by other means could be used to incite
clients to send messages to endpoints of other protocols.
One mitigation against cross-protocol attacks is strict checking of
the syntax of packets received, combined with sufficient difference
in syntax. As an example, it might help if it were difficult to
incite a DNS server to send a DNS response that would pass the checks
of a CoAP endpoint. Unfortunately, the first two bytes of a DNS
reply are an ID that can be chosen by the attacker and that map into
the interesting part of the CoAP header, and the next two bytes are
then interpreted as CoAP's Message ID (i.e., any value is
acceptable). The DNS count words may be interpreted as multiple
instances of a (nonexistent but elective) CoAP option 0, or possibly
as a Token. The echoed query finally may be manufactured by the
attacker to achieve a desired effect on the CoAP endpoint; the
response added by the server (if any) might then just be interpreted
as added payload.
1 1 1 1 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
| ID | T, TKL, code
|QR| Opcode |AA|TC|RD|RA| Z | RCODE | Message ID
| QDCOUNT | (options 0)
| ANCOUNT | (options 0)
| NSCOUNT | (options 0)
| ARCOUNT | (options 0)
Figure 15: DNS Header ([RFC1035], Section 4.1.1) vs. CoAP Message
In general, for any pair of protocols, one of the protocols can very
well have been designed in a way that enables an attacker to cause
the generation of replies that look like messages of the other
protocol. It is often much harder to ensure or prove the absence of
viable attacks than to generate examples that may not yet completely
enable an attack but might be further developed by more creative
minds. Cross-protocol attacks can therefore only be completely
mitigated if endpoints don't authorize actions desired by an attacker
just based on trusting the source IP address of a packet.
Conversely, a NoSec environment that completely relies on a firewall
for CoAP security not only needs to firewall off the CoAP endpoints
but also all other endpoints that might be incited to send UDP
messages to CoAP endpoints using some other UDP-based protocol.
In addition to the considerations above, the security considerations
for DTLS with respect to cross-protocol attacks apply. For example,
if the same DTLS security association ("connection") is used to carry
data of multiple protocols, DTLS no longer provides protection
against cross-protocol attacks between these protocols.
11.6. Constrained-Node Considerations
Implementers on constrained nodes often find themselves without a
good source of entropy [RFC4086]. If that is the case, the node MUST
NOT be used for processes that require good entropy, such as key
generation. Instead, keys should be generated externally and added
to the device during manufacturing or commissioning.
Due to their low processing power, constrained nodes are particularly
susceptible to timing attacks. Special care must be taken in
implementation of cryptographic primitives.
Large numbers of constrained nodes will be installed in exposed
environments and will have little resistance to tampering, including
recovery of keying materials. This needs to be considered when
defining the scope of credentials assigned to them. In particular,
assigning a shared key to a group of nodes may make any single
constrained node a target for subverting the entire group.