Hi, Today I did a full read and review of draft-ietf-oauth-selective-disclosure-jwt-15. Below are my comments. Thanks, -rohan
Overall - I found the Introduction, and Sections 2 and 3, not concrete enough to follow what is being discussed in a first read through. I proposed a new Section 1.3 which I think has the right spirit. - I am super happy that we are not using did: URIs in the document. - I think it is very useful to have a capitalized name for the digests. I suggest Blinded Hash. Another good choice is Redacted Claim Hash. - All the SHOULD statements should explain why they are not MUSTs or under what circumstances the implementer could do something different that still makes sense. - If a validity claim (ex: exp, nbf) is redacted, does it need to be validated if the relevant disclosure is provided? Abstract suggestion: s/for the selective disclosure of individual elements of a JSON-encoded data structure used as the payload of a JSON Web Signature (JWS)/for the selective disclosure of individual elements of a JSON-encoded JSON Web Signature (JWS) payload/ Intro: suggestion: s/A new model is emerging that/Another model/ Section 1.1 suggestions: s/SD-JWT is a composite structure enabling selective disclosure of its contents/SD-JWT is a composite structure, consisting of a JWS plus optional disclosures, enabling selective disclosure of portions of the JWS payload. s/SD-JWT+KB is a composite structure enabling cryptographic key binding when presented to the Verifier./SD-JWT+KB is a composite structure of an SD-JWT and a cryptographic key binding that can be presented to and verified by the Verifier./ Section 1.2 Selective Disclosure: "JWT Claims Set" is used in a definition but not yet defined. Since the definition in RFC7519 is somewhat circular, maybe s/JWT Claims Set/JWS payload/ Selectively Disclosable JWT: s/Issuer-signed JWT (JWS, [RFC7515])/Issuer-signed JWS [RFC7515] (often a JWT)/ Disclosure: s/The Disclosure is used to calculate a digest for the respective claim.// *add:* Blinded Hash: The cryptographic digest (hash) of a specific Disclosure Key Binding JWT (KB-JWT): s/A Key Binding JWT is said to "be tied to" a particular SD-JWT when its payload is signed using the key included in the SD-JWT payload, and also contains a hash of the SD-JWT in its sd_hash claim. A JWT for proving Key Binding as defined in Section 4.3 <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-15.html#kb-jwt>./A Key Binding JWT is said to "be tied to" a particular SD-JWT when the KB-JWT is signed using the key included in the SD-JWT payload, and the KB-JWT contains a hash of the SD-JWT in its sd_hash claim. Its format is defined in Section 4.3 <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-15.html#kb-jwt> ./ maybe mention here that "JSON object property" is just the (truly horrible) JSON name for a map/dict key and value. *I think it is a wasted opportunity to not show an example of the structure in the Introduction!* For example: Section 1.3 Brief Illustration The JWS structure consists of protected headers, the payload, and a signature. The structure can be represented in JWS Compact Serialization (the most common) or JWS JSON Serialization. In compact serialization, a base64url encoded version of the three components are concatenated, separated by periods. In the compact representation of an SD-JWT, this is followed by a tilde character, and a list of base64url encoded disclosure strings separated by tildes. If key binding is used, the KB-JWT follows the last tilde. Issuer-signed JWS <protected header>.<payload>.<JWS signature> SD-JWT <Issuer-signed JWS>~<Disclosure 1>~<Disclosure 2>~...~<Disclosure N>~ SD-JWT+KB <Issuer-signed JWS>~<Disclosure 1>~<Disclosure 2>~...~<Disclosure N>~<optional KB-JWT> The decoded payload below (from an example in Section 5.1 with parts elided for brevity with <elided>) contains the following: - the _sd claim (which contains Blinded Hashes), - standard JWT claims (issuer, issued at time, expiration, subscriber), and - the public key of the holder in a confirmation (cnf ) claim. { "_sd": [ <elided> "JzYjH4svliH0R3PyEMfeZu6Jt69u5qehZo7F7EPYlSE", "PorFbpKuVu6xymJagvkFsFXAbRoc2JGlAUA2BA4o7cI", "TGf4oLbgwd5JQaHyKVQZU9UdGE0w5rtDsrZzfUaomLo", <elided> ], "iss": "https://issuer.example.com";, "iat": 1683000000, "exp": 1883000000, "sub": "user_42", <elided> "_sd_alg": "sha-256", "cnf": { "jwk": { "kty": "EC", "crv": "P-256", "x": "TCAER19Zvu3OHF4j4W4vfSVoHIP1ILilDls7vCeGemc", "y": "ZxjiWWbZMQGHVWKVQ4hbSIirsVfuecCE6t4jT9F2HZQ" } } } Assuming an SD-JWT presented to a Verifier with decoded payload shown above and a disclosure string WyJlbHVWNU9nM2dTTklJOEVZbnN4QV9BIiwgImZhbWlseV9uYW1lIiwgIkRvZSJd, the verifier would take the digest of the disclosure string using the SHA256 algorithm from the _sd_hash claim and find that digest ( TGf4oLbgwd5JQaHyKVQZU9UdGE0w5rtDsrZzfUaomLo) in the decoded payload. The Verifier would base64url decode the disclosure into the salt, the claim name, and the claim value: ["eluV5Og3gSNII8EYnsxA_A", "family_name", "Doe"] , "adding" the family_name claim and its value to the resulting payload. The overall flow is described in Section 2; the key concepts are more fully described in Section 3; and the details of the data formats are described in Section 4. Section 4 s/The serialized format for the SD-JWT/The compact serialized format for the SD-JWT/ The ALPHA and DIGIT productions should just reference the (identical) ones in Appendix B.1 "Core Rules" of RFC5234. Anyone who wants to use ABNF will be familiar with the Core Rules, and anyone who doesn't will be confronted by one of the more arcane parts of ABNF syntax. I still think "(for those who celebrate)" is an immature in-joke that unfortunately is going to confuse a lot of people, especially non-English speakers. Please ditch it. Section 4.1.2 "the Issuer MAY create the key pair for the Holder, or Holder and Issuer MAY use pre-established key material." I think you are going to give a heart attack to all the SEC ADs with this sentence. It appears to be condoning a generally horrible practice, and is a pile of DISCUSSes waiting to happen. Anyone who knows what they are doing and understands the risks does not need the MAY to know what to do. I would just nuke it. Section 4.2.1 I think the reference to RFC20 is going to be more confusing than helpful. suggest s/, producing a US-ASCII [RFC20 <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-15.html#RFC20>] string// s/The order is decided/The order was decided/ ; in this same paragraph s/would//; and make the paragraph an indented Note. s/The resulting Disclosure would be:/The resulting Disclosure is:/ In the paragraph starting "Note that variations in whitespace" might be confusing. While the Issuer could represent the claim names many different ways, once they sign a document containing a specific variant (either as a hashed disclosure, or a fixed claim) the holder and verifier can only use the issuer-chosen variant. Section 4.2.3 s/using the hash algorithm specified in the _sd_alg claim described in Section 4.1.1 <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-15.html#hash_function_claim>./using the hash algorithm specified in the _sd_alg claim described in Section 4.1.1 <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-15.html#hash_function_claim>, or SHA-256 if no algorithm is specified./ s/US-ASCII bytes of the// Section 4.2.4.1 IMPORTANT: This section does not explain that the _sd claim can appear at any hierarchy level (nested object properties). At least provide a forward reference to Section 6 please. Section 4.2.6 I'd like to compliment the authors that this topic was explained very clearly IMO. Section 4.3.1 s/US-ASCII bytes of the encode SD-JWT/compact encoded SD-JWT/ Section 6 or 6.3 I didn't see any mention that a verifier may process blinded hashes, not finding a corresponding disclosure (or might process disclosures not finding a corresponding hash). Once it finds a disclosure containing an array or object, the verifier should retry any remaining disclosures. Section 7.1 To step 2 "Validate the Issuer-signed JWT", I would add, "Validate the Issuer is trusted for its target usage". This is akin to trusting specific root CAs in RFC5280. The list numbering is confusing. kramdown-rfc allows passthrough xml and xml2rfc allows nested ordered lists with a type parameter like so: <ol type="a"> <li>One</li> <li>Two <ol type="a"> <li>Aaa - Roman Army sounds off <ol type="i"> <li>aye</li> <li>aye aye</li> <li>aye aye aye</li> <li>aye vee</li> <li>vee</li> </ol></li> <li>Bbb</li> <li>Ccc</li> </ol></li> <li>Three</li> </ol> There is no mention of checking that validity claims (exp and nbf) are valid if they are present. Section 7.2 I think if the section is talking about processing by a particular role, then any normative statements MUST be from the perspective of that role. Having "The Issuer MUST" statements in this section feels jarring and wrong. Section 7.3 There is no mention of what to do if there are contradictory audiences on the Issuer SD-JWT and KB-JWT Section 9 Is Holder examination/verification of the Issuer's assertions not a security property? In other words, if the Issuer discloses (in plain text) something the Holder doesn't want to disclose, the Holder can decide it will not present it. Section 9.4 "The hash function SHOULD also be collision resistant." Why is this a SHOULD instead of a MUST? Under what circumstances would this be acceptable? "The collision resistance of the hash function used to generate digests SHOULD match the collision resistance of the hash function used by the signature scheme." It is not obvious why this is the case. A signature algorithm might sign thousands or millions of SD-JWTs or KB-JWTs. The hash scheme has to be unique among dozens of blinded claims. Section 9.7 This section seems to disagree with itself. I agree with the first sentence. Then the next sentences take it all back. I would not be surprised to see the SEC ADs slap a DISCUSS on this section as currently written. Again this is another place with SHOULDs without explanation when you would do something different. Section 10.1 I didn't review this yet. I'll read this tomorrow. Section 11 s/some of which substantial/some of which are substantial/ Section 12.1 I don't think "..." is strictly covered by the JWT claims registry, since it never appears in the top-level payload object. Examples in Appendix B Seemed a missed opportunity not to mention Schulstr. vs. Schulstrasse vs. Schulstraße Likewise could have mentioned a claim with a locale consideration (ex: time, data, money). These are both very minor.
_______________________________________________ OAuth mailing list -- oauth@ietf.org To unsubscribe send an email to oauth-le...@ietf.org
