{"id":13830942,"url":"https://github.com/qdm12/hbc","last_synced_at":"2025-07-09T13:30:58.811Z","repository":{"id":108549060,"uuid":"48249304","full_name":"qdm12/hbc","owner":"qdm12","description":"API of homomorphic binary operations such as binary comparisons or binary divisions using the library HElib","archived":true,"fork":false,"pushed_at":"2021-12-14T22:20:09.000Z","size":3734,"stargazers_count":28,"open_issues_count":2,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-08-05T10:15:04.706Z","etag":null,"topics":["circuit","cryptography","digital-circuits","helib","homomorphic-encryption","vagrant","virtual-machine"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qdm12.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-12-18T18:07:36.000Z","updated_at":"2024-08-03T23:02:39.000Z","dependencies_parsed_at":"2023-04-15T21:01:04.950Z","dependency_job_id":null,"html_url":"https://github.com/qdm12/hbc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdm12%2Fhbc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdm12%2Fhbc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdm12%2Fhbc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdm12%2Fhbc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qdm12","download_url":"https://codeload.github.com/qdm12/hbc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225553262,"owners_count":17487293,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["circuit","cryptography","digital-circuits","helib","homomorphic-encryption","vagrant","virtual-machine"],"created_at":"2024-08-04T10:01:13.150Z","updated_at":"2024-11-20T12:30:47.683Z","avatar_url":"https://github.com/qdm12.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# Homomorphic binary circuits - *hbc*\n\n**API** of homomorphic binary operations such as binary comparison or binary Euclidian division using the library [*HElib*](https://github.com/shaih/HElib)\n\n*Still maintained (April 2018) by Quentin McGaw (email: quentin.mcgaw@gmail.com)*\n\n[![Build Status](https://travis-ci.org/qdm12/hbc.svg?branch=master)](https://travis-ci.org/qdm12/hbc)\n\n[![GitHub last commit](https://img.shields.io/github/last-commit/qdm12/hbc.svg)](https://github.com/qdm12/hbc/issues)\n[![GitHub commit activity](https://img.shields.io/github/commit-activity/y/qdm12/hbc.svg)](https://github.com/qdm12/hbc/issues)\n[![GitHub issues](https://img.shields.io/github/issues/qdm12/hbc.svg)](https://github.com/qdm12/hbc/issues)\n\n[![Docker Build Status](https://img.shields.io/docker/build/qmcgaw/homomorphic-binary-circuits.svg)](https://hub.docker.com/r/qmcgaw/homomorphic-binary-circuits)\n[![Docker Pulls](https://img.shields.io/docker/pulls/qmcgaw/homomorphic-binary-circuits.svg)](https://hub.docker.com/r/qmcgaw/homomorphic-binary-circuits)\n[![Docker Stars](https://img.shields.io/docker/stars/qmcgaw/homomorphic-binary-circuits.svg)](https://hub.docker.com/r/qmcgaw/homomorphic-binary-circuits)\n[![Docker Automated](https://img.shields.io/docker/automated/qmcgaw/homomorphic-binary-circuits.svg)](https://hub.docker.com/r/qmcgaw/homomorphic-binary-circuits)\n[![](https://images.microbadger.com/badges/image/qmcgaw/homomorphic-binary-circuits.svg)](https://microbadger.com/images/qmcgaw/homomorphic-binary-circuits)\n[![](https://images.microbadger.com/badges/version/qmcgaw/homomorphic-binary-circuits.svg)](https://microbadger.com/images/qmcgaw/homomorphic-binary-circuits)\n\n- Written in C++\n- Cross-platform using either:\n\t- Docker (see [Dockerfile](https://github.com/qdm12/hbc/blob/master/Dockerfile))\n\t- Vagrant (see [Vagrantfile](https://github.com/qdm12/hbc/blob/master/Vagrantfile))\n- API is in [*src/he.cpp*](https://github.com/qdm12/hbc/blob/master/src/he.cpp)\n- [*src/TEST_*](https://github.com/qdm12/hbc/tree/master/src) 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.\n- **makefile** to build *hbc* and/or setup almost everything for you (depending on your OS).\n- Powerpoint Presentation available on [Dropbox][dropbox_pres], on [Github][github_pres] and on [Youtube](https://www.youtube.com/watch?v=n-adgQWZYxI) where I present it.\n- Detailed report available on [Github][github_report] or on [Dropbox][dropbox_report]\n\n*This project was developed as my Master thesis at Imperial College London.*\n\nThis 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. \n\n## 1. Your own code\n\n- By default, [*src/main.cpp*](https://github.com/qdm12/hbc/blob/master/src/main.cpp) runs all the unit tests of the project\n- Change main.cpp with your code by inspiring from the tests [*src/TEST_*](https://github.com/qdm12/hbc/tree/master/src)\n- You can also add circuits in [*src/he.cpp*](https://github.com/qdm12/hbc/blob/master/src/he.cpp) and then add corresponding tests, and **tell me** if you want to contribute !\n- Refer to the [Running it section](#running-it)\n\n## 2. Running it\n\n### 2.1. Docker (easiest)\n\n[![Docker](https://github.com/qdm12/hbc/raw/master/readme/docker.png)](https://hub.docker.com/r/qmcgaw/homomorphic-binary-circuits/)\n\nRequirements:\n- A Linux based machine, MacOS or Windows Enterprise\n- At least 3GB of RAM\n- An internet connection\n\n1. Install Docker (from [here](https://www.docker.com/community-edition))\n1. Place the **makefile** and the **src** directory from the hbc repository (or the whole repo) in `/yourpath` in example\n1. Enter the following command in your terminal:\n\n\t```bash\n\tdocker run -it --rm -v /yoursrcpath:/hbc qmcgaw/homomorphic-binary-circuits\n\t```\n\t\n\tThis downloads the Docker image (the first time), mount the makefile and source files in the Docker container,\n\tcompile your source code and run the compiled program. You can stop the execution with CTRL+C.\n\t\n1. Edit the makefile and/or source files on your host machine\n1. Enter `make` in the Docker container to re-build the binary hbc\n1. Run the executable in the Docker container with `./hbc` or even on your host\n1. To quit the Docker container and delete it, simply enter `exit`\n\n### 2.2. Vagrant\n\n![Docker](https://github.com/qdm12/hbc/raw/master/readme/vagrant.png)\n\nRequirements:\n- At least 3GB of RAM\n- An internet connection\n\n1. Install [Git](https://git-scm.com/downloads)\n1. **On Windows**, have an ssh client or add the **ssh.exe** of `C:\\Program Files\\Git\\usr\\bin` to your environment path\n1. Install [Virtual Box](https://www.virtualbox.org/wiki/Downloads)\n1. Install [Vagrant](https://www.vagrantup.com/downloads.html)\n1. In a terminal, enter\n\n\t```bash\n\tgit clone https://github.com/qdm12/hbc.git\n\t```\n\n1. Go to the hbc directory\n\n\t```bash\n\tcd hbc\n\t```\n\t\n1. Launch the virtual machine which will setup and build everything for you with\n\n\t```bash\n\tvagrant up\n\t```\n\t\n\tThis takes about 30 minutes the first time, depending on your connection speed and CPU.\n\t\n\tIt launches an Ubuntu virtual machine with only what is necessary for this project.\n\t\n\t**WARNING:** If you do not have hardware virtualization, you can still run it but you have to change *trusty64*\n\tto *trusty32* and *vb.cpus = 2* to *vb.cpus = 1*.\n\n1. Log in the virtual machine with\n\n\t```bash\n\tvagrant ssh\n\t```\n\n\tThe working directory *hbc* on your host machine is shared with the virtual machine at `/vagrant`\n\n1. In the virtual machine, enter\n\n\t```bash\n\tcd /vagrant\n\t```\n\n- You can modify the files on your host machine (Windows, MacOS etc.)\n- Changes you make are automatically reflected in the virtual machine\n- Compile hbc again with `make` in the virtual machine\n- Run hbc with ./hbc from the virtual machine or your host machine.\n- *You can use `make hbcNrun` to build and automatically run the main.cpp code*\n\nWhen you are done:\n- Enter `exit` in the virtual machine, bringing you back to your host machine.\n- Enter `vagrant halt` to shutdown the machine. Or enter `vagrant destroy` to delete the machine.\n\nTo log back in, enter `vagrant up` and it should take about 30 seconds (except if you destroy the machine)\n\n### 2.3. Manually\n\nRequirements:\n- At least 3GB of RAM\n- An internet connection\n\nFor your information, software dependencies:\n\n| Program or Library | Requirement 1 | Requirement 2 | Requirement 3 | Requirement 4 | Requirement 5 | Requirement 6 |\n| ------------------ | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- |\n| hbc                | g++           | make          | libboost      | c++11         | HElib         |\n| HElib              | g++           | make          | git           | NTL 10.5.0    | GMP 6.1.2     |\n| NTL 10.5.0         | g++           | make          | GMP 6.1.2     |\n| GMP 6.1.2          | g++           | make          | m4            | perl          |\n\n\n1. Make sure you have installed **make**\n1. Open a terminal as **root** or **administrator** ideally\n1. Setup the necessary libraries\n    - With the Makefile provided (only works for **Debian** and **Ubuntu**)\n        1. Note: *git, g++, m4, perl, gmp and ntl* will be installed automatically\n        1. Enter `make HElib` in a terminal in the *hbc* directory.\n    - Manually (if Docker, Vagrant and the Makefile are not good for you)\n        - Mac OSX\n            1. Install Xcode manually or with `xcode-select --install`\n            1. Install brew with `ruby -e \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)\"`\n            1. Install libraries with `brew install wget git g++ m4 perl libboost`\n            1. Download GMP with `curl https://gmplib.org/download/gmp/gmp-6.1.2.tar.bz2 \u003e gmp-6.1.2.tar.bz2`\n            1. Extract it and go to its directory with `tar -xvjf gmp-6.1.2.tar.bz2 \u0026\u0026 cd gmp-6.1.2`\n            1. Configure it with `./configure`\n            1. Build it with `make`\n            1. Install it with `make install`\n            1. *Optionally*, check it with `make check`\n            1. Go back and remove used files with `cd .. \u0026\u0026 rm -fr gmp-6.1.2*`\n            1. Download NTL with `curl http://www.shoup.net/ntl/ntl-10.5.0.tar.gz \u003e ntl-10.5.0.tar.gz`\n            1. Extract it and go to its directory with `tar -xvzf ntl-10.5.0.tar.gz \u0026\u0026 cd ntl-10.5.0/src`\n            1. Configure it with `./configure NTL_GMP_LIP=on`\n            1. Build it with `make`\n            1. Install it with `make install`\n            1. Go back and remove used files with `cd ../.. \u0026\u0026 rm -fr ntl-10.5.0*`\n            1. Clone HElib with with `git clone https://github.com/shaih/HElib.git`\n            1. Go to its src directory `cd HElib/src`\n            1. Build it with `make`\n            1. *Optionally*, check it with `make check`\n            1. Go back to the working directory with `cd ../..`\n        - Other Linux OSes\n            1. Install the libaries with (add `sudo` maybe) `apt-get install git g++ m4 perl libboost-all-dev`\n            1. Download GMP with `wget https://gmplib.org/download/gmp/gmp-6.1.2.tar.bz2`\n            1. Extract it and go to its directory with `tar -xvjf gmp-6.1.2.tar.bz2 \u0026\u0026 cd gmp-6.1.2`\n            1. Configure it with `./configure`\n            1. Build it with `make`\n            1. Install it with `make install`\n            1. *Optionally*, check it with `make check`\n            1. Go back and remove used files with `cd .. \u0026\u0026 rm -fr gmp-6.1.2*`\n            1. Download NTL with `wget http://www.shoup.net/ntl/ntl-10.5.0.tar.gz`\n            1. Extract it and go to its directory with `tar -xvzf ntl-10.5.0.tar.gz \u0026\u0026 cd ntl-10.5.0/src`\n            1. Configure it with `./configure NTL_GMP_LIP=on`\n            1. Build it with `make`\n            1. Install it with `make install`\n            1. Go back and remove used files with `cd ../.. \u0026\u0026 rm -fr ntl-10.5.0*`\n            1. Clone HElib with with `git clone https://github.com/shaih/HElib.git`\n            1. Go to its src directory `cd HElib/src`\n            1. Build it with `make`\n            1. *Optionally*, check it with `make check` and test it with `make test`.\n            1. Go back to the working directory with `cd ../..`\n4. Build hbc\n    - With the Makefile provided (compatible will **all** platforms).\n        1. Build it with `make hbc`\n    - Manually\n        1. Create the directory objects `mkdir -p objects`\n        1. Compile the API `g++ -c src/he.cpp -I HElib/src -o objects/he.o`\n        1. Compile the helper functions `g++ -c src/helper_functions.cpp -o objects/helper_functions.o`\n        1. Compile the various tests\n            - `g++ -c src/TEST_GATES.cpp -I HElib/src -o objects/test_gates.o`\n            - `g++ -c src/TEST_CIRC_COMB.cpp -I HElib/src -o objects/test_circ_comb.o`\n            - `g++ -c src/TEST_CIRC_SEQ.cpp -I HElib/src -o objects/test_circ_seq.o`\n            - `g++ -c src/TEST_CIRC_ARITHM.cpp -I HElib/src -o objects/test_circ_arithm.o`\n        1. Compile the main.cpp file `g++ -c src/main.cpp -I HElib/src -o objects/main.o`\n        1. Compile the objects into *hbc* `g++ objects/*.o HElib/src/fhe.a -o hbc -L/usr/local/lib -lntl -lgmp -lm`\n5. Run hbc\n    - Run it with `./hbc` (Careful about having enough **RAM**)\n    - You can also build it and run the new build with `make hbcNrun`\n\n\n## 3. RAM considerations IMPORTANT\n- To run the default hbc program, you need at least 3GB of RAM.\n- This is because the average operation (arithmetic tests) uses about 2GB of RAM for 2 bits.\n- Note that you can comment it out in the main.cpp or TEST_ARITHMETIC.cpp \n  and stick to tests of simpler circuits such as the multiplication which \n  only require about 0.7 - 1GB of RAM. \n- For **Vagrant**, you can modify the amount of RAM in the **vb.memory** field, \n  which is set to **2600MB** by default. To monitor the RAM usage, open a new \n  host terminal, go to the working directory and use `vagrant ssh -c htop`.\n\n\t  \n## 4. CPU considerations for Vagrant\n- By default, the Vagrant VM uses 2 cores of your CPU (vb.cpus = 2) so that\n  you can run hbc and also monitor the RAM with another `vagrant ssh`.\n- You can also run more instances of hbc if you have more than two cores available.\n  With Vagrant, just set vb.cpus to 3 for example, log in with `vagrant ssh` on different\n  host terminals and run hbc (provided you have enough RAM to run both obviously).\n\n## 5. Remove and uninstall\n\n### 5.1 Docker\n\nIn a terminal on your host machine, enter:\n\n```bash\ndocker image rm qmcgaw/homomorphic-binary-circuits\n```\n\nThen delete the hbc repository on your host machine\n\n### 5.1 With Vagrant\n\nIn a terminal on your host machine, enter:\n\n```bash\nvagrant destroy\n```\n\nThen delete the hbc repository on your host machine\n\n### 5.2 Otherwise\n\nUse the makefile and run `make deepclean` which uninstalls and delete:\n- hbc\n- src directory\n- HElib, NTL, GMP\nOnly the makefile will remain in the folder.\n\n\n## 6. Acknowledgements\n\nCredits to **Shai Halevi** for HElib obviously and thanks for the quick help tips in the Issues section!\n\nThanks to **Dr. Wei Dai** (Imperial College London) for introducing me to homomorphic encryption\n\nThanks to **Christian Bodt** (Coinplus) for teaching me the basics of cryptography and security, as well as useful coding skills.\n\nThanks to **Alexandra Rouhana** for her useful discussions that helped me figure out how to overcome some design restrictions.\n\nThanks to **Wei Dai** from the Vernam Group at Worcester Polytechnic Institute for keeping me updated with the status of CuHE. \n\nThanks to **my dad**, **mother** and **step-mother** for their continuous support throughout my studies.\n\n## 7. Contribution\n\nYou're welcome to contribute to this repository if you find any better circuits or other circuits and implement them.\n\nJust send me an email (see my address at the start) and I will add you as a contributor.\n\nPlease create an issue on the repository if you have an issue or question. Thanks !\n\n## 8. Future Work (ideas crossing my mind)\n\n- 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.\n- Add circuits from [here](http://www.aoki.ecei.tohoku.ac.jp/arith/mg/algorithm.html) to the core API *he.cpp*.\n- Other ideas are in chapter 9: _Future work_ of my report.\n\n[dependencies_jpg]: /docs/dependencies.jpg\n[dropbox_pres]: https://www.dropbox.com/s/scrwpum0avtqxuw/Presentation.pptx?dl=1\n[github_pres]: /docs/Homomorphic%20encryption%20Cryptography%20for%20cloud%20computing%20presentation.pptx\n[youtube_pres]: https://www.youtube.com/watch?v=n-adgQWZYxI\n[dropbox_report]: https://www.dropbox.com/s/rqnrslzb1pstkq0/FYP%20report%20-%20Homomorphic%20encryption%20Cryptography%20for%20cloud%20computing%20-%20Quentin%20McGaw%20qdm12%202016.pdf?dl=1\n[github_report]: /docs/Homomorphic%20encryption%20Cryptography%20for%20cloud%20computing%20report.pdf","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqdm12%2Fhbc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqdm12%2Fhbc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqdm12%2Fhbc/lists"}