Context
Today the Tamga wallet obtains a single WUA (Wallet Unit Attestation)An attestation by the wallet provider about a wallet unit and the security of its keys; in the current EU texts it is split into WIA and key attestation. valid for 30 days from the wallet providerThe organisation that offers a wallet, registers its wallet units and signs wallet and key attestations. Each wallet runs its own provider; the network does not run one, it lists them in the trusted list. (wallet.tamga.network). It shows the same WUA to every institution when receiving credentials (D-CRED-6, SPEC-PROTO-0001 §11.1). The EU gap analysis (H1) found this to be one of the largest gap clusters:
- topic 9: 22 items,
- topic 38: 15 items,
- VCR_01a/03a/07,
- WIAM_06/10.
Gaps against EU TS3 (v1.5.2) and ARF (Architecture and Reference Framework)The document set that describes roles, architecture, trust model and rules. Tamga ARF follows the structure of the EU ARF. 3.0:
- Lifetime and unlinkability. A WIA (Wallet Instance Attestation)A short-lived statement signed by the wallet provider that a wallet installation is genuine; issuers check it before issuing. must live less than 24 hours. The same WIA must not be shown to more than one institution; otherwise institutions can link the same wallet across each other.
- No key attestation. The wallet provider must state in a signed
key_attestationwhere the credentialA digital document signed by an issuer and held in the person's wallet; the person shows only the fields that are asked for. keys are stored (OpenID4VCI (OpenID for Verifiable Credential Issuance)The protocol an issuer uses to deliver a credential to a wallet. Annex D). Today the institution reads this from a claim in the WUA. - No revocation. The wallet provider must publish a status listA compressed, signed list in which each credential has one position that tells whether it is valid, suspended or revoked. for WIAs and KAs and be able to revoke a wallet unitThe complete configuration of a wallet given to a person on a specific device: the wallet application (wallet instance) together with the secure hardware that protects the keys. at the user's request (VCR_07, WURevocation_10). For this it must know which WIA belongs to which unit.
Project management approved the H1 plan (P3: this work) and asked to move on to the next items.
Decision
K1 — Wallet unit registration
On first setup the wallet registers a unit key with the wallet provider. This key is used only between the wallet and the provider and is never shown to an institution. The provider keeps a unit record:
- the fingerprint of the unit key,
- solution and version,
- registration time,
- revocation state,
- the WIA status list entries issued to the unit.
No personal data is kept. Requests about the unit are signed with the unit key.
K2 — WIA (Wallet Instance Attestation)
- Format: OpenID4VCI 1.0 Annex E (
oauth-client-attestation+jwt), TS3 §2.3.1 fields:sub,wallet_name,wallet_version,wallet_link,wallet_solution_certification_information,client_status {status, exp},cnf.jwk. - Lifetime < 24 hours (Tamga: 23 hours).
client_status.expat least 31 days ahead (Tamga: 60 days). - A new WIA for every credential transaction: a new PoP (proof of possession) key and a new, unlinkable status list entry. The per-institution reuse option is not used, so the provider does not learn how many institutions the wallet talks to.
- The provider keeps the mapping between status list entries and the unit; when the unit is revoked, all its entries are revoked.
K3 — KA (key attestation)
- Format: OpenID4VCI 1.0 Annex D (
typkey-attestation+jwt, Final Annex D.1; correction 2026-10-09: the earlier text named the draft valuekeyattestation+jwt), TS3 §2.3.2 fields:attested_keys(all credential keys in a batch),key_storage/user_authentication(ISO 18045 levels),certification,key_storage_status {status, exp}.
- Honest level: today the keys are in a software store (S-9). The KA says
key_storage: ["iso_18045_basic"]and carries no certification. The level rises with the move to secure hardware (Z1). - Revocation: one shared entry per storage type (TS3 Option 1). Software store, Secure Enclave and StrongBox each have one entry. The unit identity cannot be derived from the KA.
- Transport:
key_attestationin the header of thejwtproof. The proof is signed withattested_keys[0]; a batch is requested with a single proof. Each key appears in only one KA. A KA is used once.
K4 — Status lists and revocation at the user's request
- The provider publishes two Token Status Lists (WIA entries and KA storage types). It signs them with its own key, which is registered in the trust listA signed list of a country's root certificates, issuers and registered relying parties. Today trust in Tamga rests on these lists; a shared ledger comes later.. The WIA list has at least 10,000 entries.
- The user can choose "Revoke this wallet" in the wallet (handing over or selling the device). The unit and all its WIA entries are revoked.
- Revocation from a lost or stolen device requires a user account (WIAM_06); left to a later step. 2026-10-12: changed by ADR-0047 K3 — no account; the wallet provider offers a revocation path without the phone (a revocation secret given at set-up).
K5 — Issuers
At the PAR (Pushed Authorization Request)An OAuth step in which the authorization request is sent to the server first, so its contents are not exposed in the browser address. and token endpoints the WIA is verified: signature, provider key in the trust list, validity period, PoP (
cnf),client_statusnot revoked.At the credential endpoint, if the proof header carries a KA, the following are verified:
- signature and provider key,
- the proof's signature with
attested_keys[0]and the nonceA random value used once; the verifier sends it and the wallet signs it, so an old presentation cannot be replayed., key_storage_statusnot revoked,- the
key_storagelevel meets the institution's minimum.
Credentials are bound to
attested_keys.Metadata:
proof_types_supported.jwt.key_attestations_required {key_storage, user_authentication}(ISSU_27d).Transition: the proof format without a KA is accepted until the pilot, then removed.
The
key_storagethe institution read from WUA claims is now read from the KA.
K6 — Refresh token binding
The ADR-0023 refresh token is today also bound to the WUA sub. Because each transaction uses a new WIA key, this binding becomes the condition credential-specific DPoP (Demonstrating Proof of Possession)A way to bind an access token to a key, so a stolen token cannot be used without that key. key + a valid, unrevoked WIA. AR2's rule "the wallet attestation is verified on every refresh" still applies.
Options considered
| Option | Result | Why |
|---|---|---|
| A single 30-day WUA | rejected | Not TS3-compliant; linkable across institutions; no revocation |
| WIA entry reused per institution | rejected | The provider learns how many institutions the wallet talks to and how often |
| A separate status list entry per KA (Option 2) | later | For key-store revocation at the user's request; together with the hardware key (Z1) |
| A new WIA per transaction + one KA entry per storage type | accepted | Least information; the most privacy-friendly option TS3 allows |
Invariants
| Code | Rule |
|---|---|
| WIA1 | A WIA lives less than 24 hours; every credential transaction uses a WIA with a new PoP key and a new status list entry. |
| WIA2 | The wallet provider keeps no personal data in the unit record; when a unit is revoked, all WIA entries issued to it are revoked. |
| WIA3 | The key storage level in the KA states the truth; an unverified claim is not written into a KA. |
| WIA4 | An issuer does not issue a credential against a revoked WIA or KA. |
Consequences
apps/wallet-provider:- unit registration,
/wia,/ka,/units/revoke,/units/delete, - two status lists,
- a persistent state file.
- unit registration,
@tamga-network/trust(re-exported by@tamga-network/issuer): WIA and KA verification, revocation checks. The institution issuer and the identity service use this format.wallet-core: unit key, per-transaction WIA, KA request, proof with KA. Wallet: registration, "Revoke this wallet".- SPEC-PROTO-0001 §11.1 and D-CRED-6 are written according to this decision.
- ARF: topics 9, 38 and VCR_01a/03a/07 are largely met. WSCD and device attestation are in Z1.
Implementation notes (2026-10-04)
These notes do not change the decision; they record how the reference wallet (Tamga Wallet) and the provider implement K1–K3.
- Key access policy (WL1/WL11). Hardware keys are bound to the phone lock: a key is accessible only while the device is unlocked, and each use is authorised by the device biometrics or, failing that, the device passcode. iOS: Secure Enclave,
kSecAttrAccessibleWhenUnlockedThisDeviceOnly,.privateKeyUsage+.biometryCurrentSet | .or | .devicePasscode(only.devicePasscodewhen no biometrics are enrolled). Android: StrongBox/TEE,setUserAuthenticationRequired(true),setUserAuthenticationParameters(60 s, AUTH_BIOMETRIC_STRONG | AUTH_DEVICE_CREDENTIAL),setUnlockedDeviceRequired(true),setInvalidatedByBiometricEnrollment(true)(chosen astruebecause neither this record nor SPEC-WALLET-0001 defines the flag; the system does not apply it to timeout-based keys, and removing the screen lock invalidates the key). The app PIN remains the screen lock of the app; the presentation approval is the key-use prompt (a single prompt; no second PIN prompt). No key is created on a phone without a screen lock. Protocol keys that do not represent the person — the unit key (K1), WIA PoP keys (K2), DPoP keys and the access-pass key (WL13: no approval) — are accessible only while the device is unlocked but their use needs no prompt, so silent refresh and pass renewal never prompt. Flows the person did not start try credential keys without a prompt; when authentication is required they skip silently and retry on the next user action. There is no migration (ADR-0029): existing test wallets are set up again when the policy changes. - Play Integrity — not mandatory. The Android wallet may send a Play Integrity (standard API) token alongside the key attestation; when a service account is configured, the provider has Google decode it and stores only the verdict classes in the unit's device record. The
key_storagelevel in the KA comes from the Android key attestation; Play Integrity does not lower it, its absence does not block registration, and verification is skipped without a service account. Making Play Integrity mandatory (tying registration or the level to it) changes K1/K3 and requires a separate ADR.
Implementation notes (2026-10-13, first EU alignment review)
These notes do not change the decision; they align the format with the texts the EU has fixed (Implementing Regulation (EU) 2024/2979 Annex Ib, as amended by 2026/1731; EU TS3 1.5.2).
- Generic client attestation (draft -07). The WIA has the format of draft -07 of OAuth attestation-based client authentication, which OpenID4VCI 1.0 references. The wallet provider sends
issandiat(isswas required in -07 and dropped in -08;iatbecame required in -12). The verifying side acceptsissbut does not require it; it tolerates a missingiatin the attestation, whileiatis required in the PoP (OAuth-Client-Attestation-PoP). The issuer verifies everyoauth-client-attestation+jwtattestation through one path as a WIA; the legacy Tamga WUA path has been removed. If the attestation carriesclient_status(a status entry) it is checked; if not, the behaviour is the issuer'sclientStatussetting:optional(the default; the EU's generic -07 attestation is accepted and marked as not subject to a status check) orrequired(an attestation without a status entry is rejected). The identity service, which revokes in a chain, usesrequired(ADR-0047 K1). Implementation: release 0.5.2 of the packages. - WIA
cnf= the credential's own DPoP key (TS3 1.5.2). In a credential transaction the WIA'scnf.jwkis the DPoP key used at the token endpoint for that credential; no separate WIA PoP key is generated. The refresh token binding in K6 is made through the same key. WIA1 (a new key and a new status entry in every transaction) does not change: the DPoP key is also specific to the credential and the transaction. Implementation: 0.6.0. Correction (2026-10-13, during implementation): this rule was added in version 1.5.1 of TS3 and rolled back in 1.5.2 (TS3 1.5.2 version history: "rolled back the WIAcnf/DPoP requirements added in 1.5.1 (Section 2.2.1.1)"). Neither today's EU text nor Implementing Regulation (EU) 2026/1731 Annex Ib requires a link between the WIAcnfkey and the DPoP key (TR-WIA-4.3 only requires the PoP to verify under thecnfkey). The note is therefore not implemented in 0.6.0; if the EU text asks for it again it is taken up separately. The current behaviour (separate WIA PoP and DPoP keys, both specific to the transaction) does not change. - Size of the status lists. The WIA and KA status lists each have at least 10,000 entries (Implementing Regulation (EU) 2024/2979 Annex Ib; for unlinkability; the KA list carries the same lower bound even though it uses few entries per type). An issuer rejects a WIA or KA whose list has a valid signature but fewer than 10,000 entries, as a non-compliant list (not a temporary failure). Implementation: release 0.5.2 of the packages.
Status
Accepted — 2026-09-29. Approved by project management (H1 plan, P3). DECISIONS: D-CRED-7.
Change (2026-10-06, ADR-0042): the wallet provider is run by the organisation that offers the wallet; the network runs no wallet provider and lists them in the trusted list (
wallet_providers[]).wallet.tamga.networkin the Context andapps/wallet-providerin the Consequences are Tamga Wallet's wallet provider: its code moved to the wallet's repository, and the copy in this repository andwallet.tamga.networkwere removed from the network on 2026-10-06; the provider is operated by the wallet's operator atprovider.tamgawallet.com. The decision (K1–K3, WIA1–WIA4) does not change: the WIA and KA format and their verification (@tamga-network/trust) are network rules and are the same for every wallet provider.Note (2026-10-13): generic client attestation (-07;
issaccepted but not required, a missingiatin the attestation tolerated, required in the PoP), removal of the legacy WUA path and theclientStatussetting (optional/required; the identity service usesrequired), WIAcnf= the credential's own DPoP key (rolled back in TS3 1.5.2 — not implemented, see the correction above), WIA/KA lists ≥ 10,000 — see "Implementation notes (2026-10-13)" above. Approved by project management (first EU alignment review).Note (2026-10-14, K2 period wording): "
client_status.exp… (Tamga: 60 days)" in K2 is only the default period (when the issuer states no preference). When the issuer states the preference of ADR-0047 K1 (preferred_client_status_period, for the KApreferred_key_storage_status_period), the provider setsclient_status.exp(andkey_storage_status.expin the KA) to that period, up to the provider's own maximum (Tamga Wallet: 730 days). The 31-day minimum and the rest of the decision do not change.