]> Constrained Application Protocol (CoAP): Corrections and Clarifications Universität Bremen TZI
Postfach 330440 Bremen D-28359 Germany +49-421-218-63921 cabo@tzi.org
RFC 7252 defines the Constrained Application Protocol (CoAP), along with a number of additional specifications, including RFC 7641, RFC 7959, RFC 8132, and RFC 8323. RFC 6690 defines the link format that is used in CoAP self-description documents. Some parts of the specification may be unclear or even contain errors that may lead to misinterpretations that may impair interoperability between different implementations. The present document provides corrections, additions, and clarifications to the RFCs cited; this document thus updates these RFCs. In addition, other clarifications related to the use of CoAP in other specifications, including RFC 7390 and RFC 8075, are also provided. About This Document Status information for this document may be found at . Discussion of this document takes place on the core Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .
Introduction defines the Constrained Application Protocol (CoAP), along with a number of additional specifications, including , , , and . defines the link format that is used in CoAP self-description documents. During implementation and interoperability testing of these RFCs, and in their practical use, some ambiguities and common misinterpretations have been identified, as well as a few errors. The present document summarizes identified issues and provides corrections needed for implementations of CoAP to interoperate, i.e., it constitutes an update to the RFCs referenced. This document also provides other clarifications related to common misinterpretations of the specification. References to CoAP should, therefore, also include this document. In addition, some clarifications and corrections are also provided for documents that are related to CoAP, including RFC 7390 and RFC 8075.
Process
Original text The present document is an Internet-Draft, which is not intended to be published as an RFC quickly. Instead, it will be maintained as a running document of the CoRE WG, probably for a number of years, until the need for new entries tails off and the document can finally be published as an RFC. (This paragraph to be rephrased when that happens.) The status of this document as a running document of the WG implies a consensus process that is applied in making updates to it. The rest of this subsection provides more details about this consensus process. (Consensus process TBD, but it will likely be based on an editor's version in a publicly accessible git repository, as well as periodic calls for consensus that lead to a new published Internet-Draft.)
Proposed text based on IETF 117 and 2023-08-30 CoRE WG interim discussion This section describes the process that will be used for developing the present document (called "-corr-clar" colloquially). This process might be revised as its execution progresses.
  1. (Done as of this a draft): include the present process proposal.
    The document can then already be considered for WG adoption.
  2. Go through the following available material and revise/create Github issues at ISSUES as needed:
    • Existing issues at ISSUES
      • More to be opened by Jon Shallow regarding Block-wise, see JON-ISSUES
    • CoAP FAQ at the CoRE WIKI WIKI-FAQ
      • Each point likely to become a new, short issue
  3. Categorize the Github issues at ISSUES as to the topics they relate to, by tagging them.
    Completing a first round of this will be a task for a dedicated team.
  4. For each issue or set of issues at ISSUES, confirm with the CoRE WG and gather feedback from affected protocol designers/implementors if the issue is best to be:
    • Included and covered in -corr-clar, as is or revised
    • Simply omitted in -corr-clar
    • Omitted in -corr-clar and left for a possible -bis document.
      (For example, this might be the case for some specific points related to RFC 7959.)
  5. Reshape the -corr-clar document in order to reflect a sequence of pairs (Diagnosis, Therapy), where:
    • Diagnosis is the gist of a set of Github issues to cover, and
    • Therapy is the correction or clarification to address those.
    Even though at a high-level, the scope should be already clear by looking at the table of contents. That is, at this stage, there is no need to necessarily elaborate the Therapy in detail, but it is necessary to make a reader understand "what we are dealing with and taking which direction".
  6. WG document work can then focus on improving the therapy parts, until all points are satisfactorily addressed and documented.
Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. When a section of this document makes formal corrections, additions or invalidations to text in a referenced RFC, this is clearly summarized. The text from the RFC that is being addressed is given and labeled "INCOMPLETE", "INCORRECT", or "INCORRECT AND INVALIDATED", followed by the correct text labeled "CORRECTED", where applicable. When text is added that does not simply correct text in previous specifications, it is given with the label "FORMAL ADDITION". Where a resolution has not yet been agreed, the resolution is marked PENDING. In this document, a reference to a section in RFC nnnn is written as RFC nnnn-<number>, where <number> is the section number.
RFC 7252
RFC7252-1.2: Terminology (Request-URI) uses the term "request URI" repeatedly, but only provides a vague definition in . Text should be added to the definitions in Section Terminology of .
INCOMPLETE; FORMAL ADDITION (Section 1.2):
Request URI:
The URI that identifies a resource on a server intended to be addressed by a request; constructed from the context of the request combined with Options present in the request using the process defined in Section Composing URIs from Options of , see Section Forward-Proxies of for further details. Related to the HTTP concept of "target URI"; see Section Determining the Target Resource of ; previously called "effective request URI" in Section Effective Request URI of .
PENDING. Note that a similar, but distinct concept is the "base URI", relative to which relative URIs are resolved. This is more complex in CoAP than in HTTP because CoAP can multicast requests (), expecting unicast responses; these need to be interpreted relative to the unicast source address from which the responses come. has:
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.
Similarly, (Caching) says:
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.
Further discussion of a more generalized response concept can be found in .
RFC7252-5.4.1: Critical Options and Error Messages introduces the concept of rejecting a message, by sending back a RST (Reset) message or by silently ignoring the rejected message. This can deal with messages for which a node does not have (e.g., no longer has) the necessary context to process it, such as a response to a message that was sent immediately before a node rebooted. The concept of rejecting a message is a quite powerful way to limit the complexity of dealing with a variety of error conditions. However, it seems overuses this instrument for the case of non-confirmable messages. describes Critical Options, which, if not implemented/understood by a node, may require the return of server errors. For Confirmable messages containing requests, unrecognized critical options in requests are handled by a 4.02 (Bad Option) response, while those in Confirmable messages with responses and Acknowledgements are rejected.
  • Unrecognized options of class "critical" that occur in a Confirmable request MUST cause the return of a 4.02 (Bad Option) response. This response SHOULD include a diagnostic payload describing the unrecognized option(s) (see Section 5.5.2).
  • Unrecognized options of class "critical" that occur in a Confirmable response, or piggybacked in an Acknowledgement, MUST cause the response to be rejected (Section 4.2).
The 4.02 error response enables clients to perform discovery of whether a critical option is recognized by a server, but surprisingly only for Confirmable messages. For unknown reasons, then goes on to handle all Non-confirmable messages with unrecognized critical options by rejecting them:
  • Unrecognized options of class "critical" that occur in a Non-confirmable message MUST cause the message to be rejected (Section 4.3).
This deprives the sender of a Non-confirmable request of the information what caused the rejection. However, using Non-confirmable messages does not automatically mean that the recipient does not have the context needed to process the message. This unexplained inconsistency has been present in since its initial publication, apparently without causing much trouble. Recently, has been describing a situation where discovery of Option support is more central to at least one use case; not being able to properly perform this discovery for Non-confirmable messages now emerges as an actual defect. This defect can be remedied by applying this change:
INCORRECT:
  • Unrecognized options of class "critical" that occur in a Non- confirmable message MUST cause the message to be rejected (Section 4.3).
CORRECTED:
  • Unrecognized options of class "critical" that occur in a Non-confirmable request SHOULD cause the return of a 4.02 (Bad Option) response. This response SHOULD include a diagnostic payload describing the unrecognized option(s) (see Section 5.5.2).
  • Unrecognized options of class "critical" that occur in a Non-confirmable response, or piggybacked in an Acknowledgement, MUST cause the response to be rejected (Section 4.3).
(This replacement text could be integrated in a less redundant way; the present proposal primarily aims at clarity.) Of course, existing implementations will not immediately change their behavior, so an implementation of a discovery process in will still need to deal with uncertainty for the foreseeable future, but the likelihood will reduce over time. Client implementations that are not updated and actually rely on not receiving an error response in this case will simply reject the message, causing little downside. As this is a technical change, it needs to be included in a standards-track RFC to become effective. The present document proposes to include the change in , which is likely to be the next standards-track specification to emerge from the CoRE WG and also directly can make use of the updated functionality. Note that the SHOULD about diagnostic payloads is repeated here; such a mandate usually needs to provide more information about when this interoperability requirement does not need to be met. now in many cases provides a better way to respond than a diagnostic payload; for conciseness, this observation is not included in the normative replacement text proposed above.
RFC7252-5.10.1/6.1: Query Parameters explains the query component of a URI as follows:
The query component contains non-hierarchical data that, along with data in the path component (Section 3.3), serves to identify a resource within the scope of the URI's scheme and naming authority (if any). [...]
So there is no technical difference between a path and a query component in a URI except that the path is hierarchical, and the query is non-hierarchical. Both combine with scheme and authority to identify the resource, and changing any of these leads to a different resource. generally follows this definition, but has a few passages where it is somewhat questionable whether they fully agree: Section Uri-Host, Uri-Port, Uri-Path, and Uri-Query of says:
[...] each Uri-Query Option specifies one argument parameterizing the resource.
(Analog text about Location-Query is in Section Location-Path and Location-Query of .) Similarly, Section coap URI Scheme of says:
The query serves to further parameterize the resource. [...]
This could be read to say that the same resource can be accessed with different parameters in the Uri-Query options. It is likely that these passages were meant in the sense of "parameterize the resource name", i.e., changing the parameters does indeed lead to a different resource. So this could be clarified by applying this change in these three places:
INCORRECT:
further parameterize the resource
CORRECTED:
further parameterize the resource name
However, the view that the query component supplies parameters to a request on a resource that exists independent of these parameters is widely held by implementers in the "big web" (HTTP) world, even if strictly follows . This view seems to be fueled by the way that an application may use (Section Disclosure of Sensitive Information in URIs of )...
client-side mechanisms to construct a target URI out of user-provided information, such as the query fields of a form using GET
This view also seems to be suggested to some by the way query parameters are used in specifications such as ; implementations of CoAP servers also often provide primitives to set up a single "resource handler" that bundles requests to a specific path and receives the query parameters as additional request parameters . establishes guidelines with respect to "URI Design and Ownership". Section of RFC 8820 specifically discusses the query component of the URI. On one hand, it says:
Applications can specify the syntax of queries for the resources under their control.
On the other hand, it warns:
Extensions MUST NOT constrain the format or semantics of queries, to avoid collisions and erroneous client assumptions. For example, an Extension that indicates that all query parameters with the name "sig" indicate a cryptographic signature would collide with potentially preexisting query parameters on sites and lead clients to assume that any matching query parameter is a signature.
It also acknowledges:
Per the "Form submission" section of [HTML5], HTML constrains the syntax of query strings used in form submission. New form languages are encouraged to allow creation of a broader variety of URIs (e.g., by allowing the form to create new path components, and so forth).
is a specification that defines a set of query parameters. It can be adopted by an "Application" in the sense of . The current discussion goes in the direction of providing an interface type (for use in if=) that a server can declare in resource discovery to indicate to a client that the conditional query parameters interface is available. contains a brief discussion of the role of query parameters in URIs. It points to , which discusses identifier comparison and points out that
[...] it is unspecified whether the order of values matters.
further mentions that in some implementations,
they might even be re-ordered, for instance by intermediaries.
is designed to allow evolution of the set of conditional query parameters and provides a registry for the registration of additional ones. To facilitate the introduction of new parameters, it has been discussed whether should adopt an "ignore unknown" policy. Since that policy would not necessarily apply to query parameters outside the conditional set, it would require a test whether a parameter is a conditional query parameter. The names of all parameters initially registered start with "c.", which might be a convention that might be part of the if= interface type. Any "ignore unknown" policy raises the question whether there, conversely, need to be "must understand" exceptions, here chosen by the client. For instance, the client might use the parameter name "C.pmin" instead of "c.pmin" to indicate that it wants the request to fail if its preference for a minimum period between notifications cannot be fulfilled. In summary: In the definitions of URIs and of HTTP, the URI query parameters are not much different from path components. In practice, implementations tend to provide ways to handle query parameters more in terms of additional parameters to a single resource handler that handles a number of related URIs, differing in query parameters only. There appears to be little to be gained by discussing this more in the documentation (outside the present document); however, the duality between these two perspectives on query parameters needs to be kept in mind in discussions.
RFC7252-5.10.5: Max-Age In the discussion of , a comment was made that it would be needed to define the point in time relative to which Max-Age is defined. A sender might reference it to the time it actually sends the message containing the option (and paragraph 3 of RFC7252-5.10.5 indeed requests that Max-Age be updated each time a message is retransmitted). The receiver of the message does not have reliable information about the time of sending, though. It may instead reference the Max-Age to the time of reception. This in effect extends the time of Max-Age by the latency of the packet. This extension was deemed acceptable for the purposes of , but may be suboptimal when Max-Age is about the lifetime of a response object.
INCOMPLETE:
The value is intended to be current at the time of transmission.
PENDING.
RFC7252-6.4: Decomposing URIs into Options notes (text updated with newer link):
The current specification for decomposing a URI into CoAP Options (Section 6.4) is correct; however the text may still be unclear to implementers who may think that the phrase "not including the delimiting slash characters" means simply omitting a trailing slash character in the URI path. This is incorrect. See the discussion outcome in email thread https://mailarchive.ietf.org/arch/msg/core/vqOiUreodGXqWZGeGOTREChCsKY/.
proceeds to propose adding another note at the end of . A slightly updated version of the proposed note might be:
FORMAL ADDITION at the end of :
Also note that a trailing slash character in the <path> component represents a separate, zero-character path segment (see the ABNF in ). This is encoded using a Uri-Path Option of zero length. The exception at the start of step 8 means that no such zero-character path segment is added for a trailing slash that immediately follows the authority (host and port).
RFC7252-7.2.1: "ct" Attribute (content-format code) As has been noted in , there is no information in about whether the "ct" target attribute can be present multiply or not. The text does indicate that the value of the attribute MAY be "a space-separated sequence of Content-Format codes, indicating that multiple content-formats are available", but it does not repeat the prohibition of multiple instances that the analogously structured "rt" and "if" attributes in Sections and of have. This appears to be an oversight. Published examples in and further illustrate that the space-separated approach is generally accepted to be the one to be used. There is no gain to be had from allowing both variants, and it would be likely to cause interoperability problems. At the 2022-11-23 CoRE WG interim meeting, there was agreement that should be marked "VERIFIED", which was done on 2023-01-18.
INCOMPLETE; FORMAL ADDITION:
The Content-Format code attribute MUST NOT appear more than once in a link.
RFC7252-9.1.1/9.1.2: (match boxing) Sections and of provide details about using CoAP over DTLS connections; in particular they restrict both message-id matching and request/response matching to within a single combination of DTLS session/DTLS epoch. At the time, this was a decision to be very conservative based on the wide variety of security implications a new DTLS epoch might have (which also were not widely understood, e.g., for a re-authentication). The normally short time between a request and a response made this rather strict boxing appear acceptable. However, with the Observe functionality , it is quite likely that significant time elapses between a request and the arrival of a notification that is sent back as a response, causing a need for the latter to use a different box from the original request. Also, additions to CoAP such as CoAP over connection-oriented transports and OSCORE create similar matching boxes that also do not fit certain likely use cases of these additions (e.g., with short-lived TCP connections as discussed in ). The match boxing semantics of the current protocol are clearly defined, but can be unsatisfactory given the current requirements. This calls for careful design choices and enhancements when developing extensions for CoAP or protocols and methods applicable to CoAP, such as in the cases overviewed in the following and .
DTLS with Connection ID PENDING:
OSCORE, KUDOS, and Group OSCORE The security protocol Object Security for Constrained RESTful Environments (OSCORE) defined in provides end-to-end security for CoAP messages at the application level, by using CBOR Object Signing and Encryption (COSE) . In order to protect their communications, two peers need to have already established an OSCORE Security Context. provides an example for a key update procedure, which two OSCORE peers can run for establishing a new shared OSCORE Security Context that replaces their old one. The recent key update protocol KUDOS specifies how two OSCORE peers can establish a new shared OSCORE Security Context that replaces their old one, with a number of advantages compared to the method defined in . The security protocol Group Object Security for Constrained RESTful Environments (Group OSCORE) defined in builds on OSCORE and protects group communication for CoAP . The management of the group keying material is entrusted to a Group Manager (see ), which provides the latest group keying material to a new group member upon its group joining, and can update the group keying material by performing a group rekeying. The following discusses how OSCORE, KUDOS, and Group OSCORE position themselves with respect to the match boxing, the transport used underlying CoAP, and the renewal of the keying material.
Match Boxing The security processing of (Group) OSCORE is agnostic of the value assumed by the CoAP Token and Message ID. Also, (Group) OSCORE can be seamlessly used in the presence of (cross-)proxies that will change the value of the CoAP Token and Message ID on the different communication legs. This does not affect the security processing at the (Group) OSCORE endpoints. Before any security processing is performed, the only use that (Group) OSCORE makes of the Token value is on the CoAP client upon receiving a response, in order to retrieve the right Security Context to use for decrypting and verifying the response. Even in case the Token value in a CoAP response is manipulated to induce a Request-Response matching at the client, there is no risk for the client to successfully decrypt the response instead of failing as expected. This is because, per , the OSCORE Master Secret of each OSCORE Security Context is required not only to be secret, but also to have a good amount of randomness. Building on that, an HKDF is used to derive the actual encryption keys from the Master Secret and, optionally, from an additional Master Salt. Furthermore, for each OSCORE Security Context, the quartet (Master Secret, Master Salt, ID Context, Sender ID) must be unique. As per , this is a hard requirement and guarantees unique (key, nonce) pairs for the AEAD algorithm used. In Group OSCORE, the Security Context extends that of OSCORE, and the same as above holds (see Sections , , and of ). Finally, (Group) OSCORE performs a separate secure match boxing under its own control, by cryptographically binding each protected request with all the corresponding protected responses. This is achieved by means of the COSE external_aad involved during the security processing of protected messages (see and ).
Underlying Transport The security protocol (Group) OSCORE does not have any requirement on binding the Security Context in use to specific addressing information used by the transport protocol underlying CoAP. What occurs below (Group) OSCORE with transport-specific addressing information is transparent to (Group) OSCORE, but it needs to work well enough to ensure that received data is delivered to (Group) OSCORE for security processing. Consistent with the above, (Group) OSCORE does not interfere with any low-layer, transport specific information. Instead, it entrusts data to a Request-Response exchange mechanism that can rely on different means to enforce the Request-Response matching at the transport level (e.g., the 5-tuple, the CoAP Message ID, a file handle). Also, (Group) OSCORE does not alter the fact that a CoAP response needs to come from where the corresponding CoAP request was sent, which simply follows from using transports where that is a requirement. Furthermore, two peers can seamlessly use (Group) OSCORE also in the presence of cross-proxies that change transport across different communication legs. This does not affect the security processing at the (Group) OSCORE endpoints. Practically, (Group) OSCORE relies on the underlying CoAP implementation for obtaining received CoAP messages on which to perform the expected security processing. Upon receiving a protected message, the recipient endpoint retrieves the OSCORE Security Context to use for decryption based on key identifier information specified in the CoAP OSCORE Option of protected requests, and on the value of the CoAP Token of protected responses. In OSCORE, the key identifier information in request messages is typically limited to a "kid", with a value the OSCORE Sender ID associated with the message sender. In case Sender IDs are not unique among different OSCORE Security Contexts stored by the same peer, it is possible to disambiguate by additionally using a "kid context" identifying the OSCORE Security Context as a whole. Instead, response messages are not required to convey key identifier information, as the client can rely on the Token conveyed in the response for retrieving the Security Context to use (see above). In Group OSCORE, the key identifier information in request messages always includes also a "kid context", whose value is used as identifier of the OSCORE group associated with the Security Context to use for security processing of the exchanged message. Response messages are also required to convey a "kid" as key identifier information (i.e., the OSCORE Sender ID associated with the message sender), if the corresponding request was protected with the group mode of Group OSCORE (see ) . Some particular uses of (Group) OSCORE enable to build OSCORE-based tunneling . In such a case, a CoAP server might have to enforce that some OSCORE Security Contexts are not just looked up by a "kid" and similar key identifier information from the CoAP OSCORE Option in the incoming request to decrypt. Such a lookup should also rely on the alleged client's address, or on an alternative identifier of the tunnel from which the request came from.
Key Update Updating an OSCORE Security Context does not change or interfere with the values of the Token or Message ID used in the exchanged CoAP messages. However, if long-term exchanges are involved (e.g., CoAP Observations ), one has to be careful to ensure that updating the Security Context does not impair the security properties of (Group) OSCORE or result in other security vulnerabilities. The following provides more details about key update, separately for OSCORE, KUDOS, and Group OSCORE.
  • OSCORE: tacitly assumes that two peers terminate any ongoing CoAP Observation that they still have ongoing, upon installing a new OSCORE Security Context, irrespective of the method used to perform the key update. On these premises, a belated response protected with the old OSCORE Security Context will fail decryption, as that Security Context is not available anymore on the receiving client.
  • KUDOS: The key update protocol KUDOS allows the two OSCORE peers to negotiate about preserving their ongoing CoAP Observations across the performed key update. If and only if both peers agree to do that during an execution of KUDOS, their Observations will remain active after installing the new OSCORE Security Context, which the two peers will use from then on to protect their exchanged Observe notifications. Furthermore, irrespective of the method used to perform a key update, updates the security protocol OSCORE in order to prevent security issues that can arise from misbinding a request and a response, when those are protected with two different OSCORE Security Contexts. Such an update to the OSCORE protocol requires a server to include its own Sender Sequence Number as Partial IV of an outgoing response, when protecting it with a Security Context different from the one used to protect the corresponding request. An exception safely applies to the response messages that are sent when running the key update procedure defined in .
  • Group OSCORE: The Group Manager can distribute new group keying material to the members of an OSCORE group, by performing a group rekeying. When receiving updated group keying material from the Group Manager, either upon joining the group or by participating in a group rekeying, a group member uses that material to install a new, commonly shared Group OSCORE Security Context, which replaces the old one (if any is stored). Also, Group OSCORE makes it possible for group members to safely preserve their ongoing active requests (e.g., CoAP Observations), also across the establishment of new Group OSCORE Security Contexts. This is achieved by virtue of how the Group Manager assigns and maintains the identifiers of OSCORE groups (see ). Furthermore, analogous to the update that makes on the OSCORE protocol with respect to protecting responses, Group OSCORE prevents security issues that can arise from misbinding a request and a response, when those are protected with two different Group OSCORE Security Contexts. In the same way specified in for OSCORE, Group OSCORE requires a server to include its own Sender Sequence Number as Partial IV of an outgoing response, when protecting it with a Security Context different from the one used to protect the corresponding request (see Sections and of ).
Eclipse/Californium Enhancements may be called for optimizations such as Eclipse/Californium EndpointContextMatcher might not work properly unless both sides of the communication agree on the extent of the matching boxes. Mechanisms to indicate capabilities and choices selected may need to be defined; also, a way to define the progression of matching boxes needs to be defined that is compatible with the security properties of the underlying protocols. This may require new efforts, to be initiated based on some formative contributions. PENDING. Relevant starting points for retrieving existing discussion of this issue include:
  • https://mailarchive.ietf.org/arch/msg/core/biDJ8n4w0kBQATzyh9xHlKnGy1o/
    ("DTLS and Epochs")
  • https://mailarchive.ietf.org/arch/msg/core/TsyyKIHQ1FJtAvAo0ODNEt2Ileo/
    ("Connection ID")
  • https://github.com/core-wg/corrclar/issues/9
    ("Clarify/revise language around epochs in section 9.1.1 #9")
RFC 7252-9.1/11.3: Handling outdated addresses and security contexts
INCOMPLETE:
Tools for mitigating these scenarios were unavailable when CoAP originally was specified, and are now explained.
PENDING. Information obtained about an established communication partner can experience continuity interruptions and become obsolete. This can happen on different levels: For example, return routability information is lost when client's IP address changes; and information about whether a request was already handled can be lost when an OSCORE context is recovered as described in its . No matter the cause of the loss, a server still needs to maintain its security and amplification mitigation properties. The concerns addressed in the following subsections are independent on a specification level, but are described together because they can be addressed with the same tools -- moreover, a single round trip of using Echo in a response can address both at the same time. In some scenarios, these are even expected to coincide. (move) A safe option is always to reject the initial request and request confirmation. The RECOMMENDED way to do that is using CoAP's mechanism of sending a 4.01 (Unauthorized) response with an Echo option (where a subsequent request with the same Echo value proves to the server that the destination was reachable); clients SHOULD act to the Echo option as specified in . Tools specific to a security protocol, such as RRC in case of DTLS, may be used. However, their use may depend on successful negotiation.
Amplification mitigation and return routability CoAP servers have to mitigate the effects of traffic amplification as required in ; the maximum acceptable amplification factor of 3 is now the IETF consensus reflected for CoAP in , which can be summarized for this application as follows: If the server has learned that the client is reachable on the request's sender address, it can send a response. Otherwise, if the response does not exceed the request's size by a factor of 3 (, item 3), the server can answer the request successfully, but should still include an Echo value, whose presence in the next request serves to confirm the client's address. Otherwise, a 4.01 (Unautorized) error response with an Echo value is sent. Address verification is triggered both for new clients and for existing clients that changed their address. This situation can happen at any time, especially after a prolonged period of quiescence, regardless of the security protocol. Verifying the client's address is not only crucial for mitigating amplification attacks , but also to avoid traffic misdirection. describes options for how to use RRC messages to distinguish different cases. A 4.01 response with Echo can perform some of the same functions, with the Echo value replacing the RRC cookie. However, it does not offer a way to distinguish between non-preferred and preferred paths. Where that distinction matters, RRC provides the right tools to make it.
Replay protection Security mechanisms can offer trade-offs between performance and the security properties freshness and replay protection. They sometimes use names such as "0RTT" (zero round-trip time). With those mechanisms, the server recognizes that a request is sent in such a 0RTT mode, but can still decide to send a response. The general trade-off is that an attacker may intercept such a message and replay it at any later time, possibly multiple times, without the server having a reliable way of recognizing the replay. The semantics of CoAP are conducive to using such facilities: Safe requests are recognized by their request method code to not have side effects. Nonetheless, more aspects need to be considered: There is no risk of metadata revealing data if the server answers a request multiple times. Kinds of metadata to look out for are the size of the response (which, in a replay situation, can give an active attacker additional data) as well as any processing delays. (Side effects would also fall into that category, but there should not be any effects for safe requests). If nothing else, GET requests to constant resources, such as queries to /.well-known/core, can often be responded to safely on the CoAP layer even without any replay protection. There are resources for which more requests than those with safe request methods may be handled without replay protection, but as that assessment is hard to make, it is prudent to err at the side of caution. CoAP has no error code like HTTP's 425 Too Early with which a server could ask the client to resubmit its request later when all the security mechanism's guarantees are available. Instead, servers can send 4.01 Unauthorized responses with Echo option; clients then repeat the request with the Echo value in the request. describes how this is used to recover loss of state in OSCORE. Exceeding what is described there, a server can safely send a successful response, provided its criteria for 0RTT responses are met. The server can still send an Echo option with the successful response: Only when the client repeats that Echo value in a subsequent response can the replay window be initialized. Implementers of OSCORE should be aware that answering potential replays can only be determined to be safe from the CoAP application's point of view. As always, unless the sequence number in the request has just been removed from an initialized replay window, the response can not reuse the request's nonce, but needs to be sent with a new sequence number from the server's space. Requests with 0RTT properties currently cannot happen in DTLS because 0-RTT Data is not allowed for CoAP (cf. ). However, that may change if a future document defines a profile for using early data with CoAP.
RFC 7252-12.3: Content-Format Registry established the CoAP Content-Formats Registry, which maps a combination of an Internet Media Type with an HTTP Content Coding, collectively called a Content-Format, to a concise numeric identifier for that Content-Format. The "Media Type" is more than a Media-Type-Name (see for an extensive discussion), i.e., it may contain parameters beyond the mere combination of a type-name and a subtype-name registered in , as per , conventionally identified by the two names separated by a slash. This construct is often called a Content Type to reduce the confusion with a Media-Type-Name (e.g., in , which then however also opts to use the term Media Type for the same information set). The second column of the Content-Format registry is the Content Coding, which is defined in . For historical reasons, the HTTP header field that actually carries the content coding is called Content-Encoding; this often leads to the misnaming of Content Coding as "content encoding". As has been noted in , the text in incorrectly uses these terms in the context of content types and content coding:
  1. The field that describes the Content Type is called "Media Type". This can lead to the misunderstanding that this column just carries a Media-Type-Name (such as "text/plain"), while it actually also can carry media type parameters (as in "text/plain; charset=UTF-8").
  2. The field that describes the Content Coding uses the incorrect name "Content Encoding".
INCORRECT, CORRECTED:
The VERIFIED Errata Report corrects the usage of "Content-Encoding" in the text and changes the name of the first column of the Content-Format registry to "Content Type" and the name of the second field to "Content Coding". This change has been carried out by IANA.
also has some notes on what would be valid or invalid Content-Format registrations. These are not repeated here; they are however quite useful as a reference when preparing additional Content-Format registrations.
IANA Considerations This document makes no new requests to IANA. Individual clarifications may contain IANA considerations; as for example in .
Security Considerations This document provides a number of corrections and clarifications to existing RFCs, but it does not make any changes with regard to the security aspects of the protocol. As a consequence, the security considerations of the referenced RFCs apply without additions. (To be changed when that is no longer true; probably the security considerations will then be on the individual clarifications.)
References Normative References Constrained RESTful Environments (CoRE) Link Format This specification defines Web Linking using a link format for use by constrained web servers to describe hosted resources, their attributes, and other relationships between links. Based on the HTTP Link Header field defined in RFC 5988, the Constrained RESTful Environments (CoRE) Link Format is carried as a payload and is assigned an Internet media type. "RESTful" refers to the Representational State Transfer (REST) architecture. A well-known URI is defined as a default entry point for requesting the links hosted by a server. [STANDARDS-TRACK] The Constrained Application Protocol (CoAP) The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation. CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments. Observing Resources in the Constrained Application Protocol (CoAP) The Constrained Application Protocol (CoAP) is a RESTful application protocol for constrained nodes and networks. The state of a resource on a CoAP server can change over time. This document specifies a simple protocol extension for CoAP that enables CoAP clients to "observe" resources, i.e., to retrieve a representation of a resource and keep this representation updated by the server over a period of time. The protocol follows a best-effort approach for sending new representations to clients and provides eventual consistency between the state observed by each client and the actual resource state at the server. Block-Wise Transfers in the Constrained Application Protocol (CoAP) The Constrained Application Protocol (CoAP) is a RESTful transfer protocol for constrained nodes and networks. Basic CoAP messages work well for small payloads from sensors and actuators; however, applications will need to transfer larger payloads occasionally -- for instance, for firmware updates. In contrast to HTTP, where TCP does the grunt work of segmenting and resequencing, CoAP is based on datagram transports such as UDP or Datagram Transport Layer Security (DTLS). These transports only offer fragmentation, which is even more problematic in constrained nodes and networks, limiting the maximum size of resource representations that can practically be transferred. Instead of relying on IP fragmentation, this specification extends basic CoAP with a pair of "Block" options for transferring multiple blocks of information from a resource representation in multiple request-response pairs. In many important cases, the Block options enable a server to be truly stateless: the server can handle each block transfer separately, with no need for a connection setup or other server-side memory of previous block transfers. Essentially, the Block options provide a minimal way to transfer larger representations in a block-wise fashion. A CoAP implementation that does not support these options generally is limited in the size of the representations that can be exchanged, so there is an expectation that the Block options will be widely used in CoAP implementations. Therefore, this specification updates RFC 7252. PATCH and FETCH Methods for the Constrained Application Protocol (CoAP) The methods defined in RFC 7252 for the Constrained Application Protocol (CoAP) only allow access to a complete resource, not to parts of a resource. In case of resources with larger or complex data, or in situations where resource continuity is required, replacing or requesting the whole resource is undesirable. Several applications using CoAP need to access parts of the resources. This specification defines the new CoAP methods, FETCH, PATCH, and iPATCH, which are used to access and update parts of a resource. CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets The Constrained Application Protocol (CoAP), although inspired by HTTP, was designed to use UDP instead of TCP. The message layer of CoAP over UDP includes support for reliable delivery, simple congestion control, and flow control. Some environments benefit from the availability of CoAP carried over reliable transports such as TCP or Transport Layer Security (TLS). This document outlines the changes required to use CoAP over TCP, TLS, and WebSockets transports. It also formally updates RFC 7641 for use with these transports and RFC 7959 to enable the use of larger messages over a reliable transport. Object Security for Constrained RESTful Environments (OSCORE) This document defines Object Security for Constrained RESTful Environments (OSCORE), a method for application-layer protection of the Constrained Application Protocol (CoAP), using CBOR Object Signing and Encryption (COSE). OSCORE provides end-to-end protection between endpoints communicating using CoAP or CoAP-mappable HTTP. OSCORE is designed for constrained nodes and networks supporting a range of proxy operations, including translation between different transport protocols. Although an optional functionality of CoAP, OSCORE alters CoAP options processing and IANA registration. Therefore, this document updates RFC 7252. CBOR Object Signing and Encryption (COSE): Structures and Process Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need to be able to define basic security services for this data format. This document defines the CBOR Object Signing and Encryption (COSE) protocol. This specification describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization. This specification additionally describes how to represent cryptographic keys using CBOR. This document, along with RFC 9053, obsoletes RFC 8152. Concise Problem Details for Constrained Application Protocol (CoAP) APIs This document defines a concise "problem detail" as a way to carry machine-readable details of errors in a Representational State Transfer (REST) response to avoid the need to define new error response formats for REST APIs for constrained environments. The format is inspired by, but intended to be more concise than, the problem details for HTTP APIs defined in RFC 7807. Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References URI-Path abbreviation in CoAP Sandelman Software Works Applications built on CoAP face a conflict between the technical need for short message sizes and the interoperability requirement of following BCP190 and thus registering (relatively verbose) well-known URI paths. This document introduces an option that allows expressing well-known paths in as little as two bytes. URI Design and Ownership Section 1.1.1 of RFC 3986 defines URI syntax as "a federated and extensible naming system wherein each scheme's specification may further restrict the syntax and semantics of identifiers using that scheme." In other words, the structure of a URI is defined by its scheme. While it is common for schemes to further delegate their substructure to the URI's owner, publishing independent standards that mandate particular forms of substructure in URIs is often problematic. This document provides guidance on the specification of URI substructure in standards. This document obsoletes RFC 7320 and updates RFC 3986. Guidance on RESTful Design for Internet of Things Systems Ericsson Siemens This document gives guidance for designing Internet of Things (IoT) systems that follow the principles of the Representational State Transfer (REST) architectural style. This document is a product of the IRTF Thing-to-Thing Research Group (T2TRG). "Too Many Requests" Response Code for the Constrained Application Protocol A Constrained Application Protocol (CoAP) server can experience temporary overload because one or more clients are sending requests to the server at a higher rate than the server is capable or willing to handle. This document defines a new CoAP response code for a server to indicate that a client should reduce the rate of requests. HTTP Semantics The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. CoAP: Non-traditional response forms Universität Bremen TZI In CoAP as defined by RFC 7252, responses are always unicast back to a client that posed a request. The present memo describes two forms of responses that go beyond that model. The design spaces for the new CoAP Options proposed to represent these responses are now sufficiently understood that they can be developed to standards-track specifications, either in this document or by transferring the specification for an Option to a document that that Option closely works with. Conditional Query Parameters for CoAP Observe Tampere University Dogtiger Labs Qualcomm Technologies, Inc. This specification defines Conditional Notification and Control Query Parameters compatible with CoAP Observe (RFC7641). Uniform Resource Identifier (URI): Generic Syntax A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] RFC Errata Report 4895 RFC Errata Report 4954 RFC Errata Report 5078 Key Update for OSCORE (KUDOS) RISE AB RISE AB Communications with the Constrained Application Protocol (CoAP) can be protected end-to-end at the application-layer by using the security protocol Object Security for Constrained RESTful Environments (OSCORE). Under some circumstances, two CoAP endpoints need to update their OSCORE keying material before communications can securely continue, e.g., due to approaching key usage limits. This document defines Key Update for OSCORE (KUDOS), a lightweight key update procedure that two CoAP endpoints can use to update their OSCORE keying material by establishing a new OSCORE Security Context. Accordingly, this document updates the use of the OSCORE flag bits in the CoAP OSCORE Option as well as the protection of CoAP response messages with OSCORE. Also, it deprecates the key update procedure specified in Appendix B.2 of RFC 8613. Therefore, this document updates RFC 8613. Group Communication for the Constrained Application Protocol (CoAP) IoTconsultancy.nl RISE AB The Constrained Application Protocol (CoAP) is a web transfer protocol for constrained devices and constrained networks. In a number of use cases, constrained devices often naturally operate in groups (e.g., in a building automation scenario, all lights in a given room may need to be switched on/off as a group). This document specifies the use of CoAP for group communication, including the use of UDP/IP multicast as the default underlying data transport. Both unsecured and secured CoAP group communication are specified. Security is achieved by use of the Group Object Security for Constrained RESTful Environments (Group OSCORE) protocol. The target application area of this specification is any group communication use cases that involve resource-constrained devices or networks that support CoAP. This document replaces and obsoletes RFC 7390, while it updates RFC 7252 and RFC 7641. Group Object Security for Constrained RESTful Environments (Group OSCORE) RISE AB Ericsson AB Ericsson AB Ericsson AB RISE AB This document defines the security protocol Group Object Security for Constrained RESTful Environments (Group OSCORE), providing end-to-end security of messages exchanged with the Constrained Application Protocol (CoAP) between members of a group, e.g., sent over IP multicast. In particular, the described protocol defines how OSCORE is used in a group communication setting to provide source authentication for CoAP group requests, sent by a client to multiple servers, and for protection of the corresponding CoAP responses. Group OSCORE also defines a pairwise mode where each member of the group can efficiently derive a symmetric pairwise key with each other member of the group for pairwise OSCORE communication. Group OSCORE can be used between endpoints communicating with CoAP or CoAP- mappable HTTP. OSCORE-capable Proxies RISE AB RISE AB Object Security for Constrained RESTful Environments (OSCORE) can be used to protect CoAP messages end-to-end between two endpoints at the application layer, also in the presence of intermediaries such as proxies. This document defines how to use OSCORE for protecting CoAP messages also between an origin application endpoint and an intermediary, or between two intermediaries. Also, it defines rules to escalate the protection of a CoAP option, in order to encrypt and integrity-protect it whenever possible. Finally, it defines how to secure a CoAP message by applying multiple, nested OSCORE protections, e.g., both end-to-end between origin application endpoints; and between an application endpoint and an intermediary or between two intermediaries. Therefore, this document updates RFC 8613. Furthermore, this document updates RFC 8768, by explicitly defining the processing with OSCORE for the CoAP option Hop-Limit. The approach defined in this document can be seamlessly used with Group OSCORE, for protecting CoAP messages when group communication is used in the presence of intermediaries. EndpointContextMatcher.java Connection Identifier for DTLS 1.2 This document specifies the Connection ID (CID) construct for the Datagram Transport Layer Security (DTLS) protocol version 1.2. A CID is an identifier carried in the record layer header that gives the recipient additional information for selecting the appropriate security association. In "classical" DTLS, selecting a security association of an incoming DTLS record is accomplished with the help of the 5-tuple. If the source IP address and/or source port changes during the lifetime of an ongoing DTLS session, then the receiver will be unable to locate the correct security context. The new ciphertext record format with the CID also provides content type encryption and record layer padding. This document updates RFC 6347. libcoap: coap_resource(3) n.d. Amplification Attacks Using the Constrained Application Protocol (CoAP) Ericsson AB Ericsson AB Energy Harvesting Solutions Protecting Internet of Things (IoT) devices against attacks is not enough. IoT deployments need to make sure that they are not used for Distributed Denial-of-Service (DDoS) attacks. DDoS attacks are typically done with compromised devices or with amplification attacks using a spoofed source address. This document gives examples of different theoretical amplification attacks using the Constrained Application Protocol (CoAP). The goal with this document is to raise awareness and to motivate generic and protocol-specific recommendations on the usage of CoAP. Some of the discussed attacks can be mitigated by not using NoSec or by using the Echo option. Return Routability Check for DTLS 1.2 and DTLS 1.3 University of Applied Sciences Bonn-Rhein-Sieg Linaro This document specifies a return routability check for use in context of the Connection ID (CID) construct for the Datagram Transport Layer Security (DTLS) protocol versions 1.2 and 1.3. Implementations offering the CID functionality described in RFC 9146 and RFC 9147 are encouraged to also provide the return routability check functionality described in this document. For this reason, this document updates RFC 9146 and RFC 9147. TLS/DTLS 1.3 Profiles for the Internet of Things University of Applied Sciences Bonn-Rhein-Sieg Linaro Sandelman Software Works RFC 7925 offers guidance to developers on using TLS/DTLS 1.2 for Internet of Things (IoT) devices with resource constraints. This document is a companion to RFC 7925, defining TLS/DTLS 1.3 profiles for IoT devices. Additionally, it updates RFC 7925 with respect to the X.509 certificate profile and ciphersuite requirements. Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document provides an overview of HTTP architecture and its associated terminology, defines the "http" and "https" Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations. Issues in Identifier Comparison for Security Purposes Identifiers such as hostnames, URIs, IP addresses, and email addresses are often used in security contexts to identify security principals and resources. In such contexts, an identifier presented via some protocol is often compared using some policy to make security decisions such as whether the security principal may access the resource, what level of authentication or encryption is required, etc. If the parties involved in a security decision use different algorithms to compare identifiers, then failure scenarios ranging from denial of service to elevation of privilege can result. This document provides a discussion of these issues that designers should consider when defining identifiers and protocols, and when constructing architectures that use multiple protocols. EST-coaps: Enrollment over Secure Transport with the Secure Constrained Application Protocol Enrollment over Secure Transport (EST) is used as a certificate provisioning protocol over HTTPS. Low-resource devices often use the lightweight Constrained Application Protocol (CoAP) for message exchanges. This document defines how to transport EST payloads over secure CoAP (EST-coaps), which allows constrained devices to use existing EST functionality for provisioning certificates. Constrained RESTful Environments (CoRE) Resource Directory In many Internet of Things (IoT) applications, direct discovery of resources is not practical due to sleeping nodes or networks where multicast traffic is inefficient. These problems can be solved by employing an entity called a Resource Directory (RD), which contains information about resources held on other servers, allowing lookups to be performed for those resources. The input to an RD is composed of links, and the output is composed of links constructed from the information stored in the RD. This document specifies the web interfaces that an RD supports for web servers to discover the RD and to register, maintain, look up, and remove information on resources. Furthermore, new target attributes useful in conjunction with an RD are defined. TCP Usage Guidance in the Internet of Things (IoT) This document provides guidance on how to implement and use the Transmission Control Protocol (TCP) in Constrained-Node Networks (CNNs), which are a characteristic of the Internet of Things (IoT). Such environments require a lightweight TCP implementation and may not make use of optional functionality. This document explains a number of known and deployed techniques to simplify a TCP stack as well as corresponding trade-offs. The objective is to help embedded developers with decisions on which TCP features to use. Constrained Application Protocol (CoAP): Echo, Request-Tag, and Token Processing This document specifies enhancements to the Constrained Application Protocol (CoAP) that mitigate security issues in particular use cases. The Echo option enables a CoAP server to verify the freshness of a request or to force a client to demonstrate reachability at its claimed network address. The Request-Tag option allows the CoAP server to match block-wise message fragments belonging to the same request. This document updates RFC 7252 with respect to the following: processing requirements for client Tokens, forbidding non-secure reuse of Tokens to ensure response-to-request binding when CoAP is used with a security protocol, and amplification mitigation (where the use of the Echo option is now recommended). Sensor Measurement Lists (SenML) Fields for Indicating Data Value Content-Format The Sensor Measurement Lists (SenML) media types support multiple types of values, from numbers to text strings and arbitrary binary Data Values. In order to facilitate processing of binary Data Values, this document specifies a pair of new SenML fields for indicating the content format of those binary Data Values, i.e., their Internet media type, including parameters as well as any content codings applied. Media Types IANA Media Type Specifications and Registration Procedures This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice.
Acknowledgements The present document is modeled after RFC 4815 and the Internet-Drafts of the ROHC WG that led to it. Many thanks to the co-chairs of the ROHC WG and WG members that made this a worthwhile and successful experiment at the time.