Wallet Revocation¶
The revocation of a Wallet Instance may happen for various reasons:
- the user revokes its Wallet Instance, e.g. because it lost its device
- the MDVM revokes a Wallet Instance due to security reasons of the device or wallet app
Wallet Revocation by the User¶
A common use case for revocation of the Wallet Instance is that the user has lost its device and wants to prevent any mis-use. A loss of the user's device alone is not a security problem, as the platform authentication protects the unlocking of the wallet app and the Remote WSCA PIN additionally protects the PID. However, the user must have additional means to prevent the mis-use of the wallet and its contained credentials, in case the platform authentication and/or RWSCA-PIN are leaked or known by adversaries.
For these reasons, a revocation mechanism is established between the user and the Wallet Provider Backend (WB) during wallet activation. The revocation mechanism must be independent from the Wallet Instance ("out-of-band"), as it is assumed that the user has no access to its device. The setup of the wallet revocation mechanism takes place during the Wallet Activation. The WB stores the information for out-of-band authentication of the user in its WB account database. The available revocation mechanisms are:
The Wallet Provider Backend (WB) provides a website, where the user can authenticate with the revocation mechanism established during wallet activation. The WB tries to verify and associate the authentication to a specific Wallet Instance in its WB account database. If the WB successfully matches the incoming revocation request to a Wallet Instance, it takes the following actions:
- signaling to the Wallet Instance to self-lock and delete all local data
- signaling to the PID/EAA Providers by setting the status of the Wallet Instance Attestation to revoked that will trigger the revocation chaining.
Revocation code¶
For the revocation code mechanism the WB generates a random secret (wb_wi_revocation_secret) with sufficient entropy during wallet activation. The WB stores the hash of wb_wi_revocation_secret in the WB account database. Storing the hash ensures that potential database leaks do not allow to revoke arbitrary Wallet Instances. The WB uses the raw wb_wi_revocation_secret and encodes it as a single string using Bech32. Bech32 encoding combines base32 encoding (with a good tradeoff between size and user convenience to avoid similar characters) and BCH error detection/correction (in case users need to type the revocation code manually). The resulting revocation code wb_wi_revocation_code is returned to the WI. An example for the Bech32-encoded wb_wi_revocation_code:
The user is instructed about the revocation mechanism and the website for wallet revocation. The WI offers the user different options to store the code:
- copy the code to the clipboard
- export the code within a PDF file for cloud storage or printing
- storage in a synced password manager
If the user wants to revoke the WI, it has to open the WB's revocation website, either manually or following a link/QR-Code in the PDF. The user is once more explained the consequences of wallet revocation. The website contains a single text input form for the Bech32-encoded wb_wi_revocation_code. Depending on the type of storage the user has to:
- paste the code that the user copied from external storage
- click the link or scan the QR-Code (which prefills the text form)
- fill the text form through the synced password manager
The WB will decode the wb_wi_revocation_code, identify the account by wb_wi_id and verify the revocation request by wb_wi_revocation_secret and proceed to take actions to revoke the WI.
At any point of the Wallet Instance's lifecycle, the user may go to the settings of the app and request to receive a newly generated revocation code. This will invalidate the old revocation code.
Flows¶
Sequence Diagram¶
Detailed Description¶
| No | Description |
|---|---|
| 001 - 012 | Standard procedure for creating and verifying signed request. To be refined when WB flows are merged. |
| 013 | The WB generates the revocation code wb_wi_revocation_code from 128 bits of random, ensuring a sufficiently secure random generator is being used. |
| 014 | The WB updates the Wallet Backend account database to store the hash of the wb_wi_revocation_code for Wallet Instance account wb_wi_id that was authenticated in the request. The WB stores the hash using Argon2id using moderate difficulties, such as m=32MB,t=3,p=1, as the input wb_wi_revocation_code already has very high entropy. Storing the hash instead of the plain wb_wi_revocation_code prevents attackers to revoke arbitrary Wallet Instances in case of a database leak. |
| 015 | The WI calculates the Bech32 encoding using rev for the human readable header part, 1 as the default separator character and the concatenated, raw binary representation of (un-hashed!) wb_wi_revocation_secret. Calculating this string in the backend avoid complexity of keeping the code in sync between backend, Android and iOS implementation. |
| 016 | The WB returns the wb_wi_revocation_code to the WI. |
| 017 | The WB offers multiple options to the user to store the wb_wi_revocation_code. This includes:
|
| 018 | The first option is to store the wb_wi_revocation_code to the clipboard of the mobile operating system. iOS implementations must use UIPasteBoard with localOnly and expirationDate of 60 seconds. Android implementations must follow the secure clipboard handling using ClipDescription.EXTRA_IS_SENSITIVE, the data is flushed automatically after some time. The text copied to the clipboard gives a brief introduction and also provide the URL to the revocation website. The wb_wi_revocation_code should also be visible, so users may take a screenshot instead. |
| 019 - 020 | The WI calculates a URL to the WB's revocation website and appends the wb_wi_revocation_code as a query parameter (for automatically filling the text form). The WI locally generated a PDF using native platform APIs. The PDF gives a brief introduction to the wallet revocation scenario and provides the URL as a click-able link and as a QR-Code. |
| 021 | The WI uses the Autofill functionality to store the wb_wi_revocation_code in the password manager. iOS implementations must use ASPasswordCredential to store the wb_wi_revocation_code. The WI app and WB revocation website must be connected using associated domains. Android implementation must suggest the storage using the AutofillManager by marking the UI element containing wb_wi_revocation_code with AUTOFILL_HINT_NEW_PASSWORD. The WI app and WB revocation website must be connected using Digital Asset Links. |
| No | Description |
|---|---|
| 001 - 002 | The user opens the WB's revocation website. The user manually types or copies the wb_wi_revocation_code from external storage, such as messenger, e-mail or physical notes. |
| 003 - 004 | The user opens the PDF to click the embedded link or scans the embedded QR-Code. This opens the WB' revocation website on the user's browser and prefills the input for the wb_wi_revocation_code from the query parameter. |
| 005 - 006 | The user opens the WB's revocation website. The password manager suggests to fill the wb_wi_revocation_code. |
| 007 | The browser website locally checks the entered Bech32-encoding of wb_wi_revocation_code for error detection. |
| 008 | The browser website and the WB's revocation endpoint perform Captcha checks to impede access for bots or DoS. |
| 009 | The browser sends a request to the WB's revocation endpoint containing the wb_wi_revocation_code and potential Captcha information. |
| 010 | The WB calculates the hash of wb_wi_revocation_code using Argon2id with the same parameters as during revocation setup and performs a look-up against the WB account database to identify whether the wb_wi_revocation_code matches against a valid wb_wi_id. If no entry was found, the WB endpoint returns an error. |
| 011 | The WB marks the identified WI as "PENDING_WIA_REVOCATION", to prevent further operations of this WI. |
| 012 - 013 | The WB revokes the status list entries of all WIAs (wb_wia_status) that were previously issued by the wb_wi_id to initiate the revocation chaining. When WIA revocation is completed, the WB marks the state as "PENDING_APP_REVOCATION", marking the WIA revocation as completed, but the self-locking of the WI as outstanding. |
| 014 - 016 | The WB sends a push notification to trigger the WI to check its status. The WI queries the WB's status endpoint to confirm the revocation request and self-locks to delete all the local data. See Wallet Instance self-locking for details. After confirmation by the WI, the WB marks the wb_wi_id as "REVOKED" (successfully deleted). |
Wallet Revocation by the MDVM¶
If the Mobile Device Vulnerability Management (MDVM) determines that revocation actions are required, this can be triggered by two conditions:
- The MDVM identifies a new vulnerability, requiring revocation for all Wallet Instances associated with affected device classes.
- During the renewal of an MDVM token, a security issue is detected for an individual device.
In both cases, the MDVM identifies the affected Wallet Instances. For device class–based vulnerabilities, this includes all Wallet Instances matching the vulnerable device class. For individual device issues, only the specific affected Wallet Instance is targeted.
The MDVM then requests the execution of revocation actions by sending the shared possession factor public keys (wi_mdvm_auth_pubk) to the WB. The connection is secured via mTLS, and network access to the WB endpoint is restricted to the MDVM.
| No | Description |
|---|---|
| 001 - 002 | The MDVM filters the MDVM account database for all Wallet Instances that are effected by known vulnerabilities. |
| 003 - 004 | The WI attempts to get a new MDVM token (Android or iOS). During validation of MDVM signals, the MDVM detects a compromise of the WI's mobile device. |
| 005 - 006 | The MDVM sends a request to the WB's internal revocation endpoint containing the list of wi_mdvm_auth_pubk that identify the Wallet Instances to be revoked. This endpoint is secured by mTLS and networking routing ensures that this endpoint is only reachable by the WB. |
| 007 | The WB marks the identified WI as "PENDING_WIA_REVOCATION", to prevent further operations of this WI. |
| 008 - 009 | The WB revokes the status list entries of all WIAs (wb_wia_status) that were previously issued by the wb_wi_id to initiate the revocation chaining. When WIA revocation is completed, the WB marks the state as "PENDING_APP_REVOCATION", marking the WIA revocation as completed, but the self-locking of the WI as outstanding. |
| 010 - 012 | The WB sends a push notification to trigger the WI to check its status. The WI queries the WB's status endpoint to confirm the revocation request and self-locks to delete all the local data. See Wallet Instance self-locking for details. After confirmation by the WI, the WB marks the wb_wi_id as "REVOKED" (successfully deleted). |
Revocation Actions¶
Wallet Instance Self-locking¶
to be done
Revocation Chaining¶
to be done