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 (WB) 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 WB 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 processes of wallet activation additionally involve the user:

  • 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 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 user is shown the introduction screens explaining the features and functionalities of the wallet app

However, the RWSCA-PIN is not set within the wallet activation. UX tests have revealed that it is advantageous to delay this process 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.Mobile Device Vulnerability Management .MDVM.Wallet Backend .WB.Remote WSCA .RWSCA.UserUserWallet Instance / App (WI)Wallet Instance / App (WI)Mobile Device Vulnerability Management (MDVM)Mobile Device Vulnerability Management (MDVM)Wallet Backend (WB)Wallet Backend (WB)Remote WSCA (RWSCA)Remote WSCA (RWSCA)(001)open wallet(002)initialize RASP SDK(003)check platform authenticator setup(004)create wi_data_enc_symk for local data encryption(005)MDVM registration(006)Wallet Backend registration(007)Remote WSCA registration(008)show introduction/new features screens(009)setup wallet revocation

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 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.
004 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.
005 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.
006 The WI registers at the WB using the public key and the token received from the MDVM, establishing a persistent account with the WB. See Wallet Registration for details.
007 The WI registers at the RWSCA using the public key and the token received from the MDVM, establishing a persistent account with the RWSCA. See Create Account operation for details.
008 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.
009 The WI and WB set up a mechanism for user-initiated revocation, see wallet revocation.

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.Mobile Device Vulnerability Management .MDVM.Wallet Backend .WB.Remote WSCA .RWSCA.UserUserWallet Instance / App (WI)Wallet Instance / App (WI)Mobile Device Vulnerability Management (MDVM)Mobile Device Vulnerability Management (MDVM)Wallet Backend (WB)Wallet Backend (WB)Remote WSCA (RWSCA)Remote WSCA (RWSCA)(001)open wallet(002)initialize RASP SDK(003)check platform authenticator setup(004)check local data decryption with wi_data_enc_symk

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 - 004 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.

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 stores sensitive assets such as PID credentials (pp_pid_credential) and associated metadata, as well as the transaction history 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.

Android

On Android, wi_data_enc_symk is generated in the Android Keystore and 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.

For the data encryption, the WI uses EncryptedSharedPreferences or Jetpack DataStore wrapped with a wi_data_enc_symk-derived AEAD scheme.

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.