Tech-invite3GPPspecsSIPRFCs
898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100

in Index   Prev   Next

RFC 7252

The Constrained Application Protocol (CoAP)

Pages: 112
Proposed Standard
Errata
Updated by:  79598613
Part 5 of 6 – Pages 64 to 86
First   Prev   Next

Top   ToC   RFC7252 - Page 64   prevText

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
Top   ToC   RFC7252 - Page 65
   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 12

8. 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
Top   ToC   RFC7252 - Page 66
   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.
Top   ToC   RFC7252 - Page 67
   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].
Top   ToC   RFC7252 - Page 68

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.
Top   ToC   RFC7252 - Page 69
   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
Top   ToC   RFC7252 - Page 70
   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.
Top   ToC   RFC7252 - Page 71
   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]).
Top   ToC   RFC7252 - Page 72
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
Top   ToC   RFC7252 - Page 73
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.
Top   ToC   RFC7252 - Page 74
   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.
Top   ToC   RFC7252 - Page 75
   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.
Top   ToC   RFC7252 - Page 76
   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.
Top   ToC   RFC7252 - Page 77

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.
Top   ToC   RFC7252 - Page 78
   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.
Top   ToC   RFC7252 - Page 79

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.
Top   ToC   RFC7252 - Page 80

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].)
Top   ToC   RFC7252 - Page 81

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.
Top   ToC   RFC7252 - Page 82
   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.
Top   ToC   RFC7252 - Page 83

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
Top   ToC   RFC7252 - Page 84
   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.
Top   ToC   RFC7252 - Page 85
   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.
Top   ToC   RFC7252 - Page 86
   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)

Next Section