Mercurial > hg > ietf
changeset 15:4f6b93a40ca1
merge
| author | Henry S. Thompson <ht@inf.ed.ac.uk> |
|---|---|
| date | Thu, 01 May 2025 17:03:03 +0100 |
| parents | 9f2a1fab49d7 (current diff) 38c8261aebfc (diff) |
| children | f2a7c10fbdd7 |
| files | |
| diffstat | 2 files changed, 233 insertions(+), 210 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/jwt_review.txt Thu May 01 17:03:03 2025 +0100 @@ -0,0 +1,233 @@ +*Summary* + +*Minor points* +[this actually borders on the 'substantive', see the discussion under +Appendix B.] + + 4.2.1 + This bullet + + "JSON-encode the array, producing [a] UTF-8 string" + + looks simple, but ended up confusing me for over an hour. + + For the rest of things to work, you must mean "Serialize the array + to the corresponding utf-8-encoded byte sequence", but that's not + exactly trivial in the JSON-native context you've adopted in this + document. + + That is, at first I thought you should just include one extra + step in the Disclosure construction, example, namely what the + UTF-8 (byte) string looks like as (what RFC8259 calls) "UTF-8 + encoded JSON text", immediately after the array creation + display: + + ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "Möbius"] (1) + + "[\"_26bc4LT-ac6q2KI6cBW5es\", \"family_name\", \"M\u00c3\u00b6bius\"]" (2) + + but that's really ugly and would be more likely to confuse than clarify. + + Note that in only the first 64bitURL Disclosure + samples that you offer decodes to my guess (2)! And indeed + what they _do_ decode to, that is + + '["_26bc4LT-ac6q2KI6cBW5es", "family_name", "Möbius"]' # 4d c3 b6 62 69 75 73 + + '["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M\\u00f6bius"]' + + respectively, are non-trivially distinct, as in both Python and + node.js these, as strings, correspond to two _different_ + byte-sequences (the second is 4 bytes longer than the first and, + if both are decoded as utf-8, to 5 more characters). It's true + that they are both valid JSON texts, per RFC8259, but you have to + apply a JSON parser to them to get to indistinguishable JSON objects. + + Apologies for this lengthy attempt to show where I think you've + gotten in to trouble by specifying _algorithms_ in informal + english, while more-or-less assuming, I'm guessing, some library + functions in whatever language you're used to using. + + To address this problem, since you use "JSON-encode" a number of + times in later sections, I would _strongly recommend_ that you + + a) Add the following to section 1.2, immediately after the + definition of *base64url*: + + *JSON-encode* denotes the conversion of a JSON object to + "JSON text" and encoding that text in UTF-8, as defined in + RFC 8529. That is, mapping a JSON object to a UTF-8 byte + sequence which when decoded and parsed will reconstruct an + object indistinguishable from the original. + + b) Replace that problematic bullet, and the next, with + + * JSON-encode the array, producing a UTF-8 encoded byte sequence. + + * base64url-encode the resulting byte sequence. The resulting + string is the Disclosure. + + c) Be careful never to use "string" when "(UTF-8) byte sequence" + is meant, starting in 4.2.2 with + + The Disclosure string is created by JSON-encoding this array + and base64url-encoding the resulting byte sequence as + described in Section 4.2.1 + + d) In the second media type registration in 12.2 + "represented as a JSON Object" -> + 'represented as UTF-8 encoded "JSON text" as defined in RFC 8529' + + e) Include RFC 8529 in 13.1 + + Appendix B. + + The above problem resurfaces here, with confusion between three + possible interpretations, in the terms of RFC 8529, of what is + displayed: + + * a JSON object, that is, structured data composed of + instances of the six primitive types which JSON can + represent. It is _not_ to be understood as string, byte + sequence or file contents; + + * a possible JSON text for some JSON object. + + * a UTF-8 encoding of some JSON text, aka a "JSON encoding". + + The first figure is labelled as a JSON object, which is OK. + + But it is indistinguishable from one of the possible + JSON texts corresponding to that object. + + The next figure purports to present two alternative "JSON + encodings", the second of which is problematic. + + Its first line appears indistinguishable from that shown for the + JSON object in the preceding figure, but is in fact different. + + In the first figure, construed as a "JSON text", the o-umlaut + glyph denotes a single Unicode character in a six-character + representation of a six-character object member string value. + + However in the second figure, second alternative, the o-umlaut + corresponds to a _two_-byte UTF-8 sub-part of the JSON encoding of + that value as a seven-byte UTF-8 byte sequence, either in some + internal representation or an external stream or file. + + What to do? First, add something similar to + https://www.ietf.org/archive/id/draft-bray-unichars-14.html#name-notation + Then, whenever presenting JSON, always indicate whether what is + being shown is JSON text or JSON-encoded text (i.e. UTF-8 encoded + JSON text). In JSON text, always include a version using the + U+xxxx notation whenever the underlying string contains non-ASCII + characters. In JSON-encoded text, _always_ use the %xnn notation + for non-ASCII characters. + + Some examples of a possible way of indicating JSON text and + JSON-encoded text, from section 4.2.1 + + Replace the first figure with these two: + + _________________________________________________________ + |*JT* | + | | + | ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "Möbius"] | + | ^ | + | | | + | X+00F6 | + | | + |________________________________________________________| + + _______________________________________________________________ + |*J-ET* | + | | + | ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M%xc3%xb6bius"] | + | | + |_______________________________________________________________| + + and the first bullet of the three alternatives which follow with + + * A different way to encode the unicode o-umlaut: + + ______________________________________________________________ + |*JT* | + | | + | ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M\x00f6bius"] | + | | + |_____________________________________________________________| + + ______________________________________________________________ + |*J-ET* | + | | + | ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M\x00f6bius"] | + | | + |_____________________________________________________________| + + WyJfMjZiYzRMVC1hYzZxMktJNmNCVzVlcyIsICJmYW1pbHlfbmFtZSIsICJNX + HUwMGY2Yml1cyJd + + And throughout the examples in Appendices A and B, label the initial + figure with *JT* and the 'Content' boxes with *J-ET*. You don't + need to gloss every Chinese/German string with their U+xxxx version, + but saying something at the top of A that where non-ASCII characters + appear in any of the initial examples that the actual Unicode + character is what is meant. + + The Appendix B example then looks like this, along with some small + changes to the text: + + Usually, JSON-based formats transport claim values as simple + properties of a JSON object such as this: + + _________________________________________ + |*JT* | + | | + | ... | + | "family_name": "Möbius", | + | "address": { | + | "street_address": "Schulstr. 12", | + | "locality": "Schulpforta" | + | } | + | ... | + |________________________________________| + + + +*Nits* + + 4. "(for those who celebrate)" will be anywhere from obscure to + confusing for many readers from many cultures -- best to remove it. + + 4.2.1. "an UTF-8" -> "a UTF-8" [overtaken by 4.2.1 above] + + "However, the digest is calculated over the respective + base64url-encoded value itself, which effectively signs" + + -> + + "Because the digest is calculated over the respective + base64url-encoded value itself, this effectively signs" + + 4.3.1. I'd recommend + "The bytes of the digest MUST" -> "The bytes of the sd_hash value MUST" + + 6. I have decoded a few of the Disclosures and they're fine, but you + might want to ask a friendly 3rd party to double-check all the + Disclosures and digests, at least here and in Appendix A. + + 9. "Security considerations in this section help achieve the + following properties:" + + This confused me for a while. I think what you mean to say here + is something like + + This spec aims to provide two security guarantees: + + *Selective Disclosure*: ... + + *Integrity*: ... + + The following sub-sections show how the various aspects of the + design presented here combine to achieve this. +
--- a/twt_review.txt Thu May 01 13:11:58 2025 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,210 +0,0 @@ -*Summary* - -*Minor points* -[this actually borders on the 'substantive', see the discussion under -Appendix B. - - 4.2.1 - This bullet - - "JSON-encode the array, producing [a] UTF-8 string" - - looks simple, but ended up confusing me for over an hour. - - For the rest of things to work, you must mean "Serialize the array - to the corresponding utf-8-encoded byte sequence", but that's not - exactly trivial in the JSON-native context you've adopted in this - document. - - That is, at first I thought you should just include one extra - step in the Disclosure construction, example, namely what the - UTF-8 (byte) string looks like as (what RFC8259 calls) "UTF-8 - encoded JSON text", immediately after the array creation - display: - - ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "Möbius"] (1) - - "[\"_26bc4LT-ac6q2KI6cBW5es\", \"family_name\", \"M\u00c3\u00b6bius\"]" (2) - - but that's really ugly and would be more likely to confuse than clarify. - - Note that in only the first 64bitURL Disclosure - samples that you offer decodes to my guess (2)! And indeed - what they _do_ decode to, that is - - '["_26bc4LT-ac6q2KI6cBW5es", "family_name", "Möbius"]' # 4d c3 b6 62 69 75 73 - - '["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M\\u00f6bius"]' - - respectively, are non-trivially distinct, as in both Python and - node.js these, as strings, correspond to two _different_ - byte-sequences (the second is 4 bytes longer than the first and, - if both are decoded as utf-8, to 5 more characters). It's true - that they are both valid JSON texts, per RFC8259, but you have to - apply a JSON parser to them to get to indistinguishable JSON objects. - - Apologies for this lengthy attempt to show where I think you've - gotten in to trouble by specifying _algorithms_ in informal - english, while more-or-less assuming, I'm guessing, some library - functions in whatever language you're used to using. - - To address this problem, since you use "JSON-encode" a number of - times in later sections, I would _strongly recommend_ that you - - a) Add the following to section 1.2, immediately after the - definition of *base64url*: - - *JSON-encode* denotes the conversion of a JSON object to - "JSON text" and encoding that text in UTF-8, as defined in - RFC 8529. That is, mapping a JSON object to a UTF-8 byte - sequence which when decoded and parsed will reconstruct an - object indistinguishable from the original. - - b) Replace that problematic bullet, and the next, with - - * JSON-encode the array, producing a UTF-8 encoded byte sequence. - - * base64url-encode the resulting byte sequence. The resulting - string is the Disclosure. - - c) Be careful never to use "string" when "(UTF-8) byte sequence" - is meant, starting in 4.2.2 with - - The Disclosure string is created by JSON-encoding this array - and base64url-encoding the resulting byte sequence as - described in Section 4.2.1 - - d) In the second media type registration in 12.2 - "represented as a JSON Object" -> - 'represented as UTF-8 encoded "JSON text" as defined in RFC 8529' - - e) Include RFC 8529 in 13.1 - - Appendix B. - - The above problem resurfaces here, with confusion between three - possible interpretations, in the terms of RFC 8529, of what is - displayed: - - * a JSON object, that is, structured data composed of - instances of the six primitive types which JSON can - represent. It is _not_ to be understood as string, byte - sequence or file contents; - - * a possible JSON text for some JSON object. - - * a UTF-8 encoding of some JSON text, aka a "JSON encoding". - - The first figure is labelled as a JSON object, which is OK. - - But it is indistinguishable from one of the possible - JSON texts corresponding to that object. - - The next figure purports to present two alternative "JSON - encodings", the second of which is problematic. - - Its first line appears indistinguishable from that shown for the - JSON object in the preceding figure, but is in fact different. - - In the first figure, construed as a "JSON text", the o-umlaut - glyph denotes a single Unicode character in a six-character - representation of a six-character object member string value. - - However in the second figure, second alternative, the o-umlaut - corresponds to a _two_-byte UTF-8 sub-part of the JSON encoding of - that value as a seven-byte UTF-8 byte sequence, either in some - internal representation or an external stream or file. - - What to do? First, add something similar to - https://www.ietf.org/archive/id/draft-bray-unichars-14.html#name-notation - Then, whenever presenting JSON, always indicate whether what is - being shown is JSON text or JSON-encoded text (i.e. UTF-8 encoded - JSON text). In JSON text, always include a version using the - U+xxxx notation whenever the underlying string contains non-ASCII - characters. In JSON-encoded text, _always_ use the %xnn notation - for non-ASCII characters. - - Some examples of a possible way of indicating JSON text and - JSON-encoded text, from section 4.2.1 - - Replace the first figure with these two: - - _________________________________________________________ - |*JT* | - | | - | ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "Möbius"] | - | ^ | - | | | - | X+00F6 | - | | - |________________________________________________________| - - _______________________________________________________________ - |*J-ET* | - | | - | ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M%xc3%xb6bius"] | - | | - |_______________________________________________________________| - - and the first bullet of the three alternatives which follow with - - * A different way to encode the unicode o-umlaut: - - ______________________________________________________________ - |*JT* | - | | - | ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M\x00f6bius"] | - | | - |_____________________________________________________________| - - ______________________________________________________________ - |*J-ET* | - | | - | ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M\x00f6bius"] | - | | - |_____________________________________________________________| - - WyJfMjZiYzRMVC1hYzZxMktJNmNCVzVlcyIsICJmYW1pbHlfbmFtZSIsICJNX - HUwMGY2Yml1cyJd - - And throughout the examples in Appendix A, label the initial figure - with *JT* and the 'Content' boxes with *J-ET*. You don't need to - gloss every Chinese/German strings with their U+xxxx version. - -*Nits* - - 4. "(for those who celebrate)" will be anywhere from obscure to - confusing for many readers from many cultures -- best to remove it. - - 4.2.1. "an UTF-8" -> "a UTF-8" [overtaken by 4.2.1 above] - - "However, the digest is calculated over the respective - base64url-encoded value itself, which effectively signs" - - -> - - "Because the digest is calculated over the respective - base64url-encoded value itself, this effectively signs" - - 4.3.1. I'd recommend - "The bytes of the digest MUST" -> "The bytes of the sd_hash value MUST" - - 6. I have decoded a few of the Disclosures and they're fine, but you - might want to ask a friendly 3rd party to double-check all the - Disclosures and digests, at least here and in Appendix A. - - 9. "Security considerations in this section help achieve the - following properties:" - - This confused me for a while. I think what you mean to say here - is something like - - This spec aims to provide two security guarantees: - - *Selective Disclosure*: ... - - *Integrity*: ... - - The following sub-sections show how the various aspects of the - design presented here combine to achieve this. -