W3C
First
Public
Working
Draft
21
Copyright © 2023 World Wide Web Consortium . W3C ® liability , trademark and permissive document license rules apply.
This
specification
describes
a
privacy-preserving,
space-efficient,
and
high-performance
mechanism
for
publishing
status
information
such
as
suspension
or
revocation
of
Verifiable
Credentials.
Credentials
through
use
of
bitstrings.
This
section
describes
the
status
of
this
document
at
the
time
of
its
publication.
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/.
This
document
is
experimental
and
is
undergoing
heavy
development.
It
is
inadvisable
to
implement
the
specification
in
its
current
form.
An
experimental
implementation
is
available.
This document was published by the Verifiable Credentials Working Group as a First Public Working Draft using the Recommendation track .
Publication as a First Public Working Draft does not imply endorsement by W3C and its Members.
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 12 June 2023 W3C Process Document .
This section is non-normative.
It is often useful for an issuer of verifiable credentials [ VC-DATA-MODEL ] to link to a location where a verifier can check to see if a credential has been suspended or revoked. There are a variety of privacy and performance considerations that are made when designing, publishing, and processing status lists.
One such privacy consideration happens when there is a one-to-one mapping between a verifiable credential and a URL where the status is published. This type of mapping enables the website that publishes the URL to correlate the holder , time, and verifier when the status is checked. This could enable the issuer to discover the type of interaction the holder is having with the verifier , such as providing an age verification credential when entering a bar. Being tracked by the issuer of a driver's license when entering an establishment violates a privacy expectation that many people have today.
Similarly, there are performance considerations that are explored when designing status lists. One such consideration is where the list is published and the burden it places from a bandwidth and processing perspective, both on the server and the client fetching the information. In order to meet privacy expectations, it is useful to bundle the status of large sets of credentials into a single list to help with herd privacy. However, doing so can place an impossible burden on both the server and client if the status information is as much as a few hundred bytes in size per credential across a population of hundreds of millions of holders .
The rest of this document proposes a highly compressible, bitstring-based status list mechanism with strong privacy-preserving characteristics, that is compatible with the architecture of the Web, is highly space-efficient, and lends itself well to content distribution networks. As an example of using this specification to achieve a number of beneficial privacy and performance goals, it is possible to create a status list that can be constructed for 100,000 verifiable credentials that is roughly 12,500 bytes in size in the worst case. In a case where a few hundred credentials have been revoked, the size of the list is less than a few hundred bytes while providing privacy in a herd of 100,000 individuals.
This section is non-normative.
This section outlines the core concept utilized by the status list mechanism described in this document. At the most basic level, status information for all verifiable credentials issued by an issuer are expressed as simple binary values. The issuer keeps a bitstring list of all verifiable credentials it has issued. Each verifiable credential is associated with a position in the list. If the binary value of the position in the list is 1 (one), the verifiable credential is revoked, if it is 0 (zero) it is not revoked.
One of the benefits of using a bitstring is that it is a highly compressible data format since, in the average case, large numbers of credentials will remain unrevoked. This will ensure long sections of bits that are the same value and thus highly compressible using run-length compression techniques such as GZIP [ RFC1952 ]. The default bitstring size is 16KB (131,072 entries), and when only a handful of verifiable credentials are revoked, the compressed bitstring size is reduced down to a few hundred bytes.
Another benefit of using a bitstring is that it enables large numbers of verifiable credential statuses to be placed in the same list. This specification utilizes a minimum bitstring length of 131,072 (16KB). This population size ensures an adequate amount of herd privacy in the average case. If better herd privacy is required, the bitstring can be made to be larger.
This section is non-normative.
The following terms are used to describe concepts in this specification.
did:example:123456abcdef
.
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 , and SHOULD in this document are to be interpreted as described in BCP 14 [ RFC2119 ] [ RFC8174 ] when, and only when, they appear in all capitals, as shown here.
The following sections outlines the data model for this document.
When
an
issuer
desires
to
enable
status
information
for
a
verifiable
credential
,
they
MAY
add
a
credentialStatus
property
that
uses
the
data
model
described
in
this
specification.
| Property | Description | ||||||
|---|---|---|---|---|---|---|---|
| id |
An
optional
identifier
for
the
status
list
entry.
The
constraints
on
the
id
property
are
listed
in
the
Verifiable
Credentials
Data
Model
specification
[
VC-DATA-MODEL
].
If
present,
the
value
is
expected
to
be
a
URL
that
identifies
the
status
information
associated
with
the
verifiable
credential
.
It
MUST
NOT
be
the
URL
for
the
status
list.
The
value
is
not
used
during
the
verification
or
validation
process,
and
does
not
need
to
be
related
to
the
statusListCredential
value.
If
necessary,
the
value
can
be
used
to
uniquely
identify
the
object,
such
as
when
it
is
stored
in
a
database.
|
||||||
| type |
The
type
property
MUST
be
.
|
||||||
| statusPurpose |
The
purpose
of
the
status
entry
MUST
be
a
string.
While
the
value
of
the
string
is
arbitrary,
the
following
values
MUST
be
used
for
their
intended
purpose:
|
||||||
| statusListIndex |
The
statusListIndex
property
MUST
be
an
arbitrary
size
integer
greater
than
or
equal
to
0,
expressed
as
a
string.
The
value
identifies
the
position
of
the
status
of
the
verifiable
credential
.
|
||||||
| statusListCredential |
The
statusListCredential
property
MUST
be
a
URL
to
a
verifiable
credential
.
When
the
URL
is
dereferenced,
the
type
property
that
includes
the
value.
|
=======
>>>>>>> 4e198a53144c4671154323be1a6ec0c2e5965233
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
)
],
"id": "https://example.com/credentials/23894672394",
"type": ["VerifiableCredential"],
"issuer": "did:example:12345",
"issued": "2021-04-05T14:27:42Z",
"credentialStatus": {
"id": "https://example.com/credentials/status/3#94567",
"type": "StatusList2021Entry",
"id": "https://example.com/credentials/status/3#94567"
"type": "BitStringStatusListEntry",
"statusPurpose": "revocation",
"statusListIndex": "94567",
"statusListCredential": "https://example.com/credentials/status/3"
},
"credentialSubject": {
"id": "did:example:6789",
"type": "Person"
},
"proof": { ... }
}
When a status list is published, the result is a verifiable credential that encapsulates the status list. The following section describes the format of the verifiable credential that encapsulates the status list:
| Property | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| id |
The
verifiable
credential
that
contains
the
status
list
MAY
express
an
id
property
that
matches
the
value
specified
in
statusListCredential
for
the
corresponding
(see
2.1
|
||||||||
| type |
The
verifiable
credential
that
contains
the
status
list
MUST
express
a
type
property
that
includes
the
value.
|
||||||||
| validFrom | The earliest point in time at which the status list is valid. This property is defined in the Verifiable Credentials Data Model specification in Section 4.6: Validity Period . | ||||||||
| validUntil | The latest point in time at which the status list is valid. This property is defined in the Verifiable Credentials Data Model specification in Section 4.6: Validity Period . | ||||||||
| credentialSubject.type |
The
type
of
the
credential
subject
,
which
is
the
status
list,
MUST
be
.
|
||||||||
| credentialSubject.statusPurpose |
The
purpose
of
the
status
entry
MUST
be
a
string.
While
the
value
of
the
string
is
arbitrary,
the
following
values
MUST
be
used
for
their
intended
purpose:
|
||||||||
| credentialSubject.encodedList |
The
encodedList
property
of
the
credential
subject
MUST
be
the
GZIP-compressed
[
RFC1952
],
base-64
encoded
[
RFC4648
]
bitstring
values
for
the
associated
range
of
verifiable
credential
status
values.
The
uncompressed
bitstring
MUST
be
at
least
16KB
in
size.
The
bitstring
MUST
be
encoded
such
that
the
first
index,
with
a
value
of
zero
(
0
),
is
located
at
the
left-most
bit
in
the
bitstring
and
the
last
index,
with
a
value
of
one
less
than
the
length
of
the
bitstring
(
bitstring_length
-
1
),
is
located
at
the
right-most
bit
in
the
bitstring.
Further
information
on
bitstring
encoding
can
be
found
in
Section
5.1
Bitstring
Encoding
.
|
||||||||
| credentialSubject.ttl |
The
ttl
indicates
the
"time
to
live"
in
milliseconds.
This
property
MAY
be
present.
If
not
present,
implementers
MUST
use
a
value
of
300000
for
this
property.
A
verifier
MUST
NOT
use
a
cached
that
was
cached
for
more
than
the
ttl
duration
prior
to
the
start
of
verification
operation
on
a
verifiable
credential
.
Implementations
that
publish
the
status
list
SHOULD
align
any
protocol-specific
caching
information,
such
as
the
HTTP
Cache-Control
header,
with
the
value
in
this
field.
|
||||||||
| credentialSubject.size |
The
size
indicates
the
size
of
the
status
entry
in
bits.
size
MAY
be
provided.
If
size
is
not
present
as
a
property
of
the
credentialStatus
,
then
size
MUST
be
processed
as
1
.
size
MUST
be
an
integer
greater
than
zero.
If
size
is
provided
and
is
greater
than
1
,
then
the
property
credentialStatus.statusMessages
MUST
be
present,
and
the
number
of
status
messages
must
equal
the
number
of
possible
values.
|
||||||||
| credentialSubject.statusMessages |
The
statusMessages
property
MUST
be
an
array.
If
present,
the
length
of
the
array
must
equal
the
number
of
possible
status
states
indicated
by
size
.
statusMessages
MAY
be
present
if
size
is
1
.
statusMessages
MUST
be
present
if
size
is
greater
than
1
.
If
not
present,
the
message
value
associated
with
the
bit
value
of
0
is
"unset"
and
the
bit
value
of
1
is
"set".
If
present,
elements
in
the
statusMessages
array
MUST
contain
at
minimum
two
properties:
statusMessages
array.
Implementers
MAY
use
the
string
value
of
undefined
in
the
value
to
indicate
that
a
corresponding
status
is
not
defined
for
the
associated
status
value,
but
that
it
may
be
defined
in
the
future.
Rules
for
how
to
handle
various
status
messages
are
outside
the
scope
of
normative
requirements
in
this
document,
but
it
is
assumed
that
implementers
will
document
rules
for
processing
various
status
codes.
|
||||||||
| credentialSubject.reference |
The
reference
property
provides
a
point
for
implementers
to
include
a
[
URL
]
to
material
related
to
the
status.
An
implementer
MAY
include
the
reference
property,
and
if
they
do,
the
value
MUST
be
a
[
URL
]
or
an
array
of
URLs.
Implementers
using
a
statusPurpose
of
status
are
strongly
encouraged
to
provide
a
reference
.
Note
:
Details
around
reference
|
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
],
"id": "https://example.com/credentials/status/3",
"type": ["VerifiableCredential", ""],
"type": ["VerifiableCredential", "BitStringStatusListCredential"],
"issuer": "did:example:12345",
"issued": "2021-04-05T14:27:40Z",
"credentialSubject": {
"id": "https://example.com/status/3#list",
"type": "",
"type": "BitStringStatusList",
"statusPurpose": "revocation",
"encodedList": "H4sIAAAAAAAAA-3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA"
},
"proof": { ... }
}
The Working Group is still discussing the unification of a design between status lists with a single state (such as "revoked" or "suspended") and status lists with multiple states (exposed via a series of status messages). We are seeking implementer feedback on what a unified design should look like from an ease of implementation, privacy, and security standpoint.
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
],
"id": "https://example.com/credentials/status/3",
"type": ["VerifiableCredential", ""],
"type": ["VerifiableCredential", "BitStringStatusListCredential"],
"issuer": "did:example:12345",
"issued": "2021-04-05T14:27:40Z",
"credentialSubject": {
"id": "https://example.com/status/3#list",
"type": "",
"type": "BitStringStatusList",
"ttl": 500,
"statusPurpose": "status",
"reference": "https://example.org/status-dictionary/",
"size": 2,
"statusMessages": [
{"status":"0x0", "value":"valid"},
{"status":"0x1", "value":"invalid"},
{"status":"0x2", "value":"pending_review"},
...
],
"encodedList": "H4sIAAAAAAAAA-3BMQEAAADAAAAAAAAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA"
}
}
The following section outlines the algorithms that are used to generate and validate status lists as described by this document.
The
following
process,
or
one
generating
the
exact
output,
MUST
be
followed
when
producing
a
StatusList2021Credential
BitStringStatusListCredential
:
encodedList
property
set.
encodedList
to
compressed
bitstring
.
The
following
process,
or
one
generating
the
exact
output,
MUST
be
followed
when
validating
a
verifiable
credential
that
is
contained
in
a
StatusList2021Credential
BitStringStatusListCredential
:
credentialStatus
entry
that
is
a
statusPurpose
in
the
credentialStatus
entry
in
the
credentialToValidate
.
statusListCredential
URL,
and
ensure
that
all
proofs
verify
successfully.
If
the
dereference
fails,
or
if
any
of
the
proof
verifications
fail,
return
a
validation
error.
statusPurpose
value
in
the
statusListCredential
.
encodedList
property
of
the
statusListIndex
property
of
the
statusPurpose
of
revocation
or
suspension
,
return
true
if
status
is
1
,
and
return
false
if
status
has
any
other
value.
For
other
statusPurpose
,
return
the
corresponding
value
of
the
status
as
indicated
in
the
statusMessages
array.
The following process, or one generating the exact output, MUST be followed when generating a status list bitstring. The algorithm takes a issuedCredentials list as input and returns a compressed bitstring as output.
bitstring
,
if
there
is
a
corresponding
statusListIndex
value
in
a
credential
in
issuedCredentials
,
set
the
value
to
the
appropriate
status.
The
position
of
the
value
is
computed
as
statusListIndex
times
the
size
.
The following process, or one generating the exact output, MUST be followed when expanding a compressed status list bitstring. The algorithm takes a compressed bitstring as input and returns a uncompressed bitstring as output.
This section is non-normative.
This section details the general privacy considerations and specific privacy implications of deploying this specification into production environments.
This section is non-normative.
This document specifies a minimum revocation bitstring length of 131,072, or 16KB uncompressed. This is enough to give holders an adequate amount of herd privacy if the number of verifiable credentials issued is large enough. However, if the number of issued verifiable credentials is a small population, the ability to correlate an individual increases because the number of allocated slots in the bitstring is small. Correlating this information with, for example, where the geographic request came from can also help to correlate individuals that have received a credential from the same geographic region.
This section is non-normative.
It is possible for verifiers to increase the privacy of the holder whose verifiable credential is being checked by caching status lists that have been fetched from remote servers. By caching the content locally, less correlatable information can be inferred from verifier -based access patterns on the status list.
This section is non-normative.
The use of content distribution networks by issuers can increase the privacy of holders by reducing or eliminating requests for the status lists from the issuer . Often, a request for a revocation list will be served by an edge device and thus be faster and reduce the load on the server as well as cloaking verifiers and holders from issuers .
This section is non-normative.
In general, the herd privacy protections offered by this specification can be circumvented by malicious issuers and verifiers . Its privacy benefits can only be realized when issuers and verifiers intend to avoid tracking or sharing the presentation of particular credentials.
A malicious issuer might intentionally attack herd privacy by creating a unique status list per credential issued in order to establish a 1-1 mapping to track when a verifier processes a specific credential. Similarly, they could establish another a 1-1 mapping by using a different cryptographic key for every credential issued that is tracked in a status list.
A malicious verifier might intentionally attack herd privacy by sharing information from presented credentials with a malicious issuer .
What
prevents
the
issuer
from
hosting
several
status
list
bitstrings
(one
for
each
credential)
and
embedding
a
statusListIndex
value
that
represents
one
of
those
bitstrings
at
issuance
time?
This
loophole
would
allow
a
1:1
mapping
between
credential
and
status
list,
eliminating
the
herd
privacy
guarantees
that
are
integral
to
this
spec.
This section is non-normative.
There are a number of security considerations that implementers 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.
It
is
critical
that
implementers
pay
particular
attention
to
the
way
that
they
encode
and
decode
bitstrings.
Failure
to
do
so
can
result
in
checking
the
wrong
bitstring
index
for
a
given
credential,
leading
to
a
misinterpretation
of
its
present
state
(e.g.,
mistaking
a
revoked
status
for
an
unrevoked
status).
As
stated
in
Section
2.2
StatusList2021Credential
BitStringStatusListCredential
,
bitstrings
are
encoded
such
that
the
first
(zeroth)
index
refers
to
the
left-most
bit
of
the
bitstring
array.
The
diagram
below
demonstrates
the
proper
layout
for
an
uncompressed
bitstring.
For example, if a bitstring is 131,072 bits in size (16KB), the first index will be 0, and the last index will be 131,071.
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 have historically created problems for assistive technologies.
This section details the general accessibility considerations to take into account when utilizing this data model.
Write accessibility considerations.
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.
Write i18n considerations.
This section is non-normative.
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/23894672394",
"type": ["VerifiableCredential"],
"issuer": "did:example:12345",
"validFrom": "2021-04-05T14:27:42Z",
"credentialStatus": {
"id": "https://example.com/credentials/status/3#94567",
"type": "StatusList2021Entry",
"type": "BitStringStatusListEntry",
"statusPurpose": "revocation",
"statusListIndex": "94567",
"statusListCredential": "https://example.com/credentials/status/3"
},
"credentialSubject": {
"id": "did:example:6789",
"type": "Person"
}
}
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/status/3",
"type": ["VerifiableCredential", ""],
"type": ["VerifiableCredential", "BitStringStatusListCredential"],
"issuer": "did:example:12345",
"validFrom": "2021-04-05T14:27:40Z",
"credentialSubject": {
"id": "https://example.com/status/3#list",
"type": "",
"type": "BitStringStatusList",
"statusPurpose": "revocation",
"encodedList": "H4sIAAAAAAAAA-3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA"
}
}
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: