]>

lucas@lucaspardue.com

Web and Internet Transport HTTP next generation unicorn AI-native The PATCH method can be used to apply partial modifications to a resource. This document defines the Patched-Digest request field, which allows a client to indicate the integrity digest of the modified resource once a PATCH operation is applied. A server can use the integrity digest to detect an operation failure and return an error. The Want-Patched-Digest response field is also defined to signal server integrity preferences. 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 . Source for this draft and an issue tracker can be found at .

Introduction The PATCH method can be used to apply partial modifications to a resource. A client can indicate the desired precondition of the resource prior to a PATCH operation being applied (). For example, sending a PATCH request containing an If-Match () with a strong ETag (). The following example illustrates a hypothetical PATCH request to apply a patch document to an existing resource with the ETag "e0023aa4e": The PATCH operation results in a successful response that indicates the resource has been modified and the new ETag is "e0023aa4f. To date there have been no means to communicate the client's expectation of the result of a PATCH operation, delaying the ability for both client and server to detect an error. While the integrity fields defined in and can be used by a client to obtain information related to the resource before and/or after a PATCH operation, that cannot be used to communicate an a priori expectation for the result. For instance, the example request could be augmented to include integrity fields but all of them refer to the patch document itself, not any state of the resource: The earlier example response can be similarly augmented with integrity fields that indicate the state of the resource after modification: The client might be able to use either Repr-Digest or Unencoded-Digest to detect a problem that occurred during the PATCH operation. However, the server would remain oblivious unless further action were taken by the client to communicate a failure. This document defines the Patched-Digest request field, which allows a client to indicate the integrity digest () of the modified resource once a PATCH operation is applied. A server can use the integrity digest to detect an operation failure and return an error response. Patched-Digest complements other integrity fields but has a much narrower usage scope. As is common for integrity fields, the Want-Patched-Digest response field is also defined to signal server integrity preferences.

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 .

The Patched-Digest Field The Patched-Digest HTTP field can be used in requests to communicate an expected digest for the result of applying a PATCH document to a resource. The digest is calculated using a hashing algorithm applied to the resource's entire selected representation data with no content codings applied (). In the following examples of Patched-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 server 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. TODO: should we be more strict and recommend returning an error (and maybe point to RFC 5789 Section 2.2)? A client MAY send a digest without knowing whether the server supports a given hashing algorithm. A sender MAY send a digest if it knows the recipient will ignore it. An example is depicted in . Patched-Digest can be sent in a trailer section. In this case, Patched-Digest MAY be merged into the header section; see .

The Want-Patched-Digest Field Want-Patched-Digest is an integrity preference field; see . It indicates that the server would like to receive a Patched-Digest with PATCH requests. Want-Patched-Digest is only a hint. Clients can ignore it and send an Patched-Digest field using any algorithm or omit the field entirely. It is not a protocol error if preferences are ignored. Applications that use Patched-Digest and Want-Patched-Digest can define expectations or constraints that operate in addition to this specification. Ignored preferences are an application-specific concern. Want-Patched-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:

Security Considerations All the same considerations documented in apply.

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
Patched-Digest	permanent	Dictionary	of this document
Want-Patched-Digest	permanent	Dictionary	of this document

References Normative References Cloudflare Google 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. Several applications extending the Hypertext Transfer Protocol (HTTP) require a feature to do partial resource modification. The existing HTTP PUT method only allows a complete replacement of a document. This proposal adds a new HTTP method, PATCH, to modify an existing HTTP resource. [STANDARDS-TRACK] 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. 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. 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.

Example of Patched-Digest Usage This section contains a non-normative example of Patched-Digest usage for a hypothetical PATCH request. A resource located at https://www.example.com/file.txt is a plaintext file containing the string: "An unexceptional string" followed by a line feed character (0xA). A client could send a HEAD request to gather information about the status of the resource, including its integrity preference for the response: The server could provide a response the contains both an ETag and an Unencoded-Digest. It is also assumed that the client and server understand this resource can be patched (via an out-of-band signal) and so the server returns a Want-Patched-Digest: The client could make a conditional request to patch the resource and provide a Patched-Digest. In this hypothetical example, the patch document is applied by appending it to the resource, the document value is the string: "can become magic" followed by a line feed character (0xA). The server applies the patch document and confirms the result matches the Patched-Digest value, then returns a success message with a new ETag. If the client attempts to patch again with a mismatching Patched-Digest: even though the ETag precondition passes, the server is able to detect a problem with the patch operation and return an error response:

Acknowledgments The PATCH integrity capability gap was identified by a discussion with Grant Gryczan. Roberto Polli provided a reminder that the topic was touched on during RFC 9530 development, and provided some early technical input related to the design in this document.