Skip to content

3.1.1 Wallet Activation

This flow describes the wallet initialization process for the initial start-up of the wallet app after installation including the wallet activation.

Design Decisions

In the Wallet Activation process, the Wallet Instance (WI) initializes security-relevant components and establishes connections to its backend services, such that it is ready for use.

The Wallet Instance (WI) and the Wallet Provider Backend (WPB) collaboratively needs to ensure the security capabilities and current state of the device it is running on with the aim to enable level of assurance high for the PID Issuance. To achieve this, the WI registers at the WPB and performs security verifications using mobile platform mechanisms to get a wallet attestation issued. Additionally, the WI is protected using a Runtime Application Self-Protection (RASP) module, that monitors the security posture of the user device and WI locally. If the security posture of the user device or WI is insufficient, the wallet activation will be aborted.

The WI fetches feature flags from the Feature Flag Service (FFS) of the Wallet Provider at start-up. Feature flags allow the Wallet Provider to change the configuration of all Wallet Instances without an app release, in particular to enforce a minimum app version, e.g. to phase out app versions with known vulnerabilities.

The processes of wallet activation additionally involve the user:

  • the user is shown the introduction screens explaining the features and functionalities of the wallet app
  • the user is required to set up the platform authenticator of the mobile operating system for device unlock, if they have not already done so
  • the user is informed about the processing of personal data in the privacy notice and is asked to accept the terms of use, before any data specific to the WI is sent to the backends of the Wallet Provider
  • the user is asked to opt in to push notifications, e.g. to be notified about a wallet revocation
  • the user is asked to set up a method to revoke the means of authentication provided with the wallet, e.g. in case if the device is lost

The WI does not register with Remote WSCA (RWSCA) within the wallet activation, but only during the initial PID issuance, as the RWSCA is only required for the PID. Moreover, it is advantageous to delay the setup of RWSCA-PIN to the PID issuance, such that users connect the RWSCA-PIN with the PID credential. In a feature-complete wallet, user's first use case may not involve the PID and thus a RWSCA-PIN may not be necessary from the start.

Initial Start-up

This section described the data flow of the initial start-up of the Wallet Instance in a sequence diagram and a more detailed table. Artifacts in italics are further explained in the data register chapter

Sequence Diagram

Initial Start-up bluesequence numbers for steps detailed in other diagramssolid line arrows represent technical functionality, dotted line arrows represent non-technical/user functionalityUserWallet Instance . App .WI.Feature Flag Service .FFS.Mobile Device Vulnerability Management .MDVM.Wallet Provider Backend .WPB.Push Notification Service .PNS.UserWallet Instance / App (WI)Feature Flag Service (FFS)Mobile Device Vulnerability Management (MDVM)Wallet Provider Backend (WPB)Push Notification Service (PNS)UserWallet Instance / App (WI)Feature Flag Service (FFS)Mobile Device Vulnerability Management (MDVM)Wallet Provider Backend (WPB)Push Notification Service (PNS)(001)open wallet(002)initialize RASP SDK(003)fetch feature flags(004)check minimum app version(005)show introduction screens(006)check platform authenticator setup(007)create wi_data_enc_symk for local data encryption(008)show privacy notice and ask user to accept terms of use(009)MDVM registration(010)WPB registration(011)introduce push notifications and ask user to opt in(012)register push notifications(013)introduce wallet revocation and ask user to store thewpb_wi_revocation_code

Detailed Description

No Description
001 The user opens/launches the Wallet Instance / App.
002 The WI initializes the RASP SDK to start local runtime self protection. This step should happen immediately after app launch to enable root detection for the whole wallet activation flow.
003 The WI fetches the feature flags from the Feature Flag Service (FFS). The request only contains a static API key that is identical for all installations of the app on a platform and environment, but no data specific to the WI or the user, and can therefore happen before the user accepted the terms of use. The WI stores the feature flags locally.
004 The WI compares its app version with the minimum_app_version provided by the feature flags. If the app version is lower, the WI blocks the wallet activation and directs the user to the app store to update the app. This ensures that outdated app versions, e.g. with known vulnerabilities, are not registered at the backends of the Wallet Provider.
005 The WI shows screens for introduction or new features to the user. These screens should only be shown once after the initial launch of the app or once following an update.
006 The WI checks that the platform authenticator of the operating system (Android/iOS) is set-up for device unlock. The check does not actually trigger the user to perform the authentication, as the user previously authenticated when unlocking the device. If the platform authenticator is not set-up, the user is directed to the settings page of the operating system. The wallet initialization only continues, once the platform authenticator is successfully set up. See Platform Authenticator for details.
007 The WI generates a new cryptographic key wi_data_enc_symk that is bound to the Platform Authenticator and is used to encrypt all local data at the Wallet Instance. See Encryption at Rest for details.
008 The WI shows a summary of the terms of use and the privacy notice to the user, both of which the user can read in full in the WI, and asks the user to accept the terms of use. The privacy notice informs the user about the processing of personal data, starting with the registration at the MDVM and the WPB in the following steps, and is therefore shown before any data specific to the WI is sent to the backends of the Wallet Provider. The privacy notice is for information only and is not accepted, as the processing is not based on consent. The wallet activation only continues once the user accepted the terms of use. The WI stores the version of the accepted terms of use locally. See Terms of Use and Privacy Notice for details.
009 The WI registers at the MDVM, proofing the security posture of the user device and the wallet app towards the Wallet Provider and establishing a persistent, hardware-backed cryptographic key pair for authentication towards the Wallet Provider. The MDVM creates an account for the WI and issues an initial token attesting the public key. See the Android flow and iOS flow of the MDVM registration for details.
010 The WI registers at the WPB using the public key and the token received from the MDVM, establishing a persistent account with the WPB. The WPB returns the wpb_wi_revocation_code for the wallet revocation set up in step 013. See Wallet Registration for details.
011 The WI asks the user to opt in to push notifications, which are used to notify about a wallet revocation, and to trigger the Wallet Instance self-locking. Push notifications are strictly opt-in, as they introduce a dependency on Google/Apple infrastructure and expose metadata to the Mobile Platform Provider (MPP). If the user declines, the WI still detects a revocation through the regular renewal of the mdvm_token, which the MDVM rejects for a revoked account (see Wallet Instance self-locking), losing only the proactive, out-of-session signal.
012 If the user opted in, the WI retrieves an mpp_registration_token from the MPP's push notification service and registers it at the Push Notification Service (PNS), see Create Account for details. The WI stores the mpp_registration_token and the timestamp of the registration locally.
013 The WI sets up the user-initiated wallet revocation: it introduces the user to the wallet revocation and asks the user to store the wpb_wi_revocation_code received in step 010, e.g. by copying it to the clipboard, exporting it in a PDF file or storing it in the password manager. The WI only lets the user proceed once the user chose at least one of these options. See Revocation Setup for details.

Subsequent Start-up

This section described the data flow of subsequent start-ups of the Wallet Instance in a sequence diagram and a more detailed table. Artifacts in italics are further explained in the data register chapter

Sequence Diagram

Subsequent Start-ups bluesequence numbers for steps detailed in other diagramssolid line arrows represent technical functionality, dotted line arrows represent non-technical/user functionalityUserWallet Instance . App .WI.Feature Flag Service .FFS.Mobile Device Vulnerability Management .MDVM.Push Notification Service .PNS.UserWallet Instance / App (WI)Feature Flag Service (FFS)Mobile Device Vulnerability Management (MDVM)Push Notification Service (PNS)UserWallet Instance / App (WI)Feature Flag Service (FFS)Mobile Device Vulnerability Management (MDVM)Push Notification Service (PNS)(001)open wallet(002)initialize RASP SDK(003)fetch feature flags, if the last fetch is older than 24 hours(004)check minimum app version(005)check platform authenticator setup(006)check local data decryption with wi_data_enc_symk(007)check version of accepted terms of use(008)show amended terms of use and ask user to accept them, if required(009)renewal of mdvm_token, if the last renewal is older than one month(010)update *mpp_registration_token*, if the last registration is older than onemonth

Detailed Description

No Description
001 The user opens/launches the Wallet Instance / App.
002 The WI initializes the RASP SDK to start local runtime self protection. This step should happen immediately after app launch to enable root detection for the whole wallet activation flow.
003 The WI checks the locally stored timestamp of the last successful fetch of the feature flags. If no feature flags are stored or the last fetch is older than 24 hours, the WI fetches the feature flags from the FFS and stores them locally.
004 The WI compares its app version with the minimum_app_version provided by the feature flags. If the app version is lower, the WI blocks further use and directs the user to the app store to update the app.
005 - 006 The WI checks that the platform authenticator of the operating system (Android/iOS) is set-up for device unlock. The check does not actually trigger the user to perform the authentication, as the user previously authenticated when unlocking the device. If the platform authenticator was reset and local data decryption with wi_data_enc_symk fails, the WI instructs the user to set-up the wallet again.
007 - 008 The WI compares the locally stored version of the accepted terms of use with the current version provided by the feature flags (terms_of_use_version). If the terms of use were amended, the WI shows the amended terms of use together with a summary of the material changes and asks the user to accept them. Before the amended terms of use come into force, the WI shows this notice only once and the user may postpone the acceptance. Once the amended terms of use are in force, the user can only continue to use the WI after accepting them. The WI stores the version of the accepted terms of use locally. See Terms of Use and Privacy Notice for details.
009 The WI checks the timestamp of the last successful renewal of its mdvm_token (Android or iOS). If the last renewal is older than one month, the WI renews the mdvm_token, even though no operation requires it at this point in time. This keeps the last-seen timestamp at the MDVM up-to-date, which is the basis for the retention-based backend deletion, and it bounds the time until a revocation is detected for users that did not opt in to push notifications, see Wallet Instance self-locking. Independent of this interval, the WI renews the mdvm_token whenever an operation towards a backend requires a valid one.
010 If the user opted in to push notifications during the initial start-up, the WI checks the locally stored timestamp of the last Update Account operation. If the last registration is older than one month, the WI fetches the current mpp_registration_token from the MPP and updates it at the Push Notification Service (PNS), updating the timestamp on both sides. The monthly interval avoids calling the MPP and the PNS on every start-up, while ensuring that the mpp_registration_token stored at the PNS does not become stale, which would render push notifications undeliverable. Independent of this interval, the WI updates the account immediately whenever the MPP rotates the token.

Platform Authenticator

The Platform Authenticator is the user authentication mechanism provided by the mobile operating system to unlock the device. On Android, this covers biometrics (fingerprint, face) as well as the knowledge factor (PIN, pattern, password). On iOS, this covers Touch ID, Face ID and the device passcode.

The WI relies on the Platform Authenticator for binding local keys and data to the user. Cryptographic keys generated in the hardware-backed keystore (Android Keystore, iOS Keychain/Secure Enclave) are configured such that they can only be used while the Platform Authenticator is set up, and are destroyed by the operating system when the user removes it. The WI does not prompt the user to authenticate against the Platform Authenticator during app launch as the device unlock that preceded opening the app is sufficient. Explicit user authentication is requested for certain operations, such as EAA keybinding.

Encryption at Rest

The Wallet Instance uses the Hardware-backed KeyStore (HKS) to store cryptographic keys, but stores non-cryptographic, sensitive assets in the app context of the user's device. To protect the integrity and confidentiality of this data, the WI stores data encrypted by a key in the WI's hardware-backed keystore (HKS). This is to ensure that this data is not stored unencrypted in backups of the device and that this data is not accessible unencrypted when the wallet app is not active. The key wi_data_enc_symk is generated during the very first wallet start-up and is used throughout the WI's lifecycle for encryption of all local data assets. The key is bound to the Platform Authenticator, thus the data encryption is tied to the user authentication of the device, but the user is not prompted for authentication during app launch. If the Platform Authenticator is removed, the wi_data_enc_symk is destroyed and the WI becomes inaccessible. The lifecycle and algorithm for wi_data_enc_symk is specified in the cryptography chapter. Sensitive assets that are stored long-term encrypted in the Wallet Instance are labeled as "LE" in the Wallet Instance (WI) column of the data register. Examples for these sensitive assets are PID credentials (pp_pid_credential) and associated metadata, as well as the transaction history.

Android

On Android, wi_data_enc_symk is an AES-256-GCM key generated in the Android Keystore, in StrongBox if the device has one and in the Trusted Execution Environment (TEE) otherwise. The WI rejects and deletes the key if the Android Keystore reports that it is not stored in secure hardware. The key is bound to the Platform Authenticator via KeyGenParameterSpec.Builder with setUserAuthenticationRequired() to require the user authentication against the Platform Authenticator before the key can be used and setUserAuthenticationParameters() to accept both biometrics (AUTH_BIOMETRIC_STRONG) and knowledge factor (AUTH_DEVICE_CREDENTIAL, i.e. PIN/pattern/password) for the Platform Authenticator. Additionally, a 4-hour authentication validity window is set to enforce a fresh user authentication after the timeout.

The WI uses two encrypted stores:

  • Encrypted preferences: The WI stores settings and small values in EncryptedSharedPreferences, with wi_data_enc_symk as the master key. wi_data_enc_symk encrypts the Tink keysets that encrypt the preferences. The keys of the preferences are encrypted with AES-256-SIV, a deterministic scheme, so the WI can still look up a preference by its encrypted key. The values are encrypted with AES-256-GCM.
  • Encrypted database: The WI stores credentials such as pp_pid_credential and their metadata, the key metadata of the Android Keystore Secure Area, and the transaction history in a SQLCipher for Android database. The database file is in the app's no-backup directory. SQLCipher 4 encrypts each database page with AES-256-CBC using a random IV per page and authenticates it with HMAC-SHA512 (encrypt-then-MAC). SQLCipher derives the database key from a 256-bit random passphrase with PBKDF2-HMAC-SHA512 (256,000 iterations). The WI generates this passphrase with SecureRandom on first use and stores it in the encrypted preferences, so wi_data_enc_symk protects it.

iOS

On iOS, wi_data_enc_symk is generated in the iOS Keychain with the accessibility attribute kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly. This ensures that the key only becomes available after the device has been unlocked at least once since boot and is bound to a device that has a passcode/biometric set up. If the user removes the Platform Authenticator, the key is deleted by the operating system ("Disabling the device passcode causes all items in this class to be deleted."). It also ensures the key is excluded from iCloud Keychain and device backups, so the encrypted data cannot be restored on a different device. Unlike Android, iOS does not expose a per-key authentication validity window, the OS treats the device unlock as sufficient authentication for the lifetime of the session.

For the data encryption, the WI uses the Keychain directly with the given accessibility flag.

Terms of Use and Privacy Notice

The Wallet Provider publishes the terms of use and the privacy notice in German and English. The WI displays both documents within the app. The privacy notice is additionally linked in the app store listing, such that the user can be informed before installing the app.

The use of the WI requires the acceptance of the terms of use, and a separate contract of use is concluded for each Wallet Instance. Therefore, the user has to accept the terms of use during the initial start-up, before the WI registers at the backends of the Wallet Provider. The privacy notice is shown for information only. The WI stores the version of the accepted terms of use locally.

The Wallet Provider may amend the terms of use. It has to inform the user about the amendment within the wallet at least four weeks before the amended terms of use come into force, and the amended terms of use only become effective with the express consent of the user. To implement this, the Wallet Provider distributes the current version of the terms of use with the feature flag terms_of_use_version, which contains the date on which this version comes into force (ISO 8601 date, e.g. 2027-01-01). Using the effective date as the version identifier allows the WI to derive both the order of the versions and whether a version is already in force from a single value. During the subsequent start-up, the WI compares the terms_of_use_version with the version of the accepted terms of use:

  • no amendment: the versions are equal and the start-up continues.
  • amendment not yet in force: the terms_of_use_version is newer and its date lies in the future. The WI shows the amended terms of use together with a summary of the material changes once. The user may accept them right away or postpone the acceptance.
  • amendment in force: the terms_of_use_version is newer and its date is reached. The WI shows the amended terms of use together with a summary of the material changes and blocks any further use until the user accepts them. A user who does not want to accept the amended terms of use may terminate the contract of use by deleting the wallet, see Wallet Deletion.

The WI evaluates the effective date against the clock of the user device. As the acceptance of the terms of use is a contractual and not a security control, a manipulated device clock only delays the blocking for the user who manipulated it.

Feature Flags

Feature flags allow the Wallet Provider to change the configuration of all Wallet Instances without releasing a new version of the app, e.g. to enforce a minimum app version, to enable or disable functionality, or to adapt to configuration changes of other parties.

The Feature Flag Service (FFS) is a self-hosted FeatureHub instance operated by the Wallet Provider. The FFS holds separate applications for Android and iOS, each with separate environments. The WI authenticates towards the FFS with a static API key that selects the application and environment. The API key is compiled into the app and is therefore not a secret. It is identical for all installations of the app on a platform and environment and does not identify the WI or the user. Consequently, all Wallet Instances of a platform and environment receive the same feature flags.

The WI fetches the feature flags at start-up and whenever the app returns to the foreground, if no feature flags are stored or the last successful fetch is older than 24 hours. The fetch does not delay the start-up, the WI re-evaluates the minimum app version once the fetch completes. The WI stores the fetched feature flags locally and continues to use the previously stored feature flags if a fetch fails. Each feature flag has a built-in default value in the app, which the WI uses if the FFS does not provide a value.

Unlike the responses of the other backends of the Wallet Provider, the response of the FFS is only protected by TLS without CA pinning. Hence, feature flags only carry non-sensitive configuration values and must not be used to switch off security controls of the WI.

Feature Flag Default Description
minimum_app_version 0.0.0 Minimum app version (semantic version) required to use the WI. If the app version is lower, the WI blocks its use and directs the user to the app store, see step 004 of the initial start-up and the subsequent start-up.
credential_configuration_id_sdjwt built-in value credential_configuration_id of the PID in SD-JWT VC format that the WI requests in the PID issuance. Allows to follow changes of the PID Provider's metadata without an app release.
credential_configuration_id_mdoc built-in value credential_configuration_id of the PID in mdoc format that the WI requests in the PID issuance. Allows to follow changes of the PID Provider's metadata without an app release.
terms_of_use_version (planned) version at build time Effective date of the current version of the terms of use (ISO 8601 date), see Terms of Use and Privacy Notice.

Wallet Invocation

Relying Parties and EAA Providers invoke the Wallet Instance with custom URL schemes, either through a link on the same device or through a QR code scanned by the WI in cross-device flows. The WI registers the following custom URL schemes with the operating system (Android intent filters, iOS CFBundleURLTypes):

Custom URL Scheme Flow Specification
eu-eaap:// Remote PID presentation, Remote EAA presentation ETSI TS 119 472-2
haip-vp:// Remote PID presentation, Remote EAA presentation OpenID HAIP 1.0
openid4vp:// Remote PID presentation, Remote EAA presentation OpenID4VP 1.0
eu-eaa-offer:// EAA issuance ETSI TS 119 472-3
haip-vci:// EAA issuance OpenID HAIP 1.0
openid-credential-offer:// EAA issuance OpenID4VCI 1.0

The WI handles all presentation schemes identically by passing the OpenID4VP Authorization Request to the presentation flow, and all issuance schemes identically by passing the Credential Offer to the issuance flow.

Custom URL schemes are not exclusive to a single app, as any app can register the same scheme. On Android, the user selects the app from a disambiguation dialog if multiple apps handle the same scheme, or the system opens the app the user previously chose as default. On iOS, the user is not asked which app to open: if multiple apps register the same scheme, the app the system targets is undefined. As other wallets register the same standardized schemes, a link may therefore open a different wallet than the WI on both platforms. Consequently, the WI does not derive any trust from the invocation itself, but authenticates the Relying Party with the signed Authorization Request and the EAA Provider with its signed metadata. For the same reason, the redirect back to the WI after the user authorization during EAA issuance uses a claimed HTTPS URI instead of a custom URL scheme.

Invocation via the W3C Digital Credentials API, as specified in Annex A of OpenID4VP 1.0, is not yet supported.