Claims, properties

A core concept is “claims”: statements made about various entities, referred to as “subjects”. Subjects may be a person (e.g., the person holding a university degree), an animal, an abstract concept, another credential, etc. Claims may also be on the enclosing credential itself, such as issuance date, validity periods, etc. (Such claims are also loosely referred to as “credential metadata”.)

Claims are expressed using “properties” referring to “values”. Values may be literals, but may also be other entities referred to, usually, by a [[URL]]. In that case, that entity may become the subject of another claim; these claims, together, form a graph of claims that represents a credential. (See for an example of such a graph represented graphically. For more complex examples, refer to the [[[vc-data-model]]] specification itself.)

The [[[vc-data-model]]] document specifies a number of standard properties. These include, for example, `credentialSubject`, `type`, `issuer`, or `validFrom`. Developers may define their own properties to express specific types of Credentials, like a driving license, a university degree, a marriage certificate, or a Digital Product Passport.

Core concepts

Credentials

A Credential is a set of one or more claims made by the same entity. Credentials might also include an identifier and metadata to describe properties of the credential, such as a reference to the issuer, the validity date, a representative image, the revocation mechanism, and so on. A [=verifiable credential=] is a set of claims and metadata (i.e., a credential) that also includes verification mechanisms that cryptographically prove who issued it, ensures that the data has not been tampered with, etc.

For a more detailed description of abstract [=verifiable credentials=], with examples, see the relevant section in the data model specification.

Presentations

Enhancing privacy is a key design feature of [=Verifiable Credentials=]. Therefore, it is important for entities using this technology to be able to express only the portions of their persona that are appropriate for a given situation. The expression of a subset of one's persona is called a [=Verifiable Presentation=]. Examples of different personas include a person's professional persona, their online gaming persona, their family persona, or an incognito persona.

A Verifiable Presentation is created by a holder, can express data stemming from multiple [=verifiable credentials=], and can contain additional metadata in forms of additional claims. They are used to present claims to a verifier. It is also possible to present [=verifiable credential=] directly.

A Verifiable Presentation is usually short-lived, it is not meant to be stored for a longer period.

For a more detailed description of abstract Verifiable Presentations, with examples, see the relevant section in the data model specification.

JSON serialization

In the [[vc-data-model]] specification, as well as in the other documents, [=verifiable credentials=] and Presentations are mostly expressed in JSON [[rfc7519]], more specifically [[[json-ld11]]] [[json-ld11]]. In this serialization, properties of claims are represented as JSON names, and values as JSON literals or objects. Subjects of claims are either explicitly identified by an `id` property, or implicitly by appearing as an object of another claim. JSON-LD is useful because it enables the expression of the graph-based data model on which verifiable credentials are based, it has a machine-readable semantics, and is also useful when extending the data model. (See the relevant section in the [[vc-data-model]] specification.)

Standard properties defined by the [[vc-data-model]] form a distinct set of JSON names, referred to as a (standard) vocabulary. An important characteristic of [=verifiable credentials=] in JSON-LD is that it favors a decentralized and permissionless approach to extend to a new application area through application-specific vocabularies, distributed on the Web. Anyone can “publish” such a vocabulary, following some rules described in the extensibility section of the specification.

The following JSON-LD code is an example for a simple credential. It states that the person named “Pat”, identified by https://www.example.org/persons/pat, is an alumnus of the Example University (identified by did:example:c276e12ec21ebfeb1f712ebc6f1). The credential is valid from the 1st of January 2010, and is issued by an entity identified by did:example:university.example:CSSchool. Most of the properties in the credential are from the standard [=verifiable credentials=] vocabulary (identified by https://www.w3.org/ns/credentials/v2), but some terms (like `alumnusOf` or `AlumnusCredential`) are added by the application-specific vocabulary referred to by https://www.w3.org/ns/credentials/examples/v2.

shows the same credential, but represented as a graph of claims, as described in .

The Alumnus Credential in is used as a starting point throughout this document to show how to apply additional features defined by the various specifications.

The credential in , issued by Example University, is stored by a holder (who may be a person, a digital wallet, or any other entity). On request, the holder may “present” the credential to a verifier, encapsulated in a Presentation. This is how the credential looks like in the JSON-LD serialization:

Note that the holder could have presented several credentials within the same presentation, or create a new credential by either combining it with others or removing some claims as irrelevant for the specific context.

Extensions

This section describes additional (and optional) features that an issuer may choose to use to extend the core credential.

Confidence methods

The [[[vc-confidence-method]]] [[vc-confidence-method]] specification defines a mechanism that issuers can use to increase the confidence of verifiers in the legitimacy of the presentation of a given credential. An analogy is checking a driving license: when the police officer (the “verifier”) gets hold of the license, they would first compare the photograph on the physical license to compare it with the face of the driver. This raises the confidence of the police officer that the driver is indeed the “subject” of the license (the “credential”).

The specification adds the concept of a Confidence Method to the core model. It defines mechanisms that can be used by the verifier to increase its confidence that a subject of the VC is also the subject of another interaction. For example, the issuer might provide a public key of the subject; the verifier could use a proof-of-use protocol to establish that the current user indeed holds the corresponding secret key by signing cryptographic challenges (see ). A more complex verification method might be based on biometrics, like embedding raw biometric data (photograph, audio recordings, fingerprint data), or biometric vectors, i.e., compact mathematical representations produced by a specific model that can be used for matching. Some of these methods are defined in the specification, but specific communities may extend the model with other, proprietary approaches.

The list of methods in the specification is still to be finalized.

The diagram below shows the confidence setting steps for our simple university alumnus case.

Checking with JSON schemas

A significant part of the integrity of a [=verifiable credential=] comes from the ability to structure its contents so that all three parties — issuer, holder, verifier — may have a consistent mechanism of trust in interpreting the data that they are provided with. One way of doing that is to use [[json-schema]] to check the structural validity of the credential. The [[[vc-json-schema]]] [[vc-json-schema]] specification adds standard properties to express the association of a credential with a JSON Schema.

Consider the following example:

When dereferenced, the URL `https://university.example/Credential-schema.json` should return a JSON Schema, for example:

Using this JSON Schema, a verifier can check whether the credential is structurally valid or not.

For security reasons one may want to go a step further: check/verify the JSON Schema itself to see if, for example, it has been tampered with. This can be done by referring to the JSON Schema indirectly through a separate [=verifiable credential=]. The reference to such a [=verifiable credential=] looks very much like except for the value of the `type`:

In this case, when dereferenced, the URL `https://university.example/Credential-schema-credential` should return a [=verifiable credential=], whose `credentialSubject` property refers to the required JSON Schema (i.e., https://university.example/Credential-schema.json). See the example in the [[[vc-json-schema]]] specification for an example and for further details.

The diagram below shows the JSON Schema related steps for our simple university alumnus case.

Example: the Alumnus Credential

For reference, represents the full Alumnus Credential, as constructed so far.

Enveloping proofs

Enveloping proofs of credentials, defined by this Working Group, are based on JSON Object Signing and Encryption (JOSE), CBOR Object Signing and Encryption (COSE) [[rfc9052]], or Selective Disclosure for JWTs [[rfc9901]]. These are all IETF specifications, or groups of specifications (like JOSE, that refers to JWT [[rfc7519]], JWS [[rfc7515]], or JWK [[rfc7517]]). The [[[vc-jose-cose]]] [[vc-jose-cose]] Recommendation defines a “bridge” between these and the [[[vc-data-model]]], specifying the suitable header claims, media types, etc.

In the case of JOSE, the credential is the “payload” (to use the IETF terminology). This is preceded by a suitable header whose details are specified by the relevant section of the [[vc-jose-cose]] specification. These are encoded, concatenated, and signed, to be transferred in a compact form by one entity to another (e.g., sent by the holder to the verifier). All the intricate details on signatures, encryption keys, etc., are defined by the IETF specifications; see for a specific case.

The usage of COSE [[rfc9052]] is similar to JOSE, except that all structures are represented in CBOR [[rfc8949]]. From the credentials point of view, however, the structure is similar insofar as the credential (or the Presentation) is again the payload for COSE. The use of CBOR means that the final representation of the [=verifiable credential=] (or Presentation) can have a reduced footprint which can be, for example, shown in a QR Code.

The [[rfc9901]] specification is a variant of JOSE, which allows for the selective disclosure of individual claims. Claims can be selectively hidden or revealed to the verifier, but all claims are cryptographically protected against modification. This approach is obviously more complicated than the JOSE case but, from the credentials point of view, the structure is again similar. The original credential is the payload for SD-JWT; and it is the holder’s responsibility to use SD-JWT when presenting the credential to a verifier using selective disclosure.

Embedded proofs

Creation of Proofs in Data Integrity

The operation of Data Integrity is conceptually simple. To create a cryptographic proof, the following steps are performed: 1) Transformation, 2) Hashing, and 3) Proof Generation.

1. Transformation is a process described by a transformation algorithm that takes input data and prepares it for the hashing process. In the case of data serialized in JSON this transformation includes the removal of all the artifacts that do not influence the semantics of the data, such as spaces, new lines, the order of JSON names, etc. (a step usually referred to as canonicalization). In some cases the transformation may be more involved.
2. Hashing is a process described by a hashing algorithm that calculates an numerical identifier for the transformed data using a cryptographic hash function. Typically, the size of the resulting hash is smaller than the data, and it is suitable for complex cryptographic functions like digital signatures.
3. Proof Generation is a process described by a proof method that calculates a value that protects the integrity of the input data from modification or otherwise proves a certain desired threshold of trust. A typical example is the application of a cryptographic signature using asymmetric keys, generating the signature of the data using a private key.

Verification of a proof involves repeating the same transformation and hashing steps on the verifier's side and, depending on the proof method, validating the newly calculated hash value with the proof associated with the data. In the case of a digital signature, this means verifying, using the cryptographic algorithms associated with the asymmetric keys, that the proof value indeed signs the newly calculated hash.

Barcodes

[=verifiable credentials=] can be expressed through different media, such as simple text, a PDF file, or an image. An important presentation format is the usage optical barcodes, like QR codes, that often appear on identity cards or driving licenses. A simple approach is to convert the JSON serialization of the credential into CBOR [[rfc8949]], and then generate a QR Codes from that CBOR representation. This can be done by a number of off-the-shelf tools.

However,this approach has a major drawback for even moderately sized [=verifiable credentials=]: the result of the direct CBOR conversion may create a QR Code that is too large for the available space, which has a severe size limitation. To solve this problem, the [[[vc-barcodes]]] [[vc-barcodes]] specification takes a slightly different approach. Instead of using a generic CBOR conversion, it relies on the CBOR-LD [[cbor-ld]] representation of the credential. CBOR-LD is a CBOR encoding tailored for JSON-LD: it includes the possibility for a semantic compression of the data, targeted at a particular application vocabulary. It is possible to achieve compression ratios in excess of 60% better than general compression schemes, which makes it possible to represent [=verifiable credentials=] for, say, driving licenses, birth certificate,s and conformity certificates.

Any credential can be represented in a barcode yielding, for example, a birth cerfiticate like on . However, in practical applications, the situation may be a bit more complex. Consider the back side of a fictious employment authorization card on :

The card includes a machine-readable zone (MRZ) containing information designed to be read through optical character recognition. The goal is to generate a [=verifiable credential=] securing that MRZ data; this requires a special Credential whose subject cannot be simply expressed in JSON:

The `MachineReadableZone` type means to take the data directly from the MRZ, without change.

Note the usage of the `ecdsa-xi-2023` cryptosuite (listed in ): it allows the addition of additional, external data to the canonicalized JSON-LD data before signature. This is how the proof for the MRZ data is combined with that of the full credential. The result is a QR Code appearing on the front of the employment card on :

Bitstring status list

It is often useful for an issuer of [=verifiable credentials=] to link to a location where a verifier can check whether a credential has been suspended or revoked. This additional resource is referred to as a “status list”.

The simplest approach for a status list, where there is a one-to-one mapping between a [=verifiable credential=] and a URL where the status is published, raises privacy as well as performance issues. In order to meet privacy expectations, it is useful to bundle the status of large sets of credentials into a single list to help with group privacy. However, doing so can place an impossible burden on both the server and client if the status information is as much as a few hundred bytes in size per credential across a population of hundreds of millions of holders. The [[[vc-bitstring-status-list]]] [[vc-bitstring-status-list]] specification defines a highly compressible, highly space-efficient bitstring-based status list mechanism.

Conceptually, a bitstring status list is a sequence of bits. When a single bit specifies a status, such as “revoked” or “suspended”, then that status is expected to be true when the bit is set and false when unset. One of the benefits of using a bitstring is that it is a highly compressible data format since, in the average case, large numbers of credentials will remain unrevoked. If compressed using run-length compression techniques such as GZIP [[rfc1952]] the result is a significantly smaller set of data: for a status list of size is 131,072 entries, equivalent to 16 KB of single bit values, GZIP compresses the bitstring down to a few hundred bytes when only a handful of verifiable credentials are revoked.

The specification introduces the `credentialStatus` property, as well as some additional sub-properties, that should be used to add this additional information to a [=verifiable credential=].

shows the example from , combined with the information on the credential status: the purpose of that status information, the reference to the bitstring, and the index into this bitstring for the enclosing credential:

The `statusListCredential` property, when dereferenced, should return a separate credential for the status list. The status list itself is the subject of that credential (which, of course, can also be signed). An example is:

The core property in this case is `encodedList`, which is a base64url encoded version of the GZIP compressed bitstring status list.

Forgery defense

The publication of the [[[vc-forgery-defense]]] [[vc-forgery-defense]] is complementary to quantum-resistant cryptosuites, and is motivated by the same threat. While cryptosuites let issuers secure new proofs with post-quantum signatures, this specification lets an issuer establish post-quantum-backed authenticity for credentials that are signed with conventional quantum-vulnerable algorithms. That may be the case for credentials that cannot reasonably be re-issued or where the significant size of some quantum-resistant signatures becomes an obstacle. (A good example may be the employment authorizations issued by a state or a country, as described in .)

The forgery defense mechanism defined by this specification is achieved by publishing a witness list that is itself the subject of a separate [=verifiable credential=]. A “witness” in that list is, essentially, the most significant bits of a hash value generated from the credential itself, combined with a random seed. The list combines a large number of such witnesses in one, encoded value, and the Credential is signed by, preferably, a quantum resistant scheme:

For older credentials, the verifier may locate the witness list in some out-of-band manner; e.g., a university may publish the location for the witnesses of all the credentials it has issued. New [=verifiable credentials=] may include information about the relevant witness, added to the credential status alongside status lists references:

Recognized entities

The verifiable credential ecosystem relies on the ability of verifiers to determine whether a particular issuer is recognized to issue a certain type of verifiable credential. Similarly, holders should have the ability to decide whether a particular verifier is recognized to verify a credential. Historically, these determinations have often been made through out-of-band processes, bilateral agreements, or proprietary registries that are difficult to discover, query, or reason about in an automated way. As verifiable credentials are increasingly deployed, the need for a standardized, interoperable mechanism to express and communicate recognition of entities that perform known actions becomes critical. This is the problem area addressed by the [[[vc-recognized-entities]]] [[vc-recognized-entities]] specification.

Rather than mandating a central registry for issuers, this specification choses a decentralized approach. Any entity — a local governmental body, a standard institution, a university office, or a local community — can issue a special [=verifiable credential=] that lists all potential issuers that it “recognizes” to act either as an issuer or a verifier (e.g., all schools of the university). The design may lead to a “Web of Recognition”: the same entity can be recognized as an issuer both by the university office as well as the local governmental body, or the university office itself might be recognized by another institution, like the local Ministry of Higher Education. The specification also supports interoperability with existing trust infrastructure, such as X.509 [[rfc5280]] certificate authority lists and ETSI Trust Service Lists [[etsi-trust]].

shows the skeleton of a [=verifiable credential=], issued by the administration of Example University, which attests that the administrations of the School of Computer Science, respectively of Philosophy, can issue credentials. (Note that the Alumnus Credential in our example was issued by the Schoold of Computer Science.)

We can also extend the Alumnus Credential with the possibility for the verifier to trace back the Web of Recognition to a possible “root”. In the data about the issuer contains the recognizedIn claim, the refers back to the credential in .

The diagram below shows the “flow” of trust for our simple university alumnus case. See the Appendix of the [[[vc-recognized-entities]]] specification for more elaborate examples.

It is interesting to note that the [[[vc-recognized-entities]]] specification is also a perfect example for how easily application areas may define bespoke [=verifiable credential=] types. It simply boils down to the syntactic and semantic definition of new terms (e.g., `RecognizedEntity` or `recognizedTo`) to extend the core [=verifiable credential=] Data Model. Once those are defined and documented in the form of a vocabulary for JSON-LD, including an application-dependent context file (see, for example, ), the terms can be used in a [=verifiable credential=] without further ado. Anyone can “publish” such a vocabulary, following some rules described in the extensibility section of the specification, no need for a central registration of the new terms.

An API for lifecycle management

The [[[vcalm]]] [[vcalm]] specification provides a set of HTTP Application Programming Interfaces (HTTP APIs) and protocols for issuing, verifying, presenting, and managing [=verifiable credentials=]. It defines APIs among the entities corresponding to the main “roles” in the [=verifiable credential=] model (i.e., issuer, holder, and verifier, see also ). The specification provides a reference model for components within these roles, including the corresponding APIs among those components; see below for the overall architecture.

The boundaries and interfaces among the components are defined to ensure interoperability and substitutability across the [=verifiable credential=] conformant ecosystem. This approach helps to avoid vendor lock-in and leads to a pool of independent implementations of interoperating components. Any given implementation of a specific role (i.e., issuer or holder) may choose to aggregate any or all of the components of the model into a single functional application. The individual components may be of a different nature (running on a browser or on a server, implemented in different programming languages, etc.), each executing just part of the overall functionality.