Skip to content

Latest commit

 

History

History
205 lines (127 loc) · 14.4 KB

README.md

File metadata and controls

205 lines (127 loc) · 14.4 KB
Raw

forthebadge contributions welcome

WELCOME to FANNG-MPC - a SCALE-MAMBA FORK made by TII.

  • Technology Innovation Institute Abu Dhabi* : TII
  • Framework for Artificial Neural Networks and General - MPC* : FANNG-MPC.

We focus on the usability/deployability aspects of legacy SCALE-MAMBA. The new additions target Mamba rather than the rust compiler. We dedicate time to implement missing functionality and new libraries to manage ML related operations.

Remember, this is a completely independent fork from version 1.13, If you want to revise the original documentation of SCALE-MAMBA, you can do so here.

Who do I talk to?

This is a Confidential Computing Team contribution, in affiliation with various institutions. But don't worry we show you some cool ways to contact us below:

Authors and Maintainers:

There is no I in team, there is an e, and an a, but no I. Regardless I digress, here are the names of all the peeps who made this possible (in alphabetic order):

  • Najwa Aaraj
  • Abdelrahaman Aly
  • Tim Güneysu
  • Chiara Marcolla
  • Johannes Mono
  • Jose Angel Nieda
  • Ivan Santos
  • Mireia Scholz
  • Eduardo Soria Vasquez
  • Victor Sucasas
  • Ajith Suresh

How to Contribute:

If you would like to contribute, which you are welcome to do so, please follow this simple rules:

  • Follow the coding style of the framework.
  • Include test files.
  • Be sure all tests available pass. They run in the same way they used to in SCALE-MAMBA.
  • Submit a PR, stating a Description, and what tests are concerned.

Report Issues

We appreciate your inputs. If you have find some issues and wish to report them, please don't forget the following:

  • Please Create a Github Issue/Jira ticket.
  • Add a description of the issue, including inputs and outputs and configuration (prime size, protocols, players and parameters if modified).
  • Include a code example of your issue. Be sure is reproducible.

If you want to have a chat or have questions, you can also find us on this Slack Channel. If you are ol'school and would like to mail us, you can do so at fanngs-mpc@tii.ae.

How to Cite it?

This work is under submission, until then we recommend you cite us as follows:

@misc{AAGMMPSSSSS23,
      author = {Najwa Aaraj and Abdelrahaman Aly and Tim Güneysu and Chiara Marcolla and Johannes Mono and Rogerio Paludo and Iván Santos-González and Mireia Scholz and Eduardo Soria-Vazquez and Victor Sucasas and Ajith Suresh},
      title = {FANNG-MPC: Framework for Artificial Neural Networks and Generic MPC},
      howpublished = {Cryptology ePrint Archive, Paper 2023/1918},
      year = {2023},
      note = {\url{https://eprint.iacr.org/2023/1918}},
      url = {https://eprint.iacr.org/2023/1918}
}

Besides what you can find above, the framework is complemented by following contributions:

If you are interested on only one of the aspects above, we do not mind you citing that work instead.

The How's (Before You Start):

We describe here the new functionality and behaviours. If you have questions about legacy code, you can check the SCALE-MAMBA official documentation.

On the How's we have included:

  • A new installation guide.
  • A script that automatize the installation. Just run installation/install-depedencies.sh and it will quickly install and set the project dependencies up.
    • You can then run tutorial using one of the Demo configurations from Auto-Test-Data
  • For an easy deployment, we have updated the shell.nix with our new dependencies.

We support DB's now. Hence, we have added a new configuration file to the Data folder: The Storage config file. We have added them to all the Auto-Test-Data example setups, persisting information on files.

Learn more about storage config files here.

Setting up your own MySQL

We use MySql as the default DB Engine. Our architecture is flexible enough to allow you incorporate different engines. They are used by the Input/Output database system and the Offline Garbling feature. At the moment however we only support MySql.

NOTE: There are different DB models for different target applications.

Learn how to set the databases up here.

The New Features (Release Notes):

This list includes some new features and solving some old problems:

Updated Input/output System

We have added file and DB support to the default I/O. In this library, the default Input/Output system is now input_output_db.cpp. This is thought for legacy users who are used to work with channels and would like to use DB's. Note that all our new functionalities manage DB's differently.

You can learn more about the new Input/Output features here.

Offline Garbling

We are able to support the production and persistence of Garbling Circuits. They can be produced in advance, stored, and used later. We have included 3 new cool instructions to achieve that, namely OGC, LOADGC and EGC.

You can learn more about Offline Garbling here.

Garbled Circuits Generation Script

To ease their use, we have also incorporated a new bash Script to generate and store Garbled circuits into our DB. It uses the instructions above. you can invoke the script via:

./Script/gc-gen.sh

Optimizations for Big Vectors

Old versions of SCALE-MAMBA, 1.14 and below, cannot handle opening vectors above approx 100K items. Hence, we have included a connection pool and 2 new instructions, that act like the old POpen_Start and POpen_Stop. We call them POpen_Start_Batched and POpen_Stop_Batched .

You can learn more about how to work with huge vectors POpen_Start and POpen_Stop workaround here.

Streamlined Memory Management

Ever noticed your SCALE-MAMBA programs gobbling up more memory than they should? Well, in versions 1.14 and below, this is a common hiccup. The culprit? Misjudged register sizes. To fix this, we modify the compile-mamba.py script to correct overblown register allocations.

You can learn more about the modification we made to compile-mamba.py here.

Parallel Truncation (Vectorized)

Adding a connection pool has also allowed us to implement a vectorized version of the truncation method. One of the biggest bottlenecks in ML implementations. This accelerates compilation and execution times in a way that was simply not possible before. You can find the new truncation methods in the AdvInteger.py library. The method call is the following:

  • TruncPr_parallel(a, k, m, kappa=40): work in the same as legacy TruncPR except that a is a vectorized sint.
  • TruncPr_exp_parallel(a, k, m, exp_r_dprime, exp_r_prime, kappa=40): Slightly optimized version of the method above. In case you have several invocations of the parallel truncation, you can use this method and send the expansion vectors for r_dprime and r_prime. Note that TruncPr_parallel recalculates these values at every call.

NOTE: If you want to to learn how to mix vectorized truncations with comparisons, let's say, for ReLUs.. You can check out our relu_lib documentation. These vectorizations are specially helpful when compilation optimizations are not possible.

Mixed Circuit for ReLUs

You can implement comparison methods using mixed circuits (arithmetic and boolean). In our case, we have implemented the constant round mechanisms (FT Setups) from Through the Looking GLass.

64 bit circuits for ReLUs

As part of the support for mixed circuit ReLUs, we include new 64 bit circuits for comparisons, inspired by Rabbit and Through the Looking Glass.

NOTE: If wishing to recompile the basic 64 bit circuits then follow the old instructions from SCALE-MAMBA.

We are using a specialized circuit, compiled for Less Than Equal in 2 versions:

  • Circuits.ONLY_ANDS Yosys generated circuit only using HW optimizations ref: 66001.

  • Circuits.ANDS_XORS To be done. Yosys generated circuit including Xors ref: 66002.

We are currently working with HW Researchers on a joint paper about how to mix Yosys and GC's. STAY TUNED!

You can learn more about our ReLUs here.

Means to Load Preprocessed Materials From DBs

RAM Memory has its limitations, but here's the good part: parties can actually pre-compute the stuff they need and save it in their own DB. And guess what? It's totally safe to do so! This approach allows parties to load only the specific material they need into the RAM, resulting in improved performance.

Now, we've made it easy for you by providing a method to do this for various tasks, such as matrix triples and bounded randomness. We've even come up with a new set of instructions for it. The best part is, it's super user-friendly and uses a novel and unified way to utilize DBs within the framework. So, you can have your cake and eat it too – optimizing your performance without much hassle!

You can learn more about our feature to load preprocessed materials here.

Do not forget, Trusted Dealers are not real, no matter what people say.

Conversion of Preprocessed Materials in the Dealer Model

We have enhanced SCALE-MAMBA by separating pre-processing from the online phase and introducing a dealer model. The challenge now is utilizing these preprocessed materials provided by different dealers. To address this, we have designed a converter module to streamline the transition. Essentially, this module converts preprocessed materials from one format used by the dealers to another format suitable for online evaluation with a different set of parties.

Given its broader application, we have decided to host the converter module in a separate repository. You can find it here.

A New Graph Theory Library

As a little extra, we have also implemented some graph theory protocols. Namely the State of the Art of Single Source Shortest Path Exploration for MPC. This is based on the work by Aly and Cleemput.

You can learn more about them here.

NOTE: If it's in the Compiler folder and has lib as its suffix, it's new!

A Library for ML blocks -> convolutions and fully connected layers

We have put together a new library with ML functionalities to deploy convolutional layers and fully connected layers. The library also contains several functionalities to manipulate matrixes.

Additionally, we included two new bytecodes in SCALE to perform array summation in register values.

All functions are described here.

A Library for ML blocks -> folding layers, input/batch processing, and output layers

This library contains new ML functionalities to implement: i) folding layers (i.e. pooling); ii) batch normalization; iii) input normalization & standardization; iv) and some output layers such as softmax.

All functions are described here.

How can you build your own Private Neural Network?

Here we explain how to construct an oblivious neural network using the libraries detailed above. Specifically, it explains how to construct a CNN to classify CIFAR-10 data. The CNN architecture is included in a diagram, and PyTorch code is included in the repository here, and the private version is included here.

If you need guidance on generating the required input and output files, along with the essential parameters, using the pytorch Pruned Resnet implementation, as well as compiling and running the FANNG-MPC oblivious-CIFAR10 test program, you can refer to this step-by-step guide.

There is a smaller CNN for MNIST also implemented privately in the previous repo, and the Pytorch code for that one is here.

Note that our implementation uses all the functionalities explained above: I) ReLUs, ii) linear transformations; iii) folding layers; iv) new I/O functions with MySQL connection. However, for triple generation we use fake ones (i.e. secret shares of zero matrixes).

Note that the quantity of RAM required for compilation and execution of this network is not available in a normal personal computer. If you want to try in your own laptop, we recommend deploying the network for MNIST instead. If you need guidance on generating the required input and output files, along with the essential parameters, using the pytorch LeNet implementation, as well as compiling and running the FANNG-MPC oblivious-LeNet test program, you can refer to this step-by-step guide.