Jwt example diagrams

[iherman]

This is a PR to handle #1135: it adds JWT based diagrams (and corresponding explanation texts) to the informative section on the core data model. The two JWT-based diagrams themselves have been discussed on that issue (see #1135 (comment) and the thread of discussion that follows).

@selfissued, this is the PR I was referring to in #1397 (comment) and it incorporates what I think was the "spirit" of your relevant proposed changes in #1397.

This is a PR on an informative section, and the content is purely editorial, so it is not necessary to include this into the upcoming CR version (although it would be nice, to make it complete).

Note that the automatic preview below does not properly work in this case: the diagrams are not shown. Reviewers can use the githack.com preview instead to see a final form of the text.

---

Preview | Diff

[andresuribe87]

I'm not sure I follow this sentence, can you elaborate?

[iherman]

The verifiableCredential property can refer to several credentials. I.e.

{
   …
   "verifiableCredential": [{
         ... Credential #1
    },{
         ... Credential #2    
    },{
         ... Credential #3   
    }]
}

Each credential is a separate (named) graph, and each credential graph has its own related proof graph. In the embedded proof case each credential, and its related proof graph, is added to the collection of graphs which form the complete presentation.

This is what the sentence tries to describe; clearly does not do a good job at it. Any better (but still succinct) way of expressing this?

[andresuribe87]

IMO, it would suffice to only include the first sentence here. My suggestion is to leave only the text below.

This is achieved by using the verifiableCredential property to
refer to multiple verifiable credentials.

And remove the text "In the [=embedded proof=] ... same payload."

[iherman]

I wait a few days to see if someone has a different opinion, but I am happy to make this change.

[msporny]

A few concerns with the verifiable presentation diagram:

• It's not clear to me that "vc-jwt" exists as a concept anymore. The VC-JOSE-COSE specification does not define how to encode using plain JWTs anymore. It focuses on SD-JWTs (which are not compatible w/ regular JWTs due to usage of ~ characters). Renaming should probably occur at this point to at least "SD-JWT" instead of "VC-JWT".
• The diagram on presentations isn't clear how the inner VC is protected. Presumably an EnvelopedVerifiableCredential is used?

[TallTed]

There may be more, which will become clearer upon merging these.

[iherman]

A few concerns with the verifiable presentation diagram:

The problem is that I am just a messenger... I never claim to understand the details of JOSE-COSE. These diagrams were first proposed in #1135 and the comments were essentially positive (just a few changes here and there, nothing major).

In other words, I would prefer experts to give guidance and responses on these. @selfissued? @decentralgabe

• It's not clear to me that "vc-jwt" exists as a concept anymore. The VC-JOSE-COSE specification does not define how to encode using plain JWTs anymore. It focuses on SD-JWTs (which are not compatible w/ regular JWTs due to usage of ~ characters). Renaming should probably occur at this point to at least "SD-JWT" instead of "VC-JWT".

That is of course an easy change for me to do to, but I need some experts' opinion.

• The diagram on presentations isn't clear how the inner VC is protected. Presumably an EnvelopedVerifiableCredential is used?

Frankly: I do not know.

[iherman]

Actually,

• The diagram on presentations isn't clear how the inner VC is protected. Presumably an EnvelopedVerifiableCredential is used?

using EnvelopedVerifiablCredential does not see to be the right tool. That property is applicable on the Verifiable Presentation as a whole, an not on individual credentials.

[TallTed]

My in-brain ReSpec plug-in handles HTML+Markdown pretty well, but it doesn't decode INFRA markup well yet. I think I've got the VP and VC descriptions to look the same except where they should differ. I think it's important that the VP descriptions cover both "1 Presented VC" and "≥2 Presented VC" (i.e., both singular and plural cases); I think I've covered that, but more eyes looking for such issues would be good.

[TallTed]

Given that a presentation may contain multiple credentials (and credential proofs), it seems like --

the [=credential graph=], and the [=proof graph=] linked from the [=credential graph=]

-- should become (something like) --

each presented [=credential graph=], and each [=proof graph=] linked from each [=credential graph=]

But...
as I understand it, the [=presentation=] [=proof graph=] represents the digital signature of the amalgam of the [=verifiable presentation graph=], the presented [=credential graph(s)=], and the [=proof graph(s)=] linked from the presented [=credential graph(s)=].

The above may be enough for someone else to finish massaging this sentence, or I can do that after confirmation/correction of my understanding.

[iherman]

To simplify the explanation, I decided to concentrate on the case where there is one credential in the presentation, which means that the singular case is o.k. imho. To refer to the case where there are several credentials, I have expanded on the note at the end of the presentation section. See also the comments (#1404 (review)) on that note.

[TallTed]

I'm concerned that the multiple VC VP is likely to be more frequently used, and lacking a clear example of this case, it is easy to mess up, particularly in that the [=presentation=] [=proof graph=] is not the digital signature of any portion of the VP, but only of the entire VP.

I think it's easier to derive a single VC VP implementation from a multiple VC VP example, than it is to derive a multiple VC VP implementation from a single VC VP example, so if we're only going to present one example, I think that it should be a multiple VC VP example.

[iherman]

@TallTed,

I'm concerned that the multiple VC VP is likely to be more frequently used,

I cannot judge that. I would like to get an opinion on that from domain experts like @msporny, @andresuribe87, @dlongley, or @decentralgabe.

I think it's easier to derive a single VC VP implementation from a multiple VC VP example, than it is to derive a multiple VC VP implementation from a single VC VP example, so if we're only going to present one example, I think that it should be a multiple VC VP example.

I am not sure. Changing the text is easy (sort of), but that would require a change of the diagrams (both the DI and JWT cases) because the current ones are addressing the single VC case only. However, I am afraid that the diagrams would then become huge and would distort the document (the diagrams, as they are, are already fairly large). They would also become fairly complex.

I am also not convinced that such a complicated diagram (as the "only" diagram) would still be easy to comprehend. I actually think it would become too complicated to the first-time-reader. Note also that none of the examples in the spec contain several credentials explicitly (although, for some examples, there are hints to the possible presence of other credentials.)

What we may do (but I would prefer to do this in a separate PR once this one is, hopefully, solved) is

• Create a separate diagram (or diagrams, including the JWT case) in SVG but not embedded into this document
• Link to that diagram from the note at the end of the session that addresses the multiple VP case. Actually, I wonder whether it is not better to use that text as a main part of the section (which is non-normative anyway) instead of putting this as a note.

(An alternative might be to come up with a visual clue on the diagrams that provide hints to the possible presence of other credentials and related proofs, but at this moment I have no idea how that could be done properly.)

[TallTed]

Visual cues (which could be as simple as staggered, stacked replication of the relevant nodes with ... labels on them) on the existing diagram would help, but I'm less concerned with readers understanding the idea of a multiple VC VP than in them understanding the technicalities thereof.

Since we're producing an HTML doc (even though it may be printed or written to a PDF), we don't have to worry so much about page real estate nor about an image being illegible in its primary (possibly scaled down) presentation, as long as it links to a legible presentation (possibly without scaling), so I'm not concerned about a large or complex image. Complexity usually becomes comprehensible by making the image "as large as it needs to be, with as much whitespace as needed to be clear", as opposed to "as small as possible, with as little whitespace as possible, to make it fit on the page."

Given that these are informative, non-normative, we could also consider putting either or both of these diagrams and descriptions into an appendix, to which we link from the main text. I would not want to put either diagram or description into something entirely removed from this spec.

[iherman]

@TallTed I am willing to give a try working on the diagram to see if it is doable reasonably. But I am still not convinced about your initial statement

I'm concerned that the multiple VC VP is likely to be more frequently used,

Also, I am still afraid that not only the diagram but also the text would become, in fact, more convoluted and difficult to comprehend if we make this change than leaving it as is.

I would need others to chime in on this.

[selfissued]

I do not believe it's necessary to have a diagram with multiple credentials in a presentation.

[iherman]

My in-brain ReSpec plug-in handles HTML+Markdown pretty well, but it doesn't decode INFRA markup well yet. I think I've got the VP and VC descriptions to look the same except where they should differ. I think it's important that the VP descriptions cover both "1 Presented VC" and "≥2 Presented VC" (i.e., both singular and plural cases); I think I've covered that, but more eyes looking for such issues would be good.

I think you got this right, see my separate comment on the plural cases.

(Just to be pedantic: the [= ... =] syntax is not related to INFRA at all. It is related to the cross-reference infrastructure that is being used and that respec recognizes and uses...)

[TallTed]

Missed a couple...

[decentralgabe]

looks great

[iherman]

@decentralgabe @selfissued I would like to get your opinion on the problems raised by @msporny above on the very essence of the new diagrams, namely:

A few concerns with the verifiable presentation diagram:

• It's not clear to me that "vc-jwt" exists as a concept anymore. The VC-JOSE-COSE specification does not define how to encode using plain JWTs anymore. It focuses on SD-JWTs (which are not compatible w/ regular JWTs due to usage of ~ characters). Renaming should probably occur at this point to at least "SD-JWT" instead of "VC-JWT".
• The diagram on presentations isn't clear how the inner VC is protected. Presumably an EnvelopedVerifiableCredential is used?

I am largely out of my depth to answer these questions, and I would need advice on what to change on the new JWT-related diagrams (or should it be thrown out of the window altogether?)

[selfissued]

Having this diagram is an improvement. Thanks for creating it.

Please apply these tweaks, then I'll approve it.

• Change "alg: E384" to "alg: ES384".
• Change "JWS (Decoded)" to "SD-JWT (Decoded)".
• Add "typ: vc+ld+json+sd-jwt" to the header.
• Add "iss: https://example.com" to the header.
• Add "iat: 1704690029" to the header.
• Change "kid: https://example.com/keys/#1234" to "kid: aB8J-_Z".

[iherman]

Having this diagram is an improvement. Thanks for creating it.

Please apply these tweaks, then I'll approve it.

• Change "alg: E384" to "alg: ES384".
• Change "JWS (Decoded)" to "SD-JWT (Decoded)".
• Add "typ: vc+ld+json+sd-jwt" to the header.
• Add "iss: https://example.com" to the header.
• Add "iat: 1704690029" to the header.
• Change "kid: https://example.com/keys/#1234" to "kid: aB8J-_Z".

Thanks @selfissued, I have made the changes. The separate preview can be used to see the diagrams as they are now.

[msporny]

The updates that @selfissued suggested are fine, +1 to those.

@iherman wrote:

using EnvelopedVerifiablCredential does not see to be the right tool. That property is applicable on the Verifiable Presentation as a whole, an not on individual credentials.

There is no signature on the encapsulated VC. How is it secured?

[msporny]

The updates that @selfissued suggested are good, +1 to those.

@iherman wrote:

using EnvelopedVerifiablCredential does not see to be the right tool. That property is applicable on the Verifiable Presentation as a whole, an not on individual credentials.

For the SD-JWT presentation example, there is no signature on the encapsulated VC. How is it secured? There need to be two signatures, one on the VC and another on the VP. Unless I'm missing something, the diagram, at present, is just wrong. :)

If we're in a hurry to get this in, then put an issue marker beside the last diagram noting the issue and we can merge (though, I expect that to raise some eyebrows).

[iherman]

The updates that @selfissued suggested are good, +1 to those.

@iherman wrote:

using EnvelopedVerifiablCredential does not see to be the right tool. That property is applicable on the Verifiable Presentation as a whole, an not on individual credentials.

For the SD-JWT presentation example, there is no signature on the encapsulated VC. How is it secured? There need to be two signatures, one on the VC and another on the VP. Unless I'm missing something, the diagram, at present, is just wrong. :)

If we're in a hurry to get this in, then put an issue marker beside the last diagram noting the issue and we can merge (though, I expect that to raise some eyebrows).

Back to my earlier reply: I need a response from an expert. I am not...

[iherman]

@msporny @selfissued @TallTed

I have tried to close all loose ends; I would welcome a re-review to see if we can merge this PR. Here essential changes:

• The diagram on VP-s in JWT has fundamentally changed (after a discussion with @msporny): it uses an EnvelopedVerifiableCredential with a data: URL to refer to a VC under JWT. That was, I believe, the fundamental issue of @msporny. Obviously, the text preceding the diagram, as well as the caption, have been adapted to this change.
• There is now a separate Appendix depicting the situation where there are multiple credentials under the same presentation. This was the principal issue of @TallTed, which we also discussed separately. The new Appendix includes such an example both for the case of DI and for JWT.
• All the JWT diagrams include the header changes asked by @selfissued

I hope all open problems have been handled.

(Remember to use the githack preview rather than the original one to see all the diagrams.)

cc @brentzundel

[TallTed]

fix typos of vp+ld-json+sd-jwt, to vp+ld+json+sd-jwt

[msporny]

Editorial, multiple reviews, changes requested and made, no objections, merging.