jiebi/CodeConvo huggingface dataset:
Code change:
There are currently some uses of "serialise" in place of the far more common "serialize", including one case that breaks the pattern of header names ("Serializing a List", "Serializing a Dictionary", "Serializing an Item", …, "Serialising a Date"). This PR also includes an analogous update of "summarises" to "summarizes" to increase the general pattern of American spellings.
Speaking Danglish myself, I am disqualified from having an opinion on this subject matter :-)
Despite my Australianised sensibilities, I see that 8941 was normalised to American spelling by the RFC Editor, and changing things now would introduce more diffs. Thanks for the PR.

Related discussion:
text: Boolean values can be conveyed in Structured Fields. <del> When serialised in a textual HTTP field, a Boolean is indicated with </del> <ins> When serialized in a textual HTTP field, a Boolean is indicated with </ins> a leading "?" character followed by a "1" for a true value or "0" for false.  For example:
Code change:
This moves the values that were in the Encryption header field to the start of the payload. This provides a meagre efficiency gain as well as removing the need to have two correlated header fields. This should go most of the way to address WGLC comments.
Looks good to me in general. That said; this removes the parsing weirdness for "Encryption" (good), but not for "Crypto-Key", right?
NAME happy to correct any parsing weirdness, but need to know precisely what it is first.

Related discussion:
text: encryption. The "aesgcm" content coding uses a fixed record size.  The resulting <del> encoding is either a single record, or a series of fixed-size records.  The final record, or a lone record, MUST be shorter than the fixed record size. </del> <ins> encoding is any number of fixed-size records - which could be zero records - followed by a single partial record.  The partial record MUST be shorter than the fixed record size. </ins> The record size determines the length of each portion of plaintext that is enciphered, with the exception of the final record, which is
Code change:
This moves the values that were in the Encryption header field to the start of the payload. This provides a meagre efficiency gain as well as removing the need to have two correlated header fields. This should go most of the way to address WGLC comments.
Looks good to me in general. That said; this removes the parsing weirdness for "Encryption" (good), but not for "Crypto-Key", right?
NAME happy to correct any parsing weirdness, but need to know precisely what it is first.

Related discussion:
text: the content coding is reflected in a separate Encryption header field value in the order in which they were applied. <ins> Content codings that use the Encryption header field MUST always include a value for the header field when the content coding has been applied.  If no parameters are needed, then a dummy value is necessary to avoid confusion about which set of parameters applies to which content coding.  This requirement applies to uses of the "aesgcm" content coding. </ins> Encryption header field values with multiple instances of the same <del> parameter name are invalid. </del> <ins> parameter name in a single encryption-params production are invalid. </ins> Servers processing PUT requests MUST persist the value of the Encryption header field, unless they remove the content coding by
Code change:
This moves the values that were in the Encryption header field to the start of the payload. This provides a meagre efficiency gain as well as removing the need to have two correlated header fields. This should go most of the way to address WGLC comments.
Looks good to me in general. That said; this removes the parsing weirdness for "Encryption" (good), but not for "Crypto-Key", right?
NAME happy to correct any parsing weirdness, but need to know precisely what it is first.

Related discussion:
text: parameter can also be used to identify keys in an application- specific fashion. <del> The "salt" parameter contains a base64url-encoded octets RFC7515 that is used as salt in deriving a unique content encryption key (see derivation).  The "salt" parameter MUST be present, and MUST be exactly 16 octets long when decoded.  The "salt" parameter MUST </del> <ins> The "salt" parameter contains a base64url-encoded octets that is used as salt in deriving a unique content encryption key (see derivation).  The "salt" parameter MUST be present, and MUST be exactly 16 octets long when decoded.  The "salt" parameter MUST </ins> NOT be reused for two different payload bodies that have the same input keying material; generating a random salt for every application of the content coding ensures that content encryption
Code change:
This moves the values that were in the Encryption header field to the start of the payload. This provides a meagre efficiency gain as well as removing the need to have two correlated header fields. This should go most of the way to address WGLC comments.
Looks good to me in general. That said; this removes the parsing weirdness for "Encryption" (good), but not for "Crypto-Key", right?
NAME happy to correct any parsing weirdness, but need to know precisely what it is first.

Related discussion:
text: "Content-Encoding: aesgcm", a single zero octet and an optional context string: <ins> Concatenation of octet sequences is represented by the "||" operator. </ins> Unless otherwise specified, the context is a zero length octet sequence.  Specifications that use this content coding MAY specify the use of an expanded context to cover additional inputs in the key
Code change:
This moves the values that were in the Encryption header field to the start of the payload. This provides a meagre efficiency gain as well as removing the need to have two correlated header fields. This should go most of the way to address WGLC comments.
Looks good to me in general. That said; this removes the parsing weirdness for "Encryption" (good), but not for "Crypto-Key", right?
NAME happy to correct any parsing weirdness, but need to know precisely what it is first.

Related discussion:
text: 3.3. The nonce input to AEAD_AES_128_GCM is constructed for each record. <del> The nonce for each record is a 12 octet (96 bit) value is produced from the record sequence number and a value derived from the input keying material. </del> <ins> The nonce for each record is a 12 octet (96 bit) value that is produced from the record sequence number and a value derived from the input keying material. </ins> The input keying material and salt values are input to HKDF with different info and length parameters. The length (L) parameter is 12 octets.  The info parameter for the nonce is the ASCII-encoded string "Content-Encoding: nonce", a single <del> zero octet and an context: </del> <ins> zero octet and a context: </ins> The context for nonce derivation is the same as is used for content encryption key derivation.
Code change:
This moves the values that were in the Encryption header field to the start of the payload. This provides a meagre efficiency gain as well as removing the need to have two correlated header fields. This should go most of the way to address WGLC comments.
Looks good to me in general. That said; this removes the parsing weirdness for "Encryption" (good), but not for "Crypto-Key", right?
NAME happy to correct any parsing weirdness, but need to know precisely what it is first.

Related discussion:
text: coding. Crypto-Key header field values with multiple instances of the same <del> parameter name are invalid. </del> <ins> parameter name in a single crypto-key-params production are invalid. </ins> The input keying material used by the key derivation (see derivation) can be determined based on the information in the Crypto-Key header
Code change:
This moves the values that were in the Encryption header field to the start of the payload. This provides a meagre efficiency gain as well as removing the need to have two correlated header fields. This should go most of the way to address WGLC comments.
Looks good to me in general. That said; this removes the parsing weirdness for "Encryption" (good), but not for "Crypto-Key", right?
NAME happy to correct any parsing weirdness, but need to know precisely what it is first.

Related discussion:
text: 5.1. Here, a successful HTTP GET response has been encrypted using input <del> keying material that is identified by a URI. </del> <ins> keying material that is identified by the string "a1". </ins> The encrypted data in this example is the UTF-8 encoded string "I am the walrus".  The input keying material is included in the Crypto-Key
Code change:
This moves the values that were in the Encryption header field to the start of the payload. This provides a meagre efficiency gain as well as removing the need to have two correlated header fields. This should go most of the way to address WGLC comments.
Looks good to me in general. That said; this removes the parsing weirdness for "Encryption" (good), but not for "Crypto-Key", right?
NAME happy to correct any parsing weirdness, but need to know precisely what it is first.

Related discussion:
text: Note that the media type has been changed to "application/octet- stream" to avoid exposing information about the content. <ins> Alternatively (and equivalently), the Content-Type header field can be omitted. </ins> 5.2.
Code change:
message signatures are just one part of an overall system, and this adds language to make that expectation more explicit in the introductory sections.

Related discussion:
text: This document defines a mechanism for providing end-to-end integrity and authenticity for components of an HTTP message by use of a <del> detached signature.  The mechanism allows applications to create digital signatures or message authentication codes (MACs) over only the components of the message that are meaningful and appropriate for the application.  Strict canonicalization rules ensure that the verifier can verify the signature even if the message has been transformed in any of the many ways permitted by HTTP. </del> <ins> detached signature on HTTP messages.  The mechanism allows applications to create digital signatures or message authentication codes (MACs) over only the components of the message that are meaningful and appropriate for the application.  Strict canonicalization rules ensure that the verifier can verify the signature even if the message has been transformed in many of the ways permitted by HTTP. </ins> The signing mechanism described in this document consists of three parts:
Code change:
message signatures are just one part of an overall system, and this adds language to make that expectation more explicit in the introductory sections.

Related discussion:
text: mechanism can be used along with opportunistic or application-driven message signatures by either party. <ins> The mechanisms defined in this document are important tools that can be used to an overall security mechanism for an application.  This toolkit provides some powerful capabilities, but does not sufficient in creating an overall security story.  In particular, the requirements in application and the security considerations in security are of high importance to all implementors of this specification.  For example, this specification does not define a means to directly cover HTTP message content (defined in HTTP), but relies on the DIGEST specification to provide a hash of the message content, as discussed in security-message-content. </ins> 1.1. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
Code change:
message signatures are just one part of an overall system, and this adds language to make that expectation more explicit in the introductory sections.

Related discussion:
text: 1.4. <del> HTTP Message Signatures are designed to be a general-purpose security mechanism applicable in a wide variety of circumstances and applications.  In order to properly and safely apply HTTP Message Signatures, an application or profile of this specification MUST specify all of the following items: </del> <ins> HTTP Message Signatures are designed to be a general-purpose tool applicable in a wide variety of circumstances and applications.  In order to properly and safely apply HTTP Message Signatures, an application or profile of this specification MUST specify at least all of the following items: </ins> The set of covered-components and signature-params that are expected and required to be included in the covered components
Code change:
message signatures are just one part of an overall system, and this adds language to make that expectation more explicit in the introductory sections.

Related discussion:
text: when choosing the required set of component identifiers, care has to be taken to make sure that the coverage is sufficient for the application, as discussed in security-coverage and security-message- <del> content. </del> <ins> content.  This specification defines only part of a full security system for an application.  When building a complete security system based on this tool, it is important to perform a security analysis of the entire system of which HTTP Message Signatures is a part. Historical systems, such as AWS-SIGv4, can provide inspiration and examples of how to apply similar mechanisms in a secure and trustable fashion. </ins> 2.
Code change:
Point out that many frameworks smush together form parameters and query parameters into one bucket, and that can cause unexpected shadowing. Some examples changed to avoid ambiguity.
This is great.

Related discussion:
text: padding attack would be rejected by the field value processor, even in the case where the attacker could force a signature collision. <ins> 7.5.8. The HTML form parameters format defined in the "application/x-www- form-urlencoded" section of HTMLURL, is widely deployed and supported by many application frameworks.  For convenience, some of these frameworks in particular combine query parameters that are found in the HTTP query and those found in the message content, particularly for POST message with a Content-Type value of "application/x-www- form-urlencoded".  The "@query-param" derived component identifier defined in content-request-query-param draws its values only from the query section of the target URI of the request.  As such, it would be possible for an attacker to shadow or replace query parameters in a request by overriding the signed query parameter with an unsigned form parameter, or vice versa. To counter this, an application needs to make sure that values used for the signature base and the application are drawn from a consistent context, in this case the query component of the target URI.  Additionally, when the HTTP request has content, an application should sign the message content as well, as discussed in security- message-content. </ins> 8. 8.1.
Code change:
Proposed fix in URL - note that this is an incompatible change.
FWFW, if the argument is that not escaping the escape character is actually ok for this purpose...: in that case the prose should actually explain this.
I actually do think it's ok to not escape the escape character. If you've got non-ASCII header values you're already kinda out in the weeds in terms of processing the header bytes. Ultimately the signature base really only needs to have bytes, but its input is constrained to ASCII because (1) all derived components are already constrained this way (2) component names and arguments are already constrained and (3) header component values (here) are SUPPOSED to be constrained to ASCII, but might not be in some weird corners as you've pointed out. All that the newly-introduced percent encoding is doing is putting bumpers around the weird corner that isn't supposed to happen but might in some cases. I'd honestly be happier with putting advice to use the binary sequence wrapping ( flag) on problematic non-ASCII header values instead of doing percent-encoding and requiring universal escape of the escape character when the encoding isn't going to hit the VAST majority of use cases. That would reverse the previously-applied fix but I'm fine that.
That works for me. If we combine that with the "MUST produce an error for non-ASCII" in the signature base generation (and people actually do that check), we should be safe.
OK, I'll work on that, unless you want to take a swing at it.. Since we've already got the cut-out for fields that don't behave nicely as lists (specifically Set-Cookie), we've got a good space to put this advice. I think an error on generation makes perfect sense here too. I'll back out the percent-encoding for non-ASCII headers at the same time (but note it'll stay for query parameters, where I do think it makes sense to use).

Related discussion:
text: "tr" flags, below.  For most fields, the field value is an ASCII string as recommended by HTTP, and the component value is exactly that string.  Other encodings could exist in some implementations, <del> and any characters outside the ASCII range MUST be encoded using the percent-encoding mechanism defined in URI. </del> <ins> and all non-ASCII field values MUST be encoded to ASCII before being added to the signature base.  The "bs" parameter defined in http- field-byte-sequence provides a method for wrapping such problematic field values. </ins> Unless overridden by additional parameters and rules, HTTP field values MUST be combined into a single value as defined in HTTP to
Code change:
Proposed fix in URL - note that this is an incompatible change.
FWFW, if the argument is that not escaping the escape character is actually ok for this purpose...: in that case the prose should actually explain this.
I actually do think it's ok to not escape the escape character. If you've got non-ASCII header values you're already kinda out in the weeds in terms of processing the header bytes. Ultimately the signature base really only needs to have bytes, but its input is constrained to ASCII because (1) all derived components are already constrained this way (2) component names and arguments are already constrained and (3) header component values (here) are SUPPOSED to be constrained to ASCII, but might not be in some weird corners as you've pointed out. All that the newly-introduced percent encoding is doing is putting bumpers around the weird corner that isn't supposed to happen but might in some cases. I'd honestly be happier with putting advice to use the binary sequence wrapping ( flag) on problematic non-ASCII header values instead of doing percent-encoding and requiring universal escape of the escape character when the encoding isn't going to hit the VAST majority of use cases. That would reverse the previously-applied fix but I'm fine that.
That works for me. If we combine that with the "MUST produce an error for non-ASCII" in the signature base generation (and people actually do that check), we should be safe.
OK, I'll work on that, unless you want to take a swing at it.. Since we've already got the cut-out for fields that don't behave nicely as lists (specifically Set-Cookie), we've got a good space to put this advice. I think an error on generation makes perfect sense here too. I'll back out the percent-encoding for non-ASCII headers at the same time (but note it'll stay for query parameters, where I do think it makes sense to use).

Related discussion:
text: parameter's functionality is already covered when the "key" parameter is used on a dictionary item, since "key" requires strict serialization of the value.  The "bs" parameter, which requires the <del> raw field values from the message, is not compatible with use of the "sf" or "key" parameters, which require the parsed data structures of the field values after combination. </del> <ins> raw bytes of the field values from the message, is not compatible with use of the "sf" or "key" parameters, which require the parsed data structures of the field values after combination. </ins> Additional parameters can be defined in the HTTP Signature Component Parameters registry established in component-param-registry.
Code change:
Encodes query parameter names to match values, to avoid non-ascii or otherwise problematic values.
In 2.2.8: What if the query parameter contains non-ASCII characters? I think this needs to say that the name parameter needs to contain the raw (percent-encoded) name.
Good catch, I believe you're correct.

Related discussion:
text: request message.  The component value is canonicalized by taking the value of the method as a string.  Note that the method name is case- sensitive as per HTTP.  While conventionally standardized method <del> names are uppercase US-ASCII (STD80), no transformation to the input method value's case is performed. </del> <ins> names are uppercase ASCII, no transformation to the input method value's case is performed. </ins> For example, the following request message:
Code change:
Encodes query parameter names to match values, to avoid non-ascii or otherwise problematic values.
In 2.2.8: What if the query parameter contains non-ASCII characters? I think this needs to say that the name parameter needs to contain the raw (percent-encoded) name.
Good catch, I believe you're correct.

Related discussion:
text: according to the "application/x-www-form-urlencoded parsing" section of HTMLURL, resulting in a list of ("nameString", "valueString") tuples.  The REQUIRED "name" parameter of each component identifier <del> contains the "nameString" of a single query parameter as a String value.  Several different named query parameters MAY be included in the covered components.  Single named parameters MAY occur in any order in the covered components. The component value of a single named parameter is calculated by the following process: Parse the "valueString" of the named query parameter defined by the "application/x-www-form-urlencoded parsing" section of HTMLURL, which is the value after percent-encoded octets are decoded Encode the "valueString" using the "percent-encode after encoding" process defined by the "application/x-www-form-urlencoded serializing" section of HTMLURL, which results in an ASCII string This ASCII string is the component value Note that this value does not include any leading "?" characters, equals sign "=", or separating "&" characters.  Named query parameters with an empty "valueString" have an empty string as the component value. </del> <ins> contains the encoded "nameString" of a single query parameter as a String value.  The component value of a single named parameter is the encoded "valueString" of that single query parameter.  Several different named query parameters MAY be included in the covered components.  Single named parameters MAY occur in any order in the covered components, regardless of the order they occur in the query string. The value of the "name" parameter and the component value of a single named parameter are calculated by the following process: Parse the "nameString" or "valueString" of the named query parameter defined by the "application/x-www-form-urlencoded parsing" section of HTMLURL, which is the value after percent- encoded octets are decoded. Encode the "nameString" or "valueString" using the "percent-encode after encoding" process defined by the "application/x-www-form- urlencoded serializing" section of HTMLURL, which results in an ASCII string. Output the ASCII string, Note that the component value does not include any leading "?" characters, equals sign "=", or separating "&" characters.  Named query parameters with an empty "valueString" have an empty string as the component value.  Note that due to inconsistencies in implementations, some query parameter parsing libraries drop such empty values. </ins> If a query parameter is named as a covered component but it does not occur in the query parameters, this MUST cause an error in the