]> Cloudflare

lucas@lucaspardue.com

Google

mkwst@google.com

Applications 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 Identity-Digest and Want-Identity-Digest fields complement existing integrity fields for this purpose. About This Document The latest revision of this draft can be found at . 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 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 fetches multiple partial representations from different origins and "stitches" them back into a whole. Unfortunately, if the origins apply different content coding, 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 coding. 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 is possibly an unacceptable 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 Identity-Digest and Want-Identity-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 .

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 Augmented BNF defined in and updated by . This includes the rules: LF (line feed) 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 . "Integrity fields" is the collective term for Content-Digest, Repr-Digest, and Identity-Digest "Integrity preference fields" is the collective term for Want-Repr-Digest, Want-Content-Digest, and Want-Identity-Digest

The Identity-Digest Field The Identity-Digest HTTP field can be used in requests and responses to communicate digests that are calculated using a hashing algorithm applied to the representation with no content coding (). Apart from the content coding concerns, it behaves similarly to Repr-Digest (). Identity-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.

For example: 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. The security considerations cover some of the issues related to ignoring digests (see ) and validating multiple digests (see ). 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. Identity-Digest can be sent in a trailer section. In this case, Identity-Digest MAY be merged into the header section; see .

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

Examples:

Messages containing both Identity-Digest and Content-Encoding Digests delivered through Identity-Digest apply to the unencoded representation. If a message is received with content coding, 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.

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 unencoded response data is the string "An unexceptional string" following by an LF. 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 Identity-Digest therefore differ.

GET response with GZIP-encoded content

The second example demonstrates a range request with content negotiation.

Range request with content negotiation

The server responds with a 206 Partial Content response using GZIP encoding, it has three different Integrity fields. The Content-Digest relates to the response message content that can be used to validate the integrity of the received part. Repr-Digest and Identity-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 encoding

Security Considerations The considerations in apply. There are no known additional considerations.

IANA Considerations This document has no IANA actions (yet)

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. Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] This document extends the base definition of ABNF (Augmented Backus-Naur Form) to include a way to specify US-ASCII string literals that are matched in a case-sensitive manner. 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.

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.