Credentials

Verifiable Credentials ("VCs", or "credentials") are digital documents that conform to the W3C Verifiable Credential Data Model. VCs provide a standard for digitally issuing, holding, and verifying data about a subject.

📘

Definition of Verifiable Credential

"A verifiable credential is a set of tamper-evident claims and metadata that cryptographically prove who issued it." https://www.w3.org/TR/vc-data-model/

Verifiable credentials are unique from other kinds of digital documents because they enable you to verify the following things:

1. The original issuing entity (the source of the data)
2. It was issued to the entity presenting it (the subject of the data)
3. It hasn't been tampered with (the veracity of the data)
4. Whether the issuer revoked the credential as of a particular point in time (the status of the data)

Components of a Credential

To break down the components of a credential, we'll use a digital driver's license as an example.

Issuer DID

As you can see from the diagram above, a Verifier will only accept a credential if they trust its source. For example, in the United States a TSA agent will only let you on an airplane if you present a valid driver's license (or other gov ID); they do this because they trust the DMV or other agency that issued it. In order to validate where a credential came from, verifiers use the issuer's DID.

Each new Tenant is assigned an issuer DID on the network your tenant is provisioned to. The issuer DID acts as a public-facing address or public key. In the self-sovereign identity space, these DIDs are usually written to a public blockchain, but other DID registries are possible, too. Each issuer DID has an associated private key which is used to cryptographically "sign" each issued credential. In fact, each attribute inside the credential is signed in this manner, allowing the holder of the credential to share only a subset of the attributes when desired. For example, someone could share their name and age from their driver's license without sharing the driver's license number, address, and hair color. Using the issuer DID and straightforward public-private key cryptography, anyone can verify the attributes in the credential were attested to by the issuer.

In Trinsic Studio, you can find your issuer DID by clicking the "Details" button inside the organization card on your dashboard page.

Schema

Each credential needs a template so the data can be shared and interpreted correctly. That template is called a Schema.

Schemas are the general structure of the credential. In our example, they tell us what information must be included on the driver's license in order for it to be valid, like Full name, Address, Eye color, etc.

In short, they are the attributes that you want to include in this credential.

Example:

{
	"$schema": "http://json-schema.org/draft-07/schema#",
	"description": "Email",
	"type": "object",
	"properties": {
		"emailAddress": {
			"type": "string",
			"format": "email"
			}
		},
	"required": ["emailAddress"],
	"additionalProperties": false
}

Schemas also need to be discoverable by the verifier of the credential. Because of the Hyperledger Indy/Aries tech stack that we use, we write the schema object to the public ledger. Other implementations leverage schema.org or other publicly discoverable sources.

Schemas are nonproprietary; any issuer can view/use the schemas written by any other issuer.

We abstract schema creation away into the same action as creation of a credential definition. Keep reading to read how to create a schema and credential definition.

Credential Definition

Just having an issuer DID and a schema written to the ledger is not enough, however. You need to put them together in order to actually issue credentials. This is where the Credential Definition comes in.

A credential definition is a particular issuer's template to issue credentials from. There are two ways for an issuer to create a credential definition:

1. Based on an existing schema: This is the ideal way to create a credential definition because the issuer can leverage an existing schema. In addition, this promotes interoperability and trust in credentials at scale (passports, transcripts, and employee ID cards should all be based on similar data models, for example).
2. Create a new schema alongside the credential definition: This is the most common method of creating a credential definition in the early days because there is no existing directory of standard schemas.

Going back to our example, the New York DMV would create a Credential Definition with their issuer DID and the schema. They're likely to use an existing schema, ideally the same one used by other states. Once they've created a credential definition, they can then go forward with issuing New York Driver's Licenses.

Remember this:

• Credential definitions are the combination of schemas and issuer DIDs and act as a template for issuance (in fact, we call them credential templates in the Trinsic Studio!
• Credential definitions and schemas are permanent artifacts on the ledger that can't be edited.

To learn how to create schemas and credential definitions, see our API Reference docs.

Credential

In order to issue a credential, you need a credential definition (called a credential template in the Trinsic Studio). Once you have the credential definition, all you need to do is to populate the values and offer it to a holder.

{
	"credentialId": "string",
	"state": "Offered",
	"connectionId": "string",
	"definitionId": "string",
	"schemaId": "string",
	"values": {
		"additionalProp1": "string",
		"additionalProp2": "string",
		"additionalProp3": "string"
	}
}

How to offer Credentials in Trinsic

Issue your first credential by following our tutorial.

Reference App

Check out our issuer-reference-app on GitHub for a demo on how to issue a business card as a credential to anyone with a mobile wallet.