This specification describes a privacy-preserving, space-efficient, and
high-performance mechanism for publishing status information such as
suspension or revocation of Verifiable Credentials through use of bitstrings.
Status of This Document
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/.
Publication as a 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.
It is often useful for an issuer of verifiable credentials
[VC-DATA-MODEL-2.0] 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 group 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 group of 100,000 individuals.
1.1 Conceptual Framework
This section is non-normative.
This section outlines the core concept utilized by the status list
mechanism described in this specification. At the most basic level, status
information for all verifiable credentials issued by an issuer
is expressed as items in a list. Each issuer manages a list
of all verifiable credentials that it has issued. Each
verifiable credential is associated with an item in its list.
When a single bit specifies a status, such as "revoked" or "suspended",
then that status is expected to be true when the bit is set (1) and
false when unset (0).
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 status list size is 131,072 entries,
equivalent to 16 KB of single bit values. When only a handful of
verifiable credentials are revoked, GZIP compresses the bitstring
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 uses a minimum list length of 131,072. This
size ensures an adequate amount of group privacy in the average case.
If better group privacy is required, the bitstring can be made larger.
Figure 1
A visual depiction of the concepts outlined in this section.
Note: Status information is about the verifiable credential
The status information associated with a particular verifiable credential
is about the verifiable credential itself and might not apply to any
underlying or backing credential, such as an educational degree. For
example, in the case of such an educational degree, it is possible for a
verifiable credential to be revoked because the mechanism used to
create its digital signature has been compromised, while the backing educational
degree remains valid.
1.2 Terminology
This section is non-normative.
The following terms are used to describe concepts in this specification.
The act of limiting the amount of shared data strictly to the minimum
necessary to successfully accomplish a task or goal.
decentralized identifier
A portable URL-based identifier, also known as a DID,
associated with an entity. These identifiers are most often used in a
verifiable credential and are associated with subjects such that a
verifiable credential itself can be easily ported from one
repository to another without the need to reissue the credential.
An example of a DID is did:example:123456abcdef.
decentralized identifier document
Also referred to as a DID document, this is a document
that is accessible using a verifiable data registry and contains
information related to a specific decentralized identifier, such as the
associated repository and public key information.
A verifiable, boolean assertion about the value of another attribute in a
verifiable credential. These are useful in zero-knowledge-proof-style
verifiable presentations because they can limit information disclosure.
For example, if a verifiable credential contains an attribute
for expressing a specific height in centimeters, a derived predicate
might reference the height attribute in the verifiable credential
demonstrating that the issuer attests to a height value meeting the
minimum height requirement, without actually disclosing the specific height
value. For example, the subject is taller than 150 centimeters.
digital signature
A mathematical scheme for demonstrating the authenticity of a digital message.
entity
Anything that can be referenced in statements as an abstract or concrete noun.
Entities include but are not limited to people, organizations, physical things,
documents, abstract concepts, fictional characters, and arbitrary text. Any
entity might perform roles in the ecosystem, if it is capable of doing so. Note
that some entities fundamentally cannot take actions, e.g., the string "abc"
cannot issue credentials.
graph
A set of claims, forming a network of information composed of subjects
and their relationship to other subjects or data. Each claim is
part of a graph; this is either explicit in the case of named graphs, or
implicit for the default graph.
The means for keeping track of entities across contexts. Digital
identities enable tracking and customization of entity interactions
across digital contexts, typically using identifiers and attributes. Unintended
distribution or use of identity information can compromise privacy. Collection
and use of such information should follow the principle of
data minimization.
identity provider
An identity provider, sometimes abbreviated as IdP, is a system
for creating, maintaining, and managing identity information for
holders, while providing authentication services to
relying party applications within a federation or distributed network.
In this case the holder is always the subject. Even if the
verifiable credentials are bearer credentials, it is assumed the
verifiable credentials remain with the subject, and if they are
not, they were stolen by an attacker. This specification does not use this term
unless comparing or mapping the concepts in this document to other
specifications. This specification decouples the identity provider
concept into two distinct concepts: the issuer and the holder.
A graph associated with specific properties, such as
verifiableCredential. These properties
result in separate graphs that contain all claims defined in the
corresponding JSON objects.
A program, such as a browser or other Web client, that mediates the
communication between holders, issuers, and verifiers.
validation
The assurance that a claim from a specific issuer satisfies the
business requirements of a verifier for a particular use. This
specification defines how verifiers verify verifiable credentials and
verifiable presentations.
It also specifies that verifiers validate claims in verifiable
credentials before relying on them. However, the means for such validation
vary widely and are outside the scope of this specification. It is expected
that verifiers will trust certain issuers for certain claims and
apply their own rules to determine which claims in which credentials
are suitable for use by their systems.
verifiable credential
A verifiable credential is a tamper-evident credential that has authorship that
can be cryptographically verified. Verifiable credentials can be used to build
verifiable presentations, which can also be cryptographically verified.
verifiable data registry
A role a system might perform by mediating the creation and verification
of identifiers, keys, and other relevant data, such as
verifiable credential schemas, revocation registries, issuer public keys,
and so on, which might be required to use verifiable credentials. Some
configurations might require correlatable identifiers for subjects. Some
registries, such as ones for UUIDs and public keys, might just act as namespaces
for identifiers.
verifiable presentation
A verifiable presentation is a tamper-evident presentation encoded in such a way
that authorship of the data can be trusted after a process of cryptographic
verification. Certain types of verifiable presentations might contain data that
is synthesized from, but do not contain, the original verifiable credentials
(for example, zero-knowledge proofs).
verification
The evaluation of whether a verifiable credential or verifiable
presentation is an authentic and current statement of the issuer or
presenter, respectively. This includes checking that: the credential (or
presentation) conforms to the specification; the proof method is satisfied; and,
if present, the status check succeeds. Verification of a credential does not
imply evaluation of the truth of claims encoded in the credential.
Information that could be a cryptographic public key or any other data
used to verify a proof.
URL
A Uniform Resource Locator, as defined by [URL]. URLs can be dereferenced such
that they result in a resource, such as a document. The rules for dereferencing,
or fetching, a URL are defined by the URL scheme. This specification
does not use the term URI or IRI because those terms have been deemed to be
confusing to Web developers.
1.3 Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document
are to be interpreted as described in
BCP 14
[RFC2119] [RFC8174]
when, and only when, they appear in all capitals, as shown here.
A conforming document is any concrete expression of the
data model that follows the relevant normative requirements in Section
2. Data Model.
A conforming processor is any algorithm realized
as software and/or hardware that generates and/or consumes a
conforming document according to the relevant normative statements in
Section 3. Algorithms. Conforming processors MAY choose to only
support bitstring entry sizes of 1. Conforming processors MUST produce errors
when non-conforming documents are consumed.
2. Data Model
There are numerous ways to express status information associated with digital
credentials. Some of these mechanisms include Certificate Revocation Lists (CRL)
[RFC5280], the Online Certificate Status Protocol (OCSP) [RFC2560], Bloom
Filters [RFC8932], and cryptographic accumulators [ALLOSAUR]. This
specification optimizes for a variety of requirements that are different from
other mechanisms. These requirements include:
Technology
CRL
OCSP
Bloom
Accumulator
Bitstring
Provides tunable group privacy
✓
✗
✓
✓
✓
Does not require signed assertion for each credential
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 section. Any
expression of the data model in this section MUST be expressed in a
conforming verifiable credential as defined in [VC-DATA-MODEL-2.0].
(Feature at Risk) Issue 1: Bitstring entry sizes greater than 1 are at risk.
The Working Group is currently seeking implementer feedback regarding the
utility of bitstring entries that have sizes greater than one. Supporting
such entries adds complexity to the solution, and it's not clear whether there
is enough of an implementation community to support the feature. The WG is
considering three options: (1) require conforming implementations to support
the feature; (2) allow implementations to optionally support the feature; or
(3) remove the feature. At present, the specification implements option (2).
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-2.0]. 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 BitstringStatusListEntry object, such as when it is
stored in a database.
type
The type property MUST be BitstringStatusListEntry.
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:
Value
Description
revocation
Used to cancel the validity of a verifiable credential. This status is
not reversible.
suspension
Used to temporarily prevent the acceptance of a verifiable credential.
This status is reversible.
message
Used to convey an arbitrary message related to the status of the
verifiable credential.
statusListIndex
The statusListIndex property MUST be an arbitrary size integer
greater than or equal to 0, expressed as a string in base 10. The value identifies the
position of the status of the verifiable credential. Implementations
SHOULD assign indexes randomly, such that inferences — such as the recency
of the assignment or the size of the group — cannot be easily drawn from
that position.
statusListCredential
The statusListCredential property MUST be a URL to a
verifiable credential. When the URL is dereferenced, the resulting
verifiable credentialMUST have type property that
includes the BitstringStatusListCredential value.
statusSize
The statusSize indicates the size of the status entry in bits. statusSizeMAY be provided. If statusSize is not present as a property of the
credentialStatus, then statusSizeMUST be processed as 1. If present,
statusSizeMUST be an integer greater than zero. If statusSize is provided
and is greater than 1, then the property credentialStatus.statusMessageMUST be present, and the number of status messages MUST equal the
number of possible values.
statusMessage
If present, the statusMessage property MUST be an array, the length
of which MUST equal the number of possible status messages indicated
by statusSize (e.g., statusMessage array MUST have 2 elements if
statusSize has 1 bit, 4 elements if statusSize has 2 bits, 8
elements if statusSize has 3 bits, etc.). statusMessageMAY be
present if statusSize is 1, and MUST be present if statusSize is
greater than 1. If the statusMessage array is not present, the
message values associated with the status bit values of 1 and 0
are "set" and "unset", respectively. If the statusMessage array is
present, each element MUST contain the two properties described below,
and MAY contain additional properties.
status, a string representing the hexadecimal value of the status prefixed
with 0x
message, a string used by software developers to assist with debugging
which SHOULD NOT be displayed to end users.
Implementers MAY add additional values to objects in the statusMessage 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.
statusReference
An implementer MAY include the statusReference property. If present, its
value MUST be a URL or an array of URLs [URL] which dereference to material
related to the status. Implementers using a statusPurpose of message are
strongly encouraged to provide a statusReference.
Note: Details around reference
statusReference is especially important when interpretation of the status for
a credential may involve some understanding of the business case involved.
Status list entries can be used to express the purpose of a
status associated with a verifiable credential by using the
statusPurpose property.
The use of revocation or suspension as the status purpose
includes the semantics of the status, with revocation
indicating that a status bit expresses whether a
verifiable credential has been revoked and suspension
indicating that a status bit expresses whether a
verifiable credential has been suspended. The example below
demonstrates the use of these status purposes:
Example 1: Example StatusListCredential using simple entries
The use of message as the status purpose enables an issuer to
define an arbitrary number of custom, descriptive messages about
the status of the verifiable credential. The issuer commits to
the set of messages that may be associated with a particular entry
(i.e., with a particular verifiable credential) through the
statusSize, statusMessage, and optional statusReference properties,
at the time of verifiable credential issuance. This is to ensure that
the holder knows what sort of information might be associated with a
particular verifiable credential they keep in their possession, that
could then be discoverable by a verifier that later receives that
credential.
Example 2: Example StatusListCredential using more complex entries
When a status list verifiable credential is published, it MUST be a
conforming document, as defined in [VC-DATA-MODEL-2.0], that expresses the
data model in this section. The following section describes the format of
the verifiable credential that encapsulates the status list.
The status list is expressed inside a verifiable credential in order to
enable a holder to provide it directly to a verifier. This mechanism,
sometimes called "certificate stapling", increases privacy for the holder by
ensuring that the verifier does not need to contact the issuer to
retrieve the status list. Still, a verifier might choose to ignore the
holder-provided status list, even when its authenticity is verifiable,
if it desires a more recent version of a status list, for instance.
Issuers and verifiers are advised that the issuer of a
verifiable credential and the issuer of an associated
BitstringStatusListCredential might not be the same. There are technical,
legal, institutional, political, and other reasons that might make it
appropriate to separate the authority over the original credential from the
authority to revoke, or otherwise change the status of, such a credential.
Therefore, the issuer value of a verifiable credential containing a
BitstringStatusListEntryMAY be different from the issuer value of a
BitstringStatusListCredential.
(Feature at Risk) Issue 2: TTL conflicts with `validUntil`
The Working Group is considering the removal of the ttl ("time to live")
feature because its semantics conflict with the semantics of the validUntil
feature of verifiable credentials. When a verifier performs
validation and evaluates a BitstringStatusListCredential that contains both
a ttl property and a validUntil property, each with a different value
(i.e., each indicating a different point in time when the credential is to
"expire"), it is not clear which (if either) property a validator can be
expected to ignore. In other words, if a ttl value specifies an expiration
datetime of midnight today, but the validUntil property specifies an
expiration datetime of midnight tomorrow, then what is a verifier
expected to do? Fundamentally, ttl and validUntil have conflicting
semantics. One way to resolve this conflict is to remove ttl and specify
that caching behavior can be expressed using protocol mechanisms (such as the
expires header in HTTP), and that any caching performed MUST align with the
validUntil value for the verifiable credential. The Working Group is
seeking feedback from the implementer community regarding this feature.
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
BitstringStatusListEntry (see 2.1 BitstringStatusListEntry).
type
The verifiable credential that contains the status list MUST
express a type property that includes the
BitstringStatusListCredential 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 BitstringStatusList.
credentialSubject.statusPurpose
The value of the purpose property of the status entry, statusPurpose, MUST be
one or more strings. While the value of each string is arbitrary, the following
values MUST be used for their intended purpose:
Value
Description
revocation
Used to cancel the validity of a verifiable credential. This status is
not reversible.
suspension
Used to temporarily prevent the acceptance of a verifiable credential.
This status is reversible.
message
Used to indicate a status message associated with a verifiable
credential. The status message descriptions MUST be defined in
credentialSubject.statusMessages. credentialSubject.statusSizeMUST be
specified when this statusPurpose value is used.
credentialSubject.encodedList
The encodedList property of the credential subjectMUST be a
Multibase-encoded base64url (with
no padding) [RFC4648] representation of the GZIP-compressed [RFC1952]
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 6.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 BitstringStatusListCredential 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.
The example below demonstrates how the BitstringStatusListEntry is used
with a BitstringStatusListCredential to provide the verifier with
the information necessary to determine the status of a particular
verifiable credential.
The following section outlines the algorithms that are used to generate
and validate status lists as described by this document.
If an implementation of any of the algorithms in this section processes a property
defined in Section 2. Data Model whose value is malformed due to
not complying with associated "MUST" statements, a
MALFORMED_VALUE_ERRORMUST be raised.
(Feature at Risk) Issue 3: Attempting alignment with IETF Token Status List specification
The Working Group is seeking feedback related to implementer desire to align
with the IETF OAuth Working Group
Token Status List specification (formerly titled OAuth Status List, and
JWT and CWT Status List). If there is interest,
and to the extent possible, this specification might align
more closely with the Token Status List bitstring format, as it could be
beneficial to have one code base able to process bitstring values from
both lists. If there is implementer support for such changes, they
might be made during the Candidate Recommendation phase.
3.1 Generate Algorithm
The following process, or one generating the exact output, MUST be followed
when producing a
BitstringStatusListCredential.
The algorithm takes a list of issued credentials as input and either throws
an error or returns a status list credential as output.
Generate a proof for the statusListCredential and publish it to the
endpoint listed in the verifiable credential.
IssuersSHOULD publish status list credentials in a way that can be cached
and that does not track who retrieves the status list credential, such as
through Oblivious HTTP, a content distribution network that is not operated by
the issuer, or business processes for which the access logs are not
accessible by data analysts or systems administrators.
3.2 Validate Algorithm
The following process, or one generating the exact output, MUST be followed
when validating a verifiable credential that is contained in a
BitstringStatusListCredential.
The algorithm takes a status list verifiable credential as input
and either throws an error or returns a status list credential as output.
Let minimumNumberOfEntries be 131,072 unless a different lower bound is
established by a specific ecosystem specification.
Let status purpose be the value of statusPurpose
in the credentialStatus entry in the
credentialToValidate.
Dereference the statusListCredential URL, and ensure that all
proofs verify successfully. If the dereference fails, raise a
STATUS_RETRIEVAL_ERROR. If any of the
proof verifications fail, raise a
STATUS_VERIFICATION_ERROR.
Verify that the status purpose is equal to a statusPurpose value in the
statusListCredential. Note: The statusListCredential might contain multiple
status purposes in a single list. If the values are not
equal, raise a
STATUS_VERIFICATION_ERROR.
Let status be the value in the bitstring at the position indicated
by the credentialIndex multiplied by the size. If the credentialIndex
multiplied by the size is a value outside of the range of the bitstring, a
RANGE_ERRORMUST be
raised.
Set the status key in result to status, and set the purpose key in
result to the value of statusPurpose.
If status is 0, set the valid key in result to true; otherwise, set it
to false.
If the statusPurpose is message, set the message key in result to the
corresponding message of the value as indicated in the statusMessages
array.
Return result.
When a statusListCredential URL is dereferenced, server implementations MAY
provide a mechanism to dereference the status list as of a particular point in
time. When an issuer provides such a mechanism, it enables a
verifier to determine changes in status to a precision chosen by the
issuer, such as hourly, daily, or weekly. If such a feature is supported, and if
query parameters are supported by the URL scheme, then the name of the query
parameter MUST be timestamp and the value MUST be a valid URL-encoded
[XMLSCHEMA11-2] dateTimeStamp string value. The result of dereferencing such a
timestamp-parameterized URL MUST be either a status list credential containing
the status list as it existed at the given point in time, or a
STATUS_RETRIEVAL_ERROR. If the result is
an error, implementations MAY attempt the retrieval again with a different
timestamp value, or without a timestamp value, as long as the verifier's
validation rules permit such an action.
VerifiersSHOULD cache the retrieved status list and SHOULD use proxies
or other mechanisms, such as Oblivious HTTP, that hide retrieval behavior from
the issuer.
Note: Issuer validation is use case dependent
It is expected that a verifier will ensure that it trusts the issuer
of a verifiable credential, as well as the issuer of the associated
BitstringStatusListCredential,
before using the information contained in either credential for further
decision making purposes. Implementers are advised that the issuers of these
credential might differ, such as when the original issuer of the
verifiable credential does not maintain a record of its validity.
3.3 Bitstring Generation Algorithm
The following process, or one generating the exact output, MUST be followed
when generating a status list bitstring. The algorithm takes an
issuedCredentials list as input and either throws an error or returns a
compressed bitstring as output.
Let bitstring be a list of bits with a minimum size of 16KB,
where each bit is initialized to 0 (zero).
For each value in 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 statusSize.
Generate a compressed bitstring by using the GZIP
compression algorithm [RFC1952] on the bitstring
and then base64url-encoding (with no padding) [RFC4648] the result.
Return the compressed bitstring.
3.4 Bitstring Expansion Algorithm
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 either throws an error or returns a
uncompressed bitstring as output.
Let compressed bitstring be a compressed status list
bitstring.
Generate an uncompressed bitstring by using the
base64url-decoding (with no padding) [RFC4648] algorithm on the
compressed bitstring and then expanding the output using
the GZIP decompression algorithm [RFC1952].
Return the uncompressed bitstring.
3.5 Processing Errors
The algorithms described in this specification throw specific types of errors.
Implementers might find it useful to convey these errors to other libraries or
software systems. This section provides specific URLs, descriptions, and error
codes for the errors, such that an ecosystem implementing technologies described
by this specification might interoperate more effectively when errors occur.
When exposing these errors through an HTTP interface, implementers SHOULD use
Problem Details for HTTP APIs [RFC9457] to encode the error data structure. If [RFC9457] is
used:
The type value of the error object MUST be a URL that starts with the value
https://www.w3.org/ns/credentials/status-list# and ends with the value in the
section listed below.
The code value MUST be the integer code described in the table below
(in parentheses, beside the type name).
The title value SHOULD provide a short but specific human-readable string for
the error.
The detail value SHOULD provide a longer human-readable string for the error.
All human-readable strings SHOULD be localized as described in Section 1 of
Problem Details for HTTP APIs, using language negotiation through the Accept-Language
HTTP header field to select the most appropriate resources.
When dereferencing statusListCredential, the content of the returned
statusListCredential might be any media type registered for the purpose of
expressing a verifiable credential with one or more proofs.
For example, a verifiable credential secured with Data Integrity Proofs might
have media type application/vc+ld+json, while a verifiable credential
secured with SD-JWT might have media type application/sd-jwt.
Some implementations might choose to support less specific media types such as
application/ld+json or application/json.
When dereferencing over HTTP, the use of the accept
and content-type headers, might allow
some implementations to negotiate for the proof format used to secure the
statusListCredential.
Some implementations might use the 415
Unsupported Media Type status code to signal that they do not support the
requested media type.
5. Privacy Considerations
This section is non-normative.
This section details the general privacy considerations and specific privacy
implications of deploying this specification into production environments.
This document specifies a minimum revocation bitstring length of 131,072, or
16KB uncompressed. This is enough to give holders an adequate amount of
group 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.
5.2 Unnecessary Correlation
This section is non-normative.
There are a number of global identifiers used in a status list entry, defined in
Section 2.1 BitstringStatusListEntry, that can be used across verifiers
to correlate subjects. Some of the properties that can
express these values are id, statusListIndex, and
statusListCredential.
In some cases, such as when presenting a verifiable credential that
contains a global identifier (such as a driver's license identification number),
adding one or more global identifier(s) for status list information does not
increase correlation harm, since a single globally unique identifier is all that
is required for correlation.
When global identifiers are used in presentations that use
selective disclosure or unlinkable disclosure, they can violate privacy
expectations. Issuers are urged to enable status information to be
selectively disclosable/concealable when a particular verifiable credential
is expected to be disclosed in a way that does not need correlation, such as when
proving that an individual is above a certain age. Verifiers can require
that status information be revealed in situations that require them to know the
current status of a credential, and the holder might then consent or refuse to
reveal that information for a given transaction. In all cases, both issuers
and verifiers are urged to avoid the use of global identifiers in order to
prevent correlation, unless it is required for or by a particular exchange.
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.
5.4 Content Distribution Networks
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.
5.5 Decoy Values
This section is non-normative.
Issuer use of decoy values in status lists has been explored as a mechanism
to increase the privacy of subjects. While algorithms for employing decoy
values are out of scope for this specification, implementers are advised that
the use of decoy values does not improve privacy and can harm privacy in
most cases.
When indexes of status list entries are allocated in a random fashion, which is
the suggested mode of operation for this specification, adding decoys harms
privacy because it reduces the true group size by the number of decoys added
to the group. A random allocation of indexes inherently hides the true size of
the group without reducing it, ensuring that decoys are not necessary.
There might be use cases where decoy values provide benefits. Implementers are
cautioned that no such use cases were clearly identifiable by the group that
created this specification. Therefore, the use of decoys is discouraged for
most if not all use cases, as random allocation of status list entry indexes
provides adequate protection.
5.6 Malicious Issuers and Verifiers
This section is non-normative.
In general, the group 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 verifier might intentionally attack group privacy by sharing
information from presented credentials with a malicious issuer. This
sort of collusion is difficult to detect as it is typically performed via a
secure communication channel between the issuer and the verifier.
A malicious issuer might intentionally attack group privacy by creating a
unique status list for each issued credential, in order to establish a one-to-one
mapping to track when a verifier processes each mapped credential. Similarly,
they could establish a one-to-one mapping by using a different
cryptographic key for each issued credential that is tracked by a given status list.
This sort of collusion can be detected by holder software that serves
multiple holders (e.g., a holder app that runs on a server) if it
has, for example, an opt-in process that finds that some global identifier(s)
used within a verifiable credential are not adequately shared by other
credentials.
Holders could then be warned when presenting a verifiable credential
that contains some global identifier(s) that are unique to that credential.
Such an opt-in service could represent some additional privacy concerns;
whether this potential exposure via the holder software is justified by
the awareness of possible global identifier correlation can only be evaluated
by the users of such a system.
5.7 Monitoring Status Lists
This section is non-normative.
Once a verifier knows of a status list and entry index that is
associated with a specific holder or subject, it becomes possible for that
verifier to see updates to that status entry as long as the
status list continues to be updated. This is useful to a verifier that
needs to understand when a particular verifiable credential has changed
status without asking the issuer directly for status information on
the specific verifiable credential or when interacting with the holder to get
the latest status information is not possible. The feature can also cause a
privacy violation for the holder and/or subject if the
verifier is able to perform near-real-time checks on the status of the
verifiable credential.
Issuers can provide a level of reprieve from this privacy concern
holders by revoking and reissuing effectively the same
verifiable credential on a timeline that is relatively short in nature.
For example, an issuer could automatically reissue a
verifiable credential every three months and assign a new status entry
index when the reissuance occurs to break any sort of long-term monitoring
of a verifiable credential as it changes status.
5.8 Correlation of Status Messages
This section is non-normative.
This specification provides a means by which multiple status messages can be
provided for a particular entry in a status list. While this mechanism can
provide more detailed information for a particular entry in the status list,
that information can provide further correlation data.
For example, if each status message is associated with a step in a particular
process, or more detailed information as to why a credential was revoked or
suspended, then an attacker that observes the changes in the list might be
able to correlate information about the population of entities in the list
that could lead to privacy violations. Understanding how a population
progresses through a business process, or what percentage of the population
is likely to be associated with a certain status, provides additional
information to an attacker. Given such information, a phishing operation could
predict what the next step of a business process is and then preemptively
contact an entity whose current status is known. Then, based on that
information, they could attempt to phish more lucrative information from
the target using data gleaned from the status list over time.
For these reasons, issuers are urged to evaluate the potential ramifications of
publishing detailed status information about a particular entity, or a
population, in a public manner.
5.9 Alteration of Status Messages
This section is non-normative.
When a status list uses the status messages feature, it becomes possible for
the issuer to increase the types of messages that are associated with
the verifiable credentials it issues over time.
This feature creates a potential privacy violation where the
subject or holder of the verifiable credential might be
associated with additional status information that was not present when the
original verifiable credential was issued. For example, initial status
messages might convey "delayed" and "canceled", but additional status messages
might be added by the issuer to convey "delayed due to non-payment" and
"canceled due to illegal activity". This change would not be apparent to the
subject or holder unless there was monitoring software operating
on their behalf that would warn them that the issuer intends to expose
additional information about their activity.
Holder software can provide features to holders that warn them about the
level of holder and/or subject information exposure when using
verifiable credentials that are associated with status messages, and warn
them when the level of information exposure changes.
6. Security Considerations
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.
6.1 Bitstring Encoding
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 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.
Figure 2
A visual depiction of the bitstring layout.
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.
9.1.3 Multiple Status Lists in One Verifiable Credential
This specification enables an issuer to associate multiple status lists
with a single verifiable credential.
Example 6: Associating multiple status lists with a single Verifiable Credential
{
"@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",
"issuanceDate": "2021-04-05T14:27:42Z",
// note the use of an array to represent the set of
// status entries
"credentialStatus": [{
"id": "https://example.com/credentials/status/3#94567",
"type": "BitstringStatusListEntry",
"statusPurpose": "revocation",
"statusListIndex": "94567",
"statusListCredential": "https://example.com/credentials/status/3"
}, {
"id": "https://example.com/credentials/status/4#12345",
"type": "BitstringStatusListEntry",
"statusPurpose": "suspension",
"statusListIndex": "12345",
"statusListCredential": "https://example.com/credentials/status/4"
}],
"credentialSubject": {
"id": "did:example:6789",
"type": "Person"
}
}
9.1.4 Multiple Status Entries in a Single List
It is possible for a single status list to contain multiple types of status
purposes. Doing so can make the retrieval of a list slightly more efficient
than fetching multiple status lists.
(Feature at Risk) Issue 4: Efficiency argument is weak
The "space efficiency" argument for this feature is weak. One list with two types
of status entries must, presumably, be twice as long as a list with one type of
status entries, to ensure proper privacy protections. One privacy benefit of
doing so is that bit flips cannot be known to be associated with a particular
status unless one is also in control of the VC that the status is about.
Therefore, mixing "revocation" and "suspension" in a single list that is twice
as large has positive privacy implications.
The "retrieval efficiency" argument is also weak. Performing two HTTP retrievals
instead of one is probably not significant. Performing upwards of five or six,
on a list that is five or six times larger, might result in fairly meager
savings over modern versions of HTTP that bundle requests over a single channel
(such as HTTP/2 or HTTP/3). The requests themselves would save a handful of
bytes with no significant improvement in retrieval speed.
The Working Group is looking for feedback from implementers and is considering
striking this feature during the Candidate Recommendation period, since it would
simplify the specification for implementations to not have to support sets of
statusPurpose values in the status list credentials (again, a meager savings
in space efficiency at a small cost to retrieval efficiency).
Example 7: Associating multiple status entries in a single status list
{
"@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",
"issuanceDate": "2021-04-05T14:27:42Z",
// note the use of a single list to store multiple
// status entries
"credentialStatus": [{
"id": "https://example.com/credentials/status/5#94567",
"type": "BitstringStatusListEntry",
"statusPurpose": "revocation",
"statusListIndex": "94567",
"statusListCredential": "https://example.com/credentials/status/5"
}, {
"id": "https://example.com/credentials/status/5#12345",
"type": "BitstringStatusListEntry",
"statusPurpose": "suspension",
"statusListIndex": "12345",
"statusListCredential": "https://example.com/credentials/status/5"
}],
"credentialSubject": {
"id": "did:example:6789",
"type": "Person"
}
}
