Homomorphic binary circuits - hbc

API of homomorphic binary operations such as binary comparison or binary Euclidian division using the library HElib

Still maintained (April 2018) by Quentin McGaw (email: quentin.mcgaw@gmail.com)

• Written in C++
• Cross-platform using either:
  • Docker (see Dockerfile)
  • Vagrant (see Vagrantfile)
• API is in src/he.cpp
• src/TEST_ files are unit tests and timing tests for the homomorphic binary operations implemented in src/he.cpp. You should inspire for them to develop your own code.
• makefile to build hbc and/or setup almost everything for you (depending on your OS).
• Powerpoint Presentation available on [Dropbox][dropbox_pres], on [Github][github_pres] and on Youtube where I present it.
• Detailed report available on [Github][github_report] or on [Dropbox][dropbox_report]

This project was developed as my Master thesis at Imperial College London.

This project concerns the research and development of a real-use application of homomorphic encryption for cloud computing. The application takes advantage of the various possibilities and limitations of present homomorphic encryption schemes and programming libraries to remain usable in terms of time. The foundations of the application rely on the design of binary operations using homomorphic encryption. All the binary logic gates and various binary blocks were developed and adapted to provide enough functionalities to the application. The project focuses on providing features to cloud computing such as calculating averages on large amounts of encrypted numbers in a relatively short and decent time. The result is an application program interface written in C++ allowing to perform various operations on integers. It thus shows homomorphic encryption can be used today for simple operations if the security is more important than the speed of execution.

1. Your own code

• By default, src/main.cpp runs all the unit tests of the project
• Change main.cpp with your code by inspiring from the tests src/TEST_
• You can also add circuits in src/he.cpp and then add corresponding tests, and tell me if you want to contribute !
• Refer to the Running it section

2. Running it

2.1. Docker (easiest)

Requirements:

• A Linux based machine, MacOS or Windows Enterprise
• At least 3GB of RAM
• An internet connection

1. Install Docker (from here)

2. Place the makefile and the src directory from the hbc repository (or the whole repo) in /yourpath in example

3. Enter the following command in your terminal:

   docker run -it --rm -v /yoursrcpath:/hbc qmcgaw/homomorphic-binary-circuits
   

   This downloads the Docker image (the first time), mount the makefile and source files in the Docker container, compile your source code and run the compiled program. You can stop the execution with CTRL+C.

4. Edit the makefile and/or source files on your host machine

5. Enter make in the Docker container to re-build the binary hbc

6. Run the executable in the Docker container with ./hbc or even on your host

7. To quit the Docker container and delete it, simply enter exit

2.2. Vagrant

Requirements:

• At least 3GB of RAM
• An internet connection

1. Install Git

2. On Windows, have an ssh client or add the ssh.exe of C:\Program Files\Git\usr\bin to your environment path

3. Install Virtual Box

4. Install Vagrant

5. In a terminal, enter

   git clone https://github.com/qdm12/hbc.git
   

6. Go to the hbc directory

   cd hbc
   

7. Launch the virtual machine which will setup and build everything for you with

   vagrant up
   

   This takes about 30 minutes the first time, depending on your connection speed and CPU.

   It launches an Ubuntu virtual machine with only what is necessary for this project.

   WARNING: If you do not have hardware virtualization, you can still run it but you have to change trusty64 to trusty32 and vb.cpus = 2 to vb.cpus = 1.

8. Log in the virtual machine with

   vagrant ssh
   

   The working directory hbc on your host machine is shared with the virtual machine at /vagrant

9. In the virtual machine, enter

   cd /vagrant
   

• You can modify the files on your host machine (Windows, MacOS etc.)
• Changes you make are automatically reflected in the virtual machine
• Compile hbc again with make in the virtual machine
• Run hbc with ./hbc from the virtual machine or your host machine.
• You can use make hbcNrun to build and automatically run the main.cpp code

When you are done:

• Enter exit in the virtual machine, bringing you back to your host machine.
• Enter vagrant halt to shutdown the machine. Or enter vagrant destroy to delete the machine.

To log back in, enter vagrant up and it should take about 30 seconds (except if you destroy the machine)

2.3. Manually

Requirements:

• At least 3GB of RAM
• An internet connection

For your information, software dependencies:

| Program or Library | Requirement 1 | Requirement 2 | Requirement 3 | Requirement 4 | Requirement 5 | Requirement 6 | | ------------------ | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | | hbc | g++ | make | libboost | c++11 | HElib | | HElib | g++ | make | git | NTL 10.5.0 | GMP 6.1.2 | | NTL 10.5.0 | g++ | make | GMP 6.1.2 | | GMP 6.1.2 | g++ | make | m4 | perl |

1. Make sure you have installed make
2. Open a terminal as root or administrator ideally
3. Setup the necessary libraries
   • With the Makefile provided (only works for Debian and Ubuntu)
     1. Note: git, g++, m4, perl, gmp and ntl will be installed automatically
     2. Enter make HElib in a terminal in the hbc directory.
   • Manually (if Docker, Vagrant and the Makefile are not good for you)
     • Mac OSX
       1. Install Xcode manually or with xcode-select --install
       2. Install brew with ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
       3. Install libraries with brew install wget git g++ m4 perl libboost
       4. Download GMP with curl https://gmplib.org/download/gmp/gmp-6.1.2.tar.bz2 > gmp-6.1.2.tar.bz2
       5. Extract it and go to its directory with tar -xvjf gmp-6.1.2.tar.bz2 && cd gmp-6.1.2
       6. Configure it with ./configure
       7. Build it with make
       8. Install it with make install
       9. Optionally, check it with make check
       10. Go back and remove used files with cd .. && rm -fr gmp-6.1.2*
       11. Download NTL with curl http://www.shoup.net/ntl/ntl-10.5.0.tar.gz > ntl-10.5.0.tar.gz
       12. Extract it and go to its directory with tar -xvzf ntl-10.5.0.tar.gz && cd ntl-10.5.0/src
       13. Configure it with ./configure NTL_GMP_LIP=on
       14. Build it with make
       15. Install it with make install
       16. Go back and remove used files with cd ../.. && rm -fr ntl-10.5.0*
       17. Clone HElib with with git clone https://github.com/shaih/HElib.git
       18. Go to its src directory cd HElib/src
       19. Build it with make
       20. Optionally, check it with make check
       21. Go back to the working directory with cd ../..
     • Other Linux OSes
       1. Install the libaries with (add sudo maybe) apt-get install git g++ m4 perl libboost-all-dev
       2. Download GMP with `wget https://gmplib.org/dow