Skip to main content

Wallet Unit Attestation

Learn about Wallet Unit Attestation and how to set it up.

What is WUA?​

Wallet Unit Attestation, or "WUA", is a cryptographic mechanism that allows a wallet to prove they meet specific trust requirements without exposing sensitive internal details or personal data. A wallet may need to demonstrate various properties about itself, including:

  • Vendor authenticity - confirmation it was created by a certified wallet manufacturer
  • Software integrity - verification of approved versions obtained through legitimate app stores
  • Technical capabilities - support for required cryptographic standards, signature algorithms, and identity protocols
  • Hardware features - availability of secure key storage, biometric sensors, or connectivity options like Bluetooth and NFC

WUA creates trust for participants in digital identity ecosystems. Credential issuers can confidently distribute sensitive credentials knowing the receiving wallet meets their security requirements. Verifiers can trust that credential presentations come from legitimate, uncompromised wallets. Users benefit from enhanced privacy and security while maintaining interoperability across different systems and services.

Protocol​

The system implements OAuth 2.0 Attestation-Based Client Authentication. In this context, the "client" is a wallet instance, meaning a single installation of the wallet application. The protocol flow:

OAuth 2.0 Attestation-Based Client Authentication

With this protocol the wallet is able to prove it has an attestation and that it possesses the key to which that attestation is bound. If the authorization server – which could be an issuer or a verifier – trusts the Wallet Attester, then it can rely on the attestation as proof that the wallet meets whatever criteria the attester was validating. What exactly is being attested to is entirely up to the ecosystem or framework.

WUA implementation​

The system implements WUA issuance from the Procivis One Desk to the Procivis One Wallet. If WUA issuance is enabled and configured, the wallet unit requests its attestation during the wallet onboarding phase.

By default the system verifies the integrity of the app before issuing the attestation. This check can be disabled in the configuration.

Without integrity check​

Procivis One WUA without app integrity check

  1. During the initialization of the wallet, the app automatically generates a cryptographic key and a Proof of Possession (PoP) JWT.

  2. These are sent to the holder-register endpoint as a request for attestation.

  3. The system validates the PoP.

  4. If the PoP is validated, the wallet unit is marked as active and generates a WUA in the form of an attestation JWT.

  5. The system sends the WUA and the wallet stores it.

With integrity check​

When app integrity check is enabled, the system performs additional platform-specific validation to verify that each wallet app requesting an attestation is legitimate and signed by an authorized app store.

Platform-specific mechanisms​

  • iOS: App Attest
  • Android: Key attestatation

Validation process​

The system validates attestations by:

  • Verifying certificate chains against trusted platform certificate authorities
  • Confirming app bundle identifiers match the configured expected values

WUA status​

Attestations statuses:

  • ACTIVE - Valid and ready for use
  • REVOKED - Invalidated by issuer
  • PENDING - Processing in progress
  • ERROR - Failed validation or processing

Lifecycle management​

Attestation expiration times are configured by issuers in the system settings. Wallet units automatically request renewal when their current attestation approaches expiration. If the existing attestation hasn't been revoked, the system issues a new one.

Monitoring and alerts​

  • Issuers can track attestation status directly in the Desk interface
  • Wallet users can receive notifications when their attestation expires or is revoked

Configure WUA issuance​

Example configuration:

app:
  enableWalletProvider: true                    # Enable this Core instance as a wallet provider
walletProvider:
  PROCIVIS_ONE:
    type: PROCIVIS_ONE                          # Must be exactly "PROCIVIS_ONE"
    display: walletProvider.procivisOne
    params:
      private:
      public:
        walletName: "Example Wallet"            # A name for the wallet; included in the attestation
        walletLink: "https://example.com"       # A link for the wallet; included in the attestation
        android:
          bundleId: my.wallet.bundle.id         # Your Android app bundle ID
          signingCertificateFingerprints: [     # Certificate hashes for signed app releases
            "FA:C6:17:...",
            "G9:45:B1:..."
          ]
          trustedAttestationCAs: [              # Trusted Android certificate authorities
            "-----BEGIN CERTIFICATE-----\n...",
            "-----BEGIN CERTIFICATE-----\n..."
          ]
        ios:
          bundleId: my.wallet.bundle.id         # Your iOS app bundle ID
          trustedAttestationCAs: [              # Trusted iOS certificate authorities
            "-----BEGIN CERTIFICATE-----\n..."
          ]
          enforceProductionBuild: true          # Require publicly released app versions only
        lifetime:
          expirationTime: 86400                 # (seconds) Attestation validity duration
          minimumRefreshTime: 60                # (seconds) Cooldown period before requesting new attestations
        integrityCheck:
          enabled: true                         # Enable integrity verification check (default: true)
          timeout: 300                          # (seconds) Max time between register and activate calls (default: 300)