Constrained Application Protocol (CoAP): Corrections and Clarifications
Internet-Draft draft-bormann-core-corr-clar-04
Carsten Bormann
Universität Bremen TZI
Postfach 330440
Bremen
D-28359
Germany
+49-421-218-63921
cabo@tzi.org
02 July 2024
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 https://datatracker.ietf.org/doc/draft-bormann-core-corr-clar/.
Discussion of this document takes place on the core Working Group mailing list (mailto:core@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/core/. Subscribe at https://www.ietf.org/mailman/listinfo/core/.
Source for this draft and an issue tracker can be found at https://github.com/core-wg/corrclar.
Introduction
[RFC7252] defines the Constrained Application Protocol (CoAP), along with a number of additional specifications, including [RFC7641], [RFC7959], [RFC8132], and [RFC8323]. [RFC6690] 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 [RFC2119] [RFC8174] 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)
[RFC7252] uses the term "request URI" repeatedly, but only provides a vague definition in Section 5.7.2 of [RFC7252]. Text should be added to the definitions in Section Terminology of [RFC7252].
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 [RFC7252], see Section Forward-Proxies of [RFC7252] for further details. Related to the HTTP concept of "target URI"; see Section Determining the Target Resource of [RFC9110]; previously called "effective request URI" in Section Effective Request URI of [RFC7230].
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 Section 8 of [RFC7252], expecting unicast responses; these need to be interpreted relative to the unicast source address from which the responses come.
Section 8.2 of [RFC7252] 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, Section 8.2.1 of [RFC7252] (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 [I-D.bormann-core-responses].
RFC7252-5.10.5: Max-Age
In the discussion of [RFC8516], 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 [RFC8516], 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
[Err4895] 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/.
[Err4895] proceeds to propose adding another note at the end of Section 6.4 of [RFC7252]. A slightly updated version of the proposed note might be:
INCOMPLETE; FORMAL ADDITION at the end of Section 6.4 of [RFC7252]:
Also note that a trailing slash character in the <path> component represents a separate, zero-character path segment (see the ABNF in Section 3.3 of [RFC3986]). 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).
This means that for a CoAP server, no difference is visible between a request that was generated from the URI coap://authority/ and one that was generated from the URI coap://authority -- in both cases, there is no Uri-Path Option in the request.
Note that this does not mean that a client cannot create a request with a single empty Uri-Path Option (which cannot be generated from a URI according to the algorithm given here), or that a server is compelled to treat a request with such a single empty Uri-Path Option the same way as one without any Uri-Path Option — the exception at the start of step 8 is only about generating CoAP Options from a URI.
Note also that there is a difference between requests generated from coap://authority/, coap://authority//, and coap://authority///, respectively: The first has no Uri-Path Options (due to the special exception), the second, two (empty ones), the third, three (empty ones).
Similarly, for coap://authority/foo a single Uri-Path Option with the value foo is generated, while for coap://authority/foo/ that Uri-Path Option is followed by an empty one.
PENDING: Enough examples now?
RFC7252-7.2.1: "ct" Attribute (content-format code)
As has been noted in [Err5078], there is no information in [RFC7252] 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 3.1 and 3.2 of [RFC6690] have.
This appears to be an oversight. Published examples in Section 4.1 of [RFC9148] and Section 4.3 of [RFC9176] 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 [Err5078] 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 9.1.1 and 9.1.2 of [RFC7252] 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 [RFC7641], 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 [RFC8323] and OSCORE [RFC8613] 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 Section 4.3 of [RFC9006]).
The match boxing semantics of the current protocol are clearly defined, but can be unsatisfactory given the current requirements. Therefore, enhancements may be called for:
1. Protocols such as OSCORE [RFC8613], as enhanced by the proposed KUDOS mechanism [I-D.ietf-core-oscore-key-update], need to define how the matching functions are impacted by state transitions of the underlying transport and security sessions. Where extensions are already actively being developed, this work should be done in the context of the extension effort.
  a. Protocol mechanisms that have been defined for stitching together connections or phases of an underlying connection, such as Connection Identifiers for DTLS 1.2 [RFC9146], may enable keeping the session/epoch unchanged and even to change the transport address (ip-address/port), once appropriately modified match boxing rules are specified for the stitching mechanism. (These rules either need to be defined to be implicitly active for any use of the mechanism or they may require negotiation, see below.)
2. Optimizations such as Eclipse/Californium EndpointContextMatcher [CF-MATCHER] 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-12.3: Content-Format Registry
Section 12.3 of [RFC7252] 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 [RFC9193] for an extensive discussion), i.e., it may contain parameters beyond the mere combination of a type-name and a subtype-name registered in [IANA.media-types], as per [RFC6838], 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 Section 8.3 of [RFC9110], 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 Section 8.4.1 of [RFC9110]. 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 [Err4954], the text in Section 12.3 of [RFC7252] 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 [Err4954] 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.
[Err4954] 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 Section 2.6.
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
[RFC6690]

Constrained RESTful Environments (CoRE) Link Format
Z. Shelby
August 2012
RFC 6690
DOI 10.17487/RFC6690
[RFC7252]

The Constrained Application Protocol (CoAP)
Z. Shelby
K. Hartke
C. Bormann
June 2014
RFC 7252
DOI 10.17487/RFC7252
[RFC7641]

Observing Resources in the Constrained Application Protocol (CoAP)
K. Hartke
September 2015
RFC 7641
DOI 10.17487/RFC7641
[RFC7959]

Block-Wise Transfers in the Constrained Application Protocol (CoAP)
C. Bormann
Z. Shelby, Ed.
August 2016
RFC 7959
DOI 10.17487/RFC7959
[RFC8132]

PATCH and FETCH Methods for the Constrained Application Protocol (CoAP)
P. van der Stok
C. Bormann
A. Sehgal
April 2017
RFC 8132
DOI 10.17487/RFC8132
[RFC8323]

CoAP (Constrained Application Protocol) over TCP, TLS, and WebSockets
C. Bormann
S. Lemay
H. Tschofenig
K. Hartke
B. Silverajan
B. Raymor, Ed.
February 2018
RFC 8323
DOI 10.17487/RFC8323
[RFC8613]

Object Security for Constrained RESTful Environments (OSCORE)
G. Selander
J. Mattsson
F. Palombini
L. Seitz
July 2019
RFC 8613
DOI 10.17487/RFC8613
[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels
S. Bradner
March 1997
BCP 14
RFC 2119
DOI 10.17487/RFC2119
[RFC8174]

Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
B. Leiba
May 2017
BCP 14
RFC 8174
DOI 10.17487/RFC8174
Informative References
[RFC8516]

"Too Many Requests" Response Code for the Constrained Application Protocol
A. Keranen
January 2019
RFC 8516
DOI 10.17487/RFC8516
[I-D.bormann-core-responses]

CoAP: Non-traditional response forms
Carsten Bormann
Universität Bremen TZI
Christian Amsüss
3 March 2024
Internet-Draft draft-bormann-core-responses-02
[RFC3986]

Uniform Resource Identifier (URI): Generic Syntax
T. Berners-Lee
R. Fielding
L. Masinter
January 2005
STD 66
RFC 3986
DOI 10.17487/RFC3986
[Err4895]

RFC Errata Report 4895
RFC 7252
[Err4954]

RFC Errata Report 4954
RFC 7252
[Err5078]

RFC Errata Report 5078
RFC 7252
[I-D.ietf-core-oscore-key-update]

Key Update for OSCORE (KUDOS)
Rikard Höglund
RISE AB
Marco Tiloca
RISE AB
4 March 2024
Internet-Draft draft-ietf-core-oscore-key-update-07
[CF-MATCHER]

EndpointContextMatcher.java
[RFC9146]

Connection Identifier for DTLS 1.2
E. Rescorla, Ed.
H. Tschofenig, Ed.
T. Fossati
A. Kraus
March 2022
RFC 9146
DOI 10.17487/RFC9146
[RFC9110]

HTTP Semantics
R. Fielding, Ed.
M. Nottingham, Ed.
J. Reschke, Ed.
June 2022
STD 97
RFC 9110
DOI 10.17487/RFC9110
[RFC7230]

Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing
R. Fielding, Ed.
J. Reschke, Ed.
June 2014
RFC 7230
DOI 10.17487/RFC7230
[RFC9148]

EST-coaps: Enrollment over Secure Transport with the Secure Constrained Application Protocol
P. van der Stok
P. Kampanakis
M. Richardson
S. Raza
April 2022
RFC 9148
DOI 10.17487/RFC9148
[RFC9176]

Constrained RESTful Environments (CoRE) Resource Directory
C. Amsüss, Ed.
Z. Shelby
M. Koster
C. Bormann
P. van der Stok
April 2022
RFC 9176
DOI 10.17487/RFC9176
[RFC9006]

TCP Usage Guidance in the Internet of Things (IoT)
C. Gomez
J. Crowcroft
M. Scharf
March 2021
RFC 9006
DOI 10.17487/RFC9006
[RFC9193]

Sensor Measurement Lists (SenML) Fields for Indicating Data Value Content-Format
A. Keränen
C. Bormann
June 2022
RFC 9193
DOI 10.17487/RFC9193
[IANA.media-types]

Media Types
IANA
[RFC6838]

Media Type Specifications and Registration Procedures
N. Freed
J. Klensin
T. Hansen
January 2013
BCP 13
RFC 6838
DOI 10.17487/RFC6838
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.