diff --git a/.github/workflows/ci-html.yml b/.github/workflows/ci-html.yml index cc325da43..5d8a5d3e4 100644 --- a/.github/workflows/ci-html.yml +++ b/.github/workflows/ci-html.yml @@ -15,8 +15,24 @@ on: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: + + pre_job: + runs-on: ubuntu-latest + outputs: + should_skip: ${{ steps.skip_check.outputs.should_skip }} + steps: + - id: skip_check + uses: fkirc/skip-duplicate-actions@v3.4.0 + with: + skip_after_successful_duplicate: 'true' + same_content_newer: 'true' + # This workflow contains a single job called "build" - build: + main_job: + + needs: pre_job + if: needs.pre_job.outputs.should_skip != 'true' + # The type of runner that the job will run on runs-on: ubuntu-latest diff --git a/.gitignore b/.gitignore index d37bdfb02..c7c9a9360 100644 --- a/.gitignore +++ b/.gitignore @@ -16,4 +16,17 @@ env build env-preview .venv -.vscode \ No newline at end of file +.vscode +*.py +*.cfg +*.tmpl +*.exe +*.csh +*.fish +*.ps1 +*.9 +v_env/bin/python3 +v_env/bin/python +v_env/bin/pip3 +v_env/bin/pip +v_env/bin/activate diff --git a/docs/common/common_definitions.rst b/docs/common/common_definitions.rst index 4348e4d42..65a32f2c0 100644 --- a/docs/common/common_definitions.rst +++ b/docs/common/common_definitions.rst @@ -45,7 +45,6 @@ .. _JWE: https://datatracker.ietf.org/doc/html/draft-ietf-jose-json-web-encryption .. _JWK: https://datatracker.ietf.org/doc/html/draft-ietf-jose-json-web-key .. _JWS: https://datatracker.ietf.org/doc/html/draft-ietf-jose-json-web-signature -.. _OAuth-DPoP: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-10 .. _EIDAS-ARF: https://github.com/eu-digital-identity-wallet/architecture-and-reference-framework .. _OpenID4VCI: https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html .. _SD-JWT: https://www.ietf.org/archive/id/draft-fett-oauth-selective-disclosure-jwt-02.html @@ -54,7 +53,7 @@ .. _SD-JWT-VC: https://www.ietf.org/id/draft-terbu-sd-jwt-vc-02.html .. _PresentationExch: https://identity.foundation/presentation-exchange/spec/v2.0.0 .. _JARM: https://openid.net/specs/oauth-v2-jarm-final.html -.. _DPOP: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop +.. _RFC 9449: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop .. _RFC 7519: https://www.rfc-editor.org/rfc/rfc7519 .. _OAUTH2: https://www.rfc-editor.org/rfc/rfc6749 .. _OPENID4VC-HAIP: https://vcstuff.github.io/oid4vc-haip-sd-jwt-vc/draft-oid4vc-haip-sd-jwt-vc.html diff --git a/docs/common/standards.rst b/docs/common/standards.rst index 984810ead..dbe099738 100644 --- a/docs/common/standards.rst +++ b/docs/common/standards.rst @@ -10,12 +10,12 @@ Technical References * - `OIDC-FED`_ - 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 - * - `OpenID4VP`_ + * - `OPENID4VP`_ - OpenID for Verifiable Presentations - draft 19 * - `PresentationExch`_ - Presentation Exchange 2.0 for Presentation Definition @@ -53,7 +53,7 @@ Technical References - Lodderstedt, T., Campbell, B., "JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)", November 2022. * - :rfc:`6749` - The OAuth 2.0 Authorization Framework - * - `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` + * - :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)" + * - `OPENID4VC-HAIP`_ - Lodderstedt, T., K. Yasuda, "OpenID4VC High Assurance Interoperability Profile with SD-JWT VC" diff --git a/docs/en/conf.py b/docs/en/conf.py index ea29d0c3c..dd23e066e 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -2,7 +2,7 @@ # -*- coding: utf-8 -*- # -- PROJECT Variables ---------------------------------------------------- -settings_project_name = "Italian eIDAS Wallet Technical Specifications" +settings_project_name = "The Italian EUDI Wallet implementation profile" settings_copyright_copyleft = 'Dipartimento per la Trasformazione Digitale' settings_editor_name = 'Dipartimento per la Trasformazione Digitale' settings_doc_version = 'version: latest' diff --git a/docs/en/contribute.rst b/docs/en/contribute.rst index a7d3a1ace..4eb5e15fc 100644 --- a/docs/en/contribute.rst +++ b/docs/en/contribute.rst @@ -14,3 +14,45 @@ Below are several methods available for contributing to this project: - **GitHub issues**. By opening an issue, you can seek clarification, propose enhancements, or report editorial typos. If you are working on an issue, we encourage you to open a draft pull request and link it. - **Pull requests**. Pull requests represent active contributions to the project, typically, but not always following issue-based discussions. Once a pull request is initiated, it facilitates discussion and review of the proposed changes before they are merged into the main branch (`versione-corrente`). - **Developers Italia Slack channel**. Slack is a messaging application designed for businesses, connecting people to the information they need. *Developers Italia* is an open community based on contributions and participation from public administrations, developers, technicians, students, and citizens. *Developers Italia* has initiated a Slack channel that [everyone can join for free](https://slack.developers.italia.it/), where you can learn about all their activities and partake in discussions. + + +Acknowledgements +---------------- + +We would like to thank the following individuals for their comments, +concerns, ideas, contributions, some of which substantial, to this +implementation profile and to the initial set of implementations. + +- Alen Horvat +- Amir Sharif +- Andrea Prosseda +- Emanuele De Cupis +- Emiliano Vernini +- Francesco Grauso +- Francesco Marino +- Francesco Ventola +- Giada Sciarretta +- Giuseppe De Marco +- Kristina Yasuda +- Leif Johansson +- Lorenzo Cerini +- Marta Sciunnach +- Michele Silletti +- Nicola Saitto +- Paul Bastien +- Pasquale De Rose +- Peter Altmann +- Riccardo Iaconelli +- Roland Hedberg +- Salvatore Laiso +- Salvatore Manfredi +- Stefano Alifuoco +- Takahiko Kawasaki +- Torsten Lodderstedt +- Vladimir Duzhinov + +If anyone has been forgotten, please accept our apologies with the +request to propose the modification of this page via a [Pull Request](https://github.com/italia/eudi-wallet-it-docs) +with a brief description of the contribution offered, during which +event or channel, and during which period. We will then have the opportunity +to apologize again and make amends as soon as possible, including you in the list. diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index 6a0c22037..6f8e1c0e4 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -51,6 +51,8 @@ Below are the description of acronyms and definitions which are useful for furth - An architectural component that enables IT Wallet system participants to establish trust, in terms of reliability and compliance of all participants with the regulatory framework governing the digital identity system. * - Level of Assurance - The degree of confidence in the vetting process used to establish the identity of the User and the degree of confidence that the User who presents the credential is the same User to whom the credential was issued. + * - Holder Key Binding + - Ability of the Holder to prove legitimate possession of the private part, related to the public part attested by a Trusted Third Party. Acronyms -------- diff --git a/docs/en/index.rst b/docs/en/index.rst index 24762f998..b935a03ce 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -1,25 +1,25 @@ .. include:: ../common/common_definitions.rst -============================================= -Italian EUDI Wallet Technical Specifications -============================================= +============================================== +The Italian EUDI Wallet implementation profile +============================================== Introduction ------------ -Across Europe, 21 digital identities (eIDs) currently exist in 16 different Member States. -In its integration effort, the European Council called for the eIDAS Regulation on electronic identification and trust services for electronic transactions in the internal market to be updated by implementing a new tool: the European Digital Identity Wallet. -The European Digital Identity Wallet (EUDI Wallet or EUDIW) project was created to overcome the differences, both in technological and user experience terms, that exist across national experiences towards a uniform digital identity solution so as to enable cross-border access to digital services. +The European Council requested the update of the +eIDAS Regulation on electronic identification and trust services by +implementing a new tool: the `European Digital Identity Wallet `_. Italy responded to the input received from the European community by creating the National digital identity Wallet solution, called IT Wallet, to be fully interoperable with all the other solutions made available by other European Member States and in full compliance to the European regulation. -The current Italian scenario counts 3 coexisting digital identity tools that are partially overlapping, sometimes competing, and based on different technologies. This points to a highly fragmented system which yields difficulties for users and service providers and is ultimately unsustainable. -Therefore, the IT Wallet proposes to rationalise the digital identity ecosystem in Italy in order to simplify the experience of citizens, public administrations, and businesses in accessing digital services. + +The current Italian scenario counts 3 coexisting digital identity tools that are partially overlapping, sometimes competing, and based on different technologies. This points to a highly fragmented system which yields difficulties for users and service providers. Therefore, the IT Wallet proposes to rationalise the digital identity ecosystem in Italy in order to simplify the experience of citizens, public administrations, and businesses in accessing digital services. To achieve these objectives and enhance the already active and eIDAS-notified digital identity schemes, the IT Wallet project entails a technological and governance evolution that envisages the progressive migration of the current threefold digital identification solution towards IT Wallet. The purpose of the following technical rules is to define the technical architecture and reference framework to be used as a guideline by all the parties involved in the development of the IT Wallet project. -In this documentation you can find the technical specification for implementing the components that compose the Wallet ecosystem: +This documentation defines the national implementation profile of EUDI Wallet, containing the technical details about components of the Wallet ecosystem, as listed below: - Entities of the ecosystem according to `EIDAS-ARF`_. - Infrastructure of trust attesting realiability and eligibility of the participants. @@ -27,7 +27,7 @@ In this documentation you can find the technical specification for implementing - PID/EAA in MDL CBOR format. - PID/EAA in `SD-JWT`_ format. - Wallet Solution general architecture. - - Wallet Instance Attestation data model in `JWS`_ format. + - Wallet Instance Attestation. - Issuance of PID/EAA according to `OpenID4VCI`_. - Presentation of PID/EAA according to `OpenID4VP`_. - Presentation of pseudonyms according to `SIOPv2`_. diff --git a/docs/en/pid-eaa-data-model.rst b/docs/en/pid-eaa-data-model.rst index a8405e23b..dda139908 100644 --- a/docs/en/pid-eaa-data-model.rst +++ b/docs/en/pid-eaa-data-model.rst @@ -7,8 +7,7 @@ PID/(Q)EAA Data Model +++++++++++++++++++++ The Person Identification Data (PID) is issued by the PID Provider following national laws and allows a natural person to be authenitcated and identified. - -The User attributes carried in the Italian PID are: +The User attributes carried within the Italian PID are the ones listed below: - Current Family Name - Current First Name @@ -23,7 +22,7 @@ The (Q)EAAs are issued by (Q)EAA Issuers to a Wallet Instance and MUST be provid The (Q)EAAs are extended according to the `OpenID Identity Assurance Profile [OIDC.IDA] `_, that allows the recipients to know the Authentic Sources where the data comes from. -The PID/(Q)EAA data format and the mechanism through which a digital credential is issued to the Wallet Instance and presented to an RP is described in the following sections. +The PID/(Q)EAA data format and the mechanism through which a digital credential is issued to the Wallet Instance and presented to a Relying Party are described in the following sections. SD-JWT ====== @@ -91,7 +90,7 @@ The following claims MUST be in the JWT payload and MUST NOT be included in the - URL string representing the PID/(Q)EAA Issuer unique identifier. - `[RFC7519, Section 4.1.1] `_. * - **sub** - - Thumbprint of the JWK in the ``cnf`` parameter + - Thumbprint of the JWK in the ``cnf`` parameter. - `[RFC7519, Section 4.1.2] `_. * - **jti** - Unique Token ID identifier of this JWT. It SHOULD be a String in *uuid4* format. @@ -103,10 +102,10 @@ The following claims MUST be in the JWT payload and MUST NOT be included in the - UNIX Timestamp with the expiry time of the JWT, coded as NumericDate as indicated in :rfc:`7519`. - `[RFC7519, Section 4.1.4] `_. * - **status** - - HTTPS URL where the credential validity status is available + - HTTPS URL where the credential validity status is available. - `[SD-JWT-VC. Section 4.2.2.2] `_. * - **cnf** - - JSON object containing the proof-of-possession key materials. By including a **cnf** (confirmation) claim in a JWT, the issuer of the JWT declares that the presenter is in control of the private key related to the public one defined in the **cnf** parameter. The recipient MUST cryptographically verify that the presenter is in control of that key. + - JSON object containing the proof-of-possession key materials. By including a **cnf** (confirmation) claim in a JWT, the issuer of the JWT declares that the Holder is in control of the private key related to the public one defined in the **cnf** parameter. The recipient MUST cryptographically verify that the Holder is in control of that key. - `[RFC7800, Section 3.1] `_. * - **type** - Credential type as a string, MUST be set in accordance to the type obtained from the PID/(Q)EAA Issuer metadata. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData``. @@ -122,7 +121,7 @@ The following claims MUST be in the JWT payload and MUST NOT be included in the PID/(Q)EAA Verification field ----------------------------- -The ``verification`` claim contains the information regarding the trust framework used by the PID/(Q)EAA Issuer to provide the User claims. Some of these additional claims MAY be selectively disclosed, these are listed in the following tables that specify whether a claim is selectively disclosable (SD) or not (NSD). +The ``verification`` claim contains the information regarding the trust framework used by the PID/(Q)EAA Issuer to provide the User attributes (claims). Some of these additional claims MAY be selectively disclosed, these are listed in the following tables that specify whether a claim is selectively disclosable (SD) or not (NSD). The ``verification`` claim is a JSON structure with all the following mandatory sub-claims. @@ -183,13 +182,13 @@ The ``claims`` parameter contains the User attributes with the following mandato - **Description** - **Reference** * - **given_name** - - [SD]. Current First Name + - [SD]. Current First Name. - `[OpenID Connect Core 1.0, Section 5.1] `_ * - **family_name** - - [SD]. Current Family Name + - [SD]. Current Family Name. - `[OpenID Connect Core 1.0, Section 5.1] `_ * - **birthdate** - - [SD]. Date of Birth + - [SD]. Date of Birth. - `[OpenID Connect Core 1.0, Section 5.1] `_ * - **place_of_birth** - [SD]. Place of Birth. JSON Object with the following subclaims: diff --git a/docs/en/pid-eaa-issuance.rst b/docs/en/pid-eaa-issuance.rst index 33458089b..2b76c8f47 100644 --- a/docs/en/pid-eaa-issuance.rst +++ b/docs/en/pid-eaa-issuance.rst @@ -10,17 +10,17 @@ The relevant entities and interfaces involved in the issuance flow are: - *Wallet Provider*: The entity responsible for releasing an EUDI Wallet Solution. It also issues Wallet Instance Attestations to its Wallet Instances through an Attestation Service. The Wallet Attestation certifies the genuinity and authenticity of the Wallet Instance and its compliance with a Trust Framework in compliance to the security and privacy requirements. - *Wallet Solution*: Entire product and service owned by a Wallet Provider, offered to all the Users of that solution. The Wallet Solution is certified as EUDI-compliant by a Conformity Assessment Body (CAB). - - *Wallet Instance*: Instance of a Wallet Solution, installed on the User device. It provides interfaces for user interaction with the Wallet Provider, Relying Parties, PID, and (Q)EAA Providers. + - *Wallet Instance*: Instance of a Wallet Solution, installed on the User device. It provides interfaces for User interaction with the Wallet Provider, Relying Parties, PID, and (Q)EAA Providers. - *PID Provider*: The entity that issues the eIDAS Person Identification Data (PID). It is composed of: - OpenID4VCI Component: based on the “OpenID for Verifiable Credential Issuance” specification `[OIDC4VCI. Draft 13] `_ to release PID credentials. - - National eID Relying Party (OpenID Connect or SAML2): It represents the component to authenticate the End-User with the national Digital Identity Providers. - - National IdP: It represents preexisting identity systems based on SAML2 or OpenID Connect, already in production in each Member State (for Italy SPID and CIE id authentication schemed notified eIDAS with *LoA* **High**, see `SPID/CIE OpenID Connect Specifications `_). + - National eID Relying Party (OpenID Connect or SAML2): It represents the component to authenticate the User with the national Digital Identity Providers. + - National Identity Provider: It represents preexisting identity systems based on SAML2 or OpenID Connect, already in production in each Member State (for Italy SPID and CIE id authentication schemed notified eIDAS with *LoA* **High**, see `SPID/CIE OpenID Connect Specifications `_). - - *(Q)EAA Issuer*: It represents the Issuer of (Q)EAAs. It is composed of: + - *(Q)EAA Provider*: It represents the Issuer of (Q)EAAs. It is composed of: - OpenID4VCI Component: based on the “OpenID for Verifiable Credential Issuance” specification `[OIDC4VCI. Draft 13] `_ to release (Q)EAAs. - - Relying Party: It represents the component to authenticate the User with the PID. The (Q)EAA Issuer acts as a verifier and it sends a presentation request to the Wallet Instance according to [`OpenID4VP`_]. The Wallet Instance MUST have a valid PID obtained prior to starting a transaction with the (Q)EAA Issuer. + - Relying Party: It represents the component to authenticate the User with the PID. The (Q)EAA Provider acts as a Verifier and it sends a presentation request to the Wallet Instance according to [`OpenID4VP`_]. The Wallet Instance MUST have a valid PID obtained prior to starting a transaction with the (Q)EAA Provider. High-Level PID flow @@ -38,13 +38,13 @@ The :numref:`fig_High-Level-Flow-ITWallet-PID-Issuance` shows a general architec Below a detailed description for each step represented in the previous picture: 0. **Wallet Instance Setup**: the first time the Wallet Instance is started a preliminary setup phase MUST be carried out. It consists of the release of a verifiable proof issued by the Attestation Service provided by the Wallet Provider that asserts the genuineness, the authenticity and the compliance with a trust framework of the Wallet Instance. The verifiable proof binds a public key corresponding to a local private key generated by the Wallet Instance. - 1. **Obtaining the trusted PID Provider**: the Wallet Instance discovers the trusted PID Provider at the Subordinate Listing Endpoint of the Trust Anchor, and then inspects the metadata looking for the availability of the PID credential. - 2. **Obtaining of PID Provider metadata**: the Wallet Instance establishes the trust to the PID Provider according to the Trust Model, obtaining the Metadata that discloses the formats of the PID, the algorithms supported, and any other parameter required for interoperability needs. - 3. **PID request**: following the Authorization Code Flow in `[OIDC4VCI. Draft 13] `_ the Wallet Instance requests a PID to the PID Provider. A fresh key pairs is generated by the Wallet Instance, the public key is used by PID Provider for the key binding of the PID. The PID Provider checks the Wallet Instance by means of the Wallet Attestation and the Trust Chain related to the Wallet Provider. - 4. **End-user authentication**: the PID Provider authenticates the End-User with LoA High, acting as an IAM Proxy to the National eID system. - 5. **PID issuance**: once the User authentication with LoA High happens, the User gives their consent, and the PID Provider releases a PID bound to the key material held by the requesting Wallet Instance. + 1. **Obtaining the trusted PID Provider**: the Wallet Instance discovers the trusted PID Provider using the Federation API (e.g.: using the Subordinate Listing Endpoint of the Trust Anchor and its Intermediates), and then inspects the metadata looking for the availability of the PID credential. + 2. **Obtaining of PID Provider Metadata**: the Wallet Instance establishes the trust to the PID Provider according to the Trust Model, obtaining the Metadata that discloses the formats of the PID, the algorithms supported, and any other parameter required for interoperability needs. + 3. **PID Request**: following the Authorization Code Flow in `[OIDC4VCI. Draft 13] `_ the Wallet Instance requests a PID to the PID Provider. A fresh key pair that is generated by the Wallet Instance for the purpose of the sender-constrained Access Token will be used by the PID Provider for the Holder Key Binding of the PID. + 4. **User Authentication**: the PID Provider authenticates the User with LoA High, acting as an IAM Proxy to the National eID system. + 5. **PID Issuance**: once the User authentication with LoA High happens, the User gives their consent, and the PID Provider releases a PID bound to the key material held by the requesting Wallet Instance. -The Wallet Instance Setup phase is described in Section [...]. In the following Section the steps from 1 to 5 are further expanded into more technical detailed steps. +In the following sections the steps from 1 to 5 are further expanded into more technical details. High-Level (Q)EAA flow ---------------------- @@ -63,39 +63,50 @@ The :numref:`fig_High-Level-Flow-ITWallet-QEAA-Issuance` shows a general archite Below the description of the most relevant operations involved in the (Q)EAA issuance: - 1. **Obtaining the trusted (Q)EAA Issuer**: the Wallet Instance discovers the trusted (Q)EAA Issuer at the Subordinate Listing Endpoint of the Trust Anchor, and then inspects the metadata looking for the credential capabilities. - 2. **Obtaining of (Q)EAA Issuer metadata**: the Wallet Instance establishes the trust to the (Q)EAA Issuer according to the Trust Model, obtaining the Metadata that discloses the formats of the (Q)EAA, the algorithms supported, and any other parameter required for interoperability needs. - 3. **(Q)EAA request**: following the Authorization Code Flow in `[OIDC4VCI. Draft 13] `_ the Wallet Instance requests a (Q)EAA to the (Q)EAA Issuer. A fresh key pairs is generated by the Wallet Instance, the public key is used by (Q)EAA Issuer for the key binding of the (Q)EAA. The (Q)EAA Issuer checks the Wallet Instance by means of the Wallet Attestation and the Trust Chain related to the Wallet Provider. - 4. **End-user authentication**: the (Q)EAA Issuer, acting as a verifier (Relying Party), authenticates the User with the PID. - 5. **(Q)EAA issuance**: once the User has been authenticated with a valid PID, the User gives their consent, then the (Q)EAA Issuer releases a (Q)EAA bound to the key material held by the requesting Wallet Instance. - + 1. **Obtaining the trusted (Q)EAA Issuer**: the Wallet Instance discovers the trusted (Q)EAA Issuer ufing the Federaiton API (e.g.: using the Subordinate Listing Endpoint of the Trust Anchor and its Intermediates), then inspects the metadata looking for the credential capabilities. + 2. **Obtaining of (Q)EAA Provider Metadata**: the Wallet Instance establishes the trust to the (Q)EAA Provider according to the Trust Model, obtaining the Metadata that discloses the formats of the (Q)EAA, the algorithms supported, and any other parameter required for interoperability needs. + 3. **(Q)EAA Request**: according to the Authorization Code Flow in `[OIDC4VCI. Draft 13] `_ the Wallet Instance requests a (Q)EAA to the (Q)EAA Provider. A fresh key pair that is generated by the Wallet Instance for the sender-constrained Access Token TO be used by (Q)EAA Provider for the key binding of the (Q)EAA. The (Q)EAA Provider checks the Wallet Instance by means of the Wallet Instance Attestation and the Trust Chain related to the Wallet Provider. + 4. **User Authentication**: the (Q)EAA Provider, acting as a Verifier (Relying Party), authenticates the User evaluating the presentation of the PID. + 5. **(Q)EAA Issuance**: Once the User has been authenticated with a valid PID, the User gives their consent, then the (Q)EAA Provider releases a (Q)EAA bound to the key material held by the requesting Wallet Instance. Detailed Flow ------------- -The PID/(Q)EAA Issuance phase is based on the **Authorization Code Flow** with **Pushed Authorization Requests** (PAR) [:rfc:`9126`] and **PKCE** (Proof Key for Code Exchange, :rfc:`7636`) as recommended in `[OIDC4VCI. Draft 13. Section 3.4] `_. A *Wallet Initiated Flow* is considered and the User receives the PID/(Q)EAA directly in response to the Credential Request (*Immediate Flow*). +The PID/(Q)EAA Issuance phase is based on the **Authorization Code Flow** with **Pushed Authorization Requests** (PAR) [:rfc:`9126`] and **PKCE** (Proof Key for Code Exchange, :rfc:`7636`) as recommended in `[OIDC4VCI. Draft 13. Section 3.4] `_. A *Wallet Initiated Flow* is involved and the User receives the PID/(Q)EAA directly in response to the Credential Request (*Immediate Flow*). .. warning:: All the non-normative examples are referred to the PID Provider issuance flow. .. _fig_Low-Level-Flow-ITWallet-PID-QEAA-Issuance: + .. figure:: ../../images/Low-Level-Flow-ITWallet-PID-QEAA-Issuance.svg :figwidth: 100% :align: center - :target: https://www.plantuml.com/plantuml/svg/dPJVRnf74CVVzwyOEP5g9AoyMseK7DCOrQgewoYFf-LkW96FtUlkB8J-zPtH7iTYd8h6yeDzy_lpdTbFaMtWj6cDJUnTsYmm6DF9DwgfiuxXwcl4S0KsGZ9cuR_d3xz4Y1lnwjRUuHMyUwJLck_QXAUnTy7lXd1xQljcsnOPPavQS3Mg3-mCkWQaYddJTnxybfe-t-ALptns_-7wpz5qCe5PZAdt8YC_ExZv2EaM_88jETZx5E3eRXBSY7rt2tkCnWJd6S5lCS0Etdrxc3rFJHzeeQN8u9Vm759aRE2ig0wW6L2gtdoKchLtImeRu3L2n1Ph9kyqnNceITA7jE5VJhiOam2UVNbu_l8qdVvXNe63UetrIvG2bhNAUMAW28fAgwh3RoWChVO1rZKzbGZ44JR8jh5iop50uO1C4j2ofF_zyrIcQX2aELeIXjw7n6S-UO8d_3jXPBWE63ll8bQyxt0CTKlekA9c31fUrMiTnAtmzV-LTB7suXPofY7KneX1-oup5fz_VP_P7D1Cc2NSgkdz24gcD5wSC3rZTaRrT0N_Y-a5oIAjdEKKKCBBxCU6ipGgoTQsr13leT34K5xPWNW63TSziIe56WD-xoXWhCYDyX7e5TXRc2J16-YVN6UGgz2dI3CooMeaqFyEDBPbw46GW519JaL8XmFJDmMif9T4LEVyE-ArBhEIq3EAOZiom3QYMdywCyxk9t_1ev_0WpnUFoZYcWDheN06OC2k-pi6LGu7NhiB_OiBMw7J9KAud_ivlE3-XxOkUB-4fGzlN3kmVq47qdldIQOfplDPBODmYg5CLmgv2jRnuSnySxZHmybVV9Aw4Wq5h0yxGNcWt4l9nDOrnbYnVXxd6NBEOeybV-Mygt7uepeQtoIv5DjQKIeiVS8QtGFRdhzhcO7yTZv6Z54LkyvLiaY5_oKw5CKABGOfFX-jvtgKB7GpJrKQ8gi6b-GeSvOcDfR7sMjqSWtzKtVt-7Lgdd15aVKcsbQVdgBDcu2jPMp0aClPb84EbsNFr_CXuDRNsLQyIOEmnMI5kdrtHRMBjIp83c-XCj7pIJ6_hOLxP1-mLFgJz9WsxRy0 - + :target: https://www.plantuml.com/plantuml/svg/dLNTRl964BtVfnWbaHeaezn7QXIIq0GrhIWbogMrs0ECCBlk_a3eqtVMApjhGZ-H3t5XF3DdvfpvuTuwQPpVLa9wfvNVBj08KVCxAgYMoi75cqLp0TA25sAXF-ABNopOBNlLQwtm0YvVQRLs3vN7Vko3qVikNFPjxxAgqC54SGcgmCPdBr2Lm5d4IT-fqJig8nuiZdocawURwxy6uz6exqU2FtiOte6_1RrmaXGSj3Vm6I0y3Dc-luK3MY6CqWv1xz307YxVNoRpiOY18A4Ywq0lOMwyTLZ2YRI1H8F1UOTtdBNGQabc2swDOB72mf5M378oM7YkXKlHctub6R7Ca-UN-VDiFFvJ7Ca7nHgBZUKKqeKyAVJ4Miy8P248ndaRXz-Giycc4icYHu8Mo5du0vqifPCf4GW20NCnA1t3__uuPbub0XT7Iq8JVO3OPpgQmGp_ySXINHkqjLOMStUeCOEY8bGkfp9hmlDY7OYe5Hx_phVerfhTJ4JgGgMrQ4BTAMBo-jUhg4qhpSWv3c-ONWqWrPIoHK_J4-tuecjl57-ewbbmbbPAEc-m1JZkQwo-wrFJdvsig2HtWAH1Wk8CT_97rLd_A5_k3MM07pKPj3cfGTmA3l7o5aQUjJRqRypJzIvfLW8p45usaVJjG24hjaPDo5eVAFOxujkD2sS69CCp41KHVqzk3InheqJ1_DZsgG5M5eFrfv5nyZJw6rxr25xudfrEmW-jrgp2aG29x66OCmYTmomKr8cs_qvGidWhL6ZO04zJFOKD7lxNLXlDmxJKviGH0AStg81Pr9gOLxArSxPqBOo2971fIrT6AjTkdoxRrMqlmTcR6eQZ98D5EnqK2SLQKc5aKQ2rULDy5Zb4p6IY6JzNcjlUFUJfk7yvOP4NVsjjBQDpGSmoHZRkYVzPsh9V6KPALec-dRoFdVM4nYc_C7TzvRl8lCGbAOhQSH5RwRBeDKXdlVsdU7Xz6uiPhiYwCF5L5IvCKkRGOCNCIX2a8Xe3D-HYA-Dkt1ZSwVW8oSNfcfKmIphMLlUPxUp-9CfsbuurQVR2stX24tVhj4bPYNkkqM-h_m00 + PID/(Q)EAA Issuance - Detailed flow -**Steps 1-4 (Discovery):** The User selects the PID/(Q)EAA Issuer, and the Wallet Instance obtains the metadata for the selected PID/(Q)EAA Issuer. -.. note:: +**Steps 1-4 (Discovery):** The User selects the PID/(Q)EAA Provider, and the Wallet Instance obtains the Metadata for the selected PID/(Q)EAA Provider. - **Federation Check:** The Wallet Instance needs to check if the PID/(Q)EAA Issuer is part of the Federation, obtaining then 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 PID/(Q)EAA Issuer is represented within the section `Entity Configuration Credential Issuer`_. +.. note:: + **Federation Check:** The Wallet Instance needs to check if the PID/(Q)EAA Provider is part of the Federation, obtaining then 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 PID/(Q)EAA Provider is represented within the section `Entity Configuration Credential Issuer`_. -**Steps 5-6 (PAR Request):** The Wallet Instance creates a PKCE code verifier that sends in a *pushed authorization request*, using the request parameter (see :rfc:`9126` Section 3) to the PID/(Q)EAA Issuer PAR endpoint. The Wallet Instance signs the request using its private key. A OAuth2 client authentication method is involved, since in this flow the pushed authorization endpoint is a protected endpoint. The client authentication is based on the model defined in [:rfc:`7521`] using the Wallet Instance Attestation JWS inside the **client_assertion** parameter. The authorization_details [RAR :rfc:`9396`] parameter is extended to allow Wallet Instance to specify the types of the credentials when requesting authorization for the PID/(Q)EAA issuance. +**Steps 5-6 (PAR Request):** The Wallet Instance creates a fresh PKCE code verifier, and ``state`` parameter for the *Pushed Authorization Request*. The Wallet Instance sends these parameters along in a *Pushed Authorization Request* using the OIDC ``request`` parameter (hereafter Request Object) (see :rfc:`9126` Section 3) to the PID/(Q)EAA Provider PAR endpoint to prevent Request URI swapping attack (see :rfc:`9126`). The Wallet Instance MUST create the ``code_verifier`` with enough entropy random string using the unreserved characters with a minimum length of 43 characters and a maximum length of 128 characters, making it impractical for an attacker to guess its value. The value MUST be generated following the recommendation in Section 4.1 of :rfc:`7636`. The Wallet Instance signs this request using the private key that is created during the setup phase to obtain the Wallet Instance Attestation. The related public key that is attested by the Wallet Provider is inside the Wallet Instance Attestation ``cnf`` claim.. An OAuth2 client authentication method is involved, since in this flow the Pushed Authorization Endpoint is a protected endpoint. The client authentication is based on the model defined in [:rfc:`7521`] using the Wallet Instance Attestation JWS inside the ``client_assertion`` parameter. The authorization_details [RAR :rfc:`9396`] parameter is extended to allow Wallet Instance to specify the types of credentials when requesting authorization for the PID/(Q)EAA issuance. The PID/(Q)EAA Provider performs the following checks upon the receipt of the PAR request: + + 1. It MUST validate the signature of the Request Object using the algorithm specified in the ``alg`` header parameter (:rfc:`9126`, :rfc:`9101`) and the public key that can be retrieved from the Wallet Instance Attestation (``cnf``) identified using the ``kid`` header of the Request Object. + 2. It MUST check that the used algorithm for signing the request in the ``alg`` header is among the appropriate once reported in Section `Cryptographic Algorithms `_. + 3. It MUST check that the ``client_id`` in the request body of the PAR request matches the ``client_id`` claim in the Request Object. + 4. It MUST check that the ``iss`` claim in the Request Object matches the ``client_id`` claim in the Request Object (:rfc:`9126`, :rfc:`9101`). + 5. It MUST check that the ``aud`` claim in the Request Object is equal to the identifier of PID/(Q)EAA Provider (:rfc:`9126`, :rfc:`9101`). + 6. It MUST reject the PAR request, if it contains the ``request_uri`` parameter (:rfc:`9126`). + 7. It MUST check that the Request Object contains all the mandatory parameters and their values are validated according to what we defined in :ref:`Table of the HTTP parameters ` [derived from :rfc:`9126`]. + 8. It MUST check that the Request Object is not expired by checking the ``exp`` claim (:rfc:`9126`). + 9. It MUST check that the Request Object was issued at a time acceptable by the PID/(Q)EAA Provider by checking the ``iat`` claim. For example, basing on the security policies of the PID/(Q)EAA Provider, it might reject the request if the ``iat`` claim is too far away from the current time (:rfc:`9126`). + 10. It MUST check that the ``jti`` claim in the Request Object has not been used before by the Wallet Instance identified by the ``client_id``. This allows the PID/(Q)EAA Provider to mitigate replay attacks (:rfc:`7519`). Below a non-normative example of the PAR. @@ -113,7 +124,7 @@ Below a non-normative example of the PAR. &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation &client_assertion=$WalletInstanceAttestation$ -The JWS header of request object is represented below: +The JWS header of Request Object is represented below: .. code-block:: JSON @@ -123,11 +134,16 @@ The JWS header of request object is represented below: } -The JWS payload of the request object is represented below: +The JWS payload of the Request Object is represented below: .. code-block:: JSON { + "iss":"$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$", + "aud":"https://pid-provider.example.org", + "exp":1672422065, + "iat": 1672418465, + "jti":"ac80df576e7109686717bf50b869e882", "response_type":"code", "client_id":"$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$", "state":"fyZiOL9Lf2CeKuNT2JzxiLRDink0uPcd", @@ -149,10 +165,15 @@ The JWS payload of the request object is represented below: .. note:: - **Federation Check:** The PID/(Q)EAA Issuer MUST check that the Wallet Provider is part of the federation and in addition it MUST verify the Wallet Instance Attestation validity by checking its signature and data. + **Federation Check:** The PID/(Q)EAA Provider MUST check that the Wallet Provider is part of the federation and in addition it MUST verify the Wallet Instance Attestation validity by checking its signature and data. -**Step 7 (PAR Response):** The PID/(Q)EAA Issuer creates a new request URI representing a new authorization request and returns it to the Wallet Instance. +**Step 7 (PAR Response):** The PID/(Q)EAA Provider MUST issue the ``request_uri`` one-time use and bind it to the client identifier (``client_id``) that is provided in the Request Object. Furthermore, the entropy of the ``request_uri`` MUST be sufficiently large. The adequate shortness of the validity and the entropy of the ``request_uri`` depends on the risk calculation based on the value of the resource being protected. The validity time SHOULD be less than a minute, and the ``request_uri`` MUST include a cryptographic random value of 128 bits or more (:rfc:`9101`). The entire ``request_uri`` SHOULD NOT exceed 512 ASCII characters due to the following two main reasons (:rfc:`9101`): + + 1. Many phones on the market still do not accept large payloads. The restriction is typically either 512 or 1024 ASCII characters. + 2. On a slow connection such as a 2G mobile connection, a large URL would cause a slow response; therefore, the use of such is not advisable from the user-experience point of view. + + The PID/(Q)EAA Provider returns the issued ``request_uri`` to the Wallet Instance. .. code-block:: http @@ -164,10 +185,14 @@ The JWS payload of the request object is represented below: "request_uri":"urn:ietf:params:oauth:request_uri:bwc4JK-ESC0w8acc191e-Y1LTC2", "expires_in": 60 } - -**Steps 8-9 (Authorization Request):** The Wallet Instance sends an authorization request to the PID/(Q)EAA Issuer authorization endpoint. +**Steps 8-9 (Authorization Request):** The Wallet Instance sends an authorization request to the PID/(Q)EAA Provider Authorization Endpoint. Since parts of this Authorization Request content, e.g., the ``code_challenge`` parameter value, are unique to a particular Authorization Request, the Wallet Instance MUST only use a ``request_uri`` value once (:rfc:`9126`); The PID/(Q)EAA Provider performs the following checks upon the receipt of the Authorization Request: + + 1. It MUST treat ``request_uri`` values as one-time use and MUST reject an expired request. However, it MAY allow for duplicate requests due to a user reloading/refreshing their user-agent (derived from :rfc:`9126`). + 2. It MUST identify the request as a result of the submitted PAR (derived from :rfc:`9126`). + 3. It MUST reject all the Authorization Requests that do not contain the ``request_uri`` parameter as the PAR is the only way to pass the Authorization Request from the Wallet Instance (derived from :rfc:`9126`). + .. code-block:: http @@ -178,9 +203,14 @@ The JWS payload of the request object is represented below: .. note:: **User Authentication and Consent:** The PID Provider performs the User authentication based on the requirements of eIDAS LoA High by means of national notified eIDAS scheme and requires the User consent for the PID issuance. - The (Q)EAA Issuer performs the User authentication requesting a valid PID to the Wallet Instance. The (Q)EAA Issuer MUST use [`OpenID4VP`_] to dynamically request the presentation of the PID. From a protocol perspective, the (Q)EAA Issuer then acts as a verifier and sends a presentation request to the Wallet Instance. The Wallet Instance MUST have a valid PID obtained prior to starting a transaction with the (Q)EAA Issuer. + The (Q)EAA Provider performs the User authentication requesting a valid PID to the Wallet Instance. The (Q)EAA Provider MUST use [`OpenID4VP`_] to dynamically request the presentation of the PID. From a protocol perspective, the (Q)EAA Provider then acts as a Relying Party and provide the presentation request to the Wallet Instance. The Wallet Instance MUST have a valid PID obtained prior to start the transaction with the (Q)EAA Provider. + + +**Steps 10-11 (Authorization Response):** The PID/(Q)EAA Provider sends an authorization ``code`` together with ``state`` and ``iss`` parameters to the Wallet Instance. The Wallet Instance performs the following checks on the Authorization Response: -**Steps 10-11 (Authorization Response):** The PID/(Q)EAA Issuer sends an authorization code to the Wallet Instance. + 1. It MUST check the Authorization Response contains all the defined parameters according to :ref:`Table of the HTTP Response parameters `. + 2. It MUST check the returned value by the PID/(Q)EAA Provider for ``state`` parameter is equal to the value sent by Wallet Instance in the Request Object (:rfc:`6749`). + 3. It MUST check that the URL of PID/(Q)EAA Provider in ``iss`` parameter is equal to the URL identifier of intended PID/(Q)EAA Provider that the Wallet Instance start the communication with (:rfc:`9027`). .. note:: @@ -191,9 +221,16 @@ The JWS payload of the request object is represented below: HTTP/1.1 302 Found Location: eudiw://start.wallet.example.org?code=SplxlOBeZQQYbYS6WxSbIA&state=fyZiOL9Lf2CeKuNT2JzxiLRDink0uPcd&iss=https%3A%2F%2Fpid-provider.example.org -**Steps 12-13 (DPoP Proof for Token Endpoint)**: The Wallet Instance creates a key for DPoP and a fresh DPoP proof for the token request to the PID/(Q)EAA Issuer. DPoP provides a way to bind the Access Token to a certain sender (Wallet Instance) `[DPoP-draft16] `_. This mitigates the misuse of leaked or stolen Access Tokens at the Credential Endpoint of PID/(Q)EAA Issuer as the attacker needs to present a valid DPoP proof. +**Steps 12-13 (DPoP Proof for Token Endpoint)**: The Wallet Instance MUST create a new key pair for the DPoP and a fresh DPoP Proof JWT following the instruction provided in Section 4 of (:rfc:`9449`) for the token request to the PID/(Q)EAA Provider. The DPoP Proof JWT is signed using the created private key for DPoP by Wallet Instance. DPoP provides a way to bind the Access Token to a certain sender (Wallet Instance) (:rfc:`9449`). This mitigates the misuse of leaked or stolen Access Tokens at the Credential Endpoint of PID/(Q)EAA Issuer as the attacker needs to present a valid DPoP Proof JWT. -**Step 14 (Token Request):** The Wallet Instance sends a token request to the PID/(Q)EAA Issuer token endpoint using the authorization *code*, *code_verifier*, *DPoP proof* and *private_key_jwt*. +**Step 14 (Token Request):** The Wallet Instance sends a token request to the PID/(Q)EAA Provider Token Endpoint using the authorization ``code``, ``code_verifier``, *DPoP Proof JWT* and ``private_key_jwt`` parameters (``client_assertion_type`` and ``client_assertion``). +The ``client_assertion`` is signed using the private key that is created during the setup phase to obtain the Wallet Instance Attestation. The related public key that is attested by the Wallet Provider is provided within the Wallet Instance Attestation (``cnf`` claim). The PID/(Q)EAA Provider performs the following checks on the Token Request: + + 1. It MUST authenticate the Wallet Instance based on the ``private_key_jwt`` Client Authentication method `OpenID.Core#TokenRequest `_. + 2. It MUST ensure that the Authorization ``code`` is issued to the authenticated Wallet Instance (:rfc:`6749`). + 3. It MUST ensure the Authorization ``code`` is valid and has not been previously used (:rfc:`6749`). + 4. It MUST ensure the ``redirect_uri`` is identical to the value that was initially included in the Request Object `OpenID.Core#TokenRequest `_. + 5. It MUST validate the DPoP Proof JWT following the steps in Section 4.3 of (:rfc:`9449`). .. code-block:: http @@ -217,7 +254,7 @@ The JWS payload of the request object is represented below: &client_assertion=eyJhbGciOiJIUzI1NiI -**Step 15 (Token Response):** The PID/(Q)EAA Issuer validates the request and if it is successful, it issues an *Access Token* (bound to the DPoP key) and a fresh *c_nonce*. +**Step 15 (Token Response):** The PID/(Q)EAA Provider validates the request and if it is successful, it issues an *Access Token* (bound to the DPoP key) and a fresh ``c_nonce``. .. code-block:: http @@ -234,13 +271,13 @@ The JWS payload of the request object is represented below: } -**Steps 16-18 (DPoP Proof for Credential Endpoint):** The Wallet Instance SHOULD create a new key pair to which the new credential SHALL be bound. Then, it creates a proof of possession with the new key and the *c_nonce* obtained in **Step 15** and it creates a DPoP proof for the request to the PID/(Q)EAA credential issuance endpoint. +**Steps 16-17 (DPoP Proof for Credential Endpoint):** The Wallet Instance creates a proof of possession with the DPoP key following the steps in Section 7.2.1 of `OPENID4VCI`_ and the ``c_nonce`` obtained in **Step 15** and it creates a DPoP Proof JWT based on Section 4 of (:rfc:`9449`) for the request to the PID/(Q)EAA credential issuance endpoint. The ``jwk`` value in the proof parameter MUST be equal to the public key generated for the DPoP. -**Step 19 (Credential Request):** The Wallet Instance sends a PID/(Q)EAA issuance request to the PID/(Q)EAA credential endpoint. It contains the *Access Token*, the *DPoP proof*, the *credential type*, the *proof* (proof of possession of the key) and the *format*. +**Step 18 (Credential Request):** The Wallet Instance requests a PID/(Q)EAA issuance to the PID/(Q)EAA credential endpoint. The request MUST contain the *Access Token*, the *DPoP Proof JWT*, and the *credential type*, the ``proof`` (proof of possession of the key) and the ``format`` parameters. .. note:: - **PID Credential Schema and Status registration:** The PID/(Q)EAA Issuer MUST register all the issued credentials for their later revocation, if needed. + **PID/(Q)EAA Credential Schema and Status registration:** The PID/(Q)EAA Provider MUST register all the issued credentials for their later revocation, if needed. .. code-block:: http @@ -262,7 +299,6 @@ The JWS payload of the request object is represented below: &proof=%7B%22proof_type%22:%22...-ace0-9c5210e16c32%22%7D - A non-normative example of proof parameter is given below: .. code-block:: JSON @@ -280,7 +316,13 @@ Where the decoded content of the JWT is represented below: { "alg": "ES256", "typ": "openid4vci-proof+jwt", - "kid": "dB67gL7ck3TFiIAf7N6_7SHvqk0MDYMEQcoGGlkUAAw" + "jwk": { + "kty": "EC", + "x": "l8tFrhx-34tV3hRICRDY9zCkDlpBhF42UQUfWVAWBFs", + "y": "9VE4jf_Ok_o64zbTTlcuNJajHmt6v9TDVrU0CdvGRDA", + "crv": "P-256" + } + } .. code-block:: JSON @@ -293,8 +335,15 @@ Where the decoded content of the JWT is represented below: } +**Steps 19-21 (Credential Response):** The PID/(Q)EAA Provider MUST validate the *DPoP JWT Proof* based on the steps defined in Section 4.3 of (:rfc:`9449`) and whether the *Access Token* is valid and suitable for the requested PID/(Q)EAA. It also MUST validate the proof of possession for the key material the new credential SHALL be bound to following the steps in Section 7.2.2 of `OPENID4VCI`_. If all checks succeed, the PID/(Q)EAA Provider creates a new credential bound to the key material and provide it to the Wallet Instance. The Wallet Instance MUST perform the following checks before proceeding with the secure storage of the PID/(Q)EAA credential: -**Steps 20-22 (Credential Response):** The PID/(Q)EAA Issuer checks the *DPoP proof* and whether the *Access Token* is valid and suitable for the requested PID/(Q)EAA. It also checks the proof of possession for the key material the new credential SHALL be bound to. If all checks succeed, the PID/(Q)EAA Issuer creates a new credential bound to the key material and sends it to the Wallet Instance. The Wallet Instance MUST perform the PID/(Q)EAA integrity and authenticity checks before proceeding with the secure storage of the credential. + 1. It MUST check that the PID Credential Response contains all the mandatory parameters and values are validated according to :ref:`Table of the credential response parameters `. + 2. It MUST check the PID integrity by verifying the signature using the algorithm specified in the ``alg`` header parameter of SD-JWT (:ref:`PID/(Q)EAA Data Model `) and the public key that is identified using using the ``kid`` header of the SD-JWT. + 3. It MUST check that the received PID credential (in credential claim) contains all the mandatory parameters defined in :ref:`PID/(Q)EAA Data Model `. + 4. It MUST process and verify the PID that is in SD-JWT VC following the steps in Section 6 of `SD.JWT#Verification `_. + 5. It MUST verify the Trust Chain in the header of SD-JWT VC to verify that the PID Provider is trusted. + +If the checks defined above are successful the Wallet Instance proceeds with the secure storage of the PID credential. .. code-block:: http @@ -316,7 +365,7 @@ Pushed Authorization Request Endpoint Pushed Authorization Request (PAR) Request ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The requests to the PID/(Q)EAA authorization endpoint MUST be HTTP with method POST, with the following mandatory parameters in the HTTP request message body, encoded in ``application/x-www-form-urlencoded`` format. +The requests to the PID/(Q)EAA authorization endpoint MUST be HTTP with method POST, using the mandatory parameters listed below within the HTTP request message body. These MUST be encoded in ``application/x-www-form-urlencoded`` format. .. _table_http_request_claim: .. list-table:: PAR http request parameters @@ -333,13 +382,13 @@ The requests to the PID/(Q)EAA authorization endpoint MUST be HTTP with method P - MUST be set to the thumbprint of the ``jwk`` value in the ``cnf`` parameter inside the Wallet Instance Attestation. - :rfc:`6749` * - **code_challenge** - - A challenge derived from the **code verifier** that is sent in the authorization request + - A challenge derived from the **code verifier** that is sent in the authorization request. - :rfc:`7636#section-4.2`. * - **code_challenge_method** - A method that was used to derive **code challenge**. It MUST be set to ``S256``. - :rfc:`7636#section-4.3`. * - **request** - - It MUST be a signed JWT. The private key corresponding to the public one in the ``cnf`` parameter inside the Wallet Instance Attestation MUST be used for signing the request object. + - It MUST be a signed JWT. The private key corresponding to the public one in the ``cnf`` parameter inside the Wallet Instance Attestation MUST be used for signing the Request Object. - `OpenID Connect Core. Section 6 `_ * - **client_assertion_type** - It MUST be set to ``urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation``. @@ -358,10 +407,10 @@ The JWT Request Object has the following JOSE header parameters: - **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 in Section `Cryptographic Algorithms `_ and MUST NOT be none or an identifier for a symmetric algorithm (MAC). + - 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 as base64url-encoded JWK Thumbprint value. + - Unique identifier of the ``jwk`` inside the ``cnf`` claim of Wallet Instance Attestation as base64url-encoded JWK Thumbprint value. - :rfc:`7638#section_3`. .. note:: @@ -382,7 +431,7 @@ The JWT payload is given by the following parameters: - It MUST be set to the ``client_id``. - :rfc:`9126` and :rfc:`7519`. * - **aud** - - It MUST be set to the identifier of the PID/(Q)EAA Issuer. + - It MUST be set to the identifier of the PID/(Q)EAA Provider. - :rfc:`9126` and :rfc:`7519`. * - **exp** - UNIX Timestamp with the expiry time of the JWT. @@ -397,7 +446,7 @@ The JWT payload is given by the following parameters: - It MUST be set as in the :ref:`Table of the HTTP parameters `. - See :ref:`Table of the HTTP parameters `. * - **state** - - Unique session identifier at the client side. This value will be returned to the client in the response, at the end of the authentication. It MUST be a random string with at least 32 alphanumeric characters. + - Unique session identifier at the client side. This value will be returned to the client in the response, at the end of the authentication. It MUST be a random string composed by alphanumeric characters and with a minimum length of 32 digits. - See `OpenID.Core#AuthRequest `_. * - **code_challenge** - It MUST be set as in the :ref:`Table of the HTTP parameters `. @@ -410,10 +459,10 @@ The JWT payload is given by the following parameters: - **type**: it MUST be set to ``openid_credential``, - **format**: it MUST be set to ``vc+sd-jwt``, - - **credential_definition**: JSON Object. It MUST have the **type** claim which MUST be set in accordance to the type of the requested PID/(Q)EAA that is obtained from the PID/(Q)EAA Issuer metadata. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData`` + - **credential_definition**: JSON Object. It MUST have the **type** claim which MUST be set in accordance to the type of the requested PID/(Q)EAA that is obtained from the metadata of the PID/(Q)EAA Issuer. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData``. - See [RAR :rfc:`9396`] and `[OIDC4VCI. Draft 13] `_. * - **redirect_uri** - - Redirection URI to which the response will be sent. It MUST be an universal or app link registered with the local operating system, so this latter will resolve it and pass the response to the Wallet Instance. + - Redirection URI to which the response is intended to be sent. It MUST be an universal or app link registered with the local operating system, so this latter will provide the response to the Wallet Instance. - See `OpenID.Core#AuthRequest `_. * - **client_assertion_type** - It MUST be set as in the :ref:`Table of the HTTP parameters `. @@ -422,7 +471,7 @@ The JWT payload is given by the following parameters: - It MUST be set as in the :ref:`Table of the HTTP parameters `. - See :ref:`Table of the HTTP parameters `. * - **jti** - - Unique JWT identifier to prevent the reuse of the JWT (replay attack). Since the `jti` value alone is not collision resistant, it MUST be identified uniquely together with its issuer. + - Unique identifier of the JWT that, together with the value contained in the ``iss`` claim, prevents the reuse of the JWT (replay attack). Since the `jti` value alone is not collision resistant, it MUST be identified uniquely together with its issuer. - [:rfc:`7519`]. @@ -451,13 +500,13 @@ Authorization endpoint ---------------------- The authorization endpoint is used to interact with the PID/(Q)EAA Issuer and obtain an authorization grant. -The authorization server MUST first verify the identity of the resource owner (the User that own it's credentials) -as defined in the :rfc:`6749`. +The authorization server MUST first verify the identity of the User that own the credential. + Authorization Request ^^^^^^^^^^^^^^^^^^^^^^^ -The Authorization request is issued by the Wallet Instance Browser, HTTP **POST** or **GET** methods MAY be used. When the method **POST** is used, the parameters MUST be sent using the *Form Serialization*. When the method **GET** is used, the parameters MUST be sent using the *Query String Serialization*. For more details see `OpenID.Core#Serializations `_. +The Authorization request is issued by the Web Browser in use by the Wallet Instance, the HTTP methods **POST** or **GET** are used. When the method **POST** is used, the parameters MUST be sent using the *Form Serialization*. When the method **GET** is used, the parameters MUST be sent using the *Query String Serialization*. For more details see `OpenID.Core#Serializations `_. The mandatory parameters in the HTTP authentication request are specified in the following table. @@ -481,7 +530,7 @@ Authorization Response The authentication response is returned by the PID/(Q)EAA authorization endpoint at the end of the authentication flow. -If the authentication is successful the PID/(Q)EAA Issuer redirects the User by adding the following query parameters as required to the *redirect_uri*. The redirect URI MUST be an universal or app link registered with the local operating system, so this latter is able to resolve its value and delegates the Wallet Instance for the processing. +If the authentication is successful the PID/(Q)EAA Issuer redirects the User by adding the following query parameters as required to the *redirect_uri*. The redirect URI MUST be an universal or app link registered with the local operating system, so this latter is able to provide the response to the Wallet Instance. .. list-table:: :widths: 20 60 20 @@ -494,7 +543,7 @@ If the authentication is successful the PID/(Q)EAA Issuer redirects the User by - Unique *Authorization Code* that the Wallet Instance submits to the Token Endpoint. - [:rfc:`6749#section-4.1.2`], `Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants `_ * - **state** - - The Wallet Instance MUST check the correspondence with the ``state`` parameter value in the request object. It is defined as in the :ref:`Table of the JWT Request parameters `. + - The Wallet Instance MUST check the correspondence with the ``state`` parameter value in the Request Object. It is defined as in the :ref:`Table of the JWT Request parameters `. - [:rfc:`6749#section-4.1.2`]. * - **iss** - Unique identifier of the PID/(Q)EAA Issuer who created the Authentication Response. The Wallet Instance MUST validate this parameter. @@ -505,17 +554,17 @@ If the authentication is successful the PID/(Q)EAA Issuer redirects the User by Token endpoint -------------- -The token endpoint is used by the Wallet Instance -to obtain an Access Token by presenting its authorization grant, as +The token endpoint is used by the Wallet Instance to obtain an Access Token by presenting its authorization grant, as defined in :rfc:`6749`. Token Request ^^^^^^^^^^^^^^^ -The request to the PID/(Q)EAA Token endpoint MUST be an HTTP request with method POST, where its body message is encoded in ``application/x-www-form-urlencoded`` format. The Wallet Instance sends the Token endpoint request with *private_key_jwt* authentication and a *DPoP proof* containing the mandatory parameters, defined in the table below. +The request to the PID/(Q)EAA Token endpoint MUST be an HTTP request with method POST, where its body message is encoded in ``application/x-www-form-urlencoded`` format. The Wallet Instance sends the Token endpoint request with *private_key_jwt* authentication and a *DPoP proof* containing the parameters defined in the table below. -The Token endpoint MUST accept and validate the DPoP proof sent in the DPoP HTTP header. The Token endpoint MUST validate the DPoP proof according to Section 4.3 of the DPoP specifications `[DPoP-draft16] `_. Thus, this mitigates the misuse of leaked or stolen Access Tokens at the credential endpoint. If the DPoP proof is invalid, the Token endpoint returns an error response, according to Section 5.2 of [:rfc:`6749`] with ``invalid_dpop_proof`` as the value of the error parameter. +The Token endpoint MUST accept and validate the DPoP proof sent in the DPoP HTTP header. The Token endpoint MUST validate the DPoP proof according to Section 4.3 of the DPoP specifications (:rfc:`9449`). Thus, this mitigates the misuse of leaked or stolen Access Tokens at the credential endpoint. If the DPoP proof is invalid, the Token endpoint returns an error response, according to Section 5.2 of [:rfc:`6749`] with ``invalid_dpop_proof`` as the value of the error parameter. +All the parameters listed below are REQUIRED: .. list-table:: :widths: 20 60 20 @@ -534,7 +583,7 @@ The Token endpoint MUST accept and validate the DPoP proof sent in the DPoP HTTP - Authorization code returned in the Authentication Response. - `Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants `_. * - **redirect_uri** - - It MUST be set as in the request object :ref:`Table of the JWT Request parameters `. + - It MUST be set as in the Request Object :ref:`Table of the JWT Request parameters `. - `Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants `_. * - **code_verifier** - Verification code of the **code_challenge**. @@ -548,12 +597,12 @@ The Token endpoint MUST accept and validate the DPoP proof sent in the DPoP HTTP - **iss**: This MUST contain the ``client_id``. - **sub**: This MUST contain the ``iss``. - **aud**: URL of the PID/(Q)EAA Token Endpoint. - - **iat**: UNIX Timestamp with the time of the JWT issuance, coded as NumericDate as indicated in RFC 7519. - - **exp**: UNIX Timestamp with the expiry time of the JWT, coded as NumericDate as indicated in RFC 7519. - - **jti**: Unique Identifier for this authentication request, generated by the Wallet Instance. E.g., uuid4 format. + - **iat**: UNIX Timestamp with the time of the JWT issuance, coded as NumericDate as indicated in [:rfc: `7519`]. + - **exp**: UNIX Timestamp with the expiry time of the JWT, coded as NumericDate as indicated in [:rfc: `7519`]. + - **jti**: Unique Identifier for this authentication request, generated by the Wallet Instance. E.g., ``uuid4`` format. - `Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants `_. -A **DPoP proof** is included in an HTTP request using the ``DPoP`` header parameter containing a DPoP JWS. +A **DPoP Proof JWT** is included in an HTTP request using the ``DPoP`` header parameter containing a DPoP JWS. The JOSE header of a **DPoP JWT** MUST contain at least the following parameters: @@ -568,14 +617,14 @@ The JOSE header of a **DPoP JWT** MUST contain at least the following parameters - It MUST be equal to ``dpop+jwt``. - [:rfc:`7515`] and [:rfc:`8725`. Section 3.11]. * - **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 in Section :ref:`Cryptographic Algorithms ` and MUST NOT be none or an identifier for a symmetric algorithm (MAC). + - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms in Section :ref:`Cryptographic Algorithms ` and MUST NOT be set to ``none`` or with a symmetric algorithm (MAC) identifier. - [:rfc:`7515`]. * - **jwk** - - representing the public key chosen by the client, in JSON Web Key (JWK) [RFC7517] format, as defined in Section 4.1.3 of [RFC7515]. It MUST NOT contain a private key. + - representing the public key chosen by the Wallet Instance, in JSON Web Key (JWK) [:rfc:`7517`] format that the Access Token shall be bound to, as defined in Section 4.1.3 of [:rfc:`7515`]. It MUST NOT contain a private key. - [:rfc:`7517`] and [:rfc:`7515`]. -The payload of a **DPoP proof** MUST contain at least the following claims: +The payload of a **DPoP JWT Proof** MUST contain at least the following claims: .. list-table:: :widths: 20 60 20 @@ -585,7 +634,7 @@ The payload of a **DPoP proof** MUST contain at least the following claims: - **Description** - **Reference** * - **jti** - - Unique identifier for the DPoP proof JWT. The value MUST be assigned in a *UUID v4* string format according to [:rfc:`4122`]. + - Unique identifier for the DPoP proof JWT. The value SHOULD be set using a *UUID v4* value according to [:rfc:`4122`]. - [:rfc:`7519`. Section 4.1.7]. * - **htm** - The value of the HTTP method of the request to which the JWT is attached. @@ -620,7 +669,7 @@ Token endpoint response MUST contain the following mandatory claims. - Expiry time of the *Access Token* in seconds. - :rfc:`6749`. * - **c_nonce** - - JSON string containing a nonce to be used to create a *proof of possession* of key material when requesting a Credential. + - JSON string containing a ``nonce`` value to be used to create a *proof of possession* of key material when requesting a credential. - `[OIDC4VCI. Draft 13] `_. * - **c_nonce_expires_in** - JSON integer, it represents the lifetime in seconds of the **c_nonce**. @@ -629,7 +678,7 @@ Token endpoint response MUST contain the following mandatory claims. Access Token ^^^^^^^^^^^^ -A DPoP-bound Access Token is provided by the PID/(Q)EAA Token endpoint as a result of a successful token request. The Access Token is encoded in JWT format, according to [:rfc:`7519`]. The Access Token MUST have at least the following mandatory claims and it MUST be bound to the public key that is provided by the DPoP proof. This binding can be accomplished based on the methodology defined in Section 6 of `[DPoP-draft16] `_. +A DPoP-bound Access Token is provided by the PID/(Q)EAA Token endpoint as a result of a successful token request. The Access Token is encoded in JWT format, according to [:rfc:`7519`]. The Access Token MUST have at least the following mandatory claims and it MUST be bound to the public key that is provided by the DPoP proof. This binding can be accomplished based on the methodology defined in Section 6 of (:rfc:`9449`). .. list-table:: :widths: 20 60 20 @@ -642,13 +691,13 @@ A DPoP-bound Access Token is provided by the PID/(Q)EAA Token endpoint as a resu - It MUST be an HTTPS URL that uniquely identifies the PID/(Q)EAA Issuer. The Wallet Instance MUST verify that this value matches the PID/(Q)EAA Issuer where it has requested the credential. - [:rfc:`9068`], `[RFC7519, Section 4.1.1] `_. * - **sub** - - It identifies the principal that is the subject of the JWT. It MUST be set to the value of the ``sub`` field in the PID/(Q)EAA SD-JWT-VC. + - It identifies the subject of the JWT. It MUST be set to the value of the ``sub`` field in the PID/(Q)EAA SD-JWT-VC. - [:rfc:`9068`], [:rfc:`7519`] and [`OpenID.Core#SubjectIDTypes `_]. * - **client_id** - - It MUST be set to the *jwk* value in the *cnf* parameter, as taken in the Wallet Instance Attestation. + - As provided in the Wallet Instance Attestation. - [:rfc:`9068`]. * - **aud** - - It MUST match the value *client_id*. The RP MUST verify that this value matches its client ID. + - It Must be Set to the URL of Credential Endpoint of the PID/(Q)EAA Provider. - [:rfc:`9068`]. * - **iat** - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. @@ -661,20 +710,21 @@ A DPoP-bound Access Token is provided by the PID/(Q)EAA Token endpoint as a resu - [:rfc:`9068`], [:rfc:`7519`]. * - **jkt** - JWK SHA-256 Thumbprint Confirmation Method. The value of the jkt member MUST be the base64url encoding (as defined in [RFC7515]) of the JWK SHA-256 Thumbprint of the DPoP public key (in JWK format) to which the Access Token is bound. - - [`DPoP-draft16 `_. Section 6.1] and [:rfc:`7638`]. - + - [:rfc:`9449`. Section 6.1] and [:rfc:`7638`]. Credential endpoint ------------------- -The Credential Endpoint issues a Credential as approved by the End-User upon presentation of a valid Access Token representing this approval, as defined in `OPENID4VCI`_. +The Credential Endpoint issues a credential as approved by the End-User upon presentation of a valid Access Token representing this approval, as defined in `OPENID4VCI`_. + Credential Request ^^^^^^^^^^^^^^^^^^^ The Wallet Instance when requests the PID/(Q)EAA to the PID/(Q)EAA Credential endpoint, MUST use the following parameters in the entity-body of the HTTP POST request, using the `application/json` media type. -The Credential endpoint MUST accept and validate the *DPoP proof* sent in the DPoP field of the Header based on the steps defined in Section 4.3 of [DPoP-draft16]. The *DPoP proof* in addition to the values that are defined in the Token Endpoint section MUST contain the following claim: + +The Credential endpoint MUST accept and validate the *DPoP proof* sent in the DPoP field of the Header based on the steps defined in Section 4.3 of (:rfc:`9449`). The *DPoP proof* in addition to the values that are defined in the Token Endpoint section MUST contain the following claim: - **ath**: hash of the Access Token. The value MUST be the result of a base64url encoding (as defined in Section 2 of :rfc:`7515`) the SHA-256 hash of the ASCII encoding of the associated Access Token's value. @@ -692,13 +742,13 @@ If the *DPoP proof* is invalid, the Credential endpoint returns an error respons - **Description** - **Reference** * - **credential_definition** - - JSON object containing the detailed description of the credential type. It MUST have at least the **type** sub claims which is a JSON array containing the type values the Wallet SHALL request in the Credential Request. It MUST be set in accordance to the type of the requested PID/(Q)EAA that is obtained from the PID/(Q)EAA Issuer metadata. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData``. + - JSON object containing the detailed description of the credential type. It MUST have at least the **type** sub claims which is a JSON array containing the type values the Wallet SHALL request in the Credential Request. It MUST be set in accordance to the type of the requested PID/(Q)EAA that is obtained from the PID/(Q)EAA Issuer metadata. In the case of the PID it MUST be set to ``PersonIdentificationData``. - `[OIDC4VCI. Draft 13] `_. * - **format** - Format of the Credential to be issued. This MUST be `vc+sd-jwt`. - `[OIDC4VCI. Draft 13] `_. * - **proof** - - JSON object containing proof of possession of the key material the issued Credential shall be bound to. The proof object MUST contain the following mandatory claims: + - JSON object containing proof of possession of the key material the issued credential shall be bound to. The proof object MUST contain the following mandatory claims: - **proof_type**: JSON string denoting the proof type. It MUST be `jwt`. - **jwt**: the JWT used as proof of possession. @@ -719,13 +769,13 @@ The JWT proof type MUST contain the following parameters for the JOSE header and - **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 in Section :ref:`Cryptographic Algorithms ` and MUST NOT be ``none`` or an identifier for a symmetric algorithm (MAC). + - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms in Section :ref:`Cryptographic Algorithms ` and MUST NOT be set to ``none`` or to a symmetric algorithm (MAC) identifier. - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. * - **typ** - - MUST be `openid4vci-proof+jwt`. + - It MUST be set to `openid4vci-proof+jwt`. - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. - * - **kid** - - It MUST contain the identifier of the key material the PID/(Q)EAA shall be bound to. + * - **jwk** + - Representing the public key chosen by the Wallet Instance, in JSON Web Key (JWK) [:rfc:`7517`] format that the PID/(Q)EAA shall be bound to, as defined in Section 4.1.3 of [:rfc:`7515`]. The ``jwk`` value MUST be equal to the same public key that is generated for the DPoP. - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. .. list-table:: @@ -749,13 +799,13 @@ The JWT proof type MUST contain the following parameters for the JOSE header and - `[OIDC4VCI. Draft 13] `_. - Credential Response ^^^^^^^^^^^^^^^^^^^^ Credential Response to the Wallet Instance MUST be sent using `application/json` media type. The response MUST contain the following mandatory claims: -.. list-table:: +.. _table_credential_response_claim: +.. list-table:: Credential http response parameters :widths: 20 60 20 :header-rows: 1 @@ -763,13 +813,13 @@ Credential Response to the Wallet Instance MUST be sent using `application/json` - **Description** - **Reference** * - **format** - - Format of the Credential to be issued. This MUST be `vc+sd-jwt`. + - Format of the Credential to be issued. This MUST be set to `vc+sd-jwt` when the credential type is SD-JWT. - `[OIDC4VCI. Draft 13] `_. * - **credential** - - Contains the issued PID/(Q)EAA. It MUST be an SD-JWT JSON Object (see Section :ref:`PID/(Q)EAA Data Model `). + - Contains the issued PID/(Q)EAA. When the credential type is SD-JWT, it MUST be an SD-JWT JSON Object (see Section :ref:`PID/(Q)EAA Data Model `). - Appendix E in `[OIDC4VCI. Draft 13] `_. * - **c_nonce** - - JSON string containing a nonce to be used to create a *proof of possession* of key material when requesting a further credential or for renewal credential. + - JSON string containing a ``nonce`` value to be used to create a *proof of possession* of the key material when requesting a further credential or for the renewal of a credential. - `[OIDC4VCI. Draft 13] `_. * - **c_nonce_expires_in** - JSON integer corresponding to the **c_nonce** lifetime in seconds. @@ -785,7 +835,7 @@ Credential Response to the Wallet Instance MUST be sent using `application/json` Entity Configuration Credential Issuer ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Below a non-normative example of an Entity Configuration containing an `openid_credential_issuer` metadata. +Below is a non-normative example of an Entity Configuration containing an `openid_credential_issuer` metadata. .. code-block:: http @@ -822,6 +872,16 @@ Below a non-normative example of an Entity Configuration containing an `openid_c "pushed_authorization_request_endpoint": "https://pid-provider.example.org/connect/par", "dpop_signing_alg_values_supported": ["RS256", "RS512", "ES256", "ES512"], "credential_endpoint": "https://pid-provider.example.org/credential", + "jwks": { + "keys": [ + { + "crv": "P-256", + "kty": "EC", + "x": "newK5qDYMekrCPPO-yEYTdJVWJMTzasMavt2vm1Mb-A", + "y": "VizXaLO6dzeesZPxfpGZabTK3cTXtBUbIiQpmiYRtSE", + "kid": "ff0bded045fe63fe5d1d64dd83b567e0" + }] + } "credentials_supported": [ { "format": "vc+sd-jwt", diff --git a/docs/en/relying-party-solution.rst b/docs/en/relying-party-solution.rst index a498992ca..630ffefd5 100644 --- a/docs/en/relying-party-solution.rst +++ b/docs/en/relying-party-solution.rst @@ -8,11 +8,8 @@ Relying Party Solution +++++++++++++++++++++++ -This section describes how a Relying Party may ask to a Wallet Instance the presentation of the PID and the (Q)EAAs, according the following specifications: - -- `OpenID for Verifiable Presentations - draft 19 `_. -- `Draft: OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP) `_. - +This section describes how a Relying Party may request to a Wallet Instance the presentation of the PID and the (Q)EAAs, +according to `OpenID for Verifiable Presentations - draft 20 `_. In this section the following flows are described: @@ -21,13 +18,19 @@ In this section the following flows are described: In the **Same Device** and **Cross Device** Flows described in this chapter, the User interacts with a remote Relying Party. +.. note:: + The provisioning of the Wallet Instance Attestation from the Wallet Instace to the Relying Party is + under discussion within the international standardization working groups. At the current stage of the draft of this implementation profile, + a mechanism based on `OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP) `_ + is used. Remote Protocol Flow -------------------- -In this scenario the Relying Party provides the URL where the signed presentation request object is available for download. +In this scenario the Relying Party MUST provide the URL where the signed presentation Request Object is available for download. -Depending on whether the Relying Party client is on a mobile device or a workstation, it must activate one of the supported remote flows: +Depending on whether the Relying Party client is on a mobile device or a workstation, +the Relying Party MUST activate one of the supported remote flows: * **Same Device**, the Relying Party MUST provide a HTTP redirect (302) location to the Wallet Instance; * **Cross Device**, the Relying Party MUST provide a QR Code which the User frames with their Wallet Instance. @@ -53,33 +56,33 @@ The details of each step shown in the previous picture are described in the tabl * - **1**, **2** - The User asks for access to a protected resource, the Relying Party redirects the User to a discovery page in which the User selects the *Login with the Wallet* button. The Authorization flow starts. * - **3**, **4**, **5** - - The Relying Party creates an Authorization Request which contains the scopes of the request and sends it back. + - The Relying Party creates an Authorization Request which contains the scopes of the request and provides it to the requester. * - **6**, **7**, **8**, **9** - - In the **Cross Device Flow**: the Request URI is provided in the form of a QR Code that is shown to the User that frames it. The Wallet Instance decodes the QR Code and extracts the Request URI from the QR Code payload. In the **Same Device Flow** the Relying Party responses with the Request URI in the form of HTTP Redirect Location (302). + - In the **Cross Device Flow**: the Request URI is provided in the form of a QR Code that is shown to the User. The User frames the QRCode with the Wallet Instance and extracts the Request URI. In the **Same Device Flow** the Relying Party responses with the Request URI in the form of HTTP Redirect Location (302). * - **10** - The Wallet Instance requests the content of the Authorization Request by invoking the Request URI, passing an Authorization DPoP HTTP Header containing the Wallet Instance Attestation and the DPoP proof HTTP Header. * - **11** - - The Relying Party attests the trust to the Wallet Instance using the Wallet Instance Attestation and verifies its capabilities. + - The Relying Party attests the trust to the Wallet Instance using the Wallet Instance Attestation and evaluates the Wallet Instance capabilities. * - **12** - - The Relying Party issues a signed Request Object, returning it as response. + - The Relying Party issues a signed Request Object, returning it as response. The ``exp`` value of the signed Request Object MUST be no more than 240 seconds. * - **13**, **14**, **15**, **16** - - The Wallet Instance verifies Request Object JWS. The Wallet Instance attests the trust to the Relying Party by verifying the ``trust_chain``. The Wallet Instance verifies the signature of the request and processes the Relying Party metadata to attest its capabilities and allowed scopes, attesting which Verifiable Credentials and personal attributes the Relying Party is granted to request. + - The Wallet Instance verifies the Request Object JWS. The Wallet Instance attests the trust to the Relying Party by verifying the Trust Chain. The Wallet Instance verifies the signature of the request and processes the Relying Party metadata to attest its capabilities and allowed scopes, attesting which Verifiable Credentials and personal attributes the Relying Party is granted to request. * - **17**, **18** - The Wallet Instance requests the User's consent for the release of the credentials. The User authorizes and consents the presentation of their credentials, by selecting/deselecting the personal data to release. * - **19** - - The Wallet Instance provides the Authorization Response to the Relying Party using a HTTP method POST (response Mode "direct_post"). + - The Wallet Instance provides the Authorization Response to the Relying Party using an HTTP request with the method POST (response mode "direct_post"). * - **20**, **21**, **22** - - The Relying Party verifies the Authorization Response, extracts the Credential and attests the trust to the credentials Issuer. The Relying Party verifies the revocation status and the proof of possession of the presented credential. + - The Relying Party verifies the Authorization Response, extracts the credential and attests the trust to the credentials Issuer. The Relying Party verifies the revocation status and the proof of possession of the presented credential. * - **23** - - The Relying Party authenticates the User and updates its session. + - The Relying Party authenticates the User. * - **24** - - The Relying Party notifies the Wallet Instance that the operation ends successfully. + - The Relying Party notifies to the Wallet Instance that the operation ends successfully. Authorization Request Details ----------------------------- -The Relying Party creates a signed request object, then gives it to the Wallet Instance through a HTTP URL (request URI) that points to the resource where the signed request object MUST be available for download. The URL parameters contained in the Relying Party response, containing the request URI, are described in the Table below. +The Relying Party MUST create a Request Object in the format of signed JWT, then provide it to the Wallet Instance through an HTTP URL (request URI). The HTTP URL points to the web resource where the signed request object is available for download. The URL parameters contained in the Relying Party response, containing the request URI, are described in the Table below. .. list-table:: :widths: 25 50 @@ -90,7 +93,7 @@ The Relying Party creates a signed request object, then gives it to the Wallet I * - **client_id** - Unique identifier of the Relying Party. * - **request_uri** - - The HTTP URL used by the Wallet Instance to retrieve the signed request object from the Relying Party. The URL is intentionally extended with a random value that uniquely identifies the transaction. + - The HTTP URL used by the Wallet Instance to retrieve the signed Request Object from the Relying Party. The URL is intentionally extended with a random value that uniquely identifies the transaction. Below a non-normative example of the response containing the required parameters previously described. @@ -111,7 +114,7 @@ In the **Same Device Flow** the Relying Party uses a HTTP response redirect (sta &request_uri=https%3A%2F%2Frelying-party.example.org%2Frequest_uri%3Fid%3Drandom-value -In the **Cross Device Flow**, a QR Code is shown by the Relying Party to the User in order to issue the Authorization Request. The User frames the QR Code using their Wallet Instance. The QR Code payload MUST be a **Base64 encoded string**. +In the **Cross Device Flow**, a QR Code is shown by the Relying Party to the User in order to provide the Authorization Request. The User frames the QR Code using their Wallet Instance. The QR Code payload MUST be a **Base64 encoded string**. Below is represented a non-normative example of a QR Code issued by the Relying Party. @@ -144,9 +147,9 @@ Since the QRcode page and the status endpoint are implemented by the Relying Par The Relying Party MUST bind the request of the user-agent, with a Secure and HttpOnly session cookie, with the issued request. The request url SHOULD include a parameter with a random value. The HTTP response returned by this specialized endpoint MAY contain the HTTP status codes listed below: -* **200 OK**. The signed request object was issued by the Relying Party that waits to be downloaded by the Wallet Instance at the **request_uri** endpoint. -* **202 Accepted**. This response is given when the signed request object was obtained by the Wallet Instance. -* **302 Found**. The Wallet Instance has sent the presentation to the Relying Party's **redirect_uri** endpoint and the User authentication is successful. The Relying Party updates the session cookie allowing the user-agent to access to the protected resource. The ``Location`` within the HTTP Response allows the user-agent to leave the QRCode page. +* **201 Created**. The signed Request Object was issued by the Relying Party that waits to be downloaded by the Wallet Instance at the **request_uri** endpoint. +* **202 Accepted**. This response is given when the signed Request Object was obtained by the Wallet Instance. +* **200 OK**. The Wallet Instance has provided the presentation to the Relying Party's **redirect_uri** endpoint and the User authentication is successful. The Relying Party updates the session cookie allowing the user-agent to access to the protected resource. An URL is provided carrying the location where the user-agent is intended to navigate. * **401 Unauthorized**. The Wallet Instance or its User have rejected the request, or the request is expired. The QRCode page SHOULD be updated with an error message. Below a non-normative example of the HTTP Request to this specialized endpoint, where the parameter ``id`` contains an opaque and random value: @@ -165,10 +168,11 @@ The following actions are made by the Wallet Instance: - scan the QR Code (Cross Device only); - extract from the payload the ``request_uri`` parameter; - invoke the retrieved URI; -- provide in the request its Wallet Instance Attestation, using `DPOP`_ to proof the legitimate possession of it; -- obtain the signed request object from the Relying Party. +- provide in the request its Wallet Instance Attestation, using :rfc:`9449` to proof the legitimate possession of it; +- obtain the signed Request Object from the Relying Party. +- evaluate the trust with the Relying Party, by evaluating the Trust Chain related to it. -Below a non-normative example of HTTP request made by the Wallet Instance to the Relying Party to provide the Wallet Instance Attestion and retrieve the signed request object: +Below a non-normative example of HTTP request made by the Wallet Instance to the Relying Party to provide the Wallet Instance Attestion and retrieve the signed Request Object: .. code-block:: javascript @@ -182,7 +186,7 @@ More detailed information about the `Wallet Instance Attestation`_ is available To attest a high level of security, the Wallet Instance submits its Wallet Instance Attestation to the Relying Party, disclosing its capabilities and the security level attested by its Wallet Provider. -Herein the description of the parameters defined in *OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)*. +Below the description of the parameters defined in *OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)*. .. note:: The use of DPoP doesn't represent any breaking changes to Wallet Instances that do not support DPoP to a *request_uri* endpoint, since it is assumed to use it as an additional security mechanisms for the attestation of the status of the Wallet Instance. @@ -192,7 +196,7 @@ Herein the description of the parameters defined in *OAuth 2.0 Demonstration of DPoP HTTP Header ^^^^^^^^^^^^^^^^ -A **DPoP proof** is included in the request using the HTTP Header ``DPoP`` and containing a JWS. The JWS MUST be signed with the public key made available in the Wallet Instance Attestation (``Authorization: DPoP``). +A **DPoP proof** is included in the request using the HTTP Header ``DPoP`` and containing a JWS. The JWS MUST be verified with the public key made available in the Wallet Instance Attestation (``Authorization: DPoP``). The JOSE header of the **DPoP JWS** MUST contain at least the following parameters: @@ -225,7 +229,7 @@ The payload of a **DPoP proof** MUST contain at least the following claims: - **Description** - **Reference** * - **jti** - - Unique identifier for the DPoP proof JWT. The value MUST be assigned in a *UUID v4* string format according to [:rfc:`4122`]. + - Unique identifier for the DPoP proof JWT. The value SHOULD be set with a *UUID v4* value, according to [:rfc:`4122`]. - [:rfc:`7519`. Section 4.1.7]. * - **htm** - The value of the HTTP method of the request to which the JWT is attached. @@ -238,7 +242,7 @@ The payload of a **DPoP proof** MUST contain at least the following claims: - [:rfc:`7519`. Section 4.1.6]. * - **ath** - Hash of the Wallet Instance Attestation. - - [`DPOP`_. Section 4.2]. + - [:rfc:`9449`. Section 4.2]. Therein a non-normative example of the DPoP decoded content: @@ -268,7 +272,7 @@ Therein a non-normative example of the DPoP decoded content: Request URI response -------------------- -The Relying Party issues a signed request object, where a non-normative example in the form of decoded header and payload is shown below: +The Relying Party issues the signed Request Object, where a non-normative example in the form of decoded header and payload is shown below: .. code-block:: text @@ -297,7 +301,7 @@ The Relying Party issues a signed request object, where a non-normative example "exp": 1672422065 } -The JWS header parameters are described herein: +The JWS header parameters are described below: .. list-table:: :widths: 25 50 @@ -306,13 +310,13 @@ The JWS header parameters are described herein: * - **Name** - **Description** * - **alg** - - Algorithm used to sign the JWT, according to [:rfc:`7516#section-4.1.1`]. It MUST be one of the supported algorithms in Section *Cryptographic Algorithms* and MUST NOT be none or an identifier for a symmetric algorithm (MAC). + - Algorithm used to sign the JWT, according to [:rfc:`7516#section-4.1.1`]. It MUST be one of the supported algorithms in Section *Cryptographic Algorithms* and MUST NOT be set to ``none`` or to a symmetric algorithm (MAC) identifier. * - **typ** - Media Type of the JWT, as defined in [:rfc:`7519`]. * - **kid** - - Key ID of the public key needed to verify the JWS signature, as defined in [:rfc:`7517`]. Required if ``trust_chain`` is used. + - Key ID of the public key needed to verify the JWS signature, as defined in [:rfc:`7517`]. REQUIRED when ``trust_chain`` is used. * - **trust_chain** - - Sequence of Entity Statements that composes a Trust Chain related to the Relying Party, as defined in `OIDC-FED`_ Section *3.2.1. Trust Chain Header Parameter*. + - Sequence of Entity Statements that composes the Trust Chain related to the Relying Party, as defined in `OIDC-FED`_ Section *3.2.1. Trust Chain Header Parameter*. The JWS payload parameters are described herein: @@ -324,35 +328,36 @@ The JWS payload parameters are described herein: * - **Name** - **Description** * - **scope** - - Aliases for well-defined Presentation Definitions IDs. It will be used to identify which required credentials and User attributes are requested by the Relying Party. + - Aliases for well-defined Presentation Definitions IDs. It is used to identify which required credentials and User attributes are requested by the Relying Party, according to the Section "Using scope Parameter to Request Verifiable Credential(s)" of [OID4VP]. * - **client_id_scheme** - - String identifying the scheme of the value in the ``client_id``. It MUST be ``entity_id``. + - String identifying the scheme of the value in the ``client_id``. It MUST be set to the value ``entity_id``. * - **client_id** - Unique Identifier of the Relying Party. * - **response_mode** - - Used to ask the Wallet Instance in which way it has to send the response. It MUST be ``direct_post.jwt``. + - It MUST be set to ``direct_post.jwt``. * - **response_type** - - The supported response type, MUST be set to``vp_token``. + - It MUST be set to``vp_token``. * - **response_uri** - - The Response URI to which the Wallet Instance MUST send the Authorization Response using an HTTPs POST. + - The Response URI to which the Wallet Instance MUST send the Authorization Response using an HTTP request using the method POST. * - **nonce** - - Fresh cryptographically random number with sufficient entropy used for security reason, which length MUST be at least 32 digits. + - Fresh cryptographically random number with sufficient entropy, which length MUST be at least 32 digits. * - **state** - Unique identifier of the Authorization Request. * - **iss** - - The entity that issued the JWT. It will be populated with the Relying Party URI. + - The entity that has issued the JWT. It will be populated with the Relying Party client id. * - **iat** - - The NumericDate representing the time at which the JWT was issued. + - Unix Timestamp, representing the time at which the JWT was issued. * - **exp** - - The NumericDate representing the expiration time on or after which the JWT MUST NOT be accepted for processing. + - Unix Timestamp, representing the expiration time on or after which the JWT MUST NOT be valid anymore. .. warning:: - The usage of ``scope`` instead of ``presentation_definition`` is still under discussion and needs better refinements. - -Here a non-normative example of ``presentation_definition``: + This implementation profile use the parameter ``scope`` within the request instead of the ``presentation_definition``. +Using the parameter ``scope`` requires that the Relying Party Metadata MUST +contain the ``presentation_definition``, where a non-normative example of it +is given below: .. code-block:: JSON @@ -444,9 +449,9 @@ Where the following parameters are used: * - **Name** - **Description** * - **vp_token** - - JWS containing a single (or an array) of Verifiable Presentation(s) in the form of JWS. + - JWS containing a single or an array of Verifiable Presentation(s) in the form of signed JWT. * - **presentation_submission** - - JSON Object contains mappings between the requested Verifiable Credentials and where to find them within the returned VP Token. + - JSON Object containing the mappings between the requested Verifiable Credentials and where to find them within the returned VP Token. * - **state** - Unique identifier provided by the Relying Party within the Authorization Request. @@ -494,9 +499,9 @@ Where the following parameters are used: Relying Party Entity Configuration --------------------------------------------- -According to the `Trust Model`_ section, the Relying Party is a Federation Entity and MUST expose a .well-known endpoint containing its Entity Configuration. +According to the `Trust Model`_ section, the Relying Party is a Federation Entity and MUST expose a well-known endpoint containing its Entity Configuration. -Below a non-normative example of the request made by the Wallet Instance to the *openid-federation* .well-known endpoint to obtain the Relying Party Entity Configuration: +Below a non-normative example of the request made by the Wallet Instance to the *openid-federation* well-known endpoint to obtain the Relying Party Entity Configuration: .. code-block:: http @@ -759,16 +764,8 @@ The Entity Configuration is a JWS, where its header parameters are defined below * - **kid** - Key ID used identifying the key used to sign the JWS -While each metadata specific parameter is defined below: -.. list-table:: - :widths: 25 50 25 - :header-rows: 1 - - * - **Name** - - **Description** - - **Specs** - * - TBD - - TBD - - TBD +.. note: + The Relying Party specific metadata parameter are experimental + and still under discussion `here `_. diff --git a/docs/en/ssi-introduction.rst b/docs/en/ssi-introduction.rst index f456ca268..263d0cb66 100644 --- a/docs/en/ssi-introduction.rst +++ b/docs/en/ssi-introduction.rst @@ -19,24 +19,23 @@ SSI is also significant in the field of data exchange and data governance. This The main roles in an SSI ecosystem are are listed as follow: - - Issuers: parties who can issue attributes or "credentials" about a person; - - Verifiers: parties who request Holders' attributes because they want to know something about them; - - Holders: individuals who own a Wallet and have control over the attributes they can acquire, store, and present to Verifiers; - - Verifiable Data Registries: Authorities that publish certificates, attestations, metadata, and schemes needed for trust establishment between the parties. + - Issuers: parties who can issue digital credentials about a person; + - verifiers: parties who request Holders' digital credentials for authentication and authorization purposes; + - Holders: individuals who own a Wallet and have control over the digital credentials they can request, acquire, store, and present to verifiers; + - Verifiable Data Registries: Authorities that publish certificates, attestations, metadata, and schemes needed for allowing the trust establishment between the parties. -**What it is useful for** - -In the SSI model, the data source (e.g., an educational institution) provides credentials to the User, who can store them in their digital Wallet. -A secure Self-Sovereign Identity Wallet is crucial, as it allows people to carry their credentials on their digital devices. The Wallet typically comes in the form of an application on the User's mobile phone. Portability is, therefore, one of the principles of SSI. +In the SSI model, the data source (e.g., an educational institution) provides digital credentials to the User, who can store them in their digital Wallet. +A secure Self-Sovereign Identity Wallet is crucial, as it allows people to carry their credentials on their personal digital devices. The Wallet typically comes in the form of an application on the User's mobile phone. Portability is, therefore, one of the principles of SSI. Other key elements that characterize an SSI system include: - - **Privacy and control**: SSI enables individuals to maintain control over their personal data. They can choose what information to release, to whom, and for what purpose. This reduces the risk of personal data being collected, stored, or misused; - - **Security**: SSI leverages advanced cryptographic techniques to ensure the integrity and security of identity information. It avoids the risk of identity theft, fraud, and unauthorized access since the data remains under the individual's control and is not stored in a single vulnerable location; + + - **Privacy and control**: SSI enables individuals to maintain control over their personal data. They can choose what information to release, to whom, and for what purpose; + - **Security**: SSI leverages advanced cryptographic techniques to ensure the integrity and security of identity information. It avoids the risk of identity theft, fraud, and unauthorized access since the data remains under the individual's control; - **Interoperability**: SSI promotes interoperability by enabling different systems and organizations to recognize and verify identities without relying on a central authority. This allows for seamless and trusted interactions between individuals, organizations, and even across borders; - **Efficiency and cost reduction**: individuals can manage their own identities with SSI, eliminating the need for multiple identity credentials and repetitive identity verification processes. This can streamline administrative procedures, reduce costs, and enhance the user experience. **Example** -When a User wants to purchase a good or access to a service, the service provider asks the User for specific proof. Instead of presenting physical identification documents or disclosing their full data, the individual can use their SSI system. +When a User wants to purchase a good or access to a service, the service provider asks the User for authentication or for a specific proof. Instead of presenting physical identification documents or disclosing their full data, the individual can use their SSI system if supported by the service provider. An example of SSI in action could be a scenario where an individual needs to prove their age to access a restricted service, such as purchasing age-restricted items. They would release only the necessary information, such as a digitally signed proof of being above the legal age, without revealing any other personal details. The verifier can then cryptographically validate the proof. diff --git a/docs/en/standards.rst b/docs/en/standards.rst index 924e882fc..2a2c017f8 100644 --- a/docs/en/standards.rst +++ b/docs/en/standards.rst @@ -1,8 +1 @@ -.. include:: ../common/common_definitions.rst - -.. _standards.rst: - -Standards -+++++++++ - -TODO +.. include:: ../common/standards.rst diff --git a/docs/en/trust.rst b/docs/en/trust.rst index 817b523ee..319cad72e 100644 --- a/docs/en/trust.rst +++ b/docs/en/trust.rst @@ -38,8 +38,8 @@ Therein a table with the summary of the Federation Entity roles mapped on the co | EUDI Role | Federation Role| Notes | +=========================================+================+===================================+ | Public Key Infrastructure (PKI) | Trust Anchor | The Federation has PKI | -| | Intermediates | capabilities and the | -| | | Entity that configures | +| | | capabilities and the | +| | Intermediates | Entity that configures | | | | the entire infrastructure | | | | is the Trust Anchor. | | | | | @@ -59,15 +59,14 @@ Therein a table with the summary of the Federation Entity roles mapped on the co | Trust Service Provider (TSP) | Leaf | | +-----------------------------------------+----------------+-----------------------------------+ | Trusted List | Trust Anchor | The listing endpoint, the | -| | Intermediates | trust mark status endpoint | -| | | and the fetch endpoint must | +| | | trust mark status endpoint | +| | Intermediates | and the fetch endpoint must | | | | be exposed by both Trust Anchors | | | | and their Intermediates, making | | | | the Trusted List distributed | | | | over multiple Federation Entities,| | | | where each of these is responsible| | | | for their accredited subordinates.| -| | | | +-----------------------------------------+----------------+-----------------------------------+ | EUDI Wallet Provider | Leaf | | +-----------------------------------------+----------------+-----------------------------------+ @@ -83,7 +82,7 @@ OpenID Federation facilitates the building of an infrastructure that is: - **Guarantor of the non-repudiation of long-lived attestations**, historical keys endpoints and historical Trust Chains are saved for years according to data retention policies. This enables the certification of the validity of historical compliance, even in cases of revocation, expiration, or rotation of the keys used for signature verification; - **Dynamic and flexible**, any participants have the freedom to modify parts of their metadata autonomously, as these are published within their domains and verified through the Trust Chain. Simultaneously, the Trust Anchor or its Intermediate may publish a metadata policy to dynamically modify the metadata of all participants — such as disabling a vulnerable signature algorithm — and obtain certainty of propagation within a configured period of time within the federation; - **Developer friendly**, JWT and JSON formats have been adopted on the web for years. They are cost-effective in terms of storage and processing and have a wide range of solutions available, such as libraries and software development kits, which enable rapid implementation of the solution; -- **Scalable**, the Trust Model can accommodate more than a single organization by using Intermediates. +- **Scalable**, the Trust Model can accommodate more than a single organization by using Intermediates and multiple Trust Anchors where needed. Trust Model Requirements ------------------------ @@ -98,23 +97,19 @@ In the table below there’s the map of the components that the ARF defines with | Issuers registration | |check-icon| | Trust Anchor | | | | | | | | Intermediate | -| | | OnBoarding | +| | | accreditation | | | | systems | | | | | +----------------------------------------------------+--------------+----------------+ | Recognised data models and schemas | |check-icon| | Entity | | | | Configuration | | | | | -| | | | -| | | | | | | Entity | | | | Statements | +----------------------------------------------------+--------------+----------------+ | Relying Parties’ registration and authentication | |check-icon| | static | | | | Trust Chains | | | | | -| | | | -| | | | | | | Federation | | | | Entity | | | | Discovery | @@ -122,8 +117,6 @@ In the table below there’s the map of the components that the ARF defines with | Trust mechanisms in a cross-domain scenario | |check-icon| | static | | | | Trust Chains | | | | | -| | | | -| | | | | | | Federation | | | | Entity | | | | Discovery | @@ -150,14 +143,15 @@ All the endpoints listed below are defined in the `OIDC-FED`_ specs. | | |party (Superior Entity). It’s | | | | |called Entity Configuration. | Relying Party | | | | | | -| | | | | +| | | | Credential | +| | | | Issuer | +---------------------------+----------------------------------------------+--------------------------------+-----------------+ | subordinate list endpoint | **GET** /list |Lists the Subordinates. | Trust Anchor | | | | | | | | | | Intermediate | +---------------------------+----------------------------------------------+--------------------------------+-----------------+ | fetch endpoint | **GET** /fetch?sub=https://rp.example.org | | Trust Anchor | -| | |Returns a document (JWS) | | +| | |Returns a signed document (JWS) | | | | |about a specific subject, its | Intermediate | | | |Subordinate. It’s called Entity | | | | |Statement. | | @@ -169,13 +163,13 @@ All the endpoints listed below are defined in the `OIDC-FED`_ specs. | | |subject. | | +---------------------------+----------------------------------------------+--------------------------------+-----------------+ | historical keys | **GET** | | Trust Anchor | -| | |Lists its expired and revoked | | +| | |Lists the expired and revoked | | | | |keys, with the motivation of the| Intermediate | | | .well-known/openid-federation-historical-jwks|revocation. | | | | | | | +---------------------------+----------------------------------------------+--------------------------------+-----------------+ -All the responses of the Federation endpoints are in the form of a JWS, with the exception of the **Subordinate Listing endpoint** and the **Trust Mark Status endpoint** that are served as plain JSON by default, however these may be signed if required. +All the responses of the Federation endpoints are in the form of a JWS, with the exception of the **Subordinate Listing endpoint** and the **Trust Mark Status endpoint** that are served as plain JSON by default, however these MAY be signed if required. Configuration of the Federation @@ -184,7 +178,7 @@ Configuration of the Federation The configuration of the Federation is published by the Trust Anchor within its Entity Configuration, available at the well-known web path corresponding to **.well-known/openid-federation**. All entities MUST obtain the Federation configuration before entering the operational phase, and they -MUST keep it up-to-date. The Federation configuration contains the Trust Anchor +MUST keep it up-to-date. The Federation configuration is the Trust Anchor's Entity Configuration, it contains the public keys for signature operations and the maximum number of Intermediates allowed between a Leaf and the Trust Anchor (**max_path_length**). Below is a non-normative example of a Trust Anchor Entity Configuration, where each parameter is documented in the `OpenID Connect Federation `_ specifications, Section 3.1 for the Federation statements and Section 4 for the Metadata identifiers: @@ -289,15 +283,15 @@ The Entity Configurations of all the participants have in common the parameters * - **exp** - UNIX Timestamp with the expiry time of the JWT, coded as NumericDate as indicated at :rfc:`7519`. * - **jwks** - - A JSON Web Key Set (JWKS) :rfc:`7517` that represents the public part of the signing keys of the Entity at issue. Each JWK in the JWK set MUST have a key ID (claim kid) and MAY have a `x5c` parameter, as defined in :rfc:`7517`. + - A JSON Web Key Set (JWKS) :rfc:`7517` that represents the public part of the signing keys of the Entity at issue. Each JWK in the JWK set MUST have a key ID (claim kid) and MAY have a `x5c` parameter, as defined in :rfc:`7517`. It contains the Federation Entity Keys required for trust evaluation. * - **metadata** - JSON Object. Each key of the JSON Object represents a metadata type identifier containing JSON Object representing the Metadata, according to the Metadata - schema of that type. An Entity Configuration MAY contain more Metadata statements, but only one for each type of + schema of that type. An Entity Configuration MAY contain more Metadata statements, but only one for each type of Metadata (<**entity_type**>). the metadata types are defined in the section `Metadata Types `_. .. note:: - Inside the Entity Configuration the claims **iss** e **sub** contain the same value (HTTPs URL). + Inside the Entity Configuration the claims **iss** e **sub** MUST contain the same value (HTTPs URL). Entity Configuration Trust Anchor ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -465,7 +459,7 @@ Below there is a non-normative example of an Entity Statement issued by an Accre Entity Statement ^^^^^^^^^^^^^^^^^^ -The Entity Statement issued by Trust Anchors and Intermediates contain the following attributes: +The Entity Statement issued by Trust Anchors and Intermediates contains the following attributes: .. list-table:: @@ -515,9 +509,9 @@ Each Entity Statement is verifiable over time and has an expiration date. The re .. note:: The revocation of an Entity is made with the unavailability of the Entity Statement related to it. If the Trust Anchor or its Intermediates doesn't publish a valid Entity Statement, or if they publish an expired/invalid Entity Statement, the subject of the Entity Statement MUST be intended as not valid or revoked. -The concatenation of the statements, through the combination of these signing mechanisms and the binding of claims and public keys, creates the Trust Chain. +The concatenation of the statements, through the combination of these signing mechanisms and the binding of claims and public keys, forms the Trust Chain. -The Trust Chains can also be verified offline, using only the Trust Anchor's public keys. +The Trust Chains can also be verified offline, using one of the Trust Anchor's public keys. .. note:: Since the Wallet Instance is not a Federation Entity, the Trust Evaluation Mechanism related to it **requires the presentation of the Wallet Instance Attestation during the credential issuance and presentation phases**. @@ -567,14 +561,15 @@ Below is a non-normative example of a Trust Chain in its original format (JSON A .. code-block:: python [ - "eyJhbGciOiJFUzI1NiIsImtpZCI6ImVEUkNOSGhWYXpWd01VRlpjMVU0UlRremMxSjRNMGRVYUU4MWVVWk5VMVUyWkdSM1lqRmZTV2h1UVEiLCJ0eXAiOiJhcHBsaWNhdGlvbi9lbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2NDk1OTA2MDIsImlhdCI6MTY0OTQxNzg2MiwiaXNzIjoiaHR0cHM6Ly9ycC5leGFtcGxlLm9yZyIsInN1YiI6Imh0dHBzOi8vcnAuZXhhbXBsZS5vcmciLCJqd2tzIjp7ImtleXMiOlt7Imt0eSI6IkVDIiwia2lkIjoiZURSQ05IaFZhelZ3TVVGWmMxVTRSVGt6YzFKNE0wZFVhRTgxZVVaTlUxVTJaR1IzWWpGZlNXaHVRUSIsImNydiI6IlAtMjU2IiwieCI6Ik1wVlVHeUhlOGhQVHh5dklZRFd2NnJpZHN5aDFDUFB2TG94ZU0wUWhaN3ciLCJ5IjoidF95ZlBRd1Z1am5oS25fNVZnT05WcW93UzJvZGZwVWxfWnNvV1UzTDRHTSJ9XX0sIm1ldGFkYXRhIjp7Im9wZW5pZF9yZWx5aW5nX3BhcnR5Ijp7ImFwcGxpY2F0aW9uX3R5cGUiOiJ3ZWIiLCJjbGllbnRfaWQiOiJodHRwczovL3JwLmV4YW1wbGUub3JnLyIsImNsaWVudF9yZWdpc3RyYXRpb25fdHlwZXMiOlsiYXV0b21hdGljIl0sImp3a3MiOnsia2V5cyI6W3sia3R5IjoiRUMiLCJraWQiOiJlRFJDTkhoVmF6VndNVUZaYzFVNFJUa3pjMUo0TTBkVWFFODFlVVpOVTFVMlpHUjNZakZmU1dodVFRIiwiY3J2IjoiUC0yNTYiLCJ4IjoiTXBWVUd5SGU4aFBUeHl2SVlEV3Y2cmlkc3loMUNQUHZMb3hlTTBRaFo3dyIsInkiOiJ0X3lmUFF3VnVqbmhLbl81VmdPTlZxb3dTMm9kZnBVbF9ac29XVTNMNEdNIn1dfSwiY2xpZW50X25hbWUiOiJOYW1lIG9mIGFuIGV4YW1wbGUgb3JnYW5pemF0aW9uIiwiY29udGFjdHMiOlsib3BzQHJwLmV4YW1wbGUuaXQiXSwiZ3JhbnRfdHlwZXMiOlsicmVmcmVzaF90b2tlbiIsImF1dGhvcml6YXRpb25fY29kZSJdLCJyZWRpcmVjdF91cmlzIjpbImh0dHBzOi8vcnAuZXhhbXBsZS5vcmcvb2lkYy9ycC9jYWxsYmFjay8iXSwicmVzcG9uc2VfdHlwZXMiOlsiY29kZSJdLCJzY29wZXMiOiJldS5ldXJvcGEuZWMuZXVkaXcucGlkLjEgZXUuZXVyb3BhLmVjLmV1ZGl3LnBpZC5pdC4xIGVtYWlsIiwic3ViamVjdF90eXBlIjoicGFpcndpc2UifSwiZmVkZXJhdGlvbl9lbnRpdHkiOnsiZmVkZXJhdGlvbl9yZXNvbHZlX2VuZHBvaW50IjoiaHR0cHM6Ly9ycC5leGFtcGxlLm9yZy9yZXNvbHZlLyIsIm9yZ2FuaXphdGlvbl9uYW1lIjoiRXhhbXBsZSBSUCIsImhvbWVwYWdlX3VyaSI6Imh0dHBzOi8vcnAuZXhhbXBsZS5pdCIsInBvbGljeV91cmkiOiJodHRwczovL3JwLmV4YW1wbGUuaXQvcG9saWN5IiwibG9nb191cmkiOiJodHRwczovL3JwLmV4YW1wbGUuaXQvc3RhdGljL2xvZ28uc3ZnIiwiY29udGFjdHMiOlsidGVjaEBleGFtcGxlLml0Il19fSwidHJ1c3RfbWFya3MiOlt7ImlkIjoiaHR0cHM6Ly9yZWdpc3RyeS5laWRhcy50cnVzdC1hbmNob3IuZXhhbXBsZS5ldS9vcGVuaWRfcmVseWluZ19wYXJ0eS9wdWJsaWMvIiwidHJ1c3RfbWFyayI6ImV5SmggXHUyMDI2In1dLCJhdXRob3JpdHlfaGludHMiOlsiaHR0cHM6Ly9pbnRlcm1lZGlhdGUuZWlkYXMuZXhhbXBsZS5vcmciXX0.dIRBRyfEsmi_6oGrJAHaYUPCtXSvBZBMdokVZtjyYgzMKEP6eSLixa8nUU9BWBWP_ELNgdKbPquSbWIGx66D5w", - "eyJhbGciOiJFUzI1NiIsImtpZCI6IlFWUnVXSE5FWTJzMFdHNW5hSHB3VjJKVGRtd3hiRUpVY2pCdk9FeHNWMFExT0dnMFZWQnhhbTUyT0EiLCJ0eXAiOiJhcHBsaWNhdGlvbi9lbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2NDk2MjM1NDYsImlhdCI6MTY0OTQ1MDc0NiwiaXNzIjoiaHR0cHM6Ly9pbnRlcm1lZGlhdGUuZWlkYXMuZXhhbXBsZS5vcmciLCJzdWIiOiJodHRwczovL3JwLmV4YW1wbGUub3JnIiwiandrcyI6eyJrZXlzIjpbeyJrdHkiOiJFQyIsImtpZCI6ImVEUkNOSGhWYXpWd01VRlpjMVU0UlRremMxSjRNMGRVYUU4MWVVWk5VMVUyWkdSM1lqRmZTV2h1UVEiLCJjcnYiOiJQLTI1NiIsIngiOiJNcFZVR3lIZThoUFR4eXZJWURXdjZyaWRzeWgxQ1BQdkxveGVNMFFoWjd3IiwieSI6InRfeWZQUXdWdWpuaEtuXzVWZ09OVnFvd1Myb2RmcFVsX1pzb1dVM0w0R00ifV19LCJtZXRhZGF0YV9wb2xpY3kiOnsib3BlbmlkX3JlbHlpbmdfcGFydHkiOnsic2NvcGVzIjp7InN1YnNldF9vZiI6WyJldS5ldXJvcGEuZWMuZXVkaXcucGlkLjEsICBldS5ldXJvcGEuZWMuZXVkaXcucGlkLml0LjEiXX0sInJlcXVlc3RfYXV0aGVudGljYXRpb25fbWV0aG9kc19zdXBwb3J0ZWQiOnsib25lX29mIjpbInJlcXVlc3Rfb2JqZWN0Il19LCJyZXF1ZXN0X2F1dGhlbnRpY2F0aW9uX3NpZ25pbmdfYWxnX3ZhbHVlc19zdXBwb3J0ZWQiOnsic3Vic2V0X29mIjpbIlJTMjU2IiwiUlM1MTIiLCJFUzI1NiIsIkVTNTEyIiwiUFMyNTYiLCJQUzUxMiJdfX19LCJ0cnVzdF9tYXJrcyI6W3siaWQiOiJodHRwczovL3RydXN0LWFuY2hvci5leGFtcGxlLmV1L29wZW5pZF9yZWx5aW5nX3BhcnR5L3B1YmxpYy8iLCJ0cnVzdF9tYXJrIjoiZXlKaGIgXHUyMDI2In1dfQ.rIgdHa7CoaP3SO3ZNsjDWt7-8Tea41An3YBw-qaWFNdQMUzcTqRwcD4vtX6TZEEoRO3KEu8bJeaKlikHRHzoBg", - "eyJhbGciOiJFUzI1NiIsImtpZCI6ImVVRldSakJKYlhVeU5TMHRhV1JrYlhCMWVURlBjazV6UzBGRVFTMWFNVFpEYTNOWk1WUktURTR5Y3ciLCJ0eXAiOiJhcHBsaWNhdGlvbi9lbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2NDk2MjM1NDYsImlhdCI6MTY0OTQ1MDc0NiwiaXNzIjoiaHR0cHM6Ly90cnVzdC1hbmNob3IuZXhhbXBsZS5ldSIsInN1YiI6Imh0dHBzOi8vaW50ZXJtZWRpYXRlLmVpZGFzLmV4YW1wbGUub3JnIiwiandrcyI6eyJrZXlzIjpbeyJrdHkiOiJFQyIsImtpZCI6IlFWUnVXSE5FWTJzMFdHNW5hSHB3VjJKVGRtd3hiRUpVY2pCdk9FeHNWMFExT0dnMFZWQnhhbTUyT0EiLCJjcnYiOiJQLTI1NiIsIngiOiJCR1VOOXN6ZG0xT1RxVWhUQ3JkcWRmQjhtTUJqb2JCYk5Nd2JxZnd4c3pZIiwieSI6IkdnMUhCNGVJRWJhQjA4NEJiUW5QX0lseFJZYTNhVVRHSTF0aW5qTmVSdmMifV19LCJ0cnVzdF9tYXJrcyI6W3siaWQiOiJodHRwczovL3RydXN0LWFuY2hvci5leGFtcGxlLmV1L2ZlZGVyYXRpb25fZW50aXR5L3RoYXQtcHJvZmlsZSIsInRydXN0X21hcmsiOiJleUpoYiBcdTIwMjYifV19.KR2oBDMfqLGCZ2ZqN0FgOP7cWsW4ClxBaj4-j_c3HC-YEecK6SLlNk00bGqoEe2NCMy2lqk9dYQO1IauB_ZG7A" + "eyJhbGciOiJFUzI1NiIsImtpZCI6Ik5GTTFXVVZpVWxZelVXcExhbWxmY0VwUFJWWTJWWFpJUmpCblFYWm1SSGhLWVVWWVVsZFRRbkEyTkEiLCJ0eXAiOiJhcHBsaWNhdGlvbi9lbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2NDk1OTA2MDIsImlhdCI6MTY0OTQxNzg2MiwiaXNzIjoiaHR0cHM6Ly9ycC5leGFtcGxlLm9yZyIsInN1YiI6Imh0dHBzOi8vcnAuZXhhbXBsZS5vcmciLCJqd2tzIjp7ImtleXMiOlt7Imt0eSI6IkVDIiwia2lkIjoiTkZNMVdVVmlVbFl6VVdwTGFtbGZjRXBQUlZZMlZYWklSakJuUVhabVJIaEtZVVZZVWxkVFFuQTJOQSIsImNydiI6IlAtMjU2IiwieCI6InVzbEMzd2QtcFgzd3o0YlJZbnd5M2x6cGJHWkZoTjk2aEwyQUhBM01RNlkiLCJ5IjoiVkxDQlhGV2xkTlNOSXo4a0gyOXZMUjROMThCa3dHT1gyNnpRb3J1UTFNNCJ9XX0sIm1ldGFkYXRhIjp7Im9wZW5pZF9yZWx5aW5nX3BhcnR5Ijp7ImFwcGxpY2F0aW9uX3R5cGUiOiJ3ZWIiLCJjbGllbnRfaWQiOiJodHRwczovL3JwLmV4YW1wbGUub3JnLyIsImNsaWVudF9yZWdpc3RyYXRpb25fdHlwZXMiOlsiYXV0b21hdGljIl0sImp3a3MiOnsia2V5cyI6W3sia3R5IjoiRUMiLCJraWQiOiJORk0xV1VWaVVsWXpVV3BMYW1sZmNFcFBSVlkyVlhaSVJqQm5RWFptUkhoS1lVVllVbGRUUW5BMk5BIiwiY3J2IjoiUC0yNTYiLCJ4IjoidXNsQzN3ZC1wWDN3ejRiUllud3kzbHpwYkdaRmhOOTZoTDJBSEEzTVE2WSIsInkiOiJWTENCWEZXbGROU05JejhrSDI5dkxSNE4xOEJrd0dPWDI2elFvcnVRMU00In1dfSwiY2xpZW50X25hbWUiOiJOYW1lIG9mIGFuIGV4YW1wbGUgb3JnYW5pemF0aW9uIiwiY29udGFjdHMiOlsib3BzQHJwLmV4YW1wbGUuaXQiXSwiZ3JhbnRfdHlwZXMiOlsicmVmcmVzaF90b2tlbiIsImF1dGhvcml6YXRpb25fY29kZSJdLCJyZWRpcmVjdF91cmlzIjpbImh0dHBzOi8vcnAuZXhhbXBsZS5vcmcvb2lkYy9ycC9jYWxsYmFjay8iXSwicmVzcG9uc2VfdHlwZXMiOlsiY29kZSJdLCJzY29wZSI6ImV1LmV1cm9wYS5lYy5ldWRpdy5waWQuMSBldS5ldXJvcGEuZWMuZXVkaXcucGlkLml0LjEgZW1haWwiLCJzdWJqZWN0X3R5cGUiOiJwYWlyd2lzZSJ9LCJmZWRlcmF0aW9uX2VudGl0eSI6eyJmZWRlcmF0aW9uX3Jlc29sdmVfZW5kcG9pbnQiOiJodHRwczovL3JwLmV4YW1wbGUub3JnL3Jlc29sdmUvIiwib3JnYW5pemF0aW9uX25hbWUiOiJFeGFtcGxlIFJQIiwiaG9tZXBhZ2VfdXJpIjoiaHR0cHM6Ly9ycC5leGFtcGxlLml0IiwicG9saWN5X3VyaSI6Imh0dHBzOi8vcnAuZXhhbXBsZS5pdC9wb2xpY3kiLCJsb2dvX3VyaSI6Imh0dHBzOi8vcnAuZXhhbXBsZS5pdC9zdGF0aWMvbG9nby5zdmciLCJjb250YWN0cyI6WyJ0ZWNoQGV4YW1wbGUuaXQiXX19LCJ0cnVzdF9tYXJrcyI6W3siaWQiOiJodHRwczovL3JlZ2lzdHJ5LmVpZGFzLnRydXN0LWFuY2hvci5leGFtcGxlLmV1L29wZW5pZF9yZWx5aW5nX3BhcnR5L3B1YmxpYy8iLCJ0cnVzdF9tYXJrIjoiZXlKaCBcdTIwMjYifV0sImF1dGhvcml0eV9oaW50cyI6WyJodHRwczovL2ludGVybWVkaWF0ZS5laWRhcy5leGFtcGxlLm9yZyJdfQ.Un315HdckvhYA-iRregZAmL7pnfjQH2APz82blQO5S0sl1JR0TEFp5E1T913g8GnuwgGtMQUqHPZwV6BvTLA8g", + "eyJhbGciOiJFUzI1NiIsImtpZCI6IlNURkRXV2hKY0dWWFgzQjNSVmRaYWtsQ0xUTnVNa000WTNGNlFUTk9kRXRyZFhGWVlYWjJjWGN0UVEiLCJ0eXAiOiJhcHBsaWNhdGlvbi9lbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2NDk2MjM1NDYsImlhdCI6MTY0OTQ1MDc0NiwiaXNzIjoiaHR0cHM6Ly9pbnRlcm1lZGlhdGUuZWlkYXMuZXhhbXBsZS5vcmciLCJzdWIiOiJodHRwczovL3JwLmV4YW1wbGUub3JnIiwiandrcyI6eyJrZXlzIjpbeyJrdHkiOiJFQyIsImtpZCI6Ik5GTTFXVVZpVWxZelVXcExhbWxmY0VwUFJWWTJWWFpJUmpCblFYWm1SSGhLWVVWWVVsZFRRbkEyTkEiLCJjcnYiOiJQLTI1NiIsIngiOiJ1c2xDM3dkLXBYM3d6NGJSWW53eTNsenBiR1pGaE45NmhMMkFIQTNNUTZZIiwieSI6IlZMQ0JYRldsZE5TTkl6OGtIMjl2TFI0TjE4Qmt3R09YMjZ6UW9ydVExTTQifV19LCJtZXRhZGF0YV9wb2xpY3kiOnsib3BlbmlkX3JlbHlpbmdfcGFydHkiOnsic2NvcGUiOnsic3Vic2V0X29mIjpbImV1LmV1cm9wYS5lYy5ldWRpdy5waWQuMSwgIGV1LmV1cm9wYS5lYy5ldWRpdy5waWQuaXQuMSJdfSwicmVxdWVzdF9hdXRoZW50aWNhdGlvbl9tZXRob2RzX3N1cHBvcnRlZCI6eyJvbmVfb2YiOlsicmVxdWVzdF9vYmplY3QiXX0sInJlcXVlc3RfYXV0aGVudGljYXRpb25fc2lnbmluZ19hbGdfdmFsdWVzX3N1cHBvcnRlZCI6eyJzdWJzZXRfb2YiOlsiUlMyNTYiLCJSUzUxMiIsIkVTMjU2IiwiRVM1MTIiLCJQUzI1NiIsIlBTNTEyIl19fX0sInRydXN0X21hcmtzIjpbeyJpZCI6Imh0dHBzOi8vdHJ1c3QtYW5jaG9yLmV4YW1wbGUuZXUvb3BlbmlkX3JlbHlpbmdfcGFydHkvcHVibGljLyIsInRydXN0X21hcmsiOiJleUpoYiBcdTIwMjYifV19._qt5-T6DahP3TuWa_27klE8I9Z_sPK2FtQlKY6pGMPchbSI2aHXY3aAXDUrObPo4CHtqgg3J2XcrghDFUCFGEQ", + "eyJhbGciOiJFUzI1NiIsImtpZCI6ImVXa3pUbWt0WW5kblZHMWxhMjU1ZDJkQ2RVZERSazQwUWt0WVlVMWFhRFZYT1RobFpHdFdXSGQ1WnciLCJ0eXAiOiJhcHBsaWNhdGlvbi9lbnRpdHktc3RhdGVtZW50K2p3dCJ9.eyJleHAiOjE2NDk2MjM1NDYsImlhdCI6MTY0OTQ1MDc0NiwiaXNzIjoiaHR0cHM6Ly90cnVzdC1hbmNob3IuZXhhbXBsZS5ldSIsInN1YiI6Imh0dHBzOi8vaW50ZXJtZWRpYXRlLmVpZGFzLmV4YW1wbGUub3JnIiwiandrcyI6eyJrZXlzIjpbeyJrdHkiOiJFQyIsImtpZCI6IlNURkRXV2hKY0dWWFgzQjNSVmRaYWtsQ0xUTnVNa000WTNGNlFUTk9kRXRyZFhGWVlYWjJjWGN0UVEiLCJjcnYiOiJQLTI1NiIsIngiOiJyQl9BOGdCUnh5NjhVTkxZRkZLR0ZMR2VmWU5XYmgtSzh1OS1GYlQyZkZJIiwieSI6IlNuWVk2Y3NjZnkxcjBISFhLTGJuVFZsamFndzhOZzNRUEs2WFVoc2UzdkUifV19LCJ0cnVzdF9tYXJrcyI6W3siaWQiOiJodHRwczovL3RydXN0LWFuY2hvci5leGFtcGxlLmV1L2ZlZGVyYXRpb25fZW50aXR5L3RoYXQtcHJvZmlsZSIsInRydXN0X21hcmsiOiJleUpoYiBcdTIwMjYifV19.r3uoi-U0tx0gDFlnDdITbcwZNUpy7M2tnh08jlD-Ej9vMzWMCXOCCuwIn0ZT0jS4M_sHneiG6tLxRqj-htI70g" ] + .. note:: - The entire Trust Chain is verifiable by only possessing the Trust Anchor’s public key. + The entire Trust Chain is verifiable by only possessing the Trust Anchor’s public keys. Offline Trust Attestation Mechanisms @@ -590,10 +585,11 @@ offline trust evaluation mechanisms. Offline EUDI Wallet Trust Attestation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Given that a mobile device SHOULD not publish its metadata online at the *.well-known/openid-federation* endpoint, or in any other way, it is not mandatory for the Wallet Instance to publish its metadata if the User does not want this. As a result, the Wallet Instance does not need to publish its federation metadata online. +Given that a mobile device SHOULD not publish its metadata online at the *.well-known/openid-federation* endpoint, or in any other way, it is not mandatory for the Wallet Instance to publish its metadata if the User does not want this. As a result, the Wallet Instance does not require to publish its federation metadata online. However, the Wallet Instance MUST obtain a Wallet Attestation Instance issued by its Wallet Provider, which should contain a Trust Chain related to its issuer (Wallet Provider). + Offline Relying Party Metadata ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -605,33 +601,34 @@ The Wallet Instance that verifies the request issued by the Relying Party MUST u Furthermore, the Wallet Instance applies the metadata policy, if available, to filter out any User attributes not attested in the Relying Party metadata, as derived from the Trust Chain made available in the Relying Party's signed request. + Non-repudiability of the Long Lived Attestations -------------------------------------------------- -The Trust Anchor and its Intermediate MUST expose the Historical keys endpoint, where are published all the public keys that are no longer used, whether expired or revoked. +The Trust Anchor and its Intermediate MUST expose the Federation Historical Keys endpoint, where are published all the public part of the Federation Entity Keys that are no longer used, whether expired or revoked. The details of this endpoint are defined in the `OIDC-FED`_ Section 7.6. Each JWS containing a Trust Chain in the form of a JWS header parameter can be verified over time, since the entire Trust Chain is verifiable using the Trust Anchor's public key. -Even if the Trust Anchor has changed its cryptographic keys for digital signature, the historical keys endpoint always makes the keys no longer used available for historical signature verifications. +Even if the Trust Anchor has changed its cryptographic keys for digital signature, the Federation Historical Keys endpoint always makes the keys no longer used available for historical signature verifications. -Privacy Considerations ----------------------- +Privacy Remarks +--------------- -- Wallet Instances do not publish their metadata through an online service. -- The trust infrastructure is public, with all endpoints publicly accessible without any client credentials that may disclose who is requesting access. +- Wallet Instances MUST NOT publish their metadata through an online service. +- The trust infrastructure MUST be public, with all endpoints publicly accessible without any client credentials that may disclose who is requesting access. - When a Wallet Instance requests the Entity Statements to build the Trust Chain for a specific Relying Party or validates a Trust Mark online, issued for a specific Relying Party, the Trust Anchor or its Intermediate do not know that a particular Wallet Instance is inquiring about a specific Relying Party; instead, they only serve the statements related to that Relying Party as a public resource. -- The Wallet instance metadata must not contain information that may disclose technical information about the hardware used. +- The Wallet Instance metadata MUST not contain information that may disclose technical information about the hardware used. - Leaf entity, Intermediate, and Trust Anchor metadata may include the necessary amount of data as part of administrative, technical, and security contact information. It is generally not recommended to use personal contact details in such cases. From a legal perspective, the publication of such information is needed for operational support concerning technical and security matters and is in line with GDPR. Considerations about Decentralization ------------------------------------- -- There should be more than one Trust Anchor. -- In some cases, a trust verifier may trust an Intermediate, especially when the Intermediate may represent itself as a Trust Anchor within a specific perimeter, such as cases where the Leafs are both in the same perimeter like a Member State jurisdiction (eg: Italian RP with an Italian Wallet Instance may consider the Italian Accreditation Body as Trust Anchor). +- There may be more than a single Trust Anchor. +- In some cases, a trust verifier may trust an Intermediate, especially when the Intermediate may represent itself as a Trust Anchor within a specific perimeter, such as cases where the Leafs are both in the same perimeter like a Member State jurisdiction (eg: an Italian Relying Party with an Italian Wallet Instance may consider the Italian Intermediate as a Trust Anchor for the scopes of their interactions). - Trust attestations (Trust Chain) should be included in the JWS issued by Credential Issuers, and the Presentation Requests of RPs should contain the Trust Chain related to them (issuers of the presentation requests). -- Since the credential presentation must be signed, saving the signed presentation requests and responses, which include the Trust Chain, the Wallet Instance has a snapshot of the federation configuration (Trust Anchor Entity Configuration in the Trust Chain) and the verifiable reliability of the Relying Party it has interacted with. This information must be stored on the Wallet Device and backed up in a remote and secure cloud storage, with the explicit permission of its User. +- Since the credential presentation must be signed, saving the signed presentation requests and responses, which include the Trust Chain, the Wallet Instance may have snapshot of the federation configuration (Trust Anchor Entity Configuration in the Trust Chain) and the verifiable reliability of the Relying Party it has interacted with. This information must be stored on the Wallet Device and may be backed up in a remote and secure cloud storage, with the explicit permission of its User. - Each signed attestation is long-lived since it can be cryptographically validated even when the federation configuration changes or the keys of its issuers are renewed. - Each participant should be able to update its Entity Configuration without notifying the changes to any third party. The Metadata Policy of a Trust Chain must be applied to overload any information related to protocol metadata and allowed grants of the participants. diff --git a/docs/en/wallet-instance-attestation.rst b/docs/en/wallet-instance-attestation.rst index a61dc36fe..dbb895afa 100644 --- a/docs/en/wallet-instance-attestation.rst +++ b/docs/en/wallet-instance-attestation.rst @@ -5,43 +5,33 @@ Wallet Instance Attestation +++++++++++++++++++++++++++ -The Wallet Instance Attestation is data containing details about the Wallet Provider, the Wallet Solution, 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 Instance Attestation MUST contain the Wallet Instance public key. +The Wallet Instance 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 Instance Attestation MUST contain a Wallet Instance public key. General Properties ------------------ -The objectives include: +The Wallet Instance Attestation: -- Ensuring that the Wallet Instance maintains a level of **integrity** that is capable of preventing any manipulation or forgery attempts by unauthorized third parties. -- Having the Wallet Provider issue a certificate of conformity to assure that the previously mentioned security and trust objectives are fulfilled. +- 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. -To meet these requirements, it is necessary for each Wallet Instance to issue an attestation of conformity, guaranteeing its security and compliance with the Trust Model. - -This verifiable attestation, called **Wallet Instance Attestation**, must be electronically signed by its issuer. - -.. hint:: - Given that the Wallet Instance does not represent an accredited entity and does not belong to an organization but resides on the User's device, the Trust Model, based on sustainability and scalability criteria, must delegate the task of issuing the **Wallet Instance Attestation** to the **Wallet Provider**. +It is necessary for each Wallet Instance to obtain an the Wallet Instance Attestation before entering the Operational state. Requirements ------------ -The following requirements are assumed for the Wallet Instance Attestation: - -1. **Efficiency**: The Wallet Instance Attestation should use an efficient format like JSON Web Token (JWT) for light and fast data management, and compliance with various formats used for eudiw solutions. -2. **Simplicity**: The Wallet Provider should be based on a REST architecture for issuing Wallet Instance Attestations. -3. **Public key holder binding**: The Wallet Instance Attestation must be securely linked to the Wallet Instance public key. -4. **Issued and signed by an accredited Wallet Provider**: The Wallet Instance Attestation must be issued and signed by an accredited and reliable Wallet Provider, thereby providing integrity and authenticity to the attestation. -5. **Authenticity/Genuineness of the Wallet Instance**: The Wallet Instance Attestation must ensure the integrity and authenticity of the Wallet Instance, verifying that it was accurately created and provided by the Wallet Provider. ⚠️ -6. **Ability to request multiple claims for several public keys**: Each Wallet Instance should be able to request multiple attestations for different public keys associated with it. This requirement provides a privacy-preserving measure, as the public key could be used as a tracking tool in the credentials’ disclosure phase (also see point 10 below). -7. **Reusability**: The Wallet Instance Attestation should be usable multiple times during the validity period of the attestation, allowing for repeated authentication and authorization without the need to request new attestations with each interaction. -8. **Expiration**: The Wallet Instance Attestation should have a well-defined expiration date, after which it will no longer be considered valid, thereby ensuring the security and updating of attestations over time. -9. **Revocation in case of loss/deletion of the private key**: If the private key associated with the Wallet Instance is lost or deleted, the attestation automatically becomes invalid to prevent unauthorized use of the Wallet Instance. ⚠️ -10. **Pseudonymisation**: The attestations are designed to be pseudonymised (i.e., they do not contain direct references to the person, making it impossible to identify them in the absence of additional information - see art. 4(5) GDPR for a comprehensive definition). Without such a measure, the use of the attestation on multiple RPs would pose a significant risk, as it would theoretically allow the RPs to merge databases and track Users. This requirement enhances the measures adopted according to +The following requirements for the Wallet Instance Attestation are met: - art. 32 GDPR. +1. The Wallet Instance Attestation MUST use a signed JSON Web Token (JWT) format. +2. The Wallet Provider MUST offer a RESTful set of services for issuing the Wallet Instance Attestations. +3. The Wallet Instance Attestation MUST be securely bound to the Wallet Instance public key (**Holder Key Binding**). +4. The Wallet Instance Attestation MUST be issued and signed by an accredited and reliable Wallet Provider, thereby providing integrity and authenticity to the attestation. +5. The Wallet Instance 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 for different public keys associated with it. This requirement provides a privacy-preserving measure, as the public key MAY be used as a tracking tool during the presentation phase (see alos the point number 10, listed below). +7. The Wallet Instance 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 Instance 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. -.. attention:: - ⚠️ Implementation of points no. 5 and 9 is still under discussion. This version assumes the authenticity and non-revocability of the Wallet Instance. High-level Design ----------------- @@ -64,14 +54,14 @@ This section describes the Wallet Instance Attestation format and how the Wallet :alt: The figure illustrates the sequence diagram for issuing a Wallet Instance 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 -- **Message 1**: The User starts the Wallet Instance mobile app, a new Wallet Instance Attestation is automatically obtained if the previous one results expired. -- **Message 2-3**: The Wallet Instance retrieves metadata about its Wallet Provider, including the list of supported algorithms, public keys, and endpoints. -- **Message 4**: The Wallet Instance verifies the Wallet Provider's trustworthiness by resolving the provider's trust chain to the Trust Anchor. +- **Message 1**: The User starts the Wallet Instance mobile app and gets authenticated in it, a new Wallet Instance Attestation is automatically obtained if the previous one results expired. +- **Message 2-3**: The Wallet Instance retrieves the Wallet Provider metadata, including the list of supported algorithms, public keys, and endpoints. +- **Message 4**: The Wallet Instance verifies the Wallet Provider's trustworthiness by evaluating its Trust Chain. - **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 Instance Attestation Request in JWS format, signed with the private key associated with the public key for which it seeks attestation. -- **Message 9-13**: The Wallet Instance sends the Wallet Instance Attestation Request to the Wallet Provider, which validates it and issues a signed attestation in return. -- **Message 13-14**: The Wallet Instance receives the Wallet Instance Attestation signed by the Wallet Provider and performs formal verification. +- **Message 8**: The Wallet Instance creates a Wallet Instance 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 Instance Attestation Request to the Wallet Provider, which validates it and issues a signed attestation to the Wallet Instance. +- **Message 13-14**: The Wallet Instance receives the Wallet Instance Attestation signed by the Wallet Provider and performs security and integrity verifications. - **Message 15**: The Wallet Instance Attestation is now ready for use. Detailed Design @@ -94,10 +84,11 @@ Header | alg | Algorithm to verify the token | | | signature (es. ES256). | +-----------------------------------+-----------------------------------+ -| kid | Key id of the Wallet Instance. | +| kid | Key id of the public key | +| | created by the Wallet Instance. | +-----------------------------------+-----------------------------------+ -| typ | Media type, in this case we use | -| | the value ``wiar+jwt``. | +| typ | Media type, set to | +| | ``wiar+jwt``. | +-----------------------------------+-----------------------------------+ Payload @@ -106,7 +97,7 @@ Payload +--------+-------------------------------------------------------------+ | **key**| **value** | +--------+-------------------------------------------------------------+ -|| iss || The thumbprint | +|| iss || Thumbprint value | || || of the JWK of the Wallet Instance | || || for which the attestation is | || || being requested. | @@ -118,7 +109,7 @@ Payload || || `RFC7519 `_.| || || | +--------+-------------------------------------------------------------+ -|| nonce || The nonce obtained from the | +|| nonce || The nonce value obtained from the | || || App Attestation Service. | +--------+-------------------------------------------------------------+ || cnf || JSON object, according to | @@ -157,15 +148,16 @@ request where the decoded JWS headers and payload are separated by a comma: "exp": 1686652315 } -Whose corresponding JWS is verifiable through the public key -of the Wallet Instance present. +Whose corresponding JWS is verifiable using the public key +of the Wallet Provider corresponding to the `kid` made available +in the header. Format of the Wallet Instance Attestation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A JWT was chosen as the format for the Wallet Instance Attestation. -Let's see below the various fields that compose it. +The Wallet Instance Attestation MUST be provisioned in JWT format, whose +headers and payload claims are listed below. Header ^^^^^^ @@ -185,25 +177,29 @@ Header | | [`OPENID4VC-HAIP`_] | +-----------------------------------+-----------------------------------+ | x5c | Array containing the X.509 | -| | certificate (and the entire chain | -| | of certificates) used to attest | +| | chain | +| | of certificates used to attest | | | the public key of the Wallet | | | Provider. | +-----------------------------------+-----------------------------------+ -| trust_chain | Array containing the JWS of the | -| | trust chain relating to the | +| trust_chain | Array containing the Federation | +| | Trust Chain relating to the | | | Wallet Provider. | +-----------------------------------+-----------------------------------+ +.. note:: + + The claim `trust_chain` or the claim `x5c` MUST be provisioned. + If these are both provisioned, the related public key contained in + MUST be the same in both `trust_chain` and `x5c`. + Payload ^^^^^^^ +---------------------------+------------------------------------------------+ | **key** | **value** | +---------------------------+------------------------------------------------+ -|| iss || The public url of the Wallet | -|| || Instance attestation issuer. See | -|| || the example below in this section. | +|| iss || The public url of the Wallet Provider | +---------------------------+------------------------------------------------+ || sub || Thumbprint value | || || of the JWK of the Wallet Instance | @@ -220,22 +216,19 @@ Payload || || duration of the attestation. | +---------------------------+------------------------------------------------+ || attested_security_context|| Attested security context: | -|| || Represents a level of "trust" of | -|| || the service containing a Level Of | -|| || Agreement defined in the metadata | -|| || of the Wallet Provider. | +|| || Represents the level of "security" | +|| || attested by the Wallet Provider. | +---------------------------+------------------------------------------------+ || cnf || This parameter contains the ``jwk`` | || || parameter | -|| || with the public key of the Wallet | -|| || necessary for the holder binding. | +|| || 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 | -|| || that this SIOP supports. | +|| || the OAuth 2.0 ``response_type`` values. | +---------------------------+------------------------------------------------+ || vp_formats_supported || JSON object containing | || || ``jwt_vp_json`` and ``jwt_vc_json`` | @@ -243,21 +236,17 @@ Payload +---------------------------+------------------------------------------------+ || request_object_signing || JSON array containing a list of the | || _alg_values_supported || JWS signing algorithms (alg values) | -|| || supported by the SIOP for Request Objects. | +|| || supported. | +---------------------------+------------------------------------------------+ || presentation_definition || Boolean value specifying whether the | || _uri_supported || Wallet Instance supports the transfer of | -|| || presentation_definition by | -|| || reference, with true indicating support. | +|| || ``presentation_definition`` by | +|| || reference. MUST set to `false`. | +---------------------------+------------------------------------------------+ .. note:: The claim ``attested_security_context`` (Attested Security Context) is under discussion - and must be intended as experimental. - -.. note:: - - The Wallet Instance Attestation JWS is signed using the private key of the Wallet Provider. + and MUST be intended as experimental. Below is an example of Wallet Instance Attestation: @@ -272,7 +261,6 @@ Below is an example of Wallet Instance Attestation: "eyJhbGciOiJFUz...H9gw", ], "typ": "wallet-attestation+jwt", - "x5c": ["MIIBjDCC ... XFehgKQA=="] } . { @@ -310,21 +298,20 @@ Below is an example of Wallet Instance Attestation: "exp": 1687288395 } -Obtain a Wallet Instance Attestation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Obtain the Wallet Instance Attestation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To obtain the Wallet Instance Attestation it is necessary -to make a `POST `__ -request to the Wallet Solution `token endpoint`_. - -The **token** endpoint (as defined in `RFC 7523 section 4`_) requires two parameters as input, in HTTP Post method: +to make an HTTP request in method `POST `__ +to the `token endpoint`_ of the Wallet Provider. -``grant_type`` which in our case is a string: -``urn:ietf:params:oauth:grant-type:jwt-bearer`` +The **token** endpoint (as defined in `RFC 7523 section 4`_) requires the following parameters +encoded in ``application/x-www-form-urlencoded`` format: -``assertion`` which contains the signed JWT of the `Wallet Instance Attestation Request`_ +* ``grant_type`` set to ``urn:ietf:params:oauth:grant-type:jwt-bearer``; +* ``assertion`` containing the signed JWT defined in the Section `Wallet Instance Attestation Request`_. -Below a non-normative example of the request. +Below a non-normative example of the HTTP request. .. code-block:: http @@ -335,14 +322,15 @@ Below a non-normative example of the request. grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6ImtoakZWTE9nRjNHeGRxd2xVTl9LWl83NTVUT1ZEbmJIaDg2TW1KcHh2a1UifQ.eyJpc3MiOiAidmJlWEprc000NXhwaHRBTm5DaUc2bUN5dVU0amZHTnpvcEd1S3ZvZ2c5YyIsICJhdWQiOiAiaHR0cHM6Ly93YWxsZXQtcHJvdmlkZXIuZXhhbXBsZS5vcmciLCAianRpIjogImY1NjUyMDcyLWFiZWYtNDU5OS1iODYzLTlhNjkwNjA3MzJjYyIsICJub25jZSI6ICIuLi4uLiIsICJjbmYiOiB7Imp3ayI6IHsiY3J2IjogIlAtMjU2IiwgImt0eSI6ICJFQyIsICJ4IjogIjRITnB0SS14cjJwanlSSktHTW56NFdtZG5RRF91SlNxNFI5NU5qOThiNDQiLCAieSI6ICJMSVpuU0IzOXZGSmhZZ1MzazdqWEU0cjMtQ29HRlF3WnRQQklScXBObHJnIiwgImtpZCI6ICJ2YmVYSmtzTTQ1eHBodEFObkNpRzZtQ3l1VTRqZkdOem9wR3VLdm9nZzljIn19LCAiaWF0IjogMTY5MTQ4ODk2MiwgImV4cCI6IDE2OTE0OTYxNjJ9.Dg_yFaiv6lVftR3FFx0v5JW250mBgXLVP1j0ezZcHRyitqSY7xGmx4y-MGur93FAS85vf_Da-L-REVEltwU2Jw -The response is the `Wallet Instance Attestation`_ JWT in plain text: +The response is the `Wallet Instance Attestation`_ in JWT format: .. code-block:: http - HTTP/1.1 201 OK - Content-Type: application/entity-statement+jwt + HTTP/1.1 201 OK + Content-Type: application/jwt + + eyJhbGciOiJFUzI1NiIsInR5cCI6IndhbGxldC1hdHRlc3RhdGlvbitqd3QiLCJraWQiOiI1dDVZWXBCaE4tRWdJRUVJNWlVenI2cjBNUjAyTG5WUTBPbWVrbU5LY2pZIiwidHJ1c3RfY2hhaW4iOlsiZXlKaGJHY2lPaUpGVXouLi42UzBBIiwiZXlKaGJHY2lPaUpGVXouLi5qSkxBIiwiZXlKaGJHY2lPaUpGVXouLi5IOWd3Il19.eyJpc3MiOiJodHRwczovL3dhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZyIsInN1YiI6InZiZVhKa3NNNDV4cGh0QU5uQ2lHNm1DeXVVNGpmR056b3BHdUt2b2dnOWMiLCJ0eXBlIjoiV2FsbGV0SW5zdGFuY2VBdHRlc3RhdGlvbiIsInBvbGljeV91cmkiOiJodHRwczovL3dhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZy9wcml2YWN5X3BvbGljeSIsInRvc191cmkiOiJodHRwczovL3dhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZy9pbmZvX3BvbGljeSIsImxvZ29fdXJpIjoiaHR0cHM6Ly93YWxsZXQtcHJvdmlkZXIuZXhhbXBsZS5vcmcvbG9nby5zdmciLCJhdHRlc3RlZF9zZWN1cml0eV9jb250ZXh0IjoiaHR0cHM6Ly93YWxsZXQtcHJvdmlkZXIuZXhhbXBsZS5vcmcvTG9BL2Jhc2ljIiwiY25mIjp7Imp3ayI6eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6IjRITnB0SS14cjJwanlSSktHTW56NFdtZG5RRF91SlNxNFI5NU5qOThiNDQiLCJ5IjoiTElablNCMzl2RkpoWWdTM2s3alhFNHIzLUNvR0ZRd1p0UEJJUnFwTmxyZyIsImtpZCI6InZiZVhKa3NNNDV4cGh0QU5uQ2lHNm1DeXVVNGpmR056b3BHdUt2b2dnOWMifX0sImF1dGhvcml6YXRpb25fZW5kcG9pbnQiOiJldWRpdzoiLCJyZXNwb25zZV90eXBlc19zdXBwb3J0ZWQiOlsidnBfdG9rZW4iXSwidnBfZm9ybWF0c19zdXBwb3J0ZWQiOnsiand0X3ZwX2pzb24iOnsiYWxnX3ZhbHVlc19zdXBwb3J0ZWQiOlsiRVMyNTYiXX0sImp3dF92Y19qc29uIjp7ImFsZ192YWx1ZXNfc3VwcG9ydGVkIjpbIkVTMjU2Il19fSwicmVxdWVzdF9vYmplY3Rfc2lnbmluZ19hbGdfdmFsdWVzX3N1cHBvcnRlZCI6WyJFUzI1NiJdLCJwcmVzZW50YXRpb25fZGVmaW5pdGlvbl91cmlfc3VwcG9ydGVkIjpmYWxzZSwiaWF0IjoxNjg3MjgxMTk1LCJleHAiOjE2ODcyODgzOTV9.tNvCyFPCL5tUi2NakKwdaG9xbrtWWl4djSRYRfHrF8NdmffdT044U55pRn35J2cl0LZxbesEDrfSAz2pllw2Ug - eyJhbGciOiJFUzI1NiIsInR5cCI6IndhbGxldC1hdHRlc3RhdGlvbitqd3QiLCJraWQiOiI1dDVZWXBCaE4tRWdJRUVJNWlVenI2cjBNUjAyTG5WUTBPbWVrbU5LY2pZIiwidHJ1c3RfY2hhaW4iOlsiZXlKaGJHY2lPaUpGVXouLi42UzBBIiwiZXlKaGJHY2lPaUpGVXouLi5qSkxBIiwiZXlKaGJHY2lPaUpGVXouLi5IOWd3Il19.eyJpc3MiOiJodHRwczovL3dhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZyIsInN1YiI6InZiZVhKa3NNNDV4cGh0QU5uQ2lHNm1DeXVVNGpmR056b3BHdUt2b2dnOWMiLCJ0eXBlIjoiV2FsbGV0SW5zdGFuY2VBdHRlc3RhdGlvbiIsInBvbGljeV91cmkiOiJodHRwczovL3dhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZy9wcml2YWN5X3BvbGljeSIsInRvc191cmkiOiJodHRwczovL3dhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZy9pbmZvX3BvbGljeSIsImxvZ29fdXJpIjoiaHR0cHM6Ly93YWxsZXQtcHJvdmlkZXIuZXhhbXBsZS5vcmcvbG9nby5zdmciLCJhdHRlc3RlZF9zZWN1cml0eV9jb250ZXh0IjoiaHR0cHM6Ly93YWxsZXQtcHJvdmlkZXIuZXhhbXBsZS5vcmcvTG9BL2Jhc2ljIiwiY25mIjp7Imp3ayI6eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6IjRITnB0SS14cjJwanlSSktHTW56NFdtZG5RRF91SlNxNFI5NU5qOThiNDQiLCJ5IjoiTElablNCMzl2RkpoWWdTM2s3alhFNHIzLUNvR0ZRd1p0UEJJUnFwTmxyZyIsImtpZCI6InZiZVhKa3NNNDV4cGh0QU5uQ2lHNm1DeXVVNGpmR056b3BHdUt2b2dnOWMifX0sImF1dGhvcml6YXRpb25fZW5kcG9pbnQiOiJldWRpdzoiLCJyZXNwb25zZV90eXBlc19zdXBwb3J0ZWQiOlsidnBfdG9rZW4iXSwidnBfZm9ybWF0c19zdXBwb3J0ZWQiOnsiand0X3ZwX2pzb24iOnsiYWxnX3ZhbHVlc19zdXBwb3J0ZWQiOlsiRVMyNTYiXX0sImp3dF92Y19qc29uIjp7ImFsZ192YWx1ZXNfc3VwcG9ydGVkIjpbIkVTMjU2Il19fSwicmVxdWVzdF9vYmplY3Rfc2lnbmluZ19hbGdfdmFsdWVzX3N1cHBvcnRlZCI6WyJFUzI1NiJdLCJwcmVzZW50YXRpb25fZGVmaW5pdGlvbl91cmlfc3VwcG9ydGVkIjpmYWxzZSwiaWF0IjoxNjg3MjgxMTk1LCJleHAiOjE2ODcyODgzOTV9.tNvCyFPCL5tUi2NakKwdaG9xbrtWWl4djSRYRfHrF8NdmffdT044U55pRn35J2cl0LZxbesEDrfSAz2pllw2Ug .. _token endpoint: wallet-solution.html#wallet-instance-attestation .. _Wallet Instance Attestation Request: wallet-instance-attestation.html#format-of-the-wallet-instance-attestation-request diff --git a/docs/en/wallet-solution.rst b/docs/en/wallet-solution.rst index e6f895ed2..2b86525ad 100644 --- a/docs/en/wallet-solution.rst +++ b/docs/en/wallet-solution.rst @@ -9,84 +9,87 @@ The Wallet Solution is a comprehensive product offered by the Wallet Provider to The Wallet Solution is issued by the Wallet Provider in the form of a mobile app, it also consists of services and web interfaces for the exchange of data between the Wallet Provider and its Wallet Instances for the requirements of the trust model and in total respect of the user's privacy, in accordance with national and EU legislation. -The mobile app serves as the primary interface for Users, allowing them to access and interact with their digital assets conveniently. These digital assets, known as Attestations, include Personal Identification Data (PID¹), a set of data that can uniquely identify a natural or a legal person, along with other Qualified and non-qualified Electronic Attestations of Attributes, also known as QEAAs and EAAs respectively, or (Q)EAAs for short¹. Once a User installs the mobile app on their device, we refer to such an installation as a Wallet Instance for the User. +The mobile app serves as the primary interface for Users, allowing them to access and interact with their digital assets conveniently. These digital assets, known as Attestations, include Personal Identification Data (PID¹), a set of data that can uniquely identify a natural or a legal person, along with other Qualified and non-qualified Electronic Attestations of Attributes, also known as QEAAs and EAAs respectively, or (Q)EAAs for short¹. Once a User installs the mobile app on their device, it is referred to such an installation as a Wallet Instance for the User. -Supporting the mobile app, the Wallet Provider plays a vital role in ensuring the security and reliability of the Wallet Solution. The Wallet Provider is responsible for issuing the Wallet Instance Attestation — a cryptographic proof that verifies the authenticity and integrity of the Wallet Instance. +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 Instance Attestation, that is a cryptographic proof that allow the evaluation of the authenticity and the integrity of the Wallet Instance. Requirements ^^^^^^^^^^^^^^^^^^^^ - - **Trustworthiness within the Wallet ecosystem**: the Wallet Instance must establish trust and reliability within the Wallet ecosystem. - - **Compliance with Provider specifications for obtaining PID and (Q)EAA**: the Wallet Instance must adhere to the specifications set by Providers for obtaining Personal Identification (PID) and Qualified or non-qualified Electronic Address Authentication (Q)EAA. - - **Support for Android and iOS operating systems**: the Wallet Instance must be compatible and functional at least on both Android and iOS operating systems, as well as available on the Play Store and App Store respectively. - - **Verification of device ownership by the User**: the Wallet Instance must provide a mechanism to verify the User's actual possession of the device and its control. + - **Trustworthiness within the Wallet ecosystem**: the Wallet Instance MUST establish trust and reliability within the Wallet ecosystem. + - **Compliance with Provider specifications for obtaining PID and (Q)EAA**: the Wallet Instance MUST adhere to the specifications set by Providers for obtaining Personal Identification (PID) and (Q)EAAs. + - **Support for Android and iOS operating systems**: the Wallet Instance MUST be compatible and functional at least on both Android and iOS operating systems, as well as available on the Play Store and App Store respectively. + - **Verification of device ownership by the User**: the Wallet Instance MUST provide a mechanism to verify the User's actual possession and full control of their personal device. Wallet Instance ^^^^^^^^^^^^^^^^^^^^ -The Wallet Instance serves as a unique and secure representation of the User within the Wallet ecosystem. It establishes a strong and reliable identity for the User, enabling them to engage in various digital transactions in a secure and privacy-preserving manner. +The Wallet Instance 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 establishes the trust within the Wallet ecosystem by consistently presenting a Wallet Instance Attestation during interactions with other ecosystem actors such as PID Providers, (Q)EAA Providers, and Relying Parties. These attestations, provided by the underlying Wallet Provider operated by the Wallet Provider, reference a pair of asymmetric cryptographic keys exclusively owned by the Wallet Instance. Their purpose is to authenticate the Wallet Instance itself, ensuring its legitimacy when engaging with other ecosystem actors. +The Wallet Instance establishes the trust within the Wallet ecosystem by consistently presenting a Wallet Instance Attestation during interactions with other ecosystem actors such as PID Providers, (Q)EAA Providers, and Relying Parties. These 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. -To guarantee the utmost security, these cryptographic keys are securely stored within the device's Trusted Execution Environment (TEE)³. This ensures that only the User can access them, thus preventing unauthorized usage or tampering. For more detailed information, please refer to the `Wallet Instance Attestation section`_ and the `Trust Model section`_ of this document. +To guarantee the utmost security, these cryptographic keys are securely stored within the device's Trusted Execution Environment (TEE)³. This ensures that only the User is allowed to access them, thus preventing unauthorized usage or tampering. For more detailed information, please refer to the `Wallet Instance Attestation section`_ and the `Trust Model section`_ of this document. Wallet Instance Lifecycle ^^^^^^^^^^^^^^^^^^^^^^^^^^ -The Wallet Instance can exist in three distinct states: Operational, Valid, and Deactivated. Each state represents a specific functional status and determines the actions that can be performed². +The Wallet Instance has three distinct states: Operational, Valid, and Deactivated. Each state represents a specific functional status and determines the actions that can be performed². Initialization Process ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To activate the Wallet Instance, Users must install the mobile 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 is in the Operational state. +After completing these steps, the Wallet Instance sets the Operational state. 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 active, enabling secure transaction execution. +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 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. Once the Wallet Instance is in the Operational state, Users can: - - Obtain, view, and manage (Q)EAAs from trusted (Q)EAA Providers¹ - - Authenticate to Relying Parties¹ - - Authorize the sharing of their data with Relying Parties + - Obtain, view, and manage (Q)EAAs from trusted (Q)EAA Providers¹; + - Authenticate to 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 attestation presentation. +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 revocation of the associated PID by the relevant PID Provider. +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. + Deactivation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Users have the ability to deactivate the Wallet Instance voluntarily. This action removes the operational capabilities of the Wallet Instance and sets it to the deactivated state. Deactivation provides Users with control over access and usage according to their preferences. +Users have the ability to deactivate the Wallet Instance voluntarily. This action removes the operational capabilities of the Wallet Instance and sets it to the Deactivated state. Deactivation provides Users with control over access and usage according to their preferences. Wallet Provider Endpoints ^^^^^^^^^^^^^^^^^^^^^^^^^ -The Wallet Provider that issues the Wallet Instance Attestations must -make available a series of APIs in REST format that follow the OpenID -Federation standard. +The Wallet Provider that issues the Wallet Instance Attestations MUST +made available its APIs in the form of RESTful services, as listed below. Wallet Provider Metadata ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A **GET /.well-known/openid-federation endpoint** for retrieving the Wallet +An HTTP GET request to the **/.well-known/openid-federation** endpoint allows the retrieval of the Wallet Provider Entity Configuration. The Wallet Provider Entity Configuration is a JWS containing the public keys and supported algorithms of the Wallet Provider metadata definition. It is structured in accordance with the `OpenID Connect Federation `_ and the Trust Model section outlined in this specification. +The returning Entity Configuration of the Wallet Provider MUST contain the +attributes listed below: + Header ^^^^^^ +---------+-----------------------------------------------------------------+ | **Key** | **Value** | +---------+-----------------------------------------------------------------+ -| alg | Algorithm employed to verify the token signature (e.g., ES256). | +| alg | Algorithm used to verify the token signature (e.g., ES256). | +---------+-----------------------------------------------------------------+ | kid | Thumbprint of the public key used for signing. | +---------+-----------------------------------------------------------------+ -| typ | Media type, here we use the entity-statement+jwt value. | +| typ | Media type, set to ``entity-statement+jwt``. | +---------+-----------------------------------------------------------------+ Payload @@ -106,8 +109,8 @@ Payload | exp | Expiration datetime | | | in Unix Timestamp format. | +-----------------------------------+-----------------------------------+ -| authority_hints | Array of URLs (String). It | -| | contains a list of URLs of the | +| authority_hints | Array of URLs (String) containing | +| | the list of URLs of the | | | immediate superior Entities, such | | | as the Trust Anchor or an | | | Intermediate, that MAY issue an | @@ -122,17 +125,15 @@ Payload | | at issue. Each JWK in the JWK set | | | MUST have a key ID (claim kid). | +-----------------------------------+-----------------------------------+ -| metadata | For each entity, this attribute | -| | houses its metadata. In this case,| -| | it contains the Wallet Provider's | -| | metadata within the | -| | ``wallet_provider`` attribute | -| | and the generic entity | -| | ``federation_entity``. | +| metadata | Contains the | +| | metadata | +| | ``wallet_provider`` | +| | and the | +| | ``federation_entity`` metadata. | +-----------------------------------+-----------------------------------+ -Payload `wallet_provider` -~~~~~~~~~~~~~~~~~~~~~~~~~ +`wallet_provider` metadata +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------------------+---------------------------------------------------------------------+ | **Key** | **Value** | @@ -145,30 +146,28 @@ Payload `wallet_provider` | | Instance Attestation. | +---------------------------------------------+---------------------------------------------------------------------+ | attested_security_context_values_supported | List of supported values for the | -| | certified security context. These | +| | certifiable security context. These | | | values specify the security level | -| | of the app—low, medium, or high. | +| | of the app, according to the levels: low, medium, or high. | | | An attested security context is | | | defined by the proof that the | -| | Wallet Instance can send to the | -| | Wallet Provider. Note: this | -| | parameter is defined in this | -| | specification | +| | Wallet Instance can provide to the | +| | Wallet Provider. | +---------------------------------------------+---------------------------------------------------------------------+ | grant_types_supported | The types of grants supported by | -| | the endpoint token. It MUST be set to | +| | the token endpoint. It MUST be set to | | | ``urn:ietf:params:oauth:client-assertion-type: | -| | jwt-client-attestation`` | +| | jwt-client-attestation``. | +---------------------------------------------+---------------------------------------------------------------------+ -| token_endpoint_auth_methods_suppor | Supported authentication method for | -| ted | the endpoint token. | +| token_endpoint_auth_methods_suppor | Supported authentication methods for | +| ted | the token endpoint. | +---------------------------------------------+---------------------------------------------------------------------+ -| token_endpoint_auth_signing_alg_va | List of supported signature | -| lues_supported | algorithms. | +| token_endpoint_auth_signing_alg_va | Supported signature | +| lues_supported | algorithms for the token endpoint | +---------------------------------------------+---------------------------------------------------------------------+ .. note:: - The `asc_values_supported` parameter is experimental and under review. + The `attested_security_context_values_supported` parameter is experimental and under review. Payload `federation_entity` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -261,7 +260,7 @@ Below a non-normative example of the Entity Configuration. Wallet Instance Attestation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Please refer to the `Wallet Instance Attestation section`_ +Please refer to the `Wallet Instance Attestation section`_. External references diff --git a/docs/it/conf.py b/docs/it/conf.py index ea29d0c3c..dd23e066e 100644 --- a/docs/it/conf.py +++ b/docs/it/conf.py @@ -2,7 +2,7 @@ # -*- coding: utf-8 -*- # -- PROJECT Variables ---------------------------------------------------- -settings_project_name = "Italian eIDAS Wallet Technical Specifications" +settings_project_name = "The Italian EUDI Wallet implementation profile" settings_copyright_copyleft = 'Dipartimento per la Trasformazione Digitale' settings_editor_name = 'Dipartimento per la Trasformazione Digitale' settings_doc_version = 'version: latest' diff --git a/docs/it/index.rst b/docs/it/index.rst index feaabacb3..abe2399cd 100644 --- a/docs/it/index.rst +++ b/docs/it/index.rst @@ -1,8 +1,8 @@ .. include:: ../common/common_definitions.rst -============================================= -Italian eIDAS Wallet Technical Specifications -============================================= +============================================== +The Italian EUDI Wallet implementation profile +============================================== [TODO INTRO] diff --git a/images/High-Level-Flow-ITWallet-QEAA-Issuance.svg b/images/High-Level-Flow-ITWallet-QEAA-Issuance.svg index add0821b9..7a55b4792 100644 --- a/images/High-Level-Flow-ITWallet-QEAA-Issuance.svg +++ b/images/High-Level-Flow-ITWallet-QEAA-Issuance.svg @@ -1,3 +1,3 @@ -
(Q)EAA Issuer
(Q)EAA Issuer
Wallet Solution
Wallet Solution
Wallet Instance
Wallet Instance
VCI Component (OIDC4VCI)
VCI Component (OIDC4VCI...
Issues (Q)EAA
Issues (Q)EAA
Requests (Q)EAA
Requests (Q)EAA
Federation API Services
Federation API Services
Trust Anchor - Accreditation Body
Trust Anchor - Accreditation Body
Federation API Services
Federation API Services
Requests for Issuer identifier
Requests for Issuer identifier
1
1
2
2
Register
Register
User Authentication with PID
User Authentication with PID
Requests for Issuer Metadata
Requests for Issuer Metadata
RP Component (OIDC4VP)
RP Component (OIDC4VP)
5
5
3
3
4
4Viewer does not support full SVG 1.1 \ No newline at end of file +
(Q)EAA Provider
(Q)EAA Provider
Wallet Solution
Wallet Solution
Wallet Instance
Wallet Instance
VCI Component (OpenID4VCI)
VCI Component (OpenID4V...
Issues (Q)EAA
Issues (Q)EAA
Requests (Q)EAA
Requests (Q)EAA
Federation API Services
Federation API Services
Trust Anchor - Accreditation Body
Trust Anchor - Accreditation Body
Federation API Services
Federation API Services
Requests for Issuer identifier
Requests for Issuer identifier
1
1
2
2
Register
Register
User Authentication with PID
User Authentication with PID
Requests for Issuer Metadata
Requests for Issuer Metadata
RP Component (OpenID4VP)
RP Component (OpenID4VP...
5
5
3
3
4
4Text is not SVG - cannot display \ No newline at end of file diff --git a/images/Low-Level-Flow-ITWallet-PID-QEAA-Issuance.svg b/images/Low-Level-Flow-ITWallet-PID-QEAA-Issuance.svg index 243d8e23f..40c8d8c77 100644 --- a/images/Low-Level-Flow-ITWallet-PID-QEAA-Issuance.svg +++ b/images/Low-Level-Flow-ITWallet-PID-QEAA-Issuance.svg @@ -1 +1 @@ -User's smartphoneUserUserBrowserBrowserWallet InstanceWallet InstanceWallet ProviderWallet ProviderPID/(Q)EAA IssuerPID/(Q)EAA Issuer1obtain your PID/(Q)EAA2yesobtain a list of Trusted PID/(Q)EAA Issuer3confirm the selection of PID/(Q)EAA Issuer4okWallet Instance checks that the PID/(Q)EAA Issuer is part of the Federation and obtains its metadata5create PKCE code verifier6PAR Request (response_type, client_id, code_challenge, code_challenge_method, request, client_assertion_type, client_assertion=$WalletInstanceAttestation$)PID/(Q)EAA Issuer checks that the Wallet Provider is part of the FederationPID/(Q)EAA Issuer checks that the signature of the Wallet Attestation and its validity7PAR Response (request_uri, expires_in)8Authorization Request (client_id, request_uri)9Authorization Request (client_id, request_uri)alt[(Q)EAA issuance]User authentication with PID and consent[PID issuance]User authentication with eIDAS LoA High and consent10Authorization Response (code, state)11Authorization Response (code, state)12generate DPoP key13generate DPoP proof for PID/(Q)EAA Issuer token endpoint14Token Request with DPoP proof (client_id, grant_type, code, code_verifier, client_assertion_type, client_assertion, redirect_uri)15Token Response (access_token, token_type, expires_in, c_nonce, c_nonce_expires_in)16generate fresh key for credential17create proof of possession (c_nonce)18create DPoP proof for PID/(Q)EAA Issuer credential endpoint19Credential Request with DPoP access_token and DPoP proof (credential_definition, format, proof)Register all the credential-relatedinformation for verification/revocation20Credential Response (format, credential, c_nonce, c_nonce_expires_in)21PID/(Q)EAA validity and status check22store credential \ No newline at end of file +User's smartphoneUserUserBrowserBrowserWallet InstanceWallet InstanceWallet ProviderWallet ProviderPID/(Q)EAA ProviderPID/(Q)EAA Provider1obtain your PID/(Q)EAA2yesobtain a list of Trusted PID/(Q)EAA Provider3confirm the selection of PID/(Q)EAA Provider4okWallet Instance checks that the PID/(Q)EAA Issuer is part of the Federation and obtains its Metadata5create PKCE code verifier6PAR Request (response_type, client_id, code_challenge, code_challenge_method, request, client_assertion_type, client_assertion=$WalletInstanceAttestation$)PID/(Q)EAA Provider checks that the Wallet Provider is part of the FederationPID/(Q)EAA Provider checks that the signature of the Wallet Instance Attestation and its validity7PAR Response (request_uri, expires_in)8Authorization Request (client_id, request_uri)9Authorization Request (client_id, request_uri)alt[(Q)EAA issuance]User authentication with PID and consent[PID issuance]User authentication with eIDAS LoA High and consent10Authorization Response (code, state, iss)11Authorization Response (code, state, iss)12generate DPoP key13generate DPoP proof for PID/(Q)EAA Issuer token endpoint14Token Request with DPoP proof (client_id, grant_type, code, code_verifier, client_assertion_type, client_assertion, redirect_uri)15Token Response (access_token, token_type, expires_in, c_nonce, c_nonce_expires_in)16create proof of possession (c_nonce)17create DPoP proof for PID/(Q)EAA Issuer credential endpoint18Credential Request with DPoP access_token and DPoP proof (credential_definition, format, proof)Register all the credential-relatedinformation for verification/revocation19Credential Response (format, credential, c_nonce, c_nonce_expires_in)20PID/(Q)EAA validity and status check21store credential \ No newline at end of file