Skip to main content

Check the Wallet Before You Issue a Credential

Specifications:
  • ARF v3.0.0 §6.2.2 (the trust anchors of wallet providers in the Wallet Provider LoTE) and §6.6.2 (issuance)
  • ETSI TS 119 602 V1.1.1, Annex E (the list of wallet providers)
  • OpenID for Verifiable Credential Issuance 1.0 (key proofs and attestations), and the OAuth 2.0 attestation-based client authentication that carries the WIA
  • WE BUILD WP4 use case UC-TE-03: credential issuer evaluates the wallet unit

In short​

  • Before you issue a credential, you may want to know that the wallet is a genuine wallet unit of a wallet provider that you trust.
  • The wallet proves this with a wallet instance attestation (WIA), signed by its wallet provider, and with a key attestation for the key that the credential will be bound to.
  • With Require a trusted wallet provider on, the iGrant.io Organisation Wallet Suite issues only when a trust anchor in Accepted wallet providers trusts the signer of these attestations as a wallet provider.
  • For demos and tests, accept the NXD Trust List of wallet providers (NXD-TL-WalletProviders.xml). For production, accept the Wallet Provider LoTE of the EU.

What the issuer checks​

The checks of the issuer at issuance. The wallet unit sends a wallet instance attestation and a key attestation with its credential request. The issuer checks the WIA (signature, proof of possession, expiry, revocation) and that its signer is in an accepted wallet provider trust anchor. For the key attestation, it checks its signer against the same trust anchors, or, for an Android hardware Keystore key, against the Google Hardware Attestation Root. The results go to the issuance history.

What the issuer checks before it issues a credential, with the iGrant.io Organisation Wallet Suite as the issuer (ARF v3.0.0 §6.6.2, WE BUILD UC-TE-03).

The wallet sends a WIA, and a key attestation for its binding keys. Both carry the certificate chain of their signer in the x5c header.

A key attestation carries one of these chains:

  • The chain of a wallet provider: the wallet provider signed the key attestation (mode wallet_provider).
  • On Android, the chain of the device's hardware Keystore, up to the Google Hardware Attestation Root: the device key signed the key attestation (mode android_keystore).

The issuer refuses a key attestation that has neither chain, for example one that the attested key signed itself (KA_ROOT_UNTRUSTED).

iOS. An iOS wallet unit sends a key attestation signed by its wallet provider, because the wallet provider checked Apple App Attest when the wallet unit registered. The issuer therefore checks only the wallet provider.

Android hardware Keystore. A key attestation of this kind has no wallet provider signer, so the issuer runs a platform root check, not a trusted list check:

  • The chain must end at the Google Hardware Attestation Root.
  • No certificate of the chain may be revoked in the Google attestation status list.

If the issuer's copy of the Google attestation status list is not current, it cannot check revocation. It then refuses a required Android key attestation with 503. It accepts an optional one without a level, with the warning KA_ANDROID_STATUS_UNAVAILABLE.

Turn on the check​

In the dashboard, open the settings of a credential definition and go to the card Wallet provider trust:

  1. Turn on Require a trusted wallet provider. This also makes a WIA required.
  2. In Accepted wallet providers, select the trust anchors of the wallet providers that you accept. The list offers only trust anchors with Used As set to Wallet provider. Use one of these:
    • an ETSI LOTE of wallet providers that includes the wallet provider, or
    • a CA (X.509) that holds the root CA certificate of the wallet provider.
  3. Save.

In the API, these are requiresTrustedWalletProvider and acceptedWalletProviders of the credential definition (Update credential definition):

  • acceptedWalletProviders is an array of trust anchor IDs.
  • It is required while the switch is on (trust.accepted_list_required).
  • Every trust anchor in it must be used as wallet_provider (trust.accepted_list_wrong_role).

What the issuer refuses. With the switch on:

  • The wallet must send a valid WIA: signature, proof of possession, expiry and revocation status. Otherwise the issuer refuses the request with invalid_client.
  • A trust anchor in acceptedWalletProviders must trust the signer of each WIA, and of each key attestation signed by a wallet provider, for the role wallet provider. Otherwise the issuer refuses with invalid_client: "Client attestation refused: the wallet provider of the attestation is not trusted for this credential".
  • A key attestation stays optional, unless the credential configuration requires one.

With the switch off, the issuer runs no trust check. A WIA that the wallet sends must still pass its signature, proof of possession and expiry checks. A WIA that is revoked is recorded, and the request goes on. For development, leave the switch off. The key_storage and user_authentication levels of a key attestation still count when its certificate chain is valid now.

Trust a wallet provider on this platform: Get the root CA certificate (PEM) of the wallet provider: the CA that issued the certificate of its attestation key. A wallet provider on this platform finds it in the chain of the key in its wallet provider configuration, as the certificate marked Receivers must trust. Add it as a CA (X.509) trust anchor with Used As set to Wallet provider, select it in Accepted wallet providers, and repeat this when the wallet provider moves to a new root CA.

The wallet provider does not use trusted lists for its own wallets. When a wallet asks it for a key attestation, it accepts only a WIA that it signed itself with the current key of its configuration. After the wallet provider replaces that key, its wallets must request a new WIA.

What the issuance history records​

The issuance history keeps the result of every check, also when the issuer refused the request:

MemberContent
authorisation.walletUnitAttestation.walletProviderTrustedListCheckThe trusted list check of the wallet provider of the WIA. When the wallet provider is not trusted, the validity of the WIA records WUA_WALLET_PROVIDER_NOT_TRUSTED; the WIA itself stays valid.
authorisation.keyAttestation.walletProviderTrustedListCheckThe trusted list check of the wallet provider of the key attestation (mode wallet_provider), with KA_WALLET_PROVIDER_NOT_TRUSTED when it is not trusted
authorisation.keyAttestation.platformRootCheckThe platform root check of an Android hardware Keystore key attestation (mode android_keystore)
authorisation.keyAttestation.validityEach check of the key attestation (signature, expiry, revocation, nonce, proof key and levels), with its stable codes (KA_*)
authorisation.walletUnitAttestation.trustRequired, authorisation.keyAttestation.trustRequiredThe value of requiresTrustedWalletProvider that applied
authorisation.walletUnitAttestation.trust, authorisation.keyAttestation.trustWho makes the attestation trusted: trust_source, with anchorId, anchorName and providerName, or platform_root (Google Hardware Attestation Root), and the result in trusted. null when no check ran.

With the switch off, each walletProviderTrustedListCheck has the result not_applicable and the reason code not_required. See Read a Trust Check Result.

In the dashboard, the issuance history shows a seal for the WIA of each issuance:

  • valid
  • valid with a trust warning
  • valid, but its wallet provider is not trusted
  • not valid
  • missing

The Wallet unit attestation and Key attestation cards end with a part Trust. It has one row for who signed the attestation, with its trust chip: Wallet provider, or Hardware attestation root for an Android hardware Keystore key. Select the chip to open its trust panel, for example Trust: Wallet provider. See Read a Trust Check Result.