diff --git a/README.md b/README.md index 8dcd66843..911e8d53a 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,6 @@ This repository hosts the sphinx project tree of EUDI Wallet Technical Specifica The stable release in different languages is published at the link below: - [English](https://italia.github.io/eudi-wallet-it-docs/versione-corrente/en/) - - [Italian](https://italia.github.io/eudi-wallet-it-docs/versione-corrente/it/) ### Preview of a branch diff --git a/docs/en/index.rst b/docs/en/index.rst index b935a03ce..3761bdc08 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -43,14 +43,14 @@ Index of content ssi-introduction.rst defined-terms.rst trust.rst - pid-eaa-data-model.rst - pid-eaa-issuance.rst wallet-solution.rst wallet-instance-attestation.rst + pid-eaa-data-model.rst + pid-eaa-issuance.rst relying-party-solution.rst + revocation-lists.rst pseudonyms.rst backup-restore.rst - revocation-lists.rst algorithms.rst contribute.rst standards.rst diff --git a/docs/en/pid-eaa-data-model.rst b/docs/en/pid-eaa-data-model.rst index 404d3dfc1..da2a53bfc 100644 --- a/docs/en/pid-eaa-data-model.rst +++ b/docs/en/pid-eaa-data-model.rst @@ -6,8 +6,8 @@ PID/(Q)EAA Data Model +++++++++++++++++++++ -The Person Identification Data (PID) is issued by the PID Provider following national laws and allows a natural person to be authenitcated and identified. -The User attributes carried within the Italian PID are the ones listed below: +The Person Identification Data (PID) is issued by the PID Provider according to national laws. The main scope of the PID is allowing natural persons to be authenticated for the access to a service or to a protected resource. +The User attributes provided within the Italian PID are the ones listed below: - Current Family Name - Current First Name @@ -16,11 +16,9 @@ The User attributes carried within the Italian PID are the ones listed below: - Unique Identifier - Taxpayer identification number -The italian PID is extended according to the `OpenID Identity Assurance Profile [OIDC.IDA] `_, that enables the binding of the PID to a national trust framework, giving all the evidence of the identity proofing procedures underlying the PID issuing in both remote and proximity flows. +The Italian digital Credentials, like the PID and the (Q)EAA, contains additional claims and according to the `OpenID Identity Assurance Profile [OIDC.IDA] `_, these carries the national trust framework and the identity proofing procedures underlying the issuance. In particular, these carries some relevant information about the Authentic Sources of the subject's attributes. -The (Q)EAAs are issued by (Q)EAA Issuers to a Wallet Instance and MUST be provided in SD-JWT-VC or mDOC CBOR data format. - -The (Q)EAAs are extended according to the `OpenID Identity Assurance Profile [OIDC.IDA] `_, that allows the recipients to know the Authentic Sources where the data comes from. +The (Q)EAAs are issued by (Q)EAA Issuers to a Wallet Instance and MUST be provided in SD-JWT-VC or MDOC-CBOR data format. The PID/(Q)EAA data format and the mechanism through which a digital credential is issued to the Wallet Instance and presented to a Relying Party are described in the following sections. @@ -107,9 +105,9 @@ The following claims MUST be in the JWT payload and MUST NOT be included in the * - **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. - `[RFC7800, Section 3.1] `_. - * - **type** + * - **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``. - - `[draft-terbu-sd-jwt-vc-latest. Section 4.2.2.2] `__. + - `[draft-terbu-sd-jwt-vc-latest. Section Type Claim] `__. * - **verified_claims** - JSON object containing the following sub-elements: @@ -117,6 +115,7 @@ The following claims MUST be in the JWT payload and MUST NOT be included in the - **claims**. - `[OIDC.IDA. Section 5] `_. +.. _sec-pid-eaa-verification-field: PID/(Q)EAA Verification field ----------------------------- @@ -159,7 +158,7 @@ The ``record`` MUST have at least the following sub parameters: - It uniquely identifies the trust framework used for the provisioning of the credential. For example, in case of PID, the value ``https://eudi.wallet.cie.gov.it`` means that the CIE id identification scheme is used. - `[OID.IDA. Section 5.1.1.2] `_ * - **source** - - JSON Object cointaining the follwoing mandatory claims: + - JSON Object cointaining the following mandatory claims: - **organization_name**: Name of the Organization acting as Authentic Source. - **organization_id**: Identification code for the Organization. For public Organization, it MUST be set to the *IPA Code*, following the URN namespace ``urn:eudi:it:organization_id:ipa_code:``. @@ -169,6 +168,8 @@ The ``record`` MUST have at least the following sub parameters: .. warning:: Note that the sub-claims of the **evidence** parameter are not selectively disclosable separately, thus, for example, the User cannot give only the *record type* without the disclosure of the *record source* value (organization name, identifier and country). +.. _sec-pid-user-claims: + PID Claims field ---------------- @@ -532,11 +533,505 @@ The combined format for the PID issuance is represented below: .. code-block:: - eyJ0eXAiOiJ2YytzZC1qd3QiLCJhbGciOiJSUzUxMiIsImtpZCI6ImQxMjZhNmE4NTZmNzcyNDU2MDQ4NGZhOWRjNTlkMTk1IiwidHJ1c3RfY2hhaW4iOlsiTkVoUmRFUnBZbmxIWTNNNVdsZFdUV1oyYVVobSAuLi4iLCJleUpoYkdjaU9pSlNVekkxTmlJc0ltdHBaQ0k2IC4uLiIsIklrSllkbVp5Ykc1b1FVMTFTRkl3TjJGcVZXMUIgLi4uIl19.eyJpc3MiOiJodHRwczovL2lzc3Vlci5leGFtcGxlLm9yZyIsInN1YiI6Ik56YkxzWGg4dURDY2Q3bm9XWEZaQWZIa3hac1JHQzlYcy4uLiIsImp0aSI6InVybjp1dWlkOjZjNWMwYTQ5LWI1ODktNDMxZC1iYWU3LTIxOTEyMmE5ZWMyYyIsImlhdCI6MTU0MTQ5MzcyNCwiZXhwIjoxNTQxNDkzNzI0LCJzdGF0dXMiOiJodHRwczovL2lzc3Vlci5leGFtcGxlLm9yZy9zdGF0dXMiLCJjbmYiOnsiandrIjp7Imt0eSI6IlJTQSIsImUiOiJBUUFCIiwidXNlIjoic2lnIiwia2lkIjoiZDEyNmE2YTg1NmY3NzI0NTYwNDg0ZmE5ZGM1OWQxOTUiLCJhbGciOiJSUzI1NiIsIm4iOiJvaWFuczV3WUNXazR3RnRFU3RWWWNuX3hPdzllZEtNTkdIMzNfcTZfcEJJMFhhVFk3UDNhcFVnak8waXZrNWMxTlFBVlk2UFptY1BROFAxWTBjQkFDOVNUUm16dlR2RFFjT29jTGhWeTJabGNYVHUzOW9PR0xOcmE4X0xRc2FNQTM4NmxPX3FNVzQtdVk2RGJHWlk0dkhrU2N2QUM5RklaWURQYWZxV0JFUVVOVjJRT0ZNSDVWUG9paENUS0h3TUdYblpCYXRZT2JnNTd4U09VWC1idmhPX3NGTW0zazRSdnNYY3IzTUZvakFoTGZ3dXR1X2pLOWs3TjlLUl9tTmM1SXBpT3loWndfc1VtRjZTYW1ScXNTUHA0MktEMTBoUE1XMFlKVERNWXhCZEhyTUZlU01IWUlNWTRvQkJUNDNfX2E1NXpJTElfQ25JazQyNDF3T3ZHdncifX0sInR5cGUiOiJIZWFsdGhJbnN1cmFuY2VEYXRhIiwidmVyaWZpZWRfY2xhaW1zIjp7InZlcmlmaWNhdGlvbiI6eyJfc2QiOlsiMmpJUjE4Z2ZlQVNIWUdCMjdzN3NTM1NfaVE0eHhGSXhDUnlpb2hyQmZucyJdLCJ0cnVzdF9mcmFtZXdvcmsiOiJlaWRhcyIsImFzc3VyYW5jZV9sZXZlbCI6ImhpZ2gifSwiY2xhaW1zIjp7Il9zZCI6WyIxaXp0cTdib3Y2NHhUWWJEa1dGYzQ0X1ZqV2UwMjloWnFYZVVJbG9xVU40IiwiRU5ObzMxamZ6RnA4WTJEVzBSLWZJTWVXd2U3RUxHdkdvSE13TUJwdTE0RSIsIkZWMkNETld1VHFUZ09IYWZ0dlZhdW1CRjBPbG1ueXhNc3d5ZjR1SXhyaFkiLCJkWldqcTdtSlNTWC1YVElfSFd1RThCMng2SWRNNWxFLWRvRF95QnBLSmFvIiwiZ0hZaTE5ZnJiRF9pNEJvYVdFTk9qYzNsQ25NajRwYkdOUWNzQmpfUU00USJdfX0sIl9zZF9hbGciOiJzaGEtMjU2In0.PrVt9qpf1WmfoRKncGXw6loKRANomsL-foXMqMUIyK2AO0tWM5laveqRet9Bb5A0fPq7rxNQLU57ngV3o8VzKLhFkbKm1_wtA5XuZXBfz0qGCmIP6tZQu9yAvXy162h6_i4FOINyHoL8i5mNPFTHFY0nBYTyVkCScfBC2Ccv4i7RSALbpbpviTpoYVBzFWtdOKuuMED5XwKpW9-VF_JK11yaJJ880walzu5tZ3XAOb0KkfUS3sCmSkKO5wMm1SeaS7xL5iiPSnAMTMrlmKE6qcwAkdDX-hNeGzncwBjHASTWb2udayK8Cal-wFGDWrRWGq3mU0rfuxMIFkjv4gdi8Q + eyJhbGciOiJSUzI1NiIsImtpZCI6Iks2S2hpUDNrOC1XOWVHdk1SVTg0NVVwWVRTdEJsR0g4ejFKZl85czMtUWsifQ.eyJpc3MiOiJodHRwczovL2lzc3Vlci5leGFtcGxlLm9yZyIsInN1YiI6Ik56YkxzWGg4dURDY2Q3bm9XWEZaQWZIa3hac1JHQzlYcy4uLiIsImp0aSI6InVybjp1dWlkOjZjNWMwYTQ5LWI1ODktNDMxZC1iYWU3LTIxOTEyMmE5ZWMyYyIsImlhdCI6MTU0MTQ5MzcyNCwiZXhwIjoxNTQxNDkzNzI0LCJzdGF0dXMiOiJodHRwczovL2lzc3Vlci5leGFtcGxlLm9yZy9zdGF0dXMiLCJjbmYiOnsiandrIjp7Imt0eSI6IlJTQSIsImUiOiJBUUFCIiwidXNlIjoic2lnIiwia2lkIjoiZDEyNmE2YTg1NmY3NzI0NTYwNDg0ZmE5ZGM1OWQxOTUiLCJhbGciOiJSUzI1NiIsIm4iOiJvaWFuczV3WUNXazR3RnRFU3RWWWNuX3hPdzllZEtNTkdIMzNfcTZfcEJJMFhhVFk3UDNhcFVnak8waXZrNWMxTlFBVlk2UFptY1BROFAxWTBjQkFDOVNUUm16dlR2RFFjT29jTGhWeTJabGNYVHUzOW9PR0xOcmE4X0xRc2FNQTM4NmxPX3FNVzQtdVk2RGJHWlk0dkhrU2N2QUM5RklaWURQYWZxV0JFUVVOVjJRT0ZNSDVWUG9paENUS0h3TUdYblpCYXRZT2JnNTd4U09VWC1idmhPX3NGTW0zazRSdnNYY3IzTUZvakFoTGZ3dXR1X2pLOWs3TjlLUl9tTmM1SXBpT3loWndfc1VtRjZTYW1ScXNTUHA0MktEMTBoUE1XMFlKVERNWXhCZEhyTUZlU01IWUlNWTRvQkJUNDNfX2E1NXpJTElfQ25JazQyNDF3T3ZHdncifX0sInR5cGUiOiJIZWFsdGhJbnN1cmFuY2VEYXRhIiwidmVyaWZpZWRfY2xhaW1zIjp7InZlcmlmaWNhdGlvbiI6eyJfc2QiOlsiMmpJUjE4Z2ZlQVNIWUdCMjdzN3NTM1NfaVE0eHhGSXhDUnlpb2hyQmZucyJdLCJ0cnVzdF9mcmFtZXdvcmsiOiJlaWRhcyIsImFzc3VyYW5jZV9sZXZlbCI6ImhpZ2gifSwiY2xhaW1zIjp7Il9zZCI6WyIxaXp0cTdib3Y2NHhUWWJEa1dGYzQ0X1ZqV2UwMjloWnFYZVVJbG9xVU40IiwiRU5ObzMxamZ6RnA4WTJEVzBSLWZJTWVXd2U3RUxHdkdvSE13TUJwdTE0RSIsIkZWMkNETld1VHFUZ09IYWZ0dlZhdW1CRjBPbG1ueXhNc3d5ZjR1SXhyaFkiLCJkWldqcTdtSlNTWC1YVElfSFd1RThCMng2SWRNNWxFLWRvRF95QnBLSmFvIiwiZ0hZaTE5ZnJiRF9pNEJvYVdFTk9qYzNsQ25NajRwYkdOUWNzQmpfUU00USJdfX0sIl9zZF9hbGciOiJzaGEtMjU2In0.vl5ELdx9d7smuDHHDfBGaUySolBe7O3RROqpHDkM3txvXJxgZcCwZQhbWN3sSrBkJgSZ_kFEs2ddYIVKE4bglASlBbSizC8CASdJlyDD3T_dyimA1r2bwSfsHTyrcG_SpoU5Ee9KS-Lr2PCQ3LmTc8_nhaeBGtZCO4B8oZI9bpD6zqms1Zr-ymaE0pYnnQ3aWOclhiLavVudKxLxZvYXTdMStjyNbwBXekVVOnAZuCTuXMsD_jah7_MkmJP_buJgq3u6TthctsORHp4pKuZeI_43Y728-Qg7mIDeL5_-j_vgXdu7FWVa0OSTjZJM27GCDzr2M8LAhApk4aeDoF1Cmw MDOC-CBOR ========= -[TODO] +The PID/(Q)EAA MDOC-CBOR data model is defined in ISO/IEC 18013-5, the standard born for the the mobile driving license (mDL) use case. + +The MDOC data elements MUST be encoded as defined in `RFC 8949 - Concise Binary Object Representation (CBOR) `_. + +The PID encoded in MDOC-CBOR format uses the document type set to `eu.europa.ec.eudiw.pid.1`, according to the reverse domain approach defined in the +`EIDAS-ARF`_ and ISO/IEC 18013-5. + +The document's data elements utilize a consistent namespace for the mandatory Mobile Driving License attributes, while the national PID attributes use the domestic namespace `eu.europa.ec.eudiw.pid.it.1`, as outlined in this implementation profile. + +In compliance with ISO/IEC 18013-5, the MDOC data model in the domestic namespace `eu.europa.ec.eudiw.pid.it.1`, requires the following attributes: + +.. _table-mdoc-attributes: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Attribute name** + - **Description** + - **Reference** + * - **version** + - *tstr (text string)*. Version of the data structure being used. It's a way to track changes and updates to the standard or to a specific implementation profile. This allows for backward compatibility and understanding of the data if the standard or implementation evolves over time. + - [ISO 18013-5#8.3.2.1.2] + * - **status** + - *uint (unsigned int)*. Status code. For example ``"status":0`` means OK (normal processing). + - [ISO 18013-5#8.3.2.1.2.3] + * - **documents** + - *bstr (byte string)*. The collection of digital documents. Each document in this collection represents a specific type of data or information related to the Digital Credential. + - [ISO 18013-5#8.3.2.1.2] + +Each document within the **documents** collection MUST have the following structure: + +.. _table-mdoc-documents-attributes: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Attribute name** + - **Description** + - **Reference** + * - **docType** + - *tstr (text string)*. Document type. For the PID, the value MUST be set to ``eu.europa.ec.eudiw.pid.1.`` For an mDL, the value MUST be ``org.iso.18013-5.1.mDL``. + - [ISO 18013-5#8.3.2.1.2] + * - **issuerSigned** + - *bstr (byte string)*. It MUST contain the Mobile Security Object for Issuer data authentication and the data elements protected by Issuer data authentication. + - [ISO 18013-5#8.3.2.1.2] + +The **issuerSigned** object MUST have the following structure: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Attribute name** + - **Description** + - **Reference** + * - **nameSpaces** + - *bstr (byte string)* with *tag* 24 and *major type* 6. Returned data elements for the namespaces. It MAY be possible to have one or more namespaces. The `nameSpaces` MUST use the same value for the document type. However, it MAY have a domestic namespace to include attributes defined in this implementation profile. The value MUST be set to ``eu.europa.ec.eudiw.pid.it.1``. + - [ISO 18013-5#8.3.2.1.2] + * - **issuerAuth** + - *bstr (byte string)*. Contains *Mobile Security Object* (MSO), a COSE Sign1 Document, issued by the Credential Issuer. + - [ISO 18013-5#9.1.2.4] + +During the presentation of the MDOC-CBOR credential, in addition to the objects in the table above, a **deviceSigned** object MUST also be added. **deviceSigned** MUST NOT be included in the issued credential provided by the PID/(Q)EAA Issuer. + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Attribute name** + - **Description** + - **Reference** + * - **deviceSigned** + - *bstr (byte string)*. Data elements signed by the Wallet Instance during the presentation phase. + - [ISO 18013-5#8.3.2.1.2] + +Where the **deviceSigned** MUST have the following structure: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Attribute name** + - **Description** + - **Reference** + * - **nameSpaces** + - *tstr (text string)*. Returned data elements for the namespaces. It MAY be possible to have one or more namespaces. It MAY be used for self-attested claims. + - [ISO 18013-5#8.3.2.1.2] + * - **deviceAuth** + - *bstr (byte string)*. It MUST contain either the *DeviceSignature* or the *DeviceMac* element. + - [ISO 18013-5#8.3.2.1.2] + + +.. note:: + + A **deviceSigned** object given during the presentation phase has two purposes: + + 1. It provides optional self-attested attributes in the ``nameSpaces`` object. If no self-attested attributes are provided by the Wallet Instance, the ``nameSpaces`` object MUST be included with an empty structure. + 2. Provide a cryptographic proof attesting that the Holder is the legitimate owner of the Credential, by means of a ``deviceAuth`` object. + + +.. note:: + + The ``issuerSigned`` and the ``deviceSigned`` objects contain the ``nameSpaces`` object and the *Mobile Security Object*. The latter is the only signed object, while the ``nameSpaces`` object is not signed. + + + +nameSpaces +---------- + +The **nameSpaces** object contains one or more *IssuerSignedItemBytes* that are encoded using CBOR bitsring 24 tag (#6.24(bstr .cbor), marked with the CBOR Tag 24(<<... >>) and represented in the example using the diagnostic format). It represents the disclosure information for each digest within the `Mobile Security Object` and MUST contain the following attributes: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Name** + - **Encoding** + - **Description** + * - **digestID** + - *integer* + - Reference value to one of the ``ValueDigests`` provided in the *Mobile Security Object* (`issuerAuth`). + * - **random** + - *bstr (byte string)* + - 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 (text string)* + - Data element identifier. + * - **elementValue** + - depends by the value, see the next table. + - Data element value. + +The **elementIdentifier** data that MUST be included in a PID/(Q)EAA are: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Namespace** + - **Element identifier** + - **Description** + * - **eu.europa.ec.eudiw.pid.1** + - **issue_date** + - *full-date (CBORTag 1004)*. Date when the PID/(Q)EAA was issued. + * - **eu.europa.ec.eudiw.pid.1** + - **expiry_date** + - *full-date (CBORTag 1004)*. Date when the PID/(Q)EAA will expire. + * - **eu.europa.ec.eudiw.pid.1** + - **issuing_authority** + - *tstr (text string)*. Name of administrative authority that has issued the PID/(Q)EAA. + * - **eu.europa.ec.eudiw.pid.1** + - **issuing_country** + - *tstr (text string)*. Alpha-2 country code as defined in [ISO 3166]. + * - **eu.europa.ec.eudiw.pid.it.1** + - **verification.evidence** + - *bstr (byte string)*. As defined in the :ref:`PID/(Q)EAA Verification field Section `. + * - **eu.europa.ec.eudiw.pid.it.1** + - **verification.trust_framework** + - *tstr (text string)*. As defined in the :ref:`PID/(Q)EAA Verification field Section `. + * - **eu.europa.ec.eudiw.pid.it.1** + - **verification.assurance_level** + - *tstr (text string)*. As defined in the :ref:`PID/(Q)EAA Verification field Section `. + * - **eu.europa.ec.eudiw.pid.it.1** + - **status** + - *tstr (text string)*. HTTPS URL where the credential validity status is available. + + +Depending on the Digital Credential type, additional **elementIdentifier** data MAY be added. The PID MUST support the following data: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Namespace** + - **Element identifier** + - **Description** + * - **eu.europa.ec.eudiw.pid.1** + - **given_name** + - *tstr (text string)*. See :ref:`PID Claims fields Section `. + * - **eu.europa.ec.eudiw.pid.1** + - **family_name** + - *tstr (text string)*. See :ref:`PID Claims fields Section `. + * - **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 `. + * - **eu.europa.ec.eudiw.pid.it.1** + - **tax_id_code** + - *tstr (text string)*. See :ref:`PID Claims fields Section `. + + +Mobile Security Object +---------------------- + +The **issuerAuth** represents the `Mobile Security Object` which is a `COSE Sign1 Document` defined in `RFC 9052 - CBOR Object Signing and Encryption (COSE): Structures and Process `_. It has the following data structure: + +* protected header +* unprotected header +* payload +* signature. + +The **protected header** MUST contain the following parameter encoded in CBOR format: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Element** + - **Description** + - **Reference** + * - **Signature algorithm** + - `-7` means ES256, SHA-256. + - RFC8152 + +.. note:: + + Only the Signature Algorithm MUST be present in the protected headers, other elements SHOULD not be present in the protected header. + + +The **unprotected header** MUST contain the following parameter: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Element** + - **Description** + - **Reference** + * - **x5chain** + - Identified with the label 33 + - `RFC 9360 CBOR Object Signing and Encryption (COSE) - Header Parameters for Carrying and Referencing X.509 Certificates `_. + +.. note:: + The `x5chain` is included in the unprotected header with the aim to make the Holder able to update the X.509 certificate chain, related to the `Mobile Security Object` issuer, without invalidating the signature. + +The **payload** MUST contain the *MobileSecurityObject*, without the `content-type` COSE Sign header parameter and encoded as a *byte string* (bstr) using the *CBOR Tag* 24. + +The `MobileSecurityObjectBytes` MUST have the following attributes: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Element** + - **Description** + - **Reference** + * - **docType** + - See :ref:`Table `. + - [ISO 18013-5#9.1.2.4] + * - **version** + - See :ref:`Table `. + - [ISO 18013-5#9.1.2.4] + * - **validityInfo**. + - Object containing issuance and expiration datetimes. It MUST contain the following sub-value: + + * *signed* + * *validFrom* + * *validUntil* + - [ISO 18013-5#9.1.2.4] + * - **digestAlgorithm** + - According to the algorithm defined in the protected header. + - [ISO 18013-5#9.1.2.4] + * - **valueDigests** + - Mapped digest by unique id, grouped by namespace. + - [ISO 18013-5#9.1.2.4] + * - **deviceKeyInfo** + - It MUST contain the Wallet Instance's public key containing the following sub-values. + + * *deviceKey* (REQUIRED). + * *keyAuthorizations* (OPTIONAL). + * *keyInfo* (OPTIONAL). + - [ISO 18013-5#9.1.2.4] + +.. note:: + The private key related to the public key stored in the `deviceKey` object is used to sign the `DeviceSignedItems` object and proof the possession of the PID during the presentation phase (see the presentation phase with MDOC-CBOR). + + +MDOC-CBOR Examples +------------------ + +A non-normative example of a PID in MDOC-CBOR format is represented below using the AF Binary encoding: + +.. code-block:: text + + A366737461747573006776657273696F6E63312E3069646F63756D656E747381A267646F6354797065781865752E6575726F70612E65632E65756469772E7069642E316C6973737565725369676E6564A26A697373756572417574688443A10126A1182159021930820215308201BCA003020102021404AD06A30C1A6DC6E93BE0E2E8F78DCAFA7907C2300A06082A8648CE3D040302305B310B3009060355040613025A45312E302C060355040A0C25465053204D6F62696C69747920616E64205472616E73706F7274206F66205A65746F706961311C301A06035504030C1349414341205A65746573436F6E666964656E73301E170D3231303932393033333034355A170D3232313130333033333034345A3050311A301806035504030C114453205A65746573436F6E666964656E7331253023060355040A0C1C5A65746F70696120436974792044657074206F662054726166666963310B3009060355040613025A453059301306072A8648CE3D020106082A8648CE3D030107034200047C5545E9A0B15F4FF3CE5015121E8AD3257C28D541C1CD0D604FC9D1E352CCC38ADEF5F7902D44B7A6FC1F99F06EEDF7B0018FD9DA716AEC2F1FFAC173356C7DA3693067301F0603551D23041830168014BBA2A53201700D3C97542EF42889556D15B7AC4630150603551D250101FF040B3009060728818C5D050102301D0603551D0E04160414CE5FD758A8E88563E625CF056BFE9F692F4296FD300E0603551D0F0101FF040403020780300A06082A8648CE3D0403020347003044022012B06A3813FFEC5679F3B8CDDB51EAA4B95B0CBB1786B09405E2000E9C46618C02202C1F778AD252285ED05D9B55469F1CB78D773671F30FE7AB815371942328317C59032AD818590325A667646F6354797065781865752E6575726F70612E65632E65756469772E7069642E316776657273696F6E63312E306C76616C6964697479496E666FA3667369676E6564C074323032332D30322D32325430363A32333A35365A6976616C696446726F6DC074323032332D30322D32325430363A32333A35365A6A76616C6964556E74696CC074323032342D30322D32325430303A30303A30305A6C76616C756544696765737473A2781865752E6575726F70612E65632E65756469772E7069642E31AC015820A7FFC6F8BF1ED76651C14756A061D662F580FF4DE43B49FA82D80A4B80F8434A025820CD372FB85148700FA88095E3492D3F9F5BEB43E555E5FF26D95F5A6ADC36F8E6035820E67E72111B363D80C8124D28193926000980E1211C7986CACBD26AACC5528D48045820F7D062D662826ED95869851DB06BB539B402047BAEE53A00E0AA35BFBE98265D0658202A132DBFE4784627B86AA3807CD19CFEFF487AAB3DD7A60D0AB119A72E736936075820BDCA9E8DBCA354E824E67BFE1533FA4A238B9EA832F23FB4271EBEB3A5A8F7200858202C0EAEC2F05B6C7FE7982683E3773B5D8D7A01E33D04DFCB162ADD8BD99BEE9A095820BFE220D85657CCEC3C67E7DB1DF747E9148A152334BB6D4B65B273279BCC36EC0A582018E38144F5044301D6A0B4EC9D5F98D4CD950E6EA2C29B849CBD457DA29B6AD30B58203C71D2F0EFA09D9E3FBBDFFD29204F6B292C9F79570AEF72DD86C91F7A3AA5C50C582065743D58D89D45E52044758F546034FD13A4F994BC270CDFA7844F74EB3F4B6E0D5820B4A8EB5D523BFFA17B41BDA12DDC7DA32AE1E5F7FF3DCC394A35401F16919BBF781B65752E6575726F70612E65632E65756469772E7069642E69742E31A10E58209D6C11644651126C94ACDAF0803E86D4C71D15D3B2712A14295416734EFD514D6D6465766963654B6579496E666FA1696465766963654B6579A401022001215820BA01AEA44EEE1E338EB2F04E279DBD51B34655783EE185150838C9A7A7C4DB7122582025BA0044439A3871A7B975A0994A85E79B705A9AC263B3FE899B0A93412EE8C96F646967657374416C676F726974686D675348412D32353658400813C28FD62F2602CBC14724E5865733C44A0FCA589B55C085EC9D5C725D6CCE25BA0044439A3871A7B975A0994A85E79B705A9AC263B3FE899B0A93412EE8C96A6E616D65537061636573A2781865752E6575726F70612E65632E65756469772E7069642E318DD818586DA4686469676573744944016672616E646F6D5820156DF9227AD341EAA61AABD301106FD21BDC18820E01DFC16BCF5FECC447111B71656C656D656E744964656E7469666965726B6578706972795F646174656C656C656D656E7456616C7565D903EC6A323032342D30322D3232D818586FA4686469676573744944026672616E646F6D5820A3A1F13F05544D03A5B50B5FDB78465808393BCF3B7953A345FE28F820C7BE0D71656C656D656E744964656E7469666965726D69737375616E63655F646174656C656C656D656E7456616C7565D903EC6A323032332D30322D3232D8185866A4686469676573744944036672616E646F6D5820852591F90F2C9DED57A03632E2C1322AB52A082A431E71A4149A6830C8F1AD0C71656C656D656E744964656E7469666965726F69737375696E675F636F756E7472796C656C656D656E7456616C7565624954D818587CA4686469676573744944046672616E646F6D5820D1D587B3512ACCE15C4F6B20944CEB002A464E4A158389788563408873C3FCE571656C656D656E744964656E7469666965727169737375696E675F617574686F726974796C656C656D656E7456616C7565764D696E69737465726F2064656C6C27496E7465726E6FD8185864A4686469676573744944056672616E646F6D582094FDD7609C0E73DC8589B5CAB11E1D9058CF8BFF8A336DA5F81FCBA055396A0F71656C656D656E744964656E7469666965726A676976656E5F6E616D656C656C656D656E7456616C7565654D6172696FD8185865A4686469676573744944066672616E646F6D5820660C0A7BF79E0E0261CA1547A4294FB808AA70738F424B13AB1B9440B566AE1371656C656D656E744964656E7469666965726B66616D696C795F6E616D656C656C656D656E7456616C756565526F737369D818586BA4686469676573744944076672616E646F6D5820315C53491286488FA07F5C2CE67135EF5C9959C3469C99A14E9B6DC924F9EBA571656C656D656E744964656E746966696572696269727468646174656C656C656D656E7456616C7565D903EC6A313935362D30312D3132D818587AA4686469676573744944086672616E646F6D582081C5CC04FBDF78E0F84DF72FDB87028ADE08E66DC5F31084826EBAD7AE70D84671656C656D656E744964656E7469666965726B62697274685F706C6163656C656C656D656E7456616C756581A267636F756E747279624954686C6F63616C69747964526F6D65D818587DA4686469676573744944096672616E646F6D5820764EF39C9D01F3AA6A87F441603CFE853FBA3CEE3BC2C168BCC9E96271D6E06371656C656D656E744964656E74696669657269756E697175655F69646C656C656D656E7456616C7565781E78787878787878782D7878782D787878782D787878787878787878787878D81858E8A46864696765737449440A6672616E646F6D5820AD20B3B9C67AED8089FF33ECDC108781C3B49B81CD7A3F059D2FE236977037B271656C656D656E744964656E74696669657275766572696669636174696F6E2E65766964656E63656C656C656D656E7456616C756581A2647479706571656C656374726F6E69635F7265636F7264667265636F7264A264747970656C65696461732E69742E63696566736F75726365A3716F7267616E697A6174696F6E5F6E616D656C65696461732E69742E6369656F6F7267616E697A6174696F6E5F6964646D5F69746C636F756E7472795F636F6465626974D8185879A46864696765737449440B6672616E646F6D5820C12314B3695D1401505187E2113115E2F7B4A14B135DEE320F5E6DF81275F17671656C656D656E744964656E746966696572667374617475736C656C656D656E7456616C7565781D68747470733A2F2F70696470726F76696465722E69742F737461747573D8185877A46864696765737449440C6672616E646F6D5820A7B6A9027ED97F25DF96DD0EAB8093B264A3BD6A1D5B24228F3FC5B18EF835FB71656C656D656E744964656E746966696572781C766572696669636174696F6E2E74727573745F6672616D65776F726B6C656C656D656E7456616C7565656569646173D8185876A46864696765737449440D6672616E646F6D5820C76CE2AE4E9BE1DB07A5CB397B54ACE3ECCC786D3F85E4348B923DEE059783DB71656C656D656E744964656E746966696572781C766572696669636174696F6E2E6173737572616E63655F6C6576656C6C656C656D656E7456616C75656468696768781B65752E6575726F70612E65632E65756469772E7069642E69742E3181D8185877A46864696765737449440E6672616E646F6D5820717DF3F583B1484366C33A1F869F2B5D201D466A8B589C79AB1A2D85E595432571656C656D656E744964656E7469666965726D7461785F69645F6E756D6265726C656C656D656E7456616C75657554494E49542D585858585858585858585858585858 + +The `Diagnostic Notation` of the above MDOC-CBOR is given below: + +.. code-block:: text + + { + "status": 0, + "version": "1.0", + "documents": [ + { + "docType": "eu.europa.ec.eudiw.pid.1", + "issuerSigned": { + "issuerAuth": [ + << {1: -7} >>, % protected header with the value alg:ES256 + { + 33: h'30820215308201BCA003020102021404AD30C…'% 33->X5chain:COSE X_509 + }, + << + 24(<< + { + "docType": "eu.europa.ec.eudiw.pid.1", + "version": "1.0", + "validityInfo": { + "signed": 0("2023-02-22T06:23:56Z"), + "validFrom": 0("2023-02-22T06:23:56Z"), + "validUntil": 0("2024-02-22T00:00:00Z") + }, + "valueDigests": { + "eu.europa.ec.eudiw.pid.1": { + 1:h'0F1571A97FFB799CC8FCDF2BA4FC2909929…', + 2: h'0CDFE077400432C055A2B69596C90…', + 3: h'E2382149255AE8E955AF9B8984395…', + 4: h'BBC77E6CCA981A3AD0C3E544EDF86…', + 6: h'BB6E6C68D1B4B4EC5A2AE9206F5t4…', + 7: h'F8A5966E6DAC9970E0334D8F75E25…', + 8: h'EAD5E8B5E543BD31F3BE57DE4ED45…', + 9: h'DEFDF1AA746718016EF1B94BFE5R6…' + }, + "eu.europa.ec.eudiw.pid.it.1": { + 10: h'AFC5A127BE44753172844B13491D8…', + 11: h'AFC5A127BE44753172844B13492H4…', + 12: h'DJA5A127BE44753172844B13492H4…', + 13: h'KDL5A127BE44753172844B13492H4…', + 14: h'F9EE4D36F67DBD75E23311AC1C29…' + } + }, + "deviceKeyInfo": { + "deviceKey": { + 1: 2, % kty:EC2 (Eliptic curves with x and y coordinate pairs) + -1: 1, % crv:p256 + -2: h'B820963964E53AF064686DD9218303494A…', % x-coordiantes + -3: h'0A6DA0AF437E2943F1836F31C678D89298E9…'% y-ccordiantes + } + }, + "digestAlgorithm": "SHA-256" + } + >>) + >>, + h'1AD0D6A7313EFDC38FCD765852FA2BD43DEBF48BF5A580D' + ], + "nameSpaces": { + "eu.europa.ec.eudiw.pid.1": [ + 24(<< + { + "digestID": 1, + "random": h'E0B70BCEFBD43686F345C9ED429343AA', + "elementIdentifier": "expiry_date", + "elementValue": 1004("2024-02-22") + } + >>), + 24(<< + { + "digestID": 2, + "random": h'AE84834F389EE69888665B90A3E4FCCE', + "elementIdentifier": "issue_date", + "elementValue": 1004("2023-02-22") + } + >>), + 24(<< + { + "digestID": 3, + "random": h'960CB15A2EA9B68E5233CE902807AA95', + "elementIdentifier": "issuing_country", + "elementValue": "IT" + } + >>), + 24(<< + { + "digestID": 4, + "random": h'9D3774BD5994CCFED248674B32A4F76A', + "elementIdentifier": "issuing_authority", + "elementValue": "Ministero dell'Interno" + } + >>), + 24(<< + { + "digestID": 5, + "random": h'EB12193DC66C6174530CDC29B274381F', + "elementIdentifier": "given_name", + "elementValue": "Mario" + } + >>)), + 24(<< + { + "digestID": 6, + "random": h'DB143143538F3C8D41DC024F9CB25C9D', + "elementIdentifier": "family_name", + "elementValue": "Rossi" + } + >>), + 24(<< + { + "digestID": 7, + "random": h'6059FF1CE27B4997B4ADE1DE7B01DC60', + "elementIdentifier": "birthdate", + "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, + "random": h'53C15C57B3B076E788795829190220B4', + "elementIdentifier": "unique_id", + "elementValue": "xxxxxxxx-xxx-xxxx-xxxxxxxxxxxx" + } + >>) + ], + "eu.europa.ec.eudiw.pid.it.1": [ + 24(<< + { + "digestID": 10, + "random": h'CAD1F6A38F603451F1FA653F81FF309D', + "elementIdentifier": "verification.evidence", + "elementValue": [ + { + "type": "electronic_record", + "record": { + "type": "eidas.it.cie", + "source": { + "organization_name": "eidas.it.cie", + "organization_id": "m_it", + "country_code": "it", + } + } + } + ] + } + >>), + 24(<< + { + "digestID": 11, + "random": h'CAD1F6A38F603451F1FA653F81FF309D, + "elementIdentifier": "status", + "elementValue": "https://pidprovider.example.it/status" + } + >>), + 24(<< + { + "digestID": 12, + "random": h'564E3C65D46D06FEDEB0E7293A86GF', + "elementIdentifier": "verification.trust_framework", + "elementValue": "eidas" + } + >>), + 24(<< + { + "digestID": 13, + "random": h'D884E5D5EF4CFC93FDB1E4EE8F3923', + "elementIdentifier": "verification.assurance_level", + "elementValue": "high" + } + >>) + 24(<< + { + "digestID": 14, + "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 cde9ded03..8c20535f8 100644 --- a/docs/en/pid-eaa-issuance.rst +++ b/docs/en/pid-eaa-issuance.rst @@ -84,7 +84,7 @@ The PID/(Q)EAA Issuance phase is based on the **Authorization Code Flow** with * .. figure:: ../../images/Low-Level-Flow-ITWallet-PID-QEAA-Issuance.svg :figwidth: 100% :align: center - :target: https://www.plantuml.com/plantuml/svg/dLNTRl964BtVfnWbaHeaezn7QXIIq0GrhIWbogMrs0ECCBlk_a3eqtVMApjhGZ-H3t5XF3DdvfpvuTuwQPpVLa9wfvNVBj08KVCxAgYMoi75cqLp0TA25sAXF-ABNopOBNlLQwtm0YvVQRLs3vN7Vko3qVikNFPjxxAgqC54SGcgmCPdBr2Lm5d4IT-fqJig8nuiZdocawURwxy6uz6exqU2FtiOte6_1RrmaXGSj3Vm6I0y3Dc-luK3MY6CqWv1xz307YxVNoRpiOY18A4Ywq0lOMwyTLZ2YRI1H8F1UOTtdBNGQabc2swDOB72mf5M378oM7YkXKlHctub6R7Ca-UN-VDiFFvJ7Ca7nHgBZUKKqeKyAVJ4Miy8P248ndaRXz-Giycc4icYHu8Mo5du0vqifPCf4GW20NCnA1t3__uuPbub0XT7Iq8JVO3OPpgQmGp_ySXINHkqjLOMStUeCOEY8bGkfp9hmlDY7OYe5Hx_phVerfhTJ4JgGgMrQ4BTAMBo-jUhg4qhpSWv3c-ONWqWrPIoHK_J4-tuecjl57-ewbbmbbPAEc-m1JZkQwo-wrFJdvsig2HtWAH1Wk8CT_97rLd_A5_k3MM07pKPj3cfGTmA3l7o5aQUjJRqRypJzIvfLW8p45usaVJjG24hjaPDo5eVAFOxujkD2sS69CCp41KHVqzk3InheqJ1_DZsgG5M5eFrfv5nyZJw6rxr25xudfrEmW-jrgp2aG29x66OCmYTmomKr8cs_qvGidWhL6ZO04zJFOKD7lxNLXlDmxJKviGH0AStg81Pr9gOLxArSxPqBOo2971fIrT6AjTkdoxRrMqlmTcR6eQZ98D5EnqK2SLQKc5aKQ2rULDy5Zb4p6IY6JzNcjlUFUJfk7yvOP4NVsjjBQDpGSmoHZRkYVzPsh9V6KPALec-dRoFdVM4nYc_C7TzvRl8lCGbAOhQSH5RwRBeDKXdlVsdU7Xz6uiPhiYwCF5L5IvCKkRGOCNCIX2a8Xe3D-HYA-Dkt1ZSwVW8oSNfcfKmIphMLlUPxUp-9CfsbuurQVR2stX24tVhj4bPYNkkqM-h_m00 + :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 @@ -95,7 +95,16 @@ The PID/(Q)EAA Issuance phase is based on the **Authorization Code Flow** with * **Federation Check:** The Wallet Instance needs to check if the PID/(Q)EAA Provider is part of the Federation, obtaining then its protocol specific Metadata. A non-normative example of a response from the endpoint **.well-known/openid-federation** with the **Entity Configuration** and the **Metadata** of the PID/(Q)EAA Provider is represented within the section `Entity Configuration Credential Issuer`_. -**Steps 5-6 (PAR Request):** The Wallet Instance creates a fresh PKCE code verifier, and ``state`` parameter for the *Pushed Authorization Request*. The Wallet Instance sends these parameters along in a *Pushed Authorization Request* using the OIDC ``request`` parameter (hereafter Request Object) (see :rfc:`9126` Section 3) to the PID/(Q)EAA Provider PAR endpoint to prevent Request URI swapping attack (see :rfc:`9126`). The Wallet Instance MUST create the ``code_verifier`` with enough entropy random string using the unreserved characters with a minimum length of 43 characters and a maximum length of 128 characters, making it impractical for an attacker to guess its value. The value MUST be generated following the recommendation in Section 4.1 of :rfc:`7636`. The Wallet Instance signs this request using the private key that is created during the setup phase to obtain the Wallet Instance Attestation. The related public key that is attested by the Wallet Provider is inside the Wallet Instance Attestation ``cnf`` claim.. An OAuth2 client authentication method is involved, since in this flow the Pushed Authorization Endpoint is a protected endpoint. The client authentication is based on the model defined in [:rfc:`7521`] using the Wallet Instance Attestation JWS inside the ``client_assertion`` parameter. The authorization_details [RAR :rfc:`9396`] parameter is extended to allow Wallet Instance to specify the types of credentials when requesting authorization for the PID/(Q)EAA issuance. The PID/(Q)EAA Provider performs the following checks upon the receipt of the PAR request: +**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. + +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 `_. @@ -107,6 +116,7 @@ The PID/(Q)EAA Issuance phase is based on the **Authorization Code Flow** with * 8. It MUST check that the Request Object is not expired by checking the ``exp`` claim (:rfc:`9126`). 9. It MUST check that the Request Object was issued at a time acceptable by the PID/(Q)EAA Provider by checking the ``iat`` claim. For example, basing on the security policies of the PID/(Q)EAA Provider, it might reject the request if the ``iat`` claim is too far away from the current time (:rfc:`9126`). 10. It MUST check that the ``jti`` claim in the Request Object has not been used before by the Wallet Instance identified by the ``client_id``. This allows the PID/(Q)EAA Provider to mitigate replay attacks (:rfc:`7519`). + 11. It MUST validate the ``client_assertion`` parameter based on Sections 4.1 and 4.2 of [`oauth-attestation-draft `_]. Below a non-normative example of the PAR. @@ -122,45 +132,57 @@ Below a non-normative example of the PAR. &code_challenge_method=S256 &request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KIC Jpc3MiOiAiczZCaGRSa3F0MyIsDQogImF1ZCI6ICJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsDQo gInJlc3BvbnNlX3R5cGUiOiAiY29kZSBpZF90b2tlbiIsDQogImNsaWVudF9pZCI6ICJzNkJoZFJrcXQz IiwNCiAicmVkaXJlY3RfdXJpIjogImh0dHBzOi8vY2xpZW50LmV4YW1... &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation - &client_assertion=$WalletInstanceAttestation$ + &client_assertion=$WIA~WIA-PoP -The JWS header of Request Object is represented below: +An example of Wallet Instance Attestation Proof of Possession is as the following: -.. code-block:: JSON +.. code-block:: - { + { "alg": "ES256", - "kid": "FifYx03bnosD8m6gYQIfNHNP9cM_Sam9Tc5nLloIIrc", + "kid": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c", + "typ": "jwt-client-attestation-pop", + } + . + { + "iss": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c", + "aud": "https://pid-provider.example.org", + "jti": "ad25868c-8377-479b-8094-46fb1e797625", + "iat": 1686645115, + "exp": 1686652315 } +The JWS of Request Object is represented below: -The JWS payload of the Request Object is represented below: - -.. code-block:: JSON +.. code-block:: - { - "iss":"$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$", - "aud":"https://pid-provider.example.org", - "exp":1672422065, - "iat": 1672418465, - "jti":"ac80df576e7109686717bf50b869e882", - "response_type":"code", - "client_id":"$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$", - "state":"fyZiOL9Lf2CeKuNT2JzxiLRDink0uPcd", - "code_challenge":"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", - "code_challenge_method":"S256", - "authorization_details":[ - { - "type":"openid_credential", - "format": "vc+sd-jwt", - "credential_definition": { - "type": "PersonIdentificationData" - } - } - ], - "redirect_uri":"eudiw://start.wallet.example.org", - "client_assertion_type":"urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation", - } + { + "alg": "ES256", + "kid": "FifYx03bnosD8m6gYQIfNHNP9cM_Sam9Tc5nLloIIrc", + } + . + { + "iss":"$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$", + "aud":"https://pid-provider.example.org", + "exp":1672422065, + "iat": 1672418465, + "jti":"ac80df576e7109686717bf50b869e882", + "response_type":"code", + "client_id":"$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$", + "state":"fyZiOL9Lf2CeKuNT2JzxiLRDink0uPcd", + "code_challenge":"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", + "code_challenge_method":"S256", + "authorization_details":[ + { + "type":"openid_credential", + "format": "vc+sd-jwt", + "credential_definition": { + "type": "PersonIdentificationData" + } + } + ], + "redirect_uri":"eudiw://start.wallet.example.org", + } .. note:: @@ -223,10 +245,10 @@ The JWS payload of the Request Object is represented below: **Steps 12-13 (DPoP Proof for Token Endpoint)**: The Wallet Instance MUST create a new key pair for the DPoP and a fresh DPoP Proof JWT following the instruction provided in Section 4 of (:rfc:`9449`) for the token request to the PID/(Q)EAA Provider. The DPoP Proof JWT is signed using the created private key for DPoP by Wallet Instance. DPoP provides a way to bind the Access Token to a certain sender (Wallet Instance) (:rfc:`9449`). This mitigates the misuse of leaked or stolen Access Tokens at the Credential Endpoint of PID/(Q)EAA Issuer as the attacker needs to present a valid DPoP Proof JWT. -**Step 14 (Token Request):** The Wallet Instance sends a token request to the PID/(Q)EAA Provider Token Endpoint using the authorization ``code``, ``code_verifier``, *DPoP Proof JWT* and ``private_key_jwt`` parameters (``client_assertion_type`` and ``client_assertion``). +**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: - 1. It MUST authenticate the Wallet Instance based on the ``private_key_jwt`` Client Authentication method `OpenID.Core#TokenRequest `_. + 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 `_. @@ -250,8 +272,8 @@ The ``client_assertion`` is signed using the private key that is created during &code=SplxlOBeZQQYbYS6WxSbIA &redirect_uri=eudiw://start.wallet.example.org &code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk - &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer - &client_assertion=eyJhbGciOiJIUzI1NiI + &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 and if it is successful, it issues an *Access Token* (bound to the DPoP key) and a fresh ``c_nonce``. @@ -279,37 +301,33 @@ The ``client_assertion`` is signed using the private key that is created during **PID/(Q)EAA Credential Schema and Status registration:** The PID/(Q)EAA Provider MUST register all the issued credentials for their later revocation, if needed. -.. code-block:: http - - POST /credential HTTP/1.1 - Host: pid-provider.example.org - Content-Type: application/x-www-form-urlencoded - Authorization: DPoP Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU - DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik - VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR - nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R - 1JEQSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiJlMWozVl9iS2ljOC1MQUVCIiwiaHRtIj - oiR0VUIiwiaHR1IjoiaHR0cHM6Ly9yZXNvdXJjZS5leGFtcGxlLm9yZy9wcm90ZWN0Z - WRyZXNvdXJjZSIsImlhdCI6MTU2MjI2MjYxOCwiYXRoIjoiZlVIeU8ycjJaM0RaNTNF - c05yV0JiMHhXWG9hTnk1OUlpS0NBcWtzbVFFbyJ9.2oW9RP35yRqzhrtNP86L-Ey71E - OptxRimPPToA1plemAgR6pxHF8y6-yqyVnmcw6Fy1dqd-jfxSYoMxhAJpLjA - - credential_definition=%7B%22type%22:%5B%22PersonIdentificationData%22%5D%7D - &format=vc+sd-jwt - &proof=%7B%22proof_type%22:%22...-ace0-9c5210e16c32%22%7D - - -A non-normative example of proof parameter is given below: - -.. code-block:: JSON - - { - "proof_type": "jwt", - "jwt": "eyJraWQiOiJkaWQ6ZXhhbXBsZTplYm ..." +.. code-block:: + + POST /credential HTTP/1.1 + Host: pid-provider.example.org + Content-Type: application/json + Authorization: DPoP Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU + DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik + VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR + nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R + 1JEQSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiJlMWozVl9iS2ljOC1MQUVCIiwiaHRtIj + oiR0VUIiwiaHR1IjoiaHR0cHM6Ly9yZXNvdXJjZS5leGFtcGxlLm9yZy9wcm90ZWN0Z + WRyZXNvdXJjZSIsImlhdCI6MTU2MjI2MjYxOCwiYXRoIjoiZlVIeU8ycjJaM0RaNTNF + c05yV0JiMHhXWG9hTnk1OUlpS0NBcWtzbVFFbyJ9.2oW9RP35yRqzhrtNP86L-Ey71E + OptxRimPPToA1plemAgR6pxHF8y6-yqyVnmcw6Fy1dqd-jfxSYoMxhAJpLjA + { + "format": "vc+sd-jwt" + "credential_definition":{ + "type": ["PersonIdentificationData"] + }, + "proof": { + "proof_type": "jwt", + "jwt": "eyJraWQiOiJkaWQ6ZXhhbXBsZTplYm" } + } -Where the decoded content of the JWT is represented below: +Where the decoded content of the ``jwt`` parameter is represented below: .. code-block:: JSON @@ -365,7 +383,7 @@ Pushed Authorization Request Endpoint Pushed Authorization Request (PAR) Request ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The requests to the PID/(Q)EAA authorization endpoint MUST be HTTP with method POST, using the mandatory parameters listed below within the HTTP request message body. These MUST be encoded in ``application/x-www-form-urlencoded`` format. +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: .. list-table:: PAR http request parameters @@ -392,10 +410,10 @@ The requests to the PID/(Q)EAA authorization endpoint MUST be HTTP with method P - `OpenID Connect Core. Section 6 `_ * - **client_assertion_type** - It MUST be set to ``urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation``. - - `Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants `_ + - `oauth-attestation-draft `_. * - **client_assertion** - - It MUST be the Wallet Instance Attestation signed JWT. - - `Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants `_ + - It MUST be set to a value containing the Wallet Instance Attestation JWT and the Proof of Possession, separated with the ``~`` character. + - `oauth-attestation-draft `_. The JWT Request Object has the following JOSE header parameters: @@ -474,6 +492,52 @@ 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: + +.. _table_jwt_pop: +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **JOSE header** + - **Description** + - **Reference** + * - **alg** + - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms 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`. + * - **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: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - **Claim** + - **Description** + - **Reference** + * - **iss** + - Thumbprint of the JWK in the ``cnf`` parameter. + - :rfc:`9126` and :rfc:`7519`. + * - **aud** + - It MUST be set to the identifier of the PID/(Q)EAA Provider. + - :rfc:`9126` and :rfc:`7519`. + * - **exp** + - UNIX Timestamp with the expiry time of the JWT. + - :rfc:`9126` and :rfc:`7519`. + * - **iat** + - UNIX Timestamp with the time of JWT issuance. + - :rfc:`9126` and :rfc:`7519`. + * - **jti** + - Unique identifier for the DPoP proof JWT. The value SHOULD be set using a *UUID v4* value according to [:rfc:`4122`]. + - [:rfc:`7519`. Section 4.1.7]. + +.. _sec_par: Pushed Authorization Request (PAR) Response ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -555,12 +619,12 @@ Token endpoint -------------- The token endpoint is used by the Wallet Instance to obtain an Access Token by presenting its authorization grant, as -defined in :rfc:`6749`. +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 `_]. Token Request ^^^^^^^^^^^^^^^ -The request to the PID/(Q)EAA Token endpoint MUST be an HTTP request with method POST, where its body message is encoded in ``application/x-www-form-urlencoded`` format. The Wallet Instance sends the Token endpoint request with *private_key_jwt* authentication and a *DPoP proof* containing the parameters defined in the table below. +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. @@ -589,18 +653,11 @@ All the parameters listed below are REQUIRED: - Verification code of the **code_challenge**. - `Proof Key for Code Exchange by OAuth Public Clients `_. * - **client_assertion_type** - - It MUST be set to ``urn:ietf:params:oauth:client-assertion-type:jwt-bearer``. - - `Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants `_. + - It MUST be set to ``urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation``. + - `oauth-attestation-draft `_. * - **client_assertion** - - JWT signed with the Wallet Instance private key containing the following parameters: - - - **iss**: This MUST contain the ``client_id``. - - **sub**: This MUST contain the ``iss``. - - **aud**: URL of the PID/(Q)EAA Token Endpoint. - - **iat**: UNIX Timestamp with the time of the JWT issuance, coded as NumericDate as indicated in [:rfc: `7519`]. - - **exp**: UNIX Timestamp with the expiry time of the JWT, coded as NumericDate as indicated in [:rfc: `7519`]. - - **jti**: Unique Identifier for this authentication request, generated by the Wallet Instance. E.g., ``uuid4`` format. - - `Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants `_. + - 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`. + - `oauth-attestation-draft `_. A **DPoP Proof JWT** is included in an HTTP request using the ``DPoP`` header parameter containing a DPoP JWS. @@ -620,7 +677,7 @@ The JOSE header of a **DPoP JWT** MUST contain at least the following 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 in Section :ref:`Cryptographic Algorithms ` and MUST NOT be set to ``none`` or with a symmetric algorithm (MAC) identifier. - [:rfc:`7515`]. * - **jwk** - - representing the public key chosen by the 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. + - 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. - [:rfc:`7517`] and [:rfc:`7515`]. @@ -864,6 +921,7 @@ Below is a non-normative example of an Entity Configuration containing an `openi "kid": "FANFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs" }] }, + "authority_hints": ["https://superior-entity.example.org/federation"], "metadata": { "openid_credential_issuer": { "credential_issuer": "https://pid-provider.example.org", diff --git a/docs/en/relying-party-solution.rst b/docs/en/relying-party-solution.rst index f0dfbd422..9aac121b9 100644 --- a/docs/en/relying-party-solution.rst +++ b/docs/en/relying-party-solution.rst @@ -188,17 +188,13 @@ To attest a high level of security, the Wallet Instance submits its Wallet Insta Below the description of the parameters defined in *OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP)*. -.. note:: - The use of DPoP doesn't represent any breaking changes to Wallet Instances that do not support DPoP to a *request_uri* endpoint, since it is assumed to use it as an additional security mechanisms for the attestation of the status of the Wallet Instance. - - If the DPoP HTTP Header is missing, the Relying Party would assume the lowest attestable level of security to the Wallet Instance it is interacting with. +If the DPoP HTTP Header is missing, the Relying Party would assume the lowest attestable level of security to the Wallet Instance it is interacting with. DPoP HTTP Header ^^^^^^^^^^^^^^^^ A **DPoP proof** is included in the request using the HTTP Header ``DPoP`` and containing a JWS. The JWS MUST be verified with the public key made available in the Wallet Instance Attestation (``Authorization: DPoP``). - The JOSE header of the **DPoP JWS** MUST contain at least the following parameters: .. list-table:: @@ -288,7 +284,7 @@ The Relying Party issues the signed Request Object, where a non-normative exampl } . { - "scope": "eu.europa.ec.eudiw.pid.it.1 pid-sd-jwt:unique_id+given_name+family_name", + "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", @@ -353,11 +349,7 @@ The JWS payload parameters are described herein: .. warning:: - This implementation profile use the parameter ``scope`` within the request instead of the ``presentation_definition``. - -Using the parameter ``scope`` requires that the Relying Party Metadata MUST -contain the ``presentation_definition``, where a non-normative example of it -is given below: + 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 @@ -366,7 +358,7 @@ is given below: "id": "presentation definitions", "input_descriptors": [ { - "id": "pid-sd-jwt:unique_id+given_name+family_name", + "id": "eu.europa.ec.eudiw.pid.it.1", "name": "Person Identification Data", "purpose": "User authentication", "format": "vc+sd-jwt", @@ -432,7 +424,7 @@ Below is a non-normative example of the decrypted JSON ``response`` content: "id": "04a98be3-7fb0-4cf5-af9a-31579c8b0e7d", "descriptor_map": [ { - "id": "pid-sd-jwt:unique_id+given_name+family_name", + "id": "eu.europa.ec.eudiw.pid.it.1", "path": "$.vp_token.verified_claims.claims._sd[0]", "format": "vc+sd-jwt" } @@ -567,72 +559,60 @@ Below is a non-normative response example: "https://www.spid.gov.it/SpidL2", "https://www.spid.gov.it/SpidL3" ], - - "vp_formats": { - "jwt_vp_json": { - "alg": [ - "EdDSA", - "ES256K" + "vp_formats": { + "vc+sd-jwt": { + "sd-jwt_alg_values": [ + "ES256", + "ES384" + ], + "kb-jwt_alg_values": [ + "ES256", + "ES384" ] - } - }, + } + }, "presentation_definitions": [ { - "id": "pid-sd-jwt:unique_id+given_name+family_name", + "id": "eu.europa.ec.eudiw.pid.it.1", "input_descriptors": [ { - "id": "sd-jwt", + "id": "IdentityCredential", "format": { - "jwt": { - "alg": [ - "EdDSA", - "ES256" - ] - }, - "constraints": { - "limit_disclosure": "required", - "fields": [ - { - "path": [ - "$.sd-jwt.type" - ], - "filter": { - "type": "string", - "const": "PersonIdentificationData" - } - }, - { - "path": [ - "$.sd-jwt.cnf" - ], - "filter": { - "type": "object", - } - }, - { - "path": [ - "$.sd-jwt.family_name" - ], - "intent_to_retain": "true" - }, - { - "path": [ - "$.sd-jwt.given_name" - ], - "intent_to_retain": "true" - }, - { - "path": [ - "$.sd-jwt.unique_id" - ], - "intent_to_retain": "true" + "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": [ diff --git a/docs/en/trust.rst b/docs/en/trust.rst index 9f02c2641..12ad942e1 100644 --- a/docs/en/trust.rst +++ b/docs/en/trust.rst @@ -2,43 +2,43 @@ .. _trust.rst: -The Trust Infrastructure -++++++++++++++++++++++++ +The Infrastructure of Trust ++++++++++++++++++++++++++++ The EUDI Wallet Architecture Reference Framework (`EIDAS-ARF`_) describes the Trust Model as a *"collection of rules that ensure the legitimacy of the components and the entities involved in the EUDI Wallet ecosystem"*. -This section outlines the implementation of the Trust Model in an infrastructure that complies with OpenID Connect Federation 1.0 `OIDC-FED`_. This infrastructure involves a Federation RESTful API for distributing metadata, metadata policies, trust marks, public keys, X.509 certificates, and the revocation status of the participants (Federation Entities). +This section outlines the implementation of the Trust Model in an infrastructure that complies with OpenID Federation 1.0 `OIDC-FED`_. This infrastructure involves a RESTful API for distributing metadata, metadata policies, trust marks, public keys, X.509 certificates, and the revocation status of the participants, also called Federation Entities. -The Trust Infrastructure facilitates the application of a trust assessment mechanism among the parties defined in the `EIDAS-ARF`_. +The Infrastructure of trust facilitates the application of a trust assessment mechanism among the parties defined in the `EIDAS-ARF`_. .. figure:: ../../images/trust-roles.svg :alt: federation portrait :width: 100% - The roles within the Federation infrastructure, where the Trust Anchor oversees its subordinates, - which include one or more Intermediates and Leafs. In this - representation, both the Trust Anchor and the Intermediates assume the role of Accreditation Body. + The roles within the Federation, where the Trust Anchor oversees its subordinates, + which include one or more Intermediates and Leaves. In this + representation, both the Trust Anchor and the Intermediates MAY assume the role of Accreditation Body. Federation Roles ------------------ -All the participants are Federation Entities that must be accredited by an Accreditation Body, -except for the Wallet Instances which are personal devices certified by their Wallet Provider. +All the participants are Federation Entities that MUST be accredited by an Accreditation Body, +except for Wallet Instances which are End-User's personal devices certified by their Wallet Provider. .. note:: - The Wallet Instance, as a personal device, is certified as trusted through a verifiable attestation issued and signed by its Wallet Provider. + 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 `_. -Below a table with the summary of the Federation Entity roles mapped on the corresponding EUDI roles, as defined in the `EIDAS-ARF`_. +Below the table with the summary of the Federation Entity roles, mapped on the corresponding EUDI Wallet roles, as defined in the `EIDAS-ARF`_. +-----------------------------------------+----------------+-----------------------------------+ | EUDI Role | Federation Role| Notes | +=========================================+================+===================================+ | Public Key Infrastructure (PKI) | Trust Anchor | The Federation has PKI | -| | | capabilities and the | +| | | capabilities. The | | | Intermediates | Entity that configures | | | | the entire infrastructure | | | | is the Trust Anchor. | @@ -62,13 +62,13 @@ Below a table with the summary of the Federation Entity roles mapped on the corr | | | trust mark status endpoint | | | Intermediates | and the fetch endpoint must | | | | be exposed by both Trust Anchors | -| | | and their Intermediates, making | +| | | and Intermediates, making | | | | the Trusted List distributed | | | | over multiple Federation Entities,| | | | where each of these is responsible| | | | for their accredited subordinates.| +-----------------------------------------+----------------+-----------------------------------+ -| EUDI Wallet Provider | Leaf | | +| Wallet Provider | Leaf | | +-----------------------------------------+----------------+-----------------------------------+ @@ -77,8 +77,8 @@ General Properties 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 chain of trust, comprised of attestations issued by multiple parties that 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 requesters and therefore does not track who is assessing trust against whom; +- **Secure and Tamper-proof**, Entities' attestations of metadata and keys are cryptographically signed in the Trust Chain, comprised of attestations issued by multiple parties. These attestations, called statements, cannot be forged or tampered by an adversary; +- **Privacy-preserving**, the infrastructure is public and exposes public data such as public keys and metadata of the participants. It does not require authentication of the consumers and therefore does not track who is assessing trust against whom; - **Guarantor of the non-repudiation of long-lived attestations**, historical keys endpoints and historical Trust Chains are saved for years according to data retention policies. This enables the certification of the validity of historical compliance, even in cases of revocation, expiration, or rotation of the keys used for signature verification; - **Dynamic and flexible**, any participants have the freedom to modify parts of their metadata autonomously, as these are published within their domains and verified through the Trust Chain. Simultaneously, the Trust Anchor or its Intermediate may publish a metadata policy to dynamically modify the metadata of all participants - such as disabling a vulnerable signature algorithm - and obtain certainty of propagation within a configured period of time within the federation; - **Developer friendly**, JWT and JSON formats have been adopted on the web for years. They are cost-effective in terms of storage and processing and have a wide range of solutions available, such as libraries and software development kits, which enable rapid implementation of the solution; @@ -87,7 +87,7 @@ OpenID Federation facilitates the building of an infrastructure that is: Trust Model Requirements ------------------------ -In the table below there's the map of the components that the ARF defines within the Trust Model and their coverage in `OIDC-FED`_. +In the table below is provided the map of the components that the ARF defines within the Trust Model, in the same table is provided their coverage in `OIDC-FED`_. +----------------------------------------------------+--------------+----------------+ | Component | Satisfied | how | @@ -96,9 +96,9 @@ In the table below there's the map of the components that the ARF defines within +----------------------------------------------------+--------------+----------------+ | Issuers registration | |check-icon| | Trust Anchor | | | | | -| | | Intermediate | +| | | Intermediates | | | | accreditation | -| | | systems | +| | | system | | | | | +----------------------------------------------------+--------------+----------------+ | Recognised data models and schemas | |check-icon| | Entity | @@ -107,14 +107,14 @@ In the table below there's the map of the components that the ARF defines within | | | Entity | | | | Statements | +----------------------------------------------------+--------------+----------------+ -| Relying Parties' registration and authentication | |check-icon| | static | +| Relying Parties' registration and authentication | |check-icon| | | | | | Trust Chains | | | | | | | | Federation | | | | Entity | | | | Discovery | +----------------------------------------------------+--------------+----------------+ -| Trust mechanisms in a cross-domain scenario | |check-icon| | static | +| Trust mechanisms in a cross-domain scenario | |check-icon| | | | | | Trust Chains | | | | | | | | Federation | @@ -126,8 +126,8 @@ In the table below there's the map of the components that the ARF defines within Federation API endpoints ------------------------ -OpenID Connect Federation uses RESTful Web Services secured over -HTTPs. OpenID Connect Federation defines which are the web endpoints that the participants MUST make +OpenID Federation 1.0 uses RESTful Web Services secured over +HTTPs. OpenID Federation 1.0 defines which are the web endpoints that the participants MUST make publicly available. The table below summarises the endpoints and their scopes. All the endpoints listed below are defined in the `OIDC-FED`_ specs. @@ -169,19 +169,19 @@ All the endpoints listed below are defined in the `OIDC-FED`_ specs. | | | | | +---------------------------+----------------------------------------------+--------------------------------+-----------------+ -All the responses of the Federation endpoints are in the form of a JWS, with the exception of the **Subordinate Listing endpoint** and the **Trust Mark Status endpoint** that are served as plain JSON by default. +All the responses of the federation endpoints are in the form of JWS, with the exception of the **Subordinate Listing endpoint** and the **Trust Mark Status endpoint** that are served as plain JSON by default. Configuration of the Federation ------------------------------- -The configuration of the Federation is published by the Trust Anchor within its Entity Configuration, available at the well-known web path corresponding to **.well-known/openid-federation**. +The configuration of the federation is published by the Trust Anchor within its Entity Configuration, it is available at the well-known web path corresponding to **.well-known/openid-federation**. -All entities MUST obtain the Federation configuration before entering the operational phase, and they -MUST keep it up-to-date. The Federation configuration is the Trust Anchor's Entity Configuration, it contains the +All the participants in the federation MUST obtain the federation configuration before entering the operational phase, and they +MUST keep it up-to-date. The federation configuration is the Trust Anchor's Entity Configuration, it contains the public keys for signature operations and the maximum number of Intermediates allowed between a Leaf and the Trust Anchor (**max_path_length**). -Below is a non-normative example of a Trust Anchor Entity Configuration, where each parameter is documented in the `OpenID Connect Federation `_ specifications, Section 3.1 for the Federation statements and Section 4 for the Metadata identifiers: +Below is a non-normative example of a Trust Anchor Entity Configuration, where each parameter is documented in the `OpenID Federation `_ specification: .. code-block:: text @@ -229,7 +229,7 @@ Below is a non-normative example of a Trust Anchor Entity Configuration, where e "federation_trust_mark_status_endpoint": "https://registry.eidas.trust-anchor.example.eu/trust_mark_status" } }, - "trust_marks_issuers": { + "trust_mark_issuers": { "https://registry.eidas.trust-anchor.example.eu/openid_relying_party/public": [ "https://registry.spid.eidas.trust-anchor.example.eu", "https://public.intermediary.spid.org" @@ -250,9 +250,9 @@ Entity Configuration The Entity Configuration is the verifiable document that each Federation Entity MUST publish on its own behalf, in the **.well-known/openid-federation** endpoint. -The Entity Configuration HTTP response MUST set the media type `application/entity-statement+jwt`. +The Entity Configuration HTTP Response MUST set the media type to `application/entity-statement+jwt`. -The Entity Configuration MUST be cryptographically signed. The public part of this key MUST be present in the +The Entity Configuration MUST be cryptographically signed. The public part of this key MUST be provided in the Entity Configuration and within the Entity Statement issued by a immediate superior and related to its subordinate Federation Entity. The Entity Configuration MAY also contain one or more Trust Marks. @@ -265,7 +265,7 @@ The Entity Configuration MAY also contain one or more Trust Marks. Entity Configurations Common Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The Entity Configurations of all the participants have in common the parameters listed below. +The Entity Configurations of all the participants in the federation MUST have in common the parameters listed below. .. list-table:: @@ -277,26 +277,24 @@ The Entity Configurations of all the participants have in common the parameters * - **iss** - String. Identifier of the issuing Entity. * - **sub** - - String. Identifier of the Entity to which it is referred. + - String. Identifier of the Entity to which it is referred. It MUST be equal to ``iss``. * - **iat** - - UNIX Timestamp with the time of generation of the JWT, coded as NumericDate as indicated at :rfc:`7519` + - UNIX Timestamp with the time of generation of the JWT, coded as NumericDate as indicated at :rfc:`7519`. * - **exp** - UNIX Timestamp with the expiry time of the JWT, coded as NumericDate as indicated at :rfc:`7519`. * - **jwks** - - A JSON Web Key Set (JWKS) :rfc:`7517` that represents the public part of the signing keys of the Entity at issue. Each JWK in the JWK set MUST have a key ID (claim kid) and MAY have a `x5c` parameter, as defined in :rfc:`7517`. It contains the Federation Entity Keys required for trust evaluation. + - A JSON Web Key Set (JWKS) :rfc:`7517` that represents the public part of the signing keys of the Entity at issue. Each JWK in the JWK set MUST have a key ID (claim kid) and MAY have a `x5c` parameter, as defined in :rfc:`7517`. It contains the Federation Entity Keys required for the operations of trust evaluation. * - **metadata** - JSON Object. Each key of the JSON Object represents a metadata type identifier - containing JSON Object representing the Metadata, according to the Metadata - schema of that type. An Entity Configuration MAY contain more Metadata statements, but only one for each type of - Metadata (<**entity_type**>). the metadata types are defined in the section `Metadata Types `_. + containing JSON Object representing the metadata, according to the metadata + schema of that type. An Entity Configuration MAY contain more metadata statements, but only one for each type of + metadata (<**entity_type**>). the metadata types are defined in the section `Metadata Types `_. -.. note:: - Inside the Entity Configuration the claims **iss** e **sub** MUST contain the same value (HTTPs URL). Entity Configuration Trust Anchor ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The Trust Anchor Entity Configuration, in addition of the common parameters listed above, also contains the following parameters: +The Trust Anchor Entity Configuration, in addition of the common parameters listed above, MAY contain the following parameters: .. list-table:: :widths: 20 60 20 @@ -349,7 +347,7 @@ giving the references of the metadata protocol for each of these. .. note:: - The entities that doesn't have any references to a known draft or standard are intended to be defined in this technical reference. + The entries that don't have any reference to a known draft or standard are intended to be defined in this technical reference. +------------------+-----------------------------+--------------+ | Entity | metadata type | references | @@ -383,10 +381,11 @@ giving the references of the metadata protocol for each of these. `Wallet Solution section `_. + Entity Statements ----------------- -Trust Anchors and Intermediates publish an Entity Statement related to an immediate Subordinate. +Trust Anchors and Intermediates publish Entity Statements related to their immediate Subordinates. The Entity Statement MAY contain a metadata policy and the Trust Marks related to a Subordinate. The metadata policy, when applied, makes one or more changes to the final metadata of the Leaf. The final metadata of a Leaf is derived from the Trust Chain that contains all the statements, starting from the Entity Configuration up to the Entity Statement issued by the Trust Anchor. @@ -394,7 +393,7 @@ The metadata policy, when applied, makes one or more changes to the final metada Trust Anchors and Intermediates MUST expose the Federation Fetch endpoint, where the Entity Statements are requested to validate the Leaf's Entity Configuration signature. .. note:: - The Federation Fetch endpoint MAY also publish X.509 certificates for each of the public keys of the Subordinate. Making the propagation of the X.509 certificates automatic. + The Federation Fetch endpoint MAY also publish X.509 certificates for each of the public keys of the Subordinate. Making the distribution of the issued X.509 certificates via a RESTful service. Below there is a non-normative example of an Entity Statement issued by an Accreditation Body (such as the Trust Anchor or its Intermediate) in relation to one of its Subordinates. @@ -424,28 +423,29 @@ Below there is a non-normative example of an Entity Statement issued by an Accre ] }, "metadata_policy": { - "openid_relying_party": { + "wallet_relying_party": { "scope": { "subset_of": [ "eu.europa.ec.eudiw.pid.1", - "eu.europa.ec.eudiw.pid.1:given_name", + "given_name", + "family_name", "email" ] }, - }, - "client": { "vp_formats": { - "jwt_vp": { - "alg": - "subset_of": [ - "EdDSA", - "ES256K" - ] - } + "vc+sd-jwt": { + "sd-jwt_alg_values": [ + "ES256", + "ES384" + ], + "kb-jwt_alg_values": [ + "ES256", + "ES384" + ] } } } - } + } } @@ -486,33 +486,33 @@ The Entity Statement issued by Trust Anchors and Intermediates contains the foll - Federation JWKS of the *sub* entity. See `OIDC-FED`_ Section 3.1 for further details. - |check-icon| * - **metadata_policy** - - JSON Object that describes the Metadata policy. Each key of the JSON Object represents an identifier of the type of Metadata and each value MUST be a JSON Object that represents the Metadata policy according to that Metadata type. Please refer to the `OIDC-FED`_ specifications, Section-5.1, for the implementation details. + - JSON Object that describes the Metadata policy. Each key of the JSON Object represents an identifier of the metadata type and each value MUST be a JSON Object that represents the metadata policy according to that metadata type. Please refer to the `OIDC-FED`_ specifications, Section-5.1, for the implementation details. - |uncheck-icon| * - **trust_marks** - JSON Array containing the Trust Marks issued by itself for the subordinate subject. - |uncheck-icon| * - **constraints** - - It MAY contain the **allowed_leaf_entity_types**, that restricts what types of metadata a subject is allowed to publish. + - It MAY contain the **allowed_leaf_entity_types**, that restricts what types of metadata the subject is allowed to publish. - |check-icon| Trust Evaluation Mechanism -------------------------- -The Trust Anchor publishes the list of its Intermediates (Federation Subordinate Listing endpoint) and the attestations of their metadata and public keys (Entity Statements). +The Trust Anchor publishes the list of its Subordinates (Federation Subordinate Listing endpoint) and the attestations of their metadata and public keys (Entity Statements). -Each participant, including Trust Anchor, Intermediate, Credential Issuer, Wallet Provider, and Relying Party, publishes its own metadata and public keys (Entity Configuration endpoint) on the well-known web resource **.well-known/openid-federation**. +Each participant, including Trust Anchor, Intermediate, Credential Issuer, Wallet Provider, and Relying Party, publishes its own metadata and public keys (Entity Configuration endpoint) in the well-known web resource **.well-known/openid-federation**. -Each of these can be verified using the Entity Statement issued by a superior, Trust Anchor, or Intermediate. +Each of these can be verified using the Entity Statement issued by a superior, such as the Trust Anchor or an Intermediate. -Each Entity Statement is verifiable over time and has an expiration date. The revocation of each statement is verifiable in real time and online (only for remote flows) through the federation endpoints. +Each Entity Statement is verifiable over time and MUST have an expiration date. The revocation of each statement is verifiable in real time and online (only for remote flows) through the federation endpoints. .. note:: - The revocation of an Entity is made with the unavailability of the Entity Statement related to it. If the Trust Anchor or its Intermediates doesn't publish a valid Entity Statement, or if they publish an expired/invalid Entity Statement, the subject of the Entity Statement MUST be intended as not valid or revoked. + The revocation of an Entity is made with the unavailability of the Entity Statement related to it. If the Trust Anchor or its Intermediate doesn't publish a valid Entity Statement, or if it publishes an expired/invalid Entity Statement, the subject of the Entity Statement MUST be intended as not valid or revoked. The concatenation of the statements, through the combination of these signing mechanisms and the binding of claims and public keys, forms the Trust Chain. -The Trust Chains can also be verified offline, using one of the Trust Anchor's public keys. +The Trust Chains can also be verified offline, using one of the Trust Anchor's public keys. .. note:: Since the Wallet Instance is not a Federation Entity, the Trust Evaluation Mechanism related to it **requires the presentation of the Wallet Instance Attestation during the credential issuance and presentation phases**. @@ -525,7 +525,7 @@ Relying Party Attestation The Relying Party is accredited by a Trust Anchor or its Intermediate and obtains a Trust Mark to be included in its Entity Configuration. In its Entity Configuration the Relying Party publishes its specific metadata, including the supported signature and encryption algorithms and any other necessary information for the interoperability requirements. -Any requests for user attributes, such as PID or (Q)EAA, from the Relying Party to Wallet Instances are signed and contain the verifiable Trust Chain regarding the Relying Party. +Any requests for User attributes, such as PID or (Q)EAA, from the Relying Party to Wallet Instances are signed and SHOULD contain the verifiable Trust Chain regarding the Relying Party. The Wallet Instance verifies that the Trust Chain related to the Relying Party is still active, proving that the Relying Party is still part of the Federation and not revoked. @@ -539,9 +539,10 @@ Wallet Instance 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 Instance Attestation contains the Trust Chain that attests the validity for its issuer (Wallet Provider). +The Wallet Instance 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 presents its Wallet Instance Attestation within the signed request during the PID issuance phase, containing the Trust Chain related to the Wallet Provider. The PID Provider issues a PID including the public key provided by the Wallet Instance to have the Holder Key Binding within the issued PID. Trust Chain ^^^^^^^^^^^^^^^ @@ -576,11 +577,7 @@ Below is a non-normative example of a Trust Chain in its original format (JSON A Offline Trust Attestation Mechanisms ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In this section, we describe the implementation requirements to enable -offline trust evaluation mechanisms. - -.. note:: - The offline flows do not allow for real-time evaluation of an Entity's status, such as its revocation. At the same time, using short-lived Trust Chains enables the attainment of trust attestations compatible with the required revocation administrative protocols (e.g., a revocation must be propagated in less than 24 hours, thus the Trust Chain must not be valid for more than that period). +The offline flows do not allow for real-time evaluation of an Entity's status, such as its revocation. At the same time, using short-lived Trust Chains enables the attainment of trust attestations compatible with the required revocation administrative protocols (e.g., a revocation must be propagated in less than 24 hours, thus the Trust Chain must not be valid for more than that period). Offline EUDI Wallet Trust Attestation @@ -590,17 +587,16 @@ Given that the Wallet Instance cannot publish its metadata online at the *.well- 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). - Offline Relying Party Metadata ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Since the Federation Entity Discovery is only applicable in online scenarios, it is possible to include the Trust Chain in the presentation requests that a Relying Party may issue for a Wallet Instance. +Since the Federation Entity Discovery is only applicable in online scenarios, it is possible to include the Trust Chain in the presentation requests that the Relying Party may issue for a Wallet Instance. The Relying Party MUST sign the presentation request, the request SHOULD include the `trust_chain` claim in its JWS header parameters, containing the Federation Trust Chain related to itself. The Wallet Instance that verifies the request issued by the Relying Party MUST use the Trust Anchor's public keys to validate the entire Trust Chain related to the Relying Party before attesting its reliability. -Furthermore, the Wallet Instance applies the metadata policy, if available, to filter out any User attributes not attested in the Relying Party metadata, as derived from the Trust Chain made available in the Relying Party's signed request. +Furthermore, the Wallet Instance applies the metadata policy, if any. Non-repudiability of the Long Lived Attestations @@ -624,12 +620,13 @@ Privacy Remarks - The Wallet Instance metadata MUST not contain information that may disclose technical information about the hardware used. - Leaf entity, Intermediate, and Trust Anchor metadata may include the necessary amount of data as part of administrative, technical, and security contact information. It is generally not recommended to use personal contact details in such cases. From a legal perspective, the publication of such information is needed for operational support concerning technical and security matters and the GDPR regulation. + Considerations about Decentralization ------------------------------------- - There may be more than a single Trust Anchor. - In some cases, a trust verifier may trust an Intermediate, especially when the Intermediate acts as a Trust Anchor within a specific perimeter, such as cases where the Leafs are both in the same perimeter like a Member State jurisdiction (eg: an Italian Relying Party with an Italian Wallet Instance may consider the Italian Intermediate as a Trust Anchor for the scopes of their interactions). - Trust attestations (Trust Chain) should be included in the JWS issued by Credential Issuers, and the Presentation Requests of RPs should contain the Trust Chain related to them (issuers of the presentation requests). -- Since the credential presentation must be signed, storing the signed presentation requests and responses, which include the Trust Chain, the Wallet Instance may have the snapshot of the federation configuration (Trust Anchor Entity Configuration in the Trust Chain) and the verifiable reliability of the Relying Party it has interacted with. This information must be stored on the Wallet Device and may be backed up in a remote and secure cloud storage, with the explicit permission of its User. +- Since the credential presentation must be signed, storing the signed presentation requests and responses, which include the Trust Chain, the Wallet Instance may have the snapshot of the federation configuration (Trust Anchor Entity Configuration in the Trust Chain) and the verifiable reliability of the Relying Party it has interacted with. - Each signed attestation is long-lived since it can be cryptographically validated even when the federation configuration changes or the keys of its issuers are renewed. -- Each participant should be able to update its Entity Configuration without notifying the changes to any third party. The Metadata Policy of a Trust Chain must be applied to overload any information related to protocol metadata and allowed grants of the participants. +- Each participant should be able to update its Entity Configuration without notifying the changes to any third party. The metadata policy contained within a Trust Chain must be applied to overload any information related to protocol specific metadata. diff --git a/docs/en/wallet-instance-attestation.rst b/docs/en/wallet-instance-attestation.rst index ffa048e59..c3a65893c 100644 --- a/docs/en/wallet-instance-attestation.rst +++ b/docs/en/wallet-instance-attestation.rst @@ -79,7 +79,7 @@ Request from the Wallet Instance containing the associated public key The Wallet Instance MUST do an HTTP request to the Wallet Provider `token endpoint`_, using the method `POST `__. -The **token** endpoint (as defined in `RFC 7523 section 4`_) requires the following parameters +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``; @@ -102,7 +102,7 @@ The response is the `Wallet Instance Attestation`_ in JWT format: HTTP/1.1 201 OK Content-Type: application/jwt - + eyJhbGciOiJFUzI1NiIsInR5cCI6IndhbGxldC1hdHRlc3RhdGlvbitqd3QiLCJraWQiOiI1dDVZWXBCaE4tRWdJRUVJNWlVenI2cjBNUjAyTG5WUTBPbWVrbU5LY2pZIiwidHJ1c3RfY2hhaW4iOlsiZXlKaGJHY2lPaUpGVXouLi42UzBBIiwiZXlKaGJHY2lPaUpGVXouLi5qSkxBIiwiZXlKaGJHY2lPaUpGVXouLi5IOWd3Il19.eyJpc3MiOiJodHRwczovL3dhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZyIsInN1YiI6InZiZVhKa3NNNDV4cGh0QU5uQ2lHNm1DeXVVNGpmR056b3BHdUt2b2dnOWMiLCJ0eXBlIjoiV2FsbGV0SW5zdGFuY2VBdHRlc3RhdGlvbiIsInBvbGljeV91cmkiOiJodHRwczovL3dhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZy9wcml2YWN5X3BvbGljeSIsInRvc191cmkiOiJodHRwczovL3dhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZy9pbmZvX3BvbGljeSIsImxvZ29fdXJpIjoiaHR0cHM6Ly93YWxsZXQtcHJvdmlkZXIuZXhhbXBsZS5vcmcvbG9nby5zdmciLCJhdHRlc3RlZF9zZWN1cml0eV9jb250ZXh0IjoiaHR0cHM6Ly93YWxsZXQtcHJvdmlkZXIuZXhhbXBsZS5vcmcvTG9BL2Jhc2ljIiwiY25mIjp7Imp3ayI6eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6IjRITnB0SS14cjJwanlSSktHTW56NFdtZG5RRF91SlNxNFI5NU5qOThiNDQiLCJ5IjoiTElablNCMzl2RkpoWWdTM2s3alhFNHIzLUNvR0ZRd1p0UEJJUnFwTmxyZyIsImtpZCI6InZiZVhKa3NNNDV4cGh0QU5uQ2lHNm1DeXVVNGpmR056b3BHdUt2b2dnOWMifX0sImF1dGhvcml6YXRpb25fZW5kcG9pbnQiOiJldWRpdzoiLCJyZXNwb25zZV90eXBlc19zdXBwb3J0ZWQiOlsidnBfdG9rZW4iXSwidnBfZm9ybWF0c19zdXBwb3J0ZWQiOnsiand0X3ZwX2pzb24iOnsiYWxnX3ZhbHVlc19zdXBwb3J0ZWQiOlsiRVMyNTYiXX0sImp3dF92Y19qc29uIjp7ImFsZ192YWx1ZXNfc3VwcG9ydGVkIjpbIkVTMjU2Il19fSwicmVxdWVzdF9vYmplY3Rfc2lnbmluZ19hbGdfdmFsdWVzX3N1cHBvcnRlZCI6WyJFUzI1NiJdLCJwcmVzZW50YXRpb25fZGVmaW5pdGlvbl91cmlfc3VwcG9ydGVkIjpmYWxzZSwiaWF0IjoxNjg3MjgxMTk1LCJleHAiOjE2ODcyODgzOTV9.tNvCyFPCL5tUi2NakKwdaG9xbrtWWl4djSRYRfHrF8NdmffdT044U55pRn35J2cl0LZxbesEDrfSAz2pllw2Ug @@ -151,6 +151,12 @@ Assertion Payload || || containing the public key of the | || || Wallet Instance. | +--------+-------------------------------------------------------------+ +|| iat || Unix timestamp of attestation request | +|| || issuance time. | ++--------+-------------------------------------------------------------+ +|| exp || Unix timestamp regarding the | +|| || expiration date time. | ++--------+-------------------------------------------------------------+ Below a non-normative example of the Wallet Instance Attestation @@ -183,8 +189,8 @@ request where the decoded JWS headers and payload are separated by a comma: } Whose corresponding JWS is verifiable using the public key -of the Wallet Provider corresponding to the `kid` made available -in the header. +of the Wallet Provider corresponding to the `kid` made available +in the JWS header. Wallet Instance Attestation @@ -222,7 +228,7 @@ Header +-----------------------------------+-----------------------------------+ .. note:: - + The claim `trust_chain` or the claim `x5c` MUST be provisioned. If these are both provisioned, the related public key contained in MUST be the same in both `trust_chain` and `x5c`. @@ -249,9 +255,9 @@ Payload || || problems is to have a limited | || || duration of the attestation. | +---------------------------+------------------------------------------------+ -|| attested_security_context|| Attested security context: | -|| || Represents the level of "security" | -|| || attested by the Wallet Provider. | +|| aal || JSON String asserting the authentication level| +|| || of the Wallet and the key as asserted in | +|| || the cnf claim. | +---------------------------+------------------------------------------------+ || cnf || This parameter contains the ``jwk`` | || || parameter | @@ -264,9 +270,14 @@ Payload || response_types_supported || JSON array containing a list of | || || the OAuth 2.0 ``response_type`` values. | +---------------------------+------------------------------------------------+ -|| vp_formats_supported || JSON object containing | -|| || ``jwt_vp_json`` and ``jwt_vc_json`` | -|| || supported algorithms array. | +|| response_modes_supported || JSON array containing a list of the OAuth 2.0 | +|| || "response_mode" values that this | +|| || authorization server supports. | +|| || `RFC 8414 section 2`_ | ++---------------------------+------------------------------------------------+ +|| vp_formats_supported || JSON object with name/value pairs, | +|| || identifying a Credential format supported | +|| || by the Wallet. | +---------------------------+------------------------------------------------+ || request_object_signing || JSON array containing a list of the | || _alg_values_supported || JWS signing algorithms (alg values) | @@ -278,10 +289,6 @@ Payload || || reference. MUST set to `false`. | +---------------------------+------------------------------------------------+ -.. note:: - The claim ``attested_security_context`` (Attested Security Context) is under discussion - and MUST be intended as experimental. - Below is an example of Wallet Instance Attestation: .. code-block:: javascript @@ -300,7 +307,7 @@ Below is an example of Wallet Instance Attestation: { "iss": "https://wallet-provider.example.org", "sub": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c", - "attested_security_context": "https://wallet-provider.example.org/LoA/basic", + "aal": "https://trust-list.eu/aal/high", "cnf": { "jwk": @@ -316,13 +323,16 @@ Below is an example of Wallet Instance Attestation: "response_types_supported": [ "vp_token" ], + "response_modes_supported": [ + "form_post.jwt" + ], "vp_formats_supported": { - "jwt_vp_json": { - "alg_values_supported": ["ES256"] - }, - "jwt_vc_json": { - "alg_values_supported": ["ES256"] - } + "vc+sd-jwt": { + "sd-jwt_alg_values": [ + "ES256", + "ES384" + ] + } }, "request_object_signing_alg_values_supported": [ "ES256" @@ -337,3 +347,4 @@ Below is an example of 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 .. _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 cdf3e8b74..9dc0b9697 100644 --- a/docs/en/wallet-solution.rst +++ b/docs/en/wallet-solution.rst @@ -77,7 +77,7 @@ Provider Entity Configuration. The Wallet Provider Entity Configuration is a JWS containing the public keys and supported algorithms of the Wallet Provider metadata definition. It is structured in accordance with the `OpenID Connect Federation `_ and the Trust Model section outlined in this specification. -The returning Entity Configuration of the Wallet Provider MUST contain the +The returning Entity Configuration of the Wallet Provider MUST contain the attributes listed below: Header @@ -145,14 +145,11 @@ Payload | token_endpoint | Endpoint for obtaining the Wallet | | | Instance Attestation. | +---------------------------------------------+---------------------------------------------------------------------+ -| attested_security_context_values_supported | List of supported values for the | +| aal_values_supported | List of supported values for the | | | certifiable security context. These | | | values specify the security level | | | of the app, according to the levels: low, medium, or high. | -| | An attested security context is | -| | defined by the proof that the | -| | Wallet Instance can provide to the | -| | Wallet Provider. | +| | Authenticator Assurance Level values supported. | +---------------------------------------------+---------------------------------------------------------------------+ | grant_types_supported | The types of grants supported by | | | the token endpoint. It MUST be set to | @@ -163,11 +160,11 @@ Payload | ted | the token endpoint. | +---------------------------------------------+---------------------------------------------------------------------+ | token_endpoint_auth_signing_alg_va | Supported signature | -| lues_supported | algorithms for the token endpoint | +| lues_supported | algorithms for the token endpoint. | +---------------------------------------------+---------------------------------------------------------------------+ .. note:: - The `attested_security_context_values_supported` parameter is experimental and under review. + The `aal_values_supported` parameter is experimental and under review. Payload `federation_entity` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -224,7 +221,7 @@ Below a non-normative example of the Entity Configuration. ] }, "token_endpoint": "https://wallet-provider.example.org/token", - "attested_security_context_values_supported": [ + "aal_values_supported": [ "https://wallet-provider.example.org/LoA/basic", "https://wallet-provider.example.org/LoA/medium", "https://wallet-provider.example.org/LoA/high" diff --git a/images/Low-Level-Flow-ITWallet-PID-QEAA-Issuance.svg b/images/Low-Level-Flow-ITWallet-PID-QEAA-Issuance.svg index 40c8d8c77..d4bacd980 100644 --- a/images/Low-Level-Flow-ITWallet-PID-QEAA-Issuance.svg +++ b/images/Low-Level-Flow-ITWallet-PID-QEAA-Issuance.svg @@ -1 +1,2 @@ -User's smartphoneUserUserBrowserBrowserWallet InstanceWallet InstanceWallet ProviderWallet ProviderPID/(Q)EAA ProviderPID/(Q)EAA Provider1obtain your PID/(Q)EAA2yesobtain a list of Trusted PID/(Q)EAA Provider3confirm the selection of PID/(Q)EAA Provider4okWallet Instance checks that the PID/(Q)EAA Issuer is part of the Federation and obtains its Metadata5create PKCE code verifier6PAR Request (response_type, client_id, code_challenge, code_challenge_method, request, client_assertion_type, client_assertion=$WalletInstanceAttestation$)PID/(Q)EAA Provider checks that the Wallet Provider is part of the FederationPID/(Q)EAA Provider checks that the signature of the Wallet Instance Attestation and its validity7PAR Response (request_uri, expires_in)8Authorization Request (client_id, request_uri)9Authorization Request (client_id, request_uri)alt[(Q)EAA issuance]User authentication with PID and consent[PID issuance]User authentication with eIDAS LoA High and consent10Authorization Response (code, state, iss)11Authorization Response (code, state, iss)12generate DPoP key13generate DPoP proof for PID/(Q)EAA Issuer token endpoint14Token Request with DPoP proof (client_id, grant_type, code, code_verifier, client_assertion_type, client_assertion, redirect_uri)15Token Response (access_token, token_type, expires_in, c_nonce, c_nonce_expires_in)16create proof of possession (c_nonce)17create DPoP proof for PID/(Q)EAA Issuer credential endpoint18Credential Request with DPoP access_token and DPoP proof (credential_definition, format, proof)Register all the credential-relatedinformation for verification/revocation19Credential Response (format, credential, c_nonce, c_nonce_expires_in)20PID/(Q)EAA validity and status check21store credential \ No newline at end of file + +User's smartphoneUserUserBrowserBrowserWallet InstanceWallet InstancePID ProviderPID Provider1obtain your PID2yesobtain the list of the Trusted PID Providers3confirm the selection of PID Provider4okCheck PID Provider is part of the Federation and obtain its metadata5create PKCE code verifier and WIA-PoP6PAR Request (response_type,client_id,code_challenge,code_challenge_method,request,client_assertion_type,client_assertion=WIA~WIA-PoP)Check Wallet Provider is part of the FederationCheck signature of the Wallet Attestation and its validity7PAR Response (request_uri, expires_in)8Authorization Request (client_id, request_uri)9Authorization Request (client_id, request_uri)user authentication with eIDAS High and consent10Authorization Response (code, state, iss)11Authorization Response (code, state, iss)12generate DPoP key13generate DPoP proof and WIA-PoP for PID Provider token endpoint14Token Request with DPoP proof (client_id,grant_type,code,code_verifier,client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation,client_assertion=WIA~WIA-PoP,redirect_uri)15Token Response (access_token, token_type, expires_in, c_nonce, c_nonce_expires_in)16create proof of possession (c_nonce)17create DPoP proof for PID Provider credential endpoint18Credential Request with DPoP access_token and DPoP proof (credential_definition, format, proof)Register all the credential-relatedinformation for verification/revocation19Credential Response (format, credential, c_nonce, c_nonce_expires_in)20PID validity and status check21store credential \ No newline at end of file diff --git a/requirements-dev.txt b/requirements-dev.txt index 5119c87f9..76f8ae99e 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -25,4 +25,4 @@ sphinxcontrib-htmlhelp==2.0.0 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==1.0.3 sphinxcontrib-serializinghtml==1.1.5 -urllib3==1.26.9 +urllib3==1.26.18