Internet-Draft HTTP Problem Types for Digest Fields June 2024
Kleidl Expires 29 December 2024 [Page]
Workgroup:
Network Working Group
Internet-Draft:
draft-kleidl-digest-fields-problem-types-latest
Published:
Intended Status:
Informational
Expires:
Author:
M. Kleidl
Transloadit

HTTP Problem Types for Digest Fields

Abstract

TODO Abstract

About This Document

This note is to be removed before publishing as an RFC.

The latest revision of this draft can be found at https://tus.github.io/draft-digest-fields-problem-types/draft-kleidl-digest-fields-problem-types.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-kleidl-digest-fields-problem-types/.

Source for this draft and an issue tracker can be found at https://github.com/tus/draft-digest-fields-problem-types.

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 29 December 2024.

▲

Table of Contents

1. Introduction

Digest fields [DIGEST] are HTTP fields that support integrity digests. A request can include the Content-Digest and Repr-Digest header fields for verifying the integrity of the HTTP message content and the HTTP representation, respectively. In addition, a sender can include the Want-Content-Digest and Want-Repr-Digest header fields in a request to express interest in receiving integrity field in the response. [DIGEST] by design does not define, require or recommend specific server behavior if errors regarding the integrity appear.

For example, a request may include a digest algorithm in the Content-Digest and Repr-Digest header fields that the server does not support. Similar, a sender may request to the digest utilizing a hashing algorithm that the server does not support. Another possible problem is that the digest supplied in the request does not match up with the digest calculated by the server. Depending on the application, the server may choose to ignore these errors or communicate them back to the client. However, no recommended response format for communicating these errors is defined so far.

Problem types [PROBLEM] are machine-readable description of errors in HTTP response content [PROBLEM]. Each problem definition includes a unique type that can be used to identify the error and also allows the attachment of a short, human-readable summary as well as additional properties to aid debugging and error handling. In addition, a JSON and XML representation of the problem types is defined to simplify parsing.

As an example, if the resource receives a request with an integrity field utilizing an unsupported hashing algorithm foo, the response may use the following problem type:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://iana.org/assignments/http-problem-types#unsupported-hashing-algorithm",
  "title": "upload is already completed",
  "requested-algorithm": "foo",
  "supported-algorithms": ["sha-256", "sha-512"]
}

The response includes the unique problem type, the requested algorithm that is not supported by the server, as well as an array of the supported algorithms.

2. Conventions and Definitions

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.

The terms "integrity fields" and "integrity preference fields" are from [DIGEST].

3. Problem Types

3.1. Unsupported Hashing Algorithm

This section defines the "https://iana.org/assignments/http-problem-types#unsupported-hashing-algorithm" problem type [PROBLEM]. A server MAY use this problem type when responding to a request, whose integrity or integrity preference fields reference a hashing algorithm that the server can not or does not want to support for this request, and if the server wants to indicate this problem to the sender.

Two problem type extension members are defined: the unsupported-algorithm and supported-algorithms members. A response using this problem type SHOULD populate both members, with the value of unsupported-algorithm being the algorithm key of the unsupported algorithm from the request and the value of supported-algorithms being an array of the algorithm keys, as registered in the "Hash Algorithms for HTTP Digest Fields" registry, of the supported algorithms.

The following example shows a response for a request with an integrity field utilizing an unsupported hashing algorithm foo. The response also includes a list of supported algorithms.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://iana.org/assignments/http-problem-types#unsupported-hashing-algorithm",
  "title": "hashing algorithm is not supported",
  "unsupported-algorithm": "foo",
  "supported-algorithms": ["sha-256", "sha-512"]
}

If the sender receives this problem type, it SHOULD retry the request while picking another hashing algorithm. If the response includes an array of supported algorithms, it SHOULD choose one of them.

3.2. Invalid Digest Value

This section defines the "https://iana.org/assignments/http-problem-types#invalid-digest-value" problem type [PROBLEM]. A server MAY use this problem type when responding to a request, whose integrity fields include a digest value, that cannot be generated by the corresponding hashing algorithm. For example, if the digest value of the sha-512 hashing algorithm is not 64 bytes long, it cannot be a valid digest value and the server can skip computing the digest value. This problem type MUST NOT be used if the server is not able to parse the integrity fields according to Section 4.5 of [STRUCTURED-FIELDS], for example because of a syntax error in the field value.

The server SHOULD include a human-readable description why the value is considered invalid in the title member.

The following example shows a response for a request with an invalid digest value.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://iana.org/assignments/http-problem-types#invalid-digest-value",
  "title": "digest value for sha-512 is not 64 bytes long"
}

If the sender receives this problem type, it SHOULD NOT retry the request without modification. Such an error is likely rooted in a fault in the sender's computation or encoding of the digest value.

3.3. Mismatching Digest Value

This section defines the "https://iana.org/assignments/http-problem-types#mismatching-digest-value" problem type [PROBLEM]. A server MAY use this problem type when responding to a request, whose integrity fields include a digest value that does not match the digest value that the server computed for the request content or representation.

Three problem type extension members are defined: the algorithm, provided-digest, and expected-digest members. A response using this problem type SHOULD populate all members, with the value of algorithm being the algorithm key of the used hashing algorithm, with the value of provided-digest being the digest value taken from the request's integrity fields, and the value of expected-digest being the computed digest. The digest values MUST BE serialized as byte sequences as described in Section 4.1.8 of [STRUCTURED-FIELDS].

The following example shows a response for a request with a mismatching SHA-256 digest value.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://iana.org/assignments/http-problem-types#mismatching-digest-value",
  "title": "digest value fromr request does not match expected value",
  "algorithm": "sha-256",
  "provided-digest": ":RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:",
  "expected-digest": ":d435Qo+nKZ+gLcUHn7GQtQ72hiBVAgqoLsZnZPiTGPk=:"
}

If the sender receives this problem type, the request might be modified unintentionally by an intermediary. The sender MAY retry the request without modification. However, if the sender continue receiving this problem type, it SHOULD stop retrying.

4. Security Considerations

Although an error appeared while handling the digest fields, the server may choose to not disclose this error to the sender to avoid lacking implementation details. Similar, the server may choose a general problem type for the response even in a more specific problem type is defined if it prefers to hide the details of the error from the sender.

5. IANA Considerations

IANA is asked to register the following entry in the "HTTP Problem Types" registry:

Type URI:

https://iana.org/assignments/http-problem-types#unsupported-hashing-algorithm

Title:

Unsupported Hashing Algorithm

Recommended HTTP status code:

400

Reference:

This document

IANA is asked to register the following entry in the "HTTP Problem Types" registry:

Type URI:

https://iana.org/assignments/http-problem-types#invalid-digest-value

Title:

Invalid Digest Value

Recommended HTTP status code:

400

Reference:

This document

IANA is asked to register the following entry in the "HTTP Problem Types" registry:

Type URI:

https://iana.org/assignments/http-problem-types#mismatching-digest-value

Title:

Mismatching Digest Value

Recommended HTTP status code:

400

Reference:

This document

6. Normative References

[DIGEST]
Polli, R. and L. Pardue, "Digest Fields", RFC 9530, DOI 10.17487/RFC9530, , <https://www.rfc-editor.org/rfc/rfc9530>.
[PROBLEM]
Nottingham, M., Wilde, E., and S. Dalal, "Problem Details for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, , <https://www.rfc-editor.org/rfc/rfc9457>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
[STRUCTURED-FIELDS]
Nottingham, M. and P. Kamp, "Structured Field Values for HTTP", RFC 8941, DOI 10.17487/RFC8941, , <https://www.rfc-editor.org/rfc/rfc8941>.

Acknowledgments

TODO acknowledge.

Author's Address

Marius Kleidl
Transloadit