Mainzelliste SecureEpiLinker (MainSEL)
Privacy-Preserving Record Linkage using Secure Multi-Party Computation and the EpiLink algorithm. This is the repository of the ABY sMCP Node: SecureEpilinker. The SEL extended Mainzelliste is available at https://github.com/medicalinformatics/MainzellisteSEL.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
What you need to build and install.
git cmake (>= 3.10) c++ 17 compatible compiler (gcc >= 8, Ubuntu: g++-8) boost development headers (for restbed) (Ubuntu: libboost-dev) libcurl (Ubuntu: libcurl4-openssl-dev) openssl (Ubuntu: libssl-dev) gmp (Ubuntu: libgmp-dev)
Note that on Arch Linux based systems,
openssl is not shipped with static
libraries, so unfortunately the
openssl version included in
restbed needs to
be cloned and built or another custom
openssl with static libraries needs to be
To clone this repository and the necessary submodules, run
git clone https://github.com/medicalinformatics/SecureEpilinker.git cd SecureEpilinker scripts/init_submodules.sh
Depending on your internet connection this may take some time. Note that the
minimal amount of submodules is cloned and shallow cloning is applied where
possible. You may also clone with
--recurse-submodules but this will clone
more submodules than necessary.
OpenSSL (only on Arch)
As mentioned above, on Arch you may need to manually compile (static) openssl libs:
cd extern/restbed/dependency git submodule update --init openssl cd openssl ./config && make -j$(nproc)
Build it via cmake from the repo top-level directory with
mkdir build cd build cmake .. make -j$(nproc) sel
Omit or customize
-j if you don't want to build in parallel with the maximum
amount of threads available on your system.
The default server configuration logs to
../log/, so create that directory in the
repository's top level folder if running from
build/. To start the Secure
Epilinker with https enabled and log level debug, run
# current directory is build/ mkdir ../log ./sel -s -vv
To conclude all steps in one code block for convenience:
git clone https://github.com/medicalinformatics/SecureEpilinker.git cd SecureEpilinker scripts/init_submodules.sh # START optional on Arch or where static openssl is not available cd extern/restbed/dependency/openssl ./config && make -j$(nproc) cd ../../../.. # END mkdir build log; cd build cmake .. && make -j$(nproc) sel ./sel -s -vv
Keys and Certificates
To run the service in https mode with self-created keys and self-signed
certificates, generate those with
Test build targets for different components exist:
test_selto build and run the SEL circuit tests
test_abyto build and run ABY tests
test_utilto test utility functions
To run the SEL circuit tests, the
test_sel binary needs to be build and
started in two separate terminals, each representing one of two sMPC nodes. An
example of a simple invocation is as follows:
cd build make -j $(nproc) test_sel # Terminal Alice (server) ./test_sel -r 0 -v # Terminal Bob (client) ./test_sel -r 1 -v
Alternatively, using the tmuxp utility, both sessions can be started in a tmux session by invoking
cd build tmuxp load ../test/test_sel.tmuxp.yaml
This will run the benchmarks and write them to a file. To show the results in
the terminal, use and change the invocation to
./test_sel -r $role -v. Use the
-h flag to see additional options.
The easiest way to build and deploy the Secure Epilinker is via Docker. There are two flavors, both being multi-stage Docker builds:
Dockerfile.ubuntu: Build and runtime image are the latest rolling Ubuntu release. This is good for debugging the runtime image as you have access to the basic tools included in
Dockerfile.distroless: uses gcr.io/distroless/cc as the base image for minimal size and exposure to security threats. It doesn't contain any binaries besides
sel, so in particular not even
/bin/sh. Note that currently the
cc:debugflavor is used as the runtime image for debugging purposes. Remove the
:debugtag in the Dockerfile if building for production.
To build the Docker container, clone the repo and its submodules as described above and run the Docker build:
git clone https://github.com/medicalinformatics/SecureEpilinker.git cd SecureEpilinker scripts/init_submodules.sh docker build -t sel:ubuntu -f Dockerfile.ubuntu .
When running the image, you need to forward the appropriate ports and configure the network to allow the image communication access to the local Mainzelliste and remote Secure Epilinker. Ignoring the network setup, run something similar to:
docker run -p 8161:8161 -p 1337-1344:1337-1344 sel:ubuntu -vv -s
This would expose
sel on its default port on the Docker host and enable
debug output logging and https.
Logs will be printed to standard output as well as be written to the
directory inside the Docker container.
- ABY - The multi party computation framework used
- Restbed - The REST Framework used
- libfmt - Used to format and print text
- nlohmann/json - The JSON library used
- valijson - JSON schema validation library
- cxxpts - Commandline option parser
- curlpp - HTTP communication
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
- Tobias Kussel - Main author/focus on REST stack - @tkussel
- Sebastian Stammler - Main author/focus on sMPC circuit - @sebastianst
- Phillipp Schoppmann - Initial docker build file - @schoppmp
This project is licensed under the AGPL License - see the LICENSE file for details