Digest Fields
draft-ietf-httpbis-digest-headers-13

I'm balloting NOOBJ largely on the basis that the document appears to be of high quality and would probably be clear and usable if only I had the necessary grounding in HTTP's more abstruse corners to make sense of it. (Thank you for the references and examples, those got me halfway there, perhaps. The other half is the part I'm taking on faith.)

I do have a few nits and questions --

## COMMENT

### Section 5, reserved token value

In your description of the Status template field, you have ""reserved" - for algorithms that use a reserved token value that cannot be expressed in Structured Fields". This is a well-formed sentence but I have no idea what it means. I made a desultory attempt to suss it out by searching the document for "token" and this was the only occurrence. If people who will actually be making use of the registry can be expected to make sense of it, then feel free to disregard my comment, of course.

### Section 5, "optionally the key"

A few lines further down you have "Reference(s): pointer(s) to the primary document(s) defining the technical details of the algorithm, and optionally the key". I couldn't work out what "the key" is in this context, that would be placed in the registry. The values you've seeded the registry with don't provide any examples, so I'm none the wiser for having checked there.

## NITS

### Section 6.5, e.g.

In "Since it is possible for there to be variation within content coding, the checksum conveyed by the integrity field cannot be used to provide a proof of integrity "at rest" unless the whole (e.g., encoded) content is persisted.", do you actually mean "i.e." and not "e.g."? 

### Appendix A, typo

/entires/1234 should be /entries/1234

Thank you to Peter Yee for the SECDIR review.

** Section 2.  Using multiple digests in a single Content-Digest is supported.  There is also guidance that “a recipient MAY ignore any or all of the digests”.  I read that text as “if presented multiple digests, a recipient can choose to look at only one or some subset of the digests.” Is that accurate?  Is there standardized behavior for when a recipient validates/checks both digests and only one is valid?

** Section 4.
   *  key conveys the hashing algorithm (see Section 5);

Shouldn’t this read as “hashing algorithm(s)” as it is possible to send more than one in the field?

** Section 4.  
   *  value is an Integer (Section 3.3.1 of [STRUCTURED-FIELDS]) that
      conveys an ascending, relative, weighted preference.  It must be
      in the range 0 to 10 inclusive. 1 is the least preferred, 10 is
      the most preferred, and a value of 0 means "not acceptable".

-- Can multiple algorithms share the same preference value?  For example, could multiple algorithms be labeled “not acceptable”?

-- If yes, would their ordering determine preference?

** Section 6.1.  Recommend adding cautionary language about the capabilities of an adversary like those stated in Peter’s SECDIR review.  Perhaps:

OLD
   Integrity fields are not intended to be a general protection against
   malicious tampering with HTTP messages. This can be achieved by
   combining it with other approaches such as transport-layer security
   or digital signatures (for example, HTTP Message Signatures
   [SIGNATURES]).


NEW
Integrity fields are not intended to be a general protection against malicious tampering with HTTP messages. In the absence of additional security mechanisms, an on-path, malicious actor can remove or recalculate and substitute a digest value.  This attack can be mitigated by combining mechanisms described in this document with other approaches such as transport-layer security or digital signatures (for example, HTTP Message Signatures [SIGNATURES]).

This is largely outside my area of expertise, but seems reasonble.

# GEN AD review of draft-ietf-httpbis-digest-headers-12

CC @larseggert

Thanks to Joel Halpern for the General Area Review Team (Gen-ART) review
(https://mailarchive.ietf.org/arch/msg/gen-art/hOSKIuNLtGQoGLri4c1auAF9kP4).

## Nits

All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

### Outdated references

Document references `draft-ietf-httpbis-message-signatures-16`, but `-17` is
the latest available revision.

### Grammar/style

#### Section 3.2, paragraph 1
```
fication. How to deal with an ignored preferences is a scenario that should b
                           ^^^^^^^^^^^^^^^^^^^^^^
```
The plural noun "preferences" cannot be used with the article "an". Did you
mean "an ignored preference" or "ignored preferences"?

#### Section 6.1, paragraph 2
```
es of Content-Type, Content-Encoding etc). A signature that protects Integri
                                     ^^^
```
A period is needed after the abbreviation "etc.".

#### "B.6.", paragraph 7
```
Repr-Digest is designed to be independent from the use of one or more transf
                              ^^^^^^^^^^^^^^^^
```
The usual collocation for "independent" is "of", not "from". Did you mean
"independent of"?

#### "B.11.", paragraph 6
```
e Digest field. This resulted in a mixed of formats such as base64, hex or d
                                   ^^^^^
```
The phrase "a mixed of" is not correct. Use a noun, not an adjective, between
"a" and "of".

#### "Appendix E.", paragraph 1
```
ncrypted content * Digest is independent from MESSAGING and HTTP/1.1 is not
                             ^^^^^^^^^^^^^^^^
```
The usual collocation for "independent" is "of", not "from". Did you mean
"independent of"?

## Notes

This review is in the ["IETF Comments" Markdown format][ICMF], You can use the
[`ietf-comments` tool][ICT] to automatically convert this review into
individual GitHub issues. Review generated by the [`ietf-reviewtool`][IRT].

[ICMF]: https://github.com/mnot/ietf-comments/blob/main/format.md
[ICT]: https://github.com/mnot/ietf-comments
[IRT]: https://github.com/larseggert/ietf-reviewtool

This HTTP tourist was quite confused by the Repr-Digest field. Section 3.2 of RFC9110 says that a representation "consists of a set of representation metadata and a potentially unbounded stream of representation data". So what exactly is the input to the hash function for Repr-Digest? I was expecting to see some of the metadata fields somehow incorporated in the input, but the appendices seem to indicate that the input is just the full, not-range-limited content, in whatever encoding the sender selects.

An unambiguous statement of the Hash algorithm input in each case would be helpful, though maybe it's just because my comfort with the term "representation" is just from having read the definition, rather than working with it.

Hi,

Thanks for the this document.

A couple of minor comments, that are you welcome to act on, or ignore, at your desire:

1. I'm not an HTTP expert, hence I somewhat struggled with what the definition of an HTTP representation is, although the examples B.1 - B.3 helped.  Perhaps consider a forward reference to the B.1 - B.3 in section 1 or section 1.2.

2. I noted that the "Code Samples" section is marked as being removed from the final RFC, but I wondered why, and whether it wouldn't benefit for being included as informative (non-normative text).

Regards,
Rob