diff --git a/docs/common/standards.rst b/docs/common/standards.rst index dbe099738..c60f5b327 100644 --- a/docs/common/standards.rst +++ b/docs/common/standards.rst @@ -8,29 +8,27 @@ Technical References :header-rows: 0 * - `OIDC-FED`_ - - OpenID Connect Federation 1.0 + - OpenID Connect Federation 1.0. * - `OPENID4VCI`_ - - T\. Lodderstedt, K. Yasuda, T. Looker, "OpenID for Verifiable Credential Issuance", February 2023. + - T. Lodderstedt, K. Yasuda, T. Looker, "OpenID for Verifiable Credential Issuance", February 2023. * - `SD-JWT-VC`_ - - O\. Terbu, D.Fett, "SD-JWT-based Verifiable Credentials (SD-JWT VC)". + - O. Terbu, D.Fett, "SD-JWT-based Verifiable Credentials (SD-JWT VC)". * - `EIDAS-ARF`_ - - EUDI Wallet - Architecture and Reference Framework + - EUDI Wallet - Architecture and Reference Framework. * - `OPENID4VP`_ - - OpenID for Verifiable Presentations - draft 19 + - OpenID for Verifiable Presentations. * - `PresentationExch`_ - - Presentation Exchange 2.0 for Presentation Definition + - Presentation Exchange 2.0 for Presentation Definition. * - :rfc:`2119` - - Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels," BCP 14, RFC 2119, March 1997. + - Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels" BCP 14, RFC 2119, March 1997. * - :rfc:`2616` - Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” RFC 2616, June 1999. * - :rfc:`3339` - Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002. * - :rfc:`3986` - - Uniform Resource Identifier (URI): Generic Syntax - * - :rfc:`7009` - - Lodderstedt, T., Dronia, S., Scurtescu, M., “OAuth 2.0 Token Revocation,” RFC7009, August 2013. + - Uniform Resource Identifier (URI): Generic Syntax. * - :rfc:`7159` - - Bray, T., “The JavaScript Object Notation (JSON) Data Interchange Format,” RFC 7159, March 2014. + - Bray, T., “The JavaScript Object Notation (JSON) Data Interchange Format” RFC 7159, March 2014. * - :rfc:`7515` - Jones, M., Bradley, J. and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015. * - :rfc:`7516` @@ -42,7 +40,7 @@ Technical References * - :rfc:`7519` - Jones, M., Bradley, J. and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015. * - :rfc:`7638` - - Jones, M., Sakimura, N., “JSON Web Key (JWK) Thumbprint,”RFC7638, September 2015. + - Jones, M., Sakimura, N., “JSON Web Key (JWK) Thumbprint”, September 2015. * - :rfc:`7800` - Jones, M., Bradley, J. and H. Tschofenig, "Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)", RFC 7800, DOI 10.17487/RFC7800, April 2016. * - :rfc:`8174` @@ -52,8 +50,8 @@ Technical References * - `JARM`_ - Lodderstedt, T., Campbell, B., "JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)", November 2022. * - :rfc:`6749` - - The OAuth 2.0 Authorization Framework + - The OAuth 2.0 Authorization Framework. * - :rfc:`9449` - - D\. Fett, B. Campbell, J. Bradley, T. Lodderstedt, M. Jones, D. Waite, "OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)" + - D. Fett, B. Campbell, J. Bradley, T. Lodderstedt, M. Jones, D. Waite, "OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)". * - `OPENID4VC-HAIP`_ - - Lodderstedt, T., K. Yasuda, "OpenID4VC High Assurance Interoperability Profile with SD-JWT VC" + - Lodderstedt, T., K. Yasuda, "OpenID4VC High Assurance Interoperability Profile with SD-JWT VC". diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index 882588a08..66f729518 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -27,8 +27,6 @@ Below are the description of acronyms and definitions which are useful for furth - An entity accredited by the Federation Authority, responsible for managing the process of verification and certification of accreditation requirements for ecosystem roles. * - Digital Identity Provider - An entity, recognized and accredited by the State, responsible for identifying citizens for the issuance of an Electronic Identity Certificate. - * - Electronic Attestation of Identity - - Electronic attestation of attributes referring to master data already present in Italian digital identity systems. * - Digital Credential - An signed Credential whose integrity can be cryptographically verified using the public keys of its Issuer. It is also known as Credential. * - Federation Authority @@ -39,10 +37,18 @@ Below are the description of acronyms and definitions which are useful for furth - 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 Attestation - Verifiable Attestation, issued by the Wallet Provider, that proves the security compliace of the Wallet Instance. + * - Wallet Secure Cryptographic Device + - 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 - Verifiable Attestation proving that a related Digital Credential is not revoked. - * - Wallet Attestation Service - - Device manufacturer service that allows you to certify the authenticity of the mobile app (Wallet Instance). + * - Device Integrity Service + - 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. + * - Cryptographic Hardware Keys + - 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 Cryptographic 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. + * - Cryptographic Hardware Key Tag + - 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. * - 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 @@ -83,3 +89,7 @@ Acronyms - Application Programming Interface * - **LoA** - Level of Assurance + * - **AAL** + - Authenticator Assurance Level as defined in ``_ + * - **WSCD** + - Wallet Secure Cryptographic Device diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index abfde0b54..3448b4504 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -5,176 +5,247 @@ Wallet Attestation ++++++++++++++++++ -The Wallet Attestation containing details about the Wallet Instance and the device's security level where the Wallet Instance is installed. It generally attests the **authenticity**, **integrity**, **security**, **privacy**, and **trust** of a specific Wallet Instance. The Wallet Attestation MUST contain a Wallet Instance public key. - -General Properties ------------------- - -The Wallet Attestation: - -- MUST be issued and MUST be signed by Wallet Provider; -- MUST give all the relevant information to attests the **integrity** and **security** of the device where the Wallet Instance is installed. - -It is necessary for each Wallet Instance to obtain a Wallet Attestation before entering the Operational state. +Wallet Attestation contains information regarding the security level of the device hosting the Wallet Instance. It primarily certifies the **authenticity**, **integrity**, **security**, **privacy**, and **trustworthiness** of a particular Wallet Instance. The Wallet Attestation MUST contain a Wallet Instance public key. Requirements ------------ The following requirements for the Wallet Attestation are met: -1. The Wallet Attestation MUST use the signed JSON Web Token (JWT) format. -2. The Wallet Provider MUST offer a RESTful set of services for issuing the Wallet Attestations. -3. The Wallet Attestation MUST be securely bound to the Wallet Instance public key (**Holder Key Binding**). -4. The Wallet Attestation MUST be issued and signed by an accredited and reliable Wallet Provider, thereby providing integrity and authenticity to the attestation. -5. The Wallet Attestation MUST ensure the integrity and authenticity of the Wallet Instance, verifying that it was accurately created and provided by the Wallet Provider. -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. 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. - - -High-level Design ------------------ +- The Wallet Attestation MUST use the signed JSON Web Token (JWT) format; +- The Wallet Attestation MUST give all the relevant information to attests the **integrity** and **security** of the device where the Wallet Instance is installed. +- The Wallet Attestation MUST be issued and signed by an accredited and reliable Wallet Provider, thereby providing integrity and authenticity to the attestation. +- The Wallet Provider MUST ensure the integrity, authenticity, and genuineness of the Wallet Instance, preventing any attempts at manipulation or falsification by unauthorized third parties. +- The Wallet Attestation MUST have a mechanism in place for revoking the Wallet Instance, allowing the Wallet Provider to terminate service for a specific instance at any time. +- The Wallet Attestation MUST be securely bound to the Wallet Instance ephemeral public key. +- The Wallet Attestation MAY be usable multiple times during its validity period, allowing for repeated authentication and authorization without the need to request new attestations with each interaction. +- The Wallet Attestation MUST be short-lived and MUST have an expiration date time, after which SHOULD no longer be considered valid. +- The Wallet Attestation MUST NOT be issued by the Wallet Provider if the authenticity, integrity, and genuineness are not guaranteed. In this case, the Wallet Instance MUST be revoked. +- Each Wallet Instance SHOULD be able to request multiple attestations with different ephemeral 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 listed below). +- The Wallet Attestation MUST NOT contain any information that can be used to directly reference the User. +- The Wallet Instances MUST secure a Wallet Attestation as a prerequisite for transitioning to the Operational state, as defined by `ARF`_. +- Private keys MUST be generated and stored in the WSCD using at least one of the approaches listed below: + + - **Local Internal WSCD**: in this approach, the WSCD relies entirely on the device's native cryptographic hardware, such as the Secure Enclave on iOS devices or the Hardware Backed Keystore or Strongbox on Android devices. + - **Local External WSCD**: the WSCD is an hardware external to the User's device, such as a smart card compliant with _GlobalPlatform_ and supporting _JavaCard_. + - **Remote WSCD**: Here, the WSCD utilizes a remote Hardware Security Module (HSM). + + - **Local Hybrid WSCD**: the WSCD involves a pluggable internal hardware component within the User's device, such as an _eUICC_ that adheres to _GlobalPlatform_ standards and supports _JavaCard_. + - **Remote Hybrid WSCD**: the WSCD involves a local component mixed with a remote service. + +.. warning:: + At the current stage, the current implementation profile defined in this document supports only the **Local Internal WSCD**. Future versions of this specification MAY include other approaches depending on the required `AAL`. Static Component View -~~~~~~~~~~~~~~~~~~~~~ +--------------------- .. figure:: ../../images/static_view_wallet_instance_attestation.svg :name: Wallet Solution Schema :alt: The image illustrates the containment of Wallet Provider and Wallet Instances within the Wallet Solution, managed by the Wallet Provider. - :target: https://www.plantuml.com/plantuml/uml/XP4nJuSm44VtVehBdxbnPp2iRYx6qTHIjR7SaVQ0-EqzaICDgN4ZBxpqzTUXiCkyJCaupvJXzbH2le4hiCW7A7rsAGM6ETCQn-E7RMSloi0OJzDC691FeL1QE1BMWZBeraW2Mbv4wK8VQayPT5yX9TgCQPclpdy676lnGF0ZN93DyVs3xVsrhOU70hCi0_JshwHXFJp-Rg4dIuECo96moD7xeBQbUKBEbE0EPEwuEWx6N2zj_uXqU8wbhVMhD3tjbAX1BYIl_mq0 + :target: https://www.plantuml.com/plantuml/uml/VP8nJyCm48Lt_ugdTexOCw22OCY0GAeGOsMSerWuliY-fEg_9mrEPTAqw-VtNLxEtaJHGRh6AMs40rRlaS8AEgAB533H3-qS2Tu2zxPEWSF8TcrYv-mJzTOGNfzVnXXJ0wKCDorxydAUjMNNYMMVpug9OTrR7i22LlaesXlADPiOraToZWyBsgCsF-JhtFhyGyZJgNlbXVR1oX5R2YSoUdQYEzrQO1seLcfUeGXs_ot5_VzqYM6lQlRXMz6hsTccIbGHhGu2_hhfP1tBwHuZqdOUH6WuEmrKIeqtNonvXhq4ThY3Dc9xBNJv_rSwQeyfawhcZsTPIpKLKuFYSa_JyOPytJNk5m00 Dynamic Component View -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- -This section describes the Wallet Attestation format and how the Wallet Provider issues it. +The Wallet Attestation acquisition flow can be divided into two main phases. The first phase involves device initialization and registration, which occurs only during the initial launch of the Wallet Instance (after installation). The second phase pertains to the actual acquisition of the Wallet Attestation. -.. figure:: ../../images/dynamic_view_sequence_wallet_instance_attestation.svg - :name: Sequence Diagram for Wallet Attestation Request - :alt: The figure illustrates the sequence diagram for issuing a Wallet Attestation, with the steps explained below. - :target: https://www.plantuml.com/plantuml/ZP91RzH038NlyojCJwr4n7qFgrOSAf2G409wwSL9h60ryGmUpqRRNuyt6qBJe5MlzlFtx3TpcmtLoj27Tqcn6n2CuZEO5WfOB4ePQj8GagkuuOHYSFKZaru1PYZh-WFsFHby4eTAGvDavFzglceyS3jZndgjkKi9q8mSOnm5tEx0Cy_h8HIezaxUkHKROy_F1A_C7oKgAFqkJlcGb38vkL5gIKuJEOnSxSTw1_S-z6ef6CYmHSCmrfMhtEZBN84cYY4BI_U21dPCbD_34nqdJrOQlECLaZP55flzdFJJrtKIRKnDIpQN_RtjdeJKXHCr8MkUcsYsWs_dqq2Y7nky1DLvRguiVX-Lq3RnmDs_V1VMvuVl0HlZmsbWh5SHuGlzzHjWDwVizZwrlNWPwqWA2mdb3DVJsZUdIwh9rML6dR8TeVb5pHCevTAROy_jXPgv4xIYjBIMv53QgNtf-kMDBuishtT1tD8wHUUNBPwNlzi-YXAsHx08iJPa0Q5nzLjlITeoz7y0 +Wallet Instance Initialization and Registration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- **Message 1**: The User starts the Wallet Instance mobile app and gets authenticated to it. -- **Message 2**: The Wallet Instance verifies the Wallet Provider's trustworthiness by evaluating its Trust Chain. -- **Message 3-4**: The Wallet Instance retrieves the Wallet Provider metadata, including the list of supported algorithms, public keys, and endpoints. -- **Message 5**: The Wallet Instance generates a new key pair. -- **Message 6-7**: The Wallet Instance requests a ``nonce`` from the App Attestation Service. -- **Message 8**: The Wallet Instance creates a Wallet Attestation Request in JWS format, signed with the private key associated with the public key for which it request the attestation. -- **Message 9-13**: The Wallet Instance provides the Wallet Attestation Request to the Wallet Provider, which validates it and returns a signed attestation to the Wallet Instance. -- **Message 13-14**: The Wallet Instance receives the Wallet Attestation signed by the Wallet Provider and performs security and integrity verifications. -- **Message 15**: The Wallet Attestation is now ready for use. +.. figure:: ../../images/wallet_instance_initialization.svg + :name: Sequence Diagram for Wallet Instance Initialization + :alt: The figure illustrates the sequence diagram for initializa a Wallet Instance, with the steps explained below. + :target: https://www.plantuml.com/plantuml/uml/ZLFHRjD047o_hrYb3xHM-84yeA8Iqgf04IdmlBOtpYhEdRMt3eIlPy-cQMoPmeCZQszcTcOklewAeks-TjXgyEq-9t5RBWas8MWUVhfNZG6uu0QzEeU51e7PrqWo0upGseixGy3iEzOrATnvK_O5TIXi6XYYtj612pAKKYMiHrYJf4aFHurm4HjXNrL2v2StV9PmCAC2EHOxycL7pOkTSvM4je7WwoEqJV2mOOaAR8wCYSes2XlGBILZBaLu_SRU5j2L4PzEuB8d6k0g1US3Qa-nvm_ZPal53dW3Vmi4R7aEo3NcDJadFfX6E90aeRdPXOiFTwlRnzMNvVAJw-N60KqY5V1a-ZtPi8-1leIGAx87DkDxKYnHqLaTtIRdUg-sPm4hqyooOflKVKLPzXmgrMRF2UX9qZXu0kKzfGf6r8JkEnWTb3HGFLLrKZNyZHmR3PLWi-K2Rb7A7oW4ztICMMPPMRfaKOEy38T7h6ndlmGrBW1LAQeTNPvCpU5bWIkNgCzfqlXj9zELR8uYLvvAo8_miFnurkZQUXx6dq_oBSn_nPY-ZczOSuawke59m7Zt0BR-PvrnUB4FznEtQOVfYrd0w4Et5rOs9x-eFASP9VqTtRNzjFlwDm00 -Detailed Design ---------------- +**Step 1:**: The User starts the Wallet Instance mobile app for the first time. -The detailed design is explained below. +**Step 2:**: The Wallet Instance: -Wallet Attestation Request -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To obtain a Wallet Attestation from the Wallet -Provider it is necessary to send a Wallet Attestation -Request from the Wallet Instance containing the associated public key -, the ``nonce`` value provided by the App Attestation Service and a ``jti`` value. + * check if Device Integrity Service is available. + * check whether the device meets the minimum security requirements. -The Wallet Instance MUST do an HTTP request to the Wallet Provider's `token endpoint`_, -using the method `POST `__. +.. note:: -The **token** endpoint (as defined in `RFC 7523 section 4`_) requires the following parameters -encoded in ``application/x-www-form-urlencoded`` format: + **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`_. -* ``grant_type`` set to ``urn:ietf:params:oauth:grant-type:jwt-bearer``; -* ``assertion`` containing the signed JWT defined in the Section `Wallet Attestation Request`_. +**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. This endpoint is compliant with the specification `OAuth 2.0 Nonce Endpoint`_. -Below a non-normative example of the HTTP request. .. code-block:: http - POST /token HTTP/1.1 - Host: wallet-provider.example.org - Content-Type: application/x-www-form-urlencoded + GET /nonce HTTP/1.1 + Host: walletprovider.example.com - grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer - &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6ImtoakZWTE9nRjNHeGRxd2xVTl9LWl83NTVUT1ZEbmJIaDg2TW1KcHh2a1UifQ.eyJpc3MiOiAidmJlWEprc000NXhwaHRBTm5DaUc2bUN5dVU0amZHTnpvcEd1S3ZvZ2c5YyIsICJhdWQiOiAiaHR0cHM6Ly93YWxsZXQtcHJvdmlkZXIuZXhhbXBsZS5vcmciLCAianRpIjogImY1NjUyMDcyLWFiZWYtNDU5OS1iODYzLTlhNjkwNjA3MzJjYyIsICJub25jZSI6ICIuLi4uLiIsICJjbmYiOiB7Imp3ayI6IHsiY3J2IjogIlAtMjU2IiwgImt0eSI6ICJFQyIsICJ4IjogIjRITnB0SS14cjJwanlSSktHTW56NFdtZG5RRF91SlNxNFI5NU5qOThiNDQiLCAieSI6ICJMSVpuU0IzOXZGSmhZZ1MzazdqWEU0cjMtQ29HRlF3WnRQQklScXBObHJnIiwgImtpZCI6ICJ2YmVYSmtzTTQ1eHBodEFObkNpRzZtQ3l1VTRqZkdOem9wR3VLdm9nZzljIn19LCAiaWF0IjogMTY5MTQ4ODk2MiwgImV4cCI6IDE2OTE0OTYxNjJ9.Dg_yFaiv6lVftR3FFx0v5JW250mBgXLVP1j0ezZcHRyitqSY7xGmx4y-MGur93FAS85vf_Da-L-REVEltwU2Jw +.. code-block:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "nonce": "d2JhY2NhbG91cmVqdWFuZGFt" + } + +**Step 6**: The Wallet Instance, through the operating system, creates a pair of Cryptographic Hardware Keys and stores the corresponding Cryptographic Hardware Key Tag in local storage once the following requirements are met: + + 1. It MUST ensure that Cryptographic 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 Elliptic Curve keys (Cryptographic Hardware Keys) via a local WSCD. + 3. It SHOULD obtain a unique identifier (Cryptographic Hardware Key Tag) for the generated Cryptographic 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 Cryptographic 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 Cryptographic Hardware Key Tag in a local storage. + +.. note:: + + **WSCD:** The Wallet Instance MAY use a local WSCD for key generation on devices that support this feature. On Android devices, Strongbox is RECOMMENDED, Trusted Execution Environment (TEE) SHOULD be used only when Strongbox is unavailable. For iOS devices, Secure Elements (SE) SHOULD be used. Given that each OEM offers a distinct SDK for accessing the local WSCD, the discussion hereafter will address this topic in a general context. + + +**Step 7**: The Wallet Instance uses the Device Integrity Service, providing a "challenge" and the Cryptographic Hardware Key Tag to acquire the Key Attestation. + +.. note:: + + **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 object. Additionally, it offers the verifiable proof that a specific Wallet Instance is authentic, unaltered, and in its original state using a specialized signed document made for this scope. + + The service also incorporates details in the signed object, 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 performs the following actions: + +* 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 private key to sign the Key Attestation, therefore verifieable with the related OEM certificate, confirming that the Cryptographic Hardware Keys are securely managed by the operating system. + +**Step 9**: The Wallet Instance sends the ``challenge`` with Key Attestation and Cryptographic Hardware Key Tag to the Wallet Provider Backend in order to register the Wallet Instance identified with the Cryptographic Hardware Key public key. + +.. note:: + + The Key Attestation (``key_attestation``) MUST be encoded in base64. -The response is the `Wallet Attestation`_ in JWT format: .. code-block:: http - HTTP/1.1 201 OK - Content-Type: application/jwt + PUT /wallet-instance HTTP/1.1 + Host: walletprovider.example.com + Content-Type: application/json + + { + "challenge": "0fe3cbe0-646d-44b5-8808-917dd5391bd9", + "key_attestation": "o2NmbXRvYXBwbGUtYXBw... redacted", + "hardware_key_tag": "WQhyDymFKsP95iFqpzdEDWW4l7aVna2Fn4JCeWHYtbU=" + } + +.. note:: + It is not necessary to send the Wallet Hardware public key because it is already included in the ``key_attestation``. + +.. warning:: + During the registration phase of the Wallet Instance with the Wallet Provider it is also necessary to associate it with a specific user + uniquely identifiable by the Wallet Provider. This association is at the discretion of the Wallet PRovider and will not be addressed + within these guidelines as each Wallet Provider may or may not have a user identification system already implemented. + + +**Steps 10-12**: The Wallet Provider validates the ``challenge`` and ``key_attestation`` signature, therefore: + + 1. It MUST verify that the ``challenge`` was generated by Wallet Provider and has not already been used. + 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 Cryptographic Hardware Key Tag and all useful information related to the device. + 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 + + HTTP/1.1 201 Created + Content-Type: application/json + +If any errors occur during the Wallet Instance registration, the Wallet Provider MUST return an error response. The response MUST use the content type set to *application/json* and MUST include the following parameters: + + - *error*. The error code. + - *error_description*. Text in human-readable form providing further details to clarify the nature of the error encountered. + +**Steps 13-14**: The Wallet Instance has been initialized and becomes operational. + +.. 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 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 Issuance +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes the Wallet Attestation format and how the Wallet Provider issues it. + +.. figure:: ../../images/wallet_instance_acquisition.svg + :name: Sequence Diagram for Wallet Attestation acquisition + :alt: The figure illustrates the sequence diagram for issuing a Wallet Attestation, with the steps explained below. + :target: https://www.plantuml.com/plantuml/uml/VLJ1Jjj04BtlLupWK8ZIIwNsWDGAH2bGgWe1BHSaQsmFzZJEhhixTff-VMTD4YV6pS4IoxvvyzxRcPm6GI_Dl3BOYBFDF2LlIiu9dfsJrFqnRse5SCOrMZ46Ct4U3du4yWU00PgW-2q473nYLP70jLLccr67mhg6NTHdQZaZHGaLdcK9z-HRNiDH0Xo6shCj2azaHplSUjUgK0yfPZEoULUQPZDZJ5JrzfDsFO4x-jrG442mj01NaqTXPq5Ab2VhzPOzQKkOJ5QyPo9QqA4casYOMnIA7en-Azhpah8PyBEMdVjbBQxmM9USmHNwV86Uu8QMOJ81LkuMkSAq8hD5S4asIecjBL1TqboF5Sne2JMoLzwlZpVQttZhXC2rvAE4gHg4ms_NbrSFbtSN5z_DYv1X9DerHWRkMOqIVA5yxHjj3YuLP0ii0UOacAEWqG2xJcObKlj4aQ92iZAosuAsuuX1wzS1UpVWB87mdE9W34eZUcL-zoAd7LOp5bCigPYi955jKc8eDLmCS7zrzkxzXwCDtnJg9gquItujPiVZJ7jUJ3bltUsJFdov-cyIkB0eZIUz-mZnT3HKCeL5bt-oAT9dJ0IBZG2KS0B5Ii5cwCz282_iNZCUcrZInyNhaWJNDIfdrDxhATxim8Ab_1_P5COzJtSVQ_faz-K73rYyrFIle48Z7-LT_txMDoFUpzizsNoFWTtfwnSZ7iSN8sxeu0SfxWPR5iQA_rBUBKIhV-Uc2MmBs6DEiEZWuqdrAzJlnSz8Z39OXH70-BECGyVRZoDZmjrCzzVga5ukNoSzMDDnn61VjyzQPaurXsPU_GC0 + +**Step 1:**: The User initiates a new operation that necessitates the acquisition of a Wallet Attestation. + +**Steps 2-3:**: The Wallet Instance checks if a Cryptographic Hardware Key exists and generates an ephemeral asymmetric key pair. The Wallet Instance also: - eyJhbGciOiJFUzI1NiIsInR5cCI6IndhbGxldC1hdHRlc3RhdGlvbitqd3QiLCJraWQiOiI1dDVZWXBCaE4tRWdJRUVJNWlVenI2cjBNUjAyTG5WUTBPbWVrbU5LY2pZIiwidHJ1c3RfY2hhaW4iOlsiZXlKaGJHY2lPaUpGVXouLi42UzBBIiwiZXlKaGJHY2lPaUpGVXouLi5qSkxBIiwiZXlKaGJHY2lPaUpGVXouLi5IOWd3Il19.eyJpc3MiOiJodHRwczovL3dhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZyIsInN1YiI6InZiZVhKa3NNNDV4cGh0QU5uQ2lHNm1DeXVVNGpmR056b3BHdUt2b2dnOWMiLCJ0eXBlIjoiV2FsbGV0SW5zdGFuY2VBdHRlc3RhdGlvbiIsInBvbGljeV91cmkiOiJodHRwczovL3dhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZy9wcml2YWN5X3BvbGljeSIsInRvc191cmkiOiJodHRwczovL3dhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZy9pbmZvX3BvbGljeSIsImxvZ29fdXJpIjoiaHR0cHM6Ly93YWxsZXQtcHJvdmlkZXIuZXhhbXBsZS5vcmcvbG9nby5zdmciLCJhdHRlc3RlZF9zZWN1cml0eV9jb250ZXh0IjoiaHR0cHM6Ly93YWxsZXQtcHJvdmlkZXIuZXhhbXBsZS5vcmcvTG9BL2Jhc2ljIiwiY25mIjp7Imp3ayI6eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6IjRITnB0SS14cjJwanlSSktHTW56NFdtZG5RRF91SlNxNFI5NU5qOThiNDQiLCJ5IjoiTElablNCMzl2RkpoWWdTM2s3alhFNHIzLUNvR0ZRd1p0UEJJUnFwTmxyZyIsImtpZCI6InZiZVhKa3NNNDV4cGh0QU5uQ2lHNm1DeXVVNGpmR056b3BHdUt2b2dnOWMifX0sImF1dGhvcml6YXRpb25fZW5kcG9pbnQiOiJldWRpdzoiLCJyZXNwb25zZV90eXBlc19zdXBwb3J0ZWQiOlsidnBfdG9rZW4iXSwidnBfZm9ybWF0c19zdXBwb3J0ZWQiOnsiand0X3ZwX2pzb24iOnsiYWxnX3ZhbHVlc19zdXBwb3J0ZWQiOlsiRVMyNTYiXX0sImp3dF92Y19qc29uIjp7ImFsZ192YWx1ZXNfc3VwcG9ydGVkIjpbIkVTMjU2Il19fSwicmVxdWVzdF9vYmplY3Rfc2lnbmluZ19hbGdfdmFsdWVzX3N1cHBvcnRlZCI6WyJFUzI1NiJdLCJwcmVzZW50YXRpb25fZGVmaW5pdGlvbl91cmlfc3VwcG9ydGVkIjpmYWxzZSwiaWF0IjoxNjg3MjgxMTk1LCJleHAiOjE2ODcyODgzOTV9.tNvCyFPCL5tUi2NakKwdaG9xbrtWWl4djSRYRfHrF8NdmffdT044U55pRn35J2cl0LZxbesEDrfSAz2pllw2Ug - - -Below are described the JWT headers and the payload claims -of the `assertion` used in the request. - - -Assertion Header -^^^^^^^^^^^^^^^^ -+-----------------------------------+-----------------------------------+ -| **key** | **value** | -+-----------------------------------+-----------------------------------+ -| alg | Algorithm to verify the token | -| | signature (es. ES256). | -+-----------------------------------+-----------------------------------+ -| kid | Key id of the public key | -| | created by the Wallet Instance. | -+-----------------------------------+-----------------------------------+ -| typ | Media type, set to | -| | ``wiar+jwt``. | -+-----------------------------------+-----------------------------------+ - -Assertion Payload -^^^^^^^^^^^^^^^^^ - -+--------+-------------------------------------------------------------+ -| **key**| **value** | -+--------+-------------------------------------------------------------+ -|| iss || Thumbprint value | -|| || of the JWK of the Wallet Instance | -|| || for which the attestation is | -|| || being requested. | -+--------+-------------------------------------------------------------+ -|| aud || The public url of the Wallet | -|| || Provider. | -+--------+-------------------------------------------------------------+ -|| jti || Unique identifier of the request, according to | -|| || `RFC7519 `_.| -|| || | -+--------+-------------------------------------------------------------+ -|| nonce || The nonce value obtained from the | -|| || App Attestation Service. | -+--------+-------------------------------------------------------------+ -|| cnf || JSON object, according to | -|| || `RFC7800 `_ | -|| || containing the public part of an asymmetric key pair owned | -|| || by the Wallet Instance. | -+--------+-------------------------------------------------------------+ -|| iat || Unix timestamp of attestation request | -|| || issuance time. | -+--------+-------------------------------------------------------------+ -|| exp || Unix timestamp regarding the | -|| || expiration date time. | -+--------+-------------------------------------------------------------+ - - -Below a non-normative example of the Wallet Attestation -request where the decoded JWS headers and payload are separated by a comma: - -.. code-block:: javascript + 1. MUST ensure that Cryptographic Hardware Keys exist. If they do not exist, it is necessary to reinitialize the Wallet. + 2. MUST generates an ephemeral asymmetric key pair whose public key will be linked with the Wallet Attestation. + 3. MUST check if Wallet Provider is part of the federation and obtain its metadata. + + +**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 + + GET /nonce HTTP/1.1 + Host: walletprovider.example.com + +.. code-block:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "nonce": "d2JhY2NhbG91cmVqdWFuZGFt" + } + +**Step 7**: The Wallet Instance performs the following actions: + + * 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``. + +.. code-block:: json + + { + "challenge": "0fe3cbe0-646d-44b5-8808-917dd5391bd9", + "jwk": { + "crv": "P-256", + "kty": "EC", + "x": "4HNptI-xr2pjyRJKGMnz4WmdnQD_uJSq4R95Nj98b44", + "y": "LIZnSB39vFJhYgS3k7jXE4r3-CoGFQwZtPBIRqpNlrg", + "kid": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c" + } + } + +**Steps 8-10**: The Wallet Instance takes the following steps: + + * It produces an hardware_signature by signing the ``client_data_hash`` with the Wallet Hardware's private key, serving as a proof of possession for the Cryptographic Hardware Keys. + * It requests the Device Integrity Service to create an ``integrity_assertion`` linked to the ``client_data_hash``. + * It 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. + +**Steps 11-12**: The Wallet Instance: + * Constructs the Wallet Attestation Request in the form of a JWT. This JWT includes the ``integrity_assertion``, ``hardware_signature``, ``challenge``, ``wallet_hardware_key_tag``, and ``public_jwk``, and is signed using the private key from the initially generated ephemeral key pair. + * Submits the Wallet Attestation Request to the Wallet Provider's backend through the token endpoint. + +Below an non-normative example of the Wallet Attestation Request JWT without encoding and signature applied: + +.. code-block:: { "alg": "ES256", "kid": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c", - "typ": "wiar+jwt" + "typ": "war+jwt" } . { - "iss": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c", - "aud": "https://wallet-provider.example.org", - "jti": "6ec69324-60a8-4e5b-a697-a766d85790ea", - "nonce" : ".....", + "iss": "https://wallet-provider.example.org/instance/vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c", + "sub": "https://wallet-provider.example.org/", + "challenge": "6ec69324-60a8-4e5b-a697-a766d85790ea", + "hardware_signature": "KoZIhvcNAQcCoIAwgAIB...redacted", + "integrity_assertion": "o2NmbXRvYXBwbGUtYXBwYX...redacted", + "hardware_key_tag": "WQhyDymFKsP95iFqpzdEDWW4l7aVna2Fn4JCeWHYtbU=", "cnf": { "jwk": { "crv": "P-256", @@ -182,119 +253,56 @@ request where the decoded JWS headers and payload are separated by a comma: "x": "4HNptI-xr2pjyRJKGMnz4WmdnQD_uJSq4R95Nj98b44", "y": "LIZnSB39vFJhYgS3k7jXE4r3-CoGFQwZtPBIRqpNlrg", "kid": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c" - } + }, + "vp_formats_supported": { + "jwt_vc_json": { + "alg_values_supported": ["ES256K", "ES384"], + }, + "jwt_vp_json": { + "alg_values_supported": ["ES256K", "EdDSA"], + }, + }, }, "iat": 1686645115, "exp": 1686652315 } -Whose corresponding JWS is verifiable using the public part of an asymmetric -key pair owned by the Wallet Instance that has a key id which is the same -as the `kid` made available in the JWS header. +The Wallet Instance MUST do an HTTP request to the Wallet Provider's `token endpoint`_, +using the method `POST `__. +The **token** endpoint (as defined in `RFC 7523 section 4`_) requires the following parameters +encoded in ``application/x-www-form-urlencoded`` format: -Wallet Attestation -~~~~~~~~~~~~~~~~~~ +* ``grant_type`` set to ``urn:ietf:params:oauth:grant-type:jwt-bearer``; +* ``assertion`` containing the signed JWT of the Wallet Attestation Request. -The Wallet Attestation MUST be provisioned in JWT format, with -headers and payload claims are listed below. - -Header -^^^^^^ - -+-----------------------------------+-----------------------------------+ -| **key** | **value** | -+-----------------------------------+-----------------------------------+ -| alg | Algorithm to verify the token | -| | signature (es. ES256). | -+-----------------------------------+-----------------------------------+ -| kid | The key id of the key used by the | -| | Wallet Provider to sign the | -| | attestation. | -+-----------------------------------+-----------------------------------+ -| typ | Media type, set to | -| | `wallet-attestation+jwt`, | -| | according to | -| | [`OPENID4VC-HAIP`_] | -+-----------------------------------+-----------------------------------+ -| x5c | Array containing the X.509 | -| | chain | -| | of certificates used to attest | -| | the public key of the Wallet | -| | Provider. | -+-----------------------------------+-----------------------------------+ -| trust_chain | Array containing the Federation | -| | Trust Chain relating to the | -| | Wallet Provider. | -+-----------------------------------+-----------------------------------+ +.. code-block:: http -.. note:: + POST /token HTTP/1.1 + Host: wallet-provider.example.org + Content-Type: application/x-www-form-urlencoded + + grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer + &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6ImtoakZWTE9nRjNHeG... - One of the claims `trust_chain` and `x5c` MUST be provisioned. - If they are both provided, the related public key - MUST be the same in both `trust_chain` and `x5c`. - -Payload -^^^^^^^ - -+---------------------------+------------------------------------------------+ -| **key** | **value** | -+---------------------------+------------------------------------------------+ -|| iss || The public url of the Wallet Provider | -+---------------------------+------------------------------------------------+ -|| sub || Thumbprint value | -|| || of the JWK of the Wallet Instance | -|| || for which the attestation is | -|| || being issued. | -+---------------------------+------------------------------------------------+ -|| iat || Unix timestamp of attestation | -|| || issuance time. | -+---------------------------+------------------------------------------------+ -|| exp || Unix timestamp regarding the | -|| || expiration date time. | -|| || A good practice to avoid security | -|| || problems is to have a limited | -|| || duration of the attestation. | -+---------------------------+------------------------------------------------+ -|| aal || JSON String asserting the authentication level| -|| || of the Wallet and the key as asserted in | -|| || the cnf claim. | -+---------------------------+------------------------------------------------+ -|| cnf || This parameter contains the ``jwk`` | -|| || parameter | -|| || with the public key of the Wallet Instance | -|| || necessary for the Holder Key Binding. | -+---------------------------+------------------------------------------------+ -|| authorization_endpoint || URL of the SIOPv2 | -|| || Authorization Endpoint. | -+---------------------------+------------------------------------------------+ -|| response_types_supported || JSON array containing a list of | -|| || the OAuth 2.0 ``response_type`` values. | -+---------------------------+------------------------------------------------+ -|| response_modes_supported || JSON array containing a list of the OAuth 2.0 | -|| || "response_mode" values that this | -|| || authorization server supports. | -|| || `RFC 8414 section 2`_ | -+---------------------------+------------------------------------------------+ -|| vp_formats_supported || JSON object with name/value pairs, | -|| || identifying a Credential format supported | -|| || by the Wallet. | -+---------------------------+------------------------------------------------+ -|| request_object_signing || JSON array containing a list of the | -|| _alg_values_supported || JWS signing algorithms (alg values) | -|| || supported. | -+---------------------------+------------------------------------------------+ -|| presentation_definition || Boolean value specifying whether the | -|| _uri_supported || Wallet Instance supports the transfer of | -|| || ``presentation_definition`` by | -|| || reference. MUST set to `false`. | -+---------------------------+------------------------------------------------+ - -Below is an example of Wallet Attestation: - -.. code-block:: javascript +**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 `. + 2. It MUST verify that the signature of the received Wallet Attestation Request is valid and associated with public ``jwk``. + 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. + 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. + +If all checks are passed, Wallet Provider issues a Wallet Attestation with an expiration limited to 24 hours. + +Below an non-normative example of the Wallet Attestation without encoding and signature applied: + +.. code-block:: + + { "alg": "ES256", "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY", "trust_chain": [ @@ -343,9 +351,159 @@ Below is an example of Wallet Attestation: "exp": 1687288395 } +**Step 18**: The Wallet Instance receives the Wallet Attestation signed by the Wallet Provider and performs security and integrity verifications. + +.. code-block:: http + + HTTP/1.1 201 OK + Content-Type: application/jwt + + eyJhbGciOiJFUzI1NiIsInR5cCI6IndhbGx... redacted + + +.. _table_wallet_attestation_request_claim: + +Wallet Attestation Request +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The JOSE header of the Wallet Attestation Request JWT MUST contain: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **JOSE header** + - **Description** + - **Reference** + * - **alg** + - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms listed in the Section `Cryptographic Algorithms `_ and MUST NOT be set to ``none`` or any symmetric algorithm (MAC) identifier. + - :rfc:`7516#section-4.1.1`. + * - **kid** + - Unique identifier of the ``jwk`` inside the ``cnf`` claim of Wallet Instance as base64url-encoded JWK Thumbprint value. + - :rfc:`7638#section_3`. + * - **typ** + - It MUST be set to ``var+jwt`` + - + +The body of the Wallet Attestation Request JWT MUST contain: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Claim** + - **Description** + - **Reference** + * - **iss** + - Identifier of the Wallet Provider concatenated with thumbprint of the JWK in the ``cnf`` parameter. + - :rfc:`9126` and :rfc:`7519`. + * - **aud** + - It MUST be set to the identifier of the Wallet Provider. + - :rfc:`9126` and :rfc:`7519`. + * - **exp** + - UNIX Timestamp with the expiry time of the JWT. + - :rfc:`9126` and :rfc:`7519`. + * - **iat** + - UNIX Timestamp with the time of JWT issuance. + - :rfc:`9126` and :rfc:`7519`. + * - **challenge** + - Challenge data obtained from ``nonce`` endpoint + - + * - **hardware_signature** + - The signature of ``client_data`` obtained using Cryptographic Hardware Key base64 encoded. + - + * - **integrity_assertion** + - The integrity assertion obtained from the **Device Integrity Service** with the holder binding of ``client_data``. + - + * - **hardware_key_tag** + - Unique identifier of the **Cryptographic Hardware Keys** + - + * - **cnf** + - JSON object, containing the public part of an asymmetric key pair owned by the Wallet Instance. + - :rfc:`7800` + +.. _table_wallet_attestation_claim: + +Wallet Attestation +~~~~~~~~~~~~~~~~~~ + +The JOSE header of the Wallet Attestation JWT MUST contain: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **JOSE header** + - **Description** + - **Reference** + * - **alg** + - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms listed in the Section `Cryptographic Algorithms `_ and MUST NOT be set to ``none`` or any symmetric algorithm (MAC) identifier. + - :rfc:`7516#section-4.1.1`. + * - **kid** + - Unique identifier of the ``jwk`` inside the ``cnf`` claim of Wallet Instance as base64url-encoded JWK Thumbprint value. + - :rfc:`7638#section_3`. + * - **typ** + - It MUST be set to ``wallet-attestation+jwt`` + - `OPENID4VC-HAIP`_ + * - **trust_chain** + - Sequence of Entity Statements that composes the Trust Chain related to the Relying Party. + - `OIDC-FED`_ Section *3.2.1. Trust Chain Header Parameter*. + +The body of the Wallet Attestation JWT MUST contain: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Claim** + - **Description** + - **Reference** + * - **iss** + - Identifier of the Wallet Provider + - :rfc:`9126` and :rfc:`7519`. + * - **aud** + - Identifier of the Wallet Provider concatenated with thumbprint of the Wallet Instance. + - :rfc:`9126` and :rfc:`7519`. + * - **exp** + - UNIX Timestamp with the expiry time of the JWT. + - :rfc:`9126` and :rfc:`7519`. + * - **iat** + - UNIX Timestamp with the time of JWT issuance. + - :rfc:`9126` and :rfc:`7519`. + * - **cnf** + - JSON object, containing the public part of an asymmetric key pair owned by the Wallet Instance. + - :rfc:`7800` + * - **aal** + - JSON String asserting the authentication level of the Wallet and the key as asserted in the cnf claim. + - + * - **authorization_endpoint** + - URL of the Wallet Authorization Endpoint (Universal Link). + - + * - **response_types_supported** + - JSON array containing a list of the OAuth 2.0 ``response_type`` values. + - + * - **response_modes_supported** + - JSON array containing a list of the OAuth 2.0 "response_mode" values that this authorization server supports. + - :rfc:`8414` + * - **vp_formats_supported** + - JSON object with name/value pairs, identifying a Credential format supported by the Wallet. + - + * - **request_object_signing_alg_values_supported** + - JSON array containing a list of the JWS signing algorithms (alg values) supported. + - + * - **presentation_definition_uri_supported** + - Boolean value specifying whether the Wallet Instance supports the transfer of presentation_definition by reference. MUST be set to false. + - + .. _token endpoint: wallet-solution.html#wallet-attestation .. _Wallet Attestation Request: wallet-attestation.html#format-of-the-wallet-attestation-request .. _Wallet Attestation: wallet-attestation.html#format-of-the-wallet-attestation .. _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/ +.. _ARF: https://github.com/eu-digital-identity-wallet/eudi-doc-architecture-and-reference-framework diff --git a/docs/en/wallet-solution.rst b/docs/en/wallet-solution.rst index 4a2036b1f..31fd4893c 100644 --- a/docs/en/wallet-solution.rst +++ b/docs/en/wallet-solution.rst @@ -5,30 +5,32 @@ 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 a comprehensive product offered by the Wallet Provider to cater to the needs of Users in managing their digital assets securely. It 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 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[1]), 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[1]. Once a User installs the mobile app on their device, it is referred to such an installation as a Wallet Instance for the User. +The mobile app serves as the primary interface for Users, allowing them to access and interact with their digital Credentials conveniently. These are 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[1]. Once a User installs the mobile app on their device, it is referred to such an installation as a Wallet Instance for the User. By supporting the mobile app, the Wallet Provider plays a vital role in ensuring the security and reliability of the entire Wallet Solution, since it is responsible for issuing the Wallet Attestation, that is a cryptographic proof that allow the evaluation of the authenticity and the integrity of the Wallet Instance. +The Wallet Provider MUST offer a RESTful set of services for issuing the Wallet Attestations. Requirements -^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^ + +This section lists below the essential requirements that must be met by the Wallet Solution to ensure its functionality, security, and compliance with relevant standards and regulations. - **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 (Q)EAAs. - **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 and full control of their personal device. + Wallet Instance ^^^^^^^^^^^^^^^ -The Wallet Instance serves as a unique and secure device for authenticating 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 serves as a unique and secure device for authenticating the User within the Wallet ecosystem. It establishes a strong and reliable mechanismm for the User to engage 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 Attestation during interactions with other ecosystem actors such as PID Providers, (Q)EAA Providers, and Relying Parties. These verifiable attestations, provided by the Wallet Provider, reference the public part of the asymmetric cryptographic key owned by the Wallet Instance. Their purpose is to authenticate the Wallet Instance itself, ensuring its realiability when engaging with other ecosystem actors. +The Wallet Instance establishes the trust within the Wallet ecosystem by consistently presenting a Wallet Attestation during interactions with other ecosystem actors such as PID Providers, (Q)EAA Providers, and Relying Parties. These verifiable attestations, provided by the Wallet Provider, purpose to authenticate the Wallet Instance itself, ensuring its realiability 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)[3]. This ensures that only the User is allowed to access them, thus preventing unauthorized usage or tampering. For more detailed information, please refer to the `Wallet Attestation section`_ and the `Trust Model section`_ of this document. +To guarantee the utmost security, these cryptographic keys MUST be securely stored within the WSCD which MAY be internal (device's Trusted Execution Environment (TEE)[3]), external, or hybrid. This ensures that only the User is allowed to access them, thus preventing unauthorized usage or tampering. For more detailed information please refer to the `Wallet Attestation section`_ and the `Trust Model section`_ of this document. Wallet Instance Lifecycle ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -36,7 +38,7 @@ The Wallet Instance has three distinct states: Operational, Valid, and Deactivat Initialization Process ~~~~~~~~~~~~~~~~~~~~~~ -To activate the Wallet Instance, the Users MUST install the mobile wallet application on their device and open it. Furthermore, Users will be asked to set their preferred method of unlocking their device; this can be accomplished by entering a personal identification number (PIN) or by utilizing biometric authentication, such as fingerprint or facial recognition, according to their personal preferences and device's capabilities. +To activate the Wallet Instance, the Users MUST install the mobile Wallet application on their device and open it. Furthermore, Users will be asked to set their preferred method of unlocking their device; this can be accomplished by entering a personal identification number (PIN) or by utilizing biometric authentication, such as fingerprint or facial recognition, according to their personal preferences and device's capabilities. After completing these steps, the Wallet Instance sets the Operational state. @@ -44,16 +46,17 @@ Transition to Valid state ~~~~~~~~~~~~~~~~~~~~~~~~~ To transition from the Operational state to the Valid state, the Wallet Instance MUST obtain a valid Personal Identification (PID). Once a valid PID is acquired, the Wallet Instance becomes Valid. -In order to securely and unambiguously identify Users, the Wallet Instance adopts a Level of Assurance (LoA) 3 authentication, which guarantees a high level of confidence in the User's identity. The authentication method is chosen by the PID Provider from among the notified eID solutions at the national level. +To securely and unambiguously authenticate Users, the Wallet Instance necessitates a High Level of Assurance (LoA 3) for User authentication. The method to achieve this LoA is selected by the PID Provider based on the identity proofing method employed during the provisioning of the Digital Credential to the User. Furthermore, to store the acquired Digital Credential, the Wallet Instance MUST demonstrate to the Credential Issuer an adequate security compliance to maintain the Credential at the same LoA at which it was issued. Once the Wallet Instance is in the Operational state, Users can: - Obtain, view, and manage (Q)EAAs from trusted (Q)EAA Providers[1]; - Authenticate to Relying Parties[1]; - - Authorize the presentation of their digital credentials with Relying Parties. + - Authorize the presentation of their digital Credentials with Relying Parties. Please refer to the relative sections for further information about PID and (Q)EAAs issuance and presentation. + Return to Operational state ~~~~~~~~~~~~~~~~~~~~~~~~~~~ A Valid Wallet Instance may revert to the Operational state under specific circumstances. These circumstances include the expiration or the revocation of the associated PID by its PID Provider. diff --git a/images/dynamic_view_sequence_wallet_instance_attestation.svg b/images/dynamic_view_sequence_wallet_instance_attestation.svg deleted file mode 100644 index 4ab9a713d..000000000 --- a/images/dynamic_view_sequence_wallet_instance_attestation.svg +++ /dev/null @@ -1 +0,0 @@ -UserWallet InstanceWallet ProviderApp attestation serviceUserWallet InstanceWallet ProviderApp attestation service1Initialize Wallet Instanceor request/present credentials2Get Wallet Provider metadata3Metadata containing credential types, key requirements, endpoints4Validate Wallet Provider trust5Generate key pairs6Request nonce7nonce8Create Wallet Instance Attestation Request JWT9Get attestation (Wallet Instance Attestation Request)10Validate Wallet Instance genuineness (nonce)11Integrity check result12Validate signature13Generate and sign Wallet Instance Attestation14Wallet Instance Attestation15Validate Wallet Instance Attestation16Wallet Instance initializedready to obtain new credentials \ No newline at end of file diff --git a/images/static_view_wallet_instance_attestation.svg b/images/static_view_wallet_instance_attestation.svg index aab862f78..2f18451e1 100644 --- a/images/static_view_wallet_instance_attestation.svg +++ b/images/static_view_wallet_instance_attestation.svg @@ -1 +1 @@ -UserWallet providerWallet solutionWallet instanceWallet backendIs part ofProvides wallet assertionscontrol / activateIs an instance ofProvide \ No newline at end of file +UserWallet ProviderDevice OEMWallet SolutionWallet InstanceWallet BackendDevice Integrity ServiceUseUseIs part ofProvides Wallet Attestationcontrol / activateIs an instance ofProvideProvide \ No newline at end of file diff --git a/images/wallet_instance_acquisition.svg b/images/wallet_instance_acquisition.svg new file mode 100644 index 000000000..040a35eb4 --- /dev/null +++ b/images/wallet_instance_acquisition.svg @@ -0,0 +1 @@ +UserWallet InstanceDevice Integrity ServiceWallet Provider backend1Request a new operation thatrequires aWallet Attestation2Check ifCryptographic Hardware Keysis available3Generates an ephemeral key pairJWKCheck Wallet Provider is part of the Federation and obtain its metadata4Getchallenge5Generate one time usechallenge6challenge7Generateclient_data_hashas SHA256(challenge, public_jwk)8GenerateCryptographic Hardware KeyPoPhardware_signature= sign(client_data_hash, wallet_hardware_key_tag)9generateIntegrityAssertion(client_data_hash)10integrity_assertion11Generate Wallet Attestation Request withintegrity_assertion,hardware_signature,challenge,Cryptographic Hardware Key Tag,public_jwksigned with ephemeralJWK12Send Wallet Attestation RequestCheck if Wallet Instance is initialized and validusing Cryptographic Hardware Key Tag andhardware_signature13Validatechallenge14Validateintegrity_assertion15Validatehardware_signature16ValidateJWKPoP17CreateWallet Attestation18Wallet Attestation \ No newline at end of file diff --git a/images/wallet_instance_initialization.svg b/images/wallet_instance_initialization.svg new file mode 100644 index 000000000..5f5237a06 --- /dev/null +++ b/images/wallet_instance_initialization.svg @@ -0,0 +1 @@ +UserWallet InstanceDevice Integrity ServiceWallet Provider backendonly upon first installation of the app1starts the app (first use)2Check if Device Integrity Service is availableCheck Wallet Provider is part of the Federation and obtain its metadata3Getchallenge4Generate one time usechallenge5challenge6GenerateCryptographic Hardware Keyspair and storeCryptographic Hardware Key Tag7attestKey(challenge, Cryptographic Hardware Key Tag)8Key Attestationsigned by OEM9Sendchallenge,Key AttestationandCryptographic Hardware Key Tag10Validatechallenge11ValidateKey Attestation12StoreCryptographic Hardware Keys13OK14Wallet Instance Initialized \ No newline at end of file