README.md

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: [email protected])

• 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, on Github and on Youtube where I present it.
• Detailed report available on Github or on Dropbox

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/download/gmp/gmp-6.1.2.tar.bz2
       3. Extract it and go to its directory with tar -xvjf gmp-6.1.2.tar.bz2 && cd gmp-6.1.2
       4. Configure it with ./configure
       5. Build it with make
       6. Install it with make install
       7. Optionally, check it with make check
       8. Go back and remove used files with cd .. && rm -fr gmp-6.1.2*
       9. Download NTL with wget http://www.shoup.net/ntl/ntl-10.5.0.tar.gz
       10. Extract it and go to its directory with tar -xvzf ntl-10.5.0.tar.gz && cd ntl-10.5.0/src
       11. Configure it with ./configure NTL_GMP_LIP=on
       12. Build it with make
       13. Install it with make install
       14. Go back and remove used files with cd ../.. && rm -fr ntl-10.5.0*
       15. Clone HElib with with git clone https://github.com/shaih/HElib.git
       16. Go to its src directory cd HElib/src
       17. Build it with make
       18. Optionally, check it with make check and test it with make test.
       19. Go back to the working directory with cd ../..
4. Build hbc
   • With the Makefile provided (compatible will all platforms).
     1. Build it with make hbc
   • Manually
     1. Create the directory objects mkdir -p objects
     2. Compile the API g++ -c src/he.cpp -I HElib/src -o objects/he.o
     3. Compile the helper functions g++ -c src/helper_functions.cpp -o objects/helper_functions.o
     4. Compile the various tests
        • g++ -c src/TEST_GATES.cpp -I HElib/src -o objects/test_gates.o
        • g++ -c src/TEST_CIRC_COMB.cpp -I HElib/src -o objects/test_circ_comb.o
        • g++ -c src/TEST_CIRC_SEQ.cpp -I HElib/src -o objects/test_circ_seq.o
        • g++ -c src/TEST_CIRC_ARITHM.cpp -I HElib/src -o objects/test_circ_arithm.o
     5. Compile the main.cpp file g++ -c src/main.cpp -I HElib/src -o objects/main.o
     6. Compile the objects into hbc g++ objects/*.o HElib/src/fhe.a -o hbc -L/usr/local/lib -lntl -lgmp -lm
5. Run hbc
   • Run it with ./hbc (Careful about having enough RAM)
   • You can also build it and run the new build with make hbcNrun

3. RAM considerations IMPORTANT

• To run the default hbc program, you need at least 3GB of RAM.
• This is because the average operation (arithmetic tests) uses about 2GB of RAM for 2 bits.
• Note that you can comment it out in the main.cpp or TEST_ARITHMETIC.cpp and stick to tests of simpler circuits such as the multiplication which only require about 0.7 - 1GB of RAM.
• For Vagrant, you can modify the amount of RAM in the vb.memory field, which is set to 2600MB by default. To monitor the RAM usage, open a new host terminal, go to the working directory and use vagrant ssh -c htop.

4. CPU considerations for Vagrant

• By default, the Vagrant VM uses 2 cores of your CPU (vb.cpus = 2) so that you can run hbc and also monitor the RAM with another vagrant ssh.
• You can also run more instances of hbc if you have more than two cores available. With Vagrant, just set vb.cpus to 3 for example, log in with vagrant ssh on different host terminals and run hbc (provided you have enough RAM to run both obviously).

5. Remove and uninstall

5.1 Docker

In a terminal on your host machine, enter:

docker image rm qmcgaw/homomorphic-binary-circuits

Then delete the hbc repository on your host machine

5.1 With Vagrant

In a terminal on your host machine, enter:

vagrant destroy

Then delete the hbc repository on your host machine

5.2 Otherwise

Use the makefile and run make deepclean which uninstalls and delete:

• hbc
• src directory
• HElib, NTL, GMP Only the makefile will remain in the folder.

6. Acknowledgements

Credits to Shai Halevi for HElib obviously and thanks for the quick help tips in the Issues section!

Thanks to Dr. Wei Dai (Imperial College London) for introducing me to homomorphic encryption

Thanks to Christian Bodt (Coinplus) for teaching me the basics of cryptography and security, as well as useful coding skills.

Thanks to Alexandra Rouhana for her useful discussions that helped me figure out how to overcome some design restrictions.

Thanks to Wei Dai from the Vernam Group at Worcester Polytechnic Institute for keeping me updated with the status of CuHE.

Thanks to my dad, mother and step-mother for their continuous support throughout my studies.

7. Contribution

You're welcome to contribute to this repository if you find any better circuits or other circuits and implement them.

Just send me an email (see my address at the start) and I will add you as a contributor.

Please create an issue on the repository if you have an issue or question. Thanks !

8. Future Work (ideas crossing my mind)

• Use *= instead of multiplyBy when the level is very low as it is faster. multiplyBy uses relinearization which serves to reduce the size of ciphertexts. This is great for complex circuits but takes a longer time than *= for simple circuits.
• Add circuits from here to the core API he.cpp.
• Other ideas are in chapter 9: Future work of my report.