Apply suggestions from code review

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

docs/en/defined-terms.rst

@@ -46,13 +46,13 @@ Below are the description of acronyms and definitions which are useful for furth
    * - Credential Status Attestation
      - Verifiable Attestation proving that a related Digital Credential is not revoked.
    * - Device Integrity Service
-     - Device manufacturer service that allows you to certify that the app instance (Wallet Instance) is intact and genuine and also allows you to certify that the private keys generated by the device are securely stored within the device's dedicated hardware. Please note that each manufacturer uses different terms to identify it.
+     - A service provided by device manufacturers that verifies the integrity and authenticity of the app instance (Wallet Instance), as well as certifying the secure storage of private keys generated by the device within its dedicated hardware. It's important to note that the terminology used to describe this service varies among manufacturers.
    * - Wallet Hardware Keys
-     - Pair of public and private keys generated by the Wallet Instance during app initialization. These keys remain valid throughout the entire lifespan of the Wallet Instance. Conceptually, the Wallet Hardware Keys serves as a personal device Master Key and, being part of the OS domain, cannot be used for signing any arbitrary payloads. The purpose of the Wallet Hardware Keys is to uniquely identify a Wallet Instance.
+     - During the app initialization, the Wallet Instance generates a pair of keys, one public and one private, which remain valid for the entire duration of the Wallet Instance's life. Functioning as a Master Key for the personal device, these Wallet Hardware Keys are confined to the OS domain and are not designed for signing arbitrary payloads. Their primary role is to provide a unique identification for each Wallet Instance.
    * - Wallet Hardware Key Tag
-     - Unique identifier of the Wallet Hardware Keys generated by the operating system and used to access the private key in the hardware.
+     - A unique identifier created by the operating system for the Wallet Hardware Keys, utilized to gain access to the private key stored in the hardware.
    * - Key Attestation
-     - Attestation signed by device OEM that gives you more confidence that the keys you use in your Wallet Instance are stored in a device's hardware-backed keystore
+     - An attestation from the device's OEM that enhances your confidence in the keys used in your Wallet Instance being securely stored within the device's hardware-backed keystore.
    * - 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/wallet-attestation.rst

@@ -33,9 +33,9 @@ The following requirements for the Wallet Attestation are met:
 6. Each Wallet Instance SHOULD be able to request multiple attestations with different public keys associated to them. This requirement provides a privacy-preserving measure, as the public key MAY be used as a tracking tool during the presentation phase (see also the point number 10, listed below).
 7. The Wallet Attestation SHOULD be usable multiple times during its validity period, allowing for repeated authentication and authorization without the need to request new attestations with each interaction.
 8. The Wallet Attestation SHOULD have an expiration date time, after which it will no longer be considered valid.
-9. The Wallet Attestation SHOULD no longer needs to be issued by the Wallet Provider if the Wallet Instance has been revoked.
-10. The Wallet Attestation SHOULD be pseudo-anonymous (meaning they do not contain direct references to an individual), making it impossible to identify a person without additional information.
-11. When the private key associated with the Wallet Instance is lost or deleted, the attestation MUST become invalid to prevent unauthorized use of the Wallet Instance.
+9. The Wallet Attestation MUST NOT be issued by the Wallet Provider if the Wallet Instance has been revoked.
+10. The Wallet Attestation SHOULD be designed to be pseudo-anonymous, meaning it does not directly reference any individual, thereby making it impossible to identify a person without supplementary information.
+11. When the private key associated with the Wallet Instance is lost or deleted, the Wallet Attestation MUST become invalid to prevent unauthorized use of the Wallet Instance.
 
 
 Static Component View
@@ -70,7 +70,7 @@ Wallet Instance initialization and registration
 
     **Federation Check:** The Wallet Instance needs to check if the Wallet Provider is part of the Federation, obtaining its protocol specific Metadata. A non-normative example of a response from the endpoint **.well-known/openid-federation** with the **Entity Configuration** and the **Metadata** of the Wallet Provider is represented within the section `Wallet Provider metadata`_.
 
-**Steps 3-5:**: The Wallet Instance request and receive a one time ``challenge`` from the Wallet Provider Backend. The ``challenge`` is a ``nonce``, which MUST be unpredictable and it is the primary countermeasure against replay attack. The value of the ``nonce`` returned by the backend must be generated in such a way as to guarantee that it can only be used once and in a pre-established time interval.
+**Steps 3-5:**: The Wallet Instance sends a request to the Wallet Provider Backend and receives a one-time ``challenge``. This "challenge" is a ``nonce``, which must be unpredictable to serve as the main defense against replay attacks. The backend must generate the ``nonce`` value in a manner that ensures it is single-use and valid only within a specific time frame.
 
 
 .. code-block:: http
@@ -87,31 +87,33 @@ Wallet Instance initialization and registration
       "nonce": "d2JhY2NhbG91cmVqdWFuZGFt"
     }
 
-**Step 6**: The Wallet Instance generates the Wallet Hardware Keys pair via the operating system and store the relative Wallet Hardware Key Tag in a local storage:
+**Step 6**: The Wallet Instance, through the operating system, creates a pair of Wallet Hardware Keys and stores the corresponding Wallet Hardware Key Tag in local storage once the following requirements are met:
 
    1. It MUST ensure that Wallet Hardware Keys do not already exist, if they exist and the Wallet is in the initialization phase they must be deleted.
    2. It MUST generate a pair of asymmetric EC keys (Wallet Hardware Keys) via a local WSCD.
-   3. It SHOULD obtain a unique identifier (Wallet Hardware Key Tag) of the generated Wallet Hardware Keys from the operating system. If the operating system allows you to define a tag when creating keys, then a random string for Wallet Hardware Key Tag must be chosen.
-   4. It MUST store the relative Wallet Hardware Key Tag in a local storage.
+   3. It SHOULD obtain a unique identifier (Wallet Hardware Key Tag) for the generated Wallet Hardware Keys from the operating system. If the operating system permits specifying a tag during the creation of keys, then a random string for the Wallet Hardware Key Tag must be selected. This random value MUST be collision-resistant and unpredictable to ensure security. To achieve this, consider using a cryptographic hash function or a secure random number generator provided by the operating system or a reputable cryptographic library. 
+   4. If the previous points are satisfied, It MUST store the Wallet Hardware Key Tag in a local storage.
 
 .. note::
 
     **WSCD:** For key generation, the Wallet Instance will always rely on a local WSCD on devices that support it. For Android, Strongbox will be used or, if it is not available, a Trusted Execution Environment (TEE) while for iOS Secure Elements (SE). Since each OEM develops a different SDK for accessing the local WSCD, it will be treated in a generic manner below.
 
 
-**Step 7**: The Wallet Instance: invokes the operating system attestation service (Device Integrity Service) passing ``challenge`` and Wallet Hardware Key Tag in order to obtain a Key Attestation.
+**Step 7**: The Wallet Instance uses the Device Integrity Service, providing a "challenge" and the Wallet Hardware Key Tag to acquire the Key Attestation.
 
 .. note::
 
-    **Device Integrity Service:** Below we will treat a Device Integrity Service as an abstract entity made available by device OEMs which allows us to certify via a signed payload (attestation) that a particular key is hardware backed in a safe and protected environment of the device. Furthermore, the service will also allow you to demonstrate via a signed payload (assertion) that that particular app instance (Wallet Instance) is intact and genuine and has not been tampered with. Furthermore, both within the attestation and the assertion, the service includes essential information to recover the type of device, the model, the app version, the operating system version, the bootloader status and other information that allows you to understand whether the device has been tampered with or not. For Android the service used is `Key Attestation`_ in addition to `Play Integrity API`_, while for iOS the `DeviceCheck`_ service.
+    **Device Integrity Service:** In this section the Device Integrity Service is considered as it is provided by device manufacturers. This service allows the verification of a key being securely stored within the device's hardware through a signed document (attestation). Additionally, it offers the verifiable proof that a specific app instance (Wallet Instance) is authentic, unaltered, and in its original state using a specialized signed document (assertion) made for this scope. 
+
+    The service also incorporates details in both the attestation and the assertion, such as the device type, model, app version, operating system version, bootloader status, and other relevant information to assess the device has not been compromised. For Android the service used is `Key Attestation`_ in addition to `Play Integrity API`_, while for iOS the `DeviceCheck`_ service.
 
-**Step 8**: The Device Integrity Service:
+**Step 8**: The Device Integrity Service performs the following actions:
 
-  * generate a Key Attestation holder binded with ``challenge`` and Wallet Hardware public key.
-  * adds relevant information on the security of the device.
-  * sign the Key Attestation with an OEM certificate which in addition to certifying the integrity of the Wallet Instance also certifies that the Wallet Hardware Keys is secure stored by the OS (hardware backed).
+* Creates a Key Attestation that is linked with the provided "challenge" and the public key of the Wallet Hardware.
+* Incorporates information pertaining to the device's security.
+* Uses an OEM certificate to sign the Key Attestation, thereby not only verifying the integrity of the Wallet Instance but also confirming that the Wallet Hardware Keys are securely managed by the operating system (hardware-backed).
 
-**Step 9**: The Wallet Instance send the ``challenge`` with Key Attestation and Wallet Hardware Key Tag to the Wallet Provider Backend in order to register the Wallet Instance identified by the Wallet Hardware Key public key.
+**Step 9**: The Wallet Instance sends the ``challenge`` with Key Attestation and Wallet Hardware Key Tag to the Wallet Provider Backend in order to register the Wallet Instance identified by the Wallet Hardware Key public key.
 
 .. note::
 
@@ -139,7 +141,7 @@ Wallet Instance initialization and registration
   2. It MUST validate the ``key_attestation`` as defined by the device manufacturers' guidelines.
   3. It MUST verify that the device in use has no security flaws and reflects the minimum security requirements defined by the Wallet Provider.
   4. If these checks are passed, it MUST register the Wallet Instance, keeping the Wallet Hardware Key Tag and all useful information related to the device.
-  5. It SHULD associate the Wallet Instance with a specific user uniquely identified within the Wallet Provider's systems. This will be useful for the lifecycle of the Wallet Instance and for a future revocation.
+  5. It SHOULD associate the Wallet Instance with a specific user uniquely identified within the Wallet Provider's systems. This will be useful for the lifecycle of the Wallet Instance and for a future revocation.
 
 .. code-block:: http
 
@@ -153,11 +155,11 @@ If any errors occur during the Wallet Instance registration, the Wallet Provider
 
 **Steps 13-14**: The Wallet Instance has been initialized and becomes operational.
 
-.. note:: **Threat Model:** Although the registration endpoint does not require any authentication, it is protected by the presence of the ``key_attestation`` which, if validated correctly, only allows the registration of valid and intact instances of the app. Any other claims sent will not be validated and therefore the endpoint will return an error. The presence of a ``challenge`` also avoids reply attacks. Finally, the integrity of the ``challenge`` and the ``hardware_key_tag`` is guaranteed by the signature present within the ``key_attestation``.
+.. note:: **Threat Model**: While the registration endpoint does not necessitate any client authentication, it is safeguarded through the use of `key_attestation`. Proper validation of this attestation permits only the registration of authentic and unaltered app instances. Any other claims submitted will not undergo validation, leading the endpoint to respond with an error. Additionally, the inclusion of a challenge helps prevent replay attacks. The authenticity of both the challenge and the ``hardware_key_tag`` is ensured by the signature found within the ``key_attestation``.
 
 
-Wallet Attestation acquisition
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Wallet Attestation Issuance
+~~~~~~~~~~~~~~~~~~~~~
 
 This section describes the Wallet Attestation format and how the Wallet Provider issues it.
 
@@ -166,16 +168,16 @@ This section describes the Wallet Attestation format and how the Wallet Provider
    :alt: The figure illustrates the sequence diagram for issuing a Wallet Attestation, with the steps explained below.
    :target: https://www.plantuml.com/plantuml/uml/VLHFJzjE4BtlfnZ1uGTHVfTAxG6f5OXIe5GL0bekID7O7knfd5rtT-oKVlhEEdySXsqFbbZspNjltixaD0XwQHUrmLQSRHSPULDnGV3id6Jkb_clKG3dtA0LOp0Nv-7WMo1_01YW3OhVGS318zOr2LnRPROvzIXi6XYZFbB7EIbAgFGiBt1FlkCD72N0OMWysxBqH3QfSEjTfqOzP9ZFoHPzQPRFZJ7HrVyVLFK4xkXdIq40mT8IN4CUXPq5gL2UhDTRzgIIC9ciUSz4jA17JIQnOUvGAFPWz5lJdbUKpu6VXx8hzCKIFS4DlOJ915X9E-GQivhCJkKbsUWXQbgWfgA57ckOqmiqo5u9Fp_UgB3nrgciwyX7xQbs1eTVhY-l7YxlBYw-cfM3_InKDMO5xbax9FX4nQPXj0MuJ90ji0HOa621WaQJwvNCsgJgH9EYHl8gijkITdE82UlN0uTkm5a2uGN5YTWhZUXry-EBWaQi9XLJBAcPhCoYsrc5eT9mCS3zrTcRj--EjdnJQDgivdpsOpa_JZ6bdqh9RjtjapvrjVxlB71fKLfFUlSUukbety8KbZtLR5kaxpSJBBVAAE44ohNqTipFGY0lx5up7fjOCkJ4cv8PRchKJhAlrtExdVebI_KtiYcaUvwENsdwP9F1mGEMA_2GkpgCH5JqmiDqRuTwcB1xiiK_d8_dRLY5U4olGbp6lT-Uk0riMHXh_ar5lmAT_bsODh0j8TMLODdZqjaCspAimFV8Y9AQ-Z4W_H1fQ5e-ZTHeLrEySttkQNNvEkBnHgOGYTNSEMkPETKSsaNz1m00
 
-**Step 1:**: The user requests a new operation which requires obtaining a Wallet Attestation.
+**Step 1:**: The user initiates a new operation that necessitates the acquisition of a Wallet Attestation.
 
 **Steps 2-3:**: The Wallet Instance check if a Wallet Hardware Key exist and generates an ephemeral asymmetric key pair.
 
-  1. It MUST ensure that Wallet Hardware Keys exist. If they do not exist, it is necessary to reinitialize the wallet.
+  1. It MUST ensure that Wallet Hardware Keys exist. If they do not exist, it is necessary to reinitialize the Wallet.
   2. It MUST generates an ephemeral asymmetric key pair whose public key will be linked with the Wallet Attestation.
   3. it MUST check if Wallet Provider is part of the federation and obtain its metadata.
 
 
-**Steps 4-6:**: The Wallet Instance request and receive a one time ``challenge`` from the Wallet Provider Backend. The ``challenge`` is a ``nonce``, which MUST be unpredictable and it is the primary countermeasure against replay attack. The value of the ``nonce`` returned by the backend must be generated in such a way as to guarantee that it can only be used once and in a pre-established time interval.
+**Steps 4-6:**: The Wallet Instance solicits a one-time "challenge" from the Wallet Provider Backend. This "challenge" takes the form of a "nonce," which is required to be unpredictable and serves as the main defense against replay attacks. The backend must produce the "nonce" in a manner that ensures its single-use within a predetermined time frame.
 
 .. code-block:: http
 
@@ -191,10 +193,10 @@ This section describes the Wallet Attestation format and how the Wallet Provider
       "nonce": "d2JhY2NhbG91cmVqdWFuZGFt"
     }
 
-**Step 7**: The Wallet Instance:
+**Step 7**: The Wallet Instance performs the following actions:
 
-  * generate a ``client_data`` which is a JSON containing ``challenge`` and ephemeral public ``jwk``.
-  * generate a ``client_data_hash`` as SHA256 of ``client_data``.
+  * Creates a ``client_data``, a JSON structure that includes the challenge and the ephemeral public ``jwk``.
+  * Computes a ``client_data_hash`` by applying the SHA256 algorithm to the ``client_data``.
 
 Below a non-normative example of the ``client_data``.
 
@@ -211,11 +213,11 @@ Below a non-normative example of the ``client_data``.
       }
   }
 
-**Steps 8-10**: The Wallet Instance:
+**Steps 8-10**: The Wallet Instance takes the following steps:
 
-  * generate an ``hardware_signature`` signing ``client_data_hash`` with Wallet Hardware private key. It will be used as a **PoP** of the Wallet Hardware Keys.
-  * ask to Device Integrity Service to generate an ``integrity_assertion`` bounded with ``client_data_hash``.
-  * obtain from Device Integrity Service an ``integrity_assertion`` signed by OEM.
+  *  Produces an hardware_signature by signing the ``client_data_hash`` with the Wallet Hardware's private key, serving as a Proof of Possession (PoP) for the Wallet Hardware Keys.
+  *  Requests the Device Integrity Service to create an ``integrity_assertion`` linked to the ``client_data_hash``.
+  *  Receives a signed ``integrity_assertion`` from the Device Integrity Service, authenticated by the OEM.
 
 .. note:: ``integrity_assertion`` is a custom payload generated by Device Integrity Service, signed by device OEM and encoded in base64 to have uniformity between different devices.
 
@@ -230,7 +232,7 @@ Below an non-normative example of the Wallet Attestation Request JWT without enc
   {
     "alg": "ES256",
     "kid": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c",
-    "typ": "var+jwt"
+    "typ": "war+jwt"
   }
   .
   {
@@ -280,7 +282,7 @@ encoded in ``application/x-www-form-urlencoded`` format:
     grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
     &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6ImtoakZWTE9nRjNHeG...redacted
 
-**Steps 13-17**: The Wallet Provider backend validate the Wallet Attestation Request and if it passes the checks, a Wallet Attestation is issued:
+**Steps 13-17**: The Wallet Provider's backend assesses the Wallet Attestation Request and issues a Wallet Attestation, if the requirements described below are satisfied:
 
     1. It MUST check the Wallet Attestation Request contains all the defined parameters according to :ref:`Table of the Wallet Attestation Request parameters <table_wallet_attestation_request_claim>`.
     2. It MUST verify that the signature of the received Wallet Attestation Request is valid and associated with public ``jwk``.