]>

Austria christian@amsuess.com

CoRE This defines a single standard problem detail for use with the Concise Problem Details format: Request Body Error Position. Using this detail, the server can point at the position inside the client's request body that induced the error. Discussion Venues Discussion of this document takes place on the Constrained RESTful Environments Working Group mailing list (core@ietf.org), which is archived at . Source for this draft and an issue tracker can be found at .

Introduction Concise Problem Details for CoAP APIs describes how a server can provide details about an error processing a client request, and how to extend these error messages. This document uses that extension mechanism and adds the Request Body Error Position detail.

Terminology The description of the problem detail uses the term "body" as defined in .

Document lifecycle Registering a standard problem detail merely requires a specification, not an RFC (let alone of a particular track), and has been performed based on version -00 of this document. Publication as an RFC has not been pursued in -00, nor is it at the time of writing. It will expire as an Inetnet Draft, but nonetheless be usable as the permanent reference for the IANA registration. Should a need for further development or a more official publication arise, the document may be picked up again at a later time. For example, that might be done in the style of .

Request Body Error Position The Request Body Error Position problem detail indicates that the error described by the Concise Problem Details response resulted from processing the request body. The numeric value indicates a byte position inside that body that corresponds to the error. The precise error position for invalid data may vary by implementation -- for example, if a numeric value inside a CBOR () item exceeds the expected range, it may indicate the number's initial byte (typically if the implementation doesn't even implement the indicated argument size) or the argument (if it implements it). When the request's content format indicated a non-identity content coding, the offset points into the uncompressed body. Consequently, this error detail is not suitable for pointing out errors that occur during uncompressing. The main envisioned use of this option is for the client to highlight or back-annotate (eg. to counteract minification, or to display it on some diagnostic notation) the erroneous item in the request body for a human author.

Usage example The figures in this section illustrate a CoAP message exchange using CBOR bodies, and a hypothetical CoAP tool's output that utilizes this error detail.

Messages exchanged between client and server

Output of a hypothetical CoAP client that utilizes the Request Body Error Position detail

Security Considerations Producing a Request Body Error Position detail gives the client some information about the internal workings of the server. If application designers intend to minimize the amount of information obtainable about the server, they need to weigh that goal against usability, and may prefer not to expose this (or any other) detail. The Request Body Error Position detail can be used by malicious clients to explore the borders of acceptable content. This can be mitigated by limiting this (or other) details to suitably authorized users, or, where possible, only parsing data from trusted sources in the first place.

IANA considerations A new entry has been assigned in the "Standard Problem Detail Keys" subregistry of the "Constrained RESTful Environments (CoRE) Parameters" registry.

Key value:

The value -25 is suggested

Name:

request-body-error-position

CDDL type:

uint

Brief description:

Byte index inside the request body at which the error became apparent

Reference:

This document

Change controller:

IETF CoRE working group

Acknowledgements Michael Richardson provided good input for the Securitiy Considerations.

References Normative References 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. 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. Informative References The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. 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. Universität Bremen TZI The Concise Binary Object Representation (CBOR, RFC 8949) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. In CBOR, one point of extensibility is the definition of CBOR tags. RFC 8949's original edition, RFC 7049, defined a basic set of tags as well as a registry that can be used to contribute additional tag definitions [IANA.cbor-tags]. Since RFC 7049 was published, some 80 tag definitions have been added to that registry. The present document provides a roadmap to a large subset of these tag definitions. Where applicable, it points to a IETF standards or standard development document that specifies the tag. Where no such document exists, the intention is to collect specification information from the sources of the registrations. After some more development, the present document is intended to be useful as a reference document for the IANA registrations of the CBOR tags the definitions of which have been collected.

Change log Since -00:

• Update IANA section to reflect registration having been performed.
• Update document lifecycle accordingly, mention possibility of a notable-problem-details document.
• Added security considerations.