Token Status List feature support
A feature-by-feature reference for how the MATTR Pi Holder SDKs support the IETF Token Status List specification when resolving, caching and reporting the status of a stored mDoc.
Overview
This page is a feature-by-feature reference for how the MATTR Pi Holder SDKs for iOS, Android and React Native support the IETF Token Status List specification when checking the status of a credential held in the wallet.
The specification treats a holder that resolves status as following the same rules as a relying party, so most of this page describes validation the SDK performs on the issuer's status list token. The holder side adds its own behavior around when to fetch, what to store, and what to report when the network is unavailable.
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 status checks in a holding application. If you are verifying credentials rather than holding them, see Token Status List feature support (Verifier).
Behavior described here reflects the latest iOS and Android Holder SDKs. The React Native Holder SDK wraps the native SDKs, so its behavior is whatever the underlying platform provides.
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 holder 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.
If you need clarification on any feature, contact us.
What you can configure
| You control | Fixed by the SDK |
|---|---|
Whether the SDK may go to the network, using fetchUpdatedStatusList | When a stored status is considered stale and needs refreshing |
| When you read a credential, and therefore when a check happens | That the resolved status is persisted to local storage |
| How your application responds to each status value | The rate limit applied to status list requests |
| That there is no way to force a refresh independently of reading a credential |
Status list resolution
| Feature | Spec | Status | Notes |
|---|---|---|---|
| Resolving the status list over HTTP GET | § 8.1 | Supported | The token is fetched from the uri in the credential's status reference. |
| HTTPS-only status list URIs | § 11 | Supported | A uri with any other scheme is rejected without a request being made. |
Accept request header | § 8.1 | Partial | The iOS SDK sends 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. |
| 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. |
| Fetching only when the stored status is stale | § 8.3, § 13.7 | Supported | No request is made while the stored status is still within its refresh window. |
| Retries | n/a | Supported | Up to three attempts, roughly a second apart. |
| Rate limiting | n/a | Supported | Requests to fetch updated status lists are limited to five per second per document type. |
Historical resolution with a time query parameter | § 8.4 | Not supported | Never requested. |
Status list token validation
| Feature | Spec | Status | Notes |
|---|---|---|---|
| COSE signature and certificate chain validation | § 8.3, § 11.3 | Supported | The token is verified against the stored trusted issuer certificate for the credential. |
typ protected header | § 5.2 | Supported | Required. Both application/statuslist+cwt and the earlier MATTR type are accepted, so credentials issued before Draft 14 continue to resolve. |
| Signing certificate expiry and not-yet-valid checks | § 11.3 | Supported | Reported as StatusListExpired and StatusListNotYetValid. |
| Checking the signer against a certificate revocation list | § 11.3 | Not supported | The SDK does not fetch or process CRLs. |
sub must equal the credential's uri | § 8.3 | Supported | Reported as StatusListInvalid. |
exp expiry check | § 8.3 | Supported | Reported as StatusListExpired. |
nbf not-before check | § 5.2 | Supported | Honored when present, though the specification does not define it for status list tokens. |
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 beyond exp and ttl. |
ttl claim, read from key 65534 | § 5.2 | Supported | The earlier negative claim key is also read, for credentials issued before Draft 14. |
status_list claim, read from key 65533 | § 5.2 | Supported | The earlier negative claim key is also read. |
bits values 1, 2, 4 and 8 | § 4.3 | Supported | Every size the specification permits is accepted. |
aggregation_uri inside the status list | § 4.3, § 9.2 | Not supported | Not parsed. |
Decompressing lst | § 8.3 | Supported | DEFLATE in ZLIB format. |
| Status bit extraction | § 4.1 | Supported | Values are read least significant bit first within each byte. |
| Index out of bounds | § 8.3 | Supported | Reported as a corrupted status list, and the status becomes unknown. |
Referenced token
| Feature | Spec | Status | Notes |
|---|---|---|---|
status element in the MSO | § 6.3.2, 18013-5 12.3.6.2 | Supported | |
Earlier _status element in the MSO | n/a | Supported | Read so that credentials issued before Draft 14 keep working. |
status_list with uri and idx | § 6.3, 18013-5 12.3.6.5 | Supported | |
| Credential with no status reference | n/a | Supported | Reported as not supported rather than raising an error, because the credential was issued without revocation. |
Optional certificate element in the status reference | 18013-5 12.3.6.2 | Not supported | Not read. The status list must be verifiable with the credential's own trusted issuer certificate. |
identifier_list element in the MSO | 18013-5 12.3.6.4 | Not supported | application/identifierlist+cwt is not parsed. See Upcoming standards. |
status claim in a JOSE referenced token | § 6.2 | Not supported |
Status values
| Feature | Spec | Status | Notes |
|---|---|---|---|
Valid, from 0x00 | § 7.1 | Supported | Carries the next update time, so the SDK knows when to refresh. |
Invalid, from 0x01 | § 7.1 | Supported | Revocation is permanent, so no next update time is set and no further fetch is made. |
Suspended, from 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 or fails validation. |
| Not supported | n/a | Supported | Returned when the credential has no status reference. |
| Not checked | n/a | Supported | Returned when no status check has been performed yet. |
| Application-specific status types | § 7.1 | Not supported | Any unrecognized value is reported as a corrupted status list rather than being guessed at. |
Caching, refresh and offline behavior
| Feature | Spec | Status | Notes |
|---|---|---|---|
| Next update time | § 8.3, § 13.7 | Supported | The earlier of exp and the retrieval time plus ttl. The specification describes both strategies in § 13.7, and the SDK refreshes relative to when it retrieved the token. |
| Skipping the fetch while the stored status is fresh | § 13.7 | Supported | A check performed before the next update time reuses the stored status. |
| Persisting the resolved status | § 13.7 | Supported | Stored in local credential metadata along with its expiry and refresh times. |
| Falling back to the stored status when a fetch fails | § 13.7 | Supported | If the stored status has not expired it is returned, so a temporary network failure does not make a credential unknown. |
| Reporting unknown once the stored status expires | § 8.3 | Supported | |
| Working entirely from stored state | n/a | Supported | Pass fetchUpdatedStatusList as false to skip the network. The stored status is returned if it has not expired, and unknown otherwise. |
Prioritizing exp and ttl over HTTP cache headers | § 8.2 | Supported | |
| Forcing a refresh | n/a | Not supported | There is no holder equivalent of the Verifier SDK refresh method. A refresh happens only as part of reading a credential whose stored status is stale. |
Status list aggregation
A holder resolves the status of its own credentials, so it never needs the issuer's full set of status lists.
| Feature | Spec | Status | Notes |
|---|---|---|---|
| Fetching from an aggregation endpoint | § 9 | Not applicable | Each credential's status list is resolved from its own uri. |
| Discovering an aggregation endpoint | § 9.1 | Not applicable | |
aggregation_uri claim | § 9.2 | Not supported | Not parsed. |
| Bulk pre-fetching status lists | § 9 | Not supported | This is a Verifier SDK capability, used to support offline verification. |
Failure reporting
When a status check cannot produce an answer, the status is reported as unknown together with a failure reason.
| Failure | Meaning |
|---|---|
FailedToFetchStatusList | The status list token could not be retrieved, for example because the device is offline. |
StatusListInvalid | The token was structurally valid but failed a check, for example a sub that does not match the credential, or a URI that is not HTTPS. |
StatusListCorrupted | The token could not be decoded, the compressed list could not be read, the index was out of bounds, or the status value was not recognized. |
StatusListExpired | The token or its signing certificate has expired. |
StatusListNotYetValid | The token or its signing certificate is not yet valid. |
UnknownError | Any other failure. |
The iOS SDK reports failures through an equivalent error type carrying a type string and a message, rather than the Android enumeration above. Treat the set of reasons as informational for logging and user messaging, not as a stable cross-platform contract.
Credential formats
| Format | Spec | Status | Notes |
|---|---|---|---|
ISO mdoc / mDL (mso_mdoc) | § 6.3.2, 18013-5 12.3.6 | Supported | The only format the Holder SDKs check status for. |
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 | |
| 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 holder side:
- Status list tokens in JWT format (§ 5.1)
- Historical resolution with a
timequery parameter (§ 8.4) - An independent
iatfreshness policy (§ 8.3) aggregation_uriand status list aggregation (§ 9, § 9.2)- The optional
certificateelement in the credential's status reference (18013-5 12.3.6.2) - Checking the status list signer against a certificate revocation list (§ 11.3)
- Application-specific status types (§ 7.1)
- Forcing a status refresh independently of reading a credential (n/a)
- The identifier list mechanism (18013-5 12.3.6.4)
- Any credential format other than mDocs (§ 6.2)
Related
How would you rate this page?
Last updated on