diff --git a/usage control implementation/FS_UCDiagram-UC(Provider).png b/FS_UCDiagram-UC(Provider).png similarity index 100% rename from usage control implementation/FS_UCDiagram-UC(Provider).png rename to FS_UCDiagram-UC(Provider).png diff --git a/usage control implementation/FS_UCDiagram-UC(consumer).png b/FS_UCDiagram-UC(consumer).png similarity index 100% rename from usage control implementation/FS_UCDiagram-UC(consumer).png rename to FS_UCDiagram-UC(consumer).png diff --git a/README.md b/README.md index 490b689..b737891 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,38 @@ -### What is FarmStack? -FarmStack is a digital infrastructure that enables data collaboration between different entities. It does this by providing a means to: -1. Share data directly to the relevant organization without the need of third party through p2p connector (peer to peer connector) -2. Empower the data provider to specify how data can or cannot be used by the receiver through data owner defined usage policies -3. Enable organizations to make their data discoverable by publishing metadata (description of connectors and usage policies) and shareable through data interface containers +# Overview +This project is a reference implementation of farmstack to showcase restricting the usage of data by an application container running a node.js application. This reference implementation can be used to create usage policies that require constraining the usage of data for the specific purpose of the project and/or avoid unintended leak or misuse of data. Most of the data sharing agreements require that the data consumer use the data for that purpose for which data is being exchanged. This can be bundled as a node.js or python application (language independent) hosted inside of an application container and the data usage policy with p2p connectors can be used to restrict data usage beyond the container. Usage control also dovetails with the consent management framework enhancing the access control to finegrained enforceable restrictions. The usage control can be viewed as superset of the access control. -### Why is FarmStack required? -FarmStack is required because: -* Lack of trust on misuse or under utilization of data for centralized data repository -* Need to comply with evolving data policy and privacy safeguarding measures +FarmStack consists of a p2p connector which is a fork from the [trusted connector](https://github.com/industrial-data-space/trusted-connector/) provided by IDSA - Fraunhofer AISEC. The p2p connectors manage docker containers and are assigned identities through which they can mutually authenticate each other and encrypt messages. IDSA also provides an IDS communication protocol which creates a secure web socket between connectors and acts as a remote attestation endpoint. The p2p connectors can be installed and run on premise by respective participants and used to provide data which can be accessed through a filesystem or a set of flexible APIs. The architecture laid down in the [IDSA reference architecture](https://www.internationaldataspaces.org/wp-content/uploads/2019/03/IDS-Reference-Architecture-Model-3.0.pdf) (published by Fraunhofer) is a message/stream driven architecture which routes data using the open source [Apache Camel](https://camel.apache.org/docs/) framework. At the core of IDSA architecture is an [information model](https://github.com/International-Data-Spaces-Association/InformationModel) which provides the language independent description of digital resources (connectors, data description or any service etc). The information model is programmatically implemented in Java and the maven repositories are hosted in the public domain [here](https://jira.iais.fraunhofer.de/stash/projects/ICTSL/repos/ids-infomodel-demo/browse) by Fraunhofer IAIS. These classes are used to construct messages that are used to control the routing of data. The [available message types](https://htmlpreview.github.io/?https://github.com/IndustrialDataSpace/InformationModel/blob/feature/message_taxonomy_description/model/communication/Message_Description.htm) of IDSA is given here. The high level abstraction of data sharing using connectors is shown below. -### Value generated by FarmStack -* By combining specific datasets, better services or products can be created -* Potential to unlock value of data that was previously considered not shareable -* More the feedback from farmers is combined, more enriching the solution can be - giving rise to virtuous cycle + -### How does someone use FarmStack +## Trusted Connector details -Business roles in FS can be viewed as layered operational spheres: -* __FS Participants__ : These are stakeholders who are actually performing data exchange or providing some services for data exchange. This is mainly a data provider and data consumer -* __FS Central/ Steward__ : This is a nodal agency/ consortium who will run farmstack in that geography/ jurisdiction. They will operate the gateways for the participants. Examples could be MoA or a global consortium. -* __FS Core__: This is the technology stack that is maintained by DG and consortium based on IDS technology stack (Fraunhofer) which consists of the code repo under MIT/ Apache license. They will own the master services agreement - governance structure and the right to provision instance of FS central. + -#### Example: -Consider the diagram, there are two instances of FS run by two independent central bodies in different jurisdictions. Let us say MoA of Country1 and Country2 run separate instances of FarmStack C1 and C2 which have participants P1… Pn who do data exchange between each other. By provisioning FS, C1 and C2 run FS on their server in addition to managing the organizations. +## Data usage control +In information security, access control restricts access to digital resources. The term authorization is the process of granting permission to resources. Several access control models exist, such as Discretionary Access Control (DAC), Mandatory Access Control (MAC), Role-based Access Control (RBAC), Attribute-based Access Control (ABAC), etc. The XACML (eXtensible Access Control Markup Language) Standard is commonly used in the field of access control. XACML is a policy language to express ABAC rules. - +In contrast to access control, where access to specific digital resources (e.g., a service or a file) is restricted, the IDS architecture additionally supports data-centric usage control. The overall goal is to enforce usage restrictions for data after access has been granted though policies that bind to data being exchanged. At configuration time, these policies support developers and administrators in setting up correct data flows. Usage control itself does not establish trust in an endpoint. It rather builds upon an existing trust relationship and facilitates the enforcement of legal or technical requirements or data privacy regulations. + +To implement the usage policies, the policies need to be machine readable and based on common standards so that they can be enforced. The IDS usage policy language therefore relies on the Open Digital Rights Language (ODRL). ODRL is a W3C recommendation and specifies a vocabulary and data model for the description of digital and machine-readable contracts. The IDS further extends ODRL towards usage control descriptions and enforcement, provides explanations regarding the compliant interpretation of constructs and defines implications for real-world implementations. This is accomplished in the form of IDS subclass constructs to the according ODRL classes. The design preserves the structure of the introduced terminology, resulting in the compliance of IDS usage policy with ODRL recommendations. + +The fundamental building blocks for IDS Policies are the Contracts. Contracts present the container of any usage control statement and come in three different realizations: Requests, Offers, and Agreements. While all share a similar syntax, their interpretation is slightly different. + - Contract requests are created by data consumers and indicate a desire to achieve a certain contract. + - Contract offers are created by data providers and indicate willingness to exchange data or services as outlined in Contract Offers. + - Contract agreements represent a binding and final consent to the stated constraints and requirements. A contract agreement is the IDS terminology for a valid contract, which both sides accept and therefore is binding as far as the IDS is related. + +It must be noted that contract requests and contract offers are purely informative pieces of information and do not bind any contract. The figure below represents the hierarchical structure of a usage policy. + + + + +# Implementation +In this reference implementation, there is one provider and one consumer, both running a FarmStack p2p connector. The connectors mutually authenticate and encrypt data through the SSL certificates provided to them from a simulated certificate authority. The provider configures a usage policy that refers to the hash of a container that can access data. The data provider has one sample csv file. The data consumer receives the data in IDS protocol (a secured web socket protocol developed by Fraunhofer AISEC). IDSCP enables metadata exchange and remote attestation, creating a trusted tunnel between connector instances. It has a node application running within the container of the p2p connector that renders and displays the data in html format (browser). + +The usage policy essentially constrains that data be not used by any other container or if the container is modified. This is a basic example that can be used to create multiple usage restrictions that require data being available and used for only specific applications. + +## Data provider side + + +## Data consumer side + diff --git a/usage control implementation/connector_architecture.png b/connector_architecture.png similarity index 100% rename from usage control implementation/connector_architecture.png rename to connector_architecture.png diff --git a/usage control implementation/data_sharing.png b/data_sharing.png similarity index 100% rename from usage control implementation/data_sharing.png rename to data_sharing.png diff --git a/usage control implementation/configs/uc_1.png b/uc_1.png similarity index 100% rename from usage control implementation/configs/uc_1.png rename to uc_1.png diff --git a/usage control implementation/README.md b/usage control implementation/README.md index 3aa1522..af15630 100644 --- a/usage control implementation/README.md +++ b/usage control implementation/README.md @@ -1,25 +1,3 @@ -# Overview -This project is a reference implementation of farmstack to showcase restricting the usage of data by an application container running a node.js application. This reference implementation can be used to create usage policies that require constraining the usage of data for the specific purpose of the project and/or avoid unintended leak or misuse of data. Most of the data sharing agreements require that the data consumer use the data for that purpose for which data is being exchanged. This can be bundled as a node.js or python application (language independent) hosted inside of an application container and the data usage policy with p2p connectors can be used to restrict data usage beyond the container. Usage control also dovetails with the consent management framework enhancing the access control to finegrained enforceable restrictions. The usage control can be viewed as superset of the access control. - -FarmStack consists of a p2p connector which is a fork from the [trusted connector](https://github.com/industrial-data-space/trusted-connector/) provided by IDSA - Fraunhofer AISEC. The p2p connectors manage docker containers and are assigned identities through which they can mutually authenticate each other and encrypt messages. IDSA also provides an IDS communication protocol which creates a secure web socket between connectors and acts as a remote attestation endpoint. The p2p connectors can be installed and run on premise by respective participants and used to provide data which can be accessed through a filesystem or a set of flexible APIs. The architecture laid down in the [IDSA reference architecture](https://www.internationaldataspaces.org/wp-content/uploads/2019/03/IDS-Reference-Architecture-Model-3.0.pdf) (published by Fraunhofer) is a message/stream driven architecture which routes data using the open source [Apache Camel](https://camel.apache.org/docs/) framework. At the core of IDSA architecture is an [information model](https://github.com/International-Data-Spaces-Association/InformationModel) which provides the language independent description of digital resources (connectors, data description or any service etc). The information model is programmatically implemented in Java and the maven repositories are hosted in the public domain [here](https://jira.iais.fraunhofer.de/stash/projects/ICTSL/repos/ids-infomodel-demo/browse) by Fraunhofer IAIS. These classes are used to construct messages that are used to control the routing of data. The [available message types](https://htmlpreview.github.io/?https://github.com/IndustrialDataSpace/InformationModel/blob/feature/message_taxonomy_description/model/communication/Message_Description.htm) of IDSA is given here. The high level abstraction of data sharing using connectors is shown below. - - - -## Trusted Connector details - - - -# Implementation -In this reference implementation, there is one provider and one consumer, both running a FarmStack p2p connector. The connectors mutually authenticate and encrypt data through the SSL certificates provided to them from a simulated certificate authority. The provider configures a usage policy that refers to the hash of a container that can access data. The data provider has one sample csv file. The data consumer receives the data in IDS protocol (a secured web socket protocol developed by Fraunhofer AISEC). IDSCP enables metadata exchange and remote attestation, creating a trusted tunnel between connector instances. It has a node application running within the container of the p2p connector that renders and displays the data in html format (browser). - -The usage policy essentially constrains that data be not used by any other container or if the container is modified. This is a basic example that can be used to create multiple usage restrictions that require data being available and used for only specific applications. - -## Data provider side - - -## Data consumer side - - ## Code structure Config/ - Includes the configuration related files:
diff --git a/usage control implementation/configs/readme.md b/usage control implementation/configs/readme.md index 5ad4a55..e287445 100644 --- a/usage control implementation/configs/readme.md +++ b/usage control implementation/configs/readme.md @@ -1,18 +1,19 @@ -## Data usage control -In information security, access control restricts access to digital resources. The term authorization is the process of granting permission to resources. Several access control models exist, such as Discretionary Access Control (DAC), Mandatory Access Control (MAC), Role-based Access Control (RBAC), Attribute-based Access Control (ABAC), etc. The XACML (eXtensible Access Control Markup Language) Standard is commonly used in the field of access control. XACML is a policy language to express ABAC rules. -In contrast to access control, where access to specific digital resources (e.g., a service or a file) is restricted, the IDS architecture additionally supports data-centric usage control. The overall goal is to enforce usage restrictions for data after access has been granted though policies that bind to data being exchanged. At configuration time, these policies support developers and administrators in setting up correct data flows. Usage control itself does not establish trust in an endpoint. It rather builds upon an existing trust relationship and facilitates the enforcement of legal or technical requirements or data privacy regulations. +## File structure -To implement the usage policies, the policies need to be machine readable and based on common standards so that they can be enforced. The IDS usage policy language therefore relies on the Open Digital Rights Language (ODRL). ODRL is a W3C recommendation and specifies a vocabulary and data model for the description of digital and machine-readable contracts. The IDS further extends ODRL towards usage control descriptions and enforcement, provides explanations regarding the compliant interpretation of constructs and defines implications for real-world implementations. This is accomplished in the form of IDS subclass constructs to the according ODRL classes. The design preserves the structure of the introduced terminology, resulting in the compliance of IDS usage policy with ODRL recommendations. +**docker-compose-provider.yaml:**
+ Instantiates the configuration of docker containers on provider connector like ports, networks etc. It also mounts the file that defines data routing at provider connector: example-provider-routes.xml
+ This is the file that needs to be executed to run the provider connector. To run the provider connector execute the command, docker-compose -f docker-compose-provider.yaml up
-The fundamental building blocks for IDS Policies are the Contracts. Contracts present the container of any usage control statement and come in three different realizations: Requests, Offers, and Agreements. While all share a similar syntax, their interpretation is slightly different. - - Contract requests are created by data consumers and indicate a desire to achieve a certain contract. - - Contract offers are created by data providers and indicate willingness to exchange data or services as outlined in Contract Offers. - - Contract agreements represent a binding and final consent to the stated constraints and requirements. A contract agreement is the IDS terminology for a valid contract, which both sides accept and therefore is binding as far as the IDS is related. +**docker-compose-consumer.yaml:**
+ Instantiates the configuration of docker containers on consumer connector like ports, networks etc. It also mounts the file that defines data routing at consumer connector: example-consumer-routes.xml
+ This is the file that needs to be executed to run the consumer connector. To run the provider connector execute the command, docker-compose -f docker-compose-consumer.yaml up
-It must be noted that contract requests and contract offers are purely informative pieces of information and do not bind any contract. The figure below represents the hierarchical structure of a usage policy. +**example-provider-routes.xml:**
+ Configures data routing at the provider connector using [CAMEL](https://camel.apache.org/). - +**example-consumer-routes.xml:**
+ Configures data routing at the consumer connector using [CAMEL](https://camel.apache.org/). ## Contract agreement message flow Step 1: Data consumer (IDSCP2 - Client) requests contract and sends ContractRequestMessage @@ -23,7 +24,7 @@ It must be noted that contract requests and contract offers are purely informati In the current code, step1 is simulated by having a dummy ContractRequest. ## CAMEL Classes - Following classes are used in the respective xml files in provider and consumer. The actual classes are hosted by Fraunhofer. + Following classes are used in the respective xml files in provider and consumer. The actual classes are hosted by Fraunhofer. ## Provider 1. Class name: ContractOfferCreationProcessor 1. Function: @@ -63,20 +64,3 @@ In the current code, step1 is simulated by having a dummy ContractRequest. 3. Where: The first message to consumer 2. Class name: TypeExtractionProcessor 1. Covered in provider (same function here) - - -## File structure - -**docker-compose-provider.yaml:**
- Instantiates the configuration of docker containers on provider connector like ports, networks etc. It also mounts the file that defines data routing at provider connector: example-provider-routes.xml
- This is the file that needs to be executed to run the provider connector. To run the provider connector execute the command, docker-compose -f docker-compose-provider.yaml up
- -**docker-compose-consumer.yaml:**
- Instantiates the configuration of docker containers on consumer connector like ports, networks etc. It also mounts the file that defines data routing at consumer connector: example-consumer-routes.xml
- This is the file that needs to be executed to run the consumer connector. To run the provider connector execute the command, docker-compose -f docker-compose-consumer.yaml up
- -**example-provider-routes.xml:**
- Configures data routing at the provider connector using [CAMEL](https://camel.apache.org/). - -**example-consumer-routes.xml:**
- Configures data routing at the consumer connector using [CAMEL](https://camel.apache.org/). diff --git a/usage control implementation/workspace-architect.png b/usage control implementation/workspace-architect.png deleted file mode 100644 index eadeddd..0000000 Binary files a/usage control implementation/workspace-architect.png and /dev/null differ