]> 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. (This is the intended status; currently, the document is an individual submission only.) (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.

0. (Done as of this a draft): include the present process proposal.
   The document can then already be considered for WG adoption.
1. 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
2. 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.
3. 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.)
4. 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".
5. 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-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-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.

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.

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 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) 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. 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. 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. 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. 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. 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. 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 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. 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. 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. 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. IANA 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. 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.

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.