Verifiable Credentials Data Model 1.0

1.1 What is a Verifiable Credential?

In the physical world, a credential might consist of:

• Information related to the subject of the credential (for example, a photo, name, and identification number)
• Information related to the issuing authority (for example, a city government, national agency, or certification body)
• Information related to the specific attribute(s) or properties being asserted by issuing authority about the subject
• Evidence related to how the credential was derived
• Information related to expiration dates.

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 more trustworthy than their physical counterparts. Holders of verifiable credentials can generate presentations and then share these presentations with verifiers to prove they possess verifiable credentials with certain characteristics. Both verifiable credentials and verifiable presentations can be transmitted rapidly, making them more convenient than their physical counterparts when trying to establish trust at a distance.

While this specification attempts to improve the ease of expressing digital credentials, it also attempts to balance this goal with a number of privacy-preserving goals. The persistence of digital information, and the ease with which disparate sources of digital data can be collected and correlated, comprise a privacy concern that the use of verifiable and easily machine-readable credentials threatens to make worse. This document outlines and attempts to address a number of these issues in Section § 9. Privacy Considerations. Examples of how to use this data model using privacy-enhancing technologies, such as zero-knowledge proofs, are also provided throughout this document.

8.1 Data First Approaches

Many physical credentials in use today, such as government identification cards, have poor accessibility characteristics, including, but not limited to, small print, reliance on small and high-resolution images, and no affordances for people with vision impairments.

When utilizing this data model to create verifiable credentials, it is suggested that data model designers use a data first approach. For example, given the choice of using data or a graphical image to depict a credential, designers should express every element of the image, such as the name of an institution or the professional credential, in a machine-readable way instead of just relying on the image to convey this information. Using a data first approach is preferred because it provides the foundational elements of building different interfaces for people with varying abilities.

9.1 Spectrum of Privacy

It is important to recognize there is a spectrum of privacy ranging from pseudonymous to strongly identified. Depending on the use case, people have different comfort levels about what information they are willing to provide and what information can be derived from what is provided.

For example, most people probably want to remain anonymous when purchasing alcohol because the regulatory check required is solely based on whether a person is above a specific age. Alternatively, for medical prescriptions written by a doctor for a patient, the pharmacy fulfilling the prescription is required to more strongly identify the medical professional and the patient. Therefore there is not one approach to privacy that works for all use cases. Privacy solutions are use case specific.

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

9.2 Personally Identifiable Information

Data associated with verifiable credentials stored in the credential.credentialSubject field is 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, such as the combination of a birthdate and a postal code, has very powerful correlation and de-anonymizing capabilities.

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

9.3 Identifier-Based Correlation

Subjects of verifiable credentials are identified using the credential.credentialSubject.id field. The identifiers used to identify a subject create a greater risk of correlation when the identifiers are long-lived or used across more than one web domain.

Similarly, disclosing the credential identifier (credential.id) leads to situations where multiple verifiers, or an issuer and a verifier, can collude to correlate the holder. If holders want to reduce correlation, they should use credential schemes that allow hiding the identifier during presentation. Such schemes expect the holder to generate the identifier and might even allow hiding the identifier from the issuer, while still keeping the identifier embedded and signed in the credential.

If strong anti-correlation properties are a requirement in a verifiable credentials system, it is strongly advised that identifiers are either:

• Bound to a single origin
• Single-use
• Not used at all, but instead replaced by short-lived, single-use bearer tokens.

9.4 Signature-Based Correlation

The contents of verifiable credentials are secured using the credential.proof field. The properties in this field create a greater risk 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 required, 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.

9.5 Long-Lived Identifier-Based Correlation

Verifiable credentials might 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 individuals and warn holders when this information is shared.

9.6 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 (IP) address tracking, web browser fingerprinting, evercookies, advertising network trackers, mobile network position information, and in-application Global Positioning System (GPS) APIs. Using verifiable credentials cannot prevent the use of these other tracking technologies. Also, when these technologies are used in conjunction with verifiable credentials, new correlatable information could be discovered. For example, a birthday coupled with a GPS position can be used to strongly correlate an individual across multiple websites.

It is recommended that privacy-respecting systems prevent the use of these other tracking technologies when verifiable credentials are being used. In some cases, tracking technologies might need to be disabled on devices that transmit verifiable credentials on behalf of a holder.

9.7 Favor Abstract Claims

To enable recipients of verifiable credentials to use them in a variety of circumstances without revealing more personally identifiable information than necessary for transactions, 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 a subject.

For example, this document uses the ageOver property instead of a specific birthdate, which constitutes much stronger personally identifiable information. If retailers in a specific market commonly require purchasers to be older than a certain age, an issuer trusted in that market might choose to offer a credential claiming that subjects have met that requirement instead of offering credentials containing claims about specific birthdates. This enables individual customers to make purchases without revealing specific personally identifiable information.

9.8 The Principle of Data Minimization

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 data minimization approach is required by regulation in multiple jurisdictions, including the Health Insurance Portability and Accountability Act (HIPAA) in the United States and the General Data Protection Regulation (GDPR) in the European Union.

With verifiable credentials, data minimization for issuers means limiting the content of a credential to the minimum required by potential verifiers for expected use. For verifiers, data minimization 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 a credential containing more information than is necessary to establish that the person is above a certain age.

It is considered best practice for issuers to atomize information or use a signature scheme that allows for selective disclosure. For example, an issuer of driver's licenses could issue a credential containing every attribute that appears on a driver's license, as well as a set of credentials where every credential contains only a single attribute such as a person's birthday. It could also issue more abstract credentials (for example, a credential containing only an ageOver attribute). One possible adaptation would be for issuers to provide secure HTTP endpoints for retrieving single-use bearer credentials that promote the pseudonymous usage of credentials. Implementers that find this impractical or unsafe, should consider using selective disclosure schemes that eliminate dependence on issuers at proving time and reduce temporal correlation risk from issuers.

Verifiers are urged to only request information that is absolutely necessary for a specific transaction to occur. This is important for at least two reasons. It:

• Reduces the liability on the verifier for handling highly sensitive information that it does not need to.
• Enhances the privacy of the individual by only asking for information required for a specific transaction.

9.9 Bearer Credentials

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

Verifiable credentials that are bearer credentials are made possible by not specifying the subject identifier, expressed using the id property, which is nested in the credentialSubject property. For example, the following verifiable credential is a bearer credential:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://example.com/examples/v1"
  ],
  "id": "http://example.edu/credentials/temporary/28934792387492384",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2017-10-22T12:23:48Z",
  "credentialSubject": {
    // note that the 'id' property is not specified for bearer credentials
    "degree": {
      "type": "BachelorDegree",
      "name": "Bachelor of Science in Mechanical Engineering"
    }
  },
  "proof": { ... }
}

While bearer credentials can be privacy-enhancing, they must be carefully crafted so as not accidentally divulge more information than the holder of the credential expects. For example, repeated use of the same bearer credential across multiple sites enables these sites to potentially collude to unduly track or correlate the holder. Likewise, information that might seem non-identifying, such as a birthdate and postal 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 the bearer credentials provide privacy-enhancing benefits that:

• Are single-use, where possible
• Do not contain personally identifying information
• 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 might be impossible to detect all correlation risks, some might certainly be detectable.

Verifiers should not request bearer credentials that can be used to unduly correlate the holder.

9.10 Validity Checks

When processing verifiable credentials, verifiers typically perform many of the checks listed in Section § 7. Verification as well as a variety of business-process-specific checks. For example, validity checks might include checking:

• The professional licensure status of the holder.
• A date of license renewal or revocation.
• The sub-qualifications of an individual.
• If a relationship exists between the holder and the entity with whom the holder is attempting to interact.
• The geolocation information associated with the holder.

The process of performing these checks might result in information leakage that leads to a privacy violation of the holder. For example, a simple operation like checking a revocation list can notify the issuer that a specific business is likely interacting with the holder. This could 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 could 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.

9.11 Storage Providers and Data Mining

When a holder receives a credential from an issuer, the credential needs to be stored somewhere (for example, in a credential repository). Holders are warned that the information in a verifiable credential is sensitive in nature and highly individualized, making it a high value target for data mining. Services that advertise free storage of verifiable credentials might in fact be mining personal data and selling it to organizations wanting to build individualized profiles on people and organizations.

Holders need to be aware of the terms of service for their credential repository, specifically the correlation and data mining protections in place for those who store their verifiable credentials with the service provider.

The following are some effective mitigations for data mining and profiling:

• Use service providers that do not sell your information to third parties.
• Use software that encrypts verifiable credentials such that a service provider cannot view the contents of the credential.
• Use software that stores verifiable credentials locally on a device that you control and that does not upload or analyze your information beyond your expectations.

9.12 Aggregation of Credentials

Holding two pieces of information about the same subject almost always reveals more about the subject than just the sum of two pieces of information, even when the information is 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 two bearer credentials, one for an email address and then one stating the holder is over the age of 21, are provided across multiple sessions, the verifier of the information now has a unique identifier plus age-related information for the individual. It is now easy to create and build a profile for the holder such that more and more information is leaked over time. Aggregation of credentials can also be performed across multiple sites in collusion with each other, leading to privacy violations.

From a technological perspective, preventing the aggregation of information is a very difficult privacy problem to address. While new cryptographic techniques, such as zero-knowledge proofs, are being proposed as solutions to the problem of aggregation and correlation, the existence of long-lived identifiers and browser tracking techniques defeats even the most modern cryptographic techniques.

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

9.13 Usage Patterns

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

• The same credential is presented to the same verifier more than once. In this case, the verifier could infer that the holder is the same individual.
• 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. In this case, the observant party could infer that the individual presenting the credential is the same person at both services. That is, the accounts are controlled by the same person.
• A subject identifier of a credential refers to the same subject across multiple presentations or verifiers. 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.
• The underlying information in a credential can be used to identify an individual across services. In this case, using information from other sources (including information provided directly by the holder), verifiers can use information inside the credential to correlate the individual with an existing profile. For example, if a holder presents credentials that include postal code, age, and gender, a verifier can potentially correlate the subject of that credential with an established profile. For more information, see [DEMOGRAPHICS].
• Passing the identifier of a credential to a centralized revocation server. In this case 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, and so on.

In part, it is possible to mitigate this de-anonymization and loss of privacy by:

• Using a globally-unique identifier as the subject for any given credential and never re-use that credential.
• If the credential supports revocation, using a globally-distributed service for revocation.
• Designing revocation APIs that do not depend on submitting the ID of the credential. For example, use a revocation list instead of a query.
• Avoiding the association of personally identifiable information with any specific long-lived subject identifier.

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

For example, in some prescription drug 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 also 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.

9.14 Sharing Information with the Wrong Party

When a holder chooses to share information with a verifier, it might 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 might ask for a bank account number, which could then be used 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, the situation is not catastrophic.

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

Using this approach, even if a holder shares the account balance token with the wrong party, an attacker cannot discover the bank account number, nor the exact value in the account. And given the validity period for the counter-signature, does not gain access to the token for more than a few minutes.

9.15 Frequency of Claim Issuance

As detailed in Section § 9.13 Usage Patterns, 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 can defeat this protection however, by making their credentials short lived and renewal automatic.

For example, an ageOver credential is useful for gaining access to a bar. If an issuer issues such a credential with a very short expiration date and an automatic renewal mechanism, then the issuer could possibly correlate the behavior of the holder in a way that negatively impacts the holder.

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

9.16 Prefer Single-Use Credentials

An ideal privacy-respecting system would require only the information necessary for interaction with the verifier to be disclosed by the holder. 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 whenever possible.

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

10.1 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 used to implement the creation and verification of digital signatures and mathematical proofs used by their systems when processing credentials and presentations. Software developers with extensive experience implementing or auditing systems that use cryptography must be employed to ensure 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. Production quality systems must take this into account and ensure mechanisms exist to easily and proactively upgrade expired or broken cryptography suites and libraries. Procedures 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.

10.2 Content Integrity Protection

Verifiable credentials often contain URLs to data that resides outside of the credential itself. Content that exists outside a verifiable credential, such as links to images, JSON-LD Contexts, and other machine-readable data, are often not protected against tampering because the data resides outside of the protection of the proof on the verifiable credential. For example, the following highlighted links are not content-integrity protected and probably should be:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://example.com/examples/v1"
  ],
  "id": "http://example.edu/credentials/58473",
  "type": ["VerifiableCredential", "AlumniCredential"],
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "image": "https://example.edu/images/58473",
    "alumniOf": "Example University"
  },
  "proof": { ... }
}

While this specification does not recommend any particular content integrity protection, document authors that would like to ensure that links to content are integrity protected are advised to use URL schemes that enforce content integrity. Two such schemes are the Hashlink specification and the InterPlanetary File System (IPFS). The example below transforms the example above and adds content integrity protection to the JSON-LD Contexts using the Hashlink specification, and content integrity protection to the image by using an IPFS link:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1?hl=z3aq31uzgnZBuWNzUB",
    "https://example.com/examples/v1?hl=z8guWNzUBnZBu3aq31"
  ],
  "id": "http://example.edu/credentials/58473",
  "type": ["VerifiableCredential", "AlumniCredential"],
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "image": "ipfs:/ipfs/QmXfrS3pHerg44zzK6QKQj6JDk8H6cMtQS7pdXbohwNQfK/image",
    "alumniOf": "Example University"
  },
  "proof": { ... }
}

While the example above is one way to achieve content integrity protection, there are other solutions that may be better suited for certain applications. Implementers are urged to understand how links to external machine-readable content that are not content-integrity protected may result in successful attacks against their applications.

10.3 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.

10.4 Token Binding

A verifier might need to ensure it is the intended recipient of a verifiable presentation and not the target of a man-in-the-middle attack. Any protocol using the Verifiable Credentials Data Model that requires protection against these kinds of attacks needs to perform some sort of token binding, such as The Token Binding Protocol v1.0, which 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.

10.5 Bundling Dependent Claims

It is considered best practice for issuers to atomize information in a credential, or use a signature scheme that allows for selective disclosure. In the case of atomization, if it 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, for example, "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" credentials to a verifier, which together would comprise a false claim.

10.6 Highly Dynamic Information

When verifiable credentials are issued for highly dynamic information, implementers should ensure the expiration times are set appropriately. Expiration periods longer than the timeframe where the credential is valid might create exploitable security vulnerabilities. Expiration periods shorter than the timeframe where the information expressed by the credential is valid creates 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.

10.7 Device Theft and Impersonation

When verifiable credentials are stored on a device and that device is lost or stolen, it might be possible for an attacker to gain access to systems using the victim's verifiable credentials. Ways to mitigate this type of attack include:

• Enabling password, pin, pattern, or biometric screen unlock protection on the device.
• Enabling password, biometric, or multi-factor authentication for the credential repository.
• Enabling password, biometric, or multi-factor authentication when accessing cryptographic keys.
• Using a separate hardware-based signature device.
• All or any combination of the above.