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. This specification provides a mechanism
to express these sorts of credentials on the Web in a way that is
cryptographically secure, privacy respecting, and machine verifiable.
Status of This Document
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
General specification reorganization into high-level sections on
Core Data Model, Trust Model, Conformance, Basic Concepts, Advanced
Concepts, and Advanced Examples.
Addition of Accessibility Considerations section.
Detailed diagrams in Core Data Model section to supplement the basic diagrams.
Numerous updates and alignment in the Terminology section.
Addition of Status section in Basic Concepts.
Detailed explanation of how the specification can be extended via the
Extensibility section in the Advanced Concepts section.
Addition of a Data Schemas section in Advanced Concepts.
Addition of a Refreshing section in Advanced Concepts.
Addition of a Mode of Operation section in Advanced Concepts.
Addition of a Terms of Use section in Advanced Concepts.
Addition of an Evidence section in Advanced Concepts.
Addition of a Zero-Knowledge Proofs section in Advanced Concepts as well as a
general rework of the specification to focus on privacy-preserving credentials.
Addition of a section on Subject-Holder Relationships.
Addition of a Disputes section in Advanced Concepts.
Addition of an Authorization section in Advanced Concepts.
Addition of a Syntactic Sugar section in Advanced Concepts.
Addition of a JSON Web Token section in Syntaxes.
This document was published by
the Verifiable Claims Working Group as a
Working Draft.
This document is intended to become a W3C Recommendation.
Publication as a
Working Draft does not imply
endorsement by the W3C Membership.
This is a draft document and may
be updated, replaced or obsoleted
by other documents at any time. It
is inappropriate to cite this
document as other than work in
progress.
This document was produced by
a group
operating under the
W3C Patent Policy.
W3C maintains a
public list of any
patent disclosures
made in connection with the
deliverables of
the group; that page also includes
instructions for disclosing a
patent. An individual who has
actual knowledge of a patent which
the individual believes contains
Essential Claim(s)
must disclose the information in
accordance with
section 6 of the W3C Patent
Policy.
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.
Currently it is difficult to express education qualifications, healthcare
data, financial account details, and other sorts of third-party verified
machine-readable personal information on the Web. The difficulty of expressing
digital credentials on the Web makes it challenging to receive the same
benefits through the Web that physical credentials provide us in the
physical world.
This specification provides a standard way to express credentials on the
Web in a way that is cryptographically secure, privacy-respecting, and
machine-verifiable.
For those unfamiliar with the concepts related to
verifiable credentials, the following sections provide an overview of:
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. The
Privacy Considerations section in this
document outlines and attempts to address a number of these issues. 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:
A role an entity might perform by possessing one or more
verifiable credentials and generating presentations from them.
Example holders include students, employees, and customers.
A role an entity might perform by creating a
verifiable credential, associating it with a specific subject,
and transmitting it to a holder. Example issuers include
corporations, non-profit organizations, trade associations, governments, and
individuals.
A role an entity might perform by requesting and receiving a
verifiable presentation that proves the holder possesses the
required verifiable credentials with certain characteristics. Example
verifiers include employers, security personnel, and websites.
A role a system might perform by mediating the creation and verification of
issuer identifiers, keys, and other relevant data, such as
verifiable credential schemas and revocation registries, 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.
Figure 1
The roles and information flows forming the basis for this specification.
Note
The ecosystem above is provided as an example 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.
1.3 Use Cases and Requirements
This section is non-normative.
The Verifiable Credentials Use Cases [VC-USECASES] document outlines a number
of key topics that readers 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
As a result of documenting and analyzing the use cases document, a number of
desirable ecosystem characteristics were identified for this specification,
specifically:
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.
2. Terminology
This section is non-normative.
The following terms are used to describe concepts in this specification.
A set of one or more claims made by an issuer.
A verifiable credential
is a tamper-evident credential that has authorship that can be
cryptographically verified. Verifiable credentials can be used to build
verifiable presentations, which can also be cryptographically verified.
The claims in a credential can be about different subjects.
decentralized identifier
A portable URL-based identifier, also known as a DID,
associated with an entity. These identifiers are most often used in a
credential and are associated with holders such that a
credential itself can be easily ported from one repository to
another without the need to reissue the credential. An example of a DID
is did:example:123456abcdef.
A verifiable, boolean assertion about the value of another attribute in a
verifiable credential. These are useful in zero-knowledge-proof-style
presentations because they can limit information disclosure. For
example, if a verifiable credential contains an attribute
for expressing a specific height in centimeters, a derived predicate
might reference the height attribute in the credential demonstrating
that issuer attests to a height value meeting the minimum height
requirement, without actually disclosing the specific height value. For example,
the subject is taller than 150 centimeters.
digital signature
A mathematical scheme for demonstrating the authenticity of a digital message.
entity
A thing with distinct and independent existence, such as a person,
organization, concept, or device. An entity can perform one or more roles in
the ecosystem.
graph
A network of information composed of subjects and their relationship
to other subjects or data.
The means for keeping track of entities across contexts. Digital
identities enable tracking and customization of entity interactions
across digital contexts, typically using identifiers and attributes. Unintended
distribution or use of identity information can compromise privacy. Collection
and use of such information should follow the principles of minimal disclosure.
identity provider
An identity provider, sometimes abbreviated as IdP, is a system
for creating, maintaining, and managing identity information for
holders, while providing authentication services to
relying party applications within a federation or distributed network.
In this case the holder is always the subject. Even if the
credentials are bearer credentials, it is assumed they will
remain with the subject, and if they are not, they were stolen by an
attacker. This specification does not use this term unless comparing or mapping
the concepts in this document to other specifications. This specification
decouples the identity provider concept into two distinct concepts: the
issuer and the holder.
Data derived from one or more credentials, issued by one or more
issuers, that is shared with a specific verifier. A
verifiable presentation
is a tamper-evident presentation encoded in such a way that authorship of the
data can be trusted after a process of cryptographic verification. Certain
types of verifiable presentations might contain data that is synthesized from,
but do not contain, the original verifiable credentials (for example,
zero-knowledge proofs).
A role a system might perform by mediating the creation and verification of
subject identifiers, verifiable credential schemas, revocation
registries, issuer public keys, and so on. Some registries, such as ones for
UUIDs and public keys, just act as namespaces for identifiers.
A role an entity might perform by receiving one or more
verifiable presentations for processing. Other specifications might
refer to this concept as a relying party.
3. Core Data Model
This section is non-normative.
The following sections outline core data model concepts, such as
claims, credentials, and presentations, that form the
foundation of this specification.
3.1 Claims
This section is non-normative.
A claim is statement about a subject. A subject is an
entity about which claims can be made. Claims are
expressed using
subject-property-value
relationships.
Figure 2
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
graduated from a particular university can be expressed as shown below.
Figure 3
An example of a basic claim expressing that Pat is an alumni of
"Example University".
These claims can be merged together to express a graph of
information about a subject. The example below extends the previous
graph of information by adding claims stating that Pat knows Sam
and that Sam is employed as a professor.
Figure 4
Multiple claims can be combined to express a more complex graph.
To this point, the concept of a claim and a graph of information
is introduced. To be able to trust claims, more information must be
added.
3.2 Credentials
This section is non-normative.
A credential is set of one or more claims made by the same
entity. Credentials might include an identifier as well as
metadata to describe properties of the credential, such as the
issuer, the expiry time, a representative image, a public key to use
for verification purposes, the revocation mechanism, and so on. This
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.
Figure 5
The basic components of a verifiable credential.
Examples of verifiable credentials include digital employee
identification cards, digital birth certificates, and digital educational
certificates.
Note
Credential identifiers are often used to identify specific instances
of a credential. These identifiers can also be used for correlation. A
holder wanting to minimize correlation MUST use a selective disclosure
scheme that does not reveal the credential identifier.
The example above provides a simple visual describing the components of a
verifiable credential, but abstracts some of the details about how
claims are organized into graphs, which are then organized into
verifiable credentials. The example below attempts to provide a
complete visual depiction of a verifiable credential, which is
normally composed of at least two graphs of information.
The first graph expresses the credential itself, which contains
credential metadata and
claims.
The second graph expresses the
digital proof,
which is usually a digital signature.
Figure 6
A visual depiction of the information graphs associated with a basic verifiable
credential.
Note
It is possible to have a credential, such as a marriage certificate,
containing multiple claims about different subjects that are
not required to be related.
3.3 Presentations
This section is non-normative.
Because this specification takes a privacy-first approach, 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.
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
The basic components of a verifiable presentation.
Examples of different presentations include a person's professional
persona, their online gaming persona, or their home-life persona.
Note
It is possible to have a presentation, such as a business persona,
that draws on multiple credentials about different subjects
that are often, but not required to be, related.
If a presentation supports derived predicates, a claim
about birthdate in a credential can become the basis of proof that at a
given point in time, the age of a subject did or will fall within a
specified interval. Selective disclosure schemes using zero-knowledge proofs
can use claims expressed in this model to prove additional statements
about those claims. For example, a claim specifying a
subject's date of birth can be used as a predicate to prove the
subject's age is within a given range, and therefore prove the
subject qualifies for age-related discounts, without actually revealing
the subject's birthdate. The holder has the flexibility to use
the claim in any way that is applicable to the desired
presentation.
Figure 8
An example of a basic claim expressing that Pat's date of
birth is 2010-01-01T19:23:24Z.
Date encoding would be determined by the schema.
Have been transmitted in a way clearly establishing that the issuer
generated the credential and that the credential was not
tampered with in transit or storage. This trust could be weakened depending
on the risk assessment of the verifier.
The holder trusts the repository to store the credentials
securely, to not release them to anyone other than the holder, and to
not corrupt or lose them while they are in its care.
This trust model differentiates itself from other trust models by ensuring
the:
By decoupling the trust between the identity provider and the
relying party a more flexible and dynamic trust model is created
such that market competition and customer choice is increased.
Readers that would like to learn more about how this trust model interacts
with various threat models studied by the Working Group are urged to read
the Verifiable Credentials Use Cases Document [VC-USECASES].
Note
The data model detailed in this specification does not imply a transitive trust
model, such as that provided by more traditional Certificate Authority trust
models. In the Verifiable Credentials Data Model, a verifier either
directly trusts or does not trust an issuer. While it is possible to
build transitive trust models using the Verifiable Credentials Data Model,
implementers are urged to
learn about the security weaknesses
introduced by
broadly delegating trust
in the manner adopted by Certificate Authority systems.
5. Conformance
As well as sections marked as non-normative, all authoring guidelines,
diagrams, examples, and notes in this specification are non-normative.
Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, RECOMMENDED, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119].
A concrete expression of the data model in this specification is a
conforming document if it complies with the normative statements in
this specification regarding syntax. That is, the content in the
Basic Concepts,
Advanced Concepts, and
Syntaxes sections of this document. For convenience,
normative statements for conforming documents are
often phrased as statements on the syntax used in properties and their
associated values in the document (for example, "MUST be a URI", or
"MUST be a string value of an ISO8601 combined date and time string").
A conforming processor is a software or hardware-based implementation
of the normative statements in this specification regarding the expected
contents of property-value pairs (for example, the content in
Verification). For convenience, normative statements for
conforming processors are often phrased as behavioral statements
regarding the contents of property-value pairs (for example, "MUST NOT be
revoked", or "MUST be in the expected range").
6. Basic Concepts
This section introduces some basic concepts for the specification, in
preparation for advanced concepts later in the document.
6.1 Contexts
When two software systems need to exchange data, they must use terminology and
a protocol that both systems understand. As an analogy, consider how two
people communicate. Both people must use the same language and the words they
use must mean the same thing to each other. This specification uses the
@context property to express the context of a conversation.
@context
The value of the @context property MUST be one or more URIs,
where the value of the first URI is
https://www.w3.org/2018/credentials/v1. If more than one URI is
provided, the URIs MUST be interpreted as an ordered set. It is RECOMMENDED
that dereferencing the URIs results in a document containing machine-readable
information about the context.
The example above uses the base context URI
(https://www.w3.org/2018/credentials/v1) to establish that the
conversation is about a verifiable credential. The second
URI (https://example.com/examples/v1) establishes that the
conversation is about examples.
Note
This document uses the examples context URI
(https://example.com/examples/v1) for the purposes of
demonstrating examples. The examples context URI MUST NOT be used for any
other purpose, such as in pilot or production systems.
The data available at https://www.w3.org/2018/credentials/v1 is a
static document that is never updated and MAY be downloaded and cached. The
associated human-readable vocabulary document for the Verifiable Credentials
Data Model is available at
https://www.w3.org/2018/credentials.
This concept is further expanded on in Section 7.1Extensibility.
6.2 Identifiers
When expressing statements about a specific thing, such as a person, product,
or organization, it is often useful to use some kind of identifier so that
others can express statements about the same thing. Identifiers that others
are expected to use when expressing statements about a specific thing MUST be
expressed using the id property.
Note
Developers should remember that identifiers might be harmful in scenarios
where pseudonymity is required. Developers are encouraged to read
Section 9.11Privacy Considerations carefully when considering
such scenarios. Where privacy is a strong consideration, the id
property may be omitted.
id
The value of the id property MUST be a single URI. It is
RECOMMENDED that dereferencing the URI results in a document containing
machine-readable information about the identifier.
The example above uses two types of identifiers. The first identifier is for
the credential and uses an HTTP-based URL. The second identifier is for
the subject of the credential (the thing the claims are
about) and uses a decentralized identifier, also known as a DID.
Note
As of this publication, DIDs are a new type of identifier that are not
necessary for verifiable credentials to be useful. Specifically,
verifiable credentials do not depend on DIDs and DIDs do
not depend on verifiable credentials. However, it is expected that many
verifiable credentials will use DIDs and that software libraries
implementing this specification will probably need to resolve DIDs.
DID-based URLs are used for expressing identifiers associated with
cryptographic keys and other machine-readable information that is useful when
used in the verifiable credentials ecosystem.
6.3 Types
Software systems that process the kinds of objects specified in this document
use type information to determine whether or not a provided credential
or presentation is appropriate. Type information MUST be expressed
using the type property.
type
The value of the type property MUST be, or map to, one or more
URIs. If more than one URI is provided, the URIs MUST be interpreted as an
unordered set. Syntactic conveniences, such as JSON-LD terms, SHOULD be used
to ease developer usage. It is RECOMMENDED that dereferencing
the URIs results in a document containing machine-readable information about
the type.
A valid evidence type. For example, "type": "DocumentVerification2018"
All credentials, presentations, and encapsulated objects MUST
specify, or be associated with, additional more narrow types (like
ProofOfAgeCredential, for example) so software systems can
process this additional information.
When processing encapsulated objects defined in this specification, (for
example, objects associated with the credentialSubject object
or deeply nested therein), software systems SHOULD use the type
information specified in encapsulating objects higher in the hierarchy.
Specifically, an encapsulating object, such as credential, SHOULD
convey the associated object types so that verifiers can quickly
determine the contents of an associated object based on the encapsulating
object type.
For example, a credential object with the type of
ProofOfAgeCredential, signals to a verifier that the Object
associated with the credentialSubject property contains the
identifier for the:
This enables implementers to rely on values associated with the
type property for verification purposes. The expectation of
types and their associated properties SHOULD be documented in at least a
human-readable specification, and preferably, in an additional machine-readable
representation.
Note
The type system for the Verifiable Credentials Data Model is the same as
for [JSON-LD] and is detailed in
Section 5.4: Specifying the Type
and
Section 8: JSON-LD Grammar.
When using a JSON-LD context (see Section 7.1Extensibility),
this specification aliases the @type keyword to type
to make the JSON-LD documents more easily understood. While application
developers and document authors do not need to understand the specifics of the
JSON-LD type system, implementers of this specification who want to support
interoperable extensibility, do.
6.4 Issuer
Issuer information can be expressed using the following
properties:
issuer
The value of the issuer property MUST be a URI. It is RECOMMENDED
that dereferencing the URI results in a document containing machine-readable
information about the issuer that can be used to verify the information
expressed in the credential.
issuanceDate
The value of the issuanceDate property MUST be a string value of
an [ISO8601] combined date and time string representing the date and
time the credential was issued. Note that this date represents the
earliest date when the information associated with the
credentialSubject property became valid.
The method used for a mathematical proof varies by representation language and
the technology used. For example, if digital signatures are used for the
proof mechanism, the proof 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.
Example 5: Usage of the proof property on a verifiable credential
The group is currently discussing various alignments with the JOSE stack,
specifically JWS and JWK.
6.6 Expiration
Expiration information for a credentialMAY be provided by adding
the following property:
expirationDate
If specified, the value of the expirationDate property MUST be a
string value of an [ISO8601] combined date and time string representing the
date and time the credential ceases to be valid.
Information about the current status of a verifiable credential, such
as whether it is suspended or revoked, MAY be provided using the
credentialStatusproperty.
credentialStatus
If specified, the value of the credentialStatus property MUST
include the:
id property, which MUST be a URL.
type property, which expresses the credential status type
(also referred to as the credential status scheme), which MUST provide
enough information to determine the current status of the credential
(for example, suspended or revoked).
The precise contents of the credential status information is determined
by the specific credentialStatus type definition, and varies
depending on factors such as whether it is simple to implement or if it is
privacy-enhancing.
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 who want to implement credential
status checking.
The contents of the verifiableCredential property shown above are
verifiable credentials as described by this specification. The contents
of the proof property are proofs as described by the
Linked Data Proofs [LD-PROOFS] specification. The id property
is optional and MAY be used to provide a unique identifier for the
presentation. The value associated with the id property MUST be a
URI.
Some zero-knowledge cryptography schemes might enable holders to
indirectly prove they hold a credential without revealing the
credential itself. In these schemes, the original attribute, such as
date of birth, might be translated into another value, such as "over the age
of 15", which is cryptographically asserted such that a verifier can
trust the value if they trust the issuer.
Issue: ZKP-style verifiable presentation
We are currently working on an example of a ZKP-style verifiable presentation
that contains derived data instead of directly embedded verifiable credentials.
One of the goals of the Verifiable Credentials Data Model is to enable
permissionless innovation. To achieve this, the data model needs to be
extensible in a number of different ways. The data model is required to:
Model complex multi-entity relationships through the use of a
graph-based data model.
Extend the machine-readable vocabularies used to describe information in the
data model, without the use of a centralized system for doing so, through the
use of [LINKED-DATA].
Support multiple types of cryptographic proof formats through the use of
Linked Data Proofs [LD-PROOFS], Linked Data Signatures [LD-SIGNATURES],
and a variety of signature suites.
Provide all of the extensibility mechanisms outlined above in a data format
that is popular with software developers and web page authors, and is enabled
through the use of [JSON-LD].
The requirement to support multiple types of machine-readable data formats e.g., JWT is currently not supported.
This approach to data modelling is often called an
open world assumption, meaning that any entity can say anything about
any other entity. While this approach seems to conflict with building simple
and predictable software systems, balancing extensibility with program
correctness is always more challenging with an open world assumption than with
closed software systems.
The rest of this section describes, through a series of examples, how both
extensibility and program correctness are achieved.
The verifiable credential above states that the entity
associated with did:example:abcdef1234567 has a name
with a value of Jane Doe.
Now let us assume that a developer wants to extend the
verifiable credential to store two additional pieces of information: an
internal corporate reference number, and Jane's favorite food.
The first thing to do is to create a JSON-LD context containing two new terms:
After the JSON-LD context is created, the developer must publish it somewhere
so it is accessible to verifiers who will be processing the
verifiable credential. Assuming the above JSON-LD context is published
at https://example.com/contexts/mycontext.jsonld, we can extend
this example by including the context and adding the new properties to the
verifiable credential:
Example 11: A verifiable credential with a custom extension
This example demonstrates extending the Verifiable Credentials Data Model in a
permissionless and decentralized way. The mechanism shown also ensures that
verifiable credentials created in this way provide a mechanism to
prevent namespace conflicts and semantic ambiguity.
A dynamic extensibility model such as this does increase the implementation
burden. Software written for such a system has to determine whether
verifiable credentials with extensions are acceptable based on the
risk profile of the application. Some applications might accept only
certain extensions while highly secure environments might not accept any
extensions. These decisions are up to the developers of these
applications and are specifically not the domain of this specification.
Developers are urged to ensure that extension JSON-LD contexts are highly
available. Implementations that cannot fetch a context will produce an error.
Strategies for ensuring that extension JSON-LD contexts are always available
include using content-addressed URLs for contexts, bundling context documents
with implementations, or enabling aggressive caching of contexts.
7.1.1 Semantic Interoperability
This specification endeavors to enable both the JSON and JSON-LD syntaxes to
be semantically compatible with one another without the JSON implementations
needing to process the documents as JSON-LD. To achieve this, the
specification imposes the following additional restrictions on both syntaxes:
JSON-based processors MUST process the @context property,
ensuring the expected values exist in the expected order for the
credentialtype being processed. The expected order MUST
be defined by at least a human-readable extension specification and
preferably, by a machine-readable specification.
JSON-LD-based processors MUST produce an error when a JSON-LD context
redefines any term in the
active context.
To avoid the possibility of accidentally overriding terms, developers are urged
to scope their extensions. For example, the following extension scopes the
new favoriteFood term so that it can only be used within the
credentialSubject property:
Data schemas are useful when enforcing a specific structure on a given
collection of data. There are at least two types of data schemas that this
specification contemplates:
Data verification schemas, which are used to verify that the structure and
contents of a verifiable credential conform to a published schema.
Data encoding schemas, which are used to map the contents of a
verifiable credential to an alternative representation format, such as a
binary format used in a zero-knowledge proof.
The expression of a data schema can be performed using the following
property:
credentialSchema
The value of the credentialSchema property MUST be one or more
data schemas that provide verifiers with enough information to determine
if the provided data conforms to the provided schema. Each
credentialSchema comprises at least its
type (for example, JsonSchemaValidator2018),
and an id property that MUST be a URI identifying
the schema file. The precise contents of each
data schema is determined by the specific type definition.
Example 13: Usage of the credentialSchema property to perform JSON schema validation
In the example above, the issuer is specifying a
credentialSchema, which points to a JSON schema file that can be
used by a verifier to determine if the verifiable credential is
well formed.
Issue
The group is still exploring how to utilize this feature for ZKPs and will
most likely adjust this section based on implementer feedback.
Data schemas can also be used to specify mappings to other binary formats,
such as those used to perform zero-knowledge proofs.
Example 14: Usage of the credentialSchema property to perform zero-knowledge validation
In the example above, the issuer is specifying a
credentialSchema, which points to a zero-knowledge packed binary
data format that is capable of transforming the input data into a format,
which can then be used by a verifier to determine if the
proof provided with the verifiable credential is valid.
7.3 Refreshing
It is useful for systems to enable the manual or automatic refresh of a
expiredverifiable credential. This
specification enables an issuer to include a link to a refresh service.
A refresh service can be expressed using the following property:
refreshService
The value of the refreshService property MUST be one or more
refresh services that provides enough information to the holder's
software such that the holder can refresh the credential. Each
refreshService property comprises at least its type
(for example, ManualRefreshService2018) and the
serviceEndpoint URL. The precise content of each refresh service
is determined by the specific refreshServicetype
definition.
Example 15: Usage of the refreshService property by an issuer
In the example above, the issuer specifies a manual
refreshService that can be used by directing the holder to
https://dmv.example.gov/refresh/283947.
7.4 Mode of Operation
This section is non-normative.
Section 1.2Ecosystem Overview provided an overview of the
verifiable credential ecosystem. This section provides more detail about
how the ecosystem is envisaged to operate, as follows:
Note
The order of the following steps is not fixed and some steps might be repeated.
The verifier either performs the requested action or rejects the
request.
This specification does not define any protocol for transfering
verifiable credentials or verifiable presentations, but assuming
other specifications do specify how they are transferred between entities, then
this Verifiable Credential Data Model is:
Directly applicable to steps 2, 3, 4, 5, and 6.
Not sufficient on its own for steps 1, 7, and 8 because an authorization
framework is needed as well.
Terms of use can be utilized by an issuer or a
holder to communicate the terms under which a verifiable credential
or verifiable presentation was issued. The issuer places their terms of use inside
the credential before it is converted into a verifiable credential.
The holder places holder terms of use inside a presentation.
Terms of use MAY be expressed using the following property:
termsOfUse
If present, the value of this property MUST specify one or more
terms of use policies under which the creator issued the credential
or presentation. If the recipient (holder or verifier) is not willing
to adhere to the specified terms of use then they do so on their own
responsibility and may incur legal liability if they violate the
stated Terms of Use.
Each termsOfUse comprises its type,
for example, IssuerPolicy, and
optionally its instance id. The precise contents of each term of use is
determined by the specific TermsOfUse type definition.
Issue
The group is currently exploring a variety of ways of expressing the terms of
use associated with a Verifiable Credential, namely, the
Open Digital Rights Language.
A related initiative is the one at Customer Commons.
Example 16: Usage of the termsOfUse property by an issuer
In the example above, the holder, who is also the subject,
has expressed a Term of Use which prohibits the verifier (https://wineonline.example.org)
from using the information provided to correlate the holder/subject
by using a 3rd party service. If the verifier were to use such a 3rd party
service for correlation, they would violate the terms under which the holder
created the presentation.
7.6 Evidence
The evidence property is used by an issuer to represent the
set of evidence that was used to determine whether or not to issue
a credential. For example, an issuer might check physical documentation
provided by the subject or might perform a set of background checks
before issuing the credential. In certain scenarios, this information is useful
to the verifier when determining the risk associated with relying on a
given credential.
Evidence information can be expressed using the following property:
evidence
The value of the evidence property MUST be one or more evidence
schemes providing enough information to a verifier to determine whether
the evidence gathered meets their requirements. The precise content of each
evidence scheme is determined by the specific evidencetype definition.
Issue
The group is currently determining whether or not they should publish a
very simple scheme for evidence as a part of this specification.
The evidence property provides different and complimentary
information to the proof
property. The evidence property is used to express supporting
information, such as documentary evidence, related to the integrity of the
credential. In contrast, the proof property is used to
express machine-verifiable mathematical proofs related to the authenticity of
the issuer and integrity of the credential.
7.7 Zero-Knowledge Proofs
A zero-knowledge proof is a cryptographic method where an entity can prove
to another entity that they know a certain value without disclosing the
actual value. A real world example is proving that an accredited university
has granted a degree to you without revealing your identity or any other
personally identifiable information contained on the degree.
One of the goals of this specification is to provide a data model that enables
multiple different types of zero-knowledge proof mechanisms to be supported.
The examples below highlight how the data model may be utilized to issue,
present, and verify zero-knowledge based verifiable credentials.
The first stage of utilizing zero-knowledge based verifiable credentials
is for the issuer to issue a verifiable credential in a manner
that enables the holder to present the information to a verifier
in a privacy-enhancing manner. There are two requirements that are required of
most verifiable credentials when they are to be used in
zero-knowledge systems:
The verifiable credentialMUST contain a credential definition that
will be used by all parties to perform various zero-knowledge based
cryptographic operations.
The following example describes one way that a verifiable credential
can express the information needed by a Camenisch-Lysyanskaya Zero-Knowledge
Proof system, also known as "CL Signatures".
Example 19: A verifiable credential that supports CL Signatures
The example above provides the credential definition by using the
credentialSchema property and a specific proof that is usable in
the Camenisch-Lysyanskaya Zero-Knowledge Proof system.
All derived verifiable credentialsMUST contain a reference to the
credential definition that was used to generate the derived proof.
All derived proofs in verifiable credentialsMUST NOT leak
information that would enable the verifier to correlate the
holder that is presenting the credential.
Important details regarding the format for the credential definition and of
the proofs have been omitted on purpose as those are outside of the scope of
this document. The purpose of this section is to guide implementers that
desire to extend verifiable credentials and
verifiable presentations to support zero-knowledge proof systems.
7.8 Subject-Holder Relationships
This section describes the possible relationships between a subject
and a holder and how the Verifiable Claims Data Model expresses these
relationships. The following diagram illustrates the different types of
relationships covered in the rest of this section.
Figure 9
Subject-Holder Relationships in Verifiable Credentials.
The following sections describe how each of these relationships are handled in
the data model.
In this case, the credentialSubject property might contain
multiple properties each providing an aspect of the identity of the
subject, which together, unambiguously identify the subject.
Some use cases might not require the holder to be identified at all,
such as checking to see if a doctor (the subject) is board-certified.
Other use cases might require the verifier to use out-of-band knowledge
to determine the relationship between the subject and the holder.
Example 22: A credential uniquely identifying a subject
The mechanisms listed above describe the relationship between the
holder and the subject and helps the verifier decide
whether the relationship is sufficiently expressed for a given use case.
Note
The additional mechanisms the issuer or the verifier uses to
verify the relationship between the subject and the holder are
outside the scope of this specification.
Issue
It is for further study which, if any, of these mechanisms is to be
standardised by the working group.
Example 23: The relationship property in a child's credential
{
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential", "RelationshipCredential"],
"issuer": "https://example.edu/issuers/14",
"issued": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"ageUnder": 16,
"parent": {
"id": "did:example:ebfeb1c276e12ec211f712ebc6f",
"type": "Mother"
}
},
"proof": { ... } // the proof is generated by the DMV
}
In the example above, the issuer expresses the relationship between the
child and the parent such that a verifier would most likely accept the
credential if it is provided by the child or the parent.
Example 24: A relationship credential issued to a parent
{
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "RelationshipCredential"],
"issuer": "https://example.edu/issuers/14",
"issued": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1c276e12ec211f712ebc6f",
"child": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"type": ["Person", "Child"]
}
},
"proof": { ... } // the proof is generated by the DMV
}
In the example above, the issuer expresses the relationship between the
child and the parent in a separate credential such that a
verifier would most likely accept any of the child's credentials
if they are provided by the child or if the credential above is
provided with any of the child's credentials.
Example 25: A relationship credential issued by a child
{
"id": "http://example.org/credentials/23894",
"type": ["VerifiableCredential", "RelationshipCredential"],
"issuer": "http://example.org/credentials/23894",
"issued": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"parent": {
"id": "did:example:ebfeb1c276e12ec211f712ebc6f",
"type": "Mother"
}
},
"proof": { ... } // the proof is generated by the child
}
In the example above, the child expresses the relationship between the
child and the parent in a separate credential such that a
verifier would most likely accept any of the child's credentials
if the credential above is provided.
Similarly, the strategies described in the examples above can be used for many
other types of use cases, including power of attorney, pet ownership, and
patient prescription pickup.
Verifiable credentials are not an authorization framework and therefore delegation
is out of scope for this specification. However, it is understood that Verifiable
Credentials are likely to be used to build authorization and delegation systems.
The following is one approach that may be appropriate for some use cases.
When the issuer wishes to authorise a holder to possess a credential that
describes a subject who is not the holder, and the holder has no known relationship
with the subject, then the issuer may insert the
relationship of the holder to itself into the subject's credential.
Example 26: A credential issued to a
holder who is not the subject of the credential, who has no relationship with
the subject of the credential, but who has a relationship with the issuer
7.8.6 Holder Acts on Behalf of the Verifier, or has no Relationship with
the Subject, Issuer, or Verifier
The Verifiable Credentials Data Model currently does not support either of
these scenarios. It is for further study how they might be supported.
7.9 Disputes
There are at least two different cases to consider for an entity
wanting to dispute a credential issued by an issuer:
A subject disputes a claim made by the issuer. For example, the
address property is incorrect or out of date.
An entity disputes a potentially false claim made by the issuer
about a different subject. For example, an imposter claims the social
security number for an entity.
Only the subject of a verifiable credential is entitled to issue
a DisputeCredential. A DisputeCredential issued by
anyone other than the subjectSHOULD be disregarded by the
verifier, unless the verifier has some other way of determining
the truth of the dispute. This is to prevent denial of service attacks whereby
an attacker falsely disputes a true claim.
The mechanism for issuing a DisputeCredential is the same as
for a regular credential except that the credentialSubject
identifier in the DisputeCredential property is the identifier of
the disputed credential.
For example, if a credential with an identifier of
https://example.org/credentials/245 is disputed, an entity
can issue one of the credentials shown below. In the first example, the
subject might present this to the verifier along with the
disputed credential. In the second example, the entity might
publish the DisputeCredential in a public venue to make it known
that the credential is disputed.
If a credential does not have an identifier, a content-addressed
identifier can be used to identify the disputed credential. Similarly,
content-addressed identifiers can be used to uniquely identify individual
claims.
Issue
The group is currently exploring whether the specification of a vocabulary
term to express content-based identifiers for claims is within scope as well
as the specific vocabulary terms for disputed claims.
7.10 Authorization
Verifiable credentials are intended as a means of reliably identifying
subjects. While it is recognized that Role Based Access Controls (RBAC) and
Attribute Based Access Controls (ABAC) rely on this identification as a means
of authorizing subjects to access resources, this specification
MUST NOT be used for authorization purposes without an accompanying
authorization framework.
The Working Group did consider authorization use cases during the creation of
this specification and is pursuing that work as an architectural layer built
on top of this specification.
7.11 Syntactic Sugar
In general, the data model and syntaxes described in this document are
designed such that developers can copy and paste examples to incorporate
verifiable credentials into their software systems. The design goal of
this approach is to provide a low barrier to entry while still ensuring global
interoperability between a heterogeneous set of software systems. This section
describes some of these approaches, which will most likely go unnoticed by most
developers, but whose details will be of interest to implementers. The most
noteworthy syntactic sugars used throughout the ecosystem are as follows:
If processed using a JSON-LD processor:
The @id and @type keywords are aliased to
id and type respectively, enabling developers to use
this specification as idiomatic JSON.
Data types, such as integers, dates, units of measure, and URLs, are
automatically typed to provide stronger type guarantees for use cases that
require them.
The verifiableCredential and proof properties are
treated as graph containers. That is, mechanisms used to isolate sets
of data asserted by different entities. This ensures, for example, proper
cryptographic separation between the data graph provided by each issuer
and the one provided by the holder presenting the
verifiable credential to ensure the provenance of the information for
each graph is preserved.
8. Syntaxes
Many of the concepts in this document were introduced by example using the
JSON syntax. This section formalizes how the data model (described in Sections
3.Core Data Model, 6.Basic Concepts, and
7.Advanced Concepts) is realized in JSON and JSON-LD. Although
syntactic mappings are provided for these two syntaxes only, applications and
services can use any other data representation syntax,
such as XML, YAML, or CBOR, that is capable of expressing the data model.
8.1 JSON
The data model as described in Section 3.Core Data Model can be
encoded in Javascript Object Notation (JSON) [RFC8259] by mapping property
values to JSON types as follows:
Numeric values representable as IEEE754 SHOULD be represented as a Number type.
Boolean values SHOULD be represented as a Boolean type.
Sequence value SHOULD be represented as an Array type.
Unordered sets of values SHOULD be represented as an Array type.
Sets of propertiesSHOULD be represented as an Object type.
Empty values SHOULD be represented as a null value.
Other values MUST be represented as a String type.
8.2 JSON-LD
[JSON-LD] is a JSON-based format used to serialize
Linked Data.
The syntax is designed to easily integrate into deployed systems already using
JSON, and provides a smooth upgrade path from JSON to JSON-LD. It is primarily
intended to be a way to use Linked Data in Web-based programming environments,
to build interoperable Web services, and to store Linked Data in JSON-based
storage engines.
JSON-LD is useful when extending the data model described in this
specification. Instances of the data model are encoded in JSON-LD in the same
way they are encoded in JSON (Section 8.1JSON), with the addition
of the @context property. The
JSON-LD Context
is described in detail in the [JSON-LD] specification and its use is
elaborated on in Section 7.1Extensibility.
Multiple contexts MAY be used or combined to express any arbitrary information
about credentials in idiomatic JSON. If an application is processing a
verifiable credential or verifiable presentation, and a
@context property is not present at the top-level of the JSON-LD
document, then a @context property with a value of
https://www.w3.org/2018/credentials/v1MUST be assumed. The JSON-LD
Context available at https://www.w3.org/2018/credentials/v1 is a
static document that is never updated and can therefore be downloaded and
cached client side. The associated vocabulary document for the Verifiable
Credentials Data Model is available at
https://www.w3.org/2018/credentials.
8.3 JSON Web Token
JSON Web Token (JWT) [RFC7519] is still a widely used means to express
claims to be transferred between two parties. Providing a representation of the
Verifiable Credentials Data Model for JWT allows existing systems and libraries
to participate in the ecosystem described in Section
1.2Ecosystem Overview. A JWT encodes a set of claims as a JSON
object that is contained in a JSON Web Signature (JWS) [RFC7515] or JWE
[RFC7516]. For this specification, the use of JWE is out of scope.
8.3.1 Relation to the Verifiable Credentials Data Model
This specification defines encoding rules of the Verifiable Credential Data
Model onto JWT and JWS. It further defines processing rules how and when to
make use of specific JWT registered claim names and specific JWS registered
header parameter names to allow systems based on JWT to comply with this
specification. If these specific claim names and header parameters are
present, their respective counterpart in the verifiable credential and
verifiable presentationMAY be omitted to avoid duplication.
8.3.2 IANA Considerations
This specification introduces two new registered claim names, which contain the
JSON or JSON-LD verifiable credentials and
verifiable presentation object enclosed in the JWT payload:
If no JWS is present, a proof property MUST be provided. The proof
property can be used to represent more complex proofs, for example if the
creator is different from the issuer, or a proof not based
on digital signatures, such as proof of work. The issuerMAY include
both a JWS and a proof property. For backward compatibility
reasons, the issuer MUST use JWS to represent proofs based on a digital
signature.
The following defines rules for JOSE headers in the context of this
specification:
algMUST be used for RSA and ECDSA based digital signatures. If
only the proof attribute is used, the alg header MUST
be set to none.
kidMAY be used if there are multiple keys associated with the
issuer of the JWT. The key discovery is out of the scope of this
specification. For example, the kid can refer to a key in a DID
Document, or can be the identifier of a key inside a JWKS.
typMUST be set to JWT if present.
For backward compatibility with JWT processors the following JWT registered
claim names MUST be used instead of, or in addition to, their respective
verifiable credential counterparts:
expMUST represent expirationDate, encoded as a UNIX
timestamp (NumericDate).
issMUST represent the issuer property.
iatMUST represent issuanceDate, encoded as a UNIX
timestamp (NumericDate).
In the example above, the VC uses a proof based on JWS digital signatures, and the corresponding verification key can be obtained using the kid header parameter.
Example 30: JWT payload of a JWT-based verifiable credential using JWS as a proof (non-normative)
In the example above, vc does not contain the id property as the JWT encoding uses
the jti attribute to represent a unique identifier. The sub attribute encodes
the information represented by the id property of credentialSubject.
Example 31: Verifiable credential using JWT compact serialization (non-normative)
In the example above, the verifiable presentation uses a proof based on JWS digital signatures,
and the corresponding verification key can be obtained using the kid header parameter.
Example 33: JWT payload of a JWT based verifiable presentation (non-normative)
In the example above, vp does not contain the id property as the JWT encoding uses
the jti attribute to represent a unique identifier. verifiableCredential contains an Array
of Strings of verifiable credentials using JWT compact serialization.
Example 34: Verifiable presentation using JWT compact serialization (non-normative)
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 Verifiable Claims Model
and Security Considerations section of this document.
9. Verification
This section describes a number of checks required to verify a
credential. Some checks are essential for all
verifiable credentials, while other checks are applicable to only some
credentials.
The group is currently discussing whether a mechanism should be provided
that enables linkages to JSON Schema or other optional verification mechanisms.
9.1 Syntax
The document is syntactically valid. For example, syntactically valid JSON or
JSON-LD.
9.2 Credential
Required properties MUST be present. For example, for a
verifiable credential, type and proof
properties are required.
Property values MUST match expectations described in this specification. For
example, the document type property for a
verifiable credentialMUST contain the
VerifiableCredential class.
9.3 Issuer
The value associated with the issuer property MUST identify an
issuer that is known to and trusted by the verifier.
Pertinent metadata about the issuer property MUST be available to
the verifier. For example, an issuer can publish information
containing the public keys it uses to digitally sign
verifiable credentials that it has issued. This metadata is pertinent
when checking the proofs on the verifiable credential.
9.4 Subject
The value associated with the id property for each
credentialSubjectMUST identify a subject to the
verifier. For example, if a subject is identified and the
verifier has public key metadata related to the subject that is
used for authentication purposes, the verifier MAY be able to authenticate the
subject using a signature generated by the subject contained in
the verifiable presentation.
The group is currently discussing how authentication and WebAuthn may work.
Note
The id property is optional. VerifiersMAY use other
properties in a credential to uniquely identify a subject.
9.5 Proofs (Signatures)
The cryptographic mechanism used to prove that the information in a
verifiable credential or a verifiable presentation has not been
tampered with is called a proof. There are many types of
cryptographic proofs including, but not limited to, digital signatures,
zero-knowledge proofs, proofs of work, and proofs of stake. In general, when
verifying proofs implementations MUST ensure that:
The proof is available in the form of a known proof suite.
All required proof suite properties are present.
The proof suite verification algorithm, when applied to the data, results in an
acceptable proof.
Some proofs are digital signatures. In general, when verifying digital
signatures, implementations MUST ensure that:
Acceptably recent metadata regarding the public key associated with the
signature is available. For example, the metadata might include properties
related to expiration, key owner, or key purpose.
The key MUST NOT be revoked or expired.
The cryptographic signature MUST verify.
If the cryptographic suite expects a proofPurpose property, it
MUST exist and be a valid value (such as credentialIssuance) as
per the cryptographic suite.
Note
The digital signature provides a number of protections, other than tamper
resistance, that are not immediately obvious. For example, a Linked Data
Signature created property establishes a date and time before
which the credentialSHOULD NOT be considered verified. The
creator property enables the ability to dynamically discover
information about the entity who created the data to ensure that the
public key is not revoked or expired. The proofPurpose property
ensures the reason the entity created the signature, such as for
authentication or creating a verifiable credential, is clear and
protected in the signature.
9.6 Issuance
The issuanceDateMUST be within an expected range for the
verifier. For example, a verifier can ensure that the issuance
date of a verifiable credential is not in the future.
9.7 Expiration
The expirationDateMUST be within an expected range for the
verifier. For example, a verifier can ensure that the expiration
date of a verifiable credential is not in the past.
9.8 Revocation
If revocation instructions are present, the credentialMUST NOT
have been revoked.
9.9 Fitness for Purpose
The custom properties in the credential are
appropriate for the verifier's purpose. For example if a
verifier needs to determine that a subject is older than 21
years of age, they may rely on claims of a specific
birthdate or abstract properties such as
ageOver.
The issuer is trusted by the verifier to make the
claims at hand. For example, a franchised Fast Food restaurant
location will trust discount coupon claims made by the
corporate headquarters of the franchise.
Policy information expressed by the issuer
in the verifiable credentialSHOULD be respected by holders
and verifiers unless they accept the liability of ignoring the policy.
9.10 Accessibility Considerations
This section is non-normative.
There are a number of accessibility considerations implementers should be
aware of when processing data described in this specification. As with any web
standards or protocols implementation, ignoring accessibility issues makes
this information unusable to a large subset of the population. It is important
to follow accessibility guidelines and standards, such as [WCAG21], to ensure
all people, regardless of ability, can make use of this data. This is
especially important when establishing systems that utilize cryptography and
encryption, which historically, have created problems for assistive
technologies.
This section details the general accessibility considerations to take into
account when utilizing this data model.
9.10.1 Data First Approaches
Many physical credentials in use today, such as government identification
cards, have poor accessibility characteristics, including, but not limited to,
small print, reliance on small and high-resolution images, and no affordances
for people with vision impairments.
When utilizing this data model to create verifiable credentials, it is
suggested that data model designers use a data first approach. For example,
given the choice of using data or a graphical image to depict a
credential, designers should choose to express every element of the
image, such as the name of an institution or the professional credential, in a
machine readable way instead of just relying on the image to convey this
information. Using a data first approach is preferred because it provides the
foundational elements of building different interfaces for people with varying
abilities.
9.11 Privacy Considerations
This section is non-normative.
This section details the general privacy considerations and specific privacy
implications of deploying the Verifiable Credentials Data Model into production
environments.
9.11.1 Spectrum of Privacy
It is important to recognize there is a spectrum of privacy ranging from
pseudonymous to strongly identified. Depending on the use case, people have
different comfort levels about what information they are willing to provide
and what information can be derived from what is provided.
Figure 10
- Privacy is a spectrum ranging from pseudonymous to fully identified.
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. Therefore there is
not one approach to privacy that works for all use cases. Privacy solutions are
use case specific.
Note
Even for those wanting to remain anonymous when purchasing alcohol, photo
identification might still be required to provide appropriate assurance to the
merchant. The merchant might not need to know your name or other details (other
than that you are over a specific age), but in many cases just proof of age
might still be insufficient to meet regulations.
The Verifiable Credentials Data Model strives to support the full privacy
spectrum and does not take philosophical positions on the correct level of
anonymity for any specific transaction. The following sections provide
guidance for implementers who want to avoid specific scenarios that are
hostile to privacy.
9.11.2 Personally Identifiable Information
Data associated with verifiable credentials stored in the
credential.credentialSubject field is susceptible to privacy
violations when shared with verifiers. Personally identifying data, such
as a government-issued identifier, shipping address, and full name, can be
easily used to determine, track, and correlate an entity. Even
information that does not seem personally identifiable, such as the
combination of a birth date and a postal code, has very powerful correlation
and de-anonymizing capabilities.
Implementers are strongly advised to warn holders when they share data
with these kinds of characteristics. Issuers are strongly advised to
provide privacy-protecting credentials when possible. For example, issuing
ageOvercredentials instead of date of birth credentials
when a verifier wants to determine if an entity is over the age
of 18.
9.11.3 Identifier-Based Correlation
Subjects of verifiable credentials are identified using the
credential.credentialSubject.id field. The identifiers used to
identify a subject create a greater risk of correlation when the
identifiers are long-lived or used across more than one web domain.
If strong anti-correlation properties are a requirement in a
verifiable credentials system, it is strongly advised that identifiers
are either:
Bound to a single origin
Single-use
Not used at all, but instead replaced by short-lived, single-use bearer tokens.
9.11.4 Signature-Based Correlation
The contents of verifiable credentials are secured using the
credential.proof field. The properties in this field
create a greater risk of correlation when the same values are used across more
than one session or domain and the value does not change. Examples include the
creator, created, domain (for very
specific domains), nonce, and signatureValue fields.
If strong anti-correlation properties are required, it is advised that
signature values and metadata are regenerated each time using technologies like
third-party pairwise signatures, zero-knowledge proofs, or group signatures.
Note
Even when using anti-correlation signatures, information might still be
contained in a credential that defeats the anti-correlation properties
of the cryptography used.
9.11.5 Long Lived Identifier-Based Correlation
Verifiable credentials might contain long-lived identifiers that could
be used to correlate individuals. These types of identifiers include
subject identifiers, email addresses, government-issued identifiers,
organization-issued identifiers, addresses, healthcare vitals,
credential-specific JSON-LD contexts, and many other sorts of long-lived
identifiers.
Organizations providing software to holders should strive to identify
fields in credentials containing information that could be used to correlate
individuals and warn holders when this information is shared.
9.11.6 Device Fingerprinting
There are mechanisms external to verifiable credentials that are used to
track and correlate individuals on the Internet and the Web. Some of these
mechanisms include Internet protocol (IP) address tracking, web browser
fingerprinting, evercookies, advertising network trackers, mobile network
position information, and in-application Global Positioning System (GPS) APIs.
Using verifiable credentials cannot prevent the use of these other
tracking technologies. Also, when these technologies are used in conjunction
with verifiable credentials, new correlatable information could be
discovered. For example, a birthday coupled with a GPS position can be used to
strongly correlate an individual across multiple websites.
It is recommended that privacy-respecting systems prevent the use of these
other tracking technologies when verifiable credentials are being used.
In some cases, tracking technologies might need to be disabled on devices that
transmit verifiable credentials on behalf of a holder.
9.11.7 Favor Abstract Claims
To enable recipients of verifiable credentials to use them in a
variety of circumstances without revealing more personally identifiable
information than necessary for transactions, issuers should consider
limiting the information published in a credential to a minimal set
needed for the expected purposes. One way to avoid placing personally
identifiable information in a credential is to use an "abstract"
property that meets the needs of verifiers without providing specific
information about a subject.
For example, this document uses the ageOver property instead of
a specific birthdate, which constitutes much stronger personally identifiable
information. If retailers in a specific market commonly require purchasers to
be older than a certain age, an issuer trusted in that market might
choose to offer a credential claiming that subjects have met that
requirement instead of offering credentials containing claims about
specific birthdates. This enables individual customers to make purchases
without revealing specific personally identifiable information.
9.11.8 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
minimum disclosure 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, minimal disclosure for issuers means
limiting the content of a credential to the minimum required by
potential verifiers for expected use. For verifiers, minimal
disclosure 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 set of credentials
containing every attribute that appears on a driver's license, as well as
atomized credentials (for example, a credential containing only
a person's birthday), and more abstract atomized credentials (for
example, a credential containing only an ageOver
attribute). One possible adaptation would be for issuers to provide
secure HTTP endpoints for retrieving single-use bearer credentials that
promote the pseudonymous usage of credentials. Implementers that find
this impractical or unsafe, should consider using selective disclosure schemes
that eliminate dependence on issuers at proving time and reduce temporal
correlation risk from issuers.
Verifiers are urged to only request information that is absolutely
necessary for a specific transaction to occur. This is important for at
least two reasons. It:
Reduces the liability on the verifier for handling highly sensitive
information that it does not need to.
Enhances the privacy of the individual by only asking for information required
for a specific transaction.
Note
While it is possible to practice the Principle of Minimum Disclosure, it might
be impossible to avoid the strong identification of an individual for
specific use cases during a single session or over multiple sessions. The
authors of this document cannot stress how difficult it is to meet this
principle in real-world scenarios.
9.11.9 Bearer Credentials
A bearer credential is a privacy-enhancing piece of information,
such as a concert ticket, which entitles the holder of the credential to a
specific resource without divulging sensitive information about the holder.
Verifiable credentials that are bearer credentials are made possible by
not specifying the subject identifier, expressed using the
id property, which is nested in the credentialSubject
property. For example, the following verifiable credential is a bearer
credential:
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://example.com/examples/v1"
],
"id": "http://example.edu/credentials/temporary/28934792387492384",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2017-10-22T12:23:48Z",
"credentialSubject": {
// note that the 'id' property is not specified for bearer credentials
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science in Mechanical Engineering"
}
},
"proof": { ... }
}
While bearer credentials can be privacy-enhancing, they must be carefully
crafted so as not accidentally divulge more information than the holder
of the credential expects. For example, repeated use of the same bearer
credential across multiple sites enables these sites to potentially collude to
unduly track or correlate the holder. Likewise, information that might
seem non-identifying, such as a birthdate and postal code, can be used to
statistically identify an individual when used together in the same
credential or session.
Issuers of bearer credentials SHOULD ensure that bearer credentials that
are expected to provide privacy-enhancing benefits that:
Are single-use, where possible
Do not contain personally identifying information
Are not unduly correlatable.
HoldersSHOULD 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.
VerifiersSHOULD NOT request bearer credentials that can be used to
unduly correlate the user.
9.11.10 Validity Checks
When processing verifiable credentials, verifiers typically
perform many of the checks listed in Section 9.Verification as
well as a variety of business process-specific checks. For example, validity
checks might include checking:
A relationship exists between the holder and the entity
with whom the holder is attempting to interact.
The geolocation information associated with the holder.
The process of performing these checks might result in information leakage that
leads to a privacy violation of the holder. For example, a simple
operation like checking a revocation list can notify the issuer that a
specific business is likely interacting with the holder. This could
enable issuers to collude and correlate individuals without their
knowledge.
Issuers are urged to not use mechanisms, such as credential
revocation lists that are unique per credential, during the verification
process, which could lead to privacy violations. Organizations providing
software to holders should warn when credentials include
information that could lead to privacy violations during the verification
process. Verifiers should consider rejecting credentials that
produce privacy violations or that enable bad privacy practices.
9.11.11 Storage Providers and Data Mining
When a holder receives a credential from an issuer, the
credential needs to be stored somewhere (for example, in a credential
repository). Holders are warned that the information in a
verifiable credential is sensitive in nature and highly individualized,
making it a high value target for data mining. Services that advertise
free storage of verifiable credentials might in fact be mining personal
data and selling it to organizations wanting to build individualized profiles
on people and organizations.
Holders need to be aware of the terms of service for their
credential repository, specifically the correlation and data mining
protections in place for those who store their verifiable credentials
with the service provider.
The following are some effective mitigations for data mining and profiling:
Use service providers that do not sell your information to third parties.
Use software that stores verifiable credentials locally on a device
that you control and that does not upload or analyze your information beyond
your expectations.
9.11.12 Aggregation of Credentials
Two pieces of information about the same subject almost always reveals
more about the subject 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 two bearer credentials, one for an email address and then one
stating the holder is over the age of 21, are provided across multiple
sessions, the verifier of the information now has a unique identifier
plus age-related information for the individual. It is now easy to create and
build a profile for the holder such that more and more information is
leaked over time. Aggregation of credentials can also be performed across
multiple sites in collusion with each other, leading to privacy violations.
From a technological perspective, preventing the aggregation of information is
a very difficult privacy problem to address. While new cryptographic techniques,
such as zero-knowledge proofs, are being proposed as solutions to the problem
of aggregation and correlation, the existence of long-lived identifiers
and browser tracking techniques defeats even the most modern cryptographic
techniques.
The solution to the privacy implications of correlation or aggregation tend
not to be technological in nature, but policy driven instead. Therefore, if
a holder does not want information about them to be aggregated, they
must express this in the verifiable presentations they transmit.
9.11.13 Usage Patterns
Despite the best efforts to assure privacy, actually using
verifiable credentials can potentially lead to de-anonymization and a
loss of privacy. This correlation can occur when:
The same credential is presented to the same verifier more than
once. In this case, the verifier could infer that the holder is
the same individual.
The same credential is presented to different verifiers, and
either those verifiers collude or a third party has access to
transaction records from both verifiers. In this case, the observant
party could infer that the individual presenting the credential is the
same person at both services. That is, the accounts are controlled by the same
person.
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 user), 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 sex, a verifier can potentially
correlate the subject of that credential with an established
profile. For more information, see Sweeney 2000
Simple Demographics Often Identify People Uniquely].
Passing the identifier of a credential to a centralized revocation
server. In this case the centralized server can correlate the credential
usage across interactions. For example, if a verifiable credential is
used for proof of age in this manner, the centralized service could know
everywhere that credential was presented: all liquor stores, bars, adult
stores, lottery purchases, and so on.
In part, it is possible to mitigate this de-anonymization and loss of privacy
by:
Using a globally-unique identifier as the subject for any given
credential and never re-use that credential.
If the credential supports revocation, using a globally-distributed
service for revocation.
Designing revocation APIs that do not depend on submitting the ID of the
credential. For example, use a revocation list instead of a query.
Avoiding the association of personally identifiable information with any
specific long-lived subject identifier.
It is understood that these mitigation techniques are not always practical
or even compatible with necessary usage. Sometimes correlation is a
requirement.
For example, in some prescription drug monitoring programs, usage monitoring is
a requirement. Enforcement entities need to be able to confirm that individuals
are not cheating the system to get multiple prescriptions for controlled
substances. This statutory or regulatory need to correlate usage overrides
individual privacy concerns.
Verifiable credentials will also be used to intentionally correlate
individuals across services, for example, when using a common persona to log in
to multiple services, so all activity on each of those services is
intentionally linked to the same individual. This is not a privacy issue as
long as each of those services uses the correlation in the expected manner.
Privacy risks of credential usage occur when unintended or unexpected
correlation arises from the presentation of verifiable credentials.
9.11.14 Sharing Information with the Wrong Party
When a holder chooses to share information with a verifier, it
might be the case that the verifier is acting in bad faith and requests
information that could be used to harm the holder. For example, a
verifier might ask for a bank account number, which could then be used
with other information to defraud the holder or the bank.
Issuers should strive to tokenize as much information as possible such
that if a holder accidentally transmits credentials to the wrong
verifier, the situation is not catastrophic.
For example, instead of including a bank account number for the purpose of
checking a individual's bank balance, provide a token that enables the
verifier to check if the balance is above a certain amount. In this
case, the bank could issue a verifiable credential containing a balance
checking token to a holder. The holder would then include the
verifiable credential in a verifiable presentation and bind the
token to a credit checking agency using a digital signature. The
verifier could then wrap the verifiable presentation in their
digital signature, and hand it back to the issuer to dynamically check the
account balance.
Using this approach, even if a holder shares the account balance token
with the wrong party, an attacker cannot discover the bank account number, nor
the exact value in the account. And given the validity period for the
counter-signature, does not gain access to the token for more than a few
minutes.
9.11.15 Frequency of Claim Issuance
As detailed in Section 9.11.13Usage Patterns, usage patterns can be
correlated into certain types of behavior. Part of this correlation is
mitigated when a holder uses a verifiable credential without the
knowledge of the issuer. Issuers can defeat this protection
however, by making their credentials short lived and renewal automatic.
For example, an "over the age of 21" credential is useful for gaining
access to a bar. If an issuer issues such a credential with a
very short expiration date and an automatic renewal mechanism, then the
issuer could possibly correlate the behavior of the holder in a
way that negatively impacts the holder.
Organizations providing software to holders should warn them if they
repeatedly use credentials with short lifespans, which could result in
behavior correlation. Issuers should avoid issuing credentials in
a way that enables them to correlate usage patterns.
9.11.16 Prefer Single-Use Credentials
An ideal privacy-respecting system would require only the information necessary
for interaction with the verifier to be disclosed by the holder.
The verifier would then record that the disclosure requirement was met
and forget any sensitive information that was disclosed. In many cases,
competing priorities, such as regulatory burden, prevent this ideal system from
being employed. In other cases, long-lived identifiers prevent single use. The
design of any verifiable credentials ecosystem, however, should strive
to be as privacy-respecting as possible by preferring single-use
credentials whenever possible.
Using single-use credentials provides several benefits. The first
benefit is to verifiers who can be sure that the data in a
credential is fresh. The second benefit is to holders, who know
that if there are no long-lived identifiers in the credential,
the credential itself cannot be used to track or correlate them online.
Finally, the third benefit is that there is nothing for attackers to steal,
making the entire ecosystem safer to operate within.
9.11.17 Avoid Disclosing Credential Identifier
Disclosing the credential identifier leads to situations where multiple
verifiers, or an issuer and a verifier, can collude to
correlate the holder. If holders want to reduce correlation, they
should use credential schemes that allow hiding the identifier during
presentation. Such schemes expect the holder to generate the identifier
and might even allow hiding the identifier from the issuer, while still
keeping the identifier embedded and signed in the credential.
9.12 Security Considerations
This section is non-normative.
There are a number of security considerations that issuers,
holders, and verifiers should be aware of when processing
data described by this specification. Ignoring or not understanding the
implications of this section can result in security vulnerabilities.
While this section attempts to highlight a broad set of security
considerations, it should not be interpreted as a complete list. Implementers
are urged to seek the advice of security and cryptography professionals when
implementing mission critical systems using the technology outlined in this
specification.
9.12.1 Cryptography Suites and Libraries
Some aspects of the data model described in this specification can be
protected through the use of cryptography. Implementers should be aware of the
underlying cryptography suites and libraries used to implement the creation and
verification of digital signatures and mathematical proofs used by their
systems when processing credentials and presentations. Software
developers with extensive experience implementing or auditing systems that use
cryptography must be employed to ensure 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. Production quality systems must take
this into account and ensure mechanisms exist to easily and proactively upgrade
expired or broken cryptographic suites and libraries. Procedures should also
exist to invalidate and replace existing credentials in the event of a
cryptography suite or library failure. Regular monitoring of systems to ensure
proper upgrades are made in a timely manner are also important to ensure the
long term viability of systems processing verifiable credentials.
9.12.2 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.
9.12.3 Token Binding
A verifier might need to ensure it is the intended recipient of a
verifiable presentation and not the target of a
man-in-the-middle attack. Any protocol that is using the Verifiable
Credentials Data Model and requires protection against these kinds of attacks
needs to perform some sort of token binding, such as
The Token Binding Protocol v1.0, which ties the request for a
verifiable presentation with the response. Any protocol that does not
perform token binding is susceptible to man-in-the-middle attacks.
9.12.4 Bundling Dependent Claims
It is considered best practice for issuers to atomize information in a
credential, or use a signature scheme that allows for selective
disclosure. In the case of atomization, if it is not done securely by the
issuer, the holder might bundle together different
credentials in a way that was not intended by the issuer.
For example a university might issue two credentials to a person, each
containing two properties, for example, "Staff Member" in the "Department of
Computing" and "Post Graduate Student" in the "Department of Economics". If
these credentials are atomized into separate properties, then the
university would issue four credentials to the person, each containing one of
the following properties, "Staff Member", "Post Graduate Student", "Department
of Computing", and "Department of Economics". The holder could then
transfer the "Staff Member" and "Department of Economics" credentials to
a verifier, which together would comprise a false claim.
9.12.5 Highly Dynamic Information
When verifiable credentials are issued for highly dynamic information,
implementers should ensure the expiration times are set appropriately.
Expiration periods longer than the timeframe where the credential is
valid might create exploitable security vulnerabilities. Expiration periods
shorter than the timeframe where the information expressed by the
credential is valid creates a burden on holders and
verifiers. It is therefore important to set validity periods for
credentials that are appropriate to the use case and the expected
lifetime for the information contained in the credential.
9.12.6 Device Theft and Impersonation
When verifiable credentials are stored on a device and that
device is lost or stolen, it might be possible for an attacker to gain access
to systems using the victim's verifiable credentials. Ways to mitigate
this type of attack include:
Enabling password, pin, pattern, or biometric screen unlock protection.
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.13 Advanced Examples
9.13.1 Subject Passes a Verifiable Credential to Someone Else
In the above example, a patient (the original subject) has passed a prescription
(the original verifiable credential) to a friend, and has issued a new verifiable
credential to the friend, in which the friend is the subject, the original subject is
the issuer, and the credential is a copy of the original prescription.
