David W. Chadwick and Daniel C. Burnett
Verifiable credentials (VCs) are the very heart of SSI architecture. In this chapter, you learn how VCs evolved, what they look like as data structures, what different formats and digital signature options are supported, and how VCs have been standardized at World Wide Web Consortium (W3C). Your guides are two of the primary authors of the W3C Verifiable Credentials Data Model 1.0 standard: David Chadwick, professor of information systems security at the University of Kent, and Daniel Burnett, executive director of the Enterprise Ethereum Alliance and former blockchain standards architect at ConsenSys. Daniel also served as co-chair of the W3C Verifiable Claims Working Group that created the VC standard.
We all use the physical version of verifiable credentials (VCs) many times each day (even though you may not realize it). Examples include plastic credit cards, driver’s licenses, passports, membership cards, bus passes, and more. We can’t live without them because they provide us with many benefits. In fact, we wouldn’t possess them if they didn’t provide us with those benefits. There would be no point.
Unfortunately, you can lose or misplace plastic cards and paper certificates or have them stolen. Worse still, they can be copied or cloned without you knowing about it. But most importantly, you can’t use them online—not unless you type all of their details into a web form, which is time-consuming, error-prone, and privacy-invasive. VCs, which are now a full World Wide Web Consortium (W3C) open standard (https://www.w3.org/TR/vc-data-model), will allow issuers to convert the physical VCs they produce today into digital VCs so that you can carry them around in your mobile phone, tablet, laptop, and other devices and use them online by simply pointing and clicking the screen.
Coupled with this ease of use advantage, you also gain other benefits with digital VCs:
-
They are extremely hard to steal (an attacker would need to steal your electronic device and the method you use to authenticate to the device).
-
They are more privacy-protecting since they support selective disclosure (disclosing only part of some verifiable data).
-
They are more secure because they support least privileges (also known as least authority: having permission to do only the required tasks and nothing more).
-
You can delegate them to other people to use (providing that the issuer allows this).
7.1 Example uses of VCs
While VCs can be used for all the same things we use physical credentials for nearly every day, VCs can be used for much more because they are digital. Here are some typical usage scenarios.
7.1.1 Opening a bank account
Imagine that you want to open a bank account at BigBank. You visit the local branch of BigBank, and the assistant asks you to provide two official forms of identification—the so-called Know Your Customer (KYC) check. You have a passport and various utility bills that qualify, but unfortunately, you left them at home. Fortunately, the bank supports the use of W3C VCs, and you always carry your mobile phone around with you—on which you’ve stored several dozen VCs.
You select your government-issued passport VC, which confirms your nationality, name, and age; and your health insurance VC, which confirms your current residential address. Both also contain a digital image of your face. Because the bank trusts the government and the insurance company, it is willing to accept these VCs as proof of your name and address and that the person making the application is really you. This allows the bank to open your bank account and be confident of your identity.
Consequently, the bank issues you a new VC that provides your bank account details, and you add this to your set of VCs on your mobile phone. You can use this new VC in a variety of ways. You can add these bank account details to your online auction, payments, and shopping accounts, give them to your employer for your monthly salary payments, or use them when opening a new high-interest savings account with another bank.
7.1.2 Receiving a free local access pass
You’re a pensioner (or a member of the FitSports sports club). You have a VC issued by the local senior citizen center (or FitSports) that says you are entitled to free travel on buses in the local metropolitan area (or entry into all leisure centers operated by FitSports). Whenever you enter a local bus (or a FitSports venue), you simply place your mobile phone on the NFC proximity reader, and it transfers a copy of your bus pass (or FitSports membership) VC to the operator, who then grants you free unrestricted access to the bus (or venue).
Periodically you need to renew this VC by applying online and paying the fee. The website does not need a username or password to authenticate you. Instead, you simply present your existing VC together with your credit card VC (for payment). A replacement VC is issued with a new expiry date; it automatically replaces the old VC on your mobile phone.
7.1.3 Using an electronic prescription
You are ill. You visit the doctor, who diagnoses an infection, for which she prescribes penicillin. The prescription is written in the form of a VC, where you are the subject, the doctor is the issuer, and the contents are the drugs that have been prescribed to you.
You don’t feel well enough to go to the pharmacy yourself to pick up your prescription, so you ask your wife to go in your place. You transfer the prescription VC to her mobile phone and issue a relationship VC for your wife, with her as the subject, you as the issuer, and an attribute or property that says she is your wife.
note Some identity management systems talk about a subject’s attributes or identity attributes, others about a subject’s personal information (PII). The VC specification talks about a subject’s properties. We use the term property throughout this chapter, with the understanding that it is synonymous with attribute, identity attribute, or PII.
Your wife goes to the pharmacy and presents the prescription VC and relationship VC. The pharmacist checks who issued the prescription, and because he knows the doctor who signed it and has previously validated her medical practitioner VC, he’s happy to give the prescribed drugs to your wife. The pharmacist records all this information in his audit log for future inspection.
These scenarios are just a few examples of how VCs can greatly simplify your life, both online and in the physical world. VCs were created for the following two purposes:
-
To provide a digital version of the credentials we carry in our digital wallets today.
-
To allow us to prove our identities “bottom-up”—with a set of claims about an identifier—rather than “top-down” by trying to define an identity and then attach information to it.
In the rest of this chapter, we explain these points and delve more into the technical details of VCs.
7.2 The VC ecosystem
As you can see from the previous examples, a number of entities and roles are involved in the VC ecosystem. These entities and roles are shown in figure 7.1.
Figure 7.1 The overall architecture of VCs, in which the holder sits at the center—the essence of user-centric design.
NOTE To help familiarize you, in this section, the specific roles defined in the official W3C VC specification have Uppercase First Letters. In subsequent sections, they appear as standard generic nouns.
The components of the VC architecture are as follows:
-
Issuer —The entity that issues VCs to users. In most cases, the user is the Subject, but in some cases, it may not be; for example, if the Subject is a pet cat and the VC is a vaccination certificate, then the Issuer will issue the VC to the cat’s owner.
-
Subject —The entity whose properties are stored in the VC. A Subject can be anything with an identity: a person, organization, human-made thing, natural thing, logical thing, and so on.
-
Holder —The entity that is currently holding the VC and presents it to the Verifier. In most cases, the Subject and the Holder are the same entity; but as you saw in the previous prescription and cat examples, this is not always the case.
-
Verifier —The entity that receives the VCs from the Holder and provides benefits in return.
-
Wallet —The entity that holds the VCs for the Holder. In many cases, the Wallet is integral to the Holder’s Agent, but the model allows for a remote wallet to exist, such as a cloud storage wallet.
-
Holder’s Agent —The software that interacts with the VC ecosystem on behalf of the Holder. This could be an app that you load onto your mobile phone or a program you run on your laptop.
-
Verifiable Data Registry—Conceptually, an internet-accessible registry that holds all the essential data and metadata that enables the VC ecosystem to operate. Examples of the types of data and metadata that can be stored in this registry are the following:
-
The schema or ontology for all the properties that the VCs may contain; revocation lists of revoked VCs
-
The subject properties that Issuers say they are authoritative for (for example, a national government may list Social Security numbers and passport details; a university may list its degrees and transcripts)
In practice, we envisage that many different Verifiable Data Registry components will exist initially because currently, there are no standards for them. VCs have become popularized due to the potential for blockchains and distributed ledgers to serve as decentralized, Verifiable Data Registries. However, blockchains are by no means the only option. Some Verifiable Data Registries may be centralized, others widely distributed but based on different technologies, and still others virtual and preconfigured into holders’ software agents. This may change in the long term as standards evolve, but for now, this entity is a placeholder to indicate that such a registry or registries are essential for any practical VC ecosystem to operate effectively and efficiently.
The VC ecosystem will consist of many Issuers, Verifiers, Holders, and registry services working together in ecosystems or trust networks. A typical arrangement might operate as follows:
-
A Verifier defines its policies for accepting VCs from Holders for its supported services. One notable feature of the VC ecosystem is that a Verifier may offer a range of services, and each service may have a different policy. This helps to provide the least-privileges feature because the Verifier needs to request only those subject properties that are necessary for the requested service. Each policy says which Issuers the Verifier trusts to issue which VCs for this service; for example, a pizza website might have a policy that says to place an online order for a pizza, the user should present a credit card VC issued by Visa or Mastercard (for payment), and optionally either a preferred customer VC issued by itself or a student VC issued by the National Students Association (to claim a 10% discount on the order).
-
Either before or after or simultaneously with step 1, the various Issuers issue their VCs to their Subjects, who store them in their digital wallets. In some instances, the VC is issued to a Holder who is not the Subject (e.g., pet vaccination VC) or multiple Subjects (e.g., marriage certificate VC).
-
When allowed by Issuers, some Subjects may pass on their VCs to other Holders.
-
The ultimate Holder requests a particular service from a Verifier.
-
The Verifier returns its policy to the Holder’s Agent, which checks whether the Holder has the necessary set of VCs in its Wallet. If so, the policy can be fulfilled.
-
The Holder presents the requested set of VCs to the Verifier, optionally inside a Verifiable Presentation (VP), which is a packaging mechanism to cryptographically prove that the Holder is sending the VCs, along with any conditions they may be placing on the Verifier.
-
If all is good, the Verifier performs the requested service for the Holder; if not, it returns an error message.
One caveat: as noted in chapter 5, the standards for Verifiers’ policies and the protocols between the various entities are still evolving in the marketplace. It is also worth noting that using VCs does not require DIDs, just as DIDs do not require VCs to take advantage of using distributed ledger services for identification. However, combining VCs and DIDs brings many advantages to both technologies. VCs can use distributed ledgers to implement components of the Verifiable Data Registry, and distributed ledgers can use VCs to gain access to their services (as outlined previously).
7.3 The VC trust model
The verifiable in verifiable credentials means the credential can be digitally signed and the digital signature can be cryptographically verified, as described in chapter 6. But that is not the only factor in determining whether a verifier can trust a particular VC. In this section, we discuss the complete VC trust model.
7.3.1 Federated identity management vs. VCs
For those familiar with today’s federated identity management (FIM) systems (described in chapter 1), you see that the VC architecture is quite different from FIM architecture.
DEFINITION The FIM architecture comprises the user, identity provider (IDP), and service provider (SP). At first sight, this appears very similar to the holder, issuer, and verifier roles in VC architecture. But the way the various parties interact is fundamentally different. In the FIM architecture, the user first contacts the SP and is then redirected to the IDP, where they log in and are then redirected back to the SP, providing the latter with the user’s identity attributes that the IDP is willing to release. In VC architecture, there is none of this web-based redirection within a defined “federation”—the user as holder obtains VCs from issuers and uses them independently at any verifier that will accept them.
The FIM architecture places the IDP at the center of the ecosystem, whereas the VC architecture places the holder at the center of the ecosystem. This is fundamental to understanding the VC philosophy: users are paramount, and they decide whom to give their VCs to. This compares drastically with the FIM philosophy: IDPs are paramount, and they decide who can receive the user’s identity attributes.
One of the world’s largest FIM infrastructures is eduGAIN, comprising thousands of university IDPs from all over the world, along with numerous academic service providers. This community directly recognizes this key deficiency of FIM [1]:
Insufficient attribute release by IDPs is considered by user communities as the major problem today in the eduGAIN space.
The FIM architecture has this requirement because IDPs must trust SPs to maintain the privacy and confidentiality of the user’s attributes that they send to the SP. In the VC ecosystem, this connection is broken. Issuers send the user’s identity attributes to the user as properties in VCs, and the user decides what to do with them, just as they would with a physical credential issued to the user’s physical wallet. The issuer doesn’t know which verifiers the user is giving their VCs to (unless the user or the verifier tells the issuer). So the issuer no longer needs to trust the verifier. This is a fundamental difference between the trust models of conventional FIM systems and the VC system.
7.3.2 Specific trust relationships in the VC trust model
The differences between the FIM trust model and the VC trust model are apparent from figure 7.2. Here we see the three major actors—issuers, holders, and verifiers—and their relationships to the three technical components: the holder’s agent, the wallet, and the verifiable data registry. Trust relationships are shown with arrows.
Figure 7.2 The VC trust model, where holders are at the center, and verifiers only need to trust issuers (and the verifiable data registry trusted by all parties)
Let’s delve more deeply into each of the trust relationships depicted here:
-
The verifier must trust the issuer to be authoritative for the subject’s properties that are contained in a VC that it receives. For example, a verifier would usually trust a national government to be authoritative for a subject’s nationality property but would not necessarily trust the government to be authoritative for a university degree property. Conversely, a verifier would usually trust a university to be authoritative for a subject’s degree qualification property, but not necessarily for the subject’s golf club membership property. Each verifier determines its own trust rules. There is no compulsion for any verifier to trust any VC or any issuer. The verifier determines which VCs from which issuers to trust according to its risk profile. However, to help verifiers make their trust decisions, a verifiable data registry (or a governance authority that publishes a governance framework—see chapter 11) will often contain a list of known issuers and the properties for which they state they are authoritative. Verifiers can then determine who and what to trust from this list.
-
Consequently, all participants trust the verifiable data registry to be tamper-evident and to be an accurate and up-to-date record of which data is controlled by which entities. Note that we say tamper-evident and not tamper-proof. No system on earth can stop determined attackers from tampering with it, but the verifiable data registry should allow its users to detect whether it has been tampered with.
-
Both the subject/holder and the verifier must trust the issuer to issue true VCs. An issuer that lies cannot be trusted by anyone.
-
Both the subject/holder and the verifier must trust the issuer to revoke VCs that have been compromised or are no longer true, in a timely manner. This policy is determined by the issuer. The best practice is for issuers to publish the revocation timeframes under which they operate because this is fundamental to the risk-mitigation strategies of the verifiers. In certain circumstances, a subject may know that an issuer holds out-of-date information and that the corresponding VC is incorrect, but the subject finds it very difficult to get the issuer to update its database and reissue the VC. For this reason, there is a dispute procedure that is discussed further in section 7.8.2.
-
The holder trusts their wallet to store VCs securely, not release them to anyone other than the holder, and not allow them to be corrupted or lost while in its storage.
As you can see, this is a relatively simple trust model that corresponds almost exactly to the trust model for the physical credentials we have been using for decades. This is one of the major strengths of the VC ecosystem for the simple reason that it works the same way trust in the real world does—there is no artificial insertion of an identity provider into all of a user’s relationships.
7.3.3 Bottom-up trust
Credentialing systems often begin with a notion of first “securing one’s identity,” as in the PKI world. However, these top-down approaches to trust lead to centralization of information and control, dominance by small numbers of commercial entities, and loss of individual privacy. The bottom-up approach to trust taken with VCs seeks to avoid these pitfalls.
One of the biggest challenges to adoption so far has been the simplicity of the VC trust model. The current dominance of the internet giants that operate the largest FIM systems globally (the “Login with ______” buttons you see on websites everywhere) has trained internet users to believe they are the only sources of truth that verifiers will trust. But in the offline world, there are millions of issuers of credentials and millions of verifiers of those credentials, and the entire system is decentralized. Trust relationships are established peer-to-peer, “pairwise,” directly between holders and verifiers. This is sometimes called the web of trust model, and it is the bottoms-up trust model that VCs emulate. There are numerous examples of how this will work in parts 3 and 4 of this book.
7.4 W3C and the VC standardization process
The work on what we now call verifiable credentials began as an offshoot of the Web Payments Interest Group at the World Wide Web Consortium (W3C). The W3C is the standards body that defines the HTML web programming language and the other key standards for the interoperability of the web. The Web Payments Interest Group’s job was to standardize how to make payments on the web: in other words, how to pay directly from your web browser.
This required a way to authenticate individuals. So the Web Payments Interest Group started up the Verifiable Claims Task Force (VCTF, https://w3c.github.io/vctf) to explore whether the W3C could productively work in this area. This new non-standards-track group consisted mostly of members from both the Web Payments Interest Group and the W3C Credentials Community Group (another non-standards track group that is incubating all things related to digital credentials).
The VCTF developed an initial specification from which the group concluded that, indeed, W3C could productively help in this area. The VCTF wrapped up in May 2017 and transferred its specification to the newly created W3C standards-track Verifiable Claims Working Group (VCWG). At first, the specification was named the Verifiable Claims Data Model and Syntaxes specification, but after a year’s worth of work, the VCWG changed the name to Verifiable Credentials Data Model 1.0.
At this point, you may be wondering why the group was named Verifiable Claims while the specification name talks about Verifiable Credentials. The working group’s initial proponents very much believed—and still do—that the work is about creating verifiable credentials, where each credential can contain one or more claims from the same issuer. As the standards-track Working Group was being created, some parties at W3C objected to using the term credentials out of a concern that in the web security community, the word credentials meant only a username and password. Once the VCWG was underway and more people joined the effort, that concern diminished—especially as it became clear that credential really was the appropriate word.
In summary, the W3C Verifiable Credentials Data Model 1.0 specification (which we will refer to as the VC Data Model spec; https://www.w3.org/TR/vc-data-model) was created in the W3C Verifiable Claims Working Group.
The specification defines more than just a data model for VCs, however. It includes:
-
A data model for VCs, the credentials that an issuer provides to a holder
-
A data model for verifiable presentations (VPs), the collection of credentials that a holder may present to a verifier
-
A way to represent (or express) that data model using JSON Linked Data (JSON-LD) syntax
-
A way to represent (or express) that data model using JSON Web Tokens (JWT) syntax.
We refer to the latter two items as syntactic representations of the data model. The difference between a data model and a syntactic representation (also sometimes referred to as a serialization) is that a data model describes relationships of one entity to another: for example, I am a son to my father or he is a father to me. We could represent that with a diagram, but diagrams are not convenient for computers to work with. Alternatively, we could represent those relationships using a written format or syntax that is readable to computers, humans, or both. Both of the syntactic representations for VCs that we cover are readable by both computers and humans.
7.5 Syntactic representations
Although it might seem logical to describe the general data model before delving into how that data model is expressed in a concrete syntax, the data model is much easier to explain using concrete examples. So, in this section, we present concrete representations defined by the specification. These support the examples we show later. For now, do not be concerned with the various properties or attributes you see in these examples; definitions will come later in section 7.6. First, some background.
7.5.1 JSON
The two syntactic representations defined by the VC data model 1.0 specification are based on JavaScript Object Notation (JSON), which is a simplification of the syntax used to represent collections of data items in the JavaScript programming language. This subsection summarizes JSON; the following subsections summarize the two syntactic representations defined in the VC data model specification based on JSON.
NOTE Although these two syntactic representations, the JSON-LD representation and the JWT representation, are the only ones defined in the 1.0 specification, it is expected that others will be defined in the future.
A JavaScript object consists of an outer pair of curly braces that contain zero or more key-value pairs separated by commas, where each key-value pair is a key string, a colon, and a value. Between any two of those parts, white space is ignored. The key is referred to as a property of the object, and the value is the property’s value. Here are some examples:
{height:5, width:7} {"my height":75, "your height": 63} {direction:"left", coordinates1: {up:7, down:2}, coordinates2: {up:3, down:5}, magnitude: -6.73986 }
In the first example, the first key string is height, and its value is 5; the second key string is width, and its value is 7.
Notice that by default, a key is a sequence of alphanumeric characters (beginning with a letter) without spaces but that spaces can be introduced by quoting the string. The value can be a string, an integer, a floating-point value, or another object. Some unquoted strings have particular meanings when used in JavaScript. Examples include true, false, and null.
7.5.2 Beyond JSON: Adding standardized properties
JSON allows for direct representation of any tree-structured data, but there is no standard set of properties for JSON objects. By standardizing a set of properties for VCs, it becomes possible to automate the creation and use of those credentials. The next two subsections describe how to represent VC data with standardized properties using two different syntactic representations: JSON-LD and JWT. The properties in each that are critical to the data model are mappable one-to-one between the two formats.
7.5.3 JSON-LD
JSON Linked Data makes it easy to incorporate properties defined in structured templates called schemas. As an example, https://schema.org/Person defines a set of properties for a person. JSON-LD processors know how to automatically use these schemas to see what types of values the schema’s properties expect.
In JSON-LD, the desired schema locations are listed in the @context property’s value. Then the type property specifies which particular schemas from those locations are being used. Those, in turn, define the allowed properties.
Here is an example where we are using properties from the VerifiableCredential schema at https://www.w3.org/2018/credentials/v1 and the alumniOf property from the Person schema at https://schema.org:
{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://schema.org", ], "id": "http://example.edu/credentials/58473", "type": ["VerifiableCredential", "Person"], "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "alumniOf": "Example University" }, "proof": { ... } }
This approach to naming is incredibly flexible since anyone can create a new schema (called a context), post it at a stable URL on the internet, and then reference its properties in the VC. Since the previous example only cares about the alumniOf property, we can create a new, more specific JSON-LD context called AlumniCredential that contains only one property, alumniOf. Assuming the new context is stored at https:/./mysite.example.com/mycredentialschemas, the example now looks like this:
{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://mysite.example.com/mycredentialschemas", ], "id": "http://example.edu/credentials/58473", "type": ["VerifiableCredential", "AlumniCredential"], "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "alumniOf": "Example University" }, "proof": { ... } }
An essential aspect of JSON-LD contexts is that the URLs and schema definitions must be stable and unchanging. This allows the context and schema definitions to be looked up only once (either automatically or manually) and used from then on without any risk of them changing. It is very important to note that the JSON-LD syntax for VCs can be used without any dynamic fetching of context information. Essentially, these contexts can be thought of as defining separate namespaces, so one person’s definition of alumniOf does not have to be the same as someone else’s. When the contexts are different, you know that they are not intended to be the same thing. This feature of JSON-LD is very helpful in VCs since the VC data model is purposefully an open-world data model, where user-defined properties may be added at any time.
As in the Verifiable Credentials Data Model specification, this chapter uses JSON-LD as the default syntax for most of the examples. (If you’re interested in learning more, we recommend https://json-ld.org/primer/latest.)
7.5.4 JWT
JSON Web Tokens (RFC7519), pronounced either “J W Ts” or “Jots,” are a previously standardized way to represent signable claims, or attestations, using JSON. The syntax is convenient for converting into binary representations that are precise in using white space and easily compacted to reduce storage and transmission costs. Given the breadth of the JWT-based ecosystem, it made sense to find a way to represent VCs and VPs in JWTs.
JWTs have three parts: a header, a payload, and an optional signature (of the payload). For our purposes, the header and its property values are not particularly relevant but are outlined in the VC Data Model specification. Since the JWT payload is essentially a restructuring of a JSON-LD VC, the easiest way to understand the JWT syntax for VCs is to first generate the JSON-LD syntax and then convert it. The most common properties are mapped as follows:
-
Replace issuanceDate with iat, and change the date format to a UNIX timestamp (NumericDate).
-
Replace expirationDate with exp, and change the date format to a UNIX timestamp (NumericDate).
-
Remove the credentialSubject.id property, and create a sub property with the same value.
A similar process is used to convert VPs to a JWT payload, with details explained in the specification. If a JSON Web Signature (JWS) is provided in a VC, it proves the issuer of the VC; and in a VP, it proves the holder of the VP. The VC proof property may still be provided if other proof information is used: for example, zero-knowledge-based approaches.
After the previous conversions, any other remaining properties (including proof, if present) are moved into a new JSON object under the new JWT custom claim vc (or vp for a presentation).
As an example, let’s look at a JSON-LD VC (minus the proof):
{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://schema.org" ], "id": "http://example.edu/credentials/3732", "type": ["VerifiableCredential", "Course"], "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "educationalCredentialAwarded": "Bachelor of Science in Mechanical Engineering" }, "issuer": "did:example:abfe13f712120431c276e12ecab", "issuanceDate": "2019-03-09T13:25:51Z", "expirationDate": "2019-03-09T14:04:07Z" }
After converting to a JWT payload, the same VC looks like this (note that the cryptographic nonce—an arbitrary number that can be used just once in a cryptographic communication—is a feature of JWTs not derived from the original JSON-LD VC):
{ "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21", "jti": "http://example.edu/credentials/3732", "iss": "did:example:abfe13f712120431c276e12ecab", "iat": "1541493724", "exp": "1573029723", "nonce": "660!6345FSer", "vc": { "@context": [ "https://www.w3.org/2018/credentials/v1", "https://schema.org" ], "type": ["VerifiableCredential", "Course"], "credentialSubject": { "educationalCredentialAwarded": "Bachelor of Science in Mechanical Engineering" } } }
This description was designed to give experienced users of JWTs a rough idea of how this conversion process works and let others know that the JWT syntax exists. The entire JWT-based syntactic framework is fairly extensive, and there are subtleties in how the pieces work together for VCs and VPs. These are best answered by reading the VC Data Model spec.
7.6 Basic VC properties
Now that we’ve covered the syntactic representations, we can explain the properties defined by the data model. The most basic VC needs to hold only six pieces of information (encoded as JSON properties), as shown in figure 7.3.
Figure 7.3 The structure of a basic VC, showing the metadata component, the claim component, and the proof component
The contents of each of these JSON properties are described next:
-
@context—When people communicate, they need to know what language and vocabulary to use. While the default encoding language used for VCs is JSON-LD, that does not tell us what JSON properties a VC might contain. The @context property tells us which sets of vocabularies were used to construct this VC. Syntactically, @context comprises a sequence of one or more uniform resource identifiers (URIs). Ideally, each URI should point to a machine-readable document containing a vocabulary that a verifier can automatically download and configure. Because many implementations may not be that sophisticated, the URI may alternately point to a human-readable specification that allows an administrator to configure the verifier software with the necessary vocabulary. Note that @context on its own may provide more information (vocabulary) than a verifier wishes to use. Therefore, the VC also contains a type property.
-
type—The type property contains a list of URIs that assert what type of VC this is. The first type must always be https://www.w3.org/2018/credentials/v1, which can be abbreviated to VerifiableCredential using the JSON- LD @context mechanism. Verifiers can read the list of types and quickly determine if they can understand and process this VC. If the VC is a type the verifier does not recognize, the verifier can immediately reject it without further processing.
-
id—The id property is the unique identifier of this VC, created by the issuer. It consists of a single URI. This allows any entity to unambiguously reference this VC.
-
issuer—The issuer property uniquely identifies the issuer. It is a URI. This URI can point to a document that fully describes the issuer—for example, a DID that points to a DID document—or it can contain the DNS name of the issuer, and the verifiable data registry can contain further details about the issuer, such as its X.509 public-key certificate.
-
credentialSubject—This property contains the claims the issuer is making about the subject. It consists of the ID of the subject and the set of properties the issuer is asserting about the subject. In some cases, the ID may be missing: for example, if this is a bearer VC (such as a concert ticket) that can belong to anyone. Since VCs are designed to preserve a subject’s privacy, the ID is a pseudonym for the subject in the form of a URI. A subject can have countless pseudonyms, and each VC can contain a different ID. In this way, without additional information, a verifier cannot know that two VCs with different subject IDs belong to the same individual.
note Selective disclosure is another privacy feature that VCs can support. There are two recommended ways to achieve this: by including the absolute minimum number of properties (preferably one) in a single VC (a so-called atomic VC), or by using zero-knowledge proof (ZKP) VCs (discussed in section 7.10). In the former case, an issuer, instead of issuing a complex VC containing multiple properties, may issue a set of atomic VCs. For example, a full driving license VC may contain the following four properties: name, address, date of birth, and vehicle classes, whereas the alternative is four atomic VCs, each containing one property and a link ID (to link them all together). The holder can then selectively disclose individual properties from his or her driving license.
-
proof—For a credential to be verifiable, it needs a signature, referred to more generally in the VC Data Model spec as a proof. This cryptographically proves that the issuer issued this VC and that it has not been tampered with since issuance. Every VC must contain either the proof property or, if using JWT syntax, a JSON Web Signature. There is no single standard for the proof property’s contents since several different types of proof are envisaged (see section 7.10). If this property is used, the one common property that all proofs must contain is the type property, which asserts the type of the proof.
Other basic properties that are optional but generally very useful include the following:
-
issuanceDate—The combined date and time, in ISO 8601 format, after which the VC is valid. Note that it is not necessarily the actual date the VC was issued, as an issuer may issue a VC before or after this date, but it is the date before which the VC is invalid.
-
expirationDate—The combined date and time, in ISO 8601 format, after which the VC is invalid.
-
credentialStatus—Provides the verifier with details of the VC’s current status: whether it has been revoked, suspended, superseded, or otherwise changed since its issuance date. This is a particularly useful property for a long-lived VC but less so for a short-lived VC, i.e., one where it is expected that the VC will not change its status before its expiration date. (Whether a VC is short-lived or long-lived depends on the application using the VC and the risk profile of the verifier. For a stock market transaction, long-lived might be greater than a few seconds; for a national passport, short-lived might be 24 hours.) There is no standard format for the credentialStatus property, but every status must contain an id and type property. The id property is the unique URL for this credential status instance—it is where the verifier can get the status information for this VC. The type property states the type of credential status, which in turn dictates what other properties the status property should contain.
Here is a VC, encoded in JSON-LD, that contains all these basic properties:
{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://example.com/examples/v1" ], "id": "http://example.edu/credentials/3732", "type": ["VerifiableCredential", "UniversityDegreeCredential"], "issuer": "https://example.edu/issuers/14", "issuanceDate": "2010-01-01T19:23:24Z", "expirationDate": "2020-01-01T19:23:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "BachelorDegree", "name”: "Bachelor of Science in Mechanical Engineering" } }, "credentialStatus": { "id": "https://example.edu/status/24", "type": "CredentialStatusList2017" }, "proof": { "type": "RsaSignature2018", "created": "2018-06-18T21:19:10Z", "verificationMethod": "https://example.com/jdoe/keys/1", "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e", "signatureValue": "BavEll0/I1zpYw8XNi1bgVg/sCneO4Jugez8RwDg/+ MCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuFibcC1wps PRdW+gGsutPTLzvueMWmFhwYmfIFpbBu95t501+rSLHIEuujM/+PXr9Cky6Ed +W3JT24=” } }
While this example describes the basic properties of a VC, also note the following:
-
A VC can contain multiple claims, where each claim is about a different credential subject. For example, a marriage certificate VC could contain one claim about subject ID x and another claim about subject ID y. The property of the first claim could be “married to subject ID y” and of the second claim “married to subject ID x.”
-
A VC can contain multiple proofs; for example, a highly confidential or valuable VC might require two directors of the issuing company to sign it.
7.7 Verifiable presentations
A VP is one way a holder may combine several VCs to send to a verifier. It is very similar to a VC in that it contains metadata about the presentation plus a proof signed by
the holder. However, the contents are now a set of VCs rather than a set of claims (see figure 7.4).
Figure 7.4 A basic VP that contains a group of VCs plus metadata about them
One notable difference between a VC and a VP is that the issuer property is missing. If present, it would have contained the holder’s ID, and indeed, a draft version of the specification did contain just that. When it was present, if the VP issuer’s ID equaled the ID of the credential subject, it was very easy for the verifier to determine that the holder was the subject of the encapsulated VC. However, this property was removed in order for ZKP implementations not to be forced to reveal the ID of the holder (see section 7.10 for a fuller explanation). For non-ZKP VCs, it is expected that the verifier can determine the holder either from the protocol exchange before the VP is sent or from the proof property of the VP (which can contain an identifier for the signer).
Another difference between a VP and a VC is that the id property is optional. It needs to be present only if the holder wants to uniquely refer to this VP on a subsequent occasion.
Similar to VCs, a VP may contain multiple proofs. For example, say a holder has several VCs, each with a different credential subject ID that identifies the holder, implying a different asymmetric key pair for each VC. Then the holder can send a VP to a verifier containing this set of VCs and a set of proofs, each created by one of the key pairs.
Although usually clear from the context, it is common for users of VCs and VPs to refer to both generically as VCs unless they are specifically talking about a VP.
7.8 More advanced VC properties
VCs were developed using an open-world model, meaning anyone can add any property to a VC that is suitable for their application needs. Nevertheless, there are several properties that VCWG thought would be generally useful for a range of applications. These are described in this section. The following section describes the rules the VCWG recommends application designers follow if they wish to extend their VCs, remain conformant to the W3C specification, and interoperate with others. (Of course, anyone can extend a VC in any way they wish, but in that case, they should not expect other implementations to interoperate with theirs.)
7.8.1 Refresh service
VCs are designed to have a limited lifetime for several reasons. First, cryptography grows weaker over time, so enhanced proof mechanisms need to be put in place. Second, people’s circumstances and credentials change with time. A good example is a VC based on age-related properties or a student ID for a specific grade level.
The refreshService property allows an issuer to control and provide details about how the current VC can be refreshed or updated. If the issuer wants the verifier to know how to refresh the VC, the issuer can insert the refreshService property into the VC. If the issuer only wants the holder to know how to refresh the VC, the refreshService property should not be inserted into the VC, but rather into the VP that encapsulates the VC the issuer sends to the holder, since this VP is retained by the holder and is not forwarded to anyone else.
The refreshService property contains two mandatory properties:
-
type—Says what type of refresh service this is, and controls what other properties the refreshService property should contain
If a verifier wants to know whether the presented VC contains the very latest information about the subject, it can use the refresh service to find out. However, there are several caveats to doing so. First, this can breach the subject’s privacy because the issuer now learns that the subject’s VC has been presented to a particular verifier. Second, the verifier will need to be authorized to access the issuer’s refresh service (because the issuer is unlikely to issue a subject’s VCs to anyone who asks for it). Yet if the verifier is already authorized, it will already know the refresh service details and won’t need to consult the refreshService property. Consequently, the practice of inserting the refreshService property into a VC generally is not recommended.
Conversely, if a subject/holder knows that a VC is about to expire or that a property (claim) in their VC is out of date (and the issuer knows the new property value), then using the refreshService property in a VP is an easy way for the holder to obtain an updated VC (and for the issuer to simultaneously revoke the old VC).
An example of a VC containing the refreshService property is given in listing 7.1 in section 7.8.4.
7.8.2 Disputes
Sometimes an issuer holds out-of-date information about a subject—but the subject cannot compel the issuer to update its database and issue a revised VC. Other times, a person is the victim of identity theft, and an attacker masquerades as them by using falsely obtained VCs. In both these cases, the VCs that exist are false, and the rightful subject wants them to be revoked. If the issuer is slow to act in these circumstances, what should the rightful subject do? The answer is a DisputeCredential. This differs from a normal VC in that
-
It is signed by the rightful subject and not the original issuer.
-
The credentialSubject property ID contains the ID of the disputed VC.
-
The credentialSubject property should also contain the following:
-
A statusReason property with the value set to the reason for the dispute. This is currently a free-form string rather than an encoded value, but standardized reason codes are anticipated in the future.
-
If only part of the disputed VC is wrong, and some of its claims are correct (i.e., it is not an atomic VC), then the credentialSubject property can also contain a reference to the disputed claim.
In the case of an out-of-date or incorrect VC held by the rightful subject, both the disputed VC and the DisputeCredential can be sent to the verifier. The verifier can then validate that the subject is the same in both VCs and determine the disputed property(ies).
If a criminal is performing identity theft on a rightful subject, or if a denial-of-service attacker is trying to cause a verifier to doubt a valid VC, the subject in the disputed VC is different from the subject who signed the DisputeCredential. In this case, the verifier should ignore the DisputeCredential unless the verifier has some out-of-band means of assessing its validity. Verifiers must establish their own policies for how to handle these cases.
Here is an example of a DisputeCredential:
{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "id": "http://example.com/credentials/123", "type": ["VerifiableCredential", "DisputeCredential"], "credentialSubject": { "id": "http://example.com/credentials/245", "currentStatus": "Disputed", "statusReason": "Address is out of date" }, "issuer": "https://example.com/people#me", "issuanceDate": "2017-12-05T14:27:42Z", "proof": { "type": "RsaSignature2018", "created": "2018-06-17T10:03:48Z", "verificationMethod": "did:example:ebfeb1f712ebc 6f1c276e12ec21/keys/234", "nonce": "d61c4599-0cc2-4479-9efc-c63add3a43b2", "signatureValue": "pYw8XNi1..Cky6Ed=" } }
7.8.3 Terms of use
Most physical VCs today are governed by terms of use. Some are stated on a plastic card, while others are published on a website, with the plastic card containing the URL of the web page. Examples of terms of use printed on physical cards include “Not Transferable” and “Only the authorized signatory may use this card.” Examples of referring to a website include “Go to <URL> for full details of membership” or “Refer to <URL> for conditions of use.”
The standard way of adding terms of use to a VC (or a VP) is via the termsOfUse property. Terms specified by the issuer—that apply to both the holder and any verifier—are typically inside the VC. Terms specified by the holder—which apply only to the verifier—are inside the VP. Like all extensions to the basic VC (or VP), the termsOfUse property must contain its type, as this governs its contents. The id property is optional, but if present, it should point to a web page where the terms of use for this VC (or VP) can be obtained.
It is recommended that the terms of use should specify actions that the verifier, if it is to accept the VC (and or VP) from the holder,
More sophisticated terms of use may specify when these actions should take place: “Notify the subject upon accepting this VC,” “delete this information after 2 weeks,” “archive this VC for up to one year,” and so on. An example termsOfUse property is shown in listing 7.1.
7.8.4 Evidence
The VC ecosystem is based on trust. However, trust is rarely binary (on or off). It is usually qualified. I may trust you with $50 but not with $5,000. Similarly, a verifier may trust a VC issuer, but the level of trust that the verifier places in the issuer and the issued VC may be qualified depending on the procedures undertaken by the issuer, the strength of the cryptographic algorithms it used, the evidence it gathered, what service the holder wishes to perform, and so on. The evidence property is designed for the issuer to help the verifier determine the level of confidence it can have in the claims inside the VC.
Authentication systems have the concept of level of assurance (LOA). As defined by the widely followed original NIST standard [2], this is a four-level metric informing recipients about the level of confidence they can have in the strength of authentication of the remote party. This has since been superseded by a more sophisticated LOA matrix from NIST [3] because experience showed that a simple 1-to-4 LOA is insufficient to convey the inherent complexity of user authentication.
VCs are just as complex as authentication tokens, if not more so. Consequently, rather than inserting a simple fixed metric into a VC, similar to an authentication LOA, the VCWG adopted an open-ended approach using the evidence property. This allows the issuer to insert whatever information it wishes into a VC to assist the verifier in determining the level of confidence it can have in the VC’s claims. It also provides future-proofing: as VCs gain more traction and user experience, usage of the evidence property is bound to become more sophisticated.
As always, every evidence property must contain its type since this determines what type of evidence it is and what other properties the evidence must contain. The id is an optional field that should point to where more information about this evidence instance can be found. The following listing includes an example of the evidence property.
Listing 7.1 Complex VC containing several advanced properties
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://example.org/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science in Mechanical Engineering"
}
},
"credentialSchema": {
"id": "https://example.org/examples/degree.json",
"type": "JsonSchemaValidator2018"
},
"termsOfUse": {
"type": "IssuerPolicy",
"id": "http://example.com/policies/credential/4",
"profile": "http://example.com/profiles/credential",
"prohibition": [{
"assigner": "https://example.edu/issuers/14",
"assignee": "AllVerifiers",
"target": "http://example.edu/credentials/3732",
"action": ["Archival"]
}]
},
"evidence": [{
"id": "https://example.edu/evidence/f2aeec97-fc0d-42bf-
8ca7-0548192d4231",
"type": ["DocumentVerification"],
"verifier": "https://example.edu/issuers/14",
"evidenceDocument": "DriversLicense",
"subjectPresence": "Physical",
"documentPresence": "Physical"
}, {
"id": "https://example.edu/evidence/f2aeec97-fc0d-42bf-
8ca7-0548192dxyzab",
"type": ["SupportingActivity"],
"verifier": "https://example.edu/issuers/14",
"evidenceDocument": "Fluid Dynamics Focus",
"subjectPresence": "Digital",
"documentPresence": "Digital"
}],
"refreshService": {
"id": "https://example.edu/refresh/3732",
"type": "ManualRefreshService2018"
},
"proof": {
"type": "RsaSignature2018",
"created": "2018-06-18T21:19:10Z",
"verificationMethod": "https://example.com/jdoe/keys/1",
"nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
"signatureValue": "BavEll0/I1zpYw8XNi1bgVg/s...W3JT24 = "
}
}
7.8.5 When the holder is not the subject
In many VC uses, the subject and the holder are the same entity. The verifier can determine this simply by ensuring that the credentialSubject ID inside the VC equals the identity of the holder who signed the VP. But what about those cases where the holder and the subject are different? We have already cited several examples, such as when the subject is a pet, an IoT device, or a relative of the holder. How is the verifier to know the difference between a rightful holder, who obtained the VC with the full permission of both the subject and the issuer, and an attacker who stole the VC from the rightful holder? (For security purposes, both the subject and the issuer should give their permission for the VC to be transferred. The VCWG is standardizing a way for the issuer to mandate that the VC must not be transferred.) For example, say I steal your prescription VC and take it to the pharmacy so that I can obtain your drugs. How is the pharmacist to know the difference between your friend, whom you want to collect your prescription, and myself, who claims to be your friend?
The VC Data Model spec contains the following four suggested ways to do this. However, none of them were standardized in version 1.0 because it was deemed too early to determine which of these will become the preferred method(s):
-
The issuer issues the VC to the subject, who passes it to a holder; then the subject issues a new, very similar VC to the holder. This new VC contains the same credentialSubject property value as the original VC, but now the holder is the subject, and the original subject is the issuer of the new VC. An example of this “passing on” is provided in listing 7.2.
-
The issuer issues the VC to the subject, who passes it to a holder; then the subject issues a relationship VC to the holder, indicating the relationship between them. An example of a relationship VC is given in listing 7.3.
-
The issuer issues the VC directly to the holder (who is not the subject), and then the issuer also issues a relationship VC to the holder, indicating the relationship between the subject and the holder.
-
The issuer issues the VC to the subject with a relationship claim that asserts the relationship between the subject and a third party. Now the subject can pass the VC to the third party to become the holder, either immediately or later. For example, a VC could be issued to a child that contains a relationship claim to the ID of the child’s parent. An example of this is given in listing 7.4.
Listing 7.2 VP containing a VC passed to the holder with confirmation
{
"id": "did:example:76e12ec21ebhyu1f712ebc6f1z2,’
"type": ["VerifiablePresentation"],
"credential": [{
"id": "http://example.gov/credentials/3732",
"type": ["VerifiableCredential",
"PrescriptionCredential"],
"issuer": "https://example.edu",
"issuanceDate": "2010-01-01",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"prescription": {
"drug1": "val1"
}
},
"revocation": {
"id": "http://example.gov/revocations/738",
"type": "SimpleRevocationList2017"
},
“proof”: {
"type": "RsaSignature2018",
"created": "2018-06-17T10:03:48Z",
"verificationMethod":
"did:example:ebfeb1f712ebc6f1c276e12ec21/
keys/234",
"nonce": "d61c4599-0cc2-4479-9efc-c63add3a43b2",
"signatureValue": "pky6Ed..CYw8XNi1="
}
},
{
"id": "https://example.com/VC/123456789",
"type": ["VerifiableCredential",
"PrescriptionCredential"],
"issuer": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"issuanceDate": "2010-01-03",
"credentialSubject": {
"id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
"prescription": {
"drug1": "val1"
}
},
“proof”: {
"type": "RsaSignature2018",
"created": "2018-06-17T10:03:48Z",
"verificationMethod":
"did:example:ebfeb1f712ebc6f1c276e12ec21/
keys/234",
"nonce": "d61c4599-0cc2-4479-9efc-c63add3a43b2",
"signatureValue": "pYw8XNi1..Cky6Ed="
}
}
],
“proof”: {
"type": "RsaSignature2018",
"created": "2018-06-18T21:19:10Z",
"verificationMethod":
"did:example:76e12ec21ebhyu1f712ebc6f1z2/keys/2",
"nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
"signatureValue": "BavEll0/I1..W3JT24="
}
}
Listing 7.3 Relationship VC issued to a parent that identifies the child
{
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "RelationshipCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1c276e12ec211f712ebc6f",
"child": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"type": "Child"
}
},
"proof": {
"type": "RsaSignature2018",
"created": "2018-06-18T21:19:10Z",
"verificationMethod":
"did:example:76e12ec21...12ebc6f1z2/keys/2",
"nonce": "c0ae1c8e-c7e7-469f-b252-86ijh767387e",
"signatureValue": "BavEll0/I1..W3JT24="
}
}
Listing 7.4 Child’s VC containing the identification of the mother
{
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "AgeCredential",
"RelationshipCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"ageUnder": 16,
"parent": {
"id": "did:example:ebfeb1c276e12ec211f712ebc6f",
"type": "Mother"
}
},
“proof”: {
"type": "RsaSignature2018",
"created": "2018-06-18T21:19:10Z",
"verificationMethod":
"did:example:76e12ec21ebhyu1f712ebc6f1z2/keys/2",
"nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
"signatureValue": "BavEll0/I1..W3JT24="
}
}
7.9 Extensibility and schemas
As mentioned earlier, VCs are built on an open-world model, meaning anyone is free to extend VCs any way they want to—“permissionless innovation” is the phrase used in the VC Data Model spec. Open extensibility maximizes the applicability of VCs since all application developers can extend VCs to satisfy their application’s requirements. But if this extensibility is not properly controlled, it will lead to a lack of interoperability, as software A will not be able to understand a VC transmitted by software B.
This is not a new problem. X.509 certificates had the same issue. They solved it by allowing the content of certificates to be extended—in any way that anyone wanted—by requiring every extension to be labeled with a globally unique object identifier (OID). (OIDs form a hierarchical tree of numbers where the control of nodes is delegated downward. You can think of this as the DNS in numerical form.) The flaw in this solution was that there was no global OID registry, so it was impossible for software A to find out what an extension used by software B meant. This led to the IETF PKIX group standardizing dozens of extensions and publishing their OIDs so that everyone could know what they meant. But this was a cumbersome and time-consuming mechanism. Something better was needed.
VCs have a new way of solving the extensibility problem by using the internet to publish all the extensions that application developers invent and mandating that VCs include the following in their encoding:
-
The @context for this VC—As we saw earlier, this allows the issuer, holder, and verifier to establish the right context, in terms of VC vocabularies (properties and alias names), for understanding the contents of the VC. One disadvantage of the @context property, for non-JSON-LD users, is that contexts can be (and often are) nested, so several levels may need to be plumbed to discover the complete set of definitions.
-
What type of VC this is—As we saw earlier, this allows a verifier to very quickly check if it supports this type of VC and, if not, to quickly reject it without the need for further processing.
-
What schemas this VC uses—Different types of VCs contain different properties, and both the @context and credentialSchema properties say where the definitions of these new properties can be found on the internet. An example of the credentialSchema property was given in listing 7.1. It is perhaps easier for non-JSON-LD users to understand and use than the @context property.
The preferred way of extending VCs is by using the JSON-LD syntax and its built-in @context extension mechanisms since these already define how to extend objects in a way that maximizes interoperability. However, using JSON-LD is not strictly necessary as pure JSON can be used, providing the @context feature of JSON-LD is supported as a JSON property. Remember that the @context property provides short-form aliases for URIs so that they can be more easily referenced in the VC. It also says where the definitions of the core properties of VCs can be located on the internet.
Diagrams of the VC ecosystem, such as figure 7.1, often show a verifiable data registry where this extensibility data resides. In practice, there does not need to be a single place for this data; it may be implemented as one or more decentralized blockchains or as standard web pages accessible via HTTPS. However, it is important that the system serving as the verifiable data registry be designed to persist at least as long as the expiration of any VC issued that references it.
7.10 Zero-knowledge proofs
As explained in chapter 6, the term zero-knowledge proof (ZKP) refers to a class of cryptographic algorithms or protocols intended to allow for proof of the knowledge of a specific secret value, such as a password, without revealing the secret. Algorithms that fall under this category include ZK-Snarks, ZK-Starks, bullet proofs, and ring signatures. Many tutorials explain what such proofs are and how they work, but for our purposes, it is enough to understand that they can do one or more of the following:
-
Provide verification of claims in a VC without the issuer being involved or knowing who the verifier is (in other words, digital signatures)
-
Provide verification of claims in a VC while protecting the privacy of the holder
-
Allow for selective disclosure of a subset of the claims in a VC without revealing the contents, or even existence, of the other claims
-
Allow for derived claims to be presented to a verifier (e.g., over 18) rather than providing the full claim (e.g., date of birth)
These properties are extremely helpful when VCs are used in strong privacy-preserving contexts or ecosystems. In particular, the approach taken in the VC Data Model spec focuses on preserving the privacy of the holder. In the many cases where the holder is also the subject, this preserves the subject’s privacy.
In the VC Data Model spec, the use of ZKPs involves three stages:
-
One or more base VCs are created by issuers using any proof (signature) approach. Additionally, the credentialSchema property in each contains a DID that identifies that base credential and type indicating the ZKP system that will be used. One such system is the Camenisch-Lysyanskaya ZKP system (https://eprint.iacr.org/2001/019.pdf), also known as CL Signatures.
-
For each VC the holder wishes to present to a verifier, the holder creates a derived VC. In this derived VC, credentialSchema has the exact same contents as in the original base credential, which is how you know they are linked. However, the proof section contains a CL proof that enables the holder to prove knowledge of a signature from the issuer over the credential without revealing that signature. This means only the holder can prove the signature, yet the proof does not reveal who the holder is to anyone else who might intercept the credential. Additionally, this derived credential can support selective disclosure by presenting only a subset of the base VC’s claims.
-
The derived VCs are placed inside a VP issued by the holder to the verifier. The VP’s proof section contains a CL proof with the following properties: the verifier can prove knowledge of a proof that all of the derived credentials were issued to that specific holder without revealing the latter proof. This means only the verifier—and no one else—can verify this proof (the verifier cannot share it with anyone else), yet the VP’s proof still does not reveal who the holder is to anyone else who might intercept the VP.
Many of the details here are glossed over in the VC Data Model spec, largely because of the huge variability in ZKP systems. However, the data model and syntax of VCs and VPs should be sufficient to accommodate a variety of ZKP-based proof types. (For examples of ZKP-type implementations, see the Hyperledger Indy [https://wiki.hyperledger.org/display/indy] and Hyperledger Aries [https://wiki.hyperledger .org/display/aries] projects.)
7.11 Protocols and deployments
The VC Data Model 1.0 specification defines the format and contents of a VC and a VP that can be used to transfer a set of VCs from the issuer to the holder and transfer a set of VCs from the holder to a verifier. However, it does not define protocols for transferring and using VCs. That was deliberately put out of scope to keep the work of creating the 1.0 spec manageable. Obviously, these are needed before a VC identity ecosystem can become operational.
Communities of SSI implementers have been experimenting with different ways of transferring VCs. Several of these protocols are discussed in detail in chapter 5. In this section, we discuss some additional considerations. Earlier, we outlined the most likely steps involved in an operational VC ecosystem. Most of these steps still need to be standardized:
-
How does a verifier describe its policy (or requirements) for access to its resources and transfer this to the holder?
-
How does an issuer inform the holder which VCs it is capable of issuing?
The first demonstration of VCs was by Digital Bazaar in its Credential Handler API (CHAPI) for websites (https://w3c-ccg.github.io/credential-handler-api). (A video demo of this process is available at https://www.youtube.com/watch?v=bm3XBPB 4cFY) It is a common problem on the web that login pages for websites have a list of potential ways to log in: for example, using your Facebook account, Google account, LinkedIn account, etc. This has been referred to as the “NASCAR problem” because of the growing list of logos that websites need to display to accommodate all these identity providers. When using CHAPI, the web browser acts as a mediator for the user, presenting them with choices in a standardized way to simplify the user experience. Different websites can be VC storage/holders (wallets), VC issuers, VC verifiers, or any combination of these.
The process begins when a user visits a credential storage site to get a new wallet. The site uses CHAPI to set up handlers for both CredentialStoreEvents and CredentialRequestEvents. The browser agent saves the service address for this site and records that this site is a credential repository. The user then visits a credential-issuing site.
When the site calls the credential management store() method, the browser presents the user with the credential to be stored and the user’s list of wallets into which the credential can be stored. When the user selects a wallet, the browser sends a CredentialStoreEvent to the wallet provider’s service address, at which point the credential is sent from the issuer to the wallet, where it is stored (and a “hint” for the credential is saved by the browser).
Similarly, when the user visits a credential-requesting site (a verifier), and the site calls the credential management get() method with a requested type of credential, the browser presents the user with hints for the list of available credentials of the requested type. When the user selects the credential, the browser sends a CredentialRequestEvent to the wallet provider’s service address, at which point the wallet sends the credential to the requester. Note that wallet and credential options are only presented to the user via the browser agent and that credentials are directly transported between wallet and issuer/verifier.
One of the earliest VC ecosystems was defined in 2015 by co-author David Chadwick. Built in 2016, it was presented at the European Identity Conference in 2017 (https://www.kuppingercole.com/speakers/405). It was based on enhancements to the (at that time) new FIDO specifications. In this ecosystem, VCs are held on the user’s mobile phone and tied to the FIDO keys used for pairwise authentication with verifiers.
The system uses a hybrid model of centralized and decentralized identity models discussed in chapter 1. The holders, issuers, and verifiers are peers of the distributed model that communicate via connections established with FIDO keys. The blockchain component is replaced with the FIDO Alliances’ centralized schema and key management services. When the user contacts an issuer, the issuer says which identity attributes it can issue as VCs, and the user decides which ones they want. This provides the issuer with consent, an important requirement of GDPR.
Each verifier is assumed to provide a range of services, and each service has its own authorization policy: i.e., its VC requirements for access to the particular resource. After the user has browsed the verifier’s services and decided which one they want to access, the verifier sends its specific policy to the user’s device. The agent on the user’s device searches the VCs that are obtainable from the various issuers to decide whether the policy can be fulfilled. If it can, then VCs are requested from each issuer to be bound to the FIDO public key for the verifier. These are then packaged together into a VP and signed by the user (using the private key paired to the verifier).
In this way, the verifier receives a set of VCs, each bound to the same public key ID, which the user has proved ownership of by signing the VP. The system was tested with university students and a small sample of British National Health Service patients, who unanimously found it easy to use and much preferable to usernames and passwords.
There are already a number of other deployments of VCs. For example, the government of the Province of British Columbia, Canada, has developed the Verifiable Organizations Network to serve as a public holder of business credentials (https://vonx.io). OrgBookBC (https://orgbook.gov.bc.ca/en/home) contains a searchable registry of publicly available licenses and permits granted to businesses in the province. Although the digital credentials will eventually be given directly to the subject organizations, publishing the credentials to the OrgBook makes the same information publicly available (and cryptographically verifiable). This simplifies the process of identifying which businesses comply with relevant laws or, more critically, suggested but not mandated guidelines. It also serves as a convenient way for business owners, once they acquire a VC wallet, to obtain the relevant VCs for their business.
7.12 Security and privacy evaluation
The Security Considerations (https://www.w3.org/TR/vc-data-model/#security-con siderations) and Privacy Considerations (https://www.w3.org/TR/vc-data-model/#privacy-considerations) sections of the VC Data Model spec run tens of pages each. In this section, we summarize the major points made in those sections:
-
VCs are integrity protected end to end—from the issuer to the verifier through any intermediate storage wallet—because they have a proof property (or a JWT signature) inserted by the issuer that cryptographically provides tamper detection.
-
VCs should be confidentially protected during transfer by transferring them only via encrypted communications links such as TLS.
-
VCs have high availability if they are stored on the holder’s device since they do not require any communications with the issuer or any other third party to be transferred to the verifier.
-
VCs facilitate the security property of least privileges by allowing the verifier to only request those subject properties (or attributes) essential for providing its service.
-
VCs provide privacy protection through selective disclosure by the issuer issuing either a ZKP VC or a set of atomic VCs, which allow the holder to only disclose those attributes that the verifier needs and nothing more.
-
VCs provide privacy protection to subjects by identifying them via pseudonymous IDs rather than their names of other identities. If these IDs are pairwise between subjects and verifiers, then no globally unique correlating handles are created.
-
VCs support flexible role-based and attribute-based access controls because the verifier only needs to specify which roles or attributes are needed to access its services and not the identities of the users who can access its services.
Of course, the ultimate security and privacy of any operational system depend on the quality of the implementation and its correct use. If a holder provides their unique email address and telephone number to a verifier, then the use of pseudonymous IDs will not protect them from releasing globally unique correlating handles. Similarly, if the user stores their VCs on an unprotected device, which is stolen, the thief will be able to masquerade as the user.
7.13 Hurdles to adoption
Physical VCs, such as plastic cards and passports, are indispensable in today’s society. It is high time we moved these credentials into the electronic world so that we can carry them around on our mobile devices and have them with us all the time. But as we have seen, there are technical, security, and privacy hurdles that must be overcome before electronic plastic cards become ubiquitous. And of course, there is also the question of the business models needed to give issuers the incentive to adapt or adopt this new model.
As we explained in the first part of this chapter, today’s federated identity management infrastructures give issuers (IDPs) great power because they are at the center of the ecosystem. VCs turn this model on its head and place users at the center. So, issuers will need to see some financial benefit before they are willing to move. Many of the compelling benefits are discussed in chapter 4, and others are discussed in part 4 of the book.
As they say in the movies, VCs are the hero of the SSI show. They are the most visible icon of SSI infrastructure since they will sit directly in the digital wallets of individuals (and organizations) and be presented to verifiers digitally the same way we present physical credentials to verifiers today (such as to airport security agents when we want to board a plane).
But in the move from physical credentials made of paper and plastic (and even metal, for some of the latest premium credit cards) to digital credentials, every last bit matters—literally. Since all the security and privacy properties of VCs depend on cryptography, the data structures and rules for composing and verifying VCs must be locked down to the last detail. That’s what this chapter has walked through, from the supported syntaxes to the required and optional properties to the different signature mechanisms and extensibility options.
In the next chapter, we dive one level deeper: into the special new form of cryptographically verifiable identifiers designed explicitly to support VCs and now being standardized in its own W3C Working Group: decentralized identifiers (DIDs).
References
1. Mantovani, Maria Laura, Marco Malavolti, and Simona Venuti. 2016. EU AARC Project Deliverable DNA2.4: “Training Material Targeted at Identity Providers.” AARC. https://aarc-project.eu/wp-content/uploads/2016/07/AARC-DNA2.4.pdf.
2. Burr, William, et al. 2013. NIST Special Publication (SP) 800-63-2: “Electronic Authentication Guideline.” https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-63-2.pdf.
3. Grassi, Paul A., Michael E. Garcia, and James L. Fenton. 2017. NIST Special Publication (SP) 800-63-3: “Digital Identity Guidelines.” https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-63-3.pdf.