Verifiable Credentials Data Model 1.0

1.1 What is a Verifiable Credential?

This section is non-normative.

In the physical world, a credential might consist of:

• Information related to identifying the subject of the credential (for example, a photo, name, or identification number)
• Information related to the issuing authority (for example, a city government, national agency, or certification body)
• Information related to the type of credential this is (for example, a Dutch passport, an American driving license, or a health insurance card)
• Information related to specific attributes or properties being asserted by the issuing authority about the subject (for example, nationality, the classes of vehicle entitled to drive, or date of birth)
• Evidence related to how the credential was derived
• Information related to constraints on the credential (for example, expiration date, terms of use).

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 verifiable presentations and then share these verifiable 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 § 7. 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.

1.2 Ecosystem Overview

This section is non-normative.

This section describes the roles of the core actors and the relationships between them in an ecosystem where verifiable credentials are expected to be useful. A role is an abstraction that might be implemented in many different ways. The separation of roles suggests likely interfaces and protocols for standardization. The following roles are introduced in this specification:

holder

A role an entity might perform by possessing one or more verifiable credentials and generating verifiable presentations from them. Example holders include students, employees, and customers.

issuer

A role an entity performs by asserting claims about one or more subjects, creating a verifiable credential from these claims, and transmitting the verifiable credential to a holder. Example issuers include corporations, non-profit organizations, trade associations, governments, and individuals.

subject

An entity about which claims are made. Example subjects include human beings, animals, and things. In many cases the holder of a verifiable credential is the subject, but in certain cases it is not. For example, a parent (the holder) might hold the verifiable credentials of a child (the subject), or a pet owner (the holder) might hold the verifiable credentials of their pet (the subject). For more information about these special cases, see Appendix § B. Subject-Holder Relationships.

verifier

A role an entity performs by receiving one or more verifiable credentials, optionally inside a verifiable presentation, for processing. Example verifiers include employers, security personnel, and websites.

verifiable data registry

A role a system might perform by mediating the creation and verification of identifiers, keys, and other relevant data, such as verifiable credential schemas, revocation registries, issuer public keys, and so on, which might be required to use verifiable credentials. Some configurations might require correlatable identifiers for subjects. Example verifiable data registries include trusted databases, decentralized databases, government ID databases, and distributed ledgers. Often there is more than one type of verifiable data registry utilized in an ecosystem.

1.3 Use Cases and Requirements

This section is non-normative.

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

• A more thorough explanation of the roles introduced above
• The needs identified in market verticals, such as education, finance, healthcare, retail, professional licensing, and government
• Common tasks performed by the roles in the ecosystem, as well as their associated requirements
• Common sequences and flows identified by the Working Group.

As a result of documenting and analyzing the use cases document, the following desirable ecosystem characteristics were identified for this specification:

• Verifiable credentials represent statements made by an issuer in a tamper-evident and privacy-respecting manner.
• Holders assemble collections of verifiable credentials from different issuers into a single artifact, a verifiable presentation.
• Issuers can issue verifiable credentials about any subject.
• Acting as issuer, holder, or verifier requires neither registration nor approval by any authority, as the trust involved is bilateral between parties.
• Verifiable presentations allow any verifier to verify the authenticity of verifiable credentials from any issuer.
• Holders can receive verifiable credentials from anyone.
• Holders can interact with any issuer and any verifier through any user agent.
• Holders can share verifiable presentations, which can then be verified without revealing the identity of the verifier to the issuer.
• Holders can store verifiable credentials in any location, without affecting their verifiability and without the issuer knowing anything about where they are stored or when they are accessed.
• Holders can present verifiable presentations to any verifier without affecting authenticity of the claims and without revealing that action to the issuer.
• A verifier can verify verifiable presentations from any holder, containing proofs of claims from any issuer.
• Verification should not depend on direct interactions between issuers and verifiers.
• Verification should not reveal the identity of the verifier to any issuer.
• The specification must provide a means for issuers to issue verifiable credentials that support selective disclosure, without requiring all conformant software to support that feature.
• Issuers can issue verifiable credentials that support selective disclosure.
• If a single verifiable credential supports selective disclosure, then holders can present proofs of claims without revealing the entire verifiable credential.
• Verifiable presentations can either disclose the attributes of a verifiable credential, or satisfy derived predicates requested by the verifier. Derived predicates are Boolean conditions, such as greater than, less than, equal to, is in set, and so on.
• Issuers can issue revocable verifiable credentials.
• Verifiable credentials and verifiable presentations have to be serializable in one or more machine-readable data formats. The process of serialization and/or de-serialization has to be deterministic, bi-directional, and lossless. Any serialization of a verifiable credential or verifiable presentation needs to be transformable to the generic data model defined in this document in a deterministic process such that the resulting verifiable credential can be processed in an interoperable fashion. The serialized form also needs to be able to be generated from the data model without loss of data or content.
• The data model and serialization must be extendable with minimal coordination.
• Revocation by the issuer should not reveal any identifying information about the subject, the holder, the specific verifiable credential, or the verifier.
• Issuers can disclose the revocation reason.
• Issuers revoking verifiable credentials should distinguish between revocation for cryptographic integrity (for example, the signing key is compromised) versus revocation for a status change (for example, the driver’s license is suspended).
• Issuers can provide a service for refreshing a verifiable credential.

3.1 Claims

This section is non-normative.

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

The data model for claims, described in Figure 2 above, is powerful and can be used to express a large variety of statements. For example, whether someone graduated from a particular university can be expressed as shown in Figure 3 below.

Individual claims can be merged together to express a graph of information about a subject. The example shown in Figure 4 below extends the previous claim by adding the claims that Pat knows Sam and that Sam is employed as a professor.

To this point, the concepts of a claim and a graph of information are introduced. To be able to trust claims, more information must be added.

3.2 Credentials

This section is non-normative.

A credential is a set of one or more claims made by the same entity. Credentials might also include an identifier and metadata to describe properties of the credential, such as the issuer, the expiry date and time, a representative image, a public key to use for verification purposes, the revocation mechanism, and so on. The metadata might be signed by the issuer. A verifiable credential is a set of tamper-evident claims and metadata that cryptographically prove who issued it.

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

Figure 5 above shows the basic components of a verifiable credential, but abstracts the details about how claims are organized into information graphs, which are then organized into verifiable credentials. Figure 6 below shows a more complete depiction of a verifiable credential, which is normally composed of at least two information graphs. The first graph expresses the verifiable credential itself, which contains credential metadata and claims. The second graph expresses the digital proof, which is usually a digital signature.

3.3 Presentations

This section is non-normative.

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

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

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

Figure 7 above shows the components of a verifiable presentation, but abstracts the details about how verifiable credentials are organized into information graphs, which are then organized into verifiable presentations. Figure 8 below shows a more complete depiction of a verifiable presentation, which is normally composed of at least four information graphs. The first graph expresses the verifiable presentation itself, which contains presentation metadata. The verifiablePresentation property in the graph refers to one or more verifiable credentials (each a self-contained graph), which in turn contains credential metadata and claims. The third graph expresses the credential graph proof, which is usually a digital signature. The fourth graph expresses the presentation graph proof, which is usually a digital signature.

3.4 Concrete Lifecycle Example

This section is non-normative.

The previous sections introduced the concepts of claims, verifiable credentials, and verifiable presentations using graphical depictions. This section provides a concrete set of simple but complete lifecycle examples of the data model expressed in one of the concrete syntaxes supported by this specification. The lifecycle of credentials and presentations in the Verifiable Credentials Ecosystem often take a common path:

1. Issuance of one or more verifiable credentials.
2. Storage of verifiable credentials in a credential repository (such as a digital wallet).
3. Composition of verifiable credentials into a verifiable presentation for verifiers.
4. Verification of the verifiable presentation by the verifier.

We will use concrete examples to illustrate the lifecycle above by demonstrating how to redeem an alumni discount from a university. In the example below, Pat receives an alumni verifiable credential from a university that will be stored in Pat's digital wallet.

{
  // set the context, which establishes the special terms we will be using
  // such as 'issuer' and 'alumniOf'.
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  // specify the identifier for the credential
  "id": "http://example.edu/credentials/1872",
  // the credential types, which declare what data to expect in the credential
  "type": ["VerifiableCredential", "AlumniCredential"],
  // the entity that issued the credential
  "issuer": "https://example.edu/issuers/565049",
  // when the credential was issued
  "issuanceDate": "2010-01-01T19:73:24Z",
  // claims about the subjects of the credential
  "credentialSubject": {
    // identifier for the only subject of the credential
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    // assertion about the only subject of the credential
    "alumniOf": {
      "id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
      "name": [{
        "value": "Example University",
        "lang": "en"
      }, {
        "value": "Exemple d'Université",
        "lang": "fr"
      }]
    }
  },
  // digital proof that makes the credential tamper-evident
  // see the NOTE at end of this section for more detail
  "proof": {
    // the cryptographic signature suite that was used to generate the signature
    "type": "RsaSignature2018",
    // the date the signature was created
    "created": "2017-06-18T21:19:10Z",
    // purpose of this proof
    "proofPurpose": "assertionMethod",
    // the identifier of the public key that can verify the signature
    "verificationMethod": "https://example.edu/issuers/keys/1",
    // the digital signature value
    "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X
      sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc
      X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj
      PAYuNzVBAh4vGHSrQyHUdBBPM"
  }
}

Pat then presents the alumni verifiable credential shown above to receive a discount. The verifier, a ticket sales system, states that any alumni of "Example University" receives a discount on season tickets to sporting events. Using a mobile device, Pat starts the process of purchasing a season ticket. A step in the process requests an alumni verifiable credential and the request is routed to Pat's digital wallet. The digital wallet asks Pat if they would like to provide the previously issued verifiable credential. Pat selects the verifiable credential, which is then composed into a verifiable presentation. The verifiable presentation is then sent to the verifier and verified.

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "type": ["VerifiablePresentation", "CredentialManagerPresentation"],
  // the verifiable credential issued in the previous example
  "verifiableCredential": [{
    "id": "http://example.edu/credentials/1872",
    "type": ["VerifiableCredential", "AlumniCredential"],
    "issuer": "https://example.edu/issuers/565049",
    "issuanceDate": "2010-01-01T19:73:24Z",
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "alumniOf": {
        "id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
        "name": [{
          "value": "Example University",
          "lang": "en"
        }, {
          "value": "Exemple d'Université",
          "lang": "fr"
        }]
      }
    },
    "proof": {
      "type": "RsaSignature2018",
      "created": "2017-06-18T21:19:10Z",
      "proofPurpose": "assertionMethod",
      "verificationMethod": "https://example.edu/issuers/keys/1",
      "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X
        sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc
        X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj
        PAYuNzVBAh4vGHSrQyHUdBBPM"
    }
  }],
  // digital signature by Pat on the presentation
  // protects against replay attacks
  "proof": {
    "type": "RsaSignature2018",
    "created": "2018-09-14T21:19:10Z",
    "proofPurpose": "authentication",
    "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1",
    // 'challenge' and 'domain' protect against replay attacks
    "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
    "domain": "4jt78h47fh47",
    "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..kTCYt5
      XsITJX1CxPCT8yAV-TVIw5WEuts01mq-pQy7UJiN5mgREEMGlv50aqzpqh4Qq_PbChOMqs
      LfRoPsnsgxD-WUcX16dUOqV0G_zS245-kronKb78cPktb3rk-BuQy72IFLN25DYuNzVBAh
      4vGHSrQyHUGlcTwLtjPAnKb78"
  }
}

7.1 Spectrum of Privacy

This section is non-normative.

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.

7.2 Personally Identifiable Information

This section is non-normative.

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 verifiable credentials when possible. For example, issuing ageOver verifiable credentials instead of date of birth verifiable credentials when a verifier wants to determine if an entity is over the age of 18.

Because a verifiable credential often contains PII, implementers are strongly advised to use mechanisms while storing and transporting verifiable credentials that protect the data from those who should not access it. Mechanisms that could be considered include TLS or other means of encrypting the data while it is being transported, as well as encryption or data access control mechanisms to protect the data in a verifiable credential while at rest.

7.3 Identifier-Based Correlation

This section is non-normative.

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 verifiable credential schemes that allow hiding the identifier during verifiable 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 verifiable 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.

7.4 Signature-Based Correlation

This section is non-normative.

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 verificationMethod, created, proofPurpose, and jws 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.

7.5 Long-Lived Identifier-Based Correlation

This section is non-normative.

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, verifiable credential-specific JSON-LD contexts, and many other sorts of long-lived identifiers.

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

7.6 Device Fingerprinting

This section is non-normative.

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.

7.7 Favor Abstract Claims

This section is non-normative.

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 verifiable credential claiming that subjects have met that requirement instead of offering verifiable credentials containing claims about specific birthdates. This enables individual customers to make purchases without revealing specific personally identifiable information.

7.8 The Principle of Data Minimization

This section is non-normative.

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 verifiable 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 verifiable credential containing every attribute that appears on a driver's license, as well as a set of verifiable credentials where every verifiable credential contains only a single attribute such as a person's birthday. It could also issue more abstract verifiable credentials (for example, a verifiable 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 verifiable 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.

7.9 Bearer Credentials

This section is non-normative.

A bearer credential is a privacy-enhancing piece of information, such as a concert ticket, which entitles the holder of the bearer credential to a specific resource without divulging sensitive information about the holder. Bearer credentials are often used in low-risk use cases where the sharing of the bearer credential is not a concern or would not result in large economic or reputational losses.

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://www.w3.org/2018/credentials/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 and Arts"
    }
  },
  "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 bearer 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 bearer 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.

7.10 Validity Checks

This section is non-normative.

When processing verifiable credentials, verifiers are expected to perform many of the checks listed in Appendix § A. Validation as well as a variety of specific business process checks. 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 such as 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.

7.11 Storage Providers and Data Mining

This section is non-normative.

When a holder receives a verifiable credential from an issuer, the verifiable 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.

Some effective mitigations for data mining and profiling include using:

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

7.12 Aggregation of Credentials

This section is non-normative.

Holding two pieces of information about the same subject almost always reveals more about the subject than just the sum of the two pieces, even when the information is delivered through different channels. The aggregation of verifiable 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 as well as age-related information for that 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 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 tends 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.

7.13 Usage Patterns

This section is non-normative.

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 verifiable credential is presented to the same verifier more than once. The verifier could infer that the holder is the same individual.
• The same verifiable credential is presented to different verifiers, and either those verifiers collude or a third party has access to transaction records from both verifiers. An observant party could infer that the individual presenting the verifiable 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. The centralized server can correlate the credential usage across interactions. For example, if a 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 credentials.

7.14 Sharing Information with the Wrong Party

This section is non-normative.

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.

7.15 Frequency of Claim Issuance

This section is non-normative.

As detailed in Section § 7.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 verifiable credentials short lived and renewal automatic.

For example, an ageOver verifiable credential is useful for gaining access to a bar. If an issuer issues such a verifiable 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.

7.16 Prefer Single-Use Credentials

This section is non-normative.

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 verifiable credentials whenever possible.

Using single-use verifiable credentials provides several benefits. The first benefit is to verifiers who can be sure that the data in a verifiable credential is fresh. The second benefit is to holders, who know that if there are no long-lived identifiers in the verifiable credential, the verifiable 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.

7.17 Private Browsing

This section is non-normative.

In an ideal private browsing scenario, no personally identifiable information will be revealed. Because many credentials include personally identifiable information, organizations providing software to holders should warn them about the possibility of revealing this information if they wish to use credentials and presentations while in private browsing mode. As each browser vendor handles private browsing differently, and some browsers might not have this feature at all, it is important for implementers to be aware of these differences and implement solutions accordingly.

8.1 Cryptography Suites and Libraries

This section is non-normative.

Some aspects of the data model described in this specification can be protected through the use of cryptography. It is important for implementers to understand the cryptography suites and libraries used to create and process credentials and presentations. Implementing and auditing cryptography systems generally requires substantial experience. Effective red teaming can also help 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 need to take this into account and ensure mechanisms exist to easily and proactively upgrade expired or broken cryptography suites and libraries, and to invalidate and replace existing credentials. Regular monitoring is important to ensure the long term viability of systems processing credentials.

8.2 Content Integrity Protection

This section is non-normative.

Verifiable credentials often contain URLs to data that resides outside of the verifiable credential itself. Linked content that exists outside a verifiable credential, such as 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://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/58473",
  "type": ["VerifiableCredential", "AlumniCredential"],
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "image": "https://example.edu/images/58473",
    "alumniOf": {
      "id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
      "name": [{
        "value": "Example University",
        "lang": "en"
      }, {
        "value": "Exemple d'Université",
        "lang": "fr"
      }]
    }
  },
  "proof": { ... }
}

While this specification does not recommend any specific content integrity protection, document authors who want to ensure 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 [IPFS]. The example below transforms the previous example 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://www.w3.org/2018/credentials/examples/v1?hl=z8guWNzUBnZBu3aq31"
  ],
  "id": "http://example.edu/credentials/58473",
  "type": ["VerifiableCredential", "AlumniCredential"],
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "image": "ipfs:/ipfs/QmXfrS3pHerg44zzK6QKQj6JDk8H6cMtQS7pdXbohwNQfK/image",
    "alumniOf": {
      "id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
      "name": [{
        "value": "Example University",
        "lang": "en"
      }, {
        "value": "Exemple d'Université",
        "lang": "fr"
      }]
    }
  },
  "proof": { ... }
}

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

8.3 Unsigned Claims

This section is non-normative.

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 be aware that these types of credentials are not verifiable because the authorship either is not known or cannot be trusted.

8.4 Token Binding

This section is non-normative.

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. Approaches such as token binding [RFC8471], which ties the request for a verifiable presentation to the response, can secure the protocol. Any unsecured protocol is susceptible to man-in-the-middle attacks.

8.5 Bundling Dependent Claims

This section is non-normative.

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 verifiable 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 verifiable 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" verifiable credentials to a verifier, which together would comprise a false claim.

8.6 Highly Dynamic Information

This section is non-normative.

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 verifiable credential is valid might create exploitable security vulnerabilities. Expiration periods shorter than the timeframe where the information expressed by the verifiable credential is valid creates a burden on holders and verifiers. It is therefore important to set validity periods for verifiable credentials that are appropriate to the use case and the expected lifetime for the information contained in the verifiable credential.

8.7 Device Theft and Impersonation

This section is non-normative.

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.

9.1 Data First Approaches

This section is non-normative.

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 relying on a viewer's interpretation of 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.

10.1 Language and Base Direction

This section is non-normative.

Data publishers are strongly encouraged to read the section on Cross-Syntax Expression in the Strings on the Web: Language and Direction Metadata document [STRING-META] in order to ensure that the expression of language and/or base direction information is possible across multiple expression syntaxes such as [JSON-LD], [JSON], and CBOR [RFC7049].

The general design pattern is to use the following markup template when expressing a text string that is tagged with a language and, optionally, a specific base direction:

"property": {
  "value": "The string value",
  "lang": "LANGUAGE"
  "dir": "DIRECTION"
}

An example utilizing the design pattern above is shown below to express the title of a book in the English language without specifying a text direction:

"title": {
  "value": "HTML and CSS: Designing and Creating Websites",
  "lang": "en"
}

The next example uses a similar title expressed in the Arabic language with a base direction of right-to-left:

"title": {
  "value": "HTML و CSS: تصميم و إنشاء مواقع الويب",
  "lang": "ar"
  "dir": "rtl"
}

Implementers utilizing JSON-LD are strongly urged to extend the JSON-LD Context defining the internationalized property and utilize the Scoped Context feature of JSON-LD to alias the @value, @language, and @direction keywords to value, lang, and dir, respectively. An example of a JSON-LD Context snippet doing so is shown below:

"title": {
  "@context": {"value": "@value", "lang": "@language", "dir": "@direction"},
  "@id": "https://www.w3.org/2018/credentials/examples#title"
}

10.2 Complex Language Markup

This section is non-normative.

When multiple languages, base directions, and/or annotations are used in a single natural language string, more complex mechanisms are typically required. It is possible to utilize markup languages, such as HTML, to encode text with multiple language and/or base directions. It is also possible to use the rdf:HTML datatype to encode such values accurately in JSON-LD.

Despite that possibility, implementers are strongly discouraged from encoding information as HTML because doing so 1) requires some version of an HTML processor, which increases the burden of processing language and/or base direction information, and 2) increases the security attack surface when utilizing this data model as blindly processing HTML could result in executing a script tag that an attacker injected at some point during the data production process.

If implementers feel that they have to use HTML, or other markup languages that are capable of containing executable scripts, to achieve a particular use case, they are advised to analyze how an attacker would use the markup to mount injection attacks against a consumer of the markup and deploy mitigations for the identified attacks.