From a83cf2a4ef192329c0fe2c66fe0d18974365955e Mon Sep 17 00:00:00 2001 From: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> Date: Mon, 4 Mar 2024 11:01:21 +0100 Subject: [PATCH 1/6] [Issuance flow]: added error management (#225) * chore: added error management in the issuance flow * Update docs/en/pid-eaa-issuance.rst Co-authored-by: Giuseppe De Marco * Update docs/en/pid-eaa-issuance.rst Co-authored-by: Giuseppe De Marco --------- Co-authored-by: Giuseppe De Marco --- docs/en/pid-eaa-issuance.rst | 111 ++++++++++++++++++++++++++--------- 1 file changed, 83 insertions(+), 28 deletions(-) diff --git a/docs/en/pid-eaa-issuance.rst b/docs/en/pid-eaa-issuance.rst index 9dab80d4b..d75af32fa 100644 --- a/docs/en/pid-eaa-issuance.rst +++ b/docs/en/pid-eaa-issuance.rst @@ -13,7 +13,7 @@ The relevant entities and interfaces involved in the issuance flow are: - *Wallet Instance*: Instance of a Wallet Solution, installed on the User device. The Wallet Instance provides graphical interfaces for User interaction with Relying Parties, PID, (Q)EAA Providers and the Wallet Provider. - *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 the PID. + - OpenID4VCI Component: based on the "OpenID for Verifiable Credential Issuance" specification ` [OIDC4VCI. Draft 13] `_ to release the PID. - National eID Relying Party: The component to authenticate the User with the national Digital Identity Providers, based on OpenID Connect Core 1.0 or SAML2. - National Identity Provider: It represents preexisting identity systems based on SAML2 or OpenID Connect Core 1.0, already in production in each Member State (eg: the Italian SPID and CIE id schemes notified eIDAS with *LoA* **High**, see `SPID/CIE OpenID Connect Specifications `_). @@ -39,7 +39,7 @@ Below the description of the steps represented in the previous picture: 0. **Wallet Instance Setup**: the first time the Wallet Instance is started a preliminary setup phase is carried out. It consists of the release of the Wallet Attestation issued by Wallet Attestation Service asserting the genuineness and the compliance of the Wallet Instance with the shared trust framework. The Wallet Attestation binds the public key provided by the Wallet Instance, related to one of the private keys generated by the Wallet Instance. 1. **PID/(Q)EAA Provider Discovery**: the Wallet Instance discovers the trusted Digital Credential Issuers using the Federation API (e.g.: using the Subordinate Listing Endpoint of the Trust Anchor and its Intermediates), inspecting the Credential Issuer metadata and Trust Marks for filtering the PID Provider. 2. **PID Provider Metadata**: the Wallet Instance establishes the trust to the PID Provider according to the Trust Model and obtains the Metadata that discloses the formats of the PID, the algorithms supported, and any other parameter required for interoperability needs. - 3. **PID Request**: using the Authorization Code Flow defined in `[OIDC4VCI. Draft 13] `_ the Wallet Instance requests the PID to the PID Provider. + 3. **PID Request**: using the Authorization Code Flow defined in `[OIDC4VCI. Draft 13] `_ the Wallet Instance requests the PID to the PID Provider. 4. **User Authentication**: the PID Provider authenticates the User with LoA High, acting as an Identity and Access Management Proxy to the National eID system. 5. **PID Issuance**: the User is authenticated with LoA High and the PID Provider releases a PID bound to the key material held by the requesting Wallet Instance. @@ -64,7 +64,7 @@ Below the description of the most relevant operations involved in the (Q)EAA iss 1. **Discovery of the trusted (Q)EAA Provider**: the Wallet Instance obtains the list of the trusted (Q)EAA Provider using the Federation API (e.g.: using the Subordinate Listing Endpoint of the Trust Anchor and its Intermediates), then inspects the metadata and Trust Mark looking for the Digital Credential capabilities of each (Q)EAA Provider. 2. **(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**: using the Authorization Code Flow , defined in `[OIDC4VCI. Draft 13] `_, the Wallet Instance requests a (Q)EAA to the (Q)EAA Provider. + 3. **(Q)EAA Request**: using the Authorization Code Flow , defined in `[OIDC4VCI. Draft 13] `_, the Wallet Instance requests a (Q)EAA to the (Q)EAA 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**: the User is authenticated with a valid PID and the (Q)EAA Provider releases a (Q)EAA bound to the key material held by the requesting Wallet Instance. @@ -75,7 +75,7 @@ Detailed Flow The PID/(Q)EAA Issuance phase uses the **Authorization Code Flow** with the following specifications: * **Pushed Authorization Requests** (PAR) [:rfc:`9126`]; -* **PKCE** (Proof Key for Code Exchange, :rfc:`7636`) as recommended in `[OIDC4VCI. Draft 13. Section 3.4] `_. +* **PKCE** (Proof Key for Code Exchange, :rfc:`7636`) as recommended in `[OIDC4VCI. Draft 13. Section 3.4] `_. In this section a *Wallet Initiated Flow* is outlined, where the User receives the PID/(Q)EAA directly in response to the Credential Request. @@ -116,7 +116,7 @@ The PID/(Q)EAA Provider performs the following checks upon the receipt of the PA 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 PID/(Q)EAA Provider authorization endpoint uri (: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 which values are validated according to :ref:`Table of the HTTP parameters ` [derived from :rfc:`9126`]. + 7. It MUST check that the Request Object contains all the mandatory parameters which values are validated according to :ref:`Table of the HTTP parameters ` [derived from :rfc:`9126`]. 8. It MUST check that the Request Object is not expired, checking the ``exp`` claim (:rfc:`9126`). 9. It MUST check that the Request Object was issued in a previous time than the value exposed in the ``iat`` claim. It SHOULD reject the request if the ``iat`` claim is far from the current time (:rfc:`9126`) of more than `5` minutes. 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`). @@ -439,8 +439,9 @@ The requests to the PID/(Q)EAA authorization endpoint MUST use the HTTP POST met - It MUST be set to a value containing the Wallet Attestation JWT and the Proof of Possession, separated with the ``~`` character. - `oauth-attestation-draft `_. -The JWT Request Object has the following JOSE header parameters: +The JWT *Request Object* has the following JOSE header parameters: +.. _table_request_object_claim: .. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -501,7 +502,7 @@ The JWT payload is given by the following parameters: - **type**: it MUST be set to ``openid_credential``, - **credential_configuration_id**: JSON String. String specifying a unique identifier of the Credential being described in the `credential_configurations_supported` map in the Credential Issuer Metadata. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData``. - - See [RAR :rfc:`9396`] and `[OIDC4VCI. Draft 13] `_. + - See [RAR :rfc:`9396`] and `[OIDC4VCI. Draft 13] `_. * - **redirect_uri** - 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 `_. @@ -582,6 +583,25 @@ If the verification is successful, the PID/(Q)EAA Issuer MUST provide the respon - A JSON number that represents the lifetime of the request URI in seconds as a positive integer. - [:rfc:`9126`]. +If any errors occur during the PAR Request, the Authorization Server MUST return an error response as defined in :rfc:`9126#section-2.3`. The response MUST use *application/json* as the content type and MUST include the following parameters: + + - *error*. The error code. + - *error_description*. Text in human-readable form providing further details to clarify the nature of the error encountered. + +Below is a non-normative example of an error response. + +.. code:: + + HTTP/1.1 400 Bad Request + Content-Type: application/json + + { + "error": "invalid_request", + "error_description": + "The redirect_uri is not valid for the given client" + } + + Authorization endpoint ---------------------- @@ -636,6 +656,10 @@ If the authentication is successful the PID/(Q)EAA Issuer redirects the User by - Unique identifier of the PID/(Q)EAA Issuer who created the Authentication Response. The Wallet Instance MUST validate this parameter. - `OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response `_, `[RFC7519, Section 4.1.1] `_. +If any errors occur during the Authorization Request, the Authorization Server MUST return an error response as defined in :rfc:`6749#section-4.1.2.1`. The response MUST use *application/json* as the content type and MUST include the following parameters: + + - *error*. The error code. + - *error_description*. Text in human-readable form providing further details to clarify the nature of the error encountered. Token endpoint -------------- @@ -728,7 +752,7 @@ The payload of a **DPoP JWT Proof** MUST contain at least the following claims: Token Response ^^^^^^^^^^^^^^^ -Token endpoint response MUST contain the following mandatory claims. +If the Token Request is successfully validated, the Authorization Server provides an HTTP Token Response with a *200 (OK)* status code. The Token Response MUST contain the following mandatory claims. .. list-table:: :widths: 20 60 20 @@ -748,13 +772,27 @@ Token endpoint response MUST contain the following mandatory claims. - :rfc:`6749`. * - **c_nonce** - 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] `_. + - `[OIDC4VCI. Draft 13] `_. * - **c_nonce_expires_in** - JSON integer, it represents the lifetime in seconds of the **c_nonce**. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. * - **authorization_details** - JSON object, used to identify Credentials with the same metadata but different claimset/claim values and/or simplify the Credential request even when only one Credential is being issued. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. + +If any errors occur during the validation of the Token Request, the Authorization Server MUST return an error response as defined in :rfc:`6749#section-5.2`. + +.. code:: + + HTTP/1.1 400 Bad Request + Content-Type: application/json;charset=UTF-8 + Cache-Control: no-store + Pragma: no-cache + + { + "error":"invalid_client" + "error_description":"Client authentication failed" + } Access Token @@ -822,20 +860,20 @@ If the *DPoP proof* is invalid, the Credential endpoint returns an error respons - **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. In the case of the PID it MUST be set to ``PersonIdentificationData``. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. * - **format** - Format of the Credential to be issued. This MUST be `vc+sd-jwt`. - - `[OIDC4VCI. Draft 13] `_. + - `[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: - **proof_type**: JSON string denoting the proof type. It MUST be `jwt`. - **jwt**: the JWT used as proof of possession. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. .. note:: - If the **format** value is `mso_mdoc`, the credential request MUST contain the ``doctype`` claim which is a JSON string identifying the credential type according to `EIDAS-ARF`_ . See Appendix E.2. of `[OIDC4VCI. Draft 13] `_ for more details. + If the **format** value is `mso_mdoc`, the credential request MUST contain the ``doctype`` claim which is a JSON string identifying the credential type according to `EIDAS-ARF`_ . See Appendix E.2. of `[OIDC4VCI. Draft 13] `_ for more details. The JWT proof type MUST contain the following parameters for the JOSE header and the JWT body: @@ -849,13 +887,13 @@ The JWT proof type MUST contain the following parameters for the JOSE header and - **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 set to ``none`` or to a symmetric algorithm (MAC) identifier. - - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. + - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. * - **typ** - It MUST be set to `openid4vci-proof+jwt`. - - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. + - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. * - **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`]. + - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. .. list-table:: :widths: 20 60 20 @@ -866,22 +904,22 @@ The JWT proof type MUST contain the following parameters for the JOSE header and - **Reference** * - **iss** - The value of this claim MUST be the **client_id** of the Wallet Instance. - - `[OIDC4VCI. Draft 13] `_, `[RFC7519, Section 4.1.1] `_. + - `[OIDC4VCI. Draft 13] `_, `[RFC7519, Section 4.1.1] `_. * - **aud** - The value of this claim MUST be the identifier URL of the PID/(Q)EAA Issuer. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. * - **iat** - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. - - `[OIDC4VCI. Draft 13] `_, [:rfc:`7519`. Section 4.1.6]. + - `[OIDC4VCI. Draft 13] `_, [:rfc:`7519`. Section 4.1.6]. * - **nonce** - The value type of this claim MUST be a string, where the value is a **c_nonce** provided by the PID/(Q)EAA Issuer in the Token response. - - `[OIDC4VCI. Draft 13] `_. + - `[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: +Credential Response to the Wallet Instance MUST be sent using `application/json` media type. If the Credential Request is successfully validated, the PID/(Q)EAA Provider MUST return HTTP response with a *200 (OK)* status code and MUST contain the following mandatory claims: .. _table_credential_response_claim: .. list-table:: Credential http response parameters @@ -893,20 +931,37 @@ Credential Response to the Wallet Instance MUST be sent using `application/json` - **Reference** * - **format** - 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] `_. + - `[OIDC4VCI. Draft 13] `_. * - **credential** - 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] `_. + - Appendix E in `[OIDC4VCI. Draft 13] `_. * - **c_nonce** - 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] `_. + - `[OIDC4VCI. Draft 13] `_. * - **c_nonce_expires_in** - JSON integer corresponding to the **c_nonce** lifetime in seconds. - - `[OIDC4VCI. Draft 13] `_. + - `[OIDC4VCI. Draft 13] `_. .. note:: - If the **format** value is `mso_mdoc`, the **credential** value MUST be a base64url-encoded JSON string according to Appendix E of `[OIDC4VCI. Draft 13] `_. + If the **format** value is `mso_mdoc`, the **credential** value MUST be a base64url-encoded JSON string according to Appendix E of `[OIDC4VCI. Draft 13] `_. + + +If the Credential Request is invalid, the PID/(Q)EAA Provider MUST return an error response as defined in `[OIDC4VCI. Draft 13] `. The response MUST use the content type *application/json* and MUST include the following parameters: + + - *error*. The error code. + - *error_description*. Text in human-readable form providing further details to clarify the nature of the error encountered. + +.. code:: + + HTTP/1.1 400 Bad Request + Content-Type: application/json + Cache-Control: no-store + + { + "error": "invalid_proof" + "error_description":"The proof field is not present or the provided key proof is invalid or not bound to a nonce provided by the Credential Issuer." + } .. _Entity Configuration Credential Issuer: From 117bfb35182cf07fc57581d21347d8b1df755f3f Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 4 Mar 2024 13:24:09 +0100 Subject: [PATCH 2/6] Trust infrastructure functional requirements and general properties (#227) * fix!: alignments according to breaking changes introduced by openid4vci I-D * trust infrastructure requirements and properties * fix: trust.rst linting --- docs/en/index.rst | 10 ++------ docs/en/trust.rst | 58 +++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 50 insertions(+), 18 deletions(-) diff --git a/docs/en/index.rst b/docs/en/index.rst index a25387a11..9eed31a14 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -7,15 +7,9 @@ The Italian EUDI Wallet implementation profile Introduction ------------ -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 `_. +The European Parliament `has adopted `_ the revision of the eIDAS Regulation concerning electronic identification and trust services, introducing a significant innovation: the `European Digital Identity Wallet `_. This update marks a pivotal advancement in the EU's digital strategy, aiming to enhance the security, interoperability, and usability of digital identities across Member States. For further details, resources, and notes on this legislative development, please refer to the official EU Commission and Parliament websites. -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. 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. +Italy has launched the National digital identity Wallet solution, known as IT Wallet, in direct response to the European community's directives. This initiative ensures full interoperability with the digital identity solutions provided by other European Member States, aligning completely with European regulations. 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. diff --git a/docs/en/trust.rst b/docs/en/trust.rst index f8d3f4fd9..6643f7b55 100644 --- a/docs/en/trust.rst +++ b/docs/en/trust.rst @@ -19,6 +19,42 @@ The Infrastructure of trust facilitates the application of a trust assessment me which include one or more Intermediates and Leaves. In this representation, both the Trust Anchor and the Intermediates MAY assume the role of Accreditation Body. +Functional Requirements +----------------------- + +This section includes the requirements necessary for the successful implementation and operation of the infrastructure of trust. + +[FR #1] - **Federation Trust Establishment**: the system must be able to establish trust between different entities (Credential Issuers, Relying Parties, etc.) within a federation, using cryptographic signatures for secure information exchange about the participants in the ecosystem. +[FR #2] - **Entity Authentication**: the system must implement mechanisms for authenticating entities within the federation, ensuring compliance with the shared rules. +[FR #3] - **Signature Validation**: the system must support the creation, verification, and validation of electronic signatures and provide standard and secure mechanisms to obtain the public keys required for the signature validation. +[FR #4] - **Time Stamping**: the signed artifacts must contain time stamps to ensure the integrity and non-repudiation of transactions over time, thanks to the interfaces, services, storage model and approaches defined within the federation. +[FR #5] - **Certificate Validation**: the system requires confidential transmission, secured via TLS over HTTP, and validation of certificates for website authentication, ensuring they meet eIDAS criteria. +[FR #6] - **Interoperability and Standards Compliance**: ensure interoperability between federation members by adhering to technical standards, facilitating cross-border electronic transactions. +[FR #7] - **Data Protection and Privacy**: implement data protection measures in compliance with GDPR and eIDAS regulations, ensuring the privacy and security of personal data processed within the federation. +[FR #8] - **User Consent and Control**: design mechanisms for obtaining and managing user consent, empowering users with control over their personal information. +[FR #9] - **Audit and Logging**: the system must minimize data, anonymize if possible, define retention periods, secure access, and storage encryption. This protects privacy while enabling security and accountability. +[FR #10] - **Dispute Resolution and Liability**: establish clear procedures for dispute resolution and define liability among federation members, in accordance with eIDAS provisions. +[FR #11] - **Accessibility**: ensure that the system is accessible to all users, including those with disabilities, aligning with eIDAS and local accessibility standards. +[FR #12] - **Emergency and Revocation Services**: implement mechanisms for the immediate revocation of electronic identification means and participants in case of security breaches or other emergencies. +[FR #13] - **Scalable Trust Infrastructure**: the system must support scalable trust establishment mechanisms, leveraging approaches and technical solutions that complement delegation transitive approaches to efficiently manage trust relationships as the federation grows, removing central registries that might technically or administratively fail. +[FR #14] - **Efficient Storage Scalability**: implement a storage solution that scales horizontally to accommodate increasing data volumes while minimizing central storage and administrative costs. The system should enable members to independently store and present historical trust attestations and signed artifacts during dispute resolutions, with the federation infrastructure maintaining only a registry of historical keys to validate the historical data, stored and provided by the participants. +[FR #15] - **Verifiable Attestation (Trust Mark)**: incorporate a mechanism for issuing and verifying verifiable attestations that serve as proof of compliance with specific profiles or standards. This allows entities within the federation to demonstrate adherence to agreed-upon security, privacy, and operational standards. +[FR #16] - **Dynamic Policy Language**: develop and implement a dynamic, extensible policy language that allows for the creation and modification of federation policies in response to evolving requirements, technological advancements, and regulatory changes. This policy language should support the specification of rules governing entity behavior, metadata handling, and trust validation within the federation. +[FR #17] - **Automated Policy Enforcement**: the system must automatically enforce federation policies as defined by policy language and verifiable attestations, ensuring that all operations and transactions comply with current rules and standards. +[FR #18] - **Decentralized Dispute Resolution Mechanism**: design a decentralized mechanism for dispute resolution that allows federation members to independently verify historical trust establishment and signed artifacts, reducing reliance on central authorities and streamlining the resolution process. +[FR #19] - **Adaptive Load Management**: implement adaptive load management strategies to ensure the system remains responsive and efficient under varying loads, particularly during peak usage times or when processing complex tasks. +[FR #20] - **Cross-Federation Interoperability**: ensure the system is capable of interoperating with other federations or trust frameworks, facilitating cross-federation transactions and trust establishment without compromising security or compliance. +[FR #21] - **Future-Proof Cryptography**: the system should employ a flexible cryptographic framework that can be updated in response to new threats or advancements in cryptographic research, ensuring long-term security and integrity of federation operations. +[FR #23] - **Autonomous Accreditation Bodies**: the system must facilitate the integration of autonomous accreditation bodies that operate in compliance with federation rules. These bodies are tasked with evaluating and accrediting entities within the federation, according to the pre-established rules and their compliance that must be periodically asserted. +[FR #24] - **Compliance Evaluation for Federation Entity Candidates**: accreditation bodies must evaluate the compliance of candidate entities against federation standards before their registration in the federation. +[FR #25] - **Periodic Auditing of Accreditation Bodies and Entities**: implement mechanisms for the periodic auditing and monitoring of the compliance status of both accreditation bodies and their accredited entities. This ensures ongoing adherence to federation standards and policies. +[FR #26] - **Certification of Compliance for Personal Devices**: trusted bodies, in the form of federation entities, should issue certifications of compliance and provide signed proof of such compliance for the hardware of personal devices used within the federation. These certifications should be attested and periodically renewed to ensure the devices meet current security standards. +[FR #27] - **Certification of Compliance for Cryptographic Devices**: similar to personal devices, personal cryptographic devices used within the federation must also receive certifications of compliance and signed proof thereof from trusted bodies. These certifications should be subject to periodic renewal to reflect the latest security and compliance standards. +[FR #28] - **Transparent Compliance Reporting**: develop a system for transparent reporting and publication of compliance statuses, audit results, and certification renewals for all federation entities. This transparency fosters trust within the federation and with external stakeholders. +[FR #29] - **Automated Compliance Monitoring**: the system should include automated tools for monitoring the compliance of entities with federation standards. This automation aids in the early detection of potential compliance issues. +[FR #30] - **Secure Protocol Capabilities Binding**: the secure protocol must enable the exchange of protocol-specific capabilities data as cryptographically-bound metadata attached to a specific identity. This metadata should define the technical capabilities associated with the identity, ensuring verifiable proof and tamper-proof association for robust trust establishment and access control. + + Federation Roles ------------------ @@ -75,14 +111,17 @@ Below the table with the summary of the Federation Entity roles, mapped on the c General Properties ------------------ -OpenID Federation facilitates the building of an infrastructure that is: +The architecture of the trust infrastructure based on OpenID Federation is built upon several core principles: -- **Secure and Tamper-proof**, Entities' attestations of metadata and keys are cryptographically signed in the Trust Chain, comprised of attestations issued by multiple parties. These attestations, called statements, cannot be forged or tampered by an adversary; -- **Privacy-preserving**, the infrastructure is public and exposes public data such as public keys and metadata of the participants. It does not require authentication of the consumers and therefore does not track who is assessing trust against whom; -- **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 and multiple Trust Anchors where needed. +- [P1] **Security**: incorporates mechanisms to ensure the integrity, confidentiality, and authenticity of the trust relationships and interactions within the federation. +- [P2] **Privacy**: designed to respect and protect the privacy of the entities and individuals involved, minimal disclosure is part of this. +- [P3] **Interoperability**: supports seamless interaction and trust establishment between diverse systems and entities within the federation. +- [P4] **Transitive Trust**: trust established indirectly through a chain of trusted relationships, enabling entities to trust each other based on common authorities and trusted intermediaries. +- [P6] **Scalability**: designed to efficiently manage an increasing number of entities or interactions without a significant increase in trust management complexity. +- [P5] **Delegation**: technical ability/feature to delegate authority or responsibilities to other entities, allowing for a distributed trust mechanism. +- [P7] **Flexibility**: adaptable to various operational and organizational needs, allowing entities to define and adjust their trust relationships and policies. +- [P8] **Autonomy**: while part of a federated ecosystem, each entity retains control over its own definitions and configurations. +- [P9] **Decentralization**: unlike traditional centralized systems, the OpenID Federation model promotes a decentralized approach. This ensures that no single entity has control over the entire system, enhancing privacy and security for all participants. Trust Model Requirements ------------------------ @@ -165,7 +204,7 @@ All the endpoints listed below are defined in the `OIDC-FED`_ specs. | historical keys | **GET** | | Trust Anchor | | | |Lists the expired and revoked | | | | |keys, with the motivation of the| Intermediate | -| | .well-known/openid-federation-historical-jwks|revocation. | | +| | /historical-jwks |revocation. | | | | | | | +---------------------------+----------------------------------------------+--------------------------------+-----------------+ @@ -204,8 +243,7 @@ Below is a non-normative example of a Trust Anchor Entity Configuration, where e "kid": "X2ZOMHNGSDc4ZlBrcXhMT3MzRmRZOG9Jd3o2QjZDam51cUhhUFRuOWd0WQ", "crv": "P-256", "x": "1kNR9Ar3MzMokYTY8BRvRIue85NIXrYX4XD3K4JW7vI", - "y": "slT14644zbYXYF-xmw7aPdlbMuw3T1URwI4nafMtKrY", - "x5c": [ ] + "y": "slT14644zbYXYF-xmw7aPdlbMuw3T1URwI4nafMtKrY" } ] }, From 6ad09bbe2a780186e395ec4c2937823f257ffdc1 Mon Sep 17 00:00:00 2001 From: Emanuele De Cupis Date: Mon, 4 Mar 2024 21:51:52 +0100 Subject: [PATCH 3/6] Status Attestation Responses (#221) * refactor * remove line * clarify error code meaning --- docs/en/revocation-lists.rst | 137 ++++++++++++++++++++++------------- 1 file changed, 87 insertions(+), 50 deletions(-) diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 4b5da47ac..2fb8787e1 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -200,11 +200,52 @@ The Revocation Endpoint MUST be provided by the Issuer within its Metadata. Credential Revocation HTTP Response ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The response MUST be an HTTP Response using the status code set to *204 (No-Content)* in the case of successful revocation. If the Digital Credential could not be found by the Issuer, an HTTP Response with status code *404 (Not Found)* MUST be returned. Otherwise an HTTP error response MUST be provided by the Issuer to the Wallet Instance. This response MUST use *application/json* as the content type and MUST include the following parameters: +In case of successful revocation, the Issuer MUST return an HTTP Response with status code *204 No Content*. +Otherwise, an HTTP error response MUST be provided by the Issuer using status codes according to the table below. - - *error*. The error code. +The following HTTP Status Codes MUST be supported: + +.. list-table:: + :widths: 20 20 60 + :header-rows: 1 + + * - **Status Code** + - **Body** + - **Description** + * - *204 No Content* + - + - The Digital Credential has been successfully revoked. + * - *400 Bad Request* + - Error code and description + - The issuer cannot fulfill the request because of invalid parameters. + * - *404 Not Found* + - + - The Digital Credential to be revoked can not be found by the Issuer. + * - *500 Internal Server Error* + - + - The Issuer encountered an internal problem. (:rfc:`6749#section-5.2`). + * - *503 Service Unavailable* + - + - The Issuer is temporary unavailable. (:rfc:`6749#section-5.2`). + +For HTTP error responses that involve a body, the body MUST be encoded in ``application/json`` format and MUST contain the following parameters: + + - *error*. The error code, as registerd in the table below. - *error_description*. Text in human-readable form providing further details to clarify the nature of the error encountered. +Error codes are meant to provide additional information about the failure so that the User can be informed and take the appropriate action. +The following Error Codes MUST be supported: + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - **Error Code** + - **Description** + * - ``invalid_request`` + - The request is not valid due to the lack or incorrectness of one or more parameters. (:rfc:`6749#section-5.2`). + + Below a non-normative example of an HTTP Response with an error. .. code:: @@ -217,25 +258,6 @@ Below a non-normative example of an HTTP Response with an error. "error_description": "The signature of credential_pop JWT is not valid" } -The following HTTP Status Codes and Error Codes MUST be supported: - -.. list-table:: - :widths: 20 20 60 - :header-rows: 1 - - * - **Status Code** - - **Error Code** - - **Description** - * - *400 Bad Request* - - *invalid_request* - - The request is not valid due to the lack or incorrectness of one or more parameters. (:rfc:`6749#section-5.2`). - * - *500 Internal Server Error* - - *server_error* - - The Issuer encountered an internal problem. (:rfc:`6749#section-5.2`). - * - *503 Service Unavailable* - - *temporarily_unavailable* - - The Issuer is temporary unavailable. (:rfc:`6749#section-5.2`). - Status Attestation Flows @@ -313,7 +335,7 @@ A non-normative example of Credential Proof of Possession is provided :ref:`in t .. code:: - HTTP/1.1 201 OK + HTTP/1.1 201 Created Content-Type: application/json { @@ -345,7 +367,7 @@ The *Credential status endpoint* MUST be provided by the Issuers within their Me Status Attestation HTTP Response ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The *Credential status endpoint* MUST return a response with a *HTTP status code 201 OK* if the Credential is valid at the time of the request. The responses MUST be encoded in ``application/json`` format. It MUST contain the following mandatory claims. +The *Credential status endpoint* MUST return a HTTP response with status code *201 Created* if the Credential is valid at the time of the request. The responses MUST be encoded in ``application/json`` format. It MUST contain the following mandatory claims. .. _table_http_response_claim: .. list-table:: @@ -359,48 +381,63 @@ The *Credential status endpoint* MUST return a response with a *HTTP status code - It MUST contain the Status Attestation as a signed JWT. - `[OAuth Status Attestation draft 01] `_. -If the Digital Credential could not be found by the Issuer, an HTTP Response with status code 404 (Not Found) MUST be returned. In all other cases the Issuer MUST return an HTTP Response Error using *application/json* as the content type, and including the following parameters: - - - *error*. The error code. - - *error_description*. Text in human-readable form that offers more details to clarify the nature of the error encountered (for instance, changes in some attributes, reasons for revocation, other). - -Below a non-normative example of an HTTP Response with an error. - -.. code:: - - HTTP/1.1 400 Bad Request - Content-Type: application/json;charset=UTF-8 - - { - "error": "invalid_request" - "error_description": "The signature of credential_pop JWT is not valid" - } - -The following HTTP Status Codes and Error Codes MUST be supported: +The following HTTP Status Codes MUST be supported: .. list-table:: :widths: 20 20 60 :header-rows: 1 * - **Status Code** - - **Error Code** + - **Body** - **Description** + * - *201 Created* + - Status Attestation response + - The Status Attestation has been successfully created and it has been returned. * - *400 Bad Request* - - *invalid_request* - - The request is not valid due to the lack or incorrectness of one or more parameters. (:rfc:`6749#section-5.2`). + - Error code and description + - The issuer cannot fulfill the request because of invalid parameters. + * - *404 Not Found* + - + - The Digital Credential can not be found by the Issuer. * - *500 Internal Server Error* - - *server_error* + - - The Issuer encountered an internal problem. (:rfc:`6749#section-5.2`). * - *503 Service Unavailable* - - *temporarily_unavailable* + - - The Issuer is temporary unavailable. (:rfc:`6749#section-5.2`). - * - *400 Bad Request* - - *credential_revoked* + +For HTTP error responses that involve a body, the body MUST be encoded in ``application/json`` format and MUST contain the following parameters: + + - *error*. The error code, as registerd in the table below. + - *error_description*. Text in human-readable form providing further details to clarify the nature of the error encountered. + +Error codes are meant to provide additional information about the failure so that the User can be informed and take the appropriate action. +The following Error Codes MUST be supported: + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - **Error Code** + - **Description** + * - ``invalid_request`` + - The request is not valid due to the lack or incorrectness of one or more parameters. (:rfc:`6749#section-5.2`). + * - ``credential_revoked`` - The Digital Credential is revoked. The reason of revocation MUST be provided in the *error_description* field. - * - *400 Bad Request* - - *credential_updated* + * - ``credential_updated`` - One or more attributes contained in the Digital Credential are changed. The *error_description* field MUST contain a list of updated attributes. +Below a non-normative example of an HTTP Response with an error. + +.. code:: + + HTTP/1.1 400 Bad Request + Content-Type: application/json;charset=UTF-8 + + { + "error": "invalid_request" + "error_description": "The signature of credential_pop JWT is not valid" + } .. _sec_revocation_nra_presentation: From 1cdf40bb3e4cac2627acb2668c797d3e0a6ae759 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Tue, 5 Mar 2024 11:45:32 +0100 Subject: [PATCH 4/6] Relying Party (#220) * fix!: alignments according to breaking changes introduced by openid4vci I-D * RP WTE in PE and Entity Configuration base * fix: RP presentation with client_id_scheme and request_uri_method within the qrcode/redirect url * fix: RP presentation with client_id_scheme and request_uri_method using post * fix: RP presentation defintiion with WTE with exp and iat as constraints * RP Giada's revision * RP state definition * Apply suggestions from code review Co-authored-by: Giada Sciarretta * RP seq diag svg aligned * Errors that might occur during the presentation (#226) * RP errors * Apply suggestions from code review Co-authored-by: Giada Sciarretta * fix: figure visualization issue * fix: editorial --------- Co-authored-by: Giada Sciarretta Co-authored-by: fmarino-ipzs * fix: renamed Wallet Trust Evidence in Wallet Attestation * Apply suggestions from code review Co-authored-by: Francesco Grauso --------- Co-authored-by: Giada Sciarretta Co-authored-by: fmarino-ipzs Co-authored-by: Francesco Grauso --- docs/en/remote-flow.rst | 349 ++++++++++++++++++----- docs/en/revocation-lists.rst | 2 +- images/cross_device_auth_seq_diagram.svg | 2 +- 3 files changed, 273 insertions(+), 80 deletions(-) diff --git a/docs/en/remote-flow.rst b/docs/en/remote-flow.rst index aa23ce488..6f95add8d 100644 --- a/docs/en/remote-flow.rst +++ b/docs/en/remote-flow.rst @@ -7,7 +7,7 @@ Remote Flow =========== -In this scenario the Relying Party MUST provide the URL where the signed presentation Request Object is available for download. +In this flow the Relying Party MUST provide the URL where the signed presentation Request Object is available for download. Depending on whether the User is using a mobile device or a workstation, the Relying Party MUST support the following remote flows: @@ -18,27 +18,28 @@ Once the Wallet Instance establishes the trust with the Relying Party and evalua A High-Level description of the remote flow, from the User's perspective, is given below: - 1. the Wallet Instance scans the QR Code and obtains the URL (Cross Device flow) or obtain directly an URL (Same Device flow); - 2. the Wallet Instance extracts from the payload the ``client_id`` and the `request_uri` parameters; - 3. the Wallet Instance establishes the Trust to the Relying Party by building the Federation Trust Chain. Implementations may evaluate the trust after having obtained the signed Request Object (see point 5); - 4. the Wallet fetches the signed Request Object using an HTTP request with method GET to the endpoint provided in the ``request_uri`` parameter; - 5. the Wallet verifies the signature of the signed Request Object and that its issuer matches the ``client_id`` obtained at the step number 2; - 6. the Wallet checks the presence in the signed Request Object of the parameter `request_uri_method`, if this parameter is present and set with the ``post`` valueThe Wallet transmits its metadata to the request_uri endpoint of the Relying Party using an HTTP POST method and obtains an updated signed Request Object; - 7. The Wallet Instance evaluates the requested PID/EAAs and checks the elegibility of the Relying Party in asking these by applying the policies related to that specific Relying Party; - 8. the Wallet Instance asks User disclosure and consent; - 9. the Wallet Instance presents the requested disclosure of PID/EAAs to the Relying Party, which validates the Wallet Attestation and checks that the Wallet Provider is trusted; - 10. the Wallet Instance informs the User about the successfull authentication with the Relying Party and give a good user experience to let the User continuing its navigation. + 1. the Wallet Instance obtains an URL in the Same Device flow or a QR Code containing the URL in Cross Device flow; + 2. the Wallet Instance extracts from the payload the following parameters: ``client_id``, ``request_uri``, ``state``, ``request_uri_methods`` and ``client_id_scheme``; + 3. If the ``client_id_scheme`` is provided and set with the value ``entity_id``, the Wallet Instance MUST collect and validate the OpenID Federation Trust Chain related to the Relying Party. If the ``client_id_scheme`` is either not provided or is assigned a value different from ``entity_id``, the Wallet Instance MUST establish the trust by utilizing the ``client_id`` or an alternative ``client_id_scheme`` value. This alternative value MUST enable the Wallet Instance to establish trust with the Relying Party, ensuring compliance with the assurance levels mandated by the trust framework; + 4. If ``request_uri_methods`` is provided and set with the value ``post``, the Wallet Instance SHOULD transmit its metadata to the Relying Party's ``request_uri`` endpoint using the HTTP POST method and obtain the signed Request Object. If ``request_uri_methods`` is set with the value ``get`` or not present, the Wallet Instance MUST fetch the signed Request Object using an HTTP request with method GET to the endpoint provided in the ``request_uri`` parameter; + 5. the Wallet Instance verifies the signature of the signed Request Object, using the public key obtained with the trust chain, and that its issuer matches the ``client_id`` obtained at the step number 2; + 6. the Wallet Instance evaluates the requested Digital Credentials and checks the elegibility of the Relying Party in asking these by applying the policies related to that specific Relying Party, obtained with the trust chain; + 7. the Wallet Instance asks User disclosure and consent; + 8. the Wallet Instance presents the requested information to the Relying Party along with the Wallet Attestation. The Relying Party validates the presented Credentials checking the trust with their Issuers, and validates the Wallet Attestation by also checking that the Wallet Provider is trusted; + 9. the Wallet Instance informs the User about the successfull authentication with the Relying Party, the User continues the navigation. Below a sequence diagram that summarizes the interactions between all the involved parties. .. figure:: ../../images/cross_device_auth_seq_diagram.svg + :figwidth: 100% :align: center - :target: https://www.plantuml.com/plantuml/svg/XLNTRkCs4xtdKnpuk_YI84cpspi3AJQRfflijergUpSt1W9Q6jjiQ5BbZvoqwBjtA5goN2GeO1WGEMVcdFaPVl11kX0tMiWOh8cR1JaXn5KPhCFegoStWlI8GYpiSpxulyUFrAYI_0Z_-rcjrk6ZZYHgzgDALKiJC7gGMbF0dM7tfgJMn_RG9BAhCxaY4t84ASXKu2Y7PXFIBygiKF3XIslPa10HPpymP8m7Mc1ABj61aOrQoQ2i4L4cWuR6cD0VaNn0uMoWCb359zv6LxANoqiaGRYAOKs6OxPW71MEF7_dhs8jFHtZybB8CgX61aeC6ke2N3jAPn8d9vuXT7A2Hkf8SxEmaHK5YxrKbDO-gLVWBjDyZ4x1TGGRwcJ-Dhcs5U5-WjlPh609bNAi1aVVNxm_nbQ5DKgjEC2Zgaw7paxHaX8L3TcBlPQj42jdOyr4hEyg2slqoow9SOpfscx1AUferAmbbO1ljsFSrsJQstyL7RAkJw5jAJNaGOR55XawBQLXfqXU-yERv-2OtjpqYkPce6XkfAcoghbPEhj9iNidP2hHUw9K2BRp22xwaFEKh7lFsPJhqENCj_TUhGnLtHdiulUKx3xOi5WSiBRAXBPOEUohQ4wv3b3B8VXnGs5jAoWFJpjwnVrq9WG0zDHgPnjLaUyIp2XPoI0HxDjqaeU-omQP61GgK6bKgaufQxbGMWL5lWTcBR7cI5IzfUcDT1yCBNxf-AR2rLQhakFqg6_arFAb3I13T0Ix7DIWdz_x7B57IQqIi-wUBRyLH_uu6yJzt2-jGsbDckTzqyTzzrvRirHkGzLmH6BV5sqzsWLXdVepRuG9-JfvnDpacZNrOx1FPDxO43Uxl2HPMQwI2qquM3FPGG_g1GuBTXK2-Mn_pi7pvz2Wo9tYc9ZoI7kqo-PFnCSjak-u3gyEB6EC3N3KC9dgVC0cXqhBgafZB3Nkl8_aC4k3bLtkANz-c67QrNFWXUcLv7qUmTwL48wZ4cn3ZituJRdxT3lxDBcv-LMyZXWBNA-fVCAjrImBN-W57vMfkELQ8enYsVmhhFSCPzKCEKFqRD7wgkD2gn9F3CnRMgMyyCrGOh1eskRCXIjoZSw5m6nDfjjJxMMbVAcjfmeo1ASMCP0VSuaoppJsdEf-M1N7G9u8Hv2DL3erH9gcDXLYaBElTTS5-QtQwS5HVacw0Jt6O06bD-AxT-VlyFxY0lTVcCPV8vUVZ7PBZCPOXr1xHATp1xjTIp-MjYByFPo5xU7RqJqNKxcXWzSY3vvanZxJ7KPCqlxheMceV-S-JyUxp1q-77djuoW9x7PH5f2pSPoJa7bSlGPTgOPCXhHEabv_YiXsMeEUwxOsri77CdNUCkgM-mV-Ynlz3m00 + :target: https://www.plantuml.com/plantuml/svg/ZLLRRnit4ttdhpZGz_3PXkCcwPi05t5SDvUqjMefoKCI21Ht9B6co2qlgxX5_tjdIUo2SWIqXc5Or5pEd3apyo94wMFQ6I5JT3RjLkI545SgEe_9-q1-0XcGX5Yvh-NX_m4_KgSLXGd-zxFUREDBaqYq74ShtKeRCVaeZQ68DvR3MqKvnlxG976e9t93DfOCKf1jm5aEpUx8F6YxmOmV7x9bHq985NKd8p6mX2S_iFSK7sc5EVaU6Qpiz4P6xMnbAaL3jQFiFJkQuex-I1GYPjv5Kf4QVWakUSMPBY_vcGB3pE4msyf0kBmSu_PuEXf2NNlgtoJEpW9xqDaPEidqVBOhbxY-w30M7g6SkzT7t7q1j4nUmmzGEXeg_UtksZM4spkyNYnc3BRHdd7ZvFkdpq-nrt7xsIgZESDID-Trj7DaLEVuL3qkTnIthlc2JwFJCgWjxUXBnLZcdNystgMMWRemw03EceT29z8KywtR8svfWDbohGVCoqVjOxVz5BSjsUpsI3kGRNiEuvGqa8aDB8kZjBOEEiPadUrHGiwLj8m2FOpnyUPhz6oRKx7I91TFFc3jtIw_3VPa6p4wKTz43XuGVGenSvojHyQEaIUaYT1hVCirT42W4WUps_b20C1-a47hNQSR2WCNx2GR6IMYorbhVJ3ErcaRSuIwMG0mAgkgeE8uahAw9rR9LgwqqL5J46G2_GVOhsuMS1xMHRHbGaHLm-1TyWMziTGCRt2htqd5aVFZzUG6T3JeusY8n_eyqh231O9V1YQbRT0wenLNF7fz8A_N3pcLZCaJtBg2F-w9sv9xz996DzNOikM7sKauBGPfElgjdOToDbDrR0IkdLrhlwFcKDa3fLaek4hS2Q__BEk85rNRHyHdMxhIjSlexicEazvMssiPqcgdG-1_Z-ylt1JUA9UTwT1oPUXm1-O4erD5G2MjgyZa5_iB1bS-rWQped7Fm7L0l_C7jdyYViwU_1ttwUXMq24hprF7O9gB2ar9rQ_IXX5hQV0cX4GUYtvqIyWHCjv-N60-zBkAml0KXQ9UDOOImdDMWkl8indVlpUlNYzUtTtS_2gEUqm5hhUaxl7QcOQTtj43NchRi2Gp4FRYilbtvaAWt1fsUO8KsA8igRHYcUAU7SiDqNbFrWL6XovBjxHjLZfq8GGMMxAWQkKrEYZZ0ZMGCNgzIapM52f3r6imo-D4Qaw0CYoU83kf3MiXRyRCWgZeUj-E0dWVo2EKKd1IJXnI_huvHJNH_V7wxjd5Cpn_-XItxxWpVqrykMLv5KocsCRO1YHlYhWz5RKlbMi8Vul7urzkqrpkwE0qxOV3oT0on3fB7MClwYl5TVxRkUjelCPlvzFIwKTNgimXJlfgn-sLgodKd7upYGKihew5sUYER77F0NiYmZaIsnd3ZMvpqvn7IAfNupgPmzjxI5ckyGN_IJlp3m00 + Remote Protocol Flow -The details of each step shown in the previous picture are described in the table below. +The details of each step shown in the previous picture are described in the table below. .. list-table:: :widths: 10 50 @@ -47,26 +48,30 @@ The details of each step shown in the previous picture are described in the tabl * - **Id** - **Description** * - **1**, **2** - - The User requests to 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. + - The User requests to access to a protected resource of the Relying Party. * - **3**, **4**, - - The Relying Party provides the Wallet Instance with a URL where a generic signed Request Object can be downloaded. + - The Relying Party provides the Wallet Instance with a URL where the information about the Relying Party are provided, along with the information about where the signed request is available for download. * - **5**, **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. The User frames the QRCode with the Wallet Instance and extracts ``client_id``, ``request_uri`` and ``state``. In the **Same Device Flow** the Relying Party provides the same information of the Cross-Device flow but in the form of HTTP Redirect Location (302). - * - **10**, **11**, **12** + - In the **Cross Device Flow**, the Request URI is presented as a QR Code displayed to the User. The User scans the QR Code using the Wallet Instance, which retrieves a URL with the parameters ``client_id``, ``request_uri``, ``state``, ``client_id_scheme``, and ``request_uri_method``. Conversely, in the Same Device Flow, the Relying Party supplies identical information as in the Cross-Device flow, but directly through a URL. + * - **10**, + - The Wallet Instance evaluates the trust with the Relying Party. + * - **11**, **12** + - The Wallet Instance checks if the Relying Party has provided the ``request_uri_method`` within its signed Request Object. If provided and it is equal to ``post``, the Wallet Instance provides its metadata to the Relying Party. The Relying Party returns a signed Request Object compliant to the Wallet technical capabilities. + * - **13** + - When the Wallet Instance capabilities discovery is not supported by RP, the Wallet Instance request the signed Request Object using the HTTP method GET. + * - **14** - The Wallet Instance obtains the signed Request Object. - * - **13**, **14** and **15** - - The Wallet Instance checks if the Relying Party has provided the ``request_uri_method`` within its signed Request Object. If true, the Wallet provides its metadata in the to the Relying Party. The Relying PArty produces a new signed Request Object compliant to the Wallet technical capabilities. - * - **13**, **14**, **15**, **16**, **17**, **18** - - The Request Object JWS is verified by the Wallet Instance. The Wallet processes the Relying Party metadata and applies the policies related to the Relying Party, attesting whose Digital Credentials and User data the Relying Party is granted to request. - * - **19**, **20** + * - **15**, **16**, **17** + - The Request Object JWS is verified by the Wallet Instance. The Wallet Instance processes the Relying Party metadata and applies the policies related to the Relying Party, attesting whose Digital Credentials and User data the Relying Party is granted to request. + * - **18**, **19** - The Wallet Instance requests the User's consent for the release of the Credentials. The User authorizes and consents the presentation of the Credentials by selecting/deselecting the personal data to release. - * - **21** - - The Wallet Instance provides the Authorization Response to the Relying Party using an HTTP request with the method POST (response mode "direct_post"). - * - **22**, **23**, **24**, **25** and **26** + * - **20** + - The Wallet Instance provides the Authorization Response to the Relying Party using an HTTP request with the method POST (response mode "direct_post.jwt"). + * - **21**, **22**, **23**, **24**, **25** - The Relying Party verifies the Authorization Response, extracts the Wallet Attestation to establish the trust with the Wallet Solution. The Relying Party extracts the Digital Credentials and attests the trust to the Credentials Issuer and the proof of possession of the Wallet Instance about the presented Digital Credentials. Finally, the Relying Party verifies the revocation status of the presented Digital Credentials. - * - **27** and **28** - - The Relying Party provides to the Wallet a redirect URI with a response code to be used by the Wallet to finalize the authentication. - * - **29** + * - **26** + - The Relying Party provides to the Wallet Instance a redirect URI with a response code to be used by the Wallet Instance to finalize the authentication. + * - **27**, **28** and **29** - The User is informed by the Wallet Instance that the Autentication succeded, then the protected resource is made available to the User. @@ -78,8 +83,8 @@ allowing the Wallet Instance to inform the Relying Party about its technical cap This feature can be useful when, for example, the Wallet Instance supports a restricted set of features, supported algorithms or a specific url for -its ``authorization_endpoint``, and any other information that it deems necessary to -provide to the Relying Party the parameters necessary for better interoperability. +its ``authorization_endpoint``, and any other information that it deems necessary to +provide to the Relying Party for better interoperability. .. warning:: The Wallet Instance, when providing its technical capabilities to the @@ -87,8 +92,8 @@ provide to the Relying Party the parameters necessary for better interoperabilit information regarding the hardware used or usage preferences of its User. If both the Relying Party and the Wallet Instance -supports the ``request_uri_method`` with HTTP POST, -the Wallet Instance capabilities MUST +support the ``request_uri_method`` with HTTP POST, +the Wallet Instance capabilities (metadata) MUST be provided using an HTTP request to the `request_uri` endpoint of the Relying Party, with the method POST and content type set to `application/json`. @@ -119,7 +124,7 @@ A non-normative example of the HTTP request is represented below: "request_object_signing_alg_values_supported": [ "ES256" ], - "presentation_definition_uri_supported": false, + "presentation_definition_uri_supported": false } The response of the Relying Party is defined in the section below. @@ -129,8 +134,8 @@ Authorization Request Details ----------------------------- The Relying Party MUST create a Request Object in the form of a signed JWT and -it MUST 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 +MUST 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. @@ -141,17 +146,21 @@ response, containing the request URI, are described in the Table below. * - **Name** - **Description** * - **client_id** - - Unique identifier of the Relying Party. + - REQUIRED. Unique identifier of the Relying Party. * - **request_uri** - - The HTTPs URL where the Relying Party provides the signed Request Object to the Wallet Instance. - + - REQUIRED. The HTTPs URL where the Relying Party provides the signed Request Object to the Wallet Instance. + * - **client_id_scheme** + - OPTIONAL. The scheme used by the Relying Party for the client_id, detailing the format and structure and the trust evaluation method. It SHOULD be set with ``entity_id``. + * - **state** + - OPTIONAL. A unique identifier for the current transaction generated by the Relying Party. The value SHOULD be opaque to the Wallet Instance. + * - **request_uri_method** + - OPTIONAL. The HTTP method MUST be set with ``get`` or ``post``. The Wallet Instance should use this method to obtain the signed Request Object from the request_uri. If not provided or equal to ``get``, the Wallet Instance SHOULD use the HTTP method ``get``. Otherwise, the Wallet Instance SHOULD provide its metadata within the HTTP POST body encoded in ``application/json``. - Below a non-normative example of the response containing the required parameters previously described. .. code-block:: javascript - https://wallet-solution.digital-strategy.europa.eu/authorization?client_id=...&request_uri=... + https://wallet-solution.digital-strategy.europa.eu/authorization?client_id=...&request_uri=...&client_id_scheme=entity_id&request_uri_method=post The value corresponding to the `request_uri` endpoint SHOULD be randomized, according to `RFC 9101, The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR) `_ Section 5.2.1. @@ -164,6 +173,8 @@ In the **Same Device Flow** the Relying Party uses an HTTP response redirect (wi Location: https://wallet-solution.digital-strategy.europa.eu? client_id=https%3A%2F%2Frelying-party.example.org%2Fcb &request_uri=https%3A%2F%2Frelying-party.example.org%2Frequest_uri + &client_id_scheme=entity_id + &request_uri_method=post 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. @@ -179,7 +190,7 @@ Below is represented a non-normative example of the QR Code raw payload: .. code-block:: text - https://wallet-solution.digital-strategy.europa.eu/authorization?client_id=https%3A%2F%2Frelying-party.example.org&request_uri=https%3A%2F%2Frelying-party.example.org + https://wallet-solution.digital-strategy.europa.eu/authorization?client_id=https%3A%2F%2Frelying-party.example.org&request_uri=https%3A%2F%2Frelying-party.example.org&client_id_scheme=entity_id&request_uri_method=post .. note:: The *error correction level* chosen for the QR Code MUST be Q (Quartily - up to 25%), since it offers a good balance between error correction capability and data density/space. This level of quality and error correction allows the QR Code to remain readable even if it is damaged or partially obscured. @@ -190,9 +201,9 @@ Cross Device Flow Status Checks and Security When the flow is Cross Device, the user-agent needs to check the session status to the endpoint made available by Relying Party (status endpoint). This check MAY be implemented in the form of JavaScript code, within the page that shows the QRCode, then the user-agent checks the status with a polling strategy in seconds or a push strategy (eg: web socket). -Since the QRcode page and the status endpoint are implemented by the Relying Party, it is under its responsability the implementation details of this solution, since it is related to the Relying Party's internal API. +Since the QRcode page and the status endpoint are implemented by the Relying Party, it is under the Relying Party responsability the implementation details of this solution, since it is related to the Relying Party's internal API. However, the text below offers an implementation solution. -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: +The Relying Party MUST bind the request of the user-agent, with a session cookie marked as ``Secure`` and ``HttpOnly`` , 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: * **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. @@ -219,7 +230,7 @@ Below a non-normative example of HTTP request made by the Wallet Instance to the HOST: relying-party.example.org -Request URI response +Request URI Response -------------------- The Relying Party issues the signed Request Object, where a non-normative example in the form of decoded header and payload is shown below: @@ -238,7 +249,7 @@ The Relying Party issues the signed Request Object, where a non-normative exampl } . { - "scope": "eu.europa.ec.eudiw.pid.it.1 tax_id_number", + "scope": "eu.europa.ec.eudiw.pid.it.1 WalletAttestation", "client_id_scheme": "entity_id", "client_id": "https://relying-party.example.org", "response_mode": "direct_post.jwt", @@ -279,7 +290,7 @@ The JWS payload parameters are described herein: * - **Name** - **Description** * - **scope** - - 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]. + - 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 set to the value ``entity_id``. * - **client_id** @@ -287,7 +298,7 @@ The JWS payload parameters are described herein: * - **response_mode** - It MUST be set to ``direct_post.jwt``. * - **response_type** - - It 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 HTTP request using the method POST. * - **nonce** @@ -301,7 +312,7 @@ The JWS payload parameters are described herein: * - **exp** - Unix Timestamp, representing the expiration time on or after which the JWT MUST NOT be valid anymore. * - **request_uri_method** - - String determining the HTTP method to be used with the `request_uri` endpoint to provide the Wallet metadata to the Relying Party. The value is case-insensitive and can be set to: `get` or `post`. The GET method, as defined in [@RFC9101], involves the Wallet sending a GET request to retrieve a Request Object. The POST method involves the Wallet requesting the creation of a new Request Object by sending an HTTP POST request, with its metadata, to the request URI of the Relying Party. + - String determining the HTTP method to be used with the `request_uri` endpoint to provide the Wallet Instance metadata to the Relying Party. The value is case-insensitive and can be set to: `get` or `post`. The GET method, as defined in [@RFC9101], involves the Wallet Instance sending a GET request to retrieve a Request Object. The POST method involves the Wallet Instance requesting the creation of a new Request Object by sending an HTTP POST request, with its metadata, to the request URI of the Relying Party. .. warning:: @@ -330,6 +341,25 @@ The JWS payload parameters are described herein: ], "limit_disclosure": "preferred" } + }, + { + "id": "WalletAttestation", + "name": "Wallet Attestation", + "purpose": "Wallet Authentication", + "format": "jwt", + "constraints": { + "fields": [ + { + "path": [ + "$.iss", + "$.exp", + "$.iat", + "$.cnf.jwk", + "$.aal", + ] + } + ] + } } ] } @@ -346,10 +376,55 @@ The JWS payload parameters are described herein: - ``client_metadata_uri``: string containing an HTTPS URL pointing to a resource where a JSON object with the Relying Party metadata can be retrieved. The ``client_metadata_uri`` parameter MUST NOT be present when ``client_id_scheme`` is ``entity_id``. Since the ``client_metadata`` is taken from ``trust_chain``, this parameter is intended to not be used. +Request URI Endpoint Errors +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the Relying Party encounters errors while issuing the Request Object from the ``request_uri`` endpoint, the following error responses are applicable: + +- **invalid_request**: The ``request_uri`` URL is missing in some part within its webpath or urlparams, therefore it does not point to a valid Request Object and then it cannot be retrieved. This error is returned when the Request Object is not well referenced in the ``request_uri``. + +- **server_error**: The server encountered an unexpected condition that prevented it from fulfilling the request. This error is returned when the Relying Party's server is unable to process the Request Object due to a server-side issue, such as a malfunction or maintenance. The Wallet Instance should advise the User to try again later. + +The following is an example of an error response from ``request_uri`` endpoint: + +.. code-block:: + + HTTP/1.1 400 Bad Request + Content-Type: application/json + + { + "error": "invalid_request", + "error_description": "The request_uri is malformed or does not point to a valid Request Object." + } + + +Another example: + +.. code-block:: + + HTTP/1.1 500 Internal Server Error + Content-Type: application/json + + { + "error": "server_error", + "error_description": "The request_uri cannot be retrieved due to an internal server error." + } + +There are cases where the Wallet Instance cannot validate the Request Object or the Request Object results invalid. This error occurs if the Request Object is successfully fetched from the ``request_uri`` but fails validation checks by the Wallet Instance. This could be due to incorrect signatures, malformed claims, or other validation failures, such as the revocation of its issuer (Relying Party). + +Upon receiving an error response, the Wallet Instance SHOULD inform the User of the error condition in an appropriate manner. Additionally, the Wallet Instance SHOULD log the error and MAY attempt to recover from certain errors if feasible. For example, if the error is ``server_error``, the Wallet Instance MAY prompt the User to re-enter or scan a new QR code, if applicable. + +It is crucial for Wallet Instances to implement robust error handling to maintain a secure and user-friendly experience. Adhering to the specified error responses ensures interoperability and helps in diagnosing issues during the interaction with the Relying Party's endpoints. + +.. warning:: + + The current OpenID4VP specification outlines various error responses that a Wallet Instance may return to the Relying Party (Verifier) in case of faulty requests (OpenID4VP, Section 6.4. Error Response). For privacy enhancement, Wallet Instances SHOULD NOT notify the Relying Party of faulty requests in certain scenarios. This is to prevent any potential misuse of error responses that could lead to gather informations that could be exploited. + + Authorization Response Details ------------------------------ -After getting the User authorization and consent for the presentation of the Credentials, the Wallet sends the Authorization Response to the Relying Party ``response_uri`` endpoint, the content SHOULD be encrypted according `OPENID4VP`_ Section 6.3, using the Relying Party public key. +After getting the User authorization and consent for the presentation of the Credentials, the Wallet Instance sends the Authorization Response to the Relying Party ``response_uri`` endpoint, the content SHOULD be encrypted according `OPENID4VP`_ Section 6.3, using the Relying Party public key. .. note:: **Why the response is encrypted?** @@ -375,7 +450,7 @@ Below is a non-normative example of the decrypted JSON ``response`` content: "state": "3be39b69-6ac1-41aa-921b-3e6c07ddcb03", "vp_token": [ "eyJhbGciOiJFUzI1NiIs...PT0iXX0", - $WalletInstanceAttestation-JWT + $WalletAttestation-JWT ], "presentation_submission": { "definition_id": "32f54163-7166-48f1-93d8-ff217bdb0653", @@ -385,6 +460,11 @@ Below is a non-normative example of the decrypted JSON ``response`` content: "id": "eu.europa.ec.eudiw.pid.it.1", "path": "$.vp_token.verified_claims.claims._sd[0]", "format": "vc+sd-jwt" + }, + { + "id": "WalletAttestation", + "path": "$", + "format": "jwt" } ] } @@ -400,10 +480,10 @@ Where the following parameters are used: - **Description** * - **vp_token** - JSON Array containing the Verifiable Presentation(s). There MUST be at least two signed presentations in this Array: - - The Requested Digital Credential (one or more, if in format SD-JWT VC or MDOC CBOR) - - The Wallet Instance Attestation + - The requested Digital Credential (one or more, in format of SD-JWT VC or MDOC CBOR) + - The Wallet Attestation * - **presentation_submission** - - JSON Object containing the mappings between the requested Verifiable Credentials and where to find them within the returned Verifiable Presentation Token. + - JSON Object containing the mappings between the requested Verifiable Credentials and where to find them within the returned Verifiable Presentation Token, according to the `Presentation Exchange `_. * - **state** - Unique identifier provided by the Relying Party within the Authorization Request. @@ -424,7 +504,7 @@ Below is a non-normative example of the ``vp_token`` decoded content, represente "aud": "https://relying-party.example.org/response_uri", "iat": 1541493724, "exp": 1573029723, - "nonce": "2c128e4d-fc91-4cd3-86b8-18bdea0988cb" + "nonce": "2c128e4d-fc91-4cd3-86b8-18bdea0988cb", "vp": "~~~...~" } @@ -437,7 +517,7 @@ Where the following parameters are used: * - **Name** - **Description** * - **vp** - - The Digital Credential in its original state. The public key contained in the Digital Credential MUST be used to verify the entire VP JWS as Proof of Possession of the private key which the public key is included in the Digital Credential. Eg: for SD-JWT VC the pblic key is provided within the ``cnf.jwk`` claim. + - The Digital Credential in its original state. The public key contained in the Digital Credential MUST be used to verify the entire VP JWS as Proof of Possession of the private key which the public key is included in the Digital Credential. Eg: for SD-JWT VC the public key is provided within the ``cnf.jwk`` claim. * - **jti** - JWS unique identifier. * - **iat** @@ -450,14 +530,48 @@ Where the following parameters are used: - The nonce value provided by the Relying Party within the Authorization Request. +Authorization Response Errors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the Wallet sends a response using ``direct_post.jwt`` to the Relying Party, several errors may occur, including: + + - **Invalid Credential**: This error occurs when one or more Credentials or VPs, included in the ``vp_token``, fail validation because they are malformed. The correct HTTP status code for this error is 400 (Bad Request). The error should be set to ``invalid_request``, and the ``error_description`` SHOULD identify the malformed Credentials. + - **Issuer Credential Trust Failure**: This error arises when the Relying Party cannot establish trust with the issuer of a presented Credential, included in the ``vp_token``. The appropriate HTTP status code for this error is 403 (Forbidden). The ``error`` should be labeled as ``invalid_request``, and the ``error_description`` SHOULD specify the issuer for which trust could not be established. + - **Invalid Nonce**: This error happens when the nonce provided in the request is incorrect. The HTTP status code for this error should be 403 (Forbidden). The error SHOULD be labeled as ``invalid_request``, with an ``error_description`` indicating that the nonce is incorrect. + - **Invalid Wallet Attestation**: This error occours when it's not possible to establish trust with the Wallet Attestation's issuer (Wallet Provider), or if the Wallet Attestation is invalid or does not meet the Relying Party's minimum security criteria. The correct HTTP status code for this error is 403 (Forbidden). The ``error`` SHOULD be marked as ``invalid_request``, and the ``error_description`` should clarify that the issue stems from the Wallet Attestation's failure to establish trust with its issuer or its non-compliance with required security standards. + - **Invalid Presentation Submission**: This error occurs when the presentation submission is not valid. The appropriate HTTP status code for this error is 400 Bad Request. The ``error`` should be labeled as ``invalid_request``, and the ``error_description`` should specify the invalid aspects of the presentation submission. + + To enhance clarity and ensure proper error handling, it's crucial to provide detailed error responses. Below are two examples of HTTP responses using ``application/json`` that include both the ``error`` and ``error_description`` members: + +.. code-block:: text + + HTTP/1.1 403 Forbidden + Content-Type: application/json + + { + "error": "invalid_request", + "error_description": "Trust cannot be established with the issuer: https://issuer.example.com" + } + + +.. code-block:: text + + HTTP/1.1 400 Bad Request + Content-Type: application/json + + { + "error": "invalid_request", + "error_description": "The following Credentials/VP are malformed: [CredentialX, vp_token[2]]" + } + Redirect URI ------------ -When the Relying Party provides the redirect URI, the Wallet MUST send the user-agent to this redirect URI. The redirect URI allows the Relying Party to continue the interaction with the End-User on the device where the Wallet resides after the Wallet has sent the Authorization Response to the response URI. +When the Relying Party provides the redirect URI, the Wallet Instance MUST send the user-agent to this redirect URI. The redirect URI allows the Relying Party to continue the interaction with the End-User on the device where the Wallet Instance resides after the Wallet Instance has sent the Authorization Response to the response URI. -The Relying Party MUST include a response code withing the redirect URI. The response code is a fresh, cryptographically random number used to ensure only the receiver of the redirect can fetch and process the Authorization Response. The number could be added as a path component, as a parameter or as a fragment to the URL. It is RECOMMENDED to use a cryptographic random value of 128 bits or more at the time of the writing of this specification. +The Relying Party MUST include a response code within the redirect URI. The response code is a fresh, cryptographically random number used to ensure only the receiver of the redirect can fetch and process the Authorization Response. The number could be added as a path component, as a parameter or as a fragment to the URL. It is RECOMMENDED to use a cryptographic random value of 128 bits or more at the time of the writing of this specification. -The following is a non-normative example of the response from the Relying Party to the Wallet upon receiving the Authorization Response at the Response Endpoint. +The following is a non-normative example of the response from the Relying Party to the Wallet Instance upon receiving the Authorization Response at the Response Endpoint. .. code-block:: http @@ -469,8 +583,18 @@ The following is a non-normative example of the response from the Relying Party "redirect_uri": "https://relying-party.example.org/cb#response_code=091535f699ea575c7937fa5f0f454aee" } -The ``redirect_uri`` value MUST be used with an HTTP method GET by either the Wallet or the user-agent to redirect the User to the Relying Party in order to complete the authentication process. The specific entity that performs this action depends on whether the flow is Same device or Cross device. +The ``redirect_uri`` value MUST be used with an HTTP method GET by either the Wallet Instance or the user-agent to redirect the User to the Relying Party in order to complete the process. The specific entity that performs this action depends on whether the flow is Same device or Cross device. + +Redirect URI Errors +------------------- + +When the Wallet Instance sends the user-agent to the Redirect URI provided by the Relying Party, several errors may occur that prevent the successful completion of the process. These errors are critical as they directly impact the User experience by hindering the seamless flow of information between the Wallet Instance and the Relying Party. Below are potential errors related to the Redirect URI and their implications: +- **Mismatched Redirect URI**: This error occurs when the Redirect URI provided by the Relying Party does not match any of the URIs linked with the User session. This mismatch can lead to a HTTP status error code set to 403 (Forbidden), indicating that the request cannot be processed due session/URI mismatch. + +- **Redirect URI Security Issues**: If the Relying Party incurs in security issues when evaluating the User session with the provided URI, the Relying Party MUST raise an error. In such cases, an HTTP status code set to 403 (Forbidden) MUST be returned, indicating that the request is valid but the server is refusing action due to security precautions. + +Handling these errors requires clear communication to the User within the returned navigation web page. It is crucial for the Relying Party to implement robust error handling and validation mechanisms for Redirect URIs to ensure a secure implementation. Relying Party Entity Configuration ----------------------------------- @@ -489,7 +613,7 @@ Below is a non-normative response example: .. code-block:: text { - "alg": "RS256", + "alg": "ES256", "kid": "2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", "typ": "entity-statement+jwt" } @@ -502,10 +626,11 @@ Below is a non-normative response example: "jwks": { "keys": [ { - "kty": "RSA", - "n": "5s4qi ...", - "e": "AQAB", - "kid": "2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs" + "kty": "EC", + "crv": "P-256", + "x": "5s4qi ...", + "y": "AQAB", + "kid": "2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", } ] }, @@ -517,12 +642,11 @@ Below is a non-normative response example: "jwks": { "keys": [ { - "kty": "RSA", - "use": "sig", - "n": "1Ta-sE ...", - "e": "AQAB", - "kid": "YhNFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", - "x5c": [ "..." ] + "kty": "EC", + "crv": "P-256", + "x": "5s4qi ...", + "y": "AQAB", + "kid": "9tjiCaivhWLVUJ3AxwGGz_9", } ] }, @@ -555,7 +679,7 @@ Below is a non-normative response example: }, "presentation_definitions": [ { - "id": "eu.europa.ec.eudiw.pid.it.1", + "id": "32f54163-7166-48f1-93d8-ff217bdb0653", "input_descriptors": [ { "id": "IdentityCredential", @@ -592,7 +716,56 @@ Below is a non-normative response example: } ] } + }, + { + "id": "WalletAttestation", + "format": { + "jwt": {} + }, + "constraints": { + "fields": [ + { + "path": [ + "$.iss" + ], + "filter": { + "type": "string", + "enum": [ + "https://issuer.example.org", + "https://issuer2.example.org", + "https://issuer3.example.org" + ] + } + }, + { + "path": [ + "$.iat" + ], + "filter": { + "type": "number", + "minimum": 1504699136 + } + }, + { + "path": [ + "$.exp" + ], + "filter": { + "type": "number", + "minimum": 1504700136 + } + }, + { + "path": [ + "$.cnf.jwk" + ], + "filter": { + "type": "object" + } + } + ] } + } ] }, { @@ -709,7 +882,9 @@ Below is a non-normative response example: } -The Entity Configuration is a JWS, where its header parameters are defined below: +The Entity Configuration is a JWS, where its header and payload parameters are defined below, based on the provided OpenID Federation Entity Configuration example: + +**JWT Header Parameters** .. list-table:: :widths: 25 50 @@ -718,14 +893,32 @@ The Entity Configuration is a JWS, where its header parameters are defined below * - **Name** - **Description** * - **alg** - - Algorithm used to sign the JWT + - The digital signature algorithm used to sign the JWT. For example, "ES256" for ECDSA using P-256 and SHA-256. * - **typ** - - Media Type of the JWT + - The Media Type of the JWT, it MUST be set to "entity-statement+jwt". * - **kid** - - Key ID used identifying the key used to sign the JWS + - The Key ID used for identifying the key used to sign the JWS. + +**JWT Payload Parameters** +.. list-table:: + :widths: 25 50 + :header-rows: 1 -.. note: - The Relying Party specific metadata parameter are experimental - and still under discussion `here `_. + * - **Name** + - **Description** + * - **iss** + - The issuer of the Entity Configuration, identifying the entity that issued the Entity Configuration. + * - **sub** + - The subject of the Entity Configuration, identifying the principal that is the subject of the Entity Configuration. + * - **jwks** + - JSON Web Key Set representing the cryptographic keys used for trust evaluation operations and for signing this Entity Configuration. + * - **metadata** + - Metadata describing the entity, including information about the wallet relying party, client ID, client name, contacts, request URIs, response URIs, default ACR values, and VP formats. + * - **authority_hints** + - URLs hinting at the authority or authorities that the entity trusts and which the public keys for verifieng this Entity Confgiuration are intended to be available within a Subordinate Statement. + * - **exp** + - Unix Timestamp representing the expiration time of the Entity Configuration, after which the Entity Configuration MUST NOT be accepted for processing. + * - **iat** + - Unix Timestamp representing the issued at time of the Entity Configuration, representing the time at which the Entity Configuration was issued. diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 2fb8787e1..908e41111 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -482,7 +482,7 @@ The Credential Proof of Possession (**credential_pop**) MUST be a JWT that MUST - **Description** - **Reference** * - **iss** - - Thumbprint of the JWK in the ``cnf`` parameter of the Wallet Instance Attestation. + - Thumbprint of the JWK in the ``cnf`` parameter of the Wallet Attestation. - :rfc:`9126` and :rfc:`7519`. * - **aud** - It MUST be set to the Issuer endpoint at which the JWT is used. diff --git a/images/cross_device_auth_seq_diagram.svg b/images/cross_device_auth_seq_diagram.svg index f495b1d91..b685c1684 100644 --- a/images/cross_device_auth_seq_diagram.svg +++ b/images/cross_device_auth_seq_diagram.svg @@ -1 +1 @@ -User's DevicesUserUserWallet InstanceWallet Instanceuser-agentuser-agentRelying PartyRelying Party1Web Service navigation2Request Protected ResourceUser Authentication (Presentation Phase)3Create astatevaluebound to user-agent cookie4Create request_uri resource5QRCode OR HTTP Redirect (302) with client_id, request_uri, stateCross Device only6Show the QRCode page7Open the Wallet Instance app, local authentication8Scan QR Code9Extractclient_idrequest_uriand statefrom the QR Code10evaluates trust with the client_id11requests the signed request object from the request_uri endpoint12signed request objectalt[if request_uri_method is set with POST]13provides Wallet metadata to the request_uri endpoint14evaluates the Wallet tecnical capabilities15updated signed request object16evaluates Relying Party Metadata and policies17Verify signature of the signed Request Object18Validate Requested VP(s)19Request for consent20Confirmed21POST Authorization Responsewith vp_token22Evaluate the Verifiable Presentation token23Validate the Wallet Attestation.Attest the Wallet Provideris part of the Federationand the Wallet Instance is not revoked.24Attest Credential Issuer Trustand Validate JWT Signature25Process the credentialProcess the credential:Check Holder Key Binding and Proof of Possession:- using the public key bound in\n the Credential to verify the VP token. Then Extract the disclosed attributes: \n Check if all the required data are available26Update the User session (cookie updated)27HTTP/1.1 200 OK{"redirect_uri": https url with response_code }Same Device only28Use the redirect_uriCross Device only29QRCode JS: Check authentication state (HTTP request with cookie)30Authentication state given with HTTP codes, untill expired or successful \ No newline at end of file +User's DevicesUserUserWallet InstanceWallet Instanceuser-agentuser-agentRelying PartyRelying Party1Web Service navigation2Request Protected ResourcePresentation Phase3Create astatevaluebound to user-agent cookie4Create request_uri resource5QRCode OR HTTP Redirect (302) withclient_id, request_uri, state, [request_uri_method] [client_id_scheme]Cross Device only6Show the QRCode page7Open the Wallet Instance app, local authentication8Scan QR Code9Extract the parameters from the QR Code10evaluates trust with the client_id [client_id_scheme]alt[if request_uri_method is set with POST]11provides Wallet metadata to the request_uri endpoint12evaluates the Wallet tecnical capabilities[if request_uri_method is set with GET or not present]13requests the signed request object from the request_uri endpoint14signed request object15evaluates Relying Party Metadata and policies16Verify signature of the signed Request Object17Validate requested VP(s)18Request for consent19Confirmed20POST Authorization Responsewith vp_token, state, presentation_submission21Evaluate the Verifiable Presentation token22Validate the Wallet Attestation.Attest the Wallet Provideris part of the Federationand the Wallet Instance is not revoked.23Attest Credential Issuer Trustand Validate JWT Signature24Process the credentialProcess the credential:Check Holder Key Binding and Proof of Possession:- using the public key bound in the Credential to verify the VP token. Then extract the disclosed attributes: check if all the required data are available25Update the User session (cookie updated)26HTTP/1.1 200 OK{"redirect_uri": https url with response_code }Same Device only27Use the redirect_uriCross Device only28QRCode JS: Check authentication state (HTTP request with cookie)29Authentication state given with HTTP codes, untill expired or successful \ No newline at end of file From 8cf29c93955e1db1d72fd8a77efbbf1c4ef196de Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Tue, 5 Mar 2024 14:46:21 +0100 Subject: [PATCH 5/6] chore README.md release summary --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f61673da8..211634495 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,9 @@ Preview of other branches can be navigated by adding the branch name in the webp Released versions can be navigated by adding the tag in the webpath leaded by a _v_, as follows: - - https://italia.github.io/eudi-wallet-it-docs/v0.4.1/en + - [https://italia.github.io/eudi-wallet-it-docs/v0.6.0/en/](https://italia.github.io/eudi-wallet-it-docs/v0.6.0/en/) + - [https://italia.github.io/eudi-wallet-it-docs/v0.5.0/en/](https://italia.github.io/eudi-wallet-it-docs/v0.5.0/en/) + - [https://italia.github.io/eudi-wallet-it-docs/v0.4.1/en/](https://italia.github.io/eudi-wallet-it-docs/v0.4.1/en/) ## Documentation From df948503e22cbf949530a07b6cee0e83e6901613 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Thu, 7 Mar 2024 12:13:50 +0100 Subject: [PATCH 6/6] fix: requirements list in trust.rst --- docs/en/trust.rst | 58 +++++++++++++++++++++++------------------------ 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/docs/en/trust.rst b/docs/en/trust.rst index 6643f7b55..1a1a9ef59 100644 --- a/docs/en/trust.rst +++ b/docs/en/trust.rst @@ -24,35 +24,35 @@ Functional Requirements This section includes the requirements necessary for the successful implementation and operation of the infrastructure of trust. -[FR #1] - **Federation Trust Establishment**: the system must be able to establish trust between different entities (Credential Issuers, Relying Parties, etc.) within a federation, using cryptographic signatures for secure information exchange about the participants in the ecosystem. -[FR #2] - **Entity Authentication**: the system must implement mechanisms for authenticating entities within the federation, ensuring compliance with the shared rules. -[FR #3] - **Signature Validation**: the system must support the creation, verification, and validation of electronic signatures and provide standard and secure mechanisms to obtain the public keys required for the signature validation. -[FR #4] - **Time Stamping**: the signed artifacts must contain time stamps to ensure the integrity and non-repudiation of transactions over time, thanks to the interfaces, services, storage model and approaches defined within the federation. -[FR #5] - **Certificate Validation**: the system requires confidential transmission, secured via TLS over HTTP, and validation of certificates for website authentication, ensuring they meet eIDAS criteria. -[FR #6] - **Interoperability and Standards Compliance**: ensure interoperability between federation members by adhering to technical standards, facilitating cross-border electronic transactions. -[FR #7] - **Data Protection and Privacy**: implement data protection measures in compliance with GDPR and eIDAS regulations, ensuring the privacy and security of personal data processed within the federation. -[FR #8] - **User Consent and Control**: design mechanisms for obtaining and managing user consent, empowering users with control over their personal information. -[FR #9] - **Audit and Logging**: the system must minimize data, anonymize if possible, define retention periods, secure access, and storage encryption. This protects privacy while enabling security and accountability. -[FR #10] - **Dispute Resolution and Liability**: establish clear procedures for dispute resolution and define liability among federation members, in accordance with eIDAS provisions. -[FR #11] - **Accessibility**: ensure that the system is accessible to all users, including those with disabilities, aligning with eIDAS and local accessibility standards. -[FR #12] - **Emergency and Revocation Services**: implement mechanisms for the immediate revocation of electronic identification means and participants in case of security breaches or other emergencies. -[FR #13] - **Scalable Trust Infrastructure**: the system must support scalable trust establishment mechanisms, leveraging approaches and technical solutions that complement delegation transitive approaches to efficiently manage trust relationships as the federation grows, removing central registries that might technically or administratively fail. -[FR #14] - **Efficient Storage Scalability**: implement a storage solution that scales horizontally to accommodate increasing data volumes while minimizing central storage and administrative costs. The system should enable members to independently store and present historical trust attestations and signed artifacts during dispute resolutions, with the federation infrastructure maintaining only a registry of historical keys to validate the historical data, stored and provided by the participants. -[FR #15] - **Verifiable Attestation (Trust Mark)**: incorporate a mechanism for issuing and verifying verifiable attestations that serve as proof of compliance with specific profiles or standards. This allows entities within the federation to demonstrate adherence to agreed-upon security, privacy, and operational standards. -[FR #16] - **Dynamic Policy Language**: develop and implement a dynamic, extensible policy language that allows for the creation and modification of federation policies in response to evolving requirements, technological advancements, and regulatory changes. This policy language should support the specification of rules governing entity behavior, metadata handling, and trust validation within the federation. -[FR #17] - **Automated Policy Enforcement**: the system must automatically enforce federation policies as defined by policy language and verifiable attestations, ensuring that all operations and transactions comply with current rules and standards. -[FR #18] - **Decentralized Dispute Resolution Mechanism**: design a decentralized mechanism for dispute resolution that allows federation members to independently verify historical trust establishment and signed artifacts, reducing reliance on central authorities and streamlining the resolution process. -[FR #19] - **Adaptive Load Management**: implement adaptive load management strategies to ensure the system remains responsive and efficient under varying loads, particularly during peak usage times or when processing complex tasks. -[FR #20] - **Cross-Federation Interoperability**: ensure the system is capable of interoperating with other federations or trust frameworks, facilitating cross-federation transactions and trust establishment without compromising security or compliance. -[FR #21] - **Future-Proof Cryptography**: the system should employ a flexible cryptographic framework that can be updated in response to new threats or advancements in cryptographic research, ensuring long-term security and integrity of federation operations. -[FR #23] - **Autonomous Accreditation Bodies**: the system must facilitate the integration of autonomous accreditation bodies that operate in compliance with federation rules. These bodies are tasked with evaluating and accrediting entities within the federation, according to the pre-established rules and their compliance that must be periodically asserted. -[FR #24] - **Compliance Evaluation for Federation Entity Candidates**: accreditation bodies must evaluate the compliance of candidate entities against federation standards before their registration in the federation. -[FR #25] - **Periodic Auditing of Accreditation Bodies and Entities**: implement mechanisms for the periodic auditing and monitoring of the compliance status of both accreditation bodies and their accredited entities. This ensures ongoing adherence to federation standards and policies. -[FR #26] - **Certification of Compliance for Personal Devices**: trusted bodies, in the form of federation entities, should issue certifications of compliance and provide signed proof of such compliance for the hardware of personal devices used within the federation. These certifications should be attested and periodically renewed to ensure the devices meet current security standards. -[FR #27] - **Certification of Compliance for Cryptographic Devices**: similar to personal devices, personal cryptographic devices used within the federation must also receive certifications of compliance and signed proof thereof from trusted bodies. These certifications should be subject to periodic renewal to reflect the latest security and compliance standards. -[FR #28] - **Transparent Compliance Reporting**: develop a system for transparent reporting and publication of compliance statuses, audit results, and certification renewals for all federation entities. This transparency fosters trust within the federation and with external stakeholders. -[FR #29] - **Automated Compliance Monitoring**: the system should include automated tools for monitoring the compliance of entities with federation standards. This automation aids in the early detection of potential compliance issues. -[FR #30] - **Secure Protocol Capabilities Binding**: the secure protocol must enable the exchange of protocol-specific capabilities data as cryptographically-bound metadata attached to a specific identity. This metadata should define the technical capabilities associated with the identity, ensuring verifiable proof and tamper-proof association for robust trust establishment and access control. +- [FR #1] - **Federation Trust Establishment**: the system must be able to establish trust between different entities (Credential Issuers, Relying Parties, etc.) within a federation, using cryptographic signatures for secure information exchange about the participants in the ecosystem. +- [FR #2] - **Entity Authentication**: the system must implement mechanisms for authenticating entities within the federation, ensuring compliance with the shared rules. +- [FR #3] - **Signature Validation**: the system must support the creation, verification, and validation of electronic signatures and provide standard and secure mechanisms to obtain the public keys required for the signature validation. +- [FR #4] - **Time Stamping**: the signed artifacts must contain time stamps to ensure the integrity and non-repudiation of transactions over time, thanks to the interfaces, services, storage model and approaches defined within the federation. +- [FR #5] - **Certificate Validation**: the system requires confidential transmission, secured via TLS over HTTP, and validation of certificates for website authentication, ensuring they meet eIDAS criteria. +- [FR #6] - **Interoperability and Standards Compliance**: ensure interoperability between federation members by adhering to technical standards, facilitating cross-border electronic transactions. +- [FR #7] - **Data Protection and Privacy**: implement data protection measures in compliance with GDPR and eIDAS regulations, ensuring the privacy and security of personal data processed within the federation. +- [FR #8] - **User Consent and Control**: design mechanisms for obtaining and managing user consent, empowering users with control over their personal information. +- [FR #9] - **Audit and Logging**: the system must minimize data, anonymize if possible, define retention periods, secure access, and storage encryption. This protects privacy while enabling security and accountability. +- [FR #10] - **Dispute Resolution and Liability**: establish clear procedures for dispute resolution and define liability among federation members, in accordance with eIDAS provisions. +- [FR #11] - **Accessibility**: ensure that the system is accessible to all users, including those with disabilities, aligning with eIDAS and local accessibility standards. +- [FR #12] - **Emergency and Revocation Services**: implement mechanisms for the immediate revocation of electronic identification means and participants in case of security breaches or other emergencies. +- [FR #13] - **Scalable Trust Infrastructure**: the system must support scalable trust establishment mechanisms, leveraging approaches and technical solutions that complement delegation transitive approaches to efficiently manage trust relationships as the federation grows, removing central registries that might technically or administratively fail. +- [FR #14] - **Efficient Storage Scalability**: implement a storage solution that scales horizontally to accommodate increasing data volumes while minimizing central storage and administrative costs. The system should enable members to independently store and present historical trust attestations and signed artifacts during dispute resolutions, with the federation infrastructure maintaining only a registry of historical keys to validate the historical data, stored and provided by the participants. +- [FR #15] - **Verifiable Attestation (Trust Mark)**: incorporate a mechanism for issuing and verifying verifiable attestations that serve as proof of compliance with specific profiles or standards. This allows entities within the federation to demonstrate adherence to agreed-upon security, privacy, and operational standards. +- [FR #16] - **Dynamic Policy Language**: develop and implement a dynamic, extensible policy language that allows for the creation and modification of federation policies in response to evolving requirements, technological advancements, and regulatory changes. This policy language should support the specification of rules governing entity behavior, metadata handling, and trust validation within the federation. +- [FR #17] - **Automated Policy Enforcement**: the system must automatically enforce federation policies as defined by policy language and verifiable attestations, ensuring that all operations and transactions comply with current rules and standards. +- [FR #18] - **Decentralized Dispute Resolution Mechanism**: design a decentralized mechanism for dispute resolution that allows federation members to independently verify historical trust establishment and signed artifacts, reducing reliance on central authorities and streamlining the resolution process. +- [FR #19] - **Adaptive Load Management**: implement adaptive load management strategies to ensure the system remains responsive and efficient under varying loads, particularly during peak usage times or when processing complex tasks. +- [FR #20] - **Cross-Federation Interoperability**: ensure the system is capable of interoperating with other federations or trust frameworks, facilitating cross-federation transactions and trust establishment without compromising security or compliance. +- [FR #21] - **Future-Proof Cryptography**: the system should employ a flexible cryptographic framework that can be updated in response to new threats or advancements in cryptographic research, ensuring long-term security and integrity of federation operations. +- [FR #23] - **Autonomous Accreditation Bodies**: the system must facilitate the integration of autonomous accreditation bodies that operate in compliance with federation rules. These bodies are tasked with evaluating and accrediting entities within the federation, according to the pre-established rules and their compliance that must be periodically asserted. +- [FR #24] - **Compliance Evaluation for Federation Entity Candidates**: accreditation bodies must evaluate the compliance of candidate entities against federation standards before their registration in the federation. +- [FR #25] - **Periodic Auditing of Accreditation Bodies and Entities**: implement mechanisms for the periodic auditing and monitoring of the compliance status of both accreditation bodies and their accredited entities. This ensures ongoing adherence to federation standards and policies. +- [FR #26] - **Certification of Compliance for Personal Devices**: trusted bodies, in the form of federation entities, should issue certifications of compliance and provide signed proof of such compliance for the hardware of personal devices used within the federation. These certifications should be attested and periodically renewed to ensure the devices meet current security standards. +- [FR #27] - **Certification of Compliance for Cryptographic Devices**: similar to personal devices, personal cryptographic devices used within the federation must also receive certifications of compliance and signed proof thereof from trusted bodies. These certifications should be subject to periodic renewal to reflect the latest security and compliance standards. +- [FR #28] - **Transparent Compliance Reporting**: develop a system for transparent reporting and publication of compliance statuses, audit results, and certification renewals for all federation entities. This transparency fosters trust within the federation and with external stakeholders. +- [FR #29] - **Automated Compliance Monitoring**: the system should include automated tools for monitoring the compliance of entities with federation standards. This automation aids in the early detection of potential compliance issues. +- [FR #30] - **Secure Protocol Capabilities Binding**: the secure protocol must enable the exchange of protocol-specific capabilities data as cryptographically-bound metadata attached to a specific identity. This metadata should define the technical capabilities associated with the identity, ensuring verifiable proof and tamper-proof association for robust trust establishment and access control.