Skip to content

Commit

Permalink
wallet instance lifecycle
Browse files Browse the repository at this point in the history
  • Loading branch information
@balanza
balanza committed Mar 22, 2024
1 parent 3a37a32 commit c32ada2
Showing 1 changed file with 60 additions and 1 deletion.
61 changes: 60 additions & 1 deletion docs/en/wallet-attestation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -478,7 +478,66 @@ The body of the Wallet Attestation JWT MUST contain:
-
* - **presentation_definition_uri_supported**
- Boolean value specifying whether the Wallet Instance supports the transfer of presentation_definition by reference. MUST be set to false.
-

Wallet Instance Lifecycle
------------

The ability of the Wallet Instance to obtain a Wallet Attestation is bound to its current state.
The Wallet Instance calculates its current state based on its local credentials storage and its revocation state on the Wallet Provider's backend, if present.

The Wallet Instance lifecycle defines all possible states a Wallet Instance can be in, as well as the transitions between them. The Wallet Instance lifecycle is illustrated in the following diagram:

.. figure:: ../../images/wallet_instance_lifecycle.svg
:name: Wallet Instance Lifecycle
:alt: The image illustrates the Wallet Instance lifecycle, with the states explained below.
:target: https://www.plantuml.com/plantuml/uml/SoWkIImgAStDuOhMYbNGrRLJyCm32kNafAPOAMH2c5mAG00N1YloBqWjIYp9pCzBpB5IA4ijoaoh1Ab25WUh2qlCoKm1gW1HYIMf83KGCKnJClDmg799JKmkoIm3IW1DAaejoyzEHRSBfpfCbmEzQQLGceVaDOH6x4emxS9KWd0mfgH3QbuAC801


A Wallet Instance can obtain a Wallet Attestation is it's in either `Installed`, `Operational` or `Valid` state; that implies that a `Deactivated` Wallet Instance cannot obtain a Wallet Attestation hence it cannot interact with other actors such as Credentil Issuers and Relying Parties.

States
~~~~~~~~~~~~~~~~~~
+---------------+--------------------------------------------------------------------------------------------------------------------------------+
| State | Description |
+===============+================================================================================================================================+
| `Installed` | The Holder has installed the Wallet Solution on the device |
+---------------+--------------------------------------------------------------------------------------------------------------------------------+
| `Operational` | The Wallet Instance has been verified and the Wallet Hardware Key has been registered; no valid PID is present in the storage. |
+---------------+--------------------------------------------------------------------------------------------------------------------------------+
| `Valid` | A valid PID is present in the storage |
+---------------+--------------------------------------------------------------------------------------------------------------------------------+
| `Deactivated` | The Wallet Instance has been revoked and its Wallet Hardware Key has been marked as not usabel |
+---------------+--------------------------------------------------------------------------------------------------------------------------------+

Transitions
~~~~~~~~~~~~~~~~~~
+--------------+--------------------------------------------------------------------------------------------------------------+
| Transition | Description |
+==============+==============================================================================================================+
| `install` | The Holder performs a fresh installation or restore the initial state of the Wallet Instance on the device |
+--------------+--------------------------------------------------------------------------------------------------------------+
| `verify` | The Wallet Instance has been verified by the Wallet Provider and its Wallet Hardware Key has been registered |
+--------------+--------------------------------------------------------------------------------------------------------------+
| `validate` | The Wallet Instance obtains a valid PID |
+--------------+--------------------------------------------------------------------------------------------------------------+
| `invalidate` | The PID expires or gets revoked |
+--------------+--------------------------------------------------------------------------------------------------------------+
| `revoke` | The Wallet Provider marks the Wallet Instance as not usable |
+--------------+--------------------------------------------------------------------------------------------------------------+
| `uninstall` | The Holder removes the Wallet Instance from the device |
+--------------+--------------------------------------------------------------------------------------------------------------+

Revocations
~~~~~~~~~~~~~~~~~~
As mentioned in the *Wallet Instance initialization and registration* section above, a Wallet Instance is bound to a Wallet Hardware Key and it's uniquely identified by it.
The Wallet Provider, which holds the Wallet Hardware Keys, can mark them as *revoked* so to make the related Wallet Instance unusable.

The details of the revocation mechanism used by the Wallet Provider as well as the data model for maintaining the Wallet Instance references is delegated to the Wallet Provider's implementation.

During the *Wallet Instance initialization and registration* phase the Wallet Provider may associate the Wallet Instance with a specific Holder uniquely identified within the Wallet Provider's systems as well as with metadata regarding the device the Wallet Instance is running on such as operative system version, chipset capabilities and the Wallet Solution version.
These informations can allow the Wallet Provider to selectively revoke Wallet Instances based on specific criteria.

The choice of which data need to be stored is left to the Wallet Provider.


.. _token endpoint: wallet-solution.html#wallet-attestation
Expand Down

0 comments on commit c32ada2

Please sign in to comment.