diff --git a/README.md b/README.md index 911e8d53a..f61673da8 100644 --- a/README.md +++ b/README.md @@ -85,7 +85,7 @@ Each time a release is created or edited, a preview is built based on the tag th ## How to contribute -Feel free to open [Pull Requests and to present a problem with an Issue](CONTRIBUTING.md). +Don't hesitate to submit [Pull Requests or raise Issues](CONTRIBUTING.md) if you encounter any problems. ## License diff --git a/docs/en/conf.py b/docs/en/conf.py index dd23e066e..d800baa6c 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -281,5 +281,5 @@ def setup(app): numfig = True -# to turn smartquotes off and be able to use ’ +# to turn smartquotes off and be able to use smartquotes = False diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index 6f8e1c0e4..a6004323c 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -29,15 +29,17 @@ Below are the description of acronyms and definitions which are useful for furth - An entity, recognized and accredited by the State, responsible for identifying citizens for the issuance of an Electronic Identity Certificate. * - Electronic Attestation of Identity - Electronic attestation of attributes referring to master data already present in Italian digital identity systems. + * - Digital Credential + - An signed Credential whose integrity can be cryptographically verified using the public keys of its Issuer. It is also known as Credential. * - Federation Authority - A public governance entity that issues guidelines and technical rules, and administers - directly or through its intermediary - Trusted Lists, services, and accreditation processes, the status of participants, and their eligibility evaluation. It also performs oversight functions. * - Wallet Instance - An instance of the Wallet Solution, installed on a personal mobile device and controlled by a specific User who is its sole owner. It is the application that enables citizens to fully and autonomously manage their digital identity and EAAs. * - Wallet Provider - All public and/or private entities, conforming to a technical profile and accredited by the Federation Authority, that provide citizens with an IT Wallet Instance. - * - Wallet Instance Attestation + * - Wallet Attestation - Verifiable Attestation, issued by the Wallet Provider, that proves the security compliace of the Wallet Instance. - * - App Attestation Service + * - Wallet Attestation Service - Device manufacturer service that allows you to certify the authenticity of the mobile app (Wallet Instance). * - Qualified Electronic Attestation of Attributes (QEAA) - A digitally verifiable attestation in electronic form, issued by a QTSP, that substantiates a person's possession of attributes. @@ -45,12 +47,16 @@ Below are the description of acronyms and definitions which are useful for furth - The Electronic Trust Service Provider responsible for the issuing of Qualified Electronic Signature certificates to the User. * - Relying Party - A natural or legal person that implements an authentication system requiring electronic attribute attestation submissions as an authentication mechanism. + * - Verifier + - See Relying Party. * - Trust Attestation - Electronic attestation of an entity's compliance with the national regulatory framework, which is cryptographically verifiable and cannot be repudiated over time by the entity that issued it. A Trust Attestation is always related to a particular Trust Framework. * - Trust Layer - An architectural component that enables IT Wallet system participants to establish trust, in terms of reliability and compliance of all participants with the regulatory framework governing the digital identity system. + * - Trust Model + - System defining how the participants of the ecosystem establish and maintain trust in their interactions. The Trust Model outlines the rules and the procedures for the entities (like users, systems, or applications) should validate each other's identities, authenticate, and establish the level of trust before exchanging information. * - Level of Assurance - - The degree of confidence in the vetting process used to establish the identity of the User and the degree of confidence that the User who presents the credential is the same User to whom the credential was issued. + - The degree of confidence in the vetting process used to establish the identity of the User and the degree of confidence that the User who presents the credential is the same User to whom the Digital Credential was issued. * - Holder Key Binding - Ability of the Holder to prove legitimate possession of the private part, related to the public part attested by a Trusted Third Party. @@ -75,4 +81,3 @@ Acronyms - Application Programming Interface * - **LoA** - Level of Assurance - diff --git a/docs/en/index.rst b/docs/en/index.rst index 3761bdc08..a25387a11 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -27,7 +27,7 @@ This documentation defines the national implementation profile of EUDI Wallet, c - PID/EAA in MDL CBOR format. - PID/EAA in `SD-JWT`_ format. - Wallet Solution general architecture. - - Wallet Instance Attestation. + - Wallet Attestation. - Issuance of PID/EAA according to `OpenID4VCI`_. - Presentation of PID/EAA according to `OpenID4VP`_. - Presentation of pseudonyms according to `SIOPv2`_. @@ -44,7 +44,7 @@ Index of content defined-terms.rst trust.rst wallet-solution.rst - wallet-instance-attestation.rst + wallet-attestation.rst pid-eaa-data-model.rst pid-eaa-issuance.rst relying-party-solution.rst diff --git a/docs/en/pid-eaa-data-model.rst b/docs/en/pid-eaa-data-model.rst index de6bf9d36..77d1128ab 100644 --- a/docs/en/pid-eaa-data-model.rst +++ b/docs/en/pid-eaa-data-model.rst @@ -12,7 +12,6 @@ The User attributes provided within the Italian PID are the ones listed below: - Current Family Name - Current First Name - Date of Birth - - Place of Birth - Unique Identifier - Taxpayer identification number @@ -75,7 +74,7 @@ The JOSE header contains the following mandatory parameters: - JSON array containing the trust chain that proves the reliability of the issuer of the JWT. - `[OIDC-FED, Section 3.2.1] `_. -The following claims MUST be in the JWT payload and MUST NOT be included in the disclosures, i.e. cannot be selectively disclosed. +The following claims MUST be in the JWT payload. Some of these claims can be disclosed, these are listed in the following tables that specify whether a claim is selectively disclosable [SD] or not [NSD]. .. list-table:: :widths: 20 60 20 @@ -85,31 +84,31 @@ The following claims MUST be in the JWT payload and MUST NOT be included in the - **Description** - **Reference** * - **iss** - - URL string representing the PID/(Q)EAA Issuer unique identifier. + - [NSD].URL string representing the PID/(Q)EAA Issuer unique identifier. - `[RFC7519, Section 4.1.1] `_. * - **sub** - - Thumbprint of the JWK in the ``cnf`` parameter. + - [NSD].Thumbprint of the JWK in the ``cnf`` parameter. - `[RFC7519, Section 4.1.2] `_. * - **jti** - - Unique Token ID identifier of this JWT. It SHOULD be a String in *uuid4* format. + - [NSD].Unique Token ID identifier of this JWT. It SHOULD be a String in *uuid4* format. - `[RFC7519, Section 4.1.7] `_. * - **iat** - - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. + - [SD].UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. - `[RFC7519, Section 4.1.6] `_. * - **exp** - - UNIX Timestamp with the expiry time of the JWT, coded as NumericDate as indicated in :rfc:`7519`. + - [NSD].UNIX Timestamp with the expiry time of the JWT, coded as NumericDate as indicated in :rfc:`7519`. - `[RFC7519, Section 4.1.4] `_. * - **status** - - HTTPS URL where the credential validity status is available. + - [NSD].HTTPS URL where the credential validity status is available. - `[SD-JWT-VC. Section 4.2.2.2] `_. * - **cnf** - - JSON object containing the proof-of-possession key materials. By including a **cnf** (confirmation) claim in a JWT, the issuer of the JWT declares that the Holder is in control of the private key related to the public one defined in the **cnf** parameter. The recipient MUST cryptographically verify that the Holder is in control of that key. + - [NSD].JSON object containing the proof-of-possession key materials. By including a **cnf** (confirmation) claim in a JWT, the issuer of the JWT declares that the Holder is in control of the private key related to the public one defined in the **cnf** parameter. The recipient MUST cryptographically verify that the Holder is in control of that key. - `[RFC7800, Section 3.1] `_. * - **vct** - - Credential type as a string, MUST be set in accordance to the type obtained from the PID/(Q)EAA Issuer metadata. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData``. + - [NSD].Credential type as a string, MUST be set in accordance to the type obtained from the PID/(Q)EAA Issuer metadata. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData``. - `[draft-terbu-sd-jwt-vc-latest. Section Type Claim] `__. * - **verified_claims** - - JSON object containing the following sub-elements: + - [NSD].JSON object containing the following sub-elements: - **verification**; - **claims**. @@ -120,7 +119,7 @@ The following claims MUST be in the JWT payload and MUST NOT be included in the PID/(Q)EAA Verification field ----------------------------- -The ``verification`` claim contains the information regarding the trust framework used by the PID/(Q)EAA Issuer to provide the User attributes (claims). Some of these additional claims MAY be selectively disclosed, these are listed in the following tables that specify whether a claim is selectively disclosable (SD) or not (NSD). +The ``verification`` claim contains the information regarding the trust framework used by the PID/(Q)EAA Issuer to provide the User attributes (claims). The ``verification`` claim is a JSON structure with all the following mandatory sub-claims. @@ -188,33 +187,34 @@ The ``claims`` parameter contains the User attributes with the following mandato * - **family_name** - [SD]. Current Family Name. - `[OpenID Connect Core 1.0, Section 5.1] `_ - * - **birthdate** + * - **birth_date** - [SD]. Date of Birth. - - `[OpenID Connect Core 1.0, Section 5.1] `_ - * - **place_of_birth** - - [SD]. Place of Birth. JSON Object with the following subclaims: - - - **country** - - **locality** - - `[OpenID Connect for Identity Assurance 1.0, Section 4] `_ + - * - **unique_id** - [SD]. Unique citizen identifier (ID ANPR) given by the National Register of the Resident Population (ANPR). It MUST be set according to `ANPR rules `_ - - This specification + - * - **tax_id_code** - [SD]. National tax identification code of natural person as a String format. It MUST be set according to ETSI EN 319 412-1. For example ``TINIT-`` - - This specification + - PID Non-normative Examples -------------------------- -In the following, the non-normative example of a PID. +In the following, the non-normative example of a PID in JSON format. .. code-block:: JSON { - "verified_claims": { + "iss": "https://issuer.example.org", + "sub": "NzbLsXh8uDCcd7noWXFZAfHkxZsRGC9Xs", + "jti": "urn:uuid:6c5c0a49-b589-431d-bae7-219122a9ec2c", + "iat": 1683000000, + "exp": 1883000000, + "status": "https://pidprovider.example.org/status", + "vct": "PersonIdentificationData", + "verified_claims": { "verification": { "trust_framework": "eidas", "assurance_level": "high", @@ -225,7 +225,8 @@ In the following, the non-normative example of a PID. "type": "https://eudi.wallet.cie.gov.it", "source": { "organization_name": "Ministero dell'Interno", - "organization_id": "m_it", + "organization_id": + "urn:eudi:it:organization_id:ipa_code:m_it", "country_code": "IT" } } @@ -233,15 +234,10 @@ In the following, the non-normative example of a PID. ] }, "claims": { - "unique_id": - "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "unique_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "given_name": "Mario", "family_name": "Rossi", - "birthdate": "1980-01-10", - "place_of_birth": { - "country": "IT", - "locality": "Rome" - }, + "birth_date": "1980-01-10", "tax_id_code": "TINIT-XXXXXXXXXXXXXXXX" } } @@ -265,11 +261,13 @@ The corresponding SD-JWT verson for PID is given by .. code-block:: JSON { - "iss": "https://pidprovider.example.org", - "sub": "NzbLsXh8uDCcd7noWXFZAfHkxZsRGC9Xs...", + "_sd": [ + "7WG4nT6K26_R3975zcwnVwgoHA7b988_3-vJzbZf6Yc" + ], + "iss": "https://issuer.example.org", + "exp": 1883000000, + "sub": "NzbLsXh8uDCcd7noWXFZAfHkxZsRGC9Xs", "jti": "urn:uuid:6c5c0a49-b589-431d-bae7-219122a9ec2c", - "iat": 1541493724, - "exp": 1541493724, "status": "https://pidprovider.example.org/status", "cnf": { "jwk": { @@ -281,101 +279,155 @@ The corresponding SD-JWT verson for PID is given by } }, "type": "PersonIdentificationData", + "vct": "PersonIdentificationData", "verified_claims": { "verification": { "_sd": [ - "OGm7ryXgt5Xzlevp-Hu-UTk0a-TxAaPAobqv1pIWMfw" + "gd8gRxKT1hg8ptnvR5fPGhae0VXllDblsiJT9adxiS8" ], "trust_framework": "eidas", "assurance_level": "high" }, "claims": { "_sd": [ - "8JjozBfovMNvQ3HflmPWy4O19Gpxs61FWHjZebU589E", - "BoMGktW1rbikntw8Fzx_BeL4YbAndr6AHsdgpatFCig", - "CFLGzentGNRFngnLVVQVcoAFi05r6RJUX-rdbLdEfew", - "JU_sTaHCngS32X-0ajHrd1-HCLCkpT5YqgcfQme168w", - "VQI-S1mT1Kxfq2o8J9io7xMMX2MIxaG9M9PeJVqrMcA", - "zVdghcmClMVWlUgGsGpSkCPkEHZ4u9oWj1SlIBlCc1o" + "4g9lBt38U1EeTA1zlvvGfFgPPcoe3zmbQ_zSRDgHQaE", + "EYgzJ1hTYWJjhBK2V3b8HV3e_fEf-Udffc5ymY77WtQ", + "IcYHQydT_C3U1IqaJlFicxLlaHTHvElyFZ6Jxia27qQ", + "KxIG8rWXmtR884xTV7eXuHICfPYPw6gFvfr07v-d5oc", + "lXgxEDAuPeUvmkcNGr9FZuqodwFqUT01gJj7xd4yEPA" ] } }, - "_sd_alg": "sha-256" + "_sd_alg": "sha-256", + "cnf": { + "jwk": { + "kty": "EC", + "crv": "P-256", + "x": "TCAER19Zvu3OHF4j4W4vfSVoHIP1ILilDls7vCeGemc", + "y": "ZxjiWWbZMQGHVWKVQ4hbSIirsVfuecCE6t4jT9F2HZQ" + } + } } In the following the disclosure list is given -Claim **evidence**: +**Claim** ``iat``: -- SHA-256 Hash: ``OGm7ryXgt5Xzlevp-Hu-UTk0a-TxAaPAobqv1pIWMfw`` +- SHA-256 Hash: ``7WG4nT6K26_R3975zcwnVwgoHA7b988_3-vJzbZf6Yc`` - Disclosure: - ``WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwgImV2aWRlbmNlIiwgW3sidHlw`` - ``ZSI6ICJlbGVjdHJvbmljX3JlY29yZCIsICJyZWNvcmQiOiB7InR5cGUiOiAi`` - ``ZWlkYXMuaXQuY2llIiwgInNvdXJjZSI6IHsib3JnYW5pemF0aW9uX25hbWUi`` - ``OiAiTWluaXN0ZXJvIGRlbGwnSW50ZXJubyIsICJvcmdhbml6YXRpb25faWQi`` - ``OiAibV9pdCIsICJjb3VudHJ5X2NvZGUiOiAiSVQifX19XV0`` -- Contents: ``["2GLC42sKQveCfGfryNRN9w", "evidence", [{"type":`` - ``"electronic_record", "record": {"type": "https://eudi.wallet.cie.gov.it",`` - ``"source": {"organization_name": "Ministero dell'Interno",`` - ``"organization_id": "m_it", "country_code": "IT"}}}]]`` - -Claim **unique_id**: - -- SHA-256 Hash: ``BoMGktW1rbikntw8Fzx_BeL4YbAndr6AHsdgpatFCig`` + ``WyI1N212eWNUaDV5WkNyS0xaNXhuZlV3IiwgImlhdCIsIDE2ODMwMDAwMDBd`` +- Contents: ``["57mvycTh5yZCrKLZ5xnfUw", "iat", 1683000000]`` + +**Claim** ``source``: + +- SHA-256 Hash: ``ZMHbFH9SeT9CZQaOMVrXDMGWIouzXRKspKp9fDhvJ3I`` - Disclosure: - ``WyJlbHVWNU9nM2dTTklJOEVZbnN4QV9BIiwgInVuaXF1ZV9pZCIsICJ4eHh4`` + ``WyJrdWNyQm1sb19oTWFJRkY1ODVSemFRIiwgInNvdXJjZSIsIHsib3JnYW5p`` + ``emF0aW9uX25hbWUiOiAiTWluaXN0ZXJvIGRlbGwnSW50ZXJubyIsICJvcmdh`` + ``bml6YXRpb25faWQiOiAidXJuOmV1ZGk6aXQ6b3JnYW5pemF0aW9uX2lkOmlw`` + ``YV9jb2RlOm1faXQiLCAiY291bnRyeV9jb2RlIjogIklUIn1d`` +- Contents: + ``["kucrBmlo_hMaIFF585RzaQ", "source", {"organization_name":`` + ``"Ministero dell'Interno", "organization_id":`` + ``"urn:eudi:it:organization_id:ipa_code:m_it", "country_code":`` + ``"IT"}]`` + +**Claim** ``evidence``: + +- SHA-256 Hash: ``gd8gRxKT1hg8ptnvR5fPGhae0VXllDblsiJT9adxiS8`` +- Disclosure: + ``WyJOVE5Sb09pdVZWUnRGNkNFenRkOVp3IiwgImV2aWRlbmNlIiwgW3sidHlw`` + ``ZSI6ICJlbGVjdHJvbmljX3JlY29yZCIsICJyZWNvcmQiOiB7Il9zZCI6IFsi`` + ``Wk1IYkZIOVNlVDlDWlFhT01WclhETUdXSW91elhSS3NwS3A5ZkRodkozSSJd`` + ``LCAidHlwZSI6ICJodHRwczovL2V1ZGkud2FsbGV0LmNpZS5nb3YuaXQifX1d`` + ``XQ`` +- Contents: ``["NTNRoOiuVVRtF6CEztd9Zw", "evidence", [{"type":`` + ``"electronic_record", "record": {"_sd":`` + ``["ZMHbFH9SeT9CZQaOMVrXDMGWIouzXRKspKp9fDhvJ3I"], "type":`` + ``"https://eudi.wallet.cie.gov.it"}}]]`` + +**Claim** ``unique_id``: + +- SHA-256 Hash: ``4g9lBt38U1EeTA1zlvvGfFgPPcoe3zmbQ_zSRDgHQaE`` +- Disclosure: + ``WyJGRFNTUGdnekdCVXdRTEhEU0U2d1FRIiwgInVuaXF1ZV9pZCIsICJ4eHh4`` ``eHh4eC14eHh4LXh4eHgteHh4eC14eHh4eHh4eHh4eHgiXQ`` -- Contents: ``["eluV5Og3gSNII8EYnsxA_A", "unique_id",`` +- Contents: ``["FDSSPggzGBUwQLHDSE6wQQ", "unique_id",`` ``"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"]`` -Claim **given_name**: +**Claim** ``given_name``: -- SHA-256 Hash: ``zVdghcmClMVWlUgGsGpSkCPkEHZ4u9oWj1SlIBlCc1o`` +- SHA-256 Hash: ``lXgxEDAuPeUvmkcNGr9FZuqodwFqUT01gJj7xd4yEPA`` - Disclosure: - ``WyI2SWo3dE0tYTVpVlBHYm9TNXRtdlZBIiwgImdpdmVuX25hbWUiLCAiTWFy`` + ``WyJLWjhlNXdWRXREdmIxemlTUEE0RHpBIiwgImdpdmVuX25hbWUiLCAiTWFy`` ``aW8iXQ`` -- Contents: ``["6Ij7tM-a5iVPGboS5tmvVA", "given_name", "Mario"]`` +- Contents: ``["KZ8e5wVEtDvb1ziSPA4DzA", "given_name", "Mario"]`` -Claim **family_name**: +**Claim** ``family_name``: -- SHA-256 Hash: ``VQI-S1mT1Kxfq2o8J9io7xMMX2MIxaG9M9PeJVqrMcA`` +- SHA-256 Hash: ``IcYHQydT_C3U1IqaJlFicxLlaHTHvElyFZ6Jxia27qQ`` - Disclosure: - ``WyJlSThaV205UW5LUHBOUGVOZW5IZGhRIiwgImZhbWlseV9uYW1lIiwgIlJv`` + ``WyJwWjVNUnlPeHBWV1p1SExvSi15alJnIiwgImZhbWlseV9uYW1lIiwgIlJv`` ``c3NpIl0`` -- Contents: ``["eI8ZWm9QnKPpNPeNenHdhQ", "family_name", "Rossi"]`` +- Contents: ``["pZ5MRyOxpVWZuHLoJ-yjRg", "family_name", "Rossi"]`` -Claim **birthdate**: +**Claim** ``birth_date``: -- SHA-256 Hash: ``CFLGzentGNRFngnLVVQVcoAFi05r6RJUX-rdbLdEfew`` +- SHA-256 Hash: ``EYgzJ1hTYWJjhBK2V3b8HV3e_fEf-Udffc5ymY77WtQ`` - Disclosure: - ``WyJRZ19PNjR6cUF4ZTQxMmExMDhpcm9BIiwgImJpcnRoZGF0ZSIsICIxOTgw`` - ``LTAxLTEwIl0`` -- Contents: ``["Qg_O64zqAxe412a108iroA", "birthdate", "1980-01-10"]`` + ``WyJqdFZ1S0NwbjdiVGNIckFnX3NlVWJRIiwgImJpcnRoX2RhdGUiLCAiMTk4`` + ``MC0wMS0xMCJd`` +- Contents: ``["jtVuKCpn7bTcHrAg_seUbQ", "birth_date", "1980-01-10"]`` -Claim **place_of_birth**: +**Claim** ``tax_id_code``: -- SHA-256 Hash: ``JU_sTaHCngS32X-0ajHrd1-HCLCkpT5YqgcfQme168w`` +- SHA-256 Hash: ``KxIG8rWXmtR884xTV7eXuHICfPYPw6gFvfr07v-d5oc`` - Disclosure: - ``WyJBSngtMDk1VlBycFR0TjRRTU9xUk9BIiwgInBsYWNlX29mX2JpcnRoIiwg`` - ``eyJjb3VudHJ5IjogIklUIiwgImxvY2FsaXR5IjogIlJvbWUifV0`` -- Contents: - ``["AJx-095VPrpTtN4QMOqROA", "place_of_birth", {"country":`` - ``"IT", "locality": "Rome"}]`` - -Claim **tax_id_code**: - -- SHA-256 Hash: ``8JjozBfovMNvQ3HflmPWy4O19Gpxs61FWHjZebU589E`` -- Disclosure: - ``WyJQYzMzSk0yTGNoY1VfbEhnZ3ZfdWZRIiwgInRheF9pZF9jb2RlIiwgIlRJ`` + ``WyI0a3NBejZiTVVLeTZadk4xaDhIRHVRIiwgInRheF9pZF9jb2RlIiwgIlRJ`` ``TklULVhYWFhYWFhYWFhYWFhYWFgiXQ`` -- Contents: ``["Pc33JM2LchcU_lHggv_ufQ", "tax_id_code",`` +- Contents: ``["4ksAz6bMUKy6ZvN1h8HDuQ", "tax_id_code",`` ``"TINIT-XXXXXXXXXXXXXXXX"]`` + + The combined format for the PID issuance is given by .. code-block:: - eyJ0eXAiOiJ2YytzZC1qd3QiLCJhbGciOiJSUzUxMiIsImtpZCI6ImQxMjZhNmE4NTZmNzcyNDU2MDQ4NGZhOWRjNTlkMTk1IiwidHJ1c3RfY2hhaW4iOlsiTkVoUmRFUnBZbmxIWTNNNVdsZFdUV1oyYVVobSAuLi4iLCJleUpoYkdjaU9pSlNVekkxTmlJc0ltdHBaQ0k2IC4uLiIsIklrSllkbVp5Ykc1b1FVMTFTRkl3TjJGcVZXMUIgLi4uIl19.eyJpc3MiOiJodHRwczovL3BpZHByb3ZpZGVyLmV4YW1wbGUub3JnIiwic3ViIjoiTnpiTHNYaDh1RENjZDdub1dYRlpBZkhreFpzUkdDOVhzLi4uIiwianRpIjoidXJuOnV1aWQ6NmM1YzBhNDktYjU4OS00MzFkLWJhZTctMjE5MTIyYTllYzJjIiwiaWF0IjoxNTQxNDkzNzI0LCJleHAiOjE1NDE0OTM3MjQsInN0YXR1cyI6Imh0dHBzOi8vcGlkcHJvdmlkZXIuZXhhbXBsZS5vcmcvc3RhdHVzIiwiY25mIjp7Imp3ayI6eyJrdHkiOiJSU0EiLCJ1c2UiOiJzaWciLCJuIjoiMVRhLXNFIOKApiIsImUiOiJBUUFCIiwia2lkIjoiWWhORlMzWW5DOXRqaUNhaXZoV0xWVUozQXh3R0d6Xzk4dVJGYXFNRUVzIn19LCJ0eXBlIjoiUGVyc29uSWRlbnRpZmljYXRpb25EYXRhIiwidmVyaWZpZWRfY2xhaW1zIjp7InZlcmlmaWNhdGlvbiI6eyJfc2QiOlsiT0dtN3J5WGd0NVh6bGV2cC1IdS1VVGswYS1UeEFhUEFvYnF2MXBJV01mdyJdLCJ0cnVzdF9mcmFtZXdvcmsiOiJlaWRhcyIsImFzc3VyYW5jZV9sZXZlbCI6ImhpZ2gifSwiY2xhaW1zIjp7Il9zZCI6WyI4SmpvekJmb3ZNTnZRM0hmbG1QV3k0TzE5R3B4czYxRldIalplYlU1ODlFIiwiQm9NR2t0VzFyYmlrbnR3OEZ6eF9CZUw0WWJBbmRyNkFIc2RncGF0RkNpZyIsIkNGTEd6ZW50R05SRm5nbkxWVlFWY29BRmkwNXI2UkpVWC1yZGJMZEVmZXciLCJKVV9zVGFIQ25nUzMyWC0wYWpIcmQxLUhDTENrcFQ1WXFnY2ZRbWUxNjh3IiwiVlFJLVMxbVQxS3hmcTJvOEo5aW83eE1NWDJNSXhhRzlNOVBlSlZxck1jQSIsInpWZGdoY21DbE1WV2xVZ0dzR3BTa0NQa0VIWjR1OW9XajFTbElCbENjMW8iXX19LCJfc2RfYWxnIjoic2hhLTI1NiJ9.WzEiFaOjnobQisjTQ92JtKEXRN-2Sgvjklpu4IdC_cT2T6Tm8Z6sqbVy6n94AAEv-HFSv5JoSt6YjPDnGzOxN_W_131rILU8YaiNt8w31nRGIvHjJIC0w-hHIcG1LmvJshSMcT3RHeApRCmsO7xkHWmUsjt37dOzEagEti5i47hnZAbu7vWXsvUlBNNN8v7tJBLspO2Q0vnWhEDX1hQ7IH1b8oKh-_aQrhwVm9Bcs9CG8o6N9iqubCSpFI6Gty4ZZgHEb95knETVhw8IL10Z9P_Hr9twXZQaCCC8xrNh4afwR9TiDQzTr92m7luyvDfmzVgHCponI7VBhqmRqZVYQyDhq6EJbtRtIsYenla5NSKBjV8Etdlec94vJAHZNzue9aNUQeXae55V5m5O9wLoWhgV2vl4xV5C-N5s5Uzs08GAxo-CUaNOD3BQE9vfrT47IBCm4hUCnvDise_aWNCeKOQABV1J9_tV9lWZsECVuUuWWwELHCUXgdyiA3QtUtXz + eyJhbGciOiAiRVMyNTYiLCAidHlwIjogImV4YW1wbGUrc2Qtand0In0.eyJfc2QiOiBb + IjdXRzRuVDZLMjZfUjM5NzV6Y3duVndnb0hBN2I5ODhfMy12SnpiWmY2WWMiXSwgImlz + cyI6ICJodHRwczovL3BpZHByb3ZpZGVyLmV4YW1wbGUub3JnIiwgImV4cCI6IDE4ODMw + MDAwMDAsICJzdWIiOiAiTnpiTHNYaDh1RENjZDdub1dYRlpBZkhreFpzUkdDOVhzIiwg + Imp0aSI6ICJ1cm46dXVpZDo2YzVjMGE0OS1iNTg5LTQzMWQtYmFlNy0yMTkxMjJhOWVj + MmMiLCAic3RhdHVzIjogImh0dHBzOi8vcGlkcHJvdmlkZXIuZXhhbXBsZS5vcmcvc3Rh + dHVzIiwgInZjdCI6ICJQaWRJZGVudGlmaWNhdGlvbkRhdGEiLCAidmVyaWZpZWRfY2xh + aW1zIjogeyJ2ZXJpZmljYXRpb24iOiB7Il9zZCI6IFsiZ2Q4Z1J4S1QxaGc4cHRudlI1 + ZlBHaGFlMFZYbGxEYmxzaUpUOWFkeGlTOCJdLCAidHJ1c3RfZnJhbWV3b3JrIjogImVp + ZGFzIiwgImFzc3VyYW5jZV9sZXZlbCI6ICJoaWdoIn0sICJjbGFpbXMiOiB7Il9zZCI6 + IFsiNGc5bEJ0MzhVMUVlVEExemx2dkdmRmdQUGNvZTN6bWJRX3pTUkRnSFFhRSIsICJF + WWd6SjFoVFlXSmpoQksyVjNiOEhWM2VfZkVmLVVkZmZjNXltWTc3V3RRIiwgIkljWUhR + eWRUX0MzVTFJcWFKbEZpY3hMbGFIVEh2RWx5Rlo2SnhpYTI3cVEiLCAiS3hJRzhyV1ht + dFI4ODR4VFY3ZVh1SElDZlBZUHc2Z0Z2ZnIwN3YtZDVvYyIsICJsWGd4RURBdVBlVXZt + a2NOR3I5Rlp1cW9kd0ZxVVQwMWdKajd4ZDR5RVBBIl19fSwgIl9zZF9hbGciOiAic2hh + LTI1NiIsICJjbmYiOiB7Imp3ayI6IHsia3R5IjogIkVDIiwgImNydiI6ICJQLTI1NiIs + ICJ4IjogIlRDQUVSMTladnUzT0hGNGo0VzR2ZlNWb0hJUDFJTGlsRGxzN3ZDZUdlbWMi + LCAieSI6ICJaeGppV1diWk1RR0hWV0tWUTRoYlNJaXJzVmZ1ZWNDRTZ0NGpUOUYySFpR + In19fQ.1xdAqLpgMM0bBDQrYv0thRwtgRikZq75JJVhGyfWAsu8SopmhumzsTA4ohJKC + le1MV3UB6DYMFkEnoal8R1Yrw~WyI1N212eWNUaDV5WkNyS0xaNXhuZlV3IiwgImlhdC + IsIDE2ODMwMDAwMDBd~WyJrdWNyQm1sb19oTWFJRkY1ODVSemFRIiwgInNvdXJjZSIsI + Hsib3JnYW5pemF0aW9uX25hbWUiOiAiTWluaXN0ZXJvIGRlbGwnSW50ZXJubyIsICJvc + mdhbml6YXRpb25faWQiOiAidXJuOmV1ZGk6aXQ6b3JnYW5pemF0aW9uX2lkOmlwYV9jb + 2RlOm1faXQiLCAiY291bnRyeV9jb2RlIjogIklUIn1d~WyJOVE5Sb09pdVZWUnRGNkNF + enRkOVp3IiwgImV2aWRlbmNlIiwgW3sidHlwZSI6ICJlbGVjdHJvbmljX3JlY29yZCIs + ICJyZWNvcmQiOiB7Il9zZCI6IFsiWk1IYkZIOVNlVDlDWlFhT01WclhETUdXSW91elhS + S3NwS3A5ZkRodkozSSJdLCAidHlwZSI6ICJodHRwczovL2V1ZGkud2FsbGV0LmNpZS5n + b3YuaXQifX1dXQ~WyJGRFNTUGdnekdCVXdRTEhEU0U2d1FRIiwgInVuaXF1ZV9pZCIsI + CJ4eHh4eHh4eC14eHh4LXh4eHgteHh4eC14eHh4eHh4eHh4eHgiXQ~WyJLWjhlNXdWRX + REdmIxemlTUEE0RHpBIiwgImdpdmVuX25hbWUiLCAiTWFyaW8iXQ~WyJwWjVNUnlPeHB + WV1p1SExvSi15alJnIiwgImZhbWlseV9uYW1lIiwgIlJvc3NpIl0~WyJqdFZ1S0Nwbjd + iVGNIckFnX3NlVWJRIiwgImJpcnRoX2RhdGUiLCAiMTk4MC0wMS0xMCJd~WyJXRGtkNk + pzTmhERnZMUDRzMWhRZHlBIiwgInRheF9pZF9jb2RlIiwgIlRJTklULVhYWFhYWFhYWF + hYWFhYWFgiXQ~ (Q)EAA Non-normative examples ----------------------------- @@ -385,7 +437,14 @@ In the following, we provide a non-normative example of (Q)EAA in JSON. .. code-block:: JSON { - "verified_claims": { + "iss": "https://issuer.example.org", + "sub": "NzbLsXh8uDCcd7noWXFZAfHkxZsRGC9Xs", + "jti": "urn:uuid:6c5c0a49-b589-431d-bae7-219122a9ec2c", + "iat": 1683000000, + "exp": 1883000000, + "status": "https://issuer.example.org/status", + "vct": "DisabilityCard", + "verified_claims": { "verification": { "trust_framework": "eidas", "assurance_level": "high", @@ -395,8 +454,9 @@ In the following, we provide a non-normative example of (Q)EAA in JSON. "record": { "type": "https://eudi.wallet.pdnd.gov.it", "source": { - "organization_name": "Ragioneria Generale dello Stato", - "organization_id": "urn:eudi:it:organization_id:ipa_code:QLHCFC", + "organization_name": "Istituto Nazionale della Previdenza Sociale", + "organization_id": + "urn:eudi:it:organization_id:ipa_code:inps", "country_code": "IT" } } @@ -404,14 +464,13 @@ In the following, we provide a non-normative example of (Q)EAA in JSON. ] }, "claims": { + "document_number": "XXXXXXXXXX", "given_name": "Mario", "family_name": "Rossi", - "birthdate": "1980-01-10", - "place_of_birth": { - "country": "IT", - "locality": "Rome" - }, - "tax_id_code": "TINIT-XXXXXXXXXXXXXXXX" + "birth_date": "1980-01-10", + "expiry_date": "2024-01-01", + "tax_id_code": "TINIT-XXXXXXXXXXXXXXXX", + "constant_attendance_allowance": true } } } @@ -434,11 +493,13 @@ The corresponding SD-JWT for the previous data is represented as follow, as deco .. code-block:: JSON { + "_sd": [ + "7WG4nT6K26_R3975zcwnVwgoHA7b988_3-vJzbZf6Yc" + ], "iss": "https://issuer.example.org", - "sub": "NzbLsXh8uDCcd7noWXFZAfHkxZsRGC9Xs...", + "exp": 1883000000, + "sub": "NzbLsXh8uDCcd7noWXFZAfHkxZsRGC9Xs", "jti": "urn:uuid:6c5c0a49-b589-431d-bae7-219122a9ec2c", - "iat": 1541493724, - "exp": 1541493724, "status": "https://issuer.example.org/status", "cnf": { "jwk": { @@ -450,89 +511,181 @@ The corresponding SD-JWT for the previous data is represented as follow, as deco } }, "type": "HealthInsuranceData", + "vct": "DisabilityCard", "verified_claims": { "verification": { "_sd": [ - "2jIR18gfeASHYGB27s7sS3S_iQ4xxFIxCRyiohrBfns" + "sTskq0yFy31ZH3YP2nN_nFnd7H9q18dU3oEa1DC5LRc" ], "trust_framework": "eidas", "assurance_level": "high" }, "claims": { "_sd": [ - "1iztq7bov64xTYbDkWFc44_VjWe029hZqXeUIloqUN4", - "ENNo31jfzFp8Y2DW0R-fIMeWwe7ELGvGoHMwMBpu14E", - "FV2CDNWuTqTgOHaftvVaumBF0OlmnyxMswyf4uIxrhY", - "dZWjq7mJSSX-XTI_HWuE8B2x6IdM5lE-doD_yBpKJao", - "gHYi19frbD_i4BoaWENOjc3lCnMj4pbGNQcsBj_QM4Q" + "3humFjiCYHdHzjL-OEd1vKnQa10ivaYEd1dCCkfRuaA", + "EYgzJ1hTYWJjhBK2V3b8HV3e_fEf-Udffc5ymY77WtQ", + "F90SKK9nIQcHIElkHY_ult_9FGqYe-RydvY3E0qR96s", + "IcYHQydT_C3U1IqaJlFicxLlaHTHvElyFZ6Jxia27qQ", + "dfrmUvonZDgealZCGwk3ufmc_4ept3y9N7xhWZlCyxo", + "ji86HS1v3D41tU5JqW4oWCwTJDuTUwp1ewqoCUzzEXk", + "lXgxEDAuPeUvmkcNGr9FZuqodwFqUT01gJj7xd4yEPA" ] } }, - "_sd_alg": "sha-256" + "_sd_alg": "sha-256", + "cnf": { + "jwk": { + "kty": "EC", + "crv": "P-256", + "x": "TCAER19Zvu3OHF4j4W4vfSVoHIP1ILilDls7vCeGemc", + "y": "ZxjiWWbZMQGHVWKVQ4hbSIirsVfuecCE6t4jT9F2HZQ" + } + } } In the following the disclosure list is given: -Claim **evidence**: +**Claim** ``iat``: + +- SHA-256 Hash: ``7WG4nT6K26_R3975zcwnVwgoHA7b988_3-vJzbZf6Yc`` +- Disclosure: + ``WyI1N212eWNUaDV5WkNyS0xaNXhuZlV3IiwgImlhdCIsIDE2ODMwMDAwMDBd`` +- Contents: ``["57mvycTh5yZCrKLZ5xnfUw", "iat", 1683000000]`` + +**Claim** ``source``: + +- SHA-256 Hash: ``qfuzrQuGcbBBKaE4Q9eqVCSznzJ2rNndLG8q606RLsM`` +- Disclosure: + ``WyJrdWNyQm1sb19oTWFJRkY1ODVSemFRIiwgInNvdXJjZSIsIHsib3JnYW5p`` + ``emF0aW9uX25hbWUiOiAiSXN0aXR1dG8gTmF6aW9uYWxlIGRlbGxhIFByZXZp`` + ``ZGVuemEgU29jaWFsZSIsICJvcmdhbml6YXRpb25faWQiOiAidXJuOmV1ZGk6`` + ``aXQ6b3JnYW5pemF0aW9uX2lkOmlwYV9jb2RlOmlucHMiLCAiY291bnRyeV9j`` + ``b2RlIjogIklUIn1d`` +- Contents: + ``["kucrBmlo_hMaIFF585RzaQ", "source", {"organization_name":`` + ``"Istituto Nazionale della Previdenza Sociale",`` + ``"organization_id":`` + ``"urn:eudi:it:organization_id:ipa_code:inps", "country_code":`` + ``"IT"}]`` + +**Claim** ``evidence``: -- SHA-256 Hash: ``2jIR18gfeASHYGB27s7sS3S_iQ4xxFIxCRyiohrBfns`` +- SHA-256 Hash: ``sTskq0yFy31ZH3YP2nN_nFnd7H9q18dU3oEa1DC5LRc`` - Disclosure: - ``WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwgImV2aWRlbmNlIiwgW3sidHlw`` - ``ZSI6ICJlbGVjdHJvbmljX3JlY29yZCIsICJyZWNvcmQiOiB7InR5cGUiOiAi`` - ``ZWlkYXMuaXQucGRuZCIsICJzb3VyY2UiOiB7Im9yZ2FuaXphdGlvbl9uYW1l`` - ``IjogIlJhZ2lvbmVyaWEgR2VuZXJhbGUgZGVsbG8gU3RhdG8iLCAib3JnYW5p`` - ``emF0aW9uX2lkIjogIlFMSENGQyIsICJjb3VudHJ5X2NvZGUiOiAiSVQifX19`` + ``WyJOVE5Sb09pdVZWUnRGNkNFenRkOVp3IiwgImV2aWRlbmNlIiwgW3sidHlw`` + ``ZSI6ICJlbGVjdHJvbmljX3JlY29yZCIsICJyZWNvcmQiOiB7Il9zZCI6IFsi`` + ``cWZ1enJRdUdjYkJCS2FFNFE5ZXFWQ1N6bnpKMnJObmRMRzhxNjA2UkxzTSJd`` + ``LCAidHlwZSI6ICJodHRwczovL2V1ZGkud2FsbGV0LnBkbmQuZ292Lml0In19`` ``XV0`` -- Contents: ``["2GLC42sKQveCfGfryNRN9w", "evidence", [{"type":`` - ``"electronic_record", "record": {"type": "https://eudi.wallet.pdnd.gov.it",`` - ``"source": {"organization_name": "Ragioneria Generale dello Stato",`` - ``"organization_id": "QLHCFC", "country_code":"IT"}}}]]`` +- Contents: ``["NTNRoOiuVVRtF6CEztd9Zw", "evidence", [{"type":`` + ``"electronic_record", "record": {"_sd":`` + ``["qfuzrQuGcbBBKaE4Q9eqVCSznzJ2rNndLG8q606RLsM"], "type":`` + ``"https://eudi.wallet.pdnd.gov.it"}}]]`` -Claim **given_name**: +**Claim** ``document_number``: -- SHA-256 Hash: ``gHYi19frbD_i4BoaWENOjc3lCnMj4pbGNQcsBj_QM4Q`` +- SHA-256 Hash: ``3humFjiCYHdHzjL-OEd1vKnQa10ivaYEd1dCCkfRuaA`` - Disclosure: - ``WyJlbHVWNU9nM2dTTklJOEVZbnN4QV9BIiwgImdpdmVuX25hbWUiLCAiTWFyaW8iXQ`` -- Contents: ``["eluV5Og3gSNII8EYnsxA_A", "given_name", "Mario"]`` + ``WyJGRFNTUGdnekdCVXdRTEhEU0U2d1FRIiwgImRvY3VtZW50X251bWJlciIs`` + ``ICJYWFhYWFhYWFhYIl0`` +- Contents: + ``["FDSSPggzGBUwQLHDSE6wQQ", "document_number", "XXXXXXXXXX"]`` -Claim **family_name**: +**Claim** ``given_name``: -- SHA-256 Hash: ``dZWjq7mJSSX-XTI_HWuE8B2x6IdM5lE-doD_yBpKJao`` +- SHA-256 Hash: ``lXgxEDAuPeUvmkcNGr9FZuqodwFqUT01gJj7xd4yEPA`` - Disclosure: - ``WyI2SWo3dE0tYTVpVlBHYm9TNXRtdlZBIiwgImZhbWlseV9uYW1lIiwgIlJvc3NpIl0`` -- Contents: ``["6Ij7tM-a5iVPGboS5tmvVA", "family_name", "Rossi"]`` + ``WyJLWjhlNXdWRXREdmIxemlTUEE0RHpBIiwgImdpdmVuX25hbWUiLCAiTWFy`` + ``aW8iXQ`` +- Contents: ``["KZ8e5wVEtDvb1ziSPA4DzA", "given_name", "Mario"]`` -Claim **birthdate**: +**Claim** ``family_name``: -- SHA-256 Hash: ``FV2CDNWuTqTgOHaftvVaumBF0OlmnyxMswyf4uIxrhY`` +- SHA-256 Hash: ``IcYHQydT_C3U1IqaJlFicxLlaHTHvElyFZ6Jxia27qQ`` - Disclosure: - ``WyJlSThaV205UW5LUHBOUGVOZW5IZGhRIiwgImJpcnRoZGF0ZSIsICIxOTgwLTAxLTEwIl0`` -- Contents: ``["eI8ZWm9QnKPpNPeNenHdhQ", "birthdate", "1980-01-10"]`` + ``WyJwWjVNUnlPeHBWV1p1SExvSi15alJnIiwgImZhbWlseV9uYW1lIiwgIlJv`` + ``c3NpIl0`` +- Contents: ``["pZ5MRyOxpVWZuHLoJ-yjRg", "family_name", "Rossi"]`` -Claim **place_of_birth**: +**Claim** ``birth_date``: -- SHA-256 Hash: ``1iztq7bov64xTYbDkWFc44_VjWe029hZqXeUIloqUN4`` +- SHA-256 Hash: ``EYgzJ1hTYWJjhBK2V3b8HV3e_fEf-Udffc5ymY77WtQ`` - Disclosure: - ``WyJRZ19PNjR6cUF4ZTQxMmExMDhpcm9BIiwgInBsYWNlX29mX2JpcnRoIiwg`` - ``eyJjb3VudHJ5IjogIklUIiwgImxvY2FsaXR5IjogIlJvbWUifV0`` -- Contents: - ``["Qg_O64zqAxe412a108iroA", "place_of_birth", {"country":`` - ``"IT", "locality": "Rome"}]`` + ``WyJqdFZ1S0NwbjdiVGNIckFnX3NlVWJRIiwgImJpcnRoX2RhdGUiLCAiMTk4`` + ``MC0wMS0xMCJd`` +- Contents: ``["jtVuKCpn7bTcHrAg_seUbQ", "birth_date", "1980-01-10"]`` -Claim **tax_id_code**: +**Claim** ``expiry_date``: -- SHA-256 Hash: ``ENNo31jfzFp8Y2DW0R-fIMeWwe7ELGvGoHMwMBpu14E`` +- SHA-256 Hash: ``dfrmUvonZDgealZCGwk3ufmc_4ept3y9N7xhWZlCyxo`` - Disclosure: - ``WyJBSngtMDk1VlBycFR0TjRRTU9xUk9BIiwgInRheF9pZF9jb2RlIiwgIlRJ`` + ``WyJXRGtkNkpzTmhERnZMUDRzMWhRZHlBIiwgImV4cGlyeV9kYXRlIiwgIjIw`` + ``MjQtMDEtMDEiXQ`` +- Contents: ``["WDkd6JsNhDFvLP4s1hQdyA", "expiry_date", "2024-01-01"]`` + +**Claim** ``tax_id_code``: + +- SHA-256 Hash: ``F90SKK9nIQcHIElkHY_ult_9FGqYe-RydvY3E0qR96s`` +- Disclosure: + ``WyI0a3NBejZiTVVLeTZadk4xaDhIRHVRIiwgInRheF9pZF9jb2RlIiwgIlRJ`` ``TklULVhYWFhYWFhYWFhYWFhYWFgiXQ`` -- Contents: ``["AJx-095VPrpTtN4QMOqROA", "tax_id_code",`` +- Contents: ``["4ksAz6bMUKy6ZvN1h8HDuQ", "tax_id_code",`` ``"TINIT-XXXXXXXXXXXXXXXX"]`` +**Claim** ``constant_attendance_allowance``: + +- SHA-256 Hash: ``ji86HS1v3D41tU5JqW4oWCwTJDuTUwp1ewqoCUzzEXk`` +- Disclosure: + ``WyJEZFdxS2g3d2RJNVZBeEtTdnhzWFZRIiwgImNvbnN0YW50X2F0dGVuZGFu`` + ``Y2VfYWxsb3dhbmNlIiwgdHJ1ZV0`` +- Contents: + ``["DdWqKh7wdI5VAxKSvxsXVQ", "constant_attendance_allowance",`` + ``true]`` + + + The combined format for the PID issuance is represented below: .. code-block:: - eyJhbGciOiJSUzI1NiIsImtpZCI6Iks2S2hpUDNrOC1XOWVHdk1SVTg0NVVwWVRTdEJsR0g4ejFKZl85czMtUWsifQ.eyJpc3MiOiJodHRwczovL2lzc3Vlci5leGFtcGxlLm9yZyIsInN1YiI6Ik56YkxzWGg4dURDY2Q3bm9XWEZaQWZIa3hac1JHQzlYcy4uLiIsImp0aSI6InVybjp1dWlkOjZjNWMwYTQ5LWI1ODktNDMxZC1iYWU3LTIxOTEyMmE5ZWMyYyIsImlhdCI6MTU0MTQ5MzcyNCwiZXhwIjoxNTQxNDkzNzI0LCJzdGF0dXMiOiJodHRwczovL2lzc3Vlci5leGFtcGxlLm9yZy9zdGF0dXMiLCJjbmYiOnsiandrIjp7Imt0eSI6IlJTQSIsImUiOiJBUUFCIiwidXNlIjoic2lnIiwia2lkIjoiZDEyNmE2YTg1NmY3NzI0NTYwNDg0ZmE5ZGM1OWQxOTUiLCJhbGciOiJSUzI1NiIsIm4iOiJvaWFuczV3WUNXazR3RnRFU3RWWWNuX3hPdzllZEtNTkdIMzNfcTZfcEJJMFhhVFk3UDNhcFVnak8waXZrNWMxTlFBVlk2UFptY1BROFAxWTBjQkFDOVNUUm16dlR2RFFjT29jTGhWeTJabGNYVHUzOW9PR0xOcmE4X0xRc2FNQTM4NmxPX3FNVzQtdVk2RGJHWlk0dkhrU2N2QUM5RklaWURQYWZxV0JFUVVOVjJRT0ZNSDVWUG9paENUS0h3TUdYblpCYXRZT2JnNTd4U09VWC1idmhPX3NGTW0zazRSdnNYY3IzTUZvakFoTGZ3dXR1X2pLOWs3TjlLUl9tTmM1SXBpT3loWndfc1VtRjZTYW1ScXNTUHA0MktEMTBoUE1XMFlKVERNWXhCZEhyTUZlU01IWUlNWTRvQkJUNDNfX2E1NXpJTElfQ25JazQyNDF3T3ZHdncifX0sInR5cGUiOiJIZWFsdGhJbnN1cmFuY2VEYXRhIiwidmVyaWZpZWRfY2xhaW1zIjp7InZlcmlmaWNhdGlvbiI6eyJfc2QiOlsiMmpJUjE4Z2ZlQVNIWUdCMjdzN3NTM1NfaVE0eHhGSXhDUnlpb2hyQmZucyJdLCJ0cnVzdF9mcmFtZXdvcmsiOiJlaWRhcyIsImFzc3VyYW5jZV9sZXZlbCI6ImhpZ2gifSwiY2xhaW1zIjp7Il9zZCI6WyIxaXp0cTdib3Y2NHhUWWJEa1dGYzQ0X1ZqV2UwMjloWnFYZVVJbG9xVU40IiwiRU5ObzMxamZ6RnA4WTJEVzBSLWZJTWVXd2U3RUxHdkdvSE13TUJwdTE0RSIsIkZWMkNETld1VHFUZ09IYWZ0dlZhdW1CRjBPbG1ueXhNc3d5ZjR1SXhyaFkiLCJkWldqcTdtSlNTWC1YVElfSFd1RThCMng2SWRNNWxFLWRvRF95QnBLSmFvIiwiZ0hZaTE5ZnJiRF9pNEJvYVdFTk9qYzNsQ25NajRwYkdOUWNzQmpfUU00USJdfX0sIl9zZF9hbGciOiJzaGEtMjU2In0.vl5ELdx9d7smuDHHDfBGaUySolBe7O3RROqpHDkM3txvXJxgZcCwZQhbWN3sSrBkJgSZ_kFEs2ddYIVKE4bglASlBbSizC8CASdJlyDD3T_dyimA1r2bwSfsHTyrcG_SpoU5Ee9KS-Lr2PCQ3LmTc8_nhaeBGtZCO4B8oZI9bpD6zqms1Zr-ymaE0pYnnQ3aWOclhiLavVudKxLxZvYXTdMStjyNbwBXekVVOnAZuCTuXMsD_jah7_MkmJP_buJgq3u6TthctsORHp4pKuZeI_43Y728-Qg7mIDeL5_-j_vgXdu7FWVa0OSTjZJM27GCDzr2M8LAhApk4aeDoF1Cmw + eyJhbGciOiAiRVMyNTYiLCAidHlwIjogImV4YW1wbGUrc2Qtand0In0.eyJfc2QiOiBb + IjdXRzRuVDZLMjZfUjM5NzV6Y3duVndnb0hBN2I5ODhfMy12SnpiWmY2WWMiXSwgImlz + cyI6ICJodHRwczovL2lzc3Vlci5leGFtcGxlLm9yZyIsICJleHAiOiAxODgzMDAwMDAw + LCAic3ViIjogIk56YkxzWGg4dURDY2Q3bm9XWEZaQWZIa3hac1JHQzlYcyIsICJqdGki + OiAidXJuOnV1aWQ6NmM1YzBhNDktYjU4OS00MzFkLWJhZTctMjE5MTIyYTllYzJjIiwg + InN0YXR1cyI6ICJodHRwczovL2lzc3Vlci5leGFtcGxlLm9yZy9zdGF0dXMiLCAidmN0 + IjogIkRpc2FiaWxpdHlDYXJkIiwgInZlcmlmaWVkX2NsYWltcyI6IHsidmVyaWZpY2F0 + aW9uIjogeyJfc2QiOiBbInNUc2txMHlGeTMxWkgzWVAybk5fbkZuZDdIOXExOGRVM29F + YTFEQzVMUmMiXSwgInRydXN0X2ZyYW1ld29yayI6ICJlaWRhcyIsICJhc3N1cmFuY2Vf + bGV2ZWwiOiAiaGlnaCJ9LCAiY2xhaW1zIjogeyJfc2QiOiBbIjNodW1GamlDWUhkSHpq + TC1PRWQxdktuUWExMGl2YVlFZDFkQ0NrZlJ1YUEiLCAiRVlnekoxaFRZV0pqaEJLMlYz + YjhIVjNlX2ZFZi1VZGZmYzV5bVk3N1d0USIsICJGOTBTS0s5bklRY0hJRWxrSFlfdWx0 + XzlGR3FZZS1SeWR2WTNFMHFSOTZzIiwgIkljWUhReWRUX0MzVTFJcWFKbEZpY3hMbGFI + VEh2RWx5Rlo2SnhpYTI3cVEiLCAiZGZybVV2b25aRGdlYWxaQ0d3azN1Zm1jXzRlcHQz + eTlON3hoV1psQ3l4byIsICJqaTg2SFMxdjNENDF0VTVKcVc0b1dDd1RKRHVUVXdwMWV3 + cW9DVXp6RVhrIiwgImxYZ3hFREF1UGVVdm1rY05HcjlGWnVxb2R3RnFVVDAxZ0pqN3hk + NHlFUEEiXX19LCAiX3NkX2FsZyI6ICJzaGEtMjU2IiwgImNuZiI6IHsiandrIjogeyJr + dHkiOiAiRUMiLCAiY3J2IjogIlAtMjU2IiwgIngiOiAiVENBRVIxOVp2dTNPSEY0ajRX + NHZmU1ZvSElQMUlMaWxEbHM3dkNlR2VtYyIsICJ5IjogIlp4amlXV2JaTVFHSFZXS1ZR + NGhiU0lpcnNWZnVlY0NFNnQ0alQ5RjJIWlEifX19.hbgWxBoQtLVpTfygYVDhrgnoCkw + aw_hqY9GpxG4oXixejLEMvTOAwYFtqiNnYSuNaaGD6aemJW7jLSHDm9NOGA~WyI1N212 + eWNUaDV5WkNyS0xaNXhuZlV3IiwgImlhdCIsIDE2ODMwMDAwMDBd~WyJrdWNyQm1sb19 + oTWFJRkY1ODVSemFRIiwgInNvdXJjZSIsIHsib3JnYW5pemF0aW9uX25hbWUiOiAiSXN + 0aXR1dG8gTmF6aW9uYWxlIGRlbGxhIFByZXZpZGVuemEgU29jaWFsZSIsICJvcmdhbml + 6YXRpb25faWQiOiAidXJuOmV1ZGk6aXQ6b3JnYW5pemF0aW9uX2lkOmlwYV9jb2RlOml + ucHMiLCAiY291bnRyeV9jb2RlIjogIklUIn1d~WyJOVE5Sb09pdVZWUnRGNkNFenRkOV + p3IiwgImV2aWRlbmNlIiwgW3sidHlwZSI6ICJlbGVjdHJvbmljX3JlY29yZCIsICJyZW + NvcmQiOiB7Il9zZCI6IFsicWZ1enJRdUdjYkJCS2FFNFE5ZXFWQ1N6bnpKMnJObmRMRz + hxNjA2UkxzTSJdLCAidHlwZSI6ICJodHRwczovL2V1ZGkud2FsbGV0LnBkbmQuZ292Lm + l0In19XV0~WyJGRFNTUGdnekdCVXdRTEhEU0U2d1FRIiwgImRvY3VtZW50X251bWJlci + IsICJYWFhYWFhYWFhYIl0~WyJLWjhlNXdWRXREdmIxemlTUEE0RHpBIiwgImdpdmVuX2 + 5hbWUiLCAiTWFyaW8iXQ~WyJwWjVNUnlPeHBWV1p1SExvSi15alJnIiwgImZhbWlseV9 + uYW1lIiwgIlJvc3NpIl0~WyJqdFZ1S0NwbjdiVGNIckFnX3NlVWJRIiwgImJpcnRoX2R + hdGUiLCAiMTk4MC0wMS0xMCJd~WyJXRGtkNkpzTmhERnZMUDRzMWhRZHlBIiwgImV4cG + lyeV9kYXRlIiwgIjIwMjQtMDEtMDEiXQ~WyI0a3NBejZiTVVLeTZadk4xaDhIRHVRIiw + gInRheF9pZF9jb2RlIiwgIlRJTklULVhYWFhYWFhYWFhYWFhYWFgiXQ~WyJEZFdxS2g3 + d2RJNVZBeEtTdnhzWFZRIiwgImNvbnN0YW50X2F0dGVuZGFuY2VfYWxsb3dhbmNlIiwg + dHJ1ZV0~ MDOC-CBOR ========= @@ -723,12 +876,6 @@ Depending on the Digital Credential type, additional **elementIdentifier** data * - **eu.europa.ec.eudiw.pid.1** - **birth_date** - *full-date (CBORTag 1004)*. See :ref:`PID Claims fields Section `. - * - **eu.europa.ec.eudiw.pid.1** - - **birth_place** - - *tstr (text string)*. See :ref:`PID Claims fields Section `. - * - **eu.europa.ec.eudiw.pid.1** - - **birth_country** - - *tstr (text string)*. See :ref:`PID Claims fields Section `. * - **eu.europa.ec.eudiw.pid.1** - **unique_id** - *tstr (text string)*. See :ref:`PID Claims fields Section `. @@ -830,7 +977,7 @@ A non-normative example of a PID in MDOC-CBOR format is represented below using .. code-block:: text - A366737461747573006776657273696F6E63312E3069646F63756D656E747381A267646F6354797065781865752E6575726F70612E65632E65756469772E7069642E316C6973737565725369676E6564A26A697373756572417574688443A10126A1182159021930820215308201BCA003020102021404AD06A30C1A6DC6E93BE0E2E8F78DCAFA7907C2300A06082A8648CE3D040302305B310B3009060355040613025A45312E302C060355040A0C25465053204D6F62696C69747920616E64205472616E73706F7274206F66205A65746F706961311C301A06035504030C1349414341205A65746573436F6E666964656E73301E170D3231303932393033333034355A170D3232313130333033333034345A3050311A301806035504030C114453205A65746573436F6E666964656E7331253023060355040A0C1C5A65746F70696120436974792044657074206F662054726166666963310B3009060355040613025A453059301306072A8648CE3D020106082A8648CE3D030107034200047C5545E9A0B15F4FF3CE5015121E8AD3257C28D541C1CD0D604FC9D1E352CCC38ADEF5F7902D44B7A6FC1F99F06EEDF7B0018FD9DA716AEC2F1FFAC173356C7DA3693067301F0603551D23041830168014BBA2A53201700D3C97542EF42889556D15B7AC4630150603551D250101FF040B3009060728818C5D050102301D0603551D0E04160414CE5FD758A8E88563E625CF056BFE9F692F4296FD300E0603551D0F0101FF040403020780300A06082A8648CE3D0403020347003044022012B06A3813FFEC5679F3B8CDDB51EAA4B95B0CBB1786B09405E2000E9C46618C02202C1F778AD252285ED05D9B55469F1CB78D773671F30FE7AB815371942328317C59032AD818590325A667646F6354797065781865752E6575726F70612E65632E65756469772E7069642E316776657273696F6E63312E306C76616C6964697479496E666FA3667369676E6564C074323032332D30322D32325430363A32333A35365A6976616C696446726F6DC074323032332D30322D32325430363A32333A35365A6A76616C6964556E74696CC074323032342D30322D32325430303A30303A30305A6C76616C756544696765737473A2781865752E6575726F70612E65632E65756469772E7069642E31AC015820A7FFC6F8BF1ED76651C14756A061D662F580FF4DE43B49FA82D80A4B80F8434A025820CD372FB85148700FA88095E3492D3F9F5BEB43E555E5FF26D95F5A6ADC36F8E6035820E67E72111B363D80C8124D28193926000980E1211C7986CACBD26AACC5528D48045820F7D062D662826ED95869851DB06BB539B402047BAEE53A00E0AA35BFBE98265D0658202A132DBFE4784627B86AA3807CD19CFEFF487AAB3DD7A60D0AB119A72E736936075820BDCA9E8DBCA354E824E67BFE1533FA4A238B9EA832F23FB4271EBEB3A5A8F7200858202C0EAEC2F05B6C7FE7982683E3773B5D8D7A01E33D04DFCB162ADD8BD99BEE9A095820BFE220D85657CCEC3C67E7DB1DF747E9148A152334BB6D4B65B273279BCC36EC0A582018E38144F5044301D6A0B4EC9D5F98D4CD950E6EA2C29B849CBD457DA29B6AD30B58203C71D2F0EFA09D9E3FBBDFFD29204F6B292C9F79570AEF72DD86C91F7A3AA5C50C582065743D58D89D45E52044758F546034FD13A4F994BC270CDFA7844F74EB3F4B6E0D5820B4A8EB5D523BFFA17B41BDA12DDC7DA32AE1E5F7FF3DCC394A35401F16919BBF781B65752E6575726F70612E65632E65756469772E7069642E69742E31A10E58209D6C11644651126C94ACDAF0803E86D4C71D15D3B2712A14295416734EFD514D6D6465766963654B6579496E666FA1696465766963654B6579A401022001215820BA01AEA44EEE1E338EB2F04E279DBD51B34655783EE185150838C9A7A7C4DB7122582025BA0044439A3871A7B975A0994A85E79B705A9AC263B3FE899B0A93412EE8C96F646967657374416C676F726974686D675348412D32353658400813C28FD62F2602CBC14724E5865733C44A0FCA589B55C085EC9D5C725D6CCE25BA0044439A3871A7B975A0994A85E79B705A9AC263B3FE899B0A93412EE8C96A6E616D65537061636573A2781865752E6575726F70612E65632E65756469772E7069642E318DD818586DA4686469676573744944016672616E646F6D5820156DF9227AD341EAA61AABD301106FD21BDC18820E01DFC16BCF5FECC447111B71656C656D656E744964656E7469666965726B6578706972795F646174656C656C656D656E7456616C7565D903EC6A323032342D30322D3232D818586FA4686469676573744944026672616E646F6D5820A3A1F13F05544D03A5B50B5FDB78465808393BCF3B7953A345FE28F820C7BE0D71656C656D656E744964656E7469666965726D69737375616E63655F646174656C656C656D656E7456616C7565D903EC6A323032332D30322D3232D8185866A4686469676573744944036672616E646F6D5820852591F90F2C9DED57A03632E2C1322AB52A082A431E71A4149A6830C8F1AD0C71656C656D656E744964656E7469666965726F69737375696E675F636F756E7472796C656C656D656E7456616C7565624954D818587CA4686469676573744944046672616E646F6D5820D1D587B3512ACCE15C4F6B20944CEB002A464E4A158389788563408873C3FCE571656C656D656E744964656E7469666965727169737375696E675F617574686F726974796C656C656D656E7456616C7565764D696E69737465726F2064656C6C27496E7465726E6FD8185864A4686469676573744944056672616E646F6D582094FDD7609C0E73DC8589B5CAB11E1D9058CF8BFF8A336DA5F81FCBA055396A0F71656C656D656E744964656E7469666965726A676976656E5F6E616D656C656C656D656E7456616C7565654D6172696FD8185865A4686469676573744944066672616E646F6D5820660C0A7BF79E0E0261CA1547A4294FB808AA70738F424B13AB1B9440B566AE1371656C656D656E744964656E7469666965726B66616D696C795F6E616D656C656C656D656E7456616C756565526F737369D818586BA4686469676573744944076672616E646F6D5820315C53491286488FA07F5C2CE67135EF5C9959C3469C99A14E9B6DC924F9EBA571656C656D656E744964656E746966696572696269727468646174656C656C656D656E7456616C7565D903EC6A313935362D30312D3132D818587AA4686469676573744944086672616E646F6D582081C5CC04FBDF78E0F84DF72FDB87028ADE08E66DC5F31084826EBAD7AE70D84671656C656D656E744964656E7469666965726B62697274685F706C6163656C656C656D656E7456616C756581A267636F756E747279624954686C6F63616C69747964526F6D65D818587DA4686469676573744944096672616E646F6D5820764EF39C9D01F3AA6A87F441603CFE853FBA3CEE3BC2C168BCC9E96271D6E06371656C656D656E744964656E74696669657269756E697175655F69646C656C656D656E7456616C7565781E78787878787878782D7878782D787878782D787878787878787878787878D81858E8A46864696765737449440A6672616E646F6D5820AD20B3B9C67AED8089FF33ECDC108781C3B49B81CD7A3F059D2FE236977037B271656C656D656E744964656E74696669657275766572696669636174696F6E2E65766964656E63656C656C656D656E7456616C756581A2647479706571656C656374726F6E69635F7265636F7264667265636F7264A264747970656C65696461732E69742E63696566736F75726365A3716F7267616E697A6174696F6E5F6E616D656C65696461732E69742E6369656F6F7267616E697A6174696F6E5F6964646D5F69746C636F756E7472795F636F6465626974D8185879A46864696765737449440B6672616E646F6D5820C12314B3695D1401505187E2113115E2F7B4A14B135DEE320F5E6DF81275F17671656C656D656E744964656E746966696572667374617475736C656C656D656E7456616C7565781D68747470733A2F2F70696470726F76696465722E69742F737461747573D8185877A46864696765737449440C6672616E646F6D5820A7B6A9027ED97F25DF96DD0EAB8093B264A3BD6A1D5B24228F3FC5B18EF835FB71656C656D656E744964656E746966696572781C766572696669636174696F6E2E74727573745F6672616D65776F726B6C656C656D656E7456616C7565656569646173D8185876A46864696765737449440D6672616E646F6D5820C76CE2AE4E9BE1DB07A5CB397B54ACE3ECCC786D3F85E4348B923DEE059783DB71656C656D656E744964656E746966696572781C766572696669636174696F6E2E6173737572616E63655F6C6576656C6C656C656D656E7456616C75656468696768781B65752E6575726F70612E65632E65756469772E7069642E69742E3181D8185877A46864696765737449440E6672616E646F6D5820717DF3F583B1484366C33A1F869F2B5D201D466A8B589C79AB1A2D85E595432571656C656D656E744964656E7469666965726D7461785F69645F6E756D6265726C656C656D656E7456616C75657554494E49542D585858585858585858585858585858 + a366737461747573006776657273696f6e63312e3069646f63756d656e747381a267646f6354797065781865752e6575726f70612e65632e65756469772e7069642e316c6973737565725369676e6564a26a697373756572417574688443a10126a1182159021930820215308201bca003020102021404ad06a30c1a6dc6e93be0e2e8f78dcafa7907c2300a06082a8648ce3d040302305b310b3009060355040613025a45312e302c060355040a0c25465053204d6f62696c69747920616e64205472616e73706f7274206f66205a65746f706961311c301a06035504030c1349414341205a65746573436f6e666964656e73301e170d3231303932393033333034355a170d3232313130333033333034345a3050311a301806035504030c114453205a65746573436f6e666964656e7331253023060355040a0c1c5a65746f70696120436974792044657074206f662054726166666963310b3009060355040613025a453059301306072a8648ce3d020106082a8648ce3d030107034200047c5545e9a0b15f4ff3ce5015121e8ad3257c28d541c1cd0d604fc9d1e352ccc38adef5f7902d44b7a6fc1f99f06eedf7b0018fd9da716aec2f1ffac173356c7da3693067301f0603551d23041830168014bba2a53201700d3c97542ef42889556d15b7ac4630150603551d250101ff040b3009060728818c5d050102301d0603551d0e04160414ce5fd758a8e88563e625cf056bfe9f692f4296fd300e0603551d0f0101ff040403020780300a06082a8648ce3d0403020347003044022012b06a3813ffec5679f3b8cddb51eaa4b95b0cbb1786b09405e2000e9c46618c02202c1f778ad252285ed05d9b55469f1cb78d773671f30fe7ab815371942328317c59032ad818590325a667646f6354797065781865752e6575726f70612e65632e65756469772e7069642e316776657273696f6e63312e306c76616c6964697479496e666fa3667369676e6564c074323032332d30322d32325430363a32333a35365a6976616c696446726f6dc074323032332d30322d32325430363a32333a35365a6a76616c6964556e74696cc074323032342d30322d32325430303a30303a30305a6c76616c756544696765737473a2781865752e6575726f70612e65632e65756469772e7069642e31ac015820a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a025820cd372fb85148700fa88095e3492d3f9f5beb43e555e5ff26d95f5a6adc36f8e6035820e67e72111b363d80c8124d28193926000980e1211c7986cacbd26aacc5528d48045820f7d062d662826ed95869851db06bb539b402047baee53a00e0aa35bfbe98265d0658202a132dbfe4784627b86aa3807cd19cfeff487aab3dd7a60d0ab119a72e736936075820bdca9e8dbca354e824e67bfe1533fa4a238b9ea832f23fb4271ebeb3a5a8f7200858202c0eaec2f05b6c7fe7982683e3773b5d8d7a01e33d04dfcb162add8bd99bee9a095820bfe220d85657ccec3c67e7db1df747e9148a152334bb6d4b65b273279bcc36ec0a582018e38144f5044301d6a0b4ec9d5f98d4cd950e6ea2c29b849cbd457da29b6ad30b58203c71d2f0efa09d9e3fbbdffd29204f6b292c9f79570aef72dd86c91f7a3aa5c50c582065743d58d89d45e52044758f546034fd13a4f994bc270cdfa7844f74eb3f4b6e0d5820b4a8eb5d523bffa17b41bda12ddc7da32ae1e5f7ff3dcc394a35401f16919bbf781b65752e6575726f70612e65632e65756469772e7069642e69742e31a10e58209d6c11644651126c94acdaf0803e86d4c71d15d3b2712a14295416734efd514d6d6465766963654b6579496e666fa1696465766963654b6579a401022001215820ba01aea44eee1e338eb2f04e279dbd51b34655783ee185150838c9a7a7c4db7122582025ba0044439a3871a7b975a0994a85e79b705a9ac263b3fe899b0a93412ee8c96f646967657374416c676f726974686d675348412d32353658400813c28fd62f2602cbc14724e5865733c44a0fca589b55c085ec9d5c725d6cce25ba0044439a3871a7b975a0994a85e79b705a9ac263b3fe899b0a93412ee8c96a6e616d65537061636573a2781865752e6575726f70612e65632e65756469772e7069642e318cd818586da4686469676573744944016672616e646f6d5820156df9227ad341eaa61aabd301106fd21bdc18820e01dfc16bcf5fecc447111b71656c656d656e744964656e7469666965726b6578706972795f646174656c656c656d656e7456616c7565d903ec6a323032342d30322d3232d818586fa4686469676573744944026672616e646f6d5820a3a1f13f05544d03a5b50b5fdb78465808393bcf3b7953a345fe28f820c7be0d71656c656d656e744964656e7469666965726d69737375616e63655f646174656c656c656d656e7456616c7565d903ec6a323032332d30322d3232d8185866a4686469676573744944036672616e646f6d5820852591f90f2c9ded57a03632e2c1322ab52a082a431e71a4149a6830c8f1ad0c71656c656d656e744964656e7469666965726f69737375696e675f636f756e7472796c656c656d656e7456616c7565624954d818587ca4686469676573744944046672616e646f6d5820d1d587b3512acce15c4f6b20944ceb002a464e4a158389788563408873c3fce571656c656d656e744964656e7469666965727169737375696e675f617574686f726974796c656c656d656e7456616c7565764d696e69737465726f2064656c6c27496e7465726e6fd8185864a4686469676573744944056672616e646f6d582094fdd7609c0e73dc8589b5cab11e1d9058cf8bff8a336da5f81fcba055396a0f71656c656d656e744964656e7469666965726a676976656e5f6e616d656c656c656d656e7456616c7565654d6172696fd8185865a4686469676573744944066672616e646f6d5820660c0a7bf79e0e0261ca1547a4294fb808aa70738f424b13ab1b9440b566ae1371656c656d656e744964656e7469666965726b66616d696c795f6e616d656c656c656d656e7456616c756565526f737369d818586ba4686469676573744944076672616e646f6d5820315c53491286488fa07f5c2ce67135ef5c9959c3469c99a14e9b6dc924f9eba571656c656d656e744964656e746966696572696269727468646174656c656c656d656e7456616c7565d903ec6a313935362d30312d3132d818587da4686469676573744944086672616e646f6d5820764ef39c9d01f3aa6a87f441603cfe853fba3cee3bc2c168bcc9e96271d6e06371656c656d656e744964656e74696669657269756e697175655f69646c656c656d656e7456616c7565781e78787878787878782d7878782d787878782d787878787878787878787878d81858e8a4686469676573744944096672616e646f6d5820ad20b3b9c67aed8089ff33ecdc108781c3b49b81cd7a3f059d2fe236977037b271656c656d656e744964656e74696669657275766572696669636174696f6e2e65766964656e63656c656c656d656e7456616c756581a2647479706571656c656374726f6e69635f7265636f7264667265636f7264a264747970656c65696461732e69742e63696566736f75726365a3716f7267616e697a6174696f6e5f6e616d656c65696461732e69742e6369656f6f7267616e697a6174696f6e5f6964646d5f69746c636f756e7472795f636f6465626974d8185879a46864696765737449440a6672616e646f6d5820c12314b3695d1401505187e2113115e2f7b4a14b135dee320f5e6df81275f17671656c656d656e744964656e746966696572667374617475736c656c656d656e7456616c7565781d68747470733a2f2f70696470726f76696465722e69742f737461747573d8185877a46864696765737449440b6672616e646f6d5820a7b6a9027ed97f25df96dd0eab8093b264a3bd6a1d5b24228f3fc5b18ef835fb71656c656d656e744964656e746966696572781c766572696669636174696f6e2e74727573745f6672616d65776f726b6c656c656d656e7456616c7565656569646173d8185876a46864696765737449440c6672616e646f6d5820c76ce2ae4e9be1db07a5cb397b54ace3eccc786d3f85e4348b923dee059783db71656c656d656e744964656e746966696572781c766572696669636174696f6e2e6173737572616e63655f6c6576656c6c656c656d656e7456616c75656468696768781b65752e6575726f70612e65632e65756469772e7069642e69742e3181d8185877a46864696765737449440d6672616e646f6d5820717df3f583b1484366c33a1f869f2b5d201d466a8b589c79ab1a2d85e595432571656c656d656e744964656e7469666965726d7461785f69645f6e756d6265726c656c656d656e7456616c75657554494e49542d585858585858585858585858585858 The `Diagnostic Notation` of the above MDOC-CBOR is given below: @@ -865,16 +1012,15 @@ The `Diagnostic Notation` of the above MDOC-CBOR is given below: 3: h'E2382149255AE8E955AF9B8984395…', 4: h'BBC77E6CCA981A3AD0C3E544EDF86…', 6: h'BB6E6C68D1B4B4EC5A2AE9206F5t4…', - 7: h'F8A5966E6DAC9970E0334D8F75E25…', - 8: h'EAD5E8B5E543BD31F3BE57DE4ED45…', - 9: h'DEFDF1AA746718016EF1B94BFE5R6…' + 7: h'F8A5966E6DAC9970E0334D8F75E25…', + 8: h'DEFDF1AA746718016EF1B94BFE5R6…' }, "eu.europa.ec.eudiw.pid.it.1": { - 10: h'AFC5A127BE44753172844B13491D8…', - 11: h'AFC5A127BE44753172844B13492H4…', - 12: h'DJA5A127BE44753172844B13492H4…', - 13: h'KDL5A127BE44753172844B13492H4…', - 14: h'F9EE4D36F67DBD75E23311AC1C29…' + 9: h'AFC5A127BE44753172844B13491D8…', + 10: h'AFC5A127BE44753172844B13492H4…', + 11: h'DJA5A127BE44753172844B13492H4…', + 12: h'KDL5A127BE44753172844B13492H4…', + 13: h'F9EE4D36F67DBD75E23311AC1C29…' } }, "deviceKeyInfo": { @@ -945,27 +1091,14 @@ The `Diagnostic Notation` of the above MDOC-CBOR is given below: { "digestID": 7, "random": h'6059FF1CE27B4997B4ADE1DE7B01DC60', - "elementIdentifier": "birthdate", + "elementIdentifier": "birth_date", "elementValue": 1004("1956-01-12")% the tag 1004 defines the value is a full date } - >>), - 24(<< - { - "digestID": 8, - "random": h'CAD1F6A38F603451F1FA653F81FF309D', - "elementIdentifier": "birth_place", - "elementValue": [ - { - "country": "IT" , - "locality": "Rome" - } - ] - } - >>), + >>), 24(<< { - "digestID": 9, + "digestID": 8, "random": h'53C15C57B3B076E788795829190220B4', "elementIdentifier": "unique_id", "elementValue": "xxxxxxxx-xxx-xxxx-xxxxxxxxxxxx" @@ -975,7 +1108,7 @@ The `Diagnostic Notation` of the above MDOC-CBOR is given below: "eu.europa.ec.eudiw.pid.it.1": [ 24(<< { - "digestID": 10, + "digestID": 9, "random": h'CAD1F6A38F603451F1FA653F81FF309D', "elementIdentifier": "verification.evidence", "elementValue": [ @@ -995,7 +1128,7 @@ The `Diagnostic Notation` of the above MDOC-CBOR is given below: >>), 24(<< { - "digestID": 11, + "digestID": 10, "random": h'CAD1F6A38F603451F1FA653F81FF309D, "elementIdentifier": "status", "elementValue": "https://pidprovider.example.it/status" @@ -1003,7 +1136,7 @@ The `Diagnostic Notation` of the above MDOC-CBOR is given below: >>), 24(<< { - "digestID": 12, + "digestID": 11, "random": h'564E3C65D46D06FEDEB0E7293A86GF', "elementIdentifier": "verification.trust_framework", "elementValue": "eidas" @@ -1011,7 +1144,7 @@ The `Diagnostic Notation` of the above MDOC-CBOR is given below: >>), 24(<< { - "digestID": 13, + "digestID": 12, "random": h'D884E5D5EF4CFC93FDB1E4EE8F3923', "elementIdentifier": "verification.assurance_level", "elementValue": "high" @@ -1019,7 +1152,7 @@ The `Diagnostic Notation` of the above MDOC-CBOR is given below: >>) 24(<< { - "digestID": 14, + "digestID": 13, "random": h'11aa7273a2d2daa973f5951f0c34c2fbae', "elementIdentifier": "tax_id_number", "elementValue": "TINIT-XXXXXXXXXXXXXXX" diff --git a/docs/en/pid-eaa-issuance.rst b/docs/en/pid-eaa-issuance.rst index 6093ce5c3..5f29acfdb 100644 --- a/docs/en/pid-eaa-issuance.rst +++ b/docs/en/pid-eaa-issuance.rst @@ -5,27 +5,26 @@ PID/(Q)EAA Issuance +++++++++++++++++++ -This section describes the PID and (Q)EAAs issuance flow with an high level of security. +This section describes the PID and (Q)EAAs issuance flow with an high level of security. The relevant entities and interfaces involved in the issuance flow are: - - *Wallet Provider*: The entity responsible for releasing an EUDI Wallet Solution. It also issues Wallet Instance Attestations to its Wallet Instances through an Attestation Service. The Wallet Attestation certifies the genuinity and authenticity of the Wallet Instance and its compliance with a Trust Framework in compliance to the security and privacy requirements. - - *Wallet Solution*: Entire product and service owned by a Wallet Provider, offered to all the Users of that solution. The Wallet Solution is certified as EUDI-compliant by a Conformity Assessment Body (CAB). - - *Wallet Instance*: Instance of a Wallet Solution, installed on the User device. It provides interfaces for User interaction with the Wallet Provider, Relying Parties, PID, and (Q)EAA Providers. + - *Wallet Provider*: The entity responsible for releasing an EUDI Wallet Solution. The Wallet Provider issues the Wallet Attestations to its Wallet Instances through an Attestation Service. The Wallet Attestation certifies the genuinity and authenticity of the Wallet Instance and its compliance with the security and privacy requirements. + - *Wallet Solution*: Entire product and service owned by a Wallet Provider, offered to all the Users and certified as EUDI-compliant by a Conformity Assessment Body (CAB). + - *Wallet Instance*: Instance of a Wallet Solution, installed on the User device. The Wallet Instance provides graphical interfaces for User interaction with Relying Parties, PID, (Q)EAA Providers and the Wallet Provider. - *PID Provider*: The entity that issues the eIDAS Person Identification Data (PID). It is composed of: - - OpenID4VCI Component: based on the “OpenID for Verifiable Credential Issuance” specification `[OIDC4VCI. Draft 13] `_ to release PID credentials. - - National eID Relying Party (OpenID Connect or SAML2): It represents the component to authenticate the User with the national Digital Identity Providers. - - National Identity Provider: It represents preexisting identity systems based on SAML2 or OpenID Connect, already in production in each Member State (for Italy SPID and CIE id authentication schemed notified eIDAS with *LoA* **High**, see `SPID/CIE OpenID Connect Specifications `_). - + - OpenID4VCI Component: based on the "OpenID for Verifiable Credential Issuance" specification ` [OIDC4VCI. Draft 13] `_ to release the PID. + - National eID Relying Party: The component to authenticate the User with the national Digital Identity Providers, based on OpenID Connect Core 1.0 or SAML2. + - National Identity Provider: It represents preexisting identity systems based on SAML2 or OpenID Connect Core 1.0, already in production in each Member State (eg: the Italian SPID and CIE id schemes notified eIDAS with *LoA* **High**, see `SPID/CIE OpenID Connect Specifications `_). + - *(Q)EAA Provider*: It represents the Issuer of (Q)EAAs. It is composed of: - - OpenID4VCI Component: based on the “OpenID for Verifiable Credential Issuance” specification `[OIDC4VCI. Draft 13] `_ to release (Q)EAAs. - - Relying Party: It represents the component to authenticate the User with the PID. The (Q)EAA Provider acts as a Verifier and it sends a presentation request to the Wallet Instance according to [`OpenID4VP`_]. The Wallet Instance MUST have a valid PID obtained prior to starting a transaction with the (Q)EAA Provider. - + - OpenID4VCI Component: based on the "OpenID for Verifiable Credential Issuance" specification to release (Q)EAAs. + - Relying Party: Component to authenticate the User with the PID. The (Q)EAA Provider acts as a Verifier by sending a presentation request to the Wallet Instance, according to [`OpenID4VP`_]. The Wallet Instance MUST have a valid PID, obtained in a previous time, to get authenticated with the (Q)EAA Provider. High-Level PID flow ------------------- - + The :numref:`fig_High-Level-Flow-ITWallet-PID-Issuance` shows a general architecture and highlights the main operations involved in the issuance of a PID. .. _fig_High-Level-Flow-ITWallet-PID-Issuance: @@ -33,18 +32,18 @@ The :numref:`fig_High-Level-Flow-ITWallet-PID-Issuance` shows a general architec :figwidth: 100% :align: center - PID Issuance - General architecture and high level flow + PID Issuance - General architecture and high level flow. -Below a detailed description for each step represented in the previous picture: +Below the description of the steps represented in the previous picture: - 0. **Wallet Instance Setup**: the first time the Wallet Instance is started a preliminary setup phase MUST be carried out. It consists of the release of a verifiable proof issued by the Attestation Service provided by the Wallet Provider that asserts the genuineness, the authenticity and the compliance with a trust framework of the Wallet Instance. The verifiable proof binds a public key corresponding to a local private key generated by the Wallet Instance. - 1. **Obtaining the trusted PID Provider**: the Wallet Instance discovers the trusted PID Provider using the Federation API (e.g.: using the Subordinate Listing Endpoint of the Trust Anchor and its Intermediates), and then inspects the metadata looking for the availability of the PID credential. - 2. **Obtaining of PID Provider Metadata**: the Wallet Instance establishes the trust to the PID Provider according to the Trust Model, obtaining the Metadata that discloses the formats of the PID, the algorithms supported, and any other parameter required for interoperability needs. - 3. **PID Request**: following the Authorization Code Flow in `[OIDC4VCI. Draft 13] `_ the Wallet Instance requests a PID to the PID Provider. A fresh key pair that is generated by the Wallet Instance for the purpose of the sender-constrained Access Token will be used by the PID Provider for the Holder Key Binding of the PID. - 4. **User Authentication**: the PID Provider authenticates the User with LoA High, acting as an IAM Proxy to the National eID system. - 5. **PID Issuance**: once the User authentication with LoA High happens, the User gives their consent, and the PID Provider releases a PID bound to the key material held by the requesting Wallet Instance. + 0. **Wallet Instance Setup**: the first time the Wallet Instance is started a preliminary setup phase is carried out. It consists of the release of the Wallet Attestation issued by Wallet Attestation Service asserting the genuineness and the compliance of the Wallet Instance with the shared trust framework. The Wallet Attestation binds the public key provided by the Wallet Instance, related to one of the private keys generated by the Wallet Instance. + 1. **PID/(Q)EAA Provider Discovery**: the Wallet Instance discovers the trusted Digital Credential Issuers using the Federation API (e.g.: using the Subordinate Listing Endpoint of the Trust Anchor and its Intermediates), inspecting the Credential Issuer metadata and Trust Marks for filtering the PID Provider. + 2. **PID Provider Metadata**: the Wallet Instance establishes the trust to the PID Provider according to the Trust Model and obtains the Metadata that discloses the formats of the PID, the algorithms supported, and any other parameter required for interoperability needs. + 3. **PID Request**: using the Authorization Code Flow defined in `[OIDC4VCI. Draft 13] `_ the Wallet Instance requests the PID to the PID Provider. + 4. **User Authentication**: the PID Provider authenticates the User with LoA High, acting as an Identity and Access Management Proxy to the National eID system. + 5. **PID Issuance**: the User is authenticated with LoA High and the PID Provider releases a PID bound to the key material held by the requesting Wallet Instance. -In the following sections the steps from 1 to 5 are further expanded into more technical details. +In the following sections the steps from 1 to 5 are further expanded into more technical details. High-Level (Q)EAA flow ---------------------- @@ -63,20 +62,25 @@ The :numref:`fig_High-Level-Flow-ITWallet-QEAA-Issuance` shows a general archite Below the description of the most relevant operations involved in the (Q)EAA issuance: - 1. **Obtaining the trusted (Q)EAA Issuer**: the Wallet Instance discovers the trusted (Q)EAA Issuer ufing the Federaiton API (e.g.: using the Subordinate Listing Endpoint of the Trust Anchor and its Intermediates), then inspects the metadata looking for the credential capabilities. - 2. **Obtaining of (Q)EAA Provider Metadata**: the Wallet Instance establishes the trust to the (Q)EAA Provider according to the Trust Model, obtaining the Metadata that discloses the formats of the (Q)EAA, the algorithms supported, and any other parameter required for interoperability needs. - 3. **(Q)EAA Request**: according to the Authorization Code Flow in `[OIDC4VCI. Draft 13] `_ the Wallet Instance requests a (Q)EAA to the (Q)EAA Provider. A fresh key pair that is generated by the Wallet Instance for the sender-constrained Access Token TO be used by (Q)EAA Provider for the key binding of the (Q)EAA. The (Q)EAA Provider checks the Wallet Instance by means of the Wallet Instance Attestation and the Trust Chain related to the Wallet Provider. - 4. **User Authentication**: the (Q)EAA Provider, acting as a Verifier (Relying Party), authenticates the User evaluating the presentation of the PID. - 5. **(Q)EAA Issuance**: Once the User has been authenticated with a valid PID, the User gives their consent, then the (Q)EAA Provider releases a (Q)EAA bound to the key material held by the requesting Wallet Instance. + 1. **Discovery of the trusted (Q)EAA Provider**: the Wallet Instance obtains the list of the trusted (Q)EAA Provider using the Federation API (e.g.: using the Subordinate Listing Endpoint of the Trust Anchor and its Intermediates), then inspects the metadata and Trust Mark looking for the Digital Credential capabilities of each (Q)EAA Provider. + 2. **(Q)EAA Provider Metadata**: the Wallet Instance establishes the trust to the (Q)EAA Provider according to the Trust Model, obtaining the Metadata that discloses the formats of the (Q)EAA, the algorithms supported, and any other parameter required for interoperability needs. + 3. **(Q)EAA Request**: using the Authorization Code Flow , defined in `[OIDC4VCI. Draft 13] `_, the Wallet Instance requests a (Q)EAA to the (Q)EAA Provider. + 4. **User Authentication**: the (Q)EAA Provider, acting as a Verifier (Relying Party), authenticates the User evaluating the presentation of the PID. + 5. **(Q)EAA Issuance**: the User is authenticated with a valid PID and the (Q)EAA Provider releases a (Q)EAA bound to the key material held by the requesting Wallet Instance. Detailed Flow ------------- -The PID/(Q)EAA Issuance phase is based on the **Authorization Code Flow** with **Pushed Authorization Requests** (PAR) [:rfc:`9126`] and **PKCE** (Proof Key for Code Exchange, :rfc:`7636`) as recommended in `[OIDC4VCI. Draft 13. Section 3.4] `_. A *Wallet Initiated Flow* is involved and the User receives the PID/(Q)EAA directly in response to the Credential Request (*Immediate Flow*). +The PID/(Q)EAA Issuance phase uses the **Authorization Code Flow** with the following specifications: + +* **Pushed Authorization Requests** (PAR) [:rfc:`9126`]; +* **PKCE** (Proof Key for Code Exchange, :rfc:`7636`) as recommended in `[OIDC4VCI. Draft 13. Section 3.4] `_. + +In this section a *Wallet Initiated Flow* is outlined, where the User receives the PID/(Q)EAA directly in response to the Credential Request. .. warning:: - + All the non-normative examples are referred to the PID Provider issuance flow. .. _fig_Low-Level-Flow-ITWallet-PID-QEAA-Issuance: @@ -85,36 +89,36 @@ The PID/(Q)EAA Issuance phase is based on the **Authorization Code Flow** with * :figwidth: 100% :align: center :target: https://www.plantuml.com/plantuml/svg/bLJVRzis47xdNt587vO0DlPke4MTn6kC5OEHfSXB086HplOj4gcHnwZUm_xs7KLPfkQqQ8C0KSZxyNtVVSUFdhNZqDHA1xOcDC_eb6hbZ4fgjM6u-EBHNO3s49Hwjb_JmIyUV2DHxTuQl81tdsctv-iwu3JtsjbkJDVJkqTTryYmDWB1bDZ7T0fD1TBbVnWswrlOEFjArL2CbFnqCFy0OG7scJKPEDZWG29LWBbST0iue5VA6Si8zXKTTF3kyMxzi5931kyHQl8CTjj_FxZW6Il8s_a8gQyX3USVf5rfpPPSqsTuhB5aiYQMoDEK2W92CDYNAOGPYLhhJtSFd-vNgp_KpHxBbqaca0SXFuBw3ULGzpsqgOvaYJqqoBhIh7E449c3W7Ie6M7p-yrA05S8qfosXAulyhXUpZTsCyIJn6-Mzt2FVmVq39TF1i2XRwtnMF2XnLayAMj2mmLLwJyfMfJxE4IpmpUE2e6tjodOfSfv6UqzkiXgsY2_UIym_nsWFfaho7LyIyNag1yHSaZmj3EQWyCXv5XXoOoUJvf7iLzrJHNn0JAr5IMdZVeboU1ou5i4HpF0hoqvz0MPgsJQw5gzW6KGVHpza_gCufzaXgpCbGgwpwIVJbGJtMRXk0J1HpT8BScYCXNhYFU0wzlbdt0dAzspBoCdm-Uy1T4Pc562Q8OPH1Nb3ta_4kX-9Ybpz0vD71_2hTW1Nl3mpRlMMRlDVGvRwwOxnlO53GYZrf9GonRXGMv6KPCUMT7ByqNOEMquCx6jicquRjstdVy-EBCWvEr2lAeRlx1n98iKEnzZvp5syLV7y-FDoQDI_BkxCwnWHGxBtXDFqOcKn4kCyo7eiaJlYrwYML8gqSkSF8EoCDQKE7uKcStFtw6adlosrdkf7iT-EMJsuTFuNFApsKb85Ishwt60sVnkJhVdGyofzGR9HtkgMrIu9KEzjh5_etcMegxUUeEkFtzPgNlSaUUuKNKTtv8CvjnXBQGgK6HIDIdSyqhsIBltgyDNcpuXVsI6EUNCic4DwB9kFpmQ4VNqgaKnefs2XpA-ZLcSP-joEkgZW0jD_Hy0 - + PID/(Q)EAA Issuance - Detailed flow -**Steps 1-4 (Discovery):** The User selects the PID/(Q)EAA Provider, and the Wallet Instance obtains the Metadata for the selected PID/(Q)EAA Provider. +**Steps 1-4 (Discovery):** The User selects the PID/(Q)EAA Provider using the Wallet Instance, the Metadata for the selected PID/(Q)EAA Provider are processed by the Wallet Instance. .. note:: - **Federation Check:** The Wallet Instance needs to check if the PID/(Q)EAA Provider is part of the Federation, obtaining then its protocol specific Metadata. A non-normative example of a response from the endpoint **.well-known/openid-federation** with the **Entity Configuration** and the **Metadata** of the PID/(Q)EAA Provider is represented within the section `Entity Configuration Credential Issuer`_. + **Federation Check:** The Wallet Instance needs to check if the PID/(Q)EAA Provider is part of the Federation, obtaining its protocol specific Metadata. A non-normative example of a response from the endpoint **.well-known/openid-federation** with the **Entity Configuration** and the **Metadata** of the PID/(Q)EAA Provider is represented within the section `Entity Configuration Credential Issuer`_. **Steps 5-6 (PAR Request):** The Wallet Instance: - * creates a fresh PKCE code verifier, Wallet Instance Attestation Proof of Possession, and ``state`` parameter for the *Pushed Authorization Request*. - * provides to the PID/(Q)EAA Provider PAR endpoint the parameters previously listed above, using the ``request`` parameter (hereafter Request Object) according to :rfc:`9126` Section 3 to prevent Request URI swapping attack. - * MUST create the ``code_verifier`` with enough entropy random string using the unreserved characters with a minimum length of 43 characters and a maximum length of 128 characters, making it impractical for an attacker to guess its value. The value MUST be generated following the recommendation in Section 4.1 of :rfc:`7636`. - * signs this request using the private key that is created during the setup phase to obtain the Wallet Instance Attestation. The related public key that is attested by the Wallet Provider is provided within the Wallet Instance Attestation ``cnf`` claim. - * MUST create the value of the ``client_assertion`` parameter according to OAuth 2.0 Attestation-based Client Authentication [`oauth-attestation-draft `_], since in this flow the Pushed Authorization Endpoint is a protected endpoint. The ``client_assertion`` value MUST NOT contain more or less than precisely two JWTs separated with the ``~`` character. The first JWT MUST be the Wallet Instance Attestation JWT and the second JWT MUST be the Wallet Instance Attestation Proof of Possession. - * specifies the types of the requested credentials using the ``authorization_details`` [RAR :rfc:`9396`] parameter. + * creates a fresh PKCE code verifier, Wallet Attestation Proof of Possession, and ``state`` parameter for the *Pushed Authorization Request*. + * provides to the PID/(Q)EAA Provider PAR endpoint the parameters previously listed above, using the ``request`` parameter (hereafter Request Object) according to :rfc:`9126` Section 3 to prevent Request URI swapping attack. + * MUST create the ``code_verifier`` with enough entropy random string using the unreserved characters with a minimum length of 43 characters and a maximum length of 128 characters, making it impractical for an attacker to guess its value. The value MUST be generated following the recommendation in Section 4.1 of :rfc:`7636`. + * signs this request using the private key that is created during the setup phase to obtain the Wallet Attestation. The related public key that is attested by the Wallet Provider is provided within the Wallet Attestation ``cnf`` claim. + * MUST create the value of the ``client_assertion`` parameter according to OAuth 2.0 Attestation-based Client Authentication [`oauth-attestation-draft `_], since in this flow the Pushed Authorization Endpoint is a protected endpoint. The ``client_assertion`` value MUST NOT contain more or less than precisely two JWTs separated with the ``~`` character. The first JWT MUST be the Wallet Attestation JWT and the second JWT MUST be the Wallet Attestation Proof of Possession. + * specifies the types of the requested credentials using the ``authorization_details`` [RAR :rfc:`9396`] parameter. The PID/(Q)EAA Provider performs the following checks upon the receipt of the PAR request: - - 1. It MUST validate the signature of the Request Object using the algorithm specified in the ``alg`` header parameter (:rfc:`9126`, :rfc:`9101`) and the public key that can be retrieved from the Wallet Instance Attestation (``cnf``) identified using the ``kid`` header of the Request Object. - 2. It MUST check that the used algorithm for signing the request in the ``alg`` header is among the appropriate once reported in Section `Cryptographic Algorithms `_. - 3. It MUST check that the ``client_id`` in the request body of the PAR request matches the ``client_id`` claim in the Request Object. + + 1. It MUST validate the signature of the Request Object using the algorithm specified in the ``alg`` header parameter (:rfc:`9126`, :rfc:`9101`) and the public key retrieved from the Wallet Attestation (``cnf.jwk``) referenced in the Request Object, using the ``kid`` JWS header parameter. + 2. It MUST check that the used algorithm for signing the request in the ``alg`` header is one of the listed within the Section `Cryptographic Algorithms `_. + 3. It MUST check that the ``client_id`` in the request body of the PAR request matches the ``client_id`` claim included in the Request Object. 4. It MUST check that the ``iss`` claim in the Request Object matches the ``client_id`` claim in the Request Object (:rfc:`9126`, :rfc:`9101`). - 5. It MUST check that the ``aud`` claim in the Request Object is equal to the identifier of PID/(Q)EAA Provider (:rfc:`9126`, :rfc:`9101`). + 5. It MUST check that the ``aud`` claim in the Request Object is equal to the PID/(Q)EAA Provider authorization endpoint uri (:rfc:`9126`, :rfc:`9101`). 6. It MUST reject the PAR request, if it contains the ``request_uri`` parameter (:rfc:`9126`). - 7. It MUST check that the Request Object contains all the mandatory parameters and their values are validated according to what we defined in :ref:`Table of the HTTP parameters ` [derived from :rfc:`9126`]. - 8. It MUST check that the Request Object is not expired by checking the ``exp`` claim (:rfc:`9126`). - 9. It MUST check that the Request Object was issued at a time acceptable by the PID/(Q)EAA Provider by checking the ``iat`` claim. For example, basing on the security policies of the PID/(Q)EAA Provider, it might reject the request if the ``iat`` claim is too far away from the current time (:rfc:`9126`). + 7. It MUST check that the Request Object contains all the mandatory parameters which values are validated according to :ref:`Table of the HTTP parameters ` [derived from :rfc:`9126`]. + 8. It MUST check that the Request Object is not expired, checking the ``exp`` claim (:rfc:`9126`). + 9. It MUST check that the Request Object was issued in a previous time than the value exposed in the ``iat`` claim. It SHOULD reject the request if the ``iat`` claim is far from the current time (:rfc:`9126`) of more than `5` minutes. 10. It MUST check that the ``jti`` claim in the Request Object has not been used before by the Wallet Instance identified by the ``client_id``. This allows the PID/(Q)EAA Provider to mitigate replay attacks (:rfc:`7519`). 11. It MUST validate the ``client_assertion`` parameter based on Sections 4.1 and 4.2 of [`oauth-attestation-draft `_]. @@ -125,20 +129,20 @@ Below a non-normative example of the PAR. POST /as/par HTTP/1.1 Host: pid-provider.example.org Content-Type: application/x-www-form-urlencoded - + response_type=code &client_id=$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$ &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM &code_challenge_method=S256 &request=$SIGNED-JWT &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation - &client_assertion=$WIA~WIA-PoP + &client_assertion=$WIA~WIA-PoP -An example of Wallet Instance Attestation Proof of Possession is as the following: +Below an non-normative example of the Wallet Attestation Proof of Possession without encoding and signature applied: -.. code-block:: +.. code-block:: - { + { "alg": "ES256", "kid": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c", "typ": "jwt-client-attestation-pop", @@ -146,13 +150,13 @@ An example of Wallet Instance Attestation Proof of Possession is as the followin . { "iss": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c", - "aud": "https://pid-provider.example.org", + "aud": "https://pid-provider.example.org/par-endpoint", "jti": "ad25868c-8377-479b-8094-46fb1e797625", "iat": 1686645115, "exp": 1686652315 } -The JWS of Request Object is represented below: +Below an non-normative example of the signed Request Object without encoding and signature applied: .. code-block:: @@ -173,13 +177,10 @@ The JWS of Request Object is represented below: "code_challenge":"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "code_challenge_method":"S256", "authorization_details":[ - { - "type":"openid_credential", - "format": "vc+sd-jwt", - "credential_definition": { - "type": "PersonIdentificationData" - } - } + { + "type": "openid_credential", + "credential_configuration_id": "PersonIdentificationData" + } ], "redirect_uri":"eudiw://start.wallet.example.org", } @@ -187,22 +188,30 @@ The JWS of Request Object is represented below: .. note:: - **Federation Check:** The PID/(Q)EAA Provider MUST check that the Wallet Provider is part of the federation and in addition it MUST verify the Wallet Instance Attestation validity by checking its signature and data. + **Federation Check:** The PID/(Q)EAA Provider MUST check that the Wallet Provider is part of the federation. -**Step 7 (PAR Response):** The PID/(Q)EAA Provider MUST issue the ``request_uri`` one-time use and bind it to the client identifier (``client_id``) that is provided in the Request Object. Furthermore, the entropy of the ``request_uri`` MUST be sufficiently large. The adequate shortness of the validity and the entropy of the ``request_uri`` depends on the risk calculation based on the value of the resource being protected. The validity time SHOULD be less than a minute, and the ``request_uri`` MUST include a cryptographic random value of 128 bits or more (:rfc:`9101`). The entire ``request_uri`` SHOULD NOT exceed 512 ASCII characters due to the following two main reasons (:rfc:`9101`): +.. note:: + The PID/(Q)EAA Provider MUST validate the signature of the the Wallet Attestation and that it is not expired. + + +**Step 7 (PAR Response):** The PID/(Q)EAA Provider provides a one-time use ``request_uri`` value. The issued ``request_uri`` value must be bound to the client identifier (``client_id``) that was provided in the Request Object. - 1. Many phones on the market still do not accept large payloads. The restriction is typically either 512 or 1024 ASCII characters. - 2. On a slow connection such as a 2G mobile connection, a large URL would cause a slow response; therefore, the use of such is not advisable from the user-experience point of view. - - The PID/(Q)EAA Provider returns the issued ``request_uri`` to the Wallet Instance. + +.. note:: + The entropy of the ``request_uri`` MUST be sufficiently large. The adequate shortness of the validity and the entropy of the ``request_uri`` depends on the risk calculation based on the value of the resource being protected. The validity time SHOULD be less than a minute, and the ``request_uri`` MUST include a cryptographic random value of 128 bits or more (:rfc:`9101`). The entire ``request_uri`` SHOULD NOT exceed 512 ASCII characters due to the following two main reasons (:rfc:`9101`): + + 1. Many phones on the market still do not accept large payloads. The restriction is typically either 512 or 1024 ASCII characters. + 2. On a slow connection such as a 2G mobile connection, a large URL would cause a slow response; therefore, the use of such is not advisable from the user-experience point of view. + +The PID/(Q)EAA Provider returns the issued ``request_uri`` to the Wallet Instance. A non-normative example of the response is shown below. .. code-block:: http HTTP/1.1 201 Created Cache-Control: no-cache, no-store Content-Type: application/json - + { "request_uri":"urn:ietf:params:oauth:request_uri:bwc4JK-ESC0w8acc191e-Y1LTC2", "expires_in": 60 @@ -213,19 +222,19 @@ The JWS of Request Object is represented below: 1. It MUST treat ``request_uri`` values as one-time use and MUST reject an expired request. However, it MAY allow for duplicate requests due to a user reloading/refreshing their user-agent (derived from :rfc:`9126`). 2. It MUST identify the request as a result of the submitted PAR (derived from :rfc:`9126`). - 3. It MUST reject all the Authorization Requests that do not contain the ``request_uri`` parameter as the PAR is the only way to pass the Authorization Request from the Wallet Instance (derived from :rfc:`9126`). + 3. It MUST reject all the Authorization Requests that do not contain the ``request_uri`` parameter as the PAR is the only way to pass the Authorization Request from the Wallet Instance (derived from :rfc:`9126`). .. code-block:: http GET /authorize?client_id=$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$&request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3Abwc4JK-ESC0w8acc191e-Y1LTC2 HTTP/1.1 Host: pid-provider.example.org - + .. note:: - **User Authentication and Consent:** The PID Provider performs the User authentication based on the requirements of eIDAS LoA High by means of national notified eIDAS scheme and requires the User consent for the PID issuance. - The (Q)EAA Provider performs the User authentication requesting a valid PID to the Wallet Instance. The (Q)EAA Provider MUST use [`OpenID4VP`_] to dynamically request the presentation of the PID. From a protocol perspective, the (Q)EAA Provider then acts as a Relying Party and provide the presentation request to the Wallet Instance. The Wallet Instance MUST have a valid PID obtained prior to start the transaction with the (Q)EAA Provider. + **User Authentication and Consent:** The PID Provider performs the User authentication based on the requirements of eIDAS LoA High by means of national notified eIDAS scheme and requires the User consent for the PID issuance. + The (Q)EAA Provider performs the User authentication requesting a valid PID to the Wallet Instance. The (Q)EAA Provider MUST use [`OpenID4VP`_] to dynamically request the presentation of the PID. From a protocol perspective, the (Q)EAA Provider acts as a Relying Party, providing the presentation request to the Wallet Instance. The Wallet Instance MUST have a valid PID obtained prior to start the transaction with the (Q)EAA Provider. **Steps 10-11 (Authorization Response):** The PID/(Q)EAA Provider sends an authorization ``code`` together with ``state`` and ``iss`` parameters to the Wallet Instance. The Wallet Instance performs the following checks on the Authorization Response: @@ -237,22 +246,21 @@ The JWS of Request Object is represented below: .. note:: The Wallet Instance redirect URI is a universal or app link registered with the local operating system, so this latter will resolve it and pass the response to the Wallet Instance. - + .. code-block:: http HTTP/1.1 302 Found - Location: eudiw://start.wallet.example.org?code=SplxlOBeZQQYbYS6WxSbIA&state=fyZiOL9Lf2CeKuNT2JzxiLRDink0uPcd&iss=https%3A%2F%2Fpid-provider.example.org + Location: https://start.wallet.example.org?code=SplxlOBeZQQYbYS6WxSbIA&state=fyZiOL9Lf2CeKuNT2JzxiLRDink0uPcd&iss=https%3A%2F%2Fpid-provider.example.org -**Steps 12-13 (DPoP Proof for Token Endpoint)**: The Wallet Instance MUST create a new key pair for the DPoP and a fresh DPoP Proof JWT following the instruction provided in Section 4 of (:rfc:`9449`) for the token request to the PID/(Q)EAA Provider. The DPoP Proof JWT is signed using the created private key for DPoP by Wallet Instance. DPoP provides a way to bind the Access Token to a certain sender (Wallet Instance) (:rfc:`9449`). This mitigates the misuse of leaked or stolen Access Tokens at the Credential Endpoint of PID/(Q)EAA Issuer as the attacker needs to present a valid DPoP Proof JWT. +**Steps 12-13 (DPoP Proof for Token Endpoint)**: The Wallet Instance MUST create a new key pair for the DPoP and a fresh DPoP Proof JWT following the instruction provided in Section 4 of (:rfc:`9449`) for the token request to the PID/(Q)EAA Provider. The DPoP Proof JWT is signed using the private key for DPoP created by Wallet Instance for this scope. DPoP binds the Access Token to a certain Wallet Instance (:rfc:`9449`) and mitigates the misuse of leaked or stolen Access Tokens at the Credential Endpoint. -**Step 14 (Token Request):** The Wallet Instance sends a token request to the PID/(Q)EAA Provider Token Endpoint using the authorization ``code``, ``code_verifier``, *DPoP Proof JWT* and OAuth 2.0 Attestation based Client Authentication parameters (``client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation`` and ``client_assertion=WIA~WIA-PoP``). -The ``client_assertion`` is signed using the private key that is created during the setup phase to obtain the Wallet Instance Attestation. The related public key that is attested by the Wallet Provider is provided within the Wallet Instance Attestation (``cnf`` claim). The PID/(Q)EAA Provider performs the following checks on the Token Request: +**Step 14 (Token Request):** The Wallet Instance sends a token request to the PID/(Q)EAA Provider Token Endpoint with a *DPoP Proof JWT* and the parameters: ``code``, ``code_verifier``, and OAuth 2.0 Attestation based Client Authentication (``client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation`` and ``client_assertion=WIA~WIA-PoP``). +The ``client_assertion`` is signed using the private key that is created during the setup phase to obtain the Wallet Attestation. The related public key that is attested by the Wallet Provider is provided within the Wallet Attestation (``cnf`` claim). The PID/(Q)EAA Provider performs the following checks on the Token Request: - 1. It MUST authenticate the Wallet Instance based on the OAuth 2.0 Attestation based Client Authentication method `oauth-attestation-draft `_. - 2. It MUST ensure that the Authorization ``code`` is issued to the authenticated Wallet Instance (:rfc:`6749`). - 3. It MUST ensure the Authorization ``code`` is valid and has not been previously used (:rfc:`6749`). - 4. It MUST ensure the ``redirect_uri`` is identical to the value that was initially included in the Request Object `OpenID.Core#TokenRequest `_. - 5. It MUST validate the DPoP Proof JWT following the steps in Section 4.3 of (:rfc:`9449`). + 1. It MUST ensure that the Authorization ``code`` is issued to the authenticated Wallet Instance (:rfc:`6749`) and was not replied. + 2. It MUST ensure the Authorization ``code`` is valid and has not been previously used (:rfc:`6749`). + 3. It MUST ensure the ``redirect_uri`` matches the value included in the previous Request Object `OpenID.Core#TokenRequest `_. + 4. It MUST validate the DPoP Proof JWT, according to (:rfc:`9449`) Section 4.3. .. code-block:: http @@ -267,41 +275,54 @@ The ``client_assertion`` is signed using the private key that is created during WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg - client_id=$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$ - &grant_type=authorization_code + grant_type=authorization_code &code=SplxlOBeZQQYbYS6WxSbIA - &redirect_uri=eudiw://start.wallet.example.org &code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk + &redirect_uri=https://start.wallet.example.org/cb &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation &client_assertion=$WIA~WIA-PoP +**Step 15 (Token Response):** The PID/(Q)EAA Provider validates the request, if successful an *Access Token* (bound to the DPoP key) and a fresh `c_nonce` are provided by the Issuer to the Wallet Instance. The parameter `c_nonce` is a string value, which MUST be unpredictable and is used later by the Wallet Instance in Step 18 to create the proof of possession of the key (*proof* claim) and it is the primary countermeasure against key proof replay attack. Note that, the received `c_nonce` value can be used to create the proof as long as the Issuer provides the Wallet Instance with a new `c_nonce` value. -**Step 15 (Token Response):** The PID/(Q)EAA Provider validates the request and if it is successful, it issues an *Access Token* (bound to the DPoP key) and a fresh ``c_nonce``. - -.. code-block:: http +.. code-block:: HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store - + { - "access_token": "Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU", - "token_type": "DPoP", - "expires_in": 2677, - "c_nonce": "tZign[...]snFbp", - "c_nonce_expires_in": 86400 + "access_token": "Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU ...", + "token_type": "DPoP", + "expires_in": 2677, + "c_nonce": "tZign[...]snFbp", + "c_nonce_expires_in": 86400, + "authorization_details": [ + { + "type": "openid_credential", + "credential_configuration_id: "PersonIdentificationData" + } + } + ] } -**Steps 16-17 (DPoP Proof for Credential Endpoint):** The Wallet Instance creates a proof of possession with the DPoP key following the steps in Section 7.2.1 of `OPENID4VCI`_ and the ``c_nonce`` obtained in **Step 15** and it creates a DPoP Proof JWT based on Section 4 of (:rfc:`9449`) for the request to the PID/(Q)EAA credential issuance endpoint. The ``jwk`` value in the proof parameter MUST be equal to the public key generated for the DPoP. +**Steps 16-17 (DPoP Proof for Credential Endpoint):** The Wallet Instance for requesting the Digital Credential creates a proof of possession with ``c_nonce`` obtained in **Step 15** and using the private key used for the DPoP, signing a DPoP Proof JWT according to (:rfc:`9449`) Section 4. The ``jwk`` value in the ``proof`` parameter MUST be equal to the public key referenced in the DPoP. + +**Step 18 (Credential Request):** The Wallet Instance sends a request for the Digital Credential to the PID/(Q)EAA Credential endpoint. This request MUST include the Access Token, DPoP Proof JWT, credential type, proof (which demonstrates possession of the key), and format parameters. The proof parameter MUST be an object that contains evidence of possession of the cryptographic key material to which the issued PID/(Q)EAA Digital Credential will be bound. To verify the proof, the PID/(Q)EAA Provider conducts the following checks at the Credential endpoint: + + 1. the JWT proof MUST include all required claims as specified in the table of Section :ref:`Token Request `; + 2. The key proof MUST be explicitly typed using header parameters as defined for the respective proof type; + 3. The header parameter alg MUST indicate a registered asymmetric digital signature algorithm, and MUST NOT be set to `none`; + 4. The signature on the key proof MUST be verified using the public key specified in the header parameter. + 5. The header parameter MUST NOT contain a private key. + 6. If a `c_nonce` value was previously provided by the server, the nonce claim in the JWT MUST match this `c_nonce` value. Furthermore, the creation time of the JWT, as indicated by the `iat` claim or a server-managed timestamp via the nonce claim, MUST be within an acceptable window of time as determined by the server. -**Step 18 (Credential Request):** The Wallet Instance requests a PID/(Q)EAA issuance to the PID/(Q)EAA credential endpoint. The request MUST contain the *Access Token*, the *DPoP Proof JWT*, and the *credential type*, the ``proof`` (proof of possession of the key) and the ``format`` parameters. .. note:: - **PID/(Q)EAA Credential Schema and Status registration:** The PID/(Q)EAA Provider MUST register all the issued credentials for their later revocation, if needed. + **PID/(Q)EAA Credential Schema and Status registration:** The PID/(Q)EAA Provider MUST register all the issued Credentials for their later revocation, if needed. -.. code-block:: +.. code-block:: POST /credential HTTP/1.1 Host: pid-provider.example.org @@ -327,7 +348,8 @@ The ``client_assertion`` is signed using the private key that is created during } -Where the decoded content of the ``jwt`` parameter is represented below: +Where a non-normative example of the decoded content of the ``jwt`` parameter is represented below, +without encoding and signature. The JWS header: .. code-block:: JSON @@ -343,25 +365,27 @@ Where the decoded content of the ``jwt`` parameter is represented below: } +And the JWS payload: + .. code-block:: JSON { - "iss": "0b434530-e151-4c40-98b7-74c75a5ef760", - "aud": "https://pid-provider.example.org", - "iat": 1504699136, - "nonce": "tZign...snFbp" + "iss": "0b434530-e151-4c40-98b7-74c75a5ef760", + "aud": "https://pid-provider.example.org/credential", + "iat": 1504699136, + "nonce": "tZign...snFbp" } -**Steps 19-21 (Credential Response):** The PID/(Q)EAA Provider MUST validate the *DPoP JWT Proof* based on the steps defined in Section 4.3 of (:rfc:`9449`) and whether the *Access Token* is valid and suitable for the requested PID/(Q)EAA. It also MUST validate the proof of possession for the key material the new credential SHALL be bound to following the steps in Section 7.2.2 of `OPENID4VCI`_. If all checks succeed, the PID/(Q)EAA Provider creates a new credential bound to the key material and provide it to the Wallet Instance. The Wallet Instance MUST perform the following checks before proceeding with the secure storage of the PID/(Q)EAA credential: +**Steps 19-21 (Credential Response):** The PID/(Q)EAA Provider MUST validate the *DPoP JWT Proof* based on the steps defined in Section 4.3 of (:rfc:`9449`) and whether the *Access Token* is valid and suitable for the requested PID/(Q)EAA. It also MUST validate the proof of possession for the key material the new credential SHALL be bound to, according to `OPENID4VCI`_ Section 7.2.2. If all checks succeed, the PID/(Q)EAA Provider creates a new Credential bound to the key material and provide it to the Wallet Instance. The Wallet Instance MUST perform the following checks before proceeding with the secure storage of the PID/(Q)EAA: 1. It MUST check that the PID Credential Response contains all the mandatory parameters and values are validated according to :ref:`Table of the credential response parameters `. 2. It MUST check the PID integrity by verifying the signature using the algorithm specified in the ``alg`` header parameter of SD-JWT (:ref:`PID/(Q)EAA Data Model `) and the public key that is identified using using the ``kid`` header of the SD-JWT. - 3. It MUST check that the received PID credential (in credential claim) contains all the mandatory parameters defined in :ref:`PID/(Q)EAA Data Model `. - 4. It MUST process and verify the PID that is in SD-JWT VC following the steps in Section 6 of `SD.JWT#Verification `_. + 3. It MUST check that the received PID (in credential claim) matches the schema defined in :ref:`PID/(Q)EAA Data Model `. + 4. It MUST process and verify the PID in SD-JWT VC format (according to `SD.JWT#Verification `_ Section 6.) or MDOC CBOR format. 5. It MUST verify the Trust Chain in the header of SD-JWT VC to verify that the PID Provider is trusted. -If the checks defined above are successful the Wallet Instance proceeds with the secure storage of the PID credential. +If the checks defined above are successful the Wallet Instance proceeds with the secure storage of the PID/(Q)EAA. .. code-block:: http @@ -369,12 +393,12 @@ If the checks defined above are successful the Wallet Instance proceeds with the Content-Type: application/json Cache-Control: no-store Pragma: no-cache - + { - "format": "vc+sd-jwt" - "credential" : "LUpixVCWJk0eOt4CXQe1NXK[...]WZwmhmn9OQp6YxX0a2L", - "c_nonce": "fGFF7[...]UkhLa", - "c_nonce_expires_in": 86400 + "format": "vc+sd-jwt" + "credential" : "LUpixVCWJk0eOt4CXQe1NXK[...]WZwmhmn9OQp6YxX0a2L", + "c_nonce": "fGFF7[...]UkhLa", + "c_nonce_expires_in": 86400 } Pushed Authorization Request Endpoint @@ -385,7 +409,7 @@ Pushed Authorization Request (PAR) Request The requests to the PID/(Q)EAA authorization endpoint MUST use the HTTP POST method with the parameters in the message body encoded in ``application/x-www-form-urlencoded`` format. The Pushed Authorization Endpoint is protected with OAuth 2.0 Attestation-based Client Authentication [`oauth-attestation-draft `_] and the following parameters MUST be provided: -.. _table_http_request_claim: +.. _table_http_request_claim: .. list-table:: PAR http request parameters :widths: 20 60 20 :header-rows: 1 @@ -397,7 +421,7 @@ The requests to the PID/(Q)EAA authorization endpoint MUST use the HTTP POST met - MUST be set to ``code``. - :rfc:`6749` * - **client_id** - - MUST be set to the thumbprint of the ``jwk`` value in the ``cnf`` parameter inside the Wallet Instance Attestation. + - MUST be set to the thumbprint of the ``jwk`` value in the ``cnf`` parameter inside the Wallet Attestation. - :rfc:`6749` * - **code_challenge** - A challenge derived from the **code verifier** that is sent in the authorization request. @@ -406,18 +430,18 @@ The requests to the PID/(Q)EAA authorization endpoint MUST use the HTTP POST met - A method that was used to derive **code challenge**. It MUST be set to ``S256``. - :rfc:`7636#section-4.3`. * - **request** - - It MUST be a signed JWT. The private key corresponding to the public one in the ``cnf`` parameter inside the Wallet Instance Attestation MUST be used for signing the Request Object. + - It MUST be a signed JWT. The private key corresponding to the public one in the ``cnf`` parameter inside the Wallet Attestation MUST be used for signing the Request Object. - `OpenID Connect Core. Section 6 `_ * - **client_assertion_type** - It MUST be set to ``urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation``. - `oauth-attestation-draft `_. * - **client_assertion** - - It MUST be set to a value containing the Wallet Instance Attestation JWT and the Proof of Possession, separated with the ``~`` character. + - It MUST be set to a value containing the Wallet Attestation JWT and the Proof of Possession, separated with the ``~`` character. - `oauth-attestation-draft `_. The JWT Request Object has the following JOSE header parameters: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -428,8 +452,8 @@ The JWT Request Object has the following JOSE header parameters: - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms listed in the Section `Cryptographic Algorithms `_ and MUST NOT be set to ``none`` or any symmetric algorithm (MAC) identifier. - :rfc:`7516#section-4.1.1`. * - **kid** - - Unique identifier of the ``jwk`` inside the ``cnf`` claim of Wallet Instance Attestation as base64url-encoded JWK Thumbprint value. - - :rfc:`7638#section_3`. + - Unique identifier of the ``jwk`` inside the ``cnf`` claim of Wallet Attestation as base64url-encoded JWK Thumbprint value. + - :rfc:`7638#section_3`. .. note:: The parameter **typ**, if omitted, assumes the implicit value **JWT**. @@ -438,7 +462,7 @@ The JWT Request Object has the following JOSE header parameters: The JWT payload is given by the following parameters: .. _table_jwt_request: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -474,10 +498,9 @@ The JWT payload is given by the following parameters: - See :ref:`Table of the HTTP parameters `. * - **authorization_details** - Array of JSON Objects. Each JSON Object MUST include the following claims: - + - **type**: it MUST be set to ``openid_credential``, - - **format**: it MUST be set to ``vc+sd-jwt``, - - **credential_definition**: JSON Object. It MUST have the **type** claim which MUST be set in accordance to the type of the requested PID/(Q)EAA that is obtained from the metadata of the PID/(Q)EAA Issuer. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData``. + - **credential_configuration_id**: JSON String. String specifying a unique identifier of the Credential being described in the `credential_configurations_supported` map in the Credential Issuer Metadata. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData``. - See [RAR :rfc:`9396`] and `[OIDC4VCI. Draft 13] `_. * - **redirect_uri** - Redirection URI to which the response is intended to be sent. It MUST be an universal or app link registered with the local operating system, so this latter will provide the response to the Wallet Instance. @@ -492,10 +515,10 @@ The JWT payload is given by the following parameters: - Unique identifier of the JWT that, together with the value contained in the ``iss`` claim, prevents the reuse of the JWT (replay attack). Since the `jti` value alone is not collision resistant, it MUST be identified uniquely together with its issuer. - [:rfc:`7519`]. -The JOSE header of the Wallet Instance Attestation Proof of Possession MUST contain: +The JOSE header of the Wallet Attestation proof of possession MUST contain: .. _table_jwt_pop: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -506,15 +529,15 @@ The JOSE header of the Wallet Instance Attestation Proof of Possession MUST cont - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms listed in the Section `Cryptographic Algorithms `_ and MUST NOT be set to ``none`` or any symmetric algorithm (MAC) identifier. - :rfc:`7516#section-4.1.1`. * - **kid** - - Unique identifier of the ``jwk`` inside the ``cnf`` claim of Wallet Instance Attestation as base64url-encoded JWK Thumbprint value. - - :rfc:`7638#section_3`. + - Unique identifier of the ``jwk`` inside the ``cnf`` claim of Wallet Attestation as base64url-encoded JWK Thumbprint value. + - :rfc:`7638#section_3`. * - **typ** - It MUST be set to ``jwt-client-attestation-pop`` - Currently under discussion in [`oauth-attestation-draft `_]. -The body of the Wallet Instance Attestation Proof of Possession JWT MUST contain: +The body of the Wallet Attestation proof of possession JWT MUST contain: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -545,7 +568,7 @@ Pushed Authorization Request (PAR) Response If the verification is successful, the PID/(Q)EAA Issuer MUST provide the response with a *201 HTTP status code*. The following parameters are included as top-level members in the HTTP response message body, using the ``application/json`` media type as defined in [:rfc:`8259`]. .. _table_http_response_claim: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -574,7 +597,7 @@ The Authorization request is issued by the Web Browser in use by the Wallet Inst The mandatory parameters in the HTTP authentication request are specified in the following table. -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -596,7 +619,7 @@ The authentication response is returned by the PID/(Q)EAA authorization endpoint If the authentication is successful the PID/(Q)EAA Issuer redirects the User by adding the following query parameters as required to the *redirect_uri*. The redirect URI MUST be an universal or app link registered with the local operating system, so this latter is able to provide the response to the Wallet Instance. -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -614,32 +637,30 @@ If the authentication is successful the PID/(Q)EAA Issuer redirects the User by - `OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response `_, `[RFC7519, Section 4.1.1] `_. - Token endpoint -------------- -The token endpoint is used by the Wallet Instance to obtain an Access Token by presenting its authorization grant, as +The token endpoint is used by the Wallet Instance to obtain an Access Token by presenting an authorization grant, as defined in :rfc:`6749`. The Token Endpoint is a protected endpoint with a client authentication based on the model defined in OAuth 2.0 Attestation-based Client Authentication [`oauth-attestation-draft `_]. +.. _sec_token_request: + Token Request ^^^^^^^^^^^^^^^ The request to the PID/(Q)EAA Token endpoint MUST be an HTTP request with method POST, with the body message encoded in ``application/x-www-form-urlencoded`` format. The Wallet Instance sends the Token endpoint request with ``client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation`` and ``client_assertion=WIA~WIA-PoP``. -The Token endpoint MUST accept and validate the DPoP proof sent in the DPoP HTTP header. The Token endpoint MUST validate the DPoP proof according to Section 4.3 of the DPoP specifications (:rfc:`9449`). Thus, this mitigates the misuse of leaked or stolen Access Tokens at the credential endpoint. If the DPoP proof is invalid, the Token endpoint returns an error response, according to Section 5.2 of [:rfc:`6749`] with ``invalid_dpop_proof`` as the value of the error parameter. +The Token endpoint MUST accept and validate the DPoP proof sent in the DPoP HTTP header. The Token endpoint MUST validate the DPoP proof according to Section 4.3 of the DPoP specifications (:rfc:`9449`). This mitigates the misuse of leaked or stolen Access Tokens at the credential endpoint. If the DPoP proof is invalid, the Token endpoint returns an error response, according to Section 5.2 of [:rfc:`6749`] with ``invalid_dpop_proof`` as the value of the error parameter. All the parameters listed below are REQUIRED: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 * - **Claim** - **Description** - **Reference** - * - **client_id** - - It MUST be set as in the :ref:`Table of the HTTP parameters `. - - See :ref:`Table of the HTTP parameters `. * - **grant_type** - It MUST be set to ``authorization_code``. - `Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants `_. @@ -656,34 +677,34 @@ All the parameters listed below are REQUIRED: - It MUST be set to ``urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation``. - `oauth-attestation-draft `_. * - **client_assertion** - - It MUST be set to a value containing the Wallet Instance Attestation JWT and the Proof of Possession JWT, separated with the ``~`` character (WIA~WIA-PoP). The Wallet Instance Attestation Proof of Possession MUST contain the claims as defined in :ref:`Table of the JWT Wallet Instance Attestation PoP `, Section :ref:`Pushed Authorization Request (PAR) Response`. + - It MUST be set to a value containing the Wallet Attestation JWT and the Proof of Possession JWT, separated with the ``~`` character (WIA~WIA-PoP). The Wallet Attestation Proof of Possession MUST contain the claims as defined in :ref:`Table of the JWT Wallet Attestation PoP `, Section :ref:`Pushed Authorization Request (PAR) Response`. - `oauth-attestation-draft `_. -A **DPoP Proof JWT** is included in an HTTP request using the ``DPoP`` header parameter containing a DPoP JWS. +A **DPoP Proof JWT** is included in the HTTP request using the ``DPoP`` header parameter containing a DPoP JWS. The JOSE header of a **DPoP JWT** MUST contain at least the following parameters: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 * - **JOSE header** - **Description** - **Reference** - * - **typ** - - It MUST be equal to ``dpop+jwt``. + * - **typ** + - It MUST be equal to ``dpop+jwt``. - [:rfc:`7515`] and [:rfc:`8725`. Section 3.11]. - * - **alg** + * - **alg** - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms in Section :ref:`Cryptographic Algorithms ` and MUST NOT be set to ``none`` or with a symmetric algorithm (MAC) identifier. - [:rfc:`7515`]. - * - **jwk** - - It represents the public key chosen by the Wallet Instance, in JSON Web Key (JWK) [:rfc:`7517`] format that the Access Token shall be bound to, as defined in Section 4.1.3 of [:rfc:`7515`]. It MUST NOT contain a private key. + * - **jwk** + - It represents the public key chosen by the Wallet Instance, in JSON Web Key (JWK) [:rfc:`7517`] format that the Access Token MUST be bound to, as defined in [:rfc:`7515`] Section 4.1.3. It MUST NOT contain a private key. - [:rfc:`7517`] and [:rfc:`7515`]. The payload of a **DPoP JWT Proof** MUST contain at least the following claims: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -700,7 +721,7 @@ The payload of a **DPoP JWT Proof** MUST contain at least the following claims: - The HTTP target URI, without query and fragment parts, of the request to which the JWT is attached. - [:rfc:`9110`. Section 7.1]. * - **iat** - - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. + - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. - [:rfc:`7519`. Section 4.1.6]. @@ -709,7 +730,7 @@ Token Response Token endpoint response MUST contain the following mandatory claims. -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -726,43 +747,44 @@ Token endpoint response MUST contain the following mandatory claims. - Expiry time of the *Access Token* in seconds. - :rfc:`6749`. * - **c_nonce** - - JSON string containing a ``nonce`` value to be used to create a *proof of possession* of key material when requesting a credential. + - JSON string containing a ``nonce`` value to be used to create a *proof of possession* of key material when requesting a Credential. - `[OIDC4VCI. Draft 13] `_. * - **c_nonce_expires_in** - JSON integer, it represents the lifetime in seconds of the **c_nonce**. - `[OIDC4VCI. Draft 13] `_. + * - **authorization_details** + - JSON object, used to identify Credentials with the same metadata but different claimset/claim values and/or simplify the Credential request even when only one Credential is being issued. + - `[OIDC4VCI. Draft 13] `_. + Access Token ^^^^^^^^^^^^ A DPoP-bound Access Token is provided by the PID/(Q)EAA Token endpoint as a result of a successful token request. The Access Token is encoded in JWT format, according to [:rfc:`7519`]. The Access Token MUST have at least the following mandatory claims and it MUST be bound to the public key that is provided by the DPoP proof. This binding can be accomplished based on the methodology defined in Section 6 of (:rfc:`9449`). -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 * - **Claim** - **Description** - **Reference** - * - **iss** + * - **iss** - It MUST be an HTTPS URL that uniquely identifies the PID/(Q)EAA Issuer. The Wallet Instance MUST verify that this value matches the PID/(Q)EAA Issuer where it has requested the credential. - [:rfc:`9068`], `[RFC7519, Section 4.1.1] `_. - * - **sub** - - It identifies the subject of the JWT. It MUST be set to the value of the ``sub`` field in the PID/(Q)EAA SD-JWT-VC. + * - **sub** + - It identifies the subject of the JWT. It MUST be set to the value of the ``sub`` field in the PID/(Q)EAA SD-JWT-VC. - [:rfc:`9068`], [:rfc:`7519`] and [`OpenID.Core#SubjectIDTypes `_]. - * - **client_id** - - As provided in the Wallet Instance Attestation. - - [:rfc:`9068`]. - * - **aud** - - It Must be Set to the URL of Credential Endpoint of the PID/(Q)EAA Provider. + * - **aud** + - It MUST be set to the URL of Credential Endpoint of the PID/(Q)EAA Provider. - [:rfc:`9068`]. - * - **iat** - - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. + * - **iat** + - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. - [:rfc:`9068`], [:rfc:`7519`. Section 4.1.6]. * - **exp** - UNIX Timestamp with the expiry time of the JWT, coded as NumericDate as indicated in :rfc:`7519`. - [:rfc:`9068`], [:rfc:`7519`]. - * - **jti** + * - **jti** - It MUST be a String in *uuid4* format. Unique Token ID identifier that the RP MAY use to prevent reuse by rejecting the Token ID if already processed. - [:rfc:`9068`], [:rfc:`7519`]. * - **jkt** @@ -773,25 +795,25 @@ A DPoP-bound Access Token is provided by the PID/(Q)EAA Token endpoint as a resu Credential endpoint ------------------- -The Credential Endpoint issues a credential as approved by the End-User upon presentation of a valid Access Token representing this approval, as defined in `OPENID4VCI`_. +The Credential Endpoint issues a Credential upon the presentation of a valid Access Token, as defined in `OPENID4VCI`_. Credential Request ^^^^^^^^^^^^^^^^^^^ -The Wallet Instance when requests the PID/(Q)EAA to the PID/(Q)EAA Credential endpoint, MUST use the following parameters in the entity-body of the HTTP POST request, using the `application/json` media type. +The Wallet Instance when requests the PID/(Q)EAA to the PID/(Q)EAA Credential endpoint, MUST use the following parameters in the message body of the HTTP POST request, using the `application/json` media type. -The Credential endpoint MUST accept and validate the *DPoP proof* sent in the DPoP field of the Header based on the steps defined in Section 4.3 of (:rfc:`9449`). The *DPoP proof* in addition to the values that are defined in the Token Endpoint section MUST contain the following claim: +The Credential endpoint MUST accept and validate the *DPoP proof* sent in the DPoP HTTP Header parameter, according to the steps defined in (:rfc:`9449`) Section 4.3. The *DPoP proof* in addition to the values that are defined in the Token Endpoint section MUST contain the following claim: - - **ath**: hash of the Access Token. The value MUST be the result of a base64url encoding (as defined in Section 2 of :rfc:`7515`) the SHA-256 hash of the ASCII encoding of the associated Access Token's value. + - **ath**: hash value of the Access Token encoded in ASCII. The value MUST use the base64url encoding (as defined in Section 2 of :rfc:`7515`) with the SHA-256 algorithm. -If the *DPoP proof* is invalid, the Credential endpoint returns an error response per Section 5.2 of [:rfc:`6749`] with `invalid_dpop_proof` as the value of the error parameter. +If the *DPoP proof* is invalid, the Credential endpoint returns an error response per Section 5.2 of [:rfc:`6749`] with `invalid_dpop_proof` as the value of the error parameter. .. warning:: - The Wallet Instance MUST create a **new DPoP proof** for the Credential request and MUST NOT use the previously created proof for the Token Endpoint. + The Wallet Instance MUST create a **new DPoP proof** for the Credential request and MUST NOT use the previously created proof for the Token Endpoint. -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -799,16 +821,16 @@ If the *DPoP proof* is invalid, the Credential endpoint returns an error respons - **Description** - **Reference** * - **credential_definition** - - JSON object containing the detailed description of the credential type. It MUST have at least the **type** sub claims which is a JSON array containing the type values the Wallet SHALL request in the Credential Request. It MUST be set in accordance to the type of the requested PID/(Q)EAA that is obtained from the PID/(Q)EAA Issuer metadata. In the case of the PID it MUST be set to ``PersonIdentificationData``. + - JSON object containing the detailed description of the Credential type. It MUST have at least the **type** sub claims which is a JSON array containing the type values the Wallet SHALL request in the Credential Request. It MUST be set in accordance to the type of the requested PID/(Q)EAA that is obtained from the PID/(Q)EAA Issuer metadata. In the case of the PID it MUST be set to ``PersonIdentificationData``. - `[OIDC4VCI. Draft 13] `_. - * - **format** + * - **format** - Format of the Credential to be issued. This MUST be `vc+sd-jwt`. - `[OIDC4VCI. Draft 13] `_. * - **proof** - JSON object containing proof of possession of the key material the issued credential shall be bound to. The proof object MUST contain the following mandatory claims: - **proof_type**: JSON string denoting the proof type. It MUST be `jwt`. - - **jwt**: the JWT used as proof of possession. + - **jwt**: the JWT used as proof of possession. - `[OIDC4VCI. Draft 13] `_. .. note:: @@ -818,7 +840,7 @@ If the *DPoP proof* is invalid, the Credential endpoint returns an error respons The JWT proof type MUST contain the following parameters for the JOSE header and the JWT body: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -828,14 +850,14 @@ The JWT proof type MUST contain the following parameters for the JOSE header and * - **alg** - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms in Section :ref:`Cryptographic Algorithms ` and MUST NOT be set to ``none`` or to a symmetric algorithm (MAC) identifier. - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. - * - **typ** + * - **typ** - It MUST be set to `openid4vci-proof+jwt`. - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. - * - **jwk** - - Representing the public key chosen by the Wallet Instance, in JSON Web Key (JWK) [:rfc:`7517`] format that the PID/(Q)EAA shall be bound to, as defined in Section 4.1.3 of [:rfc:`7515`]. The ``jwk`` value MUST be equal to the same public key that is generated for the DPoP. + * - **jwk** + - Representing the public key chosen by the Wallet Instance, in JSON Web Key (JWK) [:rfc:`7517`] format that the PID/(Q)EAA shall be bound to, as defined in Section 4.1.3 of [:rfc:`7515`]. The ``jwk`` value MUST be equal to the same public key that is generated for the DPoP. - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -843,13 +865,13 @@ The JWT proof type MUST contain the following parameters for the JOSE header and - **Description** - **Reference** * - **iss** - - The value of this claim MUST be the **client_id** of the Wallet Instance. + - The value of this claim MUST be the **client_id** of the Wallet Instance. - `[OIDC4VCI. Draft 13] `_, `[RFC7519, Section 4.1.1] `_. * - **aud** - The value of this claim MUST be the identifier URL of the PID/(Q)EAA Issuer. - `[OIDC4VCI. Draft 13] `_. * - **iat** - - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. + - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. - `[OIDC4VCI. Draft 13] `_, [:rfc:`7519`. Section 4.1.6]. * - **nonce** - The value type of this claim MUST be a string, where the value is a **c_nonce** provided by the PID/(Q)EAA Issuer in the Token response. @@ -859,7 +881,7 @@ The JWT proof type MUST contain the following parameters for the JOSE header and Credential Response ^^^^^^^^^^^^^^^^^^^^ -Credential Response to the Wallet Instance MUST be sent using `application/json` media type. The response MUST contain the following mandatory claims: +Credential Response to the Wallet Instance MUST be sent using `application/json` media type. The response MUST contain the following mandatory claims: .. _table_credential_response_claim: .. list-table:: Credential http response parameters @@ -876,7 +898,7 @@ Credential Response to the Wallet Instance MUST be sent using `application/json` - Contains the issued PID/(Q)EAA. When the credential type is SD-JWT, it MUST be an SD-JWT JSON Object (see Section :ref:`PID/(Q)EAA Data Model `). - Appendix E in `[OIDC4VCI. Draft 13] `_. * - **c_nonce** - - JSON string containing a ``nonce`` value to be used to create a *proof of possession* of the key material when requesting a further credential or for the renewal of a credential. + - JSON string containing a ``nonce`` value to be used to create a *proof of possession* of the key material when requesting a further Credential or for the renewal of a credential. - `[OIDC4VCI. Draft 13] `_. * - **c_nonce_expires_in** - JSON integer corresponding to the **c_nonce** lifetime in seconds. @@ -895,7 +917,7 @@ Entity Configuration Credential Issuer Below is a non-normative example of an Entity Configuration containing an `openid_credential_issuer` metadata. .. code-block:: http - + HTTP/1.1 200 OK Content-Type: application/entity-statement+jwt @@ -922,48 +944,81 @@ Below is a non-normative example of an Entity Configuration containing an `openi "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY" } ] + "keys": [{ + "kty": "RSA", + "use": "sig", + "n": "1Ta-sE ...", + "e": "AQAB", + "kid": "FANFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs" + }] }, "authority_hints": ["https://superior-entity.example.org/federation"], "metadata": { "openid_credential_issuer": { "credential_issuer": "https://pid-provider.example.org", + "authorization_servers": ["https://pid-provider.example.org"], "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": ["ES256", "ES512"], "credential_endpoint": "https://pid-provider.example.org/credential", - "jwks": { + "display": [ + { + "name": "PID Provider Italiano di esempio", + "locale": "it-IT" + }, + { + "name": "Example PID Provider", + "locale": "en-US", + "logo": { + "url": "https://pid-provider example.org/public/logo.svg", + "alt_text": "logo di questo PID Provider" + }, + } + ], + "jwks": { "keys": [ - { + { "crv": "P-256", "kty": "EC", "x": "newK5qDYMekrCPPO-yEYTdJVWJMTzasMavt2vm1Mb-A", "y": "VizXaLO6dzeesZPxfpGZabTK3cTXtBUbIiQpmiYRtSE", "kid": "ff0bded045fe63fe5d1d64dd83b567e0" - }] - } - "credentials_supported": [ + } + ] + }, + "credential_configurations_supported": [ { "format": "vc+sd-jwt", - "id": "eudiw.pid.it", "cryptographic_binding_methods_supported": ["jwk"], + "cryptographic_suites_supported": ["ES256", "ES512"], + + "credential_signing_alg_values_supported": ["ES256", "ES384", "ES512"], + "proof_types_supported": { + "jwt": { + "proof_signing_alg_values_supported": [ + "ES256" + ] + } + }, + "display": [{ - "name": "PID Provider Italiano di esempio", + "name": "PID Italiano di esempio", "locale": "it-IT", "logo": { "url": "https://pid-provider example.org/public/logo.svg", - "alt_text": "logo di questo PID Provider" + "alt_text": "logo di questa Credenziale" }, "background_color": "#12107c", "text_color": "#FFFFFF" }, { - "name": "Example Italian PID Provider", + "name": "Example Italian PID", "locale": "en-US", "logo": { "url": "https://pid-provider.example.org/public/logo.svg", - "alt_text": "The logo of this PID Provider" + "alt_text": "The logo of this credential" }, "background_color": "#12107c", "text_color": "#FFFFFF" @@ -1047,11 +1102,11 @@ Below is a non-normative example of an Entity Configuration containing an `openi } } } - ] + } }, "federation_entity": { - "organization_name": "Pid Provider Organization Example", + "organization_name": "PID Provider Organization Example", "homepage_uri": "https://pid-provider.example.org", "policy_uri": "https://pid-provider.example.org/privacy_policy", "tos_uri": "https://pid-provider.example.org/info_policy", diff --git a/docs/en/proximity-flow.rst b/docs/en/proximity-flow.rst new file mode 100644 index 000000000..4b2246754 --- /dev/null +++ b/docs/en/proximity-flow.rst @@ -0,0 +1,412 @@ + + +.. _proximity_flow_sec: + +Proximity Flow +============== + +This section describes how a Verifier requests the presentation of an *mDoc-CBOR* Credential to a Wallet Instance according to the *ISO 18013-5 Specification*. Only *Supervised Device Retrieval flow* is supported in this technical implementation profile. + +The presentation phase is divided into three sub-phases: + + 1. **Device Engagement**: This subphase begins when the User is prompted to disclose certain attributes from the mDoc(s). The objective of this subphase is to establish a secure communication channel between the Wallet Instance and the Verifier App, so that the mDoc requests and responses can be exchanged during the communication subphase. + The messages exchanged in this subphase are transmitted through short-range technologies to limit the possibility of interception and eavesdropping. + This technical implementation profile exclusively supports QR code for Device Engagement. + + 2. **Session establishment**: During the session establishment phase, the Verifier App sets up a secure connection. All data transmitted over this connection is encrypted using a session key, which is known to both the Wallet Instance and the Verifier at this stage. + The established session MAY be terminated based on the conditions as detailed in [ISO18013-5#9.1.1.4]. + + 3. **Communication - Device Retrieval**: The Verifier App encrypts the mDoc request with the appropriate session key and sends it to the Wallet Instance together with its public key in a session establishment message. The mDoc uses the data from the session establishment message to derive the session key and decrypt the mDoc request. + During the communication subphase, the Verifier App has the option to request information from the Wallet using mDoc requests and responses. The primary mode of communication is the secure channel established during the session setup. The Wallet Instance encrypts the mDoc response using the session key and transmits it to the Verifier App via a session data message. This technical implementation profile only supports Bluetooth Low Energy (BLE) for the communication sub-phase. + + +The following figure illustrates the flow diagram compliant with ISO 18013-5 for proximity flow. + +.. _fig_High-Level-Flow-ITWallet-Presentation-ISO: +.. figure:: ../../images/High-Level-Flow-ITWallet-Presentation-ISO.svg + :figwidth: 100% + :align: center + :target: https://www.plantuml.com/plantuml/svg/bL9BZnCn3BxFhx3A0H3q3_ImMlOXXBJYqGguzE9ct2RQn0bvJDb_ZoSP3QFI2xab_Xx-xDocZ34NPpiisNDn1ufT1t9GPH_XUw88cA3KjuF_3QlnwNM2dHDYq9vf1Q-Up4ddErkeme9KZ381ESFg9rfB6JwnEB4IiAYTAuou7nN_Al-WQ8xcVzHd2dm8eKeFI-cMfApNDpVd3Nm9n90rmKLBa3s4I8b441dSWrTm7wcNkq7RD3xxJE07CIhlXmqyq624-CWdF94RYQaSWiP4iAweRzjr1vLvRkOVYIcYY32TWO8c9rSBp_GYWKoSe88LzPtsvx5HKO5xtnCSVVpNibA6ATjE8IyfKr7aBgptVDry0WlPXIBOH2aPpoEcbgzDOJTXIEPui2PfrqROZogki56OfNuvcxkdHv5N9H8eZSnaPLRJwUPU95JTn9P-5J60Tn2AcAZQjJ_MiCljxndUN6texN8Dr-ErSjd0roZrNEUjFDSVaJqaZP6gOMpDK0-61UHglkcJjJL75Cx4NHflAKT30xLGH_41wnLQIDb7FD6C7URSAOZCSfCjxyjSWcHEZBb4slCuTQL9FJVsWDRq9akuxfQuByx-0G00 + + High-Level Proximity Flow + +**Step 1-3**: The Verifier requests the User to reveal certain attributes from their mDoc(s) stored in the Wallet Instance. The User initiates the Wallet Instance. The Wallet Instance MUST create a new temporary key pair (EDeviceKey.Priv, EDeviceKey.Pub), and incorporate the cipher suite identifier, the identifier of the elliptic curve for key agreement, and the EDeviceKey public point into the device engagement structure (refer to [ISO18013-5#9.1.1.4]). This key pair is temporary and MUST be invalidated immediately after the secure channel is established. Finally, the Wallet Instance displays the QR Code for Device Engagement. + +Below an example of a device engagement structure that utilizes QR for device engagement and Bluetooth Low Energy (BLE) for data retrieval. + +CBOR data: + +.. code-block:: + + a30063312e30018201d818584ba4010220012158205a88d182bce5f42efa59943f33359d2e8a968ff289d93e5fa444b624343167fe225820b16e8cf858ddc7690407ba61d4c338237a8cfcf3de6aa672fc60a557aa32fc670281830201a300f401f50b5045efef742b2c4837a9a3b0e1d05a6917 + +In diagnostic notation: + +.. code-block:: + + { + 0: "1.0", % Version + + 1: % Security + [ + 1, % defines the cipher suite 1 which contains only EC curves + 24(<< % embedded CBOR data item + { + 1: 2, % kty:EC2 (Elliptic curves with x and y coordinate pairs) + -1: 1, % crv:p256 + -2:h'5A88D182BCE5F42EFA59943F33359D2E8A968FF289D93E5FA444B624343 167FE',% x-coordinate + -3:h'B16E8CF858DDC7690407BA61D4C338237A8CFCF3DE6AA672FC60A557AA32FC67' % y-coordinate + } + >>) + ], + + 2: %DeviceRetrievalMethods(Device engagement using QR code) + [ + [ + 2, %BLE + 1, % Version + { %BLE options + 0: false, % no support for mdoc peripheral server mode + 1: true, % support mdoc central client mode + 11: h'45EFEF742B2C4837A9A3B0E1D05A6917' % UUID of mdoc client central mode + } + ] + ] + } + + + +**Step 4-6**: The Verifier App scans the QR Code and generates its own ephemeral key pair (EReaderKey.Priv, EReaderKey.Pub). It then calculates the session key, using the public key received in the Engagement Structure and its newly-generated private key, as outlined in [ISO18013-5#9.1.1.5]. Finally, it generates its session key, which must be independently derived by both the Wallet Instance and the Verifier App. + +**Step 7**: The Verifier App creates an mDoc request that MUST be encrypted using the relevant session key, and transmits it to the Wallet Instance along with EReaderKey.Pub within a session establishment message. The mDoc request MUST be encoded in CBOR, as demonstrated in the following non-normative example. + +CBOR data: +.. code-block:: + + a26776657273696f6e63312e306b646f63526571756573747381a26c6974656d7352657175657374d818590152a267646f6354797065756f72672e69736f2e31383031332e352e312e6d444c6a6e616d65537061636573a2746f72672e69736f2e31383031332e352e312e4954a375766572696669636174696f6e2e65766964656e6365f4781c766572696669636174696f6e2e6173737572616e63655f6c6576656cf4781c766572696669636174696f6e2e74727573745f6672616d65776f726bf4716f72672e69736f2e31383031332e352e31ab76756e5f64697374696e6775697368696e675f7369676ef47264726976696e675f70726976696c65676573f46f646f63756d656e745f6e756d626572f46a69737375655f64617465f46f69737375696e675f636f756e747279f47169737375696e675f617574686f72697479f46a62697274685f64617465f46b6578706972795f64617465f46a676976656e5f6e616d65f468706f727472616974f46b66616d696c795f6e616d65f46a726561646572417574688443a10126a11821590129308201253081cda00302010202012a300a06082a8648ce3d0403023020311e301c06035504030c15536f6d652052656164657220417574686f72697479301e170d3233313132343130323832325a170d3238313132323130323832325a301a3118301606035504030c0f536f6d6520526561646572204b65793059301306072a8648ce3d020106082a8648ce3d03010703420004aa1092fb59e26ddd182cfdbc85f1aa8217a4f0fae6a6a5536b57c5ef7be2fb6d0dfd319839e6c24d087cd26499ec4f87c8c766200ba4c6218c74de50cd1243b1300a06082a8648ce3d0403020347003044022048466e92226e042add073b8cdc43df5a19401e1d95ab226e142947e435af9db30220043af7a8e7d31646a424e02ea0c853ec9c293791f930bf589bee557370a4c97bf6584058a0d421a7e53b7db0412a196fea50ca6d4c8a530a47dd84d88588ab145374bd0ab2a724cf2ed2facf32c7184591c5969efd53f5aba63194105440bc1904e1b9 + +The above CBOR data is represented in diagnostic notation as follows: +.. code-block:: + + { + "version": "1.0", + "docRequests": [ + { + "itemsRequest": 24(<< { + "docType": "org.iso.18013.5.1.mDL", + "nameSpaces": { + "org.iso.18013.5.1.IT": { + "verification.evidence": false, + "verification.assurance_level": false, + "verification.trust_framework": false + }, + "org.iso.18013.5.1": { + "un_distinguishing_sign": false, + "driving_privileges": false, + "document_number": false, + "issue_date": false, + "issuing_country": false, + "issuing_authority": false, + "birth_date": false, + "expiry_date": false, + "given_name": false, + "portrait": false, + "family_name": false + } + } + } >>), + "readerAuth": [ + h'a10126', + { + 33: h'308201253081cda00302010202012a300a06082a8648ce3d0403023020311e301c06035504030c15536f6d652052656164657220417574686f72697479301e170d3233313132343130323832325a170d3238313132323130323832325a301a3118301606035504030c0f536f6d6520526561646572204b65793059301306072a8648ce3d020106082a8648ce3d03010703420004aa1092fb59e26ddd182cfdbc85f1aa8217a4f0fae6a6a5536b57c5ef7be2fb6d0dfd319839e6c24d087cd26499ec4f87c8c766200ba4c6218c74de50cd1243b1300a06082a8648ce3d0403020347003044022048466e92226e042add073b8cdc43df5a19401e1d95ab226e142947e435af9db30220043af7a8e7d31646a424e02ea0c853ec9c293791f930bf589bee557370a4c97b' + }, + null, + h'58a0d421a7e53b7db0412a196fea50ca6d4c8a530a47dd84d88588ab145374bd0ab2a724cf2ed2facf32c7184591c5969efd53f5aba63194105440bc1904e1b9' + ] + } + ] + } + +**Step 8**: The Wallet Instance uses the session establishment message to derive the session keys and decrypt the mDoc request. It computes the session key using the public key received from the Verifier App and its private key. + +**Step 9-10**: When the Wallet Instance receives the mDoc request, it locates the documents that contain the requested attributes and asks the User for permission to provide this information to the Verifier. If the User agrees, the Wallet generates an mDoc response and transmits it to the Verifier App through the secure channel. + +**Step 11-12**: If the User gives consent, the Wallet Instance creates an mDoc response and transmits it to the Verifier App via the secure channel. The mDoc response MUST be encoded in CBOR, with its structure outlined in [ISO18013-5#8.3.2.1.2.2]. Below is a non-normative example of an mDoc response. + +CBOR Data: +.. code-block:: + + a36776657273696f6e63312e3069646f63756d656e747381a367646f6354797065756f72672e69736f2e31383031332e352e312e6d444c6c6973737565725369676e6564a26a6e616d65537061636573a2746f72672e69736f2e31383031332e352e312e495483d81858f7a46864696765737449440b6672616e646f6d506d44f21ee875f2c1d502b43198e5a15271656c656d656e744964656e74696669657275766572696669636174696f6e2e65766964656e63656c656c656d656e7456616c756581a2647479706571656c656374726f6e69635f7265636f7264667265636f7264bf6474797065781f68747470733a2f2f657564692e77616c6c65742e70646e642e676f762e697466736f75726365bf716f7267616e697a6174696f6e5f6e616d65754d6f746f72697a7a617a696f6e6520436976696c656f6f7267616e697a6174696f6e5f6964656d5f696e666c636f756e7472795f636f6465626974ffffd8185866a4686469676573744944046672616e646f6d50185d84dfb71ce9b173010ddd62174fbe71656c656d656e744964656e746966696572781c766572696669636174696f6e2e74727573745f6672616d65776f726b6c656c656d656e7456616c7565656569646173d8185865a4686469676573744944006672616e646f6d50137f903174253c4585358267aae2ea4e71656c656d656e744964656e746966696572781c766572696669636174696f6e2e6173737572616e63655f6c6576656c6c656c656d656e7456616c75656468696768716f72672e69736f2e31383031332e352e318bd8185852a46864696765737449440c6672616e646f6d5053e29d0ddbbc7d2306a32bdbe2e56e5171656c656d656e744964656e7469666965726b66616d696c795f6e616d656c656c656d656e7456616c756563446f65d8185855a4686469676573744944036672616e646f6d50990cba2069fa1b33b8d6ae910b6549dc71656c656d656e744964656e7469666965726a676976656e5f6e616d656c656c656d656e7456616c756567416e746f6e696fd818585ba46864696765737449440a6672616e646f6d504086c1379975f805f1b1f4975e6a126571656c656d656e744964656e7469666965726a69737375655f646174656c656c656d656e7456616c7565d903ec6a323031392d31302d3230d818585ca4686469676573744944016672616e646f6d50ab4ca30c918dd2fd0bf35242c15fa2d871656c656d656e744964656e7469666965726b6578706972795f646174656c656c656d656e7456616c7565d903ec6a323032342d31302d3230d8185855a4686469676573744944076672616e646f6d508d9066f6c8da16619867cd4e2fab0c8871656c656d656e744964656e7469666965726f69737375696e675f636f756e7472796c656c656d656e7456616c7565624954d818587ea4686469676573744944056672616e646f6d5059fe68db795dee4c20976380ea24770571656c656d656e744964656e7469666965727169737375696e675f617574686f726974796c656c656d656e7456616c75657828497374697475746f20506f6c696772616669636f2065205a656363612064656c6c6f20537461746fd818585ba4686469676573744944026672616e646f6d5008b3f1ca5517019767be3dee3bb0614571656c656d656e744964656e7469666965726a62697274685f646174656c656c656d656e7456616c7565d903ec6a313935362d30312d3230d818585ca4686469676573744944096672616e646f6d50a2395ec214350c26066306e23279b3ae71656c656d656e744964656e7469666965726f646f63756d656e745f6e756d6265726c656c656d656e7456616c756569393837363534333231d8185850a4686469676573744944066672616e646f6d50a25e1a5b915d2d6eafee9674e023293971656c656d656e744964656e74696669657268706f7274726169746c656c656d656e7456616c75654420212223d81858eea46864696765737449440d6672616e646f6d50eeed6a3b856563627589a360939d12f771656c656d656e744964656e7469666965727264726976696e675f70726976696c656765736c656c656d656e7456616c756582a37576656869636c655f63617465676f72795f636f646561416a69737375655f64617465d903ec6a323031382d30382d30396b6578706972795f64617465d903ec6a323032342d31302d3230a37576656869636c655f63617465676f72795f636f646561426a69737375655f64617465d903ec6a323031372d30322d32336b6578706972795f64617465d903ec6a323032342d31302d3230d818585ba4686469676573744944086672616e646f6d50c0ef486b2a194ed3cbf7f354fd40092171656c656d656e744964656e74696669657276756e5f64697374696e6775697368696e675f7369676e6c656c656d656e7456616c756561496a697373756572417574688443a10126a118215901423082013e3081e5a00302010202012a300a06082a8648ce3d040302301a3118301606035504030c0f5374617465204f662055746f706961301e170d3233313132343134353430345a170d3238313132323134353430345a30383136303406035504030c2d5374617465204f662055746f7069612049737375696e6720417574686f72697479205369676e696e67204b65793059301306072a8648ce3d020106082a8648ce3d03010703420004c338ec1000b351ce8bcdfc167450aeceb + +In diagnostic notation: +.. code-block:: + + { + "version": "1.0", + "documents": [ + { + "docType": "org.iso.18013.5.1.mDL", + "issuerSigned": { + "nameSpaces": { + "org.iso.18013.5.1.IT": [ + 24(<< { + "digestID": 11, + "random": h'6d44f21ee875f2c1d502b43198e5a152', + "elementIdentifier": "verification.evidence", + "elementValue": [ + { + "type": "electronic_record", + "record": { + "type": "https://eudi.wallet.pdnd.gov.it", + "source": { + "organization_name": "Motorizzazione Civile", + "organization_id": "m_inf", + "country_code": "it" + } + } + } + ] + } >>), + 24(<< { + "digestID": 4, + "random": h'185d84dfb71ce9b173010ddd62174fbe', + "elementIdentifier": "verification.trust_framework", + "elementValue": "eidas" + } >>), + 24(<< { + "digestID": 0, + "random": h'137f903174253c4585358267aae2ea4e', + "elementIdentifier": "verification.assurance_level", + "elementValue": "high" + } >>) + ], + "org.iso.18013.5.1": [ + 24(<< { + "digestID": 12, + "random": h'53e29d0ddbbc7d2306a32bdbe2e56e51', + "elementIdentifier": "family_name", + "elementValue": "Doe" + } >>), + 24(<< { + "digestID": 3, + "random": h'990cba2069fa1b33b8d6ae910b6549dc', + "elementIdentifier": "given_name", + "elementValue": "Antonio" + } >>), + 24(<< { + "digestID": 10, + "random": h'4086c1379975f805f1b1f4975e6a1265', + "elementIdentifier": "issue_date", + "elementValue": 1004("2019-10-20") + } >>), + 24(<< { + "digestID": 1, + "random": h'ab4ca30c918dd2fd0bf35242c15fa2d8', + "elementIdentifier": "expiry_date", + "elementValue": 1004("2024-10-20") + } >>), + 24(<< { + "digestID": 7, + "random": h'8d9066f6c8da16619867cd4e2fab0c88', + "elementIdentifier": "issuing_country", + "elementValue": "IT" + } >>), + 24(<< { + "digestID": 5, + "random": h'59fe68db795dee4c20976380ea247705', + "elementIdentifier": "issuing_authority", + "elementValue": "Istituto Poligrafico e Zecca dello Stato" + } >>), + 24(<< { + "digestID": 2, + "random": h'08b3f1ca5517019767be3dee3bb06145', + "elementIdentifier": "birth_date", + "elementValue": 1004("1956-01-20") + } >>), + 24(<< { + "digestID": 9, + "random": h'a2395ec214350c26066306e23279b3ae', + "elementIdentifier": "document_number", + "elementValue": "987654321" + } >>), + 24(<< { + "digestID": 6, + "random": h'a25e1a5b915d2d6eafee9674e0232939', + "elementIdentifier": "portrait", + "elementValue": h'20212223' + } >>), + 24(<< { + "digestID": 13, + "random": h'eeed6a3b856563627589a360939d12f7', + "elementIdentifier": "driving_privileges", + "elementValue": [ + { + "vehicle_category_code": "A", + "issue_date": 1004("2018-08-09"), + "expiry_date": 1004("2024-10-20") + }, + { + "vehicle_category_code": "B", + "issue_date": 1004("2017-02-23"), + "expiry_date": 1004("2024-10-20") + } + ] + } >>), + 24(<< { + "digestID": 8, + "random": h'c0ef486b2a194ed3cbf7f354fd400921', + "elementIdentifier": "un_distinguishing_sign", + "elementValue": "I" + } >>) + ] + }, + "issuerAuth": [ + h'a10126', + { + 33: h'3082013e3081e5a00302010202012a300a06082a8648ce3d040302301a3118301606035504030c0f5374617465204f662055746f706961301e170d3233313132343134353430345a170d3238313132323134353430345a30383136303406035504030c2d5374617465204f662055746f7069612049737375696e6720417574686f72697479205369676e696e67204b65793059301306072a8648ce3d020106082a8648ce3d03010703420004c338ec1000b351ce8bcdfc167450aeceb7d518bd9a519583e082d67effff06565804fc09abf0e4a08e699c9dba3796285a15f68e40ac7f9fc7700a15153a4065300a06082a8648ce3d040302034800304502210099b7d62e6bf7b1823db3713df889bf73e70bb4d9c58c21e92c58d2f1beffe932022058d039747a00d70e6d66be4797e6142b3608a014ee09b7b79af2cae2aaf27788' + }, + 24(<< { + "version": "1.0", + "digestAlgorithm": "SHA-256", + "docType": "org.iso.18013.5.1.mDL", + "valueDigests": { + "org.iso.18013.5.1": { + 1: h'0E5F0B6B33418E508740771E82F893372EAF5B2445BC4C84DCF08B005E9493FC', + 2: h'DE21BB62FF2897D8B986D2CDA9F9BC5865C02807F7B4D9DD1FA4A79DF4C0D37F', + 3: h'BC5568239E35CE9FF8798C27FFDCD757B134B679F0FE05729AA3491381912E65', + 5: h'E6048BDC7FD6454296F1E3F54536107C9C5B24C4064DE46A98121E3630EECCA2', + 6: h'73690D92DCAA61B0203870F67C6AA9FDFEA889B6F0C720DE757B4B0A8516A206', + 7: h'E353EA0B0FD92B6BE90C64CC3B2EE1284153A8F0F5066B99AAC599200E6EEEB2', + 8: h'29227872CEB49923D267B5F4BADE6D387B42AC2DC4B2AE26C9013067FEE7018A', + 9: h'A6A119F7CACAC0B8C6AACAC747FD3FE7E50B6D9BB8A507FDA79F0DF6646F285D', + 10: h'6D8025D2F02A5E7E1406FB6AAEB67F9EDE9B07191A53F3E23B77C528223A94E2', + 12: h'B0D43E4E2EA534E4D5304E64BCF7A0F13E2C8EE8304B9CD23ABA4909652A4647', + 13: h'FBF4DE318982F2DBAD43C601CAEB22628B301AC18AA8264C5831B2AAAC89C486' + }, + "org.iso.18013.5.1.IT": { + 0: h'CF57377B675F64F37314739592C1E8A911A7DDAF341CE2902FE877C5A835E4C1', + 4: h'4A4B4CC64EC9299C1A2501EA449F577005E9F7A60408057C07A7C67FB151E5F5', + 11: h'78824FBD6FBBA88A2AAB44DF8B6F5E9759126D87D1F4415995E658FD9239E1FE' + } + }, + "deviceKeyInfo": { + "deviceKey": { + 1: 2, + -1: 1, + -2: h'AFD09E720B918CEDC2B8A881950BAB6A1051E18AE16A814D51E609938663D5E1', + -3: h'61FBC6C8AD24EC86A78BB4E9AC377DD2B7C711D9F2EB9AFD4AA0963662847AED'}}, + "validityInfo": { + "signed": 0("2023-11-24T14:54:05Z"), + "validFrom": 0("2023-11-24T14:54:05Z"), + "validUntil": 0("2024-11-24T14:54:05Z")} + } >>), + h'f2461e4fab69e9f7bcffe552395424514524d1679440036213173101448d1b1ab4a293859b389ffa8b47aeed10e9b0c1545412ac37c51a76482cd9bbbe110152' + ] + }, + "deviceSigned": { + "nameSpaces": 24(<< {} >>), + "deviceAuth": { + "deviceSignature": [ + h'a10126', + {}, + null, + h'1fed7190d2975ab79c072e6f1d9d52436059d1fc959d55baf74f057d89b10fcc0dc77a50d433d4c76ddf26223c5560c4ab123b5cb5eb805a90036aa147493076' + ] + } + } + } + ], + "status": 0 + } + +**Step 13**: The Verifier App is required to validate the signatures in the mDoc's issuerSigned field using the public key of the Credential Issuer specified within the mDoc. Subsequently, the Verifier MUST validate the signature in the deviceSigned field. If these signature checks pass, the Verifier can confidently consider the received information as valid. + +Device Engagement +----------------- + +The Device Engagement structure MUST be have at least the following components: + + - **Version**: *tstr*. Version of the data structure being used. + - **Security**: an array that contains two mandatory values + + - the cipher identifier: see Table 22 of [ISO18013-5] + - the mDL public ephemeral key generated by the Wallet Instance and required by the Verifier App to derive the Session Key. The mDL public ephemeral key MUST be of a type allowed by the indicated cipher suite. + - **transferMethod**: an array that contains one or more transferMethod arrays when performing device engagement using the QR code. This array is for offline data retrieval methods. A transferMethod array holds two mandatory values (type and version). Only the BLE option is supported by this technical implementation profile, then the type value MUST be set to ``2``. + - **BleOptions**: this elements MUST provide options for the BLE connection (support for Peripheral Server or Central Client Mode, and the device UUID). + + +mDoc Request +------------ + +The messages in the mDoc Request MUST be encoded using CBOR. The resulting CBOR byte string for the mDoc Request MUST be encrypted with the Session Key obtained after the Device Engagement phase and MUST be transmitted using the BLE protocol. +The details on the structure of mDoc Request, including identifier and format of the data elements, are provided below. + + - **version**: (tstr). Version of the data structure. + - **docRequests**: Requested DocType, NameSpace and data elements. + + - **itemsRequest**: #6.24(bstr .cbor ItemsRequest). + + - **docType**: (tstr). The DocType element contains the type of document requested. See :ref:`Data Model Section `. + - **nameSpaces**: (tstr). See :ref:`Data Model Section ` for more details. + + - **dataElements**: (tstr). Requested data elements with *Intent to Retain* value for each requested element. + + - **IntentToRetain**: (bool). It indicates that the Verifier App intends to retain the received data element. + - **readerAuth**: *COSE_Sign1*. It is required for the Verifier App authentication. + +.. note:: + + The domestic data elements MUST not be returned unless specifically requested by the Verifier App. + +mDoc Response +------------- + +The messages in the mDoc Response MUST be encoded using CBOR and MUST be encrypted with the Session Key obtained after the Device Engagement phase. +The details on the structure of mDoc Response are provided below. + + - **version**: (tstr). Version of the data structure. + - **documents**: Returned *DocType*, and *ResponseData*. + + - **docType**: (tstr). The DocType element contains the type of document returned. See :ref:`Data Model Section `. + - **ResponseData**: + + - **IssuerSigned**: Responded data elements signed by the issuer. + + - **nameSpaces**: (tstr). See :ref:`Data Model Section ` for more details. + + - **IssuerSignedItemBytes**: #6.24(bstr .cbor). + + - **digestID**: (uint). Reference value to one of the **ValueDigests** provided in the *Mobile Security Object* (`issuerAuth`). + - **random**: (bstr). Random byte value used as salt for the hash function. This value SHALL be different for each *IssuerSignedItem* and it SHALL have a minimum length of 16 bytes. + - **elementIdentifier**: (tstr). Identifier of User attribute name contained in the Credential. + - **elementValue**: (any). User attribute value + - **DeviceSigned**: Responded data elements signed by the Wallet Instance. + + - **NameSpaces**: #6.24(bstr .cbor DeviceNameSpaces). The DeviceNameSpaces structure MAY be an empty structure. DeviceNameSpaces contains the data element identifiers and values. It is returned as part of the corresponding namespace in DeviceNameSpace. + + - **DataItemName**: (tstr). The identifier of the element. + - **DataItemValue**: (any). The value of the element. + - **DeviceAuth**: The DeviceAuth structure MUST contain the DeviceSignature elements. + + - **DeviceSignature**: It MUST contain the device signature for the Wallet Instance authentication. + - **status**: It contains a status code. For detailed description and action required refer to to Table 8 (ResponseStatus) of the [ISO18013-5] + + +Session Termination +------------------- + +The session MUST be terminated if at least one of the following conditions occur. + + - After a time-out of no activity of receiving or sending session establishment or session data messages occurs. The time-out for no activity implemented by the Wallet Instance and the Verifier App SHOULD be no less than 300 seconds. + - When the Wallet Instance doesn't accept any more requests. + - When the Verifier App does not send any further requests. + +If the Wallet Instance and the Verifier App does not send or receive any further requests, the session termination MUST be initiated as follows. + + - Send the status code for session termination, or + - dispatch the "End" command as outlined in [ISO18013-5#8.3.3.1.1.5]. + +When a session is terminated, the Wallet Instance and the Verifier App MUST perform at least the following actions: + + - destruction of session keys and related ephemeral key material; + - closure of the communication channel used for data retrieval. diff --git a/docs/en/relying-party-solution.rst b/docs/en/relying-party-solution.rst index 31e4900fb..82cfe274e 100644 --- a/docs/en/relying-party-solution.rst +++ b/docs/en/relying-party-solution.rst @@ -1,18 +1,17 @@ -.. 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. @@ -737,18 +736,11 @@ 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). - * - **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:: remote-flow.rst +.. include:: proximity-flow.rst -.. note: - The Relying Party specific metadata parameter are experimental - and still under discussion `here `_. diff --git a/docs/en/remote-flow.rst b/docs/en/remote-flow.rst new file mode 100644 index 000000000..0cd04af47 --- /dev/null +++ b/docs/en/remote-flow.rst @@ -0,0 +1,731 @@ +.. include:: ../common/common_definitions.rst +.. _Wallet Attestation: wallet-attestation.html +.. _Trust Model: trust.html + +.. _remote_flow_sec: + +Remote 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 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; +* **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. + +A High-Level description of the remote flow, from the User's perspective, is given below: + + 1. the Wallet Instance scans the QR Code and obtains the URL (Cross Device flow) or obtain directly an URL (Same Device flow); + 2. the Wallet Instance extracts from the payload the ``client_id`` and the `request_uri` parameters; + 3. the Wallet Instance establishes the Trust to the Relying Party by building the Federation Trust Chain. Implementations may evaluate the trust after having obtained the signed Request Object (see point 5); + 4. the Wallet fetches the signed Request Object using an HTTP request with method GET to the endpoint provided in the ``request_uri`` parameter; + 5. the Wallet verifies the signature of the signed Request Object and that its issuer matches the ``client_id`` obtained at the step number 2; + 6. the Wallet checks the presence in the signed Request Object of the parameter `request_uri_method`, if this parameter is present and set with the ``post`` valueThe Wallet transmits its metadata to the request_uri endpoint of the Relying Party using an HTTP POST method and obtains an updated signed Request Object; + 7. The Wallet Instance evaluates the requested PID/EAAs and checks the elegibility of the Relying Party in asking these by applying the policies related to that specific Relying Party; + 8. the Wallet Instance asks User disclosure and consent; + 9. the Wallet Instance presents the requested disclosure of PID/EAAs to the Relying Party, which validates the Wallet Attestation and checks that the Wallet Provider is trusted; + 10. the Wallet Instance informs the User about the successfull authentication with the Relying Party and give a good user experience to let the User continuing its navigation. + +Below a sequence diagram that summarizes the interactions between all the involved parties. + +.. figure:: ../../images/cross_device_auth_seq_diagram.svg + :align: center + :target: https://www.plantuml.com/plantuml/svg/XLNTRkCs4xtdKnpuk_YI84cpspi3AJQRfflijergUpSt1W9Q6jjiQ5BbZvoqwBjtA5goN2GeO1WGEMVcdFaPVl11kX0tMiWOh8cR1JaXn5KPhCFegoStWlI8GYpiSpxulyUFrAYI_0Z_-rcjrk6ZZYHgzgDALKiJC7gGMbF0dM7tfgJMn_RG9BAhCxaY4t84ASXKu2Y7PXFIBygiKF3XIslPa10HPpymP8m7Mc1ABj61aOrQoQ2i4L4cWuR6cD0VaNn0uMoWCb359zv6LxANoqiaGRYAOKs6OxPW71MEF7_dhs8jFHtZybB8CgX61aeC6ke2N3jAPn8d9vuXT7A2Hkf8SxEmaHK5YxrKbDO-gLVWBjDyZ4x1TGGRwcJ-Dhcs5U5-WjlPh609bNAi1aVVNxm_nbQ5DKgjEC2Zgaw7paxHaX8L3TcBlPQj42jdOyr4hEyg2slqoow9SOpfscx1AUferAmbbO1ljsFSrsJQstyL7RAkJw5jAJNaGOR55XawBQLXfqXU-yERv-2OtjpqYkPce6XkfAcoghbPEhj9iNidP2hHUw9K2BRp22xwaFEKh7lFsPJhqENCj_TUhGnLtHdiulUKx3xOi5WSiBRAXBPOEUohQ4wv3b3B8VXnGs5jAoWFJpjwnVrq9WG0zDHgPnjLaUyIp2XPoI0HxDjqaeU-omQP61GgK6bKgaufQxbGMWL5lWTcBR7cI5IzfUcDT1yCBNxf-AR2rLQhakFqg6_arFAb3I13T0Ix7DIWdz_x7B57IQqIi-wUBRyLH_uu6yJzt2-jGsbDckTzqyTzzrvRirHkGzLmH6BV5sqzsWLXdVepRuG9-JfvnDpacZNrOx1FPDxO43Uxl2HPMQwI2qquM3FPGG_g1GuBTXK2-Mn_pi7pvz2Wo9tYc9ZoI7kqo-PFnCSjak-u3gyEB6EC3N3KC9dgVC0cXqhBgafZB3Nkl8_aC4k3bLtkANz-c67QrNFWXUcLv7qUmTwL48wZ4cn3ZituJRdxT3lxDBcv-LMyZXWBNA-fVCAjrImBN-W57vMfkELQ8enYsVmhhFSCPzKCEKFqRD7wgkD2gn9F3CnRMgMyyCrGOh1eskRCXIjoZSw5m6nDfjjJxMMbVAcjfmeo1ASMCP0VSuaoppJsdEf-M1N7G9u8Hv2DL3erH9gcDXLYaBElTTS5-QtQwS5HVacw0Jt6O06bD-AxT-VlyFxY0lTVcCPV8vUVZ7PBZCPOXr1xHATp1xjTIp-MjYByFPo5xU7RqJqNKxcXWzSY3vvanZxJ7KPCqlxheMceV-S-JyUxp1q-77djuoW9x7PH5f2pSPoJa7bSlGPTgOPCXhHEabv_YiXsMeEUwxOsri77CdNUCkgM-mV-Ynlz3m00 + + Remote Protocol Flow + +The details of each step shown in the previous picture are described in the table below. + + +.. list-table:: + :widths: 10 50 + :header-rows: 1 + + * - **Id** + - **Description** + * - **1**, **2** + - The User requests to access to a protected resource, the Relying Party redirects the User to a discovery page in which the User selects the *Login with the Wallet* button. The Authorization flow starts. + * - **3**, **4**, + - The Relying Party provides the Wallet Instance with a URL where a generic signed Request Object can be downloaded. + * - **5**, **6**, **7**, **8**, **9** + - In the **Cross Device Flow**: the Request URI is provided in the form of a QR Code that is shown to the User. The User frames the QRCode with the Wallet Instance and extracts ``client_id``, ``request_uri`` and ``state``. In the **Same Device Flow** the Relying Party provides the same information of the Cross-Device flow but in the form of HTTP Redirect Location (302). + * - **10**, **11**, **12** + - The Wallet Instance obtains the signed Request Object. + * - **13**, **14** and **15** + - The Wallet Instance checks if the Relying Party has provided the ``request_uri_method`` within its signed Request Object. If true, the Wallet provides its metadata in the to the Relying Party. The Relying PArty produces a new signed Request Object compliant to the Wallet technical capabilities. + * - **13**, **14**, **15**, **16**, **17**, **18** + - The Request Object JWS is verified by the Wallet Instance. The Wallet processes the Relying Party metadata and applies the policies related to the Relying Party, attesting whose Digital Credentials and User data the Relying Party is granted to request. + * - **19**, **20** + - The Wallet Instance requests the User's consent for the release of the Credentials. The User authorizes and consents the presentation of the Credentials by selecting/deselecting the personal data to release. + * - **21** + - The Wallet Instance provides the Authorization Response to the Relying Party using an HTTP request with the method POST (response mode "direct_post"). + * - **22**, **23**, **24**, **25** and **26** + - The Relying Party verifies the Authorization Response, extracts the Wallet Attestation to establish the trust with the Wallet Solution. The Relying Party extracts the Digital Credentials and attests the trust to the Credentials Issuer and the proof of possession of the Wallet Instance about the presented Digital Credentials. Finally, the Relying Party verifies the revocation status of the presented Digital Credentials. + * - **27** and **28** + - The Relying Party provides to the Wallet a redirect URI with a response code to be used by the Wallet to finalize the authentication. + * - **29** + - The User is informed by the Wallet Instance that the Autentication succeded, then the protected resource is made available to the User. + + +Request URI with HTTP POST +-------------------------- + +The Relying Party SHOULD provide the POST method with its ``request_uri`` endpoint +allowing the Wallet Instance to inform the Relying Party about its technical capabilities. + +This feature can be useful when, for example, the Wallet Instance supports +a restricted set of features, supported algorithms or a specific url for +its ``authorization_endpoint``, and any other information that it deems necessary to +provide to the Relying Party the parameters necessary for better interoperability. + +.. warning:: + The Wallet Instance, when providing its technical capabilities to the + Relying Party, MUST NOT include any User information or other explicit + information regarding the hardware used or usage preferences of its User. + +If both the Relying Party and the Wallet Instance +supports the ``request_uri_method`` with HTTP POST, +the Wallet Instance capabilities MUST +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`. + +A non-normative example of the HTTP request is represented below: + +.. code:: http + + POST /request-uri HTTP/1.1 + HOST: relying-party.example.org + Content-Type: application/json + + { + "authorization_endpoint": "https://wallet-solution.digital-strategy.europa.eu/authorization", + "response_types_supported": [ + "vp_token" + ], + "response_modes_supported": [ + "form_post.jwt" + ], + "vp_formats_supported": { + "vc+sd-jwt": { + "sd-jwt_alg_values": [ + "ES256", + "ES384" + ] + } + }, + "request_object_signing_alg_values_supported": [ + "ES256" + ], + "presentation_definition_uri_supported": false, + } + +The response of the Relying Party is defined in the section below. + + +Authorization Request Details +----------------------------- + +The Relying Party MUST create a Request Object in the form of a signed JWT and +it MUST provide it to the Wallet Instance through an HTTP URL (request URI). +The HTTP URL points to the web resource where the signed request object is +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 HTTPs URL where the Relying Party provides the signed Request Object to the Wallet Instance. + + + +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=... + +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. + + +In the **Same Device Flow** the Relying Party uses an HTTP response redirect (with status code set to 302) as represented in the following non-normative example: + +.. code:: text + + HTTP/1.1 /authorization Found + 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 + + +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. + +Below is represented a non-normative example of a QR Code issued by the Relying Party. + +.. figure:: ../../images/verifier_qr_code.svg + :figwidth: 50% + :align: center + + +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 + +.. 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 **response_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 +---------------------- + +Below a non-normative example of HTTP request made by the Wallet Instance to the Relying Party. + +.. code-block:: javascript + + GET /request_uri HTTP/1.1 + HOST: relying-party.example.org + + +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/response_uri", + "nonce": "2c128e4d-fc91-4cd3-86b8-18bdea0988cb", + "state": "3be39b69-6ac1-41aa-921b-3e6c07ddcb03", + "iss": "https://relying-party.example.org", + "iat": 1672418465, + "exp": 1672422065, + "request_uri_method": "post" + } + +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. + * - **request_uri_method** + - String determining the HTTP method to be used with the `request_uri` endpoint to provide the Wallet metadata to the Relying Party. The value is case-insensitive and can be set to: `get` or `post`. The GET method, as defined in [@RFC9101], involves the Wallet sending a GET request to retrieve a Request Object. The POST method involves the Wallet requesting the creation of a new Request Object by sending an HTTP POST request, with its metadata, to the request URI of the Relying Party. + +.. 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_disclosure": "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``: 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. The ``client_metadata`` parameter MUST NOT be present when ``client_id_scheme`` is ``entity_id``. Since the ``client_metadata`` is taken from ``trust_chain``, this parameter is intended to not be used. + - ``client_metadata_uri``: string containing an HTTPS URL pointing to a resource where a JSON object with the Relying Party metadata can be retrieved. The ``client_metadata_uri`` parameter MUST NOT be present when ``client_id_scheme`` is ``entity_id``. Since the ``client_metadata`` is taken from ``trust_chain``, this parameter is intended to not be used. + + +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 /response_uri 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:: + + { + "state": "3be39b69-6ac1-41aa-921b-3e6c07ddcb03", + "vp_token": [ + "eyJhbGciOiJFUzI1NiIs...PT0iXX0", + $WalletInstanceAttestation-JWT + ], + "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** + - JSON Array containing the Verifiable Presentation(s). There MUST be at least two signed presentations in this Array: + - The Requested Digital Credential (one or more, if in format SD-JWT VC or MDOC CBOR) + - The Wallet Instance Attestation + * - **presentation_submission** + - JSON Object containing the mappings between the requested Verifiable Credentials and where to find them within the returned Verifiable Presentation 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": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c", + "jti": "3978344f-8596-4c3a-a978-8fcaba3903c5", + "aud": "https://relying-party.example.org/response_uri", + "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 key is included in the Digital Credential. Eg: for SD-JWT VC the pblic key is provided within the ``cnf.jwk`` claim. + * - **jti** + - JWS unique identifier. + * - **iat** + - Unix timestamp of the time of issuance of this presentation. + * - **exp** + - Unix timestamp beyond which this presentation will no longer be considered valid. + * - **aud** + - Audience of the VP, corresponding to the ``response_uri`` within the Authorization request issued by the Relying Party. + * - **nonce** + - The nonce value provided by the Relying Party within the Authorization Request. + + +Redirect URI +------------ + +When the Relying Party provides the redirect URI, the Wallet MUST send the user-agent to this redirect URI. The redirect URI allows the Relying Party to continue the interaction with the End-User on the device where the Wallet resides after the Wallet has sent the Authorization Response to the response URI. + +The Relying Party MUST include a response code withing the redirect URI. The response code is a fresh, cryptographically random number used to ensure only the receiver of the redirect can fetch and process the Authorization Response. The number could be added as a path component, as a parameter or as a fragment to the URL. It is RECOMMENDED to use a cryptographic random value of 128 bits or more at the time of the writing of this specification. + +The following is a non-normative example of the response from the Relying Party to the Wallet upon receiving the Authorization Response at the Response Endpoint. + + +.. code-block:: http + + HTTP/1.1 200 OK + Content-Type: application/json;charset=UTF-8 + + { + "redirect_uri": "https://relying-party.example.org/cb#response_code=091535f699ea575c7937fa5f0f454aee" + } + +The ``redirect_uri`` value MUST be used with an HTTP method GET by either the Wallet or the user-agent to redirect the User to the Relying Party in order to complete the authentication process. The specific entity that performs this action depends on whether the flow is Same device or Cross device. + + +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": "RS256", + "kid": "2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", + "typ": "entity-statement+jwt" + } + . + { + "exp": 1649590602, + "iat": 1649417862, + "iss": "https://rp.example.it", + "sub": "https://rp.example.it", + "jwks": { + "keys": [ + { + "kty": "RSA", + "n": "5s4qi ...", + "e": "AQAB", + "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": "RSA", + "use": "sig", + "n": "1Ta-sE ...", + "e": "AQAB", + "kid": "YhNFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", + "x5c": [ "..." ] + } + ] + }, + + "contacts": [ + "ops@relying-party.example.org" + ], + + "request_uris": [ + "https://relying-party.example.org/request_uri" + ], + "response_uris": [ + "https://relying-party.example.org/response_uri" + ], + "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" + ], + "authorization_encrypted_response_alg": [ + "RSA-OAEP", + "RSA-OAEP-256" + ], + "authorization_encrypted_response_enc": [ + "A128CBC-HS256", + "A192CBC-HS384", + "A256CBC-HS512", + "A128GCM", + "A192GCM", + "A256GCM" + ], + + // SIOPv2 related + "subject_type": "pairwise", + "require_auth_time": true, + "id_token_signed_response_alg": [ + "ES256" + ], + "id_token_encrypted_response_alg": [ + "RSA-OAEP", + "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 + + +.. note: + The Relying Party specific metadata parameter are experimental + and still under discussion `here `_. + diff --git a/docs/en/trust.rst b/docs/en/trust.rst index 464c86860..f8d3f4fd9 100644 --- a/docs/en/trust.rst +++ b/docs/en/trust.rst @@ -29,7 +29,7 @@ except for Wallet Instances which are End-User's personal devices certified by t .. note:: The Wallet Instance, as a personal device, is certified as reliable through a verifiable attestation issued and signed by a trusted third party. - This is called *Wallet Instance Attestation* and is documented in `the dedicated section `_. + This is called *Wallet Attestation* and is documented in `the dedicated section `_. Below the table with the summary of the Federation Entity roles, mapped on the corresponding EUDI Wallet roles, as defined in the `EIDAS-ARF`_. @@ -80,7 +80,7 @@ OpenID Federation facilitates the building of an infrastructure that is: - **Secure and Tamper-proof**, Entities' attestations of metadata and keys are cryptographically signed in the Trust Chain, comprised of attestations issued by multiple parties. These attestations, called statements, cannot be forged or tampered by an adversary; - **Privacy-preserving**, the infrastructure is public and exposes public data such as public keys and metadata of the participants. It does not require authentication of the consumers and therefore does not track who is assessing trust against whom; - **Guarantor of the non-repudiation of long-lived attestations**, historical keys endpoints and historical Trust Chains are saved for years according to data retention policies. This enables the certification of the validity of historical compliance, even in cases of revocation, expiration, or rotation of the keys used for signature verification; -- **Dynamic and flexible**, any participants have the freedom to modify parts of their metadata autonomously, as these are published within their domains and verified through the Trust Chain. Simultaneously, the Trust Anchor or its Intermediate may publish a metadata policy to dynamically modify the metadata of all participants — such as disabling a vulnerable signature algorithm — and obtain certainty of propagation within a configured period of time within the federation; +- **Dynamic and flexible**, any participants have the freedom to modify parts of their metadata autonomously, as these are published within their domains and verified through the Trust Chain. Simultaneously, the Trust Anchor or its Intermediate may publish a metadata policy to dynamically modify the metadata of all participants - such as disabling a vulnerable signature algorithm - and obtain certainty of propagation within a configured period of time within the federation; - **Developer friendly**, JWT and JSON formats have been adopted on the web for years. They are cost-effective in terms of storage and processing and have a wide range of solutions available, such as libraries and software development kits, which enable rapid implementation of the solution; - **Scalable**, the Trust Model can accommodate more than a single organization by using Intermediates and multiple Trust Anchors where needed. @@ -107,7 +107,7 @@ In the table below is provided the map of the components that the ARF defines wi | | | Entity | | | | Statements | +----------------------------------------------------+--------------+----------------+ -| Relying Parties’ registration and authentication | |check-icon| | | +| Relying Parties' registration and authentication | |check-icon| | | | | | Trust Chains | | | | | | | | Federation | @@ -140,7 +140,7 @@ All the endpoints listed below are defined in the `OIDC-FED`_ specs. | federation metadata | **GET** .well-known/openid-federation |Metadata that an Entity | Intermediate | | | |publishes about itself, | | | | |verifiable with a trusted third | Wallet Provider| -| | |party (Superior Entity). It’s | | +| | |party (Superior Entity). It's | | | | |called Entity Configuration. | Relying Party | | | | | | | | | | Credential | @@ -153,7 +153,7 @@ All the endpoints listed below are defined in the `OIDC-FED`_ specs. | fetch endpoint | **GET** /fetch?sub=https://rp.example.org | | Trust Anchor | | | |Returns a signed document (JWS) | | | | |about a specific subject, its | Intermediate | -| | |Subordinate. It’s called Entity | | +| | |Subordinate. It's called Entity | | | | |Statement. | | +---------------------------+----------------------------------------------+--------------------------------+-----------------+ | trust mark status | **POST** /status?sub=...&trust_mark_id=... | | Trust Anchor | @@ -199,6 +199,7 @@ Below is a non-normative example of a Trust Anchor Entity Configuration, where e "jwks": { "keys": [ { + "kty": "EC", "kid": "X2ZOMHNGSDc4ZlBrcXhMT3MzRmRZOG9Jd3o2QjZDam51cUhhUFRuOWd0WQ", "crv": "P-256", @@ -508,9 +509,9 @@ The concatenation of the statements, through the combination of these signing me The Trust Chains can also be verified offline, using one of the Trust Anchor's public keys. .. note:: - Since the Wallet Instance is not a Federation Entity, the Trust Evaluation Mechanism related to it **requires the presentation of the Wallet Instance Attestation during the credential issuance and presentation phases**. + Since the Wallet Instance is not a Federation Entity, the Trust Evaluation Mechanism related to it **requires the presentation of the Wallet Attestation during the credential issuance and presentation phases**. - The Wallet Instance Attestation conveys all the required information pertaining to the instance, such as its public key and any other technical or administrative information, without any User's personal data. + The Wallet Attestation conveys all the required information pertaining to the instance, such as its public key and any other technical or administrative information, without any User's personal data. Relying Party Attestation @@ -527,14 +528,14 @@ The Trust Chain SHOULD be contained within the signed request in the form of a J In offline flows, Trust Chain verification enables the assessment of the reliability of Trust Marks and Attestations contained within. -Wallet Instance Attestation +Wallet Attestation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The Wallet Provider issues the Wallet Instance Attestation, certifying the operational status of its Wallet Instances and including one of their public keys. +The Wallet Provider issues the Wallet Attestation, certifying the operational status of its Wallet Instances and including one of their public keys. -The Wallet Instance Attestation contains the Trust Chain that attests the reliability for its issuer (Wallet Provider) at the time of issuance. +The Wallet Attestation contains the Trust Chain that attests the reliability for its issuer (Wallet Provider) at the time of issuance. -The Wallet Instance provides its Wallet Instance Attestation within the signed request during the PID issuance phase, containing the Trust Chain related to the Wallet Provider. +The Wallet Instance provides its Wallet Attestation within the signed request during the PID issuance phase, containing the Trust Chain related to the Wallet Provider. Trust Chain @@ -564,7 +565,7 @@ Below is a non-normative example of a Trust Chain in its original format (JSON A .. note:: - The entire Trust Chain is verifiable by only possessing the Trust Anchor’s public keys. + The entire Trust Chain is verifiable by only possessing the Trust Anchor's public keys. Offline Trust Attestation Mechanisms @@ -577,7 +578,7 @@ Offline EUDI Wallet Trust Attestation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Given that the Wallet Instance cannot publish its metadata online at the *.well-known/openid-federation* endpoint, -it MUST obtain a Wallet Instance Attestation issued by its Wallet Provider. The Wallet Instance Attestation MUST contain all the relevant information regarding the security capabilities of the Wallet Instance and its protocol related configuration. It SHOULD contain the Trust Chain related to its issuer (Wallet Provider). +it MUST obtain a Wallet Attestation issued by its Wallet Provider. The Wallet Attestation MUST contain all the relevant information regarding the security capabilities of the Wallet Instance and its protocol related configuration. It SHOULD contain the Trust Chain related to its issuer (Wallet Provider). Offline Relying Party Metadata diff --git a/docs/en/wallet-instance-attestation.rst b/docs/en/wallet-attestation.rst similarity index 79% rename from docs/en/wallet-instance-attestation.rst rename to docs/en/wallet-attestation.rst index c3a65893c..abfde0b54 100644 --- a/docs/en/wallet-instance-attestation.rst +++ b/docs/en/wallet-attestation.rst @@ -1,35 +1,35 @@ .. include:: ../common/common_definitions.rst -.. _wallet-instance-attestation.rst: +.. _wallet-attestation.rst: -Wallet Instance Attestation -+++++++++++++++++++++++++++ +Wallet Attestation +++++++++++++++++++ -The Wallet Instance Attestation containing details about the Wallet Instance and the device's security level where the Wallet Instance is installed. It generally attests the **authenticity**, **integrity**, **security**, **privacy**, and **trust** of a specific Wallet Instance. The Wallet Instance Attestation MUST contain a Wallet Instance public key. +The Wallet Attestation containing details about the Wallet Instance and the device's security level where the Wallet Instance is installed. It generally attests the **authenticity**, **integrity**, **security**, **privacy**, and **trust** of a specific Wallet Instance. The Wallet Attestation MUST contain a Wallet Instance public key. General Properties ------------------ -The Wallet Instance Attestation: +The Wallet Attestation: - MUST be issued and MUST be signed by Wallet Provider; - MUST give all the relevant information to attests the **integrity** and **security** of the device where the Wallet Instance is installed. -It is necessary for each Wallet Instance to obtain an the Wallet Instance Attestation before entering the Operational state. +It is necessary for each Wallet Instance to obtain a Wallet Attestation before entering the Operational state. Requirements ------------ -The following requirements for the Wallet Instance Attestation are met: +The following requirements for the Wallet Attestation are met: -1. The Wallet Instance Attestation MUST use a signed JSON Web Token (JWT) format. -2. The Wallet Provider MUST offer a RESTful set of services for issuing the Wallet Instance Attestations. -3. The Wallet Instance Attestation MUST be securely bound to the Wallet Instance public key (**Holder Key Binding**). -4. The Wallet Instance Attestation MUST be issued and signed by an accredited and reliable Wallet Provider, thereby providing integrity and authenticity to the attestation. -5. The Wallet Instance Attestation MUST ensure the integrity and authenticity of the Wallet Instance, verifying that it was accurately created and provided by the Wallet Provider. -6. Each Wallet Instance SHOULD be able to request multiple attestations for different public keys associated with it. This requirement provides a privacy-preserving measure, as the public key MAY be used as a tracking tool during the presentation phase (see alos the point number 10, listed below). -7. The Wallet Instance Attestation SHOULD be usable multiple times during its validity period, allowing for repeated authentication and authorization without the need to request new attestations with each interaction. -8. The Wallet Instance Attestation SHOULD have an expiration date time, after which it will no longer be considered valid. +1. The Wallet Attestation MUST use the signed JSON Web Token (JWT) format. +2. The Wallet Provider MUST offer a RESTful set of services for issuing the Wallet Attestations. +3. The Wallet Attestation MUST be securely bound to the Wallet Instance public key (**Holder Key Binding**). +4. The Wallet Attestation MUST be issued and signed by an accredited and reliable Wallet Provider, thereby providing integrity and authenticity to the attestation. +5. The Wallet Attestation MUST ensure the integrity and authenticity of the Wallet Instance, verifying that it was accurately created and provided by the Wallet Provider. +6. Each Wallet Instance SHOULD be able to request multiple attestations with different public keys associated to them. This requirement provides a privacy-preserving measure, as the public key MAY be used as a tracking tool during the presentation phase (see also the point number 10, listed below). +7. The Wallet Attestation SHOULD be usable multiple times during its validity period, allowing for repeated authentication and authorization without the need to request new attestations with each interaction. +8. The Wallet Attestation SHOULD have an expiration date time, after which it will no longer be considered valid. 9. When the private key associated with the Wallet Instance is lost or deleted, the attestation MUST become invalid to prevent unauthorized use of the Wallet Instance. @@ -47,43 +47,43 @@ Static Component View Dynamic Component View ~~~~~~~~~~~~~~~~~~~~~~ -This section describes the Wallet Instance Attestation format and how the Wallet Provider issues it. +This section describes the Wallet Attestation format and how the Wallet Provider issues it. .. figure:: ../../images/dynamic_view_sequence_wallet_instance_attestation.svg - :name: Sequence Diagram for Wallet Instance Attestation Request - :alt: The figure illustrates the sequence diagram for issuing a Wallet Instance Attestation, with the steps explained below. + :name: Sequence Diagram for Wallet Attestation Request + :alt: The figure illustrates the sequence diagram for issuing a Wallet Attestation, with the steps explained below. :target: https://www.plantuml.com/plantuml/ZP91RzH038NlyojCJwr4n7qFgrOSAf2G409wwSL9h60ryGmUpqRRNuyt6qBJe5MlzlFtx3TpcmtLoj27Tqcn6n2CuZEO5WfOB4ePQj8GagkuuOHYSFKZaru1PYZh-WFsFHby4eTAGvDavFzglceyS3jZndgjkKi9q8mSOnm5tEx0Cy_h8HIezaxUkHKROy_F1A_C7oKgAFqkJlcGb38vkL5gIKuJEOnSxSTw1_S-z6ef6CYmHSCmrfMhtEZBN84cYY4BI_U21dPCbD_34nqdJrOQlECLaZP55flzdFJJrtKIRKnDIpQN_RtjdeJKXHCr8MkUcsYsWs_dqq2Y7nky1DLvRguiVX-Lq3RnmDs_V1VMvuVl0HlZmsbWh5SHuGlzzHjWDwVizZwrlNWPwqWA2mdb3DVJsZUdIwh9rML6dR8TeVb5pHCevTAROy_jXPgv4xIYjBIMv53QgNtf-kMDBuishtT1tD8wHUUNBPwNlzi-YXAsHx08iJPa0Q5nzLjlITeoz7y0 -- **Message 1**: The User starts the Wallet Instance mobile app and gets authenticated in it, a new Wallet Instance Attestation is automatically obtained if the previous one results expired. -- **Message 2-3**: The Wallet Instance retrieves the Wallet Provider metadata, including the list of supported algorithms, public keys, and endpoints. -- **Message 4**: The Wallet Instance verifies the Wallet Provider's trustworthiness by evaluating its Trust Chain. +- **Message 1**: The User starts the Wallet Instance mobile app and gets authenticated to it. +- **Message 2**: The Wallet Instance verifies the Wallet Provider's trustworthiness by evaluating its Trust Chain. +- **Message 3-4**: The Wallet Instance retrieves the Wallet Provider metadata, including the list of supported algorithms, public keys, and endpoints. - **Message 5**: The Wallet Instance generates a new key pair. - **Message 6-7**: The Wallet Instance requests a ``nonce`` from the App Attestation Service. -- **Message 8**: The Wallet Instance creates a Wallet Instance Attestation Request in JWS format, signed with the private key associated with the public key for which it request the attestation. -- **Message 9-13**: The Wallet Instance provides the Wallet Instance Attestation Request to the Wallet Provider, which validates it and issues a signed attestation to the Wallet Instance. -- **Message 13-14**: The Wallet Instance receives the Wallet Instance Attestation signed by the Wallet Provider and performs security and integrity verifications. -- **Message 15**: The Wallet Instance Attestation is now ready for use. +- **Message 8**: The Wallet Instance creates a Wallet Attestation Request in JWS format, signed with the private key associated with the public key for which it request the attestation. +- **Message 9-13**: The Wallet Instance provides the Wallet Attestation Request to the Wallet Provider, which validates it and returns a signed attestation to the Wallet Instance. +- **Message 13-14**: The Wallet Instance receives the Wallet Attestation signed by the Wallet Provider and performs security and integrity verifications. +- **Message 15**: The Wallet Attestation is now ready for use. Detailed Design --------------- The detailed design is explained below. -Wallet Instance Attestation Request +Wallet Attestation Request ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To obtain a Wallet Instance Attestation from the Wallet -Provider it is necessary to send a Wallet Instance Attestation +To obtain a Wallet Attestation from the Wallet +Provider it is necessary to send a Wallet Attestation Request from the Wallet Instance containing the associated public key -, the ``nonce`` value previously requested and a ``jti`` value. +, the ``nonce`` value provided by the App Attestation Service and a ``jti`` value. -The Wallet Instance MUST do an HTTP request to the Wallet Provider `token endpoint`_, +The Wallet Instance MUST do an HTTP request to the Wallet Provider's `token endpoint`_, using the method `POST `__. The **token** endpoint (as defined in `RFC 7523 section 4`_) requires the following parameters encoded in ``application/x-www-form-urlencoded`` format: * ``grant_type`` set to ``urn:ietf:params:oauth:grant-type:jwt-bearer``; -* ``assertion`` containing the signed JWT defined in the Section `Wallet Instance Attestation Request`_. +* ``assertion`` containing the signed JWT defined in the Section `Wallet Attestation Request`_. Below a non-normative example of the HTTP request. @@ -96,7 +96,7 @@ Below a non-normative example of the HTTP request. grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6ImtoakZWTE9nRjNHeGRxd2xVTl9LWl83NTVUT1ZEbmJIaDg2TW1KcHh2a1UifQ.eyJpc3MiOiAidmJlWEprc000NXhwaHRBTm5DaUc2bUN5dVU0amZHTnpvcEd1S3ZvZ2c5YyIsICJhdWQiOiAiaHR0cHM6Ly93YWxsZXQtcHJvdmlkZXIuZXhhbXBsZS5vcmciLCAianRpIjogImY1NjUyMDcyLWFiZWYtNDU5OS1iODYzLTlhNjkwNjA3MzJjYyIsICJub25jZSI6ICIuLi4uLiIsICJjbmYiOiB7Imp3ayI6IHsiY3J2IjogIlAtMjU2IiwgImt0eSI6ICJFQyIsICJ4IjogIjRITnB0SS14cjJwanlSSktHTW56NFdtZG5RRF91SlNxNFI5NU5qOThiNDQiLCAieSI6ICJMSVpuU0IzOXZGSmhZZ1MzazdqWEU0cjMtQ29HRlF3WnRQQklScXBObHJnIiwgImtpZCI6ICJ2YmVYSmtzTTQ1eHBodEFObkNpRzZtQ3l1VTRqZkdOem9wR3VLdm9nZzljIn19LCAiaWF0IjogMTY5MTQ4ODk2MiwgImV4cCI6IDE2OTE0OTYxNjJ9.Dg_yFaiv6lVftR3FFx0v5JW250mBgXLVP1j0ezZcHRyitqSY7xGmx4y-MGur93FAS85vf_Da-L-REVEltwU2Jw -The response is the `Wallet Instance Attestation`_ in JWT format: +The response is the `Wallet Attestation`_ in JWT format: .. code-block:: http @@ -148,8 +148,8 @@ Assertion Payload +--------+-------------------------------------------------------------+ || cnf || JSON object, according to | || || `RFC7800 `_ | -|| || containing the public key of the | -|| || Wallet Instance. | +|| || containing the public part of an asymmetric key pair owned | +|| || by the Wallet Instance. | +--------+-------------------------------------------------------------+ || iat || Unix timestamp of attestation request | || || issuance time. | @@ -159,7 +159,7 @@ Assertion Payload +--------+-------------------------------------------------------------+ -Below a non-normative example of the Wallet Instance Attestation +Below a non-normative example of the Wallet Attestation request where the decoded JWS headers and payload are separated by a comma: .. code-block:: javascript @@ -188,15 +188,15 @@ request where the decoded JWS headers and payload are separated by a comma: "exp": 1686652315 } -Whose corresponding JWS is verifiable using the public key -of the Wallet Provider corresponding to the `kid` made available -in the JWS header. +Whose corresponding JWS is verifiable using the public part of an asymmetric +key pair owned by the Wallet Instance that has a key id which is the same +as the `kid` made available in the JWS header. -Wallet Instance Attestation -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Wallet Attestation +~~~~~~~~~~~~~~~~~~ -The Wallet Instance Attestation MUST be provisioned in JWT format, whose +The Wallet Attestation MUST be provisioned in JWT format, with headers and payload claims are listed below. Header @@ -208,8 +208,9 @@ Header | alg | Algorithm to verify the token | | | signature (es. ES256). | +-----------------------------------+-----------------------------------+ -| kid | Key id used by the Wallet | -| | Provider to sign the attestation. | +| kid | The key id of the key used by the | +| | Wallet Provider to sign the | +| | attestation. | +-----------------------------------+-----------------------------------+ | typ | Media type, set to | | | `wallet-attestation+jwt`, | @@ -229,8 +230,8 @@ Header .. note:: - The claim `trust_chain` or the claim `x5c` MUST be provisioned. - If these are both provisioned, the related public key contained in + One of the claims `trust_chain` and `x5c` MUST be provisioned. + If they are both provided, the related public key MUST be the same in both `trust_chain` and `x5c`. Payload @@ -289,7 +290,7 @@ Payload || || reference. MUST set to `false`. | +---------------------------+------------------------------------------------+ -Below is an example of Wallet Instance Attestation: +Below is an example of Wallet Attestation: .. code-block:: javascript @@ -343,8 +344,8 @@ Below is an example of Wallet Instance Attestation: } -.. _token endpoint: wallet-solution.html#wallet-instance-attestation -.. _Wallet Instance Attestation Request: wallet-instance-attestation.html#format-of-the-wallet-instance-attestation-request -.. _Wallet Instance Attestation: wallet-instance-attestation.html#format-of-the-wallet-instance-attestation +.. _token endpoint: wallet-solution.html#wallet-attestation +.. _Wallet Attestation Request: wallet-attestation.html#format-of-the-wallet-attestation-request +.. _Wallet Attestation: wallet-attestation.html#format-of-the-wallet-attestation .. _RFC 7523 section 4: https://www.rfc-editor.org/rfc/rfc7523.html#section-4 .. _RFC 8414 section 2: https://www.rfc-editor.org/rfc/rfc8414.html#section-2 diff --git a/docs/en/wallet-solution.rst b/docs/en/wallet-solution.rst index dfe8ab4ca..4a2036b1f 100644 --- a/docs/en/wallet-solution.rst +++ b/docs/en/wallet-solution.rst @@ -9,9 +9,9 @@ The Wallet Solution is a comprehensive product offered by the Wallet Provider to The Wallet Solution is issued by the Wallet Provider in the form of a mobile app, it also consists of services and web interfaces for the exchange of data between the Wallet Provider and its Wallet Instances for the requirements of the trust model and in total respect of the user's privacy, in accordance with national and EU legislation. -The mobile app serves as the primary interface for Users, allowing them to access and interact with their digital assets conveniently. These digital assets, known as Attestations, include Personal Identification Data (PID¹), a set of data that can uniquely identify a natural or a legal person, along with other Qualified and non-qualified Electronic Attestations of Attributes, also known as QEAAs and EAAs respectively, or (Q)EAAs for short¹. Once a User installs the mobile app on their device, it is referred to such an installation as a Wallet Instance for the User. +The mobile app serves as the primary interface for Users, allowing them to access and interact with their digital assets conveniently. These digital assets, known as Attestations, include Personal Identification Data (PID[1]), a set of data that can uniquely identify a natural or a legal person, along with other Qualified and non-qualified Electronic Attestations of Attributes, also known as QEAAs and EAAs respectively, or (Q)EAAs for short[1]. Once a User installs the mobile app on their device, it is referred to such an installation as a Wallet Instance for the User. -By supporting the mobile app, the Wallet Provider plays a vital role in ensuring the security and reliability of the entire Wallet Solution, since it is responsible for issuing the Wallet Instance Attestation, that is a cryptographic proof that allow the evaluation of the authenticity and the integrity of the Wallet Instance. +By supporting the mobile app, the Wallet Provider plays a vital role in ensuring the security and reliability of the entire Wallet Solution, since it is responsible for issuing the Wallet Attestation, that is a cryptographic proof that allow the evaluation of the authenticity and the integrity of the Wallet Instance. Requirements @@ -23,51 +23,51 @@ Requirements - **Verification of device ownership by the User**: the Wallet Instance MUST provide a mechanism to verify the User's actual possession and full control of their personal device. Wallet Instance -^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^ The Wallet Instance serves as a unique and secure device for authenticating the User within the Wallet ecosystem. It establishes a strong and reliable identity for the User, enabling them to engage in various digital transactions in a secure and privacy-preserving manner. -The Wallet Instance establishes the trust within the Wallet ecosystem by consistently presenting a Wallet Instance Attestation during interactions with other ecosystem actors such as PID Providers, (Q)EAA Providers, and Relying Parties. These verifiable attestations, provided by the Wallet Provider, reference the public part of the asymmetric cryptographic key owned by the Wallet Instance. Their purpose is to authenticate the Wallet Instance itself, ensuring its realiability when engaging with other ecosystem actors. +The Wallet Instance establishes the trust within the Wallet ecosystem by consistently presenting a Wallet Attestation during interactions with other ecosystem actors such as PID Providers, (Q)EAA Providers, and Relying Parties. These verifiable attestations, provided by the Wallet Provider, reference the public part of the asymmetric cryptographic key owned by the Wallet Instance. Their purpose is to authenticate the Wallet Instance itself, ensuring its realiability when engaging with other ecosystem actors. -To guarantee the utmost security, these cryptographic keys are securely stored within the device's Trusted Execution Environment (TEE)³. This ensures that only the User is allowed to access them, thus preventing unauthorized usage or tampering. For more detailed information, please refer to the `Wallet Instance Attestation section`_ and the `Trust Model section`_ of this document. +To guarantee the utmost security, these cryptographic keys are securely stored within the device's Trusted Execution Environment (TEE)[3]. This ensures that only the User is allowed to access them, thus preventing unauthorized usage or tampering. For more detailed information, please refer to the `Wallet Attestation section`_ and the `Trust Model section`_ of this document. Wallet Instance Lifecycle -^^^^^^^^^^^^^^^^^^^^^^^^^^ -The Wallet Instance has three distinct states: Operational, Valid, and Deactivated. Each state represents a specific functional status and determines the actions that can be performed². +^^^^^^^^^^^^^^^^^^^^^^^^^ +The Wallet Instance has three distinct states: Operational, Valid, and Deactivated. Each state represents a specific functional status and determines the actions that can be performed[2]. Initialization Process -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~ To activate the Wallet Instance, the Users MUST install the mobile wallet application on their device and open it. Furthermore, Users will be asked to set their preferred method of unlocking their device; this can be accomplished by entering a personal identification number (PIN) or by utilizing biometric authentication, such as fingerprint or facial recognition, according to their personal preferences and device's capabilities. After completing these steps, the Wallet Instance sets the Operational state. Transition to Valid state -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~ To transition from the Operational state to the Valid state, the Wallet Instance MUST obtain a valid Personal Identification (PID). Once a valid PID is acquired, the Wallet Instance becomes Valid. In order to securely and unambiguously identify Users, the Wallet Instance adopts a Level of Assurance (LoA) 3 authentication, which guarantees a high level of confidence in the User's identity. The authentication method is chosen by the PID Provider from among the notified eID solutions at the national level. Once the Wallet Instance is in the Operational state, Users can: - - Obtain, view, and manage (Q)EAAs from trusted (Q)EAA Providers¹; - - Authenticate to Relying Parties¹; + - Obtain, view, and manage (Q)EAAs from trusted (Q)EAA Providers[1]; + - Authenticate to Relying Parties[1]; - Authorize the presentation of their digital credentials with Relying Parties. Please refer to the relative sections for further information about PID and (Q)EAAs issuance and presentation. Return to Operational state -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ A Valid Wallet Instance may revert to the Operational state under specific circumstances. These circumstances include the expiration or the revocation of the associated PID by its PID Provider. Deactivation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~ Users have the ability to deactivate the Wallet Instance voluntarily. This action removes the operational capabilities of the Wallet Instance and sets it to the Deactivated state. Deactivation provides Users with control over access and usage according to their preferences. Wallet Provider Endpoints ^^^^^^^^^^^^^^^^^^^^^^^^^ -The Wallet Provider that issues the Wallet Instance Attestations MUST +The Wallet Provider that issues the Wallet Attestations MUST made available its APIs in the form of RESTful services, as listed below. Wallet Provider Metadata @@ -133,7 +133,7 @@ Payload +-----------------------------------+-----------------------------------+ `wallet_provider` metadata -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------------------+---------------------------------------------------------------------+ | **Key** | **Value** | @@ -254,22 +254,22 @@ Below a non-normative example of the Entity Configuration. } -Wallet Instance Attestation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Wallet Attestation +~~~~~~~~~~~~~~~~~~ -Please refer to the `Wallet Instance Attestation section`_. +Please refer to the `Wallet Attestation section`_. External references ^^^^^^^^^^^^^^^^^^^^ -¹ Definitions are inherited from the EUDI Wallet Architecture and Reference Framework, version 1.1.0 at the time of writing. Please refer to `this page `_ for extended definitions and details. +.. [1] Definitions are inherited from the EUDI Wallet Architecture and Reference Framework, version 1.1.0 at the time of writing. Please refer to `this page `_ for extended definitions and details. -² Wallet Instance states adhere to the EUDI Wallet Architecture and Reference Framework, as defined `here `_. +.. [2] Wallet Instance states adhere to the EUDI Wallet Architecture and Reference Framework, as defined `here `_. -³ Depending on the device operating system, TEE is defined by `Trusty`_ or `Secure Enclave`_ for Android and iOS devices, respectively. +.. [3] Depending on the device operating system, TEE is defined by `Trusty`_ or `Secure Enclave`_ for Android and iOS devices, respectively. .. _Trust Model section: trust.html -.. _Wallet Instance Attestation section: wallet-instance-attestation.html +.. _Wallet Attestation section: wallet-attestation.html .. _Trusty: https://source.android.com/docs/security/features/trusty .. _Secure Enclave: https://support.apple.com/en-gb/guide/security/sec59b0b31ff/web diff --git a/images/High-Level-Flow-ITWallet-Presentation-ISO.svg b/images/High-Level-Flow-ITWallet-Presentation-ISO.svg new file mode 100644 index 000000000..6bcf4030f --- /dev/null +++ b/images/High-Level-Flow-ITWallet-Presentation-ISO.svg @@ -0,0 +1 @@ +User's SmartphoneVerifier's SmartphoneUserUserWallet InstanceWallet InstanceVerifier AppVerifier App1Open the Wallet Instance to present an mDoc CredentialDevice Engagement subphase -over QR-2Generate new ephemeral key pair3Show the QR Code for Device Engagement4Scan the QR Code5Generate newephemeral key pair6Compute session keySession establishment and Communication subphase -over BLE secure channel-7mDoc Request + public key of the Verifier App(Session establishment)8Compute session key9Prompt for consent to share the requested information10Grant consent11Retrieve mDoc from local storage12mDoc Response13Verify Response signatureand check mDoc validity \ No newline at end of file diff --git a/images/cross_device_auth_seq_diagram.svg b/images/cross_device_auth_seq_diagram.svg index dd1984a5d..f495b1d91 100644 --- a/images/cross_device_auth_seq_diagram.svg +++ b/images/cross_device_auth_seq_diagram.svg @@ -1,2 +1 @@ - -User's DevicesUserUserWallet InstanceWallet Instanceuser-agentuser-agentRelying PartyRelying Party1Web Service navigation2Request Protected ResourceUser Authentication (Presentation Phase)3Create Authorization Request(statebound to user-agent cookie)4Create request_uri resource5QRCode OR HTTP Redirect (302) with the request_uri endpointCross Device only6Show the QRCode page7Open the Wallet Instance app, local authentication8Scan QR Code9Extract Request URIfrom QR Code10GET Request Objectby Request URIwith Wallet Instance Attestationas DPoP token11Attest that the Wallet Provideris part of the Federationand the Wallet Instance is not revoked,then evaluate the Wallet capabilities.12Request Object13Attest Relying Party Trust14Verify Relying Party Metadata15Validate JWT Signature16Validate Requested VP(s)17Request for consent18Confirmed19POST Authorization Responsewith vp_token20Evaluate the Verifiable Presentation token21Attest Credential Issuer Trustand Validate JWT Signature22Process the credentialProcess the credential:Check Holder Key Binding and Proof of Possession:- using the public key bound in\n the Credential to verify the VP token.Then Extract the disclosed attributes: \n Check if all the required data are available23Update the User session (cookie updated)24HTTP/1.1 200 OK{"redirect_uri": https url with response_code }Same Device only25Use the redirect_uriCross Device only26QRCode JS: Check authentication state (HTTP request with cookie)27Authentication state given with HTTP codes, untill expired or successful \ No newline at end of file +User's DevicesUserUserWallet InstanceWallet Instanceuser-agentuser-agentRelying PartyRelying Party1Web Service navigation2Request Protected ResourceUser Authentication (Presentation Phase)3Create astatevaluebound to user-agent cookie4Create request_uri resource5QRCode OR HTTP Redirect (302) with client_id, request_uri, stateCross Device only6Show the QRCode page7Open the Wallet Instance app, local authentication8Scan QR Code9Extractclient_idrequest_uriand statefrom the QR Code10evaluates trust with the client_id11requests the signed request object from the request_uri endpoint12signed request objectalt[if request_uri_method is set with POST]13provides Wallet metadata to the request_uri endpoint14evaluates the Wallet tecnical capabilities15updated signed request object16evaluates Relying Party Metadata and policies17Verify signature of the signed Request Object18Validate Requested VP(s)19Request for consent20Confirmed21POST Authorization Responsewith vp_token22Evaluate the Verifiable Presentation token23Validate the Wallet Attestation.Attest the Wallet Provideris part of the Federationand the Wallet Instance is not revoked.24Attest Credential Issuer Trustand Validate JWT Signature25Process the credentialProcess the credential:Check Holder Key Binding and Proof of Possession:- using the public key bound in\n the Credential to verify the VP token. Then Extract the disclosed attributes: \n Check if all the required data are available26Update the User session (cookie updated)27HTTP/1.1 200 OK{"redirect_uri": https url with response_code }Same Device only28Use the redirect_uriCross Device only29QRCode JS: Check authentication state (HTTP request with cookie)30Authentication state given with HTTP codes, untill expired or successful \ No newline at end of file diff --git a/images/verifier_qr_code.svg b/images/verifier_qr_code.svg index 4f83ce3ff..437ad39ca 100644 --- a/images/verifier_qr_code.svg +++ b/images/verifier_qr_code.svg @@ -1,45 +1,2 @@ - - - - - - + + diff --git a/requirements-dev.txt b/requirements-dev.txt index 76f8ae99e..92f426730 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -8,7 +8,7 @@ docs-italia-theme @ git+https://github.com/italia/docs-italia-theme.git@3209d99d docutils==0.18.1 idna==3.3 imagesize==1.3.0 -Jinja2==3.1.2 +Jinja2==3.1.3 MarkupSafe==2.1.1 packaging==21.3 Pygments==2.15.0