Add Wallet Instance Revocation section (#542)

* feat: add Wallet Instance Revocation section

* fix: ci linting on missing EOL

* Apply suggestions from code review

---------

Co-authored-by: Giuseppe De Marco <[email protected]>

docs/en/index.rst

@@ -40,6 +40,7 @@ Index of content
    lifecycle.rst
    wallet-solution.rst
    wallet-attestation.rst
+   wallet-revocation.rst
    pid-eaa-data-model.rst
    pid-eaa-issuance.rst
    pid-eaa-entity-configuration.rst

docs/en/wallet-attestation.rst

@@ -549,34 +549,6 @@ The body of the Wallet Attestation JWT MUST contain:
       - Array of JSON Strings containing the values of the Client Identifier schemes that the Wallet supports.
       - `OpenID4VP`_
 
-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 Instance SHOULD send its public Wallet Hardware Key with the Wallet Provider, thus the Wallet Provider MUST identify a Wallet Instance by its Wallet Hardware Key.
-
-When a Wallet Instance is not usable anymore, the Wallet Provider MUST revoke it. The revocation process is a unilateral action taken by the Wallet Provider, and it MUST be performed when the Wallet Instance is in the `Operational` or `Valid` state.
-A Wallet Instance becomes unusable for several reasons, such as: the User requests the revocation, the Wallet Provider detects a security issue, or the Wallet Instance is no longer compliant with the Wallet Provider's security requirements.
-
-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.
-
-According to ARF, `Section 6.5.4 <https://github.com/eu-digital-identity-wallet/eudi-doc-architecture-and-reference-framework/blob/main/docs/arf.md#654-wallet-instance-management>`_ and more specifically in `Topic 38 <https://github.com/eu-digital-identity-wallet/eudi-doc-architecture-and-reference-framework/blob/main/docs/annexes/annex-2/annex-2-high-level-requirements.md#a2338-topic-38---wallet-instance-revocation>`_ the Wallet Instance can be revoked by the following entities:
-
-  1. Its owner, the User
-  2. Wallet Provider
-  3. PID Provider
-
-During the *Wallet Instance initialization and registration* phase the Wallet Provider MAY associate the Wallet Instance with a specific User, subject to obtaining the User's consent. The Wallet Provider MUST evaluate the operating system and general technical capabilities of the device to check compliance with the technical and security requirements and to produce the Wallet Instance metadata.
-When the User consents to being linked with the Wallet Instance, they gain the ability to directly request Wallet revocation from the Wallet Provider, and it also allows the Wallet Provider to revoke the Wallet Instance associated with that User.
-
-Regarding the reasons for revoking a Wallet Instance, the following scenarios may occur:
-
-- The smartphone is lost;
-- The smartphone has been compromised (e.g., a malicious actor gains control of the smartphone);
-- The smartphone has been reset to factory settings;
-- Any other scenarios where the User loses the control of the Wallet Instance.
-
-If any of the previous scenarios occur, the Wallet Instance **MUST** be revoked.
-To allow the User to revoke the Wallet Instance, the Wallet Provider (WP) **MUST**  offer a remote service, such as a web page, where the User can authenticate and request the revocation of a previously activated Wallet Instance.
 
 .. _token endpoint: wallet-solution.html#wallet-attestation
 .. _Wallet Attestation Request: wallet-attestation.html#format-of-the-wallet-attestation-request
@@ -588,3 +560,5 @@ To allow the User to revoke the Wallet Instance, the Wallet Provider (WP) **MUST
 .. _DeviceCheck: https://developer.apple.com/documentation/devicecheck
 .. _OAuth 2.0 Nonce Endpoint: https://datatracker.ietf.org/doc/draft-demarco-oauth-nonce-endpoint/
 .. _ARF: https://github.com/eu-digital-identity-wallet/eudi-doc-architecture-and-reference-framework
+
+

docs/en/wallet-revocation.rst

@@ -0,0 +1,55 @@
+.. include:: ../common/common_definitions.rst
+
+.. _wallet-revocation.rst:
+
+Wallet Instance Revocation
+==========================
+
+This section describes the involved entities and modalities to request a Wallet Instance revocation in the IT-Wallet system.
+
+The Wallet Provider MUST ensure the security and reliability of Wallet Instances, keeping them updated and compliant with security requirements. When, for technical security reasons (e.g., relating to the compromise of cryptographic material) the security of the Wallet Instance is compromised, the Wallet Provider MUST revoke the Wallet Instance. 
+
+
+As shown in :numref:`fig_Wallet_Instance_Revoc_Entities`, other actors MAY trigger the Wallet Instance revocation process:
+
+- **Users**, connecting to the Wallet Provider’s web portal from their Wallet Instance or using an external browser.
+- **PID Providers** when notified by the Authentic Source of the PID (ANPR) of the User’s death.
+- **Legal Authorities or the Supervisory Body** in cases of proven illegal activities.
+
+
+.. _fig_Wallet_Instance_Revoc_Entities:
+.. figure:: ../../images/wallet_instance_revocation.svg
+    :figwidth: 80%
+    :align: center
+    :target: https://www.plantuml.com/plantuml/uml/fL9TZn8z5BwVNt5URbusSPSRhxnQ5oOHuog1tHYJJIPbMk74JZksf-1e_E-UKmiguvqafFIXpyVvk8sa0gNELl-XQstI1lP4VNmncmLrlDaXxTCsHHDQxyWukcbzD-kjSiAvZgGjRcVpvzShWHxltymw5Sa4XfgvxthlXDEBVlLgkQYRpKEzhjyzV5ZLqwkgMfaGlPkA_ZEOFF8nuRDsX3I0FpfqEw2zWIVtNbbh29QEyxhMJ9XyvvFJAWpJO_wlYGCxTymlRpVvFhc2RnNmvnpdz1wBbZ0kr1cIxxroQcSYIBx_8ooGsw4ip8FHh8FAHixnL-q--0DghkealIh0IRhS8rnOWt8QZcOBR7d0reZ3zwhwPQ0IxSMyRQ9F8QT_UO9Waw6HXpGM5570RIA-ayzTNSQOJCYENQbKu8Eog6K0d8YI13YxD_MNdmbymAz6Drkl1mbmHY3F3aqyPTYaNWg9FWnmnw-ps-kaiKLbeH1fO9FVQiGSJ2fOBaQTowdZ7wdbcTnBr-Db0wjgRMpPiei1ZOSFQtFmhIBqZdz-PYyI2L4OSSUR9EHFvdAg4a84fB1_3J5UW7Extdh2ZuECMzRroMcZQ5-iHrCRPoZq9UCx6KvBU432dFxME9qw-mC0
+
+    Entities involved in the Wallet Instance revocation process.
+.. note::
+   Detailed flows for **PID Provider, Legal Authorities,** and **Supervisory Body** will be covered in future versions of the technical specification.
+
+Revocation Request from the User
+--------------------------------
+
+Users MAY request the Wallet Instance revocation by:
+
+- *Selecting the revocation functionality from their Wallet Instance*: this functionality may be used by Users before changing their phone.
+- *Using an external user agent*: this covers cases where Users lose their device, and so their access to their Wallet Instance.
+
+In both cases, by using the Wallet Provider portal:
+
+- Users MUST authenticate with at least a second-factor authentication mechanism, or have an active session that meets this requirement. 
+- The Wallet Provider MUST allow Users to view the state of all their Wallet Instances and ask for their revocation.
+
+Validity Verification Mechanisms
+--------------------------------
+The verification of the Wallet Instance validity MUST be performed:
+
+- **During Digital Credential issuance or presentation phase** by the Credential Issuers and Relying Parties, respectively. Only Wallet Instances in Operational or Valid state have valid Wallet Attestations. Thus, the verification of the validity of a Wallet Instance is indirectly performed by Credential Issuers and Relying Parties by checking the presence of valid Wallet Attestation (i.e. not expired and signed by a trusted Wallet Provider). 
+
+- **During the validity period of the Digital Credential**  by the Credential Issuers. Indeed, if the Wallet Instance is revoked, the PID hosted within it MUST be revoked. Any other Digital Credential obtained through the presentation of the PID MUST therefore be revoked too. In the current version of the specification, Credential Issuers are directly notified of a Wallet Instance revocation by the Wallet Provider using a PDND e-service.
+
+
+.. note::
+   With the introduction of the **Wallet Trust Evidence (WTE)**, this section will be updated accordingly.
+
+