18 vocprovider paris broker in system layer (#79)

* fix: reordering the system layer sub-sections

* fix: reordering the system layer sub-sections

* fix: adding a first ParIS section to the system layer

* fix: starting with the metadata broker in the system layer

* fix: general overview of the metadata broker in the system layer

* fix: general overview of the vocabulary hub in the system layer

* Update 3_5_4_Metadata_Broker.md

* fix: Introduction of system Layer

- Rewrote the beginning again because some points were duplicated or wrong.
- Adding *Metadata* Broker and *IDS* Connector
- Removing the distinction External/Internal Connector
- Link to 4.2 (even if the chapter does not exist in this branch yet)

* Update 3_5_4_Metadata_Broker.md

* Integrating the review comments for the ParIS subchapter of the System Layer.

* Adding a reference to the ParIS subchapter in the Identity Provider document of the System Layer.

* Integrating the comments for the Metadata Broker subchapter in the System Layer.

* Moving the current ParIS sections to the other Layers.

* Update 3_5_4_Metadata_Broker.md

Delete Query Language examples to be technology agnostic

* 18 vocprovider paris broker in system layer (#151)

* fix: starting with the ParIS section in the System Layer

* fix: Finishing my view of the ParIS in the System Layer section
Subsections:
* Components
* Endpoints
* Search and Querying
* Life Cycle of Participant's Self-Description
* Data Synchronization inside the Identity Provider

* Update 3_5_4_Metadata_Broker.md

* chore: Integrate Feedback to 3_5_0_System_Layer.md

* chore: fix typos

* chore: update interaction image

* Update documentation/3_Layers_of_the_Reference_Architecture_Model/3_5_System_Layer/3_5_0_System_Layer.md

Co-authored-by: Julia Pampus <[email protected]>

* Apply suggestions from code review

Co-authored-by: Julia Pampus <[email protected]>

* chore: IAM is not optional fpr ParIS

Co-authored-by: Jörg Langkau <[email protected]>
Co-authored-by: HeinrichPet <[email protected]>
Co-authored-by: hpettenpohl <[email protected]>
Co-authored-by: Tim Berthold <[email protected]>
Co-authored-by: jpampus <[email protected]>
Co-authored-by: Julia Pampus <[email protected]>

documentation/3_Layers_of_the_Reference_Architecture_Model/3_5_System_Layer/3_5_0_System_Layer.md

@@ -1,42 +1,18 @@
 # System Layer
 
-On the System Layer, the roles specified on the Business Layer are mapped onto a concrete data and service architecture
-in order to meet the requirements specified on the Functional Layer, resulting in what can be considered the technical core
-of the International Data Spaces.
+The processes defined in the [Process Layer](../3_3_Process_Layer) are summarized in Figure 3.5.0.1 as interactions between the IDS Components. Please note that the Identity Provider is not shown in the figure in order to maintain readability.
 
-From the requirements identified on the Functional Layer, three major technical components result:
-- the Connector,
-- the Broker, and
-- the App Store.
+![Interaction of technical components](./media/3.5.0.1_interaction_between_technical_components.png)
+#### _Fig. 3.5.0.1: Interaction of technical components_
 
-How these components interact with each other is depicted
-in Figure 3.31.
+A distributed network like the International Data Spaces relies on the connection of different participants where IDS Connectors or other core components are hosted (an IDS Connector comprising one or more Data Endpoints). The IDS Connector is responsible initiating a data exchange (see [Section 3.3.4](../../3_3_Process_Layer/3_3_4_Exchanging_Data.md)) from and to the internal data resources and enterprise systems of the participating organizations and the International Data Spaces. It provides metadata to the Metadata Broker as specified in the IDS Connector self-description, e.g. technical interface description, authentication mechanism, and associated data usage policies. Usage Contracts can be transferred via the IDS Connector to the Clearing House to ensure trust. Also, the data transfer can be logged at the Clearing House for trust reasons, or for clearing reasons. Vocabularies can be interpreted by getting more details from the Vocabulary Hub. Additional IDS Apps can be downloaded to the IDS Connector to run operations on the data.
 
-The Connector, the Broker, and the App Store are supported
-by four additional components (which are not specific to the
-International Data Spaces, but specified for the International
-Data Spaces):
+On the System Layer, the roles specified on the Business Layer and the processes defined in the Process Layer are mapped onto a concrete data and service architecture, resulting in what can be considered the technical core of the International Data Spaces.
 
-- the Identity Provider as defined in the Security
-Perspective,
-- the Vocabulary Hub currently as defined outside the IDS,
-- the Update Repository (i.e. the source for updates of deployed Connectors) depending on the connectors technology, and
-- the Trust Repository (i.e. the source for trustworthy software stacks and fingerprints as well as remote attestation checks) as discussed in the Security Perspective.
-
-A distributed network like the International Data Spaces relies on the connection of different member nodes where Connectors or other core components are hosted (a Connector comprising one or more Data Endpoints). The Connector is responsible for the exchange of data or as a proxy in the exchange of data, as it executes the complete data exchange process (see Section 3.3.2) from and to the internal data resources and enterprise systems of the participating organizations and the International Data Spaces. It provides metadata to the Broker as specified in the connector self-description, e.g. technical interface description, authentication mechanism, exposed data sources, and associated data usage policies. It is important to note that the data is transferred between the Connectors of the Data Provider and the Data Consumer (peer-to-peer network concept).
-
-There may be different types of implementations of the Connector, based on different technologies and depending on what specific functionality is required regarding the purpose of the Connector. Two fundamental variants are the Base Connector and the Trusted Connector (see Section 4.1) as they differ in the capabilities regarding security and data sovereignty.
-
-Connectors can be further distinguished into External Connectors and Internal Connectors:
-- An External Connector executes the exchange of data between participants of the International Data Spaces. The
-International Data Spaces network is constituted by the total of its External Connectors. Each External Connector
-provides data via the Data Endpoints it exposes. Applying this principle, there is no need for a central instance for
-data storage. An External Connector is typically operated behind a firewall in a specially secured network segment
-of a participant (so-called “Demilitarized Zone”, DMZ). From a DMZ, direct access to internal systems is not possible.
-It should be possible to reach an External Connector using the standard Internet Protocol (IP), and to operate it
-in any appropriate environment. A participant may operate multiple External Connectors (e.g., to meet load balancing 
-or data partitioning requirements). External Connectors can be operated on-premises or in a cloud environment.
-- An Internal Connector is typically operated in an internal company network (i.e., a network which is not accessible
-from outside). Implementations of Internal Connectors and External Connectors may be identical, as only the purpose
-and configuration differ. The main task of an Internal Connector is to facilitate access to internal data sources in
-order to provide data to External Connectors.
+The IDS consists of the following core components:
+- the [Identity Provider](./3_5_1_Identity_Provider.md) (consisting of DAPS and [ParIS](3_5_1_2_ParIS.md)),
+- the [IDS Connector](./3_5_2_Connector.md),
+- the [App Store and Data Apps](./3_5_3_App_Store_and_Data_Apps.md),
+- the [Metadata Broker](./3_5_4_Metadata_Broker.md),
+- the [Clearing House](./3_5_5_Clearing_House.md), and
+- the [Vocabulary Hub](./3_5_6_Vocabulary_Hub.md).

documentation/3_Layers_of_the_Reference_Architecture_Model/3_5_System_Layer/3_5_1_2_ParIS.md

@@ -0,0 +1,40 @@
+# Participant Information Service (ParIS)
+
+From a System Layer view, the internal architecture components and endpoints of a ParIS are very similar to the ones of an IDS Metadata Broker. Both need to receive, persist, and make IDS Self-Descriptions available for other IDS Connectors to query them. The main difference is the type of Self-Description they manage - Connectors and Resources by the Metadata Brokers and Participants by the ParIS. 
+
+
+## Components
+
+A ParIS typically consists of the following functional building blocks, which can be implemented using different technology stacks and hosting solutions:
+
+- _Server_ to host the IDS Endpoints.
+- _Database_ to persist the RDF Self-Descriptions of the registered IDS Participants.
+- _IAM_ for checking the identity claims of clients and to validate their authorization using the IDS DAT. Can be located at the surrounding Identity Provider.
+- _Index_ (optional) to increase the speed for read requests.
+- _Website_ (optional) for human interactions with the ParIS.
+
+
+## Endpoints
+
+The interactions with a ParIS can be distinguished into two main categories. The first one is related to the initial provisioning of Participant information during their onboarding in an IDS as well as the according updates through the operators of the general Identity Provider. As this workflow is completely component-internal, proprietary or custom patterns might be used. The necessity for this internal endpoint is due to the required higher trust in the Participant metadata. For instance, an incorrect VAT-ID or jurisdiction has direct and concrete legal consequences, therefore a certain validation workflow at the Identity Provider operator must be enabled. 
+
+In addition, an IDS compliant endpoint must be exposed for the communications with IDS Connectors. While this endpoint could also - given proper authentication and authorization procedures - serve for the purpose described above, its main concern is the provisioning of querying capabilities and to allow individual Participants to adjust their own Self-Description.
+
+
+## Search and Querying
+
+Each ParIS instance must provide IDS compliant functions to dereference Participant identifiers. A dereferencation function accepts the Participant identifier, an IRI according to the IDS Information Model, and returns the related Self-Description document. In addition, a ParIS may provide further search capabilities, like full-text search, attribute-based or facet search, or even expose expressive query language like SPARQL. In any case, the respective capabilities must be outlined in the Self-Description of the ParIS itself, to make them discoverable for IDS Connectors.
+
+
+## Life Cycle of Participant's Self-Description
+
+Similar to Connector and Resource Self-Descriptions, also Participant Self-Descriptions (SD) pass different lifecycle stages. The initial version is provided by the Participant itself, either directly as an IDS Information Model instance or as a filled form during the onboarding process. This SD is then, after the IDS identity of the new Participant has been created, populated at the according ParIS. 
+
+In case mistakes in this SD are noticed or attributes of the Participant change, both the operator of the Identity Provider as well as the Participant itself have the technical means to adjust the Self-Description. Note that the operator of the Identity Provider could also prohibit direct updates due to otherwise skipped validation workflows.
+
+In case a Participant temporarily or completely leaves an IDS, the according Self-Description can also be made unavailable. An unavailable SD is not exposed to the regular search and query functionalities anymore. Nevertheless, the ParIS should still keep the SD or at least its identifier, to enable potential later reactivations and especially prevent identity hijacking attempts. In such an attack, a newly onboarded Participant could try to use an identifier of another Participant that has left the IDS already, and thereby claim the access and usage permissions of the latter.
+
+
+## Data Synchronization inside the Identity Provider
+
+The core attributes of an IDS Participant, their IDS Key, UUID, and the IRI identifier, need to be maintained comprehensively between the different functional components of the Identity Provider. Apart from that, no further synchronization between different ParIS or Identity Provider instances are enforced.

documentation/3_Layers_of_the_Reference_Architecture_Model/3_5_System_Layer/3_5_1_Identity_Provider.md

@@ -1,40 +1,7 @@
 # Identity Provider
 
 ## Dynamic Attribute Provisioning Service (DAPS)
-//TODO !
 
 ## Participant Information Service (ParIS)
 
-The Participant Information Service role, short ParIS, can be implemented in different variations
-and implementation patterns. Independent of different design decisions or used
-technologies, all ParIS implementations must host an IDS endpoint that hosts a
-Self-Description of the ParIS itself as well as functions to query and update
-the contained catalog of Participant Self-Descriptions. This endpoint is required
-to allow IDS Connectors to find the ParIS and interact with it in an IDS compliant
-manner. Furthermore, a ParIS should also provide a website with a human-friendly
-presentation of its content as well as suitable query and filter capabilities.
-
-Both the website and the IDS endpoint might be protected further, by for instance
-relating the access permissions to IDS identities. One could, for instance, only
-allow registered IDS components to actually retrieve the metadata of other
-Participants. That way, the distribution of the Self-Descriptions is limited to
-certain data spaces. Nevertheless, as a ParIS is not intended to host or maintain
-completely confidential data, a fully implemented access or even Usage Control
-regime is usually not necessary. However, the typical requirements of the IDS
-communication, for instance encryption or the usage of a DAPS DAT, are also relevant
-for a ParIS. Consequently, also a ParIS needs an IDS Identity Certificate and
-needs to be registered at a DAPS.
-
-In addition to the outside communication, an internally reachable endpoint can be
-exposed, only accessible for the operators of the Identity Provider. This endpoint
-can be used to enable the provisioning and curation of Participant Self-Descriptions.
-The externally reachable endpoints only allow the curation of own Self-Descriptions,
-which means that a Participant can never change another
-Participant's Self-Description. Nevertheless, a curation process is needed, which
-can be operated using this internal endpoint. The curation process
-needs to be executed in comply to the IDS Governance rules.
-
-Apart from the endpoints, and the server hosting them,
-a ParIS needs either to host an internal database to store and retrieve the
-Participant Self-Descriptions or be connected to the general database of its
-Identity Provider.
+The [ParIS](./3_5_1_2_ParIS.md) is a vital part of the Identity Provider. While the CA is responsible to issue and manage technical identity proofs and the DAPS provides time-dependent tokens, the ParIS provides business-related  information of IDS Participants in machine- and human-readable manners.