In brief
This document sets out the rules every wallet compatible with Tamga Network must follow internally: keys, on-device storage, device change, the consent screen and credential copies. It is written for wallet developers; Tamga Wallet (a separate repository) is the reference implementation of these rules.
When to read
- First read the Privacy and Presentation concept pages.
- When you move to code, GUIDE-0005 shows how to meet these rules with
@tamga-network/wallet-core. - The protocols the wallet uses to talk to the institution and the verifier are not here: SPEC-PROTO-0001 and SPEC-PROTO-0002.
Plain explanation
The keys bound to a credential are generated in the phone's secure hardware and never leave it; so they are not backed up, and when the phone changes, the credentials are obtained again from the institution. For every share the person sees what goes to whom and approves it; a site that asks for more than it needs triggers a separate warning. The wallet keeps several copies of the same credential: it always shows the same site the same copy and different sites different copies, so sites cannot link the person across one another. "Sign in with Tamga" uses a separate pseudonym for each site. If the person wishes, they can reset the wallet and delete their data both from Tamga's services and from the phone.
Scope
The internal design of the wallet: key management, local storage, device change and migration, the consent surface, use of credential copies, the schema cache.
The protocols are in SPEC-PROTO-0001 and SPEC-PROTO-0002. The WIA (Wallet Instance Attestation)A short-lived statement signed by the wallet provider that a wallet installation is genuine; issuers check it before issuing. and the key attestationA short-lived statement by the wallet provider that a credential key was created and is kept in secure hardware. are in ADR-0025; 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. issues them.
1. The resolved tension — can the key be backed up?
This section is the most important part of the document because two existing design decisions contradicted each other.
1.1 The contradiction
SPEC-CRED-0001 §3 says:
The key is generated in the device's secure element (Secure Enclave/StrongBox) and can never be exported → the credential is non-transferable.
The backup design in the project notes, on the other hand, implied:
A 24-word seed + mandatory PIN; an encrypted backup on the server (the server cannot decrypt it).
If the seed brings the wallet back in a usable state, it also brings back the holderThe person who keeps a credential in their wallet and decides whom to show it to. key. But if the holder key cannot leave the secure area, the seed cannot bring it back.
Both cannot be true at once.
1.2 Why the key cannot be derived from the seed
The tempting option is: derive the holder keys from the seed, keep them in software, recover them anywhere.
This option is rejected because it defeats holder bindingTying a credential to a key that only the holder's device has, so a copied credential cannot be presented. entirely:
| Consequence | |
|---|---|
| Seed → holder key derivable | The seed can be shared |
| The seed can be shared | The credential is transferable |
| The credential is transferable | The gap in SPEC-CRED-0001 §3 comes back |
In that document's own words: the attack "a student has their certificate issued into a friend's wallet" would be closed at issuance and reopened at recovery. A back door is more dangerous than a front door because nobody looks there.
1.3 Decision
Invariant WL1: holder keys are not derived from a seed and never leave the device's secure area.
Invariant WL2: the wallet takes no backup of credentials: credentials are bound to the hardware key on the device and do not move. On a new device re-issuance is required. The only thing the wallet carries off the device is the migration file started by the person (§7.5); the file contains no credential values, copies or keys. (Until 2026-11-12 this rule said "the backup carries the credentials and the manifest"; no such backup was ever built — ADR-0078.)
This is an accepted user-experience cost. The alternative is to lose the system's core security property.
1.3b A third path considered (review R10)
The decision was taken between two options; there is a third one, and it needs to be rejected explicitly: platform-synced keys (iCloud Keychain / Google Password Manager style key classes, hardware-backed but portable across devices).
| Assessment | |
|---|---|
| Pro | No re-issuance on a device change; the best user experience |
| Con 1 | Trust moves from Tamga to Apple/Google — they decide where the key goes |
| Con 2 | Another device on the same account receives the key → the "credential is non-transferable" principle (WL1) is broken at account level |
| Con 3 | The EUDI ARF does not count this class as W3 (certified WSCD); state-stage alignment with the state is at risk |
Rejected. In the expansion stage it may be reconsidered as an optional "easy recovery" mode for level W2 — if the user knowingly chooses lower assurance. For now it is not worth the product complexity.
1.4 No seed and no backup (ADR-0078)
The first design foresaw a backup encrypted with a key derived from a 24-word seed: the credentials themselves, a "manifest" (which type from which institution) and the settings. This backup was not built and is not built:
| Nothing to recover | A restored credential can be read but not presented; its key stays on the old device |
| It has a cost | A copy of the credential values exists outside the device; even encrypted, it is a leak surface |
| Something takes its place | The list of "which credentials do I need to get again" is in the migration file (§7.5) |
The wallet has no seed words and no recovery phrase the person is asked to keep. The only thing the wallet carries is the migration file, encrypted with the person's own passphrase. The seed of the site pseudonyms is a different thing: it comes from the identity service, stays in the device's secure store and does not move (§5.4, WL15).
2. Key architecture
2.1 Key types
| Key | Where | Exportable | Lifetime |
|---|---|---|---|
| Holder keys (N per issuance) | Secure Enclave / StrongBox | No | Credential lifetime |
| Wallet instance key | Secure area | No | Installation lifetime |
2.2 Wallet assurance levels
The wallet-side component of Axis A in PM-ASSUR-0001:
| Level | Key storage | Phase |
|---|---|---|
| W1 | Software (no secure area) | Not supported (except the test key for the network's own trial scenes in the sandbox list — ADR-0042 K5) |
| W2 | Device secure area (Secure Enclave / StrongBox) | Initial-stage minimum |
| W3 | Certified WSCD | The state stage |
Invariant WL3: W1 wallets are not supported (except the test key for the network's own trial scenes in the sandbox list — ADR-0042 K5). Tamga Wallet is not installed on a device without a secure area — it is refused with a clear warning to the user.
2.3 PIN
Access to the key in the secure area is conditioned on user verification; verification does not encrypt the key (the hardware does that). How the user is verified depends on where the key lives:
- On a device with a secure hardware key the credential key is bound to the phone lock: it is used only while the phone is unlocked and after the device's biometrics or device passcode. The presentation approval is this operating-system prompt (a single prompt); app settings cannot turn it off. On this path the app PIN and in-app biometrics only unlock the wallet.
- On the software-key path (an environment that cannot use secure hardware, temporary deviation S-9) the presentation approval is the app PIN or in-app biometrics.
| Rule | Value |
|---|---|
| Length (app PIN) | At least 6 digits |
| Biometrics | Next to the PIN, not instead of it (the fallback is the PIN) |
| Attempts | After the 5th wrong attempt in a row, a 30 s wait; every further wrong attempt doubles the wait (1 min, 2 min, …), up to 1 hour. The counter is persistent on the device: closing the app or setting the clock back does not shorten the wait; the correct PIN clears the counter. The wallet is never erased because of wrong attempts. There is no recovery for a forgotten PIN: the person resets the wallet themselves (confirmed with the phone's own lock) and obtains the credentials again (§7.6) |
| Presentation approval | User verification mandatory for every presentation: device biometrics or device passcode on secure hardware; PIN or biometrics on the software-key path |
| Fallback | If the operating-system prompt cannot be shown for a technical or temporary reason (no foreground window, authentication service unavailable), the app PIN is asked. If the user cancels the prompt there is no fallback: nothing is presented |
The presentation approval row matters: a presentation must be a deliberate act of the user. An unlocked wallet is prevented from presenting silently in the background. Flows the person did not start (pass refresh, copy refresh) show no prompt; if verification is needed, that round is skipped.
Lifetime of the pass grant (WL13). The pass is the only flow that does not ask for user verification at every display; this is why the consent given at registration is limited in time. The wallet does not store a grant that lasts longer than 6 months (184 days; exp − iat and exp − now). The only exception is the single-use ticket (single_use): the grant's exp is the end of the event (ADR-0012 K4) and the ticket is used up at the first passage; because the event can be more than 6 months ahead, this grant is not subject to the 6-month ceiling. The other checks on the grant (registered RP/terminal group, scope, withdrawal) apply to a single-use ticket unchanged.
3. Local storage
┌──────────────────────────────────────┐
│ Secure area (hardware) │
│ holder keys — cannot leave │
├──────────────────────────────────────┤
│ Encrypted local database │
│ credentials SD-JWT strings │
│ batch_state copy ledger │
│ verifier_map sticky mapping │
│ schema_cache Type Metadata │
│ presentation_log presentation log │
│ settings │
└──────────────────────────────────────┘Invariant WL4: the presentation_log never leaves the device automatically or to a server; it leaves the device only in an export the person starts themselves, encrypted with their own password (EU TS10, ADR-0027) — it does not enter the backup either (SPEC-PROTO-0002/PV8). If it entered the backup, it would be uploaded to the server on a device change, even if encrypted, and a behavioural profile would be centralised.
The user can view and delete this record.
4. Managing credential copies
This section closes Open question 1 of SPEC-PROTO-0001 and Open question 3 of SPEC-CRED-0002.
4.1 The sticky copy rule
Invariant WL5: a verifierThe party that checks a presented credential: signature, issuer in the trust list, status and policy. Also called relying party. is always shown the same batch copy. Different verifiers are shown different copies.
verifier_map: (verifier_id, vct) → copy_indexThe rationale works in both directions:
| Direction | Why |
|---|---|
| Same copy to the same verifier | The verifier already knows who the person is (the application is named). Showing a different copy gains no unlinkability, it only spends copies. |
| Different copy to a different verifier | If two verifiers collude, they cannot link through cnf and idx (SPEC-CRED-0003 §9.4). |
verifier_id is the verifier's permanent identity in the trust list: the domain name in its record (dns_name; ADR-0034 CI4). The x509_hashA client identifier scheme from HAIP: the identifier is the base64url SHA-256 hash of the relying party's access certificate. client identifier in the request (SPEC-PROTO-0002 §2.1) changes when the access certificate is renewed, so it is not the key of the mapping. It is used instead only for a verifier whose record cannot be resolved (an unregistered verifier), because no domain name is known for it.
When a copy counts as used: at the moment the presentation leaves the device. The wallet marks the copy persistently before sending. If the verifier receives the presentation and answers with an error, or the answer is lost on the way, the copy still belongs to that verifier; it is not given to another verifier as "unused".
Proximity and wallet to wallet: a reader has no identity that lasts across sessions (the session key is new every time). Every proximity session therefore uses a new copy.
Running out of copies must not leave the person standing at the door. Target behaviour (decided 2026-11-12; wallet core: ready (@tamga-network/wallet-core 0.8.4), app screens: pending, before the store release):
| Situation | Wallet behaviour |
|---|---|
| Few unused copies left | Refreshes in the background (for credentials with a refresh token; under WL7 and the ADR-0023 conditions) |
| No copy left, device online | Refreshes right before presenting and presents with the new copy |
| No copy left, device offline | Shows the person a warning (this presentation can be linked to the previous one); if the person accepts, reuses the last copy |
Offline reuse is never silent: the warning and the person's consent are required. Once the device is online the copies are refreshed.
In the wallet core (0.8.4). The core gives only the decision and the state; the refresh call and the warning screen are the app's job:
planProximityCopyreturns the table row before presenting (present · refresh first · reuse with a warning) and says when a background refresh is due because few copies are left;proximityCopiesgives the number of copies left, whether it is below the threshold and whether none is left.- Proximity and wallet-to-wallet presentation carry the copy state to the consent screen and to the result.
- The last copy is reused only when the app asks for it explicitly (
reuseLastCopy; the person accepted the warning). Reuse always falls on the same copy and is marked in the presentation log on the device ("reused"). - Without the option nothing changes: when no unused copy is left, nothing is presented and no copy is reused.
Today's implementation (Tamga Wallet): the warning screen and the refresh before presenting are not there yet; when no unused copy is left, nothing is presented — the person refreshes the credential (§4.3).
4.2 A consistent disclosure set
Invariant WL6: for repeated presentations of the same vct to the same verifier, the wallet uses the same disclosure set.
The reason is in the Security notes of SPEC-SCHEMA-0002: a changing set reveals which fields are being hidden. If 8 fields are disclosed in the first presentation and 6 in the second, the verifier can infer the difference.
If the verifier asks for fewer fields, the wallet does not present more — the new request itself applies, not an intersection; but the user is shown "you previously gave this verifier these fields".
Implementation note (2026-11-12). The notice about earlier sharing is not on screen yet; it comes with the wallet's first update, in a plain form: a line on the consent screen, "you have shared these with this verifier before", and emphasis on the fields requested for the first time. The wallet core provides the data for it (sharedBefore, 0.8.4): from the presentation log on the device, by the verifier's persistent identity, field names and dates only — no values. The text of the rule is unchanged.
4.3 Running out
| Copies left | Wallet behaviour |
|---|---|
| 3 | Silent — visible in settings |
| 2 | Notification to the user: "2 uses left for your student certificate" |
| 0, known verifier | The existing copy is used thanks to the sticky mapping — no problem |
| 0, new verifier | The user chooses: (a) refresh, (b) reuse an existing copy — with a linkability warning |
Invariant WL7: refresh without user action happens only under the conditions AR1–AR4 of ADR-0023. Institutional credentials that have a refresh token are refreshed at the threshold announced by the institution, with the app in the foreground and unlocked, after a random delay; for identity and contact credentials refresh is a user action (the only exception is the ZK copies in §4.5). The user can turn it off in settings.
4.4 Diploma
Under SPEC-PROTO-0001 §8.5 the diploma, like other institution credentials, is issued as 10 copies (2026-10-08; the previous decision was a single copy in the pilot). The sticky mapping applies: each verifier gets its own copy. When the copies run out the wallet has them re-signed; if the user knowingly reuses a copy, the wallet shows that this creates linkability.
4.5 ZK copies (ADR-0044)
A zero-knowledge presentation (mso_mdoc_zk, ADR-0032) does not disclose the position in the revocation list. So with ZK it is not the identity credential itself that is shown but a short-lived ZK copy issued separately by the identity service:
| Topic | Rule |
|---|---|
| Type | urn:tamga:id:ShortLivedIdentityAttestation:1 (ISO 18013-5 mdoc only; namespace tamga.id.1). Because the proof binds the type, the verifier sees that it is short-lived |
| Content | Only elements that can be proven with ZK (the identity credential's age attributes age_over_18, age_over_15; ADR-0064); no name, date of birth or national ID number |
| Validity | At most 24 hours (and never after the main credential expires); no revocation list entry (ARF VCR_01) |
| Batch | A small batch (3 copies); each copy bound to its own device key |
| Obtaining | With the refresh token that comes with the identity credential (OpenID4VCI grant_type=refresh_token, DPoP + WIA); the token is single-use, changes on every use and is opaque to the wallet |
| Refresh | The window opens 8 hours before the last copy expires; the copies are refreshed silently after a random delay (at most 6 hours); if there is no valid copy, immediately or when a ZK request arrives. The conditions of ADR-0023 K1 and the "refresh copies automatically" setting apply: with the setting off no ZK copy is obtained and no ZK presentation is made |
| Revocation | If the main credential is revoked or suspended the identity service issues no new copy (invalid_grant); the wallet deletes the binding and the copies. A copy still in the wallet expires within 24 hours at most |
| Presentation | A ZK query is answered only with a valid ZK copy; the copies of the main credential are not used for ZK. Without a copy the query is not answered and the classic option (mso_mdoc / dc+sd-jwt) is chosen (ZK5). Because ZK proofs are unlinkable, no sticky copy (WL5) is needed |
Code: @tamga-network/wallet-core refreshZkCopies, scheduleZkRefreshes, selectZkCopy; the identity service's endpoint in SPEC-PROTO-0001 §4.1.
4.6 Validity state of a credential
The wallet core computes a display state for each stored credential (credentialValidity; no network call). In order of priority:
| State | When | Presented |
|---|---|---|
revoked | Revoked in the status list or locally | no |
expired | exp has passed | no |
issuer_suspended | The issuing institution is currently suspended in the trust list (ADR-0088); the credential is not deleted, the card shows a warning; it becomes valid again when the suspension is lifted | no |
suspended | Suspended in the status list | no |
not_yet_valid | The start of validity (nbf) is in the future (ARF "Issued"); the credential is received and stored, the card shows the start date | no |
valid | — | yes |
A future-dated credential is not rejected on receipt; its mdoc copy is checked against the start time. Presentation selection (remote and proximity) does not offer a credential whose start has not come. No new credential is received from a suspended institution (C1).
5. Consent surface
5.1 Presentation consent screen
Minimum content, in this order:
- Who is asking — the verifier's name (from its 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. entry) + a registered/unregistered mark
- For what — the
purposetext (SPEC-API-0001 §4.1) - What will be shared — field-by-field list, with values
- What will not be shared — the names of the fields that stay hidden (not their values)
- Approve / Decline
The fourth item is unusual and deliberate: the user needs to see selective disclosureShowing only the fields a verifier asks for from a credential, and nothing else. working. The line "your grade average will not be shared" explains the product's value at a glance.
5.2 Over-request warning
Closes Open question 1 of SPEC-PROTO-0002.
Three levels, three different visual weights:
| Situation | Presentation |
|---|---|
| Registered + within scope | Normal screen, no warning |
| Registered + fields outside scope | Out-of-scope fields appear in the list in a separate block, in a different colour, under the heading "this verifier is not authorised to request these fields". The approve button becomes active after a 3-second delay. |
| Unregistered verifier | A separate screen that interrupts the flow: "This verifier is not registered with Tamga. We cannot verify who it is." → Continue / Cancel |
Avoiding warning fatigue: a warning appears only in a truly abnormal situation. In the normal flow there is no warning. If we put a warning on every presentation, it becomes invisible.
Invariant WL8: the over-request warning is not a line of text next to the approve button; it requires a separate visual block and a delayed button.
5.3 Repeated different queries
Security notes of SPEC-PROTO-0002: a verifier can map which credentials a user holds by sending different queries.
If more than 3 different queries within 24 hours come from the same verifier, the wallet informs the user: "This verifier asked for 4 different credentials today."
5.4 Per-site pseudonym (ADR-0031)
"Sign in with Tamga" uses a per-site pseudonym (pseudonymA stable account identifier the wallet derives separately for each website; two sites cannot link the same person.) as the account key, not a credential value (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. Topic 11).
| Step | What the wallet does |
|---|---|
| Seed | It verifies the urn:tamga:id:PseudonymSeed:1 credential, requested after the identity credential with the same access token as a separate configuration (ADR-0061) (same signer as the identity credential, the key of copy 0) and puts the seed into secure storage (Keychain / Keystore; hardware-protected in the store build). The seed does not appear in the credential list and is never offered to a DCQL query (PS3). |
| Request | A format: "tamga-pseudonym" query in DCQL (meta.mode: single / multiple). If there is no credential query, the request corresponds to a pseudonym-only sign-in (no credential). |
| Consent screen | A "Your pseudonym for this site" card: new, or used before (the value is not shown). On a multiple site the user picks one of their existing pseudonyms or a new one. A pseudonym is given only to a site registered in the trust list. |
| Derivation | After PIN/biometric approval: k = HKDF-SHA256(seed, "tamga-pseudonym-v1|" + site + "|" + index) → a P-256 key; pseudonym = the RFC 7638 thumbprint of the public key. Site = the permanent identity of the actual RP's registration (dns_name; with an intermediary, the actual RP; ADR-0017 K7); derivation from a client identifier (x509_hash) is refused (wallet-core 0.7.1). The key exists only in memory and is wiped after signing. |
| Presentation | In the vp_token, under the id of the pseudonym query, a tamga-pseudonym+jwt: the public key in the header, in the body aud = client_id, nonce, rp, plus a fresh WIA and PoP for this transaction. |
| My pseudonyms | Settings: site name, created / last used, a label the user gives (not sent to the site), delete. A deleted index is never derived again for that site; registering again opens a new index. Only the site name and the event are written to the log, never the pseudonym value. |
When the identity is verified again on a new phone, the same seed arrives → the same pseudonyms → the accounts on the sites are recognised. The migration file (§7.5) carries neither the seed nor the key (LX2).
5.4.1 Mapping to the EU pseudonym rules (ARF Topic 11, PA_01–PA_31; Topic E refinement round)
The EU's current pseudonym rules (ARF 2.8 / 3.0 Topic 11 and the "Topic E — Pseudonyms, including User authentication mechanism" refinement round) assume a WebAuthn-based method but do not mandate it (PA_22 "MAY"; the EU technical specification in PA_21 does not exist yet). Tamga meets the same rules with a signed pseudonym token inside OpenID4VP. Mapping (2026-10-21):
| EU rule | Tamga | Status |
|---|---|---|
| PA_01, PA_02 create and register a pseudonym, sign in with it | Sign-up and sign-in flow (§5.4, ADR-0031 K3) | ✅ |
| PA_03 same device and other device | The same flow by link and QR | ✅ |
| PA_04 several pseudonyms at one site | pseudonyms: multiple in the RP registration (K4); single by default | ✅ |
| PA_05, PA_06, PA_19 user alias, choice, alias never sent to the site | "My pseudonyms" (K5, PS6) | ✅ |
| PA_07–PA_09 delete, manage, list | "My pseudonyms" (K5) | ✅ |
| PA_10, PA_11 non-revoked wallet unit | A new WIA and PoP for every transaction (PS5); each WIA has its own revocation entry, so it links nothing across sites | ✅ |
| PA_12 the same person presents both a credential and the pseudonym | Same vp_token, same nonce | 🟡 no cryptographic binding (ACP_01) |
| PA_13 the pseudonym belongs to the presenter | Signature with the pseudonym key, aud + nonce | ✅ |
| PA_14, PA_30 the necessary material in secure storage | Seed in Keychain / Keystore; the key is derived in memory for each transaction | ✅ |
| PA_15, PA_16, PA_17 identity not derivable, different pseudonym per site, unlinkability | Per-site key via HKDF (PS1); the same pseudonym never goes to another site | ✅ |
| PA_18 collision probability | P-256 key, RFC 7638 thumbprint | ✅ |
| PA_20 the wallet verifies the site | Access certificate + trusted list registration (stronger than the browser check in WebAuthn) | ✅ |
| PA_21, PA_22 WebAuthn profile | tamga-pseudonym+jwt inside OpenID4VP instead of WebAuthn; the site's own passkey stays for daily sign-in | ⚠️ different method — adapted when the EU specification is published |
| PA_23 algorithms in the EU ECCG list | HMAC-SHA256, HKDF-SHA256, P-256 ECDSA | ✅ |
| PA_24–PA_26, PA_28 scope and rate limited pseudonyms | One pseudonym per site (rate 1) or free (multiple); a site cannot pick a numeric rate; the limit rests on device evidence, not on a proof | 🟡 |
| PA_27 unlinkability across sites for the same scope | The site identity is an HKDF input | ✅ |
| PA_29 nobody but the user can sign in with the pseudonym | The identity service (pseudonymKey + identity number) could in theory derive the pseudonym key; sign-in also requires a valid wallet unit attestation (WIA) | 🟡 known weakening (ADR-0031); lasting fix is derivation with a zero-knowledge proof (ZKP_04, Z5) |
| PA_31 the same pseudonyms in a new wallet | The seed is derived from the person's unchanging identity | ✅ |
| DASH_03c log | Registration (pseudonym_created) and deletion are logged; the reason for a non-completed pseudonym transaction is not; pseudonym events are not in the TS10 export | 🟡 |
Site key (2026-10-21 review, wallet-core 0.7.1): under ADR-0031 K2 the site identity is the permanent identity of the RP registration, dns_name. The wallet obtains it with stableRpKey after the checkRp approval (registration found, access certificate equal to the registered one; with an intermediary, the actual RP's, when both registrations state the relationship). When a verifier's access certificate is reissued for the same registration, client_id changes and the pseudonym does not — an end-to-end test proves it. Since 0.7.1, derivation from a client identifier (x509_hash:… or any other prefixed value) is refused (by the wallet and by the verifier). Local records keyed the old way on a device are moved once to the domain, or dropped, by the app; no migration code (ADR-0029). A site "not recognising" an account is the site's own record, not a pseudonym change: the sample site keeps accounts in memory and the sandbox is reset every night.
5.5 The issuer's sharing rule — embedded disclosure policy (ADR-0046, 2026-10-11; code 0.5.0)
An institution can require that an institution credential type is shown only to specific verifiers (ARF Topic 43). The rule arrives in the signed Credential Issuer metadata as credential_metadata.embedded_disclosure_policy (SPEC-PROTO-0001 §2.1).
- Storing (EDP_10): at issuance the wallet reads the policy from the signature-verified metadata, checks its format and stores it next to the credential. A malformed policy does not stop issuance; it is stored as "not evaluable".
- Evaluation (EDP_02/03/06): at presentation, after the registration certificate is verified, without network requests:
authorized_relying_parties→ passes if the registration certificatesub(and service identifier, if present) equals arelying_partiesitem, the access certificate subject name (RFC 4514 normalised) equals asubject_dnsitem, or an entitlement of the registration certificate equals anentitlementsitem;specific_roots_of_trust→ passes if the (issuer name, serial number) pair of a certificate in the registration or access certificate chain is listed. For intermediated requests the intermediated verifier counts:rp_idis the registration certificatesub, and the access certificate subject name (the intermediary's name) is not a match. Without a registration certificate (proximity, wallet-to-wallet) the evaluation cannot be performed and counts as failed. - Comparison details: the service identifier is the registration certificate's
service_idmember (ARF RPRC_17a; the list publisher writes the use'sservice_id, or itsscope_id); an item withoutservice_idcovers all uses of the verifier. Name comparison maps attribute types to OIDs (ETSI TS 119 472-3:ORGID= organizationIdentifier,SN= serialNumber), ignores case and extra spaces in values and ignores RDN order; all attributes must be identical. A root of trust item matches the certificate whose serial number is equal and whose issuer name equalsissuer_dn(IssuerSerial; for a self-signed root the issuer name is the subject name; there is no match on the subject name). Because names and serial numbers can be copied, only certificates whose signature chain is verified from the leaf up to that certificate and anchored in trust count: the registration certificate chain starts at the registrar key from the signed list (the self-signed root that directly signed it also counts); the access certificate chain counts only when it reaches a trusted CA fingerprint from the signed list. An item that matches only an unverified certificate gives "not evaluable" (warning, default "Don't share"), never "passed". Reference implementation:@tamga-network/wallet-corecheckDisclosurePolicy(resultpassed/failed/not_evaluable, with the reason andinfo_uri). - Consent screen (EDP_05/07): if it fails or cannot be performed, a separate warning block ("[institution] wants this credential to be shown only to institutions it allows"), a "Read the rule" link when
info_uriis present; the default button is "Don't share", "Share anyway" is delayed (§5.2 pattern). There is no hard block; the final decision is the person's.
Invariant EP2/EP3 (ADR-0046): the policy is stored at issuance and evaluated at presentation without network requests; if it does not hold, a separate warning, defaulting to not sharing.
5.6 Issuer preferences, external lists, wallet to wallet (code 0.5.0)
- The issuer's wallet attestation preferences (EU ARF WUA_05a, WUA_32): when requesting a credential the wallet reads the
key_attestations_requiredrequirement and thepreferred_*revocation maintenance period preferences in the issuer's metadata; it sends no KA that misses the requirement and asks the provider for a longer WIA or KA when the remaining maintenance period is short (SPEC-PROTO-0001). - External lists (ADR-0036; ARF ISSU_10b): the wallet can load the external lists in the LOTL (ETSI TS 119 602 LoTE and ETSI TS 119 612 TL) with their signers pinned in the LOTL; if an external list cannot be verified only that list is not loaded.
- Both revocation mechanisms (ARF VCR_10): in the verifying role (wallet to wallet) the wallet verifies the Status List and the Attestation Revocation List.
- Wallet to wallet (ARF Topic 30): the protocol is in the core (
wallet-core); which type and fields may be shown is the wallet's decision. A credential restricted by the issuer's sharing rule is not shown wallet to wallet; in proximity presentation the consent screen says the rule cannot be evaluated (ADR-0046 Consequences).
5.7 EU alignment (code 0.6.0)
- Request without a registration certificate (ADR-0026 K5; ADR-0056 K10): rejected without asking the person (
registration_missing; details SPEC-PROTO-0002 §7.5); wallet-to-wallet proximity excepted. In proximity the registration certificate comes inrequestInfo.euWrprcand is verified as in the remote flow; if it is invalid, the wallet refuses without asking the person (presentProximityregistrarKeys). - Revocation status of the registration certificate (ADR-0068 K5): if the certificate carries
status.status_list, the wallet fetches the registrar's status list (signer: the registrar key in the LOTL;fetchRegistrationStatuses), caches the verified list and uses an unexpired copy when offline. Revoked certificate → the request is invalid, no data is sent; for an issuer, no credential is requested. If the status cannot be checked:registration_status_unknownwarning. Malformedstatusorpolicy_id→ the certificate is invalid. - Wallet-to-wallet presentation offer (EU TS9 v1.1): the holder puts the fields that are on the allow-list and present in its credential into the QR's DeviceEngagement (
-1) as an offer. For a request outside the offer, or one with intent to retain, it sends no field and ends withDeviceResponse.status = 10; the answer goes out a fixed time after the request arrived (the response time does not depend on the credential). The verifier can request only offered fields. Authenticating the person before the field list is shown (STS9_13) is the wallet's job. - Log events (DASH_02, DASH_03b):
issuance_failed(issuer, type, reason code),reissued,w2w_verified(in verifier mode only the time, the credential type and the outcome — no fields or values). Retention (DASH_02a): the person can choose 30 / 90 / 180 / 365 days (no limit by default); before expired entries are deleted the wallet warns (upcomingLogDeletions), and if the person postpones, nothing is deleted (theapplyLogRetentionhook). - "Listed on Tamga Network" indicator (ADR-0049): the wallet reads its own provider record in the verified trusted list with
walletProviderListing(providerId, { solutionId, unitRevoked }); when the record and the solution areACTIVE, the list is fresh and the real network's list and the unit is not revoked, the indicator shows and a tap shows the legal name, status, fingerprint and list time. - Status lists: identity credentials have no suspension (
bits = 1); the list of the mdoc copy is the CWT representation (ADR-0048).
6. Schema cache
The implementation of ARCH-0003/CMP8.
| Rule | Value |
|---|---|
| When it is fetched | At installation and when a credential of a new type is received |
| How | In bulk — all related Type Metadata + the extends chain |
| When it is not fetched | At presentation time |
| Validity | Unlimited — vct#integrity defines the content (SPEC-SCHEMA-0001 §7.1) |
Invariant WL9: the wallet makes no request to schemas.tamga.network at presentation time. If it did, the schema server would collect "who used which credential type when".
If a type that is not in the cache is to be presented, the user is told "this credential type cannot be verified yet, an internet connection is needed" and the fetch happens with the user's approval.
7. Device change and migration
7.1 No backup
The wallet takes no backup of credentials, copies or keys; neither off the device nor to a server (WL2, ADR-0078). The wallet also keeps its data out of the operating system's device backup.
The only persistent data that can leave the device is the migration file started by the person (§7.5):
| In the migration file | Not in it |
|---|---|
| The list of credentials to obtain again (type, institution, institution address) | Credential values and copies (LX2) |
| The transaction log, if the person wants (ADR-0027) | Holder keys (WL1) |
verifier_map, the pseudonym seed (WL15) |
Why there is no verifier_map: new copies will be obtained on the new device anyway, so the old mapping is meaningless. It also records which verifiers received presentations — the same rationale as WL4.
7.2 Server side
There is none. The wallet's data is not uploaded to any server: the network operates no wallet service (ADR-0042) and the wallet provider keeps no credentials, log or migration file. The migration file goes wherever the person chooses through the share menu (ADR-0027 LX1).
7.3 Device change flow
1. On the old device: Settings → Move to a new phone → set a passphrase → migration file (§7.5)
2. Install on the new device + set a new PIN
3. Open the migration file (passphrase)
4. The list is shown:
┌──────────────────────────────────────────┐
│ 4 of your credentials must be re-issued │
│ │
│ ☑ Diploma — Example University │
│ ☑ Student certificate — Example Univ. │
│ ☐ Driving licence — (state stage) │
│ │
│ [ Request the selected ones again ] │
└──────────────────────────────────────────┘
5. An OID4VCI flow for each (SPEC-PROTO-0001)
→ new holder keys, new cnf, new idxThe user is told clearly: credentials do not move; on the new phone they are obtained again from the institutions. Hiding this is worse than hitting a failure at presentation time.
7.4 Losing the device
If the device is lost the credentials cannot be brought back; if there is a migration file, only the list of "which credentials" is at hand. The user applies again to each institution and proves their identity through the institution's own procedure (SPEC-PROTO-0001 §11 — in-person binding).
This is not a disaster: the credentials are data the institution can produce again. What is lost is access, not data.
Invariant WL10: Tamga never holds a recovery key on the user's behalf. If it did, a centre able to open every wallet would come into existence.
7.5 EU TS10 migration file
The wallet produces a migration file in the EU TS10 format (Settings → Move to a new phone):
- Content:
MigrationData, i.e. the list of credentials to obtain again (listOfCredentials: vct, institution, institution address). There are no credentials that are not bound to the device. - Encryption: JWE
PBES2-HS256+A128KW+A128GCMwith the person's password (TS10 §5). - Sharing: it goes wherever the person chooses through the share menu; it does not go to Tamga.
- In the new wallet: the person opens the file; the list links to the institution's page with "obtain again" buttons (WL2).
Credential values, copies and keys do not enter the file. The transaction log does (ADR-0027); on import the person is asked whether to restore the log. The log can also be exported on its own as an encrypted file (TS10 §4.1).
7.6 Reset the wallet and delete my data
Settings → Reset the wallet and delete my data (store rules: in-app deletion; KVKK art. 7). Order:
- Identity service — for every credential obtained from the identity service, a presentation with no claims disclosed (SD-JWT VC + KB-JWT; aud = the service, nonce = the service's
/nonce) →POST {id}/erasure. The service recognises the credential by its own signature and possession by thecnfkey; it deletes the record and its event rows, revokes all copies, and has the session and images deleted at the remote identity verification provider (SPEC-ID-0003 §9.1). - Wallet provider —
POST {wp}/units/deletesigned with the unit key: the unit is revoked (WIA bits), then the record (public key, version, device attestation data) is deleted (ADR-0025). - Device — all credentials and keys, the pseudonym seed, the log, the PIN (WL1: no recovery).
Without a network, step 3 is still done; if steps 1–2 cannot be done, the person is told and shown the e-mail route. Data held by institutions (issuer, verifier) stays with them; the route is a TS7 erasure request (History → "Ask them to delete my data").
8. Invariants
| # | Invariant |
|---|---|
| WL1 | Holder keys are not derived from a seed; they do not leave the secure area. |
| WL2 | The wallet takes no backup of credentials: credentials are bound to the hardware key on the device and do not move; after a device change credentials are issued again. The only thing the wallet carries off the device is the migration file started by the person (EU TS10); the file contains no credential values, copies or keys (ADR-0078). |
| WL3 | W1 (software-key) wallets are not supported (except the test key for the network's own trial scenes in the sandbox list — ADR-0042 K5). |
| WL4 | The presentation_log never leaves the device to a server or automatically; it leaves the device only in an export the person starts, encrypted with the person's password (TS10) (ADR-0027). |
| WL5 | Always the same batch copy to a verifier; a different copy to a different verifier. |
| WL6 | The disclosure set is consistent for the same verifier + the same vct. |
| WL7 | Refresh without user action happens only under the conditions AR1–AR4 of ADR-0023. |
| WL8 | The over-request warning requires a separate visual block + a delayed button. |
| WL9 | No request to the schema server at presentation time. |
| WL10 | Tamga does not hold a recovery key on the user's behalf. |
| WL11 | Every presentation requires user verification: on a device with a secure hardware key, the device's biometrics or device passcode (the credential key is bound to the phone lock); on the software-key path (S-9), the app PIN or biometrics. Fallback and cancellation in §2.3. |
| WL12 | The pass token (tamga-pass+jwt) carries no personal data: only iss (opaque pass_id), aud, iat (≤ now + 30 s), exp (lifetime ≤ 60 s; ≤ now + 60 s + 30 s clock-skew tolerance), jti; credential content and claims do not enter the QR code (ADR-0012). |
| WL13 | A pass is generated only for an RP/terminal group registered in the trust list, and the consent given at registration is time-limited (at most 6 months — 184 days) and scoped; the user can withdraw consent at any moment (the grant is deleted). A single-use ticket (single_use) is exempt from the 6-month ceiling: its grant ends when the event ends (exp = end of the event, ADR-0012 K4) and it is used up at the first passage. It is the only exception to WL11. |
| WL14 | Every display of a pass is written to the presentation_log (within WL4, on the device); the Show screen displays a live clock and the remaining time. |
| WL15 | Site pseudonym keys are not holder keys: they are derived only from the ADR-0031 seed per site and index, and are not stored persistently; the seed stays only in the device's secure storage and enters no backup, no migration file and no presentation. |
Security and privacy notes
Recovery is the weakest point of holder binding. The reasoning in §1.2 must be repeated: every design proposal that asks for easy recovery must pass the question "does this make the credential transferable?". If the answer is yes, it is rejected.
The sticky mapping keeps a list. verifier_map contains the verifiers to which the user has presented — it is as sensitive as the presentation_log and subject to the same rules (it stays on the device, it does not enter the migration file).
The PIN wait is a limited DoS surface. Someone who seizes the device can enter wrong PINs in a row and delay unlocking the wallet by up to 1 hour; they cannot erase the credentials. Accepted risk — the alternative is to leave it open to brute force. Erasing the wallet on wrong attempts was deliberately not chosen: it would give anyone holding the phone a way to destroy the person's credentials.
Open questions
- Re-issuance on a new device requires the institution to still recognise the person. What will the university do if a graduate changes device 10 years later? A question of institutional process → PM-GTM-0001.
- How will W3 (certified WSCD) be detected in the state stage — device attestation or separate hardware? →
SPEC-WALLET-0002 How costly is fixed-size padding of the backup?— closed (2026-11-12, ADR-0078): there is no backup.- Are multiple devices (tablet + phone) supported? Not now — every device means a separate holder key, so a separate issuance for every device. Batch issuance could partly solve this but has not been designed.
- Should
verifier_mapbe shown to the user? For transparency yes, but a list of "which employers you applied to" is also visible to whoever gets hold of the phone.
Related documents
SPEC-CRED-0001 · SPEC-CRED-0002 · SPEC-CRED-0003 · SPEC-PROTO-0001 · SPEC-PROTO-0002 · SPEC-SCHEMA-0001 · SPEC-SCHEMA-0002 · SPEC-API-0001 · ARCH-0003 · PM-ASSUR-0001 · PM-GOV-0001 · INVARIANTS
Status
In force — version 1.0.0 (2026-10-02; last updated 2026-11-12).
2026-11-12: ADR-0078 — no backup, the migration file is the only thing that moves (text of WL2; §1.3, §1.4, §2.1, §7, §8). Implementation notes: the WL6 notice about earlier sharing comes with the first update (§4.2); target behaviour when copies run out in proximity (§4.1) — the wallet-core part of both is ready in 0.8.4, the app screens are pending.