Skip to content

Commit

Permalink
Script updating gh-pages from 377bfc7. [ci skip]
Browse files Browse the repository at this point in the history
  • Loading branch information
ID Bot committed Jun 27, 2024
1 parent 347aedd commit 6a70c85
Show file tree
Hide file tree
Showing 2 changed files with 47 additions and 56 deletions.
24 changes: 10 additions & 14 deletions draft-kleidl-digest-fields-problem-types.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1167,8 +1167,8 @@ <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="#RFC9530" class="cite xref">RFC9530</a>]</span> by design does not define, require or recommend specific resource 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 resource does not support. Similar, a sender may request to the digest utilizing a hashing algorithm that the resource does not support. Another possible problem is that the digest supplied in the request does not match up with the digest calculated by the resource. Depending on the application, the resource may choose to ignore these errors or communicate them back to the client. However, no recommended response format for communicating these error is defined so far.<a href="#section-1-2" class="pilcrow"></a></p>
<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">
Expand All @@ -1184,7 +1184,7 @@ <h2 id="name-introduction">
}
</pre><a href="#section-1-5" 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 resource, as well as an array of the supported algorithms.<a href="#section-1-6" class="pilcrow"></a></p>
<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">
Expand All @@ -1209,8 +1209,8 @@ <h2 id="name-problem-types">
<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 <code>https://iana.org/assignments/http-problem-types#unsupported-hashing-algorithm</code> problem type <span>[<a href="#PROBLEM" class="cite xref">PROBLEM</a>]</span>. A resource <span class="bcp14">MAY</span> use this problem type in a response to a request, whose integrity or integrity preference fields reference a hashing algorithm that the resource can not or does not want to support for this request, and if the resource wants to indicate this problem to the sender.<a href="#section-3.1-1" class="pilcrow"></a></p>
<p id="section-3.1-2">The resource <span class="bcp14">SHOULD</span> provide the algorithm key of the unsupported algorithm in the <code>unsupported-algorithm</code> member and an array of the supported algorithms in the <code>supported-algorithm</code> member. The value of this array are algorithm keys as registered in the "Hash Algorithms for HTTP Digest Fields" registry.<a href="#section-3.1-2" class="pilcrow"></a></p>
<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 in a response 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">The server <span class="bcp14">SHOULD</span> provide the algorithm key of the unsupported algorithm in the <code>unsupported-algorithm</code> member and an array of the supported algorithms in the <code>supported-algorithm</code> member. The value of this array are algorithm keys as registered in the "Hash Algorithms for HTTP Digest Fields" registry.<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>
Expand All @@ -1233,8 +1233,8 @@ <h3 id="name-unsupported-hashing-algorit">
<h3 id="name-invalid-digest-value">
<a href="#section-3.2" class="section-number selfRef">3.2. </a><a href="#name-invalid-digest-value" class="section-name selfRef">Invalid Digest Value</a>
</h3>
<p id="section-3.2-1">This section defines the <code>https://iana.org/assignments/http-problem-types#invalid-digest-value</code> problem type <span>[<a href="#PROBLEM" class="cite xref">PROBLEM</a>]</span>. A resource <span class="bcp14">MAY</span> use this problem type in a response 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 <code>sha-512</code> hashing algorithm is not 64 bytes long, it cannot be a valid digest value and the resource can skip computing the digest value. This problem type <span class="bcp14">MUST NOT</span> be used if the resource is not able to parse the integrity fields according to <span><a href="https://rfc-editor.org/rfc/rfc8941#section-4.5" class="relref">Section 4.5</a> of [<a href="#STRUCTURED-FIELDS" class="cite xref">STRUCTURED-FIELDS</a>]</span>, for example because of a syntax error in the field value.<a href="#section-3.2-1" class="pilcrow"></a></p>
<p id="section-3.2-2">The resource <span class="bcp14">SHOULD</span> a human-readable description why the value is considered invalid in the <code>title</code> member.<a href="#section-3.2-2" class="pilcrow"></a></p>
<p id="section-3.2-1">This section defines the "https://iana.org/assignments/http-problem-types#invalid-digest-value" problem type <span>[<a href="#PROBLEM" class="cite xref">PROBLEM</a>]</span>. A server <span class="bcp14">MAY</span> use this problem type in a response 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 <code>sha-512</code> 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 <span class="bcp14">MUST NOT</span> be used if the server is not able to parse the integrity fields according to <span><a href="https://rfc-editor.org/rfc/rfc8941#section-4.5" class="relref">Section 4.5</a> of [<a href="#STRUCTURED-FIELDS" class="cite xref">STRUCTURED-FIELDS</a>]</span>, for example because of a syntax error in the field value.<a href="#section-3.2-1" class="pilcrow"></a></p>
<p id="section-3.2-2">The server <span class="bcp14">SHOULD</span> include a human-readable description why the value is considered invalid in the <code>title</code> member.<a href="#section-3.2-2" class="pilcrow"></a></p>
<p id="section-3.2-3">The following example shows a response for a request with an invalid digest value.<a href="#section-3.2-3" class="pilcrow"></a></p>
<div class="lang-http-message sourcecode" id="section-3.2-4">
<pre>
Expand All @@ -1255,8 +1255,8 @@ <h3 id="name-invalid-digest-value">
<h3 id="name-mismatching-digest-value">
<a href="#section-3.3" class="section-number selfRef">3.3. </a><a href="#name-mismatching-digest-value" class="section-name selfRef">Mismatching Digest Value</a>
</h3>
<p id="section-3.3-1">This section defines the <code>https://iana.org/assignments/http-problem-types#mismatching-digest-value</code> problem type <span>[<a href="#PROBLEM" class="cite xref">PROBLEM</a>]</span>. A resource <span class="bcp14">MAY</span> use this problem type in a response to a request, whose integrity fields include a digest value that does not match the digest value that the resource computed for the request content or representation.<a href="#section-3.3-1" class="pilcrow"></a></p>
<p id="section-3.3-2">The resource <span class="bcp14">SHOULD</span> provide the algorithm key of the used hashing algorithm in the <code>algorithm</code> member, the digest value from the request's integrity fields in the <code>provided-digest</code> member, and the computed digest value in the <code>expected-digest</code> member. The digest values <span class="bcp14">MUST</span> BE serialized as byte sequences as described in <span><a href="https://rfc-editor.org/rfc/rfc8941#section-4.1.8" class="relref">Section 4.1.8</a> of [<a href="#STRUCTURED-FIELDS" class="cite xref">STRUCTURED-FIELDS</a>]</span>.<a href="#section-3.3-2" class="pilcrow"></a></p>
<p id="section-3.3-1">This section defines the "https://iana.org/assignments/http-problem-types#mismatching-digest-value" problem type <span>[<a href="#PROBLEM" class="cite xref">PROBLEM</a>]</span>. A server <span class="bcp14">MAY</span> use this problem type in a response 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.<a href="#section-3.3-1" class="pilcrow"></a></p>
<p id="section-3.3-2">The server <span class="bcp14">SHOULD</span> provide the algorithm key of the used hashing algorithm in the <code>algorithm</code> member, the digest value from the request's integrity fields in the <code>provided-digest</code> member, and the computed digest value in the <code>expected-digest</code> member. The digest values <span class="bcp14">MUST</span> BE serialized as byte sequences as described in <span><a href="https://rfc-editor.org/rfc/rfc8941#section-4.1.8" class="relref">Section 4.1.8</a> of [<a href="#STRUCTURED-FIELDS" class="cite xref">STRUCTURED-FIELDS</a>]</span>.<a href="#section-3.3-2" class="pilcrow"></a></p>
<p id="section-3.3-3">The following example shows a response for a request with a mismatching SHA-256 digest value.<a href="#section-3.3-3" class="pilcrow"></a></p>
<div class="lang-http-message sourcecode" id="section-3.3-4">
<pre>
Expand All @@ -1282,7 +1282,7 @@ <h3 id="name-mismatching-digest-value">
<h2 id="name-security-considerations">
<a href="#section-4" class="section-number selfRef">4. </a><a href="#name-security-considerations" class="section-name selfRef">Security Considerations</a>
</h2>
<p id="section-4-1">Although an error appeared while handling the digest fields, the resource may choose to not disclose this error to the sender to avoid lacking implementation details. Similar, the resource 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.<a href="#section-4-1" class="pilcrow"></a></p>
<p id="section-4-1">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.<a href="#section-4-1" class="pilcrow"></a></p>
</section>
</div>
<div id="iana-considerations">
Expand Down Expand Up @@ -1383,10 +1383,6 @@ <h2 id="name-normative-references">
<dd>
<span class="refAuthor">Leiba, B.</span>, <span class="refTitle">"Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words"</span>, <span class="seriesInfo">BCP 14</span>, <span class="seriesInfo">RFC 8174</span>, <span class="seriesInfo">DOI 10.17487/RFC8174</span>, <time datetime="2017-05" class="refDate">May 2017</time>, <span>&lt;<a href="https://www.rfc-editor.org/rfc/rfc8174">https://www.rfc-editor.org/rfc/rfc8174</a>&gt;</span>. </dd>
<dd class="break"></dd>
<dt id="RFC9530">[RFC9530]</dt>
<dd>
<span class="refAuthor">Polli, R.</span> and <span class="refAuthor">L. Pardue</span>, <span class="refTitle">"Digest Fields"</span>, <span class="seriesInfo">RFC 9530</span>, <span class="seriesInfo">DOI 10.17487/RFC9530</span>, <time datetime="2024-02" class="refDate">February 2024</time>, <span>&lt;<a href="https://www.rfc-editor.org/rfc/rfc9530">https://www.rfc-editor.org/rfc/rfc9530</a>&gt;</span>. </dd>
<dd class="break"></dd>
<dt id="STRUCTURED-FIELDS">[STRUCTURED-FIELDS]</dt>
<dd>
<span class="refAuthor">Nottingham, M.</span> and <span class="refAuthor">P. Kamp</span>, <span class="refTitle">"Structured Field Values for HTTP"</span>, <span class="seriesInfo">RFC 8941</span>, <span class="seriesInfo">DOI 10.17487/RFC8941</span>, <time datetime="2021-02" class="refDate">February 2021</time>, <span>&lt;<a href="https://www.rfc-editor.org/rfc/rfc8941">https://www.rfc-editor.org/rfc/rfc8941</a>&gt;</span>. </dd>
Expand Down
Loading

0 comments on commit 6a70c85

Please sign in to comment.