tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 7252

 
 
 

The Constrained Application Protocol (CoAP)

Part 5 of 6, p. 64 to 86
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 64 
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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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 RFC Part