Token Status List feature support
A feature-by-feature reference for how MATTR VII and the Verifier Mobile SDKs support the IETF Token Status List specification when checking whether a presented mDoc has been revoked.
Overview
This page is a feature-by-feature reference for how MATTR supports the IETF Token Status List specification when acting as a relying party that checks the status of a presented mDoc.
It covers the whole verifier surface, because the work is split:
- MATTR VII resolves and validates the status list on every remote presentation, and on the mDoc verify endpoint. Status checking is always on and cannot be disabled.
- The Verifier Mobile SDKs for iOS, Android and React Native resolve status on the device for in-person verification, including while offline. They expose an opt-out and can pre-fetch status lists in bulk.
- The Verifier Web SDK is not involved. It starts sessions, and the status check happens inside MATTR VII.
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.
It complements mDocs revocation status checks, which shows how to implement the check in an in-person verifier application. If you are publishing status rather than checking it, see Token Status List feature support (Issuer).
There is no remote equivalent of the in-person guide
Remote verification resolves status inside MATTR VII, with no configuration to change and no status-checking code for you to write. Everything a remote integration needs to know is on this page.
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 verifier 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.
This page covers two independent implementations. Where their behavior differs, the note names the surface it applies to.
If you need clarification on any feature, contact us.
What you can configure
| You control | Fixed by MATTR |
|---|---|
Whether an in-person verification checks status, using checkStatus | That remote verification always checks status |
| When to pre-fetch and refresh the offline cache on a mobile verifier | The status list fetch timeout on remote presentations |
| Which issuer certificates you trust, and therefore which status lists are pre-fetched | The cache ceiling applied on remote presentations |
| How your application responds to revoked, suspended and unknown outcomes | That the resolved status object is removed from the verification response |
| Which status list formats and token types are accepted |
Status list resolution
| Feature | Spec | Status | Notes |
|---|---|---|---|
| Resolving the status list over HTTP GET | § 8.1, § 8.3 | Supported | The token is fetched from the uri in the credential's status reference. |
Accept request header | § 8.1 | Partial | MATTR VII and the iOS SDK send an explicit Accept header for the CWT media type. The Android SDK sends none, which § 8.1 permits when the format is known out of band. |
Response Content-Type enforcement | § 8.2 | Supported | MATTR VII requires the response to be exactly application/statuslist+cwt and rejects anything else. |
| Status list token in CWT format | § 5.2 | Supported | |
| Status list token in JWT format | § 5.1 | Not supported | application/statuslist+jwt is not parsed on either surface. |
| HTTPS-only status list URIs | § 11 | Supported | A non-HTTPS uri is rejected without a request being made. |
Non-200 responses | § 8.2 | Supported | Treated as a failure to resolve, which makes the status unknown. |
Historical resolution with a time query parameter | § 8.4 | Not supported | Never requested. |
| Fetch timeout | n/a | Supported | Ten seconds by default on MATTR VII. |
| Retries | n/a | Supported | The Mobile SDKs retry up to three times. MATTR VII does not retry within a single verification. |
Status list token validation
These rows follow the validation sequence in § 8.3. MATTR verifies the credential first, then the signature and certificate chain of the status list token, then the token's claims.
| Feature | Spec | Status | Notes |
|---|---|---|---|
| Validating the credential before its status | § 8.3 | Supported | A credential that fails verification is never given a status. |
| Reading the status reference from the MSO | § 6.3.2, 18013-5 12.3.6.2 | Supported | Both the current status element and the earlier _status element are read. |
| COSE signature validation | § 8.3 | Supported | Fails as StatusListInvalidSignature. |
x5chain chained to a trusted issuer | § 11.3, 18013-5 12.3.6.2 | Supported | Fails as InvalidCertificateChain. |
| Status list signer must match the credential's issuer | 18013-5 12.3.6.2 | Supported | The status list must chain to the same trusted issuer that signed the credential. A mismatch fails as StatusListUntrustedIssuer. |
Optional certificate element as a separate trust anchor | 18013-5 12.3.6.2 | Not supported | Not read, which is why the signer must chain to the credential's own issuer. |
id-kp-oauthStatusSigning extended key usage | § 10, 18013-5 12.3.6.3 | Not supported | Not required and not checked. ISO recommends that readers support it, but the specification has not yet been assigned an object identifier for this key purpose. |
| Checking the signer against a certificate revocation list | § 11.3 | Not supported | Neither surface fetches or processes CRLs. |
typ protected header | § 5.2 | Supported | Required. Both application/statuslist+cwt and the earlier MATTR type are accepted, so previously issued credentials continue to verify. |
sub must equal the credential's uri | § 8.3 | Supported | |
exp expiry check | § 8.3 | Supported | Fails as StatusListExpired. |
nbf not-before check | § 5.2 | Supported | Fails as StatusListNotYetValid. The specification does not define nbf for status list tokens, but it is honored when present. |
Rejecting a token with neither exp nor ttl | 18013-5 12.3.6.3 | Supported | Stricter than the IETF specification, which only recommends both. |
iat freshness policy | § 8.3 | Not supported | No independent freshness policy is applied beyond exp and ttl. |
ttl honored for cache refresh | § 8.3, § 13.7 | Partial | The next refresh is the earlier of exp and the retrieval time plus ttl. On remote presentations a shorter ceiling is applied on top, because an online presentation already implies connectivity. |
bits values 1 and 2 | § 4.3 | Supported | |
bits values 4 and 8 | § 4.3 | Partial | Accepted by the Verifier Mobile SDKs. MATTR VII rejects them as an invalid status list, even though the specification permits them. |
Rejecting an empty lst | § 4.3 | Supported | |
Decompressing lst | § 8.3 | Supported | DEFLATE in ZLIB format. |
| Index out of bounds | § 8.3 | Supported | The credential is not given a status. |
| Unrecognized status values | § 7.1 | Supported | A value other than valid, invalid or suspended is never guessed at. MATTR VII reports it as not supported, and the Mobile SDKs report the status as unknown. |
Status outcomes
| Feature | Spec | Status | Notes |
|---|---|---|---|
VALID (0x00) | § 7.1 | Supported | |
INVALID (0x01) | § 7.1 | Supported | The credential has been revoked. |
SUSPENDED (0x02) | § 7.1 | Supported | Read and reported. Only credentials issued in the earlier two bit format can carry it. |
| Unknown | § 8.3 | Supported | Returned whenever no statement can be made, for example when the token cannot be fetched, fails validation or has expired. |
| Not supported | n/a | Supported | Returned when the credential carries no status reference, so no check is possible. |
| Application-specific status types | § 7.1 | Not supported | |
| An expired credential overrides a valid status | § 7.1, § 8.3 | Supported | Credential validation takes precedence over the status list. |
MATTR VII server-side verification
| Feature | Spec | Status | Notes |
|---|---|---|---|
| Status checking on remote presentations | n/a | Supported | Always performed. |
| Disabling the status check | n/a | Not supported | There is no request parameter to skip it. |
| Returning the resolved status object | n/a | Not supported | The status object, including the list uri and idx, is removed before the response is returned. |
| Reporting the outcome | n/a | Supported | The outcome is carried by the verification result reason, as StatusRevoked, StatusSuspended or StatusUnknown. |
| Error detail | § 8.3 | Supported | Failures are classified as FailedToFetchStatusList, InvalidCertificateChain, StatusListInvalidSignature, StatusListUntrustedIssuer, StatusListExpired, StatusListNotYetValid or StatusListInvalid. |
| Shared status list cache on remote presentations | § 13.7 | Supported | Tokens are cached briefly across presentations, with a ceiling that overrides a longer ttl. |
| Caching on the mDoc verify endpoint | § 13.7 | Partial | This endpoint resolves the token with default settings and no shared cache, so a status list is fetched per request. |
| Pre-fetching from the aggregation endpoint | § 9 | Not supported | Each token is resolved on demand from the credential's own uri. |
The resolved status is not returned to your application
MATTR VII deliberately strips the status object from the verification response, so you cannot read
the raw status value, the status list uri or the index out of the API. Branch on the verification
result reason instead. See
Handling verification results.
Verifier Mobile SDKs
| Feature | Spec | Status | Notes |
|---|---|---|---|
| Opting out of the status check | n/a | Supported | Pass checkStatus as false on a proximity presentation request. It defaults to true. |
| Bulk pre-fetching status lists | § 9 | Supported | Lists are downloaded when you add a trusted issuer certificate, and on demand when you refresh. |
| Discovering the aggregation endpoint from the issuer certificate | § 9.1 | Supported | Read from the MATTR private X.509 extension 1.3.6.1.4.1.61546.100 on each trusted IACA. |
| Discovering the aggregation endpoint from authorization server metadata | § 9.1 | Not supported | |
Discovering aggregation from an aggregation_uri claim | § 9.2 | Not supported | Not parsed. |
| Continuing after one status list fails | § 9 | Supported | A refresh reports which list URIs failed and keeps the rest. |
| Inspecting the cache | § 13.7 | Supported | The cache reports when the next update is due. |
| Forcing a refresh | n/a | Supported | |
| Fetch pacing | n/a | Supported | Requests are paced and retried to stay within the issuer's rate limit, and the Android SDK honors the x-ratelimit-reset header on a 429 response. |
Verifying offline after ttl but before exp | § 13.7 | Supported | A cached token remains usable until it expires. |
Verifying offline after exp | § 8.3 | Supported | The status becomes unknown. |
Credential formats
| Format | Spec | Status | Notes |
|---|---|---|---|
ISO mdoc / mDL (mso_mdoc) | § 6.3.2, 18013-5 12.3.6 | Supported | The only format for which Token Status List is checked. |
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 MATTR revocation lists instead. See Revocation. |
| W3C Bitstring Status List | n/a | Not supported |
Not currently supported
At a glance, the following features of the specification are not currently implemented on the verifier side:
- Status list tokens in JWT format (§ 5.1)
bitsvalues of 4 and 8 (§ 4.3)- Historical resolution with a
timequery parameter (§ 8.4) - An independent
iatfreshness policy (§ 8.3) - The optional
certificateelement as a separate trust anchor (18013-5 12.3.6.2) - Checking the status list signer against a certificate revocation list (§ 11.3)
- The
id-kp-oauthStatusSigningextended key usage (§ 10) - Application-specific status types (§ 7.1)
- Disabling the status check on remote presentations (n/a)
- Reading the resolved status object out of the verification response (n/a)
- Pre-fetching status lists on MATTR VII (§ 9)
- Aggregation discovery other than from the issuer certificate (§ 9.1, § 9.2)
- Any credential format other than mDocs (§ 6.2, § 6.3.1)
Related
How would you rate this page?
Last updated on