Token Status List feature support
A feature-by-feature reference for how MATTR VII supports the IETF Token Status List specification, as profiled by ISO/IEC 18013-5 for mDocs, when issuing revocable credentials and hosting status lists.
Overview
This page is a feature-by-feature reference for how MATTR VII supports the IETF Token Status List specification when issuing revocable mDocs and publishing their status.
MATTR VII fills three specification roles at once:
- Status Issuer: it allocates a status entry for each revocable credential and changes that entry when you revoke.
- Status Provider: it hosts and signs the status list tokens that relying parties fetch.
- Issuer of the Referenced Token: it embeds the status reference into the credential itself.
MATTR's implementation follows the profile defined by ISO/IEC 18013-5 second edition, clause 12.3.6, which constrains the IETF specification for mDocs. Both specifications apply, and the two disagree on a few points that are called out in the notes below.
It complements Revocation, which explains what status lists are and how to use them. Use this page when you need to know whether a specific feature of the specification is implemented, for example when answering a conformance question or writing an integration profile for a relying party.
If you are checking status rather than publishing it, see Token Status List feature support (Verifier) or Token Status List feature support (Holder).
How to read this page
Each feature is given one of the following support statuses:
- Supported: Implemented and available for use.
- Partial: Implemented with a specific limitation, described in the notes.
- Not supported: Not currently implemented. Some fields may be parsed for specification compliance without any behavior attached.
- Not applicable: Not relevant to the issuer role.
The Spec column cites the relevant section of
Token Status List draft 14
unless the citation names another specification. Citations beginning 18013-5 refer to
ISO/IEC 18013-5 second edition, which profiles the IETF
specification for mDocs, for example 18013-5 12.3.6.5. n/a means the feature is either a MATTR
extension or a behavior that neither specification defines.
Support statuses reflect the current MATTR VII platform. If you need clarification on any feature, contact us.
Credentials issued before Draft 14
MATTR VII issued status lists in an earlier MATTR format before adopting Draft 14. Those credentials remain valid and their status lists continue to be served, so a tenant can be publishing both. The format is fixed for the life of a credential and cannot be changed after issuance. See Backward compatibility.
Status list token
| Feature | Spec | Status | Notes |
|---|---|---|---|
| Status list token in CWT format | § 5.2 | Supported | The only format MATTR VII produces. The token is a COSE_Sign1 structure as defined by RFC 8392. |
| Status list token in JWT format | § 5.1 | Not supported | application/statuslist+jwt is never produced. ISO requires the CWT form for mDocs. |
typ protected header | § 5.2, 18013-5 12.3.6.5 | Supported | Set to application/statuslist+cwt. |
x5chain protected header | 18013-5 12.3.6.3 | Supported | Carries the status list signer certificate chain. This is how a relying party establishes trust. |
kid protected header | § 11.3 | Not supported | Key resolution is by certificate chain rather than key identifier. |
sub claim (key 2) | § 5.2 | Supported | Set to the token URI, and it must match the uri in the credential's status reference. |
iat claim (key 6) | § 5.2 | Supported | The time the token was signed. |
exp claim (key 4) | § 5.2, 18013-5 12.3.6.3 | Supported | Always present, as ISO requires. Defaults to one week, can be configured up to 30 days, and never exceeds the validity of the signing IACA. |
ttl claim (key 65534) | § 5.2, 18013-5 12.3.6.3 | Supported | Always present. Defaults to one day, with a minimum of one minute, and never exceeds exp. |
status_list claim (key 65533) | § 4.3, § 5.2 | Supported | Carries bits and lst. |
aggregation_uri inside the status list | § 4.3, § 9.2 | Not supported | Aggregation is advertised out of band instead. See Status list aggregation. |
iss claim (key 1) | § 5.2 | Not supported | Not emitted. The signer is identified by the certificate chain. |
nbf claim (key 5) | § 5.2 | Not supported | Not emitted. Tokens are valid from iat. |
| Signature algorithm | 18013-5 12.3.6.3 | Partial | ES256 only. ISO also permits ES384, ES512 and EdDSA. |
| MAC protection instead of a signature | § 11.6 | Not supported | Tokens are always signed. |
lst compression | § 4.1 | Supported | DEFLATE in ZLIB format, at the highest compression level the specification recommends. |
| Status bit packing order | § 4.1 | Supported | Values are packed least significant bit first within each byte. |
| Default value for unassigned entries | § 13.3 | Supported | Lists are initialized so that an unassigned index reads as VALID. |
| Obscuring how many credentials are managed | § 12.5.1 | Supported | Every list is created at its full size, so an unassigned index is indistinguishable from a valid one. |
| Pseudo-random or non-sequential index allocation | § 13.2 | Not supported | Indices are allocated sequentially within a list. |
Status types
| Feature | Spec | Status | Notes |
|---|---|---|---|
VALID (0x00) | § 7.1 | Supported | The status of every credential when it is issued. |
INVALID (0x01) | § 7.1 | Supported | Set when you revoke a credential. This is permanent, matching 18013-5 12.3.6.1. |
| Reactivating a revoked credential | § 7.1 | Not supported | invalid is a final state. An attempt to change it is rejected with a 400 response. To restore a holder, issue a new credential. |
SUSPENDED (0x02) | § 7.1, 18013-5 12.3.6.1 | Not supported | A one bit status list can only carry two values, and ISO does not allow suspension for the mDL document type. |
Application-specific status types (0x03, 0x0C to 0x0F) | § 7.1 | Not supported | |
| Other registered status types | § 14.5 | Not supported | |
bits value 1 | § 4.1, 18013-5 12.3.6.5 | Supported | The value ISO requires for mDocs. |
bits values 4 and 8 | § 4.1 | Not supported | Never emitted, and not accepted when reading a status list. |
Suspension is not available
Suspension was available on the earlier MATTR status list format, which used two bits per credential. A Draft 14 status list uses one bit, so it can only express valid and invalid. If your integration relied on a temporary suspension, model it as revocation followed by reissuance instead.
Referenced token
The referenced token is the credential that points at a status list entry.
| Feature | Spec | Status | Notes |
|---|---|---|---|
status element in the MSO | § 6.3.2, 18013-5 12.3.6.2 | Supported | Added to the Mobile Security Object payload when the credential is revocable. See mDocs structure. |
status_list with uri and idx | § 6.3, 18013-5 12.3.6.5 | Supported | uri is the public token endpoint and idx is the credential's offset in that list. |
| Opting a credential in to revocation | n/a | Supported | Set includeStatus to true on the mDoc credential configuration or the sign request. Credentials are not revocable by default. |
Unique uri and idx per credential | § 13.3 | Supported | No index is allocated twice. |
Optional certificate element in the status reference | 18013-5 12.3.6.2 | Not supported | Not emitted, so a relying party cannot be handed a separate trust anchor for the status list. The status list signer must chain to the same IACA that signed the credential. |
identifier_list element in the MSO | 18013-5 12.3.6.4 | Not supported | An alternative to status lists. See Upcoming standards. |
status claim in a JOSE referenced token | § 6.2 | Not supported | The status claim is not attached to any JOSE-based credential MATTR VII issues. |
status claim (key 65535) in a CWT referenced token | § 6.3.1 | Not supported | MATTR CWT credentials use a different revocation mechanism. See Other revocation mechanisms. |
| Batches of single-use credentials to reduce linkability | § 12.5.1 | Not supported | One credential holds one status entry. |
Hosting the status list
| Feature | Spec | Status | Notes |
|---|---|---|---|
| Fetching a status list token over HTTP GET | § 8.1 | Supported | GET /v2/credentials/mobile/status-lists/{id}/token, public and unauthenticated. |
Accept header negotiation | § 8.1 | Partial | Only application/statuslist+cwt is accepted. Any other value is rejected with 406 Not Acceptable. An absent Accept header is treated as a request for CWT. |
Response Content-Type | § 8.2 | Supported | Always application/statuslist+cwt. |
| Raw binary CWT response body | § 8.2 | Supported | The body is the signed token, not a JSON envelope. |
| HTTPS-only status list URIs | § 11 | Supported | Token URIs are always HTTPS. |
Content-Encoding: gzip | § 8.2 | Not applicable | Recommended by the specification only for the JWT format. The CWT payload is already compressed. |
HTTP 3xx redirects | § 8.2 | Not applicable | The token endpoint serves tokens directly. |
Cache-Control response headers | § 8.2 | Not supported | No HTTP caching headers are set. Relying parties use the exp and ttl claims, which the specification requires them to prioritize over HTTP headers anyway. |
Historical resolution with a time query parameter | § 8.4 | Not supported | The parameter is ignored and the current token is returned, rather than the 501 response the specification recommends. A client that needs point-in-time resolution must apply the rule in § 8.4 and reject a token whose iat to exp window does not cover the requested time. |
| Rate limiting | n/a | Supported | Public endpoints allow five requests per second. A 429 response carries an x-ratelimit-reset header. |
Status list aggregation
Aggregation lets a relying party download every status list an issuer publishes, so it can verify credentials while offline.
| Feature | Spec | Status | Notes |
|---|---|---|---|
| Aggregation endpoint | § 9 | Supported | GET /v2/credentials/mobile/status-lists/distribution, public and unauthenticated. |
status_lists array of token URIs | § 9.3 | Supported | |
application/json response | § 9.3 | Supported | |
| Excluding lists signed by expired IACAs | n/a | Supported | Tokens that can no longer be verified are left out of the response. |
status_list_aggregation_endpoint in authorization server metadata | § 9.1 | Supported | Published in /.well-known/oauth-authorization-server, pointing at the distribution endpoint above. |
status_list_aggregation_endpoint in credential issuer metadata | § 9.1 | Not supported | Absent from /.well-known/openid-credential-issuer. |
| Aggregation URI carried in the issuer certificate | § 9.1 | Supported | The IACA carries it in the MATTR private X.509 extension 1.3.6.1.4.1.61546.100. The specification allows a certificate as the carrier without defining an encoding for it. |
| Aggregation URI carried in a VICAL | § 9.1 | Not supported | |
aggregation_uri claim inside a status list token | § 9.2 | Not supported | |
| Restricting an aggregation to one credential type | § 9.1 | Not supported | One tenant-wide aggregation covers every document type. |
Lifecycle, keys and caching
| Feature | Spec | Status | Notes |
|---|---|---|---|
| Automatic status list creation | n/a | Supported | Lists and their configurations are created on demand when a revocable credential is signed. |
| Status list size | § 13.4 | Supported | 500,000 entries per list, byte aligned. |
| Multiple status lists per tenant | § 13.4 | Supported | Lists are partitioned by document type, signing IACA and format. |
Configurable ttl and exp | § 13.7 | Supported | A status list configuration sets timeToLiveDuration and expiryDuration, and is unique per document type per tenant. See Status list configuration. |
| Re-signing on change | § 13.7 | Supported | A token is re-signed when its ttl expires, when a credential on the list changes, when a credential is added, or when the configuration changes. |
| Server-side token caching | § 13.7 | Supported | Signed tokens are cached for between one minute and 24 hours, and the cache is invalidated when a status or the configuration changes. |
| Signing by a dedicated status list signer | 18013-5 12.3.6.2 | Supported | The signer certificate chains to the IACA that signed the credentials on the list. MATTR VII manages these signers by default. |
| Externally managed status list signers | n/a | Supported | Available if you use unmanaged certificates. |
id-kp-oauthStatusSigning extended key usage | § 10, 18013-5 12.3.6.3 | Not supported | The specification has not yet been assigned an object identifier for this key purpose, so no implementation can set it. MATTR uses a private extended key usage instead. |
| Status list signer revocation | § 11.3 | Partial | Revoking a signer publishes its serial number to the CRL referenced by the issuing IACA. Neither MATTR VII verification nor the MATTR SDKs fetch or process CRLs, so this is only actioned by relying parties that do so themselves. |
| IACA deletion | n/a | Supported | Deleting an IACA deletes the status lists it signed. The token endpoint then returns 410 Gone and the credential's status becomes unknown. |
| Revoking on credential deletion | n/a | Supported | Deleting a credential sets its status to invalid first. |
Credential formats
Token Status List applies only to mDocs.
| Format | Spec | Status | Notes |
|---|---|---|---|
ISO mdoc / mDL (mso_mdoc) | § 6.3.2, 18013-5 12.3.6 | Supported | The only format that uses Token Status List. |
IETF SD-JWT VC (dc+sd-jwt) | § 6.2 | Not supported | |
W3C VC JWT (jwt_vc_json) | § 6.2 | Not supported | |
W3C VC JSON-LD (ldp_vc) | § 6.2 | Not supported | |
| MATTR CWT and Semantic CWT | § 6.3.1 | Not supported | These use a different mechanism, described below. |
| W3C Bitstring Status List | n/a | Not supported | MATTR VII does not implement statusPurpose or any W3C status list format. |
Other revocation mechanisms
Not every MATTR VII credential format uses Token Status List. If you are working with a format other than mDocs, these pages apply instead:
- CWT and Semantic CWT credentials use MATTR revocation lists, where a credential references an index in a list and the status is a single boolean. See Revocation.
- Web-semantic JSON-LD credentials use W3C RevocationList2020, also a boolean status, with an optional DIDComm notification sent to the holder.
- The ISO identifier list, an alternative to status lists defined in
18013-5 12.3.6.4, is not available. See Upcoming standards.
Not currently supported
At a glance, the following features of the specification are not currently implemented on the issuer side:
- Status list tokens in JWT format (§ 5.1)
bitsvalues of 4 and 8 (§ 4.1)aggregation_uriinside a status list token (§ 4.3, § 9.2)iss,nbfandkidin the status list token (§ 5.2, § 11.3)- Signature algorithms other than
ES256(18013-5 12.3.6.3) - MAC protected status list tokens (§ 11.6)
- The
SUSPENDEDstatus type (§ 7.1, 18013-5 12.3.6.1) - Application-specific and other registered status types (§ 7.1, § 14.5)
- Reactivating a revoked credential (§ 7.1)
- The optional
certificateelement in the credential's status reference (18013-5 12.3.6.2) - The identifier list mechanism (18013-5 12.3.6.4)
- Pseudo-random or non-sequential index allocation (§ 13.2)
- Batches of single-use credentials to reduce linkability (§ 12.5.1)
- Historical resolution with a
timequery parameter (§ 8.4) - The
id-kp-oauthStatusSigningextended key usage (§ 10) - Aggregation advertised in credential issuer metadata or a VICAL (§ 9.1)
- Aggregation restricted to a single credential type (§ 9.1)
- Any credential format other than mDocs (§ 6.2, § 6.3.1)
Related
How would you rate this page?
Last updated on