Mercurial > hg > ietf

comparison jwt_review.txt @ 13:38c8261aebfc

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
renamed, more ascii art
author Henry S. Thompson <ht@inf.ed.ac.uk>
date Thu, 01 May 2025 16:50:41 +0100
parents twt_review.txt@9cb53ac26388
children f2a7c10fbdd7
comparison
equal deleted inserted replaced
12:9cb53ac26388 13:38c8261aebfc
1 *Summary*
2
3 *Minor points*
4 [this actually borders on the 'substantive', see the discussion under
5 Appendix B.]
6
7 4.2.1
8 This bullet
9
10 "JSON-encode the array, producing [a] UTF-8 string"
11
12 looks simple, but ended up confusing me for over an hour.
13
14 For the rest of things to work, you must mean "Serialize the array
15 to the corresponding utf-8-encoded byte sequence", but that's not
16 exactly trivial in the JSON-native context you've adopted in this
17 document.
18
19 That is, at first I thought you should just include one extra
20 step in the Disclosure construction, example, namely what the
21 UTF-8 (byte) string looks like as (what RFC8259 calls) "UTF-8
22 encoded JSON text", immediately after the array creation
23 display:
24
25 ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "Möbius"] (1)
26
27 "[\"_26bc4LT-ac6q2KI6cBW5es\", \"family_name\", \"M\u00c3\u00b6bius\"]" (2)
28
29 but that's really ugly and would be more likely to confuse than clarify.
30
31 Note that in only the first 64bitURL Disclosure
32 samples that you offer decodes to my guess (2)! And indeed
33 what they _do_ decode to, that is
34
35 '["_26bc4LT-ac6q2KI6cBW5es", "family_name", "Möbius"]' # 4d c3 b6 62 69 75 73
36
37 '["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M\\u00f6bius"]'
38
39 respectively, are non-trivially distinct, as in both Python and
40 node.js these, as strings, correspond to two _different_
41 byte-sequences (the second is 4 bytes longer than the first and,
42 if both are decoded as utf-8, to 5 more characters). It's true
43 that they are both valid JSON texts, per RFC8259, but you have to
44 apply a JSON parser to them to get to indistinguishable JSON objects.
45
46 Apologies for this lengthy attempt to show where I think you've
47 gotten in to trouble by specifying _algorithms_ in informal
48 english, while more-or-less assuming, I'm guessing, some library
49 functions in whatever language you're used to using.
50
51 To address this problem, since you use "JSON-encode" a number of
52 times in later sections, I would _strongly recommend_ that you
53
54 a) Add the following to section 1.2, immediately after the
55 definition of *base64url*:
56
57 *JSON-encode* denotes the conversion of a JSON object to
58 "JSON text" and encoding that text in UTF-8, as defined in
59 RFC 8529. That is, mapping a JSON object to a UTF-8 byte
60 sequence which when decoded and parsed will reconstruct an
61 object indistinguishable from the original.
62
63 b) Replace that problematic bullet, and the next, with
64
65 * JSON-encode the array, producing a UTF-8 encoded byte sequence.
66
67 * base64url-encode the resulting byte sequence. The resulting
68 string is the Disclosure.
69
70 c) Be careful never to use "string" when "(UTF-8) byte sequence"
71 is meant, starting in 4.2.2 with
72
73 The Disclosure string is created by JSON-encoding this array
74 and base64url-encoding the resulting byte sequence as
75 described in Section 4.2.1
76
77 d) In the second media type registration in 12.2
78 "represented as a JSON Object" ->
79 'represented as UTF-8 encoded "JSON text" as defined in RFC 8529'
80
81 e) Include RFC 8529 in 13.1
82
83 Appendix B.
84
85 The above problem resurfaces here, with confusion between three
86 possible interpretations, in the terms of RFC 8529, of what is
87 displayed:
88
89 * a JSON object, that is, structured data composed of
90 instances of the six primitive types which JSON can
91 represent. It is _not_ to be understood as string, byte
92 sequence or file contents;
93
94 * a possible JSON text for some JSON object.
95
96 * a UTF-8 encoding of some JSON text, aka a "JSON encoding".
97
98 The first figure is labelled as a JSON object, which is OK.
99
100 But it is indistinguishable from one of the possible
101 JSON texts corresponding to that object.
102
103 The next figure purports to present two alternative "JSON
104 encodings", the second of which is problematic.
105
106 Its first line appears indistinguishable from that shown for the
107 JSON object in the preceding figure, but is in fact different.
108
109 In the first figure, construed as a "JSON text", the o-umlaut
110 glyph denotes a single Unicode character in a six-character
111 representation of a six-character object member string value.
112
113 However in the second figure, second alternative, the o-umlaut
114 corresponds to a _two_-byte UTF-8 sub-part of the JSON encoding of
115 that value as a seven-byte UTF-8 byte sequence, either in some
116 internal representation or an external stream or file.
117
118 What to do? First, add something similar to
119 https://www.ietf.org/archive/id/draft-bray-unichars-14.html#name-notation
120 Then, whenever presenting JSON, always indicate whether what is
121 being shown is JSON text or JSON-encoded text (i.e. UTF-8 encoded
122 JSON text). In JSON text, always include a version using the
123 U+xxxx notation whenever the underlying string contains non-ASCII
124 characters. In JSON-encoded text, _always_ use the %xnn notation
125 for non-ASCII characters.
126
127 Some examples of a possible way of indicating JSON text and
128 JSON-encoded text, from section 4.2.1
129
130 Replace the first figure with these two:
131
132 _________________________________________________________
133 |*JT* |
134 | |
135 | ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "Möbius"] |
136 | ^ |
137 | | |
138 | X+00F6 |
139 | |
140 |________________________________________________________|
141
142 _______________________________________________________________
143 |*J-ET* |
144 | |
145 | ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M%xc3%xb6bius"] |
146 | |
147 |_______________________________________________________________|
148
149 and the first bullet of the three alternatives which follow with
150
151 * A different way to encode the unicode o-umlaut:
152
153 ______________________________________________________________
154 |*JT* |
155 | |
156 | ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M\x00f6bius"] |
157 | |
158 |_____________________________________________________________|
159
160 ______________________________________________________________
161 |*J-ET* |
162 | |
163 | ["_26bc4LT-ac6q2KI6cBW5es", "family_name", "M\x00f6bius"] |
164 | |
165 |_____________________________________________________________|
166
167 WyJfMjZiYzRMVC1hYzZxMktJNmNCVzVlcyIsICJmYW1pbHlfbmFtZSIsICJNX
168 HUwMGY2Yml1cyJd
169
170 And throughout the examples in Appendices A and B, label the initial
171 figure with *JT* and the 'Content' boxes with *J-ET*. You don't
172 need to gloss every Chinese/German string with their U+xxxx version,
173 but saying something at the top of A that where non-ASCII characters
174 appear in any of the initial examples that the actual Unicode
175 character is what is meant.
176
177 The Appendix B example then looks like this, along with some small
178 changes to the text:
179
180 Usually, JSON-based formats transport claim values as simple
181 properties of a JSON object such as this:
182
183 _________________________________________
184 |*JT* |
185 | |
186 | ... |
187 | "family_name": "Möbius", |
188 | "address": { |
189 | "street_address": "Schulstr. 12", |
190 | "locality": "Schulpforta" |
191 | } |
192 | ... |
193 |________________________________________|
194
195
196
197 *Nits*
198
199 4. "(for those who celebrate)" will be anywhere from obscure to
200 confusing for many readers from many cultures -- best to remove it.
201
202 4.2.1. "an UTF-8" -> "a UTF-8" [overtaken by 4.2.1 above]
203
204 "However, the digest is calculated over the respective
205 base64url-encoded value itself, which effectively signs"
206
207 ->
208
209 "Because the digest is calculated over the respective
210 base64url-encoded value itself, this effectively signs"
211
212 4.3.1. I'd recommend
213 "The bytes of the digest MUST" -> "The bytes of the sd_hash value MUST"
214
215 6. I have decoded a few of the Disclosures and they're fine, but you
216 might want to ask a friendly 3rd party to double-check all the
217 Disclosures and digests, at least here and in Appendix A.
218
219 9. "Security considerations in this section help achieve the
220 following properties:"
221
222 This confused me for a while. I think what you mean to say here
223 is something like
224
225 This spec aims to provide two security guarantees:
226
227 *Selective Disclosure*: ...
228
229 *Integrity*: ...
230
231 The following sub-sections show how the various aspects of the
232 design presented here combine to achieve this.
233