Getting started with Sharemind SDK

The requirements

• The available SDK requires Windows to run.
• Currently you are required to install the SDK in a folder, where the SDK applications will have the writing permission.
• The software included in the SDK requires a network connection for communication.
• In case you have a firewall installed, it may complain about the SDK applications trying to open some ports. Please arrange the necessary ports for the applications according to your configuration.
• The SecreC Compiler component requires that you have at least Java 1.4 installed and set in %PATH%.

The installation steps

1. Read & accept the terms of the license agreement
2. Select components to install (full installation is recommended)
3. Select the destination folder, where the Sharemind SDK will be installed. NB! It must be writable for the SDK applications!
4. Click 'Install'

Sharemind SDK Components

DevMiner (required) - The Sharemind secure multiparty computation software is crafted specifically for development and testing purposes. Basically, it combines three data miners in one executable with corresponding console output screens and a comfortable control panel.

SecreCIDE (required) - An Integrated Development Environment (IDE) for the SecreC language and Sharemind assembly.

SecreC Compiler (required) - A SecreC language compiler, that is used by SecreCIDE to compile SecreC programs into the Sharemind assembly. After compilation, the resulting Sharemind assembly code can then be executed on miners (DevMiner).

Test data (optional) - The "mushroom" dataset is ready to use by the miners for frequent itemset mining.

Example programs (optional) - Included are:

1. An unoptimized privacy-preserving SecreC version of frequent itemset mining algorithm called Apriori.
2. A client-side Sharemind demo application with miner database setup, privacy-preserving data entry and analysis capabilities.

Development headers and libraries (optional) - The new version of Sharemind SDK includes headers and libraries necessary to build your own privacy-preserving applications.

What can you do with Sharemind SDK?

1. Running DevMiner

DevMiner is a program that incorporates three data miner instances with virtual network communication channels inbetween.

To run the DevMiner, simply execute it. As you can see on the following screenshot, the DevMiner provides a user with a comfortable user interface with a console output screen component for each miner instance and a control panel at the top for starting, restarting and stopping the miners.

In order for client software (e.g. SecreCIDE and Sharemind Demo application) to connect to DevMiner, the built-in miner instances additionally listen to normal incoming network connections on three different ports, one for each miner. These ports can be configured on the options tab in the bottom-right corner of the DevMiner's UI.

2. Running the Sharemind demo application

With the Sharemind demo application you can try out some of the core features of Sharemind platform in practice. It is a client-side application that communicates with data miners to store secret data in a privacy preserving way and later analyze it. Therefore, for the demo application to work, you are required to run the DevMiner and start the miners inside of it.

Before starting the demo application you will need to configure the network addresses and ports of the miner instances to connect to. This can be done by editing the <Sharemind SDK folder>\Examples\SharemindDemo\SharemindDemo.cfg file. If you are using default port values in DevMiner, then leave the file as is. After this is done, run the SharemindDemo.exe file.

Application's user interface is divided into three tabs: database setup, data entry and data analysis.

2.1. Database setup tab

This tab gives you a straightforward interface to set up the necessary databases in the DevMiner. There will be three databases, one for each miner instance. These databases will be used to store the private data in secret-shared form on miners for later computations.

To reset the databases you will have to drop the existing databases and recreate the new ones.

For the reference, here is the data model used by the application:

• Database: shareminddemo
• Table: people
• Columns: gender, age, weight, education, role

2.2. Data entry tab

This tab contains a simple form with five fields. After each form submission the field values are secret-shared on the client side so that a five-element entry of seemingly completely random data is generated for every miner. Each such entry is securely sent to a corresponding miner, where it is stored in a database. The miners are not able to derive the original information from the entries they receive, since those look as a completely random noise to them.

The form also has a "Clear form" button, that allows one to clear the form after his/her data has been sent and let the next person enter the data.

2.3. Data analysis tab

The data analysis tab is designed to display some statistics about the data. By pressing the "Refresh data" button a user instructs the client to query the miners for the new analysis results based on the latest data in miners' databases. The miners calculate new results by collaboratively running the previously agreed and verified privacy-preserving algorithms and return only the final results to the client for display without leaking more information than necessary.

3. Running SecreCIDE

SecreCIDE is an Integrated Development Environment (IDE) built to assist the developer of privacy-preserving algorithms for the Sharemind platform. The algorithms are written in the privacy-aware programming language called SecreC, and then compiled into the Sharemind assembly for execution on data miners. SecreCIDE provides all the necessary tools to make the development process easier. Moreover, it has built-in debugging capabilities for effectively finding misbehaviors in the SecreC programs by following the execution flow and reading run-time memory values in the Sharemind virtual machine.

Getting started with SecreCIDE is very easy and fast. First start the SecreCIDE application and you will see its user interface as shown and described on the following picture.

In order to get SecreCIDE ready for development, a user has to make sure a few configuration options are set correctly (in a successful SDK installation they should by default). Follow these steps to do that:

1. Open the Tools -> Options dialogue window
2. On the Compiler tab: make sure the SecreC Compiler Path is correctly refering to <Sharemind SDK folder>\SecreC\compile.bat file
3. On the Runtime tab: make sure the ports of the miners correspond to those set in DevMiner application

For running or debugging the programs from within the SecreCIDE, it is also necessary to run and start the DevMiner, so that SecreCIDE can connect to it.

You should now be ready to use SecreCIDE!

3.1. Running the demo scripts

When the Sharemind demo application queries the miners for the latest data analysis results, the miners run corresponding privacy-preserving algorithms to calculate the results. The SecreC versions of those algorithms are included in the Sharemind SDK and are located in the <Sharemind SDK folder>\Examples\SharemindDemo\SecreCScripts directory. The included algorithms are:

1. Average
2. Average in group
3. Count items in range
4. Range histogram (similar to 3, but has hardcoded columns and ranges)

For these algorithms to work, the corresponding databases should be set up and filled using the Sharemind demo application.

Provided that this is done, you can follow these steps to open, compile and run the algorithms:

Open:

Open the project <Sharemind SDK folder>\Examples\SharemindDemo\SecreCScripts\SharemindDemo.scp in SecreCIDE. You will see the corresponding SecreC source files (*.sc) appear in your project tree view. To open the files just double-click them.

Compile:

In order to run the algorithms, they have to be compiled into Sharemind assembly first. This can be done by right-clicking the SecreC file in the project view and selecting "Build File" option from the popup menu, which will result in a new .sa (sharemind assembly) file in the project. The currently active SecreC (.sc) file can also be compiled by clicking the "Build" button in the SecreCIDE toolbar.

Run:

Having built the algorithm, you can then run it. Every SecreC program has an entry point function called "main" that may have zero or more arguments. These arguments must be passed to the compiled program before running it. To do this right-click the corresponding .sa file and select "Set Runtime Arguments" in the menu. In the appeared window enter the argument names, types and desired values according to the signature of the "main" function in the SecreC code of the algorithm. If you need table or column values, please refer to the data model description in the Sharemind demo application section. After this is done, right-click the .sa file and select "Run". You will see various output and possibly the results...

To make it clearer how run algorithms with runtime arguments, we will give an example based on the average.sc algorithm. The main function in that file has the following signature:

void main(public string table, public string column)

meaning that it takes in two public string arguments: the first one is for database table name and the second one for the column name. Since we use the same database layout as the Sharemind demo application, lets suppose we want to calculate an average over the age column in the people table. The two runtime arguments that need to be set for the average.sa file to run are as follows:

If everything was done correctly, you should see the miner instances in the DevMiner window begin generating action logs as the average.sa file is executed. When it finishes, the end result should be printed in the Results tab of the SecreCIDE's output block. The average algorithm returns the sum over the queried column and the number of entries in the column. By doing simple math you can calculate the average value over the age column.

3.2. Running the Apriori algorithm

Another interesting algorithm included in the package is the privacy-preserving version of a frequent itemset mining algorithm called Apriori. The corresponding .sc and the project file are located in the <Sharemind SDK folder>\Examples\AprioriUnoptimized\ folder. Note, that the provided version can be significantly optimized further, but is sufficient for demonstration purposes. In case you are not familiar with frequent itemset mining or you are interested in a detailed view of this and some other privacy-preserving algorithms for Sharemind, please refer to the Roman Jagomägis's Master's Thesis SecreC: a Privacy-Aware Programming Language with Applications in Data Mining on our research page.

The steps to open, compile and run the algorithm are very similar to the ones described in the previous section, except that it is not necessary to set the runtime arguments. All the needed information is already inlined into the AprioriUnoptimized.sc file. The algorithm uses the mushroom database (already provided with the SDK) to find out the itemsets of certain size that occur in the database at least the number of times as defined by the given threshold (also called the support). These itemsets are called frequent itemsets.

Given threshold of 5000 and a set size of 5 the correct output result of the Apriori algorithm using the provided mushroom database is a single frequent itemset {34,36,85,86,90}. This information can be used to verify your Sharemind SDK installation.

4. Building custom privacy-preserving applications

Sharemind SDK includes development headers and libraries that can be used to build Sharemind controller applications used for both data entry and data analysis. To get started, continue with Creating applications with Sharemind SDK.