Internet DRAFT - draft-amsuess-core-pd-body-error-position
draft-amsuess-core-pd-body-error-position
CoRE C. Amsüss
Internet-Draft 18 February 2023
Intended status: Informational
Expires: 22 August 2023
Concise Problem Details: Body Error Position
draft-amsuess-core-pd-body-error-position-01
Abstract
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
This note is to be removed before publishing as an RFC.
Discussion of this document takes place on the Constrained RESTful
Environments Working Group mailing list (core@ietf.org), which is
archived at https://mailarchive.ietf.org/arch/browse/core/.
Source for this draft and an issue tracker can be found at
https://gitlab.com/chrysn/pd-body-error-position.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 22 August 2023.
Copyright Notice
Copyright (c) 2023 IETF Trust and the persons identified as the
document authors. All rights reserved.
Amsüss Expires 22 August 2023 [Page 1]
Internet-Draft Concise Problem Details: Body Error Posi February 2023
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 2
1.2. Document lifecycle . . . . . . . . . . . . . . . . . . . 2
2. Request Body Error Position . . . . . . . . . . . . . . . . . 3
3. Usage example . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Security Considerations . . . . . . . . . . . . . . . . . . . 4
5. IANA considerations . . . . . . . . . . . . . . . . . . . . . 4
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 5
7.1. Normative References . . . . . . . . . . . . . . . . . . 5
7.2. Informative References . . . . . . . . . . . . . . . . . 5
Appendix A. Change log . . . . . . . . . . . . . . . . . . . . . 6
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6
1. Introduction
Concise Problem Details for CoAP APIs [RFC9290] 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.
1.1. Terminology
The description of the problem detail uses the term "body" as defined
in [RFC7959].
1.2. 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.
Amsüss Expires 22 August 2023 [Page 2]
Internet-Draft Concise Problem Details: Body Error Posi February 2023
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
[I-D.bormann-cbor-notable-tags].
2. 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 ([STD94]) 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.
3. Usage example
The figures in this section illustrate a CoAP [RFC7252] message
exchange using CBOR [STD94] bodies, and a hypothetical CoAP tool's
output that utilizes this error detail.
Amsüss Expires 22 August 2023 [Page 3]
Internet-Draft Concise Problem Details: Body Error Posi February 2023
Req: FETCH coap://example.com/alpha/archive
Content-Format: 60 (application/cbor)
Payload:
A2071A000123A0182C192118
Payload (diagnostic notation):
{7: 74656, 44: 8472}
Res: 4.00 Bad Request
Content-Format: 257 (application/concise-problem-details+cbor)
Payload:
A22071556E6B6E6F776E207175657279206B6579381808
Payload (diagnostic notation):
{
/ title / -1: "Unknown query key",
/ request-body-error-position / -25: 8
}
Figure 1: Messages exchanged between client and server
$ coap post coap://example.com/alpha/archive cbor '{7: 74656, 44: 8472}'
Error: Bad Request: Unknown query key
{7: 74656, 44: 8472}
^^ The server indicated that the error occurred here.
Figure 2: Output of a hypothetical CoAP client that utilizes the
Request Body Error Position detail
4. 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.
5. 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
Amsüss Expires 22 August 2023 [Page 4]
Internet-Draft Concise Problem Details: Body Error Posi February 2023
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
6. Acknowledgements
Michael Richardson provided good input for the Securitiy
Considerations.
7. References
7.1. Normative References
[RFC9290] Fossati, T. and C. Bormann, "Concise Problem Details for
Constrained Application Protocol (CoAP) APIs", RFC 9290,
DOI 10.17487/RFC9290, October 2022,
<https://www.rfc-editor.org/rfc/rfc9290>.
[RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in
the Constrained Application Protocol (CoAP)", RFC 7959,
DOI 10.17487/RFC7959, August 2016,
<https://www.rfc-editor.org/rfc/rfc7959>.
7.2. Informative References
[STD94] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", STD 94, RFC 8949, December 2020.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014,
<https://www.rfc-editor.org/rfc/rfc7252>.
[I-D.bormann-cbor-notable-tags]
Bormann, C., "Notable CBOR Tags", Work in Progress,
Internet-Draft, draft-bormann-cbor-notable-tags-07, 11
July 2022, <https://datatracker.ietf.org/doc/html/draft-
bormann-cbor-notable-tags-07>.
Amsüss Expires 22 August 2023 [Page 5]
Internet-Draft Concise Problem Details: Body Error Posi February 2023
Appendix A. 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.
Author's Address
Christian Amsüss
Austria
Email: christian@amsuess.com
Amsüss Expires 22 August 2023 [Page 6]
