The Credential Status framework is fundamental since it allows the issuers to have fine-grained control over the lifetime of the credentials they issue. An efficient framework must cover a wide range of business requirements and a variety of scenarios, ranging from online in-time VC issuance to offline cases with long-lived VCs and deferred verification. User privacy must be respected in all cases without compromising the framework's security.
This framework is designed to meet the EBSI use-case business requirements and builds on the outcomes of an extensive independent study. We decoupled the revocation/suspension strategies from data models so that use cases can pick any strategy and use a data format that best meets their business, privacy, and security requirements. Both the revocation/suspension strategies and the data formats can be developed further without interfering with each other.
Central to the Credential Status framework is the concept of VC validity. The validity of a VC is contingent upon three key components. The first component involves the VC's inherent properties, including its expiration date if one is assigned. It is also crucial to validate the authenticity of the public keys used for digitally signing/sealing the VC and their corresponding attestations. The final component considers the VC's current status as either valid, revoked, or suspended. The intrinsic properties of the VC, including its expiration date.
In these guidelines, we first present an overview of different options. Next, we deep dive into the different credential status strategies and conclude with a presentation of the supported data models.
| VC Status Strategy | Description | Legal Entity VCs | Natural Person VCs | Information revealed |
|---|---|---|---|---|
| Short VC lifetime* | Issuer issues VCs with a short lifetime, e.g., hours, days. Two strategies are possible: a) Re-issuance of the original VC with new duration b) Issuance of an additional one-time status VC | ✓** | ✓ | The Issuer learns what VC is presented and when by a holder. It doesn't learn about the Verifier. |
| VC Status managed in a Trusted Registry | When a reliable history of the VC status is required, the information can be stored in the corresponding Trusted Registry. Applicable only to Legal Entities. | ✓ | / | No information is revealed to the Issuer. |
| VC Status managed by the Issuer - direct retrieval* | The Trusted Issuer hosts VC status information, and verifiers retrieve the VC directly from the Trusted Issuer. | ✓ | ✓ | The Issuer learns which Verifier and when one of the VCs is received in the revocation or suspension list. |
| VC Status managed by the Issuer - retrieval via the Holder | The Trusted Issuer hosts VC status information; however, Holder fetches and presents the revocation/suspension information. | ✓** | ✓ | The Issuer learns what VC is presented and when by a holder. It doesn't learn about the Verifier. |
| VC Status managed by the Issuer - retrieval via EBSI | The Trusted Issuer hosts VC status information; however, the verifiers retrieve the information via an EBSI node. This way, issuers never learn who asked for the VC status information. | ✓ | ✓ | No information is revealed to the Issuer. |
* The approach may allow the issuers to trace or profile the users.
** Limited use.
The five revocation/suspension strategies are presented in detail in the following section.
Presentation of strategies for a credential Status framework
This section presents strategies to support a credential status framework to verify VC.
Issuing Short-lived Verifiable Credentials
Use cases that rely on the short VC lifetimes controlled via the VC expiration date do not require additional credential status infrastructure. They may a) re-issue the VC or b) issue an accompanying one-time VC that attests to the status of another Verifiable Credential. Both options are already supported by the existing VC issuance protocols supported by EBSI.
The approach has the following advantages:
- Relies on the existing VC issuance infrastructure.
- Verification is simple (in the context of VC status validation, only the expiration date must be checked).
- Information is always fresh.
- Verifier cannot track holder status changes.
The approach comes with the following limitations:
- The Issuer learns about the Holder's activities (which VC is shared when), which raises privacy concerns.
- Both the Issuer and Holder must be online.
- The Issuer must support in-time VC issuance.
- Not applicable to Verifiable Authorisations.
Issuing long-lived Verifiable Credentials with direct or Holder-based retrieval
In many cases, issuing short-lived VCs is not possible or desirable due to functional, security, or privacy concerns. In such cases, the Issuer can control the VC lifetime via a Credential Status VC. Verifiers can fetch the Credential Status VC directly from the Issuer. Information about the location of the Credential Status VC is in the VC itself.
The approach has the following advantages:
- Works in the case when the holder's wallet is offline, or connection is poor.
- VC status information is up to date.
The approach comes with the following limitations:
- The Issuer learns which Verifier received the VC.
- Depending on the format, the Issuer may be unable to limit how long a verifier can check the information.
- Without an additional infrastructure, the Issuer has no information about the user's consent.
- Not the best approach for Verifiable Accreditations if the accreditation chains are long.
A second option is to retrieve the Credential Status VC via the Holder's wallet. In this case, the Holder's wallet fetches and shares the information with the VC.
The approach has the following advantages:
- VC status information is up to date.
- Issuer doesn't know about the Verifier.
The approach comes with the following limitations:
- The Issuer can track the user activity.
- Depending on the format, the Issuer may be unable to limit how long a verifier can check the information.
- It only works if the wallet is online and the connection is reliable.
- Creates additional traffic for the wallet, which may affect the performance.
Issuing long-lived Verifiable Credentials with retrieval through EBSI network
To overcome the privacy, security, and functional constraints of the approaches presented above, we are introducing an approach where the Credential Status VC is hosted and managed by the Trusted Issuers and is retrieved via the EBSI network to ensure the highest level of privacy and availability. Details are presented in the next section.
The approach has the following advantages:
- Applicable to Legal Entity and Natural Person VCs
- Issuer only learns that a VC from the revocation/suspension list has been shared without knowing who shared the information or with whom the information has been shared.
- It works even if the Holder's wallet is offline.
- Depending on the format, it can limit how long the information is visible to the Verifier.
- Information is shared from the Issuer to the EBSI network to the Verifier; hence there is no additional traffic for the wallet.
The approach has the following limitations:
- It requires the EBSI network.
Credential status retrieval through EBSI network
Upon issuance of a VC, VC status information is communicated and disseminated alongside the credential itself. This information can be dereferenced to a data structure presented as a VC, which contains information that provides insight into the status of the VC in question. The Issuer is responsible for hosting the Credential Status VC, and the EBSI platform acts as a proxy between the Issuer and Verifier. A decentralised network like EBSI is crucial to increase privacy when Natural Person or Legal Entity VC statuses are checked. The information about the Issuer's endpoint serving the information is public and registered in the Trusted Issuers Registry.
The following diagram depicts the exchange of Credential Status VC between a verifier and an issuer, proxied by the Trusted Issuer Registry:
The dotted line denotes that the Credential Status VC can be fetched directly from the Trusted Issuer if required by the use case or regulation. Due to privacy concerns, direct Credential Status VC retrieval is not recommended.
Setup of Status API
The Issuer must register the Credential Status API endpoints on the EBSI Trusted Issuers Registry. When a request is submitted, a Credential Status VC is returned in a JWT-VC format, signed by the Issuer of the referenced VC. The Credential Status VC schemas of the supported revocation/suspension formats are defined in the JSON schema repository.
The following OpenAPI specification defines interfaces issuers must expose so that the Trusted Issuers Registry can fetch the information.
The timestamp query parameter is only supported by the Dynamic SL Bloom Filter 2023 and should be ignored for all others.
VC Status proxy
The Issuer must configure a minimum of one proxy before a Status VC request is processed to protect the privacy of the Verifier's activities. The proxy is created using the Trusted Issuers Registry JSON-RPC method addIssuerProxy, and AttributeData must contain the proxy configuration. The configured proxy must provide a valid Status VC signed by the Issuer requesting the proxy for the registration to be accepted. A validation combining "prefix" with "testSuffix" is executed before the registration is accepted. The validation will fail if the credential status proxy does not exist.
The proxies operate by replacing the original URL prefix with a configured prefix and inserting a header into the call. The configuration must be uploaded into issuer attributes.
Configurable properties for the proxy are presented in the following table:
| Attribute | Action | Original / Default | Description |
|---|---|---|---|
| prefix | Replace prefix | https://{ebsi-host}/trusted-issuers-registry/v5/issuers/{did}/proxies/{attribute-id}/ | Replace the original URL prefix with the configured prefix |
| headers | Add headers | N/A | Must be an object. Add static headers into the call. These are public information for everyone to read. |
| testSuffix | Suffix to pass registration | N/A | During initial registration, the prefix + suffix provides a match to a valid signed status list. The suffix is used to pass the validation. |
Example
Configuration: {"prefix": "https://localhost/my-provider/revocation/","headers":{"Authorization": "Bearer ABC"}, "testSuffix": "/credentials/status/1"}
Attribute-id for the configuration: f320c23d1b772dafdc45eec0f0e1a1bc456a283a786eb014078a5120b90451cf
Registration validation with:
GET https://localhost/my-provider/revocation/credentials/status/1
Verifier executing:
GET https://api-pilot.ebsi.eu/trusted-issuers-registry/v5/issuers/did:ebsi:zyrMG8T9xYbNoSwyQa4SGMJ/proxies/f320c23d1b772dafdc45eec0f0e1a1bc456a283a786eb014078a5120b90451cf/credentials/status/5
Proxy executing:
GET https://localhost/my-provider/revocation/credentials/status/5
Validate VC - is registered:
HEAD https://api-pilot.ebsi.eu/trusted-issuers-registry/v5/issuers/did:ebsi:zyrMG8T9xYbNoSwyQa4SGMJ/proxies/f320c23d1b772dafdc45eec0f0e1a1bc456a283a786eb014078a5120b90451cf