Proposal: Chaining VCs via links and digests

[dmitrizagidulin]

(Extracted from issue #831, which proposed two properties, digestMultibase and anchoredResource.)

Motivation

1. Provide a mechanism with which to link multiple VCs together (as peers or as parent/child relationships).
2. Provide examples of a general purpose content hash mechanism (useful for linking VCs, but also for linking to external images, PDFs, and other files).

Background / Use Cases

There are many use cases that involve binding multiple Verifiable Credentials together. For example, a simple Student ID credential can consist of an overall container credential, which links to several individual credentials (such as a student Photo credential, a proof of enrollment at a particular university, a proof of age, etc). 

Note that this is different than binding multiple credentials together in a Verifiable Presentation (and having the presenter sign the VP). In the VP case, the binding just means "this presenter is authenticating the handing over of these unrelated credentials". Whereas in the linked VC case, the credentials are aware of each other, and the peer or hierarchical relationship is built into the VC itself.

Chaining Credentials

For most use cases, chaining VCs together (or chaining a VC and an external resource) requires two things: 1) URIs (which we already have, from ids), and 2) a digest hash (to cryptographically bind the destination).

In turn, a digest hash of are resource of any kind requires, at minimum:

• specifying which hash algorithm was performed (e.g. SHA-256)
• text-encoded bytes of the actual digest. (which means you need a way to specify which character encoding (base64, base64url, base58btc, etc etc)
• (optional, but necessary in many use cases) a way to specify if any sort of transformation was done with the resource before it was hashed. (For example, if it was a JSON resource, perhaps it was sorted before hashing using JCS (JSON Canonicalization Scheme)).

Straw Proposals

For example, binding a VC to an external resource (such as an image or a PDF) would involve: (note that these are mock property names, the actual property name is in the proposal in the next section)

// Assume a photo of a person exists in the cloud at https://example.com/selfie-photo1.pdf

{
  "@context": [ "https://www.w3.org/2018/credentials/v1", "https://w3id.org/security/suites/ed25519-2020/v1" ],
  "type": ["VerifiableCredential", "MockStudentIdCredential"],
  "issuer": {
    "id": "did:key:....",
    "image": "https://example-university.edu/logo.png",
    "name": "Example University"
  },
  "issuanceDate": "2020-04-03T00:00:00.000Z",
  "name": "Mock Student Identification Document",
  "credentialSubject": [{
      id: "<student id number goes here>",
      image: {
        id: "https://example.com/selfie-photo1.pdf",
        digestHashAlgorithm: "SHA-256",
        characterEncodingAlgorithmOfDigestHashBytes: "base58btc",
        digestHashBytes: "TbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n"
        // no transformation or canonicalization was performed on the image before hashing
        // if instead the resource was not an image, but an external JSON object, you could have:
        // preHashTransformationAlgorithm: "JCS"
      }
   }],
   "proof": { // proof goes here }
}

The above example cryptographically binds the image URL & contents to the VC and its signature proof.

Actual digestMultibase proposal

For space saving reasons, the four digest-related fields (hash alg, char encoding, hash bytes, transform alg) could be all compressed into one field, using Multicodec notation (which is currently being standardized at IETF).
This proposal defines the digestMultibase field as:

MULTIBASE('<character base encoding alg>', MULTIHASH('<hash alg>', <un-transformed input>))
// or
MULTIBASE('<character base encoding alg>', TRANSFORM('<pre-hash transform alg>', MULTIHASH('<hash alg>', <transformed input>)))

Using this notation, the previous example would look something like:

{
  "@context": [ "https://www.w3.org/2018/credentials/v1", "https://w3id.org/security/suites/ed25519-2020/v1" ],
  "type": ["VerifiableCredential", "MockStudentIdCredential"],
  "issuer": {
    "id": "did:key:....",
    "image": "https://example-university.edu/logo.png",
    "name": "Example University"
  },
  "issuanceDate": "2020-04-03T00:00:00.000Z",
  "name": "Mock Student Identification Document",
  "credentialSubject": [{
      id: "<student id number goes here>",
      image: {
        id: "https://example.com/selfie-photo1.pdf",
        "digestMultibase": "zQmdfTbBqBPQ7VNxZEYEj14VmRuZBkqFbiwReogJgS1zR1n"
      }
   }],
   "proof": { // proof goes here }
}

Validation

A VC validator, when encountering a digestMultibase field, must do the following (throwing an error if any of those fail):

1. Find the corresponding URI that goes with the digest (look for the id property on the same level as the digest)
2. Resolve the URI (https get, did url resolution, finding a URN in the same presentation as this VC, etc) to get the resource external to this VC
3. Decode the digestMultibase field using Multicodec rules
4. (Optional) Transform the resolved resource from 2, using the specified transformation alg, if one was specified.
5. Perform the digest hash of the resolved resource from 2
6. Compare the bytes of the digest hash to the ones specified in digestMultibase

Use Cases and Examples

TODO: add these. But see the RWoT11 paper "Composing Credentials via Links and Cryptographic Binding" for examples of using digestMultibase for Educational credentials.

[OR13]

Should we include VerifiableEvidence in v2 context?

Currently we only have:

• https://github.com/w3c/vc-data-model/blob/main/contexts/credentials/v1#L39

[gobengo]

@dmitrizagidulin would it make sense to not reuse the 'digestMultibase' prop name and instead define a new one like 'cid'?

Now that you're including a multicodec, I think you're basically just using a CID https://github.com/multiformats/cid#cidv1

[dmitrizagidulin]

Now that you're including a multicodec, I think you're basically just using a CID

hmmm I'm not sure. One, digest is more descriptive than cid. But more importantly, digestMultibase is meant to go alongside a URI in the id, not instead.

[OR13]

Lets separate the concept of "linking VCs" from "talking about hashing"

[OR13]

Same, comment I made here: #1035 (review)

I dislike digestMultibase being the "only" or "recommended" way to link things

[iherman]

The issue was discussed in a meeting on 2022-09-15

• no resolutions were taken

View the transcript

5.3. Proposal: Chaining VCs via links and digests (issue vc-data-model#952)

See github issue vc-data-model#952.

Kristina Yasuda: We want to see concrete text to make progress.

Dmitri Zagidulin: This is the concrete text.
… It's ready for discussion.
… The proposal is there under straw proposal.

Kristina Yasuda: I'm assigning this to Dmitri.

Joe Andrieu: the "credential" related issues: #1009 and #991 and #1012.

Brent Zundel: Once it's ready for concrete changes to the spec, raise the PR.

Kristina Yasuda: We're getting into feature freeze. If you want this in V2 it needs to happen soon..

[iherman]

The issue was discussed in a meeting on 2023-04-11

• no resolutions were taken

View the transcript

1.7. Proposal: Chaining VCs via links and digests (issue vc-data-model#952)

See github issue vc-data-model#952.

Kristina Yasuda: "Proposal: Chaining VCs via links and digests" - have discussed, prior issues, don't think we ever saw a PR.
… reads from issue.
… could attach pending close.

Michael Prorock: Let's either close or mark pending close, it's a complicated enough issue that coming in right before feature freeze is problematic..
… I'm not disputing the value of it, just question whether it's pragmatic to get consensus and get it done in time..

Orie Steele: AFAIK, data integrity already added support for it.

Orie Steele: and it was not discussed in great detail.

Kristina Yasuda: any objections to pending close?.

Orie Steele: suspects personal hallucination, but thought id was present in proof, and id facilitates possible chaining.

Manu Sporny: did add id for proof chaining, but this is chaining VCs, not proofs - not this issue.

Orie Steele: This seems like "evidence".

Kristina Yasuda: marking pending close lacking objections.

[iherman]

The issue was discussed in a meeting on 2023-04-11

• no resolutions were taken

View the transcript

1.7. Proposal: Chaining VCs via links and digests (issue vc-data-model#952)

See github issue vc-data-model#952.

Kristina Yasuda: "Proposal: Chaining VCs via links and digests" - have discussed, prior issues, don't think we ever saw a PR.
… reads from issue.
… could attach pending close.

Michael Prorock: Let's either close or mark pending close, it's a complicated enough issue that coming in right before feature freeze is problematic..
… I'm not disputing the value of it, just question whether it's pragmatic to get consensus and get it done in time..

Orie Steele: AFAIK, data integrity already added support for it.

Orie Steele: and it was not discussed in great detail.

Kristina Yasuda: any objections to pending close?.

Orie Steele: suspects personal hallucination, but thought id was present in proof, and id facilitates possible chaining.

Manu Sporny: did add id for proof chaining, but this is chaining VCs, not proofs - not this issue.

Orie Steele: This seems like "evidence".

Kristina Yasuda: marking pending close lacking objections.

[brentzundel]

No objections since being marked pending close, closing.