Clarification of JWT encoding #828
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -3490,12 +3490,12 @@ <h4>JSON Web Token Extensions</h4> | |||||
| <li> | ||||||
| <code>vc</code>: JSON object, which MUST be present in a JWT | ||||||
| <a>verifiable credential</a>. The object contains the | ||||||
| <a>credential</a> according to this specification. | ||||||
| </li> | ||||||
| <li> | ||||||
| <code>vp</code>: JSON object, which MUST be present in a JWT | ||||||
| <a>verifiable presentation</a>. The object contains the | ||||||
|
There was a problem hiding this comment. This change should be accepted for the reasons I gave in https://github.com/w3c/vc-data-model/pull/828/files#r753698782 |
||||||
| <a>presentation</a> according to this specification. | ||||||
| </li> | ||||||
| </ul> | ||||||
| </section> | ||||||
|
|
@@ -3525,19 +3525,19 @@ <h5>JWT Encoding</h5> | |||||
|
|
||||||
| <p> | ||||||
| If no explicit rule is specified, <a>properties</a> are encoded in the same way | ||||||
|
There was a problem hiding this comment. This change should be accepted for the reasons I gave in https://github.com/w3c/vc-data-model/pull/828/files#r753698782 |
||||||
| as with a standard <a>credential</a>, and are added to the | ||||||
| <code>vc</code> <a>claim</a> of the JWT. As with all JWTs, the JWS-based | ||||||
| signature of a <a>verifiable credential</a> represented in the JWT syntax is | ||||||
| calculated against the literal JWT string value as presented across the wire, | ||||||
| before any decoding or transformation rules are applied. The following | ||||||
| paragraphs describe these encoding rules. | ||||||
| </p> | ||||||
|
|
||||||
| <p> | ||||||
| If a JWS is present, the digital signature refers either to the <a>issuer</a> | ||||||
| of the <a>verifiable credential</a>, or in the case of a | ||||||
| <a>verifiable presentation</a>, to the <a>holder</a> of the | ||||||
| <a>verifiable credential</a>. The JWS proves that the <code>iss</code> of the JWT | ||||||
| signed the contained JWT payload and therefore, the <code>proof</code> | ||||||
| <a>property</a> can be omitted. | ||||||
David-Chadwick marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| </p> | ||||||
|
|
@@ -3576,8 +3576,8 @@ <h5>JWT Encoding</h5> | |||||
|
|
||||||
| <p> | ||||||
| For backward compatibility with JWT processors, the following registered JWT | ||||||
David-Chadwick marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| claim names MUST be used instead of, or in addition to, their respective standard | ||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. @David-Chadwick -- You marked this resolved, and said that such marking meant you had applied my suggested change. This change was not applied. I am applying it now in a new PR. |
||||||
| <a>verifiable credential</a> counterparts: | ||||||
| </p> | ||||||
|
|
||||||
| <ul> | ||||||
|
|
@@ -3600,7 +3600,9 @@ <h5>JWT Encoding</h5> | |||||
| </li> | ||||||
| <li> | ||||||
| <code>sub</code> MUST represent the <code>id</code> <a>property</a> contained | ||||||
| in the <code>credentialSubject</code>. | ||||||
| <p class="note">In <code>bearer credentials</code> and <code>presentations</code>, | ||||||
| <code>sub</code> will not be present.</p> | ||||||
| </li> | ||||||
| <li> | ||||||
| <code>aud</code> MUST represent (i.e., identify) the intended audience | ||||||
|
|
@@ -3649,7 +3651,7 @@ <h5>JWT Encoding</h5> | |||||
| <h5>JWT Decoding</h5> | ||||||
|
|
||||||
| <p> | ||||||
| To decode a JWT to a standard <a>credential</a> or <a>presentation</a>, the following | ||||||
| transformation MUST be performed: | ||||||
| </p> | ||||||
|
|
||||||
|
|
@@ -3658,11 +3660,11 @@ <h5>JWT Decoding</h5> | |||||
| Create a JSON object. | ||||||
| </li> | ||||||
| <li> | ||||||
| Add the content from the <code>vc</code> or <code>vp</code> <a>claim</a> to the new JSON object. | ||||||
| </li> | ||||||
| <li> | ||||||
| Transform the remaining JWT specific headers and <a>claims</a>, and add the | ||||||
| results to the new <a>credential</a> or <a>presentation</a> JSON object. | ||||||
|
There was a problem hiding this comment. this is so great to see! I wonder if we might fully define these transformation functions, I would like to see them made explicit. There was a problem hiding this comment. @OR13 -- I suggest creating a new issue "to see [these transformation functions] made explicit". |
||||||
| </li> | ||||||
| </ol> | ||||||
|
|
||||||
|
|
@@ -3680,8 +3682,8 @@ <h5>JWT Decoding</h5> | |||||
| </li> | ||||||
| <li> | ||||||
| If <code>iss</code> is present, the value MUST be used to set the | ||||||
| <code>issuer</code> <a>property</a> of the new <a>credential</a> JSON object | ||||||
| or the <code>holder</code> <a>property</a> of the new <a>presentation</a> JSON object. | ||||||
| </li> | ||||||
| <li> | ||||||
| If <code>nbf</code> is present, the UNIX timestamp MUST be converted to an | ||||||
|
|
@@ -3691,7 +3693,7 @@ <h5>JWT Decoding</h5> | |||||
| </li> | ||||||
| <li> | ||||||
| If <code>sub</code> is present, the value MUST be used to set the value of the | ||||||
| <code>id</code> <a>property</a> of <code>credentialSubject</code> of the new <a>credential</a> | ||||||
| JSON object. | ||||||
| </li> | ||||||
| <li> | ||||||
|
|
@@ -3745,7 +3747,7 @@ <h5>JWT Decoding</h5> | |||||
| <a>property</a> because the JWT encoding uses the <code>jti</code> | ||||||
| attribute to represent a unique identifier. The <code>sub</code> attribute | ||||||
| encodes the information represented by the <code>id</code> <a>property</a> of | ||||||
| <code>credentialSubject</code>. The <code>nonce</code> has been added to stop a replay attack. | ||||||
| </p> | ||||||
|
|
||||||
| <pre class="example nohighlight" title="Verifiable credential using JWT compact serialization (non-normative)"> | ||||||
|
|
@@ -3807,7 +3809,8 @@ <h5>JWT Decoding</h5> | |||||
| <a>property</a> because the JWT encoding uses the <code>jti</code> | ||||||
| attribute to represent a unique identifier. <code>verifiableCredential</code> | ||||||
| contains a string array of <a>verifiable credentials</a> using | ||||||
| <code>JWT</code> compact serialization. The <code>nonce</code> has been added | ||||||
| to stop a replay attack. | ||||||
| </p> | ||||||
|
|
||||||
| <pre class="example nohighlight" title="Verifiable presentation using JWT compact serialization (non-normative)"> | ||||||
|
|
||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you clarify why a vast majority of the "verifiable" terms are being removed?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
probably because its not actually the same type... in JWT land, jwt.payload.vc.issuanceDate is maybe not required if the 'instead of' path is taken... leading to type ambiguity if the term
verifiable credentialis used to refer to thevcpayload... the jwt.payload.vc is in fact not verifiable... only the jwt (the outer container that includes it) make sit verifiable.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this is in line with the langauge we use as well:
credential: JSON with an
@contextthat contains all required fields except forproof-> issue ->
verifiable credential
<JWT or LD Proof>There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
if issuanceDate is a required attribute of a verifiable credential (thats what the spec says today)...then removing it destroys interoperability and conformance.... calling the thing that might not have that property the same as the thing that has to have that property is problematic.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, and (removing
issuerandissuanceDateand all other JWT-encoded properties) was exactly this was suggested on the call yesterday, which tells me that the entire VC-JWT ecosystem is not interoperable today.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMO, this change should be accepted, since
vcis obviously not averifiable credentialunder the current normative text... its possibly also not acredentialunder the current text, but this is a step in the right direction. We should not be standing in the way of a "more truthful" editorial refinement.