Skip to content
SPEC-CRED-0001SpecificationIn forceversion 1.0.016 November 2026

This specification summarises the format in which Tamga credentials travel and the protocols used to issue and present them. It is the starting point for every developer joining the network.

When to read

In brief. A Tamga credential is primarily an SD-JWT VC (Selective Disclosure JWT Verifiable Credential)The JSON-based credential format with selective disclosure, used for online presentation in the EUDI Wallet and in Tamga.; the identity credential is also issued as an mdocThe ISO/IEC 18013-5 mobile document format, encoded in CBOR; used for in-person presentation and for the mobile driving licence. (ISO 18013-5). The credential travels from the institution to the wallet with OpenID4VCI (OpenID for Verifiable Credential Issuance)The protocol an issuer uses to deliver a credential to a wallet. and from the wallet to the verifier with OpenID4VP (OpenID for Verifiable Presentations)The protocol a verifier uses to request a credential from a wallet and receive the presentation.; the signature is ES256. Every credential is bound to a key on the person's device, so a credential copied to another device cannot be used. The credential and its content live only in the wallet; the network publishes only the institutions' authorisation and the revocation status.


Scope ​

This specification defines the carrier format and the protocols of 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. in the trust layer. SPEC-BC-0001 answers "what is on the chain" (issuerThe institution that signs and issues credentials: a university, a professional body, a public institution or a company./status registry); this document answers "what does the credential in the wallet look like and how does it flow".

Invariant principle (PM-TRUST-0001): the credential and its content are kept in the wallet and are never written to the chain. The chain holds only the issuer's authorisation (registry) and the revocation status (status list pointer).

The decisions are fixed by ADR-0006. This is the formal counterpart of the trust framework working note (Part K).


1. Format decisions ​

TopicDecisionRationale
Credential format (primary)SD-JWT VCSelective disclosure built in, main EUDI ARF format, plenty of libraries, markedly simpler than JSON-LD
Credential format (secondary)mdoc / ISO 18013-5 — active for the identity attestation (D-CRED-5, ADR-0013); planned for other typesSafari/iOS Digital Credentials API supports only mdoc; ARF PID precedent; in-person/offline presentation (BLE, state stage)
Issuance protocolOpenID4VCIDe facto standard; fits the institution's existing OIDC infrastructure
Presentation protocolOpenID4VPSame ecosystem, easy verifier integration
Signature algorithmES256 (P-256)Universal support in mobile secure elements and HSMs
Holder bindingcnf + device key — mandatory§3; the only fix for the holder binding gap
RevocationToken Status List (bitstring)Same as SPEC-BC-0001 §5; list off-chain, pointer on-chain
Anti-correlationBatch issuance (single-use copies) — in operation: packages of 10 copies, automatic refresh (ADR-0023, ADR-0059)The same copy is not shown to two verifiers

The did:tamga pseudonymA stable account identifier the wallet derives separately for each website; two sites cannot link the same person. profile (SPEC-ID-0001) and the X.509 issuer identity (SPEC-ID-0002) are embedded in these formats (issuer = X.509; holderThe person who keeps a credential in their wallet and decides whom to show it to. = pseudonym key).


2. SD-JWT VC structure ​

An SD-JWT VC has three parts:

<Issuer-signed JWT> ~ <Disclosure 1> ~ <Disclosure 2> ~ ... ~ <Key Binding JWT>
  • Issuer-signed JWT: the core, signed by the issuer with ES256. iss = the issuer identifier (resolves to the X.509 issuerId, SPEC-ID-0002); claims that can be revealed with selective disclosureShowing only the fields a verifier asks for from a credential, and nothing else. are embedded as salted hashesA hash computed over a value together with a random salt, so the value cannot be guessed from the hash; SD-JWT hides fields this way. (the _sd array).
  • Disclosures: each disclosureIn SD-JWT, one field value packed with a random salt; the holder hands over only the disclosures the verifier needs. is [salt, claim_name, value] — the holder attaches only the ones it wants to present; the rest stay hidden without breaking the issuer signature.
  • Key Binding JWT (KB-JWT (Key Binding JWT)A short token the wallet signs with the credential's key at presentation time, proving the holder has the key.): the presentation-specific part signed by the holder with the device key (§3).

Mandatory issuer claims: iss, iat, vct (credential type), cnf (holder public key), status (Token Status List pointer). exp depends on the credential type (short TTL for a student certificate, long for a diploma). nbf (start of validity) is written by the issuer library by default equal to the issuance time (iat); for a future-dated credential (a ticket, a student certificate for a term not yet started) it is the start time. A credential whose start has not come is stored in the wallet as "not yet valid" and is not presented; the verifier rejects it at A7 (ARF 3.0 §4.6.6 "Issued").

Data minimisation: identifiers such as the national ID number (TCKN) are included only when mandatory, and then as a selectively disclosable claim; the verifierThe party that checks a presented credential: signature, issuer in the trust list, status and policy. Also called relying party. policy (PM-ASSUR-0001) can put them on its "not requested" list.


3. Holder binding — mandatory (critical security decision) ​

The problem: "the hidden flaw in the university idea" ​

The wrong assumption: "If a student receives a credential with the university's approval, that student is a real person." This is incomplete. The university confirms that the student exists; it does not confirm that the wallet belongs to that student. Attacks:

  • A student has the certificate collected into a friend's wallet.
  • From an account whose student-portal password was stolen, the credential is written into someone else's wallet.
  • One person collects the same credential into several wallets and sells them.

In that case the system silently lies — worse than failing openly. In the literature this is the holder bindingTying a credential to a key that only the holder's device has, so a copied credential cannot be presented. problem, and it is the one real security gap that could sink a pilot.

The fix: cnf key binding — mandatory without exception ​

At issuance every credential is bound to the holder's device key: the holder's public key is embedded in the issuer-signed JWT as the cnf (confirmation) field. At presentation the holder signs a KB-JWT containing the verifier's nonceA random value used once; the verifier sends it and the wallet signs it, so an old presentation cannot be replayed. with that private key. The verifier:

  1. Verifies the issuer signature (was the issuer acceptable at the credential's iat → SPEC-BC-0001isCredentialAcceptable; isValidIssuer is the issuance-time question).
  2. Verifies that the key in cnf signed the KB-JWT → the party presenting the credential controls the private key bound at issuance.
  3. Verifies nonce + audience + iat freshness (replay protection).

The key is generated in the device's secure element (Secure Enclave/StrongBox) and can never be exported → the credential cannot be transferred.

What cnf does not prove (scope limit) ​

This distinction is critical and easily overstated. cnf + KB-JWT proves:

The holder at presentation = the holder at issuance (the same key is under control).

It does not prove:

The human in front of you is the person named in the credential.

cnf binds to a device key, not to a human. If the holder hands the device and PIN to someone else, that person presents a credential with a valid signature and valid key binding; no step of the verification chain fails.

So cnf closes the first two of the three attacks above (the credential being written into the wrong wallet from the start) and transferability; it does not close voluntary device sharing.

What solves identity matching: combined presentation — in the same OpenID4VP request the credential and the state identity credential (PID (Person Identification Data)The core identity data a state issues at the highest assurance level. Tamga does not take this role; its identity credential is not a PID.) are presented together, bound to the same cnf key; the PID carries the identity. In In the initial stage there is no PID, so identity matching is procedural (the verifier compares family_name/given_name/ birth_date against an identity document seen separately). This is the same level of strength as what is done with paper documents today — not a regression but a deferred improvement. Detail: SPEC-SCHEMA-0002 §1.2.

Holder binding in the issuance flow (effect on assurance) ​

MethodHowHolder level produced (PM-ASSUR-0001)
Remote bindingThe student logs in to the student portal → the wallet public key is proven to the issuer via OIDC/OpenID4VCI → cnf is boundT1/T2 (as strong as the portal's security; improves with 2FA)
In-person bindingAt the institution's desk an officer sees the physical ID → scans the QR in the wallet → bindingT2/T3 (institution = Registration Authority)

4. Wallet attestations: WIA and KA ​

The wallet itself carries proof as well. Sooner or later the issuer asks: "Is this a genuine wallet of a wallet provider registered on the trust list, or a fake client somebody wrote; and where is the credential key kept?" Two separate attestations answer this (ADR-0025; detailed rules in FW-POL-0002):

  • Wallet Instance Attestation (WIA (Wallet Instance Attestation)A short-lived statement signed by the wallet provider that a wallet installation is genuine; issuers check it before issuing.): the short-lived proof with which the wallet application introduces itself to the issuer. Its lifetime is under 24 hours; for every issuance it is issued with a new proof-of-possession (PoP) key and a new, unlinkable status list entry (WIA1), so the provider does not learn how many institutions the wallet deals with.
  • Key attestation (KA): states in which store (software, Secure Enclave, StrongBox) and with which user authentication the credential keys are held; credentials are bound to the KA's attested_keys. The level rests on a verified state; an unverified claim is never written into a KA.
  • Both attestations are signed by the wallet provider of the organisation offering the wallet; the provider's signing key is registered on the trust list (lotl.wallet_providers[]). The network does not operate a wallet provider; it lists them (ADR-0042).
  • The attestations feed the "authenticator strength" dimension of holder assurance (PM-ASSUR-0001): software key → low; hardware + PIN → high.

Implemented profile (ADR-0025):

FieldValue
WIA formatJWT, typ: oauth-client-attestation+jwt (OpenID4VCI 1.0 Annex E), alg: ES256, x5c = wallet provider certificate; fields sub, wallet_name, wallet_version, wallet_link, wallet_solution_certification_information, client_status {status, exp}, cnf.jwk
WIA lifetimeUnder 24 hours; client_status.exp at least 31 days ahead
KA formatJWT, typ: key-attestation+jwt (OpenID4VCI 1.0 Annex D); fields attested_keys, key_storage, user_authentication, certification, key_storage_status {status, exp}
Transport (issuance)WIA: OAuth-Client-Attestation + OAuth-Client-Attestation-PoP on the PAR and token requests; KA: key_attestation in the header of the jwt proof — SPEC-PROTO-0001 §11.1
RevocationThe provider publishes two Token Status Lists (WIA entries, KA types), each with at least 10,000 entries
Provider sideThe wallet provider of the organisation offering the wallet; the network does not operate one, it lists them (ADR-0042). Tamga Wallet's provider is run by the wallet's operator at provider.tamgawallet.com (live; on the trust list as TAMGA-WP-1, ACTIVE); it registers a wallet unit only with device evidence
PresentationWIA and KA are not sent to the verifier; they are used only during issuance

5. Revocation (delegated) ​

Credential revocationWithdrawing a credential before it expires; the issuer marks it in a status list that verifiers check. is not redefined in this specification; it is delegated to the Token Status ListA compressed, signed list in which each credential has one position that tells whether it is valid, suspended or revoked. of SPEC-BC-0001 §5:

  • The status claim in the issuer-signed JWT points to the list URI + index.
  • The list is off-chain (hosted by the issuer, signed and versioned); the chain holds only URI + hash + version + bitmap (SPEC-BC-0001 StatusList).
  • Privacy: listSize >= 100,000, random index allocation (SPEC-BC-0001).

Anti-correlation (in operation): showing the same status index to different verifiers is a tracking vector. The fix is batch issuance (single-use credential copies): the issuer issues a package of 10 copies each time, every copy bound to its own key and status list entry; the wallet refreshes a shrinking package by itself (ADR-0023, ADR-0059).


6. End-to-end flow ​

Issuance (OpenID4VCI):
  1. The holder's wallet receives the issuer's credential offer
  2. The wallet generates/selects the device key → presents the public key (cnf candidate)
  3. The issuer verifies holder binding (remote OIDC / in-person desk)
  4. The issuer signs the SD-JWT VC with ES256, embedding cnf + status index
  5. A status index is reserved (SPEC-BC-0001) — NO content is written to the chain

Presentation (OpenID4VP):
  6. The verifier sends a presentation request (nonce + audience + requested claims)
  7. The holder selects only the required disclosures + signs the KB-JWT
  8. Verifier: issuer signature + cnf/KB-JWT + status + assurance policy
     (PM-ASSUR-0001) → accept/reject

At no stage is personal data written to the chain; verification is free, done with three view calls (issuer/status/recognition, SPEC-BC-0001 §6).


7. Chain-independence constraint ​

These formats and protocols work independently of the chain: the verifier library resolves issuers through a TrustedListProvider interface and does not know whether a file (in the initial stage, a signed 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.) or a chain (from the state stage on, a registry) sits behind it. This means the pilot does not wait for Besu (see ARCH-0001, initial stage). The decision lies on the ADR-0006 + ADR-0001 line.


Security and privacy notes ​

  • Holder binding is mandatory without exception — if it is switched off, the system silently lies.
  • Key in hardware (Secure Enclave/StrongBox); a software key is not accepted (the KA states this).
  • Selective disclosure by default — only the necessary claims; data minimisation.
  • The batch issuance anti-correlation measure is in operation (ADR-0059).
  • An independent security audit before production (KB-JWT replay, disclosure liveness, WIA/KA forgery) is mandatory.

Open topics ​

  1. Schema management of the vct (credential type) registry (alignment with the SPEC-BC-0001 schema registry).
  2. Definition of the mdoc/ISO 18013-5 profile for types other than identity (planned).
  3. When to enable batch issuance — closed: in operation (ADR-0023, ADR-0059).
  4. The link of WIA/KA to device attestationA signed statement about a person or a thing that is carried in a wallet, such as a student certificate or a diploma. sources (Play Integrity / App Attest) (FW-POL-0002).

Related documents ​

  • PM-ASSUR-0001 — assurance levels (LoA (Level of Assurance)How much confidence can be placed in an identity or a credential; Tamga uses separate levels for proofing (T), issuer (I) and wallet (W).); this format carries those levels.
  • PM-TRUST-0001 — a credential is never on the chain.
  • SPEC-BC-0001 — issuer registry (source for signature verification) + Token Status List (revocation).
  • SPEC-ID-0002 — issuer X.509 identity (iss → issuerId).
  • SPEC-ID-0001 — holder pseudonym key (cnf).
  • ADR-0006 — acceptance record of these format decisions.
  • ACA-ID-0001 — DID/VC/selective disclosure mechanics (background).
  • RS-EIDAS-0001 — the place of SD-JWT VC / OpenID4VCI-VP in the EUDI ARF.

Status ​

In force — version 1.0.0 (2026-10-02).