As part of our series on understanding more about the vLEI, the new Verifiable Credential to identify organisations and organisation representatives, this article is a follow-up to a previous post Introduction to Verifiable Credentials. This time, we will look in more detail at how W3C specification verifiable credentials work.

The Verifiable Credentials (VC) specification by W3C provides a way to express credentials on the web. In this article I’m giving an overview of components and terminology related to VCs, and also some information about other technologies and specifications that are needed when implementing verifiable credentials.

Claims

Before I go into the components, I’ll run through a quick explanation on claims as a critical concept to understand for verifiable credentials. A claim is a name-value statement about a subject. The subject is typically a person, but it could also be a thing, such as hardware device. Examples of claims are:

  • Person’s first and last name, date of birth etc.
  • Organisation name
  • Personal ID
  • … and many others

The concept of claims is familiar to those who have been working with federation protocols, such as OpenID Connect and SAML.

Example

“credentialSubject” : {
  “id”: “did:example:7564cb9c-165c-4857-a887-bfc2460af867”,
  “birth_date”: “1970-01-01”
}

Components of Verifiable Credentials

A Verifiable Credential (VC) is a collection of claims made by an issuer (recap issuers in Introduction to Verifiable Credentials). VC metadata describes properties such as type, expiration and issuer of a credential. VC proof is used to verify the integrity of a credential. A proof is typically expressed as a digital signature, made with the private key of the issuer.

Verifiable Credential

Example

{
    "@context": [],
    "id": "e9ea3429-b32f-44ad-b481-b9929370bb90",
    "type": [ "VerifiableCredential", "ExampleCredential" ],
    "issuer": { "id": "did:example:2d28bb79-87a9-4224-8c63-d28b29716b67" },
    "issuanceDate": "2022-01-01T00:00:00Z",
    "credentialSubject": {
        "id": "did:example:7564cb9c-165c-4857-a887-bfc2460af867",
        "birth_date": "1970-01-01"
    },
    "expirationDate": "2023-01-01T00:00:00Z",
    "proof": {}
}

Verifiable Presentation

Verifiable Presentation (VP) is a collection of Verifiable Credentials (VC). Typically, a VP contains a single VC, but in more complex scenarios (such as selective presentation or delegation) there could be many VCs within a single VP.

VP proof is used to verify the integrity of presentation. Proof is the holder’s counter signature of a collection of VCs where each VC has been individually signed by its issuer.

As with verifiable credentials, proof is typically expressed as a digital signature made with the private key of the holder. Usually, the VP holder and subject of VCs within the verifiable presentation is the same. In more complex scenarios, the holder and subject could be different. In such cases some information or rules need to exist that allow correlating VCs.

VP metadata describes properties such as expiration and nonce. The nonce is a random value generated by the relying party when requesting a VP, letting the relying party prevent re-play of VP tokens. In effect, VP is a classic challenge response authentication protocol.

Verifiable Presentation

Example

{
    "@context": [],
    "type": [ "VerifiablePresentation" ],
    "verifiableCredential": [
        {
            "@context": [],
            "id": "e9ea3429-b32f-44ad-b481-b9929370bb90",
            "type": [ "VerifiableCredential", "ExampleCredential" ],
            "issuer": { "id": "did:example:2d28bb79-87a9-4224-8c63-d28b29716b67" },
            "issuanceDate": "2022-01-01T00:00:00Z",
            "credentialSubject": {
                "id": "did:example:7564cb9c-165c-4857-a887-bfc2460af867",
                "birth_date": "1970-01-01"
            },
            "expirationDate": "2023-01-01T00:00:00Z",
            "proof": {}
        }
    ],
    "holder": "did:example:7564cb9c-165c-4857-a887-bfc2460af867",
    "proof": {}
}

Decentralised Identifier

A Decentralised Identifier (DID) is an identifier that is used to identify the subject, issuer and holder of verifiable credentials and presentations.

A DID is formatted as a URI starting with prefix “did:”, followed by the scheme identifier and a scheme specific part (did:scheme:address).

Numerous DID schemes have been defined, yet not all schemes have the same capabilities. Some schemes operate on distributed ledgers, such as blockchains. Others take more traditional approaches, such as simply referencing http resources, or even X.509 certificates.

Basically, the DID is an indirect reference to public keys, usually controlled by the entity the DID represents. This way, the keys of an entity can, for example, be rotated without the DID value having to change.

Example

did:example:e762e3b0-1cf9-4899-925f-9a6ae50a8ad6

DID document

The DID scheme defines how to resolve a DID value into a DID document. The DID document is a way to present metadata and public keys of the entity. The public keys are needed to verify VCs and VPs.

Example

{
    "@context": [],
    "id": "did:example:7564cb9c-165c-4857-a887-bfc2460af867",
    "verificationMethod": [
        {
            "id": "did:example:7564cb9c-165c-4857-a887-bfc2460af867#key-1",
            "type": "JsonWebKey2020",
            "publicKeyJwk": {}
        }
    ],
    "authentication": [ "#key-1" ],
    "assertionMethod": [ "#key-1" ],
    "controller": [ "did:example:7564cb9c-165c-4857-a887-bfc2460af867" ]
}

Trust Model

For claims to be verifiable, the relying party must establish trust with the issuer of the Verifiable Credential (VC) with the claims.

One possible model for a relying party is to use out of band methods to establish trust, where the relying party simply knows the DID value of the issuer being the trust anchor.

More complex models allow implementing chains of trust where a VC issued by the trust root could delegate trust to other intermediary VC issuers.

Self-attestation is a model where the VC is issued by the subject itself. In this case, the claims are not verifiable but could still be useful depending on the use case.

Digital Wallet

The digital wallet application holds Verifiable Credentials (VC) from issuers. The wallet creates Verifiable Presentations (VP) for relying parties with user’s consent. This application can exist on a user’s device, it can be hosted on a server, or it could be a combination of both.

Simon Wood looks at Identity Wallets used in the vLEI specification in more detail in his blog vLEI & Identity Wallets.

Self-Sovereign Identity

The wallet plays a critical role in implementation of the self-sovereign concept of Verifiable Credentials.

The wallet must not release information to relying parties without the user’s consent. Also, it must not let the VC issuer know when and where the VCs have been used. The latter property is one of the most significant differences compared to traditional OIDC and SAML based federated systems.

Selective disclosure

Selective disclosure lets the wallet app compose VPs from selected properties of VCs. This enables a wallet to “pick and choose” claims from VCs without disclosing full details and thus improving privacy. A typical example is a claim such as “age over 18”. This lets a relying party know the subject’s age is over 18 without disclosing the exact date of birth.

Issuing Credentials

Users receive Verifiable Credentials (VC) from credential issuers and store the VCs in their wallets.

Issuing Credentials

To create VCs, the issuer needs to verify the identity of the user so that it can issue credentials with the correct claims.

Because the VCs are bound to a subject DID, the issuer must also verify the user is in control of the subject DID. One method is for the issuer to request the user to create a digital signature that is verifiable with the public key referenced by the DID.

OpenID Connect for Verifiable Credential Issuance

Federated Identity Providers (IdP) already implement user identity verification and they have repositories with claims and other statements about users. It is expected that many IdPs will be extended to become issuers of VCs. The OpenID Connect for Verifiable Credential Issuance (VCI) is a set of extensions to standard OIDC flows that enable interoperability across digital wallets and identity providers. The VCI flow takes care of both DID and identity verification requirements.

Relying Party

A Relying Party or Verifier is the entity that receives Verifiable Credentials (VC) embedded within a Verifiable Presentation (VP) from a user’s wallet.

To get a VP from a wallet the Relying Party sends a Presentation Request to the user’s wallet. Properties of the request indicate things like what claims the Relying Party expects to receive.

Relying Party

After receiving a VP, the task of the verifier is to verify the integrity of both the VCs embedded within a VP and the VP itself. To do so, the verifier must look up public keys of both the subject and the issuer by resolving DIDs.

OpenID Connect for Self-Issued OP

To request and receive VPs from a wallet, a set of extensions to standard OIDC flows have been designed. The OpenID Connect for Self-Issued OP (SIOP) flow allows a relying party to request VPs from a wallet using a protocol that resembles the OIDC implicit flow.

Presentation Exchange

Presentation Exchange lets a relying party request particular types of credentials and claims. This specification defines filters and conditions that the wallet evaluates when it is constructing a VP from the set of VCs it has stored.

Example

{
  "id": "8cbe12c7-5d6b-4bfa-81c9-57855daebc77",
  "input_descriptors": [
    {
      "id": "ExampleCredential",
      "constraints": {
        "fields": [
          {
            "path": [ "$.type" ],
            "filter": {
              "type": "array",
              "const": [ "VerifiableCredential", "ExampleCredential" ]
            }
          }
        ]
      }
    }
  ]
}

Token types and formats

The Verifiable Credential spec itself being very generic does not define any token format. The examples captured in this article are from JSON-LD formatted tokens.

In addition to JSON-LD there exist many other token formats such as VC-JWT, Mobile Driver’s License (mDL), AnonCreds and KERI ACDC. Each token format has its own characteristics, such as text or binary formatting, different cryptographic proof types, support for selective disclosure etc.

Conclusions

The privacy improvements by the Self-Sovereign aspects of Verifiable Credentials are a significant improvement compared to traditional federated systems.

The current W3C VC specification is highly generic. This presents a challenge to implementations wanting to achieve interoperability. Work on the next version of the W3C VC has already started, with the goal of addressing, amongst others, interoperability problems.

OpenID for Verifiable Credentials work simplifies some implementation challenges by reusing concepts and terminology from the very well-known OpenID Connect and OAuth 2 group of specifications.

To learn more about the vLEI, and the Global LEI Foundation’s approach to using Verifiable Credentials, learn more with our vLEI 101 article.

If you have any questions on Verifiable Credentials, please comment below and I’ll get back to you or contact us. You can also sign up to our monthly identity newsletter to stay informed of future posts around Verifiable Credentials and other key identity topics.

References