feat: added new lifecycle section #532

giadas · 2025-01-21T14:54:48Z

This PR:

closes Relationship between Wallet instance lifecycle and other Credentials stored #279 by detailing the Wallet Instance and Digital Credentials lifecycle and their relationships in the IT Wallet
closes Alignment Wallet Istance Lifecycle to ARF v1.4 #446 by aligning the states and transitions of the Wallet Instance lifecycle with the ARF v1.4.1

We have:

removed “Wallet Instance Lifecycle” section from Wallet Solution section;
removed “Wallet Instance Lifecycle” section from Wallet Attestation section;
created a new section “Wallet Instance and Digital Credential Lifecycle” (merge of the previous 2 plus new text from the analysis of ARF v1.4.1 + state and transitions related to Digital Credentials).

docs/en/lifecycle.rst

Co-authored-by: Giuseppe De Marco <demarcog83@gmail.com>

peppelinux · 2025-01-23T15:07:43Z

docs/en/lifecycle.rst

+
+A Credential Issuer is responsible for creating and issuing Digital Credentials, as well as managing their lifecycle and validity status. 
+
+An Authentic Source is the entity responsible for the management and provisioning of User's attributes to Credential Issuers. 


Suggested change

An Authentic Source is the entity responsible for the management and provisioning of User's attributes to Credential Issuers.

The Authentic Source is the entity responsible for the management and provisioning of User's attributes to Credential Issuers.

peppelinux · 2025-01-23T15:07:51Z

docs/en/lifecycle.rst

+Wallet Instance and Digital Credential Lifecycle
++++++++++++++++++++++++++++++++++++++++++++++++
+
+A Credential Issuer is responsible for creating and issuing Digital Credentials, as well as managing their lifecycle and validity status. 


Suggested change

A Credential Issuer is responsible for creating and issuing Digital Credentials, as well as managing their lifecycle and validity status.

The Credential Issuer is responsible for creating and issuing Digital Credentials, as well as managing their lifecycle and validity status.

this and the one below seems more redefinition of what already defined within the defined terms ... but, since they are so small, we can live with them anyway.

peppelinux · 2025-01-23T15:11:56Z

docs/en/lifecycle.rst

+suspension of the attributes contained in the Digital Credential. In IT Wallet, the provisioning of User's attributes and the notification of 
+updates or changes in the state of the attributes are exchanged using the PDND infrastructure (see relative sections for more details).
+
+Finally, a Wallet Provider is in charge of the implementation and provision of Wallet Instances also handling their entire lifecycle. 


Suggested change

Finally, a Wallet Provider is in charge of the implementation and provision of Wallet Instances also handling their entire lifecycle.

The Wallet Provider is in charge of the implementation and provision of Wallet Instances also handling their entire lifecycle.

peppelinux · 2025-01-23T15:15:20Z

docs/en/lifecycle.rst

+
+.. note::
+
+  We distinguish PID from (Q)EAA, as its issuance effects on the Wallet Instance's lifecycle, and additionally its revocation may have potential impacts on (Q)EAAs. 


Suggested change

We distinguish PID from (Q)EAA, as its issuance effects on the Wallet Instance's lifecycle, and additionally its revocation may have potential impacts on (Q)EAAs.

PID is specialized Credential type that produces impacts on the Wallet Instance's lifecycle. The revocation of the PID MAY also have potential impacts on (Q)EAAs, if these was issued using the presentation of the PID.

aridanghete con "we" :-)

peppelinux · 2025-01-23T15:16:32Z

docs/en/lifecycle.rst

+
+.. note::
+
+  In the current version of ARF v1.4.1, two types of attestations have been introduced: Wallet Trust Evidence (WTE) and Wallet Instance Attestation (WIA). The first to prove that the keys used for key 


Suggested change

In the current version of ARF v1.4.1, two types of attestations have been introduced: Wallet Trust Evidence (WTE) and Wallet Instance Attestation (WIA). The first to prove that the keys used for key

In the current version of `ARF`_, two types of attestations have been introduced: Wallet Trust Evidence (WTE) and Wallet Instance Attestation (WIA). The first to prove that the keys used for key

the version of the ARF in use and referenced in this documentation is the one defined in the referenced standards. We really do not have to disseminate weak or static references within the specs

I would like to have the alignments with the IA terminology too- Otherwise we will use a separate PR within milestone 1.0 to have this alignment

peppelinux · 2025-01-23T15:18:48Z

docs/en/lifecycle.rst

+
+.. note::
+
+  The Wallet Provider MUST ensure the security and reliability of the Wallet Instances. To achieve this, the Wallet Provider MUST keep the Wallet Instances updated and compliant with security requirements. 


Suggested change

The Wallet Provider MUST ensure the security and reliability of the Wallet Instances. To achieve this, the Wallet Provider MUST keep the Wallet Instances updated and compliant with security requirements.

The Wallet Provider MUST ensure the security and reliability of the Wallet Instances. To achieve this, the Wallet Provider MUST periodically checks the Wallet Instances security and compliance status.

only the user can update the WI

peppelinux · 2025-01-23T15:21:42Z

docs/en/lifecycle.rst

+.. note::
+
+  As a result of the User account creation, an authentication mechanism MUST be set for the User to interact with the Wallet Provider portal. 
+  This specification mandates the use of at least a second-factor User authentication.  


Suggested change

This specification mandates the use of at least a second-factor User authentication.

This specification mandates the use of at least a second-factor for User authentication.

we should mention an internional LoA threshold, such those defined in NIST ...

AFAIK, this is not defined in EUDI yet. I suggest to wait for an update from EU before define more details here. What do you think?

peppelinux · 2025-01-23T15:22:43Z

docs/en/lifecycle.rst

+
+As part of the activation, the Wallet Provider MUST evaluate the operating system and general technical capabilities of the device to check compliance 
+with the technical and security requirements, and the authenticity and integrity of the installed Wallet Instance. 
+Upon successful verification, a Wallet Attestation MUST be issued and the Wallet Instance enters the **Operational** state. 


Suggested change

Upon successful verification, a Wallet Attestation MUST be issued and the Wallet Instance enters the **Operational** state.

Upon successful verification, the Wallet Provider MUST issue at least one valid Wallet Attestation to the Wallet Instance, therefore the Wallet Instance enters the **Operational** state.

peppelinux · 2025-01-23T15:24:30Z

docs/en/lifecycle.rst

+In addition, if not already done, Users MUST set their preferred method of unlocking their Wallet Instance; this can be accomplished by entering a 
+personal identification number (PIN) or by utilizing biometric authentication, such as fingerprint or facial recognition, according to their personal 


Suggested change

In addition, if not already done, Users MUST set their preferred method of unlocking their Wallet Instance; this can be accomplished by entering a

personal identification number (PIN) or by utilizing biometric authentication, such as fingerprint or facial recognition, according to their personal

In addition, if not already done, Users MUST set their preferred method of unlocking their Wallet Instance; this MAY be accomplished by entering a

personal identification number (PIN) or by utilizing biometric authentication, such as fingerprint or facial recognition, according to personal

peppelinux · 2025-01-23T15:25:20Z

docs/en/lifecycle.rst

+personal identification number (PIN) or by utilizing biometric authentication, such as fingerprint or facial recognition, according to their personal 
+preferences and device's capabilities. Please refer to the relevant sections for further information about Wallet Instance activation.
+
+In this state, Users can request the issuance of a PID (**PID ISS** transition) or of (Q)EAAs if the PID is not required in the issuance phase 


Suggested change

In this state, Users can request the issuance of a PID (**PID ISS** transition) or of (Q)EAAs if the PID is not required in the issuance phase

In the Operational state, Users can request the issuance of PID (**PID ISS**) or (Q)EAAs if the PID is not required in the issuance

remember to put the subject to make the sentence always linear and clear

peppelinux · 2025-01-23T15:26:24Z

docs/en/lifecycle.rst

+preferences and device's capabilities. Please refer to the relevant sections for further information about Wallet Instance activation.
+
+In this state, Users can request the issuance of a PID (**PID ISS** transition) or of (Q)EAAs if the PID is not required in the issuance phase 
+(**(Q)EEA ISS** transitions). In addition, if the credentials are (Q)EEAs and for the presentation they do not require the PID, they can be presented 


Suggested change

(**(Q)EEA ISS** transitions). In addition, if the credentials are (Q)EEAs and for the presentation they do not require the PID, they can be presented

(**(Q)EEA ISS**). In addition, if the Credentials are (Q)EEAs and for the presentation they do not require the PID, they can be presented

peppelinux · 2025-01-23T15:27:13Z

docs/en/lifecycle.rst

+A **Valid** Wallet Instance MUST transition back to the **Operational** state due to **PID EXP/REV/DEL** transition, when the associated PID expires, or 
+revoked by its Provider or either deleted by the User. 


Suggested change

A **Valid** Wallet Instance MUST transition back to the **Operational** state due to **PID EXP/REV/DEL** transition, when the associated PID expires, or

revoked by its Provider or either deleted by the User.

A **Valid** Wallet Instance MUST transition back to the **Operational** state due to **PID EXP/REV/DEL** transition, when the associated PID expires, or is revoked by its Provider or either deleted by the User.

peppelinux · 2025-01-23T15:27:50Z

docs/en/lifecycle.rst

+.. note::
+
+  Users can have only one Wallet Instance in **Valid** state for the same Wallet Solution. Thus, when a User installs and obtains a PID on a new Wallet 
+  Instance of the same Wallet Solution from the same Wallet Provider, the PID in the previous Wallet Instance MUST be revoked and the Wallet Instance goes 


Suggested change

Instance of the same Wallet Solution from the same Wallet Provider, the PID in the previous Wallet Instance MUST be revoked and the Wallet Instance goes

Instance of the same Wallet Solution from the same Wallet Provider, the PID in the previous Wallet Instance MUST be revoked and the Wallet Instance became

peppelinux · 2025-01-23T15:28:00Z

docs/en/lifecycle.rst

+
+  Users can have only one Wallet Instance in **Valid** state for the same Wallet Solution. Thus, when a User installs and obtains a PID on a new Wallet 
+  Instance of the same Wallet Solution from the same Wallet Provider, the PID in the previous Wallet Instance MUST be revoked and the Wallet Instance goes 
+  into **Operational** state.


Suggested change

into **Operational** state.

**Operational**.

peppelinux · 2025-01-23T15:28:28Z

docs/en/lifecycle.rst

+
+Transition to Uninstalled
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Across all states — **Installed**, **Actived**, **Operational**, or **Valid** — the Wallet Instance may be removed entirely through the Wallet Instance 


Suggested change

Across all states — **Installed**, **Actived**, **Operational**, or **Valid** — the Wallet Instance may be removed entirely through the Wallet Instance

Across all states, **Installed**, **Actived**, **Operational**, or **Valid**, the Wallet Instance can be removed entirely through the Wallet Instance

peppelinux · 2025-01-23T15:38:41Z

docs/en/lifecycle.rst

+.. note::
+
+  While **Issued**, **Valid**, **Expired**, **Revoked** are explicitly mentioned in the ARF (see Figure 5 of ARF v1.4), 
+  **Suspended** is implicitly present in the text. For clarity and completeness, in this specification we explicitly consider it.


Suggested change

**Suspended** is implicitly present in the text. For clarity and completeness, in this specification we explicitly consider it.

**Suspended** is implicitly present in `ARF`_. This specification explicitly considers it.

peppelinux · 2025-01-23T15:39:02Z

docs/en/lifecycle.rst

+
+Transition to Issued
+^^^^^^^^^^^^^^^^^^^^
+For the state machine to start, the Wallet Instance MUST be in either the **Operational** or **Valid** state, enabling credentials to be issued to it. 


Suggested change

For the state machine to start, the Wallet Instance MUST be in either the **Operational** or **Valid** state, enabling credentials to be issued to it.

For the state machine to start, the Wallet Instance MUST be in either the **Operational** or **Valid** state, enabling Credentials to be issued to it.

peppelinux · 2025-01-23T15:40:15Z

docs/en/lifecycle.rst

+^^^^^^^^^^^^^^^^^^^^
+For the state machine to start, the Wallet Instance MUST be in either the **Operational** or **Valid** state, enabling credentials to be issued to it. 
+The state machine begins with the **Issued** state, when an issuance process is triggered and, as a result, a Digital Credential is issued to the 
+Wallet Instance (**PID/(Q)EAA ISS**). Please refer to the relevant sections for further information about PID and (Q)EAAs issuance process.


Suggested change

Wallet Instance (**PID/(Q)EAA ISS**). Please refer to the relevant sections for further information about PID and (Q)EAAs issuance process.

Wallet Instance (**PID/(Q)EAA ISS**). Please refer to the relevant sections for further information about PID and (Q)EAAs issuance process.

I admit to get tired to read so many times the statement Please refer to the relevant sections for further information about. I ask to use a shorter sentece with a href reference to the relevant section, or delete the entire statement.

peppelinux · 2025-01-23T15:44:34Z

docs/en/lifecycle.rst

+A Digital Credential changes from **Issued**, **Valid** or **Suspended** states to **Revoked** state when it is actively revoked by the Credential Issuer 
+by a revocation process (**PID/(Q)EAA REV**), declaring that Relying Parties SHOULD no longer trust a particular Digital Credential, even though it is 
+still valid temporally and contains a valid Credential Issuer signature. Revocation can occur in the following cases:


Suggested change

A Digital Credential changes from **Issued**, **Valid** or **Suspended** states to **Revoked** state when it is actively revoked by the Credential Issuer

by a revocation process (**PID/(Q)EAA REV**), declaring that Relying Parties SHOULD no longer trust a particular Digital Credential, even though it is

still valid temporally and contains a valid Credential Issuer signature. Revocation can occur in the following cases:

A Digital Credential changes from **Issued**, **Valid** or **Suspended** states to **Revoked** state when it is actively revoked by the Credential Issuer

by a revocation process (**PID/(Q)EAA REV**). The Relying Parties SHOULD no longer consider usable a particular Digital Credential when it is **Revoked**, even though it is

still valid temporally and contains a valid Credential Issuer signature. Revocation can occur in the following cases:

peppelinux · 2025-01-23T15:57:51Z

docs/en/lifecycle.rst

+In the case of PID only, the following cases are in addition to those listed above:
+
+  * detection of a breach of the digital identity issued by an Identity Provider and used to authenticate the User during the PID Issuance;
+  * as a result of obtaining a new PID on a new Wallet Instance from the same Wallet Provider that provided the Wallet Instance containing the previous PID.


Suggested change

* as a result of obtaining a new PID on a new Wallet Instance from the same Wallet Provider that provided the Wallet Instance containing the previous PID.

* as a result of obtaining a new PID on a new Wallet Instance from the same Wallet Provider that has provided the Wallet Instance containing a PID previously issued.

peppelinux · 2025-01-23T16:00:03Z

docs/en/lifecycle.rst

+A (Q)EAA changes from **Issued** or **Valid** states to **Suspended** state when it is suspended by the Credential Issuer (**(Q)EAA SUSP**), 
+it stays in this state until it is restored to the **Issued** or **Valid** state (**(Q)EAA UNSUSP**) depending on the previous state, i.e. 
+the conditions leading to its suspension are resolved, or it changes in **Revoked**, **Expired** or it is deleted. The suspension of a (Q)EAA MAY be: 


Suggested change

A (Q)EAA changes from **Issued** or **Valid** states to **Suspended** state when it is suspended by the Credential Issuer (**(Q)EAA SUSP**),

it stays in this state until it is restored to the **Issued** or **Valid** state (**(Q)EAA UNSUSP**) depending on the previous state, i.e.

the conditions leading to its suspension are resolved, or it changes in **Revoked**, **Expired** or it is deleted. The suspension of a (Q)EAA MAY be:

A (Q)EAA changes from **Issued** or **Valid** states to **Suspended** state when it is suspended by the Credential Issuer (**(Q)EAA SUSP**).

The (Q)EAA remains **Suspended** until it is restored to the **Issued** or **Valid** state (**(Q)EAA UNSUSP**) depending on the previous state, i.e.

the conditions leading to its suspension are resolved, or it changes in **Revoked**, **Expired** or it is deleted. The suspension of a (Q)EAA MAY be:

peppelinux · 2025-01-23T16:02:07Z

docs/en/lifecycle.rst

+A Credential Issuer instead is responsible for:
+
+  * **Digital Credential Generation**: the Digital Credential is generated as a consequence of an issuance request and MUST be added to the local storage of the Credential Issuer after the successful issuance. 
+  * **Digital Credential Revocation/Suspension/Unsuspension** (**PID/(Q)EAA REV** and **(Q)EAA SUSP/UNSUSP**): for technical security reasons or triggered by  external entities (e.g., Users and Authentic Sources) the Digital Credential state MUST be locally updated.


Suggested change

* **Digital Credential Revocation/Suspension/Unsuspension** (**PID/(Q)EAA REV** and **(Q)EAA SUSP/UNSUSP**): for technical security reasons or triggered by external entities (e.g., Users and Authentic Sources) the Digital Credential state MUST be locally updated.

* **Digital Credential Revocation/Suspension/Unsuspension** (**PID/(Q)EAA REV** and **(Q)EAA SUSP/UNSUSP**): for technical security reasons or triggered by external entities (e.g., Users and Authentic Sources) the Digital Credential state MUST be locally updated.

peppelinux

few editorials. I am wondering if there might be some chance to reduce some text making this section more small

feat: added new lifecycle section

7224f94

giadas requested review from grausof, peppelinux, fmarino-ipzs and m-basili January 21, 2025 15:34

peppelinux reviewed Jan 21, 2025

View reviewed changes