From 99662bcf8c2b26025c1a8e65b92b010619402fca Mon Sep 17 00:00:00 2001 From: grausof Date: Tue, 30 Jul 2024 16:02:31 +0200 Subject: [PATCH 1/6] Add defined terms and some minor fix --- docs/en/defined-terms.rst | 30 +++++++++++++++++------------- docs/en/wallet-attestation.rst | 12 +++++++++--- 2 files changed, 26 insertions(+), 16 deletions(-) diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index bcb98e62..85139ca9 100644 --- a/docs/en/defined-terms.rst +++ b/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 Android we are referring to the term Key Attestation as the Strongbox `Key Attestation`_ feature. For iOS instead we refer to the `Device Check`_ service and in particular to 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. @@ -193,3 +193,7 @@ Acronyms - Authenticator Assurance Level as defined in ``_ * - **WSCD** - Wallet Secure Cryptographic Device + +.. _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: \ No newline at end of file diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index 25bae668..5c08109a 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -154,6 +154,12 @@ 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 we have seen in the previous steps in fact, 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 +317,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. This check summarized here includes many checks that the wallet provider will have to perform and that are recommended by the operating system manufacturers. The formal checks to be performed can be found in the relevant 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 +375,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 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. Below is a non-normative example of the response. @@ -379,7 +385,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: From 2f6b952d2dfcbb25f2abf6a8bfaff540a304805c Mon Sep 17 00:00:00 2001 From: Francesco Grauso Date: Wed, 31 Jul 2024 11:08:08 +0200 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: Giuseppe De Marco --- docs/en/defined-terms.rst | 2 +- docs/en/wallet-attestation.rst | 11 +++-------- 2 files changed, 4 insertions(+), 9 deletions(-) diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index 85139ca9..49586945 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -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. Its content is therefore defined by the operating system manufacturer. For Android we are referring to the term Key Attestation as the Strongbox `Key Attestation`_ feature. For iOS instead we refer to the `Device Check`_ service and in particular to the `attestKey`_ feature. + - 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. diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index 5c08109a..ed46868f 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -154,12 +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 we have seen in the previous steps in fact, 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. + 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 @@ -317,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. This check summarized here includes many checks that the wallet provider will have to perform and that are recommended by the operating system manufacturers. The formal checks to be performed can be found in the relevant documentation. + 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. @@ -375,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. From a9afd3ee5d71776a6c18d26baed31917afef9ee4 Mon Sep 17 00:00:00 2001 From: grausof Date: Wed, 31 Jul 2024 11:12:11 +0200 Subject: [PATCH 3/6] move to commond definitions --- docs/common/common_definitions.rst | 6 ++++-- docs/en/defined-terms.rst | 4 ---- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/common/common_definitions.rst b/docs/common/common_definitions.rst index 9decff09..00e10e85 100644 --- a/docs/common/common_definitions.rst +++ b/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: diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index 85139ca9..5deb029c 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -193,7 +193,3 @@ Acronyms - Authenticator Assurance Level as defined in ``_ * - **WSCD** - Wallet Secure Cryptographic Device - -.. _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: \ No newline at end of file From c894d996c494b119626e934a551274c1693fc5ef Mon Sep 17 00:00:00 2001 From: Francesco Grauso Date: Wed, 31 Jul 2024 11:13:26 +0200 Subject: [PATCH 4/6] Update docs/en/defined-terms.rst Co-authored-by: Giuseppe De Marco --- docs/en/defined-terms.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index fbe4f1f6..3af74fda 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -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. 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. + - 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. From e58ae7a206a535f70bfc12fffd7fa2655ba2e1e7 Mon Sep 17 00:00:00 2001 From: grausof Date: Wed, 31 Jul 2024 11:14:43 +0200 Subject: [PATCH 5/6] Update wallet-attestation.rst --- docs/en/wallet-attestation.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index ed46868f..1f26beff 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -607,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/ From f6dff682c3bc20b57aa938f60c37071ba09b361e Mon Sep 17 00:00:00 2001 From: grausof Date: Wed, 31 Jul 2024 11:17:10 +0200 Subject: [PATCH 6/6] Update relying-party-solution.rst --- docs/en/relying-party-solution.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/relying-party-solution.rst b/docs/en/relying-party-solution.rst index 7f0c0da3..eabd1c45 100644 --- a/docs/en/relying-party-solution.rst +++ b/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 `_ 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