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.
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:
what a verifiable credential contains,
an ecosystem where verifiable credentials are expected to be useful, and
the use cases and requirements that informed this specification
What is a Verifiable Credential?
In the physical world, a credential may consist of:
information related to the subject of the credential (e.g. photo, name, and
identification number),
information related to the issuing authority (e.g. state department,
federal agency, or employer),
evidence related to how the credential was derived, and
information related to expiration dates.
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:
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.
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:
a more thorough explanation of the
roles
introduced above,
the
needs
identified in market verticals like education, finance, healthcare, retail,
professional licensing, and government,
common
tasks
performed by the roles in the ecosystem, as well as their associated
requirements, and
As a result of documenting and analyzing the use cases document, a number of
desirable requirements have been identified for this specification, namely:
A verifiable credential MUST be expressed in one or more standard,
machine-readable data formats for expressing verifiable credentials which
can also be extended with minimal coordination.
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
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 made by the
same entity. It may include an identifier to uniquely identify the
credential, as well as metadata that describes properties of the credential
itself such as: the issuer, the expiry time, a representative image,
etc. A verifiable credential is a set of claims and meta data that are
tamper-resistant and that cryptographically prove who issued it.
The basic components of a verifiable credential.
Examples of verifiable credentials include digital employee identification
cards, digital proofs of age, and digital educational certificates.
It is possible to have a credential, such as a marriage certificate,
that contains multiple claims about different subjects that are
not required to be related.
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 that are often about the same subject that
have been issued by multiple issuers. The aggregation of this
information typically expresses an aspect of a person, organization, or entity.
The basic components of a verifiable profile.
Examples of different profiles include a person's professional persona, online
gaming persona, or home life persona.
It is possible to have a profile, such as a business persona,
that contains multiple credentials about different subjects
that are often, but not required to be, related.
Trust Model
The Verifiable Credentials trust model is as follows:
The verifier trusts the issuer to issue the Verifiable Credential
that it receives. This trust could be weakened depending upon the risk
assessment of the verifier.
All entities trust the identifier registry to be un-corruptible and
to be a correct record of which identifiers belong to which entities.
The subject trusts the issuer to issue true (i.e. not false)
credentials about the subject, and to revoke them quickly when
appropriate.
The holder trusts the repository to store the
credentials securely, to not release them to anyone other than the
holder, and to not corrupt or lose them whilst they are in its care.
This trust model differentiates itself from other trust models by ensuring that:
The issuer and the verifier do not need to trust the
repository, and
By decoupling the trust between the identity provider and the
relying party, a more flexible and dynamic trust model is created
such that market competition and customer choice is increased.
Basic Concepts
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.
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.
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.
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.
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.
Profiles
Credentials MAY be composed by placing them into a data structure called a
profile. A verifiable profile is a profile that contains
verifiable credentials and one or more proofs that are appropriate
for the profile. The basic structure of a verifiable profile
is provided below:
The contents of the verifiableCredential property 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.
Advanced Concepts
Extensibility
One of the goals of the Verifiable Credentials Data Model is to enable
permissionless innovation. This requires that the data model is extensible
in a number of different ways:
The requirement to model complex multi-entity relationships is provided
through the use of a graph-based data model.
The requirement to be able to extend the machine-readable vocabularies
used to describe information in the data model without the use of a
centralized system for doing so is accomplished via the use
of [[LINKED-DATA]].
The requirement to support multiple types of cryptographic proof formats is
accomplished via the use of [[LINKED-DATA-PROOFS]], [[LINKED-DATA-SIGNATURES]],
and a variety of signature suites.
The requirement to provide all of the extensibility mechanisms outlined above
in a data format that is popular among software developers and web page authors
is enabled via the use of [[!JSON-LD]].
This approach to data modelling is often called an "open world assumption",
meaning that any entity can say anything about any other entity. This approach
often feels in conflict with building simple and predictable software systems.
Balancing extensibility with program correctness is always more challenging
with an open world assumption than it is with closed software systems.
The rest of this section describes how both extensibility and program
correctness are achieved through a series of examples.
The credential above simply states that the entity associated with
did:example:abcdef1234567 has a name with a
value of Jane Doe. Let's assume that a developer wanted to
extend the verifiable credential to store two additional pieces of
information: an internal corporate reference number, and Jane's favorite
food.
The first thing that a developer would do is create a JSON-LD Context
containing the two new terms:
Now that the JSON-LD Context has been created, the developer must publish it
somewhere that is accessible to verifiers that will be processing the
verifiable credential. For this example, let us assume that the
JSON-LD Context above is published at the following URL:
https://example.com/contexts/mycontext.jsonld. At this point,
extending the first example in this section is a simple matter of including the
context above and adding the new properties to the verifiable credential.
The examples so far have shown that it is easy to extend the Verifiable
Credentials Data Model in a permissionless and decentralized way. The
mechanism shown also ensures that verifiable credentials that were created
in this way provide a mechanism to prevent namespace conflicts and
semantic ambiguity.
An extensibility model that is this dynamic does increase implementation burden.
Software written for such a system will have to determine if accepting
verifiable credentials with extensions is acceptable based on the
risk profile of the application. Some applications may choose to accept but
ignore extensions, others may choose to only accept certain extensions, while
highly secure environments may require that no extensions are allowed. These
decisions are up to the developers of these applications and are specifically
not the domain of this specification.
Implementations MUST produce an error when an extension JSON-LD Context
overrides the expanded URL for a term specified in the base JSON-LD Context
(https://w3id.org/credentials/v1). To avoid the possibility of
accidentally overriding terms, developers are urged to scope their extensions.
For example, the following extension scopes the new favoriteFood
term so that it may only be used within the claim property:
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.
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.
In the example above, the holder is prohibiting a verifier from
using the information provided to correlate the holder using a
3rd party service.
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 contents of each evidence scheme is determined by the
particular scheme itself.
The group is currently determining whether or not they should publish a
very simple scheme for evidence as a part of this specification.
An entity may dispute a credential issued by another entity.
The mechanism for doing this is the same as issuing a regular credential
except that the subject identifier for the claims are those
of the disputed credential. For example, if a disputed credential with an
identifier of https://example.org/credentials/245 contains
disputed statements, an entity may issue the following credential 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
may be used to identify the disputed credential. Similarly, content-addressed
identifiers may be used to uniquely identify individual claims.
The group is currently exploring whether the specification of a vocabulary
term to express content-based identifiers for claims is within scope.
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
Document is syntactically valid (e.g. JSON, JSON-LD).
Credential
Required properties are present. For example, for a
Credential, type and claim are
required.
Property values match expectations described in the
specification. For example, the document type for a verifiable
credential must contain the class "Credential".
Issuer
The issuer id must match expectations. Likely,
that means it is the id of a known and trusted verifiable
profile.
Recent metadata about the issuer which was published
by the issuer MUST be available.
Subject
The claim subject identifier must match expectations.
Likely, that means it is the id of a known and trusted
verifiable profile for the subject of the claim. If the
entity that is subject of a claim has transmitted it to the
verifier, the subject may be able to prove ownership of key
identifying properties such as email address(es) and public
key(s).
Signatures / Proofs
The cryptographic mechanism used to prove that the information in a
verifiable credential or a verifiable profile 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,
proof of work, and proof 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 agorithm, 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:
The public key associated with the signature is available
and a trustworthy link between the signing key and the
issuer MUST be established.
The key MUST NOT not be revoked or expired.
The cryptographic signature MUST be valid.
If a proofPurpose exists, it MUST be a valid value
per the cryptographic suite.
The digital signature provides a number of protections, other than tamper
resistance, that are not immediately obvious.
For example, a Linked Data Signature's created property
establishes a date and time where the credential SHOULD NOT be considered
valid before that date and time. The creator property enables
the ability to dynamically discover information about the entity that created
the data to ensure that the public key has not been revoked or expired.
The proofPurpose property ensures that the reason the entity
created the signature, such as for the purposes of authentication or creating
a verifiable credential, are clear and protected in the signature.
Expiration
The issued date must be in the expected range.
For example, a verifier may wish to ensure that the recorded
issued date of valid credentials is not in the future.
Revocation
If revocation instructions are present, the credential must not
have been revoked.
Fitness for Purpose
The custom properties in the credential should be
appropriate for the verifier's purpose. For example if an
verifier needs to determine that a subject is older than 21
years of age, they may accept claims of specific birthdate or
abstract properties such as ageOver.
The issuer is trusted by the verifier to make the claims
at hand. For example, Fast Food Resturant A will not be trusted
to make a claim that an individual may enjoy a lifetime 10%
discount to its competitor Fast Food Restaurant B.
If the issuer has placed any policy information about
the use of the credential, e.g. intended
verifiers, expiration date, etc., that this
policy is adhered to.
If the holder has placed any policy information about
the use of the credential, e.g. intended
verifiers, restricted usage rights, etc., that this
policy is adhered to.
Syntaxes
This section defines how the data model described in
Section is realized in two
different syntaxes: JSON and JSON-LD. Although
syntactic mappings are only provided for these two syntaxes,
applications and services may also use any other data
representation syntax that can express the data model
(e.g. XML, YAML, CBOR, etc.) .
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.
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.
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.
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.
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.
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.
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.
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.proof field. The properties in this field
create a danger of correlation when the same values are used across more than
one session or domain and the value does not change. Examples include the
creator, created,
domain (for very specific domains),
nonce, and signatureValue fields.
If strong anti-correlation properties are desired,
it is advised that signature values and metadata are regenerated
each time using technologies like third party pairwise signatures,
zero knowledge proofs, or group signatures. It is also important to note
that even when using anti-correlation signatures that information may still
be contained in the credential that defeats the anti-correlation properties
of the cryptography.
Long Lived Identifier-based Correlation
Verifiable credentials may contain long lived identifiers that could
be used to correlate individuals. These types of identifiers include:
subject identifiers, email addresses, government issued identifiers,
organization issued identifiers, addresses, healthcare vitals,
credential-specific JSON-LD Contexts, and many other sorts of long-lived
identifiers.
Organizations providing software to holders should strive to identify
fields in credentials containing information that could be used to correlate
them and warn the holder when this information is shared.
Device Fingerprinting
There are mechanisms external to Verifiable Credentials that are used to track and
correlate individuals on the Internet and the Web. Some of these mechanisms
include Internet Protocol address tracking, Web Browser fingerprinting,
Evercookies, Advertising Network trackers, mobile network position information,
and in-application Global Positioning System APIs. The use of Verifiable
Claims cannot prevent the use of these other tracking technologies. In addition,
when these technologies are used in concert with Verifiable Credentials, new
correlatable information may be discovered. For example, a birthday coupled
with a GPS position can be used to strongly correlate an individual across
multiple websites.
It is advised that privacy 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:
Checking the professional licensure status of the holder.
Checking a date of license renewal or revocation.
Checking sub-qualifications of an individual.
Ensuring that a relationship exists between the holder and the entity
with whom the holder is attempting to interact.
Checking the geolocation information associated with the holder.
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:
Use service providers that do not sell your information to third parties.
Use software that encrypts verifiable credentials such that a service provider
cannot view the contents of the claims.
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.
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.
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:
When the same claim is presented to the same verifier more than once –
that verifier could infer that the holder is the same individual.
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.
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.
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].
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:
Use a globally unique identifier as the subject for any given claim and never
re-use that claim.
If the claim supports revocation, use a globally distributed service for revocation.
Design revocation APIs that do not depend on submitting the ID
of the claim, e.g., use a revocation list rather than a query.
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.
Bundling Dependent Claims
It is considered a best practice for issuers to atomize information in a
credential, or use a signature scheme that allows for selective disclosure.
In the former case, if the atomization is not done securely by the issuer,
the holder might bundle together different credentials in a way that was not
intended by the issuer.
For example a university might issue two credentials to a person, each
containing two properties i.e. "Staff Member" in the
"Department of Computing" and "Post Graduate Student" in the
"Department of Economics". If these credentials are atomized into separate
properties, then the university would issue four credentials to the person,
each containing one of the following properties:
"Staff Member", "Post Graduate Student", "Department of Computing" and
"Department of Economics". The holder could then transfer
the "Staff Member" and "Department of Economics" to a verifier,
which together would comprise a false claim.
Highly Dynamic Information
When verifiable credentials are issued for highly dynamic information,
implementers should ensure that the expiration times for the credential are
set appropriately. Expiration periods that are longer than the timeframe
where the credential is valid may create exploitable security vulnerabilities.
Expiration periods that are shorter than the timeframe where the information
expressed by the credential is valid create a burden on holders and
verifiers. It is therefore important to set validity periods for
credentials that are appropriate to the use case and the expected lifetime
for the information contained in the credential.
Device Theft and Impersonation
When verifiable credentials are stored on a device and that
device is stolen by an attacker, it may be possible for the attacker to then
gain access to systems using the victim's verifiable credentials. Mitigations
for this attack include:
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.
Utilizing a separate hardware-based signature device.
