From 426708d69f17e4e7258fefeff3118e91ea8489bc Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Tue, 4 Jul 2023 11:28:53 +0200 Subject: [PATCH 1/7] editorial: wallet instance attestation and solution --- docs/en/defined-terms.rst | 2 ++ docs/en/wallet-instance-attestation.rst | 13 ++++++++----- docs/en/wallet-solution.rst | 23 +++++++++++------------ 3 files changed, 21 insertions(+), 17 deletions(-) diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index ed1ee55fe..2df421bfe 100644 --- a/docs/en/defined-terms.rst +++ b/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 diff --git a/docs/en/wallet-instance-attestation.rst b/docs/en/wallet-instance-attestation.rst index 06a3be6dd..70efdcc26 100644 --- a/docs/en/wallet-instance-attestation.rst +++ b/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. The Wallet Instance Attestation has +the same technical format and content as other attestations and +MUST contain at the Wallet Instance public key. + +The Wallet Instance Attestation attests the **authenticity, +integrity, security, privacy and trust** regarding a specific Wallet Instance. General Properties diff --git a/docs/en/wallet-solution.rst b/docs/en/wallet-solution.rst index 072d8ed87..bc23e4f37 100644 --- a/docs/en/wallet-solution.rst +++ b/docs/en/wallet-solution.rst @@ -7,24 +7,23 @@ 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. @@ -32,7 +31,7 @@ The Wallet Instance establishes the trust within the Wallet ecosystem by consist 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 `_ for extended definitions and details. ² Wallet Instance states adhere to the EUDI Wallet Architecture and Reference Framework, as defined `here `_. From 34d6a2adbccad55749eae7edd2f0da70ca793817 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Tue, 4 Jul 2023 12:25:41 +0200 Subject: [PATCH 2/7] fix: doc8 on issuance --- docs/en/pid-issuing.rst | 2 +- docs/en/wallet-solution.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/pid-issuing.rst b/docs/en/pid-issuing.rst index b48cb4a1b..6feca7aaa 100644 --- a/docs/en/pid-issuing.rst +++ b/docs/en/pid-issuing.rst @@ -51,7 +51,7 @@ The PID Issuing 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 withing the section `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 withing the section `Entity Configuration Credential Issuer`_. **Steps 5-6:** The Wallet Instance creates a fresh 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 its request using its attested private key. A standard OAuth2 client authentication method must be involved, since in this flow the pushed authorization endpoint is a protected endpoint. The client authentication can 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 types of the credentials when requesting authorization for the PID issuance. diff --git a/docs/en/wallet-solution.rst b/docs/en/wallet-solution.rst index bc23e4f37..328cf07be 100644 --- a/docs/en/wallet-solution.rst +++ b/docs/en/wallet-solution.rst @@ -31,7 +31,7 @@ The Wallet Instance establishes the trust within the Wallet ecosystem by consist 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 From f247d6ecb2ad99ade03af51b24fbf264c0f6c041 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Tue, 4 Jul 2023 12:33:17 +0200 Subject: [PATCH 3/7] fix: typo --- docs/en/pid-issuance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/pid-issuance.rst b/docs/en/pid-issuance.rst index a12b069ec..25f58de87 100644 --- a/docs/en/pid-issuance.rst +++ b/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 withing the section `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. From e680d18ebfc62e0c896dd851abe9d85a47da9abb Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Tue, 4 Jul 2023 12:34:41 +0200 Subject: [PATCH 4/7] fix: typo --- docs/en/wallet-instance-attestation.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/en/wallet-instance-attestation.rst b/docs/en/wallet-instance-attestation.rst index 70efdcc26..64e18f325 100644 --- a/docs/en/wallet-instance-attestation.rst +++ b/docs/en/wallet-instance-attestation.rst @@ -7,12 +7,12 @@ Wallet Instance Attestation 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. The Wallet Instance Attestation has -the same technical format and content as other attestations and -MUST contain at the Wallet Instance public key. - -The Wallet Instance Attestation attests the **authenticity, +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 From 1779b19fda03ca6a4a4d4a0f051befc0f5ff0069 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Tue, 4 Jul 2023 14:10:57 +0200 Subject: [PATCH 5/7] Update docs/en/wallet-instance-attestation.rst Co-authored-by: Riccardo Iaconelli --- docs/en/wallet-instance-attestation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/wallet-instance-attestation.rst b/docs/en/wallet-instance-attestation.rst index 64e18f325..4d2b5e7f6 100644 --- a/docs/en/wallet-instance-attestation.rst +++ b/docs/en/wallet-instance-attestation.rst @@ -6,7 +6,7 @@ Wallet Instance Attestation +++++++++++++++++++++++++++ The Wallet Instance Attestation contains data about the Wallet Provider, -the Wallet Solution, the Wallet Instance and the security level of the device +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. From a4caacae09fec4042b2d4de7a2a115e8a70b322e Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Tue, 4 Jul 2023 14:12:45 +0200 Subject: [PATCH 6/7] fix: typo in wallet instance att --- docs/en/wallet-instance-attestation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/wallet-instance-attestation.rst b/docs/en/wallet-instance-attestation.rst index 4d2b5e7f6..640eaf55e 100644 --- a/docs/en/wallet-instance-attestation.rst +++ b/docs/en/wallet-instance-attestation.rst @@ -616,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. From 56dfacfca28dfbe932547f59c150b205acf72f02 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Tue, 4 Jul 2023 16:20:21 +0200 Subject: [PATCH 7/7] fix: metadata role wallet_verifier to wallet_relying_party --- 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 9e01e00ba..42d398975 100644 --- a/docs/en/relying-party-solution.rst +++ b/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",