Skip to content

Commit

Permalink
chore: peppelinux revision
Browse files Browse the repository at this point in the history
  • Loading branch information
@fmarino-ipzs
fmarino-ipzs committed Jul 23, 2023
1 parent 3cc84c7 commit cfee7fa
Showing 1 changed file with 18 additions and 18 deletions.
36 changes: 18 additions & 18 deletions docs/en/pid-eaa-issuance.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
PID/(Q)EAA Issuance
+++++++++++++++++++

This section describes the issuance flow for the PID and (Q)EAAs that require a high security implementation profile.
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*: It represents an organization (public or private) that is responsible for the release of an eIDAS-compliant EUDI Wallet Solution. It also issues thes Wallet Instance Attestation to its Wallet Instances by means of 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.
Expand Down Expand Up @@ -48,7 +48,7 @@ The Wallet Instance Setup phase is described in Section [...]. In the following
High-Level (Q)EAA flow
----------------------

The :numref:`fig_High-Level-Flow-ITWallet-QEAA-Issuance` shows a general architecture and highlights the main operations involved in the issuance of a (Q)EAA, under the main following assumptions:
The :numref:`fig_High-Level-Flow-ITWallet-QEAA-Issuance` shows a general architecture and highlights the main operations involved in the issuance of a (Q)EAA, following the assumptions listed below:

- the User has a valid PID stored in its own Wallet Instance;
- the (Q)EAA requires a high security implementation profile.
Expand All @@ -64,9 +64,9 @@ Below the description of the most relevant operations involved in the (Q)EAA iss

1. **Obtaining the trusted (Q)EAA Issuer**: the Wallet Instance queries the Trust Anchor to fetch the trusted (Q)EAA Issuer.
2. **Obtaining of (Q)EAA Issuer metadata**: the Wallet Instance establishes the trust to the (Q)EAA Issuer 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**: following the Authorization Code Flow in `[OIDC4VCI. Draft 13] <https://openid.bitbucket.io/connect/openid-4-verifiable-credential-issuance-1_0.html>`_ the Wallet Instance requests a (Q)EAA to the (Q)EAA Issuer. A fresh key pairs is generated by the Wallet Instance, the public key is used by (Q)EAA Issuer for the key binding of the (Q)EAA. The (Q)EAA Issuer checks the Wallet Instance by means of the Wallet Attestation and the Trust Chain related to the Wallet Provider
4. **End-user authentication**: the (Q)EAA Issuer authenticates the User with the PID owned by the User, acting as a verifier (Relying Party).
5. **(Q)EAA issuance**: once the User authentication with a valid PID happens, the User gives their consent, and the (Q)EAA Issuer releases a (Q)EAA bound to the key material held by the requesting Wallet Instance.
3. **(Q)EAA request**: following the Authorization Code Flow in `[OIDC4VCI. Draft 13] <https://openid.bitbucket.io/connect/openid-4-verifiable-credential-issuance-1_0.html>`_ the Wallet Instance requests a (Q)EAA to the (Q)EAA Issuer. A fresh key pairs is generated by the Wallet Instance, the public key is used by (Q)EAA Issuer for the key binding of the (Q)EAA. The (Q)EAA Issuer checks the Wallet Instance by means of the Wallet Attestation and the Trust Chain related to the Wallet Provider.
4. **End-user authentication**: the (Q)EAA Issuer, acting as a verifier (Relying Party), authenticates the User with 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 Issuer releases a (Q)EAA bound to the key material held by the requesting Wallet Instance.



Expand All @@ -91,7 +91,7 @@ The PID/(Q)EAA Issuance phase is based on the **Authorization Code Flow** with *

.. note::

**Federation Check:** The Wallet Instance needs to check if the PID/(Q)EAA Issuer is part of 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 Issuer is represented within the section `Entity Configuration Credential Issuer`_.
**Federation Check:** The Wallet Instance needs to check if the PID/(Q)EAA Issuer 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 Issuer is represented within the section `Entity Configuration Credential Issuer`_.


**Steps 5-6 (PAR Request):** The Wallet Instance creates a PKCE code verifier that sends in a *pushed authorization request*, using the request parameter (see :rfc:`9126` Section 3) to the PID/(Q)EAA Issuer PAR endpoint. The Wallet Instance signs the request using its private key. A OAuth2 client authentication method is involved, since in this flow the pushed authorization endpoint is a protected endpoint. The client authentication is based on the model defined in [:rfc:`7521`] using the Wallet Instance Attestation JWS inside the **client_assertion** parameter. The authorization_details [RAR :rfc:`9396`] parameter is extended to allow Wallet Instance to specify the types of the credentials when requesting authorization for the PID/(Q)EAA issuance.
Expand Down Expand Up @@ -177,7 +177,7 @@ The JWS payload of the request object is represented below:
.. 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 Issuer performs the User authentication requesting a valid PID to the Wallet Instance. The (Q)EAA Issuer MUST use [`OpenID4VP`_] to dynamically request presentation of the PID. From a protocol perspective, the (Q)EAA Issuer then acts as a verifier and sends a presentation request to the Wallet Instance. The Wallet Instance MUST have a valid PID obtained prior to starting a transaction with the (Q)EAA Issuer.
The (Q)EAA Issuer performs the User authentication requesting a valid PID to the Wallet Instance. The (Q)EAA Issuer MUST use [`OpenID4VP`_] to dynamically request the presentation of the PID. From a protocol perspective, the (Q)EAA Issuer then acts as a verifier and sends a presentation request to the Wallet Instance. The Wallet Instance MUST have a valid PID obtained prior to starting a transaction with the (Q)EAA Issuer.

**Steps 10-11 (Authorization Response):** The PID/(Q)EAA Issuer sends an authorization code to the Wallet Instance.

Expand All @@ -190,7 +190,7 @@ The JWS payload of the request object is represented below:
HTTP/1.1 302 Found
Location: eudiw://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 creates a key for DPoP and a fresh DPoP proof for the token request to the PID/(Q)EAA Issuer. DPoP provides a way to bind the access token to a certain sender (Wallet Instance) `[DPoP-draft16] <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-16>`_. 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.
**Steps 12-13 (DPoP Proof for Token Endpoint)**: The Wallet Instance creates a key for DPoP and a fresh DPoP proof for the token request to the PID/(Q)EAA Issuer. DPoP provides a way to bind the Access Token to a certain sender (Wallet Instance) `[DPoP-draft16] <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-16>`_. 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.

**Step 14 (Token Request):** The Wallet Instance sends a token request to the PID/(Q)EAA Issuer token endpoint using the authorization *code*, *code_verifier*, *DPoP proof* and *private_key_jwt*.

Expand All @@ -216,7 +216,7 @@ The JWS payload of the request object is represented below:
&client_assertion=eyJhbGciOiJIUzI1NiI
**Step 15 (Token Response):** The PID/(Q)EAA Issuer 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 Issuer validates the request and if it is successful, it issues an *Access Token* (bound to the DPoP key) and a fresh *c_nonce*.

.. code-block:: http
Expand All @@ -235,7 +235,7 @@ The JWS payload of the request object is represented below:
**Steps 16-18 (DPoP Proof for Credential Endpoint):** The Wallet Instance creates a new key pair to which the new credential SHALL be bound. Then, it creates a proof of possession with the new key and the *c_nonce* obtained in **Step 15** and it creates a DPoP proof for the request to the PID/(Q)EAA credential issuance endpoint.

**Step 19 (Credential Request):** The Wallet Instance sends a PID/(Q)EAA issuance request to the PID/(Q)EAA credential endpoint. It contains the *access token*, the *DPoP proof*, the *credential type*, the *proof* (proof of possession of the key) and the *format*.
**Step 19 (Credential Request):** The Wallet Instance sends a PID/(Q)EAA issuance request to the PID/(Q)EAA credential endpoint. It contains the *Access Token*, the *DPoP proof*, the *credential type*, the *proof* (proof of possession of the key) and the *format*.

.. note::

Expand Down Expand Up @@ -293,7 +293,7 @@ Where the decoded content of the JWT is represented below:
**Steps 20-22 (Credential Response):** The PID/(Q)EAA Issuer checks the *DPoP proof* and whether the *access token* is valid and suitable for the requested PID/(Q)EAA. It also checks the proof of possession for the key material the new credential SHALL be bound to. If all checks succeed, the PID/(Q)EAA Issuer creates a new credential bound to the key material and sends it to the Wallet Instance. The Wallet Instance MUST perform the PID/(Q)EAA integrity and authenticity checks before proceeding with the secure storage of the credential.
**Steps 20-22 (Credential Response):** The PID/(Q)EAA Issuer checks the *DPoP proof* and whether the *Access Token* is valid and suitable for the requested PID/(Q)EAA. It also checks the proof of possession for the key material the new credential SHALL be bound to. If all checks succeed, the PID/(Q)EAA Issuer creates a new credential bound to the key material and sends it to the Wallet Instance. The Wallet Instance MUST perform the PID/(Q)EAA integrity and authenticity checks before proceeding with the secure storage of the credential.

.. code-block:: http
Expand Down Expand Up @@ -502,15 +502,15 @@ Token endpoint
--------------

The token endpoint is used by the Wallet Instance
to obtain an access token by presenting its authorization grant, as
to obtain an Access Token by presenting its authorization grant, as
defined in :rfc:`6749`.

Token Request
^^^^^^^^^^^^^^^

The request to the PID/(Q)EAA Token endpoint MUST be an HTTP request with method POST, where its body message is encoded in ``application/x-www-form-urlencoded`` format. The Wallet Instance sends the Token endpoint request with *private_key_jwt* authentication and a *DPoP proof* containing the mandatory parameters, defined in the table below.

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 `[DPoP-draft16] <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-16>`_. 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 `[DPoP-draft16] <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-16>`_. 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.


.. list-table::
Expand Down Expand Up @@ -641,7 +641,7 @@ A DPoP-bound Access Token is provided by the PID/(Q)EAA Token endpoint as a resu
- It identifies the principal that is 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 <https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes>`_].
* - **client_id**
- MUST be set to the *jwk* value in the *cnf* parameter inside the Wallet Instance Attestation.
- It MUST be set to the *jwk* value in the *cnf* parameter, as taken in the Wallet Instance Attestation.
- [:rfc:`9068`].
* - **aud**
- It MUST match the value *client_id*. The RP MUST verify that this value matches its client ID.
Expand All @@ -656,7 +656,7 @@ A DPoP-bound Access Token is provided by the PID/(Q)EAA Token endpoint as a resu
- 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**
- JWK SHA-256 Thumbprint Confirmation Method. The value of the jkt member MUST be the base64url encoding (as defined in [RFC7515]) of the JWK SHA-256 Thumbprint of the DPoP public key (in JWK format) to which the access token is bound.
- JWK SHA-256 Thumbprint Confirmation Method. The value of the jkt member MUST be the base64url encoding (as defined in [RFC7515]) of the JWK SHA-256 Thumbprint of the DPoP public key (in JWK format) to which the Access Token is bound.
- [`DPoP-draft16 <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-16>`_. Section 6.1] and [:rfc:`7638`].


Expand All @@ -669,7 +669,7 @@ The Credential Endpoint issues a Credential as approved by the End-User upon pre
Credential Request
^^^^^^^^^^^^^^^^^^^

A Wallet Instance makes a PID/(Q)EAA Request to the PID/(Q)EAA Credential endpoint by sending the following mandatory parameters in the entity-body of an 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 entity-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 [DPoP-draft16]. 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.
Expand Down Expand Up @@ -702,7 +702,7 @@ If the *DPoP proof* is invalid, the Credential endpoint returns an error respons

.. note::

If the **format** value is `mso_mdoc`, the credential request MUST contain the doctype claim which is a JSON string identifying the credential type according to `EIDAS-ARF`_ . See Appendix E.2. of `[OIDC4VCI. Draft 13] <https://openid.bitbucket.io/connect/openid-4-verifiable-credential-issuance-1_0.html>`_ for more details.
If the **format** value is `mso_mdoc`, the credential request MUST contain the ``doctype`` claim which is a JSON string identifying the credential type according to `EIDAS-ARF`_ . See Appendix E.2. of `[OIDC4VCI. Draft 13] <https://openid.bitbucket.io/connect/openid-4-verifiable-credential-issuance-1_0.html>`_ for more details.


The JWT proof type MUST contain the following parameters for the JOSE header and the JWT body:
Expand Down Expand Up @@ -821,7 +821,7 @@ Below a non-normative example of an Entity Configuration containing an `openid_c
"credentials_supported": [
{
"format": "vc+sd-jwt",
"id": "eu.eudiw.pid.it",
"id": "eudiw.pid.it",
"cryptographic_binding_methods_supported": ["jwk"],
"cryptographic_suites_supported": ["RS256", "RS512", "ES256", "ES512"],
"display": [{
Expand Down

0 comments on commit cfee7fa

Please sign in to comment.