I agree, I also think the intro is hard to read. There are some more points that I want to add with regard to the introduction:
> The JSON-based representation of claims in a signed JWT is secured against > modification using JWS digital signatures. A consumer of a signed JWT that > has checked the signature can safely assume that the contents of the token > have not been modified. However, anyone receiving an unencrypted JWT can read > all the claims. Likewise, anyone with the decryption key receiving encrypted > JWT can also read all the claims. Regarding “a consumer of a signed JWT that has checked the signature”, I believe, it should say “that has validated the signature”. > Similar to the JWT specification on which it builds, this document is a > product of the Web Authorization Protocol (OAuth) working group. However, > while both JWT and SD-JWT have potential OAuth 2.0 applications, their > utility and application is certainly not constrained to OAuth 2.0. JWT was > developed as a general-purpose token format and has seen widespread usage in > a variety of applications. SD-JWT is a selective disclosure mechanism for JWT > and is similarly intended to be general-purpose specification. I believe, there is a typo in the last sentence of the paragraph. It should say “[…] to be a general-purpose specification.” > While JWTs with claims describing natural persons are a common use case, the > mechanisms defined in this document are also applicable to other use cases. Repeating the “general-purpose specification”. Suggest to remove the sentence. > In an SD-JWT, claims can be hidden, but cryptographically protected against > undetected modification. "Claims" here refers to both object properties > (name/value pairs) as well as array elements. When issuing the SD-JWT to the > Holder, the Issuer includes the cleartext counterparts of all hidden claims, > the so-called Disclosures, outside the signed part of the SD-JWT. I don’t see the contradiction between “hiding” and “cryptographic protection”. Should it say “and cryptographically protected” instead of “but”? I find it confusing to use the term “claims” for two different things. I think, it would be more clear to use the term claim as defined in RFC 7519 (that is a name/value pair consisting of a Claim Name and Claim Value) and not to overload it. I also think, that the introduction does not have to list all the features, i.e. it’s ok to omit the fact that SD-JWT allows for hiding individual elements in an array. > The Holder decides which claims to disclose to a particular Verifier and > includes the respective Disclosures in the SD-JWT to that Verifier. The > Verifier has to verify that all disclosed claim values were part of the > original Issuer-signed JWT. The Verifier will not, however, learn any claim > values not disclosed in the Disclosures. To my understanding, there is no “originally Issuer-signed JWT” in an SD-JWT but simply an “Issuer-signed JWT”. Suggest to remove “originally” from the phrase. Also, “Issuer-signed JWT” appears out of the blue as it has not been introduced yet. The statement "The Verifier will not, however, learn any claim values not disclosed in the Disclosures.” is technically not true because the Verifier will still learn any “cleartext claims”. Suggest to update to "The Verifier will not, however, learn any hidden claim values not disclosed in the Disclosures.” Regards, Judith > On 4 Sep 2024, at 14:24, Dick Hardt <dick.ha...@gmail.com> wrote: > > A while ago in an in-person meeting I provided feedback that the introduction > was difficult to parse. It still is. A few comments inserted to illustrate. > > I'll raise my hand to provide alternative text if the authors are interested. > > /Dick > 1. Introduction > This document specifies conventions for creating JSON Web Signature (JWS) > [RFC7515] structures with JSON [RFC8259] objects as the payload while > supporting selective disclosure of individual elements of that JSON. Because > JSON Web Token (JWT) [RFC7519] is a very prevalent application of JWS with a > JSON payload, the selective disclosure of JWT claims receives primary > treatment herein. However, that does not preclude the mechanism's > applicability to other applications of JWS with JSON payloads. > > The last two sentences add alot of noise to the first paragraph of what this > document is all about > The JSON-based representation of claims in a signed JWT is secured against > modification using JWS digital signatures. A consumer of a signed JWT that > has checked the signature can safely assume that the contents of the token > have not been modified. However, anyone receiving an unencrypted JWT can read > all the claims. Likewise, anyone with the decryption key receiving encrypted > JWT can also read all the claims. > One of the common use cases of a signed JWT is representing a user's > identity. As long as the signed JWT is one-time use, it typically only > contains those claims the user has consented to disclose to a specific > Verifier. However, there is an increasing number of use cases where a signed > JWT is created once and then used a number of times by the user (the "Holder" > of the JWT). In such use cases, the signed JWT needs to contain the superset > of all claims the user of the signed JWT might want to disclose to Verifiers > at some point. The ability to selectively disclose a subset of these claims > depending on the Verifier becomes crucial to ensure minimum disclosure and > prevent Verifiers from obtaining claims irrelevant for the transaction at > hand. SD-JWTs defined in this document enable such selective disclosure of > JWT claims. > One example of a multi-use JWT is an Issuer-signed credential that contains > the claims about a subject, and whose authenticity can be cryptographically > verified. > Similar to the JWT specification on which it builds, this document is a > product of the Web Authorization Protocol (OAuth) working group. However, > while both JWT and SD-JWT have potential OAuth 2.0 applications, their > utility and application is certainly not constrained to OAuth 2.0. JWT was > developed as a general-purpose token format and has seen widespread usage in > a variety of applications. SD-JWT is a selective disclosure mechanism for JWT > and is similarly intended to be general-purpose specification. > While JWTs with claims describing natural persons are a common use case, the > mechanisms defined in this document are also applicable to other use cases. > > The above paragraphs are background on what problem is being solved -- but > the writing is difficult to follow > In an SD-JWT, claims can be hidden, but cryptographically protected against > undetected modification. "Claims" here refers to both object properties > (name/value pairs) as well as array elements. When issuing the SD-JWT to the > Holder, the Issuer includes the cleartext counterparts of all hidden claims, > the so-called Disclosures, outside the signed part of the SD-JWT. > > The Holder decides which claims to disclose to a particular Verifier and > includes the respective Disclosures in the SD-JWT to that Verifier. The > Verifier has to verify that all disclosed claim values were part of the > original Issuer-signed JWT. The Verifier will not, however, learn any claim > values not disclosed in the Disclosures. > > The Holder and Verifier terms are being introduced here with no context. The > key difference in an SD-JWT and a JWT that the claims are encrypted in what > is signed is not clearly obvious. > This document also defines a format for SD-JWTs with Key Binding > (SD-JWT+KB). By optionally sending an SD-JWT+KB to a Verifier, the Holder can > prove to the Verifier that they hold the private key associated to the SD-JWT > (i.e., using the cnf claim [RFC7800]). The strength of the binding is > conditional upon the trust in the protection of the private key of the key > pair an SD-JWT is bound to. > > This does not read as an introduction. Assumes significant knowledge of why > this is useful. > > SD-JWT can be used with any JSON-based representation of claims. > > repetitive from start of intro > This specification aims to be easy to implement and to leverage established > and widely used data formats and cryptographic algorithms wherever > possible.Fluff -- are there specifications that aim to be difficult to > implement? > > > On Tue, Sep 3, 2024 at 4:06 PM Brian Campbell > <bcampbell=40pingidentity....@dmarc.ietf.org> wrote: > Thanks Rifaat & Hannes, > > In an effort to make the most up-to-date content available for the WGLC > period, a -12 revision was just recently published, which contains a number > of editorial improvements. > > https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html > > > Respectfully, > Brian, Kristina, and Dr. Fett > > > > On Tue, Sep 3, 2024 at 4:40 AM Rifaat Shekh-Yusef <rifaat.s.i...@gmail.com> > wrote: > All, > > As per the discussion in Vancouver, this is a WG Last Call for the SD-JWT > document. > https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-11.html > > Please, review this document and reply on the mailing list if you have any > comments or concerns, by Sep 17th. > > Regards, > Rifaat & Hannes > _______________________________________________ > OAuth mailing list -- oauth@ietf.org > To unsubscribe send an email to oauth-le...@ietf.org > > CONFIDENTIALITY NOTICE: This email may contain confidential and privileged > material for the sole use of the intended recipient(s). Any review, use, > distribution or disclosure by others is strictly prohibited. If you have > received this communication in error, please notify the sender immediately by > e-mail and delete the message and any file attachments from your computer. > Thank you._______________________________________________ > OAuth mailing list -- oauth@ietf.org > To unsubscribe send an email to oauth-le...@ietf.org > _______________________________________________ > OAuth mailing list -- oauth@ietf.org > To unsubscribe send an email to oauth-le...@ietf.org
_______________________________________________ OAuth mailing list -- oauth@ietf.org To unsubscribe send an email to oauth-le...@ietf.org
