Copyright © 2019 W3C ® ( MIT , ERCIM , Keio , Beihang ). W3C liability , trademark and permissive document license rules apply.
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.
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/.
Comments regarding this document are welcome. Please file issues directly on GitHub , or send them to public-vc-comments@w3.org ( subscribe , archives ).
The Working Group seeks implementation feedback, having set the requirement of at least two implementations of each feature as the exit criteria for the Candidate Recommendation phase. The group aims to obtain reports from two producers and two consumers for each feature if possible. For details, see the test suite and sample implementation report .
The
following
features
are
considered
at
risk
of
removal
due
to
potentially
insufficient
implementation
experience
(reports):
credentialSchema
property,
refreshService
property,
evidence
property,
zero-knowledge
proof
support,
disputedClaim
property,
JWT
support,
nonTransferable
property.
Changes since the last publication of this document include:
This document was published by the Verifiable Claims Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-vc-comments@w3.org ( archives ).
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 23 April 2019.
Please see the Working Group's implementation report .
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 .
This document is governed by the 1 March 2019 W3C Process Document .
This section is non-normative.
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:
This section is non-normative.
In the physical world, a credential might consist of:
A verifiable credential can represent all of the same information that a physical credential represents. The addition of technologies, such as digital signatures, makes verifiable credentials more tamper-evident and more trustworthy than their physical counterparts. Holders of verifiable credentials can generate presentations and then share these presentations with verifiers to prove they possess verifiable credentials with certain characteristics. Both verifiable credentials and verifiable presentations can be transmitted rapidly, making them more convenient than their physical counterparts when trying to establish trust at a distance.
While this specification attempts to improve the ease of expressing digital credentials , it also attempts to balance this goal with a number of privacy-preserving goals. The persistence of digital information, and the ease with which disparate sources of digital data can be collected and correlated, comprise a privacy concern that the use of verifiable and easily machine-readable credentials threatens to make worse. This document outlines and attempts to address a number of these issues in Section § 7. Privacy Considerations . Examples of how to use this data model using privacy-enhancing technologies, such as zero-knowledge proofs, are also provided throughout this document.
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:
The ecosystem above is provided as an example to ground the rest of the concepts in this specification. Other ecosystems exist, such as protected environments or proprietary systems, where verifiable credentials also provide benefit.
This section is non-normative.
The Verifiable Credentials Use Cases [ VC-USECASES ] document outlines a number of key topics that readers might find useful, including:
As a result of documenting and analyzing the use cases document, the following desirable ecosystem characteristics were identified for this specification:
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 are to be interpreted as described in [ RFC2119 ].
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 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.
This section is non-normative.
The following terms are used to describe concepts in this specification.
did:example:123456abcdef
.
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.
This section is non-normative.
A claim is a statement about a subject . A subject is an entity about which claims can be made. Claims are expressed using subject - property - value relationships.
The data model for claims described 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 below.
Individual claims can be merged together to express a graph of information about a subject . The example below extends the previous claim by adding the claims that Pat knows Sam and that Sam is employed as a professor.
To this point, the concepts of a claim and a graph of information are introduced. To be able to trust claims , more information must be added.
This section is non-normative.
A credential is a set of one or more claims made by the same entity . Credentials might also include an identifier and metadata to describe properties of the credential , such as the issuer , the expiry date and time, a representative image, a public key to use for verification purposes, the revocation mechanism, and so on. The metadata might be signed by the issuer . A verifiable credential is a set of tamper-evident claims and metadata that cryptographically prove who issued it.
Examples of verifiable credentials include digital employee identification cards, digital birth certificates, and digital educational certificates.
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 credential itself, which contains credential metadata and claims . The second graph expresses the digital proof , which is usually a digital signature.
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.
This section is non-normative.
Enhancing privacy is a key design feature of this specification. Therefore, it is important for entities using this technology to be able to express only the portions of their persona that are appropriate for a given situation. The expression of a subset of one's persona is called a verifiable presentation . Examples of different personas include a person's professional persona, their online gaming persona, their family persona, or an incognito persona.
A verifiable presentation expresses data from one or more verifiable credentials , and is packaged in such a way that the authorship of the data is verifiable . If credentials are directly presented, they become a presentation . Data formats derived from credentials that are cryptographically verifiable but do not of themselves contain credentials , might also be presentations .
The data in a presentation is often about the same subject , but was issued by multiple issuers . The aggregation of this information typically expresses an aspect of a person, organization, or entity .
Figure
7
above
shows
the
components
of
a
verifiable
presentation
,
but
abstracts
the
details
about
how
verifiable
credentials
are
organized
into
information
graphs
,
which
are
then
organized
into
verifiable
presentations
.
Figure
8
below
shows
a
more
complete
depiction
of
a
verifiable
presentation
,
which
is
normally
composed
of
at
least
four
information
graphs
.
The
first
graph
expresses
the
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.
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.
This section is non-normative.
The previous sections introduced the concepts of claims , credentials , and presentations using graphical depictions. This section provides a concrete set of simple but complete lifecycle examples of the data model expressed in one of the concrete syntaxes supported by this specification. The lifecycle of credentials and presentations in the Verifiable Credentials Ecosystem often take a common path:
We will use concrete examples to illustrate the lifecycle above by demonstrating how to redeem an alumni discount from a university. In the example below, Pat receives an alumni credential from a university that will be stored in Pat's digital wallet.
{ // set the context, which establishes the special terms we will be using // such as 'issuer' and 'alumniOf'. "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], // specify the identifier for the credential "id": "http://example.edu/credentials/1872", // the credential types, which declare what data to expect in the credential "type": ["VerifiableCredential", "AlumniCredential"], // the entity that issued the credential "issuer": "https://example.edu/issuers/565049", // when the credential was issued "issuanceDate": "2010-01-01T19:73:24Z", // claims about the subject of the credential "credentialSubject": { // identifier for the subject of the credential "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", // assertion about the subject of the credential "alumniOf": "<span lang='en'>Example University</span>" }, // digital proof that makes the credential tamper-evident "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", // the public key identifier that created the signature "creator": "https://example.edu/issuers/keys/1", // the digital signature value "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj PAYuNzVBAh4vGHSrQyHUdBBPM" } }
Pat then presents the alumni credential above in order to receive a discount. The verifier , a ticket sales system, states that any alumni of "Example University" receives a discount on season tickets to sporting events. Using a mobile device, Pat starts the process of purchasing a season ticket. A step in the process requests an alumni credential and the request is routed to Pat's digital wallet. The digital wallet asks Pat if they would like to provide the previously issued verifiable credential . Pat selects the verifiable credential , which is then composed into a verifiable presentation . The verifiable presentation is then sent to the verifier and verified .
{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "type": "VerifiablePresentation", // the verifiable credential issued in the previous example "verifiableCredential": [{ "id": "http://example.edu/credentials/1872", "type": ["VerifiableCredential", "AlumniCredential"], "issuer": "https://example.edu/issuers/565049", "issuanceDate": "2010-01-01T19:73:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "alumniOf": "<span lang='en'>Example University</span>" }, "proof": { "type": "RsaSignature2018", "created": "2017-06-18T21:19:10Z", "creator": "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 establishes consent and // protects against replay attacks "proof": { "type": "RsaSignature2018", "created": "2018-09-14T21:19:10Z", "creator": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1", // 'nonce' and 'domain' protect against replay attacks "nonce": "1f44d55f-f161-4938-a659-f8026467f126", "domain": "4jt78h47fh47", "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..kTCYt5 XsITJX1CxPCT8yAV-TVIw5WEuts01mq-pQy7UJiN5mgREEMGlv50aqzpqh4Qq_PbChOMqs LfRoPsnsgxD-WUcX16dUOqV0G_zS245-kronKb78cPktb3rk-BuQy72IFLN25DYuNzVBAh 4vGHSrQyHUGlcTwLtjPAnKb78" } }
This section introduces some basic concepts for the specification, in preparation for Section § 5. Advanced Concepts later in the document.
When
two
software
systems
need
to
exchange
data,
they
must
use
terminology
and
a
protocol
that
both
systems
understand.
As
an
analogy,
consider
how
two
people
communicate.
Both
people
must
use
the
same
language
and
the
words
they
use
must
mean
the
same
thing
to
each
other.
This
is
often
referred
to
as
"the
context
in
which
a
conversation
happens".
This
specification
defines
the
use
of
the
@context
property
when
communicating
information
related
to
specific
verifiable
credentials
or
verifiable
presentations
.
Verifiable
credentials
and
verifiable
presentations
MUST
include
a
@context
property
.
@context
property
MUST
be
an
ordered
set
where
the
first
item
is
a
URI
with
the
value
https://www.w3.org/2018/credentials/v1
.
Subsequent
items
in
the
array
MUST
be
composed
of
any
combination
of
URI
s
or
objects
that
express
context
information.
It
is
RECOMMENDED
that
dereferencing
the
URIs
results
in
a
document
containing
machine-readable
information
about
the
context.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/58473",
"type": ["VerifiableCredential", "AlumniCredential"],
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"alumniOf": "<span lang='en'>Example University</span>"
},
"proof": { ... }
}
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.
This
document
uses
the
examples
context
URI
(
https://www.w3.org/2018/credentials/examples/v1
)
for
the
purposes
of
demonstrating
examples.
The
examples
context
URI
MUST
NOT
be
used
for
any
other
purpose,
such
as
in
pilot
or
production
systems.
The
data
available
at
https://www.w3.org/2018/credentials/v1
is
a
static
document
that
is
never
updated
and
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
.
The specific location and content in the JSON-LD Context URLs used throughout this document may change during the W3C Candidate Recommendation phase based on implementer feedback. The test suite will reflect any changes to the URLs or content located at the URLs.
When
expressing
statements
about
a
specific
thing,
such
as
a
person,
product,
or
organization,
it
is
often
useful
to
use
some
kind
of
identifier
so
that
others
can
express
statements
about
the
same
thing.
Identifiers
that
others
are
expected
to
use
when
expressing
statements
about
a
specific
thing
MUST
be
expressed
using
the
id
property
.
Developers
should
remember
that
identifiers
might
be
harmful
in
scenarios
where
pseudonymity
is
required.
Developers
are
encouraged
to
read
Section
§ 7.
Privacy
Considerations
carefully
when
considering
such
scenarios.
Where
privacy
is
a
strong
consideration,
the
id
property
MAY
be
omitted.
id
property
MUST
be
a
single
URI
.
It
is
RECOMMENDED
that
dereferencing
the
URI
results
in
a
document
containing
machine-readable
information
about
the
identifier.
{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "id": "http://example.edu/credentials/3732", "type": ["VerifiableCredential", "UniversityDegreeCredential"], "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "BachelorDegree", "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>" } }, "proof": { ... } }
The example above uses two types of identifiers. The first identifier is for the credential and uses an HTTP-based URL. The second identifier is for the subject of the credential (the thing the claims are about) and uses a decentralized identifier , also known as a DID .
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 that is associated with a verifiable credential .
Software
systems
that
process
the
kinds
of
objects
specified
in
this
document
use
type
information
to
determine
whether
or
not
a
provided
credential
or
presentation
is
appropriate.
This
specification
defines
a
type
property
for
the
expression
of
type
information.
Verifiable
credentials
and
verifiable
presentations
MUST
have
a
type
property
.
type
property
MUST
be,
or
map
to,
one
or
more
URIs
.
If
more
than
one
URI
is
provided,
the
URIs
MUST
be
interpreted
as
an
unordered
set.
Syntactic
conveniences,
such
as
JSON-LD
terms,
SHOULD
be
used
to
ease
developer
usage.
It
is
RECOMMENDED
that
dereferencing
the
URIs
results
in
a
document
containing
machine-readable
information
about
the
type.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
}
},
"proof": { ... }
}
With respect to this specification, the following table lists examples of objects that MUST have a type specified.
Object | Type |
---|---|
Credential object |
VerifiableCredential
and
a
more
specific
credential
type
.
For
example,
"type":
["VerifiableCredential",
"UniversityDegreeCredential"]
|
Presentation object |
VerifiablePresentation
and
a
more
specific
presentation
type
.
For
example,
"type":
["VerifiablePresentation",
"CredentialManagerPresentation"]
|
proof object |
A
valid
proof
type
.
For
example,
"type":
"RsaSignature2018"
|
credentialStatus object |
A
valid
credential
status
type
.
For
example,
"type":
"CredentialStatusList2017"
|
termsOfUse object |
A
valid
terms
of
use
type
.
For
example,
"type":
"OdrlPolicy2017"
)
|
evidence object |
A
valid
evidence
type
.
For
example,
"type":
"DocumentVerification2018"
|
All
credentials
,
presentations
,
and
encapsulated
objects
MUST
specify,
or
be
associated
with,
additional
more
narrow
types
(like
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
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:
id
property.
type
property.
name
property.
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.
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.
A
verifiable
credential
contains
claims
about
one
or
more
subjects
.
This
specification
defines
a
credentialSubject
property
for
the
expression
of
claims
about
one
or
more
subjects
.
A
verifiable
credential
MUST
have
a
credentialSubject
property
.
credentialSubject
property
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
.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
}
},
"proof": { ... }
}
This specification defines a property for expressing the issuer of a verifiable credential . A verifiable credential MUST contain the following property :
issuer
property
MUST
either
be
a
URI
or
an
object
containing
a
id
property.
It
is
RECOMMENDED
that
dereferencing
the
URI
,
or
the
id
property,
results
in
a
document
containing
machine-readable
information
about
the
issuer
that
can
be
used
to
verify
the
information
expressed
in
the
credential
.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
}
},
"proof": { ... }
}
This specification defines the following property for expressing the date and time when the credential was issued:
issuanceDate
property
.
The
value
of
the
issuanceDate
property
MUST
be
a
string
value
of
an
[
RFC3339
]
combined
date
and
time
string
representing
the
date
and
time
the
credential
was
issued.
Note
that
this
date
represents
the
earliest
date
when
the
information
associated
with
the
credentialSubject
property
became
valid.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
}
},
"proof": { ... }
}
For a credential or presentation to be verifiable , at least one proof mechanism MUST be expressed. 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 upon 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 following property MUST be used:
type
property
.
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
proof
property
will
vary
accordingly.
For
example,
if
digital
signatures
are
used
for
the
proof
mechanism,
the
proof
property
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.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.gov/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu",
"issuanceDate": "2010-01-01T19:73:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
}
},
"proof": {
"type": "RsaSignature2018",
"created": "2018-06-18T21:19:10Z",
"verificationMethod": "https://example.com/jdoe/keys/1",
"signatureValue": "BavEll0/I1zpYw8XNi1bgVg/sCneO4Jugez8RwDg/+
MCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuFibcC1wps
PRdW+gGsutPTLzvueMWmFhwYmfIFpbBu95t501+rSLHIEuujM/+PXr9Cky6Ed
+W3JT24="
}
}
No single proof mechanism is currently standardised or recommended for verifiable credentials.
This specification defines the following property for the expression of credential expiration information:
expirationDate
property
MUST
be
a
string
value
of
an
[
RFC3339
]
combined
date
and
time
string
representing
the
date
and
time
the
credential
ceases
to
be
valid.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"expirationDate": "2020-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
}
},
"proof": { ... }
}
This specification defines the following property for the discovery of information about the current status of a verifiable credential , such as whether it is suspended or revoked:
credentialStatus
property
MUST
include
the:
id
property
,
which
MUST
be
a
URL.
type
property
,
which
expresses
the
credential
status
type
(also
referred
to
as
the
credential
status
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
verifiable
credential
is
suspended
or
revoked.
The
precise
contents
of
the
credential
status
information
is
determined
by
the
specific
credentialStatus
type
definition,
and
varies
depending
on
factors
such
as
whether
it
is
simple
to
implement
or
if
it
is
privacy-enhancing.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
}
},
"credentialStatus": {
"id": "https://example.edu/status/24",
"type": "CredentialStatusList2017"
},
"proof": { ... }
}
Defining the data model, formats, and protocols for status schemes are out of scope for this specification. A status scheme registry [ VC-STATUS-REGISTRY ] exists for implementers who want to implement credential status checking.
Verifiable presentations MAY be used to combine and present verifiable credentials .
If verifiable presentations are used, they MUST be constructed from verifiable credentials themselves, or of data derived from verifiable credentials in a cryptographically verifiable format.
The example below shows a verifiable presentation that embeds verifiable credentials .
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
"type": ["VerifiablePresentation"],
"verifiableCredential": [{ ... }],
"proof": [{ ... }]
}
The
contents
of
the
verifiableCredential
property
shown
above
are
verifiable
credentials
,
as
described
by
this
specification.
The
contents
of
the
proof
property
are
proofs,
as
described
by
the
Linked
Data
Proofs
[
LD-PROOFS
]
specification.
The
id
property
is
optional
and
MAY
be
used
to
provide
a
unique
identifier
for
the
presentation.
The
value
associated
with
the
id
property
MUST
be
a
URI
.
Some zero-knowledge cryptography schemes might enable holders to indirectly prove they hold a credential without revealing the credential itself. In these schemes, the original attribute, such as date of birth, might be translated into another value, such as "over the age of 15", which is cryptographically asserted such that a verifier can trust the value if they trust the issuer .
For an example of a ZKP-style verifiable presentation that contains derived data instead of directly embedded verifiable credentials, please see Section § 5.8 Zero-Knowledge Proofs .
If a presentation supports derived predicates , a claim about birthdate in a credential can become the basis of proof that at a given point in time, the age of a subject did or will fall within a specified range. Selective disclosure schemes using zero-knowledge proofs can use claims expressed in this model to prove additional statements about those claims . For example, a claim specifying a subject's date of birth can be used as a predicate to prove the subject's age is within a given range, and therefore prove the subject qualifies for age-related discounts, without actually revealing the subject's birthdate. The holder has the flexibility to use the claim in any way that is applicable to the desired presentation .
Building on the concepts introduced in Section § 4. Basic Concepts , this section explores more complex topics about verifiable credentials .
This section is non-normative.
Section § 1.2 Ecosystem Overview provided an overview of the verifiable credential ecosystem. This section provides more detail about how the ecosystem is envisaged to operate, as follows:
The order of the steps above are not fixed and some steps might be repeated.
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:
In particular, Sections § 5.6 Terms of Use and § B. Subject-Holder Relationships specify how a verifier can determine:
This section is non-normative.
The verifiable credentials trust model is as follows:
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 [ VC-USECASES ] document.
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.
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:
This approach to data modelling is often called an open world assumption , meaning that any entity can say anything about any other entity. While this approach seems to conflict with building simple and predictable software systems, balancing extensibility with program correctness is always more challenging with an open world assumption than with closed software systems.
The rest of this section describes, through a series of examples, how both extensibility and program correctness are achieved.
Let us assume we start with the verifiable credential shown below.
{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "id": "http://example.com/credentials/4643", "type": ["VerifiableCredential"], "issuer": "https://example.com/issuers/14", "issuanceDate": "2018-02-24T05:28:04Z", "credentialSubject": { "id": "did:example:abcdef1234567", "name": "Jane Doe" }, "proof": { ... } }
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.
{ "@context": { "referenceNumber": "https://example.com/vocab#referenceNumber", "favoriteFood": "https://example.com/vocab#favoriteFood" } }
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
credential
type
to
the
verifiable
credential
.
{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://example.com/contexts/mycontext.jsonld" ], "id": "http://example.com/credentials/4643", "type": ["VerifiableCredential", "CustomExt12"], "issuer": "https://example.com/issuers/14", "issuanceDate": "2018-02-24T05:28:04Z", "referenceNumber": 83294847, "credentialSubject": { "id": "did:example:abcdef1234567", "name": "Jane Doe", "favoriteFood": "Papaya" }, "proof": { ... } }
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.
This specification endeavors to enable both the JSON and JSON-LD syntaxes to be semantically compatible with one another without the JSON implementations needing to process the documents as JSON-LD. To achieve this, the specification imposes the following additional restrictions on both syntaxes:
@context
property
,
ensuring
the
expected
values
exist
in
the
expected
order
for
the
credential
type
being
processed.
It
is
advised
that
the
expected
order
of
values
of
the
@context
property
should
be
defined
by
at
least
a
human-readable
extension
specification
and
preferably
by
a
machine-readable
specification
as
well.
@protected
feature
in
the
JSON-LD
1.1
specification.
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:
This specification defines the following property for the expression of a data schema:
credentialSchema
property
MUST
be
one
or
more
data
schemas
that
provide
verifiers
with
enough
information
to
determine
if
the
provided
data
conforms
to
the
provided
schema.
Each
credentialSchema
MUST
specify
its
type
(for
example,
JsonSchemaValidator2018
),
and
an
id
property
that
MUST
be
a
URI
identifying
the
schema
file.
The
precise
contents
of
each
data
schema
is
determined
by
the
specific
type
definition.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
}
},
"credentialSchema": {
"id": "https://example.org/examples/degree.json",
"type": "JsonSchemaValidator2018"
},
"proof": { ... }
}
In
the
example
above,
the
issuer
is
specifying
a
credentialSchema
,
which
points
to
a
[
JSON-SCHEMA
]
file
that
can
be
used
by
a
verifier
to
determine
if
the
verifiable
credential
is
well
formed.
For information about linkages to JSON Schema or other optional verification mechanisms, please refer to the Verifiable Credentials Implementation Guidelines .
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
credentialSchema
property
with
zero-knowledge
proofs,
see
Section
§ 5.8
Zero-Knowledge
Proofs
.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
}
},
"credentialSchema": {
"id": "https://example.org/examples/degree.zkp",
"type": "ZkpExampleSchema2018"
},
"proof": { ... }
}
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.
The usage of the Data Schemas property may change during the W3C Candidate Recommendation process based on implementer feedback. Specifically, the location of its usage may be expanded. It may also be removed if there is not enough implementation support.
It is useful for systems to enable the manual or automatic refresh of a expired verifiable credential . This specification enables an issuer to include a link to a refresh service.
The
issuer
can
include
the
refresh
service
as
an
element
inside
the
verifiable
credential
if
it
is
intended
for
either
the
verifier
or
the
holder
(or
both),
or
inside
the
verifiable
presentation
if
it
is
intended
for
the
holder
only.
Including
the
refresh
reference
inside
In
the
verifiable
presentation
latter
case,
this
enables
the
holder
to
refresh
the
verifiable
credential
details
before
creating
a
verifiable
presentation
to
share
with
a
verifier
,
while
.
In
the
former
case,
including
the
refresh
reference
service
inside
the
verifiable
credential
enables
both
the
holder
and
the
verifier
<>verifier
to
perform
future
updates
of
the
credential
.
credential.
This specification defines the following property for expressing a refresh service:
refreshService
property
MUST
be
one
or
more
refresh
services
that
provides
enough
information
to
the
recipient's
software
such
that
the
recipient
can
refresh
the
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
refreshService
type
definition.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
}
},
"refreshService": {
"id": "https://example.edu/refresh/3732"
"type": "ManualRefreshService2018",
},
"proof": { ... }
}
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 refresh service may change based on implementer feedback, including being removed from the specification if there is not enough implementer support for the feature.
Terms of use can be utilized by an issuer or a holder to communicate the terms under which a verifiable credential or verifiable presentation was issued. The issuer places their terms of use inside the credential . The holder places their terms of use inside a presentation . The value of this property tells the verifier what actions it must perform (an obligation ), must not perform (a prohibition ), or may perform (a permission ) if it is to accept the verifiable credential or verifiable presentation .
Further study is required to determine how a subject who is not a holder places terms of use on their verifiable credentials . One way could be for the subject to request the issuer to place the terms of use inside the issued verifiable credentials . Another way could be for the subject to delegate a verifiable credential to a holder and placing terms of use restrictions on the delegated verifiable credential .
This specification defines the following property for expressing terms of use:
termsOfUse
property
MUST
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
termsOfUse
type
definition.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
}
},
"termsOfUse": [{
"type": "IssuerPolicy",
"id": "http://example.com/policies/credential/4",
"profile": "http://example.com/profiles/credential",
"prohibition": [{
"assigner": "https://example.edu/issuers/14",
"assignee": "AllVerifiers",
"target": "http://example.edu/credentials/3732",
"action": ["Archival"]
}]
},
"proof": { ... }
}
In
the
example
above,
the
issuer
(the
assigner
)
is
prohibiting
verifiers
(the
assignee
)
from
storing
the
data
in
an
archive.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"type": "VerifiablePresentation",
"verifiableCredential": [{
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
}
},
"proof": { ... }
}],
"termsOfUse": [{
"type": "HolderPolicy",
"id": "http://example.com/policies/credential/6",
"profile": "http://example.com/profiles/credential",
"prohibition": [{
"assigner": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"assignee": "https://wineonline.example.org/",
"target": "http://example.edu/credentials/3732",
"action": ["3rdPartyCorrelation"]
}]
},
"proof": [ ... ]
}
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.
The terms of use feature may change during the W3C Candidate Recommendation phase including being removed entirely if there is not enough implementer support for the feature.
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 following property for expressing evidence information:
evidence
property
MUST
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
id
property
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
evidence
type
definition.
For information on how attachments and references to credentials and non-credential data may be supported by the specification, please refer to the Verifiable Credentials Implementation Guidelines .
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
}
},
"evidence": [{
"id": "https://example.edu/evidence/f2aeec97-fc0d-42bf-8ca7-0548192d4231",
"type": ["DocumentVerification"],
"verifier": "https://example.edu/issuers/14",
"evidenceDocument": "DriversLicense",
"subjectPresence": "Physical",
"documentPresence": "Physical"
},{
"id": "https://example.edu/evidence/f2aeec97-fc0d-42bf-8ca7-0548192dxyzab",
"type": ["SupportingActivity"],
"verifier": "https://example.edu/issuers/14",
"evidenceDocument": "Fluid Dynamics Focus",
"subjectPresence": "Digital",
"documentPresence": "Digital"
}],
"proof": { ... }
}
The
evidence
property
provides
different
and
complimentary
information
to
the
proof
property
.
The
evidence
property
is
used
to
express
supporting
information,
such
as
documentary
evidence,
related
to
the
integrity
of
the
credential
.
In
contrast,
the
proof
property
is
used
to
express
machine-verifiable
mathematical
proofs
related
to
the
authenticity
of
the
issuer
and
integrity
of
the
credential
.
The evidence feature may change during the W3C Candidate Recommendation phase based on implementer feedback, or be removed entirely due to lack of support by implementers.
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:
This specification describes a data model that supports zero-knowledge proof mechanisms. The examples below highlight how the data model may 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 will be able to 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 following example shows one method of using verifiable credential s 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 credential values.
{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "type": ["VerifiableCredential", "UniversityDegreeCredential"], "credentialSchema": { "id": "did:example:cdf:35LB7w9ueWbagPL94T9bMLtyXDj9pX5o", "type": "did:example:schema:22KpkXgecryx9k7N6XN1QoN3gXwBkSU8SfyyYQG" }, "issuer": "did:example:Wz4eUg7SetGfaUVCn8U9d62oDYrUJLuUtcy619", "credentialSubject": { "givenName": "Jane", "familyName": "Doe", "degree": { "type": "BachelorDegree", "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>", "college": "College of Engineering" } }, "proof": { "type": "AnonCredv1", "issuerData": "5NQ4TgzNfSQxoLzf2d5AV3JNiCdMaTgm...BXiX5UggB381QU7ZCgqWivUmy4D", "attributes": "pPYmqDvwwWBDPNykXVrBtKdsJDeZUGFA...tTERiLqsZ5oxCoCSodPQaggkDJy", "signature": "8eGWSiTiWtEA8WnBwX4T259STpxpRKuk...kpFnikqqSP3GMW7mVxC4chxFhVs", "signatureCorrectnessProof": "SNQbW3u1QV5q89qhxA1xyVqFa6jCrKwv...dsRypyuGGK3RhhBUvH1tPEL8orH" } }
The
example
above
provides
the
credential
definition
by
using
the
credentialSchema
property
and
a
specific
proof
that
is
usable
in
the
Camenisch-Lysyanskaya
Zero-Knowledge
Proof
system.
The next example utilizes the verifiable credential above to generate a new derived verifiable credential with a privacy-preserving proof. The derived verifiable credential is then placed in a verifiable presentation that further proves that the entire assertion is valid. There are three requirements of most verifiable presentations when they are to be used in zero-knowledge systems:
{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "type": "VerifiablePresentation", "verifiableCredential": [{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "type": ["VerifiableCredential", "UniversityDegreeCredential"], "credentialSchema": { "id": "did:example:cdf:35LB7w9ueWbagPL94T9bMLtyXDj9pX5o", "type": "did:example:schema:22KpkXgecryx9k7N6XN1QoN3gXwBkSU8SfyyYQG" }, "issuer": "did:example:Wz4eUg7SetGfaUVCn8U9d62oDYrUJLuUtcy619", "credentialSubject": { "degreeType": "BachelorDegree", "degreeSchool": "College of Engineering" } }, "proof": { "type": "AnonCredDerivedCredentialv1", "primaryProof": "cg7wLNSi48K5qNyAVMwdYqVHSMv1Ur8i...Fg2ZvWF6zGvcSAsym2sgSk737", "nonRevocationProof": "mu6fg24MfJPU1HvSXsf3ybzKARib4WxG...RSce53M6UwQCxYshCuS3d2h" } }], "proof": { "type": "AnonCredPresentationProofv1", "proofValue": "DgYdYMUYHURJLD7xdnWRinqWCEY5u5fK...j915Lt3hMzLHoPiPQ9sSVfRrs1D" } }
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 wanting to extend verifiable credentials and verifiable presentations to support zero-knowledge proof systems.
Zero Knowledge Proofs are a feature at risk. The Working Group is looking for multiple implementers to support the feature during the W3C Candidate Recommendation phase.
There are at least two different cases to consider for an entity wanting to dispute a credential issued by an issuer :
address
property
is
incorrect
or
out
of
date.
Only
the
subject
of
a
verifiable
credential
is
entitled
to
issue
a
DisputeCredential
.
A
DisputeCredential
issued
by
anyone
other
than
the
subject
should
be
disregarded
by
the
verifier
,
unless
the
verifier
has
some
other
way
of
determining
the
truth
of
the
dispute.
This
is
to
prevent
denial
of
service
attacks
whereby
an
attacker
falsely
disputes
a
true
claim.
The
mechanism
for
issuing
a
DisputeCredential
is
the
same
as
for
a
regular
credential
except
that
the
credentialSubject
identifier
in
the
DisputeCredential
property
is
the
identifier
of
the
disputed
credential
.
For
example,
if
a
credential
with
an
identifier
of
https://example.org/credentials/245
is
disputed,
an
entity
can
issue
one
of
the
credentials
shown
below.
In
the
first
example,
the
subject
might
present
this
to
the
verifier
along
with
the
disputed
credential
.
In
the
second
example,
the
entity
might
publish
the
DisputeCredential
in
a
public
venue
to
make
it
known
that
the
credential
is
disputed.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.com/credentials/123",
"type": ["VerifiableCredential", "DisputeCredential"],
"credentialSubject": {
"id": "http://example.com/credentials/245",
"currentStatus": "Disputed",
"statusReason": {
"@value": "Address is out of date",
"@language": "en"
},
},
"issuer": "https://example.com/people#me",
"issuanceDate": "2017-12-05T14:27:42Z",
"proof": { ... }
}
{
"@context": "https://w3id.org/credentials/v1",
"id": "http://example.com/credentials/321",
"type": ["VerifiableCredential", "DisputeCredential"],
"credentialSubject": {
"id": "http://example.com/credentials/245",
"currentStatus": "Disputed",
"statusReason": {
"@value": "Credential contains disputed statements",
"@language": "en"
},
"disputedClaim": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"address": "Is Wrong"
}
},
"issuer": "https://example.com/people#me",
"issuanceDate": "2017-12-05T14:27:42Z",
"proof": { ... }
}
In the above credential the issuer is claiming that the address in the disputed credential is wrong. For example, the subject might wrongly be claiming to have the same address as that of the issuer .
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.
The dispute feature may change significantly during the W3C Candidate Recommendation process including possibly being removed if there is not enough support from implementations for the feature.
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.
Many of the concepts in this document were introduced by example using the JSON syntax. This section formalizes how the data model (described in Sections § 3. Core Data Model , § 4. Basic Concepts , and § 5. Advanced Concepts ) is realized in JSON and JSON-LD. Although syntactic mappings are provided for these two syntaxes only, applications and services can use any other data representation syntax, such as XML, YAML, or CBOR, that is capable of expressing the data model.
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:
[ 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
@context
property
.
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
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
.
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:
@id
and
@type
keywords
are
aliased
to
id
and
type
respectively,
enabling
developers
to
use
this
specification
as
idiomatic
JSON.
verifiableCredential
and
proof
properties
are
treated
as
graph
containers
.
That
is,
mechanisms
used
to
isolate
sets
of
data
asserted
by
different
entities.
This
ensures,
for
example,
proper
cryptographic
separation
between
the
data
graph
provided
by
each
issuer
and
the
one
provided
by
the
holder
presenting
the
verifiable
credential
to
ensure
the
provenance
of
the
information
for
each
graph
is
preserved.
@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.
The data model described in this specification is designed to be proof format agnostic. This specification does not make any normative statements related to the use of any particular digital proof or signature format. 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:
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.
JWT support is a feature at risk and may be removed during the W3C Candidate Recommendation phase if there is not enough implementer support for the feature.
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 presentation MAY be omitted to avoid duplication.
This specification introduces two new registered claim names, which contain those parts of the standard verifiable credentials and verifiable presentation where no explicit encoding rules for JWT exist. These objects are enclosed in the JWT payload as follows:
vc
:
JSON
object,
which
MUST
be
present
in
a
JWT
verifiable
credential
.
The
object
contains
the
verifiable
credential
according
to
this
specification.
vp
:
JSON
object,
which
MUST
be
present
in
a
JWT
verifiable
presentation
.
The
object
contains
the
verifiable
presentation
according
to
this
specification.
To
encode
a
verifiable
credential
as
a
JWT,
specific
properties
introduced
by
this
specification
MUST
be
encoded
as
standard
JOSE
header
parameters,
JWT
registered
claim
names,
or
contained
in
the
JWS
signature
part.
If
no
explicit
rule
is
specified,
properties
are
encoded
in
the
same
way
as
with
a
standard
verifiable
credential
,
and
are
added
to
the
vc
property
of
the
JWT.
The
following
paragraphs
describe
these
encoding
rules.
If
the
JWS
is
present,
the
digital
signature
either
refers
to
the
issuer
of
the
verifiable
credential
,
or
in
the
case
of
a
verifiable
presentation
,
the
holder
of
the
verifiable
credential
.
The
JWS
proves
that
the
issuer
of
the
JWT
signed
the
contained
JWT
payload
and
therefore,
the
proof
property
can
be
omitted.
If
no
JWS
is
present,
a
proof
property
MUST
be
provided.
The
proof
property
can
be
used
to
represent
more
complex
proofs,
for
example
if
the
creator
is
different
from
the
issuer
,
or
a
proof
not
based
on
digital
signatures,
such
as
Proof
of
Work.
The
issuer
MAY
include
both
a
JWS
and
a
proof
property
.
For
backward
compatibility
reasons,
the
issuer
MUST
use
JWS
to
represent
proofs
based
on
a
digital
signature.
The following defines rules for JOSE headers in the context of this specification:
alg
MUST
be
used
for
RSA
and
ECDSA-based
digital
signatures.
If
only
the
proof
attribute
is
used,
the
alg
header
MUST
be
set
to
none
.
kid
MAY
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:
exp
MUST
represent
expirationDate
,
encoded
as
a
UNIX
timestamp
(
NumericDate
).
iss
MUST
represent
the
issuer
property
.
iat
MUST
represent
issuanceDate
,
encoded
as
a
UNIX
timestamp
(
NumericDate
).
jti
MUST
represent
the
id
property
of
the
verifiable
credential
.
sub
MUST
represent
the
id
property
contained
in
the
verifiable
credential
subject
.
aud
MUST
represent
the
subject
of
the
consumer
of
the
verifiable
presentation
.
Other
JOSE
header
parameters
and
claim
names
not
specified
herein
can
be
used
if
their
use
is
not
explicitly
discouraged.
Additional
claims
MUST
be
added
to
the
credentialSubject
property
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
vc
property
of
the
JWT.
To decode a JWT to a standard verifiable credential , the following transformation MUST be performed:
vc
property
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
expirationDate
property
of
credentialSubject
of
the
new
JSON
object.
iss
is
present,
the
value
MUST
be
used
to
set
the
issuer
property
of
the
new
JSON
object.
iat
is
present,
the
UNIX
timestamp
MUST
be
converted
to
an
[
RFC3339
]
date-time
,
and
MUST
be
used
to
set
the
value
of
the
issuanceDate
property
of
the
new
JSON
object.
jti
is
present,
the
value
MUST
be
used
to
set
the
value
of
the
id
property
of
credentialSubject
of
the
new
JSON
object.
sub
is
present,
the
value
MUST
be
used
to
set
the
value
of
the
id
property
of
the
new
JSON
object.
{ "alg": "RS256", "typ": "JWT", "kid": "did:example:abfe13f712120431c276e12ecab#keys-1" }
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.
{ "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21", "jti": "http://example.edu/credentials/3732", "iss": "did:example:abfe13f712120431c276e12ecab", "iat": "1541493724", "exp": "1573029723", "nonce": "660!6345FSer", "vc": { "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "type": ["VerifiableCredential", "UniversityDegreeCredential"], "credentialSubject": { "degree": { "type": "BachelorDegree", "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>" } } } }
In
the
example
above,
vc
does
not
contain
the
id
property
because
the
JWT
encoding
uses
the
jti
attribute
to
represent
a
unique
identifier.
The
sub
attribute
encodes
the
information
represented
by
the
id
property
of
credentialSubject
.
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOmFiZmUxM2Y3MTIxMjA0
MzFjMjc2ZTEyZWNhYiNrZXlzLTEifQ.eyJzdWIiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxY
zI3NmUxMmVjMjEiLCJqdGkiOiJodHRwOi8vZXhhbXBsZS5lZHUvY3JlZGVudGlhbHMvMzczMiIsImlzc
yI6ImRpZDpleGFtcGxlOmFiZmUxM2Y3MTIxMjA0MzFjMjc2ZTEyZWNhYiIsImlhdCI6IjE1NDE0OTM3M
jQiLCJleHAiOiIxNTczMDI5NzIzIiwibm9uY2UiOiI2NjAhNjM0NUZTZXIiLCJ2YyI6eyJAY29udGV4d
CI6WyJodHRwczovL3czLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIiwiaHR0cHM6Ly9leGFtcGxlLmNvb
S9leGFtcGxlcy92MSJdLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiVW5pdmVyc2l0eURlZ
3JlZUNyZWRlbnRpYWwiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsiZGVncmVlIjp7InR5cGUiOiJCYWNoZ
WxvckRlZ3JlZSIsIm5hbWUiOiJCYWNoZWxvciBvZiBTY2llbmNlIGluIE1lY2hhbmljYWwgRW5naW5lZ
XJpbmcifX19fQ.VTotLRYblDOtJBTlOYbvibqC_uu8RXdvv6m_lR6cdEdFcGf4oNKiFZ_WJr07n1A-_E
jTLzjD5XwmDPzb8lxDlEkCLJ5WQS4_jwzCZAeetNG7YO2slTCFRiE_2xBM2R01ssI8bEPnqLBnc-Lu88
DmO21wL8-Yud1eL45N_pEE5DqTF5DJ-IesmVkWvC8159GUHKShFIpgHiE1EDDEjUzjYA5ZyzS2_ZmSTj
5NDLOt8muVlORpO7xJ6aWRdtibkmSTKykUzh75-4Rklz2H9-AWBXEh5ajkyB8yINh_y4jK3g7ypVACRI
Z9DZhdw2K39KCilAPVJsmejiKlxNhQAOlgcYUlhCzphLsqo-FA90fFGrsg-3JuQihnNw6RSPImjVt_yV
appfjilEzhyfWT-Smm_KN8LRbFdNtU-awwhKbjDNW-7fNVrnsWHKvLsd_zlch8YlHZ6g0tHJnxo_yOTM
BSSpt0jzyl1ByqjumgBFNpTR-NTVog4B7vLEvq58RuShraL5VNr7bjNzq2gisp3jq3LpfUmiwc7rQXw6
AlQuattLRolXx3EtPysrZe-wU7yrEtNPvpGs-OyJAczfJPzza9lGTbx6IWS-0pTmNq6hwNd0ODMiB3uL
3TeBN1xLoue9Hdc3toUvmdyXecSvltPcaiRoN-uQo8RRAvfK7GALAzaHw
{ "alg": "RS256", "typ": "JWT", "kid": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1" }
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.
{
"iss": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"jti": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
"aud": "did:example:4a57546973436f6f6c4a4a57573",
"iat": "1541493724",
"exp": "1573029723",
"nonce": "343s$FSFDa-",
"vp": {
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"type": ["VerifiablePresentation"],
// base64url-encoded JWT as string
"verifiableCredential": ["..."]
}
}
In
the
example
above,
vp
does
not
contain
the
id
property
because
the
JWT
encoding
uses
the
jti
attribute
to
represent
a
unique
identifier.
verifiableCredential
contains
an
string
array
of
verifiable
credentials
using
JWT
compact
serialization.
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2
ZjFjMjc2ZTEyZWMyMSNrZXlzLTEifQ.eyJpc3MiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxY
zI3NmUxMmVjMjEiLCJqdGkiOiJ1cm46dXVpZDozOTc4MzQ0Zi04NTk2LTRjM2EtYTk3OC04ZmNhYmEzO
TAzYzUiLCJhdWQiOiJkaWQ6ZXhhbXBsZTo0YTU3NTQ2OTczNDM2ZjZmNmM0YTRhNTc1NzMiLCJpYXQiO
iIxNTQxNDkzNzI0IiwiZXhwIjoiMTU3MzAyOTcyMyIsIm5vbmNlIjoiMzQzcyRGU0ZEYS0iLCJ2cCI6e
yJAY29udGV4dCI6WyJodHRwczovL3czLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIiwiaHR0cHM6Ly9le
GFtcGxlLmNvbS9leGFtcGxlcy92MSJdLCJ0eXBlIjpbIlZlcmlmaWFibGVQcmVzZW50YXRpb24iXSwid
mVyaWZpYWJsZUNyZWRlbnRpYWwiOlsiZXlKaGJHY2lPaUpTVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0lzS
W10cFpDSTZJbVJwWkRwbGVHRnRjR3hsT21GaVptVXhNMlkzTVRJeE1qQTBNekZqTWpjMlpURXlaV05oW
WlOclpYbHpMVEVpZlEuZXlKemRXSWlPaUprYVdRNlpYaGhiWEJzWlRwbFltWmxZakZtTnpFeVpXSmpOb
Vl4WXpJM05tVXhNbVZqTWpFaUxDSnFkR2tpT2lKb2RIUndPaTh2WlhoaGJYQnNaUzVsWkhVdlkzSmxaR
1Z1ZEdsaGJITXZNemN6TWlJc0ltbHpjeUk2SW1ScFpEcGxlR0Z0Y0d4bE9tRmlabVV4TTJZM01USXhNa
kEwTXpGak1qYzJaVEV5WldOaFlpSXNJbWxoZENJNklqRTFOREUwT1RNM01qUWlMQ0psZUhBaU9pSXhOV
GN6TURJNU56SXpJaXdpYm05dVkyVWlPaUkyTmpBaE5qTTBOVVpUWlhJaUxDSjJZeUk2ZXlKQVkyOXVkR
1Y0ZENJNld5Sm9kSFJ3Y3pvdkwzY3pMbTl5Wnk4eU1ERTRMMk55WldSbGJuUnBZV3h6TDNZeElpd2lhS
FIwY0hNNkx5OWxlR0Z0Y0d4bExtTnZiUzlsZUdGdGNHeGxjeTkyTVNKZExDSjBlWEJsSWpwYklsWmxjb
WxtYVdGaWJHVkRjbVZrWlc1MGFXRnNJaXdpVlc1cGRtVnljMmwwZVVSbFozSmxaVU55WldSbGJuUnBZV
3dpWFN3aVkzSmxaR1Z1ZEdsaGJGTjFZbXBsWTNRaU9uc2laR1ZuY21WbElqcDdJblI1Y0dVaU9pSkNZV
05vWld4dmNrUmxaM0psWlNJc0ltNWhiV1VpT2lKQ1lXTm9aV3h2Y2lCdlppQlRZMmxsYm1ObElHbHVJR
TFsWTJoaGJtbGpZV3dnUlc1bmFXNWxaWEpwYm1jaWZYMTlmUS5WVG90TFJZYmxET3RKQlRsT1lidmlic
UNfdXU4UlhkdnY2bV9sUjZjZEVkRmNHZjRvTktpRlpfV0pyMDduMUEtX0VqVEx6akQ1WHdtRFB6Yjhse
ERsRWtDTEo1V1FTNF9qd3pDWkFlZXRORzdZTzJzbFRDRlJpRV8yeEJNMlIwMXNzSThiRVBucUxCbmMtT
HU4OERtTzIxd0w4LVl1ZDFlTDQ1Tl9wRUU1RHFURjVESi1JZXNtVmtXdkM4MTU5R1VIS1NoRklwZ0hpR
TFFRERFalV6allBNVp5elMyX1ptU1RqNU5ETE90OG11VmxPUnBPN3hKNmFXUmR0aWJrbVNUS3lrVXpoN
zUtNFJrbHoySDktQVdCWEVoNWFqa3lCOHlJTmhfeTRqSzNnN3lwVkFDUklaOURaaGR3MkszOUtDaWxBU
FZKc21lamlLbHhOaFFBT2xnY1lVbGhDenBoTHNxby1GQTkwZkZHcnNnLTNKdVFpaG5OdzZSU1BJbWpWd
F95VmFwcGZqaWxFemh5ZldULVNtbV9LTjhMUmJGZE50VS1hd3doS2JqRE5XLTdmTlZybnNXSEt2THNkX
3psY2g4WWxIWjZnMHRISm54b195T1RNQlNTcHQwanp5bDFCeXFqdW1nQkZOcFRSLU5UVm9nNEI3dkxFd
nE1OFJ1U2hyYUw1Vk5yN2JqTnpxMmdpc3AzanEzTHBmVW1pd2M3clFYdzZBbFF1YXR0TFJvbFh4M0V0U
HlzclplLXdVN3lyRXROUHZwR3MtT3lKQWN6ZkpQenphOWxHVGJ4NklXUy0wcFRtTnE2aHdOZDBPRE1pQ
jN1TDNUZUJOMXhMb3VlOUhkYzN0b1V2bWR5WGVjU3ZsdFBjYWlSb04tdVFvOFJSQXZmSzdHQUxBemFId
yJdfX0.hqDdoQrayDldi2RjdzACjgdPkp3eKQczJtkecHHlQgUs7533SoOPgG96cLPsDMb-0VKcRDw33
CgkuSIXHbxhmR23DpU0OR2lLtCI18qmtgBC9-bqvundES1p4U4cFQrUbbuMWYYpIxoHkh4KZGBAszRaF
U9OiCgOPQSpJFfr75IVYlIpgl0LwBh3Ac9-P0623BOEzOE4V-X-oYAro7on2lv6eukEb7BDpCE_DZbyT
bLLJJ5TWLUNf13CQKpza4cyVl0LtBwfBoj1IXQzdODYx2V-AAabI5H3vNSSPWZHHrm_nmnU7ZP2H8tpT
Uec3a094lZLHP3Ktz5zMLQwQwtrU7nJ4iDTW6ExIK6IxhQ250yzV4kaABbziynd5GmCrJ9IIYtMy-cK4
TPQHxlPvq9Zcxh7XEWquhc9UWFvdpx6zGtWYuDkB8q0NXwUZHrFHkqseYuiKsK7sd75ajeMCANxKw164
K4cUyX9v3w60xz3gFivd2W6A0mFRCqUkFUGfMpe4j-hsf6FyPzyXM6m1JNkNHsD86HHT_Xu9xTGHuaLp
3kn3l_wwQ687VuPnCPLGlV92lZOHIo-QSMm-WBTo4m5q5X8sr9gior_NI39OH3RfzBPA0iN1JDi8EkOA
dwapkZcYgpuhxHrzNbofYYS0nIIkZ7dIEHiyGhfLo5XzAEmAIU
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.
Information on the different qualities of the various syntax formats, e.g. JSON+JWT, JSON-LD+JWT, and JSON-LD+LD-Proofs may be found in the Verifiable Credentials Implementation Guidelines .
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.
This section is non-normative.
It is important to recognize there is a spectrum of privacy ranging from pseudonymous to strongly identified. Depending on the use case, people have different comfort levels about what information they are willing to provide and what information can be derived from what is provided.
For example, most people probably want to remain anonymous when purchasing alcohol because the regulatory check required is solely based on whether a person is above a specific age. Alternatively, for medical prescriptions written by a doctor for a patient, the pharmacy fulfilling the prescription is required to more strongly identify the medical professional and the patient. Therefore there is not one approach to privacy that works for all use cases. Privacy solutions are use case specific.
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.
This section is non-normative.
Data
associated
with
verifiable
credentials
stored
in
the
credential.credentialSubject
field
is
susceptible
to
privacy
violations
when
shared
with
verifiers
.
Personally
identifying
data,
such
as
a
government-issued
identifier,
shipping
address,
and
full
name,
can
be
easily
used
to
determine,
track,
and
correlate
an
entity
.
Even
information
that
does
not
seem
personally
identifiable,
such
as
the
combination
of
a
birthdate
and
a
postal
code,
has
very
powerful
correlation
and
de-anonymizing
capabilities.
Implementers
are
strongly
advised
to
warn
holders
when
they
share
data
with
these
kinds
of
characteristics.
Issuers
are
strongly
advised
to
provide
privacy-protecting
credentials
when
possible.
For
example,
issuing
ageOver
credentials
instead
of
date
of
birth
credentials
when
a
verifier
wants
to
determine
if
an
entity
is
over
the
age
of
18.
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
credential
schemes
that
allow
hiding
the
identifier
during
presentation.
Such
schemes
expect
the
holder
to
generate
the
identifier
and
might
even
allow
hiding
the
identifier
from
the
issuer
,
while
still
keeping
the
identifier
embedded
and
signed
in
the
credential
.
If strong anti-correlation properties are a requirement in a verifiable credentials system, it is strongly advised that identifiers are either:
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
creator
,
created
,
domain
(for
very
specific
domains),
nonce
,
and
signatureValue
fields.
If strong anti-correlation properties are required, it is advised that signature values and metadata are regenerated each time using technologies like third-party pairwise signatures, zero-knowledge proofs, or group signatures.
Even when using anti-correlation signatures, information might still be contained in a credential that defeats the anti-correlation properties of the cryptography used.
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, credential -specific JSON-LD contexts, and many other sorts of long-lived identifiers.
Organizations providing software to holders should strive to identify fields in credentials containing information that could be used to correlate individuals and warn holders when this information is shared.
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 .
This section is non-normative.
To enable recipients of verifiable credentials to use them in a variety of circumstances without revealing more personally identifiable information than necessary for transactions, issuers should consider limiting the information published in a credential to a minimal set needed for the expected purposes. One way to avoid placing personally identifiable information in a credential is to use an abstract property that meets the needs of verifiers without providing specific information about a subject .
For
example,
this
document
uses
the
ageOver
property
instead
of
a
specific
birthdate,
which
constitutes
much
stronger
personally
identifiable
information.
If
retailers
in
a
specific
market
commonly
require
purchasers
to
be
older
than
a
certain
age,
an
issuer
trusted
in
that
market
might
choose
to
offer
a
credential
claiming
that
subjects
have
met
that
requirement
instead
of
offering
credentials
containing
claims
about
specific
birthdates.
This
enables
individual
customers
to
make
purchases
without
revealing
specific
personally
identifiable
information.
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 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
credential
containing
every
attribute
that
appears
on
a
driver's
license,
as
well
as
a
set
of
credentials
where
every
credential
contains
only
a
single
attribute
such
as
a
person's
birthday.
It
could
also
issue
more
abstract
credentials
(for
example,
a
credential
containing
only
an
ageOver
attribute).
One
possible
adaptation
would
be
for
issuers
to
provide
secure
HTTP
endpoints
for
retrieving
single-use
bearer
credentials
that
promote
the
pseudonymous
usage
of
credentials
.
Implementers
that
find
this
impractical
or
unsafe,
should
consider
using
selective
disclosure
schemes
that
eliminate
dependence
on
issuers
at
proving
time
and
reduce
temporal
correlation
risk
from
issuers
.
Verifiers are urged to only request information that is absolutely necessary for a specific transaction to occur. This is important for at least two reasons. It:
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.
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 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 credential is not a concern or would not result in large economic or reputational losses.
Verifiable
credentials
that
are
bearer
credentials
are
made
possible
by
not
specifying
the
subject
identifier,
expressed
using
the
id
property
,
which
is
nested
in
the
credentialSubject
property
.
For
example,
the
following
verifiable
credential
is
a
bearer
credential
:
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/temporary/28934792387492384",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2017-10-22T12:23:48Z",
"credentialSubject": {
// note that the 'id' property is not specified for bearer credentials
"degree": {
"type": "BachelorDegree",
"name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
}
},
"proof": { ... }
}
While bearer credentials can be privacy-enhancing, they must be carefully crafted so as not accidentally divulge more information than the holder of the credential expects. For example, repeated use of the same bearer credential across multiple sites enables these sites to potentially collude to unduly track or correlate the holder . Likewise, information that might seem non-identifying, such as a birthdate and postal code, can be used to statistically identify an individual when used together in the same credential or session.
Issuers of bearer credentials should ensure that the bearer credentials provide privacy-enhancing benefits that:
Holders should be warned by their software if bearer credentials containing sensitive information are issued or requested, or if there is a correlation risk when combining two or more bearer credentials across one or more sessions. While it might be impossible to detect all correlation risks, some might certainly be detectable.
Verifiers should not request bearer credentials that can be used to unduly correlate the holder .
This section is non-normative.
When processing verifiable credentials , verifiers are expected to perform many of the checks listed in Appendix § A. Validation as well as a variety of specific business process checks. For example, validity checks might include checking:
The process of performing these checks might result in information leakage that leads to a privacy violation of the holder . For example, a simple operation like checking a revocation list can notify the issuer that a specific business is likely interacting with the holder . This could enable issuers to collude and correlate individuals without their knowledge.
Issuers are urged to not use mechanisms, such as credential revocation lists that are unique per credential , during the verification process 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.
This section is non-normative.
When a holder receives a credential from an issuer , the credential needs to be stored somewhere (for example, in a credential repository). Holders are warned that the information in a verifiable credential is sensitive in nature and highly individualized, making it a high value target for data mining. Services that advertise free storage of verifiable credentials might in fact be mining personal data and selling it to organizations wanting to build individualized profiles on people and organizations.
Holders need to be aware of the terms of service for their credential repository, specifically the correlation and data mining protections in place for those who store their verifiable credentials with the service provider.
The following are some effective mitigations for data mining and profiling:
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 two pieces of information, even when the information is delivered through different channels. The aggregation of credentials is a privacy risk and all participants in the ecosystem need to be aware of the risks of data aggregation.
For example, if two bearer credentials , one for an email address and then one stating the holder is over the age of 21, are provided across multiple sessions, the verifier of the information now has a unique identifier plus age-related information for the individual. It is now easy to create and build a profile for the holder such that more and more information is leaked over time. Aggregation of credentials can also be performed across multiple sites in collusion with each other, leading to privacy violations.
From a technological perspective, preventing the aggregation of information is a very difficult privacy problem to address. While new cryptographic techniques, such as zero-knowledge proofs, are being proposed as solutions to the problem of aggregation and correlation, the existence of long-lived identifiers and browser tracking techniques defeats even the most modern cryptographic techniques.
The solution to the privacy implications of correlation or aggregation tend not to be technological in nature, but policy driven instead. Therefore, if a holder does not want information about them to be aggregated, they must express this in the verifiable presentations they transmit.
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:
In part, it is possible to mitigate this de-anonymization and loss of privacy by:
It is understood that these mitigation techniques are not always practical or even compatible with necessary usage. Sometimes correlation is a requirement.
For example, in some prescription drug monitoring programs, usage monitoring is a requirement. Enforcement entities need to be able to confirm that individuals are not cheating the system to get multiple prescriptions for controlled substances. This statutory or regulatory need to correlate usage overrides individual privacy concerns.
Verifiable credentials will also be used to intentionally correlate individuals across services, for example, when using a common persona to log in to multiple services, so all activity on each of those services is intentionally linked to the same individual. This is not a privacy issue as long as each of those services uses the correlation in the expected manner.
Privacy risks of credential usage occur when unintended or unexpected correlation arises from the presentation of verifiable credentials .
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.
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 credentials short lived and renewal automatic.
For
example,
an
ageOver
credential
is
useful
for
gaining
access
to
a
bar.
If
an
issuer
issues
such
a
credential
with
a
very
short
expiration
date
and
an
automatic
renewal
mechanism,
then
the
issuer
could
possibly
correlate
the
behavior
of
the
holder
in
a
way
that
negatively
impacts
the
holder
.
Organizations providing software to holders should warn them if they repeatedly use credentials with short lifespans, which could result in behavior correlation. Issuers should avoid issuing credentials in a way that enables them to correlate usage patterns.
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 credentials whenever possible.
Using single-use credentials provides several benefits. The first benefit is to verifiers who can be sure that the data in a credential is fresh. The second benefit is to holders , who know that if there are no long-lived identifiers in the credential , the credential itself cannot be used to track or correlate them online. Finally, there is nothing for attackers to steal, making the entire ecosystem safer to operate within.
This section is non-normative.
In an ideal private browsing scenario, no personally identifiable information (PII) will be revealed. Because many credentials include PII, organizations providing software to holders should warn them about the possibility of revealing PII if they wish to use credentials and presentations while in private browsing mode.
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.
This section is non-normative.
Some aspects of the data model described in this specification can be protected through the use of cryptography. Implementers should be aware of the underlying cryptography suites and libraries used to implement the creation and verification of digital signatures and mathematical proofs used by their systems when processing credentials and presentations . Software developers with extensive experience implementing or auditing systems that use cryptography must be employed to ensure systems are properly designed. Proper red teaming is also suggested to remove bias from security reviews.
Cryptography suites and libraries have a shelf life and eventually fall to new attacks and technology advances. Production quality systems must take this into account and ensure mechanisms exist to easily and proactively upgrade expired or broken cryptography suites and libraries. Procedures should also exist to invalidate and replace existing credentials in the event of a cryptography suite or library failure. Regular monitoring of systems to ensure proper upgrades are made in a timely manner are also important to ensure the long term viability of systems processing verifiable credentials .
This section is non-normative.
Verifiable credentials often contain URLs to data that resides outside of the credential itself. Content that exists outside a verifiable credential , such as links to images, JSON-LD Contexts, and other machine-readable data, are often not protected against tampering because the data resides outside of the protection of the proof on the verifiable credential . For example, the following highlighted links are not content-integrity protected and probably should be:
{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "id": "http://example.edu/credentials/58473", "type": ["VerifiableCredential", "AlumniCredential"], "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "image": "https://example.edu/images/58473", "alumniOf": "<span lang='en'>Example University</span>" }, "proof": { ... } }
While this specification does not recommend any particular content integrity protection, document authors that would like to ensure that 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 InterPlanetary File System (IPFS). The example below transforms the example above and adds content integrity protection to the JSON-LD Contexts using the Hashlink specification, and content integrity protection to the image by using an IPFS link:
{ "@context": [ "https://www.w3.org/2018/credentials/v1?hl=z3aq31uzgnZBuWNzUB", "https://www.w3.org/2018/credentials/examples/v1?hl=z8guWNzUBnZBu3aq31" ], "id": "http://example.edu/credentials/58473", "type": ["VerifiableCredential", "AlumniCredential"], "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "image": "ipfs:/ipfs/QmXfrS3pHerg44zzK6QKQj6JDk8H6cMtQS7pdXbohwNQfK/image", "alumniOf": "<span lang='en'>Example University</span>" }, "proof": { ... } }
It is debatable whether or not the JSON-LD Contexts above need protection as it is expected that production implementations will 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 may be better suited for certain applications. Implementers are urged to understand how links to external machine-readable content that are not content-integrity protected may result in successful attacks against their applications.
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 note that these types of credentials are not verifiable because the authorship is either not known or cannot be trusted.
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 . Any protocol using the Verifiable Credentials Data Model that requires protection against these kinds of attacks needs to perform some sort of token binding, such as The Token Binding Protocol v1.0 , which ties the request for a verifiable presentation with the response. Any protocol that does not perform token binding is susceptible to man-in-the-middle attacks.
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 credentials to a person, each containing two properties , for example, "Staff Member" in the "Department of Computing" and "Post Graduate Student" in the "Department of Economics". If these credentials are atomized into separate properties, then the university would issue four credentials to the person, each containing one of the following properties, "Staff Member", "Post Graduate Student", "Department of Computing", and "Department of Economics". The holder could then transfer the "Staff Member" and "Department of Economics" credentials to a verifier , which together would comprise a false claim.
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 credential is valid might create exploitable security vulnerabilities. Expiration periods shorter than the timeframe where the information expressed by the credential is valid creates a burden on holders and verifiers . It is therefore important to set validity periods for credentials that are appropriate to the use case and the expected lifetime for the information contained in the credential .
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:
This section is non-normative.
There are a number of accessibility considerations implementers should be aware of when processing data described in this specification. As with any web standards or protocols implementation, ignoring accessibility issues makes this information unusable to a large subset of the population. It is important to follow accessibility guidelines and standards, such as [ WCAG21 ], to ensure all people, regardless of ability, can make use of this data. This is especially important when establishing systems utilizing cryptography, which historically, have created problems for assistive technologies.
This section details the general accessibility considerations to take into account when utilizing this data model.
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 just relying on the image to convey this information. Using a data first approach is preferred because it provides the foundational elements of building different interfaces for people with varying abilities.
This section is non-normative.
There are a number of internationalization considerations implementers should be aware of 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 would limit the applicability of the specification and significantly diminish its value as a standard.
This section outlines general internationalization considerations to take into account when utilizing this data model.
This section is non-normative.
When expressing human-readable text content in the data model, it is important for presentation, accessibility, and further processing to specify the language of the text.
@language
feature,
which
is
described
in
JSON-LD
1.1,
Section
4.2.3:
String
Internationalization
.
rdf:HTML
string
literal
type,
which
is
described
in
JSON-LD
1.0,
Section
4.2.1:
Typed
Values
.
This
mechanism
enables
a
developer
to
use
the
internationalization
features
present
in
HTML
to
express
language
information.
For
example,
consider
the
following
key-value
pair:
"nameHtml":
"<span
lang="jp">和美</span>"
.
If
the
JSON-LD
Context
expressed
that
any
value
associated
with
the
nameHtml
property
as
being
of
type
rdf:HTML
,
then
software
agents
rendering
the
property
would
be
able
to
deterministically
identify
the
language
in
use.
This section is non-normative.
When expressing human-readable text content in the data model, it is important to be able to explicitly encode the text direction. JSON and its derived formats use the UTF-8 encoding of [ Unicode ] for serializing and transmitting text. This enables text direction to be directly determined in simple cases, but the mechanism is insufficient for general use.
JSON-LD
supports
the
expression
of
text
layout
information
via
the
rdf:HTML
string
literal
type,
which
is
described
in
JSON-LD
1.0,
Section
4.2.1:
Typed
Values
.
This
mechanism
enables
a
developer
to
use
the
internationalization
features
present
in
HTML
to
express
language
information.
For
example,
consider
the
following
key-value
pair:
"nameHtml":
"<span
dir="rtl"
lang="ar">HTML
و
CSS:
تصميم
و
إنشاء
مواقع
الويب</span>"
.
If
the
JSON-LD
Context
states
that
any
value
associated
with
the
nameHtml
property
is
of
type
rdf:HTML
,
then
software
agents
have
sufficient
information
to
deterministically
identify
the
text
direction
of
the
language.
This section is non-normative.
In some situations it is common to use Ruby characters ) to ensure that text information is clear and as useful as possible. JSON-LD's support for HTML data allows text to be encoded with ruby, supporting these cases.
This section is non-normative.
The W3C Internationalisation document [ string-meta ] gives more information about the need to be able to provide reliable metadata about text to support internationalization
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 may 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 .
This section is non-normative.
In
the
verifiable
credentials
presented
by
a
holder
,
the
value
associated
with
the
id
property
for
each
credentialSubject
is
expected
to
identify
a
subject
to
the
verifier
.
If
the
holder
is
also
the
subject
,
then
the
verifier
could
authenticate
the
holder
if
they
have
public
key
metadata
related
to
the
holder
.
The
verifier
could
then
authenticate
the
holder
using
a
signature
generated
by
the
holder
contained
in
the
verifiable
presentation
.
The
id
property
is
optional.
Verifiers
could
use
other
properties
in
a
verifiable
credential
to
uniquely
identify
a
subject
.
For information on how authentication and WebAuthn might work with verifiable credentials , please refer to the Verifiable Credentials Implementation Guidelines .
This section is non-normative.
The
value
associated
with
the
issuer
property
is
expected
to
identify
an
issuer
that
is
known
to
and
trusted
by
the
verifier
.
Relevant
metadata
about
the
issuer
property
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
.
This section is non-normative.
The
issuanceDate
is
expected
to
be
within
an
expected
range
for
the
verifier
.
For
example,
a
verifier
can
ensure
that
the
issuance
date
of
a
verifiable
credential
is
not
in
the
future.
This section is non-normative.
The cryptographic mechanism used to prove that the information in a verifiable credential or a verifiable presentation has not been tampered with is called a proof . There are many types of cryptographic proofs including, but not limited to, digital signatures, zero-knowledge proofs, Proofs of Work, and Proofs of Stake. In general, when verifying proofs implementations are expected to ensure that:
Some proofs are digital signatures. In general, when verifying digital signatures, implementations are expected to ensure that:
proofPurpose
property
,
it
is
expected
to
exist
and
be
a
valid
value,
such
as
credentialIssuance
).
The
digital
signature
provides
a
number
of
protections,
other
than
tamper
resistance,
that
are
not
immediately
obvious.
For
example,
a
Linked
Data
Signature
created
property
establishes
a
date
and
time
before
which
the
credential
should
not
be
considered
verified
.
The
creator
property
enables
the
ability
to
dynamically
discover
information
about
the
entity
who
created
the
data
to
ensure
that
the
public
key
is
not
revoked
or
expired.
The
proofPurpose
property
ensures
the
reason
the
entity
created
the
signature,
such
as
for
authentication
or
creating
a
verifiable
credential
,
is
clear
and
protected
in
the
signature.
This section is non-normative.
The
expirationDate
is
expected
to
be
within
an
expected
range
for
the
verifier
.
For
example,
a
verifier
can
ensure
that
the
expiration
date
of
a
verifiable
credential
is
not
in
the
past.
This section is non-normative.
If
the
credentialStatus
property
is
available,
the
status
of
a
verifiable
credential
is
expected
to
be
evaluated
by
the
verifier
according
to
the
credentialStatus
type
definition
for
the
verifiable
credential
and
the
verifier's
own
status
evaluation
criteria.
For
example,
a
verifier
can
ensure
that
the
status
of
the
verifiable
credential
was
withdrawn
for
cause
by
the
issuer
.
This section is non-normative.
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
birthdate
property
,
or
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 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.
This section is non-normative.
This section describes the possible relationships between a subject and a holder and how the Verifiable Credentials Data Model expresses these relationships. The following diagram illustrates the different types of relationships covered in the rest of this section.
The following sections describe how each of these relationships are handled in the data model.
This section is non-normative.
The most common relationship is when a subject is the holder . In this case, a verifier can easily deduce that a subject is the holder if the verifiable presentation is digitally signed by the holder and all contained verifiable credentials are about a subject that can be identified to be the same as the holder .
If
only
the
credentialSubject
is
allowed
to
insert
a
verifiable
credential
into
a
verifiable
presentation
,
the
issuer
MAY
insert
the
nonTransferable
property
into
the
verifiable
credential
,
as
described
below.
The nonTransferable feature is at risk and is likely to be removed due to lack of consensus.
This section is non-normative.
The
nonTransferable
property
states
that
a
verifiable
credential
MUST
only
be
encapsulated
into
a
verifiable
presentation
whose
proof
was
issued
by
the
credentialSubject
.
A
verifiable
presentation
that
contains
a
verifiable
credential
containing
the
nonTransferable
property
,
whose
proof
creator
is
not
the
credentialSubject
,
is
invalid.
{ "id": "http://example.edu/credentials/3732", "type": ["VerifiableCredential", "ProofOfAgeCredential"], "issuer": "https://example.edu/issuers/14", "issuanceDate": "2010-01-01T19:23:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "ageOver": 21 }, "nonTransferable": "True", "proof": { .. "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21", ... } }
This section is non-normative.
In
this
case,
the
credentialSubject
property
might
contain
multiple
properties
each
providing
an
aspect
of
the
identity
of
the
subject
,
which
together,
unambiguously
identify
the
subject
.
Some
use
cases
might
not
require
the
holder
to
be
identified
at
all,
such
as
checking
to
see
if
a
doctor
(the
subject
)
is
board-certified.
Other
use
cases
might
require
the
verifier
to
use
out-of-band
knowledge
to
determine
the
relationship
between
the
subject
and
the
holder
.
{ "@context": ["https://www.w3.org/2018/credentials/v1", "https://schema.org/"] "id": "http://example.edu/credentials/332", "type": ["VerifiableCredential", "IdentityCredential"], "issuer": "https://example.edu/issuers/4", "issuanceDate": "2017-02-24T19:73:24Z", "credentialSubject": { "name": "J. Doe", "address": { "streetAddress": "10 Rue de Chose", "postalCode": "98052", "addressLocality": "Paris", "addressCountry": "FR" }, "birthDate": "1989-03-15" ... }, "proof": { ... } }
The example above uniquely identifies the subject using the name, address, and birthdate of the individual.
This section is non-normative.
Usually verifiable credentials are presented to verifiers by the subject . However in some cases, the subject might need to pass the whole or part of a verifiable credential to another holder . For example, if a patient (the subject ) is too ill to take a prescription (the verifiable credential ) to the pharmacist (the verifier ), a friend might take the prescription in to pick up the medication.
The data model allows for this, by the subject issuing a new verifiable credential and giving it to the new holder , who can then present both verifiable credentials to the verifier . However, the content of this second verifiable credential is likely to be application specific, so this specification cannot standardize the contents of this second verifiable credential . Nevertheless, a non-normative example is provided in Appendix § B.5 Subject Passes a Verifiable Credential to Someone Else .
This section is non-normative.
The Verifiable Credentials Data Model supports the holder acting on behalf of the subject in at least the following ways. The:
credentialSubject
property
.
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.
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.
{ "id": "http://example.edu/credentials/3732", "type": ["VerifiableCredential", "AgeCredential", "RelationshipCredential"], "issuer": "https://example.edu/issuers/14", "issuanceDate": "2010-01-01T19:23:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "ageUnder": 16, "parent": { "id": "did:example:ebfeb1c276e12ec211f712ebc6f", "type": "Mother" } }, "proof": { ... } // the proof is generated by the DMV }
In the example above, the issuer expresses the relationship between the child and the parent such that a verifier would most likely accept the credential if it is provided by the child or the parent.
{ "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 .
{ "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.
This section is non-normative.
When a subject passes a verifiable credential to another holder , the subject might issue a new verifiable credential to the holder in which the:
The holder can now create a verifiable presentation containing these two verifiable credentials so that the verifier can verify that the subject gave the original verifiable credential to the holder .
{ "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2", "type": ["VerifiablePresentation"], "credential": [ { "id": "http://example.gov/credentials/3732", "type": ["VerifiableCredential", "PrescriptionCredential"], "issuer": "https://example.edu", "issuanceDate": "2010-01-01T19:73:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "prescription": {....} }, "revocation": { "id": "http://example.gov/revocations/738", "type": "SimpleRevocationList2017" }, "proof": {....} }, { "id": "https://example.com/VC/123456789", "type": ["VerifiableCredential", "PrescriptionCredential"], "issuer": "did:example:ebfeb1f712ebc6f1c276e12ec21", "issuanceDate": "2010-01-03T19:73:24Z", "credentialSubject": { "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2", "prescription": {....} }, "proof": { "type": "RsaSignature2018", "created": "2018-06-17T10:03:48Z", "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21/keys/234", "signatureValue": "pYw8XNi1..Cky6Ed=" } } ], "proof": [{ "type": "RsaSignature2018", "created": "2018-06-18T21:19:10Z", "verificationMethod": "did:example:76e12ec21ebhyu1f712ebc6f1z2/keys/2", "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e", "signatureValue": "BavEll0/I1..W3JT24=" }] }
In the above example, a patient (the original subject ) passed a prescription (the original verifiable credential ) to a friend, and issued a new verifiable credential to the friend, in which the friend is the subject , the original subject is the issuer , and the credential is a copy of the original prescription.
This section is non-normative.
When an issuer wants to authorize a holder to possess a credential that describes a subject who is not the holder , and the holder has no known relationship with the subject , then the issuer inserts the relationship of the holder to itself into the credential for the subject .
Verifiable credentials are not an authorization framework and therefore delegation is out of scope for this specification. However, it is understood that verifiable credentials are likely to be used to build authorization and delegation systems. The following is one approach that may be appropriate for some use cases.
When an issuer wants to authorise a holder to possess a credential that describes a subject who is not the holder , and the holder has no known relationship with the subject , then the issuer might insert the relationship of the holder to itself into the subject's credential .
{ "id": "http://example.edu/credentials/3732", "type": ["VerifiableCredential", "NameAndAddress"], "issuer": "https://example.edu/issuers/14", "holder": { "type": "LawEnforcement", "id": "did:example:ebfeb1276e12ec21f712ebc6f1c" }, "issuanceDate": "2010-01-01T19:73:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "name": "Mr John Doe", "address": "10 Some Street, Anytown, ThisLocal, Country X" }, "proof": { "type": "RsaSignature2018", "created": "2018-06-17T10:03:48Z", "verificationMethod": "https://example.edu/issuers/14/keys/234", "signatureValue": "pY9...Cky6Ed = " } }
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.