From da1c3afa1b3b21cc2a1ada9072584415650df015 Mon Sep 17 00:00:00 2001 From: grausof Date: Tue, 12 Mar 2024 18:47:46 +0100 Subject: [PATCH 01/24] feat: Add Wallet Attestation request flow --- docs/en/defined-terms.rst | 16 +- docs/en/wallet-attestation.rst | 583 +++++++++++------- ...w_sequence_wallet_instance_attestation.svg | 1 - ...tatic_view_wallet_instance_attestation.svg | 2 +- images/wallet_instance_acquisition.svg | 1 + images/wallet_instance_initialization.svg | 1 + 6 files changed, 388 insertions(+), 216 deletions(-) delete mode 100644 images/dynamic_view_sequence_wallet_instance_attestation.svg create mode 100644 images/wallet_instance_acquisition.svg create mode 100644 images/wallet_instance_initialization.svg diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index 882588a08..167cf02d9 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -39,10 +39,20 @@ 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 Attestation Request + - Format of the request sent by the Wallet Instance to the backend Wallet Provider to obtain a Wallet Attestation. + * - Wallet Secure Cryptographic Device + - Hardware-backed secure environment for creating, storing, and/or managing cryptographic keys and data. Examples include Secure Elements (SE), Trusted Execution Environments (TEEs), and 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 + - Device manufacturer service that allows you to certify that the app instance (Wallet Instance) is intact and genuine and also allows you to certify that the private keys generated by the device are securely stored within the device's dedicated hardware. Please note that each manufacturer uses different terms to identify it. + * - Wallet Hardware Keys + - Pair of public and private keys generated by the Wallet Instance during app initialization. These keys remain valid throughout the entire lifespan of the Wallet Instance. Conceptually, the Wallet Hardware Keys serves as a personal device Master Key and, being part of the OS domain, cannot be used for signing any arbitrary payloads. The purpose of the Wallet Hardware Keys is to uniquely identify a Wallet Instance. + * - Wallet Hardware Key Tag + - Unique identifier of the Wallet Hardware Keys generated by the operating system and used to access the private key in the hardware. + * - Key Attestation + - Attestation signed by device OEM that gives you more confidence that the keys you use in your Wallet Instance are stored in a device's hardware-backed keystore * - 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 +93,5 @@ Acronyms - Application Programming Interface * - **LoA** - Level of Assurance + * - **WSCD** + - Wallet Secure Cryptographic Device diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index abfde0b54..271f8fd0f 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -14,6 +14,9 @@ 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. +- MUST ensure that the Wallet Instance is genuine, preventing any attempts at manipulation or falsification by unauthorized third parties. +- MUST ensure that private keys have been generated and securely stored within a trusted execution environment. +- 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. It is necessary for each Wallet Instance to obtain a Wallet Attestation before entering the Operational state. @@ -30,151 +33,214 @@ The following requirements for the Wallet Attestation are met: 6. Each Wallet Instance SHOULD be able to request multiple attestations with different public keys associated to them. This requirement provides a privacy-preserving measure, as the public key MAY be used as a tracking tool during the presentation phase (see also the point number 10, listed below). 7. The Wallet Attestation SHOULD be usable multiple times during its validity period, allowing for repeated authentication and authorization without the need to request new attestations with each interaction. 8. The Wallet Attestation SHOULD have an expiration date time, after which it will no longer be considered valid. -9. When the private key associated with the Wallet Instance is lost or deleted, the attestation MUST become invalid to prevent unauthorized use of the Wallet Instance. +9. The Wallet Attestation SHOULD no longer needs to be issued by the Wallet Provider if the Wallet Instance has been revoked. +10. The Wallet Attestation SHOULD be pseudo-anonymous (meaning they do not contain direct references to an individual), making it impossible to identify a person without additional information. +11. When the private key associated with the Wallet Instance is lost or deleted, the attestation MUST become invalid to prevent unauthorized use of the Wallet Instance. -High-level Design ------------------ - 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/TLFHRjD047o_hrYb3xHM-84ye288QLMWY1HuNjiRPnNdpjfR1yBNisUd8RRY1rkdlPdPcR5y7nL5sttjiDNWstrEuhPS4cn2q3pySMyQ0t313Nfr3WiD0hCVaMG66A6rWxj0mEmNrZKfF7fJzWLrA6mQ6A8-qe4BCfHI9Qn7M9FOv0H7ZN0J6s5VLKBahsxu9k5WHWLoB7RaouwQ5pldAWbj0y7NHsYRu6734XNO71aJbMqKDg1RIiPSYl3sdPqMq9KHNs_WjYSQu2u5vmDgJx7dnFYmfM87l86fGC2Mvu1SOrwJS-A34eG3IHAQcrsu-VouUdXPVLyklxfURXpG9581hwO_aGtx6EXB2BaYUs0plYV54XMTrT5jSgxtQdiMi2A5B2ksITrNb6NdK5rjzfo1dYIDWoTGtbEgO4HDwBw3qKL90zLpLMTLmvy2Fg2Klr48dkWOiyn2idIHeWQPmC4BLbbsaaMD2q1LYcfNjsSRSvXWthd4-MyyZTzt_AvFyn2vybH2VeJdvPUByjPMwJ3f_2hVx4yRdwxy9zPSeevQlWeOBnt0rjFDnU5NUtwwygdiClqE2nZznNPWPRFmbyfBcb6S5UFkxTNkwty0 -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 request and receive a one time ``challenge`` from the Wallet Provider Backend. The ``challenge`` is a ``nonce``, which MUST be unpredictable and it is the primary countermeasure against replay attack. The value of the ``nonce`` returned by the backend must be generated in such a way as to guarantee that it can only be used once and in a pre-established time interval. -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 generates the Wallet Hardware Keys pair via the operating system and store the relative Wallet Hardware Key Tag in a local storage: + + 1. It MUST ensure that Wallet Hardware Keys do not already exist, if they exist and the Wallet is in the initialization phase they must be deleted. + 2. It MUST generate a pair of asymmetric EC keys (Wallet Hardware Keys) via a local WSCD. + 3. It SHOULD obtain a unique identifier (Wallet Hardware Key Tag) of the generated Wallet Hardware Keys from the operating system. If the operating system allows you to define a tag when creating keys, then a random string for Wallet Hardware Key Tag must be chosen. + 4. It MUST store the relative Wallet Hardware Key Tag in a local storage. + +.. note:: + + **WSCD:** For key generation, the Wallet Instance will always rely on a local WSCD on devices that support it. For Android, Strongbox will be used or, if it is not available, a Trusted Execution Environment (TEE) while for iOS Secure Elements (SE). Since each OEM develops a different SDK for accessing the local WSCD, it will be treated in a generic manner below. + + +**Step 7**: The Wallet Instance: invokes the operating system attestation service (Device Integrity Service) passing ``challenge`` and Wallet Hardware Key Tag in order to obtain a Key Attestation. + +.. note:: + + **Device Integrity Service:** Below we will treat a Device Integrity Service as an abstract entity made available by device OEMs which allows us to certify via a signed payload (attestation) that a particular key is hardware backed in a safe and protected environment of the device. Furthermore, the service will also allow you to demonstrate via a signed payload (assertion) that that particular app instance (Wallet Instance) is intact and genuine and has not been tampered with. Furthermore, both within the attestation and the assertion, the service includes essential information to recover the type of device, the model, the app version, the operating system version, the bootloader status and other information that allows you to understand whether the device has been tampered with or not. For Android the service used is `Key Attestation`_ in addition to `Play Integrity API`_, while for iOS the `DeviceCheck`_ service. + +**Step 8**: The Device Integrity Service: + + * generate a Key Attestation holder binded with ``challenge`` and Wallet Hardware public key. + * adds relevant information on the security of the device. + * sign the Key Attestation with an OEM certificate which in addition to certifying the integrity of the Wallet Instance also certifies that the Wallet Hardware Keys is secure stored by the OS (hardware backed). + +**Step 9**: The Wallet Instance send the ``challenge`` with Key Attestation and Wallet Hardware Key Tag to the Wallet Provider Backend in order to register the Wallet Instance identified by the Wallet Hardware Key public key. + +.. note:: + + The Key Attestation (``key_attestation``) must always be encoded in base64 as the format is different between the various operating systems. -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 as it is already included in the ``key_attestation``. + +**Steps 10-12**: The Wallet Provider validate the ``challenge`` and ``key_attestation`` signature: + + 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 Wallet Hardware Key Tag and all useful information related to the device. + 5. It SHULD associate the Wallet Instance with a specific user uniquely identified within the Wallet Provider's systems. This will be useful for the lifecycle of the Wallet Instance and for a future revocation. + +.. 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 *application/json* as the content type 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:** Although the registration endpoint does not require any authentication, it is protected by the presence of the ``key_attestation`` which, if validated correctly, only allows the registration of valid and intact instances of the app. Any other claims sent will not be validated and therefore the endpoint will return an error. The presence of a ``challenge`` also avoids reply attacks. Finally, the integrity of the ``challenge`` and the ``hardware_key_tag`` is guaranteed by the signature present within the ``key_attestation``. + + +Wallet Attestation acquisition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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/VLHFJzjE4BtlfnZ1uGTHVfTAxG6f5OXIe5GL0bekID7O7knfd5rtT-oKVlhEEdySXsqFbbZspNjltixaD0XwQHUrmLQSRHSPULDnGV3id6Jkb_clKG3dtA0LOp0Nv-7WMo1_01YW3OhVGS318zOr2LnRPROvzIXi6XYZFbB7EIbAgFGiBt1FlkCD72N0OMWysxBqH3QfSEjTfqOzP9ZFoHPzQPRFZJ7HrVyVLFK4xkXdIq40mT8IN4CUXPq5gL2UhDTRzgIIC9ciUSz4jA17JIQnOUvGAFPWz5lJdbUKpu6VXx8hzCKIFS4DlOJ915X9E-GQivhCJkKbsUWXQbgWfgA57ckOqmiqo5u9Fp_UgB3nrgciwyX7xQbs1eTVhY-l7YxlBYw-cfM3_InKDMO5xbax9FX4nQPXj0MuJ90ji0HOa621WaQJwvNCsgJgH9EYHl8gijkITdE82UlN0uTkm5a2uGN5YTWhZUXry-EBWaQi9XLJBAcPhCoYsrc5eT9mCS3zrTcRj--EjdnJQDgivdpsOpa_JZ6bdqh9RjtjapvrjVxlB71fKLfFUlSUukbety8KbZtLR5kaxpSJBBVAAE44ohNqTipFGY0lx5up7fjOCkJ4cv8PRchKJhAlrtExdVebI_KtiYcaUvwENsdwP9F1mGEMA_2GkpgCH5JqmiDqRuTwcB1xiiK_d8_dRLY5U4olGbp6lT-Uk0riMHXh_ar5lmAT_bsODh0j8TMLODdZqjaCspAimFV8Y9AQ-Z4W_H1fQ5e-ZTHeLrEySttkQNNvEkBnHgOGYTNSEMkPETKSsaNz1m00 + +**Step 1:**: The user requests a new operation which requires obtaining a Wallet Attestation. + +**Steps 2-3:**: The Wallet Instance check if a Wallet Hardware Key exist and generates an ephemeral asymmetric key pair. + + 1. It MUST ensure that Wallet Hardware Keys exist. If they do not exist, it is necessary to reinitialize the wallet. + 2. It MUST generates an ephemeral asymmetric key pair whose public key will be linked with the Wallet Attestation. + 3. it MUST check if Wallet Provider is part of the federation and obtain its metadata. + + +**Steps 4-6:**: The Wallet Instance request and receive a one time ``challenge`` from the Wallet Provider Backend. The ``challenge`` is a ``nonce``, which MUST be unpredictable and it is the primary countermeasure against replay attack. The value of the ``nonce`` returned by the backend must be generated in such a way as to guarantee that it can only be used once and in a pre-established time interval. + +.. code-block:: http - 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 + 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: + + * generate a ``client_data`` which is a JSON containing ``challenge`` and ephemeral public ``jwk``. + * generate a ``client_data_hash`` as SHA256 of ``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: + + * generate an ``hardware_signature`` signing ``client_data_hash`` with Wallet Hardware private key. It will be used as a **PoP** of the Wallet Hardware Keys. + * ask to Device Integrity Service to generate an ``integrity_assertion`` bounded with ``client_data_hash``. + * obtain from Device Integrity Service an ``integrity_assertion`` signed by OEM. + +.. 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: + * generate the Wallet Attestation Request as a JWT containing ``integrity_assertion``, ``hardware_signature``, ``challenge``, ``wallet_hardware_key_tag``, ``public_jwk`` signed with the private key associated with the public key of the ephemeral key pair generated initially. + * send the Wallet Attestation Request to Wallet Provider backend via 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": "var+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", + "type": "WalletAttestationRequest", + "hardware_signature": "KoZIhvcNAQcCoIAwgAIB...redacted", + "integrity_assertion": "o2NmbXRvYXBwbGUtYXBwYX...redacted", + "hardware_key_tag": "WQhyDymFKsP95iFqpzdEDWW4l7aVna2Fn4JCeWHYtbU=", "cnf": { "jwk": { "crv": "P-256", @@ -182,119 +248,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 - 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 + grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer + &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6ImtoakZWTE9nRjNHeG...redacted - { +**Steps 13-17**: The Wallet Provider backend validate the Wallet Attestation Request and if it passes the checks, a Wallet Attestation is issued: + + 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 Wallet 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 +346,165 @@ 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 + - + * - **type** + - It MUST be set to string "WalletAttestationRequest". + - + * - **hardware_signature** + - The signature of ``client_data`` obtained using Wallet 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 **Wallet 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`. + * - **type** + - It MUST be set to string "WalletAttestation". + - + * - **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 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` + * - **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 + 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..d2e72c79e --- /dev/null +++ b/images/wallet_instance_acquisition.svg @@ -0,0 +1 @@ +UserWallet InstanceDevice Integrity ServiceWallet Provider backend1Request a new operation thatrequires aWallet Attestation2Check ifWallet 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)8GenerateWallet 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,Wallet Hardware Key Tag,public_jwksigned with ephemeralJWK12Send Wallet Attestation RequestCheck if Wallet Instance is initialized and validusing Wallet 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..f9afb7bc0 --- /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 usechallenge5challenge6GenerateWallet Hardware Keyspair and storeWallet Hardware Key Tag7attestKey(challenge, Wallet Hardware Key Tag)8Key Attestationsigned by OEM9Sendchallenge,Key AttestationandWallet Hardware Key Tag10Validatechallenge11ValidateKey Attestation12StoreWallet Hardware Keys13OK14Wallet Instance Initialized \ No newline at end of file From 809f15e72b339ddd360aff76d80ca1253b12b069 Mon Sep 17 00:00:00 2001 From: Francesco Grauso Date: Wed, 13 Mar 2024 23:06:07 +0100 Subject: [PATCH 02/24] Apply suggestions from code review Co-authored-by: Giuseppe De Marco --- docs/en/defined-terms.rst | 8 ++--- docs/en/wallet-attestation.rst | 62 ++++++++++++++++++---------------- 2 files changed, 36 insertions(+), 34 deletions(-) diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index 167cf02d9..73c651f26 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -46,13 +46,13 @@ Below are the description of acronyms and definitions which are useful for furth * - Credential Status Attestation - Verifiable Attestation proving that a related Digital Credential is not revoked. * - Device Integrity Service - - Device manufacturer service that allows you to certify that the app instance (Wallet Instance) is intact and genuine and also allows you to certify that the private keys generated by the device are securely stored within the device's dedicated hardware. Please note that each manufacturer uses different terms to identify it. + - A service provided by device manufacturers that verifies the integrity and authenticity of the app instance (Wallet Instance), as well as certifying the secure storage of private keys generated by the device within its dedicated hardware. It's important to note that the terminology used to describe this service varies among manufacturers. * - Wallet Hardware Keys - - Pair of public and private keys generated by the Wallet Instance during app initialization. These keys remain valid throughout the entire lifespan of the Wallet Instance. Conceptually, the Wallet Hardware Keys serves as a personal device Master Key and, being part of the OS domain, cannot be used for signing any arbitrary payloads. The purpose of the Wallet Hardware Keys is to uniquely identify a Wallet Instance. + - During the app initialization, the Wallet Instance generates a pair of keys, one public and one private, which remain valid for the entire duration of the Wallet Instance's life. Functioning as a Master Key for the personal device, these Wallet Hardware Keys are confined to the OS domain and are not designed for signing arbitrary payloads. Their primary role is to provide a unique identification for each Wallet Instance. * - Wallet Hardware Key Tag - - Unique identifier of the Wallet Hardware Keys generated by the operating system and used to access the private key in the hardware. + - A unique identifier created by the operating system for the Wallet Hardware Keys, utilized to gain access to the private key stored in the hardware. * - Key Attestation - - Attestation signed by device OEM that gives you more confidence that the keys you use in your Wallet Instance are stored in a device's hardware-backed keystore + - An attestation from the device's OEM that enhances your confidence in the keys used in your Wallet Instance being securely stored within the device's hardware-backed keystore. * - Qualified Electronic Attestation of Attributes (QEAA) - A digitally verifiable attestation in electronic form, issued by a QTSP, that substantiates a person's possession of attributes. * - Qualified Electronic Signature Provider diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index 271f8fd0f..66ed0306c 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -33,9 +33,9 @@ The following requirements for the Wallet Attestation are met: 6. Each Wallet Instance SHOULD be able to request multiple attestations with different public keys associated to them. This requirement provides a privacy-preserving measure, as the public key MAY be used as a tracking tool during the presentation phase (see also the point number 10, listed below). 7. The Wallet Attestation SHOULD be usable multiple times during its validity period, allowing for repeated authentication and authorization without the need to request new attestations with each interaction. 8. The Wallet Attestation SHOULD have an expiration date time, after which it will no longer be considered valid. -9. The Wallet Attestation SHOULD no longer needs to be issued by the Wallet Provider if the Wallet Instance has been revoked. -10. The Wallet Attestation SHOULD be pseudo-anonymous (meaning they do not contain direct references to an individual), making it impossible to identify a person without additional information. -11. When the private key associated with the Wallet Instance is lost or deleted, the attestation MUST become invalid to prevent unauthorized use of the Wallet Instance. +9. The Wallet Attestation MUST NOT be issued by the Wallet Provider if the Wallet Instance has been revoked. +10. The Wallet Attestation SHOULD be designed to be pseudo-anonymous, meaning it does not directly reference any individual, thereby making it impossible to identify a person without supplementary information. +11. When the private key associated with the Wallet Instance is lost or deleted, the Wallet Attestation MUST become invalid to prevent unauthorized use of the Wallet Instance. Static Component View @@ -70,7 +70,7 @@ Wallet Instance initialization and registration **Federation Check:** The Wallet Instance needs to check if the Wallet Provider is part of the Federation, obtaining its protocol specific Metadata. A non-normative example of a response from the endpoint **.well-known/openid-federation** with the **Entity Configuration** and the **Metadata** of the Wallet Provider is represented within the section `Wallet Provider metadata`_. -**Steps 3-5:**: The Wallet Instance request and receive a one time ``challenge`` from the Wallet Provider Backend. The ``challenge`` is a ``nonce``, which MUST be unpredictable and it is the primary countermeasure against replay attack. The value of the ``nonce`` returned by the backend must be generated in such a way as to guarantee that it can only be used once and in a pre-established time interval. +**Steps 3-5:**: The Wallet Instance sends a request to the Wallet Provider Backend and receives a one-time ``challenge``. This "challenge" is a ``nonce``, which must be unpredictable to serve as the main defense against replay attacks. The backend must generate the ``nonce`` value in a manner that ensures it is single-use and valid only within a specific time frame. .. code-block:: http @@ -87,31 +87,33 @@ Wallet Instance initialization and registration "nonce": "d2JhY2NhbG91cmVqdWFuZGFt" } -**Step 6**: The Wallet Instance generates the Wallet Hardware Keys pair via the operating system and store the relative Wallet Hardware Key Tag in a local storage: +**Step 6**: The Wallet Instance, through the operating system, creates a pair of Wallet Hardware Keys and stores the corresponding Wallet Hardware Key Tag in local storage once the following requirements are met: 1. It MUST ensure that Wallet Hardware Keys do not already exist, if they exist and the Wallet is in the initialization phase they must be deleted. 2. It MUST generate a pair of asymmetric EC keys (Wallet Hardware Keys) via a local WSCD. - 3. It SHOULD obtain a unique identifier (Wallet Hardware Key Tag) of the generated Wallet Hardware Keys from the operating system. If the operating system allows you to define a tag when creating keys, then a random string for Wallet Hardware Key Tag must be chosen. - 4. It MUST store the relative Wallet Hardware Key Tag in a local storage. + 3. It SHOULD obtain a unique identifier (Wallet Hardware Key Tag) for the generated Wallet Hardware Keys from the operating system. If the operating system permits specifying a tag during the creation of keys, then a random string for the Wallet Hardware Key Tag must be selected. This random value MUST be collision-resistant and unpredictable to ensure security. To achieve this, consider using a cryptographic hash function or a secure random number generator provided by the operating system or a reputable cryptographic library. + 4. If the previous points are satisfied, It MUST store the Wallet Hardware Key Tag in a local storage. .. note:: **WSCD:** For key generation, the Wallet Instance will always rely on a local WSCD on devices that support it. For Android, Strongbox will be used or, if it is not available, a Trusted Execution Environment (TEE) while for iOS Secure Elements (SE). Since each OEM develops a different SDK for accessing the local WSCD, it will be treated in a generic manner below. -**Step 7**: The Wallet Instance: invokes the operating system attestation service (Device Integrity Service) passing ``challenge`` and Wallet Hardware Key Tag in order to obtain a Key Attestation. +**Step 7**: The Wallet Instance uses the Device Integrity Service, providing a "challenge" and the Wallet Hardware Key Tag to acquire the Key Attestation. .. note:: - **Device Integrity Service:** Below we will treat a Device Integrity Service as an abstract entity made available by device OEMs which allows us to certify via a signed payload (attestation) that a particular key is hardware backed in a safe and protected environment of the device. Furthermore, the service will also allow you to demonstrate via a signed payload (assertion) that that particular app instance (Wallet Instance) is intact and genuine and has not been tampered with. Furthermore, both within the attestation and the assertion, the service includes essential information to recover the type of device, the model, the app version, the operating system version, the bootloader status and other information that allows you to understand whether the device has been tampered with or not. For Android the service used is `Key Attestation`_ in addition to `Play Integrity API`_, while for iOS the `DeviceCheck`_ service. + **Device Integrity Service:** In this section the Device Integrity Service is considered as it is provided by device manufacturers. This service allows the verification of a key being securely stored within the device's hardware through a signed document (attestation). Additionally, it offers the verifiable proof that a specific app instance (Wallet Instance) is authentic, unaltered, and in its original state using a specialized signed document (assertion) made for this scope. + + The service also incorporates details in both the attestation and the assertion, such as the device type, model, app version, operating system version, bootloader status, and other relevant information to assess the device has not been compromised. For Android the service used is `Key Attestation`_ in addition to `Play Integrity API`_, while for iOS the `DeviceCheck`_ service. -**Step 8**: The Device Integrity Service: +**Step 8**: The Device Integrity Service performs the following actions: - * generate a Key Attestation holder binded with ``challenge`` and Wallet Hardware public key. - * adds relevant information on the security of the device. - * sign the Key Attestation with an OEM certificate which in addition to certifying the integrity of the Wallet Instance also certifies that the Wallet Hardware Keys is secure stored by the OS (hardware backed). +* Creates a Key Attestation that is linked with the provided "challenge" and the public key of the Wallet Hardware. +* Incorporates information pertaining to the device's security. +* Uses an OEM certificate to sign the Key Attestation, thereby not only verifying the integrity of the Wallet Instance but also confirming that the Wallet Hardware Keys are securely managed by the operating system (hardware-backed). -**Step 9**: The Wallet Instance send the ``challenge`` with Key Attestation and Wallet Hardware Key Tag to the Wallet Provider Backend in order to register the Wallet Instance identified by the Wallet Hardware Key public key. +**Step 9**: The Wallet Instance sends the ``challenge`` with Key Attestation and Wallet Hardware Key Tag to the Wallet Provider Backend in order to register the Wallet Instance identified by the Wallet Hardware Key public key. .. note:: @@ -139,7 +141,7 @@ Wallet Instance initialization and registration 2. It MUST validate the ``key_attestation`` as defined by the device manufacturers' guidelines. 3. It MUST verify that the device in use has no security flaws and reflects the minimum security requirements defined by the Wallet Provider. 4. If these checks are passed, it MUST register the Wallet Instance, keeping the Wallet Hardware Key Tag and all useful information related to the device. - 5. It SHULD associate the Wallet Instance with a specific user uniquely identified within the Wallet Provider's systems. This will be useful for the lifecycle of the Wallet Instance and for a future revocation. + 5. It SHOULD associate the Wallet Instance with a specific user uniquely identified within the Wallet Provider's systems. This will be useful for the lifecycle of the Wallet Instance and for a future revocation. .. code-block:: http @@ -153,11 +155,11 @@ If any errors occur during the Wallet Instance registration, the Wallet Provider **Steps 13-14**: The Wallet Instance has been initialized and becomes operational. -.. note:: **Threat Model:** Although the registration endpoint does not require any authentication, it is protected by the presence of the ``key_attestation`` which, if validated correctly, only allows the registration of valid and intact instances of the app. Any other claims sent will not be validated and therefore the endpoint will return an error. The presence of a ``challenge`` also avoids reply attacks. Finally, the integrity of the ``challenge`` and the ``hardware_key_tag`` is guaranteed by the signature present within the ``key_attestation``. +.. note:: **Threat Model**: While the registration endpoint does not necessitate any client authentication, it is safeguarded through the use of `key_attestation`. Proper validation of this attestation permits only the registration of authentic and unaltered app instances. Any other claims submitted will not undergo validation, leading the endpoint to respond with an error. Additionally, the inclusion of a challenge helps prevent replay attacks. The authenticity of both the challenge and the ``hardware_key_tag`` is ensured by the signature found within the ``key_attestation``. -Wallet Attestation acquisition -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Wallet Attestation Issuance +~~~~~~~~~~~~~~~~~~~~~ This section describes the Wallet Attestation format and how the Wallet Provider issues it. @@ -166,16 +168,16 @@ This section describes the Wallet Attestation format and how the Wallet Provider :alt: The figure illustrates the sequence diagram for issuing a Wallet Attestation, with the steps explained below. :target: https://www.plantuml.com/plantuml/uml/VLHFJzjE4BtlfnZ1uGTHVfTAxG6f5OXIe5GL0bekID7O7knfd5rtT-oKVlhEEdySXsqFbbZspNjltixaD0XwQHUrmLQSRHSPULDnGV3id6Jkb_clKG3dtA0LOp0Nv-7WMo1_01YW3OhVGS318zOr2LnRPROvzIXi6XYZFbB7EIbAgFGiBt1FlkCD72N0OMWysxBqH3QfSEjTfqOzP9ZFoHPzQPRFZJ7HrVyVLFK4xkXdIq40mT8IN4CUXPq5gL2UhDTRzgIIC9ciUSz4jA17JIQnOUvGAFPWz5lJdbUKpu6VXx8hzCKIFS4DlOJ915X9E-GQivhCJkKbsUWXQbgWfgA57ckOqmiqo5u9Fp_UgB3nrgciwyX7xQbs1eTVhY-l7YxlBYw-cfM3_InKDMO5xbax9FX4nQPXj0MuJ90ji0HOa621WaQJwvNCsgJgH9EYHl8gijkITdE82UlN0uTkm5a2uGN5YTWhZUXry-EBWaQi9XLJBAcPhCoYsrc5eT9mCS3zrTcRj--EjdnJQDgivdpsOpa_JZ6bdqh9RjtjapvrjVxlB71fKLfFUlSUukbety8KbZtLR5kaxpSJBBVAAE44ohNqTipFGY0lx5up7fjOCkJ4cv8PRchKJhAlrtExdVebI_KtiYcaUvwENsdwP9F1mGEMA_2GkpgCH5JqmiDqRuTwcB1xiiK_d8_dRLY5U4olGbp6lT-Uk0riMHXh_ar5lmAT_bsODh0j8TMLODdZqjaCspAimFV8Y9AQ-Z4W_H1fQ5e-ZTHeLrEySttkQNNvEkBnHgOGYTNSEMkPETKSsaNz1m00 -**Step 1:**: The user requests a new operation which requires obtaining a Wallet Attestation. +**Step 1:**: The user initiates a new operation that necessitates the acquisition of a Wallet Attestation. **Steps 2-3:**: The Wallet Instance check if a Wallet Hardware Key exist and generates an ephemeral asymmetric key pair. - 1. It MUST ensure that Wallet Hardware Keys exist. If they do not exist, it is necessary to reinitialize the wallet. + 1. It MUST ensure that Wallet Hardware Keys exist. If they do not exist, it is necessary to reinitialize the Wallet. 2. It MUST generates an ephemeral asymmetric key pair whose public key will be linked with the Wallet Attestation. 3. it MUST check if Wallet Provider is part of the federation and obtain its metadata. -**Steps 4-6:**: The Wallet Instance request and receive a one time ``challenge`` from the Wallet Provider Backend. The ``challenge`` is a ``nonce``, which MUST be unpredictable and it is the primary countermeasure against replay attack. The value of the ``nonce`` returned by the backend must be generated in such a way as to guarantee that it can only be used once and in a pre-established time interval. +**Steps 4-6:**: The Wallet Instance solicits a one-time "challenge" from the Wallet Provider Backend. This "challenge" takes the form of a "nonce," which is required to be unpredictable and serves as the main defense against replay attacks. The backend must produce the "nonce" in a manner that ensures its single-use within a predetermined time frame. .. code-block:: http @@ -191,10 +193,10 @@ This section describes the Wallet Attestation format and how the Wallet Provider "nonce": "d2JhY2NhbG91cmVqdWFuZGFt" } -**Step 7**: The Wallet Instance: +**Step 7**: The Wallet Instance performs the following actions: - * generate a ``client_data`` which is a JSON containing ``challenge`` and ephemeral public ``jwk``. - * generate a ``client_data_hash`` as SHA256 of ``client_data``. + * Creates a ``client_data``, a JSON structure that includes the challenge and the ephemeral public ``jwk``. + * Computes a ``client_data_hash`` by applying the SHA256 algorithm to the ``client_data``. Below a non-normative example of the ``client_data``. @@ -211,11 +213,11 @@ Below a non-normative example of the ``client_data``. } } -**Steps 8-10**: The Wallet Instance: +**Steps 8-10**: The Wallet Instance takes the following steps: - * generate an ``hardware_signature`` signing ``client_data_hash`` with Wallet Hardware private key. It will be used as a **PoP** of the Wallet Hardware Keys. - * ask to Device Integrity Service to generate an ``integrity_assertion`` bounded with ``client_data_hash``. - * obtain from Device Integrity Service an ``integrity_assertion`` signed by OEM. + * Produces an hardware_signature by signing the ``client_data_hash`` with the Wallet Hardware's private key, serving as a Proof of Possession (PoP) for the Wallet Hardware Keys. + * Requests the Device Integrity Service to create an ``integrity_assertion`` linked to the ``client_data_hash``. + * Receives a signed ``integrity_assertion`` from the Device Integrity Service, authenticated by the OEM. .. note:: ``integrity_assertion`` is a custom payload generated by Device Integrity Service, signed by device OEM and encoded in base64 to have uniformity between different devices. @@ -230,7 +232,7 @@ Below an non-normative example of the Wallet Attestation Request JWT without enc { "alg": "ES256", "kid": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c", - "typ": "var+jwt" + "typ": "war+jwt" } . { @@ -280,7 +282,7 @@ encoded in ``application/x-www-form-urlencoded`` format: grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6ImtoakZWTE9nRjNHeG...redacted -**Steps 13-17**: The Wallet Provider backend validate the Wallet Attestation Request and if it passes the checks, a Wallet Attestation is issued: +**Steps 13-17**: The Wallet Provider's backend assesses the Wallet Attestation Request and issues a Wallet Attestation, if the requirements described below are satisfied: 1. It MUST check the Wallet Attestation Request contains all the defined parameters according to :ref:`Table of the Wallet Attestation Request parameters `. 2. It MUST verify that the signature of the received Wallet Attestation Request is valid and associated with public ``jwk``. From 36ca2d9cb9f09fa76f252aff7a44e77e66286bce Mon Sep 17 00:00:00 2001 From: Francesco Grauso Date: Mon, 18 Mar 2024 09:10:07 +0100 Subject: [PATCH 03/24] Apply suggestions from code review Co-authored-by: Giuseppe De Marco --- docs/en/defined-terms.rst | 2 -- docs/en/wallet-attestation.rst | 4 ++-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index 73c651f26..8184dc83c 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -39,8 +39,6 @@ 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 Attestation Request - - Format of the request sent by the Wallet Instance to the backend Wallet Provider to obtain a Wallet Attestation. * - Wallet Secure Cryptographic Device - Hardware-backed secure environment for creating, storing, and/or managing cryptographic keys and data. Examples include Secure Elements (SE), Trusted Execution Environments (TEEs), and Strongbox. * - Credential Status Attestation diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index 66ed0306c..09f72e33c 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -96,7 +96,7 @@ Wallet Instance initialization and registration .. note:: - **WSCD:** For key generation, the Wallet Instance will always rely on a local WSCD on devices that support it. For Android, Strongbox will be used or, if it is not available, a Trusted Execution Environment (TEE) while for iOS Secure Elements (SE). Since each OEM develops a different SDK for accessing the local WSCD, it will be treated in a generic manner below. + **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 Wallet Hardware Key Tag to acquire the Key Attestation. @@ -117,7 +117,7 @@ Wallet Instance initialization and registration .. note:: - The Key Attestation (``key_attestation``) must always be encoded in base64 as the format is different between the various operating systems. + The Key Attestation (``key_attestation``) MUST be encoded in base64. .. code-block:: http From 83acccc140cfd75d29df940f58b2a93c92240949 Mon Sep 17 00:00:00 2001 From: grausof Date: Mon, 18 Mar 2024 09:15:36 +0100 Subject: [PATCH 04/24] Add nonce endpoint reference --- docs/en/wallet-attestation.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index 09f72e33c..3250a9781 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -71,6 +71,7 @@ Wallet Instance initialization and registration **Federation Check:** The Wallet Instance needs to check if the Wallet Provider is part of the Federation, obtaining its protocol specific Metadata. A non-normative example of a response from the endpoint **.well-known/openid-federation** with the **Entity Configuration** and the **Metadata** of the Wallet Provider is represented within the section `Wallet Provider metadata`_. **Steps 3-5:**: The Wallet Instance 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 in inspired by `OAuth 2.0 Nonce Endpoint`_. .. code-block:: http @@ -91,7 +92,7 @@ Wallet Instance initialization and registration 1. It MUST ensure that Wallet Hardware Keys do not already exist, if they exist and the Wallet is in the initialization phase they must be deleted. 2. It MUST generate a pair of asymmetric EC keys (Wallet Hardware Keys) via a local WSCD. - 3. It SHOULD obtain a unique identifier (Wallet Hardware Key Tag) for the generated Wallet Hardware Keys from the operating system. If the operating system permits specifying a tag during the creation of keys, then a random string for the Wallet Hardware Key Tag must be selected. This random value MUST be collision-resistant and unpredictable to ensure security. To achieve this, consider using a cryptographic hash function or a secure random number generator provided by the operating system or a reputable cryptographic library. + 3. It SHOULD obtain a unique identifier (Wallet Hardware Key Tag) for the generated Wallet Hardware Keys from the operating system. If the operating system permits specifying a tag during the creation of keys, then a random string for the Wallet Hardware Key Tag must be selected. This random value MUST be collision-resistant and unpredictable to ensure security. To achieve this, consider using a cryptographic hash function or a secure random number generator provided by the operating system or a reputable cryptographic library. 4. If the previous points are satisfied, It MUST store the Wallet Hardware Key Tag in a local storage. .. note:: @@ -103,8 +104,8 @@ Wallet Instance initialization and registration .. 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 document (attestation). Additionally, it offers the verifiable proof that a specific app instance (Wallet Instance) is authentic, unaltered, and in its original state using a specialized signed document (assertion) made for this scope. - + **Device Integrity Service:** In this section the Device Integrity Service is considered as it is provided by device manufacturers. This service allows the verification of a key being securely stored within the device's hardware through a signed document (attestation). Additionally, it offers the verifiable proof that a specific app instance (Wallet Instance) is authentic, unaltered, and in its original state using a specialized signed document (assertion) made for this scope. + The service also incorporates details in both the attestation and the assertion, such as the device type, model, app version, operating system version, bootloader status, and other relevant information to assess the device has not been compromised. For Android the service used is `Key Attestation`_ in addition to `Play Integrity API`_, while for iOS the `DeviceCheck`_ service. **Step 8**: The Device Integrity Service performs the following actions: @@ -159,7 +160,7 @@ If any errors occur during the Wallet Instance registration, the Wallet Provider Wallet Attestation Issuance -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section describes the Wallet Attestation format and how the Wallet Provider issues it. @@ -222,8 +223,8 @@ Below a non-normative example of the ``client_data``. .. 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: - * generate the Wallet Attestation Request as a JWT containing ``integrity_assertion``, ``hardware_signature``, ``challenge``, ``wallet_hardware_key_tag``, ``public_jwk`` signed with the private key associated with the public key of the ephemeral key pair generated initially. - * send the Wallet Attestation Request to Wallet Provider backend via token endpoint. + * 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: @@ -509,4 +510,5 @@ The body of the Wallet Attestation JWT MUST contain: .. _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 9d3684c025b0102bc679f8ffedd3dcfdd3d94610 Mon Sep 17 00:00:00 2001 From: Francesco Grauso Date: Mon, 18 Mar 2024 16:24:29 +0100 Subject: [PATCH 05/24] Update docs/en/wallet-attestation.rst Co-authored-by: Giuseppe De Marco --- docs/en/wallet-attestation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index 3250a9781..bc3531f11 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -169,7 +169,7 @@ This section describes the Wallet Attestation format and how the Wallet Provider :alt: The figure illustrates the sequence diagram for issuing a Wallet Attestation, with the steps explained below. :target: https://www.plantuml.com/plantuml/uml/VLHFJzjE4BtlfnZ1uGTHVfTAxG6f5OXIe5GL0bekID7O7knfd5rtT-oKVlhEEdySXsqFbbZspNjltixaD0XwQHUrmLQSRHSPULDnGV3id6Jkb_clKG3dtA0LOp0Nv-7WMo1_01YW3OhVGS318zOr2LnRPROvzIXi6XYZFbB7EIbAgFGiBt1FlkCD72N0OMWysxBqH3QfSEjTfqOzP9ZFoHPzQPRFZJ7HrVyVLFK4xkXdIq40mT8IN4CUXPq5gL2UhDTRzgIIC9ciUSz4jA17JIQnOUvGAFPWz5lJdbUKpu6VXx8hzCKIFS4DlOJ915X9E-GQivhCJkKbsUWXQbgWfgA57ckOqmiqo5u9Fp_UgB3nrgciwyX7xQbs1eTVhY-l7YxlBYw-cfM3_InKDMO5xbax9FX4nQPXj0MuJ90ji0HOa621WaQJwvNCsgJgH9EYHl8gijkITdE82UlN0uTkm5a2uGN5YTWhZUXry-EBWaQi9XLJBAcPhCoYsrc5eT9mCS3zrTcRj--EjdnJQDgivdpsOpa_JZ6bdqh9RjtjapvrjVxlB71fKLfFUlSUukbety8KbZtLR5kaxpSJBBVAAE44ohNqTipFGY0lx5up7fjOCkJ4cv8PRchKJhAlrtExdVebI_KtiYcaUvwENsdwP9F1mGEMA_2GkpgCH5JqmiDqRuTwcB1xiiK_d8_dRLY5U4olGbp6lT-Uk0riMHXh_ar5lmAT_bsODh0j8TMLODdZqjaCspAimFV8Y9AQ-Z4W_H1fQ5e-ZTHeLrEySttkQNNvEkBnHgOGYTNSEMkPETKSsaNz1m00 -**Step 1:**: The user initiates a new operation that necessitates the acquisition of a Wallet Attestation. +**Step 1:**: The User initiates a new operation that necessitates the acquisition of a Wallet Attestation. **Steps 2-3:**: The Wallet Instance check if a Wallet Hardware Key exist and generates an ephemeral asymmetric key pair. From 5c50e8de3e641e435c5a808e92df9a81150bcb37 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 18 Mar 2024 23:25:21 +0100 Subject: [PATCH 06/24] chore: Wallet Attestation editorials and some normative verbs --- docs/en/wallet-attestation.rst | 89 +++++++++++++++------------------- docs/en/wallet-solution.rst | 2 + 2 files changed, 41 insertions(+), 50 deletions(-) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index bc3531f11..7bb165e9f 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -5,38 +5,29 @@ 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. -- MUST ensure that the Wallet Instance is genuine, preventing any attempts at manipulation or falsification by unauthorized third parties. -- MUST ensure that private keys have been generated and securely stored within a trusted execution environment. -- 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. - -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. The Wallet Attestation MUST NOT be issued by the Wallet Provider if the Wallet Instance has been revoked. -10. The Wallet Attestation SHOULD be designed to be pseudo-anonymous, meaning it does not directly reference any individual, thereby making it impossible to identify a person without supplementary information. -11. When the private key associated with the Wallet Instance is lost or deleted, the Wallet Attestation MUST become invalid to prevent unauthorized use of the Wallet Instance. - +- The Wallet Attestation MUST be issued and MUST be signed by Wallet Provider; +- 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 Attestation MUST ensure the integrity and authenticity of the Wallet Instance, verifying that it was accurately created and provided by the Wallet Provider. +- The Wallet Attestation MUST ensure that the Wallet Instance is genuine, preventing any attempts at manipulation or falsification by unauthorized third parties. +- The Wallet Attestation MUST ensure that private keys have been generated and securely stored within a trusted execution environment. +- 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 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 SHOULD have an expiration date time, after which it will no longer be considered valid. +- The Wallet Attestation MUST NOT be issued by the Wallet Provider if the Wallet Instance has been revoked. +- 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). +- 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`_. +- When the private key associated with the Wallet Instance is lost or deleted, the Wallet Attestation MUST become invalid to prevent unauthorized use of the Wallet Instance. Static Component View --------------------- @@ -70,8 +61,7 @@ Wallet Instance initialization and registration **Federation Check:** The Wallet Instance needs to check if the Wallet Provider is part of the Federation, obtaining its protocol specific Metadata. A non-normative example of a response from the endpoint **.well-known/openid-federation** with the **Entity Configuration** and the **Metadata** of the Wallet Provider is represented within the section `Wallet Provider metadata`_. -**Steps 3-5:**: The Wallet Instance 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 in inspired by `OAuth 2.0 Nonce Endpoint`_. +**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`_. .. code-block:: http @@ -90,9 +80,9 @@ This endpoint in inspired by `OAuth 2.0 Nonce Endpoint`_. **Step 6**: The Wallet Instance, through the operating system, creates a pair of Wallet Hardware Keys and stores the corresponding Wallet Hardware Key Tag in local storage once the following requirements are met: - 1. It MUST ensure that Wallet Hardware Keys do not already exist, if they exist and the Wallet is in the initialization phase they must be deleted. - 2. It MUST generate a pair of asymmetric EC keys (Wallet Hardware Keys) via a local WSCD. - 3. It SHOULD obtain a unique identifier (Wallet Hardware Key Tag) for the generated Wallet Hardware Keys from the operating system. If the operating system permits specifying a tag during the creation of keys, then a random string for the Wallet Hardware Key Tag must be selected. This random value MUST be collision-resistant and unpredictable to ensure security. To achieve this, consider using a cryptographic hash function or a secure random number generator provided by the operating system or a reputable cryptographic library. + 1. It MUST ensure that Wallet Hardware Keys do not already exist, if they exist and the Wallet is in the initialization phase they MUST be deleted. + 2. It MUST generate a pair of asymmetric Elliptic Curve keys (Wallet Hardware Keys) via a local WSCD. + 3. It SHOULD obtain a unique identifier (Wallet Hardware Key Tag) for the generated Wallet Hardware Keys from the operating system. If the operating system permits specifying a tag during the creation of keys, then a random string for the Wallet Hardware Key Tag MUST be selected. This random value MUST be collision-resistant and unpredictable to ensure security. To achieve this, consider using a cryptographic hash function or a secure random number generator provided by the operating system or a reputable cryptographic library. 4. If the previous points are satisfied, It MUST store the Wallet Hardware Key Tag in a local storage. .. note:: @@ -104,17 +94,17 @@ This endpoint in inspired by `OAuth 2.0 Nonce Endpoint`_. .. 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 document (attestation). Additionally, it offers the verifiable proof that a specific app instance (Wallet Instance) is authentic, unaltered, and in its original state using a specialized signed document (assertion) made for this scope. + **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 both the attestation and the assertion, such as the device type, model, app version, operating system version, bootloader status, and other relevant information to assess the device has not been compromised. For Android the service used is `Key Attestation`_ in addition to `Play Integrity API`_, while for iOS the `DeviceCheck`_ service. + 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 certificate to sign the Key Attestation, thereby not only verifying the integrity of the Wallet Instance but also confirming that the Wallet Hardware Keys are securely managed by the operating system (hardware-backed). +* Uses an OEM private key to sign the Key Attestation, therefore verifieable with the related OEM certificate, confirming that the Wallet Hardware Keys are securely managed by the operating system. -**Step 9**: The Wallet Instance sends the ``challenge`` with Key Attestation and Wallet Hardware Key Tag to the Wallet Provider Backend in order to register the Wallet Instance identified by the Wallet Hardware Key public key. +**Step 9**: The Wallet Instance sends the ``challenge`` with Key Attestation and Wallet Hardware Key Tag to the Wallet Provider Backend in order to register the Wallet Instance identified with the Wallet Hardware Key public key. .. note:: @@ -134,29 +124,29 @@ This endpoint in inspired by `OAuth 2.0 Nonce Endpoint`_. } .. note:: - It is not necessary to send the Wallet Hardware public key as it is already included in the ``key_attestation``. + It is not necessary to send the Wallet Hardware public key because it is already included in the ``key_attestation``. -**Steps 10-12**: The Wallet Provider validate the ``challenge`` and ``key_attestation`` signature: +**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. + 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 Wallet 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. + 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 *application/json* as the content type and MUST include the following parameters: +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 only the registration of authentic and unaltered app instances. Any other claims submitted will not undergo validation, leading the endpoint to respond with an error. Additionally, the inclusion of a challenge helps prevent replay attacks. The authenticity of both the challenge and the ``hardware_key_tag`` is ensured by the signature found within the ``key_attestation``. +.. 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 @@ -171,14 +161,14 @@ This section describes the Wallet Attestation format and how the Wallet Provider **Step 1:**: The User initiates a new operation that necessitates the acquisition of a Wallet Attestation. -**Steps 2-3:**: The Wallet Instance check if a Wallet Hardware Key exist and generates an ephemeral asymmetric key pair. +**Steps 2-3:**: The Wallet Instance checks if a Wallet Hardware Key exists and generates an ephemeral asymmetric key pair. The Wallet Instance also: - 1. It MUST ensure that Wallet Hardware Keys exist. If they do not exist, it is necessary to reinitialize the Wallet. - 2. It MUST generates an ephemeral asymmetric key pair whose public key will be linked with the Wallet Attestation. - 3. it MUST check if Wallet Provider is part of the federation and obtain its metadata. + 1. MUST ensure that Wallet 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. +**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 @@ -216,9 +206,9 @@ Below a non-normative example of the ``client_data``. **Steps 8-10**: The Wallet Instance takes the following steps: - * Produces an hardware_signature by signing the ``client_data_hash`` with the Wallet Hardware's private key, serving as a Proof of Possession (PoP) for the Wallet Hardware Keys. - * Requests the Device Integrity Service to create an ``integrity_assertion`` linked to the ``client_data_hash``. - * Receives a signed ``integrity_assertion`` from the Device Integrity Service, authenticated by the OEM. + * 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 Wallet 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. @@ -359,7 +349,6 @@ Below an non-normative example of the Wallet Attestation without encoding and si eyJhbGciOiJFUzI1NiIsInR5cCI6IndhbGx... redacted - .. _table_wallet_attestation_request_claim: Wallet Attestation Request diff --git a/docs/en/wallet-solution.rst b/docs/en/wallet-solution.rst index 4a2036b1f..edf72fdd1 100644 --- a/docs/en/wallet-solution.rst +++ b/docs/en/wallet-solution.rst @@ -13,6 +13,7 @@ The mobile app serves as the primary interface for Users, allowing them to acces 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 ^^^^^^^^^^^^^^^^^^^^ @@ -22,6 +23,7 @@ Requirements - **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. From 24ab089f527215b6fe0dcf68ed70a30bd1ddcd7f Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 18 Mar 2024 23:40:47 +0100 Subject: [PATCH 07/24] chore: wallet solution editorials --- docs/en/wallet-solution.rst | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/en/wallet-solution.rst b/docs/en/wallet-solution.rst index edf72fdd1..386d10ef9 100644 --- a/docs/en/wallet-solution.rst +++ b/docs/en/wallet-solution.rst @@ -5,18 +5,18 @@ 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. @@ -26,11 +26,11 @@ Requirements 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 MAY be 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. Wallet Instance Lifecycle ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -38,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. @@ -46,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. +In order to securely and unambiguously identify Users, the Wallet Instance requires a Level of Assurance (LoA) 3, which guarantees both the User's identity and the device security. The authentication method is chosen by the PID Provider from among the notified eID solutions at the national level. 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. From 24d44af5085f3f7de6969a6db7e89e92a9a21fc6 Mon Sep 17 00:00:00 2001 From: grausof Date: Tue, 19 Mar 2024 10:41:21 +0100 Subject: [PATCH 08/24] Remove type --- docs/en/wallet-attestation.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index bc3531f11..ccf1d019c 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -240,7 +240,6 @@ Below an non-normative example of the Wallet Attestation Request JWT without enc "iss": "https://wallet-provider.example.org/instance/vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c", "sub": "https://wallet-provider.example.org/", "challenge": "6ec69324-60a8-4e5b-a697-a766d85790ea", - "type": "WalletAttestationRequest", "hardware_signature": "KoZIhvcNAQcCoIAwgAIB...redacted", "integrity_assertion": "o2NmbXRvYXBwbGUtYXBwYX...redacted", "hardware_key_tag": "WQhyDymFKsP95iFqpzdEDWW4l7aVna2Fn4JCeWHYtbU=", @@ -408,9 +407,6 @@ The body of the Wallet Attestation Request JWT MUST contain: * - **challenge** - Challenge data obtained from ``nonce`` endpoint - - * - **type** - - It MUST be set to string "WalletAttestationRequest". - - * - **hardware_signature** - The signature of ``client_data`` obtained using Wallet Hardware Key base64 encoded. - From 11ad59eb7792cfb8c9a514819fbc61d1ae97b6d1 Mon Sep 17 00:00:00 2001 From: grausof Date: Tue, 19 Mar 2024 10:41:30 +0100 Subject: [PATCH 09/24] Remove type --- docs/en/wallet-attestation.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index ccf1d019c..523d9b32d 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -468,9 +468,6 @@ The body of the Wallet Attestation JWT MUST contain: * - **iat** - UNIX Timestamp with the time of JWT issuance. - :rfc:`9126` and :rfc:`7519`. - * - **type** - - It MUST be set to string "WalletAttestation". - - * - **cnf** - JSON object, containing the public part of an asymmetric key pair owned by the Wallet Instance. - :rfc:`7800` From caf862c4edcb181c61bc60012c5a5f3a38827171 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Tue, 19 Mar 2024 11:31:03 +0100 Subject: [PATCH 10/24] chore: standards editorials and removed unused token revocation --- docs/common/standards.rst | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) 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". From f07b746cc55769ed91a44fc51d5270df96faeb1b Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Wed, 20 Mar 2024 00:17:00 +0100 Subject: [PATCH 11/24] defind terms removea misleading element, wallet solution removed auth endpoint pointing to SIOP --- docs/en/defined-terms.rst | 2 -- docs/en/wallet-attestation.rst | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index 8184dc83c..067b20e73 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 diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index 7bb165e9f..e2a031cfd 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -471,7 +471,7 @@ The body of the Wallet Attestation JWT MUST contain: - JSON String asserting the authentication level of the Wallet and the key as asserted in the cnf claim. - * - **authorization_endpoint** - - URL of the SIOPv2 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. From 4defabe6b0e0e567fe4ea992f77c0ee62adc52a7 Mon Sep 17 00:00:00 2001 From: Francesco Grauso Date: Wed, 20 Mar 2024 12:54:39 +0100 Subject: [PATCH 12/24] Apply suggestions from code review Co-authored-by: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> --- docs/en/wallet-attestation.rst | 12 +++++------- docs/en/wallet-solution.rst | 2 +- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index c9497821b..467b2b2bc 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -12,19 +12,17 @@ Requirements The following requirements for the Wallet Attestation are met: -- The Wallet Attestation MUST be issued and MUST be signed by Wallet Provider; - 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 Attestation MUST ensure the integrity and authenticity of the Wallet Instance, verifying that it was accurately created and provided by the Wallet Provider. -- The Wallet Attestation MUST ensure that the Wallet Instance is genuine, preventing any attempts at manipulation or falsification by unauthorized third parties. +- 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 ensure that private keys have been generated and securely stored within a trusted execution environment. - 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 public key. +- 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 SHOULD have an expiration date time, after which it will no longer be considered valid. -- The Wallet Attestation MUST NOT be issued by the Wallet Provider if the Wallet Instance has been revoked. -- 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). +- 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`_. - When the private key associated with the Wallet Instance is lost or deleted, the Wallet Attestation MUST become invalid to prevent unauthorized use of the Wallet Instance. diff --git a/docs/en/wallet-solution.rst b/docs/en/wallet-solution.rst index 386d10ef9..5190bacfb 100644 --- a/docs/en/wallet-solution.rst +++ b/docs/en/wallet-solution.rst @@ -30,7 +30,7 @@ The Wallet Instance serves as a unique and secure device for authenticating the 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 MAY be 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 ^^^^^^^^^^^^^^^^^^^^^^^^^ From 4eb0fb9fb348c7c8ba73f2fba72c3f85a6169e7f Mon Sep 17 00:00:00 2001 From: Francesco Grauso Date: Wed, 20 Mar 2024 12:55:11 +0100 Subject: [PATCH 13/24] Update docs/en/defined-terms.rst Co-authored-by: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> --- docs/en/defined-terms.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index 067b20e73..fb746ec2e 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -89,5 +89,7 @@ Acronyms - Application Programming Interface * - **LoA** - Level of Assurance + * - **AAL** + - Authenticator Assurance Level as defined in ``_ * - **WSCD** - Wallet Secure Cryptographic Device From 3a37a32f25a4dd66081037424f42926d2d8bfdae Mon Sep 17 00:00:00 2001 From: Francesco Grauso Date: Thu, 21 Mar 2024 15:13:21 +0100 Subject: [PATCH 14/24] Update docs/en/wallet-attestation.rst Co-authored-by: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> --- docs/en/wallet-attestation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index 467b2b2bc..d0719aa16 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -16,7 +16,7 @@ The following requirements for the Wallet Attestation are met: - 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 ensure that private keys have been generated and securely stored within a trusted execution environment. +- The private keys MUST be generated and securely stored in the WSCD. It MAY be internal, external, or hybrid depending on the AAL required. - 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. From d8fcbb524494599ec782a45c6f939654792463fa Mon Sep 17 00:00:00 2001 From: grausof Date: Mon, 25 Mar 2024 09:52:20 +0100 Subject: [PATCH 15/24] refactor --- 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 d0719aa16..76aa97e6a 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -25,7 +25,6 @@ The following requirements for the Wallet Attestation are met: - 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`_. -- When the private key associated with the Wallet Instance is lost or deleted, the Wallet Attestation MUST become invalid to prevent unauthorized use of the Wallet Instance. Static Component View --------------------- From d80d97a03b791a2f4bb0ea5708c34085815b7800 Mon Sep 17 00:00:00 2001 From: grausof Date: Mon, 25 Mar 2024 10:43:15 +0100 Subject: [PATCH 16/24] Add Warning --- docs/en/wallet-attestation.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index 76aa97e6a..560db2f2d 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -26,6 +26,9 @@ The following requirements for the Wallet Attestation are met: - 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`_. +.. warning:: + The implementation profile specification, that will be given below, MUST support only the Internal WSCD. Future versions of this specification MAY include other approaches depending on the AAL required. + Static Component View --------------------- @@ -123,6 +126,12 @@ Wallet Instance initialization and registration .. 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. @@ -490,4 +499,4 @@ The body of the Wallet Attestation JWT MUST contain: .. _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 From 7aae53b29d02408a208b7ce3535842576909b2cc Mon Sep 17 00:00:00 2001 From: grausof Date: Mon, 25 Mar 2024 10:53:42 +0100 Subject: [PATCH 17/24] Add Warning --- docs/en/wallet-attestation.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index 560db2f2d..70bad7ca4 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -16,7 +16,6 @@ The following requirements for the Wallet Attestation are met: - 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 private keys MUST be generated and securely stored in the WSCD. It MAY be internal, external, or hybrid depending on the AAL required. - 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. @@ -25,6 +24,9 @@ The following requirements for the Wallet Attestation are met: - 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`_. +- The private keys MUST be generated and stored in the WSCD following different approaches: + - internal + - external .. warning:: The implementation profile specification, that will be given below, MUST support only the Internal WSCD. Future versions of this specification MAY include other approaches depending on the AAL required. From c19cebfddbc66062b4099cec1f7ee89ede5b4d89 Mon Sep 17 00:00:00 2001 From: grausof Date: Mon, 25 Mar 2024 12:15:06 +0100 Subject: [PATCH 18/24] Include other wscd technologies --- docs/en/defined-terms.rst | 2 +- docs/en/wallet-attestation.rst | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index fb746ec2e..922660d0f 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -38,7 +38,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 - - Hardware-backed secure environment for creating, storing, and/or managing cryptographic keys and data. Examples include Secure Elements (SE), Trusted Execution Environments (TEEs), and Strongbox. + - 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. * - Device Integrity Service diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index 70bad7ca4..fd488b8e6 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -25,11 +25,13 @@ The following requirements for the Wallet Attestation are met: - 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`_. - The private keys MUST be generated and stored in the WSCD following different approaches: - - internal - - external + + - **Internal WSCD**: The WSCD here is solely based on the native cryptographic hardware of the User device, for instance the (iOS) Secure Enclave or the (Android) Hardware Backed Keystore or Strongbox. + - **External WSCD**: The WSCD here is based on a remote Hardware Security Module (HSM) hosted by (or on behalf of) the Wallet Provider or is a chip external to the User device, e.g., a smart card based on GlobalPlatform, and supporting JavaCard. + - **Hybrid WSCD**: The WSCD here is based on a dedicated, internal chip integrated in the User device, e.g. an eUICC based on GlobalPlatform, and supporting JavaCard. .. warning:: - The implementation profile specification, that will be given below, MUST support only the Internal WSCD. Future versions of this specification MAY include other approaches depending on the AAL required. + The implementation profile specification, that will be given below, MUST support only the **Internal WSCD**. Future versions of this specification MAY include other approaches depending on the `AAL` required. Static Component View --------------------- From dae1758cf47951f1cb44f9f8ac24ac9f3b0beb8c Mon Sep 17 00:00:00 2001 From: grausof Date: Mon, 25 Mar 2024 12:17:27 +0100 Subject: [PATCH 19/24] Rename Wallet Hardware Key Tag to Cryptographic Hardware Key --- docs/en/defined-terms.rst | 8 +++--- docs/en/wallet-attestation.rst | 30 +++++++++++------------ images/wallet_instance_acquisition.svg | 2 +- images/wallet_instance_initialization.svg | 2 +- 4 files changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index 922660d0f..66f729518 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -43,10 +43,10 @@ Below are the description of acronyms and definitions which are useful for furth - Verifiable Attestation proving that a related Digital Credential is not revoked. * - 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. - * - Wallet 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 Wallet Hardware Keys are confined to the OS domain and are not designed for signing arbitrary payloads. Their primary role is to provide a unique identification for each Wallet Instance. - * - Wallet Hardware Key Tag - - A unique identifier created by the operating system for the Wallet Hardware Keys, utilized to gain access to the private key stored in the hardware. + * - 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) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index fd488b8e6..2394d43b1 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -82,19 +82,19 @@ Wallet Instance initialization and registration "nonce": "d2JhY2NhbG91cmVqdWFuZGFt" } -**Step 6**: The Wallet Instance, through the operating system, creates a pair of Wallet Hardware Keys and stores the corresponding Wallet Hardware Key Tag in local storage once the following requirements are met: +**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 Wallet Hardware Keys do not already exist, if they exist and the Wallet is in the initialization phase they MUST be deleted. - 2. It MUST generate a pair of asymmetric Elliptic Curve keys (Wallet Hardware Keys) via a local WSCD. - 3. It SHOULD obtain a unique identifier (Wallet Hardware Key Tag) for the generated Wallet Hardware Keys from the operating system. If the operating system permits specifying a tag during the creation of keys, then a random string for the Wallet Hardware Key Tag MUST be selected. This random value MUST be collision-resistant and unpredictable to ensure security. To achieve this, consider using a cryptographic hash function or a secure random number generator provided by the operating system or a reputable cryptographic library. - 4. If the previous points are satisfied, It MUST store the Wallet Hardware Key Tag in a local storage. + 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 Wallet Hardware Key Tag to acquire the Key Attestation. +**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:: @@ -106,9 +106,9 @@ Wallet Instance initialization and registration * 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 Wallet Hardware Keys are securely managed by the operating system. +* 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 Wallet Hardware Key Tag to the Wallet Provider Backend in order to register the Wallet Instance identified with the Wallet Hardware Key public key. +**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:: @@ -141,7 +141,7 @@ Wallet Instance initialization and registration 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 Wallet Hardware Key Tag and all useful information related to the device. + 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 @@ -171,9 +171,9 @@ This section describes the Wallet Attestation format and how the Wallet Provider **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 Wallet Hardware Key exists and generates an ephemeral asymmetric key pair. The Wallet Instance also: +**Steps 2-3:**: The Wallet Instance checks if a Cryptographic Hardware Key exists and generates an ephemeral asymmetric key pair. The Wallet Instance also: - 1. MUST ensure that Wallet Hardware Keys exist. If they do not exist, it is necessary to reinitialize the Wallet. + 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. @@ -216,7 +216,7 @@ Below a non-normative example of the ``client_data``. **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 Wallet Hardware Keys. + * 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. @@ -288,7 +288,7 @@ encoded in ``application/x-www-form-urlencoded`` format: 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 Wallet Hardware Key public key registered and associated with the Wallet Instance. + 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. @@ -407,13 +407,13 @@ The body of the Wallet Attestation Request JWT MUST contain: - Challenge data obtained from ``nonce`` endpoint - * - **hardware_signature** - - The signature of ``client_data`` obtained using Wallet Hardware Key base64 encoded. + - 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 **Wallet Hardware Keys** + - Unique identifier of the **Cryptographic Hardware Keys** - * - **cnf** - JSON object, containing the public part of an asymmetric key pair owned by the Wallet Instance. diff --git a/images/wallet_instance_acquisition.svg b/images/wallet_instance_acquisition.svg index d2e72c79e..040a35eb4 100644 --- a/images/wallet_instance_acquisition.svg +++ b/images/wallet_instance_acquisition.svg @@ -1 +1 @@ -UserWallet InstanceDevice Integrity ServiceWallet Provider backend1Request a new operation thatrequires aWallet Attestation2Check ifWallet 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)8GenerateWallet 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,Wallet Hardware Key Tag,public_jwksigned with ephemeralJWK12Send Wallet Attestation RequestCheck if Wallet Instance is initialized and validusing Wallet Hardware Key tag andhardware_signature13Validatechallenge14Validateintegrity_assertion15Validatehardware_signature16ValidateJWKPoP17CreateWallet Attestation18Wallet Attestation \ No newline at end of file +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 index f9afb7bc0..5f5237a06 100644 --- a/images/wallet_instance_initialization.svg +++ b/images/wallet_instance_initialization.svg @@ -1 +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 usechallenge5challenge6GenerateWallet Hardware Keyspair and storeWallet Hardware Key Tag7attestKey(challenge, Wallet Hardware Key Tag)8Key Attestationsigned by OEM9Sendchallenge,Key AttestationandWallet Hardware Key Tag10Validatechallenge11ValidateKey Attestation12StoreWallet Hardware Keys13OK14Wallet Instance Initialized \ No newline at end of file +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 From fbedf3bda4c30bf48107a27f33b4a3e8042b4fae Mon Sep 17 00:00:00 2001 From: grausof Date: Mon, 25 Mar 2024 12:19:53 +0100 Subject: [PATCH 20/24] Rename Wallet Hardware Key Tag to Cryptographic Hardware Key --- docs/en/wallet-attestation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index 2394d43b1..f1df6d46f 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -52,7 +52,7 @@ Wallet Instance initialization and registration .. 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/TLFHRjD047o_hrYb3xHM-84ye288QLMWY1HuNjiRPnNdpjfR1yBNisUd8RRY1rkdlPdPcR5y7nL5sttjiDNWstrEuhPS4cn2q3pySMyQ0t313Nfr3WiD0hCVaMG66A6rWxj0mEmNrZKfF7fJzWLrA6mQ6A8-qe4BCfHI9Qn7M9FOv0H7ZN0J6s5VLKBahsxu9k5WHWLoB7RaouwQ5pldAWbj0y7NHsYRu6734XNO71aJbMqKDg1RIiPSYl3sdPqMq9KHNs_WjYSQu2u5vmDgJx7dnFYmfM87l86fGC2Mvu1SOrwJS-A34eG3IHAQcrsu-VouUdXPVLyklxfURXpG9581hwO_aGtx6EXB2BaYUs0plYV54XMTrT5jSgxtQdiMi2A5B2ksITrNb6NdK5rjzfo1dYIDWoTGtbEgO4HDwBw3qKL90zLpLMTLmvy2Fg2Klr48dkWOiyn2idIHeWQPmC4BLbbsaaMD2q1LYcfNjsSRSvXWthd4-MyyZTzt_AvFyn2vybH2VeJdvPUByjPMwJ3f_2hVx4yRdwxy9zPSeevQlWeOBnt0rjFDnU5NUtwwygdiClqE2nZznNPWPRFmbyfBcb6S5UFkxTNkwty0 + :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 **Step 1:**: The User starts the Wallet Instance mobile app for the first time. @@ -167,7 +167,7 @@ This section describes the Wallet Attestation format and how the Wallet Provider .. 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/VLHFJzjE4BtlfnZ1uGTHVfTAxG6f5OXIe5GL0bekID7O7knfd5rtT-oKVlhEEdySXsqFbbZspNjltixaD0XwQHUrmLQSRHSPULDnGV3id6Jkb_clKG3dtA0LOp0Nv-7WMo1_01YW3OhVGS318zOr2LnRPROvzIXi6XYZFbB7EIbAgFGiBt1FlkCD72N0OMWysxBqH3QfSEjTfqOzP9ZFoHPzQPRFZJ7HrVyVLFK4xkXdIq40mT8IN4CUXPq5gL2UhDTRzgIIC9ciUSz4jA17JIQnOUvGAFPWz5lJdbUKpu6VXx8hzCKIFS4DlOJ915X9E-GQivhCJkKbsUWXQbgWfgA57ckOqmiqo5u9Fp_UgB3nrgciwyX7xQbs1eTVhY-l7YxlBYw-cfM3_InKDMO5xbax9FX4nQPXj0MuJ90ji0HOa621WaQJwvNCsgJgH9EYHl8gijkITdE82UlN0uTkm5a2uGN5YTWhZUXry-EBWaQi9XLJBAcPhCoYsrc5eT9mCS3zrTcRj--EjdnJQDgivdpsOpa_JZ6bdqh9RjtjapvrjVxlB71fKLfFUlSUukbety8KbZtLR5kaxpSJBBVAAE44ohNqTipFGY0lx5up7fjOCkJ4cv8PRchKJhAlrtExdVebI_KtiYcaUvwENsdwP9F1mGEMA_2GkpgCH5JqmiDqRuTwcB1xiiK_d8_dRLY5U4olGbp6lT-Uk0riMHXh_ar5lmAT_bsODh0j8TMLODdZqjaCspAimFV8Y9AQ-Z4W_H1fQ5e-ZTHeLrEySttkQNNvEkBnHgOGYTNSEMkPETKSsaNz1m00 + :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. From 6b1fc3b58a2e935b35cf4e96fafbc98d1757324a Mon Sep 17 00:00:00 2001 From: Francesco Grauso Date: Wed, 3 Apr 2024 17:14:37 +0200 Subject: [PATCH 21/24] Apply suggestions from code review Co-authored-by: Giuseppe De Marco --- docs/en/wallet-attestation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index f1df6d46f..925c28dee 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -46,7 +46,7 @@ Dynamic Component View 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. -Wallet Instance initialization and registration +Wallet Instance Initialization and Registration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. figure:: ../../images/wallet_instance_initialization.svg @@ -280,7 +280,7 @@ encoded in ``application/x-www-form-urlencoded`` format: Content-Type: application/x-www-form-urlencoded grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer - &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6ImtoakZWTE9nRjNHeG...redacted + &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6ImtoakZWTE9nRjNHeG... **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: From 4f46cd634bd1dbe677c6c4da6935c0496d471dae Mon Sep 17 00:00:00 2001 From: Francesco Grauso Date: Wed, 3 Apr 2024 17:15:40 +0200 Subject: [PATCH 22/24] Apply suggestions from code review Co-authored-by: Giuseppe De Marco --- docs/en/wallet-attestation.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index 925c28dee..65d6ecc87 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -24,14 +24,14 @@ The following requirements for the Wallet Attestation are met: - 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`_. -- The private keys MUST be generated and stored in the WSCD following different approaches: +- Private keys MUST be generated and stored in the WSCD using at least one of the approaches listed below: - - **Internal WSCD**: The WSCD here is solely based on the native cryptographic hardware of the User device, for instance the (iOS) Secure Enclave or the (Android) Hardware Backed Keystore or Strongbox. - - **External WSCD**: The WSCD here is based on a remote Hardware Security Module (HSM) hosted by (or on behalf of) the Wallet Provider or is a chip external to the User device, e.g., a smart card based on GlobalPlatform, and supporting JavaCard. - - **Hybrid WSCD**: The WSCD here is based on a dedicated, internal chip integrated in the User device, e.g. an eUICC based on GlobalPlatform, and supporting JavaCard. + - **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. + - **External WSCD**: Here, the WSCD utilizes a remote Hardware Security Module (HSM) managed by (or on behalf of) the Wallet Provider, or it could be an hardware external to the User's device, such as a smart card compliant with _GlobalPlatform_ and supporting _JavaCard_. + - **Hybrid WSCD**: In this case, 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_. .. warning:: - The implementation profile specification, that will be given below, MUST support only the **Internal WSCD**. Future versions of this specification MAY include other approaches depending on the `AAL` required. + At the current stage, the current implementation profile defined in this document supports only the **Internal WSCD**. Future versions of this specification MAY include other approaches depending on the required `AAL` . Static Component View --------------------- From e6916c69a34193d04f91ea67f99165414a0c3ee6 Mon Sep 17 00:00:00 2001 From: Francesco Grauso Date: Thu, 4 Apr 2024 09:34:22 +0200 Subject: [PATCH 23/24] Apply suggestions from code review Co-authored-by: Giuseppe De Marco --- docs/en/wallet-attestation.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index 65d6ecc87..3448b4504 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -26,12 +26,15 @@ The following requirements for the Wallet Attestation are met: - 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: - - **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. - - **External WSCD**: Here, the WSCD utilizes a remote Hardware Security Module (HSM) managed by (or on behalf of) the Wallet Provider, or it could be an hardware external to the User's device, such as a smart card compliant with _GlobalPlatform_ and supporting _JavaCard_. - - **Hybrid WSCD**: In this case, 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_. + - **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 **Internal WSCD**. Future versions of this specification MAY include other approaches depending on the required `AAL` . + 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 --------------------- From 07b4dea7bdc152eaa92755b4d803c4c8c625cd7d Mon Sep 17 00:00:00 2001 From: Francesco Grauso Date: Fri, 5 Apr 2024 09:59:49 +0200 Subject: [PATCH 24/24] Update docs/en/wallet-solution.rst Co-authored-by: Giuseppe De Marco --- docs/en/wallet-solution.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/wallet-solution.rst b/docs/en/wallet-solution.rst index 5190bacfb..31fd4893c 100644 --- a/docs/en/wallet-solution.rst +++ b/docs/en/wallet-solution.rst @@ -46,7 +46,7 @@ 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 requires a Level of Assurance (LoA) 3, which guarantees both the User's identity and the device security. 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: