Digest Fields

• 新的请求与响应头字段及尾部字段定义。

  • 第 2 节 (Content-Digest),
  • 第 3 节 (Repr-Digest), 和
  • 第 4 节 (Want-Content-Digest 与 Want-Repr-Digest）。

• 与表示数据完整性相关的特定考虑。

  • 第 3.1 节 （有状态变更请求），
  • 第 3.2 节（Content-Location），
  • 附录 A 包含了消息交换中关于表示数据的示例，以及
  • 附录 B 与 C 包含了 Repr-Digest 与 Want-Repr-Digest 在消息交换中的示例。
• 第 5 节 提出哈希算法的考虑并定义未来条目的注册流程。

本文档定义的 HTTP 字段可用于实现 HTTP 完整性。发送方选择哈希算法并基于与 HTTP 消息相关的输入计算摘要。算法标识符与摘要在 HTTP 字段中传输。接收方可以验证摘要以实现完整性检查。哈希算法在 “Hash Algorithms for HTTP Digest Fields” 注册表中注册（参见 第 7.2 节）。

选择用于计算摘要的数据取决于 HTTP 消息的用例。本文档为 HTTP 表示数据与 HTTP 内容提供了不同的字段。

在某些用例中，仅需对 HTTP 内容字节做简单摘要。Content-Digest 请求与响应头以及尾部字段被定义用于支持对内容的摘要（参见 [HTTP] 第 6.4 节）；详见 第 2 节。

对于更高级的用例，定义了 Repr-Digest 请求与响应头以及尾部字段（参见 第 3 节）。它包含通过对选定的表示数据应用哈希算法计算得到的摘要值（参见 [HTTP] 第 8.1 节）。基于选定表示的 Repr-Digest 便于将其应用到需要对消息内容进行某种处理后才视作资源表示，或内容表示资源的部分表示（例如范围请求，参见 [HTTP] 第 14 节）的用例。

Content-Digest 与 Repr-Digest 支持哈希算法的可替换性。Want-Content-Digest 与 Want-Repr-Digest 字段允许端点分别表达对接收 Content-Digest 与 Repr-Digest 的兴趣，并可在其中表达算法偏好。

Content-Digest 与 Repr-Digest 合称为“完整性字段”。Want-Content-Digest 与 Want-Repr-Digest 合称为“完整性偏好字段”。

完整性字段与 Content-Encoding 和 Content-Type 头字段相关联。因此，当通过 HTTP 传输时，同一资源可能具有多个不同的摘要值。

完整性字段适用于 HTTP 消息的内容或 HTTP 表示；它们不适用于 HTTP 消息或消息字段本身。然而，它们可以与保护元数据的其它机制（例如数字签名）结合使用，从而对 HTTP 交换的阶段性或整体提供保护。例如，可以使用 HTTP Message Signatures [SIGNATURES] 对完整性字段进行签名，从而为 HTTP 内容或表示数据提供覆盖保护。

本规范不定义身份验证、授权或隐私的手段。

[RFC3230] 定义了用于 HTTP 完整性的 Digest 与 Want-Digest 字段，并引入了“instance”（实例）与“instance manipulation”（实例处理）等术语以解释诸如选定表示数据（参见 [HTTP] 第 8.1 节）之类的概念，这些概念现在已作为 HTTP 语义更通用地定义并实现。

实践表明，对 [RFC3230] 的实现对“instance”含义的解释不一致，导致互操作性问题。最常见的问题是错误地使用（即现在称为）消息内容来计算摘要，而不是使用（即现在称为）表示数据，尽管后者为最初的意图。有趣的是，时间也表明对消息内容的摘要在某些用例中是有益的，因此难以判断对 [RFC3230] 的不一致实现是出于有意还是无意。

为了解决 Digest 与 Want-Digest 的实现间潜在不一致与歧义，本文档废弃了 [RFC3230]。本文档中定义的完整性字段（第 2 节 与第 3 节）以及完整性偏好字段（第 4 节）更好地与当前 HTTP 语义对齐，且其名称更清晰地表达了预期用法。

文中关键字 "MUST"、"MUST NOT"、"REQUIRED"、"SHALL"、"SHALL NOT"、"SHOULD"、"SHOULD NOT"、"RECOMMENDED"、"NOT RECOMMENDED"、"MAY" 和 "OPTIONAL" 的解释，见 BCP 14（参见 [RFC2119] 与 [RFC8174]），仅当这些词以全部大写形式出现时按该定义解释。

本文档使用在 [RFC5234] 中定义并经 [RFC7405] 更新的增强 BNF（ABNF）。这包括规则 CR（回车）、LF（换行）与 CRLF（回车换行）。

本文档使用 [STRUCTURED-FIELDS] 第 3 节 中的术语来指定语法与解析：Boolean、Byte Sequence、Dictionary、Integer 和 List。

文中对术语 “representation”、“selected representation”、“representation data”、“representation metadata”、“user agent” 与 “content” 的定义，应按 [HTTP] 的描述理解。

本文档使用 [FOLDING] 中描述的行折叠策略。

哈希算法名称应尊重其定义文档中使用的大小写（例如 SHA-1、CRC32c）。

HTTP 消息使用 Algorithm Key（算法键）来指示哈希算法。文中若以散文提及 Algorithm Key，则使用引号（例如 "sha", "crc32c"）。

术语 “checksum” 描述将算法应用于字节序列所产生的输出，而 “digest” 仅用于字段中包含的值。

“完整性字段” 为 Content-Digest 和 Repr-Digest 的集合称谓。

“完整性偏好字段” 为 Want-Repr-Digest 与 Want-Content-Digest 的集合称谓。

当封装在有状态变更请求中的表示并不描述目标资源时，表示摘要 MUST 在表示数据上计算。这是唯一可行的选择，因为表示摘要要求完整的表示元数据（参见 第 3 节）。

在响应中，

• 如果该表示描述了请求的状态，Repr-Digest MUST 在所封装的表示上计算（见 附录 B.8）；
• 如果存在被引用的资源，Repr-Digest MUST 在被引用资源的选定表示上计算，即便该表示与目标资源不同。此情况可能导致对封装表示或不对封装表示计算 Repr-Digest。

后一种情况应根据给定方法的 HTTP 语义执行，例如使用 Content-Location 头字段（参见 [HTTP] 第 8.7 节）。相反，Location 头字段不影响 Repr-Digest，因为它并非表示元数据。

例如，在 PATCH 请求中，表示摘要将对补丁文档计算，因为表示元数据指向的是补丁文档而非目标资源（参见 [PATCH] 第 2 节）。而在响应中，表示摘要将对被修补资源的选定表示计算。

当有状态变更方法返回 Content-Location 头字段时，所封装的表示指代由该字段值标识的资源，并应据此计算 Repr-Digest。示例见 附录 B.7。

本文档指定的数据完整性机制保护 HTTP 表示数据或内容，但并不保护 HTTP 头字段与尾部字段，因而不能防止某些类型的损坏。

完整性字段并非旨在对 HTTP 消息的恶意篡改提供通用保护。在缺乏额外安全机制的情况下，中间路径上的恶意行为者可以移除摘要值或用对操纵后的表示数据或内容重新计算的摘要值替换之。可以通过将本文档描述的机制与其它方法结合（例如传输层安全 TLS 或数字签名，如 HTTP Message Signatures [SIGNATURES]）来缓解此类攻击。

完整性字段有助于检测由于实现错误、非预期的“转换代理”（参见 [HTTP] 第 7.7 节）或数据跨越多个跃点或系统边界时的其它操作而导致的表示数据或内容修改。即使只是一个简单的端到端表示数据完整性机制也很有价值，因为用户代理可以在将数据交给 HTML 解析器、视频播放器等之前验证资源检索是否成功。

注意，仅使用这些机制并不能在多跃点场景下提供 HTTP 消息的端到端完整性，因为元数据在任何阶段都可能被篡改。保护元数据的方法见 第 6.3 节。

数字签名通常与校验和值一起使用，以确定消息来源的某些标识（参见 [FIPS186-5]）。此类签名可以保护一个或多个 HTTP 字段，但当完整性字段被包含在保护范围内时，需要考虑额外事项。

完整性字段的使用对数字签名的类型或格式没有限制。一种可行的方法是将其与 HTTP Message Signatures [SIGNATURES] 结合使用。

摘要明确依赖于“表示元数据”（例如 Content-Type、Content-Encoding 等字段的值）。如果签名保护了完整性字段但未保护其它“表示元数据”，则会使通信暴露于篡改风险。例如，行为者可以操纵 Content-Type 字段值，导致接收方的摘要校验失败，从而阻止应用访问该表示。此类攻击会消耗双方的资源。另见 第 3.2 节。

在应用完整性字段时，签名很可能被视为一种对抗性场景；参见 第 5 节。Repr-Digest 在与签名结合时提供了有趣的可能性。例如，当没有内容要发送时，可以在消息中包含对空字符串的摘要；如果对该摘要进行签名，接收方可以检测到意外或恶意地添加了内容。反过来，包含并签署用于内容的完整性字段也可以帮助接收方检测内容被移除的位置。

对完整性字段的任何篡改都可能影响签名验证。此类篡改的例子包括对摘要去重或合并不同字段值（参见 [HTTP] 第 5.2 节）。

在将完整性字段放入尾部（trailer）节之前，发送方应考虑中间体明确被允许丢弃任何尾部（参见 [HTTP] 第 6.5.2 节）。

当完整性字段位于尾部节时，这些字段的值在内容之后才到达。若在收到尾部节之前急于处理内容，则会阻止摘要验证，从而可能导致处理无效数据。

在尾部节中使用完整性字段的好处之一是允许在发送过程中对字节进行哈希。然而，也可能设计出需要以特定方式处理内容的哈希算法，从而抵消这些好处。例如，Merkle Integrity Content Encoding [MICE] 需要以反向顺序处理内容，这意味着必须拥有完整数据，因此在头部或尾部发送完整性字段在处理上几乎没有差别。

内容编码机制可能支持不同的编码参数，这意味着相同的输入内容可以产生不同的输出。例如，GZIP 支持多种压缩级别。这类编码参数通常不会作为表示元数据进行传达。例如，不同的压缩级别仍然使用相同的 "Content-Encoding: gzip" 字段。另一个例子是依赖随机数或时间戳的编码，例如 [RFC8188] 中定义的 aes128gcm 内容编码。

由于内容编码内可能存在变动，完整性字段传达的校验和不能在“静态存储”场景中作为完整性证明，除非整个内容被持久化保存。

哈希算法的安全属性并非固定不变。算法灵活性（参见 [RFC7696]）通过允许实现从 IANA 的 “Hash Algorithms for HTTP Digest Fields” 注册表中选择哈希算法来实现；参见 第 7.2 节。

通过 Want-Content-Digest 或 Want-Repr-Digest（参见 第 4 节）协商哈希算法，或通过发送多个摘要由接收方选择，支持从弱算法过渡到更强算法。依赖某个摘要来实现安全性的接收方将易受其愿意接受的最弱算法的攻击。端点应注意，发送多个值会消耗资源，如果接收方忽略这些值则可能被浪费（参见 第 3 节）。

尽管算法灵活性允许向更强算法迁移，但它不能阻止弱算法的使用。完整性字段并不对哈希算法的降级或替换攻击提供任何缓解措施（参见 [RFC6211] 第 1 节）。为防止此类攻击，端点可以将其支持的算法集合限制为更强的算法，并通过使用 TLS 和/或数字签名来保护字段值。

验证完整性字段会消耗计算资源。为避免资源耗尽，实现在验证时可以限制算法类型、验证次数或内容大小。在这些情况下，完全跳过验证或忽略更高优先级算法的验证失败会留下降级攻击的可能性（参见 第 6.6 节）。

IANA 已在 <https://www.iana.org/assignments/http-digest-hash-al/> 创建了新的 “Hash Algorithms for HTTP Digest Fields” 注册表，并用表 表 2 中的条目填充了该注册表。新注册的流程见 第 5 节。

该注册表已被弃用，因为它列出了可用于 Digest 与 Want-Digest 字段的算法，而这些字段由 [RFC3230] 定义，且该 RFC 已被 RFC 9530 废弃。虽然注册并未关闭，但鼓励新的注册使用 “Hash Algorithms for HTTP Digest Fields” 注册表。

在此示例中，消息内容传达了完整的表示数据。这意味着在响应中，Content-Digest 与 Repr-Digest 都是对 JSON 对象 {"hello": "world"} 后跟一个 LF 计算得到的；因此它们具有相同的值。

在此示例中，使用 HEAD 请求来检索资源的校验和。

响应中的 Content-Digest 字段值是对空内容计算的。Repr-Digest 是对 JSON 对象 {"hello": "world"} 后跟一个 LF 计算的，但由于没有内容该对象不显示出来。

在此示例中，客户端发出范围请求，服务器以部分内容响应。

NOTE: '\' line wrapping per RFC 8792

Repr-Digest: \
  sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:

NOTE: '\' line wrapping per RFC 8792

Content-Digest: \
  sha-256=:jjcgBDWNAtbYUXI37CVG3gRuGOAjaaDRGpIUFsdyepQ=:

请求包含一个在所封装表示上计算的 Repr-Digest 字段值。它还包含一个声明客户端支持 Brotli 编码的 Accept-Encoding: br 头字段。

响应包含一个指示所选表示为 Brotli 编码的 Content-Encoding: br。因此响应中的 Repr-Digest 字段值与请求中不同。

出于展示目的，响应体以十六进制编码字节序列显示，因为其中包含不可打印字符。

请求中的 Repr-Digest 字段值是在所封装内容上计算的，该内容为 JSON 对象 {"hello": "world"} 后跟一个 LF。

响应中的 Repr-Digest 字段值取决于表示元数据头字段，包括 Content-Encoding: br，即使响应不包含内容亦然。

NOTE: '\' line wrapping per RFC 8792

PUT /items/123 HTTP/1.1
Host: foo.example
Content-Type: application/json
Content-Length: 19
Accept-Encoding: br
Repr-Digest: \
  sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg==:

{"hello": "world"}

响应包含使用不同算法的两个摘要值。

出于展示目的，响应体以十六进制编码字节序列显示，因为其中包含不可打印字符。

请求中的 Repr-Digest 字段值是在所封装的表示上计算的（见 第 3.1 节），该表示为 JSON 对象 {"title": "New Title"} 后跟一个 LF。

响应中封装的表示是一个多行 JSON 对象后跟一个 LF。它通过 Content-Location 指向由其值标识的资源（参见 [HTTP] 第 6.4.2 节）；因此应用可以将 Repr-Digest 与由 Content-Location 引用的资源关联使用。

请求中的 Repr-Digest 字段值是在所封装的表示上计算的（见 第 3.1 节），该表示为 JSON 对象 {"title": "New Title"} 后跟一个 LF。

响应中封装的表示描述了请求的状态，因此 Repr-Digest 在该封装表示上计算。它为一个多行 JSON 对象后跟一个 LF。

响应的 Repr-Digest 与由 Location 引用的资源之间没有明确关联。

此情形类似于目标资源反映目标 URI 的 POST 请求。

PATCH 请求使用 application/merge-patch+json 媒体类型（参见 [RFC7396]）。Repr-Digest 在对应补丁文档的内容上计算，该内容为 JSON 对象 {"title": "New Title"} 后跟一个 LF。

响应中的 Repr-Digest 字段值是在被修补资源的完整表示上计算的。它为一个多行 JSON 对象后跟一个 LF。

注意，不带内容但具有相同 Repr-Digest 字段值的 204 No Content 响应也同样是合法的。在那种情况下，Content-Digest 会在空内容上计算。

在错误响应中，表示数据不必指向目标资源，而是指向错误的表示。

在下面的示例中，客户端向图 26（参见 PATCH 请求）中相同的请求对 /books/123 发出补丁请求。然而，该资源不存在，服务器生成了一个 404 响应，响应体按照 [RFC9457] 描述了错误。

响应中的 Repr-Digest 字段值是在此封装表示上计算的。它为一个多行 JSON 对象后跟一个 LF。

源服务器将 Repr-Digest 作为尾部字段发送，以便在流式传输内容时计算摘要值，从而减轻资源消耗。由于 Repr-Digest 设计为独立于一次或多次传输编码的使用（参见 第 3 节），因此其字段值与附录 B.1 中相同。

在下面的响应内容中，字符串 "\r\n" 表示 CRLF 字节。

客户端请求摘要并偏好 "sha"。服务器仍然可以自由地用 "sha-256" 作出响应。

客户端请求 "sha" 摘要，因为那是它唯一支持的算法。服务器没有义务生成包含 "sha" 摘要的响应；它可以改用不同的算法。

附录 C.2 是一个示例，展示了服务器忽略客户端首选摘要算法的情形。作为替代，服务器也可以拒绝该请求并返回包含 4xx 或 5xx 等错误状态码的响应。本规范未对状态码选择提出强制性要求；下面的示例只是说明一种可选方案。

在此示例中，客户端请求 "sha" Repr-Digest，服务器返回包含问题详细信息（参见 [RFC9457]）的错误响应体。问题详细信息列出了服务器支持的哈希算法。这仅为示例；本规范未定义此类内容的格式或要求。