System Adapter Technical Documentation

Introduction

International Data Space System Adapter is an application developed in Java Spring that allows for storing sensitive data in a secure manner. Since International Data Space Ecosystem supports different connectors and micro-services, there is a need to have a possibility to securely store data outside the connectors. Therefore, System Adapter was developed.

System Adapter allows for different kind of databases to be registered. Currently, MySQL and Postgres are supported. There is a plan to add support for other database types in the future.

Project strategy

System Adapter aims to research International Data Space data security and safety related to when data is securely stored outside its domain. By applying authentication, security and encryption principles, System Adapter aims to provide a secure environment for International Data Space users to store their sensitive data, while at same time, applying their usage policies.

System Overview

System Adapter has a goal of providing a way of storing data securely outside of IDS ecosystem. To do that, we have designed System Adapter around three principles: authentication, authorization and encryption.

Authentication is handled by Spring Security Library. We use basic form authentication in order to access pages with sensitive data. Authorization is handled through permissions and roles designed inside Spring Application. Encryption is handled by RSA with public and private key. Private key is used for encryption whereas public key is used for decryption.

Key terms and entitles

Term

Explanation

System Adapter

A component that aims to provide capabilities to securely store data in different database providers.

Policy

A set of rules telling how sensitive data should be handled.

Java Spring

A framework developed in Java, suitable for Web Applications and APIs

Java Security

A library in Java Spring which handles all security related aspects of application. It contains also facilities for authentication.

Security

In the context of System Adapter, security permits specific users of entering or not entering guarded endpoints.

Authentication

In the context of System Adapter, authentication is a mechanism which assigns roles to users and checks their user credentials in order to provide access.

Encryption

In context of System Adapter, encryption is a mechanism used to encrypt sensitive data.

AES

AES is an encryption method.

RSA

RSA is an encryption method based on public/private key pair.

System Context & Domain

Domain

The main idea of System Adapter is to allow users a secure way of storing data outside of IDS Ecosystem. To achieve this, we offer different databases with the possibility of encryption.

Users, by connecting to System Adapter through HTTP connection can conduct their transactions. System Adapter is made out:

The Front-End is handled using REACT bundled up with Material UI, whereas Back-End is handled by Java Spring. Connections to the database are handled by JPA.

One of the main objectives of IDS is to ensure data security. There we designed our security around these three elements:

Architecture Drivers

Key Functional Requirements

#	Description
FR.01	System Adapter should have a possibility to register Databases.
FR.02	System Adapter should provide at least 2 different Databases.
FR.03	System Adapter should provide different encryption techniques.
FR.04	System Adapter should be able to serialize and deserialize data.
FR.05	System Adapter should support registration of users.
FR.06	System Adapter should support accessing data through user interface.
FR.07	System Adapter should support header Id for data that is to be stored.

Description

FR.01

System Adapter should have a possibility to register Databases.

FR.02

System Adapter should provide at least 2 different Databases.

FR.03

System Adapter should provide different encryption techniques.

FR.04

System Adapter should be able to serialize and deserialize data.

FR.05

System Adapter should support registration of users.

FR.06

System Adapter should support accessing data through user interface.

FR.07

System Adapter should support header Id for data that is to be stored.

Quality Requirements

System Decomposition

Solution Approach and Key Architecture Decisions

Data Model

In the scope of System Adapter we used the following models: User, Payload, Registration, and Role.

Our User Model is constructed to be compatible with JPA Repository Interface. User Model looks like this:

As we see, we have standard accessor methods for name, surname, email and password fields. As for the other fields, they are used by Spring Security system. Finally, registration and roles fields are used by other tables in form of foreign keys.

In the scope of Payload Model we have the following:

Payload Model is used to handle sensitive data that is stored outside Fraunhofer Data Space. Most importantly, data field is created using a converter. This converter does the encryption and handling of the data.

In the scope of Registration Model we have the following:

In the scope of Role Model we have the following:

This model support Role Based Authorization system that we build. Therefore, for each registered user there is a one or more corresponding entries in role table.

Code Organization

Back-End code was organized in packages, whereas Front-End code was organized in React classes. As far as Back-End code is concerned, we defined following packages:

Package	Explanation
System Adapter	Contains main method. Here, we bootstrap our application, fill in the database with dummy data, create user, and create routes which are exposed to React Front-End.
Configuration Database	Classes where developers can register new database providers.
Configuration Security	Classes where developers can specify protection od routes, choose type of security, add CORS mapping, etc.
Configuration Security Auth	Classes where developers implement User Details interface in order to communicate with Configuration Security by providing DAO Authentication Provider with login data.
Configuration Security Role	Enums where developers define user roles and their permissions.
Data	Container for data that is to be stored safely.
Data Database Type	Enum for registering different database providers.
Data Formatter	Interface containing function signature for formatting data.
Database Dummy	Classes for creating dummy data for Databases and Users.
Encryption	Classes implementing different encryption protocols that we described above.
Form RequestBody	Classes containing request bodies for different access end-points.
Form RequestResponse	Classes containing request response bodies for different access end-points.
Form User	Classes in form of Rest Controllers containing access points related to operations of registered users.
Hashing	Class containing configuration for BCrypt password encoder.
Model MySQL	Contains data models for MySQL database provider.
Model Postgres	Contains data models for Postgres database provider.
Repository MySQL	Contains JPA Information for MySQL database provider.
Repository Postgres	Contains JPA Information for Postgres database provider.
Rest	Classes in form of Rest Controllers containing access points related to Database providers.
Service MySQL	Classes containing services for MySQL Database provider.
Service Postgres	Classes containing services for Postgres Database provider.
Validation Annotations	Annotations for Capital Letter check, Not Blank check, and Size check.
Validation Validator	Classes containing implementations for annotations

Package

Explanation

System Adapter

Contains main method. Here, we bootstrap our application, fill in the database with dummy data, create user, and create routes which are exposed to React Front-End.

Configuration Database

Classes where developers can register new database providers.

Configuration Security

Classes where developers can specify protection od routes, choose type of security, add CORS mapping, etc.

Configuration Security Auth

Classes where developers implement User Details interface in order to communicate with Configuration Security by providing DAO Authentication Provider with login data.

Configuration Security Role

Enums where developers define user roles and their permissions.

Data

Container for data that is to be stored safely.

Data Database Type

Enum for registering different database providers.

Data Formatter

Interface containing function signature for formatting data.

Database Dummy

Classes for creating dummy data for Databases and Users.

Encryption

Classes implementing different encryption protocols that we described above.

Form RequestBody

Classes containing request bodies for different access end-points.

Form RequestResponse

Classes containing request response bodies for different access end-points.

Form User

Classes in form of Rest Controllers containing access points related to operations of registered users.

Hashing

Class containing configuration for BCrypt password encoder.

Model MySQL

Contains data models for MySQL database provider.

Model Postgres

Contains data models for Postgres database provider.

Repository MySQL

Contains JPA Information for MySQL database provider.

Repository Postgres

Contains JPA Information for Postgres database provider.

Rest

Classes in form of Rest Controllers containing access points related to Database providers.

Service MySQL

Classes containing services for MySQL Database provider.

Service Postgres

Classes containing services for Postgres Database provider.

Validation Annotations

Annotations for Capital Letter check, Not Blank check, and Size check.

Validation Validator

Classes containing implementations for annotations

As far as Front-End is concerned, we defined following classes:

Folder	Explanation
App	This folder contains main files from React application responsible for starting the application.
FormRequestBodyObjects	This folder contains files that prepare request to access web points in the Back-End.
Header	This folder contains information about navigating pages and access links.
Page	This folder contains all pages that are rendered by React UI.
PageContainer	This folder contains logic behind changing the contents of the pages.
Images	This folder resources used by pages, such as images.

Folder

Explanation

App

This folder contains main files from React application responsible for starting the application.

FormRequestBodyObjects

This folder contains files that prepare request to access web points in the Back-End.

Header

This folder contains information about navigating pages and access links.

Page

This folder contains all pages that are rendered by React UI.

PageContainer

This folder contains logic behind changing the contents of the pages.

Images

This folder resources used by pages, such as images.

Security

Authentication is handled completely by Spring Security package. Spring Security package brings the infrastructure for handling different forms of Authentication. Some of the Authentication forms that Spring Security supports are: Basic, Login Form, OAuth, etc. In our case, we are using Basic Authentication. In the beginning, we secured our routes with these restrictions:

In the beginning, we disable csrf protection and make sure that for the requests that are presented inside antMatchers method to require authentication. Of course, we permit all users to access some content with permitAll method. After this step, we also allow CORS requests in this part:

We allow CORS Mappings by overriding addCorsMappings method and choosing which routes we want to map. In our case we allow for all.

After fixing the route, we defined UserAuthApplicationWrapper and UserAuthServiceWrapper in order to assist us to authenticate users. The UserAuthApplicationWrapper contains the following:

We see that this is very similar to the User Model. However, the differences lie on the way UID and Roles are organized. Furthermore, this class implements UserDetails interface which is than consumed by Spring Security's DaoAuthenticationProvider class.

By providing all of this information, Spring Security can perform authentication. This way, are routes are secured and only authenticated users can access sensitive data.

Authorization is handled by Spring Security Package. In our case, we revolved our authorization in form of user roles and permissions. We defined user permissions like this:

As we can see, we have in total 6 permissions. Their access methods were defined inside ApplicationUserPermission class. This way we can use permissions to allow or disallow certain actions. To embedd these decisions, we created user roles. The roles that we devised are:

We defined three user roles in total. The routes that they can access are expressed with antMatchers function in scope of Authentication.

Since we are storing sensitive data, we decided to use Encryption as a measure to safely store data. We offer different forms of encryption data. In total we offer:

AES Encryption
AES Encryption Values
AES Encryption Values Secret Key
RSA Encryption

In terms of security, AES encryption is the least secure, whereas RSA Encryption is the most secure. We implemented all of these mechanisms using Converter Interface and Annotation from Java Spring.

Converter	Explanation
AES	AES Encryption is done by defining two instances of Cipher: one for encrypting, one for decrypting. In the beginning we convert the data into Base64 format and then feed it to encrypt Cipher. After this step we save the data to database. As far as decrypting is concerned, the data we received is decoded using Base64 decoder and then decrypted using decrypt Cipher.
AES Values	AES Encryption is done by defining two instances of Cipher: one for encrypting, one for decrypting. In the beginning we convert the data into Base64 format and then feed it to encrypt Cipher. We only encrypt the values part, without encrypting the keys part. After this step we save the data to database. As far as decrypting is concerned, the data we received is decoded using Base64 decoder, then decrypted using decrypt Cipher and finally keys are added.
AES Values Secret Key	AES Encryption is done by defining two instances of Cipher: one for encrypting, one for decrypting. In the beginning we convert the data into Base64 format and than feed it to encrypt Cipher. Before encryption itself takes place , we define a random generated secret key, which is fed to the Cipher. We only encrypt the values part, without encrypting the keys part of the data. After this step we save the data to database. As far as decrypting is concerned, the data we received is decoded using Base64 decoder, than decrypted using decrypt Cipher and randomly generated secret key.
RSA	AES Encryption is done by defining two instances of Cipher: one for encrypting, one for decrypting. In the beginning we convert the data into Base64 format and than feed it to encrypt Cipher. Before encryption itself takes place , we define a random generated secret key using RSA, which is fed to the Cipher. We only encrypt the values part, without encrypting the keys part of the data. After this step we save the data to database. As far as decrypting is concerned, the data we received is decoded using Base64 decoder, than decrypted using decrypt Cipher and randomly generated secret key.

Converter

Explanation

AES

AES Encryption is done by defining two instances of Cipher: one for encrypting, one for decrypting. In the beginning we convert the data into Base64 format and then feed it to encrypt Cipher. After this step we save the data to database. As far as decrypting is concerned, the data we received is decoded using Base64 decoder and then decrypted using decrypt Cipher.

AES Values

AES Encryption is done by defining two instances of Cipher: one for encrypting, one for decrypting. In the beginning we convert the data into Base64 format and then feed it to encrypt Cipher. We only encrypt the values part, without encrypting the keys part. After this step we save the data to database. As far as decrypting is concerned, the data we received is decoded using Base64 decoder, then decrypted using decrypt Cipher and finally keys are added.

AES Values Secret Key

AES Encryption is done by defining two instances of Cipher: one for encrypting, one for decrypting. In the beginning we convert the data into Base64 format and than feed it to encrypt Cipher. Before encryption itself takes place , we define a random generated secret key, which is fed to the Cipher. We only encrypt the values part, without encrypting the keys part of the data. After this step we save the data to database. As far as decrypting is concerned, the data we received is decoded using Base64 decoder, than decrypted using decrypt Cipher and randomly generated secret key.

RSA

AES Encryption is done by defining two instances of Cipher: one for encrypting, one for decrypting. In the beginning we convert the data into Base64 format and than feed it to encrypt Cipher. Before encryption itself takes place , we define a random generated secret key using RSA, which is fed to the Cipher. We only encrypt the values part, without encrypting the keys part of the data. After this step we save the data to database. As far as decrypting is concerned, the data we received is decoded using Base64 decoder, than decrypted using decrypt Cipher and randomly generated secret key.

User Interface

User Interface was built by using Material UI, a library written specifically to be used in React. When we navigate to root page we get to see this:

On top we have header with navigation links, whereas the content is below. All pages share this similar structure. As far as Documentation is concerned, it looks like this:

As far as pages with restrictions are concerned, they look like this:

Deployment and Operation

The System Adapter app is a Java Spring Application. Therefore, we use available infrastructure in order to deploy our application. The Back-End is deployed on TomCat Server. The Front-End is deployed using React facilities. Database is deployed using MySQL and Postgres facilities. All of these components are wrapped around in Docker containers.