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 automatically verifiable.

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

Introduction

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 automatically verifiable.

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

  1. what a verifiable credential contains,
  2. an ecosystem where verifiable credentials are expected to be useful, and
  3. 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 is capable of containing the same information that a physical credential does and much more because it is not constrained by physical restrictions. The addition of technologies like digital signatures also make verifiable credentials more tamperproof and therefore trustworthy than their physical counterparts. Exchanging verifiable credentials over long distances are also possible through the Internet, making them more convenient when needing to establish trust over long distances.

Ecosystem Overview

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
An entity that is in control of one or more verifiable credentials. Examples of holders include students, employees, and customers.
issuer
An entity that creates a verifiable credential, associates it with a particular subject, and transmits it to a holder. Examples of issuers include corporations, governments, and individuals.
verifier
An entity that receives one or more verifiable credentials for processing. Examples of verifiers include employers, security personnel, and websites.
identifier registry
Mediates the creation and verification of subject identifiers. Examples of identifier registries include corporate employee 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.

Use Cases and Requirements

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 requirements 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

It is currently possible to include multiple subjects in a credential. The terminology above glosses over that fact. The group is debating if the terminology should be modified to include this nuance, or if the nuance would make grasping the basic concepts more difficult.

Core Data Model

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

Claims

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.

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

A credential is set of one or more claims about a subject. It typically includes an identifier to uniquely identify the credential. Credential metadata may also be included to express concepts such as when the credential expires. A digital signature is almost always appended by the issuer of the credential to enable verifiability of the credential. Therefore, a verifiable credential is a set of claims that are tamper-resistant and whose authorship can be cryptographically verified.

The basic components of a verifiable credential.

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

Profiles

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

A verifiable profile is a collection of one or more verifiable credentials typically 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 profile.

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

Basic Concepts

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.
issued
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.
{
  "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",
    "ageOver": 21
  },
  "proof": { ... }
}
        

Proofs (aka Signatures)

A credential MAY be made verifiable by adding the following property:

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.
{
  "id": "http://example.gov/credentials/3732",
  "type": ["Credential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov",
  "issued": "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="
  }
}
        

Expiration

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

expires
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.
{
  "id": "http://dmv.example.gov/credentials/3732",
  "type": ["Credential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "issued": "2010-01-01T19:73:24Z",
  "expires": "2020-01-01T19:73:24Z",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "proof": { ... }
}
        

Status

Credential status information, such as suspension or revocation, may be provided by adding the following property:

credentialStatus
The value of this property MUST be a status scheme that provides enough information to determine the current status of the credential (e.g. suspended, revoked, etc.). The status scheme will vary depending on a variety of factors, such as whether it is simple to implement or privacy-enhancing.
{
  "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",
    "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.

Advanced Concepts

Terms of Use

Terms of use can be utilized by an issuer, subject or a holder to express limitations on the use of information expressed by the Verifiable Credentials Model. The expression of terms of use are performed via the following property:

termsOfUse
The value of this property MUST be one or more terms of use descriptions that provide enough information to a verifier to determine how they may utilize the given information.

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.

{
  "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",
    "ageOver": 21
  },
  "termsOfUse": [{
    "type": "Policy",
    "uid": "http://example.com/policy:8473",
    "profile": "http://example.com/odrl:profile:40",
    "prohibition": [{
      "target": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "action": ["archive"]
    }]
  },
  "proof": { ... }
}
        

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

{
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "credential": [{
    "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",
      "ageOver": 21
    },
    "proof": { ... }
  }],
  "termsOfUse": [{
    "type": "Policy",
    "uid": "http://example.com/policy:4928",
    "profile": "http://example.com/odrl:profile:40",
    "prohibition": [{
      "target": "https://wineonline.example.org/",
      "action": ["correlate"]
    }]
  },
  "proof": [ ... ]
}
        

In the example above, the holder is prohibiting a verifier from using the information provided to correlate the holder.

Evidence

Evidence information for the credential in the Verifiable Credentials Model may be 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 group is currently determining whether or not they should publish a very simple scheme for evidence as a part of this specification.

{
  "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",
    "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": { ... }
}
        

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.

Syntax

Credential

Issuer

Subject

Signatures / Proofs

Expiration

Revocation

Fitness for Purpose

Syntaxes

This section defines how the data model described in Section is realized in each of 3 different languages: JSON, JSON-LD, and WebIDL. Although syntactic mappings are only provided for these three different languages, applications and services may also use any other data representation language (XML, for example) that can support the data model.

JSON

Verifiable Credential

In JSON, an instance of the Verifiable Credential is expressed as a single JSON object whose properties are the verifiable credential's properties, with the following value type assignments:

  • Any number value MUST be represented as a Number type.
  • Any boolean value MUST be represented as a Boolean type.
  • Any sequence value MUST be represented as an Array type.
  • Any unordered set of values MUST be represented as an Array type.
  • Any set of properties MUST be represented as an Object type.
  • Any empty value MUST be represented as a null value.
  • Any other value MUST be represented as a String type.

The following example demonstrates how to express an verifiable credential containing a simple (unverifiable) claim about a particular subject. In this case, the claim is that the subject with the Verifiable Profile id of did:example:ebfeb1f712ebc6f1c276e12ec21 is 21 years of age or older. While a human reading the property ageOver may be able to guess its meaning by its name, no machine-readable semantics for the name are provided. There is information about the claim itself, such as an identifier for the entity that issued it and a date for when it was issued.

{
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", // subject identifier
  "ageOver": 21 // property-value pair
}

The following example demonstrates how to express the same claim about the same subject, but as a verifiable credential. As such, it contains a signature that can be used to verify the author of its contents, including the claim.

{
  "id": "http://example.gov/credentials/3732",
  "type": ["Credential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov",
  "issued": "2010-01-01",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "revocation": {
    "id": "http://example.gov/revocations/738",
    "type": "SimpleRevocationList2017"
  },
  "proof": {
    "type": "LinkedDataSignature2015",
    "created": "2016-06-18T21:19:10Z",
    "creator": "https://example.com/jdoe/keys/1",
    "domain": "json-ld.org",
    "nonce": "598c63d6",
    "signatureValue": "BavEll0/I1zpYw8XNi1bgVg/sCneO4Jugez8RwDg/+
    MCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuFibcC1wps
    PRdW+gGsutPTLzvueMWmFhwYmfIFpbBu95t501+rSLHIEuujM/+PXr9Cky6Ed
    +W3JT24="
  }
}

The following example demonstrates how one could express the same claim about the same subject 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",
  "entityCredential": {
    "@context": "https://w3id.org/security/v1",
    "id": "http://example.gov/credentials/3732",
    "type": ["Credential", "ProofOfAgeCredential"],
    "issuer": "https://dmv.example.gov",
    "issued": "2010-01-01",
    "claim": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "ageOver": 21
    }
  }
}

The following example demonstrates how to express a more complex set of claims about a particular subject as a verifiable credential.

{
  "id": "http://example.gov/credentials/3732",
  "type": ["Credential", "PassportCredential"],
  "name": "Passport",
  "issuer": "https://example.gov",
  "issued": "2010-01-01",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "name": "Alice Bobman",
    "birthDate": "1985-12-14",
    "gender": "female",
    "nationality": {
      "name": "United States"
    },
    "address": {
      "type": "PostalAddress",
      "addressStreet": "372 Sumter Lane",
      "addressLocality": "Blackrock",
      "addressRegion": "Nevada",
      "postalCode": "23784",
      "addressCountry": "US"
    },
    "passport": {
      "type": "Passport",
      "name": "United States Passport",
      "documentId": "123-45-6789",
      "issuer": "https://example.gov",
      "issued": "2010-01-07T01:02:03Z",
      "expires": "2020-01-07T01:02:03Z"
    }
  },
  "proof": {
    "type": "LinkedDataSignature2015",
    "created": "2016-06-21T03:40:19Z",
    "creator": "https://example.com/jdoe/keys/1",
    "domain": "json-ld.org",
    "nonce": "783b4dfa",
    "signatureValue": "Rxj7Kb/tDbGHFAs6ddHjVLsHDiNyYzxs2MPmNG8G47oS06N8i0Dis5mUePIzII4+p/ewcOTjvH7aJxnKEePCO9IrlqaHnO1TfmTut2rvXxE5JNzur0qoNq2yXl+TqUWmDXoHZF+jQ7gCsmYqTWhhsG5ufo9oyqDMzPoCb9ibsNk="
  }
}

Verifiable Profile

In JSON [[!JSON]], an instance of the Verifiable Profile is expressed as a single JSON object whose properties are the verifiable profile's properties, with the following value type assignments:

  • Any number value MUST be represented as a Number type.
  • Any boolean value MUST be represented as a Boolean type.
  • Any sequence value MUST be represented as an Array type.
  • Any unordered set of values MUST be represented as an Array type.
  • Any set of properties MUST be represented as an Object type.
  • Any empty value MUST be represented as a null value.
  • Any other value MUST be represented as a String type.

The following example demonstrates how to express a simple verifiable profile.

{
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "credential": [{
    "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",
      "ageOver": 21
    },
    "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": "pYw8XNi1bgVg/sCneO4BavEll0/I1zJugez8RwDg/+
      ibcC1wpsMCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuF
      zvueMWmFPRdW+gGsutPTLhwYmfIFpbBu95t501+rSLHIEuujM/+PXr+W3JT24
      9Cky6Ed="
    }
  }],
  "proof": [{
    "type": "RsaSignature2018",
    "created": "2017-06-18T21:19:10Z",
    "creator": "did:example:ebfeb1f712ebc6f1c276e12ec21/keys/2",
    "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
    "signatureValue": "BavEll0/I1zpYw8XNi1bgVg/sCneO4Jugez8RwDg/+
    MCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuFibcC1wps
    PRdW+gGsutPTLzvueMWmFhwYmfIFpbBu95t501+rSLHIEuujM/+PXr9Cky6Ed
    +W3JT24="
  }]
}

JSON-LD

JSON-LD [[!JSON-LD]] is a data storage and expression approach called Linked Data. It is a way of expressing information on the Web that is both simple and extensible.

Verifiable Credential

Instances of the Verifiable Credential are expressed in JSON-LD in the same way they are expressed in JSON (Section ), except that there is an additional property @context. Each property of the verifiable credential expression, along with each sub-property within the claim property (such as the generic issuer property or the app-specific ageOver), is given context via the @context value. Other contexts can be used or combined to express any arbitrary information about claims in idiomatic JSON.

The following example demonstrates how to express a simple claim about a particular subject. In this case, the claim is that the subject with the Entity Profile id of did:example:ebfeb1f712ebc6f1c276e12ec21 is 21 years of age or older. While a human reading the property ageOver may be able to guess its meaning by its name, the context maps it to a global identifier (URL) where a document could be retrieved that provides its semantics in a machine-readable data format. There is also information about the verifiable credential itself, such as an identifier for the entity that issued it and a date for when it was issued.

{
  "@context": "https://w3id.org/credentials/v1",
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "ageOver": 21
}

The following example demonstrates how to express the same claim about the same subject, but as a verifiable credential. As such, it contains a signature that can be used to verify its entire contents, including the claim.

{
  "@context": "https://w3id.org/credentials/v1",
  "id": "http://example.gov/credentials/3732",
  "type": ["Credential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov",
  "issued": "2010-01-01",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "proof": {
    "type": "LinkedDataSignature2015",
    "created": "2016-06-18T21:10:38Z",
    "creator": "https://example.com/jdoe/keys/1",
    "domain": "json-ld.org",
    "nonce": "6165d7e8",
    "signatureValue": "g4j9UrpHM4/uu32NlTw0HDaSaYF2sykskfuByD7UbuqEcJIKa+IoLJLrLjqDnMz0adwpBCHWaqqpnd47r0NKZbnJarGYrBFcRTwPQSeqGwac8E2SqjylTBbSGwKZkprEXTywyV7gILlC8a+naA7lBRi4y29FtcUJBTFQq4R5XzI="
  }
}

The following example demonstrates how to express a more complex verifiable credential about a particular subject.

{
  "@context": [
    "http://schema.org",
    "https://w3id.org/credentials/v1"
  ],
  "id": "http://example.gov/credentials/3732",
  "type": ["Credential", "PassportCredential"],
  "name": "Passport",
  "issuer": "https://example.gov",
  "issued": "2010-01-01",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "name": "Alice Bobman",
    "birthDate": "1985-12-14",
    "gender": "female",
    "nationality": {
      "name": "United States"
    },
    "address": {
      "type": "PostalAddress",
      "addressStreet": "372 Sumter Lane",
      "addressLocality": "Blackrock",
      "addressRegion": "Nevada",
      "postalCode": "23784",
      "addressCountry": "US"
    },
    "passport": {
      "type": "Passport",
      "name": "United States Passport",
      "documentId": "123-45-6789",
      "issuer": "https://example.gov",
      "issued": "2010-01-07T01:02:03Z",
      "expires": "2020-01-07T01:02:03Z"
    }
  },
  "proof": {
    "type": "LinkedDataSignature2015",
    "created": "2016-06-21T03:43:29Z",
    "creator": "https://example.com/jdoe/keys/1",
    "domain": "json-ld.org",
    "nonce": "c168dfab",
    "signatureValue": "jz4bEW2FBMDkANyEjiPnrIctucHQCIwxrtzBXt+rVGmYMEflHrOwf7FYLH60E3Oz54VwSSQCi9J4tXQIhv4SofT5opbcIUj7ji6QrC6c+a3YLjg8l/+/uFjhzsLelAO4gh2k0FJxM04ljH0GZGuXTzhRnqTzJTnYSVo72PC92NA="
  }
}

Verifiable Profile

Instances of the Verifiable Profile are expressed in JSON-LD in the same way they are expressed in JSON (Section ), except that there is an additional property @context. Each property of the verifiable profile, such as name or email, is given context via the @context value. Other contexts can be used or combined to express any arbitrary information about an verifiable profile in idiomatic JSON.

The following example demonstrates how to express a simple verifiable profile.

{
  "@context": [
    "http://schema.org",
    "https://w3id.org/credentials/v1"
  ],
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "credential": [{
    "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",
      "ageOver": 21
    },
    "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": "pYw8XNi1bgVg/sCneO4BavEll0/I1zJugez8RwDg/+
      ibcC1wpsMCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuF
      zvueMWmFPRdW+gGsutPTLhwYmfIFpbBu95t501+rSLHIEuujM/+PXr+W3JT24
      9Cky6Ed="
    }
  }],
  "proof": [{
    "type": "RsaSignature2018",
    "created": "2017-06-18T21:19:10Z",
    "creator": "did:example:ebfeb1f712ebc6f1c276e12ec21/keys/2",
    "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
    "signatureValue": "BavEll0/I1zpYw8XNi1bgVg/sCneO4Jugez8RwDg/+
    MCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuFibcC1wps
    PRdW+gGsutPTLzvueMWmFhwYmfIFpbBu95t501+rSLHIEuujM/+PXr9Cky6Ed
    +W3JT24="
  }]
}

The group is currently considering which expressions of the data model should be listed in the spec. WebIDL and XML are two of the expressions that are being considered.

Privacy Considerations

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 pseudo-anonymous 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 pseudo-anonymous 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.

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 of a claim 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.signature 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 preserving 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 claim to a minimal set needed for the expected purposes. One way to avoid placing personally identifiable information in a claim 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 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 claim to the minimum required by potential verifiers for expected use. For verifiers, it means limiting the scope of claims request 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 claim set 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.

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 idproperty that is nested in the claim property. For example, the following Verifiable Credential is a bearer credential:

{
  "id": "http://dmv.example.gov/credentials/temporary/28934792387492384",
  "type": ["Credential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "issued": "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 birth date 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 claim from an issuer, the claim 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 reveals 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 profiles that they transmit.

The group is currently exploring various mechanisms to express the usage policy for the Verifiable Profile. These mechanisms have also been called consent receipts, terms of usage, or DO_NOT_TRACK / DO_NOT_CORRELATE flags.

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 claim is presented to the same verifier more than once – that verifier could infer that the holder is the same individual.
  2. When the same claim 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 claims 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 claim refers to the same subject across presentations or verifiers. Even when different claims are presented, if the subject identifier is the same, verifiers (and those with access to verifier logs) could infer that the holder of the claims is the same person.
  4. When the underlying information in a claim 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 claim to correlate the individual with an existing profile. For example, if a holder presents claims that include zip code, age, and sex, the verifier can potentially correlate the subject of that claim with an established profile [see Sweeney 2000 Simple Demographics Often Identify People Uniquely].
  5. When passing the identifier of a claim to a centralized revocation server – the centralized server can correlate the claim 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 claim 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 claim and never re-use that claim.
  2. If the claim supports revocation, use a globally distributed service for revocation.
  3. Design revocation APIs that do not depend on submitting the ID of the claim, 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 claims 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 claim 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 profile and bind the token to a credit checking agency via a digital signature. The verifier would then wrap the verifiable profile 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 claims 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 claims 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.

Security Considerations

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

The entire data model described in this specification is 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 profiles. 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.

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 an inspector-verifier, which together would comprise a false claim.

The group is actively discussing appropriate strategies when bundling dependent claims. When a clear set of suggestions has been identified, they will be placed here.

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.

The group is actively discussing appropriate strategies when bundling dependent claims. When a clear set of suggestions has been identified, they will be placed here.

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.