ACN's security and architecture scomposition and harmonization for certification purposes by peppelinux · Pull Request #1025 · italia/eid-wallet-it-docs

peppelinux · 2026-02-16T10:35:23Z

This pull request resolves #894, #895 and #896.

It introduces a comprehensive annex describing the certification scheme and component decomposition for the IT-Wallet system, clarifies certification scope and terminology, and aligns technical documentation with regulatory requirements (notably CIR 2024/2981). It also updates definitions and acronyms to support these changes, and makes minor clarifications in related sections.

Certification Scheme and Component Decomposition:

Added a new annex (annex-certification-scheme.rst) that details the certification scheme, including regulatory background, decomposition hierarchy, in-scope and out-of-scope components, and cross-references to technical specifications. This annex clarifies which system components require certification and under what circumstances, in line with CIR 2024/2981. [1] [2]
Updated architecture overview and credential issuer documentation to reference the new certification scheme, explicitly listing components in and out of scope for certification, and mapping technical components to certification macro-components. [1] [2]

Terminology and Definitions:

Expanded the definitions in defined-terms.rst to include new terms such as "Certification Scope," "Certification Macro-component," "Identity Proofing," "NPID," "WL2," "WL3," and others, ensuring clear understanding of certification-related concepts. [1] [2] [3] [4] [5]
Added and updated acronyms for new and existing components (e.g., ICT, NPID, PPBE, WL2, WL3, WPBE, WWI) to support the expanded terminology. [1] [2] [3]

Regulatory References:

Added new regulatory hyperlinks (e.g., CIR 2024/2981, Regulation (EU) 2016/679) to the common definitions file for consistent referencing throughout the documentation.

Security and Certification Requirements:

Clarified and enforced requirements for WSCD security levels (WL2 and WL3) in the credential issuance flow and credential issuer requirements, specifying which security level is needed for each credential type (PID, NPID, (Q)EAA). [1] [2] [3]

Minor Documentation Improvements:

Made minor wording clarifications in the architecture overview and credential issuance flow for consistency and clarity. [1] [2]

These changes collectively improve the clarity and completeness of the IT-Wallet system's certification documentation and ensure alignment with current regulatory requirements.

…tion

Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # docs/en/wallet-solution-requirements.rst

Copilot

Pull request overview

This PR updates the IT-Wallet technical documentation to align with ACN/ENISA-style certification decomposition and CIR 2024/2981, introducing a dedicated certification annex and propagating certification scope / component mapping across architecture and requirements sections.

Changes:

Added a new certification annex (EN/IT) describing the certification scheme, in-scope/out-of-scope components, and cross-references.
Reworked Wallet Solution requirements (EN/IT) into decomposition-aligned requirement tables and added WSCD WL2/WL3 security-level constraints across lifecycle/issuance/issuer sections.
Updated common references/glossary/acronyms and improved CI pip caching configuration.

Reviewed changes

Copilot reviewed 37 out of 37 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
preview_build/requirements.txt	Removed legacy local preview build dependency list.
preview_build/preview_configuration.py	Removed legacy Sphinx preview configuration.
preview_build/build.sh	Removed legacy local preview build script.
docs/common/common_definitions.rst	Added shared hyperlinks for CIR 2024/2981 and GDPR (Reg. 2016/679).
docs/it/appendix.rst	Included the new certification annex in the IT appendix.
docs/it/annex-certification-scheme.rst	Added IT annex describing certification scheme and decomposition approach.
docs/it/credential-issuer-solution.rst	Added certification decomposition mapping for PID Provider (PPBE) and WSCD level checks.
docs/it/credential-issuance-high-level.rst	Added explicit WL3 requirement check for PID issuance.
docs/it/defined-terms.rst	Extended terms/acronyms to support certification decomposition terminology.
docs/it/how-to-read-spec.rst	Updated references to use the new `test-plans` anchors.
docs/it/normative-ref.rst	Added CIR 2024/2981 to normative references.
docs/it/test-plans.rst	Added `test-plans` anchor and minor wording update.
docs/it/test-plans-wallet-provider.rst	Added `test-plans-wallet-provider` anchor.
docs/it/wallet-attestation-issuance.rst	Added WSCD WL2/WL3 classification step during WAA/WUA issuance flow.
docs/it/wallet-instance-lifecycle.rst	Added WSCD WL2/WL3 classification requirement during activation.
docs/it/wallet-solution-components.rst	Added decomposition+certification scope mapping section and expanded Secure Storage description.
docs/it/wallet-solution-requirements.rst	Converted requirements into decomposition/scoping tables and added WSCD security-level section.
docs/it/wallet-solution.rst	Added Wallet Solution certification decomposition overview and references.
docs/en/appendix.rst	Included the new certification annex in the EN appendix.
docs/en/annex-certification-scheme.rst	Added EN annex describing certification scheme and decomposition approach.
docs/en/architecture-overview.rst	Added certification/conformity assessment as an explicit core interaction process.
docs/en/credential-issuer-solution.rst	Added certification decomposition mapping for PID Provider (PPBE) and WSCD level checks.
docs/en/credential-issuance-high-level.rst	Added explicit WL3 requirement check for PID issuance.
docs/en/defined-terms.rst	Added certification/decomposition terms plus WL2/WL3 and NPID definitions/acronyms.
docs/en/how-to-read-spec.rst	Updated references to use the new `test-plans` anchors.
docs/en/normative-ref.rst	Added CIR 2024/2981 to normative references.
docs/en/test-plans.rst	Added `test-plans` anchor and minor wording update.
docs/en/test-plans-wallet-provider.rst	Added `test-plans-wallet-provider` anchor.
docs/en/wallet-attestation-issuance.rst	Added WSCD WL2/WL3 classification step during WAA/WUA issuance flow.
docs/en/wallet-instance-lifecycle.rst	Added WSCD WL2/WL3 classification requirement during activation.
docs/en/wallet-solution-components.rst	Added decomposition+certification scope mapping section and expanded Secure Storage description.
docs/en/wallet-solution-requirements.rst	Converted requirements into decomposition/scoping tables and added WSCD security-level section.
docs/en/wallet-solution.rst	Added Wallet Solution certification decomposition overview and references.
.github/workflows/ci-html.yml	Improved pip cache keying by setting `cache-dependency-path` to requirements-dev.txt.
.github/workflows/build-pdf.yml	Improved pip cache keying by setting `cache-dependency-path` to requirements-dev.txt.
.github/workflows/build-html.yml	Improved pip cache keying by setting `cache-dependency-path` to requirements-dev.txt.
.github/workflows/build-html-manual.yml	Improved pip cache keying by setting `cache-dependency-path` to requirements-dev.txt.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…the merge conflict

Copilot

Pull request overview

Copilot reviewed 37 out of 37 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-16T16:59:07Z

+     - The Wallet Unit Attestation MUST NOT be issued by the Wallet Provider if the WSCD trustworthiness is not guaranteed. In this case, the Wallet Instance MUST be revoked.
+     - WPBE, WI
+   * - WUA-011
+     - An Attestation Provider issuing non-device-bound attestations SHALL indicate in its Credential Issuer metadata that it does not need a WUA. A Wallet Unit SHALL NOT send a WUA to an Attestation Provider when requesting a non-device-bound attestation. Note: A Wallet Unit sends a WIA to the Attestation Provider regardless of whether the attestations it issues are device-bound or not.


The acronym "WIA" is used in the note but is not defined in the glossary or acronyms section. Based on context, this might be intended to refer to "WAA" (Wallet App Attestation), or it could be a shorthand for "Wallet Instance Attestation". Please verify that this acronym is correct and consider adding it to the defined terms if it's intentional, or correct it to "WAA" if it's a typo.

Suggested change

- An Attestation Provider issuing non-device-bound attestations SHALL indicate in its Credential Issuer metadata that it does not need a WUA. A Wallet Unit SHALL NOT send a WUA to an Attestation Provider when requesting a non-device-bound attestation. Note: A Wallet Unit sends a WIA to the Attestation Provider regardless of whether the attestations it issues are device-bound or not.

- An Attestation Provider issuing non-device-bound attestations SHALL indicate in its Credential Issuer metadata that it does not need a WUA. A Wallet Unit SHALL NOT send a WUA to an Attestation Provider when requesting a non-device-bound attestation. Note: A Wallet Unit sends a WAA to the Attestation Provider regardless of whether the attestations it issues are device-bound or not.

WAA doesn not exist anymore, #1031 aligns the specification according to this evidence.

Copilot · 2026-02-16T16:59:08Z

+     - La Wallet Unit Attestation NON DEVE essere emessa dal Wallet Provider se l'affidabilità del WSCD non è garantita. In tal caso, l'istanza del Wallet DEVE essere revocata.
+     - WPBE, WI
+   * - WUA-011
+     - Un Attestation Provider che emette attestazioni non vincolate al dispositivo DEVE indicare nei propri metadati del Credential Issuer che non richiede una WUA. Una Wallet Unit NON DEVE inviare una WUA a un Attestation Provider quando richiede un'attestazione non vincolata al dispositivo. Nota: Una Wallet Unit invia una WIA all'Attestation Provider indipendentemente dal fatto che le attestazioni emesse siano vincolate o meno al dispositivo.


L'acronimo "WIA" è utilizzato nella nota ma non è definito nel glossario o nella sezione acronimi. In base al contesto, potrebbe essere inteso come riferimento a "WAA" (Wallet App Attestation), oppure potrebbe essere un'abbreviazione per "Wallet Instance Attestation". Si prega di verificare che questo acronimo sia corretto e di considerare di aggiungerlo ai termini definiti se è intenzionale, o di correggerlo in "WAA" se si tratta di un errore di battitura.

WAA does not exist anymore, the alignment with WIA is provided at #1031

…tion

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Lia <139998796+RosaliaGaleano@users.noreply.github.com>

peppelinux · 2026-02-18T12:03:13Z

During the meeting of 18 feb 2025, we agreed that this PR is about LTS and to be included in the LTS it must remove the NPID, since only this represent a breaking change.

fmarino-ipzs

We should clarify whether the national eID schemes will be under the proposed decomposition before merging this PR.

fmarino-ipzs · 2026-03-02T22:43:57Z

+     - :ref:`trust-infrastructure:The Infrastructure of Trust`
+   * - **Regime di identificazione elettronica** (eID Scheme)
+     - Cross-cutting (Wallet Provider and PID Provider)
+     - National eID schemes (CIEid, SPID); :ref:`credential-issuance-l2plus:eID Substantial Authentication with MRTD Verification for PID Issuance`


See my comment in #1051 (comment)

fmarino-ipzs · 2026-03-02T22:49:21Z

+   * - eID Scheme
+     - National eID schemes; :ref:`credential-issuance:Digital Credential Issuance`
+     - Regime di identificazione elettronica


I'm not sure. eID schemes are notified according to the eIDAS Regulation, and they don't require further certification. Instead, the "new" eID scheme based on Wallet+PID is in scope.

Further ACN review on scomposition and updates

Sh-Amir · 2026-03-03T13:41:05Z

+The Wallet Solution architecture is described according to the certification macro-component **Servizi ICT Wallet** (owner: Wallet Provider). It comprises the following components and sub-components, all of which fall within certification scope:
+
+- **Wallet Instance (WI)**:
+  - Application Logic: User Interface, Issuer Component, Presentation Component, Wallet Instance Lifecycle Management


Dashboard and Log Management is missing probabaly

ZAnsaroudi · 2026-03-03T10:31:01Z

+
+- **Wallet Instance (WI)**:
+  - Application Logic: User Interface, Issuer Component, Presentation Component, Wallet Instance Lifecycle Management
+  - Local Data management: Local Data Store, Backup and Restore Component, Secure Storage interaction


What about "Dashboard and Transaction Log Component"?

Sh-Amir

I added some comments for the parts that may need some clarification and the rest looks good to me.

ghost · 2026-03-04T09:35:56Z

This change may be better introduced in the next version rather than the current one

Co-authored-by: ZAnsaroudi <ZEBADIANSAROUDI@FBK.EU>

Copilot

Copilot reviewed 38 out of 38 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

gmessori18 and others added 4 commits February 5, 2026 15:23

feat: integrate ACN WSCD security level breakdown across technical specs

b5687a3

feat: certification scheme harmonization according to ACN's decomposi…

4e4e00a

…tion

editorials: security certifications and arch scomposition

7703998

editorial: italian version alignments on certification/scomposition

3bcec3e

peppelinux requested review from fmarino-ipzs, giadas and grausof February 16, 2026 10:35

peppelinux added 7 commits February 16, 2026 11:39

Merge versione-corrente: preserve updates, adapt to scomposizione

c92085c

Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # docs/en/wallet-solution-requirements.rst

ci: pip cache

e39251e

fix: broken label/href

d82e6a5

fix: RST linting

d26d855

fix: RST line indentation

6ae0927

fix: undefined label test-plans refs in annex-certification-scheme

8cba4ea

fix: missing labels along with scomposition updates

1137483

peppelinux requested a review from Copilot February 16, 2026 11:55

Copilot started reviewing on behalf of peppelinux February 16, 2026 11:55 View session

Copilot AI reviewed Feb 16, 2026

View reviewed changes

peppelinux and others added 3 commits February 16, 2026 17:36

Apply suggestions from code review

8908694

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fix: reintroduces missing wallet solution requirements missed during …

1f7e0a2

…the merge conflict

fix: italian terms about certification purposes

73cbac6

peppelinux requested a review from Copilot February 16, 2026 16:53

Copilot started reviewing on behalf of peppelinux February 16, 2026 16:54 View session

Copilot AI reviewed Feb 16, 2026

View reviewed changes

peppelinux and others added 2 commits February 17, 2026 10:17

fix: italian version missing point on architecture overview certifica…

a0ff222

…tion

Apply suggestions from code review

120b0a5

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

RosaliaGaleano reviewed Feb 17, 2026

View reviewed changes

Comment thread docs/en/annex-certification-scheme.rst Outdated

Apply suggestions from code review

06bb7ec

Co-authored-by: Lia <139998796+RosaliaGaleano@users.noreply.github.com>

peppelinux requested a review from RosaliaGaleano February 17, 2026 17:05

peppelinux added the LTS label Feb 18, 2026

peppelinux added 4 commits February 26, 2026 13:14

Marino review on WSCD loa high

fe40af8

Marino review on unsupported nonce flows during credential issuance

1042ce5

Marino review on sec cons on wallet solution requirements

51d15b5

Marino review on certification constraints

5757d1e

peppelinux requested review from fmarino-ipzs February 26, 2026 12:24

peppelinux added 2 commits February 26, 2026 13:29

fix: missing label

8f0c483

Apply suggestions from code review

b13b42a

giadas requested review from Sh-Amir and ZAnsaroudi and removed request for giadas February 26, 2026 13:21

peppelinux added 3 commits February 26, 2026 15:53

removal of repetition about WL3

937f1c0

further ACN review on scomposition and updates

e4c00c9

fix: heading too short

232a05d

fmarino-ipzs requested changes Mar 2, 2026

View reviewed changes

fmarino-ipzs mentioned this pull request Mar 3, 2026

Further ACN review on scomposition and updates #1051

Merged

Merge pull request #1051 from italia/acn_rev

687f795

Further ACN review on scomposition and updates

Sh-Amir reviewed Mar 3, 2026

View reviewed changes

ZAnsaroudi requested changes Mar 3, 2026

View reviewed changes

Sh-Amir reviewed Mar 3, 2026

View reviewed changes

Apply suggestions from code review

61c99c6

Co-authored-by: ZAnsaroudi <ZEBADIANSAROUDI@FBK.EU>

peppelinux added eudiw and removed LTS labels Mar 18, 2026

grausof requested a review from Copilot March 26, 2026 14:38

Copilot started reviewing on behalf of grausof March 26, 2026 14:38 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

giadas added this to the 1.4.2 milestone May 12, 2026

peppelinux modified the milestones: 1.4.2, 1.5.0 Jun 9, 2026

	- An Attestation Provider issuing non-device-bound attestations SHALL indicate in its Credential Issuer metadata that it does not need a WUA. A Wallet Unit SHALL NOT send a WUA to an Attestation Provider when requesting a non-device-bound attestation. Note: A Wallet Unit sends a WIA to the Attestation Provider regardless of whether the attestations it issues are device-bound or not.
	- An Attestation Provider issuing non-device-bound attestations SHALL indicate in its Credential Issuer metadata that it does not need a WUA. A Wallet Unit SHALL NOT send a WUA to an Attestation Provider when requesting a non-device-bound attestation. Note: A Wallet Unit sends a WAA to the Attestation Provider regardless of whether the attestations it issues are device-bound or not.

Uh oh!

Conversation

peppelinux commented Feb 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

peppelinux Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

peppelinux Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

peppelinux commented Feb 18, 2026

Uh oh!

fmarino-ipzs left a comment

Choose a reason for hiding this comment

Uh oh!

fmarino-ipzs Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

fmarino-ipzs Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

Sh-Amir Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

ZAnsaroudi Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Sh-Amir left a comment

Choose a reason for hiding this comment

Uh oh!

ghost commented Mar 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

peppelinux Feb 17, 2026 •

edited

Loading