VII Core -- Verifiable Credentials

Introduction

Verifiable Credentials are a W3C standard data model for expressing cryptographically secure digital credentials on the web.

Though they are both part of the VC data model, Verifiable Credentials (VCs) are distinct from Verifiable Presentations (VPs). Presentations are typically generated or derived from VCs and presented by credential holders for the purposes of verification.

The VC data model defines two concrete data syntaxes, JSON and JSON-LD. JSON-LD allows the VC data model to be extensible and interoperable while remaining distributed in its architecture.

When combined with DIDs, VCs provide a decentralized data sharing model where interconnected webs of signed and linked data can be used to establish trust across contexts.

To learn more about our approach to VCs, read our blog, “JWT vs Linked Data Proofs: comparing Verifiable Credentials”.

JSON-LD

Linked Data plays a very important role when it comes to exchanging verifiable information. JSON-LD is designed to facilitate sharing and discovering data in web-based environments. There are several available guides online that describe JSON-LD in detail. We’re going to focus on two required properties of JSON-LD that consistently show up in the VC data model, namely @context and type.

@context

@context: When two software systems need to exchange data, they need to use terminology that both systems understand. Credentials contain attributes and values that are defined by basic terminology, i.e. in a given context, "lastName" may be an attribute that refers to a person’s surname. Contexts map terms that are used in VCs and VPs to URIs that explain what those terms mean in that context. @context is expressed as an ordered set, and all credentials share the same common context that always appears first in the set, https://www.w3.org/2018/credentials/v1. Contexts are often cached for the sake of performance.

type

type: Related to @context, the type property expresses what kind of information is in the document: is it a verifiable credential? Is it a presentation? Is it an object containing credentials, or presentations? For convenience and semantic interoperability, type is often specified as a set of terms that are defined in the JSON-LD @context.

Usage

MATTR VII utilizes Verifiable Credentials extensively in our VII Core. Core allows our users to create, store, retrieve, manage, and delete Verifiable Credentials.

In addition to JSON-LD properties that are defined in the credential, VCs created on MATTR VII will include the DID & in some cases the domain name of the issuer, as well as some kind of identifier for the subject (typically also a DID).

NOTE: We have developed an experimental feature in MATTR VII around Zero-Knowledge Proofs (ZKP). It’s a technique to implement privacy-preserving selective disclosure in verifiable credentials using the cryptography of BBS+ signatures. As ZKPs are experimental, they only work with did:key method at this point. To experiment with this feature, use your API endpoint to create a DID with "method":"key" and "keyType":"bls12381g2" parameters set. If you create a Verifiable Credential using this new DID as the issuer DID, the platform will automatically detect this capability and create a ZKP-enabled BBS+ credential for you. Our Mobile Wallet App can detect if ZKP is enabled in a credential, and upon request for verification, will use that information to derive a new credential presentation that selectively discloses the required info using ZKP. You can read more about our work on privacy-preserving verifiable credentials on our blog.

For more detail on our Verifiable Credential capabilities, check out the API Reference Docs.

Revocation

Credentials issued using MATTR VII have the capability to be set with a revocation status that can be checked by Verifiers while preserving the privacy of the credential holder. This status can then be updated by Issuers of those credentials to indicate if the credential is revoked or still valid. The holder is also able to use the MATTR Mobile Wallet to see the latest revocation status of their credentials at any time.

We have used a W3C specification known as Revocation List 2020 to achieve this in a simple, transparent, and interoperable way. Our tutorial on how to Revoke a credential goes into some depth on how this mechanism works.

The Credential Registry

Whenever a Credential is created on MATTR VII, a small amount of meta-data is held about the Credential:

  • id — internal identifier generated by the platform

  • tag — (optional) an externally provided identifier

  • credentialStatus — (optional) reference to the Revocation List

  • issuanceDate — the date the credential was issued

The actual Credential, including information about the subject, is typically stored in the holder’s digital wallet, though it can also be optionally held by the Issuer in the registry alongside the credential meta-data. It is only recommended to invoke this setting when it is appropriate to do so.

Storing and retrieving the entire Credential data needs careful consideration, as holding personally identifying information (PII) has implications when it comes to regulatory compliance e.g. GDPR and CCPA.

For Credentials issued via the OIDC Bridge, only the meta-data is stored on the MATTR platform.

The Credential Registry can be used to look-up the Credential based on tag and type to obtain the meta-data, or the entire Credential if it’s being held.

The meta-data can be used in other operations, like Revoking the Credential or determining the existence of an issued Credential based on an external ID.

A valid use-case for the credential registry is in the case of non-personal Credentials being held and retrieved for public display, for example a Verifiable Organization Network or a company’s registry.