Sprints: Add `Digest` header

[ioggstream]

Request type

• [x] New documentation

Details

1- go to https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Digest

I expect

Digest documentation (see https://tools.ietf.org/html/rfc3230)

Instead

Nothing :)

Notes

I'm willing to contribute.

[ioggstream]

<div>{{HTTPSidebar}}</div>

<p>The <strong><code>Digest</code></strong> HTTP&nbsp;header conveys the&nbsp;checksum of an "instance", that is - in RFC7231 terms -&nbsp;the selected representation&nbsp;of a resource.</p>

<p>A selected representation depends on Content-Type and Content-Encoding header values.&nbsp;Therefore, a given resource may have multiple different digest values.</p>

<p>&nbsp;</p>

<p>Not every HTTP message conveys a representation, and representation data might be:</p>

<ul>
 <li>fully contained in the message body,</li>
 <li>partially-contained in the message body (eg. Range Requests),</li>
 <li>or not at all contained in the message body (eg. HEAD requests).</li>
</ul>

<p>The <strong><code>Digest</code></strong>&nbsp;header value contains the checksum of a complete resource representation, that is for Range Requests the checksum is calculated on the full resource.&nbsp;</p>

<p>&nbsp;</p>

<p>&nbsp;</p>

<table class="properties">
 <tbody>
  <tr>
   <th scope="row">Header type</th>
   <td>{{Glossary("Response header")}}</td>
  </tr>
  <tr>
   <th scope="row">{{Glossary("Forbidden header name")}}</th>
   <td>no</td>
  </tr>
 </tbody>
</table>

<h2 id="Syntax">Syntax</h2>

<pre class="syntaxbox">
Digest:  #(instance-digest)

// multiple digest values
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
</pre>

<h2 id="Directives">Directives</h2>

<dl>
 <dt>&lt;instance-digest&gt; := &lt;digest-algorithm&gt;=&lt;digest-value&gt;</dt>
 <dd>&nbsp;</dd>
 <dt>&lt;digest-algorithm&gt;</dt>
 <dd>Supported digest algorithms are defined in RFC3230 and RFC5843, and includes <code>SHA-256</code> and <code>SHA-512</code>. Other algorithms like <code>MD5</code> and <code>unixsum</code> are subject to collisions, so should be used with care.</dd>
 <dt>&lt;digest-value&gt;</dt>
 <dd>The digest-value is&nbsp;calculated applying the digest-algorithm to the representation and encoding the result (eg. base64 for <code>SHA-256</code>).</dd>
</dl>

<h2 id="Examples">Examples</h2>

<pre class="syntaxbox">
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=,unixsum=30637
</pre>

<h3 id="Avoiding_mid-air_collisions">&nbsp;</h3>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Title</th>
  </tr>
  <tr>
   <td>{{RFC("3230", "Instance Digest", "4.3.2")}}</td>
   <td>Instance Digest</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p>

<p>{{Compat("http.headers.Digest")}}</p>

<h2 id="See_also">See also</h2>

<ul>
 <li>{{HTTPStatus("206")}}<code> Partial Content</code></li>
</ul>

[ioggstream]

Hi @jmswisher! Here's a new page for the wiki, feedback welcome :)

[chrisdavidmills]

Thanks! We'll get to this soon, now it's been triaged.

[ioggstream]

Ok, let me know if you need anything.

[wbamberg]

Thanks for filing, and writing some content. And sorry to take so long to get to this.

I see you are one of the authors of https://httpwg.org/http-extensions/draft-ietf-httpbis-digest-headers.html and as such you're certainly more qualified than me to write this page :).

I took your draft and put it at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Digest. I did make a few changes though, most notably:

• changed the "Syntax" and "Directives" syntax to be more in line with how it seems to be done elsewhere (e.g. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept#Syntax)

• changed the specification to link to your draft instead of the RFC. I'm not sure this is a good idea, but the draft was more useful (to me) than the RFC.

Anyway, please let me know if you have any comments.

I guess we will also need a page for Want-Digest?

[ioggstream]

Thank you very much!

1- I'll check the Syntax/Directives;

2- I will edit https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Digest to explain that
while the RFC 3230 is the official source, the new draft clarifies its contents without modifying
the semantics (that is, the draft is backward compatible).

3- we need Want-Digest too :)

Thanks++,
R.

PS: I'm really happy the draft was helpful! That's the actual goal!

[wbamberg]

Thanks for your updates to the page :).

I've written a page for Want-Digest, with examples stolen from your draft: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Want-Digest

Please let me know what you think.

Also, do you have any idea what browser support is like for these, or know any resources for testing this? I tried adding Want-Digest using the browser devtools, but didn't get a Digest back, but don't know if that's because the server is not configured to support it.

Thanks @ioggstream !

[ioggstream]

The Want-Digest page seems ok, thanks for your support!

Digest are usually generated by applications and/or gateways, so you need a server
generating that. Moreover they may be returned even without want-digest.

For browser support, I can't help. Digest is mainly used in APIs, but we can check with firefox/chromium communities.

[wbamberg]

Following some discussion, I updated browser compat for these headers and it is now deployed, so the pages are complete:

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Digest
https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Want-Digest