/ABY

ABY - A Framework for Efficient Mixed-protocol Secure Two-party Computation

Primary LanguageC++GNU Lesser General Public License v3.0LGPL-3.0

ABY Build Status

A Framework for Efficient Mixed-Protocol Secure Two-Party Computation

By Daniel Demmler, Thomas Schneider and Michael Zohner (ENCRYPTO, TU Darmstadt)
in Network and Distributed System Security Symposium (NDSS'15). Paper available here.

Table of Contents

Features

ABY efficiently combines secure computation schemes based on Arithmetic sharing, Boolean sharing, and Yao’s garbled circuits and makes available best-practice solutions in secure two-party computation. It allows to pre-compute almost all cryptographic operations and provides novel, highly efficient conversions between secure computation schemes based on pre-computed oblivious transfer extensions using our OT extension library available on GitHub. ABY supports several standard operations and provides example applications.

This code is provided as a experimental implementation for testing purposes and should not be used in a productive environment. We cannot guarantee security and correctness.

Requirements

  • A Linux distribution of your choice (ABY was developed and tested with recent versions of Debian and Ubuntu).

  • Required packages for ABY:

    Install these packages with your favorite package manager, e.g, sudo apt-get install <package-name>.

  • Optional packages: doxygen and graphviz to create your own Doxygen documentation of the code.

ABY Source Code

Repository Structure

  • bin/circ/ - Circuits in the ABY format.
  • cmake/ - CMake helper files.
  • extern/ - External dependencies as Git submodules.
  • src/ - Source code.
  • src/abycore/ - Source of the internal ABY functions.
  • src/examples/ - Example applications. Each application has a /common directory that holds the functionality (circuit). The idea is to re-use this circuit even outside of the application. The application's root directory contains a .cpp file with a main method that runs the circuit and is used to verify correctness.
  • src/test/ - Currently one application to test internal ABY functions as well as example applications and print debug information.

Building the ABY Framework

Short Version

  1. Clone the ABY git repository by running:

    git clone https://github.com/encryptogroup/ABY.git

  2. Enter the Framework directory: cd ABY/

  3. Create and enter the build directory: mkdir build && cd build

  4. Use CMake configure the build:

    cmake ..

    This also initializes and updates the Git submodules of the dependencies located in extern/. If you plan to work without a network connection, you should to a --recursive clone in Step 1.

  5. Call make in the build directory. You can find the build executables and libraries in the directories bin/ and lib/, respectively.

Detailed Guide
External Dependencies

ABY depends on the OTExtension and ENCRYPTO_utils libraries, which are referenced using the Git submodules in the extern/ directory. During configure phase of the build (calling cmake ..) CMake searches your system for these libraries.

  • If they are already installed at a standard location, e.g., at /usr or /usr/local, CMake should find these automatically.
  • In case they are installed at a nonstandard location, e.g., at ~/some/path/, you can point CMake to their location via the CMAKE_PREFIX_PATH option: 
    cmake .. -DCMAKE_PREFIX_PATH=~/some/path/
  • Otherwise, CMake updates and initializes the Git submodules in extern/ (if not already done), and the missing dependencies are built together with ABY. If you want to do this without a network connection, consider to clone the repository recursively.
Test Executables and Example Applications

To build the ABY test and benchmark executables as well as the bundled example applications, you use the ABY_BUILD_EXE option:

cmake .. -DABY_BUILD_EXE=On
Build Options

You can choose the build type, e.g. Release or Debug using CMAKE_BUILD_TYPE:

cmake .. -DCMAKE_BUILD_TYPE=Release
# or
cmake .. -DCMAKE_BUILD_TYPE=Debug

Release will enable optimizations whereas Debug includes debug symbols.

To choose a different compiler, use the CXX environment variable:

CXX=/usr/bin/clang++ cmake ..
Cleaning the Build Directory

Executing make clean in the build directory removes all build artifacts. This includes built dependencies and examples. To clean only parts of the build, either invoke make clean in the specific subdirectory or use make -C:

  • make clean - clean everything
  • make -C src/abycore clean - clean only the ABY library
  • make -C src/examples clean - clean only the examples
  • make -C src/test clean - clean only the test application
  • make -C extern clean - clean only the built dependencies
Installation

In case you plan to use ABY for your own application, you might want to install the ABY library to some place, for example system-wide (e.g. at /usr/local) or somewhere in your workspace (e.g. /path/to/aby). There are two relevant options:

  • CMAKE_INSTALL_PREFIX defaults to /usr/local and is preprended by CMake to all installation paths (e.g. lib/ and include/ for library and header files, respectively, become /usr/local/lib and usr/local/include). CMake will also look for dependencies at this location.
  • DESTDIR is used by the Makefile to install to a nonstandard location.

Example: If you want to install ABY to ~/path/to/aby/prefix/{include,lib} you can use:

cmake .. -DCMAKE_INSTALL_PREFIX=""
make
make DESTDIR=~/path/to/aby/prefix install

or

cmake .. -DCMAKE_INSTALL_PREFIX=~/path/to/aby/prefix
make
make install

Developer Guide and Documentation

We provide an extensive developer guide with many examples and explanations of how to use ABY.

Also, see the online doxygen documentation of ABY for further information and comments on the code.

ABY Applications

Included Example Applications

  • The Millionaire's Problem was proposed by Yao in 1982. Two parties want to find out who is richer, without revealing their actual wealth. This simple example can be used as starting point for your own ABY application.
  • Secure computation AES, where one party inputs the key and the other party inputs a message to collaboratively encrypt.
  • The Euclidean Distance for two 2-dimensional coordinates.
  • The Minimum Euclidean Distance for finding the closest match between one d-dimensional element and a database of n d-dimensional elements.
  • The Arithmetic Inner Product that multiplies N values component-wise and then adds all multiplication results (modulo 16 Bit in this case).
  • Secure Hash Function Evaluation SHA1, where both parties concatenate their 256-bit inputs to a 512-bit message which is collaboratively hashed using SHA1.
  • The LowMC block cipher family LowMC, which is a block cipher family with a low number of AND gates and a low AND depth. In the example, one party inputs the key and the other party inputs a message to collaboratively encrypt.
  • Further example applications will be added soon.

Running Applications

  • Make sure you have build ABY as described above and set the -DABY_BUILD_EXE=On option and the application's binary was created in bin/ inside the build directory.
  • To locally execute an application, run the created executable from two different terminals and pass all required parameters accordingly.
  • By default applications are tested locally (via sockets on localhost). You can run them on two different machines by specifying IP addresses and ports as parameters.
  • Example: The Millionaire's problem requires to specify the role of the executing party. All other parameters will use default values if they are not set. You execute it locally with: ./millionaire_prob_test -r 0 and ./millionaire_prob_test -r 1, each in a separate terminal.
  • You should get some debug output for you to verify the correctness of the computation.
  • Performance statistics can be turned on setting #define PRINT_PERFORMANCE_STATS 1 in src/abycore/ABY_utils/ABYconstants.h in line 33.

Creating and Building your own ABY Application

  • To get an idea how to create a simple ABY application, you can follow the comments in the Millionaire's Problem example.

  • If you are using CMake, install ABY somewhere it can be found and use find_package(ABY) or add the ABY repository as subdirectory via add_subdirectory(path/to/ABY), e.g.

     find_package(ABY QUIET)
 if(ABY_FOUND)
 	message(STATUS "Found ABY")
 elseif (NOT ABY_FOUND AND NOT TARGET ABY::aby)
 	message("ABY was not found: add ABY subdirectory")
 	add_subdirectory(extern/ABY)
 endif()

    Then define your executable and link it to the ABY::aby target:

     add_executable(my_application my_application.cpp)
 target_link_libraries(my_application ABY::aby)

  • Otherwise, setup the include path such that the headers of ABY and its dependencies can be found and link your application to the libaby.a library and the other dependencies (see above).