Verifiable Credentials Explained

Credentials - driving licenses, college degrees, passports, etc. - are such an ordinary part of everyday life that people often do not think about the established features that make their usage so simple and secure. However, these features are important as otherwise credentials would not be able to fill their purpose. These features are as follows:

• Each credential has a definite format that allows others to quickly recognize the credential type (a verifier knows what a passport looks like and how it differs from a driving license).
• The credential contains relevant information about the subject to identify her and assert additional claims, like the classes of cars she is allowed to drive or her nationality.
• The credential contains relevant information used to prove the holder's right of possession. Usually, there is a picture of the subject that can be used to verify that the person that presents the credential is the rightful owner.
• The credential contains security features that allow others to verify its authenticity, e.g., watermarks, holographic elements, stamps, or even seals. It allows the verifier to check the authenticity of the document without the need of contacting the issuer directly.

This set of features makes physical credentials secure, easy to use, and privacy-preserving^[1]. The same features need to be mapped in the digital world so that the digital versions of credentials can be used in the same manner as the physical ones. This is the role of Verifiable Credentials. As one of the specifications that describe Verifiable Credentials states, they are "a mechanism to express [...] credentials on the Web in a way that is cryptographically secure, privacy respecting, and machine-verifiable."

The "verifiable" part in the name means that the party that receives such credentials (the verifier) can check the integrity of the credential, that it was issued by a trusted issuer, and that it was presented by the rightful holder. The verifier can do all that without the need of contacting the issuer directly, exactly as is the case with physical credentials. As for the data contained in the credential itself (name, age, nationality, etc.), the verifier must trust the issuer that it has fulfilled all the due diligence to gather the correct information about the subject.

Verifiable Credentials are one part of the Digital Identities environment. If you are new to the concept and want to start with a broad overview, then have a look at our Overview of Decentralized Identities article.

Verifiable Credentials Data Formats

The data format makes a credential usable in the physical world, e.g., countries know which citizen data they have to put in a passport so that other countries recognize the document. The same goes for digital credentials. A data format makes Verifiable Credentials machine-readable and interoperable as it describes what fields are included in the document, what is the meaning of the fields, how the document is serialized, etc. Thanks to standardized data formats, applications know how to issue and consume an instance of Verifiable Credentials.

Different standards describe Verifiable Credentials data formats, among which the following are popular choices:

• Hyperledger AnonCreds (Anonymous Credentials)
• ISO/IEC 18013-5:2021 mobile Driving License (mDL)
• W3C Verifiable Credentials Data Model

W3C Verifiable Credential Data Format

The W3C Data Model is fast gaining traction as a much simpler implementation of the concept. This is why this article focuses on the W3C model as an example of Verifiable Credentials.

A Verifiable Credential document consists of three main parts.

1. Metadata describes the document itself: who is the issuer, when was the document issued, how long it is valid for, what is the schema of the data, etc.
2. Claims carry information about the subject. This is the main payload of the Verifiable Credential. E.g., in the case of a university degree, this might be the name of the titleholder, the name of the degree, the title of the thesis, the overall note, etc.
3. Proofs contain relevant information that makes the credential verifiable. This data allows for a cryptographic verification of the document's integrity and the issuer's identity.

The specification describes the canonical structure of the Verifiable Credential and does not impose any serialization. Implementers are free to choose any serialization like XML, YAML, etc. However, JSON-LD (JSON-based serialization for Linked Data) is used as the base media type.

The specification also does not impose any concrete format for the proof, and any valid cryptographic method can be used. Currently, the two most popular methods for creating proofs for the W3C data format are: using Data Integrity and signed JWTs (JWS).

Example of a W3C Verifiable Credential

Below is a simple example of a Verifiable Credential secured with a JWS:

---------------- Decoded Protected Header ----------------
{
  "alg": "ES256",
  "typ": "vc+ld+jwt",
  "iss": "https://myuniversity.example.com/issuers/23409",
  "iat": 1687858395
}
---------------- Decoded Protected Claimset ----------------
{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "id": "http://myuniversity.example.com/degrees/224567",
  "type": [
    "VerifiableCredential",
    "ExampleDegreeCredential"
  ],
  "issuer": "https://myuniversity.example.com/issuers/23409",
  "validFrom": "2022-07-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:example:6828e4302b9e11eebe560242ac120002",
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science"
    }
  }
}
--------------- JWT ---------------
eyJ0eXAiOiJ2YytsZCtqd3QiLCJpc3MiOiJodHRwczovL215dW5pdmVyc2l0eS5leGFtcGxlLmNvbS9pc3N
1ZXJzLzIzNDA5IiwiaWF0IjoxNjg3ODU4Mzk1LCJhbGciOiJFUzI1NiJ9.eyJAY29udGV4dCI6WyJodHRwc
zovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVu
dGlhbHMvZXhhbXBsZXMvdjIiXSwiaWQiOiJcImh0dHA6Ly9teXVuaXZlcnNpdHkuZXhhbXBsZS5jb20vZGV
ncmVlcy8yMjQ1NjdcIiIsInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJNeVVuaXZlcnNpdHlEZW
dyZWVDcmVkZW50aWFsIl0sImlzc3VlciI6IlwiaHR0cHM6Ly9teXVuaXZlcnNpdHkuZXhhbXBsZS5jb20va
XNzdWVycy8yMzQwOVwiIiwidmFsaWRGcm9tIjoiXCIyMDIyLTA3LTAxVDAwOjAwOjAwWlwiIiwiY3JlZGVu
dGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZXhhbXBsZTo2ODI4ZTQzMDJiOWUxMWVlYmU1NjAyNDJhYzEyMDA
wMiIsImRlZ3JlZSI6eyJ0eXBlIjoiQmFjaGVsb3JEZWdyZWUiLCJuYW1lIjoiQmFjaGVsb3Igb2YgU2NpZW
5jZSJ9fX0.0sG9Kao6gRx60Yjtf0c8O9DnO3A4t8yzfGzOqPDaEdmcSilRa0R946bsfxvVKmRDoJZPsJh6b
bn6Ofa9k9Iflg

The JWT payload contains the actual Verifiable Credential object. It consists of fields that are necessary for the Verifiable Credential to serve its purpose. These are explained below.

Context

The @context property allows applications to properly understand the properties of the credential. It's essentially a namespace for the property names and some values. The context contains a list of URIs that point to documents that describe the context. For a W3C Verifiable Credential of version 2, it always uses https://www.w3.org/ns/credentials/v2 as the first value.

ID

The id is an optional property, that, if present, contains a URL identifier of the credential. The id property can be used in different parts of the Verifiable Credential document and is used to uniquely identify the concrete element. For example, it can be used to identify a proof, the subject, the issuer, etc. It is recommended that the ID can be dereferenced to a machine-readable document with information about the identifier, thus it is common to use DIDs as identifiers in Verifiable Credentials.

Type

The type property contains a list of types that the document represents. In case of Verifiable Credentials, the VerifiableCredential type is used together with application-specific types that allow to properly verify the document. E.g., the ExampleDegreeCredential type defines that the credential will contain a degree claim with the type of degree and a descriptive name. It is recommended that the type value is a URI that points to a machine-readable description of the type. Usually, the value is a reference to a URI defined in the context.

Other types of documents and objects like a proof or a VerifiablePresentation also have a type. A Verifiable Presentation is a document that contains data derived from one or more credentials. In addition, it typically includes one or more proofs of the holder. The holder presents the Verifiable Presentation and not the Verifiable Credential to other parties. The type allows implementations to distinguish between various documents and differentiations of.

Issuer

A Verifiable Credential must contain an issuer field that uniquely identifies the issuer. It contains either a URL or an object with at least the id field:

"issuer": "https://myuniversity.example.com/issuers/23409",

or

"issuer": {
    "id": "did:example:3eftr2e5c6421eabf5tfgh",
    "name": "My University"
  },

This field is later used by verifiers to check the validity of any proofs (e.g., whether keys used to sign the credentials belong to the issuer).

Validity Period

validFrom and validUntil properties can be used to inform verifiers about the validity period of the credential. Verifies should check whether the credential is in their acceptable time range. E.g., that its validFrom date is not in the future.

These fields are optional and neither of them might appear in the Verifiable Credential document, which essentially creates a Verifiable Credential with indefinite lifetime. It is worth noting, that the validity period is not connected to the time when the concrete credentials documented was created by the issuer. E.g., in a credential representing a university degree the validFrom date will most probably point to the date when the user finished all her exams and made a successful defence of her thesis. The Verifiable Credential document saved in the user's wallet could be issued months or years later.

Credential Subject

The credentialsSubject property contains all the data about the subject of the credential. A Verifiable Credential must contain this property, as it must describe some subject. The property contains a set of objects with claims about the subject. What concrete claims are eventually inserted here depends on the concrete type of the credential.

It is worth noting that the credential contains information about a subject — an entity, and the credential is issued to a holder. Very often the holder and the subject will be the same entity, e.g., a person getting her passport as a Verifiable Credential. In other cases, these entities might be different. For example, a dog owner might get a vaccination certificate for her dog, in which case the dog will be the subject of the credential while the owner is the holder. A Verifiable Credential can even contain information about more than one subject, e.g., a marriage certificate would list both spouses as the two subjects.

Privacy-Preserving Features

Issuers can create Verifiable Credentials using features that can further preserve the holder's privacy. Selective-Disclosure JWTs (described in the context of Verifiable Credentials in this early draft specification) and Zero-Knowledge Proofs are example of such features.

With SD-JWTs holders are able to present to verifiers only some claims received in the Verifiable Credential. The verifiers are still able to check the integrity of the presented claim values, even though they do not have access to all the data from the Verifiable Credential. This is achieved by issuing the credential with hashed values and sending the holder these values outside the credential document. Upon verification, the verifier first checks the integrity of the origin Verifiable Credentials document, then creates hashes of the claim values presented by the holder and checks if these hashes are present in the Verifiable Credential.

Zero-Knowledge Proofs allow holders, apart from selectively disclosing claims, deriving claim values from the data they possess. A common example is transforming a birthdate into a claim that confirms that the holder is above certain age. Using ZKP solutions, the holder can prove that she is above certain age without actually disclosing any information about herself. The claim is cryptographically prepared in such a way that the verifier is able to check its correctness without access to any actual data from the holder. It is worth noting, that issuers must support these features as the Verifiable Credential document must be issued in a way that supports using Zero-Knowledge Proofs.

Verifiable Credential Protocols

Adhering to a concrete, standardized data format is only one part of the Verifiable Credential experience. Additional specifications are needed so that holders can perform operations on credentials:

• obtaining credentials from issuers,
• creating Verifiable Presentations based on the credentials they possess.

These specifications describe the flows that happen between wallet applications, issuers, and verifiers so that they can obtain and manage credentials in a safe way. Such standards allow all parties to operate together without the need of implementing bespoke flows for every issuer, wallet, or verifier available on the market. As with data formats, there are different standards that describe Verifiable Credential flows. Notable examples include:

• The Aries framework developed by the Hyperledger Foundation,
• OpenID for Verifiable Credentials developed by the OpenID Foundation.

The latter group of specifications is based on the well-established OAuth 2.0 protocol and makes working with Verifiable Credentials easier than is the case with the Aries framework. That is one of the reasons why the European Union regulators chose the OpenID specifications and the W3C Data Model for use in the Electronic Identification and Trust Services (eIDAS) Regulation.

Revoking Verifiable Credentials

Verifiable Credentials are meant to be used as long-lived documents, at least in scenarios where they represent long-lived physical credentials. Driving Licenses, Passports and University Degrees do not expire often and are rarely revoked. Still, to cover all situations, there is a need to support Verifiable Credential revocation. The problem of VC revocation is pretty much the same as with physical credentials. If someone presents their passport to a verifier, the verifier has to contact the issuer to check whether the document was revoked. The verifier loses the advantage of not having to maintain direct connection to the issuer.

It depends on the verifier whether it needs to check for credential revocation or not. For example, if the verifier only needs to know the holder's age, it might not care if the Verifiable Credential representing the holder's passport is revoked or not. In other cases, for example, when the holder wants to rent a car, it might be important for the verifier to make sure if the holder's driving license was revoked. Another issue are credentials revoked because of technical reasons (compromised certificates or private keys) or because of procedural errors (someone lied about her name or age). Again, it is up to the verifier to decide whether it should be concerned with such revocations or not.

One way of checking credentials for revocation is to query verifiable data registries for revocation entries. This mechanism is simple to implement, but raises some privacy issues. For example, once the verifier has some information from the holder, they can query the registry to gain additional information about them. Imagine this scenario — a celebrity uses electronic driving license to rent a car, then the rental company is able to periodically check the registry and instantly know if the celebrity lost their driving license.

Another solution might involve adding information about the date of issuance of the Verifiable Credential document, either to the document itself or to another, linked document. This will allow verifiers to decide whether the Verifiable Credential is fresh enough and ask the holder to refresh the credential otherwise. This way the verifier can assure freshness of the credential and the holder have her privacy protected. Such a solution also does not require any connection between the verifier and issuer (or a party that exposes the revocation registry). Here is a proposed standard for a solution with linked documents.

While revocation is an important part of the Verifiable Credentials lifecycle, there are no well-established standards that describe it. Implementers have to choose a method that fits their use-case and weigh the benefits against the drawbacks of different revocation solutions.

Use Cases For Verifiable Credentials

Verifiable Credentials are a generic concept that can be used in a variety of use cases. They are designed to mimic credentials that are used in the physical world, so that they can be utilized with at least the same level of security and usability in the digital one. In some cases, the security of digital identities will be even stronger than that of the physical ones, thanks to automated checks and strong cryptography. Of course, the document itself does not provide much functionality, it's how and where the credential is used. Here are some common scenarios when thinking about decentralized identities and Verifiable Credentials:

1. Electronic passports can be used in place of physical ones. This will allow the holder to prove her identity without the need of keeping the physical document with herself. The electronic passport can be kept in a cloud wallet, so that it is not tied to one concrete physical device. This will allow to access the passport even if the device is lost. What is more interesting, electronic passports or ID cards can be used to prove certain traits about the user without having to present the whole document. E.g., the user can prove her age or nationality when registering at a lottery website (or even only being above certain age, without presenting the actual age). The website will be able to securely verify this information and will not have to rely solely on the user declaration.
2. Electronic driving license can be used to rent a car or present to authorities abroad. Thanks to a standardized format of the document, verifiers are able to automatically translate field names so that they know what data they're dealing with (e.g., verifiers will not confuse the holder's name with her city of residence, etc.)
3. A university degree issued as a Verifiable Credential can be used in different applications (e.g., job application, grant application, etc.). The verifier will be able to ensure that the applicant is indeed an alumni of a given college, without performing complicated checks at the alma mater.
4. Boarding passes can be issued as Verifiable Credentials. Even though the main verifier is the same as the issuer (the airline company), the boarding pass can be used with other verifiers. E.g., it can be used in a duty-free shop to prove eligibility to tax-free shopping, and it can be done without revealing any information to the shop, apart from the destination (or even the simple fact of being eligible for tax-free shopping).

Summary

Verifiable Credentials are an important element of the digital identities landscape. They provide secure, machine-readable credentials that preserve features known from the physical world. Standards defining formats and protocols for managing Verifiable Credentials allow applications to securely work with these types of documents in a robust manner. Implementers should be aware that there are different standards as they will have to decide which they want to support in order to achieve the highest levels of interoperability in their applications. Digital identities are rapidly evolving, with standards being fleshed out and new ones emerging. However, this should not deter companies from engaging with these solutions, as at Curity we believe that digital identities will have a crucial role in the future of authentication and authorization.

1 Physical credentials are privacy-preserving in the sense that there is no direct link between the issuer and verifier. Whenever a holder presents her credential to the verifier, the issuer does not know that the credential is being used. ↩

Published: 2023-07-31

Michal Trojanowski

Product Marketing Engineer at Curity