Working on a PR ... On Thu, Sep 12, 2024 at 11:37 PM Brian Campbell <bcampb...@pingidentity.com> wrote:
> 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
