Learn

Web Credentials

Introduction

Web Credentials are based on the W3C Verifiable Credential 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 Web Credentials or 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

In addition to JSON-LD properties that are defined in the credential, Web Credentials 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 and the standards are subject to breaking changes. To experiment with this feature, use your API endpoint to create a DID using the "keyType":"Bls12381g2" option. If you create a Verifiable Credential using this new DID as the issuer DID, the platform will automatically detect this capability and issue 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 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 OpenID provisioning capability, 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.

Presentations

As noted, 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 spec defines a general data model for VPs, but doesn’t specify how to request specific information in a verifiable presentation. Our approach is based on the VP Request Spec at the W3C Credentials Community Group.

MATTR VII incorporates the privacy-preserving capabilities of verifiable presentations in the core platform capabilities.

Presentations are an area where the mobile wallet plays a very important role. While MATTR VII is used to create templates and generates requests for presentations, it’s the mobile wallet app that generates and derives these presentations and exchanges them on behalf of the user.

For more detail on our verifiable presentation capabilities, check out the API Reference Docs.