diff --git a/docs/en/conf.py b/docs/en/conf.py index dd23e066e..d800baa6c 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -281,5 +281,5 @@ def setup(app): numfig = True -# to turn smartquotes off and be able to use ’ +# to turn smartquotes off and be able to use smartquotes = False diff --git a/docs/en/pid-eaa-data-model.rst b/docs/en/pid-eaa-data-model.rst index 8e7791f7b..da2a53bfc 100644 --- a/docs/en/pid-eaa-data-model.rst +++ b/docs/en/pid-eaa-data-model.rst @@ -275,7 +275,7 @@ The corresponding SD-JWT verson for PID is given by "jwk": { "kty": "RSA", "use": "sig", - "n": "1Ta-sE …", + "n": "1Ta-sE ...", "e": "AQAB", "kid": "YhNFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs" } diff --git a/docs/en/pid-eaa-issuance.rst b/docs/en/pid-eaa-issuance.rst index d4a87a50b..8c20535f8 100644 --- a/docs/en/pid-eaa-issuance.rst +++ b/docs/en/pid-eaa-issuance.rst @@ -13,13 +13,13 @@ The relevant entities and interfaces involved in the issuance flow are: - *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. - *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. + - 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 `_). - *(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. + - 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. @@ -916,7 +916,7 @@ Below is a non-normative example of an Entity Configuration containing an `openi "keys": [{ "kty": "RSA", "use": "sig", - "n": "1Ta-sE …", + "n": "1Ta-sE ...", "e": "AQAB", "kid": "FANFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs" }] diff --git a/docs/en/relying-party-solution.rst b/docs/en/relying-party-solution.rst index 4b71a1c97..9aac121b9 100644 --- a/docs/en/relying-party-solution.rst +++ b/docs/en/relying-party-solution.rst @@ -520,7 +520,7 @@ Below is a non-normative response example: "keys": [ { "kty": "RSA", - "n": "5s4qi …", + "n": "5s4qi ...", "e": "AQAB", "kid": "2HnoFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs" } @@ -536,7 +536,7 @@ Below is a non-normative response example: { "kty": "RSA", "use": "sig", - "n": "1Ta-sE …", + "n": "1Ta-sE ...", "e": "AQAB", "kid": "YhNFS3YnC9tjiCaivhWLVUJ3AxwGGz_98uRFaqMEEs", "x5c": [ "..." ] diff --git a/docs/en/revocation-lists.rst b/docs/en/revocation-lists.rst index 49cc7b174..1364cdf56 100644 --- a/docs/en/revocation-lists.rst +++ b/docs/en/revocation-lists.rst @@ -14,15 +14,19 @@ revocation-lists.rst General Properties ------------------ -[TODO] - +The revocation mechanism is designed to ensure privacy and control over the status of digital credentials. The Relying Party (RP) can check the status of the credentials but cannot continuously monitor them without control or limit. This is achieved by using sender-constrained tokens. Requirements ------------ - - req 1 - - req 2 - +- The RP MUST provide an ephemeral key for each requested credential within the presentation request. +- The Wallet Instance MUST issue a signed status list token, signed using the private key referred to the public one included in the credential cnf.jwk. +- The status list token MUST NOT contain any information about the RP. +- The signed status list token MUST be provided to the RP with a PoP bound to the ephemeral key provided by the RP. +- The RP can only use the status list token to access the RS that hosts the status list by cryptographically proving its possession. +- The RS that provides the status list MUST NOT know the identity of the client that consumes the status list. +- The status token MUST expire in a short period (less than hours), preventing any possibility to grant the access to that anonymous client the status list for that specific credential. +- Each time in the future the RP needs to check the status of a previously obtained digital credential, it MUST ask the Holder for a presentation of that digital credential (by type). Attributes ---------- @@ -42,8 +46,7 @@ Attributes Implementation considerations ----------------------------- -TODO - +The implementation of the revocation mechanism should consider the privacy of the user and the control over the status of the digital credentials. The use of sender-constrained tokens ensures that the RP cannot continuously monitor the status of the credentials without control or limit. Libraries and code snippets --------------------------- diff --git a/docs/en/trust.rst b/docs/en/trust.rst index 4f90eb96c..12ad942e1 100644 --- a/docs/en/trust.rst +++ b/docs/en/trust.rst @@ -80,7 +80,7 @@ OpenID Federation facilitates the building of an infrastructure that is: - **Secure and Tamper-proof**, Entities' attestations of metadata and keys are cryptographically signed in the Trust Chain, comprised of attestations issued by multiple parties. These attestations, called statements, cannot be forged or tampered by an adversary; - **Privacy-preserving**, the infrastructure is public and exposes public data such as public keys and metadata of the participants. It does not require authentication of the consumers and therefore does not track who is assessing trust against whom; - **Guarantor of the non-repudiation of long-lived attestations**, historical keys endpoints and historical Trust Chains are saved for years according to data retention policies. This enables the certification of the validity of historical compliance, even in cases of revocation, expiration, or rotation of the keys used for signature verification; -- **Dynamic and flexible**, any participants have the freedom to modify parts of their metadata autonomously, as these are published within their domains and verified through the Trust Chain. Simultaneously, the Trust Anchor or its Intermediate may publish a metadata policy to dynamically modify the metadata of all participants — such as disabling a vulnerable signature algorithm — and obtain certainty of propagation within a configured period of time within the federation; +- **Dynamic and flexible**, any participants have the freedom to modify parts of their metadata autonomously, as these are published within their domains and verified through the Trust Chain. Simultaneously, the Trust Anchor or its Intermediate may publish a metadata policy to dynamically modify the metadata of all participants - such as disabling a vulnerable signature algorithm - and obtain certainty of propagation within a configured period of time within the federation; - **Developer friendly**, JWT and JSON formats have been adopted on the web for years. They are cost-effective in terms of storage and processing and have a wide range of solutions available, such as libraries and software development kits, which enable rapid implementation of the solution; - **Scalable**, the Trust Model can accommodate more than a single organization by using Intermediates and multiple Trust Anchors where needed. @@ -107,7 +107,7 @@ In the table below is provided the map of the components that the ARF defines wi | | | Entity | | | | Statements | +----------------------------------------------------+--------------+----------------+ -| Relying Parties’ registration and authentication | |check-icon| | | +| Relying Parties' registration and authentication | |check-icon| | | | | | Trust Chains | | | | | | | | Federation | @@ -140,7 +140,7 @@ All the endpoints listed below are defined in the `OIDC-FED`_ specs. | federation metadata | **GET** .well-known/openid-federation |Metadata that an Entity | Intermediate | | | |publishes about itself, | | | | |verifiable with a trusted third | Wallet Provider| -| | |party (Superior Entity). It’s | | +| | |party (Superior Entity). It's | | | | |called Entity Configuration. | Relying Party | | | | | | | | | | Credential | @@ -153,7 +153,7 @@ All the endpoints listed below are defined in the `OIDC-FED`_ specs. | fetch endpoint | **GET** /fetch?sub=https://rp.example.org | | Trust Anchor | | | |Returns a signed document (JWS) | | | | |about a specific subject, its | Intermediate | -| | |Subordinate. It’s called Entity | | +| | |Subordinate. It's called Entity | | | | |Statement. | | +---------------------------+----------------------------------------------+--------------------------------+-----------------+ | trust mark status | **POST** /status?sub=...&trust_mark_id=... | | Trust Anchor | @@ -200,7 +200,7 @@ Below is a non-normative example of a Trust Anchor Entity Configuration, where e "keys": [ { "kty": "RSA", - "n": "3i5vV-_ …", + "n": "3i5vV-_ ...", "e": "AQAB", "kid": "FifYx03bnosD8m6gYQIfNHNP9cM_Sam9Tc5nLloIIrc", "x5c": [ ] @@ -571,7 +571,7 @@ Below is a non-normative example of a Trust Chain in its original format (JSON A .. note:: - The entire Trust Chain is verifiable by only possessing the Trust Anchor’s public keys. + The entire Trust Chain is verifiable by only possessing the Trust Anchor's public keys. Offline Trust Attestation Mechanisms diff --git a/docs/en/wallet-solution.rst b/docs/en/wallet-solution.rst index dfe8ab4ca..9dc0b9697 100644 --- a/docs/en/wallet-solution.rst +++ b/docs/en/wallet-solution.rst @@ -9,7 +9,7 @@ The Wallet Solution is a comprehensive product offered by the Wallet Provider to The Wallet Solution is issued by the Wallet Provider in the form of a mobile app, it also consists of services and web interfaces for the exchange of data between the Wallet Provider and its Wallet Instances for the requirements of the trust model and in total respect of the user's privacy, in accordance with national and EU legislation. -The mobile app serves as the primary interface for Users, allowing them to access and interact with their digital assets conveniently. These digital assets, known as Attestations, include Personal Identification Data (PID¹), a set of data that can uniquely identify a natural or a legal person, along with other Qualified and non-qualified Electronic Attestations of Attributes, also known as QEAAs and EAAs respectively, or (Q)EAAs for short¹. Once a User installs the mobile app on their device, it is referred to such an installation as a Wallet Instance for the User. +The mobile app serves as the primary interface for Users, allowing them to access and interact with their digital assets conveniently. These digital assets, known as Attestations, include Personal Identification Data (PID[1]), a set of data that can uniquely identify a natural or a legal person, along with other Qualified and non-qualified Electronic Attestations of Attributes, also known as QEAAs and EAAs respectively, or (Q)EAAs for short[1]. Once a User installs the mobile app on their device, it is referred to such an installation as a Wallet Instance for the User. By supporting the mobile app, the Wallet Provider plays a vital role in ensuring the security and reliability of the entire Wallet Solution, since it is responsible for issuing the Wallet Instance Attestation, that is a cryptographic proof that allow the evaluation of the authenticity and the integrity of the Wallet Instance. @@ -28,11 +28,11 @@ The Wallet Instance serves as a unique and secure device for authenticating the The Wallet Instance establishes the trust within the Wallet ecosystem by consistently presenting a Wallet Instance Attestation during interactions with other ecosystem actors such as PID Providers, (Q)EAA Providers, and Relying Parties. These verifiable attestations, provided by the Wallet Provider, reference the public part of the asymmetric cryptographic key owned by the Wallet Instance. Their purpose is to authenticate the Wallet Instance itself, ensuring its realiability when engaging with other ecosystem actors. -To guarantee the utmost security, these cryptographic keys are securely stored within the device's Trusted Execution Environment (TEE)³. This ensures that only the User is allowed to access them, thus preventing unauthorized usage or tampering. For more detailed information, please refer to the `Wallet Instance Attestation section`_ and the `Trust Model section`_ of this document. +To guarantee the utmost security, these cryptographic keys are securely stored within the device's Trusted Execution Environment (TEE)[3]. This ensures that only the User is allowed to access them, thus preventing unauthorized usage or tampering. For more detailed information, please refer to the `Wallet Instance Attestation section`_ and the `Trust Model section`_ of this document. Wallet Instance Lifecycle ^^^^^^^^^^^^^^^^^^^^^^^^^^ -The Wallet Instance has three distinct states: Operational, Valid, and Deactivated. Each state represents a specific functional status and determines the actions that can be performed². +The Wallet Instance has three distinct states: Operational, Valid, and Deactivated. Each state represents a specific functional status and determines the actions that can be performed[2]. Initialization Process ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -48,8 +48,8 @@ In order to securely and unambiguously identify Users, the Wallet Instance adopt Once the Wallet Instance is in the Operational state, Users can: - - Obtain, view, and manage (Q)EAAs from trusted (Q)EAA Providers¹; - - Authenticate to Relying Parties¹; + - Obtain, view, and manage (Q)EAAs from trusted (Q)EAA Providers[1]; + - Authenticate to Relying Parties[1]; - Authorize the presentation of their digital credentials with Relying Parties. Please refer to the relative sections for further information about PID and (Q)EAAs issuance and presentation. @@ -262,11 +262,11 @@ Please refer to the `Wallet Instance Attestation section`_. External references ^^^^^^^^^^^^^^^^^^^^ -¹ Definitions are inherited from the EUDI Wallet Architecture and Reference Framework, version 1.1.0 at the time of writing. Please refer to `this page `_ for extended definitions and details. +.. [1] Definitions are inherited from the EUDI Wallet Architecture and Reference Framework, version 1.1.0 at the time of writing. Please refer to `this page `_ for extended definitions and details. -² Wallet Instance states adhere to the EUDI Wallet Architecture and Reference Framework, as defined `here `_. +.. [2] Wallet Instance states adhere to the EUDI Wallet Architecture and Reference Framework, as defined `here `_. -³ Depending on the device operating system, TEE is defined by `Trusty`_ or `Secure Enclave`_ for Android and iOS devices, respectively. +.. [3] Depending on the device operating system, TEE is defined by `Trusty`_ or `Secure Enclave`_ for Android and iOS devices, respectively. .. _Trust Model section: trust.html .. _Wallet Instance Attestation section: wallet-instance-attestation.html