Thanks Dick, Some hopefully not-difficult-to-parse responses are inline below.
On Wed, Sep 4, 2024 at 6:25 AM 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. > Suggestions of alternative text would be very much appreciated. Thank you for raising your hand! Please do try and be mindful of not altering the fundamental meaning of things, however. Along those lines are some comments in response to comments inline below. Pull requests, when doing so makes sense, are typically a good way of conveying suggestions. > /Dick > > >> 1. >> <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#section-1> >> Introduction >> >> <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#name-introduction>This >> document specifies conventions for creating JSON Web Signature (JWS) [ >> RFC7515 >> <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#RFC7515> >> ] structures with JSON [RFC8259 >> <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#RFC8259> >> ] objects as the payload while supporting selective disclosure of >> individual elements of that JSON. Because JSON Web Token (JWT) [RFC7519 >> <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#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 > They might be somewhat prolix but I felt they were integral to what this document is all about when I wrote them. And still do. > >> 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 > Suggestions to make it less difficult to follow would be welcome. Ideally in the form of a PR, if you are so inclined. > > >> 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. > There is a little bit more than "no context" but they do show up rather abruptly, don't they? They are also actually introduced in the Terms and Definitions section not much later in the document. Suggestions about how to provide the appropriate amount of context in the intro would be welcome. The key difference in an SD-JWT and a JWT that the claims are encrypted in > what is signed is not clearly obvious. > The meaning of that sentence is not clearly obvious to me. Some additional clarity would be needed before any related suggested changes could be considered. > > >> 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 >> <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#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. > The last sentence feels out of place here and I think it should be removed. The overall concept is relevant, I think, even for an introduction. Do you have suggestions that could provide (some) readers with the knowledge to know why it's useful? > > >> SD-JWT can be used with any JSON-based representation of claims. >> > > repetitive from start of intro > Agree. That sentence should be removed. > > >> This specification aims to be easy to implement and to leverage >> established and widely used data formats and cryptographic algorithms >> wherever possible. > > > <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#section-1-1> > > > <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#section-1-2> > > > <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#section-1-3> > > > <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#section-1-4> > > > <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#section-1-5> > > > <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#section-1-6> > > > <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#section-1-7> > > > <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#section-1-8> > > > <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#section-1-9> > > > <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#section-1-10> > > > <https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-12.html#section-1-11> > Fluff -- are there specifications that aim to be difficult to implement? > Well, I'd argue that the answer to the rhetorical question is in fact yes. You've been doing this longer than I, surely you've seen some of the same things I've seen. And I've seen some things. Perhaps it'd be more fair to say that there are lots of specifications that too quickly lose sight of that aim. > > > 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 >> > -- _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
