Re: [auth48] AUTH48: RFC-to-be 9458 <draft-ietf-ohai-ohttp-10> for your review

[Martin Thomson <[e-mail]>]

I checked the XML.  The changes to line wrapping make it very hard for me to be certain that the changes are correct.

Some observations:

1. There are quite a few tab characters inserted in the document.  This is probably the result of reformatting.  It's inconsistent though.

2. In the second-level of the IANA media type registrations, the "Macintosh file type code(s)" item has an extra <t> around the text (i.e., "<dd><t>N/A</t></dd>").  This seems unnecessary.

3. There is some weird whitespace preservation thing going on with some of the attributes.  It's probably reformatting-related, but I see `<iref item="Target         Resource"/><`  with nine spaces and a number of similar problems.  The file I submitted doesn't have this problem, so it suggests two lots of reformatting.

4. Our copy supplies fullname attributes for authors in references.  These have been turned into initials+surname, which is unnecessary and removes information that we might use to fix references in future.

Otherwise, I don't see any problems.  Though not seeing doesn't mean that they aren't there, given the level of obfuscation.

On Thu, Oct 19, 2023, at 03:39, Sarah Tarrant wrote:
> Hello Martin,
>
> Thank you for your reply. We have updated our files with the changes 
> you provided. We have one followup comment.
>
> 1) Regarding this comment:
>
>> I have an author for [OHTTP-ANALYSIS], but as a git repository, perhaps your policy is to avoid attribution in general (I'd prefer to include the name if possible).
>
> We updated per “Referencing Web-Based Public Code Repositories (e.g., 
> GitHub)” in the "Web Portion of the Style Guide” 
> (https://www.rfc-editor.org/styleguide/part2/#ref_repo).
>
>
> Updated XML file:
> http://www.rfc-editor.org/authors/rfc9458.xml
>
> Updated output files:
> https://www.rfc-editor.org/authors/rfc9458.html
> https://www.rfc-editor.org/authors/rfc9458.txt
> https://www.rfc-editor.org/authors/rfc9458.pdf
>
> Diff file showing all changes made during AUTH48:
> https://www.rfc-editor.org/authors/rfc9458-auth48diff.html
> https://www.rfc-editor.org/authors/rfc9458-auth48-rfcdiff.html 
> (side-by-side diff)
>
> Comprehensive Diffs:
> https://www.rfc-editor.org/authors/rfc9458-diff.html
> https://www.rfc-editor.org/authors/rfc9458-rfcdiff.html (side-by-side diff)
>
> Note that it may be necessary for you to refresh your browser to view 
> the most recent version. 
>
> For the AUTH48 status of this document, please see:
> https://www.rfc-editor.org/auth48/rfc9458
>
> Thank you,
> RFC Editor/st
>
>> On Oct 16, 2023, at 9:39 PM, Martin Thomson <[e-mail]> wrote:
>> 
>> Bullet 5 in S 4.3
>> 
>> -       Encrypted Request (enc_request).
>> +       Encapsulated Request (enc_request).
>> 
>> S 4.4 uses inconstent comma/paren groupings:
>> 
>> -   context, rctxt, as the HPKE context (context) as follows:
>> +   context (rctxt) as the HPKE context (context) as follows:
>> 
>> S 6.2.3 missed a capitalization:
>> 
>> -   The time at which Encapsulated Request or response messages are sent
>> +   The time at which Encapsulated Request or Response messages are sent
>> 
>> I have an author for [OHTTP-ANALYSIS], but as a git repository, perhaps your policy is to avoid attribution in general (I'd prefer to include the name if possible).
>> 
>> [ODOH-PETS] is marked "Volume 2021, Issue 4, pp. 575-592", but I think that it should be "PoPETS Volume ..." instead.
>> 
>> [UWT] should be "W3C TAG Finding" rather than just "W3C TAG".
>> 
>> Reviewing the XML of this document is essentially impossible.  A whole bunch of line folding was introduced.  I'll need some more time for that.
>> 
>> On Tue, Oct 17, 2023, at 07:54, Sarah Tarrant wrote:
>>> Hello Martin and Murray*,
>>> 
>>> Murray* - please review the last sentence of paragraph 2 in Section 7 
>>> and let us know if you approve. This change is best viewed in this diff 
>>> file: https://www.rfc-editor.org/authors/rfc9458-auth48diff.html
>>> 
>>> Martin, thank you for your reply. We have updated our xml file with the 
>>> changes you provided. All of our questions have been addressed.
>>> 
>>> Regarding this comment:
>>> 
>>>> I don't know how to ensure that links are formatted correctly.  This is an XML-level change that I'm deferring, but I wanted to point out that we're using anchors (https://www.iana.org/assignments/hpke/hpke.xhtml#hpke-aead-ids) where you changed to bare URLs (https://www.iana.org/assignments/hpke in the same place).  I wanted to confirm whether this was deliberate.
>>> 
>>> Yes, this change was deliberate. IANA has asked us to use the bare URLs 
>>> (without anchors) as they are more stable. We use the bare IANA URLs in 
>>> running text and in IANA reference entries. See “Referencing IANA 
>>> Registries” in the “Web Portion of the Style Guide” 
>>> (https://www.rfc-editor.org/styleguide/part2/#ref_iana_reg).
>>> 
>>> Updated XML file:
>>> http://www.rfc-editor.org/authors/rfc9458.xml
>>> 
>>> Updated output files:
>>> https://www.rfc-editor.org/authors/rfc9458.html
>>> https://www.rfc-editor.org/authors/rfc9458.txt
>>> https://www.rfc-editor.org/authors/rfc9458.pdf
>>> 
>>> Diff file showing all changes made during AUTH48:
>>> https://www.rfc-editor.org/authors/rfc9458-auth48diff.html
>>> 
>>> Comprehensive Diffs:
>>> https://www.rfc-editor.org/authors/rfc9458-diff.html
>>> https://www.rfc-editor.org/authors/rfc9458-rfcdiff.html (side-by-side diff)
>>> 
>>> Note that it may be necessary for you to refresh your browser to view 
>>> the most recent version. 
>>> 
>>> For the AUTH48 status of this document, please see:
>>> https://www.rfc-editor.org/auth48/rfc9458
>>> 
>>> Thank you,
>>> RFC Editor/st
>>> 
>>> 
>>>> On Oct 15, 2023, at 5:56 PM, Martin Thomson <[e-mail]> wrote:
>>>> 
>>>> Hi Sandy,
>>>> 
>>>> These links should not be displayed with any decoration.  They don't appear to be as far as I can see, in any of the styles we presently use.  Is there a version of this document that I'm unaware of and that is being styled differently?
>>>> 
>>>> The fact that xml2rfc generates multiple index entries is a bug: https://github.com/ietf-tools/xml2rfc/issues/988
>>>> 
>>>> The use of cref is automated in our authoring tools and would be difficult to apply selectively.
>>>> 
>>>> Cheers,
>>>> Martin
>>>> 
>>>> On Sat, Oct 14, 2023, at 04:39, Sandy Ginoza wrote:
>>>>> Authors,
>>>>> 
>>>>> The goal of links and an index in a document is to help the reader 
>>>>> navigate that document. This document includes links that are not 
>>>>> visually differentiable from the surrounding text (except upon hover), 
>>>>> so it is difficult for the reader to discover them. 
>>>>> 
>>>>> However, once the links are shown with color, their current 
>>>>> overabundance can be distracting and confusing to the reader. In 
>>>>> addition, the large number of index entries makes it difficult for the 
>>>>> reader to determine where they should look for information. For 
>>>>> example, there are 91 entries for Oblivious Gateway Resource, and many 
>>>>> instances appear within the same paragraph and subsequent paragraphs 
>>>>> (e.g., "Section 6, Paragraph 8; Section 6, Paragraph 8; Section 6.2, 
>>>>> Paragraph 1; Section 6.2, Paragraph 1"). Similarly, there are 150 
>>>>> entries for Client and 52 more for Clients. For some of the terms, they 
>>>>> are linked in close proximity, and some are even linked within their 
>>>>> own definitions. We recommend trimming both links and index entries 
>>>>> down to instances that aid the reader. In addition to having a more 
>>>>> useful index, link color will no longer be distracting. 
>>>>> 
>>>>> Thanks,
>>>>> Sandy 
>>>>> 
>>>>> 
>>>>>> On Oct 9, 2023, at 6:37 PM, Martin Thomson <[e-mail]> wrote:
>>>>>> 
>>>>>> Hi,
>>>>>> 
>>>>>> Thanks for sending this over.
>>>>>> 
>>>>>> https://github.com/ietf-wg-ohai/oblivious-http/pull/289 is where we're tracking changes for our own review.  I've started to port your changes over there and have attached an updated XML file that should match yours (mostly).
>>>>>> 
>>>>>> I have only reviewed the text diff at this stage, so things like references will be very different in this version of the XML.  I plan to go over XML changes once this round of edits is sorted out.
>>>>>> 
>>>>>> Responses inline below, but first I have a few things to point out.
>>>>>> 
>>>>>> I don't know how to ensure that links are formatted correctly.  This is an XML-level change that I'm deferring, but I wanted to point out that we're using anchors (https://www.iana.org/assignments/hpke/hpke.xhtml#hpke-aead-ids) where you changed to bare URLs (https://www.iana.org/assignments/hpke in the same place).  I wanted to confirm whether this was deliberate.
>>>>>> 
>>>>>> Chris and I have rejected some changes:
>>>>>> 
>>>>>> S5:
>>>>>> -   request, which the Client makes to the Target Resource, diverges from
>>>>>> +   request, which the Clients make to the Target Resource, diverges from
>>>>>> 
>>>>>> (There is only one capital-C Oblivious HTTP Client as the subject of this statement.  This might have been confused as the preceding statement talked about that Client being an HTTP client in two separate contexts.)
>>>>>> 
>>>>>> S5.1:
>>>>>> -   This encapsulation does not permit progressive processing of
>>>>>> +   This encapsulation does not permit the progressive processing of
>>>>>> 
>>>>>> In IANA considerations, the media type registrations are extremely long if a compact list is not used.  I've made tweaks to layout based on your changes that should improve things like line wrapping, but I think that this is better left in a compact form.
>>>>>> 
>>>>>> There are also a few other minor edits for consistency, as noted below.  These relate to capitalization (client->Client in particular) and more use of parentheses in algorithms.
>>>>>> 
>>>>>> Cheers,
>>>>>> Martin
>>>>>> 
>>>>>> On Sat, Oct 7, 2023, at 09:06, [e-mail] wrote:
>>>>>>> 1) <!--[rfced] Note that the updates that were approved by the AD in
>>>>>>> versions -09 and -10 have been incorporated. Please review and
>>>>>>> let us know if any further updates are needed.
>>>>>> 
>>>>>> I can confirm that the changes are in place.
>>>>>> 
>>>>>>> 2) <!-- [rfced] Please insert any keywords (beyond those that appear in the
>>>>>>> title) for use on https://www.rfc-editor.org/search. 
>>>>>>> -->
>>>>>> 
>>>>>> Added privacy, proxy, partitioning, tunnel
>>>>>> 
>>>>>>> 3) <!-- [rfced] The SVG figures in Sections 2 and 6.5.2 have width or height
>>>>>>> specified, which will make the artwork not scale. 
>>>>>> 
>>>>>> Yes, this is fine.
>>>>>> 
>>>>>>> 4) <!-- [rfced] Please review the following questions related to the use
>>>>>>> of "<tt>".
>>>>>>> 
>>>>>>> a) In the html and pdf outputs, the text enclosed in <tt> is
>>>>>>> output in fixed-width font. In the txt output, there are no
>>>>>>> changes to the font, and the quotation marks have been
>>>>>>> removed. Please review carefully and let us know if the output is
>>>>>>> acceptable or if any updates are needed.
>>>>>> 
>>>>>> This is acceptable.  We use this for function names and HTTP field names, which are generally able to be distinguished based on context and the use of CapTaliZaTiOn.
>>>>>> 
>>>>>>> b) Should any of the following terms be formatted with <tt>
>>>>>>> for consistency? 
>>>>>>> c) We notice that the "Date" and "Vary" header fields are enclosed 
>>>>>>> with <tt>.  Should any of the other header field names be enclosed 
>>>>>>> with <tt> for consistency?
>>>>>> 
>>>>>> Yes, for all of these.
>>>>>> 
>>>>>>> d) Is it intentional for some terms to be enclosed with both <tt>
>>>>>>> and quotation marks? For example: "message/ohttp-req" and 
>>>>>>> "message/ohttp-res". Please let us know if any updates are needed.
>>>>>> 
>>>>>> This was deliberate.  Quotes are safe to use with media types and it is my belief that these require this additional marking for documents in text format as they lack the case distinctions of the former.  I'm not firm on this though, the quotes could probably be dropped (what I really want is something to stop these from wrapping unnecessarily).
>>>>>> 
>>>>>>> 5) <!-- [rfced] Please review the "type" attribute of each sourcecode
>>>>>>> element in the XML file to ensure correctness.
>>>>>> 
>>>>>> Verified.  I've marked some as pseudocode.  However, you note two instance of tls-syntax, where I was able to spot only one.
>>>>>> 
>>>>>>> 6) <!--[rfced] Section 3.1. We updated the "HPKE KDF Identifiers"
>>>>>>> registry to the "HPKE KEM Identifiers" registry since it applies
>>>>>>> to the "HPKE KEM ID". Please let us know if this is not correct.
>>>>>>> 
>>>>>>> Original:
>>>>>>> HPKE KEM ID: 
>>>>>>>  A 16 bit value that identifies the Key Encapsulation Method
>>>>>>>  (KEM) used for the identified key as defined in Section 7.1 
>>>>>>>  of [HPKE] or the HPKE KDF IANA registry.
>>>>>>> 
>>>>>>> Current:
>>>>>>> HPKE KEM ID:
>>>>>>>  A 16-bit value that identifies the KEM used for the identified key
>>>>>>>  as defined in Section 7.1 of [HPKE] or the "HPKE KEM Identifiers"
>>>>>>>  IANA registry <https://www.iana.org/assignments/hpke>.
>>>>>>> -->
>>>>>> 
>>>>>> I have this using <eref, which renders using parentheses rather than angle brackets.  Otherwise, I think we're good.  I think that this is a change that was made in our repository that didn't make it into -10.
>>>>>> 
>>>>>>> 7) <!--[rfced] Section 4.3. May we add parentheses to this bullet point
>>>>>>> as follows for easier readability? Please let us know your
>>>>>>> preference.
>>>>>>> 
>>>>>>> Original:
>>>>>>> *  a combination of KDF, identified by kdf_id, and AEAD, identified
>>>>>>>    by aead_id, that the Client selects from those in the key
>>>>>>>    configuration.
>>>>>>> 
>>>>>>> Perhaps:
>>>>>>> *  a combination of KDF (identified by kdf_id) and AEAD (identified
>>>>>>>    by aead_id) that the Client selects from those in the key
>>>>>>>    configuration.
>>>>>>> -->
>>>>>> 
>>>>>> There is a consistency issue here.  Other bullets used commas.  I think that we can lean on parentheses more if we're careful.
>>>>>> 
>>>>>>> 8) <!-- [rfced] Please review whether any of the notes in this document
>>>>>>> should be in the <aside> element.
>>>>>> 
>>>>>> It's hard to answer this question without an example.  I could find a couple of places where it might work, but those were in lists, where I'm less confident about what that might render as.  I don't see any places where this would help.
>>>>>> 
>>>>>>> 9) 
>>>>>>> Perhaps:
>>>>>>> 2.  Builds info by concatenating the ASCII-encoded string "message/
>>>>>>>     bhttp request"; a zero-byte; key_id as an 8-bit integer; and
>>>>>>>     kem_id, kdf_id, and aead_id as three 16-bit integers.
>>>>>>> -->
>>>>>> 
>>>>>> Semi-colons can act as comma's big sister here, sure.
>>>>>> 
>>>>>>> 10) 
>>>>>>> Perhaps:
>>>>>>> 6.  Encrypt response, passing the AEAD function Seal with the values
>>>>>>>     of aead_key, aead_nonce, an empty aad, and a pt input of response,
>>>>>>>     which yields ct.
>>>>>> 
>>>>>> Maybe instead:
>>>>>> 
>>>>>> Encrypt `response` by passing the AEAD function Seal the values of
>>>>>> `aead_key`, `aead_nonce`, an empty `aad`, and a `pt` input of
>>>>>> `response`. This yields `ct`.
>>>>>> 
>>>>>> 
>>>>>>> 11) 
>>>>>>> Current:
>>>>>>> The request, which the Clients make to the Target Resource,
>>>>>>> diverges from typical HTTP assumptions about the use of a 
>>>>>>> connection (see Section 3.3 of [HTTP]) in that the request 
>>>>>>> and response are encrypted rather than sent over a connection.
>>>>>>> -->
>>>>>> 
>>>>>> I've gone with:
>>>>>> The request, which the Client makes to the Target Resource, diverges
>>>>>> 
>>>>>> 
>>>>>>> 12) 
>>>>>>> Current:
>>>>>>> The problem type [PROBLEM] of "https://iana.org/assignments/http-
>>>>>>> problem-types#ohttp-key" is defined in this section. 
>>>>>> 
>>>>>> Sure.
>>>>>> 
>>>>>>> 13)
>>>>>>> Perhaps:
>>>>>>> This ensures that Oblivious Gateway Resources are not 
>>>>>>> misused to forward traffic to arbitrary Target 
>>>>>>> Resources. 
>>>>>> 
>>>>>> Yes, good.
>>>>>> 
>>>>>>> 14)
>>>>>>> Perhaps:
>>>>>>> While TLS might be
>>>>>>> intercepted successfully, intercepted middlebox devices might not
>>>>>>> receive updates that would allow Oblivious HTTP to be correctly
>>>>>>> identified using the media types defined in Sections 9.2 and 9.3.
>>>>>> 
>>>>>> This is a middlebox that exist to intercept, so I believe "interception middlebox devices" is correct.
>>>>>> 
>>>>>>> 15) <!-- [rfced] Some author comments are present in the XML. 
>>>>>> 
>>>>>> Yes, this exist to aid us in drafting, specifically to help regenerate examples when things change.  We don't need (or want) those to be published.
>>>>>> 
>>>>>>> 16) <!-- [rfced] Terminology
>>>>>>> 
>>>>>>> a) Throughout the text, the following terminology appears to be capitalized 
>>>>>>> inconsistently. Please review these occurrences and let us know if/how they
>>>>>>> may be made consistent.  
>>>>>>> 
>>>>>>> client vs. Client:
>>>>>>>  Client
>>>>>>>  client 
>>>>>>>  HTTP client 
>>>>>>>  Oblivious HTTP Client
>>>>>>>  per-Client
>>>>>> 
>>>>>> This is tricky, but here are the rules we're following:
>>>>>> 
>>>>>> 1. HTTP uses "client", we use "HTTP client" when we refer specifically to something that is exclusively performing HTTP functions.  This was consistent.
>>>>>> 
>>>>>> 2. Oblivious HTTP uses "Client" when referring to the rule it defines (which is mostly just an HTTP client) and so that is capitalized everywhere.  (That is the first, fourth, and fifth items on this list.)
>>>>>> 
>>>>>> 3. Some of the introductory text talks generically about clients, which are things that make requests of servers.  There, because it is talking about a generic concept, these are just "client" without qualification..
>>>>>> 
>>>>>>> 
>>>>>>> key identifier vs. Key Identifier vs. key ID
>>>>>>>  key identifier (9) 
>>>>>>>  Key Identifier (5) 
>>>>>>>  key ID (1)
>>>>>> 
>>>>>> The capitalized form refers exclusively to a field as encoded.  Otherwise, we're using lowercase.
>>>>>> 
>>>>>>> nonce vs. Nonce vs. Nonce field
>>>>>>>  Nonce (3) 
>>>>>>>  nonce (29)
>>>>>>>  Nonce field (1)
>>>>>> 
>>>>>> Again, the capitalized form refers exclusively to the field in the message.  I've tweaked the text to make this clearer.
>>>>>> 
>>>>>>> plaintext Request (1) vs. 
>>>>>>> plaintext request (1) vs. 
>>>>>>> plaintext Response (1) vs.
>>>>>>> plaintext request and response (1)
>>>>>> 
>>>>>> This was indeed correct, because the odd capitalization was referring to structures in messages as shown in diagrams, with case that matched.  I've tweaked this a little to make that clearer by re-captioning the message and using matching words to highlight the parallelism.
>>>>>> 
>>>>>> 
>>>>>>> b) We updated the following terms to the latter forms shown below for
>>>>>>> consistency. Please let us know of any concerns.
>>>>>>> 
>>>>>>> encapsulated KEM shared secret -> Encapsulated KEM Shared Secret (1)
>>>>>> 
>>>>>> Please revert, RFC 9180 uses "enc is an encapsulated KEM shared secret".
>>>>>> 
>>>>>>> encapsulated request -> Encapsulated Request (2)
>>>>>> 
>>>>>> Great.
>>>>>> 
>>>>>>> encapsulated response -> Encapsulated Response (5)
>>>>>>> Encapsulated Requests and responses -> Encapsulated Requests and Responses (1)
>>>>>> 
>>>>>> Also good.
>>>>>> 
>>>>>>> b) Please confirm if the case for these terms is okay as is 
>>>>>>> or if you would like to make any changes.
>>>>>>> 
>>>>>>> Client request (both words are lowercase in RFC 9110)
>>>>>> 
>>>>>> The cases I see are specific on the first (this is an OHTTP Client) and non-specific on the second (this is just a request in the abstract).  That's probably sloppy, but I see no need to fix that.
>>>>>> 
>>>>>>> encrypted request (lowercase in all RFCs)
>>>>>>> encrypted requests and responses 
>>>>>> 
>>>>>> In some cases, those needed to be Encapsulated Request(s), which I've corrected.
>>>>>> 
>>>>>>> HTTP request (lowercase in RFC 9110)
>>>>>>> HTTP requests and responses 
>>>>>>> HTTP request-response
>>>>>> 
>>>>>> This is correct.  When talking about HTTP, we use HTTP lowercasing.
>>>>>> 
>>>>>>> 17) <!-- [rfced] Please review the "Inclusive Language" portion of the online 
>>>>>>> Style Guide <https://www.rfc-editor.org/styleguide/part2/#inclusive_language>
>>>>>>> and let us know if any changes are needed.
>>>>>> 
>>>>>> Acknowledged and validated.  I couldn't see anything either.
>>>>>> 
>>>>>>> The files are available here:
>>>>>>> https://www.rfc-editor.org/authors/rfc9458.xml
>>>>>>> https://www.rfc-editor.org/authors/rfc9458.html
>>>>>>> https://www.rfc-editor.org/authors/rfc9458.pdf
>>>>>>> https://www.rfc-editor.org/authors/rfc9458.txt
>>>>>> <draft-ietf-ohai-ohttp.xml>