w3c / vc-data-model

W3C Verifiable Credentials Working Group — VC Data Model and Representations specification

Verifiable Credentials Data Model and Representations

Credentials are a part of our daily lives; driver's licenses are used to assert that we are capable of operating a motor vehicle, university degrees can be used to assert our level of education, and government-issued passports enable us to travel between countries. This specification provides a mechanism to express these sorts of credentials on the Web in a way that is cryptographically secure, privacy respecting, and machine-verifiable.

We encourage contributions meeting the Contribution Guidelines. While we prefer the creation of issues and Pull Requests in the GitHub repository, discussions also occur on the public-vc-wg mailing list.

Verifiable Credentials Working Group

• Group page: https://www.w3.org/2017/vc/WG/
• Charter: https://www.w3.org/2022/06/verifiable-credentials-wg-charter.html
• Chairs
  • Brent Zundel - @brentzundel

Verifiable Credentials github repos

• Use Cases
• Data Model
• Implementation Guide
• Data Model Test Cases

Discussion Forums

• W3C Credentials Community Group Mailing List (Incubation)
• W3C Verifiable Credentials WG Mailing List (Standardization)

Process Overview for VC Data Model Pull Requests

1. Anyone can open a PR on the repository. Note that for the PR to be merged, the individual must agree to the W3C Patent Policy.
2. Once a PR is opened on the v2.0 branch, chairs and editors make judgement call on whether changes are substantive or editorial.

   Editorial

   Mark with "editorial" tag

   Substantive

   Mark with "substantive" tag.

3. W3C CCG is automatically notified of PRs as they are raised and discussed.
4. PRs are usually merged in 7 days if there is adequate review and consensus, as determined by the Chairs and Editors.

Roadmap for 2022-2024

The VCWG has a set of deliverables and a timeline listed in the most recent VCWG charter

Debugging Github Pages Build Errors

There are times where Github Pages will fail to build with nondescript errors such as "Page build error." or "Symlink does not exist within your site's repository". You will need to run github-pages locally to debug such errors. To run github-pages, which uses Ruby and Jekyll locally, you will need to set up a working Ruby and Bundle environment.

After you have installed Ruby and Bundle, you will need to do the following:

gem install jekyll github-pages

Then create a Gemfile file in the top level directory with the following contents:

source 'https://rubygems.org'
gem 'github-pages'

Then run the following command:

bundle exec jekyll serve --watch --force_polling

You should be able to see the page build errors in detail upon running the command above.

vc-data-model's Issues

Typo section 2 "abouth"

"or other information abouth the" should be "...about the"

Correlation via frequency of claim issuance

The rate at which an issuer issues claims may be a privacy violation because the holder of those claims may use them in a particular pattern that exposes what the claims are being used for. For example, short-lived over-21 claims being used to correlate that someone went to a particular bar.

3 Types of Claims

Repeatedly when talking to various people using claims, largely from communities doing reputation systems, they make distinctions between 3 types of claims.

R3, a consortium of banks, at https://bitsonblocks.net/2017/05/17/a-gentle-introduction-to-self-sovereign-identity/ says:

Claims would be stored by typing text into standardised text fields, and saving photos
or scans of documents.

Proofs would be stored by saving scans or photos of proof documents. However this
would be for backward compatibility, because digitally signed attestations remove the
need for proofs as we know them today.

Attestations – and here’s the neat bit – would be stored in this wallet too. These would be 
machine readable, digitally signed pieces of information, valid within certain time windows.
The relevant authority would need to sign these with digital signatures – for example,
passport agencies, hospitals, driving licence authorities, police, etc.

Need to know, but not more: Authorities could provide “bundles” of attested claims, such
as “over 18”, “over 21”, “accredited investor”, “can drive cars” etc, for the user to use as they
see fit. The identity owner would be able to choose which piece of information to pass to
any requester. For example, if you need to prove you are over 18, you don’t need to share
your date of birth, you just need a statement saying you are over 18, signed by the relevant 
authority.

This also come up with the Portable Reputation Toolkit from #RebootingWebOfTrust at https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-fall2016/blob/master/final-documents/reputation-toolkit.pdf

A user creates a Distributed Identifier (DID).
They get an accompanying private key that they use
to sign assertions.

A user makes an *Assertion* using a JSON-LD claim
format. It is signed with their DID and timestamped
with a decentralized timestamping service like Open
Timestamps. The assertion includes the submitter’s
DID and a target identifier that the the assertion is
about. Later claims can evaluate or invalidate the
statements by pointing to the assertion.

Users publish *Evidence JSON-LD claims. Evidence
is signed by a user’s DID. Evidence JSON-LD claims
link to media, with a unique identifier. The evidence
doesn’t have to be related to any assertion initially.
Evidence can be related to any assertion at any time
using an evaluation.

Any user can challenge or support an earlier
assertion with an *Evaluation*. An evaluation
references an assertion and evidence. It supports or
refutes the assertion. This evaluation will always
point to an assertion, and have a true/false or 0-1
float value judging its "truthfulness". Evaluations
are signed by the creators DID and timestamped.

The end user validates the truthfulness of an
assertion by querying evaluations and evidence
associated with it using an algorithm called a Filter.
Users can develop a list of trusted evaluators for
themselves, import a list from others, or use a filter
template that includes evaluator trust parameters
and weightings. The filter factors in the evidence,
the evaluations, and the trust in the reputation of
each of these to determine the truth or falsehood of
the assertion. The user can apply multiple filters and
audit the Filter to gain multiple perspectives.

Proof of Age insufficient for some regulatory requirements

Note that even if one may desire to remain anonymous when purchasing alcohol, a photo ID may still be required to provide appropriate assurance to the merchant. The merchant may not need to know your name or other details (other than that you are over a certain age), but in many cases a mere proof of age may still be insufficient to meet regulations. We need to mention language in the specification calling this out specifically.

DID Documents as self-signed Verifiable Claims

From @ChristopherA on June 30, 2017 7:20

The current DID implementors spec for DIDs just has the DDO being a signed JSON-LD blob.

I've always been inclined that instead it should be a self-signed verifiable claim, pointing to itself. This may be a minor point but that is the way I've always thought of the trusted root ever since the days of Ronald Rivest's SDSI.

I believe this is what @msporny and @dlongley are doing with their DDO method. Can you guys share what your DDO looks like?

Copied from original issue: WebOfTrustInfo/btcr-hackathon-2017#8

Ideas for roles to add to the data model for next draft

Some of these terms are already defined and this is just my way of expressing them in single framework to layout some other roles and dependencies/relationships.

• An Issuer issues claims about Subjects using Identifiers
• Subject is the party about whom the claim is made and can be a:
o Person
o Thing
o Entity
o Artificial Intelligence
o Other?
• An Asserter of a claim is the party submitting the claim to an Inspector and can be:
o Subject
o Holder
o Broker
o Agent
• Seekers are parties looking for specific claims or claim elements who have not yet been authorized by the Subject of a claim to receive the claim
• Broker is a party that facilitates connections and exchange between Subjects and Seekers in regard to a claim
• Agent is a party acting on behalf of a Subject
• Inspector accepts claims or claim elements from Asserters
• Verifier is a party that determines the elements of a claim necessary for validity are present and current and that its contents and status are consistent and fedelitous with the issuer’s terms and purpose
• Accessors are those with permission to examine some or all of the contents of a claim
• Claimvelope is the encapsulation of the contents of claim and securing said contents from unauthorized access, use, or modification
• Claimvelope Label contains the data necessary to facilitate transmission and verification of a claim and to gain or request access to some or all of the contents.
• Published Claims are claims made public by the subject of a claim in which the claim and subject are revealed and such a revelation is allowed by the terms of issuance
• Discoverable Claims are non-public claims that can be queried, if allowed, to determine if it contains attributes of interest to a Seeker
• Identifiers are methods of associating a Subject with a claim and can be:
o Anonymous
o Pseudo-nonymous
o Veri-nonymous

Correlatability of bearer claims

We should make it clear that even bearer claims can be correlated. For example, claims that contain personally identifiable information or unique identifiers can be correlated. Bearer claims can be tracked based on usage patterns.

Should commenting by adding Github issue be mentioned in Status section?

"Status" currently includes this sentence about commenting on the document:
“If you wish to make comments regarding this document, please send them to [email protected] (subscribe, archives).”

Should the method of creating Github issues (like this one) also be included?

List all validity checks that should be performed

We should make it clear that an inspector (e.g. corporation) is required to check revocation via the Issuer (e.g. government). In fact, there are many different types of validity checks that should be performed on data, such as the revocation status of an Issuer's signing key, the expiration date of the claim, etc.

Challenges in Understanding Spectrum of Integrity/Inspection/Validation/Verification/Confirmation/Revocation

From @kimdhamilton on July 15, 2017 23:8

From @ChristopherA on July 12, 2017 0:7

(this is a pre-draft of a post to be an issue on https://github.com/w3c/vc-data-model/issues/ or possibly added to #58 once it is more thought out)

As evidenced by the failure of polling in the W3C Verifiable Claims WG last week on the name of the role of Validator vs. Inspector, and the lively discussion in the WG meeting today https://www.w3.org/2017/07/11-vcwg-minutes.html, we lack a really good model for describing the multiple actions that happen in our verifiable claim architecture, in particular when blockchain-based DIDs are being used.

In addition, our whole industry has been terribly bad at the practical considerations as to the issues of how revocation should be designed. I personally have experienced this with SSL/TLS, which for almost a decade and a half had only lip-service support of revocation, and even now is still being challenged to deploy more advanced solutions

So I want to walk through DID:BTCR from the vantage point of a number of steps that fall into the Integrity/Inspection/Validation/Verification/Confirmation/Revocation spectrum of roles.

First, please forgive in advance the specific words I'm using below — they are used more to signify the different placeholders as opposed to a well thought out proposal as which words should be used.

---

In our #RebootingWebOfTrust User Story Alice, our pseudo-anonymous programmer. daughter of immigrants, has heard that Bob, a refugee advocate has a need a mobile phone app. Fearing that her own extended family might be harmed if she is revealed to be helping Bob, she wishes to introduce herself and present credentials that she is qualified for the work, but remain pseudo-anonymous.

So first she establishes a DID and self-signed DDO. She has a professional colleague and friend Donna with a public persona (i.e. not anonymous) who indirectly knows Bob through yet another colleague (i.e. Bob & Donna share a trust network but connected by multiple-degrees of separation).

Donna issues a Verifiable Claim that she "knows" Alice and she is willing to attest to her competence in mobile development, which Donna gives a signed copy of back to Alice. Alice counter-signs this claim and adds it to her DDO (this is something unique to the very self-sovereign BTCR method, and may not apply to other methods).

Alice then sends a response to Bob's request for programming assistance, along with the claim issued by Donna.

---

Now we dive into some mechanics:

Bob receives this offer from Alice (possibly itself a self-signed claim) along with the claim issued by Donna. The first thing his software does is do an INTEGRITY CHECK of the claim itself. Is it properly formed? Has it expired? Is it properly signed by the issuer? Is it properly countersigned by the subject? If it fails any of these INTEGRITY CHECKS, Bob will not even know about it, and the whole message and claims will be rejected.

The next thing the software MAY do is INSPECT INTO the claim the DID number found in Donna claim. This will typically be automatic, but if Bob is hyper-concerned about internet traffic correlation (as he is advocating against a nation-state) it may require a human to decide if they wish to proceed further. But Bob is an EU citizen and feels sufficiently protected, so his software is set to INSPECT INTO automatically.

The first DID is Donna's. His software INSPECTS INTO the Bitcoin Blockchain for the appropriate transaction, and then looks at the first TXOUT of that transaction to see if it has been spent. In this case, it has, so this transaction cannot be VALIDATED. However, it has not failed, so the software now goes forward to that new transaction (the "tip" of the DID chain).

This time the software INSPECTS INTO this transaction's first TXOUT, and is not spent and there is a properly formatted op_return pointing to a DDO, which reside's on Donna's github account. The software now INSPECTS INTO and finds the DDO.

Now the the software does an INTEGRITY CHECK on the DDO, and if is, then it VALIDATES the DDO by comparing it to the owner key that is found from signature used to send transaction to the Bitcoin Blockchain that the INSPECTION CHECK revealed. If they match, both the DID and the DDO are now VALIDATED.

However, the claim itself was not signed by the owner key so it is not VALIDATED yet. So the software INSPECTS INTO the DDO, and finds another key (either looking through all the appropriately listed keys, or possibly because of a hint added in the claim). If the signature on the claim matches, now the claim issuer is VALIDATED.

However, the claim makes a statement to yet other DID, so it not yet VERIFIED, only VALID. The software must now do the same set of operations on Alice's DID to INSPECT INTO her DID and determine if it too can be VALIDATED.

Finally, if both the issuer's DID and subject's DID are VALID, (which includes the previous INTEGRITY CHECK of Donna's claim and Alice's countersignature of Donna's signature on the claim) the claim is now VERIFIED (thus it is called a "Verifiable Claim").

However, this verified claim is not yet CONFIRMED. In order to be CONFIRMED, Bob's Web-of-Trust CONFIRMATION criteria needs to be met. In this case, **Donna" is a third-degree connection, making Alice a fourth-degree connection. Over half of the world is a fourth-degree connection!

In this case, the software kicks out the claim for Bob to make a decision on (i.e. the claim and DIDs are both VALIDATED and VERIFIED, but not CONFIRMED). He decides to look further into what Donna is willing to share in her DID. In this case, Donna is vaguely known to him ("a familiar stranger") and her github repository is active and has a long history of mobile development. He looks now at what Alice shares in her DID, and it is almost nothing, and has no personal info. However, her response to his request for proposal is interesting, and he hasn't found anyone yet, so he decides to CONFIRM and accept this claim to give her a trial.

If Alice fails her trial, Bob will change his criteria to never waste any time on her again, or even possibly never even bother to look at CONFIRMING any more Donna's claims (a locally-negative trust, but is non-transitive to others in the self-sovereign scenario required by the BTC method).

However, Alice doesn't fail her trial, and later Bob issues her a new claim saying that he also liked Alice's work, and maybe even issues a claim that countersigns Donna's original claim, showing appreciation for Donna's good recommendation.

(the next section will discuss when things go wrong, aka REVOCATION)

Copied from original issue: WebOfTrustInfo/btcr-hackathon-2017#33

Copied from original issue: WebOfTrustInfo/rwot5-boston#12

Insight for DID spec: proofs, not keys

From @ChristopherA on July 14, 2017 7:31

An insight from the work this week is we should not be talking about owner key, or control key, etc.

Instead, we should be talking about proofs.

For instance, this fragment from a DDO

{
"control":
[{
"control-bond": 1.25
"rotate-proof": [{
"proof-type": "pubkeyhash",
"bond-value": 1.25
"hash-base58check": "mvZ3MyLgsvYr87GGSbsPBWEDduLRptfzEU"
}]
},{
"revocation-proof": [{
"bond-value": 1.25
"proof-type": "pubkeyhash",
"hash-base58check": "mvZ3MyLgsvYr87GGSbsPBWEDduLRptfzEU"
}]
}

It basically says that for control (which permits rotating the owner key and the DDO address) that there are two subtypes, a rotate proof and a revocation proof. In another ddo system the proof-type could be "signature", or even "revocation list".

Similar with owner (which permits updating of the keys allowed to issue claims, and the other content of the DDO, but not the control key or the DDO address), it can be proofs as well which may not just be signatures.

cc: @talltree @msporny @dlongley

Copied from original issue: WebOfTrustInfo/btcr-hackathon-2017#39

Tokenize to prevent sharing information with the wrong party

It is important that issuers tokenize identifiers (like bank account numbers) when possible. It is also important to grant rights to a service via cryptographic mechanisms, such as proving that a set of verifiable claims are owned by a particular party.

Atomize information for principle of least authority

We should include information in the spec that states that when issuing information, one should issue it in the smallest pieces possible. When requesting information, only ask for the data points that you need. Issue abstract claims alongside actual data when possible.

RDFS / OWL for VC vocabulary?

Hello, I'm curious if there are plans to define an RDF schema or OWL ontology for the VC vocabulary. E.g. what would be the rdfs:domain and rdfs:range of the cred:claim property?

Confused by json-ld inclusions in JSON examples 3 and 5 -- is this correct?

See section:
4.1.2 Expressing Entity Credentials in JSON

Why is json-ld used in two examples under this JSON section, in Examples 3 and 5?

I'm not versed in either json-ld or JSON more than the small amount I've seen while on the Web Payments and VC mailing lists, which isn't a lot, so I'm coming to this section relatively cold. And I find it confusing: in fact they look like full-blown json-ld examples, and if so, it must be an error, and they should be in the following section, 4.2.

A second possibility: is json-ld and @context actually required within JSON, in section 4.1.2, to achieve Examples 3 and 5? It seems odd if that's true, and the naive reader might need a little explanation of that, considering that the next section, 4.2, is supposedly the json-ld section.

Third, if it's not an error, yet not a necessary part of JSON code, then my last guess is that json-ld in those examples was merely chosen as an (aribtrary) instance of a type of code or organization; and if so then I believe a different one should be used, since, again, that is confusing as regards the actual json-ld examples in the following section, 4.2.

And finally, if none of those are true, then people reading this document who don't write these types of code are still going to need some help in understanding what those json-ld code bits are doing under the JSON heading. :-)

Expiration versus Revocation

When a claim issuer limits the duration or similar condition for use of a claim it should be considered an expiration. This could include something as simple as the time for which it is allowed to be used or a business model requirement like the subject has a current paid subscription, attending X hours of continuing education, or a membership that includes the claim as part of that business model. An expired claim can be known to have existed like license a subject once held but no longer has or is no longer in current issuance. That would allow resume like uses of past claims that have expired.

Revocation would be when some aspect of the validity of the claim has failed such as discovered fraud by the subject, faulty evidence or theory on which the claim was based, a compromise of the security of the claim, misuse of the claim in violation of the terms of issuance, and so on. A revocation would remove the claim from be asserted by anyone and disallow referential uses in resumes or similar use.

An alternate approach to expressing JSON formulations with VC

In at least two parts of the Data Model document there are sections which demonstrate using JSON formulations vs JSON-LD formulations. That is, section 4.1.1 "Expressing an Identity Profile in JSON" vs section 4.2.1 "Expressing an Identity Profile in JSON-LD". There are parallel sections 4.1.2 and 4.2.2 dealing with Entity Credentials. In each case the difference is minor--the JSON version documents the various type assignments, then the JSON-LD says something like "just like the JSON except there is an additional @context value".

Do we really need this parallelism? Why not just have a JSON section that gives the full description (include the @context)? Many newbies don't realize that JSON-LD is still pure JSON and adds no syntax to JSON whatsoever. (In other words, pure JSON parsers work fine on it).

We could still say something to the effect that the JSON boiler-plate is carefully crafted so that folks with specific needs can use it in its JSON-LD. Perhaps in an appendix we could give a further deep dive on what it means to use true linked data concepts and tools.

Our experience is that 80% of standards folks don't need the full power of JSON-LD. They're willing to follow a templated approach. Application coders can use the JSON tools they're familiar with in accompaniment to specialized libraries to do stuff like signing.

The 20% that do need / use / appreciate JSON-LD are those that 1) create the libraries, 2) define the basic templates for a particular set of claims, 3) need more exotic transformations that are provided by JSON-LD libraries or 4) just love the linked data stuff like the true nerds among us.

Once people get comfortable using the JSON level stuff it's much easier to add the extra concepts as they need them.

Net-net: lead with the JSON and soft-pedal the -LD until it's needed and wanted.

Add DO_NOT_CORRELATE flag to Verifiable Claims

It should be possible for a sender of a Verifiable Claim to add a DO_NOT_CORRELATE flag to make their desire to not be correlated concrete.

For example, only releasing email information for the purposes of login and site-wide correlation (and not 3rd party correlation) should be possible via the data model.

Add Accessibility Use Case for under 3.3 Healthcare

This could be better worded, but I rushed to put this together when I noticed the notice to publish FPWD. I could also come up with one for Education.

H.5 Proving Legal Disability Status

Trina, who is legally blind is currently unemployed and needs to use the local free disability ride service to get to the employment office. To use this service she is required to verify that she, in fact, maintains legal disability status. Trina provides her government-issued disability credential to sign up for the ride service, and in doing so it is not necessary for her to disclose her specific disability to the ride service as it could put her at personal risk.

Add section about terms of use

Currently we don't have a section on how the data model supports various terms-of-use scenarios.

There have been discussions about expiry, revocation, and scope of use, but none have matured enough to have made it into the data model.

In particular, we need some distinction between terms of use for a given claim or credential, as set by the issuer, and the terms of use of a given presentation, as set by the controller of the claim.

Without the right hooks in the data model for this, we're propagating legacy problems related to data binding, the right to erasure, and other privacy issues.

FWIW, the UMA work on scope may be of use. https://docs.kantarainitiative.org/uma/rec-uma-core.html

"Inspector-Verifier" terminology is confusing

I'm concerned about the recent decision to pick "inspector-verifier" as a glossary term for the following reasons:

• From a communication and marketing standpoint, it's awkward to say and use alongside the other terminology (issuer, holder, etc.). Having used the term to talk about the ecosystem, it sounds out of place when said out loud on a stage or when talking with customers.
• It makes it seem like there are two roles instead of one.
• It sounds like the Chairs mis-read the IRV poll results, which showed Verifier as the clearly preferred choice.

I suggest we select "Verifier" as the winner because:

• That is aligned with the results of the poll.
• It doesn't lead to confusion over number of roles.
• Its easy for readers/listeners to understand the concept based on the word.

Nesting Signatures with JWT

There is a concern that nesting multiple signatures with JWT results in an exponential increase in the amount of data that needs to be stored. Each "envelope" needs to encapsulate the entirety of the signed data as a base-64 encoded blob. This is an issue for endorsements, counter-signatures, and M-of-N signature schemes. How will nested signatures be supported using JWTs?

Add renewalService URL to standard data model

We may want to provide a verifiable claim refresh/renewal service to a verifiable claim such that it may be automatically renewed upon revocation or expiration. This could help smooth out the experience around "expired credential" use cases such that expired credentials with a renewal service URL could still be considered for use without the individual explicitly having to renew the credential.

Highly dynamic information should have short expiry times

The specification should note that validity time periods should be shorter for highly dynamic information. We should also mention that shorter expiry periods may result in less privacy due to frequency of issuance/use.

Storage location of claims may mine data

We should make it clear that the storage location of claims may mine data or forward data so participants in the ecosystem should be wary of those business models. Systems that don't mine data may be able to use that feature as a competitive advantage. We should be clear that even though this system is privacy-enhancing, that it is not a panacea.

Composing JWT documents

What is the data model for composing JWT documents. For Linked Data Signatures, the approach utilizes a graph-based data model to "merge" the data together. Is this same approach valid for JWT-signed data? Do we assume a graph-based data model and merge using the same rules, ignoring the JSON tree structure? Or do we have to specify how different JWT documents are merged together? We need examples of how this is done.

Add display hints to data model, for example: information to use a Web Component

We should consider having something in the data model that specifies how to display a credential in a consistent way, for example, a link to a Web Component for rendering a verifiable claim/credential. This would allow independent displayers of VCs to be able to pull in custom components for rendering claims/credentials in specific and consistent ways.

Note that there are privacy concerns related to this -- as when displayers request custom component HTML it will leak information (i.e. that the displayer wants to display that particular type of VC ... and we need to be careful that this doesn't uniquely identify someone). There are also security issues -- users getting fooled by displays that misrepresent the credential information.

What would a counter-signed RWoT claim look like?

From @ChristopherA on July 14, 2017 22:43

Using my DID (the latest value from Shannon's code), and signing a verifiable claim (created from the verifiable claims playground and signed with my correct testnet private key I used to create the DID transaction) I get:

{
  "@context": [
    "https://schema.org/",
    "https://w3id.org/security/v1"
  ],
  "claim": {
    "id": "did:btcr:xyv2-xzyq-qqm5-tyke",
    "alternate-name": "ChristopherA",
    "knows": {
      "id": "did:btcr:rzqq-qqqq-uvlj-ez",
      "alternate-name": "Alice"
    }
  },
  "signature": {
    "type": "EcdsaKoblitzSignature2016",
    "created": "2017-07-14T22:38:36Z",
    "creator": "ecdsa-koblitz-pubkey:02b97c30de767f084ce3080168ee293053ba33b235d7116a3263d29f1450936b71",
    "signatureValue": "IGbDlNVSLIk7//rnuEEw7vtRKQ1HFLb+/K0cFHZ80zcVbFkF6vQj+jtDANc0MD9o0nhL5ykGFTd1VoP7a7B2iqM="
  }
}

This should be (hopefully and eventually) inspectable, validatable, verifiable and confirmable.

However, under the BTCR method, we are extremely self-sovereign centric, so this claim is not considered to be valid until it is countersigned by Alice.

@dlongley What would that extra countersignature look like?

Copied from original issue: WebOfTrustInfo/btcr-hackathon-2017#45

Should spec include WebIDL and XML expressions

Should the VC Data Model spec contain WebIDL and XML expressions of the data model?

Dependent claims should be bundled

Dependent claims should be bundled together so they're not used for the wrong purposes. Separating claims may result in their use in an unintended way, such as a proof of age being used to buy alcohol when the issuer never intended their set of issued claims to be used for that purpose.

Design choices in expressing a verifiable claim

There are a number of design choices needed in expressing a real verifiable claim. I’m working with an IMS group that is designing a VC to represent a college transcript. The questions that are emerging here might very well be generic and could be the basis of normative best practices for the data model document.

The central issue is how skinny or fat should a VC be. For example, the group wants a number of informational fields about the issuer: address, phone, name of issuing person. Should these be included in the VC or is it assumed that they should be gotten by dereferencing the issuer URI?

Arguments in favor of including informational fields embedded in the VC:

1. The transcript data model can standardize the vocabulary of these fields whereas the “foreign information” in the dereferenced URI might not follow any standardized practices for such vocabulary.
2. The foreign information isn’t itself verifiable. That is, unless the URI itself points to another VC from the issuer.
3. Even if the foreign information is signed that signed data might not be synchronized with the claims made about the issuer within the local VC. For example, an issuer might be an institution that had an engineering program at the time the local VC was signed but no longer has such a program.
4. The VC becomes more readable without needing to dereference anybody. Especially important for disconnected devices.

Arguments against including informational fields embedded in the VC:

1. Some of the informational data is not critical in the signing. For example, the textual course description might change frequently in minor ways without implying in real change of underlying competencies.
2. Such an approach violates principles of data normalization that we’ve used for years in database design. (Which BTW may be irrelevant in this context).
3. “Identity Minimalization” (as stated in the Christoper Allen’s (@ChristopherA) blog post “The Path to Self-Sovereign Identity”) asserts that “When data is disclosed, that disclosure should involve the minimum amount of data necessary to accomplish the task at hand”.

What I think we need are a set of guidelines for what properties is meaningful to include in the VC.

Unsigned claims not secure

Claims that are not digitally signed are not verifiable. The specification should allow unsigned claims, but should say something about claims that are unsigned.

Add section on Revocation

It is currently not clear how Verifiable Claims may be revoked by the issuer. We should add a section to the specification that clarifies the various mechanisms for revocation of claims.

Discussion on this issue started here: w3c/vc-use-cases#33 (comment)

Bootstrapping Simple WoT Verifiable Claims

I’m puzzling through some simple verifiable claims for bootstrapping some of the basic functions of the classic web of trust (both explicit what actually existed, as well what people falsely believed to be claimed.

The first kind of claim I’d like to build is that did::Alice knows did::Bob.

Knows is part of https://schema.org/Person

The simplest verified claim in Figure 8 of https://opencreds.github.io/vc-data-model/ (less the signature) is:

{
  "@context": [
    "https://w3id.org/identity/v1"
   ],
  "id": "http://example.gov/credentials/3732",
  "type": ["Credential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov",
  "issued": "2010-01-01",
  "claim": {
    "id": "did:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  }
}

Modifying this for did::Alice and did::Bob and modify this claim for knows:

{
  "@context": [
    "https://w3id.org/identity/v1"
   ],
  "id": "did::Alice#THISCLAIM",
  "type": "Person",
  "issuer": "did::Alice",
  "issued": "2017-01-01",
  "claim": {
    "id": "did::Alice",
    "knows": "did::Bob"
  }
}

QUESTION ONE: So my first question is “id”: “did::alice#THISCLAIM” correct? Or a URL where this claim is stored? If I put this claim anywhere in my DDO, is it just did::Alice? How I can I point to a specific spot in a JSON-LD based DDO where this claim is added?

Now at this point there is no cryptographic proof that Alice knows Bob (and in fact, Alice & Bob are not even human readable names, just DID number). It is just a signed claim:

{
  "@context": [
    "https://w3id.org/identity/v1",
    "https://comakery.github.io/json-ld.org/schemas/security-v1-patch.jsonld"
  ],
  "id": "did::Alice#THISCLAIM",
  "type": "Person",
  "issuer": "did::Alice",
  "issued": "2017-01-01",
  "claim": {
    "id": "did::Alice",
    "knows": "did::Bob"
  },
  "signature": {
    "type": "EcdsaKoblitzSignature2016",
    "created": "2016-12-13T19:24:12Z",
    "creator": "ecdsa-koblitz-pubkey:02c490e19e936efab022bd9fc12833db082706473fd96cec14c4a8dac058a0dbee",
    "signatureValue": "HwMjpgikyk6htrUATmj6r5XXxBFZ/gvaRD9Ti6LNC7YRdluYVX0Tz1fiXFQLtpNNl0umDkINUNf7l+ByH2SloKc="
  }
}

And in fact in the schema, “knows” requires that the relationship be reciprocal, so there needs to be a Bob knows Alice.

QUESTION TWO: How does Bob, having received this claim from Alice, make a new claim that incorporates BOTH claims, making the “knows” reciprocity valid.

QUESTION THREE: How does Alice, having received a double claim (her original, and Bob’s reciprocal claim) incorporate all of them into here DDO’s JSON-LD?

We still have no proofs. We have two claims, that are reciprocal, but we Alice can’t prove that she has validated any keying material from Bob such that she really prove anything — there isn’t even any proof that the Bob she knows had control of the keying material used to sign.

Presumably, Alice can encrypt to Bob’s public key a nonce, which bob decryptst, encrypts, add another nonce, and return (or if using Schnorr sig construction, some type of non-interactive key exchange using ECDH values.) At this point, the claim is more than knows, it is that it has been validated or assessed via some mechanism.

QUESTION FOUR: How is this cross-validation of control of the keys done? There is a nonce available in the signature format, but I’m not sure it makes cryptographic sense here to reveal it publicly in a verified claim. Is this a separate claim from knows, or a validation/assessment of the

Possibly relevant, there is also an AssessAction at http://1.schemaorgae.appspot.com/AssessAction which is part of http://1.schemaorgae.appspot.com/Action — is it is incompatible with Verifiable Claims?

Summary: The most basic web-of-trust function is that anonymous IDs 67889 knows 5679 and that each have validated each others keys securely in some store-and-forward fashion. Solve the above and we have a start to WoT.

Next items after this: A claim that Bob is a natural person. That my nickname for Bob is “Bob”. That my human trust level of Bob’s in a particular trust context has a rating (for instance “I believe that Bob is careful with his keys and careful with his claims). That I consent to accept/read introductions from people that “Bob” knows with one degrees of separation, without Bob’s active participation, or two degrees with. That Bob has ‘eyes on” 2 hours peer reviewing of file x of software build y, under review criteria of “academic” or “security” or “xxxx”.

Once we have a basic draft of some of these, I’d like to circulate this to the larger #RebootingWebOfTrust community that are considering adoption of Verifiable Claims, to the larger WoT community to validate the web-of-trust assumptions.

Origin-bound claims are more privacy-aware

Single-use, origin bound claims are generally safer than long-lived claims. We should mention this in the privacy considerations section.

Linked Data in JWTs

Is the approach that we've taken to embed Linked Data in JWTs valid? Is it okay to just include JSON-LD data in a JWT? Should we be embedding NQuads instead? What is the most appropriate format for expressing data in a JWT and JSON-LD?

Add section/language about presentation of claims

The dominant mental model is that a singular claim is issued and later presented to an inspector. However, there has been significant discussion about how a subset of a credential may be presented as well as how claims from multiple issuers may be aggregated for presentation.

This significantly impacts privacy around the issue of minimal disclosure and selective disclosure.

In particular, what is the thing that is presented when it is not a single credential from a single issuer? Given a name for that we can flesh out how a controller might construct such presentations from multiple credentials. Right now, there is no language about this.

Correlatability of usage patterns

When and how verifiable claims are used is important for correlation purposes. It is important that implementers are aware and may warn their customers of correlation patterns.

Favoring abstract claims

We need text in the specification that notes that all ecosystem participants should favor “proof of” vs. “actual data”. Example: overAge: 21 vs. birthdate. There are benefits for issuers, holders, and inspectors; we should specify what these are.

"Verifiable Claim" as a concept without a direct data model mapping

I think that "Verifiable Claim" is a concept that does not actually have a direct mapping in our data model, yet we are trying to shoehorn it in. The implementations don't support it. I think we're (mistakenly) trying to say "Here is where the verifiable claim is in the data model" simply because the work is called "Verifiable Claims Data Model".

Instead, we should embrace that "Verifiable Claims" is an overarching concept only. You do not make a claim "verifiable" by putting it into a "Verifiable Claim" or anything of that sort. You do not simply attach a signature to a claim to make it "Verifiable" in our data model.

Instead, you create an "Entity Credential", which includes a number of other important properties (such as the issuer of the credential) and you place one or more claims inside of it. Then the credential is signed, making the entire element verifiable -- a "Verifiable Credential".

We should not have a "Verifiable Claim" in the data model. In my view, we should have: "Claim", "Verifiable Credential", and "Verifiable Profile".

A Claim is simply a statement about a particular subject, the subject having a typically pseudonymous identifier.

A Verifiable Credential includes N Claims, who made those claims, expiry information, revocation information, (so on) and a mechanism (e.g. a digital signature) for verifying authorship. Most of our data model revolves around this.

A Verifiable Profile includes N Claims, which may be backed by M Verifiable Credentials (thus making the Profile verifiable) that can be used to verify the authorship of those Claims, and a mechanism (e.g. a digital signature) for verifying proof of possession of the pseudonymous identifier that links all of the Claims together.

Three identical typos of "representd", sections 4.1.1, 4.1.2, 4.3.2

Should all be "represented" in "MUST be representd as a Boolean type" in sections 4.1.1, 4.1.2, 4.3.2.

Repo Needs README.md

This repo needs a README.md document, in case you arrive in it via a google or github search.

Are JWTs appropriate for Verifiable Claims?

I've been a big fan of JWTs. In fact, in a recent revamp of IMS Global's LTI web service security we've added JWTs as a favored mechanism for generating bearer tokens.

But I have reservations of using JWTs for all but the simplest Verifiable Claims (if at all). It seems to me that JWTs are optimized for just what the acronym implies: creating a token. A token, to me, is a small thing. It may carry some state; for example, access control cues. The fact that it's signed ensures that the access control parameter can't be tampered with. That's good. And the fact that its 3 zones are base64-encoded means it will travel easily as a bearer token.

But there are problems using it for a rich verifiable claim.

1. A rich verifiable claim, like an extended Transcript, can be a deeply nested, highly interlinked structure. It seems counter-intuitive to me to tokenize it. Furthermore, problems with more complex signature structures (nested, etc) have already been noted.

2. Structurally it looks inside-out to our VC structure which has the signature embedded within the claim. In the JWT case the entity credentials are inside the JWT with the signature on the outside contained in the obfuscated JWT.

3. While I understand that tooling is beyond the scope of this document, isn't it going to be painful to use JSON-LD tools to work on artifiacts embedded in a JWT?

Perhaps, if there's interest among the JWT community of experts, something can be done to ameliorate these issues.

Is the WebIDL expression necessary?

Do we need to specify the WebIDL expression of Verifiable Claims in the same document? Should it be in a separate document? It feels pretty heavy-weight in the current document.

Why is the Identity Profile not included in the list of "standardization work"?

In the Introduction there are "two pieces of possible standardization work": 1) data model of entity credentials and 2) specific representations in different syntaxes. Why isn't the Identity Profile Model (cf section 3.2 of this document) included in that list? If it's more fully described in some other document or standard, then that should be referenced. If it's defined herein, it should be added to this list.

Unclear on antecedent of "agent" in Entity Credentials capabilities

In section 1 of the vc-data-model there is a list of capabilities for Entity credential holders. One of them is: "Entity credential holders that share verifiable claims are not required to reveal the identity of the inspector to their agent or to issuers.". On initial reading I've taken the agent to mean the agent of the Entity credential holder. If that's true that would imply that the holder's own agent doesn't have the identity of the of the issuer or the inspector. (refer to Architecture Block Diagram in section 3 of the Architecture document for a diagram of these entities).
I've always understood that the VCTF architecture provided an insulation protecting the identities of issuer from inspector and vice versa. But if the above sentence is correct then even the holder's agent is barred from this knowledge. Is this correct?

Define ONE concrete format for the revocation parameter

What is the simplest format of the revocation parameter?

Perhaps something like this:

{
  "revocation": {
    "id": "https://example.org/revocations/23984",
    "type": "SimpleRevocationList2017"
  }
}

When you dereference the "id" parameter above, options include:

1. a list of strings, which are IDs (e.g. ["https://example.com/vcs/23898239", "https://example.com/vcs/838732", ...]),
2. a list of JSON objects each with an 'id' entry (e.g. [{"id": "https://example.com/vcs/23898239"}, {"id": "https://example.com/vcs/838732"}, ...]),
3. a data-model agnostic list of items that each have an id that is associated with the provided claim (e.g. abstract data model that is defined in the spec, where realizations of the data model are provided in latter JSON/JSON-LD/WebIDL sections)

If the issued verifiable claim's id is in the list of IDs, then its status is revoked. Note that the mechanism used for pseudonymous revocation will be calculated differently, which is why the format of the revocation list is signature scheme specific.

Bad Github Description Link

A github issue — the link in the description at the top of this github pages is a now 404 https://opencreds.github.io/vc-data-model/ — should be to the correct new page.

Multiple subjects in a single credential

Technically, the data model supports a single credential making claims about multiple subjects:

{
  "@context": ["http://schema.org/", "https://w3id.org/identity/v1"],
  "id": "http://example.gov/credentials/3732",
  "type": ["Credential", "MultiSubjectCredential"],
  "issuer": "https://multi.example.org",
  "issued": "2017-06-05",
  "claim": [{
    "id": "did:v1:9f52df2e-7c96-42af-8dfd-1099980f8467",
    "ageOver": 18
  }, {
    "id": "did:v1:7d866a9f-c5a3-41f5-8ae1-0297b7849801",
    "ageOver": 21    
  }, {
    "id": "did:v1:c4e13c30-31dc-40df-867f-ed678d87ac54",
    "ageOver": 65   
  }],
  "signature": {
    "type": "LinkedDataSignature2015",
    "created": "2017-06-05T07:08:36Z",
    "creator": "https://example.com/jdoe/keys/1",
    "signatureValue": "lQ7VZUeAA...Z5Lk="
  }
}

While this may be a corner case, the data model allows for it. Should we change the definition of entity credential and entity profile from being about "a subject" to "usually about the same subject" or equivalent language.

Aggregation of claims reveal more than the data itself

Aggregation of claims can reveal more information than just the attributes being aggregated. For example, exposing a birthdate and a zip code may identify a person far more accurately than a first and last name.