Credentials are a part of our daily lives; driver's licenses are used to assert that we are capable of operating a motor vehicle, university degrees can be used to assert our level of education, and government-issued passports enable holders to travel between countries. This specification provides a mechanism to express these sorts of credentials on the Web in a way that is cryptographically secure, privacy respecting, and machine verifiable.

Comments regarding this document are welcome. Please file issues directly on GitHub, or send them to public-vc-comments@w3.org (subscribe, archives).

There remain a list of terminology-related editorial issues that need to be processed in this document.

There remain a list of editorial issues that need to be processed in this document.

Introduction

This section is non-normative.

Credentials are a part of our daily lives; driver's licenses are used to assert that we are capable of operating a motor vehicle, university degrees can be used to assert our level of education, and government-issued passports enable us to travel between countries. These credentials provide benefits to us when used in the physical world, but their use on the Web continues to be elusive.

It is currently difficult to express banking account information, education qualifications, healthcare data, and other sorts of machine-readable personal information that has been verified by a 3rd party on the Web and this makes it difficult to receive the same benefits from the Web that physical credentials provide us in the physical world.

This specification provides a standard way to express credentials on the Web in a way that is cryptographically secure, privacy-respecting, and machine-verifiable.

For those that are unfamiliar with the concepts related to verifiable credentials, the following sections provide an overview of:

  1. the components that constitute a verifiable credential,
  2. the components that constitutes a verifiable presentation,
  3. an ecosystem where verifiable credentials and verifiable presentations are expected to be useful, and
  4. the use cases and requirements that informed this specification.

What is a Verifiable Credential?

In the physical world, a credential may consist of:

A verifiable credential can represent all of the same information that a physical credential represents. The addition of technologies such as digital signatures makes verifiable credentials more tamper-evident and therefore more trustworthy than their physical counterparts. Holders can generate presentations and share them with verifiers to prove they possess verifiable credentials with certain characteristics. Both credentials and presentations can be rapidly transmitted, making them more convenient than their physical counterparts when establishing trust at a distance.

Ecosystem Overview

This section is non-normative.

This section outlines a basic set of roles and an ecosystem where verifiable credentials are expected to be useful. In this section, we distinguish the essential roles of core actors and the relationships between them; how do they interact? A role is an abstraction that might be implemented in many different ways. The separation of roles suggests likely interfaces and/or protocols for standardization. The following roles are introduced in this specification:

holder
A role an entity may perform by possessing one or more verifiable credentials and generating presentations from them. Examples of holders include students, employees, and customers.
issuer
A role an entity may perform by creating a verifiable credential, associating it with a particular subject, and transmitting it to a holder. Examples of issuers include corporations, non-profits, trade associations, governments, and individuals.
verifier
A role an entity may perform by requesting and receiving a verifiable presentation that proves the holder possesses the required verifiable credentials with certain characteristics. Examples of verifiers include employers, security personnel, and websites.
identifier registry
A role a system may perform by mediating the creation and verification of issuer identifiers, keys and other relevant data required to use verifiable credentials. Some configurations may require correlatable identifiers for subjects. Examples of such data repositories include trusted databases, decentralized databases, government ID databases, and distributed ledgers.
The roles and information flows that form the basis for this specification.

The ecosystem above is provided as an example to the reader in order to ground the rest of the concepts in this specification. Other ecosystems exist, such as protected environments or proprietary systems, where verifiable credentials also provide benefit.

The VCWG is actively discussing the number of roles and terminology used in this specification. The group expects terminology and role identification to be an ongoing discussion and will be influenced by public feedback on the specification. At present, the following incomplete list of roles and terminology have been considered: Subject, Issuer, Authority, Author, Signatory, Holder, Presenter, Asserter, Claimant, Sharer, Subject's Agent, Prover, Mediator, Inspector, Evaluator, Verifier, Consumer, and Relying Party. Some of these are aliases for the same concept, others are possibly new roles in the ecosystem. Reviewers should be aware that the terminology used in this document is not necessarily final and the group is actively soliciting feedback on the roles and terminology used in this specification.

The group is currently discussing how the ecosystem overview could be improved with the intent to defer future improvements as the current section seems to be working well so far.

The group is currently discussing how to bootstrap simple Web of Trust credentials in this ecosystem.

Use Cases and Requirements

This section is non-normative.

The Verifiable Credentials Use Cases [[VC-USECASES]] document outlines a number of key topics that readers may find useful, including:

As a result of documenting and analyzing the use cases document, a number of desirable ecosystem characteristics have been identified for this specification, namely:

There are other requirements listed in the Verifiable Credentials Use Cases document that may or may not be aligned with the requirements listed above. The VCWG will be ensuring alignment of the list of requirements from both documents over time and will most likely move the list of requirements to a single document.

Terminology

This section is non-normative.

Core Data Model

This section is non-normative.

The following sections outline core data model concepts, such as claims, credentials, and presentations, that form the foundation of this specification.

Claims

This section is non-normative.

A claim is statement about a subject. A subject is an entity about which claims may be made. Claims are expressed using subject-property-value relationships.

The basic structure of a claim.

The data model for claims described above is powerful and can be used to express a large variety of statements. For example, whether or not someone is over the age of 21 may be expressed as follows:

An example of a basic claim that expresses that Pat is over the age of 21.

If a presentation supports derived predicates, a claim about birthdate in a credential can become the basis of proof that at an arbitrary point in time, the age of a subject did or will fall within an arbitrary interval.

These claims may be merged together to express a graph of information about a particular subject. The example below extends the data model above by adding claims that state that Pat knows Sam and that Sam is employed as a professor.

Multiple claims may be combined to express a more complex graph.

At this point, the concept of a claim has been introduced. To enable one to trust the claims, more information must be added to the graph of information.

Credentials

This section is non-normative.

A credential is set of one or more claims made by the same entity. It may include an identifier as well as metadata that describes properties of the credential itself such as: the issuer, the expiry time, a representative image, a public key to use for the purposes of verification, the revocation mechanism to use etc. This metadata may be signed by the issuer. A verifiable credential is a set of claims and meta data that are tamper-evident and that cryptographically prove who issued it.

The basic components of a verifiable credential.

Examples of verifiable credentials include digital employee identification cards, digital birth certificates, digital educational certificates, etc.

It is possible to have a credential, such as a marriage certificate, that contains multiple claims about different subjects that are not required to be related.

The group is currently discussing whether or not they support all the types of claims that can be made.

Presentations

This section is non-normative.

As this specification takes a privacy-first approach, it is important that the entities that use this technology are able to express only the portions of their persona that are appropriate for the situation. The expression of a subset of one's persona is called a verifiable presentation.

A verifiable presentation expresses data from one or more verifiable credentials, and is packaged in such a way that the authorship of the data is verifiable. If credentials are directly presented, they become a presentation. Data formats derived from credentials that are cryptographically verifiable but that do not, of themselves, contain credentials, may also be presentations.

The data in a presentation are often about the same subject that have been issued by multiple issuers. The aggregation of this information typically expresses an aspect of a person, organization, or entity.

The basic components of a verifiable presentation.

Examples of different presentations include a person's professional persona, online gaming persona, or home-life persona.

It is possible to have a presentation, such as a business persona, that draws upon multiple credentials about different subjects that are often, but not required to be, related.

Trust Model

This section is non-normative.

The Verifiable Credentials trust model is as follows:

  1. The verifier trusts the issuer to issue the credential that it receives. In order to establish this trust, a credential MUST either 1) include a proof that establishes that the issuer generated the credential (it is a verifiable credential), or 2) have been transmitted in a way that clearly establishes that the issuer generated the credential and that the credential has not been tampered with in transit or storage. This trust could be weakened depending upon the risk assessment of the verifier.
  2. All entities trust the identifier registry to be incorruptible and to be a correct record of which identifiers belong to which entities.
  3. The subject trusts the issuer to issue true (i.e., not false) credentials about the subject, and to revoke them quickly when appropriate.
  4. The holder trusts the repository to store the credentials securely, to not release them to anyone other than the holder, and to not corrupt or lose them whilst they are in its care.

This trust model differentiates itself from other trust models by ensuring that:

By decoupling the trust between the identity provider and the relying party, a more flexible and dynamic trust model is created such that market competition and customer choice is increased.

Basic Concepts

This section outlines some of the basic concepts introduced in this specification and lays the groundwork for the more advanced concepts toward the end of the document.

Types

Software systems that process the objects specified in this document use type information to make determinations about whether or not the provided credential or presentation is appropriate. Type information MUST be expressed via the type property:

type
The value of this property MUST be or map to one or more URIs. If more than one URI is provided, the URIs MUST be interpreted as an unordered set. Note that syntactic conveniences, such as JSON-LD terms, SHOULD be used to ease developer usage. It is RECOMMENDED that dereferencing the URI results in a document containing machine-readable information about the type.
{
  "@context": "https://w3id.org/credentials/v1",
  "id": "http://dmv.example.gov/credentials/3732",
  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "proof": { ... }
}
        

With respect to this specification, the following types MUST be specified on the following objects:

Concept Type
A credential object "type": ["VerifiableCredential"] and a more specific credential type (e.g., ProofOfAgeCredential)
A presentation object "type": ["VerifiablePresentation"] and optionally a more specific presentation type (e.g., CredentialManagerPresentation).
credentialStatus object A valid credential status type (e.g., CredentialStatusList2017)
A termsOfUse object A valid terms of use type (e.g., OdrlPolicy2017)
An evidence object A valid evidence type (e.g., DocumentVerification2018)

All credentials, presentations, and encapsulated objects MUST specify or be associated with additional, more narrow types (e.g., ProofOfAgeCredential) such that software systems can use the additional information to more easily process the data.

When processing encapsulated objects in this specification, (e.g., objects associated with the claim property or deeply nested therein), a software system SHOULD use type information specified in encapsulating objects higher in the hierarchy. For the avoidance of doubt, an encapsulating object such as credential, SHOULD convey the types of associated objects so that the verifier can quickly determine the contents of the associated object based on the type of the encapsulating object. To provide a concrete example, a credential with the additional type of ProofOfAgeCredential would signal to the verifier that the object associated with the claim property will contain the identifier for the subject in the id property and the age assertion in the ageOver property. This enables implementers to rely on values associated with the type property for verification purposes. The expectation of types and their associated properties SHOULD be documented in at least a human-readable specification and, preferably, in an additional machine-readable representation.

The type system for the Verifiable Credentials Data Model is the same as the one for [[JSON-LD]] and is detailed in Section 5.4: Specifying the Type and Section 8: JSON-LD Grammar. When using a JSON-LD Context (see Section ), this specification aliases the @type keyword to type in order to make the JSON-LD documents more idiomatic. While application developers and document authors do not need to understand the specifics of JSON-LD's type system, implementers of this specification that want to support extensibility in an interoperable fashion do.

Issuer

Issuer information may be expressed via the following properties:

issuer
The value of this property MUST be a URI. It is RECOMMENDED that dereferencing the URI results in a document containing machine-readable information about the issuer that may be used to verify the information expressed in the credential.
issuanceDate
The value of this property MUST be a string value of an [[!ISO8601]] combined date and time string and represents the date and time the credential was issued. Note that this date represents the earliest date when the information associated with the claim property became valid.
{
  "@context": "https://w3id.org/credentials/v1",
  "id": "http://dmv.example.gov/credentials/3732",
  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "proof": { ... }
}
        

Proofs (e.g., Signatures)

In order for a credential or presentation to be made verifiable, the following property MUST be present:

proof
The method used for a mathematical proof will vary by representation language and the technology used. For example, if digital signatures are used for the proof mechanism, this property is expected to have a value that is a set of name-value pairs including at least a signature, a reference to the signing entity, and a representation of the signing date.
{
  "@context": "https://w3id.org/credentials/v1",
  "id": "http://example.gov/credentials/3732",
  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov",
  "issuanceDate": "2010-01-01",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "proof": {
    "type": "RsaSignature2018",
    "created": "2017-06-18T21:19:10Z",
    "creator": "https://example.com/jdoe/keys/1",
    "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
    "signatureValue": "BavEll0/I1zpYw8XNi1bgVg/sCneO4Jugez8RwDg/+
      MCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuFibcC1wps
      PRdW+gGsutPTLzvueMWmFhwYmfIFpbBu95t501+rSLHIEuujM/+PXr9Cky6Ed
      +W3JT24="
  }
}
        

The group is currently discussing various alignments with the JOSE stack, specifically JWS and JWK.

Expiration

Expiration information for the credential MAY be provided by adding the following property:

expirationDate
The value of this property MUST be a string value of an [[!ISO8601]] combined date and time string and represents the date and time the credential will cease to be valid.
{
  "@context": "https://w3id.org/credentials/v1",
  "id": "http://dmv.example.gov/credentials/3732",
  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "expirationDate": "2020-01-01T19:73:24Z",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "proof": { ... }
}
        

The group is currently discussing expiration and caching.

The group is currently discussing how to automatically renew credentials.

The group is currently discussing how verifiable credentials may be automatically updated.

Status

Information about the current status of a verifiable credential, such as suspension or revocation, may be provided by adding the credentialStatus property. This property comprises the type of credential status information that is being provided (sometimes referred to as the credential status scheme), plus the id of the status type instance. The precise contents of the credential status information is determined by the specific credentialStatus type definition, and will vary depending upon a variety of factors, such as whether it is simple to implement or privacy-enhancing.

credentialStatus
The value of this property MUST be a credential status scheme that provides enough information to determine the current status of the credential (e.g., suspended, revoked, etc.).
{
  "@context": "https://w3id.org/credentials/v1",
  "id": "http://dmv.example.gov/credentials/3732",
  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "credentialStatus": {
    "id": "https://dmv.example.gov/status/24,
    "type": "CredentialStatusList2017"
  },
  "proof": { ... }
}
        

Defining the data model, formats, and protocols for status schemes are out of scope for this specification. A status scheme registry [[VC-STATUS-REGISTRY]] exists for implementers that would like to implement credential status checking.

Presentations

Credentials MAY be used to construct a verifiable presentation. A verifiable presentation may be of a verifiable credential itself, or of data derived from verifiable credentials in a format that is cryptographically verifiable.

In the example below, we show a verifiable presentation that embeds verifiable credentials:

{
  "@context": "https://w3id.org/credentials/v1",
  "id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
  "type": ["VerifiablePresentation"],
  "verifiableCredential": [{ ... }],
  "proof": [{ ... }]
}
        

The group is currently discussing whether the "id" field is appropriately defined for Presentations.

The group is currently discussing how the data model expresses when the subject is not the holder of the credential/presentation.

The group is currently discussing holders, subjects, and identifier control.

The contents of the verifiableCredential property shown above are verifiable credentials as described by this specification. The contents of the proof property are proofs as described by the Linked Data Proofs [[LD-PROOFS]] specification. The id property is optional and MAY be used to provide a unique identifier for the presentation. The value associated with the id property MUST be a URI.

Some zero-knowledge cryptography schemes may enable holders to indirectly prove that they hold a credential without revealing the credential itself. In these schemes, the original attribute, such as a date of birth, may be translated into another value, such as "over the age of 15", that is cryptographically asserted such that a verifier can trust the value if they trust the issuer.

We are currently working on an example of a ZKP-style verifiable presentation that contains derived data instead of directly embedded verifiable credentials.

Advanced Concepts

Extensibility

One of the goals of the Verifiable Credentials Data Model is to enable permissionless innovation. This requires that the data model is extensible in a number of different ways:

This approach to data modelling is often called an "open world assumption," meaning that any entity can say anything about any other entity. This approach often feels in conflict with building simple and predictable software systems. Balancing extensibility with program correctness is always more challenging with an open world assumption than it is with closed software systems.

The rest of this section describes how both extensibility and program correctness are achieved through a series of examples.

The group is currently discussing how a travel use case could be covered as an extension.

Let us assume that we start with the following verifiable credential:

{
  "@context": "https://w3id.org/credentials/v1",
  "id": "http://example.com/credentials/4643",
  "type": ["VerifiableCredential"],
  "issuer": "https://example.com/issuers/14",
  "issuanceDate": "2018-02-24T05:28:04Z",
  "claim": {
    "id": "did:example:abcdef1234567",
    "name": "Jane Doe"
  },
  "proof": { ... }
}
        

The credential above simply states that the entity associated with did:example:abcdef1234567 has a name with a value of Jane Doe. Let's assume that a developer wanted to extend the verifiable credential to store two additional pieces of information: an internal corporate reference number, and Jane's favorite food.

The first thing that a developer would do is create a JSON-LD Context containing two new terms:

{
  "@context": {
    "referenceNumber": "https://example.com/vocab#referenceNumber",
    "favoriteFood": "https://example.com/vocab#favoriteFood"
  }
}
        

Now that the JSON-LD Context has been created, the developer must publish it somewhere that is accessible to verifiers that will be processing the verifiable credential. For this example, let us assume that the JSON-LD Context above is published at the following URL: https://example.com/contexts/mycontext.jsonld. At this point, extending the first example in this section is a simple matter of including the context above and adding the new properties to the verifiable credential.

{
  "@context": [
    "https://w3id.org/credentials/v1",
    "https://example.com/contexts/mycontext.jsonld"
  ],
  "id": "http://example.com/credentials/4643",
  "type": ["VerifiableCredential"],
  "issuer": "https://example.com/issuers/14",
  "issuanceDate": "2018-02-24T05:28:04Z",
  "referenceNumber": 83294847,
  "claim": {
    "id": "did:example:abcdef1234567",
    "name": "Jane Doe",
    "favoriteFood": "Papaya"
  },
  "proof": { ... }
}
        

The examples so far have shown that it is easy to extend the Verifiable Credentials Data Model in a permissionless and decentralized way. The mechanism shown also ensures that verifiable credentials that were created in this way provide a mechanism to prevent namespace conflicts and semantic ambiguity.

An extensibility model that is this dynamic does increase implementation burden. Software written for such a system will have to determine if accepting verifiable credentials with extensions is acceptable based on the risk profile of the application. Some applications may choose to only accept certain extensions while highly secure environments may require that no extensions are allowed. These decisions are up to the developers of these applications and are specifically not the domain of this specification. Applications that do not understand the semantic meaning of all properties while processing a verifiable credential or a verifiable presentation MUST produce an error.

Developers are urged to ensure that extension JSON-LD Contexts are highly available. Implementations that cannot fetch a context will produce an error. Strategies for ensuring that extension JSON-LD Contexts are always available include using content-addressed URLs for contexts, bundling context documents with implementations, or enabling aggressive caching of contexts.

Semantic Interoperability

This specification endeavors to enable both the JSON and JSON-LD syntaxes to be semantically compatible with one another without the JSON implementations needing to process the documents as JSON-LD. In order to achieve this, the specification creates the following additional restrictions on both syntaxes:

  • JSON-based processors MUST process the @context property, ensuring the expected values exist in the expected order for the type of credential that they are processing. The expected order MUST be defined by at least a human-readable extension specification and, preferably, a machine-readable specification.
  • In addition to the rule above, JSON-LD-based processors MUST produce an error when a JSON-LD Context redefines any term in the active context.

To avoid the possibility of accidentally overriding terms, developers are urged to scope their extensions. For example, the following extension scopes the new favoriteFood term so that it may only be used within the claim property:

{
  "@context": {
    "referenceNumber": "https://example.com/vocab#referenceNumber",
    "claim": {
      "@id": "https://w3id.org/credentials#claim",
      "@context": {
        "favoriteFood": "https://example.com/vocab#favoriteFood"
      }
    }
  }
}
          

Terms of Use

Terms of use can be utilized by an issuer, a subject, or a holder to constrain the use of information expressed by the Verifiable Credentials Data Model. The issuer places their terms of use inside the credential before it is converted into a verifiable credential. The holder places holder terms of use inside a presentation.

it is for further study how a subject who is not a holder places terms of use on his or her verifiable credentials. One way could be for the subject to request the issuer to place them inside the issued verifiable credentials. Another way could be by the subject delegating a verifiable credential to a holder and placing terms of use restrictions on the delegated verifiable credential.

The expression of terms of use may be performed via the following property:

termsOfUse
The value of this property MUST be one or more terms of use that tell the verifier what actions it MUST perform if it is to accept the verifiable credential or verifiable presentation. If the verifier is not willing to accept these terms of use then it MUST reject the verifiable credential or verifiable presentation. Each termsOfUse comprises its type, for example, IssuerPolicy, and optionally its instance id. The precise contents of each term of use is determined by the specific TermsOfUse type definition.

The group is currently exploring a variety of ways of expressing the terms of use associated with a Verifiable Credential, namely, the Open Digital Rights Language. A related initiative is the one at Customer Commons.

{
  "@context": [
    "https://w3id.org/credentials/v1",
    "https://example.org/motorlicense/v1"
  ],
  "id": "http://dmv.example.gov/credentials/3732",
  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "termsOfUse": [{
    "type": "IssuerPolicy",
    "id": "http://example.com/policies/credential/4",
    "profile": "http://example.com/profiles/credential",
    "prohibition": [{
      "assigner": "https://dmv.example.gov/issuers/14",
      "assignee": "AllVerifiers",
      "target": "http://dmv.example.gov/credentials/3732",
      "action": ["Archival"]
    }]
  },
  "proof": { ... }
}
        

In the example above, the issuer is prohibiting a verifier from storing the data in an archive.

{
  "@context": [
    "https://w3id.org/credentials/v1",
    "https://example.org/motorlicense/v1"
  ],
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "type": "VerifiablePresentation",
  "credential": [{
    "id": "http://dmv.example.gov/credentials/3732",
    "type": ["VerifiableCredential", "ProofOfAgeCredential"],
    "issuer": "https://dmv.example.gov/issuers/14",
    "issuanceDate": "2010-01-01T19:73:24Z",
    "claim": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "ageOver": 21
    },
    "proof": { ... }
  }],
  "termsOfUse": [{
    "type": "HolderPolicy",
    "id": "http://example.com/policies/credential/6",
    "profile": "http://example.com/profiles/credential",
    "prohibition": [{
      "assigner": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "assignee": "https://wineonline.example.org/",
      "target": "http://dmv.example.gov/credentials/3732",
      "action": ["3rdPartyCorrelation"]
    }]
  },
  "proof": [ ... ]
}
        

In the example above, the holder, who is also the subject, is prohibiting the verifier (https://wineonline.example.org) from using the information provided to correlate the holder/subject by using a 3rd party service.

The group is currently discussing how one knows who specified the Terms of Use.

Evidence

The evidence property is used by an issuer to represent the set of evidence that was used to determine whether or not to issue a credential. For example, an issuer might check physical documentation provided by the subject or might perform a set of background checks before issuing the credential. In certain scenarios, this information is useful to the verifier when determining the risk associated with accepting the credential.

Evidence information for the credential in the Verifiable Credentials Data Model is provided by adding the following property:

evidence
The value of this property MUST be one or more evidence schemes that provides enough information to a verifier to determine whether or not the evidence gathered meets their requirements. The contents of each evidence scheme is determined by the particular scheme itself.

The group is currently determining whether or not they should publish a very simple scheme for evidence as a part of this specification.

The group is currently discussing how attachments and references to non-credential data are supported by the specification.

The group is currently discussing how attachments and references to credentials are supported by the specification.

{
  "@context": [
    "https://w3id.org/credentials/v1",
    "https://example.org/motorlicense/v1"
  ],
  "id": "http://dmv.example.gov/credentials/3732",
  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "evidence": [{
    "id": "https://dmv.example.gov/evidence/f2aeec97-fc0d-42bf-8ca7-0548192d4231",
    "type": ["DocumentVerification"],
    "verifier": "https://dmv.example.gov/issuers/14",
    "evidenceDocument": "DriversLicense",
    "subjectPresence": "Physical",
    "documentPresence": "Physical"
  }],
  "proof": { ... }
}
        

For the avoidance of doubt, the evidence property provides information that is different from and complementary to the proof property. The evidence property is used to express supporting information, such as documentary evidence, related to the integrity of the credential. In contrast, the proof property is used to express machine-verifiable mathematical proofs related to the authenticity of the issuer and integrity of the credential.

The group is currently discussing how to visualize verifiable credentials and any media associated with them.

Subject-Holder Relationships

This section describes the possible relationships between the subject and the holder and how the data model expresses the various relationships. The following diagram depicts the various types of relationships that are covered in the rest of this section:

Subject-Holder Relationships in Verifiable Credentials.

The following sections describe how each of these instances are handled in the data model.

Subject is the Holder

The most common case is when the subject is the holder. For example, the verifier can easily deduce that the subject is the holder if the verifiable presentation is digitally signed by the holder and all contained verifiable credentials are about a subject that can be identified to be the same as the holder.

Credential Uniquely Identifies Subject

. In this case, the claim may contain multiple properties that each provide an aspect of the identity of the subject, and which together unambiguously identify the subject. Some use cases may not require the holder to be identified at all, such as checking to see if a doctor (the subject) is board certified. Other use cases may require the verifier to use out-of-band knowledge to determine the relationship between the subject and the holder.

{
  "@context": ["https://w3id.org/credentials/v1", "https://schema.org/"]
  "id": "http://dmv.example.gov/credentials/332",
  "type": ["Credential", "IdentityCredential"],
  "issuer": "https://dmv.example.gov/issuers/4",
  "issued": "2017-02-24",
  "claim": {
    "name": "J. Doe",
    "address": {
      "streetAddress": "10 Rue de Chose",
      "postalCode": "98052",
      "addressLocality": "Paris",
      "addressCountry": "FR"
    },
    "birthDate": "1989-03-15"
    ...
  },
  "proof": { ... }
}
      

The example above uniquely identifies the subject through the use of the name, address, and birth date of the individual.

Subject Passes the Verifiable Credential to a Holder

The group is currently debating the best security model for delegation. Readers should treat this entire section as at-risk and currently under debate.

Normally verifiable credentials will be presented to verifiers by the subject. However in some cases, the subject may need to pass the whole or part of a verifiable credential to another holder. The data model allows for both cases as follows.

If only the subject is allowed to present the verifiable credential to a verifier, the issuer MUST insert the "subject only" Terms of Use into the verifiable credential, as defined below. This feature is at risk and is likely to be removed due to lack of consensus.

If the subject is not forbidden by the issuer to pass the whole or part of a verifiable credential to a holder, for example, a patient may pass a prescription verifiable credential to a relative for the relative to present it to a pharmacist for dispensing, then the subject MUST issue a verifiable credential to the holder containing the claim properties that are being passed on, as described below. This feature is at risk and is likely to be removed and replaced with another solution, possibly created by another Working Group, that focuses on delegation of authority instead of delegation of attributes.

'Subject Only' Terms of Use

The group is currently debating the best security model for delegation. Readers should treat this entire section as at-risk and currently under debate.

The Subject Only Terms of Use states that a verifiable credential MUST only be presented to a verifier by the subject. If a verifier is presented with a verifiable credential containing the Subject Only Terms of Use, by anyone other than the subject, it MUST refuse to accept it.

{
  "id": "http://dmv.example.gov/credentials/3732",
  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "issued": "2010-01-01T19:73:24Z",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "termsOfUse": [{
    "type": "SubjectOnly",
    }]
  },
  "proof": { ... }
}
        

Passing on a Verifiable Credential

The group is currently debating the best security model for delegation. Readers should treat this entire section as at-risk and currently under debate.

When the subject passes a verifiable credential to a holder, the subject SHOULD issue a new verifiable credential to the holder in which: the issuer is the subject, the subject is the holder to whom the verifiable credential is being passed, and the claim contains the properties that are being passed on. In addition, the holder creates a verifiable presentation that contains these two verifiable credentials.

{
  "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
  "type": ["VerifiablePresentation"],
  "credential": [{
      "id": "http://example.gov/credentials/3732",
      "type": ["Credential", "PrescriptionCredential"],
      "issuer": "https://dmv.example.gov",
      "issued": "2010-01-01",
      "claim": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "prescription": {....}
      },
      "revocation": {
        "id": "http://example.gov/revocations/738",
        "type": "SimpleRevocationList2017"
      },
      "proof": {....}
    },
    {
      "id": "https://example.com/VC/123456789",
      "type": ["Credential", "PrescriptionCredential"],
      "issuer": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "issued": "2010-01-03",
      "claim": {
        "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
        "prescription": {....}
      },
      "proof": {
        "type": "RsaSignature2018",
        "created": "2017-06-17T10:03:48Z",
        "creator": "did:example:ebfeb1f712ebc6f1c276e12ec21/keys/234",
        "nonce": "d61c4599-0cc2-4479-9efc-c63add3a43b2",
        "signatureValue": "pYw8XNi1..Cky6Ed = "
      }
    }
  ],
  "proof": [{
    "type": "RsaSignature2018",
    "created": "2017-06-18T21:19:10Z",
    "creator": "did:example:76e12ec21ebhyu1f712ebc6f1z2/keys/2",
    "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
    "signatureValue": "BavEll0/I1..W3JT24 = "
  }]
}
        

Holder Acts on Behalf of the Subject

The data model supports the holder acting on behalf of the subject in at least the following ways:

  • The issuer may include the relationship between the holder and the subject in the claim data.
  • The issuer may express the relationship between the holder and the subject by issuing a new verifiable credential which the holder utilizes.
  • The subject may express their relationship with the holder by issuing a new verifiable credential which the holder utilizes.

The mechanisms above describe the relationship between the holder and the subject and helps the verifier to decide whether the relationship is sufficiently expressed for the given use case.

The additional mechanisms that the issuer or the verifier uses to verify the relationship between the subject and the holder are outside of the scope of this specification.

It is for further study which, if any, of these mechanisms is to be standardised by the working group.

{
  "id": "http://dmv.example.gov/credentials/3732",
  "type": ["Credential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "issued": "2010-01-01T19:73:24Z",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageUnder": 16,
    "parent": {
      "id": "did:example:ebfeb1c276e12ec211f712ebc6f",
      "type": "Mother"
    }
  },
  "proof": { ... } // the proof is generated by the DMV
}
      

In the example above, the issuer has expressed the relationship between the child and the parent such that a verifier would most likely accept the credential if it is provided by the child or the parent.

{
  "id": "http://dmv.example.gov/credentials/3732",
  "type": ["Credential", "RelationshipCredential"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "issued": "2010-01-01T19:73:24Z",
  "claim": {
    "id": "did:example:ebfeb1c276e12ec211f712ebc6f",
    "child": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "type": ["Person", "Child"]
    }
  },
  "proof": { ... } // the proof is generated by the DMV
}

In the example above, the issuer has expressed the relationship between the child and the parent in a separate credential such that a verifier would most likely accept any of the child's credentials if it is provided by the child or if the credential above is provided with any of the child's credentials.

{
  "id": "http://example.org/credentials/23894",
  "type": ["Credential", "RelationshipCredential"],
  "issuer": "http://example.org/credentials/23894",
  "issued": "2010-01-01T19:73:24Z",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "parent": {
      "id": "did:example:ebfeb1c276e12ec211f712ebc6f",
      "type": "Mother"
    }
  },
  "proof": { ... } // the proof is generated by the child
}

In the example above, the child has expressed the relationship between the child and the parent in a separate credential such that a verifier would most likely accept any of the child's credentials if the credential above is provided.

Similarly, these same strategies can be used for many other types of use cases such as power of attorney, pet ownership, and patient prescription pick up.

Issuer Authorises Holder

When the issuer wishes to authorise a holder to possess a credential that describes a subject who is not the holder, and the holder has no known relationship with the subject, then the issuer inserts the relationship of the holder to itself into the subject's credential.


{
  "id": "http://dmv.example.gov/credentials/3732",
  "type": ["Credential", "NameAndAddress"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "holder": {
    "type": "LawEnforcement",
    "id": "did:example:ebfeb1276e12ec21f712ebc6f1c"
  },
  "issued": "2010-01-01",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "name": "Mr John Doe",
    "address": "10 Some Street, Anytown, ThisLocal, Country X"
  },
  "proof": {
    "type": "RsaSignature2018",
    "created": "2017-06-17T10:03:48Z",
    "creator": "https://dmv.example.gov/issuers/14/keys/234",
    "nonce": "d61c4599-0cc2-4479-9efc-c63add3a43b2",
    "signatureValue": "pY9...Cky6Ed = "
  }
}        

Holder Acts on Behalf of Verifier or has no Relationship with the Subject, Issuer or Verifier

The data model currently does not support either of these scenarios. It is for further study how they might be supported.

Disputes

The time may come when an entity wants to dispute a credential issued by another entity. The mechanism for doing this is the same as issuing a regular credential except that the subject identifier for the claims are those of the disputed credential. For example, if a disputed credential with an identifier of http://con-artist.example.com/credentials/3732 contains disputed statements, an entity would issue the following credential in a public venue to make it known that the credential is disputed:

{
  "@context": "https://w3id.org/credentials/v1",
  "id": "http://example.com/credentials/245",
  "type": ["VerifiableCredential", "DisputeCredential"],
  "claim": {
    "id": "http://con-artist.example.com/credentials/3732",
    "currentStatus": "Disputed",
    "statusReason": "Credential contains disputed statements",
    "disputedClaim": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "ageOver": 21
    }
  },
  "issuer": "https://example.com/people#me",
  "issuanceDate": "2017-12-05T14:27:42Z",
  "proof": { ... }
}
        

A DisputeCredential issued by anyone other than the subject, or its authorised agent, SHOULD be disregarded by a verifier, unless the verifier has some out of band means of ascertaining the truth of the dispute.

If a credential does not have an identifier, a content-addressed identifier can be used to identify the disputed credential. Similarly, content-addressed identifiers can be used to uniquely identify individual claims.

The group is currently exploring whether the specification of a vocabulary term to express content-based identifiers for claims is within scope as well as the specific vocabulary terms for disputed claims.

Conformance

A concrete expression of the data model in this specification is a conforming document if it complies with the normative statements in this specification regarding syntax (e.g., the content in Basic Concepts, Advanced Concepts, and Syntaxes). For convenience, normative statements for conforming documents are often phrased as statements on the syntax used in properties and their associated values in the document (e.g., "MUST be a URI", "MUST be a string value of an ISO8601 combined date and time string").

A conforming processor is a software or hardware-based implementation of the normative statements in this specification regarding the expected contents of property-value pairs (e.g., the content in Verification). For convenience, normative statements for conforming processors are often phrased as behavioral statements regarding the contents of property-value pairs (e.g., "MUST NOT be revoked", "MUST be in the expected range").

Syntaxes

Many of the data model concepts in this document thus far have been introduced by example using the JSON syntax. This section formalizes how the data model (described in Sections , , and ) is realized in JSON and JSON-LD. Although syntactic mappings are only provided for these two syntaxes, applications and services may also use any other data representation syntax, such as XML, YAML, or CBOR, that is capable of expressing the data model.

JSON

The data model as described in Section can be encoded in Javascript Object Notation (JSON) [[!RFC8259]] by mapping property values to the following JSON types:

JSON Web Token

This section will be moved into its own specification before this document enters the Candidate Recommendation stage.

The following example demonstrates how one could express this data model using a JSON Web Token.

  eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2Rtdi
  5leGFtcGxlLmdvdiIsImlhdCI6MTI2MjMwNDAwMCwiZXhwIjoxNDgzMjI4ODAwL
  CJhdWQiOiJ3d3cuZXhhbXBsZS5jb20iLCJzdWIiOiJkaWQ6ZWJmZWIxZjcxMmVi
  YzZmMWMyNzZlMTJlYzIxIiwiZW50aXR5Q3JlZGVudGlhbCI6eyJAY29udGV4dCI
  6Imh0dHBzOi8vdzNpZC5vcmcvc2VjdXJpdHkvdjEiLCJpZCI6Imh0dHA6Ly9leG
  FtcGxlLmdvdi9jcmVkZW50aWFscy8zNzMyIiwidHlwZSI6WyJDcmVkZW50aWFsI
  iwiUHJvb2ZPZkFnZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9kbXYu
  ZXhhbXBsZS5nb3YiLCJpc3N1ZWQiOiIyMDEwLTAxLTAxIiwiY2xhaW0iOnsiaWQ
  iOiJkaWQ6ZWJmZWIxZjcxMmViYzZmMWMyNzZlMTJlYzIxIiwiYWdlT3ZlciI6Mj
  F9fX0.LwqH58NasGPeqtTxT632YznKDuxEeC59gMAe9uueb4pX_lDQd2_UyUcc6
  NW1E3qxvYlps4hH_YzzTuXB_R1A9UHXq4zyiz2sMtZWyJkUL1FERclT2CypX5e1
  fO4zVES_8uaNoinim6VtS76x_2VmOMQ_GcqXG3iaLGVJHCNlCu4
  

The JWT above was produced using the inputs below:

A number of the concerns have been raised around security, composability, reusability, and extensibility with respect to the use of JWTs for Verifiable Credentials. These concerns will be documented in time in at least the Verfiable Claims Model and Security Considerations section of this document.

  // JWT Header
  {
    "alg": "RS256",
    "typ": "JWT"
  }
  // JWT Payload
  {
    "iss": "https://dmv.example.gov",
    "iat": 1262304000,
    "exp": 1483228800,
    "aud": "www.example.com",
    "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "verifiableCredential": {
      "@context": "https://w3id.org/security/v1",
      "id": "http://example.gov/credentials/3732",
      "type": ["VerifiableCredential", "ProofOfAgeCredential"],
      "issuer": "https://dmv.example.gov",
      "issuanceDate": "2010-01-01",
      "claim": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "ageOver": 21
      }
    }
  }
  

JSON-LD

[[!JSON-LD]] is a JSON-based format that is used to serialize Linked Data. The syntax is designed to easily integrate into deployed systems that already use JSON, and provides a smooth upgrade path from JSON to JSON-LD. It is primarily intended to be a way to use Linked Data in Web-based programming environments, to build interoperable Web services, and to store Linked Data in JSON-based storage engines.

JSON-LD is useful when extending the data model described in this specification. Instances of the data model are encoded in JSON-LD in the same way that they are encoded in JSON (Section ), with the addition of the @context property. The JSON-LD Context is described in detail in the [[!JSON-LD]] specification and its use is elaborated upon in Section .

Multiple contexts MAY be used or combined to express any arbitrary information about credentials in idiomatic JSON. If an application is processing a verifiable credential or verifiable presentation, and a @context property is not present at the top-level of the JSON-LD document, then a @context property with a value of https://w3id.org/credentials/v1 MUST be assumed.

Verification

This section describes a number of checks required to verify a credential. Some checks are essential for all verifiable credentials, while some are applicable to only some credentials.

The group is currently discussing whether a mechanism should be provided that enables linkages to JSON Schema or other optional validation mechanisms.

Syntax

Credential

Issuer

Subject

The group is currently discussing how authentication and WebAuthn may work.

The id property is optional, and verifiers MAY use other properties in a credential to uniquely identify the subject.

Proofs (e.g., Signatures)

The cryptographic mechanism used to prove that the information in a verifiable credential or a verifiable presentation has not been tampered with is called a proof. There are many types of cryptographic proofs including but not limited to, digital signatures, zero-knowledge proofs, proofs of work, and proofs of stake. In general, when verifying proofs, implementations MUST ensure that:

Some proofs are digital signatures. In general, when verifying digital signatures, implementations MUST ensure that:

The digital signature provides a number of protections, other than tamper resistance, that are not immediately obvious. For example, a Linked Data Signature's created property establishes a date and time where the credential SHOULD NOT be considered valid before that date and time. The creator property enables the ability to dynamically discover information about the entity that created the data to ensure that the public key has not been revoked or expired. The proofPurpose property ensures that the reason the entity created the signature, such as for the purposes of authentication or creating a verifiable credential, is clear and protected in the signature.

Issuance

Expiration

Revocation

Fitness for Purpose

Privacy Considerations

This section is non-normative.

This section details the general privacy considerations and specific privacy implications of deploying the verifiable credentials data model into production environments.

Spectrum of Privacy

It is important to recognize that there is a spectrum of privacy that ranges from pseudonymous to strongly identified. Depending on the use case, people have different appetites when it comes to what information they are willing to provide and what information may be derived from what is provided.

- Privacy is a spectrum that ranges from pseudonymous to fully identified.

For example, one would most likely desire to remain anonymous when purchasing alcohol because the regulatory check that’s required is solely whether or not the person is above a particular age. However, when a doctor is writing a prescription for a patient, the pharmacy fulfilling the prescription is required to more strongly identify the medical professional. Therefore it is important to recognize that there is not one approach to privacy that works for all use cases; privacy solutions tend to be use case specific.

Even if one may desire to remain anonymous when purchasing alcohol, a photo ID may still be required to provide appropriate assurance to the merchant. The merchant may not need to know your name or other details (other than that you are over a certain age), but in many cases a mere proof of age may still be insufficient to meet regulations.

The Verifiable Credentials data model strives to support the full spectrum of privacy and does not take philosophical positions on the right level of anonymity for any particular transaction. The following sections provide guidance for implementers that want to avoid specific scenarios that are hostile to privacy.

The group is currently discussing how the specification should be modified to support ZKPs and other forms of anonymous credentials.

Personally Identifiable Information

The data associated with verifiable credentials stored in the credential.claim field are largely susceptible to privacy violations when shared with verifiers. Personally identifying data such as a government-issued identifier, shipping address, and full name can be easily used to determine, track, and correlate an entity. Even information that does not seem personally identifiable like the combination of a birth date and zip code have very powerful correlation and de-anonymizing capabilities.

Implementers are strongly advised to warn holders when they share data with these sorts of characteristics. Issuers are strongly advised to provide privacy-protecting credentials when possible. For example, issuing ageOver credentials instead of birthdate credentials when the verifier desires to determine if an entity is over the age of 18.

Identifier-Based Correlation

Subjects of verifiable credentials are identified via the credential.claim.id field. The identifiers that are used to identify the subject create a danger of correlation when the identifiers are long-lived or used across more than one web domain.

If strong anti-correlation properties are a requirement in a system using verifiable credentials, it is strongly advised that identifiers are bound to a single origin or that identifiers are single-use or not used at all and are replaced by short-lived, single-use bearer tokens.

Signature-Based Correlation

The contents of verifiable credentials are secured via the credential.proof field. The properties in this field create a danger of correlation when the same values are used across more than one session or domain and the value does not change. Examples include the creator, created, domain (for very specific domains), nonce, and signatureValue fields.

If strong anti-correlation properties are desired, it is advised that signature values and metadata are regenerated each time using technologies like third-party pairwise signatures, zero-knowledge proofs, or group signatures. It is also important to note that even when using anti-correlation signatures that information may still be contained in the credential that defeats the anti-correlation properties of the cryptography.

Long Lived Identifier-Based Correlation

Verifiable credentials may contain long lived identifiers that could be used to correlate individuals. These types of identifiers include: subject identifiers, email addresses, government-issued identifiers, organization-issued identifiers, addresses, healthcare vitals, credential-specific JSON-LD Contexts, and many other sorts of long-lived identifiers.

Organizations providing software to holders should strive to identify fields in credentials containing information that could be used to correlate them and warn the holder when this information is shared.

Device Fingerprinting

There are mechanisms external to Verifiable Credentials that are used to track and correlate individuals on the Internet and the Web. Some of these mechanisms include Internet Protocol address tracking, web browser fingerprinting, evercookies, advertising network trackers, mobile network position information, and in-application Global Positioning System APIs. The use of Verifiable Claims cannot prevent the use of these other tracking technologies. In addition, when these technologies are used in concert with Verifiable Credentials, new correlatable information may be discovered. For example, a birthday coupled with a GPS position can be used to strongly correlate an individual across multiple websites.

It is advised that privacy-respecting systems prevent the use of these other tracking technologies when verifiable credentials are being utilized. In some cases, these tracking technologies may need to be disabled entirely on devices that transmit verifiable credentials on behalf of the Holder.

Favor Abstract Claims

In order to enable recipients of verifiable credentials to use them in a variety of circumstances without revealing more personally identifiable information than necessary for the transaction, issuers should consider limiting the information published in a credential to a minimal set needed for the expected purposes. One way to avoid placing personally identifiable information in a credential is to use an "abstract" property that meets the needs of verifiers without providing specific information about the subject.

An example in this document is the use of the ageOver property as opposed to a specific birthdate that would constitute much stronger personally identifiable information. If retailers in a market commonly require purchasers to be older than a specific age, an issuer trusted in that market may choose to offer a credential claiming that subjects have met that requirement as opposed to offering credentials containing claims of their specific birthdates. This enables individual customers to purchase items without revealing specific personally identifiable information.

The Principle of Minimum Disclosure

Privacy violations occur when information divulged in one context leaks into another. Accepted best practice for preventing such violations is to limit the information requested, and received, to the absolute minimum necessary. This minimal disclosure approach is required by regulation in multiple jurisdictions, including HIPAA in the US and GDPR in the EU.

With verifiable credentials, minimal disclosure for issuers means limiting the content of a credential to the minimum required by potential verifiers for expected use. For verifiers, it means limiting the scope of the information requested or required for accessing services.

For example, a driver's license containing a driver's ID number, height, weight, birthday, and home address is an example of a credential containing more information than is necessary to establish that the person is above a certain age.

It is considered a best practice for issuers to atomize information or use a signature scheme that allows for selective disclosure. For example, an issuer that issues driver's licenses could issue a set of credentials containing every attribute that appears on a driver's license in addition to atomized credentials (a credential containing only the person's birthday), and atomized credentials that are more abstract (a credential containing only an ageOver attribute). In addition, the issuer is encouraged to provide secure HTTP endpoints for retrieving single-use bearer credentials to promote the pseudonymous usage of credentials when it is safe for the issuer to issue such credentials.

Similarly, verifiers are urged to only request information that is absolutely necessary for a particular transaction to occur. This is important for at least two reasons: 1) it reduces the liability on the verifier for handling highly sensitive information that it does not need, and 2) it enhances the privacy of the individual by only asking for information that is required for the particular transaction.

While it is possible to practice the Principle of Minimum Disclosure, it may be impossible to avoid the strong identification of an individual for specific use cases during a single session or over multiple sessions. The authors of this document cannot stress how difficult it is to meet this principle in real world scenarios.

Bearer Credentials

A bearer credential is a privacy-enhancing piece of information, such as a concert ticket, that entitles the holder of the credential to a particular resource without divulging sensitive information about the holder.

Verifiable Credentials that are bearer credentials are possible by not specifying the subject identifier, expressed using the id property that is nested in the claim property. For example, the following Verifiable Credential is a bearer credential:

{
  "@context": "https://w3id.org/credentials/v1",
  "id": "http://dmv.example.gov/credentials/temporary/28934792387492384",
  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "issuanceDate": "2017-10-22T12:23:48Z",
  "claim": {
    // note that the 'id' property is not specified for bearer credentials
    "ageOver": 21
  },
  "proof": { ... }
}
        

While bearer credentials can be privacy enhancing, their use must be carefully crafted to not accidentally divulge more information than the holder of the credential expects. For example, repeated use of the same bearer credential across sites enables each site to potentially collude to unduly track or correlate the holder. Additionally, information that may seem non-identifying such as a birthdate and zip code can be used to statistically identify an individual when used together in the same credential or session.

Issuers of bearer credentials SHOULD ensure that bearer credentials that are expected to provide privacy-enhancing benefits 1) are single use, when possible, 2) do not contain personally identifying information, and 3) are not unduly correlatable.

Holders SHOULD be warned by their software if bearer credentials containing sensitive information are issued or requested, or if there is a correlation risk when combining two or more bearer credentials across one or more sessions. While it may be impossible to detect all correlation risks, some may be detectable.

Verifiers SHOULD NOT request bearer credentials that can be used to unduly correlate the user.

Validity Checks

When processing verifiable credentials, verifiers typically perform many of the checks listed in Section as well as a variety of business-process-specific checks. For example, validity checks may include any of the following:

The process of performing these checks may result in information leakage that leads to a privacy violation of the holder. For example, an operation as simple as checking a revocation list can notify the issuer that a very specific business is most likely interacting with the holder. This would enable issuers to collude and correlate individuals without their knowledge.

Issuers are urged to not use mechanisms, such as credential revocation lists that are unique per credential, during the verification process that would lead to privacy violations. Organizations providing software to holders should warn when credentials include information that could lead to privacy violations during the verification process. Verifiers should consider rejecting credentials that produce privacy violations or that enable bad privacy practices.

Storage Providers and Data Mining

When a holder receives a credential from an issuer, the credential will need to be stored somewhere (e.g., in a credential repository). Holders are warned that the information in a verifiable credential may be sensitive in nature and highly individualized, making it a high value target for data mining. Therefore, there may be services that store verifiable credentials for free and mine personal data and sell it to organizations that desire individualized profiles on people and organizations (i.e., if the service is free, you are the product).

It is suggested that holders be aware of the terms of service for their credential repository, specifically the correlation and data mining protections that are in place for those who store their verifiable credentials at the service provider.

There are a number of effective mitigations for data mining and profiling:

Aggregation of Credentials

Two pieces of information about the same subject almost always reveal more information than just a single piece of information, even when delivered through different channels. The aggregation of credentials is a privacy risk and all participants in the ecosystem need to be aware of the risks of data aggregation.

For example, if a bearer credential for an email address and then a bearer credential stating that the holder is over the age of 21 are provided across multiple sessions, the verifier of the information has 1) a unique identifier to associate with the individual, and 2) age-related information for that individual. It then becomes trivial to create a profile for the holder such that more and more information is leaked over time. Aggregation of credentials can be performed across multiple sites that are colluding as well, leading to privacy violations.

Preventing the aggregation of information is a very difficult privacy problem to address from a technological perspective. While new cryptographic techniques, such as zero-knowledge proofs, have been proposed as solutions to the problem of aggregation and correlation, the existence of long-lived identifiers and browser tracking techniques easily defeat even the most modern cryptographic techniques.

The solution to the privacy implications of correlation or aggregation tend to not be technological in nature, but policy driven instead. Therefore, if a holder does not wish information to be aggregated about them, then they must express this in the verifiable presentations that they transmit.

Usage Patterns

Despite the best efforts to assure privacy, the actual use of verifiable credentials can potentially lead to de-anonymization and a loss of privacy. This correlation can occur:

  1. When the same credential is presented to the same verifier more than once — that verifier could infer that the holder is the same individual.
  2. When the same credential is presented to different verifiers, and either those verifiers collude or a third party has access to transaction records from both verifiers — the observant party could infer that the individual presenting the credential is the same person at both services, i.e., the accounts are controlled by the same person.
  3. When the same subject identifier of a credential refers to the same subject across presentations or verifiers, then loss of privacy is possible. Even when different credentials are presented, if the subject identifier is the same, verifiers (and those with access to verifier logs) could infer that the holder of the credential is the same person.
  4. When the underlying information in a credential can be used to identify an individual across services — using information from other sources (including information provided directly by the user), verifiers can use the information inside the credential to correlate the individual with an existing profile. For example, if a holder presents credentials that include zip code, age, and sex, the verifier can potentially correlate the subject of that credential with an established profile [see Sweeney 2000 Simple Demographics Often Identify People Uniquely].
  5. When passing the identifier of a credential to a centralized revocation server — the centralized server can correlate the credential usage across interactions. For example, if a verifiable credential is used for proof of age in this manner, the centralized service could know everywhere that credential was presented: all liquor stores, bars, adult stores, lottery purchases, etc.

It’s possible to mitigate this in part:

  1. Use a globally-unique identifier as the subject for any given credential and never re-use that credential.
  2. If the credential supports revocation, use a globally-distributed service for revocation.
  3. Design revocation APIs that do not depend on submitting the ID of the credential, e.g., use a revocation list rather than a query.
  4. Avoid associating personally identifiable information with any particular long-lived subject identifier.

It is understood that these mitigation techniques are not always practical or even compatible with necessary usage. Sometimes correlation is the point.

In state prescription monitoring programs, usage monitoring is a requirement: enforcement entities need to be able to confirm that individuals are not cheating the system to get multiple prescriptions for controlled substances. This statutory or regulatory need to correlate usage overrides individual privacy concerns.

Verifiable credentials will so be used to intentionally correlate individuals across services, for example, when using a common persona to log in to multiple services, so all activity on each of those services is intentionally linked to the same individual. This is not a privacy issue as long as each of those services uses the correlation in the expected manner.

Privacy risks of credential usage occur when unintended or unexpected correlation arises from the presentation of verifiable credentials.

Sharing Information with the Wrong Party

When a holder chooses to share information with a verifier, it may be the case that the verifier is acting in bad faith and requests information that could be used to harm the holder. For example, a verifier may ask for a bank account number, which could then be used in concert with other information to defraud the holder or the bank.

Issuers should strive to tokenize as much information as possible such that if a holder accidentally transmits credentials to the wrong verifier that the information loss isn't catastrophic.

For example, instead of including a bank account number for the purposes of checking a bank balance for an individual, provide a token that enables the verifier to use the token to check to see if the balance is above a certain amount. In this case, the bank could issue a verifiable credential containing a token for checking balance to a holder. A holder would then include the verifiable credential in a verifiable presentation and bind the token to a credit checking agency via a digital signature. The verifier would then wrap the verifiable presentation in their digital signature, and hand it back to the issuer to dynamically check the account balance.

This approach ensures that even if the holder shares the account balance token with the wrong party that the attacker doesn't discover the bank account number, nor the exact value in the account, and given the validity period for the counter-signature, doesn't gain access to the token for more than a few minutes.

Frequency of Claim Issuance

As Section details, usage patterns can be correlated into certain types of behavior. Part of this correlation is mitigated when a holder uses a verifiable credential without the knowledge of the issuer. Issuers may defeat this protection by making their credentials short lived and renewal automatic.

For example, an "over the age of 21" credential may be useful when gaining access to a bar. If an issuer makes the credential have a very short expiration date and an automatic renewal mechanism, then they could possibly correlate the holder's behavior in a way that negatively impacts the holder.

Organizations providing software to holders should warn holders if they repeatedly use credentials with short lifespans that could result in behavior correlation. Issuers should avoid issuing credentials in a way that enables them to correlate usage patterns.

Prefer Single-Use Credentials

An ideal privacy-respecting system would only require information to be disclosed by the holder that is necessary for the interaction with the verifier. The verifier would then record that the disclosure requirement was met and forget any sensitive information that was disclosed. In many cases, competing priorities, such as regulatory burden, prevent this ideal system from being employed. In other cases, long-lived identifiers prevent single use. The design of any verifiable credentials ecosystem, however, should strive to be as privacy-respecting as possible by preferring single-use credentials when possible.

The usage of these type of credentials provides several benefits. The first benefit is to verifiers who can be sure that the data in the credential is fresh. The second benefit is to holders, who know that if there are no long-lived identifiers in the credential that the credential itself cannot be used to track or correlate them online. Finally, the third benefit ensures that there is nothing for attackers to steal, making the entire ecosystem safer to operate within.

Avoid Disclosing Credential Identifier

Disclosing the credential identifier leads to situations where multiple verifiers or an issuer and a verifier can collude to correlate the holder. If the holder desires to reduce correlation, they should use credential schemes which allow hiding the identifier during presentation. Such schemes expect the holder to generate the identifier and may even allow hiding the identifier from the issuer, whilst still keeping the identifier embedded and signed in the credential.

Security Considerations

This section is non-normative.

There are a number of security considerations that issuers, holders, and verifiers should be aware of when processing data described by this specification. Ignoring or not understanding the implications of this section can result in security vulnerabilities.

While this section attempts to highlight a broad set of security considerations, it should not be interpreted as a complete list of all security considerations. Implementers are urged to seek the advice of security and cryptography professionals when implementing mission critical systems using the technology outlined in this specification.

Cryptography Suites and Libraries

Some aspects of the data model described in this specification can be protected through the use of cryptography. Implementers should be aware of the underlying cryptography suites and libraries that are used to implement the creation and verification of digital signatures and mathematical proofs utilized by their systems when processing credentials and presentations. Software developers with extensive experience implementing or auditing systems that use cryptography must be used to ensure that systems are properly designed. Proper red teaming is also suggested to remove bias from security reviews.

Cryptography suites and libraries have a shelf life and eventually fall to new attacks and technology advances. Any production quality system must take this reality into account and ensure that mechanisms exist to easily upgrade old or broken cryptographic suites and libraries in a proactive manner. Mechanisms should also exist to invalidate and replace existing credentials in the event of a cryptography suite or library failure. Regular monitoring of systems to ensure proper upgrades are made in a timely manner are also important to ensure the long term viability of systems processing verifiable credentials.

Unsigned Claims

This specification allows credentials to be produced that do not contain signatures or proofs of any kind. These types of credentials are often useful for intermediate storage, or self-asserted information, which is analogous to filling out a form on a web page. Implementers should note that these types of credentials are not verifiable because the authorship is either not known or cannot be trusted.

Token Binding

A verifier may need to ensure that it is the intended recipient of a verifiable presentation and is not the target of a man-in-the-middle attack. Any protocol that utilizes the Verifiable Credentials Data Model and requires protection against these sorts of attacks needs to perform some sort of token binding, such as using The Token Binding Protocol v1.0, that ties the request for a verifiable presentation with the response. Any protocol that does not perform token binding is susceptible to man-in-the-middle attacks.

Bundling Dependent Claims

It is considered a best practice for issuers to atomize information in a credential, or use a signature scheme that allows for selective disclosure. In the former case, if the atomization is not done securely by the issuer, the holder might bundle together different credentials in a way that was not intended by the issuer.

For example a university might issue two credentials to a person, each containing two properties, i.e., "Staff Member" in the "Department of Computing" and "Post Graduate Student" in the "Department of Economics". If these credentials are atomized into separate properties, then the university would issue four credentials to the person, each containing one of the following properties: "Staff Member", "Post Graduate Student", "Department of Computing", and "Department of Economics". The holder could then transfer the "Staff Member" and "Department of Economics" to a verifier, which together would comprise a false claim.

Highly Dynamic Information

When verifiable credentials are issued for highly dynamic information, implementers should ensure that the expiration times for the credential are set appropriately. Expiration periods that are longer than the timeframe where the credential is valid may create exploitable security vulnerabilities. Expiration periods that are shorter than the timeframe where the information expressed by the credential is valid create a burden on holders and verifiers. It is therefore important to set validity periods for credentials that are appropriate to the use case and the expected lifetime for the information contained in the credential.

Device Theft and Impersonation

When verifiable credentials are stored on a device and that device is stolen by an attacker, it may be possible for the attacker to then gain access to systems using the victim's verifiable credentials. Mitigations for this attack include: