diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
index 73867058e..58a5c934f 100644
--- a/.github/workflows/gh-pages.yml
+++ b/.github/workflows/gh-pages.yml
@@ -67,11 +67,11 @@ jobs:
echo '
- Italian eIDAS Wallet Technical Specifications
+ EUDI Wallet docs
- Italian eIDAS Wallet Technical Specifications
+ EUDI Wallet docs
- Italian version
diff --git a/docs/common/common_definitions.rst b/docs/common/common_definitions.rst
index 5abf3f1bc..4348e4d42 100644
--- a/docs/common/common_definitions.rst
+++ b/docs/common/common_definitions.rst
@@ -57,5 +57,6 @@
.. _DPOP: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop
.. _RFC 7519: https://www.rfc-editor.org/rfc/rfc7519
.. _OAUTH2: https://www.rfc-editor.org/rfc/rfc6749
+.. _OPENID4VC-HAIP: https://vcstuff.github.io/oid4vc-haip-sd-jwt-vc/draft-oid4vc-haip-sd-jwt-vc.html
diff --git a/docs/common/standards.rst b/docs/common/standards.rst
index b753a750a..984810ead 100644
--- a/docs/common/standards.rst
+++ b/docs/common/standards.rst
@@ -54,4 +54,6 @@ Technical References
* - :rfc:`6749`
- The OAuth 2.0 Authorization Framework
* - `DPOP`
- - TBD
+ - D. Fett, B. Campbell, J. Bradley, T. Lodderstedt, M. Jones, D. Waite, "OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)"
+ * - `OPENID4VC-HAIP`
+ - Lodderstedt, T., K. Yasuda, "OpenID4VC High Assurance Interoperability Profile with SD-JWT VC"
diff --git a/docs/en/defined-terms.rst b/docs/en/defined-terms.rst
index c4e1c7054..fffdb9a10 100644
--- a/docs/en/defined-terms.rst
+++ b/docs/en/defined-terms.rst
@@ -2,6 +2,13 @@
.. _defined-terms.rst:
+
+Normative Language and Conventions
+++++++++++++++++++++++++++++++++++
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
+
+
Defined Terms
+++++++++++++
diff --git a/docs/en/index.rst b/docs/en/index.rst
index 100c7d1ac..82ff010e5 100644
--- a/docs/en/index.rst
+++ b/docs/en/index.rst
@@ -60,7 +60,7 @@ Index of content
----------------
.. toctree::
- :maxdepth: 2
+ :maxdepth: 3
ssi-introduction.rst
defined-terms.rst
diff --git a/docs/en/pid-eaa-data-model.rst b/docs/en/pid-eaa-data-model.rst
index e999c5d60..25888685e 100644
--- a/docs/en/pid-eaa-data-model.rst
+++ b/docs/en/pid-eaa-data-model.rst
@@ -50,6 +50,7 @@ The Disclosures are sent to the Holder together with the SD-JWT in the *Combined
See `[draft-terbu-sd-jwt-vc-latest] `_ and `[SD-JWT] `__ for more details.
+
PID/(Q)EAA SD-JWT parameters
----------------------------
@@ -174,7 +175,6 @@ PID Claims field
The ``claims`` parameter contains the User attributes with the following mandatory fields:
-
.. list-table::
:widths: 20 60 20
:header-rows: 1
diff --git a/docs/en/relying-party-solution.rst b/docs/en/relying-party-solution.rst
index 42d398975..a35bf3e4a 100644
--- a/docs/en/relying-party-solution.rst
+++ b/docs/en/relying-party-solution.rst
@@ -10,8 +10,8 @@ Relying Party Solution
This section describes how a Relying Party may ask to a Wallet Instance the presentation of the PID and the (Q)EAAs, according the following specifications:
-- `OpenID for Verifiable Presentations - draft 19 `_.
-- `Draft: OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP) `_.
+- `OpenID for Verifiable Presentations - draft 19 `_.
+- `Draft: OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP) `_.
In this section the following flows are described:
@@ -340,10 +340,10 @@ Here a non-normative example of ``presentation_definition``:
{
"presentation_definition": {
- "id": "pid-sd-jwt:unique_id+given_name+family_name",
+ "id": "presentation definitions",
"input_descriptors": [
{
- "id": "eu.europa.ec.eudiw.pid.it.1",
+ "id": "pid-sd-jwt:unique_id+given_name+family_name",
"name": "Person Identification Data",
"purpose": "User authentication",
"format": "vc+sd-jwt",
@@ -384,8 +384,7 @@ After getting the User authorization and consent for the presentation of the cre
.. note::
**Why the response is encrypted?**
- The response sent from the Wallet Instance to the Relying Party is encrypted
- to prevent a technique called `SSL split attack `_, that could be enabled by malicious app installed locally by Users,that intecepts the network traffic, or be present by-design in network environments where a next-generation firewalls or other security devices may reduce the privacy of the Users.
+ The response sent from the Wallet Instance to the Relying Party is encrypted to prevent a malicious agent from gaining access to the plaintext information transmitted within the verifier's network. This is only possible if the network environment of the verifier employs `TLS termination `_. Such technique employs a termination proxy that acts as an intermediary between the client and the webserver and handles all TLS-related operations. In this manner, the proxy deciphers the transmission's content and either forwards it in plaintext or by negotiates an internal TLS session with the actual webserver's intended target. In the first scenario, any malicious actor within the network segment could intercept the transmitted data and obtain sensitive information, such as an unencrypted response, by sniffing the transmitted data.
Below a non-normative example of the request:
@@ -410,14 +409,9 @@ Below is a non-normative example of the decrypted JSON ``response`` content:
"id": "04a98be3-7fb0-4cf5-af9a-31579c8b0e7d",
"descriptor_map": [
{
- "id": "eu.europa.ec.eudiw.pid.it.1:unique_id",
+ "id": "pid-sd-jwt:unique_id+given_name+family_name",
"path": "$.vp_token.verified_claims.claims._sd[0]",
"format": "vc+sd-jwt"
- },
- {
- "id": "eu.europa.ec.eudiw.pid.it.1:given_name",
- "path": "$.vp_token.verified_claims.claims._sd[1]",
- "format": "vc+sd-jwt"
}
]
}
diff --git a/docs/en/trust.rst b/docs/en/trust.rst
index 8fa149c8c..3e3898615 100644
--- a/docs/en/trust.rst
+++ b/docs/en/trust.rst
@@ -254,7 +254,10 @@ Below is a non-normative example of a Trust Anchor Entity Configuration, where e
Entity Configuration
--------------------
-The Entity Configuration is the verifiable document that each Federation Entity must publish on its own behalf.
+The Entity Configuration is the verifiable document that each Federation Entity must publish on its own behalf in the web path **.well-known/openid-federation**.
+
+The Entity Configuration HTTP response MUST set the media type `application/entity-statement+jwt`.
+
The Entity Configuration must be cryptographically signed. The public part of this key must be present in the
Entity Configuration and within the Entity Statement issued by a immediate superior concerning the Federation Entity.
diff --git a/docs/en/wallet-instance-attestation.rst b/docs/en/wallet-instance-attestation.rst
index 899b1bf62..7ce4641fd 100644
--- a/docs/en/wallet-instance-attestation.rst
+++ b/docs/en/wallet-instance-attestation.rst
@@ -43,222 +43,40 @@ The following requirements are assumed for the Wallet Instance Attestation:
.. attention::
⚠️ Implementation of points no. 5 and 9 is still under discussion. This version assumes the authenticity and non-revocability of the Wallet Instance.
-High-end design
----------------
+High-level Design
+-----------------
-Static view of the components
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Static Component View
+~~~~~~~~~~~~~~~~~~~~~
.. figure:: ../../images/static_view_wallet_instance_attestation.svg
- :name: Wallet Solution schema
- :alt: The image shows how the Wallet Provider and the Wallet Instances are contained within the Wallet Solution, which is managed by the Wallet Provider.
+ :name: Wallet Solution Schema
+ :alt: The image illustrates the containment of Wallet Provider and Wallet Instances within the Wallet Solution, managed by the Wallet Provider.
:target: https://www.plantuml.com/plantuml/uml/XP4nJuSm44VtVehBdxbnPp2iRYx6qTHIjR7SaVQ0-EqzaICDgN4ZBxpqzTUXiCkyJCaupvJXzbH2le4hiCW7A7rsAGM6ETCQn-E7RMSloi0OJzDC691FeL1QE1BMWZBeraW2Mbv4wK8VQayPT5yX9TgCQPclpdy676lnGF0ZN93DyVs3xVsrhOU70hCi0_JshwHXFJp-Rg4dIuECo96moD7xeBQbUKBEbE0EPEwuEWx6N2zj_uXqU8wbhVMhD3tjbAX1BYIl_mq0
-Dynamic view of the components
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Dynamic Component View
+~~~~~~~~~~~~~~~~~~~~~~
-This section describes the format of the Wallet Instance Attestation and how it is issued by the Wallet Provider.
+This section describes the Wallet Instance Attestation format and how the Wallet Provider issues it.
.. figure:: ../../images/dynamic_view_sequence_wallet_instance_attestation.svg
- :name: sequence diagram for Wallet Instance Attestation request
- :alt: The figure shows the sequence diagram for issuing a Wallet Instance Attestation. The steps will be described below.
+ :name: Sequence Diagram for Wallet Instance Attestation Request
+ :alt: The figure illustrates the sequence diagram for issuing a Wallet Instance Attestation, with the steps explained below.
:target: https://www.plantuml.com/plantuml/uml/XPB1RzKm3CRl-IlCJY3nn7s7QOZ3118IGi0kkxYDLLcqJd2SLMz_FLvV6r7AnDN-_Fi-ExajXcfr6iEhh3XC24Rf2Kmh1QoMf4uTQGZPLTnpHZ6u-bv8hm0Br7tz7iUH33wAGwMdHJBpFpLVD3roN35p5qA5qusBhtsQZN7a9uBvekMLzo19GUbNfMBlib8X1_PAaUHveeIPJpTpTmrtPDjiNdrW8iE8Xc7kJgvoeyzh1VeaXYmimnyqi7EcyXP-qddnPAN9EruXYJcnsEhdf1yUrqbqC3MjnM3aOgxT5hmZ8NNrWix8MhQcH_zwMGyaIK-U5KwNgRNGB3yeFIF-kZYyBuNKE4a3VRh_5h0tVbpoTRiROLE__Y_eZOTP9W_RyZOpa5GM4YhbA2uy25fLQgrXkmDANDe7OClN7ktbXO-FyJ8jqluYpguDtVJSFc9y42MCPx04gJDa0Q5vz_LkIMATnjy0
--
-
- **Message 1**: The User initializes the Wallet Instance. In particular, this process happens after the Wallet Instance installation and after the expiration of the Wallet Instance Attestation is launched and every time the User wants to request or present a credential.
-- **Message 2-3**: The Wallet Instance obtains metadata about its Wallet Provider. Among these, we also find the list of supported algorithms, public keys, endpoints.
-- **Message 4**: The Wallet Instance verifies that the Wallet Provider is trustworthy by resolving the provider's trust chain up to the Trust Anchor.
-- **Message 5-7**: The Wallet Instance creates a new key pair and requests a ``nonce`` from the Wallet Provider (as a measure against replay attacks).
-- **Message 8**: The Wallet Instance generates a Wallet Instance Attestation Request, in JWS format, signed with the private key associated with the public key for which it wants to obtain the attestation.
-- **Message 9-13**: The Wallet Instance sends the Wallet Instance Attestation Request to the Wallet Provider which verifies its validity and issues the signed attestation.
-- **Message 13-14**:The Wallet Instance receives the Wallet Instance Attestation signed by the Wallet Provider and proceeds with a formal verification.
-- **Message 15**:The Wallet Instance Attestation is ready to be consumed.
+- **Message 1**: The User starts the Wallet Instance mobile app, a new Wallet Instance Attestation is automatically obtained if the previous one results expired.
+- **Message 2-3**: The Wallet Instance retrieves metadata about its Wallet Provider, including the list of supported algorithms, public keys, and endpoints.
+- **Message 4**: The Wallet Instance verifies the Wallet Provider's trustworthiness by resolving the provider's trust chain to the Trust Anchor.
+- **Message 5-7**: The Wallet Instance generates a new key pair and requests a ``nonce`` from the Wallet Provider to guard against replay attacks.
+- **Message 8**: The Wallet Instance creates a Wallet Instance Attestation Request in JWS format, signed with the private key associated with the public key for which it seeks attestation.
+- **Message 9-13**: The Wallet Instance sends the Wallet Instance Attestation Request to the Wallet Provider, which validates it and issues a signed attestation in return.
+- **Message 13-14**: The Wallet Instance receives the Wallet Instance Attestation signed by the Wallet Provider and performs formal verification.
+- **Message 15**: The Wallet Instance Attestation is now ready for use.
-Detail design
+Detailed Design
---------------
-We will go into the detail design below.
-
-Format of the Wallet Provider Entity Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The Wallet Provider Entity Configuration is a JWS containing the public keys and the supported algorithms within the Wallet Provider metadata definition. It is defined according to `OpenID Connect Federation `_ and Section Trust Model of this specification.
-
-Header
-^^^^^^
-+---------+-----------------------------------------------------------------+
-| **key** | **value** |
-+---------+-----------------------------------------------------------------+
-| alg | Algorithm to verify the token signature (es. ES256). |
-+---------+-----------------------------------------------------------------+
-| kid | Thumbprint of the public key used for signing. |
-+---------+-----------------------------------------------------------------+
-| typ | Media type, in this case, we use the entity-statement+jwt value.|
-+---------+-----------------------------------------------------------------+
-
-Payload
-^^^^^^^
-+-----------------------------------+-----------------------------------+
-| **key** | **value** |
-+-----------------------------------+-----------------------------------+
-| iss | The public url of the Wallet |
-| | Provider. |
-+-----------------------------------+-----------------------------------+
-| sub | The public url of the Wallet |
-| | Provider. |
-+-----------------------------------+-----------------------------------+
-| iat | Configuration release timestamp. |
-+-----------------------------------+-----------------------------------+
-| exp | Configuration expiration |
-| | timestamp. |
-+-----------------------------------+-----------------------------------+
-| jwks | Containing the keys attribute |
-| | which is an array of all the |
-| | public keys associated with the |
-| | domain (they could also match |
-| | those of the Wallet Provider). |
-+-----------------------------------+-----------------------------------+
-| metadata | This attribute will contain for |
-| | each entity its own |
-| | metadata. In this case we |
-| | will have the Wallet |
-| | Provider metadata contained within|
-| | the ``eudi_wallet_provider`` |
-| | attribute and the more generic |
-| | entity ``federation_entity``. |
-+-----------------------------------+-----------------------------------+
-
-Payload `eudi_wallet_provider`
-''''''''''''''''''''''''''''''
-+------------------------------------+------------------------------------+
-| **key** | **value** |
-+------------------------------------+------------------------------------+
-|| jwks || Containing the keys attribute |
-|| || which is an array of all the |
-|| || Wallet Provider's public keys. |
-+------------------------------------+------------------------------------+
-|| token_endpoint || Endpoint for obtaining the Wallet |
-|| || Instance Attestation. |
-+------------------------------------+------------------------------------+
-|| asc_values_supported || List of supported values for |
-|| || the certified security context. |
-|| || These values define a level of |
-|| || assurance about the security of |
-|| || the app. In particular we will |
-|| || mainly have 3 values associated |
-|| || with low, medium and high |
-|| || security. An attested security |
-|| || context is defined according to |
-|| || the proof that the Wallet |
-|| || Instance is able to send to the |
-|| || Wallet Provider. |
-|| || ⚠️ This parameter is not standard |
-|| || and is still under discussion. |
-+------------------------------------+------------------------------------+
-|| grant_types_supported || The type of grants supported by |
-|| || the endpoint token. Therefore, |
-|| || for the Wallet Provider the token |
-|| || is equivalent only to the Wallet |
-|| || Instance attestation, therefore |
-|| || this attribute will contain an |
-|| || array with only one element. |
-+------------------------------------+------------------------------------+
-|| token_endpoint_auth_methods_suppo || Supported authentication method |
-|| rted || for the endpoint token. |
-|| || |
-+------------------------------------+------------------------------------+
-|| token_endpoint_auth_signing_alg_v || List of supported signature |
-|| alues_supported || algorithms. |
-+------------------------------------+------------------------------------+
-
-.. note::
- The parameter `asc_values_supported` is experimental and still
- under discussion.
-
-Payload `federation_entity`
-'''''''''''''''''''''''''''
-+-------------------+----------------------------------------+
-| **key** | **value** |
-+-------------------+----------------------------------------+
-| organization_name | Organization name. |
-+-------------------+----------------------------------------+
-| homepage_uri | Organization website. |
-+-------------------+----------------------------------------+
-| tos_uri | Url to the terms of use. |
-+-------------------+----------------------------------------+
-| policy_uri | Url to the privacy policy. |
-+-------------------+----------------------------------------+
-| logo_uri | URL of the organization logo. |
-+-------------------+----------------------------------------+
-
-Below a non-normative example of the Entity Configuration.
-
-.. code-block:: javascript
-
- {
- "alg": "ES256",
- "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY",
- "typ": "entity-statement+jwt"
- }
- .
- {
- "iss": "https://wallet-provider.example.org",
- "sub": "https://wallet-provider.example.org",
- "jwks": {
- "keys": [
- {
- "crv": "P-256",
- "kty": "EC",
- "x": "qrJrj3Af_B57sbOIRrcBM7br7wOc8ynj7lHFPTeffUk",
- "y": "1H0cWDyGgvU8w-kPKU_xycOCUNT2o0bwslIQtnPU6iM",
- "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY"
- }
- ]
- },
- "metadata": {
- "eudi_wallet_provider": {
- "jwks": {
- "keys": [
- {
- "crv": "P-256",
- "kty": "EC",
- "x": "qrJrj3Af_B57sbOIRrcBM7br7wOc8ynj7lHFPTeffUk",
- "y": "1H0cWDyGgvU8w-kPKU_xycOCUNT2o0bwslIQtnPU6iM",
- "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY"
- }
- ]
- },
- "token_endpoint": "https://wallet-provider.example.org/token",
- "asc_values_supported": [
- "https://wallet-provider.example.org/LoA/basic",
- "https://wallet-provider.example.org/LoA/medium",
- "https://wallet-provider.example.org/LoA/high"
- ],
- "grant_types_supported": [
- "urn:ietf:params:oauth:client-assertion-type:jwt-key-attestation"
- ],
- "token_endpoint_auth_methods_supported": [
- "private_key_jwt"
- ],
- "token_endpoint_auth_signing_alg_values_supported": [
- "ES256",
- "ES384",
- "ES512"
- ]
- },
- "federation_entity": {
- "organization_name": "PagoPa S.p.A.",
- "homepage_uri": "https://wallet-provider.example.org",
- "policy_uri": "https://wallet-provider.example.org/privacy_policy",
- "tos_uri": "https://wallet-provider.example.org/info_policy",
- "logo_uri": "https://wallet-provider.example.org/logo.svg"
- }
- },
- "iat": 1687171759,
- "exp": 1709290159
- }
-
+The detailed design is explained below.
Format of the Wallet Instance Attestation Request
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -284,38 +102,38 @@ Header
Payload
^^^^^^^
-+---------+---------------------------------------+
-| **key** | **value** |
-+---------+---------------------------------------+
-|| iss || The thumbprint |
-|| || of the JWK of the Wallet Instance |
-|| || for which the attestation is |
-|| || being requested. |
-+---------+---------------------------------------+
-|| sub || The public url of the Wallet |
-|| || Provider |
-+---------+---------------------------------------+
-|| jti || Unique identifier of the request. |
-|| || This parameter will be used to |
-|| || avoid replay attacks. |
-+---------+---------------------------------------+
-|| type || String. It must be set to |
-|| || ``WalletInstanceAttestationRequest`` |
-+---------+---------------------------------------+
-|| nonce || The nonce obtained from the |
-|| || Wallet Porvider. |
-+---------+---------------------------------------+
-|| cnf || This parameter will contain the |
-|| || configuration of the Wallet |
-|| || Instance in JSON format. Among |
-|| || the mandatory attributes there |
-|| || will be the jwk parameter |
-|| || containing the public key of the |
-|| || Wallet Instance. It will also |
-|| || contain all the information |
-|| || useful for the Wallet Provider |
-|| || to verify that the app is genuine. |
-+---------+---------------------------------------+
++--------+----------------------------------------+
+| **key**| **value** |
++--------+----------------------------------------+
+|| iss || The thumbprint |
+|| || of the JWK of the Wallet Instance |
+|| || for which the attestation is |
+|| || being requested. |
++--------+----------------------------------------+
+|| aud || The public url of the Wallet |
+|| || Provider. |
++--------+----------------------------------------+
+|| jti || Unique identifier of the request. |
+|| || This parameter will be used to |
+|| || avoid replay attacks. |
++--------+----------------------------------------+
+|| type || String. It must be set to |
+|| || ``WalletInstanceAttestationRequest``. |
++--------+----------------------------------------+
+|| nonce || The nonce obtained from the |
+|| || Wallet Porvider. |
++--------+----------------------------------------+
+|| cnf || This parameter will contain the |
+|| || configuration of the Wallet |
+|| || Instance in JSON format. Among |
+|| || the mandatory attributes there |
+|| || will be the jwk parameter |
+|| || containing the public key of the |
+|| || Wallet Instance. It will also |
+|| || contain all the information |
+|| || useful for the Wallet Provider |
+|| || to verify that the app is genuine. |
++--------+----------------------------------------+
Below a non-normative example of the Wallet Instance Attestation
request where the decoded JWS headers and payload are separated by a comma:
@@ -330,7 +148,7 @@ request where the decoded JWS headers and payload are separated by a comma:
.
{
"iss": "vbeXJksM45xphtANnCiG6mCyuU4jfGNzopGuKvogg9c",
- "sub": "https://wallet-provider.example.org",
+ "aud": "https://wallet-provider.example.org",
"jti": "6ec69324-60a8-4e5b-a697-a766d85790ea",
"type": "WalletInstanceAttestationRequest",
"nonce" : "....."
@@ -369,15 +187,10 @@ Header
| kid | Key id used by the Wallet |
| | Provider to sign the attestation. |
+-----------------------------------+-----------------------------------+
-| typ | Media type, in this case we use |
-| | the value va+jwt (Verifiable |
-| | Assertion JWT). |
-| | This parameter is currently |
-| | non-standard as it is not yet |
-| | registered as `IANA Media |
-| | Types `__. |
+| typ | Media type, set to |
+| | `wallet-attestation+jwt`, |
+| | according to |
+| | [`OPENID4VC-HAIP`_] |
+-----------------------------------+-----------------------------------+
| x5c | Array containing the X.509 |
| | certificate (and the entire chain |
@@ -392,79 +205,77 @@ Header
Payload
^^^^^^^
-+---------------------------+-------------------------------------------+
-| **key** | **value** |
-+---------------------------+-------------------------------------------+
-|| iss || The public url of the Wallet |
-|| || Instance attestation issuer. See |
-|| || the example below in this section. |
-+---------------------------+-------------------------------------------+
-|| sub || Thumbprint value |
-|| || of the JWK of the Wallet Instance |
-|| || for which the attestation is |
-|| || being issued. |
-+---------------------------+-------------------------------------------+
-|| iat || Unix timestamp of attestation |
-|| || issuance time. |
-+---------------------------+-------------------------------------------+
-|| exp || Unix timestamp regarding the |
-|| || expiration date time. |
-|| || A good practice to avoid security |
-|| || problems is to have a limited |
-|| || duration of the attestation. |
-+---------------------------+-------------------------------------------+
-|| type || String: |
-|| || "WalletInstanceAttestation". |
-+---------------------------+-------------------------------------------+
-|| policy_uri || Url to the privacy policy |
-|| || of the wallet. |
-+---------------------------+-------------------------------------------+
-|| tos_uri || Url to the terms |
-|| || of use of the Wallet Provider. |
-+---------------------------+-------------------------------------------+
-|| logo_uri || Logo url of the Wallet Provider. |
-+---------------------------+-------------------------------------------+
-|| asc || Attested security context: |
-|| || Represents a level of "trust" of |
-|| || the service containing a Level Of |
-|| || Agreement defined in the metadata |
-|| || of the Wallet Provider. |
-+---------------------------+-------------------------------------------+
-|| cnf || This parameter contains the ``jwk`` |
-|| || parameter |
-|| || with the public key of the Wallet |
-|| || necessary for the holder binding. |
-+---------------------------+-------------------------------------------+
-|| authorization_endpoint || URL of the OP's OAuth 2.0 |
-|| || Authorization Endpoint. |
-+---------------------------+-------------------------------------------+
-|| response_types_supported || JSON array containing a list of |
-|| || the OAuth 2.0 response_type values |
-|| || that this OP supports. |
-+---------------------------+-------------------------------------------+
-|| vp_formats_supported || JSON object containing |
-|| || ``jwt_vp_json`` and ``jwt_vc_json`` |
-|| || supported algorithms array. |
-+---------------------------+-------------------------------------------+
-|| request_object_signing || JSON array containing a list of the |
-|| _alg_values_supported || JWS signing algorithms (alg values) |
-|| || supported by the OP for Request Objects. |
-+---------------------------+-------------------------------------------+
-|| presentation_definition || Boolean value specifying whether the |
-|| _uri_supported || Wallet Instance supports the transfer of |
-|| || presentation_definition by |
-|| || reference, with true indicating support. |
-+---------------------------+-------------------------------------------+
++---------------------------+------------------------------------------------+
+| **key** | **value** |
++---------------------------+------------------------------------------------+
+|| iss || The public url of the Wallet |
+|| || Instance attestation issuer. See |
+|| || the example below in this section. |
++---------------------------+------------------------------------------------+
+|| sub || Thumbprint value |
+|| || of the JWK of the Wallet Instance |
+|| || for which the attestation is |
+|| || being issued. |
++---------------------------+------------------------------------------------+
+|| iat || Unix timestamp of attestation |
+|| || issuance time. |
++---------------------------+------------------------------------------------+
+|| exp || Unix timestamp regarding the |
+|| || expiration date time. |
+|| || A good practice to avoid security |
+|| || problems is to have a limited |
+|| || duration of the attestation. |
++---------------------------+------------------------------------------------+
+|| type || String: |
+|| || "WalletInstanceAttestation". |
++---------------------------+------------------------------------------------+
+|| policy_uri || URL to the privacy policy |
+|| || of the wallet. |
++---------------------------+------------------------------------------------+
+|| tos_uri || URL to the terms |
+|| || of use of the Wallet Provider. |
++---------------------------+------------------------------------------------+
+|| logo_uri || URL of the Wallet Provider logo in SVG format |
++---------------------------+------------------------------------------------+
+|| attested_security_context|| Attested security context: |
+|| || Represents a level of "trust" of |
+|| || the service containing a Level Of |
+|| || Agreement defined in the metadata |
+|| || of the Wallet Provider. |
++---------------------------+------------------------------------------------+
+|| cnf || This parameter contains the ``jwk`` |
+|| || parameter |
+|| || with the public key of the Wallet |
+|| || necessary for the holder binding. |
++---------------------------+------------------------------------------------+
+|| authorization_endpoint || URL of the OP's OAuth 2.0 |
+|| || Authorization Endpoint. |
++---------------------------+------------------------------------------------+
+|| response_types_supported || JSON array containing a list of |
+|| || the OAuth 2.0 response_type values |
+|| || that this OP supports. |
++---------------------------+------------------------------------------------+
+|| vp_formats_supported || JSON object containing |
+|| || ``jwt_vp_json`` and ``jwt_vc_json`` |
+|| || supported algorithms array. |
++---------------------------+------------------------------------------------+
+|| request_object_signing || JSON array containing a list of the |
+|| _alg_values_supported || JWS signing algorithms (alg values) |
+|| || supported by the OP for Request Objects. |
++---------------------------+------------------------------------------------+
+|| presentation_definition || Boolean value specifying whether the |
+|| _uri_supported || Wallet Instance supports the transfer of |
+|| || presentation_definition by |
+|| || reference, with true indicating support. |
++---------------------------+------------------------------------------------+
.. note::
- The claim ``asc`` (Attested Security Context) is under discussion
+ The claim ``attested_security_context`` (Attested Security Context) is under discussion
and must be intended as experimental.
-Signature
-^^^^^^^^^
+.. note::
-The Wallet Instance Attestation JWS is signed using the
-private key of the Wallet Provider.
+ The Wallet Instance Attestation JWS is signed using the private key of the Wallet Provider.
Below is an example of Wallet Instance Attestation:
@@ -478,7 +289,7 @@ Below is an example of Wallet Instance Attestation:
"eyJhbGciOiJFUz...jJLA",
"eyJhbGciOiJFUz...H9gw",
],
- "typ": "va+jwt",
+ "typ": "wallet-attestation+jwt",
"x5c": ["MIIBjDCC ... XFehgKQA=="]
}
.
@@ -489,7 +300,7 @@ Below is an example of Wallet Instance Attestation:
"policy_uri": "https://wallet-provider.example.org/privacy_policy",
"tos_uri": "https://wallet-provider.example.org/info_policy",
"logo_uri": "https://wallet-provider.example.org/logo.svg",
- "asc": "https://wallet-provider.example.org/LoA/basic",
+ "attested_security_context": "https://wallet-provider.example.org/LoA/basic",
"cnf":
{
"jwk":
@@ -520,28 +331,3 @@ Below is an example of Wallet Instance Attestation:
"iat": 1687281195,
"exp": 1687288395
}
-
-
-Endpoints
-~~~~~~~~~
-The Wallet Provider that issues the Wallet Instance Attestations must
-make available a series of APIs in REST format that follow the OpenID
-Federation standard.
-
-Metadata
-^^^^^^^^
-A **GET /.well-known/openid-federation endpoint** for retrieving the Wallet
-Provider Entity Configuration.
-
-Wallet Instance Attestation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A second **POST /token** endpoint that takes two parameters as input:
-
-``grant_type`` which in our case is a string:
-``urn:ietf:params:oauth:client-assertion-type:jwt-key-attestation``
-
-``assertion`` which contains the signed JWT of the Wallet Instance Attestation
-Request.
-
-The response will then contain the Wallet Instance Attestation.
diff --git a/docs/en/wallet-solution.rst b/docs/en/wallet-solution.rst
index 328cf07be..119eb441d 100644
--- a/docs/en/wallet-solution.rst
+++ b/docs/en/wallet-solution.rst
@@ -62,6 +62,200 @@ Deactivation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Users have the ability to deactivate the Wallet Instance voluntarily. This action removes the operational capabilities of the Wallet Instance and sets it to the deactivated state. Deactivation provides Users with control over access and usage according to their preferences.
+
+Wallet Provider Endpoints
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Wallet Provider that issues the Wallet Instance Attestations must
+make available a series of APIs in REST format that follow the OpenID
+Federation standard.
+
+Wallet Provider Metadata
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A **GET /.well-known/openid-federation endpoint** for retrieving the Wallet
+Provider Entity Configuration.
+
+The Wallet Provider Entity Configuration is a JWS containing the public keys and supported algorithms of the Wallet Provider metadata definition. It is structured in accordance with the `OpenID Connect Federation `_ and the Trust Model section outlined in this specification.
+
+Header
+^^^^^^
++---------+-----------------------------------------------------------------+
+| **Key** | **Value** |
++---------+-----------------------------------------------------------------+
+| alg | Algorithm employed to verify the token signature (e.g., ES256). |
++---------+-----------------------------------------------------------------+
+| kid | Thumbprint of the public key used for signing. |
++---------+-----------------------------------------------------------------+
+| typ | Media type, here we use the entity-statement+jwt value. |
++---------+-----------------------------------------------------------------+
+
+Payload
+^^^^^^^
++-----------------------------------+-----------------------------------+
+| **Key** | **Value** |
++-----------------------------------+-----------------------------------+
+| iss | Public URL of the Wallet |
+| | Provider. |
++-----------------------------------+-----------------------------------+
+| sub | Public URL of the Wallet |
+| | Provider. |
++-----------------------------------+-----------------------------------+
+| iat | Issuance datetime in |
+| | Unix Timestamp format. |
++-----------------------------------+-----------------------------------+
+| exp | Expiration datetime |
+| | in Unix Timestamp format. |
++-----------------------------------+-----------------------------------+
+| jwks | Contains an array of all public |
+| | keys associated with the domain. |
+| | These could match the Wallet |
+| | Provider's keys. |
++-----------------------------------+-----------------------------------+
+| metadata | For each entity, this attribute |
+| | houses its metadata. In this case,|
+| | it contains the Wallet Provider's |
+| | metadata within the |
+| | ``wallet_provider`` attribute |
+| | and the generic entity |
+| | ``federation_entity``. |
++-----------------------------------+-----------------------------------+
+
+Payload `wallet_provider`
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
++---------------------------------------------+---------------------------------------------------------------------+
+| **Key** | **Value** |
++---------------------------------------------+---------------------------------------------------------------------+
+| jwks | Contains an array of all the Wallet |
+| | Provider's public keys. |
++---------------------------------------------+---------------------------------------------------------------------+
+| token_endpoint | Endpoint for obtaining the Wallet |
+| | Instance Attestation. |
++---------------------------------------------+---------------------------------------------------------------------+
+| attested_security_context_values_supported | List of supported values for the |
+| | certified security context. These |
+| | values specify the security level |
+| | of the app—low, medium, or high. |
+| | An attested security context is |
+| | defined by the proof that the |
+| | Wallet Instance can send to the |
+| | Wallet Provider. Note: this |
+| | parameter is defined in this |
+| | specification |
++---------------------------------------------+---------------------------------------------------------------------+
+| grant_types_supported | The types of grants supported by |
+| | the endpoint token. It MUST be set to |
+| | ``urn:ietf:params:oauth:client-assertion-type:jwt-key-attestation`` |
++---------------------------------------------+---------------------------------------------------------------------+
+| token_endpoint_auth_methods_suppor | Supported authentication method for |
+| ted | the endpoint token. |
++---------------------------------------------+---------------------------------------------------------------------+
+| token_endpoint_auth_signing_alg_va | List of supported signature |
+| lues_supported | algorithms. |
++---------------------------------------------+---------------------------------------------------------------------+
+
+.. note::
+ The `asc_values_supported` parameter is experimental and under review.
+
+Payload `federation_entity`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
++-------------------+----------------------------------------------+
+| **Key** | **Value** |
++-------------------+----------------------------------------------+
+| organization_name | Organization name. |
++-------------------+----------------------------------------------+
+| homepage_uri | Organization's website URL. |
++-------------------+----------------------------------------------+
+| tos_uri | URL to the terms of service. |
++-------------------+----------------------------------------------+
+| policy_uri | URL to the privacy policy. |
++-------------------+----------------------------------------------+
+| logo_uri | URL of the organization's logo in SVG format.|
++-------------------+----------------------------------------------+
+
+Below a non-normative example of the Entity Configuration.
+
+.. code-block:: javascript
+
+ {
+ "alg": "ES256",
+ "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY",
+ "typ": "entity-statement+jwt"
+ }
+ .
+ {
+ "iss": "https://wallet-provider.example.org",
+ "sub": "https://wallet-provider.example.org",
+ "jwks": {
+ "keys": [
+ {
+ "crv": "P-256",
+ "kty": "EC",
+ "x": "qrJrj3Af_B57sbOIRrcBM7br7wOc8ynj7lHFPTeffUk",
+ "y": "1H0cWDyGgvU8w-kPKU_xycOCUNT2o0bwslIQtnPU6iM",
+ "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY"
+ }
+ ]
+ },
+ "metadata": {
+ "wallet_provider": {
+ "jwks": {
+ "keys": [
+ {
+ "crv": "P-256",
+ "kty": "EC",
+ "x": "qrJrj3Af_B57sbOIRrcBM7br7wOc8ynj7lHFPTeffUk",
+ "y": "1H0cWDyGgvU8w-kPKU_xycOCUNT2o0bwslIQtnPU6iM",
+ "kid": "5t5YYpBhN-EgIEEI5iUzr6r0MR02LnVQ0OmekmNKcjY"
+ }
+ ]
+ },
+ "token_endpoint": "https://wallet-provider.example.org/token",
+ "attested_security_context_values_supported": [
+ "https://wallet-provider.example.org/LoA/basic",
+ "https://wallet-provider.example.org/LoA/medium",
+ "https://wallet-provider.example.org/LoA/high"
+ ],
+ "grant_types_supported": [
+ "urn:ietf:params:oauth:client-assertion-type:jwt-key-attestation"
+ ],
+ "token_endpoint_auth_methods_supported": [
+ "private_key_jwt"
+ ],
+ "token_endpoint_auth_signing_alg_values_supported": [
+ "ES256",
+ "ES384",
+ "ES512"
+ ]
+ },
+ "federation_entity": {
+ "organization_name": "PagoPa S.p.A.",
+ "homepage_uri": "https://wallet-provider.example.org",
+ "policy_uri": "https://wallet-provider.example.org/privacy_policy",
+ "tos_uri": "https://wallet-provider.example.org/info_policy",
+ "logo_uri": "https://wallet-provider.example.org/logo.svg"
+ }
+ },
+ "iat": 1687171759,
+ "exp": 1709290159
+ }
+
+
+Wallet Instance Attestation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The **token** endpoint requires two parameters as input, in HTTP Post method:
+
+``grant_type`` which in our case is a string:
+``urn:ietf:params:oauth:client-assertion-type:jwt-key-attestation``
+
+``assertion`` which contains the signed JWT of the Wallet Instance Attestation
+Request.
+
+The response will then contain the Wallet Instance Attestation.
+
+
External references
^^^^^^^^^^^^^^^^^^^^
¹ Definitions are inherited from the EUDI Wallet Architecture and Reference Framework, version 1.1.0 at the time of writing. Please refer to `this page `_ for extended definitions and details.