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.

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

First pass at updating validation language #1297

Closed
wants to merge 59 commits into from
Closed
Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
59 commits
Select commit Hold shift + click to select a range
965fbbc
updated entity to include abstract nouns
jandrieu Sep 6, 2023
0817aff
Apply suggestions from code review
jandrieu Sep 14, 2023
941bda4
Update terms.html
jandrieu Sep 14, 2023
bf6fa2c
full text pass at updating validation/verification language
jandrieu Oct 2, 2023
2843e16
updated terms.html to use new validation langauge
jandrieu Oct 2, 2023
f373e6c
address 1245
decentralgabe Sep 18, 2023
a6032bd
Update index.html
decentralgabe Sep 19, 2023
ea5906e
Update index.html
decentralgabe Sep 25, 2023
79791d0
Apply suggestions from code review
decentralgabe Sep 26, 2023
0c87ee0
Update index.html
decentralgabe Sep 29, 2023
d3568d7
Remove "proof" clauses from initial examples (#1308)
selfissued Oct 13, 2023
5536809
Remove CL Signature example (#1305)
OR13 Oct 13, 2023
5d8849b
Add `relatedResource` and `digestSRI` to the vocabulary.
iherman Oct 16, 2023
87a4db3
Remove extraneous trailing spaces.
msporny Oct 18, 2023
9234fb4
Adding issue marker for adding validation to image
jandrieu Oct 18, 2023
64b3e57
Update index.html
jandrieu Oct 18, 2023
4831cf8
Update index.html
jandrieu Oct 18, 2023
b983110
Update index.html
jandrieu Oct 18, 2023
d031bdb
Update index.html
jandrieu Oct 18, 2023
856a5c0
Update terms.html
jandrieu Oct 18, 2023
357e218
Update terms.html
jandrieu Oct 18, 2023
a49142d
Update index.html
jandrieu Oct 18, 2023
cc5cd92
Remove unused references and vendor-specific protocols.
OR13 Oct 21, 2023
e07bae4
Apply suggestions from code review
jandrieu Oct 24, 2023
114c452
Update index.html
jandrieu Oct 24, 2023
03c922d
Add suggestion to use Oblivious HTTP when fetching resources.
msporny Oct 21, 2023
737cdea
Fix grammar in OHTTP section.
msporny Oct 24, 2023
491b378
Update link to OHTTP draft at IETF.
msporny Oct 24, 2023
966b275
Add concrete examples of when OHTTP is useful.
msporny Oct 29, 2023
d4a6ee2
Add section on trust boundaries in privacy considerations.
msporny Oct 22, 2023
c9c3120
Clarify types of software used by roles.
msporny Oct 22, 2023
efd3992
Fix grammar/flow in trust boundaries section.
msporny Oct 30, 2023
56b52a6
Fix flow and examples in trust boundaries section.
msporny Oct 30, 2023
6382c0a
Add statement about software auditing in trust boundaries section.
msporny Oct 30, 2023
aace5b0
Add text on not being able to act in best interest of role.
msporny Oct 30, 2023
9042355
Fix grammar and flow in trust boundaries section.
msporny Oct 31, 2023
5168ddc
Specify who is providing what to platform in trust boundaries.
msporny Oct 31, 2023
699d594
Minor grammar fix in fraudulent VC usage.
msporny Oct 31, 2023
19fb1e3
Kristina stepping down as a co-chair
Sakurann Oct 26, 2023
a12a5e1
Update index.html
jandrieu Oct 31, 2023
4d77ad0
Update terms.html
jandrieu Oct 31, 2023
64a136a
rebased to latest from W3C main
jandrieu Sep 6, 2023
6ac7150
Apply suggestions from code review
jandrieu Sep 14, 2023
6adb497
Update terms.html
jandrieu Sep 14, 2023
6333d44
full text pass at updating validation/verification language
jandrieu Oct 2, 2023
5b3bb42
updated terms.html to use new validation langauge
jandrieu Oct 2, 2023
6ff22b7
Adding issue marker for adding validation to image
jandrieu Oct 18, 2023
115d44e
Update index.html
jandrieu Oct 18, 2023
c3a3898
Update index.html
jandrieu Oct 18, 2023
aa68ca2
Update index.html
jandrieu Oct 18, 2023
ceb8685
Update index.html
jandrieu Oct 18, 2023
19671d9
Update terms.html
jandrieu Oct 18, 2023
31d3481
Update terms.html
jandrieu Oct 18, 2023
b9e31f4
Update index.html
jandrieu Oct 18, 2023
124e6b5
Apply suggestions from code review
jandrieu Oct 24, 2023
9664ed0
Update index.html
jandrieu Oct 24, 2023
061c4cc
Update index.html
jandrieu Oct 31, 2023
119263a
Update terms.html
jandrieu Oct 31, 2023
400bcd8
merge cleanup
jandrieu Oct 31, 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
93 changes: 60 additions & 33 deletions index.html
Original file line number Diff line number Diff line change
Expand Up @@ -305,10 +305,7 @@ <h3>What is a Verifiable Credential?</h3>
refers to the characteristic of a <a>credential</a> or <a>presentation</a>
as being able to be <a>verified</a> by a <a>verifier</a>,
as defined in this document. Verifiability of a credential does not imply
that the truth of <a>claims</a> encoded therein can be evaluated; however,
the issuer can include values in the <a>evidence</a> property to help the verifier
apply their business logic to determine whether the claims have sufficient
veracity for their needs.
that truth of <a>claims</a> encoded therein. Rather, once the authenticity and currency of a Verifiable Credential or Verifiable Presentation are established, a <a>verifier</a> MUST validate included claims using their own business rules before relying on them. Such reliance SHOULD only occur after evaluating the issuer, the proof, the subject, and the claims, against verifier policy.
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</p>
</section>

Expand Down Expand Up @@ -915,6 +912,9 @@ <h3>Concrete Lifecycle Example</h3>
<a>Verification</a> of the <a>verifiable presentation</a> by the
<a>verifier</a>.
</li>
<li>
<a>Validation</a> by the <a>verifier</a> of relevant <a>claims</a> contained in the <a>verifiable presentation</a>.
</li>
</ol>

<p>
Expand Down Expand Up @@ -981,8 +981,19 @@ <h3>Concrete Lifecycle Example</h3>
<a>verifiable credential</a>. Pat selects the alumni
<a>verifiable credential</a>, which is then composed into a
<a>verifiable presentation</a>. The <a>verifiable presentation</a> is sent to
the <a>verifier</a> and <a>verified</a>.
</p>
the <a>verifier</a> and <a>verified</a>.
</p>
<p>Once verified as authentic and current, the seller of the season ticket
then validates that the issuer of the <a>verifiable credential</a> is
recognized for the claim of alumni status&mdash;it is, as it is issued
by Example University&mdash;and that today's date lies within the
validity period defined by the values of the validFrom and validUntil
properties. Since the holder is expected to be the subject of the
<a>verifiable credential</a> , the <a>verifier</a> also confirms that
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
the id for the alumni claim matches the id of the creator of the
Copy link
Member

Choose a reason for hiding this comment

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

The actual check is the id of the credentialSubject is associated, in some way, with the creator of the verifiable presentation. The language here is a bit loose, but that might be ok. I don't have a concrete suggestion that would be easy to read here.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

"associated, in some way" is not correct.

This particular example is an example of redeeming an alumni discount from a university, in which case arbitrary association is not the business rule. Subject==Holder is.

<a>verifiable presentation.</a>
</p>
<p>Having verified the credential and the presentation, and validated the relevant claims, the ticket seller safely enables the alumni discount for Pat, confident that Pat is legitimately entitled to it.</p>
<pre class="example nohighlight" title="A simple example of a verifiable presentation">
{
"@context": [
Expand Down Expand Up @@ -2371,7 +2382,7 @@ <h3>Data Schemas</h3>

<ul>
<li>
Data verification schemas, which are used to <a>verify</a> that the structure
Data verification schemas, which are used to establish that the structure
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
and contents of a <a>credential</a> or <a>verifiable credential</a> conform to a
published schema.
</li>
Expand Down Expand Up @@ -2461,12 +2472,12 @@ <h3>Data Schemas</h3>
In the example above, the <a>issuer</a> is specifying a
<code>credentialSchema</code>, which points to a [[?VC-JSON-SCHEMA-2023]] file that
can be used by a <a>verifier</a> to determine if the
<a>verifiable credential</a> is well formed.
<a>verifiable credential</a> is well-formed.
</p>

<p class="note" >
For information about linkages to JSON Schema [[?VC-JSON-SCHEMA-2023]] or other
optional <a>verification</a> mechanisms, see the Verifiable Credentials
optional schema validation mechanisms, see the Verifiable Credentials
Implementation Guidelines [[VC-IMP-GUIDE]] document.
</p>

Expand Down Expand Up @@ -2506,7 +2517,7 @@ <h3>Data Schemas</h3>
In the example above, the <a>issuer</a> is specifying a
<code>credentialSchema</code> pointing to a means of transforming the input
data into a format which can then be used by a <a>verifier</a> to determine if
the proof provided with the <a>verifiable credential</a> is valid.
the proof provided with the <a>verifiable credential</a> is well-formed.
OR13 marked this conversation as resolved.
Show resolved Hide resolved
</p>


Expand Down Expand Up @@ -2541,6 +2552,7 @@ <h3>Lifecycle Details</h3>
verifiable data registry">
<figcaption style="text-align: center;">
The roles and information flows for this specification.
NEEDS VALIDATE
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</figcaption>
</figure>

Expand All @@ -2567,10 +2579,12 @@ <h3>Lifecycle Details</h3>
</li>
<li>
A <a>verifier</a> <a>verifies</a> the authenticity of the presented
<a>verifiable presentation</a> and <a>verifiable credentials</a>. This should
include checking the <a href="#status">credential status</a> for revocation
<a>verifiable presentation</a> and <a>verifiable credentials</a> and
checks any <a href="#status">credential status</a>
of the <a>verifiable credentials</a>.
</li>
<li>
After <a>verification</a>, a <a>verifier</a> validates the relevant claims in presented <a>verifiable credentials</a>, using their own business logic to evaluate which issuers are appropriate for which claims and which subjects are appropriate for the requested use.</li>
<li>
An <a>issuer</a> might <dfn class="lint-ignore" data-lt="revoke">revoke</dfn> a
<a>verifiable credential</a>.
Expand All @@ -2593,14 +2607,20 @@ <h3>Lifecycle Details</h3>

<ol>
<li>
An <a>issuer</a> <a href="#lifecycle-details">issues</a> to a <a>holder</a>.
An <a>issuer</a> <a href="#lifecycle-details">issues</a> a <a>verifiable credential</a> to a <a>holder</a>.
</li>
<li>
The <a>holder</a> <a href="#lifecycle-details">presents</a> to a <a>verifier</a>.
</li>
<li>
The <a>verifier</a> <a href="#lifecycle-details">verifies</a>.
</li>
<li>
The <a>verifier</a> <a href="#lifecycle-details">validates</a> claims.
</li>
<li>
The <a>verifier</a> applies valid claims</a>.
</li>
</ol>

<p>
Expand All @@ -2611,13 +2631,15 @@ <h3>Lifecycle Details</h3>
</p>

<p>
This specification also does not define an authorization framework nor the
decisions that a <a>verifier</a> might make after <a>verifying</a> a
<a>verifiable credential</a> or <a>verifiable presentation</a>,
taking into account the <a>holder</a>, the <a>issuers</a> of the
<a>verifiable credentials</a>, the contents of the
<a>verifiable credentials</a>, and its own policies.
</p>
This specification also does not define an authorization framework nor
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
does it restrict the business decisions that a <a>verifier</a> might make
after <a>verifying</a> a <a>verifiable credential</a> or <a>verifiable
presentation</a>. However, it is required that <a>verifiers</a> MUST
apply their own business rules before treating any claims as valid,
taking into account the <a>holder</a>, the <a>issuers</a> of the
<a>verifiable credentials</a>, the claims of the
<a>verifiable credentials</a>, and its own policies.
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</p>

<p>
In particular, Sections <a href="#terms-of-use"></a> and
Expand Down Expand Up @@ -4629,14 +4651,15 @@ <h3>Bearer Credentials</h3>
</p>
</section>

<section class="informative">
<h3>Validity Checks</h3>
<section class="normative">
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
<h3>Validation</h3>
jandrieu marked this conversation as resolved.
Show resolved Hide resolved

<p>
When processing <a>verifiable credentials</a>, <a>verifiers</a> are expected to
perform many of the checks listed in Appendix <a href="#validation"></a> as
well as a variety of specific business process checks. Validity checks might
include checking:
When processing <a>verifiable credentials</a>, <a>verifiers</a> MUST
evaluate any relevant <a>claims</a> before relying upon them. This
evaluation may be done in any manner desired, as long as it satisfies
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
the requirements of the <a>verifier</a> doing the validation.
Many verifiers will perform the checks listed in Appendix <a href="#validation"></a> as well as a variety of specific business process checks such as:
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</p>

<ul>
Expand All @@ -4661,8 +4684,9 @@ <h3>Validity Checks</h3>
<p>
The process of performing these checks might result in information leakage that
leads to a privacy violation of the <a>holder</a>. For example, a simple
operation such as checking a revocation list can notify the <a>issuer</a> that a
specific business is likely interacting with the <a>holder</a>. This could
operation such as checking an improperly configured revocation list can
notify the <a>issuer</a> that a specific business is likely interacting
with the <a>holder</a>. This could
enable <a>issuers</a> to collude and correlate individuals without their
knowledge.
</p>
Expand Down Expand Up @@ -5303,10 +5327,12 @@ <h4>Unauthorized Use</h4>
</p>
<h4>Inappropriate Use</h4>
<p>
While valid cryptographic signatures and successful <a href="#validation">validity checks</a>
While valid cryptographic signatures and successful status checks
signify the reliability of credentials, they do not signify that all credentials
are interchangeable for all contexts. Toward the pursuit of appropriate use,
it is crucial to consider the source and authenticity of the information. For
are interchangeable for all contexts. It is crucial for verifiers to
also validate any claims which might be relevant, considering the source and nature of the claim as well as privilege or service for which the credential is presented.
</p><p>
For
instance, in scenarios where a certified medical diagnosis is required, a self-asserted
<a>credential</a> carrying the necessary data might not suffice because it lacks validity from an
authoritative medical source. To ensure the propriety of <a>credential</a> use,
Expand Down Expand Up @@ -5639,7 +5665,8 @@ <h3>Proofs (Signatures)</h3>
The digital signature provides a number of protections, other than tamper
resistance, which are not immediately obvious. For example, a Linked Data
Signature <code>created</code> <a>property</a> establishes a date and time
before which the <a>credential</a> should not be considered <a>verified</a>. The
before which the <a>credential</a> should not be considered <a>verified</a>, separate from the validity period of the credential. This property describes the validity of the proof, not of the credential.<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
Expand All @@ -5658,7 +5685,7 @@ <h3>Validity Periods</h3>
The <code>validFrom</code> and <code>validUntil</code> properties are expected
to be within an expected range for the <a>verifier</a>. For example, a
<a>verifier</a> can check that the end of the validity period of a <a>verifiable
credential</a> is not in the past.
credential</a> is not in the past. Because some credentials can be useful for secondary purposes even if their original validity period has expired, validity period, as expressed using the validFrom and validUntil properties, is always considered a component of validation, which is perforemed **after** verification.
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</p>
</section>

Expand Down
37 changes: 23 additions & 14 deletions terms.html
Original file line number Diff line number Diff line change
Expand Up @@ -51,9 +51,12 @@
</dd>
<dt><dfn data-lt="entities|entity's">entity</dfn></dt>
<dd>
A thing with distinct and independent existence, such as a person,
organization, or device that performs one or more roles in the ecosystem.
</dd>
Anything that can be referenced in statements as an abstract or concrete noun.
Entities include but are not limited to people, organizations, physical things, documents,
abstract concepts, numbers, and strings. Any entity may perform roles
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
in the ecosystem, if it is capable of doing so. Note that some
entities fundamentally cannot take actions, e.g., the string "abc"
cannot issue credentials. </dd>
<dt><dfn data-lt="graphs">graph</dfn></dt>
<dd>
A network of information composed of <a>subjects</a> and their relationship
Expand All @@ -62,8 +65,9 @@
<dt><dfn data-lt="holders|holder's|holders'">holder</dfn></dt>
<dd>
A role an <a>entity</a> might perform by possessing one or more
<a>verifiable credentials</a> and generating <a>presentations</a> from them.
A holder is usually, but not always, a <a>subject</a> of the <a>verifiable
<a>verifiable credentials</a> and generating <a>verifiable presentations</a> from
them.
A holder is often, but not always, a <a>subject</a> of the <a>verifiable
credentials</a> they are holding. Holders store their <a>credentials</a> in
<a>credential repositories</a>.
</dd>
Expand Down Expand Up @@ -123,14 +127,19 @@
A program, such as a browser or other Web client, that mediates the
communication between <a>holders</a>, <a>issuers</a>, and <a>verifiers</a>.
</dd>
<dt><dfn data-lt="credential validation">validation</dfn></dt>
<dt><dfn data-lt="claim validation">validation</dfn></dt>
<dd>
The assurance that a <a>verifiable credential</a> or a
<a>verifiable presentation</a> meets the needs of a <a>verifier</a> and other
dependent stakeholders. This specification is constrained to <a>verifying</a>
<a>verifiable credentials</a> and <a>verifiable presentations</a> regardless of
their usage. Validating <a>verifiable credentials</a> or
<a>verifiable presentations</a> is outside the scope of this specification.
The assurance that a <a>claim</a> from a specific <a>issuer</a> satisfies
the business requirements of a <a>verifier<a>
for a particular use. This specification defines how verifiers
verify<a>verifiable credentials</a> and <a>verifiable presentations</a>.
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
<br/>
It also specifies that Verifiers MUST validate claims in VCs before
relying on them. However, the means for such validation vary widely and
are outside the scope of this specification. It is expected that
verifiers will trust certain issuers for certain claims and apply their
own rules to determine which claims in which credentials are suitable
for use by their systems.
jandrieu marked this conversation as resolved.
Show resolved Hide resolved
</dd>
<dt><dfn data-lt="verifiable credential|verifiable credentials|vc|vcs">verifiable credential</dfn></dt>
<dd>
Expand Down Expand Up @@ -159,11 +168,11 @@
<dt><dfn data-lt="verify|verified|verifying|verifiable|verifiability">verification</dfn></dt>
<dd>
The evaluation of whether a <a>verifiable credential</a> or <a>verifiable presentation</a>
is an authentic and timely statement of the issuer or presenter, respectively.
is an authentic and current statement of the issuer or presenter, respectively.
This includes checking that: the credential (or presentation) conforms to the specification; the proof method is
satisfied; and, if present, the status check succeeds.
Verification of a credential does not imply evaluation of the truth
of <a>claims</a> encoded in the credential.</a>.
of <a>claims</a> encoded in the credential.

</dd>
<dt><dfn data-lt="verifier|verifiers|verifier's|credential verifiers|credential verifier's">verifier</dfn></dt>
Expand Down