> For the complete documentation index, see [llms.txt](https://ldsec.gitbook.io/unlynx/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ldsec.gitbook.io/unlynx/running-unlynx.md). # Running UnLynx UnLynx can be split in different running instances. The ***protocols*** specify individual elements/building blocks that compose our software tool and can be tested independently. The ***services*** are the assembly of the different protocols into something that can provide different functionalities. The ***simulations*** enable the simulation of each of our services or protocols under specific settings. Finally, the ***applications*** use a real deployment of UnLynx to design a set of APIs than can be made available to potential users. There are 4 global parameters in `github.com/ldsec/unlynx/lib/constants.go` that can be set before executing any of these instances. * `TIMEOUT` - `TIMEOUT` stores the timeout for node communication and can be changed by setting the `CONN_TIMEOUT` environment variable. * `TIME` - `TIME` is true if we want to measure the time of computations. * `VPARALLELIZE` - `VPARALLELIZE` allows to choose the level of parallelization in the vector computations (>=1). * `DIFFPRI` - `DIFFPRI` enables the DRO protocol (Distributed Results Obfuscation). For more information on how to run a protocol/service/simulation/cmd please refer to [cothority\_template](https://github.com/dedis/cothority_template) ### Protocols **Note**: We denote as `ciphertexts` the encrypted messages. Each protocol instance is run at every conode. For each protocol, we provide a test (mostly for unit testing) that offers a small overview on how each block operates and ensures that the code executes as expected. Each instance can be directly ran either by using an IDE (e.g., [IntelliJ IDEA](https://www.jetbrains.com/idea/)) or executing `go test`. #### Collective aggregation The collective aggregation protocol collectively aggregates the local results of a query from all the servers. It uses a tree structure aggregation: 1. the root sends down an aggregation trigger message; 2. the leafs respond with their local result; 3. parent nodes aggregate the information from their children; 4. these nodes forward the aggregation result up the tree. Input parameters: * `GroupedData : map[GroupingKey]FilteredResponse` - data to be collectively aggregated * `SimpleData : []CipherText` - data to be collectively aggregated (simpler format) * `Proofs : bool` - set to true in order to compute proofs and publish them You can run the protocol by filling either the `SimpleData` or `GroupedData` (**but not both**, otherwise the protocol will throw an error). Output parameters: * `FeedbackChannel : map[GroupingKey]FilteredResponse` - the list of collectively aggregated ciphertexts #### Deterministic tagging The distributed deterministic tagging protocol deterministically tags ciphertexts. In other words, the probabilistic ciphertexts are converted to a deterministic tag (identifier). To do this each cothority server (node) removes its secret contribution and homomorphically multiplies the ciphertexts with an ephemeral secret. This protocol operates in a circuit between the servers: the data is sent sequentially through this circuit and each server applies its transformation. Input parameters: * `TargetOfSwitch : []CipherText` - data to deterministically tag * `Proofs : bool` - set to true in order to compute proofs and publish them Output parameters: * `FeedbackChannel : []DeterministCipherText` - the list of deterministic ciphertexts (tags) #### Key switching The key switching protocol switches a ciphertext encrypted under a specific key to another ciphertext encrypted under another key. To do this each cothority server (node) removes its secret contribution and homomorphically adds the ciphertexts with a new secret contribution containing the new key. This protocol operates in a circuit between the servers: the data is sent sequentially through this circuit and each server applies its transformation. Input parameters: * `TargetOfSwitch : []CipherText` - data to key switch * `TargetPublicKey : kyber.Point` - public key to switch to * `Proofs : bool` - set to true in order to compute proofs and publish them Output parameters: * `FeedbackChannel : []CipherText` - the list of key switched ciphertexts #### Shuffling The shuffling protocol rerandomizes and shuffles a list of ciphertexts. This operates in a circuit between the servers: the data is sent sequentially through this circuit and each server applies its transformation. Input parameters: * `TargetOfShuffle : [][]CipherText` - data to shuffle * `Proofs : bool` - set to true in order to compute proofs and publish them Output parameters: * `FeedbackChannel : [][]CipherText` - the list of shuffled ciphertexts #### Distributed Results Obfuscation (DRO) The distruted results obfuscation is a special use of the shuffling protocol that is specially defined for adding random noise values and ensure differential privacy. The input and output are the same as the shuffling protocol. ### Services The UnLynx service works as described in this image : ![Unlynx service](https://s31.postimg.cc/bjxy3rqvv/Unlynx_service.png) The UnLynx service was built with the intention of supporting the sharing of sensitive data in a secure and private way. Our solution starts with a query sent to UnLynx and then broadcast to a number of different data providers. Each of these will respond with homomorphically encrypted data. This information will be encrypted under a collective key (collectively built by the conodes) and then shuffled, thus, preventing any entity from linking back the responses to their respective owners. UnLynx will deterministically compute tags on some of the response fields and then use them to aggregate the remaining sensitive data. The final results are sent back to the querier. This service comes with a set of test functions that offer the possibility to run this secure sharing tool under specific testing scenarios. These can be carried out either by using an IDE or executing `go test`. Check the service (`github.com/ldsec/unlynx/services/`) and the [paper](https://infoscience.epfl.ch/record/229308?ln=en) for more details. ### Simulations We can run UnLynx simulations in three different platforms: localhost (local machine), in [deterlab](https://www.isi.deterlab.net/index.php3) (a state-of-the-art scientific computing facility) and [ICCluster](http://install.iccluster.epfl.ch/Portal/) (an infrastructure that offers computing and storage services to EPFL researchers). Here we show how to run the simulations in your local machine. For each simulation we have to specify its configuration parameters using the correspondent *.toml* file. Check `github.com/ldsec/unlynx/simul/runfiles` for examples. > e.g., the file *shuffling.toml* allows the configuration of different simulation setting(s) for the shuffling protocol. If `TIME` is enabled you can check the time measurements for the computation by looking at the correspondent *.csv* file in `github.com/ldsec/unlynx/simul/test_data`. > e.g., the file *shuffling.csv* stores all the time measurements taken during the execution of a shuffling simulation. To ease out the task of parsing the time measurements you can simply run `github.com/ldsec/unlynx/simul/test_data/time_data/parse_time_data_test.go` after setting up the constants `filename_read`, `filename_write`, `filename_toml`. #### Localhost ```bash cd /ldsec/unlynx/simul go build ./simul runfiles/unlynx.toml ``` ### Applications Each application defines a set of APIs and deployment steps to install UnLynx in multiple conodes. This can either be done locally (for testing purposes), or **in any other set of machines**, if they are able to communicate among each other. **1.** Depending on the architecture of the machine compile the code accordingly for example check `ldsec/unlynx/cmd/unlynx/compileLinux.sh` or `ldsec/unlynx/cmd/unlynx/compileMac.sh` on how to do it. **2.** Copy the compiled executable and example data files (`ldsec/unlynx/data/unlynx_test_data.txt`) to each server > NOTE. To generate random data just have a look at: > > ``` > ldsec/unlynx/data/handle_data_test.go > ``` **3.** For each server run a "server setup" command and follow the installation guide ```bash ./unlynx server setup ``` **4.** Create in your client machine (the one that will act as your client) a `group.toml` file and append the content of all the `public.toml` files created during each setup command. **5.** Start each UnLynx conode ```bash ./unlynx server -c private.toml ``` **6.** Run a query, for example: ```bash ./unlynx -d 1 -f group.toml -s "{s0, s1}" -w "{w0, 1, w1, 1}" -p "(v0 == v1 && v2 == v3)" -g "{g0, g1, g2}" ``` What each flag stands for: * `-d` = debug level; * `-f` = group definition file; * `-s` = select attributes; * `-w` = where attributes + values; * `-p` = query predicate; * `-g` = group by attributes