RFC 7252
The Constrained Application Protocol (CoAP)
7. Discovery
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 available. 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 finishes. 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 seconds. 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.8.2.1. Caching
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 request. 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 further study.8.2.2. Proxying
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 client. 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 9.1.3.2.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 9.1.3.1. 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 9.1.3.2. The device also has an identity calculated from the public key and a list of identities of the nodes it can communicate with. 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 9.1.3.3. 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 approach.
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 intermediary.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 transport. +----------------------+ | Application | +----------------------+ +----------------------+ | Requests/Responses | |----------------------| CoAP | 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 inefficient.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.9.1.3.1. 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 [RFC6655]. 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]).
9.1.3.2. 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. Extension: elliptic_curves Type: elliptic_curves (0x000a) Length: 4 Elliptic Curves Length: 2 Elliptic curves (1 curve) Elliptic curve: secp256r1 (0x0017) Extension: ec_point_formats Type: ec_point_formats (0x000b) Length: 2 EC point formats Length: 1 Elliptic curves point formats (1) EC point format: uncompressed (0) Extension: signature_algorithms Type: signature_algorithms (0x000d) Length: 4 Data (4 bytes): 00 02 04 03 HashAlgorithm: sha256 (4) SignatureAlgorithm: ecdsa (3) Figure 14: DTLS Extensions Present for TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
9.1.3.2.1. Provisioning
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.9.1.3.3. 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 method.
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 specification.
There are two possible directions to access a resource via a forward-
proxy:
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.10.1.1. GET
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 described below. 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.
10.1.2. PUT
The PUT method requests the proxy to update or create the HTTP resource identified by the request URI with the enclosed representation. 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.10.1.3. DELETE
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.10.1.4. POST
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 URI. 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.10.2.2. GET
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 response. 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.
10.2.3. HEAD
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.10.2.4. POST
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 URI. 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 returned. If any of the Location-* Options are present in the CoAP response, a Location header field constructed from the values of these options is returned.10.2.5. PUT
The PUT method requests the proxy to update or create the CoAP resource identified by the Request-URI with the enclosed representation. 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.
10.2.6. DELETE
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.10.2.7. CONNECT
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 CoAP. 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 traffic.
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 victim. 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 amplification attack. 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 target.); or 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 address. 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.
(page 86 continued on part 6)
