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/.
The Working Group thanks the following individuals not only
for their contributions toward the content of this document,
but also for yeoman's work in this standards community that
drove changes, discussion, and consensus among a sea of varied
opinions: Matt Stone, Gregg Kellogg, Ted Thibodeau Jr, Oliver
Terbu, Joe Andrieu, David I. Lehn, Matthew Collier, and Adrian
Gropper.
Work on this specification has been supported by the
Rebooting the Web of Trust community facilitated by Christopher
Allen, Shannon Appelcline, Kiara Robles, Brian Weller, Betty
Dhamers, Kaliya Young, Manu Sporny, Drummond Reed, Joe Andrieu,
Heather Vescent, Kim Hamilton Duffy, Samantha Chase, and Andrew
Hughes. The participants in the Internet Identity Workshop,
facilitated by Phil Windley, Kaliya Young, Doc Searls, and
Heidi Nobantu Saul, also supported the refinement of this work
through numerous working sessions designed to educate about,
debate on, and improve this specification.
Portions of the work on this specification have been funded
by the United States Department of Homeland Security's Science
and Technology Directorate under contract HSHQDC-17-C-00019.
The content of this specification does not necessarily reflect
the position or the policy of the U.S. Government and no
official endorsement should be inferred.
This is the second publication of a Candidate Recommendation
document and is being made for specific feedback on a change to
the JWT section related to the nbf and
iss attributes. The Working Group is only seeking
feedback on these changes from implementers and is specifically
not seeking feedback on other parts of the document. The
comment period for these features expire on 21 August 2019.
Other comments regarding this document are welcome, but
readers should be aware that the Candidate Recommendation
comment period regarding the rest of this document has ended
and the Working Group is unlikely to make substantive
modifications to the specification at this stage. Please file
issues directly on GitHub, or
send them to public-vc-comments@w3.org
(subscribe,
archives).
The Working Group has received implementation feedback
showing that there are at least two implementations for each
normative feature in the specification. The group has obtained
reports from nine (9) implementations. For details, see the
test suite
and implementation
report.
Changes since the last publication of this document
include:
Substantive changes to the JWT section regarding the use
of the nbf and iss properties.
Editorial clarifications related to the support of
various proof mechanisms by this specification.
Editorial clarifications related to JSON-LD processing
not being necessary for conforming implementations.
Editorial clarifications related to JWT processing.
Editorial clarifications related to the level of
interoperability (data model and syntax) that this
specification is designed to achieve.
Editorial updates throughout the specification to ease
readability.
The following features are at risk:
The JWT section is at risk due to implementation maturity
concerns. If the section is removed in the Proposed
Recommendation, it will be migrated to a separate
document.
This document was published by the Verifiable Claims Working
Group as a Candidate Recommendation. This document is
intended to become a W3C Recommendation.
W3C publishes
a Candidate Recommendation to indicate that the document is
believed to be stable and to encourage implementation by the
developer community. This Candidate Recommendation is expected
to advance to Proposed Recommendation no earlier than 21 August
2019.
Publication as a Candidate Recommendation 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:
The use cases and requirements that informed this
specification.
1.1 What is a Verifiable Credential?
This section is non-normative.
In the physical world, a credential might
consist of:
Information related to identifying the subject of the credential (for
example, a photo, name, or identification number)
Information related to the issuing authority (for
example, a city government, national agency, or
certification body)
Information related to the type of
credential this is (for example, a Dutch passport, an
American driving license, or a health insurance card)
Information related to specific attributes or
properties being asserted by the issuing authority about
the subject (for example, nationality,
the classes of vehicle entitled to drive, or date of birth)
Evidence related to how the credential was
derived
Information related to constraints on the credential
(for example, expiration date, or terms of use).
A verifiable credential
can represent all of the same information that a physical
credential represents. The addition of
technologies, such as digital signatures, makes verifiable credentials more
tamper-evident and more trustworthy than their physical
counterparts.
Both verifiable credentials
and verifiable
presentations can be transmitted rapidly, making them
more convenient than their physical counterparts when trying
to establish trust at a distance.
While this specification attempts to improve the ease of
expressing digital credentials, it also
attempts to balance this goal with a number of
privacy-preserving goals. The persistence of digital
information, and the ease with which disparate sources of
digital data can be collected and correlated, comprise a
privacy concern that the use of verifiable and easily
machine-readable credentials threatens
to make worse. This document outlines and attempts to address
a number of these issues in Section § 7. Privacy Considerations. Examples of how
to use this data model using privacy-enhancing technologies,
such as zero-knowledge proofs, are also provided throughout
this document.
1.2
Ecosystem Overview
This section is non-normative.
This section describes the roles of the core actors and
the relationships between them in an ecosystem where verifiable credentials are expected
to be useful. A role is an abstraction that might be
implemented in many different ways. The separation of roles
suggests likely interfaces and protocols for standardization.
The following roles are introduced in this specification:
A role an entity performs by receiving one
or more verifiable
credentials, optionally inside a verifiable presentation, for
processing. Example verifiers include employers, security
personnel, and websites.
A role a system might perform by mediating the creation
and verification of identifiers,
keys, and other relevant data, such as verifiable credential schemas,
revocation registries, issuer public keys, and so on,
which might be required to use verifiable credentials. Some
configurations might require correlatable identifiers for
subjects. Example verifiable
data registries include trusted databases, decentralized
databases, government ID databases, and distributed
ledgers. Often there is more than one type of verifiable
data registry utilized in an ecosystem.
Figure 1 The roles and information flows forming the
basis for this specification.
Note
Figure 1 above provides an
example ecosystem in which 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 document
[VC-USECASES] outlines a number of key
topics that readers might find useful, including:
A more thorough explanation of the roles
introduced above
The needs
identified in market verticals, such as education, finance,
healthcare, retail, professional licensing, and government
Common tasks
performed by the roles in the ecosystem, as well as their
associated requirements
As a result of documenting and analyzing the use cases
document, the following desirable ecosystem characteristics
were identified for this specification:
Verifiable credentials represent
statements made by an issuer in a
tamper-evident and privacy-respecting manner.
The specification must provide a means for issuers to issue verifiable credentials that
support selective disclosure, without requiring all
conformant software to support that feature.
Verifiable credentials and
verifiable
presentations have to be serializable in one or more
machine-readable data formats. The process of
serialization and/or de-serialization has to be
deterministic, bi-directional, and lossless. Any
serialization of a verifiable
credential or verifiable
presentation needs to be transformable to the generic
data model defined in this document in a deterministic
process such that the resulting verifiable credential can be
processed in an interoperable fashion. The serialized
form also needs to be able to be generated from the data
model without loss of data or content.
The data model and serialization must be extendable
with minimal coordination.
Issuers revoking verifiable credentials should
distinguish between revocation for cryptographic
integrity (for example, the signing key is compromised)
versus revocation for a status change (for example, the
driver’s license is suspended).
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, and SHOULD in this document are to be interpreted
as described in BCP 14
[RFC2119] [RFC8174] when, and only
when, they appear in all capitals, as shown here.
A conforming document is any
concrete expression of the data model that complies with the
normative statements in this specification. Specifically, all
relevant normative statements in Sections § 4. Basic Concepts, § 5. Advanced Concepts, and § 6. Syntaxes of this document MUST be enforced. A serialization
format for the conforming document MUST be deterministic, bi-directional, and
lossless as described in Section § 6. Syntaxes.
The conforming documentMAY be transmitted or stored in
any such serialization format.
A conforming processor is any
algorithm realized as software and/or hardware that generates
or consumes a conforming document.
Conforming processors MUST produce errors when non-conforming documents
are consumed.
This specification makes no normative statements with
regard to the conformance of roles in the ecosystem, such as
issuers, holders, or verifiers,
because the conformance of ecosystem roles are highly
application, use case, and market vertical specific.
Digital proof mechanisms, a subset of which are digital
signatures, are required to ensure the protection of a
verifiable credential. Having and
validating proofs, which may be dependent on the syntax of
the proof (for example, using the JSON Web Signature of a
JSON Web Token for proofing a key holder), are an essential
part of processing a verifiable
credential. At the time of publication, Working Group
members had implemented verifiable
credentials using at least three proof mechanisms:
JSON Web Tokens [RFC7519] secured using JSON Web
Signatures [RFC7515]
Implementers are advised to note that not all proof
mechanisms are standardized as of the publication date of
this specification. The group expects some of these
mechanisms, as well as new ones, to mature independently and
become standardized in time. Given there are multiple valid
proof mechanisms, this specification does not standardize on
any single digital signature mechanism. One of the goals of
this specification is to provide a data model that can be
protected by a variety of current and future digital proof
mechanisms. Conformance to this specification does not depend
on the details of a particular proof mechanism; it requires
clearly identifying the mechanism a verifiable credential uses.
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.
data minimization
The act of limiting the amount of shared data strictly
to the minimum necessary to successfully accomplish a task
or goal.
decentralized identifier
A portable URL-based identifier, also known as a
DID, associated with an
entity. These identifiers are
most often used in a verifiable credential and are
associated with subjects such that
a verifiable
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.
decentralized identifier document
Also referred to as a DID
document, this is a document that is
accessible using a verifiable data registry and
contains information related to a specific decentralized identifier, such
as the associated repository
and public key information.
derived
predicate
A verifiable, boolean assertion about the value of
another attribute in a verifiable credential. These are
useful in zero-knowledge-proof-style verifiable 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 verifiable credential
demonstrating that the 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, or device that performs 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
principle of data minimization.
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 verifiable credentials are
bearer credentials, it is assumed the
verifiable credentials 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 verifiable 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 identifiers,
keys, and other relevant data, such as verifiable credential schemas,
revocation registries, issuer public keys, and so on,
which might be required to use verifiable credentials. Some
configurations might require correlatable identifiers for
subjects. Some registries, such
as ones for UUIDs and public keys, might just act as
namespaces for identifiers.
A Uniform Resource Identifier, as defined by
[RFC3986].
3. Core
Data Model
This section is non-normative.
The following sections outline core data model concepts,
such as claims, credentials, and
presentations, which form the
foundation of this specification.
3.1
Claims
This section is non-normative.
A claim is a statement about a
subject. A subject is a thing
about which claims can be made. Claims are expressed using
subject-property-value relationships.
Figure 2 The basic structure of a claim.
The data model for claims, illustrated in
Figure 2 above, is powerful and can be used to
express a large variety of statements. For example, whether
someone graduated from a particular university can be
expressed as shown in
Figure 3 below.
Figure 3 A basic claim expressing that Pat is an
alumni of "Example University".
Individual claims can be merged together to
express a graph of information about a
subject. The example shown in
Figure 4 below extends the
previous claim by adding the claims that Pat knows Sam and that Sam is employed
as a professor.
Figure 4 Multiple claims can be combined to express a
graph of information.
To this point, the concepts of a claim and a
graph of information are introduced. To be able to
trust claims, more information is expected
to be added to the graph.
3.2
Credentials
This section is non-normative.
A credential is a set of one or more
claims made by the same entity. Credentials might also include an identifier and
metadata to describe properties of the credential, such as the issuer, the
expiry date and time, a representative image, a public key to
use for verification purposes, the
revocation mechanism, and so on. The metadata might be signed
by the issuer. A verifiable credential is a set of
tamper-evident claims and metadata that
cryptographically prove who issued it.
Figure 5 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 is advised to use a selective
disclosure scheme that does not reveal the credential identifier.
Figure
5 above shows the basic
components of a verifiable credential,
but abstracts the details about how claims are
organized into information graphs, which are then
organized into verifiable
credentials.
Figure 6 below shows a more
complete depiction of a verifiable
credential, which is normally composed of at least two
information graphs. The first graph expresses the verifiable credential itself, which
contains credential metadata and claims. The second
graph expresses the digital proof, which is usually a
digital signature.
Figure 6 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.
Note
It is possible to have a credential that does not contain any claims about the entity to which the
credential was issued. For
example, a credential that only contains
claims about a specific dog, but is issued to its
owner.
3.3
Presentations
This section is non-normative.
Enhancing privacy is a key design feature of this
specification. Therefore, it is important for entities using this technology to be able to
express only the portions of their persona that are
appropriate for a given situation. The expression of a subset
of one's persona is called a verifiable presentation. Examples of
different personas include a person's professional persona,
their online gaming persona, their family persona, or an
incognito persona.
The data in a presentation is often
about the same subject, but might have been issued
by multiple issuers. The aggregation of this
information typically expresses an aspect of a person,
organization, or entity.
Figure 7 Basic components of a verifiable
presentation.
Figure
7 above shows the components of
a verifiable presentation, but
abstracts the details about how verifiable credentials are organized
into information graphs, which are then organized
into verifiable
presentations.
Figure 8 below shows a more
complete depiction of a verifiable presentation, which is
normally composed of at least four information graphs. The first graph expresses the
verifiable presentation itself,
which contains presentation metadata. The
verifiablePresentation property in the graph refers to one or more verifiable credentials (each a
self-contained graph), which in turn contains
credential
metadata and claims. The third graph expresses the credential graph proof, which is
usually a digital signature. The fourth graph expresses
the presentation graph proof, which is
usually a digital signature.
Figure 8 Information graphs associated with a basic
verifiable presentation.
Note
It is possible to have a presentation, such as a business persona, which
draws on multiple credentials about
different subjects that are often, but not
required to be, related.
To illustrate this lifecycle, we will use the example of
redeeming an alumni discount from a university. In the
example below, Pat receives an alumni verifiable credential from a
university, and Pat stores the verifiable credential in a digital
wallet.
Example
1: A simple
example of a verifiable credential
{
// set the context, which establishes the special terms we will be using
// such as 'issuer' and 'alumniOf'.
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
// specify the identifier for the credential
"id": "http://example.edu/credentials/1872",
// the credential types, which declare what data to expect in the credential
"type": ["VerifiableCredential", "AlumniCredential"],
// the entity that issued the credential
"issuer": "https://example.edu/issuers/565049",
// when the credential was issued
"issuanceDate": "2010-01-01T19:73:24Z",
// claims about the subjects of the credential
"credentialSubject": {
// identifier for the only subject of the credential
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
// assertion about the only subject of the credential
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": [{
"value": "Example University",
"lang": "en"
}, {
"value": "Exemple d'Université",
"lang": "fr"
}]
}
},
// digital proof that makes the credential tamper-evident// see the NOTE at end of this section for more detail
"proof": {
// the cryptographic signature suite that was used to generate the signature
"type": "RsaSignature2018",
// the date the signature was created
"created": "2017-06-18T21:19:10Z",
// purpose of this proof
"proofPurpose": "assertionMethod",
// the identifier of the public key that can verify the signature
"verificationMethod": "https://example.edu/issuers/keys/1",
// the digital signature value
"jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X
sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc
X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj
PAYuNzVBAh4vGHSrQyHUdBBPM"
}
}
Pat then attempts to redeem the alumni discount. The
verifier, a ticket sales system, states that any
alumni of "Example University" receives a discount on season
tickets to sporting events. Using a mobile device, Pat starts
the process of purchasing a season ticket. A step in this
process requests an alumni verifiable credential, and this
request is routed to Pat's digital wallet. The digital wallet
asks Pat if they would like to provide a previously issued
verifiable credential. Pat selects
the alumni verifiable credential,
which is then composed into a verifiable presentation. The
verifiable presentation is sent to
the verifier and verified.
Example 2: A
simple example of a verifiable presentation
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"type": "VerifiablePresentation",
// the verifiable credential issued in the previous example
"verifiableCredential": [{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/1872",
"type": ["VerifiableCredential", "AlumniCredential"],
"issuer": "https://example.edu/issuers/565049",
"issuanceDate": "2010-01-01T19:73:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": [{
"value": "Example University",
"lang": "en"
}, {
"value": "Exemple d'Université",
"lang": "fr"
}]
}
},
"proof": {
"type": "RsaSignature2018",
"created": "2017-06-18T21:19:10Z",
"proofPurpose": "assertionMethod",
"verificationMethod": "https://example.edu/issuers/keys/1",
"jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X
sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc
X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj
PAYuNzVBAh4vGHSrQyHUdBBPM"
}
}],
// digital signature by Pat on the presentation
// protects against replay attacks
"proof": {
"type": "RsaSignature2018",
"created": "2018-09-14T21:19:10Z",
"proofPurpose": "authentication",
"verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1",
// 'challenge' and 'domain' protect against replay attacks
"challenge": "1f44d55f-f161-4938-a659-f8026467f126",
"domain": "4jt78h47fh47",
"jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..kTCYt5
XsITJX1CxPCT8yAV-TVIw5WEuts01mq-pQy7UJiN5mgREEMGlv50aqzpqh4Qq_PbChOMqs
LfRoPsnsgxD-WUcX16dUOqV0G_zS245-kronKb78cPktb3rk-BuQy72IFLN25DYuNzVBAh
4vGHSrQyHUGlcTwLtjPAnKb78"
}
}
Note
Implementers that are interested in
understanding more about the proof mechanism
used above can learn more in Section § 4.7 Proofs (Signatures) and by reading
the following specifications: Linked Data Proofs
[LD-PROOFS], Linked Data Signatures
[LD-SIGNATURES], 2018 RSA Signature
Suite [LDS-RSA2018], and JSON
Web Signature (JWS) Unencoded Payload Option
[RFC7797]. A list of
proof mechanisms is available in the Verifiable Credentials
Extension Registry [VC-EXTENSION-REGISTRY].
4. Basic
Concepts
This section introduces some basic concepts for the
specification, in preparation for Section § 5. Advanced Concepts later in the
document.
4.1
Contexts
When two software systems need to exchange data, they need
to use terminology 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 might be referred to as
the context of a conversation.
In JSON-LD, the @contextproperty can also be used to communicate other
details, such as datatype information, language
information, transformation rules, and so on, which are
beyond the needs of this specification, but might be useful
in the future or to related work. For more information, see
Section 3.1:
The Context of the [JSON-LD]
specification.
The value of the @contextpropertyMUST be an ordered set where the first item
is a URI with the value
https://www.w3.org/2018/credentials/v1. For
reference, a copy of the base context is provided in
Appendix § B. Base
Context. Subsequent items in the array MUST express context
information and be composed of any combination of
URIs or objects. It is RECOMMENDED that each URI in the @context be one which,
if dereferenced, results in a document containing
machine-readable information about the
@context.
Note
Though this specification requires that a
@contextproperty be present,
it is not required that the value of the
@contextproperty be
processed using JSON-LD. This is to support processing
using plain JSON libraries, such as those that might be
used when the verifiable
credential is encoded as a JWT. All libraries or
processors MUST
ensure that the order of the values in the
@contextproperty is what is
expected for the specific application. Libraries or
processors that support JSON-LD can process the
@contextproperty using full
JSON-LD processing as expected.
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://www.w3.org/2018/credentials/examples/v1)
establishes that the conversation is about examples.
Note
This document uses the example context URI
(https://www.w3.org/2018/credentials/examples/v1)
for the purpose of demonstrating examples. Implementations
are expected to not use this URI 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 SHOULD 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 § 5.3 Extensibility.
4.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. This specification defines the optional
idproperty for such identifiers. The
idproperty is intended to
unambiguously refer to an object, such as a person, product,
or organization. Using the idproperty allows for the expression of statements
about specific things in the verifiable credential.
The idpropertyMUST express an
identifier that others are expected to use when
expressing statements about a specific thing identified
by that identifier.
Developers should remember that identifiers
might be harmful in scenarios where pseudonymity is
required. Developers are encouraged to read Section
§ 7.3
Identifier-Based Correlation carefully when considering
such scenarios. There are also other types of correlation
mechanisms documented in Section § 7. Privacy
Considerations that create privacy concerns. Where
privacy is a strong consideration, the idpropertyMAY
be omitted.
id
The value of the idpropertyMUST be a single
URI. It is RECOMMENDED that the URI in the id be one which, if
dereferenced, results in a document containing
machine-readable information about the id.
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 subjects, issuers, holders, credential status lists, cryptographic
keys, and other machine-readable information associated
with a verifiable
credential.
4.3
Types
Software systems that process the kinds of objects
specified in this document use type information to determine
whether or not a provided verifiable credential or verifiable presentation is
appropriate. This specification defines a typeproperty for the expression of type
information.
The value of the typepropertyMUST be, or map to (through interpretation of
the @context property), one or more URIs. If more than one URI is
provided, the URIsMUST be interpreted as an unordered set.
Syntactic conveniences SHOULD be used to ease developer usage.
Such conveniences might include JSON-LD terms. It is
RECOMMENDED
that each URI in the type be
one which, if dereferenced, results in a document
containing machine-readable information about the
type.
VerifiableCredential and, optionally, a
more specific verifiable
credentialtype. For
example, "type": ["VerifiableCredential",
"UniversityDegreeCredential"]
VerifiableCredential and, optionally, a
more specific verifiable
credentialtype. For
example, "type": ["VerifiableCredential",
"UniversityDegreeCredential"]
VerifiablePresentation and, optionally,
a more specific verifiable presentationtype. For example, "type": ["VerifiablePresentation",
"CredentialManagerPresentation"]
VerifiablePresentation and, optionally,
a more specific verifiable presentationtype. For example, "type": ["VerifiablePresentation",
"CredentialManagerPresentation"]
A valid evidence type. For
example, "type": "DocumentVerification2018"
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 § 5.3
Extensibility), 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.
All credentials, presentations, and encapsulated objects MUST specify, or be associated
with, additional more narrow types (like
UniversityDegreeCredential, 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 a 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
UniversityDegreeCredential, 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 used in the data model
described in this specification allows for multiple ways to
associate types with data. Implementers and authors are
urged to read the section on typing in the Verifiable
Credentials Implementation Guide [VC-IMP-GUIDE].
The value of the credentialSubjectproperty is defined as a set of objects that
contain one or more properties that are each related to a
subject of the verifiable credential. Each
object MAY contain
an id, as described in Section § 4.2 Identifiers.
Example
6: Usage of
the credentialSubject property
It is possible to express information related to multiple
subjects in a verifiable
credential. The example below specifies two subjects who are spouses. Note the use of array
notation to associate multiple subjects with the
credentialSubject property.
Example 7:
Specifying multiple subjects in a verifiable
credential
The value of the issuerpropertyMUST be either a URI or an object
containing an idproperty. It
is RECOMMENDED that the URI in the issuer or its
id be one which, if dereferenced, results in
a document containing machine-readable information about
the issuer that can be used to
verify the information expressed in the
credential.
The value of the issuerproperty can also be a JWK (for example,
"https://example.com/keys/foo.jwk") or a
DID (for example,
"did:example:abfe13f712120431c276e12ecab").
4.6
Issuance Date
This specification defines the issuanceDateproperty for expressing the date and time when a
credential becomes valid.
issuanceDate
A credentialMUST have an issuanceDateproperty. The value of the
issuanceDatepropertyMUST be a string
value of an [RFC3339] combined date
and time string representing the date and time the
credential becomes valid, which
could be a date and time in the future. Note that this
value represents the earliest point in time at which the
information associated with the
credentialSubjectproperty
becomes valid.
It is expected that the next version of this
specification will add the validFromproperty and will deprecate the
issuanceDateproperty in favor of
a new issuedproperty. The range
of values for both properties are expected to remain as
[RFC3339] combined date and time
strings. Implementers are advised that the
validFrom and issuedproperties are reserved and use for any other
purpose is discouraged.
This specification identifies two classes of proof
mechanisms: external proofs and embedded proofs. An
external
proof is one that wraps an expression of this data
model, such as a JSON Web Token, which is elaborated on in
Section § 6.3.1 JSON Web
Token. An embedded proof is a mechanism
where the proof is included in the data, such as a Linked
Data Signature, which is elaborated upon in Section § 6.3.2 Linked Data Proofs.
When embedding a proof, the proofpropertyMUST
be used.
proof
One or more cryptographic proofs that can be used to
detect tampering and verify the authorship of a credential or presentation. The specific method used for an
embedded proofMUST be included using the
typeproperty.
Because the method used for a mathematical proof varies by
representation language and the technology used, the set of
name-value pairs that is expected as the value of the
proofproperty will vary
accordingly. For example, if digital signatures are used for
the proof mechanism, the proofproperty is expected to have name-value pairs that
include a signature, a reference to the signing entity, and a
representation of the signing date. The example below uses
RSA digital signatures.
Example 10:
Usage of the proof property on a verifiable
credential
As discussed in Section § 1.4
Conformance, there are multiple viable proof
mechanisms, and this specification does not standardize nor
recommend any single proof mechanism for use with verifiable credentials. For more
information about the proof mechanism, see the
following specifications: Linked Data Proofs
[LD-PROOFS], Linked Data Signatures
[LD-SIGNATURES], 2018 RSA Signature
Suite [LDS-RSA2018], and JSON
Web Signature (JWS) Unencoded Payload Option
[RFC7797]. A list of
proof mechanisms is available in the Verifiable Credentials
Extension Registry [VC-EXTENSION-REGISTRY].
4.8
Expiration
This specification defines the expirationDateproperty for the expression of credential expiration information.
expirationDate
If present, the value of the expirationDatepropertyMUST be a string value of an
[RFC3339] combined date
and time string representing the date and time the
credential ceases to be valid.
It is expected that the next version of this
specification will add the validUntilproperty in a way that deprecates, but preserves
backwards compatability with the
expirationDateproperty.
Implementers are advised that the validUntilproperty is reserved and its use for any other
purpose is discouraged.
4.9
Status
This specification defines the following
credentialStatusproperty for the
discovery of information about the current status of a
verifiable credential, such as
whether it is suspended or revoked.
credentialStatus
The value of the credentialStatuspropertyMUST include the:
typeproperty,
which expresses the credential
status type (also referred to as the credential status method). It is expected
that the value will provide enough information to
determine the current status of the credential. For example, the object could
contain a link to an external document noting whether
or not the credential is
suspended or revoked.
The precise contents of the credential
status information is determined by the specific
credentialStatustype 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 Verifiable
Credential Extension Registry [VC-EXTENSION-REGISTRY] exists that
contains available status schemes for implementers who want
to implement verifiable credential
status checking.
The idproperty is
optional and MAY be
used to provide a unique identifier for the presentation. For details related to the use of
this property, see Section § 4.2
Identifiers.
type
The typeproperty is
required and expresses the type of presentation, such as
VerifiablePresentation. For details related
to the use of this property, see Section § 4.3
Types.
Some zero-knowledge cryptography schemes might enable
holders to indirectly prove they hold claims from a verifiable
credential without revealing the verifiable credential itself. In
these schemes, a claim from a verifiable credential might be used
to derive a presented value, which is cryptographically
asserted such that a verifier can trust the
value if they trust the issuer.
For example, a verifiable
credential containing the claimdate of
birth might be used to derive the presented value
over the age of 15 in a manner that is
cryptographically verifiable. That is, a verifier can still trust the derived value if they
trust the issuer.
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 verifiable presentation.
Figure 9 A basic claim expressing that Pat's date of
birth is 2010-01-01T19:23:24Z. Date encoding would be
determined by the schema.
The order of the actions above is not fixed,
and some actions might be taken more than once. Such
action-recurrence might be immediate or at any later
point.
The most comon sequence of actions is envisioned to
be:
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.
Have been transmitted in a way clearly establishing
that the issuer generated the
verifiable
credential and that the verifiable 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
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.
For more information about how this trust model interacts
with various threat models studied by the Working Group, see
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.3
Extensibility
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].
This approach to data modeling 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.
This verifiable credential
states that the entity associated with
did:example:abcdef1234567 has a
name with a value of Jane Doe.
Now let us assume 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, as shown below.
After this JSON-LD context is created, the developer
publishes 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 and credentialtype to the verifiable credential.
Example 16: 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.
Implementers are advised to pay close attention to the
extension points in this specification, such as in Sections
§ 4.7 Proofs
(Signatures), § 4.9 Status,
§ 5.4 Data Schemas,§ 5.5
Refreshing, § 5.6 Terms of
Use, and § 5.7 Evidence.
While this specification does not define concrete
implementations for those extension points, the Verifiable
Credentials Extension Registry [VC-EXTENSION-REGISTRY] provides an
unofficial, curated list of extensions that developers can
use from these extension points.
5.3.1 Semantic Interoperability
This specification ensures that "plain" JSON and JSON-LD
syntaxes are semantically compatible without requiring JSON
implementations to use a JSON-LD processor. To achieve
this, the specification imposes the following additional
requirements on both syntaxes:
JSON-based processors MUST process the @context key,
ensuring the expected values exist in the expected order
for the credential type being processed.
The order is important because keys used in a credential, which are defined using the values
associated with @context, are defined using
a "first defined wins" mechanism and changing the order
might result in a different key definition "winning".
JSON-LD-based processors MUST produce an error when a JSON-LD context
redefines any term in the active
context. The only way to change the definition of
existing terms is to introduce a new term that clears the
active context within the scope of that new term. Authors
that are interested in this feature should read about the
@protected feature in the JSON-LD 1.1
specification.
A human-readable document describing the expected order
of values for the @contextproperty is expected to be published by any
implementer seeking interoperability. A machine-readable
description (that is, a normal JSON-LD Context document) is
expected to be published at the URL specified in the
@contextproperty by JSON-LD
implementers seeking interoperability.
The requirements above guarantee semantic
interoperability between JSON and JSON-LD for terms defined
by the @context mechanism. While JSON-LD
processors will use the specific mechanism provided and can
verify that all terms are correctly specified, JSON-based
processors implicitly accept the same set of terms without
testing that they are correct. In other words, the context
in which the data exchange happens is explicitly stated for
both JSON and JSON-LD by using the same mechanism. With
respect to JSON-based processors, this is achieved in a
lightweight manner, without having to use JSON-LD
processing libraries.
5.4 Data
Schemas
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
considers:
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.
It is important to understand that data schemas serve a
different purpose from the @context property,
which neither enforces data structure or data syntax, nor
enables the definition of arbitrary encodings to alternate
representation formats.
This specification defines the following property for the expression of a data schema:
credentialSchema
The value of the credentialSchemapropertyMUST be one or more data schemas that provide
verifiers with enough
information to determine if the provided data conforms to
the provided schema. Each credentialSchemaMUST specify its
type (for example,
JsonSchemaValidator2018), and an
idproperty that
MUST be a URI identifying the schema file. The precise
contents of each data schema is determined by the
specific type definition.
Note
The credentialSchemaproperty provides an opportunity to annotate type
definitions or lock them to specific versions of the
vocabulary. Authors of verifiable credentials can include
a static version of their vocabulary using
credentialSchema that is locked to some
content integrity protection mechanism. The
credentialSchemaproperty also
makes it possible to perform syntactic checking on the
credential and to use verification mechanisms such as JSON Schema
[JSON-SCHEMA-2018]
validation.
Example 17:
Usage of the credentialSchema property to perform JSON
schema validation
For information about linkages to JSON Schema
[JSON-SCHEMA-2018] or
other optional verification mechanisms, see the
Verifiable Credentials Implementation Guidance
[VC-IMP-GUIDE]
document.
Data schemas can also be used to specify mappings to other
binary formats, such as those used to perform zero-knowledge
proofs. For more information on using the
credentialSchemaproperty with
zero-knowledge proofs, see Section § 5.8 Zero-Knowledge Proofs.
Example 18:
Usage of the credentialSchema property to perform
zero-knowledge validation
In the example above, the issuer is specifying a
credentialSchema pointing 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.
5.5
Refreshing
It is useful for systems to enable the manual or automatic
refresh of an expired verifiable
credential. For more information about expired verifiable credentials, see Section
§ 4.8 Expiration. This specification defines
a refreshServiceproperty, which
enables an issuer to include a link to a
refresh service.
The refresh service is only expected to be used when
either the credential has expired or the
issuer does not publish credential
status information. Issuers are advised
not to put the refreshServiceproperty in a verifiable
credential that does not contain public information or
whose refresh service is not protected in some way.
The value of the refreshServicepropertyMUST be one or more refresh services that
provides enough information to the recipient's software
such that the recipient can refresh the verifiable credential. Each
refreshService value MUST specify its type (for
example, ManualRefreshService2018) and its
id, which is the URL of the service. The
precise content of each refresh service is determined by
the specific refreshServicetype definition.
Example 19:
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 or the verifier to
https://example.edu/refresh/3732.
The value of the termsOfUseproperty tells the verifier what actions
it is required to perform (an obligation), not
allowed to perform (a prohibition), or allowed to
perform (a permission) if it is to accept the
verifiable credential or verifiable presentation.
The value of the termsOfUsepropertyMUST specify one or more terms of use
policies under which the creator issued the credential or presentation. If the recipient (a holder or verifier) is not
willing to adhere to the specified terms of use, then
they do so on their own responsibility and might incur
legal liability if they violate the stated terms of use.
Each termsOfUse value MUST specify its type, for
example, IssuerPolicy, and MAY specify its instance
id. The precise contents of each term of use
is determined by the specific termsOfUsetype definition.
Example 20:
Usage of the termsOfUse property by an issuer
In the example above, the holder (the
assigner), who is also the subject, expressed a term of use prohibiting the
verifier (the assignee,
https://wineonline.example.org) from using the
information provided to correlate the holder or
subject using a third-party service. If the
verifier were to use a third-party service for
correlation, they would violate the terms under which the
holder created the presentation.
This feature is also expected to be used by
government-issued verifiable
credentials to instruct digital wallets to limit their
use to similar government organizations in an attempt to
protect citizens from unexpected usage of sensitive data.
Similarly, some verifiable credentials
issued by private industry are expected to limit usage to
within departments inside the organization, or during
business hours. Implementers are urged to read more about
this rapidly evolving feature in the appropriate section of
the Verifiable Credentials Implementation Guidance
[VC-IMP-GUIDE]
document.
5.7
Evidence
Evidence can be included by an issuer to
provide the verifier with additional supporting
information in a verifiable credential.
This could be used by the verifier to establish
the confidence with which it relies on the claims in the
verifiable credential.
For example, an issuer could check physical
documentation provided by the subject or 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.
This specification defines the evidenceproperty for expressing evidence information.
evidence
The value of the evidencepropertyMUST be one or more evidence schemes
providing enough information for a verifier to determine whether the evidence
gathered by the issuer meets its
confidence requirements for relying on the credential. Each evidence scheme is identified
by its type. The idproperty is optional, but if
present, SHOULD
contain a URL that points to where more information about
this instance of evidence can be found. The precise
content of each evidence scheme is determined by the
specific evidencetype definition.
Note
For information about how attachments and
references to credentials and non-credential
data might be supported by the specification, see the
Verifiable Credentials Implementation Guidance
[VC-IMP-GUIDE]
document.
The evidenceproperty provides different and complementary
information to the proofproperty. The evidenceproperty is used to express supporting
information, such as documentary evidence, related to the
integrity of the verifiable
credential. In contrast, the proofproperty is used to express machine-verifiable
mathematical proofs related to the authenticity of the
issuer and integrity of the verifiable credential. For more
information about the proofproperty, see Section § 4.7 Proofs (Signatures).
5.8 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.
The key capabilities introduced by zero-knowledge proof
mechanisms are the ability of a holder to:
This specification describes a data model that supports
zero-knowledge proof mechanisms. The examples below highlight
how the data model can be used to issue, present, and verify
zero-knowledge verifiable
credentials.
To use zero-knowledge verifiable credentials the issuer must issue a verifiable credential in a manner
that enables the holder to present the information to
a verifier in a privacy-enhancing manner. This
implies that the holder can prove the validity of the
issuer's signature without revealing the values
that were signed, or when only revealing certain selected
values. The standard practice is to do so by proving
knowledge of the signature, without revealing the signature
itself. There are two requirements for verifiable credentials when they are
to be used in zero-knowledge proof systems. The verifiable credentialMUST contain a:
Credential definition, using the
credentialSchemaproperty,
that can be used by all parties to perform various
cryptographic operations in zero-knowledge.
The following example shows one method of using verifiable credentials in
zero-knowledge. It makes use of a CL Signature, which allows
the presentation of the verifiable
credential in a way that supports the privacy of the
holder and subject through the
use of selective disclosure of the verifiable credential values.
Example 23: A
verifiable credential that supports CL Signatures
The example above provides the verifiable credential definition by
using the credentialSchemaproperty and a specific proof that is usable in the
Camenisch-Lysyanskaya Zero-Knowledge Proof system.
Figure 11 A visual example of the relationship between
credentials and derived credentials in a ZKP presentation.
Note
Important details regarding the format for the
credential definition and of the
proofs are omitted on purpose because they are outside of
the scope of this document. The purpose of this section is
to guide implementers who want to extend verifiable credentials and
verifiable presentations to
support zero-knowledge proof systems.
5.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
addressproperty 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.
The mechanism for issuing a DisputeCredential
is the same as for a regular credential except that
the credentialSubject identifier in the
DisputeCredentialproperty is the
identifier of the disputed credential.
For example, if a credential with an
identifier of
https://example.org/credentials/245 is disputed,
the subject can issue the credential shown below and present it to the
verifier along with the disputed credential.
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.
Note
This area of study is rapidly evolving and
developers that are interested in publishing credentials that dispute the veracity of other
credentials are urged to read the
section related to disputes in the Verifiable Credentials
Implementation Guidance [VC-IMP-GUIDE]
document.
5.10
Authorization
This section is non-normative.
Verifiable credentials are intended
as a means of reliably identifying subjects. While
it is recognized that Role Based Access Controls (RBACs) and
Attribute Based Access Controls (ABACs) rely on this
identification as a means of authorizing subjects to access resources, this specification
does not provide a complete solution for RBAC or ABAC.
Authorization is not an appropriate use for this
specification 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.
6.
Syntaxes
The data model as described in Sections § 3. Core Data Model, § 4. Basic
Concepts, and § 5. Advanced
Concepts is the canonical structural representation of a
verifiable credential or verifiable presentation. All
serializations are representations of that data model in a
specific format. This section specifies how the data model is
realized in JSON-LD and plain JSON. Although syntactic mappings
are provided for only these two syntaxes, applications and
services can use any other data representation syntax (such as
XML, YAML, or CBOR) that is capable of expressing the data
model. As the verification and validation requirements are defined in
terms of the data model, all serialization syntaxes have to be
deterministically translated to the data model for processing,
validation, or comparison. This
specification makes no requirements for support of any specific
serialization format.
The expected arity of the property values in this
specification, and the resulting datatype which holds those
values, can vary depending on the property. If present, the
following properties are represented as a single value:
All other properties, if present, are represented as either
a single value or an array of values.
6.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.
Note
As the transformations listed herein have
potentially incompatible interpretations, additional
profiling of the JSON format is required to provide a
deterministic transformation to the data model.
6.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 § 6.1 JSON), with
the addition of the @contextproperty. The JSON-LD
context is described in detail in the [JSON-LD] specification and
its use is elaborated on in Section § 5.3
Extensibility.
Multiple contexts MAY
be used or combined to express any arbitrary information
about verifiable credentials
in idiomatic JSON. 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.
6.2.1 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 likely go unnoticed by most developers, but
whose details will be of interest to implementers. The most
noteworthy syntactic sugars provided by [JSON-LD] are:
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
proofproperties 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.
The @protected properties feature of
[JSON-LD] 1.1 is used
to ensure that terms defined by this specification
cannot be overridden. This means that as long as the
same @context declaration is made at the
top of a verifiable
credential or verifiable presentation,
interoperability is guaranteed for all terms understood
by users of the data model whether or not they use a
[JSON-LD] processor.
6.3
Proof Formats
The data model described in this specification is designed
to be proof format agnostic. This specification does not
normatively require any particular digital proof or signature
format. While the data model is the canonical representation
of a verifiable credential
or verifiable
presentation, the proofing mechanisms for these are often
tied to the syntax used in the transmission of the document
between parties. As such, each proofing mechanism has to
specify whether the validation of the proof is calculated
against the state of the document as transmitted, against the
transformed data model, or against another form. At the time
of publication, at least two proof formats are being actively
utilized by implementers and the Working Group felt that
documenting what these proof formats are and how they are
being used would be beneficial to implementers. The sections
detailing the current proof formats being actively utilized
to issue verifiable credentials
are:
JWT Support is a feature at risk and
may be removed in the Proposed Recommendation due to
implementation maturity concerns. Implementers are
requested to pay particular attention to this section in
general, and specifically, substantive changes made to
processing instructions related to nbf and
iss since the previous Candidate
Recommendation publication. If this section is removed
from the Proposed Recommendation, it is expected to be
published as a separate document for further development
and maturity on a different timeline from this
specification.
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.2 Ecosystem
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.
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 standard verifiable credential and
verifiable
presentationMAY
be omitted to avoid duplication.
JSON Web Token
Extensions
This specification introduces two new registered
claim names, which contain those parts of the
standard verifiable
credentials and verifiable presentations where
no explicit encoding rules for JWT exist. These objects
are enclosed in the JWT payload as follows:
If no explicit rule is specified, properties are encoded in the same way as
with a standard verifiable
credential, and are added to the vcproperty of the JWT. As with
all JWTs, the JWS-based signature of a verifiable credential
represented in the JWT syntax is calculated against the
literal JWT string value as presented across the wire,
before any decoding or transformation rules are
applied. The following paragraphs describe these
encoding rules.
If no JWS is present, a proofpropertyMUST be provided. The proofproperty can be used to
represent a more complex proof, as may be necessary 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
proofproperty. For
backward compatibility reasons, the issuer MUST use JWS to represent
proofs based on a digital signature.
The following rules apply to JOSE headers in the
context of this specification:
algMUST be set for digital signatures. If
only the proofproperty is needed for the chosen
signature method (that is, if there is no choice of
algorithm within that method), 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.
typ, if present, MUST be set to
JWT.
For backward compatibility with JWT processors, the
following JWT-registered claim names MUST be used instead of, or
in addition to, their respective standard verifiable credential
counterparts:
expMUST represent the
expirationDateproperty, encoded as a UNIX timestamp
(NumericDate).
issMUST represent the issuerproperty of a verifiable
credential or the holderproperty of a verifiable presentation.
nbfMUST represent issuanceDate,
encoded as a UNIX timestamp
(NumericDate).
Other JOSE header parameters and claim names not specified herein can be used
if their use is not explicitly discouraged. Additional
claimsMUST be added to the
credentialSubjectproperty
of the JWT.
This version of the specification defines no
JWT-specific encoding rules for the concepts outlined
in Section Advanced
Concepts (for example, refreshService,
termsOfUse, and evidence).
These concepts can be encoded as they are without any
transformation, and can be added to the vcproperty of the JWT.
Note
Implementers are warned that JWTs are not
capable of encoding multiple subjects
and are thus not capable of encoding a verifiable credential with
more than one subject. JWTs
might support multiple subjects in the future and
implementers are advised to refer to the JSON Web
Token Claim Registry for multi-subject JWT claim
names or the
Nested JSON Web Token specification.
JWT Decoding
To decode a JWT to a standard verifiable credential, the
following transformation MUST be performed:
Create a JSON object.
Add the content from the vcproperty to the new JSON
object.
Transform the remaining JWT specific headers and
claims, and add the results
to the new JSON object.
To transform the JWT specific headers and claims, the following MUST be done:
If exp is present, the UNIX
timestamp MUST
be converted to an [RFC3339]
date-time, and MUST be used to set the value of
the expirationDateproperty of
credentialSubject of the new JSON
object.
If iss is present, the value
MUST be used to
set the issuerproperty
of the new verifiable credential JSON object or the
holder property of the new verifiable
presentation JSON object.
If nbf is present, the UNIX
timestamp MUST
be converted to an [RFC3339]
date-time, and MUST be used to set the value of
the issuanceDateproperty of the new JSON object.
If sub is present, the value
MUST be used to
set the value of the idproperty of credentialSubject
of the new JSON object.
If jti is present, the value
MUST be used to
set the value of the idproperty of the new JSON object.
Example 26: JWT header of a JWT-based
verifiable credential using JWS as a proof
(non-normative)
In the example above, the verifiable credential uses a
proof based on JWS digital
signatures, and the corresponding verification key can be obtained using the
kid header parameter.
Example 27: JWT payload of a JWT-based
verifiable credential using JWS as a proof
(non-normative)
In the example above, vc does not
contain the idproperty
because the JWT encoding uses the
jti attribute to represent a unique
identifier. The sub attribute encodes the
information represented by the idproperty of
credentialSubject.
Example 28: 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 30: JWT payload of a JWT based
verifiable presentation (non-normative)
In the example above, vp does not
contain the idproperty
because the JWT encoding uses the
jti attribute to represent a unique
identifier. verifiableCredential contains
a string array of verifiable
credentials using JWT compact
serialization.
Example 31: Verifiable presentation using JWT
compact serialization (non-normative)
This specification utilizes Linked Data to publish
information on the Web using standards, such as URLs and
JSON-LD, to identify subjects and their
associated properties. When information is presented in
this manner, other related information can be easily
discovered and new information can be easily merged into
the existing graph of knowledge. Linked Data is extensible
in a decentralized way, greatly reducing barriers to large
scale integration. The data model in this specification
works well with the Linked Data
Proofs, Linked Data
Signatures, and the associated Linked
Data Cryptographic Suites, which are designed to
protect the data model as described by this
specification.
Unlike the use of JSON Web Token, no extra pre- or
post-processing is necessary. The Linked Data Proofs format
was designed to simply and easily protect verifiable credentials and
verifiable presentations.
Protecting a verifiable
credential or verifiable
presentation is as simple as passing a valid example in
this specification to a Linked Data Signatures
implementation and generating a digital signature.
Note
For more information about the different
qualities of the various syntax formats (for example,
JSON+JWT, JSON-LD+JWT, or JSON-LD+LD-Proofs), see the
Verifiable Credentials Implementation Guidance
[VC-IMP-GUIDE]
document.
7.
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.
7.1 Spectrum of Privacy
This section is non-normative.
It is important to recognize there is a spectrum of
privacy ranging from pseudonymous to strongly identified.
Depending on the use case, people have different comfort
levels about what information they are willing to provide and
what information can be derived from what is provided.
Figure 12 Privacy 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
and the patient. 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.
7.2 Personally Identifiable
Information
This section is non-normative.
Data associated with verifiable
credentials stored in the
credential.credentialSubject field is
susceptible to privacy violations when shared with verifiers. Personally identifying data, such as a
government-issued identifier, shipping address, and full
name, can be easily used to determine, track, and correlate
an entity. Even information that does
not seem personally identifiable, such as the combination of
a birthdate and a postal code, has very powerful correlation
and de-anonymizing capabilities.
Because a verifiable credential
often contains personally identifiable information (PII),
implementers are strongly advised to use mechanisms while
storing and transporting verifiable credentials that protect
the data from those who should not access it. Mechanisms that
could be considered include Transport Layer Security (TLS) or
other means of encrypting the data while in transit, as well
as encryption or data access control mechanisms to protect
the data in a verifiable credential
while at rest.
7.3 Identifier-Based Correlation
This section is non-normative.
Subjects of verifiable credentials are
identified using the
credential.credentialSubject.id field. The
identifiers used to identify a subject create a
greater risk of correlation when the identifiers are
long-lived or used across more than one web domain.
Similarly, disclosing the credential identifier
(credential.id) leads to situations where
multiple verifiers, or an issuer and a verifier, can collude
to correlate the holder. If holders want to
reduce correlation, they should use verifiable credential schemes that
allow hiding the identifier during verifiable presentation. Such
schemes expect the holder to generate the identifier
and might even allow hiding the identifier from the issuer, while still keeping the identifier embedded
and signed in the verifiable
credential.
If strong anti-correlation properties are a requirement in
a verifiable credentials system, it is
strongly advised that identifiers are either:
Bound to a single origin
Single-use
Not used at all, but instead replaced by short-lived,
single-use bearer tokens.
7.4 Signature-Based Correlation
This section is non-normative.
The contents of verifiable
credentials are secured using the
credential.proof field. The properties in this field create a greater risk of
correlation when the same values are used across more than
one session or domain and the value does not change. Examples
include the verificationMethod,
created, proofPurpose, and
jws fields.
If strong anti-correlation properties are required, it is
advised that signature values and metadata are regenerated
each time using technologies like third-party pairwise
signatures, zero-knowledge proofs, or group signatures.
Note
Even when using anti-correlation signatures,
information might still be contained in a verifiable credential that defeats
the anti-correlation properties of the cryptography
used.
7.5 Long-Lived Identifier-Based
Correlation
This section is non-normative.
Verifiable credentials might contain
long-lived identifiers that could be used to correlate
individuals. These types of identifiers include subject identifiers, email addresses,
government-issued identifiers, organization-issued
identifiers, addresses, healthcare vitals, verifiable credential-specific
JSON-LD contexts, and many other sorts of long-lived
identifiers.
Organizations providing software to holders should
strive to identify fields in verifiable credentials containing
information that could be used to correlate individuals and
warn holders when this information is
shared.
7.6 Device Fingerprinting
This section is non-normative.
There are mechanisms external to verifiable credentials that are used
to track and correlate individuals on the Internet and the
Web. Some of these mechanisms include Internet protocol (IP)
address tracking, web browser fingerprinting, evercookies,
advertising network trackers, mobile network position
information, and in-application Global Positioning System
(GPS) APIs. Using verifiable
credentials cannot prevent the use of these other
tracking technologies. Also, when these technologies are used
in conjunction with verifiable
credentials, new correlatable information could be
discovered. For example, a birthday coupled with a GPS
position can be used to strongly correlate an individual
across multiple websites.
It is recommended that privacy-respecting systems prevent
the use of these other tracking technologies when verifiable credentials are being
used. In some cases, tracking technologies might need to be
disabled on devices that transmit verifiable credentials on behalf of
a holder.
7.7 Favor Abstract Claims
This section is non-normative.
To enable recipients of verifiable credentials to use them
in a variety of circumstances without revealing more PII 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 PII 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 ageOverproperty instead of a specific birthdate, which
constitutes much stronger PII. If retailers in a specific
market commonly require purchasers to be older than a certain
age, an issuer trusted in that market might
choose to offer a verifiable
credential claiming that subjects have met that
requirement instead of offering verifiable credentials containing
claims about specific birthdates. This enables
individual customers to make purchases without revealing
specific PII.
7.8 The Principle of Data Minimization
This section is non-normative.
Privacy violations occur when information divulged in one
context leaks into another. Accepted best practice for
preventing such violations is to limit the information
requested, and received, to the absolute minimum necessary.
This data minimization approach is required by regulation in
multiple jurisdictions, including the Health Insurance
Portability and Accountability Act (HIPAA) in the United
States and the General Data Protection Regulation (GDPR) in
the European Union.
With verifiable
credentials, data minimization for issuers means
limiting the content of a verifiable credential to the minimum
required by potential verifiers for expected
use. For verifiers, data minimization means
limiting the scope of the information requested or required
for accessing services.
For example, a driver's license containing a driver's ID
number, height, weight, birthday, and home address is a
credential containing more information than is
necessary to establish that the person is above a certain
age.
It is considered best practice for issuers to
atomize information or use a signature scheme that allows for
selective disclosure. For example,
an issuer of driver's licenses could issue a verifiable credential containing
every attribute that appears on a driver's license, as well
as a set of verifiable credentials
where every verifiable credential
contains only a single attribute, such as a person's
birthday. It could also issue more abstract verifiable credentials (for example,
a verifiable credential containing
only an ageOver attribute). One possible
adaptation would be for issuers to provide
secure HTTP endpoints for retrieving single-use bearer credentials that promote the pseudonymous
usage of verifiable
credentials. Implementers that find this impractical or
unsafe, should consider using selective disclosure schemes that
eliminate dependence on issuers at proving
time and reduce temporal correlation risk from issuers.
Verifiers are urged to only request
information that is absolutely necessary for a specific
transaction to occur. This is important for at least two
reasons. It:
Reduces the liability on the verifier for
handling highly sensitive information that it does not need
to.
Enhances the privacy of the individual by only asking
for information required for a specific transaction.
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.
7.9
Bearer Credentials
This section is non-normative.
A bearer
credential is a privacy-enhancing piece of information,
such as a concert ticket, which entitles the holder of the bearer credential to a specific
resource without divulging sensitive information about the
holder. Bearer credentials are often used in
low-risk use cases where the sharing of the bearer credential
is not a concern or would not result in large economic or
reputational losses.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/temporary/28934792387492384",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2017-10-22T12:23:48Z",
"credentialSubject": {
// note that the 'id' property is not specified for bearer credentials
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": { ... }
}
While bearer credentials can
be privacy-enhancing, they must be carefully crafted so as
not accidentally divulge more information than the holder of the bearer
credential expects. For example, repeated use of the same
bearer credential across multiple
sites enables these sites to potentially collude to unduly
track or correlate the holder. Likewise,
information that might seem non-identifying, such as a
birthdate and postal code, can be used to statistically
identify an individual when used together in the same
bearer credential or session.
Do not contain personally identifying information.
Are not unduly correlatable.
Holders should be warned by their software if
bearer credentials containing
sensitive information are issued or requested, or if there is
a correlation risk when combining two or more bearer credentials across one or more sessions.
While it might be impossible to detect all correlation risks,
some might certainly be detectable.
When processing verifiable
credentials, verifiers are expected to perform
many of the checks listed in Appendix § A.
Validation as well as a variety of specific business
process checks. Validity checks might include checking:
If a relationship exists between the holder and the entity with whom the
holder is attempting to
interact.
The geolocation information associated with the
holder.
The process of performing these checks might result in
information leakage that leads to a privacy violation of the
holder. For example, a simple operation such as
checking a revocation list can notify the issuer that a specific business is likely
interacting with the holder. This could
enable issuers to collude and correlate
individuals without their knowledge.
Issuers are urged to not use mechanisms, such as
credential revocation lists that are unique per
credential, during the verification process
that could lead to privacy violations. Organizations
providing software to holders should warn
when credentials include information that
could lead to privacy violations during the verification
process. Verifiers should consider rejecting
credentials that produce privacy violations or that
enable bad privacy practices.
7.11 Storage Providers and Data Mining
This section is non-normative.
When a holder receives a verifiable credential from an
issuer, the verifiable
credential needs to be stored somewhere (for example, in
a credential repository). Holders are warned that the information in a
verifiable credential is sensitive
in nature and highly individualized, making it a high value
target for data mining. Services that advertise free storage
of verifiable credentials might in fact
be mining personal data and selling it to organizations
wanting to build individualized profiles on people and
organizations.
Holders need to be aware of the terms of service
for their credential repository, specifically
the correlation and data mining protections in place for
those who store their verifiable
credentials with the service provider.
Some effective mitigations for data mining and profiling
include using:
Service providers that do not sell your information to
third parties.
Software that stores verifiable credentials locally on
a device that you control and that does not upload or
analyze your information beyond your expectations.
7.12 Aggregation of Credentials
This section is non-normative.
Holding two pieces of information about the same subject almost always reveals more about the
subject than just the sum of the two pieces, even
when the information is delivered through different channels.
The aggregation of verifiable
credentials is a privacy risk and all participants in the
ecosystem need to be aware of the risks of data
aggregation.
For example, if two bearer
credentials, one for an email address and then one
stating the holder is over the age of 21, are
provided across multiple sessions, the verifier of the information now has a unique
identifier as well as age-related information for that
individual. It is now easy to create and build a profile for
the holder such that more and more
information is leaked over time. Aggregation of credentials can also be performed across multiple
sites in collusion with each other, leading to privacy
violations.
From a technological perspective, preventing aggregation
of information is a very difficult privacy problem to
address. While new cryptographic techniques, such as
zero-knowledge proofs, are being proposed as solutions to the
problem of aggregation and correlation, the existence of
long-lived identifiers and browser tracking techniques
defeats even the most modern cryptographic techniques.
The solution to the privacy implications of correlation or
aggregation tends not to be technological in nature, but
policy driven instead. Therefore, if a holder does not
want information about them to be aggregated, they must
express this in the verifiable
presentations they transmit.
7.13
Usage Patterns
This section is non-normative.
Despite the best efforts to assure privacy, actually using
verifiable credentials can
potentially lead to de-anonymization and a loss of privacy.
This correlation can occur when:
The same verifiable
credential is presented to different verifiers, and either those verifiers collude or a third party has access to
transaction records from both verifiers.
An observant party could infer that the individual
presenting the verifiable
credential is the same person at both services. That
is, the accounts are controlled by the same person.
The underlying information in a
credential can be used to identify an individual
across services. In this case, using information from
other sources (including information provided directly by
the holder), verifiers
can use information inside the credential
to correlate the individual with an existing profile. For
example, if a holder presents credentials that include postal code, age, and
gender, a verifier can potentially
correlate the subject of that credential with an established profile. For
more information, see [DEMOGRAPHICS].
Passing the identifier of a credential to
a centralized revocation server. The centralized server can
correlate the credential usage across
interactions. For example, if a credential
is used for proof of age in this manner, the centralized
service could know everywhere that credential was presented (all liquor stores,
bars, adult stores, lottery purchases, and so on).
In part, it is possible to mitigate this de-anonymization
and loss of privacy by:
Using a globally-unique identifier as the subject for any given credential and
never re-use that credential.
If the credential supports revocation,
using a globally-distributed service for revocation.
Designing revocation APIs that do not depend on
submitting the ID of the credential. For
example, use a revocation list instead of a query.
Avoiding the association of personally identifiable
information with any specific long-lived subject identifier.
It is understood that these mitigation techniques are not
always practical or even compatible with necessary usage.
Sometimes correlation is a requirement.
For example, in some prescription drug monitoring
programs, usage monitoring is a requirement. Enforcement
entities need to be able to confirm that individuals are not
cheating the system to get multiple prescriptions for
controlled substances. This statutory or regulatory need to
correlate usage overrides individual privacy concerns.
Verifiable credentials will also be
used to intentionally correlate individuals across services,
for example, when using a common persona to log in to
multiple services, so all activity on each of those services
is intentionally linked to the same individual. This is not a
privacy issue as long as each of those services uses the
correlation in the expected manner.
Privacy risks of credential usage occur
when unintended or unexpected correlation arises from the
presentation of credentials.
7.14 Sharing Information with the
Wrong Party
This section is non-normative.
When a holder chooses to share information
with a verifier, it might be the case that
the verifier is acting in bad faith and
requests information that could be used to harm the holder. For example, a verifier might
ask for a bank account number, which could then be used with
other information to defraud the holder or the
bank.
Issuers should strive to tokenize as much
information as possible such that if a holder
accidentally transmits credentials to the
wrong verifier, the situation is not
catastrophic.
For example, instead of including a bank account number
for the purpose of checking an individual's bank balance,
provide a token that enables the verifier to
check if the balance is above a certain amount. In this case,
the bank could issue a verifiable
credential containing a balance checking token to a
holder. The holder would then
include the verifiable credential
in a verifiable
presentation and bind the token to a credit checking
agency using a digital signature. The verifier could
then wrap the verifiable
presentation in their digital signature, and hand it back
to the issuer to dynamically check the account balance.
Using this approach, even if a holder shares
the account balance token with the wrong party, an attacker
cannot discover the bank account number, nor the exact value
in the account. And given the validity period for the
counter-signature, does not gain access to the token for more
than a few minutes.
7.15 Frequency of Claim Issuance
This section is non-normative.
As detailed in Section § 7.13 Usage
Patterns, usage patterns can be correlated into certain
types of behavior. Part of this correlation is mitigated when
a holder uses a verifiable
credential without the knowledge of the issuer. Issuers can defeat this protection
however, by making their verifiable credentials short lived
and renewal automatic.
For example, an ageOververifiable credential is useful for
gaining access to a bar. If an issuer issues such a
verifiable credential with a very
short expiration date and an automatic renewal mechanism,
then the issuer could possibly correlate the
behavior of the holder in a way that negatively
impacts the holder.
Organizations providing software to holders should
warn them if they repeatedly use credentials with
short lifespans, which could result in behavior correlation.
Issuers should avoid issuing credentials in a way that enables them to correlate
usage patterns.
7.16 Prefer Single-Use Credentials
This section is non-normative.
An ideal privacy-respecting system would require only the
information necessary for interaction with the verifier to be disclosed by the holder. The verifier would then
record that the disclosure requirement was met and forget any
sensitive information that was disclosed. In many cases,
competing priorities, such as regulatory burden, prevent this
ideal system from being employed. In other cases, long-lived
identifiers prevent single use. The design of any verifiable credentials ecosystem,
however, should strive to be as privacy-respecting as
possible by preferring single-use verifiable credentials whenever
possible.
Using single-use verifiable
credentials provides several benefits. The first benefit
is to verifiers who can be sure that the
data in a verifiable credential
is fresh. The second benefit is to holders, who
know that if there are no long-lived identifiers in the
verifiable credential, the verifiable credential itself cannot
be used to track or correlate them online. Finally, there is
nothing for attackers to steal, making the entire ecosystem
safer to operate within.
7.17
Private Browsing
This section is non-normative.
In an ideal private browsing scenario, no PII will be
revealed. Because many credentials include
PII, organizations providing software to holders should warn them about the possibility of
revealing this information if they wish to use credentials and presentations while in
private browsing mode. As each browser vendor handles private
browsing differently, and some browsers might not have this
feature at all, it is important for implementers to be aware
of these differences and implement solutions accordingly.
8.
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 is not 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.
8.1 Cryptography Suites and Libraries
This section is non-normative.
Some aspects of the data model described in this
specification can be protected through the use of
cryptography. It is important for implementers to understand
the cryptography suites and libraries used to create and
process credentials and presentations. Implementing and auditing
cryptography systems generally requires substantial
experience. Effective red teaming can
also help remove bias from security reviews.
Cryptography suites and libraries have a shelf life and
eventually fall to new attacks and technology advances.
Production quality systems need to take this into account and
ensure mechanisms exist to easily and proactively upgrade
expired or broken cryptography suites and libraries, and to
invalidate and replace existing credentials.
Regular monitoring is important to ensure the long term
viability of systems processing credentials.
8.2 Content Integrity Protection
This section is non-normative.
Verifiable credentials often contain
URLs to data that resides outside of the verifiable credential itself. Linked
content that exists outside a verifiable credential, such as
images, JSON-LD Contexts, and other machine-readable data,
are often not protected against tampering because the data
resides outside of the protection of the proof on the verifiable credential. For example,
the following highlighted links are not content-integrity
protected but probably should be:
While this specification does not recommend any specific
content integrity protection, document authors who want to
ensure links to content are integrity protected are advised
to use URL schemes that enforce content integrity. Two such
schemes are the [HASHLINK] specification and the
[IPFS]. The example below transforms the
previous example and adds content integrity protection to the
JSON-LD Contexts using the [HASHLINK] specification,
and content integrity protection to the image by using an
[IPFS] link.
Example 34:
Content-integrity protection for links to external
data
It is debatable whether the JSON-LD Contexts
above need protection because production implementations
are expected to ship with static copies of important
JSON-LD Contexts.
While the example above is one way to achieve content
integrity protection, there are other solutions that might be
better suited for certain applications. Implementers are
urged to understand how links to external machine-readable
content that are not content-integrity protected could result
in successful attacks against their applications.
8.3
Unsigned Claims
This section is non-normative.
This specification allows credentials to be
produced that do not contain signatures or proofs of any
kind. These types of credentials are often
useful for intermediate storage, or self-asserted
information, which is analogous to filling out a form on a
web page. Implementers should be aware that these types of
credentials are not verifiable because the
authorship either is not known or cannot be trusted.
8.4
Token Binding
This section is non-normative.
A verifier might need to ensure it is
the intended recipient of a verifiable presentation and not the
target of a man-in-the-middle
attack. Approaches such as token binding [RFC8471], which ties the request for a
verifiable presentation to the
response, can secure the protocol. Any unsecured protocol is
susceptible to man-in-the-middle attacks.
8.5 Bundling Dependent Claims
This section is non-normative.
It is considered best practice for issuers to
atomize information in a credential, or use a
signature scheme that allows for selective disclosure. In the
case of atomization, if it is not done securely by the
issuer, the holder might bundle
together different credentials in a way
that was not intended by the issuer.
For example, a university might issue two verifiable credentials to a person,
each containing two properties, which must
be taken together to to designate the "role" of that person
in a given "department", such as "Staff Member" in the
"Department of Computing", or "Post Graduate Student" in the
"Department of Economics". If these verifiable credentials are atomized
to put only one of these properties into each
credential , then the university would issue four
credentials to the person, each containing one of
the following designations: "Staff Member", "Post Graduate
Student", "Department of Computing", and "Department of
Economics". The holder might then transfer the
"Staff Member" and "Department of Economics" verifiable credentials to a verifier, which together would comprise a false
claim.
8.6 Highly Dynamic Information
This section is non-normative.
When verifiable credentials
are issued for highly dynamic information, implementers
should ensure the expiration times are set appropriately.
Expiration periods longer than the timeframe where the
verifiable credential is valid might
create exploitable security vulnerabilities. Expiration
periods shorter than the timeframe where the information
expressed by the verifiable credential
is valid creates a burden on holders and verifiers. It is therefore important to set
validity periods for verifiable
credentials that are appropriate to the use case and the
expected lifetime for the information contained in the
verifiable credential.
8.7 Device Theft and Impersonation
This section is non-normative.
When verifiable credentials
are stored on a device and that device is lost or stolen, it
might be possible for an attacker to gain access to systems
using the victim's verifiable
credentials. Ways to mitigate this type of attack
include:
Enabling password, pin, pattern, or biometric screen
unlock protection on the device.
Enabling password, biometric, or multi-factor
authentication for the credentialrepository.
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. 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 implementation of any web
standard or protocol, ignoring accessibility issues makes this
information unusable by a large subset of the population. It is
important to follow accessibility guidelines and standards,
such as [WCAG21], to ensure that all
people, regardless of ability, can make use of this data. This
is especially important when establishing systems utilizing
cryptography, which have historically created problems for
assistive technologies.
This section details the general accessibility
considerations to take into account when utilizing this data
model.
9.1 Data First Approaches
This section is non-normative.
Many physical credentials in use
today, such as government identification cards, have poor
accessibility characteristics, including, but not limited to,
small print, reliance on small and high-resolution images,
and no affordances for people with vision impairments.
When utilizing this data model to create verifiable credentials, it is
suggested that data model designers use a data first
approach. For example, given the choice of using data or a
graphical image to depict a credential, designers
should express every element of the image, such as the name
of an institution or the professional credential, in a machine-readable way instead of
relying on a viewer's interpretation of the image to convey
this information. Using a data first approach is preferred
because it provides the foundational elements of building
different interfaces for people with varying abilities.
10. Internationalization Considerations
This section is non-normative.
Implementers are advised to be aware of a number of
internationalization considerations when publishing data
described in this specification. As with any web standards or
protocols implementation, ignoring internationalization makes
it difficult for data to be produced and consumed across a
disparate set of languages and societies, which limits the
applicability of the specification and significantly diminishes
its value as a standard.
Implementers are strongly advised to read the Strings on
the Web: Language and Direction Metadata document
[STRING-META], published by
the W3C
Internationalization Activity, which elaborates on the need to
provide reliable metadata about text to support
internationalization. For the latest information on
internationalization considerations, implementers are also
urged to read the Verifiable Credentials Implementation
Guidance [VC-IMP-GUIDE] document.
This section outlines general internationalization
considerations to take into account when utilizing this data
model and is intended to highlight specific parts of the
Strings on the Web: Language and Direction Metadata
document [STRING-META] that
implementers might be interested in reading.
10.1 Language and Base Direction
This section is non-normative.
Data publishers are strongly encouraged to read the
section on Cross-Syntax Expression in the Strings on the
Web: Language and Direction Metadata document
[STRING-META] to ensure
that the expression of language and base direction
information is possible across multiple expression syntaxes,
such as [JSON-LD], [JSON], and CBOR
[RFC7049].
The general design pattern is to use the following markup
template when expressing a text string that is tagged with a
language and, optionally, a specific base direction.
Example 35:
Design pattern for natural language strings
Using the design pattern above, the following example
expresses the title of a book in the English language without
specifying a text direction.
Example 36:
Expressing natural language text as English
"title": {
"value": "HTML and CSS: Designing and Creating Websites",
"lang": "en"
}
The next example uses a similar title expressed in the
Arabic language with a base direction of right-to-left.
Example 37:
Arabic text with a base direction of right-to-left
"title": {
"value": "HTML و CSS: تصميم و إنشاء مواقع الويب",
"lang": "ar"
"dir": "rtl"
}
Note
The text above would most likley be rendered
incorrectly as left-to-right without the explicit
expression of language and direction because many systems
use the first character of a text string to determine text
direction.
Implementers utilizing JSON-LD are strongly urged to
extend the JSON-LD Context
defining the internationalized property and use the
Scoped Context feature of JSON-LD to alias the
@value, @language, and
@direction keywords to value,
lang, and dir, respectively. An
example of a JSON-LD Context snippet doing this is shown
below.
Example 38:
Specifying scoped aliasing for language
information
When multiple languages, base directions, and annotations
are used in a single natural language string, more complex
mechanisms are typically required. It is possible to use
markup languages, such as HTML, to encode text with multiple
languages and base directions. It is also possible to use the
rdf:HTML datatype to encode such values
accurately in JSON-LD.
Despite the ability to encode information as HTML,
implementers are strongly discouraged from doing this because
it:
Requires some version of an HTML processor, which
increases the burden of processing language and base
direction information.
Increases the security attack surface when utilizing
this data model because blindly processing HTML could
result in executing a script tag that an
attacker injected at some point during the data production
process.
If implementers feel they must use HTML, or other markup
languages capable of containing executable scripts, to
address a specific use case, they are advised to analyze how
an attacker would use the markup to mount injection attacks
against a consumer of the markup and then deploy mitigations
against the identified attacks.
A.
Validation
This section is non-normative.
While this specification does not provide conformance
criteria for the process of the validation of verifiable credentials or verifiable presentations, readers
might be curious about how the information in this data model
is expected to be utilized by verifiers during the
process of validation. This section
captures a selection of conversations held by the Working Group
related to the expected usage of the data fields in this
specification by verifiers.
For information on how authentication and
WebAuthn might work with verifiable credentials, see the
Verifiable Credentials Implementation Guidance
[VC-IMP-GUIDE]
document.
A.2
Issuer
This section is non-normative.
The value associated with the issuerproperty is expected to identify an issuer that is known to and trusted by the verifier.
Relevant metadata about the issuerproperty is expected to 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 issued. This metadata is relevant when checking the
proofs on the verifiable
credentials.
A.3
Issuance Date
This section is non-normative.
The issuanceDate is expected to be within an
expected range for the verifier. For example,
a verifier can check that the issuance date of a
verifiable credential is not in the
future.
A.4
Proofs (Signatures)
This section is non-normative.
The cryptographic mechanism used to prove that the
information in a verifiable credential
or verifiable
presentation was not 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 are
expected to ensure:
The proof is available in the form of a known proof
suite.
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 are expected to
ensure:
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 is not suspended, revoked, or expired.
The cryptographic signature is expected to verify.
If the cryptographic suite expects a
proofPurposeproperty, it is
expected to exist and be a valid value, such as
assertionMethod.
Note
The digital signature provides a number of
protections, other than tamper resistance, which are not
immediately obvious. For example, a Linked Data Signature
createdproperty establishes
a date and time before which the credential
should not be considered verified. The
verificationMethodproperty
specifies, for example, the public key that can be used to
verify the digital signature. Dereferencing a public key
URL reveals information about the controller of the key,
which can be checked against the issuer of the credential. The proofPurposeproperty clearly expresses the purpose for the
proof and ensures this information is protected by the
signature. A proof is typically attached to a verifiable presentation for
authentication purposes and to a verifiable credential as a method
of assertion.
A.5
Expiration
This section is non-normative.
The expirationDate is expected to be within
an expected range for the verifier. For example,
a verifier can check that the expiration date of a
verifiable credential is not in the
past.
Fitness for purpose is about whether the custom properties in the verifiable credential are
appropriate for the verifier's purpose.
For example, if a verifier needs to determine whether
a subject is older than 21 years of age, they might
rely on a specific birthdateproperty, or on more 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 trusts
the discount coupon claims made by the corporate
headquarters of the franchise. Policy information expressed
by the issuer in the verifiable credential should be
respected by holders and verifiers unless
they accept the liability of ignoring the policy.
B. Base
Context
This section is non-normative.
The base context, located at
https://www.w3.org/2018/credentials/v1 with a
SHA-256 digest of
ab4ddd9a531758807a79a5b450510d61ae8d147eab966cc9a200c07095b0cdcc,
can be used to implement a local cached copy. For convenience,
the base context is also provided in this section.
This section describes possible relationships between a
subject and a holder and how the
Verifiable Credentials Data Model expresses these
relationships. The following diagram illustrates these
relationships, with the subsequent sections describing how each
of these relationships are handled in the data model.
Figure 13 Subject-Holder Relationships in Verifiable
Credentials.
In this case, the credentialSubjectproperty might contain multiple properties, each providing an aspect of a
description of the subject, which combine
together to 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 40: 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.
Example 41:
The relationship property in a child's credential
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 42: A
relationship credential issued to a parent
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "RelationshipCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1c276e12ec211f712ebc6f",
"child": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"type": "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 43: A
relationship credential issued by a child
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.org/credentials/23894",
"type": ["VerifiableCredential", "RelationshipCredential"],
"issuer": "http://example.org/credentials/23894",
"issuanceDate": "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.
C.5 Subject Passes a Verifiable
Credential to Someone Else
Verifiable credentials are not an authorization
framework and therefore delegation is outside the scope of
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 might be appropriate for some use cases.
Example 45: A
credential issued to a holder who is not the (only)
subject of the credential, who has no relationship with
the subject of the credential, but who has a relationship
with the issuer
C.7 Holder Acts on Behalf of the
Verifier, or has no Relationship with the Subject, Issuer, or
Verifier
This section is non-normative.
The Verifiable Credentials Data Model currently does not
support either of these scenarios. It is for further study
how they might be supported.
D. IANA
Considerations
This section is non-normative.
This section will be submitted to the Internet Engineering
Steering Group (IESG) for review, approval, and registration
with IANA in the "JSON Web Token Claims Registry".
The Working Group would like to thank the following
individuals for reviewing and providing feedback on the
specification (in alphabetical order):
Christopher Allen, David Ammouial, Joe Andrieu, Bohdan
Andriyiv, Ganesh Annan, Kazuyuki Ashimura, Tim Bouma, Pelle
Braendgaard, Dan Brickley, Allen Brown, Jeff Burdges, Daniel
Burnett, ckennedy422, David Chadwick, Chaoxinhu, Kim (Hamilton)
Duffy, Lautaro Dragan, enuoCM, Ken Ebert, Eric Elliott, William
Entriken, David Ezell, Nathan George, Reto Gmür, Ryan Grant,
glauserr, Adrian Gropper, Joel Gustafson, Amy Guy, Lovesh
Harchandani, Daniel Hardman, Dominique Hazael-Massieux,
Jonathan Holt, David Hyland-Wood, Iso5786, Renato Iannella,
Richard Ishida, Ian Jacobs, Anil John, Tom Jones, Rieks
Joosten, Gregg Kellogg, Kevin, Eric Korb, David I. Lehn,
Michael Lodder, Dave Longley, Christian Lundkvist, Jim
Masloski, Pat McBennett, Adam C. Migus, Liam Missin, Alexander
Mühle, Anthony Nadalin, Clare Nelson, Mircea Nistor, Grant
Noble, Darrell O'Donnell, Nate Otto, Matt Peterson, Addison
Phillips, Eric Prud'hommeaux, Liam Quin, Rajesh Rathnam,
Drummond Reed, Yancy Ribbens, Justin Richer, Evstifeev Roman,
RorschachRev, Steven Rowat, Pete Rowley, Markus Sabadello,
Kristijan Sedlak, Tzviya Seigman, Reza Soltani, Manu Sporny,
Orie Steele, Matt Stone, Oliver Terbu, Ted Thibodeau Jr, John
Tibbetts, Mike Varley, Richard Varn, Heather Vescent,
Christopher Lemmer Webber, Benjamin Young, Kaliya Young, Dmitri
Zagidulin, and Brent Zundel.
