From cfe40bba6270bd433f43554f3b40543fae531e15 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Thu, 7 Dec 2023 16:16:11 +0100 Subject: [PATCH 01/11] fix: RSA removed, according to #164 --- docs/en/algorithms.rst | 18 +++++------------- docs/en/pid-eaa-data-model.rst | 27 +++++++++++++-------------- docs/en/pid-eaa-issuance.rst | 24 +++++++++++++----------- docs/en/relying-party-solution.rst | 25 ++++++++++++++----------- docs/en/trust.rst | 11 ++--------- 5 files changed, 47 insertions(+), 58 deletions(-) diff --git a/docs/en/algorithms.rst b/docs/en/algorithms.rst index 7fae0ee7f..2340749d0 100644 --- a/docs/en/algorithms.rst +++ b/docs/en/algorithms.rst @@ -14,10 +14,13 @@ The following algorithms MUST be supported: * - **Algorithm** - **Operations** - **References** - * - **RS256** + * - **ES256** + - Signature + - :rfc:`7518`. + * - **ES384** - Signature - :rfc:`7518`. - * - **RS512** + * - **ES256** - Signature - :rfc:`7518`. * - **RSA-OAEP** @@ -42,12 +45,6 @@ The following algorithms are RECOMMENDED to be supported: * - **Algorithm** - **Operations** - **References** - * - **ES256** - - Signature - - :rfc:`7518`. - * - **ES512** - - Signature - - :rfc:`7518`. * - **PS256** - Signature - :rfc:`7518`. @@ -89,10 +86,5 @@ The following algorithms MUST NOT be supported: - Signature - :rfc:`7518`. -.. warning:: - - The length of the RSA keys MUST be equal to or greater than 2048 bits. - A length of 4096 bits is RECOMMENDED. - diff --git a/docs/en/pid-eaa-data-model.rst b/docs/en/pid-eaa-data-model.rst index 8e7791f7b..de6bf9d36 100644 --- a/docs/en/pid-eaa-data-model.rst +++ b/docs/en/pid-eaa-data-model.rst @@ -253,7 +253,7 @@ The corresponding SD-JWT verson for PID is given by { "typ":"vc+sd-jwt", - "alg":"RS512", + "alg":"ES256", "kid":"dB67gL7ck3TFiIAf7N6_7SHvqk0MDYMEQcoGGlkUAAw", "trust_chain" : [ "NEhRdERpYnlHY3M5WldWTWZ2aUhm ...", @@ -273,12 +273,12 @@ The corresponding SD-JWT verson for PID is given by "status": "https://pidprovider.example.org/status", "cnf": { "jwk": { - "kty": "RSA", - "use": "sig", - "n": "1Ta-sE …", - "e": "AQAB", - "kid": "YhNFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs" - } + "crv": "P-256", + "kty": "EC", + "x": "qrJrj3Af_B57sbOIRrcBM7br7wOc8ynj7lHFPTeffUk", + "y": "1H0cWDyGgvU8w-kPKU_xycOCUNT2o0bwslIQtnPU6iM", + "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY" + } }, "type": "PersonIdentificationData", "verified_claims": { @@ -422,7 +422,7 @@ The corresponding SD-JWT for the previous data is represented as follow, as deco { "typ":"vc+sd-jwt", - "alg":"RS512", + "alg":"ES256", "kid":"d126a6a856f7724560484fa9dc59d195", "trust_chain" : [ "NEhRdERpYnlHY3M5WldWTWZ2aUhm ...", @@ -442,12 +442,11 @@ The corresponding SD-JWT for the previous data is represented as follow, as deco "status": "https://issuer.example.org/status", "cnf": { "jwk": { - "kty": "RSA", - "e": "AQAB", - "use": "sig", - "kid": "d126a6a856f7724560484fa9dc59d195", - "alg": "RS256", - "n": "oians5wYCWk4wFtEStVYcn_xOw9edKMNGH33_q6_pBI0XaTY7P3apUgjO0ivk5c1NQAVY6PZmcPQ8P1Y0cBAC9STRmzvTvDQcOocLhVy2ZlcXTu39oOGLNra8_LQsaMA386lO_qMW4-uY6DbGZY4vHkScvAC9FIZYDPafqWBEQUNV2QOFMH5VPoihCTKHwMGXnZBatYObg57xSOUX-bvhO_sFMm3k4RvsXcr3MFojAhLfwutu_jK9k7N9KR_mNc5IpiOyhZw_sUmF6SamRqsSPp42KD10hPMW0YJTDMYxBdHrMFeSMHYIMY4oBBT43__a55zILI_CnIk4241wOvGvw" + "crv": "P-256", + "kty": "EC", + "x": "qrJrj3Af_B57sbOIRrcBM7br7wOc8ynj7lHFPTeffUk", + "y": "1H0cWDyGgvU8w-kPKU_xycOCUNT2o0bwslIQtnPU6iM", + "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY" } }, "type": "HealthInsuranceData", diff --git a/docs/en/pid-eaa-issuance.rst b/docs/en/pid-eaa-issuance.rst index d4a87a50b..6093ce5c3 100644 --- a/docs/en/pid-eaa-issuance.rst +++ b/docs/en/pid-eaa-issuance.rst @@ -130,7 +130,7 @@ Below a non-normative example of the PAR. &client_id=$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$ &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM &code_challenge_method=S256 - &request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KIC Jpc3MiOiAiczZCaGRSa3F0MyIsDQogImF1ZCI6ICJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsDQo gInJlc3BvbnNlX3R5cGUiOiAiY29kZSBpZF90b2tlbiIsDQogImNsaWVudF9pZCI6ICJzNkJoZFJrcXQz IiwNCiAicmVkaXJlY3RfdXJpIjogImh0dHBzOi8vY2xpZW50LmV4YW1... + &request=$SIGNED-JWT &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation &client_assertion=$WIA~WIA-PoP @@ -901,7 +901,7 @@ Below is a non-normative example of an Entity Configuration containing an `openi { - "alg": "RS256", + "alg": "ES256", "kid": "FANFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", "typ": "entity-statement+jwt" @@ -913,13 +913,15 @@ Below is a non-normative example of an Entity Configuration containing an `openi "iss": "https://pid-provider.example.org", "sub": "https://pid-provider.example.org", "jwks": { - "keys": [{ - "kty": "RSA", - "use": "sig", - "n": "1Ta-sE …", - "e": "AQAB", - "kid": "FANFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs" - }] + "keys": [ + { + "crv": "P-256", + "kty": "EC", + "x": "qrJrj3Af_B57sbOIRrcBM7br7wOc8ynj7lHFPTeffUk", + "y": "1H0cWDyGgvU8w-kPKU_xycOCUNT2o0bwslIQtnPU6iM", + "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY" + } + ] }, "authority_hints": ["https://superior-entity.example.org/federation"], "metadata": { @@ -928,7 +930,7 @@ Below is a non-normative example of an Entity Configuration containing an `openi "authorization_endpoint": "https://pid-provider.example.org/connect/authorize", "token_endpoint": "https://pid-provider.example.org/connect/token", "pushed_authorization_request_endpoint": "https://pid-provider.example.org/connect/par", - "dpop_signing_alg_values_supported": ["RS256", "RS512", "ES256", "ES512"], + "dpop_signing_alg_values_supported": ["ES256", "ES512"], "credential_endpoint": "https://pid-provider.example.org/credential", "jwks": { "keys": [ @@ -945,7 +947,7 @@ Below is a non-normative example of an Entity Configuration containing an `openi "format": "vc+sd-jwt", "id": "eudiw.pid.it", "cryptographic_binding_methods_supported": ["jwk"], - "cryptographic_suites_supported": ["RS256", "RS512", "ES256", "ES512"], + "cryptographic_suites_supported": ["ES256", "ES512"], "display": [{ "name": "PID Provider Italiano di esempio", "locale": "it-IT", diff --git a/docs/en/relying-party-solution.rst b/docs/en/relying-party-solution.rst index 4b71a1c97..31e4900fb 100644 --- a/docs/en/relying-party-solution.rst +++ b/docs/en/relying-party-solution.rst @@ -506,7 +506,7 @@ Below is a non-normative response example: .. code-block:: text { - "alg": "RS256", + "alg": "ES256", "kid": "2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", "typ": "entity-statement+jwt" } @@ -519,9 +519,11 @@ Below is a non-normative response example: "jwks": { "keys": [ { - "kty": "RSA", - "n": "5s4qi …", - "e": "AQAB", + "kty": "EC", + "crv": "P-256", + "x": "1kNR9Ar3MzMokYTY8BRvRIue85NIXrYX4XD3K4JW7vI", + "y": "slT14644zbYXYF-xmw7aPdlbMuw3T1URwI4nafMtKrY", + "x5c": [ ] "kid": "2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs" } ] @@ -534,10 +536,11 @@ Below is a non-normative response example: "jwks": { "keys": [ { - "kty": "RSA", + "kty": "EC", "use": "sig", - "n": "1Ta-sE …", - "e": "AQAB", + "crv": "P-256", + "x": "1kNR9Ar3MzMokYTY8BRvRIue85NIXrYX4XD3K4JW7vI", + "y": "slT14644zbYXYF-xmw7aPdlbMuw3T1URwI4nafMtKrY", "kid": "YhNFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", "x5c": [ "..." ] } @@ -676,8 +679,8 @@ Below is a non-normative response example: // JARM related "authorization_signed_response_alg": [[ - "RS256", - "ES256" + "ES256", + "ES384" ], "authorization_encrypted_response_alg": [ "RSA-OAEP", @@ -696,8 +699,8 @@ Below is a non-normative response example: "subject_type": "pairwise", "require_auth_time": true, "id_token_signed_response_alg": [ - "RS256", - "ES256" + "ES256", + "ES384" ], "id_token_encrypted_response_alg": [ "RSA-OAEP", diff --git a/docs/en/trust.rst b/docs/en/trust.rst index 4f90eb96c..464c86860 100644 --- a/docs/en/trust.rst +++ b/docs/en/trust.rst @@ -186,7 +186,7 @@ Below is a non-normative example of a Trust Anchor Entity Configuration, where e .. code-block:: text { - "alg": "RS256", + "alg": "ES256", "kid": "FifYx03bnosD8m6gYQIfNHNP9cM_Sam9Tc5nLloIIrc", "typ": "entity-statement+jwt" } @@ -198,13 +198,6 @@ Below is a non-normative example of a Trust Anchor Entity Configuration, where e "sub": "https://registry.eidas.trust-anchor.example.eu", "jwks": { "keys": [ - { - "kty": "RSA", - "n": "3i5vV-_ …", - "e": "AQAB", - "kid": "FifYx03bnosD8m6gYQIfNHNP9cM_Sam9Tc5nLloIIrc", - "x5c": [ ] - }, { "kty": "EC", "kid": "X2ZOMHNGSDc4ZlBrcXhMT3MzRmRZOG9Jd3o2QjZDam51cUhhUFRuOWd0WQ", @@ -400,7 +393,7 @@ Below there is a non-normative example of an Entity Statement issued by an Accre .. code-block:: text { - "alg": "RS256", + "alg": "ES256", "kid": "em3cmnZgHIYFsQ090N6B3Op7LAAqj8rghMhxGmJstqg", "typ": "entity-statement+jwt" } From 1389ef01e6b2af6ce95d284429d294152cbdb8d6 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Mon, 26 Feb 2024 15:13:42 +0100 Subject: [PATCH 02/11] chore: Section improved by Amir Work --- docs/en/algorithms.rst | 81 ++++++++++++++++++++++++++++++++---------- 1 file changed, 62 insertions(+), 19 deletions(-) diff --git a/docs/en/algorithms.rst b/docs/en/algorithms.rst index 2340749d0..3d9610f0f 100644 --- a/docs/en/algorithms.rst +++ b/docs/en/algorithms.rst @@ -8,81 +8,124 @@ Cryptographic algorithms The following algorithms MUST be supported: .. list-table:: - :widths: 20 20 20 + :widths: 20 20 20 20 :header-rows: 1 - * - **Algorithm** + * - **Algorithm `alg` parameter value** + - **Description** - **Operations** - **References** * - **ES256** + - Elliptic Curve Digital Signature Algorithm (ECDSA) using one of the Agreed curves and SHA256. - Signature - - :rfc:`7518`. + - :rfc:`7518`, `[SOG-IS] `_, `[ETSI] `_ . * - **ES384** + - Elliptic Curve Digital Signature Algorithm (ECDSA) using one of the Agreed curves and SHA384. - Signature - - :rfc:`7518`. - * - **ES256** + - :rfc:`7518`, `[SOG-IS] `_, `[ETSI] `_ . + * - **ES512** + - Elliptic Curve Digital Signature Algorithm (ECDSA) using one of the Agreed curves and SHA521. - Signature - - :rfc:`7518`. - * - **RSA-OAEP** - - Key Encryption - - :rfc:`7518`. + - :rfc:`7518`, `[SOG-IS] `_, `[ETSI] `_ . * - **RSA-OAEP-256** + - RSA Encryption Scheme with Optimal Asymmetric Encryption Padding (OAEP) using SHA256 hash function and the MGF1 with SHA-256 mask generation function. - Key Encryption - - :rfc:`7516`. + - :rfc:`7516`, :rfc:`7518`. * - **A128CBC-HS256** + - AES encryption in Cipher Block Chaining mode with 128-bit Initial Vector value, plus HMAC authentication using SHA-256 and truncating HMAC to 128 bits. - Content Encryption - - :rfc:`7516`. + - :rfc:`7516`, :rfc:`7518`. * - **A256CBC-HS512** + - AES encryption in Cipher Block Chaining mode with 256-bit Initial Vector value, plus HMAC authentication using SHA-512 and truncating HMAC to 256 bits. - Content Encryption - - :rfc:`7516`. + - :rfc:`7516`, :rfc:`7518`. + +The following Elliptic Curves MUST be supported for the Elliptic Curve Digital Signature Algorithm: + +.. list-table:: + :widths: 20 20 20 + :header-rows: 1 + + * - **Curve Family** + - **Short Curve Name** + - **References** + * - **Brainpool** + - brainpoolP256r1, brainpoolP384r1, brainpoolP512r1. + - :rfc:`5639`, `[ETSI] `_ . + * - **NIST** + - P-256, P-384, P-521 + - `[ETSI] `_, `[FIPS-186-4] `_, `[ISO/IEC 14888-3] `_. The following algorithms are RECOMMENDED to be supported: .. list-table:: - :widths: 20 20 20 + :widths: 20 20 20 20 :header-rows: 1 - * - **Algorithm** + * - **Algorithm `alg` parameter value** + - **Description** - **Operations** - **References** * - **PS256** + - RSASSA (RSA with Signature Scheme Appendix) with PSS ( Probabilistic Signature Scheme) padding using SHA256 hash function and MGF1 mask generation function with SHA-256. - Signature - - :rfc:`7518`. + - :rfc:`7518`, `[SOG-IS] `_. + * - **PS384** + - RSASSA (RSA with Signature Scheme Appendix) with PSS ( Probabilistic Signature Scheme) padding using SHA384 hash function and MGF1 mask generation function with SHA-384. + - Signature + - :rfc:`7518`, `[SOG-IS] `_. * - **PS512** + - RSASSA (RSA with Signature Scheme Appendix) with PSS ( Probabilistic Signature Scheme) padding using SHA512 hash function and MGF1 mask generation function with SHA-512. - Signature - - :rfc:`7518`. + - :rfc:`7518`, `[SOG-IS] `_. * - **ECDH-ES** + - Elliptic Curve Diffie-Hellman (ECDH) Ephemeral Static key agreement using Concat Key Derivation Function (KDF). - Key Encryption - :rfc:`7518`. * - **ECDH-ES+A128KW** + - ECDH-ES using Concat KDF and content encryption key (CEK) wrapped using AES with a key length of 128 (A128KW). - Key Encryption - :rfc:`7518`. * - **ECDH-ES+A256KW** + - ECDH-ES using Concat KDF and content encryption key (CEK) wrapped using AES with a key length of 256 (A256KW). - Key Encryption - :rfc:`7518`. +.. note:: + It is importnat to highlight that For optimal security and compatibility in cryptographic operations, it is crucial that mobile devices support the reported algorithms. + The following algorithms MUST NOT be supported: .. list-table:: - :widths: 20 20 20 + :widths: 20 20 20 20 :header-rows: 1 - * - **Algorithm** + * - **Algorithm `alg` parameter value** + - **Description** - **Operations** - **References** * - **none** + - - - Signature - :rfc:`7518`. * - **RSA_1_5** + - RSAES with PKCS1-v1_5 padding scheme. Use of this algorithm is generally not recommended. + - Key Encryption + - :rfc:`7516`, `[security vulnerability] `_, `[SOG-IS] `_. + * - **RSA-OAEP** + - RSA Encryption Scheme with Optimal Asymmetric Encryption Padding (OAEP) using default parameters. - Key Encryption - - :rfc:`7516`. + - :rfc:`7518`, `[SOG-IS] `_. * - **HS256** + - HMAC using SHA256. - Signature - :rfc:`7518`. * - **HS384** + - HMAC using SHA384. - Signature - :rfc:`7518`. * - **HS512** + - HMAC using SHA512 - Signature - :rfc:`7518`. From 6915090ca32d71ad235b780b69b7e5a111234745 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Mon, 26 Feb 2024 15:19:22 +0100 Subject: [PATCH 03/11] chore: editorial --- docs/en/algorithms.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/en/algorithms.rst b/docs/en/algorithms.rst index 3d9610f0f..685faaf07 100644 --- a/docs/en/algorithms.rst +++ b/docs/en/algorithms.rst @@ -91,9 +91,6 @@ The following algorithms are RECOMMENDED to be supported: - Key Encryption - :rfc:`7518`. -.. note:: - It is importnat to highlight that For optimal security and compatibility in cryptographic operations, it is crucial that mobile devices support the reported algorithms. - The following algorithms MUST NOT be supported: .. list-table:: From c39cc313615f7c138ac29956decfc1506d7217b6 Mon Sep 17 00:00:00 2001 From: asharif1990 <35602900+asharif1990@users.noreply.github.com> Date: Mon, 26 Feb 2024 16:53:34 +0100 Subject: [PATCH 04/11] editorial --- docs/en/algorithms.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/algorithms.rst b/docs/en/algorithms.rst index 685faaf07..52ca7f35c 100644 --- a/docs/en/algorithms.rst +++ b/docs/en/algorithms.rst @@ -108,7 +108,7 @@ The following algorithms MUST NOT be supported: * - **RSA_1_5** - RSAES with PKCS1-v1_5 padding scheme. Use of this algorithm is generally not recommended. - Key Encryption - - :rfc:`7516`, `[security vulnerability] `_, `[SOG-IS] `_. + - :rfc:`7516`, `[Security Vulnerability] `_, `[SOG-IS] `_. * - **RSA-OAEP** - RSA Encryption Scheme with Optimal Asymmetric Encryption Padding (OAEP) using default parameters. - Key Encryption From 1158f3d7aa794c9f7976f67f78efedf2b3ec932e Mon Sep 17 00:00:00 2001 From: asharif1990 <35602900+asharif1990@users.noreply.github.com> Date: Tue, 27 Feb 2024 16:31:36 +0100 Subject: [PATCH 05/11] editorial resolve the regression --- docs/en/relying-party-solution.rst | 196 +++++------------------------ 1 file changed, 32 insertions(+), 164 deletions(-) diff --git a/docs/en/relying-party-solution.rst b/docs/en/relying-party-solution.rst index 82cfe274e..c61fa775c 100644 --- a/docs/en/relying-party-solution.rst +++ b/docs/en/relying-party-solution.rst @@ -1,17 +1,19 @@ +@ -1,512 +1,512 @@ +.. include:: ../common/common_definitions.rst - - +.. _Wallet Instance Attestation: wallet-instance-attestation.html +.. _Trust Model: trust.html .. _relying-party-solution: Relying Party Solution +++++++++++++++++++++++ -This section describes how a remote Relying Party or a Verifier App requests to a Wallet Instance the presentation of the PID/EAAs. +This section describes how a Relying Party may request to a Wallet Instance the presentation of the PID and the (Q)EAAs, +according to `OpenID for Verifiable Presentations - draft 20 `_. In this section the following flows are described: -<<< - **Remote Same Device Flow**, where the user-agent and the Wallet Instance are used in the same device. - **Remote Cross Device Flow**, where the user-agent and the Wallet Instance are used in different devices. @@ -505,19 +507,18 @@ Below is a non-normative response example: .. code-block:: text { + "alg": "RS256", "alg": "ES256", "kid": "2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", "typ": "entity-statement+jwt" } - . - { - "exp": 1649590602, - "iat": 1649417862, - "iss": "https://rp.example.it", - "sub": "https://rp.example.it", +@ -519,9 +519,11 @@ Below is a non-normative response example: "jwks": { "keys": [ { + "kty": "RSA", + "n": "5s4qi …", + "e": "AQAB", "kty": "EC", "crv": "P-256", "x": "1kNR9Ar3MzMokYTY8BRvRIue85NIXrYX4XD3K4JW7vI", @@ -526,178 +527,38 @@ Below is a non-normative response example: "kid": "2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs" } ] - }, - "metadata": { - "wallet_relying_party": { - "application_type": "web", - "client_id": "https://rp.example.it", - "client_name": "Name of an example organization", +@ -534,10 +536,11 @@ Below is a non-normative response example: "jwks": { "keys": [ { + "kty": "RSA", "kty": "EC", "use": "sig", + "n": "1Ta-sE …", + "e": "AQAB", "crv": "P-256", "x": "1kNR9Ar3MzMokYTY8BRvRIue85NIXrYX4XD3K4JW7vI", "y": "slT14644zbYXYF-xmw7aPdlbMuw3T1URwI4nafMtKrY", "kid": "YhNFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", "x5c": [ "..." ] } - ] - }, - - "contacts": [ - "ops@relying-party.example.org" - ], - - "request_uris": [ - "https://relying-party.example.org/request_uri" - ], - "redirect_uris": [ - "https://relying-party.example.org/callback" - ], - - "default_acr_values": [ - "https://www.spid.gov.it/SpidL2", - "https://www.spid.gov.it/SpidL3" - ], - "vp_formats": { - "vc+sd-jwt": { - "sd-jwt_alg_values": [ - "ES256", - "ES384" - ], - "kb-jwt_alg_values": [ - "ES256", - "ES384" - ] - } - }, - "presentation_definitions": [ - { - "id": "eu.europa.ec.eudiw.pid.it.1", - "input_descriptors": [ - { - "id": "IdentityCredential", - "format": { - "vc+sd-jwt": {} - }, - "constraints": { - "limit_disclosure": "required", - "fields": [ - { - "path": [ - "$.type" - ], - "filter": { - "type": "string", - "const": "IdentityCredential" - } - }, - { - "path": [ - "$.family_name" - ] - }, - { - "path": [ - "$.given_name" - ] - }, - { - "path": [ - "$.unique_id" - ], - "intent_to_retain": "true" - } - ] - } - } - ] - }, - { - "id": "mDL-sample-req", - "input_descriptors": [ - { - "id": "mDL", - "format": { - "mso_mdoc": { - "alg": [ - "EdDSA", - "ES256" - ] - }, - "constraints": { - "limit_disclosure": "required", - "fields": [ - { - "path": [ - "$.mdoc.doctype" - ], - "filter": { - "type": "string", - "const": "org.iso.18013.5.1.mDL" - } - }, - { - "path": [ - "$.mdoc.namespace" - ], - "filter": { - "type": "string", - "const": "org.iso.18013.5.1" - } - }, - { - "path": [ - "$.mdoc.family_name" - ], - "intent_to_retain": "false" - }, - { - "path": [ - "$.mdoc.portrait" - ], - "intent_to_retain": "false" - }, - { - "path": [ - "$.mdoc.driving_privileges" - ], - "intent_to_retain": "false" - } - ] - } - } - } - ] - } - ], - - "default_max_age": 1111, +@ -676,8 +679,8 @@ Below is a non-normative response example: // JARM related "authorization_signed_response_alg": [[ + "RS256", + "ES256" "ES256", "ES384" ], "authorization_encrypted_response_alg": [ "RSA-OAEP", - "RSA-OAEP-256" - ], - "authorization_encrypted_response_enc": [ - "A128CBC-HS256", - "A192CBC-HS384", - "A256CBC-HS512", - "A128GCM", - "A192GCM", - "A256GCM" - ], - - // SIOPv2 related +@ -696,57 +699,57 @@ "subject_type": "pairwise", "require_auth_time": true, "id_token_signed_response_alg": [ + "RS256", + "ES256" "ES256", "ES384" ], @@ -736,11 +597,18 @@ The Entity Configuration is a JWS, where its header parameters are defined below .. list-table:: :widths: 25 50 :header-rows: 1 -- :ref:`Remote Flow `, where the User presents a Credential to a remote Relying Party according to `OPENID4VP`_. In this scenario the user-agent and the Wallet Instance may be used in the same device (**Same Device Flow**), or in different devices (**Cross Device Flow**). -- :ref:`Proximity Flow `, where the User presents a Credential to a Verifier App according to ISO 18013-5. The User interacts with a Verifier using proximity connection technologies such as QR Code and Bluetooth Low Energy (BLE). -.. include:: remote-flow.rst + * - **Name** + - **Description** + * - **alg** + - Algorithm used to sign the JWT + * - **typ** + - Media Type of the JWT + * - **kid** + - Key ID used identifying the key used to sign the JWS -.. include:: proximity-flow.rst +.. note: + The Relying Party specific metadata parameter are experimental + and still under discussion `here `_. From b27d6dfbea958efe8a0fb42193ed3e44ab0055c7 Mon Sep 17 00:00:00 2001 From: asharif1990 <35602900+asharif1990@users.noreply.github.com> Date: Wed, 28 Feb 2024 10:56:01 +0100 Subject: [PATCH 06/11] update RP solution. editorial changes. --- docs/en/relying-party-solution.rst | 166 +++++++++++++++++++++++++---- 1 file changed, 147 insertions(+), 19 deletions(-) diff --git a/docs/en/relying-party-solution.rst b/docs/en/relying-party-solution.rst index c61fa775c..06e8ee8b3 100644 --- a/docs/en/relying-party-solution.rst +++ b/docs/en/relying-party-solution.rst @@ -1,4 +1,4 @@ -@ -1,512 +1,512 @@ + .. include:: ../common/common_definitions.rst .. _Wallet Instance Attestation: wallet-instance-attestation.html @@ -507,18 +507,19 @@ Below is a non-normative response example: .. code-block:: text { - "alg": "RS256", "alg": "ES256", "kid": "2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", "typ": "entity-statement+jwt" } -@ -519,9 +519,11 @@ Below is a non-normative response example: + . + { + "exp": 1649590602, + "iat": 1649417862, + "iss": "https://rp.example.it", + "sub": "https://rp.example.it", "jwks": { "keys": [ { - "kty": "RSA", - "n": "5s4qi …", - "e": "AQAB", "kty": "EC", "crv": "P-256", "x": "1kNR9Ar3MzMokYTY8BRvRIue85NIXrYX4XD3K4JW7vI", @@ -527,43 +528,170 @@ Below is a non-normative response example: "kid": "2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs" } ] -@ -534,10 +536,11 @@ Below is a non-normative response example: + }, + "metadata": { + "wallet_relying_party": { + "application_type": "web", + "client_id": "https://rp.example.it", + "client_name": "Name of an example organization", "jwks": { "keys": [ { - "kty": "RSA", "kty": "EC", "use": "sig", - "n": "1Ta-sE …", - "e": "AQAB", "crv": "P-256", "x": "1kNR9Ar3MzMokYTY8BRvRIue85NIXrYX4XD3K4JW7vI", "y": "slT14644zbYXYF-xmw7aPdlbMuw3T1URwI4nafMtKrY", "kid": "YhNFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", "x5c": [ "..." ] } -@ -676,8 +679,8 @@ Below is a non-normative response example: + ] + }, + + "contacts": [ + "ops@relying-party.example.org" + ], + + "request_uris": [ + "https://relying-party.example.org/request_uri" + ], + "redirect_uris": [ + "https://relying-party.example.org/callback" + ], + + "default_acr_values": [ + "https://www.spid.gov.it/SpidL2", + "https://www.spid.gov.it/SpidL3" + ], + "vp_formats": { + "vc+sd-jwt": { + "sd-jwt_alg_values": [ + "ES256", + "ES384" + ], + "kb-jwt_alg_values": [ + "ES256", + "ES384" + ] + } + }, + "presentation_definitions": [ + { + "id": "eu.europa.ec.eudiw.pid.it.1", + "input_descriptors": [ + { + "id": "IdentityCredential", + "format": { + "vc+sd-jwt": {} + }, + "constraints": { + "limit_disclosure": "required", + "fields": [ + { + "path": [ + "$.type" + ], + "filter": { + "type": "string", + "const": "IdentityCredential" + } + }, + { + "path": [ + "$.family_name" + ] + }, + { + "path": [ + "$.given_name" + ] + }, + { + "path": [ + "$.unique_id" + ], + "intent_to_retain": "true" + } + ] + } + } + ] + }, + { + "id": "mDL-sample-req", + "input_descriptors": [ + { + "id": "mDL", + "format": { + "mso_mdoc": { + "alg": [ + "EdDSA", + "ES256" + ] + }, + "constraints": { + "limit_disclosure": "required", + "fields": [ + { + "path": [ + "$.mdoc.doctype" + ], + "filter": { + "type": "string", + "const": "org.iso.18013.5.1.mDL" + } + }, + { + "path": [ + "$.mdoc.namespace" + ], + "filter": { + "type": "string", + "const": "org.iso.18013.5.1" + } + }, + { + "path": [ + "$.mdoc.family_name" + ], + "intent_to_retain": "false" + }, + { + "path": [ + "$.mdoc.portrait" + ], + "intent_to_retain": "false" + }, + { + "path": [ + "$.mdoc.driving_privileges" + ], + "intent_to_retain": "false" + } + ] + } + } + } + ] + } + ], + "default_max_age": 1111, // JARM related "authorization_signed_response_alg": [[ - "RS256", - "ES256" "ES256", "ES384" ], "authorization_encrypted_response_alg": [ - "RSA-OAEP", -@ -696,57 +699,57 @@ + "RSA-OAEP-256", + ], "subject_type": "pairwise", "require_auth_time": true, "id_token_signed_response_alg": [ - "RS256", - "ES256" "ES256", "ES384" ], "id_token_encrypted_response_alg": [ - "RSA-OAEP", "RSA-OAEP-256" ], "id_token_encrypted_response_enc": [ @@ -597,7 +725,7 @@ The Entity Configuration is a JWS, where its header parameters are defined below .. list-table:: :widths: 25 50 :header-rows: 1 - + * - **Name** - **Description** * - **alg** From 5bfaaed178675445e21da2dadb145213032dab44 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> Date: Thu, 29 Feb 2024 18:34:29 +0100 Subject: [PATCH 07/11] Update docs/en/algorithms.rst Co-authored-by: Giuseppe De Marco --- docs/en/algorithms.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/algorithms.rst b/docs/en/algorithms.rst index 52ca7f35c..53f58655d 100644 --- a/docs/en/algorithms.rst +++ b/docs/en/algorithms.rst @@ -24,7 +24,7 @@ The following algorithms MUST be supported: - Signature - :rfc:`7518`, `[SOG-IS] `_, `[ETSI] `_ . * - **ES512** - - Elliptic Curve Digital Signature Algorithm (ECDSA) using one of the Agreed curves and SHA521. + - Elliptic Curve Digital Signature Algorithm (ECDSA) using one of the enabled curves listed in the section below and SHA521. - Signature - :rfc:`7518`, `[SOG-IS] `_, `[ETSI] `_ . * - **RSA-OAEP-256** From c0ca6b20f64b3b93539fe9df9caf2fbebc48e6cd Mon Sep 17 00:00:00 2001 From: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> Date: Thu, 29 Feb 2024 18:34:44 +0100 Subject: [PATCH 08/11] Update docs/en/algorithms.rst Co-authored-by: Giuseppe De Marco --- docs/en/algorithms.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/algorithms.rst b/docs/en/algorithms.rst index 53f58655d..6b2966bcb 100644 --- a/docs/en/algorithms.rst +++ b/docs/en/algorithms.rst @@ -20,7 +20,7 @@ The following algorithms MUST be supported: - Signature - :rfc:`7518`, `[SOG-IS] `_, `[ETSI] `_ . * - **ES384** - - Elliptic Curve Digital Signature Algorithm (ECDSA) using one of the Agreed curves and SHA384. + - Elliptic Curve Digital Signature Algorithm (ECDSA) using one of the enabled curves listed in the section below and SHA384. - Signature - :rfc:`7518`, `[SOG-IS] `_, `[ETSI] `_ . * - **ES512** From 82e1e599acfba06bf3ccf175cb8d24abd902d628 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> Date: Thu, 29 Feb 2024 18:34:58 +0100 Subject: [PATCH 09/11] Update docs/en/algorithms.rst Co-authored-by: Giuseppe De Marco --- docs/en/algorithms.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/algorithms.rst b/docs/en/algorithms.rst index 6b2966bcb..a1698984a 100644 --- a/docs/en/algorithms.rst +++ b/docs/en/algorithms.rst @@ -16,7 +16,7 @@ The following algorithms MUST be supported: - **Operations** - **References** * - **ES256** - - Elliptic Curve Digital Signature Algorithm (ECDSA) using one of the Agreed curves and SHA256. + - Elliptic Curve Digital Signature Algorithm (ECDSA) using one of the enabled curves listed in the section below and SHA256. - Signature - :rfc:`7518`, `[SOG-IS] `_, `[ETSI] `_ . * - **ES384** From 105b2429786db6b114cab098d4b92fb63c2d6dc4 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Thu, 29 Feb 2024 18:41:35 +0100 Subject: [PATCH 10/11] fix: pid issuance conflicts --- docs/en/pid-eaa-issuance.rst | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/docs/en/pid-eaa-issuance.rst b/docs/en/pid-eaa-issuance.rst index 44a3e96c1..9dab80d4b 100644 --- a/docs/en/pid-eaa-issuance.rst +++ b/docs/en/pid-eaa-issuance.rst @@ -940,15 +940,6 @@ Below is a non-normative example of an Entity Configuration of a PID Provider co "iss": "https://pid-provider.example.org", "sub": "https://pid-provider.example.org", "jwks": { - "keys": [ - { - "crv": "P-256", - "kty": "EC", - "x": "qrJrj3Af_B57sbOIRrcBM7br7wOc8ynj7lHFPTeffUk", - "y": "1H0cWDyGgvU8w-kPKU_xycOCUNT2o0bwslIQtnPU6iM", - "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY" - } - ] "keys": [{ "kty": "RSA", "use": "sig", @@ -1051,9 +1042,6 @@ Below is a non-normative example of an Entity Configuration of a PID Provider co { "format": "vc+sd-jwt", "cryptographic_binding_methods_supported": ["jwk"], - - "cryptographic_suites_supported": ["ES256", "ES512"], - "credential_signing_alg_values_supported": ["ES256", "ES384", "ES512"], "proof_types_supported": { "jwt": { @@ -1062,7 +1050,6 @@ Below is a non-normative example of an Entity Configuration of a PID Provider co ] } }, - "display": [{ "name": "PID Italiano di esempio", "locale": "it-IT", @@ -1174,3 +1161,4 @@ Below is a non-normative example of an Entity Configuration of a PID Provider co } } } + From 43bf3e44b66a05b36ae6e73bd1d40d1675e28c16 Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Thu, 29 Feb 2024 18:48:17 +0100 Subject: [PATCH 11/11] fix: RP solution conflicts --- docs/en/relying-party-solution.rst | 734 +---------------------------- docs/en/remote-flow.rst | 2 +- 2 files changed, 7 insertions(+), 729 deletions(-) diff --git a/docs/en/relying-party-solution.rst b/docs/en/relying-party-solution.rst index 06e8ee8b3..afa4d6a06 100644 --- a/docs/en/relying-party-solution.rst +++ b/docs/en/relying-party-solution.rst @@ -1,742 +1,20 @@ -.. include:: ../common/common_definitions.rst -.. _Wallet Instance Attestation: wallet-instance-attestation.html -.. _Trust Model: trust.html + .. _relying-party-solution: Relying Party Solution +++++++++++++++++++++++ -This section describes how a Relying Party may request to a Wallet Instance the presentation of the PID and the (Q)EAAs, -according to `OpenID for Verifiable Presentations - draft 20 `_. +This section describes how a remote Relying Party or a Verifier App requests to a Wallet Instance the presentation of the PID/EAAs. In this section the following flows are described: -- **Remote Same Device Flow**, where the user-agent and the Wallet Instance are used in the same device. -- **Remote Cross Device Flow**, where the user-agent and the Wallet Instance are used in different devices. - -In the **Same Device** and **Cross Device** Flows described in this chapter, the User interacts with a remote Relying Party. - -.. note:: - The provisioning of the Wallet Instance Attestation from the Wallet Instace to the Relying Party is - under discussion within the international standardization working groups. At the current stage of the draft of this implementation profile, - a mechanism based on `OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP) `_ - is used. - -Remote Protocol Flow --------------------- - -In this scenario the Relying Party MUST provide the URL where the signed presentation Request Object is available for download. - -Depending on whether the Relying Party client is on a mobile device or a workstation, -the Relying Party MUST activate one of the supported remote flows: - -* **Same Device**, the Relying Party MUST provide a HTTP redirect (302) location to the Wallet Instance; -* **Cross Device**, the Relying Party MUST provide a QR Code which the User frames with their Wallet Instance. - -Once the Wallet Instance establishes the trust with the Relying Party, the User gives the consent for the release of the personal data, in the form of a Verifiable Presentation. - -Below a sequence diagram that summarizes the interactions between all the involved parties. - -.. image:: ../../images/cross_device_auth_seq_diagram.svg - :align: center - :target: //www.plantuml.com/plantuml/uml/XLLTJoCt57tthxXA7neGK7Rx5ebgMKg1tRPCax2y8277labS77lgZmbfrV_UQtkOJ4YaIWXfx7EFpxaVDvzyu2x4bMOy1clYQeQECNOfWdKmUF3e1i0zHCPczhKSVE_XPsoKG3-0xtvLYsNuh2EocdYKK3Kt0GQFN6iCS6U8tWZC7EjTI2IgKxv04yeBdA6HGA_imiQeDyeieAB3JKOso5Y4qvyeP0IFE8C9kYG736_KWWTb3OkS08GSmHZ_YkW3LCu6504bdNWRdI2MYmj8Xk0oXYKQUZC7mx1owEcxV5LBxl48BYuO5q4rF61IqE3R0rSEwInpMAV-pa7TgqzcU7pi0m6EZybR98V1mjOw26jV5D7l4xf2yHoT0jTApgXY_8_nbPK8zsEudKuhUb0gH_vW-EFvnoDOgx24iDnbeVpMLfd09FQjiAsnDMCBPsDD6gn_ApDOepTjHkC89akxpjIjWfgCf7hGxNe4zpMQVFkk0u3NzGbeAxW6lfDkjeOIEX7S42aarkxm-ZKuajSbz65yzsJcpguw9BbY16-JTtCzxR3tipzHf1hCDlruEaZfsLDu6GBwKdI2SB9VsGg2VK733jU-3I6_FFHDKwyrIg9xCg0yf7O6Ey-0Nv2EynDqnuqyc2gACJQ0muRUbYU4JFa2RBYE9A4V8tZDPqgheD2VaR2s3Bifs2zuoMwdVsV6OEgY3nta6pertxo3_8Q1Inxu5iMraed-o-CK9cfXU8WEzwzRNIZXMpNqHmKGjthdre6m9atVDkLnsrvNrioLMw7iMuhRybVta-dUAFewCL9DorWqzNCfwk6QNlVINDmhFjC8EqkX4Emr0esk98pY6kwyZ-XACjjQ7qvIZuNwHg3t-MNHKJ7cZAKesw0Z6EtSkvlRwStu-lftTZXYnE1gYU85RgsM5FGLD_1P6Ka5p48eYlgH_YhhFOMJ8mevXUW9aRdgEDDAm0i5bgsbJ6d3liLWeIdTaLFLpiePOp2bVkr6DrrAvOMs7YNm49oQnO1-H1LfTQevK3zt2qiv0gR-0kuGUCELfXBaKS-fOBsSFTIoBLRPvQqV69RD2Z7VooFOJaVUc3zyEFi07y_FuVuhoVXduCe2pPjoC89b2BM7w7Jf6TSsqRD8A-_VVlUjtqzNsQ0JliAT1RfkDpV9B7BxBoPh_xTx6-os_fV9gCtSxYu57vAAOJBujlgBWVPtfYIXwBWy5BfG3PeIaacINty2aN1K87ojSssi0nz5whnvr5dx9_eNL_e_ - - -The details of each step shown in the previous picture are described in the table below. - - -.. list-table:: - :widths: 50 50 - :header-rows: 1 - - * - **Id** - - **Description** - * - **1**, **2** - - The User asks for access to a protected resource, the Relying Party redirects the User to a discovery page in which the User selects the *Login with the Wallet* button. The Authorization flow starts. - * - **3**, **4**, **5** - - The Relying Party creates an Authorization Request which contains the scopes of the request and provides it to the requester. - * - **6**, **7**, **8**, **9** - - In the **Cross Device Flow**: the Request URI is provided in the form of a QR Code that is shown to the User. The User frames the QRCode with the Wallet Instance and extracts the Request URI. In the **Same Device Flow** the Relying Party responses with the Request URI in the form of HTTP Redirect Location (302). - * - **10** - - The Wallet Instance requests the content of the Authorization Request by invoking the Request URI, passing an Authorization DPoP HTTP Header containing the Wallet Instance Attestation and the DPoP proof HTTP Header. - * - **11** - - The Relying Party attests the trust to the Wallet Instance using the Wallet Instance Attestation and evaluates the Wallet Instance capabilities. - * - **12** - - The Relying Party issues a signed Request Object, returning it as response. The ``exp`` value of the signed Request Object MUST be no more than 240 seconds. - * - **13**, **14**, **15**, **16** - - The Wallet Instance verifies the Request Object JWS. The Wallet Instance attests the trust to the Relying Party by verifying the Trust Chain. The Wallet Instance verifies the signature of the request and processes the Relying Party metadata to attest its capabilities and allowed scopes, attesting which Verifiable Credentials and personal attributes the Relying Party is granted to request. - * - **17**, **18** - - The Wallet Instance requests the User's consent for the release of the credentials. The User authorizes and consents the presentation of their credentials, by selecting/deselecting the personal data to release. - * - **19** - - The Wallet Instance provides the Authorization Response to the Relying Party using an HTTP request with the method POST (response mode "direct_post"). - * - **20**, **21**, **22** - - The Relying Party verifies the Authorization Response, extracts the credential and attests the trust to the credentials Issuer. The Relying Party verifies the revocation status and the proof of possession of the presented credential. - * - **23** - - The Relying Party authenticates the User. - * - **24** - - The Relying Party notifies to the Wallet Instance that the operation ends successfully. - - -Authorization Request Details ------------------------------ - -The Relying Party MUST create a Request Object in the format of signed JWT, then provide it to the Wallet Instance through an HTTP URL (request URI). The HTTP URL points to the web resource where the signed request object is available for download. The URL parameters contained in the Relying Party response, containing the request URI, are described in the Table below. - -.. list-table:: - :widths: 25 50 - :header-rows: 1 - - * - **Name** - - **Description** - * - **client_id** - - Unique identifier of the Relying Party. - * - **request_uri** - - The HTTP URL used by the Wallet Instance to retrieve the signed Request Object from the Relying Party. The URL is intentionally extended with a random value that uniquely identifies the transaction. - -Below a non-normative example of the response containing the required parameters previously described. - -.. code-block:: javascript - - eudiw://authorize?client_id=`$client_id`&request_uri=`$request_uri` - -The value corresponding to the `request_uri` endpoint MUST be randomized, according to `RFC 9101, The OAuth 2.0 Authorization Framework: JWT-Secured Authorization Request (JAR) `_ Section 5.2.1. - - -In the **Same Device Flow** the Relying Party uses a HTTP response redirect (status code 302) as represented in the following non-normative example: - -.. code:: text - - HTTP/1.1 /pre-authz-endpoint Found - Location: https://wallet-providers.eudi.wallet.gov.it? - client_id=https%3A%2F%2Frelying-party.example.org%2Fcb - &request_uri=https%3A%2F%2Frelying-party.example.org%2Frequest_uri%3Fid%3Drandom-value - - -In the **Cross Device Flow**, a QR Code is shown by the Relying Party to the User in order to provide the Authorization Request. The User frames the QR Code using their Wallet Instance. The QR Code payload MUST be a **Base64 encoded string**. - -Below is represented a non-normative example of a QR Code issued by the Relying Party. - -.. image:: ../../images/verifier_qr_code.svg - :align: center - - -Below is represented a non-normative example of the QR Code raw payload: - -.. code-block:: text - - ZXVkaXc6Ly9hdXRob3JpemU/Y2xpZW50X2lkPWh0dHBzOi8vdmVyaWZpZXIuZXhhbXBsZS5vcmcmcmVxdWVzdF91cmk9aHR0cHM6Ly92ZXJpZmllci5leGFtcGxlLm9yZy9yZXF1ZXN0X3VyaS8= - -The decoded content of the previous Base64 value is represented below: - -.. code-block:: text - - eudiw://authorize?client_id=https%3A%2F%2Frelying-party.example.org&request_uri=https%3A%2F%2Frelying-party.example.org%2Frequest_uri%3Fid%3Drandom-value - -.. 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. - - -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. - -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: - -* **201 Created**. The signed Request Object was issued by the Relying Party that waits to be downloaded by the Wallet Instance at the **request_uri** endpoint. -* **202 Accepted**. This response is given when the signed Request Object was obtained by the Wallet Instance. -* **200 OK**. The Wallet Instance has provided the presentation to the Relying Party's **redirect_uri** endpoint and the User authentication is successful. The Relying Party updates the session cookie allowing the user-agent to access to the protected resource. An URL is provided carrying the location where the user-agent is intended to navigate. -* **401 Unauthorized**. The Wallet Instance or its User have rejected the request, or the request is expired. The QRCode page SHOULD be updated with an error message. - -Below a non-normative example of the HTTP Request to this specialized endpoint, where the parameter ``id`` contains an opaque and random value: - -.. code:: - - GET /session-state?id=3be39b69-6ac1-41aa-921b-3e6c07ddcb03 - HTTP/1.1 - HOST: relying-party.example.org - - -Request Object Details ----------------------- -The following actions are made by the Wallet Instance: - -- scan the QR Code (Cross Device only); -- extract from the payload the ``request_uri`` parameter; -- invoke the retrieved URI; -- provide in the request its Wallet Instance Attestation, using :rfc:`9449` to proof the legitimate possession of it; -- obtain the signed Request Object from the Relying Party. -- evaluate the trust with the Relying Party, by evaluating the Trust Chain related to it. - -Below a non-normative example of HTTP request made by the Wallet Instance to the Relying Party to provide the Wallet Instance Attestion and retrieve the signed Request Object: - -.. code-block:: javascript - - GET /request_uri HTTP/1.1 - HOST: relying-party.example.org - Authorization: DPoP $WalletInstanceAttestation - DPoP: $WalletInstanceAttestationProofOfPossession - - -More detailed information about the `Wallet Instance Attestation`_ is available in its dedicated section of this technical specification. - -To attest a high level of security, the Wallet Instance submits its Wallet Instance Attestation to the Relying Party, disclosing its capabilities and the security level attested by its Wallet Provider. - -Below the description of the parameters defined in *OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)*. - -If the DPoP HTTP Header is missing, the Relying Party would assume the lowest attestable level of security to the Wallet Instance it is interacting with. - -DPoP HTTP Header -^^^^^^^^^^^^^^^^ - -A **DPoP proof** is included in the request using the HTTP Header ``DPoP`` and containing a JWS. The JWS MUST be verified with the public key made available in the Wallet Instance Attestation (``Authorization: DPoP``). - -The JOSE header of the **DPoP JWS** MUST contain at least the following parameters: - -.. list-table:: - :widths: 20 60 20 - :header-rows: 1 - - * - **JOSE header** - - **Description** - - **Reference** - * - **typ** - - It MUST be equal to ``dpop+jwt``. - - [:rfc:`7515`] and [:rfc:`8725`. Section 3.11]. - * - **alg** - - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms in Section *Cryptographic Algorithms* `* and MUST NOT be none or an identifier for a symmetric algorithm (MAC). - - [:rfc:`7515`] - * - **jwk** - - Representing the public key chosen by the client, in JSON Web Key (JWK) [RFC7517] format, as defined in Section 4.1.3 of [RFC7515]. It MUST NOT contain a private key. - - [:rfc:`7517`] and [:rfc:`7515`] - - -The payload of a **DPoP proof** MUST contain at least the following claims: - -.. list-table:: - :widths: 20 60 20 - :header-rows: 1 - - * - **Claim** - - **Description** - - **Reference** - * - **jti** - - Unique identifier for the DPoP proof JWT. The value SHOULD be set with a *UUID v4* value, according to [:rfc:`4122`]. - - [:rfc:`7519`. Section 4.1.7]. - * - **htm** - - The value of the HTTP method of the request to which the JWT is attached. - - [:rfc:`9110`. Section 9.1]. - * - **htu** - - The HTTP target URI, without query and fragment parts, of the request to which the JWS is attached. - - [:rfc:`9110`. Section 7.1]. - * - **iat** - - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. - - [:rfc:`7519`. Section 4.1.6]. - * - **ath** - - Hash of the Wallet Instance Attestation. - - [:rfc:`9449`. Section 4.2]. - - -Therein a non-normative example of the DPoP decoded content: - -.. code-block:: text - - { - "typ": "dpop+jwt", - "alg": "ES256", - "jwk": { - "kty": "EC", - "x": "l8tFrhx-34tV3hRICRDY9zCkDlpBhF42UQUfWVAWBFs", - "y": "9VE4jf_Ok_o64zbTTlcuNJajHmt6v9TDVrU0CdvGRDA", - "crv": "P-256" - } - } - . - { - "jti": "f47c96a1-f928-4768-aa30-ef32dc78aa69", - "htm": "GET", - "htu": "https://relying-party.example.org/request_uri", - "iat": 1562262616, - "ath": "fUHyO2r2Z3DZ53EsNrWBb0xWXoaNy59IiKCAqksmQEo" - } - - -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: - -.. code-block:: text - - { - "alg": "ES256", - "typ": "JWT", - "kid": "e0bbf2f1-8c3a-4eab-a8ac-2e8f34db8a47", - "trust_chain": [ - "MIICajCCAdOgAwIBAgIC...awz", - "MIICajCCAdOgAwIBAgIC...2w3", - "MIICajCCAdOgAwIBAgIC...sf2" - ] - } - . - { - "scope": "eu.europa.ec.eudiw.pid.it.1 tax_id_number", - "client_id_scheme": "entity_id", - "client_id": "https://relying-party.example.org", - "response_mode": "direct_post.jwt", - "response_type": "vp_token", - "response_uri": "https://relying-party.example.org/callback", - "nonce": "2c128e4d-fc91-4cd3-86b8-18bdea0988cb", - "state": "3be39b69-6ac1-41aa-921b-3e6c07ddcb03", - "iss": "https://relying-party.example.org", - "iat": 1672418465, - "exp": 1672422065 - } - -The JWS header parameters are described below: - -.. list-table:: - :widths: 25 50 - :header-rows: 1 - - * - **Name** - - **Description** - * - **alg** - - Algorithm used to sign the JWT, according to [:rfc:`7516#section-4.1.1`]. It MUST be one of the supported algorithms in Section *Cryptographic Algorithms* and MUST NOT be set to ``none`` or to a symmetric algorithm (MAC) identifier. - * - **typ** - - Media Type of the JWT, as defined in [:rfc:`7519`]. - * - **kid** - - Key ID of the public key needed to verify the JWS signature, as defined in [:rfc:`7517`]. REQUIRED when ``trust_chain`` is used. - * - **trust_chain** - - Sequence of Entity Statements that composes the Trust Chain related to the Relying Party, as defined in `OIDC-FED`_ Section *3.2.1. Trust Chain Header Parameter*. - - -The JWS payload parameters are described herein: - -.. list-table:: - :widths: 25 50 - :header-rows: 1 - - * - **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``. - * - **response_type** - - 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** - - Fresh cryptographically random number with sufficient entropy, which length MUST be at least 32 digits. - * - **state** - - Unique identifier of the Authorization Request. - * - **iss** - - The entity that has issued the JWT. It will be populated with the Relying Party client id. - * - **iat** - - Unix Timestamp, representing the time at which the JWT was issued. - * - **exp** - - Unix Timestamp, representing the expiration time on or after which the JWT MUST NOT be valid anymore. - - -.. 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: - -.. code-block:: JSON - - { - "presentation_definition": { - "id": "presentation definitions", - "input_descriptors": [ - { - "id": "eu.europa.ec.eudiw.pid.it.1", - "name": "Person Identification Data", - "purpose": "User authentication", - "format": "vc+sd-jwt", - "constraints": { - "fields": [ - { - "path": [ - "$.credentialSubject.unique_id", - "$.credentialSubject.given_name", - "$.credentialSubject.family_name", - ] - } - ], - "limit_discolusre": "preferred" - } - } - ] - } - } - - - -.. 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``: 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. The ``client_metadata`` parameter MUST NOT be present when ``client_id_scheme`` is ``entity_id``. The ``client_metadata`` is taken from ``trust_chain``. - - ``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``. - - ``redirect_uri``: the redirect URI to which the Wallet Instance MUST redirect the Authorization Response. This parameter MUST not be present when ``response_uri`` is present. - - -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. - -.. note:: - **Why the response is encrypted?** - - The response sent from the Wallet Instance to the Relying Party is encrypted to prevent a malicious agent from gaining access to the plaintext information transmitted within the Relying Party's network. This is only possible if the network environment of the Relying Party employs `TLS termination `_. Such technique employs a termination proxy that acts as an intermediary between the client and the webserver and handles all TLS-related operations. In this manner, the proxy deciphers the transmission's content and either forwards it in plaintext or by negotiates an internal TLS session with the actual webserver's intended target. In the first scenario, any malicious actor within the network segment could intercept the transmitted data and obtain sensitive information, such as an unencrypted response, by sniffing the transmitted data. - -Below a non-normative example of the request: - -.. code-block:: http - - POST /callback HTTP/1.1 - HOST: relying-party.example.org - Content-Type: application/x-www-form-urlencoded - - response=eyJhbGciOiJFUzI1NiIs...9t2LQ - - -Below is a non-normative example of the decrypted JSON ``response`` content: - -.. code-block:: JSON - - { - "state": "3be39b69-6ac1-41aa-921b-3e6c07ddcb03", - "vp_token": "eyJhbGciOiJFUzI1NiIs...PT0iXX0", - "presentation_submission": { - "definition_id": "32f54163-7166-48f1-93d8-ff217bdb0653", - "id": "04a98be3-7fb0-4cf5-af9a-31579c8b0e7d", - "descriptor_map": [ - { - "id": "eu.europa.ec.eudiw.pid.it.1", - "path": "$.vp_token.verified_claims.claims._sd[0]", - "format": "vc+sd-jwt" - } - ] - } - } - -Where the following parameters are used: - -.. list-table:: - :widths: 25 50 - :header-rows: 1 - - * - **Name** - - **Description** - * - **vp_token** - - JWS containing a single or an array of Verifiable Presentation(s) in the form of signed JWT. - * - **presentation_submission** - - JSON Object containing the mappings between the requested Verifiable Credentials and where to find them within the returned VP Token. - * - **state** - - Unique identifier provided by the Relying Party within the Authorization Request. - - -Below is a non-normative example of the ``vp_token`` decoded content, represented in the form of JWS header and payload, separated by a period: - -.. code-block:: text - - { - "alg": "ES256", - "typ": "JWT", - "kid": "e0bbf2f1-8c3a-4eab-a8ac-2e8f34db8a47" - } - . - { - "iss": "https://wallet-provider.example.org/instance/vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c", - "jti": "3978344f-8596-4c3a-a978-8fcaba3903c5", - "aud": "https://relying-party.example.org/callback", - "iat": 1541493724, - "exp": 1573029723, - "nonce": "2c128e4d-fc91-4cd3-86b8-18bdea0988cb" - "vp": "~~~...~" - } - -Where the following parameters are used: - -.. list-table:: - :widths: 25 50 - :header-rows: 1 - - * - **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 part is carried in the digital credential (Holder Key Binding). - * - **jti** - - JWS Unique identifier. - * - **iat** - - Unix timestamp of the issuance datetime. - * - **exp** - - Unix timestamp beyond which the presentation of the digital credential will no longer be considered valid. - * - **aud** - - Audience of the VP, corresponding to the ``redirect_uri`` within the Authorization request issued by the Relying Party. - * - **nonce** - - Nonce provided by the Relying Party within the Authorization Request. - -Relying Party Entity Configuration ---------------------------------------------- -According to the `Trust Model`_ section, the Relying Party is a Federation Entity and MUST expose a well-known endpoint containing its Entity Configuration. - -Below a non-normative example of the request made by the Wallet Instance to the *openid-federation* well-known endpoint to obtain the Relying Party Entity Configuration: - -.. code-block:: http - - GET /.well-known/openid-federation HTTP/1.1 - HOST: relying-party.example.org - - -Below is a non-normative response example: - -.. code-block:: text - - { - "alg": "ES256", - "kid": "2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", - "typ": "entity-statement+jwt" - } - . - { - "exp": 1649590602, - "iat": 1649417862, - "iss": "https://rp.example.it", - "sub": "https://rp.example.it", - "jwks": { - "keys": [ - { - "kty": "EC", - "crv": "P-256", - "x": "1kNR9Ar3MzMokYTY8BRvRIue85NIXrYX4XD3K4JW7vI", - "y": "slT14644zbYXYF-xmw7aPdlbMuw3T1URwI4nafMtKrY", - "x5c": [ ] - "kid": "2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs" - } - ] - }, - "metadata": { - "wallet_relying_party": { - "application_type": "web", - "client_id": "https://rp.example.it", - "client_name": "Name of an example organization", - "jwks": { - "keys": [ - { - "kty": "EC", - "use": "sig", - "crv": "P-256", - "x": "1kNR9Ar3MzMokYTY8BRvRIue85NIXrYX4XD3K4JW7vI", - "y": "slT14644zbYXYF-xmw7aPdlbMuw3T1URwI4nafMtKrY", - "kid": "YhNFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", - "x5c": [ "..." ] - } - ] - }, - - "contacts": [ - "ops@relying-party.example.org" - ], - - "request_uris": [ - "https://relying-party.example.org/request_uri" - ], - "redirect_uris": [ - "https://relying-party.example.org/callback" - ], - - "default_acr_values": [ - "https://www.spid.gov.it/SpidL2", - "https://www.spid.gov.it/SpidL3" - ], - "vp_formats": { - "vc+sd-jwt": { - "sd-jwt_alg_values": [ - "ES256", - "ES384" - ], - "kb-jwt_alg_values": [ - "ES256", - "ES384" - ] - } - }, - "presentation_definitions": [ - { - "id": "eu.europa.ec.eudiw.pid.it.1", - "input_descriptors": [ - { - "id": "IdentityCredential", - "format": { - "vc+sd-jwt": {} - }, - "constraints": { - "limit_disclosure": "required", - "fields": [ - { - "path": [ - "$.type" - ], - "filter": { - "type": "string", - "const": "IdentityCredential" - } - }, - { - "path": [ - "$.family_name" - ] - }, - { - "path": [ - "$.given_name" - ] - }, - { - "path": [ - "$.unique_id" - ], - "intent_to_retain": "true" - } - ] - } - } - ] - }, - { - "id": "mDL-sample-req", - "input_descriptors": [ - { - "id": "mDL", - "format": { - "mso_mdoc": { - "alg": [ - "EdDSA", - "ES256" - ] - }, - "constraints": { - "limit_disclosure": "required", - "fields": [ - { - "path": [ - "$.mdoc.doctype" - ], - "filter": { - "type": "string", - "const": "org.iso.18013.5.1.mDL" - } - }, - { - "path": [ - "$.mdoc.namespace" - ], - "filter": { - "type": "string", - "const": "org.iso.18013.5.1" - } - }, - { - "path": [ - "$.mdoc.family_name" - ], - "intent_to_retain": "false" - }, - { - "path": [ - "$.mdoc.portrait" - ], - "intent_to_retain": "false" - }, - { - "path": [ - "$.mdoc.driving_privileges" - ], - "intent_to_retain": "false" - } - ] - } - } - } - ] - } - ], - "default_max_age": 1111, - - // JARM related - "authorization_signed_response_alg": [[ - "ES256", - "ES384" - ], - "authorization_encrypted_response_alg": [ - "RSA-OAEP-256", - ], - "subject_type": "pairwise", - "require_auth_time": true, - "id_token_signed_response_alg": [ - "ES256", - "ES384" - ], - "id_token_encrypted_response_alg": [ - "RSA-OAEP-256" - ], - "id_token_encrypted_response_enc": [ - "A128CBC-HS256", - "A192CBC-HS384", - "A256CBC-HS512", - "A128GCM", - "A192GCM", - "A256GCM" - ], - }, - "federation_entity": { - "organization_name": "OpenID Wallet Relying Party example", - "homepage_uri": "https://relying-party.example.org/home", - "policy_uri": "https://relying-party.example.org/policy", - "logo_uri": "https://relying-party.example.org/static/logo.svg", - "contacts": [ - "tech@relying-party.example.org" - ] - } - }, - "authority_hints": [ - "https://registry.eudi-wallet.example.it" - ] - } - } - - -The Entity Configuration is a JWS, where its header parameters are defined below: - -.. list-table:: - :widths: 25 50 - :header-rows: 1 - - * - **Name** - - **Description** - * - **alg** - - Algorithm used to sign the JWT - * - **typ** - - Media Type of the JWT - * - **kid** - - Key ID used identifying the key used to sign the JWS +- :ref:`Remote Flow `, where the User presents a Credential to a remote Relying Party according to `OPENID4VP`_. In this scenario the user-agent and the Wallet Instance may be used in the same device (**Same Device Flow**), or in different devices (**Cross Device Flow**). +- :ref:`Proximity Flow `, where the User presents a Credential to a Verifier App according to ISO 18013-5. The User interacts with a Verifier using proximity connection technologies such as QR Code and Bluetooth Low Energy (BLE). +.. include:: remote-flow.rst -.. note: - The Relying Party specific metadata parameter are experimental - and still under discussion `here `_. +.. include:: proximity-flow.rst diff --git a/docs/en/remote-flow.rst b/docs/en/remote-flow.rst index 0cd04af47..aa23ce488 100644 --- a/docs/en/remote-flow.rst +++ b/docs/en/remote-flow.rst @@ -57,7 +57,7 @@ The details of each step shown in the previous picture are described in the tabl * - **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. + - 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** - 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**