From f442117223cbbb913d4d36788e484a26d1907c9e Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 25 Nov 2024 15:37:16 +0100 Subject: [PATCH 01/10] breaking change: OpenID4VP alignments to Draft 22 --- docs/common/common_definitions.rst | 1 - docs/common/standards.rst | 2 - docs/en/pid-eaa-data-model.rst | 2 +- docs/en/pid-eaa-entity-configuration.rst | 14 +- docs/en/pid-eaa-issuance.rst | 12 +- .../en/relying-party-entity-configuration.rst | 20 +-- docs/en/remote-flow.rst | 148 +++++++++--------- docs/en/trust.rst | 8 +- docs/en/wallet-attestation.rst | 6 +- examples/credential-request.json | 2 +- examples/ec-eaa.json | 92 +---------- examples/ec-rp.json | 94 +---------- examples/pid-sd-jwt-example-header.json | 2 +- examples/presentation-definition.json | 2 +- examples/qeaa-sd-jwt-example-header.json | 2 +- 15 files changed, 117 insertions(+), 290 deletions(-) diff --git a/docs/common/common_definitions.rst b/docs/common/common_definitions.rst index f6380a2bc..a83a7f127 100644 --- a/docs/common/common_definitions.rst +++ b/docs/common/common_definitions.rst @@ -61,7 +61,6 @@ .. _OAUTH2: https://www.rfc-editor.org/rfc/rfc6749 .. _OPENID4VC-HAIP: https://openid.net/specs/openid4vc-high-assurance-interoperability-profile-sd-jwt-vc-1_0.html .. _OAUTH-STATUS-ASSERTION: https://datatracker.ietf.org/doc/draft-demarco-oauth-status-assertions/02/ -.. _OAUTH-V2-JARM-04: https://openid.net/specs/oauth-v2-jarm-04.html .. _OIDC: https://openid.net/specs/openid-connect-core-1_0.html .. _OAUTH-MULT-RESP-TYPE: https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html .. _OAUTH-ATTESTATION-CLIENT-AUTH: https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/03/ diff --git a/docs/common/standards.rst b/docs/common/standards.rst index 5092837b7..ba01d29c8 100644 --- a/docs/common/standards.rst +++ b/docs/common/standards.rst @@ -63,8 +63,6 @@ Technical References - De Marco, G., Steele, O., Marino, F., "OpenID4VC High Assurance Interoperability Profile with SD-JWT VC", June 2024, Draft 2. * - `OAUTH-ATTESTATION-CLIENT-AUTH`_ - Looker, T., Bastian, P., "OAuth 2.0 Attestation-Based Client Authentication", May 2024, Draft 3. - * - `OAUTH-V2-JARM-04`_ - - Lodderstedt, T., Campbell, B., "JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)". * - `OAUTH-MULT-RESP-TYPE`_ - de Medeiros, B., Scurtescu, M., Tarjan, P., Jones, M., "OAuth 2.0 Multiple Response Type Encoding Practices", February 2014. * - ISO18013-5 diff --git a/docs/en/pid-eaa-data-model.rst b/docs/en/pid-eaa-data-model.rst index bfdbce2cc..dc45b8976 100644 --- a/docs/en/pid-eaa-data-model.rst +++ b/docs/en/pid-eaa-data-model.rst @@ -71,7 +71,7 @@ The JOSE header contains the following mandatory parameters: - **Description** - **Reference** * - **typ** - - REQUIRED. It MUST be set to ``vc+sd-jwt`` as defined in `SD-JWT-VC`_. + - REQUIRED. It MUST be set to ``dc+sd-jwt`` as defined in `SD-JWT-VC`_. - :rfc:`7515` Section 4.1.9. * - **alg** - REQUIRED. Signature Algorithm. diff --git a/docs/en/pid-eaa-entity-configuration.rst b/docs/en/pid-eaa-entity-configuration.rst index b50e10b78..304f08ef3 100644 --- a/docs/en/pid-eaa-entity-configuration.rst +++ b/docs/en/pid-eaa-entity-configuration.rst @@ -13,7 +13,7 @@ The PID/(Q)EAA Providers MUST provide the following metadata types: - `oauth_authorization_server` - `openid_credential_issuer` -In cases where the (Q)EAA Providers authenticate Users using their Wallet Instance, then the metadata for *wallet_relying_party* MUST be provided in addition to the metadata above. In case a national eID scheme is used by the PID/(Q)EAA Providers for the User authentication, they MAY include a metadata for *openid_relying_party* within their Entity Configuration. The *openid_relying_party* metadata MUST be compliant with the current version of `SPID/CIE id OIDC Technical Specification `_. +In cases where the (Q)EAA Providers authenticate Users using their Wallet Instance, then the metadata for *openid_credential_verifier* MUST be provided in addition to the metadata above. In case a national eID scheme is used by the PID/(Q)EAA Providers for the User authentication, they MAY include a metadata for *openid_relying_party* within their Entity Configuration. The *openid_relying_party* metadata MUST be compliant with the current version of `SPID/CIE id OIDC Technical Specification `_. Metadata for federation_entity @@ -54,9 +54,9 @@ The *oauth_authorization_server* metadata MUST contain the following parameters. * - **scopes_supported** - JSON array containing a list of the supported *scope* values. See :rfc:`8414#section-2`. * - **response_modes_supported** - - JSON array containing a list of the supported "response_mode" values, as specified in `OAuth 2.0 Multiple Response Type Encoding Practices `_. The supported values MAY be *query* and *form_post.jwt* (see `[oauth-v2-jarm-03] `__). + - JSON array containing a list of the supported "response_mode" values, as specified in `OAuth 2.0 Multiple Response Type Encoding Practices `_. The supported values MAY be *query* and *form_post.jwt* (see `JARM`_). * - **authorization_signing_alg_values_supported** - - JSON array containing a list of the :rfc:`7515` supported signing algorithms (*alg* values). The values MUST be set according to Section :ref:`Cryptographic algorithms`. See Section 4 of `[oauth-v2-jarm-03] `__. + - JSON array containing a list of the :rfc:`7515` supported signing algorithms (*alg* values). The values MUST be set according to Section :ref:`Cryptographic algorithms`. See Section 4 of `JARM`_. * - **grant_types_supported** - JSON array containing a list of the supported grant type values. The authorization server MUST support *authorization_code*. * - **token_endpoint_auth_methods_supported** @@ -100,7 +100,7 @@ The *openid_credential_issuer* metadata MUST contain the following claims. * - **credential_configurations_supported** - JSON object that outlines the details of the Credential supported by the PID/(Q)EAA Provider. It includes a list of name/value pairs, where each name uniquely identifies a specific supported Credential. This identifier is utilized to inform the Wallet Instance which Credential can be provided by the PID/(Q)EAA Provider. The associated value within the object MUST contain metadata specific to that Credential, as defined following. See `OpenID4VCI`_ Sections 11.2.3 and A.3.2. - - **format**: String identifying the format of this Credential. The PID/(Q)EAA MUST support the value string "*vc+sd-jwt*". See `OpenID4VCI`_ Section A.3.1. + - **format**: String identifying the format of this Credential. The PID/(Q)EAA MUST support the value string "*dc+sd-jwt*". See `OpenID4VCI`_ Section A.3.1. - **scope**: JSON String identifying the supported *scope* value. The Wallet Instance MUST use this value in the Pushed Authorization Request. Scope values MUST be the entire set or a subset of the *scope* values in the *scopes_supported* parameter of the Authorization Server. [See `OpenID4VCI`_ Section 11.2.3]. - **cryptographic_binding_methods_supported**: JSON Array of case sensitive strings that identify the representation of the cryptographic key material that the issued Credential is bound to. The PID/(Q)EAA Provider MUST support the value "*jwk*". - **credential_signing_alg_values_supported**: JSON Array of case sensitive strings that identify the algorithms that the PID/(Q)EAA Provider MUST support to sign the issued Credential. See Section :ref:`Cryptographic algorithms` for more details. @@ -123,10 +123,10 @@ The *openid_credential_issuer* metadata MUST contain the following claims. -Metadata for wallet_relying_party +Metadata for openid_credential_verifier ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The *wallet_relying_party* metadata MUST contain the parameters as defined in Section :ref:`Metadata for wallet_relying_party`. +The *openid_credential_verifier* metadata MUST contain the parameters as defined in Section :ref:`Metadata for openid_credential_verifier`. Example of a (Q)EAA Provider Entity Configuration @@ -137,7 +137,7 @@ Below is a non-normative example of an Entity Configuration of a (Q)EAA Provider - `federation_entity` - `oauth_authorization_server` - `openid_credential_issuer` - - `wallet_relying_party` + - `openid_credential_verifier` .. literalinclude:: ../../examples/ec-eaa.json :language: JSON diff --git a/docs/en/pid-eaa-issuance.rst b/docs/en/pid-eaa-issuance.rst index ff6e17210..9d23e2430 100644 --- a/docs/en/pid-eaa-issuance.rst +++ b/docs/en/pid-eaa-issuance.rst @@ -80,7 +80,7 @@ The PID/(Q)EAA Issuance flow is based on [`OpenID4VCI`_] and the following main * **Pushed Authorization Requests** (PAR) [:rfc:`9126`], as recommended in Section 5 of [`OpenID4VCI`_]. * **Proof Key for Code Exchange** (PKCE) [:rfc:`7636`], as recommended in Section 5 of [`OpenID4VCI`_]. * **JWT Authorization Requests** (JAR) [:rfc:`9101`]. - * **JWT Authorization Response Modes** (JARM) [`OAUTH-V2-JARM-04`_]. + * **JWT Authorization Response Modes** (JARM) [`JARM`_]. * **Rich Authorization Requests** (RAR) [:rfc:`9396`]. * **OAuth 2.0 Attestation-Based Client Authentication** [`OAUTH-ATTESTATION-CLIENT-AUTH`_]. * **OpenID Federation 1.0** [`OID-FED`_]. @@ -504,8 +504,8 @@ The ``request`` JWT payload contained in the HTTP POST message is given with the - MUST be set to ``code``. - :rfc:`6749` * - **response_mode** - - It MUST be a string indicating the "*response_mode*", as specified in [`OAUTH-MULT-RESP-TYPE`_]. It MUST be one of the supported values (*response_modes_supported*) provided in the metadata of the PID/(Q)EAA Provider. It informs the PID/(Q)EAA Provider of the mechanism to be used for returning parameters from the Authorization Endpoint. In case of *HTTP 302 Redirect Response* the value MUST be *query*. In this mode, Authorization Response parameters are encoded in the query string added to the ``redirect_uri`` when redirecting back to the Wallet Instance. In case of *HTTP POST Response* the value MUST be *form_post.jwt* according to [`OAUTH-V2-JARM-04`_]. In this mode, Authorization Response parameters are specified into a JWT encoded as HTML form value that is auto-submitted in the user-agent, and thus is transmitted via the HTTP POST method to the Wallet Instance, with the result parameters being encoded in the body using the *application/x-www-form-urlencoded* format. The action attribute of the form MUST be the Redirection URI of the Wallet Instance. The method of the form attribute MUST be POST. - - See [`OAUTH-MULT-RESP-TYPE`_] and [`OAUTH-V2-JARM-04`_]. + - It MUST be a string indicating the "*response_mode*", as specified in [`OAUTH-MULT-RESP-TYPE`_]. It MUST be one of the supported values (*response_modes_supported*) provided in the metadata of the PID/(Q)EAA Provider. It informs the PID/(Q)EAA Provider of the mechanism to be used for returning parameters from the Authorization Endpoint. In case of *HTTP 302 Redirect Response* the value MUST be *query*. In this mode, Authorization Response parameters are encoded in the query string added to the ``redirect_uri`` when redirecting back to the Wallet Instance. In case of *HTTP POST Response* the value MUST be *form_post.jwt* according to [`JARM`_]. In this mode, Authorization Response parameters are specified into a JWT encoded as HTML form value that is auto-submitted in the user-agent, and thus is transmitted via the HTTP POST method to the Wallet Instance, with the result parameters being encoded in the body using the *application/x-www-form-urlencoded* format. The action attribute of the form MUST be the Redirection URI of the Wallet Instance. The method of the form attribute MUST be POST. + - See [`OAUTH-MULT-RESP-TYPE`_] and [`JARM`_]. * - **client_id** - It MUST be set as in the :ref:`Table of the HTTP parameters `. - See :ref:`Table of the HTTP parameters `. @@ -897,10 +897,10 @@ If the *DPoP proof* is invalid, the Credential endpoint returns an error respons - **Description** - **Reference** * - **format** - - Format of the Credential to be issued. This MUST be ``vc+sd-jwt`` or ``mso_mdoc``. + - Format of the Credential to be issued. This MUST be ``dc+sd-jwt`` or ``mso_mdoc``. - [`OpenID4VCI`_]. * - **vct** - - CONDITIONAL. REQUIRED only if the *format* identifier is ``vc+sd-jwt``. + - CONDITIONAL. REQUIRED only if the *format* identifier is ``dc+sd-jwt``. - See Annex A3.4. of [`OpenID4VCI`_] * - **doctype** - CONDITIONAL. REQUIRED only if the *format* identifier is ``mso_mdoc``. @@ -969,7 +969,7 @@ The Credential Response contains the following parameters: - **Description** - **Reference** * - **credential** - - CONDITIONAL. REQUIRED if ``lead_time`` is not present. String Containing the issued PID/(Q)EAA. If the requested format identifier is ``vc+sd-jwt`` then the ``credential`` parameter MUST NOT be re-encoded. If the requested format identifier is ``mso_mdoc`` then the ``credential`` parameter MUST be a base64url-encoded representation of the issued Credential. + - CONDITIONAL. REQUIRED if ``lead_time`` is not present. String Containing the issued PID/(Q)EAA. If the requested format identifier is ``dc+sd-jwt`` then the ``credential`` parameter MUST NOT be re-encoded. If the requested format identifier is ``mso_mdoc`` then the ``credential`` parameter MUST be a base64url-encoded representation of the issued Credential. - Section 7.3, Annex A2.5 and Annex A3.5 of [`OpenID4VCI`_]. * - **lead_time** - CONDITIONAL. REQUIRED if ``credential`` is not present. The amount of time (in seconds) required before making a new Credential Request. diff --git a/docs/en/relying-party-entity-configuration.rst b/docs/en/relying-party-entity-configuration.rst index 39bcf2d33..407edd56a 100644 --- a/docs/en/relying-party-entity-configuration.rst +++ b/docs/en/relying-party-entity-configuration.rst @@ -9,7 +9,7 @@ The Entity Configuration of Relying Parties MUST contain the parameters defined The Relying Parties MUST provide the following metadata types: - `federation_entity` - - `wallet_relying_party` + - `openid_credential_verifier` Metadata for federation_entity @@ -17,10 +17,10 @@ Metadata for federation_entity The *federation_entity* metadata MUST contain the claims as defined in Section :ref:`Metadata of federation_entity Leaves`. -Metadata for wallet_relying_party +Metadata for openid_credential_verifier ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The *wallet_relying_party* metadata MUST contain the following parameters. +The *openid_credential_verifier* metadata MUST contain the following parameters. .. list-table:: :widths: 20 60 @@ -39,16 +39,18 @@ The *wallet_relying_party* metadata MUST contain the following parameters. * - **response_uris_supported** - JSON Array of response URI strings to which the Wallet Instance MUST send the Authorization Response using an HTTP POST request as defined by the Response Mode ``direct_post`` and ``direct_post.jwt`` (see `OpenID4VP`_ Draft 20 Sections 6.2 and 6.3). * - **authorization_signed_response_alg** - - String representing the signing [:rfc:`7515`] *alg* algorithm that MUST be used for signing authorization responses. The algorithm *none* MUST NOT be used. See `[oauth-v2-jarm-03] `_ Section 3. + - String representing the signing [:rfc:`7515`] *alg* algorithm that MUST be used for signing authorization responses. The algorithm *none* MUST NOT be used. See `JARM`_. + * - **authorization_encrypted_response_alg** + - Algorithm used to encrypt the authorization response. It specifies to the Wallet Instance the asymmetric encryption algorithm. See `JARM`_. + * - **authorization_encrypted_response_enc** + - Encryption algorithm used for the authorization response. It specifies to the Wallet Instance the symmetric encryption algorithm. See `JARM`_. * - **vp_formats** - - JSON object defining the formats and proof types of Verifiable Presentations and Verifiable Credentials the RP supports. It consists of a list of name/value pairs, where each name uniquely identifies a supported type. The RP MUST support at least "*vc+sd-jwt*" according to `OPENID4VC-HAIP`_ Draft 00 Section 7.2.7. The value associated with each name/value pair MUST be a JSON object "**sd-jwt_alg_values**" that MUST contain a JSON array containing identifiers of cryptographic algorithms the RP supports for protection of a SD-JWT. The *alg* JOSE header (as defined in :rfc:`7515`) of the presented SD-JWT MUST match one of the array values. See also `OpenID4VP`_ Draft 20 Section 9.1. - * - **presentation_definitions_supported** - - JSON Array of supported *presentation_definition* objects that MUST be compliant to the syntax defined in Section 5 of `[DIF.PresentationExchange] `_ and Section 7.2.8 of `OPENID4VC-HAIP`_ Draft 00. For *presentation_definition* objects see also `OpenID4VP`_ Section 5.1. + - JSON object defining the formats and proof types of Verifiable Presentations and Verifiable Credentials the RP supports. It consists of a list of name/value pairs, where each name uniquely identifies a supported type. The RP MUST support at least "*dc+sd-jwt*". The value associated with each name/value pair MUST be a JSON object "**sd-jwt_alg_values**" that MUST contain a JSON array containing identifiers of cryptographic algorithms the RP supports for protection of a SD-JWT. The *alg* JOSE header (as defined in :rfc:`7515`) of the presented SD-JWT MUST match one of the array values. See also `OpenID4VP`_ Draft 20 Section 9.1. * - **jwks** - - JSON Web Key Set document, passed by value, containing the protocol specific keys for the Relying Party. See `[oauth-v2-jarm-03] `_ Section 3, `OID-FED`_ Draft 36 Section 5.2.1 and `JWK`_. + - JSON Web Key Set document, passed by value, containing the protocol specific keys for the Relying Party. See `JARM`_ Section 3, `OID-FED`_ Draft 36 Section 5.2.1 and `JWK`_. .. note:: - The claims **response_uris_supported** and **presentation_definitions_supported** are introduced in this Specification. + The claims **response_uris_supported** are introduced in this Specification. Example of a Relying Party Entity Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/en/remote-flow.rst b/docs/en/remote-flow.rst index 1511e0257..744b8a634 100644 --- a/docs/en/remote-flow.rst +++ b/docs/en/remote-flow.rst @@ -10,23 +10,23 @@ In this flow the Relying Party MUST provide the URL where the signed presentatio Depending on whether the User is using a mobile device or a workstation, the Relying Party MUST support the following remote flows: -* **Same Device**, the Relying Party MUST provide a HTTP redirect (302) location to the Wallet Instance; +* **Same Device**, the Relying Party MUST provide a HTTP location to the Wallet Instance using a redirect (302) or an HTML href in a web page; * **Cross Device**, the Relying Party MUST provide a QR Code which the User frames with the Wallet Instance. -Once the Wallet Instance establishes the trust with the Relying Party and evaluates the request, the User gives the consent for the disclosure of the Digital Credentials, in the form of a Verifiable Presentation. +Once the Wallet Instance establishes the trust with the Relying Party and evaluates the request, +the User gives the consent for the disclosure of the Digital Credentials, in the form of a Verifiable Presentation. A High-Level description of the remote flow, from the User's perspective, is given below: 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_method`` 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_method`` 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_method`` 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 identifier within the Request Object JWT header parameter to select the correct public key obtained within Trust Chain related to the RP; - 6. the Wallet Instance verifies that the ``client_id`` contained in the Request Object issuer (RP) matches with the one obtained at the step number 2 and with the ``sub`` parameter contained in the RP's Entity Configuration within the Trust Chain; - 7. 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; - 8. the Wallet Instance asks User disclosure and consent by showing the Relying Party's identity and the requested attributes; - 9. 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; - 10. the Wallet Instance informs the User about the successfull authentication with the Relying Party, the User continues the navigation. + 2. the Wallet Instance extracts from the payload the following parameters: ``client_id``, ``request_uri``, ``state``, ``request_uri_method``; + 3. If ``request_uri_method`` 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_method`` 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; + 4. the Wallet Instance verifies the signature of the signed Request Object, using the public key identified within the Request Object JWT header parameter to select the correct RP's public key to be used for the verify the signature; + 5. the Wallet Instance verifies that the ``client_id`` contained in the Request Object issuer (RP) matches with the one obtained at the step number 2 and with the ``sub`` parameter contained in the RP's Entity Configuration within the Trust Chain; + 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 by showing the Relying Party's identity and the requested attributes; + 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. @@ -52,15 +52,15 @@ The details of each step shown in the previous picture are described in the tabl * - **3**, **4**, - 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 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 provided with an ``href`` in an html page or a HTTP Redirect (302) response. + - 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`` 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 provided with an ``href`` in an html page or a HTTP Redirect (302) response. * - **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 Relying Party, the Wallet Instance request the signed Request Object using the HTTP method GET. + - When the Wallet Instance capabilities discovery is not supported by Relying Party, the Wallet Instance requests the signed Request Object using the HTTP method GET. * - **14** - - The RP issues the Request Object signin it using one of its cryptographic private keys, where their public parts have been published within its Entity Configuration (`metadata.wallet_relying_party.jwks`). The Wallet Instance obtains the signed Request Object. + - The RP issues the Request Object signin it using one of its cryptographic private keys, where their public parts have been published within its Entity Configuration (`metadata.openid_credential_verifier.jwks`). The Wallet Instance obtains the signed Request Object. * - **15**, **16**, **17** - The Request Object, in the form of signed JWT, 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** @@ -84,7 +84,7 @@ 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 for better interoperability. +provide to the Relying Party for interoperability. .. warning:: The Wallet Instance, when providing its technical capabilities to the @@ -114,7 +114,7 @@ A non-normative example of the HTTP request is represented below: "form_post.jwt" ], "vp_formats_supported": { - "vc+sd-jwt": { + "dc+sd-jwt": { "sd-jwt_alg_values": [ "ES256", "ES384" @@ -124,7 +124,8 @@ 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, + "client_id_schemes_supported": ["https"] } The response of the Relying Party is defined in the section below. @@ -149,18 +150,19 @@ response, containing the request URI, are described in the Table below. - REQUIRED. Unique identifier of the Relying Party. * - **request_uri** - 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. + - RECOMMENDED. 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``. - + +.. note:: + The state parameter in an OAuth request is optional, but it is highly recommended. It is primarily used to prevent Cross-Site Request Forgery (CSRF) attacks by including a unique and unpredictable value that the Relying Party can verify upon receiving the response. Additionally, it helps maintain state between the request and response, such as session information or other data the Relying Party needs after the authorization process. + 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=...&client_id_scheme=entity_id&request_uri_method=post + https://wallet-solution.digital-strategy.europa.eu/authorization?client_id=...&request_uri=...&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. @@ -173,7 +175,6 @@ 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 @@ -190,7 +191,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&client_id_scheme=entity_id&request_uri_method=post + 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&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. @@ -199,6 +200,8 @@ Below is represented a non-normative example of the QR Code raw payload: Device Flow Status Checks and Security -------------------------------------- +This specification introduces the Relying Party Presentation Request Status Endpoint for implementations that want to use it, as this endpoint is an internal feature for the security of the implementation and is not required for interoperability. + Be the flow Same Device or 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 or the href button pointing to the request URL. The JavaScript code makes the user-agent check the status endpoint using a polling strategy in seconds or a push strategy (eg: web socket). @@ -232,6 +235,9 @@ Below a non-normative example of the HTTP Request to the status endpoint, where When the status endpoint returns **200 OK**, it means that the User authentication is successful and the JavaScript code will use the returned location where the user-agent will be redirect to continue the navigation. +Even if an adversary were to steal the random value used in the request to the status endpoint, their user-agent would be rejected due to the missing cookie in the request. + + Request Object Details ---------------------- @@ -263,11 +269,34 @@ where a non-normative example in the form of decoded header and payload is shown } . { - "scope": "PersonIdentificationData WalletAttestation", - "client_id_scheme": "entity_id", "client_id": "https://relying-party.example.org", "response_mode": "direct_post.jwt", "response_type": "vp_token", + "dcql_query": { + "credentials": [ + { + "id": "perdonal id data", + "format": "dc+sd-jwt", + "meta": { + "vct_values": [ "https://pidprovider.example.org/v1.0/personidentificationdata" ] + }, + "claims": [ + {"path": ["given_name"]}, + {"path": ["family_name"]}, + {"path": ["tax_id_code", "personal_administrative_number"]} + ] + }, + { + "id": "wallet unit attestation", + "format": "jwt", + "claims": [ + {"path": ["iss"]}, + {"path": ["iat"]}, + {"path": ["cnf"]} + ] + } + ] + }, "response_uri": "https://relying-party.example.org/response_uri", "nonce": "2c128e4d-fc91-4cd3-86b8-18bdea0988cb", "state": "3be39b69-6ac1-41aa-921b-3e6c07ddcb03", @@ -303,14 +332,12 @@ The JWT 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]. - * - **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** - Unique Identifier of the Relying Party. * - **response_mode** - It MUST be set to ``direct_post.jwt``. + * - **dcql_query** + - Object representing a request for a presentation of one Credential, according to the DCQL query language defined in Section 6 of `OpenID4VP`_. * - **response_type** - It MUST be set to ``vp_token``. * - **response_uri** @@ -328,30 +355,19 @@ The JWT payload parameters are described herein: * - **request_uri_method** - 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:: - - Using the parameter ``scope`` requires that the Relying Party Metadata MUST contain the ``presentation_definition``, where a non-normative example of it is given below: - -.. literalinclude:: ../../examples/presentation-definition.json - :language: JSON - .. note:: The following parameters, even if defined in [OID4VP], are not mentioned in the previous non-normative example, since their usage is conditional and may change in future release of this documentation. - ``presentation_definition``: JSON object according to `Presentation Exchange `_. This parameter MUST not be present when ``presentation_definition_uri`` or ``scope`` are present. - ``presentation_definition_uri``: Not supported. String containing an HTTPS URL pointing to a resource where a Presentation Definition JSON object can be retrieved. This parameter MUST be present when ``presentation_definition`` parameter or a ``scope`` value representing a Presentation Definition is not present. - - ``client_metadata``: A JSON object containing the Relying Party metadata values. If the ``client_metadata`` parameter is present when ``client_id_scheme`` is ``entity_id``, the Wallet Instance MUST consider the client metadata obtained through the OpenID Federation Trust Chain. + - ``client_metadata``: A JSON object containing the Relying Party metadata values. If the ``client_metadata`` parameter is present, the Wallet Instance MUST ignore it and consider the client metadata obtained through the OpenID Federation Trust Chain. 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. +When the Relying Party encounters errors while issuing the Request Object from the ``request_uri`` endpoint, the error responses defined in `OpenID4VP`_, Section 7.5. (Error Response) are applicable. The following is an example of an error response from ``request_uri`` endpoint: @@ -382,11 +398,9 @@ There are cases where the Wallet Instance cannot validate the Request Object or 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. + The current OpenID4VP specification outlines various error responses that a Wallet Instance may return to the Relying Party (Verifier) in case of faulty requests. 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 @@ -410,31 +424,16 @@ Below a non-normative example of the request: response=eyJhbGciOiJFUzI1NiIs...9t2LQ -Below is a non-normative example of the decrypted payload of the JWT contained in the ``response``, before base64url encoding: +Below is a non-normative example of the decrypted payload of the JWT contained in the ``response``, before base64url encoding. +The `vp_token` parameter value corresponds to the format used when the DCQL query language is used in the presentation request. .. code-block:: { "state": "3be39b69-6ac1-41aa-921b-3e6c07ddcb03", - "vp_token": [ - "eyJhbGciOiJFUzI1NiIs...PT0iXX0", - $WalletAttestation-JWT - ], - "presentation_submission": { - "definition_id": "32f54163-7166-48f1-93d8-ff217bdb0653", - "id": "04a98be3-7fb0-4cf5-af9a-31579c8b0e7d", - "descriptor_map": [ - { - "id": "PersonIdentificationData", - "path": "$.vp_token[0]", - "format": "vc+sd-jwt" - }, - { - "id": "WalletAttestation", - "path": "$.vp_token[1]", - "format": "wallet-attestation+jwt" - } - ] + "vp_token": { + "personal id data": "eyJhbGciOiJFUzI1NiIs...PT0iXX0", + "wallet unit attestation": $WalletAttestation-JWT } } @@ -447,17 +446,17 @@ Where the following parameters are used: * - **Name** - **Description** * - **vp_token** - - JSON Array containing the Verifiable Presentation(s). There MUST be at least two signed presentations in this Array: + - There MUST be at least two signed presentations in this Array: - The requested Digital Credential (one or more, in format of SD-JWT VC) - 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, according to the `Presentation Exchange `_. This is expressed via elements in the ``descriptor_map`` array (Input Descriptor Mapping Objects) that contain a field called ``path``, which MUST have the value $ (top level root path) when only one Verifiable Presentation is contained in the VP Token, and MUST have the value $[n] (indexed path from root) when there are multiple Verifiable Presentations, where ``n`` is the index to select. The Relying Party receiving the `presentation_submission` descriptor therefore is able to use the correct method to decode each credential data format provided within the ``vp_token``. - * - **state** - - Unique identifier provided by the Relying Party within the Authorization Request. + + When `presentation_definition` is used, the ``vp_token`` value is a JSON Array containing the Verifiable Presentation(s) and the `presentation_submission` MUST be also present within the reponse. + When the DCQL query language is used, the ``vp_token`` format is a JSON Object which keys corresponds to the requested credential ids in the ``dcql_query`` used in the request, and the values to each presented Digital Credential. -The items contained in the ``vp_token`` array are Verifiable Presentations of Credentials. + * - **state** + - Unique identifier provided by the Relying Party within the Authorization Request. SD-JWT Presentation @@ -559,7 +558,8 @@ When the Wallet sends a response using ``direct_post.jwt`` to the Relying Party, Redirect 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. +When the Relying Party provides the redirect URI, the Wallet Instance MUST redirect the user-agent to the location defined in the 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 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. @@ -575,7 +575,7 @@ 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 Instance or the user-agent to redirect the User to the Relying Party in order to complete the process. The value can be added as a path component, as a fragment or as a parameter to the URL according to Section 6.2 of `OpenID4VP`_. 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 a specific RP's endpoint in order to complete the process. The value can be added as a path component, as a fragment or as a parameter to the URL according to Section 6.2 of `OpenID4VP`_. The specific entity that performs this action depends on whether the flow is Same device or Cross device. Redirect URI Errors ------------------- diff --git a/docs/en/trust.rst b/docs/en/trust.rst index e591b33bf..298eb94dd 100644 --- a/docs/en/trust.rst +++ b/docs/en/trust.rst @@ -420,7 +420,7 @@ giving the references of the metadata protocol for each of these. - `OPENID4VCI`_ * - Relying Party - Relying Party - - ``federation_entity``, ``wallet_relying_party`` + - ``federation_entity``, ``openid_credential_verifier`` - `OID-FED`_, `OpenID4VP`_ @@ -437,7 +437,7 @@ giving the references of the metadata protocol for each of these. Other implementations may divide the Credential Issuer from the Authorization Server, when this happens the Credential Issuer metadata MUST contain the `authorization_servers` parameters, including the Authorization Server unique identifier. Furthermore, should there be a necessity for User Authentication by the Credential Issuer, it could be necessary to include the relevant metadata type, either ``openid_relying_party`` - or ``wallet_relying_party``. + or ``openid_credential_verifier``. Metadata of federation_entity Leaves @@ -507,7 +507,7 @@ Below there is a non-normative example of an Entity Statement issued by an Regis ] }, "metadata_policy": { - "wallet_relying_party": { + "openid_credential_verifier": { "scope": { "subset_of": [ "eu.europa.ec.eudiw.pid.1", @@ -517,7 +517,7 @@ Below there is a non-normative example of an Entity Statement issued by an Regis ] }, "vp_formats": { - "vc+sd-jwt": { + "dc+sd-jwt": { "sd-jwt_alg_values": [ "ES256", "ES384" diff --git a/docs/en/wallet-attestation.rst b/docs/en/wallet-attestation.rst index cbfe68be1..5f9b3ccdf 100644 --- a/docs/en/wallet-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -366,7 +366,7 @@ Below an non-normative example of the Wallet Attestation without encoding and si "form_post.jwt" ], "vp_formats_supported": { - "vc+sd-jwt": { + "dc+sd-jwt": { "sd-jwt_alg_values": [ "ES256", "ES384" @@ -545,7 +545,9 @@ The body of the Wallet Attestation JWT MUST contain: * - **presentation_definition_uri_supported** - Boolean value specifying whether the Wallet Instance supports the transfer of presentation_definition by reference. MUST be set to false. - - + * - **client_id_schemes_supported** + - Array of JSON Strings containing the values of the Client Identifier schemes that the Wallet supports. + - `OpenID4VP`_ Wallet Instance Lifecycle ----------------------------- diff --git a/examples/credential-request.json b/examples/credential-request.json index 0f3003a3f..74e005d95 100644 --- a/examples/credential-request.json +++ b/examples/credential-request.json @@ -1,5 +1,5 @@ { - "format": "vc+sd-jwt", + "format": "dc+sd-jwt", "vct": "EuropeanDisabilityCard", "proof": { "proof_type": "jwt", diff --git a/examples/ec-eaa.json b/examples/ec-eaa.json index babaf54a2..b6428dfdf 100644 --- a/examples/ec-eaa.json +++ b/examples/ec-eaa.json @@ -103,7 +103,7 @@ ], "credential_configurations_supported": { "EuropeanDisabilityCard": { - "format": "vc+sd-jwt", + "format": "dc+sd-jwt", "scope": "EuropeanDisabilityCard", "cryptographic_binding_methods_supported": [ "jwk" @@ -254,7 +254,7 @@ } }, "MDL": { - "format": "vc+sd-jwt", + "format": "dc+sd-jwt", "scope": "MDL", "cryptographic_binding_methods_supported": [ "jwk" @@ -469,7 +469,7 @@ ] } }, - "wallet_relying_party": { + "openid_credential_verifier": { "application_type": "web", "client_id": "https://eaa-provider.example.org", "client_name": "Organization Name", @@ -509,7 +509,7 @@ "A256GCM" ], "vp_formats": { - "vc+sd-jwt": { + "dc+sd-jwt": { "sd-jwt_alg_values": [ "ES256", "ES384", @@ -517,90 +517,6 @@ ] } }, - "presentation_definitions_supported": [ - { - "id": "d76c51b7-ea90-49bb-8368-6b3d194fc131", - "input_descriptors": [ - { - "id": "PersonIdentificationData", - "format": { - "vc+sd-jwt": { - "alg": [ - "ES256", - "ES384", - "ES512" - ] - }, - "constraints": { - "limit_disclosure": "required", - "fields": [ - { - "filter": { - "const": "PersonIdentificationData", - "type": "string" - }, - "path": [ - "$.vct" - ] - }, - { - "filter": { - "type": "object" - }, - "path": [ - "$.cnf.jwk" - ] - }, - { - "path": [ - "$.unique_id" - ] - }, - { - "path": [ - "$.tax_id_code" - ] - } - ] - } - } - }, - { - "id": "WalletAttestation", - "format": { - "jwt": { - "alg": [ - "ES256", - "ES384", - "ES512" - ] - }, - "constraints": { - "limit_disclosure": "required", - "fields": [ - { - "filter": { - "type": "string" - }, - "path": [ - "$.iss" - ] - }, - { - "filter": { - "type": "object" - }, - "path": [ - "$.cnf.jwk" - ] - } - ] - } - } - } - ] - } - ], "jwks": { "keys": [ { diff --git a/examples/ec-rp.json b/examples/ec-rp.json index 4f734e5e7..9b5b7cb37 100644 --- a/examples/ec-rp.json +++ b/examples/ec-rp.json @@ -29,7 +29,7 @@ "policy_uri": "https://relying-party.example.org/public/privacy_policy.html", "logo_uri": "https://relying-party.example.org/public/logo.svg" }, - "wallet_relying_party": { + "openid_credential_verifier": { "application_type": "web", "client_id": "https://relying-party.example.org", "client_name": "Organization Name", @@ -45,7 +45,7 @@ ], "authorization_signed_response_alg": "ES256", "vp_formats": { - "vc+sd-jwt": { + "dc+sd-jwt": { "sd-jwt_alg_values": [ "ES256", "ES384", @@ -53,96 +53,6 @@ ] } }, - "presentation_definitions_supported": [ - { - "id": "d76c51b7-ea90-49bb-8368-6b3d194fc131", - "input_descriptors": [ - { - "id": "PersonIdentificationData", - "name": "Person Identification Data", - "purpose": "User Authentication", - "format": { - "vc+sd-jwt": { - "alg": [ - "ES256", - "ES384", - "ES512" - ] - } - }, - "constraints": { - "limit_disclosure": "required", - "fields": [ - { - "filter": { - "const": "PersonIdentificationData", - "type": "string" - }, - "path": [ - "$.vct" - ] - }, - { - "filter": { - "type": "object" - }, - "path": [ - "$.cnf.jwk" - ] - }, - { - "path": [ - "$.unique_id" - ] - }, - { - "path": [ - "$.tax_id_code" - ] - } - ] - } - - }, - { - "id": "WalletAttestation", - "name": "Wallet Attestation", - "purpose": "Wallet Authentication", - "format": { - "jwt": { - "alg": [ - "ES256", - "ES384", - "ES512" - ] - } - }, - "constraints": { - "limit_disclosure": "required", - "fields": [ - { - "filter": { - "type": "string" - }, - "path": [ - "$.iss" - ] - }, - { - "filter": { - "type": "object" - }, - "path": [ - "$.cnf.jwk" - ] - } - ] - } - } - - ] - } - ], "jwks": { "keys": [ { diff --git a/examples/pid-sd-jwt-example-header.json b/examples/pid-sd-jwt-example-header.json index 949354abf..78992c5b7 100644 --- a/examples/pid-sd-jwt-example-header.json +++ b/examples/pid-sd-jwt-example-header.json @@ -1,5 +1,5 @@ { - "typ":"vc+sd-jwt", + "typ":"dc+sd-jwt", "alg":"ES256", "kid":"dB67gL7ck3TFiIAf7N6_7SHvqk0MDYMEQcoGGlkUAAw", "trust_chain" : [ diff --git a/examples/presentation-definition.json b/examples/presentation-definition.json index c7a649e2f..1aaf4ec0c 100644 --- a/examples/presentation-definition.json +++ b/examples/presentation-definition.json @@ -9,7 +9,7 @@ "group1" ], "format": { - "vc+sd-jwt": { + "dc+sd-jwt": { "alg": [ "ES256", "ES384", diff --git a/examples/qeaa-sd-jwt-example-header.json b/examples/qeaa-sd-jwt-example-header.json index 72dcc1dd5..6220431a8 100644 --- a/examples/qeaa-sd-jwt-example-header.json +++ b/examples/qeaa-sd-jwt-example-header.json @@ -1,5 +1,5 @@ { - "typ":"vc+sd-jwt", + "typ":"dc+sd-jwt", "alg":"ES256", "kid":"d126a6a856f7724560484fa9dc59d195", "trust_chain" : [ From 3990d389c84aaee2fc4bbe23cff71091c8c05e56 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 25 Nov 2024 15:39:21 +0100 Subject: [PATCH 02/10] fix: standards refs --- docs/common/standards.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/common/standards.rst b/docs/common/standards.rst index ba01d29c8..dbc4598e6 100644 --- a/docs/common/standards.rst +++ b/docs/common/standards.rst @@ -16,13 +16,13 @@ Technical References * - `EIDAS-ARF`_ - EUDI Wallet - Architecture and Reference Framework. * - `OpenID4VP`_ - - Terbu, O., Lodderstedt, T., Yasuda, K., Looker, T., "OpenID for Verifiable Presentations", November 2023, Draft 20. + - Terbu, O., Lodderstedt, T., Yasuda, K., Looker, T., "OpenID for Verifiable Presentations", October 2024, Draft 22. * - `PresentationExch`_ - Presentation Exchange 2.0 for Presentation Definition. * - :rfc:`2119` - Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels" BCP 14, RFC 2119, March 1997. * - :rfc:`2616` - - Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” RFC 2616, June 1999. + - Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1”, RFC 2616, June 1999. * - :rfc:`3339` - Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002. * - :rfc:`3986` @@ -71,8 +71,6 @@ Technical References - Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., "OpenID Connect Core 1.0 incorporating errata set 2", December 2023. * - `SD-JWT`_ - Fett, D., Yasuda, K., Campbell, B., "Selective Disclosure for JWTs (SD-JWT)". - * - `OAUTH-ATTESTATION-CLIENT-AUTH`_ - - Looker, T., Bastian, P., "OAuth 2.0 Attestation-Based Client Authentication". * - USASCII - American National Standards Institute, "Coded Character Set -- 7-bit American Standard Code for Information Interchange", 1986. * - `MODI`_ From 019a1e870cb5c817a7cb2b089e89ca03fa01d8c3 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 25 Nov 2024 15:46:16 +0100 Subject: [PATCH 03/10] Apply suggestions from code review --- docs/en/remote-flow.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/remote-flow.rst b/docs/en/remote-flow.rst index 744b8a634..b4482d8cf 100644 --- a/docs/en/remote-flow.rst +++ b/docs/en/remote-flow.rst @@ -337,7 +337,7 @@ The JWT payload parameters are described herein: * - **response_mode** - It MUST be set to ``direct_post.jwt``. * - **dcql_query** - - Object representing a request for a presentation of one Credential, according to the DCQL query language defined in Section 6 of `OpenID4VP`_. + - Object representing a request for a presentation of Credentials, according to the DCQL query language defined in Section 6 of `OpenID4VP`_. * - **response_type** - It MUST be set to ``vp_token``. * - **response_uri** @@ -451,7 +451,7 @@ Where the following parameters are used: - The requested Digital Credential (one or more, in format of SD-JWT VC) - The Wallet Attestation - When `presentation_definition` is used, the ``vp_token`` value is a JSON Array containing the Verifiable Presentation(s) and the `presentation_submission` MUST be also present within the reponse. + When `presentation_definition` is used, the ``vp_token`` value is a JSON Array containing the Verifiable Presentation(s) and the `presentation_submission` parameter MUST be also present within the response. When the DCQL query language is used, the ``vp_token`` format is a JSON Object which keys corresponds to the requested credential ids in the ``dcql_query`` used in the request, and the values to each presented Digital Credential. From c89ac5d34618a4f90e2ec9636b13a6a094d9101c Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 25 Nov 2024 17:05:23 +0100 Subject: [PATCH 04/10] fix: added redirect_uris in rp metadata and further indication againts endpoint mix-ups attacks --- docs/en/remote-flow.rst | 9 +++++++++ docs/en/security-privacy-considerations.rst | 3 +-- examples/ec-rp.json | 5 ++++- 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/en/remote-flow.rst b/docs/en/remote-flow.rst index b4482d8cf..679434f30 100644 --- a/docs/en/remote-flow.rst +++ b/docs/en/remote-flow.rst @@ -155,6 +155,9 @@ response, containing the request URI, are described in the Table below. * - **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``. +.. warning:: + For security reasons and to prevent endpoint mix-up attacks, the value contained in the ``request_uri`` parameter MUST be one of those attested by a trusted third party, such as those provided in the ``openid_credential_verifier`` metadata within the ``request_uris`` parameter, obtained from the Trust Chain about the Relying Party. + .. note:: The state parameter in an OAuth request is optional, but it is highly recommended. It is primarily used to prevent Cross-Site Request Forgery (CSRF) attacks by including a unique and unpredictable value that the Relying Party can verify upon receiving the response. Additionally, it helps maintain state between the request and response, such as session information or other data the Relying Party needs after the authorization process. @@ -355,6 +358,9 @@ The JWT payload parameters are described herein: * - **request_uri_method** - 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:: + For security reasons and to prevent endpoint mix-up attacks, the value contained in the ``response_uri`` parameter MUST be one of those attested by a trusted third party, such as those provided in the ``openid_credential_verifier`` metadata within the ``response_uris`` parameter, obtained from the Trust Chain about the Relying Party. + .. note:: The following parameters, even if defined in [OID4VP], are not mentioned in the previous non-normative example, since their usage is conditional and may change in future release of this documentation. @@ -577,6 +583,9 @@ The following is a non-normative example of the response from the Relying Party 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 a specific RP's endpoint in order to complete the process. The value can be added as a path component, as a fragment or as a parameter to the URL according to Section 6.2 of `OpenID4VP`_. The specific entity that performs this action depends on whether the flow is Same device or Cross device. +.. warning:: + For security reasons and to prevent endpoint mix-up attacks, the value contained in the ``redirect_uri`` parameter MUST be one of those attested by a trusted third party, such as those provided in the ``openid_credential_verifier`` metadata within the ``redirect_uris`` parameter, obtained from the Trust Chain about the Relying Party. + Redirect URI Errors ------------------- diff --git a/docs/en/security-privacy-considerations.rst b/docs/en/security-privacy-considerations.rst index 153d2a227..914547081 100644 --- a/docs/en/security-privacy-considerations.rst +++ b/docs/en/security-privacy-considerations.rst @@ -438,8 +438,7 @@ Additionally, the Authorization Response is encrypted with the Verifier's public further securing the transmission. Another endpoint to be validated is the **redirect_uri**, which is used to redirect the User back to the Verifier after the Credential presentation is complete. -In the IT-Wallet specification, the **redirect_uri** is registered and validated beforehand during the Verifier onboarding using OpenID Federation. During the presentation -phase, the Wallet must validate this value by verifying the trust with the Verifier according to the Section `Trust Evaluation Mechanism `_ +In the IT-Wallet specification, the **redirect_uri** is registered and validated beforehand during the Verifier onboarding using OpenID Federation. During the presentation phase, the Wallet must validate this value by verifying the trust with the Verifier according to the Section `Trust Evaluation Mechanism `_ In order to be sure that the **redirect_uri** is received from a legit Wallet and not from the attacker, the Verifier response endpoint upon the recipient of a valid diff --git a/examples/ec-rp.json b/examples/ec-rp.json index 9b5b7cb37..7a2ac6cca 100644 --- a/examples/ec-rp.json +++ b/examples/ec-rp.json @@ -40,9 +40,12 @@ "request_uris": [ "https://relying-party.example.org/request_uri" ], - "response_uris_supported": [ + "response_uris": [ "https://relying-party.example.org/response_uri" ], + "redirect_uris": [ + "https://relying-party.example.org/cb" + ], "authorization_signed_response_alg": "ES256", "vp_formats": { "dc+sd-jwt": { From 7ff7d770cd5647900ff8e5340a015932224a92df Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 25 Nov 2024 17:50:46 +0100 Subject: [PATCH 05/10] fix: request endpoint with wallet metadata and wallet nonce --- docs/en/remote-flow.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/en/remote-flow.rst b/docs/en/remote-flow.rst index 679434f30..5da3719ab 100644 --- a/docs/en/remote-flow.rst +++ b/docs/en/remote-flow.rst @@ -248,9 +248,17 @@ Below a non-normative example of HTTP request made by the Wallet Instance to the .. code-block:: javascript - GET /request_uri HTTP/1.1 - HOST: relying-party.example.org + POST /request HTTP/1.1 + Host: client.example.org + Content-Type: application/x-www-form-urlencoded + + wallet_metadata=%7B%22authorization_endpoint%22%3A%20%22eudiw%3A%22%2C%20%22response_types_supported%22%3A%20%5B%22vp_token%22%5D%2C%20%22response_modes_supported%22%3A%20%5B%22form_post.jwt%22%5D%2C%20%22vp_formats_supported%22%3A%20%7B%22dc%2Bsd-jwt%22%3A%20%7B%22sd-jwt_alg_values%22%3A%20%5B%22ES256%22%2C%20%22ES384%22%5D%7D%7D%2C%20%22request_object_signing_alg_values_supported%22%3A%20%5B%22ES256%22%5D%2C%20%22presentation_definition_uri_supported%22%3A%20false%7D + wallet_nonce=qPmxiNFCR3QTm19POc8u + +.. note:: + The ``wallet_nonce`` parameter is RECOMMENDED for Wallet Instances that wants to prevent reply of their http requests to the Relying Parties. + When present, the RTelying Party MUST evaluate it. Request URI Response -------------------- From 310278e0e21e3090485723c1cf2566cf5f571837 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 23 Dec 2024 13:06:06 +0100 Subject: [PATCH 06/10] Apply suggestions from Giada Co-authored-by: Giada Sciarretta --- docs/common/standards.rst | 2 +- docs/en/remote-flow.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/common/standards.rst b/docs/common/standards.rst index dbc4598e6..52f10059f 100644 --- a/docs/common/standards.rst +++ b/docs/common/standards.rst @@ -16,7 +16,7 @@ Technical References * - `EIDAS-ARF`_ - EUDI Wallet - Architecture and Reference Framework. * - `OpenID4VP`_ - - Terbu, O., Lodderstedt, T., Yasuda, K., Looker, T., "OpenID for Verifiable Presentations", October 2024, Draft 22. + - Terbu, O., Lodderstedt, T., Yasuda, K., Looker, T., "OpenID for Verifiable Presentations", December 2024, Draft 23. * - `PresentationExch`_ - Presentation Exchange 2.0 for Presentation Definition. * - :rfc:`2119` diff --git a/docs/en/remote-flow.rst b/docs/en/remote-flow.rst index 5da3719ab..4d440885f 100644 --- a/docs/en/remote-flow.rst +++ b/docs/en/remote-flow.rst @@ -241,7 +241,7 @@ When the status endpoint returns **200 OK**, it means that the User authenticati Even if an adversary were to steal the random value used in the request to the status endpoint, their user-agent would be rejected due to the missing cookie in the request. -Request Object Details +Request URI Request ---------------------- Below a non-normative example of HTTP request made by the Wallet Instance to the Relying Party. @@ -258,7 +258,7 @@ Below a non-normative example of HTTP request made by the Wallet Instance to the .. note:: The ``wallet_nonce`` parameter is RECOMMENDED for Wallet Instances that wants to prevent reply of their http requests to the Relying Parties. - When present, the RTelying Party MUST evaluate it. + When present, the Relying Party MUST evaluate it. Request URI Response -------------------- @@ -286,7 +286,7 @@ where a non-normative example in the form of decoded header and payload is shown "dcql_query": { "credentials": [ { - "id": "perdonal id data", + "id": "personal id data", "format": "dc+sd-jwt", "meta": { "vct_values": [ "https://pidprovider.example.org/v1.0/personidentificationdata" ] @@ -294,7 +294,7 @@ where a non-normative example in the form of decoded header and payload is shown "claims": [ {"path": ["given_name"]}, {"path": ["family_name"]}, - {"path": ["tax_id_code", "personal_administrative_number"]} + {"path": ["personal_administrative_number"]} ] }, { From fc78f2f927695b669894d9e6796ea8806428825e Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 23 Dec 2024 17:08:08 +0100 Subject: [PATCH 07/10] fix: request uri json object example --- docs/en/remote-flow.rst | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/en/remote-flow.rst b/docs/en/remote-flow.rst index 4d440885f..43666b35f 100644 --- a/docs/en/remote-flow.rst +++ b/docs/en/remote-flow.rst @@ -94,18 +94,14 @@ provide to the Relying Party for interoperability. If both the Relying Party and the Wallet Instance 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`. +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/x-www-form-urlencoded`. -A non-normative example of the HTTP request is represented below: +A non-normative example of the request object encoded in JSON, prior to being encoded in `application/x-www-form-urlencoded` by the Wallet for the Relying Party. -.. code:: http - - POST /request-uri HTTP/1.1 - HOST: relying-party.example.org - Content-Type: application/json +.. code:: json { + "wallet_metadata": { "authorization_endpoint": "https://wallet-solution.digital-strategy.europa.eu/authorization", "response_types_supported": [ "vp_token" @@ -125,7 +121,9 @@ A non-normative example of the HTTP request is represented below: "ES256" ], "presentation_definition_uri_supported": false, - "client_id_schemes_supported": ["https"] + "client_id_schemes_supported": ["https"], + }, + "wallet_nonce": "qPmxiNFCR3QTm19POc8u" } The response of the Relying Party is defined in the section below. From 03d7666af0d101246cf591ca66882463d25eeecf Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 23 Dec 2024 17:08:28 +0100 Subject: [PATCH 08/10] Apply suggestions from code review --- docs/en/relying-party-entity-configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/relying-party-entity-configuration.rst b/docs/en/relying-party-entity-configuration.rst index 407edd56a..107948600 100644 --- a/docs/en/relying-party-entity-configuration.rst +++ b/docs/en/relying-party-entity-configuration.rst @@ -50,7 +50,7 @@ The *openid_credential_verifier* metadata MUST contain the following parameters. - JSON Web Key Set document, passed by value, containing the protocol specific keys for the Relying Party. See `JARM`_ Section 3, `OID-FED`_ Draft 36 Section 5.2.1 and `JWK`_. .. note:: - The claims **response_uris_supported** are introduced in this Specification. + The claims **response_uris_supported** are introduced in this specification. Example of a Relying Party Entity Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 1c2a2c678156b3b6c27a72dc7bef8097995840c1 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 23 Dec 2024 17:08:46 +0100 Subject: [PATCH 09/10] Apply suggestions from code review Co-authored-by: Giada Sciarretta --- docs/en/remote-flow.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/en/remote-flow.rst b/docs/en/remote-flow.rst index 43666b35f..51b87c37f 100644 --- a/docs/en/remote-flow.rst +++ b/docs/en/remote-flow.rst @@ -250,15 +250,14 @@ Below a non-normative example of HTTP request made by the Wallet Instance to the Host: client.example.org Content-Type: application/x-www-form-urlencoded - wallet_metadata=%7B%22authorization_endpoint%22%3A%20%22eudiw%3A%22%2C%20%22response_types_supported%22%3A%20%5B%22vp_token%22%5D%2C%20%22response_modes_supported%22%3A%20%5B%22form_post.jwt%22%5D%2C%20%22vp_formats_supported%22%3A%20%7B%22dc%2Bsd-jwt%22%3A%20%7B%22sd-jwt_alg_values%22%3A%20%5B%22ES256%22%2C%20%22ES384%22%5D%7D%7D%2C%20%22request_object_signing_alg_values_supported%22%3A%20%5B%22ES256%22%5D%2C%20%22presentation_definition_uri_supported%22%3A%20false%7D - wallet_nonce=qPmxiNFCR3QTm19POc8u + wallet_metadata%3D%7B%22authorization_endpoint%22%3A%20%22eudiw%3A%22%2C%20%22response_types_supported%22%3A%20%5B%22vp_token%22%5D%2C%20%22response_modes_supported%22%3A%20%5B%22form_post.jwt%22%5D%2C%20%22vp_formats_supported%22%3A%20%7B%22dc%2Bsd-jwt%22%3A%20%7B%22sd-jwt_alg_values%22%3A%20%5B%22ES256%22%2C%20%22ES384%22%5D%7D%7D%2C%20%22request_object_signing_alg_values_supported%22%3A%20%5B%22ES256%22%5D%2C%20%22presentation_definition_uri_supported%22%3A%20false%7D%2C%20wallet_nonce%3DqPmxiNFCR3QTm19POc8u .. note:: The ``wallet_nonce`` parameter is RECOMMENDED for Wallet Instances that wants to prevent reply of their http requests to the Relying Parties. When present, the Relying Party MUST evaluate it. -Request URI Response +Request Object Details -------------------- The Relying Party issues the signed Request Object using the content type set to ``application/oauth-authz-req+jwt``, From c20cd08b3cbb55ed37a786cc2f9910ff2c44bb7e Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Mon, 23 Dec 2024 17:16:28 +0100 Subject: [PATCH 10/10] fix: ref to openid4vp section 7.3 --- docs/en/remote-flow.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/remote-flow.rst b/docs/en/remote-flow.rst index 51b87c37f..3de11d30e 100644 --- a/docs/en/remote-flow.rst +++ b/docs/en/remote-flow.rst @@ -417,7 +417,7 @@ Upon receiving an error response, the Wallet Instance SHOULD inform the User of Authorization Response Details ------------------------------ -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. +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 7.3, using the Relying Party public key. .. note:: **Why the response is encrypted?**