Verifiable Credentials (W3C)

Verifiable Credentials (VCs) are digital credentials that contain actual identity data of people or organizations and are standardized by the W3C. They are digital equivalents of paper-based identity documents like passports or diplomas.

Before we dive deeper into Verifiable Credentials and learn about their structure and how they work, we will have a look at the problems of today's credentials.

Credentials today

Today's credentials are easy to fake, hard to verify, and not privacy preserving by design. Making it hard for business and people offline but especially online to trust each other, when exchanging information and data. This brings about many problems, thereunder:

  • To verify that a document or claim presented is actually valid, can take up many resources and time. Just think about, what you had to do last time you opened up a bank account. The presenting of your ID card via a video call, taking selfies etc.
  • Often the credentials provided by you to get access to a service, are then stored on centralized servers. This makes them not only vulnerable to data breaches, but you also need to trust the organization that they only use the data in ways you would agree with.
  • You might be forced to disclose more information than needed. The police officer checking your driver license, in most cases, only needs to know that you are allowed to drive, but not where you live or your name.
  • Organizations employing people who claim to have a skill by presenting a fake certificate, can get jobs, which, when performed poorly, could have catastrophic consequences.

This is why we need a better way to verify the claims presented, and that is where Verifiable Credentials come in.

Verifiable Credentials to the Rescue

With VCs and the standard introduced by W3C, we now have a way of creating a digital piece of information that identifies a particular entity or verifies a specific attribute, qualification or claim about them, in a way, that is almost impossible to forger, easy to verify, and privacy preserving by design. Leaving us with the following benefits:

  • Easy to verify: There is a clearly defined and reliable way of verifying a Verifiable Credential.
  • Temper-proof: No one expect the issuer (entity creating the VC) can change the claims stated in the VC.
  • Independent: No need to contact the issuer of the presented certificate to be certain about its validity. The check can happen in an independent, asynchronous way.
  • Data is owned: The holder of a certificate now owns the data and decides what to share and when, only providing proof but never actually giving it (a copy) to the service provider.
  • Portable: The user is free to choose where to take their VC and in which wallet it is saved.

The lifecycle of a Verifiable Credential

For us to understand the typical lifecycle of a Verifiable Credential, we need to make sure, we understand the idea behind an Issuer, Holder and Verifier and what DID and DID Documents are.

Issuer, Holder and Verifier

  • Issuers - Parties who “issue” identity-related data to people or organizations (“Holders”) in the form of digital credentials. They are the original data sources of a digital identity ecosystem. For example, a government issues digital passports to citizens or a university issues digital diplomas to graduates.
  • Holders - Individuals or organizations who receive digital credentials that contain data about themselves from various sources (“Issuers”). By aggregating and storing such credentials in digital wallets, Holders can build holistic digital identities that are under their control and can easily be shared with third parties ("Verifiers").
  • Verifiers - Parties who rely on data to provide products and services can reliably verify and process data that has been provided by others (“Holders”). Verifiers, also called “Relying Parties”, are usually organizations or individuals in their professional capacity.

DID and DID Documents

You can read up on both those concepts in the DID Concept Section.

With that out of the way, let's start with the Lifecycle.

After the registration of the issuer and the setup of the wallet for the holder, the holder can receive a VC from the issuer.

Issuance & Content

When the holder receives their Verifiable Credential it will be saved on their wallet, and it will contain the following:

  • Metadata:
    • The DID of the issuer
    • The status of the credential (expiration and issuing date, revoke state)
  • Claims:
    • The DID of the holder of the credential
    • The claims about the subject (what the issuer asserts about the subject). This could be, if they can drive a car and what type of car (driver license) or the subject of their study and knowledge areas skilled in (university certificate).
  • Proof:
    • This will contain the signatures of the issuer, which can be used to see if the content of the VC has been tempered with and for an authenticity check.

Using the Certificate

The holder can now use the VC in their wallet to access services, and get access to products by presenting it to the service/product provider (The Verifier) and thereby making it a Verifiable Presentation. The verifier will go through the following steps to make sure the certificate is valid:

  1. Before the validation of the content of the certificate can take place, the VC needs to be parsed from the support JWT, SD-JWT or JSON-LD format. Depending on the ecosystem used, there will also happen a validation of the schema of the credential.
  2. Validate that the DID of the holder, stated in the certificate, is the person presenting the VC.
  3. Checking if all the state values are valid (expiration date and if the certificate is revoked or not).
  4. Checking the claims about the subject and if they match the requirements to give the person access to the service they are requesting to get access to.
  5. Checking the signatures of the issuer and the holder, by getting the DID of the issuer from the registry and the DID from the holder in their wallet and validating it using the public keys presented in the related DID documents.

When all the checks pass, the verifier can now grant the holder access to the service requested.

Example of a Verifiable Credential


{
  // Sets the context of the credential. Establishes the idea and meaning behind the
  // special terms used in the credential, so that the parties interacting with the
  // credential are on the same side.
  "@context": ["https://www.w3.org/2018/credentials/v1", "https://essif.europa.eu/schemas/v-a/2020/v1", "https://essif.europa.eu/schemas/eidas/2020/v1"],
  // The identifier of the Verifiable Credential
  "id": "education#higherEducation#3fea53a4-0432-4910-ac9c-69ah8da3c37f",
  // Types of the credential, giving you an overview of the data to expect
  "type": ["VerifiableCredential", "VerifiableAttestation"],
  // Issuer of the credential
  "issuer": "did:ebsi:2757945549477fc571663bee12042873fe555b674bd294a3",
  // When the credential was issued
  "issuanceDate": "2019-06-22T14:11:44Z",
  // When the credential will be valid
  "validFrom": "2019-06-22T14:11:44Z",
  // Claims about the subject
  "credentialSubject": {
    // Identifier of the only subject of the credential
    "id": "id111"
  },
  // Current status of the credential, such as if it is suspended or revoked
  "credentialStatus": {
    "id": "https://essif.europa.eu/status/identity#verifiableID#1dee355d-0432-4910-ac9c-70d89e8d674e",
    "type": "CredentialStatusList2020"
  },
  // Used data schema by the credential. It gives the verifiers an idea,
  // if the presented data in the credential conforms.
  "credentialSchema": {
    "id": "https://essif.europa.eu/tsr-vid/verifiableid1.json",
    "type": "JsonSchemaValidator2018"
  },
  // It can give the verifier an extra level of security, that the issued credential
  // can be trused, as it lays out requirements the issuer needs to check the
  // subject against, before issuance of the credential can take place.
  "evidence": [
    {
      "id": "https://essif.europa.eu/tsr-va/evidence/f2aeec97-fc0d-42bf-8ca7-0548192d5678",
      "type": ["DocumentVerification"],
      "verifier": "did:ebsi:2962fb784df61baa267c8132497539f8c674b37c1244a7a",
      "evidenceDocument": "Passport",
      "subjectPresence": "Physical",
      "documentPresence": "Physical"
    }
  ],
  // Digital proof that makes the credential temper-evident
  "proof": {
    // The cryptographic signature suite that was used to generate the signature
    "type": "EidasSeal2021",
    // The date when the signature was created
    "created": "2019-06-22T14:11:44Z",
    // Purpose of this prove
    "proofPurpose": "assertionMethod",
    // The identifier of the public key that can be used to verify the signature
    "verificationMethod": "did:ebsi:2757945549477fc571663bee12042873fe555b674bd294a3#2368332668",
    // The digital signature value
    "jws": "HG21J4fdlnBvBA+y6D...amP7O="
  }
}

Verifiable Presentation (VPs)

A Verifiable Presentation (VP) is a collection from one or more Verifiable Credentials, whereas the authorship of the whole collection can be cryptographically verified. VPs are standardized as part of the W3C Verifiable Credentials Data Model.

Why do we need Verifiable Presentations?

Verifiable Presentations, make it possible to combine and tamper-evident share data of one or more Verifiable Credentials. The shared presentation of the data will be encoded in such a way that authorship of the data can be trusted after a process of cryptographic verification. In situations where only a subset of the original Verifiable Credential data is reveled, for example, to enhance user privacy, Zero-Knowledge Proofs can help us keep that data verifiable.

How Verifiable Presentations are composed?

Verifiable Presentations represent a composition of claims, which can come from one or multiple Verifiable Credentials, of which the authorship is verified. This gives the holder of credentials the chance of composing context specify presentations, which only contain the data which is relevant in that context. When presenting the composition to a verifier, it can easily be validated.

Taking a closer look at how they are built up. We will see four different layers:

  • Presentation Layer - Being the Verifiable Presentation itself with the required metadata
  • Credential Layer - Referenced by Layer 1 and pointing to one or more credentials
  • Credential Proof Layer - Holding the proofs of the credentials and the signatures from Layer
  • Presentation Proof Layer - Holding the proof of the Verifiable Presentation and its signatures

Verifiable Presentation Layers

Example of a Verifiable Presentation

{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["VerifiableCredential", "VerifiablePresentation"],
  "verifiableCredential": [
    {
      "@context": ["https://www.w3.org/2018/credentials/v1", "https://essif.europa.eu/schemas/vc/2020/v1"],
      "credentialSubject": {
        "id": "did:ebsi:00000004321",
        "naturalPerson": {
          "did": "did:example:00001111"
        }
      },
      "id": "did:ebsi-eth:00000001/credentials/1872",
      "issuanceDate": "2020-08-24T14:13:44Z",
      "issuer": "did:ebsi:000001234",
      "proof": {
        "created": "2020-08-24T14:13:44Z",
        "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19.",
        "proofPurpose": "assertionMethod",
        "type": "EcdsaSecp256k1Signature2019",
        "verificationMethod": "did:ebsi-eth:000001234#key-1"
      },
      "type": ["VerifiableCredential", "VerifiableAuthorization"]
    },
    {
      "@context": ["https://www.w3.org/2018/credentials/v1", "https://w3id.org/citizenship/v1"],
      "credentialSubject": {
        "birthDate": "1958-08-17",
        "givenName": "JOHN",
        "id": "did:example:123",
        "type": ["PermanentResident", "Person"]
      },
      "issuer": "did:example:456",
      "proof": {
        "created": "2020-04-22T10:37:22Z",
        "jws": "eyJjcml0IjpbImI2NCJdLCJiNjQiOmZhbHNlLCJhbGciOiJFZERTQSJ9..BhWew0x-txcroGjgdtK-yBCqoetg9DD9SgV4245TmXJi-PmqFzux6Cwaph0r-mbqzlE17yLebjfqbRT275U1AA",
        "proofPurpose": "assertionMethod",
        "type": "Ed25519Signature2018",
        "verificationMethod": "did:example:456#key-1"
      },
      "type": ["VerifiableCredential", "PermanentResidentCard"]
    }
  ]
}

Working With Verifiable Credentials

walt.id offers a wide range of open-source tools that help you create and verify Verifiable Credentials in JWT, SD-JWT and JSON-LD format.

Get started by using:

Servicesmdoc/mDL (ISO)