]> Cloudflare

lucas@lucaspardue.com

Google

mkwst@google.com

Web and Internet Transport HTTP next generation unicorn sparkling distributed ledger The Repr-Digest and Content-Digest integrity fields are subject to HTTP content coding considerations. There are some use cases that benefit from the unambiguous exchange of integrity digests of unencoded representation. The Unencoded-Digest and Want-Unencoded-Digest fields complement existing integrity fields for this purpose. This document updates the definitions of the terms "Integrity fields" and "Integrity preference fields" originally defined in RFC 9530. About This Document Status information for this document may be found at . Discussion of this document takes place on the HTTP Working Group mailing list (), which is archived at . Working Group information can be found at . Source for this draft and an issue tracker can be found at .

Introduction The Repr-Digest and Content-Digest integrity fields defined in are suitable for a range of use cases. However, because the fields are subject to HTTP content coding considerations, it is difficult to support use cases that could benefit from the exchange of integrity digests of the unencoded representation. As a simple example, an application using HTTP might be presented with request or response representation data that has been transparently decoded. Attempting to verify the integrity of the data against the Repr-Digest would first require re-encoding that data using the same coding indicated by the Content-Encoding header field (), which is not always possible (see ). Although receivers could feasibly re-encode data in order to carry out Repr-Digest validation, it might be impractical for certain kinds of environments. For instance, browsers tend to provide built-in support for transparent decoding but little support for encoding; while this could be done via the use of additional libraries it would create work in JavaScript that could contend with other activities. Even on the server side, the re-encoding of received data might not be acceptable; some coding algorithms are optimized towards efficient decoding at the cost of complex encoding. A Content-Encoding field value that indicates a series of encodings adds further complexity. A more complex example involves HTTP Range Requests (), where a client issues multiple requests to obtain partial representations and "stitches" them back into a whole. Unfortunately, if the responses have different content codings, the Repr-Digest field will vary by the server's selected encoding (i.e., the Content-Encoding header field, ). This provides a challenge for a client - in order to verify the integrity of the pieced-together whole it would need to remove the encoding of each part, combine them, and then encode the result in order to compare against one or more Repr-Digests. The Accept-Encoding header field () provides the means to indicate preferences for content codings. It is possible for an endpoint to indicate a preference for no encoding, for example, by sending the "identity" token. However, codings often provide data compression that is advantageous. Disabling content coding in order to simplify integrity checking might not be an acceptable trade-off. For a variety of reasons, decoding and re-encoding content in order to benefit from HTTP integrity fields is not preferable. This specification defines the Unencoded-Digest and Want-Unencoded-Digest fields to support a simpler validation workflow in some scenarios where content coding is applied. These fields complement the other integrity fields defined in . This document updates the definition of terms originally defined in . "Integrity fields" is updated to also include the Unencoded-Digest field (. "Integrity preference fields" is updated Want-Unencoded-Digest field ().

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. This document uses the following terminology from to specify syntax and parsing: Byte Sequence, Dictionary, and Integer. The definitions "representation", "selected representation", "representation data", "representation metadata", and "content" in this document are to be interpreted as described in . This document uses the line folding strategies described in . The term "digest" is to be interpreted as described in . "Integrity fields" is the collective term for Content-Digest, Repr-Digest, and Unencoded-Digest. "Integrity preference fields" is the collective term for Want-Repr-Digest, Want-Content-Digest, and Want-Unencoded-Digest.

The Unencoded-Digest Field The Unencoded-Digest HTTP field can be used in requests and responses to communicate digests that are calculated using a hashing algorithm applied to the entire selected representation data with no content codings applied (). Apart from the content coding concerns, Unencoded-Digest behaves similarly to Repr-Digest (). Unencoded-Digest can be sent in messages with and without content codings. When there is no content coding, Unencoded-Digest acts identically to Repr-Digest; for the same hashing algorithm the computed value would be the same. Unencoded-Digest is a Dictionary (see ) where each:

• key conveys the hashing algorithm (see ) used to compute the digest;
• value is a Byte Sequence (), that conveys an encoded version of the byte output produced by the digest calculation. Each Dictionary value can have zero or more Parameters (). This specification does not define any Parameters; future extensions may do so. Unknown Parameters MUST be ignored.

In the following examples of Unencoded-Digest fields, the representation data with no content codings applied is: "An unexceptional string" followed by a line feed character (0xA). The Dictionary type can be used, for example, to attach multiple digests calculated using different hashing algorithms in order to support a population of endpoints with different or evolving capabilities. Such an approach could support transitions away from weaker algorithms (see ). A recipient MAY ignore any or all digests. Application-specific behavior or local policy MAY set additional constraints on the processing and validation practices of the conveyed digests. Security considerations related to ignoring digests or validating multiple digests are presented in Sections and of respectively. A sender MAY send a digest without knowing whether the recipient supports a given hashing algorithm. A sender MAY send a digest if it knows the recipient will ignore it. Unencoded-Digest can be sent in a trailer section. In this case, Unencoded-Digest MAY be merged into the header section; see .

The Want-Unencoded-Digest Field Want-Unencoded-Digest is an integrity preference field; see . It indicates that the sender would like to receive (via the Unencoded-Digest field) a representation digest on messages associated with the request URI and representation metadata where no content coding is applied. If Want-Unencoded-Digest is used in a response, it indicates that the server would like the client to provide the Unencoded-Digest field on future requests. Want-Unencoded-Digest is only a hint. The receiver of the field can ignore it and send an Unencoded-Digest field using any algorithm or omit the field entirely. It is not a protocol error if preferences are ignored. Applications that use Unencoded-Digest and Want-Unencoded-Digest can define expectations or constraints that operate in addition to this specification. Ignored preferences are an application-specific concern. Want-Unencoded-Digest is of type Dictionary where each:

• key conveys the hashing algorithm;
• value is an Integer () 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". Each Dictionary value can have zero or more Parameters (). This specification does not define any Parameters; future extensions may do so. Unknown Parameters MUST be ignored.

Examples:

Messages containing both Unencoded-Digest and Content-Encoding Digests delivered through Unencoded-Digest apply to the unencoded representation. If a message is received with content codings, a recipient needs to decode the message in order to calculate the digest that can subsequently be used for validation. If multiple content codings are applied, the recipient needs to decode all encodings in order before validation. Since the digest is calculated on unencoded representation bytes, validation of a message with content codings (as described above) can only succeed where the decoded output produces the same byte sequence as the input. While describes content codings to operate "without loss of information", that doesn't necessarily mean a byte-for-byte equivalence. A content coding could perform semantically-meaningless transformations that nevertheless result in a decoded byte sequence that does not exactly match the original unencoded representation. In order to avoid unintended validation failures, care is advised when selecting content codings for use with Unencoded-Digest; that said, most registered content codings do provide byte-for-byte equivalence and are appropriate.

Integrity Fields are Complementary Integrity fields can be used in combination to address different and complementary needs, particularly the cases described in . In the following examples, the selected representation data with no content codings applied is: "An unexceptional string" followed by a line feed character (0xA). For presentation purposes, the response content is displayed as a sequence of hex-encoded bytes because it contains non-printable characters. The first example demonstrates a request that uses content negotiation.

GET request with content negotiation

The server responds with the full GZIP-encoded representation. The Repr-Digest and Unencoded-Digest therefore differ.

GET response with GZIP content coding

The second example demonstrates a range request that uses content negotiation.

Range request with content negotiation

The server responds with a 206 (Partial Content) response using GZIP content coding, it has three different Integrity fields. The Content-Digest relates to the response content that can be used to validate the integrity of the received part. Repr-Digest and Unencoded-Digest can be used later once the entire object is reconstructed. The choice of which to use is left to the application that would consider a range of factors outside the scope of this document.

Partial response with GZIP content coding

Security Considerations All the same considerations documented in apply. This document introduces a further consideration related to the process of validation when an HTTP message contains both Content-Encoding and Unencoded-Digest (). In order to validate the Unencoded-Digest, encoded content needs to be decoded. This provides an opportunity for an attacker to direct malicious data into a decoder. One possible mitigation would be to also provide a Content-Digest or Repr-Digest in the message, allowing for validation of the received bytes before further processing. An attacker that can substitute various parts of an HTTP message presents several risks; Sections , , and of describe relevant considerations and mitigations. A content coding might provide encryption capabilities, for example "aes128gcm" (). Using Unencoded-Digest with such content codings can leak information about the original data because header fields are visible to anyone who can read the HTTP message. For instance, an attacker that can access Unencoded-Digest values could infer details about the unencrypted content without decrypting it if, for example, the unencrypted content has a predictable pattern. When the "aes128gcm" content coding is used, the security considerations in apply. Namely, the Unencoded-Digest field is considered sensitive information and SHOULD be omitted unless a means of encrypting the Unencoded-Digest field is used.

IANA Considerations IANA is asked to update the "Hypertext Transfer Protocol (HTTP) Field Name Registry" as shown in the table below: Hypertext Transfer Protocol (HTTP) Field Name Registry Update

Field Name	Status	Structured Type	Reference
Unencoded-Digest	permanent	Dictionary	of this document
Want-Unencoded-Digest	permanent	Dictionary	of this document

References Normative References This document defines HTTP fields that support integrity digests. The Content-Digest field can be used for the integrity of HTTP message content. The Repr-Digest field can be used for the integrity of HTTP representations. Want-Content-Digest and Want-Repr-Digest can be used to indicate a sender's interest and preferences for receiving the respective Integrity fields. This document obsoletes RFC 3230 and the Digest and Want-Digest HTTP fields. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document describes a set of data types and associated algorithms that are intended to make it easier and safer to define and handle HTTP header and trailer fields, known as "Structured Fields", "Structured Headers", or "Structured Trailers". It is intended for use by specifications of new HTTP fields. This document obsoletes RFC 8941. Informative References This document defines two strategies for handling long lines in width-bounded text content. One strategy, called the "single backslash" strategy, is based on the historical use of a single backslash ('\') character to indicate where line-folding has occurred, with the continuation occurring with the first character that is not a space character (' ') on the next line. The second strategy, called the "double backslash" strategy, extends the first strategy by adding a second backslash character to identify where the continuation begins and is thereby able to handle cases not supported by the first strategy. Both strategies use a self-describing header enabling automated reconstitution of the original content. This memo introduces a content coding for HTTP that allows message payloads to be encrypted.

Acknowledgments Early drafts of included a mechanism to support the exchange of digests where no content coding is applied, which was removed before publication. While the design here is different, it is motivated by discussion of the previous design in the HTTP WG. The motivating use cases still mostly apply identically. The following people provided detailed feedback on the document: Mike Bishop, Mallory Knodel, Roberto Polli, Rifaat Shekh-Yusef, and Martin Thomson.