Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for Enveloped Verifiable Credentials (2nd attempt) #1379

Merged
merged 6 commits into from
Dec 15, 2023
Merged

Add support for Enveloped Verifiable Credentials (2nd attempt) #1379

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2783fd5
Add EnvelopedVerifiableCredential type to vocabulary.
iherman Dec 9, 2023
179b88b
Add section for Enveloped Verifiable Credentials.
msporny Dec 9, 2023
5cbb196
Add EnvelopedVerifiableCredential to JSON-LD Context.
msporny Dec 9, 2023
c4d5554
Fix grammar in Enveloped Verifiable Credentials introduction.
msporny Dec 15, 2023
01262ae
Add reference to RFC2397.
msporny Dec 15, 2023
3884d4e
Fix example for SD-JWT.
msporny Dec 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions contexts/credentials/v2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,9 @@
"description": "https://schema.org/description",
"name": "https://schema.org/name",

"EnvelopedVerifiableCredential":
"https://www.w3.org/2018/credentials#EnvelopedVerifiableCredential",

"VerifiableCredential": {
"@id": "https://www.w3.org/2018/credentials#VerifiableCredential",
"@context": {
Expand Down
46 changes: 46 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2324,6 +2324,52 @@ <h3>Presentations</h3>
[[?VC-JOSE-COSE]] specification.
</p>

<section>
<h4>Enveloped Verifiable Credentials</h4>

<p>
It is possible to include one or more <a>verifiable credentials</a> in a
<a>verifiable presentation</a> that have been secured using a securing mechanism
msporny marked this conversation as resolved.
Show resolved Hide resolved
that "envelopes" the payload, such as [[[?VC-JOSE-COSE]]] [[?VC-JOSE-COSE]].
iherman marked this conversation as resolved.
Show resolved Hide resolved
This can be accomplished by associating the `verifiableCredential` property with
an object that has a `type` of `EnvelopedVerifiableCredential`.
</p>

<dl>
<dt id="defn-EnvelopedVerifiableCredential">EnvelopedVerifiableCredential</dt>
<dd>
Used to associate an object containing an enveloped <a>verifiable credential</a>
with the `verifiableCredential` property in a <a>verifiable presentation</a>.
The `@context` value of the object MUST follow all of the "MUST" statements in
Section <a href="#contexts"></a>. The `id` value of the object MUST be a `data:`
Comment on lines +2343 to +2344
Copy link
Member

@iherman iherman Dec 10, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `@context` value of the object MUST follow all of the "MUST" statements in
Section <a href="#contexts"></a>. The `id` value of the object MUST be a `data:`
The possible `@context` value of the object MUST follow all of the "MUST" statements in
Section <a href="#contexts"></a>. The `id` value of the object MUST be a `data:`

Is it really necessary to include a @context at this point? The only reason to have it is to use the id and type aliases, but that would be inherited from the contexts above, wouldn't it?

Copy link
Member Author

@msporny msporny Dec 10, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it's necessary, because (in the v2 context) we clear all context values inside the Verifiable Credential Graph. We have to do this in order to ensure that VCDM v1.1 VCs can be put inside VCDMV v2.0 VPs. If we don't do that, JSON-LD protected mode kicks in and alerts us that we're re-defining some terms (which is the correct behaviour).

Copy link
Member

@iherman iherman Dec 10, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah. Right, my bad.

(For other reviewers, in case they do not follow: there is a "@context": null statement within the definition of the VerifiablePresentation.verifiableCredential property in the V2 @context file. The reason is what @msporny describes above.)

Let me picky, though. The text says:

The @context value of the object MUST follow all of the "MUST" statements in Section 4.2 Contexts.

However, §4.2 only says:

Verifiable credentials and verifiable presentations MUST include a @context property.

Technically, i.e., in the vocabulary, an EnvelopedVerifiableCredential is not a VerifiableCredential (they are different classes), meaning that the statement in §4.2 does not apply, i.e., it is not said that a @context file must be present. You can either change the text in §4.2, or add a statement in the new section whereby a @context property MUST be added.

Also, continuing to be picky, and looking at §5.12, the text says:

For presentations, each value associated with the verifiableCredential property of the presentation is a separate named graph of type VerifiableCredentialGraph which contains a single verifiable credential.

(Emphasis is mine.) I believe it should say something like

which contains a single verifiable credential or and enveloped verifiable credential.

(Or something for that effect.)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I believe your statements above are correct, I'll make those modifications in the next iteration of this PR.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think the second context is required here... if the v2 context defines things correctly.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@OR13,

As explained in the comments above, the second context is indeed necessary as the context is intentionally cleared to support other contexts (such as 1.1). So a context declaration is required.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@OR13

We can put it another way: if the second context is not used, then the right terms for that object must be @type and @id instead of type and id, respectively (this is how the current, v2 version of @context works, and I do not see any way to avoid that.)

It is indeed unfortunate that the usage of those aliases force us to use the second context here. But that is water under the bridge, we decided not to use the original, @-prefixed values.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@iherman, I applied your requests in 2ffb884.

URL that expresses a secured <a>verifiable credential</a> using an enveloping
msporny marked this conversation as resolved.
Show resolved Hide resolved
security scheme, such as [[[VC-JOSE-COSE]]] [[VC-JOSE-COSE]]. The `type` value
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there 2 here intentionally?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@OR13, this is a respec trick.

  • [[[VC-JOSE-COSE]]] is converted into the official title of the spec
  • [[VC-JOSE-COSE]] is converted into a reference to the References' section.

So the short answer to your question is: yes.

of the object MUST be `EnvelopedVerifiableCredential`.
</dd>
</dl>

<p>
The example below shows a <a>verifiable presentation</a> that contains an
enveloped <a>verifiable credential</a>:
</p>

<pre class="example nohighlight" title="Basic structure of a presentation">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"type": ["VerifiablePresentation", "ExamplePresentation"],
<span class="highlight">"verifiableCredential": [{
"@context": "https://www.w3.org/ns/credentials/v2",
"id": "data:application/vc+ld+json+sd-jwt;base64,QzVjV...RMjUK==",
msporny marked this conversation as resolved.
Show resolved Hide resolved
"type": "EnvelopedVerifiableCredential"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is interesting... I think with some discussion this could be acceptable.

}]</span>
}
</pre>

</section>

<section>
<h4>Presentations Using Derived Credentials</h4>

Expand Down
12 changes: 8 additions & 4 deletions vocab/credentials/v2/vocabulary.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,10 @@ class:
defined_by: https://www.w3.org/TR/vc-data-model-2.0/#bc-confidence-method
status: reserved

- id: EnvelopedVerifiableCredential
defined_by: https://www.w3.org/TR/vc-data-model-2.0/#defn-EnvelopedVerifiableCredential
label: Enveloped verifiable credential

- id: JsonSchema
label: JSON schema validator
defined_by: https://www.w3.org/TR/vc-json-schema/#jsonschema
Expand Down Expand Up @@ -102,10 +106,10 @@ property:
label: Subresource integrity digest
defined_by: https://www.w3.org/TR/vc-data-model-2.0/#defn-digestSRI
range: cred:sriString
see_also:
see_also:
- label: Subresource Integrity Metadata
url: https://www.w3.org/TR/SRI/#the-integrity-attribute

- id: evidence
label: Evidence
defined_by: https://www.w3.org/TR/vc-data-model-2.0/#defn-evidence
Expand Down Expand Up @@ -195,7 +199,7 @@ datatype:
label: Datatype for digest SRI values
upper_value: xsd:string
defined_by: https://www.w3.org/TR/vc-data-model-2.0/#the-sristring-datatype
see_also:
see_also:
- label: Subresource Integrity Metadata
url: https://www.w3.org/TR/SRI/#the-integrity-attribute