From 119cbadcc9aad716d971df2297f908d5d92c0eef Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Wed, 3 Jan 2024 16:39:40 +0100 Subject: [PATCH 1/4] fix!: OpenID4VCI Draft 13 (#175) * fix: Defined terms and editorial on issuance introduction * Issuance: detailed flow up to the federation discovery * fix: issuance according to OpenID4VCI Draft 13 * fix!: issuance - credential_supported schema * fix: issuance - request object reordiering members * fix!: issuance - authorization_servers in the metadata - Closes https://github.com/italia/eudi-wallet-it-docs/issues/148 * chore: issuance - added proof_types_supported in the metadata * fix: issuance - metadata - proof types mandatory - according to https://github.com/openid/OpenID4VCI/pull/87/files * fix: remove NRA * editorials: OpenID Connect Core 1.0 or SAML2 * fix: WIA~POP removed from token endpoint * fix: WIA~POP removed from token endpoint * fix: credential_definition.type is an ARRAY * fix: editorial on vci metadata * Apply suggestions from code review * Apply suggestions from code review * Apply suggestions from code review with Amir Co-authored-by: asharif1990 <35602900+asharif1990@users.noreply.github.com> * fix!: alignments according to breaking changes introduced by openid4vci I-D * fix!: alignments according to breaking changes introduced by openid4vci I-D - ff * Apply suggestions from code review Co-authored-by: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: asharif1990 <35602900+asharif1990@users.noreply.github.com> Co-authored-by: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> --------- Co-authored-by: asharif1990 <35602900+asharif1990@users.noreply.github.com> Co-authored-by: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> --- docs/en/defined-terms.rst | 11 +- docs/en/pid-eaa-issuance.rst | 369 ++++++++++++++++++----------------- 2 files changed, 199 insertions(+), 181 deletions(-) diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst index f1f5927dc..a6004323c 100644 --- a/docs/en/defined-terms.rst +++ b/docs/en/defined-terms.rst @@ -29,6 +29,8 @@ Below are the description of acronyms and definitions which are useful for furth - An entity, recognized and accredited by the State, responsible for identifying citizens for the issuance of an Electronic Identity Certificate. * - Electronic Attestation of Identity - Electronic attestation of attributes referring to master data already present in Italian digital identity systems. + * - Digital Credential + - An signed Credential whose integrity can be cryptographically verified using the public keys of its Issuer. It is also known as Credential. * - Federation Authority - A public governance entity that issues guidelines and technical rules, and administers - directly or through its intermediary - Trusted Lists, services, and accreditation processes, the status of participants, and their eligibility evaluation. It also performs oversight functions. * - Wallet Instance @@ -37,7 +39,7 @@ Below are the description of acronyms and definitions which are useful for furth - All public and/or private entities, conforming to a technical profile and accredited by the Federation Authority, that provide citizens with an IT Wallet Instance. * - Wallet Attestation - Verifiable Attestation, issued by the Wallet Provider, that proves the security compliace of the Wallet Instance. - * - App Attestation Service + * - Wallet Attestation Service - Device manufacturer service that allows you to certify the authenticity of the mobile app (Wallet Instance). * - Qualified Electronic Attestation of Attributes (QEAA) - A digitally verifiable attestation in electronic form, issued by a QTSP, that substantiates a person's possession of attributes. @@ -45,12 +47,16 @@ Below are the description of acronyms and definitions which are useful for furth - The Electronic Trust Service Provider responsible for the issuing of Qualified Electronic Signature certificates to the User. * - Relying Party - A natural or legal person that implements an authentication system requiring electronic attribute attestation submissions as an authentication mechanism. + * - Verifier + - See Relying Party. * - Trust Attestation - Electronic attestation of an entity's compliance with the national regulatory framework, which is cryptographically verifiable and cannot be repudiated over time by the entity that issued it. A Trust Attestation is always related to a particular Trust Framework. * - Trust Layer - An architectural component that enables IT Wallet system participants to establish trust, in terms of reliability and compliance of all participants with the regulatory framework governing the digital identity system. + * - Trust Model + - System defining how the participants of the ecosystem establish and maintain trust in their interactions. The Trust Model outlines the rules and the procedures for the entities (like users, systems, or applications) should validate each other's identities, authenticate, and establish the level of trust before exchanging information. * - Level of Assurance - - The degree of confidence in the vetting process used to establish the identity of the User and the degree of confidence that the User who presents the credential is the same User to whom the credential was issued. + - The degree of confidence in the vetting process used to establish the identity of the User and the degree of confidence that the User who presents the credential is the same User to whom the Digital Credential was issued. * - Holder Key Binding - Ability of the Holder to prove legitimate possession of the private part, related to the public part attested by a Trusted Third Party. @@ -75,4 +81,3 @@ Acronyms - Application Programming Interface * - **LoA** - Level of Assurance - diff --git a/docs/en/pid-eaa-issuance.rst b/docs/en/pid-eaa-issuance.rst index fd78e05b6..8843b25af 100644 --- a/docs/en/pid-eaa-issuance.rst +++ b/docs/en/pid-eaa-issuance.rst @@ -5,27 +5,26 @@ PID/(Q)EAA Issuance +++++++++++++++++++ -This section describes the PID and (Q)EAAs issuance flow with an high level of security. +This section describes the PID and (Q)EAAs issuance flow with an high level of security. The relevant entities and interfaces involved in the issuance flow are: - - *Wallet Provider*: The entity responsible for releasing an EUDI Wallet Solution. It also issues Wallet Attestations to its Wallet Instances through an Attestation Service. The Wallet Attestation certifies the genuinity and authenticity of the Wallet Instance and its compliance with a Trust Framework in compliance to the security and privacy requirements. - - *Wallet Solution*: Entire product and service owned by a Wallet Provider, offered to all the Users of that solution. The Wallet Solution is certified as EUDI-compliant by a Conformity Assessment Body (CAB). - - *Wallet Instance*: Instance of a Wallet Solution, installed on the User device. It provides interfaces for User interaction with the Wallet Provider, Relying Parties, PID, and (Q)EAA Providers. + - *Wallet Provider*: The entity responsible for releasing an EUDI Wallet Solution. The Wallet Provider issues the Wallet Attestations to its Wallet Instances through an Attestation Service. The Wallet Attestation certifies the genuinity and authenticity of the Wallet Instance and its compliance with the security and privacy requirements. + - *Wallet Solution*: Entire product and service owned by a Wallet Provider, offered to all the Users and certified as EUDI-compliant by a Conformity Assessment Body (CAB). + - *Wallet Instance*: Instance of a Wallet Solution, installed on the User device. The Wallet Instance provides graphical interfaces for User interaction with Relying Parties, PID, (Q)EAA Providers and the Wallet Provider. - *PID Provider*: The entity that issues the eIDAS Person Identification Data (PID). It is composed of: - - OpenID4VCI Component: based on the "OpenID for Verifiable Credential Issuance" specification `[OIDC4VCI. Draft 13] `_ to release PID credentials. - - National eID Relying Party (OpenID Connect or SAML2): It represents the component to authenticate the User with the national Digital Identity Providers. - - National Identity Provider: It represents preexisting identity systems based on SAML2 or OpenID Connect, already in production in each Member State (for Italy SPID and CIE id authentication schemed notified eIDAS with *LoA* **High**, see `SPID/CIE OpenID Connect Specifications `_). - + - OpenID4VCI Component: based on the "OpenID for Verifiable Credential Issuance" specification ` [OIDC4VCI. Draft 13] `_ to release the PID. + - National eID Relying Party: The component to authenticate the User with the national Digital Identity Providers, based on OpenID Connect Core 1.0 or SAML2. + - National Identity Provider: It represents preexisting identity systems based on SAML2 or OpenID Connect Core 1.0, already in production in each Member State (eg: the Italian SPID and CIE id schemes notified eIDAS with *LoA* **High**, see `SPID/CIE OpenID Connect Specifications `_). + - *(Q)EAA Provider*: It represents the Issuer of (Q)EAAs. It is composed of: - - OpenID4VCI Component: based on the "OpenID for Verifiable Credential Issuance" specification `[OIDC4VCI. Draft 13] `_ to release (Q)EAAs. - - Relying Party: It represents the component to authenticate the User with the PID. The (Q)EAA Provider acts as a Verifier and it sends a presentation request to the Wallet Instance according to [`OpenID4VP`_]. The Wallet Instance MUST have a valid PID obtained prior to starting a transaction with the (Q)EAA Provider. - + - OpenID4VCI Component: based on the "OpenID for Verifiable Credential Issuance" specification to release (Q)EAAs. + - Relying Party: Component to authenticate the User with the PID. The (Q)EAA Provider acts as a Verifier by sending a presentation request to the Wallet Instance, according to [`OpenID4VP`_]. The Wallet Instance MUST have a valid PID, obtained in a previous time, to get authenticated with the (Q)EAA Provider. High-Level PID flow ------------------- - + The :numref:`fig_High-Level-Flow-ITWallet-PID-Issuance` shows a general architecture and highlights the main operations involved in the issuance of a PID. .. _fig_High-Level-Flow-ITWallet-PID-Issuance: @@ -33,18 +32,18 @@ The :numref:`fig_High-Level-Flow-ITWallet-PID-Issuance` shows a general architec :figwidth: 100% :align: center - PID Issuance - General architecture and high level flow + PID Issuance - General architecture and high level flow. -Below a detailed description for each step represented in the previous picture: +Below the description of the steps represented in the previous picture: - 0. **Wallet Instance Setup**: the first time the Wallet Instance is started a preliminary setup phase MUST be carried out. It consists of the release of a verifiable proof issued by the Attestation Service provided by the Wallet Provider that asserts the genuineness, the authenticity and the compliance with a trust framework of the Wallet Instance. The verifiable proof binds a public key corresponding to a local private key generated by the Wallet Instance. - 1. **Obtaining the trusted PID Provider**: the Wallet Instance discovers the trusted PID Provider using the Federation API (e.g.: using the Subordinate Listing Endpoint of the Trust Anchor and its Intermediates), and then inspects the metadata looking for the availability of the PID credential. - 2. **Obtaining of PID Provider Metadata**: the Wallet Instance establishes the trust to the PID Provider according to the Trust Model, obtaining the Metadata that discloses the formats of the PID, the algorithms supported, and any other parameter required for interoperability needs. - 3. **PID Request**: following the Authorization Code Flow in `[OIDC4VCI. Draft 13] `_ the Wallet Instance requests a PID to the PID Provider. A fresh key pair that is generated by the Wallet Instance for the purpose of the sender-constrained Access Token will be used by the PID Provider for the Holder Key Binding of the PID. - 4. **User Authentication**: the PID Provider authenticates the User with LoA High, acting as an IAM Proxy to the National eID system. - 5. **PID Issuance**: once the User authentication with LoA High happens, the User gives their consent, and the PID Provider releases a PID bound to the key material held by the requesting Wallet Instance. + 0. **Wallet Instance Setup**: the first time the Wallet Instance is started a preliminary setup phase is carried out. It consists of the release of the Wallet Attestation issued by Wallet Attestation Service asserting the genuineness and the compliance of the Wallet Instance with the shared trust framework. The Wallet Attestation binds the public key provided by the Wallet Instance, related to one of the private keys generated by the Wallet Instance. + 1. **PID/(Q)EAA Provider Discovery**: the Wallet Instance discovers the trusted Digital Credential Issuers using the Federation API (e.g.: using the Subordinate Listing Endpoint of the Trust Anchor and its Intermediates), inspecting the Credential Issuer metadata and Trust Marks for filtering the PID Provider. + 2. **PID Provider Metadata**: the Wallet Instance establishes the trust to the PID Provider according to the Trust Model and obtains the Metadata that discloses the formats of the PID, the algorithms supported, and any other parameter required for interoperability needs. + 3. **PID Request**: using the Authorization Code Flow defined in `[OIDC4VCI. Draft 13] `_ the Wallet Instance requests the PID to the PID Provider. + 4. **User Authentication**: the PID Provider authenticates the User with LoA High, acting as an Identity and Access Management Proxy to the National eID system. + 5. **PID Issuance**: the User is authenticated with LoA High and the PID Provider releases a PID bound to the key material held by the requesting Wallet Instance. -In the following sections the steps from 1 to 5 are further expanded into more technical details. +In the following sections the steps from 1 to 5 are further expanded into more technical details. High-Level (Q)EAA flow ---------------------- @@ -63,20 +62,25 @@ The :numref:`fig_High-Level-Flow-ITWallet-QEAA-Issuance` shows a general archite Below the description of the most relevant operations involved in the (Q)EAA issuance: - 1. **Obtaining the trusted (Q)EAA Issuer**: the Wallet Instance discovers the trusted (Q)EAA Issuer ufing the Federaiton API (e.g.: using the Subordinate Listing Endpoint of the Trust Anchor and its Intermediates), then inspects the metadata looking for the credential capabilities. - 2. **Obtaining of (Q)EAA Provider Metadata**: the Wallet Instance establishes the trust to the (Q)EAA Provider according to the Trust Model, obtaining the Metadata that discloses the formats of the (Q)EAA, the algorithms supported, and any other parameter required for interoperability needs. - 3. **(Q)EAA Request**: according to the Authorization Code Flow in `[OIDC4VCI. Draft 13] `_ the Wallet Instance requests a (Q)EAA to the (Q)EAA Provider. A fresh key pair that is generated by the Wallet Instance for the sender-constrained Access Token TO be used by (Q)EAA Provider for the key binding of the (Q)EAA. The (Q)EAA Provider checks the Wallet Instance by means of the Wallet Attestation and the Trust Chain related to the Wallet Provider. - 4. **User Authentication**: the (Q)EAA Provider, acting as a Verifier (Relying Party), authenticates the User evaluating the presentation of the PID. - 5. **(Q)EAA Issuance**: Once the User has been authenticated with a valid PID, the User gives their consent, then the (Q)EAA Provider releases a (Q)EAA bound to the key material held by the requesting Wallet Instance. + 1. **Discovery of the trusted (Q)EAA Provider**: the Wallet Instance obtains the list of the trusted (Q)EAA Provider using the Federation API (e.g.: using the Subordinate Listing Endpoint of the Trust Anchor and its Intermediates), then inspects the metadata and Trust Mark looking for the Digital Credential capabilities of each (Q)EAA Provider. + 2. **(Q)EAA Provider Metadata**: the Wallet Instance establishes the trust to the (Q)EAA Provider according to the Trust Model, obtaining the Metadata that discloses the formats of the (Q)EAA, the algorithms supported, and any other parameter required for interoperability needs. + 3. **(Q)EAA Request**: using the Authorization Code Flow , defined in `[OIDC4VCI. Draft 13] `_, the Wallet Instance requests a (Q)EAA to the (Q)EAA Provider. + 4. **User Authentication**: the (Q)EAA Provider, acting as a Verifier (Relying Party), authenticates the User evaluating the presentation of the PID. + 5. **(Q)EAA Issuance**: the User is authenticated with a valid PID and the (Q)EAA Provider releases a (Q)EAA bound to the key material held by the requesting Wallet Instance. Detailed Flow ------------- -The PID/(Q)EAA Issuance phase is based on the **Authorization Code Flow** with **Pushed Authorization Requests** (PAR) [:rfc:`9126`] and **PKCE** (Proof Key for Code Exchange, :rfc:`7636`) as recommended in `[OIDC4VCI. Draft 13. Section 3.4] `_. A *Wallet Initiated Flow* is involved and the User receives the PID/(Q)EAA directly in response to the Credential Request (*Immediate Flow*). +The PID/(Q)EAA Issuance phase uses the **Authorization Code Flow** with the following specifications: + +* **Pushed Authorization Requests** (PAR) [:rfc:`9126`]; +* **PKCE** (Proof Key for Code Exchange, :rfc:`7636`) as recommended in `[OIDC4VCI. Draft 13. Section 3.4] `_. + +In this section a *Wallet Initiated Flow* is outlined, where the User receives the PID/(Q)EAA directly in response to the Credential Request. .. warning:: - + All the non-normative examples are referred to the PID Provider issuance flow. .. _fig_Low-Level-Flow-ITWallet-PID-QEAA-Issuance: @@ -85,36 +89,36 @@ The PID/(Q)EAA Issuance phase is based on the **Authorization Code Flow** with * :figwidth: 100% :align: center :target: https://www.plantuml.com/plantuml/svg/bLJVRzis47xdNt587vO0DlPke4MTn6kC5OEHfSXB086HplOj4gcHnwZUm_xs7KLPfkQqQ8C0KSZxyNtVVSUFdhNZqDHA1xOcDC_eb6hbZ4fgjM6u-EBHNO3s49Hwjb_JmIyUV2DHxTuQl81tdsctv-iwu3JtsjbkJDVJkqTTryYmDWB1bDZ7T0fD1TBbVnWswrlOEFjArL2CbFnqCFy0OG7scJKPEDZWG29LWBbST0iue5VA6Si8zXKTTF3kyMxzi5931kyHQl8CTjj_FxZW6Il8s_a8gQyX3USVf5rfpPPSqsTuhB5aiYQMoDEK2W92CDYNAOGPYLhhJtSFd-vNgp_KpHxBbqaca0SXFuBw3ULGzpsqgOvaYJqqoBhIh7E449c3W7Ie6M7p-yrA05S8qfosXAulyhXUpZTsCyIJn6-Mzt2FVmVq39TF1i2XRwtnMF2XnLayAMj2mmLLwJyfMfJxE4IpmpUE2e6tjodOfSfv6UqzkiXgsY2_UIym_nsWFfaho7LyIyNag1yHSaZmj3EQWyCXv5XXoOoUJvf7iLzrJHNn0JAr5IMdZVeboU1ou5i4HpF0hoqvz0MPgsJQw5gzW6KGVHpza_gCufzaXgpCbGgwpwIVJbGJtMRXk0J1HpT8BScYCXNhYFU0wzlbdt0dAzspBoCdm-Uy1T4Pc562Q8OPH1Nb3ta_4kX-9Ybpz0vD71_2hTW1Nl3mpRlMMRlDVGvRwwOxnlO53GYZrf9GonRXGMv6KPCUMT7ByqNOEMquCx6jicquRjstdVy-EBCWvEr2lAeRlx1n98iKEnzZvp5syLV7y-FDoQDI_BkxCwnWHGxBtXDFqOcKn4kCyo7eiaJlYrwYML8gqSkSF8EoCDQKE7uKcStFtw6adlosrdkf7iT-EMJsuTFuNFApsKb85Ishwt60sVnkJhVdGyofzGR9HtkgMrIu9KEzjh5_etcMegxUUeEkFtzPgNlSaUUuKNKTtv8CvjnXBQGgK6HIDIdSyqhsIBltgyDNcpuXVsI6EUNCic4DwB9kFpmQ4VNqgaKnefs2XpA-ZLcSP-joEkgZW0jD_Hy0 - + PID/(Q)EAA Issuance - Detailed flow -**Steps 1-4 (Discovery):** The User selects the PID/(Q)EAA Provider, and the Wallet Instance obtains the Metadata for the selected PID/(Q)EAA Provider. +**Steps 1-4 (Discovery):** The User selects the PID/(Q)EAA Provider using the Wallet Instance, the Metadata for the selected PID/(Q)EAA Provider are processed by the Wallet Instance. .. note:: - **Federation Check:** The Wallet Instance needs to check if the PID/(Q)EAA Provider is part of the Federation, obtaining then its protocol specific Metadata. A non-normative example of a response from the endpoint **.well-known/openid-federation** with the **Entity Configuration** and the **Metadata** of the PID/(Q)EAA Provider is represented within the section `Entity Configuration Credential Issuer`_. + **Federation Check:** The Wallet Instance needs to check if the PID/(Q)EAA Provider is part of the Federation, obtaining its protocol specific Metadata. A non-normative example of a response from the endpoint **.well-known/openid-federation** with the **Entity Configuration** and the **Metadata** of the PID/(Q)EAA Provider is represented within the section `Entity Configuration Credential Issuer`_. **Steps 5-6 (PAR Request):** The Wallet Instance: - * creates a fresh PKCE code verifier, Wallet Attestation Proof of Possession, and ``state`` parameter for the *Pushed Authorization Request*. - * provides to the PID/(Q)EAA Provider PAR endpoint the parameters previously listed above, using the ``request`` parameter (hereafter Request Object) according to :rfc:`9126` Section 3 to prevent Request URI swapping attack. - * MUST create the ``code_verifier`` with enough entropy random string using the unreserved characters with a minimum length of 43 characters and a maximum length of 128 characters, making it impractical for an attacker to guess its value. The value MUST be generated following the recommendation in Section 4.1 of :rfc:`7636`. - * signs this request using the private key that is created during the setup phase to obtain the Wallet Attestation. The related public key that is attested by the Wallet Provider is provided within the Wallet Attestation ``cnf`` claim. - * MUST create the value of the ``client_assertion`` parameter according to OAuth 2.0 Attestation-based Client Authentication [`oauth-attestation-draft `_], since in this flow the Pushed Authorization Endpoint is a protected endpoint. The ``client_assertion`` value MUST NOT contain more or less than precisely two JWTs separated with the ``~`` character. The first JWT MUST be the Wallet Attestation JWT and the second JWT MUST be the Wallet Attestation Proof of Possession. - * specifies the types of the requested credentials using the ``authorization_details`` [RAR :rfc:`9396`] parameter. + * creates a fresh PKCE code verifier, Wallet Attestation Proof of Possession, and ``state`` parameter for the *Pushed Authorization Request*. + * provides to the PID/(Q)EAA Provider PAR endpoint the parameters previously listed above, using the ``request`` parameter (hereafter Request Object) according to :rfc:`9126` Section 3 to prevent Request URI swapping attack. + * MUST create the ``code_verifier`` with enough entropy random string using the unreserved characters with a minimum length of 43 characters and a maximum length of 128 characters, making it impractical for an attacker to guess its value. The value MUST be generated following the recommendation in Section 4.1 of :rfc:`7636`. + * signs this request using the private key that is created during the setup phase to obtain the Wallet Attestation. The related public key that is attested by the Wallet Provider is provided within the Wallet Attestation ``cnf`` claim. + * MUST create the value of the ``client_assertion`` parameter according to OAuth 2.0 Attestation-based Client Authentication [`oauth-attestation-draft `_], since in this flow the Pushed Authorization Endpoint is a protected endpoint. The ``client_assertion`` value MUST NOT contain more or less than precisely two JWTs separated with the ``~`` character. The first JWT MUST be the Wallet Attestation JWT and the second JWT MUST be the Wallet Attestation Proof of Possession. + * specifies the types of the requested credentials using the ``authorization_details`` [RAR :rfc:`9396`] parameter. The PID/(Q)EAA Provider performs the following checks upon the receipt of the PAR request: - - 1. It MUST validate the signature of the Request Object using the algorithm specified in the ``alg`` header parameter (:rfc:`9126`, :rfc:`9101`) and the public key that can be retrieved from the Wallet Attestation (``cnf``) identified using the ``kid`` header of the Request Object. - 2. It MUST check that the used algorithm for signing the request in the ``alg`` header is among the appropriate once reported in Section `Cryptographic Algorithms `_. - 3. It MUST check that the ``client_id`` in the request body of the PAR request matches the ``client_id`` claim in the Request Object. + + 1. It MUST validate the signature of the Request Object using the algorithm specified in the ``alg`` header parameter (:rfc:`9126`, :rfc:`9101`) and the public key retrieved from the Wallet Attestation (``cnf.jwk``) referenced in the Request Object, using the ``kid`` JWS header parameter. + 2. It MUST check that the used algorithm for signing the request in the ``alg`` header is one of the listed within the Section `Cryptographic Algorithms `_. + 3. It MUST check that the ``client_id`` in the request body of the PAR request matches the ``client_id`` claim included in the Request Object. 4. It MUST check that the ``iss`` claim in the Request Object matches the ``client_id`` claim in the Request Object (:rfc:`9126`, :rfc:`9101`). - 5. It MUST check that the ``aud`` claim in the Request Object is equal to the identifier of PID/(Q)EAA Provider (:rfc:`9126`, :rfc:`9101`). + 5. It MUST check that the ``aud`` claim in the Request Object is equal to the PID/(Q)EAA Provider authorization endpoint uri (:rfc:`9126`, :rfc:`9101`). 6. It MUST reject the PAR request, if it contains the ``request_uri`` parameter (:rfc:`9126`). - 7. It MUST check that the Request Object contains all the mandatory parameters and their values are validated according to what we defined in :ref:`Table of the HTTP parameters ` [derived from :rfc:`9126`]. - 8. It MUST check that the Request Object is not expired by checking the ``exp`` claim (:rfc:`9126`). - 9. It MUST check that the Request Object was issued at a time acceptable by the PID/(Q)EAA Provider by checking the ``iat`` claim. For example, basing on the security policies of the PID/(Q)EAA Provider, it might reject the request if the ``iat`` claim is too far away from the current time (:rfc:`9126`). + 7. It MUST check that the Request Object contains all the mandatory parameters which values are validated according to :ref:`Table of the HTTP parameters ` [derived from :rfc:`9126`]. + 8. It MUST check that the Request Object is not expired, checking the ``exp`` claim (:rfc:`9126`). + 9. It MUST check that the Request Object was issued in a previous time than the value exposed in the ``iat`` claim. It SHOULD reject the request if the ``iat`` claim is far from the current time (:rfc:`9126`) of more than `5` minutes. 10. It MUST check that the ``jti`` claim in the Request Object has not been used before by the Wallet Instance identified by the ``client_id``. This allows the PID/(Q)EAA Provider to mitigate replay attacks (:rfc:`7519`). 11. It MUST validate the ``client_assertion`` parameter based on Sections 4.1 and 4.2 of [`oauth-attestation-draft `_]. @@ -125,20 +129,20 @@ Below a non-normative example of the PAR. POST /as/par HTTP/1.1 Host: pid-provider.example.org Content-Type: application/x-www-form-urlencoded - + response_type=code &client_id=$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$ &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM &code_challenge_method=S256 &request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KIC Jpc3MiOiAiczZCaGRSa3F0MyIsDQogImF1ZCI6ICJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbSIsDQo gInJlc3BvbnNlX3R5cGUiOiAiY29kZSBpZF90b2tlbiIsDQogImNsaWVudF9pZCI6ICJzNkJoZFJrcXQz IiwNCiAicmVkaXJlY3RfdXJpIjogImh0dHBzOi8vY2xpZW50LmV4YW1... &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation - &client_assertion=$WIA~WIA-PoP + &client_assertion=$WIA~WIA-PoP -An example of Wallet Attestation Proof of Possession is as the following: +Below an non-normative example of the Wallet Attestation Proof of Possession without encoding and signature applied: -.. code-block:: +.. code-block:: - { + { "alg": "ES256", "kid": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c", "typ": "jwt-client-attestation-pop", @@ -146,13 +150,13 @@ An example of Wallet Attestation Proof of Possession is as the following: . { "iss": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c", - "aud": "https://pid-provider.example.org", + "aud": "https://pid-provider.example.org/par-endpoint", "jti": "ad25868c-8377-479b-8094-46fb1e797625", "iat": 1686645115, "exp": 1686652315 } -The JWS of Request Object is represented below: +Below an non-normative example of the signed Request Object without encoding and signature applied: .. code-block:: @@ -173,13 +177,10 @@ The JWS of Request Object is represented below: "code_challenge":"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "code_challenge_method":"S256", "authorization_details":[ - { - "type":"openid_credential", - "format": "vc+sd-jwt", - "credential_definition": { - "type": "PersonIdentificationData" - } - } + { + "type": "openid_credential", + "credential_configuration_id": "PersonIdentificationData" + } ], "redirect_uri":"eudiw://start.wallet.example.org", } @@ -187,22 +188,30 @@ The JWS of Request Object is represented below: .. note:: - **Federation Check:** The PID/(Q)EAA Provider MUST check that the Wallet Provider is part of the federation and in addition it MUST verify the Wallet Attestation validity by checking its signature and data. + **Federation Check:** The PID/(Q)EAA Provider MUST check that the Wallet Provider is part of the federation. + + +.. note:: + The PID/(Q)EAA Provider MUST validate the signature of the the Wallet Attestation and that it is not expired. + + +**Step 7 (PAR Response):** The PID/(Q)EAA Provider provides a one-time use ``request_uri`` value. The issued ``request_uri`` value must be bound to the client identifier (``client_id``) that was provided in the Request Object. + +.. note:: + The entropy of the ``request_uri`` MUST be sufficiently large. The adequate shortness of the validity and the entropy of the ``request_uri`` depends on the risk calculation based on the value of the resource being protected. The validity time SHOULD be less than a minute, and the ``request_uri`` MUST include a cryptographic random value of 128 bits or more (:rfc:`9101`). The entire ``request_uri`` SHOULD NOT exceed 512 ASCII characters due to the following two main reasons (:rfc:`9101`): -**Step 7 (PAR Response):** The PID/(Q)EAA Provider MUST issue the ``request_uri`` one-time use and bind it to the client identifier (``client_id``) that is provided in the Request Object. Furthermore, the entropy of the ``request_uri`` MUST be sufficiently large. The adequate shortness of the validity and the entropy of the ``request_uri`` depends on the risk calculation based on the value of the resource being protected. The validity time SHOULD be less than a minute, and the ``request_uri`` MUST include a cryptographic random value of 128 bits or more (:rfc:`9101`). The entire ``request_uri`` SHOULD NOT exceed 512 ASCII characters due to the following two main reasons (:rfc:`9101`): + 1. Many phones on the market still do not accept large payloads. The restriction is typically either 512 or 1024 ASCII characters. + 2. On a slow connection such as a 2G mobile connection, a large URL would cause a slow response; therefore, the use of such is not advisable from the user-experience point of view. - 1. Many phones on the market still do not accept large payloads. The restriction is typically either 512 or 1024 ASCII characters. - 2. On a slow connection such as a 2G mobile connection, a large URL would cause a slow response; therefore, the use of such is not advisable from the user-experience point of view. - - The PID/(Q)EAA Provider returns the issued ``request_uri`` to the Wallet Instance. +The PID/(Q)EAA Provider returns the issued ``request_uri`` to the Wallet Instance. A non-normative example of the response is shown below. .. code-block:: http HTTP/1.1 201 Created Cache-Control: no-cache, no-store Content-Type: application/json - + { "request_uri":"urn:ietf:params:oauth:request_uri:bwc4JK-ESC0w8acc191e-Y1LTC2", "expires_in": 60 @@ -213,19 +222,19 @@ The JWS of Request Object is represented below: 1. It MUST treat ``request_uri`` values as one-time use and MUST reject an expired request. However, it MAY allow for duplicate requests due to a user reloading/refreshing their user-agent (derived from :rfc:`9126`). 2. It MUST identify the request as a result of the submitted PAR (derived from :rfc:`9126`). - 3. It MUST reject all the Authorization Requests that do not contain the ``request_uri`` parameter as the PAR is the only way to pass the Authorization Request from the Wallet Instance (derived from :rfc:`9126`). + 3. It MUST reject all the Authorization Requests that do not contain the ``request_uri`` parameter as the PAR is the only way to pass the Authorization Request from the Wallet Instance (derived from :rfc:`9126`). .. code-block:: http GET /authorize?client_id=$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$&request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3Abwc4JK-ESC0w8acc191e-Y1LTC2 HTTP/1.1 Host: pid-provider.example.org - + .. note:: - **User Authentication and Consent:** The PID Provider performs the User authentication based on the requirements of eIDAS LoA High by means of national notified eIDAS scheme and requires the User consent for the PID issuance. - The (Q)EAA Provider performs the User authentication requesting a valid PID to the Wallet Instance. The (Q)EAA Provider MUST use [`OpenID4VP`_] to dynamically request the presentation of the PID. From a protocol perspective, the (Q)EAA Provider then acts as a Relying Party and provide the presentation request to the Wallet Instance. The Wallet Instance MUST have a valid PID obtained prior to start the transaction with the (Q)EAA Provider. + **User Authentication and Consent:** The PID Provider performs the User authentication based on the requirements of eIDAS LoA High by means of national notified eIDAS scheme and requires the User consent for the PID issuance. + The (Q)EAA Provider performs the User authentication requesting a valid PID to the Wallet Instance. The (Q)EAA Provider MUST use [`OpenID4VP`_] to dynamically request the presentation of the PID. From a protocol perspective, the (Q)EAA Provider acts as a Relying Party, providing the presentation request to the Wallet Instance. The Wallet Instance MUST have a valid PID obtained prior to start the transaction with the (Q)EAA Provider. **Steps 10-11 (Authorization Response):** The PID/(Q)EAA Provider sends an authorization ``code`` together with ``state`` and ``iss`` parameters to the Wallet Instance. The Wallet Instance performs the following checks on the Authorization Response: @@ -237,22 +246,21 @@ The JWS of Request Object is represented below: .. note:: The Wallet Instance redirect URI is a universal or app link registered with the local operating system, so this latter will resolve it and pass the response to the Wallet Instance. - + .. code-block:: http HTTP/1.1 302 Found - Location: eudiw://start.wallet.example.org?code=SplxlOBeZQQYbYS6WxSbIA&state=fyZiOL9Lf2CeKuNT2JzxiLRDink0uPcd&iss=https%3A%2F%2Fpid-provider.example.org + Location: https://start.wallet.example.org?code=SplxlOBeZQQYbYS6WxSbIA&state=fyZiOL9Lf2CeKuNT2JzxiLRDink0uPcd&iss=https%3A%2F%2Fpid-provider.example.org -**Steps 12-13 (DPoP Proof for Token Endpoint)**: The Wallet Instance MUST create a new key pair for the DPoP and a fresh DPoP Proof JWT following the instruction provided in Section 4 of (:rfc:`9449`) for the token request to the PID/(Q)EAA Provider. The DPoP Proof JWT is signed using the created private key for DPoP by Wallet Instance. DPoP provides a way to bind the Access Token to a certain sender (Wallet Instance) (:rfc:`9449`). This mitigates the misuse of leaked or stolen Access Tokens at the Credential Endpoint of PID/(Q)EAA Issuer as the attacker needs to present a valid DPoP Proof JWT. +**Steps 12-13 (DPoP Proof for Token Endpoint)**: The Wallet Instance MUST create a new key pair for the DPoP and a fresh DPoP Proof JWT following the instruction provided in Section 4 of (:rfc:`9449`) for the token request to the PID/(Q)EAA Provider. The DPoP Proof JWT is signed using the private key for DPoP created by Wallet Instance for this scope. DPoP binds the Access Token to a certain Wallet Instance (:rfc:`9449`) and mitigates the misuse of leaked or stolen Access Tokens at the Credential Endpoint. -**Step 14 (Token Request):** The Wallet Instance sends a token request to the PID/(Q)EAA Provider Token Endpoint using the authorization ``code``, ``code_verifier``, *DPoP Proof JWT* and OAuth 2.0 Attestation based Client Authentication parameters (``client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation`` and ``client_assertion=WIA~WIA-PoP``). +**Step 14 (Token Request):** The Wallet Instance sends a token request to the PID/(Q)EAA Provider Token Endpoint with a *DPoP Proof JWT* and the parameters: ``code``, ``code_verifier``, and OAuth 2.0 Attestation based Client Authentication (``client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation`` and ``client_assertion=WIA~WIA-PoP``). The ``client_assertion`` is signed using the private key that is created during the setup phase to obtain the Wallet Attestation. The related public key that is attested by the Wallet Provider is provided within the Wallet Attestation (``cnf`` claim). The PID/(Q)EAA Provider performs the following checks on the Token Request: - 1. It MUST authenticate the Wallet Instance based on the OAuth 2.0 Attestation based Client Authentication method `oauth-attestation-draft `_. - 2. It MUST ensure that the Authorization ``code`` is issued to the authenticated Wallet Instance (:rfc:`6749`). - 3. It MUST ensure the Authorization ``code`` is valid and has not been previously used (:rfc:`6749`). - 4. It MUST ensure the ``redirect_uri`` is identical to the value that was initially included in the Request Object `OpenID.Core#TokenRequest `_. - 5. It MUST validate the DPoP Proof JWT following the steps in Section 4.3 of (:rfc:`9449`). + 1. It MUST ensure that the Authorization ``code`` is issued to the authenticated Wallet Instance (:rfc:`6749`) and was not replied. + 2. It MUST ensure the Authorization ``code`` is valid and has not been previously used (:rfc:`6749`). + 3. It MUST ensure the ``redirect_uri`` matches the value included in the previous Request Object `OpenID.Core#TokenRequest `_. + 4. It MUST validate the DPoP Proof JWT, according to (:rfc:`9449`) Section 4.3. .. code-block:: http @@ -267,41 +275,46 @@ The ``client_assertion`` is signed using the private key that is created during WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg - client_id=$thumprint-of-the-jwk-in-the-cnf-wallet-attestation$ - &grant_type=authorization_code + grant_type=authorization_code &code=SplxlOBeZQQYbYS6WxSbIA - &redirect_uri=eudiw://start.wallet.example.org &code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk + &redirect_uri=https://start.wallet.example.org/cb &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation &client_assertion=$WIA~WIA-PoP - -**Step 15 (Token Response):** The PID/(Q)EAA Provider validates the request and if it is successful, it issues an *Access Token* (bound to the DPoP key) and a fresh ``c_nonce``. +**Step 15 (Token Response):** The PID/(Q)EAA Provider validates the request, if successful an *Access Token* (bound to the DPoP key) and a fresh ``c_nonce`` is provided to the Wallet Instance. .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store - + { - "access_token": "Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU", - "token_type": "DPoP", - "expires_in": 2677, - "c_nonce": "tZign[...]snFbp", - "c_nonce_expires_in": 86400 + "access_token": "Kz~8mXK1EalYznwH-LC-1fBAo.4Ljp~zsPE_NeO.gxU ...", + "token_type": "DPoP", + "expires_in": 2677, + "c_nonce": "tZign[...]snFbp", + "c_nonce_expires_in": 86400, + "authorization_details": [ + { + "type": "openid_credential", + "credential_configuration_id: "PersonIdentificationData" + } + } + ] } -**Steps 16-17 (DPoP Proof for Credential Endpoint):** The Wallet Instance creates a proof of possession with the DPoP key following the steps in Section 7.2.1 of `OPENID4VCI`_ and the ``c_nonce`` obtained in **Step 15** and it creates a DPoP Proof JWT based on Section 4 of (:rfc:`9449`) for the request to the PID/(Q)EAA credential issuance endpoint. The ``jwk`` value in the proof parameter MUST be equal to the public key generated for the DPoP. +**Steps 16-17 (DPoP Proof for Credential Endpoint):** The Wallet Instance for requesting the Digital Credential creates a proof of possession with ``c_nonce`` obtained in **Step 15** and using the private key used for the DPoP, signing a DPoP Proof JWT according to (:rfc:`9449`) Section 4. The ``jwk`` value in the ``proof`` parameter MUST be equal to the public key referenced in the DPoP. -**Step 18 (Credential Request):** The Wallet Instance requests a PID/(Q)EAA issuance to the PID/(Q)EAA credential endpoint. The request MUST contain the *Access Token*, the *DPoP Proof JWT*, and the *credential type*, the ``proof`` (proof of possession of the key) and the ``format`` parameters. +**Step 18 (Credential Request):** The Wallet Instance requests the Digital Credential to the PID/(Q)EAA Credential endpoint. The request MUST contain the *Access Token*, the *DPoP Proof JWT*, the *credential type*, the ``proof`` (proof of possession of the key) and the ``format`` parameters. .. note:: - **PID/(Q)EAA Credential Schema and Status registration:** The PID/(Q)EAA Provider MUST register all the issued credentials for their later revocation, if needed. + **PID/(Q)EAA Credential Schema and Status registration:** The PID/(Q)EAA Provider MUST register all the issued Credentials for their later revocation, if needed. -.. code-block:: +.. code-block:: POST /credential HTTP/1.1 Host: pid-provider.example.org @@ -327,7 +340,8 @@ The ``client_assertion`` is signed using the private key that is created during } -Where the decoded content of the ``jwt`` parameter is represented below: +Where a non-normative example of the decoded content of the ``jwt`` parameter is represented below, +without encoding and signature. The JWS header: .. code-block:: JSON @@ -343,25 +357,27 @@ Where the decoded content of the ``jwt`` parameter is represented below: } +And the JWS payload: + .. code-block:: JSON { - "iss": "0b434530-e151-4c40-98b7-74c75a5ef760", - "aud": "https://pid-provider.example.org", - "iat": 1504699136, - "nonce": "tZign...snFbp" + "iss": "0b434530-e151-4c40-98b7-74c75a5ef760", + "aud": "https://pid-provider.example.org/credential", + "iat": 1504699136, + "nonce": "tZign...snFbp" } -**Steps 19-21 (Credential Response):** The PID/(Q)EAA Provider MUST validate the *DPoP JWT Proof* based on the steps defined in Section 4.3 of (:rfc:`9449`) and whether the *Access Token* is valid and suitable for the requested PID/(Q)EAA. It also MUST validate the proof of possession for the key material the new credential SHALL be bound to following the steps in Section 7.2.2 of `OPENID4VCI`_. If all checks succeed, the PID/(Q)EAA Provider creates a new credential bound to the key material and provide it to the Wallet Instance. The Wallet Instance MUST perform the following checks before proceeding with the secure storage of the PID/(Q)EAA credential: +**Steps 19-21 (Credential Response):** The PID/(Q)EAA Provider MUST validate the *DPoP JWT Proof* based on the steps defined in Section 4.3 of (:rfc:`9449`) and whether the *Access Token* is valid and suitable for the requested PID/(Q)EAA. It also MUST validate the proof of possession for the key material the new credential SHALL be bound to, according to `OPENID4VCI`_ Section 7.2.2. If all checks succeed, the PID/(Q)EAA Provider creates a new Credential bound to the key material and provide it to the Wallet Instance. The Wallet Instance MUST perform the following checks before proceeding with the secure storage of the PID/(Q)EAA: 1. It MUST check that the PID Credential Response contains all the mandatory parameters and values are validated according to :ref:`Table of the credential response parameters `. 2. It MUST check the PID integrity by verifying the signature using the algorithm specified in the ``alg`` header parameter of SD-JWT (:ref:`PID/(Q)EAA Data Model `) and the public key that is identified using using the ``kid`` header of the SD-JWT. - 3. It MUST check that the received PID credential (in credential claim) contains all the mandatory parameters defined in :ref:`PID/(Q)EAA Data Model `. - 4. It MUST process and verify the PID that is in SD-JWT VC following the steps in Section 6 of `SD.JWT#Verification `_. + 3. It MUST check that the received PID (in credential claim) matches the schema defined in :ref:`PID/(Q)EAA Data Model `. + 4. It MUST process and verify the PID in SD-JWT VC format (according to `SD.JWT#Verification `_ Section 6.) or MDOC CBOR format. 5. It MUST verify the Trust Chain in the header of SD-JWT VC to verify that the PID Provider is trusted. -If the checks defined above are successful the Wallet Instance proceeds with the secure storage of the PID credential. +If the checks defined above are successful the Wallet Instance proceeds with the secure storage of the PID/(Q)EAA. .. code-block:: http @@ -369,12 +385,12 @@ If the checks defined above are successful the Wallet Instance proceeds with the Content-Type: application/json Cache-Control: no-store Pragma: no-cache - + { - "format": "vc+sd-jwt" - "credential" : "LUpixVCWJk0eOt4CXQe1NXK[...]WZwmhmn9OQp6YxX0a2L", - "c_nonce": "fGFF7[...]UkhLa", - "c_nonce_expires_in": 86400 + "format": "vc+sd-jwt" + "credential" : "LUpixVCWJk0eOt4CXQe1NXK[...]WZwmhmn9OQp6YxX0a2L", + "c_nonce": "fGFF7[...]UkhLa", + "c_nonce_expires_in": 86400 } Pushed Authorization Request Endpoint @@ -385,7 +401,7 @@ Pushed Authorization Request (PAR) Request The requests to the PID/(Q)EAA authorization endpoint MUST use the HTTP POST method with the parameters in the message body encoded in ``application/x-www-form-urlencoded`` format. The Pushed Authorization Endpoint is protected with OAuth 2.0 Attestation-based Client Authentication [`oauth-attestation-draft `_] and the following parameters MUST be provided: -.. _table_http_request_claim: +.. _table_http_request_claim: .. list-table:: PAR http request parameters :widths: 20 60 20 :header-rows: 1 @@ -412,12 +428,12 @@ The requests to the PID/(Q)EAA authorization endpoint MUST use the HTTP POST met - It MUST be set to ``urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation``. - `oauth-attestation-draft `_. * - **client_assertion** - - It MUST be set to a value containing the Wallet Attestation JWT and the Proof of Possession, separated with the ``~`` character. + - It MUST be set to a value containing the Wallet Attestation JWT and the Proof of Possession, separated with the ``~`` character. - `oauth-attestation-draft `_. The JWT Request Object has the following JOSE header parameters: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -429,7 +445,7 @@ The JWT Request Object has the following JOSE header parameters: - :rfc:`7516#section-4.1.1`. * - **kid** - Unique identifier of the ``jwk`` inside the ``cnf`` claim of Wallet Attestation as base64url-encoded JWK Thumbprint value. - - :rfc:`7638#section_3`. + - :rfc:`7638#section_3`. .. note:: The parameter **typ**, if omitted, assumes the implicit value **JWT**. @@ -438,7 +454,7 @@ The JWT Request Object has the following JOSE header parameters: The JWT payload is given by the following parameters: .. _table_jwt_request: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -474,10 +490,9 @@ The JWT payload is given by the following parameters: - See :ref:`Table of the HTTP parameters `. * - **authorization_details** - Array of JSON Objects. Each JSON Object MUST include the following claims: - + - **type**: it MUST be set to ``openid_credential``, - - **format**: it MUST be set to ``vc+sd-jwt``, - - **credential_definition**: JSON Object. It MUST have the **type** claim which MUST be set in accordance to the type of the requested PID/(Q)EAA that is obtained from the metadata of the PID/(Q)EAA Issuer. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData``. + - **credential_configuration_id**: JSON String. String specifying a unique identifier of the Credential being described in the `credential_configurations_supported` map in the Credential Issuer Metadata. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData``. - See [RAR :rfc:`9396`] and `[OIDC4VCI. Draft 13] `_. * - **redirect_uri** - Redirection URI to which the response is intended to be sent. It MUST be an universal or app link registered with the local operating system, so this latter will provide the response to the Wallet Instance. @@ -492,10 +507,10 @@ The JWT payload is given by the following parameters: - Unique identifier of the JWT that, together with the value contained in the ``iss`` claim, prevents the reuse of the JWT (replay attack). Since the `jti` value alone is not collision resistant, it MUST be identified uniquely together with its issuer. - [:rfc:`7519`]. -The JOSE header of the Wallet Attestation Proof of Possession MUST contain: +The JOSE header of the Wallet Attestation proof of possession MUST contain: .. _table_jwt_pop: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -507,14 +522,14 @@ The JOSE header of the Wallet Attestation Proof of Possession MUST contain: - :rfc:`7516#section-4.1.1`. * - **kid** - Unique identifier of the ``jwk`` inside the ``cnf`` claim of Wallet Attestation as base64url-encoded JWK Thumbprint value. - - :rfc:`7638#section_3`. + - :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 Attestation Proof of Possession JWT MUST contain: +The body of the Wallet Attestation proof of possession JWT MUST contain: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -545,7 +560,7 @@ Pushed Authorization Request (PAR) Response If the verification is successful, the PID/(Q)EAA Issuer MUST provide the response with a *201 HTTP status code*. The following parameters are included as top-level members in the HTTP response message body, using the ``application/json`` media type as defined in [:rfc:`8259`]. .. _table_http_response_claim: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -574,7 +589,7 @@ The Authorization request is issued by the Web Browser in use by the Wallet Inst The mandatory parameters in the HTTP authentication request are specified in the following table. -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -596,7 +611,7 @@ The authentication response is returned by the PID/(Q)EAA authorization endpoint If the authentication is successful the PID/(Q)EAA Issuer redirects the User by adding the following query parameters as required to the *redirect_uri*. The redirect URI MUST be an universal or app link registered with the local operating system, so this latter is able to provide the response to the Wallet Instance. -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -614,11 +629,10 @@ If the authentication is successful the PID/(Q)EAA Issuer redirects the User by - `OAuth 2.0 Authorization Server Issuer Identifier in Authorization Response `_, `[RFC7519, Section 4.1.1] `_. - Token endpoint -------------- -The token endpoint is used by the Wallet Instance to obtain an Access Token by presenting its authorization grant, as +The token endpoint is used by the Wallet Instance to obtain an Access Token by presenting an authorization grant, as defined in :rfc:`6749`. The Token Endpoint is a protected endpoint with a client authentication based on the model defined in OAuth 2.0 Attestation-based Client Authentication [`oauth-attestation-draft `_]. Token Request @@ -626,20 +640,17 @@ Token Request The request to the PID/(Q)EAA Token endpoint MUST be an HTTP request with method POST, with the body message encoded in ``application/x-www-form-urlencoded`` format. The Wallet Instance sends the Token endpoint request with ``client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-client-attestation`` and ``client_assertion=WIA~WIA-PoP``. -The Token endpoint MUST accept and validate the DPoP proof sent in the DPoP HTTP header. The Token endpoint MUST validate the DPoP proof according to Section 4.3 of the DPoP specifications (:rfc:`9449`). Thus, this mitigates the misuse of leaked or stolen Access Tokens at the credential endpoint. If the DPoP proof is invalid, the Token endpoint returns an error response, according to Section 5.2 of [:rfc:`6749`] with ``invalid_dpop_proof`` as the value of the error parameter. +The Token endpoint MUST accept and validate the DPoP proof sent in the DPoP HTTP header. The Token endpoint MUST validate the DPoP proof according to Section 4.3 of the DPoP specifications (:rfc:`9449`). This mitigates the misuse of leaked or stolen Access Tokens at the credential endpoint. If the DPoP proof is invalid, the Token endpoint returns an error response, according to Section 5.2 of [:rfc:`6749`] with ``invalid_dpop_proof`` as the value of the error parameter. All the parameters listed below are REQUIRED: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 * - **Claim** - **Description** - **Reference** - * - **client_id** - - It MUST be set as in the :ref:`Table of the HTTP parameters `. - - See :ref:`Table of the HTTP parameters `. * - **grant_type** - It MUST be set to ``authorization_code``. - `Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants `_. @@ -659,31 +670,31 @@ All the parameters listed below are REQUIRED: - It MUST be set to a value containing the Wallet Attestation JWT and the Proof of Possession JWT, separated with the ``~`` character (WIA~WIA-PoP). The Wallet Attestation Proof of Possession MUST contain the claims as defined in :ref:`Table of the JWT Wallet Attestation PoP `, Section :ref:`Pushed Authorization Request (PAR) Response`. - `oauth-attestation-draft `_. -A **DPoP Proof JWT** is included in an HTTP request using the ``DPoP`` header parameter containing a DPoP JWS. +A **DPoP Proof JWT** is included in the HTTP request using the ``DPoP`` header parameter containing a DPoP JWS. The JOSE header of a **DPoP JWT** MUST contain at least the following parameters: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 * - **JOSE header** - **Description** - **Reference** - * - **typ** - - It MUST be equal to ``dpop+jwt``. + * - **typ** + - It MUST be equal to ``dpop+jwt``. - [:rfc:`7515`] and [:rfc:`8725`. Section 3.11]. - * - **alg** + * - **alg** - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms in Section :ref:`Cryptographic Algorithms ` and MUST NOT be set to ``none`` or with a symmetric algorithm (MAC) identifier. - [:rfc:`7515`]. - * - **jwk** - - It represents the public key chosen by the Wallet Instance, in JSON Web Key (JWK) [:rfc:`7517`] format that the Access Token shall be bound to, as defined in Section 4.1.3 of [:rfc:`7515`]. It MUST NOT contain a private key. + * - **jwk** + - It represents the public key chosen by the Wallet Instance, in JSON Web Key (JWK) [:rfc:`7517`] format that the Access Token MUST be bound to, as defined in [:rfc:`7515`] Section 4.1.3. It MUST NOT contain a private key. - [:rfc:`7517`] and [:rfc:`7515`]. The payload of a **DPoP JWT Proof** MUST contain at least the following claims: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -700,7 +711,7 @@ The payload of a **DPoP JWT Proof** MUST contain at least the following claims: - The HTTP target URI, without query and fragment parts, of the request to which the JWT is attached. - [:rfc:`9110`. Section 7.1]. * - **iat** - - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. + - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. - [:rfc:`7519`. Section 4.1.6]. @@ -709,7 +720,7 @@ Token Response Token endpoint response MUST contain the following mandatory claims. -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -726,43 +737,44 @@ Token endpoint response MUST contain the following mandatory claims. - Expiry time of the *Access Token* in seconds. - :rfc:`6749`. * - **c_nonce** - - JSON string containing a ``nonce`` value to be used to create a *proof of possession* of key material when requesting a credential. + - JSON string containing a ``nonce`` value to be used to create a *proof of possession* of key material when requesting a Credential. - `[OIDC4VCI. Draft 13] `_. * - **c_nonce_expires_in** - JSON integer, it represents the lifetime in seconds of the **c_nonce**. - `[OIDC4VCI. Draft 13] `_. + * - **authorization_details** + - JSON object, used to identify Credentials with the same metadata but different claimset/claim values and/or simplify the Credential request even when only one Credential is being issued. + - `[OIDC4VCI. Draft 13] `_. + Access Token ^^^^^^^^^^^^ A DPoP-bound Access Token is provided by the PID/(Q)EAA Token endpoint as a result of a successful token request. The Access Token is encoded in JWT format, according to [:rfc:`7519`]. The Access Token MUST have at least the following mandatory claims and it MUST be bound to the public key that is provided by the DPoP proof. This binding can be accomplished based on the methodology defined in Section 6 of (:rfc:`9449`). -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 * - **Claim** - **Description** - **Reference** - * - **iss** + * - **iss** - It MUST be an HTTPS URL that uniquely identifies the PID/(Q)EAA Issuer. The Wallet Instance MUST verify that this value matches the PID/(Q)EAA Issuer where it has requested the credential. - [:rfc:`9068`], `[RFC7519, Section 4.1.1] `_. - * - **sub** - - It identifies the subject of the JWT. It MUST be set to the value of the ``sub`` field in the PID/(Q)EAA SD-JWT-VC. + * - **sub** + - It identifies the subject of the JWT. It MUST be set to the value of the ``sub`` field in the PID/(Q)EAA SD-JWT-VC. - [:rfc:`9068`], [:rfc:`7519`] and [`OpenID.Core#SubjectIDTypes `_]. - * - **client_id** - - As provided in the Wallet Attestation. - - [:rfc:`9068`]. - * - **aud** - - It Must be Set to the URL of Credential Endpoint of the PID/(Q)EAA Provider. + * - **aud** + - It MUST be set to the URL of Credential Endpoint of the PID/(Q)EAA Provider. - [:rfc:`9068`]. - * - **iat** - - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. + * - **iat** + - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. - [:rfc:`9068`], [:rfc:`7519`. Section 4.1.6]. * - **exp** - UNIX Timestamp with the expiry time of the JWT, coded as NumericDate as indicated in :rfc:`7519`. - [:rfc:`9068`], [:rfc:`7519`]. - * - **jti** + * - **jti** - It MUST be a String in *uuid4* format. Unique Token ID identifier that the RP MAY use to prevent reuse by rejecting the Token ID if already processed. - [:rfc:`9068`], [:rfc:`7519`]. * - **jkt** @@ -773,25 +785,25 @@ A DPoP-bound Access Token is provided by the PID/(Q)EAA Token endpoint as a resu Credential endpoint ------------------- -The Credential Endpoint issues a credential as approved by the End-User upon presentation of a valid Access Token representing this approval, as defined in `OPENID4VCI`_. +The Credential Endpoint issues a Credential upon the presentation of a valid Access Token, as defined in `OPENID4VCI`_. Credential Request ^^^^^^^^^^^^^^^^^^^ -The Wallet Instance when requests the PID/(Q)EAA to the PID/(Q)EAA Credential endpoint, MUST use the following parameters in the entity-body of the HTTP POST request, using the `application/json` media type. +The Wallet Instance when requests the PID/(Q)EAA to the PID/(Q)EAA Credential endpoint, MUST use the following parameters in the message body of the HTTP POST request, using the `application/json` media type. -The Credential endpoint MUST accept and validate the *DPoP proof* sent in the DPoP field of the Header based on the steps defined in Section 4.3 of (:rfc:`9449`). The *DPoP proof* in addition to the values that are defined in the Token Endpoint section MUST contain the following claim: +The Credential endpoint MUST accept and validate the *DPoP proof* sent in the DPoP HTTP Header parameter, according to the steps defined in (:rfc:`9449`) Section 4.3. The *DPoP proof* in addition to the values that are defined in the Token Endpoint section MUST contain the following claim: - - **ath**: hash of the Access Token. The value MUST be the result of a base64url encoding (as defined in Section 2 of :rfc:`7515`) the SHA-256 hash of the ASCII encoding of the associated Access Token's value. + - **ath**: hash value of the Access Token encoded in ASCII. The value MUST use the base64url encoding (as defined in Section 2 of :rfc:`7515`) with the SHA-256 algorithm. -If the *DPoP proof* is invalid, the Credential endpoint returns an error response per Section 5.2 of [:rfc:`6749`] with `invalid_dpop_proof` as the value of the error parameter. +If the *DPoP proof* is invalid, the Credential endpoint returns an error response per Section 5.2 of [:rfc:`6749`] with `invalid_dpop_proof` as the value of the error parameter. .. warning:: - The Wallet Instance MUST create a **new DPoP proof** for the Credential request and MUST NOT use the previously created proof for the Token Endpoint. + The Wallet Instance MUST create a **new DPoP proof** for the Credential request and MUST NOT use the previously created proof for the Token Endpoint. -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -799,16 +811,16 @@ If the *DPoP proof* is invalid, the Credential endpoint returns an error respons - **Description** - **Reference** * - **credential_definition** - - JSON object containing the detailed description of the credential type. It MUST have at least the **type** sub claims which is a JSON array containing the type values the Wallet SHALL request in the Credential Request. It MUST be set in accordance to the type of the requested PID/(Q)EAA that is obtained from the PID/(Q)EAA Issuer metadata. In the case of the PID it MUST be set to ``PersonIdentificationData``. + - JSON object containing the detailed description of the Credential type. It MUST have at least the **type** sub claims which is a JSON array containing the type values the Wallet SHALL request in the Credential Request. It MUST be set in accordance to the type of the requested PID/(Q)EAA that is obtained from the PID/(Q)EAA Issuer metadata. In the case of the PID it MUST be set to ``PersonIdentificationData``. - `[OIDC4VCI. Draft 13] `_. - * - **format** + * - **format** - Format of the Credential to be issued. This MUST be `vc+sd-jwt`. - `[OIDC4VCI. Draft 13] `_. * - **proof** - JSON object containing proof of possession of the key material the issued credential shall be bound to. The proof object MUST contain the following mandatory claims: - **proof_type**: JSON string denoting the proof type. It MUST be `jwt`. - - **jwt**: the JWT used as proof of possession. + - **jwt**: the JWT used as proof of possession. - `[OIDC4VCI. Draft 13] `_. .. note:: @@ -818,7 +830,7 @@ If the *DPoP proof* is invalid, the Credential endpoint returns an error respons The JWT proof type MUST contain the following parameters for the JOSE header and the JWT body: -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -828,14 +840,14 @@ The JWT proof type MUST contain the following parameters for the JOSE header and * - **alg** - A digital signature algorithm identifier such as per IANA "JSON Web Signature and Encryption Algorithms" registry. It MUST be one of the supported algorithms in Section :ref:`Cryptographic Algorithms ` and MUST NOT be set to ``none`` or to a symmetric algorithm (MAC) identifier. - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. - * - **typ** + * - **typ** - It MUST be set to `openid4vci-proof+jwt`. - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. - * - **jwk** - - Representing the public key chosen by the Wallet Instance, in JSON Web Key (JWK) [:rfc:`7517`] format that the PID/(Q)EAA shall be bound to, as defined in Section 4.1.3 of [:rfc:`7515`]. The ``jwk`` value MUST be equal to the same public key that is generated for the DPoP. + * - **jwk** + - Representing the public key chosen by the Wallet Instance, in JSON Web Key (JWK) [:rfc:`7517`] format that the PID/(Q)EAA shall be bound to, as defined in Section 4.1.3 of [:rfc:`7515`]. The ``jwk`` value MUST be equal to the same public key that is generated for the DPoP. - `[OIDC4VCI. Draft 13] `_, [:rfc:`7515`], [:rfc:`7517`]. -.. list-table:: +.. list-table:: :widths: 20 60 20 :header-rows: 1 @@ -843,13 +855,13 @@ The JWT proof type MUST contain the following parameters for the JOSE header and - **Description** - **Reference** * - **iss** - - The value of this claim MUST be the **client_id** of the Wallet Instance. + - The value of this claim MUST be the **client_id** of the Wallet Instance. - `[OIDC4VCI. Draft 13] `_, `[RFC7519, Section 4.1.1] `_. * - **aud** - The value of this claim MUST be the identifier URL of the PID/(Q)EAA Issuer. - `[OIDC4VCI. Draft 13] `_. * - **iat** - - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. + - UNIX Timestamp with the time of JWT issuance, coded as NumericDate as indicated in :rfc:`7519`. - `[OIDC4VCI. Draft 13] `_, [:rfc:`7519`. Section 4.1.6]. * - **nonce** - The value type of this claim MUST be a string, where the value is a **c_nonce** provided by the PID/(Q)EAA Issuer in the Token response. @@ -859,7 +871,7 @@ The JWT proof type MUST contain the following parameters for the JOSE header and Credential Response ^^^^^^^^^^^^^^^^^^^^ -Credential Response to the Wallet Instance MUST be sent using `application/json` media type. The response MUST contain the following mandatory claims: +Credential Response to the Wallet Instance MUST be sent using `application/json` media type. The response MUST contain the following mandatory claims: .. _table_credential_response_claim: .. list-table:: Credential http response parameters @@ -876,7 +888,7 @@ Credential Response to the Wallet Instance MUST be sent using `application/json` - Contains the issued PID/(Q)EAA. When the credential type is SD-JWT, it MUST be an SD-JWT JSON Object (see Section :ref:`PID/(Q)EAA Data Model `). - Appendix E in `[OIDC4VCI. Draft 13] `_. * - **c_nonce** - - JSON string containing a ``nonce`` value to be used to create a *proof of possession* of the key material when requesting a further credential or for the renewal of a credential. + - JSON string containing a ``nonce`` value to be used to create a *proof of possession* of the key material when requesting a further Credential or for the renewal of a credential. - `[OIDC4VCI. Draft 13] `_. * - **c_nonce_expires_in** - JSON integer corresponding to the **c_nonce** lifetime in seconds. @@ -895,7 +907,7 @@ Entity Configuration Credential Issuer Below is a non-normative example of an Entity Configuration containing an `openid_credential_issuer` metadata. .. code-block:: http - + HTTP/1.1 200 OK Content-Type: application/entity-statement+jwt @@ -925,6 +937,7 @@ Below is a non-normative example of an Entity Configuration containing an `openi "metadata": { "openid_credential_issuer": { "credential_issuer": "https://pid-provider.example.org", + "authorization_servers": ["https://pid-provider.example.org"], "authorization_endpoint": "https://pid-provider.example.org/connect/authorize", "token_endpoint": "https://pid-provider.example.org/connect/token", "pushed_authorization_request_endpoint": "https://pid-provider.example.org/connect/par", @@ -940,12 +953,12 @@ Below is a non-normative example of an Entity Configuration containing an `openi "kid": "ff0bded045fe63fe5d1d64dd83b567e0" }] } - "credentials_supported": [ + "credential_configurations_supported": [ { "format": "vc+sd-jwt", - "id": "eudiw.pid.it", "cryptographic_binding_methods_supported": ["jwk"], "cryptographic_suites_supported": ["RS256", "RS512", "ES256", "ES512"], + "proof_types": ["jwt"], "display": [{ "name": "PID Provider Italiano di esempio", "locale": "it-IT", @@ -1045,11 +1058,11 @@ Below is a non-normative example of an Entity Configuration containing an `openi } } } - ] + } }, "federation_entity": { - "organization_name": "Pid Provider Organization Example", + "organization_name": "PID Provider Organization Example", "homepage_uri": "https://pid-provider.example.org", "policy_uri": "https://pid-provider.example.org/privacy_policy", "tos_uri": "https://pid-provider.example.org/info_policy", From 5419e36b607ec10d38a6cfb0bde44aca22b4015b Mon Sep 17 00:00:00 2001 From: fmarino-ipzs Date: Tue, 9 Jan 2024 15:55:23 +0100 Subject: [PATCH 2/4] feat: added ISO18013 proximity flow --- docs/en/pid-eaa-issuance.rst | 2 +- docs/en/relying-party-solution.rst | 419 +++++++++++++++++- ...h-Level-Flow-ITWallet-Presentation-ISO.svg | 1 + 3 files changed, 420 insertions(+), 2 deletions(-) create mode 100644 images/High-Level-Flow-ITWallet-Presentation-ISO.svg diff --git a/docs/en/pid-eaa-issuance.rst b/docs/en/pid-eaa-issuance.rst index 8843b25af..4dfdd4707 100644 --- a/docs/en/pid-eaa-issuance.rst +++ b/docs/en/pid-eaa-issuance.rst @@ -284,7 +284,7 @@ The ``client_assertion`` is signed using the private key that is created during **Step 15 (Token Response):** The PID/(Q)EAA Provider validates the request, if successful an *Access Token* (bound to the DPoP key) and a fresh ``c_nonce`` is provided to the Wallet Instance. -.. code-block:: http +.. code-block:: HTTP/1.1 200 OK Content-Type: application/json diff --git a/docs/en/relying-party-solution.rst b/docs/en/relying-party-solution.rst index daef36e98..2144262d0 100644 --- a/docs/en/relying-party-solution.rst +++ b/docs/en/relying-party-solution.rst @@ -15,6 +15,7 @@ In this section the following flows are described: - **Remote Same Device Flow**, where the user-agent and the Wallet Instance are used in the same device. - **Remote Cross Device Flow**, where the user-agent and the Wallet Instance are used in different devices. +- **Proximity Flow**, where the User presents a Credential to a Verifier App according to ISO 18013-5. The User interacts with a Verifier using proximity connection technologies such as QR Code and Bluetooth Low Energy (BLE). In the **Same Device** and **Cross Device** Flows described in this chapter, the User interacts with a remote Relying Party. @@ -25,7 +26,7 @@ In the **Same Device** and **Cross Device** Flows described in this chapter, the is used. Remote Protocol Flow --------------------- +==================== In this scenario the Relying Party MUST provide the URL where the signed presentation Request Object is available for download. @@ -749,3 +750,419 @@ The Entity Configuration is a JWS, where its header parameters are defined below The Relying Party specific metadata parameter are experimental and still under discussion `here `_. + +Proximity Flow +============== + +This section describes how a Relying Party requests the presentation of an *mDoc-CBOR* Credential to a Wallet Instance according to the *ISO 18013-5 Specification*. Only *Supervised Device Retrieval flow* is supported in this technical implementation profile. + +The presentation phase is divided into three sub-phases: + + 1. **Device Engagement**: This subphase starts when the User is asked to disclose some attributes from their mDoc(s). The objective of this subphase is to establish a secure communication channel between the Wallet Instance and the Verifier App, so that the mDoc requests and responses can be exchanged during the communication subphase. + The messages exchanged in this subphase are transmitted through short-range technologies to limit the possibility of interception and eavesdropping. + This technical implementation profile only support QR code for the Device Engagement. + + 2. **Session establishment**: In session establishment, the Verifier App establishes a connection on a secure channels. + The data transmitted in such a connection will all be encrypted with the session key that both the Wallet Instance and the verifier know at this point in time. + The established session MAY be terminated based on the conditions as detailed in [ISO18013-5#9.1.1.4]. + + 3. **Communication - Device Retrieval**: The Verifier App encrypts the mdoc request with the appropriate session key and sends it to the Wallet Instance together with its public key in a session establishment message. The mdoc uses the data from the session establishment message to derive the session key and decrypt the mdoc request. + In communication subphase, the Verifier App MAY ask the Wallet for information about the holder using mDoc requests and responses. + The main channel for communication is the secure channel that has been established with the session establishment. The Wallet Instance encrypts the mdoc response with the appropriate session key and sends it to the Verifier App in a session data message. + For the communication sub-phase, only BLE is supported by this technical implementation profile. + + +The Figure below presents the flow diagram of ISO 18013-5 compliant proximity flow. + +.. _fig_High-Level-Flow-ITWallet-Presentation-ISO: +.. figure:: ../../images/High-Level-Flow-ITWallet-Presentation-ISO.svg + :figwidth: 100% + :align: center + :target: https://www.plantuml.com/plantuml/svg/bL9BZnCn3BxFhx3A0H3q3_ImMlOXXBJYqGguzE9ct2RQn0bvJDb_ZoSP3QFI2xab_Xx-xDocZ34NPpiisNDn1ufT1t9GPH_XUw88cA3KjuF_3QlnwNM2dHDYq9vf1Q-Up4ddErkeme9KZ381ESFg9rfB6JwnEB4IiAYTAuou7nN_Al-WQ8xcVzHd2dm8eKeFI-cMfApNDpVd3Nm9n90rmKLBa3s4I8b441dSWrTm7wcNkq7RD3xxJE07CIhlXmqyq624-CWdF94RYQaSWiP4iAweRzjr1vLvRkOVYIcYY32TWO8c9rSBp_GYWKoSe88LzPtsvx5HKO5xtnCSVVpNibA6ATjE8IyfKr7aBgptVDry0WlPXIBOH2aPpoEcbgzDOJTXIEPui2PfrqROZogki56OfNuvcxkdHv5N9H8eZSnaPLRJwUPU95JTn9P-5J60Tn2AcAZQjJ_MiCljxndUN6texN8Dr-ErSjd0roZrNEUjFDSVaJqaZP6gOMpDK0-61UHglkcJjJL75Cx4NHflAKT30xLGH_41wnLQIDb7FD6C7URSAOZCSfCjxyjSWcHEZBb4slCuTQL9FJVsWDRq9akuxfQuByx-0G00 + + High-Level Proximity Flow + +**Step 1-3**: The Verifier asks the User to disclose some attributes from their mdoc(s) stored in the Wallet Instance. The User opens the Wallet Instance. The Wallet Instance MUST generate a new ephemeral key pair (EDeviceKey.Priv, EDeviceKey.Pub), and includes the cipher suite identifier, the identifier of the elliptic curve to be used for key agreement and the EDeviceKey public point, as part of the device engagement structure (see [ISO18013-5#9.1.1.4]). This pair of keys is ephemeral and MUST be invalidated as soon as the secure channel is established. Finally, the Walle Instance shows the QR Code for the Device Engagement. + +Following is an example of a device engagement structure for QR device engagement and BLE as the data retrieval mode. + +CBOR data: + +.. code-block:: + + a30063312e30018201d818584ba4010220012158205a88d182bce5f42efa59943f33359d2e8a968ff289d93e5fa444b624343167fe225820b16e8cf858ddc7690407ba61d4c338237a8cfcf3de6aa672fc60a557aa32fc670281830201a300f401f50b5045efef742b2c4837a9a3b0e1d05a6917 + +In diagnostic notation: + +.. code-block:: + + { + 0: "1.0", % Version + + 1: % Security + [ + 1, % defines the cipher suite 1 which contains only EC curves + 24(<< % embedded CBOR data item + { + 1: 2, % kty:EC2 (Elliptic curves with x and y coordinate pairs) + -1: 1, % crv:p256 + -2:h'5A88D182BCE5F42EFA59943F33359D2E8A968FF289D93E5FA444B624343 167FE',% x-coordinate + -3:h'B16E8CF858DDC7690407BA61D4C338237A8CFCF3DE6AA672FC60A557AA32FC67' % y-coordinate + } + >>) + ], + + 2: %DeviceRetrievalMethods(Device engagement using QR code) + [ + [ + 2, %BLE + 1, % Version + { %BLE options + 0: false, % no support for mdoc peripheral server mode + 1: true, % support mdoc central client mode + 11: h'45EFEF742B2C4837A9A3B0E1D05A6917' % UUID of mdoc client central mode + } + ] + ] + } + + + +**Step 4-6**: The Verifier App scan the QR Code, generates its own set of ephemeral keys (EReaderKey. Priv, EReaderKey.Pub) and computes the session key, involving the public key received in the Engagement Structure and its newly-generated private key as specified in [ISO18013-5#9.1.1.5]. Finally, generates its session key that MUST be derived independently by the Wallet Instance and the Verifier App. + +**Step 7**: The Verifier App generates the mdoc request that MUST be encrypted with the appropriate session key, and sends it to the Wallet Instance together with EReaderKey.Pub in a session establishment message. The mdoc request MUST be encoded as CBOR as in the following non-normative example. + +CBOR data: +.. code-block:: + + a26776657273696f6e63312e306b646f63526571756573747381a26c6974656d7352657175657374d818590152a267646f6354797065756f72672e69736f2e31383031332e352e312e6d444c6a6e616d65537061636573a2746f72672e69736f2e31383031332e352e312e4954a375766572696669636174696f6e2e65766964656e6365f4781c766572696669636174696f6e2e6173737572616e63655f6c6576656cf4781c766572696669636174696f6e2e74727573745f6672616d65776f726bf4716f72672e69736f2e31383031332e352e31ab76756e5f64697374696e6775697368696e675f7369676ef47264726976696e675f70726976696c65676573f46f646f63756d656e745f6e756d626572f46a69737375655f64617465f46f69737375696e675f636f756e747279f47169737375696e675f617574686f72697479f46a62697274685f64617465f46b6578706972795f64617465f46a676976656e5f6e616d65f468706f727472616974f46b66616d696c795f6e616d65f46a726561646572417574688443a10126a11821590129308201253081cda00302010202012a300a06082a8648ce3d0403023020311e301c06035504030c15536f6d652052656164657220417574686f72697479301e170d3233313132343130323832325a170d3238313132323130323832325a301a3118301606035504030c0f536f6d6520526561646572204b65793059301306072a8648ce3d020106082a8648ce3d03010703420004aa1092fb59e26ddd182cfdbc85f1aa8217a4f0fae6a6a5536b57c5ef7be2fb6d0dfd319839e6c24d087cd26499ec4f87c8c766200ba4c6218c74de50cd1243b1300a06082a8648ce3d0403020347003044022048466e92226e042add073b8cdc43df5a19401e1d95ab226e142947e435af9db30220043af7a8e7d31646a424e02ea0c853ec9c293791f930bf589bee557370a4c97bf6584058a0d421a7e53b7db0412a196fea50ca6d4c8a530a47dd84d88588ab145374bd0ab2a724cf2ed2facf32c7184591c5969efd53f5aba63194105440bc1904e1b9 + +The above CBOR data in diagnostic notation: +.. code-block:: + + { + "version": "1.0", + "docRequests": [ + { + "itemsRequest": 24(<< { + "docType": "org.iso.18013.5.1.mDL", + "nameSpaces": { + "org.iso.18013.5.1.IT": { + "verification.evidence": false, + "verification.assurance_level": false, + "verification.trust_framework": false + }, + "org.iso.18013.5.1": { + "un_distinguishing_sign": false, + "driving_privileges": false, + "document_number": false, + "issue_date": false, + "issuing_country": false, + "issuing_authority": false, + "birth_date": false, + "expiry_date": false, + "given_name": false, + "portrait": false, + "family_name": false + } + } + } >>), + "readerAuth": [ + h'a10126', + { + 33: h'308201253081cda00302010202012a300a06082a8648ce3d0403023020311e301c06035504030c15536f6d652052656164657220417574686f72697479301e170d3233313132343130323832325a170d3238313132323130323832325a301a3118301606035504030c0f536f6d6520526561646572204b65793059301306072a8648ce3d020106082a8648ce3d03010703420004aa1092fb59e26ddd182cfdbc85f1aa8217a4f0fae6a6a5536b57c5ef7be2fb6d0dfd319839e6c24d087cd26499ec4f87c8c766200ba4c6218c74de50cd1243b1300a06082a8648ce3d0403020347003044022048466e92226e042add073b8cdc43df5a19401e1d95ab226e142947e435af9db30220043af7a8e7d31646a424e02ea0c853ec9c293791f930bf589bee557370a4c97b' + }, + null, + h'58a0d421a7e53b7db0412a196fea50ca6d4c8a530a47dd84d88588ab145374bd0ab2a724cf2ed2facf32c7184591c5969efd53f5aba63194105440bc1904e1b9' + ] + } + ] + } + +**Step 8**: The Wallet Instance uses the session establishment message to derive the session keys and decrypt the mdoc request. It computes the session key using the public key received from the Verifier App and its private key. + +**Step 9-10**: Upon receiving the mDoc request, the Wallet Instance identifies the documents containing the requested attributes and prompts the User for permission to share this information with the Verifier. If the User consents, the Wallet produces an mDoc response and sends it to the Verifier App via the secure channel. + +**Step 11-12**: In case of User consent, the Wallet Instance generates an mDoc response and sends it to the Verifier App through the secure channel. The mDoc response MUST be CBOR encoded, and its structure is defined in [ISO18013-5#8.3.2.1.2.2]. A non-normative example of a mDoc response is given below. + +CBOR Data: +.. code-block:: + + a36776657273696f6e63312e3069646f63756d656e747381a367646f6354797065756f72672e69736f2e31383031332e352e312e6d444c6c6973737565725369676e6564a26a6e616d65537061636573a2746f72672e69736f2e31383031332e352e312e495483d81858f7a46864696765737449440b6672616e646f6d506d44f21ee875f2c1d502b43198e5a15271656c656d656e744964656e74696669657275766572696669636174696f6e2e65766964656e63656c656c656d656e7456616c756581a2647479706571656c656374726f6e69635f7265636f7264667265636f7264bf6474797065781f68747470733a2f2f657564692e77616c6c65742e70646e642e676f762e697466736f75726365bf716f7267616e697a6174696f6e5f6e616d65754d6f746f72697a7a617a696f6e6520436976696c656f6f7267616e697a6174696f6e5f6964656d5f696e666c636f756e7472795f636f6465626974ffffd8185866a4686469676573744944046672616e646f6d50185d84dfb71ce9b173010ddd62174fbe71656c656d656e744964656e746966696572781c766572696669636174696f6e2e74727573745f6672616d65776f726b6c656c656d656e7456616c7565656569646173d8185865a4686469676573744944006672616e646f6d50137f903174253c4585358267aae2ea4e71656c656d656e744964656e746966696572781c766572696669636174696f6e2e6173737572616e63655f6c6576656c6c656c656d656e7456616c75656468696768716f72672e69736f2e31383031332e352e318bd8185852a46864696765737449440c6672616e646f6d5053e29d0ddbbc7d2306a32bdbe2e56e5171656c656d656e744964656e7469666965726b66616d696c795f6e616d656c656c656d656e7456616c756563446f65d8185855a4686469676573744944036672616e646f6d50990cba2069fa1b33b8d6ae910b6549dc71656c656d656e744964656e7469666965726a676976656e5f6e616d656c656c656d656e7456616c756567416e746f6e696fd818585ba46864696765737449440a6672616e646f6d504086c1379975f805f1b1f4975e6a126571656c656d656e744964656e7469666965726a69737375655f646174656c656c656d656e7456616c7565d903ec6a323031392d31302d3230d818585ca4686469676573744944016672616e646f6d50ab4ca30c918dd2fd0bf35242c15fa2d871656c656d656e744964656e7469666965726b6578706972795f646174656c656c656d656e7456616c7565d903ec6a323032342d31302d3230d8185855a4686469676573744944076672616e646f6d508d9066f6c8da16619867cd4e2fab0c8871656c656d656e744964656e7469666965726f69737375696e675f636f756e7472796c656c656d656e7456616c7565624954d818587ea4686469676573744944056672616e646f6d5059fe68db795dee4c20976380ea24770571656c656d656e744964656e7469666965727169737375696e675f617574686f726974796c656c656d656e7456616c75657828497374697475746f20506f6c696772616669636f2065205a656363612064656c6c6f20537461746fd818585ba4686469676573744944026672616e646f6d5008b3f1ca5517019767be3dee3bb0614571656c656d656e744964656e7469666965726a62697274685f646174656c656c656d656e7456616c7565d903ec6a313935362d30312d3230d818585ca4686469676573744944096672616e646f6d50a2395ec214350c26066306e23279b3ae71656c656d656e744964656e7469666965726f646f63756d656e745f6e756d6265726c656c656d656e7456616c756569393837363534333231d8185850a4686469676573744944066672616e646f6d50a25e1a5b915d2d6eafee9674e023293971656c656d656e744964656e74696669657268706f7274726169746c656c656d656e7456616c75654420212223d81858eea46864696765737449440d6672616e646f6d50eeed6a3b856563627589a360939d12f771656c656d656e744964656e7469666965727264726976696e675f70726976696c656765736c656c656d656e7456616c756582a37576656869636c655f63617465676f72795f636f646561416a69737375655f64617465d903ec6a323031382d30382d30396b6578706972795f64617465d903ec6a323032342d31302d3230a37576656869636c655f63617465676f72795f636f646561426a69737375655f64617465d903ec6a323031372d30322d32336b6578706972795f64617465d903ec6a323032342d31302d3230d818585ba4686469676573744944086672616e646f6d50c0ef486b2a194ed3cbf7f354fd40092171656c656d656e744964656e74696669657276756e5f64697374696e6775697368696e675f7369676e6c656c656d656e7456616c756561496a697373756572417574688443a10126a118215901423082013e3081e5a00302010202012a300a06082a8648ce3d040302301a3118301606035504030c0f5374617465204f662055746f706961301e170d3233313132343134353430345a170d3238313132323134353430345a30383136303406035504030c2d5374617465204f662055746f7069612049737375696e6720417574686f72697479205369676e696e67204b65793059301306072a8648ce3d020106082a8648ce3d03010703420004c338ec1000b351ce8bcdfc167450aeceb + +In diagnostic notation: +.. code-block:: + + { + "version": "1.0", + "documents": [ + { + "docType": "org.iso.18013.5.1.mDL", + "issuerSigned": { + "nameSpaces": { + "org.iso.18013.5.1.IT": [ + 24(<< { + "digestID": 11, + "random": h'6d44f21ee875f2c1d502b43198e5a152', + "elementIdentifier": "verification.evidence", + "elementValue": [ + { + "type": "electronic_record", + "record": { + "type": "https://eudi.wallet.pdnd.gov.it", + "source": { + "organization_name": "Motorizzazione Civile", + "organization_id": "m_inf", + "country_code": "it" + } + } + } + ] + } >>), + 24(<< { + "digestID": 4, + "random": h'185d84dfb71ce9b173010ddd62174fbe', + "elementIdentifier": "verification.trust_framework", + "elementValue": "eidas" + } >>), + 24(<< { + "digestID": 0, + "random": h'137f903174253c4585358267aae2ea4e', + "elementIdentifier": "verification.assurance_level", + "elementValue": "high" + } >>) + ], + "org.iso.18013.5.1": [ + 24(<< { + "digestID": 12, + "random": h'53e29d0ddbbc7d2306a32bdbe2e56e51', + "elementIdentifier": "family_name", + "elementValue": "Doe" + } >>), + 24(<< { + "digestID": 3, + "random": h'990cba2069fa1b33b8d6ae910b6549dc', + "elementIdentifier": "given_name", + "elementValue": "Antonio" + } >>), + 24(<< { + "digestID": 10, + "random": h'4086c1379975f805f1b1f4975e6a1265', + "elementIdentifier": "issue_date", + "elementValue": 1004("2019-10-20") + } >>), + 24(<< { + "digestID": 1, + "random": h'ab4ca30c918dd2fd0bf35242c15fa2d8', + "elementIdentifier": "expiry_date", + "elementValue": 1004("2024-10-20") + } >>), + 24(<< { + "digestID": 7, + "random": h'8d9066f6c8da16619867cd4e2fab0c88', + "elementIdentifier": "issuing_country", + "elementValue": "IT" + } >>), + 24(<< { + "digestID": 5, + "random": h'59fe68db795dee4c20976380ea247705', + "elementIdentifier": "issuing_authority", + "elementValue": "Istituto Poligrafico e Zecca dello Stato" + } >>), + 24(<< { + "digestID": 2, + "random": h'08b3f1ca5517019767be3dee3bb06145', + "elementIdentifier": "birth_date", + "elementValue": 1004("1956-01-20") + } >>), + 24(<< { + "digestID": 9, + "random": h'a2395ec214350c26066306e23279b3ae', + "elementIdentifier": "document_number", + "elementValue": "987654321" + } >>), + 24(<< { + "digestID": 6, + "random": h'a25e1a5b915d2d6eafee9674e0232939', + "elementIdentifier": "portrait", + "elementValue": h'20212223' + } >>), + 24(<< { + "digestID": 13, + "random": h'eeed6a3b856563627589a360939d12f7', + "elementIdentifier": "driving_privileges", + "elementValue": [ + { + "vehicle_category_code": "A", + "issue_date": 1004("2018-08-09"), + "expiry_date": 1004("2024-10-20") + }, + { + "vehicle_category_code": "B", + "issue_date": 1004("2017-02-23"), + "expiry_date": 1004("2024-10-20") + } + ] + } >>), + 24(<< { + "digestID": 8, + "random": h'c0ef486b2a194ed3cbf7f354fd400921', + "elementIdentifier": "un_distinguishing_sign", + "elementValue": "I" + } >>) + ] + }, + "issuerAuth": [ + h'a10126', + { + 33: h'3082013e3081e5a00302010202012a300a06082a8648ce3d040302301a3118301606035504030c0f5374617465204f662055746f706961301e170d3233313132343134353430345a170d3238313132323134353430345a30383136303406035504030c2d5374617465204f662055746f7069612049737375696e6720417574686f72697479205369676e696e67204b65793059301306072a8648ce3d020106082a8648ce3d03010703420004c338ec1000b351ce8bcdfc167450aeceb7d518bd9a519583e082d67effff06565804fc09abf0e4a08e699c9dba3796285a15f68e40ac7f9fc7700a15153a4065300a06082a8648ce3d040302034800304502210099b7d62e6bf7b1823db3713df889bf73e70bb4d9c58c21e92c58d2f1beffe932022058d039747a00d70e6d66be4797e6142b3608a014ee09b7b79af2cae2aaf27788' + }, + 24(<< { + "version": "1.0", + "digestAlgorithm": "SHA-256", + "docType": "org.iso.18013.5.1.mDL", + "valueDigests": { + "org.iso.18013.5.1": { + 1: h'0E5F0B6B33418E508740771E82F893372EAF5B2445BC4C84DCF08B005E9493FC', + 2: h'DE21BB62FF2897D8B986D2CDA9F9BC5865C02807F7B4D9DD1FA4A79DF4C0D37F', + 3: h'BC5568239E35CE9FF8798C27FFDCD757B134B679F0FE05729AA3491381912E65', + 5: h'E6048BDC7FD6454296F1E3F54536107C9C5B24C4064DE46A98121E3630EECCA2', + 6: h'73690D92DCAA61B0203870F67C6AA9FDFEA889B6F0C720DE757B4B0A8516A206', + 7: h'E353EA0B0FD92B6BE90C64CC3B2EE1284153A8F0F5066B99AAC599200E6EEEB2', + 8: h'29227872CEB49923D267B5F4BADE6D387B42AC2DC4B2AE26C9013067FEE7018A', + 9: h'A6A119F7CACAC0B8C6AACAC747FD3FE7E50B6D9BB8A507FDA79F0DF6646F285D', + 10: h'6D8025D2F02A5E7E1406FB6AAEB67F9EDE9B07191A53F3E23B77C528223A94E2', + 12: h'B0D43E4E2EA534E4D5304E64BCF7A0F13E2C8EE8304B9CD23ABA4909652A4647', + 13: h'FBF4DE318982F2DBAD43C601CAEB22628B301AC18AA8264C5831B2AAAC89C486' + }, + "org.iso.18013.5.1.IT": { + 0: h'CF57377B675F64F37314739592C1E8A911A7DDAF341CE2902FE877C5A835E4C1', + 4: h'4A4B4CC64EC9299C1A2501EA449F577005E9F7A60408057C07A7C67FB151E5F5', + 11: h'78824FBD6FBBA88A2AAB44DF8B6F5E9759126D87D1F4415995E658FD9239E1FE' + } + }, + "deviceKeyInfo": { + "deviceKey": { + 1: 2, + -1: 1, + -2: h'AFD09E720B918CEDC2B8A881950BAB6A1051E18AE16A814D51E609938663D5E1', + -3: h'61FBC6C8AD24EC86A78BB4E9AC377DD2B7C711D9F2EB9AFD4AA0963662847AED'}}, + "validityInfo": { + "signed": 0("2023-11-24T14:54:05Z"), + "validFrom": 0("2023-11-24T14:54:05Z"), + "validUntil": 0("2024-11-24T14:54:05Z")} + } >>), + h'f2461e4fab69e9f7bcffe552395424514524d1679440036213173101448d1b1ab4a293859b389ffa8b47aeed10e9b0c1545412ac37c51a76482cd9bbbe110152' + ] + }, + "deviceSigned": { + "nameSpaces": 24(<< {} >>), + "deviceAuth": { + "deviceSignature": [ + h'a10126', + {}, + null, + h'1fed7190d2975ab79c072e6f1d9d52436059d1fc959d55baf74f057d89b10fcc0dc77a50d433d4c76ddf26223c5560c4ab123b5cb5eb805a90036aa147493076' + ] + } + } + } + ], + "status": 0 + } + +**Step 13**: The Verifier App MUST verify that the signatures in the mDoc **issuerSigned** field are valid using the public key of the Credential Issuer declared in the mDoc itself. At this point, the verifier MUST check the signature in the **deviceSigned** field. If the check of these signatures is successful, the verifier can trust that the information it received is valid. + + + + + +Device Engagement +----------------- + +The Device Engagement structure MUST be have at least the following components: + + - **Version**: *tstr*. Version of the data structure being used. + - **Security**: an array that contains two mandatory values + + - the cipher identifier: see Table 22 of [ISO18013-5] + - the mDL public ephemeral key generated by the Wallet Instance and required by the Verifier App to derive the Session Key. The mDL public ephemeral key MUST be of a type allowed by the indicated cipher suite. + - **TransferMethod**: an array that contains one or more transferMethod arrays when performing device engagement using the QR code. This array is for offline data retrieval methods. A transferMethod array holds two mandatory values (type and version). Only the BLE option is supported by this technical implementation profile, then the type value MUST be set to '2'. + - **BleOptions**: this elements MUST provide options for the BLE connection (support for Peripheral Server or Central Client Mode, and the device UUID). + + +mDoc Request +------------ + +The messages in the mDoc Request MUST be encoded using CBOR. The resulting CBOR byte string for the mDoc Request MUST be encrypted with the Session Key obtained after the Device Engagement phase and MUST be transmitted using the BLE protocol. +The details on the structure of mDoc Request, including identifier and format of the data elements, are provided below. + + - **version**: (tstr). Version of the data structure. + - **docRequests**: Requested DocType, NameSpace and data elements. + + - **itemsRequest**: #6.24(bstr .cbor ItemsRequest). + + - **docType**: (tstr). The DocType element contains the type of document requested. See :ref:`Data Model Section `. + - **nameSpaces**: (tstr). See :ref:`Data Model Section ` for more details. + + - **dataElements**: (tstr). Requested data elements with *Intent to Retain* value for each requested element. + + - **IntentToRetain**: (bool). It indicates that the Verifier App intends to retain the received data element. + - **readerAuth**: *COSE_Sign1*. It is required for the Verifier App authentication. + +.. note:: + + The domestic data elements MUST not be returned unless specifically requested by the Verifier App. + +mDoc Response +------------- + +The messages in the mDoc Response MUST be encoded using CBOR and MUST be encrypted with the Session Key obtained after the Device Engagement phase. +The details on the structure of mDoc Response are provided below. + + - **version**: (tstr). Version of the data structure. + - **documents**: Returned *DocType*, and *ResponseData*. + + - **docType**: (tstr). The DocType element contains the type of document returned. See :ref:`Data Model Section `. + - **ResponseData**: + + - **IssuerSigned**: Responded data elements signed by the issuer. + + - **nameSpaces**: (tstr). See :ref:`Data Model Section ` for more details. + + - **IssuerSignedItemBytes**: #6.24(bstr .cbor). + + - **digestID**: (uint). Reference value to one of the **ValueDigests** provided in the *Mobile Security Object* (`issuerAuth`). + - **random**: (bstr). Random byte value used as salt for the hash function. This value SHALL be different for each *IssuerSignedItem* and it SHALL have a minimum length of 16 bytes. + - **elementIdentifier**: (tstr). Identifier of User attribute name contained in the Credential. + - **elementValue**: (any). User attribute value + - **DeviceSigned**: Responded data elements signed by the Wallet Instance. + + - **NameSpaces**: #6.24(bstr .cbor DeviceNameSpaces). The DeviceNameSpaces structure MAY be an empty structure. DeviceNameSpaces contains the data element identifiers and values. It is returned as part of the corresponding namespace in DeviceNameSpace. + + - **DataItemName**: (tstr). The identifier of the element. + - **DataItemValue**: (any). The value of the element. + - **DeviceAuth**: The DeviceAuth structure MUST contain the DeviceSignature elements. + + - **DeviceSignature**: It MUST contain the device signature for the Wallet Instance authentication. + - **status**: It contains a status code. For detailed description and action required refer to to Table 8 (ResponseStatus) of the [ISO18013-5] + + +Session Termination +------------------- + +The session MUST be terminated if at least one of the following conditions occur. + + - After a time-out of no activity of receiving or sending session establishment or session data messages occurs. The time-out for no activity implemented by the Wallet Instance and the Verifier App SHOULD be no less than 300 s. + - If the Wallet Instance does not want to receive any further requests. + - If the Verifier App does not want to send any further requests. + +If the Wallet Instance and the Verifier App does not want to send or receive any further requests, it MUST initiate session termination as follows. + + - to send the status code for session termination or + - to send the "End" command defined in [ISO18013-5#8.3.3.1.1.5]. + +When a session is terminated, the Wallet Instance and the Verifier App MUST perform at least the following actions: + + - destruction of session keys and related ephemeral key material; + - closure of the communication channel used for data retrieval. diff --git a/images/High-Level-Flow-ITWallet-Presentation-ISO.svg b/images/High-Level-Flow-ITWallet-Presentation-ISO.svg new file mode 100644 index 000000000..6bcf4030f --- /dev/null +++ b/images/High-Level-Flow-ITWallet-Presentation-ISO.svg @@ -0,0 +1 @@ +User's SmartphoneVerifier's SmartphoneUserUserWallet InstanceWallet InstanceVerifier AppVerifier App1Open the Wallet Instance to present an mDoc CredentialDevice Engagement subphase -over QR-2Generate new ephemeral key pair3Show the QR Code for Device Engagement4Scan the QR Code5Generate newephemeral key pair6Compute session keySession establishment and Communication subphase -over BLE secure channel-7mDoc Request + public key of the Verifier App(Session establishment)8Compute session key9Prompt for consent to share the requested information10Grant consent11Retrieve mDoc from local storage12mDoc Response13Verify Response signatureand check mDoc validity \ No newline at end of file From 4463c23b03fb26e7d1230e329131c35ed20ddfbb Mon Sep 17 00:00:00 2001 From: fmarino-ipzs <77629526+fmarino-ipzs@users.noreply.github.com> Date: Wed, 10 Jan 2024 09:13:07 +0100 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Giuseppe De Marco --- docs/en/relying-party-solution.rst | 53 +++++++++++++----------------- 1 file changed, 23 insertions(+), 30 deletions(-) diff --git a/docs/en/relying-party-solution.rst b/docs/en/relying-party-solution.rst index 3359e9d02..3038b15b5 100644 --- a/docs/en/relying-party-solution.rst +++ b/docs/en/relying-party-solution.rst @@ -750,25 +750,22 @@ The Entity Configuration is a JWS, where its header parameters are defined below Proximity Flow ============== -This section describes how a Relying Party requests the presentation of an *mDoc-CBOR* Credential to a Wallet Instance according to the *ISO 18013-5 Specification*. Only *Supervised Device Retrieval flow* is supported in this technical implementation profile. +This section describes how a Verifier requests the presentation of an *mDoc-CBOR* Credential to a Wallet Instance according to the *ISO 18013-5 Specification*. Only *Supervised Device Retrieval flow* is supported in this technical implementation profile. The presentation phase is divided into three sub-phases: - 1. **Device Engagement**: This subphase starts when the User is asked to disclose some attributes from their mDoc(s). The objective of this subphase is to establish a secure communication channel between the Wallet Instance and the Verifier App, so that the mDoc requests and responses can be exchanged during the communication subphase. + 1. **Device Engagement**: This subphase begins when the User is prompted to disclose certain attributes from the mDoc(s). The objective of this subphase is to establish a secure communication channel between the Wallet Instance and the Verifier App, so that the mDoc requests and responses can be exchanged during the communication subphase. The messages exchanged in this subphase are transmitted through short-range technologies to limit the possibility of interception and eavesdropping. - This technical implementation profile only support QR code for the Device Engagement. + This technical implementation profile exclusively supports QR code for Device Engagement. - 2. **Session establishment**: In session establishment, the Verifier App establishes a connection on a secure channels. - The data transmitted in such a connection will all be encrypted with the session key that both the Wallet Instance and the verifier know at this point in time. + 2. **Session establishment**: During the session establishment phase, the Verifier App sets up a secure connection. All data transmitted over this connection is encrypted using a session key, which is known to both the Wallet Instance and the Verifier at this stage. The established session MAY be terminated based on the conditions as detailed in [ISO18013-5#9.1.1.4]. - 3. **Communication - Device Retrieval**: The Verifier App encrypts the mdoc request with the appropriate session key and sends it to the Wallet Instance together with its public key in a session establishment message. The mdoc uses the data from the session establishment message to derive the session key and decrypt the mdoc request. - In communication subphase, the Verifier App MAY ask the Wallet for information about the holder using mDoc requests and responses. - The main channel for communication is the secure channel that has been established with the session establishment. The Wallet Instance encrypts the mdoc response with the appropriate session key and sends it to the Verifier App in a session data message. - For the communication sub-phase, only BLE is supported by this technical implementation profile. + 3. **Communication - Device Retrieval**: The Verifier App encrypts the mDoc request with the appropriate session key and sends it to the Wallet Instance together with its public key in a session establishment message. The mDoc uses the data from the session establishment message to derive the session key and decrypt the mDoc request. + During the communication subphase, the Verifier App has the option to request information from the Wallet using mDoc requests and responses. The primary mode of communication is the secure channel established during the session setup. The Wallet Instance encrypts the mDoc response using the session key and transmits it to the Verifier App via a session data message. This technical implementation profile only supports Bluetooth Low Energy (BLE) for the communication sub-phase. -The Figure below presents the flow diagram of ISO 18013-5 compliant proximity flow. +The following figure illustrates the flow diagram compliant with ISO 18013-5 for proximity flow. .. _fig_High-Level-Flow-ITWallet-Presentation-ISO: .. figure:: ../../images/High-Level-Flow-ITWallet-Presentation-ISO.svg @@ -778,9 +775,9 @@ The Figure below presents the flow diagram of ISO 18013-5 compliant proximity fl High-Level Proximity Flow -**Step 1-3**: The Verifier asks the User to disclose some attributes from their mdoc(s) stored in the Wallet Instance. The User opens the Wallet Instance. The Wallet Instance MUST generate a new ephemeral key pair (EDeviceKey.Priv, EDeviceKey.Pub), and includes the cipher suite identifier, the identifier of the elliptic curve to be used for key agreement and the EDeviceKey public point, as part of the device engagement structure (see [ISO18013-5#9.1.1.4]). This pair of keys is ephemeral and MUST be invalidated as soon as the secure channel is established. Finally, the Walle Instance shows the QR Code for the Device Engagement. +**Step 1-3**: The Verifier requests the User to reveal certain attributes from their mDoc(s) stored in the Wallet Instance. The User initiates the Wallet Instance. The Wallet Instance MUST create a new temporary key pair (EDeviceKey.Priv, EDeviceKey.Pub), and incorporate the cipher suite identifier, the identifier of the elliptic curve for key agreement, and the EDeviceKey public point into the device engagement structure (refer to [ISO18013-5#9.1.1.4]). This key pair is temporary and MUST be invalidated immediately after the secure channel is established. Finally, the Wallet Instance displays the QR Code for Device Engagement. -Following is an example of a device engagement structure for QR device engagement and BLE as the data retrieval mode. +Below an example of a device engagement structure that utilizes QR for device engagement and Bluetooth Low Energy (BLE) for data retrieval. CBOR data: @@ -824,16 +821,16 @@ In diagnostic notation: -**Step 4-6**: The Verifier App scan the QR Code, generates its own set of ephemeral keys (EReaderKey. Priv, EReaderKey.Pub) and computes the session key, involving the public key received in the Engagement Structure and its newly-generated private key as specified in [ISO18013-5#9.1.1.5]. Finally, generates its session key that MUST be derived independently by the Wallet Instance and the Verifier App. +**Step 4-6**: The Verifier App scans the QR Code and generates its own ephemeral key pair (EReaderKey.Priv, EReaderKey.Pub). It then calculates the session key, using the public key received in the Engagement Structure and its newly-generated private key, as outlined in [ISO18013-5#9.1.1.5]. Finally, it generates its session key, which must be independently derived by both the Wallet Instance and the Verifier App. -**Step 7**: The Verifier App generates the mdoc request that MUST be encrypted with the appropriate session key, and sends it to the Wallet Instance together with EReaderKey.Pub in a session establishment message. The mdoc request MUST be encoded as CBOR as in the following non-normative example. +**Step 7**: The Verifier App creates an mDoc request that MUST be encrypted using the relevant session key, and transmits it to the Wallet Instance along with EReaderKey.Pub within a session establishment message. The mDoc request MUST be encoded in CBOR, as demonstrated in the following non-normative example. CBOR data: .. code-block:: a26776657273696f6e63312e306b646f63526571756573747381a26c6974656d7352657175657374d818590152a267646f6354797065756f72672e69736f2e31383031332e352e312e6d444c6a6e616d65537061636573a2746f72672e69736f2e31383031332e352e312e4954a375766572696669636174696f6e2e65766964656e6365f4781c766572696669636174696f6e2e6173737572616e63655f6c6576656cf4781c766572696669636174696f6e2e74727573745f6672616d65776f726bf4716f72672e69736f2e31383031332e352e31ab76756e5f64697374696e6775697368696e675f7369676ef47264726976696e675f70726976696c65676573f46f646f63756d656e745f6e756d626572f46a69737375655f64617465f46f69737375696e675f636f756e747279f47169737375696e675f617574686f72697479f46a62697274685f64617465f46b6578706972795f64617465f46a676976656e5f6e616d65f468706f727472616974f46b66616d696c795f6e616d65f46a726561646572417574688443a10126a11821590129308201253081cda00302010202012a300a06082a8648ce3d0403023020311e301c06035504030c15536f6d652052656164657220417574686f72697479301e170d3233313132343130323832325a170d3238313132323130323832325a301a3118301606035504030c0f536f6d6520526561646572204b65793059301306072a8648ce3d020106082a8648ce3d03010703420004aa1092fb59e26ddd182cfdbc85f1aa8217a4f0fae6a6a5536b57c5ef7be2fb6d0dfd319839e6c24d087cd26499ec4f87c8c766200ba4c6218c74de50cd1243b1300a06082a8648ce3d0403020347003044022048466e92226e042add073b8cdc43df5a19401e1d95ab226e142947e435af9db30220043af7a8e7d31646a424e02ea0c853ec9c293791f930bf589bee557370a4c97bf6584058a0d421a7e53b7db0412a196fea50ca6d4c8a530a47dd84d88588ab145374bd0ab2a724cf2ed2facf32c7184591c5969efd53f5aba63194105440bc1904e1b9 -The above CBOR data in diagnostic notation: +The above CBOR data is represented in diagnostic notation as follows: .. code-block:: { @@ -875,11 +872,11 @@ The above CBOR data in diagnostic notation: ] } -**Step 8**: The Wallet Instance uses the session establishment message to derive the session keys and decrypt the mdoc request. It computes the session key using the public key received from the Verifier App and its private key. +**Step 8**: The Wallet Instance uses the session establishment message to derive the session keys and decrypt the mDoc request. It computes the session key using the public key received from the Verifier App and its private key. -**Step 9-10**: Upon receiving the mDoc request, the Wallet Instance identifies the documents containing the requested attributes and prompts the User for permission to share this information with the Verifier. If the User consents, the Wallet produces an mDoc response and sends it to the Verifier App via the secure channel. +**Step 9-10**: When the Wallet Instance receives the mDoc request, it locates the documents that contain the requested attributes and asks the User for permission to provide this information to the Verifier. If the User agrees, the Wallet generates an mDoc response and transmits it to the Verifier App through the secure channel. -**Step 11-12**: In case of User consent, the Wallet Instance generates an mDoc response and sends it to the Verifier App through the secure channel. The mDoc response MUST be CBOR encoded, and its structure is defined in [ISO18013-5#8.3.2.1.2.2]. A non-normative example of a mDoc response is given below. +**Step 11-12**: If the User gives consent, the Wallet Instance creates an mDoc response and transmits it to the Verifier App via the secure channel. The mDoc response MUST be encoded in CBOR, with its structure outlined in [ISO18013-5#8.3.2.1.2.2]. Below is a non-normative example of an mDoc response. CBOR Data: .. code-block:: @@ -1067,11 +1064,7 @@ In diagnostic notation: "status": 0 } -**Step 13**: The Verifier App MUST verify that the signatures in the mDoc **issuerSigned** field are valid using the public key of the Credential Issuer declared in the mDoc itself. At this point, the verifier MUST check the signature in the **deviceSigned** field. If the check of these signatures is successful, the verifier can trust that the information it received is valid. - - - - +**Step 13**: The Verifier App is required to validate the signatures in the mDoc's issuerSigned field using the public key of the Credential Issuer specified within the mDoc. Subsequently, the Verifier MUST validate the signature in the deviceSigned field. If these signature checks pass, the Verifier can confidently consider the received information as valid. Device Engagement ----------------- @@ -1083,7 +1076,7 @@ The Device Engagement structure MUST be have at least the following components: - the cipher identifier: see Table 22 of [ISO18013-5] - the mDL public ephemeral key generated by the Wallet Instance and required by the Verifier App to derive the Session Key. The mDL public ephemeral key MUST be of a type allowed by the indicated cipher suite. - - **TransferMethod**: an array that contains one or more transferMethod arrays when performing device engagement using the QR code. This array is for offline data retrieval methods. A transferMethod array holds two mandatory values (type and version). Only the BLE option is supported by this technical implementation profile, then the type value MUST be set to '2'. + - **transferMethod**: an array that contains one or more transferMethod arrays when performing device engagement using the QR code. This array is for offline data retrieval methods. A transferMethod array holds two mandatory values (type and version). Only the BLE option is supported by this technical implementation profile, then the type value MUST be set to ``2``. - **BleOptions**: this elements MUST provide options for the BLE connection (support for Peripheral Server or Central Client Mode, and the device UUID). @@ -1149,14 +1142,14 @@ Session Termination The session MUST be terminated if at least one of the following conditions occur. - - After a time-out of no activity of receiving or sending session establishment or session data messages occurs. The time-out for no activity implemented by the Wallet Instance and the Verifier App SHOULD be no less than 300 s. - - If the Wallet Instance does not want to receive any further requests. - - If the Verifier App does not want to send any further requests. + - After a time-out of no activity of receiving or sending session establishment or session data messages occurs. The time-out for no activity implemented by the Wallet Instance and the Verifier App SHOULD be no less than 300 seconds. + - When the Wallet Instance doesn't accept any more requests. + - When the Verifier App does not send any further requests. -If the Wallet Instance and the Verifier App does not want to send or receive any further requests, it MUST initiate session termination as follows. +If the Wallet Instance and the Verifier App does not send or receive any further requests, the session termination MUST be initiated as follows. - - to send the status code for session termination or - - to send the "End" command defined in [ISO18013-5#8.3.3.1.1.5]. + - Send the status code for session termination, or + - dispatch the "End" command as outlined in [ISO18013-5#8.3.3.1.1.5]. When a session is terminated, the Wallet Instance and the Verifier App MUST perform at least the following actions: From 57020a232c7dfeba676986384595ffe0babff129 Mon Sep 17 00:00:00 2001 From: Giuseppe De Marco Date: Wed, 10 Jan 2024 14:22:56 +0100 Subject: [PATCH 4/4] Apply suggestions from code review --- docs/en/pid-eaa-issuance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/pid-eaa-issuance.rst b/docs/en/pid-eaa-issuance.rst index 4dfdd4707..8843b25af 100644 --- a/docs/en/pid-eaa-issuance.rst +++ b/docs/en/pid-eaa-issuance.rst @@ -284,7 +284,7 @@ The ``client_assertion`` is signed using the private key that is created during **Step 15 (Token Response):** The PID/(Q)EAA Provider validates the request, if successful an *Access Token* (bound to the DPoP key) and a fresh ``c_nonce`` is provided to the Wallet Instance. -.. code-block:: +.. code-block:: http HTTP/1.1 200 OK Content-Type: application/json