chore: Adds some details to the Key Attestation (#375)

* Add defined terms and some minor fix

* Apply suggestions from code review

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

* move to commond definitions

* Update docs/en/defined-terms.rst

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

* Update wallet-attestation.rst

* Update relying-party-solution.rst

---------

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

docs/common/common_definitions.rst

@@ -9,7 +9,7 @@
 
 .. |check-icon| image:: ../../images/Eo_circle_green_checkmark.svg
    :width: 25
-   
+
 .. |uncheck-icon| image:: ../../images/Eo_circle_red_letter-x.svg
    :width: 25
 
@@ -62,4 +62,6 @@
 .. _OAUTH-MULT-RESP-TYPE: https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html
 .. _SELECTIVE-DISCLOSURE-JWT: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-selective-disclosure-jwt-10
 .. _OAUTH-ATTESTATION-CLIENT-AUTH: https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/03/
-
+.. _Key Attestation: https://developer.android.com/privacy-and-security/security-key-attestation#attestation-v4
+.. _Device Check: https://developer.apple.com/documentation/devicecheck
+.. _attestKey: https://developer.apple.com/documentation/devicecheck/dcappattestservice/attestkey:clientdatahash:completionhandler:

docs/en/defined-terms.rst

@@ -24,7 +24,7 @@ Below are the description of acronyms and definitions which are useful for furth
      - Notes
    * - User
      - A natural or legal person using an EUDI Wallet. [ARF v1.3]
-     - -
+     -
    * - User Attribute
      - A feature, characteristic or quality of a natural or legal person or of an entity, in electronic form. [ARF v1.3]
      - Other alternative terms: User Claim
@@ -60,16 +60,16 @@ Below are the description of acronyms and definitions which are useful for furth
      - Differences with ARF: added a sentence on proximity supervised scenarios. Other alternative terms: Verifier App
    * - Verifier
      - A natural person or legal person using an RP Instance. [New]
-     - 
+     -
    * - Trust
      - Trust is the confidence in the security, reliability, and integrity of entities (such as systems, organizations, or individuals) and their actions, ensuring that they will operate as expected in a secure and predictable manner. It is often established through empirical proof, such as past performance, security certifications, or transparent operational practices, which demonstrate a track record of adherence to security standards and ethical conduct. [Revised from ARF v1.3]
-     - 
+     -
    * - Trust Framework
      - A legally enforceable set of operational and technical rules and agreements that govern a multi-party system designed for conducting specific types of transactions among a community of participants and bound by a common set of requirements. [ARF v1.3]
-     - 
+     -
    * - Trust Model
      - Collection of rules that ensure the legitimacy of the components and the entities involved in the EUDI Wallet ecosystem. [ARF v1.3]
-     - 
+     -
    * - Trusted List
      - Repository of information about authoritative entities in a particular legal or contractual context which provides information about their current and historical status. It serves as the bedrock of trust, acting as federative sources that publish the crucial information about root entities within the ecosystem. [Revised from ARF v1.3]
      - Differences with ARF: added the last sentence
@@ -78,7 +78,7 @@ Below are the description of acronyms and definitions which are useful for furth
      - ARF: Registrar
    * - Conformity Assessment Body (CAB)
      - A conformity assessment body as defined in Article 2, point 13, of Regulation (EC) No 765/2008, which is accredited in accordance with that Regulation as competent to carry out conformity assessment of a qualified trust service provider and the qualified trust services it provides, or as competent to carry out certification of European Digital Identity Wallets or electronic identification means. [ARF v1.3]
-     - 
+     -
    * - National Accreditation Bodies (NAB)
      - A body that performs accreditation with authority derived from a Member State under Regulation (EC) No 765/2008. [ARF v1.3]
      - Other alternative terms: Accreditation Authority
@@ -90,16 +90,16 @@ Below are the description of acronyms and definitions which are useful for furth
      - Other alternative terms: Verifiable Attestation, Access Certificate
    * - Trust Relationship
      - Positive outcome of Trust Evaluation, which produces a reliable relationship between Organizational Entities, where one Organizational Entity trusts the other to securely handle data, execute transactions, or perform actions on its behalf.
-     - 
+     -
    * - Metadata
      - Digital artifact that contains all the required information about an Organizational Entity, e.g., protocol related endpoints and the Organizational Entity’s cryptographic public keys (for the complete list check requirement “Metadata Content”).
-     - 
+     -
    * - Policy Language
      - A formal language used to define security, privacy, and identity management policies that govern interactions and transactions within a Trust Framework. This language allows for the clear and unambiguous expression of rules and conditions, facilitating the automation of processes and interoperability among different systems and organizations.
-     - 
+     -
    * - Registration Process
      - Process performed by a Registration Authority verifying necessary information to ensure Organizational Entity eligibility and compliance with the relevant rules and standards. The main goal of the Registration Process is for the Organizational Entity to receive one or more Trust Assertions to be used for the Trust Evaluation processes.
-     - 
+     -
    * - Accreditation Process
      - Process performed by the National Accreditation Body to accreditate CABs. As a result of the Accreditation Process, a NAB issues an accreditation certificate to a CAB.
      - Currently, out of scope of the Trust Model requirements
@@ -108,7 +108,7 @@ Below are the description of acronyms and definitions which are useful for furth
      - Currently, out of scope of the Trust Model requirements
    * - Notification Process
      - Process defining how information is transferred to the European Commission and the inclusion of an entity in the Trusted List.
-     - 
+     -
    * - Supervision Process
      - Process performed by a Supervisory Body to review and ensure proper functioning of the Wallet Provider and other relevant actors.
      - Currently, out of scope of the Trust Model requirements
@@ -118,7 +118,7 @@ Below are the description of acronyms and definitions which are useful for furth
    * - Wallet Attestation
      - Verifiable Attestation, issued by the Wallet Provider, that proves the security compliace of the Wallet Instance.
      -
-   * - Wallet Secure Cryptographic Device
+   * - Wallet Secure Cryptographic Device (WSCD)
      - Hardware-backed secure environment for creating, storing, and/or managing cryptographic keys and data. A WSCD MAY implement an association proof in different ways. This largely depends on the implementation of the WSCD for example: remote HSM, external smart card, internal UICC, internal native cryptographic hardware, such as the iOS Secure Enclave or the Android Hardware Backed Keystore or StrongBox
      -
    * - Credential Status Attestation
@@ -134,7 +134,7 @@ Below are the description of acronyms and definitions which are useful for furth
      - A unique identifier created by the operating system for the Cryptographic Hardware Keys, utilized to gain access to the private key stored in the hardware.
      -
    * - Key Attestation
-     - 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.
+     - 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. Its content is therefore defined by the operating system manufacturer. For Google Android, the term Key Attestation refers to the Strongbox Key Attestation feature. For Apple iOS, the reference is to the `Device Check`_ service, specifically the `attestKey`_ feature.
      -
    * - 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.

docs/en/relying-party-solution.rst

@@ -11,7 +11,7 @@ This section describes how a remote Relying Party or a Verifier App requests to
 
 In this section the following flows are described:
 
-- :ref:`Remote Flow`, where the User presents a Credential to a remote Relying Party according to `OpenID4VP <https://openid.net/specs/openid-4-verifiable-presentations-1_0.html>`_ Draft 20. In this scenario the user-agent and the Wallet Instance can be used in the same device (**Same Device Flow**), or in different devices (**Cross Device Flow**).
+- :ref:`Remote Flow`, where the User presents a Credential to a remote Relying Party according to `OpenID4VP`_ Draft 20. In this scenario the user-agent and the Wallet Instance can be used in the same device (**Same Device Flow**), or in different devices (**Cross Device Flow**).
 - :ref:`Proximity Flow`, where the User presents a Credential to a Verifier App according to ISO 18013-5. The User interacts with a Verifier using proximity connection technologies such as QR Code and Bluetooth Low Energy (BLE).
 
 .. include:: remote-flow.rst

docs/en/wallet-attestation.rst

@@ -154,6 +154,7 @@ Below is a non-normative example of the request.
 
 .. note::
   It is not necessary to send the Wallet Hardware public key because it is already included in the ``key_attestation``.
+  As seen in the previous steps, the Device Integrity Service (DIS) creates a Key Attestation linked to the provided "challenge" and the public key of the Wallet Hardware. This process eliminates the need to send the Wallet Hardware public key directly, as it is already included in the key attestation. The ``hardware_key_tag`` serves as a reference or identifier for the corresponding Cryptographic Hardware key stored by the Wallet Provider. Therefore, the Wallet Provider can associate the received ``hardware_key_tag`` with the appropriate Cryptographic Hardware key in its storage.
 
 .. warning::
   During the registration phase of the Wallet Instance with the Wallet Provider it is also necessary to associate it with a specific user
@@ -311,7 +312,7 @@ encoded in ``application/x-www-form-urlencoded`` format:
     3. It MUST verify that the ``challenge`` was generated by  Wallet Provider and has not already been used.
     4. It MUST check that there is a Wallet Instance registered with that ``hardware_key_tag`` and that it is still valid.
     5. It MUST reconstruct the ``client_data`` via the ``challenge`` and the ``jwk`` public key, to validate ``hardware_signature`` via the Cryptographic Hardware Key public key registered and associated with the Wallet Instance.
-    6. It MUST validate the ``integrity_assertion`` as defined by the device manufacturers' guidelines.
+    6. It MUST validate the ``integrity_assertion`` as defined by the device manufacturers' guidelines. The list of checks that the Wallet Provider MUST perform are defined by the operating system manufacturers documentation.
     7. It MUST verify that the device in use has no security flaws and reflects the minimum security requirements defined by the Wallet Provider.
     8. It MUST check that the URL in ``iss`` parameter is equal to the URL identifier of Wallet Provider.
 
@@ -369,7 +370,7 @@ Below an non-normative example of the Wallet Attestation without encoding and si
     "exp": 1687288395
   }
 
-**Step 18**: The response is returned by the Wallet Provider. If successful, the HTTP response code MUST be set to 200 OK and contain the Wallet Attestation signed by the Wallet Provider. The Wallet Instance therefore performs security and integrity verification about the Wallet Attestation. 
+**Step 18**: The response is returned by the Wallet Provider. If successful, the HTTP response code MUST be set with the value ``200 OK`` and contain the Wallet Attestation signed by the Wallet Provider. The Wallet Instance therefore performs security, integrity and trust verification about the Wallet Attestation and its issuer.
 
 
 Below is a non-normative example of the response.
@@ -379,7 +380,7 @@ Below is a non-normative example of the response.
     HTTP/1.1 200 OK
     Content-Type: application/jwt
 
-    eyJhbGciOiJFUzI1NiIsInR5cCI6IndhbGx ... 
+    eyJhbGciOiJFUzI1NiIsInR5cCI6IndhbGx ...
 
 
 .. _table_wallet_attestation_request_claim:
@@ -606,7 +607,6 @@ To allow the User to revoke the Wallet Instance, the Wallet Provider (WP) **MUST
 .. _RFC 7523 section 4: https://www.rfc-editor.org/rfc/rfc7523.html#section-4
 .. _RFC 8414 section 2: https://www.rfc-editor.org/rfc/rfc8414.html#section-2
 .. _Wallet Provider metadata: wallet-solution.html#wallet-provider-metadata
-.. _Key Attestation: https://developer.android.com/privacy-and-security/security-key-attestation
 .. _Play Integrity API: https://developer.android.com/google/play/integrity?hl=it
 .. _DeviceCheck: https://developer.apple.com/documentation/devicecheck
 .. _OAuth 2.0 Nonce Endpoint: https://datatracker.ietf.org/doc/draft-demarco-oauth-nonce-endpoint/