Script updating gh-pages from 97cc1f4. [ci skip]

draft-kleidl-digest-fields-problem-types.html

@@ -6,8 +6,9 @@
 <meta content="initial-scale=1.0" name="viewport">
 <title>HTTP Problem Types for Digest Fields</title>
 <meta content="Marius Kleidl" name="author">
+<meta content="Lucas Pardue" name="author">
 <meta content="
-       TODO Abstract 
+       This document specifies problem types that servers can use in responses to problems encountered while dealing with a request carrying integrity fields and integrity preference fields. 
     " name="description">
 <meta content="xml2rfc 3.22.0" name="generator">
 <meta content="next generation" name="keyword">
@@ -1029,7 +1030,7 @@
 <td class="right">July 2024</td>
 </tr></thead>
 <tfoot><tr>
-<td class="left">Kleidl</td>
+<td class="left">Kleidl &amp; Pardue</td>
 <td class="center">Expires 9 January 2025</td>
 <td class="right">[Page]</td>
 </tr></tfoot>
@@ -1049,19 +1050,23 @@
 <dd class="intended-status">Informational</dd>
 <dt class="label-expires">Expires:</dt>
 <dd class="expires"><time datetime="2025-01-09">9 January 2025</time></dd>
-<dt class="label-authors">Author:</dt>
+<dt class="label-authors">Authors:</dt>
 <dd class="authors">
 <div class="author">
       <div class="author-name">M. Kleidl</div>
 <div class="org">Transloadit</div>
 </div>
+<div class="author">
+      <div class="author-name">L. Pardue</div>
+<div class="org">Cloudflare</div>
+</div>
 </dd>
 </dl>
 </div>
 <h1 id="title">HTTP Problem Types for Digest Fields</h1>
 <section id="section-abstract">
       <h2 id="abstract"><a href="#abstract" class="selfRef">Abstract</a></h2>
-<p id="section-abstract-1">TODO Abstract<a href="#section-abstract-1" class="pilcrow">¶</a></p>
+<p id="section-abstract-1">This document specifies problem types that servers can use in responses to problems encountered while dealing with a request carrying integrity fields and integrity preference fields.<a href="#section-abstract-1" class="pilcrow">¶</a></p>
 </section>
 <section class="note rfcEditorRemove" id="section-note.1">
       <h2 id="name-about-this-document">
@@ -1155,7 +1160,7 @@ <h2 id="name-copyright-notice">
             <p id="section-toc.1-1.7.1"><a href="#appendix-A" class="auto internal xref"></a><a href="#name-acknowledgments" class="internal xref">Acknowledgments</a></p>
 </li>
           <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.8">
-            <p id="section-toc.1-1.8.1"><a href="#appendix-B" class="auto internal xref"></a><a href="#name-authors-address" class="internal xref">Author's Address</a></p>
+            <p id="section-toc.1-1.8.1"><a href="#appendix-B" class="auto internal xref"></a><a href="#name-authors-addresses" class="internal xref">Authors' Addresses</a></p>
 </li>
         </ul>
 </nav>
@@ -1166,24 +1171,21 @@ <h2 id="name-copyright-notice">
       <h2 id="name-introduction">
 <a href="#section-1" class="section-number selfRef">1. </a><a href="#name-introduction" class="section-name selfRef">Introduction</a>
       </h2>
-<p id="section-1-1">Digest fields <span>[<a href="#DIGEST" class="cite xref">DIGEST</a>]</span> are HTTP fields that support integrity digests. A request can include the <code>Content-Digest</code> and <code>Repr-Digest</code> header fields for verifying the integrity of the HTTP message content and the HTTP representation, respectively. In addition, a sender can include the <code>Want-Content-Digest</code> and <code>Want-Repr-Digest</code> header fields in a request to express interest in receiving integrity field in the response. <span>[<a href="#DIGEST" class="cite xref">DIGEST</a>]</span> by design does not define, require or recommend specific server behavior if errors regarding the integrity appear.<a href="#section-1-1" class="pilcrow">¶</a></p>
-<p id="section-1-2">For example, a request may include a digest algorithm in the <code>Content-Digest</code> and <code>Repr-Digest</code> 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.<a href="#section-1-2" class="pilcrow">¶</a></p>
-<p id="section-1-3">Problem types <span>[<a href="#PROBLEM" class="cite xref">PROBLEM</a>]</span> are machine-readable description of errors in HTTP response content <span>[<a href="#PROBLEM" class="cite xref">PROBLEM</a>]</span>. 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.<a href="#section-1-3" class="pilcrow">¶</a></p>
-<p id="section-1-4">As an example, if the resource receives a request with an integrity field utilizing an unsupported hashing algorithm <code>foo</code>, the response may use the following problem type:<a href="#section-1-4" class="pilcrow">¶</a></p>
-<div class="lang-http-message sourcecode" id="section-1-5">
+<p id="section-1-1"><span>[<a href="#DIGEST" class="cite xref">DIGEST</a>]</span> 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 <span>[<a href="#PROBLEM" class="cite xref">PROBLEM</a>]</span> 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.<a href="#section-1-1" class="pilcrow">¶</a></p>
+<p id="section-1-2">For example, a request message may include content alongside <code>Content-Digest</code> and <code>Repr-Digest</code> 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.<a href="#section-1-2" class="pilcrow">¶</a></p>
+<div class="lang-http-message sourcecode" id="section-1-3">
 <pre>
 HTTP/1.1 400 Bad Request
 Content-Type: application/problem+json
+Want-Content-Digest: sha-512=3, sha-256=10
 
 {
   "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"]
+  "title": "hashing algorithm is not supported",
+  "unsupported-algorithm": "foo"
 }
-</pre><a href="#section-1-5" class="pilcrow">¶</a>
+</pre><a href="#section-1-3" class="pilcrow">¶</a>
 </div>
-<p id="section-1-6">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.<a href="#section-1-6" class="pilcrow">¶</a></p>
 </section>
 </div>
 <div id="conventions-and-definitions">
@@ -1209,22 +1211,22 @@ <h3 id="name-unsupported-hashing-algorit">
 <a href="#section-3.1" class="section-number selfRef">3.1. </a><a href="#name-unsupported-hashing-algorit" class="section-name selfRef">Unsupported Hashing Algorithm</a>
         </h3>
 <p id="section-3.1-1">This section defines the "https://iana.org/assignments/http-problem-types#unsupported-hashing-algorithm" problem type <span>[<a href="#PROBLEM" class="cite xref">PROBLEM</a>]</span>. A server <span class="bcp14">MAY</span> 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.<a href="#section-3.1-1" class="pilcrow">¶</a></p>
-<p id="section-3.1-2">Two problem type extension members are defined: the <code>unsupported-algorithm</code> and <code>supported-algorithms</code> members. A response using this problem type <span class="bcp14">SHOULD</span> populate both members, with the value of <code>unsupported-algorithm</code> being the algorithm key of the unsupported algorithm from the request and the value of <code>supported-algorithms</code> being an array of the algorithm keys, as registered in the "Hash Algorithms for HTTP Digest Fields" registry, of the supported algorithms.<a href="#section-3.1-2" class="pilcrow">¶</a></p>
+<p id="section-3.1-2">For this problem type, the <code>unsupported-algorithm</code> is defined as the only extension member. It <span class="bcp14">SHOULD</span> be populated in a response using this problem type, with its value being the algorithm key of the unsupported algorithm from the request. The response <span class="bcp14">SHOULD</span> include the corresponding integrity preference field to indicate the server's algorithm support and preference.<a href="#section-3.1-2" class="pilcrow">¶</a></p>
 <p id="section-3.1-3">The following example shows a response for a request with an integrity field utilizing an unsupported hashing algorithm <code>foo</code>. The response also includes a list of supported algorithms.<a href="#section-3.1-3" class="pilcrow">¶</a></p>
 <div class="lang-http-message sourcecode" id="section-3.1-4">
 <pre>
 HTTP/1.1 400 Bad Request
 Content-Type: application/problem+json
+Want-Content-Digest: sha-512=3, sha-256=10
 
 {
   "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"]
+  "unsupported-algorithm": "foo"
 }
 </pre><a href="#section-3.1-4" class="pilcrow">¶</a>
 </div>
-<p id="section-3.1-5">If the sender receives this problem type, it <span class="bcp14">SHOULD</span> retry the request while picking another hashing algorithm. If the response includes an array of supported algorithms, it <span class="bcp14">SHOULD</span> choose one of them.<a href="#section-3.1-5" class="pilcrow">¶</a></p>
+<p id="section-3.1-5">This problem type is a hint to the client about algorithm support, which the client could use to retry the request with a different algorithm supported by the server.<a href="#section-3.1-5" class="pilcrow">¶</a></p>
 </section>
 </div>
 <div id="invalid-digest-value">
@@ -1246,7 +1248,7 @@ <h3 id="name-invalid-digest-value">
 }
 </pre><a href="#section-3.2-4" class="pilcrow">¶</a>
 </div>
-<p id="section-3.2-5">If the sender receives this problem type, it <span class="bcp14">SHOULD NOT</span> retry the request without modification. Such an error is likely rooted in a fault in the sender's calculation or encoding of the digest value.<a href="#section-3.2-5" class="pilcrow">¶</a></p>
+<p id="section-3.2-5">This problem type indicates a fault in the sender's calculation or encoding of the digest value. A retry of the same request without modification will likely not yield a successful response.<a href="#section-3.2-5" class="pilcrow">¶</a></p>
 </section>
 </div>
 <div id="mismatching-digest-value">
@@ -1271,7 +1273,7 @@ <h3 id="name-mismatching-digest-value">
 }
 </pre><a href="#section-3.3-4" class="pilcrow">¶</a>
 </div>
-<p id="section-3.3-5">If the sender receives this problem type, the request might be modified unintentionally by an intermediary. The sender <span class="bcp14">MAY</span> retry the request without modification. However, if the sender continue receiving this problem type, it <span class="bcp14">SHOULD</span> stop retrying.<a href="#section-3.3-5" class="pilcrow">¶</a></p>
+<p id="section-3.3-5">If the sender receives this problem type, the request might be modified unintentionally by an intermediary. The sender could use this information to retry the request without modification to address temporary transmission issues.<a href="#section-3.3-5" class="pilcrow">¶</a></p>
 </section>
 </div>
 </section>
@@ -1394,13 +1396,13 @@ <h2 id="name-normative-references">
       <h2 id="name-acknowledgments">
 <a href="#name-acknowledgments" class="section-name selfRef">Acknowledgments</a>
       </h2>
-<p id="appendix-A-1">TODO acknowledge.<a href="#appendix-A-1" class="pilcrow">¶</a></p>
+<p id="appendix-A-1">This document is based on ideas from a discussion with Roberto Polli, so thanks to him for his valuable input and feedback on this topic.<a href="#appendix-A-1" class="pilcrow">¶</a></p>
 </section>
 </div>
 <div id="authors-addresses">
 <section id="appendix-B">
-      <h2 id="name-authors-address">
-<a href="#name-authors-address" class="section-name selfRef">Author's Address</a>
+      <h2 id="name-authors-addresses">
+<a href="#name-authors-addresses" class="section-name selfRef">Authors' Addresses</a>
       </h2>
 <address class="vcard">
         <div dir="auto" class="left"><span class="fn nameRole">Marius Kleidl</span></div>
@@ -1410,6 +1412,14 @@ <h2 id="name-authors-address">
 <a href="mailto:[email protected]" class="email">[email protected]</a>
 </div>
 </address>
+<address class="vcard">
+        <div dir="auto" class="left"><span class="fn nameRole">Lucas Pardue</span></div>
+<div dir="auto" class="left"><span class="org">Cloudflare</span></div>
+<div class="email">
+<span>Email:</span>
+<a href="mailto:[email protected]" class="email">[email protected]</a>
+</div>
+</address>
 </section>
 </div>
 <script>const toc = document.getElementById("toc");