Merge pull request #47 from italia/wie

editorial: wallet instance attestation and solution

docs/en/defined-terms.rst

@@ -28,6 +28,8 @@ Below are the description of acronyms and definitions which are useful for furth
      - An instance of the Wallet Solution, installed on a personal mobile device and controlled by a specific User who is its sole owner. It is the application that enables citizens to fully and autonomously manage their digital identity and EAAs.
    * - Wallet Provider
      - All public and/or private entities, conforming to a technical profile and accredited by the Federation Authority, that provide citizens with an IT Wallet Instance.
+   * - Wallet Instance Attestation
+     - Verifiable Attestation, issued by the Wallet Provider, that proves the security compliace of the Wallet Instance.
    * - Qualified Electronic Attestation of Attributes (QEAA)
      - A digitally verifiable attestation in electronic form, issued by a QTSP, that substantiates a person's possession of attributes.
    * - Qualified Electronic Signature Provider

docs/en/pid-issuance.rst

@@ -51,7 +51,7 @@ The PID Issuance phase is based on the **Authorization Code Flow** with **Pushed
 
 .. note::
 
-    **Federation Check:** The Wallet Instance needs to check if the PID Provider is part of Federation and then it can consume its Metadata. A non-normative example of a response from the endpoint **.well-known/openid-federation** with the **Entity Configuration** and the **Metadata** of the PID Provider is represented within the section `Entity Configuration Credential Issuer <Entity Configuration Credential Issuer>`_.
+    **Federation Check:** The Wallet Instance needs to check if the PID Provider is part of Federation and then it can consume its Metadata. A non-normative example of a response from the endpoint **.well-known/openid-federation** with the **Entity Configuration** and the **Metadata** of the PID Provider is represented within the section `Entity Configuration Credential Issuer`_.
 
 
 **Steps 5-6:** The Wallet Instance creates a PKCE code verifier that sends in a *pushed authorization request*, using the request parameter (see :rfc:`9126` Section 3) to the PID Provider authorization endpoint. The Wallet Instance signs the request using its private key. A OAuth2 client authentication method must be involved, since in this flow the pushed authorization endpoint is a protected endpoint. The client authentication should be based on the model defined in [:rfc:`7521`] using the Wallet Instance Attestation JWS inside the **client_assertion** parameter. The authorization_details [RAR :rfc:`9396`] parameter is extended to allow Wallet Instance to specify the types of the credentials when requesting authorization for the PID issuance.
@@ -723,6 +723,8 @@ Credential Response to the Wallet Instance MUST be sent using `application/json`
   If the **format** value is `mso_mdoc`, the **credential** value MUST be a base64url-encoded JSON string according to Appendix E of `[OIDC4VCI. Draft 13] <https://openid.bitbucket.io/connect/openid-4-verifiable-credential-issuance-1_0.html>`_.
 
 
+.. _Entity Configuration Credential Issuer:
+
 Entity Configuration Credential Issuer
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/en/relying-party-solution.rst

@@ -497,7 +497,7 @@ Below is a non-normative response example:
             ]
         },
         "metadata": {
-            "wallet_verifier": {
+            "wallet_relying_party": {
                 "application_type": "web",
                 "client_id": "https://rp.example.it",
                 "client_name": "Name of an example organization",

docs/en/wallet-instance-attestation.rst

@@ -5,11 +5,14 @@
 Wallet Instance Attestation
 +++++++++++++++++++++++++++
 
-Inside a **Wallet Solution** and, especially with regards
-to the **Wallet Instance**, it is essential to ensure the **authenticity,
-integrity, security, privacy and trust** in the use of the latter both
-by the User and the services connected to it, such as the
-**PID Provider** or one **Relying Party**.
+The Wallet Instance Attestation contains data about the Wallet Provider, 
+the Wallet Solution, the Wallet Instance and the security level of the device 
+where the Wallet Instance is installed on, in general speaking it attests the
+**authenticity,
+integrity, security, privacy and trust** regarding a specific Wallet Instance.
+The Wallet Instance Attestation MUST contain the Wallet Instance public key.
+
+
 
 
 General Properties
@@ -613,7 +616,7 @@ A second **POST /token** endpoint that takes two parameters as input:
 ``grant_type`` which in our case is a string:
 ``urn:ietf:params:oauth:client-assertion-type:jwt-key-attestation``
 
-``assertion``` which contains the signed JWT of the Wallet Instance Attestation
+``assertion`` which contains the signed JWT of the Wallet Instance Attestation
 Request.
 
 The response will then contain the Wallet Instance Attestation.

docs/en/wallet-solution.rst

@@ -7,32 +7,31 @@ Wallet Solution
 
 The Wallet Solution is a comprehensive product offered by the Wallet Provider to cater to the needs of Users in managing their digital assets securely. Designed to provide a seamless User experience, this solution enables Users to leverage the capabilities of the Wallet effectively.
 
+The Wallet Solution is issued by the Wallet Provider in the form of a mobile app, it also consists of services and web interfaces for the exchange of data between the Wallet Provider and its Wallet Instances for the requirements of the trust model and in total respect of the user's privacy, in accordance with national and EU legislation.
+
+The mobile app serves as the primary interface for Users, allowing them to access and interact with their digital assets conveniently. These digital assets, known as Attestations, include Personal Identification Data (PID¹), a set of data that can uniquely identify a natural or a legal person, along with other Qualified and non-qualified Electronic Attestations of Attributes, also known as QEAAs and EAAs respectively, or (Q)EAAs for short¹. Once a User installs the mobile app on their device, we refer to such an installation as a Wallet Instance for the User.
+
+Supporting the mobile app, the Wallet Provider plays a vital role in ensuring the security and reliability of the Wallet Solution. The Wallet Provider is responsible for issuing the Wallet Instance Attestation — a cryptographic proof that verifies the authenticity and integrity of the Wallet Instance.
+
+
 Requirements
-------------
+^^^^^^^^^^^^^^^^^^^^
 
  - **Trustworthiness within the Wallet ecosystem**: the Wallet Instance must establish trust and reliability within the Wallet ecosystem.
  - **Compliance with Provider specifications for obtaining PID and (Q)EAA**: the Wallet Instance must adhere to the specifications set by Providers for obtaining Personal Identification (PID) and Qualified or non-qualified Electronic Address Authentication (Q)EAA.
  - **Support for Android and iOS operating systems**: the Wallet Instance must be compatible and functional at least on both Android and iOS operating systems, as well as available on the Play Store and App Store respectively.
  - **Verification of device ownership by the User**: the Wallet Instance must provide a mechanism to verify the User's actual possession of the device and its control.
 
-Wallet Solution
------------------------------
-The Wallet Solution is issued by the Wallet Provider in the form of a mobile app, it also consists of services and web interfaces for the exchange of data between the Wallet Provider and its Wallet Instances for the requirements of the trust model and in total respect of the user's privacy, in accordance with national and EU legislation.
-
-The mobile app serves as the primary interface for Users, allowing them to access and interact with their digital assets conveniently. These digital assets, known as Attestations, include Personal Identification Data (PID¹), a set of data that can uniquely identify a natural or a legal person, along with other Qualified and non-qualified Electronic Attestations of Attributes, also known as QEAAs and EAAs respectively, or (Q)EAAs for short¹. Once a User installs the mobile app on their device, we refer to such an installation as a Wallet Instance for the User.
-
-Supporting the mobile app, the Wallet Provider plays a vital role in ensuring the security and reliability of the Wallet Solution. The Wallet Provider is responsible for issuing the Wallet Instance Attestation — a cryptographic proof that verifies the authenticity and integrity of the Wallet Instance.
-
 Wallet Instance
------------------------------
+^^^^^^^^^^^^^^^^^^^^
 The Wallet Instance serves as a unique and secure representation of the User within the Wallet ecosystem. It establishes a strong and reliable identity for the User, enabling them to engage in various digital transactions in a secure and privacy-preserving manner.
 
 The Wallet Instance establishes the trust within the Wallet ecosystem by consistently presenting a Wallet Instance Attestation during interactions with other ecosystem actors such as PID Providers, (Q)EAA Providers, and Relying Parties. These attestations, provided by the underlying Wallet Provider operated by the Wallet Provider, reference a pair of asymmetric cryptographic keys exclusively owned by the Wallet Instance. Their purpose is to authenticate the Wallet Instance itself, ensuring its legitimacy when engaging with other ecosystem actors.
 
 To guarantee the utmost security, these cryptographic keys are securely stored within the device's Trusted Execution Environment (TEE)³. This ensures that only the User can access them, thus preventing unauthorized usage or tampering. For more detailed information, please refer to the `Wallet Instance Attestation section`_ and the `Trust Model section`_ of this document.
 
 Wallet Instance Lifecycle
------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 The Wallet Instance can exist in three distinct states: Operational, Valid, and Deactivated. Each state represents a specific functional status and determines the actions that can be performed².
 
 Initialization Process
@@ -64,7 +63,7 @@ Deactivation
 Users have the ability to deactivate the Wallet Instance voluntarily. This action removes the operational capabilities of the Wallet Instance and sets it to the deactivated state. Deactivation provides Users with control over access and usage according to their preferences.
 
 External references
--------------------
+^^^^^^^^^^^^^^^^^^^^
 ¹ Definitions are inherited from the EUDI Wallet Architecture and Reference Framework, version 1.1.0 at the time of writing. Please refer to `this page <https://github.com/eu-digital-identity-wallet/eudi-doc-architecture-and-reference-framework/blob/9647a408f628569449af6b30a15fed82cd41129a/arf.md#2-definitions>`_ for extended definitions and details.
 
 ² Wallet Instance states adhere to the EUDI Wallet Architecture and Reference Framework, as defined `here <https://github.com/eu-digital-identity-wallet/eudi-doc-architecture-and-reference-framework/blob/9647a408f628569449af6b30a15fed82cd41129a/arf.md#424-eudi-wallet-instance-lifecycle>`_.