A framework for user centred privacy and security in the cloud

CLARUS - H2020-ICT-2014-1 - G.A. 644024

© CLARUS Consortium 1 / 48

A framework for user

centred privacy and

security in the cloud

The CLARUS Platform v2

Type (distribution level) Public

Contractual date of Delivery 31-10-2017

Actual date of delivery 31-10-2017

Deliverable number D5.5

Deliverable name The CLARUS Platform v2

Version V2.0

Number of pages 48

WP/Task related to the

deliverable WP5/T5.3

WP/Task responsible MTI

Author(s) THALES

Partner(s) Contributing AKKA, OFFIS, URV, FCRB, MTI

Document ID D5.5 - The CLARUS Platform v2-v2.0

Abstract The second version of the CLARUS platform document constitutes a

user guide for the deployment, configuration of the CLARUS proxy.

Information about the upgrade and extension of this proxy is also

presented as well as an example of usage of this proxy.

This platform is composed of the proxy itself and a set of external

tools to administrate the proxy (adm), to specify new security policies

(spm), to manage access rights to dataspaces and datasets (arm)

and to monitor the proxy (mmt).

All the proposed tools are open source and are available in

https://github.com/clarus-proxy. In this document, we describe the

release 1.0.1 of the proxy and its accompanying tools. An example

for the encryption of data is presented. Notice that with the same

CLARUS – H2020-ICT-2014-1 – G.A. 644024 D5.5 - The CLARUS Platform v2-v2.0

© CLARUS Consortium 2 /48

approach, we can use the other protection modules available in the

project that are: anonymization, splitting, searchable encryption,

homomorphic encryption.



Disclaimer

CLARUS (644024) is a Research and Innovation Actions project funded by the EU Framework Program for Research and Innovation Horizon 2020. This document contains information on CLARUS core activities, findings and outcomes. Any reference to content in this document should clearly indicate the authors, source, organization and date of publication. The content of this publication is the sole responsibility of the CLARUS consortium and cannot be considered to reflect the views of the European Commission.



Table of Contents

1 INTRODUCTION ............................................................................................................................................ 6

1.1 SCOPE OF THE DOCUMENT ..................................................................................................................................... 6

1.2 REVISION HISTORY ............................................................................................................................................... 6

1.3 NOTATIONS, ABBREVIATIONS AND ACRONYMS ........................................................................................................... 7

1 REQUIREMENTS ............................................................................................................................................ 8

1.1 HARDWARE REQUIREMENTS .................................................................................................................................. 8

1.1.1 Minimum Requirements ........................................................................................................................ 8

1.1.2 Minimum Recommendations ................................................................................................................ 9

1.2 SOFTWARE REQUIREMENTS ................................................................................................................................... 9

2 DEPLOYMENT ............................................................................................................................................. 10

2.1 STANDARD DEPLOYMENT .................................................................................................................................... 12

2.1.1 Installation of the CLARUS proxy ......................................................................................................... 13

2.1.2 Configuration of the CLARUS proxy software ...................................................................................... 13

2.1.3 Execution of the CLARUS proxy software ............................................................................................ 14

2.1.4 Installing and executing the MMT based monitoring solution ........................................................... 15

2.1.5 Release management.......................................................................................................................... 17

2.1.6 Open issues and known bugs .............................................................................................................. 17

2.2 COLLABORATIVE DEPLOYMENT ............................................................................................................................. 17

2.3 LOAD BALANCED DEPLOYMENT............................................................................................................................. 18

3 CONFIGURATION ........................................................................................................................................ 19

3.1 SYSTEM ........................................................................................................................................................... 19

3.2 CLARUS GLOBAL .............................................................................................................................................. 19

3.2.1 Using the administration management tool ....................................................................................... 19

3.2.2 Using the access right management module ...................................................................................... 21

3.3 SECURITY POLICIES ............................................................................................................................................. 21

3.3.1 Using the command line based security manager .............................................................................. 21

3.3.2 Using the web based security manager .............................................................................................. 23

3.4 UPGRADING THE PROXY ...................................................................................................................................... 26



4 USAGE EXAMPLE ......................................................................................................................................... 28

4.1 SECURITY POLICY CREATION ................................................................................................................................. 28

4.2 CLARUS PROXY CONFIGURATION ......................................................................................................................... 30

4.3 CLARUS PROXY EXECUTION ............................................................................................................................... 31

4.4 CONNECTION TO THE CLARUS PROXY ................................................................................................................... 32

4.5 EXECUTION OF THE SQL QUERIES ......................................................................................................................... 32

5 EXTENDING THE PROXY .............................................................................................................................. 35

5.1 PROTOCOL MODULE EXTENSION ........................................................................................................................... 35

5.1.1 Implementation of the service provider interface ............................................................................... 35

5.1.2 Processing requests and responses ..................................................................................................... 37

5.2 DATA PROTECTION MODULE EXTENSION ................................................................................................................. 37

6 CONCLUSION .............................................................................................................................................. 41

A.1 PLATFORM DESIGN ................................................................................................................................................ 42

A.1.1 Architecture .............................................................................................................................................. 42

A.2 CLARUS INTEGRATION PLATFORM ........................................................................................................................... 43

A.2.1 Environment ............................................................................................................................................. 43

A2.2 Connection ................................................................................................................................................ 44

A.2.3 VM Provisioning ....................................................................................................................................... 45



1 Introduction

1.1 Scope of the document

This document presents a user and developer guide of the CLARUS proxy. Indeed, by integrating the

second version of the different proxy modules presented in D5.4 “The CLARUS Platform v1.0”, we were

able to build the first stable release of the CLARUS proxy and share it as an open source project available

on https://github.com/clarus-proxy. This integrated work provides us all the mechanisms in order to

obtain a trusted cloud platform.

The document constitutes a user guide for the deployment, configuration of the CLARUS proxy for a

specific case study. Information about the upgrade and extension (for a developer) of this proxy is also

presented as well as an example of usage of this proxy.

This platform is composed of the proxy itself and a set of external tools to administrate the proxy (adm),

to specify new security policies (spm), to manage access rights to dataspaces and datasets (arm) and to

monitor the proxy (mmt).

This document is divided in two main parts addressing specific users:

- The user that will install and operate CLARUS (administrator and integrator)

- The user that will extend CLARUS (developer)

In this document, we describe the release 1.0.1 of the CLARUS proxy and its accompanying tools. An

example for the encryption of data is presented. Notice that with the same approach, we can use the

other protection modules available in the project that are: anonymization, splitting, searchable

encryption, homomorphic encryption. The integration of this proxy within the CLARUS real-life case

studies are already presented in the first version of this deliverable D5.3 “The CLARUS Platform v1”.

1.2 Revision History

Version Date Author Description

0.1 2017/08/20 THALES Document initialization

0.2 2017/09/11 MTI Configuration of the security policies –

command line

0.2 2017/09/11 OFFIS Configuration of the security policy – Web

based application

0.3 2017/09/18 MTI Administration of the proxy

0.4 2017/09/25 THALES/MTI Integration of the proxy modules

0.5 2017/10/09 URV Data protection module extension

0.6 2017/10/10 AKKA Protocol module extension

0.7 2017/10/16 MTI Configuration of the proxy

0.8 2017/10/21 MTI Standard deployment of the proxy

0.9 2017/10/23 MTI Usage example



1.0 2017/10/23 THALES First version of the user guide

1.1 2017/10/24 MTI Other kinds of deployments of the proxy

1.2 2017/10/25 MTI Consolidation of the deployment section

1.3 2017/10/25 THALES Release of the document of internal

review

2017/10/27 AKKA Review 1 of the document

2017/10/26 FCRB Review 2 of the document

2017/10/31 MTI Testing the proxy by following the user

guide

2.0 2017/10/31 THALES Addressing reviewers comment and

finalization of the document

1.3 Notations, abbreviations and acronyms

Acronym Definition

CSP Cloud Service Provider

JAR Java Archive

LDAP Lightweight Directory Access Protocol

MMT Montimage Monitoring Tool

NIC Network Interface Card

NIDS Network-based Intrusion Detection System

NNID Neural Network Intrusion Detection

OGC Open Geo Spatial standards

SaaS Software as a service

SOA Service Oriented Architecture

TCP Transmission Control Protocol

VM Virtual Machine



1 Requirements

1.1 Hardware Requirements

Suitable hardware configurations are necessary to exploit the capacity of the CLARUS proxy to the

fullest. The CLARUS proxy can be deployed on a single physical device (e.g., raspberry pi, server) or as a

virtual machine or container to be run on a dedicated server. This section specifies the hardware

requirements for the former.

1.1.1 Minimum Requirements

Network Interface Cards

The CLARUS proxy needs at least 1 NIC (network interface card) so that it can communicate with the

user application and the CSP. But it is recommended to use at least 3 NICs:

• One for this communication with the user application in the trusted zone

• One for the communication with the CSP or CSPs

• And a last for administrating the proxy

In the same way, the monitoring solution based on MMT (Montimage Monitoring Tool) for the

detection and mitigation of potentials attacks and intrusions described in the deliverable D3.6 “Adapted

monitoring tool for the CLARUS platform V2” needs one administration NIC that can be the same as the

proxy one. To achieve the best performance, the capturing NIC should be either Intel X710 or Intel X520

card. These are recommended because they support DPDK that will considerably improve the packet

processing.

CPU

The proxy can run on any device regardless its CPU power. This is also the case for the monitoring

solution that will be deployed in the same machine as the proxy. To be able to manage a set of 1000

users without big delays and packet loss, it is recommended to use at least 1 processor core for the

proxy and another processor core for the monitoring. The larger the CPU cache, the better the

performance obtained.

RAM

The RAM is closely related to the dataset size to be analyzed. It is recommended to have a minimum of 2

GB of RAM to avoid any swapping.

Hard disk Drive

The proxy stores the queries/transactions medatada in a local mongodb database. In the same way, the

monitoring tool store statistics and incidents (security and other) about the proxy usage at runtime. We

recommend using a Solid-State Drive with at least 10 GB of free space. Purging or migrating the content

of mongodb collections should be done periodically.



1.1.2 Minimum Recommendations

NIC CPU RAM Free Disk Space

Single Node 2 2 cores 2 10

1.2 Software Requirements

The packages available on the release1 page of the CLARUS proxy have been produced for Linux Ubuntu

16.04, and they have been tested under the same platform. Both packages depend directly on other

packages that are available in the official repositories of Ubuntu 16.04:

• Java Runtime Environment 8: The CLARUS suite is a set of tools that have been developed using

the Java 8 language. To correctly execute the tools, the Java Runtime is required.

• Mongo Database. The CLARUS suite depends on Mongo Databases to store the configuration

and any metadata related with the data protection.

Notice that the proxy can work on other Linux distributions, and also on other operating system

(Windows, MAC OS) but no test has been performed in the context of this project. If you need a package

for a specific distribution, do not hesitate to send your request using the official web site of the CLARUS

proxy following this link http://www.clarussecure.eu/contact or by compiling the proxy using the open

source project available in https://github.com/clarus-proxy.

1 https://github.com/clarus-proxy/proxy/releases/latest

https://github.com/clarus-proxy



2 Deployment

The main objective of building the CLARUS proxy is to secure sensitive data to be stored in the cloud and

process them in a performing way. To reach this objective, it is very important to design and build

optimal modules and integrate them in a way that avoids delays and bottlenecks.

For this reason, our main idea was to avoid network-based communications between modules as much

as possible and we opted for a communication based on Java methods calls since all the proxy modules,

but the attack tolerance module, are implemented in Java language.

Following this reasoning, the CLARUS proxy has been implemented as a main process with a plugin

architecture as shown in Figure 1. This process will load different plugins, compiled as java JARs. These

plugins are from 3 types:

• Protocol plugins: The communication between the client application and the CSP (storing and

manipulating sensitive data) relies natively on a dedicated protocol or list of protocols. These

protocols should be added as plugins to manage the client application requests and the CSP

responses. The data communicated using the proxy will be modified/obfuscated but will rely

always on the native protocols supported by the client application and CSP. In this case, we

ensure the transparency of the Proxy mainly from the end-user point of view. Natively the TCP

protocol is supported by the CLARUS proxy which facilitates the integration of protocols on top

of it.

• Data protection plugins: The CLARUS proxy proposes different protection mechanisms for

sensitive data. These mechanisms depend generally on the client application requirements in

terms of data security and privacy. Different plugins are already implemented or under

implementation in the context of CLARUS project. This is the case for the following list: simple

encryption, searchable encryption, homomorphic encryption, anonymization, splitting, verifiable

keyword search.

• Authentication plugin: In the current state of the implementation, only LDAP (Lightweight

Directory Access Protocol) is implemented as a plugin. This is because it is one of the most

common methods to authenticate users in a company network and it is easy to connect to this

authentication and identification service. Other authentication methods can be added for future

developments.



CL

AR

US

Pro

xy

Data protection

pluginData protection

pluginData protections loader

Authentication

mechanism loader

Protocols loader

Authentication

plugin

Protocol

plugin

Security Policy Manager

Inte

r-P

roxy c

om

mu

nic

atio

n

Access Control Policy

Management

Monitoring

Administration

e.g., Data Encyption

CL

AR

US

pro

xy m

ain

pro

ce

ss

Figure 1. CLARUS modules integration

This CLARUS proxy main process can also handle inter-proxy communication. In this context, we

consider that communication between 2 proxies is secured by using for instance a VPN connection. Two

cases are to be handled:

• The proxy is deployed between the client application and a remote proxy. In this case, this

proxy will relay/forward the communication without any modification. Indeed, all the

obfuscation / de-obfuscation task in delegated to the remote proxy that owns the data.

• The proxy is deployed between a first proxy and the CSP. In this case, the first proxy will be

considered as the client application of the main proxy that will treat the first proxy as a

technical user.

One other process must run in the same host (physical or virtual host) as the CLARUS proxy process. It is

the administration process implemented as a command line utility namely clarus-adm. It allows:

• configuring the repository used by the CLARUS proxy for the access rights management

• configuring the user authentication module

• configuring the Cloud Service Providers

o to register a Cloud Service Provider (CSP)

o delete a CSP

o update a CSP configuration

o enable or disable a CSP



• configuring the failover mode

• configuring the deployment of modules

o registering a new module

o deleting a module

o updating a module

Two other separate processes should be deployed in the same host as the CLARUS proxy process. But

this is not mandatory to have them co-located. These modules are:

• The policy manager module (named clarus-spm) that defines the CLARUS security policies, i.e.

what to protect in the outsourced datasets and how to protect it. The output of this program is

a JSON file needed by the CLARUS main process to configure itself.

• The access control policy manager (named clarus-arm) that manages the access right to

different authenticated proxy users. This manager defines the access rights of the users on the

storage/processing services protected by CLARUS. It also defines the permissions of the users

on the outsourced datasets.

Finally, the monitoring module is defined as a standalone module that can run on the same proxy host

as a separate process or a virtual machine in this host or on any standalone (physical or virtual) host.

The whole integration is performed in a platform provided by Thales partner2. This same platform is also

used to test the proxy and assess the fulfillment of its requirements planned in D6.2 “Benchmarking test

suite”.

2.1 Standard deployment

The CLARUS software is composed of a set of tools and libraries that support the protection of data

before storing it in third-party data storage providers. The complete suite of software is composed of

two packages, each one containing complimentary parts of the software:

• CLARUS Proxy: This package contains the main proxy software and the libraries that implement

the supported protocols and protection modules. In the version 1.0.1, this package is composed

of:

o The proxy software, which implements the principal executable module

o The PostgreSQL protocol module, allowing the protection of Potgres-based databases.

o The Encryption protection module, supporting the encryption of the data using AES-

ciphers.

o The Anonymization protection module, which supports the obfuscation of personal data

before storing it in the cloud.

o The Splitting protection module, allowing the data to be split among multiple cloud

servers.

• CLARUS Tools: This package contains complimentary tools that support the configuration of the

complete CLARUS Proxy and the edition of the security policies that specify how to protect the

data. In summary, this package contains three tools:

o CLARUS Security Policy Manager: This tool allows editing new security policies and

registering them in the CLARUS policy server.

2 See Annex A



o CLARUS Acces Rights Management: This tool is intended to be used by the System

administrator to grant and deny the access to the datasets for each registered user.

o CLARUS Security Administrator: this tool allows the administration of modules of the

CLARUS proxy, as well as the remote cloud servers to store the protected data.

2.1.1 Installation of the CLARUS proxy

2.1.1.1 Installing pre-requisites

The pre-requisites can be installed from the official repositories of Ubuntu 16.04. Both packages can be

installed with the command (please note the apt-get command required sudo access to execute):

$ sudo apt-get install mongodb openjdk-8-jdk

This command will install the Mongo Database and the Java Development Kit, which includes the Java

Runtime Environment. Although it is possible to replace the jdk with the java runtime package “openjdk-

8-jre”, it is not recommended.

2.1.1.2 Installing CLARUS packages

Once the pre-requisites have been installed, the CLARUS packages can be installed with the following

command (please note that the dpkg command required sudo access to execute):

$ sudo dpkg -i clarus_1.0.1.deb clarus-tools_1.0.2.deb

Please note that this command needs to be executed in the folder where both deb files reside.

2.1.2 Configuration of the CLARUS proxy software

To help the execution of the tools and the protection of the data, the CLARUS suite relies on

configuration files that need to be modified before executing the software. There are 3 files that require

attention:

• /etc/clarus/clarus-proxy.conf: Principal configuration file of the proxy. In this file, some variables

are required to be correctly set before running the proxy:

o JAVA_COMMAND (default: java): This is the java command that will be invoked to

execute the CLARUS Proxy. In environment with multiple versions of the java runtime,

this variable will help the administrator to execute CLARUS using the right java version.

o JAVA_HOME (required, no default): The CLARUS Proxy modifies the path of the java

external libraries. However, some of these libraries are required by the proxy to

correctly execute. This variable points to the Java runtime folder to correctly locate the

base java external libraries.

o CLARUS_SECURITY_POLICY (required, no default): This variable points to the XML file

containing the security policy used to protect the data.

o CLARUS_LIBRARY_PATH (default: /opt/clarus/ext-libs): This is the path to find the

CLARUS plugins containing protocols and protection modules. Multiple Paths can be

specified by separating the using “:”.

o CLARUS_CLOUD_IP (required, no default): This is the IP address of the cloud server used

to store the protected data.

o CLARUS_CLOUD_PORT (required, no default): This is the port number of the cloud

server used to store the protected data.



o BASE_FOLDER_INSTALLATION (default: /opt/clarus/libs): This is the path of the CLARUS

proxy and is base required libraries.

• /etc/clarus/clarus-keystore.conf: This is the configuration file of the Mongo Database used as

keystore by the Encryption module:

o CLARUS_keystore_db_hostname: This is the hostname (or IP address) of the Mongo

Database to use as keystore.

o CLARUS_keystore_db_port: This is port number of the Mongo Database to use as

keystore.

o CLARUS_keystore_db_name: This is the name of the Mongo Database to use as

keystore.

• /etc/clarus/clarus-tools.conf: In a similar way, the tools also take general configurations. In this

file some variables aare required to be correctly set before executing the tools:

o JAVA_COMMAND (default: java): This is the java command that will be invoked to

execute the CLARUS tools. In environment with multiple versions of the java runtime,

this variable will help the administrator to execute CLARUS using the right java version.

o JAVA_HOME (required, no default): The CLARUS tools modify the path of the java

external libraries. However, some of these libraries are required by the proxy to

correctly execute. This variable points to the Java runtime folder to correctly locate the

base java external libraries.

o CLARUS_TOOLS_LIBRARY_PATH (default: /opt/clarus/ext-libs): This is the path to find

the external libraries used by the CLARUS tools (as the MongoDB connector). Multiple

Paths can be specified by separating the using “:”.

o CLARUS_TOOLS_BASE_PATH (default: /opt/clarus/libs): This is the path where the

CLARUS tools reside.

o CLARUS_TOOLS_VERION: This is the installed version of the tools. It is advised to leave

this variable with the original value, since modifying can affect the correct execution of

the tools.

• /etc/clarus/clarus-mgmt-tools.conf: This is the general configuration file for the CLARUS

Management tool:

o CLARUS_metadata_db_hostname: Hostname (or IP address) of the Mongo Database

used to store metadata.

o CLARUS_metadata_db_port: Port number of the Mongo Database used to store

metadata.

o CLARUS_metadata_db_name: Name of the Mongo Database used to store metadata.

o CLARUS_policies_db_hostname: Hostname (or IP address) of the Mongo Database used

to store the security policies.

o CLARUS_policies_db_port: Port number of the Mongo Database used to store the

security policies.

o CLARUS_policies_db_name: Name of the Mongo Database used to store the security

policies.

2.1.3 Execution of the CLARUS proxy software

The installation of the packages provides useful commands to execute the proxy and the management

tools. These commands are stored in the /usr/bin folder. Please check that this folder is part of the PATH

environment variable before continuing.



2.1.3.1 Starting Local Mongo Server

As seen in the last section, both the proxy and the management tools rely on Mongo databases to store

different data. The configuration files will use a Mongo Database running in localhost, hence it is

required to start the mongo service before continuing. If the system administrator configured to use an

external Mongo server, please check that it is running correctly and accepting connections, and proceed

to the next subsection.

To start the local Mongo database, it is required to run

$ sudo service mongod start

Please note that the service command required sudo permissions to start the mongo database.

2.1.3.2 Executing the CLARUS Proxy

The CLARUS Proxy package provides a straightforward way to start the Proxy. To do so, please execute:

$ clarus-proxy

which will start the proxy on localhost. Depending on the protocol module used, the listening port will

vary. For the default PosgreSQL protocol, the proxy will set up a database server on the port 5432.

2.1.3.3 Executing the CLARUS Management Tools

The CLARUS Tools package provides straightforward ways to execute the management tools. Each tool

can be executed as is shown below:

CLARUS Security Policy Management:

$ clarus-spm <command> <arguments> <options>

CLARUS Security Administrator:

$ clarus-adm <command> <arguments> <options>

CLARUS Access Rights Management:

$ clarus-arm <command> <arguments> <options>

For further reference of the command and options of these commands, please refer to D5.3

2.1.4 Installing and executing the MMT based monitoring solution

In the context of CLARUS project, we propose to deploy this monitoring service as a pre-configured VM

to facilitate its usage. The monitoring service is an adaptation of the on MMT solution and is available

following this link: montimage.com/resources/downloads/clarus/3

3 The login and password for this repository are respectively clarus and clA34__.



The monitoring service has a graphical user interface that displays different reports to the proxy

administrator and detects near real-time potential security issues. The following Figure 2 presents an

example of an alert notified to the administrator after the detection of side channel attack.

Figure 2. MMT GUI showing the detected attack trace

It is also possible to deploy the monitoring solution by installing it directly on the proxy machine by

following these commands:

• Install MongoDB version >= 3.4.4. See: https://docs.mongodb.com/manual/tutorial/install-

mongodb-on-ubuntu/

• Install NodeJS version >= 6.10.3. See https://nodejs.org/en/download/package-

manager/#debian-and-ubuntu-based-linux-distributions

• Note that libpcap0.8 may need to be installed if ubuntu kernel < 4.4.0

o sudo apt-get install libpcap0.8

• NIC on which MMT-Probe is listening on, e.g., eth0, must disable offload

o sudo ethtool -K eth0 rx off gso off sg off rxvlan off gro off tso off

• Install and Run MMT-Probe

o Copy the files in this folder into the home folder of machine to be installed then run

the following commands:

▪ sudo dpkg -i mmt-dpi*.deb

▪ sudo dpkg -i mmt-security*.deb

▪ sudo dpkg -i mmt-probe*.deb

▪ sudo dpkg -i mmt-behaviour*.deb

▪ sudo ldconfig

o Run MMT-Probe by using "sudo mmt-probe -i eth0" to start only MMT-Probe to

monitor traffic on NIC eth0

o Use "sudo mmt-ba" to start MMT-Behaviour

• Install and Run MMT-Operator

o Copy MMT-Operator deb file (mmt-operator*.deb) into the home folder of machine

tobe installed, then run the following command:

▪ sudo dpkg -i mmt-operator*.deb

o sudo mmt-operator

o Note : If MMT-Operator and MMT-Probe are running on 2 different machines and they

communicate together using SSHSF, then file mount-sshfs.sh can be used on MMT-

Operator machine to mount the folder being shared between the machines. In such a



case, one sshfs must be installed on MMT-Operator machine by using the command:

sudo apt-get install sshfs

2.1.5 Release management

The CLARUS proxy open source project is a public project on github.com platform and available

following this link: https://github.com/clarus-proxy. We use git Tags for managing different releases of

the proxy and refer to its compatible dependencies. More information is available in

https://help.github.com/articles/creating-releases/

The current stable version of the proxy is 1.0.1.

2.1.6 Open issues and known bugs

The current version of the proxy supports several protocols and protection mechanisms. The protocols

are Postgresql and WFS, and, the protection mechanisms are simple encryption, anonymization,

splitting, searchable encryption and homomorphic encryption. The open issues are available for each

proxy module in github. For instance, for the proxy core component the list of issues is available in this

link: https://github.com/clarus-proxy/proxy/issues.

2.2 Collaborative deployment

Figure 3: Users and their roles in the multiple CLARUS proxies scenario

The data owning CLARUS proxy – in this Figure 3, CLARUS Proxy 2 – manages the data access for all

external CLARUS proxies in the Inter-proxy communication module. For each external CLARUS proxy a

key is used to encrypt the requested data with, so that the external proxy can decrypt the data. The

policy management defines the access levels for external CLARUS proxies analogue to the intra-proxy

policies. The Inter-proxy communication module creates access policies for external CLARUS proxies and

stores them in the Access Policy DB.

The first Proxy 1 forwards the user requests to the Proxy 2 by changing the identity of the user to a

technical user and forwards later the answer of Proxy 2 to the user like a classical proxy. Notice that the

proxy 1 has a security policy that does not protect any confidential data. All the protection mechanism is

supported by Proxy 2.



Notice that the communication between the two proxies is done through a secure channel such as VPN

so that this communication also satisfies all requirements for secure communication. The proxy 1 is

running with an “empty” security policy where all the data to be protected is empty (i.e. tag <data/>).

2.3 Load Balanced deployment

The CLARUS solution is designed as a microservice architecture which improves flexibility of the whole

solution. Each CLARUS service is simple by design: one proxy provides one functionality (i.e splitting data

or anonymizing data). Therefore, the CLARUS services are easier to integrate with the IT infrastructure

(on baremetals or on VMs or in containers) and to deploy with continuous delivery tools. In the same

way, the CLARUS services are easier to scale with the IT infrastructure and with orchestration tools

(physical or virtual load balancers, cloud orchestration tools, container orchestration tools). See

deliverable D5.4 for more details.

The following deployment architectures show how scalability could be implemented for a specific

CLARUS service:

• Protect one data storage/processing service:

Several CLARUS proxies are deployed behind a load balancer:

Figure 4 - CLARUS proxy - Scalability

Since the protocols supported by CLARUS rely on TCP, the load balancer must be configured to achieve

server-affinity (e.g. using sticky sessions).



3 Configuration

3.1 System

No specific configuration is needed for your system. The proxy is coded in Java and is system

independent. You only need to download and install Java version 8+. The last release is available

following this link: https://java.com/en/download/

3.2 CLARUS Global

It is possible to configure your proxy using two tools:

• The administration management tool: The security manager is provided with an administration

interface in order for him/her to:

o configuring the repository used by the CLARUS proxy for the access rights management

o configuring the user authentication module

o configuring the Cloud Service Providers

▪ to register a Cloud Service Provider (CSP)

▪ delete a CSP

▪ update a CSP configuration

▪ enable or disable a CSP

o configuring the failover mode

o configuring the deployment of modules

▪ registering a new module

▪ deleting a module

▪ updating a module

• The access right management tool: The access right management tool allows the security

manager to:

o define the access rights of the users on the storage/processing services protected by

CLARUS;

o define the permissions of the users on the outsourced dataspaces.

Besides, a configuration file /etc/clarus/clarus-proxy.conf is to be modified. For this part, please refer to

section 4.1.2

3.2.1 Using the administration management tool

The proxy administration module is a command line tool called clarus-adm. It allows managing user

repository, CSPs and the proxy modules. The commands are as follows:

clarus-adm <command> <arguments> <options>

Whatever the command, the security manager must be identified (see options). The user is

prompted for the credentials if they are not specified.

Commands



user_repo < protocol > < credentials > [ < uri > ] [-l, --login <name> [-p, --

password <passwd> | -i <identityfile>]]

Update the configuration of the user repository. Two kinds of user repository are supported:

- embedded

- ldap

If the < protocol > parameter is defined as “embedded” the parameters < uri > is not needed. If

the protocol is defined as “ldap” it is mandatory.

list_csp [-l, --login <name> [-p, --password <passwd> | -i <identityfile>]]

List the CSPs configured inside the CLARUS proxy

register_csp < name > < credentials > < base_endpoint > [-l, --login <name> [-p, --


Register a CSP to the CLARUS proxy

delete_csp < csp_id > [-l, --login <name> [-p, --password <passwd> | -i

<identityfile>]]

Delete a CSP identified by the parameter < csp_id > from the CLARUS proxy

disable_csp < csp_id > [-l, --login <name> [-p, --password <passwd> | -i

<identityfile>]]

Disable a CSP identified by the parameter < csp_id >

enable_csp < cspId > [-l, --login <name> [-p, --password <passwd> | -i

<identityfile>]]

Enable a CSP identified by the parameter < csp_id >

failover < param > [ < masterNode > ] [-l, --login <name> [-p, --password <passwd> |

-i <identityfile>]]

Enable or disable the failover mode of the CLARUS proxy using the < param > as a Boolean. If the

failover mode is enabled, the address of the master node will be declared as a second parameter. If

there is not any, the CLARUS proxy will be considered as the master node.

list_modules [-l, --login <name> [-p, --password <passwd> | -i <identityfile>]]

List all the modules with an id, version and a name.

delete_module < module_id > [-l, --login <name> [-p, --password <passwd> | -i

<identityfile>]]

Delete the module identified by < module_id >

register_module < module_file > [-l, --login <name> [-p, --password <passwd> | -i

<identityfile>]]

Register a new CLARUS module using the < module_file > parameter as an input.



update_module < module_id > < moduleFile > [-l, --login <name> [-p, --password

<passwd> | -i <identityfile>]]

Update a CLARUS module identified by < module_id > using the < moduleFile > parameter as an

input. The module version will be checked and the most recent module will be kept. The other one will

be deleted.

user_auth_module < auth_module_configuration_file > [-l, --login <name> [-p, --


Update the configuration of the user authentication module using the <

auth_module_configuration_file > as an input.

Options

-h, --help

Shows a short usage summary

-l, --login <name>

Specifies the user to log in as on the CLARUS system.

-p, --password <passwd>

Specifies the password of the user to log in on the CLARUS system.

-i <identityfile>

Specifies the file from which the identity (private key) for CLARUS authentication is read.

3.2.2 Using the access right management module

The most important command line is:

clarus-arm set < username > < dataspace > < rights >

sets the <username> read/write permission to the <dataspace> : <rights> can be r, rw or none. none

means that <username> has no rights on the <dataspace>.

3.3 Security Policies

The security policy manager allows to edit a new security policy or to display the ones stored in the

proxy database. It is possible to perform these operations using two complementary tools:

• Command line based security policy manager

• Web based security policy manager

3.3.1 Using the command line based security manager

clarus-spm <command> <arguments> <options>

Commands



create <policyname>

Start definition of a new security policy with the given name. Returns a policyid.

set_dataspace_endpoint <policyid> <protocolname> <port> <baseurl>

Define the endpoint of the dataspace (a dataspace is a virtual space linking the applications

running on premises with the cloud services and on which the security policy is applied). The

dataspace will support the specified <protocolname> and accessible on the specified <port> by

the client applications. The optional <baseurl> can complete the endpoint URL. Returns the

endpoint URL (e.g. <protocolscheme>://<hostname>:<port>/<baseurl>).

set_attribute_type <policyid> <attributepath> <attributetype> <datatype>

Define data attributes regarding security policy: a data attribute is identified by

<attributepath>, a path in the data structure or in the schema (e.g.

‘/<database>/<table>/<column>’ for a database column, ‘/<layer>/<property>’ for a feature

property in a layer, ‘/<file>/<attribute>’ for a feature attribute in a shapefile) ;

<attributetype> can be non_confidential, confidential, identifier, quasi_identifier ;

<datatype> can be categoric, categoric_ordinal, numeric_discrete, numeric_continuous,

geometric_object, etc. Usually, only data related to privacy and confidentiality need to be

protected. If there is already an entry for <policyid> and <attributepath>, changes the value.

set_data_usage <policyid> <datausage>

Set the data usage for the dataspace: <datausage> can be (1) data storage, (2) search in the cloud,

(3) update in the cloud, (4) compute in the cloud. If no value is provided, the list of possible values

is displayed on the console.

set_protection_module <policyid> <protectionmodule>

Set the protection module to apply: <protectionmodule> can be anonymization, splitting,

encryption, etc. If no value is provided, the list of possible values is displayed on the console, and

the most appropriate protection module is highlighted. The list of possible values are given in a

list of protection modules that could be applied according to the configuration defined in previous

steps.

set_protection_param <policyid> <attributetype> <protectionname> <param> <value>

Set the protection parameter for a given attribute type and a given protection: <attributetype>

can be non_confidential, confidential, identifier, quasi_identifier ;

<protectionname> depends on the applied protection module (e.g. it can be suppression, k-

anonymity, t-closeness, coarsening, etc. for anonymization). If no value is provided, the list of

possible values is displayed on the console; <param> depends on the given protection name (e.g.

it can be k for k-anonymity, t for t-closeness, radius for coarsening, etc.). If no value is provided,

the list of possible values is displayed on the console.

convert <policyid> <outputfilename>

Convert the locally-stored JSON policy to an XML format. This command will evaluate the policy

created with the previous commands and write it in <outputfilename> with XML format.



register <policyid> [-l, --login <name> [-p, --password <passwd> | -i

<identityfile>]]

Register a security policy. The security manager must be identified (see options). The user is

prompted for the credentials if they are not specified. Please note that a registered security policy

cannot be modified.

delete <policyid> [-l, --login <name> [-p, --password <passwd> | -i <identityfile>]]

Delete a security policy. If the security policy is registered, the security manager must be

identified (see options). The user is prompted for the credentials if they are not specified.

list [-l, --login <name> [-p, --password <passwd> | -i <identityfile>]]

List all the registered security policies. The security manager must be identified (see options). The

user is prompted for the credentials if they are not specified.

Options

-h, --help

Shows a short usage summary

-l, --login <name>

Specifies the user to log in as on the CLARUS system (required for the register, delete and list

commands)

-p, --password <passwd>

Specifies the password of the user to log in on the CLARUS system (required for the register,

delete and list commands)

-i <identityfile>

Specifies the file from which the identity (private key) for CLARUS authentication is read (required

for the register, delete and list commands).

3.3.2 Using the web based security manager

The security policy manager web tool allows users to create, define and edit security policies through an

intuitive web page, useable in any modern web browser.

To start the security policy management, the user must use the CLARUS web administration tool and

chose the “Manage Security Policies” section, as shown in the Figure 5.



Figure 5. Manage Security Policies section of the CLARUS web administration tool

The user is then presented with a list of all existing security policies. He can either edit or delete these,

or publish an existing policy. A published policy cannot be changed anymore. In the example in Figure 6,

there are 4 unpublished policies.

Figure 6. List of all unpublished policies.

This view also allows the user to create a new policy. He needs to enter a name for the new policy and

then click on the “Add new Policy” button. Clicking on the “View Published Security Policies” link on the

bottom on the view leads the user to the screen shown in Figure 7.



Figure 7. List of published policies. These cannot be changed anymore.

All published policies are listed here with their identification number (ID) and name.

If the user clicks on the “Edit“ button of one of the unpublished policies shown in Figure 6, the Security

Policy detail view as shown in Figure 8 is shown. Here, the user can change individiual aspects of each

single Security Policy. First of all, this is the endpoint and the protocol of the policy as well as the single

protection attributes and their parameters.



Figure 8. Security Policy detail view with editing possibility. Allows the user to add, remove or change single

aspects of a single Security Policy.

If there are predefined values for single parameter, a drop-down box is presented with all possible

values. If the parameter allows free values, a click on the “Edit” button of that parameter changes its

value fields into editable text boxes, where the user can simply enter their desired values. After the user

saves his changes, he can return to the overview of the managing tool.

Offering the described functionality, the Security Policy Web Form is a visualized alternative to the

command line based Security Policy Manager.

3.4 Upgrading the proxy

When a new version of the proxy is available, the IT responsible of the CLARUS proxy should manually

download it and install it. A notification mail is sent to all the users that already downloaded the

previous versions of the proxy.



If only the protocol module or data protection module is to be upgraded, it is possible to use the

administration module using the following command line:

update_module < module_id > < moduleFile > [-l, --login <name> [-p, --password

<passwd> | -i <identityfile>]]

Update a CLARUS module identified by < module_id > using the < moduleFile > parameter as an

input. The module version will be checked and the most recent module will be kept. The other one will

be deleted.



4 Usage example

This section shows how to use the CLARUS proxy and tools, in order to correctly protect the data before

externalizing it to third-party servers.

In the example presented in these pages, we will use the Encryption module to protect some columns;

however, the instructions given can be easily applied to any other protection module.

The main objective of this is the creation of a PostgreSQL table with 8 columns, all of them containing

text, protecting the last 7 fields. Table 1 Table specification below shows a summary of the desired

structure:

Table 1 Table specification

Column Name pat_id pat_name pat_last1 pat_last2 ep_id lab_id lab_ver lab_pdf

Protected? No Yes Yes Yes Yes Yes Yes Yes

4.1 Security Policy creation

The first step is the creation of the security policy. To this end, the clarus-spm (Security Policy

management) tool, which is included in clarus-tools package.

The first step is the specification of the attributes in the security policy. To this end, we will use a set of

commands using the clarus-spm tool:

1. Create a new security policy. The tools will return the ID of the created policy. $ clarus-spm create TestPolicy

The ID of the policy created is 7

2. Set the endpoint used for the policy. As we are using the Postgres protocol it is required to specify which is the protocol module affected by this policy.

$ clarus-spm set_dataspace_endpoint 7 PostgreSQL 5432

Endpoint set succesfully. The Endpoint URL is:

pgsql://host_name:5432/

3. Specify the columns that will be protected. In this case, we need to specify the names (wildcards are used to protect similar attributes in multiple databases and/or protocols), the protection type and the data type of the attribute. The data type should match the data type present in the database.

$ clarus-spm set_attribute_type 7 */pat_name confidential varchar

An attribute for path */pat_name in policy 7 was added

$ clarus-spm set_attribute_type 7 */pat_last1 confidential varchar

An attribute for path */pat_last1 in policy 7 was added

$ clarus-spm set_attribute_type 7 */pat_last2 confidential varchar



An attribute for path */pat_last2 in policy 7 was added

$ clarus-spm set_attribute_type 7 */ep_id confidential

numeric_discrete

An attribute for path */ep_id in policy 7 was added

$ clarus-spm set_attribute_type 7 */lab_id confidential

numeric_discrete

An attribute for path */lab_id in policy 7 was added

$ clarus-spm set_attribute_type 7 */lab_ver confidential

numeric_discrete

An attribute for path */lab_ver in policy 7 was added

$ clarus-spm set_attribute_type 7 */lab_pdf confidential

numeric_discrete

An attribute for path */lab_pdf in policy 7 was added

4. Specify the overall usage of the data. To better understand and choose the usage that best fit your data; a tool has been developed and published on CLARUS’ website. You can use it to guide you in this matter: http://www.clarussecure.eu/advisory-tool

In this case, the data will only be stored in the cloud.

$ clarus-spm set_data_usage 7 storage

The usage for policy ID 7 was correctly set.

As we write this guide, the XML representation of the security policy does not display the

“data_usage” attribute. Nevertheless, this information is indeed stored in the proxy. In the

next release of the CLARUS proxy this attribute will be displayed.

5. Set the Protection module that will be used to protect the data. In this example, we will use the encryption module.

$ clarus-spm set_protection_module 7 encryption

The Protection module for Policy ID 7 was correctly set.

6. Specify any parameter the protection module might use. The Encryption module uses the id_key parameter, which specifies the id in the keystore of the secret key that will be used to protect the data.

$ clarus-spm set_protection_param 7 confidential encryption id_key

123

The Policy ID 7 was updated sucessfully

7. Convert the policy to XML format. The clarus-spm tool was designed to provide JSON-formatted security policies, however, the proxy requires the policy to be expressed in XML format. To this end, the clarus-spm tool offers the possibility to export the policy to XML format.

$ clarus-spm convert_policy 7 policy.xml



The policy ID 7 was correctly converted to XML.

The summary of this process can be seen in Figure 9. In Figure 10 it is shown the generated XML security

policy.

Figure 9 Creation of the security Policy

Figure 10 Generated XML Security Policy

4.2 CLARUS Proxy configuration

Once the security policy has been created, it is required to correctly configure the CLARUS Proxy to use

the recently-generated policy. This is done by editing the corresponding configuration file located at

/etc/clarus/clarus-proxy.conf.



In this file, the variable CLARUS_SECURITY_POLICY has to be specified so that it contains the full path of

the security policy to be used by the proxy. In Figure 11 we show how this file is configured to point to

the recently created security policy.

Figure 11 CLARUS Proxy Configuration

4.3 CLARUS Proxy Execution

Once the Proxy has been configured, it is possible to start it. This is done by invoking the clarus-proxy

command. If the configuration has been correctly done, the Proxy will start, showing on the screen the

protection module used, as shown in Figure 12.

Figure 12 Proxy Execution



4.4 Connection to the CLARUS Proxy

At this point, the Proxy is ready to accept incoming connections. To connect to the proxy, we will use the

PgAdmin software. The connection will ask for a password. Once connected, there will be a public

schema with no tables in it, as seen in Figure 13.

Figure 13 Empty Proxy Running

4.5 Execution of the SQL Queries

Using the PgAdmin software, two SQL queries will be executed in order to create the protected table

and insert the data into it.

Figure 14 shows the execution of the query to create the table specified in Table 1.



Figure 14 Creation of the Table

Once this query is ready, it is possible to insert data into it and the CLARUS Proxy will take in charge the

protection of the columns according to the given security policy. In Figure 15 it is shown the execution of

the “insert” query.

Figure 15 Insertion of Rows in the Created Table

Finally, in Figure 16 we can see the differences between select queries run through the proxy on the one

hand, and directly on the cloud server on the other. On top, the data retrieved are shown unencrypted,

as the “select request has been executed through the proxy”. While below, the raw data stored in the



cloud server are shown encrypted, with the corresponding columns containing encrypted data instead

of their plain value.

Figure 16 Stored Data in Different Servers



5 Extending the proxy

5.1 Protocol module extension

The communication between the client application and the CSP can rely on different protocols

depending on the nature of provided services. In the context of the CLARUS project, the following

protocols have been considered : PostgreSQL/PostGIS, HTTPS and WFS.

But other protocols may be needed to store, retrieve and search on sensitive data deployed in an

untrusted cloud. For example we may think about the Amazon S3 protocol to store and retrieve data on

the cloud, or about any protocol easing data exchange in different domains (interoperability), but which

at the same time have to deal with data protection issues.

In order to provide support for these protocols, a developer willing to extend the CLARUS solution needs

to develop a “protocol plug-in” extending the so-called “protocol module”. In the CLARUS landscape, the

protocol module is the necessary transit point of any CLARUS-secured application communicating with a

cloud service. It is the only CLARUS module which needs to understand the protocol used by the client

application, i.e. the only one which is protocol-dependent compared to other modules (such as the data

operation module) which are protocol-agnostic. That is why it is necessary to extend CLARUS in the case

someone wants to secure an application which does not use one of the protocols natively supported, i.e.

PostgreSQL, PostGIS or the Web Feature Service.

5.1.1 Implementation of the service provider interface

To support additional protocols, the CLARUS proxy has been designed with a plugin architecture that

allows adding new protocol plug-ins. The JAR specification offers since Java 6 a very practical feature:

the Service Provider Interface (SPI). Behind this uninviting name is a mechanism for dynamically

discovering and loading classes that respond to a given interface.

The SPI mechanism is composed of 3 elements:

- a service, represented by an abstract class.

- a configuration file named eu.clarussecure.proxy.spi.protocol.Protocol to be placed in the

META-INF/services folder and declaring one or more implementations of this service

- the ServiceLoader, responsible for discovering and loading service implementations.

A new protocol plug-in must implement the Protocol SPI interface so that the proxy application can

resolve and load it. See below this interface:

package eu.clarussecure.proxy.spi.protocol;

import java.util.concurrent.ExecutionException;

public interface Protocol {

ProtocolCapabilities getCapabilities();

Configuration getConfiguration();

void start();



void waitForServerIsReady() throws InterruptedException;

void sync() throws InterruptedException, ExecutionException;

void stop();

default String[] adaptDataIds(String[] dataIds) {

return dataIds;

}

}

In order to take into account the specificities of the protocol, the plug-in should provide an extension of

the following CLARUS classes:

- eu.clarussecure.proxy.spi.protocol.ProtocolExecutor (abstract implementation of the service

provider interface)

- eu.clarussecure.proxy.spi.protocol.Configuration

- eu.clarussecure.proxy.spi.protocol.ProtocolCapabilities

As required by the Java extension mechanism, the protocol plug-in must be packaged as a Java library

and placed in a dedicated directory (here the ext-libs directory). This could be done thanks to Maven

“Project Object model” instructions :

<profile>

<id>install-libs</id>

<activation>

<activeByDefault>true</activeByDefault>

</activation>

<properties>

<install.dir>${project.parent.relativePath}/install/ext-libs</install.dir>

</properties>

<build>

<plugins>

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-dependency-plugin</artifactId>

<executions>

<execution>

<id>copy-dependencies</id>

<phase>install</phase>

<goals>

<goal>copy-dependencies</goal>

</goals>

<configuration>

<outputDirectory>${install.dir}</outputDirectory>

<overWriteReleases>false</overWriteReleases>

<overWriteSnapshots>false</overWriteSnapshots>

<overWriteIfNewer>true</overWriteIfNewer>

<includeScope>compile</includeScope>

</configuration>

</execution>

<execution>

<id>copy-installed</id>

<phase>install</phase>

<goals>

<goal>copy</goal>

</goals>

<configuration>

<artifactItems>

<artifactItem>



<groupId>${project.groupId}</groupId>

<artifactId>${project.artifactId}</artifactId>

<version>${project.version}</version>

<type>${project.packaging}</type>

</artifactItem>

</artifactItems>

<outputDirectory>${install.dir}</outputDirectory>

<overWriteReleases>false</overWriteReleases>

<overWriteSnapshots>false</overWriteSnapshots>

<overWriteIfNewer>true</overWriteIfNewer>

</configuration>

</execution>

</executions>

</plugin>

</plugins>

</build>

</profile>

5.1.2 Processing requests and responses

Ideally, a protocol plug-in for CLARUS is a Java8+ program, relying on the Java networking API (namely

NIO) and on the Netty framework which allows developing efficient client/server applications, see

https://netty.io/

In order to process the requests and responses, we therefore advise to define two distinct classes,

extending the Netty ChannelInitializer class :

• a client pipeline initializer (for processing requests from the client to the server)

• a server pipeline initializer (for processing responses from the server to the client)

Each of these classes can in turn apply different treatments on requests and responses, and in particular

aggregating requests in the case of buffering, initializing a session, building modified queries according

to the data operation triggered or reconstituting expected responses, etc.

The best for developers willing to implement an efficient plug-in for their own protocol is actually to

study in depth an example implementation, like the PostgreSQL or the WFS protocol plug-ins, which are

extensively described in the D5.3 “CLARUS modules v2”.

5.2 Data protection module extension

In the context of WP3, different data operation modules have been designed and implemented in order

to protect sensitive data e.g., data encryption, data splitting, data anonymization etc. Details about

these mechanisms are provided in D3.3 deliverable.

The CLARUS proxy has been designed to allow the support for new data protection mechanisms by

relying on a plugin architecture. The Data operations public API is a common interface for all the data

operation modules, both already implemented or under development within the CLARUS project and for

future data operation modules. The API bridges the communication between the protocol module and

the data operation modules, abstracting the concrete details of the protocol modules implementation.

Table 2. DataOperation Interface

eu.clarussecure.dataoperations interface DataOperation

https://netty.io/



Version 2.4

Type Method and description

List<DataOperationCommand> delete(String[] attributeNames, Criteria[] criteria)

Outbound DELETE Operation, deletes data specified by criteria.

List<DataOperationResult> get(List<DataOperationCommand>, List<String[][]> contents)

Inbound GET operation (RESPONSE), reconstructs data received by

CSP.

List<DataOperationCommand> get(String[] attributeNames, Criteria[] criteria)

Outbound GET operation.

List<DataOperationCommand> post(String[] attributeNames, String[][] contents)

Outbound POST operation. Modifies data according to security policy.

List<DataOperationCommand> put(String[] attributeNames, Citeria[] criteria, String[][] contents)

Outbound PUT operation. Modifies data specified by criteria, according

to security policy.

List<Map<String,String> head(java.lang.String[] attributeNames)

Returns the metadata associated with the transformation of the

dataset, e.g. the translation between original attribute names and

protected attribute names.

DataOperationResult is the root of all possible return values of the get, post, put and delete methods of

the DataOperation API. It is an abstract class that contains the internal id of the call as assigned by an

instance of DataOperation, and the attribute names involved in the call. This class should not be

extended by data operation module developers.

Table 3. Abstract class DataOperationResult

eu.clarussecure.dataoperations abstract class DataOperationResult implements Serializable


String[] getAttributeNames()

Attribute names involved in the call.

int getId()

Internal ID of the call.

DataOperationCommand represents calls transformed by the data operation module instance destined

to the CSP. This class contains all necessary information for the Protocol Modules to build calls directed

at the CSP. DataOperationCommand is an abstract class that should be extended by data protection

modules developers.

Table 4. Abstract class DataOperationCommand

eu.clarussecure.dataoperations abstract class DataOperationCommand extends DataOperationResult


String[] getProtectedAttributeNames()

Returns the attribute names as modified by the data operation module.

String[] getExtraProtectedAttributeNames()

Returns additional attribute names not directly associated with the original



attribute names.

InputStream[] getExtraBinaryContent()

Returns additional content generated by the data operation module.

Map<String,String> getMapping()

Returns the metadata associated with the transformation of the particular call by

the data operation module, e.g. the translation between original attribute names

and protected attribute names.

Criteria[] getCriteria()

Returns the search criteria of the call.

String[][] getProtectedContents()

Returns the contents of the call as modified by the data operation module.

void setProtectedAttributeNames(String[] protectedAttributeNames)

Sets new protected attribute names.

void setExtraProtectedAttributeNames(String[] extraProtectedAttributeNames)

Sets new extra protected attribute names.

void setExtraBinaryContent(InputStream[] extraBinaryContent)

Sets new extra binary content.

void setMapping(Map<String,String> mapping)

Sets new metadata associated with the transformation of the call.

void setProtectedContents(String[][] protectedContents)

Sets new protected contents.

void setCriteria(Criteria[] criteria)

Sets new search criteria.

DataOperationResponse contains the reconstructed response by the CSP to the user who issued the

call. It contains the necessary information for the Protocol Module to build a response directed at the

user client application. This is an abstract class that should be implemented by data operation modules

developers.

Table 5. Abstract class DataOperationResponse

eu.clarussecure.dataoperations abstract class DataOperationResponse extends DataOperationResult


String[][] getContent()

Returns the content contained in the response by the cloud, after inverting the

transformations made by the data operation module (e.g. decrypting the

contents).

Criteria is a representation of the search criteria as used by the get, put and delete operations. Multiple

Criteria are evaluated as if connected by ANDs, but module developers can freely interpret the contents

of this class.

Table 6. Class Criteria

eu.clarussecure.dataoperations class Criteria implements Serializable




String getAttributeName()

Returns the attribute name associated to this search criteria.

String getOperator()

Returns the comparison operator of this search criteria. Operators include “=”,

“<”, “>”, “<=”, “>=”, “in”, “area”, among others.

String getValue()

Returns the value to which the attribute is compared.

void setAttributeName(String attributeName)

Sets a new attribute name.

void setOperator(String operator)

Sets a new operator.

void setValue(String value)

Sets a new value.

The class AttributeNamesUtilites is a utility class to bridge the instantiated security policy and the actual

attribute names present in the protected datasets. This class contains methods to resolve concrete

attribute names with respect to abstract attribute names in the security policy.

Table 7. Class AttributeNamesUtilities

eu.clarussecure.dataoperations class AttributeNamesUtilities


List<String> fullyQualified(List<String>)

Replaces unqualified attribute names by generic qualified ones.

String fullyQualified(String)

Replaces an unqualified attribute name by a generic qualified one.

String[] resolveOperationAttributeNames(String[], List<String>)

Resolves the operation input attribute names that contain “*” according to the

associated security policy.

String escapeRegex(String)

Escape special characters.

String resolveProtectedAttributeName(String, String)

Resolves a protected attribute name that contains “*” according to the operation

input attribute name.



6 Conclusion

This document presents a user and an administration guide for the CLARUS proxy for the release 1.0.1.

Notice that this is a live guide that is based on a living open source project that can and will evolve over

time. It introduces all security mechanisms in order to obtain a trusted CLOUD platform by using the

CLARUS solution.

The user guide presented in this document is valuable to an integrator or an administrator of the

CLARUS solution. We explain and describe all the requirements that need to be fulfilled in order to

deploy a fully functional CLARUS proxy. This guide matches the three kind of deployment model that are

supported by CLARUS. They can be implemented by the integrator depending on the size and usage of

his end user. We describe all the administration mechanisms and tools that allow the administrator to

operate safely his instance(s) of the CLARUS proxy. A section is also specifically targeting the

implementation of security. This work is also targeting developers that want to extend CLARUS to better

suit his needs or contribute to the CLARUS community by enhancing the Open Source Project available

on github.

The underlying test bed that supports and validates this integration work is a realistic and standard

architecture of a Cloud Service Provider.



Annex.A The CLARUS private integration platform

The CLARUS integration platform hosts all the CLARUS proxy modules and allows their integrations to

build different proof of concept demonstrations. This platform is hosted privately on THALES premises.

It is accessible only by the members of the consortium. More details are provided in the next sections.

This platform has been built in order to represent the real condition of a Cloud Service Provider.

A.1 Platform Design

A.1.1 Architecture

Figure 17. The THALES platform architecture



Figure 17 presents the global architecture of the THALES platform. The details of different platform

features are presented in the next subsection A.2.

A.2 CLARUS integration platform

This annex is intended to guide the CLARUS partners on how to use the platform to build different proof

of concept demonstrators integrating different version of CLARUS proxies and use cases. This manual

can also be a first documentation for an early adopter of the CLARUS solution.

A.2.1 Environment

The THALES platform is also intended to facilitate the development and delivery of CLARUS’ modules. It

is for now divided into 4 main networks:

• integ-dev

• geoLoc

• eHealth

• services

The first (integ-dev) is an open network where the developers are able to start/instantiate virtual

machine(s) based on Openstack4 in order to deploy their own modules. This network has no specific

constraints so that every user can build new VMs to test specific integrations between different

modules.

The second and third networks (GeoLoc and eHealth) are only available through the port numbers

80 and 443. These networks are intended to be the PoC demonstrators of the project use-cases and are

intended to be easily and automatically reproducible.

The final network (services) is the network where all the platform-related services are available.

For instance, a GIT repository based on the GitLab tool is available so that every partner can store the

source code, the configuration files, and the documentation of its developed module(s). An aptitude

relay is also available so that every partner can install packages into its VM(s) on the integ-dev network.

WARNING: In all environments no Internet is available

In order to order to correctly deploy the two use case applications, THALES also provides public

cloud services supporting Postgres and S3/SWIFIT for Storage as a Service. One Postgres server for each

use case and three S3 CSPs are available for different usages.

4 https://www.openstack.org/



A2.2 Connection

An X509 certificate is requested from THALES administration team composed of Romain FERRARI and

Jérôme VENANT in order to set up the VPN connection to the platform.

The access to the VPN server is to be performed using OpenVPN with UDP through the 11194 port. An

example of a configuration file for Linux is provided below:

#### VPN definition

client

remote <IP_OF_THE_CLARUS_VPN> <PORT_OF_CLARUS_VPN> udp

nobind

dev tapKalEL

auth-nocache

resolv-retry infinite

#### SSL/TLS root certificate, certificate, private key

askpass

ca client.certs/ca.crt

cert client.certs/client.crt

key client.certs/client.key #### MUST BE KEPT SECRET

# Wireless networks often produce a lot of duplicate packets. Set

this flag to silence duplicate packet warnings

mute-replay-warnings

#### Misc

comp-lzo

daemon

log /tmp/ovpn.log

#### MTU troubles Fix

fragment 1300

mssfix

# Set log file verbosity.

verb 3

# Silence repeating messages

mute 10



A.2.3 VM Provisioning

A.2.3.1 Account configuration

The Thales Administration Team provides authorized partners with a login and a password to connect to

the Openstack Dashboard in order to manage their VMs.

The first thing to do after a first connection is to create a set of RSA keys. In order to do that, you may

import your own keys created on your own computer or you can generate them directly using the Web

interface available using the URL provided by Jérôme.

Figure 18. Authentication the THALES platform

After connection, a user needs follow these steps:

• Click on the top right side of the screen on your username then on parameters.

• Click on the “Compute” link on the left side then click on “Access and Security”

• Choose the tab Key Pair.

Figure 19. OpenStack Interface – Access & Security



• Click on create a Key Pair, choose a name and click on “Create key pair”. The key pair will be

created inside the interface and you will have to download the private part. DO NOT LOOSE

YOUR PRIVATE KEY. If you lose it, we will have no way of retrieving it and you will no longer

have access to your VMs.

A.2.3.2 Create a VM

The VM in the sandbox environment MUST be provisioned using the CLARUS Template image. It’s an

Ubuntu based image (Ubuntu 16.04) with the configuration needed to work with the CLARUS

integration platform.

• Connect to your VPN

• Open your favorite browser to the openstack dashboard url provided by Jérôme.

• Type in the user and password that was given to you by the Thales Administration Team.

Figure 20. Openstack interface - Instances

• Click on the “Compute” link on the left side then click on “Instances”.

• Then Click on “Launch Instance” on the right side of the screen.



Figure 21. Openstack interface – Creating a new VM

• Fill in the form. For a standard VM you can use the same configuration as the one above.

• The “Access and Security” tab should show the name of the previously imported SSH key. The

“Network” tab should show the integDev network.

• No more configurations are needed at this stage. Just click on launch to instantiate the VM.

• Wait until the VM generation is finalized then you can connect to your VM using SSH with the

user “ubuntu” and the IP written in the description.

Figure 22. Openstack interface – List of VMs

$ ssh [email protected] -i ~/clarus/myKeySandbox

A2.3.3 CLARUS Release Process

The release process can and will probably evolve in order to be as much easy and stable as possible.

Docker Releases

The releases must be supplied as Docker containers. Each Dockerfile must be provided in the GIT

repository of the use-case project (Geoloc and eHealth) in the branch of each module. The reference



Dockerfile must be present under the directory docker of each branch. If there is no branch describing

your module, create one.

A README.md must be provided under the docker folder. Such a README must give instructions about

how to work with the corresponding Docker container.

Dockerfile must follow the best practices described here:

https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/

To merge the stable version of each use case a Merge Request need to be done and should be approved

by the responsible of the use case.

A Dockerfile sample will be provided in the project repository.

A.2.3.4 Services

Git

A git repository is available for all CLARUS’ partners to use. It is accessible using the gitlab url provided

by Jérôme after the correct set up of the VPN.

The web interface is based on the GitLab OSS version 8.8.4 (https://gitlab.com/gitlab-org/gitlab-ce). All

users will be available to create projects, groups and branches. The users will be added by the Thales

Administration Team at the same time as the X509 for the VPN is created.

Aptitude relay

An aptitude relay is set up in order to properly update the VMs’ environment. In order to configure it

you need to issue the command (as root):

$ echo “Acquire::http::proxy \"http://<apt-cache-url>:3142\" ;” > /etc/apt/apt.conf.d/01proxy

Documents

A framework for user centred privacy and security in the cloud