diff --git a/draft-kleidl-digest-fields-problem-types.md b/draft-kleidl-digest-fields-problem-types.md index c3f33e1..7ebd4c8 100644 --- a/draft-kleidl-digest-fields-problem-types.md +++ b/draft-kleidl-digest-fields-problem-types.md @@ -50,7 +50,7 @@ This document specifies problem types that servers can use in responses to probl {{DIGEST}} by design does not define, require or recommend any specific behavior for error handling relating to integrity. The responsibility is instead delegated to applications. This draft defines a set of problem types {{PROBLEM}} that can be used by server applications to indicate that a problem was encountered while dealing with a request carrying integrity fields and integrity preference fields. -For example, a request message may include content alongside `Content-Digest` and `Repr-Digest` header fields that use a digest algorithm the server does not support. An application could decide to reject this request because it cannot validate the integrity. Using a problem type, the server can provide machine-readable error details to aid debugging or error reporting, as shown in the following example. +For example, a request message may include content alongside `Content-Digest` and `Repr-Digest` fields that use a digest algorithm the server does not support. An application could decide to reject this request because it cannot validate the integrity. Using a problem type, the server can provide machine-readable error details to aid debugging or error reporting, as shown in the following example. ~~~ http-message HTTP/1.1 400 Bad Request @@ -68,13 +68,17 @@ Want-Content-Digest: sha-512=3, sha-256=10 {::boilerplate bcp14-tagged} -The terms "integrity fields" and "integrity preference fields" are from {{DIGEST}}. +The terms "integrity fields" and "integrity preference fields" in this document are to be +interpreted as described in {{DIGEST}}. + +The term "problem type" in this document is to be +interpreted as described in {{PROBLEM}}. # Problem Types ## Unsupported Hashing Algorithm -This section defines the "https://iana.org/assignments/http-problem-types#unsupported-hashing-algorithm" problem type {{PROBLEM}}. +This section defines the "https://iana.org/assignments/http-problem-types#unsupported-hashing-algorithm" problem type. A server MAY use this problem type if it wants to communicate to the client that none of the hashing algorithms referenced in the integrity or integrity preference fields present in the request, is supported. @@ -142,7 +146,7 @@ Want-Repr-Digest: sha-512=10, sha-256=3 ## 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. +This section defines the "https://iana.org/assignments/http-problem-types#invalid-digest-value" problem type. 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. @@ -163,7 +167,7 @@ This problem type indicates a fault in the sender's calculation or encoding of t ## 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 calculated for the request content or representation. +This section defines the "https://iana.org/assignments/http-problem-types#mismatching-digest-value" problem type. 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 calculated for the request content or representation. Three problem type extension members are defined: the `algorithm`, `provided-digest`, and `calculated-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 `calculated-digest` being the calculated digest. The digest values MUST BE serialized as byte sequences as described in {{Section 4.1.8 of STRUCTURED-FIELDS}}.