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

Jump to bottom

Correct layering violations related to the proof property #1397

Merged
merged 16 commits into from
Jan 12, 2024
Merged

Correct layering violations related to the proof property #1397

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
3de855a
Correct layering violations related to the proof property
selfissued Dec 19, 2023
5bb8f16
Resolved merge conflicts and incorporated input from Oliver and Manu
selfissued Jan 10, 2024
5604b06
Applied Ted's suggestion
selfissued Jan 12, 2024
1be081b
Applied Ted's suggestion
selfissued Jan 12, 2024
57f8238
Applied Ted's suggestion
selfissued Jan 12, 2024
349c53f
Applied Ted's suggestion
selfissued Jan 12, 2024
b5f633d
Applied Ted's suggestion
selfissued Jan 12, 2024
f4148b3
Applied Ted's suggestion
selfissued Jan 12, 2024
122c1b2
Applied Ted's suggestion
selfissued Jan 12, 2024
1bf153b
Applied suggestions by Manu and Brent
selfissued Jan 12, 2024
78d02e2
Applied Manu's suggestion
selfissued Jan 12, 2024
a2e1bfd
Applied Ivan's suggestion
selfissued Jan 12, 2024
1dc5319
Applied Manu's suggestion
selfissued Jan 12, 2024
c52fd53
Applied Manu's suggestion to delete controller DT
selfissued Jan 12, 2024
7e1e1c8
Applied Manu's suggestion
selfissued Jan 12, 2024
ca11418
Merge branch 'main' of https://github.com/w3c/vc-data-model into mbj-…
selfissued Jan 12, 2024
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
181 changes: 46 additions & 135 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -632,7 +632,7 @@ <h3>Use Cases and Requirements</h3>
Web Signature of a JSON Web Token for proofing a key holder), are an essential
part of processing <a>verifiable credentials</a> and
<a>verifiable presentations</a>. At the time of publication, Working Group
members had implemented such protection using at least three proof mechanisms:
members had implemented such protection using at least two proof mechanisms:
</p>

<ul>
Expand Down Expand Up @@ -800,7 +800,9 @@ <h3>Credentials</h3>
<a>verifiable credential</a>, but abstracts the details about how <a>claims</a>
are organized into information <a>graphs</a>, which are then organized into
<a>verifiable credentials</a>. <a href="#info-graph-vc"></a> below shows a
more complete depiction of a <a>verifiable credential</a>, which is normally
more complete depiction of a <a>verifiable credential</a>
secured with Data Integrity Proofs [[VC-DATA-INTEGRITY]].
<a>Verifiable credentials</a> secured in this manner are
selfissued marked this conversation as resolved.
Show resolved Hide resolved
composed of at least two information <a>graphs</a>. The first <a>graph</a>
(the <a>verifiable credential graph</a>, in this case the <a>default graph</a>)
expresses the <a>verifiable credential</a> itself, which contains credential
Expand Down Expand Up @@ -890,7 +892,10 @@ <h3>Presentations</h3>
</p>
<p>
<a href="#info-graph-vp"></a> below shows a more complete depiction of a
<a>verifiable presentation</a>, which is normally composed of at least four
<a>verifiable presentation</a>
secured with Data Integrity Proofs [[VC-DATA-INTEGRITY]].
<a>Verifiable presentations</a>, secured in this manner are
selfissued marked this conversation as resolved.
Show resolved Hide resolved
normally composed of at least four
selfissued marked this conversation as resolved.
Show resolved Hide resolved
information <a>graphs</a>. The first of these <a>graphs</a>, the
<a>verifiable presentation graph</a> (which is the <a>default graph</a>),
expresses the <a>verifiable presentation</a> itself, and contains presentation
Expand Down Expand Up @@ -1175,7 +1180,7 @@ <h3>Contexts</h3>
</dd>
</dl>
<p class="note">
This specification requires for a <code>@context</code> <a>property</a>
This specification requires a <code>@context</code> <a>property</a>
to be present; this property is defined by [[JSON-LD]].
</p>
<pre class="example nohighlight" title="Usage of the @context property">
Expand All @@ -1194,8 +1199,7 @@ <h3>Contexts</h3>
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
},
"proof": { <span class="comment">...</span> }
}
}
</pre>

Expand Down Expand Up @@ -1417,16 +1421,6 @@ <h3>Types</h3>
</td>
</tr>

<tr>
<td>
<a href="#proofs-signatures">Proof</a>&nbsp;object
</td>
<td>
A valid proof <a>type</a>. For example,<br>
<code>"type": "DataIntegrityProof"</code>
</td>
</tr>

<tr>
<td>
<a href="#status">credentialStatus</a>&nbsp;object
Expand Down Expand Up @@ -2048,7 +2042,9 @@ <h3>Securing Mechanisms</h3>
</li>
<li>
MUST provide a verification mechanism that returns only the information in the
<a>conforming document</a> that has been secured. It MAY provide an
<a>conforming document</a> that has been secured.
selfissued marked this conversation as resolved.
Show resolved Hide resolved
This does not include the proof and related data used to secure the information.
It MAY provide an
additional mechanism to receive other information that might be helpful
during validation or for debugging purposes. The concrete interface that is
expected to be provided is detailed in the
Expand All @@ -2066,72 +2062,21 @@ <h3>Securing Mechanisms</h3>

<p>
Methods of securing <a>verifiable credentials</a> or
<a>verifiable presentations</a> that embed a proof in the data model MUST use
the <code>proof</code> <a>property</a>.
<a>verifiable presentations</a> that embed a proof in the data model MAY use a
selfissued marked this conversation as resolved.
Show resolved Hide resolved
the <code>proof</code> <a>property</a>,
when specified by the securing mechanism.
</p>
iherman marked this conversation as resolved.
Show resolved Hide resolved
<p>
Methods of securing <a>verifiable credentials</a> or <a>verifiable
presentations</a> that use an external proof MAY use the <code>proof</code>
presentations</a> that use an external proof MAY include a <code>proof</code>
<a>property</a>.
</p>
<dl>
<dt><var>proof</var></dt>
<dd>
<p>
One or more cryptographic proofs that can be used to detect tampering and verify
the authorship of a <a>verifiable credential</a> or a <a>verifiable
presentation</a>. Each proof is a separate <a>named graph</a>
(referred to as a <dfn class="export">proof graph</dfn>) containing a single
proof. The specific method used for an <a>embedded proof</a> MUST be identified
using the <code>type</code> <a>property</a>.
</p>
<p>
A proof for a <a>verifiable credential</a> covers all <a>claims</a>
included in the corresponding <a>verifiable credential graph</a>.
See <a href="#presentations-0"></a> for the case when the property is used for a
<a>verifiable presentation</a>.
</p>
</dd>
</dl>

<p>
Because the method used for a mathematical proof varies by representation
language and the technology used, the set of name-value pairs that is expected
as the value of the <code>proof</code> <a>property</a> will vary accordingly.
For example, if digital signatures are used for the proof mechanism, the
<code>proof</code> <a>property</a> is expected to have name-value pairs that
include a signature, a reference to the signing entity, and a representation of
the signing date. The example below uses Ed25519 digital signatures.
</p>

<pre class="example nohighlight"
title="Usage of the proof property on a verifiable credential">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://example.gov/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential"],
"issuer": "https://university.example",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
<span class="highlight">"proof": {
"type": "Ed25519Signature2020",
"created": "2021-11-13T18:19:39Z",
"verificationMethod": "https://university.example/issuers/14#key-1",
"proofPurpose": "assertionMethod",
"proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdo
WhAfGFCF5bppETSTojQCrfFPP2oumHKtz"
}</span>
}
</pre>

<p class="note">
As discussed in Section <a href="#conformance"></a>, there are multiple viable
Expand Down Expand Up @@ -2308,26 +2253,18 @@ <h3>Presentations</h3>
<dd>
<p>
The <a>verifiable presentation</a> MAY include a <code>proof</code>
<a>property</a>, which refers to a separate <a>named graph</a> containing a single proof.
The specific method used for the MUST be
identified using the <code>type</code> <a>property</a>.
<!-- If present, the value SHOULD be used to express a securing
mechanism, such as those listed in the
Verifiable Credentials Specifications Directory [[?VC-SPECS]]. -->
The proof covers of all claims in the following <a>graphs</a>:
<a>property</a>
when its use is specified by the securing mechanism used.
</p>
<ul>
<li>the <a>verifiable presentation graph</a>;</li>
<li>all <a>verifiable credential graphs</a> referred to by the <code>verifiableCredential</code> property of the presentation, as well as their corresponding <a>proof graphs</a>.</li>
</ul>
</dd>
</dl>

<p>
The example below shows a <a>verifiable presentation</a>:
The example below shows a <a>verifiable presentation</a>
secured with Data Integrity Proofs [[VC-DATA-INTEGRITY]]:
</p>

<pre class="example nohighlight" title="Basic structure of a presentation">
<pre class="example nohighlight" title="Basic structure of a presentation secured with Data Integrity">
Copy link
Member

Choose a reason for hiding this comment

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

I do not think it is necessary for this example. Example 18 does not use any proof mechanisms, so the reference to DI looks irrelevant.

selfissued marked this conversation as resolved.
Show resolved Hide resolved
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
Expand Down Expand Up @@ -2475,7 +2412,7 @@ <h4>Presentations Including Holder Claims</h4>
mechanism as the <a>verifiable presentation</a>.
</p>

<pre class="example nohighlight" title="A verifiable presentation, secured with an embedded proof, with a self-asserted verifiable credential">
<pre class="example nohighlight" title="A verifiable presentation, secured with an embedded Data Integrity proof, with a self-asserted verifiable credential">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
Expand All @@ -2502,7 +2439,7 @@ <h4>Presentations Including Holder Claims</h4>
<a>verifiable presentation</a>.
</p>

<pre class="example nohighlight" title="A verifiable presentation, secured with an embedded proof, with a self-asserted verifiable credential about the verifiable presentation">
<pre class="example nohighlight" title="A verifiable presentation, secured with an embedded Data Integrity proof, with a self-asserted verifiable credential about the verifiable presentation">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
Expand Down Expand Up @@ -2664,8 +2601,7 @@ <h3>Data Schemas</h3>
<span class="highlight">"credentialSchema": {
"id": "https://example.org/examples/degree",
"type": "ZkpExampleSchema2018"
}</span>,
"proof": { <span class="comment">...</span> }
}</span>
}
</pre>

Expand Down Expand Up @@ -2843,7 +2779,8 @@ <h3>Trust Model</h3>
it received. To establish this trust, a <a>credential</a> is expected to either:
<ul>
<li>
Include a <a href="#proofs-signatures">proof</a> establishing that the
Secure the <a>credential</a> with
a <a href="#proofs-signatures">proof</a> establishing that the
<a>issuer</a> generated the <a>credential</a> (that is, it is a
<a>verifiable credential</a>), or
</li>
Expand Down Expand Up @@ -3470,9 +3407,8 @@ <h3>Terms of Use</h3>
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
},
"proof": { <span class="comment">...</span> }
}],
<span class="highlight">"termsOfUse": [{
"type": "HolderPolicy",
Expand All @@ -3484,8 +3420,7 @@ <h3>Terms of Use</h3>
"target": "http://university.example/credentials/3732",
"action": ["3rdPartyCorrelation"]
}]
}]</span>,
"proof": [ ... ]
}]</span>
}
</pre>

Expand Down Expand Up @@ -3591,8 +3526,7 @@ <h3>Evidence</h3>
"subjectPresence": "Physical",
"documentPresence": "Physical",
"licenseNumber": "123AB4567"
}]</span>,
"proof": { <span class="comment">...</span> }
}]</span>
}
</pre>

Expand All @@ -3607,13 +3541,13 @@ <h3>Evidence</h3>

<p class="note">
The <code>evidence</code> <a>property</a> provides different and complementary
information to the <code>proof</code> <a>property</a>. The <code>evidence</code>
information to the securing mechanism utlized. The <code>evidence</code>
selfissued marked this conversation as resolved.
Show resolved Hide resolved
<a>property</a> is used to express supporting information, such as documentary
evidence, related to the integrity of the <a>verifiable credential</a>. In
contrast, the <code>proof</code> <a>property</a> is used to express
contrast, the securing mechanism is used to express
machine-verifiable mathematical proofs related to the authenticity of the
<a>issuer</a> and integrity of the <a>verifiable credential</a>. For more
information about the <code>proof</code> <a>property</a>, see Section
information about securing mechanisms, see Section
<a href="#proofs-signatures"></a>.
selfissued marked this conversation as resolved.
Show resolved Hide resolved
</p>

Expand Down Expand Up @@ -4182,10 +4116,10 @@ <h3>Syntactic Sugar</h3>
require them.
</li>
<li>
The <code>verifiableCredential</code> and <code>proof</code> <a>properties</a>
are defined as
<a href="https://www.w3.org/TR/json-ld11/#graph-containers">JSON-LD 1.1 graph containers</a>.
This means the creation of <a>named graphs</a> used to isolate sets of data
The <code>verifiableCredential</code> <a>property</a>
is defined as
a <a href="https://www.w3.org/TR/json-ld11/#graph-containers">JSON-LD 1.1 graph container</a>.
This means the creation of <a>named graphs</a> can be used to isolate sets of data
asserted by different entities. This ensures, for example, proper cryptographic
separation between the data graph provided by each <a>issuer</a>
and the one provided by the <a>holder</a> presenting the <a>verifiable
Expand Down Expand Up @@ -4648,7 +4582,7 @@ <h3>Verify Securing Mechanism</h3>
If the <var>inputMediaType</var> is `application/vc+ld+json` or
`application/vp+ld+json`, the <var>extractDocument</var> function takes
<var>inputBytes</var> as an input parameter, parses the value as JSON into
selfissued marked this conversation as resolved.
Show resolved Hide resolved
an object, removes the `proof` property, and returns the result as an object.
an object, removes any `proof` property, if present, and returns the result as a JSON object.
selfissued marked this conversation as resolved.
Show resolved Hide resolved
If JSON parsing fails, a <a href="#PARSING_ERROR">PARSING_ERROR</a> is appended
to <var>result</var>.<var>errors</var>.
</li>
Expand Down Expand Up @@ -4698,13 +4632,7 @@ <h3>Verify Securing Mechanism</h3>
If <var>securedDocument</var> was successfully set in the previous step, set
<var>result</var>.<var>status</var> to the result of passing
<var>securedDocument</var>, along with any relevant function-specific options,
to the <var>verifyProof</var> function. For example, the
<var>expectedProofPurpose</var> option is set to `assertionMethod` when
the conforming document is expected to be a <a>verifiable credential</a>,
and if the <a>conforming document</a> is expected to be a
<a>verifiable presentation</a>, the <var>expectedProofPurpose</var> option
is set to `authentication` and the <var>domain</var> and <var>challenge</var>
are also provided as options.
to the <var>verifyProof</var> function.
</li>
</ol>
</li>
Expand Down Expand Up @@ -5060,12 +4988,10 @@ <h3>Identifier-Based Correlation</h3>
<h3>Signature-Based Correlation</h3>

<p>
The contents of <a>verifiable credentials</a> are secured using the
<code>credential.proof</code> field. The <a>properties</a> in this field
The contents of <a>verifiable credentials</a> are secured using a securing method.
Values used to represent the securing method
selfissued marked this conversation as resolved.
Show resolved Hide resolved
create a greater risk of correlation when the same values are used across more
than one session or domain and the value does not change. Examples include the
<code>verificationMethod</code>, <code>created</code>,
<code>proofPurpose</code>, and <code>jws</code> fields.
than one session or domain and the value does not change.
</p>

<p>
Expand Down Expand Up @@ -5893,8 +5819,7 @@ <h3>Content Integrity Protection</h3>
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
},
"proof": { <span class="comment">...</span> }
}
}
</pre>

Expand All @@ -5919,8 +5844,7 @@ <h3>Content Integrity Protection</h3>
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
},
"proof": { <span class="comment">...</span> }
}
}
</pre>

Expand All @@ -5944,7 +5868,7 @@ <h3>Content Integrity Protection</h3>
<h3>Unsigned Claims</h3>

<p>
This specification allows <a>credentials</a> to be produced that do not contain
This specification allows <a>credentials</a> to be produced that are not secured by
signatures or proofs of any kind. These types of <a>credentials</a> are often
useful for intermediate storage, or self-asserted information, which is
analogous to filling out a form on a web page. Implementers should be aware that
Expand Down Expand Up @@ -6554,11 +6478,6 @@ <h3>Proofs (Signatures)</h3>
<li>
The cryptographic signature is expected to verify.
</li>
<li>
If the cryptographic suite expects a <code>proofPurpose</code> <a>property</a>,
it is expected to exist and be a valid value, such as
<code>assertionMethod</code>.
</li>
</ul>

<p class="note">
Expand All @@ -6568,15 +6487,7 @@ <h3>Proofs (Signatures)</h3>
before which the <a>credential</a> should not be considered <a>verified</a>,
distinct from the validity period of the credential. This property describes the
validity of the proof, not of the credential.
<br/><br/>
The <code>verificationMethod</code> <a>property</a> specifies, for example, the
public key that can be used to verify the digital signature. Dereferencing a
public key URL reveals information about the controller of the key, which can
be checked against the issuer of the <a>credential</a>. The
<code>proofPurpose</code> <a>property</a> clearly expresses the purpose for
the proof and ensures this information is protected by the signature. A proof is
typically attached to a <a>verifiable presentation</a> for authentication
purposes and to a <a>verifiable credential</a> as a method of assertion.
The JWT <code>iat</code> claim likewise provides the time that the signature was made.
selfissued marked this conversation as resolved.
Show resolved Hide resolved
</p>
</section>

Expand Down
2 changes: 1 addition & 1 deletion terms.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@
<dt><dfn data-lt="named graphs">named graph</dfn></dt>
<dd>
A <a>graph</a> associated with specific properties, such as
`verifiableCredential` or `proof`. These properties
`verifiableCredential`. These properties
Copy link
Member

Choose a reason for hiding this comment

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

@iherman this is removing all notions that proof is a separate graph, which doesn't seem like a good idea. You added this text, thoughts?

Copy link
Member

@iherman iherman Jan 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Good point but, with this new setup, the fact that a proof creates a new named graph must be added somewhere to the DI spec, and it is ok not to have it there.

At this point we probably should raise a new issue in the DI repo to remind us that this MUST be done, and leave this change as is.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I agree with @iherman that this information belongs in DI - not VCDM.

result in separate <a>graphs</a> that contain all <a>claims</a> defined in the
corresponding JSON objects.
</dd>
Expand Down